# WS-F: NixOS, docs, end-to-end tests Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](contracts.md) sections 5 to 10. | Field | Value | |---|---| | Status | Not started | | Owner | | | Depends on | C, D, E (original plan). F1 (module) and F4 (docs drafts) can begin once A1 settles the config keys, since they depend only on contracts sections 6 and 9; F2/F3 need the other streams | | Blocks | phase exit | | Can start when | F1 and doc drafts: after A0/A1 land. F2: after C, D, E and [WS-T](ws-t-tests.md) are green. F3: after B and C | | Owned files | `nix/module.nix`, `nix/tests/vm.nix`, `systemd/skyg-linux-tracker.service`, `README.md` (peers section), `docs/consolidator.md` (new; except the `## Testing` section owned by WS-T), `tests/peers.rs`, `tests/common/mod.rs` (shared helpers, append-only with B), `config.example.toml` (merge with A1: comments and example peers, not the keys), `flake.nix` (only the move of `tests..peers` into `checks.vm-peers`, in F2), `AGENTS.md` (MCP tool count note) | | Do not touch | `src/**` (all code streams; report bugs to the owning stream's Log), `nix/tests/peers.nix` except to adapt it to the first-class options in F2 (coordinate with WS-T, update contracts section 10), `dev/test.nu`, `devenv.nix` (T), `docs/api.md` (C), `src/config.rs` (A) | Shared-file seams: - `flake.nix`: WS-T owns it until F2; F2 then moves exactly one attribute into `checks`. - `README.md` / `AGENTS.md`: WS-T owns the command lists; F4 owns the peers section and the MCP tool count note (tool count becomes "8, or 10 with peers enabled"). - `config.example.toml`: A1 owns the keys and defaults; F reviews that it is in sync with `docs/consolidator.md` and adds only commentary/examples. - `tests/common/mod.rs`: append-only; B may have added helpers already. ## Goal Shippable, documented, verified. ## Tasks - **F1** module: `peers.enable`; `peers.peers. = { url; tokenFile; caFile ? null; enable ? true; allowPlainHttp ? false; }`; `peers.settings` for intervals/caps. The module renders `[[peers.peer]]` entries into the TOML with the *paths* only and adds one `LoadCredential=peer-:` per peer, pointing each `token_file` at `/run/credentials/skyg-linux-tracker.service/peer-` so the service user needs no read access to `/run/agenix/*` (same mechanism as TLS, DEC-12). `tokenFile` is typed as a string (`config.age.secrets..path`), never a path literal, so secrets cannot enter the Nix store; an eval assertion rejects a store path. Config change reloads via `ExecReload` (SIGHUP) with `reloadIfChanged`, else restarts. Assertions: at least one peer when `peers.enable`; names valid and unique. Also add `RefreshOnReload=credentials` as `nix/tests/peers.nix` does (contracts section 10) if the systemd version supports it. - **F2** promote WS-T to `checks`, switched to the first-class module options (`peers.peers..tokenFile`); plus a three-machine variant (consolidator, peer1, peer2) for fan-in. Mint tokens on peers, write them to root-owned 0400 files on the consolidator (stand-ins for agenix paths) and declare the peers through the module, assert status via REST and MCP, stop peer2's service and assert server/api flip, assert proxied `units` match a direct call, then rotate a token file and revoke the token on the peer: `auth` flips to rejected, then back after rewriting the file, with no restart. Remove a peer from the config, SIGHUP, assert the series is gone. - **F3** `tests/peers.rs` end-to-end (plain, TLS with an `rcgen` CA via `--ca-file`, wrong CA rejected, redirect not followed, oversize body, slow-loris peer, 64-peer cap, cancel on shutdown). - **F4** README section, `docs/consolidator.md` (threat model, token handling, firewall note: peers must allow the consolidator), a worked agenix example (`secrets.nix` entry, `age.secrets.peer-minipc1.file`, `peers.peers.minipc1.tokenFile = config.age.secrets.peer-minipc1.path`), AGENTS.md MCP tool count note. ## Inputs - Contracts section 9 (Nix options), 6 (TOML), 10 (test contract), 5 and 7 (what the tests assert). Fakes: none for F2 (real binary); F3 uses in-process servers, not the fake transport. - Constraint: nix builds only when the nix gate is free (AGENTS.md). ## Done when `nix flake check` passes including the new VM test; docs and example config in sync. ## Handoff - Phase exit evidence: `nix flake check` output, docs, example config, the Verification plan results in the [README](README.md#verification-plan). - To the orchestrator: ARCHITECTURE.md decision rows (DEC-13 and the DEC-11 clarification), TODO.md checklists, and moving `plan/phase-5-consolidator/` to `docs/workstreams/`. ## Log - 2026-10-19: Split from the single phase plan 2026-10-19. `tests/peers.rs` ownership moved here from WS-T; `docs/consolidator.md` shares one `## Testing` section with WS-T.