From 57b77dc56d24c24e9bb4207ca89b8a49482deac7 Mon Sep 17 00:00:00 2001 From: Marco Kuidja Date: Sun, 15 Nov 2026 19:13:28 +0100 Subject: [PATCH 1/2] docs: update documentation and AI prompts for v0.15 --- src/components/CopyAiPrompt.astro | 2 +- .../advanced/continuous-access-evaluation.md | 16 ++--- src/content/docs/advanced/op-server.md | 9 +-- src/content/docs/advanced/policy-engine.md | 33 +++++++--- src/content/docs/advanced/resource-server.mdx | 14 +++-- src/content/docs/guides/ai-agents.md | 15 ++--- .../docs/guides/framework-integration.mdx | 4 +- src/content/docs/guides/quickstart.mdx | 4 +- 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 | 28 ++++----- src/content/docs/providers/magic-link.md | 2 +- src/content/docs/providers/oauth2.mdx | 2 +- src/content/docs/providers/oidc.md | 2 +- src/content/docs/providers/otp.md | 2 +- src/content/docs/providers/passkeys.md | 2 +- src/content/docs/providers/recovery-codes.md | 2 +- src/content/docs/providers/totp.md | 4 +- src/content/docs/storage/kv-store.md | 2 +- src/content/docs/storage/sql-store.md | 2 +- src/lib/ai-prompts.ts | 60 +++++++++---------- src/pages/llms-full.txt.ts | 2 +- src/pages/llms.txt.ts | 17 +++--- 24 files changed, 126 insertions(+), 104 deletions(-) diff --git a/src/components/CopyAiPrompt.astro b/src/components/CopyAiPrompt.astro index 67d8720..ac08652 100644 --- a/src/components/CopyAiPrompt.astro +++ b/src/components/CopyAiPrompt.astro @@ -21,7 +21,7 @@ const prompt = getAiPrompt(rawSlug); AI Coding Prompt Claude & Cursor - authkestra = "0.13" + authkestra = "0.15"
diff --git a/src/content/docs/advanced/continuous-access-evaluation.md b/src/content/docs/advanced/continuous-access-evaluation.md index bdb9be0..74401ad 100644 --- a/src/content/docs/advanced/continuous-access-evaluation.md +++ b/src/content/docs/advanced/continuous-access-evaluation.md @@ -41,9 +41,9 @@ side of that exchange. ```toml [dependencies] -authkestra = { version = "0.13", features = ["ssf", "axum", "memory"] } +authkestra = { version = "0.15", features = ["ssf", "axum", "memory"] } # or crate directly: -authkestra-ssf = "0.13" +authkestra-ssf = "0.15" jsonwebtoken = { version = "11", features = ["rust_crypto"] } ``` @@ -76,21 +76,21 @@ let receiver = PushReceiver::new(Arc::new(verifier)) In Axum, mount the standard push receiver endpoints (`POST /.well-known/ssf/events` and `POST /ssf/events`): ```rust -use authkestra_axum::ssf::ssf_routes; +use authkestra_axum::ssf::ssf_axum_router; use axum::Router; -let app = Router::new() - .merge(ssf_routes(Arc::new(receiver))); +let app: Router = Router::new() + .merge(ssf_axum_router(Arc::new(receiver))); ``` In Actix-web: ```rust -use authkestra_actix::ssf::configure_ssf; -use actix_web::{web, App}; +use authkestra_actix::ssf::ssf_actix_scope; +use actix_web::App; App::new() - .configure(|cfg| configure_ssf(cfg, Arc::new(receiver))); + .service(ssf_actix_scope(Arc::new(receiver))); ``` If you prefer custom endpoint handling, `PushReceiver::receive` is framework-agnostic: diff --git a/src/content/docs/advanced/op-server.md b/src/content/docs/advanced/op-server.md index 1214fc7..2d35bb5 100644 --- a/src/content/docs/advanced/op-server.md +++ b/src/content/docs/advanced/op-server.md @@ -15,9 +15,9 @@ Because OP Servers are an advanced use case, the OP logic is not included in the ```toml [dependencies] -authkestra = { version = "0.13", features = ["axum", "op"] } +authkestra = { version = "0.15", features = ["axum", "op"] } # Or if using Actix: -# authkestra = { version = "0.13", features = ["actix", "op"] } +# authkestra = { version = "0.15", features = ["actix", "op"] } ``` ## The OpStore Interface @@ -69,10 +69,7 @@ let op_store: Arc = Arc::new(CompositeOpSto A handler clones the store once per request and drops the clone when the request ends. `Clone` here has to mean "a new handle onto the same underlying state" — never "an independent copy of the data". A naive `#[derive(Clone)]` over a plain `HashMap` field, for example, compiles and satisfies `CloneableOpStore`, but every write a handler makes disappears with that request's clone: the code `/authorize` stores would never be visible to the following `/token` exchange, which would always fail with `invalid_grant` — no compile error, no log, no failing test. Put mutable in-memory state behind `Arc>`/`Arc>` (as `authkestra_op::MemoryClientAssertionStore` and `authkestra_engine::store::memory::MemoryStore` do), or use a connection-pool handle that is already cheap-clone-shares-state by construction. ::: -`CompositeOpStore` carries two further, optional slots for the replay guards above — supply them -with `.with_client_assertion_store(...)` and `.with_dpop_replay_store(...)`. Left unset they resolve -to `NoClientAssertionStore` / `NoDpopReplayStore`, which are the fail-closed defaults described in -the caution box. +`CompositeOpStore` carries optional slots for replay guards and rotating DPoP nonces: supply `.with_client_assertion_store(...)`, `.with_dpop_replay_store(...)`, and `.with_dpop_nonces(...)` (`DpopNonces`). Left unset, the replay guards resolve to `NoClientAssertionStore` / `NoDpopReplayStore`, which are the fail-closed defaults described in the caution box. Client registrations also support `allowed_audiences` for explicit audience scoping (`resource` / RFC 8707) and custom `amr`/`acr` claims via `amr_acr_extra_claims`. :::tip[Overriding Refresh Token Logic] The `OpStore` interface allows overriding `handle_refresh_token` for custom refresh token rotation or revocation policies. When the `openid` scope is requested during the refresh flow, Authkestra automatically issues an updated `id_token` alongside the new access token. diff --git a/src/content/docs/advanced/policy-engine.md b/src/content/docs/advanced/policy-engine.md index 248b1ef..64bfc91 100644 --- a/src/content/docs/advanced/policy-engine.md +++ b/src/content/docs/advanced/policy-engine.md @@ -17,9 +17,9 @@ review, diff and reload, instead of in `if role == "admin"` branches scattered a ```toml [dependencies] -authkestra = { version = "0.13", features = ["policy"] } +authkestra = { version = "0.15", features = ["policy"] } # or the crate on its own: -authkestra-policy = "0.13" +authkestra-policy = "0.15" ``` ## The one rule: the engine never touches your database @@ -171,24 +171,41 @@ caveats. ### Axum & Actix Route Protection -When the `policy` feature is enabled on `authkestra-axum` or `authkestra-actix`, wrap your routes with `PolicyGuard`: +When the `policy` feature is enabled on `authkestra-axum` or `authkestra-actix`, store `Arc` in application state and pull it into handlers via `AuthPolicyGuard`. `PolicyGuard::new(engine)` uses `DefaultPrincipalMapper`, formatting principals as `User::"{provider}:{external_id}"` (percent-encoding `%` and `:` to prevent delimiter collisions): ```rust use std::sync::Arc; -use authkestra::policy::CedarPolicyEngine; -use authkestra::axum::PolicyGuard; -use axum::{routing::get, Router}; +use authkestra::policy::PolicyEngine; +use authkestra::axum::policy::AuthPolicyGuard; +use authkestra_resource::PolicyGuard; +use axum::{extract::Path, routing::get, Router}; let policy_engine = Arc::new( - CedarPolicyEngine::builder() + PolicyEngine::builder() .policies(policy_source) .loader(loader) .build()?, ); +let guard = Arc::new(PolicyGuard::new(policy_engine)); + +async fn get_document( + Path(id): Path, + AuthPolicyGuard(guard): AuthPolicyGuard, +) -> Result<&'static str, axum::http::StatusCode> { + let decision = guard + .authorize(&identity, "read", &format!(r#"Doc::"{id}""#), None) + .await + .map_err(|_| axum::http::StatusCode::INTERNAL_SERVER_ERROR)?; + if decision.is_allowed() { + Ok("ok") + } else { + Err(axum::http::StatusCode::FORBIDDEN) + } +} let app = Router::new() .route("/api/documents/:id", get(get_document)) - .layer(PolicyGuard::new(policy_engine.clone())); + .with_state(guard); ``` ### Resource Server & MCP Tool Enforcement diff --git a/src/content/docs/advanced/resource-server.mdx b/src/content/docs/advanced/resource-server.mdx index 8a87262..5848866 100644 --- a/src/content/docs/advanced/resource-server.mdx +++ b/src/content/docs/advanced/resource-server.mdx @@ -18,9 +18,9 @@ Like the OP Server, the Resource Server is an advanced component and is not incl ```toml [dependencies] -authkestra = { version = "0.13", features = ["axum", "resource"] } +authkestra = { version = "0.15", features = ["axum", "resource"] } # Or if using Actix: -# authkestra = { version = "0.13", features = ["actix", "resource"] } +# authkestra = { version = "0.15", features = ["actix", "resource"] } ``` ### TLS Backend Selection @@ -29,7 +29,7 @@ Outbound HTTP requests for JWKS discovery require a TLS backend. Authkestra enab ```toml [dependencies] -authkestra-resource = { version = "0.13", default-features = false, features = ["rustls-no-provider"] } +authkestra-resource = { version = "0.15", default-features = false, features = ["rustls-no-provider"] } ``` ## Building with Authkestra Guard @@ -122,9 +122,15 @@ let config = ValidationConfig::builder() let strategy = JwtStrategy::::new(config) // Required: the default `NoDpopReplayStore` refuses every DPoP-bound token. - .with_dpop_replay_store(Arc::new(my_replay_store)); + .with_dpop_replay_store(Arc::new(my_replay_store)) + // Optional: enforce rotating DPoP nonces (RFC 9449 §8/§9) + .with_dpop_nonces(dpop_nonces) + // Optional: enforce RFC 9470 step-up auth (`acr_values` / `max_age`) + .with_step_up(StepUpRequirement::new().max_age(300)); ``` +Failed DPoP nonce checks or step-up requirements produce structured `ResourceRefusal` challenges (`DPoP-Nonce` header on `use_dpop_nonce` or `WWW-Authenticate` with `insufficient_user_authentication` per RFC 9470) via `resource_refusal_response`. + :::caution[`require_dpop` without a replay store rejects everything] `JwtStrategy` starts with the fail-closed `NoDpopReplayStore`, which refuses every proof. That is intentional — DPoP without single-use `jti` tracking gives no replay protection while looking like diff --git a/src/content/docs/guides/ai-agents.md b/src/content/docs/guides/ai-agents.md index 21e595f..211b3f6 100644 --- a/src/content/docs/guides/ai-agents.md +++ b/src/content/docs/guides/ai-agents.md @@ -29,14 +29,15 @@ Install the official [Authkestra skill pack](https://github.com/Authkestra/skill | 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-quickstart` | End-to-end Axum/Actix setup, TLS backend selection, typestate builder, and extractor wiring (`v0.15`). | | `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-op` | Running an embedded OpenID Provider: PKCE, DPoP (`DpopNonces`), `private_key_jwt`, Device Flow, and RFC 8693 Token Exchange. | +| `authkestra-resource-server` | Protecting APIs and MCP servers with `Guard`, multi-issuer JWKS, DPoP, mTLS, and RFC 9470 `StepUpRequirement`. | +| `authkestra-mfa` | Passkeys (WebAuthn), TOTP (`claim_totp_step`), Magic Links, OTP, Recovery Codes, `ReproofRequirement`, and `authkestra-devsig` profile v1. | +| `authkestra-mcp` | Embedded MCP server security tiers, JCS parameter binding, human step-up approval, and `EncryptedKvTokenVault`. | +| `authkestra-upgrade` | Migrating from pre-RFC-001 crates (`authkestra-core`, `authkestra-flow`, `authkestra-session`, `authkestra-token`) and upgrading to `0.15` APIs. | | `authkestra-troubleshoot` | Resolving `rustls` CryptoProvider panics, cross-site OAuth cookie drops, and clock skew. | --- @@ -47,11 +48,11 @@ Enable the `mcp` feature on the `authkestra` facade crate (or depend on `authkes ```toml [dependencies] -authkestra = { version = "0.13", features = ["axum", "mcp", "memory"] } +authkestra = { version = "0.15", features = ["axum", "mcp", "memory"] } ``` ### Three Composable Security Tiers (`McpSecurityTier`) -Register tools on `McpRouter::builder()` with per-tool security policies: +Register tools on `McpRouter::builder()` with per-tool security policies (unverified identity headers are rejected by default via `allow_unverified_identity_header(false)`): - **`McpSecurityTier::Public`**: Callable without authentication (or with optional caller identity). - **`McpSecurityTier::Scoped { required_scopes }`**: Validates Bearer or DPoP-bound tokens via `authkestra-resource`, returning RFC 9728 `WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource"` on `401 Unauthorized` and `insufficient_scope` on `403 Forbidden`. - **`McpSecurityTier::HumanApproved { required_scopes, reproof, approval_ttl_secs }`**: Requires both scope validation and a single-use cryptographic step-up human approval bound to the exact tool name and canonicalized arguments. diff --git a/src/content/docs/guides/framework-integration.mdx b/src/content/docs/guides/framework-integration.mdx index afab5f3..3b75d73 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", "memory"] } +authkestra = { version = "0.15", features = ["axum", "memory"] } ``` @@ -23,7 +23,7 @@ authkestra = { version = "0.13", features = ["axum", "memory"] } ```toml [dependencies] -authkestra = { version = "0.13", features = ["actix", "macros", "memory"] } +authkestra = { version = "0.15", features = ["actix", "macros", "memory"] } ``` diff --git a/src/content/docs/guides/quickstart.mdx b/src/content/docs/guides/quickstart.mdx index 2900e62..bf1e2b1 100644 --- a/src/content/docs/guides/quickstart.mdx +++ b/src/content/docs/guides/quickstart.mdx @@ -16,7 +16,7 @@ Add the `authkestra` facade crate to your `Cargo.toml`. The facade re-exports al ```toml [dependencies] -authkestra = { version = "0.13", features = ["axum", "memory", "github"] } +authkestra = { version = "0.15", features = ["axum", "memory", "github"] } tower-cookies = "0.11" tokio = { version = "1", features = ["full"] } ``` @@ -26,7 +26,7 @@ tokio = { version = "1", features = ["full"] } ```toml [dependencies] -authkestra = { version = "0.13", features = ["actix", "macros", "memory", "github"] } +authkestra = { version = "0.15", features = ["actix", "macros", "memory", "github"] } actix-web = "4" ``` diff --git a/src/content/docs/providers/bot-protection.md b/src/content/docs/providers/bot-protection.md index 88ff09e..c349d37 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 = { version = "0.13", features = ["captcha"] } +authkestra = { version = "0.15", features = ["captcha"] } ``` ## Configuration diff --git a/src/content/docs/providers/client-credentials.md b/src/content/docs/providers/client-credentials.md index 2f79e82..b5d5271 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.13" +authkestra-engine = "0.15" tokio = { version = "1", features = ["full"] } ``` diff --git a/src/content/docs/providers/device-flow.md b/src/content/docs/providers/device-flow.md index 2f774e4..7cb305a 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.13" +authkestra-engine = "0.15" tokio = { version = "1", features = ["full"] } ``` diff --git a/src/content/docs/providers/device-signatures.mdx b/src/content/docs/providers/device-signatures.mdx index 99a37ff..77a1ec1 100644 --- a/src/content/docs/providers/device-signatures.mdx +++ b/src/content/docs/providers/device-signatures.mdx @@ -18,35 +18,30 @@ Add the `authkestra-devsig` crate to your dependencies: ```toml [dependencies] -authkestra = { version = "0.13", features = ["axum", "devsig"] } +authkestra = { version = "0.15", features = ["axum", "devsig"] } # Or with Actix: -# authkestra = { version = "0.13", features = ["actix", "devsig"] } +# authkestra = { version = "0.15", features = ["actix", "devsig"] } ``` ## How to use `authkestra-devsig` The easiest way to use `authkestra-devsig` is via the official web framework integrations (`authkestra-axum` and `authkestra-actix`). These integrations provide ready-to-use middleware that intercepts requests, buffers the body to compute the required `bdh` (body digest hash), and verifies the signatures before your route handlers are ever executed. -### 1. Building the Verifier State +### 1. Building the Verifier State (Profile v1) -To start, construct the `DevSig` configuration state using the unified typestate builder. You will need a `VerifierConfig`, an `IssuerJwks` (a JWKS cache of the issuers trusted to mint attestations), and a `ReplayStore` (to protect against replay attacks). +To start, construct the `DevSig` configuration state using the unified typestate builder. `VerifierConfig::profile_v1` configures the standard device-signature profile v1 defaults (`ES256`/`EdDSA`, `RECOMMENDED_CLOCK_SKEW`, `MAX_SIGNATURE_LIFETIME`), alongside an `IssuerJwks` cache and a `ReplayStore`: ```rust use authkestra_devsig::{DevSig, InMemoryReplayStore, IssuerJwks, ReplayStore, VerifierConfig}; use jsonwebtoken::Algorithm; use std::sync::Arc; -use std::time::Duration; -// `VerifierConfig` is `#[non_exhaustive]`, so build it with `new(...)` rather than a -// struct literal. Arguments, in order: -// trusted_issuers, allowed_algs, max_clock_skew, max_signature_lifetime, audience -let config = VerifierConfig::new( +// Profile v1 constructor (trusted_issuers, audience); customize device signing algs via `.with_device_algs(...)`. +let config = VerifierConfig::profile_v1( ["https://op.example.test"], - [Algorithm::ES256, Algorithm::EdDSA], - Duration::from_secs(5), - Duration::from_secs(60), "https://api.example.test", -); +) +.with_device_algs([Algorithm::EdDSA, Algorithm::ES256]); // The JWKS cache does no network I/O of its own — populate it with // `jwks.insert(issuer, kid, jwk).await` from wherever you fetch and refresh keys. @@ -60,8 +55,13 @@ let devsig = DevSig::builder() .build(); ``` +Profile v1 enforces strict request binding and uniform refusals: +- `qsh` and `bdh` claims must be present when the request has a query string or body, and omitted when absent. +- The attestation `att` claim carries `status` and an optional `KeyRole` (`KeyRole::Ambient` or `KeyRole::UserPresent`) surfaced on `DeviceIdentity.role`. +- Failed verifications return a structured JSON refusal (`{"error":""}`) with `WWW-Authenticate: DeviceSignature error=""`. + :::caution -`allowed_algs` is asymmetric-only. `VerifierConfig::new` silently drops any HMAC algorithm you +`allowed_algs` and `device_algs` are asymmetric-only. `VerifierConfig` silently drops any HMAC algorithm you pass, and `verify()` rejects the whole HMAC family regardless — the device's private key never leaves the device, so there is no symmetric secret a verifier could legitimately share. ::: diff --git a/src/content/docs/providers/magic-link.md b/src/content/docs/providers/magic-link.md index 9ca12b4..2e1cd77 100644 --- a/src/content/docs/providers/magic-link.md +++ b/src/content/docs/providers/magic-link.md @@ -11,7 +11,7 @@ To use magic links, enable the `magic-link` feature in your `Cargo.toml`: ```toml [dependencies] -authkestra-engine = { version = "0.13", features = ["magic-link"] } +authkestra-engine = { version = "0.15", features = ["magic-link"] } ``` ## Configuration diff --git a/src/content/docs/providers/oauth2.mdx b/src/content/docs/providers/oauth2.mdx index 19ab08d..7af25d8 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", "github", "google"] } +authkestra = { version = "0.15", features = ["axum", "github", "google"] } ``` ## Stateless Engine Configuration diff --git a/src/content/docs/providers/oidc.md b/src/content/docs/providers/oidc.md index e081783..779b3e0 100644 --- a/src/content/docs/providers/oidc.md +++ b/src/content/docs/providers/oidc.md @@ -11,7 +11,7 @@ To use the OIDC client, enable the `oidc` feature on the `authkestra` crate. ```toml [dependencies] -authkestra = { version = "0.13", features = ["oidc", "memory"] } +authkestra = { version = "0.15", features = ["oidc", "memory"] } ``` ## Configuring the OIDC Provider diff --git a/src/content/docs/providers/otp.md b/src/content/docs/providers/otp.md index df3692d..1acd73d 100644 --- a/src/content/docs/providers/otp.md +++ b/src/content/docs/providers/otp.md @@ -11,7 +11,7 @@ To use OTP, enable the `otp` feature in your `Cargo.toml`. The example below als ```toml [dependencies] -authkestra-engine = { version = "0.13", features = ["otp", "memory"] } +authkestra-engine = { version = "0.15", features = ["otp", "memory"] } ``` ## Registering the Method diff --git a/src/content/docs/providers/passkeys.md b/src/content/docs/providers/passkeys.md index c6b23d5..f3ac9cb 100644 --- a/src/content/docs/providers/passkeys.md +++ b/src/content/docs/providers/passkeys.md @@ -11,7 +11,7 @@ To use Passkeys, enable the `webauthn` feature in your `Cargo.toml` (either on t ```toml [dependencies] -authkestra = { version = "0.13", features = ["webauthn"] } +authkestra = { version = "0.15", features = ["webauthn"] } ``` ## Configuration diff --git a/src/content/docs/providers/recovery-codes.md b/src/content/docs/providers/recovery-codes.md index 57db0f4..149b995 100644 --- a/src/content/docs/providers/recovery-codes.md +++ b/src/content/docs/providers/recovery-codes.md @@ -11,7 +11,7 @@ To use recovery codes, enable the `recovery-codes` feature in your `Cargo.toml`: ```toml [dependencies] -authkestra-engine = { version = "0.13", features = ["recovery-codes"] } +authkestra-engine = { version = "0.15", features = ["recovery-codes"] } ``` ## Configuration diff --git a/src/content/docs/providers/totp.md b/src/content/docs/providers/totp.md index b0c993c..bfa3225 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 = { version = "0.13", features = ["totp"] } +authkestra = { version = "0.15", features = ["totp"] } ``` ## Configuration @@ -79,4 +79,4 @@ let result = engine.authenticate(AuthInput::MfaChallenge { ### Built-in Replay Protection -Authkestra strictly adheres to [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238). It automatically tracks the highest `last_used_step` in the credential store, preventing the exact same code from being submitted more than once within the validity window. This completely mitigates replay attacks! +Authkestra strictly adheres to [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238). It atomically claims the active time step via `CredentialStore::claim_totp_step`, ensuring the exact same code cannot be accepted twice under concurrent requests or anywhere within the drift window. diff --git a/src/content/docs/storage/kv-store.md b/src/content/docs/storage/kv-store.md index 0282888..0aef054 100644 --- a/src/content/docs/storage/kv-store.md +++ b/src/content/docs/storage/kv-store.md @@ -11,7 +11,7 @@ Authkestra includes built-in generic KV stores (`memory` and `redis`), forwarded ```toml [dependencies] -authkestra = { version = "0.13", features = ["axum", "redis"] } +authkestra = { version = "0.15", features = ["axum", "redis"] } ``` ### 1. Memory Store (`memory`) diff --git a/src/content/docs/storage/sql-store.md b/src/content/docs/storage/sql-store.md index ad570c7..2a9e6ec 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.13", features = ["postgres"] } +authkestra-store-sqlx = { version = "0.15", features = ["postgres"] } # or mysql, sqlite ``` diff --git a/src/lib/ai-prompts.ts b/src/lib/ai-prompts.ts index 1260a2e..6eb3e97 100644 --- a/src/lib/ai-prompts.ts +++ b/src/lib/ai-prompts.ts @@ -4,104 +4,104 @@ * Maps every documentation slug (across concepts/, guides/, providers/, advanced/, storage/, and root index) * to a tailored, context-specific prompt for AI coding assistants (Claude, Cursor, etc.). * - * Target: authkestra = "0.13" + * Target: authkestra = "0.15" * Reference: https://docs.authkestra.com/llms-full.txt */ export const AI_PROMPTS: Record = { // Root index / Introduction index: - 'Implement an authentication stack using Authkestra v0.13 (authkestra = "0.13"). Configure the typestate builder Authkestra::builder() with Axum (features = ["axum", "memory", "github"]). Note that session and token state start as Missing at compile time and require a concrete store (e.g. MemoryStore or RedisStore) plus a cookie encryption key before calling .build(). Use AkWebAppEngine in your Axum router state and inject AuthSession into protected handlers. Refer to the complete documentation at https://docs.authkestra.com/llms-full.txt.', + 'Implement an authentication stack using Authkestra v0.15 (authkestra = "0.15"). Configure the typestate builder Authkestra::builder() with Axum (features = ["axum", "memory", "github"]). Note that session and token state start as Missing at compile time and require a concrete store (e.g. MemoryStore or RedisStore) plus a cookie encryption key (or SessionConfig::new for multi-replica keys) before calling .build(). Use AkWebAppEngine in your Axum router state and inject AuthSession into protected handlers. Refer to the complete documentation at https://docs.authkestra.com/llms-full.txt.', // Concepts 'concepts/architecture': - "Architect a modular identity service using Authkestra v0.13 (authkestra = \"0.13\"). Follow Authkestra's three-layer architecture: authkestra-engine (pure framework-agnostic core), extensions (authkestra-providers, authkestra-oidc, authkestra-policy, authkestra-ssf, authkestra-mcp), and adapters (authkestra-axum / authkestra-actix). Never create a UserStore trait — Authkestra has no user table; your application owns user records while Authkestra manages protocol state via KvStore, SessionStore, and OpStore. Refer to https://docs.authkestra.com/llms-full.txt.", + "Architect a modular identity service using Authkestra v0.15 (authkestra = \"0.15\"). Follow Authkestra's three-layer architecture: authkestra-engine (pure framework-agnostic core), extensions (authkestra-providers, authkestra-oidc, authkestra-policy, authkestra-ssf, authkestra-mcp), and adapters (authkestra-axum / authkestra-actix). Never create a UserStore trait: Authkestra has no user table; your application owns user records while Authkestra manages protocol state via KvStore, SessionStore, CredentialStore, and OpStore. Refer to https://docs.authkestra.com/llms-full.txt.", 'concepts/typestate-builder': - 'Construct an Authkestra v0.13 (authkestra = "0.13") engine enforcing compile-time safety with the typestate builder pattern. Call Authkestra::builder() which initializes Engine. Supply a session store to transition to Engine (AkWebAppEngine), a token manager for Engine (AkApiEngine), or both for Engine (AkEngine). Calling .build() while required type parameters remain Missing is rejected by the Rust compiler. Derive AxumState or ActixState on your application router state. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Construct an Authkestra v0.15 (authkestra = "0.15") engine enforcing compile-time safety with the typestate builder pattern. Call Authkestra::builder() which initializes Engine. Supply a session store to transition to Engine (AkWebAppEngine), a token manager for Engine (AkApiEngine), or both for Engine (AkEngine). Calling .build() while required type parameters remain Missing is rejected by the Rust compiler. Derive AxumState or ActixState on your application router state. Refer to https://docs.authkestra.com/llms-full.txt.', // Guides 'guides/quickstart': - 'Implement an end-to-end GitHub OAuth2 login flow using Authkestra v0.13 (authkestra = "0.13", features = ["axum", "memory", "github"]). Initialize Authkestra::builder() with MemoryStore::new(), configure GitHubProvider with client credentials and scopes, set an encryption key with cookie_key(), and mount auth routes with .with_auth_routes(). Protect an Axum endpoint by extracting AuthSession and verify user authentication. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement an end-to-end GitHub OAuth2 login flow using Authkestra v0.15 (authkestra = "0.15", features = ["axum", "memory", "github"]). Initialize Authkestra::builder() with MemoryStore::new(), configure GithubProvider with client credentials, configure SessionConfig::new(key) for stable session cookies across restarts/replicas, and mount auth routes with .axum_router(). Protect an Axum endpoint by extracting AuthSession. Refer to https://docs.authkestra.com/llms-full.txt.', 'guides/framework-integration': - 'Integrate Authkestra v0.13 (authkestra = "0.13", features = ["axum"] or ["actix"]) into a web application router. Wrap Arc in your application state using #[derive(AxumState)] or #[derive(ActixState)]. Extract AuthSession for cookie/session-based web apps or AuthToken for bearer JWT API routes. Use AxumExt / ActixExt to wire automatic /auth/login/{provider}, /auth/callback/{provider}, and /auth/logout routes with encrypted cookie state. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Integrate Authkestra v0.15 (authkestra = "0.15", features = ["axum"] or ["actix"]) into a web application router. Wrap AkWebAppEngine in your application state using #[derive(AxumState)] or #[derive(ActixState)]. Extract AuthSession for cookie/session-based web apps or AuthToken / Auth for bearer JWT API routes. Use AxumExt / ActixExt to wire automatic /auth/login/{provider}, /auth/callback/{provider}, and POST /auth/logout routes with encrypted cookie state. Refer to https://docs.authkestra.com/llms-full.txt.', 'guides/wired-endpoints': - 'Configure and customize Authkestra v0.13 (authkestra = "0.13", features = ["axum", "memory"]) standard endpoints. Use AxumExt::with_auth_routes or manual route wiring for /auth/login/:provider, /auth/callback/:provider, and /auth/logout. Ensure CSRF protection via encrypted state cookies without database lookups. Use stateless_auth_routes() for stateless OAuth2 JWT flows. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Configure and customize Authkestra v0.15 (authkestra = "0.15", features = ["axum", "memory"]) standard endpoints. Use AxumExt::axum_router or manual route wiring for /auth/login/:provider, /auth/callback/:provider, and POST /auth/logout. Ensure CSRF protection via encrypted state cookies without database lookups. Use axum_router_stateless() for stateless OAuth2 JWT flows. Refer to https://docs.authkestra.com/llms-full.txt.', 'guides/ai-agents': - 'Secure AI agents and Model Context Protocol (MCP) servers using Authkestra v0.13 (authkestra = "0.13", features = ["mcp", "passkeys", "axum"]). Use McpRouter to define tool endpoints across three security tiers: McpSecurityTier::Public, McpSecurityTier::Scoped, and McpSecurityTier::HumanApproved. For sensitive tools, bind parameters cryptographically using RFC 8785 JSON Canonicalization Scheme (JCS) SHA-256 digests and require a human biometric passkey step-up pulse before dispensing downstream OAuth tokens from EncryptedKvTokenVault (AES-256-GCM). Refer to https://docs.authkestra.com/llms-full.txt.', + 'Secure AI agents and Model Context Protocol (MCP) servers using Authkestra v0.15 (authkestra = "0.15", features = ["mcp", "webauthn", "axum"]). Use McpRouter::builder() to define tool endpoints across three security tiers: McpSecurityTier::Public, McpSecurityTier::Scoped, and McpSecurityTier::HumanApproved (with allow_unverified_identity_header(false) by default and optional with_policy_engine). For sensitive tools, bind parameters cryptographically using RFC 8785 JSON Canonicalization Scheme (JCS) SHA-256 digests and require a human biometric passkey step-up before dispensing downstream OAuth tokens from EncryptedKvTokenVault (AES-256-GCM). Refer to https://docs.authkestra.com/llms-full.txt.', 'guides/device-attestation': - 'Implement cryptographic device attestation and key issuance using Authkestra v0.13 (authkestra = "0.13", features = ["op", "devsig", "axum"]). Configure DeviceIdentity with hardware-backed Ed25519 or ECDSA keys. Enforce per-request signatures (X-Signature and X-Attestation) with body digest hashing (bdh) against an Authkestra OpenID Provider verifying RFC 8693 token exchange. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement cryptographic device attestation and key issuance using Authkestra v0.15 (authkestra = "0.15", features = ["op", "devsig", "axum"]). Configure hardware-backed Ed25519 or ECDSA keys with authkestra-devsig profile v1 (VerifierConfig::profile_v1). Enforce per-request signatures (X-Signature and X-Attestation) with query/body digest rules (qsh/bdh) against an Authkestra OpenID Provider verifying RFC 8693 token exchange. Refer to https://docs.authkestra.com/llms-full.txt.', // Authentication Flows / Providers 'providers/oauth2': - 'Implement stateless OAuth2 authentication with Authkestra v0.13 (authkestra = "0.13", features = ["axum", "memory"]). Use AxumStatelessExt with encrypted cookie state and nonce validation to issue signed JWTs upon successful OAuth callback without writing session records to a database. Configure JwtStrategy for token verification. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement stateless OAuth2 authentication with Authkestra v0.15 (authkestra = "0.15", features = ["axum", "memory"]). Use AxumStatelessExt with encrypted cookie state and nonce validation to issue signed JWTs upon successful OAuth callback without writing session records to a database. Configure JwtStrategy for token verification. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/oidc': - 'Configure an OpenID Connect (OIDC) client in Authkestra v0.13 (authkestra = "0.13", features = ["oidc", "axum", "memory"]). Use OidcProvider::discover to asynchronously fetch and background-cache provider metadata from .well-known/openid-configuration. Validate ID tokens using the provider\'s JWKS key set, enforce nonce binding, and map claims to an authenticated AuthSession. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Configure an OpenID Connect (OIDC) client in Authkestra v0.15 (authkestra = "0.15", features = ["oidc", "axum", "memory"]). Use OidcProvider::discover to asynchronously fetch and background-cache provider metadata from .well-known/openid-configuration. Validate ID tokens using the provider\'s JWKS key set, enforce nonce binding, and map claims to an authenticated AuthSession. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/client-credentials': - 'Implement the OAuth 2.0 Client Credentials grant for machine-to-machine (M2M) communication using Authkestra v0.13 (authkestra = "0.13", features = ["engine", "axum"]). Support both client_secret_post/basic and asymmetric private_key_jwt (RFC 7523) client assertion authentication. Validate scopes and issue scoped AuthToken access tokens without human session overhead. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement the OAuth 2.0 Client Credentials grant for machine-to-machine (M2M) communication using Authkestra v0.15 (authkestra = "0.15", features = ["engine", "axum"]). Support both client_secret_post/basic and asymmetric private_key_jwt (RFC 7523) client assertion authentication. Validate scopes and issue scoped AuthToken access tokens without human session overhead. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/device-flow': - 'Implement the RFC 8628 OAuth 2.0 Device Authorization Grant for headless CLIs and input-constrained devices using Authkestra v0.13 (authkestra = "0.13", features = ["op", "axum", "memory"]). Issue user_code and device_code with verification_uri, handle client polling with slow_down / authorization_pending status codes, and issue tokens once approved in a browser session. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement the RFC 8628 OAuth 2.0 Device Authorization Grant for headless CLIs and input-constrained devices using Authkestra v0.15 (authkestra = "0.15", features = ["op", "axum", "memory"]). Issue user_code and device_code with verification_uri, handle client polling with slow_down / authorization_pending status codes, and issue tokens once approved in a browser session. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/passkeys': - 'Implement FIDO2 / WebAuthn passkey authentication using Authkestra v0.13 (authkestra = "0.13", features = ["webauthn", "axum", "memory"]). Use WebAuthnAuthMethod with CredentialStore. In v0.13, enforce re-proof gated enrolment: start_register requires (&Identity, &ReproofRequirement) to prevent confused-deputy attacks. Generate stable UUIDv5 user handles to prevent PII leakage to authenticators and validate origin and RP ID. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement FIDO2 / WebAuthn passkey authentication using Authkestra v0.15 (authkestra = "0.15", features = ["webauthn", "axum", "memory"]). Use WebAuthnAuthMethod with CredentialStore and enforce re-proof gated enrolment: start_register requires (&Identity, &ReproofRequirement) to prevent confused-deputy attacks. Generate stable UUIDv5 user handles to prevent PII leakage to authenticators and validate origin and RP ID. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/totp': - 'Implement Time-based One-Time Password (TOTP, RFC 6238) MFA in Authkestra v0.13 (authkestra = "0.13", features = ["totp", "axum", "memory"]). In v0.13, register_totp requires (&Identity, &ReproofRequirement) to ensure the user re-authenticates before enrolling an authenticator app. Validate 6-digit codes with replay attack prevention and configurable drift windows. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement Time-based One-Time Password (TOTP, RFC 6238) MFA in Authkestra v0.15 (authkestra = "0.15", features = ["totp", "axum", "memory"]). register_totp requires (&Identity, &ReproofRequirement) to ensure the user re-authenticates before enrolling an authenticator app. Validate 6-digit codes with atomic replay protection via CredentialStore::claim_totp_step and configurable drift windows. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/magic-link': - 'Implement passwordless email magic link authentication using Authkestra v0.13 (authkestra = "0.13", features = ["engine", "memory", "axum"]). Use MagicLinkAuthMethod backed by a store implementing AtomicConsume to ensure single-use consumption and eliminate TOCTOU race conditions when links are scanned by email security filters. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement passwordless email magic link authentication using Authkestra v0.15 (authkestra = "0.15", features = ["engine", "memory", "axum"]). Use MagicLinkAuthMethod backed by a store implementing AtomicConsume to ensure single-use consumption and eliminate TOCTOU race conditions when links are scanned by email security filters. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/otp': - 'Implement email or SMS one-time passcode (OTP) authentication in Authkestra v0.13 (authkestra = "0.13", features = ["engine", "memory", "axum"]). Use OtpAuthMethod backed by a KvStore implementing AtomicDecrement to enforce strict per-challenge attempt limits, fail closed on exhaustion, and enforce short expiration TTLs. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement email or SMS one-time passcode (OTP) authentication in Authkestra v0.15 (authkestra = "0.15", features = ["engine", "memory", "axum"]). Use OtpAuthMethod backed by a KvStore implementing AtomicDecrement to enforce strict per-challenge attempt limits, fail closed on exhaustion, and enforce short expiration TTLs. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/recovery-codes': - 'Implement backup recovery code authentication in Authkestra v0.13 (authkestra = "0.13", features = ["engine", "memory", "axum"]). Use RecoveryCodeAuthMethod with Argon2id cryptographic hashing. In v0.13, generating recovery codes requires (&Identity, &ReproofRequirement). Consuming a recovery code requires AtomicConsume to guarantee single-use invalidation. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement backup recovery code authentication in Authkestra v0.15 (authkestra = "0.15", features = ["engine", "memory", "axum"]). Use RecoveryCodeAuthMethod with Argon2id cryptographic hashing. Generating recovery codes requires (&Identity, &ReproofRequirement), and consuming a code requires AtomicConsume to guarantee single-use invalidation. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/bot-protection': - 'Integrate CAPTCHA and bot protection into authentication flows using Authkestra v0.13 (authkestra = "0.13", features = ["engine", "axum"]). Use TurnstileVerifier or HCaptchaVerifier to validate client challenge tokens fail-closed before processing credential submission or triggering expensive password hashing. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Integrate CAPTCHA and bot protection into authentication flows using Authkestra v0.15 (authkestra = "0.15", features = ["engine", "captcha", "axum"]). Use TurnstileVerifier or HCaptchaVerifier to validate client challenge tokens fail-closed before processing credential submission or triggering expensive password hashing. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/device-signatures': - 'Implement cryptographic request signing using Authkestra v0.13 (authkestra = "0.13", features = ["devsig", "axum"]). Enforce proof-of-possession on HTTP requests via X-Signature and X-Attestation headers. Use SignedRequest to verify Ed25519/ECDSA signatures over method, path, timestamp, and body digest hash (bdh) to protect APIs against MITM and replay attacks. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement cryptographic request signing using Authkestra v0.15 (authkestra = "0.15", features = ["devsig", "axum"]). Enforce device-signature profile v1 proof-of-possession via X-Signature and X-Attestation headers with VerifierConfig::profile_v1, optional separate device_algs, KeyRole (Ambient / UserPresent), qsh/bdh binding, and JSON {"error":""} refusals. Refer to https://docs.authkestra.com/llms-full.txt.', // Building Servers & Advanced 'advanced/resource-server': - 'Build a secure OAuth 2.0 Resource Server using Authkestra v0.13 (authkestra = "0.13", features = ["resource", "axum"]). Use Guard with JwtStrategy to validate Bearer tokens across multiple issuer JWKS endpoints. Enforce sender-constrained tokens via DPoP (RFC 9449) and mTLS (RFC 8705). Integrate with CedarPolicyEngine for fine-grained attribute-based access control. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Build a secure OAuth 2.0 Resource Server using Authkestra v0.15 (authkestra = "0.15", features = ["resource", "axum"]). Use Guard with JwtStrategy to validate Bearer tokens across multiple issuer JWKS endpoints (including nbf and strict issuer checks). Enforce sender-constrained tokens via DPoP (RFC 9449, with DpopNonces) and mTLS (RFC 8705), RFC 9470 StepUpRequirement challenges, and CedarPolicyEngine ABAC. Refer to https://docs.authkestra.com/llms-full.txt.', 'advanced/op-server': - "Deploy a full OpenID Connect Provider (OP) using Authkestra v0.13 (authkestra = \"0.13\", features = [\"op\", \"sql-postgres\", \"axum\"]). Configure OpConfig and SqlxOpStore to serve discovery metadata at .well-known/openid-configuration, authorization endpoint, token endpoint with RFC 8693 Token Exchange, and RFC 8628 Device Authorization Grant. Refer to https://docs.authkestra.com/llms-full.txt.", + "Deploy a full OpenID Connect Provider (OP) using Authkestra v0.15 (authkestra = \"0.15\", features = [\"op\", \"sql-postgres\", \"axum\"]). Configure OpConfig, ClientRegistration (with allowed_audiences), and SqlxOpStore or CompositeOpStore (with DpopNonces) to serve discovery metadata at .well-known/openid-configuration, authorization endpoint, token endpoint with RFC 8693 Token Exchange, and RFC 8628 Device Authorization Grant. Refer to https://docs.authkestra.com/llms-full.txt.", 'advanced/policy-engine': - 'Implement declarative Attribute-Based Access Control (ABAC) using AWS Cedar with Authkestra v0.13 (authkestra = "0.13", features = ["policy", "axum"]). Use CedarPolicyEngine (authkestra_policy::PolicyEngine) with AuthorizationRequest and a custom ResourceLoader (e.g. MemoryResourceLoader or DB loader). Note that the engine performs no direct I/O and fails closed with PolicyError::UnreliableDecision if an erroring forbid policy is skipped. Wire into Axum/Actix guards and MCP tool execution. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement declarative Attribute-Based Access Control (ABAC) using AWS Cedar with Authkestra v0.15 (authkestra = "0.15", features = ["policy", "axum"]). Use CedarPolicyEngine (authkestra_policy::PolicyEngine) and PolicyGuard (User::"{provider}:{external_id}" principals with percent-encoded : and %) with AuthorizationRequest and a ResourceLoader. Note that the engine performs no direct I/O and fails closed with PolicyError::UnreliableDecision if an erroring forbid policy is skipped. Refer to https://docs.authkestra.com/llms-full.txt.', 'advanced/continuous-access-evaluation': - 'Implement OpenID Shared Signals Framework (SSF) and Continuous Access Evaluation Profile (CAEP) push event receiver in Authkestra v0.13 (authkestra = "0.13", features = ["ssf", "axum", "memory"]). Wire PushReceiver to handle POST /.well-known/ssf/events and POST /ssf/events. Configure SetVerifier with RFC 8417 Security Event Token validation and attach SessionRevocationHandler to automatically revoke matching sessions in SessionStore upon receiving SessionRevoked or CredentialChange events. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement OpenID Shared Signals Framework (SSF) and Continuous Access Evaluation Profile (CAEP) push event receiver in Authkestra v0.15 (authkestra = "0.15", features = ["ssf", "axum", "memory"]). Wire PushReceiver with ssf_axum_router / ssf_actix_scope to handle POST /.well-known/ssf/events and POST /ssf/events. Configure SetVerifier with RFC 8417 Security Event Token validation and attach SessionRevocationHandler (optionally with SessionSubjectResolver) to revoke sessions upon SessionRevoked or CredentialChange events. Refer to https://docs.authkestra.com/llms-full.txt.', 'advanced/instrumentation': - 'Configure production observability for Authkestra v0.13 (authkestra = "0.13", features = ["engine", "axum"]). Leverage built-in tracing spans and events emitted across authentication ceremonies, OAuth handshakes, and Cedar policy evaluation. Ensure span attributes never leak PII or plaintext credentials while logging decision reasons and policy IDs. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Configure production observability for Authkestra v0.15 (authkestra = "0.15", features = ["engine", "axum"]). Leverage built-in tracing spans and events emitted across authentication ceremonies, OAuth handshakes, and Cedar policy evaluation. Ensure span attributes never leak PII or plaintext credentials while logging decision reasons and policy IDs. Refer to https://docs.authkestra.com/llms-full.txt.', // Storage 'storage/overview': - 'Design storage backends for Authkestra v0.13 (authkestra = "0.13", features = ["memory", "redis", "sql-postgres"]). Implement database-agnostic traits: SessionStore for user sessions, KvStore for short-lived protocol state (PKCE, magic links, OTP), CredentialStore for WebAuthn/TOTP secrets, and OpStore for OpenID Provider entities. Authkestra has no user table trait; your application schema owns user records outright. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Design storage backends for Authkestra v0.15 (authkestra = "0.15", features = ["memory", "redis", "sql-postgres"]). Implement database-agnostic traits: SessionStore for user sessions, KvStore for short-lived protocol state (PKCE, magic links, OTP), CredentialStore (including claim_totp_step) for WebAuthn/TOTP secrets, and OpStore for OpenID Provider entities. Authkestra has no user table trait; your application schema owns user records outright. Refer to https://docs.authkestra.com/llms-full.txt.', 'storage/kv-store': - 'Configure key-value storage in Authkestra v0.13 (authkestra = "0.13", features = ["memory"] or ["redis"]). Use MemoryStore for development and testing, or RedisStore for production distributed caching. Store ephemeral OAuth state, magic link tokens, and rate-limiting counters with strict TTL expiration and atomic operations. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Configure key-value storage in Authkestra v0.15 (authkestra = "0.15", features = ["memory"] or ["redis"]). Use MemoryStore for development and testing, or RedisStore for production distributed caching. Store ephemeral OAuth state, magic link tokens, and rate-limiting counters with strict TTL expiration and atomic operations. Refer to https://docs.authkestra.com/llms-full.txt.', 'storage/sql-store': - "Implement relational database storage for Authkestra v0.13's OpenID Provider (authkestra = \"0.13\", features = [\"op\", \"sql-postgres\"] or [\"sql-mysql\"] / [\"sql-sqlite\"]). Use SqlxOpStore to persist OAuth2 clients, authorization codes, refresh tokens, and consent grants with connection pooling and transactional integrity. Refer to https://docs.authkestra.com/llms-full.txt.", + "Implement relational database storage for Authkestra v0.15's OpenID Provider (authkestra = \"0.15\", features = [\"op\", \"sql-postgres\"] or [\"sql-mysql\"] / [\"sql-sqlite\"]). Use SqlxOpStore to persist OAuth2 clients, authorization codes, refresh tokens, and consent grants with connection pooling and transactional integrity. Refer to https://docs.authkestra.com/llms-full.txt.", 'storage/implementing-stores': - 'Implement custom storage traits for Authkestra v0.13 (authkestra = "0.13", features = ["engine"]). Implement KvStore, AtomicConsume (for single-use tokens like magic links and recovery codes), and AtomicDecrement (for OTP attempt throttling) without TOCTOU race conditions. Implement SessionStore for session persistence. Ensure all storage errors are cleanly mapped to StoreError. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement custom storage traits for Authkestra v0.15 (authkestra = "0.15", features = ["engine"]). Implement KvStore, AtomicConsume (for single-use tokens like magic links and recovery codes), AtomicDecrement (for OTP attempt throttling), CredentialStore::claim_totp_step, and SessionStore without TOCTOU race conditions. Ensure all storage errors are cleanly mapped to StoreError. Refer to https://docs.authkestra.com/llms-full.txt.', }; export const FALLBACK_AI_PROMPT = - 'Build a secure authentication and authorization solution using Authkestra v0.13 (authkestra = "0.13"). Configure the compile-time typestate builder Authkestra::builder() with Axum (features = ["axum", "memory"]) or Actix-web (features = ["actix", "memory"]). Inject session and protocol stores before invoking .build() and extract AuthSession or AuthToken in your route handlers. Refer to the complete documentation corpus at https://docs.authkestra.com/llms-full.txt.'; + 'Build a secure authentication and authorization solution using Authkestra v0.15 (authkestra = "0.15"). Configure the compile-time typestate builder Authkestra::builder() with Axum (features = ["axum", "memory"]) or Actix-web (features = ["actix", "memory"]). Inject session and protocol stores before invoking .build() and extract AuthSession or AuthToken in your route handlers. Refer to the complete documentation corpus at https://docs.authkestra.com/llms-full.txt.'; /** * Normalizes an arbitrary documentation slug or pathname into a canonical key. diff --git a/src/pages/llms-full.txt.ts b/src/pages/llms-full.txt.ts index 20e4bf5..bcbed81 100644 --- a/src/pages/llms-full.txt.ts +++ b/src/pages/llms-full.txt.ts @@ -58,7 +58,7 @@ export const GET: APIRoute = async () => { ]; const sections: string[] = [ - '# Authkestra — Complete Documentation Corpus (v0.13)', + '# Authkestra Complete Documentation Corpus (v0.15)', '', '> Source: https://docs.authkestra.com | Index: https://docs.authkestra.com/llms.txt | Crate: https://crates.io/crates/authkestra | Skills: https://github.com/Authkestra/skills', '', diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts index 4c3df46..67f0414 100644 --- a/src/pages/llms.txt.ts +++ b/src/pages/llms.txt.ts @@ -1,21 +1,22 @@ import type { APIRoute } from 'astro'; -const LLMS_TXT = `# Authkestra (v0.13) +const LLMS_TXT = `# Authkestra (v0.15) -> 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()\`). +> 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/RFC 9470 step-up), OpenID Connect Provider (OP with RFC 8693 Token Exchange & Device Flow), Model Context Protocol (MCP) tool security (\`authkestra-mcp\`), 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\`. +- **Target Version**: \`authkestra = "0.15"\`. +- **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\`. 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\`. Use \`webauthn\` (not \`passkeys\`) for passkey support. - **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)]\`). +- **Session Keys & TOTP Replay (\`0.15+\`)**: \`SessionConfig::default()\` generates a fresh CSPRNG 32-byte key per call (use \`SessionConfig::new\` for shared keys across replicas), and \`CredentialStore::claim_totp_step\` provides atomic TOTP replay rejection. - **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. -- **Production Cedar Policy Wiring (\`policy\`)**: \`CedarPolicyEngine\` (\`authkestra-policy\`) evaluates declarative AWS Cedar policies. The engine does zero I/O and fetches entities through \`ResourceLoader\`. An erroring forbid policy fails closed with \`PolicyError::UnreliableDecision\`. Fully wired into \`authkestra-axum\` and \`authkestra-actix\` (\`PolicyGuard\`), \`authkestra-resource\`, and \`authkestra-mcp\` tool execution with structured \`tracing\` logs. -- **Production Shared Signals / CAEP Wiring (\`ssf\`)**: \`PushReceiver\` (\`authkestra-ssf\`) ingests RFC 8417 Security Event Tokens and OpenID CAEP events. Wire push endpoints in Axum and Actix via \`POST /.well-known/ssf/events\` and \`POST /ssf/events\`. The built-in \`SessionRevocationHandler\` automatically revokes matching sessions in \`SessionStore\` upon receiving \`SessionRevoked\` or \`CredentialChange\` events. +- **Re-Proof Gated Enrolment**: \`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. +- **Production Cedar Policy Wiring (\`policy\`)**: \`CedarPolicyEngine\` (\`authkestra-policy\`) evaluates declarative AWS Cedar policies. The engine does zero I/O and fetches entities through \`ResourceLoader\`. An erroring forbid policy fails closed with \`PolicyError::UnreliableDecision\`. Wired into \`authkestra-resource\` (\`PolicyGuard\` with \`User::"{provider}:{external_id}"\` principals), \`authkestra-axum\`/\`authkestra-actix\` (\`AuthPolicyGuard\`), and \`authkestra-mcp\`. +- **Production Shared Signals / CAEP Wiring (\`ssf\`)**: \`PushReceiver\` (\`authkestra-ssf\`) ingests RFC 8417 Security Event Tokens and OpenID CAEP events. Mount push endpoints via \`ssf_axum_router\` / \`ssf_actix_scope\` (\`POST /.well-known/ssf/events\` and \`POST /ssf/events\`). \`SessionRevocationHandler\` automatically revokes matching sessions in \`SessionStore\` upon receiving \`SessionRevoked\` or \`CredentialChange\` events. ## Full Documentation Corpus From edbb51824cf28ba1ead2c46ed9f08bae0c7a90cf Mon Sep 17 00:00:00 2001 From: Marco Kuidja Date: Sun, 15 Nov 2026 19:42:29 +0100 Subject: [PATCH 2/2] docs: address CodeRabbit review feedback for v0.15 APIs --- src/content/docs/advanced/policy-engine.md | 22 ++++++++++++++----- src/content/docs/advanced/resource-server.mdx | 3 ++- .../docs/providers/device-signatures.mdx | 2 +- src/content/docs/providers/totp.md | 4 ++++ src/lib/ai-prompts.ts | 6 ++--- 5 files changed, 27 insertions(+), 10 deletions(-) diff --git a/src/content/docs/advanced/policy-engine.md b/src/content/docs/advanced/policy-engine.md index 64bfc91..40bcd3a 100644 --- a/src/content/docs/advanced/policy-engine.md +++ b/src/content/docs/advanced/policy-engine.md @@ -18,7 +18,9 @@ review, diff and reload, instead of in `if role == "admin"` branches scattered a ```toml [dependencies] authkestra = { version = "0.15", features = ["policy"] } -# or the crate on its own: +# Required when wiring PolicyGuard in Axum / Actix route handlers: +authkestra-resource = { version = "0.15", features = ["policy"] } +# or the policy crate on its own: authkestra-policy = "0.15" ``` @@ -175,25 +177,35 @@ When the `policy` feature is enabled on `authkestra-axum` or `authkestra-actix`, ```rust use std::sync::Arc; +use authkestra::axum::{policy::AuthPolicyGuard, AuthSession, AxumState}; +use authkestra::core::AkWebAppEngine; use authkestra::policy::PolicyEngine; -use authkestra::axum::policy::AuthPolicyGuard; use authkestra_resource::PolicyGuard; use axum::{extract::Path, routing::get, Router}; +#[derive(Clone, AxumState)] +struct AppState { + #[authkestra(engine)] + auth: AkWebAppEngine, + #[authkestra(store)] + policy_guard: Arc, +} + let policy_engine = Arc::new( PolicyEngine::builder() .policies(policy_source) .loader(loader) .build()?, ); -let guard = Arc::new(PolicyGuard::new(policy_engine)); +let policy_guard = Arc::new(PolicyGuard::new(policy_engine)); async fn get_document( Path(id): Path, + AuthSession(session): AuthSession, AuthPolicyGuard(guard): AuthPolicyGuard, ) -> Result<&'static str, axum::http::StatusCode> { let decision = guard - .authorize(&identity, "read", &format!(r#"Doc::"{id}""#), None) + .authorize(&session.identity, "read", &format!(r#"Doc::"{id}""#), None) .await .map_err(|_| axum::http::StatusCode::INTERNAL_SERVER_ERROR)?; if decision.is_allowed() { @@ -205,7 +217,7 @@ async fn get_document( let app = Router::new() .route("/api/documents/:id", get(get_document)) - .with_state(guard); + .with_state(AppState { auth, policy_guard }); ``` ### Resource Server & MCP Tool Enforcement diff --git a/src/content/docs/advanced/resource-server.mdx b/src/content/docs/advanced/resource-server.mdx index 5848866..ca4ca7f 100644 --- a/src/content/docs/advanced/resource-server.mdx +++ b/src/content/docs/advanced/resource-server.mdx @@ -112,6 +112,7 @@ binding claim at all: against this server's own origin. ```rust +use authkestra_resource::StepUpRequirement; use std::sync::Arc; let config = ValidationConfig::builder() @@ -126,7 +127,7 @@ let strategy = JwtStrategy::::new(config) // Optional: enforce rotating DPoP nonces (RFC 9449 §8/§9) .with_dpop_nonces(dpop_nonces) // Optional: enforce RFC 9470 step-up auth (`acr_values` / `max_age`) - .with_step_up(StepUpRequirement::new().max_age(300)); + .with_step_up(StepUpRequirement::new().with_max_age(300)); ``` Failed DPoP nonce checks or step-up requirements produce structured `ResourceRefusal` challenges (`DPoP-Nonce` header on `use_dpop_nonce` or `WWW-Authenticate` with `insufficient_user_authentication` per RFC 9470) via `resource_refusal_response`. diff --git a/src/content/docs/providers/device-signatures.mdx b/src/content/docs/providers/device-signatures.mdx index 77a1ec1..a4fd63a 100644 --- a/src/content/docs/providers/device-signatures.mdx +++ b/src/content/docs/providers/device-signatures.mdx @@ -57,7 +57,7 @@ let devsig = DevSig::builder() Profile v1 enforces strict request binding and uniform refusals: - `qsh` and `bdh` claims must be present when the request has a query string or body, and omitted when absent. -- The attestation `att` claim carries `status` and an optional `KeyRole` (`KeyRole::Ambient` or `KeyRole::UserPresent`) surfaced on `DeviceIdentity.role`. +- The attestation `att` claim carries `status` and an optional `KeyRole` (`KeyRole::Ambient` or `KeyRole::UserPresent`) surfaced via `identity.key_role()` (which reads `att.role` and returns `KeyRole::Ambient` when absent or unrecognized). - Failed verifications return a structured JSON refusal (`{"error":""}`) with `WWW-Authenticate: DeviceSignature error=""`. :::caution diff --git a/src/content/docs/providers/totp.md b/src/content/docs/providers/totp.md index bfa3225..b367d4f 100644 --- a/src/content/docs/providers/totp.md +++ b/src/content/docs/providers/totp.md @@ -80,3 +80,7 @@ let result = engine.authenticate(AuthInput::MfaChallenge { ### Built-in Replay Protection Authkestra strictly adheres to [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238). It atomically claims the active time step via `CredentialStore::claim_totp_step`, ensuring the exact same code cannot be accepted twice under concurrent requests or anywhere within the drift window. + +:::note[Custom `CredentialStore` migration (`v0.15+`)] +Custom `CredentialStore` implementations must override `claim_totp_step` with atomic compare-and-advance semantics (`matched_step > last_used_step`). The trait's default implementation returns `AuthError::Unsupported`, causing matching TOTP logins to fail until updated. +::: diff --git a/src/lib/ai-prompts.ts b/src/lib/ai-prompts.ts index 6eb3e97..c06ea2c 100644 --- a/src/lib/ai-prompts.ts +++ b/src/lib/ai-prompts.ts @@ -56,13 +56,13 @@ export const AI_PROMPTS: Record = { 'Implement Time-based One-Time Password (TOTP, RFC 6238) MFA in Authkestra v0.15 (authkestra = "0.15", features = ["totp", "axum", "memory"]). register_totp requires (&Identity, &ReproofRequirement) to ensure the user re-authenticates before enrolling an authenticator app. Validate 6-digit codes with atomic replay protection via CredentialStore::claim_totp_step and configurable drift windows. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/magic-link': - 'Implement passwordless email magic link authentication using Authkestra v0.15 (authkestra = "0.15", features = ["engine", "memory", "axum"]). Use MagicLinkAuthMethod backed by a store implementing AtomicConsume to ensure single-use consumption and eliminate TOCTOU race conditions when links are scanned by email security filters. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement passwordless email magic link authentication using Authkestra v0.15 (authkestra = "0.15", features = ["magic-link", "memory", "axum"]). Use MagicLinkAuthMethod backed by a store implementing AtomicConsume to ensure single-use consumption and eliminate TOCTOU race conditions when links are scanned by email security filters. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/otp': - 'Implement email or SMS one-time passcode (OTP) authentication in Authkestra v0.15 (authkestra = "0.15", features = ["engine", "memory", "axum"]). Use OtpAuthMethod backed by a KvStore implementing AtomicDecrement to enforce strict per-challenge attempt limits, fail closed on exhaustion, and enforce short expiration TTLs. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement email or SMS one-time passcode (OTP) authentication in Authkestra v0.15 (authkestra = "0.15", features = ["otp", "memory", "axum"]). Use OtpAuthMethod backed by a KvStore implementing AtomicDecrement to enforce strict per-challenge attempt limits, fail closed on exhaustion, and enforce short expiration TTLs. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/recovery-codes': - 'Implement backup recovery code authentication in Authkestra v0.15 (authkestra = "0.15", features = ["engine", "memory", "axum"]). Use RecoveryCodeAuthMethod with Argon2id cryptographic hashing. Generating recovery codes requires (&Identity, &ReproofRequirement), and consuming a code requires AtomicConsume to guarantee single-use invalidation. Refer to https://docs.authkestra.com/llms-full.txt.', + 'Implement backup recovery code authentication in Authkestra v0.15 (authkestra = "0.15", features = ["recovery-codes", "memory", "axum"]). Use RecoveryCodeAuthMethod with Argon2id cryptographic hashing. Generating recovery codes requires (&Identity, &ReproofRequirement), and consuming a code requires AtomicConsume to guarantee single-use invalidation. Refer to https://docs.authkestra.com/llms-full.txt.', 'providers/bot-protection': 'Integrate CAPTCHA and bot protection into authentication flows using Authkestra v0.15 (authkestra = "0.15", features = ["engine", "captcha", "axum"]). Use TurnstileVerifier or HCaptchaVerifier to validate client challenge tokens fail-closed before processing credential submission or triggering expensive password hashing. Refer to https://docs.authkestra.com/llms-full.txt.',