AuthKit

A better-auth–inspired authentication library for Rust. Plug-and-play, framework-agnostic, and opinionated yet extensible.

Overview

AuthKit is a Rust authentication library designed to feel like better-auth, but for the Rust ecosystem. It provides secure, database-backed authentication with a single, unified API that works across any context—HTTP servers, CLI tools, background workers, or proxies.

Key Features

🔒 Secure by Default - Argon2id password hashing, timing-safe comparisons, secure token generation
🎯 Single Entry Point - One Auth object for all authentication operations
🔧 Framework-Agnostic - Works with Axum, Actix, Rocket, or standalone—no framework lock-in
💾 Database-Backed - SQLite and PostgreSQL support via SQLx (hidden from API)
🚀 Simple API - Register, login, verify, logout—same API everywhere
⚡ Async-First - Built on Tokio for high-performance async operations
🎨 Extensible - Swappable password and session strategies

Quick Start

Installation

Add AuthKit to your Cargo.toml:

[dependencies]
authkit = "0.1"
tokio = { version = "1.28", features = ["full"] }

Basic Usage

use authkit::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Create an Auth instance
    let auth = Auth::builder()
        .database(Database::sqlite("auth.db").await?)
        .build()?;

    // Run migrations
    auth.migrate().await?;

    // Register a new user
    let user = auth.register(Register {
        email: "user@example.com".into(),
        password: "secure-password".into(),
    }).await?;

    println!("User registered: {}", user.email);

    // Login
    let session = auth.login(Login {
        email: "user@example.com".into(),
        password: "secure-password".into(),
    }).await?;

    println!("Session token: {}", session.token);

    // Verify a session
    let user = auth.verify(Verify {
        token: session.token.clone(),
    }).await?;

    println!("Verified user: {}", user.email);

    // Logout
    auth.logout(Logout {
        token: session.token,
    }).await?;

    println!("Logged out successfully");

    Ok(())
}

Design Philosophy

AuthKit is built around five core principles:

1. Single Entry Point

Users interact with only one object: Auth. No repositories, no generics, no leaked internals.

let auth = Auth::builder()
    .database(Database::sqlite("auth.db").await?)
    .build()?;

2. Framework-Agnostic by Design

AuthKit doesn't depend on Axum, Actix, Rocket, Hyper, or Tower. It works equally well in:

REST APIs
CLI tools
gRPC services
Proxies (Pingora)
Background workers

Framework adapters live outside the core library.

3. Opinionated Defaults, Explicit Overrides

Ships with secure defaults:

Argon2id password hashing
Database-backed sessions
Secure token generation
Sensible expiry defaults

Override behavior explicitly when needed, but never accidentally weaken security.

4. No Leaky Abstractions

AuthKit hides implementation details:

SQLx internals
Database schemas
Crypto implementations
Token formats

Users never interact with traits, repositories, lifetimes, or generic parameters in the public API.

5. Same API Everywhere

auth.register(Register { ... }).await?;
auth.login(Login { ... }).await?;
auth.verify(Verify { ... }).await?;
auth.logout(Logout { ... }).await?;

These calls behave identically whether invoked from an HTTP handler, CLI command, test, or background task.

Architecture

Auth
 └── AuthInner (Arc)
     ├── Database (trait object)
     ├── PasswordStrategy
     ├── SessionStrategy
     └── TokenStrategy

Key characteristics:

Auth is cheap to clone (uses Arc internally)
Internals are completely hidden
Components are swappable via builder pattern
No global state required

Strategy Pattern

AuthKit uses a consistent strategy pattern for all authentication components:

┌─────────────────────────────────────────────────────────┐
│                    Application Layer                    │
│  (Auth, Operations: register, login, verify, etc.)      │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ↓
┌─────────────────────────────────────────────────────────┐
│                  Strategy Layer                         │
│  • PasswordStrategy   (Argon2, Bcrypt, etc.)            │
│  • SessionStrategy    (Database-backed)                 │
│  • TokenStrategy      (Database-backed)                 │
│                                                         │
│  Strategies receive &dyn DatabaseTrait as parameter     │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ↓
┌─────────────────────────────────────────────────────────┐
│              DatabaseTrait (Abstraction)                │
│                                                         │
│  • User Operations (create, find)                       │
│  • Session Operations (create, find, delete)            │
│  • Token Operations (create, verify, mark used)         │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ↓
┌─────────────────────────────────────────────────────────┐
│            Backend Implementations                      │
│  • SqliteDatabase   (SQLite with ? params)              │
│  • PostgresDatabase (Postgres with $N params)           │
└─────────────────────────────────────────────────────────┘

Design Benefits:

Strategies remain stateless and don't store database references
Database logic is centralized in backend implementations
Easy to add new database backends (MySQL, etc.)
Easy to mock for testing
No SQLx types leak into public API

Feature Flags

AuthKit uses Cargo features for optional functionality:

[features]
default = ["sqlite", "argon2"]

# Database backends
sqlite = ["sqlx/sqlite", "sqlx/runtime-tokio"]
postgres = ["sqlx/postgres", "sqlx/runtime-tokio"]

# Password hashing strategies
argon2 = ["dep:argon2", "dep:password-hash"]
bcrypt = ["dep:bcrypt"]

# Token strategies
jwt = ["dep:jsonwebtoken"]

Examples

PostgreSQL with Argon2:

authkit = { version = "0.1", default-features = false, features = ["postgres", "argon2"] }

SQLite with bcrypt:

authkit = { version = "0.1", default-features = false, features = ["sqlite", "bcrypt"] }

Database Support

SQLite

let auth = Auth::builder()
    .database(Database::sqlite("auth.db").await?)
    .build()?;

PostgreSQL

let auth = Auth::builder()
    .database(Database::postgres("postgresql://user:pass@localhost/authdb").await?)
    .build()?;

Migrations

AuthKit manages its own schema and migrations:

auth.migrate().await?;

Database Schema:

users - User accounts with email and password
sessions - Active user sessions
tokens - Unified table for email verification, password reset, etc.

All tables include proper indexes and foreign key constraints for optimal performance and data integrity.

API Reference

Auth Operations

Register

Create a new user account:

let user = auth.register(Register {
    email: "user@example.com".into(),
    password: "secure-password".into(),
}).await?;

Validation:

Email must be valid format
Password must meet minimum security requirements
Email must be unique

Login

Authenticate and create a session:

let session = auth.login(Login {
    email: "user@example.com".into(),
    password: "secure-password".into(),
}).await?;

Returns:

Session with token, user_id, and expiration

Verify

Verify a session token and retrieve user:

let user = auth.verify(Verify {
    token: session_token,
}).await?;

Errors:

Invalid token
Expired session
Session not found

Logout

Invalidate a session:

auth.logout(Logout {
    token: session_token,
}).await?;

Send Email Verification

Generate and optionally send a verification token for a user:

// Option 1: Manual email handling (no EmailSender configured)
let verification = auth.send_email_verification(SendEmailVerification {
    user_id: user.id.clone(),
}).await?;

// You handle sending the email
send_email(&verification.email, &verification.token).await?;

// Option 2: Automatic email sending (with EmailSender configured)
// Email is sent automatically, token still returned
let verification = auth.send_email_verification(SendEmailVerification {
    user_id: user.id.clone(),
}).await?;

Returns:

VerificationToken with token, email, and expiration time
Token expires in 24 hours

Errors:

User not found
Email already verified
Email send failed (if EmailSender is configured)

Verify Email

Verify a user's email using a token:

let verified_user = auth.verify_email(VerifyEmail {
    token: verification_token,
}).await?;

Returns:

Updated User with email_verified set to true

Errors:

Invalid or expired token
Token already used
Email already verified

Resend Email Verification

Resend verification token to a user:

let verification = auth.resend_email_verification(ResendEmailVerification {
    email: "user@example.com".into(),
}).await?;

Returns:

New VerificationToken (old tokens remain valid until used or expired)

Errors:

User not found
Email already verified

Types

User

pub struct User {
    pub id: String,
    pub email: String,
    pub created_at: i64,
    pub email_verified: bool,
    pub email_verified_at: Option<i64>,
}

Session

pub struct Session {
    pub token: String,
    pub user_id: String,
    pub expires_at: i64,
}

VerificationToken

pub struct VerificationToken {
    pub token: String,
    pub email: String,
    pub expires_at: i64,
}

Email Integration

AuthKit provides a flexible email integration system that allows you to use any email service (SendGrid, AWS SES, SMTP, etc.) for sending verification emails, password reset emails, and other authentication-related emails.

Quick Start

Option 1: Manual Email Handling (Default)

By default, AuthKit generates tokens but doesn't send emails. You handle email sending:

let auth = Auth::builder()
    .database(Database::sqlite("auth.db").await?)
    .build()?;

let verification = auth.send_email_verification(SendEmailVerification {
    user_id: user.id,
}).await?;

// You send the email using your service
your_email_service::send(&verification.email, &verification.token).await?;

Option 2: Automatic Email Sending

Configure an EmailSender to send emails automatically:

use authkit::email::{EmailSender, EmailContext};
use async_trait::async_trait;

// Implement the EmailSender trait
struct MyEmailSender {
    api_key: String,
}

#[async_trait]
impl EmailSender for MyEmailSender {
    async fn send_verification_email(&self, context: EmailContext) -> Result<()> {
        let url = format!("https://myapp.com/verify?token={}", context.token);
        
        // Use your email service (SendGrid, AWS SES, SMTP, etc.)
        sendgrid::send(
            &self.api_key,
            &context.email,
            "Verify your email",
            &format!("Click here: {}", url),
        ).await?;
        
        Ok(())
    }
}

// Configure Auth with your email sender
let auth = Auth::builder()
    .database(Database::sqlite("auth.db").await?)
    .email_sender(Box::new(MyEmailSender {
        api_key: "your_api_key".to_string(),
    }))
    .build()?;

// Now emails are sent automatically
auth.send_email_verification(SendEmailVerification {
    user_id: user.id,
}).await?;

EmailSender Trait

#[async_trait]
pub trait EmailSender: Send + Sync {
    async fn send_verification_email(&self, context: EmailContext) -> Result<()>;
}

pub struct EmailContext {
    pub email: String,      // Recipient's email
    pub token: String,      // Verification token (plaintext)
    pub expires_at: i64,    // Unix timestamp
}

Example Implementations

Console Logger (Development)

struct ConsoleEmailSender {
    base_url: String,
}

#[async_trait]
impl EmailSender for ConsoleEmailSender {
    async fn send_verification_email(&self, context: EmailContext) -> Result<()> {
        println!("📧 Verify at: {}/verify?token={}", self.base_url, context.token);
        Ok(())
    }
}

SendGrid (Production)

struct SendGridEmailSender {
    api_key: String,
    from_email: String,
    base_url: String,
}

#[async_trait]
impl EmailSender for SendGridEmailSender {
    async fn send_verification_email(&self, context: EmailContext) -> Result<()> {
        let url = format!("{}/verify?token={}", self.base_url, context.token);
        
        let client = reqwest::Client::new();
        client
            .post("https://api.sendgrid.com/v3/mail/send")
            .header("Authorization", format!("Bearer {}", self.api_key))
            .json(&serde_json::json!({
                "personalizations": [{"to": [{"email": context.email}]}],
                "from": {"email": self.from_email},
                "subject": "Verify your email",
                "content": [{
                    "type": "text/html",
                    "value": format!("<a href='{}'>Verify Email</a>", url)
                }]
            }))
            .send()
            .await?;
        
        Ok(())
    }
}

Environment-Based Configuration

fn create_email_sender(env: &str) -> Box<dyn EmailSender> {
    match env {
        "production" => Box::new(SendGridEmailSender { /* ... */ }),
        "development" => Box::new(ConsoleEmailSender { /* ... */ }),
        _ => panic!("Unknown environment"),
    }
}

let auth = Auth::builder()
    .database(database)
    .email_sender(create_email_sender(&env))
    .build()?;

For detailed email integration guide, see docs/EMAIL_INTEGRATION.md.

Security

Default Security Features

Feature	Default
Password hashing	Argon2id
Timing-safe compares	✅ Enabled
Session expiration	✅ Enabled (24 hours)
Token entropy	High (cryptographically secure)
Password reuse	🚫 Prevented
Weak passwords	🚫 Rejected

Password Requirements

Minimum length: 8 characters
Must contain at least one uppercase letter
Must contain at least one lowercase letter
Must contain at least one number
Must contain at least one special character

Email Validation

RFC 5322 compliant email validation
Checks for valid format and structure

Advanced Configuration

Custom Password Strategy

use authkit::prelude::*;
use authkit::strategies::password::PasswordStrategyType;

let auth = Auth::builder()
    .database(Database::sqlite("auth.db").await?)
    .password_strategy(PasswordStrategyType::Argon2)
    .build()?;

Custom Session Strategy

use authkit::prelude::*;
use authkit::strategies::session::SessionStrategyType;

let auth = Auth::builder()
    .database(Database::sqlite("auth.db").await?)
    .session_strategy(SessionStrategyType::Database)
    .build()?;

Error Handling

AuthKit provides a comprehensive error type:

use authkit::prelude::*;

match auth.login(login_request).await {
    Ok(session) => println!("Login successful"),
    Err(AuthError::InvalidCredentials) => println!("Wrong email or password"),
    Err(AuthError::UserNotFound) => println!("User doesn't exist"),
    Err(e) => println!("Error: {}", e),
}

Examples

Check the examples/ directory for more usage examples:

email_verification.rs - Complete email verification workflow
email_sender.rs - Custom email sender implementations (SendGrid, AWS SES, SMTP, etc.)
basic.rs - Simple registration and login flow (planned)
web_server.rs - Integration with Axum (planned)
cli_tool.rs - CLI authentication example (planned)

Run an example:

cargo run --example email_verification --features sqlite
cargo run --example email_sender --features sqlite

Testing

Run the test suite:

cargo test

Run tests with all features:

cargo test --all-features

Roadmap

Current Status: Foundation Phase ✅

Implemented:

✅ Core Auth API
✅ Builder pattern
✅ SQLite backend
✅ PostgreSQL backend
✅ Argon2 password hashing
✅ Database sessions
✅ Email validation
✅ Password validation
✅ Token system (database-backed)
✅ Email verification flow (send, verify, resend)

Planned:

🔜 JWT sessions
🔜 Refresh tokens
🔜 Password reset flow
🔜 Magic link authentication
🔜 Axum adapter
🔜 Actix adapter
🔜 Rate limiting
🔜 Audit logging
🔜 OAuth integration
🔜 Two-factor authentication

Contributing

Contributions are welcome! Please read our contribution guidelines first.

For Contributors (Including AI Agents)

When contributing to AuthKit, you MUST:

✅ Preserve the single-entry-point design
✅ Avoid exposing generics or traits publicly
✅ Keep framework dependencies out of core
✅ Prefer composition over configuration
✅ Default to secure behavior

You MUST NOT:

❌ Add framework-specific logic to core
❌ Leak SQLx types into the public API
❌ Introduce global state
❌ Require users to wire repositories manually

If a change makes the API feel less like better-auth, it's probably wrong.

License

This project is dual-licensed under your choice of:

MIT License (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Acknowledgments

Inspired by better-auth - an excellent authentication library for JavaScript/TypeScript.

Support

Built with ❤️ by Akshay B

authkit 0.1.2

AuthKit

Overview

Key Features

Quick Start

Installation

Basic Usage

Design Philosophy

1. Single Entry Point

2. Framework-Agnostic by Design

3. Opinionated Defaults, Explicit Overrides

4. No Leaky Abstractions

5. Same API Everywhere

Architecture

Strategy Pattern

Feature Flags

Examples

Database Support

SQLite

PostgreSQL

Migrations

API Reference

Auth Operations

Register

Login

Verify

Logout

Send Email Verification

Verify Email

Resend Email Verification

Types

User

Session

VerificationToken

Email Integration

Quick Start

Option 1: Manual Email Handling (Default)

Option 2: Automatic Email Sending

EmailSender Trait

Example Implementations

Console Logger (Development)

SendGrid (Production)

Environment-Based Configuration

Security

Default Security Features

Password Requirements

Email Validation

Advanced Configuration

Custom Password Strategy

Custom Session Strategy

Error Handling

Examples

Testing

Roadmap

Current Status: Foundation Phase ✅

Contributing

For Contributors (Including AI Agents)

License

Contribution

Acknowledgments

Support