Module auth 

Authentication & authorization.

Three pieces:

• users.rs — user records, password hashing, login
• sessions.rs — DB-backed sessions with expiry cleanup
• permissions.rs — granular permissions + groups

A user belongs to zero or more groups. Permissions come from two sources: (a) direct assignments on the user, (b) inherited from the user’s groups. The permission string is <app>.<action>_<model> — e.g. posts.change_post.

Modules

guards

Authority guards — server-side enforcement of the rank model.

Structs

DefaultPasswordPolicy

Length-only password policy. Default min_len is 10 — the secure-by-default baseline R1 ships with: long enough to defeat trivial guessing under Argon2id + per-IP rate-limiting (NIST SP 800-63B’s recommended length floor is 8, with longer being preferable), short enough not to drive operators toward sticky- note workarounds. Production / regulated deployments are encouraged to override to 12+ via crate::admin::Admin::password_policy; high-sensitivity deployments may want 16+ paired with an organisational complexity rule or breach blocklist.

DefaultRecoveryPolicy

Length-only / rate-limit-only baseline policy. Public fields plus chainable with_* setters so projects that want to tweak one knob don’t need to author a full trait impl.

Identity

The identity attached to a request by the auth middleware. Kept cheap to clone because we pass it into handler bodies.

InvalidationOutcome

Outcome of an invalidate_sessions call. Used by the audit pipeline to write one row per affected session and by the caller to decide whether to clear the user’s cookie.

Permission

Session

One session row, reconstructed from rustio_sessions. Returned by list_active_for_user for the active-sessions UI.

StoredUser

Superuser

Marker type used by the admin’s authorize macro for fast-paths on admins.

UserProfile

Read-only view of a user, used by the built-in admin profile page. Excludes password_hash deliberately. Construct via load_user_profile.

Enums

PasswordPolicyError

Reasons a candidate password fails policy validation.

PermissionError

Role

SessionInvalidationReason

Why a session is being invalidated. Drives both the audit action_type and decisions about whether to clear remembered MFA or mint a replacement session.

SessionTarget

Which sessions an invalidate_sessions call targets.

SessionTrust

Trust level a session has acquired. The login flow mints SessionTrust::Authenticated; the future re-auth wall promotes to SessionTrust::Elevated; a successful TOTP step on this session lifts to SessionTrust::MfaVerified.

Constants

SESSION_COOKIE

The cookie name we look for and set. Constant so middleware and handlers stay in sync.

Traits

PasswordPolicy

Validates a candidate password against project-defined rules.

RecoveryPolicy

Tunables for the R1 recovery flow: token TTL, rate-limit shape, strict-mailer boot guard, and public-site-URL derivation.

Functions

add_user_to_group

check_permission

Ask “does this identity have permission X?”.

create_group

create_session

create_user

current_session_id

Resolve the cookie token to its session_id (active sessions only). Used by the active-sessions UI to mark which row is the current device, and by UserExceptCurrent callers.

delete_session

Hard-delete a session row by cookie token. Retained as a pre-0.4.0 compatibility shim — internal callers are migrating to invalidate_sessions, which soft-revokes via revoked_at and keeps the row available for the audit trail. New code MUST NOT call this directly; only the expired-row sweeper and the read-path stale-cleanup branch are allowed callers, both of which are inside this module.

find_user_by_email

grant_to_group

grant_to_user

hash_password

identity_from_session

init_permission_tables

init_session_tables

init_tables

Initialise every auth-related table. Safe to call on every boot.

init_user_tables

invalidate_sessions

Centralised session invalidation — the single legitimate writer of rustio_sessions.revoked_at.

list_active_for_user

List a user’s currently-active sessions, ordered by last_seen descending so the active-sessions UI surfaces the most recently used row first. Excludes revoked + expired rows.

load_user_profile

Load a user by id for display purposes. Returns Ok(None) for a missing id (callers map to 404). Returns Err only on a real DB failure or a corrupted role string. Never reads password_hash.

login

Verify credentials and create a session. Returns the session token to set in the cookie. A deliberately vague error on failure — we don’t want to leak whether the email was valid.

logout_session

Convenience wrapper for the existing logout flow. Routes through invalidate_sessions with SessionTarget::Single and SessionInvalidationReason::Logout.

migrate_user_schema

Idempotent schema upgrade for the 5-tier role hierarchy + demo + profile columns. Safe to call repeatedly; safe on a fresh DB and on a legacy 'admin'-roled DB.

permissions_for_user

All permission names belonging to the given user — direct + via groups — unioned into one set. Cached for 60s.

protected_roles

Roles the framework refuses to lose its last active member of.

purge_expired_sessions

Delete all expired sessions. Intended to be called periodically from a background task (see background::spawn_session_sweeper).

register_model_permissions

For an admin model named posts, register the canonical four permissions: add_post, change_post, delete_post, view_post. Idempotent.

remove_user_from_group

session_token_from_cookie

set_password

Re-hash and write a new password for user_id. Stamps both password_changed_at and updated_at to the same NOW() — password_changed_at is the doctrine-7 surface (“Password last changed: 2 days ago”) that the active-sessions UI reads; the existing updated_at continues to track row-level edits.

update_user_role

verdict_for_orphan_role

Pure verdict for the orphan check, factored out so it can be unit-tested without a Db. The async wrapper would_orphan_role supplies active_count and target_is_protected from SQL.

verify_password

would_orphan_developersDeprecated

Legacy alias preserved so external callers keep compiling. Prefer would_orphan_protected which generalises across every role in super::role::protected_roles.

would_orphan_protected

Walk every entry in super::role::protected_roles and return the first protected role whose membership would be orphaned by the proposed change. None means the change is safe.

would_orphan_role

Would the proposed change leave the system with zero active members of protected_role?

Type Aliases

SharedPasswordPolicy

Type-erased shared password-policy reference, mirroring crate::email::SharedMailer. The framework’s Admin holds one of these; defaults to Arc::new(DefaultPasswordPolicy::new()) until a project overrides via Admin::password_policy(Arc::new(...)).

SharedRecoveryPolicy

Type-erased shared recovery-policy reference, mirroring SharedPasswordPolicy / crate::email::SharedMailer.