@arex95/vue-core 3.1.0 → 5.0.0

package/dist/config/axios/axiosConfig.d.ts

@@ -1,16 +1,10 @@
-import { AxiosInstance } from "axios";
-import { AxiosServiceOptions } from "@/types/AxiosServiceOptions";
-declare module "axios" {
+import { AxiosInstance } from 'axios';
+import { AxiosServiceOptions } from '@/types/AxiosServiceOptions';
+declare module 'axios' {
     interface InternalAxiosRequestConfig {
         _retry?: boolean;
     }
 }
-/**
- * A service class that encapsulates a customizable Axios instance with built-in interceptors
- * for handling authentication, token refreshing, and request cancellation. It is designed to
- * streamline API communication by automatically attaching authorization headers and managing
- * token refresh logic for 401 Unauthorized responses.
- */
 export declare class AxiosService {
     private readonly instance;
     private cancelTokenSource;
@@ -18,37 +12,19 @@ export declare class AxiosService {
     private readonly refreshTokenUrl;
     private isRefreshing;
     private failedQueue;
+    constructor(options: AxiosServiceOptions);
     /**
-     * Creates an instance of AxiosService.
-     * @param {AxiosServiceOptions} options - Configuration options for the Axios instance, such as `baseURL`, `timeout`, and custom `headers`.
+     * Resolves or rejects all queued promises waiting for a token refresh.
+     *
+     * Fix: if both error and token are null (edge case), the queue is still
+     * cleared to avoid permanently hanging promises.
      */
-    constructor(options: AxiosServiceOptions);
     private processQueue;
     private setAuthHeader;
     private initializeInterceptors;
-    /**
-     * Returns the number of active (in-flight) requests.
-     * @returns {number} The number of active requests.
-     */
     getActiveRequests(): number;
-    /**
-     * Returns the underlying Axios instance.
-     * @returns {AxiosInstance} The Axios instance.
-     */
     getAxiosInstance(): AxiosInstance;
-    /**
-     * Cancels all ongoing requests made by this Axios instance.
-     */
     cancelAllRequests(): void;
-    /**
-     * Sets a default header for all subsequent requests.
-     * @param {string} key - The header key.
-     * @param {string} value - The header value.
-     */
     setHeader(key: string, value: string): void;
-    /**
-     * Removes a default header.
-     * @param {string} key - The header key to remove.
-     */
     removeHeader(key: string): void;
 }

package/dist/config/global/callbacksConfig.d.ts

@@ -0,0 +1,14 @@
+export interface CallbacksConfig {
+    onRefreshFailed?: () => void;
+    onLogout?: () => void;
+}
+/**
+ * Configures the lifecycle callbacks for auth events.
+ * @param {CallbacksConfig} config - Callbacks to invoke on refresh failure or logout.
+ */
+export declare const configCallbacks: (config: CallbacksConfig) => void;
+/**
+ * Returns the configured lifecycle callbacks.
+ * @returns {CallbacksConfig}
+ */
+export declare const getCallbacksConfig: () => CallbacksConfig;

package/dist/config/global/index.d.ts

@@ -3,3 +3,4 @@ export * from './endpointsConfig';
 export * from './sessionConfig';
 export * from './keyConfig';
 export * from './tokenPathsConfig';
+export * from './callbacksConfig';

package/dist/index.mjs

@@ -35,33 +35,47 @@ function getTokenConfig() {
 }
 
 /**
- * Converts an `ArrayBuffer` or `Uint8Array` into a hexadecimal string representation.
+ * Returns the Web Crypto API instance, validating availability.
  *
- * @param {ArrayBuffer | Uint8Array} buffer - The buffer to convert.
- * @returns {string} The resulting hexadecimal string.
+ * Compatible with:
+ *   - Modern browsers        (window.crypto.subtle)
+ *   - Node.js 15+            (globalThis.crypto.subtle — built-in Web Crypto API)
+ *   - Nitro / Deno / Workers (globalThis.crypto.subtle)
+ *
+ * Throws a descriptive error on Node.js < 15 instead of failing silently.
+ */
+function getWebCrypto() {
+    const c = typeof globalThis !== 'undefined'
+        ? globalThis.crypto
+        : typeof crypto !== 'undefined'
+            ? crypto
+            : undefined;
+    if (!c?.subtle) {
+        throw new Error('[arex-core] Web Crypto API (crypto.subtle) is not available. ' +
+            'Requires Node.js 15+, a modern browser, or a runtime that exposes globalThis.crypto.subtle.');
+    }
+    return c;
+}
+/**
+ * Converts an `ArrayBuffer` or `Uint8Array` into a hexadecimal string.
  */
 function ab2hex(buffer) {
     return Array.from(new Uint8Array(buffer))
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
 }
 /**
  * Converts a hexadecimal string into a `Uint8Array`.
- *
- * @param {string} hex - The hexadecimal string to convert.
- * @returns {Uint8Array} The resulting `Uint8Array`.
- * @throws {TypeError} If the input is not a string.
- * @throws {Error} If the hexadecimal string has an invalid format or an odd length.
  */
 function hex2ab(hex) {
-    if (typeof hex !== "string") {
-        throw new TypeError("Input must be a string.");
+    if (typeof hex !== 'string') {
+        throw new TypeError('Input must be a string.');
     }
     if (hex.length === 0) {
         return new Uint8Array();
     }
     if (!/^[0-9a-fA-F]*$/.test(hex) || hex.length % 2 !== 0) {
-        throw new Error("Invalid hexadecimal string format or odd length.");
+        throw new Error('Invalid hexadecimal string format or odd length.');
     }
     const array = new Uint8Array(hex.length / 2);
     for (let i = 0; i < hex.length; i += 2) {
@@ -70,81 +84,66 @@ function hex2ab(hex) {
     return array;
 }
 /**
- * Derives a `CryptoKey` for AES-CBC encryption from a plain-text secret key.
- * It uses SHA-256 to hash the secret key, ensuring a fixed-length key suitable for the Web Crypto API.
+ * Derives a CryptoKey for AES-CBC-256 from a plain-text secret using SHA-256.
  *
- * @param {string} secretKey - The plain-text secret key.
- * @returns {Promise<CryptoKey>} A promise that resolves with the derived `CryptoKey`.
- * @throws {Error} If the `secretKey` is null or empty.
+ * @throws {Error} If secretKey is empty or Web Crypto API is unavailable.
  */
 async function importKey(secretKey) {
     if (!secretKey) {
-        throw new Error("Secret key cannot be null or empty.");
+        throw new Error('Secret key cannot be null or empty.');
     }
+    const wc = getWebCrypto();
     const keyMaterial = new TextEncoder().encode(secretKey);
-    const digest = await crypto.subtle.digest("SHA-256", keyMaterial);
-    return crypto.subtle.importKey("raw", digest, { name: "AES-CBC", length: 256 }, false, ["encrypt", "decrypt"]);
+    const digest = await wc.subtle.digest('SHA-256', keyMaterial);
+    return wc.subtle.importKey('raw', digest, { name: 'AES-CBC', length: 256 }, false, ['encrypt', 'decrypt']);
 }
 /**
- * Encrypts a plain-text value using AES-CBC with a given secret key.
- * A random 16-byte initialization vector (IV) is generated for each encryption.
- *
- * @param {string} value - The plain-text string to encrypt.
- * @param {string} secretKey - The secret key to use for encryption.
- * @returns {Promise<string>} A promise that resolves with a concatenated hexadecimal string of the IV and the ciphertext.
- * @throws {Error} If the `secretKey` is null or empty.
+ * Encrypts a plain-text string using AES-CBC-256.
+ * A unique 16-byte IV is generated per call.
+ * Output format: IV_hex (32 chars) + ciphertext_hex.
  */
 async function encrypt(value, secretKey) {
+    const wc = getWebCrypto();
     const key = await importKey(secretKey);
-    const iv = crypto.getRandomValues(new Uint8Array(16));
+    const iv = wc.getRandomValues(new Uint8Array(16));
     const encodedValue = new TextEncoder().encode(value);
-    const ciphertext = await crypto.subtle.encrypt({ name: "AES-CBC", iv: iv }, key, encodedValue);
+    const ciphertext = await wc.subtle.encrypt({ name: 'AES-CBC', iv }, key, encodedValue);
     return ab2hex(iv) + ab2hex(new Uint8Array(ciphertext));
 }
 /**
- * Decrypts a hexadecimal string (IV + ciphertext) using AES-CBC with a given secret key.
- *
- * @param {string} encryptedValue - The concatenated hexadecimal string of the IV and ciphertext.
- * @param {string} secretKey - The secret key to use for decryption.
- * @returns {Promise<string>} A promise that resolves with the decrypted plain-text string.
- * @throws {Error} If the encrypted value is null, empty, or too short, or if the `secretKey` is invalid.
+ * Decrypts a hex string (IV_hex + ciphertext_hex) produced by `encrypt()`.
  */
 async function decrypt(encryptedValue, secretKey) {
     if (!encryptedValue) {
-        throw new Error("Encrypted value cannot be null or empty.");
+        throw new Error('Encrypted value cannot be null or empty.');
     }
-    // For AES-CBC, the IV is ALWAYS 16 bytes.
-    // 16 bytes * 2 hex characters/byte = 32 hex characters for the IV.
     if (encryptedValue.length < 32) {
-        throw new Error("Encrypted value is too short. Expected at least 32 hexadecimal characters for the IV.");
+        throw new Error('Encrypted value is too short. Expected at least 32 hex chars for the IV.');
     }
+    const wc = getWebCrypto();
     const key = await importKey(secretKey);
-    const ivHex = encryptedValue.substring(0, 32);
-    const ciphertextHex = encryptedValue.substring(32);
-    const iv = hex2ab(ivHex);
-    const ciphertext = hex2ab(ciphertextHex);
+    const iv = hex2ab(encryptedValue.substring(0, 32));
+    const ciphertext = hex2ab(encryptedValue.substring(32));
     if (iv.byteLength !== 16) {
-        throw new Error(`Converted IV has incorrect length: ${iv.byteLength} bytes. Expected 16 bytes.`);
+        throw new Error(`IV has incorrect length: ${iv.byteLength} bytes. Expected 16.`);
     }
     if (ciphertext.byteLength === 0) {
-        throw new Error("Ciphertext is empty. No data to decrypt.");
+        throw new Error('Ciphertext is empty. Nothing to decrypt.');
     }
-    const decryptedBuffer = await crypto.subtle.decrypt({ name: "AES-CBC", iv: iv }, key, ciphertext);
+    const decryptedBuffer = await wc.subtle.decrypt({ name: 'AES-CBC', iv }, key, ciphertext);
     return new TextDecoder().decode(decryptedBuffer);
 }
 
 const isServer = typeof window === 'undefined';
 const isClient = typeof window !== 'undefined';
 function getStorage() {
-    if (isServer) {
+    if (isServer)
         return null;
-    }
     return window.localStorage;
 }
 function getSessionStorage() {
-    if (isServer) {
+    if (isServer)
         return null;
-    }
     return window.sessionStorage;
 }
 function getCookieStorage() {
@@ -154,10 +153,14 @@ function getCookieStorage() {
                 return null;
             const cookies = document.cookie.split(';');
             for (const cookie of cookies) {
-                const [name, value] = cookie.trim().split('=');
-                if (name === key) {
-                    return decodeURIComponent(value);
-                }
+                // Split on the FIRST '=' only — values may contain '=' (e.g. base64, hex).
+                const separatorIndex = cookie.indexOf('=');
+                if (separatorIndex === -1)
+                    continue;
+                const name = cookie.substring(0, separatorIndex).trim();
+                if (name !== key)
+                    continue;
+                return decodeURIComponent(cookie.substring(separatorIndex + 1));
             }
             return null;
         },
@@ -170,62 +173,57 @@ function getCookieStorage() {
                 date.setTime(date.getTime() + options.expires * 24 * 60 * 60 * 1000);
                 cookie += `; expires=${date.toUTCString()}`;
             }
-            cookie += `; path=${options?.path || '/'}`;
+            cookie += `; path=${options?.path ?? '/'}`;
             if (options?.domain) {
                 cookie += `; domain=${options.domain}`;
             }
             if (options?.secure !== false) {
-                const isSecure = options?.secure ?? (typeof window !== 'undefined' && window.location.protocol === 'https:');
-                if (isSecure) {
+                const isSecure = options?.secure ??
+                    (typeof window !== 'undefined' && window.location.protocol === 'https:');
+                if (isSecure)
                     cookie += '; Secure';
-                }
-            }
-            if (options?.sameSite) {
-                cookie += `; SameSite=${options.sameSite}`;
-            }
-            else {
-                cookie += '; SameSite=Lax';
             }
+            cookie += `; SameSite=${options?.sameSite ?? 'Lax'}`;
             if (options?.httpOnly) {
-                console.warn('HttpOnly cookies cannot be set from JavaScript. Use server-side code to set HttpOnly cookies.');
+                throw new Error('[arex-core] HttpOnly cookies cannot be set from JavaScript. ' +
+                    'Use server-side code (e.g. h3 setCookie) to set HttpOnly cookies.');
             }
             document.cookie = cookie;
         },
         removeItem: (key, options) => {
             if (isServer)
                 return;
-            const path = options?.path || '/';
+            const path = options?.path ?? '/';
             const domain = options?.domain ? `; domain=${options.domain}` : '';
             document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${path}${domain}`;
         },
     };
 }
 function getPreferredStorage() {
-    if (isServer) {
+    if (isServer)
         return getCookieStorage();
-    }
-    const storage = getStorage();
-    if (storage) {
-        return storage;
-    }
-    return getCookieStorage();
+    return getStorage() ?? getCookieStorage();
 }
 
 /**
- * Encrypts and stores a key-value pair in either `localStorage`, `sessionStorage`, or cookies.
- * Cookies are automatically used in SSR environments and can be explicitly requested.
- * Cookies include security options: Secure (HTTPS only), SameSite (CSRF protection), and encryption.
+ * Encrypts and stores a value in the requested storage.
+ *
+ * | location  | where it goes               | persistence         |
+ * |-----------|----------------------------|---------------------|
+ * | 'cookie'  | document.cookie            | expires option      |
+ * | 'local'   | localStorage               | until explicitly cleared |
+ * | 'any'     | localStorage               | until explicitly cleared |
+ * | 'session' | sessionStorage             | until tab closes    |
  *
- * @param {string} key - The key for the storage item.
- * @param {string} value - The string value to encrypt and store.
- * @param {string} secretKey - The secret key to use for encryption.
- * @param {LocationPreference} location - The storage location: 'local' for `localStorage`, 'session' for `sessionStorage`, 'cookie' for cookies, or 'any' for retrieval.
- * @param {CookieOptions} [cookieOptions] - Optional cookie-specific options (only used when location is 'cookie').
- * @returns {Promise<void>} A promise that resolves when the item has been stored.
+ * Note: 'any' stores in localStorage (same as 'local') for maximum
+ * persistence. Previously it stored in sessionStorage — that was a bug.
+ *
+ * In SSR environments cookies are always used regardless of location
+ * (localStorage / sessionStorage do not exist on the server).
  */
 async function storeEncryptedItem(key, value, secretKey, location, cookieOptions) {
     const encryptedValue = await encrypt(value, secretKey);
-    if (location === "cookie" || isServer) {
+    if (location === 'cookie' || isServer) {
         const cookieStorage = getCookieStorage();
         const defaultCookieOptions = {
             expires: location === 'local' || isServer ? 365 : undefined,
@@ -237,58 +235,85 @@ async function storeEncryptedItem(key, value, secretKey, location, cookieOptions
         cookieStorage.setItem(key, encryptedValue, defaultCookieOptions);
         return;
     }
-    const storage = location === "local" ? getStorage() : getSessionStorage();
+    // 'local' and 'any' → localStorage (persistent)
+    // 'session'         → sessionStorage (tab-scoped)
+    const storage = location === 'local' || location === 'any' ? getStorage() : getSessionStorage();
     if (storage) {
         storage.setItem(key, encryptedValue);
     }
 }
 /**
- * Retrieves and decrypts an item from `localStorage`, `sessionStorage`, or cookies.
- * When location is 'any', checks in order: sessionStorage, localStorage, cookies.
- * Cookies are automatically checked in SSR environments.
+ * Retrieves and decrypts a value from storage.
+ *
+ * Search order by location:
+ *
+ * | location  | search order                              |
+ * |-----------|-------------------------------------------|
+ * | 'cookie'  | cookies only                              |
+ * | 'local'   | localStorage only                         |
+ * | 'session' | sessionStorage only                       |
+ * | 'any'     | sessionStorage → localStorage → cookies   |
  *
- * @param {string} key - The key of the item to retrieve.
- * @param {string} secretKey - The secret key to use for decryption.
- * @param {LocationPreference} location - The storage location to search: 'local', 'session', 'cookie', or 'any' (checks session, local, cookie in that order).
- * @returns {Promise<string | null>} A promise that resolves with the decrypted value, or `null` if the item is not found or decryption fails.
+ * In SSR, cookies are always checked first (localStorage / sessionStorage
+ * are not available on the server).
+ *
+ * Returns null if the key is not found or decryption fails.
  */
 async function getDecryptedItem(key, secretKey, location) {
     let encryptedData = null;
-    if (location === "cookie" || isServer) {
+    // ── cookies ─────────────────────────────────────────────────────────────
+    if (location === 'cookie' || isServer) {
         const cookieStorage = getCookieStorage();
         encryptedData = cookieStorage.getItem(key);
         if (encryptedData) {
             try {
                 return await decrypt(encryptedData, secretKey);
             }
-            catch (error) {
+            catch {
                 return null;
             }
         }
-        if (location === "cookie") {
+        // Explicit 'cookie' location stops here — don't fall through
+        if (location === 'cookie')
             return null;
+    }
+    // ── sessionStorage ───────────────────────────────────────────────────────
+    if (location === 'session' || location === 'any') {
+        const ss = getSessionStorage();
+        encryptedData = ss?.getItem(key) ?? null;
+        if (encryptedData) {
+            try {
+                return await decrypt(encryptedData, secretKey);
+            }
+            catch {
+                return null;
+            }
         }
     }
-    if (location === "session" || location === "any") {
-        const sessionStorage = getSessionStorage();
-        encryptedData = sessionStorage?.getItem(key) || null;
+    // ── localStorage ─────────────────────────────────────────────────────────
+    if (location === 'local' || location === 'any') {
+        const ls = getStorage();
+        encryptedData = ls?.getItem(key) ?? null;
         if (encryptedData) {
             try {
                 return await decrypt(encryptedData, secretKey);
             }
-            catch (error) {
+            catch {
                 return null;
             }
         }
     }
-    if (location === "local" || location === "any") {
-        const storage = getStorage();
-        encryptedData = storage?.getItem(key) || null;
+    // ── cookies fallback for 'any' on client ─────────────────────────────────
+    // Checked last so that localStorage/sessionStorage take precedence,
+    // but cookies stored explicitly with location='cookie' are still found.
+    if (location === 'any' && !isServer) {
+        const cookieStorage = getCookieStorage();
+        encryptedData = cookieStorage.getItem(key);
         if (encryptedData) {
             try {
                 return await decrypt(encryptedData, secretKey);
             }
-            catch (error) {
+            catch {
                 return null;
             }
         }
@@ -1246,115 +1271,115 @@ function getRefreshTokenPathsConfig() {
     return refreshTokenPathsConfig;
 }
 
+let callbacksConfig = {};
+/**
+ * Configures the lifecycle callbacks for auth events.
+ * @param {CallbacksConfig} config - Callbacks to invoke on refresh failure or logout.
+ */
+const configCallbacks = (config) => {
+    callbacksConfig = { ...config };
+};
 /**
- * Removes all stored authentication credentials (access and refresh tokens) from the specified storage locations.
+ * Returns the configured lifecycle callbacks.
+ * @returns {CallbacksConfig}
+ */
+const getCallbacksConfig = () => callbacksConfig;
+
+/**
+ * Removes all stored authentication credentials (access + refresh tokens)
+ * from the specified storage location(s).
  *
- * @param {LocationPreference} location - The storage location to clear. Can be 'local' for `localStorage`,
- *   'session' for `sessionStorage`, 'cookie' for cookies, or 'any' to clear all.
- * @returns {Promise<void>} A promise that resolves when the credentials have been cleared.
+ * With location='any', ALL storage locations are cleared — including cookies.
+ * This prevents orphaned tokens surviving a logout.
  */
 const cleanCredentials = async (location) => {
     const tokensConfig = getTokenConfig();
-    if (location === "cookie" || isServer) {
+    const keys = Object.keys(tokensConfig);
+    const tokenItemKeys = keys.map((k) => tokensConfig[k]);
+    const removeCookies = () => {
         const cookieStorage = getCookieStorage();
-        Object.keys(tokensConfig).forEach((key) => {
-            cookieStorage.removeItem(tokensConfig[key], { path: '/' });
-        });
-        if (location === "cookie") {
-            return;
-        }
+        tokenItemKeys.forEach((itemKey) => cookieStorage.removeItem(itemKey, { path: '/' }));
+    };
+    const removeFromStorage = (storage) => {
+        tokenItemKeys.forEach((itemKey) => storage?.removeItem(itemKey));
+    };
+    if (location === 'cookie') {
+        removeCookies();
+        return;
+    }
+    if (isServer) {
+        removeCookies();
+        return;
+    }
+    // Client — clear every requested location
+    if (location === 'local' || location === 'any') {
+        removeFromStorage(getStorage());
+    }
+    if (location === 'session' || location === 'any') {
+        removeFromStorage(getSessionStorage());
+    }
+    // 'any' also clears cookies so that tokens stored explicitly with
+    // location='cookie' don't survive a logout
+    if (location === 'any') {
+        removeCookies();
     }
-    Object.keys(tokensConfig).forEach((key) => {
-        const itemKey = tokensConfig[key];
-        if (location === "local" || location === "any") {
-            const storage = getStorage();
-            storage?.removeItem(itemKey);
-        }
-        if (location === "session" || location === "any") {
-            const sessionStorage = getSessionStorage();
-            sessionStorage?.removeItem(itemKey);
-        }
-    });
 };
 /**
  * Retrieves and decrypts the access token from the specified storage location.
- *
- * @param {string} secretKey - The secret key to use for decryption.
- * @param {LocationPreference} location - The storage location to search ('local', 'session', 'cookie', or 'any').
- * @returns {Promise<string | null>} A promise that resolves with the decrypted access token, or `null` if it's not found.
  */
 const getAuthToken = async (secretKey, location) => {
     const tokensConfig = getTokenConfig();
-    return await getDecryptedItem(tokensConfig.ACCESS_TOKEN, secretKey, location);
+    return getDecryptedItem(tokensConfig.ACCESS_TOKEN, secretKey, location);
 };
 /**
  * Retrieves and decrypts the refresh token from the specified storage location.
- *
- * @param {string} secretKey - The secret key to use for decryption.
- * @param {LocationPreference} location - The storage location to search ('local', 'session', 'cookie', or 'any').
- * @returns {Promise<string | null>} A promise that resolves with the decrypted refresh token, or `null` if it's not found.
  */
 const getAuthRefreshToken = async (secretKey, location) => {
     const tokensConfig = getTokenConfig();
-    return await getDecryptedItem(tokensConfig.REFRESH_TOKEN, secretKey, location);
+    return getDecryptedItem(tokensConfig.REFRESH_TOKEN, secretKey, location);
 };
 /**
- * Encrypts and stores the access token in the specified storage location.
- *
- * @param {string} token - The access token to store.
- * @param {string} secretKey - The secret key to use for encryption.
- * @param {LocationPreference} location - The storage location ('local', 'session', or 'cookie').
- * @returns {Promise<void>} A promise that resolves when the token has been stored.
+ * Encrypts and stores the access token.
  */
 const storeAuthToken = async (token, secretKey, location) => {
     const tokensConfig = getTokenConfig();
     await storeEncryptedItem(tokensConfig.ACCESS_TOKEN, token, secretKey, location);
 };
 /**
- * Encrypts and stores the refresh token in the specified storage location.
- *
- * @param {string} token - The refresh token to store.
- * @param {string} secretKey - The secret key to use for encryption.
- * @param {LocationPreference} location - The storage location ('local', 'session', or 'cookie').
- * @returns {Promise<void>} A promise that resolves when the token has been stored.
+ * Encrypts and stores the refresh token.
  */
 const storeAuthRefreshToken = async (token, secretKey, location) => {
     const tokensConfig = getTokenConfig();
     await storeEncryptedItem(tokensConfig.REFRESH_TOKEN, token, secretKey, location);
 };
 /**
- * Verifies the current user's authentication status by checking for a valid, unexpired access token.
- * It searches for the token in all storage locations (sessionStorage, localStorage, cookies).
- * If the token is missing, malformed, or expired, it logs the issue, clears credentials, and returns `false`.
+ * Verifies the current user's authentication status by checking for a
+ * valid, unexpired access token across all storage locations.
  *
- * @returns {Promise<boolean>} A promise that resolves to `true` if the user is authenticated, and `false` otherwise.
+ * Returns false (without throwing) if the token is missing, malformed, or expired.
  */
 const verifyAuth = async () => {
-    const sessionPersistence = 'any';
-    const handleAuthError = async (message, shouldClean = true) => {
-        handleError(message);
-        if (shouldClean) {
-            await cleanCredentials(sessionPersistence);
-        }
+    const token = await getAuthToken(getAppKey(), 'any');
+    if (!token)
         return false;
-    };
-    const token = await getAuthToken(getAppKey(), sessionPersistence);
-    if (!token) {
-        return handleAuthError("TOKEN_MISSING: No valid token found");
-    }
     try {
         const decoded = jwtDecode(token);
         const currentTime = Date.now() / 1000;
-        if (typeof decoded.exp !== "number") {
-            return handleAuthError("TOKEN_INVALID: Invalid expiration format");
+        if (typeof decoded.exp !== 'number') {
+            handleError('TOKEN_INVALID: Invalid expiration format');
+            await cleanCredentials('any');
+            return false;
         }
         if (decoded.exp <= currentTime) {
-            return handleAuthError("TOKEN_EXPIRED: Token is expired");
+            handleError('TOKEN_EXPIRED: Token is expired');
+            return false;
         }
         return true;
     }
-    catch (error) {
-        return handleAuthError("TOKEN_INVALID: Invalid token format");
+    catch {
+        handleError('TOKEN_INVALID: Could not decode token');
+        await cleanCredentials('any');
+        return false;
     }
 };
 
@@ -1744,38 +1769,49 @@ function getDefaultAuthFetcher() {
 }
 
 /**
- * Refreshes the access and refresh tokens by making a POST request to the refresh endpoint.
- * It retrieves the current refresh token from storage, sends it to the refresh endpoint,
- * and then stores the new tokens upon a successful response. If the refresh process fails
- * or no refresh token is found, it clears all credentials and reloads the page.
+ * Refreshes the access and refresh tokens.
+ *
+ * Fixes over the original:
+ *   1. Uses `persistence` (the location where tokens were originally stored)
+ *      instead of hardcoding `"any"` — so cookies / localStorage / sessionStorage
+ *      are searched in the right place.
+ *   2. Sends the refresh token in the request body using the configured
+ *      `refreshTokenPaths.refreshTokenPath` as the body key, so the backend
+ *      always receives it regardless of withCredentials or cookie settings.
  *
- * @param {Fetcher} [fetcher] - Optional fetcher function to use for the refresh request. If not provided, uses the default configured fetcher.
- * @returns {Promise<AuthResponse>} A promise that resolves with the new authentication response containing the refreshed tokens.
- * @throws {Error} Throws an error if the refresh token is missing or if the refresh request fails, which is then caught to trigger a logout.
+ * On failure: clears credentials and calls `onRefreshFailed` callback.
  */
 const refreshTokens = async (fetcher) => {
     const tokenPaths = getRefreshTokenPathsConfig();
     const endpoints = getEndpointsConfig();
     const secretKey = getAppKey();
     const persistence = await getSessionPersistence();
-    const getFetcher = () => fetcher || getDefaultAuthFetcher();
+    const getFetcher = () => fetcher ?? getDefaultAuthFetcher();
     try {
-        const refreshTokenFromStorage = await getAuthRefreshToken(secretKey, "any");
-        if (!refreshTokenFromStorage) {
-            throw new Error("TOKEN_MISSING: No refresh token found in storage.");
+        // Use persistence (not hardcoded "any") — tokens live where they were stored
+        const refreshToken = await getAuthRefreshToken(secretKey, persistence);
+        if (!refreshToken) {
+            throw new Error('TOKEN_MISSING: No refresh token found in storage.');
         }
+        // Send refresh token in the request body using the configured path key
+        const refreshBodyKey = tokenPaths.refreshTokenPath ?? 'refresh_token';
         const data = await getFetcher()({
             method: 'POST',
             url: endpoints.REFRESH,
+            data: { [refreshBodyKey]: refreshToken },
         });
-        const { accessToken, refreshToken } = extractAndValidateTokens(data, tokenPaths, "REFRESH");
-        await storeTokens(accessToken, refreshToken, persistence);
+        const { accessToken, refreshToken: newRefreshToken } = extractAndValidateTokens(data, tokenPaths, 'REFRESH');
+        await storeTokens(accessToken, newRefreshToken, persistence);
         return data;
     }
     catch (error) {
         handleError(error);
         await cleanCredentials(persistence);
-        if (typeof window !== 'undefined') {
+        const { onRefreshFailed } = getCallbacksConfig();
+        if (onRefreshFailed) {
+            onRefreshFailed();
+        }
+        else if (typeof window !== 'undefined') {
             window.location.reload();
         }
         throw error;
@@ -1822,12 +1858,6 @@ function createAxiosFetcher(axiosInstance) {
     };
 }
 
-/**
- * A service class that encapsulates a customizable Axios instance with built-in interceptors
- * for handling authentication, token refreshing, and request cancellation. It is designed to
- * streamline API communication by automatically attaching authorization headers and managing
- * token refresh logic for 401 Unauthorized responses.
- */
 class AxiosService {
     instance;
     cancelTokenSource;
@@ -1835,26 +1865,30 @@ class AxiosService {
     refreshTokenUrl;
     isRefreshing = false;
     failedQueue = [];
-    /**
-     * Creates an instance of AxiosService.
-     * @param {AxiosServiceOptions} options - Configuration options for the Axios instance, such as `baseURL`, `timeout`, and custom `headers`.
-     */
     constructor(options) {
         this.cancelTokenSource = axios.CancelToken.source();
         const endpointsConfig = getEndpointsConfig();
         this.refreshTokenUrl = endpointsConfig.REFRESH;
         this.instance = axios.create({
-            baseURL: options.baseURL ?? "",
+            baseURL: options.baseURL ?? '',
             timeout: options.timeout ?? 30000,
             headers: {
-                Accept: "application/json",
-                "Content-Type": "application/json",
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
                 ...options.headers,
             },
             withCredentials: options.withCredentials ?? false,
         });
-        this.initializeInterceptors();
+        if (options.setupAuthInterceptors !== false) {
+            this.initializeInterceptors();
+        }
     }
+    /**
+     * Resolves or rejects all queued promises waiting for a token refresh.
+     *
+     * Fix: if both error and token are null (edge case), the queue is still
+     * cleared to avoid permanently hanging promises.
+     */
     processQueue(error, token = null) {
         this.failedQueue.forEach((prom) => {
             if (error) {
@@ -1863,6 +1897,10 @@ class AxiosService {
             else if (token) {
                 prom.resolve(token);
             }
+            else {
+                // Neither error nor token — reject with a clear message rather than hanging
+                prom.reject(new Error('[arex-core] Token refresh completed but no token was produced.'));
+            }
         });
         this.failedQueue = [];
     }
@@ -1872,8 +1910,12 @@ class AxiosService {
         }
     }
     initializeInterceptors() {
+        // ── Request: attach Authorization using the session's storage location ──
         this.instance.interceptors.request.use(async (config) => {
-            const token = await getAuthToken(getAppKey(), "any");
+            // Use persistence preference (not hardcoded "any") so the token is
+            // found regardless of whether it was stored in cookies, localStorage, etc.
+            const persistence = await getSessionPersistence();
+            const token = await getAuthToken(getAppKey(), persistence);
             if (token) {
                 this.setAuthHeader(config, token);
             }
@@ -1884,23 +1926,25 @@ class AxiosService {
             handleError(error);
             return Promise.reject(error);
         });
+        // ── Response: handle 401 with token refresh ──────────────────────────
         this.instance.interceptors.response.use((response) => {
             this.activeRequests--;
             return response;
         }, async (error) => {
             this.activeRequests--;
+            // Do not attempt refresh in SSR — storage is unavailable
+            if (typeof window === 'undefined') {
+                return Promise.reject(error);
+            }
             const originalRequest = error.config;
             const isAuthError = axios.isAxiosError(error) && error.response?.status === 401;
             const isRefreshCall = originalRequest?.url === this.refreshTokenUrl;
             const isRetry = originalRequest?._retry === true;
-            if (!isAuthError || isRefreshCall || isRetry) {
-                handleError(error);
-                return Promise.reject(error);
-            }
-            if (!originalRequest) {
+            if (!isAuthError || isRefreshCall || isRetry || !originalRequest) {
                 handleError(error);
                 return Promise.reject(error);
             }
+            // Queue concurrent requests while a refresh is already in progress
             if (this.isRefreshing) {
                 return new Promise((resolve, reject) => {
                     this.failedQueue.push({ resolve, reject });
@@ -1909,25 +1953,22 @@ class AxiosService {
                     this.setAuthHeader(originalRequest, newToken);
                     return this.instance(originalRequest);
                 })
-                    .catch((err) => {
-                    return Promise.reject(err);
-                });
+                    .catch((err) => Promise.reject(err));
             }
             this.isRefreshing = true;
             originalRequest._retry = true;
             try {
                 const fetcher = createAxiosFetcher(this.instance);
                 await refreshTokens(fetcher);
-                const newToken = await getAuthToken(getAppKey(), "any");
-                if (newToken) {
-                    this.processQueue(null, newToken);
-                    this.setAuthHeader(originalRequest, newToken);
-                }
-                else {
-                    const refreshError = new Error("New token not found after refresh.");
+                const persistence = await getSessionPersistence();
+                const newToken = await getAuthToken(getAppKey(), persistence);
+                if (!newToken) {
+                    const refreshError = new Error('[arex-core] New token not found after refresh.');
                     this.processQueue(refreshError, null);
                     throw refreshError;
                 }
+                this.processQueue(null, newToken);
+                this.setAuthHeader(originalRequest, newToken);
                 this.isRefreshing = false;
                 return this.instance(originalRequest);
             }
@@ -1939,39 +1980,19 @@ class AxiosService {
             }
         });
     }
-    /**
-     * Returns the number of active (in-flight) requests.
-     * @returns {number} The number of active requests.
-     */
     getActiveRequests() {
         return this.activeRequests;
     }
-    /**
-     * Returns the underlying Axios instance.
-     * @returns {AxiosInstance} The Axios instance.
-     */
     getAxiosInstance() {
         return this.instance;
     }
-    /**
-     * Cancels all ongoing requests made by this Axios instance.
-     */
     cancelAllRequests() {
-        this.cancelTokenSource.cancel("Operation canceled by the user.");
+        this.cancelTokenSource.cancel('Operation canceled by the user.');
         this.cancelTokenSource = axios.CancelToken.source();
     }
-    /**
-     * Sets a default header for all subsequent requests.
-     * @param {string} key - The header key.
-     * @param {string} value - The header value.
-     */
     setHeader(key, value) {
         this.instance.defaults.headers.common[key] = value;
     }
-    /**
-     * Removes a default header.
-     * @param {string} key - The header key to remove.
-     */
     removeHeader(key) {
         delete this.instance.defaults.headers.common[key];
     }
@@ -4279,7 +4300,11 @@ function useAuth(fetcher) {
         }
         finally {
             await cleanCredentials(await getSessionPersistence());
-            if (typeof window !== 'undefined') {
+            const { onLogout } = getCallbacksConfig();
+            if (onLogout) {
+                onLogout();
+            }
+            else if (typeof window !== 'undefined') {
                 window.location.reload();
             }
         }
@@ -4406,9 +4431,14 @@ const ArexVueCore = {
             baseURL: options.axios.baseURL,
             headers: options.axios.headers,
             timeout: options.axios.timeout,
-            withCredentials: options.axios.withCredentials
+            withCredentials: options.axios.withCredentials,
+            setupAuthInterceptors: options.axios.setupAuthInterceptors,
+        });
+        configCallbacks({
+            onRefreshFailed: options.onRefreshFailed,
+            onLogout: options.onLogout,
         });
     },
 };
 
-export { AppTypes, ArchiveTypes, ArexVueCore, AudioTypes, AuthError, AxiosService, BaseError, ContentTypeEnum, DocumentTypes, ERROR_MESSAGES, ERROR_STYLES, ErrorEnum, ErrorMessages, ErrorStyles, ExceptionEnum, FontTypes, ImageTypes, KeyCodeEnum, NetworkError, OtherTypes, RestStd, ScreenBreakpoint, ScreenSize, ServerError, StorageKeyEnum, StorageTypeEnum, TextTypes, ValidationError, VideoTypes, ab2hex, addCustomKeyboardShortcut, addDays, addDoubleClickListener, addKeyListener, ageAtDate, axiosFetch, blobToFormData, bufferToBlob, calculateAge, cleanCredentials, clickOutside, compareObject, configAppKey, configAuthFetcher, configAxios, configEndpoints, configRefreshTokenPaths, configSession, configTokenKeys, configTokenPaths, copyToClipboard, countWords, createAxiosFetcher, createKeyMap, createOfetchFetcher, customShortcut, daysBetween, daysToNextBirthday, debounce, debounceAsync, debounceAsyncValidator, debounceAsyncWithImmediate, debounceLeading, debounceLeadingTrailing, debounceTrailing, decrypt, deepClone, deepEqual, deepMerge, detectKeyHold, disableCopy, disableF12Key, disableMouseButtons, disableRightClick, disableSpecificKeys, downloadBlob, enableMouseButtons, enableRightClick, enableSpecificKeys, encrypt, exportToCSV, exportToExcel, exportToJSON, exportToText, exportToXML, extractAndValidateTokens, filterObjectByKeys, flattenObject, formDataToObject, formatDate, generateRandomString, getAppKey, getAuthRefreshToken, getAuthToken, getConfiguredAxiosInstance, getCookieStorage, getDecryptedItem, getDefaultAuthFetcher, getEndOfMonth, getEndpointsConfig, getObjectDifferences, getObjectKeys, getPreferredStorage, getQueryParam, getRefreshTokenPathsConfig, getSessionConfig, getSessionId, getSessionPersistence, getSessionStorage, getStartOfMonth, getStorage, getTokenConfig, getTokenPathsConfig, handleError, hasNestedProperties, hex2ab, importKey, isClient, isEmptyObject, isLeapYear, isServer, isStrongPassword, isValidAge, isValidCreditCard, isValidDate, isValidEmail, isValidExpiryDate, isValidHexColor, isValidHexColorAlpha, isValidHexNumber, isValidIP, isValidPhoneNumber, isValidSSN, isValidTime, isValidURL, isValidUsername, isValidZIP, lowerFirst, objectToFormData, objectToFormDataEnhanced, objectToQueryString, openWindow, parseDate, proxyToPlainObject, readFileAsDataURL, readFileAsText, refreshTokens, registerKeyboardShortcuts, removeAccent, removeClickOutside, removeCustomKeyboardShortcut, removeCustomShortcuts, removeDoubleClickListener, removeEmptyProperties, removeKeyListeners, replaceAll, retryWithBackoff, reverseString, safeGet, screenMap, scrollToTop, setDefaultAuthFetcherFactory, simulateKeyPress, stopDetectingKeyHold, storeAuthRefreshToken, storeAuthToken, storeEncryptedItem, storeTokens, stringToBlob, subtractDays, throttle, toCamelCase, toKebabCase, toggleTabNavigation, truncateString, unregisterKeyboardShortcuts, upperFirst, useAuth, useBreakpoint, useFetch, useFilter, usePagination, useSorter, validateAlphanumeric, validateLetters, validateNumbers, verifyAuth };
+export { AppTypes, ArchiveTypes, ArexVueCore, AudioTypes, AuthError, AxiosService, BaseError, ContentTypeEnum, DocumentTypes, ERROR_MESSAGES, ERROR_STYLES, ErrorEnum, ErrorMessages, ErrorStyles, ExceptionEnum, FontTypes, ImageTypes, KeyCodeEnum, NetworkError, OtherTypes, RestStd, ScreenBreakpoint, ScreenSize, ServerError, StorageKeyEnum, StorageTypeEnum, TextTypes, ValidationError, VideoTypes, ab2hex, addCustomKeyboardShortcut, addDays, addDoubleClickListener, addKeyListener, ageAtDate, axiosFetch, blobToFormData, bufferToBlob, calculateAge, cleanCredentials, clickOutside, compareObject, configAppKey, configAuthFetcher, configAxios, configCallbacks, configEndpoints, configRefreshTokenPaths, configSession, configTokenKeys, configTokenPaths, copyToClipboard, countWords, createAxiosFetcher, createKeyMap, createOfetchFetcher, customShortcut, daysBetween, daysToNextBirthday, debounce, debounceAsync, debounceAsyncValidator, debounceAsyncWithImmediate, debounceLeading, debounceLeadingTrailing, debounceTrailing, decrypt, deepClone, deepEqual, deepMerge, detectKeyHold, disableCopy, disableF12Key, disableMouseButtons, disableRightClick, disableSpecificKeys, downloadBlob, enableMouseButtons, enableRightClick, enableSpecificKeys, encrypt, exportToCSV, exportToExcel, exportToJSON, exportToText, exportToXML, extractAndValidateTokens, filterObjectByKeys, flattenObject, formDataToObject, formatDate, generateRandomString, getAppKey, getAuthRefreshToken, getAuthToken, getCallbacksConfig, getConfiguredAxiosInstance, getCookieStorage, getDecryptedItem, getDefaultAuthFetcher, getEndOfMonth, getEndpointsConfig, getObjectDifferences, getObjectKeys, getPreferredStorage, getQueryParam, getRefreshTokenPathsConfig, getSessionConfig, getSessionId, getSessionPersistence, getSessionStorage, getStartOfMonth, getStorage, getTokenConfig, getTokenPathsConfig, handleError, hasNestedProperties, hex2ab, importKey, isClient, isEmptyObject, isLeapYear, isServer, isStrongPassword, isValidAge, isValidCreditCard, isValidDate, isValidEmail, isValidExpiryDate, isValidHexColor, isValidHexColorAlpha, isValidHexNumber, isValidIP, isValidPhoneNumber, isValidSSN, isValidTime, isValidURL, isValidUsername, isValidZIP, lowerFirst, objectToFormData, objectToFormDataEnhanced, objectToQueryString, openWindow, parseDate, proxyToPlainObject, readFileAsDataURL, readFileAsText, refreshTokens, registerKeyboardShortcuts, removeAccent, removeClickOutside, removeCustomKeyboardShortcut, removeCustomShortcuts, removeDoubleClickListener, removeEmptyProperties, removeKeyListeners, replaceAll, retryWithBackoff, reverseString, safeGet, screenMap, scrollToTop, setDefaultAuthFetcherFactory, simulateKeyPress, stopDetectingKeyHold, storeAuthRefreshToken, storeAuthToken, storeEncryptedItem, storeTokens, stringToBlob, subtractDays, throttle, toCamelCase, toKebabCase, toggleTabNavigation, truncateString, unregisterKeyboardShortcuts, upperFirst, useAuth, useBreakpoint, useFetch, useFilter, usePagination, useSorter, validateAlphanumeric, validateLetters, validateNumbers, verifyAuth };

package/dist/services/credentials.d.ts

@@ -1,51 +1,32 @@
-import { LocationPreference } from "@/types/SessionConfig";
+import { LocationPreference } from '@/types/SessionConfig';
 /**
- * Removes all stored authentication credentials (access and refresh tokens) from the specified storage locations.
+ * Removes all stored authentication credentials (access + refresh tokens)
+ * from the specified storage location(s).
  *
- * @param {LocationPreference} location - The storage location to clear. Can be 'local' for `localStorage`,
- *   'session' for `sessionStorage`, 'cookie' for cookies, or 'any' to clear all.
- * @returns {Promise<void>} A promise that resolves when the credentials have been cleared.
+ * With location='any', ALL storage locations are cleared — including cookies.
+ * This prevents orphaned tokens surviving a logout.
  */
 export declare const cleanCredentials: (location: LocationPreference) => Promise<void>;
 /**
  * Retrieves and decrypts the access token from the specified storage location.
- *
- * @param {string} secretKey - The secret key to use for decryption.
- * @param {LocationPreference} location - The storage location to search ('local', 'session', 'cookie', or 'any').
- * @returns {Promise<string | null>} A promise that resolves with the decrypted access token, or `null` if it's not found.
  */
 export declare const getAuthToken: (secretKey: string, location: LocationPreference) => Promise<string | null>;
 /**
  * Retrieves and decrypts the refresh token from the specified storage location.
- *
- * @param {string} secretKey - The secret key to use for decryption.
- * @param {LocationPreference} location - The storage location to search ('local', 'session', 'cookie', or 'any').
- * @returns {Promise<string | null>} A promise that resolves with the decrypted refresh token, or `null` if it's not found.
  */
 export declare const getAuthRefreshToken: (secretKey: string, location: LocationPreference) => Promise<string | null>;
 /**
- * Encrypts and stores the access token in the specified storage location.
- *
- * @param {string} token - The access token to store.
- * @param {string} secretKey - The secret key to use for encryption.
- * @param {LocationPreference} location - The storage location ('local', 'session', or 'cookie').
- * @returns {Promise<void>} A promise that resolves when the token has been stored.
+ * Encrypts and stores the access token.
  */
 export declare const storeAuthToken: (token: string, secretKey: string, location: LocationPreference) => Promise<void>;
 /**
- * Encrypts and stores the refresh token in the specified storage location.
- *
- * @param {string} token - The refresh token to store.
- * @param {string} secretKey - The secret key to use for encryption.
- * @param {LocationPreference} location - The storage location ('local', 'session', or 'cookie').
- * @returns {Promise<void>} A promise that resolves when the token has been stored.
+ * Encrypts and stores the refresh token.
  */
 export declare const storeAuthRefreshToken: (token: string, secretKey: string, location: LocationPreference) => Promise<void>;
 /**
- * Verifies the current user's authentication status by checking for a valid, unexpired access token.
- * It searches for the token in all storage locations (sessionStorage, localStorage, cookies).
- * If the token is missing, malformed, or expired, it logs the issue, clears credentials, and returns `false`.
+ * Verifies the current user's authentication status by checking for a
+ * valid, unexpired access token across all storage locations.
  *
- * @returns {Promise<boolean>} A promise that resolves to `true` if the user is authenticated, and `false` otherwise.
+ * Returns false (without throwing) if the token is missing, malformed, or expired.
  */
 export declare const verifyAuth: () => Promise<boolean>;

package/dist/services/refreshTokens.d.ts

@@ -1,12 +1,15 @@
-import { AuthResponse, Fetcher } from "@/types";
+import { AuthResponse, Fetcher } from '@/types';
 /**
- * Refreshes the access and refresh tokens by making a POST request to the refresh endpoint.
- * It retrieves the current refresh token from storage, sends it to the refresh endpoint,
- * and then stores the new tokens upon a successful response. If the refresh process fails
- * or no refresh token is found, it clears all credentials and reloads the page.
+ * Refreshes the access and refresh tokens.
  *
- * @param {Fetcher} [fetcher] - Optional fetcher function to use for the refresh request. If not provided, uses the default configured fetcher.
- * @returns {Promise<AuthResponse>} A promise that resolves with the new authentication response containing the refreshed tokens.
- * @throws {Error} Throws an error if the refresh token is missing or if the refresh request fails, which is then caught to trigger a logout.
+ * Fixes over the original:
+ *   1. Uses `persistence` (the location where tokens were originally stored)
+ *      instead of hardcoding `"any"` — so cookies / localStorage / sessionStorage
+ *      are searched in the right place.
+ *   2. Sends the refresh token in the request body using the configured
+ *      `refreshTokenPaths.refreshTokenPath` as the body key, so the backend
+ *      always receives it regardless of withCredentials or cookie settings.
+ *
+ * On failure: clears credentials and calls `onRefreshFailed` callback.
  */
 export declare const refreshTokens: (fetcher?: Fetcher) => Promise<AuthResponse>;

package/dist/types/ArexVueCoreOptions.d.ts

@@ -39,4 +39,14 @@ export interface ArexVueCoreOptions {
     };
     /** The configuration options for the underlying Axios instance. */
     axios: AxiosServiceOptions;
+    /**
+     * Called when a token refresh attempt fails (e.g., to redirect to login via Vue Router).
+     * Falls back to `window.location.reload()` if not provided.
+     */
+    onRefreshFailed?: () => void;
+    /**
+     * Called after a successful logout (e.g., to redirect to login via Vue Router).
+     * Falls back to `window.location.reload()` if not provided.
+     */
+    onLogout?: () => void;
 }

package/dist/types/AxiosServiceOptions.d.ts

@@ -12,4 +12,10 @@ export interface AxiosServiceOptions {
     timeout?: number;
     /** A boolean indicating whether cross-site Access-Control requests should be made using credentials. */
     withCredentials?: boolean;
+    /**
+     * Whether to mount the authentication interceptors (token attachment + 401 refresh).
+     * Set to `false` in SSR environments where browser storage is unavailable.
+     * Defaults to `true`.
+     */
+    setupAuthInterceptors?: boolean;
 }

package/dist/utils/encryption.d.ts

@@ -1,44 +1,24 @@
 /**
- * Converts an `ArrayBuffer` or `Uint8Array` into a hexadecimal string representation.
- *
- * @param {ArrayBuffer | Uint8Array} buffer - The buffer to convert.
- * @returns {string} The resulting hexadecimal string.
+ * Converts an `ArrayBuffer` or `Uint8Array` into a hexadecimal string.
  */
 export declare function ab2hex(buffer: ArrayBuffer | Uint8Array): string;
 /**
  * Converts a hexadecimal string into a `Uint8Array`.
- *
- * @param {string} hex - The hexadecimal string to convert.
- * @returns {Uint8Array} The resulting `Uint8Array`.
- * @throws {TypeError} If the input is not a string.
- * @throws {Error} If the hexadecimal string has an invalid format or an odd length.
  */
 export declare function hex2ab(hex: string): Uint8Array;
 /**
- * Derives a `CryptoKey` for AES-CBC encryption from a plain-text secret key.
- * It uses SHA-256 to hash the secret key, ensuring a fixed-length key suitable for the Web Crypto API.
+ * Derives a CryptoKey for AES-CBC-256 from a plain-text secret using SHA-256.
  *
- * @param {string} secretKey - The plain-text secret key.
- * @returns {Promise<CryptoKey>} A promise that resolves with the derived `CryptoKey`.
- * @throws {Error} If the `secretKey` is null or empty.
+ * @throws {Error} If secretKey is empty or Web Crypto API is unavailable.
  */
 export declare function importKey(secretKey: string): Promise<CryptoKey>;
 /**
- * Encrypts a plain-text value using AES-CBC with a given secret key.
- * A random 16-byte initialization vector (IV) is generated for each encryption.
- *
- * @param {string} value - The plain-text string to encrypt.
- * @param {string} secretKey - The secret key to use for encryption.
- * @returns {Promise<string>} A promise that resolves with a concatenated hexadecimal string of the IV and the ciphertext.
- * @throws {Error} If the `secretKey` is null or empty.
+ * Encrypts a plain-text string using AES-CBC-256.
+ * A unique 16-byte IV is generated per call.
+ * Output format: IV_hex (32 chars) + ciphertext_hex.
  */
 export declare function encrypt(value: string, secretKey: string): Promise<string>;
 /**
- * Decrypts a hexadecimal string (IV + ciphertext) using AES-CBC with a given secret key.
- *
- * @param {string} encryptedValue - The concatenated hexadecimal string of the IV and ciphertext.
- * @param {string} secretKey - The secret key to use for decryption.
- * @returns {Promise<string>} A promise that resolves with the decrypted plain-text string.
- * @throws {Error} If the encrypted value is null, empty, or too short, or if the `secretKey` is invalid.
+ * Decrypts a hex string (IV_hex + ciphertext_hex) produced by `encrypt()`.
  */
 export declare function decrypt(encryptedValue: string, secretKey: string): Promise<string>;

package/dist/utils/storage.d.ts

@@ -1,26 +1,37 @@
-import { LocationPreference } from "@/types";
-import { CookieOptions } from "./ssr";
+import { LocationPreference } from '@/types';
+import { CookieOptions } from './ssr';
 /**
- * Encrypts and stores a key-value pair in either `localStorage`, `sessionStorage`, or cookies.
- * Cookies are automatically used in SSR environments and can be explicitly requested.
- * Cookies include security options: Secure (HTTPS only), SameSite (CSRF protection), and encryption.
+ * Encrypts and stores a value in the requested storage.
  *
- * @param {string} key - The key for the storage item.
- * @param {string} value - The string value to encrypt and store.
- * @param {string} secretKey - The secret key to use for encryption.
- * @param {LocationPreference} location - The storage location: 'local' for `localStorage`, 'session' for `sessionStorage`, 'cookie' for cookies, or 'any' for retrieval.
- * @param {CookieOptions} [cookieOptions] - Optional cookie-specific options (only used when location is 'cookie').
- * @returns {Promise<void>} A promise that resolves when the item has been stored.
+ * | location  | where it goes               | persistence         |
+ * |-----------|----------------------------|---------------------|
+ * | 'cookie'  | document.cookie            | expires option      |
+ * | 'local'   | localStorage               | until explicitly cleared |
+ * | 'any'     | localStorage               | until explicitly cleared |
+ * | 'session' | sessionStorage             | until tab closes    |
+ *
+ * Note: 'any' stores in localStorage (same as 'local') for maximum
+ * persistence. Previously it stored in sessionStorage — that was a bug.
+ *
+ * In SSR environments cookies are always used regardless of location
+ * (localStorage / sessionStorage do not exist on the server).
  */
 export declare function storeEncryptedItem(key: string, value: string, secretKey: string, location: LocationPreference, cookieOptions?: CookieOptions): Promise<void>;
 /**
- * Retrieves and decrypts an item from `localStorage`, `sessionStorage`, or cookies.
- * When location is 'any', checks in order: sessionStorage, localStorage, cookies.
- * Cookies are automatically checked in SSR environments.
+ * Retrieves and decrypts a value from storage.
+ *
+ * Search order by location:
+ *
+ * | location  | search order                              |
+ * |-----------|-------------------------------------------|
+ * | 'cookie'  | cookies only                              |
+ * | 'local'   | localStorage only                         |
+ * | 'session' | sessionStorage only                       |
+ * | 'any'     | sessionStorage → localStorage → cookies   |
+ *
+ * In SSR, cookies are always checked first (localStorage / sessionStorage
+ * are not available on the server).
  *
- * @param {string} key - The key of the item to retrieve.
- * @param {string} secretKey - The secret key to use for decryption.
- * @param {LocationPreference} location - The storage location to search: 'local', 'session', 'cookie', or 'any' (checks session, local, cookie in that order).
- * @returns {Promise<string | null>} A promise that resolves with the decrypted value, or `null` if the item is not found or decryption fails.
+ * Returns null if the key is not found or decryption fails.
  */
 export declare function getDecryptedItem(key: string, secretKey: string, location: LocationPreference): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arex95/vue-core",
-  "version": "3.1.0",
+  "version": "5.0.0",
   "description": "Opinionated Vue Core",
   "main": "dist/index.js",
   "module": "dist/index.mjs",