@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/manual/02-tutorials/04-encrypt-secret.md

@@ -0,0 +1,275 @@
+# Tutorial: Encrypt a Secret
+
+How to store an API key (or any secret) encrypted in the repository using Age and SOPS — decrypted automatically on `dot apply`.
+
+## The Threat Model
+
+Secrets in plaintext config files are:
+
+- Committed to Git history (permanent record)
+- Visible to every process on the machine
+- Included in backup archives
+
+Secrets encrypted with Age:
+
+- Cipher text committed to Git is useless without the private key
+- Private key (`~/.config/age/keys.txt`) never leaves the user's machine
+- Per-machine policy: only authorized hosts hold keys for their share of secrets
+
+## Step 1: Generate an Age Key (First Time Only)
+
+```sh
+age-keygen -o ~/.config/age/keys.txt
+chmod 600 ~/.config/age/keys.txt
+```
+
+The public key is embedded in the file:
+
+```sh
+cat ~/.config/age/keys.txt
+# created: 2026-04-16T09:00:00Z
+# public key: age1qy90l...xyz
+AGE-SECRET-KEY-1A...
+```
+
+Copy the public key — you'll reference it when encrypting.
+
+## Step 2: Choose Encryption Method
+
+Two approaches are supported:
+
+| Method | Best For | Filename |
+|:---|:---|:---|
+| **Chezmoi encrypt** | Individual files (API tokens, config snippets) | `dot_config/token.age` |
+| **SOPS** | YAML/JSON with multiple secrets, selective field encryption | `dot_config/creds.sops.yaml` |
+
+## Step 3A: Chezmoi-Encrypted File
+
+Create an unencrypted source file:
+
+```sh
+mkdir -p ~/tmp
+echo "sk_live_abc123" > ~/tmp/stripe-key.txt
+```
+
+Import it as encrypted:
+
+```sh
+chezmoi add --encrypt ~/tmp/stripe-key.txt
+```
+
+This:
+
+1. Reads `~/tmp/stripe-key.txt`
+2. Encrypts with your Age public key
+3. Stores encrypted content at `~/.dotfiles/dot_tmp/stripe-key.txt.age`
+4. Template reads encrypted content at apply time and decrypts to target
+
+Delete the plaintext source:
+
+```sh
+rm ~/tmp/stripe-key.txt
+```
+
+On `dot apply`, chezmoi decrypts and writes to `~/tmp/stripe-key.txt`. If someone lacks the private key, they see only the encrypted `.age` file in Git.
+
+## Step 3B: SOPS-Encrypted YAML
+
+SOPS encrypts **values** in YAML/JSON while preserving the structure. Useful when you want:
+
+- Multiple secrets in one file
+- Encryption of only sensitive fields (leaving metadata readable)
+- Multi-recipient (e.g. the work laptop AND the backup laptop can decrypt)
+
+Configure SOPS once:
+
+```yaml
+# .sops.yaml (at repo root)
+creation_rules:
+  - path_regex: \.sops\.yaml$
+    age: age1qy90l...xyz
+```
+
+Create a secrets file:
+
+```yaml
+# dot_config/credentials.sops.yaml
+database:
+  host: db.prod.example.com
+  user: app
+  password: supersecret
+api_keys:
+  stripe: sk_live_abc
+  sendgrid: SG.xyz
+```
+
+Encrypt it:
+
+```sh
+sops --encrypt --in-place dot_config/credentials.sops.yaml
+```
+
+The file now contains ciphertext blobs where plaintext values were:
+
+```yaml
+database:
+    host: ENC[AES256_GCM,data:...]
+    user: ENC[AES256_GCM,data:...]
+    password: ENC[AES256_GCM,data:...]
+api_keys:
+    stripe: ENC[AES256_GCM,data:...]
+    sendgrid: ENC[AES256_GCM,data:...]
+sops:
+    age:
+        - recipient: age1qy90l...xyz
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            ...
+```
+
+To edit the encrypted file:
+
+```sh
+sops dot_config/credentials.sops.yaml
+# Opens in $EDITOR with decrypted content; re-encrypts on save
+```
+
+## Step 4: Reference the Secret in a Template
+
+Chezmoi has a built-in `decrypt` helper:
+
+```go
+# dot_bashrc.tmpl
+export STRIPE_KEY="{{ include "dot_tmp/stripe-key.txt.age" | decrypt | trim }}"
+```
+
+For SOPS:
+
+```go
+# Use the sopsDecrypt template function
+{{- $creds := dict -}}
+{{- $creds = sopsDecrypt "dot_config/credentials.sops.yaml" | fromYaml }}
+export DB_PASSWORD="{{ $creds.database.password }}"
+```
+
+## Step 5: Commit and Verify
+
+```sh
+cd ~/.dotfiles
+git add .sops.yaml dot_config/credentials.sops.yaml dot_tmp/stripe-key.txt.age
+git commit -sS -m "feat(secrets): add stripe and database credentials"
+git push
+```
+
+Verify the commit doesn't leak secrets:
+
+```sh
+git log -p HEAD~1..HEAD | grep -v ENC | grep -iE 'password|secret|key' || echo "Clean"
+```
+
+On the next machine:
+
+```sh
+dot update
+# Chezmoi decrypts using that machine's Age key
+# If decryption fails, the template errors with a clear message
+```
+
+## Step 6: Multi-Recipient (Fleet)
+
+To allow multiple hosts to decrypt the same secret, add more recipients:
+
+```yaml
+# .sops.yaml
+creation_rules:
+  - path_regex: \.sops\.yaml$
+    age: >-
+      age1qy90l...xyz,
+      age1z2x33...abc,
+      age1mm0kk...def
+```
+
+Re-encrypt the affected files:
+
+```sh
+sops updatekeys dot_config/credentials.sops.yaml
+```
+
+Now any host with one of those three private keys can decrypt. Hosts without any matching key see the encrypted file but cannot read it.
+
+## Step 7: Rotate a Compromised Key
+
+```sh
+# 1. Generate a new Age key on the affected host
+age-keygen -o ~/.config/age/keys.txt.new
+mv ~/.config/age/keys.txt.new ~/.config/age/keys.txt
+
+# 2. Update .sops.yaml with the new public key
+
+# 3. Re-encrypt all SOPS files with the new recipient list
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+
+# 4. Commit and push
+git add .sops.yaml dot_config/*.sops.yaml
+git commit -sS -m "chore(secrets): rotate Age key"
+
+# 5. On other fleet hosts
+dot update
+```
+
+Old key still works for existing ciphertext, but new secrets use the new key. To force deprecation, delete the old key from `.sops.yaml` and `sops updatekeys` all files.
+
+## Verifying No Plaintext Leaks
+
+CI runs three secret scanners (`gitleaks`, `detect-secrets`, `trufflehog`) on every commit. You can run them locally:
+
+```sh
+gitleaks detect --redact --source .
+detect-secrets scan --update .secrets.baseline
+trufflehog git file://. --only-verified
+```
+
+If any scanner finds a potential leak, the commit is blocked.
+
+## Operational Rules
+
+1. **Never commit plaintext secrets** — use chezmoi encrypt or SOPS
+2. **Never commit `~/.config/age/keys.txt`** — it's gitignored; double-check before pushing
+3. **Age keys are per-host** — don't copy them via Git; use secure channels (1Password, Bitwarden, physical USB)
+4. **Rotate on team membership changes** — when someone leaves, update recipients and rotate all shared secrets
+5. **Audit with `dot verify --security`** — runs gitleaks + signature + policy hash checks
+
+## Troubleshooting
+
+### "Could not decrypt: no age key found"
+
+`~/.config/age/keys.txt` is missing or unreadable:
+
+```sh
+chmod 600 ~/.config/age/keys.txt
+ls -la ~/.config/age/keys.txt
+# -rw------- 1 user user 189 Apr 16 09:00 keys.txt
+```
+
+### "sops: file encrypted with outdated recipients"
+
+A secret file has an old recipient list. Fix:
+
+```sh
+sops updatekeys path/to/file.sops.yaml
+```
+
+### Secrets Not Applying After Apply
+
+Check that `dot_tmp/stripe-key.txt.age` is committed. Run:
+
+```sh
+chezmoi apply --verbose dot_tmp/stripe-key.txt
+# Will show decrypt attempts and errors
+```
+
+## Next
+
+- [Concept: Trust Model](../01-concepts/02-trust-model.md) — the security architecture
+- [Reference: Secret operations](../03-reference/01-dot-cli.md#secrets)
+- [Security: Secret management](../../security/SECRETS.md)

package/docs/manual/02-tutorials/05-deploy-fleet.md

@@ -0,0 +1,279 @@
+# Tutorial: Deploy to a Fleet
+
+Roll out `.dotfiles` across multiple workstations and verify they're in sync.
+
+## Scenario
+
+You have three hosts:
+
+- **macbook-t2** — your MacBook (current host, already installed)
+- **surface-pro** — your Linux laptop (new install)
+- **geekom-a9** — your desktop NUC (new install)
+
+Goal: all three running identical `.dotfiles` with per-host customization, with auditable cross-host attestation.
+
+## Step 1: Per-Host Install
+
+On each new host:
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+During `chezmoi init`, answer with the host's preset:
+
+- Surface Pro → `machine = "surface-pro"`
+- Geekom A9 → `machine = "geekom-a9"`
+
+## Step 2: Exchange Signing Keys
+
+Each host has its own SSH ED25519 key. To verify commits and attestations across the fleet, publish each host's public key to every other host.
+
+**On each host, copy the public key:**
+
+```sh
+cat ~/.ssh/id_ed25519.pub
+# ssh-ed25519 AAAAC3N...jkl5 user@macbook-t2
+```
+
+**Collect all three keys. Append them to `~/.ssh/allowed_signers` on every host:**
+
+```
+user@macbook-t2 ssh-ed25519 AAAAC3N...jkl5
+user@surface-pro ssh-ed25519 AAAAC3N...abc7
+user@geekom-a9 ssh-ed25519 AAAAC3N...def9
+```
+
+Optionally commit `allowed_signers` as a template so all hosts receive updates via `dot update`:
+
+```sh
+# On macbook-t2
+chezmoi add ~/.ssh/allowed_signers
+git add -A && git commit -sS -m "feat(ssh): add fleet signing keys"
+git push
+```
+
+Now every other host gets the updated list on `dot update`.
+
+## Step 3: Share the Age Key (for Shared Secrets)
+
+If you want shared secrets decrypted on all three hosts, each host must have an Age key recipient in `.sops.yaml`.
+
+Option A: Share one key across all hosts (simpler, less granular).
+Option B: Each host has its own key; all three are listed as recipients (better operational security).
+
+For Option B:
+
+```sh
+# On macbook-t2 (already set up)
+grep "public key:" ~/.config/age/keys.txt
+
+# On surface-pro
+age-keygen -o ~/.config/age/keys.txt
+grep "public key:" ~/.config/age/keys.txt
+
+# On geekom-a9
+age-keygen -o ~/.config/age/keys.txt
+grep "public key:" ~/.config/age/keys.txt
+```
+
+Add all three public keys to `.sops.yaml`:
+
+```yaml
+creation_rules:
+  - path_regex: \.sops\.yaml$
+    age: >-
+      age1aaa...111,    # macbook-t2
+      age1bbb...222,    # surface-pro
+      age1ccc...333     # geekom-a9
+```
+
+Re-encrypt existing secrets for the new recipients:
+
+```sh
+# On macbook-t2
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+git add .sops.yaml dot_config/*.sops.yaml
+git commit -sS -m "chore(secrets): add fleet recipients"
+git push
+```
+
+Other hosts on `dot update` decrypt with their own private key automatically.
+
+## Step 4: Verify Fleet Alignment
+
+From any host:
+
+```sh
+dot fleet attest
+```
+
+Expected output:
+
+```
+Fleet Attestation — v0.2.500
+
+Host           Git SHA    Policy    Tools OK   Drift   Verified
+-------------- ---------- --------- ---------- ------- --------
+macbook-t2     abc123d    0x7f2a…   ✓          0       ✓
+surface-pro    abc123d    0x7f2a…   ✓          0       ✓
+geekom-a9      abc123d    0x7f2a…   ✓          0       ✓
+-------------- ---------- --------- ---------- ------- --------
+FLEET STATUS: 3/3 aligned
+```
+
+If any row shows drift or missing verification:
+
+```sh
+# Check which host is out of sync
+dot fleet diff
+
+# SSH into the affected host and fix
+ssh surface-pro
+dot doctor && dot heal
+dot update
+```
+
+## Step 5: Per-Host Customization
+
+Each host has its own `~/.config/chezmoi/chezmoi.toml` — use it for things that shouldn't propagate:
+
+```toml
+# surface-pro's chezmoi.toml
+[data]
+machine = "surface-pro"
+theme = "dome-dark"           # per-host default
+default_shell = "fish"
+terminal_font_size = 11       # smaller for HiDPI
+```
+
+```toml
+# geekom-a9's chezmoi.toml
+[data]
+machine = "geekom-a9"
+theme = "valley-dark"         # different default
+default_shell = "zsh"
+terminal_font_size = 14       # larger for external 1440p
+```
+
+Both hosts render from the same templates, producing correct platform-appropriate output.
+
+## Step 6: Fleet-Wide Updates
+
+When you push a commit to master, each host pulls independently:
+
+```sh
+# On each host
+dot update
+```
+
+`dot update` does:
+
+1. `git pull --rebase --autostash` in `~/.dotfiles`
+2. `chezmoi apply` with progress output
+3. `dot heal` if apply detected drift
+4. Reports changes applied
+
+For simultaneous update across the fleet (requires SSH):
+
+```sh
+dot fleet sync
+# Connects to each host in parallel
+# Runs `dot update` via SSH
+# Collects outcomes
+```
+
+## Step 7: Secrets Rotation
+
+When a secret is compromised (or as part of routine rotation):
+
+```sh
+# 1. Edit the secret on any host
+sops dot_config/credentials.sops.yaml
+# Change the compromised value, save
+
+# 2. Commit and push
+git commit -sS -am "chore(secrets): rotate stripe key"
+git push
+
+# 3. All fleet hosts pick up the new value on next update
+# On each host:
+dot update
+```
+
+Since hosts all have the Age private key for themselves, decryption is automatic.
+
+## Step 8: Decommission a Host
+
+When retiring a host:
+
+```sh
+# 1. Remove the host's public key from allowed_signers
+# Edit dot_ssh/allowed_signers.tmpl (on any host)
+
+# 2. Remove the host's Age public key from .sops.yaml
+
+# 3. Re-encrypt all SOPS files (remove the decommissioned recipient)
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+
+# 4. Commit
+git commit -sS -am "chore(fleet): decommission geekom-a9"
+git push
+
+# 5. On the decommissioned host: wipe the dotfiles state
+rm -rf ~/.dotfiles ~/.local/bin/dot ~/.config/chezmoi ~/.config/age
+```
+
+## Troubleshooting
+
+### "Fleet host unreachable"
+
+`dot fleet` couldn't SSH to a host. Check:
+
+```sh
+ssh surface-pro 'dot version'
+# If this fails, fix SSH connectivity first
+```
+
+### Drift on One Host
+
+Run `dot heal` on that host:
+
+```sh
+ssh surface-pro 'dot heal'
+```
+
+If drift persists:
+
+```sh
+ssh surface-pro 'chezmoi diff | head -50'
+# Inspect what's different
+```
+
+### Policy Hash Mismatch
+
+One host has an older policy than the others. Usually means that host missed an update:
+
+```sh
+ssh surface-pro 'dot update'
+```
+
+### Attestation Signature Failed
+
+The host's SSH key isn't in `~/.ssh/allowed_signers` on the verifying host. Fix by redistributing `allowed_signers`.
+
+## Summary
+
+A three-host fleet:
+
+- Installs from one repository
+- Has independent signing keys (each host verifies commits from others)
+- Can share secrets across specific hosts via SOPS recipients
+- Is auditable via `dot fleet attest`
+- Updates independently with `dot update` (or in parallel with `dot fleet sync`)
+
+## Next
+
+- [Concept: Fleet Architecture](../01-concepts/04-fleet.md)
+- [Reference: Fleet Commands](../03-reference/01-dot-cli.md#fleet)
+- [Operations: Fleet Deployment](../../architecture/fleet-deployment.md)