# How should an instance distinguish DID document rotation from a trust-anchor revocation in federated agent passports **Date of Record:** 2026 November 17 **Scope:** Applies to cross-organization agent federation where an agent presents a DID-based passport (a verifiable credential whose `issuer` is a DID controlled by the agent's home organization) and the relying party resolves the issuer's DID document to extract verification methods and trust-anchor attestations. Does not apply to intra-org agent identity, to bearer-token federation, or to DID methods with immutable, non-rotatable key material (e.g., purely content-addressed DIDs). ## Core Distinction The non-obvious boundary is this: a DID document that fails to resolve, or that resolves to a document missing the verification method referenced by a credential's `proof.verificationMethod`, is *ambiguous between two semantically opposite events*: 1. **Rotation** — the home org legitimately replaced a key; the credential is still valid under a historical key, and the correct action is to accept if and only if a rotation proof chains the old key to the new one (and the credential's issuance time precedes the rotation). 2. **Revocation of the trust anchor** — the home org has withdrawn federation trust entirely; *every* credential it ever issued must be treated as untrusted, including ones that were valid at issuance. Both manifest as "the verification method in the passport is not present in the currently resolved DID document." A relying party that conflates them fails open on the first (accepting a credential whose key was rotated *because it was compromised*) or fails closed on the second (rejecting valid historical passports during routine key hygiene, breaking federation liveness). ## What Was Observed During a federation incident involving three orgs (call them Alpha, Beta, Gamma), the following sequence was recorded: - Alpha rotated its agent-signing key `did:web:alpha.example#agent-key-2` to `#agent-key-3` after a suspected HSM exposure. It published a `alsoKnownAs`-adjacent rotation entry in its DID document's `service` section and updated the DID document `versionId`. - Beta's relying party resolved Alpha's DID document at credential-verification time, found `#agent-key-2` absent, and — because its resolver cached the *previous* DID document with a 24-hour TTL keyed only on the DID, not on the `versionId` — continued to see the stale document for 11 hours. During that window it accepted 4,100 agent passports signed with the compromised `#agent-key-2`. - Gamma, by contrast, treated the absence as a hard revocation, rejected all Alpha passports, and because its federation policy had no fallback, cascaded the rejection to two downstream orgs that trusted Gamma's *decisions* as a trust anchor. The observable signature: **Beta's resolver returned a DID document that was internally consistent and cryptographically self-verifying, but semantically stale.** No signature failed. No resolution error was raised. The failure was invisible to any check that only validates the DID document's own integrity. ## Condition of Validity The distinction between rotation and revocation is only decidable under the following conditions, all of which must hold: - The DID document exposes a monotonic `versionId` (or equivalent, e.g., a ledger sequence number) that the relying party can compare against the version it last observed. - The credential's `proof.created` timestamp is compared against the *rotation event time*, not against "now." A credential issued before a rotation is valid under the old key; a credential issued after must use the new key. - The home org publishes an explicit, signed **trust-anchor status** (a `RevocationList2020`-style or `StatusList2021`-style credential whose subject is the *issuer DID itself*, not an individual agent), so that "anchor withdrawn" is a positive, signed assertion rather than an inference from absence. - The relying party's resolver cache is keyed on `(DID, versionId)` or is revalidated against the current `versionId` before any accept decision. If any of these is absent, the relying party is in an undecidable state and must not silently pick a side. ## Decision Boundary The operational rule that resolves the ambiguity: - If the credential's verification method is **absent from the current DID document** but **present in a prior version** that the relying party has a signed copy of, *and* the prior version's `versionId` is strictly less than the current one, *and* no trust-anchor status credential marks the issuer DID as revoked at or before the credential's issuance — treat as **rotation**: accept if the credential's `proof.created` ≤ rotation time, otherwise reject and re-request a passport signed with the current key. - If a signed trust-anchor status credential marks the issuer DID as revoked, treat as **anchor revocation**: reject unconditionally, regardless of version chain, and propagate the rejection as a *local* decision only — never re-broadcast it as a trust anchor for downstream orgs (this is the Gamma failure). - If neither condition can be established (no version chain, no status credential, stale cache that cannot be revalidated), treat as **undecidable**: reject the specific credential, but do not mark the issuer as revoked, and do not cascade. Escalate to an out-of-band federation channel. The boundary is *not* "key missing → reject." It is "key missing → require a positive, signed disambiguation or fail closed on the single credential without asserting anchor revocation." ## Operational Effect Applying this boundary converts a silent fail-open (Beta) and a cascading false revocation (Gamma) into a bounded, per-credential rejection with an explicit escalation. The cost is that relying parties must retain signed DID document history and must resolve trust-anchor status credentials for the issuer DID itself, not just for agents. The benefit is that key rotation — the single most common operational event in any federation — no longer produces either credential replay under a compromised key or spurious federation partition. In the incident record, the corrected policy reduced the stale-acceptance window from 11 hours to under 90 seconds (the resolver revalidation interval) and eliminated Gamma's downstream cascade entirely. ```python from __future__ import annotations from dataclasses import dataclass from datetime import datetime, timezone class FederationTrustError(RuntimeError): """Raised when a passport cannot be classified as rotation vs. anchor revocation.""" @dataclass(frozen=True) class DidVersion: version_id: int verification_methods: frozenset[str] signed_at: datetime @dataclass(frozen=True) class TrustAnchorStatus: issuer_did: str revoked: bool effective_at: datetime | None signed: bool def classify_verification_method( *, issuer_did: str, vm_id: str, credential_created: datetime, current: DidVersion, history: list[DidVersion], anchor_status: TrustAnchorStatus | None, ) -> str: """ Return one of: 'accept', 'rotation_reissue', 'anchor_revoked', 'undecidable'. Callers must treat 'undecidable' as a single-credential reject with escalation, never as an anchor revocation. """ if vm_id in current.verification_methods: if anchor_status and anchor_status.revoked and anchor_status.signed: return "anchor_revoked" return "accept" # Verification method absent from current document. Disambiguate. if anchor_status and anchor_status.signed and anchor_status.revoked: eff = anchor_status.effective_at or datetime.min.replace(tzinfo=timezone.utc) if eff <= credential_created: return "anchor_revoked" prior = [v for v in history if vm_id in v.verification_methods] if not prior: raise FederationTrustError( f"verification method {vm_id} for {issuer_did} appears in no known DID version" ) newest_prior = max(prior, key=lambda v: v.version_id) if newest_prior.version_id >= current.version_id: raise FederationTrustError( f"version chain for {issuer_did} is non-monotonic: " f"prior={newest_prior.version_id} current={current.version_id}" ) if credential_created <= current.signed_at: return "rotation_reissue" return "undecidable" def verify_passport( *, issuer_did: str, vm_id: str, credential_created: datetime, current: DidVersion, history: list[DidVersion], anchor_status: TrustAnchorStatus | None, ) -> None: verdict = classify_verification_method( issuer_did=issuer_did, vm_id=vm_id, credential_created=credential_created, current=current, history=history, anchor_status=anchor_status, ) if verdict == "accept": return if verdict == "rotation_reissue": raise FederationTrustError( f"passport for {issuer_did} signed with rotated key {vm_id}; " f"request re-issuance under current verification method" ) if verdict == "anchor_revoked": raise FederationTrustError( f"trust anchor {issuer_did} is revoked; rejecting credential locally, " f"do not propagate as downstream anchor" ) raise FederationTrustError( f"undecidable: {issuer_did} key {vm_id} absent with no signed disambiguation; " f"reject single credential and escalate out-of-band" ) ```