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

package/README.md

@@ -6,28 +6,43 @@
 [![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**.
+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**.
 
 ---
 
 ## 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).
+- **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.
 
 ---
 
 ## Architecture Overview
 
-![Architecture Overview](https://cdn.jsdelivr.net/npm/@vunexa/lixa/docs/images/architecture.svg)
+```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)"]
+    end
+
+    SessionStore -->|Session Cookie| Client
+    ResourceStore -->|Auto-Refreshed Tokens| Client
+```
 
 ---
 
@@ -35,751 +50,150 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 
 ```bash
 npm install @vunexa/lixa @vunexa/lixa-extensions
-# or
-yarn add @vunexa/lixa @vunexa/lixa-extensions
 ```
 
 ---
 
 ## Quick Start
 
-### 1. Configure Lixa with Account Linking & Providers
+### 1. Configure Lixa Instance
 
 ```typescript
 import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
 import { GoogleProvider, GithubProvider } from "@vunexa/lixa-extensions/providers";
+import { createPrismaAdapter } from "@vunexa/lixa-extensions/storage/prisma";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
 
 export const lixa = new Lixa({
-  // Configure Multi-SSO Account Linking Strategy
+  // Unified database storage for sessions, OAuth state, resources, and account linking
+  storage: createPrismaAdapter(prisma),
+
+  // Configure Multi-SSO Account Linking
   accountLinking: {
     mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
     requireVerifiedEmail: true,
   },
-  providers: {
+
+  // Federated OAuth Providers
+  federatedOAuthProviders: {
     google: {
       provider: new GoogleProvider(),
       clientId: process.env.GOOGLE_CLIENT_ID!,
       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-      redirectUri: "http://localhost:3000/auth/google/callback",
+      redirectUri: "http://localhost:3000/api/v1/oidc/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",
+      redirectUri: "http://localhost:3000/api/v1/oidc/github/callback",
       scopes: ["read:user", "user:email"],
     },
   },
 });
 ```
 
-### 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");
-  }
-});
-```
-
 ---
 
 ## 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
+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.
 
-![Account Linking Sequence](https://cdn.jsdelivr.net/npm/@vunexa/lixa/docs/images/account-linking.svg)
+### Account Linking Sequence
 
-### Account Linking Configuration Modes
+```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
 
-```typescript
-import { AccountLinkingStrategy } from "@vunexa/lixa";
-
-// Mode 1: Auto-link by verified email (Recommended)
-accountLinking: {
-  mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
-  requireVerifiedEmail: true,
-}
+    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
 
-// Mode 2: Treat provider logins as separate accounts
-accountLinking: {
-  mode: AccountLinkingStrategy.ISOLATED,
-}
+    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
 ```
 
-### Explicit Account Linking & Unlinking APIs
+### Account Linking Usage
 
 ```typescript
 // Explicitly link a new provider while authenticated
-await lixa.linkAccount({
-  sessionId: req.cookies.session_id,
+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
 });
 
 // Unlink a provider account
-await lixa.unlinkAccount(req.cookies.session_id, "github");
-```
-
----
-
-## 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
-
-![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");
-
-// 5. Disconnect Resource Provider
-app.delete("/connect/github", async (req, res) => {
-  await lixa.disconnectResource(req.cookies.session_id, "github");
-  res.json({ success: true });
-});
-```
-
----
-
-## Session Interface Structure
-
-```typescript
-export interface Session<TRaw = OAuthTokenResponse> {
-  /** Unique session ID generated by Lixa */
-  id?: string;
-
-  /** Unified user ID across linked accounts */
-  userId?: string;
-
-  /** Primary user email */
-  email?: string;
-
-  /** Linked SSO provider accounts (AuthN) - Single Source of Truth */
-  accounts?: Record<string, LinkedAccount>;
-
-  /** Connected third-party resource provider tokens (AuthZ) - Single Source of Truth */
-  resources?: Record<string, ConnectedResource>;
-
-  /** Optional primary access token or session token */
-  token?: string;
-
-  /** Optional current active auth provider */
-  provider?: string;
-
-  /** Optional raw token response from provider */
-  raw?: TRaw;
-}
-```
-
-### `LinkedAccount` vs `ConnectedResource`
-
-| 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]` |
-
----
-
-## 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:
-
-#### 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
-
-```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;
-  }
-
-  async deleteSession(sessionId: string): Promise<void> {
-    const stmt = this.db.prepare(`DELETE FROM sessions WHERE id = ?`);
-    stmt.run(sessionId);
-  }
-
-  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(),
-  },
-  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
-    },
-    "github": {
-      "provider": "github",
-      "email": "alex.developer@example.com",
-      "providerUserId": "5829104",
-      "accessToken": "gho_8f7b2a9e1c3...",
-      "linkedAt": 1771657250000
-    }
-  }
-}
-```
-
----
-
-### 2. AWS DynamoDB Session Storage (`@aws-sdk/lib-dynamodb`)
-
-For serverless and distributed AWS deployments using DynamoDB:
-
-#### 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
-
-```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: { /* ... */ },
-});
-```
-
-#### 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
-      }
-    }
-  }
-}
+await lixa.unlinkAccount(activeSessionId, "github");
 ```
 
 ---
 
-## Custom Resource Storage Implementation (`ResourceStorage`)
+## Post-Login Resource Connection (AuthZ API)
 
-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.
+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**.
 
-### `ResourceStorage` Interface
+### Resource Connection Sequence
 
-```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>;
-}
-```
+```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
 
-### 1. SQLite Resource Storage (`better-sqlite3`)
+    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
 
-#### Table Schema (SQL DDL)
-
-```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)
-);
+    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
 ```
 
-#### TypeScript Implementation
+### Querying Connected Resource Access Tokens
 
 ```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;
-  }
-
-  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;
-  }
-
-  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());
-  }
-}
+// Query connected resource (automatically handles token refreshes)
+const resource = await lixa.getConnectedResource(sessionId, "github");
 
-// Pass to Lixa instance via resourceHandler
-export const lixa = new Lixa({
-  resourceHandler: {
-    resourceStorage: new SqliteResourceStorage(),
-  },
-  providers: { /* ... */ },
-});
-```
-
-#### 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
-  }
-}
-```
-
-**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
-  }
-}
-```
-
----
-
-### 2. AWS DynamoDB Resource Storage (`@aws-sdk/lib-dynamodb`)
-
-For serverless AWS deployments storing user API credentials in DynamoDB:
-
-#### Table Configuration
-
-- **Table Name**: `LixaUserResources`
-- **Partition Key (PK)**: `userId` (String)
-- **Sort Key (SK)**: `provider` (String)
-
-#### TypeScript Implementation
-
-```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(),
-        },
-      })
-    );
-  }
-
-  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: { /* ... */ },
-});
-```
-
-#### 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
-    }
-  }
-]
-```
-
----
-
-### 3. Querying Connected Resources Directly by User ID
-
-`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}` },
+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();
 }
 ```
 
 ---
 
-## User Info Utilities
-
-Lixa provides utilities to extract user information from OAuth tokens:
-
-```typescript
-import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
-
-const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
-console.log(userInfo.email, userInfo.name);
-```
-
----
-
 ## License
 
-[MIT](LICENSE)
+MIT © [Vunexa](https://github.com/vunexa)