@oxyhq/core 6.0.0 → 7.1.0

package/src/session/SessionClient.ts

@@ -9,7 +9,7 @@ import { getSocketIO } from './socketLoader';
 import type { MinimalSocket, SocketIOFactory } 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. */
+  /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
   ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
 
@@ -46,16 +46,62 @@ export interface SessionClientOptions {
    * absent it falls back to `getSocketIO()`.
    */
   socketFactory?: SocketIOFactory;
+  /**
+   * Gate + credential for opening the realtime socket while SIGNED OUT (no
+   * access token), so an idle tab still joins its `device:<id>` room and can
+   * self-acquire the moment a sibling app/tab signs in on the same device.
+   * Returns:
+   *   - `true`   → connect and rely on the first-party `oxy_device` cookie
+   *     riding the same-site handshake (web `*.oxy.so`; the cookie is HttpOnly
+   *     so JS cannot read it, but the browser sends it automatically).
+   *   - a string → connect and present it as `deviceToken` in the handshake
+   *     auth (native shared-keychain device token; RN has no cookie jar).
+   *   - `false`/`null` → do NOT open a signed-out socket (the default — e.g. a
+   *     native app with no known device yet).
+   * Called at connect time (and each reconnect); may be async (keychain read).
+   */
+  signedOutSocketAuth?: () => boolean | string | null | Promise<boolean | string | null>;
+  /**
+   * Invoked when a `session_state` push (or a same-origin BroadcastChannel wake)
+   * arrives while this tab is SIGNED OUT and the pushed device state has at
+   * least one account — i.e. a sibling just signed in on this device. The
+   * consumer runs its session acquisition (cold boot / `requestWebSession`),
+   * which plants a token and flips the tab to signed-in. Guarded + idempotent:
+   * only one acquisition runs at a time, and a returned promise gates the next.
+   */
+  onSessionAppeared?: () => void | Promise<void>;
 }
 
 type StateListener = (state: DeviceSessionState | null) => void;
 
+/**
+ * Same-origin `BroadcastChannel` name for instant, network-free session wake
+ * across tabs of the SAME origin (e.g. two `accounts.oxy.so` tabs). Complements
+ * the cookie-authed device socket, which covers same-apex cross-origin
+ * (`accounts` ↔ `console` ↔ `inbox`, all `*.oxy.so`). Cross-APEX (mention.earth)
+ * is covered by neither and relies on a reload — the documented limitation.
+ */
+const SESSION_BROADCAST_CHANNEL = 'oxy.session';
+
+/** A minimal, feature-detected `BroadcastChannel` surface (absent on native RN). */
+interface SessionBroadcastChannel {
+  postMessage(message: unknown): void;
+  close(): void;
+  onmessage: ((event: { data: unknown }) => void) | null;
+}
+
 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;
