@vunexa/lixa 0.0.1-alpha.20 → 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,6 +132,118 @@ app.get("/auth/:provider/callback", async (req, res) => {
 });
 ```
 
+## Provider Configuration
+
+### Using Built-in Providers
+
+Built-in providers are available in the `@vunexa/lixa-providers` package:
+
+```typescript
+import { Lixa } from "@vunexa/lixa";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-providers";
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: new GoogleProvider(),
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/google/callback",
+      scopes: ["openid", "email", "profile"]
+    }
+  }
+});
+```
+
+### Using Custom Inline Providers
+
+You can create custom providers by implementing the `IProvider` interface:
+
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+
+// Define your custom provider
+const customProvider: IProvider = {
+  authorizationEndpoint: "https://provider.com/oauth/authorize",
+  tokenEndpoint: "https://provider.com/oauth/token",
+  userInfoEndpoint: "https://provider.com/api/user"
+};
+
+// Use it directly in configuration
+const lixa = new Lixa({
+  providers: {
+    custom: {
+      provider: customProvider,
+      clientId: "your-client-id",
+      clientSecret: "your-client-secret",
+      redirectUri: "https://yourapp.com/auth/custom/callback",
+      scopes: ["read:user"]
+    }
+  }
+});
+```
+
+### Mixing Built-in and Custom Providers
+
+You can use both built-in and custom providers in the same configuration:
+
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+import { GoogleProvider } from "@vunexa/lixa-providers";
+
+const customProvider: IProvider = {
+  authorizationEndpoint: "https://custom.com/oauth/authorize",
+  tokenEndpoint: "https://custom.com/oauth/token",
+  userInfoEndpoint: "https://custom.com/api/user"
+};
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: new GoogleProvider(),
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/google/callback",
+      scopes: ["openid", "email", "profile"]
+    },
+    custom: {
+      provider: customProvider,
+      clientId: process.env.CUSTOM_CLIENT_ID!,
+      clientSecret: process.env.CUSTOM_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/custom/callback",
+      scopes: ["read:user"]
+    }
+  }
+});
+```
+
+### Overriding Built-in Providers (Testing)
+
+You can override built-in providers with custom implementations for testing:
+
+```typescript
+import { Lixa, IProvider } from "@vunexa/lixa";
+
+// Mock provider for testing
+const mockGoogleProvider: IProvider = {
+  authorizationEndpoint: "http://localhost:3000/mock/authorize",
+  tokenEndpoint: "http://localhost:3000/mock/token",
+  userInfoEndpoint: "http://localhost:3000/mock/userinfo"
+};
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      provider: mockGoogleProvider, // Override with mock
+      clientId: "test-client-id",
+      clientSecret: "test-client-secret",
+      redirectUri: "http://localhost:3000/callback",
+      scopes: ["openid", "email"]
+    }
+  }
+});
+```
+
 ## Advanced Usage
 
 ### Custom State Storage (StateDao)
@@ -275,9 +398,11 @@ Debug mode logs:
 - Session creation
 - Error details from OAuth providers
 
-### Custom Provider Registration
+### Legacy Provider Registration (Deprecated)
+
+> **Note**: This pattern is deprecated. Use inline providers instead (see examples above).
 
-You can register custom OAuth providers by implementing the `IProvider` interface:
+For backward compatibility, you can still register providers globally:
 
 ```typescript
 import { Lixa, IProvider } from "@vunexa/lixa";
@@ -293,7 +418,7 @@ Lixa.registerProvider({
   custom: new CustomProvider(),
 });
 
