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

package/README.md

@@ -1,311 +1,292 @@
-<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>
+# @vunexa/lixa
 
-# 🚀 Lixa (`@vunexa/lixa`)
+**A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for Node.js.**
 
-> **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.
+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?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)
+[![npm version](https://img.shields.io/npm/v/@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/)
+
+📖 **Full Documentation:** [lixa.vunexa.app](https://lixa.vunexa.app)
 
 ---
 
-## 📑 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)
+## 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)
 
 ---
 
-## 💡 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.
+## Why Lixa?
 
-**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.
+| 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 |
 
 ---
 
-## ✨ Key Features
+## Architecture Overview
+
+Lixa is organized into a lightweight, modular **2-package architecture**:
 
-- 🛡️ **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.
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     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           │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
 
 ---
 
-## 📐 Architecture & Sequence Diagrams
-
-### 1. Authentication Flow (AuthN)
-
-This sequence diagram illustrates how a user logs in via AWS Cognito (or Google/GitHub SSO), receives a secure session cookie, and benefits from Lixa's 2-minute memory cache:
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User as User Browser
-    participant Express as Express App (Lixa Middleware)
-    participant Lixa as Lixa Engine
-    participant Cache as In-Memory Cache (120s TTL)
-    participant DB as Prisma / Database
-    participant Cognito as AWS Cognito (OIDC / Hosted UI)
-
-    User->>Express: GET /api/v1/auth/login?provider=cognito
-    Express->>Lixa: getAuthUrl("cognito")
-    Lixa->>DB: Store state & PKCE codeVerifier in `oauth_states`
-    Lixa-->>Express: Return Authorization URL
-    Express-->>User: 302 Redirect to AWS Cognito
-
-    User->>Cognito: User signs in & consents
-    Cognito-->>User: 302 Redirect to /api/v1/auth/callback?code=...&state=...
-
-    User->>Express: GET /api/v1/auth/callback?code=...&state=...
-    Express->>Lixa: handleCallback("cognito", code, state)
-    Lixa->>DB: Validate & delete state from `oauth_states`
-    Lixa->>Cognito: Exchange code + PKCE verifier for tokens (AT, RT, idToken)
-    Cognito-->>Lixa: Return Cognito Tokens & User Claims
-    Lixa->>DB: Upsert normalized row in `sessions` (userId, AT, RT, idToken)
-    Lixa->>Cache: Cache session for 120 seconds
-    Lixa-->>Express: Issue Session ID (UUID)
-    Express-->>User: Set-Cookie: app_session=<sessionId>; HttpOnly; Secure
-
-    Note over User, Express: Subsequent Authenticated Requests
-    User->>Express: GET /api/v1/me (Cookie: app_session=...)
-    Express->>Cache: Check session in memory cache
-    alt Cache Hit (< 2 mins)
-        Cache-->>Express: Return cached session (0 DB queries!)
-    else Cache Miss / Expired
-        Express->>DB: Query `sessions` by id
-        DB-->>Express: Return session & refresh cache
-    end
-    Express-->>User: 200 OK (User Profile)
+## Installation
+
+```bash
+npm install @vunexa/lixa @vunexa/lixa-extensions
 ```
 
----
+```bash
+# yarn
+yarn add @vunexa/lixa @vunexa/lixa-extensions
 
-### 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
+# pnpm
+pnpm add @vunexa/lixa @vunexa/lixa-extensions
 ```
 
 ---
 
-### 3. Multi-SSO Account Linking
+## Quick Start
 
-Lixa automatically links multiple identity providers (e.g. AWS Cognito + Google) sharing the same verified email address:
+Get up and running with Google OAuth in under 5 minutes:
 
-```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.
-```
+```typescript
+import { Lixa } from "@vunexa/lixa";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-extensions/providers";
 
----
+// 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/auth/google/callback",
+      scopes: ["openid", "email", "profile"],
+    },
+    github: {
+      provider: new GithubProvider(),
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      redirectUri: "http://localhost:3000/auth/github/callback",
+      scopes: ["read:user", "user:email"],
+    },
+  },
+});
 
-## 📦 Installation
+// 2. Generate an authorization URL and redirect the user
+const authUrl = await lixa.getAuthUrl("google");
+// → Redirect user to authUrl
 
-```bash
-# Core framework & official extensions
-npm install @vunexa/lixa @vunexa/lixa-extensions
+// 3. Handle the callback after the user authorizes
+const sessionId = await lixa.handleCallback({
+  provider: "google",
+  code: "authorization_code_from_query",
+  state: "state_from_query",
+});
 
-# If using Prisma ORM (recommended)
-npm install @prisma/client
-npm install -D prisma
+// 4. Fetch session info anywhere in your app
+const session = await lixa.fetchSessionInfo(sessionId);
+// → { sessionId, userId, email, provider: "google", token, raw }
 ```
 
 ---
 
-## 🏁 Quickstart: AWS Cognito + Express + Prisma
+## Identity Providers
 
-Here is a complete, production-ready example configuring **AWS Cognito SSO**, **Prisma storage with 2-minute caching**, and **Express**.
+Lixa supports multiple identity backends for username/password authentication alongside OAuth SSO. Configure them via the `identityProvider` (or `identity`) field in `LixaConfig`.
 
-### Step 1: Database Schema (Prisma)
+### AWS Cognito
 
-Create or update your `prisma/schema.prisma` file with normalized primitive columns:
+The most mature integration. Communicates directly with AWS Cognito REST APIs — **zero AWS SDK dependency**.
 
-```prisma
-datasource db {
-  provider = "sqlite" // or "postgresql", "mysql"
-  url      = env("DATABASE_URL")
-}
+```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
+  }),
+});
 
-generator client {
-  provider = "prisma-client-js"
-}
+// 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" },
+    },
+  },
+});
 
-// 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")
-}
+const lixaWithSSO = new Lixa({
+  identity: cognito,
+  // cognito.getProviders() auto-registers 'cognito_sso', 'cognito_google', 'cognito_apple'
+});
+```
 
-// 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")
-}
+**Cognito API coverage:**
 
-// 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")
-}
+| 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` |
 
-// 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")
-}
-```
+**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
 
-Push the schema to your database:
-```bash
-npx prisma db push
+### Auth0
+
+```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
+  }),
+});
 ```
 
----
+### Okta
+
+```typescript
+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
+  }),
+});
+```
 
-### Step 2: Initialize Lixa & Storage with 2-Minute Cache
+### Self-Managed (Database)
 
-Create `src/config/lixa.ts`:
+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, CompositeIdentityProvider, AccountLinkingStrategy } from "@vunexa/lixa";
-import { CognitoIdentityProvider } from "@vunexa/lixa-extensions/identity";
-import { GoogleProvider, GithubProvider } from "@vunexa/lixa-extensions/providers";
+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,
+    },
+  },
+});
+```
 
