@oxyhq/core 15.0.0 → 16.0.0

package/dist/types/OxyServices.d.ts

@@ -57,7 +57,7 @@
  * See method JSDoc for more details and options.
  */
 import { type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
-import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
 import { composeOxyServices } from './mixins';
 /**
  * OxyServices - Unified client library for interacting with the Oxy API
@@ -121,7 +121,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
     assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
 }
-export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError };
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
 /**
  * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
  */

package/dist/types/OxyServices.errors.d.ts

@@ -46,6 +46,39 @@ export declare class AssetUrlResolutionError extends Error {
     readonly cause?: unknown;
     constructor(fileId: string, variant: string | undefined, status: number | undefined, cause?: unknown);
 }
+/**
+ * Thrown when one or more chunks of `getServiceAssetMetadataByIds` could not be
+ * resolved.
+ *
+ * Exists because for this endpoint a FAILED request and an ABSENT asset produce
+ * the same observable result. The server legitimately omits unknown/deleted ids,
+ * so callers are documented to map the response by `id` and treat a missing
+ * entry as "no such asset" — which means a chunk that 429s, times out or 5xxs
+ * reads as authoritative absence unless it is raised.
+ *
+ * That was not hypothetical: a metadata backfill counted every throttled asset
+ * as needing no update and exited 0, and the MTN signed-record builder embedded
+ * media with no content hash into records that are immutable once signed. Both
+ * paths reported success and wrote nothing.
+ *
+ * `unresolvedIds` carries every id in a failed chunk — not the subset the server
+ * would have omitted anyway, which is unknowable when the request never landed.
+ * A caller that wants best-effort passes `{ partial: true }` and never sees this.
+ */
+export declare class ServiceAssetMetadataError extends Error {
+    readonly code = "SERVICE_ASSET_METADATA_UNRESOLVED";
+    /** Every id belonging to a chunk whose request failed. */
+    readonly unresolvedIds: string[];
+    /** HTTP statuses observed across the failed chunks (deduped, ascending). */
+    readonly statuses: number[];
+    /**
+     * The first underlying transport/API failure. Declared on the class rather
+     * than relying on `Error.cause` because this package targets ES2020, where
+     * `cause` is not part of the `Error` type.
+     */
+    readonly cause?: unknown;
+    constructor(unresolvedIds: string[], statuses: number[], cause?: unknown);
+}
 export declare class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     constructor(operationName: string, timeoutMs: number);
 }

package/dist/types/index.d.ts

@@ -17,7 +17,7 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 import './crypto/polyfill';
-export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
+export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';

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

@@ -160,15 +160,27 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * throws because no credentials are available. A plain user-session request
          * is rejected by the route's service-auth guard.
          *
-         * Resilience: chunks are independent. A failed chunk is logged and skipped —
-         * the method returns every entry that resolved successfully rather than
-         * discarding the whole call on one chunk's failure. An empty/whitespace-only
-         * input resolves immediately with `[]` and performs no network call.
+         * FAILURE IS NOT ABSENCE. The server legitimately omits unknown/deleted ids,
+         * so a short result is normal — which means a chunk that FAILED (a 429, a
+         * timeout, a 5xx) is indistinguishable from "those assets don't exist" if it
+         * simply contributes nothing. This method used to swallow a failed chunk and
+         * return the rest, so every caller silently read a throttled request as "no
+         * metadata": a backfill counted the asset as needing no update, and the
+         * signed-record builder embedded a media item with no hash. Both reported
+         * success while writing nothing, and the MTN chain's records are immutable.
+         *
+         * So a failed chunk THROWS {@link ServiceAssetMetadataError} by default,
+         * carrying the ids it could not resolve. A caller that genuinely wants
+         * best-effort opts in with `{ partial: true }` and gets the old behaviour
+         * explicitly. An empty/whitespace-only input resolves immediately with `[]`
+         * and performs no network call.
          *
          * Not cached at the SDK layer: it's a POST keyed on a multi-id body (low hit
          * rate), mirroring the sibling service/POST methods which never cache.
          */
