plan: DEC-9/10 decided, DEC-12 TLS proposed, add WS-I TLS card, update WS-H
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
b5b3466e1d
commit
7b588120e0
6 files changed
+91
-27
No files matched your search
+3
-1
@@ -46,7 +46,8 @@ Move a card by cutting its row into another column. Keep the card's own **Status
|
||||
| [WS-F MCP](workstreams/WS-F-mcp.md) | P0 to start; A, B, C, D to finish |
|
||||
| [WS-G OTel](workstreams/WS-G-otel.md) | P0 to start; A, B, C to finish |
|
||||
| [P3 Integration](workstreams/P3-integration.md) | E, F, G |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | P3 |
|
||||
| [WS-I TLS](workstreams/WS-I-tls.md) | P3 |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | P3, WS-I |
|
||||
|
||||
## Milestones
|
||||
|
||||
@@ -57,3 +58,4 @@ Move a card by cutting its row into another column. Keep the card's own **Status
|
||||
| M2 Surfaces | Verification #3, #4 and #5 pass | 🟨 #3 and #4 verified live on 2026-10-15; #5 (OTel smoke test) not run, no otelcol-contrib binary |
|
||||
| M3 Release | Verification #1–#6 pass. Unit file and README shipped. | ⬜ |
|
||||
| M4 NixOS | `nix flake check` passes including the VM test. `:1984` serves and a token is minted with the system-installed CLI. | ⬜ |
|
||||
| M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | ⬜ |
|
||||
+3
-2
@@ -23,7 +23,8 @@ Markdown workboard for building skyg-linux-tracker (CLI: `slinuxm`). The design
|
||||
| [WS-F MCP](workstreams/WS-F-mcp.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/mcp/` |
|
||||
| [WS-G OTel](workstreams/WS-G-otel.md) | 2 | P0 (fakes); A, B, C to finish | `src/telemetry/`, `dev/otelcol.yaml` |
|
||||
| [P3 Integration](workstreams/P3-integration.md) | 3 | E, F, G | `src/main.rs` (wiring), `systemd/`, `README.md`, `tests/` |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | 4 | P3 | `flake.nix`, `nix/` |
|
||||
| [WS-I TLS](workstreams/WS-I-tls.md) | 4 | P3 | `src/tls.rs`, `server.tls` config keys, `tests/tls.rs` |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | 4 | P3, WS-I | `flake.nix`, `nix/` |
|
||||
|
||||
## Dependency graph
|
||||
|
||||
@@ -35,7 +36,7 @@ P0 Foundation (config, DTOs, traits+fakes, AppState, stubs)
|
||||
└── WS-D auth ─────┤ WS-F MCP ───┼──► P3 Integration
|
||||
└──► WS-G OTel ──┘
|
||||
|
||||
P3 Integration ──► WS-H NixOS (package + module + CLI wrapper + VM test)
|
||||
P3 Integration ──► WS-I TLS ──► WS-H NixOS (package + module + CLI + VM test)
|
||||
```
|
||||
|
||||
With source traits and fakes (DEC-2), Phase 2 cards can **start** as soon as P0 is done. They **finish** only once their real sources are merged and verified against a live host.
|
||||
|
||||
+20
-12
@@ -108,27 +108,25 @@ The MCP spec requires Origin validation on Streamable HTTP servers. If the pinne
|
||||
|
||||
---
|
||||
|
||||
## DEC-9 — Port 1984 in the NixOS module, reachable from a remote server on the LAN
|
||||
## DEC-9 — Port 1984 in the NixOS module, loopback by default
|
||||
|
||||
**Status:** Revised 2026-10-16, awaiting answers
|
||||
**Status:** Decided 2026-10-16
|
||||
|
||||
The module defaults `port = 1984`. The binary's own default is unchanged, so non-Nix installs are unaffected.
|
||||
The module defaults `port = 1984` and `bind = "127.0.0.1"`. The binary's own default is unchanged. Exposing the service to the LAN is an install-time choice made in the host's own config, never a default: the operator sets `bind`, `openFirewall` (or an interface-scoped rule) and `allowedHosts` for that deployment. Config validation already refuses auth-off on a non-loopback bind, and a non-loopback bind without TLS logs a warning (see DEC-12).
|
||||
|
||||
**Intended use:** another server on the LAN calls this host. So the host config sets `bind` to a LAN address (or `0.0.0.0`), the firewall opens 1984 for that traffic, and auth must be enabled (config validation already refuses auth-off on a non-loopback bind). For `/mcp`, `server.allowed_hosts` must include the hostname or IP the remote client uses, or rmcp answers 403.
|
||||
|
||||
**Open:** (a) restrict the firewall to the remote server's IP or subnet, which is recommended, versus the whole LAN; (b) plain HTTP versus TLS in front, since bearer tokens are readable on the wire over plain HTTP; (c) the LAN address or hostname clients use.
|
||||
|
||||
**Decision:**
|
||||
**Decision:** Accepted by the user. The default is loopback. Installs change the relevant settings.
|
||||
|
||||
---
|
||||
|
||||
## DEC-10 — CLI wrapper for token commands
|
||||
## DEC-10 — No CLI wrapper
|
||||
|
||||
**Status:** Proposed
|
||||
**Status:** Decided 2026-10-16
|
||||
|
||||
The DB is in a 0700 state dir owned by the service user, so a login user cannot run `slinuxm token …` directly. The module installs `slinuxm` on `PATH` as a wrapper that re-execs `token` subcommands via `sudo -u <service user>` and passes everything else through. Alternative: ship the bare binary and document `sudo -u`.
|
||||
The module installs the plain `slinuxm` binary on `PATH`. Tokens are minted with `sudo -u skyg-linux-tracker slinuxm token create <name>`, documented in the README and in the module's post-install notes. No wrapper script.
|
||||
|
||||
**Decision:**
|
||||
Running the token commands as root is a trap: if the service has not started yet, root creates the state dir and DB owned by root, and root-owned WAL files can lock the service out. So the token subcommands refuse to run as root when the state dir or DB belongs to another user, and print the exact `sudo -u …` command to use. This is a small change in `slinuxm`, tracked as H5.
|
||||
|
||||
**Decision:** Accepted by the user. No wrapper. The app guards against the root mistake.
|
||||
|
||||
---
|
||||
|
||||
@@ -139,3 +137,13 @@ The DB is in a 0700 state dir owned by the service user, so a login user cannot
|
||||
Tokens are minted with `slinuxm token create <name>`, printed once, and never stored in plaintext. There is no `bootstrapTokens` option and no import of pre-hashed tokens in v1.
|
||||
|
||||
**Decision:** Accepted by the user: print the token once, never store it.
|
||||
|
||||
---
|
||||
|
||||
## DEC-12 — TLS terminated in-process with rustls
|
||||
|
||||
**Status:** Proposed
|
||||
|
||||
Bearer tokens over plain HTTP are readable on the wire, and LAN exposure is the intended deployment. The service gets native TLS: `server.tls.enabled`, `cert_file`, `key_file`, with certificate reload on SIGHUP so ACME or sops-managed rotation needs no restart. A reverse proxy still works and nothing depends on it. rustls is already in the dependency tree and openssl stays out. When TLS is enabled the MCP Origin allowlist uses `https://`. A non-loopback bind without TLS logs a startup warning but is not refused.
|
||||
|
||||
**Decision:**
|
||||
@@ -5,7 +5,7 @@
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 4 (single track, after release candidate) |
|
||||
| Depends on | P3 (final unit hardening, `--print-config`, README) |
|
||||
| Depends on | P3 (final unit hardening, `--print-config`, README); WS-I (TLS options) |
|
||||
| Blocks | — |
|
||||
| Owned files | `flake.nix`, `nix/package.nix`, `nix/module.nix`, `nix/tests/`, `README.md` (NixOS section only) |
|
||||
|
||||
@@ -22,7 +22,8 @@ Tick these in [`TODO.md`](../../TODO.md).
|
||||
- **H3** `nix/module.nix` options under `services.skyg-linux-tracker`:
|
||||
- `enable`, `package`
|
||||
- `port` (default **1984**; the app default is unchanged, DEC-9)
|
||||
- `bind` (default `"127.0.0.1"`)
|
||||
- `bind` (default `"127.0.0.1"`; LAN exposure is set per install)
|
||||
- `tls.enable`, `tls.certFile`, `tls.keyFile` (passed via systemd `LoadCredential`, DEC-12)
|
||||
- `openFirewall` (default `false`)
|
||||
- `allowedHosts` (extra Host/Origin entries for `/mcp`; the module adds `networking.hostName` automatically)
|
||||
- `docker.enable` (default `false`; adds the `docker` group and sets the socket path, DEC-6)
|
||||
@@ -34,15 +35,15 @@ Tick these in [`TODO.md`](../../TODO.md).
|
||||
- `SupplementaryGroups=systemd-journal` (plus `docker` when enabled)
|
||||
- the P3 hardening set (`NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome`, `PrivateTmp`, `RestrictAddressFamilies`, …), reusing `systemd/skyg-linux-tracker.service` rather than diverging
|
||||
- config written to `/etc/skyg-linux-tracker.toml`, the default path the app already reads, so the CLI and the service always agree
|
||||
- **H5** CLI install (required): `environment.systemPackages = [ cfg.package ]`. A thin wrapper on `PATH` re-execs `slinuxm token create|list|revoke …` as the service user via `sudo -u`, and passes every other subcommand through untouched. Without privileges it prints a clear message instead of a permission error (DEC-10).
|
||||
- **H5** CLI install (required): `environment.systemPackages = [ cfg.package ]`, plain binary, no wrapper (DEC-10). Mint tokens with `sudo -u skyg-linux-tracker slinuxm token create <name>`; the module's NixOS notes and the README show this exact command. The root guard in `slinuxm` (token commands refuse to run as root against another user's DB and print the command above) is implemented here as a small change in the CLI code.
|
||||
- **H6** Firewall: `openFirewall` opens the port globally. Also support an interface-scoped option (`networking.firewall.interfaces.<if>.allowedTCPPorts`), which is the recommended LAN setup. Assert at eval time that `bind` non-loopback is accompanied by auth enabled.
|
||||
- **H7** README NixOS section: flake input, minimal config, token workflow (`sudo slinuxm token create <name>`), the exposure model (loopback + Tailscale or TLS proxy recommended, since bearer tokens over plain HTTP are readable on a LAN), `allowedHosts` for `bind = 0.0.0.0`.
|
||||
- **H7** README NixOS section: flake input, minimal config, token workflow (`sudo -u skyg-linux-tracker slinuxm token create <name>`), the exposure model (loopback + Tailscale or TLS proxy recommended, since bearer tokens over plain HTTP are readable on a LAN), `allowedHosts` for `bind = 0.0.0.0`.
|
||||
- **H8** NixOS VM test (`nix/tests/`):
|
||||
1. service starts and `curl :1984/healthz` returns 200 unauthenticated
|
||||
1. service starts and `curl :1984/healthz` returns 200 unauthenticated (a second case with TLS enabled and a test cert)
|
||||
2. `/api/v1/systemd/units` returns 401 without a token
|
||||
3. `sudo slinuxm token create t` prints a token, and the same request with it returns 200
|
||||
3. `sudo -u skyg-linux-tracker slinuxm token create t` prints a token, and the same request with it returns 200
|
||||
4. `/mcp` initialize and tools/list work with the token
|
||||
5. `sudo slinuxm token revoke t` makes the same request return 401 without a restart
|
||||
5. `slinuxm token revoke t` (same `sudo -u` form) makes the same request return 401 without a restart
|
||||
6. bad Origin on `/mcp` returns 403
|
||||
|
||||
## Done when
|
||||
@@ -54,7 +55,7 @@ Tick these in [`TODO.md`](../../TODO.md).
|
||||
## Notes
|
||||
|
||||
- Port 1984 is set in the module only, so the non-Nix path is unchanged.
|
||||
- Declarative/hash-imported tokens and activation-time `bootstrapTokens` are out of scope for v1 (DEC-11). They would need a `slinuxm` change to import hashes from a file.
|
||||
- Tokens are printed once and never stored (DEC-11). Declarative/hash-imported tokens and activation-time `bootstrapTokens` are out of scope for v1 are not offered.
|
||||
- The module must not put secrets in the generated TOML. Anything sensitive goes through `environmentFile`.
|
||||
|
||||
## Log
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# 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).
|
||||
|
||||
- **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 in `config.example.toml`.
|
||||
- **I2** 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.
|
||||
- **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_origins` default to `https://…`. `allowed_hosts` is unchanged.
|
||||
- **I5** Startup warning when `bind` is 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 --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 I8 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.
|
||||
Reference in new issue
Block a user