latchkey

Sign-in building blocks and sign-in policy for Rust, without I/O.

latchkey hashes passwords, checks TOTP and recovery codes, runs passkey ceremonies, issues tokens, seals secrets, builds cookies, and decides what a sign-in flow does next. It does not talk to a database, send mail, serve HTTP, read the clock or draw randomness behind your back. Every function takes values (including now and an explicit CryptoRng) and returns values; your app stores what it is told to store, sends what it is told to send and answers its clients.

It was extracted from an axum sign-in service (latchkey 0.2) and keeps its behaviour and stored formats: Argon2id (64 MiB, t=3, p=2), TOTP (SHA-1, 6 digits, 30 s, ±1 step) with a replay guard, single-use recovery codes, passkeys with user verification, __Host- cookies, Origin and CSRF checks, a doubling lockout, a wrong-password throttle, new-device mail and an audit trail, now as pure functions and state machines.

What is in it

Features

Without passkeys, nothing links OpenSSL. The flows still accept a passkey result (verified: bool) from any WebAuthn library you prefer.

Public dependencies

These crates' types appear in latchkey's API, so a breaking release of one of them means a breaking release of latchkey:

Everything else (url, rand, argon2, totp-rs, aes-gcm and the rest) stays private: URLs are &str, os_rng() returns impl CryptoRng.

How the flows work

Each flow is an enum of states. advance consumes the state, takes one event carrying the facts your app loaded (the account, its factor material, the presented device cookie, a verification result) and now, and returns either

• Ok(Transition { state, effects }): the next state and what to do, or
• Err(Refusal { error, effects }): the error to answer with and what must still be done (count the failure, lock the account, write the audit event).

sign_in:    Start -Password-> VerifyPassword -PasswordChecked-> SecondFactor -Code|Passkey-> SignedIn
            Start -PasskeyOnly-> SignedIn
email_link: Start -Request-> Requested            Start -Redeem-> SignedIn
setup:      Start -RequestLink-> LinkRequested    Start -Redeem-> InSetup -PasswordSet-> InSetup -Finish-> Complete
invite:     Start -Send-> Sent
step_up:    Start -Password-> VerifyPassword -PasswordChecked-> Done      Start -Passkey-> Done

Password steps are split in two so the throttle and lockout are decided before the expensive hash, and an unknown address still costs a full (dummy) hash.

Effects are values: StoreSession { session, replaces }, DeleteSession, SetCookie, RecordFailure, ClearFailures, RecordWrongPassword, UseTotpStep, UseRecoveryCode, StoreRecoveryCodes, StoreLinkToken, SendMail, Audit, RememberDevice, CreateAccount, StorePassword, ActivateAccount, MarkStepUp, and with per-session step-up failures RecordStepUpFailure and ClearStepUpFailures. Carry out every one, in order: storage effects ideally in one transaction, then mail. UseTotpStep and UseRecoveryCode are compare-and-set: if the stored step is already as new, or the code already used, the request lost a race and must be refused. RecordFailure must be one atomic statement that increments the stored count (UPDATE users SET failures = failures + 1 WHERE id = ? RETURNING failures), never a value computed from the Account snapshot, so failures that race are all counted; then store config.lockout().locked_until(n, at) and append config.lockout().lockout_event(user, n, at, ip_tag) when they are Some. ClearFailures resets the count and the lock.

Where wrong step-up guesses count

By default (StepUpFailures::AccountLockout) a wrong password or code at step-up counts like a sign-in failure: towards the account lockout and the wrong-password throttle, and a locked account cannot step up. That lets anyone holding a stolen session cookie lock the real owner out, and lets anonymous sign-in guesses stop a signed-in owner from re-verifying. To count them per session instead:

use latchkey::{Config, Error, StepUpFailures};

fn config() -> Result<Config, Error> {
    Config::builder("owner@example.com", "https://home.example.com")
        .step_up_failures(StepUpFailures::PerSession { limit: 5 })
        .build()
}
assert!(config().is_ok());

Then step-up neither consults nor feeds the lockout and throttle. Each wrong guess emits RecordStepUpFailure { token_hash }: increment sessions.step_up_failures atomically in the same transaction (UPDATE sessions SET step_up_failures = step_up_failures + 1 WHERE token_hash = ? RETURNING step_up_failures). Load that column into Session::step_up_failures when you rebuild the session. The guess that reaches limit also emits DeleteSession, a cookie removal and a session_revoked audit event (detail step_up_failures), and the refusal is Error::SessionEnded (session_ended, 401): sign in again. A session whose stored count already reached the limit (guesses that raced) is refused and ended the same way on its next step-up; to end it at once, check config.step_up_failures().ends_session(n) on the count the increment returned. A successful step-up emits ClearStepUpFailures and still ClearFailures, so a full proof lifts an account lock. A passkey that fails to verify is not counted in either mode.

Accounts with only a password

latchkey asks for a second factor after every password, and setup does not finish without one. Accounts imported from another system with only a password, or apps that let users enrol TOTP or a passkey later, can opt in:

use latchkey::{Config, Error, PasswordOnly};

fn config() -> Result<Config, Error> {
    Config::builder("owner@example.com", "https://home.example.com")
        .password_only(PasswordOnly::AllowedUntilEnrolled)
        .build()
}
assert!(config().is_ok());

Then an account with a password and no second factor signs in with the password alone (SignIn::VerifyPassword goes straight to SignedIn, method password_only), steps up with it, finishes setup and gets issue_session. As soon as the account has TOTP or a passkey, that factor is required again; Factors::password_suffices(config.password_only()) says which case applies.

Passkey sign-in before a session exists

Registration, a passkey second factor and step-up run inside a session, and their ceremonies are bound to it (Binding::Session, finished with into_state(session.id, user, now)). A passkey sign-in has no session yet: RelyingParty::start_sign_in(user, passkeys, now, rng) (the user typed their address; the challenge lists their passkeys) and start_discoverable(now, rng) return a SignInStarted whose binding_token is a one-off token for the browser's cookie. The ceremony keeps only its hash (Binding::Browser).

#[cfg(feature = "passkeys")]
mod passkey_sign_in {
    use latchkey::http::{SetCookie, find_cookie};
    use latchkey::passkey::webauthn_rs::prelude::{
        AuthenticationResult, Passkey, PasskeyAuthentication, PublicKeyCredential,
    };
    use latchkey::passkey::{CEREMONY_TTL, Ceremony, RelyingParty, SignInStarted};
    use latchkey::{Config, CryptoRng, Error, UserId};
    use time::OffsetDateTime;

    /// POST /sign-in/passkey/start {email}: store `started.ceremony` under its id, answer
    /// with `started.challenge` and that id, and send the cookie.
    pub fn start(
        config: &Config,
        rp: &RelyingParty,
        user: UserId,
        passkeys: &[Passkey],
        now: OffsetDateTime,
        rng: &mut impl CryptoRng,
    ) -> Result<(SignInStarted<PasskeyAuthentication>, SetCookie), Error> {
        let started = rp.start_sign_in(user, passkeys, now, rng)?;
        let name = config.ceremony_cookie_name().clone();
        let cookie = SetCookie::new(name, &started.binding_token, CEREMONY_TTL);
        Ok((started, cookie))
    }

    /// POST /sign-in/passkey/finish {ceremony_id, credential}: `ceremony` is the one the app
    /// removed from storage by the posted id. Then `passkey::record_use` on the passkeys of
    /// the returned user, and `SignInEvent::PasskeyOnly { account, verified, client }`.
    pub fn finish(
        config: &Config,
        rp: &RelyingParty,
        ceremony: Ceremony<PasskeyAuthentication>,
        cookie_headers: &[&str],
        credential: &PublicKeyCredential,
        now: OffsetDateTime,
    ) -> Result<(UserId, AuthenticationResult), Error> {
        let user = ceremony.binding().user().ok_or(Error::SignInFailed)?;
        let name = config.ceremony_cookie_name().as_str();
        let binding = find_cookie(cookie_headers.iter().copied(), name).unwrap_or_default();
        let state = ceremony.into_browser_state(binding, now)?;
        Ok((user, rp.finish_authentication(credential, &state)?))
    }
}

Only the browser holding the cookie can finish the ceremony it started.

Plain-HTTP development on localhost

Cookies are __Host- and Secure. Chrome and Firefox keep such cookies on http://localhost, Safari does not. For local development over plain HTTP:

use latchkey::{Config, Error};

fn development_config() -> Result<Config, Error> {
    Config::builder("owner@example.com", "http://localhost:3000")
        .danger_insecure_localhost_cookies()
        .build()
}
let config = development_config();
assert_eq!(config.map(|c| c.cookie_name().to_string()), Ok("latchkey".into())); // no __Host-

build refuses this for any origin other than http://localhost, http://127.0.0.1 or http://[::1], and a production origin must be https, so it cannot reach production by accident. Read cookies by config.cookie_name().as_str(), not a hard-coded name.

Example: password + TOTP with your own storage

A condensed version of examples/password_totp.rs (cargo run --example password_totp). Storage is a HashMap here; use whatever you like.

use std::collections::HashMap;

use latchkey::account::{AccountKey, Lockout};
use latchkey::flow::sign_in::{SignIn, SignInEvent};
use latchkey::flow::{Client, CodeMaterial, Effect, TotpMaterial};
use latchkey::limits::WrongPasswordThrottle;
use latchkey::password::{PasswordHash, PasswordHasher};
use latchkey::recovery::RecoveryCodeHash;
use latchkey::seal::DataKey;
use latchkey::session::Session;
use latchkey::token::TokenHash;
use latchkey::totp::TotpStep;
use latchkey::{Account, Config, CryptoRng, Email, Error, UserId};
use time::OffsetDateTime;

/// An account as the app stores it: a database row in a real app.
struct Row {
    account: Account,
    password: PasswordHash,
    sealed_totp: Vec<u8>,
    last_step: Option<TotpStep>,
    recovery: Vec<(RecoveryCodeHash, bool)>,
}

/// Built once at start-up.
struct App {
    config: Config,                  // Config::builder(owner, origin).build()?
    hasher: PasswordHasher,          // PasswordHasher::new(config.password_params(), &mut rng)?
    data_key: DataKey,               // DataKey::new(&keys.data), kept out of the database
    throttle: WrongPasswordThrottle, // WrongPasswordThrottle::new(config.rate_limits())
    users: HashMap<UserId, Row>,
    sessions: HashMap<TokenHash, Session>,
}

impl App {
    /// POST /sign-in {email, password}
    fn sign_in(
        &mut self,
        email: &str,
        password: &str,
        client: Client,
        now: OffsetDateTime,
        rng: &mut impl CryptoRng,
    ) -> Result<(), Error> {
        let address = Email::parse(email).ok();
        let row = self.users.values().find(|row| Some(&row.account.email) == address.as_ref());
        let event = SignInEvent::Password {
            login: email.to_owned(),
            account: row.map(|row| row.account.clone()),
            wrong_passwords: self.throttle.window(&AccountKey::from_login(email)),
        };
        // Throttled or locked: refused before any hashing.
        let step = SignIn::Start
            .advance(&self.config, event, now, rng)
            .map_err(|refusal| refusal.error)?;
        // On a blocking thread in a server. An unknown address (None) still costs a hash.
        let matched = self.hasher.verify(password, row.map(|row| &row.password));
        let event = SignInEvent::PasswordChecked { matched, client };
        match step.state.advance(&self.config, event, now, rng) {
            Ok(step) => self.apply(step.effects, now), // reply with the new session's CSRF token
            Err(refusal) => {
                self.apply(refusal.effects, now)?;
                Err(refusal.error)
            }
        }
    }

    /// POST /sign-in/code {code}, with the second-factor session's cookie
    fn code(
        &mut self,
        cookie: &str,
        code: String,
        client: Client,
        now: OffsetDateTime,
        rng: &mut impl CryptoRng,
    ) -> Result<(), Error> {
        let hash = TokenHash::of(cookie).ok_or(Error::Unauthorized)?;
        let session = self.sessions.get(&hash).cloned().ok_or(Error::Unauthorized)?;
        let row = self.users.get(&session.user_id).ok_or(Error::Unauthorized)?;
        let totp = TotpMaterial::new(
            self.data_key.open_totp(row.account.id, &row.sealed_totp)?,
            row.last_step,
        );
        let unused = row.recovery.iter().filter(|(_, used)| !used).map(|(h, _)| *h).collect();
        let material = CodeMaterial::new(Some(totp), unused);
        let event = SignInEvent::Code { code, material, client };
        match SignIn::second_factor(session, row.account.clone()).advance(&self.config, event, now, rng) {
            Ok(step) => self.apply(step.effects, now), // a full session replaces the pending one
            Err(refusal) => {
                self.apply(refusal.effects, now)?;
                Err(refusal.error)
            }
        }
    }