-export const lixa = new Lixa({
-  // 1. Unified storage with automatic 2-minute (120s) in-memory cache
-  storage: createPrismaAdapter(prisma, {
-    enableCache: true,
-    cacheTtlSeconds: 120, // Cache session validations locally
-  }),
+### Composite (Multiple Backends)
 
-  // 2. Multi-SSO account linking strategy
-  accountLinking: {
-    mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
-    requireVerifiedEmail: true,
-  },
+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";
 
-  // 3. Composite Identity Provider (AWS Cognito + Social SSO)
+const lixa = new Lixa({
   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"
+        userPoolId: "us-east-1_xxx",
+        clientId: "your-client-id",
+        region: "us-east-1",
+      }),
+      "self-managed": new SelfManagedIdentityProvider({
+        /* credentials config */
       }),
     },
     oauthProviders: {
@@ -313,191 +294,427 @@ export const lixa = new Lixa({
         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"],
-        },
+        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" });
 ```
 
 ---
 
-### Step 3: Setup Express Server & Routes
+## OAuth / SSO Providers
+
+### Built-in Providers
 
-Create `src/server.ts`:
+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 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);
+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:
 
-// 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",
+```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"],
+    },
+  },
 });
-app.use("/api/v1/auth", authRouter);
 ```
 
 ---
 
-### Step 4: Protect Routes & Use Tokens
+## Credentials Authentication
+
+Sign up, sign in, change password, and forgot password — all through a unified API:
 
 ```typescript
