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

package/dist/esm/client/NostrClient.js

@@ -14,6 +14,35 @@ const DEFAULT_QUERY_TIMEOUT_MS = 5000;
 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
@@ -53,6 +82,30 @@ export class NostrClient {
         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
@@ -96,13 +149,6 @@ export class NostrClient {
             }
         }
     }
-    /**
-     * 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
@@ -139,11 +185,41 @@ export class NostrClient {
             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,
@@ -155,8 +231,28 @@ export class NostrClient {
                     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
@@ -197,9 +293,40 @@ export class NostrClient {
                     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);
@@ -211,7 +338,11 @@ export class NostrClient {
                         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);
@@ -288,16 +419,31 @@ export class NostrClient {
                 }
                 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++;
             }
@@ -332,6 +478,11 @@ export class NostrClient {
         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);
         }
@@ -351,7 +502,7 @@ export class NostrClient {
     /**
      * 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)
@@ -365,16 +516,16 @@ export class NostrClient {
                     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;
             }
         }
@@ -386,7 +537,7 @@ export class NostrClient {
      * 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];
@@ -424,11 +575,23 @@ export class NostrClient {
     }
     /**
      * 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);
@@ -445,15 +608,64 @@ export class NostrClient {
     }
     /**
      * 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);
         }
     }
     /**
@@ -478,8 +690,27 @@ export class NostrClient {
         // 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);
     }
@@ -499,24 +730,40 @@ export class NostrClient {
             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();
     }
@@ -718,7 +965,22 @@ export class NostrClient {
             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) {
@@ -736,12 +998,19 @@ export class NostrClient {
         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);
         }
     }
     /**
@@ -767,12 +1036,45 @@ export class NostrClient {
     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)
@@ -791,24 +1093,55 @@ export class NostrClient {
                         }
                     }
                 },
-                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.