@oxyhq/core 10.1.4 → 10.2.0

package/dist/esm/server/rateLimit.js

@@ -1,3 +1,5 @@
+import { createHmac } from 'node:crypto';
+import { isIPv4, isIPv6 } from 'node:net';
 import rateLimit from 'express-rate-limit';
 /**
  * Built-in exemptions. A media app's cover-art/avatar fan-out and HLS
@@ -15,9 +17,98 @@ function isBuiltInExempt(req) {
         path === '/health' ||
         path.endsWith('/health'));
 }
-/** IPv6-safe IP key generator (replaces colons to avoid Redis namespace issues). */
-function ipKeyGenerator(ip) {
-    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) {
+    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;
+    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, bits) {
+    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) {
+    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);
 }
 /**
  * Resolve the trusted authenticated rate-limit key.
@@ -43,14 +134,17 @@ function resolveTrustedAuthenticatedKey(req) {
     }
     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) {
     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);
 }
 /**
  * Build the composed Oxy rate-limit middleware. See module docs for rationale.

package/dist/esm/session/SessionClient.js

@@ -1,4 +1,4 @@
-import { deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, } from '@oxyhq/contracts';
+import { deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedEventSchema, } from '@oxyhq/contracts';
 import { logger } from '../utils/loggerUtils.js';
 import { getSocketIO } from './socketLoader.js';
 /**
@@ -308,6 +308,9 @@ export class SessionClient {
                 });
             }
         });
+        socket.on(SESSION_ACCOUNTS_CHANGED_EVENT, (payload) => {
+            this.onSessionAccountsChanged(payload);
+        });
         this.socket = socket;
         // (Re)bind app-facing server-event subscriptions on the fresh socket.
         this.boundServerEvents.clear();
@@ -315,6 +318,38 @@ export class SessionClient {
             this.bindServerEvent(event);
         }
     }
+    /**
+     * 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.
+     */
+    onSessionAccountsChanged(payload) {
+        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/dist/esm/session/accountDialogController.js

@@ -30,7 +30,15 @@ import { extractErrorStatus } from '../utils/errorUtils.js';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
 import { generateOAuthState, generatePkcePair, normalizeOAuthRedirectUri, persistOAuthHandshake, } from '../utils/oauthPkce.js';
 import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
-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
  * installed Commons on the same device; the `oxycommons://approve?...` deep link
@@ -62,6 +70,18 @@ export class AccountDialogController {
         /** The secret device-flow token of the active QR flow (never surfaced). */
         this.signInToken = null;
         this.pollTimer = 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.
+         */
+        this.authSessionSocket = 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.
+         */
+        this.pollInFlight = false;
         // --- Store plumbing ---
         this.unsubscribeSession = null;
         this.unsubscribeTokens = null;
@@ -80,6 +100,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();
     }
     // =========================================================================
@@ -147,6 +168,8 @@ export class AccountDialogController {
             this.unsubscribeTokens = null;
         }
         this.clearPollTimer();
+        this.closeAuthSessionSocket();
+        this.signInToken = null;
         this.listeners.clear();
     }
     // =========================================================================
@@ -420,6 +443,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
@@ -449,9 +476,10 @@ export class AccountDialogController {
             logger.debug('[AccountDialogController] Commons deep-link probe failed (QR fallback active)', { component: 'AccountDialogController' }, error);
         }
     }
-    /** 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() {
         this.clearPollTimer();
+        this.closeAuthSessionSocket();
         this.signInToken = null;
         if (this.signIn !== IDLE_SIGN_IN) {
             this.setSignIn(IDLE_SIGN_IN);
@@ -506,39 +534,52 @@ export class AccountDialogController {
             void this.pollOnce(sessionToken);
         }, 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`.
+     */
     async pollOnce(sessionToken) {
-        // 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.');
+        // 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;
+                }
             }
-            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 (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;
         }
     }
     async claimAndComplete(sessionId, sessionToken) {
@@ -586,6 +627,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();
@@ -607,6 +649,7 @@ export class AccountDialogController {
     }
     failSignIn(message) {
         this.clearPollTimer();
+        this.closeAuthSessionSocket();
         this.signInToken = null;
         this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: message });
     }
@@ -617,6 +660,77 @@ 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.
+     */
+    openAuthSessionSocket(sessionToken) {
+        this.closeAuthSessionSocket();
+        if (!this.socketFactory)
+            return;
+        let socket;
+        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 = () => {
+            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. */
+    closeAuthSessionSocket() {
+        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
     // =========================================================================
     setSignIn(next) {