-// 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,
-    },
-  });
+// 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!",
+});
+
+// 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!",
 });
 
-app.listen(3000, () => {
-  console.log("Server running at http://localhost:3000");
+// Verify credentials without creating a session
+const identity = await lixa.verifyCredentials({
+  identifier: "alice@example.com",
+  password: "ResetPassword789!",
 });
 ```
 
 ---
 
-## 🔌 Connecting External Resources (AuthZ)
+## 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, ... } }
+```
+
+---
+
+## Account Linking
 
-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.
+Automatically link multiple SSO accounts (Google + GitHub + Cognito) under a single user identity based on verified email:
 
 ```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);
+import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
+
+const lixa = new Lixa({
+  accountLinking: {
+    mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
+    requireVerifiedEmail: true, // default
+  },
+  providers: { /* ... */ },
 });
+```
+
+**Account linking strategies:**
+
+| 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 |
+
+**Manual account linking:**
+
+```typescript
+// Explicitly link a provider to an active session
+await lixa.linkAccount({ sessionId, provider: "github", code, state });
 
-// 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");
+// 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: { ... } }
+```
+
+---
+
+## Resource Connections (AuthZ)
+
+Connect third-party APIs (Google Drive, GitHub Repos) **post-login** with clean AuthN / AuthZ separation:
+
+```typescript
+// 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
+      },
+    },
+  },
 });
 
-// 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" });
-  }
+// 1. Generate resource auth URL (user must be logged in)
+const resourceUrl = await lixa.getResourceAuthUrl({
+  sessionId,
+  provider: "github",
+  scopes: ["repo", "read:org"],
+  prompt: "consent",
+});
 
-  // Call GitHub API with resource.accessToken
-  const response = await fetch("https://api.github.com/user/repos", {
-    headers: { Authorization: `Bearer ${resource.accessToken}` },
-  });
-  const repos = await response.json();
-  res.json({ repos });
+// 2. 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");
 ```
 
 ---
 
-## ⚡ In-Memory 2-Minute Caching (`withLocalCache`)
+## Database Storage
 
-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**:
+Lixa uses in-memory storage by default. For production, use the database adapters from `@vunexa/lixa-extensions`:
 
 ```typescript
-import { withLocalCache } from "@vunexa/lixa-extensions/storage";
+// 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,
+});
 
-// Automatically applied when using createPrismaAdapter
-const cachedStorage = withLocalCache(baseAdapter, {
-  ttlSeconds: 120, // 2 minutes (default)
+// Pass to Lixa
+const lixa = new Lixa({
+  storage,
+  providers: { /* ... */ },
 });
 ```
 
-### 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.
+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`.
 
 ---
 
-## 🌐 Supported Identity Providers
+## Express Integration
+
+Drop-in Express route handlers and middleware from `@vunexa/lixa-extensions/express`:
 
-| 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) |
+```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));
+```
 
 ---
 
-## 📚 TypeScript API Reference
+## Error Handling
 
-### `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).
+All Lixa errors extend `LixaError` with a `code` and optional `details`:
 
-### 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.
+```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 |
 
 ---
 
-## 🤝 Contributing & License
+## 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 |
+
+---
 
-Contributions are welcome! Please open an issue or pull request on GitHub.
+## License
 
-Distributed under the **MIT License**. See `LICENSE` for details.
+[MIT](https://opensource.org/licenses/MIT) © [Vunexa](https://vunexa.app)