@oxyhq/core 10.1.4 → 10.2.0

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.4",
+  "version": "10.2.0",
   "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/server/__tests__/rateLimit.test.ts

@@ -26,6 +26,8 @@ interface RateLimitTestRequest extends Request {
   observedKey?: string;
 }
 
+const HEX24 = /^[0-9a-f]{24}$/;
+
 function makeOxy(authHandler: RequestHandler): OxyServices {
   return {
     auth: jest.fn(() => authHandler),
@@ -33,17 +35,37 @@ function makeOxy(authHandler: RequestHandler): OxyServices {
 }
 
 function makeRequest(overrides: Partial<RateLimitTestRequest> = {}): RateLimitTestRequest {
+  const ip = overrides.ip ?? '203.0.113.9';
   return {
     method: 'GET',
     path: '/api/test',
-    ip: '203.0.113.9',
-    socket: { remoteAddress: '203.0.113.9' },
+    ip,
+    socket: { remoteAddress: ip },
     ...overrides,
   } as RateLimitTestRequest;
 }
 
+/** Run the anonymous limiter for a bare IP and return the store key it produced. */
+function keyForIp(ip: string): string {
+  const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => next());
+  const req = makeRequest({ ip });
+  createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+  if (typeof req.observedKey !== 'string') {
+    throw new Error('key generator did not run');
+  }
+  return req.observedKey;
+}
+
 describe('@oxyhq/core/server rate limiter', () => {
+  const originalEnv = {
+    IP_HASH_SALT: process.env.IP_HASH_SALT,
+    DEVICE_ID_SALT: process.env.DEVICE_ID_SALT,
+  };
+
   beforeEach(() => {
+    // Isolate salt resolution from any ambient env so key assertions are deterministic.
+    delete process.env.IP_HASH_SALT;
+    delete process.env.DEVICE_ID_SALT;
     rateLimitMock.mockImplementation((options: CapturedRateLimitOptions) => {
       return (req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
         req.observedMax = options.max(req);
@@ -55,6 +77,10 @@ describe('@oxyhq/core/server rate limiter', () => {
 
   afterEach(() => {
     jest.clearAllMocks();
+    if (originalEnv.IP_HASH_SALT === undefined) delete process.env.IP_HASH_SALT;
+    else process.env.IP_HASH_SALT = originalEnv.IP_HASH_SALT;
+    if (originalEnv.DEVICE_ID_SALT === undefined) delete process.env.DEVICE_ID_SALT;
+    else process.env.DEVICE_ID_SALT = originalEnv.DEVICE_ID_SALT;
   });
 
   it('does not trust locally decoded non-session JWT identities for quota or bucket keys', () => {
@@ -73,7 +99,9 @@ describe('@oxyhq/core/server rate limiter', () => {
     );
 
     expect(req.observedMax).toBe(600);
-    expect(req.observedKey).toBe('203.0.113.9');
+    // Anonymous callers are bucketed by a hashed key, NEVER the raw IP.
+    expect(req.observedKey).toMatch(HEX24);
+    expect(req.observedKey).not.toContain('203.0.113.9');
     expect(next).toHaveBeenCalledTimes(1);
   });
 
@@ -93,6 +121,7 @@ describe('@oxyhq/core/server rate limiter', () => {
     );
 
     expect(req.observedMax).toBe(5000);
+    // Authenticated identities are keyed by the user id verbatim — NOT hashed.
     expect(req.observedKey).toBe('user:validated-user');
   });
 
@@ -110,7 +139,72 @@ describe('@oxyhq/core/server rate limiter', () => {
     );
 
     expect(req.observedMax).toBe(600);
-    expect(req.observedKey).toBe('203.0.113.9');
+    expect(req.observedKey).toMatch(HEX24);
+    expect(req.observedKey).not.toContain('203.0.113.9');
     expect(next).toHaveBeenCalledTimes(1);
   });
+
+  describe('anonymous key hashing', () => {
+    it('produces a deterministic 24-hex key that never contains the raw IP', () => {
+      const first = keyForIp('203.0.113.9');
+      const second = keyForIp('203.0.113.9');
+
+      expect(first).toMatch(HEX24);
+      expect(first).toBe(second);
+      expect(first).not.toContain('203.0.113.9');
+    });
+
+    it('produces different keys for different IPv4 addresses', () => {
+      expect(keyForIp('203.0.113.9')).not.toBe(keyForIp('198.51.100.7'));
+    });
+
+    it('buckets IPv6 addresses in the same /56 to the same key', () => {
+      // 2001:db8:abcd:ee11 and 2001:db8:abcd:eeff share the /56 prefix (top byte of
+      // the 4th hextet is 0xee for both); the differing bits are host bits.
+      const a = keyForIp('2001:db8:abcd:ee11::1');
+      const b = keyForIp('2001:db8:abcd:eeff::9999');
+
+      expect(a).toMatch(HEX24);
+      expect(a).toBe(b);
+    });
+
+    it('produces different keys for IPv6 addresses in different /56 prefixes', () => {
+      const sameFiftySix = keyForIp('2001:db8:abcd:ee11::1');
+      const otherFiftySix = keyForIp('2001:db8:abcd:ff11::1');
+
+      expect(sameFiftySix).not.toBe(otherFiftySix);
+    });
+
+    it('salts the hash with IP_HASH_SALT so keys are not portable across salts', () => {
+      const unsalted = keyForIp('203.0.113.9');
+
+      process.env.IP_HASH_SALT = 'salt-a';
+      const saltedA = keyForIp('203.0.113.9');
+
+      process.env.IP_HASH_SALT = 'salt-b';
+      const saltedB = keyForIp('203.0.113.9');
+
+      expect(saltedA).toMatch(HEX24);
+      expect(saltedA).not.toBe(unsalted);
+      expect(saltedB).not.toBe(saltedA);
+    });
+
+    it('prefers IP_HASH_SALT over DEVICE_ID_SALT', () => {
+      process.env.DEVICE_ID_SALT = 'device-salt';
+      const deviceOnly = keyForIp('203.0.113.9');
+
+      process.env.IP_HASH_SALT = 'ip-salt';
+      const ipPreferred = keyForIp('203.0.113.9');
+
+      expect(ipPreferred).not.toBe(deviceOnly);
+    });
+
+    it('falls back to the literal "unknown" key when no IP is resolvable', () => {
+      const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => next());
+      const req = makeRequest({ ip: undefined, socket: {} as Request['socket'] });
+      createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+      expect(req.observedKey).toBe('unknown');
+    });
+  });
 });

package/src/server/rateLimit.ts

@@ -1,3 +1,5 @@
+import { createHmac } from 'node:crypto';
+import { isIPv4, isIPv6 } from 'node:net';
 import type { Request, RequestHandler } from 'express';
 import rateLimit, { type Store } from 'express-rate-limit';
 import type { OxyServices } from '../OxyServices';
@@ -99,9 +101,103 @@ function isBuiltInExempt(req: Request): boolean {
   );
 }
 
-/** IPv6-safe IP key generator (replaces colons to avoid Redis namespace issues). */
-function ipKeyGenerator(ip: string): string {
-  return ip.replace(/:/g, '_');
+/**
+ * Anonymous rate-limit keys must be PRIVACY-PRESERVING: the raw client IP must
+ * never reach a store at rest (in-memory or Redis). We therefore HMAC-hash the
+ * IP into a short, transient-only bucket key. Two IPv6-specific concerns shape
+ * the pre-hash normalization:
+ *
+ *  - IPv6 hosts are typically handed an entire /64 (often a /56), so a single
+ *    host can rotate through an enormous address space and evade a per-address
+ *    limit. We bucket IPv6 to its /56 prefix BEFORE hashing.
+ *  - express-rate-limit only exposes an `ipKeyGenerator` /56 helper from v8
+ *    onwards; `@oxyhq/core` pins v7 (peer `^7.0.0`), so the masking is
+ *    implemented here rather than pulling a major-version bump of a
+ *    security-critical dependency (and its rate-limit-redis compatibility) into
+ *    an unrelated privacy change. This mirrors `packages/api/src/utils/ipKey.ts`.
+ */
+const IPV6_SUBNET_BITS = 56;
+
+/** Expand an IPv6 literal (handling `::` and embedded IPv4) to 8 numeric hextets, or null if unparseable. */
+function ipv6Hextets(ip: string): number[] | null {
+  let addr = ip;
+  const zone = addr.indexOf('%');
+  if (zone !== -1) {
+    addr = addr.slice(0, zone);
+  }
+
+  // Embedded IPv4 tail (e.g. `::ffff:203.0.113.7`) → fold the dotted quad into two hextets.
+  const lastColon = addr.lastIndexOf(':');
+  if (lastColon !== -1 && addr.slice(lastColon + 1).includes('.')) {
+    const v4 = addr.slice(lastColon + 1);
+    if (!isIPv4(v4)) {
+      return null;
+    }
+    const octets = v4.split('.').map((part) => Number.parseInt(part, 10));
+    const high = ((octets[0] << 8) | octets[1]).toString(16);
+    const low = ((octets[2] << 8) | octets[3]).toString(16);
+    addr = `${addr.slice(0, lastColon + 1)}${high}:${low}`;
+  }
+
+  const halves = addr.split('::');
+  if (halves.length > 2) {
+    return null;
+  }
+  const head = halves[0] ? halves[0].split(':') : [];
+  const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+  let groups: string[];
+  if (halves.length === 1) {
+    groups = head;
+  } else {
+    const missing = 8 - (head.length + tail.length);
+    if (missing < 0) {
+      return null;
+    }
+    groups = [...head, ...new Array(missing).fill('0'), ...tail];
+  }
+  if (groups.length !== 8) {
+    return null;
+  }
+  const hextets = groups.map((group) => Number.parseInt(group || '0', 16));
+  if (hextets.some((value) => Number.isNaN(value) || value < 0 || value > 0xffff)) {
+    return null;
+  }
+  return hextets;
+}
+
+/** Mask an IPv6 address to its /{bits} prefix, returned as a canonical hex string. */
+function maskIPv6(ip: string, bits: number): string {
+  const hextets = ipv6Hextets(ip);
+  if (!hextets) {
+    return ip;
+  }
+  const masked = hextets.map((hextet, index) => {
+    const groupStart = index * 16;
+    if (groupStart >= bits) {
+      return 0;
+    }
+    const keepBits = Math.min(16, bits - groupStart);
+    const mask = keepBits >= 16 ? 0xffff : (0xffff << (16 - keepBits)) & 0xffff;
+    return hextet & mask;
+  });
+  return `${masked.map((hextet) => hextet.toString(16)).join(':')}/${bits}`;
+}
+
+/**
+ * Hash a client IP into a privacy-preserving bucket key. IPv6 is bucketed to its
+ * /56 prefix first (so a single v6 host can't rotate through its allocation to
+ * mint fresh keys), then HMAC'd with the server-side salt. The salt is resolved
+ * at CALL time (`IP_HASH_SALT`, else `DEVICE_ID_SALT`, else empty) — an empty
+ * salt still hashes, which beats storing a raw IP; backends SHOULD set one of
+ * those envs. The `rl|` namespace ensures a rate-limit key can never collide
+ * with, or be correlated against, a deviceId derivation that reuses the same
+ * salt. The result is a short hex digest with no colons, so it is Redis-safe.
+ */
+function hashAnonymousIp(ip: string): string {
+  const normalized =
+    isIPv6(ip) && !ip.startsWith('::ffff:') ? maskIPv6(ip, IPV6_SUBNET_BITS) : ip;
+  const salt = process.env.IP_HASH_SALT || process.env.DEVICE_ID_SALT || '';
+  return createHmac('sha256', salt).update(`rl|${normalized}`).digest('hex').slice(0, 24);
 }
 
 /**
@@ -132,14 +228,17 @@ function resolveTrustedAuthenticatedKey(req: OxyAuthedRequest): string | null {
   return null;
 }
 
-/** Resolve the rate-limit key: per trusted authenticated identity, else per (IPv6-safe) IP. */
+/** Resolve the rate-limit key: per trusted authenticated identity, else per hashed (IPv6-bucketed) IP. */
 function resolveKey(req: OxyAuthedRequest): string {
   const authenticatedKey = resolveTrustedAuthenticatedKey(req);
   if (authenticatedKey) {
     return authenticatedKey;
   }
-  const ip = req.ip || req.socket.remoteAddress || 'unknown';
-  return ipKeyGenerator(ip);
+  const ip = req.ip || req.socket.remoteAddress;
+  if (!ip) {
+    return 'unknown';
+  }
+  return hashAnonymousIp(ip);
 }
 
 /**

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; }
 }