ch-auth 0.1.2

Authentication and session primitives with explicit security policies
Documentation

ch-auth

ch-auth provides authentication and session building blocks with explicit security policies and application-owned account models.

More information is available in the API documentation.

High-level features

  • Signed sessions with validated cookie policies
  • Argon2id password and recovery-code hashing
  • Password login, registration, CAPTCHA, and two-factor workflows
  • Bounded request rate limiting
  • Typed account authorization without a built-in role hierarchy
  • Stable outcome codes for transport and presentation layers

The crate does not define account identifiers, roles, lifecycle states, database schemas, or UI preferences.

Account security

RandomCodeSpec controls the length and alphabet used for generated display codes. Bootstrap accounts read BOOTSTRAP_EMAIL, BOOTSTRAP_FULL_NAME, and BOOTSTRAP_PASSWORD; either all three values must be present or none of them. Secrets are redacted from diagnostics and zeroized where ownership permits it.

use ch_auth::accounts::{RandomCodeSpec, generate_random_code};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let format = RandomCodeSpec::new(12, "ABCDEFGHJKLMNPQRSTUVWXYZ23456789")?;
    let code = generate_random_code(format)?;

    assert_eq!(code.len(), 12);
    Ok(())
}

Sessions

SessionKey reads SESSION_KEY or SESSION_KEY_FILE. Release builds require a stable key. Debug builds may generate a process-local key, which deliberately invalidates development sessions after a restart.

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

fn build() -> 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 authorization::AccountAuthorizer for the session account and use the application's role or permission type as its Role. Custom session types can implement authorization::AccountSession. The companion ch-auth-macros crate provides #[auth(...)] without defining product roles.

Request handling

SecurityState derives client identities from the TCP peer address and applies the configured authentication budgets. CAPTCHA answers are stored as expiring HMAC tags. Login identifiers, CAPTCHA answers, and second-factor tokens are length-limited before expensive validation. Successful authentication renews the session identifier before storing authenticated state.

Minimum supported Rust version

ch-auth requires Rust 1.96 or newer.

License

Licensed under the Sustainable Use License 1.0. See LICENSE.md.