@oxyhq/core 5.1.0 → 5.2.0

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/mixins/__tests__/getUsersByIds.test.ts

@@ -0,0 +1,149 @@
+/**
+ * `getUsersByIds` dual-mode auth tests.
+ *
+ * `POST /users/by-ids` is `optionalUserOrServiceAuth` on oxy-api and returns
+ * the identical public `{ data: PublicUserProfile[] }` shape for both a service
+ * token and a user session. The SDK method must therefore:
+ *  - use the bearer-SERVICE path (`makeServiceRequest`) when the instance was
+ *    configured via `configureServiceAuth()` (the backend / hydration case), and
+ *  - use the USER path (`makeRequest('POST', ..., { cache: false })`) otherwise
+ *    (a browser / RN client with only a user session). Before the dual-mode fix
+ *    the method always took the service path, so every client-side caller got
+ *    `[]` because `getServiceToken()` had no credentials.
+ *
+ * Both paths must dedup + chunk, map every result through `normalizeUserIdentity`
+ * (so `name.displayName` is present), and tolerate a per-chunk failure without
+ * sinking the rest. `makeRequest` / `makeServiceRequest` are stubbed so the
+ * tests run with no network.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { User } from '../../models/interfaces';
+
+const makeRawUser = (id: string): User =>
+  // The wire payload is a PublicUserProfile with server-owned name.displayName.
+  // Cast through the User shape the API returns post-unwrap.
+  ({
+    id,
+    username: `user_${id}`,
+    name: { displayName: `Display ${id}` },
+    _count: { followers: 1, following: 2 },
+  }) as unknown as User;
+
+describe('OxyServices.getUsersByIds — dual-mode auth', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+  let makeServiceRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+    makeServiceRequestSpy = jest.spyOn(
+      oxy as unknown as { makeServiceRequest: jest.Mock },
+      'makeServiceRequest',
+    );
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('returns [] and performs no network call for empty / whitespace input', async () => {
+    await expect(oxy.getUsersByIds([])).resolves.toEqual([]);
+    await expect(oxy.getUsersByIds(['', '   '])).resolves.toEqual([]);
+    expect(makeRequestSpy).not.toHaveBeenCalled();
+    expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+  });
+
+  describe('without service credentials (client / user-session path)', () => {
+    it('uses makeRequest with the user bearer and cache:false', async () => {
+      makeRequestSpy.mockResolvedValueOnce([makeRawUser('a'), makeRawUser('b')]);
+
+      const result = await oxy.getUsersByIds(['a', 'b']);
+
+      expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/users/by-ids',
+        { ids: ['a', 'b'] },
+        { cache: false },
+      );
+      // normalizeUserIdentity ran on every entry (display name preserved).
+      expect(result).toHaveLength(2);
+      expect(result[0].name.displayName).toBe('Display a');
+      expect(result[1].id).toBe('b');
+    });
+
+    it('de-duplicates ids and drops blanks before the request', async () => {
+      makeRequestSpy.mockResolvedValueOnce([makeRawUser('a')]);
+
+      await oxy.getUsersByIds(['a', 'a', '   ', 'a']);
+
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/users/by-ids',
+        { ids: ['a'] },
+        { cache: false },
+      );
+    });
+  });
+
+  describe('with service credentials (backend / hydration path)', () => {
+    beforeEach(() => {
+      oxy.configureServiceAuth('oxy_dk_key', 'secret');
+    });
+
+    it('uses makeServiceRequest and never the user path — unchanged behavior', async () => {
+      makeServiceRequestSpy.mockResolvedValueOnce([makeRawUser('a'), makeRawUser('b')]);
+
+      const result = await oxy.getUsersByIds(['a', 'b']);
+
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+      expect(makeServiceRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeServiceRequestSpy).toHaveBeenCalledWith('POST', '/users/by-ids', {
+        ids: ['a', 'b'],
+      });
+      expect(result).toHaveLength(2);
+      expect(result[0].name.displayName).toBe('Display a');
+    });
+  });
+
+  describe('chunking + resilience (applies to both modes)', () => {
+    it('chunks at 100 ids per request on the user path and flattens results', async () => {
+      const ids = Array.from({ length: 250 }, (_, i) => `id-${i}`);
+      makeRequestSpy.mockImplementation(
+        async (
+          _method: string,
+          _url: string,
+          data?: { ids: string[] },
+        ): Promise<User[]> => (data?.ids ?? []).map((id) => makeRawUser(id)),
+      );
+
+      const result = await oxy.getUsersByIds(ids);
+
+      // 250 unique ids => 100 + 100 + 50 across three POSTs.
+      expect(makeRequestSpy).toHaveBeenCalledTimes(3);
+      const chunkSizes = makeRequestSpy.mock.calls.map(
+        (call) => (call[2] as { ids: string[] }).ids.length,
+      );
+      expect(chunkSizes).toEqual([100, 100, 50]);
+      expect(result).toHaveLength(250);
+    });
+
+    it('skips a failed chunk and returns the users that resolved (user path)', async () => {
+      const ids = Array.from({ length: 150 }, (_, i) => `id-${i}`);
+      makeRequestSpy
+        .mockResolvedValueOnce([makeRawUser('id-0')])
+        .mockRejectedValueOnce(new Error('chunk boom'));
+
+      const result = await oxy.getUsersByIds(ids);
+
+      expect(makeRequestSpy).toHaveBeenCalledTimes(2);
+      // The failed second chunk contributes nothing; the first survives.
+      expect(result).toHaveLength(1);
+      expect(result[0].id).toBe('id-0');
+    });
+  });
+});

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);
   });
 });
 

package/src/utils/ssoBounce.ts

@@ -69,6 +69,7 @@ const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
 const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
 const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
+const SIGNED_OUT_KEY_PREFIX = 'oxy_signed_out:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -125,6 +126,37 @@ export function ssoPriorSessionKey(origin: string): string {
   return `${PRIOR_SESSION_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin DURABLE "the user DELIBERATELY signed out on this device/origin"
+ * flag.
+ *
+ * Like {@link ssoPriorSessionKey} this lives in DURABLE storage (web
+ * `localStorage`; services uses its own `storageKeyPrefix`-scoped key), NOT the
+ * per-tab `sessionStorage` the loop-breaker keys use — it must survive a reload.
+ *
+ * It exists purely to suppress AUTOMATIC silent restore after a deliberate
+ * sign-out: a still-live IdP session (the central `fedcm_session` / the FedCM
+ * credential association) would otherwise let `fedcm-silent` / the per-apex
+ * `/auth/silent` iframe re-mint a session on the very next cold boot, so a user
+ * who pressed "Sign out" gets silently signed back in on reload. With this flag
+ * set, those silent cold-boot steps are skipped while the Gmail-style
+ * returning-account fast-path is otherwise preserved.
+ *
+ * Lifecycle (mirrors the existing gate machinery — set on a definitive event,
+ * cleared on its inverse):
+ *   - SET on EXPLICIT full sign-out (alongside clearing the prior-session hint
+ *     and the SSO bounce state).
+ *   - CLEARED on ANY deliberate sign-in (password, FedCM, account switch, device
+ *     claim) so a real sign-in fully re-enables silent restore — there is no
+ *     "stuck signed out" state.
+ *
+ * NOTE: this gates only AUTOMATIC/silent restore. An INTERACTIVE sign-in always
+ * clears it first, so the user can always sign back in.
+ */
+export function ssoSignedOutKey(origin: string): string {
+  return `${SIGNED_OUT_KEY_PREFIX}${origin}`;
+}
+
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -267,6 +299,35 @@ export function guardActive(
   return now - ts < SSO_GUARD_TTL_MS;
 }
 
+/**
+ * Whether AUTOMATIC silent restore is SUPPRESSED for this origin because the
+ * user deliberately signed out (the durable {@link ssoSignedOutKey} flag).
+ *
+ * When `true`, the silent cold-boot steps that can re-mint a session from a
+ * still-live IdP session WITHOUT user intent — `fedcm-silent` and the per-apex
+ * `/auth/silent` iframe — MUST be skipped, so a user who pressed "Sign out" is
+ * not silently signed back in on the next reload. Interactive sign-in clears the
+ * flag, so this never blocks a deliberate re-sign-in.
+ *
+ * Defensive: a `getItem` that throws (locked/disabled storage) is treated as NOT
+ * suppressed, so the gate fails toward the normal restore behaviour rather than
+ * wedging the user out.
+ *
+ * @param storage - The DURABLE storage to read (web `localStorage`; injected for
+ *   testability).
+ * @param origin - The page origin whose signed-out flag to evaluate.
+ */
+export function silentRestoreSuppressed(
+  storage: Pick<Storage, 'getItem'>,
+  origin: string,
+): boolean {
+  try {
+    return storage.getItem(ssoSignedOutKey(origin)) === '1';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Inputs to the smart {@link allowSsoBounce} gate.
  */