@oxyhq/core 5.1.0 → 5.2.0

package/src/OxyServices.base.ts

@@ -9,6 +9,9 @@ import { handleHttpError } from './utils/errorUtils';
 import { HttpService, type AuthRefreshReason, type RequestOptions } from './HttpService';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import { resolveCentralAuthUrl } from './utils/authWebUrl';
+import { isWeb } from './utils/platform';
+import { registrableApex } from './utils/fapiAutoDetect';
+import { logger } from './utils/loggerUtils';
 
 export interface OxyConfig extends OxyConfigBase {
   cloudURL?: string;
@@ -310,6 +313,82 @@ export class OxyServicesBase {
     return this.httpService.getAccessToken();
   }
 
+  /**
+   * Register the CURRENTLY-ACTIVE session in the device's first-party
+   * multi-account refresh-cookie set by calling `POST /auth/session`.
+   *
+   * This is the single, shared primitive every web primary-session commit and the
+   * account switch use to plant their `oxy_rt_<authuser>` slot. It MUST be a
+   * dedicated call to `/auth/session` rather than relying on whichever endpoint
+   * established the session: that endpoint is frequently OUTSIDE the cookie's
+   * `Path=/auth` scope (`/accounts/:id/switch`) or is a cross-origin/credential-
+   * less restore (`/sso/exchange`, the IdP `/auth/silent` postMessage) that cannot
+   * set an `api.oxy.so` cookie at all. `/auth/session` runs where the device's
+   * existing slots ARE visible, so the server resolves this user's slot (reusing an
+   * existing one or allocating a new one) without clobbering a sibling account,
+   * mints a fresh access token bound to the same session, and returns the resolved
+   * `authuser`.
+   *
+   * Behaviour:
+   * - Requires a planted bearer (the caller must have already installed the
+   *   session's access token); `/auth/session` derives the session from it.
+   * - On success re-plants the rotated access token (so the active token matches
+   *   the freshly-rotated cookie) and returns the device `authuser` slot.
+   * - WEB-ONLY: on native there are no first-party refresh cookies → returns
+   *   `null`.
+   * - FIRST-PARTY-ONLY: the cookie is host-only on the API host with
+   *   `SameSite=Lax`, so it only sticks when the page is SAME-SITE (same
+   *   registrable apex) as the API. On a cross-apex RP (`mention.earth` calling
+   *   `api.oxy.so`) the browser rejects the `Set-Cookie` as a third-party cookie,
+   *   so a returned slot would be a phantom never enumerated by `refresh-all`.
+   *   Those RPs durably restore via the per-apex `/auth/silent` iframe + `/sso`
+   *   bounce, NOT this device set → returns `null` without calling the API.
+   * - BEST-EFFORT: a failure (e.g. transient network) never throws — the session
+   *   stays active in-memory; only its reload durability via the device set is at
+   *   risk. The caller treats `null` as "not registered in the device set".
+   *
+   * @returns The resolved device `authuser` slot, or `null` on native / cross-apex
+   *   / failure.
+   */
+  public async establishDeviceRefreshSlot(): Promise<number | null> {
+    if (!isWeb()) {
+      return null;
+    }
+    if (typeof window !== 'undefined' && window.location?.hostname) {
+      const pageApex = registrableApex(window.location.hostname);
+      let apiApex: string | null = null;
+      try {
+        apiApex = registrableApex(new URL(this.getBaseURL()).hostname);
+      } catch {
+        apiApex = null;
+      }
+      if (!pageApex || !apiApex || pageApex !== apiApex) {
+        return null;
+      }
+    }
+    try {
+      const established = await this.makeRequest<{ accessToken?: string; authuser?: number }>(
+        'POST',
+        '/auth/session',
+        undefined,
+        { cache: false },
+      );
+      // `/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);
+      }
+      return typeof established?.authuser === 'number' ? established.authuser : null;
+    } catch (error) {
+      logger.warn(
+        '[OxyServices] Failed to establish device refresh cookie via POST /auth/session; the session is active in-session but may not survive a reload as part of the device account set',
+        { component: 'OxyServices', method: 'establishDeviceRefreshSlot' },
+        error,
+      );
+      return null;
+    }
+  }
+
   /**
    * Decode the current access token and return its `exp` claim in SECONDS since
    * the Unix epoch (the raw JWT `exp` unit), or `null` when there is no token,

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/OxyServices.user.ts

@@ -88,6 +88,18 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       userId?: string,
     ) => Promise<R>;
 
+    /**
+     * Raw service credentials stored by `configureServiceAuth()` on the auth
+     * mixin (earlier in the pipeline). Surfaced here via `declare` — for the
+     * same typing reason as `makeServiceRequest` above — so `getUsersByIds` can
+     * detect whether this instance is service-configured (a backend) and pick
+     * the bearer-service path, or fall back to the user-session path (a browser/
+     * RN client). Both are `null` until `configureServiceAuth(apiKey, apiSecret)`
+     * is called.
+     */
+    declare _serviceApiKey: string | null;
+    declare _serviceApiSecret: string | null;
+
     /**
      * Get profile by username
      */
@@ -349,16 +361,28 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * by `id`); each is run through `normalizeUserIdentity`, matching
      * `getUserById`.
      *
-     * **Service-token auth (required).** `/users/by-ids` is a server-to-server
-     * bulk fetch of PUBLIC user data and is called via `makeServiceRequest`,
-     * which attaches `Authorization: Bearer <serviceToken>`. oxy-api's CSRF
-     * middleware skips bearer-authenticated requests, so the calling client
-     * MUST be service-configured (`configureServiceAuth(apiKey, apiSecret)`)
-     * before invoking this method; otherwise `getServiceToken()` throws because
-     * no credentials are available. (A plain user-session request fails here:
-     * server-to-server there is no cookie jar, so the auto-attached
-     * `X-CSRF-Token` has no matching cookie and oxy-api rejects the POST with
-     * 403 "CSRF token missing".)
+     * **Dual-mode auth.** `/users/by-ids` is `optionalUserOrServiceAuth` on
+     * oxy-api: it accepts a service token, a user session, or an anonymous
+     * caller, and returns the SAME public `{ data: PublicUserProfile[] }`
+     * payload (canonical `name.displayName` + `_count`) in every case — no
+     * viewer-specific fields. This method picks the path automatically:
+     * - **Service-configured host (backend):** when `configureServiceAuth(apiKey,
+     *   apiSecret)` has been called, the chunk is fetched via `makeServiceRequest`
+     *   (attaches `Authorization: Bearer <serviceToken>`). This is the
+     *   server-to-server feed/notification hydration path (e.g. Mention's
+     *   `PostHydrationService`) and is unchanged.
+     * - **Plain client (browser / React Native with a user session):** when no
+     *   service credentials are configured, the chunk is fetched via
+     *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
+     *   middleware skips bearer-authenticated writes, and `makeRequest` only
+     *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
+     *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+     *   this method always used the service path, so every client-side caller
+     *   silently received `[]` because `getServiceToken()` had no credentials.
+     *
+     * Both paths run results through `normalizeUserIdentity` and unwrap the
+     * API's `{ data }` envelope identically (`makeServiceRequest` is literally
+     * `makeRequest` plus a bearer service header).
      *
      * Resilience: chunks are independent. A failed chunk is logged and skipped
      * — the method returns every user that resolved successfully rather than
@@ -381,15 +405,23 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         chunks.push(uniqueIds.slice(i, i + USERS_BY_IDS_CHUNK_SIZE));
       }
 
+      // A backend that called configureServiceAuth() uses the bearer-service
+      // path; any other caller (browser / RN with a user session) uses the
+      // user-bearer path. See the method doc for why the user path is CSRF-safe.
+      const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
+
       // Run chunks concurrently; a single chunk failure must not sink the rest.
       const settled = await Promise.all(
         chunks.map(async (chunk): Promise<User[]> => {
           try {
-            const users = await this.makeServiceRequest<User[]>('POST', '/users/by-ids', { ids: chunk });
+            const users = useServiceAuth
+              ? await this.makeServiceRequest<User[]>('POST', '/users/by-ids', { ids: chunk })
+              : await this.makeRequest<User[]>('POST', '/users/by-ids', { ids: chunk }, { cache: false });
             return Array.isArray(users) ? users.map((user) => normalizeUserIdentity(user)) : [];
           } catch (error: unknown) {
             logger.warn('getUsersByIds: chunk failed, continuing with remaining chunks', {
               method: 'getUsersByIds',
+              mode: useServiceAuth ? 'service' : 'user',
               chunkSize: chunk.length,
               status: extractErrorStatus(error),
               error: error instanceof Error ? error.message : String(error),