@vunexa/lixa 0.0.1-alpha.20 → 0.0.1-alpha.22

package/README.md

@@ -18,7 +18,8 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 - Custom provider registration with extensible provider interface
 - Extensible session management via pluggable strategies
 - PKCE (Proof Key for Code Exchange) support
-- TypeScript-first with strong typing and async/await support
+- TypeScript-first with full type safety (zero `any` types)
+- OAuth 2.0 and OpenID Connect spec-compliant types
 - 100% test coverage with comprehensive error handling
 
 ---
@@ -33,14 +34,22 @@ yarn add @vunexa/lixa
 
 ## Quick Start
 
-### 1. Configure lixa with multiple providers
+### 1. Install packages
+
+```bash
+npm install @vunexa/lixa @vunexa/lixa-providers
+```
+
+### 2. Configure Lixa with providers
 
 ```typescript
 import { Lixa } from "@vunexa/lixa";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-providers";
 
 const lixa = new Lixa({
   providers: {
     google: {
+      provider: new GoogleProvider(),
       clientId: process.env.GOOGLE_CLIENT_ID!,
       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
       redirectUri: "https://yourapp.com/auth/google/callback",
@@ -51,20 +60,21 @@ const lixa = new Lixa({
       },
     },
     github: {
+      provider: new GithubProvider(),
       clientId: process.env.GITHUB_CLIENT_ID!,
       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
       redirectUri: "https://yourapp.com/auth/github/callback",
       scopes: ["read:user", "user:email"],
-      extraConfig: {},
     },
   },
 
   // Optional: custom session strategy
   sessionStrategy: {
     createSession: async (tokenData) => {
-      // Custom session creation logic
+      // tokenData is typed as OAuthTokenResponse with proper OAuth 2.0 fields
+      // { access_token, token_type, expires_in?, refresh_token?, scope?, id_token? }
       return {
-        token: "custom-session-token",
+        token: tokenData.access_token,
         raw: tokenData,
       };
     },
@@ -72,22 +82,22 @@ const lixa = new Lixa({
 });
 ```
 
-### 2. Redirect users to the provider's authorization URL
+### 3. Redirect users to the provider's authorization URL
 
 ```typescript
 app.get("/login", (req, res) => {
   const provider = req.query.provider as string; // 'google' or 'github'
-  const state = lixa.generateRandomState();
+  const state = Lixa.generateRandomState();
 
   // Store state in session for validation
   req.session.oauthState = state;
 
-  const authUrl = lixa.getAuthUrl(provider.toUpperCase(), state);
+  const authUrl = lixa.getAuthUrl(provider, state);
   res.redirect(authUrl);
 });
 ```
 
-### 3. Handle the provider callback and establish a session
+### 4. Handle the provider callback and establish a session
 
 ```typescript
 app.get("/auth/:provider/callback", async (req, res) => {
@@ -100,14 +110,17 @@ app.get("/auth/:provider/callback", async (req, res) => {
       throw new Error("Invalid state parameter");
     }
 
-    const session = await lixa.handleCallback({
+    const sessionId = await lixa.handleCallback({
       provider,
       code: code as string,
       state: state as string,
     });
 
-    // Session established
-    res.cookie("session_token", session.token, {
+    // Session established - retrieve session info if needed
+    const session = await lixa.fetchSessionInfo(sessionId);
+
+    // Store session ID in cookie
+    res.cookie("session_id", sessionId, {
       httpOnly: true,
       secure: true,
       sameSite: "strict",
@@ -121,6 +134,118 @@ app.get("/auth/:provider/callback", async (req, res) => {
 });
 ```
 
