@unicitylabs/nostr-js-sdk 0.4.1 → 0.5.0-dev.3

package/dist/browser/index.umd.js

@@ -9538,6 +9538,35 @@
     const DEFAULT_RECONNECT_INTERVAL_MS = 1000;
     const DEFAULT_MAX_RECONNECT_INTERVAL_MS = 30000;
     const DEFAULT_PING_INTERVAL_MS = 30000;
+    /**
+     * Internal sub_id reserved for the keepalive REQ. Namespaced with a
+     * `__nostr-sdk-` prefix so that user code calling
+     * {@link NostrClient.subscribe} with an explicit `subscriptionId`
+     * cannot collide — a user choosing the literal `"ping"` would
+     * otherwise have their subscription forcibly CLOSE/REQ'd every
+     * ping interval. The leading `__` is a stable convention for
+     * "do not pick this name."
+     */
+    const PING_SUB_ID = '__nostr-sdk-keepalive__';
+    /**
+     * Filter id used by the keepalive REQ. We need a filter the relay can
+     * resolve immediately (so EOSE comes back fast = relay is alive), but
+     * which can NOT match any real event past EOSE (so the live tail stays
+     * empty).
+     *
+     * Scoping by `authors:[selfPubkey]` was the original approach but it
+     * matched every event the wallet itself published — including kind-31113
+     * token transfers — which the relay then echoed back on the keepalive
+     * sub. Some relays dedupe events across overlapping subs, so the
+     * wallet's own consumer subscription would not receive its own echo and
+     * any flow waiting on that echo would time out.
+     *
+     * The filter `{ ids: ['00...00'] }` asks the relay for a single event
+     * whose id is exactly the all-zero hash. Real Nostr event ids are
+     * SHA-256 over a canonical JSON serialization, so the all-zero hash is
+     * unreachable in practice. Result: instant EOSE, empty live tail.
+     */
+    const KEEPALIVE_NEVER_MATCH_ID = '0'.repeat(64);
     /**
      * Delay before resubscribing after NIP-42 authentication.
      * This gives the relay time to process the AUTH response before we send
@@ -9577,6 +9606,30 @@
             this.maxReconnectIntervalMs = options?.maxReconnectIntervalMs ?? DEFAULT_MAX_RECONNECT_INTERVAL_MS;
             this.pingIntervalMs = options?.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
         }
+        /**
+         * Replace the key manager used for signing and encryption.
+         *
+         * The connection stays alive — but every operation that consults the
+         * key manager from this point on uses the new key, including:
+         *   - signing future published events,
+         *   - signing NIP-42 AUTH challenge responses,
+         *   - the `authors:[selfPubkey]` filter on the keepalive ping REQ
+         *     (computed each ping interval),
+         *   - any other code path that calls `getPublicKeyHex()` on the
+         *     stored manager.
+         *
+         * Existing in-flight subscriptions are not re-issued or re-keyed.
+         * @param keyManager New key manager
+         */
+        setKeyManager(keyManager) {
+            this.keyManager = keyManager;
+        }
+        /**
+         * Get the current key manager.
+         */
+        getKeyManager() {
+            return this.keyManager;
+        }
         /**
          * Add a connection event listener.
          * @param listener Listener for connection events
@@ -9620,13 +9673,6 @@
                 }
             }
         }
-        /**
-         * Get the key manager.
-         * @returns The key manager instance
-         */
-        getKeyManager() {
-            return this.keyManager;
-        }
         /**
          * Get the current query timeout in milliseconds.
          * @returns Query timeout in milliseconds
@@ -9663,11 +9709,41 @@
                 return;
             }
             return new Promise((resolve, reject) => {
+                // The connection-setup timeout has three races to defend
+                // against:
+                //   A) createWebSocket resolves AFTER the timeout fired.
+                //   B) createWebSocket resolves BEFORE the timeout, but
+                //      `onopen` fires AFTER the timeout fired.
+                //   C) createWebSocket resolves and `onopen` fires BEFORE the
+                //      timeout (the success path).
+                // `pendingSocket` lets the timeout proactively close any
+                // socket that's already been created but hasn't fired
+                // `onopen` yet. The `timedOut` flag covers (A) inside `.then`
+                // and (B) inside `socket.onopen`.
+                let timedOut = false;
+                let pendingSocket = null;
                 const timeoutId = setTimeout(() => {
+                    timedOut = true;
+                    if (pendingSocket) {
+                        try {
+                            pendingSocket.close(1000, 'Connection setup timed out');
+                        }
+                        catch { /* ignore */ }
+                    }
                     reject(new Error(`Connection to ${url} timed out`));
                 }, CONNECTION_TIMEOUT_MS);
                 createWebSocket(url)
                     .then((socket) => {
+                    if (timedOut) {
+                        // Caller already saw the rejection. Discard the late
+                        // socket so we don't leak it.
+                        try {
+                            socket.close(1000, 'Connection setup timed out');
+                        }
+                        catch { /* ignore */ }
+                        return;
+                    }
+                    pendingSocket = socket;
                     const relay = {
                         url,
                         socket,
@@ -9679,8 +9755,28 @@
                         lastPongTime: Date.now(),
                         unansweredPings: 0,
                         wasConnected: existingRelay?.wasConnected ?? false,
+                        // Reset on every new connection: a relay's per-connection
+                        // sub-slot accounting is fresh, so previously-rejected REQs
+                        // should be re-issued on the new socket.
+                        closedSubIds: new Set(),
+                        eosedSubIds: new Set(),
                     };
                     socket.onopen = () => {
+                        // The `.then` block already guards against a socket
+                        // arriving after the connection timeout, but the socket
+                        // can also be created BEFORE the timeout while
+                        // `onopen` fires AFTER the timeout has rejected the
+                        // outer promise. Without this second guard we'd register
+                        // the relay, start a pingTimer, and resubscribe — orphan
+                        // background resources the caller can't see or clean up
+                        // because their connect() call already saw a rejection.
+                        if (timedOut) {
+                            try {
+                                socket.close(1000, 'Connection setup timed out');
+                            }
+                            catch { /* ignore */ }
+                            return;
+                        }
                         clearTimeout(timeoutId);
                         relay.connected = true;
                         relay.reconnectAttempts = 0; // Reset on successful connection
@@ -9721,9 +9817,40 @@
                         const wasConnected = relay.connected;
                         relay.connected = false;
                         this.stopPingTimer(url);
+                        // Pre-onopen close: TCP handshake failure or relay
+                        // immediately closed the WS during the upgrade. Without
+                        // this, the connectToRelay promise stays pending until
+                        // CONNECTION_TIMEOUT_MS (30s) expires; surfacing it now
+                        // lets the caller see the failure promptly and retry.
+                        if (!wasConnected && !timedOut) {
+                            timedOut = true;
+                            clearTimeout(timeoutId);
+                            reject(new Error(`Connection to ${url} closed during handshake: ${event?.reason || 'no reason'}`));
+                        }
                         if (wasConnected) {
                             const reason = event?.reason || 'Connection closed';
                             this.emitConnectionEvent('disconnect', url, reason);
+                            // Re-trigger the all-done check on every active sub.
+                            // queryWithFirstSeenWins.allRelaysDoneFor only runs
+                            // from listener callbacks (EOSE / CLOSED via onError);
+                            // a socket that drops without sending either would
+                            // otherwise leave the query hanging until
+                            // queryTimeoutMs even though the disconnected relay no
+                            // longer counts toward "still pending" relays. Firing
+                            // a synthetic onError gives every active sub a chance
+                            // to re-evaluate now that the relay set has shrunk.
+                            // Include the relay URL so listeners in a multi-relay
+                            // client can attribute which relay dropped.
+                            const inflight = Array.from(this.subscriptions.entries());
+                            for (const [subId, sub] of inflight) {
+                                try {
+                                    sub.listener.onError?.(subId, `Relay disconnected (${url}): ${reason}`);
+                                }
+                                catch {
+                                    // Ignore listener errors — we're notifying
+                                    // best-effort.
+                                }
+                            }
                         }
                         if (!this.closed && this.autoReconnect && !relay.reconnecting) {
                             this.scheduleReconnect(url);
@@ -9735,7 +9862,11 @@
                             reject(new Error(`Failed to connect to ${url}: ${error.message || 'Unknown error'}`));
                         }
                     };
-                    this.relays.set(url, relay);
+                    // Note: we do NOT register the relay in `this.relays` here —
+                    // only after `onopen` fires successfully. Registering eagerly
+                    // (before onopen) would leak the relay into the global map
+                    // even when the connection setup times out and the caller's
+                    // promise has already rejected.
                 })
                     .catch((error) => {
                     clearTimeout(timeoutId);
@@ -9812,16 +9943,31 @@
                     }
                     return;
                 }
