Add documentation for managing encrypted secrets with sops and age

nix-system-configs/modules/system/system_wishlist.md

@@ -1,5 +1,5 @@
 ## Mail Server
 
-Todo: Resolve the issue with the Three / 3 about the IP PTR Record mismatch where the mail.prg-radio.org off the IP
+TODO: Resolve the issue with the Three / 3 about the IP PTR Record mismatch where the mail.prg-radio.org off the IP
 record is XXX.XXX.XXX.XXX.mobile.3.dk and not XXX.XXX.XXX.XXX, which hecks up the secure reverse DNS lookup.
-Current solution uses SMPT2Go, which has limited outbound mail limits.
+Current solution uses SMPT2Go, which has limited outbound mail limits.

secrets.md

@@ -1,4 +1,4 @@
-# Secrets — managing encrypted secrets with sops (age)
+# Secrets – managing encrypted secrets with sops (age)
 
 This document explains how we manage secrets for the PRG server configuration using sops and the age encryption protocol. It keeps the original workflow and file layout but presents it in a more structured, readable format with examples and useful tips.
 
@@ -13,9 +13,9 @@ We encrypt secrets with sops using the age tool. The repository contains a `.sop
 
 ## Files and conventions (what to look for)
 
-- `.sops.yaml` — repository configuration that lists public age recipients and creation_rules that map file paths to key groups.
+- `.sops.yaml` - repository configuration that lists public age recipients and creation_rules that map file paths to key groups.
-- `nix-system-configs/secrets/...` — the repository path where secrets are stored, organized by subsystem (for example `database`, `mail`, `songsheet`, `build_machine`, `traefik`, etc.).
+- `nix-system-configs/secrets/...` - the repository path where secrets are stored, organized by subsystem (for example `database`, `mail`, `songsheet`, `build_machine`, `traefik`, etc.).
-- Nix module files that use sops (examples in `nix-system-configs/modules/secrets-config/`) — those show how secrets are exported into NixOS as file or string secrets.
+- Nix module files that use sops (examples in `nix-system-configs/modules/secrets-config/`) - those show how secrets are exported into NixOS as file or string secrets.
 
 Inspect the repository's `.sops.yaml` (example shown later) and the secrets folders before creating or editing secrets.
 
@@ -38,7 +38,7 @@ nix-shell -p age --run 'sudo mkdir -p /var/lib/sops-nix && sudo chown $USER /var
 What the generated key file contains (example):
 
 - private key: starts with `AGE-SECRET-KEY-` (keep private)
-- public key (recipient): looks like `age1...` — this is what you add to `.sops.yaml`
+- public key (recipient): looks like `age1...` - this is what you add to `.sops.yaml`
 
 
 ## Inspecting / editing `.sops.yaml`
@@ -71,7 +71,7 @@ Notes:
 1. Ensure the public recipient(s) for the intended end systems exist in `.sops.yaml`.
 2. Use sops to create or edit an encrypted file. If sops cannot find an age key in the usual locations, pass `SOPS_AGE_KEY_FILE` pointing to the generated private key (only when editing locally with your private key present).
 
-Example (editor micro) — note we use a temporary environment so sops can locate the key you generated locally:
+Example (editor micro) - note we use a temporary environment so sops can locate the key you generated locally:
 
 ```zsh
 # from the repository root, create/edit a new secret for the build machine
@@ -86,7 +86,7 @@ runner_token: "example-runner-token"
 # any other keys as required by your service
 ```
 
-After saving, sops will replace plaintext with encrypted blocks and add a `sops:` metadata section — commit this encrypted file to git.
+After saving, sops will replace plaintext with encrypted blocks and add a `sops:` metadata section - commit this encrypted file to git.
 
 
 #### Example secret file
@@ -173,7 +173,20 @@ imports = [
 > sudo cat /var/lib/sops-nix/key.txt
 > ```
 >
-> Important: never commit the private key (the `AGE-SECRET-KEY-...` line) into the repository — only the `age1...` public recipient belongs in `.sops.yaml`.
+> Important: never commit the private key (the `AGE-SECRET-KEY-...` line) into the repository - only the `age1...` public recipient belongs in `.sops.yaml`.
+
+> [!NOTE]
+> After you add a new public `age1...` recipient to `.sops.yaml`, update any existing encrypted files so the new recipient is included in each file's recipients list. Use `sops updatekeys <file>` to update a single file; sops must be able to decrypt the file locally (for example by having a private key available or by setting `SOPS_AGE_KEY_FILE`).
+>
+> Examples:
+>
+> ```zsh
+> # update a single file so the new recipient can decrypt it
+> sops updatekeys nix-system-configs/secrets/project_example/secrets.yaml
+>
+> # or update all yaml secrets in the secrets tree (run from repo root)
+> find nix-system-configs/secrets -type f -name "*.yaml" -exec sops updatekeys {} \;
+> ```
 
 
 4) Reference the secret from other Nix code and services
@@ -207,6 +220,6 @@ This instructs the generated Nix expression to reference the secret name (which
 
 - Never commit private keys. Only public age recipients belong in `.sops.yaml`.
 - If sops fails to encrypt/decrypt locally, check that you have the corresponding private key available and `SOPS_AGE_KEY_FILE` points to it when running from a shell that cannot otherwise find it.
-- `path_regex` in `.sops.yaml` is matched relative to the repo root — use it carefully so creation rules apply where expected.
+- `path_regex` in `.sops.yaml` is matched relative to the repo root - use it carefully so creation rules apply where expected.
 - If `sops.age.generateKey` is enabled and you rely on the module to generate keys, remember you must register the generated public recipient in the repo `.sops.yaml` after first activation. Extract the `age1...` line with one of the commands above and add it to `keys:` and the appropriate `creation_rules`.
 - If the Nix module expects the private key at `/var/lib/sops-nix/key.txt`, make sure that is where the key is placed on the target end system and that ownership/mode are correct for the system service that reads it.