Skip to content

Hooks

Lifecycle callbacks for app policy (welcome email, trial grant, audit log). A hook fires uniformly across every path that creates or authenticates a user.

crudauth.hooks.AuthHooks dataclass

AuthHooks(
    on_after_register: Hook | None = None,
    on_oauth_login: Hook | None = None,
    on_login_failed: Hook | None = None,
    on_lockout: Hook | None = None,
    on_after_login: Hook | None = None,
    on_after_logout: Hook | None = None,
    on_after_recovery_verified: Hook | None = None,
    on_after_password_reset: Hook | None = None,
    on_after_password_changed: Hook | None = None,
    on_after_email_changed: Hook | None = None,
    on_after_sudo: Hook | None = None,
    on_after_mfa_enabled: Hook | None = None,
    on_after_mfa_disabled: Hook | None = None,
    on_after_recovery_code_used: Hook | None = None,
)

Container of optional lifecycle callbacks.

Every hook may be sync or async. user is passed as a plain dict so hooks don't depend on your ORM type. Example:

```python
async def after_register(user, *, db, context):
    await grant_trial(user["id"], db=db)

AuthHooks(on_after_register=after_register)
```
Note

Hooks run after the operation is done (the account created, the session stored, the password changed), so they can't block or undo it. An exception a hook raises is logged on the crudauth.hooks logger with its traceback and the request completes normally. A hook that writes through db commits its own work; if it raises, crudauth rolls back whatever it left uncommitted, and it may roll back itself as well.

run_oauth_login async

run_oauth_login(
    user: dict,
    info: "OAuthUserInfo",
    *,
    db: Any,
    created: bool,
    context: HookContext,
) -> None

An OAuth sign-in resolved an active account: created, linked by email, or found.

info is the provider's normalized profile (info.username is the GitHub login, info.raw_data the provider's payload), so an app can keep provider data that changes over time in step on every sign-in. created is True only when this sign-in made the account. It runs before the MFA challenge and before the session exists, so context.session_handle is None.

A hand-written callback that resolves the account with auth.oauth.get_or_create_user calls this itself, after its own checks.

run_login_failed async

run_login_failed(
    identifier: str,
    *,
    user: dict | None,
    reason: str,
    context: HookContext,
) -> None

A password login was refused: reason is "invalid_credentials" or "inactive".

user is the account the identifier resolved to, or None when it named none. The caller's response doesn't distinguish the two; this hook can, for an audit log.

run_lockout async

run_lockout(
    identifier: str,
    *,
    retry_after: int,
    context: HookContext,
) -> None

A password login was refused because the lockout is engaged for this IP or identifier.

crudauth.hooks.HookContext dataclass

HookContext(
    ip_address: str | None = None,
    user_agent: str | None = None,
    transport: str | None = None,
    request: "Request | None" = None,
    extra: dict[str, Any] | None = None,
    session_handle: str | None = None,
)

Ambient request/identity info passed to hooks as context=.

session_handle is set on a session login and logout: the same public, non-reversible handle GET /sessions lists, so an audit log can name the session that was created or ended (and match it to a revocation) without storing a credential.