diff --git a/astro.config.mjs b/astro.config.mjs index fb2bb93..1da83bb 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -56,6 +56,9 @@ export default defineConfig({ { label: 'Device Flow', slug: 'providers/device-flow' }, { label: 'Passkeys (WebAuthn)', slug: 'providers/passkeys' }, { label: 'TOTP (Authenticator Apps)', slug: 'providers/totp' }, + { label: 'Magic Link', slug: 'providers/magic-link' }, + { label: 'Email/SMS One-Time Codes', slug: 'providers/otp' }, + { label: 'Recovery Codes', slug: 'providers/recovery-codes' }, { label: 'Bot Protection (CAPTCHA)', slug: 'providers/bot-protection' }, { label: 'Device Signatures', slug: 'providers/device-signatures' }, ], diff --git a/src/content/docs/advanced/op-server.md b/src/content/docs/advanced/op-server.md index 9aba7ce..fb0b868 100644 --- a/src/content/docs/advanced/op-server.md +++ b/src/content/docs/advanced/op-server.md @@ -16,9 +16,9 @@ Because OP Servers are an advanced use case, the OP logic is not included in the ```toml [dependencies] authkestra-op = "0.9" -authkestra-axum = { version = "0.9", features = ["op"] } +authkestra-axum = { version = "0.13", features = ["op"] } # Or if using Actix: -# authkestra-actix = { version = "0.9", features = ["op"] } +# authkestra-actix = { version = "0.13", features = ["op"] } ``` ## The OpStore Interface diff --git a/src/content/docs/advanced/policy-engine.md b/src/content/docs/advanced/policy-engine.md index ecbaebe..e6a8542 100644 --- a/src/content/docs/advanced/policy-engine.md +++ b/src/content/docs/advanced/policy-engine.md @@ -19,7 +19,7 @@ review, diff and reload, instead of in `if role == "admin"` branches scattered a ```toml [dependencies] -authkestra = { version = "0.11", features = ["policy"] } +authkestra = { version = "0.13", features = ["policy"] } # or the crate on its own: authkestra-policy = "0.11" ``` diff --git a/src/content/docs/advanced/resource-server.mdx b/src/content/docs/advanced/resource-server.mdx index 8257fc9..5c24dc8 100644 --- a/src/content/docs/advanced/resource-server.mdx +++ b/src/content/docs/advanced/resource-server.mdx @@ -19,9 +19,9 @@ Like the OP Server, the Resource Server is an advanced component and is not incl ```toml [dependencies] authkestra-resource = "0.9" -authkestra-axum = { version = "0.9", features = ["resource"] } +authkestra-axum = { version = "0.13", features = ["resource"] } # Or if using Actix: -# authkestra-actix = { version = "0.9", features = ["resource"] } +# authkestra-actix = { version = "0.13", features = ["resource"] } ``` ### TLS Backend Selection @@ -30,7 +30,7 @@ Outbound HTTP requests for JWKS discovery require a TLS backend. Authkestra enab ```toml [dependencies] -authkestra-resource = { version = "0.9", default-features = false, features = ["rustls-no-provider"] } +authkestra-resource = { version = "0.13", default-features = false, features = ["rustls-no-provider"] } ``` ## Building with Authkestra Guard diff --git a/src/content/docs/concepts/architecture.md b/src/content/docs/concepts/architecture.md index 3442ed2..4d05fcb 100644 --- a/src/content/docs/concepts/architecture.md +++ b/src/content/docs/concepts/architecture.md @@ -28,6 +28,6 @@ Framework-specific wrappers that embed the engine into your web application. 1. **Typestate Builder Pattern**: The `Authkestra::builder()` utilizes Rust's typestate pattern to enforce configuration validity at compile-time. Misconfigurations are compile errors, not runtime panics. 2. **Stateless OAuth by Default**: OAuth `state` and `nonce` parameters are stored in securely encrypted cookies rather than a database. This guarantees horizontal scalability. -3. **Database Agnostic**: Authkestra never enforces schemas. All data access occurs through traits — `KvStore`/`SessionStore` for protocol state, `CredentialStore` for TOTP/WebAuthn secrets, and `authkestra-op`'s `OpStore` for OAuth clients, codes and tokens — allowing you to use SQLx, Diesel, Redis, or purely in-memory solutions. Note there is deliberately **no** user or account trait: your application owns those tables outright. +3. **Database Agnostic**: Authkestra never enforces schemas. All data access occurs through traits — `KvStore`/`SessionStore` for protocol state, `CredentialStore` for TOTP/WebAuthn/recovery-code secrets, and `authkestra-op`'s `OpStore` for OAuth clients, codes and tokens — allowing you to use SQLx, Diesel, Redis, or purely in-memory solutions. Note there is deliberately **no** user or account trait: your application owns those tables outright. 4. **Trait Objects over Generics**: For I/O-bound paths, we prefer dynamic dispatch (`Box`) to optimize compilation times and improve Developer Experience without sacrificing noticeable runtime performance. 5. **Observability**: Every handler and endpoint is deeply instrumented via the `tracing` crate, providing granular visibility into authentication flows in production. diff --git a/src/content/docs/guides/framework-integration.mdx b/src/content/docs/guides/framework-integration.mdx index ed37ca1..9bd31c1 100644 --- a/src/content/docs/guides/framework-integration.mdx +++ b/src/content/docs/guides/framework-integration.mdx @@ -15,7 +15,7 @@ Ensure you have enabled the correct web framework feature on the `authkestra` cr ```toml [dependencies] -authkestra = { version = "0.9", features = ["axum", "session"] } +authkestra = { version = "0.13", features = ["axum", "session"] } ``` @@ -23,7 +23,7 @@ authkestra = { version = "0.9", features = ["axum", "session"] } ```toml [dependencies] -authkestra = { version = "0.9", features = ["actix", "session"] } +authkestra = { version = "0.13", features = ["actix", "session"] } ``` diff --git a/src/content/docs/guides/quickstart.mdx b/src/content/docs/guides/quickstart.mdx index b06bdf3..18a5b32 100644 --- a/src/content/docs/guides/quickstart.mdx +++ b/src/content/docs/guides/quickstart.mdx @@ -16,8 +16,8 @@ Add the `authkestra` facade crate to your `Cargo.toml`. The facade re-exports al ```toml [dependencies] -authkestra = { version = "0.9", features = ["axum", "session", "github"] } -authkestra-engine = { version = "0.9", features = ["session", "memory"] } +authkestra = { version = "0.13", features = ["axum", "session", "github"] } +authkestra-engine = { version = "0.13", features = ["session", "memory"] } tower-cookies = "0.11" tokio = { version = "1", features = ["full"] } ``` @@ -27,8 +27,8 @@ tokio = { version = "1", features = ["full"] } ```toml [dependencies] -authkestra = { version = "0.9", features = ["actix", "session", "github"] } -authkestra-engine = { version = "0.9", features = ["session", "memory"] } +authkestra = { version = "0.13", features = ["actix", "session", "github"] } +authkestra-engine = { version = "0.13", features = ["session", "memory"] } actix-web = "4" ``` diff --git a/src/content/docs/providers/bot-protection.md b/src/content/docs/providers/bot-protection.md index fc43812..96d4574 100644 --- a/src/content/docs/providers/bot-protection.md +++ b/src/content/docs/providers/bot-protection.md @@ -11,7 +11,7 @@ Enable the `captcha` feature in your `Cargo.toml`: ```toml [dependencies] -authkestra-engine = { version = "0.9", features = ["captcha"] } +authkestra-engine = { version = "0.13", features = ["captcha"] } ``` ## Configuration diff --git a/src/content/docs/providers/device-signatures.mdx b/src/content/docs/providers/device-signatures.mdx index 8443bf9..8645614 100644 --- a/src/content/docs/providers/device-signatures.mdx +++ b/src/content/docs/providers/device-signatures.mdx @@ -20,8 +20,8 @@ Add the `authkestra-devsig` crate to your dependencies: [dependencies] authkestra-devsig = "0.9" # ...plus the `devsig` feature on whichever adapter you use: -authkestra-axum = { version = "0.9", features = ["devsig"] } -# authkestra-actix = { version = "0.9", features = ["devsig"] } +authkestra-axum = { version = "0.13", features = ["devsig"] } +# authkestra-actix = { version = "0.13", features = ["devsig"] } ``` ## How to use `authkestra-devsig` diff --git a/src/content/docs/providers/magic-link.md b/src/content/docs/providers/magic-link.md new file mode 100644 index 0000000..9ca12b4 --- /dev/null +++ b/src/content/docs/providers/magic-link.md @@ -0,0 +1,87 @@ +--- +title: Magic Link +description: Learn how to implement magic-link authentication in Authkestra, delivered however you choose. +--- + +A magic link authenticates someone by proving they control an inbox (or phone number): the application sends them a single-use URL, and following it produces an identity. Authkestra's part of that is deliberately small — it mints a single-use, TTL-bounded, subject-bound secret and consumes it exactly once. It does not own the address book, the mail transport, the template, or the question of whether an address corresponds to an account; delivering the link is always the application's job. + +## Enabling Magic Link + +To use magic links, enable the `magic-link` feature in your `Cargo.toml`: + +```toml +[dependencies] +authkestra-engine = { version = "0.13", features = ["magic-link"] } +``` + +## Configuration + +Magic link is implemented via the `MagicLinkAuthMethod` struct. You initialize it by passing a store that implements both `KvStore` and `AtomicConsume` (e.g. the built-in `RedisStore`, or `MemoryStore` for tests) — atomic fetch-and-remove is what makes a link single-use even against concurrent requests. + +There is no `.with_magic_link()` convenience wrapper the way `.with_totp()` or `.with_webauthn()` exist; register it directly with `.with_auth_method()`: + +```rust +use authkestra::Authkestra; +use authkestra_engine::auth::magic_link::MagicLinkAuthMethod; + +// `my_store` implements `KvStore + AtomicConsume` +let engine = Authkestra::builder() + .with_auth_method(MagicLinkAuthMethod::new(my_store)) + .build(); +``` + +There is no enrolment step: `has_enrolled()` always returns `false` and `is_mfa_equivalent()` always returns `false`. Both are deliberate statements rather than inherited defaults — there is no enrolment ceremony (any subject the application can resolve can be sent a link), and proving you clicked a link is not phishing-resistant, so it earns no second-factor credit for an account whose recovery address is the same inbox. + +## Minting a Link + +Your application resolves whatever the user typed (an email address, say) into a `subject` string, then calls `mint` to get a secret to embed in a URL. Authkestra never sends anything — rendering and delivering the mail (or SMS) is entirely up to you. + +```rust +use std::time::Duration; +use authkestra_engine::auth::magic_link::MagicLinkBinding; + +let token = magic_link_method + .mint("alice", Duration::from_secs(300), MagicLinkBinding::AnyContext) + .await?; + +// token.secret -> embed in the link, e.g. https://example.com/login/confirm?token=... +// token.expires_at -> Unix seconds, useful for rendering in the email +``` + +`ttl` has no default — you must name it. `token.secret` is returned exactly once and is never recoverable afterward; if sending the mail fails, mint a new one rather than trying to retrieve the old secret. + +:::caution +Minting twice for the same subject leaves **both** secrets live until they expire. That's intentional (the first mail may simply be slow) but means you cannot assume a fresh mint invalidates an earlier one still in someone's inbox. +::: + +### Choosing a `MagicLinkBinding` + +`MagicLinkBinding` has no default, and picking one is not optional — you must choose: + +- **`MagicLinkBinding::AnyContext`** — the link works from anywhere. Cross-device flows work ("request on my laptop, open on my phone"), but a forwarded link, a shared inbox, or a screenshot in a support ticket authenticates whoever holds it. +- **`MagicLinkBinding::SameContext(nonce)`** — the link is only valid when redeemed alongside the same `nonce` it was minted with. Set an unguessable nonce as a cookie when the link is requested, and pass that same value back at redemption time. This defends against a forwarded link, at the cost of breaking cross-device use. + +:::note +The nonce must be unguessable — a CSPRNG value, not a username or email address. Binding to something an attacker can predict reproduces `AnyContext` while looking like it doesn't. +::: + +## Authenticating + +Authentication is not tied to the `GET` that loads the landing page — it must happen on an explicit, application-driven call (typically the `POST` behind a "Sign in" button), because corporate mail scanners and link-preview generators routinely `GET` every URL in an email the moment it arrives. If following the link consumed the token, the real user would find it already burned on their first click. + +Redeem the secret with `AuthInput::MagicLink`, passing the same binding value the caller presented (or `None` if the link was minted with `AnyContext`): + +```rust +use authkestra_engine::auth::AuthInput; + +let result = engine.authenticate(AuthInput::MagicLink { + token: secret_from_the_url, + binding: nonce_from_the_cookie, // Some(nonce) for SameContext, None for AnyContext +}).await?; +``` + +A link works exactly once: the store entry is atomically fetched and removed, so a second attempt with the same token — even the correct one — fails. Every rejection (unknown, expired, already used, or wrong binding) returns the same `AuthError::InvalidCredentials`, deliberately: distinguishing them in the response would hand an attacker an oracle. The distinction is still visible in `tracing` output for operators. + +:::caution +A binding mismatch **consumes** the secret rather than leaving it available for a retry. A link presented from the wrong context is exactly the attack `SameContext` exists to catch, so it's burned on the spot — the correct binding cannot rescue it afterward. +::: diff --git a/src/content/docs/providers/oauth2.mdx b/src/content/docs/providers/oauth2.mdx index 9cbd2b8..43e33ee 100644 --- a/src/content/docs/providers/oauth2.mdx +++ b/src/content/docs/providers/oauth2.mdx @@ -18,7 +18,7 @@ If you are using multiple OAuth providers (e.g., GitHub and Google), enable thei ```toml [dependencies] -authkestra = { version = "0.9", features = ["axum", "token", "github", "google"] } +authkestra = { version = "0.13", features = ["axum", "token", "github", "google"] } ``` ## Stateless Engine Configuration diff --git a/src/content/docs/providers/oidc.md b/src/content/docs/providers/oidc.md index b27c81e..40f5360 100644 --- a/src/content/docs/providers/oidc.md +++ b/src/content/docs/providers/oidc.md @@ -11,8 +11,8 @@ To use the OIDC client, enable the `oidc` feature on the `authkestra` crate. ```toml [dependencies] -authkestra = { version = "0.9", features = ["oidc", "session"] } -authkestra-engine = { version = "0.9", features = ["session", "memory"] } +authkestra = { version = "0.13", features = ["oidc", "session"] } +authkestra-engine = { version = "0.13", features = ["session", "memory"] } ``` ## Configuring the OIDC Provider diff --git a/src/content/docs/providers/otp.md b/src/content/docs/providers/otp.md new file mode 100644 index 0000000..df3692d --- /dev/null +++ b/src/content/docs/providers/otp.md @@ -0,0 +1,120 @@ +--- +title: Email/SMS One-Time Codes +description: Learn how to send and verify email or SMS one-time passcodes (OTP) in Authkestra. +--- + +Email/SMS one-time codes let a user sign in with a short numeric code your application delivers however it likes — over email, over SMS, read aloud on a support call. The engine never sends anything and never sees an address: you resolve the subject, ask it to mint a code, deliver the digits yourself, and hand back whatever the user typed. Because a six-digit code is too short to double as a lookup key the way a magic-link secret can, the challenge is stored under the *subject* instead of the code, with a server-enforced attempt budget doing the work a longer secret would otherwise do. + +## Enabling One-Time Codes + +To use OTP, enable the `otp` feature in your `Cargo.toml`. The example below also needs the `memory` feature, for the in-memory store used to hold live challenges: + +```toml +[dependencies] +authkestra-engine = { version = "0.13", features = ["otp", "memory"] } +``` + +## Registering the Method + +OTP has no enrolment ceremony — there is nothing to register in advance. Any subject you've already resolved (an email address, a phone number, whatever your application uses) can be minted a code. There is also no dedicated `.with_otp()` convenience wrapper the way `.with_totp()` / `.with_webauthn()` exist for the older methods, so `OtpAuthMethod` is registered like any other `AuthMethod`, through `.with_auth_method(...)`. + +```rust +use authkestra::Authkestra; +use authkestra_engine::auth::otp::OtpAuthMethod; +use authkestra_engine::store::memory::MemoryStore; + +let otp_store = MemoryStore::new(); + +// Keep a handle you can call `.mint()` on directly — minting isn't +// authentication, so it isn't reached through `Engine::authenticate`. +// `MemoryStore` (and `RedisStore`) are cheap to clone: both wrap their +// backing state behind an `Arc`, so this clone shares the same live +// challenges as the copy registered with the engine below. +let otp_method = OtpAuthMethod::new(otp_store.clone()); + +// `MemoryStore` works for a single process. Swap in `RedisStore` (feature +// `redis`) for anything that needs a live challenge to survive a restart or +// be shared across more than one instance. +let engine = Authkestra::builder() + .with_auth_method(OtpAuthMethod::new(otp_store)) + .build(); +``` + +:::note +There is no `.with_otp(store)` shorthand on `EngineBuilder`. Build the `OtpAuthMethod` yourself and pass it to `.with_auth_method(...)`, as shown above. +::: + +You can optionally chain `.with_resend_cooldown(...)` onto the instance you call `.mint()` through, to refuse a repeat mint for the same subject within an interval. The engine's copy only ever calls `.authenticate()`, never `.mint()`, so it doesn't need the cooldown configured on it too: + +```rust +use std::time::Duration; + +let otp_method = OtpAuthMethod::new(otp_store.clone()) + // Opt-in, and off by default: refuses a second mint for the same + // subject within 60 seconds. + .with_resend_cooldown(Duration::from_secs(60)); +``` + +:::caution +The resend cooldown is per subject, not a replacement for rate limiting at your HTTP edge. It stops one subject's mailbox or phone from being flooded by repeated resends; an attacker rotating IP addresses still needs edge-level limits to be stopped. +::: + +## Minting a Code + +Once you've resolved who is signing in, call `OtpAuthMethod::mint`: + +```rust +use authkestra_engine::auth::otp::OtpChannel; +use std::time::Duration; + +let minted = otp_method + .mint( + "alice@example.com", // subject: whatever you resolved this login attempt to + Duration::from_secs(300), // ttl + OtpChannel::Email, // channel + 3, // max_attempts + ) + .await?; + +// Deliver `minted.code` over your own transport. Authkestra has no mailer +// and no SMS gateway — it only hands you the digits and their expiry. +send_email("alice@example.com", &minted.code); +``` + +- **`subject`** is the identifier you already resolved outside the engine — the same string you'll pass back in on redemption. The challenge is keyed by it. +- **`ttl`** bounds how long the code stays valid; `minted.expires_at` is the resulting Unix timestamp. +- **`channel`** is `OtpChannel::Email` or `OtpChannel::Sms`. It changes nothing about verification — it's recorded purely so the delivery method can be reported later (for `amr`/audit purposes), and this module never inspects it otherwise. +- **`max_attempts`** is the lockout threshold: the number of wrong guesses this one challenge tolerates before it is discarded outright, even if the right code is typed afterwards. It's a required `u32` — `mint` refuses `0` with `AuthError::InvalidInput` rather than silently minting a code nobody could ever redeem. + +:::note +Minting again for the same subject replaces any still-live challenge. A "resend" simply invalidates the old code and restores a fresh attempt budget — it does not stack a second, independent challenge alongside the first. +::: + +## Authenticating + +Redeem the code the user typed with `AuthInput::Otp`: + +```rust +use authkestra_engine::auth::{AuthInput, AuthResult}; + +let result = engine.authenticate(AuthInput::Otp { + subject: "alice@example.com".to_string(), + code: "482913".to_string(), +}).await?; + +match result { + AuthResult::Success(identity) => { + println!("Signed in as: {}", identity.external_id); + } + AuthResult::MfaRequired { mfa_token, allowed_methods, .. } => { + // Handle step-up authentication if this subject also has a + // second factor enrolled. + } +} +``` + +A code is single-use: redemption wins the challenge atomically from the store, so a correct code submitted concurrently from two requests still only ever produces one successful `Identity`. Every wrong guess spends one attempt from the budget you passed to `mint`, tracked server-side alongside the challenge; once the budget reaches zero the challenge is discarded even for the correct code. + +:::caution +An unknown subject, a wrong code, an expired code, and an exhausted attempt budget are all indistinguishable to the caller — every one of them returns `AuthError::InvalidCredentials`. Don't try to branch on *why* an attempt failed from that return value; if you need to know, look at your `tracing` output instead. +::: diff --git a/src/content/docs/providers/passkeys.md b/src/content/docs/providers/passkeys.md index f3844ea..cadba40 100644 --- a/src/content/docs/providers/passkeys.md +++ b/src/content/docs/providers/passkeys.md @@ -11,7 +11,7 @@ To use Passkeys, you must first enable the `webauthn` feature in your `Cargo.tom ```toml [dependencies] -authkestra-engine = { version = "0.9", features = ["webauthn"] } +authkestra-engine = { version = "0.13", features = ["webauthn"] } ``` ## Configuration diff --git a/src/content/docs/providers/recovery-codes.md b/src/content/docs/providers/recovery-codes.md new file mode 100644 index 0000000..57db0f4 --- /dev/null +++ b/src/content/docs/providers/recovery-codes.md @@ -0,0 +1,96 @@ +--- +title: Recovery Codes +description: Learn how to implement one-time-use recovery codes, a look-up secret authenticator, in Authkestra. +--- + +Recovery codes are a set of one-time-use codes an account can fall back on when its usual factor is unreachable — the phone with the authenticator app is in a river, the passkey's device is lost, the recovery mailbox is gone. Authkestra implements them as a **look-up secret authenticator** per [NIST SP 800-63B §5.1.2](https://pages.nist.gov/800-63-3/sp800-63b.html#sec5), and that framing is deliberate: this is a fallback for *whatever* the account has registered — a passkey, TOTP, magic link, anything — not an appendix to one factor. An account whose only factor is a passkey can enrol recovery codes with no TOTP in sight. Never call these "TOTP backup codes"; they are their own `AuthMethod`, keyed by subject and independent of what else the account has enrolled. + +## Enabling Recovery Codes + +To use recovery codes, enable the `recovery-codes` feature in your `Cargo.toml`: + +```toml +[dependencies] +authkestra-engine = { version = "0.13", features = ["recovery-codes"] } +``` + +## Configuration + +Recovery codes are implemented via the `RecoveryCodeAuthMethod` struct. You initialize it by passing a `CredentialStore` where the code hashes will be saved — the store never sees a plaintext code. + +```rust +use authkestra::Authkestra; +use authkestra_engine::auth::recovery::RecoveryCodeAuthMethod; + +// `my_store` implements the `CredentialStore` trait (e.g. `SqlxCredentialStore`) +let engine = Authkestra::builder() + .with_auth_method(RecoveryCodeAuthMethod::new(my_store.clone())) + .build(); +``` + +There is no `.with_recovery_codes()` convenience wrapper the way `.with_totp()` and `.with_webauthn()` exist for the two older methods — register it through `.with_auth_method(...)` as shown above. + +## Generating a Set (Enrolment) + +Recovery codes are the one method on this track that actually **enrols**, so generating a set is gated behind a `ReproofRequirement` — the same re-proof gate that guards enrolling any other sensitive credential. Keep a reference to your `RecoveryCodeAuthMethod` and call `generate`, passing the already-authenticated `Identity`, the gate, and how many codes to issue: + +```rust +use authkestra_engine::auth::{AuthMethod, ReproofRequirement}; +use authkestra_engine::auth::recovery::RecoveryCodeAuthMethod; + +let recovery = RecoveryCodeAuthMethod::new(my_store); + +// `identity` is the `Identity` from the user's current, freshly-proved session. +// Drive `require_step_up` from whether the account already has a working +// fallback: one that does is made to use it, one that does not (this is +// plausibly its very first enrolment) is gated on freshness alone. +let has_fallback = recovery.has_enrolled(&identity.external_id).await?; +let gate = ReproofRequirement::new(300).require_step_up(has_fallback); + +let codes: Vec = recovery.generate(&identity, &gate, 10).await?; +// e.g. ["4KDW-9JMQ-2XPT-R7HV", ...] +``` + +Calling `generate` again replaces the previous set entirely — there is no partial top-up. + +:::caution +`codes` is the **only time** these values are ever readable. The store only ever holds a SHA-256 hash of each code, never the code itself, and there is no "show them to me again" endpoint. Render them to the user immediately (a printable page, a download) and discard them from memory afterward. + +Note the argument order on `generate`: `identity`, then `gate`, then `count: u8`. The gate is checked, and nothing is written, before any code is generated — a rejected gate leaves the account's existing set (if any) untouched. +::: + +## Checking How Many Remain + +`remaining` reports how many unredeemed codes an account still has, so an application can prompt a user to regenerate before they run out: + +```rust +let left: usize = recovery.remaining(&identity).await?; +``` + +:::note +`has_enrolled` (from the `AuthMethod` trait, hence the `AuthMethod` import above) means "has at least one **unredeemed** code", not "has ever generated a set". An account that has burned through every code reports `false` again — which is exactly what makes it safe to drive `require_step_up` from, as shown above: it can only report a usable fallback exists when one actually does. +::: + +## Authenticating (Redeeming a Code) + +A code is redeemed with `AuthInput::RecoveryCode`, naming the account and the code as typed: + +```rust +use authkestra_engine::auth::{AuthInput, AuthResult}; + +let result = engine.authenticate(AuthInput::RecoveryCode { + user_id: "user_123".to_string(), + code: "4KDW-9JMQ-2XPT-R7HV".to_string(), +}).await?; + +match result { + AuthResult::Success(identity) => { + println!("Successfully authenticated as: {}", identity.external_id); + } + AuthResult::MfaRequired { mfa_token, allowed_methods, .. } => { + // A recovery code satisfies an MFA challenge as a step-up factor. + } +} +``` + +Redemption is single-use and safe under concurrency: if two requests race to redeem the same code, exactly one succeeds and the other gets `AuthError::InvalidCredentials`, the same error returned for an unknown or already-used code — nothing about the failure distinguishes the two cases. Dashes and letter case are also normalized before comparison, so `4kdw9jmq2xptr7hv` and `4KDW-9JMQ-2XPT-R7HV` are the same code as far as redemption is concerned. diff --git a/src/content/docs/providers/totp.md b/src/content/docs/providers/totp.md index cd6aa85..cea8f3f 100644 --- a/src/content/docs/providers/totp.md +++ b/src/content/docs/providers/totp.md @@ -11,7 +11,7 @@ To use TOTP, enable the `totp` feature in your `Cargo.toml`: ```toml [dependencies] -authkestra-engine = { version = "0.9", features = ["totp"] } +authkestra-engine = { version = "0.13", features = ["totp"] } ``` ## Configuration diff --git a/src/content/docs/storage/kv-store.md b/src/content/docs/storage/kv-store.md index 9a87763..988b26e 100644 --- a/src/content/docs/storage/kv-store.md +++ b/src/content/docs/storage/kv-store.md @@ -13,9 +13,9 @@ as features of its own, so depend on the engine directly for these: ```toml [dependencies] -authkestra = { version = "0.9", features = ["axum", "session"] } +authkestra = { version = "0.13", features = ["axum", "session"] } # Example: Using the Redis KV store -authkestra-engine = { version = "0.9", features = ["session", "redis"] } +authkestra-engine = { version = "0.13", features = ["session", "redis"] } ``` ### 1. Memory Store (`memory`) diff --git a/src/content/docs/storage/sql-store.md b/src/content/docs/storage/sql-store.md index a906e02..ad570c7 100644 --- a/src/content/docs/storage/sql-store.md +++ b/src/content/docs/storage/sql-store.md @@ -19,7 +19,7 @@ To use it, add the `authkestra-store-sqlx` crate and enable the feature for the ```toml [dependencies] -authkestra-store-sqlx = { version = "0.9", features = ["postgres"] } +authkestra-store-sqlx = { version = "0.13", features = ["postgres"] } # or mysql, sqlite ```