Storage seam for authorization codes.

Attesto.AuthorizationCode is pure: it generates a code, hashes it, and validates a redemption, but it never decides where the code lives. That is this behaviour. A host implements it over whatever store fits (Postgres, Redis, ETS); Attesto.CodeStore.ETS is a ready single-node implementation.

The single-use contract (load-bearing)

take/1 MUST be atomic: it returns the record for code_hash and removes it in one indivisible step, so two concurrent redemptions of the same code cannot both succeed. Authorization codes are single-use (RFC 6749 §4.1.2); a store that let take/1 race would let a captured code be replayed. A SQL implementation uses DELETE ... WHERE code_hash = $1 RETURNING ...; an ETS implementation uses :ets.take/2.

The code is consumed by take/1 even if Attesto.AuthorizationCode then rejects the redemption (wrong redirect URI, failed PKCE): a code that has been presented once is spent, which denies an attacker repeated validation attempts against a stolen code.

Optional reuse tracking (additive, fail-safe)

The single-use contract above stops a code being redeemed twice, but on its own it cannot tell a replay of an already-redeemed code apart from a never-issued code: once take/1 has removed the row, a second presentation looks identical to garbage. The OAuth 2.0 Security BCP §4.13 (and RFC 6749 §4.1.2) say more: when a code is presented a second time the AS SHOULD revoke the tokens already issued from the first redemption, because a second presentation is an attack signal (the code leaked). Acting on that signal requires remembering which family, if any, the first redemption spawned.

A store MAY opt into this by implementing the OPTIONAL mark_consumed/2 callback and extending take/1 to return {:error, :consumed, meta} for a code that was already redeemed. This is purely additive:

• A store that does NOT implement reuse tracking keeps take/1's original {:ok, entry} | :error contract. Attesto.AuthorizationCode treats a re-presented (now absent) code as :invalid_grant, exactly as before. Single use is unaffected.
• A store that DOES implement reuse tracking calls mark_consumed/2 when a redemption succeeds, recording the code_hash together with meta (the family_id/subject for that redemption, plus its optional replay_retain_until deadline). The family is nil for finalize/3 no-refresh flows and is the exact issued family only for issue_refresh_and_finalize/6. A later take/1 of the same hash then returns {:error, :consumed, meta}, and Attesto.AuthorizationCode.redeem/4 surfaces {:error, {:reuse, meta}} so the caller can revoke the family.

Fail-safe means: the absence of reuse tracking never makes the system less safe than single use already guarantees; it only forgoes the extra descendant-revocation signal. A store therefore implements the callback only when it can persist the consumed marker durably enough to be useful (a single-redemption window is already closed by take/1 whether or not the marker survives).

Optional access-token replay containment

Integrations can extend reuse tracking to the access token minted from a code by capability-detecting these functions on the store module:

• record_access_token_for_code(code_hash, jti, expires_at) links the minted token to the code until the token expires.
• revoke_access_token_for_code(code_hash) revokes the linked token and is idempotent for unknown or legacy codes.
• revoke_family_access_tokens(family_id) revokes tokens whose code was finalized with that refresh family in mark_consumed/2.
• access_token_revoked?(jti) reports whether an unexpired linked token has been revoked.

These remain capability-detected extension functions rather than behaviour callbacks. That lets stores compiled against an earlier Attesto 2.x release keep their existing @impl annotations without new compiler warnings while allowing bundled and custom stores to adopt the extension independently.

Record shape

A stored record is a map with:

• :code_hash - the Attesto.Secret.hash/1 of the code (the key).
• :data - the canonical grant context the host round-trips. It contains all and only :client_id, :redirect_uri, :code_challenge, :subject, :scope, :resource, :dpop_jkt, :family_id, and :claims. Adapter metadata must not be added beside those keys; host-specific values belong inside the portable, string-keyed :claims object (valid UTF-8 without U+0000 and exact-range integers). The PKCE method is fixed to S256 whenever a challenge is present and is therefore not a stored context key.
• :expires_at - absolute expiry, unix seconds. The store MAY evict expired records, but Attesto.AuthorizationCode re-checks expiry after take/1, so eviction timing is not security-critical.