@oxyhq/core 10.1.3 → 10.1.5

package/dist/types/session/SessionClient.d.ts

@@ -129,6 +129,23 @@ export declare class SessionClient {
     start(): Promise<void>;
     stop(): void;
     private connectSocket;
+    /**
+     * Handle the token-free `session_accounts_changed` signal (room `user:<userId>`).
+     *
+     * Unlike `session_state` (device-scoped, carries the new state to APPLY), this
+     * reaches ALL of a user's connected sockets across their devices/origins and is
+     * a pure SIGNAL: it carries no token, no secret, and no account bodies. The only
+     * trustworthy bit is "something changed for this user", so — matching the
+     * `session_state` contract's guidance — we re-fetch our OWN authoritative device
+     * state (`bootstrap` → `GET /session/device/state`) and let the existing
+     * `applyState` revision guard reconcile it. We never trust any field on the event
+     * beyond routing it to the current user.
+     *
+     * The refetch is a private (bearer) call: the socket only joins `user:<userId>`
+     * when authenticated, so a signed-out client never receives this — but we guard
+     * the bearer anyway so a race at sign-out can't 401.
+     */
+    private onSessionAccountsChanged;
     /**
      * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
      * commits an account switch / sign-out posts a wake ping; on receipt an

package/dist/types/session/accountDialogController.d.ts

@@ -28,6 +28,7 @@
 import type { OxyServices } from '../OxyServices';
 import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { SessionClient } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
 import { type SwitchableAccount } from './accountProjection';
 /** The dialog's top-level view. */
 export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add';
@@ -103,8 +104,20 @@ export interface AccountDialogControllerOptions {
      * `location.origin` normalization in {@link openPasswordAtOxyAuth}.
      */
     authRedirectUri?: string | null;
-    /** QR device-flow poll interval in ms (default 3000). */
+    /**
+     * QR device-flow FALLBACK poll interval in ms (default 12000). The primary
+     * approval signal is the `/auth-session` socket's `auth_update` event (instant);
+     * this slow poll is only the safety net for when the socket can't connect.
+     */
     pollIntervalMs?: number;
+    /**
+     * Statically-injected `socket.io-client` factory (its `io` export), same as
+     * {@link SessionClient}'s. When provided, the QR flow subscribes to the
+     * `/auth-session` namespace for an INSTANT `auth_update` wake instead of relying
+     * on the slow fallback poll. Absent on web builds without a bundled `io` and in
+     * headless/core usage → the controller silently degrades to poll-only.
+     */
+    socketFactory?: SocketIOFactory;
     /**
      * Optional URL opener. When provided, `openPasswordAtOxyAuth` invokes it with
      * the built URL in addition to returning it (web: `location.assign`; native:
@@ -135,6 +148,7 @@ export declare class AccountDialogController {
     private readonly pollIntervalMs;
     private readonly openUrl?;
     private readonly canOpenApp?;
+    private readonly socketFactory?;
     private readonly listeners;
     private view;
     private graph;
@@ -146,6 +160,18 @@ export declare class AccountDialogController {
     /** The secret device-flow token of the active QR flow (never surfaced). */
     private signInToken;
     private pollTimer;
+    /**
+     * The `/auth-session` socket for the active QR flow, or null (poll-only). Its
+     * `auth_update` event wakes {@link pollOnce} instantly instead of waiting for the
+     * slow fallback timer.
+     */
+    private authSessionSocket;
+    /**
+     * Guards {@link pollOnce} against re-entrancy: the fallback timer and a socket
+     * `auth_update` wake can fire together — without this both could claim the
+     * single-use token concurrently.
+     */
+    private pollInFlight;
     private unsubscribeSession;
     private unsubscribeTokens;
     /** Last-observed SDK auth readiness (a planted bearer). Drives the fetch edge. */
@@ -249,7 +275,7 @@ export declare class AccountDialogController {
      * probe/open failure is logged and swallowed — the QR/polling fallback remains.
      */
     private maybeOpenCommons;
-    /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
+    /** Tear down the active sign-in device flow (timers + socket + token) and reset to idle. */
     cancelSignIn(): void;
     /**
      * Build (and, when an `openUrl` handler was supplied, open) the auth.oxy.so
@@ -271,6 +297,13 @@ export declare class AccountDialogController {
         redirectUri?: string;
     }): Promise<string>;
     private scheduleNextPoll;
+    /**
+     * Run one status check + (on approval) claim. Triggered by the fallback timer
+     * AND by the `/auth-session` socket's `auth_update` wake, so it is guarded
+     * against concurrent entry: whichever fires first claims the single-use token;
+     * the other no-ops. The `auth_update` payload is never trusted — this always
+     * re-checks the authoritative status via `pollCommonsSignIn`.
+     */
     private pollOnce;
     private claimAndComplete;
     /**
@@ -286,6 +319,21 @@ export declare class AccountDialogController {
     private commitAuthorizedSession;
     private failSignIn;
     private clearPollTimer;
+    /**
+     * Subscribe the active QR flow to the `/auth-session` namespace so the API's
+     * `auth_update` event wakes {@link pollOnce} the instant the approval lands.
+     *
+     * The join is keyed by the secret `sessionToken` (the server's `auth:<token>`
+     * room, joined by emitting `join`) and re-issued on every (re)connect so it
+     * survives socket drops. `auth_update` is treated as a pure SIGNAL — the payload
+     * is never trusted; `pollOnce` re-checks the authoritative status and claims.
+     *
+     * No-op (poll-only) when no `socketFactory` was injected (web without a bundled
+     * `io`, headless/core usage, tests). The namespace needs no auth.
+     */
+    private openAuthSessionSocket;
+    /** Tear down the `/auth-session` socket, if any. Idempotent. */
+    private closeAuthSessionSocket;
     private setSignIn;
     private computeSnapshot;
     /** Recompute the snapshot and notify subscribers. */

package/dist/types/session/socketLoader.d.ts

@@ -2,6 +2,8 @@ export interface MinimalSocket {
     connected: boolean;
     on(event: string, handler: (...args: unknown[]) => void): void;
     off(event: string, handler?: (...args: unknown[]) => void): void;
+    /** Client→server emit (e.g. joining the `/auth-session` room for a QR flow). */
+    emit(event: string, ...args: unknown[]): void;
     connect(): void;
     disconnect(): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "10.1.3",
+  "version": "10.1.5",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.14.0",
+    "@oxyhq/contracts": "^0.14.1",
     "@oxyhq/protocol": "^0.1.5",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/session/SessionClient.ts

@@ -2,6 +2,8 @@ import {
   deviceSessionStateSchema,
   deviceSessionSyncSchema,
   safeParseContract,
+  SESSION_ACCOUNTS_CHANGED_EVENT,
+  sessionAccountsChangedEventSchema,
   type DeviceSessionState,
 } from '@oxyhq/contracts';
 import { logger } from '../utils/loggerUtils';
@@ -407,6 +409,9 @@ export class SessionClient {
         });
       }
     });
