@oxyhq/core 1.6.0 → 1.6.2

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.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -58,7 +58,7 @@
     "build": "npm run build:cjs && npm run build:esm && npm run build:types && npm run copy-assets",
     "copy-assets": "cp -r src/i18n/locales dist/cjs/i18n/locales && cp -r src/i18n/locales dist/esm/i18n/locales",
     "build:cjs": "tsc -p tsconfig.cjs.json",
-    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-imports.mjs",
     "build:types": "tsc -p tsconfig.types.json",
     "clean": "rm -rf dist",
     "typescript": "tsc --noEmit",

package/src/AuthManager.ts

@@ -58,6 +58,7 @@ const STORAGE_KEYS = {
   SESSION: 'oxy_session',
   USER: 'oxy_user',
   AUTH_METHOD: 'oxy_auth_method',
+  FEDCM_LOGIN_HINT: 'oxy_fedcm_login_hint',
 } as const;
 
 /**
@@ -366,6 +367,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;
@@ -396,6 +410,7 @@ export class AuthManager {
     await this.storage.removeItem(STORAGE_KEYS.SESSION);
     await this.storage.removeItem(STORAGE_KEYS.USER);
     await this.storage.removeItem(STORAGE_KEYS.AUTH_METHOD);
+    await this.storage.removeItem(STORAGE_KEYS.FEDCM_LOGIN_HINT);
   }
 
   /**

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

@@ -8,6 +8,7 @@ const debug = createDebugLogger('FedCM');
 export interface FedCMAuthOptions {
   nonce?: string;
   context?: 'signin' | 'signup' | 'continue' | 'use';
+  loginHint?: string;
 }
 
 export interface FedCMConfig {
@@ -16,6 +17,8 @@ export interface FedCMConfig {
   clientId?: string;
 }
 
+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;
@@ -102,7 +105,10 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       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({
@@ -110,6 +116,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         clientId,
         nonce,
         context: options.context,
+        loginHint,
       });
 
       if (!credential || !credential.token) {
@@ -126,6 +133,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         this.httpService.setTokens((session as any).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 as any)?.user?.id });
 
       return session;
@@ -195,14 +207,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     // Optional/interactive mediation should only happen when the user clicks "Sign In".
     let credential: { token: string } | null = 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 as any).DEFAULT_CONFIG_URL,
         clientId,
         nonce,
+        loginHint,
         mediation: 'silent',
       });
 
@@ -263,6 +278,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       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
@@ -286,6 +306,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     clientId: string;
     nonce: string;
     context?: string;
+    loginHint?: string;
     mediation?: 'silent' | 'optional' | 'required';
   }): Promise<{ token: string } | null> {
     const requestedMediation = options.mediation || 'optional';
@@ -346,7 +367,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
                 params: {
                   nonce: options.nonce, // For Chrome 145+
                 },
-                ...(options.context && { loginHint: options.context }),
+                ...(options.loginHint && { loginHint: options.loginHint }),
               },
             ],
           },
@@ -480,6 +501,26 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     }
     return window.location.origin;
   }
+
+  /** @internal */
+  public getStoredLoginHint(): string | undefined {
+    if (typeof window === 'undefined') return undefined;
+    try {
+      return localStorage.getItem(FEDCM_LOGIN_HINT_KEY) || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** @internal */
+  public storeLoginHint(userId: string): void {
+    if (typeof window === 'undefined') return;
+    try {
+      localStorage.setItem(FEDCM_LOGIN_HINT_KEY, userId);
+    } catch {
+      // Storage full or blocked
+    }
+  }
   };
 }
 

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,
+  });
+}