2.4 KiB
2.4 KiB
WS-I — Native TLS
| Field | Value |
|---|---|
| Status | Backlog |
| 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.
- I1 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. - I2 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. - I3 Reload certificate and key on SIGHUP without dropping connections. A bad new cert keeps the old one and logs an error.
- I4 MCP allowlists: when TLS is on,
allowed_originsdefault tohttps://….allowed_hostsis unchanged. - I5 Startup warning when
bindis non-loopback and TLS is off. Do not refuse. - I6 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. - I7 README TLS section, with a self-signed example and a note on ACME or sops certificate paths.
- I8 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 I8 live check passes.
Notes
- 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.