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 ;
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 SameSite;
use ;
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.