@sebastienrousseau/dotfiles 0.2.520 → 0.2.522

package/docs/security/VERIFICATION_VALIDATION.md

@@ -1,228 +0,0 @@
----
-render_with_liquid: false
----
-
-# Verification and Validation Report
-
-## Document Control
-
-| Field | Value |
-|-------|-------|
-| Document ID | VV-DOT-001 |
-| Version | 0.2.501 |
-| Date | 2026-03-20 |
-| Author | Repository Maintainer |
-| Status | Active |
-| Classification | Internal |
-| Standard | ISO 13485:2016 Sections 7.3.6 / 7.3.7 (adapted) |
-
----
-
-## Purpose
-
-This document constitutes the formal Verification and Validation (V&V) report for the chezmoi-managed dotfiles repository, adapted from ISO 13485:2016 Sections 7.3.6 (Design and Development Verification) and 7.3.7 (Design and Development Validation) for infrastructure-as-code.
-
-**Verification** confirms that each design output meets its corresponding design input requirement through inspection, analysis, and testing. **Validation** confirms that the deployed system satisfies its intended use under representative operating conditions (Linux, macOS, WSL).
-
-All verification activities are executed through automated CI pipelines, pre-commit hooks, and the repository test framework. Evidence is retained in CI logs, test output, and this document.
-
----
-
-## Verification Matrix
-
-| Req ID | Requirement | Verification Method | Test File(s) | Result |
-|--------|-------------|---------------------|--------------|--------|
-| VR-01 | Shell scripts pass ShellCheck (severity=error) | Static analysis via `shellcheck --severity=error -e SC1091 -e SC2030 -e SC2031` | `ci.yml`, `ci-enforced.yml`, pre-commit hook | Pass |
-| VR-02 | All scripts have `set -euo pipefail` | Pattern scan across all `.sh` files; CI enforcement | `ci-enforced.yml`, `compliance-guard.yml` | Pass |
-| VR-03 | No secrets in source control (gitleaks clean) | Gitleaks scan with `config/gitleaks.toml` ruleset | Pre-commit hook, `security-enhanced.yml` | Pass |
-| VR-04 | Cross-platform compatibility (BSD + GNU) | Dual-platform CI matrix (ubuntu-latest, macos-latest) | `cross-platform-test.yml` | Pass |
-| VR-05 | TLS enforcement (no insecure curl/wget) | Pattern blocking for `curl -k`, `--insecure`, `wget --no-check-certificate` | Pre-commit hook, `compliance-guard.yml` | Pass |
-| VR-06 | Permission controls (no chmod 777/666) | CI pattern scan blocks world-writable permissions | Pre-commit hook, `compliance-guard.yml` | Pass |
-| VR-07 | Signed commits enforced | Pre-push hook verifies `git verify-commit` for all commits in range | `scripts/git-hooks/pre-push`, `compliance-guard.yml` | Pass |
-| VR-08 | Conventional commit format | Pre-commit hook validates `feat:`, `fix:`, `docs:` prefixes | Pre-commit hook (conventional-commits) | Pass |
-| VR-09 | Template rendering correctness | `chezmoi apply --dry-run` on Linux and macOS CI runners | `ci.yml` (Linux + macOS matrix), `tests/unit/test_*.sh` | Pass |
-| VR-10 | Alias system functional | Unit tests source alias files and verify command availability | `tests/unit/aliases/test_*.sh` (104 files) | Pass |
-| VR-11 | Neovim config loads without errors | Headless Neovim launch with error detection | `tests/unit/neovim/test_*.sh` (15 files) | Pass |
-| VR-12 | Fish/Zsh/Nushell configs valid | Syntax validation and functional tests per shell | `tests/unit/fish/` (33), `tests/unit/shell/` (12), `tests/unit/nushell/` (5) | Pass |
-| VR-13 | CI pipelines execute successfully | GitHub Actions workflow status across all triggers | `ci.yml`, `ci-enforced.yml`, `compliance-guard.yml`, `cross-platform-test.yml`, `security-enhanced.yml`, `codeql.yml` | Pass |
-| VR-14 | Pre-commit hooks functional | Hook execution via `pre-commit run --all-files` | `config/pre-commit-config.yaml` | Pass |
-| VR-15 | Age encryption operational | Chezmoi age-encrypted file decryption during apply | `chezmoi apply --dry-run` (encrypted targets), integration tests | Pass |
-
----
-
-## Validation Summary
-
-### Coverage Metrics
-
-| Metric | Value | Threshold | Status |
-|--------|-------|-----------|--------|
-| Total test files | 430 | N/A | Measured |
-| Total assertions | 2,217 | N/A | Measured |
-| Pass rate | 100% | 100% | Pass |
-| Module coverage | 100% | >= 95% | Pass |
-
-### Category Breakdown
-
-| Category | Test Files | Status |
-|----------|-----------|--------|
-| Alias files | 104 | Tested |
-| Function files | 76 | Tested |
-| Fish functions + conf.d | 33 | Tested |
-| Misc / compliance | 34 | Tested |
-| Dot CLI | 30 | Tested |
-| Diagnostics | 28 | Tested |
-| Shell configs | 20 | Tested |
-| Ops | 18 | Tested |
-| Install | 17 | Tested |
-| Security | 16 | Tested |
-| Neovim Lua configs | 15 | Tested |
-| Theme | 11 | Tested |
-| Tools | 7 | Tested |
-| Nushell configs | 6 | Tested |
-| Secrets | 5 | Tested |
-| Integration tests | 10 | Tested |
-| **Total** | **430** | **All pass** |
-
-### Validation Environments
-
-| Environment | OS | Shell | Bash Version | Status |
-|-------------|-----|-------|--------------|--------|
-| CI (Linux) | Ubuntu latest | Bash | 5.x | Validated |
-| CI (macOS) | macOS latest | Zsh | 3.2 (system) | Validated |
-| Local (Linux) | CachyOS / Arch | Fish, Zsh, Bash | 5.x | Validated |
-| Local (WSL) | Ubuntu | Bash | 5.x | Validated |
-
----
-
-## Test Framework Architecture
-
-### Directory Structure
-
-```
-tests/
-├── framework/
-│   ├── test_runner.sh     # Test executor — discovers and runs all test_*.sh files
-│   ├── assertions.sh      # 16 assertion functions (assert_equals, assert_contains, etc.)
-│   └── mocks.sh           # Mock utilities for isolating external dependencies
-├── unit/
-│   ├── aliases/           # Alias and command-surface tests
-│   ├── functions/         # Function behavior tests
-│   ├── dot-cli/           # `dot` command workflow tests
-│   ├── shell/             # Shell integration and completion tests
-│   ├── fish/              # Fish function and completion tests
-│   ├── nushell/           # Nushell configuration tests
-│   ├── nvim/              # Neovim configuration tests
-│   └── test_*.sh          # 425 unit test files total
-├── integration/
-│   └── test_*.sh          # 11 integration test files
-└── performance/
-    └── benchmark_runner.sh # Performance regression benchmarks
-```
-
-### Execution Model
-
-1. `test_runner.sh` recursively discovers all `test_*.sh` files under `tests/`.
-2. Each test file is executed in a subshell with `assertions.sh` sourced.
-3. Tests source bash files directly from the repository (not Go templates).
-4. `mocks.sh` provides stubs for external tools (`chezmoi`, `git`, `brew`, etc.).
-5. Exit codes and assertion counts are aggregated into a final report.
-
-### Assertion Library
-
-| Function | Purpose |
-|----------|---------|
-| `assert_equals` | Exact string equality |
-| `assert_not_equals` | String inequality |
-| `assert_contains` | Substring match |
-| `assert_not_contains` | Substring absence |
-| `assert_starts_with` | Prefix match |
-| `assert_ends_with` | Suffix match |
-| `assert_matches` | Regex match |
-| `assert_file_exists` | File presence |
-| `assert_file_not_exists` | File absence |
-| `assert_directory_exists` | Directory presence |
-| `assert_command_exists` | Command availability |
-| `assert_exit_code` | Process exit code |
-| `assert_empty` | Empty string |
-| `assert_not_empty` | Non-empty string |
-| `assert_true` | Boolean truth |
-| `assert_false` | Boolean false |
-
----
-
-## Traceability Matrix
-
-This matrix maps compliance controls from COMPLIANCE.md to verification requirements defined in this document.
-
-### SOC 2 Type II Traceability
-
-| SOC 2 Control | Description | Verification Requirement(s) |
-|---------------|-------------|----------------------------|
-| CC6.1 | Logical Access Security | VR-06 (Permission controls), VR-15 (Age encryption) |
-| CC6.8 | Unauthorized Code Protection | VR-07 (Signed commits), VR-03 (No secrets) |
-| CC7.1 | System Operations | VR-05 (TLS enforcement), VR-13 (CI pipelines) |
-| CC7.2 | Change Detection | VR-14 (Pre-commit hooks), VR-08 (Conventional commits) |
-| CC8.1 | Change Management | VR-07 (Signed commits), VR-08 (Conventional commits), VR-13 (CI pipelines) |
-| A1.2 | Audit Logs | VR-13 (CI pipelines — logs retained in GitHub Actions) |
-
-### ISO 27001 Traceability
-
-| ISO Control | Description | Verification Requirement(s) |
-|-------------|-------------|----------------------------|
-| A.9.1.1 | Access Control Policy | VR-06 (Permission controls), VR-15 (Age encryption) |
-| A.9.4.1 | Information Access Restriction | VR-06 (No chmod 777/666) |
-| A.12.1.2 | Change Management | VR-07 (Signed commits), VR-08 (Conventional commits) |
-| A.12.6.1 | Technical Vulnerability Management | VR-03 (Gitleaks), VR-05 (TLS enforcement) |
-| A.13.1.1 | Network Controls | VR-05 (TLS enforcement) |
-| A.14.2.5 | Secure Engineering | VR-01 (ShellCheck), VR-02 (set -euo pipefail), VR-04 (Cross-platform) |
-| A.14.2.8 | System Security Testing | VR-09 (Template rendering), VR-10 (Aliases), VR-11 (Neovim), VR-12 (Shell configs) |
-
-### GDPR / Privacy Traceability
-
-| Requirement | Description | Verification Requirement(s) |
-|-------------|-------------|----------------------------|
-| Data Minimization | Limit data collection | VR-03 (No secrets in source) |
-| Integrity | Protect against tampering | VR-07 (Signed commits), VR-14 (Pre-commit hooks) |
-| Encryption | Protect data at rest | VR-15 (Age encryption operational) |
-
----
-
-## Acceptance Criteria
-
-All of the following criteria must be satisfied for this V&V report to remain valid.
-
-| Criterion | Verification Method | Required Outcome |
-|-----------|---------------------|------------------|
-| All unit and integration tests pass | `./tests/framework/test_runner.sh` | Exit code 0, 0 failures |
-| ShellCheck clean | `shellcheck --severity=error` on all `.sh` files | Zero findings |
-| Gitleaks clean | `gitleaks detect --config config/gitleaks.toml` | Zero findings |
-| Chezmoi dry-run clean | `chezmoi apply --dry-run` on Linux and macOS | Exit code 0, no errors |
-| Pre-commit hooks pass | `pre-commit run --all-files` | Exit code 0 |
-| Cross-platform CI green | `cross-platform-test.yml` on ubuntu-latest and macos-latest | All jobs pass |
-| Module coverage at threshold | Test runner coverage report | >= 95% (currently 100%) |
-| No world-writable permissions | `compliance-guard.yml` pattern scan | Zero `chmod 777` or `chmod 666` matches |
-| No insecure TLS patterns | `compliance-guard.yml` pattern scan | Zero `curl -k` or `wget --no-check-certificate` matches |
-| All commits signed | `git verify-commit` on HEAD~50..HEAD range | All commits verified |
-
----
-
-## Sign-off
-
-| Role | Name | Date | Signature |
-|------|------|------|-----------|
-| Repository Owner | | | |
-| Security Reviewer | | | |
-| Quality Assurance | | | |
-| Release Manager | | | |
-
----
-
-## References
-
-- [ISO 13485:2016](https://www.iso.org/standard/59752.html) — Medical devices, Quality management systems
-- [ISO 27001:2022](https://www.iso.org/standard/27001) — Information security management
-- [SOC 2 Type II](https://www.aicpa.org/soc2) — Trust Services Criteria
-- [SLSA Framework](https://slsa.dev/) — Supply chain Levels for Software Artifacts
-- [ShellCheck](https://www.shellcheck.net/) — Static analysis for shell scripts
-- [Gitleaks](https://gitleaks.io/) — Secrets detection
-- [Chezmoi](https://www.chezmoi.io/) — Dotfiles manager

package/docs/security/VERIFY_RELEASE.md

@@ -1,201 +0,0 @@
----
-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 `SECURITY.md`.
-
----
-
-## See also
-
-- `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

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