feat(npmprofile): support building a caller-specified source ref for dispatch retries #81

Activity

1. yunseo-kim

   added 2 commits that reference this issue on Aug 13, 2026

   docs(decisions): add ADRs 0079/0080 for caller-specified build source…

   ...

   09ade19

   docs(specs): Specify tags-only source-ref input and ADR 0080 verifica…

   ...

   fba994d
2. yunseo-kim commented on Aug 13, 2026

   

   yunseo-kim

   on Aug 13, 2026

   Last edited by yunseo-kim

   MemberAuthor

   More actions

   Design resolution and specification revision complete

   This issue's root cause was re-analyzed from scratch and resolved as a design decision, then specified. Summary of what landed:

   Root cause (verified)

   Release retry was structurally blocked by a three-layer conflation of the invocation ref (where the workflow was dispatched from) with the built source ref (what content is built and attested):

   1. ADR 0032 restricted manual dispatch to tag refs only, so a fixed pipeline on another ref (e.g. main) could never rebuild an existing tag.
   2. The specs required the caller's github.ref/github.sha to byte-equal the release tag/commit.
   3. The verification policy compared the signing certificate's platform-fixed source claims (Fulcio OIDC extensions .13/.14 — always the invocation context) directly against the release tag, making a dispatch retry unverifiable even if built.

   Ecosystem research confirmed this is platform-inherent: GitHub OIDC claims always describe the invocation context, and the predecessor ecosystem (slsa-github-generator) never shipped dispatch tag identity either — slsa-github-generator#1947 remained open through the end of maintenance. The same problem class was independently reported for osv-scanner in google/osv-scanner#632.

   Accepted ADRs (merged in #83)

   • ADR 0079 — Every producer profile offers an optional, tags-only source-ref input (npm is the first adopter). When supplied, the built source is that tag instead of the invocation ref; existence, resolution, and version-match checks are fail-closed. Tags-only was chosen over arbitrary refs to avoid resurrecting an "arbitrary release button" while structuring away retag cost. Partially supersedes ADR 0032's dispatch-ref restriction.
   • ADR 0080 — binding model: verification policy source expectations bind the signed built-source fields in provenance; certificate source claims are authenticated against a signed invocation record in provenance instead. The built commit is thus builder-attested (same class as other externalParameters), while the platform still anchors builder identity, repository, invocation origin, and run. When source-ref is unset, signed bundles are byte-identical to the single-identity contract. Partially supersedes ADR 0068 section 4 only.

   Specification revision (merged in #84)

   • core-profile-contract.md: new cross-profile built source identity invariant.
   • js-ts-npm-package-profile.md: ninth public input source-ref; runtime guards, supported triggers, and PRE-mutation/mutation concurrency keys re-anchored on the built release tag; new pre-mutation diagnostic windlass.verify.error.source-ref-invalid (registered in the diagnostic registry ahead of implementation, per the mutation-queue-overflow precedent); dispatch-retry-success and single-identity-default fixtures.
   • js-ts-npm-provenance-publish.md: conditional input_ref / invocation_ref / invocation_revision members in the closed source group; nine-input completeness mapping; signer-identity table rebound per ADR 0080.
   • slsa-provenance-v1.md, identity-and-buildtypes.md, verification-policy-and-fixtures.md: two-identity model throughout — policy binds signed built-source fields, certificate .13/.14 claims bind the signed invocation record; source-digest-mismatch / source-ref-mismatch diagnostics redefined to the invocation comparison.
   • Bilingual READMEs: nine-input contract, "Fixed-pipeline release retry" feature, two-identity verification model, and the ecosystem limitation write-up.

   Remaining before this issue closes

   1. Implementation (next): workflow source-ref input + build checkout ref, workflow_metadata.go guard split, provenance source-group generation, verification policy/cert-claim rebinding, fixtures and conformance tests.
   2. Dogfood retry (ADR 0079/0080 confirmation criteria): dispatch vers-js v0.1.2 from main with source-ref: refs/tags/v0.1.2 after the pin bump, exercising the path that originally failed in run 31622651874.

   This issue closes when the implementation merges and the dogfood confirms the retry path end-to-end.
3. yunseo-kim

   added a commit that references this issue on Aug 13, 2026

   feat(npmprofile): Add tags-only source-ref input for fixed-pipeline r…

   ...

   496e40e
4. yunseo-kim commented on Aug 13, 2026

   

   yunseo-kim

   on Aug 13, 2026

   MemberAuthor

   More actions

   Implementation update: the source-ref capability has landed on main via #86 (merge commit 496e40e).

   Delivered behavior

   • New optional, tags-only source-ref input on js-ts-npm-package-slsa3.yml (full refs/tags/<name> only). When omitted, behavior is byte-compatible with the previous contract (golden-tested).
   • Pre-checkout resolution: the internal npm-profile-source-ref subcommand validates the input, resolves and peels the tag in an isolated fetch, proves the target is a commit, and the package checkout is pinned to the resolved commit SHA. Missing, unresolvable, non-commit, version-mismatched, or invocation-conflicting refs fail closed with windlass.verify.error.source-ref-invalid before any registry or build work. No tag is ever created, moved, or deleted.
   • The signed SLSA v1 predicate records the built source identity (source.ref/source.revision), and when source-ref is supplied additionally records the invocation context as signed conditional members (source.input_ref, source.invocation_ref, source.invocation_revision; all-present-or-absent, explicit null rejected). Omitted input keeps the previous predicate bytes exactly.
   • ADR 0080 verification binding: explicit policy binds the signed built-source fields, while certificate source claims bind the signed invocation record, with exact single-identity fallback. The signing step consumes the built release identity through the digest-verified handoff (build job outputs), and a mismatch is a policy failure (exit 1, release-ref-mismatch).
   • Release concurrency groups are canonicalized to the full-ref form ${{ inputs.source-ref || github.ref }} across build/sign/publish and enforced by workflowcheck, so a dispatch retry and a tag-triggered run for the same release intent share one mutation group regardless of invocation ref. Because the raw input participates in group computation and GitHub expressions cannot normalize it, only the exact empty string counts as omitted; whitespace-only or padded spellings are rejected (source-ref-invalid).
   • Fixtures: 2 accepted + 9 rejected fixtures registered under the provenance-inputs phase with their canonical primary diagnostics.

   Verification

   • Test-first throughout: each behavioral change was captured as a failing test in a detached worktree from main before its implementation landed; every commit is independently green with DCO sign-off.
   • Gates: go test ./..., go test -race ./..., golangci-lint, actionlint, fixture-check (full index + provenance-inputs phase), and workflow-check (all jobs + npm-only profile) all pass; PR checks (CodeQL, OSV, dependency-review, semgrep, DCO, etc.) are green.
   • An independent five-lane review (goal/constraints, hands-on QA, code quality, security, context mining) iterated to an unconditional pass; its findings — signing-path built-identity wiring, input normalization, dispatcher error classification, and the concurrency-spelling gap — were fixed in dedicated commits before merge.

   Remaining

   The live acceptance step is still pending: a real workflow_dispatch retry of vers-js v0.1.2 from main with source-ref: refs/tags/v0.1.2 (ADR 0079 confirmation). This issue stays open until that dogfood run confirms the provenance binds to the tag commit while run_invocation records the dispatch ref.
5. yunseo-kim

   added a commit that references this issue on Aug 13, 2026

   docs(dogfood): Add npm M1 verification procedure (#87)

   ...

   72f92c9
6. yunseo-kim commented on Aug 14, 2026

   

   yunseo-kim

   on Aug 14, 2026

   MemberAuthor

   More actions

   Closing: the capability this issue asked for is implemented (#86) and was exercised live end-to-end up to an unrelated, separately tracked failure.

   Live evidence from the second vers-js dogfood attempt (run 31737001312, dispatched from main with release_tag=v0.1.2):

   • The caller supplied source-ref: refs/tags/v0.1.2 (full-ref form on dispatch) and the reusable workflow accepted it under the tags-only validation rules.
   • The build job checked out and packed the tag content, not the dispatch ref.
   • The sign job received the resolved built identity exactly as specified: BUILT_REF=refs/tags/v0.1.2, BUILT_REVISION=68e6f0018d6824167ec490243b17a9edd6ba8fc7 (the annotated tag's peeled commit), while the invocation context stayed refs/heads/main @ 7851c5f832abce998fa7071941a94ad580afef60 — the dispatch retry carrying the release tag identity, which is precisely this issue's scenario.

   The run did not reach provenance emission: it failed in the sign job's early npm OIDC exchange preflight for an unrelated response-contract gap (full report on #30; follow-up ADR in progress). The signed-Statement field values (externalParameters.source.*, internalParameters exactly {}) remain pinned by #86's unit/golden coverage and will be observed on the live registry attestation in the next dogfood run as part of #30's acceptance, so no work remains under this issue.
7. yunseo-kim

   closed this as completedon Aug 14, 2026
8. yunseo-kim

   added a commit that references this issue on Aug 14, 2026

   docs(decisions): Add ADR 0081 npm OIDC exchange response contract (#88)

   ...

   16a2de2