Required storage contract for authorization codes and their token linkage.
Attesto.AuthorizationCode reads, compares the immutable grant
bindings, then claims a live code atomically. Refused comparisons write
nothing. Expiry is checked only for live codes. Stores retain the grant in every state: :live (unclaimed),
:claimed (issuing tokens), and :redeemed (issuance finished).
read/1 returns these as named fields, never as an error or metadata flag.
All callbacks are required. validate!/1 refuses an incomplete store with
the missing callback's name. There are no capability-dependent tiers.
Stores implement transitions; core decides whether a presentation is a
replay and whether to revoke a refresh family. finish/2 reports concurrent
revocation in its atomic transition. A persistent store may conservatively deny
linked access tokens as soon as a flag is written, including through a shared
marker understood by previous-release nodes.
Immutable grant and retention
put/1 accepts :code_hash, :expires_at (unix seconds), and :data.
Data contains exactly :client_id, :redirect_uri, :code_challenge,
:subject, :scope, :resource, :dpop_jkt, :family_id, and :claims.
PKCE uses S256 when a challenge is present. Host context belongs in the
portable string-keyed claims object. These fields never change after insert;
the authorization's family provenance is separate from the redemption family.
A read adds :state, :redemption, and :revoked.
Redemption is nil until finish, then contains :family_id, :subject, and
:replay_retain_until. Claimed records remain for at least 300 seconds after
claim, then may be deleted once the code and linked access token expire.
A missing claim makes finish/2 return :error; core revokes newly issued
credentials and returns no tokens. Cleanup must never reopen a claimed code.
Redeemed records remain through code and linked token expiry. Housekeeping with an authoritative bundled refresh table may retire a family record once its last unexpired member disappears. Otherwise retain through the recorded family deadline, indefinitely when no deadline is known.
Every write is atomic against competing operations on the same code. SQL
batches lock code rows before refresh families; lock refresh families in
ascending family-id order and take each family's advisory lock before its
rows. See Attesto.RefreshStore. Store transitions never call a refresh store.
A host can run the shared contract tests by adding
use Attesto.Test.CodeStoreContract, store: Host.CodeStore to an
ExUnit.Case with async: false. The suite starts the store for each test;
pass :start as a zero-arity setup function for an already supervised or
database-backed store, ensuring isolated storage between tests.
See the custom-store upgrade guide for the previous callback mapping.
Summary
Callbacks
Read whether an unexpired linked token is revoked. Never writes.
Atomically change live to claimed. Any other state returns :error without writes.
Atomically delete matching live codes and flag matching claimed grants revoked.
Return the number deleted. Redeemed records are unchanged. Criteria are ANDed;
invalid or empty criteria raise ArgumentError. See Attesto.RevocationCriteria.
Atomically finish a claimed code, recording redemption and returning concurrent revocation.
Atomically flag a claimed code's replay. Other states return :error without writes.
Atomically insert a live code. Duplicate hashes raise; never replace a record.
Read any state without writing. Absent records return :error.
Atomically link one token to a claimed/redeemed code, preserving revocation. Invalid state raises.
Atomically revoke a code's token linkage, including later linkage; absent codes are a no-op.
Atomically revoke token linkages for redeemed codes belonging to a refresh family.
Functions
Validate that a module implements every required callback; raise naming a missing callback.
Validate a redemption record's required fields; malformed records raise without writes.
Types
@type code_hash() :: String.t()
@type redemption() :: %{ family_id: String.t() | nil, subject: String.t(), replay_retain_until: non_neg_integer() | nil }
@type snapshot() :: %{ code_hash: code_hash(), data: map(), expires_at: integer(), state: :live | :claimed | :redeemed, redemption: redemption() | nil, revoked: boolean() }
Callbacks
Read whether an unexpired linked token is revoked. Never writes.
@callback claim(code_hash()) :: :ok | :error
Atomically change live to claimed. Any other state returns :error without writes.
@callback delete_unclaimed(Attesto.RevocationCriteria.criteria()) :: {:ok, non_neg_integer()}
Atomically delete matching live codes and flag matching claimed grants revoked.
Return the number deleted. Redeemed records are unchanged. Criteria are ANDed;
invalid or empty criteria raise ArgumentError. See Attesto.RevocationCriteria.
@callback finish(code_hash(), redemption()) :: {:ok, boolean()} | :error
Atomically finish a claimed code, recording redemption and returning concurrent revocation.
@callback flag_replay(code_hash()) :: :ok | :error
Atomically flag a claimed code's replay. Other states return :error without writes.
@callback put(entry()) :: :ok
Atomically insert a live code. Duplicate hashes raise; never replace a record.
Read any state without writing. Absent records return :error.
Atomically link one token to a claimed/redeemed code, preserving revocation. Invalid state raises.
@callback revoke_access_token_for_code(code_hash()) :: :ok
Atomically revoke a code's token linkage, including later linkage; absent codes are a no-op.
@callback revoke_family_access_tokens(String.t()) :: :ok
Atomically revoke token linkages for redeemed codes belonging to a refresh family.
Functions
@spec validate!(module()) :: :ok
Validate that a module implements every required callback; raise naming a missing callback.
@spec validate_redemption!(redemption()) :: :ok
Validate a redemption record's required fields; malformed records raise without writes.