Struct AllowThem 

pub struct AllowThem { /* private fields */ }

Configured allowthem handle.

Bundles a Db, SessionConfig, and cookie domain into a single value that is cheaply cloneable and safe to share across Axum handlers via State<AllowThem> or Extension<AllowThem>.

Implementations

impl AllowThem

pub fn db(&self) -> &Db

Access the underlying database handle.

Escape hatch for callers who need direct Db access for operations not yet wrapped by AllowThem methods (e.g., user CRUD, role management).

pub fn session_config(&self) -> &SessionConfig

Access the session configuration.

pub fn session_cookie(&self, token: &SessionToken) -> String

Build a Set-Cookie header value for the given session token.

Uses the stored SessionConfig and cookie domain. Delegates to sessions::session_cookie().

pub fn base_url(&self) -> Result<&str, AuthError>

Returns the base URL (issuer), or Err(BaseUrlNotConfigured) if not set.

pub fn csrf_key(&self) -> Result<&[u8; 32], AuthError>

pub fn on_user_active(&self) -> Option<&OnUserActive>

Return a reference to the on_user_active callback, if configured.

Used to pass the callback into free functions (e.g. exchange_authorization_code) that do not receive the full AllowThem handle.

pub fn email_sender(&self) -> &dyn EmailSender

Borrow the configured email sender.

Defaults to NoopEmailSender unless overridden via AllowThemBuilder::email_sender.

pub fn event_sink(&self) -> &dyn EventSink

Borrow the configured event sink.

Defaults to NoopEventSink unless overridden via AllowThemBuilder::event_sink.

pub async fn emit_event(&self, event: AuthEvent)

Emit an event to the configured sink.

Awaits the sink’s emit future. Returns when the sink finishes (typically a single local DB write or a noop). The sink contract forbids panics and errors; this method is unconditionally infallible.

pub async fn send_password_reset_email( &self, email: &Email, ) -> Result<(), AuthError>

Send a password reset email to the given address.

Creates a reset token, composes the reset URL from base_url, and sends a PasswordReset template. Returns Ok(()) silently if no user exists for that email (enumeration prevention). Requires base_url to be configured; returns Err(BaseUrlNotConfigured) otherwise.

pub async fn send_verification_email( &self, user_id: UserId, email: &Email, ) -> Result<(), AuthError>

Send an email verification link to the given user.

Creates a verification token, composes the verification URL from base_url, and sends an EmailVerification template. Requires base_url to be configured.

pub async fn send_invitation_email( &self, email: &Email, invitation_url: &str, invited_by: UserId, expires_at: DateTime<Utc>, ) -> Result<(), AuthError>

Send an invitation email to the given address.