+    socket.on(SESSION_ACCOUNTS_CHANGED_EVENT, (payload: unknown) => {
+      this.onSessionAccountsChanged(payload);
+    });
     this.socket = socket;
     // (Re)bind app-facing server-event subscriptions on the fresh socket.
     this.boundServerEvents.clear();
@@ -415,6 +420,37 @@ export class SessionClient {
     }
   }
 
+  /**
+   * Handle the token-free `session_accounts_changed` signal (room `user:<userId>`).
+   *
+   * Unlike `session_state` (device-scoped, carries the new state to APPLY), this
+   * reaches ALL of a user's connected sockets across their devices/origins and is
+   * a pure SIGNAL: it carries no token, no secret, and no account bodies. The only
+   * trustworthy bit is "something changed for this user", so — matching the
+   * `session_state` contract's guidance — we re-fetch our OWN authoritative device
+   * state (`bootstrap` → `GET /session/device/state`) and let the existing
+   * `applyState` revision guard reconcile it. We never trust any field on the event
+   * beyond routing it to the current user.
+   *
+   * The refetch is a private (bearer) call: the socket only joins `user:<userId>`
+   * when authenticated, so a signed-out client never receives this — but we guard
+   * the bearer anyway so a race at sign-out can't 401.
+   */
+  private onSessionAccountsChanged(payload: unknown): void {
+    const event = safeParseContract(sessionAccountsChangedEventSchema, payload);
+    if (!event) {
+      logger.warn('[SessionClient] discarded invalid session_accounts_changed', { component: 'SessionClient' });
+      return;
+    }
+    // The socket is in `user:<activeUserId>` for the planted bearer, so this should
+    // always be the current user; ignore a foreign id defensively (out-of-band relay).
+    if (event.userId !== this.host.getCurrentAccountId()) return;
+    if (!this.host.getAccessToken()) return;
+    void this.bootstrap().catch((error) => {
+      logger.warn('[SessionClient] session_accounts_changed refetch failed', { component: 'SessionClient' }, error);
+    });
+  }
+
   /**
    * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
    * commits an account switch / sign-out posts a wake ping; on receipt an

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

@@ -8,6 +8,7 @@ class FakeSocket implements MinimalSocket {
   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)); }
+  emit(_event: string, ..._args: unknown[]) { /* client→server emit, unused here */ }
   connect() { this.connected = true; }
   disconnect() { this.connected = false; }
   emitServer(event: string, payload: unknown) { for (const h of this.handlers.get(event) ?? []) h(payload); }

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

