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

package/README.md

@@ -13,13 +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 strong typing and async/await support
-- 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
 
 ---
 
@@ -33,61 +36,81 @@ 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 { 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'],
+      redirectUri: "https://yourapp.com/auth/google/callback",
+      scopes: ["openid", "email", "profile"],
       extraConfig: {
-        prompt: 'consent',
-        access_type: 'offline',
+        prompt: "consent",
+        access_type: "offline",
       },
     },
     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: {},
+      redirectUri: "https://yourapp.com/auth/github/callback",
+      scopes: ["read:user", "user:email"],
     },
   },
 
-  // Optional: custom session strategy
-  sessionStrategy: {
-    createSession: async (tokenData) => {
-      // Custom session creation logic
+  // 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 {
-        token: 'custom-session-token',
-        raw: tokenData
+        token: tokenData.access_token,
+        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 });
+      },
+    },
   },
 });
 ```
 
-### 2. Redirect users to the provider's authorization URL
+### 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.toUpperCase(), state);
+
+  // getAuthUrl automatically generates state if not provided
+  const authUrl = await lixa.getAuthUrl(provider);
   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) => {
@@ -95,24 +118,23 @@ 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');
-    }
-
-    const session = await lixa.handleCallback({
+    // State validation is handled automatically by lixa
+    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'
+      sameSite: "strict",
     });
-    
+
     res.redirect("/dashboard");
   } catch (error) {
     console.error("Authentication error:", error);
@@ -121,87 +143,758 @@ 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 Provider Registration
+### Custom State Handler
 
-You can register custom OAuth providers by implementing the `IProvider` interface:
+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, IProvider } from '@vunexa/lixa';
+import { Lixa, StateHandler, StateStorage, StateData } from "@vunexa/lixa";
+
+// Example: DynamoDB state storage
+const dynamoDbStateStorage: StateStorage = {
+  saveState: async (state: string, data: StateData, expiresInSeconds: number) => {
+    await dynamoDB.put({
+      TableName: "oauth-states",
+      Item: {
+        state,
+        data: JSON.stringify(data),
+        expiresAt: Math.floor(Date.now() / 1000) + expiresInSeconds,
+      },
+    });
+  },
+  
+  getState: async (state: string): Promise<StateData | null> => {
+    const result = await dynamoDB.get({
+      TableName: "oauth-states",
+      Key: { state },
+    });
+    
+    if (!result.Item) return null;
+    
+    if (result.Item.expiresAt < Math.floor(Date.now() / 1000)) {
+      return null; // Expired
+    }
+    
+    return JSON.parse(result.Item.data) as StateData;
+  },
+  
+  deleteState: async (state: string) => {
+    await dynamoDB.delete({
+      TableName: "oauth-states",
+      Key: { state },
+    });
+  },
+};
+
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  stateHandler: {
+    stateStorage: dynamoDbStateStorage,
+    // Optional: customize state generation
+    // generateState: async (provider) => { ... }
+  },
+});
+```
+
+**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
+
+### Custom Session Handler
+
+The session handler manages both session generation and storage. You can customize either or both:
+
+```typescript
+import { Lixa, SessionHandler, SessionStorage, extractUserInfo } from "@vunexa/lixa";
+
+const customSessionStorage: SessionStorage = {
+  saveSession: async <T = unknown>(sessionId: string, session: T, expiresInSeconds: number) => {
+    await db.sessions.create({
+      id: sessionId,
+      data: session,
+      expiresAt: Date.now() + expiresInSeconds * 1000,
+    });
+  },
+  
+  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 as T;
+  },
+  
+  deleteSession: async (sessionId: string) => {
+    await db.sessions.delete(sessionId);
+  },
+};
+
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  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,
+  },
+});
+```
+
+**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 `generateSession` method controls how user sessions are created from OAuth tokens:
+
+```typescript
+import { Lixa, SessionHandler, OAuthTokenResponse, Session, extractUserInfo } from "@vunexa/lixa";
+
+// Define custom session data structure
+interface CustomSessionData extends OAuthTokenResponse {
+  userId: string;
+  userInfo: {
+    email: string;
+    name: string;
+  };
+}
+
+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)
+    // - expires_in?: number
+    // - refresh_token?: string
+    // - scope?: string
+    // - id_token?: string (for OIDC providers)
+    
+    // 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({
+      email: userInfo.email,
+      name: userInfo.name,
+      // ... other fields
+    });
+    
+    return {
+      token: tokenData.access_token,
+      raw: {
+        ...tokenData,
+        userId: user.id,
+        userInfo,
+      },
+    };
+  },
+  
+  // 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: { /* ... */ },
+  sessionHandler: customSessionHandler,
+});
+```
+
+### Debug Mode
+
+Enable debug logging to troubleshoot OAuth flows:
+
+```typescript
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  debug: true, // Enables detailed logging
+});
+```
+
+Debug mode logs:
+- Token exchange requests and responses
+- State validation
+- Session creation
+- Error details from OAuth providers
+
+### Legacy Provider Registration (Deprecated)
+
+> **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";
 
 class CustomProvider implements IProvider {
-  authorizationEndpoint = 'https://custom-provider.com/oauth/authorize';
-  tokenEndpoint = 'https://custom-provider.com/oauth/token';
-  userInfoEndpoint = 'https://custom-provider.com/api/user';
+  authorizationEndpoint = "https://custom-provider.com/oauth/authorize";
+  tokenEndpoint = "https://custom-provider.com/oauth/token";
+  userInfoEndpoint = "https://custom-provider.com/api/user";
 }
 
