Oauth States

oauth_states

OAuth state adapter interface.

Defines the abstract interface for OAuth state token storage. State tokens prevent CSRF attacks during OAuth authentication flows.

Classes

OAuthStateAdapter

Bases: ABC

Abstract base class for OAuth state token operations.

State tokens prevent CSRF attacks in OAuth flows.

Functions

create abstractmethod

create(
    *,
    state_hash: str,
    provider: str,
    redirect_uri: str,
    code_challenge: str | None = None,
    code_challenge_method: str | None = None,
    user_id: UUID | None = None,
    expires_at: datetime
) -> Any

Create a new OAuth state token.

Parameters:

Name	Type	Description	Default
state_hash	str	Hashed state token	required
provider	str	OAuth provider name	required
redirect_uri	str	Callback URL after OAuth	required
code_challenge	str | None	Optional PKCE code challenge	None
code_challenge_method	str | None	PKCE challenge method (e.g., 'S256')	None
user_id	UUID | None	Optional user ID for linking existing account	None
expires_at	datetime	State token expiration datetime	required

Returns:

Type	Description
Any	Created OAuth state object

Source code in fastauth/adapters/base/oauth_states.py

@abstractmethod
def create(
    self,
    *,
    state_hash: str,
    provider: str,
    redirect_uri: str,
    code_challenge: str | None = None,
    code_challenge_method: str | None = None,
    user_id: uuid.UUID | None = None,
    expires_at: datetime,
) -> Any:
    """
    Create a new OAuth state token.

    Args:
        state_hash: Hashed state token
        provider: OAuth provider name
        redirect_uri: Callback URL after OAuth
        code_challenge: Optional PKCE code challenge
        code_challenge_method: PKCE challenge method (e.g., 'S256')
        user_id: Optional user ID for linking existing account
        expires_at: State token expiration datetime

    Returns:
        Created OAuth state object
    """
    ...

get_valid abstractmethod

get_valid(*, state_hash: str) -> Any

Get a valid (unused, non-expired) state token.

Parameters:

Name	Type	Description	Default
state_hash	str	Hashed state token to look up	required

Returns:

Type	Description
Any	OAuth state record if found and not used, None otherwise

Source code in fastauth/adapters/base/oauth_states.py

@abstractmethod
def get_valid(self, *, state_hash: str) -> Any:
    """
    Get a valid (unused, non-expired) state token.

    Args:
        state_hash: Hashed state token to look up

    Returns:
        OAuth state record if found and not used, None otherwise
    """
    ...

mark_used abstractmethod

mark_used(*, state_hash: str) -> None

Mark a state token as used (one-time use).

Parameters:

Name	Type	Description	Default
state_hash	str	Hashed state token to mark as used	required

Source code in fastauth/adapters/base/oauth_states.py

@abstractmethod
def mark_used(self, *, state_hash: str) -> None:
    """
    Mark a state token as used (one-time use).

    Args:
        state_hash: Hashed state token to mark as used
    """
    ...

cleanup_expired abstractmethod

cleanup_expired() -> None

Remove expired state tokens from database.

This can be called periodically to clean up old state tokens.

Source code in fastauth/adapters/base/oauth_states.py

@abstractmethod
def cleanup_expired(self) -> None:
    """
    Remove expired state tokens from database.

    This can be called periodically to clean up old state tokens.
    """
    ...