Skip to content

docs(security): cosign verify-blob trust model + cert-subject lookup#3793

Merged
bokelley merged 2 commits intomainfrom
bokelley/docs-verify-tarballs
May 1, 2026
Merged

docs(security): cosign verify-blob trust model + cert-subject lookup#3793
bokelley merged 2 commits intomainfrom
bokelley/docs-verify-tarballs

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

@bokelley bokelley commented May 1, 2026

Summary

Adds `docs/reference/verifying-protocol-tarballs.mdx` — a dedicated reference for verifying AdCP protocol bundle signatures with cosign keyless. Updates `docs/building/schemas-and-sdks.mdx` to use the canonical regex and link to the new doc.

Why

Adopters running `@adcp/sdk sync-schemas` against v3.0.1+ saw cryptic verification failures ("none of the expected identities matched") because the cert subject for those releases is `release.yml@refs/heads/3.0.x` — not `refs/heads/main` like v3.0.0. The SDK's regex was a literal allowlist that didn't include `3.0.x`. The fix on the consumer side is straightforward (broaden the regex), but until now the "why" wasn't documented anywhere — every consumer who hit the failure had to reason through it from scratch.

This doc:

  1. Explains the trust model — keyless Sigstore via GitHub Actions OIDC, what each verification check binds (signature math vs identity match), and why the AdCP-specific part is just "workflow file path + release-line ref".
  2. Recommends the canonical `cosign verify-blob` invocation with the `refs/(heads|tags)/.*` regex.
  3. Explains why the regex is a wildcard, not a literal — the upstream `release.yml` `on.push.branches` allowlist is the trust gate; consumer regexes that mirror it are a maintenance liability.
  4. Tables the cert subject for every released version so consumers can sanity-check what they're seeing.
  5. Documents the degraded modes — pre-v3.0.0 (no sigs), out-of-band republishes (no sigs) — so SDKs distinguish "sidecars absent" (degrade to checksum-only) from "sidecars present but invalid" (hard fail).
  6. Links to the SDK source-of-truth files so fourth-party SDK authors can mirror the pattern.

Companion SDK fixes

SDK PR Status
adcp-client (TS) adcontextprotocol/adcp-client#1243 Broaden regex from `(main|2.6.x)` literal to `(heads|tags)/.*` — fixes the v3.0.1+ break
adcp-client-python adcontextprotocol/adcp-client-python#343 Add `tags` for forward-compat (already accepts all branches)
adcp-go n/a Already on `refs/(heads|tags)/.*`

Files

Change File
New doc `docs/reference/verifying-protocol-tarballs.mdx`
Update existing doc to reference + use canonical regex `docs/building/schemas-and-sdks.mdx`
Add to nav (default version + flat top-level groups for non-default) `docs.json`
Empty changeset (docs-only) `.changeset/docs-verifying-protocol-tarballs.md`

Test plan

  • `npm run test:docs-nav` passes
  • JSON valid (`docs.json` parses)
  • CI green
  • Mintlify renders correctly (visual check on preview)

🤖 Generated with Claude Code

bokelley and others added 2 commits May 1, 2026 18:19
Adds docs/reference/verifying-protocol-tarballs.mdx covering the
keyless Sigstore trust model for AdCP protocol bundles, the
recommended verify-blob invocation, and a per-release cert-subject
table so consumers know what to expect.

Updates docs/building/schemas-and-sdks.mdx to use the canonical
refs/(heads|tags)/.* regex (was refs/heads/.*) and link to the new
doc.

The new doc explains why a wildcard branch component is correct: the
release.yml workflow's own on.push.branches allowlist is what gates
which refs can produce a signature, so mirroring that list in every
consumer's regex was a maintenance liability that silently broke
v3.0.1+ verification when the 3.0.x maintenance branch was cut.

Companion SDK fixes: adcontextprotocol/adcp-client#1243 (TS),
adcontextprotocol/adcp-client-python#343 (Python). adcp-go was
already on the canonical pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@bokelley bokelley merged commit bf36e02 into main May 1, 2026
17 checks passed
@bokelley bokelley deleted the bokelley/docs-verify-tarballs branch May 1, 2026 22:30
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