    /// Carries out every effect, in order: storage in one transaction, then mail.
    fn apply(&mut self, effects: Vec<Effect>, now: OffsetDateTime) -> Result<(), Error> {
        for effect in effects {
            match effect {
                Effect::StoreSession { session, replaces } => {
                    if let Some(old) = replaces {
                        self.sessions.remove(&old);
                    }
                    self.sessions.insert(session.token_hash, session);
                }
                Effect::SetCookie(cookie) => {
                    let _header = cookie.header_value(); // add to the response
                }
                Effect::RecordFailure { user_id, at, ip_tag } => {
                    // In SQL, one statement:
                    // UPDATE users SET failures = failures + 1 WHERE id = ? RETURNING failures
                    let row = self.users.get_mut(&user_id).ok_or(Error::NotFound)?;
                    let n = row.account.lockout.failures.saturating_add(1);
                    row.account.lockout.failures = n;
                    if let Some(until) = self.config.lockout().locked_until(n, at) {
                        row.account.lockout.locked_until = Some(until);
                    }
                    let _lock = self.config.lockout().lockout_event(user_id, n, at, ip_tag); // append if Some
                }
                Effect::ClearFailures { user_id } => {
                    let row = self.users.get_mut(&user_id).ok_or(Error::NotFound)?;
                    row.account.lockout = Lockout::default();
                }
                Effect::RecordWrongPassword { key } => self.throttle.record(&key, now),
                Effect::UseTotpStep { user_id, step } => {
                    // Compare-and-set: UPDATE ... SET last_step = ?
                    //   WHERE user_id = ? AND (last_step IS NULL OR last_step < ?)
                    let row = self.users.get_mut(&user_id).ok_or(Error::SignInFailed)?;
                    if row.last_step.is_some_and(|last| last >= step) {
                        return Err(Error::SignInFailed); // the code raced another request
                    }
                    row.last_step = Some(step);
                }
                Effect::UseRecoveryCode { user_id, hash } => {
                    let row = self.users.get_mut(&user_id).ok_or(Error::SignInFailed)?;
                    let code = row.recovery.iter_mut().find(|(h, used)| *h == hash && !used);
                    code.ok_or(Error::SignInFailed)?.1 = true;
                }
                Effect::SendMail(_mail) => { /* after commit: mail.to, mail.subject(), mail.text() */ }
                Effect::Audit(_event) => { /* append */ }
                // RememberDevice, RecordStepUpFailure and the effects of the other flows: see
                // the documentation of `Effect`.
                _ => {}
            }
        }
        Ok(())
    }
}

examples/email_link.rs and examples/passkey_registration.rs (feature passkeys) show the other two common paths.

Migrating from 0.3.0-dev

Apps on latchkey 0.3.0-dev (from crates.io or git, such as Home and the portfolio) change these lines; the compiler finds each one.

Stored data is unchanged except passkey ceremonies, which no longer deserialize across the upgrade; they live 5 minutes, so drop pending ones when you deploy.

Porting from 0.2

latchkey 0.2 was a service: an axum router, extractors, a SQLite store, a mailer and in-memory limiters. 0.3 keeps the decisions and leaves the I/O to the app.

Endpoints to flow calls:

Behavioural changes: step_up joins the reserved method names for app-issued sessions; RelyingParty::finish_discoverable takes the claimed user and refuses an assertion whose user handle differs; the device cookie is still set on every completed sign-in.

Security notes

• Passwords: Argon2id; an unknown account verifies against a dummy hash and fails the same way as a wrong password. Passwords over 4096 bytes are not hashed as given.
• Tokens (sessions, links, devices, CSRF) are 32 random bytes; only SHA-256 hashes are stored, except the session's CSRF token, which the client needs again. Comparisons of presented secrets are constant-time.
• A TOTP step is accepted once (last_used_step); recovery codes, links and passkey ceremonies are single use; passkey ceremonies are bound to the session and account that started them (a sign-in, which has no session yet, to the browser by a one-off cookie) and expire after 5 minutes; counter regressions are rejected by webauthn-rs.
• Every stage change issues a new session token (StoreSession { replaces }).
• The wrong-password throttle (10 per 15 minutes per address) counts unknown addresses too and is checked before hashing; the lockout (5 failures: 5 minutes, doubling to an hour) is per account. Step-up guesses count towards both unless Config::step_up_failures is PerSession { limit }, which bounds each session to limit wrong guesses and then ends it.
• Sealed values use a random 96-bit nonce and associated data latchkey-totp:<user> or latchkey-passkey:<user>:<passkey>; Aad::app(context) is for the app's own secrets.
• Secret types (SecretToken, TotpSecret, RecoveryCode, PasswordHash, SetCookie, DataKey, IpTagKey, Mail links) redact Debug, have no Display, and zero their memory on drop where they own it.
• No unsafe; unwrap, expect, panic! and indexing are denied outside tests.
• Randomness comes from the CryptoRng you pass, except webauthn-rs challenges, which it draws from OpenSSL.

Known trade-offs carried over from 0.2: a locked account answers too_many_attempts, which tells someone who already made 5 wrong guesses that the address exists; the new-device check is per browser profile; anyone with both the database and the data key can read factors.

Testing

cargo test --all-features runs unit tests, property tests (proptest: token and cookie parsing, the limiter against a fixed-window model, the throttle against a sliding-window model, the lockout, TOTP replay, sealing) and integration tests that drive every flow through an in-memory app (tests/common), including a software passkey.

fuzz/ has a cargo-fuzz target, untrusted_inputs, that feeds arbitrary bytes to every parser of client input. It builds on stable (cargo build --manifest-path fuzz/Cargo.toml); running it needs nightly: cargo +nightly fuzz run untrusted_inputs.

The minimum supported Rust version is 1.88.

For coding agents

The crate ships Symposium skills in skills/: latchkey-basics (how to use it correctly) and latchkey-porting (moving from 0.2). With the cargo agents CLI, cargo agents use latchkey in a project that depends on latchkey installs them.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.