TLS And mTLS

NOOSChain supports transport encryption for deployment-facing MVP networking. TLS/mTLS is layered under the existing signed node-auth headers; it does not replace signature checks.

Production mode (NODE_ENV=production) fails closed unless every configured NOOSChain network surface uses TLS. Development mode may run without TLS, but startup prints a console warning for each plaintext surface.

TypeScript Node HTTP TLS

NOOS_TLS_ENABLED=true
NOOS_TLS_CERT_PATH=dev-certs/node-a.crt
NOOS_TLS_KEY_PATH=dev-certs/node-a.key
NOOS_TLS_CA_PATH=dev-certs/ca.crt
NOOS_MTLS_REQUIRED=true
NOOS_TLS_REJECT_UNAUTHORIZED=true
NOOS_TLS_SERVER_NAME=localhost

When NOOS_TLS_ENABLED=true, Fastify starts HTTPS. When NOOS_MTLS_REQUIRED=true, clients must present a certificate signed by NOOS_TLS_CA_PATH.

In production, NOOS_TLS_ENABLED=true, NOOS_TLS_CERT_PATH, and NOOS_TLS_KEY_PATH are required. NOOS_TLS_REJECT_UNAUTHORIZED=false is refused in production.

Internal TypeScript clients used for sync, gossip, payload backfill, Raft HTTP transport, and HashiCorp Raft sidecar control calls use the same CA/client certificate settings for HTTPS URLs.

HashiCorp Raft Sidecar HTTP TLS

GO_RAFT_TLS_ENABLED=true
GO_RAFT_TLS_CERT_PATH=dev-certs/go-raft-a.crt
GO_RAFT_TLS_KEY_PATH=dev-certs/go-raft-a.key
GO_RAFT_TLS_CA_PATH=dev-certs/ca.crt
GO_RAFT_MTLS_REQUIRED=true

The HashiCorp Raft sidecar serves its HTTP control API over HTTPS when enabled and requires client certificates when mTLS is required. Committed callbacks back into TypeScript also use the configured CA/client certificate material.

In production, HashiCorp sidecar HTTP control/callback traffic requires GO_RAFT_TLS_ENABLED=true, certificate/key paths, and https:// values for HASHICORP_GO_RAFT_HTTP_BIND and HASHICORP_GO_RAFT_CALLBACK_BASE.

HashiCorp Raft TCP Transport TLS

The HashiCorp Raft sidecar has a separate TCP transport for Raft replication. That channel is independent from the sidecar HTTP control API.

GO_RAFT_TCP_TLS_ENABLED=true
GO_RAFT_TCP_TLS_CERT_PATH=dev-certs/go-raft-a.crt
GO_RAFT_TCP_TLS_KEY_PATH=dev-certs/go-raft-a.key
GO_RAFT_TCP_TLS_CA_PATH=dev-certs/ca.crt
GO_RAFT_TCP_MTLS_REQUIRED=true

When GO_RAFT_TCP_TLS_ENABLED=true, the Raft TCP listener and outbound Raft dialer use TLS. When GO_RAFT_TCP_MTLS_REQUIRED=true, inbound Raft TCP peers must present a certificate signed by GO_RAFT_TCP_TLS_CA_PATH, and outbound connections verify the remote certificate against that CA.

GO_RAFT_TCP_TLS_SERVER_NAME can pin a server name for outbound TLS verification. If it is omitted, the dialed host is used. The MVP verifies the certificate chain/SAN through TLS but does not yet map a Raft nodeId to a specific certificate identity.

In production, GO_RAFT_TCP_TLS_ENABLED=true, certificate/key paths, and a TCP TLS CA are required before the sidecar starts.

Dev Certificates

Generate local self-signed development certificates:

npm run dev:certs

Output goes to dev-certs/, which is ignored by git. The generated CA and node certificates are for local development only. The generated certificates include SANs for localhost, 127.0.0.1, node-a, node-b, node-c, go-raft-a, go-raft-b, and go-raft-c, so they can be used for TypeScript HTTPS, sidecar HTTP TLS, and sidecar Raft TCP TLS smoke tests.

Security Model

mTLS proves the peer holds a certificate trusted by the operator-configured CA. Signed node headers still prove the request was signed by the node identity registered in NOOSChain state. Both layers are checked on protected node-to-node routes.

Production deployments should use a real PKI or internal certificate authority, rotate certificates before expiry, and avoid logging certificate private keys. TLS errors fail closed.