mTLS

mTLS gives rstream a certificate-backed authentication path for machines, services, devices, and published clients. The private key stays with the caller. rstream stores and authorizes the public certificate fingerprint through credentials, then applies the credential's permissions and Tunnel access rules at runtime.

mTLS is part of the Enterprise Edition runtime. Project plan gates are separate: agent mTLS authentication is available on every project plan, while mTLS for public traffic entering published tunnel endpoints is available on Pro and Enterprise projects.

Surfaces

The Control plane API is the hosted API used to manage accounts, workspaces, projects, credentials, billing, and token minting. It is authenticated with tokens.

The engine control channel is the runtime connection used by agents and SDK runtimes to create tunnels, open private or direct connections, and attach streams. It can authenticate a client with either a token or an mTLS client certificate.

The Engine HTTP API exposes HTTP endpoints such as live resource listing, SSE, and WebSocket watch streams. It currently accepts token authentication only. mTLS credentials do not authenticate Engine HTTP API requests.

Published Tunnel access is traffic entering a public tunnel URL or public socket. A tunnel can require mTLS for that public traffic when it enables mtls_auth.

Client certificate credentials

Create an mTLS Client Certificate (MTLS) credential from the Dashboard and paste the PEM-encoded client certificate. rstream stores the certificate SHA-256 fingerprint, not the certificate body or private key. The private key stays with the client that will authenticate.

A client certificate credential can carry Engine API permissions and Tunnel access grants. It does not carry Control plane API permissions. This keeps certificate-based runtime access separate from hosted account and workspace administration.

Certificate matching is exact, and a certificate fingerprint can be registered only once. If another user tries to register the same certificate, creation is rejected. Use a separate certificate and private key for each user, device, service, or principal so one private key cannot map to multiple identities.

Rotating the client certificate means creating a new credential for the replacement fingerprint, then moving the agent or client to the replacement certificate. rstream checks the certificate validity window when the credential is created and when the certificate is presented at runtime, so expired certificates and certificates that are not valid yet are rejected.

Generate a client certificate

For a local test or a first production rollout, generate one client key pair per agent, service, user, or device:

openssl genpkey \
  -algorithm EC \
  -pkeyopt ec_paramgen_curve:P-384 \
  -out rstream-client.key
 
chmod 600 rstream-client.key
 
openssl req \
  -new \
  -x509 \
  -key rstream-client.key \
  -sha384 \
  -days 397 \
  -subj "/CN=rstream-agent-prod-01" \
  -addext "keyUsage=digitalSignature" \
  -addext "extendedKeyUsage=clientAuth" \
  -out rstream-client.crt

-days 397 is a conservative rotation-friendly example, not a protocol limit. Use the lifetime that matches your operational policy, and rotate before the certificate expires. Longer lifetimes reduce operational churn but increase the blast radius of a leaked private key.

Paste the full contents of rstream-client.crt into the Dashboard when creating the mTLS Client Certificate (MTLS) credential:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Do not paste the private key into the Dashboard. Store rstream-client.key on the agent or client host and protect it as authentication material. The certificate may be self-signed because rstream authorizes the exact certificate fingerprint registered on the credential.

Agent authentication

Agents and SDK runtimes connecting to the engine control channel can authenticate with either a token or an mTLS client certificate. Supplying both on the same engine connection is rejected as ambiguous.

Use token authentication for the default CLI login flow, CI tokens, and application credentials. Use mTLS authentication when the agent identity should be bound to a private key managed outside the token store.

CLI contexts configure this under auth.mtls with either certificateFile / keyFile or inline certificate / key values. Stateless agents can set RSTREAM_MTLS_CERT_FILE and RSTREAM_MTLS_KEY_FILE. See Configuration File and Environment Variables for the exact shapes and precedence rules.

Direct and private tunnel dialing uses the authenticated engine session. It does not use published Tunnel access authentication because no public tunnel URL is involved.

Published Tunnel access

mtls_auth protects traffic that enters a published tunnel through its public endpoint. If it is enabled, the client reaching the published endpoint must present an allowed client certificate during the TLS handshake.

Published tunnel authentication methods are tunnel policy choices. A tunnel may enable more than one method, for example token authentication, rstream Auth, challenge mode, and mTLS, so different clients can use different authentication mechanisms.

The strict conflict rule applies to a single request or connection: mTLS must not be combined with HTTP-layer authentication proofs. A request with both a valid client certificate and a bearer token is rejected as ambiguous. A request with both a valid client certificate and an rstream Auth session cookie is rejected for the same reason. Token authentication and rstream Auth can still be enabled together on the tunnel; bearer token requests use the token path, and browser requests can use the rstream Auth path.

For HTTP tunnels, mTLS is checked before the request is forwarded upstream. For non-HTTP published tunnels where the edge terminates TLS, the certificate is checked during the client handshake. TLS passthrough is different: the edge does not terminate TLS, so client certificate validation belongs to the upstream service.

Engine HTTP API

The Engine HTTP API currently accepts token authentication only. Use scoped tokens for HTTP endpoints such as resource listing, SSE, and WebSocket watch streams. mTLS credentials are not presented or accepted on the browser-facing Engine HTTP API.

Published Tunnel access plan limits do not apply to agent authentication. They apply only to public traffic entering published tunnel URLs or public sockets.