Types and protocols¶

Runtime-checkable Protocol definitions and type aliases used across transports, strategies, and user models.

DbSessionDependencyKey is the public type alias for LitestarAuthConfig.db_session_dependency_key. It is an Annotated[str, ...] contract: values must be valid non-keyword Python identifiers because Litestar matches dependency keys to callable parameter names. The default is "db_session".

RoleCapableUserProtocol is the dedicated public typing surface for user objects that expose normalized flat roles membership. Use that protocol directly instead of treating an arbitrary roles attribute as sufficient.

That protocol describes the library boundary rather than a storage implementation detail. Bundled SQLAlchemy models now persist roles through relational role / user_role tables, but managers, schemas, and guards still exchange one normalized flat roles collection. This remains flat role membership, not a full RBAC permission model.

Which protocol should my user model implement?¶

Pick the narrowest protocol that covers the features you enable. If a guard or TOTP flow needs attributes your model does not expose, authentication may succeed while authorization fails with a generic permission error—so align the model with Guards and TOTP usage up front.

Use UserProtocol when code needs isinstance(user, UserProtocol) at runtime. Use UserProtocolStrict for static-only annotations and type-variable bounds. The strict variant avoids the @runtime_checkable tradeoff: runtime protocol checks are convenient but only validate the runtime-visible shape of the protocol and carry extra overhead.

Config inference and dependency-key typing¶

Construct LitestarAuthConfig directly. For strict typing, spell both generic parameters as LitestarAuthConfig[User, UUID](...) so the configured user and ID types stay explicit.

The db_session_dependency_key parameter is typed as DbSessionDependencyKey, so the annotation documents the same identifier rule enforced at runtime. This complete example type-checks as LitestarAuthConfig[User, UUID]:

from dataclasses import dataclass
from typing import assert_type
from uuid import UUID

from litestar_auth import LitestarAuthConfig
from litestar_auth.types import DbSessionDependencyKey
from litestar_auth.manager import BaseUserManager
from litestar_auth.types import UserProtocolStrict


@dataclass(slots=True)
class User:
    id: UUID
    email: str


class UserManager(BaseUserManager[User, UUID]):
    pass


def needs_static_user_contract(user: UserProtocolStrict[UUID]) -> UUID:
    return user.id


dependency_key: DbSessionDependencyKey = "db_session"

config = LitestarAuthConfig[User, UUID](
    user_model=User,
    user_manager_class=UserManager,
    db_session_dependency_key=dependency_key,
)

assert_type(config, LitestarAuthConfig[User, UUID])

Example: account state and roles together¶

A single model often needs GuardedUserProtocol and RoleCapableUserProtocol so both account-state and role guards can run:

from collections.abc import Sequence
from dataclasses import dataclass


@dataclass(slots=True)
class StaffUser:
    """Satisfies GuardedUserProtocol and RoleCapableUserProtocol."""

    id: int
    is_active: bool
    is_verified: bool
    roles: Sequence[str]

Add TOTP fields when you enable 2FA; see TotpUserProtocol in the generated API below.

131
132

async def read_token_with_context(self, token: str | None, user_manager: object) -> object | None:
    """Resolve a user plus strategy-specific request auth context."""

123
124

async def destroy_token(self, token: str, user: UP) -> None:
    """Invalidate a token for strategies that keep server-side state."""

117
118

async def read_token(self, token: str | None, user_manager: object) -> UP | None:
    """Resolve a user from a transport token."""

120
121

async def write_token(self, user: UP) -> str:
    """Create a token for a given user."""

103
104

async def read_token(self, connection: ASGIConnection[Any, Any, Any, Any]) -> str | None:
    """Extract a login token from an incoming connection."""

106
107

def set_login_token(self, response: Response[Any], token: str) -> Response[Any]:
    """Persist a login token on an outgoing response."""

109
110

def set_logout(self, response: Response[Any]) -> Response[Any]:
    """Clear any transport-specific authentication state."""