From 13e5a9bb5663410c874f5f866940f133825eac13 Mon Sep 17 00:00:00 2001 From: alexion Date: Sun, 19 Jul 2026 16:56:36 -0400 Subject: [PATCH] docs: describe the current secrets design in the install procedure The closing section still described key derivation from each machine's SSH host key, a mechanism that was superseded because it forces new host keys on every reimage and makes storing those keys as secrets circular. Record the two-tier identity model that replaced it, and warn that the hand-set bootstrap password stops working once the password becomes a secret: hashedPasswordFile outranks every other password option, so a machine installed after that must have its identity provisioned before first boot rather than a password set afterwards. --- docs/install.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/install.md b/docs/install.md index 148c778..752875a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -148,6 +148,12 @@ At boot you are prompted for the LUKS passphrase from step 3; after unlocking, l Setting the login password by hand is a bootstrap shortcut, not the end state. The first thing to do on the running laptop is to move that password to a `hashedPasswordFile` backed by a `sops-nix` secret, so it is declared and reproducible like everything else. -This is deliberately out of scope for the install itself. -Per ADR 0001, each `Host`'s secrets are encrypted to an age key derived from that `Host`'s SSH host key — and that host key does not exist until this first install generates it. -So the sops wiring can only happen *after* the machine is up, which is exactly why it is the first follow-up rather than part of this procedure. +Per ADR 0002, secrets are decrypted by two tiers of age identity: an admin identity held in a password manager, which is a recipient of every secrets file, and a per-`Host` identity generated on that machine's encrypted root. +A `Host` identity is deliberately *not* derived from its SSH host key, which is what allows the SSH host keys to become secrets in their own right and survive a reimage. + +That wiring is out of scope here because this procedure is what produces the machine the identity is generated on. + +**Once the password is a secret, step 4 of this procedure stops working.** +`hashedPasswordFile` takes precedence over every other password option, so `passwd` under `nixos-enter` no longer yields a login, and no fallback setting can override it. +From that point on, a `Host` must have its identity provisioned and registered as a recipient *before* its first boot, or it boots with no usable password. +Anyone reinstalling after the secrets work lands should follow the secrets provisioning procedure rather than step 4 as written.