@oxyhq/core 5.2.1 → 5.3.0

package/src/__tests__/crossDomainAuth.test.ts

@@ -6,6 +6,7 @@ interface MockServices {
   signInWithFedCM: jest.Mock;
   signInWithRedirect: jest.Mock;
   silentSignInWithFedCM: jest.Mock;
+  silentSignIn: jest.Mock;
   isFedCMSupported: jest.Mock;
   getCurrentUser: jest.Mock;
   handleAuthCallback: jest.Mock;
@@ -28,6 +29,7 @@ function createMockServices(overrides: Partial<MockServices> = {}): MockServices
     signInWithFedCM: jest.fn(async () => fakeSession('fedcm-sess')),
     signInWithRedirect: jest.fn(),
     silentSignInWithFedCM: jest.fn(async () => null),
+    silentSignIn: jest.fn(async () => null),
     isFedCMSupported: jest.fn(() => true),
     getCurrentUser: jest.fn(),
     handleAuthCallback: jest.fn(() => null),
@@ -62,38 +64,53 @@ describe('CrossDomainAuth', () => {
     });
   });
 
-  it('uses FedCM first in auto mode when supported', async () => {
-    const services = createMockServices();
+  it('auto mode goes straight to redirect and never calls FedCM, even when FedCM is supported', async () => {
+    const services = createMockServices({ isFedCMSupported: jest.fn(() => true) });
     const auth = new CrossDomainAuth(services as unknown as OxyServices);
     const selected: string[] = [];
 
-    const session = await auth.signIn({
+    const result = await auth.signIn({
       method: 'auto',
       onMethodSelected: (method) => selected.push(method),
     });
 
-    expect(session?.sessionId).toBe('fedcm-sess');
-    expect(selected).toEqual(['fedcm']);
-    expect(services.signInWithRedirect).not.toHaveBeenCalled();
+    expect(result).toBeNull();
+    expect(selected).toEqual(['redirect']);
+    expect(services.signInWithFedCM).not.toHaveBeenCalled();
+    expect(services.signInWithRedirect).toHaveBeenCalledTimes(1);
   });
 
-  it('falls back to redirect in auto mode when FedCM fails', async () => {
+  it('autoSignIn does not call FedCM (goes to redirect) regardless of browser support', async () => {
     const services = createMockServices({
-      signInWithFedCM: jest.fn(async () => { throw new Error('fedcm fail'); }),
+      isFedCMSupported: jest.fn(() => true),
+      signInWithFedCM: jest.fn(async () => {
+        throw new Error('autoSignIn must never call signInWithFedCM');
+      }),
     });
     const auth = new CrossDomainAuth(services as unknown as OxyServices);
-    const selected: string[] = [];
-    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
 
-    const result = await auth.signIn({
-      method: 'auto',
-      onMethodSelected: (method) => selected.push(method),
-    });
+    const result = await auth.signIn({ method: 'auto' });
 
     expect(result).toBeNull();
-    expect(selected).toEqual(['fedcm', 'redirect']);
+    expect(services.signInWithFedCM).not.toHaveBeenCalled();
+    expect(services.isFedCMSupported).not.toHaveBeenCalled();
     expect(services.signInWithRedirect).toHaveBeenCalledTimes(1);
+  });
+
+  it('getRecommendedMethod always recommends redirect', () => {
+    const services = createMockServices({ isFedCMSupported: jest.fn(() => true) });
+    const auth = new CrossDomainAuth(services as unknown as OxyServices);
+
+    expect(auth.getRecommendedMethod().method).toBe('redirect');
+    expect(services.isFedCMSupported).not.toHaveBeenCalled();
+  });
+
+  it('silentSignIn falls back to iframe-based silent auth without ever calling FedCM', async () => {
+    const services = createMockServices({ isFedCMSupported: jest.fn(() => true) });
+    const auth = new CrossDomainAuth(services as unknown as OxyServices);
+
+    await auth.silentSignIn();
 
-    warnSpy.mockRestore();
+    expect(services.silentSignInWithFedCM).not.toHaveBeenCalled();
   });
 });

package/src/index.ts

@@ -530,6 +530,10 @@ export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
 
+// Post-claim durable-session establish hop (web device-flow / QR sign-in).
+export { establishIdpSessionAfterClaim } from './utils/ssoEstablish';
+export type { SsoEstablishClient, EstablishAfterClaimDeps } from './utils/ssoEstablish';
+
 // SSO bounce — per-origin sessionStorage keys, bounce URL builder, predicates
 export {
     SSO_CALLBACK_PATH,
@@ -562,6 +566,26 @@ export type {
     RunColdBootOptions,
 } from './utils/coldBoot';
 
+// ---------------------------------------------------------------------------
+// Session sync (device-scoped multi-account session client)
+// ---------------------------------------------------------------------------
+export { SessionClient } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+
+// Shared SessionClient integration layer: the host adapter, the pure
+// DeviceSessionState projection helpers, and the client factory are defined
+// ONCE here so `@oxyhq/services` and `@oxyhq/auth` both reuse them instead of
+// duplicating a local copy. Each consumer supplies its own `TokenTransport`
+// (native vs. web mint strategies differ) to `createSessionClient`.
+export { createSessionClientHost } from './session/sessionClientHost';
+export { createSessionClient } from './session/createSessionClient';
+export {
+    deviceStateToClientSessions,
+    activeSessionIdOf,
+    activeUserOf,
+    accountIdsOf,
+} from './session/projectSessionState';
+
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every
 // client SDK. Import them directly from `@oxyhq/contracts`; `@oxyhq/core` does NOT

package/src/mixins/OxyServices.sso.ts

@@ -49,6 +49,11 @@ interface SsoExchangeWireResponse {
   authuser?: number;
 }
 
+/** Wire shape of `POST /sso/establish-token`. */
+interface SsoEstablishTokenWireResponse {
+  establishUrl: string;
+}
+
 /**
  * Generate a cryptographically secure state value for the SSO bounce.
  *
@@ -202,5 +207,55 @@ export function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T) {
 
       return session;
     }
+
+    /**
+     * Mint a server-formed `/sso/establish` URL for the caller's OWN session,
+     * bound to an approved RP `origin`.
+     *
+     * Bearer-authenticated (the session id is taken from the caller's own
+     * bearer, server-side — never from any argument). The server validates that
+     * `origin` is an approved client origin (and matches the request `Origin`),
+     * derives the per-apex IdP host (`auth.<apex>`), mints a short-lived HS256
+     * establish-token, and returns a fully-formed
+     * `https://<auth-host>/sso/establish?et=…&return_to=<origin>/__oxy/sso-callback&state=<state>`.
+     *
+     * Used AFTER a web device-flow claim to plant the durable first-party
+     * `fedcm_session` cookie so a reload can re-mint a token (see
+     * {@link establishIdpSessionAfterClaim}). Cache-free (a POST is never
+     * cached, but `cache: false` is explicit).
+     *
+     * @param origin - The RP origin (`window.location.origin`) to establish for.
+     * @param state - The CSRF state echoed back in the callback fragment; the
+     *   caller persists the SAME value under `ssoStateKey(origin)` so the
+     *   post-bounce `sso-return` step validates it.
+     */
+    public async requestSsoEstablishUrl(
+      origin: string,
+      state: string,
+    ): Promise<{ establishUrl: string }> {
+      if (typeof origin !== 'string' || origin.length === 0) {
+        throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty origin'));
+      }
+      if (typeof state !== 'string' || state.length === 0) {
+        throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty state'));
+      }
+
+      const response = await this.makeRequest<SsoEstablishTokenWireResponse>(
+        'POST',
+        '/sso/establish-token',
+        { origin, state },
+        { cache: false },
+      );
+
+      if (
+        !response ||
+        typeof response.establishUrl !== 'string' ||
+        response.establishUrl.length === 0
+      ) {
+        throw this.handleError(new Error('SSO establish-token returned no establishUrl'));
+      }
+
+      return { establishUrl: response.establishUrl };
+    }
   };
 }

package/src/mixins/OxyServices.user.ts

@@ -796,6 +796,32 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Get the authenticated VIEWER's OWN mutual-follow user ids — the accounts the
+     * viewer follows that ALSO follow the viewer back (a bidirectional follow
+     * edge). The viewer is derived server-side from the SDK's auth token (never a
+     * param), so there is no target id to pass.
+     *
+     * Returns a bounded, lean list of ids meant to SEED a "Mutuals" feed (the
+     * consumer hydrates/ranks the posts itself) — distinct from
+     * {@link getUserMutuals}, which returns hydrated "followers you know" DTOs
+     * about ANOTHER profile. An anonymous caller resolves to an empty array.
+     */
+    async getMutualUserIds(
+      params?: { limit?: number }
+    ): Promise<string[]> {
+      try {
+        const query = buildPaginationParams(params || {});
+        const response = await this.makeRequest<{ data: string[] }>('GET', '/users/mutual-ids', query, {
+          cache: true,
+          cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+        });
+        return response.data || [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Get notifications
      */

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

@@ -166,6 +166,47 @@ describe('OxyServices.exchangeSsoCode', () => {
   });
 });
 
+describe('OxyServices.requestSsoEstablishUrl', () => {
+  const ESTABLISH_URL =
+    'https://auth.oxy.so/sso/establish?et=jwt&return_to=https%3A%2F%2Faccounts.oxy.so%2F__oxy%2Fsso-callback&state=s';
+
+  it('POSTs origin + state to /sso/establish-token (bearer, cache-free) and returns the URL', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const spy = jest
+      .spyOn(oxy, 'makeRequest')
+      .mockResolvedValue({ establishUrl: ESTABLISH_URL } as never);
+
+    const result = await oxy.requestSsoEstablishUrl('https://accounts.oxy.so', 's');
+
+    expect(result).toEqual({ establishUrl: ESTABLISH_URL });
+    expect(spy).toHaveBeenCalledWith(
+      'POST',
+      '/sso/establish-token',
+      { origin: 'https://accounts.oxy.so', state: 's' },
+      { cache: false },
+    );
+    spy.mockRestore();
+  });
+
+  it('rejects an empty origin or state without calling the API', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const spy = jest.spyOn(oxy, 'makeRequest');
+
+    await expect(oxy.requestSsoEstablishUrl('', 's')).rejects.toThrow();
+    await expect(oxy.requestSsoEstablishUrl('https://accounts.oxy.so', '')).rejects.toThrow();
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('throws when the server returns no establishUrl', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const spy = jest.spyOn(oxy, 'makeRequest').mockResolvedValue({} as never);
+
+    await expect(oxy.requestSsoEstablishUrl('https://accounts.oxy.so', 's')).rejects.toThrow();
+    spy.mockRestore();
+  });
+});
+
 describe('generateSsoState', () => {
   it('returns a non-empty unique string (module-level helper)', () => {
     const a = generateSsoState();

package/src/server/index.ts

@@ -63,3 +63,15 @@ export type { OxyCorsOptions } from './cors';
 
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret';
+
+// Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
+// SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.
+// Pure host handling (no browser deps), so it is safe on the server subpath and
+// lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
+export { registrableApex } from '../utils/fapiAutoDetect';
+
+// The single RP callback path the IdP redirects back to. A pure wire-contract
+// constant (no browser deps at module top level), re-used server-side so the
+// `/sso/establish-token` `return_to` cannot drift from what `/sso/establish`
+// validates.
+export { SSO_CALLBACK_PATH } from '../utils/ssoBounce';

package/src/session/SessionClient.ts

@@ -0,0 +1,175 @@
+import {
+  deviceSessionStateSchema,
+  deviceSessionSyncSchema,
+  safeParseContract,
+  type DeviceSessionState,
+} from '@oxyhq/contracts';
+import { logger } from '../utils/loggerUtils';
+import { getSocketIO } from './socketLoader';
+import type { MinimalSocket } from './socketLoader';
+
+export interface TokenTransport {
+  /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
+  ensureActiveToken(state: DeviceSessionState): Promise<void>;
+}
+
+export interface SessionClientHost {
+  makeRequest<T>(method: 'GET' | 'POST', url: string, data?: unknown, options?: { cache?: boolean }): Promise<T>;
+  getBaseURL(): string;
+  getAccessToken(): string | null;
+  onTokensChanged(listener: (token: string | null) => void): () => void;
+  setTokens(accessToken: string): void;
+  getCurrentAccountId(): string | null;
+}
+
+export interface SessionClientOptions {
+  transport?: TokenTransport;
+}
+
+type StateListener = (state: DeviceSessionState | null) => void;
+
+export class SessionClient {
+  private state: DeviceSessionState | null = null;
+  private readonly listeners = new Set<StateListener>();
+  protected socket: MinimalSocket | null = null;
+  private tokenUnsub: (() => void) | null = null;
+  private started = false;
+
+  constructor(
+    protected readonly host: SessionClientHost,
+    protected readonly options: SessionClientOptions = {},
+  ) {}
+
+  getState(): DeviceSessionState | null {
+    return this.state;
+  }
+
+  subscribe(listener: StateListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  protected notify(): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(this.state);
+      } catch (error) {
+        logger.error('[SessionClient] subscriber threw', error);
+      }
+    }
+  }
+
+  /** Validate + last-writer-wins by revision. Returns true if applied. */
+  protected applyState(raw: unknown): boolean {
+    const next = safeParseContract(deviceSessionStateSchema, raw);
+    if (!next) {
+      logger.warn('[SessionClient] discarded invalid session state');
+      return false;
+    }
+    if (this.state && next.revision <= this.state.revision) {
+      return false;
+    }
+    this.state = next;
+    this.notify();
+    if (this.options.transport) {
+      void this.options.transport.ensureActiveToken(next).catch((error) => {
+        logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+      });
+    }
+    return true;
+  }
+
+  /**
+   * Validate `{ state, activeToken }`, apply the state, and plant the active token host-side.
+   * Token-planting is decoupled from whether `applyState` advanced the revision: a socket push
+   * followed by this same `GET /state` fetch returns the SAME revision (applyState no-ops), but
+   * the token still needs to be planted. The account-match guard rejects a stale response for an
+   * account that is no longer active.
+   */
+  private applySync(raw: unknown): void {
+    const sync = safeParseContract(deviceSessionSyncSchema, raw);
+    if (!sync) {
+      logger.warn('[SessionClient] discarded invalid session sync');
+      return;
+    }
+    this.applyState(sync.state);
+    if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
+      this.host.setTokens(sync.activeToken.accessToken);
+    }
+  }
+
+  async bootstrap(): Promise<void> {
+    const res = await this.host.makeRequest<{ data?: unknown }>('GET', '/session/device/state', undefined, { cache: false });
+    this.applySync(res?.data);
+  }
+
+  async switchAccount(accountId: string): Promise<void> {
+    const res = await this.host.makeRequest<{ data?: unknown }>('POST', '/session/device/switch', { accountId }, { cache: false });
+    this.applySync(res?.data);
+  }
+
+  async signOut(target: { accountId: string } | { all: true }): Promise<void> {
+    const res = await this.host.makeRequest<{ data?: unknown }>('POST', '/session/device/signout', target, { cache: false });
+    this.applySync(res?.data);
+  }
+
+  async addCurrentAccount(): Promise<void> {
+    const res = await this.host.makeRequest<{ data?: unknown }>('POST', '/session/device/add', undefined, { cache: false });
+    this.applySync(res?.data);
+  }
+
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    this.tokenUnsub = this.host.onTokensChanged((token) => {
+      if (token && this.socket && !this.socket.connected) {
+        this.socket.connect();
+      }
+    });
+    await this.bootstrap();
+    await this.connectSocket();
+  }
+
+  stop(): void {
+    this.started = false;
+    if (this.tokenUnsub) {
+      this.tokenUnsub();
+      this.tokenUnsub = null;
+    }
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+  }
+
+  private async connectSocket(): Promise<void> {
+    const io = await getSocketIO();
+    if (!io) {
+      logger.warn('[SessionClient] no socket.io-client; running REST-only (no realtime sync)', { component: 'SessionClient' });
+      return;
+    }
+    if (!this.started) return; // stopped while the dynamic import was in flight
+    const hasToken = Boolean(this.host.getAccessToken());
+    const socket = io(this.host.getBaseURL(), {
+      transports: ['websocket'],
+      autoConnect: hasToken,
+      auth: (cb: (data: { token: string }) => void) => {
+        cb({ token: this.host.getAccessToken() ?? '' });
+      },
+    });
+    socket.on('session_state', (payload: unknown) => {
+      const applied = this.applyState(payload);
+      if (applied) {
+        const active = this.state?.activeAccountId ?? null;
+        if (active && active !== this.host.getCurrentAccountId()) {
+          void this.bootstrap().catch((error) => {
+            logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
+          });
+        }
+      }
+    });
+    this.socket = socket;
+  }
+}

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

@@ -0,0 +1,79 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+const STATE = (rev: number): DeviceSessionState => ({
+  deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000,
+});
+
+function makeHost(makeRequest: jest.Mock): SessionClientHost {
+  return {
+    makeRequest,
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 't',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => null,
+  };
+}
+
+// The server wraps the sync payload in a REST `{ data }` envelope; makeRequest does NOT unwrap it.
+const SYNC = (rev: number) => ({ data: { state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } } });
+
+describe('SessionClient REST', () => {
+  it('bootstrap GETs /session/device/state and applies it', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(SYNC(3));
+    const host = makeHost(makeRequest);
+    const c = new SessionClient(host);
+    await c.bootstrap();
+    expect(makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(c.getState()?.revision).toBe(3);
+    expect(host.setTokens).toHaveBeenCalledWith('jwt-3');
+  });
+
+  it('switchAccount POSTs and applies the returned state', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(SYNC(4));
+    const host = makeHost(makeRequest);
+    const c = new SessionClient(host);
+    await c.switchAccount('a1');
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/session/device/switch', { accountId: 'a1' }, { cache: false });
+    expect(c.getState()?.revision).toBe(4);
+    expect(host.setTokens).toHaveBeenCalledWith('jwt-4');
+  });
+
+  it('signOut one account POSTs { accountId }', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(SYNC(5));
+    const c = new SessionClient(makeHost(makeRequest));
+    await c.signOut({ accountId: 'a1' });
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/session/device/signout', { accountId: 'a1' }, { cache: false });
+  });
+
+  it('signOut all POSTs { all: true }', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(SYNC(6));
+    const c = new SessionClient(makeHost(makeRequest));
+    await c.signOut({ all: true });
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/session/device/signout', { all: true }, { cache: false });
+  });
+
+  it('addCurrentAccount POSTs /session/device/add with no body', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(SYNC(2));
+    const c = new SessionClient(makeHost(makeRequest));
+    await c.addCurrentAccount();
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/session/device/add', undefined, { cache: false });
+  });
+
+  it('does not throw / does not apply when the server returns invalid state', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce({ bogus: true });
+    const c = new SessionClient(makeHost(makeRequest));
+    await c.bootstrap();
+    expect(c.getState()).toBeNull();
+  });
+
+  it('applies state but does not plant a token when activeToken is null', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce({ data: { state: STATE(7), activeToken: null } });
+    const host = makeHost(makeRequest);
+    const c = new SessionClient(host);
+    await c.bootstrap();
+    expect(c.getState()?.revision).toBe(7);
+    expect(host.setTokens).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,132 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  on(event: string, cb: Handler) { const l = this.handlers.get(event) ?? []; l.push(cb); this.handlers.set(event, l); }
+  off(event: string, cb?: Handler) { if (!cb) { this.handlers.delete(event); return; } this.handlers.set(event, (this.handlers.get(event) ?? []).filter((h) => h !== cb)); }
+  connect() { this.connected = true; this.trigger('connect'); }
+  disconnect() { this.connected = false; }
+  trigger(event: string, ...args: unknown[]) { for (const h of this.handlers.get(event) ?? []) h(...args); }
+}
+let fakeSocket: FakeSocket;
+const ioMock = jest.fn((_uri: string, opts?: Record<string, unknown>) => {
+  // honor autoConnect like real socket.io (connect immediately unless autoConnect:false)
+  if (!opts || opts.autoConnect !== false) fakeSocket.connected = true;
+  return fakeSocket;
+});
+jest.mock('socket.io-client', () => ({ __esModule: true, io: (...args: unknown[]) => ioMock(...(args as [string, Record<string, unknown>?])) }));
+
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+// The server wraps the sync payload in a REST `{ data }` envelope; makeRequest does NOT unwrap it.
+const SYNC = (rev: number) => ({ data: { state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } } });
+
+function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
+  return {
+    makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 'tok',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => 'a1',
+    ...over,
+  };
+}
+
+beforeEach(() => { fakeSocket = new FakeSocket(); ioMock.mockClear(); });
+
+describe('SessionClient socket', () => {
+  it('start() bootstraps then opens ONE socket to the base URL with a token-in-handshake auth callback', async () => {
+    const host = makeHost();
+    const c = new SessionClient(host);
+    await c.start();
+    expect(host.makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(ioMock).toHaveBeenCalledTimes(1);
+    const [uri, opts] = ioMock.mock.calls[0];
+    expect(uri).toBe('http://test.invalid');
+    const authCb = jest.fn();
+    (opts?.auth as (cb: (d: { token: string }) => void) => void)(authCb);
+    expect(authCb).toHaveBeenCalledWith({ token: 'tok' });
+    c.stop();
+  });
+
+  it('applies a pushed session_state event', async () => {
+    const c = new SessionClient(makeHost());
+    await c.start();
+    fakeSocket.trigger('session_state', STATE(9));
+    expect(c.getState()?.revision).toBe(9);
+    c.stop();
+  });
+
+  it('fetches the active token via bootstrap when a pushed state changes the active account', async () => {
+    const makeRequest = jest.fn().mockResolvedValue(SYNC(1));
+    const host = makeHost({ makeRequest, getCurrentAccountId: () => 'other-account' });
+    const c = new SessionClient(host);
+    await c.start();
+    makeRequest.mockClear();
+    fakeSocket.trigger('session_state', STATE(9));
+    await Promise.resolve();
+    expect(makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    c.stop();
+  });
+
+  it('C1 regression: plants the active token on a socket-pushed switch even when the post-push bootstrap returns the SAME revision as the push', async () => {
+    const setTokens = jest.fn();
+    const makeRequest = jest
+      .fn()
+      .mockResolvedValueOnce(SYNC(1)) // initial bootstrap in start()
+      .mockResolvedValue(SYNC(9)); // post-push bootstrap: same revision as the socket push below
+    const host = makeHost({ makeRequest, setTokens, getCurrentAccountId: () => 'other-account' });
+    const c = new SessionClient(host);
+    await c.start();
+    makeRequest.mockClear();
+    setTokens.mockClear();
+    fakeSocket.trigger('session_state', STATE(9));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(setTokens).toHaveBeenCalledWith('jwt-9');
+    c.stop();
+  });
+
+  it('does not re-fetch when the pushed active account matches the host-held account', async () => {
+    const makeRequest = jest.fn().mockResolvedValue(SYNC(1));
+    const host = makeHost({ makeRequest, getCurrentAccountId: () => 'a1' });
+    const c = new SessionClient(host);
+    await c.start();
+    makeRequest.mockClear();
+    fakeSocket.trigger('session_state', STATE(9));
+    await Promise.resolve();
+    expect(makeRequest).not.toHaveBeenCalled();
+    c.stop();
+  });
+
+  it('does not connect the socket when there is no token (autoConnect false)', async () => {
+    const c = new SessionClient(makeHost({ getAccessToken: () => null }));
+    await c.start();
+    const [, opts] = ioMock.mock.calls[0];
+    expect(opts?.autoConnect).toBe(false);
+    c.stop();
+  });
+
+  it('reconnects when a token arrives after being disconnected', async () => {
+    let tokenListener: ((t: string | null) => void) | null = null;
+    const host = makeHost({ getAccessToken: () => null, onTokensChanged: (l) => { tokenListener = l; return () => undefined; } });
+    const c = new SessionClient(host);
+    await c.start();
+    fakeSocket.connected = false;
+    tokenListener?.('fresh-token');
+    expect(fakeSocket.connected).toBe(true);
+    c.stop();
+  });
+
+  it('stop() disconnects the socket', async () => {
+    const c = new SessionClient(makeHost());
+    await c.start();
+    c.stop();
+    expect(fakeSocket.connected).toBe(false);
+  });
+});