@spec dpop_bound?(module(), String.t()) :: boolean()

Returns true iff a stored code for code is bound to a DPoP key (RFC 9449 §10) - i.e. its redemption requires a matching DPoP proof (holder-of-key).

Reads the code via the store's OPTIONAL Attesto.CodeStore.get/1 WITHOUT consuming it, so a legitimate redemption is unaffected. Returns false when the store has no get/1, the code is unknown, or it carries no :dpop_jkt. This lets the token endpoint surface a holder-of-key (invalid_dpop_proof) rejection ahead of the client-authentication error (FAPI2) without burning the single-use code.

@spec finalize(module(), String.t(), Attesto.AuthorizationCode.Grant.t()) :: :ok

Finalize a fully completed redemption: record the reuse marker (consumed_success) for code's grant.

Call this only AFTER the full token response has been successfully built. It is split from redeem/4 so redemption is atomic - redeem/4 claims the code (single use, via take/1) and validates it, but defers this marker so a failure in the caller's downstream issuance (mint, refresh-token persistence, a host callback fault) does NOT leave a spent-but-tokenless code recorded as a completed redemption (which would make a legitimate retry look like a reuse attack and revoke the family). A no-op for stores that do not implement Attesto.CodeStore.mark_consumed/2. This form is only for flows that issue no refresh token and always records a nil family_id in the marker. The Grant's family_id is authorization provenance, not a refresh-family identifier. For a refresh grant, use issue_refresh_and_finalize/6 so the marker carries the family ID returned by RefreshToken.issue/3 without accepting a caller-supplied ID.

@spec issue(module(), issue_attrs(), keyword()) ::
  {:ok, String.t()} | {:error, issue_error()}

Mint a single-use authorization code and persist it via store.

attrs MUST carry :client_id, :redirect_uri, and :subject. Optional :code_challenge binds the code to PKCE; when present, :code_challenge_method must be "S256" if given. Optional :scope (a list of strings, default []), :dpop_jkt (binds the code to a DPoP key), :family_id (a non-empty provenance string round-tripped to the redeemed Grant; use issue_refresh_and_finalize/6 to bind the actually issued refresh family), and :claims (a lossless, string-keyed I-JSON object of host context; persisted numbers are exact-range integers, not floats) round-tripped to redeem/4.

Options: :ttl (seconds the code is valid, default

60. and :now (clock override).

Returns {:ok, code} with the plaintext code to hand the client. Only the code's hash is stored. Returns {:error, reason} on malformed attrs.

@spec issue_refresh_and_finalize(
  module(),
  String.t(),
  Attesto.AuthorizationCode.Grant.t(),
  module(),
  Attesto.RefreshToken.context(),
  keyword()
) ::
  {:ok, Attesto.RefreshToken.issued()}
  | {:error, Attesto.RefreshToken.issue_error()}

Issue an initial refresh token for a redeemed code and finalize its reuse marker with the family ID returned by the refresh-token issuer.

This composition API is the safe bridge for authorization-code flows that issue refresh tokens. First finish every access-token, ID-token, and other response operation that can fail; then call this function, and add the returned plaintext refresh token to the response only after it returns {:ok, issued}. It calls Attesto.RefreshToken.issue/3 itself, so callers never provide a family ID or generation. Only a validated success result can reach mark_consumed/2, and the exact family ID captured from that result is written to the code-reuse marker. A refresh issuance error is returned unchanged and leaves the code spent-but-unfinalized. A finalization exception or contract violation is propagated and never becomes an :ok result.

refresh_context must carry the redeemed grant's :subject and :client_id, and its :scope and :resource lists must be subsets of the grant's authorization. If the redeemed grant is DPoP-bound, the context's :dpop_jkt may be nil for a confidential-client refresh or must exactly match that binding for a public-client refresh; a different key is rejected. The host is responsible for that public/confidential classification and for choosing the context binding required by RFC 9449 §5. A token-endpoint DPoP binding may differ from the authorization-request binding only when the redeemed grant itself is unbound, which permits token-endpoint DPoP initiation without weakening a holder-of-key grant. The context must not contain top-level :family_id or :generation continuation fields. Those are internal rotation state, not caller input; put authorization provenance inside :claims when needed.

@spec redeem(module(), String.t(), redeem_params(), keyword()) ::
  {:ok, Attesto.AuthorizationCode.Grant.t()} | {:error, redeem_error()}

Validate and consume a code at the token endpoint.

params MUST carry the :redirect_uri (matched exactly against the one in the authorization request), the :code_verifier (checked against the stored PKCE challenge), and the :client_id of the redeeming client. By default client binding is fail-closed: since every stored code carries a client_id, redemption MUST present one (:client_required if absent, :client_mismatch if wrong) - this stops a code issued to one client being redeemed by another (RFC 6749 §4.1.3). A caller that cannot authenticate the client and relies on PKCE alone passes allow_missing_client_id?: true in opts. :dpop_jkt is required iff the code was DPoP-bound at issue/3; if the code was not bound, a presented :dpop_jkt is allowed and can be used by the caller to mint a DPoP-bound access token.

The code is consumed (single use) before validation. Returns {:ok, %Attesto.AuthorizationCode.Grant{}} with the validated grant context, or {:error, reason}.

When the store implements optional reuse tracking (see Attesto.CodeStore), a second redemption of a code that was already successfully redeemed returns {:error, {:reuse, meta}} rather than {:error, :invalid_grant}. meta carries the first redemption's :family_id and :subject. For a redemption that issued a refresh token, :family_id identifies the descendant family to revoke (OAuth 2.0 Security BCP §4.13); for a no-refresh redemption it is nil. Codes the store has never seen remain {:error, :invalid_grant}.