-// Register the custom provider
+// Register the custom provider BEFORE creating Lixa instance
 Lixa.registerProvider({
-  custom: new CustomProvider()
+  custom: new CustomProvider(),
 });
 
-// Use it in your configuration
+// Use it in your configuration (without provider field)
 const lixa = new Lixa({
   providers: {
     custom: {
-      clientId: 'your-client-id',
-      clientSecret: 'your-client-secret',
-      redirectUri: 'https://yourapp.com/auth/custom/callback',
-      scopes: ['read:user'],
-    }
+      clientId: "your-client-id",
+      clientSecret: "your-client-secret",
+      redirectUri: "https://yourapp.com/auth/custom/callback",
+      scopes: ["read:user"],
+    },
+  },
+});
+```
+
+### Check Provider Configuration
+
+```typescript
+// 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 (legacy)
+const providers = Lixa.getRegisteredProviders();
+console.log("Registered providers:", providers);
+```
+
+## Common Pitfalls & Solutions
+
+### 1. "Invalid or expired state" Error
+
+**Cause**: The state parameter is not being stored or retrieved correctly.
+
+**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 `stateStorage.saveState()` stores ALL fields from the data object, including `codeVerifier`:
+
+```typescript
+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: ... });
   }
+}
+```
+
+### 3. Token Exchange Fails with 400 Bad Request
+
+**Causes**:
+- Redirect URI mismatch between your config and OAuth provider console
+- Invalid client ID or secret
+- Code has already been used or expired
+
+**Solution**: 
+- Enable debug mode to see the exact error from the provider
+- Verify redirect URI matches exactly (including protocol, port, path)
+- Check that client credentials are correct
+
+### 4. Session Not Found After Creation
+
+**Cause**: Using default in-memory session storage in serverless/distributed environments.
+
+**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 }),
+    },
+  },
 });
 ```
 
