docs(spec): harden the release and dependency supply chain

[antstanley]

Note

Stacked PR 14 of 16 — part of stack #35, which targets main.
Base: #31 (spec/eliminate-secret-leakage-logs-spans) · Followed by: #34

This PR's diff shows only its own change. Merge the stack bottom-up; do not merge this before its base.

Why it sits at position 14: Distribution and CI surfaces. Mutually scoped with #25 on the installer: #25 owns the checksum fail-open, this owns the --version traversal, signing and attestation.

Scope of this PR

This PR currently carries the change spec. It will also carry the implementation plan and the build work for that spec — plan and code land as later commits on this same branch, so the spec, its plan, and its implementation review and merge as one unit.

Review order within the PR: spec first, then plan, then implementation.

---

Change spec proposing hardening of the release and dependency supply chain.

Problem. Eleven confirmed findings across four surfaces: the publish-npm job resolves dependencies at run time while holding id-token: write publishing rights; release.yml carries one workflow-level permissions block instead of per-job least privilege; release installs bypass the committed lockfile; two of four distribution channels ship with no build provenance; there is no dependency-advisory gate, so a lockfile that fails an advisory check today surfaces nothing; and install.sh interpolates its --version operand into a download URL without validation.

Proposed delta.

• Per-job least-privilege permissions: blocks, with publint/attw moved out of the publishing job into a permissions: {} validation job.
• Pin every run-time dependency resolution inside the publish job.
• --frozen-lockfile on every release install, after regenerating the stale Node lockfile.
• actions/attest-build-provenance on the binary and container builds — the two channels lacking what npm --provenance and PyPI Trusted Publishing already give the other two — with install.sh verifying via gh attestation verify and failing loudly rather than silently.
• Pattern-validate the installer's --version operand before any URL is constructed.
• Separately shippable: a cargo deny advisory gate backed by a new deny.toml, with a stated policy — no entry fails the build; an entry carrying a reachability rationale and an expiry warns until that expiry — plus a resolved-graph dependency-policy check for the pre-release crypto crates.

Corrections to the scan, from reading the workflows and manifests.

• There are four unpinned package fetches in publish-npm (npm@latest, @napi-rs/cli, npx --yes publint, npx --yes @arethetypeswrong/cli), not five. The fifth cited site is an unfrozen install of the Lambda dependency graph — a different defect, also fixed here.
• There are two pyo3 advisories, not one: RUSTSEC-2025-0020 (fixed in 0.24.1) and RUSTSEC-2026-0177 (fixed in 0.29.0). bindings/python/Cargo.toml:12 pins "0.22", so no cargo update can reach either fix — this needs a version bump, not a refresh.
• Two scan findings contradict each other on rsa 0.10.0-rc.18. g4-no-dependency-advisory-gate-in-ci describes it as a dev-only edge that does not ship; crates/adapters/Cargo.toml:19 declares it under [dependencies] (and separately at :40 under [dev-dependencies]), so it does ship. The spec follows the code. This does not make RUSTSEC-2023-0071 reachable — all four RsaPrivateKey::new sites remain #[cfg(test)] — but the crate is in the shipped graph, not only the test graph.
• --no-frozen-lockfile is release-only. ci.yml uses plain pnpm install, which pnpm freezes automatically under CI.
• Anchor drift resolved in favour of the code: rsa 0.10.0-rc.18 starts at Cargo.lock:3714; verify_rsa_pkcs1v15 at kms/mod.rs:269; setup.sh key generation at :9-16.

Cross-reference note. The installer's checksum verification failing open is owned by 2026-08-05-fail_closed_across_config_and_adapters.md (#25) and is cross-referenced rather than restated. That file is not on main yet, so the two links resolve once #25 merges.

Drafted with the spec-creator plugin from a deep security scan of the repository at 53cbdec9. Spec only — no source, workflow, or .gitignore changes.