echoclaw-relay-agent 0.4.1 → 0.5.0

package/dist/RelayAgent.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RelayAgent — Agent-side entry point.
+ *
+ * Runs on the OpenClaw machine. Connects to relay.echoclaw.me,
+ * waits for client pairing, then enters E2E encrypted communication.
+ *
+ * Pair once, connect forever:
+ *   - First run: `agent.start('1234')` — pairs with code, persists session
+ *   - Subsequent runs: `agent.start()` — auto-resumes from saved session
+ *   - New pairing: `agent.start('5678')` — overwrites old session
+ *
+ * Usage:
+ *   const agent = new RelayAgent({ relayServer: 'wss://relay.echoclaw.me' });
+ *   await agent.start('1234');
+ *   agent.on('message', (payload) => console.log(payload));
+ *   await agent.send({ type: 'greeting', text: 'Hello from OpenClaw' });
+ */
+import { EventEmitter } from 'node:events';
+import type { RelayAgentConfig, ClientStatus } from './types.js';
+export declare class RelayAgent extends EventEmitter {
+    private transport;
+    private pairing;
+    private sessionStore;
+    private frameCrypto;
+    private sessionKey;
+    private sessionId;
+    private pairingCode;
+    private _status;
+    private _dataHandler;
+    private _stopped;
+    private _starting;
+    private readonly config;
+    private readonly subscribers;
+    private gatewayManager;
+    constructor(config: RelayAgentConfig);
+    /** Current connection status. */
+    get status(): ClientStatus;
+    /**
+     * Start the relay agent.
+     * @param pairingCode - 4-digit code for new pairing. Omit to resume saved session.
+     */
+    start(pairingCode?: string): Promise<void>;
+    /**
+     * Send an encrypted payload to the connected client.
+     */
+    send(payload: object): Promise<void>;
+    /**
+     * Subscribe to decrypted messages from the client.
+     * Returns an unsubscribe function.
+     */
+    subscribe(event: string, cb: (payload: unknown) => void): () => void;
+    /** Gracefully stop the agent. */
+    stop(): Promise<void>;
+    private freshPairing;
+    private resumeSession;
+    private onPaired;
+    private setupDataHandler;
+    private setupTransportEvents;
+    private setStatus;
+}

package/dist/RelayAgent.js

