Skip to content

OAuth state

reauth.factors.oauth2.state

OAuth2State dataclass 

OAuth2State(
    id: Any | None,
    token_identifier: str,
    token_verifier: str,
    provider: str,
    code_verifier: str | None,
    nonce: str | None,
    redirect_uri: str,
    identity_id: Any | None,
    scope: list[str] | None,
    expires_at: int,
    context: dict[str, Any] | None = None,
)

id instance-attribute 

id: Any | None

token_identifier instance-attribute 

token_identifier: str

token_verifier instance-attribute 

token_verifier: str

provider instance-attribute 

provider: str

code_verifier instance-attribute 

code_verifier: str | None

nonce instance-attribute 

nonce: str | None

redirect_uri instance-attribute 

redirect_uri: str

identity_id instance-attribute 

identity_id: Any | None

scope instance-attribute 

scope: list[str] | None

expires_at instance-attribute 

expires_at: int

context class-attribute instance-attribute 

context: dict[str, Any] | None = None

OAuth2StateException 

OAuth2StateException(message: str | None = None)

Bases: ReauthException

Base exception for OAuth2 state errors.

InvalidStateException 

InvalidStateException(message: str | None = None)

Bases: OAuth2StateException

Raised when a state token is invalid or does not correspond to any state.

ExpiredStateException 

ExpiredStateException(message: str | None = None)

Bases: OAuth2StateException

Raised when a state has expired.

OAuth2StateService 

OAuth2StateService(
    *,
    token_provider: TokenProvider,
    lifetime: timedelta = datetime.timedelta(minutes=10),
)

Bases: ABC

Service for managing OAuth2 state data storage.

Pure CRUD operations - no business logic. The factor handles flow validation.

token_provider instance-attribute 

token_provider = token_provider

lifetime instance-attribute 

lifetime = lifetime

create async 

create(
    *,
    provider: str,
    redirect_uri: str,
    identity_id: Any | None = None,
    nonce: str | None = None,
    code_verifier: str | None = None,
    scope: list[str] | None = None,
    **context: Any,
) -> tuple[str, OAuth2State]

Create a new OAuth2 state and store it.

Returns:

Type Description
str

A tuple of (state_token, OAuth2State).
OAuth2State

The caller MUST bind state_token to the user agent context.

Raises:

Type Description
TokenGenerationException

If credential generation repeatedly collides.

consume async 

consume(state: str) -> OAuth2State

Atomically retrieve and delete an OAuth2 state.

Parameters:

Name Type Description Default
state str

The state token to consume.

 required

Returns:

Type Description
OAuth2State

The corresponding OAuth2State instance.

Raises:

Type Description
InvalidStateException

If the state is invalid or does not correspond to any state.
ExpiredStateException

If the state has expired.

get_by_token_identifier abstractmethod async 

get_by_token_identifier(
    token_identifier: str,
) -> OAuth2State | None

Retrieve OAuth2 state by its identifier from persistent store.

Parameters:

Name Type Description Default
token_identifier str

The identifier of the state token to look up.

 required

Returns:

Type Description
OAuth2State | None

The corresponding OAuth2State instance, or None if not found.
Implementation contract

Match the supplied token identifier and include expired rows without validating them. Acquire protection before reading and retain it until the caller's transaction ends, preventing competing mutations of the returned state. Leave commit and rollback to the caller.

insert abstractmethod async 

insert(oauth2_state: OAuth2State) -> typing.Any

Insert OAuth2 state into persistent store.

Parameters:

Name Type Description Default
oauth2_state OAuth2State

The OAuth2State instance to insert.

 required

Returns:

Type Description
Any

The ID of the inserted OAuth2State.

Raises:

Type Description
TokenIdentifierCollision

If the identifier already exists in the store.
Implementation contract

Persist the supplied state, enforce uniqueness of token_identifier, and return the record ID. On identifier collision, raise TokenIdentifierCollision without persisting changes and leave the transaction usable for retry. Leave commit and rollback to the caller.

delete abstractmethod async 

delete(oauth2_state: OAuth2State) -> None

Delete OAuth2 state from persistent store.

Parameters:

Name Type Description Default
oauth2_state OAuth2State

The OAuth2State instance to delete.

 required
Implementation contract

Delete the supplied state by ID in the transaction that protects the record. Leave commit and rollback to the caller. Deletion becomes durable on commit; a rollback restores the state.