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 by default) 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. Since 0.4 an emailed link or code stands in for the password only: the second factor is always asked for.

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.

Configuration

latchkey provides the mechanisms; your app chooses the numbers. Every one of them is a Config::builder(owner_email, origin) setting with a default, and build() refuses values outside the bounds below (Error::Config with a ConfigReason naming the setting). Read them back from the built Config (config.link_ttl(), config.totp_params(), ...) and pass them to the primitives that take them; the flows read them themselves.

use latchkey::Config;
use time::Duration;

let config = Config::builder("owner@example.com", "https://home.example.com")
    .link_ttl(Duration::minutes(2))
    .email_code_digits(8)
    .email_code_attempts(3)
    .recovery_code_count(16)
    .build()?;
assert_eq!(config.email_code_digits(), 8);
assert!(Config::builder("owner@example.com", "https://home.example.com")
    .email_code_attempts(0)
    .build()
    .is_err());
# Ok::<(), latchkey::Error>(())

TOTP digits and step are part of every enrolment. Authenticator apps store them with the secret, and latchkey stores nothing per enrolment: an account enrolled under one setting keeps working only while the setting stays the same. Change totp_digits or totp_step and every account must enrol TOTP again (for the step, also clear its stored last-used step, which counts steps of the old length). totp::enrolment puts digits and period in the otpauth:// URL, and so in its QR code, whenever they differ from 6 and 30; if you show only the base32 secret, tell users the values. totp_skew can change at any time.

The other settings change only what happens next: new passwords, new codes, new mails, new sessions. Pending email codes of another length stop matching, recovery-code sets keep their size until regenerated, and stored passwords keep verifying.

