Skip to content

feat(gateway): mTLS client-certificate listener (Phase 1) - #2

Open
marcorivm wants to merge 1 commit into
open-edition/reconciledfrom
worktree-agent-abc6d62ceacdb6f8c
Open

feat(gateway): mTLS client-certificate listener (Phase 1)#2
marcorivm wants to merge 1 commit into
open-edition/reconciledfrom
worktree-agent-abc6d62ceacdb6f8c

Conversation

@marcorivm

Copy link
Copy Markdown
Member

Phase 1 of remote-gateway hardening — mTLS listener

Enables hosting the gateway on a different machine than the clients (Dokploy / Railway, where Tailscale can't run). First of a stacked series; later PRs add client-cert issuance (Phase 2), an onecli-gateway relay client (Phase 3), nanoclaw integration (Phase 4), and cert↔token binding enforcement (Phase 5).

What this PR does

  • Adds a second listener terminating mutual TLS, requiring a client certificate signed by a dedicated client CA — distinct from the MITM CA in ca.rs. After the handshake the stream is handed to the existing connection handler unchanged, so all CONNECT / MITM / Axum logic is reused.
  • Extracts the peer cert identity (URI-SAN preferred, else CN) into ProxyContext. Phase 1 logs it only — no enforcement against the agent token yet (Phase 5).
  • mTLS is off when GATEWAY_MTLS_PORT is unset — fully backward compatible; the plaintext listener behaves exactly as before.

Security properties

  • Fail-closed startup: a mis-configured mTLS request aborts main before DB/crypto init — never falls back to plaintext.
  • Client-cert verifier uses rustls' default deny anonymous policy (no allow_unauthenticated); rustls validates chain + expiry during the handshake.
  • GATEWAY_CLIENT_CA is rejected if its SPKI matches the host-resident MITM CA's public key — that key signs leaf certs on demand, so trusting it as a client anchor would let anyone mint their own client cert.
  • GATEWAY_PLAIN_BIND fails closed on an unparseable value (no silent 0.0.0.0); the accept loop retries transient errors so one listener can't cancel the other.
  • Identity strings are sanitized (control/quote/oversize dropped) before reaching tracing fields.

Env contract (all off unless GATEWAY_MTLS_PORT is set)

GATEWAY_MTLS_PORT, GATEWAY_TLS_CERT, GATEWAY_TLS_KEY, GATEWAY_CLIENT_CA (each path-or-inline PEM), GATEWAY_PLAIN_BIND (default 0.0.0.0).

Testing

  • OSS build clean; 578 tests pass (40 client_ca unit tests + an mTLS e2e through handle_connection); cargo clippy --all-targets -- -D warnings and cargo fmt --check clean.
  • Matrix: no cert / wrong CA / expired → rejected (asserting the specific rustls alert); valid → accepted + identity extracted (URI-SAN and CN); valid cert reaches /healthz 200 (proves no Phase-1 enforcement); hostile CN/SAN dropped; same-public-key-different-cert client CA → rejected; all from_parts fail-closed cases.

Notes for reviewers

  • cargo build --features cloud currently fails with 27 errors — pre-existing in the ee/*.rs stubs on this branch, reproduced on the base commit; none originate in this PR's code. Validated on OSS build only.
  • Deployment (Phase 4 doc): the mTLS port must be exposed as raw TCP passthrough; if Traefik/Railway terminates TLS in front of it, the gateway never sees the client cert.
  • Pipeline: Opus plan → Sonnet dev → Opus security review (fail-open hunt) → fixes → Sonnet QA → rebase onto this branch → focused Opus spot-check of the merged accept path.

https://claude.ai/code/session_01BgJuqEJqf7ZiUdqHWxi6bt

Add a second listener that terminates mutual TLS, requiring a client
certificate signed by a dedicated client CA (distinct from the MITM CA).
After the handshake the stream is handed to the existing connection
handler unchanged; the peer certificate's identity (URI-SAN preferred,
else CN) is extracted and threaded into ProxyContext. Phase 1 logs the
identity only — no enforcement against the agent token yet.

- New src/client_ca.rs: ClientIdentity, identity extraction with
  injection-safe sanitization, path-or-inline PEM loading, and
  MtlsConfig with fail-closed from_parts/from_env.
- Fail-closed startup: mis-configured mTLS aborts main before DB/crypto
  init; never falls back to plaintext.
- SECURITY: client-cert verifier uses the default deny anon policy (no
  allow_unauthenticated); GATEWAY_CLIENT_CA is rejected if its SPKI
  matches the host-resident MITM CA's public key.
- GATEWAY_PLAIN_BIND fails closed on an unparseable value; accept loop
  retries transient errors so one listener can't cancel the other.
- mTLS is off when GATEWAY_MTLS_PORT is unset (backward compatible).
- 40 client_ca tests + mTLS e2e through handle_connection; OSS build,
  clippy --all-targets -D warnings, and fmt all clean.

Claude-Session: https://claude.ai/code/session_01BgJuqEJqf7ZiUdqHWxi6bt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant