# 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](https://docs.rs/ch-auth) 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.
```rust,no_run
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.
```rust,no_run
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](https://docs.rs/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](LICENSE.md).