@vunexa/lixa 0.0.1-alpha.18 → 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/dist/export-types/index.d.ts

@@ -85,12 +85,15 @@ export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     private stateDao;
     private sesionDao;
     private sessionStrategy;
+    private debug;
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
      * @param config - The configuration object containing provider settings and optional session strategy
      */
     constructor(config: TConfig);
+    private log;
+    private logError;
     /**
      * Checks if a provider is both registered and configured for this instance.
      * This is a type guard that narrows the provider type for use with getAuthUrl.
@@ -219,6 +222,8 @@ export declare interface LixaConfig<TRegisteredProviders extends string = string
     stateDao?: StateDao;
     /** Optiona: custom session storage implementation */
     sessionDao?: SessionDao;
+    /** Enable debug logging */
+    debug?: boolean;
 }
 
 /**

package/dist/index.cjs

@@ -108,6 +108,7 @@ var Lixa = class _Lixa {
   stateDao;
   sesionDao;
   sessionStrategy;
+  debug;
   /**
    * Creates a new Lixa instance with the provided configuration.
    *
@@ -125,6 +126,17 @@ var Lixa = class _Lixa {
     this.stateDao = config.stateDao || _Lixa.LOCAL_STATE_CACHE;
     this.sesionDao = config.sessionDao || _Lixa.LOCAL_SESSION_CACHE;
     this.sessionStrategy = config.sessionStrategy || _Lixa.DEFAULT_SESSION_STRATEGY;
+    this.debug = config.debug || false;
+  }
+  log(...args) {
+    if (this.debug) {
+      console.log("[Lixa]", ...args);
+    }
+  }
+  logError(...args) {
+    if (this.debug) {
+      console.error("[Lixa]", ...args);
+    }
   }
   /**
    * Checks if a provider is both registered and configured for this instance.
@@ -331,6 +343,8 @@ var Lixa = class _Lixa {
       body.code_verifier = codeVerifier;
     }
     const params = new URLSearchParams(body);
+    this.log("Token Exchange - Request body:", params.toString());
+    this.log("Token Exchange - Token endpoint:", providerImpl.tokenEndpoint);
     const response = await fetch(providerImpl.tokenEndpoint, {
       method: "POST",
       headers: {
@@ -340,8 +354,10 @@ var Lixa = class _Lixa {
       body: params.toString()
     });
     if (!response.ok) {
+      const errorBody = await response.text();
+      this.logError("Token Exchange - Error response:", errorBody);
       throw new Error(
-        `Token exchange failed: ${response.status} ${response.statusText}`
+        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`
       );
     }
     return response.json();

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/lixa.ts","../src/dao/state-cache.ts","../src/dao/session-cache.ts","../src/models/session.ts"],"sourcesContent":["/**\n * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.\n * \n * @remarks\n * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.\n * \n * @packageDocumentation\n */\n\nexport { Lixa } from \"./lixa\";\nexport {\n  type ProviderConfig,\n  type LixaConfig,\n  type SafeLixaConfig,\n} from \"./types\";\nexport { type Session, type SessionStrategy, DefaultSessionStrategy } from \"./models/session\";\nexport { type IProvider } from \"./providers\";\n","import { randomBytes } from \"crypto\";\nimport { type LixaConfig, type ProviderConfig } from \"./types\";\nimport { IProvider } from \"./providers\";\nimport { LocalStateCache } from \"./dao/state-cache\";\nimport { SessionDao, StateDao } from \"./dao/types\";\nimport crypto from \"crypto\";\nimport { LocalSessionCache } from \"./dao/session-cache\";\nimport { type Session, type SessionStrategy, DefaultSessionStrategy } from \"./models/session\";\n\n/**\n * Global registry of registered provider names\n */\ntype RegisteredProviders = string;\n\n/**\n * Type representing the keys of configured providers\n */\ntype ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];\n\n/**\n * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.\n *\n * @remarks\n * Lixa simplifies multi-provider authentication flows and supports extensible session management.\n *\n * @example\n * ```typescript\n * import { Lixa } from '@vunexa/lixa';\n * import { GoogleProvider } from '@vunexa/lixa/providers';\n * \n * // Register providers before using them\n * Lixa.registerProvider({ google: new GoogleProvider() });\n * \n * const config = Lixa.createConfig({\n *   providers: {\n *     google: {\n *       clientId: 'your-client-id',\n *       clientSecret: 'your-client-secret',\n *       redirectUri: 'https://yourapp.com/auth/google/callback',\n *       scopes: ['openid', 'email', 'profile']\n *     }\n *   }\n * });\n * \n * const lixa = new Lixa(config);\n * ```\n *\n * @public\n */\nclass Lixa<TConfig extends LixaConfig<any> = LixaConfig> {\n  private static CONFIGURED_PROVIDERS: Map<string, IProvider> = new Map();\n  private static LOCAL_STATE_CACHE = new LocalStateCache();\n  private static LOCAL_SESSION_CACHE = new LocalSessionCache();\n  private static DEFAULT_SESSION_STRATEGY = new DefaultSessionStrategy();\n  private config: TConfig;\n  private stateDao: StateDao;\n  private sesionDao: SessionDao;\n  private sessionStrategy: SessionStrategy;\n\n  /**\n   * Creates a new Lixa instance with the provided configuration.\n   *\n   * @param config - The configuration object containing provider settings and optional session strategy\n   */\n  constructor(config: TConfig) {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    this.config = config;\n    this.stateDao = config.stateDao || Lixa.LOCAL_STATE_CACHE;\n    this.sesionDao = config.sessionDao || Lixa.LOCAL_SESSION_CACHE;\n    this.sessionStrategy = config.sessionStrategy || Lixa.DEFAULT_SESSION_STRATEGY;\n  }\n\n  /**\n   * Checks if a provider is both registered and configured for this instance.\n   * This is a type guard that narrows the provider type for use with getAuthUrl.\n   *\n   * @param provider - The provider name to check (case-insensitive)\n   * @returns True if the provider is registered and configured, false otherwise\n   *\n   * @example\n   * ```typescript\n   * if (lixa.isProviderConfigured(provider)) {\n   *   // TypeScript now knows provider is a valid ConfiguredProviderKey\n   *   const authUrl = lixa.getAuthUrl(provider, state);\n   * }\n   * ```\n   */\n  public isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig> {\n    const providerType = provider.toLowerCase();\n    return Lixa.CONFIGURED_PROVIDERS.has(providerType) &&\n      this.config.providers.hasOwnProperty(providerType);\n  }\n\n  /**\n   * Registers custom OAuth providers for use with Lixa.\n   *\n   * @param providerMap - A map of provider names to IProvider implementations\n   *\n   * @example\n   * ```typescript\n   * class CustomProvider implements IProvider {\n   *   authorizationEndpoint = 'https://custom.com/oauth/authorize';\n   *   tokenEndpoint = 'https://custom.com/oauth/token';\n   *   userInfoEndpoint = 'https://custom.com/api/user';\n   * }\n   *\n   * Lixa.registerProvider({ custom: new CustomProvider() });\n   * ```\n   */\n  public static registerProvider<T extends Record<string, IProvider>>(providerMap: T): void {\n    Object.entries(providerMap).forEach(([key, providerImpl]) => {\n      Lixa.CONFIGURED_PROVIDERS.set(key.toLowerCase(), providerImpl);\n    });\n  }\n\n  /**\n   * Gets the list of registered provider names.\n   * \n   * @returns Array of registered provider names\n   */\n  public static getRegisteredProviders(): string[] {\n    return Array.from(Lixa.CONFIGURED_PROVIDERS.keys());\n  }\n\n  /**\n   * Creates a type-safe configuration that only allows registered providers.\n   * \n   * @param config - Configuration object with providers that must be registered\n   * @returns The same configuration object, but with type safety for registered providers\n   */\n  public static createConfig<T extends Record<string, ProviderConfig>>(\n    config: LixaConfig<keyof T & string> & { providers: T }\n  ): LixaConfig<keyof T & string> {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    return config;\n  }\n\n  /**\n   * Generates a cryptographically secure random state parameter for OAuth flows.\n   *\n   * @returns A 32-character hexadecimal string\n   *\n   * @remarks\n   * The state parameter is used to prevent CSRF attacks in OAuth flows.\n   */\n  public static generateRandomState(): string {\n    return randomBytes(16).toString(\"hex\");\n  }\n\n  /**\n   * Generates a cryptographically secure code verifier for PKCE flows.\n   *\n   * @returns A 64-character hexadecimal string\n   *\n   * @remarks\n   * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.\n   */\n  private static generateCodeVerifier(): string {\n    return randomBytes(32).toString(\"hex\");\n  }\n\n  private static buildCodeChallenge(codeVerifier: string): string {\n    const hash = crypto\n      .createHash(\"sha256\")\n      .update(codeVerifier)\n      .digest(\"base64\");\n\n    // Convert to base64url\n    return hash.replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n  }\n\n  /**\n   * Generates the authorization URL for the specified provider.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param state - The state parameter for CSRF protection\n   * @returns The complete authorization URL to redirect users to\n   *\n   * @throws Error when the provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const state = Lixa.generateRandomState();\n   * const authUrl = lixa.getAuthUrl('google', state);\n   * res.redirect(authUrl);\n   * ```\n   */\n  public getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state: string): string {\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${providerType} not configured`);\n    }\n\n    const codeVerifier = Lixa.generateCodeVerifier();\n    const codeChallenge = Lixa.buildCodeChallenge(codeVerifier);\n\n    // Cache the state paramaeter with TTL of 5 minutes (300 seconds)\n    // We dont care about value. we are onl interested in key existence\n    this.stateDao.saveState(\n      state,\n      {\n        createdAt: Date.now(),\n        provider: providerType,\n        codeVerifier,\n      },\n      300 // 5 minutes in seconds\n    );\n\n    const params = new URLSearchParams({\n      client_id: providerConfig.clientId,\n      redirect_uri: providerConfig.redirectUri,\n      scope: providerConfig.scopes.join(\" \"),\n      state,\n      response_type: \"code\",\n      code_challenge: codeChallenge,\n      code_challenge_method: \"S256\",\n      ...providerConfig.extraConfig,\n    });\n\n    return `${providerImpl.authorizationEndpoint}?${params.toString()}`;\n  }\n\n  /**\n   * Handles the OAuth callback and creates a user session.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param code - The authorization code from the provider\n   * @param state - The state parameter for validation\n   * @returns A Promise that resolves to the session ID\n   *\n   * @throws Error when code or state is missing/invalid, or provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const sessionId = await lixa.handleCallback({\n   *   provider: 'google',\n   *   code: req.query.code,\n   *   state: req.query.state\n   * });\n   * ```\n   */\n  public async handleCallback({\n    provider,\n    code,\n    state,\n  }: {\n    provider: ConfiguredProviderKey<TConfig> | string;\n    code: string;\n    state?: string;\n  }): Promise<string> {\n    if (!code || code.trim() === \"\") {\n      throw new Error(\"Invalid or missing code in callback\");\n    }\n\n    if (!state || state.trim() === \"\") {\n      throw new Error(\"Invalid or missing state in callback\");\n    }\n\n    //Validate state here\n    const cachedState = await this.stateDao.getState(state);\n    if (!cachedState) {\n      throw new Error(\"Invalid or expired state\");\n    }\n    // State is valid, remove it from cache to prevent reuse\n    await this.stateDao.deleteState(state);\n\n    //Get code verifier from cached state\n    const codeVerifier = cachedState.codeVerifier;\n\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${String(provider)} not configured`);\n    }\n\n    // Exchange code for tokens and fetch user info here.\n    const tokens = await this.exchangeCodeForToken(\n      code,\n      providerConfig,\n      providerImpl,\n      codeVerifier\n    );\n\n\n    const session = await this.sessionStrategy.createSession(tokens);\n\n    // Generate unique session ID\n    const sessionId = randomBytes(32).toString(\"hex\");\n\n    // Store session with 24 hour TTL (86400 seconds)\n    await this.sesionDao.saveSession(sessionId, session, 86400);\n\n    return sessionId;\n  }\n\n  public fetchSessionInfo(sessionId: string): Promise<Session | null> {\n    return this.sesionDao.getSession(sessionId);\n  }\n\n  private async exchangeCodeForToken(\n    code: string,\n    providerConfig: ProviderConfig,\n    providerImpl: IProvider,\n    codeVerifier: string\n  ): Promise<any> {\n    // Build the request body\n    const body: Record<string, string> = {\n      client_id: providerConfig.clientId,\n      client_secret: providerConfig.clientSecret,\n      code,\n      redirect_uri: providerConfig.redirectUri,\n      grant_type: \"authorization_code\",\n    };\n\n    if (codeVerifier) {\n      body.code_verifier = codeVerifier;\n    }\n    const params = new URLSearchParams(body);\n\n    const response = await fetch(providerImpl.tokenEndpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n        Accept: \"application/json\",\n      },\n      body: params.toString(),\n    });\n\n    if (!response.ok) {\n      throw new Error(\n        `Token exchange failed: ${response.status} ${response.statusText}`\n      );\n    }\n\n    return response.json();\n  }\n\n  private findProviderByType(providerType: string): ProviderConfig | undefined {\n    return this.config.providers[providerType];\n  }\n}\n\nexport { Lixa };\n","import NodeCache from 'node-cache';\nimport { StateDao } from \"./types\";\n\nclass LocalStateCache implements StateDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveState(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getState(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteState(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalStateCache };\n","import NodeCache from 'node-cache';\nimport { SessionDao } from \"./types\";\n\nclass LocalSessionCache implements SessionDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveSession(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getSession(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteSession(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalSessionCache };\n","/**\n * Represents a user session after successful OAuth authentication.\n *\n * @public\n */\nexport interface Session {\n  /** The session token (typically the access token) */\n  token: string;\n  /** Raw token data from the OAuth provider */\n  raw: any;\n}\n\n/**\n * Strategy interface for custom session creation.\n *\n * @public\n */\nexport interface SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   *\n   * @param userInfo - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  createSession(userInfo: any): Promise<Session>;\n}\n\n/**\n * Default session strategy that works with any OAuth provider.\n * Extracts common token information and creates a standardized session.\n *\n * @public\n */\nexport class DefaultSessionStrategy implements SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   * Handles common OAuth token formats and extracts the access token.\n   *\n   * @param tokenData - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  async createSession(tokenData: any): Promise<Session> {\n    // Extract access token from various possible formats\n    const accessToken = tokenData.access_token || \n                       tokenData.accessToken || \n                       tokenData.token ||\n                       tokenData;\n\n    if (!accessToken || typeof accessToken !== 'string') {\n      throw new Error('No valid access token found in OAuth response');\n    }\n\n    return {\n      token: accessToken,\n      raw: tokenData,\n    };\n  }\n}"],"mappings":"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","names":["NodeCache","import_crypto","import_node_cache","NodeCache","crypto"]}
+{"version":3,"sources":["../src/index.ts","../src/lixa.ts","../src/dao/state-cache.ts","../src/dao/session-cache.ts","../src/models/session.ts"],"sourcesContent":["/**\n * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.\n * \n * @remarks\n * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.\n * \n * @packageDocumentation\n */\n\nexport { Lixa } from \"./lixa\";\nexport {\n  type ProviderConfig,\n  type LixaConfig,\n  type SafeLixaConfig,\n} from \"./types\";\nexport { type Session, type SessionStrategy, DefaultSessionStrategy } from \"./models/session\";\nexport { type IProvider } from \"./providers\";\n","import { randomBytes } from \"crypto\";\nimport { type LixaConfig, type ProviderConfig } from \"./types\";\nimport { IProvider } from \"./providers\";\nimport { LocalStateCache } from \"./dao/state-cache\";\nimport { SessionDao, StateDao } from \"./dao/types\";\nimport crypto from \"crypto\";\nimport { LocalSessionCache } from \"./dao/session-cache\";\nimport { type Session, type SessionStrategy, DefaultSessionStrategy } from \"./models/session\";\n\n/**\n * Global registry of registered provider names\n */\ntype RegisteredProviders = string;\n\n/**\n * Type representing the keys of configured providers\n */\ntype ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];\n\n/**\n * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.\n *\n * @remarks\n * Lixa simplifies multi-provider authentication flows and supports extensible session management.\n *\n * @example\n * ```typescript\n * import { Lixa } from '@vunexa/lixa';\n * import { GoogleProvider } from '@vunexa/lixa/providers';\n * \n * // Register providers before using them\n * Lixa.registerProvider({ google: new GoogleProvider() });\n * \n * const config = Lixa.createConfig({\n *   providers: {\n *     google: {\n *       clientId: 'your-client-id',\n *       clientSecret: 'your-client-secret',\n *       redirectUri: 'https://yourapp.com/auth/google/callback',\n *       scopes: ['openid', 'email', 'profile']\n *     }\n *   }\n * });\n * \n * const lixa = new Lixa(config);\n * ```\n *\n * @public\n */\nclass Lixa<TConfig extends LixaConfig<any> = LixaConfig> {\n  private static CONFIGURED_PROVIDERS: Map<string, IProvider> = new Map();\n  private static LOCAL_STATE_CACHE = new LocalStateCache();\n  private static LOCAL_SESSION_CACHE = new LocalSessionCache();\n  private static DEFAULT_SESSION_STRATEGY = new DefaultSessionStrategy();\n  private config: TConfig;\n  private stateDao: StateDao;\n  private sesionDao: SessionDao;\n  private sessionStrategy: SessionStrategy;\n  private debug: boolean;\n\n  /**\n   * Creates a new Lixa instance with the provided configuration.\n   *\n   * @param config - The configuration object containing provider settings and optional session strategy\n   */\n  constructor(config: TConfig) {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    this.config = config;\n    this.stateDao = config.stateDao || Lixa.LOCAL_STATE_CACHE;\n    this.sesionDao = config.sessionDao || Lixa.LOCAL_SESSION_CACHE;\n    this.sessionStrategy = config.sessionStrategy || Lixa.DEFAULT_SESSION_STRATEGY;\n    this.debug = config.debug || false;\n  }\n\n  private log(...args: any[]) {\n    if (this.debug) {\n      console.log('[Lixa]', ...args);\n    }\n  }\n\n  private logError(...args: any[]) {\n    if (this.debug) {\n      console.error('[Lixa]', ...args);\n    }\n  }\n\n  /**\n   * Checks if a provider is both registered and configured for this instance.\n   * This is a type guard that narrows the provider type for use with getAuthUrl.\n   *\n   * @param provider - The provider name to check (case-insensitive)\n   * @returns True if the provider is registered and configured, false otherwise\n   *\n   * @example\n   * ```typescript\n   * if (lixa.isProviderConfigured(provider)) {\n   *   // TypeScript now knows provider is a valid ConfiguredProviderKey\n   *   const authUrl = lixa.getAuthUrl(provider, state);\n   * }\n   * ```\n   */\n  public isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig> {\n    const providerType = provider.toLowerCase();\n    return Lixa.CONFIGURED_PROVIDERS.has(providerType) &&\n      this.config.providers.hasOwnProperty(providerType);\n  }\n\n  /**\n   * Registers custom OAuth providers for use with Lixa.\n   *\n   * @param providerMap - A map of provider names to IProvider implementations\n   *\n   * @example\n   * ```typescript\n   * class CustomProvider implements IProvider {\n   *   authorizationEndpoint = 'https://custom.com/oauth/authorize';\n   *   tokenEndpoint = 'https://custom.com/oauth/token';\n   *   userInfoEndpoint = 'https://custom.com/api/user';\n   * }\n   *\n   * Lixa.registerProvider({ custom: new CustomProvider() });\n   * ```\n   */\n  public static registerProvider<T extends Record<string, IProvider>>(providerMap: T): void {\n    Object.entries(providerMap).forEach(([key, providerImpl]) => {\n      Lixa.CONFIGURED_PROVIDERS.set(key.toLowerCase(), providerImpl);\n    });\n  }\n\n  /**\n   * Gets the list of registered provider names.\n   * \n   * @returns Array of registered provider names\n   */\n  public static getRegisteredProviders(): string[] {\n    return Array.from(Lixa.CONFIGURED_PROVIDERS.keys());\n  }\n\n  /**\n   * Creates a type-safe configuration that only allows registered providers.\n   * \n   * @param config - Configuration object with providers that must be registered\n   * @returns The same configuration object, but with type safety for registered providers\n   */\n  public static createConfig<T extends Record<string, ProviderConfig>>(\n    config: LixaConfig<keyof T & string> & { providers: T }\n  ): LixaConfig<keyof T & string> {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    return config;\n  }\n\n  /**\n   * Generates a cryptographically secure random state parameter for OAuth flows.\n   *\n   * @returns A 32-character hexadecimal string\n   *\n   * @remarks\n   * The state parameter is used to prevent CSRF attacks in OAuth flows.\n   */\n  public static generateRandomState(): string {\n    return randomBytes(16).toString(\"hex\");\n  }\n\n  /**\n   * Generates a cryptographically secure code verifier for PKCE flows.\n   *\n   * @returns A 64-character hexadecimal string\n   *\n   * @remarks\n   * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.\n   */\n  private static generateCodeVerifier(): string {\n    return randomBytes(32).toString(\"hex\");\n  }\n\n  private static buildCodeChallenge(codeVerifier: string): string {\n    const hash = crypto\n      .createHash(\"sha256\")\n      .update(codeVerifier)\n      .digest(\"base64\");\n\n    // Convert to base64url\n    return hash.replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n  }\n\n  /**\n   * Generates the authorization URL for the specified provider.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param state - The state parameter for CSRF protection\n   * @returns The complete authorization URL to redirect users to\n   *\n   * @throws Error when the provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const state = Lixa.generateRandomState();\n   * const authUrl = lixa.getAuthUrl('google', state);\n   * res.redirect(authUrl);\n   * ```\n   */\n  public getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state: string): string {\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${providerType} not configured`);\n    }\n\n    const codeVerifier = Lixa.generateCodeVerifier();\n    const codeChallenge = Lixa.buildCodeChallenge(codeVerifier);\n\n    // Cache the state paramaeter with TTL of 5 minutes (300 seconds)\n    // We dont care about value. we are onl interested in key existence\n    this.stateDao.saveState(\n      state,\n      {\n        createdAt: Date.now(),\n        provider: providerType,\n        codeVerifier,\n      },\n      300 // 5 minutes in seconds\n    );\n\n    const params = new URLSearchParams({\n      client_id: providerConfig.clientId,\n      redirect_uri: providerConfig.redirectUri,\n      scope: providerConfig.scopes.join(\" \"),\n      state,\n      response_type: \"code\",\n      code_challenge: codeChallenge,\n      code_challenge_method: \"S256\",\n      ...providerConfig.extraConfig,\n    });\n\n    return `${providerImpl.authorizationEndpoint}?${params.toString()}`;\n  }\n\n  /**\n   * Handles the OAuth callback and creates a user session.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param code - The authorization code from the provider\n   * @param state - The state parameter for validation\n   * @returns A Promise that resolves to the session ID\n   *\n   * @throws Error when code or state is missing/invalid, or provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const sessionId = await lixa.handleCallback({\n   *   provider: 'google',\n   *   code: req.query.code,\n   *   state: req.query.state\n   * });\n   * ```\n   */\n  public async handleCallback({\n    provider,\n    code,\n    state,\n  }: {\n    provider: ConfiguredProviderKey<TConfig> | string;\n    code: string;\n    state?: string;\n  }): Promise<string> {\n    if (!code || code.trim() === \"\") {\n      throw new Error(\"Invalid or missing code in callback\");\n    }\n\n    if (!state || state.trim() === \"\") {\n      throw new Error(\"Invalid or missing state in callback\");\n    }\n\n    //Validate state here\n    const cachedState = await this.stateDao.getState(state);\n    if (!cachedState) {\n      throw new Error(\"Invalid or expired state\");\n    }\n    // State is valid, remove it from cache to prevent reuse\n    await this.stateDao.deleteState(state);\n\n    //Get code verifier from cached state\n    const codeVerifier = cachedState.codeVerifier;\n\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${String(provider)} not configured`);\n    }\n\n    // Exchange code for tokens and fetch user info here.\n    const tokens = await this.exchangeCodeForToken(\n      code,\n      providerConfig,\n      providerImpl,\n      codeVerifier\n    );\n\n\n    const session = await this.sessionStrategy.createSession(tokens);\n\n    // Generate unique session ID\n    const sessionId = randomBytes(32).toString(\"hex\");\n\n    // Store session with 24 hour TTL (86400 seconds)\n    await this.sesionDao.saveSession(sessionId, session, 86400);\n\n    return sessionId;\n  }\n\n  public fetchSessionInfo(sessionId: string): Promise<Session | null> {\n    return this.sesionDao.getSession(sessionId);\n  }\n\n  private async exchangeCodeForToken(\n    code: string,\n    providerConfig: ProviderConfig,\n    providerImpl: IProvider,\n    codeVerifier: string\n  ): Promise<any> {\n    // Build the request body\n    const body: Record<string, string> = {\n      client_id: providerConfig.clientId,\n      client_secret: providerConfig.clientSecret,\n      code,\n      redirect_uri: providerConfig.redirectUri,\n      grant_type: \"authorization_code\",\n    };\n\n    if (codeVerifier) {\n      body.code_verifier = codeVerifier;\n    }\n    const params = new URLSearchParams(body);\n\n    this.log('Token Exchange - Request body:', params.toString());\n    this.log('Token Exchange - Token endpoint:', providerImpl.tokenEndpoint);\n    \n    const response = await fetch(providerImpl.tokenEndpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n        Accept: \"application/json\",\n      },\n      body: params.toString(),\n    });\n\n    if (!response.ok) {\n      const errorBody = await response.text();\n      this.logError('Token Exchange - Error response:', errorBody);\n      throw new Error(\n        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`\n      );\n    }\n\n    return response.json();\n  }\n\n  private findProviderByType(providerType: string): ProviderConfig | undefined {\n    return this.config.providers[providerType];\n  }\n}\n\nexport { Lixa };\n","import NodeCache from 'node-cache';\nimport { StateDao } from \"./types\";\n\nclass LocalStateCache implements StateDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveState(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getState(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteState(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalStateCache };\n","import NodeCache from 'node-cache';\nimport { SessionDao } from \"./types\";\n\nclass LocalSessionCache implements SessionDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveSession(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getSession(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteSession(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalSessionCache };\n","/**\n * Represents a user session after successful OAuth authentication.\n *\n * @public\n */\nexport interface Session {\n  /** The session token (typically the access token) */\n  token: string;\n  /** Raw token data from the OAuth provider */\n  raw: any;\n}\n\n/**\n * Strategy interface for custom session creation.\n *\n * @public\n */\nexport interface SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   *\n   * @param userInfo - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  createSession(userInfo: any): Promise<Session>;\n}\n\n/**\n * Default session strategy that works with any OAuth provider.\n * Extracts common token information and creates a standardized session.\n *\n * @public\n */\nexport class DefaultSessionStrategy implements SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   * Handles common OAuth token formats and extracts the access token.\n   *\n   * @param tokenData - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  async createSession(tokenData: any): Promise<Session> {\n    // Extract access token from various possible formats\n    const accessToken = tokenData.access_token || \n                       tokenData.accessToken || \n                       tokenData.token ||\n                       tokenData;\n\n    if (!accessToken || typeof accessToken !== 'string') {\n      throw new Error('No valid access token found in OAuth response');\n    }\n\n    return {\n      token: accessToken,\n      raw: tokenData,\n    };\n  }\n}"],"mappings":"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","names":["NodeCache","import_crypto","import_node_cache","NodeCache","crypto"]}

