@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

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

@@ -1,281 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# 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)
-{% endraw %}

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

@@ -1,283 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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/main/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.501
-
-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 = "monterey-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 main, 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)