Skip to content

Core

Shared runtime types. The Transport port itself is documented under Transports.

crudauth.core.CookieConfig dataclass 

CookieConfig(
    secure: bool = True,
    samesite: SameSite = "lax",
    path: str = "/",
)

One cookie policy, shared by every transport that sets cookies.

Configured once on CRUDAuth and threaded through AuthRuntime, so the session cookie and the bearer refresh cookie can't silently disagree on secure/samesite. A transport may still be handed its own CookieConfig to override the app-wide default.

crudauth.core.AuthContext dataclass 

AuthContext(
    request: Request,
    db: "AsyncSession",
    runtime: AuthRuntime,
    _cache: dict[Any, Any] = dict(),
)

Per-request context passed to Transport.authenticate.

resolve_user async 

resolve_user(user_id: Any) -> Any | None

Shared identity resolver - load the user row for user_id (cached per request).

build_principal 

build_principal(
    *,
    user_id: Any,
    user: Any,
    transport: str,
    scopes: tuple[str, ...] = (),
    metadata: dict[str, Any] | None = None,
) -> Principal

Construct a Principal, filling status flags from the user row.

crudauth.core.AuthRuntime dataclass 

AuthRuntime(
    secret_key: str,
    repo: "UserRepository",
    hooks: "AuthHooks",
    redirect_base_url: str | None = None,
    email_service: "EmailFlowService | None" = None,
    db_dependency: Callable[..., Any] | None = None,
    algorithm: str = DEFAULT_ALGORITHM,
    cookie_config: CookieConfig = CookieConfig(),
    rate_limiter: "RateLimiterBackend | None" = None,
    lockout: "LockoutPolicy | None" = None,
    trusted_proxy_hops: int = 0,
)

Shared, facade-owned state handed to every transport via Transport.bind.

Transports are constructed by the user as lightweight config objects (SessionTransport(backend="redis")); the facade binds them to this runtime so they can reach the secret key, the user repository, hooks, etc., without the user having to wire any of it.

Attributes:

Name Type Description
secret_key str

Key for signing/verifying tokens.
repo 'UserRepository'

The user repository (logical-field contract over the app's model).
hooks 'AuthHooks'

Lifecycle hooks (on_after_register, on_after_login, ...).
redirect_base_url str | None

Base URL for building OAuth redirect URIs.
email_service 'EmailFlowService | None'

Email flow service, or None when email isn't configured.
db_dependency Callable[..., Any] | None

FastAPI dependency yielding an AsyncSession.
algorithm str

JWT signing algorithm.
cookie_config CookieConfig

App-wide cookie policy.
rate_limiter 'RateLimiterBackend | None'

Pluggable rate-limiter backend.
lockout 'LockoutPolicy | None'

Shared escalating login-lockout policy.
trusted_proxy_hops int

Number of trusted reverse proxies in front of the app, used to resolve the client IP from X-Forwarded-For. 0 (default) ignores the header and uses the socket peer.
Note

lockout is a single shared policy used by BOTH the session /login and bearer /token routes, keyed identically so neither endpoint can sidestep the other's failure counter.