echoclaw-relay-agent 0.6.1 → 0.7.0

package/dist/RelayClient.d.ts

@@ -1,19 +1,24 @@
 /**
  * RelayClient — Desktop client entry point.
  *
- * Connects to an existing RelayAgent via 4-digit pairing code.
- * All communication is E2E encrypted through relay.echoclaw.me.
+ * Connects to relay.echoclaw.me for E2E encrypted communication with agent.
  *
- * Pair once, connect forever:
- *   - First run: `client.connect('1234')` — pairs with code, persists session
+ * Pairing flow (desktop initiates):
+ *   1. `client.connect()` — connects to relay, server assigns 4-digit code
+ *   2. Client emits 'pairing_code' event — UI displays code for user
+ *   3. User copies code to agent machine → agent connects with code
+ *   4. ECDH key exchange completes → client emits 'paired' + 'connected'
+ *
+ * Session lifecycle:
+ *   - First run: `client.connect()` — new pairing, gets code, waits for agent
  *   - Subsequent runs: `client.connect()` — auto-resumes from saved session
- *   - New pairing: `client.connect('5678')` — overwrites old session
+ *   - Force new pairing: `client.clearSession()` then `client.connect()`
  *
  * Usage:
  *   const client = new RelayClient({ relayServer: 'wss://relay.echoclaw.me' });
- *   await client.connect('1234');   // first time: pair with code
- *   // ... later, on app restart:
- *   await client.connect();          // auto-resume saved session
+ *   client.on('pairing_code', (code) => showCodeInUI(code));
+ *   client.on('paired', () => console.log('Agent connected!'));
+ *   await client.connect();
  *   client.on('message', (payload) => console.log(payload));
  *   await client.send({ type: 'chat', text: 'Hello' });
  *   await client.disconnect();
@@ -37,11 +42,15 @@ export declare class RelayClient extends EventEmitter {
     /** Current connection status. */
     get status(): ClientStatus;
     /**
-     * Connect to a relay agent.
-     * @param pairingCode - 4-digit code for new pairing. Omit to resume saved session.
+     * Connect to relay server.
+     *
+     * - No saved session: initiates new pairing. Emits 'pairing_code' with 4-digit code
+     *   for user to give to agent. Resolves when agent connects and ECDH completes.
+     * - Saved session exists: auto-resumes with forward-secret re-keying.
+     *
      * Idempotent: calling while already connecting/connected is a no-op.
      */
-    connect(pairingCode?: string): Promise<void>;
+    connect(): Promise<void>;
     /**
      * Send an encrypted payload to the connected agent.
      */

package/dist/RelayClient.js

@@ -1,19 +1,24 @@
 /**
  * RelayClient — Desktop client entry point.
  *
- * Connects to an existing RelayAgent via 4-digit pairing code.
- * All communication is E2E encrypted through relay.echoclaw.me.
+ * Connects to relay.echoclaw.me for E2E encrypted communication with agent.
  *
- * Pair once, connect forever:
- *   - First run: `client.connect('1234')` — pairs with code, persists session
+ * Pairing flow (desktop initiates):
+ *   1. `client.connect()` — connects to relay, server assigns 4-digit code
+ *   2. Client emits 'pairing_code' event — UI displays code for user
+ *   3. User copies code to agent machine → agent connects with code
+ *   4. ECDH key exchange completes → client emits 'paired' + 'connected'
+ *
+ * Session lifecycle:
+ *   - First run: `client.connect()` — new pairing, gets code, waits for agent
  *   - Subsequent runs: `client.connect()` — auto-resumes from saved session
- *   - New pairing: `client.connect('5678')` — overwrites old session
+ *   - Force new pairing: `client.clearSession()` then `client.connect()`
  *
  * Usage:
  *   const client = new RelayClient({ relayServer: 'wss://relay.echoclaw.me' });
- *   await client.connect('1234');   // first time: pair with code
- *   // ... later, on app restart:
- *   await client.connect();          // auto-resume saved session
+ *   client.on('pairing_code', (code) => showCodeInUI(code));
+ *   client.on('paired', () => console.log('Agent connected!'));
+ *   await client.connect();
  *   client.on('message', (payload) => console.log(payload));
  *   await client.send({ type: 'chat', text: 'Hello' });
  *   await client.disconnect();
@@ -106,11 +111,15 @@ export class RelayClient extends EventEmitter {
         return this._status;
     }
     /**
-     * Connect to a relay agent.
-     * @param pairingCode - 4-digit code for new pairing. Omit to resume saved session.
+     * Connect to relay server.
+     *
+     * - No saved session: initiates new pairing. Emits 'pairing_code' with 4-digit code
+     *   for user to give to agent. Resolves when agent connects and ECDH completes.
+     * - Saved session exists: auto-resumes with forward-secret re-keying.
+     *
      * Idempotent: calling while already connecting/connected is a no-op.
      */
-    async connect(pairingCode) {
+    async connect() {
         // Idempotent guard
         if (this._connecting || this._status === 'connected')
             return;
@@ -123,19 +132,14 @@ export class RelayClient extends EventEmitter {
         }
         this.frameCrypto = null;
         try {
-            if (pairingCode) {
-                // New pairing — overwrite any existing session
-                await this.freshPairing(pairingCode);
+            // Try to resume saved session first
+            const session = await this.sessionStore.load();
+            if (session) {
+                await this.resumeSession(session);
             }
             else {
-                // Try to resume saved session
-                const session = await this.sessionStore.load();
-                if (session) {
-                    await this.resumeSession(session);
-                }
-                else {
-                    throw new Error('No saved session found. Provide a pairing code: client.connect("1234")');
-                }
+                // No saved session — initiate new pairing (desktop gets code from server)
+                await this.freshPairing();
             }
         }
         finally {
@@ -186,7 +190,7 @@ export class RelayClient extends EventEmitter {
         await this.sessionStore.clear();
     }
     // ── Private ────────────────────────────────────────────────
-    async freshPairing(code) {
+    async freshPairing() {
         this.setStatus('connecting');
         const clientUrl = `${this.config.relayServer}/client/connect`;
         this.transport = new RelayTransport({
@@ -196,8 +200,13 @@ export class RelayClient extends EventEmitter {
         });
         this.setupTransportEvents();
         this.transport.connect();
+        // Initiator mode: no code — PairingProtocol gets code from server HELLO
         const pairing = new PairingProtocol(this.transport);
-        const result = await pairing.pairAsClient(code);
+        pairing.on('pairing_code', (code) => {
+            this.pairingCode = code;
+            this.emit('pairing_code', code);
+        });
+        const result = await pairing.pairAsClient(); // no code = initiator mode
         await this.onPaired(result, 'paired');
     }
     async resumeSession(session) {

package/dist/relay/PairingProtocol.d.ts

@@ -2,17 +2,15 @@
  * PairingProtocol — E2E key exchange via pairing code.
  *
  * Agent side:
- *   1. Register with relay server → receive session_id + pairing_code (4 digits)
+ *   1. Connect with ?code=XXXX → receive HELLO with session_id
  *   2. Send HELLO with agent's X25519 public key
  *   3. Wait for client's HELLO with their public key
  *   4. ECDH + HKDF (with pairing code as salt) → sessionKey
- *   5. Persist session for future auto-resume
  *
- * Client side:
- *   1. Connect with ?code=<4-digit-code>
- *   2. Send HELLO with client's X25519 public key
- *   3. Receive agent's HELLO with their public key
- *   4. ECDH + HKDF → sessionKey
+ * Client (desktop) side — two modes:
+ *   A. Initiator (no code): connect /client/connect → server HELLO gives code →
+ *      emit 'pairing_code' → send pubkey → wait for agent HELLO → ECDH
+ *   B. With code (resume): connect with known code → send pubkey → ECDH
  *
  * Pairing code is mixed into HKDF salt for MITM protection.
  */
@@ -33,8 +31,14 @@ export declare class PairingProtocol extends EventEmitter {
      */
     pairAsAgent(inputCode?: string): Promise<PairingResult>;
     /**
-     * Client-side pairing: connect with pairing code, exchange keys with agent.
-     * Returns the E2E session key.
+     * Client-side pairing: exchange keys with agent via relay server.
+     *
+     * Two modes:
+     * - **Initiator** (no code): Desktop connects first, server assigns code.
+     *   Emits 'pairing_code' so UI can display it. Waits for agent to join.
+     * - **With code** (resume): Desktop already knows the code, sends pubkey immediately.
+     *
+     * @param pairingCode - Known code for HKDF. Omit for initiator mode.
      */
-    pairAsClient(pairingCode: string): Promise<PairingResult>;
+    pairAsClient(pairingCode?: string): Promise<PairingResult>;
 }

package/dist/relay/PairingProtocol.js

@@ -2,17 +2,15 @@
  * PairingProtocol — E2E key exchange via pairing code.
  *
  * Agent side:
- *   1. Register with relay server → receive session_id + pairing_code (4 digits)
+ *   1. Connect with ?code=XXXX → receive HELLO with session_id
  *   2. Send HELLO with agent's X25519 public key
  *   3. Wait for client's HELLO with their public key
  *   4. ECDH + HKDF (with pairing code as salt) → sessionKey
- *   5. Persist session for future auto-resume
  *
- * Client side:
- *   1. Connect with ?code=<4-digit-code>
- *   2. Send HELLO with client's X25519 public key
- *   3. Receive agent's HELLO with their public key
- *   4. ECDH + HKDF → sessionKey
+ * Client (desktop) side — two modes:
+ *   A. Initiator (no code): connect /client/connect → server HELLO gives code →
+ *      emit 'pairing_code' → send pubkey → wait for agent HELLO → ECDH
+ *   B. With code (resume): connect with known code → send pubkey → ECDH
  *
  * Pairing code is mixed into HKDF salt for MITM protection.
  */
@@ -93,40 +91,72 @@ export class PairingProtocol extends EventEmitter {
         });
     }
     /**
-     * Client-side pairing: connect with pairing code, exchange keys with agent.
-     * Returns the E2E session key.
+     * Client-side pairing: exchange keys with agent via relay server.
+     *
+     * Two modes:
+     * - **Initiator** (no code): Desktop connects first, server assigns code.
+     *   Emits 'pairing_code' so UI can display it. Waits for agent to join.
+     * - **With code** (resume): Desktop already knows the code, sends pubkey immediately.
+     *
+     * @param pairingCode - Known code for HKDF. Omit for initiator mode.
      */
     async pairAsClient(pairingCode) {
         this.keyPair = await generateKeyPair();
+        const isInitiator = !pairingCode;
         return new Promise((resolve, reject) => {
             let sessionId = '';
+            let code = pairingCode || '';
             let resolved = false;
             let sentHello = false;
+            // Initiator waits up to 10 min for agent; with-code waits 30s
+            const timeoutMs = isInitiator ? 10 * 60 * 1000 : 30000;
+            const timeoutMsg = isInitiator
+                ? 'Pairing timeout: no agent connected within 10 minutes'
+                : 'Pairing timeout: agent not responding within 30 seconds';
             const timeout = setTimeout(() => {
                 if (!resolved) {
                     cleanup();
-                    reject(new Error('Pairing timeout: agent not responding within 30 seconds'));
+                    reject(new Error(timeoutMsg));
                 }
-            }, 30000);
+            }, timeoutMs);
             const cleanup = () => {
                 resolved = true;
                 clearTimeout(timeout);
                 this.transport.removeListener('message', onMessage);
                 this.transport.removeListener('open', onOpen);
             };
-            const onOpen = () => {
+            const sendPubkey = () => {
                 if (sentHello)
                     return;
                 sentHello = true;
-                // Send our public key immediately
-                this.transport.send(this.transport.buildMessage('HELLO', '', 'desktop', {
+                this.transport.send(this.transport.buildMessage('HELLO', sessionId, 'desktop', {
                     pubkey: toBase64(this.keyPair.publicKey),
                 }));
             };
+            const onOpen = () => {
+                // With known code: send pubkey immediately on connect
+                if (!isInitiator) {
+                    sendPubkey();
+                }
+                // Initiator mode: wait for server HELLO to get code first
+            };
             const onMessage = async (msg) => {
                 if (resolved)
                     return;
-                // Track session_id from server
+                // Server HELLO — provides session_id (and code in initiator mode)
+                if (msg.type === 'HELLO' && msg.sender_role === 'server') {
+                    if (msg.session_id)
+                        sessionId = msg.session_id;
+                    if (msg.payload && isInitiator) {
+                        code = msg.payload;
+                        this.emit('pairing_code', code);
+                    }
+                    // In initiator mode, send pubkey after receiving server HELLO
+                    if (isInitiator) {
+                        sendPubkey();
+                    }
+                }
+                // Track session_id from any message
                 if (msg.session_id && !sessionId) {
                     sessionId = msg.session_id;
                 }
@@ -134,15 +164,17 @@ export class PairingProtocol extends EventEmitter {
                 if (msg.type === 'HELLO' && msg.pubkey && msg.sender_role === 'agent') {
                     try {
                         const theirPub = fromBase64(msg.pubkey);
-                        const sessionKey = await completeHandshake(this.keyPair.privateKey, theirPub, pairingCode);
+                        const sessionKey = await completeHandshake(this.keyPair.privateKey, theirPub, code || undefined);
                         cleanup();
-                        resolve({ sessionKey, sessionId, pairingCode });
+                        resolve({ sessionKey, sessionId, pairingCode: code });
                     }
                     catch (err) {
                         cleanup();
                         reject(err);
                     }
                 }
+                // PAIRED notification from server — agent has joined (initiator mode)
+                // No action needed, just wait for agent's HELLO with pubkey
                 // Error from server
                 if (msg.type === 'CLOSE') {
                     cleanup();
@@ -154,8 +186,8 @@ export class PairingProtocol extends EventEmitter {
             };
             this.transport.on('message', onMessage);
             this.transport.on('open', onOpen);
-            // If already connected, send HELLO now
-            if (this.transport.isConnected && !sentHello) {
+            // If already connected, trigger onOpen
+            if (this.transport.isConnected) {
                 onOpen();
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echoclaw-relay-agent",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "EchoClaw Relay Connection — E2E encrypted relay transport, pairing, and session management",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,17 +17,17 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts"
+  },
   "dependencies": {
-    "ws": "^8.18.0",
-    "echoclaw-crypto": "0.2.0"
+    "echoclaw-crypto": "workspace:*",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.10",
     "tsx": "^4.7.0",
     "typescript": "^5.7.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/cli.ts"
   }
-}
+}