5.4 KiB
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 inconfig.example.toml. - T2 Serve over rustls. Pick the integration that keeps openssl out (
axum-serverwithtls-rustls, ortokio-rustlswith 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_originsdefault tohttps://….allowed_hostsis unchanged. - T5 Startup warning when
bindis 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 --cacertagainst the running server, and one/mcpinitialize over HTTPS.
Done when
server.tls.enabled = trueserves HTTPS, andcargo tree -i opensslis 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.enableddefaults tofalse. With it off the server behaves exactly as before: plain HTTP, no cert or key files read, MCP origins stayhttp://. 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
LoadCredentialso 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): withserver.tls.enabled = falsethe plain path is unchanged, the cert/key paths are ignored and never read, no rustls code runs, no provider is built, MCP origins stayhttp://; env (SKYG_SERVER__TLS__*) and--print-configcover the block. Design:src/tls.rsusestokio-rustls+hyper-util(auto builder, HTTP/1.1 ALPN) with an accept loop and aReloadableCert(ResolvesServerCertbehind 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. Theringprovider is passed explicitly toServerConfig::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 getsgraceful_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 intests/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 hyperheader_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'sserve_connection_with_upgradessniffs the protocol before hyper starts, which defeats the header timeout, so the TLS path usesserve_connection(no upgrades; none are used). A SIGHUP handler is now installed at the top ofserveon 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 thecert_filechain. 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.