@oxyhq/core 5.0.0 → 5.1.1

package/dist/types/index.d.ts

@@ -62,7 +62,7 @@ export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
-export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceSession, DeviceSessionsResponse, DeviceSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
+export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceSession, DeviceSessionsResponse, DeviceSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation } from './models/Topic';

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -437,10 +437,19 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * Unlike the removed `X-Acting-As` delegation header, the returned session
          * IS the new identity: this plants `accessToken` as the active token —
          * exactly like `claimSessionByToken` / `verifyChallenge` — so every
-         * subsequent request authenticates as the target account. The refresh token
-         * is the server-set httpOnly `oxy_rt_<authuser>` cookie (never in the body),
-         * so it joins the device multi-account set and survives reload /
-         * `refresh-all` with no extra client work.
+         * subsequent request authenticates as the target account.
+         *
+         * Joining the device multi-account set (so the switch survives a reload and
+         * propagates cross-domain via `/auth/refresh-all`) requires a SECOND call, to
+         * `POST /auth/session`, made here after the token is planted. The switch route
+         * lives at `/accounts/*`, OUTSIDE the `oxy_rt_<authuser>` cookie's `Path=/auth`
+         * scope, so the server never sees the device's existing slots from it and
+         * would clobber slot 0 (destroying the operator's own session). `/auth/session`
+         * runs where those cookies ARE visible, so the server allocates a NEW slot that
+         * coexists with the operator's and returns its `authuser`. This step is
+         * web-only (native multi-account uses stored sessions, not cookies) and
+         * best-effort — a failure leaves the in-session switch intact; the switched
+         * account simply won't survive a reload until the cookie is next established.
          *
          * After planting, the SDK's identity-scoped GET cache is fully cleared so
          * every cached read re-fetches as the new account. (The consuming

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -1,7 +1,17 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, ServiceAssetMetadata } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
+        /**
+         * Service-token request, implemented by the auth mixin earlier in the
+         * composition pipeline (see `mixins/index.ts`). The assets mixin is typed
+         * against `OxyServicesBase`, which does not carry the auth mixin's methods,
+         * so this `declare` surfaces the inherited runtime method to TypeScript
+         * without re-implementing it. Used by
+         * {@link getServiceAssetMetadataByIds} to authenticate the server-to-server
+         * `/assets/service/by-ids` bulk fetch with a bearer service token.
+         */
+        makeServiceRequest: <R = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: unknown, userId?: string) => Promise<R>;
         /**
          * Delete file
          */
@@ -49,6 +59,37 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * Get download URLs for multiple files efficiently
          */
         getFileDownloadUrls(fileIds: string[], context?: string): Promise<Record<string, string>>;
+        /**
+         * Resolve many Oxy asset ids to their content-addressed metadata in one
+         * round-trip per chunk via `POST /assets/service/by-ids` (body `{ ids }`).
+         *
+         * Returns each asset's `sha256`, `mime`, byte `size`, and `status` — built
+         * for server-to-server callers (e.g. Mention's MTN Protocol blob-ref
+         * resolution) that need the content hash for an asset id. Ids are
+         * deduplicated and validated (empty/blank ids dropped) before being split
+         * into chunks of {@link SERVICE_ASSET_METADATA_CHUNK_SIZE} (the server-side
+         * cap). The server omits unknown/deleted ids from each chunk's `data`, so
+         * the merged result may be shorter than the requested id list and the caller
+         * is expected to map by `id`.
+         *
+         * **Service-token auth (required).** `/assets/service/by-ids` is guarded by
+         * `serviceAuthMiddleware` + the `files:read` scope and is called via
+         * `makeServiceRequest`, which attaches `Authorization: Bearer <serviceToken>`
+         * (the same client that calls `POST /assets/service/cache`). 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
+         * is rejected by the route's service-auth guard.
+         *
+         * Resilience: chunks are independent. A failed chunk is logged and skipped —
+         * the method returns every entry that resolved successfully rather than
+         * discarding the whole call on one chunk's failure. An empty/whitespace-only
+         * input resolves immediately with `[]` and performs no network call.
+         *
+         * Not cached at the SDK layer: it's a POST keyed on a multi-id body (low hit
+         * rate), mirroring the sibling service/POST methods which never cache.
+         */
+        getServiceAssetMetadataByIds(ids: string[]): Promise<ServiceAssetMetadata[]>;
         /**
          * Upload raw file data
          */