Creates an invitation token in the database and sends an Invitation template. invitation_url must be pre-composed by the caller — the URL format varies by deployment (the saas binary uses https://{base_domain}/invite/{token}; standalone server may differ). invited_by is the UserId of the inviter; their display name is resolved from the database and used in the template. On lookup failure, falls back to "your team".

pub async fn send_mfa_recovery_email( &self, user_id: UserId, codes: Vec<String>, ) -> Result<(), AuthError>

Send MFA recovery codes to the given user via email.

Looks up the user by user_id to determine recipient address and username. Sends an MfaRecovery template with the supplied codes. Does not write to the database — code generation and persistence are the caller’s responsibility (see Db::enable_mfa).

pub fn notify_user_active(&self, user_id: UserId)

Fire the on_user_active callback, if configured.

Call this immediately after a session row or access token is durably written, for active auth events only. Panics from the callback are caught and logged; they never propagate to the caller.

pub async fn get_decrypted_signing_key( &self, ) -> Result<(SigningKey, String), AuthError>

Fetch the active signing key and decrypt its private key PEM.

Combines the encryption key, active key lookup, and decryption into a single call. Keeps the raw encryption key private to the core crate.

pub fn clear_session_cookie(&self) -> String

Build a Set-Cookie header value that expires the session cookie.

Returns Max-Age=0 with the same cookie name, path, domain, and flags used by session_cookie(). Pass this as the Set-Cookie header on a logout response to clear the browser’s stored session cookie.

pub fn parse_session_cookie(&self, cookie_header: &str) -> Option<SessionToken>

Extract the session token from a Cookie header value.

Uses the stored cookie name. Delegates to sessions::parse_session_cookie().

pub async fn login( &self, identifier: &str, password: &str, ) -> Result<LoginOutcome, AuthError>

Authenticate with credentials and create a session.

Returns Err(AuthError::InvalidCredentials) for any credential failure — unknown identifier, wrong password, no local password hash (SSO-only account), or inactive user — to prevent account enumeration.

Records an AuditEvent::Login on success. IP and user-agent are not available at this layer; callers who need them in the audit log should use the low-level Db methods directly.

pub async fn create_session_cookie( &self, user_id: UserId, ) -> Result<LoginOutcome, AuthError>

Create a session for an already-authenticated user.

Does not verify credentials. Intended for use after OAuth, TOTP, or other non-password authentication flows. The calling flow is responsible for audit logging.

impl AllowThem

pub async fn consume_password_reset( &self, raw_token: &str, new_password: &str, ) -> Result<bool, AuthError>

Validate and consume a password-reset token, setting a new password.

Emits password.reset on success. Returns Ok(true) if the token was valid and the password was updated, Ok(false) if the token was invalid or already used.

impl AllowThem

pub async fn assign_permission_to_user( &self, user_id: &UserId, permission_id: &PermissionId, ) -> Result<(), AuthError>

pub async fn unassign_permission_from_user( &self, user_id: &UserId, permission_id: &PermissionId, ) -> Result<(), AuthError>

impl AllowThem

pub async fn assign_role( &self, user_id: &UserId, role_id: &RoleId, ) -> Result<(), AuthError>

pub async fn unassign_role( &self, user_id: &UserId, role_id: &RoleId, ) -> Result<(), AuthError>

impl AllowThem

pub async fn delete_session( &self, token: &SessionToken, ) -> Result<bool, AuthError>

Delete a session by token and emit session.destroyed (scope=single).

Returns Ok(true) if a session was found and deleted, Ok(false) if not. The event is only emitted on Ok(true).

pub async fn delete_session_by_id( &self, id: SessionId, ) -> Result<bool, AuthError>

Delete a session by ID and emit session.destroyed (scope=single).

Returns Ok(true) if a session was found and deleted, Ok(false) if not. The event is only emitted on Ok(true).

pub async fn delete_user_sessions( &self, user_id: &UserId, ) -> Result<u64, AuthError>

Delete all sessions for a user and emit one session.destroyed event.

The event carries { user_id, count, scope: "all" }. Returns the count.

impl AllowThem

pub async fn create_social_provider( &self, provider_type: ProviderType, display_name: &str, client_id: &str, client_secret: &str, scopes: &[String], config: Option<&Value>, priority: i64, ) -> Result<SocialProviderId, AuthError>

Create a social provider. Reads mfa_key from the builder config.

pub async fn list_social_providers( &self, ) -> Result<Vec<SocialProviderRow>, AuthError>

List all social providers.

pub async fn list_enabled_social_providers( &self, ) -> Result<Vec<SocialProviderRow>, AuthError>

List only enabled social providers.

pub async fn get_social_provider( &self, id: SocialProviderId, ) -> Result<SocialProviderRow, AuthError>

Get a provider row by ID.

pub async fn get_social_provider_decrypted( &self, id: SocialProviderId, ) -> Result<SocialProviderConfig, AuthError>

Fetch a provider row and decrypt its secret in one call.

Used by the OAuth callback path (7m5.2) when building a Box<dyn SocialProvider> for an inbound request.

pub async fn update_social_provider( &self, id: SocialProviderId, display_name: Option<&str>, client_id: Option<&str>, client_secret: Option<&str>, scopes: Option<&[String]>, enabled: Option<bool>, priority: Option<i64>, config: Option<Option<&Value>>, ) -> Result<(), AuthError>

Update editable fields. See Db::update_social_provider for semantics.

pub async fn delete_social_provider( &self, id: SocialProviderId, ) -> Result<bool, AuthError>

Delete a provider by ID.

impl AllowThem

pub async fn get_pending_mfa_secret( &self, user_id: UserId, ) -> Result<Option<String>, AuthError>

pub async fn create_mfa_secret( &self, user_id: UserId, ) -> Result<String, AuthError>

pub async fn enable_mfa( &self, user_id: UserId, code: &str, ) -> Result<Vec<String>, AuthError>

pub async fn verify_totp( &self, user_id: UserId, code: &str, ) -> Result<bool, AuthError>

pub async fn has_mfa_enabled(&self, user_id: UserId) -> Result<bool, AuthError>

pub async fn disable_mfa(&self, user_id: UserId) -> Result<(), AuthError>

pub async fn verify_recovery_code( &self, user_id: UserId, code: &str, ) -> Result<bool, AuthError>

pub async fn remaining_recovery_codes( &self, user_id: UserId, ) -> Result<i64, AuthError>

pub async fn regenerate_recovery_codes( &self, user_id: UserId, ) -> Result<Vec<String>, AuthError>

impl AllowThem

pub async fn create_user( &self, email: Email, password: &str, username: Option<Username>, custom_data: Option<&Value>, ) -> Result<User, AuthError>

Create a user and emit a user.created event on success.

pub async fn update_user_email( &self, id: UserId, email: Email, ) -> Result<(), AuthError>

Update a user’s email address and emit a user.updated event on success.

pub async fn update_user_username( &self, id: UserId, username: Option<Username>, ) -> Result<(), AuthError>

Update a user’s username and emit a user.updated event on success.

pub async fn update_user_password( &self, id: UserId, new_password: &str, ) -> Result<(), AuthError>

Update a user’s password and emit a password.changed event on success.

pub async fn delete_user(&self, id: UserId) -> Result<(), AuthError>

Delete a user and emit a user.deleted event on success.

pub async fn update_user_active( &self, id: UserId, is_active: bool, ) -> Result<(), AuthError>

Set a user’s active status and emit user.blocked or user.unblocked.

Trait Implementations

impl Clone for AllowThem

fn clone(&self) -> AllowThem

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.