Skip to main content

ADR-009: Authority Domain Allowlist

Status: Accepted Date: 2026-04-13 Relates to: ADR-005 (Trust Authority Model), ADR-007 (Security and Anti-Gaming)

Context​

The discovery specification requires agents to validate that the verify endpoint domain belongs to a legitimate trust authority. Without a defined mechanism, "known trust authority" is ambiguous — any domain can claim to be one, and agents have no way to distinguish legitimate authorities from imposters. This is the primary defense against authority impersonation (threat T2 in the threat model).

The allowlist is the protocol's trust root. It needs a defined entry shape so different distribution mechanisms produce compatible data, and a protocol-native response to key compromise that does not require agent software updates.

Decision​

Adopt a preconfigured-allowlist trust model with a defined entry shape and key-level revocation through JWKS refresh.

Trust model​

Agents ship with a list of trusted authorities. Distribution, updates, and authority-wide revocation happen through the agent vendor's normal software-distribution channel and are out of scope for the protocol. The current spec expects small static allowlists (typically one authority during ecosystem bootstrap).

Allowlist entry shape​

Each allowlist entry MUST contain:

FieldTypeDescription
domainstringFully-qualified domain of the authority. The link-tag href domain MUST match this value exactly.
jwksUrlstring (URL)HTTPS URL where the authority's JWKS is served. The URL is pinned in the allowlist — agents MUST NOT infer the JWKS URL from the domain.

Rejection rules agents MUST enforce:

  • Link-tag href domains not matching any allowlist entry's domain are rejected before any request is sent.
  • JWKS fetched from any URL other than the pinned jwksUrl for the corresponding authority is rejected.
  • jwksUrl MUST be HTTPS. The URL MAY be on a different host than domain (e.g., a CDN).

Key-level revocation​

Agents MUST refresh the JWKS for each allowlisted authority at least every 1 hour. A key absent from the current JWKS MUST be treated as revoked — responses signed with a kid not present in the current JWKS MUST be rejected regardless of the response's expires timestamp.

This gives authorities a fast, protocol-native response to key compromise: remove the key from JWKS, and propagation to all agents is bounded by the refresh interval. It also resolves a separate undefined behavior: what an agent does when a response's kid is not in its cached JWKS. Refresh, then reject if still absent.

Distribution mechanism​

The way an allowlist is delivered (hardcoded list, configuration file, signed remote registry) is the agent operator's choice. Different deployment environments — browser extensions, server-side agents, embedded systems — favor different mechanisms. The protocol does not constrain the mechanism, only the entry shape: every distribution path MUST produce entries with {domain, jwksUrl} so all conformant agents enforce the same security properties.

A configuration override MAY disable the allowlist check for testing and development. Such overrides MUST NOT be enabled in production.

Options Considered​

A. Bare domain allowlist (rejected). Allowlist entries are domain strings only. Agents derive the JWKS URL from the domain (e.g., https://{domain}/.well-known/jwks.json). Offers no defense beyond CA + DNS — an attacker who hijacks DNS for the authority domain can substitute the JWKS. Provides no way to host keys on a separate operational boundary.

B. Domain + jwksUrl (chosen). Pins the JWKS location explicitly without coupling to specific key material. Authorities can rotate keys via standard JWKS without out-of-band allowlist updates. JWKS can live on a CDN or separate infrastructure, raising the cost of compromise. The minimum viable entry shape that makes interoperability and protocol-native key-level revocation possible.

C. Domain + jwksUrl + key fingerprints. Strongest static defense — the allowlist pins the keys themselves, not just their location. Operationally brittle: every key rotation requires an out-of-band allowlist update propagated to every agent. Not adopted; a transparency log on the roadmap gives a more graceful path to the same property without coupling key rotation to allowlist distribution.

Known limitations​

The chosen design has these limitations, named explicitly:

  1. No authority-wide revocation channel. If an entire authority is compromised, removal depends on agent software updates. A protocol-level revocation mechanism is tracked on the roadmap.
  2. Allowlist binds authority identity, not provider→authority pairing. Any allowlisted authority can claim to vouch for any provider via a link tag. A future provider-hosted manifest would bind provider→authority through the well-known location — see the roadmap.
  3. Single-authority bootstrap. The current spec expects small static allowlists. Multi-authority federation is on the roadmap.

Consequences​

  • Agents must ship or configure an allowlist with {domain, jwksUrl} entries before they can validate link tags.
  • The working group (or authority operator) must publish the list of authorized domains together with their pinned JWKS URLs.
  • Adding a new authority requires agents to update their allowlist — intentional friction that prevents unauthorized authorities.
  • Authorities respond to key compromise by removing the key from JWKS; propagation to agents is bounded by the 1-hour refresh interval.
  • The allowlist entry can be extended with optional fields (publicKeyFingerprints, federationTrustLevel, displayName) without breaking existing agents.
  • Testing environments need a way to bypass the check without weakening production security.

References​