-        getServiceAssetMetadataByIds(ids: string[]): Promise<ServiceAssetMetadata[]>;
+        getServiceAssetMetadataByIds(ids: string[], options?: {
+            partial?: boolean;
+        }): Promise<ServiceAssetMetadata[]>;
         /**
          * Reverse content-address lookup: resolve many content `sha256` digests to
          * the servable Oxy asset holding each, in one round-trip per chunk via

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

@@ -104,6 +104,24 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * method would be dead code plus a second implementation of the failure
          * rules. The asymmetry is the design.
          *
+         * **Call this from NATIVE only.** There is no background worker on web to
+         * consume the credential, and handing a browser origin a long-lived
+         * non-rotating secret to persist is strictly weaker than the rotating device
+         * secret it already holds. The 404 degrade below is also native-shaped: a
+         * browser attaches `Origin`, which a server predating this route answers
+         * `403 BAD_ORIGIN` from its router-wide same-site guard rather than 404, so
+         * the quiet degrade would not fire there. A native client sends no `Origin`
+         * and gets the 404. Gate the caller by platform; do not widen the degrade to
+         * 403, which would also swallow a genuine origin misconfiguration.
+         *
+         * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
+         * oxy-api's router-wide origin guard (deliberately, so a native client with
+         * no `Origin` is not rejected). oxy-api additionally refuses callers that
+         * carry browser context signals (`Origin` or `Sec-Fetch-Site`) with
+         * `403 browser_not_allowed` — native HTTP clients send neither. Gate the
+         * caller by platform on the client as well; do not widen the 404 degrade to
+         * 403, which would also swallow a genuine origin misconfiguration.
+         *
          * @returns the provisioned credential, or `null` when the endpoint is absent
          * (404). The API deploy leads the SDK release, so a client on a newer SDK
          * than the server degrades to "no background session" quietly instead of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "15.0.0",
+  "version": "16.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -131,7 +131,7 @@
     "expo-crypto": "*",
     "expo-secure-store": "*",
     "express": "^4.0.0",
-    "express-rate-limit": "^7.0.0",
+    "express-rate-limit": "^8.0.0",
     "helmet": "^8.0.0"
   },
   "peerDependenciesMeta": {

package/src/OxyServices.errors.ts

@@ -64,6 +64,51 @@ export class AssetUrlResolutionError extends Error {
   }
 }
 
+/**
+ * Thrown when one or more chunks of `getServiceAssetMetadataByIds` could not be
+ * resolved.
+ *
+ * Exists because for this endpoint a FAILED request and an ABSENT asset produce
+ * the same observable result. The server legitimately omits unknown/deleted ids,
+ * so callers are documented to map the response by `id` and treat a missing
+ * entry as "no such asset" — which means a chunk that 429s, times out or 5xxs
+ * reads as authoritative absence unless it is raised.
+ *
+ * That was not hypothetical: a metadata backfill counted every throttled asset
+ * as needing no update and exited 0, and the MTN signed-record builder embedded
+ * media with no content hash into records that are immutable once signed. Both
+ * paths reported success and wrote nothing.
+ *
+ * `unresolvedIds` carries every id in a failed chunk — not the subset the server
+ * would have omitted anyway, which is unknowable when the request never landed.
+ * A caller that wants best-effort passes `{ partial: true }` and never sees this.
+ */
+export class ServiceAssetMetadataError extends Error {
+  public readonly code = 'SERVICE_ASSET_METADATA_UNRESOLVED';
+  /** Every id belonging to a chunk whose request failed. */
+  public readonly unresolvedIds: string[];
+  /** HTTP statuses observed across the failed chunks (deduped, ascending). */
+  public readonly statuses: number[];
+  /**
+   * The first underlying transport/API failure. Declared on the class rather
+   * than relying on `Error.cause` because this package targets ES2020, where
+   * `cause` is not part of the `Error` type.
+   */
+  public readonly cause?: unknown;
+
+  constructor(unresolvedIds: string[], statuses: number[], cause?: unknown) {
+    const uniqueStatuses = Array.from(new Set(statuses)).sort((a, b) => a - b);
+    const statusSuffix = uniqueStatuses.length > 0 ? ` — status ${uniqueStatuses.join(', ')}` : '';
+    super(
+      `Could not resolve asset metadata for ${unresolvedIds.length} id(s)${statusSuffix}. Treat this as unknown, not as absent; pass { partial: true } for best-effort.`,
+    );
+    this.name = 'ServiceAssetMetadataError';
+    this.unresolvedIds = unresolvedIds;
+    this.statuses = uniqueStatuses;
+    this.cause = cause;
+  }
+}
+
 export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
   constructor(operationName: string, timeoutMs: number) {
     super(

package/src/OxyServices.ts

@@ -57,7 +57,7 @@
  * See method JSDoc for more details and options.
  */
 import { OxyServicesBase, type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
-import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
 
 // Import mixin composition helper
 import { composeOxyServices } from './mixins';
@@ -151,7 +151,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
 }
 
 // Re-export error classes for convenience
-export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError };
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
 
 /**
  * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.

package/src/index.ts

@@ -23,7 +23,7 @@ import './crypto/polyfill';
 // ---------------------------------------------------------------------------
 // API client
 // ---------------------------------------------------------------------------
-export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
+export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 // Auth-refresh handler surface — consumed by `@oxyhq/services`'s OxyContext to

package/src/mixins/OxyServices.assets.ts

@@ -2,7 +2,7 @@ import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, A
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
 import { logger } from '../logger';
-import { AssetUrlResolutionError } from '../OxyServices.errors';
+import { AssetUrlResolutionError, ServiceAssetMetadataError } from '../OxyServices.errors';
 import { extractErrorStatus } from '../utils/errorUtils';
 import { redactUrlQuery } from '../utils/redactUrl';
 
@@ -353,15 +353,28 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
      * throws because no credentials are available. A plain user-session request
      * is rejected by the route's service-auth guard.
      *
-     * Resilience: chunks are independent. A failed chunk is logged and skipped —
-     * the method returns every entry that resolved successfully rather than
-     * discarding the whole call on one chunk's failure. An empty/whitespace-only
-     * input resolves immediately with `[]` and performs no network call.
+     * FAILURE IS NOT ABSENCE. The server legitimately omits unknown/deleted ids,
+     * so a short result is normal — which means a chunk that FAILED (a 429, a
+     * timeout, a 5xx) is indistinguishable from "those assets don't exist" if it
+     * simply contributes nothing. This method used to swallow a failed chunk and
+     * return the rest, so every caller silently read a throttled request as "no
+     * metadata": a backfill counted the asset as needing no update, and the
+     * signed-record builder embedded a media item with no hash. Both reported
+     * success while writing nothing, and the MTN chain's records are immutable.
+     *
+     * So a failed chunk THROWS {@link ServiceAssetMetadataError} by default,
+     * carrying the ids it could not resolve. A caller that genuinely wants
+     * best-effort opts in with `{ partial: true }` and gets the old behaviour
+     * explicitly. An empty/whitespace-only input resolves immediately with `[]`
+     * and performs no network call.
      *
      * Not cached at the SDK layer: it's a POST keyed on a multi-id body (low hit
      * rate), mirroring the sibling service/POST methods which never cache.
      */
-    async getServiceAssetMetadataByIds(ids: string[]): Promise<ServiceAssetMetadata[]> {
+    async getServiceAssetMetadataByIds(
+      ids: string[],
+      options: { partial?: boolean } = {},
+    ): Promise<ServiceAssetMetadata[]> {
       const uniqueIds = Array.from(
         new Set(ids.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)),
       );
@@ -374,7 +387,12 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
         chunks.push(uniqueIds.slice(i, i + SERVICE_ASSET_METADATA_CHUNK_SIZE));
       }
 
-      // Run chunks concurrently; a single chunk failure must not sink the rest.
+      // Chunks stay independent so one failure never cancels work already in
+      // flight; the failures are collected and re-raised together below.
+      const unresolvedIds: string[] = [];
+      const statuses: number[] = [];
+      let firstError: unknown;
+
       const settled = await Promise.all(
         chunks.map(async (chunk): Promise<ServiceAssetMetadata[]> => {
           try {
@@ -385,17 +403,26 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
             );
             return Array.isArray(entries) ? entries : [];
           } catch (error: unknown) {
-            logger.warn('getServiceAssetMetadataByIds: chunk failed, continuing with remaining chunks', {
+            const status = extractErrorStatus(error);
+            logger.warn('getServiceAssetMetadataByIds: chunk failed', {
               method: 'getServiceAssetMetadataByIds',
               chunkSize: chunk.length,
-              status: extractErrorStatus(error),
+              status,
+              partial: options.partial === true,
               error: error instanceof Error ? error.message : String(error),
             });
+            unresolvedIds.push(...chunk);
+            if (typeof status === 'number') statuses.push(status);
+            firstError ??= error;
             return [];
           }
         }),
       );
 
+      if (unresolvedIds.length > 0 && options.partial !== true) {
+        throw new ServiceAssetMetadataError(unresolvedIds, statuses, firstError);
+      }
+
       return settled.flat();
     }
 

package/src/mixins/OxyServices.deviceBoot.ts

@@ -157,6 +157,24 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * method would be dead code plus a second implementation of the failure
      * rules. The asymmetry is the design.
      *
+     * **Call this from NATIVE only.** There is no background worker on web to
+     * consume the credential, and handing a browser origin a long-lived
+     * non-rotating secret to persist is strictly weaker than the rotating device
+     * secret it already holds. The 404 degrade below is also native-shaped: a
+     * browser attaches `Origin`, which a server predating this route answers
+     * `403 BAD_ORIGIN` from its router-wide same-site guard rather than 404, so
+     * the quiet degrade would not fire there. A native client sends no `Origin`
+     * and gets the 404. Gate the caller by platform; do not widen the degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
+     *
+     * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
+     * oxy-api's router-wide origin guard (deliberately, so a native client with
+     * no `Origin` is not rejected). oxy-api additionally refuses callers that
+     * carry browser context signals (`Origin` or `Sec-Fetch-Site`) with
+     * `403 browser_not_allowed` — native HTTP clients send neither. Gate the
+     * caller by platform on the client as well; do not widen the 404 degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
+     *
      * @returns the provisioned credential, or `null` when the endpoint is absent
      * (404). The API deploy leads the SDK release, so a client on a newer SDK
      * than the server degrades to "no background session" quietly instead of

