Atomically retrieves and deletes an authorization code.

Takes an authorization code string, removes it from storage, and returns its metadata map. If the code does not exist (or has already been consumed), returns nil. This prevents replay attacks where concurrent requests could both read the same code before either deletes it.

Deletes an authorization code.

Takes an authorization code string and removes it from storage. Authorization codes are single-use, so they should be deleted after being exchanged for tokens. Returns true if deleted successfully.

Retrieves authorization code metadata.

Takes an authorization code string and looks up its associated metadata. Returns a map with keys [:user-id :client-id :redirect-uri :scope :nonce :expiry] and optionally :code-challenge, :code-challenge-method, :resource, and :auth-time if found, or nil if the code doesn’t exist or has been deleted.

Retrieves the tokens issued for a previously consumed authorization code.

Takes an authorization code string and returns a map with :access-token and optionally :refresh-token if the code was previously exchanged, or nil if no record exists.

Records that an authorization code was exchanged for tokens.

Takes the authorization code, the issued access token string, and an optional refresh token string (may be nil). Stores a record associating the code with its issued tokens so that replay detection can revoke them per RFC 6749 §10.5. Returns true if recorded successfully.

Saves an authorization code with associated metadata.

Takes an authorization code string, user identifier, OAuth2 client identifier, the redirect URI from the authorization request, a vector of scope strings, an optional nonce for replay protection, an expiration timestamp (milliseconds since epoch), optional PKCE code-challenge and code-challenge-method strings, an optional resource vector of target resource indicator URIs (per RFC 8707), and an optional auth-time (epoch seconds) recording when the user authenticated. Stores the code and metadata. Returns true if saved successfully.

Returns a claims map for the given user-id and scope vector.

The returned map must include at minimum :sub. Additional claims such as :name, :email, etc. should be included based on the requested scopes.

Removes a client registration by client-id.

Returns true if the client existed and was removed, false if the client was not found.

Retrieves client configuration by client-id.

Takes an OAuth2 client identifier and looks up the client configuration. Returns the client configuration map matching the ClientConfig schema if found, or nil if the client doesn’t exist.

Registers a new client.

Takes a client configuration map matching the ClientConfig schema. Stores the client and generates a client-id if one isn’t provided. Returns the registered client configuration including the client-id.

Updates an existing client’s configuration.

Merges updated-config into the existing client config for client-id, preserving fields not present in updated-config. Returns the updated client config, or nil if the client does not exist.

Retrieves access token metadata.

Takes an access token string and looks up its associated metadata. Returns a map with keys [:user-id :client-id :scope :expiry] if found, or nil if the token doesn’t exist or has been revoked.

Retrieves refresh token metadata.

Takes a refresh token string and looks up its associated metadata. Returns a map with keys [:user-id :client-id :scope] if found, or nil if the token doesn’t exist or has been revoked.

Revokes a token.

Takes a token string (either access or refresh token) and revokes it, preventing it from being used in future requests. Returns true if revoked successfully.

Saves an access token.

Takes an access token string, user identifier, OAuth2 client identifier, a vector of scope strings, an expiration timestamp (milliseconds since epoch), and an optional resource vector of target resource indicator URIs (per RFC 8707). Stores the token and its metadata. Returns true if saved successfully.

Saves a refresh token.

Takes a refresh token string, user identifier, OAuth2 client identifier, a vector of scope strings, an optional expiration timestamp (milliseconds since epoch, or nil for no expiry), and an optional resource vector of target resource indicator URIs (per RFC 8707). Stores the token and its metadata. Returns true if saved successfully.