@callback access_token_revoked?(jti :: raw(), opts()) :: boolean() | {:error, reason()}

Whether an access token has been revoked. Optional.

Fails closed for the caller: a verifier that cannot reach the store treats the token as revoked rather than as valid.

@callback bind_authorization_code_family(code :: raw(), family_id :: String.t(), opts()) ::
  :ok | {:error, :not_found} | {:error, reason()}

Attach a refresh family to an already-stored code.

Used when the family is allocated after the code row is written (an upstream flow that resolves the subject late). Idempotent.

@callback delete_client(client_id :: String.t(), opts()) :: :ok | {:error, reason()}

Delete a client. Optional.

@callback get_client(client_id :: String.t(), opts()) ::
  {:ok, Noizu.MCP.Auth.Server.Client.t()}
  | {:error, :not_found}
  | {:error, reason()}

Fetch a client by its client_id.

For a CIMD client the client_id is an https URL; the adapter does not care. Returning {:error, :not_found} for an unresolvable client is what keeps the authorization endpoint from redirecting anywhere.

@callback get_consent(subject :: String.t(), client_id :: String.t(), opts()) ::
  {:ok, Noizu.MCP.Auth.Server.Store.Consent.t()}
  | {:error, :not_found}
  | {:error, reason()}

Fetch a subject's recorded consent for a client.

@callback get_login_state(state :: raw(), opts()) ::
  {:ok, map()} | {:error, :not_found} | {:error, reason()}

Read login state without consuming it (the consent screen re-renders).

@callback get_refresh_token(token :: raw(), opts()) ::
  {:ok, Noizu.MCP.Auth.Server.Store.RefreshToken.t()}
  | {:error, :not_found}
  | {:error, reason()}

Look a refresh token up by its raw value, without consuming it.

@callback purge_expired(now :: DateTime.t(), opts()) ::
  {:ok, %{optional(atom()) => non_neg_integer()}} | {:error, reason()}

Delete everything that expired before now. Optional.

The host owns the schedule (a 15-minute Oban job); the library never starts a sweeper of its own. Returns per-table counts for logging.

@callback put_access_token(Noizu.MCP.Auth.Server.Store.AccessToken.t(), opts()) ::
  :ok | {:error, reason()}

Record an issued access token. Optional. jti is raw; store its hash.

@callback put_authorization_code(
  Noizu.MCP.Auth.Server.Store.AuthorizationCode.t(),
  opts()
) ::
  :ok | {:error, reason()}

Persist a pending authorization code. code is raw; store its hash.

@callback put_client(Noizu.MCP.Auth.Server.Client.t(), opts()) ::
  {:ok, Noizu.MCP.Auth.Server.Client.t()} | {:error, reason()}

Insert or replace a client. secret_hash arrives already hashed.

@callback put_consent(Noizu.MCP.Auth.Server.Store.Consent.t(), opts()) ::
  :ok | {:error, reason()}

Record consent, replacing any prior row for the same {subject, client_id}.

@callback put_login_state(state :: raw(), payload :: map(), ttl :: pos_integer(), opts()) ::
  :ok | {:error, reason()}

Store the state carried across the upstream IdP round trip, keyed by a raw state value the adapter hashes. ttl is in seconds — login state is short-lived by construction, so an adapter may expire it eagerly.

The payload holds the pending authorization request (client_id, redirect_uri, scope, resource, PKCE challenge, the client's own state) plus CSRF material.

@callback put_refresh_token(Noizu.MCP.Auth.Server.Store.RefreshToken.t(), opts()) ::
  :ok | {:error, reason()}

Persist a refresh token. token is raw; store its hash.

@callback revoke_access_token(jti :: raw(), opts()) :: :ok | {:error, reason()}

Revoke a single access token by jti. Optional.

@callback revoke_consent(subject :: String.t(), client_id :: String.t(), opts()) ::
  :ok | {:error, reason()}

Withdraw consent. Withdrawing consent that was never given is :ok.

@callback revoke_refresh_family(family_id :: String.t(), opts()) ::
  :ok | {:error, reason()}

Revoke every refresh token in a family. Called on replay detection and on logout.

@callback revoke_refresh_token(token :: raw(), opts()) :: :ok | {:error, reason()}

Revoke a single refresh token (RFC 7009). Revoking an unknown token is :ok.

@callback revoke_subject_tokens(
  subject :: String.t(),
  client_id :: String.t() | nil,
  opts()
) ::
  :ok | {:error, reason()}

Revoke every refresh token a subject holds, optionally narrowed to one client. Optional; client_id may be nil for "all clients".

@callback rotate_refresh_token(
  old_token :: raw(),
  new_token :: Noizu.MCP.Auth.Server.Store.RefreshToken.t(),
  opts()
) ::
  {:ok, Noizu.MCP.Auth.Server.Store.RefreshToken.t()}
  | {:error, :not_found}
  | {:error, {:replayed, Noizu.MCP.Auth.Server.Store.RefreshToken.t()}}
  | {:error, reason()}

Rotate old_token into new_token atomically, returning the old record.

• {:ok, old} — rotated now, by this call
• {:error, :not_found} — unknown, expired, or revoked
• {:error, {:replayed, old}} — already rotated. This is the reuse-detection signal: the caller revokes old.family_id in full and answers invalid_grant, on the assumption that either the client or an attacker holds a copy, and there is no way to tell which.

new_token.token is raw; store its hash. The new row must carry the old row's family_id and family_expires_at.

@callback take_authorization_code(code :: raw(), opts()) ::
  {:ok, Noizu.MCP.Auth.Server.Store.AuthorizationCode.t()}
  | {:error, :not_found}
  | {:error, {:replayed, Noizu.MCP.Auth.Server.Store.AuthorizationCode.t()}}
  | {:error, reason()}

Redeem a code atomically and exactly once.

• {:ok, code} — redeemed now, by this call, for the first time
• {:error, :not_found} — no such code, or it expired
• {:error, {:replayed, code}} — it existed and had already been redeemed. The caller revokes code.refresh_family_id and answers invalid_grant.

Collapsing the third case into the second disables replay detection, so it is part of the contract, not a nicety.

@callback take_login_state(state :: raw(), opts()) ::
  {:ok, map()} | {:error, :not_found} | {:error, reason()}

Consume login state: read and delete atomically, so one callback cannot be replayed into two authorization codes.

@callback update_login_state(state :: raw(), changes :: map(), opts()) ::
  {:ok, map()} | {:error, :not_found} | {:error, reason()}

Merge changes into stored login state — how a consent decision or a resolved upstream subject is recorded without a second round trip.