Email flows¶

Wire the sender port plus token lifetimes and link targets.

Links point at frontend_url with the signed token appended as a query param, e.g. {frontend_url}{verify_path}?token=....

EmailConfig(sender=MyEmailSender(), frontend_url="https://app.example.com")

link(path: str, token: str) -> str

Bases: ABC

Adapter crudauth calls to deliver a message.

crudauth composes the subject and a plain-text body (with the signed-token link in it) and hands them to you; you decide how to deliver (SMTP, SES, a task queue...). For a plain sender, deliver body as-is. To send your own HTML, read context - context.link is the assembled URL, so you can build a real <a href> button or branded template without regexing the link out of body.

context carries crudauth-owned render data only (link, kind, expiry, recipient), never the bare token and never user-controlled fields. For per-user personalization, write a DeliveryChannel (it has db and owns escaping) rather than reaching for user data here.

class MyEmailSender(EmailSender):
    async def send(self, *, to, subject, body, kind, context):
        # plain: deliver crudauth's text as-is.
        # html:  build your own from context.link.
        html = render(f"{kind}.html", link=context.link) if context.link else body
        await my_task_queue.enqueue(send_email, to=to, subject=subject, html=html)

send(
    *,
    to: str,
    subject: str,
    body: str,
    kind: EmailKind,
    context: EmailContext,
) -> None

crudauth-owned render data handed to EmailSender.send.

Everything a sender needs to render its own HTML around crudauth's recovery flow, and nothing else. Specifically it carries the assembled link (the signed token is already embedded in the URL, which is what gets emailed), not the bare token, and it carries no user-controlled fields (no username, no email). That is deliberate: a sender drops these values into HTML, so crudauth keeps anything injectable out of reach and is never the XSS vector.

For per-user personalization (Hi Alice), write a DeliveryChannel instead: it receives the db handle and the user row, and owns its own escaping.

Attributes:

# inside EmailSender.send, render your own HTML from the context:
html = f'<a href="{context.link}">Verify your email</a>'

Mints/verifies signed tokens and drives the recovery flows.

The package owns token lifecycle; delivery is pluggable via one or more DeliveryChannels (email is the built-in one). Trigger endpoints are throttled two ways: a per-IP edge limit (in the router) and a silent per-target-email limit here - silent because a 429 on a victim's address would re-introduce the enumeration oracle and hand an attacker a DoS lever against that user.

Each token carries a fingerprint of the account state it authorizes (an HMAC over, never a copy of, that state), so it stops working once that state moves on: a reset token after the password or recovery value changes, an email-change token after the password, email, or token_version changes, and a verification token after the recovery value changes.

Construction is additive: pass config=EmailConfig(...) (back-compat, which builds an EmailChannel and seeds the token TTLs) and/or channels=[...] plus explicit *_ttl_hours. Reachable as auth.emails (None when no recovery is configured).

if auth.emails is not None:
    await auth.emails.request_password_reset(db, email)

supports_email_change: bool

notify_existing_account(value: str) -> None

request_recovery_verification(
    db: AsyncSession,
    value: str,
    *,
    redirect_to: str | None = None,
) -> None

confirm_recovery_verification(
    db: AsyncSession, token: str
) -> EmailFlowResult

request_password_reset(
    db: AsyncSession,
    value: str,
    *,
    redirect_to: str | None = None,
) -> None

reset_password(
    db: AsyncSession, token: str, new_password: str
) -> EmailFlowResult

request_email_change(
    db: AsyncSession,
    user: Any,
    new_email: str,
    password: str,
    *,
    redirect_to: str | None = None,
) -> None

confirm_email_change(
    db: AsyncSession, token: str
) -> EmailFlowResult

Bases: NamedTuple

What a confirmed recovery flow produced.

Attributes: