authbox

A lightweight, modular authentication framework for Rust built around traits, async support, and pluggable components.

It provides

• Password hashing (Argon2)
• JWT authentication (access + refresh tokens)
• Async-ready API (Tokio)
• Pluggable architecture (store, hasher, token manager)
• Fully testable design

Features

• User registration & login flow
• Secure password hashing using Argon2
• JWT access + refresh token support
• Token refresh rotation
• Custom user store support (DB or in-memory)
• Fully async (tokio + async-trait)
• Trait-based architecture for flexibility

Installation

```bash
cargo add authbox

Quick Start

1. Import prelude

use authbox::prelude::*;

2. Create JWT manager

You can use the default DefaultJwtManager or use yours by implemting the TokenManager trait For example we use the DefaultJwtManager

let tokens = DefaultJwtManager::new("my-secret-key");

3. Create password hasher

You can use the default DefaultHasher or use yours by implemting the PasswordHasher trait For example we use the DefaultJwtManager

let hasher = DefaultHasher;

4. Implement a user store

You can use your DB or in-memory store. and must implement the UserStrore<U: YourCustomUserType> and YourCustomUserType must implement the AuthUser trait;

Example:

  struct YourCustomUserType{
      id: String,
      email: String,
     password_hash: String,
    .... // Other fields
 }

  impl AuthUser for YourCustomUserType{
    fn id(&self) -> String {
        self.id.clone()
    }

    fn email(&self) -> &str {
        &self.email
    }

    fn password_hash(&self) -> &str {
        &self.password_hash
    }
}


  struct MyDbStore;  // Must implemt the  >>>> UserStrore<U: YourCustomUserType>`

impl  UserStrore<YourCustomUserType> for MyDbStore{ 
  // add concrete implemetations
    fn find_by_id(&self, user_id: &str) -> Option<YourCustomUserType>;
    fn find_by_email(&self, email: &str) -> Option<YourCustomUserType>;
    fn create_user(&mut self, email: String, pass_hash: String) -> YourCustomUserType;
}

5. Create AuthService

let store = MyDbStore::new();
let tokens = DefaultJwtManager::new("my-secret-key");
let hasher = DefaultHasher;
let mut auth = AuthService {
    store,
    hasher,
    tokens,
};

6 Register User

let user = auth
    .register::<TestUser>(
        "user@mail.com".to_string(),
        "password123".to_string(),
    )
    .await;

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

7 Login User

let login = auth
    .login::<TestUser>("user@mail.com", "password123")
    .await?;

if let Some(tokens) = login {
    println!("Access token: {}", tokens.access_token);
    println!("Refresh token: {}", tokens.refresh_token);
}

8 Refresh Token

let new_tokens = auth
    .tokens
    .refresh(refresh_token)
    .await?;

println!("New access token: {}", new_tokens.access_token);

Token Structure

pub struct AuthTokens {
    pub access_token: String,
    pub refresh_token: String,
    pub expires_in: usize,
    pub token_type: String, // "Bearer"
}

Architecture

authbox is built using traits:

AuthService

Handles business logic:

• register
• login

TokenManager

Handles JWT:

• generate
• verify
• refresh

PasswordHasher

Handles password security:

• hash
• verify

UserStore

Handles persistence:

• create user
• find user

Roadmap

• Database adapters (SQLx, MongoDB)
• Token revocation list
• Role-based access control (RBAC)
• OAuth2 integration
• Middleware for Actix / Axum
• Redis session support

License

Apache-2.0