@oxyhq/core 1.11.17 → 1.11.18

package/src/crypto/keyManager.ts

@@ -637,16 +637,28 @@ export class KeyManager {
   /**
    * Atomically persist a key pair to secure storage with verification + backup.
    *
-   * Write order is critical:
-   *   1. Backup (BACKUP_PRIVATE_KEY + BACKUP_PUBLIC_KEY + BACKUP_TIMESTAMP)
-   *   2. Primary public key
-   *   3. Primary private key (last so a partial write leaves us in a known
-   *      "no identity yet" state — easier to retry than a half-written one)
-   *   4. Read back + sign/verify to confirm the storage round-trip works
+   * INVARIANT (the reason this method exists): at no instant during the write
+   * may the device be left holding ZERO recoverable copies of a healthy
+   * identity. This matters most on the OVERWRITE / account-switch path: if we
+   * are replacing identity A with B and the write fails halfway, we MUST end
+   * up back on A — never on a half-written B, and never on nothing.
    *
-   * If any step throws, the caller sees the error AND any partial state is
-   * cleaned up so the device is left either fully consistent or fully empty.
-   * It never leaves an unusable half-identity that would fool `hasIdentity()`.
+   * Algorithm (recoverability-preserving):
+   *   0. Snapshot the existing primary (privA, pubA) so we can roll back to
+   *      EXACTLY what was there.
+   *   1. Write the new primary: public first, then private.
+   *   2. Read back + sign/verify the new primary.
+   *   3. ONLY after the new primary is proven durable, refresh the backup to
+   *      the new key. The backup is NEVER touched before this point, so any
+   *      prior identity's backup remains intact and `restoreIdentityFromBackup`
+   *      can always recover it.
+   *   4. On ANY failure in steps 1–2, restore the snapshotted primary verbatim
+   *      (or delete it if there was none), then surface the error.
+   *
+   * Earlier versions wrote the *incoming* key to the backup FIRST, which
+   * destroyed the previous identity's backup, and rolled back by blindly
+   * deleting the primary — so a failed overwrite silently switched the user
+   * to (or lost them into) the half-written new identity. That is fixed here.
    *
    * @internal
    */
@@ -663,23 +675,64 @@ export class KeyManager {
     const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
     const canonicalPublic = publicKey.toLowerCase();
 
-    // Step 1: Backup BEFORE touching primary storage so we always have a
-    // recoverable copy even if the device crashes mid-write. Store the
-    // backup in canonical form too so a backup-restore cycle preserves
-    // canonicalization.
+    // Step 0: Snapshot the existing primary so a failed write can be rolled
+    // back to EXACTLY the prior state. If the read itself fails we treat the
+    // prior primary as unknown and refuse to proceed — overwriting blind
+    // would risk clobbering an identity we just couldn't see (e.g. a
+    // transient keychain lock).
+    let priorPrivate: string | null;
+    let priorPublic: string | null;
     try {
-      await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, canonicalPrivate, {
-        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-      });
-      await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, canonicalPublic);
-      await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+      priorPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+      priorPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
     } catch (error) {
-      logger.error('Failed to write identity backup before primary', error, { component: 'KeyManager' });
-      throw new IdentityPersistError('Failed to write identity backup', error);
+      logger.error('Failed to read existing primary before persist', error, { component: 'KeyManager' });
+      throw new IdentityPersistError(
+        'Could not read existing identity before writing a new one; refusing to overwrite blind.',
+        error,
+      );
     }
 
