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

package/dist/index.d.ts

@@ -4,10 +4,18 @@
  * @remarks
  * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
  *
+ * Key features:
+ * - OAuth 2.0 authorization code flow with PKCE (RFC 6749, RFC 7636)
+ * - OpenID Connect support
+ * - Built-in providers available in \@vunexa/lixa-providers
+ * - Custom provider support via IProvider interface
+ * - Extensible session management via SessionStrategy
+ * - Pluggable state and session storage via StateDao and SessionDao
+ * - TypeScript-first with comprehensive type safety
+ *
  * @packageDocumentation
  */
 export { Lixa } from "./lixa";
-export { type ProviderConfig, type LixaConfig, type SafeLixaConfig, } from "./types";
-export { type Session, type SessionStrategy, DefaultSessionStrategy } from "./models/session";
-export { type IProvider } from "./providers";
+export { type ProviderConfig, type LixaConfig, type SafeLixaConfig, type IProvider, type SessionStrategy, type Session, type StateDao, type SessionDao, type StateData, } from "./types";
+export { DefaultSessionStrategy } from "./models/session";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -50,12 +50,11 @@ var DefaultSessionStrategy = class {
    * @returns A Promise that resolves to a Session object
    */
   async createSession(tokenData) {
-    const accessToken = tokenData.access_token || tokenData.accessToken || tokenData.token || tokenData;
-    if (!accessToken || typeof accessToken !== "string") {
+    if (!tokenData.access_token || typeof tokenData.access_token !== "string") {
       throw new Error("No valid access token found in OAuth response");
     }
     return {
-      token: accessToken,
+      token: tokenData.access_token,
       raw: tokenData
     };
   }
@@ -63,7 +62,9 @@ var DefaultSessionStrategy = class {
 
 // src/lixa.ts
 var Lixa = class _Lixa {
+  static DEFAULT_PROVIDERS = /* @__PURE__ */ new Map();
   static CONFIGURED_PROVIDERS = /* @__PURE__ */ new Map();
+  // Legacy registry for backward compatibility
   static LOCAL_STATE_CACHE = new LocalStateCache();
   static LOCAL_SESSION_CACHE = new LocalSessionCache();
   static DEFAULT_SESSION_STRATEGY = new DefaultSessionStrategy();
@@ -74,39 +75,122 @@ var Lixa = class _Lixa {
   debug;
   /**
    * Creates a new Lixa instance with the provided configuration.
-   *
+   * 
+   * @remarks
+   * Providers can be passed inline in the configuration using the `provider` field.
+   * Provider resolution priority: inline custom provider \> default providers \> legacy registry.
+   * 
    * @param config - The configuration object containing provider settings and optional session strategy
+   * 
+   * @throws Error when provider configuration is missing required fields
+   * @throws Error when provider implementation is missing required properties
+   * @throws Error when provider is not available and no inline implementation is provided
    */
   constructor(config) {
-    const configuredProviders = Object.keys(config.providers);
-    const registeredProviders = _Lixa.getRegisteredProviders();
-    for (const provider of configuredProviders) {
-      if (!registeredProviders.includes(provider.toLowerCase())) {
-        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);
-      }
-    }
     this.config = config;
     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;
+    this.log("INFO", "Init", "Initializing Lixa instance", {
+      providers: Object.keys(config.providers),
+      debug: this.debug
+    });
+    for (const [providerName, providerConfig] of Object.entries(config.providers)) {
+      const name = providerName.toLowerCase();
+      const typedConfig = providerConfig;
+      this.validateProviderConfig(providerName, typedConfig);
+      if (typedConfig.provider) {
+        this.validateProviderImplementation(providerName, typedConfig.provider);
+        this.log("INFO", "Init", `Registered inline provider: ${providerName}`);
+      } else {
+        if (!_Lixa.DEFAULT_PROVIDERS.has(name) && !_Lixa.CONFIGURED_PROVIDERS.has(name)) {
+          this.log("ERROR", "Init", `Provider '${providerName}' not available`);
+          throw new Error(
+            `Provider '${providerName}' is not available. Either import it from '@vunexa/lixa-providers' and include it in the configuration, or provide a custom implementation using the 'provider' field: { provider: new CustomProvider(), clientId: '...', ... }`
+          );
+        }
+        this.log("INFO", "Init", `Using registered provider: ${providerName}`);
+      }
+    }
+    this.log("INFO", "Init", "Lixa instance initialized successfully");
   }
-  log(...args) {
-    if (this.debug) {
-      console.log("[Lixa]", ...args);
+  /**
+   * Validates that a provider configuration has all required credentials.
+   * 
+   * @param name - The provider name
+   * @param config - The provider configuration
+   * @throws Error when required fields are missing or invalid
+   */
+  validateProviderConfig(name, config) {
+    const requiredFields = ["clientId", "clientSecret", "redirectUri", "scopes"];
+    const missingFields = requiredFields.filter((field) => {
+      const value = config[field];
+      return value === void 0 || value === null || typeof value === "string" && value.trim() === "";
+    });
+    if (missingFields.length > 0) {
+      throw new Error(
+        `Provider '${name}' configuration is missing required fields: ${missingFields.join(", ")}`
+      );
+    }
+    if (!Array.isArray(config.scopes)) {
+      throw new Error(
+        `Provider '${name}' configuration error: 'scopes' must be an array of strings`
+      );
+    }
+    if (config.scopes.length === 0) {
+      throw new Error(
+        `Provider '${name}' configuration error: 'scopes' array cannot be empty`
+      );
     }
   }
-  logError(...args) {
-    if (this.debug) {
-      console.error("[Lixa]", ...args);
+  /**
+   * Validates that a provider implementation has all required properties.
+   * 
+   * @param name - The provider name
+   * @param provider - The provider implementation
+   * @throws Error when required properties are missing
+   */
+  validateProviderImplementation(name, provider) {
+    const requiredProps = ["authorizationEndpoint", "tokenEndpoint", "userInfoEndpoint"];
+    const missingProps = requiredProps.filter((prop) => {
+      const value = provider[prop];
+      return !value || typeof value !== "string" || value.trim() === "";
+    });
+    if (missingProps.length > 0) {
+      throw new Error(
+        `Provider '${name}' implementation is missing required properties: ${missingProps.join(", ")}. All IProvider implementations must define: authorizationEndpoint, tokenEndpoint, and userInfoEndpoint.`
+      );
     }
   }
   /**
-   * Checks if a provider is both registered and configured for this instance.
+   * Structured debug logging with standardized format.
+   * 
+   * @param level - Log level (INFO, WARN, ERROR)
+   * @param context - Context of the log (Init, Auth, Token, Session, State)
+   * @param message - Log message
+   * @param data - Optional data to log
+   * 
+   * @remarks
+   * Format: [Lixa] [timestamp] [level] [context] message
+   * Only logs when debug mode is enabled.
+   */
+  log(level, context, message, data) {
+    if (!this.debug) return;
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const prefix = `[Lixa] [${timestamp}] [${level}] [${context}]`;
+    if (data !== void 0) {
+      console.log(`${prefix} ${message}`, data);
+    } else {
+      console.log(`${prefix} ${message}`);
+    }
+  }
+  /**
+   * Checks if a provider is configured for this instance.
    * This is a type guard that narrows the provider type for use with getAuthUrl.
    *
    * @param provider - The provider name to check (case-insensitive)
-   * @returns True if the provider is registered and configured, false otherwise
+   * @returns True if the provider is configured, false otherwise
    *
    * @example
    * ```typescript
@@ -118,14 +202,55 @@ var Lixa = class _Lixa {
    */
   isProviderConfigured(provider) {
     const providerType = provider.toLowerCase();
-    return _Lixa.CONFIGURED_PROVIDERS.has(providerType) && this.config.providers.hasOwnProperty(providerType);
+    return this.config.providers.hasOwnProperty(providerType);
+  }
+  /**
+   * Gets a provider implementation by name.
+   * Resolution priority: inline custom provider \> default providers \> legacy registry
+   * 
+   * @param name - The provider name (case-insensitive)
+   * @param config - The provider configuration
+   * @returns The provider implementation
+   * @throws Error when provider is not found
+   */
+  getProvider(name, config) {
+    if (config.provider) {
+      return config.provider;
+    }
+    const lowerName = name.toLowerCase();
+    const defaultProvider = _Lixa.DEFAULT_PROVIDERS.get(lowerName);
+    if (defaultProvider) {
+      return defaultProvider;
+    }
+    const legacyProvider = _Lixa.CONFIGURED_PROVIDERS.get(lowerName);
+    if (legacyProvider) {
+      return legacyProvider;
+    }
+    throw new Error(
+      `Provider '${name}' not found. Ensure the provider is included in the configuration with a 'provider' field, or registered using Lixa.registerProvider().`
+    );
   }
   /**
    * Registers custom OAuth providers for use with Lixa.
+   * 
+   * @deprecated This method is maintained for backward compatibility.
+   * The recommended approach is to pass providers inline in the configuration:
+   * ```typescript
+   * const lixa = new Lixa({
+   *   providers: {
+   *     custom: {
+   *       provider: new CustomProvider(),
+   *       clientId: '...',
+   *       // ...
+   *     }
+   *   }
+   * });
+   * ```
    *
    * @param providerMap - A map of provider names to IProvider implementations
    *
    * @example
+   * Legacy usage (still supported):
    * ```typescript
    * class CustomProvider implements IProvider {
    *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
@@ -150,19 +275,29 @@ var Lixa = class _Lixa {
     return Array.from(_Lixa.CONFIGURED_PROVIDERS.keys());
   }
   /**
-   * Creates a type-safe configuration that only allows registered providers.
+   * Creates a type-safe configuration.
+   * 
+   * @deprecated This method is maintained for backward compatibility.
+   * You can now pass configuration directly to the Lixa constructor without this helper.
+   * 
+   * @param config - Configuration object with provider settings
+   * @returns The same configuration object with type safety
    * 
-   * @param config - Configuration object with providers that must be registered
-   * @returns The same configuration object, but with type safety for registered providers
+   * @example
+   * New approach (recommended):
+   * ```typescript
+   * const lixa = new Lixa({
+   *   providers: {
+   *     google: {
+   *       provider: new GoogleProvider(),
+   *       clientId: '...',
+   *       // ...
+   *     }
+   *   }
+   * });
+   * ```
    */
   static createConfig(config) {
-    const configuredProviders = Object.keys(config.providers);
-    const registeredProviders = _Lixa.getRegisteredProviders();
-    for (const provider of configuredProviders) {
-      if (!registeredProviders.includes(provider.toLowerCase())) {
-        throw new Error(`Provider '${provider}' is not registered. Please register it first using Lixa.registerProvider()`);
-      }
-    }
     return config;
   }
   /**
@@ -179,14 +314,83 @@ var Lixa = class _Lixa {
   /**
    * Generates a cryptographically secure code verifier for PKCE flows.
    *
-   * @returns A 64-character hexadecimal string
+   * @returns A 64-character hexadecimal string (32 random bytes encoded as hex)
    *
    * @remarks
-   * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.
+   * This method implements the code verifier generation as specified in RFC 7636 (PKCE).
+   * 
+   * **PKCE (Proof Key for Code Exchange)** is a security extension to OAuth 2.0 that
+   * prevents authorization code interception attacks. It's especially important for
+   * public clients (mobile apps, SPAs) but is recommended for all OAuth flows.
+   * 
+   * **Generation methodology:**
+   * 1. Generate 32 cryptographically random bytes using Node.js crypto.randomBytes()
+   * 2. Encode the bytes as a hexadecimal string (64 characters)
+   * 3. The verifier is stored securely and used later in the token exchange
+   * 
+   * **RFC 7636 Requirements:**
+   * - Minimum length: 43 characters
+   * - Maximum length: 128 characters
+   * - Character set: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+   * - This implementation produces 64 hex characters, meeting the requirements
+   * 
+   * The code verifier is:
+   * - Generated when creating the authorization URL
+   * - Stored in state cache with the state parameter
+   * - Retrieved during callback handling
+   * - Sent to the token endpoint to prove the client's identity
+   * 
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+   * @see buildCodeChallenge for the corresponding challenge generation
+   * 
+   * @internal
    */
   static generateCodeVerifier() {
     return randomBytes(32).toString("hex");
   }
+  /**
+   * Generates a code challenge from a code verifier for PKCE flows.
+   *
+   * @param codeVerifier - The code verifier string (64 hex characters)
+   * @returns A base64url-encoded SHA-256 hash of the code verifier
+   *
+   * @remarks
+   * This method implements the code challenge generation as specified in RFC 7636 (PKCE)
+   * using the S256 (SHA-256) transformation method.
+   * 
+   * **Challenge generation methodology:**
+   * 1. Hash the code verifier using SHA-256
+   * 2. Encode the hash as base64
+   * 3. Convert to base64url format (RFC 4648):
+   *    - Replace '+' with '-'
+   *    - Replace '/' with '_'
+   *    - Remove trailing '=' padding
+   * 
+   * **PKCE Flow:**
+   * 1. Client generates code_verifier (random string)
+   * 2. Client creates code_challenge = BASE64URL(SHA256(code_verifier))
+   * 3. Client sends code_challenge to authorization endpoint
+   * 4. Authorization server stores the code_challenge
+   * 5. Client sends code_verifier to token endpoint
+   * 6. Authorization server verifies: SHA256(code_verifier) == code_challenge
+   * 
+   * **Security Benefits:**
+   * - Prevents authorization code interception attacks
+   * - Even if an attacker intercepts the authorization code, they cannot
+   *   exchange it for tokens without the original code_verifier
+   * - The challenge is sent in the authorization request (public)
+   * - The verifier is sent in the token request (should be kept secret)
+   * 
+   * **RFC 7636 Transformation Methods:**
+   * - plain: code_challenge = code_verifier (not recommended)
+   * - S256: code_challenge = BASE64URL(SHA256(code_verifier)) (recommended, used here)
+   * 
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5 | RFC 4648 - Base64url Encoding}
+   * @see generateCodeVerifier for the verifier generation
+   * 
+   * @internal
+   */
   static buildCodeChallenge(codeVerifier) {
     const hash = crypto.createHash("sha256").update(codeVerifier).digest("base64");
     return hash.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -209,13 +413,16 @@ var Lixa = class _Lixa {
    */
   getAuthUrl(provider, state) {
     const providerType = String(provider).toLowerCase();
+    this.log("INFO", "Auth", `Generating authorization URL for provider: ${providerType}`);
     const providerConfig = this.findProviderByType(providerType);
-    const providerImpl = _Lixa.CONFIGURED_PROVIDERS.get(providerType);
-    if (!providerConfig || !providerImpl) {
-      throw new Error(`Provider ${providerType} not configured`);
+    if (!providerConfig) {
+      this.log("ERROR", "Auth", `Provider '${String(provider)}' is not configured`);
+      throw new Error(`Provider '${String(provider)}' is not configured in this Lixa instance`);
     }
+    const providerImpl = this.getProvider(providerType, providerConfig);
     const codeVerifier = _Lixa.generateCodeVerifier();
     const codeChallenge = _Lixa.buildCodeChallenge(codeVerifier);
+    this.log("INFO", "State", `Saving state for provider: ${providerType}`, { state });
     this.stateDao.saveState(
       state,
       {
@@ -236,7 +443,12 @@ var Lixa = class _Lixa {
       code_challenge_method: "S256",
       ...providerConfig.extraConfig
     });
-    return `${providerImpl.authorizationEndpoint}?${params.toString()}`;
+    const authUrl = `${providerImpl.authorizationEndpoint}?${params.toString()}`;
+    this.log("INFO", "Auth", `Authorization URL generated successfully`, {
+      provider: providerType,
+      endpoint: providerImpl.authorizationEndpoint
+    });
+    return authUrl;
   }
   /**
    * Handles the OAuth callback and creates a user session.
@@ -262,37 +474,50 @@ var Lixa = class _Lixa {
     code,
     state
   }) {
+    const providerType = String(provider).toLowerCase();
+    this.log("INFO", "Auth", `Handling OAuth callback for provider: ${providerType}`);
     if (!code || code.trim() === "") {
+      this.log("ERROR", "Auth", "Invalid or missing authorization code in callback");
       throw new Error("Invalid or missing code in callback");
     }
     if (!state || state.trim() === "") {
+      this.log("ERROR", "Auth", "Invalid or missing state in callback");
       throw new Error("Invalid or missing state in callback");
     }
+    this.log("INFO", "State", "Validating state parameter", { state });
     const cachedState = await this.stateDao.getState(state);
     if (!cachedState) {
+      this.log("ERROR", "State", "State validation failed: state not found or expired", { state });
       throw new Error("Invalid or expired state");
     }
+    this.log("INFO", "State", "State validated successfully, removing from cache");
     await this.stateDao.deleteState(state);
     const codeVerifier = cachedState.codeVerifier;
-    const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
-    const providerImpl = _Lixa.CONFIGURED_PROVIDERS.get(providerType);
-    if (!providerConfig || !providerImpl) {
-      throw new Error(`Provider ${String(provider)} not configured`);
+    if (!providerConfig) {
+      this.log("ERROR", "Auth", `Provider '${String(provider)}' is not configured`);
+      throw new Error(`Provider '${String(provider)}' is not configured in this Lixa instance`);
     }
+    const providerImpl = this.getProvider(providerType, providerConfig);
+    this.log("INFO", "Token", `Exchanging authorization code for tokens`, { provider: providerType });
     const tokens = await this.exchangeCodeForToken(
       code,
       providerConfig,
       providerImpl,
       codeVerifier
     );
+    this.log("INFO", "Token", "Token exchange successful");
+    this.log("INFO", "Session", "Creating user session");
     const session = await this.sessionStrategy.createSession(tokens);
     const sessionId = randomBytes(32).toString("hex");
+    this.log("INFO", "Session", "Storing session", { sessionId });
     await this.sesionDao.saveSession(sessionId, session, 86400);
+    this.log("INFO", "Session", "Session created successfully", { sessionId });
     return sessionId;
   }
-  fetchSessionInfo(sessionId) {
-    return this.sesionDao.getSession(sessionId);
+  async fetchSessionInfo(sessionId) {
+    const sessionData = await this.sesionDao.getSession(sessionId);
+    return sessionData;
   }
   async exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier) {
     const body = {
@@ -306,8 +531,9 @@ 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);
+    this.log("INFO", "Token", "Sending token exchange request", {
+      endpoint: providerImpl.tokenEndpoint
+    });
     const response = await fetch(providerImpl.tokenEndpoint, {
       method: "POST",
       headers: {
@@ -318,15 +544,25 @@ var Lixa = class _Lixa {
     });
     if (!response.ok) {
       const errorBody = await response.text();
-      this.logError("Token Exchange - Error response:", errorBody);
+      this.log("ERROR", "Token", "Token exchange failed", {
+        status: response.status,
+        statusText: response.statusText,
+        error: errorBody
+      });
       throw new Error(
         `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`
       );
     }
+    this.log("INFO", "Token", "Token exchange response received successfully");
     return response.json();
   }
   findProviderByType(providerType) {
-    return this.config.providers[providerType];
+    for (const [key, value] of Object.entries(this.config.providers)) {
+      if (key.toLowerCase() === providerType.toLowerCase()) {
+        return value;
+      }
+    }
+    return void 0;
   }
 };
 export {