+## Provider Configuration
+
+### Using Built-in Providers
+
+Built-in providers are available in the `@vunexa/lixa-providers` package:
+
+```typescript
+import { Lixa } from "@vunexa/lixa";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-providers";
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: new GoogleProvider(),
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/google/callback",
+      scopes: ["openid", "email", "profile"]
+    }
+  }
+});
+```
+
+### Using Custom Inline Providers
+
+You can create custom providers by implementing the `IProvider` interface:
+
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+
+// Define your custom provider
+const customProvider: IProvider = {
+  authorizationEndpoint: "https://provider.com/oauth/authorize",
+  tokenEndpoint: "https://provider.com/oauth/token",
+  userInfoEndpoint: "https://provider.com/api/user"
+};
+
+// Use it directly in configuration
+const lixa = new Lixa({
+  providers: {
+    custom: {
+      provider: customProvider,
+      clientId: "your-client-id",
+      clientSecret: "your-client-secret",
+      redirectUri: "https://yourapp.com/auth/custom/callback",
+      scopes: ["read:user"]
+    }
+  }
+});
+```
+
+### Mixing Built-in and Custom Providers
+
+You can use both built-in and custom providers in the same configuration:
+
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+import { GoogleProvider } from "@vunexa/lixa-providers";
+
+const customProvider: IProvider = {
+  authorizationEndpoint: "https://custom.com/oauth/authorize",
+  tokenEndpoint: "https://custom.com/oauth/token",
+  userInfoEndpoint: "https://custom.com/api/user"
+};
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: new GoogleProvider(),
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/google/callback",
+      scopes: ["openid", "email", "profile"]
+    },
+    custom: {
+      provider: customProvider,
+      clientId: process.env.CUSTOM_CLIENT_ID!,
+      clientSecret: process.env.CUSTOM_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/custom/callback",
+      scopes: ["read:user"]
+    }
+  }
+});
+```
+
+### Overriding Built-in Providers (Testing)
+
+You can override built-in providers with custom implementations for testing:
+
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+
+// Mock provider for testing
+const mockGoogleProvider: IProvider = {
+  authorizationEndpoint: "http://localhost:3000/mock/authorize",
+  tokenEndpoint: "http://localhost:3000/mock/token",
+  userInfoEndpoint: "http://localhost:3000/mock/userinfo"
+};
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: mockGoogleProvider, // Override with mock
+      clientId: "test-client-id",
+      clientSecret: "test-client-secret",
+      redirectUri: "http://localhost:3000/callback",
+      scopes: ["openid", "email"]
+    }
+  }
+});
+```
+
 ## Advanced Usage
 
 ### Custom State Storage (StateDao)
@@ -128,11 +253,11 @@ app.get("/auth/:provider/callback", async (req, res) => {
 By default, Lixa uses an in-memory cache for state management. For production applications or serverless environments, you should implement a custom state storage:
 
 ```typescript
-import { Lixa } from "@vunexa/lixa";
+import { Lixa, StateDao, StateData } from "@vunexa/lixa";
 
