@oxyhq/core 5.0.0 → 5.1.0

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/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.0",
   "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/__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]);
+  });
+});

package/src/mixins/__tests__/accounts.test.ts

@@ -176,57 +176,100 @@ describe('OxyServices.accounts', () => {
   });
 
   describe('switchToAccount', () => {
+    // The switch route NO LONGER returns `authuser` or sets the device cookie —
+    // it can't (it's at /accounts/*, outside the Path=/auth cookie scope). The SDK
+    // establishes the cookie + resolves the slot via a follow-up POST /auth/session.
     const switchResponse: SwitchAccountResult = {
       sessionId: 'sess_switch',
       deviceId: 'dev_switch',
       expiresAt: '2026-06-30T01:00:00.000Z',
       accessToken: 'access_switch',
       user: { id: 'acc1', username: 'oxy-org', name: { displayName: 'Oxy Org' } },
-      authuser: 2,
     };
+    // POST /auth/session establishes the cookie in a correctly-allocated NEW slot
+    // and returns that slot + a fresh access token off the same session.
+    const sessionResponse = { accessToken: 'access_session', authuser: 1 };
+
+    // Route makeRequest by path: the switch call vs the /auth/session establishment.
+    const routeByPath = (response = switchResponse) =>
+      makeRequestSpy.mockImplementation((_method: string, path: string) =>
+        Promise.resolve(path === '/auth/session' ? sessionResponse : response),
+      );
 
-    it('posts to /:id/switch (no body, no cache), plants the token, sweeps the cache, and returns the session', async () => {
+    it('posts to /:id/switch then establishes the cookie via POST /auth/session, planting both tokens and sweeping the cache', async () => {
       const setTokensSpy = jest.spyOn(oxy, 'setTokens');
       const clearCacheSpy = jest.spyOn(oxy, 'clearCache');
-      makeRequestSpy.mockResolvedValue(switchResponse);
+      routeByPath();
 
       const result = await oxy.switchToAccount('acc1');
 
-      // Request shape: POST, exact path, no body, cache disabled.
+      // Switch request shape: POST, exact path, no body, cache disabled.
       expect(makeRequestSpy).toHaveBeenCalledWith(
         'POST',
         '/accounts/acc1/switch',
         undefined,
         expect.objectContaining({ cache: false }),
       );
+      // Then the canonical refresh-cookie establishment under /auth (where the
+      // device's oxy_rt_* slots ARE visible, so a NEW slot is allocated).
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/auth/session',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
 
-      // Session planting: the access token from the body is installed as the
-      // active token (mirrors claimSessionByToken / verifyChallenge).
-      expect(setTokensSpy).toHaveBeenCalledWith('access_switch');
-      expect(oxy.getAccessToken()).toBe('access_switch');
+      // The switch token is planted first; /auth/session's fresh token re-planted.
+      expect(setTokensSpy).toHaveBeenNthCalledWith(1, 'access_switch');
+      expect(setTokensSpy).toHaveBeenNthCalledWith(2, 'access_session');
+      expect(oxy.getAccessToken()).toBe('access_session');
       expect(oxy.hasValidToken()).toBe(true);
 
-      // Identity changed → the whole GET cache is swept so reads refetch as the
-      // new account, AND it happens AFTER the token is planted.
+      // Cache swept once, AFTER both tokens are planted.
       expect(clearCacheSpy).toHaveBeenCalledTimes(1);
-      expect(setTokensSpy.mock.invocationCallOrder[0]).toBeLessThan(
+      expect(setTokensSpy.mock.invocationCallOrder[1]).toBeLessThan(
         clearCacheSpy.mock.invocationCallOrder[0],
       );
 
-      // The returned session carries the target account (id-normalised) + authuser.
-      expect(result).toEqual({ ...switchResponse, user: { id: 'acc1', username: 'oxy-org', name: { displayName: 'Oxy Org' } } });
-      expect(result.authuser).toBe(2);
+      // The returned session carries the target account (id-normalised) and the
+      // slot resolved by /auth/session — NEVER the clobbering slot 0.
+      expect(result.sessionId).toBe('sess_switch');
+      expect(result.user).toEqual({ id: 'acc1', username: 'oxy-org', name: { displayName: 'Oxy Org' } });
+      expect(result.authuser).toBe(1);
 
       setTokensSpy.mockRestore();
       clearCacheSpy.mockRestore();
     });
 
     it('URL-encodes the accountId path segment', async () => {
-      makeRequestSpy.mockResolvedValue(switchResponse);
+      routeByPath();
       await oxy.switchToAccount('a b/c');
       expect(makeRequestSpy.mock.calls[0][1]).toBe('/accounts/a%20b%2Fc/switch');
     });
 
+    it('keeps the switch active in-session when /auth/session fails (best-effort cookie)', async () => {
+      const setTokensSpy = jest.spyOn(oxy, 'setTokens');
+      const clearCacheSpy = jest.spyOn(oxy, 'clearCache');
+      makeRequestSpy.mockImplementation((_method: string, path: string) =>
+        path === '/auth/session'
+          ? Promise.reject(Object.assign(new Error('origin'), { response: { status: 403 } }))
+          : Promise.resolve(switchResponse),
+      );
+
+      const result = await oxy.switchToAccount('acc1');
+
+      // The in-session switch survives: the switch token stays planted and the
+      // cache is still swept. The switched account just won't survive a reload
+      // until the cookie is next established (no authuser resolved).
+      expect(setTokensSpy).toHaveBeenCalledWith('access_switch');
+      expect(oxy.getAccessToken()).toBe('access_switch');
+      expect(clearCacheSpy).toHaveBeenCalledTimes(1);
+      expect(result.authuser).toBeUndefined();
+
+      setTokensSpy.mockRestore();
+      clearCacheSpy.mockRestore();
+    });
+
     it('does NOT plant or sweep when the operator is not authorized (403 surfaces via handleError)', async () => {
       const setTokensSpy = jest.spyOn(oxy, 'setTokens');
       const clearCacheSpy = jest.spyOn(oxy, 'clearCache');
@@ -235,9 +278,16 @@ describe('OxyServices.accounts', () => {
       );
 
       await expect(oxy.switchToAccount('acc1')).rejects.toThrow();
-      // A failed switch must NOT mutate session state.
+      // A failed switch must NOT mutate session state, and must NOT attempt the
+      // /auth/session establishment.
       expect(setTokensSpy).not.toHaveBeenCalled();
       expect(clearCacheSpy).not.toHaveBeenCalled();
+      expect(makeRequestSpy).not.toHaveBeenCalledWith(
+        'POST',
+        '/auth/session',
+        undefined,
+        expect.anything(),
+      );
 
       setTokensSpy.mockRestore();
       clearCacheSpy.mockRestore();

package/src/models/interfaces.ts

@@ -514,6 +514,25 @@ export interface AssetUpdateVisibilityResponse {
   };
 }
 
+/**
+ * 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)
  */