@vunexa/lixa 0.0.1-alpha.8 → 0.1.0

package/dist/index.js

@@ -1,10 +1,993 @@
-/**
- * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
- *
- * @remarks
- * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
- *
- * @packageDocumentation
- */
-export { Lixa } from "./lixa";
+// src/lixa.ts
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/types.ts
+var AccountLinkingStrategy = /* @__PURE__ */ ((AccountLinkingStrategy2) => {
+  AccountLinkingStrategy2["AUTO_LINK_BY_VERIFIED_EMAIL"] = "AUTO_LINK_BY_VERIFIED_EMAIL";
+  AccountLinkingStrategy2["ISOLATED"] = "ISOLATED";
+  return AccountLinkingStrategy2;
+})(AccountLinkingStrategy || {});
+
+// src/dao/state-cache.ts
+import NodeCache from "node-cache";
+import { randomBytes } from "crypto";
+var LocalStateHandler = class {
+  cache;
+  stateStorage;
+  constructor(defaultTtlSeconds = 600) {
+    this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });
+    this.stateStorage = {
+      saveState: async (state, data, expiresInSeconds) => {
+        this.cache.set(state, data, expiresInSeconds);
+      },
+      getState: async (state) => {
+        return this.cache.get(state) || null;
+      },
+      deleteState: async (state) => {
+        this.cache.del(state);
+      }
+    };
+  }
+  // Default GenerateState implementation
+  async generateState(provider) {
+    const state = randomBytes(16).toString("hex");
+    const codeVerifier = randomBytes(32).toString("hex");
+    return {
+      state,
+      data: {
+        provider,
+        codeVerifier,
+        createdAt: Date.now()
+      }
+    };
+  }
+};
+
+// src/lixa.ts
+import crypto from "crypto";
+
+// src/dao/session-cache.ts
+import NodeCache2 from "node-cache";
+var LocalSessionHandler = class {
+  cache;
+  emailToSessionMap = /* @__PURE__ */ new Map();
+  sessionStorage;
+  constructor(defaultTtlSeconds = 600) {
+    this.cache = new NodeCache2({ stdTTL: defaultTtlSeconds });
+    this.sessionStorage = {
+      saveSession: async (sessionId, session, expiresInSeconds) => {
+        this.cache.set(sessionId, session, expiresInSeconds);
+        if (session.email) {
+          this.emailToSessionMap.set(session.email.toLowerCase(), sessionId);
+        }
+      },
+      getSession: async (sessionId) => {
+        return this.cache.get(sessionId) || null;
+      },
+      deleteSession: async (sessionId) => {
+        const session = this.cache.get(sessionId);
+        if (session?.email) {
+          this.emailToSessionMap.delete(session.email.toLowerCase());
+        }
+        this.cache.del(sessionId);
+      },
+      getSessionByEmail: async (email) => {
+        const normalizedEmail = email.toLowerCase();
+        const sessionId = this.emailToSessionMap.get(normalizedEmail);
+        if (!sessionId) return null;
+        const session = this.cache.get(sessionId);
+        if (!session) {
+          this.emailToSessionMap.delete(normalizedEmail);
+          return null;
+        }
+        return { sessionId, session };
+      }
+    };
+  }
+  // Default GenerateSession implementation
+  async GenerateSession(tokenData, providerMetadata) {
+    if (!tokenData.access_token || typeof tokenData.access_token !== "string") {
+      throw new Error("No valid access token found in OAuth response");
+    }
+    const session = {
+      token: tokenData.access_token,
+      raw: tokenData
+    };
+    return session;
+  }
+};
+
+// src/utils/user-info.ts
+function decodeIdToken(idToken) {
+  const parts = idToken.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid ID token format: expected 3 parts separated by dots");
+  }
+  const base64Payload = parts[1];
+  if (!base64Payload) {
+    throw new Error("Invalid ID token: missing payload section");
+  }
+  const payload = Buffer.from(base64Payload, "base64").toString();
+  try {
+    return JSON.parse(payload);
+  } catch (error) {
+    throw new Error("Invalid ID token: failed to parse payload JSON");
+  }
+}
+function determineProviderFromIssuer(userInfo) {
+  if (!userInfo.iss) {
+    return null;
+  }
+  const issuer = userInfo.iss.toLowerCase();
+  if (issuer.includes("accounts.google.com")) {
+    return "google";
+  }
+  if (issuer.includes("github")) {
+    return "github";
+  }
+  return null;
+}
+async function fetchUserInfo(accessToken, userInfoEndpoint) {
+  const response = await fetch(userInfoEndpoint, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/json"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch user info: ${response.status} ${response.statusText}`);
+  }
+  const data = await response.json();
+  if (!data || typeof data !== "object" || !("email" in data) || typeof data.email !== "string") {
+    throw new Error(`Invalid user info response: missing or invalid email`);
+  }
+  return {
+    email: data.email,
+    id: "id" in data ? String(data.id) : void 0,
+    sub: "sub" in data ? String(data.sub) : void 0,
+    given_name: "given_name" in data ? String(data.given_name) : void 0,
+    family_name: "family_name" in data ? String(data.family_name) : void 0,
+    name: "name" in data ? String(data.name) : void 0,
+    picture: "picture" in data ? String(data.picture) : void 0,
+    email_verified: "email_verified" in data ? Boolean(data.email_verified) : void 0,
+    iss: "iss" in data ? String(data.iss) : void 0
+  };
+}
+async function extractUserInfo(tokenData, providerMetadata) {
+  let userInfo;
+  const userInfoEndpoint = providerMetadata.endpoints.userInfo;
+  if (tokenData.id_token) {
+    userInfo = decodeIdToken(tokenData.id_token);
+  } else if (tokenData.access_token) {
+    userInfo = await fetchUserInfo(tokenData.access_token, userInfoEndpoint);
+  } else {
+    throw new Error("No ID token or access token available to fetch user info");
+  }
+  return { userInfo };
+}
+
+// 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_HANDLER = new LocalStateHandler();
+  static LOCAL_SESSION_HANDLER = new LocalSessionHandler();
+  config;
+  stateHandler;
+  sessionHandler;
+  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) {
+    this.config = config;
+    this.stateHandler = config.stateHandler || _Lixa.LOCAL_STATE_HANDLER;
+    this.sessionHandler = config.sessionHandler || _Lixa.LOCAL_SESSION_HANDLER;
+    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");
+  }
+  /**
+   * 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`
+      );
+    }
+  }
+  /**
+   * 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.`
+      );
+    }
+  }
+  /**
+   * 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 configured, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (lixa.isProviderConfigured(provider)) {
+   *   // TypeScript now knows provider is a valid ConfiguredProviderKey
+   *   const authUrl = lixa.getAuthUrl(provider, state);
+   * }
+   * ```
+   */
+  isProviderConfigured(provider) {
+    const providerType = provider.toLowerCase();
+    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';
+   *   tokenEndpoint = 'https://custom.com/oauth/token';
+   *   userInfoEndpoint = 'https://custom.com/api/user';
+   * }
+   *
+   * Lixa.registerProvider({ custom: new CustomProvider() });
+   * ```
+   */
+  static registerProvider(providerMap) {
+    Object.entries(providerMap).forEach(([key, providerImpl]) => {
+      _Lixa.CONFIGURED_PROVIDERS.set(key.toLowerCase(), providerImpl);
+    });
+  }
+  /**
+   * Gets the list of registered provider names.
+   * 
+   * @returns Array of registered provider names
+   */
+  static getRegisteredProviders() {
+    return Array.from(_Lixa.CONFIGURED_PROVIDERS.keys());
+  }
+  /**
+   * 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
+   * 
+   * @example
+   * New approach (recommended):
+   * ```typescript
+   * const lixa = new Lixa({
+   *   providers: {
+   *     google: {
+   *       provider: new GoogleProvider(),
+   *       clientId: '...',
+   *       // ...
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  static createConfig(config) {
+    return config;
+  }
+  /**
+   * Generates a cryptographically secure random state parameter for OAuth flows.
+   *
+   * @returns A 32-character hexadecimal string
+   *
+   * @remarks
+   * The state parameter is used to prevent CSRF attacks in OAuth flows.
+   */
+  static generateRandomState() {
+    return randomBytes2(16).toString("hex");
+  }
+  /**
+   * Generates a cryptographically secure code verifier for PKCE flows.
+   *
+   * @returns A 64-character hexadecimal string (32 random bytes encoded as hex)
+   *
+   * @remarks
+   * 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 randomBytes2(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(/=+$/, "");
+  }
+  /**
+   * Generates the authorization URL for the specified provider.
+   *
+   * @param provider - The provider name (must be a configured provider key)
+   * @param state - The state parameter for CSRF protection
+   * @returns The complete authorization URL to redirect users to
+   *
+   * @throws Error when the provider is not configured
+   *
+   * @example
+   * ```typescript
+   * const state = Lixa.generateRandomState();
+   * const authUrl = lixa.getAuthUrl('google', state);
+   * res.redirect(authUrl);
+   * ```
+   */
+  async getAuthUrl(provider, state) {
+    const providerType = String(provider).toLowerCase();
+    this.log("INFO", "Auth", `Generating authorization URL for provider: ${providerType}`);
+    const providerConfig = this.findProviderByType(providerType);
+    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);
+    let stateValue;
+    let codeVerifier;
+    if (this.stateHandler.generateState) {
+      this.log("INFO", "State", "Calling custom GenerateState");
+      const generated = await this.stateHandler.generateState(providerType);
+      stateValue = state || generated.state;
+      codeVerifier = generated.data.codeVerifier;
+      const storage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      await storage.saveState(stateValue, generated.data, 300);
+    } else {
+      this.log("INFO", "State", "Using default state generation");
+      stateValue = state || randomBytes2(16).toString("hex");
+      codeVerifier = randomBytes2(32).toString("hex");
+      const storage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      await storage.saveState(
+        stateValue,
+        {
+          createdAt: Date.now(),
+          provider: providerType,
+          codeVerifier
+        },
+        300
+        // 5 minutes in seconds
+      );
+    }
+    const codeChallenge = _Lixa.buildCodeChallenge(codeVerifier);
+    this.log("INFO", "State", `Saved state for provider: ${providerType}`, { state: stateValue });
+    const authNScopes = this.resolveAuthNScopes(providerType, providerConfig.scopes, providerImpl);
+    const params = new URLSearchParams({
+      client_id: providerConfig.clientId,
+      redirect_uri: providerConfig.redirectUri,
+      scope: authNScopes.join(" "),
+      state: stateValue,
+      response_type: "code",
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      ...providerConfig.extraConfig
+    });
+    const authUrl = `${providerImpl.authorizationEndpoint}?${params.toString()}`;
+    this.log("INFO", "Auth", `Authorization URL generated successfully`, {
+      provider: providerType,
+      endpoint: providerImpl.authorizationEndpoint
+    });
+    return authUrl;
+  }
+  /**
+   * Restricts primary authentication scopes strictly to AuthN identity scopes.
+   */
+  resolveAuthNScopes(providerType, configuredScopes, providerImpl) {
+    const defaultAuthScopes = {
+      google: ["openid", "email", "profile"],
+      github: ["read:user", "user:email"],
+      microsoft: ["openid", "email", "profile"]
+    };
+    const standardAuthNScopes = [
+      "openid",
+      "email",
+      "profile",
+      "read:user",
+      "user:email",
+      "read:email",
+      "user:profile",
+      "user"
+    ];
+    const allowedAuthNScopes = /* @__PURE__ */ new Set([
+      ...standardAuthNScopes,
+      ...providerImpl.authScopes || [],
+      ...defaultAuthScopes[providerType] || []
+    ]);
+    const validAuthNScopes = (configuredScopes || []).filter((scope) => allowedAuthNScopes.has(scope));
+    const nonAuthNScopes = (configuredScopes || []).filter((scope) => !allowedAuthNScopes.has(scope));
+    if (nonAuthNScopes.length > 0) {
+      this.log(
+        "WARN",
+        "Auth",
+        `Primary authentication is strictly limited to AuthN scopes. Excluded non-AuthN resource scopes: [${nonAuthNScopes.join(
+          ", "
+        )}]. Use lixa.getResourceAuthUrl() post-login to connect resource providers.`
+      );
+    }
+    if (validAuthNScopes.length > 0) {
+      return validAuthNScopes;
+    }
+    return providerImpl.authScopes || defaultAuthScopes[providerType] || ["openid", "email", "profile"];
+  }
+  /**
+   * Handles the OAuth callback and creates a user session.
+   *
+   * @param provider - The provider name (must be a configured provider key)
+   * @param code - The authorization code from the provider
+   * @param state - The state parameter for validation
+   * @returns A Promise that resolves to the session ID
+   *
+   * @throws Error when code or state is missing/invalid, or provider is not configured
+   *
+   * @example
+   * ```typescript
+   * const sessionId = await lixa.handleCallback({
+   *   provider: 'google',
+   *   code: req.query.code,
+   *   state: req.query.state
+   * });
+   * ```
+   */
+  async handleCallback({
+    provider,
+    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 stateStorage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+    const cachedState = await stateStorage.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 stateStorage.deleteState(state);
+    const codeVerifier = cachedState.codeVerifier;
+    const providerConfig = this.findProviderByType(providerType);
+    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", "Generating user session");
+    const providerMetadata = {
+      name: providerType,
+      endpoints: {
+        authorization: providerImpl.authorizationEndpoint,
+        token: providerImpl.tokenEndpoint,
+        userInfo: providerImpl.userInfoEndpoint
+      }
+    };
+    let extractedUserInfo;
+    try {
+      const { userInfo } = await extractUserInfo(tokens, providerMetadata);
+      extractedUserInfo = userInfo;
+    } catch {
+    }
+    const generateSession = this.sessionHandler.generateSession || _Lixa.LOCAL_SESSION_HANDLER.GenerateSession.bind(_Lixa.LOCAL_SESSION_HANDLER);
+    if (this.sessionHandler.generateSession) {
+      this.log("INFO", "Session", "Calling custom GenerateSession");
+    } else {
+      this.log("INFO", "Session", "Using default session generation");
+    }
+    const session = await generateSession(tokens, providerMetadata);
+    session.provider = session.provider || providerType;
+    if (extractedUserInfo?.email && !session.email) {
+      session.email = extractedUserInfo.email;
+    }
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const linkingConfig = this.config.accountLinking;
+    const mode = String(linkingConfig?.mode || "");
+    const isLinkByEmail = mode === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || mode === "AUTO_LINK_BY_VERIFIED_EMAIL" || mode === "linkByEmail";
+    const email = extractedUserInfo?.email;
+    const isVerified = extractedUserInfo?.email_verified !== false;
+    const requireVerified = linkingConfig?.requireVerifiedEmail ?? true;
+    const canLink = isLinkByEmail && email && (!requireVerified || isVerified);
+    if (canLink && sessionStorage.getSessionByEmail) {
+      const existingRecord = await sessionStorage.getSessionByEmail(email);
+      if (existingRecord) {
+        this.log("INFO", "AccountLinking", `Linking provider '${providerType}' to existing session for email '${email}'`);
+        const { sessionId: existingSessionId, session: existingSession } = existingRecord;
+        existingSession.accounts = existingSession.accounts || {};
+        existingSession.accounts[providerType] = {
+          provider: providerType,
+          providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
+          email,
+          accessToken: tokens.access_token,
+          raw: tokens,
+          linkedAt: Date.now()
+        };
+        existingSession.provider = providerType;
+        existingSession.token = tokens.access_token;
+        existingSession.raw = tokens;
+        await sessionStorage.saveSession(existingSessionId, existingSession, 86400);
+        return existingSessionId;
+      }
+    }
+    session.accounts = session.accounts || {};
+    session.accounts[providerType] = {
+      provider: providerType,
+      providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
+      email: extractedUserInfo?.email,
+      accessToken: tokens.access_token,
+      raw: tokens,
+      linkedAt: Date.now()
+    };
+    const sessionId = randomBytes2(32).toString("hex");
+    session.id = sessionId;
+    this.log("INFO", "Session", "Storing session", { sessionId });
+    await sessionStorage.saveSession(sessionId, session, 86400);
+    this.log("INFO", "Session", "Session created successfully", { sessionId });
+    return sessionId;
+  }
+  /**
+   * Explicitly link a new OAuth provider account to an active session.
+   * 
+   * @param params - Object containing sessionId, provider, code, and optional state
+   * @returns The active session ID with the newly linked provider
+   */
+  async linkAccount(params) {
+    const { sessionId, provider, code, state } = params;
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const existingSession = await sessionStorage.getSession(sessionId);
+    if (!existingSession) {
+      throw new Error("Invalid session ID. User must be authenticated to link an account.");
+    }
+    const providerType = String(provider).toLowerCase();
+    const providerConfig = this.findProviderByType(providerType);
+    if (!providerConfig) {
+      throw new Error(`Provider '${String(provider)}' is not configured`);
+    }
+    const providerImpl = this.getProvider(providerType, providerConfig);
+    let codeVerifier = randomBytes2(32).toString("hex");
+    if (state) {
+      const stateStorage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      const cachedState = await stateStorage.getState(state);
+      if (cachedState) {
+        codeVerifier = cachedState.codeVerifier;
+        await stateStorage.deleteState(state);
+      }
+    }
+    const tokens = await this.exchangeCodeForToken(providerType, providerConfig, providerImpl, codeVerifier);
+    const providerMetadata = {
+      name: providerType,
+      endpoints: {
+        authorization: providerImpl.authorizationEndpoint,
+        token: providerImpl.tokenEndpoint,
+        userInfo: providerImpl.userInfoEndpoint
+      }
+    };
+    let extractedUserInfo;
+    try {
+      const { userInfo } = await extractUserInfo(tokens, providerMetadata);
+      extractedUserInfo = userInfo;
+    } catch {
+    }
+    existingSession.accounts = existingSession.accounts || {};
+    existingSession.accounts[providerType] = {
+      provider: providerType,
+      providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
+      email: extractedUserInfo?.email,
+      accessToken: tokens.access_token,
+      raw: tokens,
+      linkedAt: Date.now()
+    };
+    if (extractedUserInfo?.email && !existingSession.email) {
+      existingSession.email = extractedUserInfo.email;
+    }
+    await sessionStorage.saveSession(sessionId, existingSession, 86400);
+    return sessionId;
+  }
+  /**
+   * Unlinks an OAuth provider account from an active session.
+   * 
+   * @param sessionId - Active session ID
+   * @param providerToUnlink - Provider name to unlink (e.g. 'github')
+   * @returns Promise resolving to true on successful unlink
+   */
+  async unlinkAccount(sessionId, providerToUnlink) {
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const session = await sessionStorage.getSession(sessionId);
+    if (!session || !session.accounts) {
+      throw new Error("Session not found or has no linked accounts.");
+    }
+    const linkedProviders = Object.keys(session.accounts);
+    if (linkedProviders.length <= 1) {
+      throw new Error("Cannot unlink the only authentication provider for this account.");
+    }
+    delete session.accounts[providerToUnlink.toLowerCase()];
+    await sessionStorage.saveSession(sessionId, session, 86400);
+    return true;
+  }
+  /**
+   * Generates an authorization URL for connecting a resource provider (AuthZ) post-login.
+   * 
+   * @remarks
+   * Resource authorization is kept strictly separate from primary authentication (AuthN).
+   * Call this method after a user is authenticated to request permissions for external API access
+   * (e.g. GitHub repositories, Google Drive, Slack, etc.).
+   * 
+   * @param params - Object containing sessionId, provider, requested resource scopes, and optional state
+   * @returns The authorization URL for resource consent
+   */
+  async getResourceAuthUrl(params) {
+    const { sessionId, provider, scopes, state } = params;
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const activeSession = await sessionStorage.getSession(sessionId);
+    if (!activeSession) {
+      throw new Error("Authentication required. Active session must exist to connect resource providers.");
+    }
+    const providerType = String(provider).toLowerCase();
+    const providerConfig = this.findProviderByType(providerType);
+    if (!providerConfig) {
+      throw new Error(`Provider '${String(provider)}' is not configured`);
+    }
+    const providerImpl = this.getProvider(providerType, providerConfig);
+    const stateValue = state || randomBytes2(16).toString("hex");
+    const codeVerifier = randomBytes2(32).toString("hex");
+    const storage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+    await storage.saveState(
+      stateValue,
+      {
+        createdAt: Date.now(),
+        provider: providerType,
+        codeVerifier
+      },
+      300
+    );
+    const codeChallenge = _Lixa.buildCodeChallenge(codeVerifier);
+    const searchParams = new URLSearchParams({
+      client_id: providerConfig.clientId,
+      redirect_uri: providerConfig.redirectUri,
+      scope: scopes.join(" "),
+      state: stateValue,
+      response_type: "code",
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      ...providerConfig.extraConfig
+    });
+    return `${providerImpl.authorizationEndpoint}?${searchParams.toString()}`;
+  }
+  /**
+   * Handles the OAuth callback for a connected resource provider and stores resource tokens on the session.
+   * 
+   * @param params - Object containing sessionId, provider, code, state, and requested scopes
+   * @returns Updated Session containing stored resource tokens under session.resources[provider]
+   */
+  async handleResourceCallback(params) {
+    const { sessionId, provider, code, state, scopes } = params;
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const activeSession = await sessionStorage.getSession(sessionId);
+    if (!activeSession) {
+      throw new Error("Authentication required. Active session not found for resource connection.");
+    }
+    const providerType = String(provider).toLowerCase();
+    const providerConfig = this.findProviderByType(providerType);
+    if (!providerConfig) {
+      throw new Error(`Provider '${String(provider)}' is not configured`);
+    }
+    const providerImpl = this.getProvider(providerType, providerConfig);
+    let codeVerifier = randomBytes2(32).toString("hex");
+    if (state) {
+      const stateStorage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      const cachedState = await stateStorage.getState(state);
+      if (cachedState) {
+        codeVerifier = cachedState.codeVerifier;
+        await stateStorage.deleteState(state);
+      }
+    }
+    const tokens = await this.exchangeCodeForToken(providerType, providerConfig, providerImpl, codeVerifier);
+    activeSession.resources = activeSession.resources || {};
+    activeSession.resources[providerType] = {
+      provider: providerType,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      scopes: scopes || (tokens.scope ? tokens.scope.split(" ") : []),
+      raw: tokens,
+      connectedAt: Date.now()
+    };
+    await sessionStorage.saveSession(sessionId, activeSession, 86400);
+    return activeSession;
+  }
+  /**
+   * Retrieves a connected resource provider token for an active session.
+   * 
+   * @param sessionId - Active session ID
+   * @param provider - Provider identifier (e.g. 'github')
+   */
+  async getConnectedResource(sessionId, provider) {
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const activeSession = await sessionStorage.getSession(sessionId);
+    if (!activeSession || !activeSession.resources) return null;
+    return activeSession.resources[provider.toLowerCase()] || null;
+  }
+  /**
+   * Disconnects a resource provider from an active session.
+   * 
+   * @param sessionId - Active session ID
+   * @param provider - Provider identifier to disconnect
+   */
+  async disconnectResource(sessionId, provider) {
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const activeSession = await sessionStorage.getSession(sessionId);
+    if (!activeSession || !activeSession.resources) return false;
+    delete activeSession.resources[provider.toLowerCase()];
+    await sessionStorage.saveSession(sessionId, activeSession, 86400);
+    return true;
+  }
+  async fetchSessionInfo(sessionId) {
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    return await sessionStorage.getSession(sessionId);
+  }
+  async exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier) {
+    const body = {
+      client_id: providerConfig.clientId,
+      client_secret: providerConfig.clientSecret,
+      code,
+      redirect_uri: providerConfig.redirectUri,
+      grant_type: "authorization_code"
+    };
+    if (codeVerifier) {
+      body.code_verifier = codeVerifier;
+    }
+    const params = new URLSearchParams(body);
+    this.log("INFO", "Token", "Sending token exchange request", {
+      endpoint: providerImpl.tokenEndpoint
+    });
+    const response = await fetch(providerImpl.tokenEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: params.toString()
+    });
+    if (!response.ok) {
+      const errorBody = await response.text();
+      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) {
+    for (const [key, value] of Object.entries(this.config.providers)) {
+      if (key.toLowerCase() === providerType.toLowerCase()) {
+        return value;
+      }
+    }
+    return void 0;
+  }
+};
+export {
+  AccountLinkingStrategy,
+  Lixa,
+  decodeIdToken,
+  determineProviderFromIssuer,
+  extractUserInfo,
+  fetchUserInfo
+};
 //# sourceMappingURL=index.js.map