-// Example: DynamoDB state storage
-const dynamoDbStateDao = {
-  saveState: async (state: string, data: any, expiresInSeconds: number) => {
+// Example: DynamoDB state storage with proper typing
+const dynamoDbStateDao: StateDao = {
+  saveState: async (state: string, data: StateData, expiresInSeconds: number) => {
     await dynamoDB.put({
       TableName: "oauth-states",
       Item: {
@@ -143,7 +268,7 @@ const dynamoDbStateDao = {
     });
   },
   
-  getState: async (state: string) => {
+  getState: async (state: string): Promise<StateData | null> => {
     const result = await dynamoDB.get({
       TableName: "oauth-states",
       Key: { state },
@@ -155,7 +280,7 @@ const dynamoDbStateDao = {
       return null; // Expired
     }
     
-    return JSON.parse(result.Item.data);
+    return JSON.parse(result.Item.data) as StateData;
   },
   
   deleteState: async (state: string) => {
@@ -172,15 +297,22 @@ const lixa = new Lixa({
 });
 ```
 
-**Important**: The state data includes a `codeVerifier` field required for PKCE. Make sure your storage preserves all fields in the data object.
+**Important**: The `StateData` type includes required fields:
+- `provider` (string): Provider name for callback routing
+- `codeVerifier` (string): PKCE code verifier (64 hex characters)
+- `createdAt` (number): Unix timestamp in milliseconds
+
+Make sure your storage preserves all fields in the data object.
 
 ### Custom Session Storage (SessionDao)
 
-Similar to state storage, you can implement custom session storage:
+Similar to state storage, you can implement custom session storage with proper typing:
 
 ```typescript
-const customSessionDao = {
-  saveSession: async (sessionId: string, session: any, expiresInSeconds: number) => {
+import { Lixa, SessionDao, Session } from "@vunexa/lixa";
+
+const customSessionDao: SessionDao = {
+  saveSession: async <T = unknown>(sessionId: string, session: T, expiresInSeconds: number) => {
     // Store session in your database
     await db.sessions.create({
       id: sessionId,
@@ -189,12 +321,12 @@ const customSessionDao = {
     });
   },
   
-  getSession: async (sessionId: string) => {
+  getSession: async <T = unknown>(sessionId: string): Promise<T | null> => {
     const session = await db.sessions.findById(sessionId);
     if (!session || session.expiresAt < Date.now()) {
       return null;
     }
-    return session.data;
+    return session.data as T;
   },
   
   deleteSession: async (sessionId: string) => {
@@ -210,12 +342,29 @@ const lixa = new Lixa({
 
 ### Custom Session Strategy
 
-The session strategy controls how user sessions are created from OAuth tokens:
+The session strategy controls how user sessions are created from OAuth tokens. The `tokenData` parameter is typed as `OAuthTokenResponse` with proper OAuth 2.0 fields:
 
 ```typescript
-const customSessionStrategy = {
-  createSession: async (tokenData) => {
-    // tokenData contains: access_token, refresh_token, id_token, etc.
+import { Lixa, SessionStrategy, OAuthTokenResponse, Session } from "@vunexa/lixa";
+
+// Define custom session data structure
+interface CustomSessionData extends OAuthTokenResponse {
+  userId: string;
+  userInfo: {
+    email: string;
+    name: string;
+  };
+}
+
+const customSessionStrategy: SessionStrategy = {
+  createSession: async (tokenData: OAuthTokenResponse): Promise<Session<CustomSessionData>> => {
+    // tokenData is properly typed with OAuth 2.0 fields:
+    // - access_token: string (required)
+    // - token_type: string (required)
+    // - expires_in?: number
+    // - refresh_token?: string
+    // - scope?: string
+    // - id_token?: string (for OIDC providers)
     
     // Decode ID token to get user info (for OIDC providers like Google)
     let userInfo;
@@ -275,9 +424,11 @@ Debug mode logs:
 - Session creation
 - Error details from OAuth providers
 
-### Custom Provider Registration
+### Legacy Provider Registration (Deprecated)
 
-You can register custom OAuth providers by implementing the `IProvider` interface:
+> **Note**: This pattern is deprecated. Use inline providers instead (see examples above).
+
+For backward compatibility, you can still register providers globally:
 
 ```typescript
 import { Lixa, IProvider } from "@vunexa/lixa";
@@ -293,7 +444,7 @@ Lixa.registerProvider({
   custom: new CustomProvider(),
 });
 
-// Use it in your configuration
+// Use it in your configuration (without provider field)
 const lixa = new Lixa({
   providers: {
     custom: {
@@ -306,17 +457,17 @@ const lixa = new Lixa({
 });
 ```
 
-### Check Provider Registration
+### Check Provider Configuration
 
 ```typescript
-// Check if a provider is registered
-if (Lixa.isProviderRegistered("google")) {
-  console.log("Google provider is available");
+// Check if a provider is configured for this instance
+if (lixa.isProviderConfigured("google")) {
+  console.log("Google provider is configured");
 }
 
-// Get list of all registered providers
+// Get list of all registered providers (legacy)
 const providers = Lixa.getRegisteredProviders();
-console.log("Available providers:", providers);
+console.log("Registered providers:", providers);
 ```
 
 ## Common Pitfalls & Solutions
@@ -368,21 +519,30 @@ saveState: async (state: string, data: any, expiresInSeconds: number) => {
 **Solution**: Decode the `id_token` (for OIDC providers) or fetch user info from the provider's API:
 
 ```typescript
-createSession: async (tokenData) => {
-  // For OIDC providers (Google, etc.)
-  if (tokenData.id_token) {
-    const base64Payload = tokenData.id_token.split('.')[1];
-    const userInfo = JSON.parse(Buffer.from(base64Payload, 'base64').toString());
-  }
-  
-  // For OAuth-only providers (GitHub, etc.)
-  else if (tokenData.access_token) {
-    const response = await fetch(providerUserInfoEndpoint, {
-      headers: { Authorization: `Bearer ${tokenData.access_token}` }
-    });
-    const userInfo = await response.json();
+import { SessionStrategy, OAuthTokenResponse } from "@vunexa/lixa";
+
+const strategy: SessionStrategy = {
+  createSession: async (tokenData: OAuthTokenResponse) => {
+    // For OIDC providers (Google, etc.) - id_token is properly typed
+    if (tokenData.id_token) {
+      const base64Payload = tokenData.id_token.split('.')[1];
+      const userInfo = JSON.parse(Buffer.from(base64Payload, 'base64').toString());
+    }
+    
+    // For OAuth-only providers (GitHub, etc.) - access_token is guaranteed to exist
+    else {
+      const response = await fetch(providerUserInfoEndpoint, {
+        headers: { Authorization: `Bearer ${tokenData.access_token}` }
+      });
+      const userInfo = await response.json();
+    }
+    
+    return {
+      token: tokenData.access_token,
+      raw: tokenData
+    };
   }
-}
+};
 ```
 
 ## API Reference
@@ -395,54 +555,77 @@ createSession: async (tokenData) => {
 
 #### Static Methods
 
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers before creating instances
-- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
-- `Lixa.getRegisteredProviders(): string[]` - Get list of all registered provider names
-- `Lixa.generateRandomState(): string` - Generate a cryptographically secure random state string
+- `Lixa.generateRandomState(): string` - Generate a cryptographically secure random state string for CSRF protection
+- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - **[Deprecated]** Register custom providers globally. Use inline providers instead.
+- `Lixa.getRegisteredProviders(): string[]` - **[Deprecated]** Get list of all registered provider names from legacy registry
 
 #### Instance Methods
 
-- `getAuthUrl(provider: string, state: string): string` - Generate authorization URL for a provider. Automatically stores state with PKCE code verifier.
-- `handleCallback({ provider, code, state }): Promise<string>` - Handle OAuth callback, validate state, exchange code for tokens, and create session. Returns session ID.
-- `fetchSessionInfo(sessionId: string): Promise<Session | null>` - Retrieve session information by session ID
+- `getAuthUrl(provider: string, state: string): string` - Generate authorization URL for a provider. Automatically generates PKCE code verifier and challenge, stores state with code verifier for later validation.
+- `handleCallback({ provider, code, state }): Promise<string>` - Handle OAuth callback, validate state parameter, retrieve PKCE code verifier, exchange authorization code for tokens, and create session using SessionStrategy. Returns session ID.
+- `fetchSessionInfo(sessionId: string): Promise<Session | null>` - Retrieve session information by session ID from SessionDao.
+- `isProviderConfigured(provider: string): boolean` - Check if a provider is configured for this Lixa instance. Useful for type guards and runtime validation.
 
 ### Types
 
+All types are fully typed with zero `any` types, following OAuth 2.0 and OpenID Connect specifications:
+
 ```typescript
-interface ProviderConfig {
+// OAuth 2.0 token response (RFC 6749 Section 5.1)
+interface OAuthTokenResponse {
+  access_token: string;           // Required: OAuth access token
+  token_type: string;             // Required: Token type (usually "Bearer")
+  expires_in?: number;            // Optional: Token expiration in seconds
+  refresh_token?: string;         // Optional: Refresh token
+  scope?: string;                 // Optional: Granted scopes (space-separated)
+  id_token?: string;              // Optional: OpenID Connect ID token (JWT)
+  [key: string]: unknown;         // Additional provider-specific fields
+}
+
+// Provider configuration with inline provider support
+type ProviderConfig = {
   clientId: string;
   clientSecret: string;
   redirectUri: string;
   scopes: string[];
-  extraConfig?: Record<string, any>; // Provider-specific parameters
-}
-
-interface LixaConfig {
-  providers: Record<string, ProviderConfig>;
+  extraConfig?: Record<string, string>;
+} & (
+  | { provider?: never }        // Built-in provider (no provider field)
+  | { provider: IProvider }     // Custom provider (provider field required)
+);
+
+interface LixaConfig<TProviders = Record<string, ProviderConfig>> {
+  providers: TProviders;
   sessionStrategy?: SessionStrategy;
-  stateDao?: StateDao; // Custom state storage
-  sessionDao?: SessionDao; // Custom session storage
-  debug?: boolean; // Enable debug logging
+  stateDao?: StateDao;
+  sessionDao?: SessionDao;
+  debug?: boolean;
 }
 
 interface SessionStrategy {
-  createSession(tokenData: any): Promise<Session>;
+  createSession(tokenData: OAuthTokenResponse): Promise<Session>;
+}
+
+interface Session<TRaw = OAuthTokenResponse> {
+  token: string;
+  raw: TRaw;  // Defaults to OAuthTokenResponse, can be extended
 }
 
-interface Session {
-  token: string; // Your custom session identifier
-  raw: any; // Raw data you want to store with the session
+interface StateData {
+  provider: string;       // Provider name for routing
+  codeVerifier: string;   // PKCE code verifier (64 hex chars)
+  createdAt: number;      // Unix timestamp in milliseconds
 }
 
 interface StateDao {
-  saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
-  getState(state: string): Promise<any | null>;
+  saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+  getState(state: string): Promise<StateData | null>;
   deleteState(state: string): Promise<void>;
 }
 
 interface SessionDao {
-  saveSession(sessionId: string, session: Session, expiresInSeconds: number): Promise<void>;
-  getSession(sessionId: string): Promise<Session | null>;
+  saveSession<T = unknown>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
+  getSession<T = unknown>(sessionId: string): Promise<T | null>;
   deleteSession(sessionId: string): Promise<void>;
 }
 
@@ -455,21 +638,321 @@ interface IProvider {
 
 ## Built-in Providers
 
-### Google
+Built-in providers are available in the `@vunexa/lixa-providers` package:
+
+```bash
+npm install @vunexa/lixa-providers
+```
+
+### Google (`GoogleProvider`)
+
+```typescript
+import { GoogleProvider } from "@vunexa/lixa-providers";
+```
+
 - **Type**: OAuth 2.0 + OpenID Connect (OIDC)
 - **Authorization Endpoint**: `https://accounts.google.com/o/oauth2/v2/auth`
 - **Token Endpoint**: `https://oauth2.googleapis.com/token`
 - **User Info Endpoint**: `https://www.googleapis.com/oauth2/v2/userinfo`
 - **Supports**: PKCE, ID tokens, refresh tokens
-- **Common Scopes**: `openid`, `email`, `profile`
+- **Common Scopes**: 
+  - `openid` - Required for OpenID Connect
+  - `email` - Access to user's email address
+  - `profile` - Access to user's basic profile information
+  - `https://www.googleapis.com/auth/drive.readonly` - Read-only access to Google Drive
+  - `https://www.googleapis.com/auth/calendar.readonly` - Read-only access to Google Calendar
+
+[Full list of Google OAuth scopes](https://developers.google.com/identity/protocols/oauth2/scopes)
+
+### GitHub (`GithubProvider`)
+
+```typescript
+import { GithubProvider } from "@vunexa/lixa-providers";
+```
 
-### GitHub
 - **Type**: OAuth 2.0
 - **Authorization Endpoint**: `https://github.com/login/oauth/authorize`
 - **Token Endpoint**: `https://github.com/login/oauth/access_token`
 - **User Info Endpoint**: `https://api.github.com/user`
 - **Supports**: PKCE
-- **Common Scopes**: `read:user`, `user:email`
+- **Common Scopes**:
+  - `user` - Read/write access to profile info
+  - `user:email` - Read access to user's email addresses
+  - `read:user` - Read-only access to profile info
+  - `repo` - Full control of private repositories
+  - `public_repo` - Access to public repositories
+  - `gist` - Create gists
+  - `read:org` - Read-only access to organization membership
+
+[Full list of GitHub OAuth scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)
+
+## Extensibility Interfaces
+
+### SessionStrategy Interface
+
+The `SessionStrategy` interface allows you to customize how OAuth tokens are converted into application sessions. The `tokenData` parameter is fully typed as `OAuthTokenResponse`:
+
+```typescript
+interface SessionStrategy {
+  createSession(tokenData: OAuthTokenResponse): Promise<Session>;
+}
+
+interface Session<TRaw = OAuthTokenResponse> {
+  token: string;  // Your session identifier
+  raw: TRaw;      // Session data (defaults to OAuthTokenResponse)
+}
+
+interface OAuthTokenResponse {
+  access_token: string;    // Required
+  token_type: string;      // Required
+  expires_in?: number;     // Optional
+  refresh_token?: string;  // Optional
+  scope?: string;          // Optional
+  id_token?: string;       // Optional (OIDC)
+  [key: string]: unknown;  // Provider-specific fields
+}
+```
+
+**Use cases:**
+- Decode ID tokens for user information
+- Create or update users in your database
+- Generate custom session identifiers
+- Store tokens securely
+- Add custom claims or metadata
+
+**Example with database integration and proper typing:**
+```typescript
+import { SessionStrategy, OAuthTokenResponse, Session } from "@vunexa/lixa";
+
+interface CustomSessionData extends OAuthTokenResponse {
+  userId: string;
+}
+
+const dbSessionStrategy: SessionStrategy = {
+  createSession: async (tokenData: OAuthTokenResponse): Promise<Session<CustomSessionData>> => {
+    // tokenData is properly typed with OAuth 2.0 fields
+    // TypeScript will catch errors like tokenData.id_tokn (typo)
+    
+    // Decode ID token (for OIDC providers)
+    const payload = tokenData.id_token 
+      ? decodeJwt(tokenData.id_token)
+      : null;
+    
+    // Create/update user
+    const user = await db.users.upsert({
+      email: payload?.email,
+      name: payload?.name
+    });
+    
+    // Generate session
+    const sessionId = generateId();
+    await db.sessions.create({
+      id: sessionId,
+      userId: user.id,
+      accessToken: tokenData.access_token,
+      refreshToken: tokenData.refresh_token,
+      expiresAt: tokenData.expires_in 
+        ? new Date(Date.now() + tokenData.expires_in * 1000)
+        : null
+    });
+    
+    return {
+      token: sessionId,
+      raw: { 
+        ...tokenData,
+        userId: user.id 
+      }
+    };
+  }
+};
+```
+
+### StateDao Interface
+
+The `StateDao` interface manages OAuth state storage for CSRF protection and PKCE:
+
+```typescript
+interface StateDao {
+  saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+  getState(state: string): Promise<StateData | null>;
+  deleteState(state: string): Promise<void>;
+}
+
+interface StateData {
+  provider: string;      // Provider name for routing
+  codeVerifier: string;  // PKCE code verifier (64 hex chars)
+  createdAt: number;     // Unix timestamp in milliseconds
+}
+```
+
+**Required fields:**
+- `provider`: Used to route callbacks to the correct provider configuration
+- `codeVerifier`: Required for PKCE token exchange (RFC 7636)
+- `createdAt`: Timestamp for debugging and validation
+
+**Example with Redis:**
+```typescript
+const redisStateDao: StateDao = {
+  saveState: async (state, data, expiresInSeconds) => {
+    await redis.setex(
+      `oauth:state:${state}`,
+      expiresInSeconds,
+      JSON.stringify(data)
+    );
+  },
+  
+  getState: async (state) => {
+    const data = await redis.get(`oauth:state:${state}`);
+    return data ? JSON.parse(data) : null;
+  },
+  
+  deleteState: async (state) => {
+    await redis.del(`oauth:state:${state}`);
+  }
+};
+```
+
+### SessionDao Interface
+
+The `SessionDao` interface manages persistent user session storage with generic typing for flexibility:
+
+```typescript
+interface SessionDao {
+  saveSession<T = unknown>(sessionId: string, data: T, expiresInSeconds: number): Promise<void>;
+  getSession<T = unknown>(sessionId: string): Promise<T | null>;
+  deleteSession(sessionId: string): Promise<void>;
+}
+```
+
+**Example with database and proper typing:**
+```typescript
+import { SessionDao, Session } from "@vunexa/lixa";
+
+const dbSessionDao: SessionDao = {
+  saveSession: async <T = unknown>(sessionId: string, data: T, expiresInSeconds: number) => {
+    const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+    await db.sessions.create({
+      id: sessionId,
+      data: JSON.stringify(data),
+      expiresAt
+    });
+  },
+  
+  getSession: async <T = unknown>(sessionId: string): Promise<T | null> => {
+    const session = await db.sessions.findOne({
+      id: sessionId,
+      expiresAt: { $gt: new Date() }
+    });
+    return session ? JSON.parse(session.data) as T : null;
+  },
+  
+  deleteSession: async (sessionId: string) => {
+    await db.sessions.delete({ id: sessionId });
+  }
+};
+```
+
+## PKCE Implementation
+
+Lixa automatically implements **PKCE (Proof Key for Code Exchange)** according to [RFC 7636](https://tools.ietf.org/html/rfc7636) for all OAuth flows.
+
+### How it Works
+
+1. **Code Verifier Generation**
+   - Generates 32 cryptographically random bytes
+   - Encodes as 64-character hexadecimal string
+   - Example: `a1b2c3d4e5f6...` (64 chars)
+
+2. **Code Challenge Generation**
+   - Creates SHA-256 hash of the code verifier
+   - Encodes as base64url (RFC 4648)
+   - Sends with authorization request
+
+3. **Token Exchange**
+   - Retrieves code verifier from state storage
+   - Sends original code verifier with token request
+   - Provider validates: `SHA256(code_verifier) === code_challenge`
+
+### Security Benefits
+
+- **Prevents authorization code interception**: Even if an attacker intercepts the authorization code, they cannot exchange it for tokens without the code verifier
+- **No client secret required**: PKCE works without client secrets, making it suitable for public clients
+- **Standards compliant**: Follows RFC 7636 specification
+
+### Debug Logging
+
+Enable debug mode to see PKCE flow details:
+
+```typescript
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  debug: true
+});
+```
+
+Debug output includes:
+- `[Lixa] [timestamp] [INFO] [Auth]` - Code verifier and challenge generation
+- `[Lixa] [timestamp] [INFO] [State]` - State storage with code verifier
+- `[Lixa] [timestamp] [INFO] [Token]` - Token exchange with code verifier
+
+## Migration Guide
+
+### Migrating from Legacy Registration Pattern
+
+**Old Pattern (Deprecated):**
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+import { GoogleProvider } from "@vunexa/lixa";
+
+// Step 1: Register providers globally
+Lixa.registerProvider({
+  google: new GoogleProvider()
+});
+
+// Step 2: Configure with credentials only
+const lixa = new Lixa({
+  providers: {
+    google: {
+      clientId: "...",
+      clientSecret: "...",
+      redirectUri: "...",
+      scopes: ["openid", "email"]
+    }
+  }
+});
+```
+
+**New Pattern (Recommended):**
+```typescript
+import { Lixa } from "@vunexa/lixa";
+import { GoogleProvider } from "@vunexa/lixa-providers";
+
+// Single step: Pass provider inline
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: new GoogleProvider(),  // ← Add this line
+      clientId: "...",
+      clientSecret: "...",
+      redirectUri: "...",
+      scopes: ["openid", "email"]
+    }
+  }
+});
+```
+
+**Migration Steps:**
+1. Install `@vunexa/lixa-providers`: `npm install @vunexa/lixa-providers`
+2. Update imports: `import { GoogleProvider } from "@vunexa/lixa-providers"`
+3. Remove `Lixa.registerProvider()` calls
+4. Add `provider` field to each provider configuration
+5. Test your OAuth flows
+
+**Benefits:**
+- ✅ No global state - each Lixa instance is independent
+- ✅ Better testability - easy to mock providers per instance
+- ✅ Clearer configuration - everything in one place
+- ✅ Type safety - TypeScript knows which providers are configured
 
 ## Security Considerations