Verifier Provenance Disclosure
Companion to Cross-Custodian Attestation Convergence (which creates the supersession link this discloses) and System Design (the verification contract this extends).
Where this sits in the chain of custody
Holder claim integrity and cross-custodian convergence fix the network’s internal integrity: a holder can’t misclaim a credential, and when Custodian A, Custodian B, and Issuer C all touch the same record, the system resolves that automatically (or escalates the genuine ambiguity to an admin). But all of that resolution stays internal — nothing carries it to the verifier, the party the whole network exists to serve.
Concretely: once convergence links Custodian A’s or B’s Tier-2 credential as superseded by Issuer C’s Tier-1 one, a verifier handed A’s or B’s original credential — still a completely valid, unrevoked, correctly-signed VC — gets no indication whatsoever that a more authoritative record now exists. It verifies as fully active, full stop.
Why this isn’t a simple field addition
provenance_tier is derived purely from the presented VC’s own type array, never a database
read — deliberately, since verification is stateless by design. superseded_by_credential_id is
structurally different: it’s a mutable pointer set after issuance, so it can never be part of an
immutable signed payload. There’s no way for a verifier’s own submitted VC bytes to ever carry this
fact, however the extraction code is written.
The good news: this exact problem is already solved once, for revocation. The live revocation status check already does exactly this shape of thing — a live, source-of-truth read from Credential Issuance behind a short-TTL Redis cache, so a mutable fact becomes visible to verifiers within a bounded window without adding a network round trip to every verification. This extends that exact mechanism, rather than inventing a second one.
The successor summary rides the existing status lookup — it adds no second Credential Issuance
round trip, and doesn’t change isValid/status’s own outcome.
Design guardrails
| Guardrail | Meaning |
|---|---|
| Reuse the existing live-status call and cache, never a second round trip | One extra field on an existing response — verification must stay fast and stateless-by-default. |
| Supersession is advisory, never a validity failure | A superseded credential still returns isValid: true if its signature and revocation status say so. A verifier UI must not conflate “outdated” with “fraudulent.” |
| Disclose existence and tier, not internal detail | A verifier sees that a successor exists, its tier, its issuer name, and (when shareable) a link to verify it directly — never the original custodian’s review notes or reviewer identity. |
| Direction matters: forward disclosure is required, reverse is optional | Verifying a superseded (old, Tier-2) credential must surface the successor — the safety-relevant direction. Verifying the authoritative credential showing its prior custodian attestations is a transparency nice-to-have, not required. |
| Cache freshness matches the actual event rate, not revocation’s | Linking happens far less often than revocation; its own tunable TTL, not hardcoded equal to the revocation cache’s. |
Carry supersession through the live-status call
The status response gains the resolved final successor’s credential id (empty = none), issuer name, provenance tier, and shareable id — additive and wire-compatible. Cycles, dangling pointers, and long chains resolve to no verifier disclosure rather than an error.
Surface it through the verify response and verifier UI
The REST verify response gains an optional supersededBy object (credential id, issuer name, tier,
a verify URL when the successor is independently shareable) — null when not superseded. The
verifier-portal credential detail view shows a distinct banner, visually and textually separate
from the existing revoked/expired states: “A more authoritative record for this credential now
exists, issued directly by ‹org›” with a direct link when available. The exported PDF verification
report carries the same disclosure, so a verifier who downloads a report doesn’t lose the signal
the moment they leave the live page.
Reverse disclosure (lower priority, optional)
Verifying a Tier-1 credential could additionally show “this record consolidates N prior custodian attestation(s)” — a trust/transparency signal, not a safety one. Deferred unless product pull materializes.