Struct AuthPlugin 

pub struct AuthPlugin<U: UserModel = AuthUser> {
    pub user_model_name: Option<String>,
    pub default_routes_prefix: Option<String>,
    pub form_routes_prefix: Option<String>,
    pub user_in_templates: bool,
    /* private fields */
}

The built-in authentication plugin, generic over the user model.

U defaults to AuthUser so AuthPlugin::default() continues to work in all existing code unchanged. Apps that need a custom user type opt in with one line:

.plugin(AuthPlugin::<CustomUser>::default())

user_model_name

An optional informational string surfaced in OpenAPI schemas and the admin nav. Default None (resolved from U::NAME by the plugin itself when left empty). Set it explicitly when the type name is insufficient:

AuthPlugin::<TenantUser>::default().user_model_name("tenant_user")

Fields

user_model_name: Option<String>

Documentation-only: the human-readable name of the active user model. Consumed by admin / OpenAPI when surfacing the user table. The actual dispatch is entirely through the type parameter U.

default_routes_prefix: Option<String>

When Some, mount the four built-in routes (register / login / logout / me) under this prefix. None skips them — the user either doesn’t want them or is rolling their own surface. Only settable on AuthPlugin<AuthUser> (the handlers FK into AuthToken → AuthUser); custom user models bring their own.

form_routes_prefix: Option<String>

When Some, mount the 7 POST form-action routes (login, logout, signup, verify-email, resend, password-forgot, password-reset) under this prefix. Default None — opt in via AuthPlugin::with_form_routes / AuthPlugin::with_form_routes_at. Only settable on AuthPlugin<AuthUser>.

user_in_templates: bool

When true, wrap the app router with user_context_layer so every template render has user in its global context: { is_authenticated, is_staff, username, ... }. Opt-in because it costs one DB read per request (cookie → session → user); a REST-only service has nothing to gain from it. Set via AuthPlugin::with_user_in_templates.

Implementations

impl<U: UserModel> AuthPlugin<U>

pub fn user_model_name(self, name: impl Into<String>) -> Self

Override the informational user-model name shown in admin / OpenAPI. Fluent builder method; the return type is Self so it chains.

pub fn with_user_in_templates(self) -> Self

Mount the user_context_layer middleware globally so every HTML template gets user in its render context — anonymous requests see { is_authenticated: false }, authenticated requests see the full serialized AuthUser merged with is_authenticated: true. Lets templates write {% if user.is_staff %} without the consumer having to thread a user value into every handler’s context manually.

One DB read per request (cookie → session → user row). Off by default because REST-only services have no templates and the cost would be pure overhead. Turn it on for HTML-heavy apps:

AuthPlugin::<AuthUser>::default()
    .with_default_routes()
    .with_user_in_templates()   // ← here

Implemented via Plugin::wrap_router; the wrapper wraps the merged app router (including every other plugin’s routes), so admin / REST / playground / your own handlers all see the populated context with one builder call.

pub fn password_validators(self, policy: PasswordPolicy) -> Self

Replace the default password-strength policy with a custom one. The full PasswordPolicy you pass becomes the active set at boot; the default validators are NOT merged in. Build the policy you want from scratch:

use umbral_auth::{AuthPlugin, PasswordPolicy, MinLengthValidator, CommonPasswordValidator};
AuthPlugin::<AuthUser>::default().password_validators(
    PasswordPolicy::empty()
        .with(Box::new(MinLengthValidator(12)))
        .with(Box::new(CommonPasswordValidator)),
)

pub fn min_password_length(self, n: usize) -> Self

Convenience: keep the four default validators but change the minimum password length. Equivalent to building a PasswordPolicy with a MinLengthValidator of n plus the other three defaults.

pub fn disable_password_validation(self) -> Self

Explicit opt-OUT: install an empty policy so NO password validation runs. Secure-by-default means an app that genuinely wants to accept any password — a throwaway demo, a migration importing legacy hashes with externally-validated plaintext — has to ask for it by name. Don’t reach for this to silence a failing test; fix the fixture’s password instead.

pub fn login_throttle(self, max: usize, window: Duration) -> Self

Tune the login rate limit: max failed-or-not attempts per trailing window, keyed per IP + username. The default is 5 / 5 min — a budget that stops credential-stuffing dead while leaving room for a human who fat-fingers their password a couple of times (a successful login also clears the counter). Lower it for a high-security surface; raise it for a shared-NAT office where many users hit login from one IP.

