echoclaw-relay-agent 0.14.0 → 0.15.2

package/dist/RelayAgent.js

@@ -23,6 +23,7 @@ import { SessionStore } from './relay/SessionStore.js';
 import { IdentityStore } from './relay/IdentityStore.js';
 import { FrameCrypto } from './crypto/FrameCrypto.js';
 import { GatewayManager } from './gateway/GatewayManager.js';
+import { IdentityExchangeError } from './types.js';
 export class RelayAgent extends EventEmitter {
     constructor(config) {
         super();
@@ -537,7 +538,7 @@ export class RelayAgent extends EventEmitter {
                 await this._handleIdentityExchange(sessionData, freshPairing);
             }
             catch (err) {
-                this.emit('error', new Error(`Identity exchange failed: ${err instanceof Error ? err.message : err}`));
+                this.emit('error', new IdentityExchangeError(`Identity exchange failed: ${err instanceof Error ? err.message : err}`));
             }
         }
         // Persist session (with identity fields if exchange succeeded)
@@ -564,35 +565,57 @@ export class RelayAgent extends EventEmitter {
      * Agent waits for desktop's identity_exchange, then responds with its own.
      */
     async _handleIdentityExchange(sessionData, forceExchange = false) {
-        const identity = await this.identityStore.loadOrCreate();
-        const ed = this.identityStore.getEd25519Identity();
-        // Populate session with own identity
-        sessionData.identityDeviceId = identity.deviceId;
-        // If we already have peer's key from previous pairing, skip exchange
-        // UNLESS forceExchange is true (fresh pairing → may be a new desktop machine).
-        if (identity.peerPublicKeyRaw && !forceExchange) {
-            sessionData.peerPublicKeyRaw = identity.peerPublicKeyRaw;
-            sessionData.bindingSecret = identity.bindingSecret;
+        // Start listening for desktop's identity_exchange IMMEDIATELY — before any
+        // async work — to prevent a race condition where the desktop sends its
+        // identity_exchange before our loadOrCreate() completes.
+        // The desktop (warm restart, identity cached) may complete onPaired() and
+        // send the message before our cold-start I/O finishes.
+        let earlyIdentity = null;
+        const earlyHandler = (payload) => {
+            if (payload?.type === 'identity_exchange' && payload.ed25519_pubkey) {
+                earlyIdentity = payload;
+                this.removeListener('message', earlyHandler);
+            }
+        };
+        this.on('message', earlyHandler);
+        try {
+            const identity = await this.identityStore.loadOrCreate();
+            const ed = this.identityStore.getEd25519Identity();
+            // Populate session with own identity
+            sessionData.identityDeviceId = identity.deviceId;
+            // If we already have peer's key from previous pairing, skip exchange
+            // UNLESS forceExchange is true (fresh pairing → may be a new desktop machine).
+            if (identity.peerPublicKeyRaw && !forceExchange) {
+                sessionData.peerPublicKeyRaw = identity.peerPublicKeyRaw;
+                sessionData.bindingSecret = identity.bindingSecret;
+                this._identityExchanged = true;
+                return;
+            }
+            // Remove early handler before entering wait — prevents both handlers from
+            // processing the same message simultaneously (Reviewer #2, #3 finding).
+            this.removeListener('message', earlyHandler);
+            // Use early-captured message if available, otherwise wait with timeout
+            const peerIdentity = earlyIdentity ?? await this._waitForIdentityExchange(10000);
+            // Respond with our own identity
+            const myPubKeyBase64 = toBase64(ed.publicKeyRaw);
+            await this.send({
+                type: 'identity_exchange',
+                ed25519_pubkey: myPubKeyBase64,
+                device_id: identity.deviceId,
+            });
+            // Persist peer's public key
+            await this.identityStore.updatePeer(peerIdentity.ed25519_pubkey);
+            sessionData.peerPublicKeyRaw = peerIdentity.ed25519_pubkey;
             this._identityExchanged = true;
-            return;
+            this.emit('identity_exchanged', {
+                ownDeviceId: identity.deviceId,
+                peerDeviceId: peerIdentity.device_id,
+            });
+        }
+        finally {
+            // Clean up early handler if still registered
+            this.removeListener('message', earlyHandler);
         }
-        // Wait for desktop's identity_exchange (10s timeout)
-        const peerIdentity = await this._waitForIdentityExchange(10000);
-        // Respond with our own identity
-        const myPubKeyBase64 = toBase64(ed.publicKeyRaw);
-        await this.send({
-            type: 'identity_exchange',
-            ed25519_pubkey: myPubKeyBase64,
-            device_id: identity.deviceId,
-        });
-        // Persist peer's public key
-        await this.identityStore.updatePeer(peerIdentity.ed25519_pubkey);
-        sessionData.peerPublicKeyRaw = peerIdentity.ed25519_pubkey;
-        this._identityExchanged = true;
-        this.emit('identity_exchanged', {
-            ownDeviceId: identity.deviceId,
-            peerDeviceId: peerIdentity.device_id,
-        });
     }
     /**
      * Wait for an identity_exchange message from the desktop.

package/dist/RelayClient.d.ts

@@ -36,6 +36,7 @@ export declare class RelayClient extends EventEmitter {
     private _stopped;
     private _paired;
     private _needsRekey;
+    private _rekeyInFlight;
     private _rekeyRetryCount;
     private _activePairing;
     private readonly config;

package/dist/RelayClient.js

@@ -30,6 +30,7 @@ import { PairingProtocol } from './relay/PairingProtocol.js';
 import { SessionStore } from './relay/SessionStore.js';
 import { IdentityStore } from './relay/IdentityStore.js';
 import { FrameCrypto } from './crypto/FrameCrypto.js';
+import { IdentityExchangeError } from './types.js';
 export class RelayClient extends EventEmitter {
     constructor(config) {
         super();
@@ -93,6 +94,12 @@ export class RelayClient extends EventEmitter {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_rekeyInFlight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         Object.defineProperty(this, "_rekeyRetryCount", {
             enumerable: true,
             configurable: true,
@@ -242,6 +249,7 @@ export class RelayClient extends EventEmitter {
         this._stopped = true;
         this._paired = false;
         this._needsRekey = false;
+        this._rekeyInFlight = false;
         this._activePairing?.abort();
         this._activePairing = null;
         this.transport?.disconnect();
@@ -510,7 +518,7 @@ export class RelayClient extends EventEmitter {
             catch (err) {
                 // Identity exchange failure is non-fatal — connection works without it,
                 // but identity reconnect won't be available.
-                this.emit('error', new Error(`Identity exchange failed: ${err instanceof Error ? err.message : err}`));
+                this.emit('error', new IdentityExchangeError(`Identity exchange failed: ${err instanceof Error ? err.message : err}`));
             }
         }
         // Persist session (with identity fields if exchange succeeded)
@@ -527,36 +535,56 @@ export class RelayClient extends EventEmitter {
      * Desktop initiates by sending its identity first, then waits for agent's response.
      */
     async _performIdentityExchange(sessionData, forceExchange = false) {
-        const identity = await this.identityStore.loadOrCreate();
-        const ed = this.identityStore.getEd25519Identity();
-        // Populate session with own identity
-        sessionData.identityDeviceId = identity.deviceId;
-        // If we already have peer's key (from previous pairing stored in identity file),
-        // skip the exchange — just carry it forward.
-        // UNLESS forceExchange is true (fresh pairing with new code → may be a new agent machine).
-        if (identity.peerPublicKeyRaw && !forceExchange) {
-            sessionData.peerPublicKeyRaw = identity.peerPublicKeyRaw;
-            sessionData.bindingSecret = identity.bindingSecret;
+        // Register listener IMMEDIATELY — before any async work — to prevent
+        // a race condition where the agent responds before we start waiting.
+        // Agent (warm restart, identity cached) may send identity_exchange
+        // before our loadOrCreate() or send() completes.
+        let earlyIdentity = null;
+        const earlyHandler = (payload) => {
+            if (payload?.type === 'identity_exchange' && payload.ed25519_pubkey) {
+                earlyIdentity = payload;
+                this.removeListener('message', earlyHandler);
+            }
+        };
+        this.on('message', earlyHandler);
+        try {
+            const identity = await this.identityStore.loadOrCreate();
+            const ed = this.identityStore.getEd25519Identity();
+            // Populate session with own identity
+            sessionData.identityDeviceId = identity.deviceId;
+            // If we already have peer's key (from previous pairing stored in identity file),
+            // skip the exchange — just carry it forward.
+            // UNLESS forceExchange is true (fresh pairing with new code → may be a new agent machine).
+            if (identity.peerPublicKeyRaw && !forceExchange) {
+                sessionData.peerPublicKeyRaw = identity.peerPublicKeyRaw;
+                sessionData.bindingSecret = identity.bindingSecret;
+                this._identityExchanged = true;
+                return; // finally will clean up earlyHandler
+            }
+            // Send our Ed25519 public key to the agent (through E2E encrypted DATA channel)
+            const myPubKeyBase64 = toBase64(ed.publicKeyRaw);
+            await this.send({
+                type: 'identity_exchange',
+                ed25519_pubkey: myPubKeyBase64,
+                device_id: identity.deviceId,
+            });
+            // Remove early handler before entering wait — prevents dual listeners
+            this.removeListener('message', earlyHandler);
+            // Use early-captured message if available, otherwise wait with timeout
+            const peerIdentity = earlyIdentity ?? await this._waitForIdentityExchange(10000);
+            // Persist peer's public key
+            await this.identityStore.updatePeer(peerIdentity.ed25519_pubkey);
+            sessionData.peerPublicKeyRaw = peerIdentity.ed25519_pubkey;
             this._identityExchanged = true;
-            return;
+            this.emit('identity_exchanged', {
+                ownDeviceId: identity.deviceId,
+                peerDeviceId: peerIdentity.device_id,
+            });
+        }
+        finally {
+            // Clean up early handler if still registered (e.g. early return path)
+            this.removeListener('message', earlyHandler);
         }
-        // Send our Ed25519 public key to the agent (through E2E encrypted DATA channel)
-        const myPubKeyBase64 = toBase64(ed.publicKeyRaw);
-        await this.send({
-            type: 'identity_exchange',
-            ed25519_pubkey: myPubKeyBase64,
-            device_id: identity.deviceId,
-        });
-        // Wait for agent's identity_exchange response (10s timeout)
-        const peerIdentity = await this._waitForIdentityExchange(10000);
-        // Persist peer's public key
-        await this.identityStore.updatePeer(peerIdentity.ed25519_pubkey);
-        sessionData.peerPublicKeyRaw = peerIdentity.ed25519_pubkey;
-        this._identityExchanged = true;
-        this.emit('identity_exchanged', {
-            ownDeviceId: identity.deviceId,
-            peerDeviceId: peerIdentity.device_id,
-        });
     }
     /**
      * Wait for an identity_exchange message from the agent.
@@ -650,34 +678,82 @@ export class RelayClient extends EventEmitter {
         });
         this.transport.on('open', () => {
             if (this._paired && this._needsRekey && this.pairingCode && this.transport) {
+                // If a re-key is already in flight on a previous (now-dead) connection,
+                // abort it and start fresh on this new connection. Just returning would
+                // leave the new WebSocket idle while the old pairing hangs on a dead socket.
+                // (Reviewer finding: Gemini + Claude both flagged simple `return` as a bug.)
+                if (this._rekeyInFlight) {
+                    this._activePairing?.abort();
+                    this._rekeyInFlight = false;
+                    // Fall through to start fresh re-key on the new connection.
+                }
                 // Server requested re-ECDH (e.g. AGENT_RESTARTED) —
-                // cancel any in-flight pairing and start fresh handshake.
+                // start fresh handshake on the (possibly new) transport.
                 // Invalidate old crypto state: agent has new keys, old ones are useless.
-                this._needsRekey = false;
-                this._activePairing?.abort();
+                // Note: _needsRekey stays true until handshake succeeds.
+                this._rekeyInFlight = true;
                 this.sessionKey = null;
                 this.frameCrypto = null;
                 this.setStatus('connecting');
-                const pairing = new PairingProtocol(this.transport);
-                this._activePairing = pairing;
-                pairing.pairAsClient(this.pairingCode)
+                let pairing;
+                let pairingPromise;
+                try {
+                    pairing = new PairingProtocol(this.transport);
+                    this._activePairing = pairing;
+                    pairingPromise = pairing.pairAsClient(this.pairingCode);
+                }
+                catch (syncErr) {
+                    // Guard against synchronous throw from constructor or pairAsClient
+                    this._rekeyInFlight = false;
+                    this._activePairing = null;
+                    this.emit('error', syncErr instanceof Error ? syncErr : new Error(String(syncErr)));
+                    return;
+                }
+                pairingPromise
                     .then(result => {
-                    this._rekeyRetryCount = 0; // Reset on success
+                    // Identity guard: if _activePairing changed, this is a stale
+                    // (aborted) promise settling as microtask — ignore it.
+                    if (this._activePairing !== pairing)
+                        return;
+                    this._rekeyInFlight = false;
+                    this._activePairing = null;
+                    this._needsRekey = false; // Clear only on success
+                    this._rekeyRetryCount = 0;
                     this.onPaired(result, 'resumed');
                 })
                     .catch(err => {
+                    // Identity guard: old aborted pairing's .catch() fires as microtask
+                    // AFTER new pairing is set up — must not clobber new pairing's state.
+                    if (this._activePairing !== pairing)
+                        return;
+                    this._rekeyInFlight = false;
                     this._activePairing = null;
                     this._rekeyRetryCount++;
-                    // Circuit breaker: stop after 5 consecutive re-key failures
+                    // Circuit breaker: stop after 5 consecutive re-key failures.
+                    // Clear all rekey state so next connect() can start fresh.
+                    // IMPORTANT: reset ALL state before emitting error — emit() is
+                    // synchronous, and a listener may call connect() immediately.
                     if (this._rekeyRetryCount >= 5) {
+                        const retries = this._rekeyRetryCount;
+                        // 1. Reset all in-memory state
                         this._needsRekey = false;
-                        this.emit('error', new Error(`Re-key failed after ${this._rekeyRetryCount} retries, giving up`));
-                        // Force transport to close and reconnect from scratch
+                        this._paired = false;
+                        this._identityExchanged = false;
+                        this.sessionKey = null;
+                        this.frameCrypto = null;
+                        this._rekeyRetryCount = 0;
+                        // 2. Clear disk state + teardown transport
+                        this.sessionStore.clear().catch((clearErr) => {
+                            this.emit('error', new Error(`Failed to clear stale session: ${clearErr instanceof Error ? clearErr.message : clearErr}`));
+                        });
                         this.transport?.disconnect();
+                        this.setStatus('disconnected');
+                        // 3. Notify LAST — state is fully clean if listener calls connect()
+                        this.emit('error', new Error(`Re-key failed after ${retries} retries, giving up`));
                         return;
                     }
-                    // Re-key failed — set _needsRekey back to true for retry.
-                    this._needsRekey = true;
+                    // Re-key failed — _needsRekey stays true (never cleared), so next
+                    // on('open') will retry automatically.
                     // If WS is still OPEN (pairing failed at protocol level, not transport level),
                     // _needsRekey won't be consumed until next on('open').
                     // Force a reconnect to trigger a fresh on('open').

package/dist/cli.js

@@ -283,6 +283,13 @@ async function runSetup(code, relay, bridgePort) {
             resolve(info);
         });
         agent.on('error', (err) => {
+            // Identity exchange failure is non-fatal — ECDH pairing still works,
+            // only identity reconnect won't be available. Don't reject setup.
+            if (err.constructor?.name === 'IdentityExchangeError') {
+                console.log(`  ${YELLOW}Warning: ${err.message}${RESET}`);
+                console.log(`  ${DIM}Connection will work, but identity reconnect won't be available.${RESET}`);
+                return;
+            }
             clearTimeout(timeout);
             reject(err);
         });

package/dist/index.d.ts

@@ -8,7 +8,7 @@
  *   connect(pairingCode) → send(payload) / subscribe(event, cb) → disconnect()
  */
 export type { EncryptedFrame, RelayMessage, SessionData, ReconnectConfig, RelayClientConfig, RelayAgentConfig, ClientStatus, ConnectedEvent, DisconnectedEvent, ReconnectingEvent, PairedEvent, ErrorEvent, } from './types.js';
-export { RELAY_PROTOCOL_VERSION, DEFAULT_RECONNECT } from './types.js';
+export { RELAY_PROTOCOL_VERSION, DEFAULT_RECONNECT, IdentityExchangeError } from './types.js';
 export { FrameCrypto } from './crypto/FrameCrypto.js';
 export { ReconnectPolicy } from './relay/ReconnectPolicy.js';
 export { SessionStore } from './relay/SessionStore.js';

package/dist/index.js

@@ -7,7 +7,7 @@
  * External callers only need:
  *   connect(pairingCode) → send(payload) / subscribe(event, cb) → disconnect()
  */
-export { RELAY_PROTOCOL_VERSION, DEFAULT_RECONNECT } from './types.js';
+export { RELAY_PROTOCOL_VERSION, DEFAULT_RECONNECT, IdentityExchangeError } from './types.js';
 // ── Crypto ───────────────────────────────────────────────────────
 export { FrameCrypto } from './crypto/FrameCrypto.js';
 // ── Relay ────────────────────────────────────────────────────────

package/dist/types.d.ts

@@ -73,5 +73,13 @@ export interface PeerStatusEvent {
     status: 'warning' | 'online';
     timestamp?: number;
 }
+/**
+ * Non-fatal error emitted when Ed25519 identity exchange fails.
+ * Connection still works — only identity-based reconnect is unavailable.
+ * Consumers (e.g. setup CLI) can check `instanceof` to avoid treating this as fatal.
+ */
+export declare class IdentityExchangeError extends Error {
+    constructor(message: string);
+}
 export type { InstallRequest, InstallAbort, InstallAck, InstallStatus, InstallResult, InstallPreviewData, InstallPreviewResult, InstallPhase, InstallResultStatus, InstallIncoming, InstallOutgoing, } from './install/types.js';
 export { INSTALL_ERROR_CODES } from './install/types.js';

package/dist/types.js

@@ -9,4 +9,15 @@ export const DEFAULT_RECONNECT = {
     maxDelayMs: 30000,
     jitterFactor: 0.3,
 };
+/**
+ * Non-fatal error emitted when Ed25519 identity exchange fails.
+ * Connection still works — only identity-based reconnect is unavailable.
+ * Consumers (e.g. setup CLI) can check `instanceof` to avoid treating this as fatal.
+ */
+export class IdentityExchangeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityExchangeError';
+    }
+}
 export { INSTALL_ERROR_CODES } from './install/types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echoclaw-relay-agent",
-  "version": "0.14.0",
+  "version": "0.15.2",
   "description": "EchoClaw Relay Connection — E2E encrypted relay transport, pairing, and session management",
   "type": "module",
   "main": "./dist/index.js",