docs(design): freeze connector-registry index schema + trust model (R-1)#2631
Merged
Conversation
R-1 of the v0.18 registry epic (#2625). The security-critical foundation the registry install/publish/audit/index-CI all trust: a signed index envelope (payload + signatures[], JCS-canonicalized, verify-before-parse with parse-time duplicate-key rejection), per-name identity pinning (anchored cosign certificate-identity), a separate reviewer-gated ROOT key vs an unattended-nightly FRESHNESS key (à la TUF's timestamp role — the root key never signs unattended), build-time-fixed trust anchors with server-side co-signature rotation + ERR_TRUST_ANCHOR_EXPIRED fail-closed, 7-day staleness + version-bumping heartbeat, embedded revocation, and the registration-vs-version-bump index-CI split. Companion JSON Schema (Draft 2020-12) + a sample index that validates against it live under docs/design-documents/registry-index/. Twice security-reviewed. The second review's 5 required fixes are folded in (freshness-key split; rotation never runtime-auto-trusted; wider overlap window + trust-anchor-exhaustion; offline root-key backup; parse-time duplicate-key rejection) plus its non-blocking additions (index-CI runs the provenance checks; pattern-tightness lint; the binary-release-pipeline trust assumption stated). Deferred refinements (canonicalization library, per-artifact-vs-version provenance shape — blocked on the publish Action, epic step 4 — TUF-lite→TUF trigger, delisting, pruning) don't block freezing the MVP schema. Tier 3 (design doc). Advances ROADMAP §7 (v0.18 registry), #2625 (R-1). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B3cLokwNJYLLBpdyt3cgGr
Confirm review found the 5 fixes were only in the preamble; the §a-§f body and
the closing summary still framed them as open (self-contradictory). Propagated
throughout: §a sign/verify now carries the signature `role` + the freshness-key
acceptance rule + parse-time duplicate-key rejection; §b sets maxStaleness=7d,
adds ERR_TRUST_ANCHOR_EXPIRED, and corrects the "doesn't split into roles" claim;
§d adds the §c-step-7 provenance re-verification and the expectedIdentityPattern
tightness lint; OPEN QUESTIONS 1/2/3/9/12 rewritten as RESOLVED; the closing
"frozen vs open" summary rewritten to match; schema gains revokedBy/yankedBy and
the artifact.url description is corrected ("inside the signed payload"). Schema
+ sample re-validated (Draft 2020-12); markdownlint clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B3cLokwNJYLLBpdyt3cgGr
…TEGRITY Final R-1 confirm review flagged that §a step 2c described the two error codes as what read like the same condition twice. Tighten the boundary: ERR_TRUST_ANCHOR_EXPIRED when no keyId in signatures[] matches any compiled-in anchor at all (unrecognized key — the upgrade-lag case); ERR_INDEX_INTEGRITY when a keyId is recognized but the cryptographic verification itself fails (tampering/corruption). Wording tightening only; no design change. Closes the last residual nit from the frozen-R-1 review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B3cLokwNJYLLBpdyt3cgGr
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
R-1 of the v0.18 registry epic (#2625) — freezes the index schema + trust model, the security-critical foundation the registry's install/publish/audit/index-CI all trust. Companion JSON Schema (Draft 2020-12) + a validating sample under
docs/design-documents/registry-index/.Trust model (hardened by two security reviews)
payload+signatures[], JCS-canonicalized, verify-before-parse, with explicit parse-time duplicate-key rejection (JCS alone doesn't stop a producer/verifier parser differential).^...$) cosign--certificate-identity-regexp+--certificate-oidc-issuer, plus SLSA subject-digest +builder.idbinding; a valid signature by the wrong identity →ERR_IDENTITY_MISMATCH.timestamp/bumpversionon byte-identicalconnectors[].signatures[].rolecarries this. The root key is never used unattended.ERR_TRUST_ANCHOR_EXPIRED(fail closed, never stale cache).index.version+ signedtimestamp, 7-day staleness + nightly version-bumping heartbeat; embedded (non-flattened) revocation; registration-vs-version-bump index-CI split with independent re-verification.Review trail
Twice security-reviewed; the second review's 5 required fixes are all folded in (freshness-key split, rotation semantics, wider window + exhaustion, offline backup, duplicate-key rejection) + its non-blocking additions. Deferred refinements (canonicalization lib, per-artifact-vs-version provenance — blocked on epic step 4 — TUF trigger, delisting, pruning) don't block freezing.
Tier 3 (design doc). Schema well-formed + sample validates (Draft 2020-12, verified). markdownlint clean. Advances #2625 (R-1).
🤖 Generated with Claude Code
https://claude.ai/code/session_01B3cLokwNJYLLBpdyt3cgGr