@@ -0,0 +1,370 @@
+/**
+ * RelayAgent — Agent-side entry point.
+ *
+ * Runs on the OpenClaw machine. Connects to relay.echoclaw.me,
+ * waits for client pairing, then enters E2E encrypted communication.
+ *
+ * Pair once, connect forever:
+ *   - First run: `agent.start('1234')` — pairs with code, persists session
+ *   - Subsequent runs: `agent.start()` — auto-resumes from saved session
+ *   - New pairing: `agent.start('5678')` — overwrites old session
+ *
+ * Usage:
+ *   const agent = new RelayAgent({ relayServer: 'wss://relay.echoclaw.me' });
+ *   await agent.start('1234');
+ *   agent.on('message', (payload) => console.log(payload));
+ *   await agent.send({ type: 'greeting', text: 'Hello from OpenClaw' });
+ */
+import { EventEmitter } from 'node:events';
+// @echoclaw/crypto used via FrameCrypto and PairingProtocol
+import { RelayTransport } from './relay/RelayTransport.js';
+import { PairingProtocol } from './relay/PairingProtocol.js';
+import { SessionStore } from './relay/SessionStore.js';
+import { FrameCrypto } from './crypto/FrameCrypto.js';
+import { GatewayManager } from './gateway/GatewayManager.js';
+export class RelayAgent extends EventEmitter {
+    constructor(config) {
+        super();
+        Object.defineProperty(this, "transport", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "pairing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "sessionStore", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "frameCrypto", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "sessionKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "sessionId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        Object.defineProperty(this, "pairingCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        Object.defineProperty(this, "_status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'disconnected'
+        });
+        Object.defineProperty(this, "_dataHandler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_stopped", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_starting", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "subscribers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "gatewayManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.config = config;
+        this.sessionStore = new SessionStore(config.sessionPath);
+        // V2: Create gateway manager if enabled
+        if (config.gateway?.enabled) {
+            this.gatewayManager = new GatewayManager(config.gateway, config.sessionPath);
+            // Forward gateway events
+            this.gatewayManager.on('bridge_up', (info) => this.emit('bridge_up', info));
+            this.gatewayManager.on('bridge_down', (info) => this.emit('bridge_down', info));
+            this.gatewayManager.on('bridge_recovered', (info) => this.emit('bridge_recovered', info));
+            this.gatewayManager.on('tunnel_request', (info) => this.emit('tunnel_request', info));
+            this.gatewayManager.on('tunnel_response', (info) => this.emit('tunnel_response', info));
+            this.gatewayManager.on('tunnel_error', (info) => this.emit('tunnel_error', info));
+        }
+    }
+    /** Current connection status. */
+    get status() {
+        return this._status;
+    }
+    /**
+     * Start the relay agent.
+     * @param pairingCode - 4-digit code for new pairing. Omit to resume saved session.
+     */
+    async start(pairingCode) {
+        if (this._starting)
+            return;
+        this._starting = true;
+        this._stopped = false;
+        // Teardown previous transport before starting new
+        if (this.transport) {
+            this.transport.disconnect();
+            this.transport = null;
+        }
+        this.frameCrypto = null;
+        try {
+            if (pairingCode) {
+                // New pairing — overwrite any existing session
+                await this.freshPairing(pairingCode);
+            }
+            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: agent.start("1234")');
+                }
+            }
+        }
+        finally {
+            this._starting = false;
+        }
+    }
+    /**
+     * Send an encrypted payload to the connected client.
+     */
+    async send(payload) {
+        if (!this.sessionKey || !this.transport?.isConnected) {
+            throw new Error('Not connected. Call start() first.');
+        }
+        const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+        const frame = await this.frameCrypto.encrypt(plaintext);
+        const wire = FrameCrypto.frameToWire(frame);
+        this.transport.send(this.transport.buildMessage('DATA', this.sessionId, 'agent', {
+            iv: wire.iv,
+            payload: wire.payload,
+            seq: wire.seq,
+        }));
+    }
+    /**
+     * Subscribe to decrypted messages from the client.
+     * Returns an unsubscribe function.
+     */
+    subscribe(event, cb) {
+        if (!this.subscribers.has(event)) {
+            this.subscribers.set(event, new Set());
+        }
+        this.subscribers.get(event).add(cb);
+        return () => {
+            this.subscribers.get(event)?.delete(cb);
+        };
+    }
+    /** Gracefully stop the agent. */
+    async stop() {
+        this._stopped = true;
+        this.gatewayManager?.stop();
+        this.transport?.disconnect();
+        this.transport = null;
+        this.sessionKey = null;
+        this.frameCrypto = null;
+        this.setStatus('disconnected');
+    }
+    // ── Private ────────────────────────────────────────────────
+    async freshPairing(code) {
+        this.setStatus('connecting');
+        // Connect to relay server as agent
+        const agentUrl = `${this.config.relayServer}/agent/connect`;
+        this.transport = new RelayTransport({
+            url: agentUrl,
+            reconnect: this.config.reconnect,
+            pingIntervalMs: this.config.pingIntervalMs,
+        });
+        this.setupTransportEvents();
+        this.transport.connect();
+        // Run pairing protocol
+        this.pairing = new PairingProtocol(this.transport);
+        this.pairing.on('pairing_code', (receivedCode) => {
+            this.pairingCode = receivedCode;
+            this.emit('pairing_code', receivedCode);
+        });
+        const result = await this.pairing.pairAsAgent();
+        await this.onPaired(result);
+    }
+    async resumeSession(session) {
+        this.setStatus('connecting');
+        this.pairingCode = session.pairingCode;
+        this.sessionId = session.relaySessionId;
+        // Reconnect with session resume
+        const resumeUrl = `${this.config.relayServer}/agent/connect?resume=${session.relaySessionId}`;
+        this.transport = new RelayTransport({
+            url: resumeUrl,
+            reconnect: this.config.reconnect,
+            pingIntervalMs: this.config.pingIntervalMs,
+        });
+        this.setupTransportEvents();
+        // V1: Re-do key exchange on resume since session keys are ephemeral (not persisted).
+        // The relay server uses the session ID to reconnect the same agent-client pair,
+        // but a fresh ECDH handshake establishes new forward-secret session keys.
+        // V2 may add session key persistence for instant resume without re-keying.
+        this.pairing = new PairingProtocol(this.transport);
+        this.transport.connect();
+        try {
+            const result = await this.pairing.pairAsAgent();
+            await this.onPaired(result);
+        }
+        catch (err) {
+            // Resume failed — clear stale session to prevent infinite retry loop
+            this.transport?.disconnect();
+            this.transport = null;
+            this.frameCrypto = null;
+            this.setStatus('disconnected');
+            await this.sessionStore.clear();
+            throw err;
+        }
+    }
+    async onPaired(result) {
+        this.sessionKey = result.sessionKey;
+        this.sessionId = result.sessionId;
+        this.pairingCode = result.pairingCode;
+        this.frameCrypto = new FrameCrypto(result.sessionKey);
+        // Persist session for future auto-resume
+        await this.sessionStore.save({
+            pairingCode: result.pairingCode,
+            relaySessionId: result.sessionId,
+            lastConnected: new Date().toISOString(),
+        });
+        this.setupDataHandler();
+        this.setStatus('connected');
+        this.emit('paired', {
+            pairingCode: result.pairingCode,
+            sessionId: result.sessionId,
+        });
+        this.emit('connected');
+        // V2: Start gateway (non-blocking — failure doesn't affect connection)
+        if (this.gatewayManager) {
+            this.gatewayManager.start().catch((err) => {
+                this.emit('error', new Error(`Gateway start failed: ${err instanceof Error ? err.message : err}`));
+            });
+        }
+    }
+    setupDataHandler() {
+        if (!this.transport)
+            return;
+        // Remove previous data handler to prevent listener accumulation on reconnect
+        if (this._dataHandler) {
+            this.transport.removeListener('message', this._dataHandler);
+        }
+        this._dataHandler = async (msg) => {
+            if (msg.type !== 'DATA' || !msg.iv || !msg.payload || !this.frameCrypto)
+                return;
+            try {
+                if (typeof msg.seq !== 'number') {
+                    this.emit('error', new Error('DATA message missing seq field'));
+                    return;
+                }
+                const frame = FrameCrypto.wireToFrame({
+                    iv: msg.iv,
+                    payload: msg.payload,
+                    seq: msg.seq,
+                });
+                const plainBytes = await this.frameCrypto.decrypt(frame);
+                const payload = JSON.parse(new TextDecoder().decode(plainBytes));
+                // V2: Route TunnelPayload requests to gateway if enabled
+                if (this.gatewayManager && payload.request_id && payload.direction === 'request') {
+                    if (payload.method === 'CANCEL') {
+                        this.gatewayManager.handleCancel(payload.request_id);
+                        return;
+                    }
+                    this.gatewayManager.handleRequest(payload, async (response) => {
+                        try {
+                            await this.send(response);
+                        }
+                        catch { /* send may fail if disconnected */ }
+                    });
+                    return;
+                }
+                this.emit('message', payload);
+                // Notify typed subscribers
+                const eventType = payload?.type ?? 'message';
+                this.subscribers.get(eventType)?.forEach(cb => cb(payload));
+                this.subscribers.get('*')?.forEach(cb => cb(payload));
+            }
+            catch (err) {
+                this.emit('error', err);
+            }
+        };
+        this.transport.on('message', this._dataHandler);
+    }
+    setupTransportEvents() {
+        if (!this.transport)
+            return;
+        this.transport.on('close', () => {
+            if (!this._stopped) {
+                this.setStatus('reconnecting');
+                this.emit('disconnected', { code: 0, reason: 'transport closed' });
+                // V2: Notify gateway of disconnect (starts grace period)
+                this.gatewayManager?.onDisconnected();
+            }
+        });
+        this.transport.on('reconnecting', (info) => {
+            this.setStatus('reconnecting');
+            this.emit('reconnecting', info);
+        });
+        this.transport.on('error', (err) => {
+            this.emit('error', err);
+        });
+        this.transport.on('open', () => {
+            if (this.sessionKey) {
+                this.setStatus('connected');
+                this.emit('connected');
+                // V2: Reattach gateway callbacks after reconnect
+                if (this.gatewayManager) {
+                    this.gatewayManager.onReconnected(async (r) => {
+                        try {
+                            await this.send(r);
+                        }
+                        catch { /* send may fail */ }
+                    });
+                }
+            }
+        });
+    }
+    setStatus(status) {
+        if (this._status !== status) {
+            this._status = status;
+            this.emit('status', status);
+        }
+    }
+}

package/dist/RelayClient.d.ts

@@ -0,0 +1,64 @@
+/**
+ * RelayClient — Desktop client entry point.
+ *
+ * Connects to an existing RelayAgent via 4-digit pairing code.
+ * All communication is E2E encrypted through relay.echoclaw.me.
+ *
+ * Pair once, connect forever:
+ *   - First run: `client.connect('1234')` — pairs with code, persists session
+ *   - Subsequent runs: `client.connect()` — auto-resumes from saved session
+ *   - New pairing: `client.connect('5678')` — overwrites old session
+ *
+ * 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('message', (payload) => console.log(payload));
+ *   await client.send({ type: 'chat', text: 'Hello' });
+ *   await client.disconnect();
+ */
+import { EventEmitter } from 'node:events';
+import type { RelayClientConfig, ClientStatus } from './types.js';
+export declare class RelayClient extends EventEmitter {
+    private transport;
+    private frameCrypto;
+    private sessionKey;
+    private sessionId;
+    private pairingCode;
+    private _status;
+    private _connecting;
+    private _stopped;
+    private readonly config;
+    private readonly sessionStore;
+    private readonly subscribers;
+    private _dataHandler;
+    constructor(config: RelayClientConfig);
+    /** Current connection status. */
+    get status(): ClientStatus;
+    /**
+     * Connect to a relay agent.
+     * @param pairingCode - 4-digit code for new pairing. Omit to resume saved session.
+     * Idempotent: calling while already connecting/connected is a no-op.
+     */
+    connect(pairingCode?: string): Promise<void>;
+    /**
+     * Send an encrypted payload to the connected agent.
+     */
+    send(payload: object): Promise<void>;
+    /**
+     * Subscribe to decrypted messages from the agent.
+     * Returns an unsubscribe function.
+     */
+    subscribe(event: string, cb: (payload: unknown) => void): () => void;
+    /** Disconnect from the relay. */
+    disconnect(): Promise<void>;
+    /** Clear saved session, forcing fresh pairing on next connect(). */
+    clearSession(): Promise<void>;
+    private freshPairing;
+    private resumeSession;
+    private onPaired;
+    private setupDataHandler;
+    private setupTransportEvents;
+    private setStatus;
+}