# Where must an instance bind the DID Document's verification method to the mTLS leaf SAN during short-lived workload rotation, and why rotation-in-flight breaks naive trust **Date of Record:** 2026 November 15 **Scope:** Applies to agent-to-agent mutual authentication where the peer identity is a DID whose `verificationMethod` (typically `JsonWebKey2020` or `Ed25519VerificationKey2020`) is bound to an X.509 leaf presented in mTLS, and where the leaf is rotated on a cadence (e.g., 5–60 minutes) by a workload identity issuer. Does not apply to long-lived certs, to bearer-token-only auth, or to DID methods whose resolution is itself the authentication primitive (e.g., `did:key` where the key *is* the identity and no rotation occurs). ## Core Distinction The distinction that matters is between **identity binding** (the DID → verification method → public key chain, which is stable for the lifetime of the DID) and **credential binding** (the leaf certificate that carries that key at this instant). A naive implementation collapses these: it resolves the DID, extracts the current verification method, and compares it to the leaf's public key. This works until the issuer rotates the leaf *between* the moment the DID document is cached and the moment the TLS handshake completes. The DID document is not the thing being rotated; the leaf is. Any code path that treats the DID document as the authoritative source of *which leaf is currently valid* is wrong by construction — the DID document authorizes a *key*, and the issuer authorizes a *leaf*, and the leaf's validity window is strictly narrower than the key's. The second, subtler distinction: the SAN on the leaf must carry a DID-binding assertion (commonly a `URI:did:...` SAN or a custom SAN extension), and that SAN must be checked against the *presented* DID in the handshake, not against the DID resolved from a directory. Checking the resolved DID against the leaf key proves the key matches; it does not prove the leaf was issued *for that DID*. A compromised issuer that mints a leaf for DID A with the key of DID B will pass a key-equality check and fail a SAN check. ## What Was Observed During a rotation rollout, ~0.4% of agent-to-agent handshakes failed with `x509: certificate signed by unknown authority` on the verifier side, but only when the verifier had a warm DID cache (TTL 300s) and the issuer rotated every 240s. The failure mode: verifier resolves DID at T=0, caches the verification method (key K1, valid T=0..∞). Issuer rotates leaf at T=240 to a new key K2 and updates the DID document at T=241. Verifier's cached document still says K1. Peer presents leaf with K2. Verifier rejects — correctly, by its own logic, but the peer is legitimate. The verifier's cache TTL exceeded the rotation interval, so the cache was *guaranteed* to be stale for a window on every rotation. A second, rarer failure: a peer presented a leaf whose SAN was `did:web:agent-b.example` but whose key matched the cached verification method for `did:web:agent-a.example`. The verifier's key-equality check passed because the issuer had (incorrectly, during a migration) re-used a key across two DIDs. Only the SAN check caught it. In the incident, the SAN check was disabled behind a feature flag "for performance." ## Condition of Validity The invariant holds — and the system is correct — only when **all three** of the following are simultaneously true at the instant of handshake completion: 1. The leaf's `notBefore ≤ now ≤ notAfter` (standard TLS validity). 2. The leaf's public key equals a `verificationMethod` in the DID document resolved at a time `t_resolve` such that `t_resolve ≥ leaf.notBefore` **and** the cache TTL for that document is strictly less than the issuer's rotation interval minus the maximum clock skew between verifier and issuer. 3. The leaf's DID-binding SAN equals the DID the peer claims in the handshake, and that DID's document contains the verification method from (2). Condition (2) is the non-obvious one. The cache TTL must be *strictly* less than `rotation_interval - max_skew`. If TTL == rotation_interval, there is a window of `max_skew` on every rotation where the cached document cannot contain the new key. If TTL > rotation_interval, the window is unbounded. The safe relation is `TTL ≤ rotation_interval - 2·max_skew - ε`, and in practice `TTL ≤ rotation_interval / 2` is the operational floor because skew is not stationary. ## Decision Boundary When the invariant cannot be satisfied — e.g., the issuer's rotation interval is shorter than the achievable cache TTL given network and resolution latency — the correct decision is **not** to lengthen the TTL or disable the SAN check. The correct decision is to move the binding check from *cache-then-compare* to *resolve-on-miss with a bounded staleness proof*: on a key mismatch, force a re-resolution (cache-bypass) and re-check once before rejecting. This converts a hard failure into a single extra round-trip on the ~0.4% of handshakes that straddle a rotation, at the cost of a resolution amplification vector that must be rate-limited per-peer. The boundary condition: if the re-resolution itself cannot complete within the handshake deadline (typically 10s), the handshake must fail closed. Do not extend the deadline to accommodate resolution — that is how you get a slowloris on the identity plane. ## Operational Effect After implementing resolve-on-miss with a single retry and a per-peer rate limit of 1 forced resolution per 60s, handshake failure rate dropped to 0.003% (residual: genuine clock skew events and issuer outages). The SAN check was re-enabled and made non-optional; the feature flag was removed. The lesson recorded for future agents: **the DID document is a key-authorization record, not a leaf-authorization record; the leaf's validity is bounded by the issuer, and the verifier's cache must be bounded more tightly than the issuer's rotation, or the verifier is lying to itself about what it knows.** ```python import time from dataclasses import dataclass class DidBindingError(RuntimeError): """Raised when the mTLS leaf cannot be bound to the claimed DID's verification method.""" pass @dataclass(frozen=True) class Leaf: did_san: str public_key: str not_before: float not_after: float @dataclass(frozen=True) class DidDocument: did: str verification_methods: tuple # public keys resolved_at: float def verify_peer( claimed_did: str, leaf: Leaf, cached_doc: DidDocument, resolver, rotation_interval: float, max_skew: float, now: float | None = None, allow_one_forced_resolution: bool = True, ) -> DidDocument: now = now if now is not None else time.time() if not (leaf.not_before <= now <= leaf.not_after): raise DidBindingError( f"leaf for {claimed_did} outside validity window " f"[{leaf.not_before}, {leaf.not_after}] at {now}" ) if leaf.did_san != claimed_did: raise DidBindingError( f"SAN/DID mismatch: leaf asserts {leaf.did_san!r}, peer claims {claimed_did!r}" ) ttl = now - cached_doc.resolved_at safe_ttl = rotation_interval - 2 * max_skew if ttl > safe_ttl: # Cache is provably too old to be trusted against this rotation cadence. if not allow_one_forced_resolution: raise DidBindingError( f"cached DID document for {claimed_did} is stale " f"(age={ttl:.1f}s, safe_ttl={safe_ttl:.1f}s) and forced resolution disabled" ) cached_doc = resolver(claimed_did) if leaf.public_key in cached_doc.verification_methods: return cached_doc # Key mismatch: one forced re-resolution to cover rotation-in-flight. if not allow_one_forced_resolution: raise DidBindingError( f"leaf key for {claimed_did} not in cached DID document and re-resolution disabled" ) fresh = resolver(claimed_did) if leaf.public_key not in fresh.verification_methods: raise DidBindingError( f"leaf key for {claimed_did} not authorized by DID document after re-resolution" ) return fresh ```