@@ -132,6 +132,42 @@ describe('SessionClient socket', () => {
     expect(fakeSocket.connected).toBe(false);
   });
 
+  it('session_accounts_changed for the current user refetches device state (GET /session/device/state)', 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_accounts_changed', { userId: 'a1', revision: 5, reason: 'add' });
+    await Promise.resolve();
+    expect(makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    c.stop();
+  });
+
+  it('session_accounts_changed for a DIFFERENT user is ignored (no refetch)', 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_accounts_changed', { userId: 'someone-else', revision: 5, reason: 'switch' });
+    await Promise.resolve();
+    expect(makeRequest).not.toHaveBeenCalled();
+    c.stop();
+  });
+
+  it('session_accounts_changed drops a malformed payload without refetching', 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_accounts_changed', { userId: 'a1', reason: 'not-a-real-reason' });
+    await Promise.resolve();
+    expect(makeRequest).not.toHaveBeenCalled();
+    c.stop();
+  });
+
   it('a socket-pushed empty state fires onUnauthenticated with the PUSH origin (bug #4)', async () => {
     const onUnauthenticated = jest.fn();
     const c = new SessionClient(makeHost(), { onUnauthenticated });

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

@@ -20,6 +20,7 @@ class FakeSocket implements MinimalSocket {
   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)); }
+  emit(_event: string, ..._args: unknown[]) { /* no-op: device socket never emits */ }
   connect() { this.connected = true; }
   disconnect() { this.connected = false; }
 }

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

@@ -4,6 +4,7 @@ import type { User } from '../../models/interfaces';
 import type { SessionLoginResponse, MinimalUserData } from '../../models/session';
 import type { AccountNode } from '../../mixins/OxyServices.accounts';
 import { SessionClient, type SessionClientHost } from '../SessionClient';