+  /** In-flight guard so a burst of pushes triggers at most ONE acquisition. */
+  private acquiring = false;
+  /** True while the live socket is an anonymous (signed-out) device connection. */
+  private socketAnonymous = false;
+  /** Same-origin cross-tab wake channel; null on platforms without BroadcastChannel. */
+  private channel: SessionBroadcastChannel | null = null;
 
   constructor(
     protected readonly host: SessionClientHost,
@@ -161,16 +207,19 @@ export class SessionClient {
   async switchAccount(accountId: string): Promise<void> {
     const res = await this.host.makeRequest<unknown>('POST', '/session/device/switch', { accountId }, { cache: false });
     this.applySync(res);
+    this.postCommitPing();
   }
 
   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);
+    this.postCommitPing();
   }
 
   async addCurrentAccount(): Promise<void> {
     const res = await this.host.makeRequest<unknown>('POST', '/session/device/add', undefined, { cache: false });
     this.applySync(res);
+    this.postCommitPing();
   }
 
   /**
@@ -199,20 +248,54 @@ export class SessionClient {
     if (this.started) return;
     this.started = true;
     this.tokenUnsub = this.host.onTokensChanged((token) => {
-      if (token && this.socket && !this.socket.connected) {
+      if (!token) return;
+      // A bearer just landed: an in-flight acquisition (if any) succeeded — clear
+      // the guard so a later sign-out can re-acquire.
+      this.acquiring = false;
+      if (!this.socket) return;
+      if (this.socketAnonymous) {
+        // The live socket was an anonymous (device-room-only) connection. Force a
+        // reconnect so the handshake re-runs authenticated and also joins the
+        // `user:<id>` notification room.
+        this.socketAnonymous = false;
+        this.socket.disconnect();
+        this.socket.connect();
+      } else if (!this.socket.connected) {
         this.socket.connect();
       }
     });
-    await this.bootstrap();
+    this.openBroadcastChannel();
+    // `bootstrap` (`GET /session/device/state`) is bearer-authenticated: skip it
+    // when signed out (the signed-out socket below still joins the device room to
+    // receive pushes). A bootstrap failure is non-fatal — the socket must still
+    // connect so realtime sync survives a transient state-fetch error.
+    if (this.host.getAccessToken()) {
+      try {
+        await this.bootstrap();
+      } catch (error) {
+        logger.warn('[SessionClient] bootstrap during start failed (non-fatal)', { component: 'SessionClient' }, error);
+      }
+    }
     await this.connectSocket();
   }
 
   stop(): void {
     this.started = false;
+    this.acquiring = false;
+    this.socketAnonymous = false;
     if (this.tokenUnsub) {
       this.tokenUnsub();
       this.tokenUnsub = null;
     }
+    if (this.channel) {
+      this.channel.onmessage = null;
+      try {
+        this.channel.close();
+      } catch (error) {
+        logger.debug('[SessionClient] BroadcastChannel close failed', { component: 'SessionClient' }, error);
+      }
+      this.channel = null;
+    }
     if (this.socket) {
       this.socket.disconnect();
       this.socket = null;
@@ -230,24 +313,131 @@ export class SessionClient {
     }
     if (!this.started) return; // stopped while the dynamic import was in flight
     const hasToken = Boolean(this.host.getAccessToken());
+
+    // Signed-out connect gate: when there is no bearer, only open the socket if
+    // the consumer supplies a device anchor (web cookie → `true`; native token →
+    // string). This lets an idle tab receive its device's `session_state` pushes
+    // and self-acquire when a sibling signs in.
+    let signedOutAuth: boolean | string | null = false;
+    if (!hasToken && this.options.signedOutSocketAuth) {
+      try {
+        signedOutAuth = await this.options.signedOutSocketAuth();
+      } catch (error) {
+        logger.warn('[SessionClient] signedOutSocketAuth failed', { component: 'SessionClient' }, error);
+        signedOutAuth = false;
+      }
+      if (!this.started) return; // stopped while the async gate was in flight
+    }
+    const signedOutConnect = signedOutAuth !== false && signedOutAuth != null;
+    const signedOutDeviceToken = typeof signedOutAuth === 'string' ? signedOutAuth : undefined;
+    this.socketAnonymous = !hasToken && signedOutConnect;
+
     const socket = io(this.host.getBaseURL(), {
       transports: ['websocket'],
-      autoConnect: hasToken,
-      auth: (cb: (data: { token: string }) => void) => {
-        cb({ token: this.host.getAccessToken() ?? '' });
+      // Send the first-party `oxy_device` cookie on the same-site handshake so a
+      // signed-out browser tab can be resolved to its device room server-side.
+      withCredentials: true,
+      autoConnect: hasToken || signedOutConnect,
+      auth: (cb: (data: { token: string; deviceToken?: string }) => void) => {
+        const token = this.host.getAccessToken() ?? '';
+        // Present the native device token only while signed out (no bearer). Once
+        // a token is held the bearer path wins and the deviceToken is redundant.
+        cb(token || !signedOutDeviceToken ? { token } : { token, deviceToken: signedOutDeviceToken });
       },
     });
     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);
-          });
+      if (!applied) return;
+      // Signed-out tab: a session appeared on this device (a sibling signed in).
+      // Acquire it so this tab flips to signed-in; the planted token then
+      // reconnects the socket on the authenticated path.
+      if (!this.host.getAccessToken()) {
+        if ((this.state?.accounts.length ?? 0) > 0) {
+          this.requestAcquisition();
         }
+        return;
+      }
+      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;
   }
+
+  /**
+   * Run the consumer's session acquisition at most once at a time. A returned
+   * promise gates the next attempt (reset on settle), so a failed acquisition
+   * can retry on the NEXT push while a burst of identical pushes cannot pile up.
+   */
+  private requestAcquisition(): void {
+    if (this.acquiring || !this.options.onSessionAppeared) return;
+    this.acquiring = true;
+    let result: void | Promise<void>;
+    try {
+      result = this.options.onSessionAppeared();
+    } catch (error) {
+      this.acquiring = false;
+      logger.error('[SessionClient] onSessionAppeared threw', error);
+      return;
+    }
+    void Promise.resolve(result).catch((error) => {
+      logger.warn('[SessionClient] onSessionAppeared rejected', { component: 'SessionClient' }, error);
+    }).finally(() => {
+      this.acquiring = false;
+    });
+  }
+
+  /**
+   * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
+   * commits a session posts a wake ping; on receipt a signed-in tab re-syncs its
+   * device state and a signed-out tab self-acquires — instant + network-free for
+   * the common "two tabs of the same origin" case, with no state (and no tokens)
+   * ever crossing the channel. No-op on native (no BroadcastChannel).
+   */
+  private openBroadcastChannel(): void {
+    if (this.channel) return;
+    const Ctor = (globalThis as { BroadcastChannel?: new (name: string) => SessionBroadcastChannel }).BroadcastChannel;
+    if (typeof Ctor !== 'function') return; // native RN / SSR — feature absent
+    let channel: SessionBroadcastChannel;
+    try {
+      channel = new Ctor(SESSION_BROADCAST_CHANNEL);
+    } catch (error) {
+      logger.debug('[SessionClient] BroadcastChannel unavailable', { component: 'SessionClient' }, error);
+      return;
+    }
+    channel.onmessage = (event) => {
+      if (!event || typeof event.data !== 'object' || event.data === null) return;
+      if ((event.data as { type?: unknown }).type !== 'commit') return;
+      // BroadcastChannel never echoes to the posting context, so this is a
+      // sibling's commit. Re-sync (signed-in) or acquire (signed-out). Neither
+      // path re-posts, so there is no cross-tab ping loop.
+      if (this.host.getAccessToken()) {
+        void this.bootstrap().catch((error) => {
+          logger.warn('[SessionClient] broadcast re-sync failed', { component: 'SessionClient' }, error);
+        });
+      } else {
+        this.requestAcquisition();
+      }
+    };
+    this.channel = channel;
+  }
+
+  /**
+   * Wake same-origin sibling tabs after a locally-initiated session mutation.
+   * Opens the channel lazily: a sign-in registers the account (`addCurrentAccount`
+   * / `switchAccount`) BEFORE `start()` runs, so the ping must not depend on
+   * `start()` having opened the channel first.
+   */
+  private postCommitPing(): void {
+    this.openBroadcastChannel();
+    if (!this.channel) return;
+    try {
+      this.channel.postMessage({ type: 'commit', at: Date.now() });
+    } catch (error) {
+      logger.debug('[SessionClient] BroadcastChannel post failed', { component: 'SessionClient' }, error);
+    }
+  }
 }

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

