@oxyhq/core 1.6.0 → 1.6.1

package/dist/cjs/AuthManager.js

@@ -300,6 +300,19 @@ class AuthManager {
             clearTimeout(this.refreshTimer);
             this.refreshTimer = null;
         }
+        // Invalidate current session on the server (best-effort)
+        try {
+            const sessionJson = await this.storage.getItem(STORAGE_KEYS.SESSION);
+            if (sessionJson) {
+                const session = JSON.parse(sessionJson);
+                if (session.sessionId && typeof this.oxyServices.logoutSession === 'function') {
+                    await this.oxyServices.logoutSession(session.sessionId);
+                }
+            }
+        }
+        catch {
+            // Best-effort: don't block local signout on network failure
+        }
         // Revoke FedCM credential if supported
         try {
             const services = this.oxyServices;

package/dist/cjs/index.js

@@ -30,7 +30,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.normalizeLanguageCode = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.SUPPORTED_LANGUAGES = exports.DeviceManager = exports.RecoveryPhraseService = exports.SignatureService = exports.KeyManager = exports.createCrossDomainAuth = exports.CrossDomainAuth = exports.createAuthManager = exports.AuthManager = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
-exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.packageInfo = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = void 0;
+exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.packageInfo = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // --- Core API Client ---
@@ -119,6 +119,14 @@ Object.defineProperty(exports, "createDebugLogger", { enumerable: true, get: fun
 // --- i18n ---
 var i18n_1 = require("./i18n");
 Object.defineProperty(exports, "translate", { enumerable: true, get: function () { return i18n_1.translate; } });
+// --- Auth Helpers ---
+var authHelpers_1 = require("./utils/authHelpers");
+Object.defineProperty(exports, "SessionSyncRequiredError", { enumerable: true, get: function () { return authHelpers_1.SessionSyncRequiredError; } });
+Object.defineProperty(exports, "AuthenticationFailedError", { enumerable: true, get: function () { return authHelpers_1.AuthenticationFailedError; } });
+Object.defineProperty(exports, "ensureValidToken", { enumerable: true, get: function () { return authHelpers_1.ensureValidToken; } });
+Object.defineProperty(exports, "isAuthenticationError", { enumerable: true, get: function () { return authHelpers_1.isAuthenticationError; } });
+Object.defineProperty(exports, "withAuthErrorHandling", { enumerable: true, get: function () { return authHelpers_1.withAuthErrorHandling; } });
+Object.defineProperty(exports, "authenticatedApiCall", { enumerable: true, get: function () { return authHelpers_1.authenticatedApiCall; } });
 // --- Session Utilities ---
 var sessionUtils_1 = require("./utils/sessionUtils");
 Object.defineProperty(exports, "mergeSessions", { enumerable: true, get: function () { return sessionUtils_1.mergeSessions; } });

package/dist/cjs/mixins/OxyServices.utility.js

@@ -67,6 +67,17 @@ function OxyServicesUtilityMixin(Base) {
          * Validates JWT tokens against the Oxy API and attaches user data to requests.
          * Uses server-side session validation for security (not just JWT decode).
          *
+         * **Design note — jwtDecode vs jwt.verify:**
+         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
+         * verification) for user tokens. This is by design, NOT a security gap:
+         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
+         * - Security comes from API-based session validation (`validateSession()`)
+         *   which checks the session server-side on every request
+         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
+         *   via the `jwtSecret` option, since they are stateless
+         * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+         *   direct access to `ACCESS_TOKEN_SECRET`
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';
@@ -119,6 +130,7 @@ function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'MISSING_TOKEN',
                             message: 'Access token required',
                             code: 'MISSING_TOKEN',
                             status: 401
@@ -139,6 +151,7 @@ function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'INVALID_TOKEN_FORMAT',
                             message: 'Invalid token format',
                             code: 'INVALID_TOKEN_FORMAT',
                             status: 401
@@ -158,6 +171,7 @@ function OxyServicesUtilityMixin(Base) {
                                 return next();
                             }
                             const error = {
+                                error: 'SERVICE_TOKEN_NOT_CONFIGURED',
                                 message: 'Service token verification not configured',
                                 code: 'SERVICE_TOKEN_NOT_CONFIGURED',
                                 status: 403
@@ -192,7 +206,7 @@ function OxyServicesUtilityMixin(Base) {
                                 (verifyError.message === 'Invalid signature' || verifyError.message === 'Invalid token structure');
                             if (!isSignatureError) {
                                 console.error('[oxy.auth] Unexpected error during service token verification:', verifyError);
-                                const error = { message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
+                                const error = { error: 'AUTH_INTERNAL_ERROR', message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
                                 if (onError)
                                     return onError(error);
                                 return res.status(500).json(error);
@@ -202,7 +216,7 @@ function OxyServicesUtilityMixin(Base) {
                                 req.user = null;
                                 return next();
                             }
-                            const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
@@ -214,7 +228,7 @@ function OxyServicesUtilityMixin(Base) {
                                 req.user = null;
                                 return next();
                             }
-                            const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+                            const error = { error: 'TOKEN_EXPIRED', message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
@@ -226,7 +240,7 @@ function OxyServicesUtilityMixin(Base) {
                                 req.user = null;
                                 return next();
                             }
-                            const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
@@ -253,6 +267,7 @@ function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'INVALID_TOKEN_PAYLOAD',
                             message: 'Token missing user ID',
                             code: 'INVALID_TOKEN_PAYLOAD',
                             status: 401
@@ -269,6 +284,7 @@ function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'TOKEN_EXPIRED',
                             message: 'Token expired',
                             code: 'TOKEN_EXPIRED',
                             status: 401
@@ -291,6 +307,7 @@ function OxyServicesUtilityMixin(Base) {
                                     return next();
                                 }
                                 const error = {
+                                    error: 'INVALID_SESSION',
                                     message: 'Session invalid or expired',
                                     code: 'INVALID_SESSION',
                                     status: 401
@@ -325,6 +342,7 @@ function OxyServicesUtilityMixin(Base) {
                                 return next();
                             }
                             const error = {
+                                error: 'SESSION_VALIDATION_ERROR',
                                 message: 'Session validation failed',
                                 code: 'SESSION_VALIDATION_ERROR',
                                 status: 401
@@ -382,6 +400,8 @@ function OxyServicesUtilityMixin(Base) {
          * Returns a middleware function for Socket.IO that validates JWT tokens
          * from the handshake auth object and attaches user data to the socket.
          *
+         * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';

package/dist/cjs/utils/authHelpers.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationFailedError = exports.SessionSyncRequiredError = void 0;
+exports.ensureValidToken = ensureValidToken;
+exports.isAuthenticationError = isAuthenticationError;
+exports.withAuthErrorHandling = withAuthErrorHandling;
+exports.authenticatedApiCall = authenticatedApiCall;
+/**
+ * Error thrown when session sync is required
+ */
+class SessionSyncRequiredError extends Error {
+    constructor(message = 'Session needs to be synced. Please try again.') {
+        super(message);
+        this.name = 'SessionSyncRequiredError';
+    }
+}
+exports.SessionSyncRequiredError = SessionSyncRequiredError;
+/**
+ * Error thrown when authentication fails
+ */
+class AuthenticationFailedError extends Error {
+    constructor(message = 'Authentication failed. Please sign in again.') {
+        super(message);
+        this.name = 'AuthenticationFailedError';
+    }
+}
+exports.AuthenticationFailedError = AuthenticationFailedError;
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+async function ensureValidToken(oxyServices, activeSessionId) {
+    if (oxyServices.hasValidToken() || !activeSessionId) {
+        return;
+    }
+    try {
+        await oxyServices.getTokenBySession(activeSessionId);
+    }
+    catch (tokenError) {
+        const errorMessage = tokenError instanceof Error ? tokenError.message : String(tokenError);
+        if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+            throw new SessionSyncRequiredError();
+        }
+        throw tokenError;
+    }
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+function isAuthenticationError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const errorObj = error;
+    const errorMessage = errorObj.message || '';
+    const status = errorObj.status || errorObj.response?.status;
+    return (status === 401 ||
+        errorMessage.includes('Authentication required') ||
+        errorMessage.includes('Invalid or missing authorization header'));
+}
+/**
+ * Wraps an API call with authentication error handling.
+ * On auth failure, optionally attempts to sync the session and retry.
+ *
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ */
+async function withAuthErrorHandling(apiCall, options) {
+    try {
+        return await apiCall();
+    }
+    catch (error) {
+        if (!isAuthenticationError(error)) {
+            throw error;
+        }
+        if (options?.syncSession && options?.activeSessionId && options?.oxyServices) {
+            try {
+                await options.syncSession();
+                await options.oxyServices.getTokenBySession(options.activeSessionId);
+                return await apiCall();
+            }
+            catch {
+                throw new AuthenticationFailedError();
+            }
+        }
+        throw new AuthenticationFailedError();
+    }
+}
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+async function authenticatedApiCall(oxyServices, activeSessionId, apiCall, syncSession) {
+    await ensureValidToken(oxyServices, activeSessionId);
+    return withAuthErrorHandling(apiCall, {
+        syncSession,
+        activeSessionId,
+        oxyServices,
+    });
+}

package/dist/esm/AuthManager.js

@@ -296,6 +296,19 @@ export class AuthManager {
             clearTimeout(this.refreshTimer);
             this.refreshTimer = null;
         }
+        // Invalidate current session on the server (best-effort)
+        try {
+            const sessionJson = await this.storage.getItem(STORAGE_KEYS.SESSION);
+            if (sessionJson) {
+                const session = JSON.parse(sessionJson);
+                if (session.sessionId && typeof this.oxyServices.logoutSession === 'function') {
+                    await this.oxyServices.logoutSession(session.sessionId);
+                }
+            }
+        }
+        catch {
+            // Best-effort: don't block local signout on network failure
+        }
         // Revoke FedCM credential if supported
         try {
             const services = this.oxyServices;

package/dist/esm/index.js

@@ -40,6 +40,8 @@ export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBac
 export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './shared/utils/debugUtils';
 // --- i18n ---
 export { translate } from './i18n';
+// --- Auth Helpers ---
+export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 // --- Session Utilities ---
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from './utils/sessionUtils';
 // --- Constants ---

package/dist/esm/mixins/OxyServices.utility.js

@@ -31,6 +31,17 @@ export function OxyServicesUtilityMixin(Base) {
          * Validates JWT tokens against the Oxy API and attaches user data to requests.
          * Uses server-side session validation for security (not just JWT decode).
          *
+         * **Design note — jwtDecode vs jwt.verify:**
+         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
+         * verification) for user tokens. This is by design, NOT a security gap:
+         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
+         * - Security comes from API-based session validation (`validateSession()`)
+         *   which checks the session server-side on every request
+         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
+         *   via the `jwtSecret` option, since they are stateless
+         * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+         *   direct access to `ACCESS_TOKEN_SECRET`
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';
@@ -83,6 +94,7 @@ export function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'MISSING_TOKEN',
                             message: 'Access token required',
                             code: 'MISSING_TOKEN',
                             status: 401
@@ -103,6 +115,7 @@ export function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'INVALID_TOKEN_FORMAT',
                             message: 'Invalid token format',
                             code: 'INVALID_TOKEN_FORMAT',
                             status: 401
@@ -122,6 +135,7 @@ export function OxyServicesUtilityMixin(Base) {
                                 return next();
                             }
                             const error = {
+                                error: 'SERVICE_TOKEN_NOT_CONFIGURED',
                                 message: 'Service token verification not configured',
                                 code: 'SERVICE_TOKEN_NOT_CONFIGURED',
                                 status: 403
@@ -156,7 +170,7 @@ export function OxyServicesUtilityMixin(Base) {
                                 (verifyError.message === 'Invalid signature' || verifyError.message === 'Invalid token structure');
                             if (!isSignatureError) {
                                 console.error('[oxy.auth] Unexpected error during service token verification:', verifyError);
-                                const error = { message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
+                                const error = { error: 'AUTH_INTERNAL_ERROR', message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
                                 if (onError)
                                     return onError(error);
                                 return res.status(500).json(error);
@@ -166,7 +180,7 @@ export function OxyServicesUtilityMixin(Base) {
                                 req.user = null;
                                 return next();
                             }
-                            const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
@@ -178,7 +192,7 @@ export function OxyServicesUtilityMixin(Base) {
                                 req.user = null;
                                 return next();
                             }
-                            const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+                            const error = { error: 'TOKEN_EXPIRED', message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
@@ -190,7 +204,7 @@ export function OxyServicesUtilityMixin(Base) {
                                 req.user = null;
                                 return next();
                             }
-                            const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
@@ -217,6 +231,7 @@ export function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'INVALID_TOKEN_PAYLOAD',
                             message: 'Token missing user ID',
                             code: 'INVALID_TOKEN_PAYLOAD',
                             status: 401
@@ -233,6 +248,7 @@ export function OxyServicesUtilityMixin(Base) {
                             return next();
                         }
                         const error = {
+                            error: 'TOKEN_EXPIRED',
                             message: 'Token expired',
                             code: 'TOKEN_EXPIRED',
                             status: 401
@@ -255,6 +271,7 @@ export function OxyServicesUtilityMixin(Base) {
                                     return next();
                                 }
                                 const error = {
+                                    error: 'INVALID_SESSION',
                                     message: 'Session invalid or expired',
                                     code: 'INVALID_SESSION',
                                     status: 401
@@ -289,6 +306,7 @@ export function OxyServicesUtilityMixin(Base) {
                                 return next();
                             }
                             const error = {
+                                error: 'SESSION_VALIDATION_ERROR',
                                 message: 'Session validation failed',
                                 code: 'SESSION_VALIDATION_ERROR',
                                 status: 401
@@ -346,6 +364,8 @@ export function OxyServicesUtilityMixin(Base) {
          * Returns a middleware function for Socket.IO that validates JWT tokens
          * from the handshake auth object and attaches user data to the socket.
          *
+         * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';

package/dist/esm/utils/authHelpers.js

@@ -0,0 +1,105 @@
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+/**
+ * Error thrown when session sync is required
+ */
+export class SessionSyncRequiredError extends Error {
+    constructor(message = 'Session needs to be synced. Please try again.') {
+        super(message);
+        this.name = 'SessionSyncRequiredError';
+    }
+}
+/**
+ * Error thrown when authentication fails
+ */
+export class AuthenticationFailedError extends Error {
+    constructor(message = 'Authentication failed. Please sign in again.') {
+        super(message);
+        this.name = 'AuthenticationFailedError';
+    }
+}
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+export async function ensureValidToken(oxyServices, activeSessionId) {
+    if (oxyServices.hasValidToken() || !activeSessionId) {
+        return;
+    }
+    try {
+        await oxyServices.getTokenBySession(activeSessionId);
+    }
+    catch (tokenError) {
+        const errorMessage = tokenError instanceof Error ? tokenError.message : String(tokenError);
+        if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+            throw new SessionSyncRequiredError();
+        }
+        throw tokenError;
+    }
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+export function isAuthenticationError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const errorObj = error;
+    const errorMessage = errorObj.message || '';
+    const status = errorObj.status || errorObj.response?.status;
+    return (status === 401 ||
+        errorMessage.includes('Authentication required') ||
+        errorMessage.includes('Invalid or missing authorization header'));
+}
+/**
+ * Wraps an API call with authentication error handling.
+ * On auth failure, optionally attempts to sync the session and retry.
+ *
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ */
+export async function withAuthErrorHandling(apiCall, options) {
+    try {
+        return await apiCall();
+    }
+    catch (error) {
+        if (!isAuthenticationError(error)) {
+            throw error;
+        }
+        if (options?.syncSession && options?.activeSessionId && options?.oxyServices) {
+            try {
+                await options.syncSession();
+                await options.oxyServices.getTokenBySession(options.activeSessionId);
+                return await apiCall();
+            }
+            catch {
+                throw new AuthenticationFailedError();
+            }
+        }
+        throw new AuthenticationFailedError();
+    }
+}
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export async function authenticatedApiCall(oxyServices, activeSessionId, apiCall, syncSession) {
+    await ensureValidToken(oxyServices, activeSessionId);
+    return withAuthErrorHandling(apiCall, {
+        syncSession,
+        activeSessionId,
+        oxyServices,
+    });
+}

package/dist/types/index.d.ts

@@ -43,6 +43,8 @@ export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBac
 export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/networkUtils';
 export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './shared/utils/debugUtils';
 export { translate } from './i18n';
+export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
+export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from './utils/sessionUtils';
 export { packageInfo } from './constants/version';
 export * from './utils/apiUtils';

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -43,6 +43,17 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Validates JWT tokens against the Oxy API and attaches user data to requests.
          * Uses server-side session validation for security (not just JWT decode).
          *
+         * **Design note — jwtDecode vs jwt.verify:**
+         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
+         * verification) for user tokens. This is by design, NOT a security gap:
+         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
+         * - Security comes from API-based session validation (`validateSession()`)
+         *   which checks the session server-side on every request
+         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
+         *   via the `jwtSecret` option, since they are stateless
+         * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+         *   direct access to `ACCESS_TOKEN_SECRET`
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';
@@ -74,6 +85,8 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Returns a middleware function for Socket.IO that validates JWT tokens
          * from the handshake auth object and attaches user data to the socket.
          *
+         * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';

package/dist/types/utils/authHelpers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+import type { OxyServices } from '../OxyServices';
+/**
+ * Error thrown when session sync is required
+ */
+export declare class SessionSyncRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when authentication fails
+ */
+export declare class AuthenticationFailedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+export declare function ensureValidToken(oxyServices: OxyServices, activeSessionId: string | null | undefined): Promise<void>;
+/**
+ * Options for handling API authentication errors
+ */
+export interface HandleApiErrorOptions {
+    syncSession?: () => Promise<unknown>;
+    activeSessionId?: string | null;
+    oxyServices?: OxyServices;
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+export declare function isAuthenticationError(error: unknown): boolean;
+/**
+ * Wraps an API call with authentication error handling.
+ * On auth failure, optionally attempts to sync the session and retry.
+ *
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ */
+export declare function withAuthErrorHandling<T>(apiCall: () => Promise<T>, options?: HandleApiErrorOptions): Promise<T>;
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export declare function authenticatedApiCall<T>(oxyServices: OxyServices, activeSessionId: string | null | undefined, apiCall: () => Promise<T>, syncSession?: () => Promise<unknown>): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/AuthManager.ts

@@ -366,6 +366,19 @@ export class AuthManager {
       this.refreshTimer = null;
     }
 
+    // Invalidate current session on the server (best-effort)
+    try {
+      const sessionJson = await this.storage.getItem(STORAGE_KEYS.SESSION);
+      if (sessionJson) {
+        const session = JSON.parse(sessionJson);
+        if (session.sessionId && typeof (this.oxyServices as any).logoutSession === 'function') {
+          await (this.oxyServices as any).logoutSession(session.sessionId);
+        }
+      }
+    } catch {
+      // Best-effort: don't block local signout on network failure
+    }
+
     // Revoke FedCM credential if supported
     try {
       const services = this.oxyServices as OxyServicesWithFedCM;

package/src/index.ts

@@ -123,6 +123,17 @@ export {
 // --- i18n ---
 export { translate } from './i18n';
 
+// --- Auth Helpers ---
+export {
+  SessionSyncRequiredError,
+  AuthenticationFailedError,
+  ensureValidToken,
+  isAuthenticationError,
+  withAuthErrorHandling,
+  authenticatedApiCall,
+} from './utils/authHelpers';
+export type { HandleApiErrorOptions } from './utils/authHelpers';
+
 // --- Session Utilities ---
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from './utils/sessionUtils';
 

package/src/mixins/OxyServices.utility.ts

@@ -83,6 +83,17 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * Validates JWT tokens against the Oxy API and attaches user data to requests.
      * Uses server-side session validation for security (not just JWT decode).
      *
+     * **Design note — jwtDecode vs jwt.verify:**
+     * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
+     * verification) for user tokens. This is by design, NOT a security gap:
+     * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
+     * - Security comes from API-based session validation (`validateSession()`)
+     *   which checks the session server-side on every request
+     * - Service tokens (type: 'service') DO use cryptographic HMAC verification
+     *   via the `jwtSecret` option, since they are stateless
+     * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+     *   direct access to `ACCESS_TOKEN_SECRET`
+     *
      * @example
      * ```typescript
      * import { OxyServices } from '@oxyhq/core';
@@ -138,6 +149,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'MISSING_TOKEN',
               message: 'Access token required',
               code: 'MISSING_TOKEN',
               status: 401
@@ -158,6 +170,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'INVALID_TOKEN_FORMAT',
               message: 'Invalid token format',
               code: 'INVALID_TOKEN_FORMAT',
               status: 401
@@ -177,6 +190,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 return next();
               }
               const error = {
+                error: 'SERVICE_TOKEN_NOT_CONFIGURED',
                 message: 'Service token verification not configured',
                 code: 'SERVICE_TOKEN_NOT_CONFIGURED',
                 status: 403
@@ -212,7 +226,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
 
               if (!isSignatureError) {
                 console.error('[oxy.auth] Unexpected error during service token verification:', verifyError);
-                const error = { message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
+                const error = { error: 'AUTH_INTERNAL_ERROR', message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
                 if (onError) return onError(error);
                 return res.status(500).json(error);
               }
@@ -222,7 +236,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 req.user = null;
                 return next();
               }
-              const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -234,7 +248,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 req.user = null;
                 return next();
               }
-              const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+              const error = { error: 'TOKEN_EXPIRED', message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -246,7 +260,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 req.user = null;
                 return next();
               }
-              const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -278,6 +292,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'INVALID_TOKEN_PAYLOAD',
               message: 'Token missing user ID',
               code: 'INVALID_TOKEN_PAYLOAD',
               status: 401
@@ -295,6 +310,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'TOKEN_EXPIRED',
               message: 'Token expired',
               code: 'TOKEN_EXPIRED',
               status: 401
@@ -319,6 +335,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 }
 
                 const error = {
+                  error: 'INVALID_SESSION',
                   message: 'Session invalid or expired',
                   code: 'INVALID_SESSION',
                   status: 401
@@ -356,6 +373,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               }
 
               const error = {
+                error: 'SESSION_VALIDATION_ERROR',
                 message: 'Session validation failed',
                 code: 'SESSION_VALIDATION_ERROR',
                 status: 401
@@ -416,6 +434,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * Returns a middleware function for Socket.IO that validates JWT tokens
      * from the handshake auth object and attaches user data to the socket.
      *
+     * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+     *
      * @example
      * ```typescript
      * import { OxyServices } from '@oxyhq/core';

package/src/utils/authHelpers.ts

@@ -0,0 +1,140 @@
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+
+import type { OxyServices } from '../OxyServices';
+
+/**
+ * Error thrown when session sync is required
+ */
+export class SessionSyncRequiredError extends Error {
+  constructor(message = 'Session needs to be synced. Please try again.') {
+    super(message);
+    this.name = 'SessionSyncRequiredError';
+  }
+}
+
+/**
+ * Error thrown when authentication fails
+ */
+export class AuthenticationFailedError extends Error {
+  constructor(message = 'Authentication failed. Please sign in again.') {
+    super(message);
+    this.name = 'AuthenticationFailedError';
+  }
+}
+
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+export async function ensureValidToken(
+  oxyServices: OxyServices,
+  activeSessionId: string | null | undefined
+): Promise<void> {
+  if (oxyServices.hasValidToken() || !activeSessionId) {
+    return;
+  }
+
+  try {
+    await oxyServices.getTokenBySession(activeSessionId);
+  } catch (tokenError) {
+    const errorMessage = tokenError instanceof Error ? tokenError.message : String(tokenError);
+
+    if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+      throw new SessionSyncRequiredError();
+    }
+
+    throw tokenError;
+  }
+}
+
+/**
+ * Options for handling API authentication errors
+ */
+export interface HandleApiErrorOptions {
+  syncSession?: () => Promise<unknown>;
+  activeSessionId?: string | null;
+  oxyServices?: OxyServices;
+}
+
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+export function isAuthenticationError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const errorObj = error as { message?: string; status?: number; response?: { status?: number } };
+  const errorMessage = errorObj.message || '';
+  const status = errorObj.status || errorObj.response?.status;
+
+  return (
+    status === 401 ||
+    errorMessage.includes('Authentication required') ||
+    errorMessage.includes('Invalid or missing authorization header')
+  );
+}
+
+/**
+ * Wraps an API call with authentication error handling.
+ * On auth failure, optionally attempts to sync the session and retry.
+ *
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ */
+export async function withAuthErrorHandling<T>(
+  apiCall: () => Promise<T>,
+  options?: HandleApiErrorOptions
+): Promise<T> {
+  try {
+    return await apiCall();
+  } catch (error) {
+    if (!isAuthenticationError(error)) {
+      throw error;
+    }
+
+    if (options?.syncSession && options?.activeSessionId && options?.oxyServices) {
+      try {
+        await options.syncSession();
+        await options.oxyServices.getTokenBySession(options.activeSessionId);
+        return await apiCall();
+      } catch {
+        throw new AuthenticationFailedError();
+      }
+    }
+
+    throw new AuthenticationFailedError();
+  }
+}
+
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export async function authenticatedApiCall<T>(
+  oxyServices: OxyServices,
+  activeSessionId: string | null | undefined,
+  apiCall: () => Promise<T>,
+  syncSession?: () => Promise<unknown>
+): Promise<T> {
+  await ensureValidToken(oxyServices, activeSessionId);
+
+  return withAuthErrorHandling(apiCall, {
+    syncSession,
+    activeSessionId,
+    oxyServices,
+  });
+}