Crate arium 

Framework-agnostic authentication engine for axum + sqlx fullstack apps.

arium owns the auth domain — password hashing, sessions, OAuth and OpenID Connect (GitHub, Google, Microsoft, or any OIDC issuer), MFA/TOTP, email verification + password reset, RBAC, API tokens, and an audit log — plus the install helper that bolts the whole thing onto an axum::Router. It has no UI-framework dependency; framework adapters such as arium-dioxus wrap these primitives in their own server fns + UI.

Typical server-side usage:

use arium::{
    AuthConfig, Mailer, install, migrator,
    oauth::{github::GithubProvider, OAuthRegistry},
};

let pool = sqlx::sqlite::SqlitePoolOptions::new()
    .connect_with("sqlite://./app.db?mode=rwc".parse()?)
    .await?;
migrator().run(&pool).await?;

let mut oauth = OAuthRegistry::new(pool.clone())?;
if let Some(gh) = GithubProvider::from_env()? {
    oauth = oauth.with_provider(gh);
}

let cfg = AuthConfig::builder(pool.clone(), Mailer::from_env()?)
    .oauth(oauth)
    .build()?;

// `router` is any `axum::Router` (e.g. your framework's server router).
let router = install(router, cfg).await?;

oauth-github is on by default. The opt-in oauth-oidc, oauth-google, and oauth-microsoft features add a generic OpenID Connect provider plus Google/Microsoft presets — each from_env()-constructed and registered the same way as GithubProvider above.

Per-resource authorization

Beyond global RBAC (flat permission tokens), the authz module adds relationship-based checks — “what role does this user hold on this resource?” Implement authz::ResourceAuthority over your own membership storage and guard resource-scoped mutations with require_resource; it does a fresh per-request lookup and default-denies. arium ships no membership table — the app owns that storage; arium owns the enforcement boundary and the ResourceRole lattice.

Re-exports

pub use config::AuditConfig;

pub use config::AuthConfig;

pub use config::AuthConfigBuilder;

pub use config::RECOMMENDED_HSTS;

pub use config::RateLimitConfig;

pub use api_key::ApiKeyUser;

pub use extract::AuditCtx;

pub use extract::AuthUser;

pub use extract::AuthzCtx;

pub use extract::ResourceAuthorityExt;

pub use extract::SessionStore;

pub use mail::Mailer;

pub use arium_wire as wire;

Modules

api_key

Bearer-token authentication: the axum middleware that turns an Authorization: Bearer <token> header into an api_key::ApiKeyUser request extension, applied automatically by install. Gated on tokens (it hashes the presented token with auth::tokens). Bearer-token authentication middleware.

auth

Server-side authentication primitives: the User model that the session layer loads, the password and MFA flows, the audit-log emitter, and the helpers every server fn uses to identify the caller.

authz

Per-resource authorization, re-exported from the standalone arium_authz crate so arium::authz::* and arium::membership::* keep resolving for existing code (and the framework adapters). The global↔resource bridge (require_resource_or_permission) and the bundled SqlMembershipStore stay in this crate — they touch the auth engine and its schema. Per-resource, relationship-based authorization — the second axis arium’s global RBAC (flat permission tokens) can’t express.

config

Configuration object the consumer hands to crate::install.

extract

Axum request extractors shared across arium’s framework adapters.

mail

Outbound email infrastructure.

membership

Per-resource authorization, re-exported from the standalone arium_authz crate so arium::authz::* and arium::membership::* keep resolving for existing code (and the framework adapters). The global↔resource bridge (require_resource_or_permission) and the bundled SqlMembershipStore stay in this crate — they touch the auth engine and its schema. Membership lifecycle and enumeration — the management layer above authz’s per-request enforcement.

oauth

Pluggable third-party OAuth providers.

pool

Compile-time-selected sqlx pool aliases.

Structs

ApiTokenView

One row in the user’s API-token list. The full secret is NEVER returned after creation — only prefix ("dxsk_abcd") so the UI can disambiguate tokens by sight.

CreateApiTokenResponse

Response from create_api_token. token is the cleartext secret — shown to the user ONCE and never recoverable from the server.

Membership

One user’s role on a resource, as returned by MembershipStore::list_members.

MfaSetupView

Setup payload returned to the client when starting MFA enrollment. recovery_codes is the only time these appear in plaintext anywhere — the server only persists Argon2 hashes.

ProviderInfo

One third-party identity provider the server has credentials for and is willing to mount routes for. Returned by available_providers so the client can render a button per entry without needing to know which provider features were compiled in.

ResourceRef

Identifies one resource instance for an authorization check. kind is an opaque, app-chosen namespace ("board", "doc", …) and id the row id within it. Borrowed so a check on the request hot path needn’t allocate.

SqlMembershipStore

A MembershipStore backed by arium’s arium_resource_members table. Stateless — construct with SqlMembershipStore wherever a store is needed.

TxExec

A live transaction handle arium opens and threads into MembershipStore write primitives so a composite’s steps commit or roll back together.

UserProfile

Profile fields safe to expose to the client.

Enums

LoginOutcome

Result of a sign-in or sign-up attempt.

MembershipError

Why a membership composite did not complete.

MfaStatusView

Whether the current user has MFA enabled, pending, or off entirely.

ResourceAuthzError

Why a require_resource check did not pass.

ResourceGrant

Which axis authorized a require_resource_or_permission call.

ResourceRole

The relationship role a user holds on a single resource (a board, a document, …). The variants form an ordered lattice: a higher role subsumes every capability of the lower ones, so the access check is a plain held_role >= required_role. Declaration order defines that ordering via the derived Ord — do not reorder the variants.

Traits

MembershipStore

Storage-shaped primitives for managing and enumerating resource memberships.

ResourceAuthority

App-implemented lookup of a user’s role on a resource — the one method an app writes to plug its own membership storage into arium’s per-resource enforcement. arium never stores resource memberships itself.

Functions

grant_membership

Grant target_id the role role on resource, acting as actor_id.

install

Attach all arium wiring to router and return the augmented Router.

membership_migrator

Returns the migrator that creates the arium_resource_members table backing the bundled SqlMembershipStore.

migrator

Returns the embedded migrator that creates the users, oauth_accounts, roles, audit_events, api_keys, and related tables arium owns.

require_resource

Fresh, per-request authorization check for a single resource — the security boundary for resource-scoped actions.

require_resource_audited

require_resource plus the standard audit-on-denial, driven by an already-resolved user_id. The reusable kernel behind the framework adapters’ session guards (e.g. dioxus’s require_resource_dioxus).

require_resource_or_permission

Authorize on either axis: a sufficient per-resource role, or a global permission token. The one place the two authorization stories compose.

revoke_membership

Remove user_id’s membership of resource, refusing if they are the sole ResourceRole::Owner (MembershipError::LastOwner).

transfer_ownership

Transfer ownership of resource from from_id to to_id: the new owner is promoted to ResourceRole::Owner and the previous owner demoted to ResourceRole::Manager, atomically. from_id must currently be an Owner (MembershipError::NotOwner otherwise).

Type Aliases

SharedResourceAuthority

Cheaply-cloneable shared handle to the app’s ResourceAuthority. Apps register this as an axum::Extension (directly, or via arium’s AuthConfigBuilder::resource_authority); server fns reach it through the arium::extract::ResourceAuthorityExt extractor.