Authkestra

authkestra is a modular, framework-agnostic authentication orchestration system designed to be idiomatic to Rust, emphasizing explicit control flow, strong typing, and composability over dynamic middleware strategies common in other ecosystems.

📦 Getting Started

The easiest way to use Authkestra is via the authkestra facade crate. It re-exports all sub-crates behind feature flags, allowing you to manage your authentication stack from a single dependency.

Add this to your Cargo.toml:

[dependencies]
# Use the facade with the features you need
authkestra = { version = "0.2.4", features = ["axum", "github"] }

For advanced users, individual crates are still available and can be used independently if preferred.

🚀 Features

• Modular & Unified Core: Following our RFC-001 architecture, core concerns are unified in authkestra-engine while adapters like authkestra-axum and authkestra-actix provide seamless framework integrations.
• Stateless OAuth: OAuth state and nonce are stored securely in encrypted cookies—never in your database—keeping your architecture clean and horizontally scalable.
• Performant OIDC Discovery: OIDC discovery documents are cached via background tokio::spawn tasks, completely eliminating per-request latency for fetching keys.
• Database Agnostic: Authkestra never enforces schemas. All data access is strictly defined via traits (e.g., UserStore, SessionStore), allowing you to use any database or ORM.
• Flexible Chaining: Chain multiple authentication strategies (Token, Session, Basic, Custom) seamlessly.
• OpenID Connect Provider (OP): Build your own identity provider and authorization server using authkestra-op.
• Session Management: Built-in support for in-memory, Redis, and SQL via sqlx.

📦 Workspace Crates

🛠️ Usage

Authkestra utilizes a powerful Typestate Builder Pattern (Engine::builder()). This enforces at compile-time that certain methods are only available if their prerequisites are met (e.g., you can only call session methods if a SessionStore was provided).

Quick Start Example

use authkestra::flow::{Engine, OAuth2Flow};
use authkestra_providers::github::GithubProvider;

// The builder ensures compile-time safety for your authentication stack
let github_provider = GithubProvider::new(client_id, client_secret, redirect_uri);

let auth_engine = Engine::builder()
    .provider(OAuth2Flow::new(github_provider))
    .session_store(session_store)
    .build();

To see complete, runnable examples for various frameworks and flows, check out the examples directory:

• Axum Basic Setup: cargo run --example axum_basic_setup
• Actix Basic Setup: cargo run --example actix_basic_setup
• Axum with GitHub OAuth: cargo run --example axum_oauth2_github
• Axum with Google OIDC: cargo run --example axum_oidc_google
• Axum with Redis Session: cargo run --example axum_session_redis
• Axum with SQL Store: cargo run --example axum_sql_store
• Client Credentials Flow: cargo run --example core_client_credentials
• Device Flow: cargo run --example core_device_flow
• Axum Resource Server: cargo run --example axum_resource_server
• Axum OP Server: cargo run --example axum_op_server

🏗️ Technical Design Principles

Our architecture enforces strict design principles to guarantee compile-time safety and optimal Developer Experience (DX):

• Typestate Builder Pattern: The Engine::builder() uses Rust's typestate pattern. This makes misconfigurations a compile-time error rather than a runtime surprise.
• Trait Objects over Generics: For I/O bound paths, we prefer Box<dyn Trait> (e.g., Box<dyn AuthMethod>) over heavy monomorphized generics. This drastically optimizes compilation times without sacrificing meaningful runtime performance.
• Framework Agnostic Core: The authkestra-engine is pure Rust logic. Axum and Actix integrations are entirely isolated in separate adapter crates, utilizing explicit Extractors like AuthSession(session).
• Plugin Interfaces: We extend functionality via strict plugin interfaces (AuthMethod, Flow) rather than opaque, ordering-dependent middleware.
• Production-Ready Tracing: Every handler, endpoint, and logical branch is deeply instrumented with the tracing crate, ensuring request flows and errors are fully visible in production without code changes.

📜 License

This project is dual-licensed under either:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.