@oxyhq/core 5.2.1 → 5.4.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,60 @@ 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 the authenticated VIEWER's bounded "follows-of-follows" user ids — the
+     * union of the accounts followed by the accounts the viewer follows (a
+     * two-hop walk of the follow graph), MINUS the viewer's own follows and the
+     * viewer themselves. 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 friends-of-friends
+     * feed (the consumer hydrates/ranks the posts itself), ordered by frequency
+     * (accounts followed by more of the viewer's follows first), then recency.
+     * An anonymous caller resolves to an empty array. Mirrors
+     * {@link getMutualUserIds}'s caching posture.
+     */
+    async getFollowsOfFollowsIds(
+      params?: { limit?: number }
+    ): Promise<string[]> {
+      try {
+        const query = buildPaginationParams(params || {});
+        const response = await this.makeRequest<{ data: string[] }>('GET', '/users/follows-of-follows-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,187 @@
+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) {
+      const parsed = deviceSessionSyncSchema.safeParse(raw);
+      // Log field-level type diagnostics ONLY — never values. The payload carries tokens and
+      // session ids; issue.path/code and the invalid_type expected/received TYPE names are safe,
+      // but zod messages can embed offending values for other codes, so they are omitted.
+      const issues = parsed.success
+        ? []
+        : parsed.error.issues.map((issue) =>
+            issue.code === 'invalid_type'
+              ? { path: issue.path.join('.'), code: issue.code, expected: issue.expected, received: issue.received }
+              : { path: issue.path.join('.'), code: issue.code },
+          );
+      const keys = raw && typeof raw === 'object' ? Object.keys(raw) : [];
+      logger.warn('[SessionClient] discarded invalid session sync', { component: 'SessionClient', issues, keys });
+      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<unknown>('GET', '/session/device/state', undefined, { cache: false });
+    this.applySync(res);
+  }
+
+  async switchAccount(accountId: string): Promise<void> {
+    const res = await this.host.makeRequest<unknown>('POST', '/session/device/switch', { accountId }, { cache: false });
+    this.applySync(res);
+  }
+
+  async signOut(target: { accountId: string } | { all: true }): Promise<void> {
+    const res = await this.host.makeRequest<unknown>('POST', '/session/device/signout', target, { cache: false });
+    this.applySync(res);
+  }
+
+  async addCurrentAccount(): Promise<void> {
+    const res = await this.host.makeRequest<unknown>('POST', '/session/device/add', undefined, { cache: false });
+    this.applySync(res);
+  }
+
+  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.diagnostics.test.ts

@@ -0,0 +1,90 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+import { logger } from '../../utils/loggerUtils';
+
+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,
+  };
+}
+
+describe('SessionClient sync diagnostics', () => {
+  let warnSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it('logs the failing zod issue path + code when a nested field is the wrong type', async () => {
+    // authuser must be a non-negative integer; a string trips invalid_type at accounts[0].authuser.
+    const badAuthuser = { accountId: 'a1', sessionId: 's1', authuser: 'not-a-number' };
+    const state = { ...STATE(3), accounts: [badAuthuser] };
+    const makeRequest = jest.fn().mockResolvedValueOnce({ state, activeToken: null });
+    const c = new SessionClient(makeHost(makeRequest));
+
+    await c.bootstrap();
+
+    expect(c.getState()).toBeNull();
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[SessionClient] discarded invalid session sync',
+      expect.objectContaining({ component: 'SessionClient' }),
+    );
+    const context = warnSpy.mock.calls[0][1];
+    expect(context.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: 'state.accounts.0.authuser', code: 'invalid_type' }),
+      ]),
+    );
+    // invalid_type issues carry TYPE names (safe), not values.
+    const authuserIssue = context.issues.find((i: { path: string }) => i.path === 'state.accounts.0.authuser');
+    expect(authuserIssue.received).toBe('string');
+    expect(authuserIssue.expected).toBe('number');
+    // Top-level envelope keys are summarized to catch drift.
+    expect(context.keys).toEqual(['state', 'activeToken']);
+  });
+
+  it('never leaks token-like values into the logged diagnostics', async () => {
+    // A valid-looking accessToken alongside an otherwise-invalid state must not surface in the log.
+    const secretToken = 'jwt-SUPER-SECRET-ACCESS-TOKEN-abc123';
+    const makeRequest = jest.fn().mockResolvedValueOnce({
+      state: { deviceId: 'd1' /* missing required fields */ },
+      activeToken: { accessToken: secretToken, expiresAt: 'x' },
+    });
+    const c = new SessionClient(makeHost(makeRequest));
+
+    await c.bootstrap();
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const serialized = JSON.stringify(warnSpy.mock.calls[0]);
+    expect(serialized).not.toContain(secretToken);
+    expect(serialized).not.toContain('SUPER-SECRET');
+  });
+
+  it('reports envelope drift via keys and a top-level invalid_type when raw is undefined', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(undefined);
+    const c = new SessionClient(makeHost(makeRequest));
+
+    await c.bootstrap();
+
+    const context = warnSpy.mock.calls[0][1];
+    expect(context.keys).toEqual([]);
+    expect(context.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: '', code: 'invalid_type', expected: 'object', received: 'undefined' }),
+      ]),
+    );
+  });
+});

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

@@ -0,0 +1,65 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+import { SessionClient } from '../SessionClient';
+import { createSessionClientHost } from '../sessionClientHost';
+
+/**
+ * Real-stack integration test: a genuine `HttpService` (via `OxyServices`) →
+ * `createSessionClientHost` → `SessionClient`, with `global.fetch` stubbed to
+ * return the EXACT wire body the server sends for `GET /session/device/state`:
+ * `{ data: { state, activeToken } }`.
+ *
+ * This is the test that would have caught the P0: `HttpService.unwrapResponse`
+ * strips the outer `{ data }` envelope, so `makeRequest` already returns
+ * `{ state, activeToken }`. If `SessionClient` reads `.data` a SECOND time (or
+ * if `HttpService` stops unwrapping), the sync silently discards and neither
+ * the state nor the token reach the client — exactly the prod symptom.
+ */
+const WIRE_STATE: DeviceSessionState = {
+  deviceId: 'device-real',
+  accounts: [{ accountId: 'acct-1', sessionId: 'sess-1', authuser: 0 }],
+  activeAccountId: 'acct-1',
+  revision: 42,
+  updatedAt: 1720000000000,
+};
+
+const ROUTE_BODY = {
+  data: {
+    state: WIRE_STATE,
+    activeToken: { accessToken: 'planted-access-token', expiresAt: '2026-01-01T00:00:00.000Z' },
+  },
+};
+
+describe('SessionClient over a real HttpService (unwrap contract)', () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('bootstrap() applies the server state and plants the active token through the real unwrap path', async () => {
+    const fetchMock = jest.fn(async () =>
+      new Response(JSON.stringify(ROUTE_BODY), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+    global.fetch = fetchMock as unknown as typeof fetch;
+
+    const oxy = new OxyServices({ baseURL: 'http://api.test.invalid' });
+    const host = createSessionClientHost(oxy);
+    const client = new SessionClient(host);
+
+    await client.bootstrap();
+
+    // The exact URL the server route serves.
+    const calledUrl = String((fetchMock.mock.calls[0] ?? [])[0]);
+    expect(calledUrl).toContain('/session/device/state');
+
+    // State reached the client (would be null if `.data` were read twice).
+    expect(client.getState()).toEqual(WIRE_STATE);
+
+    // Active token planted host-side (would be absent on a discarded sync).
+    expect(oxy.getAccessToken()).toBe('planted-access-token');
+  });
+});