-### Check Provider Registration
+### 5. User Info is Undefined
+
+**Cause**: The `generateSession()` receives raw token data, not user info.
+
+**Solution**: Use lixa's `extractUserInfo()` utility to automatically extract user info:
 
 ```typescript
-// Check if a provider is registered
-if (Lixa.isProviderRegistered('google')) {
-  console.log('Google provider is available');
+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);
+    
+    // Now you have user info
+    console.log(userInfo.email, userInfo.name);
+    
+    return {
+      token: tokenData.access_token,
+      raw: tokenData
+    };
+  }
+};
+```
+
+## User Info Utilities
+
+Lixa provides utilities to extract user information from OAuth tokens, making it easier to work with user data across different providers.
+
+### `extractUserInfo()`
+
+High-level function that automatically extracts user information from OAuth token data:
+
+```typescript
+import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
+
+// 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);
+    
+    console.log(`User ${userInfo.email} authenticated`);
+    
+    // Create user in database
+    const user = await db.users.upsert({
+      email: userInfo.email,
+      name: userInfo.name,
+      givenName: userInfo.given_name,
+      familyName: userInfo.family_name,
+      picture: userInfo.picture,
+    });
+    
+    return {
+      token: generateSessionId(),
+      raw: { ...tokenData, userId: user.id }
+    };
+  }
+};
+```
+
+**Parameters:**
+- `tokenData` (OAuthTokenResponse) - OAuth token response from provider
+- `providerMetadata` (ProviderMetadata) - Provider metadata containing endpoints configuration
+
+**Returns:**
+- `{ userInfo: UserInfo }` - User information extracted from token or fetched from provider
+
+**Behavior:**
+1. If ID token present: Decodes JWT and extracts user info (OIDC providers like Google)
+2. If only access token: Fetches from userinfo endpoint using `providerMetadata.endpoints.userInfo` (OAuth providers like GitHub)
+3. Automatically determines the best method based on available token data
+4. Throws clear errors if neither ID token nor access token is available
+
+### `decodeIdToken()`
+
+Decode JWT ID tokens to extract user information:
+
+```typescript
+import { decodeIdToken, type UserInfo } from "@vunexa/lixa";
+
+const userInfo: UserInfo = decodeIdToken(tokenData.id_token);
+console.log(userInfo.email, userInfo.name);
+```
+
+**Use case:** When you know the provider returns an ID token (OIDC providers like Google)
+
+### `fetchUserInfo()`
+
+Fetch user information from a provider's userinfo endpoint:
+
+```typescript
+import { fetchUserInfo, type UserInfo } from "@vunexa/lixa";
+
+const userInfo: UserInfo = await fetchUserInfo(
+  tokenData.access_token,
+  'https://www.googleapis.com/oauth2/v2/userinfo',
+  'google'  // Optional: for error messages
+);
+```
+
+**Use case:** When you need to fetch user info from the API (OAuth-only providers like GitHub, or when ID token is not available)
+
+### `determineProviderFromIssuer()`
+
+Detect OAuth provider from ID token issuer field:
+
+```typescript
+import { determineProviderFromIssuer, decodeIdToken } from "@vunexa/lixa";
+
+const userInfo = decodeIdToken(tokenData.id_token);
+const provider = determineProviderFromIssuer(userInfo);
+// Returns: 'google', 'github', or null if unknown
+```
+
+**Supported providers:**
+- Google: Detects `accounts.google.com` in issuer
+- GitHub: Detects `github` in issuer
+- Returns `null` for unknown issuers
+
+**Note:** This utility is primarily for informational purposes. The `extractUserInfo()` function no longer returns provider information as it now relies on `providerMetadata` parameter.
+
+### `UserInfo` Type
+
+Standard user information structure across all providers:
+
+```typescript
+interface UserInfo {
+  email: string;                    // Required: User's email address
+  id?: string;                      // Optional: Provider-specific user ID
+  sub?: string;                     // Optional: Subject identifier (OIDC)
+  given_name?: string;              // Optional: First name
+  family_name?: string;             // Optional: Last name
+  name?: string;                    // Optional: Full name
+  picture?: string;                 // Optional: Profile picture URL
+  email_verified?: boolean;         // Optional: Email verification status
+  iss?: string;                     // Optional: Token issuer (OIDC)
 }
 ```
 
+### Complete Example with User Info Utilities
+
+```typescript
+import { Lixa, extractUserInfo, type UserInfo } 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"],
+    },
+    github: {
+      provider: new GithubProvider(),
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/github/callback",
+      scopes: ["user:email"],
+    }
+  },
+  
+  sessionHandler: {
+    generateSession: async (tokenData, providerMetadata) => {
+      // Extract user info - works for both Google (ID token) and GitHub (API fetch)
+      const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+      
+      console.log(`User ${userInfo.email} authenticated`);
+      
+      // Create or update user in database
+      const user = await db.users.upsert({
+        email: userInfo.email,
+        name: userInfo.name || `${userInfo.given_name} ${userInfo.family_name}`.trim(),
+        givenName: userInfo.given_name,
+        familyName: userInfo.family_name,
+        picture: userInfo.picture,
+        emailVerified: userInfo.email_verified,
+      });
+      
+      return {
+        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 });
+      },
+    },
+  }
+});
+```
+
+### Benefits of User Info Utilities
+
+✅ **Provider-agnostic** - Works with any OAuth provider  
+✅ **Automatic method selection** - Uses ID token or fetches from API based on what's available  
+✅ **Type-safe** - Full TypeScript support with UserInfo interface  
+✅ **Flexible** - Supports both OIDC (ID token) and OAuth-only (API fetch) providers  
+✅ **Error handling** - Clear error messages when token data is invalid  
+✅ **Uses provider metadata** - Leverages userInfoEndpoint from provider configuration  
+
 ## API Reference
 
 ### `Lixa` Class
 
 #### Constructor
+
 - `new Lixa(config: LixaConfig)` - Creates a new Lixa instance
 
 #### Static Methods
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers
-- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
+
+- `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
-- `generateRandomState(): string` - Generate a random state parameter for OAuth flow
-- `getAuthUrl(provider: string, state: string): string` - Get authorization URL for a provider
-- `handleCallback({ provider, code, state }): Promise<Session>` - Handle OAuth callback and create session
+
+- `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
 
