42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
# 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`](../../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.
|