Use /protocol/{version}.tgz for schema sync instead of per-file downloads

[bokelley]

The AdCP spec repo now publishes a single gzipped bundle per version at /protocol/{version}.tgz (and /protocol/latest.tgz for the dev snapshot). The bundle contains schemas + compliance storyboards + openapi, wrapped under a single adcp-{version}/ directory for safe extraction. This SDK can replace the current per-file sync with one HTTP request.

Current state

schemas/cache/ contains a per-file mirror of the spec schemas, with .hashes.json used to skip re-fetching unchanged files. That's clever but requires many HTTP round trips per sync and maintenance of the hash map.

Proposed change

One fetch + verify + extract:

import hashlib, tarfile, urllib.request
from pathlib import Path

VERSION = \"latest\"  # or pin to a released semver
BASE = f\"https://adcontextprotocol.org/protocol\"

tgz = Path(f\"{VERSION}.tgz\")
sha = Path(f\"{VERSION}.tgz.sha256\")
urllib.request.urlretrieve(f\"{BASE}/{VERSION}.tgz\", tgz)
urllib.request.urlretrieve(f\"{BASE}/{VERSION}.tgz.sha256\", sha)

expected = sha.read_text().split()[0]
got = hashlib.sha256(tgz.read_bytes()).hexdigest()
if got != expected:
    raise RuntimeError(f\"checksum mismatch: {got} != {expected}\")

with tarfile.open(tgz) as t:
    t.extractall(\"schemas/cache\", filter=\"data\")
# Resulting layout: schemas/cache/adcp-{VERSION}/{schemas,compliance,openapi}/

Why

• One request instead of ~250. The bundle is ~1.4 MB gzipped for the full schema tree.
• Integrity built in. SHA-256 sidecar at /protocol/{version}.tgz.sha256 guarantees the bytes haven't changed.
• Immutable caching on pinned versions. /protocol/3.1.0.tgz is served with Cache-Control: immutable, max-age=31536000 — pin once, trust forever.
• Storyboards come for free. The same bundle contains compliance/ with the full storyboard tree — if this SDK ever wants to run storyboards locally, the fixtures are already extracted.
• Retires .hashes.json. Checksum is the file itself, not a map you have to keep in sync.

Discovery endpoint

/protocol/ returns a JSON manifest listing available versions + the latest dev bundle. Useful for "pin when available, fall back to latest" logic.

Related

• Upstream spec change: Move storyboards back to adcp repo for versioned release adcp#2176 (merged as #2265)
• Bundle layout + stability contract: https://adcontextprotocol.org/docs/building/schemas-and-sdks#one-shot-protocol-bundle

Layout inside adcp-{version}/ is a stable contract within a given major version.

[bokelley]

Heads up: signature verification arriving for the tarball.

adcontextprotocol/adcp#2273 adds Sigstore detached signatures next to every released /protocol/{version}.tgz. New sidecars:

Path	Purpose
/protocol/{version}.tgz.sig	Detached Sigstore signature
/protocol/{version}.tgz.crt	Fulcio-issued signing certificate (PEM)

The signature is keyless OIDC — bound to the GitHub Actions release workflow identity, no long-lived AdCP signing key. SHA-256 alone protects against in-transit tampering; the Sigstore signature additionally proves the bundle came from adcontextprotocol/adcp/.github/workflows/release.yml and not just from adcontextprotocol.org.

Suggested behavior in the schema sync

After verifying the SHA, attempt signature verification when sidecars are present. Treat missing sidecars as a warning rather than a failure (older releases predate signing).

# Use the `sigstore` package on PyPI (https://pypi.org/project/sigstore/).
from sigstore.verify import Verifier, VerificationMaterials, policy

sig = fetch_optional(f"{base}/{version}.tgz.sig")
crt = fetch_optional(f"{base}/{version}.tgz.crt")
if sig and crt:
    Verifier.production().verify(
        materials=VerificationMaterials.from_blob(
            blob=tarball_bytes, signature=sig, certificate_pem=crt,
        ),
        policy=policy.AnyOf([
            policy.Identity(
                identity=re.compile(
                    r"^https://github\.com/adcontextprotocol/adcp/\.github/workflows/release\.yml@refs/heads/.*$"
                ),
                issuer="https://token.actions.githubusercontent.com",
            ),
        ]),
    )
else:
    log.warning("no Sigstore signature for %s.tgz — checksum-only trust", version)

/protocol/ discovery JSON now surfaces signature / certificate URLs per version plus the expected identity, so the sync can read them rather than hardcoding paths.

Manual verification

cosign verify-blob \
  --signature 3.1.0.tgz.sig \
  --certificate 3.1.0.tgz.crt \
  --certificate-identity-regexp '^https://github\.com/adcontextprotocol/adcp/\.github/workflows/release\.yml@refs/heads/.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  3.1.0.tgz

Docs: https://adcontextprotocol.org/docs/building/schemas-and-sdks#verifying-protocol-bundle-signatures