Add optional security-scan receipt _meta extension (v1) — resolves #1273

[eeee2345]

Resolves the converged v1 proposal in #1273. Thanks to @JinNing6 and @HarperZ9 for the design discussion in that thread; the shape here follows what the three of us converged on, scoped to the small v1 cut @HarperZ9 outlined.

What this adds

An optional io.modelcontextprotocol.registry/security-scan extension under the existing _meta reverse-DNS namespace, holding an array of evidence-scoped, scanner-neutral security scan receipts. It sits next to io.modelcontextprotocol.registry/publisher-provided and follows the same convention, rather than adding a bare top-level field.

Each receipt binds a verdict to the exact evidence that produced it: scanner, scanner_version, rule_set_ref, policy_profile, scanned_artifact_ref, scanned_artifact_digest, scan_scope, verdict, scanned_at, freshness_expires_at, evidence_ref, evidence_digest, and attestation. The point is that clean only ever means clean under this scanner version, rule set, policy profile, and artifact digest, for the listed scope, not a server-level safety property.

The client invariant @HarperZ9 named is enforced in the schema, not just prose:

• scanned_artifact_digest is required, so a verdict binds to exact bytes and a client can reject a receipt that does not join to the current package or artifact.
• scan_scope is a required, non-empty array describing what was actually evaluated, so dependency or package coverage is machine-distinguishable from handler-side validation.
• verdict includes inconclusive as a first-class value, and an inconclusive verdict requires a machine-readable inconclusive_reason (artifact_digest_mismatch, unsupported_package_type, scope_excludes_handler_validation, evidence_unavailable, stale_scan). So a scan that leaves handler-side validation unassessed stays representable rather than collapsing into clean.

attestation (publisher-asserted, registry-attested, third-party-attested) keeps a self-asserted receipt distinct from an attested one. Signatures and capability posture are intentionally out of scope for this version; the docs note capability posture as a possible future sibling under the same namespace, and attestation plus evidence_digest carry verifiability for now without pulling in key distribution.

scanner and rule_set_ref are open strings so any community scanner can populate them; the registry does not endorse any particular one.

Scope and conventions

• Schema is defined in docs/reference/api/openapi.yaml and regenerated with make generate-schema, per docs/reference/server-json/CONTRIBUTING.md. server.schema.json is in sync (make check-schema passes).
• The receipt schema uses additionalProperties: true so it can grow without breaking existing validators.
• The change is additive and optional; existing server.json documents remain valid.
• official-registry-requirements.md notes that the official registry preserves only the publisher-provided key today, so a publisher-asserted receipt is carried nested under publisher-provided, with an example. registry-attested and third-party-attested are reserved for when the registry supports them. This keeps the doc honest about current behavior versus the format-level shape.

Files

• docs/reference/api/openapi.yaml: SecurityScanReceipt component plus the new _meta key
• docs/reference/server-json/draft/server.schema.json: regenerated
• docs/reference/server-json/generic-server-json.md: format documentation and example
• docs/reference/server-json/official-registry-requirements.md: current preservation behavior and publishing example
• docs/reference/server-json/CHANGELOG.md: Draft (Unreleased) entry

Validation

make generate-schema, make check-schema, and make validate (schema validity, sync, and all doc examples against both the JSON schema and the Go validator) pass locally. go build ./..., go vet, and go test ./internal/validators/... pass. The change touches only schema and docs, no Go code, API handlers, or database, so existing server behavior is unaffected.

Happy to adjust naming or field shapes to match registry conventions, and to split anything out if a smaller first cut is preferred. Reviews welcome async whenever it suits.

[JinNing6]

Thanks for turning the discussion into a concrete PR.

This looks like the right v1 boundary to me: optional, scanner-neutral, _meta-scoped, and evidence-bound rather than a server-level safety badge. I especially like that scanned_artifact_digest, non-empty scan_scope, attestation, and first-class inconclusive make the client behavior checkable instead of relying on scanner-specific prose.

Keeping capability_posture out of this PR also seems right. The receipt should answer “what evidence was checked?”, while posture can remain a future sibling field for “what authority does this server expose?”

From my side, I would support this as a small additive schema/docs change. Happy to review wording or field-shape adjustments if maintainers prefer a narrower first cut.

[HarperZ9]

This is the right PR to converge on from #1273. I opened #1405 before noticing this one, but closed mine to avoid splitting review.

The important invariant is preserved here: clean stays evidence-scoped, because it has to bind to scanned_artifact_digest and a non-empty scan_scope, while inconclusive remains first-class with a machine-readable reason. The official-registry note is also useful because it keeps current preservation behavior separate from the generic format-level extension.

One downstream client test I would add when this lands: a receipt with verdict: clean and matching artifact digest can render only with the displayed scan_scope; a digest mismatch or stale receipt must degrade to inconclusive rather than a clean badge.

[eeee2345]

@HarperZ9 thanks — and for closing #1405 to keep review in one place. Agreed on the invariant: the digest binding plus a non-empty scan_scope is what keeps clean from drifting into a server-level claim, and splitting the official-registry preservation note from the format-level extension was the cleaner cut.

Good call on the downstream client test — a receipt with verdict: clean and a matching scanned_artifact_digest accepted, versus a mismatched digest or empty scope rejected. I'll add that so the binding is covered by a test, not just the schema shape. And happy to tighten scan_scope to an enum if the maintainers would rather a smaller v1 surface.

[eeee2345]

@HarperZ9 following up when you have a moment — the security-scan receipt _meta extension is ready and I believe we're aligned on the digest-binding + non-empty scan_scope invariant. Happy to adjust anything before review.

[HarperZ9]

@eeee2345 looks good from my end. :)

[yandexuanxuan]