package/dist/types/mixins/OxyServices.user.d.ts

@@ -48,6 +48,17 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * server-to-server `/users/by-ids` bulk fetch with a bearer service token.
          */
         makeServiceRequest: <R = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: unknown, 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.
+         */
+        _serviceApiKey: string | null;
+        _serviceApiSecret: string | null;
         /**
          * Get profile by username
          */
@@ -138,16 +149,28 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * 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

package/dist/types/models/interfaces.d.ts

@@ -447,6 +447,24 @@ export interface AssetUpdateVisibilityResponse {
         updatedAt: string;
     };
 }
+/**
+ * Minimal, service-token-scoped asset metadata returned by
+ * `POST /assets/service/by-ids`.
+ *
+ * Resolves an Oxy asset `id` to its content-addressed identity (`sha256`),
+ * MIME type, byte `size`, and storage `status`. Used by server-to-server
+ * callers (e.g. Mention's MTN Protocol blob-ref resolution) that hold a
+ * `files:read`-scoped service token rather than a user session. Unknown or
+ * deleted ids are omitted from the response (never error the whole batch),
+ * so the result may be shorter than the requested id list.
+ */
+export interface ServiceAssetMetadata {
+    id: string;
+    sha256: string;
+    mime: string;
+    size: number;
+    status: 'active' | 'trash';
+}
 /**
  * Account storage usage (server-side usage, not local AsyncStorage)
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -95,7 +95,7 @@
   },
   "dependencies": {
     "@oxyhq/contracts": "^0.7.0",
-    "@oxyhq/protocol": "^0.1.0",
+    "@oxyhq/protocol": "^0.1.1",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/index.ts

@@ -324,6 +324,7 @@ export type {
     AssetDeleteSummary,
     AssetUpdateVisibilityRequest,
     AssetUpdateVisibilityResponse,
+    ServiceAssetMetadata,
     AccountStorageCategoryUsage,
     AccountStorageUsageResponse,
     SecurityEventType,

package/src/mixins/OxyServices.accounts.ts

@@ -35,6 +35,8 @@ 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';
 
 // ---------------------------------------------------------------------------
@@ -520,10 +522,19 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
      * Unlike the removed `X-Acting-As` delegation header, the returned session
      * IS the new identity: this plants `accessToken` as the active token —
      * exactly like `claimSessionByToken` / `verifyChallenge` — so every
-     * subsequent request authenticates as the target account. The refresh token
-     * is the server-set httpOnly `oxy_rt_<authuser>` cookie (never in the body),
-     * so it joins the device multi-account set and survives reload /
-     * `refresh-all` with no extra client work.
+     * subsequent request authenticates as the target account.
+     *
+     * Joining the device multi-account set (so the switch survives a reload and
+     * propagates cross-domain via `/auth/refresh-all`) requires a SECOND call, to
+     * `POST /auth/session`, made here after the token is planted. The switch route
+     * lives at `/accounts/*`, OUTSIDE the `oxy_rt_<authuser>` cookie's `Path=/auth`
+     * scope, so the server never sees the device's existing slots from it and
+     * would clobber slot 0 (destroying the operator's own session). `/auth/session`
+     * runs where those cookies ARE visible, so the server allocates a NEW slot that
+     * coexists with the operator's and returns its `authuser`. This step is
+     * web-only (native multi-account uses stored sessions, not cookies) and
+     * best-effort — a failure leaves the in-session switch intact; the switched
+     * account simply won't survive a reload until the cookie is next established.
      *
      * After planting, the SDK's identity-scoped GET cache is fully cleared so
      * every cached read re-fetches as the new account. (The consuming
@@ -546,12 +557,45 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
 
         // Plant the freshly minted session as the ACTIVE session, mirroring
         // `claimSessionByToken` / `verifyChallenge`: the response body carries
-        // the first access token; the refresh token is the server-set httpOnly
-        // cookie, so there is nothing else to store here.
+        // the first access token. The device refresh cookie is established below.
         if (res?.accessToken) {
           this.setTokens(res.accessToken);
         }
 
+        // 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,
+            );
+          }
+        }
+
         // Identity changed → drop the entire GET response cache so no entry
         // personalised for the previous identity is reused. Cache keys are
         // identity-scoped, so a different identity could not READ the old
@@ -561,6 +605,7 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
 
         return {
           ...res,
+          ...(typeof authuser === 'number' ? { authuser } : {}),
           user: normalizeUserIdentity(res.user),
         };
       } catch (error) {

package/src/mixins/OxyServices.assets.ts

@@ -1,6 +1,16 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor, ServiceAssetMetadata } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
+import { logger } from '../utils/loggerUtils';
+import { extractErrorStatus } from '../utils/errorUtils';
+
+/**
+ * Maximum number of ids sent per `POST /assets/service/by-ids` request. Matches
+ * the server-side batch cap (the route rejects empty or > 100 id arrays with a
+ * 400); larger inputs are split into multiple chunked calls and merged. Mirrors
+ * `getUsersByIds`'s `USERS_BY_IDS_CHUNK_SIZE`.
+ */
+const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
 
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -8,6 +18,22 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       super(...(args as [any]));
     }
 