AuthPlugin::<AuthUser>::default().login_throttle(10, Duration::from_secs(300))

pub fn register_throttle(self, max: usize, window: Duration) -> Self

Tune the register rate limit: max account-creation attempts per trailing window, keyed per IP. The default is 10 / hour, which brakes mass automated signups without blocking a legitimate burst from one office.

pub fn email_action_throttle(self, max: usize, window: Duration) -> Self

Tune the email-action rate limit: max attempts per trailing window, keyed per IP + email. Covers verify-email, resend-verification, and password-forgot. The default is 5 / hour — enough for a user who needs a couple of resends, but low enough to stop email-bombing / online code-guessing scripts dead.

pub fn disable_throttle(self) -> Self

Explicit opt-OUT: turn login, register, and email-action throttling OFF entirely. Secure-by-default means an app that genuinely wants no rate limit — a load test, an internal tool behind its own gateway limiter — has to ask for it by name. Don’t reach for this to silence a throttled test; use a distinct IP/username per attempt or generous budget methods instead.

pub fn mailer(self, m: impl AuthMailer + 'static) -> Self

Wire the mailer used by the verification + password-reset flows. Pass a type implementing AuthMailer or an async closure |mail| async { ... }. Unset → ConsoleMailer (stderr in dev).

AuthPlugin::<AuthUser>::default().mailer(|m: OutgoingMail| async move {
    umbral_email::send(&umbral_email::EmailMessage::new(m.subject, vec![m.to])
        .html_body(m.html).text_body(m.text)).await
        .map(|_| ()).map_err(|e| AuthMailError::Send(e.to_string()))
})

impl AuthPlugin<AuthUser>

pub fn with_default_routes(self) -> Self

Mount the built-in /api/auth/{register,login,logout,me,…} surface. Same handlers that lived in the derive-demo example app, promoted to the framework so every app gets them with one line. JSON-only; UNIQUE-violation → 409; login returns both a Set-Cookie and a bearer token in one response so browsers and CLI clients share an endpoint.

The prefix resolves at build time: {api_base()}/auth, so it follows whatever base the REST plugin set (default /api/auth). Use Self::with_default_routes_at to fix a literal prefix.

pub fn with_default_routes_at(self, prefix: impl Into<String>) -> Self

Same as Self::with_default_routes but the prefix is yours to pick. Useful when /api/auth collides with an existing surface or you want versioning (/v1/auth).

pub fn require_verified_email(self) -> Self

Block login until the user’s email_verified_at column is stamped, and auto-send a verification code immediately on register. Off by default — the email_verified_at column is always tracked and the /verify-email + /resend-verification endpoints are always mounted; this flag only controls enforcement:

• register: after a successful create_user, fires start_email_verification best-effort (a mail failure does NOT fail registration; it is logged at warn level). The 201 response is unchanged.
• login: after authenticate succeeds and before minting the bearer token / session, checks email_verified_at IS NULL; returns 403 {error: "email_not_verified"} if so.

Available only on AuthPlugin<AuthUser> because enforcement is implemented inside the built-in handlers (which are AuthUser-only). Custom user models bring their own routes and their own enforcement.

Requires a working mailer in production — wire AuthPlugin::mailer alongside this builder, or users won’t receive the verification code and will be permanently locked out:

AuthPlugin::<AuthUser>::default()
    .with_default_routes()
    .mailer(my_smtp_mailer)
    .require_verified_email()

pub fn with_form_routes(self) -> Self

Mount the 7 POST form-action auth routes (login, logout, signup, verify-email, resend, password-forgot, password-reset) under the default /auth prefix.

These are the form-action endpoints that developer-written HTML forms POST to: <form method="POST" action="/auth/login">. The framework never ships the pages themselves — the developer writes those with their own brand and design.

Each handler receives a form-encoded body, runs the same auth logic as the JSON surface (including throttle and enumeration-safe guards), sets a flash message via the session, then returns a 303 redirect.

Use Self::with_form_routes_at to mount under a custom prefix.

pub fn with_form_routes_at(self, prefix: impl Into<String>) -> Self

Same as Self::with_form_routes but you choose the prefix.

AuthPlugin::<AuthUser>::default().with_form_routes_at("/accounts")

Trait Implementations

impl<U: Debug + UserModel> Debug for AuthPlugin<U>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<U: UserModel> Default for AuthPlugin<U>

fn default() -> Self

Returns the “default value” for a type.

impl<U: UserModel> Plugin for AuthPlugin<U>

fn wrap_router(&self, router: Router) -> Router

Mount user_context_layer on the full merged router when the user_in_templates flag is on (see AuthPlugin::with_user_in_templates). The layer reads the session cookie, hydrates the AuthUser, and pushes a serde_json representation into umbral::templates::CURRENT_USER for the duration of the request — every template render downstream gets user in its global context with no per-handler plumbing.

Off by default — see the builder method’s docstring for the “why” (one DB read per request, pointless for REST-only apps).

fn on_ready(&self, _ctx: &AppContext) -> Result<(), PluginError>

Seal the password-strength policy into the ambient OnceLock so the free-function helpers (create_user, set_password) can read it without a handle to Self. Mirrors the sessions plugin’s SLIDING_EXPIRY_ENABLED install.

A None configured policy means “use the secure default” — NOT “off” — so we install PasswordPolicy::default in that case. disable_password_validation is the only path that installs an empty policy. The install is idempotent (first boot wins), matching the ambient-pool contract.

fn name(&self) -> &'static str

A stable identifier. Used as the key in the migration tracking table, in dependency lists, and as the directory name under migrations/. Plugin names live in the same namespace as migrate::APP_PLUGIN_NAME ("app"), so user crates must not pick the name "app".

fn models(&self) -> Vec<ModelMeta>

The plugin’s models, in declaration order. The M7 migration engine collects these across every registered plugin and uses them as the diff target for makemigrations.

fn templates_dirs(&self) -> Vec<PathBuf>

Template directories this plugin contributes.

fn commands(&self) -> Vec<Box<dyn PluginCommand>>

CLI subcommands the plugin contributes.

fn routes(&self) -> Router

The plugin’s HTTP routes. Merged into the app router after the hand-written one passed to AppBuilder::routes(). Plugins choose their own path prefixes (spec 02 §“What a plugin can contribute”: routes are flat, not auto-prefixed).

fn route_paths(&self) -> Vec<RouteSpec>

Declared URL routes this plugin contributes — a companion to routes used for surfacing route lists outside the request flow (currently: the dev-mode default 404 page). axum doesn’t expose its internal route table, so plugins report what they declare here; the framework treats this as informational only — not a source of truth for routing.

fn openapi_paths(&self) -> Vec<(String, Value)>

OpenAPI path items the plugin contributes. Returned as a Vec<(path, value)> where path is the URL template (/api/auth/login, /api/foo/{id}) and value is the matching OpenAPI 3.0 Path Item Object serialised as a serde_json::Value.

fn dependencies(&self) -> &'static [&'static str]

