Files
skyg-linux-tracker/plan/workstreams/WS-I-tls.md
T

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.

  • 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.