@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/docs/security/DISCLOSURE.md

@@ -0,0 +1,130 @@
+# Encrypted Security Disclosure — Reporter Workflow
+
+This document is for **external security researchers** who have found
+an issue in this repository and want to report it without exposing
+sensitive details (PII, exploit chains, internal infrastructure) in
+transit or at rest on third-party servers.
+
+If your report doesn't need encryption, please use
+[GitHub Security Advisories](https://github.com/sebastienrousseau/dotfiles/security/advisories)
+instead — it's faster and the GitHub-side audit trail is stronger.
+
+## 1. Fetch the maintainer's public key
+
+```sh
+# Web Key Directory is the modern recommendation.
+gpg --auto-key-locate clear,wkd \
+    --locate-keys security@sebastienrousseau.com
+```
+
+If WKD fails (offline keyserver, corporate proxy), download directly:
+
+```sh
+curl -fsSL \
+  https://sebastienrousseau.com/.well-known/openpgpkey/hu/qpzqfwauiwxnu1xrf5h47bunsho44p6f \
+  | gpg --import
+```
+
+## 2. Verify the fingerprint
+
+**Do not skip this step.** A MITM attacker can serve their own key.
+
+```sh
+gpg --fingerprint security@sebastienrousseau.com
+```
+
+The fingerprint must match the one published in
+[`.github/SECURITY.md`](../../.github/SECURITY.md). Cross-verify
+against the SSH signing key in `dot_config/git/allowed_signers.tmpl`
+— the maintainer signs commits with the same identity, so both
+fingerprints derive from the same identity claim.
+
+If the two fingerprints don't match, **stop**. Open a private
+[Security Advisory](https://github.com/sebastienrousseau/dotfiles/security/advisories/new)
+and ask the maintainer to confirm the key out-of-band.
+
+## 3. Encrypt your report
+
+```sh
+cat <<EOF | gpg --encrypt --armor \
+  --recipient security@sebastienrousseau.com \
+  --output disclosure.asc
+Subject: <short description of the issue>
+
+<full details — repro steps, affected versions, exploit, screenshots
+referenced by base64-encoded attachments, contact info for follow-up>
+EOF
+```
+
+Verify the output is an ASCII-armored OpenPGP message before sending:
+
+```sh
+head -1 disclosure.asc
+# Expected: -----BEGIN PGP MESSAGE-----
+```
+
+## 4. Send
+
+Attach `disclosure.asc` to an email to
+**<security@sebastienrousseau.com>**.
+
+Subject line: `[dotfiles] <severity>: <short description>` (no
+encryption-sensitive content in the subject; mail relays log
+subjects in plain text).
+
+## 5. Acknowledgement
+
+You should receive an acknowledgement within the SLA in
+[`.github/SECURITY.md`](../../.github/SECURITY.md):
+
+| Severity | Initial response |
+|---|---|
+| Critical | 24 hours |
+| High | 72 hours |
+| Medium | 5 business days |
+| Low | 10 business days |
+
+The acknowledgement will be signed with the same key you encrypted
+to. Verify the signature:
+
+```sh
+gpg --verify response.asc
+```
+
+If you don't receive an acknowledgement in the SLA window, or the
+acknowledgement signature doesn't verify, escalate by:
+
+1. Opening a private GitHub Security Advisory.
+2. DM-ing the maintainer on Mastodon: `@sebastienrousseau@hachyderm.io`.
+
+## 6. After disclosure
+
+The maintainer commits to:
+
+- A fix timeline communicated within the SLA.
+- A CVE assignment when severity ≥ Medium and the issue affects
+  published releases (npm package, release tarballs).
+- Public credit at fix time in the release notes (unless you
+  request anonymity at report time).
+- A backport to any actively-supported release line listed in
+  `.github/SECURITY.md`.
+
+## What NOT to do
+
+- Don't post details in a public issue, even a "I found a bug, ping
+  me for details" placeholder — every public reference is a tip-off
+  to attackers monitoring the repo.
+- Don't disclose to third parties (other dotfile maintainers,
+  security mailing lists, blog posts) before the embargo lifts.
+- Don't access data or systems you don't own.
+- Don't run automated scans against `*.sebastienrousseau.com` that
+  exceed normal browser-like traffic.
+
+## See also
+
+- [`.github/SECURITY.md`](../../.github/SECURITY.md) — policy
+  overview + fingerprint.
+- [`docs/security/KEY_ROTATION.md`](KEY_ROTATION.md) — schedule for
+  when the disclosure key is rotated.
+- [`docs/security/AUDIT_BYPASS.md`](AUDIT_BYPASS.md) — separate flow
+  for the pre-push audit bypass (not for disclosure).

package/docs/security/ENCRYPTION.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Secrets Encryption with SOPS and age
 
 ## Quick Start
@@ -30,6 +34,7 @@ sops secrets.sops.yaml
 ## Recovery
 
 If you lose your age private key, follow these steps:
+
 1. Create a new key: `age-keygen -o ~/.config/sops/age/keys.txt`
 2. Re-encrypt all secrets with the new public key.
 3. Update `.sops.yaml` with the new public key.

package/docs/security/FMEA.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Failure Mode and Effects Analysis (FMEA)
 
 Systematic risk assessment of the chezmoi-managed dotfiles repository per IEC 60812 methodology. Identifies failure modes, quantifies risk priority, and documents mitigations across all configuration management subsystems.

package/docs/security/HISTORY_FILTERING.md

@@ -0,0 +1,132 @@
+---
+render_with_liquid: false
+---
+
+# Atuin History Filtering
+
+This page documents how high-risk command patterns are excluded from
+Atuin shell history, how to extend the list for your machine, and the
+trade-offs of filter design.
+
+## Why
+
+Atuin syncs shell history across machines and exposes a fuzzy-search UI
+(`Ctrl-R`). Without a filter, every command — including ones that
+contain secrets passed inline (`AWS_SECRET_ACCESS_KEY=...`, `op run`,
+`vault read`, `curl -H 'Authorization: Bearer ...'`) — is captured,
+synced to a remote service, and made grep-able.
+
+The `history_filter` array in `~/.config/atuin/config.toml` lists
+regular expressions that, if matched, prevent Atuin from recording the
+command at all (it never enters the local DB, and therefore never
+syncs).
+
+## How it ships
+
+Patterns are sourced from `.chezmoidata/secrets-patterns.toml` and
+materialised into `~/.config/atuin/config.toml` by the chezmoi template
+at `dot_config/atuin/config.toml.tmpl`.
+
+```
+.chezmoidata/secrets-patterns.toml
+  └── [atuin.history_filter]
+        defaults  = [...]      # audited baseline (this repo)
+        extra     = [...]      # empty by default; populated per machine
+
+dot_config/atuin/config.toml.tmpl
+  └── chezmoi apply  ─────►  ~/.config/atuin/config.toml
+```
+
+Run `chezmoi apply ~/.config/atuin/config.toml` after editing the
+defaults; `dot doctor` reports the count of deployed patterns and
+fails loud if the block is missing.
+
+## What's filtered by default
+
+The audited baseline covers:
+
+- Generic env-var exports: `^export (SECRET|TOKEN|PASSWORD|API_KEY|AWS_)`,
+  `^PASSWORD=`, `^[A-Z_]+_TOKEN=`, `^[A-Z_]+_KEY=`.
+- Cloud provider auth: `aws ... configure|auth|login`, `gcloud auth ...`,
+  `az login`, `kubectl ... --kubeconfig`.
+- AI provider keys: Anthropic, OpenAI, Gemini, Mistral.
+- SaaS secrets: Stripe, GitHub PAT (`GH_TOKEN`, `GITHUB_TOKEN`), `NPM_TOKEN`,
+  `CARGO_REGISTRY_TOKEN`.
+- Authorization headers (`curl -H 'Authorization: ...'`).
+- Embedded creds in git URLs (`git clone https://user:pass@...`).
+- Secret managers: `vault`, `op` (1Password), `chamber`.
+- Key material: `ssh-keygen`, `ssh-add`, `gpg --import|--export-secret`,
+  `age -d|-e --passphrase`.
+- DB connection strings with inline creds
+  (`postgres|mysql|mongodb|redis://user:pass@host`).
+
+See `.chezmoidata/secrets-patterns.toml` for the canonical list.
+
+## Adding per-host patterns
+
+Each contributor or machine can extend the list without editing the
+shared template. In `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data.atuin.history_filter]
+extra = [
+  "^my-private-tool ",
+  "^OUR_CORP_API_KEY=",
+  "tailscale up --auth-key=",
+]
+```
+
+Then re-apply:
+
+```bash
+chezmoi apply ~/.config/atuin/config.toml
+```
+
+The `extra` patterns are appended to the defaults in the deployed
+config.
+
+## Adding a pattern to the project defaults
+
+Edit `.chezmoidata/secrets-patterns.toml` and add a regex to
+`[atuin.history_filter].defaults`. Then:
+
+1. Add a fixture command to `tests/unit/secrets/test_atuin_history_filter.sh`
+   under `LEAKED_FIXTURES` — your new pattern must catch at least one
+   real-shape command.
+2. Run the test: `bash tests/unit/secrets/test_atuin_history_filter.sh`.
+3. Add a benign-fixture if your regex is broad enough to risk false
+   positives.
+4. Open a PR; CI runs the same test.
+
+## Trade-offs
+
+`history_filter` is a deny-list. Two classes of failure to design
+around:
+
+- **False positives**: an overly broad regex hides commands the user
+  needs to recall. Mitigation: every new pattern must include a
+  fixture under `BENIGN_FIXTURES` that the regex correctly does *not*
+  match.
+- **False negatives**: a new secret format ships, no pattern matches,
+  the secret lands in history. Mitigation: the OpenSSF Scorecard
+  workflow (issue #869) and the nightly drift detector (#875) will
+  surface new exposure surfaces; review them quarterly.
+
+`history_filter` does not replace:
+
+- A real secret manager (`age`/`sops`, 1Password, Vault) — see
+  `docs/security/ENCRYPTION.md`.
+- Pre-commit `gitleaks` / `detect-secrets` scans — see
+  `config/pre-commit-config.yaml`.
+- Server-side audit logging — see `docs/security/COMPLIANCE.md`.
+
+It's the last line of defence against accidental command-line capture,
+not the first.
+
+## References
+
+- Atuin config schema: <https://atuin.sh/docs/config>
+- Chezmoi template data: <https://www.chezmoi.io/reference/templates/>
+- Issue #872 (this hardening)
+- `tests/unit/secrets/test_atuin_history_filter.sh` (pattern-coverage test)
+- `scripts/diagnostics/doctor.sh` — "Atuin History Filter" section

package/docs/security/INCIDENT_RESPONSE.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Incident Response Plan
 
 Incident response procedures for the dotfiles repository. Covers supply chain compromise, secrets exposure, configuration drift, tool tampering, and CI pipeline attacks. Based on NIST SP 800-61 Rev. 2 (Computer Security Incident Handling Guide).

package/docs/security/INSTALL_VERIFICATION.md

@@ -0,0 +1,122 @@
+---
+render_with_liquid: false
+---
+
+# Install Verification
+
+This page documents what gets verified during `install.sh` execution,
+why those checks matter, and how to obtain the per-release expected
+hashes used by the verified-install path in the README.
+
+Managed under
+[#858](https://github.com/sebastienrousseau/dotfiles/issues/858).
+
+## What is verified
+
+`install.sh` performs three classes of verification before doing
+anything destructive:
+
+### 1. The installer itself (verified path)
+
+The README's **Verified install** snippet pins to a release tag
+(e.g. `v0.2.501`), downloads the installer, and asks `shasum -a 256
+-c` (or `sha256sum -c`) to check the contents against an expected
+hash. If the hash doesn't match, the verify step exits non-zero and
+the install never starts.
+
+### 2. The `chezmoi` binary (always verified when possible)
+
+`install.sh` prefers the bundled checksum-verified installer at
+`scripts/ci/install-chezmoi-verified.sh`, which:
+
+- Resolves the platform (`uname -s` + `uname -m`).
+- Downloads `chezmoi_<version>_<os>_<arch>.tar.gz` AND the matching
+  `chezmoi_<version>_checksums.txt` from the official
+  `twpayne/chezmoi` GitHub release.
+- Greps the checksum file for the asset's expected SHA256.
+- Verifies the downloaded tarball against that SHA256 using
+  `shasum -a 256 -c` / `sha256sum -c`.
+- Aborts with a clear error if the asset isn't in the checksum file
+  or the verification fails.
+
+When the verified installer isn't available (e.g. the curl one-liner
+mode where `install.sh` is fetched in isolation), the code falls back
+to `get.chezmoi.io` with two defense-in-depth checks:
+
+- The downloaded installer must be smaller than 100 KiB (sanity
+  guard against a CDN serving an arbitrary binary).
+- The first line must start with `#!/` (must look like a shell
+  script).
+
+These are weaker than a SHA256 check, but they catch the obvious
+"installer got replaced with a 50 MB malicious binary" failure mode.
+
+### 3. The chezmoi source tree
+
+After chezmoi is installed, `install.sh` clones the dotfiles repo
+itself. This isn't currently cryptographically verified beyond Git's
+own object integrity, but commits in the repo are SSH-signed and
+branch protection on `master` requires signed commits (see #853).
+
+## How to obtain per-release hashes
+
+The verified-install snippet uses the SHA256 of the `install.sh`
+file *as it exists at the release tag*. To regenerate after a release:
+
+```bash
+git switch master
+git pull
+NEW_TAG="v0.2.502"   # adjust
+git tag -s "$NEW_TAG" -m "..."
+git push origin "$NEW_TAG"
+
+# Compute the hash:
+shasum -a 256 install.sh
+
+# Update README.md's verified-install snippet with the new hash + tag.
+```
+
+A follow-up automation (tracked at the bottom of this page) will
+publish a `.sha256` sibling next to the install.sh asset in GitHub
+Releases so the README snippet can reference a stable URL instead
+of a hardcoded value.
+
+## What to do if the hash doesn't match
+
+If you run the verified install and `shasum -a 256 -c` reports
+`FAILED`:
+
+1. **Don't run the installer.** The hash mismatch means either the
+   release was retagged (rare) or someone is MITM-ing your download.
+2. Check the [Releases page](https://github.com/sebastienrousseau/dotfiles/releases)
+   for the matching tag. The per-release `install.sh` SHA is
+   embedded in the README at the time of that release; you can also
+   recover it from the git history of `README.md`.
+3. If the README hash is stale (release was retagged for legitimate
+   reasons), `git log` on `install.sh` will show the change. Inspect
+   the diff before trusting a new hash.
+
+## What is NOT verified (yet)
+
+- **Cosign keyless signature** on `install.sh` — tracked separately
+  under #876.
+- **deps.dev attestation lookup** for npm/Python deps used during
+  install — tracked under #877.
+- **Reproducible-build guarantee** for the chezmoi binary itself —
+  out of scope; rely on the upstream project's release engineering.
+
+## Negative-test coverage
+
+`tests/unit/install/test_install_chezmoi_verified.sh` exercises the
+verification path with a deliberately tampered checksum to confirm
+the installer aborts. The test ships with the repo and runs on every
+PR.
+
+## References
+
+- `install.sh` — the entry point.
+- `scripts/ci/install-chezmoi-verified.sh` — the SHA256-pinned
+  chezmoi installer.
+- `tests/unit/install/test_install_chezmoi_verified.sh` — the
+  negative test.
+- Issue [#858](https://github.com/sebastienrousseau/dotfiles/issues/858).

package/docs/security/KEYS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Keybindings
 
 This is the single source of truth for navigation and muscle-memory shortcuts

package/docs/security/KEY_ROTATION.md

@@ -1,6 +1,90 @@
+---
+render_with_liquid: false
+---
+
 # Key Rotation Guide
 
-This guide covers rotating encryption keys for secrets managed by Age and SOPS.
+This page tracks two distinct key lifecycles:
+
+1. **Disclosure key** — the GPG key reporters use to encrypt vulnerability reports to the maintainer. Single key, public, rotated annually or on compromise. Source of truth for the active fingerprint is `.github/SECURITY.md`.
+2. **Secrets encryption keys** — the Age and SOPS keys that protect encrypted dotfiles in this repo. Multiple keys, per-machine, rotated annually or on personnel / device change.
+
+Both sections live here so a single audit can confirm the project's
+posture across encrypted-disclosure-in and encrypted-secrets-at-rest.
+
+## Disclosure Key (GPG)
+
+Closes the rotation half of [#870](https://github.com/sebastienrousseau/dotfiles/issues/870).
+
+### Active key
+
+| Field | Value |
+|---|---|
+| Identity | `security@sebastienrousseau.com` |
+| Fingerprint | `55AFAD364FD9DB3819E61F0C8D688FAFA9144693` |
+| Algorithm | ED25519 signing primary + CV25519 encryption subkey |
+| Created | 2026-05-16 |
+| Expires | 2029-05-15 (3 years from creation) |
+| WKD URL | <https://sebastienrousseau.com/.well-known/openpgpkey/hu/qpzqfwauiwxnu1xrf5h47bunsho44p6f> |
+| Cross-reference | matches the SSH signing key in `dot_config/git/allowed_signers.tmpl` |
+
+### Rotation triggers
+
+| Trigger | Response time | Action |
+|---|---|---|
+| Annual cadence | Within 30 days of expiry | Generate new key, publish, sign transition statement with the old key, archive old key below. |
+| Suspected compromise | Same day | Revoke immediately, publish revocation cert to WKD, replay in-flight encrypted disclosures with the new key. |
+| Algorithm deprecation | Within 90 days of advisory | Generate replacement on a stronger algorithm; follow annual-cadence steps. |
+| Maintainer change | Same day as handover | Old maintainer signs a transition statement; old key revoked 30 days after handover. |
+
+### Rotation procedure
+
+1. Generate the new key (air-gapped where possible):
+
+   ```sh
+   gpg --quick-generate-key \
+     "Sebastien Rousseau (Security) <security@sebastienrousseau.com>" \
+     ed25519 sign 1y
+   ```
+
+2. Sign a transition statement with the OLD key:
+
+   ```sh
+   gpg --clearsign <<EOF
+   Transition statement, $(date -u +%Y-%m-%dT%H:%M:%SZ).
+   The disclosure key for security@sebastienrousseau.com rotates from:
+     OLD: <old-fingerprint>
+     NEW: <new-fingerprint>
+   Encrypted reports sent to either key during the 30-day overlap
+   will be accepted. After <UTC-cutoff>, only the new key is honoured.
+   EOF
+   ```
+
+3. Publish the new key to:
+   - `sebastienrousseau.com/.well-known/openpgpkey/hu/` (WKD)
+   - the maintainer's keyoxide profile if applicable
+
+4. Update the "Active key" table above with the new fingerprint and
+   move the previous row into the "Historical disclosure keys"
+   table below with the actual revocation date.
+
+5. Commit, signing with both old and new keys during the overlap:
+
+   ```sh
+   git commit -S -m "security(key): rotate disclosure key $(date +%Y-%m)" \
+     -m "$(cat transition.asc)"
+   ```
+
+6. After the 30-day overlap, revoke the old key and publish the
+   revocation cert to the same WKD endpoint.
+
+### Historical disclosure keys
+
+| From | Until | Fingerprint | Reason for rotation |
+|---|---|---|---|
+| *(none yet — first key)* | *—* | *—* | *—* |
+
+---
 
 ## Age Key Rotation
 

package/docs/security/MCP_POLICY.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # MCP Policy
 
 MCP is treated as a controlled execution boundary.
@@ -7,6 +11,7 @@ MCP is treated as a controlled execution boundary.
 The tracked default is `strict-local`.
 
 Properties:
+
 - local-first
 - least privilege
 - no broad filesystem roots
@@ -21,6 +26,7 @@ Approved package pins live in [mcp-lock.json](/home/seb/.dotfiles/dot_config/dot
 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`
@@ -45,6 +51,7 @@ The JSON form is the audit artifact for CI, release validation, and workstation
 ## 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
@@ -55,11 +62,13 @@ Any change to MCP policy requires:
 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

package/docs/security/POLICY_RELEASES.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Policy Bundle Releases
 
 Policy bundles are released as tracked governance artifacts.

package/docs/security/README.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Security Documentation
 
 This directory contains security documentation for the dotfiles project.