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.