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

package/dist/index.cjs

@@ -31,11 +31,31 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AccountLinkingStrategy: () => AccountLinkingStrategy,
+  AccountUnlinkError: () => AccountUnlinkError,
+  DEFAULT_SESSION_COOKIE_NAME: () => DEFAULT_SESSION_COOKIE_NAME,
+  DEFAULT_SESSION_MAX_AGE_SECONDS: () => DEFAULT_SESSION_MAX_AGE_SECONDS,
+  DEFAULT_STATE_COOKIE_NAME: () => DEFAULT_STATE_COOKIE_NAME,
+  DEFAULT_STATE_MAX_AGE_SECONDS: () => DEFAULT_STATE_MAX_AGE_SECONDS,
+  EmailNotVerifiedError: () => EmailNotVerifiedError,
+  InvalidOAuthCallbackError: () => InvalidOAuthCallbackError,
+  InvalidProviderConfigError: () => InvalidProviderConfigError,
+  InvalidStateError: () => InvalidStateError,
   Lixa: () => Lixa,
+  LixaError: () => LixaError,
+  ProviderNotConfiguredError: () => ProviderNotConfiguredError,
+  RefreshTokenError: () => RefreshTokenError,
+  SessionNotFoundError: () => SessionNotFoundError,
+  TokenExchangeError: () => TokenExchangeError,
+  clearSessionCookie: () => clearSessionCookie,
+  clearStateCookie: () => clearStateCookie,
+  createSessionCookie: () => createSessionCookie,
+  createStateCookie: () => createStateCookie,
   decodeIdToken: () => decodeIdToken,
   determineProviderFromIssuer: () => determineProviderFromIssuer,
   extractUserInfo: () => extractUserInfo,
-  fetchUserInfo: () => fetchUserInfo
+  fetchUserInfo: () => fetchUserInfo,
+  isProductionEnvironment: () => isProductionEnvironment,
+  serializeCookie: () => serializeCookie
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -207,6 +227,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();
@@ -252,8 +346,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}`);
@@ -266,7 +361,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"];
@@ -275,18 +370,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 }
       );
     }
   }
@@ -295,7 +393,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"];
@@ -304,8 +402,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 }
       );
     }
   }
@@ -372,8 +471,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().` }
     );
   }
   /**
@@ -563,7 +663,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;
@@ -679,18 +781,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);
@@ -698,7 +800,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 });
@@ -791,12 +895,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 = (0, import_crypto2.randomBytes)(32).toString("hex");
@@ -849,11 +953,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);
@@ -875,12 +982,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 || (0, import_crypto2.randomBytes)(16).toString("hex");
@@ -960,12 +1067,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 = (0, import_crypto2.randomBytes)(32).toString("hex");
@@ -1066,11 +1173,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 = {
@@ -1089,7 +1199,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;
@@ -1112,7 +1225,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);
@@ -1148,10 +1261,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,
@@ -1182,8 +1307,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");
@@ -1198,13 +1325,152 @@ 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
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   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.cjs.map