+import type { MinimalSocket, SocketIOFactory } from '../socketLoader';
 import { logger } from '../../utils/loggerUtils';
 import {
   AccountDialogController,
@@ -68,6 +69,7 @@ function graphNode(id: string, over: Partial<AccountNode> = {}): AccountNode {
 
 interface OxyMock {
   getAccessToken: jest.Mock;
+  getBaseURL: jest.Mock;
   onTokensChanged: jest.Mock;
   listAccounts: jest.Mock;
   getUsersByIds: jest.Mock;
@@ -91,6 +93,7 @@ function makeOxy(): OxyMock {
   let currentToken: string | null = 'access-token';
   return {
     getAccessToken: jest.fn(() => currentToken),
+    getBaseURL: jest.fn(() => 'http://test.invalid'),
     onTokensChanged: jest.fn((listener: (token: string | null) => void) => {
       tokenListeners.add(listener);
       return () => tokenListeners.delete(listener);
@@ -727,6 +730,110 @@ describe('AccountDialogController — openPasswordAtOxyAuth', () => {
   });
 });
 
+describe('AccountDialogController — /auth-session socket (instant QR wake)', () => {
+  type Handler = (...args: unknown[]) => void;
+  class FakeAuthSocket implements MinimalSocket {
+    connected = false;
+    disconnected = false;
+    handlers = new Map<string, Handler[]>();
+    emitted: Array<{ event: string; args: unknown[] }> = [];
+    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)); }
+    emit(event: string, ...args: unknown[]) { this.emitted.push({ event, args }); }
+    connect() { this.connected = true; }
+    disconnect() { this.connected = false; this.disconnected = true; }
+    /** Simulate a server→client push on this socket. */
+    server(event: string, payload?: unknown) { for (const h of this.handlers.get(event) ?? []) h(payload); }
+  }
+
+  const START_HANDLE = {
+    sessionToken: 'secret-tok',
+    authorizeCode: 'AUTH-CODE',
+    qrPayload: 'oxycommons://approve?v=1&code=AUTH-CODE',
+    expiresAt: Date.now() + 600_000,
+    status: 'pending' as const,
+  };
+
+  function makeSocketHarness(): { controller: AccountDialogController; oxy: OxyMock; created: () => FakeAuthSocket | null; factory: jest.Mock; commitSession: jest.Mock } {
+    const oxy = makeOxy();
+    oxy.startCommonsSignIn.mockResolvedValue(START_HANDLE);
+    let socket: FakeAuthSocket | null = null;
+    const factory = jest.fn((_uri: string, _opts?: Record<string, unknown>): MinimalSocket => {
+      socket = new FakeAuthSocket();
+      socket.connected = true; // real io autoConnect resolves before we inspect
+      return socket;
+    });
+    const commitSession = jest.fn().mockResolvedValue(undefined);
+    const controller = new AccountDialogController({
+      oxyServices: oxy as unknown as OxyServices,
+      sessionClient: new TestSessionClient(host()),
+      clientId: 'oxy_dk_test',
+      commitSession,
+      socketFactory: factory as unknown as SocketIOFactory,
+    });
+    return { controller, oxy, created: () => socket, factory, commitSession };
+  }
+
+  it('connects to /auth-session, joins the flow room, and wakes the claim on auth_update — no timer advance', async () => {
+    const { controller, oxy, created, factory, commitSession } = makeSocketHarness();
+    oxy.pollCommonsSignIn.mockResolvedValue({ authorized: true, sessionId: 'sess-1', status: 'authorized' });
+    oxy.claimSessionByToken.mockResolvedValue({
+      accessToken: 'access-1', sessionId: 'sess-1', deviceId: 'device-1', expiresAt: '2030-01-01T00:00:00Z', user: user('a1'),
+    });
+
+    await controller.showQr();
+
+    expect(factory).toHaveBeenCalledWith('http://test.invalid/auth-session', expect.any(Object));
+    const sock = created();
+    if (!sock) throw new Error('socket not created');
+    expect(sock.emitted).toContainEqual({ event: 'join', args: ['secret-tok'] });
+
+    // The server pushes auth_update → immediate status check + claim, without any poll timer firing.
+    sock.server('auth_update', { status: 'authorized', sessionId: 'sess-1' });
+    await flush();
+
+    expect(oxy.pollCommonsSignIn).toHaveBeenCalledWith('secret-tok');
+    expect(oxy.claimSessionByToken).toHaveBeenCalledWith('secret-tok');
+    expect(commitSession).toHaveBeenCalled();
+    expect(controller.getSnapshot().view).toBe('accounts');
+    expect(sock.disconnected).toBe(true); // torn down on completion
+  });
+
+  it('re-joins the room on reconnect (connect event) and tears the socket down on cancelSignIn', async () => {
+    const { controller, oxy, created } = makeSocketHarness();
+    oxy.pollCommonsSignIn.mockResolvedValue({ authorized: false, status: 'pending' });
+
+    await controller.showQr();
+    const sock = created();
+    if (!sock) throw new Error('socket not created');
+    expect(sock.emitted.filter((e) => e.event === 'join')).toHaveLength(1);
+
+    // A reconnect fires `connect` again → the join is re-issued so it survives drops.
+    sock.server('connect');
+    expect(sock.emitted.filter((e) => e.event === 'join')).toHaveLength(2);
+
+    controller.cancelSignIn();
+    expect(sock.disconnected).toBe(true);
+  });
+
+  it('a stale auth_update after the flow was cancelled does not re-poll', async () => {
+    const { controller, oxy, created } = makeSocketHarness();
+    oxy.pollCommonsSignIn.mockResolvedValue({ authorized: false, status: 'pending' });
+
+    await controller.showQr();
+    const sock = created();
+    if (!sock) throw new Error('socket not created');
+    oxy.pollCommonsSignIn.mockClear();
+
+    controller.cancelSignIn();
+    // Even if a late auth_update slips through on the (now-detached) socket, the
+    // superseded-token guard drops it.
+    sock.server('auth_update', { status: 'authorized' });
+    await flush();
+    expect(oxy.pollCommonsSignIn).not.toHaveBeenCalled();
+  });
+});
+
 describe('AccountDialogController — lifecycle', () => {
   it('destroy unsubscribes so later device-state changes do not notify', async () => {
     const { controller, oxy, sc } = makeHarness();