clawmatrix 0.1.22 → 0.2.0

package/src/peer-manager.ts

@@ -1,27 +1,46 @@
 import { EventEmitter } from "node:events";
+import path from "node:path";
+import { homedir, tmpdir } from "node:os";
 import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
 import { WebSocketServer, WebSocket as WsWebSocket } from "ws";
 import type { ClawMatrixConfig, PeerConfig } from "./config.ts";
 import { Connection } from "./connection.ts";
-import type { WsTransport } from "./connection.ts";
+import type { WsTransport, ConnectionE2eeOptions } from "./connection.ts";
 import { Router } from "./router.ts";
+import { debug } from "./debug.ts";
 import { collectDeviceInfo } from "./device-info.ts";
+import { RateLimiter } from "./rate-limiter.ts";
+import { audit } from "./audit.ts";
 import type {
   AnyClusterFrame,
   ClusterFrame,
   DeviceInfo,
   NodeCapabilities,
+  PeerApprovalRequest,
+  PeerApprovalResponse,
   PeerInfo,
   PeerSync,
 } from "./types.ts";
+import { PeerApprovalManager, type ChannelApi, type NotifyTarget } from "./peer-approval.ts";
+import { loadOrCreateIdentity } from "./identity.ts";
+import type { KeyPair } from "./crypto.ts";
 
 const RECONNECT_BASE = 1_000;
 const RECONNECT_MAX = 60_000;
 
+/** Check if an IP is a loopback address (IPv4 127.x or IPv6 ::1). */
+function isLoopback(ip?: string): boolean {
+  if (!ip) return false;
+  // Normalize IPv6-mapped IPv4 (e.g. "::ffff:127.0.0.1")
+  const normalized = ip.replace(/^::ffff:/, "");
+  return normalized === "::1" || normalized.startsWith("127.");
+}
+
 export interface PeerManagerEvents {
   frame: [frame: AnyClusterFrame, from: Connection];
   peerConnected: [nodeId: string];
   peerDisconnected: [nodeId: string];
+  peerCapabilitiesChanged: [];
 }
 
 export class PeerManager extends EventEmitter<PeerManagerEvents> {
@@ -37,12 +56,21 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private stopped = false;
   /** Map from ws WebSocket to Connection for inbound connections. */
   private inboundConnections = new Map<WsWebSocket, Connection>();
+  /** Map from ws WebSocket to remote IP (for audit logging on close). */
+  private inboundIps = new Map<WsWebSocket, string>();
   private gossipDebounceTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Persistent X25519 identity key pair (TOFU). See identity.ts for security model. */
+  private identityKeyPair: KeyPair;
+  private e2eeOptions: ConnectionE2eeOptions;
+  private e2eeOptionsInbound: ConnectionE2eeOptions;
+  private rateLimiter: RateLimiter;
+  readonly approvalManager: PeerApprovalManager;
 
   constructor(config: ClawMatrixConfig, openclawVersion?: string) {
     super();
     this.config = config;
     this.localDeviceInfo = collectDeviceInfo(openclawVersion);
+    const acpAgents = config.acp?.enabled ? config.acp.agents : undefined;
     this.localCapabilities = {
       nodeId: config.nodeId,
       agents: config.agents,
@@ -54,18 +82,44 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         allow: config.toolProxy.allow,
         deny: config.toolProxy.deny,
       } : undefined,
+      acpAgents,
     };
+    // Load or generate persistent identity key pair (TOFU — see identity.ts)
+    // Use ~/.openclaw/ instead of cwd — gateway's cwd may be "/" (read-only)
+    const stateDir = path.join(homedir() || tmpdir(), ".openclaw", "clawmatrix");
+    this.identityKeyPair = loadOrCreateIdentity(stateDir);
+
+    this.e2eeOptions = {
+      e2ee: config.e2ee, compression: config.compression,
+      identityKeyPair: config.e2ee !== false ? this.identityKeyPair : undefined,
+    };
+    // Inbound connections defer auth_ok when peer approval is enabled in required mode
+    const deferAuth = config.peerApproval?.enabled && config.peerApproval?.mode === "required";
+    this.e2eeOptionsInbound = { ...this.e2eeOptions, deferAuthOk: !!deferAuth };
+    this.rateLimiter = new RateLimiter();
     this.router = new Router(config.nodeId, {
       agents: config.agents,
       models: config.models,
       tags: config.tags,
       deviceInfo: this.localDeviceInfo,
       toolProxy: this.localCapabilities.toolProxy,
+      acpAgents,
     });
+
+    // Peer approval
+    const approvalConfig = config.peerApproval ?? {
+      enabled: false, mode: "notify" as const, timeout: 1_200_000, allowList: [], persistPath: "approved-peers.json",
+    };
+    this.approvalManager = new PeerApprovalManager(approvalConfig, stateDir);
   }
 
   // ── Lifecycle ──────────────────────────────────────────────────
   async start() {
+    await this.approvalManager.load();
+    this.approvalManager.setBroadcastFn((frame) => {
+      frame.from = this.config.nodeId;
+      this.router.broadcast(frame);
+    });
     if (this.config.listen) {
       this.startListening();
     }
@@ -105,6 +159,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       this.httpServer = null;
     }
 
