@oxyhq/core 12.5.4 → 12.7.0

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

@@ -12,7 +12,35 @@
  *     private access should use `getFileDownloadUrlAsync()` for a scoped URL.
  */
 
-import { OxyServices } from '../../OxyServices';
+import { AssetUrlResolutionError, OxyServices } from '../../OxyServices';
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check),
+ * so this is enough to give the HTTP cache a distinct per-user identity tag.
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify({ data }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/** An error `Response` mimicking the API's error body. */
+function errorResponse(status: number, code: string): Response {
+  return new Response(JSON.stringify({ error: code, message: code }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
 
 describe('OxyServices.getFileDownloadUrl', () => {
   describe('public assets (no token, no expiresIn) → CDN', () => {
@@ -80,3 +108,239 @@ describe('OxyServices.getFileDownloadUrl', () => {
     });
   });
 });
+
+describe('OxyServices.getFileDownloadUrlAsync', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('passes the API-scoped private stream URL through UNCHANGED', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    const scopedUrl =
+      'https://api.oxy.so/assets/priv1/stream?variant=thumb&mt=SCOPED-MEDIA-TOKEN';
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: scopedUrl, variant: 'thumb', expiresIn: 600 }));
+
+    const resolved = await oxy.getFileDownloadUrlAsync('priv1', 'thumb');
+
+    // Returned exactly as the API produced it — never rewritten to the CDN.
+    expect(resolved).toBe(scopedUrl);
+    expect(resolved).not.toContain('cloud.oxy.so');
+    // It hit the authorized resolution endpoint, not the public CDN builder.
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('/assets/priv1/url');
+  });
+
+  it('resolves a public asset to the CDN URL the API returns', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ url: 'https://cloud.oxy.so/pub1?variant=thumb', variant: 'thumb', expiresIn: 3600 }),
+    );
+
+    const resolved = await oxy.getFileDownloadUrlAsync('pub1', 'thumb');
+    expect(resolved).toBe('https://cloud.oxy.so/pub1?variant=thumb');
+  });
+
+  it('THROWS rather than returning a known-404 CDN URL when the API denies access', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValue(errorResponse(403, 'Access denied'));
+
+    await expect(oxy.getFileDownloadUrlAsync('priv1', 'thumb')).rejects.toBeInstanceOf(
+      AssetUrlResolutionError,
+    );
+
+    // Prove the failure was surfaced instead of a silent public-CDN fallback.
+    const err = await oxy
+      .getFileDownloadUrlAsync('priv1', 'thumb')
+      .catch((e: unknown) => e as AssetUrlResolutionError);
+    expect(err).toBeInstanceOf(AssetUrlResolutionError);
+    expect(err.fileId).toBe('priv1');
+    expect(err.variant).toBe('thumb');
+    expect(err.status).toBe(403);
+    // The error must not leak the scoped media token.
+    expect(err.message).not.toContain('mt=');
+  });
+
+  it('THROWS when the API returns an empty URL body', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: '', variant: undefined, expiresIn: 600 }));
+
+    await expect(oxy.getFileDownloadUrlAsync('priv1')).rejects.toBeInstanceOf(
+      AssetUrlResolutionError,
+    );
+  });
+});
+
+describe('OxyServices asset URL cache TTL', () => {
+  const MEDIA_TOKEN_TTL_MS = 10 * 60 * 1000;
+
+  it('never caches a resolved URL for as long as the media-token TTL', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Default (no explicit expiry) and an over-long explicit expiry both stay
+    // comfortably under the token lifetime.
+    expect(oxy.getAssetUrlCacheTTL()).toBeLessThan(MEDIA_TOKEN_TTL_MS);
+    expect(oxy.getAssetUrlCacheTTL(3600)).toBeLessThan(MEDIA_TOKEN_TTL_MS);
+    // Half of the 10-min bound.
+    expect(oxy.getAssetUrlCacheTTL(3600)).toBe(5 * 60 * 1000);
+  });
+
+  it('scales a short requested expiry down proportionally', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    expect(oxy.getAssetUrlCacheTTL(60)).toBe(30 * 1000);
+  });
+});
+
+describe('OxyServices.getFileDownloadUrls (variant-aware batch)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('sends a per-file {fileId, variant} list plus expiresIn and keeps only usable URLs', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        results: {
+          img1: {
+            allowed: true,
+            url: 'https://api.oxy.so/assets/img1/stream?variant=thumb&mt=TKN',
+            visibility: 'private',
+            mime: 'image/jpeg',
+          },
+          vid1: {
+            allowed: true,
+            url: 'https://cloud.oxy.so/vid1?variant=poster',
+            visibility: 'public',
+          },
+          gone: { allowed: false, error: 'Access denied' },
+        },
+      }),
+    );
+
+    const urls = await oxy.getFileDownloadUrls(
+      [
+        { fileId: 'img1', variant: 'thumb' },
+        { fileId: 'vid1', variant: 'poster' },
+        { fileId: 'gone' },
+      ],
+      { expiresIn: 600, context: 'file-manager' },
+    );
+
+    // Denied/missing ids are OMITTED (never an empty-string value).
+    expect(urls).toEqual({
+      img1: 'https://api.oxy.so/assets/img1/stream?variant=thumb&mt=TKN',
+      vid1: 'https://cloud.oxy.so/vid1?variant=poster',
+    });
+    expect('gone' in urls).toBe(false);
+
+    // The request carried the per-file variants + expiresIn on the POST body.
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(String(init.body));
+    expect(body.files).toEqual([
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: 'vid1', variant: 'poster' },
+      { fileId: 'gone' },
+    ]);
+    expect(body.expiresIn).toBe(600);
+    expect(body.context).toBe('file-manager');
+  });
+
+  it('drops blank ids and collapses exact (fileId, variant) duplicates before sending', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ results: {} }));
+
+    await oxy.getFileDownloadUrls([
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: '   ' },
+      { fileId: 'img1' },
+    ]);
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(String(init.body));
+    // Dedup on (fileId, variant): the two thumb entries collapse; the
+    // variant-less img1 is a DIFFERENT request and survives; blank id dropped.
+    expect(body.files).toEqual([
+      { fileId: 'img1', variant: 'thumb' },
+      { fileId: 'img1' },
+    ]);
+  });
+
+  it('makes NO network call for an all-empty request list', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(makeJwt({ userId: 'viewer-A' }));
+
+    const urls = await oxy.getFileDownloadUrls([{ fileId: '' }, { fileId: '  ' }]);
+    expect(urls).toEqual({});
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('OxyServices asset URL cache isolation across accounts', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('never serves account A’s scoped URL to account B after a switch', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Account A resolves the asset; response is cached under A's identity.
+    oxy.setTokens(makeJwt({ userId: 'account-A' }));
+    const urlForA = 'https://api.oxy.so/assets/priv1/stream?mt=TOKEN-FOR-A';
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: urlForA, expiresIn: 600 }));
+    expect(await oxy.getFileDownloadUrlAsync('priv1')).toBe(urlForA);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Switching to account B mints a new access token → new identity tag. B's
+    // read must MISS A's cache entry and hit the network for its own scoped URL.
+    oxy.setTokens(makeJwt({ userId: 'account-B' }));
+    const urlForB = 'https://api.oxy.so/assets/priv1/stream?mt=TOKEN-FOR-B';
+    fetchMock.mockResolvedValueOnce(jsonResponse({ url: urlForB, expiresIn: 600 }));
+
+    const resolvedForB = await oxy.getFileDownloadUrlAsync('priv1');
+    expect(resolvedForB).toBe(urlForB);
+    expect(resolvedForB).not.toBe(urlForA);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/mixins/index.ts

