ch-auth 0.3.2

Authentication and session primitives with explicit security policies
Documentation
# 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).