Constants that stay are formats and security floors, not preferences: token::TOKEN_BYTES (256-bit tokens, how latchkey recognises its own), token::FOREIGN_MIN_LEN/FOREIGN_MAX_LEN (the shape of imported tokens: at least 128 bits), totp::SECRET_BYTES (160-bit secrets, RFC 4226's recommendation) and MIN_SECRET_BYTES (128 bits, its floor), http::CSRF_HEADER (a wire name) and http::MAX_USER_AGENT (what truncate_user_agent keeps; Client::user_agent is yours to shorten differently), plus the recovery-code format and the hash and seal layouts that stored values depend on. The DEFAULT_* constants (email_link::DEFAULT_CODE_DIGITS, totp::DEFAULT_STEP_SECS, ...) are the settings' defaults.

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|RedeemCode-> SecondFactor, then sign_in's SecondFactor
setup:      Start -RequestLink-> LinkRequested    Start -Redeem-> InSetup -PasswordSet-> InSetup -Finish-> Complete
invite:     Start -Send-> Sent
reset:      Start -Reset-> Done                   then setup: Start -Redeem { kind: Invite }-> ...
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, with per-session step-up failures RecordStepUpFailure and ClearStepUpFailures, for email codes StoreEmailCode, ConsumeEmailCode, DeleteEmailCode and DeleteEmailSignIn, and for a sign-in reset RevokeSessions, RemoveFactors, DeactivateAccount and DeletePendingLinks. 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, 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();
        // As long as the ceremony: config.passkey_ceremony_ttl(), via RelyingParty::new.
        let cookie = SetCookie::new(name, &started.binding_token, rp.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.

Email sign-in: a link and a code

EmailLinkEvent::Request mails one message with a single-use link and a code of config.email_code_digits() digits (6 by default), both valid for config.link_ttl() (5 minutes by default). The link works on any device; the code only on the device that asked, which gets a binding cookie (config.email_cookie_name()) whether or not the address exists. Redeeming either one deletes both, and neither signs in on its own: they replace the password, and the flow continues to the second factor exactly as after a password (EmailLink::SecondFactor, then SignIn::second_factor(session, account) with SignInEvent::Code or Passkey).

A 6-digit code is only safe because it is bound to one pending request (its hash is keyed with the binding cookie, which is never stored), allows few guesses (config.email_code_attempts(), 5 by default, each counted before it is checked, and also towards the account lockout), lives minutes (link_ttl), and still needs the second factor. Keep all four; the settings let you make the code longer and the budget smaller.

use latchkey::flow::email_link::{EmailCodeRequest, EmailLink, EmailLinkEvent};
use latchkey::flow::{Client, Effect, Refusal};
use latchkey::token::SecretToken;
use latchkey::{Account, Config, CryptoRng};
use time::OffsetDateTime;

/// POST /sign-in/email {email}: carry out the effects and answer 202 either way. They set
/// the binding cookie and, for an active account outside the resend cooldown, store the link
/// (`StoreLinkToken`) and the code (`StoreEmailCode`, under the cookie's hash) and mail both.
fn request(
    config: &Config,
    account: Option<Account>,
    last_sent_at: Option<OffsetDateTime>,
    cookie: Option<&str>, // config.email_cookie_name()
    client: Client,
    now: OffsetDateTime,
    rng: &mut impl CryptoRng,
) -> Result<Vec<Effect>, Refusal> {
    let binding = cookie.map(SecretToken::from_presented);
    let event = EmailLinkEvent::Request { account, last_sent_at, binding, client };
    Ok(EmailLink::Start.advance(config, event, now, rng)?.effects)
}

/// POST /sign-in/email/code {code}, with the binding cookie. `counted` is the row the app
/// read with the attempt already counted, in one statement:
/// `UPDATE email_codes SET attempts = attempts + 1 WHERE binding_hash = ? RETURNING ...`.
/// On success, `ConsumeEmailCode` deletes the request and its link (both must still exist)
/// and the client gets a second-factor session.
fn redeem_code(
    config: &Config,
    cookie: Option<&str>,
    code: String,
    counted: Option<EmailCodeRequest>,
    account: Option<Account>,
    client: Client,
    now: OffsetDateTime,
    rng: &mut impl CryptoRng,
) -> Result<(EmailLink, Vec<Effect>), Refusal> {
    let binding = cookie.map(SecretToken::from_presented);
    let event = EmailLinkEvent::RedeemCode { binding, code, request: counted, account, client };
    let step = EmailLink::Start.advance(config, event, now, rng)?;
    Ok((step.state, step.effects)) // EmailLink::SecondFactor: ask for TOTP or a passkey next
}

# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let config = Config::builder("owner@example.com", "https://home.example.com").build()?;
# let mut rng = latchkey::os_rng()?;
# let now = OffsetDateTime::from_unix_timestamp(1_800_000_000)?;
let effects = request(&config, None, None, None, Client::default(), now, &mut rng)?;
assert!(matches!(effects.as_slice(), [Effect::SetCookie(_)]), "unknown address: cookie only");
let refused = redeem_code(&config, None, "123456".into(), None, None, Client::default(), now, &mut rng);
assert_eq!(refused.err().map(|refusal| refusal.error), Some(latchkey::Error::SignInFailed));
# Ok(())
# }

For the link, delete it by TokenHash::of(token) (DELETE ... RETURNING) and send EmailLinkEvent::Redeem { token_hash, link, account, client }; its DeleteEmailCode kills the code. examples/email_link.rs runs the whole path, second factor included.

Resetting a member who lost their second factor

flow::reset gives the owner a "Reset sign-in" button: from the owner's recent session, Reset::Start with ResetEvent::Reset { admin, session, member, remove_password, client } revokes the member's sessions (RevokeSessions), removes their TOTP, passkeys and recovery codes and optionally their password (RemoveFactors), deactivates the account and clears its failures, deletes their older links and codes (DeletePendingLinks), and mails a one-time setup link valid for config.invite_ttl() (24 hours) as MailKind::SignInReset, with an AuditKind::SignInReset event (detail by:<owner id>). The link is an invite link: the member finishes it through Setup with Redeem { kind: LinkKind::Invite }, enrolling a new second factor (and a password if theirs was removed) before Finish.

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

0.4 changes email sign-in: a link no longer signs in on its own, the same mail carries a code, and links and invites live shorter. Apps on 0.3.0 change these lines:

Stored data is unchanged; rows written by 0.3.0 keep working.

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: email links (and the new codes) no longer sign in on their own but lead to the second factor, and live 5 minutes instead of 15 (owner setup links 1 hour); 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, email-code bindings, 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, email codes and passkey ceremonies are single use; an emailed link or code replaces only the password, never the second factor. An email code has 6 to 10 digits (6 by default), so it is bound to the requesting device's cookie (its hash is keyed with it), allows 1 to 20 counted guesses (5 by default; they also count towards the lockout), and lives link_ttl (5 minutes by default); using the link or the code deletes both; 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 passkey_ceremony_ttl (5 minutes by default); counter regressions are rejected by webauthn-rs.
• Every stage change issues a new session token (StoreSession { replaces }).
• The wrong-password throttle (by default 10 per 15 minutes per address) counts unknown addresses too and is checked before hashing; the lockout (by default 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, EmailCode, TotpSecret, RecoveryCode, PasswordHash, SetCookie, DataKey, IpTagKey, Mail links and codes) 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, email codes) 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.