@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/security/AUDIT_BYPASS.md

@@ -1,103 +0,0 @@
----
-render_with_liquid: false
----
-
-# Pre-Push Audit Bypass
-
-This page documents when the pre-push reliability audit can be bypassed,
-how to do it, and why the answer is "almost never on `main`."
-
-## Background
-
-`scripts/git-hooks/pre-push` runs two checks on every push:
-
-1. **Signed-commit verification** — every commit being pushed must have
-   a valid GPG/SSH signature. No bypass is available; an unsigned
-   commit is refused unconditionally.
-
-2. **Reliability audit** — `scripts/qa/reliability-audit.sh --quick`
-   runs a fast subset of the test suite + lint checks. This is the
-   step that can be bypassed.
-
-Before issue #871 the audit was opt-out: `DOTFILES_SKIP_PRE_PUSH_AUDIT=1`
-in your shell rc would silently skip every push's audit. Bypass was
-invisible, persistent, and one keystroke away. That's the wrong default.
-
-## The new policy
-
-Effective with #871 and the corresponding commit on this branch:
-
-- The audit **always runs by default**. Missing env var → audit runs.
-- Bypass requires `DOTFILES_ALLOW_UNSKIPPED_PUSH=1` set inline for the
-  one push you want to bypass (not exported in your shell rc).
-- The legacy `DOTFILES_SKIP_PRE_PUSH_AUDIT=1` is **rejected** with a
-  migration message; the hook exits non-zero if it sees the old var.
-- Every bypass is appended to
-  `${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log` with
-  timestamp, branch, remote, and reason.
-- `dot doctor` reports the count of bypasses in the last 7 days.
-
-The new variable name is deliberately awkward
-(`DOTFILES_ALLOW_UNSKIPPED_PUSH`) — it should not feel like a routine
-flag. Setting it should require a moment's thought.
-
-## How to bypass for a single push
-
-```bash
-DOTFILES_ALLOW_UNSKIPPED_PUSH=1 \
-DOTFILES_BYPASS_REASON='hotfix: CI is wedged on flake' \
-  git push origin hotfix/my-branch
-```
-
-The reason string is optional but encouraged. It lands in the audit log
-so `dot doctor` and any future review can answer "why was this
-bypassed?" without git archaeology.
-
-## When bypass is legitimate
-
-Short list — anything outside this is suspicious:
-
-- **Hotfix push to a non-main branch** when CI infrastructure itself
-  is the audit blocker (e.g., the audit pre-flight depends on a remote
-  service that's down). The fix should land *before* the
-  infrastructure recovers; bypass is the bridge.
-- **Force-push of a tag rewind** that doesn't introduce new commits
-  (rare).
-
-When bypass is **not** legitimate:
-
-- Routine `main` pushes. The whole point of the audit is to guard
-  the protected branch.
-- Pushes whose audit failure is "annoying" — the right move is to fix
-  the failure, not skip the check.
-- CI environments. CI should run the audit explicitly, never bypass
-  it; if a CI job pushes, the env var must remain unset there.
-
-## Verifying current state
-
-```bash
-dot doctor   # surfaces recent bypasses
-cat ${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log
-```
-
-Each line of the log is tab-separated:
-`ISO8601-timestamp \t branch=... \t remote=... \t reason=...`.
-
-## Disabling bypass entirely
-
-If your machine should *never* bypass (e.g., a release runner), unset
-the env var in your shell rc and add a guard to your `.zshenv` or
-equivalent:
-
-```bash
-unset DOTFILES_ALLOW_UNSKIPPED_PUSH
-```
-
-There's no way to permanently grant bypass — that's intentional.
-
-## References
-
-- `scripts/git-hooks/pre-push` — the hook itself
-- `scripts/diagnostics/doctor.sh` — the "Pre-Push Audit Bypass" section
-- `tests/unit/security/test_pre_push_bypass.sh` — regression test
-- Issue #871

package/docs/security/AUTOMATION_SECRETS.md

@@ -1,26 +0,0 @@
----
-render_with_liquid: false
----
-
-# Automation Secrets
-
-## Required secrets
-
-| Secret | Scope | Purpose |
-| :--- | :--- | :--- |
-| `ACTIONS_BOT_SIGNING_KEY` | GitHub Actions | SSH private key used for signed automation commits |
-| `GITHUB_TOKEN` | GitHub Actions | GitHub API access for PRs, attestations, and scans |
-
-## Required local variables
-
-| Variable | Scope | Purpose |
-| :--- | :--- | :--- |
-| `HOMEBREW_INSTALLER_SHA256` | macOS bootstrap | Verifies the Homebrew installer before execution |
-| `CHEZMOI_INSTALLER_SHA256` | Installer | Verifies the Chezmoi installer before execution |
-
-## Provisioning notes
-
-1. Store the SSH signing private key in GitHub Actions as `ACTIONS_BOT_SIGNING_KEY`.
-2. Store the matching public key in [allowed_signers](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/git/allowed_signers.tmpl).
-3. Rotate the key on personnel or workstation change.
-4. Fail closed when secrets are absent.

package/docs/security/CI_EGRESS_ALLOWLIST.md

@@ -1,127 +0,0 @@
----
-render_with_liquid: false
----
-
-# CI Egress Allowlist
-
-This page documents the network endpoints CI jobs are allowed to
-reach when `step-security/harden-runner` is operating in `block`
-mode. Managed under
-[#878](https://github.com/sebastienrousseau/dotfiles/issues/878).
-
-## Status
-
-All 76 jobs across the 28 workflow files in `.github/workflows/` are
-currently in **`audit` mode** — harden-runner is the first step in
-every job and records outbound network calls to the
-[step-security telemetry dashboard](https://app.stepsecurity.io) but
-does not block them.
-
-The next iteration (tracked as a follow-up under #878) flips each
-group to `block` once the audit-mode runs confirm the allowlist is
-complete. Switching one job at a time keeps blast radius small:
-a missing endpoint on a `block`-mode job fails the run loud and the
-list below gets updated.
-
-## Allowlist (by domain)
-
-This is the union of endpoints the entire workflow surface needs.
-When flipping a specific job to `block` mode, narrow this list to
-the endpoints that particular job actually touches.
-
-### GitHub itself (universally required)
-
-| Endpoint | Used by | Why |
-|---|---|---|
-| `github.com:443` | every job | git clone, gh CLI |
-| `api.github.com:443` | every job | gh CLI, issue/PR API |
-| `objects.githubusercontent.com:443` | every job | release-asset downloads, LFS objects |
-| `*.actions.githubusercontent.com:443` | every job | runner ↔ orchestrator |
-| `pkg.actions.githubusercontent.com:443` | every job | action-cache CDN |
-| `results-receiver.actions.githubusercontent.com:443` | every job | workflow telemetry |
-| `codeload.github.com:443` | jobs that `git clone` tagged refs | tarball downloads for some actions |
-| `uploads.github.com:443` | jobs that upload artifacts | `actions/upload-artifact` |
-| `raw.githubusercontent.com:443` | the install-script jobs | curl-pull of unversioned content |
-
-### Package managers (apt, brew, cargo, npm, luarocks)
-
-| Endpoint | Used by | Why |
-|---|---|---|
-| `azure.archive.ubuntu.com:443` | ubuntu jobs running `apt-get` | apt mirror |
-| `archive.ubuntu.com:80` | ubuntu jobs running `apt-get` | apt mirror |
-| `security.ubuntu.com:80` | ubuntu jobs running `apt-get` | security updates |
-| `keyserver.ubuntu.com:443` | jobs that add repo signing keys | GPG keyserver |
-| `formulae.brew.sh:443` | macOS jobs running `brew` | Homebrew formula index |
-| `ghcr.io:443` + `*.docker.io:443` | docker / container jobs | image pulls |
-| `registry.npmjs.org:443` | npm-publish.yml + the pre-commit npm hook | npm metadata + publish |
-| `registry-1.docker.io:443` | docker jobs | image manifests |
-| `crates.io:443` + `static.crates.io:443` | cargo-install jobs | crate downloads |
-| `index.crates.io:443` | cargo-install jobs | crate index |
-| `luarocks.org:443` + `*.luarocks.org:443` | reusable-lua-lint.yml | luacheck install |
-
-### Project-specific installers (chezmoi / mise / starship / stylua / typos / etc.)
-
-| Endpoint | Used by | Why |
-|---|---|---|
-| `get.chezmoi.io:443` | `setup-chezmoi` composite (fallback path) | chezmoi installer |
-| `mise.run:443` | `setup-mise` composite | mise installer |
-| `releases.starship.rs:443` | mise-managed install of starship | starship binary |
-
-### Security / SBOM / scanning
-
-| Endpoint | Used by | Why |
-|---|---|---|
-| `api.osv.dev:443` | grype / scorecard | OSV vuln database |
-| `vulners.com:443` | grype | vulnerability metadata |
-| `toolbox-data.anchore.io:443` | anchore/sbom-action | SBOM tooling |
-| `api.deps.dev:443` | future deps.dev integration (#877) | package metadata |
-| `api.securityscorecards.dev:443` | scorecard.yml | publish_results upload |
-| `*.codeql.github.com:443` | codeql.yml | CodeQL bundle download |
-
-## Job-level egress notes (legitimate broad-egress jobs)
-
-A few jobs need wider network access than the standard allowlist
-covers. Each carries an inline comment near the harden-runner step
-explaining the deviation so reviewers can audit at a glance.
-
-### `update-deps.yml` — broad GitHub API egress
-
-Polls multiple `github.com/<repo>/releases/latest` endpoints to find
-new tool versions. Allowlist needs to include `api.github.com:443`
-and the raw-content domain for sed-replacing version strings.
-
-### `devcontainer-prebuild.yml` — registry push
-
-Pushes to `ghcr.io:443` with the `packages: write` token. The egress
-allowlist for that job is the standard set plus `ghcr.io` writes.
-
-### `nightly.yml` — `Beta/Nightly Tools Test` job
-
-This job deliberately runs `curl ... | tar -xJf -` against the
-shellcheck release. Justified because the job is `continue-on-error: true`
-and is opt-in (manual or scheduled). Future hardening: download the
-release asset, verify a known hash, then exec — same shape as
-`tools/ci/install-chezmoi-verified.sh`.
-
-## Updating this page
-
-Whenever a job is flipped to `block` mode:
-
-1. Run the audit-mode workflow at least once after every recent
-   workflow change to make sure the harden-runner telemetry reflects
-   reality.
-2. Visit the [step-security dashboard](https://app.stepsecurity.io/)
-   filtered to the repo + job + last 7 days.
-3. Add any endpoints the dashboard reports that aren't already in
-   this page's tables.
-4. Edit the job to set `egress-policy: block` and add the per-job
-   `allowed-endpoints:` block listing only what that specific job
-   needs (not the whole union).
-5. Land the change, watch the first run; if anything fails the run
-   loud, add the missing endpoint and retry.
-
-## References
-
-- `step-security/harden-runner` — [https://github.com/step-security/harden-runner](https://github.com/step-security/harden-runner)
-- `docs/security/SCORECARD.md` — Token-Permissions check ties to harden-runner adoption.
-- Issue [#878](https://github.com/sebastienrousseau/dotfiles/issues/878).

package/docs/security/CI_PINNING.md

@@ -1,129 +0,0 @@
----
-render_with_liquid: false
----
-
-# CI Dependency Pinning Policy
-
-Every external dependency the CI pipeline consumes must be pinned by
-40-hex commit SHA. The policy applies to:
-
-1. **Third-party actions** — `uses: owner/action@<sha>` (already enforced via Scorecard's `Pinned-Dependencies` check at score ≥ 9).
-2. **Reusable workflows in this repo** — `uses: sebastienrousseau/dotfiles/.github/workflows/reusable-X.yml@<sha>` (added with [#855](https://github.com/sebastienrousseau/dotfiles/issues/855); enforced by `tools/ci/lint-reusable-pins.sh`).
-3. **Container base images** — `FROM image:tag@sha256:<digest>` (closed by [#886](https://github.com/sebastienrousseau/dotfiles/pull/886)).
-4. **Release binaries downloaded at build time** — `curl … && echo "<sha256> ..." | sha256sum -c` (closed by [#888](https://github.com/sebastienrousseau/dotfiles/pull/888)).
-
-The sole exception is the SLSA generic reusable workflow. Its bootstrap
-validates that the caller reference has the form `refs/tags/vX.Y.Z` and
-fails when invoked through a bare commit SHA. Therefore
-`generator_generic_slsa3.yml` is pinned to the exact release tag
-`v2.1.0`; the corresponding commit SHA is recorded beside the call site
-and must be verified before any tag bump. OpenSSF Scorecard explicitly
-exempts the SLSA generator from its SHA-pinning check for this constraint.
-
-## Why SHA-pin reusable workflows
-
-When `ci.yml` calls a reusable via `./.github/workflows/reusable-X.yml`,
-GitHub resolves the reusable from the **same ref as the calling
-workflow at run time**. For an in-repo PR that's the PR's branch —
-fine. The risk is the inverse: a malicious push to `main` (or any
-ref the calling workflow might resolve from) can swap reusable
-content under a CI run, with no audit trail in the PR diff.
-
-Pinning to a 40-hex SHA freezes the reusable's content at the
-pinned commit. To swap the reusable, you have to bump every call
-site — visible in the PR diff, reviewable, revertible.
-
-## Acceptable forms
-
-```yaml
-# Acceptable — full SHA pin.
-uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@b0615f8fb5c0f3826f58904a5567eff11b6c500e # main
-```
-
-The trailing comment is a human-readable hint at what the SHA
-represented when it was pinned (typically `main`, sometimes a tag
-like `v0.2.501`). The hint is documentation only — the SHA is what
-GitHub uses.
-
-## Rejected forms
-
-```yaml
-# Rejected — relative path is a mutable ref.
-uses: ./.github/workflows/reusable-shell-lint.yml
-
-# Rejected — branch ref is mutable.
-uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@main
-
-# Rejected — tag ref is mutable (tags can be moved).
-uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@v0.2.501
-```
-
-The `lint-reusable-pins` job in `ci.yml` runs `tools/ci/lint-reusable-pins.sh`
-on every workflow change. The lint fails the build on any of the
-rejected forms above.
-
-## Refreshing pinned SHAs
-
-`bump-reusable-pins.yml` handles this automatically. On every push to
-`main` that touches `.github/workflows/reusable-*.yml`, the bot scans
-caller workflows for stale pins and opens a PR bumping them to the new
-SHA. Signed with `ACTIONS_BOT_SIGNING_KEY` so the resulting commit
-passes `Verify Commit Signatures`.
-
-The manual recipe below stays here as a fallback — for example, if you
-need to bump pins before a merge to main, or if the bot's run failed
-and you want to short-circuit waiting for the next push trigger.
-
-```sh
-# 1. Land the change to the reusable on main via a PR.
-# 2. After merge, capture the new main SHA:
-git fetch origin main
-PIN=$(git rev-parse origin/main)
-echo "$PIN"
-
-# 3. Bump every call site:
-find .github/workflows -name '*.yml' -exec sed -i.bak -E \
-  "s|(/reusable-[a-z0-9-]+\.yml@)[0-9a-f]{40}|\\1${PIN}|g" {} +
-rm -f .github/workflows/*.bak
-
-# 4. Verify the lint still passes:
-bash tools/ci/lint-reusable-pins.sh
-
-# 5. Land the bump on a follow-up PR with a single-purpose commit:
-git commit -am "chore(ci): bump reusable-workflow pins to ${PIN:0:10}"
-```
-
-Whether bumped by the bot or by hand, the resulting PR runs the full
-CI suite — a reviewer still confirms the new reusable content is
-intentional before merge.
-
-## Dependabot
-
-Dependabot's `github-actions` ecosystem now updates full-SHA references to
-same-repository reusable workflows. PR
-[#992](https://github.com/sebastienrousseau/dotfiles/pull/992) verified this
-behavior by moving the reusable workflow baseline from v0.2.511 to the
-immutable v0.2.516 commit alongside the external minor/patch action group.
-
-Keep `bump-reusable-pins.yml` enabled as the immediate post-merge path. It
-updates callers as soon as a reusable workflow changes on `main`, while
-Dependabot provides the scheduled dependency review and grouped update path.
-Both mechanisms must preserve full 40-hex SHA references and pass
-`lint-reusable-pins` plus the egress-policy contract tests.
-
-## Negative test
-
-`tests/unit/ci/test_reusable_pin_lint.sh` deliberately drops an
-unpinned reusable reference into a sandboxed workflow tree and
-asserts that `lint-reusable-pins.sh` exits non-zero with the
-expected error message. The test runs as part of the standard
-test suite — a regression in the lint catches at PR time, not at
-merge time.
-
-## See also
-
-- [#855](https://github.com/sebastienrousseau/dotfiles/issues/855) — original tracking issue.
-- `tools/ci/lint-reusable-pins.sh` — the enforcement script.
-- `tests/unit/ci/test_reusable_pin_lint.sh` — the negative test.
-- `.github/workflows/bump-reusable-pins.yml` — the auto-bump bot.
-- [GitHub: pinning actions to a full-length commit SHA](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions).

package/docs/security/COMMIT_SIGNING.md

@@ -1,138 +0,0 @@
-# Commit Signing — Policy & Setup
-
-Every commit that reaches `main` 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/main.json` declares
-   `required_signatures` on `refs/heads/main`. The rule is part
-   of the repo so it's reproducible across forks. Apply with
-   `gh ruleset import .github/rulesets/main.json`.
-4. **`compliance-guard.yml` workflow** — runs on every PR targeting
-   `main`. 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 `main` 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 main 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/main.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/main.json
-```
-
-(or `-X PUT` against the existing ruleset's ID if it already exists).
-
-## References
-
-- `.github/rulesets/main.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)