@vunexa/lixa 0.0.1-alpha.29 → 0.0.1-alpha.33

package/README.md

@@ -13,14 +13,16 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 
 ## Features
 
-- Multi-provider OAuth/OIDC support with unified API
-- Built-in support for popular providers like Google and GitHub
-- Custom provider registration with extensible provider interface
-- Extensible session management via pluggable strategies
-- PKCE (Proof Key for Code Exchange) 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
+- **Multi-provider OAuth/OIDC support** with unified API
+- **Built-in providers** for Google, GitHub, and more via `@vunexa/lixa-providers`
+- **Custom provider support** with extensible provider interface
+- **Unified session management** via `SessionHandler` (generation + storage in one place)
+- **Unified state management** via `StateHandler` (generation + storage in one place)
+- **Automatic PKCE** (Proof Key for Code Exchange) for all OAuth flows
+- **User info utilities** for extracting user data from OAuth tokens
+- **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
 
 ---
 
@@ -68,9 +70,10 @@ const lixa = new Lixa({
     },
   },
 
-  // Optional: custom session strategy
-  sessionStrategy: {
-    createSession: async (tokenData) => {
+  // Optional: custom session handler
+  sessionHandler: {
+    // Optional: customize session generation
+    generateSession: async (tokenData, providerMetadata) => {
       // tokenData is typed as OAuthTokenResponse with proper OAuth 2.0 fields
       // { access_token, token_type, expires_in?, refresh_token?, scope?, id_token? }
       return {
@@ -78,6 +81,19 @@ const lixa = new Lixa({
         raw: tokenData,
       };
     },
+    // Optional: custom session storage
+    sessionStorage: {
+      saveSession: async (sessionId, session, ttl) => {
+        await db.sessions.create({ id: sessionId, data: session, expiresAt: Date.now() + ttl * 1000 });
+      },
+      getSession: async (sessionId) => {
+        const session = await db.sessions.findOne({ id: sessionId });
+        return session?.data || null;
+      },
+      deleteSession: async (sessionId) => {
+        await db.sessions.delete({ id: sessionId });
+      },
+    },
   },
 });
 ```
@@ -85,14 +101,11 @@ const lixa = new Lixa({
 ### 3. Redirect users to the provider's authorization URL
 
 ```typescript
-app.get("/login", (req, res) => {
+app.get("/login", async (req, res) => {
   const provider = req.query.provider as string; // 'google' or 'github'
-  const state = Lixa.generateRandomState();
-
-  // Store state in session for validation
-  req.session.oauthState = state;
 
-  const authUrl = lixa.getAuthUrl(provider, state);
+  // getAuthUrl automatically generates state if not provided
+  const authUrl = await lixa.getAuthUrl(provider);
   res.redirect(authUrl);
 });
 ```
@@ -105,11 +118,7 @@ app.get("/auth/:provider/callback", async (req, res) => {
   const provider = req.params.provider;
 
   try {
-    // Validate state parameter
-    if (state !== req.session.oauthState) {
-      throw new Error("Invalid state parameter");
-    }
-
+    // State validation is handled automatically by lixa
     const sessionId = await lixa.handleCallback({
       provider,
       code: code as string,
@@ -248,15 +257,15 @@ const lixa = new Lixa({
 
 ## Advanced Usage
 
-### Custom State Storage (StateDao)
+### Custom State Handler
 
-By default, Lixa uses an in-memory cache for state management. For production applications or serverless environments, you should implement a custom state storage:
+By default, Lixa uses an in-memory cache for state management. For production applications or serverless environments, you should implement a custom state handler:
 
 ```typescript
-import { Lixa, StateDao, StateData } from "@vunexa/lixa";
+import { Lixa, StateHandler, StateStorage, StateData } from "@vunexa/lixa";
 
-// Example: DynamoDB state storage with proper typing
-const dynamoDbStateDao: StateDao = {
+// Example: DynamoDB state storage
+const dynamoDbStateStorage: StateStorage = {
   saveState: async (state: string, data: StateData, expiresInSeconds: number) => {
     await dynamoDB.put({
       TableName: "oauth-states",
@@ -293,27 +302,32 @@ const dynamoDbStateDao: StateDao = {
 
 const lixa = new Lixa({
   providers: { /* ... */ },
-  stateDao: dynamoDbStateDao,
+  stateHandler: {
+    stateStorage: dynamoDbStateStorage,
+    // Optional: customize state generation
+    // generateState: async (provider) => { ... }
+  },
 });
 ```
 
-**Important**: The `StateData` type includes required fields:
+**StateHandler Properties:**
+- `stateStorage` (optional): Custom storage for OAuth state (save/get/delete operations)
+- `generateState` (optional): Custom state and PKCE verifier generation
+
+**StateData 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)
+### Custom Session Handler
 
-Similar to state storage, you can implement custom session storage with proper typing:
+The session handler manages both session generation and storage. You can customize either or both:
 
 ```typescript
-import { Lixa, SessionDao, Session } from "@vunexa/lixa";
+import { Lixa, SessionHandler, SessionStorage, extractUserInfo } from "@vunexa/lixa";
 
-const customSessionDao: SessionDao = {
+const customSessionStorage: SessionStorage = {
   saveSession: async <T = unknown>(sessionId: string, session: T, expiresInSeconds: number) => {
-    // Store session in your database
     await db.sessions.create({
       id: sessionId,
       data: session,
@@ -336,16 +350,39 @@ const customSessionDao: SessionDao = {
 
 const lixa = new Lixa({
   providers: { /* ... */ },
-  sessionDao: customSessionDao,
+  sessionHandler: {
+    // Optional: customize session generation
+    generateSession: async (tokenData, providerMetadata) => {
+      // Extract user info from OAuth tokens
+      const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+      
+      // Create or update user in database
+      const user = await db.users.upsert({
+        email: userInfo.email,
+        name: userInfo.name,
+      });
+      
+      return {
+        token: tokenData.access_token,
+        raw: { ...tokenData, userId: user.id },
+      };
+    },
+    // Optional: custom session storage
+    sessionStorage: customSessionStorage,
+  },
 });
 ```
 
-### Custom Session Strategy
+**SessionHandler Properties:**
+- `generateSession` (optional): Customize how OAuth tokens are converted to session data
+- `sessionStorage` (optional): Custom storage for sessions (save/get/delete operations)
+
+### Custom Session Generation
 
-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:
+The `generateSession` method controls how user sessions are created from OAuth tokens:
 
 ```typescript
-import { Lixa, SessionStrategy, OAuthTokenResponse, Session } from "@vunexa/lixa";
+import { Lixa, SessionHandler, OAuthTokenResponse, Session, extractUserInfo } from "@vunexa/lixa";
 
 // Define custom session data structure
 interface CustomSessionData extends OAuthTokenResponse {
@@ -356,8 +393,8 @@ interface CustomSessionData extends OAuthTokenResponse {
   };
 }
 
-const customSessionStrategy: SessionStrategy = {
-  createSession: async (tokenData: OAuthTokenResponse): Promise<Session<CustomSessionData>> => {
+const customSessionHandler: SessionHandler = {
+  generateSession: async (tokenData: OAuthTokenResponse, providerMetadata): Promise<Session<CustomSessionData>> => {
     // tokenData is properly typed with OAuth 2.0 fields:
     // - access_token: string (required)
     // - token_type: string (required)
@@ -366,13 +403,8 @@ const customSessionStrategy: SessionStrategy = {
     // - scope?: string
     // - id_token?: string (for OIDC providers)
     
-    // Decode ID token to get user info (for OIDC providers like Google)
-    let userInfo;
-    if (tokenData.id_token) {
-      const base64Payload = tokenData.id_token.split('.')[1];
-      const payload = Buffer.from(base64Payload, 'base64').toString();
-      userInfo = JSON.parse(payload);
-    }
+    // Extract user info using lixa's utility
+    const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
     
     // Create or update user in your database
     const user = await db.users.upsert({
@@ -381,17 +413,8 @@ const customSessionStrategy: SessionStrategy = {
       // ... other fields
     });
     
-    // Create session in your database
-    const sessionId = generateUniqueId();
-    await db.sessions.create({
-      id: sessionId,
-      userId: user.id,
-      accessToken: tokenData.access_token,
-      refreshToken: tokenData.refresh_token,
-    });
-    
     return {
-      token: sessionId,
+      token: tokenData.access_token,
       raw: {
         ...tokenData,
         userId: user.id,
@@ -399,11 +422,25 @@ const customSessionStrategy: SessionStrategy = {
       },
     };
   },
+  
+  // Optional: custom storage
+  sessionStorage: {
+    saveSession: async (sessionId, session, ttl) => {
+      await db.sessions.create({ id: sessionId, data: session, expiresAt: Date.now() + ttl * 1000 });
+    },
+    getSession: async (sessionId) => {
+      const session = await db.sessions.findOne({ id: sessionId });
+      return session?.data || null;
+    },
+    deleteSession: async (sessionId) => {
+      await db.sessions.delete({ id: sessionId });
+    },
+  },
 };
 
 const lixa = new Lixa({
   providers: { /* ... */ },
-  sessionStrategy: customSessionStrategy,
+  sessionHandler: customSessionHandler,
 });
 ```
 
@@ -476,21 +513,36 @@ console.log("Registered providers:", providers);
 
 **Cause**: The state parameter is not being stored or retrieved correctly.
 
-**Solution**: Implement a custom `stateDao` that persists state across requests. The default in-memory cache doesn't work in serverless or multi-instance environments.
+**Solution**: Implement a custom `stateHandler` with persistent storage. The default in-memory cache doesn't work in serverless or multi-instance environments.
+
+```typescript
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  stateHandler: {
+    stateStorage: {
+      saveState: async (state, data, ttl) => await redis.setex(state, ttl, JSON.stringify(data)),
+      getState: async (state) => JSON.parse(await redis.get(state) || 'null'),
+      deleteState: async (state) => await redis.del(state),
+    },
+  },
+});
+```
 
 ### 2. "Missing code verifier" Error
 
 **Cause**: The `codeVerifier` field is not being preserved in your state storage.
 
-**Solution**: Ensure your `stateDao.saveState()` stores ALL fields from the data object, including `codeVerifier`:
+**Solution**: Ensure your `stateStorage.saveState()` stores ALL fields from the data object, including `codeVerifier`:
 
 ```typescript
-saveState: async (state: string, data: any, expiresInSeconds: number) => {
-  // ✅ Correct: Store the entire data object
-  await storage.save({ state, data, expiresAt: ... });
-  
-  // ❌ Wrong: Only storing some fields
-  await storage.save({ state, provider: data.provider, expiresAt: ... });
+stateStorage: {
+  saveState: async (state: string, data: StateData, expiresInSeconds: number) => {
+    // ✅ Correct: Store the entire data object
+    await storage.save({ state, data, expiresAt: ... });
+    
+    // ❌ Wrong: Only storing some fields
+    await storage.save({ state, provider: data.provider, expiresAt: ... });
+  }
 }
 ```
 
@@ -510,32 +562,37 @@ saveState: async (state: string, data: any, expiresInSeconds: number) => {
 
 **Cause**: Using default in-memory session storage in serverless/distributed environments.
 
-**Solution**: Implement a custom `sessionDao` that uses persistent storage (database, Redis, etc.).
+**Solution**: Implement a custom `sessionHandler` with persistent storage (database, Redis, etc.):
+
+```typescript
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  sessionHandler: {
+    sessionStorage: {
+      saveSession: async (id, session, ttl) => await db.sessions.create({ id, session, ttl }),
+      getSession: async (id) => await db.sessions.findOne({ id }),
+      deleteSession: async (id) => await db.sessions.delete({ id }),
+    },
+  },
+});
+```
 
 ### 5. User Info is Undefined
 
-**Cause**: The `sessionStrategy.createSession()` receives raw token data, not user info.
+**Cause**: The `generateSession()` receives raw token data, not user info.
 
-**Solution**: Decode the `id_token` (for OIDC providers) or fetch user info from the provider's API:
+**Solution**: Use lixa's `extractUserInfo()` utility to automatically extract user info:
 
 ```typescript
-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());
-    }
+import { SessionHandler, extractUserInfo } from "@vunexa/lixa";
+
+const sessionHandler: SessionHandler = {
+  generateSession: async (tokenData, providerMetadata) => {
+    // Automatically extracts user info from ID token or fetches from API
+    const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
     
-    // 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();
-    }
+    // Now you have user info
+    console.log(userInfo.email, userInfo.name);
     
     return {
       token: tokenData.access_token,
@@ -556,9 +613,9 @@ High-level function that automatically extracts user information from OAuth toke
 ```typescript
 import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
 
-// In your session strategy
-const sessionStrategy = {
-  createSession: async (tokenData, providerMetadata) => {
+// In your session handler
+const sessionHandler = {
+  generateSession: async (tokenData, providerMetadata) => {
     // Automatically extracts user info from ID token or fetches from API
     const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
     
@@ -684,8 +741,8 @@ const lixa = new Lixa({
     }
   },
   
-  sessionStrategy: {
-    createSession: async (tokenData, providerMetadata) => {
+  sessionHandler: {
+    generateSession: async (tokenData, providerMetadata) => {
       // Extract user info - works for both Google (ID token) and GitHub (API fetch)
       const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
       
@@ -701,26 +758,32 @@ const lixa = new Lixa({
         emailVerified: userInfo.email_verified,
       });
       
-      // Create session
-      const sessionId = generateUniqueId();
-      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,
+        token: tokenData.access_token,
         raw: {
           ...tokenData,
           userId: user.id,
         }
       };
-    }
+    },
+    sessionStorage: {
+      saveSession: async (sessionId, session, ttl) => {
+        await db.sessions.create({
+          id: sessionId,
+          userId: session.raw.userId,
+          accessToken: session.raw.access_token,
+          refreshToken: session.raw.refresh_token,
+          expiresAt: new Date(Date.now() + ttl * 1000),
+        });
+      },
+      getSession: async (sessionId) => {
+        const session = await db.sessions.findOne({ id: sessionId });
+        return session ? { token: session.accessToken, raw: session } : null;
+      },
+      deleteSession: async (sessionId) => {
+        await db.sessions.delete({ id: sessionId });
+      },
+    },
   }
 });
 ```
@@ -744,15 +807,14 @@ const lixa = new Lixa({
 
 #### Static Methods
 
-- `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 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.
+- `getAuthUrl(provider: string, state?: string): Promise<string>` - Generate authorization URL for a provider. Automatically generates state if not provided, creates 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 SessionHandler. Returns session ID.
+- `fetchSessionInfo(sessionId: string): Promise<Session | null>` - Retrieve session information by session ID from SessionHandler storage.
 - `isProviderConfigured(provider: string): boolean` - Check if a provider is configured for this Lixa instance. Useful for type guards and runtime validation.
 
 ### Types
@@ -785,14 +847,34 @@ type ProviderConfig = {
 
 interface LixaConfig<TProviders = Record<string, ProviderConfig>> {
   providers: TProviders;
-  sessionStrategy?: SessionStrategy;
-  stateDao?: StateDao;
-  sessionDao?: SessionDao;
+  sessionHandler?: SessionHandler;
+  stateHandler?: StateHandler;
   debug?: boolean;
 }
 
-interface SessionStrategy {
-  createSession(tokenData: OAuthTokenResponse): Promise<Session>;
+interface SessionHandler {
+  generateSession?<T extends Session>(
+    tokenData: OAuthTokenResponse,
+    providerMetadata: ProviderMetadata
+  ): Promise<T>;
+  sessionStorage?: SessionStorage;
+}
+
+interface SessionStorage {
+  saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
+  getSession<T extends Session>(sessionId: string): Promise<T | null>;
+  deleteSession(sessionId: string): Promise<void>;
+}
+
+interface StateHandler {
+  generateState?(provider: string): Promise<{ state: string; data: StateData }>;
+  stateStorage?: StateStorage;
+}
+
+interface StateStorage {
+  saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+  getState(state: string): Promise<StateData | null>;
+  deleteState(state: string): Promise<void>;
 }
 
 interface Session<TRaw = OAuthTokenResponse> {
@@ -806,16 +888,13 @@ interface StateData {
   createdAt: number;      // Unix timestamp in milliseconds
 }
 
-interface StateDao {
-  saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
-  getState(state: string): Promise<StateData | null>;
-  deleteState(state: string): Promise<void>;
-}
-
-interface SessionDao {
-  saveSession<T = unknown>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
-  getSession<T = unknown>(sessionId: string): Promise<T | null>;
-  deleteSession(sessionId: string): Promise<void>;
+interface ProviderMetadata {
+  name: string;
+  endpoints: {
+    authorization: string;
+    token: string;
+    userInfo: string;
+  };
 }
 
 interface IProvider {
@@ -877,13 +956,23 @@ import { GithubProvider } from "@vunexa/lixa-providers";
 
 ## Extensibility Interfaces
 
-### SessionStrategy Interface
+### SessionHandler Interface
 
-The `SessionStrategy` interface allows you to customize how OAuth tokens are converted into application sessions. The `tokenData` parameter is fully typed as `OAuthTokenResponse`:
+The `SessionHandler` interface allows you to customize session generation and storage:
 
 ```typescript
-interface SessionStrategy {
-  createSession(tokenData: OAuthTokenResponse): Promise<Session>;
+interface SessionHandler {
+  generateSession?<T extends Session>(
+    tokenData: OAuthTokenResponse,
+    providerMetadata: ProviderMetadata
+  ): Promise<T>;
+  sessionStorage?: SessionStorage;
+}
+
+interface SessionStorage {
+  saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
+  getSession<T extends Session>(sessionId: string): Promise<T | null>;
+  deleteSession(sessionId: string): Promise<void>;
 }
 
 interface Session<TRaw = OAuthTokenResponse> {
@@ -900,68 +989,84 @@ interface OAuthTokenResponse {
   id_token?: string;       // Optional (OIDC)
   [key: string]: unknown;  // Provider-specific fields
 }
+
+interface ProviderMetadata {
+  name: string;
+  endpoints: {
+    authorization: string;
+    token: string;
+    userInfo: string;
+  };
+}
 ```
 
 **Use cases:**
-- Decode ID tokens for user information
+- Extract user info from OAuth tokens
 - Create or update users in your database
-- Generate custom session identifiers
-- Store tokens securely
+- Store tokens securely in your database
 - Add custom claims or metadata
+- Implement custom session storage (Redis, database, etc.)
 
-**Example with database integration and proper typing:**
+**Example with database integration:**
 ```typescript
-import { SessionStrategy, OAuthTokenResponse, Session } from "@vunexa/lixa";
+import { SessionHandler, OAuthTokenResponse, Session, extractUserInfo } 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;
+const dbSessionHandler: SessionHandler = {
+  generateSession: async (tokenData: OAuthTokenResponse, providerMetadata): Promise<Session<CustomSessionData>> => {
+    // Extract user info using lixa's utility
+    const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
     
     // 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
+      email: userInfo.email,
+      name: userInfo.name
     });
     
     return {
-      token: sessionId,
+      token: tokenData.access_token,
       raw: { 
         ...tokenData,
         userId: user.id 
       }
     };
-  }
+  },
+  
+  sessionStorage: {
+    saveSession: async (sessionId, session, ttl) => {
+      await db.sessions.create({
+        id: sessionId,
+        userId: session.raw.userId,
+        accessToken: session.raw.access_token,
+        refreshToken: session.raw.refresh_token,
+        expiresAt: new Date(Date.now() + ttl * 1000),
+      });
+    },
+    getSession: async (sessionId) => {
+      const session = await db.sessions.findOne({ id: sessionId });
+      return session ? { token: session.accessToken, raw: session } : null;
+    },
+    deleteSession: async (sessionId) => {
+      await db.sessions.delete({ id: sessionId });
+    },
+  },
 };
 ```
 
-### StateDao Interface
+### StateHandler Interface
 
-The `StateDao` interface manages OAuth state storage for CSRF protection and PKCE:
+The `StateHandler` interface manages OAuth state generation and storage for CSRF protection and PKCE:
 
 ```typescript
-interface StateDao {
+interface StateHandler {
+  generateState?(provider: string): Promise<{ state: string; data: StateData }>;
+  stateStorage?: StateStorage;
+}
+
+interface StateStorage {
   saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
   getState(state: string): Promise<StateData | null>;
   deleteState(state: string): Promise<void>;
@@ -974,60 +1079,62 @@ interface StateData {
 }
 ```
 
-**Required fields:**
+**StateData 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}`);
+const redisStateHandler: StateHandler = {
+  stateStorage: {
+    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
+### SessionStorage Interface
 
-The `SessionDao` interface manages persistent user session storage with generic typing for flexibility:
+The `SessionStorage` interface manages persistent user session storage:
 
 ```typescript
-interface SessionDao {
-  saveSession<T = unknown>(sessionId: string, data: T, expiresInSeconds: number): Promise<void>;
-  getSession<T = unknown>(sessionId: string): Promise<T | null>;
+interface SessionStorage {
+  saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
+  getSession<T extends Session>(sessionId: string): Promise<T | null>;
   deleteSession(sessionId: string): Promise<void>;
 }
 ```
 
-**Example with database and proper typing:**
+**Example with database:**
 ```typescript
-import { SessionDao, Session } from "@vunexa/lixa";
+import { SessionStorage, Session } from "@vunexa/lixa";
 
-const dbSessionDao: SessionDao = {
-  saveSession: async <T = unknown>(sessionId: string, data: T, expiresInSeconds: number) => {
+const dbSessionStorage: SessionStorage = {
+  saveSession: async <T extends Session>(sessionId: string, session: T, expiresInSeconds: number) => {
     const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
     await db.sessions.create({
       id: sessionId,
-      data: JSON.stringify(data),
+      data: JSON.stringify(session),
       expiresAt
     });
   },
   
-  getSession: async <T = unknown>(sessionId: string): Promise<T | null> => {
+  getSession: async <T extends Session>(sessionId: string): Promise<T | null> => {
     const session = await db.sessions.findOne({
       id: sessionId,
       expiresAt: { $gt: new Date() }
@@ -1084,65 +1191,6 @@ Debug output includes:
 - `[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
 
 ### PKCE (Proof Key for Code Exchange)