Skip to content

OAuth state

reauth.factors.oauth2.state

OAuth2State dataclass 

OAuth2State(
    id: Any | None,
    state_hash: TokenHash,
    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

state_hash instance-attribute 

state_hash: TokenHash

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(
    *,
    hash_secret: str,
    lifetime: timedelta = datetime.timedelta(minutes=10),
    token_prefix: str = "reauth_oauth2_",
)

Bases: ABC

Service for managing OAuth2 state data storage.

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

hash_secret instance-attribute 

hash_secret = hash_secret

lifetime instance-attribute 

lifetime = lifetime

token_prefix instance-attribute 

token_prefix = token_prefix

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.

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_state_hash abstractmethod async 

get_by_state_hash(
    state_hash: TokenHash,
) -> OAuth2State | None

Retrieve OAuth2 state by its hash from persistent store.

Parameters:

Name Type Description Default
state_hash TokenHash

The hash of the state token to look up.

 required

Returns:

Type Description
OAuth2State | None

The corresponding OAuth2State instance, or None if not found.

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.

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