+    this.rateLimiter.destroy();
+    this.approvalManager.destroy();
     this.router.destroy();
   }
 
@@ -122,14 +178,35 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
     this.httpServer = createServer((req, res) => {
       if (this.httpRequestHandler && this.httpRequestHandler(req, res)) return;
-      res.writeHead(426, { "Content-Type": "text/plain" });
-      res.end("WebSocket upgrade required");
+      // Disguise as a normal web server to avoid fingerprinting
+      res.writeHead(200, { "Content-Type": "text/html", "Server": "nginx" });
+      res.end("<!DOCTYPE html><html><head><title>Welcome</title></head><body><p>It works!</p></body></html>");
+    });
+
+    this.wss = new WebSocketServer({
+      server: this.httpServer,
+      handleProtocols(protocols) {
+        // Accept client's preferred subprotocol for disguise
+        if (protocols.size > 0) return protocols.values().next().value!;
+        return false;
+      },
     });
 
-    this.wss = new WebSocketServer({ server: this.httpServer });
+    this.wss.on("connection", (ws, req) => {
+      const ip = req.headers["x-forwarded-for"]?.toString().split(",")[0].trim()
+        ?? req.socket.remoteAddress
+        ?? "unknown";
+
+      // Rate limit check
+      if (!this.rateLimiter.check(ip)) {
+        audit("conn_rate_limited", { ip, detail: `remaining=0` });
+        ws.close(4029, "rate limited");
+        return;
+      }
 
-    this.wss.on("connection", (ws) => {
-      this.handleInboundOpen(ws);
+      audit("conn_open", { ip });
+      this.inboundIps.set(ws, ip);
+      this.handleInboundOpen(ws, ip);
 
       ws.on("message", (data) => {
         const conn = this.inboundConnections.get(ws);
@@ -144,6 +221,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
           conn.feedClose(code, reason.toString());
           this.inboundConnections.delete(ws);
         }
+        this.inboundIps.delete(ws);
       });
     });
 
@@ -154,7 +232,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.httpServer.listen(port, hostname);
   }
 
