@oxy.so/core 1.0.0

package/src/session/__tests__/refresh.test.ts

@@ -0,0 +1,443 @@
+import type { OxyServices } from '../../OxyServices';
+import type { DeviceTokenMintResponse } from '@oxy.so/contracts';
+import type { SessionLoginResponse } from '../../models/session';
+import {
+  refreshPersistedSession,
+  startTokenRefreshScheduler,
+  type DeviceSecretMintOutcome,
+} from '../refresh';
+import {
+  createMemoryAuthStateStore,
+  type AuthStateStore,
+  type PersistedAuthState,
+} from '../authStateStore';
+
+/**
+ * A real, per-client device-secret mint single-flight matching
+ * `HttpService.runSingleFlightDeviceSecretMint`: concurrent callers await the
+ * SAME in-flight mint and all receive its result; a fresh call after it settles
+ * starts a new one.
+ */
+function makeMintSingleFlight(): (mint: () => Promise<DeviceSecretMintOutcome>) => Promise<DeviceSecretMintOutcome> {
+  let inFlight: Promise<DeviceSecretMintOutcome> | null = null;
+  return (mint) => {
+    if (!inFlight) {
+      inFlight = mint().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
+
+/** The persisted zero-cookie mint credential the refresh reads. */
+const STORED: PersistedAuthState = {
+  sessionId: 'sess-old',
+  userId: 'user-1',
+  deviceId: 'dev-mint',
+  deviceSecret: 'ds-secret-orig',
+};
+
+/** A successful `POST /session/device/token` mint (rotates the secret + active account). */
+const MINT: DeviceTokenMintResponse = {
+  accessToken: 'access-new',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  nextDeviceSecret: 'ds-next-secret',
+  state: {
+    deviceId: 'dev-mint',
+    accounts: [{ accountId: 'user-1', sessionId: 'sess-new', authuser: 0 }],
+    activeAccountId: 'user-1',
+    revision: 4,
+    updatedAt: 1_700_000_000_000,
+  },
+};
+
+interface RefreshMockOverrides {
+  mintFromDeviceSecret?: OxyServices['mintFromDeviceSecret'];
+  signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
+}
+
+function makeOxy(overrides: RefreshMockOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
+  const setTokens = jest.fn();
+  const oxy = {
+    setTokens,
+    mintFromDeviceSecret: overrides.mintFromDeviceSecret ?? (async () => MINT),
+    signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
+    // The rotating mint runs under the client's process-wide single-flight; the
+    // arm reaches for it via `oxy.httpService.runSingleFlightDeviceSecretMint`.
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+  } as unknown as OxyServices;
+  return { oxy, setTokens };
+}
+
+describe('refreshPersistedSession — arm 1 (device-secret mint)', () => {
+  it('mints, plants, persists the rotated secret + active account, and returns the token', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy, setTokens } = makeOxy();
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(token).toBe('access-new');
+    expect(setTokens).toHaveBeenCalledWith('access-new');
+    expect(await store.load()).toEqual({
+      sessionId: 'sess-new',
+      userId: 'user-1',
+      deviceId: 'dev-mint',
+      deviceSecret: 'ds-next-secret',
+      accessToken: 'access-new',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    });
+  });
+
+  it('presents the persisted deviceId + deviceSecret to the mint', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+  });
+
+  it('drops only the secret (keeps deviceId) on a 401 and falls to shared-key when native', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const SHARED: SessionLoginResponse = {
+      sessionId: 'sess-shared',
+      deviceId: 'dev-1',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+      user: { id: 'user-1', username: 'u', name: {}, avatar: undefined },
+      accessToken: 'access-shared',
+    };
+    const signInWithSharedIdentity = jest.fn(async () => SHARED);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        throw Object.assign(new Error('invalid_device_secret'), { status: 401 });
+      },
+      signInWithSharedIdentity,
+    });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+
+    expect(token).toBe('access-shared');
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+    const persisted = await store.load();
+    expect(persisted?.deviceSecret).toBeUndefined();
+    expect(persisted?.deviceId).toBe('dev-mint');
+  });
+
+  it('clears the store on a 401 when there is no shared-key fallback (web)', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        throw Object.assign(new Error('no_active_session'), { status: 401 });
+      },
+    });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(token).toBeNull();
+    expect(await store.load()).toBeNull();
+  });
+
+  it('KEEPS the store and returns null on a transient (500 / network) error', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        throw Object.assign(new Error('server'), { status: 500 });
+      },
+      signInWithSharedIdentity,
+    });
+
+    // A transient failure must NOT drop the credential nor fall through to shared-key.
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).toBeNull();
+    expect(await store.load()).toEqual(STORED);
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  it('KEEPS the store on an UNRECOGNIZED 401 (proxy / middleware / deploy-window) — never wipes the credential on an ambiguous 401', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        // A 401 whose body is NEITHER `invalid_device_secret` NOR `no_active_session`
+        // — an auth-layer / proxy / starting-instance 401 common during a deploy
+        // window. It is NOT proof the secret diverged, so the durable device
+        // credential must survive (treated as transient) and a later attempt self-heals.
+        throw Object.assign(new Error('Unauthorized'), { status: 401 });
+      },
+      signInWithSharedIdentity,
+    });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).toBeNull();
+    expect(await store.load()).toEqual(STORED);
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+});
+
+describe('refreshPersistedSession — arm 2 (native shared-key fallback)', () => {
+  const SHARED_SESSION: SessionLoginResponse = {
+    sessionId: 'sess-shared',
+    deviceId: 'dev-1',
+    expiresAt: '2030-01-01T00:00:00.000Z',
+    user: { id: 'user-1', username: 'u', name: {}, avatar: undefined },
+    accessToken: 'access-shared',
+  };
+
+  it('re-mints via shared identity when there is no persisted secret', async () => {
+    const store = createMemoryAuthStateStore(); // no stored device secret
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+
+    expect(token).toBe('access-shared');
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT try shared-key when the fallback is disabled (web)', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false })).toBeNull();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  it('returns null when the shared-key re-mint yields no session', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).toBeNull();
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+  });
+
+  it('persists the recovered credential from the shared-key re-mint (repopulates the fast lane)', async () => {
+    // Bug #3: an in-session shared-key recovery must repopulate the durable
+    // device credential, not leave the fast device-secret lane empty.
+    const store = createMemoryAuthStateStore(); // no persisted secret → arm 1 skips
+    const RECOVERED: SessionLoginResponse = {
+      sessionId: 'sess-shared',
+      deviceId: 'dev-shared',
+      deviceSecret: 'ds-shared-secret',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+      user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+      accessToken: 'access-shared',
+    };
+    const { oxy } = makeOxy({ signInWithSharedIdentity: jest.fn(async () => RECOVERED) });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+
+    expect(token).toBe('access-shared');
+    expect(await store.load()).toEqual({
+      sessionId: 'sess-shared',
+      userId: 'user-shared',
+      deviceId: 'dev-shared',
+      deviceSecret: 'ds-shared-secret',
+      accessToken: 'access-shared',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    });
+  });
+});
+
+describe('refreshPersistedSession — single-flight (no double-rotation)', () => {
+  it('coalesces two concurrent mints into ONE server rotation; the store holds the final current secret', async () => {
+    // The server rotates the secret on every mint. Two concurrent lanes must
+    // therefore share ONE in-flight mint (one rotation) or the store could
+    // converge on a superseded secret.
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+
+    let release: (() => void) | null = null;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const mintFromDeviceSecret = jest.fn(async (deviceId: string, deviceSecret: string) => {
+      // Block until BOTH callers have entered so the single-flight is exercised.
+      await gate;
+      expect(deviceId).toBe('dev-mint');
+      expect(deviceSecret).toBe('ds-secret-orig');
+      return MINT;
+    });
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const first = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+    const second = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+    // Both callers entered while the mint is in flight.
+    release?.();
+    const [t1, t2] = await Promise.all([first, second]);
+
+    // Exactly one server rotation despite two concurrent callers…
+    expect(mintFromDeviceSecret).toHaveBeenCalledTimes(1);
+    // …both callers received the same minted token…
+    expect(t1).toBe('access-new');
+    expect(t2).toBe('access-new');
+    // …and the durable store converged on the rotated (current) secret.
+    expect((await store.load())?.deviceSecret).toBe('ds-next-secret');
+    // The token was planted exactly once (inside the single-flighted mint).
+    expect(setTokens).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('refreshPersistedSession — durable persist failure is fatal to the mint', () => {
+  it('does NOT plant a token when the rotated secret cannot be durably persisted', async () => {
+    // Bug #2: a mint that rotated the server secret but could not persist it must
+    // not leave the process advertising a session on an unsaved, soon-dead secret.
+    const failingStore: AuthStateStore = {
+      load: async () => STORED,
+      save: async () => false, // durable write did not land
+      clear: async () => undefined,
+    };
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const token = await refreshPersistedSession({
+      oxy,
+      store: failingStore,
+      allowSharedKeyFallback: false,
+    });
+
+    // The mint ran (the server rotated) but the token was NOT planted…
+    expect(mintFromDeviceSecret).toHaveBeenCalledTimes(1);
+    expect(setTokens).not.toHaveBeenCalled();
+    // …and the lane reports failure rather than a healthy session.
+    expect(token).toBeNull();
+  });
+
+  it('does NOT fall through to the shared-key arm on a persist failure', async () => {
+    const failingStore: AuthStateStore = {
+      load: async () => STORED,
+      save: async () => false,
+      clear: async () => undefined,
+    };
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => MINT,
+      signInWithSharedIdentity,
+    });
+
+    await refreshPersistedSession({ oxy, store: failingStore, allowSharedKeyFallback: true });
+
+    // A storage failure is not a bad-secret signal — the shared-key arm must not run.
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+});
+
+describe('startTokenRefreshScheduler', () => {
+  function makeSchedulerOxy(expiresInSeconds: number | null): {
+    oxy: OxyServices;
+    refreshAccessToken: jest.Mock;
+  } {
+    let cleared = false;
+    const refreshAccessToken = jest.fn(async () => {
+      cleared = true; // stop the reschedule loop after the first fire
+      return null;
+    });
+    const nowSec = Math.floor(Date.now() / 1000);
+    const oxy = {
+      getAccessToken: () => (cleared ? null : 'tok'),
+      getAccessTokenExpiry: () => (expiresInSeconds === null ? null : nowSec + expiresInSeconds),
+      onTokensChanged: () => () => undefined,
+      httpService: { refreshAccessToken },
+    } as unknown as OxyServices;
+    return { oxy, refreshAccessToken };
+  }
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('fires a refresh ~60s before expiry', async () => {
+    jest.useFakeTimers();
+    const { oxy, refreshAccessToken } = makeSchedulerOxy(120);
+    const handle = startTokenRefreshScheduler(oxy);
+
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+    await jest.advanceTimersByTimeAsync(60_000);
+    expect(refreshAccessToken).toHaveBeenCalledWith('preflight');
+
+    handle.dispose();
+  });
+
+  it('no-ops cleanly for an opaque token with no exp', () => {
+    jest.useFakeTimers();
+    const { oxy, refreshAccessToken } = makeSchedulerOxy(null);
+    const handle = startTokenRefreshScheduler(oxy);
+    jest.advanceTimersByTime(10 * 60_000);
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+    handle.dispose();
+  });
+
+  it('backs off on repeated failure — bounded attempts, never a zero-delay busy loop', async () => {
+    jest.useFakeTimers();
+    // Already-expired token + a refresh that ALWAYS fails. The old code floored
+    // the delay to 0 and re-armed in the finally block → a tight loop that would
+    // exhaust jest's 100k-timer guard. The backoff schedule fires only a handful
+    // of times per simulated minute.
+    const refreshAccessToken = jest.fn(async () => null);
+    const nowSec = Math.floor(Date.now() / 1000);
+    const oxy = {
+      getAccessToken: () => 'tok',
+      getAccessTokenExpiry: () => nowSec - 10,
+      onTokensChanged: () => () => undefined,
+      httpService: { refreshAccessToken },
+    } as unknown as OxyServices;
+
+    const handle = startTokenRefreshScheduler(oxy);
+    await jest.advanceTimersByTimeAsync(60_000);
+
+    expect(refreshAccessToken.mock.calls.length).toBeGreaterThan(0);
+    expect(refreshAccessToken.mock.calls.length).toBeLessThan(10);
+    handle.dispose();
+  });
+
+  it('resets the backoff after a successful refresh', async () => {
+    jest.useFakeTimers();
+    // Expiry is always ~1h from NOW, so a successful refresh genuinely pushes
+    // the token out (as a real rotation would). Fail once, then succeed.
+    const refreshAccessToken = jest
+      .fn<Promise<string | null>, [unknown]>()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue('fresh');
+    const oxy = {
+      getAccessToken: () => 'tok',
+      getAccessTokenExpiry: () => Math.floor(Date.now() / 1000) + 3600,
+      onTokensChanged: () => () => undefined,
+      httpService: { refreshAccessToken },
+    } as unknown as OxyServices;
+
+    const handle = startTokenRefreshScheduler(oxy);
+    // First fire ~ (3600-60)s out (fails → 5s backoff), then the backoff fire
+    // succeeds and re-arms ~1h out from the (now-fresh) expiry.
+    await jest.advanceTimersByTimeAsync((3600 - 60) * 1000);
+    await jest.advanceTimersByTimeAsync(5_000);
+    const callsAfterSuccess = refreshAccessToken.mock.calls.length;
+    expect(callsAfterSuccess).toBe(2); // one failure + one success
+    // A further minute must NOT produce a burst — the healthy re-arm is ~1h out.
+    await jest.advanceTimersByTimeAsync(60_000);
+    expect(refreshAccessToken.mock.calls.length).toBe(callsAfterSuccess);
+    handle.dispose();
+  });
+
+  it('calls unref() on its timer so it never holds the event loop', () => {
+    const unref = jest.fn();
+    const setTimeoutSpy = jest
+      .spyOn(global, 'setTimeout')
+      .mockReturnValue({ unref } as unknown as ReturnType<typeof setTimeout>);
+    const { oxy } = makeSchedulerOxy(120);
+
+    const handle = startTokenRefreshScheduler(oxy);
+    expect(setTimeoutSpy).toHaveBeenCalled();
+    expect(unref).toHaveBeenCalled();
+
+    handle.dispose();
+    setTimeoutSpy.mockRestore();
+  });
+});

package/src/session/__tests__/sessionIntegration.test.ts

@@ -0,0 +1,209 @@
+import type { DeviceSessionState } from '@oxy.so/contracts';
+import type { User } from '../../models/interfaces';
+import { SessionClient, type TokenTransport } from '../SessionClient';
+import { createSessionClientHost } from '../sessionClientHost';
+import { createSessionClient } from '../createSessionClient';
+import {
+  accountIdsOf,
+  activeSessionIdOf,
+  activeUserOf,
+  deviceStateToClientSessions,
+} from '../projectSessionState';
+
+function fakeOxy() {
+  const listeners = new Set<(t: string | null) => void>();
+  return {
+    makeRequest: jest.fn().mockResolvedValue({ ok: true }),
+    getBaseURL: jest.fn().mockReturnValue('https://api.oxy.so'),
+    getAccessToken: jest.fn().mockReturnValue('tok'),
+    setTokens: jest.fn(),
+    onTokensChanged: jest.fn((l: (t: string | null) => void) => {
+      listeners.add(l);
+      return () => listeners.delete(l);
+    }),
+    _emit: (t: string | null) => listeners.forEach((l) => l(t)),
+  };
+}
+
+describe('createSessionClientHost', () => {
+  test('delegates REST + token methods to oxyServices', async () => {
+    const oxy = fakeOxy();
+    const host = createSessionClientHost(oxy as never);
+    await host.makeRequest('GET', '/session/device/state', undefined, { cache: false });
+    expect(oxy.makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(host.getBaseURL()).toBe('https://api.oxy.so');
+    expect(host.getAccessToken()).toBe('tok');
+    host.setTokens('new');
+    expect(oxy.setTokens).toHaveBeenCalledWith('new');
+  });
+
+  test('getCurrentAccountId reflects setCurrentAccountId', () => {
+    const host = createSessionClientHost(fakeOxy() as never);
+    expect(host.getCurrentAccountId()).toBeNull();
+    host.setCurrentAccountId('u1');
+    expect(host.getCurrentAccountId()).toBe('u1');
+  });
+
+  test('setDeviceCredential reflects on getDeviceCredential', () => {
+    const host = createSessionClientHost(fakeOxy() as never);
+    expect(host.getDeviceCredential()).toBeNull();
+    host.setDeviceCredential({ deviceId: 'd1', deviceSecret: 's1' });
+    expect(host.getDeviceCredential()).toEqual({ deviceId: 'd1', deviceSecret: 's1' });
+  });
+
+  test('onTokensChanged forwards to oxyServices and unsubscribes', () => {
+    const oxy = fakeOxy();
+    const host = createSessionClientHost(oxy as never);
+    const cb = jest.fn();
+    const unsub = host.onTokensChanged(cb);
+    oxy._emit(null);
+    expect(cb).toHaveBeenCalledWith(null);
+    unsub();
+    oxy._emit('x');
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+});
+
+function makeUser(id: string): User {
+  return {
+    id,
+    publicKey: `pk-${id}`,
+    username: `user-${id}`,
+    name: {},
+  };
+}
+
+// DeviceSessionState.updatedAt is an epoch-ms number on the wire (see
+// packages/contracts/src/deviceSession.ts: `updatedAt: z.number()`), not an
+// ISO string.
+const UPDATED_AT_MS = Date.UTC(2026, 6, 1, 0, 0, 0, 0);
+const UPDATED_AT_ISO = new Date(UPDATED_AT_MS).toISOString();
+
+const state: DeviceSessionState = {
+  deviceId: 'device-1',
+  accounts: [
+    { accountId: 'a1', sessionId: 'sess-a1', authuser: 0 },
+    { accountId: 'a2', sessionId: 'sess-a2', authuser: 1 },
+  ],
+  activeAccountId: 'a2',
+  revision: 1,
+  updatedAt: UPDATED_AT_MS,
+};
+
+const usersById = new Map<string, User>([
+  ['a1', makeUser('a1')],
+  ['a2', makeUser('a2')],
+]);
+
+describe('projectSessionState', () => {
+  describe('activeSessionIdOf', () => {
+    test('returns the active account sessionId', () => {
+      expect(activeSessionIdOf(state)).toBe('sess-a2');
+    });
+
+    test('returns null for null state', () => {
+      expect(activeSessionIdOf(null)).toBeNull();
+    });
+
+    test('returns null when activeAccountId is null', () => {
+      expect(activeSessionIdOf({ ...state, activeAccountId: null })).toBeNull();
+    });
+  });
+
+  describe('deviceStateToClientSessions', () => {
+    test('maps every account in order with isCurrent + authuser', () => {
+      const sessions = deviceStateToClientSessions(state, usersById);
+      expect(sessions).toHaveLength(2);
+      expect(sessions[0]).toEqual({
+        sessionId: 'sess-a1',
+        deviceId: 'device-1',
+        expiresAt: UPDATED_AT_ISO,
+        lastActive: UPDATED_AT_ISO,
+        userId: 'a1',
+        isCurrent: false,
+        authuser: 0,
+      });
+      expect(sessions[1]).toEqual({
+        sessionId: 'sess-a2',
+        deviceId: 'device-1',
+        expiresAt: UPDATED_AT_ISO,
+        lastActive: UPDATED_AT_ISO,
+        userId: 'a2',
+        isCurrent: true,
+        authuser: 1,
+      });
+    });
+
+    test('still projects a session for an account absent from usersById', () => {
+      const sessions = deviceStateToClientSessions(state, new Map());
+      expect(sessions).toHaveLength(2);
+      expect(sessions.map((session) => session.userId)).toEqual(['a1', 'a2']);
+    });
+  });
+
+  describe('activeUserOf', () => {
+    test('returns the active account user', () => {
+      expect(activeUserOf(state, usersById)).toEqual(makeUser('a2'));
+    });
+
+    test('returns null for null state', () => {
+      expect(activeUserOf(null, usersById)).toBeNull();
+    });
+
+    test('returns null when activeAccountId is null', () => {
+      expect(activeUserOf({ ...state, activeAccountId: null }, usersById)).toBeNull();
+    });
+
+    test('returns null when the active account id is absent from usersById', () => {
+      expect(activeUserOf(state, new Map())).toBeNull();
+    });
+  });
+
+  describe('accountIdsOf', () => {
+    test('returns every account id in order', () => {
+      expect(accountIdsOf(state)).toEqual(['a1', 'a2']);
+    });
+
+    test('returns [] for null state', () => {
+      expect(accountIdsOf(null)).toEqual([]);
+    });
+  });
+});
+
+describe('createSessionClient', () => {
+  function fakeTransport(): TokenTransport {
+    return { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+  }
+
+  test('wires a SessionClient instance backed by the host + injected transport', () => {
+    const oxy = fakeOxy();
+
+    const { client, host } = createSessionClient(oxy as never, fakeTransport());
+
+    expect(client).toBeInstanceOf(SessionClient);
+    expect(typeof client.bootstrap).toBe('function');
+    expect(client.getState()).toBeNull();
+    expect(typeof host.setCurrentAccountId).toBe('function');
+  });
+
+  test('the returned host reflects setCurrentAccountId', () => {
+    const oxy = fakeOxy();
+
+    const { host } = createSessionClient(oxy as never, fakeTransport());
+
+    expect(host.getCurrentAccountId()).toBeNull();
+    host.setCurrentAccountId('u1');
+    expect(host.getCurrentAccountId()).toBe('u1');
+  });
+
+  test('uses the injected transport (not a hard-coded one) when the client bootstraps', async () => {
+    const oxy = fakeOxy();
+    oxy.makeRequest.mockResolvedValue({ state, activeToken: null });
+    const transport = fakeTransport();
+
+    const { client } = createSessionClient(oxy as never, transport);
+    await client.bootstrap();
+
+    expect(transport.ensureActiveToken).toHaveBeenCalledWith(expect.objectContaining({ revision: state.revision }));
+  });
+});