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

package/README.md

@@ -1,65 +1,282 @@
-# @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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+---
 
-A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend Node.js applications.  
-`@vunexa/lixa` simplifies multi-provider authentication (e.g. Google, GitHub, Microsoft, AWS Cognito), enforces strict **AuthN/AuthZ separation**, enables **multi-SSO account linking**, and provides a dedicated post-login **Resource Connection API**.
+## 📑 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)
 
 ---
 
-## Features
+## 💡 Why Lixa?
+
+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.
 
-- **Strict AuthN / AuthZ Separation**: Primary login is automatically restricted to minimal identity scopes (`openid`, `email`, `profile`, `read:user`, `user:email`). Resource permissions are isolated to post-login resource connection.
-- **Multi-SSO Account Linking**: Seamlessly merge multiple authentication providers (e.g. AWS Cognito + Google + GitHub) under a single user profile based on verified email or active session context.
-- **Persistent Account Storage (`AccountStorage`)**: Linked identity accounts remain saved in persistent database storage across session logouts and log-ins.
-- **Post-Login Resource Connection API**: Connect third-party API providers (GitHub Repositories, Google Drive, Slack) post-authentication and manage resource access tokens bound to the user profile.
-- **Multi-Identity Provider Architecture**: Built-in support for Self-Managed Database credentials, AWS Cognito, Auth0, and Okta via `@vunexa/lixa-extensions`.
-- **Automatic PKCE** (Proof Key for Code Exchange) and state CSRF validation for all OAuth flows.
-- **TypeScript-first**: Comprehensive type safety across all core APIs and HTTP adapters.
+**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.
 
 ---
 
-## Architecture Overview
+## ✨ Key Features
+
+- 🛡️ **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.
+
+---
+
+## 📐 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
-flowchart TD
-    Client["Client App / Frontend"] -->|1. AuthN / Login Request| LixaEngine["Lixa Core Engine"]
-    
-    subgraph AuthN ["Primary Authentication & Account Linking (AuthN)"]
-        LixaEngine -->|Minimal Scopes| IdP["Identity Provider / Social SSO (Cognito, Google, GitHub)"]
-        IdP -->|Authorization Code| Callback["/callback Endpoint"]
-        Callback -->|Verify Code + Link Accounts| SessionStore["Session & Account Storage (Prisma / Drizzle / DB)"]
-    end
-    
-    subgraph AuthZ ["Post-Login Resource Connection (AuthZ)"]
-        LixaEngine -->|Resource Scopes (e.g. repo, drive)| ResourceProvider["External Resource APIs (GitHub API, Google Drive)"]
-        ResourceProvider -->|Resource Tokens| ResourceStore["Resource Storage (user_resources DB)"]
+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)
+```
+
+---
 
-    SessionStore -->|Session Cookie| Client
-    ResourceStore -->|Auto-Refreshed Tokens| Client
+### 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
 ```
 
 ---
 
-## Installation
+### 3. Multi-SSO Account Linking
+
+Lixa automatically links multiple identity providers (e.g. AWS Cognito + Google) sharing the same verified email address:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User with alex@example.com
+    participant Lixa as Lixa Engine
+    participant DB as Database (`user_accounts`)
+
+    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.
+```
+
+---
+
+## 📦 Installation
 
 ```bash
+# Core framework & official extensions
 npm install @vunexa/lixa @vunexa/lixa-extensions
+
+# If using Prisma ORM (recommended)
+npm install @prisma/client
+npm install -D prisma
 ```
 
 ---
 
-## Quick Start
+## 🏁 Quickstart: AWS Cognito + Express + Prisma
+
+Here is a complete, production-ready example configuring **AWS Cognito SSO**, **Prisma storage with 2-minute caching**, and **Express**.
+
+### Step 1: Database Schema (Prisma)
+
+Create or update your `prisma/schema.prisma` file with normalized primitive columns:
+
+```prisma
+datasource db {
+  provider = "sqlite" // or "postgresql", "mysql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+// 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")
+}
+
+// 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")
+}
+
+// 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")
+}
+
+// 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")
+}
+```
 
-### 1. Configure Lixa Instance
+Push the schema to your database:
+```bash
+npx prisma db push
+```
+
+---
+
+### Step 2: Initialize Lixa & Storage with 2-Minute Cache
+
+Create `src/config/lixa.ts`:
 
 ```typescript
-import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
+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";
@@ -67,133 +284,220 @@ import { PrismaClient } from "@prisma/client";
 const prisma = new PrismaClient();
 
 export const lixa = new Lixa({
-  // Unified database storage for sessions, OAuth state, resources, and account linking
-  storage: createPrismaAdapter(prisma),
+  // 1. Unified storage with automatic 2-minute (120s) in-memory cache
+  storage: createPrismaAdapter(prisma, {
+    enableCache: true,
+    cacheTtlSeconds: 120, // Cache session validations locally
+  }),
 
-  // Configure Multi-SSO Account Linking
+  // 2. Multi-SSO account linking strategy
   accountLinking: {
     mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
     requireVerifiedEmail: true,
   },
 
-  // Federated OAuth Providers
-  federatedOAuthProviders: {
-    google: {
-      provider: new GoogleProvider(),
-      clientId: process.env.GOOGLE_CLIENT_ID!,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-      redirectUri: "http://localhost:3000/api/v1/oidc/google/callback",
-      scopes: ["openid", "email", "profile"],
+  // 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: new GithubProvider(),
-      clientId: process.env.GITHUB_CLIENT_ID!,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      redirectUri: "http://localhost:3000/api/v1/oidc/github/callback",
-      scopes: ["read:user", "user:email"],
+    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"],
+        },
+      },
     },
-  },
+  }),
 });
 ```
 
 ---
 
-## Multi-SSO Account Linking
-
-Lixa allows users to sign in with different identity providers (e.g. Username/Password, AWS Cognito, Google, GitHub) and links them to the same underlying user account.
+### Step 3: Setup Express Server & Routes
 
-### Account Linking Sequence
+Create `src/server.ts`:
 
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User
-    participant Frontend
-    participant Express as Backend Express App
-    participant Lixa as Lixa Core Engine
-    participant GitHub as GitHub OAuth
-    participant DB as Prisma / Drizzle DB
-
-    User->>Frontend: Click "Link GitHub"
-    Frontend->>Express: GET /login?provider=github
-    Express->>Lixa: getAuthUrl("github")
-    Lixa-->>Express: Returns Auth URL + State
-    Express-->>User: 302 Redirect to GitHub
-
-    User->>GitHub: Authenticate & Grant Identity Scope
-    GitHub-->>Express: GET /callback?code=123&state=abc (Cookie: session_id)
-    Express->>Lixa: handleCallback({ provider: "github", code, state, sessionId })
-    Lixa->>GitHub: Exchange Code for Access Token
-    GitHub-->>Lixa: Return Access Token + Profile (email)
-    Lixa->>DB: Save Account Link (accounts.github) to user_resources DB
-    Lixa-->>Express: Return Updated Session ID
-    Express-->>Frontend: Redirect to /dashboard with updated session cookie
+```typescript
+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",
+});
+app.use("/api/v1/auth", authRouter);
 ```
 
-### Account Linking Usage
+---
+
+### Step 4: Protect Routes & Use Tokens
 
 ```typescript
-// Explicitly link a new provider while authenticated
-const sessionId = await lixa.handleCallback({
-  provider: "github",
-  code: req.query.code as string,
-  state: req.query.state as string,
-  sessionId: activeSessionId, // Links GitHub directly to the active session
+// 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,
+    },
+  });
 });
 
