@vunexa/lixa 0.1.6-alpha.7 → 0.1.6-alpha.8

package/dist/index.js

@@ -166,6 +166,80 @@ async function extractUserInfo(tokenData, providerMetadata) {
   return { userInfo };
 }
 
+// src/errors.ts
+var LixaError = class extends Error {
+  /**
+   * Standard error code string.
+   */
+  code;
+  /**
+   * Additional error context data.
+   */
+  details;
+  constructor(message, code = "LIXA_ERROR", details) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidStateError = class extends LixaError {
+  constructor(message = "Invalid or expired state", details) {
+    super(message, "INVALID_STATE", details);
+  }
+};
+var ProviderNotConfiguredError = class extends LixaError {
+  constructor(provider, details) {
+    const message = details?.message && typeof details.message === "string" ? details.message : `Provider '${provider}' 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: '...', ... }`;
+    super(message, "PROVIDER_NOT_CONFIGURED", {
+      provider,
+      ...details
+    });
+  }
+};
+var InvalidProviderConfigError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "INVALID_PROVIDER_CONFIG", details);
+  }
+};
+var InvalidOAuthCallbackError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "INVALID_OAUTH_CALLBACK", details);
+  }
+};
+var TokenExchangeError = class extends LixaError {
+  status;
+  constructor(message, status, details) {
+    super(message, "TOKEN_EXCHANGE_FAILED", { status, ...details });
+    this.status = status;
+  }
+};
+var SessionNotFoundError = class extends LixaError {
+  constructor(message = "Active session not found or has expired", details) {
+    super(message, "SESSION_NOT_FOUND", details);
+  }
+};
+var EmailNotVerifiedError = class extends LixaError {
+  constructor(email, details) {
+    super(
+      `Cannot link account: email '${email || "unknown"}' is not verified by the identity provider`,
+      "EMAIL_NOT_VERIFIED",
+      { email, ...details }
+    );
+  }
+};
+var AccountUnlinkError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "ACCOUNT_UNLINK_ERROR", details);
+  }
+};
+var RefreshTokenError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "REFRESH_TOKEN_ERROR", details);
+  }
+};
+
 // src/lixa.ts
 var Lixa = class _Lixa {
   static DEFAULT_PROVIDERS = /* @__PURE__ */ new Map();
@@ -211,8 +285,9 @@ var Lixa = class _Lixa {
       } 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: '...', ... }`
+          throw new ProviderNotConfiguredError(
+            providerName,
+            { hint: `Ensure the provider is registered via '@vunexa/lixa-providers' or provided inline.` }
           );
         }
         this.log("INFO", "Init", `Using registered provider: ${providerName}`);
@@ -225,7 +300,7 @@ var Lixa = class _Lixa {
    * 
    * @param name - The provider name
    * @param config - The provider configuration
-   * @throws Error when required fields are missing or invalid
+   * @throws InvalidProviderConfigError when required fields are missing or invalid
    */
   validateProviderConfig(name, config) {
     const requiredFields = ["clientId", "clientSecret", "redirectUri", "scopes"];
@@ -234,18 +309,21 @@ var Lixa = class _Lixa {
       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(", ")}`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' configuration is missing required fields: ${missingFields.join(", ")}`,
+        { provider: name, missingFields }
       );
     }
     if (!Array.isArray(config.scopes)) {
-      throw new Error(
-        `Provider '${name}' configuration error: 'scopes' must be an array of strings`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' configuration error: 'scopes' must be an array of strings`,
+        { provider: name }
       );
     }
     if (config.scopes.length === 0) {
-      throw new Error(
-        `Provider '${name}' configuration error: 'scopes' array cannot be empty`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' configuration error: 'scopes' array cannot be empty`,
+        { provider: name }
       );
     }
   }
@@ -254,7 +332,7 @@ var Lixa = class _Lixa {
    * 
    * @param name - The provider name
    * @param provider - The provider implementation
-   * @throws Error when required properties are missing
+   * @throws InvalidProviderConfigError when required properties are missing
    */
   validateProviderImplementation(name, provider) {
     const requiredProps = ["authorizationEndpoint", "tokenEndpoint", "userInfoEndpoint"];
@@ -263,8 +341,9 @@ var Lixa = class _Lixa {
       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.`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' implementation is missing required properties: ${missingProps.join(", ")}. All IProvider implementations must define: authorizationEndpoint, tokenEndpoint, and userInfoEndpoint.`,
+        { provider: name, missingProps }
       );
     }
   }
@@ -331,8 +410,9 @@ var Lixa = class _Lixa {
     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().`
+    throw new ProviderNotConfiguredError(
+      name,
+      { hint: `Ensure the provider is included in the configuration with a 'provider' field, or registered using Lixa.registerProvider().` }
     );
   }
   /**
@@ -522,7 +602,9 @@ var Lixa = class _Lixa {
     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`);
+      throw new ProviderNotConfiguredError(String(provider), {
+        message: `Provider '${String(provider)}' is not configured in this Lixa instance`
+      });
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     let stateValue;
@@ -638,18 +720,18 @@ var Lixa = class _Lixa {
     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");
+      throw new InvalidOAuthCallbackError("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");
+      throw new InvalidOAuthCallbackError("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");
+      throw new InvalidStateError("Invalid or expired state", { state });
     }
     this.log("INFO", "State", "State validated successfully, removing from cache");
     await stateStorage.deleteState(state);
@@ -657,7 +739,9 @@ var Lixa = class _Lixa {
     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`);
+      throw new ProviderNotConfiguredError(String(provider), {
+        message: `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 });
@@ -750,12 +834,12 @@ var Lixa = class _Lixa {
     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.");
+      throw new SessionNotFoundError("Invalid session ID. User must be authenticated to link an account.", { sessionId });
     }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${String(provider)}' is not configured`);
+      throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     let codeVerifier = randomBytes2(32).toString("hex");
@@ -808,11 +892,14 @@ var Lixa = class _Lixa {
     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.");
+      throw new AccountUnlinkError("Session not found or has no linked accounts.", { sessionId });
     }
     const linkedProviders = Object.keys(session.accounts);
     if (linkedProviders.length <= 1) {
-      throw new Error("Cannot unlink the only authentication provider for this account.");
+      throw new AccountUnlinkError("Cannot unlink the only authentication provider for this account.", {
+        sessionId,
+        provider: providerToUnlink
+      });
     }
     delete session.accounts[providerToUnlink.toLowerCase()];
     await sessionStorage.saveSession(sessionId, session, 86400);
@@ -834,12 +921,12 @@ var Lixa = class _Lixa {
     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.");
+      throw new SessionNotFoundError("Authentication required. Active session must exist to connect resource providers.", { sessionId });
     }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${String(provider)}' is not configured`);
+      throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     const stateValue = state || randomBytes2(16).toString("hex");
@@ -919,12 +1006,12 @@ var Lixa = class _Lixa {
     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.");
+      throw new SessionNotFoundError("Authentication required. Active session not found for resource connection.", { sessionId });
     }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${String(provider)}' is not configured`);
