# 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`](../../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.