@oxyhq/core 12.5.4 → 12.7.0

package/src/crypto/__tests__/scopedSeed.test.ts

@@ -0,0 +1,126 @@
+import { setPlatformOS } from '../../utils/platform';
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    const store = new Map<string, string>();
+    return {
+      __esModule: true,
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
+      WHEN_UNLOCKED: 'WHEN_UNLOCKED',
+      setItemAsync: jest.fn(async (k: string, v: string) => { store.set(k, v); }),
+      getItemAsync: jest.fn(async (k: string) => store.get(k) ?? null),
+      deleteItemAsync: jest.fn(async (k: string) => { store.delete(k); }),
+      __resetStore__: () => store.clear(),
+    };
+  },
+  { virtual: true },
+);
+
+jest.mock(
+  'expo-crypto',
+  () => ({
+    __esModule: true,
+    getRandomBytes: (length: number) => {
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = (Math.random() * 256) & 0xff;
+      return out;
+    },
+    digestStringAsync: async () => '0'.repeat(64),
+    CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+  }),
+  { virtual: true },
+);
+
+jest.mock('@oxyhq/protocol', () => ({
+  __esModule: true,
+  ...jest.requireActual('@oxyhq/protocol'),
+  loadExpoCrypto: async () => require('expo-crypto'),
+  loadSecureStore: async () => require('expo-secure-store'),
+  loadNodeCrypto: async () => require('crypto'),
+  loadSharedIdentityBridge: async () => null,
+}));
+
+const FIXED_PRIV = 'aa'.repeat(32);
+const EXPECTED_FAIR = '4b90d900a11b0a1737ed643db3446e5f28035d86f1a4fda92474ea8ab152adf5';
+const EXPECTED_OTHER = 'cdedf1f076b0f4766c769e55bc1e90c5bf44d8630f6e5fb147615ee7c330c905';
+const toHex = (b: Uint8Array): string => Buffer.from(b).toString('hex');
+
+describe('KeyManager.deriveScopedSeed', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    const secureStore = (await import('expo-secure-store' as string)) as unknown as {
+      __resetStore__: () => void;
+    };
+    secureStore.__resetStore__();
+    const km = await import('../keyManager');
+    KeyManager = km.KeyManager;
+    // Store a known shared identity key so derivation is deterministic.
+    await KeyManager.importSharedIdentity(FIXED_PRIV);
+  });
+
+  it('derives the pinned 32-byte seed for a fixed identity + info', async () => {
+    const seed = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    if (!seed) throw new Error('expected a seed');
+    expect(seed).toHaveLength(32);
+    expect(toHex(seed)).toBe(EXPECTED_FAIR);
+  });
+
+  it('is deterministic (same identity + info → identical seed)', async () => {
+    const a = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    const b = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    if (!a || !b) throw new Error('expected seeds');
+    expect(toHex(a)).toBe(toHex(b));
+  });
+
+  it('domain-separates by info (different info → different seed)', async () => {
+    const fair = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    const other = await KeyManager.deriveScopedSeed('oxypay/other/v1');
+    if (!fair || !other) throw new Error('expected seeds');
+    expect(toHex(other)).toBe(EXPECTED_OTHER);
+    expect(toHex(fair)).not.toBe(toHex(other));
+  });
+
+  it('never returns the raw private key (no leak)', async () => {
+    const seed = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    if (!seed) throw new Error('expected a seed');
+    expect(toHex(seed)).not.toBe(FIXED_PRIV);
+  });
+
+  it('returns null on web (no identity key available)', async () => {
+    // `jest.resetModules()` gives KeyManager its own bound instance of
+    // `utils/platform` (its cached OS locks in as soon as `beforeEach`'s
+    // `importSharedIdentity` first checks it). The file-level `setPlatformOS`
+    // import above is bound to a different, earlier instance, so mutating it
+    // here would not be observed by the already-imported `KeyManager`. Reset
+    // again and re-import both from the same fresh module graph so the
+    // platform flip actually reaches the KeyManager instance under test.
+    //
+    // `jest.resetModules()` also re-runs the virtual `expo-secure-store`
+    // mock factory, handing this fresh KeyManager a brand-new empty
+    // in-memory store — the identity `beforeEach` imported lives only in the
+    // pre-reset store instance. Without re-storing an identity here, a
+    // `null` result would be ambiguous between the web gate and the
+    // no-identity fallback. Re-import the identity on THIS fresh instance
+    // (while still native — `importSharedIdentity` itself is native-gated
+    // and throws on web) BEFORE flipping to web, so the later `null` can
+    // only be explained by the web gate, not a missing identity.
+    jest.resetModules();
+    const platform = await import('../../utils/platform');
+    const km = await import('../keyManager');
+    await km.KeyManager.importSharedIdentity(FIXED_PRIV);
+    platform.setPlatformOS('web');
+    expect(await km.KeyManager.deriveScopedSeed('oxypay/faircoin/v1')).toBeNull();
+  });
+
+  it('returns null when no identity exists on the device', async () => {
+    const secureStore = (await import('expo-secure-store' as string)) as unknown as {
+      __resetStore__: () => void;
+    };
+    secureStore.__resetStore__();
+    expect(await KeyManager.deriveScopedSeed('oxypay/faircoin/v1')).toBeNull();
+  });
+});

