Behaviour for caching a validated Client ID Metadata Document - CIMD (draft-ietf-oauth-client-id-metadata-document-01, IETF OAuth WG).

CIMD lets a client identify itself with no prior registration by using an HTTPS URL as its client_id; the authorization server dereferences that URL (AttestoPhoenix.ClientIdMetadata.Fetcher) and validates the returned document (Attesto.ClientIdMetadata.validate_document/2). This behaviour is the seam through which the resolver remembers a successfully validated document so that not every authorization request reaches out to the network.

What may be cached

Only a document that has passed validation is stored, and only with an expires_at the resolver derives from the response's HTTP freshness directives (Cache-Control: max-age / Expires, RFC 9111), clamped to the host's configured bounds. The draft (§6) and RFC 9111 forbid caching error responses or invalid/malformed documents, so an implementation of this behaviour is only ever handed metadata the caller already accepted; it does no validation of its own.

Cache key and value

The key is the CIMD client_id URL (the same string the client presented and the document's client_id equals). The value is the validated, string-keyed metadata map together with its expires_at. get/1 MUST treat an expired entry as a miss - freshness is re-checked on read, never honored past expires_at - so an implementation that cannot cheaply evict still cannot serve a stale document.

Default and the opt-out

The default implementation is AttestoPhoenix.ClientIdMetadata.Cache.Ecto, which persists the entry to Postgres (table attesto_client_id_metadata, swept by AttestoPhoenix.Store.Sweeper) so the cache is coherent across a cluster and the outbound fetch fan-out is bounded under load. A single-node deployment may opt into the per-node AttestoPhoenix.ClientIdMetadata.Cache.ETS instead - a per-node cache is correct here because a miss simply re-fetches - by configuring the :cache module under AttestoPhoenix.Config's :client_id_metadata key.