@oxyhq/core 12.5.4 → 12.6.0

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

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

@@ -12,7 +12,35 @@
  *     private access should use `getFileDownloadUrlAsync()` for a scoped URL.
  */
 
-import { OxyServices } from '../../OxyServices';
+import { AssetUrlResolutionError, OxyServices } from '../../OxyServices';
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check),
+ * so this is enough to give the HTTP cache a distinct per-user identity tag.
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify({ data }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/** An error `Response` mimicking the API's error body. */
+function errorResponse(status: number, code: string): Response {
+  return new Response(JSON.stringify({ error: code, message: code }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
 
 describe('OxyServices.getFileDownloadUrl', () => {
   describe('public assets (no token, no expiresIn) → CDN', () => {
@@ -80,3 +108,239 @@ describe('OxyServices.getFileDownloadUrl', () => {
     });
   });
 });
+
+describe('OxyServices.getFileDownloadUrlAsync', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('passes the API-scoped private stream URL through UNCHANGED', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    const scopedUrl =
+      'https://api.oxy.so/assets/priv1/stream?variant=thumb&mt=SCOPED-MEDIA-TOKEN';
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: scopedUrl, variant: 'thumb', expiresIn: 600 }));
+
+    const resolved = await oxy.getFileDownloadUrlAsync('priv1', 'thumb');
+
+    // Returned exactly as the API produced it — never rewritten to the CDN.
+    expect(resolved).toBe(scopedUrl);
+    expect(resolved).not.toContain('cloud.oxy.so');
+    // It hit the authorized resolution endpoint, not the public CDN builder.
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('/assets/priv1/url');
+  });
+
+  it('resolves a public asset to the CDN URL the API returns', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ url: 'https://cloud.oxy.so/pub1?variant=thumb', variant: 'thumb', expiresIn: 3600 }),
+    );
+
+    const resolved = await oxy.getFileDownloadUrlAsync('pub1', 'thumb');
+    expect(resolved).toBe('https://cloud.oxy.so/pub1?variant=thumb');
+  });
+
+  it('THROWS rather than returning a known-404 CDN URL when the API denies access', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValue(errorResponse(403, 'Access denied'));
+
+    await expect(oxy.getFileDownloadUrlAsync('priv1', 'thumb')).rejects.toBeInstanceOf(
+      AssetUrlResolutionError,
+    );
+
+    // Prove the failure was surfaced instead of a silent public-CDN fallback.
+    const err = await oxy
+      .getFileDownloadUrlAsync('priv1', 'thumb')
+      .catch((e: unknown) => e as AssetUrlResolutionError);
+    expect(err).toBeInstanceOf(AssetUrlResolutionError);
+    expect(err.fileId).toBe('priv1');
+    expect(err.variant).toBe('thumb');
+    expect(err.status).toBe(403);
+    // The error must not leak the scoped media token.
+    expect(err.message).not.toContain('mt=');
+  });
+
+  it('THROWS when the API returns an empty URL body', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: '', variant: undefined, expiresIn: 600 }));
+
+    await expect(oxy.getFileDownloadUrlAsync('priv1')).rejects.toBeInstanceOf(
+      AssetUrlResolutionError,
+    );
+  });
+});
+
+describe('OxyServices asset URL cache TTL', () => {
+  const MEDIA_TOKEN_TTL_MS = 10 * 60 * 1000;
+
+  it('never caches a resolved URL for as long as the media-token TTL', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Default (no explicit expiry) and an over-long explicit expiry both stay
+    // comfortably under the token lifetime.
+    expect(oxy.getAssetUrlCacheTTL()).toBeLessThan(MEDIA_TOKEN_TTL_MS);
+    expect(oxy.getAssetUrlCacheTTL(3600)).toBeLessThan(MEDIA_TOKEN_TTL_MS);
+    // Half of the 10-min bound.
+    expect(oxy.getAssetUrlCacheTTL(3600)).toBe(5 * 60 * 1000);
+  });
+
+  it('scales a short requested expiry down proportionally', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    expect(oxy.getAssetUrlCacheTTL(60)).toBe(30 * 1000);
+  });
+});
+
+describe('OxyServices.getFileDownloadUrls (variant-aware batch)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('sends a per-file {fileId, variant} list plus expiresIn and keeps only usable URLs', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        results: {
+          img1: {
+            allowed: true,
+            url: 'https://api.oxy.so/assets/img1/stream?variant=thumb&mt=TKN',
+            visibility: 'private',
+            mime: 'image/jpeg',
+          },
+          vid1: {
+            allowed: true,
+            url: 'https://cloud.oxy.so/vid1?variant=poster',
+            visibility: 'public',
+          },
+          gone: { allowed: false, error: 'Access denied' },
+        },
+      }),
+    );
+
+    const urls = await oxy.getFileDownloadUrls(
+      [
+        { fileId: 'img1', variant: 'thumb' },
+        { fileId: 'vid1', variant: 'poster' },
+        { fileId: 'gone' },
+      ],
+      { expiresIn: 600, context: 'file-manager' },
+    );
+
+    // Denied/missing ids are OMITTED (never an empty-string value).
+    expect(urls).toEqual({
+      img1: 'https://api.oxy.so/assets/img1/stream?variant=thumb&mt=TKN',
+      vid1: 'https://cloud.oxy.so/vid1?variant=poster',
+    });
+    expect('gone' in urls).toBe(false);
+
+    // The request carried the per-file variants + expiresIn on the POST body.
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(String(init.body));
+    expect(body.files).toEqual([
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: 'vid1', variant: 'poster' },
+      { fileId: 'gone' },
+    ]);
+    expect(body.expiresIn).toBe(600);
+    expect(body.context).toBe('file-manager');
+  });
+
+  it('drops blank ids and collapses exact (fileId, variant) duplicates before sending', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ results: {} }));
+
+    await oxy.getFileDownloadUrls([
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: '   ' },
+      { fileId: 'img1' },
+    ]);
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(String(init.body));
+    // Dedup on (fileId, variant): the two thumb entries collapse; the
+    // variant-less img1 is a DIFFERENT request and survives; blank id dropped.
+    expect(body.files).toEqual([
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: 'img1' },
+    ]);
+  });
+
+  it('makes NO network call for an all-empty request list', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    const urls = await oxy.getFileDownloadUrls([{ fileId: '' }, { fileId: '  ' }]);
+    expect(urls).toEqual({});
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('OxyServices asset URL cache isolation across accounts', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('never serves account A’s scoped URL to account B after a switch', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Account A resolves the asset; response is cached under A's identity.
+    oxy.setTokens(makeJwt({ userId: 'account-A' }));
+    const urlForA = 'https://api.oxy.so/assets/priv1/stream?mt=TOKEN-FOR-A';
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: urlForA, expiresIn: 600 }));
+    expect(await oxy.getFileDownloadUrlAsync('priv1')).toBe(urlForA);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Switching to account B mints a new access token → new identity tag. B's
+    // read must MISS A's cache entry and hit the network for its own scoped URL.
+    oxy.setTokens(makeJwt({ userId: 'account-B' }));
+    const urlForB = 'https://api.oxy.so/assets/priv1/stream?mt=TOKEN-FOR-B';
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: urlForB, expiresIn: 600 }));
+
+    const resolvedForB = await oxy.getFileDownloadUrlAsync('priv1');
+    expect(resolvedForB).toBe(urlForB);
+    expect(resolvedForB).not.toBe(urlForA);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/models/interfaces.ts

@@ -517,6 +517,26 @@ export interface AssetUrlResponse {
   expiresIn: number;
 }
 
+/**
+ * Per-file result of `POST /assets/batch-access`. `allowed` is authoritative:
+ * when `false` the entry carries an `error` string (e.g. `'Access denied'`,
+ * `'File not found'`) and no `url`. When `true`, `url` is a caller-scoped,
+ * `<img src>`-ready URL — the public CDN form for a public asset or an
+ * API-origin stream URL carrying a short-lived media token for a private one.
+ */
+export interface BatchFileAccessEntry {
+  allowed: boolean;
+  url?: string;
+  visibility?: FileVisibility;
+  mime?: string;
+  error?: string;
+}
+
+/** Envelope returned by `POST /assets/batch-access`, keyed by file id. */
+export interface BatchFileAccessResponse {
+  results: Record<string, BatchFileAccessEntry>;
+}
+
 export interface AssetDeleteSummary {
   fileId: string;
   wouldDelete: boolean;