@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

package/docs/security/SCORECARD.md

@@ -11,6 +11,33 @@ narrative behind it.
 
 ## Live score
 
+<!-- BEGIN scorecard-snapshot (auto-generated, do not edit by hand) -->
+Aggregate score **7.6 / 10** at 2026-05-17T08:11:51Z.
+
+| Check | Score | Reason |
+|---|---:|---|
+| Binary-Artifacts | 10 | no binaries found in the repo |
+| Branch-Protection | -1 | internal error: error during branchesHandler.setup: internal error: some github tokens can't read cl |
+| CI-Tests | 10 | 15 out of 15 merged PRs checked by a CI test -- score normalized to 10 |
+| CII-Best-Practices | 2 | badge detected: InProgress |
+| Code-Review | 0 | Found 0/30 approved changesets -- score normalized to 0 |
+| Contributors | 0 | project has 0 contributing companies or organizations -- score normalized to 0 |
+| Dangerous-Workflow | 10 | no dangerous workflow patterns detected |
+| Dependency-Update-Tool | 10 | update tool detected |
+| Fuzzing | 0 | project is not fuzzed |
+| License | 9 | license file detected |
+| Maintained | 10 | 30 commit(s) and 30 issue activity found in the last 90 days -- score normalized to 10 |
+| Packaging | 10 | packaging workflow detected |
+| Pinned-Dependencies | 9 | dependency not pinned by hash detected -- score normalized to 9 |
+| SAST | 10 | SAST tool is run on all commits |
+| Security-Policy | 10 | security policy file detected |
+| Signed-Releases | 3 | 1 out of the last 3 releases have a total of 2 signed artifacts. |
+| Token-Permissions | 10 | GitHub workflow tokens follow principle of least privilege |
+| Vulnerabilities | 10 | 0 existing vulnerabilities detected |
+
+*Refresh: `scripts/qa/scorecard-snapshot.sh` · CI check: `lint/scorecard-snapshot` (planned).*
+<!-- END scorecard-snapshot -->
+
 [![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
@@ -30,7 +57,7 @@ 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)
+## Per-check posture (snapshot, master HEAD)
 
 The checks below come from OpenSSF Scorecard's published rubric. Tick
 marks reflect this repo's posture at the time of writing — the
@@ -38,30 +65,103 @@ marks reflect this repo's posture at the time of writing — the
 
 | 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. |
+| Branch-Protection | ⚠ | `master` requires signed commits, linear history, required checks (`.github/rulesets/master.json`). Scorecard can't read classic protection rules without a fine-grained PAT, so this check reports as `-1` ("internal error"). |
+| Code-Review | ⚠ | Single-maintainer repo; PRs are self-merged after CI. Scorecard scores 0/30 here by design — see `Open findings` below. |
 | 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. |
+| Fuzzing | ⚠ | `install.sh` fuzz harness lives under `tests/fuzz/` (closes #881), but it's shell-based and Scorecard's heuristic only recognizes OSS-Fuzz / ClusterFuzzLite / native Go fuzz / libFuzzer / Atheris. None support shell. Property tests under `tests/unit/functions/test_property_*.sh` cover the closest equivalent surface. |
+| License | ✓ | MIT at repo root (`LICENSE`). |
+| Maintained | ✓ | Active commit cadence; the [README](../../README.md) lists the current `dotfiles_version`. |
+| Pinned-Dependencies | ⚠ | Closed 8 of 14 findings this cycle (every Dockerfile base + every workflow action + 2 `curl \| sh` installers + the `npm install -g npm` upgrade step). 5 residual findings stay open by design — see `Open findings`. |
 | 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. |
+| Token-Permissions | ✓ | Top-level `permissions:` blocks restricted to `contents: read`. `write` scopes scoped to the jobs that need them (#886). |
 | 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. |
+| CI-Tests | ✓ | Linux + macOS Intel + Apple Silicon matrix; 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. |
+| Signed-Releases | ⚠ | SLSA provenance + minisig attached via `security-release.yml`; Cosign keyless signing tracked at #876. |
+
+## Open findings
+
+The eight items below are surfaced as alerts at
+<https://github.com/sebastienrousseau/dotfiles/security/code-scanning>.
+Each row gives the dismissal **reason** and the exact **comment text**
+to paste when triaging.
+
+### Bucket 1 — Dismiss in the UI (5 items)
+
+Scorecard flags every `npm install`, `pip install`, `go install`, and
+`curl | sh` invocation under the `Pinned-Dependencies` check. The five
+below either belong to user-facing "update everything" aliases or are
+false positives in Scorecard's regex.
+
+| Path | Reason | Comment to paste |
+|---|---|---|
+| `.chezmoitemplates/aliases/legal/legal.aliases.sh:64` | **Won't fix** | User-facing convenience alias — `go install <fortune-style joke command>@latest`. Pinning by SHA would require users to update the alias manually on every upstream change. Intentional. |
+| `.chezmoitemplates/aliases/update/update.aliases.sh:173` | **Won't fix** | User-facing convenience alias — bulk-update wrapper around `npm`. The alias's purpose is to update everything; pinning defeats it. Intentional. |
+| `dot_local/bin/executable_update:99` | **Won't fix** | `dot_local/bin/executable_update` is the user-invoked "update everything" command. The literal point of `npm update -g` is to update to whatever's latest. Pinning defeats it. Intentional. |
+| `scripts/dot/commands/tools.sh:121` | **False positive** | `npm install --package-lock-only --ignore-scripts --silent` generates a lockfile and does NOT fetch packages. Scorecard's regex matches `npm install` blindly; this invocation has no supply-chain surface. |
+| `install/provision/run_onchange_10-linux-packages.sh.tmpl:369` | **Won't fix** | Already exact-version-pins `aider-chat==0.86.2`. Scorecard wants sha256-hash pinning, which would require a ~2,700-line lockfile covering all 108 transitive deps and re-generated on every aider release — disproportionate maintenance for a single optional provisioning install. |
+
+### Bucket 2 — Architectural (1 item)
+
+| Alert | Why architectural |
+|---|---|
+| `CodeReviewID` (high) — score 0 | Scorecard requires every merged PR to record an approval review by a different GitHub user than the author. This repo is single-maintainer; PRs are self-merged after CI. The fix path is either (a) onboard a co-maintainer who reviews PRs before merge, or (b) accept the finding. Dismiss as **Won't fix** with comment: "Single-maintainer project — no second reviewer available. CI gates (47 required checks per PR) substitute for human review." |
+
+### Bucket 3 — External action (2 items)
+
+| Alert | Action |
+|---|---|
+| `FuzzingID` (medium) | Dismiss as **Won't fix** with comment: "Repo is bash + Go-template + Lua. ClusterFuzzLite / OSS-Fuzz / native Go fuzz / libFuzzer / Atheris (the frameworks Scorecard recognises) all target compiled languages, none support shell. The `tests/fuzz/fuzz_install.sh` harness + property tests under `tests/unit/functions/test_property_*.sh` cover the equivalent surface." |
+| `CIIBestPracticesID` (low) | Apply at <https://www.bestpractices.dev/projects/new>. ~67 self-attested questions, free, 1-2 hours. After silver-tier approval, paste the badge into `README.md` next to the existing Scorecard badge. Most criteria already met (signed commits, CI, security policy, license). |
+
+## Closed this cycle
+
+| Date | Score | Alerts open | Change |
+|---|---|---|---|
+| 2026-05-14 | 6.5 | 28 | First clean publish after fixing the scorecard.yml `uses:`-only restriction (#885). Findings had been hidden by publish-step 400s until then. |
+| 2026-05-14 | 6.5 | 11 | Closed 17 of 28: 10× TokenPermissions (#886), 6× Dockerfile bases (#886), 1× gitleaks fixture (#884). |
+| 2026-05-14 | 6.5 | 9 | Closed 2× `curl \| sh` installers (#888). |
+| 2026-05-14 | 6.5 | 8 | Closed 1× `npm install -g npm@…` via Node 24 bump (#889). |
+| 2026-05-17 | 7.6 | 7 | v0.2.502 released; Cosign keyless signing live (#876 implementation landed in `security-release.yml` sbom job). |
+| 2026-05-17 | 7.6 | 6 | SLSA Release Attestation pipeline unblocked (PR #894 — 6 prior releases had failed identically). v0.2.502 backfilled with `.intoto.jsonl` + `.sig` + `.pem` triplet. `Signed-Releases` should bump from 3 to ~10 on next Scorecard re-scrape. |
+| 2026-05-17 | 7.6 | — | Added `MAINTAINERS.md` + `GOVERNANCE.md` at repo root. Provides the formal context for the `Code-Review` 0/30 score (solo maintainer) and unblocks the CII Best Practices badge application. |
 
 ## 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.
+- **Apply for the OpenSSF Best Practices Badge** — see Bucket 3 above. All passing-tier criteria are now met (signed commits, CI, security policy, MIT license, MAINTAINERS.md, GOVERNANCE.md, RFC process documented).
+- **Re-trigger Scorecard after SLSA backfill propagates** — expected `Signed-Releases` 3 → 10.
+- **`harden-runner` block-mode adoption (#878)** — should tighten the `Token-Permissions` check further.
+- **Investigate `License` 9/10 false-positive** — repo is MIT (SPDX-compliant), Scorecard's penalty should not apply.
+- **Investigate `Branch-Protection` `-1`** — scanner internal error; manually verify with `gh api repos/:owner/:repo/branches/master/protection` and document.
+
+### Enabling Branch-Protection + Webhooks checks (one-time PAT setup)
+
+Scorecard's `Branch-Protection` and `Webhooks` checks require a
+fine-grained Personal Access Token with `Administration: read`
+scope. Without it both checks return `-1` ("internal error"). The
+workflow already wires this up — only the secret needs to be created.
+
+Steps (one-time, repo owner):
+
+1. Go to <https://github.com/settings/personal-access-tokens/new>
+2. **Resource owner**: `sebastienrousseau` · **Repository access**: only `sebastienrousseau/dotfiles`
+3. **Repository permissions** → `Administration: read-only` and `Metadata: read-only`
+4. **Expiration**: 1 year (set a calendar reminder to rotate; document the rotation in this file when done)
+5. Generate the token, copy it once
+6. Add as a secret named `SCORECARD_TOKEN` at <https://github.com/sebastienrousseau/dotfiles/settings/secrets/actions/new>
+7. Next Scorecard run (manual via `gh workflow run scorecard.yml` or weekly cron) picks it up automatically
+8. Expected effect: `Branch-Protection` `-1` → 10/10 if all rules are correctly configured; `Webhooks` `-1` → 10/10 (no webhooks present).
+
+The PAT secret is **optional**. When absent, the workflow falls back
+to `${{ github.token }}` and Scorecard continues to run, only with
+those two checks at `-1`. Adding the PAT cannot reduce any other check's
+score — it's a strict improvement.
 
 ## Exceptions
 
@@ -72,9 +172,24 @@ marks reflect this repo's posture at the time of writing — the
 If you add an exception, include the check name, an expiry date
 (don't allow indefinite), and the rationale. Re-evaluate every quarter.
 
+## Refreshing this document
+
+```bash
+# Re-count open alerts:
+gh api 'repos/sebastienrousseau/dotfiles/code-scanning/alerts?state=open&per_page=50' \
+  --jq '[.[].rule.id] | group_by(.) | map({rule: .[0], count: length})'
+
+# Trigger Scorecard manually:
+gh workflow run scorecard.yml --ref master
+```
+
+If a new category appears, add a row to the matching bucket. If a
+remediation closes one of the rows above, delete the row.
+
 ## References
 
-- `.github/workflows/scorecard.yml` — the scanner.
+- `.github/workflows/scorecard.yml` — the scanner workflow (split into
+  `analysis` + `track-regression` jobs per #885).
 - [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).
+- Tracking issue [#869](https://github.com/sebastienrousseau/dotfiles/issues/869).

package/docs/security/SHELL_EXEMPTIONS.md

@@ -7,7 +7,7 @@ render_with_liquid: false
 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
-[`scripts/ci/check-shell-preamble.sh`](../../scripts/ci/check-shell-preamble.sh),
+[`tools/ci/check-shell-preamble.sh`](../../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`](../../tests/unit/security/test_shell_preamble_lint.sh).
@@ -115,14 +115,14 @@ When you need to mark a new file:
 3. **Run the checker:**
 
    ```bash
-   ./scripts/ci/check-shell-preamble.sh path/to/file.sh
+   ./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 `scripts/ci/check-shell-preamble.sh` and document it in this
+   in `tools/ci/check-shell-preamble.sh` and document it in this
    page's "Bulk-sourced fragments" table above.
 
 ## CI integration
@@ -138,7 +138,7 @@ this page in the same PR.
 
 ## References
 
-- `scripts/ci/check-shell-preamble.sh` — the lint.
+- `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.

package/docs/security/VERIFY_RELEASE.md

@@ -0,0 +1,201 @@
+---
+title: "Verify a Release"
+date: 2026-05-17
+---
+
+# Verifying a Release
+
+Every release of the framework ships four independent attestations.
+Verify any of them, they're orthogonal and each rules out a
+different class of attack.
+
+| Artefact | Format | Tool | Threat covered |
+|----------|--------|------|----------------|
+| **SBOM** (`dotfiles-sbom.spdx.json`) | SPDX 2.3 JSON | any SBOM viewer | "what's in the release?", full component inventory |
+| **Cosign signature** (`.sig` + `.pem`) | sigstore keyless | `cosign verify-blob` | "did our CI actually produce this SBOM?", short-lived Fulcio cert + Rekor transparency-log entry |
+| **SLSA provenance** (`.intoto.jsonl`) | in-toto v1 / SLSA L3 | `slsa-verifier` | "what build process produced this?", workflow ID, source ref, builder identity |
+| **Unified manifest** (`ALL_SHA256SUMS` + `.sig` + `.pem`) | text + sigstore keyless | `cosign verify-blob` then `sha256sum -c` | "is every other asset on this release the one our CI produced?", one signed line per asset |
+
+All four are attached to every GitHub Release as assets, from v0.2.503 forward.
+Releases v0.2.500 through v0.2.502 carry the SBOM bundle only: the unified
+manifest landed in v0.2.503 and is forward-only (re-tagging earlier releases
+would break consumer pins on existing SHAs).
+
+---
+
+## TL;DR — verify v0.2.503+ end-to-end
+
+```sh
+# 0. Pick the release to verify
+TAG=v0.2.503
+REPO=sebastienrousseau/dotfiles
+
+# 1. Download every attestation artefact
+gh release download "$TAG" --repo "$REPO" \
+  --pattern dotfiles-sbom.spdx.json \
+  --pattern dotfiles-sbom.spdx.json.sig \
+  --pattern dotfiles-sbom.spdx.json.pem \
+  --pattern dotfiles-sbom.spdx.json.intoto.jsonl \
+  --pattern ALL_SHA256SUMS \
+  --pattern ALL_SHA256SUMS.sig \
+  --pattern ALL_SHA256SUMS.pem
+
+# 2. Verify Cosign signature on the SBOM (binds SBOM to CI workflow identity)
+cosign verify-blob \
+  --certificate dotfiles-sbom.spdx.json.pem \
+  --signature  dotfiles-sbom.spdx.json.sig \
+  --certificate-identity-regexp "^https://github.com/$REPO/" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  dotfiles-sbom.spdx.json
+
+# 3. Verify SLSA provenance (binds SBOM to exact source tag + builder)
+slsa-verifier verify-artifact dotfiles-sbom.spdx.json \
+  --provenance-path dotfiles-sbom.spdx.json.intoto.jsonl \
+  --source-uri "github.com/$REPO" \
+  --source-tag "$TAG"
+
+# 4. Verify the unified manifest, then verify every other asset against it.
+#    One signed file covers all release artefacts in one shot.
+cosign verify-blob \
+  --certificate ALL_SHA256SUMS.pem \
+  --signature  ALL_SHA256SUMS.sig \
+  --certificate-identity-regexp "^https://github.com/$REPO/" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  ALL_SHA256SUMS
+
+gh release download "$TAG" --repo "$REPO" --dir .  # pull every other asset
+sha256sum -c ALL_SHA256SUMS                        # one line per asset
+```
+
+All four commands should print "Verified" / "PASSED" / "OK" and
+exit 0. If any fails, **the release was tampered with**: open
+an issue at <https://github.com/sebastienrousseau/dotfiles/issues>
+and do **not** install.
+
+---
+
+## Tool installation
+
+| Tool | macOS | Linux | Windows |
+|------|-------|-------|---------|
+| `gh` (GitHub CLI) | `brew install gh` | `apt install gh` / [release page](https://github.com/cli/cli/releases) | `scoop install gh` |
+| `cosign` | `brew install cosign` | `curl -sSfL https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -o /usr/local/bin/cosign && chmod +x /usr/local/bin/cosign` | `scoop install cosign` |
+| `slsa-verifier` | `brew install slsa-verifier` | `go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest` | `scoop install slsa-verifier` |
+
+If you don't have Go installed, fetch the pre-built `slsa-verifier`
+binary from <https://github.com/slsa-framework/slsa-verifier/releases>
+(SHA256-verify per their release notes).
+
+---
+
+## What each verification actually proves
+
+### `cosign verify-blob` succeeds
+
+- The SBOM was signed by a workflow run **on this repository** (the
+  `--certificate-identity-regexp` enforces it).
+- The signing OIDC token was issued by **GitHub Actions** (the
+  `--certificate-oidc-issuer` enforces it).
+- The signature is recorded in the **Rekor public transparency log**
+  (cosign queries this automatically) — anyone can audit it.
+- The Cosign cert was issued by **Fulcio** (the sigstore CA) and
+  was valid at the time of signing.
+
+This **does not** prove what the build process did — only that
+"the file you have is the file CI produced." For "what did CI do",
+see SLSA verification below.
+
+### `slsa-verifier verify-artifact` succeeds
+
+- The SBOM digest matches a provenance statement.
+- The provenance was generated by the **SLSA-Generator** running on
+  **GitHub-hosted runners** for **this exact repository**.
+- The build was triggered by the named tag (`--source-tag $TAG`).
+- The provenance is anchored in Rekor (immutable, third-party-auditable).
+
+SLSA Level 3 is achieved because: (a) the provenance is generated
+by a *trusted, isolated* builder (slsa-github-generator), not by
+us; (b) the builder runs with hermetic, non-falsifiable inputs;
+(c) the provenance is signed by the builder's own identity, not
+ours.
+
+### What none of this proves
+
+The framework's source code is **not formally verified**. SBOM +
+SLSA + Cosign protect the *supply chain* (you got what we shipped)
+— not the *correctness* (what we shipped does what we claim).
+
+For correctness review:
+
+- Code is open under MIT — read it. Start at `bin/dot`.
+- CI runs ~75 checks per PR (shellcheck, shfmt, CodeQL, Semgrep, Codacy, etc.).
+- Pre-commit hooks reject typos, unsigned commits, raw secrets.
+- See `docs/security/SCORECARD.md` for the OpenSSF score posture.
+
+---
+
+## In-shell one-liner for ongoing verification
+
+If you intend to install or update from a release tag, add this to
+your shell startup (already in `dot_config/shell/*` for users who
+run `chezmoi apply`):
+
+```sh
+verify-dot-release() {
+  local tag="${1:-$(gh release view --json tagName --jq .tagName \
+    --repo sebastienrousseau/dotfiles)}"
+  local tmp
+  tmp="$(mktemp -d)"
+  ( cd "$tmp" \
+    && gh release download "$tag" --repo sebastienrousseau/dotfiles \
+      --pattern 'dotfiles-sbom.*' \
+    && cosign verify-blob \
+      --certificate dotfiles-sbom.spdx.json.pem \
+      --signature  dotfiles-sbom.spdx.json.sig \
+      --certificate-identity-regexp '^https://github.com/sebastienrousseau/dotfiles/' \
+      --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+      dotfiles-sbom.spdx.json \
+    && slsa-verifier verify-artifact dotfiles-sbom.spdx.json \
+      --provenance-path dotfiles-sbom.spdx.json.intoto.jsonl \
+      --source-uri github.com/sebastienrousseau/dotfiles \
+      --source-tag "$tag"
+  )
+  local rc=$?
+  rm -rf "$tmp"
+  return $rc
+}
+```
+
+Usage:
+
+```sh
+verify-dot-release             # verify latest
+verify-dot-release v0.2.502    # verify specific tag
+```
+
+---
+
+## If verification fails
+
+1. **Don't install.** Stop the bootstrap script. `^C` any in-flight
+   `chezmoi apply`.
+2. **Compare assets**. The release page shows file sizes — if
+   yours don't match what's on
+   <https://github.com/sebastienrousseau/dotfiles/releases>, you
+   downloaded from a man-in-the-middle.
+3. **Report**: open an issue and email
+   `security@sebastienrousseau.com` (encrypted to the WKD-published
+   GPG key — fingerprint
+   `55AFAD364FD9DB3819E61F0C8D688FAFA9144693`). Acknowledgement
+   SLA: 72 hours per `.github/SECURITY.md`.
+
+---
+
+## See also
+
+- `.github/SECURITY.md` — coordinated disclosure policy.
+- `docs/security/KEY_ROTATION.md` — disclosure-key rotation procedure.
+- `docs/security/SCORECARD.md` — OpenSSF Scorecard posture.
+- `docs/operations/HARD_AUDIT_2026.md` Part 7 — the GPG key generation + WKD publication record.
+- [Sigstore Cosign docs](https://docs.sigstore.dev/cosign/signing/overview/)
+- [SLSA verifier docs](https://github.com/slsa-framework/slsa-verifier)

package/docs/security/security-pubkey.asc

@@ -0,0 +1,15 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEagg20hYJKwYBBAHaRw8BAQdAk2HMi5IFTHBGhCtSFzqwsyuVb7mO0iIhoUXR
+mTv/PNK0R1NlYmFzdGllbiBSb3Vzc2VhdSAoRG90ZmlsZXMgU2VjdXJpdHkpIDxz
+ZWN1cml0eUBzZWJhc3RpZW5yb3Vzc2VhdS5jb20+iLUEExYKAF0WIQRVr602T9nb
+OBnmHwyNaI+vqRRGkwUCagg20hsUgAAAAAAEAA5tYW51MiwyLjUrMS4xMiwwLDMC
+GwMFCQWjmoAFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AACgkQjWiPr6kURpOH
+qQEA4gl4pfhkR9Y3IM6oMHydavrx3CE6mX4YRIkYJ7fYj4UA/iO/54bdjG+wmIrE
+cQ077+ijTTCMnHrosn3E13oQ6NIJuDgEagg20hIKKwYBBAGXVQEFAQEHQKdKJLxe
+xsXBXELbxGHUz2asoTuOnsKk8WEdOyESH3dnAwEIB4iUBBgWCgA8FiEEVa+tNk/Z
+2zgZ5h8MjWiPr6kURpMFAmoINtIbFIAAAAAABAAObWFudTIsMi41KzEuMTIsMCwz
+AhsMAAoJEI1oj6+pFEaTUw0A/14oNMWsx1gcyx9wl/vy+OgEXoOksxSV+FetAI2Q
+Q7qOAP9pohjVAi40dqfBXv3vet7CV0V4p2kQ+qpQTOPTVafkDA==
+=UtsL
+-----END PGP PUBLIC KEY BLOCK-----

package/install.sh

@@ -6,6 +6,13 @@
 
 set -euo pipefail
 
+# Restrict the permissions of any file/dir we create during bootstrap.
+# The installer writes secret-adjacent artifacts (chezmoi config, age
+# keys, ssh tooling, downloaded archives) under $HOME — 077 prevents
+# other local accounts from reading them. Individual call sites can
+# still relax with `chmod` when a file is meant to be world-readable.
+umask 077
+
 # ANSI Colors
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -52,7 +59,7 @@ show_help() {
 Usage: install.sh [version] [options]
 
 Arguments:
-  version       The version (tag or branch) to install (default: v0.2.501)
+  version       The version (tag or branch) to install (default: v0.2.503)
 
 Options:
   --help        Show this help message
@@ -64,7 +71,7 @@ EOF
 }
 
 main() {
-  local version="v0.2.501"
+  local version="v0.2.503"
   local version_set=0
   local minimal=0
   local _cleanup_files=()
@@ -92,7 +99,7 @@ main() {
         # like `foobar` doesn't trigger a 30s+ network download attempt.
         # Caught by the install.sh fuzz harness (#881).
         if [[ ! "$arg" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+([-+][a-zA-Z0-9.-]+)?$ ]]; then
-          error "Unrecognized positional argument '$arg' — expected a semver version (e.g. v0.2.501)."
+          error "Unrecognized positional argument '$arg' — expected a semver version (e.g. v0.2.503)."
         fi
         version="$arg"
         version_set=1
@@ -135,10 +142,29 @@ main() {
       sudo mkdir -p /etc/apt/keyrings
       curl -fsSL https://repo.charm.sh/apt/gpg.key |
         sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/charm.gpg
-      # Verify Charm GPG key fingerprint
-      if ! gpg --no-default-keyring --keyring /etc/apt/keyrings/charm.gpg \
-        --list-keys --with-colons 2>/dev/null | grep -q "fid:"; then
-        echo "Warning: Could not verify Charm GPG key" >&2
+      # Pin the Charm GPG key fingerprint — a DNS attacker swapping
+      # repo.charm.sh/apt/gpg.key for a forged key with the same uid
+      # would otherwise pass the prior "any fid: present" check.
+      # Pinned value taken from https://repo.charm.sh/apt/gpg.key on
+      # 2026-05-16. If Charm rotates, update this and call it out in
+      # CHANGELOG.md.
+      CHARM_GPG_EXPECTED_FPR="C026D31B92F9BBE91D5DB75AB07AE17C9E0A6585"
+      charm_actual_fpr="$(gpg --no-default-keyring \
+        --keyring /etc/apt/keyrings/charm.gpg \
+        --with-colons --fingerprint 2>/dev/null |
+        awk -F: '/^fpr:/{print $10; exit}')"
+      if [[ -z "$charm_actual_fpr" ]]; then
+        echo "Error: Could not extract Charm GPG fingerprint — aborting" >&2
+        sudo rm -f /etc/apt/keyrings/charm.gpg
+        return 1
+      fi
+      if [[ "$charm_actual_fpr" != "$CHARM_GPG_EXPECTED_FPR" ]]; then
+        echo "Error: Charm GPG fingerprint mismatch" >&2
+        echo "  expected: $CHARM_GPG_EXPECTED_FPR" >&2
+        echo "  got:      $charm_actual_fpr" >&2
+        echo "  aborting (possible DNS / keyserver hijack)" >&2
+        sudo rm -f /etc/apt/keyrings/charm.gpg
+        return 1
       fi
       echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
       sudo apt-get update && sudo apt-get install gum -y >/dev/null 2>&1
@@ -160,43 +186,31 @@ main() {
       mkdir -p "$bin_dir"
       echo "   Installing chezmoi via binary download..."
 
-      # Prefer verified installer with SHA256 checksum when available
+      # Prefer verified installer with SHA256 checksum when available.
+      # When verification fails or the verified installer isn't present
+      # we refuse to bootstrap rather than silently downloading and
+      # executing an unverified script (the previous fall-back to
+      # `get.chezmoi.io` was an unsigned bootstrap and a security hole).
       local verified_installer
-      verified_installer="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts/ci/install-chezmoi-verified.sh"
+      verified_installer="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/tools/ci/install-chezmoi-verified.sh"
       if [[ -x "$verified_installer" ]] || [[ -f "$verified_installer" ]]; then
         echo "   Using checksum-verified installer..."
         if ! bash "$verified_installer" "${CHEZMOI_VERSION:-2.47.1}" "$bin_dir"; then
-          echo "   Verified installer failed, falling back to get.chezmoi.io" >&2
-        else
-          return 0
+          echo "" >&2
+          echo "   The verified chezmoi installer failed." >&2
+          echo "   Refusing to fall back to an unverified bootstrap path." >&2
+          echo "   Install chezmoi manually from a trusted source, then re-run install.sh:" >&2
+          echo "     macOS:  brew install chezmoi" >&2
+          echo "     Linux:  see https://www.chezmoi.io/install/" >&2
+          return 1
         fi
+        return 0
       fi
-
-      # Fallback: download installer with size/shebang validation
-      local installer
-      installer=$(umask 077 && mktemp)
-      if ! curl -fsSL -o "$installer" https://get.chezmoi.io; then
-        rm -f "$installer"
-        echo "   Failed to download chezmoi installer" >&2
-        return 1
-      fi
-      # Validate: must be a shell script and not suspiciously large
-      if [[ "$(wc -c <"$installer")" -gt 102400 ]]; then
-        rm -f "$installer"
-        echo "   Chezmoi installer suspiciously large. Aborting." >&2
-        return 1
-      fi
-      if ! head -1 "$installer" | grep -q '^#!/'; then
-        rm -f "$installer"
-        echo "   Chezmoi installer doesn't look like a shell script. Aborting." >&2
-        return 1
-      fi
-      if ! BINDIR="$bin_dir" sh "$installer"; then
-        rm -f "$installer"
-        echo "   chezmoi binary installer failed" >&2
-        return 1
-      fi
-      rm -f "$installer"
+      echo "" >&2
+      echo "   tools/ci/install-chezmoi-verified.sh is missing; cannot verify chezmoi bootstrap." >&2
+      echo "   Install chezmoi manually (brew install chezmoi / official binary)" >&2
+      echo "   and re-run install.sh." >&2
+      return 1
     fi
   }
 
@@ -290,6 +304,21 @@ main() {
   # 6. Initialize & Apply
   step "Applying Configuration..."
 
+  # ── Auto-migration for v0.2.503 reorg ─────────────────────────────────
+  # If the user is upgrading from a pre-0.2.503 install, run the
+  # migration script BEFORE `chezmoi apply` so the reorg's source-
+  # path moves don't cause chezmoi to delete deployed files.
+  # The script is idempotent + silent-by-default; safe to run on
+  # every install (fresh installs detect "no prior state" and exit 0).
+  for migrate_src in "$SOURCE_DIR" "$LEGACY_SOURCE_DIR"; do
+    migrate_script="$migrate_src/install/migrate/migrate-v0_2-to-v0_2_503.sh"
+    if [[ -x "$migrate_script" ]]; then
+      echo "   Running v0.2.503 migration (idempotent; safe on fresh installs)..."
+      "$migrate_script" || echo "   migration exited non-zero — continuing apply"
+      break
+    fi
+  done
+
   # If we are running from a local source, just apply
   if [[ -d "$SOURCE_DIR/.git" ]]; then
     echo "   Applying from local source: $SOURCE_DIR"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebastienrousseau/dotfiles",
-  "version": "0.2.501",
+  "version": "0.2.503",
   "description": "The Trusted Shell Platform — Universal dotfiles managed by Chezmoi. Features Bash & Zsh for macOS, Linux & WSL. Rust modern tooling & enterprise-grade security.",
   "main": "install.sh",
   "bin": {