+      throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     let codeVerifier = randomBytes2(32).toString("hex");
@@ -1025,11 +1112,14 @@ var Lixa = class _Lixa {
     const providerType = provider.toLowerCase();
     let resource = existingResource || await resourceStorage.getResource(userIdOrEmail, providerType);
     if (!resource || !resource.refreshToken) {
-      throw new Error(`No refresh token available for user '${userIdOrEmail}' on connected resource '${provider}'`);
+      throw new RefreshTokenError(
+        `No refresh token available for user '${userIdOrEmail}' on connected resource '${provider}'`,
+        { userId: userIdOrEmail, provider }
+      );
     }
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${provider}' is not configured`);
+      throw new ProviderNotConfiguredError(provider);
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     const body = {
@@ -1048,7 +1138,10 @@ var Lixa = class _Lixa {
     });
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Failed to refresh resource token for user '${userIdOrEmail}' on '${provider}': ${response.status} - ${errorText}`);
+      throw new RefreshTokenError(
+        `Failed to refresh resource token for user '${userIdOrEmail}' on '${provider}': ${response.status} - ${errorText}`,
+        { userId: userIdOrEmail, provider, status: response.status }
+      );
     }
     const tokens = await response.json();
     const expiresAt = tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0;
@@ -1071,7 +1164,7 @@ var Lixa = class _Lixa {
     const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (!activeSession) {
-      throw new Error("Active session not found.");
+      throw new SessionNotFoundError("Active session not found.", { sessionId });
     }
     const providerType = provider.toLowerCase();
     const userKey = this.getUserKeyFromSession(activeSession);
@@ -1107,10 +1200,22 @@ var Lixa = class _Lixa {
     }
     return false;
   }
+  /**
+   * Retrieves active session details from session storage.
+   */
   async fetchSessionInfo(sessionId) {
     const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
     return await sessionStorage.getSession(sessionId);
   }
+  /**
+   * Deletes a session from session storage (e.g. on logout).
+   * 
+   * @param sessionId - Active session identifier
+   */
+  async deleteSession(sessionId) {
+    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    await sessionStorage.deleteSession(sessionId);
+  }
   async exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier) {
     const body = {
       client_id: providerConfig.clientId,
@@ -1141,8 +1246,10 @@ var Lixa = class _Lixa {
         statusText: response.statusText,
         error: errorBody
       });
-      throw new Error(
-        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`
+      throw new TokenExchangeError(
+        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`,
+        response.status,
+        { statusText: response.statusText, errorBody }
       );
     }
     this.log("INFO", "Token", "Token exchange response received successfully");
@@ -1157,12 +1264,151 @@ var Lixa = class _Lixa {
     return void 0;
   }
 };
+
+// src/utils/cookies.ts
+var DEFAULT_SESSION_COOKIE_NAME = "lixa_session";
+var DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
+var DEFAULT_SESSION_MAX_AGE_SECONDS = 24 * 60 * 60;
+var DEFAULT_STATE_MAX_AGE_SECONDS = 10 * 60;
+function isProductionEnvironment() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+function serializeCookie(name, value, options) {
+  const isProd = isProductionEnvironment();
+  const path = options?.path ?? "/";
+  const httpOnly = options?.httpOnly ?? true;
+  const secure = options?.secure ?? isProd;
+  const sameSite = options?.sameSite ?? "lax";
+  const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+  if (path) {
+    parts.push(`Path=${path}`);
+  }
+  if (typeof options?.maxAge === "number") {
+    parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+    const expires = new Date(Date.now() + options.maxAge * 1e3).toUTCString();
+    parts.push(`Expires=${expires}`);
+  }
+  if (options?.domain) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (httpOnly) {
+    parts.push("HttpOnly");
+  }
+  if (secure) {
+    parts.push("Secure");
+  }
+  if (sameSite) {
+    const capitalized = sameSite.charAt(0).toUpperCase() + sameSite.slice(1).toLowerCase();
+    parts.push(`SameSite=${capitalized}`);
+  }
+  return parts.join("; ");
+}
+function createSessionCookie(sessionId, options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_SESSION_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: options?.maxAge ?? DEFAULT_SESSION_MAX_AGE_SECONDS,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, sessionId, resolvedOptions);
+  return {
+    name,
+    value: sessionId,
+    options: resolvedOptions,
+    header
+  };
+}
+function clearSessionCookie(options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_SESSION_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: 0,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, "", resolvedOptions);
+  return {
+    name,
+    value: "",
+    options: resolvedOptions,
+    header
+  };
+}
+function createStateCookie(state, options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_STATE_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: options?.maxAge ?? DEFAULT_STATE_MAX_AGE_SECONDS,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, state, resolvedOptions);
+  return {
+    name,
+    value: state,
+    options: resolvedOptions,
+    header
+  };
+}
+function clearStateCookie(options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_STATE_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: 0,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, "", resolvedOptions);
+  return {
+    name,
+    value: "",
+    options: resolvedOptions,
+    header
+  };
+}
 export {
   AccountLinkingStrategy,
+  AccountUnlinkError,
+  DEFAULT_SESSION_COOKIE_NAME,
+  DEFAULT_SESSION_MAX_AGE_SECONDS,
+  DEFAULT_STATE_COOKIE_NAME,
+  DEFAULT_STATE_MAX_AGE_SECONDS,
+  EmailNotVerifiedError,
+  InvalidOAuthCallbackError,
+  InvalidProviderConfigError,
+  InvalidStateError,
   Lixa,
+  LixaError,
+  ProviderNotConfiguredError,
+  RefreshTokenError,
+  SessionNotFoundError,
+  TokenExchangeError,
+  clearSessionCookie,
+  clearStateCookie,
+  createSessionCookie,
+  createStateCookie,
   decodeIdToken,
   determineProviderFromIssuer,
   extractUserInfo,
-  fetchUserInfo
+  fetchUserInfo,
+  isProductionEnvironment,
+  serializeCookie
 };
 //# sourceMappingURL=index.js.map