@oxyhq/core 1.6.0 → 1.6.2

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

@@ -1,4 +1,4 @@
-import { OxyAuthenticationError } from '../OxyServices.errors';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
 export function OxyServicesAuthMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,4 +1,4 @@
-import { CACHE_TIMES } from './mixinHelpers';
+import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesDeveloperMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,4 +1,4 @@
-import { CACHE_TIMES } from './mixinHelpers';
+import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesFeaturesMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,6 +1,7 @@
-import { OxyAuthenticationError } from '../OxyServices.errors';
-import { createDebugLogger } from '../shared/utils/debugUtils';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
+import { createDebugLogger } from '../shared/utils/debugUtils.js';
 const debug = createDebugLogger('FedCM');
+const FEDCM_LOGIN_HINT_KEY = 'oxy_fedcm_login_hint';
 // Global lock to prevent concurrent FedCM requests
 // FedCM only allows one navigator.credentials.get request at a time
 let fedCMRequestInProgress = false;
@@ -78,13 +79,16 @@ export function OxyServicesFedCMMixin(Base) {
                 try {
                     const nonce = options.nonce || this.generateNonce();
                     const clientId = this.getClientId();
-                    debug.log('Interactive sign-in: Requesting credential for', clientId);
+                    // Use provided loginHint, or fall back to stored last-used account ID
+                    const loginHint = options.loginHint || this.getStoredLoginHint();
+                    debug.log('Interactive sign-in: Requesting credential for', clientId, loginHint ? `(hint: ${loginHint})` : '');
                     // Request credential from browser's native identity flow
                     const credential = await this.requestIdentityCredential({
                         configURL: this.constructor.DEFAULT_CONFIG_URL,
                         clientId,
                         nonce,
                         context: options.context,
+                        loginHint,
                     });
                     if (!credential || !credential.token) {
                         throw new OxyAuthenticationError('No credential received from browser');
@@ -96,6 +100,10 @@ export function OxyServicesFedCMMixin(Base) {
                     if (session && session.accessToken) {
                         this.httpService.setTokens(session.accessToken);
                     }
+                    // Store the user ID as loginHint for future FedCM requests
+                    if (session?.user?.id) {
+                        this.storeLoginHint(session.user.id);
+                    }
                     debug.log('Interactive sign-in: Success!', { userId: session?.user?.id });
                     return session;
                 }
@@ -160,13 +168,15 @@ export function OxyServicesFedCMMixin(Base) {
                 // this runs on app startup — showing browser UI without user action is bad UX.
                 // Optional/interactive mediation should only happen when the user clicks "Sign In".
                 let credential = null;
+                const loginHint = this.getStoredLoginHint();
                 try {
                     const nonce = this.generateNonce();
-                    debug.log('Silent SSO: Attempting silent mediation...');
+                    debug.log('Silent SSO: Attempting silent mediation...', loginHint ? `(hint: ${loginHint})` : '');
                     credential = await this.requestIdentityCredential({
                         configURL: this.constructor.DEFAULT_CONFIG_URL,
                         clientId,
                         nonce,
+                        loginHint,
                         mediation: 'silent',
                     });
                     debug.log('Silent SSO: Silent mediation result:', { hasCredential: !!credential, hasToken: !!credential?.token });
@@ -221,6 +231,10 @@ export function OxyServicesFedCMMixin(Base) {
                 else {
                     debug.warn('Silent SSO: No accessToken in session response');
                 }
+                // Store the user ID as loginHint for future FedCM requests
+                if (session.user?.id) {
+                    this.storeLoginHint(session.user.id);
+                }
                 debug.log('Silent SSO: Success!', {
                     sessionId: session.sessionId?.substring(0, 8) + '...',
                     userId: session.user?.id
@@ -295,7 +309,7 @@ export function OxyServicesFedCMMixin(Base) {
                                         params: {
                                             nonce: options.nonce, // For Chrome 145+
                                         },
-                                        ...(options.context && { loginHint: options.context }),
+                                        ...(options.loginHint && { loginHint: options.loginHint }),
                                     },
                                 ],
                             },
@@ -415,6 +429,28 @@ export function OxyServicesFedCMMixin(Base) {
                 }
                 return window.location.origin;
             }
+            /** @internal */
+            getStoredLoginHint() {
+                if (typeof window === 'undefined')
+                    return undefined;
+                try {
+                    return localStorage.getItem(FEDCM_LOGIN_HINT_KEY) || undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            }
+            /** @internal */
+            storeLoginHint(userId) {
+                if (typeof window === 'undefined')
+                    return;
+                try {
+                    localStorage.setItem(FEDCM_LOGIN_HINT_KEY, userId);
+                }
+                catch {
+                    // Storage full or blocked
+                }
+            }
         },
         _a.DEFAULT_CONFIG_URL = 'https://auth.oxy.so/fedcm.json',
         _a.FEDCM_TIMEOUT = 15000 // 15 seconds for interactive

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

@@ -1,4 +1,4 @@
-import { CACHE_TIMES } from './mixinHelpers';
+import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesKarmaMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,8 +1,8 @@
 /**
  * Language Methods Mixin
  */
-import { normalizeLanguageCode, getLanguageMetadata, getLanguageName, getNativeLanguageName } from '../utils/languageUtils';
-import { isDev } from '../shared/utils/debugUtils';
+import { normalizeLanguageCode, getLanguageMetadata, getLanguageName, getNativeLanguageName } from '../utils/languageUtils.js';
+import { isDev } from '../shared/utils/debugUtils.js';
 export function OxyServicesLanguageMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,4 +1,4 @@
-import { CACHE_TIMES } from './mixinHelpers';
+import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesPaymentMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,5 +1,5 @@
-import { OxyAuthenticationError } from '../OxyServices.errors';
-import { createDebugLogger } from '../shared/utils/debugUtils';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
+import { createDebugLogger } from '../shared/utils/debugUtils.js';
 const debug = createDebugLogger('PopupAuth');
 /**
  * Popup-based Cross-Domain Authentication Mixin

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

@@ -1,4 +1,4 @@
-import { isDev } from '../shared/utils/debugUtils';
+import { isDev } from '../shared/utils/debugUtils.js';
 export function OxyServicesPrivacyMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,4 +1,4 @@
-import { OxyAuthenticationError } from '../OxyServices.errors';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
 /**
  * Redirect-based Cross-Domain Authentication Mixin
  *

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

@@ -1,4 +1,4 @@
-import { isDev } from '../shared/utils/debugUtils';
+import { isDev } from '../shared/utils/debugUtils.js';
 export function OxyServicesSecurityMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -1,4 +1,4 @@
-import { buildSearchParams, buildPaginationParams } from '../utils/apiUtils';
+import { buildSearchParams, buildPaginationParams } from '../utils/apiUtils.js';
 export function OxyServicesUserMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -5,7 +5,7 @@
  * and Express.js authentication middleware
  */
 import { jwtDecode } from 'jwt-decode';
-import { CACHE_TIMES } from './mixinHelpers';
+import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesUtilityMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -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/mixins/index.js

@@ -4,24 +4,24 @@
  * This module provides a clean way to compose all mixins
  * and ensures consistent ordering for better maintainability
  */
-import { OxyServicesBase } from '../OxyServices.base';
-import { OxyServicesAuthMixin } from './OxyServices.auth';
-import { OxyServicesFedCMMixin } from './OxyServices.fedcm';
-import { OxyServicesPopupAuthMixin } from './OxyServices.popup';
-import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
-import { OxyServicesUserMixin } from './OxyServices.user';
-import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
-import { OxyServicesLanguageMixin } from './OxyServices.language';
-import { OxyServicesPaymentMixin } from './OxyServices.payment';
-import { OxyServicesKarmaMixin } from './OxyServices.karma';
-import { OxyServicesAssetsMixin } from './OxyServices.assets';
-import { OxyServicesDeveloperMixin } from './OxyServices.developer';
-import { OxyServicesLocationMixin } from './OxyServices.location';
-import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
-import { OxyServicesDevicesMixin } from './OxyServices.devices';
-import { OxyServicesSecurityMixin } from './OxyServices.security';
-import { OxyServicesUtilityMixin } from './OxyServices.utility';
-import { OxyServicesFeaturesMixin } from './OxyServices.features';
+import { OxyServicesBase } from '../OxyServices.base.js';
+import { OxyServicesAuthMixin } from './OxyServices.auth.js';
+import { OxyServicesFedCMMixin } from './OxyServices.fedcm.js';
+import { OxyServicesPopupAuthMixin } from './OxyServices.popup.js';
+import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect.js';
+import { OxyServicesUserMixin } from './OxyServices.user.js';
+import { OxyServicesPrivacyMixin } from './OxyServices.privacy.js';
+import { OxyServicesLanguageMixin } from './OxyServices.language.js';
+import { OxyServicesPaymentMixin } from './OxyServices.payment.js';
+import { OxyServicesKarmaMixin } from './OxyServices.karma.js';
+import { OxyServicesAssetsMixin } from './OxyServices.assets.js';
+import { OxyServicesDeveloperMixin } from './OxyServices.developer.js';
+import { OxyServicesLocationMixin } from './OxyServices.location.js';
+import { OxyServicesAnalyticsMixin } from './OxyServices.analytics.js';
+import { OxyServicesDevicesMixin } from './OxyServices.devices.js';
+import { OxyServicesSecurityMixin } from './OxyServices.security.js';
+import { OxyServicesUtilityMixin } from './OxyServices.utility.js';
+import { OxyServicesFeaturesMixin } from './OxyServices.features.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *

package/dist/esm/shared/index.js

@@ -20,12 +20,12 @@
  * ```
  */
 // Color utilities
-export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './utils/colorUtils';
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './utils/colorUtils.js';
 // Theme utilities
-export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './utils/themeUtils';
+export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './utils/themeUtils.js';
 // Error utilities
-export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './utils/errorUtils';
+export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './utils/errorUtils.js';
 // Network utilities
-export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './utils/networkUtils';
+export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './utils/networkUtils.js';
 // Debug utilities
-export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './utils/debugUtils';
+export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './utils/debugUtils.js';

package/dist/esm/shared/utils/index.js

@@ -6,10 +6,10 @@
  * @module shared/utils
  */
 // Color utilities
-export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './colorUtils';
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './colorUtils.js';
 // Theme utilities
-export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './themeUtils';
+export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './themeUtils.js';
 // Error utilities
-export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './errorUtils';
+export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './errorUtils.js';
 // Network utilities
-export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './networkUtils';
+export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './networkUtils.js';

package/dist/esm/utils/asyncUtils.js

@@ -1,7 +1,7 @@
 /**
  * Async utilities for common asynchronous patterns and error handling
  */
-import { logger } from './loggerUtils';
+import { logger } from './loggerUtils.js';
 /**
  * Wrapper for async operations with automatic error handling
  * Returns null on error instead of throwing

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/esm/utils/errorUtils.js

@@ -1,4 +1,4 @@
-import { logger } from './loggerUtils';
+import { logger } from './loggerUtils.js';
 /**
  * Error handling utilities for consistent error processing
  */

package/dist/esm/utils/index.js

@@ -1,7 +1,7 @@
-export { DeviceManager } from './deviceManager';
+export { DeviceManager } from './deviceManager.js';
 // Request utilities
-export { RequestDeduplicator, RequestQueue, SimpleLogger } from './requestUtils';
+export { RequestDeduplicator, RequestQueue, SimpleLogger } from './requestUtils.js';
 // Cache utilities
-export { TTLCache, createCache, registerCacheForCleanup, unregisterCacheFromCleanup } from './cache';
+export { TTLCache, createCache, registerCacheForCleanup, unregisterCacheFromCleanup } from './cache.js';
 // Session utilities
-export { normalizeSession, sortSessions, deduplicateSessions, deduplicateSessionsByUserId, normalizeAndSortSessions, mergeSessions, sessionsEqual, sessionsArraysEqual } from './sessionUtils';
+export { normalizeSession, sortSessions, deduplicateSessions, deduplicateSessionsByUserId, normalizeAndSortSessions, mergeSessions, sessionsEqual, sessionsArraysEqual } from './sessionUtils.js';

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.fedcm.d.ts

@@ -3,6 +3,7 @@ import type { SessionLoginResponse } from '../models/session';
 export interface FedCMAuthOptions {
     nonce?: string;
     context?: 'signin' | 'signup' | 'continue' | 'use';
+    loginHint?: string;
 }
 export interface FedCMConfig {
     enabled: boolean;
@@ -107,6 +108,7 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
             clientId: string;
             nonce: string;
             context?: string;
+            loginHint?: string;
             mediation?: "silent" | "optional" | "required";
         }): Promise<{
             token: string;
@@ -145,6 +147,10 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
          * @private
          */
         getClientId(): string;
+        /** @internal */
+        getStoredLoginHint(): string | undefined;
+        /** @internal */
+        storeLoginHint(userId: string): void;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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';