-// Unlink a provider account
-await lixa.unlinkAccount(activeSessionId, "github");
+app.listen(3000, () => {
+  console.log("Server running at http://localhost:3000");
+});
 ```
 
 ---
 
-## Post-Login Resource Connection (AuthZ API)
+## 🔌 Connecting External Resources (AuthZ)
 
-Primary authentication is strictly limited to identity scopes. To request third-party API permissions (such as GitHub Repositories or Google Drive access), use Lixa's post-login **Resource Connection API**.
+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.
 
-### Resource Connection Sequence
+```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);
+});
 
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User
-    participant Frontend
-    participant Express as Backend Express App
-    participant Lixa as Lixa Core Engine
-    participant ResourceAPI as GitHub / Google Drive API
-
-    User->>Frontend: Click "Connect GitHub Repos"
-    Frontend->>Express: GET /connect-resource/github
-    Express->>Lixa: getResourceAuthUrl({ sessionId, provider: "github", scopes: ["repo"] })
-    Lixa-->>Express: Returns Consent URL + Resource State
-    Express-->>User: 302 Redirect to Provider Consent Page
-
-    User->>ResourceAPI: Grant Resource Permission ("repo")
-    ResourceAPI-->>Express: GET /callback?code=xyz (Cookie: session_id, lixa_resource_flow=true)
-    Express->>Lixa: handleResourceCallback({ sessionId, provider: "github", code })
-    Lixa->>ResourceAPI: Exchange Code for Resource Access & Refresh Tokens
-    Lixa->>DB: Save Resource Tokens to user_resources Table
-    Lixa-->>Express: Return Updated Session
-    Express-->>Frontend: 200 OK / Redirect to Dashboard
+// 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");
+});
+
+// 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" });
+  }
+
+  // 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 });
+});
 ```
 
-### Querying Connected Resource Access Tokens
+---
+
+## ⚡ In-Memory 2-Minute Caching (`withLocalCache`)
+
+Under high traffic, hitting your database on every single API request to validate a session creates heavy I/O bottlenecks.
+
+Lixa includes a high-performance **2-Minute In-Memory TTL Cache**:
 
 ```typescript
-// Query connected resource (automatically handles token refreshes)
-const resource = await lixa.getConnectedResource(sessionId, "github");
+import { withLocalCache } from "@vunexa/lixa-extensions/storage";
 
-if (resource) {
-  // Use access token to call external API
-  const reposResponse = await fetch("https://api.github.com/user/repos", {
-    headers: { Authorization: `Bearer ${resource.accessToken}` },
-  });
-  const repos = await reposResponse.json();
-}
+// Automatically applied when using createPrismaAdapter
+const cachedStorage = withLocalCache(baseAdapter, {
+  ttlSeconds: 120, // 2 minutes (default)
+});
 ```
 
+### 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.
+
+---
+
+## 🌐 Supported Identity Providers
+
+| 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) |
+
 ---
 
-## License
+## 📚 TypeScript API Reference
+
+### `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).
+
+### 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.
+
+---
+
+## 🤝 Contributing & License
+
+Contributions are welcome! Please open an issue or pull request on GitHub.
 
-MIT © [Vunexa](https://github.com/vunexa)
+Distributed under the **MIT License**. See `LICENSE` for details.

package/dist/credentials/credentials-manager.d.ts

@@ -45,6 +45,20 @@ export declare class CredentialsManager {
      * @returns True if password was successfully updated
      */
     changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Sets a password for a user who doesn't have one yet (e.g. SSO-first users),
+     * or updates an existing password without requiring the old one.
+     * This should only be called from an authenticated context (user already verified their identity via SSO).
+     *
+     * @param params - userId and newPassword
+     * @returns True if password was successfully set
+     */
+    setPassword(params: {
+        userId: string;
+        newPassword: string;
+        identifier?: string;
+        email?: string;
+    }): Promise<boolean>;
     /**
      * Finds a user by ID and returns safe user data.
      */