@@ -0,0 +1,224 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  connectCalls = 0;
+  disconnectCalls = 0;
+  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.connectCalls += 1; this.connected = true; this.trigger('connect'); }
+  disconnect() { this.disconnectCalls += 1; this.connected = false; }
+  trigger(event: string, ...args: unknown[]) { for (const h of this.handlers.get(event) ?? []) h(...args); }
+}
+let fakeSocket: FakeSocket;
+let lastOpts: Record<string, unknown> | undefined;
+const ioMock = jest.fn((_uri: string, opts?: Record<string, unknown>) => {
+  lastOpts = opts;
+  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>?])) }));
+
+// A same-name in-process BroadcastChannel bus: postMessage delivers to every
+// OTHER open channel of the same name (never the sender) — matching the spec.
+type BusEntry = { name: string; onmessage: ((event: { data: unknown }) => void) | null };
+const bus = new Set<BusEntry>();
+class FakeBroadcastChannel {
+  private entry: BusEntry;
+  constructor(public name: string) { this.entry = { name, onmessage: null }; bus.add(this.entry); }
+  get onmessage(): ((event: { data: unknown }) => void) | null { return this.entry.onmessage; }
+  set onmessage(cb: ((event: { data: unknown }) => void) | null) { this.entry.onmessage = cb; }
+  postMessage(data: unknown) {
+    for (const e of bus) {
+      if (e === this.entry || e.name !== this.name) continue;
+      e.onmessage?.({ data });
+    }
+  }
+  close() { bus.delete(this.entry); }
+}
+
+import { SessionClient, type SessionClientHost, type SessionClientOptions } from '../SessionClient';
+
+const STATE = (rev: number, accounts = [{ accountId: 'a1', sessionId: 's1', authuser: 0 }]): DeviceSessionState =>
+  ({ deviceId: 'd1', accounts, activeAccountId: accounts[0]?.accountId ?? null, revision: rev, updatedAt: 1720000000000 });
+const SYNC = (rev: number) => ({ 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: () => null,
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => null,
+    ...over,
+  };
+}
+
+const flush = async () => { await Promise.resolve(); await Promise.resolve(); };
+
+beforeEach(() => {
+  fakeSocket = new FakeSocket();
+  lastOpts = undefined;
+  ioMock.mockClear();
+  bus.clear();
+  (globalThis as { BroadcastChannel?: unknown }).BroadcastChannel = FakeBroadcastChannel as unknown;
+});
+afterEach(() => {
+  (globalThis as { BroadcastChannel?: unknown }).BroadcastChannel = undefined;
+});
+
+describe('SessionClient signed-out socket', () => {
+  it('opens the socket while signed-out when signedOutSocketAuth resolves true (web cookie), with credentials', async () => {
+    const c = new SessionClient(makeHost(), { signedOutSocketAuth: () => true });
+    await c.start();
+    expect(ioMock).toHaveBeenCalledTimes(1);
+    expect(lastOpts?.autoConnect).toBe(true);
+    expect(lastOpts?.withCredentials).toBe(true);
+    // No bearer, no native token → handshake presents an empty token, no deviceToken.
+    const authCb = jest.fn();
+    (lastOpts?.auth as (cb: (d: unknown) => void) => void)(authCb);
+    expect(authCb).toHaveBeenCalledWith({ token: '' });
+    c.stop();
+  });
+
+  it('presents the native device token in the handshake when signedOutSocketAuth returns a string', async () => {
+    const c = new SessionClient(makeHost(), { signedOutSocketAuth: () => 'dt-native' });
+    await c.start();
+    expect(lastOpts?.autoConnect).toBe(true);
+    const authCb = jest.fn();
+    (lastOpts?.auth as (cb: (d: unknown) => void) => void)(authCb);
+    expect(authCb).toHaveBeenCalledWith({ token: '', deviceToken: 'dt-native' });
+    c.stop();
+  });
+
+  it('does NOT open the socket while signed-out when signedOutSocketAuth is absent (default)', async () => {
+    const c = new SessionClient(makeHost());
+    await c.start();
+    expect(lastOpts?.autoConnect).toBe(false);
+    c.stop();
+  });
+
+  it('does NOT open the socket while signed-out when signedOutSocketAuth resolves false', async () => {
+    const c = new SessionClient(makeHost(), { signedOutSocketAuth: async () => false });
+    await c.start();
+    expect(lastOpts?.autoConnect).toBe(false);
+    c.stop();
+  });
+
+  it('skips the bearer-authenticated bootstrap when signed-out', async () => {
+    const makeRequest = jest.fn().mockResolvedValue(SYNC(1));
+    const c = new SessionClient(makeHost({ makeRequest }), { signedOutSocketAuth: () => true });
+    await c.start();
+    expect(makeRequest).not.toHaveBeenCalled();
+    c.stop();
+  });
+
+  it('a session_state push while signed-out triggers acquisition exactly once for a burst', async () => {
+    const onSessionAppeared = jest.fn(() => new Promise<void>(() => undefined)); // never resolves (in flight)
+    const c = new SessionClient(makeHost(), { signedOutSocketAuth: () => true, onSessionAppeared });
+    await c.start();
+    fakeSocket.trigger('session_state', STATE(9));
+    fakeSocket.trigger('session_state', STATE(10));
+    await flush();
+    expect(onSessionAppeared).toHaveBeenCalledTimes(1);
+    c.stop();
+  });
+
+  it('does NOT acquire when the pushed signed-out state has zero accounts', async () => {
+    const onSessionAppeared = jest.fn();
+    const c = new SessionClient(makeHost(), { signedOutSocketAuth: () => true, onSessionAppeared });
+    await c.start();
+    fakeSocket.trigger('session_state', STATE(9, []));
+    await flush();
+    expect(onSessionAppeared).not.toHaveBeenCalled();
+    c.stop();
+  });
+
+  it('re-acquires on a LATER push after the prior acquisition settled (no permanent lock)', async () => {
+    const onSessionAppeared = jest.fn(() => Promise.resolve());
+    const c = new SessionClient(makeHost(), { signedOutSocketAuth: () => true, onSessionAppeared });
+    await c.start();
+    fakeSocket.trigger('session_state', STATE(9));
+    await flush();
+    expect(onSessionAppeared).toHaveBeenCalledTimes(1);
+    fakeSocket.trigger('session_state', STATE(10));
+    await flush();
+    expect(onSessionAppeared).toHaveBeenCalledTimes(2);
+    c.stop();
+  });
+
+  it('reconnects the anonymous socket authenticated once a token arrives', async () => {
+    let tokenListener: ((t: string | null) => void) | null = null;
+    let token: string | null = null;
+    const host = makeHost({
+      getAccessToken: () => token,
+      onTokensChanged: (l) => { tokenListener = l; return () => undefined; },
+    });
+    const c = new SessionClient(host, { signedOutSocketAuth: () => true });
+    await c.start();
+    expect(fakeSocket.connected).toBe(true); // anonymous connect
+    const before = fakeSocket.disconnectCalls;
+    token = 'fresh';
+    tokenListener?.('fresh');
+    // Anonymous → authenticated: force a reconnect so the handshake re-runs.
+    expect(fakeSocket.disconnectCalls).toBe(before + 1);
+    expect(fakeSocket.connected).toBe(true);
+    c.stop();
+  });
+});
+
+describe('SessionClient BroadcastChannel wake', () => {
+  const opts = (over: Partial<SessionClientOptions>): SessionClientOptions => ({ signedOutSocketAuth: () => true, ...over });
+
+  it('a local mutation wakes a signed-out sibling to acquire', async () => {
+    const onSessionAppeared = jest.fn(() => Promise.resolve());
+    // Signed-out sibling B listening on the channel.
+    const b = new SessionClient(makeHost(), opts({ onSessionAppeared }));
+    await b.start();
+    // Signed-in tab A commits (switchAccount posts a commit ping).
+    const a = new SessionClient(makeHost({ getAccessToken: () => 'tok-a' }), opts({}));
+    await a.start();
+    await a.switchAccount('a1');
+    await flush();
+    expect(onSessionAppeared).toHaveBeenCalledTimes(1);
+    a.stop();
+    b.stop();
+  });
+
+  it('a local mutation wakes a signed-in sibling to re-sync (bootstrap)', async () => {
+    const bMakeRequest = jest.fn().mockResolvedValue(SYNC(1));
+    const b = new SessionClient(makeHost({ makeRequest: bMakeRequest, getAccessToken: () => 'tok-b' }), opts({}));
+    await b.start();
+    bMakeRequest.mockClear();
+    const a = new SessionClient(makeHost({ getAccessToken: () => 'tok-a' }), opts({}));
+    await a.start();
+    await a.addCurrentAccount();
+    await flush();
+    expect(bMakeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    a.stop();
+    b.stop();
+  });
+
+  it('does not deliver a commit ping back to the posting tab (no self-loop)', async () => {
+    // A signed-out tab that commits locally must not re-trigger its OWN acquisition.
+    const onSessionAppeared = jest.fn();
+    const a = new SessionClient(makeHost(), opts({ onSessionAppeared }));
+    await a.start();
+    await a.addCurrentAccount();
+    await flush();
+    expect(onSessionAppeared).not.toHaveBeenCalled();
+    a.stop();
+  });
+
+  it('is a no-op on platforms without BroadcastChannel (native)', async () => {
+    (globalThis as { BroadcastChannel?: unknown }).BroadcastChannel = undefined;
+    const c = new SessionClient(makeHost({ getAccessToken: () => 'tok' }), { });
+    await c.start();
+    // Mutations must not throw when BroadcastChannel is absent.
+    await expect(c.switchAccount('a1')).resolves.toBeUndefined();
+    c.stop();
+  });
+});