Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
],
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/advanced/op-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/advanced/policy-engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
```
Expand Down
6 changes: 3 additions & 3 deletions src/content/docs/advanced/resource-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/concepts/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<dyn Trait>`) 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.
4 changes: 2 additions & 2 deletions src/content/docs/guides/framework-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,15 @@ 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"] }
```

</TabItem>
<TabItem label="Actix-web" icon="seti:rust">

```toml
[dependencies]
authkestra = { version = "0.9", features = ["actix", "session"] }
authkestra = { version = "0.13", features = ["actix", "session"] }
```

</TabItem>
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/guides/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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"] }
```
Expand All @@ -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"
```

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/providers/bot-protection.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/providers/device-signatures.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
87 changes: 87 additions & 0 deletions src/content/docs/providers/magic-link.md
Original file line number Diff line number Diff line change
@@ -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<MagicLinkRecord>` and `AtomicConsume<MagicLinkRecord>` (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<MagicLinkRecord> + AtomicConsume<MagicLinkRecord>`
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.
:::
2 changes: 1 addition & 1 deletion src/content/docs/providers/oauth2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/providers/oidc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
120 changes: 120 additions & 0 deletions src/content/docs/providers/otp.md
Original file line number Diff line number Diff line change
@@ -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.
:::
2 changes: 1 addition & 1 deletion src/content/docs/providers/passkeys.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading