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
1 change: 1 addition & 0 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ export default defineConfig({
{ label: 'Quickstart', slug: 'guides/quickstart' },
{ label: 'Framework Integration', slug: 'guides/framework-integration' },
{ label: 'Wired Endpoints', slug: 'guides/wired-endpoints' },
{ label: 'AI Agents & MCP', slug: 'guides/ai-agents', badge: { text: 'New', variant: 'tip' } },
],
},
{
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/advanced/continuous-access-evaluation.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ The three gaps are tracked in

```toml
[dependencies]
authkestra-ssf = "0.11"
authkestra-ssf = "0.13"
jsonwebtoken = { version = "11", features = ["rust_crypto"] }
```

Expand Down
5 changes: 2 additions & 3 deletions src/content/docs/advanced/op-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,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.13", features = ["op"] }
authkestra = { version = "0.13", features = ["axum", "op"] }
# Or if using Actix:
# authkestra-actix = { version = "0.13", features = ["op"] }
# authkestra = { version = "0.13", features = ["actix", "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 @@ -21,7 +21,7 @@ review, diff and reload, instead of in `if role == "admin"` branches scattered a
[dependencies]
authkestra = { version = "0.13", features = ["policy"] }
# or the crate on its own:
authkestra-policy = "0.11"
authkestra-policy = "0.13"
```

## The one rule: the engine never touches your database
Expand Down
5 changes: 2 additions & 3 deletions src/content/docs/advanced/resource-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,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.13", features = ["resource"] }
authkestra = { version = "0.13", features = ["axum", "resource"] }
# Or if using Actix:
# authkestra-actix = { version = "0.13", features = ["resource"] }
# authkestra = { version = "0.13", features = ["actix", "resource"] }
```

### TLS Backend Selection
Expand Down
58 changes: 58 additions & 0 deletions src/content/docs/guides/ai-agents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
title: AI Coding Assistants & Agent Auth
description: Using Authkestra with Claude Code, Cursor, and Windsurf via llms.txt and official skills, and securing AI agents & MCP servers in Rust.
---

Authkestra is designed for two sides of the AI era:
1. **Zero-Hallucination Code Generation ("Vibe-Coding" Guardrails)**: Because `Authkestra::builder()` uses a strict **Typestate Builder Pattern**, an AI coding assistant cannot accidentally wire a session route without a session store or a stateless JWT callback without a token manager — invalid authentication flows fail at `cargo check` instead of shipping a runtime vulnerability.
2. **High-Assurance AI Agent & MCP Authorization**: Authkestra's embedded OIDC Provider (`authkestra-op`), Resource Server (`authkestra-resource`), Device-Bound Signatures (`authkestra-devsig`), WebAuthn Passkeys, and AWS Cedar Policy Engine (`authkestra-policy`) provide the exact cryptographic primitives needed to authenticate AI agents, broker scoped downstream tokens, and enforce human-in-the-loop (HITL) step-up approval.

---

## 1. `llms.txt` & Official Coding Agent Skills

### `llms.txt` and `llms-full.txt`

Every deploy of `docs.authkestra.com` generates machine-readable documentation indexes following the [llms.txt standard](https://llmstxt.org/):

- **[`https://docs.authkestra.com/llms.txt`](/llms.txt)**: Concise index of all Authkestra crates, feature flags, architectural rules, and documentation links.
- **[`https://docs.authkestra.com/llms-full.txt`](/llms-full.txt)**: Complete, single-file concatenation of the entire Authkestra documentation corpus for pasting into Claude, Cursor `@Docs`, Windsurf, or local RAG pipelines.

### Official Agent Skill Pack (`Authkestra/skills`)

Install the official [Authkestra skill pack](https://github.com/Authkestra/skills) into Claude Code, Cursor, or any SKILL.md-compatible coding agent:

```bash
/plugin marketplace add Authkestra/skills
/plugin install authkestra@authkestra
```

| Skill | What it teaches your coding agent |
| --- | --- |
| `authkestra-quickstart` | End-to-end Axum/Actix setup, TLS backend selection, typestate builder, and extractor wiring (`v0.13`). |
| `authkestra-features` | Diagnosing missing Cargo feature flags vs. unmet typestate prerequisites. |
| `authkestra-store` | Implementing `KvStore`, `AtomicConsume`, `AtomicDecrement`, `CredentialStore`, and `OpStore`, validated with `authkestra-store-testsuite`. |
| `authkestra-social-login` | GitHub/Google/Discord OAuth2, OIDC discovery caching, and stateless encrypted-cookie handshakes. |
| `authkestra-op` | Running an embedded OpenID Provider: PKCE, DPoP, `private_key_jwt`, Device Flow, and RFC 8693 Token Exchange. |
| `authkestra-resource-server` | Protecting APIs and MCP servers with `Guard`, multi-issuer JWKS, DPoP, and mTLS. |
| `authkestra-mfa` | Passkeys (WebAuthn), TOTP, Magic Links, OTP, Recovery Codes, `ReproofRequirement`, and `authkestra-devsig`. |
| `authkestra-upgrade` | Migrating from pre-RFC-001 crates (`authkestra-core`, `authkestra-flow`, `authkestra-session`, `authkestra-token`) and upgrading to `0.13` `ReproofRequirement` signatures. |
| `authkestra-troubleshoot` | Resolving `rustls` CryptoProvider panics, cross-site OAuth cookie drops, and clock skew. |

---

## 2. Securing AI Agents & MCP Servers with Authkestra

When building Model Context Protocol (MCP) servers or autonomous agent gateways in Rust, Authkestra gives you four composable primitives inside a single binary:

### Delegated Agent Tokens via RFC 8693 Token Exchange (`authkestra-op`)
Never place long-lived user refresh tokens or god-mode API keys inside an LLM's context window. Enable `token_exchange_enabled: true` on `OpConfig` to let your agent gateway trade a user's token for a short-lived, strictly audience-bound (`allowed_audiences`) and scope-narrowed downstream token via `urn:ietf:params:oauth:grant-type:token-exchange`.

### Out-of-Band Human Approval via Device Flow (`DeviceFlow` + `authkestra-op`)
When a headless CLI agent or background worker hits a restricted tool call, initiate an [RFC 8628 Device Authorization Grant](/providers/device-flow/) against your `authkestra-op` server. The human user opens the verification URI on their phone or laptop and authenticates with a phishing-resistant [Passkey](/providers/passkeys/) before the agent receives its execution token.

### Cryptographic Parameter Binding (`authkestra-devsig`)
Standard bearer tokens only prove *who* authorized the agent, not *which parameters* the agent is sending. With [`authkestra-devsig`](/providers/device-signatures/), every request carries an `X-Attestation` (minted by `authkestra-op`) and a single-use `X-Signature` JWS whose `bdh` claim is the SHA-256 digest of the exact HTTP request body (`mth`, `pth`, `qsh`, `bdh`, `aud`). Modifying a single tool argument invalidates the signature before your handler ever runs.

### Guardrails & Instant Kill-Switch (`authkestra-policy` + `authkestra-ssf`)
Evaluate every tool invocation against declarative [AWS Cedar policies](/advanced/policy-and-ssf/) (`authkestra-policy`) and terminate compromised agent sessions in real time via [OpenID CAEP `SessionRevoked` events](/advanced/policy-and-ssf/#2-shared-signals-framework--caep-authkestra-ssf) (`authkestra-ssf`).
6 changes: 4 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.13", features = ["axum", "session"] }
authkestra = { version = "0.13", features = ["axum", "memory"] }
```

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

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

</TabItem>
Expand Down Expand Up @@ -173,6 +173,7 @@ use axum::Router;
use tower_cookies::CookieManagerLayer;

#[derive(Clone, AxumState)]
#[authkestra(crate = ::authkestra::axum)]
struct AppState {
#[authkestra(engine)]
auth: AkWebAppEngine,
Expand All @@ -198,6 +199,7 @@ use authkestra::actix::{ActixExt, ActixState};
use authkestra::core::AkWebAppEngine;

#[derive(Clone, ActixState)]
#[authkestra(crate = ::authkestra::actix)]
struct AppState {
#[authkestra(engine)]
auth: AkWebAppEngine,
Expand Down
24 changes: 11 additions & 13 deletions src/content/docs/guides/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,7 @@ Add the `authkestra` facade crate to your `Cargo.toml`. The facade re-exports al

```toml
[dependencies]
authkestra = { version = "0.13", features = ["axum", "session", "github"] }
authkestra-engine = { version = "0.13", features = ["session", "memory"] }
authkestra = { version = "0.13", features = ["axum", "memory", "github"] }
tower-cookies = "0.11"
tokio = { version = "1", features = ["full"] }
```
Expand All @@ -27,8 +26,7 @@ tokio = { version = "1", features = ["full"] }

```toml
[dependencies]
authkestra = { version = "0.13", features = ["actix", "session", "github"] }
authkestra-engine = { version = "0.13", features = ["session", "memory"] }
authkestra = { version = "0.13", features = ["actix", "macros", "memory", "github"] }
actix-web = "4"
```

Expand All @@ -40,10 +38,10 @@ actix-web = "4"
The core logic of Authkestra is identical regardless of which web framework you choose. First, initialize the Identity Provider (`GithubProvider`), wrap it in an `OAuth2Flow`, and construct the `Engine` using the Typestate Builder Pattern (`Authkestra::builder()`).

```rust
use authkestra::Authkestra;
use authkestra::core::{OAuth2Flow, SessionStore};
use authkestra::providers::github::GithubProvider;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use authkestra::store::memory::MemoryStore;
use authkestra::Authkestra;
use std::sync::Arc;

// 1. Initialize the GitHub Provider
Expand Down Expand Up @@ -78,16 +76,16 @@ Once the engine is built, integrate it into your web framework's routing layer.

```rust
use authkestra::axum::{AxumExt, AxumState};
use authkestra::core::AkWebAppEngine;
use authkestra::core::{AkWebAppEngine, OAuth2Flow, SessionStore};
use authkestra::providers::github::GithubProvider;
use authkestra::store::memory::MemoryStore;
use authkestra::Authkestra;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use axum::Router;
use std::sync::Arc;
use tower_cookies::CookieManagerLayer;

#[derive(Clone, AxumState)]
#[authkestra(crate = ::authkestra::axum)]
struct AppState {
#[authkestra(engine)]
auth: AkWebAppEngine,
Expand Down Expand Up @@ -132,14 +130,14 @@ cargo run -p authkestra --example axum_oauth2_github --all-features
```rust
use actix_web::{web, App, HttpServer};
use authkestra::actix::{ActixExt, ActixState};
use authkestra::core::AkWebAppEngine;
use authkestra::core::{AkWebAppEngine, OAuth2Flow, SessionStore};
use authkestra::providers::github::GithubProvider;
use authkestra::store::memory::MemoryStore;
use authkestra::Authkestra;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use std::sync::Arc;

#[derive(Clone, ActixState)]
#[authkestra(crate = ::authkestra::actix)]
struct AppState {
#[authkestra(engine)]
auth: AkWebAppEngine,
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.13", features = ["captcha"] }
authkestra = { version = "0.13", features = ["captcha"] }
```

## Configuration
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/providers/client-credentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ engine's own types, so depend on it directly (the `authkestra` facade re-exports

```toml
[dependencies]
authkestra-engine = "0.9"
authkestra-engine = "0.13"
tokio = { version = "1", features = ["full"] }
```

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/providers/device-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ engine's own types, so depend on it directly (the `authkestra` facade re-exports

```toml
[dependencies]
authkestra-engine = "0.9"
authkestra-engine = "0.13"
tokio = { version = "1", features = ["full"] }
```

Expand Down
7 changes: 3 additions & 4 deletions src/content/docs/providers/device-signatures.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,9 @@ Add the `authkestra-devsig` crate to your dependencies:

```toml
[dependencies]
authkestra-devsig = "0.9"
# ...plus the `devsig` feature on whichever adapter you use:
authkestra-axum = { version = "0.13", features = ["devsig"] }
# authkestra-actix = { version = "0.13", features = ["devsig"] }
authkestra = { version = "0.13", features = ["axum", "devsig"] }
# Or with Actix:
# authkestra = { version = "0.13", features = ["actix", "devsig"] }
```

## How to use `authkestra-devsig`
Expand Down
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.13", features = ["axum", "token", "github", "google"] }
authkestra = { version = "0.13", features = ["axum", "github", "google"] }
```

## Stateless Engine Configuration
Expand Down
3 changes: 1 addition & 2 deletions src/content/docs/providers/oidc.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,7 @@ To use the OIDC client, enable the `oidc` feature on the `authkestra` crate.

```toml
[dependencies]
authkestra = { version = "0.13", features = ["oidc", "session"] }
authkestra-engine = { version = "0.13", features = ["session", "memory"] }
authkestra = { version = "0.13", features = ["oidc", "memory"] }
```

## Configuring the OIDC Provider
Expand Down
29 changes: 17 additions & 12 deletions src/content/docs/providers/passkeys.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ Passkeys provide a highly secure, phishing-resistant alternative to passwords by

## Enabling Passkeys

To use Passkeys, you must first enable the `webauthn` feature in your `Cargo.toml`:
To use Passkeys, enable the `webauthn` feature in your `Cargo.toml` (either on the `authkestra` facade or directly on `authkestra-engine`):

```toml
[dependencies]
authkestra-engine = { version = "0.13", features = ["webauthn"] }
authkestra = { version = "0.13", features = ["webauthn"] }
```

## Configuration
Expand Down Expand Up @@ -47,21 +47,26 @@ A runnable example combining passkeys with TOTP lives in the repository:
cargo run -p authkestra --example axum_mfa_server --all-features
```

## Registration Ceremony
## Registration Ceremony (Re-Proof Gated)

Registration is also a two-step ceremony, driven directly on the `WebAuthnAuthMethod`:
Enrolling a passkey is a security-posture change, so `start_register` requires an authenticated `Identity` and a [`ReproofRequirement`](/providers/passwordless/#re-proof-gating-reproofrequirement) (introduced in `0.13`) rather than a bare user ID string. This prevents a stale or stolen session from silently enrolling an attacker's passkey, and binds the subject into the returned `PasskeyEnrolment` state so `finish_register` cannot be tricked into filing the credential under a different account:

```rust
use authkestra_engine::auth::webauthn::WebAuthnAuthMethod;
use authkestra_engine::auth::{webauthn::WebAuthnAuthMethod, AuthMethod, ReproofRequirement};

let method = WebAuthnAuthMethod::new(Arc::new(webauthn), my_store);

// Require authentication within the last 300 seconds, plus step-up if a passkey is already enrolled
let gate = ReproofRequirement::new(300)
.require_step_up(method.has_enrolled(&session.identity.external_id).await?);

// 1. Start: return `challenge` to the browser for `navigator.credentials.create()`,
// and stash `reg_state` in the user's session.
let (challenge, reg_state) = method.start_register("user_123", "ada")?;
// and stash `enrolment` (`PasskeyEnrolment`) in server-side session state.
let (challenge, enrolment) = method.start_register(&session.identity, &gate, "ada")?;

// 2. Finish: verify the attestation and persist the passkey via the CredentialStore.
let passkey = method.finish_register("user_123", reg_response, reg_state).await?;
// `enrolment` already carries the verified subject, so no user_id argument is passed here.
let passkey = method.finish_register(enrolment, reg_response).await?;
```

### User handles
Expand All @@ -71,7 +76,7 @@ credential and returns it as `response.userHandle` on every later assertion, whi
discoverable ("usernameless") sign-in able to resolve an account. It must be stable for the lifetime
of the account and map back to exactly one user.

`start_register` derives the handle from `user_id` with `derive_user_handle`:
`start_register` derives the handle from `identity.external_id` with `derive_user_handle`:

- a `user_id` that already parses as a UUID is used verbatim;
- anything else (CUID, ULID, prefixed id, integer) is hashed into a **UUIDv5** over the documented
Expand All @@ -86,9 +91,9 @@ since `start_register` passes `username` for both — use `start_register_with_h
```rust
use authkestra_engine::auth::webauthn::derive_user_handle;

let handle = derive_user_handle("user_123"); // or your own stable handle
let (challenge, reg_state) =
method.start_register_with_handle(handle, "ada", "Ada Lovelace")?;
let handle = derive_user_handle(&session.identity.external_id); // or your own stable handle
let (challenge, enrolment) =
method.start_register_with_handle(&session.identity, &gate, handle, "ada", "Ada Lovelace")?;
```

## Authentication Ceremony
Expand Down
16 changes: 11 additions & 5 deletions src/content/docs/providers/totp.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ To use TOTP, enable the `totp` feature in your `Cargo.toml`:

```toml
[dependencies]
authkestra-engine = { version = "0.13", features = ["totp"] }
authkestra = { version = "0.13", features = ["totp"] }
```

## Configuration
Expand All @@ -38,14 +38,20 @@ step-up-only behaviour described here.

By registering it this way, the Engine will automatically block any attempt to use TOTP directly for primary authentication (enforcing that it can only be submitted in an `MfaChallenge` after a primary method like a password is authenticated).

## Registering a Device
## Registering a Device (Re-Proof Gated)

To enroll a user, keep a reference to your `TotpAuthMethod` and call `register_totp`. It automatically generates a new base32 secret and an `otpauth://` provisioning URI. The secret is saved to the store internally.
To enroll a user, keep a reference to your `TotpAuthMethod` and call `register_totp`. Like Passkeys and Recovery Codes, TOTP enrolment is gated by [`ReproofRequirement`](/providers/passwordless/#re-proof-gating-reproofrequirement) so a stale session cannot silently enrol a second factor, and the account ID is taken directly from `identity.external_id`:

```rust
use authkestra_engine::auth::{AuthMethod, ReproofRequirement};

let gate = ReproofRequirement::new(300)
.require_step_up(totp_method.has_enrolled(&session.identity.external_id).await?);

let (secret_b32, uri) = totp_method.register_totp(
"user_123", // user ID
"Authkestra", // Issuer (shows in app)
&session.identity, // Authenticated identity (provides external_id + auth_time)
&gate, // Freshness + step-up gate
"Authkestra", // Issuer (shows in authenticator app)
"alice@example.com" // Account name
).await?;
```
Expand Down
8 changes: 2 additions & 6 deletions src/content/docs/storage/kv-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,11 @@ KV Stores (Key-Value) are the primary way `authkestra-engine` persists session d

## Available Implementations

Authkestra includes a few generic KV stores. The store implementations and their feature flags
live on `authkestra-engine` — the `authkestra` facade does not re-export `memory`/`redis`
as features of its own, so depend on the engine directly for these:
Authkestra includes built-in generic KV stores (`memory` and `redis`), forwarded directly through the `authkestra` facade crate:

```toml
[dependencies]
authkestra = { version = "0.13", features = ["axum", "session"] }
# Example: Using the Redis KV store
authkestra-engine = { version = "0.13", features = ["session", "redis"] }
authkestra = { version = "0.13", features = ["axum", "redis"] }
```

### 1. Memory Store (`memory`)
Expand Down
Loading
Loading