@@ -30,6 +30,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -64,6 +65,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -138,6 +140,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,
 
+    // Device-to-device identity transfer ("add a device"): E2E-encrypted key
+    // clone over a short-lived relay (b3 Feature 2).
+    OxyServicesDeviceTransferMixin,
+
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/src/models/interfaces.ts

@@ -517,6 +517,26 @@ export interface AssetUrlResponse {
   expiresIn: number;
 }
 
+/**
+ * Per-file result of `POST /assets/batch-access`. `allowed` is authoritative:
+ * when `false` the entry carries an `error` string (e.g. `'Access denied'`,
+ * `'File not found'`) and no `url`. When `true`, `url` is a caller-scoped,
+ * `<img src>`-ready URL — the public CDN form for a public asset or an
+ * API-origin stream URL carrying a short-lived media token for a private one.
+ */
+export interface BatchFileAccessEntry {
+  allowed: boolean;
+  url?: string;
+  visibility?: FileVisibility;
+  mime?: string;
+  error?: string;
+}
+
+/** Envelope returned by `POST /assets/batch-access`, keyed by file id. */
+export interface BatchFileAccessResponse {
+  results: Record<string, BatchFileAccessEntry>;
+}
+
 export interface AssetDeleteSummary {
   fileId: string;
   wouldDelete: boolean;

package/src/session/SessionClient.ts

@@ -7,6 +7,7 @@ import {
   type DeviceSessionState,
 } from '@oxyhq/contracts';
 import { logger } from '../logger';
+import { computeIdentityTag } from '../utils/cacheKey';
 import { getSocketIO } from './socketLoader';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 
@@ -172,8 +173,25 @@ export class SessionClient {
     }
   }
 
-  /** Validate + last-writer-wins by revision. Returns true if applied. */
-  protected applyState(raw: unknown, origin: SessionStateOrigin = 'push'): boolean {
+  /**
+   * Validate + last-writer-wins by revision. Returns true if applied.
+   *
+   * `activeToken` (sync path only) is the server-issued access token for
+   * `raw.activeAccountId`. When present and the state is applied, it is planted
+   * BEFORE any subscriber is notified so the bearer already belongs to the new
+   * active account — the local switch/bootstrap path then needs no redundant
+   * device-secret mint. Push-origin applies carry no token and rely on the
+   * mint-before-notify gate below.
+   *
+   * ORDERING INVARIANT: a subscriber must NEVER observe a newly-active account
+   * while the planted bearer still identifies the PREVIOUS one — otherwise a
+   * `useCurrentUser`-style refetch fires under the wrong account's token (the
+   * account-switch 404 race). So when a transport is available and the planted
+   * bearer does not already belong to `next.activeAccountId`, minting is awaited
+   * BEFORE `notify()`. This covers EVERY notify source (a switch push, a
+   * cross-device push, a cold mint), not just the initial "no bearer yet" case.
+   */
+  protected applyState(raw: unknown, origin: SessionStateOrigin = 'push', activeToken?: string): boolean {
     const next = safeParseContract(deviceSessionStateSchema, raw);
     if (!next) {
       logger.warn('[SessionClient] discarded invalid session state');
@@ -192,10 +210,27 @@ export class SessionClient {
     ) {
       return false;
     }
+    const previousState = this.state;
     this.state = next;
+    // Plant the sync-supplied active token (it is for `next.activeAccountId`)
+    // now — before the notify below — so the bearer matches the new active
+    // account when subscribers observe it. Guarded on difference to avoid a
+    // redundant token-change notification on an unchanged token (bootstrap
+    // restate).
+    if (activeToken && next.activeAccountId !== null && activeToken !== this.host.getAccessToken()) {
+      this.host.setTokens(activeToken);
+    }
     const transport = this.options.transport;
+    const activeAccountId = next.activeAccountId;
+    // Mint before notifying when the bearer does not already belong to the new
+    // active account: no bearer at all, an opaque bearer, OR a bearer for a
+    // DIFFERENT account. `computeIdentityTag` yields the token's `userId`/`id`
+    // for a real JWT (comparable to the account id) and a non-account sentinel
+    // otherwise, so a mismatch always resolves to "mint".
     const needsMintBeforeNotify =
-      transport != null && next.accounts.length > 0 && !this.host.getAccessToken();
+      transport != null &&
+      next.accounts.length > 0 &&
+      (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
 
     const finishApply = (): void => {
       this.notify();
@@ -210,8 +245,10 @@ export class SessionClient {
 
     if (needsMintBeforeNotify) {
       void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
-        logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
-        finishApply();
+        logger.warn('[SessionClient] ensureActiveToken failed — reverting session state', { component: 'SessionClient' }, error);
+        // Do NOT notify under a mismatched bearer. Revert to the last applied
+        // state so subscribers keep observing the account whose token is planted.
+        this.state = previousState ?? null;
       });
     } else {
       if (transport) {
@@ -251,9 +288,23 @@ export class SessionClient {
     }
     // A `sync` is always the response to a direct REST call this client made
     // (bootstrap / switch / signOut / add) → a `request`-origin, authoritative
-    // verdict.
-    this.applyState(sync.state, 'request');
-    if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
+    // verdict. Hand the active token to `applyState`: in the applied path it is
+    // planted BEFORE notify (bearer matches the new active account when
+    // subscribers observe it, and no redundant device-secret mint is triggered).
+    const applied = this.applyState(sync.state, 'request', sync.activeToken?.accessToken);
+    // Equal-revision restate (this revision was already applied by a preceding
+    // socket push): `applyState` no-ops without planting, but the token still
+    // needs planting. Guard on the sync's active account STILL being the current
+    // active account so a stale response cannot adopt a token for an account a
+    // newer state already switched away from.
+    if (
+      !applied &&
+      sync.activeToken &&
+      this.state &&
+      sync.state.activeAccountId !== null &&
+      sync.state.activeAccountId === this.state.activeAccountId &&
+      sync.activeToken.accessToken !== this.host.getAccessToken()
+    ) {
       this.host.setTokens(sync.activeToken.accessToken);
     }
   }

package/src/session/__tests__/SessionClient.switchTokenOrder.test.ts

@@ -0,0 +1,170 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost, type TokenTransport } from '../SessionClient';
+import { computeIdentityTag } from '../../utils/cacheKey';
+
+/**
+ * The account-switch 404 race (regression guard).
+ *
+ * When a `session_state` push re-elects the active account from A to B, the
+ * push carries NO token — the app still holds A's bearer. If a subscriber were
+ * notified before B's bearer is planted, a `useCurrentUser`-style refetch would
+ * fire under A's token against B's session and 404.
+ *
+ * INVARIANT: no subscriber is ever notified while the planted bearer identifies
+ * an account OTHER than the observed active account. This test records, at every
+ * notify, the observed active account alongside the account the CURRENT bearer
+ * belongs to (via the same `computeIdentityTag` derivation `applyState` uses)
+ * and asserts they always match — and that the switch notify is DEFERRED until
+ * the mint lands B's token.
+ */
+
+/** A minimal jwt-decode-able token whose `userId` claim is `accountId`. */
+function jwtFor(accountId: string): string {
+  const payload = Buffer.from(JSON.stringify({ userId: accountId })).toString('base64url');
+  return `h.${payload}.s`;
+}
+
+const stateWith = (rev: number, active: string): DeviceSessionState => ({
+  deviceId: 'd1',
+  accounts: [
+    { accountId: 'a1', sessionId: 's-a1', authuser: 0 },
+    { accountId: 'b1', sessionId: 's-b1', authuser: 1 },
+  ],
+  activeAccountId: active,
+  revision: rev,
+  updatedAt: 1720000000000,
+});
+
+class TestClient extends SessionClient {
+  public apply(raw: unknown): boolean {
+    return this.applyState(raw);
+  }
+}
+
+describe('SessionClient — no notify under a mismatched bearer on an account switch', () => {
+  it('defers the switch notify until the mint lands the new active account bearer', async () => {
+    // Mutable planted bearer, starting on account A.
+    let planted: string | null = jwtFor('a1');
+    const host: SessionClientHost = {
+      makeRequest: jest.fn(),
+      getBaseURL: () => 'http://test.invalid',
+      getAccessToken: () => planted,
+      getDeviceCredential: () => null,
+      onTokensChanged: () => () => undefined,
+      setTokens: (token) => {
+        planted = token;
+      },
+      getCurrentAccountId: () => null,
+    };
+
+    // The mint lands the ACTIVE account's bearer, asynchronously (models the
+    // real device-secret mint round trip).
+    const transport: TokenTransport = {
+      ensureActiveToken: jest.fn(async (state: DeviceSessionState) => {
+        await Promise.resolve();
+        if (state.activeAccountId) {
+          planted = jwtFor(state.activeAccountId);
+        }
+      }),
+    };
+
+    const c = new TestClient(host, { transport });
+
+    const observations: Array<{ active: string | null; bearer: string }> = [];
+    c.subscribe((s) => {
+      observations.push({
+        active: s?.activeAccountId ?? null,
+        bearer: computeIdentityTag(host.getAccessToken()),
+      });
+    });
+
+    // Apply A (bearer already A's) → matches → synchronous notify.
+    c.apply(stateWith(1, 'a1'));
+    expect(observations).toEqual([{ active: 'a1', bearer: 'a1' }]);
+
+    // A `session_state` push re-elects B while the bearer is still A's.
+    c.apply(stateWith(2, 'b1'));
+    // The switch notify MUST NOT have fired yet — the bearer is still A's, so a
+    // synchronous notify would let a subscriber observe B under A's token.
+    expect(observations).toEqual([{ active: 'a1', bearer: 'a1' }]);
+
+    // Flush the mint + deferred notify.
+    for (let i = 0; i < 5; i++) {
+      await Promise.resolve();
+    }
+
+    // The mint ran, and the switch notify fired only AFTER B's bearer was planted.
+    expect(transport.ensureActiveToken).toHaveBeenCalledWith(
+      expect.objectContaining({ activeAccountId: 'b1' }),
+    );
+    expect(observations).toContainEqual({ active: 'b1', bearer: 'b1' });
+
+    // At NO notify did the observed active account differ from the bearer's account.
+    for (const o of observations) {
+      expect(o.bearer).toBe(o.active);
+    }
+  });
+
+  it('does not defer when the bearer already belongs to the new active account', () => {
+    let planted: string | null = jwtFor('b1');
+    const host: SessionClientHost = {
+      makeRequest: jest.fn(),
+      getBaseURL: () => 'http://test.invalid',
+      getAccessToken: () => planted,
+      getDeviceCredential: () => null,
+      onTokensChanged: () => () => undefined,
+      setTokens: (token) => {
+        planted = token;
+      },
+      getCurrentAccountId: () => null,
+    };
+    const transport: TokenTransport = { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+    const c = new TestClient(host, { transport });
+
+    const seen: Array<string | null> = [];
+    c.subscribe((s) => seen.push(s?.activeAccountId ?? null));
+
+    // Bearer is already B's → the notify is synchronous (no mint-before-notify).
+    c.apply(stateWith(3, 'b1'));
+    expect(seen).toEqual(['b1']);
+  });
+
+  it('reverts state and does not notify when minting fails on an account switch', async () => {
+    let planted: string | null = jwtFor('a1');
+    const host: SessionClientHost = {
+      makeRequest: jest.fn(),
+      getBaseURL: () => 'http://test.invalid',
+      getAccessToken: () => planted,
+      getDeviceCredential: () => null,
+      onTokensChanged: () => () => undefined,
+      setTokens: (token) => {
+        planted = token;
+      },
+      getCurrentAccountId: () => null,
+    };
+
+    const transport: TokenTransport = {
+      ensureActiveToken: jest.fn(async () => {
+        await Promise.resolve();
+        throw new Error('mint failed');
+      }),
+    };
+
+    const c = new TestClient(host, { transport });
+    const seen: Array<string | null> = [];
+    c.subscribe((s) => seen.push(s?.activeAccountId ?? null));
+
+    c.apply(stateWith(1, 'a1'));
+    expect(seen).toEqual(['a1']);
+
+    c.apply(stateWith(2, 'b1'));
+    for (let i = 0; i < 5; i++) {
+      await Promise.resolve();
+    }
+
+    // Still on A — no notify under A's bearer for B's active account.
+    expect(seen).toEqual(['a1']);
+    expect(c.getState()?.activeAccountId).toBe('a1');
+    expect(computeIdentityTag(host.getAccessToken())).toBe('a1');
+  });
+});

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

@@ -0,0 +1,33 @@
+/**
+ * `redactUrlQuery` tests — the query-string scrubber used before any asset URL
+ * reaches a log sink. Asset stream URLs carry a scoped `mt=` media token that
+ * is a bearer credential; it must never be logged.
+ */
+
+import { redactUrlQuery } from '../redactUrl';
+
+describe('redactUrlQuery', () => {
+  it('strips the query string (including a media token) from an absolute URL', () => {
+    const redacted = redactUrlQuery(
+      'https://api.oxy.so/assets/priv1/stream?variant=thumb&mt=SECRET-TOKEN',
+    );
+    expect(redacted).toBe('https://api.oxy.so/assets/priv1/stream?<redacted>');
+    expect(redacted).not.toContain('mt=');
+    expect(redacted).not.toContain('SECRET-TOKEN');
+  });
+
+  it('strips the query string from a relative path too', () => {
+    expect(redactUrlQuery('/assets/priv1/url?expiresIn=600&mt=SECRET')).toBe(
+      '/assets/priv1/url?<redacted>',
+    );
+  });
+
+  it('returns a URL without a query string unchanged', () => {
+    expect(redactUrlQuery('https://cloud.oxy.so/pub1')).toBe('https://cloud.oxy.so/pub1');
+    expect(redactUrlQuery('/assets')).toBe('/assets');
+  });
+
+  it('passes through empty input', () => {
+    expect(redactUrlQuery('')).toBe('');
+  });
+});

package/src/utils/redactUrl.ts

@@ -0,0 +1,28 @@
+/**
+ * URL redaction for logging.
+ *
+ * Asset URLs the API hands back for private assets carry a scoped, short-lived
+ * media token (`mt=…`) in their query string. That token is a bearer credential
+ * for the underlying object, so it must never land in a log line, breadcrumb,
+ * or metric — a captured log would otherwise grant read access until the token
+ * expires. Query strings on API URLs can also carry other sensitive params, so
+ * we redact the whole query rather than allow-listing one key.
+ *
+ * `redactUrlQuery` returns the URL's path portion with a `?<redacted>` marker
+ * when a query string is present, and the input unchanged otherwise. It is
+ * defensive: any input that does not parse as a URL is passed through as-is,
+ * except that a bare `?query` tail is still stripped so a relative path with a
+ * query never leaks.
+ */
+export function redactUrlQuery(url: string): string {
+  if (typeof url !== 'string' || url.length === 0) {
+    return url;
+  }
+
+  const queryIndex = url.indexOf('?');
+  if (queryIndex === -1) {
+    return url;
+  }
+
+  return `${url.slice(0, queryIndex)}?<redacted>`;
+}