From a43aa02a6964cf72e726564db47c187c80ac36bd Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Mon, 21 Sep 2026 20:45:47 +0800 Subject: [PATCH] docs(secrets): state the recipient invariant A recipient set must answer two questions: who may read it, and how it is recovered once those hosts are gone. Dropping recovery_key while narrowing a secret is easy and silent. --- secrets/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/secrets/README.md b/secrets/README.md index 6014b2de..2a530d91 100644 --- a/secrets/README.md +++ b/secrets/README.md @@ -20,6 +20,20 @@ repository. This directory contains this `README.md`, and a `nixos.nix`/`darwin.nix` file that is used to decrypt all my secrets via `agenix`. Then, I can use them in this flake. +## Which Keys Go on a Secret + +Changing a secret's recipients is **two** questions, and both have to be answered: + +- **Who must be able to read it?** Only the hosts that actually need it. Splitting by trust domain + (desktops, servers, one application) keeps a compromised host from reading secrets it has no + business reading. +- **How is it recovered when those hosts are gone?** Every set must keep `recovery_key`. It is held + offline and on no machine, so it does not widen who can read a secret — but without it, the secret + is unrecoverable once the machines that could decrypt it are lost. + +Narrowing a secret's recipients is where this bites: it is easy to drop the offline key along with +the hosts being removed. Re-check both questions after any recipient change. + ## Adding or Updating Secrets > All the operations in this section should be performed in my private repository: `nix-secrets`.