@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/security/KEYS.md

@@ -0,0 +1,49 @@
+---
+render_with_liquid: false
+---
+
+# Keybindings
+
+This is the single source of truth for navigation and muscle-memory shortcuts
+across the dotfiles stack. Keep it concise and consistent.
+
+## Zsh
+
+- `Ctrl+R`: History search (`fzf`/`atuin` if enabled)
+- `Ctrl+P` / `Ctrl+N`: History prefix search (up/down)
+
+## Tmux (prefix = `Ctrl-a`)
+
+- `Prefix + r`: Reload config
+- `Prefix + N`: New window
+- `Prefix + a` / `Tab`: Last window
+- `Prefix + %`: Split vertical (current path)
+- `Prefix + "`: Split horizontal (current path)
+- `Prefix + \`: Split vertical (alt)
+- `Prefix + |`: Split horizontal (alt)
+- `Prefix + h/j/k/l`: Move between panes (vim-style)
+- `Prefix + z`: Toggle zoom pane
+- `Prefix + H/J/K/L`: Resize pane (left/down/up/right)
+
+## Neovim (leader = `Space`)
+
+- `Ctrl-h/j/k/l`: Move between splits
+- `Ctrl-s`: Save file
+- `Leader + ff`: Find files (Telescope)
+- `Leader + fg`: Live grep (Telescope)
+- `Leader + q`: Quit
+
+## Shell Tools
+
+- `z <dir>`: Jump to a directory (`zoxide`)
+- `lg`: Open `lazygit`
+
+## Terminal
+
+- `Ctrl+Shift+C`: Copy
+- `Ctrl+Shift+V`: Paste
+
+---
+
+Update this file when bindings change. If you add a new tool, add its shortcuts
+here and keep them aligned with the global conventions.

package/docs/security/KEY_ROTATION.md

@@ -0,0 +1,223 @@
+---
+render_with_liquid: false
+---
+
+# 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,78 @@
+---
+render_with_liquid: false
+---
+
+# 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,37 @@
+---
+render_with_liquid: false
+---
+
+# 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,28 @@
+---
+render_with_liquid: false
+---
+
+# 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/SCORECARD.md

@@ -0,0 +1,80 @@
+---
+render_with_liquid: false
+---
+
+# OpenSSF Scorecard
+
+This page records the current OpenSSF Scorecard posture for this
+repository, the known gaps, and the remediation roadmap. The badge in
+the README links to the live result; this page is the maintained
+narrative behind it.
+
+## Live score
+
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sebastienrousseau/dotfiles/badge)](https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles)
+
+The badge above is regenerated every Monday at 06:00 UTC and on every
+push to `master` by `.github/workflows/scorecard.yml`. The SARIF
+result is uploaded to GitHub Code Scanning (Security tab) and
+retained as a 30-day workflow artifact.
+
+## Threshold policy
+
+| Score | Action |
+|---|---|
+| ≥ 8.0 | Healthy. Keep doing what we're doing. |
+| 7.0 – 7.9 | Acceptable. Tracked. |
+| < 7.0 | Regression — the workflow auto-opens a tracking issue labelled `type:security + priority:high`. |
+
+Regressions are triaged within one Monday cycle: identify the check
+that dropped, either remediate or file an exception entry below with
+a rationale and an expiry date.
+
+## Per-check posture (snapshot)
+
+The checks below come from OpenSSF Scorecard's published rubric. Tick
+marks reflect this repo's posture at the time of writing — the
+*live* badge is authoritative if these diverge.
+
+| Check | Status | Notes |
+|---|---|---|
+| Branch-Protection | ✓ | `master` requires signed commits, linear history, required checks. Codified at `.github/rulesets/master.json` and `.github/branch-protection-config.json`. |
+| Code-Review | ✓ | Every PR requires at least one approval; CODEOWNERS in place. |
+| Signed-Commits | ✓ | Enforced by pre-push hook (`scripts/git-hooks/pre-push`) and at-push by branch protection (#853 + #857). |
+| Dependency-Update-Tool | ✓ | Dependabot configured for github-actions / npm / docker / devcontainers / uv. |
+| Fuzzing | ⚠ | `install.sh` fuzz harness lives under `tests/fuzz/` (closes #881). Coverage is the script's CLI surface plus chaos input fixtures — not full corpus fuzzing yet. |
+| License | ✓ | Apache-2.0 at repo root. |
+| Maintained | ✓ | Active commit cadence; the [README](../../README.md) lists the current `dotfiles_version` (v0.2.501). |
+| Pinned-Dependencies | ✓ | Every workflow action is pinned to a 40-char commit SHA; the lint rule under `actionlint` enforces this on PR. |
+| SAST | ✓ | CodeQL (`.github/workflows/codeql.yml`) + Checkov + Grype. |
+| SBOM | ✓ | Generated per PR by `sbom-diff.yml` and per release by `security-release.yml`. |
+| Security-Policy | ✓ | `.github/SECURITY.md` + this page + `docs/security/THREAT_MODEL.md`. |
+| Token-Permissions | ✓ | Workflows use least-privilege `permissions:` blocks. `harden-runner` adoption (#878) tightens this further. |
+| Vulnerabilities | ✓ | Grype gate hard-fails on `high` / `critical` on `master` (#852). |
+| Webhooks | n/a | No external webhooks configured. |
+| CI-Tests | ✓ | Comprehensive CI matrix (Linux + macOS Intel + Apple Silicon, optional Windows). |
+| CII-Best-Practices | ☐ | Not applied yet — see "Open work" below. |
+| Dangerous-Workflow | ✓ | No `pull_request_target` with checkout-PR-code anti-pattern. |
+| Packaging | ✓ | `npm publish --provenance` via OIDC (`.github/workflows/npm-publish.yml`); `policy-bundle-release.yml` for the policy artifact. |
+
+## Open work
+
+- Apply for the [OpenSSF Best Practices badge (CII)](https://www.bestpractices.dev/) and embed it next to the Scorecard badge. (Maintainer action — needs the project to register with the BestPractices.dev site.)
+- Once `harden-runner` is in `block` mode across all jobs (#878), the **Token-Permissions** check should hit its maximum.
+- Once Cosign keyless signing is wired into the release pipeline (#876), the **Signed-Releases** check should hit its maximum.
+
+## Exceptions
+
+| Check | Expiry | Rationale |
+|---|---|---|
+| *(none currently)* | *—* | *—* |
+
+If you add an exception, include the check name, an expiry date
+(don't allow indefinite), and the rationale. Re-evaluate every quarter.
+
+## References
+
+- `.github/workflows/scorecard.yml` — the scanner.
+- [Scorecard project](https://github.com/ossf/scorecard).
+- [Scorecard checks reference](https://github.com/ossf/scorecard/blob/main/docs/checks.md).
+- Issue [#869](https://github.com/sebastienrousseau/dotfiles/issues/869).

package/docs/security/SECRETS.md

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

package/docs/security/SECURITY.md

@@ -0,0 +1,45 @@
+---
+render_with_liquid: false
+---
+
+# 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.