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

package/README.md

@@ -1,47 +1,88 @@
 # @vunexa/lixa
 
-> Package is in active development.
+**A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for Node.js.**
+
+Lixa simplifies multi-provider authentication, identity management, and third-party resource authorization into a single, type-safe API. Use it with any OAuth provider — Google, GitHub, Microsoft, AWS Cognito, or your own custom provider — without being locked in to any vendor.
 
 [![npm version](https://img.shields.io/npm/v/@vunexa/lixa.svg)](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 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**.
+📖 **Full Documentation:** [lixa.vunexa.app](https://lixa.vunexa.app)
+
+---
+
+## Table of Contents
+
+- [Why Lixa?](#why-lixa)
+- [Architecture Overview](#architecture-overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Identity Providers](#identity-providers)
+  - [AWS Cognito](#aws-cognito)
+  - [Auth0](#auth0)
+  - [Okta](#okta)
+  - [Self-Managed (Database)](#self-managed-database)
+  - [Composite (Multiple Backends)](#composite-multiple-backends)
+- [OAuth / SSO Providers](#oauth--sso-providers)
+  - [Built-in Providers](#built-in-providers)
+  - [Custom Providers](#custom-providers)
+- [Credentials Authentication](#credentials-authentication)
+- [Session Management](#session-management)
+- [Account Linking](#account-linking)
+- [Resource Connections (AuthZ)](#resource-connections-authz)
+- [Database Storage](#database-storage)
+- [Express Integration](#express-integration)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [License](#license)
 
 ---
 
-## Features
+## Why Lixa?
 
-- **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.
+| Feature | Lixa |
+|---------|------|
+| **Provider-agnostic** | Works with any OAuth 2.0 / OIDC provider |
+| **Identity Management** | Built-in support for AWS Cognito, Auth0, Okta, or self-managed DB credentials |
+| **PKCE by default** | Every OAuth flow uses RFC 7636 PKCE (S256) automatically |
+| **AuthN / AuthZ separation** | Clean separation between login (identity) and post-login API access (resource connections) |
+| **Account linking** | Auto-link multiple SSO providers (Google + GitHub + Cognito) under a single user |
+| **Type-safe** | Full TypeScript with inferred provider keys and generic session types |
+| **Zero vendor lock-in** | No AWS SDK, no Auth0 SDK — just `fetch()` calls to standard APIs |
+| **Minimal dependencies** | Only `node-cache` as runtime dependency |
 
 ---
 
 ## Architecture Overview
 
-```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
+Lixa is organized into a lightweight, modular **2-package architecture**:
 
-    SessionStore -->|Session Cookie| Client
-    ResourceStore -->|Auto-Refreshed Tokens| Client
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     Your Application                         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │              @vunexa/lixa  (Core Engine)               │  │
+│  │                                                        │  │
+│  │  • Lixa class       • OAuth 2.0 + PKCE flows          │  │
+│  │  • IProvider        • Session / State management       │  │
+│  │  • IIdentityProvider • Credentials (scrypt hashing)    │  │
+│  │  • Account linking  • Resource connections (AuthZ)     │  │
+│  │  • Cookie utilities • Structured error hierarchy       │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                           ▲                                  │
+│                           │ peer dependency                  │
+│  ┌────────────────────────┴───────────────────────────────┐  │
+│  │         @vunexa/lixa-extensions  (Extensions)          │  │
+│  │                                                        │  │
+│  │  • OAuth Providers: Google, GitHub, Microsoft, Cognito │  │
+│  │  • Identity: CognitoIdentityProvider, Auth0, Okta      │  │
+│  │  • Storage: Prisma adapter, Drizzle adapter, Cache     │  │
+│  │  • HTTP: Express route handlers & middleware           │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -52,148 +93,628 @@ flowchart TD
 npm install @vunexa/lixa @vunexa/lixa-extensions
 ```
 
+```bash
+# yarn
+yarn add @vunexa/lixa @vunexa/lixa-extensions
+
+# pnpm
+pnpm add @vunexa/lixa @vunexa/lixa-extensions
+```
+
 ---
 
 ## Quick Start
 
-### 1. Configure Lixa Instance
+Get up and running with Google OAuth in under 5 minutes:
 
 ```typescript
-import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
+import { Lixa } 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({
-  // 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,
-  },
-
-  // Federated OAuth Providers
-  federatedOAuthProviders: {
+// 1. Create a Lixa instance with your providers
+const lixa = new Lixa({
+  providers: {
     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",
+      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/api/v1/oidc/github/callback",
+      redirectUri: "http://localhost:3000/auth/github/callback",
       scopes: ["read:user", "user:email"],
     },
   },
 });
+
+// 2. Generate an authorization URL and redirect the user
+const authUrl = await lixa.getAuthUrl("google");
+// → Redirect user to authUrl
+
+// 3. Handle the callback after the user authorizes
+const sessionId = await lixa.handleCallback({
+  provider: "google",
+  code: "authorization_code_from_query",
+  state: "state_from_query",
+});
+
+// 4. Fetch session info anywhere in your app
+const session = await lixa.fetchSessionInfo(sessionId);
+// → { sessionId, userId, email, provider: "google", token, raw }
 ```
 
 ---
 
-## Multi-SSO Account Linking
+## Identity Providers
+
+Lixa supports multiple identity backends for username/password authentication alongside OAuth SSO. Configure them via the `identityProvider` (or `identity`) field in `LixaConfig`.
+
+### AWS Cognito
+
+The most mature integration. Communicates directly with AWS Cognito REST APIs — **zero AWS SDK dependency**.
+
+```typescript
+import { Lixa, CompositeIdentityProvider } from "@vunexa/lixa";
+import { CognitoIdentityProvider } from "@vunexa/lixa-extensions/identity/cognito";
+import { GoogleProvider } from "@vunexa/lixa-extensions/providers";
+
+// Option A: Cognito-only (username/password via User Pool)
+const lixa = new Lixa({
+  identity: new CognitoIdentityProvider({
+    userPoolId: process.env.COGNITO_USER_POOL_ID!,
+    clientId: process.env.COGNITO_CLIENT_ID!,
+    region: "us-east-1",
+    clientSecret: process.env.COGNITO_CLIENT_SECRET, // optional
+  }),
+});
+
+// Option B: Cognito + Hosted UI federated SSO (Google, Apple, SAML, etc.)
+const cognito = new CognitoIdentityProvider({
+  userPoolId: process.env.COGNITO_USER_POOL_ID!,
+  clientId: process.env.COGNITO_CLIENT_ID!,
+  region: "us-east-1",
+  clientSecret: process.env.COGNITO_CLIENT_SECRET,
+  hostedUi: {
+    domain: "https://my-pool.auth.us-east-1.amazoncognito.com",
+    redirectUri: "http://localhost:3000/auth/cognito/callback",
+    federated: {
+      google: { identityProvider: "Google" },
+      apple: { identityProvider: "SignInWithApple" },
+    },
+  },
+});
+
+const lixaWithSSO = new Lixa({
+  identity: cognito,
+  // cognito.getProviders() auto-registers 'cognito_sso', 'cognito_google', 'cognito_apple'
+});
+```
 
-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.
+**Cognito API coverage:**
 
-### Account Linking Sequence
+| Method | Cognito API Action |
+|--------|--------------------|
+| `lixa.signUp()` | `SignUp` |
+| `lixa.signIn()` | `InitiateAuth` (USER_PASSWORD_AUTH) |
+| `lixa.confirmSignUp()` | `ConfirmSignUp` |
+| `lixa.resendConfirmationCode()` | `ResendConfirmationCode` |
+| `lixa.forgotPassword()` | `ForgotPassword` |
+| `lixa.confirmPasswordReset()` | `ConfirmForgotPassword` |
+| `lixa.changePassword()` | `InitiateAuth` → `ChangePassword` |
 
-```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
+**Features:**
+- Automatic `SecretHash` HMAC-SHA256 computation when `clientSecret` is configured
+- JWT ID token decoding for user profile extraction
+- Cognito error mapping to Lixa error types (`UsernameExistsException` → `UserAlreadyExistsError`, etc.)
+- Custom endpoint support for LocalStack, VPC endpoints, or mock servers
+- Hosted UI federated SSO with automatic provider registration
 
-    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
+### Auth0
 
-    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 { Auth0IdentityProvider } from "@vunexa/lixa-extensions/identity/auth0";
+
+const lixa = new Lixa({
+  identity: new Auth0IdentityProvider({
+    domain: "your-tenant.auth0.com",
+    clientId: process.env.AUTH0_CLIENT_ID!,
+    clientSecret: process.env.AUTH0_CLIENT_SECRET,
+    connection: "Username-Password-Authentication", // optional
+  }),
+});
 ```
 
-### Account Linking Usage
+### Okta
 
 ```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
+import { OktaIdentityProvider } from "@vunexa/lixa-extensions/identity/okta";
+
+const lixa = new Lixa({
+  identity: new OktaIdentityProvider({
+    orgUrl: "https://your-org.okta.com",
+    clientId: process.env.OKTA_CLIENT_ID,
+    apiToken: process.env.OKTA_API_TOKEN, // for admin operations
+  }),
+});
+```
+
+### Self-Managed (Database)
+
+Use your own database for user credentials — no external identity service needed. Includes Node.js native `crypto.scrypt` hashing, configurable password policies, and timing-attack-safe verification.
+
+```typescript
+import { Lixa } from "@vunexa/lixa";
+import { createPrismaAdapter } from "@vunexa/lixa-extensions/storage/prisma";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+const storage = createPrismaAdapter(prisma);
+
+const lixa = new Lixa({
+  storage,
+  credentials: {
+    policy: {
+      minLength: 10,
+      requireUppercase: true,
+      requireNumbers: true,
+      requireSpecialChars: true,
+    },
+  },
+});
+```
+
+### Composite (Multiple Backends)
+
+Combine multiple identity providers under a single Lixa instance:
+
+```typescript
+import { Lixa, CompositeIdentityProvider, SelfManagedIdentityProvider } from "@vunexa/lixa";
+import { CognitoIdentityProvider } from "@vunexa/lixa-extensions/identity/cognito";
+import { GoogleProvider } from "@vunexa/lixa-extensions/providers";
+
+const lixa = new Lixa({
+  identityProvider: new CompositeIdentityProvider({
+    defaultProvider: "cognito",
+    providers: {
+      cognito: new CognitoIdentityProvider({
+        userPoolId: "us-east-1_xxx",
+        clientId: "your-client-id",
+        region: "us-east-1",
+      }),
+      "self-managed": new SelfManagedIdentityProvider({
+        /* credentials config */
+      }),
+    },
+    oauthProviders: {
+      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"],
+      },
+    },
+  }),
+});
+
+// Route to a specific backend:
+await lixa.signIn({ identifier: "user@example.com", password: "pass", provider: "cognito" });
+```
+
+---
+
+## OAuth / SSO Providers
+
+### Built-in Providers
+
+Available from `@vunexa/lixa-extensions/providers`:
+
+| Provider | Class | Default Auth Scopes |
+|----------|-------|-------------------|
+| Google | `GoogleProvider` | `openid`, `profile`, `email` |
+| GitHub | `GithubProvider` | `read:user`, `user:email` |
+| Microsoft | `MicrosoftProvider` | `openid`, `profile`, `email`, `User.Read` |
+| AWS Cognito SSO | `CognitoSSOProvider` | `openid`, `email`, `profile` |
+
+```typescript
+import { GoogleProvider, GithubProvider, MicrosoftProvider, CognitoSSOProvider } from "@vunexa/lixa-extensions/providers";
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: new GoogleProvider(),
+      clientId: "...", clientSecret: "...", redirectUri: "...",
+      scopes: ["openid", "email", "profile"],
+    },
+    microsoft: {
+      provider: new MicrosoftProvider({ tenant: "common" }),
+      clientId: "...", clientSecret: "...", redirectUri: "...",
+      scopes: ["openid", "profile", "email", "User.Read"],
+    },
+  },
+});
+```
+
+### Custom Providers
+
+Integrate **any** OAuth 2.0 / OIDC provider by implementing the `IProvider` interface — just 3 URLs:
+
+```typescript
+import { type IProvider, Lixa } from "@vunexa/lixa";
+
+const discordProvider: IProvider = {
+  authorizationEndpoint: "https://discord.com/api/oauth2/authorize",
+  tokenEndpoint: "https://discord.com/api/oauth2/token",
+  userInfoEndpoint: "https://discord.com/api/users/@me",
+};
+
+const lixa = new Lixa({
+  providers: {
+    discord: {
+      provider: discordProvider,
+      clientId: "...", clientSecret: "...", redirectUri: "...",
+      scopes: ["identify", "email"],
+    },
+  },
+});
+```
+
+---
+
+## Credentials Authentication
+
+Sign up, sign in, change password, and forgot password — all through a unified API:
+
+```typescript
+// Sign up a new user
+const { user, sessionId } = await lixa.signUp({
+  identifier: "alice@example.com",
+  password: "SecurePassword123!",
+  email: "alice@example.com",
+  metadata: { name: "Alice Smith" },
+});
+
+// Sign in
+const { user, sessionId, session } = await lixa.signIn({
+  identifier: "alice@example.com",
+  password: "SecurePassword123!",
+});
+
+// Change password
+await lixa.changePassword({
+  identifier: "alice@example.com",
+  oldPassword: "SecurePassword123!",
+  newPassword: "NewSecurePassword456!",
 });
 
-// Unlink a provider account
-await lixa.unlinkAccount(activeSessionId, "github");
+// Forgot password flow
+const { deliveryMedium } = await lixa.forgotPassword({
+  identifier: "alice@example.com",
+});
+
+// Confirm password reset with verification code
+await lixa.confirmPasswordReset({
+  identifier: "alice@example.com",
+  confirmationCode: "123456",
+  newPassword: "ResetPassword789!",
+});
+
+// Verify credentials without creating a session
+const identity = await lixa.verifyCredentials({
+  identifier: "alice@example.com",
+  password: "ResetPassword789!",
+});
+```
+
+---
+
+## Session Management
+
+Lixa manages sessions with pluggable storage. By default, sessions are stored in-memory (suitable for development). For production, use a database adapter.
+
+```typescript
+// Fetch session info
+const session = await lixa.fetchSessionInfo(sessionId);
+// → { sessionId, userId, email, provider, token, raw }
+
+// Delete session (logout)
+await lixa.deleteSession(sessionId);
+```
+
+**Cookie utilities** are included for secure session cookie management:
+
+```typescript
+import {
+  createSessionCookie,
+  clearSessionCookie,
+  DEFAULT_SESSION_COOKIE_NAME,
+} from "@vunexa/lixa";
+
+// Create a session cookie (HttpOnly, Secure, SameSite=Lax)
+const cookie = createSessionCookie(sessionId);
+// → { name: "lixa_session", value: sessionId, options: { httpOnly, secure, ... } }
 ```
 
 ---
 
-## Post-Login Resource Connection (AuthZ API)
+## Account Linking
+
+Automatically link multiple SSO accounts (Google + GitHub + Cognito) under a single user identity based on verified email:
+
+```typescript
+import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
+
+const lixa = new Lixa({
+  accountLinking: {
+    mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
+    requireVerifiedEmail: true, // default
+  },
+  providers: { /* ... */ },
+});
+```
 
-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**.
+**Account linking strategies:**
 
-### Resource Connection Sequence
+| Strategy | Behavior |
+|----------|----------|
+| `AUTO_LINK_BY_VERIFIED_EMAIL` | Auto-merge accounts with the same verified email |
+| `ISOLATED` | Keep each provider login as a separate account (default) |
+| `STEP_UP_VERIFICATION` | Require password verification before linking a new provider |
 
-```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
+**Manual account linking:**
 
-    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
+```typescript
+// Explicitly link a provider to an active session
+await lixa.linkAccount({ sessionId, provider: "github", code, state });
 
-    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
+// Unlink a provider
+await lixa.unlinkAccount(sessionId, "github");
+
+// Get all linked accounts for a user
+const accounts = await lixa.getUserAccounts(sessionId);
+// → { google: { provider, email, linkedAt }, github: { ... } }
 ```
 
-### Querying Connected Resource Access Tokens
+---
+
+## Resource Connections (AuthZ)
+
+Connect third-party APIs (Google Drive, GitHub Repos) **post-login** with clean AuthN / AuthZ separation:
 
 ```typescript
-// Query connected resource (automatically handles token refreshes)
+// Configure scopes for resource authorization
+const lixa = new Lixa({
+  providers: {
+    github: {
+      provider: new GithubProvider(),
+      clientId: "...", clientSecret: "...", redirectUri: "...",
+      scopes: {
+        auth: ["read:user", "user:email"],          // login scopes
+        resource: ["repo", "read:org"],              // post-login API scopes
+      },
+    },
+  },
+});
+
+// 1. Generate resource auth URL (user must be logged in)
+const resourceUrl = await lixa.getResourceAuthUrl({
+  sessionId,
+  provider: "github",
+  scopes: ["repo", "read:org"],
+  prompt: "consent",
+});
+
+// 2. Handle resource callback
+const session = await lixa.handleResourceCallback({
+  sessionId,
+  provider: "github",
+  code: "auth_code",
+  state: "state_param",
+});
+
+// 3. Get connected resource token (auto-refreshes expired tokens)
 const resource = await lixa.getConnectedResource(sessionId, "github");
+// → { provider, accessToken, refreshToken, expiresAt, scopes, raw }
+
+// 4. Or fetch by user ID directly (session-independent)
+const resource = await lixa.getUserResource("user@example.com", "github");
+
+// 5. Disconnect a resource
+await lixa.disconnectResource(sessionId, "github");
+```
+
+---
+
+## Database Storage
+
+Lixa uses in-memory storage by default. For production, use the database adapters from `@vunexa/lixa-extensions`:
+
+```typescript
+// Prisma
+import { createPrismaAdapter } from "@vunexa/lixa-extensions/storage/prisma";
+const storage = createPrismaAdapter(new PrismaClient());
+
+// Drizzle
+import { createDrizzleAdapter } from "@vunexa/lixa-extensions/storage/drizzle";
+const storage = createDrizzleAdapter(db, {
+  sessions: schema.sessions,
+  userResources: schema.userResources,
+  oauthStates: schema.oauthStates,
+  userCredentials: schema.userCredentials,
+});
 
-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();
+// Pass to Lixa
+const lixa = new Lixa({
+  storage,
+  providers: { /* ... */ },
+});
+```
+
+The adapters include a built-in **2-minute in-memory TTL cache** to eliminate redundant database reads on rapid HTTP requests. Disable it with `{ enableCache: false }` (Prisma) or by not calling `withLocalCache`.
+
+---
+
+## Express Integration
+
+Drop-in Express route handlers and middleware from `@vunexa/lixa-extensions/express`:
+
+```typescript
+import {
+  handleLogin,
+  handleCallback,
+  handleLogout,
+  createRequireAuthMiddleware,
+  handleCredentialsSignUp,
+  handleCredentialsSignIn,
+} from "@vunexa/lixa-extensions/express";
+
+const requireAuth = createRequireAuthMiddleware(lixa);
+
+// OAuth SSO
+app.get("/login", (req, res) => handleLogin(req, res, lixa));
+app.get("/auth/:provider/callback", (req, res) =>
+  handleCallback(req, res, lixa, {
+    successRedirectUrl: "/dashboard",
+    errorRedirectUrl: "/login?error=auth_failed",
+  })
+);
+
+// Credentials (username/password)
+app.post("/auth/signup", (req, res) => handleCredentialsSignUp(req, res, lixa));
+app.post("/auth/signin", (req, res) => handleCredentialsSignIn(req, res, lixa));
+
+// Protected routes
+app.get("/profile", requireAuth, (req, res) => {
+  res.json({ user: req.sessionInfo });
+});
+
+// Logout
+app.post("/logout", (req, res) => handleLogout(req, res, lixa));
+```
+
+---
+
+## Error Handling
+
+All Lixa errors extend `LixaError` with a `code` and optional `details`:
+
+```typescript
+import {
+  LixaError,
+  InvalidCredentialsError,
+  UserAlreadyExistsError,
+  WeakPasswordError,
+  ProviderNotConfiguredError,
+  SessionNotFoundError,
+  AccountLinkingChallengeRequiredError,
+} from "@vunexa/lixa";
+
+try {
+  await lixa.signIn({ identifier: "user", password: "wrong" });
+} catch (error) {
+  if (error instanceof InvalidCredentialsError) {
+    // error.code === "INVALID_CREDENTIALS"
+  }
+  if (error instanceof WeakPasswordError) {
+    // error.validationErrors === ["Must be at least 10 characters", ...]
+  }
+  if (error instanceof AccountLinkingChallengeRequiredError) {
+    // error.challengeToken, error.email, error.existingProviders
+  }
 }
 ```
 
+**Error codes reference:**
+
+| Error Class | Code | When |
+|-------------|------|------|
+| `InvalidStateError` | `INVALID_STATE` | OAuth state expired or tampered |
+| `ProviderNotConfiguredError` | `PROVIDER_NOT_CONFIGURED` | Provider not in config |
+| `InvalidProviderConfigError` | `INVALID_PROVIDER_CONFIG` | Missing clientId/secret/redirectUri |
+| `TokenExchangeError` | `TOKEN_EXCHANGE_FAILED` | Code-to-token exchange failed |
+| `SessionNotFoundError` | `SESSION_NOT_FOUND` | Session expired or invalid |
+| `InvalidCredentialsError` | `INVALID_CREDENTIALS` | Wrong username/password |
+| `UserAlreadyExistsError` | `USER_ALREADY_EXISTS` | Duplicate registration |
+| `UserNotFoundError` | `USER_NOT_FOUND` | User not in database |
+| `WeakPasswordError` | `WEAK_PASSWORD` | Password policy violation |
+| `IdentityNotConfiguredError` | `CREDENTIALS_NOT_CONFIGURED` | No identity provider set |
+| `AccountLinkingChallengeRequiredError` | `ACCOUNT_LINKING_CHALLENGE_REQUIRED` | Step-up verification needed |
+| `SSOAccountAlreadyExistsError` | `SSO_ACCOUNT_EXISTS` | Email already has SSO account |
+| `AccountNotVerifiedError` | `ACCOUNT_NOT_VERIFIED` | Email not confirmed yet |
+| `RefreshTokenError` | `REFRESH_TOKEN_ERROR` | Token refresh failed |
+
+---
+
+## API Reference
+
+### `Lixa` Class
+
+**Constructor:** `new Lixa(config: LixaConfig)`
+
+| Config Property | Type | Description |
+|----------------|------|-------------|
+| `providers` | `Record<string, ProviderConfig>` | OAuth provider configurations |
+| `identityProvider` / `identity` | `IIdentityProvider \| IdentityConfig` | Identity backend (Cognito, Auth0, Okta, Self-Managed) |
+| `credentials` | `CredentialsConfig` | Self-managed credential settings (auto-creates SelfManagedIdentityProvider) |
+| `storage` | `StorageAdapter` | Unified database adapter (Prisma / Drizzle) |
+| `accountLinking` | `boolean \| AccountLinkingMode \| AccountLinkingConfig` | Multi-SSO account linking strategy |
+| `sessionCookieName` | `string \| ((lixa, req?) => string)` | Custom session cookie name |
+| `debug` | `boolean` | Enable structured debug logging |
+| `logger` | `LixaLogger` | Custom logger implementation |
+
+**OAuth Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getAuthUrl(provider, state?)` | `Promise<string>` | Generate authorization URL with PKCE |
+| `handleCallback({ provider, code, state })` | `Promise<string>` | Exchange code for tokens, create session |
+| `isProviderConfigured(provider)` | `boolean` | Check if a provider is configured |
+
+**Identity Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `signUp(params)` | `Promise<SignUpResult>` | Register a new user |
+| `signIn(params)` | `Promise<SignInResult>` | Authenticate with credentials |
+| `verifyCredentials(params)` | `Promise<UserIdentity \| null>` | Verify credentials without session |
+| `changePassword(params)` | `Promise<boolean>` | Update user password |
+| `forgotPassword(params)` | `Promise<ForgotPasswordResult>` | Initiate password reset |
+| `confirmPasswordReset(params)` | `Promise<boolean>` | Complete password reset |
+| `confirmSignUp(params)` | `Promise<boolean>` | Confirm registration with code |
+| `resendConfirmationCode(params)` | `Promise<ResendConfirmationCodeResult>` | Resend verification code |
+
+**Session & Account Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `fetchSessionInfo(sessionId)` | `Promise<Session \| null>` | Get active session details |
+| `deleteSession(sessionId)` | `Promise<void>` | Delete session (logout) |
+| `linkAccount(params)` | `Promise<string>` | Link new OAuth provider to session |
+| `unlinkAccount(sessionId, provider)` | `Promise<boolean>` | Unlink a provider account |
+| `getUserAccounts(userIdOrSessionId)` | `Promise<Record<string, LinkedAccount>>` | Get all linked accounts |
+
+**Resource Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getResourceAuthUrl(params)` | `Promise<string>` | Generate resource authorization URL |
+| `handleResourceCallback(params)` | `Promise<Session>` | Handle resource OAuth callback |
+| `getConnectedResource(sessionId, provider)` | `Promise<ConnectedResource \| null>` | Get resource token (auto-refreshes) |
+| `getUserResource(userId, provider)` | `Promise<ConnectedResource \| null>` | Get resource by user ID |
+| `disconnectResource(sessionId, provider)` | `Promise<boolean>` | Disconnect resource provider |
+
+**Static Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `Lixa.generateRandomState()` | `string` | Generate 32-char hex CSRF state |
+
 ---
 
 ## License
 
-MIT © [Vunexa](https://github.com/vunexa)
+[MIT](https://opensource.org/licenses/MIT) © [Vunexa](https://vunexa.app)