Decision records

ADR-0023: Remote administration over mutual TLS

• Status: Accepted (2026-10-06)

Context

Handoff §11: the admin API uses a Unix socket by default; remote administration only when explicitly enabled and strongly authenticated (mTLS). ADR-0017 delivered the socket.

Decision

• server.admin.remote: {address, cert, key, client_ca} — absent by default. All four fields are required; there is no password or token mode.
• TLS 1.3 only, ALPN http/1.1; WebPkiClientVerifier with the roots in client_ca: a connection without a client certificate chaining to that CA fails the handshake and never reaches the router. Refused handshakes are logged under scalws::audit.
• Authenticated connections get the same router and privileges as the Unix socket (views and mutations). Every mutation is audited with the client certificate subject and the peer address.
• scalwsctl --remote host:port --ca <server CA> --client-cert <pem> --client-key <pem>; every resolved address of host is tried.
• Changing admin.remote requires a restart (topology).

Consequences

• Operators manage a small private CA (issue/revoke by re-issuing the CA bundle; CRLs are not checked). Restrict address with a firewall as defence in depth.