Names of plugins that must load before this one. The App::builder() topological sort uses this; cycles surface as BuildError::PluginCycle. The default is no dependencies.

fn system_checks(&self) -> Vec<SystemCheck>

Boot-time checks the plugin needs to pass. Run in phase 4 of App::build() alongside the framework’s built-in checks. Severity::Error blocks boot; Severity::Warning logs and continues.

fn provides_storage(&self) -> bool

true if this plugin registers a Storage backend (e.g. StoragePlugin, which calls crate::storage::set_storage in Plugin::on_ready).

fn database(&self) -> Option<&'static str>

The database alias every model this plugin contributes should be read from and written to. Returns None to use the "default" pool (the same one umbral::db::pool() returns).

fn template_registrars( &self, ) -> Vec<Box<dyn Fn(&mut Environment<'static>) + Sync + Send>>

Custom template tags / filters this plugin contributes (feature #67 - a loadable template tag/filter library).

fn middleware(&self) -> Vec<Arc<dyn Middleware>>

Framework-level request/response middleware this plugin contributes (feature #68).

fn static_files(&self) -> Vec<StaticFile>

Static files the plugin ships baked into its binary.

fn static_dirs(&self) -> Vec<StaticDir>

On-disk source directories this plugin contributes to the unified static pipeline.

fn static_root_dirs(&self) -> Vec<PathBuf>

On-disk directories served at the root of static_url — with no namespace segment.

fn api_endpoints(&self) -> Vec<ApiEndpoint>

Callable HTTP endpoints this plugin wants advertised in a machine-readable index (e.g. a REST API root, or a client’s service-discovery fetch).