@securecoms/agent-bridge 0.26.3 → 0.26.5

package/connectors/openclaw/openclaw-entry.toolgate.test.ts

@@ -0,0 +1,466 @@
+// packages/connect-agent-bridge/connectors/openclaw/openclaw-entry.toolgate.test.ts
+//
+// Tool gate (security fix 2026-10-05): only a turn the daemon granted tools
+// (its authorization block's tool_grants is non-empty, which the daemon does
+// ONLY for the agent's pinned owner in their DM or an owner-spoken relayed
+// voice turn) may run OpenClaw tools. Every other sender (room member,
+// other-org member, another agent, a frame with no or a malformed block) runs
+// with every tool call BLOCKED by the connector's before_tool_call hook. If
+// the OpenClaw host gives the plugin no hook API, such a turn is refused
+// outright (acked, never dispatched). Fail closed.
+//
+// Drives the REAL register() + plugin.gateway.startAccount path with a fake
+// OpenClaw runtime and api, like openclaw-entry.inbound.test.ts.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildConnectionFile, writeConnectionFile } from "../../src/service/connection-file.js";
+
+const BOUND_ID = "agent-identity";
+const OWNER_ID = "owner-human";
+const PORT = 7099;
+const TOKEN_VALUE = "toolgate-test-token";
+const ORIGINAL_CONN_FILE_ENV = process.env.SECURECOMS_CONNECTION_FILE;
+
+const GRANTS = [{ tool: "current_time", mode: "read" }, { tool: "web_search", mode: "read" }];
+const OWNER_AUTH = { version: 1, audience: "owner_dm", sender_membership: "active", tool_grants: GRANTS };
+const noGrant = (audience: string) => ({ version: 1, audience, sender_membership: "active", tool_grants: [] });
+
+const MISSING = Symbol("missing");
+const NO_TOOL_SENDERS: Array<[string, unknown]> = [
+  ["room member", noGrant("team_room")],
+  ["other-org member", noGrant("partner_room")],
+  ["agent sender", noGrant("agent_to_agent")],
+  ["missing authorization", MISSING],
+];
+
+function waitFor(predicate: () => boolean, timeout = 3000): Promise<void> {
+  const start = Date.now();
+  return new Promise((resolve, reject) => {
+    const check = () => {
+      if (predicate()) return resolve();
+      if (Date.now() - start > timeout) return reject(new Error("waitFor: condition never became true"));
+      setTimeout(check, 5);
+    };
+    check();
+  });
+}
+
+type FakeWs = { sent: Array<Record<string, unknown>>; _emit: (type: string, ev?: unknown) => void };
+
+function makeFakeWebSocket() {
+  const instances: FakeWs[] = [];
+  class FakeWebSocket {
+    url: string;
+    sent: Array<Record<string, unknown>> = [];
+    closed = false;
+    listeners: Record<string, Array<(ev?: unknown) => void>> = {};
+    constructor(url: string) {
+      this.url = url;
+      instances.push(this);
+    }
+    addEventListener(type: string, cb: (ev?: unknown) => void) {
+      (this.listeners[type] ??= []).push(cb);
+    }
+    send(data: string) {
+      this.sent.push(JSON.parse(data));
+    }
+    close() {
+      if (this.closed) return;
+      this.closed = true;
+      this._emit("close");
+    }
+    _emit(type: string, ev?: unknown) {
+      for (const cb of this.listeners[type] ?? []) cb(ev ?? {});
+    }
+  }
+  return { FakeWebSocket, instances };
+}
+
+type HookFn = (event: Record<string, unknown>, ctx: Record<string, unknown>) => unknown;
+
+/**
+ * A fake runtime whose dispatch can run "tool calls" through the hook the
+ * connector registered, with the context OpenClaw would build for this turn
+ * (the turn's SessionKey, and the requester when the host proves it).
+ */
+function makeRuntime(getHook: () => HookFn | undefined) {
+  const contexts: Array<Record<string, any>> = [];
+  const toolResults: unknown[] = [];
+  let toolCallDuringDispatch: ((ctx: Record<string, any>) => Record<string, unknown>) | undefined;
+  const runtime = {
+    version: "2026.9.8",
+    channel: {
+      routing: { resolveAgentRoute: () => ({ agentId: "main", sessionKey: "agent:main:main" }) },
+      session: {
+        resolveStorePath: () => "/tmp/openclaw-store-unused",
+        readSessionUpdatedAt: () => undefined,
+        recordInboundSession: async () => {},
+      },
+      reply: {
+        resolveEnvelopeFormatOptions: () => ({}),
+        formatAgentEnvelope: (args: any) => `ENV:${args.body}`,
+        finalizeInboundContext: (ctx: any) => { contexts.push(ctx); return ctx; },
+        dispatchReplyWithBufferedBlockDispatcher: async ({ ctx }: any) => {
+          if (toolCallDuringDispatch) {
+            const hook = getHook();
+            toolResults.push(hook ? await hook({ toolName: "exec", params: {} }, toolCallDuringDispatch(ctx)) : "no-hook");
+          }
+        },
+      },
+    },
+    error: () => {},
+  };
+  return {
+    runtime,
+    contexts,
+    toolResults,
+    callToolDuringDispatch(fn: (ctx: Record<string, any>) => Record<string, unknown>) { toolCallDuringDispatch = fn; },
+  };
+}
+
+describe("openclaw-entry — tool gate (non-owner senders get no tools)", () => {
+  let home: string;
+  let controller: AbortController;
+  let mod: any;
+  let hook: HookFn | undefined;
+  let hookNames: string[];
+  let hookOpts: unknown[];
+  let sends: Array<Record<string, unknown>>;
+  let logs: string[];
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "sc-toolgate-"));
+    const tokenFile = join(home, "bridge-token");
+    writeFileSync(tokenFile, TOKEN_VALUE, { mode: 0o600 });
+    writeConnectionFile(home, buildConnectionFile({
+      identityId: BOUND_ID,
+      port: PORT,
+      tokenFile,
+      slug: "toolgate-test",
+      label: "Toolgate Test",
+      instanceId: "toolgate-test-instance",
+      now: new Date().toISOString(),
+    }));
+    process.env.SECURECOMS_CONNECTION_FILE = join(home, ".securecoms", "connections", `${BOUND_ID}.json`);
+    vi.stubGlobal("fetch", vi.fn(async (url: string, init?: RequestInit) => {
+      const u = String(url);
+      if (u.endsWith("/healthz")) return { ok: true, json: async () => ({ identity_id: BOUND_ID, joined_channels: 1 }) };
+      if (u.includes("/v1/reply-receipt")) return { ok: true, status: 200, json: async () => ({ found: false }) };
+      if (u.endsWith("/v1/send")) {
+        sends.push(JSON.parse(String(init?.body)));
+        return { ok: true, json: async () => ({ message_id: "reply-1" }) };
+      }
+      if (u.endsWith("/v1/status")) return { ok: true, json: async () => ({ ok: true }) };
+      throw new Error(`unexpected fetch: ${u}`);
+    }));
+    controller = new AbortController();
+    hook = undefined;
+    hookNames = [];
+    hookOpts = [];
+    sends = [];
+    logs = [];
+  });
+
+  afterEach(async () => {
+    controller.abort();
+    vi.unstubAllGlobals();
+    vi.unmock("node:os");
+    if (ORIGINAL_CONN_FILE_ENV === undefined) delete process.env.SECURECOMS_CONNECTION_FILE;
+    else process.env.SECURECOMS_CONNECTION_FILE = ORIGINAL_CONN_FILE_ENV;
+    vi.resetModules();
+  });
+
+  async function start(
+    runtime: unknown,
+    opts: { withHookApi?: boolean; onThrows?: boolean; withTrustedPolicyApi?: boolean } = {},
+  ) {
+    const withHookApi = opts.withHookApi ?? true;
+    const withTrustedPolicyApi = opts.withTrustedPolicyApi ?? true;
+    vi.resetModules();
+    vi.doMock("node:os", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("node:os")>();
+      return { ...actual, homedir: () => home };
+    });
+    mod = await import("./openclaw-entry.js");
+    let plugin: any;
+    const api: Record<string, unknown> = {
+      runtime,
+      registerChannel: ({ plugin: p }: { plugin: unknown }) => { plugin = p; },
+    };
+    if (withHookApi) {
+      api.on = (name: string, handler: HookFn, hookOptions?: unknown) => {
+        if (opts.onThrows) throw new Error("hooks unsupported");
+        hookNames.push(name);
+        hookOpts.push(hookOptions);
+        if (name === "before_tool_call") hook = handler;
+      };
+    }
+    // OpenClaw >= 2026.4.27 (#72287) exposes registerTrustedToolPolicy; its
+    // presence is the connector's proof that before_tool_call blocks.
+    if (withTrustedPolicyApi) api.registerTrustedToolPolicy = () => {};
+    mod.default.register(api);
+    const { FakeWebSocket, instances } = makeFakeWebSocket();
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+    const account = plugin.config.resolveAccount({}, "default");
+    plugin.gateway.startAccount({ account, cfg: {}, log: (m: string) => logs.push(String(m)), abortSignal: controller.signal });
+    await waitFor(() => instances.length >= 1);
+    instances[0]._emit("open");
+    return instances[0];
+  }
+
+  function deliver(ws: FakeWs, frame: Record<string, unknown>) {
+    ws._emit("message", { data: JSON.stringify({ type: "message", ts: 1_700_000_000_000, ...frame }) });
+  }
+  function frame(messageId: string, channel: string, sender: string, authorization: unknown, extra: Record<string, unknown> = {}) {
+    return {
+      channel_id: channel, message_id: messageId, sender_id: sender, text: "run something",
+      ...(authorization === MISSING ? {} : { authorization }),
+      ...extra,
+    };
+  }
+  const acksOf = (ws: FakeWs) => ws.sent.filter((f) => f.type === "ack").map((f) => f.message_id);
+  const turnCtx = (ctx: Record<string, any>) => ({
+    sessionKey: ctx.SessionKey,
+    channelId: "securecoms",
+    requester: { channel: "securecoms", senderId: ctx.SenderId },
+  });
+
+  // ------------------------------------------------------------ pure ----
+
+  describe("toolsAuthorized", () => {
+    it("is true only for a v1 block from an active sender with at least one tool grant", async () => {
+      const m = await import("./openclaw-entry.js");
+      expect(m.toolsAuthorized(OWNER_AUTH)).toBe(true);
+      expect(m.toolsAuthorized({ ...noGrant("agent_to_agent"), tool_grants: GRANTS })).toBe(true); // owner-spoken relay turn
+      expect(m.toolsAuthorized(noGrant("owner_dm"))).toBe(false); // kill switch / unpinned owner / lying flag
+      expect(m.toolsAuthorized(noGrant("team_room"))).toBe(false);
+      expect(m.toolsAuthorized(noGrant("partner_room"))).toBe(false);
+      expect(m.toolsAuthorized(noGrant("agent_to_agent"))).toBe(false);
+      expect(m.toolsAuthorized(undefined)).toBe(false);
+      expect(m.toolsAuthorized(null)).toBe(false);
+      expect(m.toolsAuthorized("owner_dm")).toBe(false);
+      expect(m.toolsAuthorized({ ...OWNER_AUTH, version: 2 })).toBe(false);
+      expect(m.toolsAuthorized({ ...OWNER_AUTH, sender_membership: "unknown" })).toBe(false);
+      expect(m.toolsAuthorized({ ...OWNER_AUTH, tool_grants: "current_time" })).toBe(false);
+      expect(m.toolsAuthorized({ ...OWNER_AUTH, tool_grants: [null] })).toBe(false);
+      expect(m.toolsAuthorized({ ...OWNER_AUTH, tool_grants: [{ mode: "read" }] })).toBe(false);
+      expect(m.toolsAuthorized({ ...OWNER_AUTH, tool_grants: [{ tool: "" }] })).toBe(false);
+    });
+  });
+
+  // ------------------------------------------------------------- owner ----
+
+  it("owner DM: tools run (the hook does not block), CommandAuthorized stays true", async () => {
+    const rt = makeRuntime(() => hook);
+    rt.callToolDuringDispatch(turnCtx);
+    const ws = await start(rt.runtime);
+    expect(hookNames).toEqual(["before_tool_call"]);
+    deliver(ws, frame("m1", "dm", OWNER_ID, OWNER_AUTH));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(rt.contexts).toHaveLength(1);
+    expect(rt.contexts[0].CommandAuthorized).toBe(true);
+    expect(rt.contexts[0].GroupSystemPrompt).toBeUndefined();
+    expect(rt.toolResults).toEqual([undefined]);
+  });
+
+  // ---------------------------------------------------------- no tools ----
+
+  it.each(NO_TOOL_SENDERS)("%s: every tool call in the turn is blocked", async (_name, authorization) => {
+    const rt = makeRuntime(() => hook);
+    rt.callToolDuringDispatch(turnCtx);
+    const ws = await start(rt.runtime);
+    deliver(ws, frame("m1", "room", "sender", authorization));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(rt.contexts).toHaveLength(1);
+    expect(rt.contexts[0].CommandAuthorized).toBe(false);
+    expect(rt.contexts[0].GroupSystemPrompt).toBe(mod.NO_TOOLS_TURN_NOTE);
+    expect(rt.toolResults).toEqual([{ block: true, blockReason: mod.TOOL_VETO_REASON }]);
+  });
+
+  it.each(NO_TOOL_SENDERS)("%s: without a hook API the turn is refused and acked", async (_name, authorization) => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime, { withHookApi: false });
+    deliver(ws, frame("m1", "room", "sender", authorization));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(rt.contexts).toEqual([]);
+  });
+
+  it("a hook API that throws on registration also refuses non-owner turns", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime, { onThrows: true });
+    deliver(ws, frame("m1", "room", "sender", noGrant("team_room")));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(rt.contexts).toEqual([]);
+  });
+
+  it("without a hook API the owner DM turn still runs", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime, { withHookApi: false });
+    deliver(ws, frame("m1", "dm", OWNER_ID, OWNER_AUTH));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(rt.contexts).toHaveLength(1);
+  });
+
+  it("a voice turn without tools carries the voice guidance and the note", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime);
+    deliver(ws, frame("v1", "room", "sender", noGrant("team_room"), { voice: true, guidance: "Be brief." }));
+    await waitFor(() => acksOf(ws).includes("v1"));
+    expect(rt.contexts[0].GroupSystemPrompt).toBe(`${mod.VOICE_TURN_PREFIX}Be brief.\n\n${mod.NO_TOOLS_TURN_NOTE}`);
+  });
+
+  it("a host that accepts api.on but has no registerTrustedToolPolicy is not trusted: non-owner turns are refused", async () => {
+    // H3: before 2026.4.27 a host can take the registration and still not
+    // block; the connector cannot tell, so it refuses instead.
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime, { withTrustedPolicyApi: false });
+    deliver(ws, frame("m1", "room", "sender", noGrant("team_room")));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(rt.contexts).toEqual([]);
+  });
+
+  it("registers the veto at a high priority", async () => {
+    const rt = makeRuntime(() => hook);
+    await start(rt.runtime);
+    expect(hookOpts).toEqual([{ priority: mod.TOOL_VETO_PRIORITY }]);
+    expect(mod.TOOL_VETO_PRIORITY).toBeGreaterThanOrEqual(1000);
+  });
+
+  // ---------------------------------------------------------- rollout ----
+
+  it("on connect, a hello tells the daemon the harness, its version and that the veto is active", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime);
+    expect(ws.sent.filter((f) => f.type === "hello")).toEqual([
+      { type: "hello", harness: { name: "openclaw", version: "2026.9.8", tool_veto: "active" } },
+    ]);
+  });
+
+  it("the hello reports an inactive veto on a host without the hook API", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime, { withHookApi: false });
+    expect(ws.sent.filter((f) => f.type === "hello")).toEqual([
+      { type: "hello", harness: { name: "openclaw", version: "2026.9.8", tool_veto: "inactive" } },
+    ]);
+  });
+
+  it("a refused turn gets one notice per channel, never to an agent", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime, { withHookApi: false });
+    deliver(ws, frame("m1", "room", "sender", noGrant("team_room")));
+    deliver(ws, frame("m2", "room", "sender", noGrant("team_room")));
+    deliver(ws, frame("m3", "room-2", "other", noGrant("partner_room")));
+    deliver(ws, frame("m4", "room-3", "agent-b", noGrant("agent_to_agent")));
+    await waitFor(() => ["m1", "m2", "m3", "m4"].every((id) => acksOf(ws).includes(id)));
+    expect(sends.map((b) => [b.channel_id, b.text])).toEqual([
+      ["room", mod.REFUSED_TURN_NOTICE],
+      ["room-2", mod.REFUSED_TURN_NOTICE],
+    ]);
+    expect(mod.REFUSED_TURN_NOTICE).toBe("I can't respond in this room until my owner updates me.");
+  });
+
+  it("with an active veto no notice is sent: the turn runs without tools", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime);
+    deliver(ws, frame("m1", "room", "sender", noGrant("team_room")));
+    await waitFor(() => acksOf(ws).includes("m1"));
+    expect(sends).toEqual([]);
+    expect(rt.contexts).toHaveLength(1);
+  });
+
+  it("frames without an authorization block are warned about loudly", async () => {
+    const rt = makeRuntime(() => hook);
+    const ws = await start(rt.runtime);
+    deliver(ws, frame("m1", "c", "s", MISSING));
+    deliver(ws, frame("m2", "c", "s", OWNER_AUTH));
+    await waitFor(() => acksOf(ws).includes("m1") && acksOf(ws).includes("m2"));
+    expect(logs.filter((l) => l.includes("NO authorization block"))).toHaveLength(1);
+  });
+
+  // ------------------------------------------------------------- hook ----
+
+  describe("the before_tool_call decision", () => {
+    it("blocks a SecureComs session it never saw, and one with no session key", async () => {
+      const rt = makeRuntime(() => hook);
+      await start(rt.runtime);
+      expect(await hook!({ toolName: "exec" }, { sessionKey: "agent:main:securecoms:direct:never" }))
+        .toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+      expect(await hook!({ toolName: "exec" }, { channelId: "securecoms" }))
+        .toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+      expect(await hook!({ toolName: "exec" }, { requester: { channel: "securecoms" } }))
+        .toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+    });
+
+    it("leaves other channels' sessions alone", async () => {
+      const rt = makeRuntime(() => hook);
+      await start(rt.runtime);
+      expect(await hook!({ toolName: "exec" }, { sessionKey: "agent:main:telegram:direct:42", channelId: "telegram" }))
+        .toBeUndefined();
+      expect(await hook!({ toolName: "exec" }, {})).toBeUndefined();
+    });
+
+    it("a requester who is not the granted sender is blocked inside the owner's session", async () => {
+      const rt = makeRuntime(() => hook);
+      const ws = await start(rt.runtime);
+      deliver(ws, frame("m1", "dm", OWNER_ID, OWNER_AUTH));
+      await waitFor(() => acksOf(ws).includes("m1"));
+      const key = rt.contexts[0].SessionKey;
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key, requester: { senderId: OWNER_ID } })).toBeUndefined();
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key, requester: { senderId: `securecoms:${OWNER_ID}` } })).toBeUndefined();
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key, requester: { senderId: "intruder" } }))
+        .toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+      // A requester the hook cannot read blocks rather than falling open.
+      const hostile = { toString() { throw new Error("unreadable"); } };
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key, requester: { senderId: hostile } }))
+        .toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+    });
+
+    it("an ungranted turn in the owner's session blocks tools there while it is in flight, and after it the latest turn decides", async () => {
+      const rt = makeRuntime(() => hook);
+      const ws = await start(rt.runtime);
+      deliver(ws, frame("m1", "dm", OWNER_ID, OWNER_AUTH));
+      await waitFor(() => acksOf(ws).includes("m1"));
+      const key = rt.contexts[0].SessionKey;
+      // Same DM channel, same chat type ("direct"), but no grant: e.g. the
+      // owner_dm audience with the default grants switched off.
+      rt.callToolDuringDispatch(() => ({ sessionKey: key }));
+      deliver(ws, frame("m2", "dm", OWNER_ID, noGrant("owner_dm")));
+      await waitFor(() => acksOf(ws).includes("m2"));
+      expect(rt.contexts[1].SessionKey).toBe(key);
+      expect(rt.toolResults).toEqual([{ block: true, blockReason: mod.TOOL_VETO_REASON }]);
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key })).toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+      deliver(ws, frame("m3", "dm", OWNER_ID, OWNER_AUTH));
+      await waitFor(() => acksOf(ws).includes("m3"));
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key })).toBeUndefined();
+    });
+
+    it("blocks the owner's session while ANOTHER ungranted turn for it is still dispatching", async () => {
+      const rt = makeRuntime(() => hook);
+      const ws = await start(rt.runtime);
+      deliver(ws, frame("m1", "dm", OWNER_ID, OWNER_AUTH));
+      await waitFor(() => acksOf(ws).includes("m1"));
+      const key = rt.contexts[0].SessionKey;
+      // Hold an ungranted turn in dispatch, then let the owner's next turn
+      // land: the owner turn is now the latest, but the ungranted one is
+      // still running in the same session.
+      let release!: () => void;
+      const held = new Promise<void>((r) => { release = r; });
+      const orig = rt.runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher;
+      rt.runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher = async (args: any) => {
+        if (args.ctx.MessageSid === "slow") await held;
+        return orig(args);
+      };
+      deliver(ws, frame("slow", "dm", OWNER_ID, noGrant("owner_dm")));
+      await waitFor(() => rt.contexts.length === 2);
+      deliver(ws, frame("m3", "dm", OWNER_ID, OWNER_AUTH));
+      await waitFor(() => acksOf(ws).includes("m3"));
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key })).toEqual({ block: true, blockReason: mod.TOOL_VETO_REASON });
+      release();
+      await waitFor(() => acksOf(ws).includes("slow"));
+      expect(await hook!({ toolName: "exec" }, { sessionKey: key })).toBeUndefined();
+    });
+  });
+});