package/src/crypto/keyManager.ts

@@ -10,6 +10,7 @@ import type { ECKeyPair } from 'elliptic';
 import { isWeb, isIOS, isAndroid } from '../utils/platform';
 import { type ExpoCryptoLike, type ExpoSecureStoreLike, isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
 import { isDev, logger } from '../logger';
+import { hkdfSha256 } from './kdf';
 
 /**
  * Options for expo-secure-store calls made by KeyManager.
@@ -79,6 +80,28 @@ export class IdentityPersistError extends Error {
 
 const ec = new EC('secp256k1');
 
+/**
+ * HKDF salt that domain-separates every identity-scoped seed produced by
+ * {@link KeyManager.deriveScopedSeed}. Versioned so a future scheme change is a
+ * new, non-colliding tag. The per-app domain (e.g. Oxy Pay's FairCoin wallet)
+ * is carried by the caller's `info` string, not this salt.
+ */
+const SCOPED_SEED_KDF_SALT = 'oxy-identity-scoped-seed-v1';
+
+/** UTF-8 encode an ASCII label to bytes (HKDF salt/info). */
+function utf8ToBytes(label: string): Uint8Array {
+  return new TextEncoder().encode(label);
+}
+
+/** Decode a hex string to bytes. Inverse of {@link uint8ArrayToHex}. */
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
 const STORAGE_KEYS = {
   PRIVATE_KEY: 'oxy_identity_private_key',
   PUBLIC_KEY: 'oxy_identity_public_key',
@@ -1559,6 +1582,38 @@ export class KeyManager {
     }
   }
 
+  /**
+   * Derive a 32-byte, domain-separated seed from the on-device Oxy identity
+   * private key via HKDF-SHA256, WITHOUT ever exposing the raw private key.
+   *
+   * The domain separation is carried by `info` (e.g. `"oxypay/faircoin/v1"`),
+   * so distinct apps/purposes get independent seeds from the same identity.
+   * The output is HKDF keying material, never the private key itself — a
+   * consumer (e.g. Oxy Pay's FairCoin HD wallet) can feed it straight into
+   * `HDKey.fromMasterSeed` and never touches the identity key.
+   *
+   * Key source (native only): prefers the shared ecosystem identity written to
+   * `group.so.oxy.shared` (what a Relying Party like Oxy Pay reads), then falls
+   * back to this device's primary identity (Commons/Accounts). Both reproduce
+   * from the user's Oxy recovery phrase, so the derived seed is recoverable.
+   *
+   * @param info Context/domain-binding label (distinct labels → independent seeds).
+   * @returns 32 bytes of derived keying material, or `null` on web / when no
+   *          identity key is available on this device.
+   */
+  static async deriveScopedSeed(info: string): Promise<Uint8Array | null> {
+    if (isWebPlatform()) {
+      return null;
+    }
+    const privateKey =
+      (await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey());
+    if (!privateKey) {
+      return null;
+    }
+    const ikm = hexToBytes(KeyManager.canonicalPrivateKey(privateKey));
+    return hkdfSha256(ikm, utf8ToBytes(SCOPED_SEED_KDF_SALT), utf8ToBytes(info), 32);
+  }
+
   /**
    * Get a shortened version of the public key for display
    * Format: first 8 chars...last 8 chars

package/src/i18n/locales/en-US.json

@@ -1449,6 +1449,13 @@
       "emptyTitle": "No photos yet",
       "emptySubtitle": "Upload from your device to get started"
     },
+    "details": {
+      "title": "File Details",
+      "download": "Download",
+      "type": "Type",
+      "uploaded": "Uploaded",
+      "description": "Description"
+    },
     "a11y": {
       "viewAll": "Show all files",
       "viewPhotos": "Show photos only",

package/src/i18n/locales/es-ES.json

@@ -1449,6 +1449,13 @@
       "emptyTitle": "Aún no hay fotos",
       "emptySubtitle": "Sube desde tu dispositivo para empezar"
     },
+    "details": {
+      "title": "Detalles del archivo",
+      "download": "Descargar",
+      "type": "Tipo",
+      "uploaded": "Subido",
+      "description": "Descripción"
+    },
     "a11y": {
       "viewAll": "Mostrar todos los archivos",
       "viewPhotos": "Mostrar solo fotos",

package/src/index.ts

@@ -23,7 +23,7 @@ import './crypto/polyfill';
 // ---------------------------------------------------------------------------
 // API client
 // ---------------------------------------------------------------------------
-export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
+export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } 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
@@ -48,6 +48,10 @@ export type {
     ContactDiscoveryMatch,
     ContactDiscoveryResponse,
 } from './mixins/OxyServices.contacts';
+export type {
+    InitDeviceTransferResult,
+    DeviceTransferOutcome,
+} from './mixins/OxyServices.deviceTransfer';
 export type {
     BulkFollowEntry,
     BulkFollowResult,
@@ -311,6 +315,8 @@ export type {
     AssetLinkRequest,
     AssetUnlinkRequest,
     AssetUrlResponse,
+    BatchFileAccessEntry,
+    BatchFileAccessResponse,
     AssetDeleteSummary,
     AssetUpdateVisibilityRequest,
     AssetUpdateVisibilityResponse,

package/src/mixins/OxyServices.assets.ts

@@ -1,8 +1,10 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
 import { logger } from '../logger';
+import { AssetUrlResolutionError } from '../OxyServices.errors';
 import { extractErrorStatus } from '../utils/errorUtils';
+import { redactUrlQuery } from '../utils/redactUrl';
 
 /**
  * Maximum number of ids sent per `POST /assets/service/by-ids` request. Matches
@@ -27,6 +29,40 @@ const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
  */
 const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
 
+/**
+ * Conservative lower bound (10 min) the SDK assumes for the lifetime of the
+ * scoped media token (`mt`) the API embeds in the stream URL it returns for a
+ * private asset. The SDK never mints or inspects that token; this constant
+ * exists only so the SDK's own URL cache can be sized safely BELOW the token's
+ * real lifetime.
+ *
+ * The API currently mints tokens for 900s (`MEDIA_TOKEN_TTL_SECONDS` in
+ * `packages/api/src/utils/mediaToken.ts`). Core deliberately assumes a shorter
+ * 10-min floor rather than copying 15: core and the API are separate packages,
+ * so core cannot observe a server-side TTL change at runtime. Under-assuming the
+ * lifetime only ever shortens the cache (more refetches, never a dead URL), so
+ * it stays correct even if the server lowers its TTL toward this floor. The
+ * {@link ASSET_URL_CACHE_LIFETIME_FRACTION} discount is applied on top.
+ */
+const ASSET_MEDIA_TOKEN_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Fraction of a resolved URL's remaining lifetime the SDK is willing to keep it
+ * cached for. A resolved URL stops working the moment its media token expires,
+ * so caching it for its full nominal lifetime guarantees a window in which the
+ * cache hands out an already-dead URL (clock skew, time spent in the render
+ * pipeline, an image request queued behind others). Half the lifetime leaves a
+ * margin at least as large as the entry's own age.
+ */
+const ASSET_URL_CACHE_LIFETIME_FRACTION = 0.5;
+
+/**
+ * Fallback URL lifetime, in seconds, assumed when the caller does not request
+ * an explicit `expiresIn`. Mirrors the API's default signed-URL expiry; the
+ * effective value is still clamped by {@link ASSET_MEDIA_TOKEN_TTL_MS}.
+ */
+const DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS = 3600;
+
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -61,14 +97,33 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Build a synchronous, `<img src>`-ready file URL from an Oxy asset id.
+     * Build a synchronous, `<img src>`-ready URL for a **PUBLIC** Oxy asset.
+     *
+     * ## Contract — read before calling
      *
-     * This method must never embed the caller's general access token in the
-     * returned URL. The URL is commonly rendered into DOM attributes, browser
-     * network panels, caches, and logs. Public asset URLs use the clean CDN
-     * origin; callers that need authorized/private access should use
-     * {@link getFileDownloadUrlAsync}, which asks the API for a scoped download
-     * URL instead of exposing the in-memory bearer token in a query string.
+     * This is a pure string builder. It performs no network call and therefore
+     * has **no knowledge of the asset's visibility**. It always produces the
+     * public form: `${cloudURL}/<id>[?variant=…]`, which the CDN serves from
+     * the public media origin only.
+     *
+     * Consequently:
+     *  - Call it ONLY when the asset is known to be `public` — e.g. avatars and
+     *    profile banners, which {@link uploadAvatar} / {@link uploadProfileBanner}
+     *    upload with `visibility: 'public'`.
+     *  - For an asset that may be `private` or `unlisted` — anything uploaded
+     *    through the generic {@link assetUpload} path, whose server-side default
+     *    is private — this URL resolves to a hard **404**. Use
+     *    {@link getFileDownloadUrlAsync}, which asks the API for a URL scoped to
+     *    the current caller.
+     *  - It must never guess visibility, and must never embed the caller's
+     *    bearer token: the returned string is rendered into DOM attributes,
+     *    browser network panels, HTTP caches, and logs.
+     *
+     * Passing `expiresIn` switches to the API-origin stream form
+     * (`${baseURL}/assets/<id>/stream?…`) WITHOUT any credential. That form
+     * still only serves what an unauthenticated request may see — it is not a
+     * synchronous private-asset path, and none exists: authorization for a
+     * private asset requires the round-trip in {@link getFileDownloadUrlAsync}.
      */
     getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string {
       // Never embed the in-memory bearer token: this URL is rendered into DOM
@@ -91,21 +146,46 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Get file download URL asynchronously (returns signed URL directly from CDN)
+     * Resolve an asset id to a URL that is valid for the CURRENT caller,
+     * whatever the asset's visibility.
+     *
+     * Asks the API (`GET /assets/:id/url`) rather than guessing: a `public`
+     * asset resolves to the CDN form, while a `private`/`unlisted` asset the
+     * caller may read resolves to an API-origin stream URL carrying a scoped,
+     * short-lived media token. The returned URL is passed through **unchanged**
+     * — the SDK never rewrites, re-signs, or strips it.
+     *
+     * ## Failure behaviour — no CDN fallback
+     *
+     * Throws {@link AssetUrlResolutionError} when the API returns no URL or the
+     * request fails (including 401/403/404). It deliberately does NOT fall back
+     * to {@link getFileDownloadUrl}: that builder only produces the public CDN
+     * form, so falling back would hand the caller a URL that renders as a hard
+     * 404 for every private asset and would silently swallow the real failure.
+     * A caller that knows an asset is public should call the synchronous
+     * builder directly instead of relying on a fallback here.
+     *
+     * The resolved URL is cached per identity for well under the media token's
+     * lifetime — see {@link getAssetUrlCacheTTL}.
      */
     async getFileDownloadUrlAsync(fileId: string, variant?: string, expiresIn?: number): Promise<string> {
+      let url: string | null;
       try {
-        const url = await this.fetchAssetDownloadUrl(
+        url = await this.fetchAssetDownloadUrl(
           fileId,
           variant,
           this.getAssetUrlCacheTTL(expiresIn),
           expiresIn
         );
+      } catch (error: unknown) {
+        throw new AssetUrlResolutionError(fileId, variant, extractErrorStatus(error), error);
+      }
 
-        return url || this.getFileDownloadUrl(fileId, variant, expiresIn);
-      } catch (error) {
-        return this.getFileDownloadUrl(fileId, variant, expiresIn);
+      if (!url) {
+        throw new AssetUrlResolutionError(fileId, variant, undefined);
       }
+
+      return url;
     }
 
     /**
@@ -180,13 +260,39 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Get batch access to multiple files
+     * Resolve access + a caller-scoped URL for many assets — each with its OWN
+     * requested variant — in ONE round trip via `POST /assets/batch-access`.
+     *
+     * `requests` is a per-file `{ fileId, variant? }` list (a `variant` of
+     * `undefined` asks for the original). `options.expiresIn` sets the requested
+     * media-token / signed-URL lifetime (seconds); `options.context` is the
+     * server-side access-check context. Entries with a blank `fileId` are
+     * dropped and exact `(fileId, variant)` duplicates are collapsed before the
+     * request; an empty effective list performs no network call.
+     *
+     * The server caps the batch at 100 entries — callers that page beyond that
+     * must chunk. Returns the raw per-file envelope (see
+     * {@link BatchFileAccessResponse}); most callers want {@link getFileDownloadUrls},
+     * which flattens it to just the usable URLs.
      */
-    async getBatchFileAccess(fileIds: string[], context?: string): Promise<Record<string, any>> {
+    async getBatchFileAccess(
+      requests: Array<{ fileId: string; variant?: string }>,
+      options?: { expiresIn?: number; context?: string },
+    ): Promise<BatchFileAccessResponse> {
+      const files = dedupeFileAccessRequests(requests);
+      if (files.length === 0) {
+        return { results: {} };
+      }
+
+      const body: { files: Array<{ fileId: string; variant?: string }>; expiresIn?: number; context?: string } = {
+        files,
+      };
+      if (typeof options?.expiresIn === 'number') body.expiresIn = options.expiresIn;
+      if (typeof options?.context === 'string') body.context = options.context;
+
       try {
-        return await this.makeRequest('POST', '/assets/batch-access', { 
-          fileIds, 
-          context 
+        return await this.makeRequest<BatchFileAccessResponse>('POST', '/assets/batch-access', body, {
+          cache: false,
         });
       } catch (error) {
         throw this.handleError(error);
@@ -194,13 +300,30 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Get download URLs for multiple files efficiently
+     * Resolve many assets — each with its OWN variant — to caller-scoped,
+     * `<img src>`-ready URLs in one round trip. The batch counterpart of
+     * {@link getFileDownloadUrlAsync}, built to resolve a whole grid page at once.
+     *
+     * `requests` is a per-file `{ fileId, variant? }` list (e.g. `poster` for a
+     * video, `thumb` for an image); the per-file variant RULE lives in the
+     * caller — core just forwards what it is given. `options.expiresIn` /
+     * `options.context` are passed through to the endpoint.
+     *
+     * Each returned URL is the API's own scoped form, passed through unchanged:
+     * the public CDN URL for a public asset, or an API-origin
+     * `/assets/:id/stream?…&mt=<media token>` URL for a private asset the caller
+     * may read. Ids the caller cannot access (or that do not exist) are simply
+     * OMITTED from the returned map — there is NO public-CDN fallback, so a grid
+     * never renders a known-404 URL. Callers detect a miss by the absent key
+     * (the map never contains an empty-string value). Keyed by `fileId`.
      */
-    async getFileDownloadUrls(fileIds: string[], context?: string): Promise<Record<string, string>> {
-      const response: any = await this.getBatchFileAccess(fileIds, context);
+    async getFileDownloadUrls(
+      requests: Array<{ fileId: string; variant?: string }>,
+      options?: { expiresIn?: number; context?: string },
+    ): Promise<Record<string, string>> {
+      const response = await this.getBatchFileAccess(requests, options);
       const urls: Record<string, string> = {};
-      const results = response.results || {};
-      for (const [id, result] of Object.entries(results as Record<string, any>)) {
+      for (const [id, result] of Object.entries(response.results ?? {})) {
         if (result.allowed && result.url) {
           urls[id] = result.url;
         }
@@ -526,7 +649,7 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
         
         return await this.makeRequest<AssetUrlResponse>('GET', `/assets/${fileId}/url`, params, {
           cache: true,
-          cacheTTL: 10 * 60 * 1000,
+          cacheTTL: this.getAssetUrlCacheTTL(expiresIn),
         });
       } catch (error) {
         throw this.handleError(error);
@@ -614,9 +737,21 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       }
     }
 
-    public getAssetUrlCacheTTL(expiresIn?: number) {
-      const desiredTtlMs = (expiresIn ?? 3600) * 1000;
-      return Math.min(desiredTtlMs, 10 * 60 * 1000);
+    /**
+     * How long a resolved asset URL may stay in the SDK's GET cache, in ms.
+     *
+     * A resolved private-asset URL dies the instant its scoped media token
+     * expires (~{@link ASSET_MEDIA_TOKEN_TTL_MS}). Caching it for its full
+     * nominal lifetime would leave a window where the cache serves an
+     * already-dead URL (clock skew, render-pipeline latency, an image request
+     * queued behind others). So the TTL is (a) never longer than the token's
+     * lifetime and (b) discounted to {@link ASSET_URL_CACHE_LIFETIME_FRACTION}
+     * of that bound — comfortably below the token TTL by construction.
+     */
+    public getAssetUrlCacheTTL(expiresIn?: number): number {
+      const requestedLifetimeMs = (expiresIn ?? DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS) * 1000;
+      const boundedLifetimeMs = Math.min(requestedLifetimeMs, ASSET_MEDIA_TOKEN_TTL_MS);
+      return Math.floor(boundedLifetimeMs * ASSET_URL_CACHE_LIFETIME_FRACTION);
     }
 
     public async fetchAssetDownloadUrl(
@@ -635,7 +770,10 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
         Object.keys(params).length ? params : undefined,
         {
           cache: true,
-          cacheTTL: cacheTTL ?? 10 * 60 * 1000,
+          // Cap the cached URL well below the media token's lifetime. The
+          // response body is a scoped, expiring URL; over-caching it serves a
+          // dead URL after the token expires (see getAssetUrlCacheTTL).
+          cacheTTL: cacheTTL ?? this.getAssetUrlCacheTTL(expiresIn),
         }
       );
 
@@ -656,6 +794,32 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
   };
 }
 
+/**
+ * Normalize the per-file batch-access request list: drop entries with a blank
+ * `fileId` and collapse exact `(fileId, variant)` duplicates (first occurrence
+ * wins, preserving order). Two entries for the SAME `fileId` with DIFFERENT
+ * variants are intentionally kept — but note the response is keyed by `fileId`,
+ * so a caller that needs two variants of one file must issue separate calls.
+ */
+function dedupeFileAccessRequests(
+  requests: Array<{ fileId: string; variant?: string }>,
+): Array<{ fileId: string; variant?: string }> {
+  const seen = new Set<string>();
+  const out: Array<{ fileId: string; variant?: string }> = [];
+  for (const req of requests) {
+    if (typeof req?.fileId !== 'string' || req.fileId.trim().length === 0) {
+      continue;
+    }
+    const key = `${req.fileId}\u0000${req.variant ?? ''}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    out.push(req.variant === undefined ? { fileId: req.fileId } : { fileId: req.fileId, variant: req.variant });
+  }
+  return out;
+}
+
 /**
  * Only send ambient credentials (cookies) when the asset URL is same-origin with
  * the configured API base. Caller-supplied cross-origin asset URLs must not leak