Files
2026-10-19 14:14:29 -04:00

5.4 KiB

WS-I — Native TLS

Field Value
Status Done
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

  • TLS is optional (user requirement, 2026-10-16). server.tls.enabled defaults to false. With it off the server behaves exactly as before: plain HTTP, no cert or key files read, MCP origins stay http://. It is configurable by file, env (SKYG_SERVER__TLS__*) and shown by --print-config. Existing tests pass unchanged with the default config.
  • 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.
  • 2026-10-16: Review fixes. TLS listener bounded by a semaphore (tls::Limits::max_conns, default 1024; at the cap accepting pauses) and a 30s hyper header_read_timeout (covers post-handshake silence and idle keep-alive), accept-error warnings rate-limited to one per 10s, HTTP/1.1 only. Note: the auto builder's serve_connection_with_upgrades sniffs the protocol before hyper starts, which defeats the header timeout, so the TLS path uses serve_connection (no upgrades; none are used). A SIGHUP handler is now installed at the top of serve on both paths, so SIGHUP never kills the process; with TLS off it only logs. Cert and key are read separately on reload: rotation tooling must send SIGHUP after BOTH files are in place (a mismatch keeps the old pair; fix the files and send HUP again). Intermediates must be in the cert_file chain. Pre-existing and out of scope: the plain-HTTP path has no connection cap or header timeout either (axum::serve defaults), the same exhaustion exposure it had before WS-I. New tests: silent-connection header timeout, connection cap, SIGHUP with TLS off, key/cert mismatch on SIGHUP.