-                // Send a subscription request as a ping (relays respond with EOSE)
-                // Use a single fixed subscription ID per relay to avoid accumulating subscriptions
-                // Note: limit:1 is used because some relays don't respond to limit:0
+                // Send a subscription request as a ping (relays respond with EOSE).
+                // The filter MUST be tightly scoped to something no real event can
+                // match — both for the initial query AND the post-EOSE live tail.
+                //
+                // Earlier iterations used `authors:[self]` reasoning that "the
+                // relay would only forward our own future events". That reasoning
+                // was wrong: it precisely DOES forward every event the wallet
+                // publishes, including kind-31113 token transfers. Some relays
+                // dedupe events across overlapping subs, so the wallet's own
+                // consumer subscription would miss its echo and any flow waiting
+                // on it would time out.
+                //
+                // {@link KEEPALIVE_NEVER_MATCH_ID} (the all-zero SHA-256 hash) is
+                // unreachable in real event-id space, so the relay returns EOSE
+                // immediately and the live tail never matches.
                 try {
-                    const pingSubId = `ping`;
                     // First close any existing ping subscription to ensure we don't accumulate
-                    const closeMessage = JSON.stringify(['CLOSE', pingSubId]);
+                    const closeMessage = JSON.stringify(['CLOSE', PING_SUB_ID]);
                     relay.socket.send(closeMessage);
                     // Then send the new ping request (limit:1 ensures relay sends EOSE)
-                    const pingMessage = JSON.stringify(['REQ', pingSubId, { limit: 1 }]);
+                    const pingMessage = JSON.stringify([
+                        'REQ',
+                        PING_SUB_ID,
+                        { ids: [KEEPALIVE_NEVER_MATCH_ID], limit: 1 },
+                    ]);
                     relay.socket.send(pingMessage);
                     relay.unansweredPings++;
                 }
