plan: add WS-H NixOS module + CLI install card, TODO phase 4, DEC-9..11
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
936efaf97e
commit
af73d118bb
5 files changed
+109
No files matched your search
@@ -102,3 +102,15 @@ Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md)
|
||||
- [ ] **I4** README: install, config reference, token workflow, MCP client setup, hardened docker option
|
||||
- [ ] **I5** Release build: `ldd` shows only libc + libsystemd and its deps. Record binary size.
|
||||
- [ ] **I6** Full manual Verification #1–#6 from `plan.md` passes on a real host
|
||||
|
||||
## Phase 4 — NixOS packaging · [card](plan/workstreams/WS-H-nixos.md)
|
||||
|
||||
- [ ] **H1** `nix/package.nix`: `buildRustPackage` from `Cargo.lock` with pkg-config, cmake, systemd. Binary `slinuxm`.
|
||||
- [ ] **H2** `flake.nix` with `packages.default`, `nixosModules.default` and `checks`
|
||||
- [ ] **H3** `nix/module.nix` options: `enable`, `package`, `port` (default 1984), `bind`, `openFirewall`, `allowedHosts`, `docker.enable`, `settings`, `environmentFile`
|
||||
- [ ] **H4** Service: dedicated user, `StateDirectory` 0700, `systemd-journal` group, P3 hardening set, config at `/etc/skyg-linux-tracker.toml`
|
||||
- [ ] **H5** **CLI installed system-wide** with a wrapper that runs `slinuxm token …` as the service user (DEC-10)
|
||||
- [ ] **H6** Firewall: global `openFirewall` plus interface-scoped option. Eval assertion: non-loopback bind requires auth.
|
||||
- [ ] **H7** README NixOS section: flake input, token workflow, exposure model, `allowedHosts`
|
||||
- [ ] **H8** NixOS VM test: healthz, 401, mint token via CLI, 200, `/mcp`, revoke, 401, bad Origin 403
|
||||
- [ ] **Gate:** `nix build` and `nix flake check` pass. `ldd` shows no openssl. A fresh NixOS host serves `:1984` and a token can be minted from a login shell.
|
||||
@@ -46,6 +46,7 @@ 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 |
|
||||
|
||||
## Milestones
|
||||
|
||||
@@ -55,3 +56,4 @@ Move a card by cutting its row into another column. Keep the card's own **Status
|
||||
| M1 Sources live | All four Phase 1 examples run against a real host | ⬜ |
|
||||
| M2 Surfaces | Verification #3, #4 and #5 pass | ⬜ |
|
||||
| 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. | ⬜ |
|
||||
@@ -23,6 +23,7 @@ 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/` |
|
||||
|
||||
## Dependency graph
|
||||
|
||||
@@ -33,6 +34,8 @@ P0 Foundation (config, DTOs, traits+fakes, AppState, stubs)
|
||||
├── WS-C docker ───┼──► WS-E REST ──┐
|
||||
└── WS-D auth ─────┤ WS-F MCP ───┼──► P3 Integration
|
||||
└──► WS-G OTel ──┘
|
||||
|
||||
P3 Integration ──► WS-H NixOS (package + module + CLI wrapper + 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.
|
||||
|
||||
@@ -105,3 +105,33 @@ Options:
|
||||
The MCP spec requires Origin validation on Streamable HTTP servers. If the pinned `rmcp` version has a built-in allowed-hosts or Origin option, use it. Otherwise add a small tower layer on `/mcp` that rejects requests whose `Origin` is present and not in an allowlist. Default allowlist: loopback origins plus `server.bind`.
|
||||
|
||||
**Decision:** Resolved by spike P0-3, 2026-10-15. `rmcp` 3.5.1 validates both headers itself: `StreamableHttpServerConfig::with_allowed_hosts` (default: loopback names only) and `with_allowed_origins` (default empty = Origin validation off; requests without `Origin` always pass). **No custom tower layer is needed.** F8 must set both. Hosts: loopback names + `server.bind` + `server.allowed_hosts`. Origins: `http://localhost:*`, `http://127.0.0.1:*`, `http://[::1]:*`, `http://<bind>:*` + `server.allowed_origins`. The config keys `server.allowed_hosts` and `server.allowed_origins` already exist.
|
||||
|
||||
---
|
||||
|
||||
## DEC-9 — Port 1984 lives in the NixOS module
|
||||
|
||||
**Status:** Proposed
|
||||
|
||||
The module defaults `port = 1984` and `bind = 127.0.0.1`. The binary's own default is unchanged, so non-Nix installs are unaffected. Exposure beyond loopback is an explicit opt-in (`openFirewall` or an interface-scoped rule). Bearer tokens over plain HTTP are readable on a LAN, so Tailscale or a TLS proxy is the recommended path.
|
||||
|
||||
**Decision:**
|
||||
|
||||
---
|
||||
|
||||
## DEC-10 — CLI wrapper for token commands
|
||||
|
||||
**Status:** Proposed
|
||||
|
||||
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`.
|
||||
|
||||
**Decision:**
|
||||
|
||||
---
|
||||
|
||||
## DEC-11 — No declarative or bootstrap tokens in v1
|
||||
|
||||
**Status:** Proposed
|
||||
|
||||
A `bootstrapTokens` option would write plaintext secrets to disk, and importing pre-hashed tokens needs a `slinuxm` change. Tokens stay imperative: printed once, never stored in plaintext.
|
||||
|
||||
**Decision:**
|
||||
@@ -0,0 +1,62 @@
|
||||
# WS-H — NixOS module + package
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 4 (single track, after release candidate) |
|
||||
| Depends on | P3 (final unit hardening, `--print-config`, README) |
|
||||
| Blocks | — |
|
||||
| Owned files | `flake.nix`, `nix/package.nix`, `nix/module.nix`, `nix/tests/`, `README.md` (NixOS section only) |
|
||||
|
||||
## Goal
|
||||
|
||||
Install `skyg-linux-tracker` on NixOS as a systemd service that exposes the REST API and `/mcp` on **port 1984**, and install the `slinuxm` CLI system-wide so the operator can mint the first token.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **H1** `nix/package.nix`: `rustPlatform.buildRustPackage` from the committed `Cargo.lock`. `nativeBuildInputs = [ pkg-config cmake ]` (cmake for `aws-lc-sys`), `buildInputs = [ systemd ]`. Binary is `slinuxm`. Live-journal tests are `#[ignore]`, so the sandbox build runs `cargo test`.
|
||||
- **H2** `flake.nix` exporting `packages.<system>.default` and `nixosModules.default`, plus `checks` wired to H8.
|
||||
- **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"`)
|
||||
- `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)
|
||||
- `settings` (freeform TOML via `pkgs.formats.toml`, merged over module defaults)
|
||||
- `environmentFile` (for secrets such as `SKYG_OTEL__HEADERS__*`, kept out of the store)
|
||||
- **H4** Service definition:
|
||||
- dedicated user and group
|
||||
- `StateDirectory=skyg-linux-tracker`, mode 0700 (matches `db_path`)
|
||||
- `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).
|
||||
- **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`.
|
||||
- **H8** NixOS VM test (`nix/tests/`):
|
||||
1. service starts and `curl :1984/healthz` returns 200 unauthenticated
|
||||
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
|
||||
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
|
||||
6. bad Origin on `/mcp` returns 403
|
||||
|
||||
## Done when
|
||||
|
||||
- `nix build .#default` produces `bin/slinuxm`, and `ldd` shows only libc and libsystemd (plus deps). No openssl.
|
||||
- `nix flake check` passes, including the VM test (H8).
|
||||
- On a NixOS host, enabling the module with `port = 1984` exposes `:1984` as described, and `slinuxm token create` works from a normal login shell.
|
||||
|
||||
## 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.
|
||||
- The module must not put secrets in the generated TOML. Anything sensitive goes through `environmentFile`.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created from design discussion.
|
||||
Reference in new issue
Block a user