Torii Authentication Framework

Torii is an authentication framework for Rust applications designed for developers who require complete control over user data. Unlike hosted authentication services, Torii allows you to manage your own authentication stack and maintain full data sovereignty by storing user information in your own database.

Warning: This project is in early development and is not production-ready. The API is subject to change, and the project has not undergone security audits. It should not be used in production environments.

Torii supports two distinct session token strategies:

Opaque Sessions

• Mechanism: Traditional session tokens stored in the database.
• Pros: Immediate revocation capability; server-side validation.
• Cons: Requires a database lookup for every validation.

JWT Sessions

• Mechanism: Self-contained JSON Web Tokens.
• Pros: Stateless authentication; no database lookup required for validation; supports custom claims.
• Cons: Harder to revoke immediately (requires additional logic like a blacklist). Supports various signing algorithms (HS256, HS384, HS512, RS256, etc.).

Torii provides two distinct session management strategies depending on your requirements for speed versus control:

1. Database Sessions (Default): Sessions are stored in your configured database. This allows for immediate revocation of any session (e.g., during a logout or security event) but requires a database lookup for every request.
2. JWT Sessions: Sessions use self-contained JSON Web Tokens. These are highly performant as they don't require database lookups, but they cannot be revoked before their natural expiration time.

The torii-storage-seaorm crate provides SeaORMRepositoryProvider, which implements the RepositoryProvider trait from torii-core. This allows the SeaORM storage implementation to be used directly as the data layer for the main torii::Torii authentication coordinator.

To bridge the storage to Torii, you call .into_repository_provider() on a SeaORMStorage instance, wrap it in an Arc, and pass it to torii::Torii::new().

let storage = SeaORMStorage::connect("...").await?;
let repositories = Arc::new(storage.into_repository_provider());
let torii = torii::Torii::new(repositories);

Torii uses strongly typed IDs and newtype patterns to ensure security and prevent mixing different ID types.

User Struct

Contains:

• id: UserId (Unique identifier)
• name: Option<String>
• email: String
• email_verified_at: Option<DateTime>
• created_at: DateTime
• updated_at: DateTime

Session Struct

Tracks authentication state via either opaque tokens or JWTs. Contains:

• token: SessionToken
• user_id: UserId
• user_agent: Option<String>
• ip_address: Option<String>
• created_at: DateTime
• updated_at: DateTime
• expires_at: DateTime

Torii provides several core authentication capabilities:

• Data Sovereignty: User data is stored in your own database.
• Multiple Authentication Methods: Supports Password-based auth, Social OAuth/OpenID Connect, Passkey/WebAuthn, and Magic Link authentication.
• Flexible Storage: Supports SQLite, PostgreSQL, and MySQL.
• Session Management: Offers a choice between database-backed sessions or JWT tokens.
• Type Safety: Provides strongly typed APIs with Rust's compile-time guarantees.

Torii manages two primary data entities: Users and Sessions.

Users

Users represent authenticated identities in your application. Key attributes include:

• Unique ID: A stable, immutable identifier.
• Email: The required primary identifier for the user.
• Name: An optional display name.
• Verification Status: Indicates if the user's email has been verified.
• Timestamps: Tracking for creation and last update.

Sessions

Sessions maintain the authenticated state. Key attributes include:

• Token: A secret string used to identify the session.
• User ID: The identifier of the user owning the session.
• Expiration: The timestamp when the session becomes invalid.
• Client Info: Metadata such as User Agent and IP address.

Torii supports two primary session management models:

1. Database Sessions (Default): Sessions are stored directly in your database. This allows for immediate revocation of sessions (e.g., when a user logs out or an admin terminates a session).
2. JWT Sessions: Uses self-contained JSON Web Tokens. These do not require database lookups for verification, making them highly scalable, but they are harder to revoke instantly.

Torii is an authentication framework composed of four primary architectural components:

• Torii Instance: The central coordinator responsible for managing the authentication lifecycle.
• Storage: The persistence layer for user and session data (supports SQLite, PostgreSQL, and MySQL).
• Authentication Methods: The mechanisms users use to prove identity (Password, OAuth, Passkeys, and Magic Links).
• Sessions: The mechanism that maintains a user's authenticated state after a successful login.

Torii is built on a modular, service-oriented architecture that separates business logic from data persistence:

• Services: Handle the high-level business logic for specific authentication methods (e.g., password(), oauth()).
• Repositories: Act as an abstraction layer for data access.
• Storage Backends: Implement the concrete database operations (e.g., SQLite, PostgreSQL, MySQL).
• Session Providers: Manage the lifecycle of session tokens, supporting both opaque tokens and JWTs.

This separation allows developers to swap storage backends or session management strategies without changing the core authentication logic.

Torii organizes its authentication logic into specific namespaces. Each namespace provides methods tailored to that specific authentication type:

• torii.password(): Traditional email/password authentication.
• torii.oauth(): Social login (e.g., Google, GitHub).
• torii.passkey(): Modern biometric/WebAuthn authentication.
• torii.magic_link(): Email-based passwordless login.