From 1e406b3d2212680f738c1f6aa920759114e57edf Mon Sep 17 00:00:00 2001 From: Marco Kuidja Date: Mon, 26 Oct 2026 00:04:12 +0100 Subject: [PATCH] feat(docs): add /llms.txt, /llms-full.txt, AI agents guide, and v0.13 API fixes --- astro.config.mjs | 1 + .../advanced/continuous-access-evaluation.md | 2 +- src/content/docs/advanced/op-server.md | 5 +- src/content/docs/advanced/policy-engine.md | 2 +- src/content/docs/advanced/resource-server.mdx | 5 +- src/content/docs/guides/ai-agents.md | 58 ++++++++++++ .../docs/guides/framework-integration.mdx | 6 +- src/content/docs/guides/quickstart.mdx | 24 +++-- src/content/docs/providers/bot-protection.md | 2 +- .../docs/providers/client-credentials.md | 2 +- src/content/docs/providers/device-flow.md | 2 +- .../docs/providers/device-signatures.mdx | 7 +- src/content/docs/providers/oauth2.mdx | 2 +- src/content/docs/providers/oidc.md | 3 +- src/content/docs/providers/passkeys.md | 29 +++--- src/content/docs/providers/totp.md | 16 ++-- src/content/docs/storage/kv-store.md | 8 +- src/pages/llms-full.txt.ts | 89 +++++++++++++++++++ src/pages/llms.txt.ts | 70 +++++++++++++++ 19 files changed, 277 insertions(+), 56 deletions(-) create mode 100644 src/content/docs/guides/ai-agents.md create mode 100644 src/pages/llms-full.txt.ts create mode 100644 src/pages/llms.txt.ts diff --git a/astro.config.mjs b/astro.config.mjs index 1da83bb..0eda372 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -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' } }, ], }, { diff --git a/src/content/docs/advanced/continuous-access-evaluation.md b/src/content/docs/advanced/continuous-access-evaluation.md index fd276f6..01042b7 100644 --- a/src/content/docs/advanced/continuous-access-evaluation.md +++ b/src/content/docs/advanced/continuous-access-evaluation.md @@ -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"] } ``` diff --git a/src/content/docs/advanced/op-server.md b/src/content/docs/advanced/op-server.md index fb0b868..1214fc7 100644 --- a/src/content/docs/advanced/op-server.md +++ b/src/content/docs/advanced/op-server.md @@ -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 diff --git a/src/content/docs/advanced/policy-engine.md b/src/content/docs/advanced/policy-engine.md index e6a8542..495dede 100644 --- a/src/content/docs/advanced/policy-engine.md +++ b/src/content/docs/advanced/policy-engine.md @@ -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 diff --git a/src/content/docs/advanced/resource-server.mdx b/src/content/docs/advanced/resource-server.mdx index 5c24dc8..8a87262 100644 --- a/src/content/docs/advanced/resource-server.mdx +++ b/src/content/docs/advanced/resource-server.mdx @@ -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 diff --git a/src/content/docs/guides/ai-agents.md b/src/content/docs/guides/ai-agents.md new file mode 100644 index 0000000..7f4d112 --- /dev/null +++ b/src/content/docs/guides/ai-agents.md @@ -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`). diff --git a/src/content/docs/guides/framework-integration.mdx b/src/content/docs/guides/framework-integration.mdx index 9bd31c1..afab5f3 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.13", features = ["axum", "session"] } +authkestra = { version = "0.13", features = ["axum", "memory"] } ``` @@ -23,7 +23,7 @@ authkestra = { version = "0.13", features = ["axum", "session"] } ```toml [dependencies] -authkestra = { version = "0.13", features = ["actix", "session"] } +authkestra = { version = "0.13", features = ["actix", "macros", "memory"] } ``` @@ -173,6 +173,7 @@ use axum::Router; use tower_cookies::CookieManagerLayer; #[derive(Clone, AxumState)] +#[authkestra(crate = ::authkestra::axum)] struct AppState { #[authkestra(engine)] auth: AkWebAppEngine, @@ -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, diff --git a/src/content/docs/guides/quickstart.mdx b/src/content/docs/guides/quickstart.mdx index 18a5b32..2900e62 100644 --- a/src/content/docs/guides/quickstart.mdx +++ b/src/content/docs/guides/quickstart.mdx @@ -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"] } ``` @@ -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" ``` @@ -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 @@ -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, @@ -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, diff --git a/src/content/docs/providers/bot-protection.md b/src/content/docs/providers/bot-protection.md index 96d4574..88ff09e 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.13", features = ["captcha"] } +authkestra = { version = "0.13", features = ["captcha"] } ``` ## Configuration diff --git a/src/content/docs/providers/client-credentials.md b/src/content/docs/providers/client-credentials.md index f1d6110..2f79e82 100644 --- a/src/content/docs/providers/client-credentials.md +++ b/src/content/docs/providers/client-credentials.md @@ -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"] } ``` diff --git a/src/content/docs/providers/device-flow.md b/src/content/docs/providers/device-flow.md index 0b61ba5..2f774e4 100644 --- a/src/content/docs/providers/device-flow.md +++ b/src/content/docs/providers/device-flow.md @@ -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"] } ``` diff --git a/src/content/docs/providers/device-signatures.mdx b/src/content/docs/providers/device-signatures.mdx index 8645614..99a37ff 100644 --- a/src/content/docs/providers/device-signatures.mdx +++ b/src/content/docs/providers/device-signatures.mdx @@ -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` diff --git a/src/content/docs/providers/oauth2.mdx b/src/content/docs/providers/oauth2.mdx index 43e33ee..19ab08d 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.13", features = ["axum", "token", "github", "google"] } +authkestra = { version = "0.13", features = ["axum", "github", "google"] } ``` ## Stateless Engine Configuration diff --git a/src/content/docs/providers/oidc.md b/src/content/docs/providers/oidc.md index 40f5360..e081783 100644 --- a/src/content/docs/providers/oidc.md +++ b/src/content/docs/providers/oidc.md @@ -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 diff --git a/src/content/docs/providers/passkeys.md b/src/content/docs/providers/passkeys.md index cadba40..c6b23d5 100644 --- a/src/content/docs/providers/passkeys.md +++ b/src/content/docs/providers/passkeys.md @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/src/content/docs/providers/totp.md b/src/content/docs/providers/totp.md index cea8f3f..b0c993c 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.13", features = ["totp"] } +authkestra = { version = "0.13", features = ["totp"] } ``` ## Configuration @@ -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?; ``` diff --git a/src/content/docs/storage/kv-store.md b/src/content/docs/storage/kv-store.md index 988b26e..0282888 100644 --- a/src/content/docs/storage/kv-store.md +++ b/src/content/docs/storage/kv-store.md @@ -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`) diff --git a/src/pages/llms-full.txt.ts b/src/pages/llms-full.txt.ts new file mode 100644 index 0000000..20e4bf5 --- /dev/null +++ b/src/pages/llms-full.txt.ts @@ -0,0 +1,89 @@ +import type { APIRoute } from 'astro'; +import { getCollection } from 'astro:content'; + +const PAGE_ORDER = [ + 'index', + 'concepts/architecture', + 'concepts/typestate-builder', + 'guides/quickstart', + 'guides/framework-integration', + 'guides/wired-endpoints', + 'guides/ai-agents', + 'providers/oauth2', + 'providers/oidc', + 'providers/client-credentials', + 'providers/device-flow', + 'providers/passkeys', + 'providers/totp', + 'providers/magic-link', + 'providers/otp', + 'providers/recovery-codes', + 'providers/bot-protection', + 'providers/device-signatures', + 'advanced/resource-server', + 'advanced/op-server', + 'guides/device-attestation', + 'advanced/policy-engine', + 'advanced/continuous-access-evaluation', + 'advanced/instrumentation', + 'storage/overview', + 'storage/kv-store', + 'storage/sql-store', + 'storage/implementing-stores', +]; + +function cleanMdxBody(raw: string): string { + return raw + .replace(/^import\s+.*?;?\s*$/gm, '') + .replace(/<\/?(?:Tabs|CardGrid)\b[^>]*>/g, '') + .replace(/]*>/g, '\n#### $1\n') + .replace(/<\/TabItem>/g, '') + .replace( + //g, + '- [$1](https://docs.authkestra.com$3): $2', + ) + .replace(/\n{3,}/g, '\n\n') + .trim(); +} + +export const GET: APIRoute = async () => { + const docs = await getCollection('docs'); + const byId = new Map(docs.map((doc) => [doc.id.replace(/\.(mdx?|md)$/, ''), doc])); + + const orderedIds = [ + ...PAGE_ORDER.filter((id) => byId.has(id)), + ...Array.from(byId.keys()) + .filter((id) => !PAGE_ORDER.includes(id)) + .sort(), + ]; + + const sections: string[] = [ + '# Authkestra — Complete Documentation Corpus (v0.13)', + '', + '> Source: https://docs.authkestra.com | Index: https://docs.authkestra.com/llms.txt | Crate: https://crates.io/crates/authkestra | Skills: https://github.com/Authkestra/skills', + '', + ]; + + for (const id of orderedIds) { + const doc = byId.get(id); + if (!doc) continue; + const url = + id === 'index' ? 'https://docs.authkestra.com/' : `https://docs.authkestra.com/${id}/`; + sections.push('---'); + sections.push(''); + sections.push(`# ${doc.data.title}`); + if (doc.data.description) { + sections.push(`> ${doc.data.description}`); + } + sections.push(`URL: ${url}`); + sections.push(''); + sections.push(cleanMdxBody(doc.body ?? '')); + sections.push(''); + } + + return new Response(sections.join('\n'), { + headers: { + 'Content-Type': 'text/plain; charset=utf-8', + }, + }); +}; diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts new file mode 100644 index 0000000..144df71 --- /dev/null +++ b/src/pages/llms.txt.ts @@ -0,0 +1,70 @@ +import type { APIRoute } from 'astro'; + +const LLMS_TXT = `# Authkestra (v0.13) + +> Authkestra is a modular, framework-agnostic authentication and authorization orchestration engine for Rust. It combines an OAuth2/OIDC client, stateless/stateful session orchestrator, passwordless & MFA engine (Passkeys/WebAuthn, TOTP, Magic Links, Email/SMS OTP, Recovery Codes, Re-proof gating), Resource Server (JWT/JWKS/DPoP/mTLS), OpenID Connect Provider (OP with RFC 8693 Token Exchange & Device Flow), Device-Bound Signatures (\`authkestra-devsig\`), AWS Cedar Policy Engine (\`authkestra-policy\`), and OpenID Shared Signals / CAEP receiver (\`authkestra-ssf\`) behind a compile-time safe Typestate Builder (\`Authkestra::builder()\`). + +## Critical Rules for AI Coding Assistants + +- **Target Version**: \`authkestra = "0.13"\`. +- **RFC-001 Architecture Consolidation**: \`authkestra-core\`, \`authkestra-flow\`, \`authkestra-token\`, and \`authkestra-session\` no longer exist — they were merged into \`authkestra-engine\` (re-exported via \`authkestra::core\` and \`authkestra::store\`). +- **Removed Facade Features**: There is NO \`session\` or \`token\` feature on \`authkestra\` or \`authkestra-engine\` in \`0.13\`. Session and token machinery are always compiled into \`authkestra-engine\`. Pick a storage backend feature instead: \`memory\`, \`redis\`, \`sql-postgres\`, \`sql-mysql\`, or \`sql-sqlite\`. +- **TLS Backend**: \`rustls-aws-lc-rs\` is enabled by default. If using \`default-features = false\` with \`rustls-no-provider\`, you MUST install a \`rustls::crypto::CryptoProvider\` before constructing any Authkestra client or \`reqwest\` will panic at runtime. +- **Typestate Builder**: \`Authkestra::builder()\` returns \`Engine\` where \`S\` (session store) and \`T\` (token manager) start as \`Missing\`. Use the aliases \`AkWebAppEngine\` (sessions), \`AkApiEngine\` (tokens), or \`AkEngine\` (both) in your router state (\`#[derive(AxumState)]\` / \`#[derive(ActixState)]\`). +- **Stateless OAuth**: OAuth \`state\` and \`nonce\` live in encrypted cookies, never in the database. +- **No User Table**: Authkestra deliberately has no \`UserStore\` trait. Your application owns user/account records; Authkestra provides traits for protocol state (\`KvStore\`, \`SessionStore\`, \`CredentialStore\`, \`OpStore\`). +- **Re-Proof Gated Enrolment (\`0.13+\`)**: \`TotpAuthMethod::register_totp\`, \`WebAuthnAuthMethod::start_register\`, and \`RecoveryCodeAuthMethod::generate\` require \`(&Identity, &ReproofRequirement, ...)\` rather than a bare \`user_id: &str\` to prevent confused-deputy and stale-session escalation attacks. + +## Full Documentation Corpus + +- [Complete Single-File Documentation (llms-full.txt)](https://docs.authkestra.com/llms-full.txt): Full Markdown documentation and code examples for all Authkestra crates and flows. +- [Official Agent Skills Pack](https://github.com/Authkestra/skills): Install via \`/plugin marketplace add Authkestra/skills\`. + +## Getting Started & Core Concepts + +- [Introduction](https://docs.authkestra.com/): Overview of the embedded Rust identity engine. +- [Architecture](https://docs.authkestra.com/concepts/architecture/): The three-layer design (Engine, Extensions, Adapters). +- [Typestate Builder Pattern](https://docs.authkestra.com/concepts/typestate-builder/): Compile-time guarantees with \`Engine\`, \`AkWebAppEngine\`, \`AkApiEngine\`, and \`AkEngine\`. +- [Quickstart](https://docs.authkestra.com/guides/quickstart/): Working GitHub OAuth2 login in Axum and Actix-web. +- [Framework Integration](https://docs.authkestra.com/guides/framework-integration/): \`AuthSession\`, \`AuthToken\`, \`AxumExt\`, \`AxumStatelessExt\`, \`ActixExt\`, and \`ActixStatelessExt\`. +- [Wired Endpoints](https://docs.authkestra.com/guides/wired-endpoints/): Automatic vs. manual route wiring for \`/auth/login/{provider}\`, \`/auth/callback/{provider}\`, and \`/auth/logout\`. +- [AI Coding Assistants & Agent Auth](https://docs.authkestra.com/guides/ai-agents/): Using \`llms.txt\`, \`Authkestra/skills\`, and securing AI agents & MCP servers. + +## Authentication Flows + +- [Stateless OAuth2](https://docs.authkestra.com/providers/oauth2/): Encrypted-cookie OAuth2 with JWT issuance (\`AxumStatelessExt\`). +- [OIDC Client](https://docs.authkestra.com/providers/oidc/): Background-cached OIDC discovery (\`OidcProvider::discover\`). +- [Client Credentials](https://docs.authkestra.com/providers/client-credentials/): Machine-to-machine OAuth2 and \`private_key_jwt\` (RFC 7523). +- [Device Flow](https://docs.authkestra.com/providers/device-flow/): RFC 8628 Device Authorization Grant for CLIs and headless agents. +- [Passkeys (WebAuthn)](https://docs.authkestra.com/providers/passkeys/): \`WebAuthnAuthMethod\`, \`ReproofRequirement\`, \`PasskeyEnrolment\`, and stable UUIDv5 user handles. +- [TOTP (Authenticator Apps)](https://docs.authkestra.com/providers/totp/): RFC 6238 TOTP enrolment and step-up MFA challenges with replay tracking. +- [Magic Link](https://docs.authkestra.com/providers/magic-link/): Single-use email magic links (\`MagicLinkAuthMethod\`) with \`AtomicConsume\`. +- [Email/SMS One-Time Codes](https://docs.authkestra.com/providers/otp/): Short numeric one-time codes (\`OtpAuthMethod\`) with per-challenge attempt budgets (\`AtomicDecrement\`). +- [Recovery Codes](https://docs.authkestra.com/providers/recovery-codes/): Single-use backup authenticators (\`RecoveryCodeAuthMethod\`) with Argon2id hashing and \`ReproofRequirement\`. +- [Bot Protection (CAPTCHA)](https://docs.authkestra.com/providers/bot-protection/): Fail-closed Cloudflare Turnstile and hCaptcha verification. +- [Device Signatures](https://docs.authkestra.com/providers/device-signatures/): Per-request proof-of-possession (\`X-Signature\` + \`X-Attestation\`) with body digest hashing (\`bdh\`) via \`authkestra-devsig\`. + +## Building Servers & Policy + +- [Resource Server (API)](https://docs.authkestra.com/advanced/resource-server/): \`Guard\`, \`JwtStrategy\`, multi-issuer JWKS, DPoP (RFC 9449), and mTLS (RFC 8705). +- [OpenID Provider (OP)](https://docs.authkestra.com/advanced/op-server/): Full OIDC Provider (\`authkestra-op\`), \`OpStore\`, RFC 8693 Token Exchange, Device Code grant, and attestation issuance. +- [Device Attestation](https://docs.authkestra.com/guides/device-attestation/): Enrolling and re-issuing hardware/service keys against \`authkestra-op\`. +- [Policy Engine (Cedar)](https://docs.authkestra.com/advanced/policy-engine/): Declarative authorization with AWS Cedar (\`authkestra-policy\`). +- [Continuous Access Evaluation (SSF/CAEP)](https://docs.authkestra.com/advanced/continuous-access-evaluation/): OpenID CAEP / RFC 8417 Security Event Token ingestion (\`authkestra-ssf\`). +- [Instrumentation & Tracing](https://docs.authkestra.com/advanced/instrumentation/): Production observability with \`tracing\`. + +## Data & Storage + +- [Storage Overview](https://docs.authkestra.com/storage/overview/): Database-agnostic trait architecture. +- [KV Stores](https://docs.authkestra.com/storage/kv-store/): \`MemoryStore\` and \`RedisStore\`. +- [OP SQL Store](https://docs.authkestra.com/storage/sql-store/): Relational \`SqlxOpStore\` for PostgreSQL, MySQL, and SQLite. +- [Implementing Custom Stores](https://docs.authkestra.com/storage/implementing-stores/): Implementing \`KvStore\`, \`AtomicConsume\`, \`AtomicDecrement\`, and \`IndexedKvStore\` without TOCTOU races. +`; + +export const GET: APIRoute = async () => { + return new Response(LLMS_TXT, { + headers: { + 'Content-Type': 'text/plain; charset=utf-8', + }, + }); +};