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

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

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.

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

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?