-  private handleInboundOpen(ws: WsWebSocket) {
+  private handleInboundOpen(ws: WsWebSocket, ip: string) {
     // Wrap ws WebSocket into our WsTransport interface
     const transport: WsTransport = {
       send(data: string) {
@@ -174,12 +252,25 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       this.config.nodeId,
       this.config.secret,
       this.localCapabilities,
+      this.e2eeOptionsInbound,
     );
 
     this.inboundConnections.set(ws, conn);
 
     conn.on("authenticated", (caps) => {
-      this.onPeerAuthenticated(conn, caps);
+      audit("auth_success", { ip, nodeId: caps.nodeId });
+      this.onPeerAuthenticated(conn, caps, ip);
+    });
+
+    conn.on("close", (code, reason) => {
+      if (!conn.authenticated && code === 4001) {
+        audit("auth_failure", { ip, detail: reason });
+        this.rateLimiter.recordFailure(ip);
+      } else if (!conn.authenticated && code === 4003) {
+        audit("auth_timeout", { ip });
+      } else {
+        audit("conn_close", { ip, nodeId: conn.remoteNodeId ?? undefined, detail: `code=${code}` });
+      }
     });
 
     conn.on("error", () => {
@@ -191,7 +282,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private connectToPeer(peer: PeerConfig) {
     if (this.stopped) return;
 
-    const ws = new WebSocket(peer.url);
+    // Use a common WS subprotocol for traffic disguise
+    const ws = new WebSocket(peer.url, ["graphql-transport-ws"]);
 
     ws.addEventListener("open", () => {
       const conn = new Connection(
@@ -200,6 +292,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         this.config.nodeId,
         this.config.secret,
         this.localCapabilities,
+        this.e2eeOptions,
       );
       conn.bindWebSocket(ws);
 
@@ -213,13 +306,16 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       });
     });
 
-    ws.addEventListener("error", () => {
-      this.scheduleReconnect(peer);
-    });
+    let reconnectScheduled = false;
+    const tryReconnect = () => {
+      if (!reconnectScheduled) {
+        reconnectScheduled = true;
+        this.scheduleReconnect(peer);
+      }
+    };
 
-    ws.addEventListener("close", () => {
-      this.scheduleReconnect(peer);
-    });
+    ws.addEventListener("error", tryReconnect);
+    ws.addEventListener("close", tryReconnect);
   }
 
   private scheduleReconnect(peer: PeerConfig) {
@@ -238,8 +334,76 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   }
 
   // ── Peer lifecycle ─────────────────────────────────────────────
-  private onPeerAuthenticated(conn: Connection, caps: NodeCapabilities) {
+  private onPeerAuthenticated(conn: Connection, caps: NodeCapabilities, ip?: string) {
     const nodeId = conn.remoteNodeId!;
+    // Peer's persistent public key for TOFU identity binding
+    const peerPublicKey = conn.remoteIdentityKey ?? undefined;
+
+    // Peer approval check (inbound only — outbound peers are explicitly configured)
+    // Skip approval for same-nodeId connections from localhost (local clients
+    // like Mac desktop app / iOS simulator). An attacker would need to already
+    // be on the same machine to exploit this, which is outside our threat model.
+    const isLocalClient = nodeId === this.config.nodeId && isLoopback(ip);
+    debug("approval", `onPeerAuthenticated: nodeId=${nodeId} role=${conn.role} isLocalClient=${isLocalClient} ip=${ip}`);
+    if (conn.role === "inbound" && !isLocalClient) {
+      // IP-level approval rate limiting (suppress noise from leaked tokens)
+      if (ip && this.approvalManager.isIpBlocked(ip)) {
+        audit("approval_ip_blocked", { ip, nodeId });
+        conn.close(4005, "approval denied");
+        return;
+      }
+
+      const check = this.approvalManager.checkPeer(nodeId, caps, peerPublicKey);
+      debug("approval", `checkPeer: nodeId=${nodeId} result=${check}`);
+      if (check === "deny") {
+        conn.close(4005, "approval denied");
+        return;
+      }
+      if (check === "pending") {
+        // In notify mode, requestApproval auto-approves and sends notification.
+        // In required mode, it waits for explicit approval.
+        this.approvalManager.requestApproval(
+          nodeId,
+          caps,
+          (frame) => {
+            frame.from = this.config.nodeId;
+            this.router.broadcast(frame);
+          },
+          peerPublicKey,
+          ip,
+        ).then((decision) => {
+          if (decision === "approve" && conn.isOpen) {
+            conn.completeAuth();
+            this.completePeerJoin(conn, caps);
+          } else if (conn.isOpen) {
+            if (ip) this.approvalManager.recordIpDeny(ip);
+            conn.close(
+              decision === "timeout" ? 4004 : 4005,
+              decision === "timeout" ? "approval timeout" : "approval denied",
+            );
+          }
+        });
+        // In required mode, don't complete the join yet
+        if (this.config.peerApproval?.mode === "required") {
+          // Wire up close handler to clean up if connection drops while pending
+          conn.on("close", () => this.onPeerDisconnected(conn));
+          return;
+        }
+        // In notify mode, requestApproval resolves immediately, but
+        // completePeerJoin is called async — fall through to complete now
+      }
+    }
+
+    // For outbound connections auth_ok is not deferred; for already-approved
+    // inbound connections we need to send the deferred auth_ok now.
+    conn.completeAuth();
+    this.completePeerJoin(conn, caps);
+  }
+
+  private completePeerJoin(conn: Connection, caps: NodeCapabilities) {
+    const nodeId = conn.remoteNodeId!;
+    // Same-nodeId 连接（如 Mac/iOS 桌面客户端）也正常注册路由，
+    // 使得 sendTo(nodeId) 能将响应帧路由回客户端连接。
     this.router.addDirectPeer(nodeId, conn, caps);
 
     conn.on("message", (frame) => this.onFrame(frame, conn));
@@ -248,28 +412,32 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
     this.sendPeerSync(conn);
 
-    // Broadcast peer_join to other peers
-    this.router.broadcast({
-      type: "peer_join",
-      from: this.config.nodeId,
-      timestamp: Date.now(),
-      payload: {
-        nodeId,
-        agents: caps.agents,
-        models: caps.models,
-        tags: caps.tags,
-        deviceInfo: caps.deviceInfo,
-        toolProxy: caps.toolProxy,
-      },
-    } as AnyClusterFrame);
-
-    // Re-sync with all existing peers so they learn about the new node
-    for (const existingConn of this.router.getDirectConnections()) {
-      if (existingConn !== conn && existingConn.isOpen) {
-        this.sendPeerSync(existingConn);
+    // Same-nodeId 的本地客户端不向集群广播 peer_join，对外不可见
+    if (nodeId !== this.config.nodeId) {
+      // Broadcast peer_join to other peers
+      this.router.broadcast({
+        type: "peer_join",
+        from: this.config.nodeId,
+        timestamp: Date.now(),
+        payload: {
+          nodeId,
+          agents: caps.agents,
+          models: caps.models,
+          tags: caps.tags,
+          deviceInfo: caps.deviceInfo,
+          toolProxy: caps.toolProxy,
+        },
+      } as AnyClusterFrame);
+
+      // Re-sync with all existing peers so they learn about the new node
+      for (const existingConn of this.router.getDirectConnections()) {
+        if (existingConn !== conn && existingConn.isOpen) {
+          this.sendPeerSync(existingConn);
+        }
       }
     }
 
+    audit("peer_join", { nodeId, detail: `agents=${caps.agents.length} models=${caps.models.length}` });
     this.emit("peerConnected", nodeId);
   }
 
@@ -277,6 +445,13 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     const nodeId = conn.remoteNodeId;
     if (!nodeId) return;
 
+    // Same-nodeId 本地客户端断开：仅清理路由，不广播 peer_leave
+    if (nodeId === this.config.nodeId) {
+      this.router.removePeer(nodeId);
+      return;
+    }
+
+    audit("peer_leave", { nodeId });
     this.router.removePeer(nodeId);
 
     // Remove satellite contexts that were only reachable via this peer
@@ -299,7 +474,10 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   // ── Message handling ───────────────────────────────────────────
   private onFrame(frame: AnyClusterFrame, from: Connection) {
     // Validate from field: must be the direct peer or a known node (relayed)
-    if (frame.from && frame.from !== from.remoteNodeId && !this.router.getRoute(frame.from)) return;
+    if (frame.from && frame.from !== from.remoteNodeId && !this.router.getRoute(frame.from)) {
+      debug("peer", `dropped frame type=${frame.type} from=${frame.from}: unknown origin (via ${from.remoteNodeId})`);
+      return;
+    }
 
     // Skip dedup for streaming and response frame types.
     // Stream frames share one id across many chunks.
@@ -315,9 +493,52 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       || frame.type === "handoff_res" || frame.type === "handoff_status_res"
       || frame.type === "handoff_input_required"
       || frame.type === "handoff_input" || frame.type === "handoff_cancel"
-      || frame.type === "handoff_status";
+      || frame.type === "handoff_status"
+      || frame.type === "diagnostic_exec_res" || frame.type === "diagnostic_status_res"
+      || frame.type === "peer_approval_res"
+      || frame.type === "acp_stream" || frame.type === "acp_res"
+      || frame.type === "acp_close_res"
+      || frame.type === "acp_list_res" || frame.type === "acp_resume_res"
+      || frame.type === "acp_cancel_res"
+      || frame.type === "acp_set_mode_res" || frame.type === "acp_get_modes_res"
+      || frame.type === "terminal_open_res" || frame.type === "terminal_data"
+      || frame.type === "terminal_resize" || frame.type === "terminal_close"
+      || frame.type === "terminal_close_res";
     if (frame.id && !skipDedup && this.router.isDuplicate(frame.id)) return;
 
+    // Handle peer approval responses locally (don't emit to cluster-service)
+    if (frame.type === "peer_approval_res") {
+      this.approvalManager.handleApprovalFrame(frame as PeerApprovalResponse);
+      return;
+    }
+
+    // Forward peer approval requests from other nodes to local IM channels + desktop notification
+    if (frame.type === "peer_approval_req" && frame.from !== this.config.nodeId) {
+      const req = frame as PeerApprovalRequest;
+      this.approvalManager.forwardApprovalToIM(
+        req.payload.approvalId,
+        req.payload.nodeId,
+        req.payload.deviceInfo,
+        req.payload.ip,
+      );
+      // Don't return — let it propagate for relay
+    }
+
+    // Forward peer approval resolution notifications to local IM channels
+    if (frame.type === "peer_approval_notify" && frame.from !== this.config.nodeId) {
+      const notify = frame as import("./types.ts").PeerApprovalNotify;
+      if (notify.payload.resolution) {
+        this.approvalManager.forwardResolutionToIM(
+          notify.payload.approvalId,
+          notify.payload.nodeId,
+          notify.payload.deviceInfo,
+          notify.payload.resolution.decision,
+          notify.payload.resolution.resolvedBy,
+        );
+      }
+      // Don't return — let it propagate for relay
+    }
+
     if (frame.type === "peer_sync") {
       this.handlePeerSync(frame as PeerSync, from);
       return;
@@ -345,6 +566,14 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       return;
     }
 
+    // Forward to same-nodeId satellite connection (e.g. Mac desktop app) so that
+    // responses to requests the satellite originated are delivered back to it.
+    // Skip if the frame came from the satellite itself (avoid echo).
+    const sameNodeConn = this.router.getRoute(this.config.nodeId)?.connection;
+    if (sameNodeConn?.isOpen && sameNodeConn !== from) {
+      sameNodeConn.send(frame);
+    }
+
     this.emit("frame", frame, from);
   }
 
@@ -385,11 +614,13 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         const hadDirectPeers = prev?.directPeers.length ?? 0;
         const hadToolProxy = JSON.stringify(prev?.toolProxy);
         const hadDeviceInfo = prev?.deviceInfo?.hostname;
+        const hadAcpAgents = prev?.acpAgents?.length ?? 0;
         this.router.updatePeerCapabilities(peer.nodeId, peer);
         if (peer.agents.length !== hadAgents || peer.models.length !== (prev?.models.length ?? 0)
             || (peer.directPeers?.length ?? 0) !== hadDirectPeers
             || JSON.stringify(peer.toolProxy) !== hadToolProxy
-            || peer.deviceInfo?.hostname !== hadDeviceInfo) {
+            || peer.deviceInfo?.hostname !== hadDeviceInfo
+            || (peer.acpAgents?.length ?? 0) !== hadAcpAgents) {
           changed = true;
         }
       } else {
@@ -410,6 +641,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
           }
         }
       }, 100);
+      this.emit("peerCapabilitiesChanged");
     }
   }
 