@@ -9856,6 +10002,11 @@
             if (!relay?.socket || !relay.connected)
                 return;
             for (const [subId, info] of this.subscriptions) {
+                // Skip subs this relay has previously CLOSED — re-issuing them
+                // just triggers the same rejection in a loop. Other healthy
+                // relays still resubscribe.
+                if (relay.closedSubIds.has(subId))
+                    continue;
                 const message = JSON.stringify(['REQ', subId, info.filter.toJSON()]);
                 relay.socket.send(message);
             }
@@ -9875,7 +10026,7 @@
         /**
          * Handle a message from a relay.
          */
-        handleRelayMessage(_url, message) {
+        handleRelayMessage(relayUrl, message) {
             try {
                 const json = JSON.parse(message);
                 if (!Array.isArray(json) || json.length < 2)
@@ -9889,16 +10040,16 @@
                         this.handleOkMessage(json);
                         break;
                     case 'EOSE':
-                        this.handleEOSEMessage(json);
+                        this.handleEOSEMessage(relayUrl, json);
                         break;
                     case 'NOTICE':
                         this.handleNoticeMessage(json);
                         break;
                     case 'CLOSED':
-                        this.handleClosedMessage(json);
+                        this.handleClosedMessage(relayUrl, json);
                         break;
                     case 'AUTH':
-                        this.handleAuthMessage(_url, json);
+                        this.handleAuthMessage(relayUrl, json);
                         break;
                 }
             }
@@ -9910,7 +10061,7 @@
          * Handle EVENT message from relay.
          */
         handleEventMessage(json) {
-            if (json.length < 3)
+            if (json.length < 3 || typeof json[1] !== 'string')
                 return;
             const subscriptionId = json[1];
             const eventData = json[2];
@@ -9948,11 +10099,23 @@
         }
         /**
          * Handle EOSE (End of Stored Events) message from relay.
+         *
+         * Records the per-relay EOSE marker (mirroring closedSubIds) so
+         * queryWithFirstSeenWins can decide when ALL connected relays have
+         * finished — either streamed EOSE or rejected with CLOSED — instead
+         * of settling off the first fast relay's EOSE while a slower relay
+         * is still about to deliver matching events.
          */
-        handleEOSEMessage(json) {
-            if (json.length < 2)
+        handleEOSEMessage(relayUrl, json) {
+            if (json.length < 2 || typeof json[1] !== 'string')
                 return;
             const subscriptionId = json[1];
+            if (!this.subscriptions.has(subscriptionId))
+                return;
+            const relay = this.relays.get(relayUrl);
+            if (relay) {
+                relay.eosedSubIds.add(subscriptionId);
+            }
             const subscription = this.subscriptions.get(subscriptionId);
             if (subscription?.listener.onEndOfStoredEvents) {
                 subscription.listener.onEndOfStoredEvents(subscriptionId);
@@ -9969,15 +10132,64 @@
         }
         /**
          * Handle CLOSED message from relay (subscription closed by relay).
+         *
+         * NIP-01 CLOSED frames are terminal for the named subscription **on
+         * the sending relay**. In a multi-relay client the same sub_id may
+         * still be alive on a healthy relay, so we must NOT delete the
+         * global `this.subscriptions` entry here — that would silently drop
+         * EVENT/EOSE frames from the still-healthy relays in
+         * `handleEventMessage` (which consults the global map).
+         *
+         * Instead we record the rejection on the sending relay's
+         * `closedSubIds` set so `resubscribeAll` and post-AUTH resubscribe
+         * skip it on this relay only. The listener is notified via
+         * `onError` so callers (e.g. queryWithFirstSeenWins) can decide to
+         * settle and explicitly `unsubscribe()` if they want to give up
+         * across all relays.
          */
-        handleClosedMessage(json) {
-            if (json.length < 3)
+        handleClosedMessage(relayUrl, json) {
+            // NIP-01 makes the message field optional: `["CLOSED", <sub>]` is
+            // valid. Dropping such frames was exactly the leak this PR sets out
+            // to fix — no closedSubIds marker and no onError notification means
+            // queries hang until timeout and resubscribe loops persist.
+            if (json.length < 2 || typeof json[1] !== 'string')
                 return;
             const subscriptionId = json[1];
-            const message = json[2];
+            // Ignore CLOSED for sub_ids we don't know about. A misbehaving or
+            // malicious relay could otherwise spam us with arbitrary sub_ids
+            // and grow `closedSubIds` unbounded over a long-lived connection,
+            // and could pre-emptively block sub_ids we might use later.
+            if (!this.subscriptions.has(subscriptionId))
+                return;
+            const message = typeof json[2] === 'string' ? json[2] : 'no reason provided';
+            // NIP-42 transient case: relays that require AUTH typically reject
+            // pre-auth REQs with `CLOSED("auth-required:...")` and then send
+            // an AUTH challenge. resubscribeAfterAuth re-issues the sub, so
+            // this rejection is NOT terminal. If we marked closedSubIds here,
+            // queryWithFirstSeenWins.onError would settle the future
+            // prematurely (single-relay → allRelaysDoneFor=true), unsubscribe
+            // the sub, and the post-AUTH retry would find nothing to retry.
+            // Listener still gets onError so callers see the reason; we just
+            // don't poison the per-relay state with a transient marker.
+            //
+            // We accept three on-the-wire shapes: `auth-required:...`
+            // (NIP-42 standard with reason), `auth-required ...` (whitespace
+            // separator), and bare `auth-required` (no suffix at all — some
+            // relays / tests).
+            const isAuthRequired = message === 'auth-required'
+                || message.startsWith('auth-required:')
+                || message.startsWith('auth-required ');
+            const relay = this.relays.get(relayUrl);
+            if (relay && !isAuthRequired) {
+                relay.closedSubIds.add(subscriptionId);
+            }
             const subscription = this.subscriptions.get(subscriptionId);
             if (subscription?.listener.onError) {
-                subscription.listener.onError(subscriptionId, `Subscription closed: ${message}`);
+                // Pass the relay's reason through verbatim so callers can
+                // pattern-match on standard prefixes (`auth-required:`,
+                // `rate-limited:`, `blocked:`, etc.) without parsing through
+                // a wrapper string.
+                subscription.listener.onError(subscriptionId, message);
             }
         }
         /**
@@ -10002,8 +10214,27 @@
             // Send AUTH response
             const message = JSON.stringify(['AUTH', authEvent.toJSON()]);
             relay.socket.send(message);
-            // Re-send subscriptions after auth (relay may have ignored pre-auth requests)
+            // Re-send subscriptions after auth (relay may have ignored pre-auth
+            // requests). Two separate per-relay markers, two separate decisions:
+            //
+            //  - `closedSubIds`: do NOT clear. handleClosedMessage already
+            //    skips the auth-required transient case, so anything in this
+            //    set is a TERMINAL rejection (rate-limited, blocked, etc.)
+            //    that AUTH does not relax. The resubscribeAll guard then
+            //    correctly skips terminal-rejected subs on this relay. They
+            //    will be retried on the next reconnect, when onopen creates a
+            //    fresh RelayConnection with empty markers.
+            //
+            //  - `eosedSubIds`: clear. A relay may have EOSE'd a pre-auth sub
+            //    with zero events (filter unsatisfiable without auth context);
+            //    post-auth the same filter might match. We must re-arm the
+            //    local "still waiting" state so any in-flight
+            //    queryWithFirstSeenWins doesn't see this relay as already-done
+            //    from a stale marker.
             setTimeout(() => {
+                const r = this.relays.get(relayUrl);
+                if (r)
+                    r.eosedSubIds.clear();
                 this.resubscribeAll(relayUrl);
             }, AUTH_RESUBSCRIBE_DELAY_MS);
         }
@@ -10023,24 +10254,40 @@
                 item.reject(new Error('Client disconnected'));
             }
             this.eventQueue = [];
-            // Close all relay connections and clean up timers
+            // Close all relay connections and clean up timers. Mark every
+            // relay disconnected synchronously BEFORE we notify subscriptions
+            // below, so any listener that consults `allRelaysDoneFor` sees
+            // zero connected relays and settles immediately.
             for (const [url, relay] of this.relays) {
-                // Stop ping timer
+                relay.connected = false;
                 if (relay.pingTimer) {
                     clearInterval(relay.pingTimer);
                     relay.pingTimer = null;
                 }
-                // Stop reconnect timer
                 if (relay.reconnectTimer) {
                     clearTimeout(relay.reconnectTimer);
                     relay.reconnectTimer = null;
                 }
-                // Close socket
                 if (relay.socket && relay.socket.readyState !== CLOSED) {
                     relay.socket.close(1000, 'Client disconnected');
                 }
                 this.emitConnectionEvent('disconnect', url, 'Client disconnected');
             }
+            // Notify in-flight subscriptions that we're shutting down.
+            // queryWithFirstSeenWins.onError re-checks allRelaysDoneFor (now
+            // 0 connected → trivially true) and settles immediately, sparing
+            // callers the full queryTimeoutMs wait. Snapshot keys first
+            // because the listener may call unsubscribe(), which mutates
+            // this.subscriptions while we iterate.
+            const inflightSubs = Array.from(this.subscriptions.entries());
+            for (const [subId, sub] of inflightSubs) {
+                try {
+                    sub.listener.onError?.(subId, 'Client disconnected');
+                }
+                catch {
+                    // Ignore listener errors — we're tearing down anyway.
+                }
+            }
             this.relays.clear();
             this.subscriptions.clear();
         }
@@ -10242,7 +10489,22 @@
                 filter = filterOrSubId;
                 listener = listenerOrFilter;
             }
+            // Reserved prefix for SDK-internal sub_ids (currently just the
+            // keepalive `PING_SUB_ID`). Reject explicit caller use so the
+            // keepalive timer's CLOSE/REQ cycle can't stomp on user state.
+            if (subscriptionId.startsWith('__nostr-sdk-')) {
+                throw new Error(`Subscription ID "${subscriptionId}" uses the reserved "__nostr-sdk-" prefix — pick a different id.`);
+            }
             this.subscriptions.set(subscriptionId, { filter, listener });
+            // Wipe any stale per-relay EOSE/CLOSED markers for this sub_id
+            // before issuing the REQ — otherwise a fresh subscribe with a
+            // sub_id that was previously CLOSED (or was just freshly
+            // EOSE'd) would be skipped or treated as "already done" on
+            // those relays.
+            for (const [, relay] of this.relays) {
+                relay.closedSubIds.delete(subscriptionId);
+                relay.eosedSubIds.delete(subscriptionId);
+            }
             // Send subscription request to all connected relays
             const message = JSON.stringify(['REQ', subscriptionId, filter.toJSON()]);
             for (const [, relay] of this.relays) {
@@ -10260,12 +10522,19 @@
             if (!this.subscriptions.has(subscriptionId))
                 return;
             this.subscriptions.delete(subscriptionId);
-            // Send CLOSE to all connected relays
+            // Send CLOSE to all connected relays — except those that already
+            // CLOSED the sub themselves (no point telling the relay something
+            // it told us).
             const message = JSON.stringify(['CLOSE', subscriptionId]);
             for (const [, relay] of this.relays) {
-                if (relay.connected && relay.socket?.readyState === OPEN) {
+                if (relay.connected && relay.socket?.readyState === OPEN
+                    && !relay.closedSubIds.has(subscriptionId)) {
                     relay.socket.send(message);
                 }
+                // Drop both per-relay markers now that the sub is gone from
+                // the global map.
+                relay.closedSubIds.delete(subscriptionId);
+                relay.eosedSubIds.delete(subscriptionId);
             }
         }
         /**
@@ -10291,12 +10560,45 @@
         queryWithFirstSeenWins(filter, extractResult) {
             return new Promise((resolve) => {
                 let subscriptionId = '';
-                const timeoutId = setTimeout(() => {
-                    if (subscriptionId)
-                        this.unsubscribe(subscriptionId);
-                    resolve(null);
-                }, this.queryTimeoutMs);
+                let settled = false;
+                // Declared as `let` and initialized lazily so `finishWith` can be
+                // invoked before the setTimeout call below without hitting the
+                // TDZ on `clearTimeout(timeoutId)`. (The same comment on the
+                // listener anticipates synchronous-callback hypothetical paths.)
+                let timeoutId;
+                // Accept an explicit `id` so callers from inside the listener can
+                // pass the sub_id the relay echoed back. This guards against any
+                // future change to subscribe() that would invoke listener
+                // callbacks before its return value is bound to `subscriptionId`
+                // — the closure-captured value would still be `''` and we'd skip
+                // the CLOSE frame, leaking the slot on the relay.
+                const finishWith = (result, id) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timeoutId !== undefined)
+                        clearTimeout(timeoutId);
+                    const subId = id || subscriptionId;
+                    if (subId)
+                        this.unsubscribe(subId);
+                    resolve(result);
+                };
+                timeoutId = setTimeout(() => finishWith(null), this.queryTimeoutMs);
                 const authors = new Map();
+                const allRelaysDone = (id) => this.allRelaysDoneFor(id);
+                const pickWinner = () => {
+                    let winnerEntry = null;
+                    let winnerPubkey = '';
+                    for (const [pubkey, entry] of authors) {
+                        if (!winnerEntry
+                            || entry.firstSeen < winnerEntry.firstSeen
+                            || (entry.firstSeen === winnerEntry.firstSeen && pubkey < winnerPubkey)) {
+                            winnerEntry = entry;
+                            winnerPubkey = pubkey;
+                        }
+                    }
+                    return winnerEntry ? extractResult(winnerEntry.latestEvent) : null;
+                };
                 subscriptionId = this.subscribe(filter, {
                     onEvent: (event) => {
                         // Verify signature to prevent relay injection of forged events (#4)
@@ -10315,24 +10617,55 @@
                             }
                         }
                     },
-                    onEndOfStoredEvents: () => {
-                        clearTimeout(timeoutId);
-                        this.unsubscribe(subscriptionId);
-                        let winnerEntry = null;
-                        let winnerPubkey = '';
-                        for (const [pubkey, entry] of authors) {
-                            if (!winnerEntry
-                                || entry.firstSeen < winnerEntry.firstSeen
-                                || (entry.firstSeen === winnerEntry.firstSeen && pubkey < winnerPubkey)) {
-                                winnerEntry = entry;
-                                winnerPubkey = pubkey;
-                            }
+                    // EOSE means *this relay* has finished delivering stored
+                    // events. In a multi-relay client we must not settle yet — a
+                    // slower relay may still be about to deliver matching events.
+                    // Settle only when every connected relay has either EOSE'd
+                    // OR CLOSED'd this sub. (Single-relay clients are unaffected:
+                    // allDone is trivially true with one relay.)
+                    onEndOfStoredEvents: (id) => {
+                        if (allRelaysDone(id)) {
+                            finishWith(pickWinner(), id);
+                        }
+                    },
+                    // Subscription error from the SDK — fires from three paths
+                    // that all need the same "is it time to settle?" check:
+                    //   1. Relay sent CLOSED for this sub. In a multi-relay
+                    //      client the same sub_id may still be alive on a
+                    //      healthy relay; settling on the first CLOSED would
+                    //      prematurely abort a query other relays could
+                    //      satisfy. handleClosedMessage records the rejection
+                    //      on the sending relay's closedSubIds before invoking
+                    //      us, so we can decide via allRelaysDoneFor.
+                    //   2. Relay disconnected mid-query (socket.onclose →
+                    //      synthetic onError). The relay no longer counts as
+                    //      connected, so allRelaysDoneFor excludes it.
+                    //   3. Client disconnected (disconnect() → synthetic
+                    //      onError). All relays are torn down, allRelaysDoneFor
+                    //      sees zero connected and settles.
+                    onError: (id, message) => {
+                        console.warn(`Subscription error on ${id}: ${message}`);
+                        if (allRelaysDone(id)) {
+                            finishWith(pickWinner(), id);
                         }
-                        resolve(winnerEntry ? extractResult(winnerEntry.latestEvent) : null);
+                        // else: keep waiting for EOSE / CLOSED from remaining
+                        // relays or the overall query timeout.
                     },
                 });
             });
         }
+        /**
+         * True if every currently-connected relay has finished delivering
+         * for the given sub_id (either EOSE'd or CLOSED'd it). Used by
+         * queryWithFirstSeenWins to coordinate multi-relay settlement.
+         */
+        allRelaysDoneFor(subscriptionId) {
+            const connected = Array.from(this.relays.values()).filter((r) => r.connected);
+            // No connected relays at all → nothing to wait for; settle.
+            if (connected.length === 0)
+                return true;
+            return connected.every((r) => r.eosedSubIds.has(subscriptionId) || r.closedSubIds.has(subscriptionId));
+        }
         /**
          * Query for a public key by nametag.
          * Uses first-seen-wins anti-hijacking resolution.