Expand description
§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.
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.