Repair stale new-host and SOPS registration helpers #224

New issue

Open

opened 2026-09-12 17:15:15 +01:00 by nimmo · 2 comments

nimmo commented

2026-09-12 17:15:15 +01:00

Owner

Problem

Phase 4 wiki verification found that the public new-host helpers no longer match the current repository architecture and secret-scope policy.

just add-host HOSTNAME correctly creates and stages hosts/HOSTNAME/default.nix, but its printed flake registration example still expands the old inline nixpkgs.lib.nixosSystem form. Current hosts use the shared makeNixosSystem { configName = "HOSTNAME"; } builder.
just add-secret and just add-secret-remote tell the operator to use a nonexistent migrate-host-key recipe when a host is already registered.
Both secret helpers insert the new host reference after only the last recipient reference in .sops.yaml. In the current scoped layout, host access must be selected per explicit consumer rule; appending to one syntactic location is not a reliable expression of required access.
The helpers then run sops updatekeys across tracked secret files, which can give a false impression that every required host/service rule was deliberately reviewed.

Scope

Update host scaffolding output to the current makeNixosSystem registration pattern and current host/profile boundaries.
Replace or implement the nonexistent host-key migration guidance.
Make recipient registration explicit and safe for the scoped SOPS layout. It should not silently grant broad access or imply that one recipient-group insertion is sufficient.
Add regression coverage for generated guidance and recipient-rule handling.
Update README/wiki commands if the supported interface changes.

Acceptance criteria

Generated host registration instructions match current flake.nix.
New-host recipient access is chosen from real consumer requirements and represented in explicit creation rules.
Duplicate/existing host handling points to a real supported rotation procedure.
Tests cover current multi-rule .sops.yaml behavior.
Host provisioning runbook can use the helpers without a transitional warning.

Discovered while executing wiki rebuild issue #222 against source commit 556df88494.

## Problem Phase 4 wiki verification found that the public new-host helpers no longer match the current repository architecture and secret-scope policy. - `just add-host HOSTNAME` correctly creates and stages `hosts/HOSTNAME/default.nix`, but its printed flake registration example still expands the old inline `nixpkgs.lib.nixosSystem` form. Current hosts use the shared `makeNixosSystem { configName = "HOSTNAME"; }` builder. - `just add-secret` and `just add-secret-remote` tell the operator to use a nonexistent `migrate-host-key` recipe when a host is already registered. - Both secret helpers insert the new host reference after only the last recipient reference in `.sops.yaml`. In the current scoped layout, host access must be selected per explicit consumer rule; appending to one syntactic location is not a reliable expression of required access. - The helpers then run `sops updatekeys` across tracked secret files, which can give a false impression that every required host/service rule was deliberately reviewed. ## Scope - Update host scaffolding output to the current `makeNixosSystem` registration pattern and current host/profile boundaries. - Replace or implement the nonexistent host-key migration guidance. - Make recipient registration explicit and safe for the scoped SOPS layout. It should not silently grant broad access or imply that one recipient-group insertion is sufficient. - Add regression coverage for generated guidance and recipient-rule handling. - Update README/wiki commands if the supported interface changes. ## Acceptance criteria - [ ] Generated host registration instructions match current `flake.nix`. - [ ] New-host recipient access is chosen from real consumer requirements and represented in explicit creation rules. - [ ] Duplicate/existing host handling points to a real supported rotation procedure. - [ ] Tests cover current multi-rule `.sops.yaml` behavior. - [ ] Host provisioning runbook can use the helpers without a transitional warning. Discovered while executing wiki rebuild issue #222 against source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e.

nimmo added this to the Wiki Knowledge Architecture Rebuild milestone

2026-09-12 17:15:15 +01:00

nimmo added the

host:fleet

project:wiki-rebuild

labels

2026-09-12 17:15:15 +01:00

nimmo commented

2026-09-12 17:19:21 +01:00

Author

Owner

Additional verified defect: after nixos-anywhere completes, the provision recipe prints ssh root@TARGET 'rm /root/.config/sops/age/keys.txt'. Managed hosts that enable SSH set PermitRootLogin = "no", so this cleanup path is normally unavailable after first boot. The supported guidance should use the configured administrative account with sudo (and a TTY where required), after permanent host-key decryption has been proven. The current wiki runbook documents that safe sequence.

Additional verified defect: after nixos-anywhere completes, the provision recipe prints `ssh root@TARGET 'rm /root/.config/sops/age/keys.txt'`. Managed hosts that enable SSH set `PermitRootLogin = "no"`, so this cleanup path is normally unavailable after first boot. The supported guidance should use the configured administrative account with sudo (and a TTY where required), after permanent host-key decryption has been proven. The current wiki runbook documents that safe sequence.

nimmo referenced this issue

2026-09-12 17:19:39 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo referenced this issue

2026-09-12 23:55:03 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo commented

2026-09-12 23:55:14 +01:00

Author

Owner

Additional Phase 4 finding: secrets/README.md still instructs just migrate-host-key HOSTNAME, but just --list and justfiles/secrets.just confirm that recipe does not exist. The new wiki runbook uses a staged manual recipient-rotation procedure until this issue repairs the helper and README guidance. The current remove-secret-key helper also bulk-runs updatekeys using the invoking host SSH identity, which may not be authorised for every scoped file; avoid presenting it as a complete rotation procedure without per-file checks.

nimmo referenced this issue

2026-09-13 11:16:29 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo referenced this issue

2026-09-13 12:54:16 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo referenced this issue

2026-09-13 12:57:42 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo referenced this issue

2026-09-14 07:35:52 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222