-// Use it in your configuration
+// Use it in your configuration (without provider field)
 const lixa = new Lixa({
   providers: {
     custom: {
@@ -306,17 +431,17 @@ const lixa = new Lixa({
 });
 ```
 
-### Check Provider Registration
+### Check Provider Configuration
 
 ```typescript
-// Check if a provider is registered
-if (Lixa.isProviderRegistered("google")) {
-  console.log("Google provider is available");
+// Check if a provider is configured for this instance
+if (lixa.isProviderConfigured("google")) {
+  console.log("Google provider is configured");
 }
 
-// Get list of all registered providers
+// Get list of all registered providers (legacy)
 const providers = Lixa.getRegisteredProviders();
-console.log("Available providers:", providers);
+console.log("Registered providers:", providers);
 ```
 
 ## Common Pitfalls & Solutions
@@ -395,34 +520,38 @@ createSession: async (tokenData) => {
 
 #### Static Methods
 
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers before creating instances
-- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
-- `Lixa.getRegisteredProviders(): string[]` - Get list of all registered provider names
-- `Lixa.generateRandomState(): string` - Generate a cryptographically secure random state string
+- `Lixa.generateRandomState(): string` - Generate a cryptographically secure random state string for CSRF protection
+- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - **[Deprecated]** Register custom providers globally. Use inline providers instead.
+- `Lixa.getRegisteredProviders(): string[]` - **[Deprecated]** Get list of all registered provider names from legacy registry
 
 #### Instance Methods
 
-- `getAuthUrl(provider: string, state: string): string` - Generate authorization URL for a provider. Automatically stores state with PKCE code verifier.
-- `handleCallback({ provider, code, state }): Promise<string>` - Handle OAuth callback, validate state, exchange code for tokens, and create session. Returns session ID.
-- `fetchSessionInfo(sessionId: string): Promise<Session | null>` - Retrieve session information by session ID
+- `getAuthUrl(provider: string, state: string): string` - Generate authorization URL for a provider. Automatically generates PKCE code verifier and challenge, stores state with code verifier for later validation.
+- `handleCallback({ provider, code, state }): Promise<string>` - Handle OAuth callback, validate state parameter, retrieve PKCE code verifier, exchange authorization code for tokens, and create session using SessionStrategy. Returns session ID.
+- `fetchSessionInfo(sessionId: string): Promise<Session | null>` - Retrieve session information by session ID from SessionDao.
+- `isProviderConfigured(provider: string): boolean` - Check if a provider is configured for this Lixa instance. Useful for type guards and runtime validation.
 
 ### Types
 
 ```typescript
-interface ProviderConfig {
+// Provider configuration with inline provider support
+type ProviderConfig = {
   clientId: string;
   clientSecret: string;
   redirectUri: string;
   scopes: string[];
-  extraConfig?: Record<string, any>; // Provider-specific parameters
-}
-
-interface LixaConfig {
-  providers: Record<string, ProviderConfig>;
+  extraConfig?: Record<string, any>;
+} & (
+  | { provider?: never }        // Built-in provider (no provider field)
+  | { provider: IProvider }     // Custom provider (provider field required)
+);
+
+interface LixaConfig<TProviders = Record<string, ProviderConfig>> {
+  providers: TProviders;
   sessionStrategy?: SessionStrategy;
-  stateDao?: StateDao; // Custom state storage
-  sessionDao?: SessionDao; // Custom session storage
-  debug?: boolean; // Enable debug logging
+  stateDao?: StateDao;
+  sessionDao?: SessionDao;
+  debug?: boolean;
 }
 
 interface SessionStrategy {
@@ -430,19 +559,25 @@ interface SessionStrategy {
 }
 
 interface Session {
-  token: string; // Your custom session identifier
-  raw: any; // Raw data you want to store with the session
+  token: string;
+  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: any, expiresInSeconds: number): Promise<void>;
-  getState(state: string): Promise<any | null>;
+  saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+  getState(state: string): Promise<StateData | null>;
   deleteState(state: string): Promise<void>;
 }
 
 interface SessionDao {
-  saveSession(sessionId: string, session: Session, expiresInSeconds: number): Promise<void>;
-  getSession(sessionId: string): Promise<Session | null>;
+  saveSession(sessionId: string, session: any, expiresInSeconds: number): Promise<void>;
+  getSession(sessionId: string): Promise<any | null>;
   deleteSession(sessionId: string): Promise<void>;
 }
 
@@ -455,21 +590,292 @@ interface IProvider {
 
 ## Built-in Providers
 
-### Google
+Built-in providers are available in the `@vunexa/lixa-providers` package:
+
+```bash
+npm install @vunexa/lixa-providers
+```
+
+### Google (`GoogleProvider`)
+
+```typescript
+import { GoogleProvider } from "@vunexa/lixa-providers";
+```
+
 - **Type**: OAuth 2.0 + OpenID Connect (OIDC)
 - **Authorization Endpoint**: `https://accounts.google.com/o/oauth2/v2/auth`
 - **Token Endpoint**: `https://oauth2.googleapis.com/token`
 - **User Info Endpoint**: `https://www.googleapis.com/oauth2/v2/userinfo`
 - **Supports**: PKCE, ID tokens, refresh tokens
-- **Common Scopes**: `openid`, `email`, `profile`
+- **Common Scopes**: 
+  - `openid` - Required for OpenID Connect
+  - `email` - Access to user's email address
+  - `profile` - Access to user's basic profile information
+  - `https://www.googleapis.com/auth/drive.readonly` - Read-only access to Google Drive
+  - `https://www.googleapis.com/auth/calendar.readonly` - Read-only access to Google Calendar
+
+[Full list of Google OAuth scopes](https://developers.google.com/identity/protocols/oauth2/scopes)
+
+### GitHub (`GithubProvider`)
+
+```typescript
+import { GithubProvider } from "@vunexa/lixa-providers";
+```
 
-### GitHub
 - **Type**: OAuth 2.0
 - **Authorization Endpoint**: `https://github.com/login/oauth/authorize`
 - **Token Endpoint**: `https://github.com/login/oauth/access_token`
 - **User Info Endpoint**: `https://api.github.com/user`
 - **Supports**: PKCE
-- **Common Scopes**: `read:user`, `user:email`
+- **Common Scopes**:
+  - `user` - Read/write access to profile info
+  - `user:email` - Read access to user's email addresses
+  - `read:user` - Read-only access to profile info
+  - `repo` - Full control of private repositories
+  - `public_repo` - Access to public repositories
+  - `gist` - Create gists
+  - `read:org` - Read-only access to organization membership
+
+[Full list of GitHub OAuth scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)
+
+## Extensibility Interfaces
+
+### SessionStrategy Interface
+
+The `SessionStrategy` interface allows you to customize how OAuth tokens are converted into application sessions:
+
+```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