fixes and docs

README.md

@@ -113,6 +113,122 @@ sudo nixos-rebuild switch --flake .#hostname
 home-manager switch --flake .#username@hostname
 ```
 
+## Secrets Management
+
+Secrets are managed with [sops-nix](https://github.com/Mic92/sops-nix). Each secret file is encrypted with [age](https://age-encryption.org/), using the SSH host key (`/etc/ssh/ssh_host_ed25519_key`) of each machine as a recipient, so that machine can decrypt its own secrets at boot without any passphrase.
+
+### How age keys work
+
+sops-nix derives an age key from the machine's ed25519 SSH host key automatically. The corresponding age **public key** must be added to `.sops.yaml` before you can encrypt secrets for that machine.
+
+To get the age public key for a machine:
+
+```bash
+# On the target machine (or from its host key file):
+nix-shell -p ssh-to-age --run \
+  'ssh-keyscan localhost 2>/dev/null | ssh-to-age'
+
+# Or directly from the key file:
+nix-shell -p ssh-to-age --run \
+  'ssh-to-age < /etc/ssh/ssh_host_ed25519_key.pub'
+```
+
+### Adding a new machine
+
+1. **Get the age public key** for the new machine using the command above.
+
+2. **Add it to `.sops.yaml`**:
+   ```yaml
+   keys:
+     - &new-machine age1<public-key-here>
+   creation_rules:
+     - path_regex: secrets/[^/]+\.(yaml|json|env|ini)$
+       key_groups:
+         - age:
+             - *new-machine
+             # ... existing recipients
+   ```
+
+3. **Re-encrypt all secret files** so the new machine becomes a recipient:
+   ```bash
+   find secrets/ -name '*.yaml' -exec sops updatekeys {} \;
+   ```
+
+### Adding a new secret
+
+To add a secret to an existing file:
+
+```bash
+# Edit the file interactively (sops decrypts, opens $EDITOR, re-encrypts on save)
+sops secrets/nas-secrets.yaml
+```
+
+To create a new secrets file:
+
+```bash
+sops secrets/mymachine-secrets.yaml
+```
+
+The `.sops.yaml` `creation_rules` determine which keys encrypt the file based on its path.
+
+### Generating Nebula VPN certificates
+
+The Nebula module (`mjallen.services.nebula`) expects three secrets per host under a configurable prefix:
+- `<prefix>/ca-cert` — the CA certificate (shared across all nodes)
+- `<prefix>/host-cert` — this node's signed certificate
+- `<prefix>/host-key` — this node's private key
+
+**Step 1 — Create the CA** (once per network, on a trusted machine):
+
+```bash
+nebula-cert ca -name "jallen-nebula"
+# Produces: ca.crt, ca.key
+```
+
+**Step 2 — Sign a certificate for each node**:
+
+```bash
+# Lighthouse (assign an overlay IP, e.g. 10.1.1.1)
+nebula-cert sign -name "pi5" -ip "10.1.1.1/24" \
+  -ca-crt ca.crt -ca-key ca.key \
+  -out-crt lighthouse.crt -out-key lighthouse.key
+
+# Regular node (assign a unique overlay IP, e.g. 10.1.1.2)
+nebula-cert sign -name "nas" -ip "10.1.1.2/24" \
+  -ca-crt ca.crt -ca-key ca.key \
+  -out-crt nas.crt -out-key nas.key
+```
+
+**Step 3 — Add the secrets to SOPS**:
+
+```bash
+# Edit the target host's secrets file
+sops secrets/pi5-secrets.yaml
+```
+
+Add the certificate contents under the configured prefix (e.g. `pi5/nebula`):
+
+```yaml
+pi5:
+  nebula:
+    ca-cert: |
+      <contents of ca.crt>
+    lighthouse-cert: |
+      <contents of lighthouse.crt>
+    lighthouse-key: |
+      <contents of lighthouse.key>
+```
+
+The key name for the cert/key pair matches the `hostSecretName` option (e.g. `hostSecretName = "lighthouse"` → looks for `lighthouse-cert` / `lighthouse-key`).
+
+**Step 4 — Shred the plaintext key files** once they are in SOPS:
+
+```bash
+shred -u ca.key lighthouse.key nas.key
+```
+
+> Keep `ca.crt` accessible if you need to sign more nodes later, but store `ca.key` only in SOPS.
+
 ## Documentation
 
 Comprehensive documentation is available in the [docs](./docs) directory: