@oxyhq/core 1.11.18 → 1.11.20

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

@@ -10,6 +10,25 @@ export interface FedCMConfig {
     configURL: string;
     clientId?: string;
 }
+/**
+ * FedCM request mode values.
+ *
+ * The W3C FedCM spec renamed the `IdentityCredentialRequestOptions.mode` enum:
+ * `'widget'` → `'passive'` and `'button'` → `'active'`. Modern Chrome only
+ * accepts `'active'`/`'passive'` and throws a synchronous `TypeError` for the
+ * legacy values, while Chrome 125–131 only understands `'button'`/`'widget'`.
+ * Callers should use the modern values; the legacy values are accepted for
+ * convenience and normalised internally.
+ */
+export type FedCMRequestMode = 'active' | 'passive' | 'button' | 'widget';
+/**
+ * Normalised result of a FedCM credential request: the IdP-issued ID token plus
+ * whether the browser auto-selected the account (no explicit user choice).
+ */
+interface FedCMTokenResult {
+    token: string;
+    isAutoSelected: boolean;
+}
 /**
  * Federated Credential Management (FedCM) Authentication Mixin
  *
@@ -111,11 +130,15 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
             context?: string;
             loginHint?: string;
             mediation?: "silent" | "optional" | "required";
-            mode?: "button" | "widget";
-        }): Promise<{
-            token: string;
-            isAutoSelected: boolean;
-        } | null>;
+            /**
+             * FedCM request mode. The W3C spec values are `'active'` (user-gesture
+             * button flow) and `'passive'` (browser-initiated widget flow). Chrome
+             * 125–131 used the legacy names `'button'`/`'widget'`; those are accepted
+             * here and mapped to the modern values, with an automatic legacy retry if
+             * the running browser only understands the old enum.
+             */
+            mode?: FedCMRequestMode;
+        }): Promise<FedCMTokenResult | null>;
         /**
          * Exchange FedCM ID token for Oxy session
          *

package/package.json

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

package/src/mixins/OxyServices.fedcm.ts

@@ -17,12 +17,117 @@ export interface FedCMConfig {
   clientId?: string;
 }
 
+/**
+ * FedCM request mode values.
+ *
+ * The W3C FedCM spec renamed the `IdentityCredentialRequestOptions.mode` enum:
+ * `'widget'` → `'passive'` and `'button'` → `'active'`. Modern Chrome only
+ * accepts `'active'`/`'passive'` and throws a synchronous `TypeError` for the
+ * legacy values, while Chrome 125–131 only understands `'button'`/`'widget'`.
+ * Callers should use the modern values; the legacy values are accepted for
+ * convenience and normalised internally.
+ */
+export type FedCMRequestMode = 'active' | 'passive' | 'button' | 'widget';
+
+// Modern (W3C spec) → legacy (Chrome 125–131) mode value mapping. Used to
+// retry a credential request when an older browser rejects the modern enum.
+const MODERN_TO_LEGACY_MODE: Record<'active' | 'passive', 'button' | 'widget'> = {
+  active: 'button',
+  passive: 'widget',
+};
+
+// Legacy → modern mapping so callers may pass either spelling.
+const LEGACY_TO_MODERN_MODE: Record<'button' | 'widget', 'active' | 'passive'> = {
+  button: 'active',
+  widget: 'passive',
+};
+
+/**
+ * Normalise any accepted mode value to the modern W3C spelling
+ * (`'active'`/`'passive'`), which is what is sent to the browser first.
+ */
+function toModernMode(mode: FedCMRequestMode): 'active' | 'passive' {
+  return mode === 'button' || mode === 'widget' ? LEGACY_TO_MODERN_MODE[mode] : mode;
+}
+
+/**
+ * Detect the synchronous `TypeError` a pre-spec browser throws when it does not
+ * recognise a modern `mode` enum value (e.g. Chrome 125–131 rejecting
+ * `'active'`/`'passive'`). Such a browser only understands the legacy
+ * `'button'`/`'widget'` values, so the caller can retry with those.
+ */
+function isUnknownModeEnumError(error: unknown): boolean {
+  if (!(error instanceof TypeError)) return false;
+  const message = error.message.toLowerCase();
+  return (
+    message.includes('identitycredentialrequestoptionsmode') ||
+    ((message.includes('active') || message.includes('passive')) &&
+      (message.includes('enum') || message.includes('not a valid')))
+  );
+}
+
+// Minimal structural types for the FedCM `navigator.credentials.get` surface.
+// The DOM lib does not ship these in every TypeScript version we build against,
+// so we model only the fields this mixin reads/writes. This lets the FedCM code
+// stay free of `any` without depending on lib-dom FedCM typings.
+interface FedCMProviderRequest {
+  configURL: string;
+  clientId: string;
+  nonce: string;
+  params?: { nonce: string };
+  loginHint?: string;
+}
+
+interface FedCMIdentityRequest {
+  providers: FedCMProviderRequest[];
+  mode?: FedCMRequestMode;
+}
+
+interface FedCMCredentialRequest {
+  identity: FedCMIdentityRequest;
+  mediation: 'silent' | 'optional' | 'required';
+  signal: AbortSignal;
+}
+
+interface FedCMIdentityCredential {
+  type?: string;
+  token?: string;
+  isAutoSelected?: boolean;
+}
+
+interface FedCMCredentialsContainer {
+  get(options: FedCMCredentialRequest): Promise<FedCMIdentityCredential | null>;
+}
+
+/**
+ * Normalised result of a FedCM credential request: the IdP-issued ID token plus
+ * whether the browser auto-selected the account (no explicit user choice).
+ */
+interface FedCMTokenResult {
+  token: string;
+  isAutoSelected: boolean;
+}
+
+// Options accepted by the static `IdentityCredential.disconnect()` method
+// (W3C FedCM "disconnect" / sign-out). Not declared in every lib-dom version.
+interface FedCMDisconnectOptions {
+  configURL: string;
+  clientId: string;
+  accountHint: string;
+}
+
+// Minimal structural shape of the global `IdentityCredential` interface object,
+// modelling only the static `disconnect` method this mixin invokes.
+interface FedCMIdentityCredentialStatic {
+  disconnect(options: FedCMDisconnectOptions): Promise<void>;
+}
+
 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;
-let fedCMRequestPromise: Promise<any> | null = null;
+let fedCMRequestPromise: Promise<FedCMTokenResult | null> | null = null;
 let currentMediationMode: string | null = null;
 
 /**
@@ -120,15 +225,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
 
       debug.log('Interactive sign-in: Requesting credential for', clientId, loginHint ? `(hint: ${loginHint})` : '');
 
-      // Request credential from browser's native identity flow
-      // mode: 'button' signals this is a user-gesture-initiated flow (Chrome 125+)
+      // Request credential from browser's native identity flow.
+      // mode: 'active' signals this is a user-gesture-initiated (button) flow.
+      // 'active' is the current W3C spec value; requestIdentityCredential
+      // transparently retries with the legacy 'button' value for Chrome 125–131.
       const credential = await this.requestIdentityCredential({
         configURL: this.resolveFedcmConfigUrl(),
         clientId,
         nonce,
         context: options.context,
         loginHint,
-        mode: 'button',
+        mode: 'active',
       });
 
       if (!credential || !credential.token) {
@@ -140,9 +247,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       // Exchange FedCM ID token for Oxy session
       const session = await this.exchangeIdTokenForSession(credential.token);
 
-      // Store access token in HttpService (extract from response or get from session)
-      if (session && (session as any).accessToken) {
-        this.httpService.setTokens((session as any).accessToken);
+      // Store access token in HttpService. `accessToken`/`refreshToken` are
+      // declared optional on SessionLoginResponse; default the refresh token to
+      // an empty string when the exchange did not return one.
+      if (session?.accessToken) {
+        this.httpService.setTokens(session.accessToken, session.refreshToken ?? '');
       }
 
       // Store the user ID as loginHint for future FedCM requests
@@ -150,17 +259,20 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         this.storeLoginHint(session.user.id);
       }
 
-      debug.log('Interactive sign-in: Success!', { userId: (session as any)?.user?.id });
+      debug.log('Interactive sign-in: Success!', { userId: session?.user?.id });
 
       return session;
     } catch (error) {
       debug.log('Interactive sign-in failed:', error);
       const errorMessage = error instanceof Error ? error.message : String(error);
+      // FedCM aborts/network failures surface as DOMException/Error instances,
+      // both of which carry a `name`. Anything else has no meaningful name.
+      const errorName = error instanceof Error ? error.name : '';
 
-      if ((error as any).name === 'AbortError') {
+      if (errorName === 'AbortError') {
         throw new OxyAuthenticationError('Sign-in was cancelled by user');
       }
-      if ((error as any).name === 'NetworkError') {
+      if (errorName === 'NetworkError') {
         throw new OxyAuthenticationError('Network error during sign-in. Please check your connection.');
       }
       if (errorMessage.includes('multiple accounts')) {
@@ -217,7 +329,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     // We intentionally do NOT fall back to optional mediation here because
     // 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: { token: string; isAutoSelected: boolean } | null = null;
+    let credential: FedCMTokenResult | null = null;
 
     const loginHint = this.getStoredLoginHint();
 
@@ -284,9 +396,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       return null;
     }
 
-    // Set the access token
-    if ((session as any).accessToken) {
-      this.httpService.setTokens((session as any).accessToken);
+    // Set the access token. `accessToken`/`refreshToken` are declared optional
+    // on SessionLoginResponse; default the refresh token to an empty string when
+    // the exchange did not return one.
+    if (session.accessToken) {
+      this.httpService.setTokens(session.accessToken, session.refreshToken ?? '');
       debug.log('Silent SSO: Access token set');
     } else {
       debug.warn('Silent SSO: No accessToken in session response');
@@ -322,8 +436,15 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     context?: string;
     loginHint?: string;
     mediation?: 'silent' | 'optional' | 'required';
-    mode?: 'button' | 'widget';
-  }): Promise<{ token: string; isAutoSelected: boolean } | null> {
+    /**
+     * FedCM request mode. The W3C spec values are `'active'` (user-gesture
+     * button flow) and `'passive'` (browser-initiated widget flow). Chrome
+     * 125–131 used the legacy names `'button'`/`'widget'`; those are accepted
+     * here and mapped to the modern values, with an automatic legacy retry if
+     * the running browser only understands the old enum.
+     */
+    mode?: FedCMRequestMode;
+  }): Promise<FedCMTokenResult | null> {
     const requestedMediation = options.mediation || 'optional';
     const isInteractive = requestedMediation !== 'silent';
 
@@ -367,31 +488,58 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       controller.abort();
     }, timeoutMs);
 
