Skip to content

spec: package verification — min pkg verify, fail-closed pulls, a Sigstore bundle on every artifact (inbox#721) - #1585

Closed
bryan-minimal wants to merge 1 commit into
mainfrom
spec/25-pkg-verify
Closed

bryan-minimal wants to merge 1 commit into
mainfrom
spec/25-pkg-verify

Conversation

@bryan-minimal

@bryan-minimal bryan-minimal commented Sep 23, 2026 •

Copy link
Copy Markdown
Member

Spec for the package-verification epic gominimal/inbox#721 (supersedes inbox#348): min pkg verify, fail-closed pulls, and a Sigstore bundle on every artifact's provenance.

Bound to architecture.md @ faccc370: D3 (supply chain and verification), D3.1, "What verified means" (a)–(d), the pkg command tree, exit codes 4 and 6, Security & Compliance use cases 1–3 and 5, AT2. Two rulings requested from the architecture in gominimal/arch#91 (well-known trust-root URL + meta-key custody; stating the post-quantum plane); the spec carries them as open questions and keeps PKV-015 at tier: none until then.

Shape: 20 requirements, PKV-001..020. Two signature planes: the Sigstore bundle (index today, provenance statement per artifact after build-servers#185) as the interoperable plane an auditor verifies with stock cosign v3; the KMS DSSE envelope (ECDSA P-256 + ML-DSA-65) as the post-quantum plane min verifies against a vendored, append-only trust root. Index first, always; fail closed on a required plane's absence; threshold over distinct trusted keys, never first-valid; byte-exact PAE; a cache miss is exit 4, not a verification failure.

Process: foundry spec@0.7.0 template and linter (18 findings, all P004 named-test-not-found, the expected pre-implementation state); stories transcribed byte-for-byte from the epic; interview held; adversarial review against the architecture, the producer's dsse.rs/provenance.rs/commit_index.rs, rcache and the related issues produced 18 confirmed findings, all applied (notably: the sealed map is unsigned so nothing gates on it; commit is reported not asserted because identical rebuilds are never re-uploaded; the RFC 3161 timestamp is the signing time on Rekor v2; the KMS key-window check is self-asserted until build-servers#95; object names follow #185; a new bundled map state instead of redefining signed).

Related: build-servers#185, #230, #322, #329, #332, #338, #86; inbox#582, #583.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added a specification for package verification, including authenticated pulls and signed artifact provenance.
    • Documented trust-root, signature, and provenance checks; verification results and failure behavior; and how verification affects payload commands and host fetches.
    • Added producer requirements, security invariants, and open questions for the verification process.

…store bundle on every artifact (inbox#721)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@bryan-minimal
bryan-minimal requested a review from a team as a code owner September 23, 2026 22:36
@github-actions

Copy link
Copy Markdown
Contributor

Spec lint

docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md — 18 finding(s)

docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:48: P004 PKV-001 names test 'index_bundle_verifies_against_pinned_identity', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:59: P004 PKV-002 names test 'index_bundle_agrees_with_cosign_corpus', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:64: P004 PKV-003 names test 'artifact_hash_bound_to_verified_index', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:75: P004 PKV-004 names test 'envelope_parse_rejects_unknown_fields_and_oversize', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:80: P004 PKV-005 names test 'pae_is_byte_exact', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:85: P004 PKV-006 names test 'role_policy_is_threshold_over_distinct_keys', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:93: P004 PKV-007 names test 'mldsa65_known_answer_and_negative_vectors', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:98: P004 PKV-008 names test 'statement_subject_binding_and_expectations', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:106: P004 PKV-009 names test 'absent_envelope_fails_closed_legacy_json_ignored', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:111: P004 PKV-010 names test 'live_corpus_round_trip', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:115: P004 PKV-011 names test 'pkg_payload_commands_verify_before_print', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:128: P004 PKV-012 names test 'pkg_verify_exit_code_and_json_shape', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:133: P004 PKV-013 names test 'trust_root_parses_vendored_and_override', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:141: P004 PKV-014 names test 'trust_policy_matches_vendored_root', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:149: P004 PKV-016 names test 'artifact_bundle_verified_when_present_absent_policy', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:157: P004 PKV-017 names test 'per_artifact_bundle_statement_bytes_identical', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:162: P004 PKV-018 names test 'materialize_verifies_before_accept', which was not found in the repository
docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md:180: P004 PKV-020 names test 'docs_commands_match_ci_workflow', which was not found in the repository

Advisory. None of this blocks the merge; the review decides.

Advisory, and never a merge gate. Linter: gominimal/foundry@7c939200, spec format: How Minimal Writes Specs.

@coderabbitai

coderabbitai Bot commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: 734f36e9-4dca-4ef8-a6e7-9aad0bf26c42

📥 Commits

Reviewing files that changed from the base of the PR and between 85c9b4a and 73085a3.

📒 Files selected for processing (1)
  • docs/specs/25-spec-pkg-verify/25-spec-pkg-verify.md
 _____________________________________________________________________
< RabbitShergill is my Punjabi cousin. He's a bit musically inclined. >
 ---------------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       /   づ
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Comment @coderabbitai help to get the list of available commands.

@minimal-foundry

Copy link
Copy Markdown
Contributor

Reading 73085a30d32a.

This comment updates when the review finishes.

@bryan-minimal

Copy link
Copy Markdown
Member Author

Replaced by #1586: same spec, one commit with a conforming Conventional Commits header (commitlint rejected spec: and the 111-character header). Branch deleted.

@bryan-minimal
bryan-minimal deleted the spec/25-pkg-verify branch September 23, 2026 22:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant