echoclaw-relay-agent 0.1.0

package/dist/main.js

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/relay/client.ts
+var import_ws = __toESM(require("ws"));
+
+// ../../packages/crypto/src/x25519.ts
+var subtle = globalThis.crypto.subtle;
+async function generateKeyPair() {
+  const keyPair2 = await subtle.generateKey(
+    { name: "X25519" },
+    false,
+    // non-extractable: private key cannot be exported
+    ["deriveBits"]
+  );
+  const rawPub = await subtle.exportKey("raw", keyPair2.publicKey);
+  return {
+    publicKey: new Uint8Array(rawPub),
+    privateKey: keyPair2.privateKey
+  };
+}
+async function computeSharedSecret(myPrivateKey, theirPublicKeyRaw) {
+  const theirPublicKey = await subtle.importKey(
+    "raw",
+    theirPublicKeyRaw,
+    { name: "X25519" },
+    false,
+    []
+  );
+  const sharedBits = await subtle.deriveBits(
+    { name: "X25519", public: theirPublicKey },
+    myPrivateKey,
+    256
+    // 32 bytes
+  );
+  return new Uint8Array(sharedBits);
+}
+
+// ../../packages/crypto/src/hkdf.ts
+var subtle2 = globalThis.crypto.subtle;
+var PROTOCOL_SALT = new TextEncoder().encode("echoclaw-relay-v1");
+var INFO_PREFIX = "echoclaw-e2e-";
+async function deriveSessionKey(sharedSecret, pairingCode2) {
+  const hkdfKey = await subtle2.importKey(
+    "raw",
+    sharedSecret,
+    "HKDF",
+    false,
+    ["deriveKey"]
+  );
+  const info = new TextEncoder().encode(
+    pairingCode2 ? `${INFO_PREFIX}${pairingCode2}` : INFO_PREFIX
+  );
+  return subtle2.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: PROTOCOL_SALT,
+      info
+    },
+    hkdfKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    // non-extractable
+    ["encrypt", "decrypt"]
+  );
+}
+
+// ../../packages/crypto/src/aes-gcm.ts
+var subtle3 = globalThis.crypto.subtle;
+var IV_LENGTH = 12;
+async function encrypt(key, plaintext) {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const ciphertext = await subtle3.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    plaintext
+  );
+  return {
+    iv,
+    ciphertext: new Uint8Array(ciphertext)
+  };
+}
+async function decrypt(key, iv, ciphertext) {
+  const plaintext = await subtle3.decrypt(
+    { name: "AES-GCM", iv },
+    key,
+    ciphertext
+  );
+  return new Uint8Array(plaintext);
+}
+
+// ../../packages/crypto/src/index.ts
+async function completeHandshake(myPrivateKey, theirPublicKey, pairingCode2) {
+  const shared = await computeSharedSecret(myPrivateKey, theirPublicKey);
+  return deriveSessionKey(shared, pairingCode2);
+}
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// src/relay/reconnect.ts
+var MIN_DELAY_MS = 1e3;
+var MAX_DELAY_MS = 3e4;
+var JITTER_FACTOR = 0.3;
+function createReconnectController() {
+  const ctrl = {
+    state: "disconnected",
+    attempt: 0,
+    setState(s) {
+      ctrl.state = s;
+      if (s === "connected" || s === "paired") {
+        ctrl.attempt = 0;
+      }
+    },
+    nextDelay() {
+      const base = Math.min(MIN_DELAY_MS * 2 ** ctrl.attempt, MAX_DELAY_MS);
+      const jitter = base * JITTER_FACTOR * (Math.random() * 2 - 1);
+      ctrl.attempt++;
+      return Math.max(MIN_DELAY_MS, Math.round(base + jitter));
+    },
+    reset() {
+      ctrl.state = "disconnected";
+      ctrl.attempt = 0;
+    }
+  };
+  return ctrl;
+}
+
+// src/tunnel/http.ts
+async function forwardToBridge(bridgeUrl, request) {
+  const url = `${bridgeUrl}${request.path ?? "/"}`;
+  const method = request.method ?? "GET";
+  try {
+    const headers = {
+      "Content-Type": "application/json",
+      ...request.headers
+    };
+    const fetchOpts = {
+      method,
+      headers
+    };
+    if (request.body && ["POST", "PUT", "PATCH"].includes(method)) {
+      fetchOpts.body = Buffer.from(request.body, "base64").toString("utf-8");
+    }
+    const res = await fetch(url, fetchOpts);
+    const bodyText = await res.text();
+    const responseHeaders = {};
+    const ct = res.headers.get("content-type");
+    if (ct) responseHeaders["content-type"] = ct;
+    return {
+      request_id: request.request_id,
+      direction: "response",
+      status: res.status,
+      headers: responseHeaders,
+      body: Buffer.from(bodyText, "utf-8").toString("base64"),
+      final: true
+    };
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : "Bridge unreachable";
+    console.error(`[tunnel] Failed to reach ${url}: ${errMsg}`);
+    return {
+      request_id: request.request_id,
+      direction: "response",
+      status: 502,
+      body: Buffer.from(JSON.stringify({ error: errMsg }), "utf-8").toString("base64"),
+      final: true
+    };
+  }
+}
+
+// src/relay/client.ts
+var ws = null;
+var keyPair = null;
+var sessionKey = null;
+var sessionId = null;
+var pairingCode = null;
+var reconnect;
+var config;
+var _stopped = false;
+async function startRelayClient(cfg) {
+  config = cfg;
+  _stopped = false;
+  reconnect = createReconnectController();
+  keyPair = await generateKeyPair();
+  console.log("[relay-agent] X25519 key pair generated");
+  connect();
+}
+function stopRelayClient() {
+  _stopped = true;
+  if (ws) {
+    ws.close(1e3, "agent shutdown");
+    ws = null;
+  }
+  sessionKey = null;
+  keyPair = null;
+  reconnect?.reset();
+}
+function connect() {
+  if (_stopped) return;
+  reconnect.setState("connecting");
+  const url = config.sessionId ? `${config.relayUrl}?resume=${config.sessionId}` : config.relayUrl;
+  console.log(`[relay-agent] Connecting to ${url}...`);
+  ws = new import_ws.default(url);
+  ws.on("open", () => {
+    reconnect.setState("connected");
+    console.log("[relay-agent] Connected to relay server");
+    const registerMsg = {
+      version: 1,
+      session_id: sessionId ?? "",
+      msg_id: makeId(),
+      type: "HELLO",
+      pubkey: toBase64(keyPair.publicKey),
+      sender_role: "agent",
+      timestamp: Date.now()
+    };
+    ws.send(JSON.stringify(registerMsg));
+  });
+  ws.on("message", (data) => {
+    handleMessage(data.toString());
+  });
+  ws.on("close", (code, reason) => {
+    console.log(`[relay-agent] Disconnected (code=${code}, reason=${reason.toString()})`);
+    sessionKey = null;
+    scheduleReconnect();
+  });
+  ws.on("error", (err) => {
+    console.error(`[relay-agent] WebSocket error: ${err.message}`);
+  });
+}
+function scheduleReconnect() {
+  if (_stopped) return;
+  reconnect.setState("disconnected");
+  const delay = reconnect.nextDelay();
+  console.log(`[relay-agent] Reconnecting in ${delay}ms (attempt ${reconnect.attempt})...`);
+  setTimeout(connect, delay);
+}
+async function handleMessage(raw) {
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    console.warn("[relay-agent] Invalid JSON from relay server");
+    return;
+  }
+  switch (msg.type) {
+    case "HELLO":
+      await handleHello(msg);
+      break;
+    case "DATA":
+      await handleData(msg);
+      break;
+    case "PING":
+      sendRaw({ version: 1, session_id: msg.session_id, msg_id: makeId(), type: "PING", sender_role: "agent" });
+      break;
+    case "CLOSE":
+      console.log("[relay-agent] Session closed by peer");
+      sessionKey = null;
+      reconnect.setState("connected");
+      break;
+  }
+}
+async function handleHello(msg) {
+  if (msg.session_id && !sessionId) {
+    sessionId = msg.session_id;
+    if (msg.payload) {
+      pairingCode = msg.payload;
+      console.log("");
+      console.log("  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557");
+      console.log(`  \u2551  Pairing Code:  ${pairingCode.padEnd(24)}\u2551`);
+      console.log("  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D");
+      console.log("");
+      console.log("  Enter this code in your EchoClaw desktop client to connect.");
+      console.log("");
+    }
+  }
+  if (msg.pubkey && msg.sender_role === "desktop") {
+    console.log("[relay-agent] Received desktop public key, completing handshake...");
+    const theirPubKey = fromBase64(msg.pubkey);
+    sessionKey = await completeHandshake(
+      keyPair.privateKey,
+      theirPubKey,
+      pairingCode ?? void 0
+    );
+    reconnect.setState("paired");
+    console.log("[relay-agent] \u2705 E2E encryption established \u2014 session paired");
+  }
+}
+async function handleData(msg) {
+  if (!sessionKey || !msg.iv || !msg.payload) {
+    console.warn("[relay-agent] Received DATA but no session key or missing fields");
+    return;
+  }
+  try {
+    const plainBytes = await decrypt(
+      sessionKey,
+      fromBase64(msg.iv),
+      fromBase64(msg.payload)
+    );
+    const tunnelPayload = JSON.parse(
+      new TextDecoder().decode(plainBytes)
+    );
+    if (tunnelPayload.direction !== "request") {
+      console.warn("[relay-agent] Unexpected payload direction:", tunnelPayload.direction);
+      return;
+    }
+    const response = await forwardToBridge(config.bridgeUrl, tunnelPayload);
+    const responseBytes = new TextEncoder().encode(JSON.stringify(response));
+    const encrypted = await encrypt(sessionKey, responseBytes);
+    const responseMsg = {
+      version: 1,
+      session_id: sessionId,
+      msg_id: makeId(),
+      type: "DATA",
+      iv: toBase64(encrypted.iv),
+      payload: toBase64(encrypted.ciphertext),
+      sender_role: "agent",
+      timestamp: Date.now()
+    };
+    sendRaw(responseMsg);
+  } catch (err) {
+    console.error("[relay-agent] Failed to process DATA message:", err.message);
+  }
+}
+var _counter = 0;
+function makeId() {
+  return `ra-${++_counter}-${Date.now().toString(36)}`;
+}
+function sendRaw(msg) {
+  if (ws?.readyState === import_ws.default.OPEN) {
+    ws.send(JSON.stringify(msg));
+  }
+}
+
+// src/main.ts
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {
+    relayUrl: "wss://relay.echoclaw.me/agent/connect",
+    bridgeUrl: "http://localhost:8013"
+  };
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--relay":
+      case "-r":
+        opts.relayUrl = args[++i] || opts.relayUrl;
+        break;
+      case "--bridge":
+      case "-b":
+        opts.bridgeUrl = args[++i] || opts.bridgeUrl;
+        break;
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+      case "--version":
+      case "-v":
+        console.log("echoclaw-relay-agent 0.1.0");
+        process.exit(0);
+      default:
+        if (args[i].startsWith("-")) {
+          console.error(`Unknown option: ${args[i]}`);
+          printHelp();
+          process.exit(1);
+        }
+    }
+  }
+  return opts;
+}
+function printHelp() {
+  console.log(`
+  EchoClaw Relay Agent \u2014 Connect OpenClaw to the cloud relay
+
+  USAGE
+    echoclaw-relay [options]
+
+  OPTIONS
+    --relay, -r <url>    Relay server WebSocket URL
+                         (default: wss://relay.echoclaw.me/agent/connect)
+
+    --bridge, -b <url>   Local OpenClaw bridge HTTP URL
+                         (default: http://localhost:8013)
+
+    --help, -h           Show this help message
+    --version, -v        Show version
+
+  EXAMPLES
+    echoclaw-relay
+    echoclaw-relay --bridge http://localhost:9000
+    echoclaw-relay --relay wss://my-relay.example.com/agent/connect
+
+  SECURITY
+    All communication is end-to-end encrypted (X25519 + AES-256-GCM).
+    The relay server cannot read your messages \u2014 it only forwards ciphertext.
+    Verify: https://github.com/echoclaw/relay-agent/tree/main/packages/crypto
+  `);
+}
+async function main() {
+  const opts = parseArgs();
+  console.log("");
+  console.log("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+  console.log("  \u2502        EchoClaw Relay Agent  v0.1.0       \u2502");
+  console.log("  \u2502   Open Source \xB7 Apache License 2.0        \u2502");
+  console.log("  \u2502   github.com/echoclaw/relay-agent         \u2502");
+  console.log("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+  console.log("");
+  console.log(`  Relay:  ${opts.relayUrl}`);
+  console.log(`  Bridge: ${opts.bridgeUrl}`);
+  console.log("");
+  try {
+    const healthRes = await fetch(`${opts.bridgeUrl}/health`, {
+      signal: AbortSignal.timeout(3e3)
+    });
+    if (healthRes.ok) {
+      console.log("  \u2705 Local bridge is reachable");
+    } else {
+      console.warn(`  \u26A0\uFE0F  Bridge returned HTTP ${healthRes.status} \u2014 starting anyway`);
+    }
+  } catch {
+    console.warn("  \u26A0\uFE0F  Cannot reach local bridge \u2014 will retry when messages arrive");
+  }
+  console.log("");
+  await startRelayClient({
+    relayUrl: opts.relayUrl,
+    bridgeUrl: opts.bridgeUrl
+  });
+}
+process.on("SIGINT", () => {
+  console.log("\n[relay-agent] Shutting down...");
+  stopRelayClient();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  console.log("\n[relay-agent] Terminated");
+  stopRelayClient();
+  process.exit(0);
+});
+main().catch((err) => {
+  console.error("[relay-agent] Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "echoclaw-relay-agent",
+  "version": "0.1.0",
+  "description": "EchoClaw Relay Agent — connects OpenClaw bridge to the EchoClaw Relay Server with E2E encryption",
+  "main": "./dist/main.js",
+  "bin": {
+    "echoclaw-relay-agent": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/main.ts",
+    "build": "node build.mjs",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@echoclaw/crypto": "workspace:*",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.27.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "echoclaw",
+    "relay",
+    "openclaw",
+    "e2e",
+    "encryption"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicekwell/EchoClaw.git"
+  }
+}