package/src/rate-limiter.ts

@@ -0,0 +1,88 @@
+/** Per-IP sliding window rate limiter for inbound WebSocket connections. */
+
+export interface RateLimiterConfig {
+  /** Max connection attempts per IP within the window (default: 10). */
+  maxAttempts: number;
+  /** Sliding window duration in ms (default: 60000 = 1 minute). */
+  windowMs: number;
+  /** How often to run GC on expired entries in ms (default: 30000). */
+  gcIntervalMs: number;
+}
+
+const DEFAULT_CONFIG: RateLimiterConfig = {
+  maxAttempts: 10,
+  windowMs: 60_000,
+  gcIntervalMs: 30_000,
+};
+
+export class RateLimiter {
+  private config: RateLimiterConfig;
+  /** Map from IP → sorted array of timestamps (ms). */
+  private attempts = new Map<string, number[]>();
+  private gcTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config?: Partial<RateLimiterConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.gcTimer = setInterval(() => this.gc(), this.config.gcIntervalMs);
+  }
+
+  /** Returns true if the connection should be allowed, false if rate-limited. */
+  check(ip: string): boolean {
+    const now = Date.now();
+    const cutoff = now - this.config.windowMs;
+
+    let timestamps = this.attempts.get(ip);
+    if (timestamps) {
+      // Remove expired entries
+      timestamps = timestamps.filter((t) => t > cutoff);
+    } else {
+      timestamps = [];
+    }
+
+    if (timestamps.length >= this.config.maxAttempts) {
+      this.attempts.set(ip, timestamps);
+      return false;
+    }
+
+    timestamps.push(now);
+    this.attempts.set(ip, timestamps);
+    return true;
+  }
+
+  /** Record a failed auth attempt — counts as extra weight. */
+  recordFailure(ip: string) {
+    const now = Date.now();
+    const timestamps = this.attempts.get(ip) ?? [];
+    // A failure counts as 3 attempts to accelerate blocking of brute-force
+    timestamps.push(now, now, now);
+    this.attempts.set(ip, timestamps);
+  }
+
+  /** Get remaining attempts for an IP. */
+  remaining(ip: string): number {
+    const cutoff = Date.now() - this.config.windowMs;
+    const timestamps = this.attempts.get(ip) ?? [];
+    const active = timestamps.filter((t) => t > cutoff).length;
+    return Math.max(0, this.config.maxAttempts - active);
+  }
+
+  private gc() {
+    const cutoff = Date.now() - this.config.windowMs;
+    for (const [ip, timestamps] of this.attempts) {
+      const active = timestamps.filter((t) => t > cutoff);
+      if (active.length === 0) {
+        this.attempts.delete(ip);
+      } else {
+        this.attempts.set(ip, active);
+      }
+    }
+  }
+
+  destroy() {
+    if (this.gcTimer) {
+      clearInterval(this.gcTimer);
+      this.gcTimer = null;
+    }
+    this.attempts.clear();
+  }
+}