ace-auth 1.2.0 → 1.2.1

package/README.md

@@ -1,7 +1,7 @@
 # 🛡️ AceAuth
 
-> **Stateful Security, Stateless Speed.**  
-> An enterprise-grade identity management library featuring "Graceful Token Rotation," Device Fingerprinting, and Sliding Window sessions.
+> **Stateful security. Stateless speed.**  
+> A production-grade authentication engine that combines JWT performance with server-side control using a hybrid, cache-aware architecture.
 
 [![NPM Version](https://img.shields.io/npm/v/ace-auth?style=flat-square)](https://www.npmjs.com/package/ace-auth)
 ![TypeScript](https://img.shields.io/badge/Language-TypeScript-blue?style=flat-square)
@@ -12,22 +12,47 @@
 
 ## 💡 Why AceAuth?
 
-In modern web development, you typically have to choose between **Security** (short-lived JWTs) and **User Experience** (long-lived sessions).  
+Most authentication systems force a trade-off:
 
-**AceAuth gives you both.** It uses a **Hybrid Architecture** to maintain security without forcing users to log in repeatedly.
+- **Stateless JWTs** → Fast, scalable, but impossible to revoke  
+- **Server sessions** → Secure and controllable, but harder to scale  
 
-| Feature         | Standard JWT                  | AceAuth                     |
-|------------------|-------------------------------|-----------------------------|
-| **Revocation**   | ❌ Impossible until expiry    | ✅ **Instant** (DB Backed)  |
-| **Performance**  | ✅ High (Stateless)           | ✅ **High** (Redis Caching) |
-| **UX**           | ❌ Hard Logout on expiry      | ✅ **Graceful Auto-Rotation** |
-| **Device Mgmt**  | ❌ None                       | ✅ **Active Sessions View** |
+**AceAuth removes this trade-off.**
+
+AceAuth uses:
+- **JWTs as identifiers (not authority)**
+- **A database as the source of truth**
+- **A two-tier cache (RAM + DB) for performance**
+
+This allows AceAuth to provide:
+- Immediate revocation
+- Transparent token rotation
+- High throughput on hot paths
+- Explicit, documented trade-offs
 
 ---
 
-## 📦 Installation
+## 🧠 Architecture Overview
+
+```
+Client
+  ↓
+JWT (sessionId only)
+  ↓
+L1 Cache (RAM, short TTL)
+  ↓
+L2 Store (Redis / SQL / Mongo)
+```
+
+- **Hot path**: Served entirely from RAM  
+- **Cold path**: Falls back to database  
+- **Writes**: Throttled to avoid load amplification  
+
+Bounded inconsistency window: **≤ cacheTTL (default: 2 seconds)**
 
-Install AceAuth via npm:
+---
+
+## 📦 Installation
 
 ```bash
 npm install ace-auth
@@ -37,186 +62,238 @@ npm install ace-auth
 
 ## 🚀 Quick Start
 
-### 1. Initialize
-
-AceAuth is database-agnostic. Below is a standard production setup using Redis:
+### 1️⃣ Initialize AceAuth
 
-```typescript
-import { AceAuth, RedisStore } from 'ace-auth';
-import { createClient } from 'redis';
+AceAuth is storage-agnostic. You can plug in any supported database adapter.
 
-// 1. Connect to Redis
-const redis = createClient();
-await redis.connect();
+```ts
+import { AceAuth } from 'ace-auth';
 
-// 2. Initialize Auth Engine
 const auth = new AceAuth({
-    secret: process.env.JWT_SECRET || 'super-secret',
-    store: new RedisStore(redis),
-    sessionDuration: 30 * 24 * 60 * 60, // 30 Days (Sliding Window)
-    tokenDuration: '15m',               // Rotate token every 15 mins
-    smtp: {                             // Optional: For Email OTP
-        host: 'smtp.example.com',
-        auth: { user: '...', pass: '...' }
-    }
+  secret: process.env.JWT_SECRET!,
+  store: yourStore,
+  sessionDuration: 30 * 24 * 60 * 60, // 30 days
+  tokenDuration: '15m',
+  cacheTTL: 2000
 });
 ```
 
-### 2. Login (Capture Device Info)
-
-Pass the request object (`req`) so AceAuth can fingerprint the device (IP/User-Agent).
-
-```typescript
-import express from 'express';
-const app = express();
+---
 
-app.post('/api/login', async (req, res) => {
-    // ... validate user credentials first ...
-    const userId = 'user_123'; 
+## 🔐 Authentication Flow
 
-    // Create Session & Token
-    const { token, sessionId } = await auth.login({ id: userId, role: 'admin' }, req);
+### Login
 
-    res.json({ token });
-});
+```ts
+const { token, sessionId } = await auth.login(
+  { id: user.id, role: 'user' },
+  req
+);
 ```
 
-### 3. Protect Routes (Middleware)
+- Creates a session in the database
+- Stores session in L1 cache
+- Issues a short-lived JWT (identifier only)
+
+---
 
-Use the included gatekeeper middleware to secure endpoints. It automatically handles Graceful Expiration.
+### Protect Routes (Middleware)
 
-```typescript
+```ts
 import { gatekeeper } from 'ace-auth/middleware';
 
-app.get('/api/profile', gatekeeper(auth), (req, res) => {
-    // If token was rotated, the new one is in res.headers['x-ace-token']
-    res.json({ message: `Hello User ${req.user.id}` });
+app.get('/profile', gatekeeper(auth), (req, res) => {
+  res.json({ user: req.user });
 });
 ```
 
+If a token expires but the session is valid, AceAuth **automatically rotates it** and returns a new token via:
+
+```
+X-Ace-Token: <new-token>
+```
+
 ---
 
-## 🔌 Database Adapters
+## 🔌 Database Adapters (Full Implementations)
+
+AceAuth works with any persistent store implementing `IStore`.
+
+---
 
-AceAuth works with any database. Import the specific adapter you need.
+## 🟥 Redis Adapter (Recommended)
 
-### Redis (Recommended for Speed)
+### When to use
+- High traffic APIs
+- Real-time systems
+- Horizontally scaled services
 
-Uses Secondary Indexing (Sets) to map Users ↔ Sessions for O(1) lookups.
+### Setup
 
-```typescript
+```ts
+import { createClient } from 'redis';
 import { RedisStore } from 'ace-auth/adapters';
-// Requires 'redis' package installed
-const store = new RedisStore(redisClient);
+
+const redis = createClient();
+await redis.connect();
+
+const store = new RedisStore(redis);
 ```
 
-### PostgreSQL (Persistent)
+### How it works
+- Sessions stored as `sessionId → payload`
+- Secondary index: `userId → set(sessionIds)`
+- TTL enforced by Redis
+- O(1) lookup for session revocation
+
+---
 
-Requires a table with columns: `sid` (text), `sess` (json), `expired_at` (timestamp).
+## 🟦 PostgreSQL Adapter
 
-```typescript
-import { PostgresStore } from 'ace-auth/adapters';
-// Requires 'pg' pool
-const store = new PostgresStore(pool, 'auth_sessions_table');
+### When to use
+- Strong consistency requirements
+- Existing SQL infrastructure
+- Auditable session history
+
+### Schema
+
+```sql
+CREATE TABLE auth_sessions (
+  sid TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  sess JSONB NOT NULL,
+  expires_at TIMESTAMP NOT NULL
+);
+
+CREATE INDEX idx_auth_sessions_user
+ON auth_sessions(user_id);
 ```
 
-### MongoDB
+### Setup
+
+```ts
+import { Pool } from 'pg';
+import { PostgresStore } from 'ace-auth/adapters';
 
-Stores sessions as documents. Good for no-setup environments.
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 
-```typescript
-import { MongoStore } from 'ace-auth/adapters';
-// Requires 'mongoose' connection
-const store = new MongoStore(mongoose.connection.collection('sessions'));
+const store = new PostgresStore(pool, 'auth_sessions');
 ```
 
----
+### Notes
+- Expired sessions are lazily cleaned
+- Indexed by `user_id` for fast logout-all
+- Suitable for compliance-heavy systems
 
-## 🧠 Advanced Features
+---
 
-### 📱 Device Management Dashboard
+## 🟩 MongoDB Adapter
 
-Allow users to see all their logged-in devices and remotely log them out (like Netflix/Google).
+### When to use
+- Document-based stacks
+- Rapid prototyping
+- Flexible schemas
 
-```typescript
-// GET /api/devices
-app.get('/api/devices', gatekeeper(auth), async (req, res) => {
-    const sessions = await auth.getActiveSessions(req.user.id);
-    res.json(sessions);
-});
+### Schema (Example)
 
-// POST /api/devices/logout-all
-app.post('/api/devices/logout-all', gatekeeper(auth), async (req, res) => {
-    await auth.logoutAll(req.user.id);
-    res.json({ success: true, message: "Logged out of all other devices" });
-});
+```js
+{
+  _id: sessionId,
+  userId: "user_123",
+  sess: { ... },
+  expiresAt: ISODate()
+}
 ```
 
-### 📧 Passwordless Login (OTP)
+### Setup
 
-Built-in support for generating and verifying Email One-Time-Passwords.
+```ts
+import mongoose from 'mongoose';
+import { MongoStore } from 'ace-auth/adapters';
 
-```typescript
-// 1. Send Code
-app.post('/auth/send-code', async (req, res) => {
-    await auth.sendOTP(req.body.email);
-    res.send('Code sent!');
-});
+await mongoose.connect(process.env.MONGO_URL);
 
-// 2. Verify & Login
-app.post('/auth/verify-code', async (req, res) => {
-    const { valid } = await auth.verifyOTP(req.body.email, req.body.code);
-    
-    if (valid) {
-        const { token } = await auth.login({ email: req.body.email }, req);
-        res.json({ token });
-    } else {
-        res.status(401).send('Invalid Code');
-    }
-});
+const store = new MongoStore(
+  mongoose.connection.collection('auth_sessions')
+);
 ```
 
+### Notes
+- TTL index recommended on `expiresAt`
+- Simple setup, no migrations required
+
 ---
 
-## 🏗️ Architecture: "Graceful Expiration"
+## 📱 Device & Session Management
 
-This is the core problem AceAuth solves.
+```ts
+// List active sessions
+const sessions = await auth.getActiveSessions(userId);
+
+// Logout everywhere
+await auth.logoutAll(userId);
+```
 
-**Scenario:** User leaves a tab open for 20 minutes. The 15-minute JWT expires.  
+- Device info captured at login
+- Bounded cache delay ≤ cacheTTL
+- Redis/DB is always source of truth
 
-- **Standard Library:** Request fails (401). User is forced to log in again. 😡  
-- **AceAuth:** Middleware catches the expiry error, checks the database, and issues a new token if the session is still valid.
+---
 
-```mermaid
-sequenceDiagram
-        participant Client
-        participant Middleware
-        participant Database
+## 📧 Passwordless OTP (Email)
 
-        Client->>Middleware: Sends Request (Token Expired)
-        Middleware->>Middleware: Signature Valid? ✅
-        Middleware->>Middleware: Time Check: Expired ❌
-        
-        Note right of Middleware: "Graceful Rescue" Triggered
-        
-        Middleware->>Database: Check Session ID
-        Database-->>Middleware: Session Active (30 Days left)
-        
-        Middleware->>Client: 200 OK + New Token (Header)
+```ts
+await auth.sendOTP(email);
+await auth.verifyOTP(email, code);
 ```
 
+- OTPs are single-use
+- Auto-expire (10 minutes)
+- Stored server-side only
+
+---
+
+## 📊 Benchmarks
+
+AceAuth is benchmarked against:
+- Raw JWT
+- Passport.js
+- express-session
+
+Results show AceAuth:
+- Outperforms Passport.js on hot paths
+- Retains server-side revocation
+- Trades minimal latency for correctness
+
+See **BENCHMARKS.md** for full data.
+
+---
+
+## 🔐 Security Guarantees
+
+- Server-side revocation
+- Token rotation handled internally
+- JWT payloads contain no user data
+- Bounded cache staleness (explicit)
+- Write throttling prevents DB overload
+
 ---
 
-## 🧪 Security & Testing
+## ❓ When to Use AceAuth
 
-This library is 100% covered by tests using Vitest.
+Use AceAuth if you need:
+- JWT-like scalability
+- Immediate logout across devices
+- Transparent refresh UX
+- Measured, explainable behavior
 
-- ✅ **Replay Protection:** OTPs are deleted immediately after use.  
-- ✅ **Tamper Proofing:** Tokens signed with invalid secrets are rejected immediately.  
-- ✅ **Lazy Cleanup:** Expired sessions are automatically cleaned up from the user index during read operations to prevent memory leaks.
+Avoid if you want:
+- Pure stateless JWT only
+- Cookie-only sessions
+- OAuth / SSO (out of scope)
 
 ---
 
 ## 📄 License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ace-auth",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Enterprise-grade identity management with graceful token rotation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",