@oxyhq/core 10.1.4 → 10.2.0

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();

package/src/session/accountDialogController.ts

@@ -39,6 +39,7 @@ import {
   persistOAuthHandshake,
 } from '../utils/oauthPkce';
 import type { SessionClient } from './SessionClient';
+import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 import {
   projectSwitchableAccounts,
   switchableAccountIds,
@@ -124,8 +125,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:
@@ -144,7 +157,16 @@ export interface AccountDialogControllerOptions {
   canOpenApp?: (url: string) => Promise<boolean>;
 }
 
-const DEFAULT_POLL_INTERVAL_MS = 3000;
+/**
+ * Slow FALLBACK poll cadence for the QR flow. The `/auth-session` socket delivers
+ * the approval instantly via `auth_update`; this poll only covers the case where
+ * the socket can't connect, so it is deliberately slow (was 3000 when polling was
+ * the sole mechanism).
+ */
+const DEFAULT_POLL_INTERVAL_MS = 12000;
+
+/** Socket.IO namespace the API emits QR-flow approval (`auth_update`) events on. */
+const AUTH_SESSION_NAMESPACE = '/auth-session';
 
 /**
  * Commons's custom URL scheme. Probed via the injected `canOpenApp` to detect an
@@ -179,6 +201,7 @@ export class AccountDialogController {
   private readonly pollIntervalMs: number;
   private readonly openUrl?: (url: string) => void;
   private readonly canOpenApp?: (url: string) => Promise<boolean>;
+  private readonly socketFactory?: SocketIOFactory;
 
   private readonly listeners = new Set<SnapshotListener>();
 
@@ -195,6 +218,18 @@ export class AccountDialogController {
   /** The secret device-flow token of the active QR flow (never surfaced). */
   private signInToken: string | null = null;
   private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * 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: MinimalSocket | null = null;
+  /**
+   * 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 = false;
 
   // --- Store plumbing ---
   private unsubscribeSession: (() => void) | null = null;
@@ -217,6 +252,7 @@ export class AccountDialogController {
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.openUrl = options.openUrl;
     this.canOpenApp = options.canOpenApp;
+    this.socketFactory = options.socketFactory;
     this.snapshot = this.computeSnapshot();
   }
 
@@ -289,6 +325,8 @@ export class AccountDialogController {
       this.unsubscribeTokens = null;
     }
     this.clearPollTimer();
+    this.closeAuthSessionSocket();
+    this.signInToken = null;
     this.listeners.clear();
   }
 
@@ -568,6 +606,10 @@ export class AccountDialogController {
         expiresAt: handle.expiresAt,
         error: null,
       });
+      // Primary path: an instant `auth_update` wake over the `/auth-session`
+      // socket. The poll below is only the fallback for when the socket can't
+      // connect, so it now runs at the slow fallback cadence.
+      this.openAuthSessionSocket(handle.sessionToken);
       this.scheduleNextPoll(handle.sessionToken);
       // Same-device convenience: if Commons is installed (native only — `canOpenApp`
       // is undefined/false on web), deep-link straight into its approve screen with
@@ -600,9 +642,10 @@ export class AccountDialogController {
     }
   }
 
-  /** 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 {
     this.clearPollTimer();
+    this.closeAuthSessionSocket();
     this.signInToken = null;
     if (this.signIn !== IDLE_SIGN_IN) {
       this.setSignIn(IDLE_SIGN_IN);
@@ -664,36 +707,48 @@ export class AccountDialogController {
     }, this.pollIntervalMs);
   }
 
+  /**
+   * 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 async pollOnce(sessionToken: string): Promise<void> {
-    // A superseded / cancelled flow must not act.
-    if (this.signInToken !== sessionToken) return;
-    const expiresAt = this.signIn.expiresAt;
-    if (typeof expiresAt === 'number' && Date.now() > expiresAt) {
-      this.failSignIn('Session expired. Please try again.');
-      return;
-    }
+    // A superseded / cancelled flow must not act; a poll already running owns the claim.
+    if (this.signInToken !== sessionToken || this.pollInFlight) return;
+    this.pollInFlight = true;
     try {
-      const status = await this.oxyServices.pollCommonsSignIn(sessionToken);
-      if (this.signInToken !== sessionToken) return; // cancelled mid-request
-      if (status.authorized && status.sessionId) {
-        this.clearPollTimer();
-        await this.claimAndComplete(status.sessionId, sessionToken);
+      const expiresAt = this.signIn.expiresAt;
+      if (typeof expiresAt === 'number' && Date.now() > expiresAt) {
+        this.failSignIn('Session expired. Please try again.');
         return;
       }
-      if (status.status === 'cancelled') {
-        this.failSignIn('Authorization was denied.');
-        return;
+      try {
+        const status = await this.oxyServices.pollCommonsSignIn(sessionToken);
+        if (this.signInToken !== sessionToken) return; // cancelled mid-request
+        if (status.authorized && status.sessionId) {
+          this.clearPollTimer();
+          await this.claimAndComplete(status.sessionId, sessionToken);
+          return;
+        }
+        if (status.status === 'cancelled') {
+          this.failSignIn('Authorization was denied.');
+          return;
+        }
+        if (status.status === 'expired') {
+          this.failSignIn('Session expired. Please try again.');
+          return;
+        }
+      } catch (error) {
+        // Transient poll error — the next tick retries. Logged, never thrown.
+        logger.debug('[AccountDialogController] poll error (will retry)', { component: 'AccountDialogController' }, error);
       }
-      if (status.status === 'expired') {
-        this.failSignIn('Session expired. Please try again.');
-        return;
+      if (this.signInToken === sessionToken) {
+        this.scheduleNextPoll(sessionToken);
       }
-    } catch (error) {
-      // Transient poll error — the next tick retries. Logged, never thrown.
-      logger.debug('[AccountDialogController] poll error (will retry)', { component: 'AccountDialogController' }, error);
-    }
-    if (this.signInToken === sessionToken) {
-      this.scheduleNextPoll(sessionToken);
+    } finally {
+      this.pollInFlight = false;
     }
   }
 
@@ -754,6 +809,7 @@ export class AccountDialogController {
     await this.commitAuthorizedSession(session, user);
     this.signInToken = null;
     this.clearPollTimer();
+    this.closeAuthSessionSocket();
     this.signIn = IDLE_SIGN_IN;
     this.view = 'accounts';
     this.emit();
@@ -779,6 +835,7 @@ export class AccountDialogController {
 
   private failSignIn(message: string): void {
     this.clearPollTimer();
+    this.closeAuthSessionSocket();
     this.signInToken = null;
     this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: message });
   }
@@ -790,6 +847,72 @@ export class AccountDialogController {
     }
   }
 
+  // =========================================================================
+  // /auth-session socket (instant QR approval wake — replaces 3s polling)
+  // =========================================================================
+
+  /**
+   * 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(sessionToken: string): void {
+    this.closeAuthSessionSocket();
+    if (!this.socketFactory) return;
+    let socket: MinimalSocket;
+    try {
+      socket = this.socketFactory(`${this.oxyServices.getBaseURL()}${AUTH_SESSION_NAMESPACE}`, {
+        transports: ['websocket'],
+        autoConnect: true,
+        reconnection: true,
+        reconnectionAttempts: Number.POSITIVE_INFINITY,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 10000,
+      });
+    } catch (error) {
+      // Socket unavailable — the fallback poll still completes the flow.
+      logger.debug('[AccountDialogController] auth-session socket create failed (poll fallback)', { component: 'AccountDialogController' }, error);
+      return;
+    }
+    const join = (): void => {
+      if (this.signInToken !== sessionToken) return;
+      try {
+        socket.emit('join', sessionToken);
+      } catch (error) {
+        logger.debug('[AccountDialogController] auth-session join failed', { component: 'AccountDialogController' }, error);
+      }
+    };
+    socket.on('connect', join);
+    if (socket.connected) join();
+    socket.on('auth_update', () => {
+      if (this.signInToken !== sessionToken) return;
+      // Pure wake signal — re-check the authoritative status + claim the poll would have.
+      void this.pollOnce(sessionToken);
+    });
+    this.authSessionSocket = socket;
+  }
+
+  /** Tear down the `/auth-session` socket, if any. Idempotent. */
+  private closeAuthSessionSocket(): void {
+    const socket = this.authSessionSocket;
+    if (!socket) return;
+    this.authSessionSocket = null;
+    try {
+      socket.off('auth_update');
+      socket.off('connect');
+      socket.disconnect();
+    } catch (error) {
+      logger.debug('[AccountDialogController] auth-session socket close failed', { component: 'AccountDialogController' }, error);
+    }
+  }
+
   // =========================================================================
   // Snapshot plumbing
   // =========================================================================

package/src/session/socketLoader.ts

@@ -4,6 +4,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;
 }