clawmatrix 0.1.15 → 0.1.17

package/BOOTSTRAP.md

@@ -175,12 +175,23 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
 ```json
 {
   "tools": {
-    "allow": ["clawmatrix"]
+    "profile": "full",
+    "sessions": {
+      "visibility": "all"
+    },
+    "allow": [
+      "clawmatrix"
+    ]
   }
 }
 ```
 
-或按 Agent 粒度启用：
+配置说明：
+- `profile: "full"` — 启用完整工具集（包括可选工具）
+- `sessions.visibility: "all"` — 允许跨会话访问工具（集群工具需要此设置才能在所有会话中可用）
+- `allow: ["clawmatrix"]` — 显式允许 ClawMatrix 插件注册的所有集群工具
+
+也可以按 Agent 粒度启用：
 
 ```json
 {
@@ -189,6 +200,10 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
       {
         "id": "main",
         "tools": {
+          "profile": "full",
+          "sessions": {
+            "visibility": "all"
+          },
           "allow": ["clawmatrix"]
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/auth.ts

@@ -3,17 +3,40 @@ export function generateNonce(): string {
   return Buffer.from(bytes).toString("hex");
 }
 
-export async function computeHmac(
-  nonce: string,
-  secret: string,
-): Promise<string> {
-  const key = await crypto.subtle.importKey(
+/** Cache imported CryptoKey keyed by a hash of the secret (avoid storing plaintext). Max 8 entries. */
+const KEY_CACHE_MAX = 8;
+const keyCache = new Map<string, CryptoKey>();
+
+function cacheKeyFor(secret: string): string {
+  const { createHash } = require("node:crypto");
+  return createHash("sha256").update(secret).digest("hex");
+}
+
+async function getHmacKey(secret: string): Promise<CryptoKey> {
+  const cacheKey = cacheKeyFor(secret);
+  let key = keyCache.get(cacheKey);
+  if (key) return key;
+  key = await crypto.subtle.importKey(
     "raw",
     new TextEncoder().encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
     ["sign"],
   );
+  if (keyCache.size >= KEY_CACHE_MAX) {
+    // Evict oldest entry
+    const oldest = keyCache.keys().next().value!;
+    keyCache.delete(oldest);
+  }
+  keyCache.set(cacheKey, key);
+  return key;
+}
+
+export async function computeHmac(
+  nonce: string,
+  secret: string,
+): Promise<string> {
+  const key = await getHmacKey(secret);
   const sig = await crypto.subtle.sign(
     "HMAC",
     key,
@@ -22,14 +45,21 @@ export async function computeHmac(
   return Buffer.from(sig).toString("hex");
 }
 
-/** Constant-time string comparison. */
+/** Constant-time string comparison. Uses native crypto.timingSafeEqual with
+ *  SHA-256 pre-hash to normalize lengths (avoids length-leak from early return). */
 export function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  const nodeTimingSafeEqual = require("node:crypto").timingSafeEqual;
+  const encoder = new TextEncoder();
+  const bufA = encoder.encode(a);
+  const bufB = encoder.encode(b);
+  if (bufA.byteLength !== bufB.byteLength) {
+    // Hash both to fixed length so we still compare in constant time
+    const { createHash } = require("node:crypto");
+    const hashA = createHash("sha256").update(bufA).digest();
+    const hashB = createHash("sha256").update(bufB).digest();
+    return nodeTimingSafeEqual(hashA, hashB);
   }
-  return diff === 0;
+  return nodeTimingSafeEqual(Buffer.from(bufA), Buffer.from(bufB));
 }
 
 export async function verifyHmac(
@@ -38,5 +68,5 @@ export async function verifyHmac(
   sig: string,
 ): Promise<boolean> {
   const expected = await computeHmac(nonce, secret);
-  return timingSafeEqual(expected, sig);
+  return timingSafeEqual(expected, sig); // timingSafeEqual is now sync
 }

package/src/cluster-service.ts

@@ -17,6 +17,11 @@ import type {
   HandoffRequest,
   HandoffResponse,
   HandoffStreamChunk,
+  HandoffCancel,
+  HandoffStatusQuery,
+  HandoffStatusResponse,
+  HandoffInputRequired,
+  HandoffInput,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -44,6 +49,7 @@ export class ClusterRuntime {
   readonly handoffManager: HandoffManager;
   readonly modelProxy: ModelProxy;
   readonly toolProxy: ToolProxy;
+  webHandler: WebHandler | null = null;
   private logger: PluginLogger;
 
   constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
@@ -58,7 +64,7 @@ export class ClusterRuntime {
 
   start() {
     // Wire up frame dispatch
-    this.peerManager.on("frame", (frame, conn) => {
+    this.peerManager.on("frame", (frame) => {
       this.dispatchFrame(frame);
     });
 
@@ -72,8 +78,10 @@ export class ClusterRuntime {
 
     // Web dashboard (must be set before peerManager.start() creates the HTTP server)
     if (this.config.web?.enabled) {
-      const webHandler = new WebHandler(this.config, this.peerManager, this.handoffManager);
-      this.peerManager.setHttpHandler((req, res) => webHandler.handle(req, res));
+      this.webHandler = new WebHandler(this.config, this.peerManager, this.handoffManager);
+      this.peerManager.setHttpHandler((req, res) => this.webHandler!.handle(req, res));
+      // Enable satellite tool routing through WebHandler
+      this.toolProxy.setSatelliteHandler(this.webHandler);
       this.logger.info(`[clawmatrix] Web dashboard enabled on listen port`);
     }
 
@@ -89,6 +97,7 @@ export class ClusterRuntime {
   }
 
   async stop() {
+    this.webHandler?.destroy();
     this.handoffManager.destroy();
     this.modelProxy.stop();
     this.toolProxy.destroy();
@@ -98,7 +107,7 @@ export class ClusterRuntime {
 
   private dispatchFrame(frame: AnyClusterFrame) {
     if (frame.type.startsWith("model_")) {
-      debug("dispatch", `${frame.type} id=${frame.id} from=${(frame as ClusterFrame).from}`);
+      debug("dispatch", `${frame.type} id=${frame.id} from=${frame.from}`);
     }
     switch (frame.type) {
       case "handoff_req":
@@ -112,6 +121,24 @@ export class ClusterRuntime {
       case "handoff_res":
         this.handoffManager.handleResponse(frame as HandoffResponse);
         break;
+      case "handoff_cancel":
+        this.handoffManager.handleCancel(frame as HandoffCancel);
+        break;
+      case "handoff_status":
+        this.handoffManager.handleStatusQuery(frame as HandoffStatusQuery);
+        break;
+      case "handoff_input_required":
+        this.handoffManager.handleInputRequired(frame as HandoffInputRequired);
+        break;
+      case "handoff_input":
+        this.handoffManager.handleInput(frame as HandoffInput).catch((err) => {
+          this.logger.error(`[clawmatrix] Handoff input error: ${err}`);
+        });
+        break;
+      case "handoff_status_res":
+        // Status responses are handled by the requester via pending callbacks
+        // (currently informational — logged but not routed to pending map)
+        break;
       case "model_req":
         this.modelProxy.handleModelRequest(frame as ModelRequest).catch((err) => {
           this.logger.error(`[clawmatrix] Model request error: ${err}`);

package/src/compat.ts

@@ -40,6 +40,9 @@ export function spawnProcess(
         stream.on("end", () => controller.close());
         stream.on("error", (err) => controller.error(err));
       },
+      cancel() {
+        stream.destroy();
+      },
     });
   }
 

package/src/connection.ts

@@ -9,6 +9,7 @@ import type {
   DeviceInfo,
   ModelInfo,
   NodeCapabilities,
+  ToolProxyInfo,
 } from "./types.ts";
 import { generateNonce, computeHmac, verifyHmac } from "./auth.ts";
 
@@ -68,13 +69,15 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     this.secret = secret;
     this.localCapabilities = localCapabilities;
 
+    // Both inbound and outbound get an auth timeout to prevent hanging connections
+    this.authTimer = setTimeout(() => {
+      if (!this.authenticated) {
+        this.close(4003, "auth timeout");
+      }
+    }, AUTH_TIMEOUT);
+
     if (role === "inbound") {
       this.sendAuthChallenge();
-      this.authTimer = setTimeout(() => {
-        if (!this.authenticated) {
-          this.close(4003, "auth timeout");
-        }
-      }, AUTH_TIMEOUT);
     }
   }
 
@@ -162,13 +165,14 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async handleAuthMessage(frame: AnyClusterFrame) {
     if (this.role === "inbound") {
       if (frame.type !== "auth") return;
-      const { nodeId, sig, agents, models, tags, deviceInfo } = frame.payload as {
+      const { nodeId, sig, agents, models, tags, deviceInfo, toolProxy } = frame.payload as {
         nodeId: string;
         sig: string;
         agents?: AgentInfo[];
         models?: ModelInfo[];
         tags?: string[];
         deviceInfo?: DeviceInfo;
+        toolProxy?: ToolProxyInfo;
       };
       if (!this.pendingNonce) return;
 
@@ -193,6 +197,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         models: models ?? [],
         tags: tags ?? [],
         deviceInfo,
+        toolProxy,
       };
       this.authenticated = true;
       this.clearAuthTimer();
@@ -207,6 +212,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           models: this.localCapabilities.models,
           tags: this.localCapabilities.tags,
           deviceInfo: this.localCapabilities.deviceInfo,
+          toolProxy: this.localCapabilities.toolProxy,
         },
       } as AuthOk);
 
@@ -227,6 +233,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
             models: this.localCapabilities.models,
             tags: this.localCapabilities.tags,
             deviceInfo: this.localCapabilities.deviceInfo,
+            toolProxy: this.localCapabilities.toolProxy,
           },
         });
         return;
@@ -241,8 +248,10 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           models: ok.payload.models,
           tags: ok.payload.tags,
           deviceInfo: ok.payload.deviceInfo,
+          toolProxy: ok.payload.toolProxy,
         };
         this.authenticated = true;
+        this.clearAuthTimer();
         this.startHeartbeat();
         this.emit("authenticated", this.remoteCapabilities);
         return;