-    // Step 2 + 3: Write primary keys. Public first so that if private write
-    // fails we are still missing the most critical bit.
+    // If we are replacing a DIFFERENT, currently-healthy identity, make sure
+    // it is recoverable from the backup slot BEFORE we overwrite the primary.
+    // We only do this when the existing backup does not already hold that
+    // identity — otherwise we would needlessly churn the keychain. This keeps
+    // the "always at least one recoverable copy" invariant intact across the
+    // window where the primary briefly holds the new key but the new backup
+    // has not been written yet.
+    const priorIsHealthyDifferent =
+      !!priorPrivate &&
+      !!priorPublic &&
+      priorPublic.toLowerCase() !== canonicalPublic &&
+      KeyManager.isValidPrivateKey(priorPrivate) &&
+      KeyManager.isValidPublicKey(priorPublic) &&
+      KeyManager.derivePublicKey(priorPrivate).toLowerCase() === priorPublic.toLowerCase();
+
+    if (priorIsHealthyDifferent && priorPrivate && priorPublic) {
+      let existingBackupPublic: string | null = null;
+      try {
+        existingBackupPublic = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+      } catch {
+        existingBackupPublic = null;
+      }
+      if (existingBackupPublic?.toLowerCase() !== priorPublic.toLowerCase()) {
+        try {
+          await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, KeyManager.canonicalPrivateKey(priorPrivate), {
+            keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+          });
+          await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, priorPublic.toLowerCase());
+          await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+        } catch (error) {
+          logger.error('Failed to back up existing identity before overwrite', error, { component: 'KeyManager' });
+          throw new IdentityPersistError('Failed to back up existing identity before overwrite', error);
+        }
+      }
+    }
+
+    // Step 1: Write the new primary. Public first so that if the private write
+    // fails we are missing the most critical bit. The backup is intentionally
+    // NOT touched here — it still holds the previous good identity until the
+    // new primary is proven durable.
     try {
       await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, canonicalPublic);
       await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, {
@@ -687,13 +740,11 @@ export class KeyManager {
       });
     } catch (error) {
       logger.error('Failed to write primary identity to secure store', error, { component: 'KeyManager' });
-      // Roll back the public-key half-write so hasIdentity() doesn't lie later.
-      try { await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY); } catch { /* best effort */ }
-      try { await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY); } catch { /* best effort */ }
+      await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
       throw new IdentityPersistError('Failed to write identity to secure store', error);
     }
 
-    // Step 4: Verify round-trip. If the store silently drops our writes
+    // Step 2: Verify round-trip. If the store silently drops our writes
     // (e.g., a misconfigured keychain access group), we MUST surface it
     // before declaring success — otherwise the caller will think the
     // identity was saved and discard the in-memory copy.
@@ -704,6 +755,7 @@ export class KeyManager {
       readBackPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
     } catch (error) {
       logger.error('Failed to read identity back after write', error, { component: 'KeyManager' });
+      await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
       throw new IdentityPersistError('Failed to verify identity after write', error);
     }
 
@@ -715,6 +767,7 @@ export class KeyManager {
       readBackPublic?.toLowerCase() !== canonicalPublic
     ) {
       logger.error('Identity round-trip mismatch after write', undefined, { component: 'KeyManager' });
+      await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
       throw new IdentityPersistError('Identity write was not persisted correctly (round-trip mismatch).');
     }
 
@@ -735,16 +788,72 @@ export class KeyManager {
         throw new IdentityPersistError('Sign/verify roundtrip failed for newly stored identity.');
       }
     } catch (error) {
+      await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
       if (error instanceof IdentityPersistError) throw error;
       logger.error('Identity sign/verify probe failed', error, { component: 'KeyManager' });
       throw new IdentityPersistError('Stored identity failed crypto self-test', error);
     }
 
+    // Step 3: The new primary is durable and functional. NOW it is safe to
+    // refresh the backup to the new key. If this final backup write fails the
+    // user still has a fully working primary, and the backup still holds the
+    // PREVIOUS good identity — so we log and continue rather than failing the
+    // whole operation (failing here would be strictly worse: a working
+    // primary would be reported as an error to the caller).
+    try {
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, canonicalPrivate, {
+        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+      });
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, canonicalPublic);
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+    } catch (error) {
+      logger.warn(
+        'Primary identity persisted successfully but refreshing the backup failed; primary is usable, backup may be stale',
+        { component: 'KeyManager' },
+        error,
+      );
+    }
+
     // Update cache only after we are certain the identity is durable.
     KeyManager.cachedPublicKey = canonicalPublic;
     KeyManager.cachedHasIdentity = true;
   }
 