+    // Normalise the caller's mode to the modern W3C value first. A modern
+    // browser accepts it; an older one (Chrome 125–131) rejects it with a
+    // synchronous TypeError, in which case we retry with the legacy value.
+    const modernMode = options.mode ? toModernMode(options.mode) : undefined;
+
+    // Build the identity request for a specific mode value. The `mode` field
+    // lives on the `identity` object (sibling of `providers`), separate from
+    // the top-level `mediation` field.
+    const buildCredentialOptions = (modeValue: FedCMRequestMode | undefined): FedCMCredentialRequest => ({
+      identity: {
+        providers: [
+          {
+            configURL: options.configURL,
+            clientId: options.clientId,
+            // Older browsers read `nonce` at the top level; Chrome 145+
+            // expects it inside `params`. Send both for full coverage.
+            nonce: options.nonce,
+            params: {
+              nonce: options.nonce,
+            },
+            ...(options.loginHint && { loginHint: options.loginHint }),
+          },
+        ],
+        ...(modeValue && { mode: modeValue }),
+      },
+      mediation: requestedMediation,
+      signal: controller.signal,
+    });
+
+    // The DOM lib's `CredentialsContainer` does not declare the FedCM `identity`
+    // request in every TypeScript version we build against. Re-type through the
+    // minimal structural interface above (not `any`) to keep this typed.
+    const credentials = navigator.credentials as unknown as FedCMCredentialsContainer;
+
     fedCMRequestPromise = (async () => {
       try {
-        debug.log('Calling navigator.credentials.get with mediation:', requestedMediation);
-        // Type assertion needed as FedCM types may not be in all TypeScript versions
-        const credentialOptions: any = {
-          identity: {
-            providers: [
-              {
-                configURL: options.configURL,
-                clientId: options.clientId,
-                // Older browsers read `nonce` at the top level; Chrome 145+
-                // expects it inside `params`. Send both for full coverage.
-                nonce: options.nonce,
-                params: {
-                  nonce: options.nonce,
-                },
-                ...(options.loginHint && { loginHint: options.loginHint }),
-              },
-            ],
-            ...(options.mode && { mode: options.mode }),
-          },
-          mediation: requestedMediation,
-          signal: controller.signal,
-        };
-        const credential = (await (navigator.credentials as any).get(credentialOptions)) as any;
+        debug.log('Calling navigator.credentials.get with mediation:', requestedMediation, modernMode ? `mode: ${modernMode}` : '');
+        let credential: FedCMIdentityCredential | null;
+        try {
+          credential = await credentials.get(buildCredentialOptions(modernMode));
+        } catch (modeError) {
+          // Chrome 125–131 only knows the legacy 'button'/'widget' enum and
+          // throws a synchronous TypeError for the modern 'active'/'passive'
+          // values. Retry once with the legacy value so older browsers work.
+          if (modernMode && isUnknownModeEnumError(modeError)) {
+            const legacyMode = MODERN_TO_LEGACY_MODE[modernMode];
+            debug.log(`Browser rejected modern mode '${modernMode}'; retrying with legacy mode '${legacyMode}'`);
+            credential = await credentials.get(buildCredentialOptions(legacyMode));
+          } else {
+            throw modeError;
+          }
+        }
 
         debug.log('navigator.credentials.get returned:', {
           hasCredential: !!credential,
@@ -399,7 +547,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
           hasToken: !!credential?.token,
         });
 
-        if (!credential || credential.type !== 'identity') {
+        if (!credential || credential.type !== 'identity' || !credential.token) {
           debug.log('No valid identity credential returned');
           return null;
         }
@@ -471,9 +619,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     try {
-      if ('IdentityCredential' in window && 'disconnect' in (window as any).IdentityCredential) {
+      // The DOM lib does not declare the global `IdentityCredential` interface
+      // object (with its static `disconnect`) in every TypeScript version we
+      // build against. Read it off `window` through the minimal structural type
+      // (not `any`), guarding that `disconnect` is actually present at runtime.
+      const fedCMWindow = window as unknown as {
+        IdentityCredential?: Partial<FedCMIdentityCredentialStatic>;
+      };
+      const identityCredential = fedCMWindow.IdentityCredential;
+      if (identityCredential && typeof identityCredential.disconnect === 'function') {
         const clientId = this.getClientId();
-        await (window as any).IdentityCredential.disconnect({
+        await identityCredential.disconnect({
           configURL: this.resolveFedcmConfigUrl(),
           clientId,
           accountHint: accountHint || '*',

package/src/mixins/__tests__/fedcm.test.ts

@@ -185,3 +185,139 @@ describe('OxyServices FedCM nonce binding', () => {
     await expect(oxy.silentSignInWithFedCM()).resolves.toBeNull();
   });
 });
+
+/**
+ * FedCM `mode` enum regression tests.
+ *
+ * The W3C FedCM spec renamed `IdentityCredentialRequestOptions.mode`:
+ * `'button'` → `'active'` and `'widget'` → `'passive'`. Modern Chrome rejects
+ * the legacy values with a synchronous `TypeError`; Chrome 125–131 only knows
+ * the legacy values. These tests lock in that:
+ *
+ *   1. the interactive button flow requests the MODERN `mode: 'active'`;
+ *   2. a `TypeError` on the modern value triggers a single retry with the
+ *      LEGACY `'button'` value (so older Chrome still works);
+ *   3. the silent SSO path sends NO `mode` at all (mode and mediation are
+ *      independent fields).
+ */
+function mintAndExchange(oxy: OxyServices, exchanged: string[]): void {
+  jest
+    .spyOn(oxy, 'makeRequest')
+    .mockImplementation(async (_method: string, url: string, data?: unknown) => {
+      if (url === '/fedcm/nonce') {
+        return { nonce: 'server-nonce', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+      }
+      if (url === '/fedcm/exchange') {
+        exchanged.push((data as { id_token: string }).id_token);
+        return {
+          sessionId: 'sess_mode',
+          deviceId: 'dev_mode',
+          expiresAt: new Date(Date.now() + 60000).toISOString(),
+          accessToken: 'access_mode',
+          user: { id: 'user_mode', username: 'tester' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+}
+
+describe('OxyServices FedCM mode enum (active/passive)', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('interactive sign-in requests the modern mode: "active"', async () => {
+    const modesSeen: Array<string | undefined> = [];
+    installBrowserGlobals({
+      credentialsGet: async (opts) => {
+        modesSeen.push(opts.identity.mode);
+        return { type: 'identity', token: 'idp-id-token', isAutoSelected: false };
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const exchanged: string[] = [];
+    mintAndExchange(oxy, exchanged);
+
+    const session = await oxy.signInWithFedCM();
+
+    expect(session.sessionId).toBe('sess_mode');
+    // The modern W3C value — never the legacy 'button' — is sent first.
+    expect(modesSeen).toEqual(['active']);
+    expect(exchanged).toEqual(['idp-id-token']);
+  });
+
+  it('retries with legacy mode "button" when the browser rejects "active" with a TypeError', async () => {
+    const modesSeen: Array<string | undefined> = [];
+    installBrowserGlobals({
+      credentialsGet: async (opts) => {
+        modesSeen.push(opts.identity.mode);
+        // First call (modern 'active'): emulate Chrome 125–131 rejecting the
+        // unknown enum value synchronously with a TypeError.
+        if (opts.identity.mode === 'active') {
+          throw new TypeError(
+            "The provided value 'active' is not a valid enum value of type IdentityCredentialRequestOptionsMode."
+          );
+        }
+        // Second call (legacy 'button'): the old browser accepts it.
+        return { type: 'identity', token: 'legacy-id-token', isAutoSelected: false };
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const exchanged: string[] = [];
+    mintAndExchange(oxy, exchanged);
+
+    const session = await oxy.signInWithFedCM();
+
+    expect(session.sessionId).toBe('sess_mode');
+    // Tried modern 'active' first, then fell back to legacy 'button'.
+    expect(modesSeen).toEqual(['active', 'button']);
+    // The token from the successful legacy retry was exchanged.
+    expect(exchanged).toEqual(['legacy-id-token']);
+  });
+
+  it('does not retry (and surfaces the error) when a non-mode TypeError is thrown', async () => {
+    let callCount = 0;
+    installBrowserGlobals({
+      credentialsGet: async () => {
+        callCount += 1;
+        throw new TypeError('Failed to fetch the FedCM config file.');
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const exchanged: string[] = [];
+    mintAndExchange(oxy, exchanged);
+
+    await expect(oxy.signInWithFedCM()).rejects.toThrow('Failed to fetch the FedCM config file.');
+    // Only one attempt — an unrelated TypeError must not trigger the legacy retry.
+    expect(callCount).toBe(1);
+  });
+
+  it('silent SSO sends no mode (mode and mediation are independent fields)', async () => {
+    let credentialCall: CredentialGetCall | null = null;
+    installBrowserGlobals({
+      credentialsGet: async (opts) => {
+        credentialCall = opts;
+        return null;
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
+      if (url === '/fedcm/nonce') {
+        return { nonce: 'n', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    await oxy.silentSignInWithFedCM();
+
+    expect(credentialCall).not.toBeNull();
+    const call = credentialCall as unknown as CredentialGetCall;
+    expect(call.mediation).toBe('silent');
+    expect(call.identity.mode).toBeUndefined();
+  });
+});