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 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 of that first redemption). 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).

Record shape

A stored record is a map with:

• :code_hash - the Attesto.Secret.hash/1 of the code (the key).
• :data - the opaque grant context the host round-trips (client, redirect URI, scope, PKCE challenge, optional DPoP thumbprint, subject, and any host claims).
• :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.