TLS everywhere
Production-secure means TLS on every network surface. Each component of the framework has its own TLS configuration; this page is the catalog of where to enable it and what cert material each needs.
Cluster transport
Section titled “Cluster transport”import { TcpTransport, Cluster, ClusterOptions } from 'actor-ts/cluster';
const transport = new TcpTransport(self, log, { tls: { cert: fs.readFileSync('./tls/cluster.crt'), key: fs.readFileSync('./tls/cluster.key'), ca: fs.readFileSync('./tls/ca.crt'), rejectUnauthorized: true, },});
const clusterOptions = ClusterOptions.create() .withHost(host) .withPort(port) .withSeeds(seeds) .withTransport(transport);await Cluster.join(system, clusterOptions);Mutually-authenticated TLS between cluster nodes. See
cluster security
for the full discussion, and Client certificates
for the rule every listener’s ca is held to.
Every field here takes the certificate material, never a path to it — which is why the example reads the files itself. Nothing in the transport touches the filesystem, and none of Bun, Node or Deno accepts a filename in these fields.
cert and key are required together on a listener. A tls
object with only one of them used to make the listener conclude
“no TLS” and bind in plaintext, while still dialling out over
TLS — so the cluster formed and nothing looked wrong. That
combination is now refused at bind time, which also means a node
mis-configured this way stops silently downgrading and starts
failing loudly.
Don’t skip this — even on internal networks, defense in depth applies.
HTTP server
Section titled “HTTP server”TLS is a server option, so it reads the same on every backend — Fastify, Express and Hono — whichever one is mounted:
import { readFileSync } from 'node:fs';import { HttpExtensionId, HttpServerOptions } from 'actor-ts/http';
const serverOptions = HttpServerOptions.create() .withTls({ cert: readFileSync('./tls/http.crt'), key: readFileSync('./tls/http.key'), });
await system.extension(HttpExtensionId) .newServerAt('0.0.0.0', 8443) .withServerOptions(serverOptions) .bind(routes);From the config file the same fields are paths —
actor-ts.http.server.tls.cert-file, key-file and ca-file, read once at
bind(). Client certificates (requestClientCert) follow the rule under
Client certificates; HTTP/2 is withHttp2() on Fastify and
Hono, while Express serves TLS but refuses HTTP/2. The per-backend and
per-runtime details are under TLS and HTTP/2.
For HTTPS at the application layer. Often terminated at the load balancer instead — in K8s, the Service/Ingress handles TLS, the app speaks plain HTTP internally. Pick by your infrastructure shape.
The one place Fastify’s own https factory option still matters is a Fastify
backend you construct yourself: Fastify takes the certificate at construction,
so a hand-built instance needs it then. fastifyFactoryOptions(serverOptions)
builds that option — and http2 and the size caps — from the same server
options, so both layers agree; a hand-built Fastify without TLS that is handed
withTls(...) is refused at bind() rather than serving plain HTTP:
import { FastifyBackend, fastifyFactoryOptions } from 'actor-ts/http';
const backend = new FastifyBackend({ logger: false, ...fastifyFactoryOptions(serverOptions), // { https: { cert, key, … } }});
await system.extension(HttpExtensionId) .newServerAt('0.0.0.0', 8443) .useBackend(backend) .withServerOptions(serverOptions) .bind(routes);Client certificates
Section titled “Client certificates”Every listener that can demand a client certificate — the HTTP server on each backend, the cluster transport and the TCP listener — holds the demand to one rule, and refuses at bind whatever does not meet it:
- The certificate verifies against the
cayou configure. On the HTTP server the demand isrequestClientCert: true; on the cluster transport and the TCP listener acamakes it by default. A demand without acais refused. - A
cahas to hold a certificate. An empty or blank string, an empty byte array, an empty array,null, or aca-filenaming an empty file is refused, naming the field, whateverrequestClientCertsays. That is what a missing secret looks like by the time it arrives, not a request for one-way TLS —requestClientCert: falseis that, on every listener. - On Deno the demand is refused.
Deno.servehas no client-certificate option and Deno’snode:httpsacceptsrequestCertwithout enforcing it, so Hono, Fastify and Express all refuse it there;Deno.listenTlscannot request a certificate either, so neither can a cluster or TCP listener on Deno. On Node and Bun it is enforced.
const clientCertificateServerOptions = HttpServerOptions.create() .withTls({ cert: readFileSync('./tls/http.crt'), key: readFileSync('./tls/http.key'), ca: readFileSync('./tls/clients-ca.crt'), // the CA that signs your clients' certificates requestClientCert: true, });Management endpoint
Section titled “Management endpoint”import { readFileSync } from 'node:fs';import { HttpServerOptions } from 'actor-ts/http';import { managementRoutes } from 'actor-ts/management';
const routes = managementRoutes(system, cluster);
const managementServerOptions = HttpServerOptions.create() .withTls({ cert: readFileSync('./tls/mgmt.crt'), key: readFileSync('./tls/mgmt.key'), });await system.http(8558) .withServerOptions(managementServerOptions) .bind(routes);The same server options take a ca and requestClientCert: true when only
clients holding a certificate from your own CA may reach it. A Fastify
backend built by hand and handed over as the backend option takes the
certificate through fastifyFactoryOptions(managementServerOptions), as above.
The management server is internal-only by default — but TLS still helps:
- Protects against lateral movement inside a compromised network.
- Required by some compliance regimes regardless of network topology.
Broker actors
Section titled “Broker actors”Each broker actor takes TLS in two separate steps, and confusing them is the usual reason a connection that says TLS turns out not to verify what you meant:
- Turning TLS on is the URL scheme —
amqps://,mqtts://,rediss://,wss://— orwithSsl(true)on Kafka. The driver then verifies the broker against the system trust store, which is all a publicly-trusted certificate needs. - Supplying certificate material is
withTls({ … }): a private CA to trust, or a client certificate for mTLS. It configures the handshake rather than starting one, so keep the TLS scheme as well.
As on the cluster transport, every field carries the material
itself, never a path to it — which is why each example reads the
file. cert and key only mean anything together; supplying one
without the other is refused when the actor starts, rather than
throwing inside the handshake and being retried forever as a
connection failure.
None of this is readable from HOCON, deliberately: a private key does
not belong in a config file. withTls is code-only on every broker,
and Kafka’s ssl config leaf stays boolean-only.
Kafka has no URL scheme to carry TLS, so ssl does both jobs —
true for the system trust store, or the material itself:
const kafkaOptions = KafkaOptions.create() .withBrokers(['kafka-1:9093']) .withSsl({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), cert: fs.readFileSync('./tls/client.crt', 'utf8'), key: fs.readFileSync('./tls/client.key', 'utf8'), }) .withSasl({ mechanism: 'scram-sha-512', username: process.env.KAFKA_USER!, password: process.env.KAFKA_PASS!, });new KafkaActor(kafkaOptions);const mqttOptions = MqttOptions.create() .withBrokerUrl('mqtts://mqtt.example.com:8883') .withCredentials(process.env.MQTT_USER, process.env.MQTT_PASS) .withTls({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), });new MqttActor(mqttOptions);mqtts:// starts the handshake; withTls decides what it trusts.
Drop withTls and verification falls back to the mqtt package’s
defaults, which is the system trust store.
const amqpOptions = AmqpOptions.create() .withUrl('amqps://rabbitmq.example.com:5671') .withTls({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), });new AmqpActor(amqpOptions);amqps:// plus withTls, which reaches amqplib as its
socketOptions argument. AMQP URL query parameters carry
heartbeat, frameMax, channelMax and locale — never
certificate material, so there is no way to express this in the URL.
const natsOptions = NatsOptions.create() .withServers(['nats://nats.example.com:4222']) .withTls({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), cert: fs.readFileSync('./tls/client.crt', 'utf8'), key: fs.readFileSync('./tls/client.key', 'utf8'), });new NatsActor(natsOptions);mTLS via withTls — common for production NATS. NATS has no tls
URL scheme, so here withTls is also what asks the driver to
negotiate TLS at all. JetStreamActor takes the identical option.
Redis Streams
Section titled “Redis Streams”const redisStreamsOptions = RedisStreamsOptions.create() .withUrl('rediss://redis.example.com:6380') .withTls({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), });new RedisStreamsActor(redisStreamsOptions);rediss:// URL scheme (note the double-s). Both the producer and
the consumer client are built from the same material.
TCP listener
Section titled “TCP listener”The one broker actor on the inbound side. It takes the same
material as the cluster transport, and supplying ca turns on
client-certificate verification unless requestClientCert: false
says otherwise — under the rule in
Client certificates:
const tcpServerOptions = TcpServerOptions.create() .withBindPort(9500) .withTarget(handler) .withTls({ cert: fs.readFileSync('./tls/server.crt', 'utf8'), key: fs.readFileSync('./tls/server.key', 'utf8'), ca: fs.readFileSync('./tls/ca.crt', 'utf8'), });new TcpServerActor(tcpServerOptions);const grpcClientOptions = GrpcClientOptions.create() .withEndpoint('orders.example.com:50051') .withCredentials({ kind: 'tls', rootCerts: fs.readFileSync('./tls/ca.crt'), });new GrpcClientActor(grpcClientOptions);For mutual TLS, add cert + key.
WebSocket
Section titled “WebSocket”const webSocketClientOptions = WebsocketClientOptions.create().withUrl('wss://realtime.example.com/feed');new WebsocketClientActor(webSocketClientOptions);wss:// URL scheme. Cert verification follows the runtime’s
TLS defaults.
Default trust store only
Section titled “Default trust store only”Two client actors still take no certificate material, so they can reach a broker only when its certificate chains to a publicly trusted root:
WebsocketClientActor(above).TcpSocketActor— the outbound TCP client. Its listener siblingTcpServerActordoes take material; the dialling half does not.
Behind a private CA, that means terminating TLS at a proxy holding a
public certificate, or adding the CA to the host’s trust store. It
does not mean NODE_TLS_REJECT_UNAUTHORIZED=0, which disables
verification for every TLS connection the process makes — the cluster
transport and every HTTP client included.
Persistence backends
Section titled “Persistence backends”Three of these drivers read a verification switch out of the connection
string itself: node-postgres, node-mssql and the MongoDB driver. When that
string comes from HOCON — the url leaf of a plugin’s block — the framework
refuses one that switches verification off, with a ConfigError naming the
leaf and the switch (#1490). Only the configuration file is inspected: the
same string passed to withUrl(...) is your code’s decision, visible in
review, and goes to the driver untouched. About the file the refusal is
strict — a block’s url is refused even when code supplies its own
connection, and a ${?DATABASE_URL} substitution is refused like a written
url. It covers TLS that authenticates nobody, not plaintext:
sslmode=disable, Encrypt=false and tls=false stay allowed, since no
TLS is a different decision and reads as what it is. The sections below
name each driver’s switches.
SQLite
Section titled “SQLite”N/A — local-file access. TLS not applicable.PostgreSQL
Section titled “PostgreSQL”const postgresJournalOptions = PostgresJournalOptions.create() .withUrl(process.env.DATABASE_URL!) .withPoolConfig({ ssl: { rejectUnauthorized: true, ca: fs.readFileSync('./tls/rds-ca.pem') }, });new PostgresJournal(postgresJournalOptions);poolConfig is merged over { connectionString: url } and lands in
new pg.Pool(...) verbatim — nothing filters it, so ssl is exactly
what node-postgres hands to tls.connect. A managed instance
publishes its CA bundle; ca is where it goes. A connection string
can point at a root certificate too (sslrootcert=), but its
sslmode= values come from libpq — where require alone does not
verify the chain — and node-postgres has changed its reading of them
between releases, so the object form, which says exactly what is
verified, is the one to copy. The snapshot store and the durable-state
store take the same withPoolConfig.
From HOCON there are two routes to a private CA. In the connection
string, the one spelling that keeps its meaning across those releases is
verify-full, with sslrootcert= naming the CA file:
actor-ts.persistence.journal.postgres { url = "postgres://actor_ts@db.example.com:5432/app?sslmode=verify-full&sslrootcert=/etc/ssl/rds-ca.pem"}Or the block’s ca-file leaf names it, beside a url with no ssl
parameter at all (#1490). The framework reads the file when the pool
opens and hands it to node-postgres as ssl.ca; node’s TLS default then
verifies the chain and the name:
actor-ts.persistence.journal.postgres { url = "postgres://actor_ts@db.example.com:5432/app" ca-file = "/etc/ssl/rds-ca.pem"}One or the other, never both. node-postgres assigns the TLS settings it
parses out of the connection string over its config object — run against
pg 8.23, a CA given beside sslmode=verify-full was dropped and beside
sslmode=no-verify it came back with verification off — so the store
refuses ca-file beside any ssl parameter in the url, and in code a
poolConfig.ssl beside one, when it is built.
A url read from HOCON is refused when it carries sslmode=no-verify
or ssl=no-verify — the second is read by pg itself, after the
parser — or, under uselibpqcompat=true, which gives sslmode libpq’s
meanings, sslmode=prefer, require or verify-ca. Under those
meanings prefer, and require without sslrootcert, verify nothing;
verify-ca, and require with a root certificate, check the chain but
not the hostname, so a certificate the same authority issued for any
other host passes. Without uselibpqcompat, pg 8 still reads all three
as verify-full, so they are not refused; its parser warns that the
next major release will give them libpq’s meanings. One channel stays
outside the refusal: when neither the url, poolConfig nor ca-file
configures TLS, node-postgres falls back to the PGSSLMODE environment
variable, and no-verify there turns verification off without going
through HOCON at all.
MariaDB
Section titled “MariaDB”const mariaDbJournalOptions = MariaDbJournalOptions.create() .withPoolConfig({ host: 'db.example.com', port: 3306, database: 'app', user: 'actor_ts', password: process.env.MARIADB_PASSWORD, ssl: { rejectUnauthorized: true, ca: fs.readFileSync('./tls/rds-ca.pem') }, });new MariaDbJournal(mariaDbJournalOptions);The connector’s ssl takes Node’s own TLS options — the Postgres
shape verbatim — and poolConfig reaches mariadb.createPool(...)
untouched. Its connection string is the exception to the refusal
above, because there is nothing in it to refuse: the connector reads a
url’s ssl as a boolean (mariadb 3.5), and ssl=true verifies the
chain against the trust store. So a MariaDB url from HOCON is not
inspected — and cannot carry a CA either. From configuration a private
CA is named with the block’s ca-file leaf instead (#1490): the
framework reads the file when the pool opens and hands it to the
connector as ssl.ca, laid over the url parsed the way the connector
parses it, so host, database and options survive.
actor-ts.persistence.journal.mariadb { url = "mariadb://actor_ts@db.example.com:3306/app" ca-file = "/etc/ssl/rds-ca.pem"}It is refused beside a url ssl the connector reads as false — any value
but exactly true, so ssl=TRUE too — since that switches TLS off and
would leave the CA unused.
SQL Server
Section titled “SQL Server”const msSqlJournalOptions = MsSqlJournalOptions.create() .withPoolConfig({ server: 'db.example.com', database: 'app', user: 'actor_ts', password: process.env.MSSQL_PASSWORD, options: { encrypt: true, cryptoCredentialsDetails: { ca: fs.readFileSync('./tls/rds-ca.pem') }, serverName: 'db.example.com', }, });new MsSqlJournal(msSqlJournalOptions);mssql encrypts by default and verifies the server certificate. The
driver underneath, tedious, hands cryptoCredentialsDetails to
tls.createSecureContext, so ca is where a private CA goes, and
serverName is the name the certificate has to carry when it differs
from server. The driver’s alternative — telling it to trust the
server certificate, which a connection string spells
TrustServerCertificate= — is the switch the caution below marks
with a cross, under another name: tedious inverts it straight into
tls.connect’s rejectUnauthorized, so the link stays encrypted and
authenticates nobody. A connection string has no key for a CA at all,
so in code a private CA means poolConfig. The object reaches
new mssql.ConnectionPool(...) verbatim.
From HOCON that switch is refused. node-mssql reads every value of
TrustServerCertificate as true except false, no, 0 and an
empty one — yes, 1, {true} and even a quoted " false" all turn
verification off — so a url leaf whose connection string sets it to
anything else, in any letter case of the key, fails with a
ConfigError. The same holds for the switch in the query of an
mssql:// url, although node-mssql has parsed only the
Server=...;Database=... form since its 8.0 — and a store refuses such
a url anyway when it is built. With no key for a CA in the connection
string, a SQL Server behind a private CA is named beside it with the
block’s ca-file leaf (#1490): the framework reads the file when the
pool opens and hands it to tedious in cryptoCredentialsDetails.
actor-ts.persistence.journal.mssql { url = "Server=db.example.com;Database=app;User Id=actor_ts;Encrypt=true" ca-file = "/etc/ssl/rds-ca.pem"}It is refused beside an Encrypt node-mssql reads as false, which
switches TLS off, and beside a TrustServerCertificate it reads as true,
which switches verification off — either would leave the CA unused. One
whose certificate chains to a public root needs nothing but the default,
Encrypt=true.
Whichever of the three, the certificate never goes into configuration as
bytes. In code the material goes in the object, read from a file by your
code. From configuration it is a path: ca-file, which the framework
reads when the pool opens, or — for Postgres — the url’s sslrootcert,
which the driver reads. That is where the persistence stores differ
from the cluster transport and the brokers, whose TLS fields take the
material itself: a store is built from its own configuration block, and
a path there keeps the PEM out of the file without code to read it. And
the journal is the application’s system of record, so anything on the
path to it that can present its own certificate can rewrite history.
MongoDB
Section titled “MongoDB”const mongoJournalOptions = MongoJournalOptions.create().withUrl('mongodb://db.example.com:27017/app?tls=true&tlsCAFile=/etc/ssl/rds-ca.pem');new MongoJournal(mongoJournalOptions);The MongoDB driver takes its TLS settings from the connection string:
tls=true encrypts and verifies both the server’s certificate and its
hostname, and tlsCAFile names a private CA’s file, which the driver
reads itself when it connects. mongodb+srv:// turns TLS on by default.
From HOCON a private CA has two routes, as it has for Postgres. The
same url works there unchanged, or the block’s ca-file leaf names the
file (#1490): the framework reads it when the client opens and hands it
to the driver as ca, with tls switched on.
actor-ts.persistence.journal.mongodb { url = "mongodb://db.example.com:27017/app" ca-file = "/etc/ssl/rds-ca.pem"}One or the other, never both, and nothing beside it that sets the CA
aside. The store refuses ca-file when it is built, with an
OptionsError naming both sides, beside:
- a
tlsCAFilein the url or inclientOptions, or acainclientOptions— the driver readstlsCAFileonly when it was handed noca, so one of the two would be dropped; - a
tlsorsslset tofalsein either, which leaves the CA unused; - a
tlsInsecureortlsAllowInvalidCertificatesin either that switches certificate verification off, and arejectUnauthorizedoffalseinclientOptions, in any letter case of the key — the switchtlsInsecuresets, handed tonode:tlsas it stands; - a
secureContextinclientOptions, which brings a trust store of its own thatnode:tlsuses in place of the CA; - a pre-built
client, which was configured where it was built and never readsca-file— give that client its CA where you build it.
The driver’s three ways out of verification are tlsInsecure,
tlsAllowInvalidCertificates — both stop checking the certificate —
and tlsAllowInvalidHostnames, which keeps the chain and drops the
name. They are the switch the caution below marks with a cross, under
other names. A url read from HOCON that sets any of them to anything
but false, in any letter case of the key, is refused with a
ConfigError; set in code, with withUrl(...) or clientOptions,
they are not inspected unless ca-file is set beside them, when the
list above applies. tls=false is plaintext and stays allowed.
Cassandra
Section titled “Cassandra”const cassandraJournalOptions = CassandraJournalOptions.create() .withContactPoints(['cass-1.example.com:9042']) .withClient(clientWithMtls);new CassandraJournal(cassandraJournalOptions); // mTLS cert material (cert / key / ca) is configured on the // cassandra-driver client passed via withClient()Cassandra clusters typically run with mTLS in production.
Object storage
Section titled “Object storage”const s3ObjectStorageOptions = S3ObjectStorageOptions.create().withRegion('eu-west-1');const objectStorageDurableStateStoreOptions = ObjectStorageDurableStateStoreOptions.create().withBackend(new S3ObjectStorageBackend(s3ObjectStorageOptions));new ObjectStorageDurableStateStore(objectStorageDurableStateStoreOptions); // S3 uses HTTPS by defaultCloud object storage (S3, GCS, Azure Blob) always uses TLS. No configuration needed beyond pointing at the endpoint.
Cert provisioning
Section titled “Cert provisioning”Three patterns in K8s production:
cert-manager
Section titled “cert-manager”apiVersion: cert-manager.io/v1kind: Certificatemetadata: name: actor-ts-clusterspec: secretName: actor-ts-cluster-tls issuerRef: name: actor-ts-ca kind: ClusterIssuer commonName: actor-ts dnsNames: [actor-ts-cluster.svc] duration: 8760h renewBefore: 720hcert-manager auto-renews certs before expiry. Most production K8s setups use it.
Vault Agent
Section titled “Vault Agent”Vault Agent runs as a sidecar; pulls certs into the pod’s filesystem; renews automatically. Useful when you already have HashiCorp Vault.
Manual + scheduled rotation
Section titled “Manual + scheduled rotation”For non-K8s environments, scheduled cron jobs that pull fresh certs from an internal CA + restart the affected services. Works but requires careful operational discipline.
What about CA chain?
Section titled “What about CA chain?”ca: fs.readFileSync('./tls/ca.crt'),Most internal setups: one CA, signs all client + server certs. The cert verification needs the CA cert at both ends.
Cloud-managed certificates (Let’s Encrypt, AWS ACM): use
public CA bundles — already present in most runtimes. No
explicit ca needed.
Where to next
Section titled “Where to next”- Cluster security — the cluster-transport detail.
- Master key rotation — for data at rest.
- Kubernetes deployment — the K8s recipe + cert-manager integration.
- Operations overview — the production-security checklist.
