clawmatrix 0.1.22 → 0.2.0

package/src/peer-approval.ts

@@ -0,0 +1,628 @@
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import type { PeerApprovalConfig } from "./config.ts";
+import { debug } from "./debug.ts";
+import type {
+  AnyClusterFrame,
+  DeviceInfo,
+  NodeCapabilities,
+  PeerApprovalNotify,
+  PeerApprovalRequest,
+  PeerApprovalResponse,
+} from "./types.ts";
+
+const RATE_LIMIT_WINDOW = 600_000; // 10 min cooldown after deny
+const IP_DENY_THRESHOLD = 3;       // auto-block IP after N denied approvals
+const IP_DENY_WINDOW = 1_800_000;  // 30 min IP block window
+
+/** Who resolved the approval and how. */
+export interface ApprovalResolvedBy {
+  /** Source: which node/channel resolved this. e.g. "home-macmini", "telegram:95123182" */
+  source: string;
+  /** Timestamp of the resolution. */
+  at: number;
+}
+
+export interface ApprovedPeerRecord {
+  nodeId: string;
+  approvedAt: number;
+  deviceInfo?: DeviceInfo;
+  /**
+   * Persistent public key (base64) pinned at approval time (TOFU).
+   */
+  publicKey?: string;
+  /** Who approved this peer and when. */
+  resolvedBy?: ApprovalResolvedBy;
+}
+
+export interface DeniedPeerRecord {
+  nodeId: string;
+  deniedAt: number;
+  deviceInfo?: DeviceInfo;
+  /** Who denied this peer and when. */
+  resolvedBy?: ApprovalResolvedBy;
+}
+
+interface PersistentData {
+  approved: Record<string, ApprovedPeerRecord>;
+  denied: Record<string, DeniedPeerRecord | number>; // number for legacy compat
+}
+
+export interface PendingApproval {
+  approvalId: string;
+  nodeId: string;
+  deviceInfo?: DeviceInfo;
+  capabilities: NodeCapabilities;
+  /** Peer's persistent public key (base64), to be pinned on approval. */
+  publicKey?: string;
+  createdAt: number;
+  resolve: (decision: "approve" | "deny") => void;
+}
+
+export interface PeerApprovalEvents {
+  /** Fired when a new peer needs notification/approval. */
+  notify: [approval: PendingApproval];
+}
+
+/** Channel target for sending notifications. */
+export interface NotifyTarget {
+  channel: string;
+  to: string;
+  accountId?: string;
+  threadId?: string | number;
+}
+
+/** Minimal interface for sending messages via OpenClaw channel API. */
+export interface ChannelApi {
+  [channel: string]: {
+    [method: string]: (to: string, text: string, opts?: Record<string, unknown>) => Promise<unknown>;
+  } | undefined;
+}
+
+/** Gateway send function for channels not available in the runtime channel API (e.g. plugin channels). */
+export type GatewaySendFn = (params: {
+  to: string;
+  message: string;
+  channel: string;
+  accountId?: string;
+  threadId?: string;
+}) => Promise<unknown>;
+
+export class PeerApprovalManager extends EventEmitter<PeerApprovalEvents> {
+  private config: PeerApprovalConfig;
+  private stateDir: string;
+  private data: PersistentData = { approved: {}, denied: {} };
+  private pending = new Map<string, PendingApproval>();
+  private channelApi: ChannelApi | null = null;
+  private gatewaySend: GatewaySendFn | null = null;
+  private broadcastFn: ((frame: AnyClusterFrame) => void) | null = null;
+  private notifyTargets: NotifyTarget[] = [];
+  private loaded = false;
+  /** IP → list of deny timestamps (for approval noise suppression). */
+  private ipDenyHistory = new Map<string, number[]>();
+
+  constructor(config: PeerApprovalConfig, stateDir: string) {
+    super();
+    this.config = config;
+    this.stateDir = stateDir;
+  }
+
+  private log(msg: string) {
+    debug("approval", msg);
+  }
+
+  /** Set the OpenClaw channel API for sending notifications. */
+  setChannelApi(channelApi: ChannelApi | null) {
+    this.channelApi = channelApi;
+    this.log(`setChannelApi: ${channelApi ? Object.keys(channelApi).join(",") : "null"}`);
+  }
+
+  /** Set a gateway send function for plugin channels not in the runtime API. */
+  setGatewaySend(fn: GatewaySendFn | null) {
+    this.gatewaySend = fn;
+  }
+
+  /** Set the broadcast function for sending frames to mesh peers. */
+  setBroadcastFn(fn: ((frame: AnyClusterFrame) => void) | null) {
+    this.broadcastFn = fn;
+  }
+
+  /** Set notification targets (from OpenClaw approvals config). */
+  setNotifyTargets(targets: NotifyTarget[]) {
+    this.notifyTargets = targets;
+    this.log(`setNotifyTargets: ${targets.map(t => `${t.channel}/${t.to}`).join(", ")}`);
+  }
+
+  // ── Persistence ─────────────────────────────────────────────────
+
+  async load() {
+    if (this.loaded) return;
+    try {
+      const filePath = path.join(this.stateDir, this.config.persistPath);
+      if (fs.existsSync(filePath)) {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        this.data = {
+          approved: parsed.approved ?? {},
+          denied: parsed.denied ?? {},
+        };
+      }
+    } catch {
+      // Start fresh
+    }
+    this.loaded = true;
+  }
+
+  private save() {
+    try {
+      const filePath = path.join(this.stateDir, this.config.persistPath);
+      // Ensure directory exists
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(filePath, JSON.stringify(this.data, null, 2), { mode: 0o600 });
+    } catch {
+      // Best-effort
+    }
+  }
+
+  // ── Core logic ──────────────────────────────────────────────────
+
+  /**
+   * Check if a peer should be allowed to join.
+   * Returns: "allow" (immediate), "pending" (wait for approval), or "deny" (rate-limited).
+   *
+   * @param publicKey - The peer's persistent public key (base64) from the E2EE
+   *   handshake. Used for TOFU identity verification: if the peer was previously
+   *   approved with a different public key, it is treated as a new device and
+   *   must be re-approved. This prevents nodeId impersonation — an attacker who
+   *   obtains the shared secret cannot forge the private key backing this public key.
+   */
+  checkPeer(
+    nodeId: string,
+    capabilities: NodeCapabilities,
+    publicKey?: string,
+  ): "allow" | "pending" | "deny" {
+    if (!this.config.enabled) return "allow";
+
+    // Always allow pre-approved nodeIds from config
+    if (this.config.allowList.includes(nodeId)) return "allow";
+
+    // Already approved (persisted)
+    const approved = this.data.approved[nodeId];
+    if (approved) {
+      // TOFU public key verification: if the approved record has a pinned key
+      // and the connecting peer presents a different key, treat as a new device.
+      // This is the core defense against nodeId impersonation.
+      if (approved.publicKey && publicKey && approved.publicKey !== publicKey) {
+        return "pending";
+      }
+
+      // Legacy: deviceInfo hostname change detection (weaker signal, kept
+      // for backwards compatibility with records that lack a public key)
+      if (!approved.publicKey) {
+        const newHostname = capabilities.deviceInfo?.hostname;
+        const oldHostname = approved.deviceInfo?.hostname;
+        if (oldHostname && newHostname && oldHostname !== newHostname) {
+          return "pending";
+        }
+      }
+
+      return "allow";
+    }
+
+    // Recently denied — rate limit
+    const denied = this.data.denied[nodeId];
+    const deniedAt = typeof denied === "number" ? denied : denied?.deniedAt;
+    if (deniedAt && Date.now() - deniedAt < RATE_LIMIT_WINDOW) {
+      return "deny";
+    }
+
+    return "pending";
+  }
+
+  /**
+   * Create a pending approval and return a promise that resolves with the decision.
+   * In "notify" mode, the promise resolves immediately with "approve".
+   *
+   * @param publicKey - The peer's persistent public key (base64), pinned on approval.
+   */
+  async requestApproval(
+    nodeId: string,
+    capabilities: NodeCapabilities,
+    broadcastFn: (frame: AnyClusterFrame) => void,
+    publicKey?: string,
+    ip?: string,
+  ): Promise<"approve" | "deny" | "timeout"> {
+    const approvalId = crypto.randomUUID();
+    this.log(`requestApproval: nodeId=${nodeId} mode=${this.config.mode} approvalId=${approvalId}`);
+
+    if (this.config.mode === "notify") {
+      // Auto-approve, but send notifications
+      this.addApproved(nodeId, capabilities.deviceInfo, publicKey, { source: "auto:notify-mode", at: Date.now() });
+      this.sendNotifications(approvalId, nodeId, capabilities.deviceInfo, "notify", ip);
+      this.broadcastNotify(broadcastFn, approvalId, nodeId, capabilities.deviceInfo, "notify", ip);
+      return "approve";
+    }
+
+    // Required mode: wait for explicit approval
+    return new Promise<"approve" | "deny" | "timeout">((resolve) => {
+      const pending: PendingApproval = {
+        approvalId,
+        nodeId,
+        deviceInfo: capabilities.deviceInfo,
+        capabilities,
+        publicKey,
+        createdAt: Date.now(),
+        resolve: (decision) => {
+          this.pending.delete(approvalId);
+          clearTimeout(timer);
+          resolve(decision);
+        },
+      };
+
+      this.pending.set(approvalId, pending);
+
+      // Timeout
+      const timer = setTimeout(() => {
+        if (this.pending.has(approvalId)) {
+          this.pending.delete(approvalId);
+          resolve("timeout");
+        }
+      }, this.config.timeout);
+
+      // Send notifications to IM channels
+      this.sendNotifications(approvalId, nodeId, capabilities.deviceInfo, "required", ip);
+      this.broadcastNotify(broadcastFn, approvalId, nodeId, capabilities.deviceInfo, "required", ip);
+
+      // Broadcast approval request to mesh (for iOS etc.)
+      broadcastFn({
+        type: "peer_approval_req",
+        id: approvalId,
+        from: "",  // will be set by PeerManager
+        timestamp: Date.now(),
+        payload: {
+          approvalId,
+          nodeId,
+          deviceInfo: capabilities.deviceInfo,
+          ip,
+        },
+      } as PeerApprovalRequest);
+
+      this.emit("notify", pending);
+    });
+  }
+
+  /** Handle an approval response from a connected peer or gateway method. */
+  handleResponse(approvalId: string, decision: "approve" | "deny", resolvedBy?: ApprovalResolvedBy) {
+    const pending = this.pending.get(approvalId);
+    if (!pending) return false;
+
+    const resolved = resolvedBy ?? { source: "unknown", at: Date.now() };
+    this.log(`handleResponse: ${decision} for ${pending.nodeId} by ${resolved.source}`);
+
+    if (decision === "approve") {
+      this.addApproved(pending.nodeId, pending.deviceInfo, pending.publicKey, resolved);
+    } else {
+      this.data.denied[pending.nodeId] = {
+        nodeId: pending.nodeId,
+        deniedAt: Date.now(),
+        deviceInfo: pending.deviceInfo,
+        resolvedBy: resolved,
+      };
+      this.save();
+    }
+
+    // Send resolution notification to all channels + mesh
+    this.sendResolutionNotification(approvalId, pending.nodeId, pending.deviceInfo, decision, resolved);
+
+    pending.resolve(decision);
+    return true;
+  }
+
+  /** Handle a peer_approval_res frame from mesh. */
+  handleApprovalFrame(frame: PeerApprovalResponse) {
+    const resolvedBy: ApprovalResolvedBy = {
+      source: frame.from || "mesh",
+      at: Date.now(),
+    };
+    return this.handleResponse(frame.payload.approvalId, frame.payload.decision, resolvedBy);
+  }
+
+  /** Revoke an approved peer. */
+  revoke(nodeId: string, resolvedBy?: ApprovalResolvedBy): boolean {
+    const existing = this.data.approved[nodeId];
+    if (!existing) return false;
+    delete this.data.approved[nodeId];
+    this.data.denied[nodeId] = {
+      nodeId,
+      deniedAt: Date.now(),
+      deviceInfo: existing.deviceInfo,
+      resolvedBy: resolvedBy ?? { source: "unknown", at: Date.now() },
+    };
+    this.save();
+    return true;
+  }
+
+  /** Get all approved peers. */
+  getApprovedPeers(): ApprovedPeerRecord[] {
+    return Object.values(this.data.approved);
+  }
+
+  /** Get all pending approvals. */
+  getPendingApprovals(): PendingApproval[] {
+    return [...this.pending.values()];
+  }
+
+  /** Get denied peer records (excluding legacy number-only entries). */
+  getDeniedPeers(): DeniedPeerRecord[] {
+    return Object.values(this.data.denied)
+      .filter((v): v is DeniedPeerRecord => typeof v === "object" && v !== null)
+      .sort((a, b) => b.deniedAt - a.deniedAt);
+  }
+
+  /**
+   * Forward a peer approval notification received from mesh to local IM channels.
+   * Called on nodes that are NOT the originator of the approval request.
+   */
+  async forwardApprovalToIM(
+    approvalId: string,
+    nodeId: string,
+    deviceInfo?: DeviceInfo,
+    ip?: string,
+  ) {
+    this.log(`forwardApprovalToIM: approvalId=${approvalId} nodeId=${nodeId}`);
+    await this.sendNotifications(approvalId, nodeId, deviceInfo, "required", ip);
+  }
+
+  /**
+   * Send resolution notification to all IM channels and broadcast to mesh.
+   * Called after a peer approval is resolved (approved or denied).
+   */
+  private sendResolutionNotification(
+    approvalId: string,
+    nodeId: string,
+    deviceInfo: DeviceInfo | undefined,
+    decision: "approve" | "deny",
+    resolvedBy: ApprovalResolvedBy,
+  ) {
+    // Send to local IM channels
+    this.sendResolutionToIM(approvalId, nodeId, deviceInfo, decision, resolvedBy);
+
+    // Broadcast to mesh so other nodes can notify their local channels
+    if (this.broadcastFn) {
+      this.broadcastFn({
+        type: "peer_approval_notify",
+        from: "",
+        timestamp: Date.now(),
+        payload: {
+          approvalId,
+          nodeId,
+          deviceInfo,
+          mode: "required",
+          resolution: { decision, resolvedBy: resolvedBy.source },
+        },
+      } as PeerApprovalNotify);
+    }
+  }
+
+  /**
+   * Send resolution result to local IM channels.
+   */
+  private async sendResolutionToIM(
+    approvalId: string,
+    nodeId: string,
+    deviceInfo: DeviceInfo | undefined,
+    decision: "approve" | "deny",
+    resolvedBy: ApprovalResolvedBy,
+  ) {
+    if (this.notifyTargets.length === 0) {
+      return;
+    }
+    if (!this.channelApi && !this.gatewaySend) {
+      return;
+    }
+
+    const deviceLabel = `${deviceInfo?.hostname ?? "unknown"} (${deviceInfo?.os ?? "?"})`;
+    const emoji = decision === "approve" ? "\u2705" : "\u274c";
+    const verb = decision === "approve" ? "Approved" : "Denied";
+    const message = [
+      `${emoji} Peer ${verb}`,
+      `Node: ${nodeId}`,
+      `Device: ${deviceLabel}`,
+      `By: ${resolvedBy.source}`,
+    ].join("\n");
+
+    this.log(`sendResolutionToIM: ${decision} for ${nodeId} by ${resolvedBy.source}`);
+
+    for (const target of this.notifyTargets) {
+      try {
+        const channelObj = this.channelApi?.[target.channel];
+        const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+        const methodName = `sendMessage${capitalize(target.channel)}`;
+        const sendFn = channelObj?.[methodName];
+
+        if (typeof sendFn === "function") {
+          await sendFn(target.to, message, {
+            accountId: target.accountId,
+            messageThreadId: target.threadId,
+          });
+        } else if (this.gatewaySend) {
+          await this.gatewaySend({
+            to: target.to,
+            message,
+            channel: target.channel,
+            accountId: target.accountId,
+            threadId: target.threadId != null ? String(target.threadId) : undefined,
+          });
+        }
+      } catch (err) {
+        this.log(`sendResolutionToIM: failed for ${target.channel}/${target.to}: ${err}`);
+      }
+    }
+  }
+
+  /**
+   * Forward a resolution notification received from mesh to local IM channels.
+   */
+  async forwardResolutionToIM(
+    approvalId: string,
+    nodeId: string,
+    deviceInfo: DeviceInfo | undefined,
+    decision: "approve" | "deny",
+    resolvedBySource: string,
+  ) {
+    this.log(`forwardResolutionToIM: ${decision} for ${nodeId}`);
+    await this.sendResolutionToIM(approvalId, nodeId, deviceInfo, decision, {
+      source: resolvedBySource,
+      at: Date.now(),
+    });
+  }
+
+  private addApproved(nodeId: string, deviceInfo?: DeviceInfo, publicKey?: string, resolvedBy?: ApprovalResolvedBy) {
+    this.data.approved[nodeId] = {
+      nodeId,
+      approvedAt: Date.now(),
+      deviceInfo,
+      publicKey,
+      resolvedBy,
+    };
+    delete this.data.denied[nodeId];
+    this.save();
+  }
+
+  // ── Notifications ───────────────────────────────────────────────
+
+  private broadcastNotify(
+    broadcastFn: (frame: AnyClusterFrame) => void,
+    approvalId: string,
+    nodeId: string,
+    deviceInfo: DeviceInfo | undefined,
+    mode: "notify" | "required",
+    ip?: string,
+  ) {
+    broadcastFn({
+      type: "peer_approval_notify",
+      from: "",
+      timestamp: Date.now(),
+      payload: { approvalId, nodeId, deviceInfo, mode, ip },
+    } as PeerApprovalNotify);
+  }
+
+  private async sendNotifications(
+    approvalId: string,
+    nodeId: string,
+    deviceInfo: DeviceInfo | undefined,
+    mode: "notify" | "required",
+    ip?: string,
+  ) {
+    if (!this.channelApi || this.notifyTargets.length === 0) {
+      this.log(`sendNotifications: skipped (channelApi=${!!this.channelApi} targets=${this.notifyTargets.length})`);
+      return;
+    }
+    this.log(`sendNotifications: sending to ${this.notifyTargets.length} targets`);
+
+    const deviceLabel = `${deviceInfo?.hostname ?? "unknown"} (${deviceInfo?.os ?? "?"})`;
+    const expiresMin = Math.floor(this.config.timeout / 60_000);
+    const ipLine = ip ? `IP: ${ip}` : null;
+
+    const lines = mode === "notify"
+      ? [
+          `\u{1f4f2} New device joined ClawMatrix cluster`,
+          `Node: ${nodeId}`,
+          `Device: ${deviceLabel}`,
+          ...(ipLine ? [ipLine] : []),
+          ``,
+          `If this wasn't you: /clawmatrix approval revoke ${nodeId}`,
+        ]
+      : [
+          `\u{1f512} New device requesting to join ClawMatrix cluster`,
+          `Node: ${nodeId}`,
+          `Device: ${deviceLabel}`,
+          ...(ipLine ? [ipLine] : []),
+          `Expires in ${expiresMin} minutes`,
+        ];
+
+    const message = lines.join("\n");
+
+    // Interactive buttons for channels that support them (callback_data processed as command)
+    const approveCmd = `/clawmatrix approve ${approvalId}`;
+    const denyCmd = `/clawmatrix deny ${approvalId}`;
+
+    for (const target of this.notifyTargets) {
+      try {
+        const channelObj = this.channelApi[target.channel];
+
+        // Convention: sendMessage{Channel} e.g. sendMessageTelegram
+        const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+        const methodName = `sendMessage${capitalize(target.channel)}`;
+        const sendFn = channelObj?.[methodName];
+
+        if (typeof sendFn === "function") {
+          // Direct channel API (built-in channels like telegram)
+          const opts: Record<string, unknown> = {
+            accountId: target.accountId,
+            messageThreadId: target.threadId,
+          };
+          if (mode === "required") {
+            opts.buttons = [
+              [
+                { text: "\u2705 Approve", callback_data: approveCmd },
+                { text: "\u274c Deny", callback_data: denyCmd },
+              ],
+            ];
+          }
+          await sendFn(target.to, message, opts);
+          this.log(`sendNotifications: sent to ${target.channel}/${target.to} via channelApi`);
+        } else if (this.gatewaySend) {
+          // Fallback: gateway send method (works for all channels including plugins like feishu)
+          await this.gatewaySend({
+            to: target.to,
+            message: mode === "required"
+              ? `${message}\n\nApprove: ${approveCmd}\nDeny: ${denyCmd}`
+              : message,
+            channel: target.channel,
+            accountId: target.accountId,
+            threadId: target.threadId != null ? String(target.threadId) : undefined,
+          });
+          this.log(`sendNotifications: sent to ${target.channel}/${target.to} via gatewaySend`);
+        } else {
+          this.log(`sendNotifications: no channelApi or gatewaySend for "${target.channel}"`);
+        }
+      } catch (err) {
+        this.log(`sendNotifications: failed for ${target.channel}/${target.to}: ${err}`);
+      }
+    }
+  }
+
+  // ── IP-level approval noise suppression ─────────────────────────
+
+  /** Check if an IP has exceeded the deny threshold (auto-block). */
+  isIpBlocked(ip: string): boolean {
+    const history = this.ipDenyHistory.get(ip);
+    if (!history) return false;
+    const cutoff = Date.now() - IP_DENY_WINDOW;
+    const recent = history.filter((t) => t > cutoff);
+    if (recent.length !== history.length) {
+      this.ipDenyHistory.set(ip, recent);
+    }
+    return recent.length >= IP_DENY_THRESHOLD;
+  }
+
+  /** Record a deny event for an IP. */
+  recordIpDeny(ip: string) {
+    const history = this.ipDenyHistory.get(ip) ?? [];
+    history.push(Date.now());
+    this.ipDenyHistory.set(ip, history);
+  }
+
+  destroy() {
+    // Reject all pending approvals
+    for (const pending of this.pending.values()) {
+      pending.resolve("deny");
+    }
+    this.pending.clear();
+  }
+}