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

package/README.md

@@ -33,14 +33,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,11 +59,11 @@ 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: {},
     },
   },
 
@@ -72,22 +80,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 +108,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,11 +132,277 @@ 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 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
 
-You can register custom OAuth providers by implementing the `IProvider` interface:
+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
+
+### 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";
@@ -136,12 +413,12 @@ 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(),
 });
 
-// Use it in your configuration
+// Use it in your configuration (without provider field)
 const lixa = new Lixa({
   providers: {
     custom: {
@@ -154,12 +431,82 @@ const lixa = new Lixa({
 });
 ```
 
-### Check Provider Registration
+### 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 `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
-// Check if a provider is registered
-if (Lixa.isProviderRegistered("google")) {
-  console.log("Google provider is available");
+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();
+  }
 }
 ```
 
@@ -173,33 +520,42 @@ if (Lixa.isProviderRegistered("google")) {
 
 #### Static Methods
 
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers
-- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
+- `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
 
-- `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 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
 
 ```typescript
-interface ProviderConfig {
+// Provider configuration with inline provider support
+type ProviderConfig = {
   clientId: string;
   clientSecret: string;
   redirectUri: string;
   scopes: string[];
   extraConfig?: Record<string, any>;
-}
+} & (
+  | { provider?: never }        // Built-in provider (no provider field)
+  | { provider: IProvider }     // Custom provider (provider field required)
+);
 
-interface LixaConfig {
-  providers: Record<string, ProviderConfig>;
+interface LixaConfig<TProviders = Record<string, ProviderConfig>> {
+  providers: TProviders;
   sessionStrategy?: SessionStrategy;
+  stateDao?: StateDao;
+  sessionDao?: SessionDao;
+  debug?: boolean;
 }
 
 interface SessionStrategy {
-  createSession(userInfo: any): Promise<Session>;
+  createSession(tokenData: any): Promise<Session>;
 }
 
 interface Session {
@@ -207,6 +563,24 @@ interface Session {
   raw: any;
 }
 
+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: StateData, expiresInSeconds: number): Promise<void>;
+  getState(state: string): Promise<StateData | null>;
+  deleteState(state: string): Promise<void>;
+}
+
+interface SessionDao {
+  saveSession(sessionId: string, session: any, expiresInSeconds: number): Promise<void>;
+  getSession(sessionId: string): Promise<any | null>;
+  deleteSession(sessionId: string): Promise<void>;
+}
+
 interface IProvider {
   authorizationEndpoint: string;
   tokenEndpoint: string;
@@ -216,8 +590,322 @@ 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
+
+### SessionStrategy Interface
+
+The `SessionStrategy` interface allows you to customize how OAuth tokens are converted into application sessions:
+
+```typescript
+interface SessionStrategy {
+  createSession(tokenData: any): Promise<Session>;
+}
+
+interface Session {
+  token: string;  // Your session identifier
+  raw: any;       // Additional session data
+}
+```
+
+**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:**
+```typescript
+const dbSessionStrategy: SessionStrategy = {
+  createSession: async (tokenData) => {
+    // Decode ID token (for OIDC providers)
+    const payload = decodeJwt(tokenData.id_token);
+    
+    // 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
+    });
+    
+    return {
+      token: sessionId,
+      raw: { userId: user.id, ...tokenData }
+    };
+  }
+};
+```
+
+### 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:
+
+```typescript
+interface SessionDao {
+  saveSession(sessionId: string, data: any, expiresInSeconds: number): Promise<void>;
+  getSession(sessionId: string): Promise<any | null>;
+  deleteSession(sessionId: string): Promise<void>;
+}
+```
+
+**Example with database:**
+```typescript
+const dbSessionDao: SessionDao = {
+  saveSession: async (sessionId, data, expiresInSeconds) => {
+    const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+    await db.sessions.create({
+      id: sessionId,
+      data: JSON.stringify(data),
+      expiresAt
+    });
+  },
+  
+  getSession: async (sessionId) => {
+    const session = await db.sessions.findOne({
+      id: sessionId,
+      expiresAt: { $gt: new Date() }
+    });
+    return session ? JSON.parse(session.data) : null;
+  },
+  
+  deleteSession: async (sessionId) => {
+    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
+
+### 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