package/dist/index.d.cts

@@ -85,6 +85,8 @@ interface LixaConfig<TRegisteredProviders extends string = string> {
     stateDao?: StateDao;
     /** Optiona: custom session storage implementation */
     sessionDao?: SessionDao;
+    /** Enable debug logging */
+    debug?: boolean;
 }
 /**
  * Helper type to create a configuration with only registered providers.
@@ -139,12 +141,15 @@ declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     private stateDao;
     private sesionDao;
     private sessionStrategy;
+    private debug;
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
      * @param config - The configuration object containing provider settings and optional session strategy
      */
     constructor(config: TConfig);
+    private log;
+    private logError;
     /**
      * Checks if a provider is both registered and configured for this instance.
      * This is a type guard that narrows the provider type for use with getAuthUrl.

package/dist/index.js

@@ -71,6 +71,7 @@ var Lixa = class _Lixa {
   stateDao;
   sesionDao;
   sessionStrategy;
+  debug;
   /**
    * Creates a new Lixa instance with the provided configuration.
    *
@@ -88,6 +89,17 @@ var Lixa = class _Lixa {
     this.stateDao = config.stateDao || _Lixa.LOCAL_STATE_CACHE;
     this.sesionDao = config.sessionDao || _Lixa.LOCAL_SESSION_CACHE;
     this.sessionStrategy = config.sessionStrategy || _Lixa.DEFAULT_SESSION_STRATEGY;
+    this.debug = config.debug || false;
+  }
+  log(...args) {
+    if (this.debug) {
+      console.log("[Lixa]", ...args);
+    }
+  }
+  logError(...args) {
+    if (this.debug) {
+      console.error("[Lixa]", ...args);
+    }
   }
   /**
    * Checks if a provider is both registered and configured for this instance.
@@ -294,6 +306,8 @@ var Lixa = class _Lixa {
       body.code_verifier = codeVerifier;
     }
     const params = new URLSearchParams(body);
+    this.log("Token Exchange - Request body:", params.toString());
+    this.log("Token Exchange - Token endpoint:", providerImpl.tokenEndpoint);
     const response = await fetch(providerImpl.tokenEndpoint, {
       method: "POST",
       headers: {
@@ -303,8 +317,10 @@ var Lixa = class _Lixa {
       body: params.toString()
     });
     if (!response.ok) {
+      const errorBody = await response.text();
+      this.logError("Token Exchange - Error response:", errorBody);
       throw new Error(
-        `Token exchange failed: ${response.status} ${response.statusText}`
+        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`
       );
     }
     return response.json();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/lixa.ts","../src/dao/state-cache.ts","../src/dao/session-cache.ts","../src/models/session.ts"],"sourcesContent":["import { randomBytes } from \"crypto\";\nimport { type LixaConfig, type ProviderConfig } from \"./types\";\nimport { IProvider } from \"./providers\";\nimport { LocalStateCache } from \"./dao/state-cache\";\nimport { SessionDao, StateDao } from \"./dao/types\";\nimport crypto from \"crypto\";\nimport { LocalSessionCache } from \"./dao/session-cache\";\nimport { type Session, type SessionStrategy, DefaultSessionStrategy } from \"./models/session\";\n\n/**\n * Global registry of registered provider names\n */\ntype RegisteredProviders = string;\n\n/**\n * Type representing the keys of configured providers\n */\ntype ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];\n\n/**\n * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.\n *\n * @remarks\n * Lixa simplifies multi-provider authentication flows and supports extensible session management.\n *\n * @example\n * ```typescript\n * import { Lixa } from '@vunexa/lixa';\n * import { GoogleProvider } from '@vunexa/lixa/providers';\n * \n * // Register providers before using them\n * Lixa.registerProvider({ google: new GoogleProvider() });\n * \n * const config = Lixa.createConfig({\n *   providers: {\n *     google: {\n *       clientId: 'your-client-id',\n *       clientSecret: 'your-client-secret',\n *       redirectUri: 'https://yourapp.com/auth/google/callback',\n *       scopes: ['openid', 'email', 'profile']\n *     }\n *   }\n * });\n * \n * const lixa = new Lixa(config);\n * ```\n *\n * @public\n */\nclass Lixa<TConfig extends LixaConfig<any> = LixaConfig> {\n  private static CONFIGURED_PROVIDERS: Map<string, IProvider> = new Map();\n  private static LOCAL_STATE_CACHE = new LocalStateCache();\n  private static LOCAL_SESSION_CACHE = new LocalSessionCache();\n  private static DEFAULT_SESSION_STRATEGY = new DefaultSessionStrategy();\n  private config: TConfig;\n  private stateDao: StateDao;\n  private sesionDao: SessionDao;\n  private sessionStrategy: SessionStrategy;\n\n  /**\n   * Creates a new Lixa instance with the provided configuration.\n   *\n   * @param config - The configuration object containing provider settings and optional session strategy\n   */\n  constructor(config: TConfig) {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    this.config = config;\n    this.stateDao = config.stateDao || Lixa.LOCAL_STATE_CACHE;\n    this.sesionDao = config.sessionDao || Lixa.LOCAL_SESSION_CACHE;\n    this.sessionStrategy = config.sessionStrategy || Lixa.DEFAULT_SESSION_STRATEGY;\n  }\n\n  /**\n   * Checks if a provider is both registered and configured for this instance.\n   * This is a type guard that narrows the provider type for use with getAuthUrl.\n   *\n   * @param provider - The provider name to check (case-insensitive)\n   * @returns True if the provider is registered and configured, false otherwise\n   *\n   * @example\n   * ```typescript\n   * if (lixa.isProviderConfigured(provider)) {\n   *   // TypeScript now knows provider is a valid ConfiguredProviderKey\n   *   const authUrl = lixa.getAuthUrl(provider, state);\n   * }\n   * ```\n   */\n  public isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig> {\n    const providerType = provider.toLowerCase();\n    return Lixa.CONFIGURED_PROVIDERS.has(providerType) &&\n      this.config.providers.hasOwnProperty(providerType);\n  }\n\n  /**\n   * Registers custom OAuth providers for use with Lixa.\n   *\n   * @param providerMap - A map of provider names to IProvider implementations\n   *\n   * @example\n   * ```typescript\n   * class CustomProvider implements IProvider {\n   *   authorizationEndpoint = 'https://custom.com/oauth/authorize';\n   *   tokenEndpoint = 'https://custom.com/oauth/token';\n   *   userInfoEndpoint = 'https://custom.com/api/user';\n   * }\n   *\n   * Lixa.registerProvider({ custom: new CustomProvider() });\n   * ```\n   */\n  public static registerProvider<T extends Record<string, IProvider>>(providerMap: T): void {\n    Object.entries(providerMap).forEach(([key, providerImpl]) => {\n      Lixa.CONFIGURED_PROVIDERS.set(key.toLowerCase(), providerImpl);\n    });\n  }\n\n  /**\n   * Gets the list of registered provider names.\n   * \n   * @returns Array of registered provider names\n   */\n  public static getRegisteredProviders(): string[] {\n    return Array.from(Lixa.CONFIGURED_PROVIDERS.keys());\n  }\n\n  /**\n   * Creates a type-safe configuration that only allows registered providers.\n   * \n   * @param config - Configuration object with providers that must be registered\n   * @returns The same configuration object, but with type safety for registered providers\n   */\n  public static createConfig<T extends Record<string, ProviderConfig>>(\n    config: LixaConfig<keyof T & string> & { providers: T }\n  ): LixaConfig<keyof T & string> {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    return config;\n  }\n\n  /**\n   * Generates a cryptographically secure random state parameter for OAuth flows.\n   *\n   * @returns A 32-character hexadecimal string\n   *\n   * @remarks\n   * The state parameter is used to prevent CSRF attacks in OAuth flows.\n   */\n  public static generateRandomState(): string {\n    return randomBytes(16).toString(\"hex\");\n  }\n\n  /**\n   * Generates a cryptographically secure code verifier for PKCE flows.\n   *\n   * @returns A 64-character hexadecimal string\n   *\n   * @remarks\n   * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.\n   */\n  private static generateCodeVerifier(): string {\n    return randomBytes(32).toString(\"hex\");\n  }\n\n  private static buildCodeChallenge(codeVerifier: string): string {\n    const hash = crypto\n      .createHash(\"sha256\")\n      .update(codeVerifier)\n      .digest(\"base64\");\n\n    // Convert to base64url\n    return hash.replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n  }\n\n  /**\n   * Generates the authorization URL for the specified provider.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param state - The state parameter for CSRF protection\n   * @returns The complete authorization URL to redirect users to\n   *\n   * @throws Error when the provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const state = Lixa.generateRandomState();\n   * const authUrl = lixa.getAuthUrl('google', state);\n   * res.redirect(authUrl);\n   * ```\n   */\n  public getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state: string): string {\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${providerType} not configured`);\n    }\n\n    const codeVerifier = Lixa.generateCodeVerifier();\n    const codeChallenge = Lixa.buildCodeChallenge(codeVerifier);\n\n    // Cache the state paramaeter with TTL of 5 minutes (300 seconds)\n    // We dont care about value. we are onl interested in key existence\n    this.stateDao.saveState(\n      state,\n      {\n        createdAt: Date.now(),\n        provider: providerType,\n        codeVerifier,\n      },\n      300 // 5 minutes in seconds\n    );\n\n    const params = new URLSearchParams({\n      client_id: providerConfig.clientId,\n      redirect_uri: providerConfig.redirectUri,\n      scope: providerConfig.scopes.join(\" \"),\n      state,\n      response_type: \"code\",\n      code_challenge: codeChallenge,\n      code_challenge_method: \"S256\",\n      ...providerConfig.extraConfig,\n    });\n\n    return `${providerImpl.authorizationEndpoint}?${params.toString()}`;\n  }\n\n  /**\n   * Handles the OAuth callback and creates a user session.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param code - The authorization code from the provider\n   * @param state - The state parameter for validation\n   * @returns A Promise that resolves to the session ID\n   *\n   * @throws Error when code or state is missing/invalid, or provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const sessionId = await lixa.handleCallback({\n   *   provider: 'google',\n   *   code: req.query.code,\n   *   state: req.query.state\n   * });\n   * ```\n   */\n  public async handleCallback({\n    provider,\n    code,\n    state,\n  }: {\n    provider: ConfiguredProviderKey<TConfig> | string;\n    code: string;\n    state?: string;\n  }): Promise<string> {\n    if (!code || code.trim() === \"\") {\n      throw new Error(\"Invalid or missing code in callback\");\n    }\n\n    if (!state || state.trim() === \"\") {\n      throw new Error(\"Invalid or missing state in callback\");\n    }\n\n    //Validate state here\n    const cachedState = await this.stateDao.getState(state);\n    if (!cachedState) {\n      throw new Error(\"Invalid or expired state\");\n    }\n    // State is valid, remove it from cache to prevent reuse\n    await this.stateDao.deleteState(state);\n\n    //Get code verifier from cached state\n    const codeVerifier = cachedState.codeVerifier;\n\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${String(provider)} not configured`);\n    }\n\n    // Exchange code for tokens and fetch user info here.\n    const tokens = await this.exchangeCodeForToken(\n      code,\n      providerConfig,\n      providerImpl,\n      codeVerifier\n    );\n\n\n    const session = await this.sessionStrategy.createSession(tokens);\n\n    // Generate unique session ID\n    const sessionId = randomBytes(32).toString(\"hex\");\n\n    // Store session with 24 hour TTL (86400 seconds)\n    await this.sesionDao.saveSession(sessionId, session, 86400);\n\n    return sessionId;\n  }\n\n  public fetchSessionInfo(sessionId: string): Promise<Session | null> {\n    return this.sesionDao.getSession(sessionId);\n  }\n\n  private async exchangeCodeForToken(\n    code: string,\n    providerConfig: ProviderConfig,\n    providerImpl: IProvider,\n    codeVerifier: string\n  ): Promise<any> {\n    // Build the request body\n    const body: Record<string, string> = {\n      client_id: providerConfig.clientId,\n      client_secret: providerConfig.clientSecret,\n      code,\n      redirect_uri: providerConfig.redirectUri,\n      grant_type: \"authorization_code\",\n    };\n\n    if (codeVerifier) {\n      body.code_verifier = codeVerifier;\n    }\n    const params = new URLSearchParams(body);\n\n    const response = await fetch(providerImpl.tokenEndpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n        Accept: \"application/json\",\n      },\n      body: params.toString(),\n    });\n\n    if (!response.ok) {\n      throw new Error(\n        `Token exchange failed: ${response.status} ${response.statusText}`\n      );\n    }\n\n    return response.json();\n  }\n\n  private findProviderByType(providerType: string): ProviderConfig | undefined {\n    return this.config.providers[providerType];\n  }\n}\n\nexport { Lixa };\n","import NodeCache from 'node-cache';\nimport { StateDao } from \"./types\";\n\nclass LocalStateCache implements StateDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveState(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getState(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteState(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalStateCache };\n","import NodeCache from 'node-cache';\nimport { SessionDao } from \"./types\";\n\nclass LocalSessionCache implements SessionDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveSession(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getSession(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteSession(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalSessionCache };\n","/**\n * Represents a user session after successful OAuth authentication.\n *\n * @public\n */\nexport interface Session {\n  /** The session token (typically the access token) */\n  token: string;\n  /** Raw token data from the OAuth provider */\n  raw: any;\n}\n\n/**\n * Strategy interface for custom session creation.\n *\n * @public\n */\nexport interface SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   *\n   * @param userInfo - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  createSession(userInfo: any): Promise<Session>;\n}\n\n/**\n * Default session strategy that works with any OAuth provider.\n * Extracts common token information and creates a standardized session.\n *\n * @public\n */\nexport class DefaultSessionStrategy implements SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   * Handles common OAuth token formats and extracts the access token.\n   *\n   * @param tokenData - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  async createSession(tokenData: any): Promise<Session> {\n    // Extract access token from various possible formats\n    const accessToken = tokenData.access_token || \n                       tokenData.accessToken || \n                       tokenData.token ||\n                       tokenData;\n\n    if (!accessToken || typeof accessToken !== 'string') {\n      throw new Error('No valid access token found in OAuth response');\n    }\n\n    return {\n      token: accessToken,\n      raw: tokenData,\n    };\n  }\n}"],"mappings":"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","names":["NodeCache"]}
+{"version":3,"sources":["../src/lixa.ts","../src/dao/state-cache.ts","../src/dao/session-cache.ts","../src/models/session.ts"],"sourcesContent":["import { randomBytes } from \"crypto\";\nimport { type LixaConfig, type ProviderConfig } from \"./types\";\nimport { IProvider } from \"./providers\";\nimport { LocalStateCache } from \"./dao/state-cache\";\nimport { SessionDao, StateDao } from \"./dao/types\";\nimport crypto from \"crypto\";\nimport { LocalSessionCache } from \"./dao/session-cache\";\nimport { type Session, type SessionStrategy, DefaultSessionStrategy } from \"./models/session\";\n\n/**\n * Global registry of registered provider names\n */\ntype RegisteredProviders = string;\n\n/**\n * Type representing the keys of configured providers\n */\ntype ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];\n\n/**\n * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.\n *\n * @remarks\n * Lixa simplifies multi-provider authentication flows and supports extensible session management.\n *\n * @example\n * ```typescript\n * import { Lixa } from '@vunexa/lixa';\n * import { GoogleProvider } from '@vunexa/lixa/providers';\n * \n * // Register providers before using them\n * Lixa.registerProvider({ google: new GoogleProvider() });\n * \n * const config = Lixa.createConfig({\n *   providers: {\n *     google: {\n *       clientId: 'your-client-id',\n *       clientSecret: 'your-client-secret',\n *       redirectUri: 'https://yourapp.com/auth/google/callback',\n *       scopes: ['openid', 'email', 'profile']\n *     }\n *   }\n * });\n * \n * const lixa = new Lixa(config);\n * ```\n *\n * @public\n */\nclass Lixa<TConfig extends LixaConfig<any> = LixaConfig> {\n  private static CONFIGURED_PROVIDERS: Map<string, IProvider> = new Map();\n  private static LOCAL_STATE_CACHE = new LocalStateCache();\n  private static LOCAL_SESSION_CACHE = new LocalSessionCache();\n  private static DEFAULT_SESSION_STRATEGY = new DefaultSessionStrategy();\n  private config: TConfig;\n  private stateDao: StateDao;\n  private sesionDao: SessionDao;\n  private sessionStrategy: SessionStrategy;\n  private debug: boolean;\n\n  /**\n   * Creates a new Lixa instance with the provided configuration.\n   *\n   * @param config - The configuration object containing provider settings and optional session strategy\n   */\n  constructor(config: TConfig) {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    this.config = config;\n    this.stateDao = config.stateDao || Lixa.LOCAL_STATE_CACHE;\n    this.sesionDao = config.sessionDao || Lixa.LOCAL_SESSION_CACHE;\n    this.sessionStrategy = config.sessionStrategy || Lixa.DEFAULT_SESSION_STRATEGY;\n    this.debug = config.debug || false;\n  }\n\n  private log(...args: any[]) {\n    if (this.debug) {\n      console.log('[Lixa]', ...args);\n    }\n  }\n\n  private logError(...args: any[]) {\n    if (this.debug) {\n      console.error('[Lixa]', ...args);\n    }\n  }\n\n  /**\n   * Checks if a provider is both registered and configured for this instance.\n   * This is a type guard that narrows the provider type for use with getAuthUrl.\n   *\n   * @param provider - The provider name to check (case-insensitive)\n   * @returns True if the provider is registered and configured, false otherwise\n   *\n   * @example\n   * ```typescript\n   * if (lixa.isProviderConfigured(provider)) {\n   *   // TypeScript now knows provider is a valid ConfiguredProviderKey\n   *   const authUrl = lixa.getAuthUrl(provider, state);\n   * }\n   * ```\n   */\n  public isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig> {\n    const providerType = provider.toLowerCase();\n    return Lixa.CONFIGURED_PROVIDERS.has(providerType) &&\n      this.config.providers.hasOwnProperty(providerType);\n  }\n\n  /**\n   * Registers custom OAuth providers for use with Lixa.\n   *\n   * @param providerMap - A map of provider names to IProvider implementations\n   *\n   * @example\n   * ```typescript\n   * class CustomProvider implements IProvider {\n   *   authorizationEndpoint = 'https://custom.com/oauth/authorize';\n   *   tokenEndpoint = 'https://custom.com/oauth/token';\n   *   userInfoEndpoint = 'https://custom.com/api/user';\n   * }\n   *\n   * Lixa.registerProvider({ custom: new CustomProvider() });\n   * ```\n   */\n  public static registerProvider<T extends Record<string, IProvider>>(providerMap: T): void {\n    Object.entries(providerMap).forEach(([key, providerImpl]) => {\n      Lixa.CONFIGURED_PROVIDERS.set(key.toLowerCase(), providerImpl);\n    });\n  }\n\n  /**\n   * Gets the list of registered provider names.\n   * \n   * @returns Array of registered provider names\n   */\n  public static getRegisteredProviders(): string[] {\n    return Array.from(Lixa.CONFIGURED_PROVIDERS.keys());\n  }\n\n  /**\n   * Creates a type-safe configuration that only allows registered providers.\n   * \n   * @param config - Configuration object with providers that must be registered\n   * @returns The same configuration object, but with type safety for registered providers\n   */\n  public static createConfig<T extends Record<string, ProviderConfig>>(\n    config: LixaConfig<keyof T & string> & { providers: T }\n  ): LixaConfig<keyof T & string> {\n    // Validate that all providers in config are registered\n    const configuredProviders = Object.keys(config.providers);\n    const registeredProviders = Lixa.getRegisteredProviders();\n    \n    for (const provider of configuredProviders) {\n      if (!registeredProviders.includes(provider.toLowerCase())) {\n        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);\n      }\n    }\n    \n    return config;\n  }\n\n  /**\n   * Generates a cryptographically secure random state parameter for OAuth flows.\n   *\n   * @returns A 32-character hexadecimal string\n   *\n   * @remarks\n   * The state parameter is used to prevent CSRF attacks in OAuth flows.\n   */\n  public static generateRandomState(): string {\n    return randomBytes(16).toString(\"hex\");\n  }\n\n  /**\n   * Generates a cryptographically secure code verifier for PKCE flows.\n   *\n   * @returns A 64-character hexadecimal string\n   *\n   * @remarks\n   * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.\n   */\n  private static generateCodeVerifier(): string {\n    return randomBytes(32).toString(\"hex\");\n  }\n\n  private static buildCodeChallenge(codeVerifier: string): string {\n    const hash = crypto\n      .createHash(\"sha256\")\n      .update(codeVerifier)\n      .digest(\"base64\");\n\n    // Convert to base64url\n    return hash.replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n  }\n\n  /**\n   * Generates the authorization URL for the specified provider.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param state - The state parameter for CSRF protection\n   * @returns The complete authorization URL to redirect users to\n   *\n   * @throws Error when the provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const state = Lixa.generateRandomState();\n   * const authUrl = lixa.getAuthUrl('google', state);\n   * res.redirect(authUrl);\n   * ```\n   */\n  public getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state: string): string {\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${providerType} not configured`);\n    }\n\n    const codeVerifier = Lixa.generateCodeVerifier();\n    const codeChallenge = Lixa.buildCodeChallenge(codeVerifier);\n\n    // Cache the state paramaeter with TTL of 5 minutes (300 seconds)\n    // We dont care about value. we are onl interested in key existence\n    this.stateDao.saveState(\n      state,\n      {\n        createdAt: Date.now(),\n        provider: providerType,\n        codeVerifier,\n      },\n      300 // 5 minutes in seconds\n    );\n\n    const params = new URLSearchParams({\n      client_id: providerConfig.clientId,\n      redirect_uri: providerConfig.redirectUri,\n      scope: providerConfig.scopes.join(\" \"),\n      state,\n      response_type: \"code\",\n      code_challenge: codeChallenge,\n      code_challenge_method: \"S256\",\n      ...providerConfig.extraConfig,\n    });\n\n    return `${providerImpl.authorizationEndpoint}?${params.toString()}`;\n  }\n\n  /**\n   * Handles the OAuth callback and creates a user session.\n   *\n   * @param provider - The provider name (must be a configured provider key)\n   * @param code - The authorization code from the provider\n   * @param state - The state parameter for validation\n   * @returns A Promise that resolves to the session ID\n   *\n   * @throws Error when code or state is missing/invalid, or provider is not configured\n   *\n   * @example\n   * ```typescript\n   * const sessionId = await lixa.handleCallback({\n   *   provider: 'google',\n   *   code: req.query.code,\n   *   state: req.query.state\n   * });\n   * ```\n   */\n  public async handleCallback({\n    provider,\n    code,\n    state,\n  }: {\n    provider: ConfiguredProviderKey<TConfig> | string;\n    code: string;\n    state?: string;\n  }): Promise<string> {\n    if (!code || code.trim() === \"\") {\n      throw new Error(\"Invalid or missing code in callback\");\n    }\n\n    if (!state || state.trim() === \"\") {\n      throw new Error(\"Invalid or missing state in callback\");\n    }\n\n    //Validate state here\n    const cachedState = await this.stateDao.getState(state);\n    if (!cachedState) {\n      throw new Error(\"Invalid or expired state\");\n    }\n    // State is valid, remove it from cache to prevent reuse\n    await this.stateDao.deleteState(state);\n\n    //Get code verifier from cached state\n    const codeVerifier = cachedState.codeVerifier;\n\n    const providerType = String(provider).toLowerCase();\n    const providerConfig = this.findProviderByType(providerType);\n    const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);\n\n    if (!providerConfig || !providerImpl) {\n      throw new Error(`Provider ${String(provider)} not configured`);\n    }\n\n    // Exchange code for tokens and fetch user info here.\n    const tokens = await this.exchangeCodeForToken(\n      code,\n      providerConfig,\n      providerImpl,\n      codeVerifier\n    );\n\n\n    const session = await this.sessionStrategy.createSession(tokens);\n\n    // Generate unique session ID\n    const sessionId = randomBytes(32).toString(\"hex\");\n\n    // Store session with 24 hour TTL (86400 seconds)\n    await this.sesionDao.saveSession(sessionId, session, 86400);\n\n    return sessionId;\n  }\n\n  public fetchSessionInfo(sessionId: string): Promise<Session | null> {\n    return this.sesionDao.getSession(sessionId);\n  }\n\n  private async exchangeCodeForToken(\n    code: string,\n    providerConfig: ProviderConfig,\n    providerImpl: IProvider,\n    codeVerifier: string\n  ): Promise<any> {\n    // Build the request body\n    const body: Record<string, string> = {\n      client_id: providerConfig.clientId,\n      client_secret: providerConfig.clientSecret,\n      code,\n      redirect_uri: providerConfig.redirectUri,\n      grant_type: \"authorization_code\",\n    };\n\n    if (codeVerifier) {\n      body.code_verifier = codeVerifier;\n    }\n    const params = new URLSearchParams(body);\n\n    this.log('Token Exchange - Request body:', params.toString());\n    this.log('Token Exchange - Token endpoint:', providerImpl.tokenEndpoint);\n    \n    const response = await fetch(providerImpl.tokenEndpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n        Accept: \"application/json\",\n      },\n      body: params.toString(),\n    });\n\n    if (!response.ok) {\n      const errorBody = await response.text();\n      this.logError('Token Exchange - Error response:', errorBody);\n      throw new Error(\n        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`\n      );\n    }\n\n    return response.json();\n  }\n\n  private findProviderByType(providerType: string): ProviderConfig | undefined {\n    return this.config.providers[providerType];\n  }\n}\n\nexport { Lixa };\n","import NodeCache from 'node-cache';\nimport { StateDao } from \"./types\";\n\nclass LocalStateCache implements StateDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveState(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getState(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteState(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalStateCache };\n","import NodeCache from 'node-cache';\nimport { SessionDao } from \"./types\";\n\nclass LocalSessionCache implements SessionDao {\n  private cache: NodeCache;\n\n  constructor(defaultTtlSeconds: number = 600) {\n    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });\n  }\n\n  async saveSession(state: string, data: any, expiresInSeconds: number): Promise<void> {\n    this.cache.set(state, data, expiresInSeconds);\n  }\n\n  async getSession(state: string): Promise<any | null> {\n    return this.cache.get(state) || null;\n  }\n\n  async deleteSession(state: string): Promise<void> {\n    this.cache.del(state);\n  }\n}\n\nexport { LocalSessionCache };\n","/**\n * Represents a user session after successful OAuth authentication.\n *\n * @public\n */\nexport interface Session {\n  /** The session token (typically the access token) */\n  token: string;\n  /** Raw token data from the OAuth provider */\n  raw: any;\n}\n\n/**\n * Strategy interface for custom session creation.\n *\n * @public\n */\nexport interface SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   *\n   * @param userInfo - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  createSession(userInfo: any): Promise<Session>;\n}\n\n/**\n * Default session strategy that works with any OAuth provider.\n * Extracts common token information and creates a standardized session.\n *\n * @public\n */\nexport class DefaultSessionStrategy implements SessionStrategy {\n  /**\n   * Creates a session from OAuth token data.\n   * Handles common OAuth token formats and extracts the access token.\n   *\n   * @param tokenData - The token data received from the OAuth provider\n   * @returns A Promise that resolves to a Session object\n   */\n  async createSession(tokenData: any): Promise<Session> {\n    // Extract access token from various possible formats\n    const accessToken = tokenData.access_token || \n                       tokenData.accessToken || \n                       tokenData.token ||\n                       tokenData;\n\n    if (!accessToken || typeof accessToken !== 'string') {\n      throw new Error('No valid access token found in OAuth response');\n    }\n\n    return {\n      token: accessToken,\n      raw: tokenData,\n    };\n  }\n}"],"mappings":"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","names":["NodeCache"]}

package/dist/lixa.d.ts

@@ -44,12 +44,15 @@ declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     private stateDao;
     private sesionDao;
     private sessionStrategy;
+    private debug;
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
      * @param config - The configuration object containing provider settings and optional session strategy
      */
     constructor(config: TConfig);
+    private log;
+    private logError;
     /**
      * Checks if a provider is both registered and configured for this instance.
      * This is a type guard that narrows the provider type for use with getAuthUrl.

package/dist/lixa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,OAAO,EAAE,KAAK,OAAO,EAAgD,MAAM,kBAAkB,CAAC;AAO9F;;GAEG;AACH,KAAK,qBAAqB,CAAC,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,cAAM,IAAI,CAAC,OAAO,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,UAAU;IACrD,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAyB;IACzD,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAA2B;IAC7D,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAgC;IACvE,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,eAAe,CAAkB;IAEzC;;;;OAIG;gBACS,MAAM,EAAE,OAAO;IAiB3B;;;;;;;;;;;;;;OAcG;IACI,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC;IAM1G;;;;;;;;;;;;;;;OAeG;WACW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI;IAMzF;;;;OAIG;WACW,sBAAsB,IAAI,MAAM,EAAE;IAIhD;;;;;OAKG;WACW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACjE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG;QAAE,SAAS,EAAE,CAAC,CAAA;KAAE,GACtD,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAc/B;;;;;;;OAOG;WACW,mBAAmB,IAAI,MAAM;IAI3C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAInC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;;;;;;;;;;;;;OAeG;IACI,UAAU,CAAC,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAsC3F;;;;;;;;;;;;;;;;;;OAkBG;IACU,cAAc,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,KAAK,GACN,EAAE;QACD,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgDZ,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAIrD,oBAAoB;IAsClC,OAAO,CAAC,kBAAkB;CAG3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,OAAO,EAAE,KAAK,OAAO,EAAgD,MAAM,kBAAkB,CAAC;AAO9F;;GAEG;AACH,KAAK,qBAAqB,CAAC,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,cAAM,IAAI,CAAC,OAAO,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,UAAU;IACrD,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAyB;IACzD,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAA2B;IAC7D,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAgC;IACvE,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,KAAK,CAAU;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,OAAO;IAkB3B,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,QAAQ;IAMhB;;;;;;;;;;;;;;OAcG;IACI,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC;IAM1G;;;;;;;;;;;;;;;OAeG;WACW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI;IAMzF;;;;OAIG;WACW,sBAAsB,IAAI,MAAM,EAAE;IAIhD;;;;;OAKG;WACW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACjE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG;QAAE,SAAS,EAAE,CAAC,CAAA;KAAE,GACtD,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAc/B;;;;;;;OAOG;WACW,mBAAmB,IAAI,MAAM;IAI3C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAInC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;;;;;;;;;;;;;OAeG;IACI,UAAU,CAAC,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAsC3F;;;;;;;;;;;;;;;;;;OAkBG;IACU,cAAc,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,KAAK,GACN,EAAE;QACD,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgDZ,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAIrD,oBAAoB;IA2ClC,OAAO,CAAC,kBAAkB;CAG3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/types.d.ts

@@ -33,6 +33,8 @@ export interface LixaConfig<TRegisteredProviders extends string = string> {
     stateDao?: StateDao;
     /** Optiona: custom session storage implementation */
     sessionDao?: SessionDao;
+    /** Enable debug logging */
+    debug?: boolean;
 }
 /**
  * Helper type to create a configuration with only registered providers.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,oBAAoB,SAAS,MAAM,GAAG,MAAM;IACtE,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC,oBAAoB,EAAE,cAAc,CAAC,CAAC;IACxD,gDAAgD;IAChD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,UAAU,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG;IACtH,SAAS,EAAE,UAAU,CAAC;CACvB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,oBAAoB,SAAS,MAAM,GAAG,MAAM;IACtE,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC,oBAAoB,EAAE,cAAc,CAAC,CAAC;IACxD,gDAAgD;IAChD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,UAAU,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG;IACtH,SAAS,EAAE,UAAU,CAAC;CACvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vunexa/lixa",
-  "version": "0.0.1-alpha.18",
+  "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",