@vunexa/lixa 0.1.6-alpha.13 → 0.1.6-alpha.15

package/README.md

@@ -1,785 +1,503 @@
-# @vunexa/lixa
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vunexa/lixa/master/docs/assets/lixa-banner.png" alt="Lixa Banner" width="600" onerror="this.style.display='none'"/>
+</p>
 
-> Package is in active development.
+# 🚀 Lixa (`@vunexa/lixa`)
 
-[![npm version](https://img.shields.io/npm/v/@vunexa/lixa.svg)](https://www.npmjs.com/package/@vunexa/lixa)
+> **The modern, developer-first TypeScript authentication & authorization framework for Node.js.**  
+> Built for zero-friction developer experience, strict AuthN/AuthZ separation, multi-SSO account linking, normalized database persistence, and blazing-fast in-memory caching.
+
+[![npm version](https://img.shields.io/npm/v/@vunexa/lixa.svg?color=blue)](https://www.npmjs.com/package/@vunexa/lixa)
 [![npm downloads](https://img.shields.io/npm/dm/@vunexa/lixa.svg)](https://www.npmjs.com/package/@vunexa/lixa)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.  
-`@vunexa/lixa` simplifies multi-provider authentication (e.g. Google, GitHub, Microsoft), enforces strict **AuthN/AuthZ separation**, enables **multi-SSO account linking**, and provides a dedicated post-login **Resource Connection API**.
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
 ---
 
-## Features
-
-- **Strict AuthN / AuthZ Separation**: Primary login is automatically restricted to minimal identity scopes (`openid`, `email`, `profile`). Resource scopes are isolated to post-login connection.
-- **Multi-SSO Account Linking**: Seamlessly merge accounts sharing the same verified email address under a single unified user session.
-- **Post-Login Resource Connection API**: Connect third-party API providers (GitHub Repositories, Google Drive, Slack) post-authentication and manage resource tokens on the user session.
-- **Multi-provider OAuth/OIDC support** with unified API.
-- **Official Extensions Package**: Built-in OAuth Providers (Google, GitHub), Database Storage (Prisma, Drizzle), and HTTP Frameworks (Express) via `@vunexa/lixa-extensions`.
-- **Unified session management** via `SessionHandler` (generation + storage).
-- **Unified state management** via `StateHandler` (PKCE + CSRF protection).
-- **Automatic PKCE** (Proof Key for Code Exchange) for all OAuth flows.
-- **TypeScript-first** with full type safety (zero `any` types).
+## 📑 Table of Contents
+
+- [Why Lixa?](#-why-lixa)
+- [Key Features](#-key-features)
+- [Architecture & Sequence Diagrams](#-architecture--sequence-diagrams)
+  - [1. Authentication Flow (AuthN)](#1-authentication-flow-authn)
+  - [2. Post-Login Resource Connection (AuthZ)](#2-post-login-resource-connection-authz)
+  - [3. Multi-SSO Account Linking](#3-multi-sso-account-linking)
+- [Installation](#-installation)
+- [Quickstart: AWS Cognito + Express + Prisma](#-quickstart-aws-cognito--express--prisma)
+  - [Step 1: Database Schema (Prisma)](#step-1-database-schema-prisma)
+  - [Step 2: Initialize Lixa & Storage with 2-Minute Cache](#step-2-initialize-lixa--storage-with-2-minute-cache)
+  - [Step 3: Setup Express Server & Routes](#step-3-setup-express-server--routes)
+  - [Step 4: Protect Routes & Use Tokens](#step-4-protect-routes--use-tokens)
+- [Connecting External Resources (AuthZ)](#-connecting-external-resources-authz)
+- [In-Memory 2-Minute Caching (`withLocalCache`)](#-in-memory-2-minute-caching-withlocalcache)
+- [Supported Identity Providers](#-supported-identity-providers)
+- [TypeScript API Reference](#-typescript-api-reference)
+- [Contributing & License](#-contributing--license)
 
 ---
 
-## Architecture Overview
+## 💡 Why Lixa?
 
-![Architecture Overview](https://cdn.jsdelivr.net/npm/@vunexa/lixa/docs/images/architecture.svg)
+Most auth libraries blur the line between **authenticating a user** (AuthN) and **requesting access to third-party APIs** (AuthZ). They cram bloated, multi-token JSON blobs into session cookies or single database rows, making user sessions fragile, bloated, and vulnerable.
 
----
-
-## Installation
-
-```bash
-npm install @vunexa/lixa @vunexa/lixa-extensions
-# or
-yarn add @vunexa/lixa @vunexa/lixa-extensions
-```
+**Lixa solves this cleanly:**
+1. **Single-Purpose Sessions**: A user session contains *only* the authentication tokens (`accessToken`, `refreshToken`, `idToken`) needed for that specific session.
+2. **First-Class Normalized Database Columns**: No opaque JSON blobs. Every table (`sessions`, `user_accounts`, `user_resources`, `oauth_states`, `user_credentials`) uses primitive typed columns (`userId`, `provider`, `accessToken`, `expiresAt`, etc.) with built-in database indexing.
+3. **Built-in 2-Minute Local In-Memory Cache**: Eliminates redundant database reads on high-frequency API endpoints while guaranteeing safe invalidation on logout or token updates.
+4. **Universal Multi-SSO Account Linking**: Seamlessly links AWS Cognito, Google, GitHub, Okta, Auth0, or username/password credentials to a single unified user ID by verified email.
+5. **Zero-Boilerplate DevXP**: Type-safe out of the box, with full Express middleware, Prisma and Drizzle ORM adapters, and automatic PKCE security.
 
 ---
 
-## Quick Start
+## ✨ Key Features
 
-### 1. Configure Lixa with Account Linking & Providers
+- 🛡️ **Strict AuthN / AuthZ Separation**: Identity tokens stay in `sessions`. External API tokens (e.g. GitHub repos, Google Drive) are isolated in `user_resources`.
+- ⚡ **2-Minute In-Memory Cache (`withLocalCache`)**: Blazing-fast response times for session checks and user lookups with zero SQLite/Postgres I/O overhead.
+- 🔗 **Multi-SSO Account Linking**: Automatic or interactive linking of multiple identity providers under one user account.
+- 🗄️ **Clean Database Schema**: Fully normalized Prisma and Drizzle models with primitive column types and indexed foreign keys.
+- 🔐 **PKCE & State Validation**: Automatic RFC 7636 Proof Key for Code Exchange and cryptographic CSRF state verification.
+- ☁️ **Enterprise Identity Backends**: First-class support for **AWS Cognito**, **Auth0**, **Okta**, and **Self-Managed Database** credentials.
 
-```typescript
-import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
-import { GoogleProvider, GithubProvider } from "@vunexa/lixa-extensions/providers";
+---
 
-export const lixa = new Lixa({
-  // Configure Multi-SSO Account Linking Strategy
-  accountLinking: {
-    mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
-    requireVerifiedEmail: true,
-  },
-  providers: {
-    google: {
-      provider: new GoogleProvider(),
-      clientId: process.env.GOOGLE_CLIENT_ID!,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-      redirectUri: "http://localhost:3000/auth/google/callback",
-      scopes: ["openid", "email", "profile"],
-    },
-    github: {
-      provider: new GithubProvider(),
-      clientId: process.env.GITHUB_CLIENT_ID!,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      redirectUri: "http://localhost:3000/auth/github/callback",
-      scopes: ["read:user", "user:email"],
-    },
-  },
-});
+## 📐 Architecture & Sequence Diagrams
+
+### 1. Authentication Flow (AuthN)
+
+This sequence diagram illustrates how a user logs in via AWS Cognito (or Google/GitHub SSO), receives a secure session cookie, and benefits from Lixa's 2-minute memory cache:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User Browser
+    participant Express as Express App (Lixa Middleware)
+    participant Lixa as Lixa Engine
+    participant Cache as In-Memory Cache (120s TTL)
+    participant DB as Prisma / Database
+    participant Cognito as AWS Cognito (OIDC / Hosted UI)
+
+    User->>Express: GET /api/v1/auth/login?provider=cognito
+    Express->>Lixa: getAuthUrl("cognito")
+    Lixa->>DB: Store state & PKCE codeVerifier in `oauth_states`
+    Lixa-->>Express: Return Authorization URL
+    Express-->>User: 302 Redirect to AWS Cognito
+
+    User->>Cognito: User signs in & consents
+    Cognito-->>User: 302 Redirect to /api/v1/auth/callback?code=...&state=...
+
+    User->>Express: GET /api/v1/auth/callback?code=...&state=...
+    Express->>Lixa: handleCallback("cognito", code, state)
+    Lixa->>DB: Validate & delete state from `oauth_states`
+    Lixa->>Cognito: Exchange code + PKCE verifier for tokens (AT, RT, idToken)
+    Cognito-->>Lixa: Return Cognito Tokens & User Claims
+    Lixa->>DB: Upsert normalized row in `sessions` (userId, AT, RT, idToken)
+    Lixa->>Cache: Cache session for 120 seconds
+    Lixa-->>Express: Issue Session ID (UUID)
+    Express-->>User: Set-Cookie: app_session=<sessionId>; HttpOnly; Secure
+
+    Note over User, Express: Subsequent Authenticated Requests
+    User->>Express: GET /api/v1/me (Cookie: app_session=...)
+    Express->>Cache: Check session in memory cache
+    alt Cache Hit (< 2 mins)
+        Cache-->>Express: Return cached session (0 DB queries!)
+    else Cache Miss / Expired
+        Express->>DB: Query `sessions` by id
+        DB-->>Express: Return session & refresh cache
+    end
+    Express-->>User: 200 OK (User Profile)
 ```
 
-### 2. Primary Authentication & Callback
-
-```typescript
-// 1. Redirect to provider authorization URL
-app.get("/auth/:provider", async (req, res) => {
-  const authUrl = await lixa.getAuthUrl(req.params.provider);
-  res.redirect(authUrl);
-});
-
-// 2. Handle provider callback
-app.get("/auth/:provider/callback", async (req, res) => {
-  const { code, state } = req.query;
-  const provider = req.params.provider;
+---
 
-  try {
-    const sessionId = await lixa.handleCallback({
-      provider,
-      code: code as string,
-      state: state as string,
-    });
-
-    res.cookie("session_id", sessionId, { httpOnly: true, secure: true });
-    res.redirect("/profile");
-  } catch (error) {
-    res.status(401).send("Authentication failed");
-  }
-});
+### 2. Post-Login Resource Connection (AuthZ)
+
+When an authenticated user grants your application access to external APIs (e.g. GitHub repos or Google Drive), tokens are stored in `user_resources` and bound to the user's account—completely separate from their login session:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Authenticated User
+    participant Express as Express App
+    participant Lixa as Lixa Engine
+    participant DB as Database (`user_resources`)
+    participant GitHub as GitHub OAuth (Resource Provider)
+
+    User->>Express: GET /api/v1/resources/connect/github
+    Express->>Lixa: getResourceAuthUrl("github", { userId: req.session.userId })
+    Lixa-->>Express: Return OAuth URL with resource scopes (`repo`, `read:user`)
+    Express-->>User: 302 Redirect to GitHub OAuth
+
+    User->>GitHub: Authorize application for repository access
+    GitHub-->>User: 302 Redirect to /api/v1/resources/callback/github?code=...
+
+    User->>Express: GET /api/v1/resources/callback/github?code=...
+    Express->>Lixa: handleResourceCallback("github", code, userId)
+    Lixa->>GitHub: Exchange authorization code for Resource Access Token
+    GitHub-->>Lixa: Return Access Token & Scopes
+    Lixa->>DB: Save to `user_resources` (userId, provider="github", accessToken, scopes)
+    Lixa-->>Express: Resource Connected
+    Express-->>User: 200 OK: GitHub Connected Successfully!
+
+    Note over Express, GitHub: Background Tasks / API Requests
+    Express->>DB: Get GitHub Resource Token for userId
+    Express->>GitHub: Fetch user repositories with Resource Token
+    GitHub-->>Express: Repository List
 ```
 
 ---
 
-## Multi-SSO Account Linking
-
-Lixa supports automatic identity merging for users signing in with different SSO providers (e.g. Google and GitHub) that share the same verified email address.
-
-### Account Linking Sequence Diagram
-
-![Account Linking Sequence](https://cdn.jsdelivr.net/npm/@vunexa/lixa/docs/images/account-linking.svg)
-
-### Account Linking Configuration Modes
-
-```typescript
-import { AccountLinkingStrategy } from "@vunexa/lixa";
-
-// Mode 1: Auto-link by verified email (Recommended)
-accountLinking: {
-  mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
-  requireVerifiedEmail: true,
-}
-
-// Mode 2: Treat provider logins as separate accounts
-accountLinking: {
-  mode: AccountLinkingStrategy.ISOLATED,
-}
-```
+### 3. Multi-SSO Account Linking
 
-### Explicit Account Linking & Unlinking APIs
+Lixa automatically links multiple identity providers (e.g. AWS Cognito + Google) sharing the same verified email address:
 
-```typescript
-// Explicitly link a new provider while authenticated
-await lixa.linkAccount({
-  sessionId: req.cookies.session_id,
-  provider: "github",
-  code: req.query.code as string,
-  state: req.query.state as string,
-});
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User with alex@example.com
+    participant Lixa as Lixa Engine
+    participant DB as Database (`user_accounts`)
 
-// Unlink a provider account
-await lixa.unlinkAccount(req.cookies.session_id, "github");
+    Note over User, DB: User previously registered with AWS Cognito (userId="usr_123")
+    User->>Lixa: Signs in via Google SSO (email="alex@example.com", verified=true)
+    Lixa->>DB: Find existing account by verified email in `user_accounts`
+    DB-->>Lixa: Found existing account (userId="usr_123", provider="cognito")
+    Lixa->>DB: Link Google identity to same userId in `user_accounts` (userId="usr_123", provider="google")
+    Lixa->>DB: Create active session for userId="usr_123"
+    Lixa-->>User: Logged in! Unified profile and data preserved across both logins.
 ```
 
 ---
 
-## Post-Login Resource Connection API (AuthZ)
-
-Primary authentication is strictly limited to identity scopes. To request third-party API permissions (such as GitHub Repositories or Google Drive), use Lixa's post-login **Resource Connection API**.
-
-### Resource Connection Sequence Diagram
+## 📦 Installation
 
-![Resource Connection Sequence](https://cdn.jsdelivr.net/npm/@vunexa/lixa/docs/images/resource-connection.svg)
-
-### Resource Connection Usage Example
-
-```typescript
-// 1. Generate Resource Authorization URL (Requires Active Session)
-app.get("/connect/github", async (req, res) => {
-  const sessionId = req.cookies.session_id;
-
-  const resourceAuthUrl = await lixa.getResourceAuthUrl({
-    sessionId,
-    provider: "github",
-    scopes: ["repo", "read:org"], // Resource permissions requested post-login
-  });
-
-  res.redirect(resourceAuthUrl);
-});
-
-// 2. Handle Resource Callback
-app.get("/connect/github/callback", async (req, res) => {
-  const sessionId = req.cookies.session_id;
-
-  const updatedSession = await lixa.handleResourceCallback({
-    sessionId,
-    provider: "github",
-    code: req.query.code as string,
-    state: req.query.state as string,
-    scopes: ["repo", "read:org"],
-  });
-
-  res.redirect("/dashboard");
-});
-
-// 3. Query Connected Resource Access Token (Auto-Refreshes Expired Tokens)
-app.get("/api/github/repos", async (req, res) => {
-  // Queries by active session OR user ID, auto-refreshing expired access tokens
-  const resource = await lixa.getConnectedResource(req.cookies.session_id, "github");
-
-  if (!resource) {
-    return res.status(403).json({ error: "GitHub resource not connected" });
-  }
-
-  // Call GitHub API with active resource access token
-  const response = await fetch("https://api.github.com/user/repos", {
-    headers: { Authorization: `Bearer ${resource.accessToken}` },
-  });
-
-  const repos = await response.json();
-  res.json(repos);
-});
-
-// 4. Query Resource Directly by User ID (e.g. inside background cron jobs or webhooks)
-const githubResource = await lixa.getUserResource(userId, "github");
+```bash
+# Core framework & official extensions
+npm install @vunexa/lixa @vunexa/lixa-extensions
 
-// 5. Disconnect Resource Provider
-app.delete("/connect/github", async (req, res) => {
-  await lixa.disconnectResource(req.cookies.session_id, "github");
-  res.json({ success: true });
-});
+# If using Prisma ORM (recommended)
+npm install @prisma/client
+npm install -D prisma
 ```
 
 ---
 
-## Session Interface Structure
+## 🏁 Quickstart: AWS Cognito + Express + Prisma
 
-```typescript
-export interface Session<TRaw = OAuthTokenResponse> {
-  /** Unique session ID generated by Lixa */
-  id?: string;
+Here is a complete, production-ready example configuring **AWS Cognito SSO**, **Prisma storage with 2-minute caching**, and **Express**.
 
-  /** Unified user ID across linked accounts */
-  userId?: string;
+### Step 1: Database Schema (Prisma)
 
-  /** Primary user email */
-  email?: string;
+Create or update your `prisma/schema.prisma` file with normalized primitive columns:
 
-  /** Linked SSO provider accounts (AuthN) - Single Source of Truth */
-  accounts?: Record<string, LinkedAccount>;
+```prisma
+datasource db {
+  provider = "sqlite" // or "postgresql", "mysql"
+  url      = env("DATABASE_URL")
+}
 
-  /** Connected third-party resource provider tokens (AuthZ) - Single Source of Truth */
-  resources?: Record<string, ConnectedResource>;
+generator client {
+  provider = "prisma-client-js"
+}
 
-  /** Optional primary access token or session token */
-  token?: string;
+// 1. Active User Sessions (AuthN)
+model Session {
+  id           String    @id @map("id")
+  userId       String?   @map("user_id")
+  userEmail    String?   @map("user_email")
+  provider     String?   @map("provider")
+  accessToken  String?   @map("access_token")
+  refreshToken String?   @map("refresh_token")
+  idToken      String?   @map("id_token")
+  expiresAt    DateTime  @map("expires_at")
+  createdAt    DateTime  @default(now()) @map("created_at")
+  updatedAt    DateTime  @default(now()) @updatedAt @map("updated_at")
+
+  @@index([userId])
+  @@index([userEmail])
+  @@index([expiresAt])
+  @@map("sessions")
+}
 
-  /** Optional current active auth provider */
-  provider?: string;
+// 2. Multi-SSO Linked Identity Accounts (AuthN)
+model UserAccount {
+  userId         String    @map("user_id")
+  provider       String    @map("provider")
+  providerUserId String?   @map("provider_user_id")
+  email          String?   @map("email")
+  linkedAt       DateTime  @default(now()) @map("linked_at")
+  updatedAt      DateTime  @default(now()) @updatedAt @map("updated_at")
+
+  @@id([userId, provider])
+  @@index([email])
+  @@map("user_accounts")
+}
 
-  /** Optional raw token response from provider */
-  raw?: TRaw;
+// 3. Connected Third-Party API Resources (AuthZ)
+model ConnectedResource {
+  userId       String    @map("user_id")
+  provider     String    @map("provider")
+  accessToken  String    @map("access_token")
+  refreshToken String?   @map("refresh_token")
+  idToken      String?   @map("id_token")
+  scopes       String?   @map("scopes")
+  expiresAt    DateTime? @map("expires_at")
+  connectedAt  DateTime  @default(now()) @map("connected_at")
+  updatedAt    DateTime  @default(now()) @updatedAt @map("updated_at")
+
+  @@id([userId, provider])
+  @@map("user_resources")
 }
-```
 
-### `LinkedAccount` vs `ConnectedResource`
+// 4. PKCE & OAuth Flow State
+model OAuthState {
+  state         String    @id @map("state")
+  provider      String?   @map("provider")
+  redirectUri   String?   @map("redirect_uri")
+  codeVerifier  String?   @map("code_verifier")
+  codeChallenge String?   @map("code_challenge")
+  expiresAt     DateTime  @map("expires_at")
+  createdAt     DateTime  @default(now()) @map("created_at")
+
+  @@index([expiresAt])
+  @@map("oauth_states")
+}
+```
 
-| Concept | Purpose | Scopes Allowed | Stored Location |
-| :--- | :--- | :--- | :--- |
-| **`LinkedAccount`** | Identity verification & multi-SSO merging (**AuthN**) | Minimal identity scopes (`openid`, `email`, `read:user`) | `session.accounts[provider]` |
-| **`ConnectedResource`** | External API resource access (**AuthZ**) | Resource permissions (`repo`, `drive.readonly`) | `session.resources[provider]` |
+Push the schema to your database:
+```bash
+npx prisma db push
+```
 
 ---
 
-## Custom Session Storage Implementations
-
-Lixa allows you to store sessions in any database or cache by implementing the `SessionStorage` interface.
-
-### 1. SQLite Session Storage (`better-sqlite3`)
-
-For relational persistence or single-node deployments using SQLite:
+### Step 2: Initialize Lixa & Storage with 2-Minute Cache
 
-#### Table Schema (SQL DDL)
-
-```sql
-CREATE TABLE IF NOT EXISTS sessions (
-  id TEXT PRIMARY KEY,
-  user_email TEXT,
-  data TEXT NOT NULL,
-  expires_at INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_sessions_email ON sessions(user_email);
-CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
-```
-
-#### TypeScript Implementation
+Create `src/config/lixa.ts`:
 
 ```typescript
-import Database from "better-sqlite3";
-import { Lixa, type SessionStorage, type Session } from "@vunexa/lixa";
-
-export class SqliteSessionStorage implements SessionStorage {
-  private db = new Database("lixa_sessions.db");
-
-  constructor() {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS sessions (
-        id TEXT PRIMARY KEY,
-        user_email TEXT,
-        data TEXT NOT NULL,
-        expires_at INTEGER NOT NULL
-      );
-      CREATE INDEX IF NOT EXISTS idx_sessions_email ON sessions(user_email);
-    `);
-  }
-
-  async saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void> {
-    const expiresAt = Math.floor(Date.now() / 1000) + expiresInSeconds;
-    const stmt = this.db.prepare(`
-      INSERT INTO sessions (id, user_email, data, expires_at)
-      VALUES (?, ?, ?, ?)
-      ON CONFLICT(id) DO UPDATE SET
-        user_email = excluded.user_email,
-        data = excluded.data,
-        expires_at = excluded.expires_at
-    `);
-    stmt.run(sessionId, session.email || null, JSON.stringify(session), expiresAt);
-  }
-
-  async getSession<T extends Session>(sessionId: string): Promise<T | null> {
-    const now = Math.floor(Date.now() / 1000);
-    const stmt = this.db.prepare(`SELECT data FROM sessions WHERE id = ? AND expires_at > ?`);
-    const row = stmt.get(sessionId, now) as { data: string } | undefined;
-    return row ? (JSON.parse(row.data) as T) : null;
-  }
+import { Lixa, CompositeIdentityProvider, AccountLinkingStrategy } from "@vunexa/lixa";
+import { CognitoIdentityProvider } from "@vunexa/lixa-extensions/identity";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-extensions/providers";
+import { createPrismaAdapter } from "@vunexa/lixa-extensions/storage/prisma";
+import { PrismaClient } from "@prisma/client";
 
-  async deleteSession(sessionId: string): Promise<void> {
-    const stmt = this.db.prepare(`DELETE FROM sessions WHERE id = ?`);
-    stmt.run(sessionId);
-  }
+const prisma = new PrismaClient();
 
-  async getSessionByEmail<T extends Session>(email: string): Promise<{ sessionId: string; session: T } | null> {
-    const now = Math.floor(Date.now() / 1000);
-    const stmt = this.db.prepare(`SELECT id, data FROM sessions WHERE user_email = ? AND expires_at > ? LIMIT 1`);
-    const row = stmt.get(email, now) as { id: string; data: string } | undefined;
-    return row ? { sessionId: row.id, session: JSON.parse(row.data) as T } : null;
-  }
-}
-
-// Pass to Lixa instance
 export const lixa = new Lixa({
-  sessionHandler: {
-    sessionStorage: new SqliteSessionStorage(),
+  // 1. Unified storage with automatic 2-minute (120s) in-memory cache
+  storage: createPrismaAdapter(prisma, {
+    enableCache: true,
+    cacheTtlSeconds: 120, // Cache session validations locally
+  }),
+
+  // 2. Multi-SSO account linking strategy
+  accountLinking: {
+    mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
+    requireVerifiedEmail: true,
   },
-  providers: { /* ... */ },
-});
-```
 
-#### Saved JSON Record Example in SQLite (`data` Column)
-
-```json
-{
-  "id": "e4a91f82c3b4a07f",
-  "userId": "1049281048",
-  "email": "alex.developer@example.com",
-  "accounts": {
-    "google": {
-      "provider": "google",
-      "email": "alex.developer@example.com",
-      "providerUserId": "1049281048",
-      "accessToken": "ya29.a0ARW5m7...",
-      "linkedAt": 1771657200000
+  // 3. Composite Identity Provider (AWS Cognito + Social SSO)
+  identityProvider: new CompositeIdentityProvider({
+    defaultProvider: "cognito",
+    providers: {
+      cognito: new CognitoIdentityProvider({
+        userPoolId: process.env.COGNITO_USER_POOL_ID!,
+        clientId: process.env.COGNITO_CLIENT_ID!,
+        clientSecret: process.env.COGNITO_CLIENT_SECRET, // optional
+        region: process.env.AWS_REGION || "us-east-1",
+        domain: process.env.COGNITO_DOMAIN, // e.g. "my-app.auth.us-east-1.amazoncognito.com"
+      }),
     },
-    "github": {
-      "provider": "github",
-      "email": "alex.developer@example.com",
-      "providerUserId": "5829104",
-      "accessToken": "gho_8f7b2a9e1c3...",
-      "linkedAt": 1771657250000
-    }
-  }
-}
+    oauthProviders: {
+      google: {
+        provider: new GoogleProvider(),
+        clientId: process.env.GOOGLE_CLIENT_ID!,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+        redirectUri: "http://localhost:3000/api/v1/auth/google/callback",
+        scopes: {
+          auth: ["openid", "email", "profile"],
+          resource: ["https://www.googleapis.com/auth/drive.readonly"],
+        },
+      },
+      github: {
+        provider: new GithubProvider(),
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+        redirectUri: "http://localhost:3000/api/v1/auth/github/callback",
+        scopes: {
+          auth: ["read:user", "user:email"],
+          resource: ["repo", "read:org"],
+        },
+      },
+    },
+  }),
+});
 ```
 
 ---
 
-### 2. AWS DynamoDB Session Storage (`@aws-sdk/lib-dynamodb`)
-
-For serverless and distributed AWS deployments using DynamoDB:
+### Step 3: Setup Express Server & Routes
 
-#### Table Configuration
-
-- **Table Name**: `LixaSessions`
-- **Partition Key**: `sessionId` (String)
-- **Global Secondary Index (GSI)**: `EmailIndex` (`email` as Partition Key)
-- **TTL Attribute**: `ttl` (Unix timestamp in seconds for automatic AWS expiration)
-
-#### TypeScript Implementation
+Create `src/server.ts`:
 
 ```typescript
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient, PutCommand, GetCommand, DeleteCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
-import { Lixa, type SessionStorage, type Session } from "@vunexa/lixa";
-
-export class DynamoDbSessionStorage implements SessionStorage {
-  private docClient: DynamoDBDocumentClient;
-  private tableName = "LixaSessions";
-
-  constructor() {
-    const client = new DynamoDBClient({ region: process.env.AWS_REGION || "us-east-1" });
-    this.docClient = DynamoDBDocumentClient.from(client);
-  }
-
-  async saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void> {
-    const ttl = Math.floor(Date.now() / 1000) + expiresInSeconds;
-    await this.docClient.send(
-      new PutCommand({
-        TableName: this.tableName,
-        Item: {
-          sessionId,
-          email: session.email || "N/A",
-          sessionData: session,
-          ttl,
-        },
-      })
-    );
-  }
-
-  async getSession<T extends Session>(sessionId: string): Promise<T | null> {
-    const res = await this.docClient.send(
-      new GetCommand({
-        TableName: this.tableName,
-        Key: { sessionId },
-      })
-    );
-
-    if (!res.Item) return null;
-    const now = Math.floor(Date.now() / 1000);
-    if (res.Item.ttl && res.Item.ttl < now) return null;
-
-    return res.Item.sessionData as T;
-  }
-
-  async deleteSession(sessionId: string): Promise<void> {
-    await this.docClient.send(
-      new DeleteCommand({
-        TableName: this.tableName,
-        Key: { sessionId },
-      })
-    );
-  }
-
-  async getSessionByEmail<T extends Session>(email: string): Promise<{ sessionId: string; session: T } | null> {
-    const res = await this.docClient.send(
-      new QueryCommand({
-        TableName: this.tableName,
-        IndexName: "EmailIndex",
-        KeyConditionExpression: "email = :email",
-        ExpressionAttributeValues: { ":email": email },
-        Limit: 1,
-      })
-    );
-
-    if (!res.Items || res.Items.length === 0) return null;
-    const item = res.Items[0];
-    const now = Math.floor(Date.now() / 1000);
-    if (item.ttl && item.ttl < now) return null;
-
-    return { sessionId: item.sessionId, session: item.sessionData as T };
-  }
-}
-
-// Pass to Lixa instance
-export const lixa = new Lixa({
-  sessionHandler: {
-    sessionStorage: new DynamoDbSessionStorage(),
-  },
-  providers: { /* ... */ },
+import express from "express";
+import cookieParser from "cookie-parser";
+import cors from "cors";
+import { createAuthRouter, createRequireAuthMiddleware } from "@vunexa/lixa-extensions/http/express";
+import { lixa } from "./config/lixa";
+
+const app = express();
+app.use(express.json());
+app.use(cookieParser(process.env.COOKIE_SECRET || "super-secret-key"));
+app.use(cors({ origin: "http://localhost:5173", credentials: true }));
+
+// Auth guard middleware
+const requireAuth = createRequireAuthMiddleware(lixa);
+
+// Mount Lixa authentication routes:
+// - GET  /api/v1/auth/login?provider=cognito
+// - GET  /api/v1/auth/callback
+// - POST /api/v1/auth/logout
+// - GET  /api/v1/auth/me
+const authRouter = express.Router();
+createAuthRouter(lixa, {
+  router: authRouter,
+  requireAuth,
+  successRedirectUrl: "http://localhost:5173/dashboard",
+  errorRedirectUrl: "http://localhost:5173/login?error=auth_failed",
 });
-```
-
-#### Saved DynamoDB Item JSON Example
-
-```json
-{
-  "sessionId": "e4a91f82c3b4a07f",
-  "email": "alex.developer@example.com",
-  "ttl": 1771743600,
-  "sessionData": {
-    "id": "e4a91f82c3b4a07f",
-    "userId": "1049281048",
-    "email": "alex.developer@example.com",
-    "accounts": {
-      "google": {
-        "provider": "google",
-        "email": "alex.developer@example.com",
-        "providerUserId": "1049281048",
-        "accessToken": "ya29.a0ARW5m7...",
-        "linkedAt": 1771657200000
-      },
-      "github": {
-        "provider": "github",
-        "email": "alex.developer@example.com",
-        "providerUserId": "5829104",
-        "accessToken": "gho_8f7b2a9e1c3...",
-        "linkedAt": 1771657250000
-      }
-    }
-  }
-}
+app.use("/api/v1/auth", authRouter);
 ```
 
 ---
 
-## Custom Resource Storage Implementation (`ResourceStorage`)
-
-While `SessionStorage` manages short-lived user authentication sessions (indexed by `sessionId`), **`ResourceStorage`** manages long-lived third-party API tokens (**AuthZ**) bound directly to a **User ID** (or Email). This ensures that third-party credentials (such as GitHub Repositories or Google Drive) persist across session expirations and logouts.
-
-### `ResourceStorage` Interface
+### Step 4: Protect Routes & Use Tokens
 
 ```typescript
-export interface ResourceStorage {
-  saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void>;
-  getResource(userId: string, provider: string): Promise<ConnectedResource | null>;
-  getUserResources(userId: string): Promise<Record<string, ConnectedResource>>;
-  deleteResource(userId: string, provider: string): Promise<void>;
-}
-```
-
-### 1. SQLite Resource Storage (`better-sqlite3`)
-
-#### Table Schema (SQL DDL)
+// Protected route example
+app.get("/api/v1/profile", requireAuth, async (req: any, res) => {
+  // req.session is populated automatically
+  const { userId, email, provider, accessToken, idToken } = req.session;
+
+  res.json({
+    message: "Authenticated successfully!",
+    user: {
+      userId,
+      email,
+      provider,
+    },
+    tokens: {
+      accessTokenPreview: accessToken ? `${accessToken.substring(0, 15)}...` : null,
+      idTokenPreview: idToken ? `${idToken.substring(0, 15)}...` : null,
+    },
+  });
+});
 
-```sql
-CREATE TABLE IF NOT EXISTS user_resources (
-  user_id TEXT NOT NULL,
-  provider TEXT NOT NULL,
-  data TEXT NOT NULL,
-  updated_at INTEGER NOT NULL,
-  PRIMARY KEY (user_id, provider)
-);
+app.listen(3000, () => {
+  console.log("Server running at http://localhost:3000");
+});
 ```
 
-#### TypeScript Implementation
-
-```typescript
-import Database from "better-sqlite3";
-import { Lixa, type ResourceStorage, type ConnectedResource } from "@vunexa/lixa";
-
-export class SqliteResourceStorage implements ResourceStorage {
-  private db = new Database("lixa_resources.db");
-
-  constructor() {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS user_resources (
-        user_id TEXT NOT NULL,
-        provider TEXT NOT NULL,
-        data TEXT NOT NULL,
-        updated_at INTEGER NOT NULL,
-        PRIMARY KEY (user_id, provider)
-      );
-    `);
-  }
-
-  async saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void> {
-    const stmt = this.db.prepare(`
-      INSERT INTO user_resources (user_id, provider, data, updated_at)
-      VALUES (?, ?, ?, ?)
-      ON CONFLICT(user_id, provider) DO UPDATE SET
-        data = excluded.data,
-        updated_at = excluded.updated_at
-    `);
-    stmt.run(userId, provider.toLowerCase(), JSON.stringify(resource), Date.now());
-  }
+---
 
-  async getResource(userId: string, provider: string): Promise<ConnectedResource | null> {
-    const stmt = this.db.prepare(`SELECT data FROM user_resources WHERE user_id = ? AND provider = ?`);
-    const row = stmt.get(userId, provider.toLowerCase()) as { data: string } | undefined;
-    return row ? (JSON.parse(row.data) as ConnectedResource) : null;
-  }
+## 🔌 Connecting External Resources (AuthZ)
 
-  async getUserResources(userId: string): Promise<Record<string, ConnectedResource>> {
-    const stmt = this.db.prepare(`SELECT provider, data FROM user_resources WHERE user_id = ?`);
-    const rows = stmt.all(userId) as Array<{ provider: string; data: string }>;
-    const result: Record<string, ConnectedResource> = {};
-    for (const r of rows) {
-      result[r.provider] = JSON.parse(r.data);
-    }
-    return result;
-  }
+Unlike login authentication, **Resource Connections** allow your application to interact with external APIs (like GitHub repositories or Google Drive files) on behalf of the user.
 
-  async deleteResource(userId: string, provider: string): Promise<void> {
-    const stmt = this.db.prepare(`DELETE FROM user_resources WHERE user_id = ? AND provider = ?`);
-    stmt.run(userId, provider.toLowerCase());
-  }
-}
+```typescript
+// 1. Generate connection redirect URL
+app.get("/api/v1/resources/github/connect", requireAuth, async (req: any, res) => {
+  const url = await lixa.getResourceAuthUrl("github", {
+    userId: req.session.userId,
+    redirectUri: "http://localhost:3000/api/v1/resources/github/callback",
+  });
+  res.redirect(url);
+});
 
-// Pass to Lixa instance via resourceHandler
-export const lixa = new Lixa({
-  resourceHandler: {
-    resourceStorage: new SqliteResourceStorage(),
-  },
-  providers: { /* ... */ },
+// 2. Handle resource callback & store token
+app.get("/api/v1/resources/github/callback", requireAuth, async (req: any, res) => {
+  const { code } = req.query;
+  await lixa.handleResourceCallback("github", code as string, req.session.userId);
+  res.redirect("http://localhost:5173/settings?connected=github");
 });
-```
 
-#### Saved JSON Records Example in SQLite (`user_resources` Table)
-
-**Row 1 (GitHub Repositories)**:
-```json
-{
-  "user_id": "1049281048",
-  "provider": "github",
-  "data": {
-    "accessToken": "gho_resource_repo_9a8b7c...",
-    "refreshToken": "ghr_refresh_token_123...",
-    "scopes": ["repo", "read:org"],
-    "expiresAt": 1771743600000,
-    "connectedAt": 1771657300000
+// 3. Make third-party API calls using stored resource tokens
+app.get("/api/v1/resources/github/repos", requireAuth, async (req: any, res) => {
+  const resource = await lixa.getResource(req.session.userId, "github");
+  if (!resource) {
+    return res.status(404).json({ error: "GitHub account not connected" });
   }
-}
-```
 
-**Row 2 (Google Drive)**:
-```json
-{
-  "user_id": "1049281048",
-  "provider": "google",
-  "data": {
-    "accessToken": "ya29.drive_resource_token_456...",
-    "refreshToken": "1//09abc_google_refresh_token...",
-    "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
-    "expiresAt": 1771660800000,
-    "connectedAt": 1771657400000
-  }
-}
+  // Call GitHub API with resource.accessToken
+  const response = await fetch("https://api.github.com/user/repos", {
+    headers: { Authorization: `Bearer ${resource.accessToken}` },
+  });
+  const repos = await response.json();
+  res.json({ repos });
+});
 ```
 
 ---
 
-### 2. AWS DynamoDB Resource Storage (`@aws-sdk/lib-dynamodb`)
-
-For serverless AWS deployments storing user API credentials in DynamoDB:
-
-#### Table Configuration
+## ⚡ In-Memory 2-Minute Caching (`withLocalCache`)
 
-- **Table Name**: `LixaUserResources`
-- **Partition Key (PK)**: `userId` (String)
-- **Sort Key (SK)**: `provider` (String)
+Under high traffic, hitting your database on every single API request to validate a session creates heavy I/O bottlenecks.
 
-#### TypeScript Implementation
+Lixa includes a high-performance **2-Minute In-Memory TTL Cache**:
 
 ```typescript
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient, PutCommand, GetCommand, DeleteCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
-import { Lixa, type ResourceStorage, type ConnectedResource } from "@vunexa/lixa";
-
-export class DynamoDbResourceStorage implements ResourceStorage {
-  private docClient: DynamoDBDocumentClient;
-  private tableName = "LixaUserResources";
-
-  constructor() {
-    const client = new DynamoDBClient({ region: process.env.AWS_REGION || "us-east-1" });
-    this.docClient = DynamoDBDocumentClient.from(client);
-  }
-
-  async saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void> {
-    await this.docClient.send(
-      new PutCommand({
-        TableName: this.tableName,
-        Item: {
-          userId,
-          provider: provider.toLowerCase(),
-          resourceData: resource,
-          updatedAt: Date.now(),
-        },
-      })
-    );
-  }
+import { withLocalCache } from "@vunexa/lixa-extensions/storage";
 
-  async getResource(userId: string, provider: string): Promise<ConnectedResource | null> {
-    const res = await this.docClient.send(
-      new GetCommand({
-        TableName: this.tableName,
-        Key: {
-          userId,
-          provider: provider.toLowerCase(),
-        },
-      })
-    );
-
-    return res.Item ? (res.Item.resourceData as ConnectedResource) : null;
-  }
-
-  async getUserResources(userId: string): Promise<Record<string, ConnectedResource>> {
-    const res = await this.docClient.send(
-      new QueryCommand({
-        TableName: this.tableName,
-        KeyConditionExpression: "userId = :userId",
-        ExpressionAttributeValues: { ":userId": userId },
-      })
-    );
-
-    const result: Record<string, ConnectedResource> = {};
-    if (res.Items) {
-      for (const item of res.Items) {
-        result[item.provider] = item.resourceData as ConnectedResource;
-      }
-    }
-    return result;
-  }
-
-  async deleteResource(userId: string, provider: string): Promise<void> {
-    await this.docClient.send(
-      new DeleteCommand({
-        TableName: this.tableName,
-        Key: {
-          userId,
-          provider: provider.toLowerCase(),
-        },
-      })
-    );
-  }
-}
-
-// Pass to Lixa instance via resourceHandler
-export const lixa = new Lixa({
-  resourceHandler: {
-    resourceStorage: new DynamoDbResourceStorage(),
-  },
-  providers: { /* ... */ },
+// Automatically applied when using createPrismaAdapter
+const cachedStorage = withLocalCache(baseAdapter, {
+  ttlSeconds: 120, // 2 minutes (default)
 });
 ```
 
-#### Saved DynamoDB Resource Items Example (`LixaUserResources` Table)
-
-```json
-[
-  {
-    "userId": "1049281048",
-    "provider": "github",
-    "updatedAt": 1771657300000,
-    "resourceData": {
-      "accessToken": "gho_resource_repo_9a8b7c...",
-      "refreshToken": "ghr_refresh_token_123...",
-      "scopes": ["repo", "read:org"],
-      "expiresAt": 1771743600000,
-      "connectedAt": 1771657300000
-    }
-  },
-  {
-    "userId": "1049281048",
-    "provider": "google",
-    "updatedAt": 1771657400000,
-    "resourceData": {
-      "accessToken": "ya29.drive_resource_token_456...",
-      "refreshToken": "1//09abc_google_refresh_token...",
-      "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
-      "expiresAt": 1771660800000,
-      "connectedAt": 1771657400000
-    }
-  }
-]
-```
+### Cache Features & Invalidation Guarantees:
+- **Zero Database I/O**: Session lookups within 120 seconds return in sub-millisecond memory time.
+- **Auto-Invalidation on Logout**: Calling `deleteSession(sessionId)` immediately clears both the database record and memory cache.
+- **Auto-Invalidation on Updates**: Saving or updating accounts/credentials purges stale cached keys automatically.
+- **Safe Isolation**: OAuth states (single-use CSRF tokens) bypass the cache and validate directly against persistent storage.
 
 ---
 
-### 3. Querying Connected Resources Directly by User ID
+## 🌐 Supported Identity Providers
 
-`ResourceStorage` enables background workers, cron jobs, and webhooks to access third-party API credentials by `userId` without an active HTTP session:
-
-```typescript
-// Background worker querying user's GitHub Repos token
-const githubResource = await lixa.getUserResource(user.id, "github");
-
-if (githubResource) {
-  // Lixa auto-refreshes expired access tokens transparently!
-  const response = await fetch("https://api.github.com/user/repos", {
-    headers: { Authorization: `Bearer ${githubResource.accessToken}` },
-  });
-}
-```
+| Provider | Type | AuthN (SSO) | AuthZ (Resources) | Package |
+| :--- | :--- | :---: | :---: | :--- |
+| **AWS Cognito** | Enterprise IdP | ✅ | — | `@vunexa/lixa-extensions/identity` |
+| **Google** | Social / OIDC | ✅ | ✅ (Drive, Gmail) | `@vunexa/lixa-extensions/providers` |
+| **GitHub** | OAuth 2.0 | ✅ | ✅ (Repos, Orgs) | `@vunexa/lixa-extensions/providers` |
+| **Microsoft** | Azure AD / OIDC | ✅ | ✅ (Graph API) | `@vunexa/lixa-extensions/providers` |
+| **Auth0** | Enterprise IdP | ✅ | — | `@vunexa/lixa-extensions/identity` |
+| **Okta** | Enterprise IdP | ✅ | — | `@vunexa/lixa-extensions/identity` |
+| **Self-Managed** | SQLite / Postgres | ✅ | — | `@vunexa/lixa` (Built-in) |
 
 ---
 
-## User Info Utilities
-
-Lixa provides utilities to extract user information from OAuth tokens:
+## 📚 TypeScript API Reference
 
-```typescript
-import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
+### `new Lixa(options)`
+- `storage`: Storage adapter created via `createPrismaAdapter` or custom implementation.
+- `identityProvider`: `CompositeIdentityProvider` or standalone IdP instance.
+- `accountLinking`: Configuration for cross-provider email matching (`AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL`).
+- `sessionHandler`: Custom session serialization logic (optional).
 
-const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
-console.log(userInfo.email, userInfo.name);
-```
+### Methods
+- `lixa.getAuthUrl(provider, options)`: Returns authorization URL with PKCE verifier stored in state.
+- `lixa.handleCallback(provider, code, state)`: Validates state, exchanges code for tokens, creates session, and links account.
+- `lixa.getSession(sessionId)`: Retrieves active session from memory cache or database.
+- `lixa.deleteSession(sessionId)`: Deletes session and purges local cache.
+- `lixa.getResourceAuthUrl(provider, options)`: Returns resource authorization URL.
+- `lixa.handleResourceCallback(provider, code, userId)`: Stores connected resource tokens under `userId`.
+- `lixa.getResource(userId, provider)`: Retrieves active resource token for third-party API requests.
 
 ---
 
-## License
+## 🤝 Contributing & License
+
+Contributions are welcome! Please open an issue or pull request on GitHub.
 
-[MIT](LICENSE)
+Distributed under the **MIT License**. See `LICENSE` for details.