Files
skyg-linux-tracker/plan/workstreams/WS-I-tls.md
T
ariandClaude Sonnet 5.5 c5972b762f WS-I: native TLS (optional, default off) with SIGHUP cert reload
server.tls.{enabled,cert_file,key_file}; rustls (ring, explicit provider) via
tokio-rustls + hyper-util; https:// MCP origins when enabled; non-loopback
plain-HTTP startup warning; tests/tls.rs; README TLS section.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-16 07:10:14 -04:00

3.9 KiB

WS-I — Native TLS

Field Value
Status Done on ws-i/tls (not merged)
Owner —
Phase 4 (single track, after P3, before WS-H)
Depends on P3
Blocks WS-H (the NixOS module exposes the TLS options)
Owned files src/tls.rs, src/server.rs (serve path only), src/config.rs (server.tls keys), config.example.toml (tls keys), Cargo.toml (tls deps, by agreed exception), tests/tls.rs, README.md (TLS section)

Goal

Serve REST and /mcp over HTTPS with certificates the operator provides, so bearer tokens are not readable on the LAN. No openssl.

Tasks

Tick these in TODO.md.

  • T1 Config: server.tls.enabled (default false), server.tls.cert_file, server.tls.key_file. Validation: enabled requires both paths, and both files must be readable at startup with a clear error. Document each key and its env var in config.example.toml.
  • T2 Serve over rustls. Pick the integration that keeps openssl out (axum-server with tls-rustls, or tokio-rustls with hyper-util). Pin the crypto provider so only one is linked. Cargo.toml change is a small separate commit.
  • T3 Reload certificate and key on SIGHUP without dropping connections. A bad new cert keeps the old one and logs an error.
  • T4 MCP allowlists: when TLS is on, allowed_origins default to https://…. allowed_hosts is unchanged.
  • T5 Startup warning when bind is non-loopback and TLS is off. Do not refuse.
  • T6 Tests: generate a self-signed cert in the test (dev-dependency such as rcgen). Cover HTTPS /healthz, 401 and 200 with a token over TLS, plain HTTP to the TLS port failing, SIGHUP reload serving the new cert, bad cert files failing startup, and graceful shutdown still within its bound.
  • T7 README TLS section, with a self-signed example and a note on ACME or sops certificate paths.
  • T8 Live check: curl --cacert against the running server, and one /mcp initialize over HTTPS.

Done when

  • server.tls.enabled = true serves HTTPS, and cargo tree -i openssl is still empty.
  • Replacing the cert files and sending SIGHUP changes the served certificate without a restart.
  • Clippy, fmt and tests are clean, and the T8 live check passes.

Notes

  • DEC-12 holds the rationale. The NixOS module (WS-H) passes certificate paths through systemd LoadCredential so the service user never needs read access to the original key file.

Log

  • 2026-10-16: Card created from design discussion.
  • 2026-10-16: Implemented on ws-i/tls, T1-T8 done. TLS is optional, default off (user requirement): with server.tls.enabled = false the plain path is unchanged, the cert/key paths are ignored and never read, no rustls code runs, no provider is built, MCP origins stay http://; env (SKYG_SERVER__TLS__*) and --print-config cover the block. Design: src/tls.rs uses tokio-rustls + hyper-util (auto builder, HTTP/1.1 ALPN) with an accept loop and a ReloadableCert (ResolvesServerCert behind an RwLock) so SIGHUP swaps the cert for new handshakes without touching live connections; a bad pair logs an error and keeps the old one. The ring provider is passed explicitly to ServerConfig::builder_with_provider; no process-wide default is installed (aws-lc-rs was already in the tree via reqwest/OTLP; this adds no new provider or openssl). Cargo.toml: rustls, tokio-rustls, hyper-util (separate commit), rcgen dev-dependency. Shutdown: accept stops, each connection gets graceful_shutdown, bounded by the existing 10s drain (test: SIGTERM with an idle keep-alive and an open SSE stream over TLS exits 0). T5 warning is logged only when TLS is off and bind is non-loopback. Tests: 3 new unit tests (config validation, env, origins) and 8 in tests/tls.rs. Live check (debug binary, openssl-generated certs, curl): healthz, 401/200 REST, MCP initialize over HTTPS, plain HTTP rejected, SIGHUP changed the served fingerprint, a junk cert + SIGHUP kept the rotated one, SIGTERM exit 0.