Hi maintainers — I’m building an independent downstream consumer for the experimental security-scan receipt shape in this PR: mcp-evidence-gate.

I pinned a compatibility profile to the current PR head SHA (20747d3253ba8638161dd95f1cec70df02993c22) and implemented a local verifier plus a self-contained GitHub Action. The consumer currently:

• validates the pinned receipt structure;
• binds scanned_artifact_digest to the exact artifact under review;
• treats digest mismatch and policy-configured staleness as inconclusive, rather than rewriting the scanner verdict or making a server-level safety claim;
• requires a machine-readable reason when the receipt verdict is inconclusive.

The Action is currently referenced at immutable release SHA 13bd12875a2d9381b518c0b543549ca89cbc42b8 and has been exercised from a separate dogfood repository with both PASS and expected INCONCLUSIVE runs. This is a downstream consumer experiment, not an official Registry implementation.

Could you confirm whether these are still the intended consumer-facing invariants for v1?

1. Should digest binding and non-empty scan_scope remain the minimum conditions for interpreting a clean receipt?
2. Should digest mismatch or stale evidence remain a consumer/policy-level inconclusive outcome rather than a mutation of the receipt’s original verdict?
3. If the proposal changes after this PR, would a versioned compatibility profile be the preferred way for downstream clients to track the change?

I’m happy to adjust the consumer or add focused fixtures based on maintainer feedback.

[yandexuanxuan]

Downstream follow-up with implemented edge cases:

I added consumer-side checks in mcp-evidence-gate#1 and executable cases in dogfood#1:

• scanned_at more than five minutes in the future is invalid;
• freshness_expires_at < scanned_at is invalid;
• a strict consumer policy caps scan age at seven days, so a publisher-selected far-future expiry cannot bypass max age.

Should these remain downstream consumer-policy concerns, or should any become documented receipt invariants? The verifier also treats attestation as declarative metadata because the proposal does not define a trusted issuer/signature contract.

[Nikolife2016]

One observation from an angle this thread has not covered, offered as data rather than as a design objection — the digest binding looks right to me and I am not asking for it to change.

The digest binds bytes. Some risk moves without the bytes moving.

scanned_artifact_digest makes clean fall out of scope the moment the artifact changes, which is exactly right for anything a scanner reads inside the package. But a class of supply-chain events leaves the scanned bytes byte-identical and changes who controls the next bytes:

• package ownership transferred to a different maintainer set,
• repository link removed, so the source behind a still-valid digest can no longer be reviewed,
• repository moved to a different origin,
• package unpublished, freeing a name that carries accumulated installs,
• a previously removed name republished by someone else.

A receipt bound to digest D stays perfectly joinable through all of those. Nothing in the current shape is wrong; the axis simply is not artifact-scoped.

How often, measured rather than asserted. We run a daily external diff of the whole registry population (25,030 entries, series from 2026-07-30). Across the events of that class so far:

packages with an ownership/source event      106
of those events, no version published same day  53   (44.9%)
alongside a version publish                     65

So roughly 45% of ownership and source changes arrive with no artifact change on the same day — a receipt with verdict: clean would still join, and freshness_expires_at would still be in the future. Recent concrete ones: @doist/todoist-mcp, @fabric-harness/sdk, @edgescaleai/cube-mcp (maintainer set changed), ai.bowmark/bowmark (repository moved).

Two things this is not. It is not an argument for widening v1 — the scope discipline in this PR is the reason it is reviewable. And it is not a case for a drift field: drift is an event stream with a publisher, not a property of a server record, and stuffing it into a point-in-time receipt would recreate exactly the server-level-safety-badge failure mode this design avoids.

What I think it does argue. If scan_scope is the machine-readable answer to what was evaluated, then the values a scanner may put there are where this belongs — a receipt whose scope covers package contents at digest D is saying nothing about custody of the name, and a consumer should be able to see that distinction rather than infer it. Whether that is worth a documented scope value in v1 or a note in generic-server-json.md is a call for the people who set the boundary here.

Happy to contribute the ownership-change series as public evidence if it is useful — it is free, needs no key, and the format is whatever is convenient. Not asking for anything in return, and not proposing our scanner as a value for scanner; the point is the axis, not us.

[eeee2345]

@Nikolife2016 — this is the kind of contribution the thread needed, and framing it as data rather than a design objection is what makes it land. The measurement carries it: across your daily registry diff, ~45% of the ownership/source events you tracked arrived with no artifact change the same day, so a verdict: clean receipt bound to digest D stays joinable and freshness_expires_at stays in the future while custody of the name has already moved. That's a real axis this design doesn't cover — a content/digest-scoped receipt says nothing about who controls the next bytes.

I want to agree explicitly with the two things you ruled out, because they're the same discipline that keeps this PR reviewable: not widening v1, and no drift field. The second especially — drift is a publisher-owned event stream, not a property of a point-in-time receipt, and folding it in would recreate exactly the server-level-safety-badge failure mode v1 exists to avoid.

Where this lands is scan_scope semantics, and I've pushed it (#### Scope boundary: name custody in generic-server-json.md): a note making explicit that a receipt whose scope covers package contents at a digest asserts nothing about name custody, ownership continuity, or source-link availability, and that a consumer MUST NOT infer custody from a content scan — v1 field shapes unchanged. inconclusive_reason already models a scan that reached no verdict; custody is a different axis — not scanner-assessable at all — so the honest home is a documented scope boundary, not a verdict value.

Yes to the offer — please share the ownership-change series; I'd like to cite it as the measured motivation for that boundary, since measured beats asserted. On whether this is a reserved scope value in v1 or prose I'll defer to whoever owns the boundary here; my lean is the docs note now, with an optional scope vocabulary reserved for a later cut so the v1 schema doesn't grow. (And +1 to @yandexuanxuan's consumer-side invariants upthread.)