@oxyhq/core 5.1.1 → 5.2.0

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/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]);
+  });
+});

package/src/models/interfaces.ts

@@ -533,6 +533,30 @@ export interface ServiceAssetMetadata {
   status: 'active' | 'trash';
 }
 
+/**
+ * Reverse-lookup asset metadata returned by `POST /assets/service/by-sha256`.
+ *
+ * Resolves a content-addressed `sha256` digest back to the live Oxy asset that
+ * holds those bytes: its file `id`, MIME type, byte `size`, storage `status`,
+ * and — for active, public, CDN-reachable assets only — a public `url`
+ * (`cloud.oxy.so`). This is the inverse of {@link ServiceAssetMetadata}: it lets
+ * a `files:read`-scoped service-to-server caller (e.g. Mention's MTN materializer
+ * / node-blob sync) turn a record's `blob.sha256` into a servable asset.
+ *
+ * `url` is omitted for private/unlisted assets (and for public assets whose
+ * bytes are not yet CDN-reachable) — those must be streamed through the origin.
+ * Unknown or deleted hashes are omitted from the response (never error the whole
+ * batch), so the result may be shorter than the requested hash list.
+ */
+export interface ServiceAssetMetadataBySha {
+  sha256: string;
+  id: string;
+  mime: string;
+  size: number;
+  status: 'active' | 'trash';
+  url?: string;
+}
+
 /**
  * Account storage usage (server-side usage, not local AsyncStorage)
  */

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

@@ -16,9 +16,11 @@ import {
   ssoNoSessionKey,
   ssoAttemptedKey,
   ssoPriorSessionKey,
+  ssoSignedOutKey,
   buildSsoBounceUrl,
   isCentralIdPOrigin,
   guardActive,
+  silentRestoreSuppressed,
   allowSsoBounce,
 } from '../ssoBounce';
 import { CENTRAL_AUTH_URL } from '../authWebUrl';
@@ -40,11 +42,50 @@ describe('per-origin key builders', () => {
     expect(ssoNoSessionKey(origin)).toBe('oxy_sso_no_session:https://mention.earth');
     expect(ssoAttemptedKey(origin)).toBe('oxy_sso_attempted:https://mention.earth');
     expect(ssoPriorSessionKey(origin)).toBe('oxy_sso_prior_session:https://mention.earth');
+    expect(ssoSignedOutKey(origin)).toBe('oxy_signed_out:https://mention.earth');
   });
 
   it('namespaces keys per origin so two RPs never collide', () => {
     expect(ssoStateKey('https://a.test')).not.toBe(ssoStateKey('https://b.test'));
     expect(ssoPriorSessionKey('https://a.test')).not.toBe(ssoPriorSessionKey('https://b.test'));
+    expect(ssoSignedOutKey('https://a.test')).not.toBe(ssoSignedOutKey('https://b.test'));
+  });
+});
+
+describe('silentRestoreSuppressed (deliberately-signed-out gate)', () => {
+  const origin = 'https://accounts.oxy.so';
+
+  function storageWith(value: string | null): Pick<Storage, 'getItem'> {
+    return { getItem: (key: string) => (key === ssoSignedOutKey(origin) ? value : null) };
+  }
+
+  it('is SUPPRESSED when the signed-out flag is set to "1" for this origin', () => {
+    expect(silentRestoreSuppressed(storageWith('1'), origin)).toBe(true);
+  });
+
+  it('is NOT suppressed when the flag is absent (normal restore)', () => {
+    expect(silentRestoreSuppressed(storageWith(null), origin)).toBe(false);
+  });
+
+  it('is NOT suppressed for any non-"1" value (only the exact set value gates)', () => {
+    expect(silentRestoreSuppressed(storageWith('0'), origin)).toBe(false);
+    expect(silentRestoreSuppressed(storageWith(''), origin)).toBe(false);
+  });
+
+  it('is per-origin: another origin\'s flag does not suppress this one', () => {
+    const otherOriginFlag: Pick<Storage, 'getItem'> = {
+      getItem: (key: string) => (key === ssoSignedOutKey('https://other.test') ? '1' : null),
+    };
+    expect(silentRestoreSuppressed(otherOriginFlag, origin)).toBe(false);
+  });
+
+  it('fails safe (NOT suppressed, never throws) when getItem throws', () => {
+    const throwing: Pick<Storage, 'getItem'> = {
+      getItem: () => {
+        throw new Error('storage locked');
+      },
+    };
+    expect(silentRestoreSuppressed(throwing, origin)).toBe(false);
   });
 });