@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/security/KEY_ROTATION.md

@@ -0,0 +1,219 @@
+# Key Rotation Guide
+
+This guide covers rotating encryption keys for secrets managed by Age and SOPS.
+
+## Age Key Rotation
+
+### When to Rotate
+
+- **Annually**: As a preventive measure
+- **After compromise**: If you suspect key exposure
+- **Personnel change**: When team members leave
+- **Device loss**: If a device with the key is lost/stolen
+
+### Rotation Procedure
+
+#### 1. Generate New Key
+
+```bash
+# Create new age key
+age-keygen -o ~/.config/chezmoi/key-new.txt
+
+# Note the public key (starts with "age1...")
+cat ~/.config/chezmoi/key-new.txt | grep "public key"
+```
+
+#### 2. Re-encrypt All Secrets
+
+```bash
+# List all encrypted files
+chezmoi managed --include=encrypted
+
+# For each encrypted file, decrypt with old key and re-encrypt with new
+for file in $(chezmoi managed --include=encrypted); do
+  # Decrypt with old key
+  chezmoi cat "$file" > "/tmp/$(basename $file).dec"
+
+  # Re-encrypt with new key (update chezmoi config first)
+  # See step 3
+done
+```
+
+#### 3. Update Chezmoi Configuration
+
+Edit `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[age]
+  identity = "~/.config/chezmoi/key-new.txt"
+  recipient = "age1your_new_public_key_here"
+```
+
+#### 4. Re-add Encrypted Files
+
+```bash
+# Re-add each secret with new encryption
+chezmoi add --encrypt ~/.ssh/id_ed25519
+chezmoi add --encrypt ~/.config/secrets/api-keys.env
+```
+
+#### 5. Verify and Clean Up
+
+```bash
+# Verify decryption works
+chezmoi cat ~/.ssh/id_ed25519
+
+# Archive old key (store securely offline)
+mv ~/.config/chezmoi/key.txt ~/.config/chezmoi/key-$(date +%Y%m%d)-archived.txt
+
+# Rename new key
+mv ~/.config/chezmoi/key-new.txt ~/.config/chezmoi/key.txt
+
+# Commit changes
+cd ~/.dotfiles
+git add -A
+git commit -m "chore(secrets): rotate age encryption key"
+```
+
+### Emergency Rotation (Compromised Key)
+
+```bash
+# 1. Immediately generate new key
+age-keygen -o ~/.config/chezmoi/key-emergency.txt
+
+# 2. Re-encrypt ALL secrets (prioritize most sensitive)
+# 3. Revoke/rotate any API keys, tokens that were encrypted
+# 4. Update any shared secrets with team members
+# 5. Document the incident
+```
+
+---
+
+## SOPS Key Rotation
+
+### Overview
+
+SOPS supports multiple key types. This covers Age keys (recommended) and GPG keys.
+
+### SOPS with Age Keys
+
+#### Generate New Key
+
+```bash
+age-keygen -o ~/.config/sops/age/keys-new.txt
+```
+
+#### Update .sops.yaml
+
+```yaml
+creation_rules:
+  - path_regex: \.env$
+    age: >-
+      age1new_key_here,
+      age1old_key_here  # Keep old key temporarily for decryption
+```
+
+#### Re-encrypt Files
+
+```bash
+# Rotate key for a single file
+sops updatekeys secrets.env
+
+# Or re-encrypt entirely
+sops -d secrets.env | sops -e /dev/stdin > secrets.env.new
+mv secrets.env.new secrets.env
+```
+
+#### Remove Old Key
+
+After confirming all files are re-encrypted:
+
+1. Remove old key from `.sops.yaml`
+2. Archive old key securely
+3. Commit changes
+
+### SOPS with GPG Keys
+
+```bash
+# Generate new GPG key
+gpg --full-generate-key
+
+# Export fingerprint
+gpg --list-keys --keyid-format LONG
+
+# Update .sops.yaml with new fingerprint
+# Re-encrypt files
+sops updatekeys <file>
+```
+
+---
+
+## Automation Scripts
+
+### Check Key Age
+
+```bash
+#!/usr/bin/env bash
+# check-key-age.sh - Alert if keys are older than 365 days
+
+KEY_FILE="${HOME}/.config/chezmoi/key.txt"
+MAX_AGE_DAYS=365
+
+if [[ -f "$KEY_FILE" ]]; then
+  key_age=$(( ($(date +%s) - $(stat -c %Y "$KEY_FILE")) / 86400 ))
+
+  if [[ $key_age -gt $MAX_AGE_DAYS ]]; then
+    echo "⚠️  Age key is ${key_age} days old. Consider rotation."
+    exit 1
+  else
+    echo "✓ Age key is ${key_age} days old (limit: ${MAX_AGE_DAYS})"
+  fi
+fi
+```
+
+### Automated Backup Before Rotation
+
+```bash
+#!/usr/bin/env bash
+# backup-before-rotation.sh
+
+BACKUP_DIR="${HOME}/.local/share/dotfiles/key-backups"
+mkdir -p "$BACKUP_DIR"
+
+# Backup current key
+cp ~/.config/chezmoi/key.txt "$BACKUP_DIR/key-$(date +%Y%m%d_%H%M%S).txt"
+
+# Encrypt backup with passphrase
+gpg --symmetric --cipher-algo AES256 "$BACKUP_DIR/key-$(date +%Y%m%d_%H%M%S).txt"
+
+# Remove unencrypted backup
+rm "$BACKUP_DIR/key-$(date +%Y%m%d_%H%M%S).txt"
+
+echo "Key backed up to $BACKUP_DIR (encrypted)"
+```
+
+---
+
+## Best Practices
+
+1. **Never commit unencrypted keys** - Use `.gitignore` properly
+2. **Store backups offline** - USB drive in secure location
+3. **Use hardware keys when possible** - YubiKey with age-plugin-yubikey
+4. **Document rotation dates** - Keep a log of when keys were rotated
+5. **Test decryption** - Always verify after rotation
+6. **Notify team members** - If using shared secrets
+
+## Recovery Procedures
+
+If you lose access to your key:
+
+1. **Check backups** - Offline storage, password manager
+2. **Check other machines** - Key may exist on another device
+3. **Re-create secrets** - As last resort, regenerate API keys, tokens, etc.
+
+## Related Documentation
+
+- [SECRETS.md](SECRETS.md) - Secrets management overview
+- [SECURITY.md](SECURITY.md) - Security hardening guide
+- [Age documentation](https://github.com/FiloSottile/age)
+- [SOPS documentation](https://github.com/getsops/sops)

package/docs/security/MCP_POLICY.md

@@ -0,0 +1,69 @@
+# MCP Policy
+
+MCP is treated as a controlled execution boundary.
+
+## Default posture
+
+The tracked default is `strict-local`.
+
+Properties:
+- local-first
+- least privilege
+- no broad filesystem roots
+- no wildcard or unsafe flags
+- no network-facing MCP servers enabled by default
+- machine-readable validation output
+
+## Policy artifact
+
+The source of truth lives in [mcp-policy.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-policy.json).
+Approved package pins live in [mcp-lock.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-lock.json).
+Tracked server registry entries live in [mcp-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-registry.json).
+
+Current defaults:
+- Allowed launchers: `npx`, `node`, `uvx`
+- Trusted transports: `stdio`, `http`
+- Blocked filesystem roots: `/`, `/home`, `/Users`
+- Blocked argument patterns: `^--allow-.*`, `^--unsafe$`, `^\\*$`
+- Network-facing servers disabled by default: `github`, `brave-search`, `fetch`, `puppeteer`, `filesystem`
+- Approved packages must resolve through the tracked MCP lock manifest
+- Every active server must match the tracked MCP registry
+- HTTP transports must use `https://` and registry-declared OAuth2
+
+## Validation
+
+Run:
+
+```bash
+dot mcp --strict
+dot mcp -s -j
+dot mcp registry
+```
+
+The JSON form is the audit artifact for CI, release validation, and workstation attestation.
+
+## Change control
+
+Any change to MCP policy requires:
+1. A signed commit
+2. A matching test update
+3. A release note if the effective trust boundary changes
+4. A policy bundle review when enterprise defaults change
+
+## Supply-chain controls
+
+Phase 2 adds explicit package locking for default MCP servers.
+
+Current approved refs:
+- `mcp-server-git@2025.1.14`
+- `@modelcontextprotocol/server-memory@2025.8.4`
+- `mcp-server-sqlite@2025.1.14`
+
+`dot mcp --strict` and `dot mcp -s` now verify that:
+- package refs are version-pinned
+- the pinned refs match the tracked lock manifest
+- non-approved package refs are rejected in strict mode
+- active servers match the tracked registry entries
+- remote HTTP transports are HTTPS and OAuth-backed
+
+Policy bundle baselines live in [policy-bundles.json](/home/seb/.dotfiles/dot_config/dotfiles/policy-bundles.json).

package/docs/security/POLICY_RELEASES.md

@@ -0,0 +1,33 @@
+# Policy Bundle Releases
+
+Policy bundles are released as tracked governance artifacts.
+
+They include:
+
+- policy bundles
+- model registry
+- prompt registry
+- agent profiles
+- agent card
+- MCP policy, registry, and lock
+- A2A discovery metadata
+
+## Local packaging
+
+```bash
+bash scripts/release/package-policy-bundles.sh --version 2026.03
+bash scripts/release/package-policy-bundles.sh --json
+```
+
+## Release workflow
+
+Use the `Policy Bundle Release` workflow.
+
+Release controls:
+
+- source ref must be signed
+- governance JSON must validate with `jq`
+- bundle archive gets a SHA-256 checksum
+- bundle archive gets GitHub provenance attestation
+
+Signed commits remain mandatory for any policy change.

package/docs/security/README.md

@@ -0,0 +1,24 @@
+# Security Documentation
+
+This directory contains security documentation for the dotfiles project.
+
+## Index
+
+| Document | Description |
+|----------|-------------|
+| [SECURITY.md](SECURITY.md) | Core security model and opt-in hardening |
+| [THREAT_MODEL.md](THREAT_MODEL.md) | Threat analysis with trust boundaries |
+| [SECRETS.md](SECRETS.md) | Secrets management (Age, SOPS, Keychain) |
+| [KEY_ROTATION.md](KEY_ROTATION.md) | Key rotation procedures |
+| [KEYS.md](KEYS.md) | Keybindings reference |
+| [COMPLIANCE.md](COMPLIANCE.md) | SOC 2, ISO 27001, GDPR, HIPAA mapping |
+| [AI_ACT_COMPLIANCE.md](AI_ACT_COMPLIANCE.md) | EU AI Act risk classification and exemption analysis |
+| [SECURITY_CHECKLIST.md](SECURITY_CHECKLIST.md) | Pre-release security verification |
+
+## Quick Reference
+
+- **Encryption:** Age + SOPS for secrets at rest
+- **Signing:** SSH ED25519 commit signing enforced
+- **Scanning:** Gitleaks pre-commit hook prevents credential leaks
+- **Telemetry:** Disabled by default, no data leaves your machine
+- **Hardening:** Opt-in firewall, DNS-over-HTTPS, lock-screen, USB safety

package/docs/security/SECRETS.md

@@ -0,0 +1,146 @@
+# Secrets Management
+
+Provider-agnostic secrets via `dot secrets`. Supports macOS Keychain, `pass`, and age-encrypted local storage.
+
+## Providers
+
+Provider selection is controlled by `.chezmoidata.toml`:
+
+```toml
+[secrets.policy]
+provider = "auto"     # auto | macos-keychain | pass | plain-enc
+auto_load = true
+
+[secrets.buckets]
+ai = ["GEMINI_API_KEY", "CLAUDE_API_KEY", "OPENAI_API_KEY"]
+infra = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "GITHUB_TOKEN"]
+```
+
+`auto` resolves in this order:
+1. `macos-keychain` on macOS
+2. `pass` when available
+3. `plain-enc` fallback (age-encrypted local store)
+
+## Commands
+
+```bash
+# Bootstrap age key for chezmoi encrypted files
+dot secrets-init
+
+# Optional: create encrypted secrets file for chezmoi
+dot secrets-create
+dot secrets edit
+
+# Managed secret store
+dot secrets set GEMINI_API_KEY
+dot secrets get GEMINI_API_KEY --raw
+dot secrets list
+dot secrets provider
+
+# Emit export lines for a bucket
+dot secrets load ai
+
+# Load into current shell session
+eval "$(dot env load ai)"
+```
+
+## Shell Auto-Load
+
+When `auto_load = true`, shell startup can load configured buckets automatically via `dot env load <bucket>`.
+
+Environment toggles:
+- `DOTFILES_SECRETS_PROVIDER`
+- `DOTFILES_SECRETS_AUTO_LOAD`
+- `DOTFILES_SECRETS_BUCKET_NAMES`
+
+## Governance
+
+A pre-commit hook runs:
+
+```bash
+scripts/diagnostics/secret-governance.sh
+```
+
+It blocks staged commits when likely secret patterns are found. In strict mode it also blocks exact matches against managed secret values.
+
+## SSH Key Encryption
+
+```bash
+dot ssh-key ~/.ssh/id_ed25519
+```
+
+This creates a local encrypted file, which you can add to chezmoi with `chezmoi add --encrypt` if needed.
+
+## External Secrets Backends
+
+Chezmoi natively supports external secret managers as template functions. Configure the backend in `.chezmoidata.toml`:
+
+```toml
+secrets_backend = "age"  # age, 1password, bitwarden, pass, vault
+```
+
+### 1Password
+
+Requires the [1Password CLI](https://developer.1password.com/docs/cli/) (`op`).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "1password"
+```
+
+Use in templates:
+```text
+{{ onepassword "my-secret" "vault-name" }}
+{{ onepasswordRead "op://vault/item/field" }}
+```
+
+### Bitwarden
+
+Requires the [Bitwarden CLI](https://bitwarden.com/help/cli/) (`bw`).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "bitwarden"
+```
+
+Use in templates:
+```text
+{{ bitwarden "item" "my-login" }}
+{{ bitwardenFields "item" "my-login" }}
+```
+
+### HashiCorp Vault
+
+Requires the [Vault CLI](https://developer.hashicorp.com/vault/docs/commands) (`vault`).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "vault"
+```
+
+Use in templates:
+```text
+{{ vault "secret/data/my-secret" }}
+```
+
+### pass (Password Store)
+
+Requires [pass](https://www.passwordstore.org/).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "pass"
+```
+
+Use in templates:
+```text
+{{ pass "my-secret" }}
+```
+
+See the [chezmoi documentation](https://www.chezmoi.io/user-guide/password-managers/) for full details on each backend.
+
+## Security Notes
+
+- **Never commit** `~/.config/chezmoi/key.txt` to version control.
+- **Avoid shell history exposure** — use `dot secrets set` which prompts securely.
+- **Rotate credentials** on a regular schedule.

package/docs/security/SECURITY.md

@@ -0,0 +1,41 @@
+# Security
+
+How dotfiles handles security and system modifications.
+
+## Core Principles
+
+- **Opt-In Only** — No hardening applies unless `DOTFILES_*` variables are set to `1`.
+- **Local Logging** — All actions log to `~/.local/share/dotfiles.log`. No telemetry.
+- **No Hidden Sudo** — Sudo requests only for package managers. Never cached indefinitely.
+
+## Hardening
+
+| Feature | Env Var | Action (macOS) | Action (Linux) |
+|---|---|---|---|
+| Firewall | `DOTFILES_FIREWALL` | Enables `socketfilterfw` + Stealth Mode | Configures UFW |
+| Telemetry | `DOTFILES_TELEMETRY` | Disables Diagnostic plists | Disables `whoopsie`/`apport` |
+| DNS-over-HTTPS | `DOTFILES_DOH` | Browser-level settings | Configures `resolvectl` |
+| Idle Security | `DOTFILES_LOCK` | Sets screensaver idle time | Sets GNOME/KDE idle-delay |
+
+## Secrets
+
+The dotfiles use **age** for encryption.
+
+- **Initialization**: `dot secrets-init` creates a key at `~/.config/chezmoi/key.txt`.
+- **Storage**: Secrets are stored as `.age` encrypted files.
+- **Protection**: Private keys aren't committed to the repo.
+
+## SSH Certificates
+
+Short-lived SSH certificates reduce the blast radius of key compromise.
+
+- **Issue**: `dot ssh-cert issue [--ttl 16h] [--principal user]`
+- **Status**: `dot ssh-cert status` — checks certificate validity and expiry
+- **Revoke**: `dot ssh-cert revoke` — revokes active certificates
+- **Backends**: `step-ca` (Smallstep) and local CA key (`ssh-keygen`)
+- **Default TTL**: 16 hours (override via `SSH_CERT_TTL` environment variable)
+- **CA URL**: Set `SSH_CERT_CA_URL` for `step-ca` integration
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, don't open a public issue. Follow the instructions in the Security Policy.

package/docs/security/SECURITY_CHECKLIST.md

@@ -0,0 +1,44 @@
+# Security Release Checklist
+
+Use this checklist before cutting any new release (e.g., `v0.x.x`) to ensure supply-chain integrity.
+
+## 1. Supply Chain & Installer
+- [ ] **Pinned Version**: Update `install.sh` `VERSION` variable to match the release tag.
+- [ ] **Docs Sync**: Ensure `README.md` and `.github/PULL_REQUEST_TEMPLATE.md` installer URLs point to the new tag (not `main`).
+- [ ] **Clean Build**: Verify `install.sh` does not curl random scripts from third parties without pinning.
+- [ ] **SOUP Register**: Review [SOUP_REGISTER.md](/home/seb/.dotfiles/docs/security/SOUP_REGISTER.md) and confirm all active external components have an owner and validation path.
+
+## 2. Secrets & Leak Prevention
+- [ ] **SSH Keys**: Scan `dot_ssh/` to ensure no private keys (`id_rsa`, `id_ed25519`) are committed.
+- [ ] **Env Vars**: Check for hardcoded API tokens in `dot_config/` (use `age` encryption or environment variables instead).
+- [ ] **Git History**: Run `git secrets` or similar to scan for accidental commits of credentials.
+
+## 3. Platform Safety
+- [ ] **WSL Check**: Verify `install.sh` detects WSL and does not try to install systemd services or macOS defaults.
+- [ ] **Root usage**: Ensure no script requires `sudo` unnecessarily (Principle of Least Privilege).
+
+## 4. Toolchain
+- [ ] **Binary Integrity**: Check that `dot_local/bin/` scripts are pure shell/executable and match expected checksums (no binary blobs).
+- [ ] **Dependency Scan**: Run `npm audit` / `cargo audit` if applicable (currently Node.js legacy is removed).
+
+## 5. MCP (Model Context Protocol) Hardening
+- [ ] **Launcher Policy**: Verify `dot mcp` shows only allowlisted launchers (`npx`, `node`, `uvx`).
+- [ ] **Filesystem Scope**: Ensure no MCP server has broad access (`/`, `/home`, `/Users`).
+- [ ] **Default Profile**: Confirm only the `strict-local` server set is enabled by default.
+- [ ] **Token Validation**: Confirm required API tokens are set (`GITHUB_TOKEN`, `BRAVE_API_KEY`).
+- [ ] **Arg Policy**: No wildcard (`*`) or `--unsafe` arguments in MCP server configs.
+- [ ] **Env Placeholders**: All `${VAR}` references in MCP config have corresponding environment variables.
+
+Run `dot mcp --strict --json` to validate all MCP server configurations and capture an audit artifact.
+
+## 6. Release Attestation
+- [ ] **SBOM Generation**: Verify `dotfiles-sbom.spdx.json` is generated in release workflow.
+- [ ] **Attestation Signing**: Confirm `actions/attest-build-provenance` signs the release artifacts.
+- [ ] **Attestation Verification**: Verify with `gh attestation verify <artifact> --repo sebastienrousseau/dotfiles`.
+- [ ] **Branch Protection**: Ensure `security-attestation` is a required status check on master.
+- [ ] **Automation Keying**: Confirm `ACTIONS_BOT_SIGNING_KEY` exists and matches the signer in `dot_config/git/allowed_signers`.
+
+## 7. Final Verification
+- [ ] **Docker Test**: Run `docker build -f Dockerfile.test .` to verify clean install.
+- [ ] **Doctor**: Run `dot doctor` locally.
+- [ ] **MCP Check**: Run `dot mcp` to verify MCP configuration.

package/docs/security/SOUP_REGISTER.md

@@ -0,0 +1,32 @@
+# SOUP Register
+
+## Purpose
+
+Controlled inventory for software of unknown pedigree used by the dotfiles platform.
+
+## Active components
+
+| Component | Source | Version control | Verification path | Owner | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| Homebrew installer | `raw.githubusercontent.com/Homebrew/install` | Moving upstream script, gated by `HOMEBREW_INSTALLER_SHA256` | SHA-256 in [package_managers.sh](/home/seb/.dotfiles/install/lib/package_managers.sh) | Repo maintainer | Conditional |
+| Chezmoi installer | `get.chezmoi.io` | Pinned by `CHEZMOI_INSTALLER_SHA256` when used | SHA-256 in `install/lib/chezmoi.sh` | Repo maintainer | Controlled |
+| GitHub Actions marketplace actions | GitHub Marketplace | Full commit SHA pinning | Workflow `uses:` pins | Repo maintainer | Controlled |
+| Grype container | `anchore/grype` | Pinned tag in workflow | Container tag in [security-enhanced.yml](/home/seb/.dotfiles/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
+| Trivy container | `aquasec/trivy` | Pinned tag in workflow | Container tag in [security-enhanced.yml](/home/seb/.dotfiles/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
+| Checkov action | GitHub Marketplace | Full commit SHA pinning | Workflow `uses:` pin | Repo maintainer | Controlled |
+| Nix inputs | GitHub flakes | Locked in [flake.lock](/home/seb/.dotfiles/flake.lock) | `narHash` and revision lock | Repo maintainer | Controlled |
+| GitHub release metadata queries | GitHub API | Discovery only, not release validation | `update-deps.yml` query path | Repo maintainer | Monitored |
+
+## Validation record
+
+1. Record version or commit SHA.
+2. Record checksum, signature, or attestation method.
+3. Record workflow or script that consumes the component.
+4. Record owner and review date.
+5. Reject moving inputs in production or release paths unless checksum-gated.
+
+## Exit criteria
+
+- No unsigned automation commits.
+- No unverified executable download in installer or release path.
+- Every SOUP item has owner, version control method, and validation record.