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

package/README.md

@@ -123,6 +123,158 @@ app.get("/auth/:provider/callback", async (req, res) => {
 
 ## Advanced Usage
 
+### Custom State Storage (StateDao)
+
+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";
+
+// Example: DynamoDB state storage
+const dynamoDbStateDao = {
+  saveState: async (state: string, data: any, 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) => {
+    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);
+  },
+  
+  deleteState: async (state: string) => {
+    await dynamoDB.delete({
+      TableName: "oauth-states",
+      Key: { state },
+    });
+  },
+};
+
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  stateDao: dynamoDbStateDao,
+});
+```
+
+**Important**: The state data includes a `codeVerifier` field required for PKCE. 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:
+
+```typescript
+const customSessionDao = {
+  saveSession: async (sessionId: string, session: any, expiresInSeconds: number) => {
+    // Store session in your database
+    await db.sessions.create({
+      id: sessionId,
+      data: session,
+      expiresAt: Date.now() + expiresInSeconds * 1000,
+    });
+  },
+  
+  getSession: async (sessionId: string) => {
+    const session = await db.sessions.findById(sessionId);
+    if (!session || session.expiresAt < Date.now()) {
+      return null;
+    }
+    return session.data;
+  },
+  
+  deleteSession: async (sessionId: string) => {
+    await db.sessions.delete(sessionId);
+  },
+};
+
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  sessionDao: customSessionDao,
+});
+```
+
+### Custom Session Strategy
+
+The session strategy controls how user sessions are created from OAuth tokens:
+
+```typescript
+const customSessionStrategy = {
+  createSession: async (tokenData) => {
+    // tokenData contains: access_token, refresh_token, id_token, etc.
+    
+    // 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);
+    }
+    
+    // Create or update user in your database
+    const user = await db.users.upsert({
+      email: userInfo.email,
+      name: userInfo.name,
+      // ... 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,
+      raw: {
+        ...tokenData,
+        userId: user.id,
+        userInfo,
+      },
+    };
+  },
+};
+
+const lixa = new Lixa({
+  providers: { /* ... */ },
+  sessionStrategy: customSessionStrategy,
+});
+```
+
+### 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
+
 ### Custom Provider Registration
 
 You can register custom OAuth providers by implementing the `IProvider` interface:
@@ -136,7 +288,7 @@ class CustomProvider implements IProvider {
   userInfoEndpoint = "https://custom-provider.com/api/user";
 }
 
-// Register the custom provider
+// Register the custom provider BEFORE creating Lixa instance
 Lixa.registerProvider({
   custom: new CustomProvider(),
 });
@@ -161,6 +313,76 @@ const lixa = new Lixa({
 if (Lixa.isProviderRegistered("google")) {
   console.log("Google provider is available");
 }
+
+// Get list of all registered providers
+const providers = Lixa.getRegisteredProviders();
+console.log("Available 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 `stateDao` that persists state across requests. The default in-memory cache doesn't work in serverless or multi-instance environments.
+
+### 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`:
+
+```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: ... });
+}
+```
+
+### 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 `sessionDao` that uses persistent storage (database, Redis, etc.).
+
+### 5. User Info is Undefined
+
+**Cause**: The `sessionStrategy.createSession()` receives raw token data, not user info.
+
+**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();
+  }
+}
 ```
 
 ## API Reference
@@ -173,14 +395,16 @@ if (Lixa.isProviderRegistered("google")) {
 
 #### Static Methods
 
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers
+- `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
 
 #### 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): 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
 
 ### Types
 
@@ -190,21 +414,36 @@ interface ProviderConfig {
   clientSecret: string;
   redirectUri: string;
   scopes: string[];
-  extraConfig?: Record<string, any>;
+  extraConfig?: Record<string, any>; // Provider-specific parameters
 }
 
 interface LixaConfig {
   providers: Record<string, ProviderConfig>;
   sessionStrategy?: SessionStrategy;
+  stateDao?: StateDao; // Custom state storage
+  sessionDao?: SessionDao; // Custom session storage
+  debug?: boolean; // Enable debug logging
 }
 
 interface SessionStrategy {
-  createSession(userInfo: any): Promise<Session>;
+  createSession(tokenData: any): Promise<Session>;
 }
 
 interface Session {
-  token: string;
-  raw: any;
+  token: string; // Your custom session identifier
+  raw: any; // Raw data you want to store with the session
+}
+
+interface StateDao {
+  saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
+  getState(state: string): Promise<any | null>;
+  deleteState(state: string): Promise<void>;
+}
+
+interface SessionDao {
+  saveSession(sessionId: string, session: Session, expiresInSeconds: number): Promise<void>;
+  getSession(sessionId: string): Promise<Session | null>;
+  deleteSession(sessionId: string): Promise<void>;
 }
 
 interface IProvider {
@@ -216,8 +455,51 @@ interface IProvider {
 
 ## Built-in Providers
 
-- **Google** - OAuth 2.0 and OpenID Connect
-- **GitHub** - OAuth 2.0
+### Google
+- **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`
+
+### 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`
+
+## 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vunexa/lixa",
-  "version": "0.0.1-alpha.19",
+  "version": "0.0.1-alpha.20",
   "description": "Lixa is a flexible, provider-agnostic OAuth and OpenID Connect (OIDC) client library that simplifies multi-provider authentication flows. It supports seamless integration with providers like Google and GitHub, offers extensible session management, and enables dynamic provider resolution based on callback URLs.",
   "keywords": [
     "oauth",