+  /**
+   * Restore the primary slot to a previously-snapshotted (privA, pubA) pair,
+   * or delete it entirely if there was no prior identity. Best-effort: every
+   * step is wrapped so a rollback failure never masks the original error the
+   * caller is about to throw. Invalidates the in-memory cache so the next read
+   * reflects whatever actually landed on disk.
+   *
+   * @internal
+   */
+  private static async _rollbackPrimary(
+    store: Awaited<ReturnType<typeof initSecureStore>>,
+    priorPrivate: string | null,
+    priorPublic: string | null,
+  ): Promise<void> {
+    try {
+      if (priorPrivate && priorPublic) {
+        // Restore exactly what was there before the failed write.
+        await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, priorPublic, {});
+        await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, priorPrivate, {
+          keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+      } else {
+        // There was no prior identity — leave the device empty rather than
+        // half-written so hasIdentity() does not lie.
+        try { await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY); } catch { /* best effort */ }
+        try { await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY); } catch { /* best effort */ }
+      }
+    } catch (rollbackError) {
+      logger.error('Failed to roll back primary identity after a failed write', rollbackError, { component: 'KeyManager' });
+    } finally {
+      // Whatever happened, the cached verdict is no longer trustworthy.
+      KeyManager.invalidateCache();
+    }
+  }
+
   /**
    * Generate and securely store a new key pair on the device.
    *
@@ -1122,17 +1231,23 @@ export class KeyManager {
   }
 
   /**
-   * Restore identity from backup if primary storage is corrupted.
+   * Restore identity from backup if primary storage is genuinely missing or
+   * corrupt.
    *
-   * SAFETY: this method will NEVER overwrite a verifying primary identity.
-   * If the primary passes a sign/verify probe, the backup is left untouched
-   * and `false` is returned — this protects against a transient
-   * `verifyIdentityIntegrity()` blip clobbering valid keys with stale
-   * backup keys (e.g., from a previous account before an import).
+   * SAFETY (three independent guards against silently switching accounts):
+   *   1. If the primary passes a full sign/verify probe, do nothing.
+   *   2. If the primary keys CANNOT BE READ (storage threw — e.g. a transient
+   *      keychain lock during a background launch), do nothing. We must NOT
+   *      treat "couldn't read" as "corrupted" and restore a possibly-stale
+   *      backup over an identity that is actually fine but momentarily
+   *      inaccessible.
+   *   3. If a primary private/public key IS present but does not match the
+   *      backup, the backup may belong to a different identity — refuse, so we
+   *      never silently switch the user to another account.
    *
-   * Additionally, if the backup public key does NOT match the (still-
-   * present-but-failing) primary public key, we refuse to overwrite — the
-   * backup may belong to a different identity entirely.
+   * Only when the primary is provably absent (read succeeded, returned
+   * null/empty) or provably corrupt (read succeeded, bytes malformed AND no
+   * conflicting key material is present) do we rebuild it from the backup.
    */
   static async restoreIdentityFromBackup(): Promise<boolean> {
     if (isWebPlatform()) {
@@ -1141,15 +1256,38 @@ export class KeyManager {
     try {
       const store = await initSecureStore();
 
-      // First: if the primary still works, do nothing. Returning true here
-      // would be misleading; returning false (no restore needed) is the
-      // honest answer.
-      const primaryOk = await KeyManager.verifyIdentityIntegrity();
-      if (primaryOk) {
+      // Read the primary DIRECTLY (not via the error-swallowing getters) so
+      // we can distinguish a transient read failure from a genuinely absent
+      // key. A thrown read here means the keychain is locked/unavailable —
+      // bail out and let a later call retry rather than risk restoring over a
+      // healthy-but-locked identity.
+      let primaryPrivate: string | null;
+      let primaryPublic: string | null;
+      try {
+        primaryPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+        primaryPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+      } catch (error) {
+        logger.warn(
+          'restoreIdentityFromBackup: could not read primary (transient?). Refusing to restore.',
+          { component: 'KeyManager' },
+          error,
+        );
         return false;
       }
 
-      // Check if backup exists
+      // If the primary reads back as a complete, self-consistent identity, it
+      // is healthy — nothing to restore. (Guard 1.)
+      if (primaryPrivate && primaryPublic) {
+        if (
+          KeyManager.isValidPrivateKey(primaryPrivate) &&
+          KeyManager.isValidPublicKey(primaryPublic) &&
+          KeyManager.derivePublicKey(primaryPrivate).toLowerCase() === primaryPublic.toLowerCase()
+        ) {
+          return false;
+        }
+      }
+
+      // Load + validate the backup.
       const backupPrivateKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
       const backupPublicKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
 
@@ -1157,7 +1295,6 @@ export class KeyManager {
         return false; // No backup available
       }
 
-      // Verify backup integrity
       if (!KeyManager.isValidPrivateKey(backupPrivateKey) || !KeyManager.isValidPublicKey(backupPublicKey)) {
         logger.warn('Backup identity is malformed; refusing to restore', { component: 'KeyManager' });
         return false;
@@ -1172,17 +1309,30 @@ export class KeyManager {
         return false;
       }
 
-      // CRITICAL: if there is still a (broken) primary public key present
-      // that does NOT match the backup, the backup may be from a completely
-      // different identity. Better to surface a corrupted state than
-      // silently switch the user to a different account.
-      const currentPrimaryPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY).catch(() => null);
+      // Guard 3: if ANY primary key material is still present and identifies a
+      // DIFFERENT identity than the backup, refuse — the backup may be from a
+      // completely different account and restoring it would silently switch
+      // the user. We check the private key too (not just the public): a
+      // present private key that derives to a non-backup public means a real,
+      // different identity is sitting in the primary slot.
+      if (
+        primaryPublic &&
+        primaryPublic.toLowerCase() !== backupPublicKey.toLowerCase()
+      ) {
+        logger.error(
+          'Primary public key is present, corrupt-or-mismatched, AND differs from the backup. Refusing to restore to avoid switching accounts.',
+          undefined,
+          { component: 'KeyManager' },
+        );
+        return false;
+      }
       if (
-        currentPrimaryPublic &&
-        currentPrimaryPublic.toLowerCase() !== backupPublicKey.toLowerCase()
+        primaryPrivate &&
+        KeyManager.isValidPrivateKey(primaryPrivate) &&
+        KeyManager.derivePublicKey(primaryPrivate).toLowerCase() !== backupPublicKey.toLowerCase()
       ) {
         logger.error(
-          'Primary identity is corrupted AND does not match the backup. Refusing to restore to avoid switching accounts.',
+          'Primary private key identifies a DIFFERENT identity than the backup. Refusing to restore to avoid switching accounts.',
           undefined,
           { component: 'KeyManager' },
         );

package/src/mixins/OxyServices.fedcm.ts

@@ -109,7 +109,10 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     try {
-      const nonce = options.nonce || this.generateNonce();
+      // Prefer a server-minted, origin-bound nonce so the downstream
+      // `/fedcm/exchange` can validate it. A caller-supplied nonce is
+      // respected as-is for advanced use cases.
+      const nonce = options.nonce || (await this.getFedcmNonce());
       const clientId = this.getClientId();
 
       // Use provided loginHint, or fall back to stored last-used account ID
@@ -219,7 +222,9 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     const loginHint = this.getStoredLoginHint();
 
     try {
-      const nonce = this.generateNonce();
+      // Server-minted, origin-bound nonce — required for `/fedcm/exchange`
+      // to accept the resulting ID token (anti-replay binding).
+      const nonce = await this.getFedcmNonce();
       debug.log('Silent SSO: Attempting silent mediation...', loginHint ? `(hint: ${loginHint})` : '');
 
       credential = await this.requestIdentityCredential({
@@ -494,7 +499,14 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
   }
 
   /**
-   * Generate a cryptographically secure nonce for FedCM
+   * Generate a cryptographically secure local nonce for FedCM.
+   *
+   * NOTE: this is a *local* fallback only. The server-side `/fedcm/exchange`
+   * endpoint requires the nonce embedded in the ID token to have been minted
+   * by `POST /fedcm/nonce` (see {@link mintServerNonce}) and bound to this
+   * origin. A purely local nonce will be rejected with `invalid_nonce`. Use
+   * {@link getFedcmNonce}, which prefers a server-minted nonce and only falls
+   * back to this generator when the mint endpoint is unreachable.
    *
    * @private
    */
@@ -510,6 +522,58 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     throw new Error('No secure random source available for nonce generation');
   }
 
+  /**
+   * Mint a single-use, origin-bound nonce from the Oxy API.
+   *
+   * The FedCM ID token issued by the IdP embeds this nonce as the `nonce`
+   * claim. When the consuming app calls `POST /fedcm/exchange`, the API burns
+   * the nonce (atomic `usedAt` transition) and verifies it was minted for the
+   * same origin as the token `aud`. This is the anti-replay binding required
+   * by the API's H9 hardening — without a server-minted nonce the exchange
+   * always fails.
+   *
+   * The browser attaches the `Origin` header automatically on this
+   * cross-origin request, so the API binds the nonce to the calling app's
+   * origin (which also becomes the FedCM `clientId`/token `aud`).
+   *
+   * @private
+   */
+  public async mintServerNonce(): Promise<string> {
+    const result = await this.makeRequest<{ nonce: string; expiresAt: string }>(
+      'POST',
+      '/fedcm/nonce',
+      {},
+      { cache: false }
+    );
+    if (!result?.nonce) {
+      throw new OxyAuthenticationError('FedCM nonce endpoint returned no nonce');
+    }
+    return result.nonce;
+  }
+
+  /**
+   * Resolve the nonce to use for a FedCM credential request.
+   *
+   * Prefers a server-minted, origin-bound nonce (required for the token
+   * exchange to succeed). If the mint endpoint is unreachable we fall back to
+   * a locally generated nonce so the browser flow can still proceed; the
+   * exchange may then fail server-side, but that is strictly better than
+   * throwing before the browser ever shows its UI.
+   *
+   * @private
+   */
+  public async getFedcmNonce(): Promise<string> {
+    try {
+      return await this.mintServerNonce();
+    } catch (error) {
+      debug.warn(
+        'Could not mint server nonce, falling back to local nonce:',
+        error instanceof Error ? error.message : String(error)
+      );
+      return this.generateNonce();
+    }
+  }
+
   /**
    * Get the client ID for this origin
    *

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

@@ -0,0 +1,187 @@
+/**
+ * FedCM mixin regression tests.
+ *
+ * Locks in the fix for the broken SSO token exchange: the API's H9 hardening
+ * (commit 21af7c48) made `/fedcm/exchange` require a server-minted,
+ * origin-bound nonce, but the SDK was still generating a purely local nonce
+ * that the API always rejected with `invalid_nonce`. These tests assert that
+ * both the silent and interactive FedCM flows now:
+ *
+ *   1. mint a nonce from `POST /fedcm/nonce` and pass THAT nonce (not a local
+ *      UUID) to `navigator.credentials.get`;
+ *   2. fall back to a local nonce if the mint endpoint is unreachable, rather
+ *      than throwing before the browser UI can show;
+ *   3. resolve silent SSO cleanly to `null` (never throw into a retry loop)
+ *      when the browser returns no credential or rejects the request.
+ *
+ * The browser globals (`window`, `navigator.credentials`, `IdentityCredential`)
+ * are stubbed so the platform-agnostic mixin can run under the node test env.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+interface CredentialGetCall {
+  identity: {
+    providers: Array<{ configURL: string; clientId: string; nonce: string; params?: { nonce?: string } }>;
+    mode?: string;
+  };
+  mediation: string;
+}
+
+const ORIGIN = 'https://accounts.oxy.so';
+
+function installBrowserGlobals(options: {
+  credentialsGet: (opts: CredentialGetCall) => Promise<unknown>;
+}): void {
+  const store = new Map<string, string>();
+  const localStorageStub = {
+    getItem: (k: string) => (store.has(k) ? (store.get(k) as string) : null),
+    setItem: (k: string, v: string) => { store.set(k, v); },
+    removeItem: (k: string) => { store.delete(k); },
+  };
+  const nav = {
+    credentials: {
+      get: (opts: CredentialGetCall) => options.credentialsGet(opts),
+    },
+  };
+  // `isFedCMSupported()` checks: 'IdentityCredential' in window &&
+  // 'navigator' in window && 'credentials' in navigator. The stub must expose
+  // all three the way a real browser does.
+  const win = {
+    location: { origin: ORIGIN, hostname: 'accounts.oxy.so' },
+    IdentityCredential: function IdentityCredential() {},
+    navigator: nav,
+    localStorage: localStorageStub,
+  };
+  (globalThis as unknown as { window: unknown }).window = win;
+  (globalThis as unknown as { navigator: unknown }).navigator = nav;
+  (globalThis as unknown as { localStorage: unknown }).localStorage = localStorageStub;
+  (globalThis as unknown as { IdentityCredential: unknown }).IdentityCredential = win.IdentityCredential;
+}
+
+function clearBrowserGlobals(): void {
+  for (const key of ['window', 'navigator', 'localStorage', 'IdentityCredential'] as const) {
+    delete (globalThis as Record<string, unknown>)[key];
+  }
+}
+
+describe('OxyServices FedCM nonce binding', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('silent SSO mints a server nonce and forwards it to the browser', async () => {
+    let credentialCall: CredentialGetCall | null = null;
+    installBrowserGlobals({
+      credentialsGet: async (opts) => {
+        credentialCall = opts;
+        // Browser returns no credential (user not logged in at IdP)
+        return null;
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const makeRequest = jest
+      .spyOn(oxy, 'makeRequest')
+      .mockImplementation(async (_method: string, url: string) => {
+        if (url === '/fedcm/nonce') {
+          return { nonce: 'server-minted-nonce-123', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+        }
+        throw new Error(`unexpected request to ${url}`);
+      });
+
+    const result = await oxy.silentSignInWithFedCM();
+
+    expect(result).toBeNull();
+    // The mint endpoint was hit
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/fedcm/nonce', {}, { cache: false });
+    // The server nonce — not a random UUID — was passed to the browser
+    expect(credentialCall).not.toBeNull();
+    const call = credentialCall as unknown as CredentialGetCall;
+    expect(call.identity.providers[0].nonce).toBe('server-minted-nonce-123');
+    expect(call.identity.providers[0].params?.nonce).toBe('server-minted-nonce-123');
+    expect(call.mediation).toBe('silent');
+  });
+
+  it('interactive sign-in mints a server nonce and exchanges the returned token', async () => {
+    installBrowserGlobals({
+      credentialsGet: async () => ({ type: 'identity', token: 'idp-id-token', isAutoSelected: false }),
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const exchanged: string[] = [];
+    jest
+      .spyOn(oxy, 'makeRequest')
+      .mockImplementation(async (_method: string, url: string, data?: unknown) => {
+        if (url === '/fedcm/nonce') {
+          return { nonce: 'server-minted-nonce-xyz', 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_1',
+            deviceId: 'dev_1',
+            expiresAt: new Date(Date.now() + 60000).toISOString(),
+            accessToken: 'access_1',
+            user: { id: 'user_1', username: 'tester' },
+          } as never;
+        }
+        throw new Error(`unexpected request to ${url}`);
+      });
+
+    const session = await oxy.signInWithFedCM();
+
+    expect(session.sessionId).toBe('sess_1');
+    // The browser-issued token was exchanged for a session
+    expect(exchanged).toEqual(['idp-id-token']);
+  });
+
+  it('falls back to a local nonce when the mint endpoint is unreachable', 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') {
+        throw new Error('network down');
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const result = await oxy.silentSignInWithFedCM();
+
+    // Did not throw; resolved cleanly to null
+    expect(result).toBeNull();
+    // Still passed a (locally generated) non-empty nonce to the browser
+    expect(credentialCall).not.toBeNull();
+    const call = credentialCall as unknown as CredentialGetCall;
+    expect(typeof call.identity.providers[0].nonce).toBe('string');
+    expect(call.identity.providers[0].nonce.length).toBeGreaterThan(0);
+  });
+
+  it('silent SSO resolves to null (no throw) when the browser rejects', async () => {
+    installBrowserGlobals({
+      credentialsGet: async () => {
+        const err = new Error('User not signed in');
+        err.name = 'NotAllowedError';
+        throw err;
+      },
+    });
+
+    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 expect(oxy.silentSignInWithFedCM()).resolves.toBeNull();
+  });
+});