@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/security/SECRETS.md

@@ -1,158 +0,0 @@
----
-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

@@ -1,45 +0,0 @@
----
-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.

package/docs/security/SECURITY_CHECKLIST.md

@@ -1,55 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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](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 main.
-- [ ] **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/SHELL_EXEMPTIONS.md

@@ -1,145 +0,0 @@
----
-render_with_liquid: false
----
-
-# Shell Preamble Exemptions
-
-Every bash script in this repo must include `set -euo pipefail` (or
-`set -eu` for POSIX `sh`) within its first 50 lines. The rule is
-enforced by
-[`tools/ci/check-shell-preamble.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tools/ci/check-shell-preamble.sh),
-wired into `pre-commit` and the `reusable-shell-lint.yml` CI job.
-Tests pin the contract under
-[`tests/unit/security/test_shell_preamble_lint.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tests/unit/security/test_shell_preamble_lint.sh).
-
-## Why the preamble is mandatory
-
-`set -e` fails the script on the first error. `set -u` rejects
-reads of unset variables. `set -o pipefail` propagates the exit
-code of the last failing command in a pipeline rather than only the
-final command's. Together they convert silent failures into loud
-ones — which is the only way to catch them.
-
-Real example from this repo's history: `executable_dot-load-benchmark`
-shipped with only `set -e`. A failing pipeline (e.g. `cmd | grep`)
-where `grep` succeeded would still report success even when `cmd`
-crashed. The full triple catches this. The benchmark was upgraded
-in commit 970b631d under #854.
-
-## Exemption categories
-
-Two kinds of files legitimately can't enforce the preamble locally:
-
-### 1. Sourced libraries
-
-Files loaded via `source` / `.` into a caller's shell context. The
-caller already has `set -euo pipefail`; the library inherits it.
-Adding `set -e` locally would persist after the library returns and
-break the caller's own error-handling logic.
-
-These files must carry a comment header in their first 15 lines:
-
-```bash
-# Sourced by <parent>.sh; inherits set -euo pipefail.
-```
-
-The lint accepts files with this marker regardless of preamble
-state. Current adopters:
-
-| Path | Sourced by |
-|---|---|
-| `dot_config/shell/00-core-paths.sh.tmpl` | shell init (zsh/bash/fish) |
-| `dot_config/shell/05-core-safety.sh` | shell init |
-| `dot_config/shell/10-secrets.sh` | shell init |
-| `dot_config/shell/40-fzf-defaults.sh.tmpl` | shell init |
-| `dot_config/shell/40-ls-colors.sh` | shell init |
-| `dot_config/shell/50-logic-functions-core.sh.tmpl` | shell init + fish bridge |
-| `dot_config/shell/50-logic-functions.sh.tmpl` | shell init + fish bridge |
-| `dot_config/shell/51-logic-functions-extra.sh.tmpl` | shell init (lazy) |
-| `dot_config/shell/90-ux-aliases.sh.tmpl` | shell init + fish bridge |
-| `dot_config/shell/91-ux-aliases-lazy.sh.tmpl` | shell init (lazy) |
-| `scripts/dot/lib/bento.sh` | dot CLI commands |
-| `scripts/dot/lib/log.sh` | dot CLI + diagnostics |
-| `scripts/dot/lib/platform.sh` | dot CLI commands |
-| `scripts/dot/lib/ui.sh` | dot CLI + diagnostics + ops |
-| `scripts/dot/lib/utils.sh` | dot CLI |
-| `scripts/ops/heal-chezmoi.sh` | `scripts/ops/heal.sh` |
-| `scripts/ops/heal-system.sh` | `scripts/ops/heal.sh` |
-| `scripts/ops/heal-tools.sh` | `scripts/ops/heal.sh` |
-
-### 2. Bulk-sourced fragments (path-skipped)
-
-Three directories contain hundreds of alias / function / PATH
-snippets that are sourced into the shell. Annotating each one
-individually would be 300+ marker comments with no extra signal.
-The lint skips them by path:
-
-| Path | Contents |
-|---|---|
-| `.chezmoitemplates/aliases/**/*.aliases.sh` | alias definitions sourced into the user's shell. |
-| `.chezmoitemplates/functions/**` | shell-function definitions sourced into the user's shell. |
-| `.chezmoitemplates/paths/**` | `PATH=…:$PATH` snippets concatenated by the shell init. |
-
-### 3. Test scripts (path-skipped)
-
-`tests/**` — every file under the test tree is invoked through
-`tests/framework/test_runner.sh` which manages shell options for its
-children. The runner itself has the full preamble; children that
-source the framework inherit it.
-
-### 4. Explicit opt-outs
-
-Init fragments and completion scripts that must NOT carry their own
-preamble (e.g., `dot_local/bin/executable_dot_completion`, a zsh
-completion sourced into the interactive shell) can carry an
-explicit marker:
-
-```bash
-# preamble:skip — opt-out for completion / init fragments.
-```
-
-The lint accepts these. Use sparingly.
-
-## Adding a new exemption
-
-When you need to mark a new file:
-
-1. **Decide whether it's actually sourced or executed.** If a user
-   ever invokes it directly (chmod +x + `./file.sh`), add the
-   preamble. If it's only ever `source`d, mark it.
-
-2. **Pick the right marker.**
-   - Sourced library: `# Sourced by <caller>; inherits set -euo pipefail.`
-   - Completion / init fragment: `# preamble:skip — <why>.`
-
-3. **Run the checker:**
-
-   ```bash
-   ./tools/ci/check-shell-preamble.sh path/to/file.sh
-   ```
-
-   Exit 0 = lint passes.
-
-4. **If you're adding a new entire directory of fragments**
-   (rare — alias buckets, plugin trees), edit the path-skip rule
-   in `tools/ci/check-shell-preamble.sh` and document it in this
-   page's "Bulk-sourced fragments" table above.
-
-## CI integration
-
-- **Pre-commit hook** (`config/pre-commit-config.yaml` →
-  `shell-preamble-check`): blocks `git commit` if a staged shell
-  file fails the lint.
-- **CI** (`.github/workflows/reusable-shell-lint.yml`): runs the
-  full-repo scan on every PR.
-
-A change to either the checker or the marker convention must update
-this page in the same PR.
-
-## References
-
-- `tools/ci/check-shell-preamble.sh` — the lint.
-- `tests/unit/security/test_shell_preamble_lint.sh` — contract test.
-- `config/pre-commit-config.yaml` (`shell-preamble-check` hook).
-- `.github/workflows/reusable-shell-lint.yml` — CI invocation.
-- Issue [#854](https://github.com/sebastienrousseau/dotfiles/issues/854).

package/docs/security/SOUP_REGISTER.md

@@ -1,36 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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](https://github.com/sebastienrousseau/dotfiles/blob/main/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](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
-| Trivy container | `aquasec/trivy` | Pinned tag in workflow | Container tag in [security-enhanced.yml](https://github.com/sebastienrousseau/dotfiles/blob/main/.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](https://github.com/sebastienrousseau/dotfiles/blob/main/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.

package/docs/security/THREAT_MODEL.md

@@ -1,130 +0,0 @@
----
-render_with_liquid: false
----
-
-# Threat Model
-
-Security analysis of the dotfiles distribution. Covers trust boundaries, threat actors, attack surfaces, and mitigations.
-
-## Trust Boundary
-
-The primary trust boundary is the **local machine**. Dotfiles are deployed to and executed on the user's own system. All configuration files, scripts, and templates run with the user's privileges.
-
-```text
-┌─────────────────────────────────────────────────┐
-│ Local Machine (trusted zone)                    │
-│  ┌─────────────────┐  ┌──────────────────────┐  │
-│  │ ~/.dotfiles/     │  │ ~/.config/ (deployed)│  │
-│  │ (source repo)    │──│ Shell configs, nvim  │  │
-│  └─────────────────┘  └──────────────────────┘  │
-│                                                  │
-│  ┌─────────────────┐  ┌──────────────────────┐  │
-│  │ ~/.local/bin/    │  │ ~/.cache/shell/      │  │
-│  │ (user scripts)   │  │ (cached eval output) │  │
-│  └─────────────────┘  └──────────────────────┘  │
-└─────────────────────────────────────────────────┘
-         │
-    ─────┼──────── Trust boundary ────────
-         │
-┌─────────────────────────────────────────────────┐
-│ External (untrusted zone)                        │
-│  GitHub (repo hosting), Homebrew, Nix,           │
-│  Zinit plugins, Neovim plugins, npm, pip         │
-└─────────────────────────────────────────────────┘
-```
-
-## Threat Actors
-
-| Actor | Motivation | Capability |
-|-------|-----------|------------|
-| Supply chain attacker | Inject malicious code via dependency | Compromise upstream packages (Homebrew, npm, Zinit plugins) |
-| Secrets harvester | Steal API keys, SSH keys, tokens | Scrape git history, shell history, env vars |
-| Privilege escalation | Gain root access | Exploit `sudo` aliases, writable scripts in PATH |
-| Network attacker | Intercept credentials | MITM on install scripts, curl-pipe-bash |
-
-## Attack Surfaces
-
-### 1. Shell Startup Scripts
-
-**Risk:** Malicious code in sourced files executes with user privileges on every shell start.
-
-**Mitigations:**
-
-- All shell scripts pass `shellcheck --severity=error`
-- `set -euo pipefail` enforced in all operational scripts
-- `eval` usage hardened with process substitution (`. /dev/stdin`)
-- Input validation on dynamic function generation
-- `DOTFILES_ULTRA_FAST=1` bypasses all non-core sourcing
-
-### 2. Secrets Exposure
-
-**Risk:** API keys, tokens, and SSH keys leaked via git history, shell history, or environment.
-
-**Mitigations:**
-
-- [Gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook blocks secrets in commits
-- Atuin `history_filter` excludes sensitive patterns
-- Age encryption for local secret storage
-- `dot secrets set` uses secure prompts (no shell history)
-- `.gitignore` excludes `key.txt`, `.env`, credential files
-
-### 3. Supply Chain Dependencies
-
-**Risk:** Compromised upstream packages injected into the toolchain.
-
-**Mitigations:**
-
-- Nix Flakes provide reproducible, pinned dependencies
-- Zinit plugin versions pinned (`ver"0.8.0"`)
-- Neovim plugin versions locked via `lazy-lock.json`
-- `install.sh` uses HTTPS for all downloads
-- Homebrew formula integrity via bottle checksums
-
-### 4. Path Manipulation
-
-**Risk:** Attacker places malicious binary in a PATH directory that shadows legitimate tools.
-
-**Mitigations:**
-
-- PATH construction is deterministic (template-generated)
-- `~/.local/bin` is user-controlled and checked for writability
-- No world-writable directories in PATH
-- `prependpath` function validates directory existence
-
-### 5. Template Injection
-
-**Risk:** Chezmoi template variables could inject shell code if not properly quoted.
-
-**Mitigations:**
-
-- Template variables come from `.chezmoidata.toml` (user-controlled)
-- No external/network data used in templates
-- Template validation via `chezmoi apply --dry-run` in CI
-
-### 6. Cached Eval Files
-
-**Risk:** Stale or tampered cache files in `~/.cache/shell/` sourced at startup.
-
-**Mitigations:**
-
-- `_cached_eval` validates cache against binary mtime
-- Cache files are user-owned (0644)
-- Cache directory is under `$XDG_CACHE_HOME` (user-controlled)
-- Cache can be cleared with `rm -rf ~/.cache/shell/`
-
-## Residual Risks
-
-| Risk | Likelihood | Impact | Status |
-|------|-----------|--------|--------|
-| Zinit plugin compromise | Low | High | Mitigated by version pinning |
-| Shell history leak | Medium | Medium | Mitigated by Atuin filter |
-| Stale Nix closure | Low | Low | Accepted (manual `nix flake update`) |
-| macOS Keychain access | Low | Medium | Accepted (OS-level protection) |
-
-## Recommendations
-
-1. Run `gitleaks detect` before every push (pre-commit hook enforced)
-2. Rotate secrets on a 90-day schedule
-3. Audit `lazy-lock.json` diffs when updating Neovim plugins
-4. Pin Homebrew versions for security-critical tools
-5. Use `DOTFILES_ULTRA_FAST=1` in CI to minimize attack surface