package/src/mixins/__tests__/OxyServices.serviceAssetMetadata.test.ts

@@ -10,11 +10,14 @@
  *  - the `{ data }` envelope is unwrapped to a bare `ServiceAssetMetadata[]`
  *    (mirroring how `makeServiceRequest<T[]>` returns the inner array);
  *  - inputs > 100 ids are chunked at 100/request and merged;
- *  - a failed chunk is logged and skipped — successful chunks still return.
+ *  - a failed chunk THROWS `ServiceAssetMetadataError` naming its ids, so a
+ *    throttled request can never be read as "those assets do not exist";
+ *  - `{ partial: true }` opts back into best-effort explicitly.
  */
 
 import type { ServiceAssetMetadata } from '../../models/interfaces';
 import { OxyServices } from '../../OxyServices';
+import { ServiceAssetMetadataError } from '../../OxyServices.errors';
 
 const sampleEntry: ServiceAssetMetadata = {
   id: 'asset-1',
@@ -101,16 +104,62 @@ describe('OxyServices.assets — getServiceAssetMetadataByIds', () => {
     expect(result[249]?.id).toBe('asset-249');
   });
 
-  it('skips a failed chunk and returns the entries that resolved', async () => {
+  it('THROWS when a chunk fails, so a failed request is never read as absence', async () => {
+    // The load-bearing assertion. The server legitimately omits unknown/deleted
+    // ids, so a short result is normal — which is exactly why a chunk that 429s
+    // must not just contribute nothing. Swallowing it made a throttled request
+    // indistinguishable from "those assets do not exist".
     const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
 
     makeServiceRequestSpy
       .mockResolvedValueOnce([sampleEntry]) // first chunk (100 ids) succeeds
       .mockRejectedValueOnce(new Error('chunk failed')); // second chunk (50 ids) fails
 
-    const result = await oxy.getServiceAssetMetadataByIds(ids);
+    await expect(oxy.getServiceAssetMetadataByIds(ids)).rejects.toThrow(ServiceAssetMetadataError);
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('names every id of the failed chunk on the error', async () => {
+    const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
+
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([sampleEntry])
+      .mockRejectedValueOnce(Object.assign(new Error('rate limited'), {
+        response: { status: 429 },
+      }));
+
+    const error = await oxy.getServiceAssetMetadataByIds(ids).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(ServiceAssetMetadataError);
+    const typed = error as ServiceAssetMetadataError;
+    // The whole chunk is unresolved: which of those ids the server would have
+    // omitted anyway is unknowable when the request never landed.
+    expect(typed.unresolvedIds).toHaveLength(50);
+    expect(typed.unresolvedIds).toContain('asset-100');
+    expect(typed.unresolvedIds).not.toContain('asset-0');
+    expect(typed.statuses).toEqual([429]);
+    expect(typed.code).toBe('SERVICE_ASSET_METADATA_UNRESOLVED');
+  });
+
+  it('returns the resolved entries when the caller opts into { partial: true }', async () => {
+    const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
+
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([sampleEntry])
+      .mockRejectedValueOnce(new Error('chunk failed'));
+
+    const result = await oxy.getServiceAssetMetadataByIds(ids, { partial: true });
 
     expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
     expect(result).toEqual([sampleEntry]);
   });
+
+  it('does not throw when every chunk succeeds, with or without partial', async () => {
+    makeServiceRequestSpy.mockResolvedValue([sampleEntry]);
+
+    await expect(oxy.getServiceAssetMetadataByIds(['asset-1'])).resolves.toEqual([sampleEntry]);
+    await expect(
+      oxy.getServiceAssetMetadataByIds(['asset-1'], { partial: true }),
+    ).resolves.toEqual([sampleEntry]);
+  });
 });

package/src/mixins/__tests__/backgroundCredential.httpIntegration.test.ts

@@ -0,0 +1,135 @@
+import type { DeviceBackgroundCredentialResponse } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Real-stack integration test for `provisionBackgroundCredential`: a genuine
+ * `HttpService` (via `OxyServices`) with `global.fetch` stubbed to return the
+ * EXACT wire bodies oxy-api sends, rather than a `makeRequest` spy.
+ *
+ * The unit suite (`OxyServices.deviceBoot.test.ts`) stubs `makeRequest`, so by
+ * construction it cannot see either of the two things this file pins:
+ *
+ *  1. **The `{ data }` envelope.** The route answers
+ *     `{ data: { deviceId, secret, accountId, expiresAt } }`, and
+ *     `HttpService.unwrapResponse` strips that outer envelope — so the mixin
+ *     must validate the FLAT credential and must not read `.data` a second
+ *     time. A spy returning the flat shape asserts that assumption instead of
+ *     testing it; the same blind spot produced a P0 in `SessionClient` (see
+ *     `SessionClient.httpIntegration.test.ts`).
+ *  2. **The 404 degrade against the REAL error object.** The `404 → null` path
+ *     is what keeps a client on a newer SDK than the server from breaking, and
+ *     it keys on the status surviving whatever `HttpService` throws. A
+ *     hand-built `Object.assign(new Error(), { status: 404 })` proves only that
+ *     the branch reads the shape the test itself invented.
+ *
+ * The stub is URL-aware because a state-changing request through the real stack
+ * fetches `GET /csrf-token` FIRST. A blanket stub answers that call too, which
+ * both shifts the request under test out of `calls[0]` and (on a non-200 stub)
+ * makes the CSRF fetch burn its own retries — so a naive call-count assertion
+ * measures CSRF attempts rather than the route.
+ */
+const ROUTE = '/session/device/background-credential';
+
+const CREDENTIAL: DeviceBackgroundCredentialResponse = {
+  deviceId: 'device-real',
+  secret: 'bg-secret-from-the-wire',
+  accountId: 'acct-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+};
+
+/** The route's success body: the credential under this API's `data` envelope. */
+const ROUTE_BODY = { data: CREDENTIAL };
+
+/** oxy-api's 404 body for an unmatched path (server.ts's terminal handler). */
+const NOT_FOUND_BODY = { error: 'NOT_FOUND', message: 'Resource not found' };
+
+const jsonResponse = (body: unknown, status: number) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+
+/**
+ * A syntactically real, far-future access token. It must be a decodable JWT:
+ * `HttpService.getAuthHeader` runs `jwtDecode` and sends NO bearer at all when
+ * that throws, so an opaque placeholder would silently turn this into an
+ * anonymous request and make the bearer assertion below untestable.
+ */
+const ACCESS_TOKEN = (() => {
+  const segment = (payload: object) => Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return [
+    segment({ alg: 'none', typ: 'JWT' }),
+    segment({ sub: 'acct-1', exp: 4_102_444_800 }), // 2100-01-01
+    'signature-not-verified-client-side',
+  ].join('.');
+})();
+
+describe('provisionBackgroundCredential over a real HttpService', () => {
+  const originalFetch = global.fetch;
+
+  /** Answers the CSRF preflight properly; answers the route under test with `body`/`status`. */
+  const stubFetch = (body: unknown, status: number) => {
+    const fetchMock = jest.fn(async (input: unknown) => {
+      if (String(input).includes('/csrf-token')) {
+        return jsonResponse({ csrfToken: 'csrf-test-token' }, 200);
+      }
+      return jsonResponse(body, status);
+    });
+    global.fetch = fetchMock as unknown as typeof fetch;
+    return fetchMock;
+  };
+
+  /** Every stubbed call whose URL is the route under test (i.e. not the CSRF preflight). */
+  const routeCalls = (fetchMock: jest.Mock) =>
+    fetchMock.mock.calls.filter(([input]) => String(input).includes(ROUTE));
+
+  const client = () => {
+    const oxy = new OxyServices({ baseURL: 'http://api.test.invalid' });
+    // Bearer required: the server derives both the deviceId and the account
+    // from it, and this call (unlike the device-secret mint) does not skipAuth.
+    oxy.setTokens(ACCESS_TOKEN);
+    return oxy;
+  };
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('unwraps the { data } envelope and returns the flat credential', async () => {
+    stubFetch(ROUTE_BODY, 200);
+
+    const result = await client().provisionBackgroundCredential();
+
+    // Would be `{ data: {...} }` if the envelope were not unwrapped, and would
+    // throw (contract validation failure) if `.data` were read twice.
+    expect(result).toEqual(CREDENTIAL);
+    expect(result?.secret).toBe('bg-secret-from-the-wire');
+  });
+
+  it('sends a POST to the route with NO body and a bearer', async () => {
+    const fetchMock = stubFetch(ROUTE_BODY, 200);
+
+    await client().provisionBackgroundCredential();
+
+    const calls = routeCalls(fetchMock);
+    expect(calls).toHaveLength(1);
+    const [, init] = calls[0] as unknown as [string, RequestInit];
+    expect(init.method).toBe('POST');
+    // No body at all — not `'undefined'`, not `'{}'`. The server derives the
+    // deviceId and the account from the bearer; anything sent here would be
+    // ignored at best and mass-assignment surface at worst.
+    expect(init.body ?? null).toBeNull();
+    expect(new Headers(init.headers).get('authorization')).toBe(`Bearer ${ACCESS_TOKEN}`);
+  });
+
+  it('returns null on the real 404 response, without retrying the route', async () => {
+    const fetchMock = stubFetch(NOT_FOUND_BODY, 404);
+
+    await expect(client().provisionBackgroundCredential()).resolves.toBeNull();
+
+    // 4xx is not retried (`retryAsync`'s default shouldRetry), so an absent
+    // endpoint costs exactly one request to the route — the degrade must not
+    // burn a backoff loop on every provision attempt.
+    expect(routeCalls(fetchMock)).toHaveLength(1);
+  });
+});

package/src/utils/__tests__/accountUtils.test.ts

@@ -1,4 +1,5 @@
 import {
+    createQuickAccount,
     getAccountDisplayName,
     getAccountFallbackHandle,
     formatPublicKeyHandle,
@@ -116,6 +117,27 @@ describe('getAccountFallbackHandle', () => {
     });
 });
 
+describe('createQuickAccount', () => {
+    it('prefers API name.displayName over composed first/last', () => {
+        const account = createQuickAccount('sess-1', {
+            name: { first: 'Nate', last: 'Isern', displayName: 'Nate Isern' },
+            username: 'nateus',
+            id: 'user-1',
+        });
+        expect(account.displayName).toBe('Nate Isern');
+    });
+
+    it('falls back to the normalized handle when displayName is absent', () => {
+        const account = createQuickAccount('sess-1', {
+            name: { first: 'Nate', last: 'Isern' },
+            username: 'nateus',
+            id: 'user-1',
+        });
+        expect(account.displayName).toBe('nateus');
+        expect(account.displayName).not.toBe('Nate Isern');
+    });
+});
+
 describe('formatPublicKeyHandle', () => {
     it('truncates a long key and strips the 0x prefix before re-adding it', () => {
         expect(formatPublicKeyHandle('0x1234567890abcdef')).toBe('0x12345678…');

package/src/utils/accountUtils.ts

@@ -4,6 +4,7 @@
  */
 
 import { translate } from '../i18n';
+import { getNormalizedUserHandle } from './userHandle';
 
 export interface QuickAccount {
     sessionId: string;
@@ -154,7 +155,14 @@ export const createQuickAccount = (
     existingAccount?: QuickAccount,
     getFileDownloadUrl?: (fileId: string, variant: string) => string
 ): QuickAccount => {
-    const displayName = getAccountDisplayName(userData);
+    const nameObj =
+        userData.name && typeof userData.name === 'object' ? userData.name : undefined;
+    const apiDisplayName =
+        typeof nameObj?.displayName === 'string' ? nameObj.displayName.trim() : '';
+    const displayName =
+        apiDisplayName ||
+        getNormalizedUserHandle(userData) ||
+        getAccountDisplayName(null);
     const userId = userData.id || (typeof userData._id === 'string' ? userData._id : userData._id?.toString());
 
     // Preserve existing avatarUrl if avatar hasn't changed (prevents image reload)