@oxyhq/core 5.1.1 → 5.2.1

package/src/__tests__/establishDeviceRefreshSlot.test.ts

@@ -0,0 +1,221 @@
+/**
+ * `establishDeviceRefreshSlot` + primary-session slot-registration tests.
+ *
+ * ROOT CAUSE these lock in: a web PRIMARY session (FedCM exchange, central `/sso`
+ * return, IdP `/auth/silent` iframe, password) plants only an access token. The
+ * cross-origin/credential-less restore endpoints (`/sso/exchange`, `/auth/silent`)
+ * cannot set the device's `oxy_rt_<authuser>` cookie, so without an explicit
+ * `POST /auth/session` the primary never joins the device refresh-cookie set:
+ * `/auth/refresh-all` returns zero accounts and account-switch persistence has no
+ * foundation. `establishDeviceRefreshSlot()` is the single shared primitive (on the
+ * base, reused by `switchToAccount` and `AuthManager.handleAuthSuccess`) that plants
+ * the slot where the cookie is visible, re-plants the rotated token, and returns the
+ * authoritative `authuser`.
+ *
+ * `testEnvironment` is `node`, where `getPlatformOS()` resolves to `'web'`
+ * (`isWeb()` is true) and `window` is undefined — so the FIRST-PARTY apex gate is
+ * inert and the method exercises its happy path. Browser-only apex gating is
+ * verified separately by stubbing a `window`.
+ */
+
+import { OxyServices } from '../OxyServices';
+import { AuthManager } from '../AuthManager';
+import type { StorageAdapter } from '../AuthManager';
+import type { RefreshAllResponse, RefreshCookieResponse, User } from '../models/interfaces';
+import type { SessionLoginResponse } from '../models/session';
+
+function buildAccessToken(claims: Record<string, unknown>): string {
+  const b64url = (value: string): string =>
+    Buffer.from(value).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  const header = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const payload = b64url(JSON.stringify(claims));
+  return `${header}.${payload}.signature`;
+}
+
+describe('OxyServices.establishDeviceRefreshSlot', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens('primary-token');
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    makeRequestSpy.mockRestore();
+  });
+
+  it('POSTs to /auth/session, re-plants the rotated access token, and returns the server authuser', async () => {
+    makeRequestSpy.mockResolvedValue({ accessToken: 'rotated-token', authuser: 2 });
+
+    const authuser = await oxy.establishDeviceRefreshSlot();
+
+    expect(authuser).toBe(2);
+    expect(makeRequestSpy).toHaveBeenCalledWith('POST', '/auth/session', undefined, { cache: false });
+    // The rotated token from /auth/session is now the active token.
+    expect(oxy.getAccessToken()).toBe('rotated-token');
+  });
+
+  it('returns the authuser even when the response carries no rotated token (keeps the existing token)', async () => {
+    makeRequestSpy.mockResolvedValue({ authuser: 0 });
+
+    const authuser = await oxy.establishDeviceRefreshSlot();
+
+    expect(authuser).toBe(0);
+    expect(oxy.getAccessToken()).toBe('primary-token');
+  });
+
+  it('returns null when the server omits a numeric authuser', async () => {
+    makeRequestSpy.mockResolvedValue({ accessToken: 'rotated-token' });
+
+    const authuser = await oxy.establishDeviceRefreshSlot();
+
+    expect(authuser).toBeNull();
+  });
+
+  it('is best-effort: a failed /auth/session resolves null and never throws', async () => {
+    makeRequestSpy.mockRejectedValue(new Error('network down'));
+
+    await expect(oxy.establishDeviceRefreshSlot()).resolves.toBeNull();
+  });
+
+  it('FIRST-PARTY gate: skips /auth/session when the page apex differs from the API apex (cross-apex RP)', async () => {
+    // Simulate a cross-apex RP page (mention.earth) calling api.oxy.so.
+    const rp = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    rp.httpService.setTokens('primary-token');
+    const rpSpy = jest.spyOn(rp, 'makeRequest');
+    const originalWindow = (globalThis as { window?: unknown }).window;
+    (globalThis as { window?: unknown }).window = { location: { hostname: 'mention.earth' } };
+    try {
+      const authuser = await rp.establishDeviceRefreshSlot();
+      expect(authuser).toBeNull();
+      expect(rpSpy).not.toHaveBeenCalled();
+    } finally {
+      if (originalWindow === undefined) {
+        delete (globalThis as { window?: unknown }).window;
+      } else {
+        (globalThis as { window?: unknown }).window = originalWindow;
+      }
+      rpSpy.mockRestore();
+    }
+  });
+
+  it('FIRST-PARTY gate: proceeds when the page apex matches the API apex (first-party *.oxy.so)', async () => {
+    const fp = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    fp.httpService.setTokens('primary-token');
+    const fpSpy = jest.spyOn(fp, 'makeRequest').mockResolvedValue({ accessToken: 'rotated', authuser: 1 });
+    const originalWindow = (globalThis as { window?: unknown }).window;
+    (globalThis as { window?: unknown }).window = { location: { hostname: 'accounts.oxy.so' } };
+    try {
+      const authuser = await fp.establishDeviceRefreshSlot();
+      expect(authuser).toBe(1);
+      expect(fpSpy).toHaveBeenCalledWith('POST', '/auth/session', undefined, { cache: false });
+    } finally {
+      if (originalWindow === undefined) {
+        delete (globalThis as { window?: unknown }).window;
+      } else {
+        (globalThis as { window?: unknown }).window = originalWindow;
+      }
+      fpSpy.mockRestore();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AuthManager.handleAuthSuccess — every web primary now joins the device set
+// ---------------------------------------------------------------------------
+
+class InMemoryStorage implements StorageAdapter {
+  private store = new Map<string, string>();
+  getItem(key: string): string | null { return this.store.get(key) ?? null; }
+  setItem(key: string, value: string): void { this.store.set(key, value); }
+  removeItem(key: string): void { this.store.delete(key); }
+  raw(): Map<string, string> { return this.store; }
+}
+
+interface MockHttpService {
+  setTokens: jest.Mock;
+  setAuthRefreshHandler: jest.Mock;
+}
+
+interface MockServices {
+  establishDeviceRefreshSlot: jest.Mock<Promise<number | null>, []>;
+  getAccessToken: jest.Mock<string | null, []>;
+  refreshAllSessions: jest.Mock<Promise<RefreshAllResponse>, []>;
+  refreshTokenViaCookie: jest.Mock<Promise<RefreshCookieResponse | null>, [{ authuser?: number }]>;
+  logoutSessionByAuthuser: jest.Mock<Promise<void>, [number]>;
+  logoutAllSessionsViaCookie: jest.Mock<Promise<void>, []>;
+  getCurrentUser: jest.Mock<Promise<User>, []>;
+  httpService: MockHttpService;
+}
+
+const ACTIVE_AUTHUSER_KEY = 'oxy_active_authuser';
+
+function makeMockServices(): MockServices {
+  return {
+    establishDeviceRefreshSlot: jest.fn(async () => null),
+    getAccessToken: jest.fn(() => null),
+    refreshAllSessions: jest.fn(async (): Promise<RefreshAllResponse> => ({ accounts: [] })),
+    refreshTokenViaCookie: jest.fn(),
+    logoutSessionByAuthuser: jest.fn(async () => undefined),
+    logoutAllSessionsViaCookie: jest.fn(async () => undefined),
+    getCurrentUser: jest.fn(async (): Promise<User> => ({ id: 'user-fedcm', publicKey: '0xabc', username: 'nate' } as User)),
+    httpService: { setTokens: jest.fn(), setAuthRefreshHandler: jest.fn() },
+  };
+}
+
+function makeManager(services: MockServices, storage: InMemoryStorage): AuthManager {
+  return new AuthManager(services as unknown as OxyServices, {
+    storage,
+    autoRefresh: false,
+    crossTabSync: false,
+  });
+}
+
+function fedcmSession(): SessionLoginResponse {
+  // No `authuser` claim in the FedCM-restored token — mirrors a cross-domain
+  // restore whose token is not slot-bound until /auth/session runs.
+  return {
+    accessToken: buildAccessToken({ sessionId: 'sess-fedcm', userId: 'user-fedcm', exp: 9999999999 }),
+    sessionId: 'sess-fedcm',
+    deviceId: 'dev-1',
+    expiresAt: '2099-01-01T00:00:00.000Z',
+    user: { id: 'user-fedcm', username: 'nate', name: { displayName: 'Nate' } },
+  } as SessionLoginResponse;
+}
+
+describe('AuthManager.handleAuthSuccess — primary session joins the device set', () => {
+  it('establishes the device refresh slot and adopts the server-authoritative authuser', async () => {
+    const services = makeMockServices();
+    // /auth/session allocated slot 3 and rotated the token.
+    services.establishDeviceRefreshSlot.mockResolvedValueOnce(3);
+    const rotated = buildAccessToken({ sessionId: 'sess-fedcm', userId: 'user-fedcm', authuser: 3, exp: 9999999999 });
+    services.getAccessToken.mockReturnValue(rotated);
+    const storage = new InMemoryStorage();
+    const manager = makeManager(services, storage);
+
+    await manager.handleAuthSuccess(fedcmSession(), 'fedcm');
+
+    expect(services.establishDeviceRefreshSlot).toHaveBeenCalledTimes(1);
+    // The authoritative slot from /auth/session is recorded as the active account.
+    expect(manager.getActiveAuthuser()).toBe(3);
+    expect(storage.raw().get(ACTIVE_AUTHUSER_KEY)).toBe('3');
+    expect(manager.getActiveAccount()?.authuser).toBe(3);
+  });
+
+  it('falls back to the JWT-decoded authuser (then 0) when /auth/session is a no-op (native / cross-apex)', async () => {
+    const services = makeMockServices();
+    services.establishDeviceRefreshSlot.mockResolvedValueOnce(null);
+    const storage = new InMemoryStorage();
+    const manager = makeManager(services, storage);
+
+    // FedCM session token carries no authuser claim → falls back to slot 0.
+    await manager.handleAuthSuccess(fedcmSession(), 'fedcm');
+
+    expect(manager.getActiveAuthuser()).toBe(0);
+    // getAccessToken() is only consulted for the rotated token when a slot was
+    // actually established — a null slot must not re-read it.
+    expect(services.getAccessToken).not.toHaveBeenCalled();
+  });
+});

package/src/i18n/locales/ar-SA.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "قائمة الحساب",
     "manage": "إدارة حساب Oxy الخاص بك",
+    "viewProfile": "عرض الملف الشخصي",
     "addAnother": "إضافة حساب آخر",
     "signOutAll": "تسجيل الخروج من جميع الحسابات",
     "open": "قائمة الحساب",

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

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menú del compte",
     "manage": "Gestiona el teu compte d'Oxy",
+    "viewProfile": "Mostra el perfil",
     "addAnother": "Afegeix un altre compte",
     "signOutAll": "Tanca la sessió de tots els comptes",
     "open": "Menú del compte",

package/src/i18n/locales/de-DE.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Kontomenü",
     "manage": "Ihr Oxy-Konto verwalten",
+    "viewProfile": "Profil ansehen",
     "addAnother": "Weiteres Konto hinzufügen",
     "signOutAll": "Von allen Konten abmelden",
     "open": "Kontomenü",

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

@@ -1555,6 +1555,7 @@
   "accountMenu": {
     "label": "Account menu",
     "manage": "Manage your Oxy Account",
+    "viewProfile": "View profile",
     "addAnother": "Add another account",
     "signOutAll": "Sign out of all accounts",
     "open": "Account menu",

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

@@ -1555,6 +1555,7 @@
   "accountMenu": {
     "label": "Menú de cuenta",
     "manage": "Gestiona tu cuenta de Oxy",
+    "viewProfile": "Ver perfil",
     "addAnother": "Añadir otra cuenta",
     "signOutAll": "Cerrar sesión en todas las cuentas",
     "open": "Menú de cuenta",

package/src/i18n/locales/fr-FR.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu du compte",
     "manage": "Gérer votre compte Oxy",
+    "viewProfile": "Voir le profil",
     "addAnother": "Ajouter un autre compte",
     "signOutAll": "Se déconnecter de tous les comptes",
     "open": "Menu du compte",

package/src/i18n/locales/it-IT.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu account",
     "manage": "Gestisci il tuo account Oxy",
+    "viewProfile": "Visualizza profilo",
     "addAnother": "Aggiungi un altro account",
     "signOutAll": "Esci da tutti gli account",
     "open": "Menu account",

package/src/i18n/locales/ja-JP.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "アカウントメニュー",
     "manage": "Oxy アカウントを管理",
+    "viewProfile": "プロフィールを表示",
     "addAnother": "別のアカウントを追加",
     "signOutAll": "すべてのアカウントからログアウト",
     "open": "アカウントメニュー",

package/src/i18n/locales/ko-KR.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "계정 메뉴",
     "manage": "Oxy 계정 관리",
+    "viewProfile": "프로필 보기",
     "addAnother": "다른 계정 추가",
     "signOutAll": "모든 계정에서 로그아웃",
     "open": "계정 메뉴",

package/src/i18n/locales/pt-PT.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu da conta",
     "manage": "Gerir a sua conta Oxy",
+    "viewProfile": "Ver perfil",
     "addAnother": "Adicionar outra conta",
     "signOutAll": "Terminar sessão em todas as contas",
     "open": "Menu da conta",

package/src/i18n/locales/zh-CN.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "账户菜单",
     "manage": "管理您的 Oxy 账户",
+    "viewProfile": "查看个人资料",
     "addAnother": "添加其他账户",
     "signOutAll": "退出所有账户",
     "open": "账户菜单",

package/src/index.ts

@@ -325,6 +325,7 @@ export type {
     AssetUpdateVisibilityRequest,
     AssetUpdateVisibilityResponse,
     ServiceAssetMetadata,
+    ServiceAssetMetadataBySha,
     AccountStorageCategoryUsage,
     AccountStorageUsageResponse,
     SecurityEventType,
@@ -539,12 +540,14 @@ export {
     ssoNoSessionKey,
     ssoAttemptedKey,
     ssoPriorSessionKey,
+    ssoSignedOutKey,
     ssoCallbackBootstrapKey,
     ssoNavigate,
     getSsoCallbackBootstrapScript,
     buildSsoBounceUrl,
     isCentralIdPOrigin,
     guardActive,
+    silentRestoreSuppressed,
     allowSsoBounce,
 } from './utils/ssoBounce';
 export type { SsoBounceGate } from './utils/ssoBounce';

package/src/mixins/OxyServices.accounts.ts

@@ -35,8 +35,6 @@ import type { User } from '../models/interfaces';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { normalizeUserIdentity } from '../utils/userIdentity';
-import { isWeb } from '../utils/platform';
-import { logger } from '../utils/loggerUtils';
 import { CACHE_TIMES } from './mixinHelpers';
 
 // ---------------------------------------------------------------------------
@@ -564,37 +562,16 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
 
         // Register the switched session in the device's multi-account set by
         // establishing its first-party refresh cookie. This MUST be a separate
-        // call to `POST /auth/session`: the switch route is at `/accounts/*`,
-        // outside the `oxy_rt_<authuser>` cookie's `Path=/auth` scope, so it can
-        // never read the device's existing slots and would overwrite slot 0
-        // (destroying the operator's own session). `/auth/session` runs where the
-        // cookies ARE visible, so the server allocates a NEW slot that coexists
-        // with the operator's and returns its `authuser`. Web-only; best-effort.
-        let authuser = res.authuser;
-        if (isWeb()) {
-          try {
-            const established = await this.makeRequest<{ accessToken?: string; authuser?: number }>(
-              'POST',
-              '/auth/session',
-              undefined,
-              { cache: false },
-            );
-            if (typeof established?.authuser === 'number') {
-              authuser = established.authuser;
-            }
-            // /auth/session mints a fresh access token off the same session;
-            // re-plant it so the active token matches the rotated cookie.
-            if (established?.accessToken) {
-              this.setTokens(established.accessToken);
-            }
-          } catch (error) {
-            logger.warn(
-              '[OxyServices] Failed to establish device refresh cookie after account switch; the switch is active in-session but may not survive a reload',
-              { component: 'OxyServices', method: 'switchToAccount' },
-              error,
-            );
-          }
-        }
+        // call to `POST /auth/session` (the shared `establishDeviceRefreshSlot`
+        // primitive): the switch route is at `/accounts/*`, outside the
+        // `oxy_rt_<authuser>` cookie's `Path=/auth` scope, so it can never read
+        // the device's existing slots and would overwrite slot 0 (destroying the
+        // operator's own session). `/auth/session` runs where the cookies ARE
+        // visible, so the server allocates a NEW slot that coexists with the
+        // operator's and returns its `authuser`. Web-only; best-effort (the helper
+        // re-plants the rotated access token and returns `null` on native/failure).
+        const establishedAuthuser = await this.establishDeviceRefreshSlot();
+        const authuser = establishedAuthuser ?? res.authuser;
 
         // Identity changed → drop the entire GET response cache so no entry
         // personalised for the previous identity is reused. Cache keys are

package/src/mixins/OxyServices.assets.ts

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor, ServiceAssetMetadata } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
 import { logger } from '../utils/loggerUtils';
@@ -12,6 +12,21 @@ import { extractErrorStatus } from '../utils/errorUtils';
  */
 const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
 
+/**
+ * Maximum number of content hashes sent per `POST /assets/service/by-sha256`
+ * request. Matches the server-side cap (the route rejects empty or > 100 hash
+ * arrays with a 400); larger inputs are chunked and merged. Same ceiling as
+ * {@link SERVICE_ASSET_METADATA_CHUNK_SIZE} for the forward id lookup.
+ */
+const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
+
+/**
+ * Lowercase hex SHA-256 digest matcher (exactly 64 hex chars). The reverse
+ * lookup drops non-conforming hashes client-side so a single malformed value
+ * never 400s an otherwise-valid chunk on the server.
+ */
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -261,6 +276,82 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       return settled.flat();
     }
 
+    /**
+     * Reverse content-address lookup: resolve many content `sha256` digests to
+     * the servable Oxy asset holding each, in one round-trip per chunk via
+     * `POST /assets/service/by-sha256` (body `{ sha256s }`).
+     *
+     * This is the INVERSE of {@link getServiceAssetMetadataByIds}: given a
+     * record's `blob.sha256`, it returns the asset's `id`, `mime`, byte `size`,
+     * `status`, and — for active, public, CDN-reachable assets only — a public
+     * `url` (`cloud.oxy.so`). Built for server-to-server callers (e.g. Mention's
+     * MTN materializer / node-blob sync) that hold a content hash and need to
+     * map it back to a servable asset. Hashes are lowercased, validated against
+     * a 64-char hex pattern (malformed entries dropped client-side), and
+     * deduplicated before being split into chunks of
+     * {@link SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE} (the server-side cap). The
+     * server omits unknown/deleted hashes from each chunk's `data`, so the
+     * merged result may be shorter than the requested list and the caller is
+     * expected to map by `sha256`.
+     *
+     * **Service-token auth (required).** `/assets/service/by-sha256` is guarded
+     * by `serviceAuthMiddleware` + the `files:read` scope and is called via
+     * `makeServiceRequest` (`Authorization: Bearer <serviceToken>`, `cache:false`).
+     * The calling client MUST be service-configured (`configureServiceAuth`)
+     * before invoking; 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 —
+     * every entry that resolved is still returned. An empty input (or one whose
+     * every value is malformed) resolves immediately with `[]` and performs no
+     * network call.
+     *
+     * Not cached at the SDK layer: it's a POST keyed on a multi-hash body (low
+     * hit rate), mirroring the sibling service/POST methods which never cache.
+     */
+    async getServiceAssetMetadataBySha256(sha256s: string[]): Promise<ServiceAssetMetadataBySha[]> {
+      const uniqueShas = Array.from(
+        new Set(
+          sha256s
+            .filter((sha): sha is string => typeof sha === 'string')
+            .map((sha) => sha.trim().toLowerCase())
+            .filter((sha) => SHA256_HEX_PATTERN.test(sha)),
+        ),
+      );
+      if (uniqueShas.length === 0) {
+        return [];
+      }
+
+      const chunks: string[][] = [];
+      for (let i = 0; i < uniqueShas.length; i += SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE) {
+        chunks.push(uniqueShas.slice(i, i + SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE));
+      }
+
+      // Run chunks concurrently; a single chunk failure must not sink the rest.
+      const settled = await Promise.all(
+        chunks.map(async (chunk): Promise<ServiceAssetMetadataBySha[]> => {
+          try {
+            const entries = await this.makeServiceRequest<ServiceAssetMetadataBySha[]>(
+              'POST',
+              '/assets/service/by-sha256',
+              { sha256s: chunk },
+            );
+            return Array.isArray(entries) ? entries : [];
+          } catch (error: unknown) {
+            logger.warn('getServiceAssetMetadataBySha256: chunk failed, continuing with remaining chunks', {
+              method: 'getServiceAssetMetadataBySha256',
+              chunkSize: chunk.length,
+              status: extractErrorStatus(error),
+              error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+          }
+        }),
+      );
+
+      return settled.flat();
+    }
+
     /**
      * Upload raw file data
      */

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

@@ -0,0 +1,135 @@
+/**
+ * `getServiceAssetMetadataBySha256` mixin tests (reverse content-address lookup).
+ *
+ * Stubs `makeServiceRequest` (the service-token transport used by the route's
+ * `serviceAuthMiddleware` + `files:read` scope) so the tests run with no network
+ * and no `getServiceToken()` round-trip, then asserts:
+ *  - empty / whitespace / all-malformed input no-ops to `[]` with no network call;
+ *  - hashes are lowercased, hex-validated (malformed dropped), and de-duplicated,
+ *    and a single chunk is POSTed to `/assets/service/by-sha256` as `{ sha256s }`;
+ *  - the `{ data }` envelope is unwrapped to a bare `ServiceAssetMetadataBySha[]`
+ *    (mirroring how `makeServiceRequest<T[]>` returns the inner array), with the
+ *    optional `url` preserved for public assets and absent for private ones;
+ *  - inputs > 100 hashes are chunked at 100/request and merged;
+ *  - a failed chunk is logged and skipped — successful chunks still return.
+ */
+
+import type { ServiceAssetMetadataBySha } from '../../models/interfaces';
+import { OxyServices } from '../../OxyServices';
+
+const publicEntry: ServiceAssetMetadataBySha = {
+  sha256: 'a'.repeat(64),
+  id: 'asset-1',
+  mime: 'image/jpeg',
+  size: 12345,
+  status: 'active',
+  url: 'https://cloud.oxy.so/content/2026/06/aa/abc.jpg',
+};
+
+const privateEntry: ServiceAssetMetadataBySha = {
+  sha256: 'b'.repeat(64),
+  id: 'asset-2',
+  mime: 'application/octet-stream',
+  size: 7,
+  status: 'active',
+  // no url — private/unlisted assets stream through the origin
+};
+
+describe('OxyServices.assets — getServiceAssetMetadataBySha256', () => {
+  let oxy: OxyServices;
+  let makeServiceRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeServiceRequestSpy = jest.spyOn(oxy, 'makeServiceRequest');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('returns [] and performs no network call for empty / malformed input', async () => {
+    await expect(oxy.getServiceAssetMetadataBySha256([])).resolves.toEqual([]);
+    // whitespace, wrong length, and non-hex are all dropped → no chunk to send
+    await expect(
+      oxy.getServiceAssetMetadataBySha256(['   ', 'zzz', 'a'.repeat(63), 'a'.repeat(65)]),
+    ).resolves.toEqual([]);
+    expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+  });
+
+  it('lowercases, hex-validates, de-duplicates, and sends a single chunk', async () => {
+    // makeServiceRequest unwraps the API's `{ data }` envelope, so the resolved
+    // value is the bare array (NOT `{ data: [...] }`) — mirror that real shape.
+    makeServiceRequestSpy.mockResolvedValueOnce([publicEntry, privateEntry]);
+
+    const result = await oxy.getServiceAssetMetadataBySha256([
+      'A'.repeat(64), // uppercase → normalized to 'a'*64
+      'a'.repeat(64), // duplicate after lowercasing
+      'B'.repeat(64),
+      'not-hex', // dropped
+      '   ', // dropped
+    ]);
+
+    expect(result).toEqual([publicEntry, privateEntry]);
+    // public asset carries url; private one does not
+    expect(result[0].url).toBe(publicEntry.url);
+    expect(result[1].url).toBeUndefined();
+
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(1);
+    expect(makeServiceRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/assets/service/by-sha256',
+      { sha256s: ['a'.repeat(64), 'b'.repeat(64)] },
+    );
+  });
+
+  it('chunks at 100 hashes per request and merges each chunk', async () => {
+    // 250 distinct valid hex digests.
+    const shas = Array.from({ length: 250 }, (_, i) =>
+      i.toString(16).padStart(64, '0'),
+    );
+
+    makeServiceRequestSpy.mockImplementation(
+      async (
+        _method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+        _url: string,
+        data?: { sha256s: string[] },
+      ): Promise<ServiceAssetMetadataBySha[]> =>
+        (data?.sha256s ?? []).map((sha) => ({
+          sha256: sha,
+          id: `asset-${sha}`,
+          mime: 'application/octet-stream',
+          size: 1,
+          status: 'active' as const,
+        })),
+    );
+
+    const result = await oxy.getServiceAssetMetadataBySha256(shas);
+
+    // 250 unique hashes => 100 + 100 + 50 across three POSTs.
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(3);
+    const chunkSizes = makeServiceRequestSpy.mock.calls.map(
+      (call) => (call[2] as { sha256s: string[] }).sha256s.length,
+    );
+    expect(chunkSizes).toEqual([100, 100, 50]);
+
+    expect(result).toHaveLength(250);
+    expect(result[0].sha256).toBe(shas[0]);
+    expect(result[249].sha256).toBe(shas[249]);
+  });
+
+  it('skips a failed chunk and returns the entries that resolved', async () => {
+    const shas = Array.from({ length: 150 }, (_, i) =>
+      i.toString(16).padStart(64, '0'),
+    );
+
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([publicEntry]) // first chunk (100 hashes) succeeds
+      .mockRejectedValueOnce(new Error('chunk failed')); // second chunk (50) fails
+
+    const result = await oxy.getServiceAssetMetadataBySha256(shas);
+
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
+    expect(result).toEqual([publicEntry]);
+  });
+});