Skip to main content

Crate ch_auth

Crate ch_auth 

Source
Expand description

§ch-auth

Authentication building blocks for Rust and Axum.

  • Signed sessions and cookie policies
  • Argon2id passwords and recovery codes
  • Login, registration, CAPTCHA and two-factor authentication
  • Request limits and typed account permissions

The application owns its accounts, roles, database and translations. See the API documentation for the full API.

Use ch-parsing 0.2 when handling the parser types returned by this crate.

§Passwords

Use verify_password in request handlers. It runs password checks on blocking workers and limits concurrent checks in each process.

use ch_auth::accounts::verify_password;

async fn check(password: &str, stored_hash: &str) -> Result<bool, Box<dyn std::error::Error>> {
    Ok(verify_password(password, stored_hash).await?)
}

§Sessions

Set SESSION_KEY or SESSION_KEY_FILE to a stable key in production. SessionKey requires 64 bytes encoded as Base64.

use axum_session::SameSite;
use ch_auth::session::{SessionKey, SessionPolicy, build_session_config};

fn sessions() -> Result<axum_session::SessionConfig, Box<dyn std::error::Error>> {
    let key = SessionKey::from_environment()?;
    let policy = SessionPolicy::new("session", SameSite::Lax, true, true, "/")?;
    Ok(build_session_config(policy, key))
}

Implement AccountAuthorizer for your account type to define permissions. The companion ch-auth-macros crate checks them on Axum handlers.

§Two-factor login

verify_totp_step returns the verified 30-second timestep. Verification alone does not prevent a code from being used again.

complete_two_factor_login requires a consume_totp_step callback. The application must atomically store the timestep for the current account and active secret. Reject equal or older steps before creating a session. Keep this state across restarts and share it between instances. Record the first step when enabling an authenticator. Recovery codes must also be single use.

Use SecurityState to check client budgets at the HTTP boundary. Use its account budget for sensitive two-factor actions and pass the same state to complete_two_factor_login. Limits are local to each process. Deployments with multiple processes need a shared account attempt limit as well.

Requires Rust 1.99 or newer. Licensed under the Sustainable Use License 1.0.

Modules§

accounts
Password, recovery-code, and random-code primitives for account systems. Bootstrap credentials, passwords, recovery codes, and random-code primitives.
auth
Authentication workflows, form models, and permission helpers.
authorization
Typed account authorization for session-backed handlers. Typed account authorization for session-backed handlers.
captcha
CAPTCHA issuance and one-time verification policies.
messages
Stable, application-translatable authentication messages.
ratelimit
In-process authentication rate limiting keyed by the TCP peer address.
session
Session signing, cookie policy, and Axum session state adapters.
status
Account authorization decisions and denial reasons.

Macros§

impl_login_traits
Implements login traits for standard account and credential types.