RFC 6749 §4.1 authorization-code grant, with mandatory PKCE (RFC 7636, S256) and optional DPoP binding of the code (RFC 9449 §10).

This module is pure logic over a Attesto.CodeStore: issue/3 mints a single-use code at the authorization endpoint, redeem/4 validates and consumes it at the token endpoint and returns the grant context the host uses to mint an access token. The store decides where codes live and guarantees single use; everything validated here (expiry, exact redirect-URI match, the PKCE transform, the DPoP key binding) is protocol.

PKCE (S256), required by default

issue/3 accepts a valid S256 code_challenge and redeem/4 checks the matching code_verifier; only S256 is accepted (see Attesto.PKCE). This closes authorization-code interception and is the modern default (OAuth 2.0 Security BCP / RFC 9700). PKCE enforcement at the authorization endpoint is governed by Attesto.AuthorizationRequest's :require_pkce option (default true); a host MAY relax it for a confidential client (public clients MUST use PKCE, RFC 9700 §2.1.1), in which case a code is issued with no challenge and redeemed with no verifier. A code_challenge that is present is always fully enforced. issue/3 therefore treats :code_challenge as optional: when given it must be a valid S256 challenge, when absent the code is unbound and a later redemption MUST present no code_verifier.

Single use even on failure

redeem/4 consumes the code via Attesto.CodeStore.take/1 before validating it, so a presented code is spent whether or not the redemption succeeds. An attacker who captures a code cannot make repeated validation attempts against it.

Code-reuse detection (when the store supports it)

Single use alone cannot distinguish a replay of an already-redeemed code from a never-issued code: once take/1 removes the row, both look absent. OAuth 2.0 Security BCP §4.13 (and RFC 6749 §4.1.2) say the AS SHOULD, on a second presentation of a code, revoke the tokens already issued from its first redemption, because a re-presented code is an attack signal.

redeem/4 enables that when - and only when - the Attesto.CodeStore implements the optional reuse-tracking pair (Attesto.CodeStore.take/1 returning {:error, :consumed, meta} plus Attesto.CodeStore.mark_consumed/2). The reuse marker is recorded by finalize/3, which the caller invokes AFTER the full token response has been successfully built - NOT by redeem/4 itself. So a code whose redemption validated but whose downstream issuance then failed (a mint or refresh-token fault, a host callback returning a bad principal) is left single-use-spent but NOT reuse-flagged: a replay is {:error, :invalid_grant}, and a legitimate retry of a transient failure is never mistaken for a reuse attack (which would wrongly revoke the family). Once finalize/3 has run, a later redemption of the same code yields {:error, {:reuse, meta}}, where meta carries that first redemption's context so the caller can revoke the descendant family (e.g. via Attesto.Revocation). A store that does not implement the pair behaves exactly as before: a re-presented code is {:error, :invalid_grant}. This is additive and fail-safe (see Attesto.CodeStore).

Pass a :family_id to issue/3 to link the code to the refresh-token family it will spawn; it rides onto the returned Grant so the host mints the family under that id, and it is what reuse detection replays.

DPoP-bound codes

If issue/3 is given a :dpop_jkt, the code is bound to that DPoP key (RFC 9449 §10): redemption MUST present the same :dpop_jkt (the thumbprint of the key in the token-request's DPoP proof) or it is rejected. A code minted without a binding MAY still be redeemed with a token-request DPoP proof; in that case this module treats the proof as a token-endpoint sender constraint for the access token the host is about to mint, not as a pre-existing authorization-code binding.