@oxyhq/core 2.4.0 → 3.0.0

package/src/mixins/OxyServices.applications.ts

@@ -0,0 +1,511 @@
+/**
+ * Applications Methods Mixin
+ *
+ * Provides methods for managing Oxy applications, their members, and their
+ * credentials via the `/applications` API. An application is a multi-user
+ * entity: membership (with a role) grants permissions; credentials
+ * (public/confidential/service) carry OAuth client identifiers and the
+ * service-token API key material.
+ *
+ * Reference applications by their Mongo `_id` (`applicationId`) and credentials
+ * by their `credentialId`. Never by name.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import { CACHE_TIMES } from './mixinHelpers';
+
+/**
+ * Application classification. Set only by Oxy platform staff — never editable
+ * through the normal member-facing update path.
+ */
+export type ApplicationType = 'first_party' | 'third_party' | 'internal' | 'system';
+
+/** Lifecycle status of an application. */
+export type ApplicationStatus = 'active' | 'suspended' | 'deleted' | 'pending_review';
+
+/** Role a member holds within an application. */
+export type ApplicationRole = 'owner' | 'admin' | 'developer' | 'viewer' | 'billing';
+
+/** Membership lifecycle status. */
+export type ApplicationMemberStatus = 'active' | 'invited' | 'removed';
+
+/** Credential kind. `service` credentials mint service tokens. */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service';
+
+/** Deployment environment a credential is scoped to. */
+export type ApplicationEnvironment = 'development' | 'staging' | 'production';
+
+/** Credential lifecycle status. */
+export type ApplicationCredentialStatus = 'active' | 'deprecated' | 'revoked';
+
+/**
+ * Client-facing Application shape returned by the `/applications` API.
+ * Mirrors the server `Application` model with `_id` as a string and dates
+ * serialized to ISO strings.
+ */
+export interface Application {
+  _id: string;
+  name: string;
+  description?: string;
+  websiteUrl?: string;
+  icon?: string;
+  type: ApplicationType;
+  status: ApplicationStatus;
+  isOfficial: boolean;
+  isInternal: boolean;
+  capabilities: string[];
+  redirectUris: string[];
+  scopes: string[];
+  webhookUrl?: string;
+  devWebhookUrl?: string;
+  createdByUserId: string;
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * The calling user's own membership in this application, embedded by the API
+   * on list (`GET /applications`) and detail (`GET /applications/:appId`)
+   * responses. Use `callerMembership.permissions` to gate UI affordances.
+   */
+  callerMembership?: ApplicationMember;
+}
+
+/**
+ * Client-facing ApplicationMember shape. `permissions` is derived from `role`
+ * on the server at write time.
+ */
+export interface ApplicationMember {
+  _id: string;
+  applicationId: string;
+  userId: string;
+  role: ApplicationRole;
+  permissions: string[];
+  invitedByUserId?: string;
+  joinedAt?: string;
+  status: ApplicationMemberStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Client-facing ApplicationCredential shape. The raw secret is NEVER part of
+ * this shape — it is returned exactly once, separately, at creation/rotation.
+ */
+export interface ApplicationCredential {
+  _id: string;
+  applicationId: string;
+  name: string;
+  publicKey: string;
+  type: ApplicationCredentialType;
+  environment: ApplicationEnvironment;
+  scopes: string[];
+  status: ApplicationCredentialStatus;
+  lastUsedAt?: string;
+  expiresAt?: string;
+  createdByUserId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Input accepted by `createApplication`. Staff-only fields are not settable here. */
+export interface CreateApplicationInput {
+  name: string;
+  description?: string;
+  websiteUrl?: string;
+  icon?: string;
+  redirectUris?: string[];
+  scopes?: string[];
+}
+
+/** Input accepted by `updateApplication`. Staff-only fields are not settable here. */
+export interface UpdateApplicationInput {
+  name?: string;
+  description?: string;
+  websiteUrl?: string;
+  icon?: string;
+  redirectUris?: string[];
+  scopes?: string[];
+  webhookUrl?: string;
+  devWebhookUrl?: string;
+  status?: ApplicationStatus;
+}
+
+/** Input accepted by `inviteApplicationMember`. The owner role cannot be invited. */
+export interface InviteApplicationMemberInput {
+  userId: string;
+  role: Exclude<ApplicationRole, 'owner'>;
+}
+
+/** Input accepted by `updateApplicationMember`. */
+export interface UpdateApplicationMemberInput {
+  role: ApplicationRole;
+}
+
+/** Input accepted by `transferApplicationOwnership`. */
+export interface TransferApplicationOwnershipInput {
+  userId: string;
+}
+
+/** Input accepted by `createApplicationCredential`. */
+export interface CreateApplicationCredentialInput {
+  name: string;
+  type: ApplicationCredentialType;
+  environment: ApplicationEnvironment;
+  scopes?: string[];
+}
+
+/** Result of creating or rotating a credential — `secret` is returned ONCE. */
+export interface ApplicationCredentialWithSecret {
+  credential: ApplicationCredential;
+  secret: string;
+}
+
+/** Time window for application usage statistics. */
+export type ApplicationUsagePeriod = '24h' | '7d' | '30d' | '90d';
+
+/** Aggregate totals for an application over the requested period. */
+export interface ApplicationUsageSummary {
+  totalRequests: number;
+  totalTokens: number;
+  totalCredits: number;
+  avgResponseTime: number;
+  successfulRequests: number;
+  errorRequests: number;
+}
+
+/** Per-day usage bucket. `_id` is the day key (e.g. `YYYY-MM-DD`). */
+export interface ApplicationUsageByDay {
+  _id: string;
+  requests: number;
+  tokens: number;
+  credits: number;
+}
+
+/** Per-endpoint usage bucket. `_id` is the endpoint identifier. */
+export interface ApplicationUsageByEndpoint {
+  _id: string;
+  requests: number;
+  tokens: number;
+}
+
+/** Usage statistics for an application over a period. */
+export interface ApplicationUsageStats {
+  summary: ApplicationUsageSummary;
+  byDay: ApplicationUsageByDay[];
+  byEndpoint: ApplicationUsageByEndpoint[];
+}
+
+/** Result of a delete/remove/revoke/transfer operation. */
+export interface ApplicationSuccessResult {
+  success: boolean;
+}
+
+export function OxyServicesApplicationsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * List applications the current user is an active member of.
+     */
+    async getApplications(): Promise<Application[]> {
+      try {
+        const res = await this.makeRequest<{ applications?: Application[] }>(
+          'GET',
+          '/applications',
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.applications ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a new application. The caller becomes its `owner`.
+     * @param data - Application configuration. Staff-only fields are ignored.
+     */
+    async createApplication(data: CreateApplicationInput): Promise<Application> {
+      try {
+        const res = await this.makeRequest<{ application: Application }>(
+          'POST',
+          '/applications',
+          data,
+          { cache: false },
+        );
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Fetch a single application by id.
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async getApplication(applicationId: string): Promise<Application> {
+      try {
+        const res = await this.makeRequest<{ application: Application }>(
+          'GET',
+          `/applications/${applicationId}`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.LONG },
+        );
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update an application's mutable fields.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param data - Subset of updatable fields. Staff-only fields are ignored.
+     */
+    async updateApplication(
+      applicationId: string,
+      data: UpdateApplicationInput,
+    ): Promise<Application> {
+      try {
+        const res = await this.makeRequest<{ application: Application }>(
+          'PATCH',
+          `/applications/${applicationId}`,
+          data,
+          { cache: false },
+        );
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Soft-delete an application (owner only).
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async deleteApplication(applicationId: string): Promise<ApplicationSuccessResult> {
+      try {
+        return await this.makeRequest<ApplicationSuccessResult>(
+          'DELETE',
+          `/applications/${applicationId}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * List members of an application.
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async getApplicationMembers(applicationId: string): Promise<ApplicationMember[]> {
+      try {
+        const res = await this.makeRequest<{ members?: ApplicationMember[] }>(
+          'GET',
+          `/applications/${applicationId}/members`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.members ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Add a member to an application.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param data - Target user id and role (never `owner`).
+     */
+    async inviteApplicationMember(
+      applicationId: string,
+      data: InviteApplicationMemberInput,
+    ): Promise<ApplicationMember> {
+      try {
+        const res = await this.makeRequest<{ member: ApplicationMember }>(
+          'POST',
+          `/applications/${applicationId}/members`,
+          data,
+          { cache: false },
+        );
+        return res.member;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Change a member's role.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param memberId - The member's Mongo `_id`.
+     * @param data - New role.
+     */
+    async updateApplicationMember(
+      applicationId: string,
+      memberId: string,
+      data: UpdateApplicationMemberInput,
+    ): Promise<ApplicationMember> {
+      try {
+        const res = await this.makeRequest<{ member: ApplicationMember }>(
+          'PATCH',
+          `/applications/${applicationId}/members/${memberId}`,
+          data,
+          { cache: false },
+        );
+        return res.member;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Remove a member from an application.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param memberId - The member's Mongo `_id`.
+     */
+    async removeApplicationMember(
+      applicationId: string,
+      memberId: string,
+    ): Promise<ApplicationSuccessResult> {
+      try {
+        return await this.makeRequest<ApplicationSuccessResult>(
+          'DELETE',
+          `/applications/${applicationId}/members/${memberId}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Transfer ownership of an application to another member (owner only).
+     * Demotes the current owner to `admin` and promotes the target to `owner`.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param data - Target user id.
+     */
+    async transferApplicationOwnership(
+      applicationId: string,
+      data: TransferApplicationOwnershipInput,
+    ): Promise<ApplicationSuccessResult> {
+      try {
+        return await this.makeRequest<ApplicationSuccessResult>(
+          'POST',
+          `/applications/${applicationId}/transfer-ownership`,
+          data,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * List an application's credentials. The response NEVER includes secrets.
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async getApplicationCredentials(applicationId: string): Promise<ApplicationCredential[]> {
+      try {
+        const res = await this.makeRequest<{ credentials?: ApplicationCredential[] }>(
+          'GET',
+          `/applications/${applicationId}/credentials`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.credentials ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a credential. The plaintext `secret` is returned exactly ONCE;
+     * the server stores only a hash and will never return it again.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param data - Credential configuration.
+     */
+    async createApplicationCredential(
+      applicationId: string,
+      data: CreateApplicationCredentialInput,
+    ): Promise<ApplicationCredentialWithSecret> {
+      try {
+        return await this.makeRequest<ApplicationCredentialWithSecret>(
+          'POST',
+          `/applications/${applicationId}/credentials`,
+          data,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Rotate a credential's secret. The new plaintext `secret` is returned
+     * exactly ONCE.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param credentialId - The credential's Mongo `_id`.
+     */
+    async rotateApplicationCredential(
+      applicationId: string,
+      credentialId: string,
+    ): Promise<ApplicationCredentialWithSecret> {
+      try {
+        return await this.makeRequest<ApplicationCredentialWithSecret>(
+          'POST',
+          `/applications/${applicationId}/credentials/${credentialId}/rotate`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Revoke a credential (`status='revoked'`). Revoked credentials can no
+     * longer authenticate.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param credentialId - The credential's Mongo `_id`.
+     */
+    async revokeApplicationCredential(
+      applicationId: string,
+      credentialId: string,
+    ): Promise<ApplicationSuccessResult> {
+      try {
+        return await this.makeRequest<ApplicationSuccessResult>(
+          'DELETE',
+          `/applications/${applicationId}/credentials/${credentialId}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Fetch usage statistics for an application.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param period - Time window (defaults to the server default).
+     */
+    async getApplicationUsage(
+      applicationId: string,
+      period?: ApplicationUsagePeriod,
+    ): Promise<ApplicationUsageStats> {
+      try {
+        return await this.makeRequest<ApplicationUsageStats>(
+          'GET',
+          `/applications/${applicationId}/usage`,
+          period ? { period } : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.auth.ts

@@ -157,8 +157,8 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * legitimate multi-tenant hosts that need to switch credentials cannot leak
      * one tenant's token to another tenant on the same instance.
      *
-     * @param apiKey - DeveloperApp API key (oxy_dk_*)
-     * @param apiSecret - DeveloperApp API secret
+     * @param apiKey - Application credential public key (oxy_dk_*)
+     * @param apiSecret - Application credential secret
      */
     configureServiceAuth(apiKey: string, apiSecret: string): void {
       this._serviceApiKey = apiKey;
@@ -181,8 +181,8 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * This prevents an attacker who learned a peer's apiKey from extracting
      * their service token by polling with a wrong secret.
      *
-     * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
-     * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
+     * @param apiKey - Application credential public key (optional if configureServiceAuth was called)
+     * @param apiSecret - Application credential secret (optional if configureServiceAuth was called)
      */
     async getServiceToken(apiKey?: string, apiSecret?: string): Promise<string> {
       const key = apiKey || this._serviceApiKey;

package/src/mixins/OxyServices.fedcm.ts

@@ -214,6 +214,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
   // 20-30s cold-boot stall. Do NOT lower below 4s (it would clip live success).
   public static readonly FEDCM_SILENT_TIMEOUT = 4000; // 4 seconds for silent mediation
 
+  // Grace margin between the cooperative abort deadline (`FEDCM_SILENT_TIMEOUT`
+  // / `FEDCM_TIMEOUT`) and the HARD settle of `requestIdentityCredential`. The
+  // abort fires first; a well-behaved browser surfaces its own `AbortError`
+  // within this window (keeping the existing error path intact). If — as seen
+  // in production — `navigator.credentials.get()` ignores the abort and the
+  // awaited promise never settles, the hard settle resolves the request to
+  // `null` this many ms later, guaranteeing the cold-boot step always settles.
+  // 500ms is ample for a browser to deliver an abort rejection while keeping the
+  // worst-case dead wait tight (silent: 4.5s, interactive: 15.5s).
+  public static readonly FEDCM_ABORT_SETTLE_GRACE_MS = 500;
+
   /**
    * Check if FedCM is supported in the current browser
    */
@@ -606,6 +617,37 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       controller.abort();
     }, timeoutMs);
 
+    // Hard settle guarantee for the timeout path.
+    //
+    // The `setTimeout` above aborts the request's `AbortController`, which is
+    // the COOPERATIVE cancel signal. For a regular `fetch` an abort deterministically
+    // rejects the awaited promise — but `navigator.credentials.get()` is a
+    // browser-internal FedCM primitive whose abort behaviour is NOT guaranteed
+    // to settle the awaited promise in every Chrome version / internal state
+    // (the credential request can sit "pending" while the browser-side flow is
+    // stuck, ignoring the signal). If that happens, `await credentials.get(...)`
+    // never resolves OR rejects, this IIFE hangs forever, and — because this is
+    // ONE step of the ordered cold-boot sequence — the whole cold boot hangs and
+    // the terminal `/sso` bounce never fires. That was the production hang.
+    //
+    // `settlePromise` races the credential lookup against a timer that ALWAYS
+    // resolves to `null` shortly after the abort deadline. The abort still fires
+    // first (so the browser is asked to cancel), but even if `credentials.get`
+    // never settles, the race resolves and the step falls through cleanly to the
+    // next cold-boot step. The small `FEDCM_ABORT_SETTLE_GRACE_MS` margin gives a
+    // well-behaved browser the chance to surface its own AbortError (preserving
+    // the existing error path) before we force a clean `null`.
+    let settleTimer: ReturnType<typeof setTimeout> | undefined;
+    const settlePromise = new Promise<FedCMIdentityCredential | null>((resolve) => {
+      const ctor = this.constructor as typeof OxyServicesBase & {
+        FEDCM_ABORT_SETTLE_GRACE_MS: number;
+      };
+      settleTimer = setTimeout(() => {
+        debug.log('Request hard-settled to null', timeoutMs + ctor.FEDCM_ABORT_SETTLE_GRACE_MS, 'ms (credentials.get never settled after abort)');
+        resolve(null);
+      }, timeoutMs + ctor.FEDCM_ABORT_SETTLE_GRACE_MS);
+    });
+
     // 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.
@@ -645,7 +687,13 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         debug.log('Calling navigator.credentials.get with mediation:', requestedMediation, modernMode ? `mode: ${modernMode}` : '');
         let credential: FedCMIdentityCredential | null;
         try {
-          credential = await credentials.get(buildCredentialOptions(modernMode));
+          // Race the browser FedCM lookup against the hard settle guarantee so
+          // a `credentials.get` that ignores the abort signal can never hang
+          // the cold boot (see `settlePromise`).
+          credential = await Promise.race([
+            credentials.get(buildCredentialOptions(modernMode)),
+            settlePromise,
+          ]);
         } catch (modeError) {
           // Chrome 125–131 only knows the legacy 'button'/'widget' enum and
           // throws a synchronous TypeError for the modern 'active'/'passive'
@@ -653,7 +701,10 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
           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));
+            credential = await Promise.race([
+              credentials.get(buildCredentialOptions(legacyMode)),
+              settlePromise,
+            ]);
           } else {
             throw modeError;
           }
@@ -680,6 +731,9 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         throw error;
       } finally {
         clearTimeout(timeout);
+        if (settleTimer !== undefined) {
+          clearTimeout(settleTimer);
+        }
         // Only reset the shared lock if it still belongs to THIS request. When an
         // interactive request aborts a slow silent one, the silent settles (and
         // runs this `finally`) AFTER the interactive has already taken over the

package/src/mixins/OxyServices.utility.ts

@@ -54,7 +54,7 @@ export interface ServiceActingAsVerification {
 /**
  * Service app metadata attached to requests authenticated with service tokens.
  * `scopes` reflects the scopes granted to the app at signup time (from the
- * `DeveloperApp.scopes` field); route-level checks can require additional
+ * `Application.scopes` field); route-level checks can require additional
  * scope-narrowing via `requireScope()`.
  */
 export interface ServiceApp {

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

@@ -192,6 +192,58 @@ describe('OxyServices FedCM nonce binding', () => {
 
     await expect(oxy.silentSignInWithFedCM()).resolves.toBeNull();
   });
+
+  /**
+   * Production-hang regression. `navigator.credentials.get()` is a
+   * browser-internal FedCM primitive that, in some Chrome states, IGNORES its
+   * abort signal — the awaited promise never settles. The cooperative
+   * `setTimeout`→`controller.abort()` alone cannot unblock that await, so the
+   * `fedcm-silent` cold-boot step (and the whole cold boot) hangs forever and
+   * the terminal `/sso` bounce never fires.
+   *
+   * The hard settle guarantee (`Promise.race` against a timer that resolves
+   * `null` at `FEDCM_SILENT_TIMEOUT + FEDCM_ABORT_SETTLE_GRACE_MS`) must resolve
+   * the request to `null` regardless. This test models the hung primitive and
+   * asserts `silentSignInWithFedCM()` settles to `null` within that bound.
+   */
+  it('hard-settles to null when navigator.credentials.get never settles (ignores abort)', async () => {
+    jest.useFakeTimers();
+    try {
+      installBrowserGlobals({
+        // Never resolves or rejects, and never observes the abort signal —
+        // models the production hung FedCM credential request.
+        credentialsGet: () => new Promise<unknown>(() => {}),
+      });
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      localStorage.setItem('oxy_fedcm_login_hint', 'prior-user-id');
+      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}`);
+      });
+
+      let settled = false;
+      const promise = oxy.silentSignInWithFedCM().then((r) => {
+        settled = true;
+        return r;
+      });
+
+      // Before the hard-settle deadline it must still be pending — proving the
+      // primitive really is hung (so the test would fail without the fix).
+      await jest.advanceTimersByTimeAsync(4000);
+      expect(settled).toBe(false);
+
+      // FEDCM_SILENT_TIMEOUT (4000) + FEDCM_ABORT_SETTLE_GRACE_MS (500) = 4500.
+      await jest.advanceTimersByTimeAsync(600);
+      await expect(promise).resolves.toBeNull();
+      expect(settled).toBe(true);
+    } finally {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    }
+  });
 });
 
 /**