+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>;
+  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;
+  sessionHandler?: SessionHandler;
+  stateHandler?: StateHandler;
+  debug?: boolean;
+}
+
+interface SessionHandler {
+  generateSession?<T extends Session>(
+    tokenData: OAuthTokenResponse,
+    providerMetadata: ProviderMetadata
+  ): Promise<T>;
+  sessionStorage?: SessionStorage;
 }
 
-interface LixaConfig {
-  providers: Record<string, ProviderConfig>;
-  sessionStrategy?: SessionStrategy;
+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 SessionStrategy {
-  createSession(userInfo: any): Promise<Session>;
+interface StateHandler {
+  generateState?(provider: string): Promise<{ state: string; data: StateData }>;
+  stateStorage?: StateStorage;
 }
 
-interface Session {
+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> {
   token: string;
-  raw: any;
+  raw: TRaw;  // Defaults to OAuthTokenResponse, can be extended
+}
+
+interface StateData {
+  provider: string;       // Provider name for routing
+  codeVerifier: string;   // PKCE code verifier (64 hex chars)
+  createdAt: number;      // Unix timestamp in milliseconds
+}
+
+interface ProviderMetadata {
+  name: string;
+  endpoints: {
+    authorization: string;
+    token: string;
+    userInfo: string;
+  };
 }
 
 interface IProvider {
@@ -213,8 +906,320 @@ interface IProvider {
 
 ## Built-in Providers
 
-- **Google** - OAuth 2.0 and OpenID Connect
-- **GitHub** - OAuth 2.0
+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` - 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";
+```
+
+- **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**:
+  - `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
+
+### SessionHandler Interface
+
+The `SessionHandler` interface allows you to customize session generation and storage:
+
+```typescript
+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> {
+  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
+}
+
+interface ProviderMetadata {
+  name: string;
+  endpoints: {
+    authorization: string;
+    token: string;
+    userInfo: string;
+  };
+}
+```
+
+**Use cases:**
+- Extract user info from OAuth tokens
+- Create or update users in your database
+- Store tokens securely in your database
+- Add custom claims or metadata
+- Implement custom session storage (Redis, database, etc.)
+
+**Example with database integration:**
+```typescript
+import { SessionHandler, OAuthTokenResponse, Session, extractUserInfo } from "@vunexa/lixa";
+
+interface CustomSessionData extends OAuthTokenResponse {
+  userId: string;
+}
+
+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: userInfo.email,
+      name: userInfo.name
+    });
+    
+    return {
+      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 });
+    },
+  },
+};
+```
+
+### StateHandler Interface
+
+The `StateHandler` interface manages OAuth state generation and storage for CSRF protection and PKCE:
+
+```typescript
+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 StateData {
+  provider: string;      // Provider name for routing
+  codeVerifier: string;  // PKCE code verifier (64 hex chars)
+  createdAt: number;     // Unix timestamp in milliseconds
+}
+```
+
+**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 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}`);
+    }
+  }
+};
+```
+
+### SessionStorage Interface
+
+The `SessionStorage` interface manages persistent user session storage:
+
+```typescript
+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:**
+```typescript
+import { SessionStorage, Session } from "@vunexa/lixa";
+
+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(session),
+      expiresAt
+    });
+  },
+  
+  getSession: async <T extends Session>(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
+
+## Security Considerations
+
+### PKCE (Proof Key for Code Exchange)
+
+Lixa automatically implements PKCE for all OAuth flows:
+- Generates a cryptographically secure code verifier
+- Creates SHA-256 code challenge
+- Stores code verifier with state
+- Sends code verifier during token exchange
+
+This protects against authorization code interception attacks.
+
+### State Parameter
+
+The state parameter prevents CSRF attacks:
+- Always generated using cryptographically secure random bytes
+- Must be validated on callback
+- Automatically stored and validated when using custom `stateDao`
+- Single-use (deleted after validation)
+
+### Best Practices
+
+1. **Always use HTTPS** in production for redirect URIs
+2. **Implement custom storage** (StateDao/SessionDao) for production
+3. **Set short TTLs** for state (5 minutes) and sessions (24 hours recommended)
+4. **Validate state parameter** on every callback
+5. **Store tokens securely** - never expose access/refresh tokens to client-side code
+6. **Use HttpOnly cookies** for session tokens
+7. **Enable debug mode** only in development
 
 ## Development