+    /**
+     * Service-token request, implemented by the auth mixin earlier in the
+     * composition pipeline (see `mixins/index.ts`). The assets mixin is typed
+     * against `OxyServicesBase`, which does not carry the auth mixin's methods,
+     * so this `declare` surfaces the inherited runtime method to TypeScript
+     * without re-implementing it. Used by
+     * {@link getServiceAssetMetadataByIds} to authenticate the server-to-server
+     * `/assets/service/by-ids` bulk fetch with a bearer service token.
+     */
+    declare makeServiceRequest: <R = unknown>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: unknown,
+      userId?: string,
+    ) => Promise<R>;
+
     /**
      * Delete file
      */
@@ -167,6 +193,74 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       return urls;
     }
 
+    /**
+     * Resolve many Oxy asset ids to their content-addressed metadata in one
+     * round-trip per chunk via `POST /assets/service/by-ids` (body `{ ids }`).
+     *
+     * Returns each asset's `sha256`, `mime`, byte `size`, and `status` — built
+     * for server-to-server callers (e.g. Mention's MTN Protocol blob-ref
+     * resolution) that need the content hash for an asset id. Ids are
+     * deduplicated and validated (empty/blank ids dropped) before being split
+     * into chunks of {@link SERVICE_ASSET_METADATA_CHUNK_SIZE} (the server-side
+     * cap). The server omits unknown/deleted ids from each chunk's `data`, so
+     * the merged result may be shorter than the requested id list and the caller
+     * is expected to map by `id`.
+     *
+     * **Service-token auth (required).** `/assets/service/by-ids` is guarded by
+     * `serviceAuthMiddleware` + the `files:read` scope and is called via
+     * `makeServiceRequest`, which attaches `Authorization: Bearer <serviceToken>`
+     * (the same client that calls `POST /assets/service/cache`). 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
+     * is rejected by the route's service-auth guard.
+     *
+     * Resilience: chunks are independent. A failed chunk is logged and skipped —
+     * the method returns every entry that resolved successfully rather than
+     * discarding the whole call on one chunk's failure. An empty/whitespace-only
+     * input resolves immediately with `[]` and performs no network call.
+     *
+     * Not cached at the SDK layer: it's a POST keyed on a multi-id body (low hit
+     * rate), mirroring the sibling service/POST methods which never cache.
+     */
+    async getServiceAssetMetadataByIds(ids: string[]): Promise<ServiceAssetMetadata[]> {
+      const uniqueIds = Array.from(
+        new Set(ids.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)),
+      );
+      if (uniqueIds.length === 0) {
+        return [];
+      }
+
+      const chunks: string[][] = [];
+      for (let i = 0; i < uniqueIds.length; i += SERVICE_ASSET_METADATA_CHUNK_SIZE) {
+        chunks.push(uniqueIds.slice(i, i + SERVICE_ASSET_METADATA_CHUNK_SIZE));
+      }
+
+      // Run chunks concurrently; a single chunk failure must not sink the rest.
+      const settled = await Promise.all(
+        chunks.map(async (chunk): Promise<ServiceAssetMetadata[]> => {
+          try {
+            const entries = await this.makeServiceRequest<ServiceAssetMetadata[]>(
+              'POST',
+              '/assets/service/by-ids',
+              { ids: chunk },
+            );
+            return Array.isArray(entries) ? entries : [];
+          } catch (error: unknown) {
+            logger.warn('getServiceAssetMetadataByIds: chunk failed, continuing with remaining chunks', {
+              method: 'getServiceAssetMetadataByIds',
+              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),

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

@@ -0,0 +1,116 @@
+/**
+ * `getServiceAssetMetadataByIds` mixin tests.
+ *
+ * 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-only input no-ops to `[]` with no network call;
+ *  - input is de-duplicated and a single chunk is sent for <= 100 unique ids,
+ *    POSTed to `/assets/service/by-ids` as `{ ids }`;
+ *  - the `{ data }` envelope is unwrapped to a bare `ServiceAssetMetadata[]`
+ *    (mirroring how `makeServiceRequest<T[]>` returns the inner array);
+ *  - inputs > 100 ids are chunked at 100/request and merged;
+ *  - a failed chunk is logged and skipped — successful chunks still return.
+ */
+
+import type { ServiceAssetMetadata } from '../../models/interfaces';
+import { OxyServices } from '../../OxyServices';
+
+const sampleEntry: ServiceAssetMetadata = {
+  id: 'asset-1',
+  sha256: 'a'.repeat(64),
+  mime: 'image/jpeg',
+  size: 12345,
+  status: 'active',
+};
+
+describe('OxyServices.assets — getServiceAssetMetadataByIds', () => {
+  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 / whitespace input', async () => {
+    await expect(oxy.getServiceAssetMetadataByIds([])).resolves.toEqual([]);
+    await expect(oxy.getServiceAssetMetadataByIds(['', '   '])).resolves.toEqual([]);
+    expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+  });
+
+  it('de-duplicates and sends a single chunk for <= 100 unique ids', async () => {
+    // makeServiceRequest unwraps the API's `{ data }` envelope, so the resolved
+    // value is the bare array (NOT `{ data: [...] }`) — mirror that real shape.
+    makeServiceRequestSpy.mockResolvedValueOnce([sampleEntry]);
+
+    const result = await oxy.getServiceAssetMetadataByIds([
+      'asset-1',
+      'asset-1', // duplicate
+      '   ', // dropped
+    ]);
+
+    expect(result).toEqual([sampleEntry]);
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(1);
+    expect(makeServiceRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/assets/service/by-ids',
+      { ids: ['asset-1'] },
+    );
+  });
+
+  it('chunks at 100 ids per request and merges each chunk', async () => {
+    const ids = Array.from({ length: 250 }, (_, i) => `asset-${i}`);
+
+    makeServiceRequestSpy.mockImplementation(
+      async (
+        _method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+        _url: string,
+        data?: { ids: string[] },
+      ): Promise<ServiceAssetMetadata[]> =>
+        (data?.ids ?? []).map((id) => ({
+          id,
+          sha256: 'b'.repeat(64),
+          mime: 'application/octet-stream',
+          size: 1,
+          status: 'active' as const,
+        })),
+    );
+
+    const result = await oxy.getServiceAssetMetadataByIds(ids);
+
+    // 250 unique ids => 100 + 100 + 50 across three POSTs.
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(3);
+    const chunkSizes = makeServiceRequestSpy.mock.calls.map(
+      (call) => (call[2] as { ids: string[] }).ids.length,
+    );
+    expect(chunkSizes).toEqual([100, 100, 50]);
+
+    expect(result).toHaveLength(250);
+    expect(result[0]).toEqual({
+      id: 'asset-0',
+      sha256: 'b'.repeat(64),
+      mime: 'application/octet-stream',
+      size: 1,
+      status: 'active',
+    });
+    expect(result[249]?.id).toBe('asset-249');
+  });
+
+  it('skips a failed chunk and returns the entries that resolved', async () => {
+    const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
+
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([sampleEntry]) // first chunk (100 ids) succeeds
+      .mockRejectedValueOnce(new Error('chunk failed')); // second chunk (50 ids) fails
+
+    const result = await oxy.getServiceAssetMetadataByIds(ids);
+
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
+    expect(result).toEqual([sampleEntry]);
+  });
+});