@vunexa/lixa 0.1.4 → 0.1.6-alpha.10

package/README.md

@@ -17,8 +17,7 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 - **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.
-- **Built-in providers** for Google, GitHub, and more via `@vunexa/lixa-providers`.
-- **Custom provider support** with extensible provider interface.
+- **Pre-built Database Storage Adapters**: Official Prisma and Drizzle ORM adapters via `@vunexa/lixa-adapters` with support for PostgreSQL, MySQL, and SQLite.
 - **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.
@@ -187,15 +186,16 @@ app.get("/connect/github/callback", async (req, res) => {
   res.redirect("/dashboard");
 });
 
-// 3. Query Connected Resource Access Token
+// 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 resource access token
+  // Call GitHub API with active resource access token
   const response = await fetch("https://api.github.com/user/repos", {
     headers: { Authorization: `Bearer ${resource.accessToken}` },
   });
@@ -204,7 +204,10 @@ app.get("/api/github/repos", async (req, res) => {
   res.json(repos);
 });
 
-// 4. Disconnect Resource Provider
+// 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 });
@@ -220,26 +223,26 @@ export interface Session<TRaw = OAuthTokenResponse> {
   /** Unique session ID generated by Lixa */
   id?: string;
 
-  /** Primary access token or session token */
-  token: string;
-
   /** Unified user ID across linked accounts */
   userId?: string;
 
   /** Primary user email */
   email?: string;
 
-  /** Current active auth provider */
-  provider?: string;
-
-  /** Linked SSO provider accounts (AuthN) */
+  /** Linked SSO provider accounts (AuthN) - Single Source of Truth */
   accounts?: Record<string, LinkedAccount>;
 
-  /** Connected third-party resource provider tokens (AuthZ) */
+  /** Connected third-party resource provider tokens (AuthZ) - Single Source of Truth */
   resources?: Record<string, ConnectedResource>;
 
-  /** Full raw token response from provider */
-  raw: TRaw;
+  /** Optional primary access token or session token */
+  token?: string;
+
+  /** Optional current active auth provider */
+  provider?: string;
+
+  /** Optional raw token response from provider */
+  raw?: TRaw;
 }
 ```
 
@@ -252,6 +255,518 @@ export interface Session<TRaw = OAuthTokenResponse> {
 
 ---
 
+## 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
+      }
+    }
+  }
+}
+```
+
+---
+
+## 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
+
+```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)
+
+```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)
+);
+```
+
+#### 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;
+  }
+
+  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());
+  }
+}
+
+// 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}` },
+  });
+}
+```
+
+---
+
 ## User Info Utilities
 
 Lixa provides utilities to extract user information from OAuth tokens: