@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

package/docs/security/COMMIT_SIGNING.md

@@ -0,0 +1,138 @@
+# Commit Signing — Policy & Setup
+
+Every commit that reaches `master` in this repository must carry a
+cryptographic signature that GitHub can verify. The policy is enforced
+in three independent layers, so a single bypass does not break the
+chain. This document explains the policy, walks through SSH and GPG
+setup, and lists the verification commands you can run locally before
+pushing.
+
+## Why
+
+Closes [#853](https://github.com/sebastienrousseau/dotfiles/issues/853).
+Local hooks alone are bypassable — `git commit --no-verify`,
+`git push --no-verify`, or unsetting `DOTFILES_ALLOW_UNSKIPPED_PUSH`
+all let an unsigned commit reach a remote if GitHub-side enforcement
+is missing. The chain below removes every escape hatch.
+
+## Enforcement layers
+
+1. **Local commit hook** — `dot_config/git/hooks/executable_commit-msg`
+   is deployed by chezmoi. It rejects an unsigned commit at the
+   `commit-msg` stage on the developer machine.
+2. **Local pre-push hook** — `scripts/git-hooks/pre-push` runs
+   `git verify-commit` against every commit in the push range. A
+   single unverified commit aborts the push. `--no-verify` skips
+   this layer; the next two catch it.
+3. **GitHub Rulesets** — `.github/rulesets/master.json` declares
+   `required_signatures` on `refs/heads/master`. The rule is part
+   of the repo so it's reproducible across forks. Apply with
+   `gh ruleset import .github/rulesets/master.json`.
+4. **`compliance-guard.yml` workflow** — runs on every PR targeting
+   `master`. Walks the commit range with `git verify-commit` and
+   marks unsigned commits in the PR summary; fails the workflow
+   when `unsigned_count > 0`.
+
+A merge to `master` therefore requires (Ruleset accepts the push) AND
+(the workflow's signed-commit check passes) AND (the maintainer's
+push key is allowed). The protection holds even if a contributor's
+local hooks are missing or skipped.
+
+## Setting up SSH signing (recommended)
+
+SSH signing is the 2026 default. It reuses your existing SSH key —
+no new key material, no GPG agent, no Kleopatra UI. GitHub has
+recognised SSH signatures since [2022](https://github.blog/changelog/2022-08-23-ssh-commit-verification-now-supported/).
+
+```sh
+# 1. Tell git to sign with SSH.
+git config --global gpg.format ssh
+
+# 2. Point at the SSH key you want git to use.
+git config --global user.signingkey "$HOME/.ssh/id_ed25519.pub"
+
+# 3. Turn on auto-signing for every commit and tag.
+git config --global commit.gpgsign true
+git config --global tag.gpgsign true
+
+# 4. Tell GitHub which SSH key signs your commits.
+gh ssh-key add ~/.ssh/id_ed25519.pub --type signing --title "$(hostname) signing"
+
+# 5. (Optional) Populate the allowed_signers file so
+#    `git log --show-signature` can verify locally.
+mkdir -p "$HOME/.config/git"
+echo "$(git config user.email) $(cat ~/.ssh/id_ed25519.pub)" \
+  > "$HOME/.config/git/allowed_signers"
+git config --global gpg.ssh.allowedSignersFile \
+  "$HOME/.config/git/allowed_signers"
+```
+
+After this, `git log --show-signature` shows `Good "git" signature
+for you@example.com with ED25519 key SHA256:…` on every new commit.
+
+## Setting up GPG signing (legacy / for tag-signing mirrors that don't yet support SSH)
+
+```sh
+# 1. Generate or import a key. ED25519 is the modern recommendation;
+#    RSA-4096 is the conservative fallback.
+gpg --quick-generate-key "Your Name <you@example.com>" ed25519 sign 2y
+
+# 2. Find the long key ID.
+gpg --list-secret-keys --keyid-format=long
+
+# 3. Tell git which key.
+git config --global user.signingkey <LONG_KEY_ID>
+git config --global commit.gpgsign true
+
+# 4. Export and upload the public key to GitHub.
+gpg --armor --export <LONG_KEY_ID> | gh gpg-key add -
+```
+
+## Verifying locally before pushing
+
+```sh
+# Every commit in the push range.
+git log "$(git merge-base @{u} HEAD)..HEAD" \
+  --pretty='%H %G? %s' \
+  | awk '$2 != "G" {print "UNSIGNED:", $0}'
+
+# Or the canonical command the pre-push hook uses:
+for c in $(git rev-list "$(git merge-base @{u} HEAD)..HEAD"); do
+  git verify-commit "$c" >/dev/null 2>&1 \
+    && echo "✓ $c" \
+    || echo "✗ $c — unsigned, will be rejected by master ruleset"
+done
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `error: gpg failed to sign the data` | gpg-agent isn't running, or `GPG_TTY` not exported | `export GPG_TTY=$(tty)` in your shell rc; restart agent with `gpgconf --kill gpg-agent` |
+| `error: Load key "/.../id_ed25519": Permission denied` | SSH key permissions too open | `chmod 600 ~/.ssh/id_ed25519` |
+| GitHub shows "Unverified" on a commit signed locally | Signing key not uploaded to GitHub | `gh ssh-key add … --type signing` (SSH) or `gh gpg-key add` (GPG) |
+| Pre-push hook rejects a merge commit you didn't author | Upstream commit lacks a signature | Either pull the rebased branch, or fast-forward instead of merging |
+| Ruleset import via `gh` complains "invalid JSON" | Rulesets API expects the `target` + `rules` envelope, not just the rules array | Use the file as-is — `gh ruleset import .github/rulesets/master.json` |
+
+## Re-applying the ruleset after a manual edit
+
+If someone edits the ruleset in the GitHub UI by mistake, the
+file-of-truth wins. Re-apply:
+
+```sh
+gh api -X POST repos/{owner}/{repo}/rulesets \
+  --input .github/rulesets/master.json
+```
+
+(or `-X PUT` against the existing ruleset's ID if it already exists).
+
+## References
+
+- `.github/rulesets/master.json` — the enforced policy.
+- `.github/workflows/compliance-guard.yml` — the workflow that
+  fails PRs containing unsigned commits.
+- `scripts/git-hooks/pre-push` — the local pre-push gate.
+- `dot_config/git/hooks/executable_commit-msg` — the local
+  commit-msg gate.
+- [GitHub: About commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)
+- [GitHub: Telling Git about your SSH key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key)

package/docs/security/DEPS_DEV_EXCEPTIONS.md

@@ -19,7 +19,7 @@ Managed under [#877](https://github.com/sebastienrousseau/dotfiles/issues/877).
 
 ## Active exceptions
 
-_(none currently)_
+*(none currently)*
 
 ## Adding an exception
 
@@ -79,7 +79,7 @@ auto-fail the gate even when they're still listed here.
 
 ## References
 
-- [`scripts/ci/check-deps-dev.sh`](../../scripts/ci/check-deps-dev.sh) — the scanner.
+- [`tools/ci/check-deps-dev.sh`](../../tools/ci/check-deps-dev.sh) — the scanner.
 - [`.github/workflows/deps-dev-validation.yml`](../../.github/workflows/deps-dev-validation.yml) — CI wiring.
 - [`tests/unit/security/test_check_deps_dev.sh`](../../tests/unit/security/test_check_deps_dev.sh) — contract test against canned fixtures.
 - [deps.dev API reference](https://docs.deps.dev/api/v3/).

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/FUZZING.md

@@ -0,0 +1,114 @@
+---
+title: "Fuzzing"
+date: 2026-05-17
+---
+
+# Fuzzing
+
+The project ships native-Go fuzz harnesses for every user-input
+parsing surface in the framework. The harnesses run locally via
+`go test -fuzz`, in CI on every PR via `.github/workflows/fuzz.yml`,
+and (pending upstream submission) continuously on Google's OSS-Fuzz
+infrastructure.
+
+## Why Go fuzzing
+
+The framework is bash. Bash has no first-class fuzzing framework
+that OpenSSF Scorecard recognises (Scorecard scores `Fuzzing` 0
+unless the project ships an integration with one of: OSS-Fuzz,
+ClusterFuzzLite, native Go fuzz, libFuzzer, Atheris). The
+pragmatic path is to **port each user-input parsing surface
+into a small Go function**, run the fuzzer against the Go port,
+and keep the Go port in lockstep with the shell original via
+identical regex / control-flow.
+
+Drift between the shell and Go port IS the bug class the
+fuzzer is designed to surface — if the Go port accepts a string
+the shell rejects (or vice-versa), one of them has a hole.
+
+## Harnesses today
+
+| Harness | Mirrors | What it proves |
+|---------|---------|----------------|
+| `FuzzValidateName` | `scripts/dot/lib/utils.sh:101` (`validate_name`) | Every accepted name contains only `[a-zA-Z0-9._-]`; no shell metacharacter slips through; empty input refused. |
+| `FuzzInitURLResolver` | `scripts/dot/commands/init.sh` (URL construction in `dot init <user\|owner/repo\|url>`) | Accepted URLs use `https://` / `git@` / `ssh://` only; plain HTTP refused; no shell metacharacters in constructed URLs; one input shape per acceptable form. |
+
+Add a harness when:
+
+- a new `dot <subcommand>` accepts user input via `$1` / `--flag`,
+- a new regex appears in `scripts/dot/lib/utils.sh`,
+- a new "construct a URL / path / shell-eval string" code path lands.
+
+## Running locally
+
+```sh
+cd oss-fuzz-integration/fuzz
+
+# 30-second smoke (find regressions quickly)
+go test -run TestNothing -fuzz=FuzzValidateName    -fuzztime=30s ./...
+go test -run TestNothing -fuzz=FuzzInitURLResolver -fuzztime=30s ./...
+
+# Longer run when investigating a flake
+go test -run TestNothing -fuzz=FuzzValidateName    -fuzztime=10m ./...
+```
+
+Failures land in `testdata/fuzz/Fuzz<Name>/` as auto-saved
+reproducers. Commit them — they become permanent regression
+guards via `go test ./...`.
+
+## OSS-Fuzz integration (pending)
+
+The `oss-fuzz-integration/` directory contains everything OSS-Fuzz
+needs to onboard this project:
+
+```
+oss-fuzz-integration/
+├── project.yaml      # OSS-Fuzz project metadata
+├── Dockerfile        # build environment
+├── build.sh          # compiles every harness in fuzz/
+└── fuzz/             # the harnesses themselves
+    ├── go.mod
+    ├── validate_name_test.go
+    └── init_url_resolver_test.go
+```
+
+To onboard:
+
+1. Fork `github.com/google/oss-fuzz`.
+2. Copy `oss-fuzz-integration/` contents to `projects/dotfiles/` in the fork.
+3. Verify locally per <https://google.github.io/oss-fuzz/getting-started/new-project-guide/#testing-locally>:
+
+   ```sh
+   python infra/helper.py build_image dotfiles
+   python infra/helper.py build_fuzzers --sanitizer address dotfiles
+   python infra/helper.py check_build dotfiles
+   python infra/helper.py run_fuzzer dotfiles fuzz_validate_name
+   ```
+
+4. Open a PR to `google/oss-fuzz` per <https://google.github.io/oss-fuzz/getting-started/accepting-new-projects/>.
+5. Once merged, OSS-Fuzz schedules continuous runs on GCP; findings land as private issues in the OSS-Fuzz tracker and are mirrored to the maintainer email in `project.yaml`.
+6. Update `docs/security/SCORECARD.md` — Scorecard's `Fuzzing` check recognises OSS-Fuzz projects automatically (0 → 10).
+
+The upstream PR opens the door to the **CIFuzz** GitHub Action,
+which runs OSS-Fuzz-style fuzzing on every PR in this repo
+(separate from the local-go-fuzz CI job).
+
+## CI workflow
+
+`.github/workflows/fuzz.yml` (planned) runs each harness for
+60 seconds on every PR touching:
+
+- `scripts/dot/lib/utils.sh`
+- `scripts/dot/commands/init.sh`
+- `oss-fuzz-integration/**`
+
+This is the local equivalent of CIFuzz and catches the
+"shell-regex-change without Go-port update" drift class before
+PR merge.
+
+## See also
+
+- `docs/security/SCORECARD.md` — `Fuzzing` check tracking.
+- [Go native fuzzing tutorial](https://go.dev/doc/tutorial/fuzz).
+- [OSS-Fuzz new project guide](https://google.github.io/oss-fuzz/getting-started/new-project-guide/).
+- [CIFuzz GitHub Action](https://google.github.io/oss-fuzz/getting-started/continuous-integration/).

package/docs/security/INSTALL_VERIFICATION.md

@@ -27,7 +27,7 @@ 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:
+`tools/ci/install-chezmoi-verified.sh`, which:
 
 - Resolves the platform (`uname -s` + `uname -m`).
 - Downloads `chezmoi_<version>_<os>_<arch>.tar.gz` AND the matching
@@ -115,7 +115,7 @@ PR.
 ## References
 
 - `install.sh` — the entry point.
-- `scripts/ci/install-chezmoi-verified.sh` — the SHA256-pinned
+- `tools/ci/install-chezmoi-verified.sh` — the SHA256-pinned
   chezmoi installer.
 - `tests/unit/install/test_install_chezmoi_verified.sh` — the
   negative test.

package/docs/security/KEY_ROTATION.md

@@ -4,7 +4,87 @@ 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/POLICY_RELEASES.md

@@ -19,8 +19,8 @@ They include:
 ## Local packaging
 
 ```bash
-bash scripts/release/package-policy-bundles.sh --version 2026.03
-bash scripts/release/package-policy-bundles.sh --json
+bash tools/release/package-policy-bundles.sh --version 2026.03
+bash tools/release/package-policy-bundles.sh --json
 ```
 
 ## Release workflow