predicate-claw 0.1.0

package/tests/multi-tenant-isolation.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AuthorizationRequest } from "@predicatesystems/authority";
+import {
+  type DecisionAuditExporter,
+  type DecisionTelemetryEvent,
+  GuardedProvider,
+} from "../src/provider.js";
+
+describe("multi-tenant isolation", () => {
+  it("propagates tenant_id through authorization request", async () => {
+    const capturedRequests: AuthorizationRequest[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockImplementation((req: AuthorizationRequest) => {
+        capturedRequests.push(req);
+        return Promise.resolve({ allow: true, reason: "policy_pass" });
+      }),
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:test-agent",
+      authorityClient: mockClient,
+    });
+
+    await provider.authorize({
+      action: "fs.read",
+      resource: "/workspace/file.txt",
+      args: { path: "/workspace/file.txt" },
+      context: {
+        tenant_id: "tenant-alpha",
+        session_id: "session-123",
+        source: "trusted_ui",
+      },
+    });
+
+    expect(capturedRequests).toHaveLength(1);
+    expect(capturedRequests[0].labels).toContain("source:trusted_ui");
+  });
+
+  it("isolates decisions by tenant in telemetry events", async () => {
+    const events: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi
+        .fn()
+        .mockResolvedValue({ allow: true, reason: "tenant_policy" }),
+    };
+
+    const telemetry = {
+      onDecision: (event: DecisionTelemetryEvent) => events.push(event),
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:multi-tenant-agent",
+      authorityClient: mockClient,
+      telemetry,
+    });
+
+    // Authorize as tenant A
+    await provider.authorize({
+      action: "shell.execute",
+      resource: "echo hello",
+      args: { cmd: "echo hello" },
+      context: { tenant_id: "tenant-a", user_id: "user-a1" },
+    });
+
+    // Authorize as tenant B
+    await provider.authorize({
+      action: "shell.execute",
+      resource: "echo world",
+      args: { cmd: "echo world" },
+      context: { tenant_id: "tenant-b", user_id: "user-b1" },
+    });
+
+    expect(events).toHaveLength(2);
+    expect(events[0].tenantId).toBe("tenant-a");
+    expect(events[0].userId).toBe("user-a1");
+    expect(events[1].tenantId).toBe("tenant-b");
+    expect(events[1].userId).toBe("user-b1");
+  });
+
+  it("audit exports include tenant isolation context", async () => {
+    const exportedEvents: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockResolvedValue({ allow: true }),
+    };
+
+    const auditExporter: DecisionAuditExporter = {
+      exportDecision: async (event) => {
+        exportedEvents.push(event);
+      },
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:audited-agent",
+      authorityClient: mockClient,
+      auditExporter,
+    });
+
+    await provider.authorize({
+      action: "net.http",
+      resource: "https://api.example.com/data",
+      args: { method: "GET", url: "https://api.example.com/data" },
+      context: {
+        tenant_id: "tenant-enterprise",
+        session_id: "sess-456",
+        trace_id: "trace-abc",
+        source: "trusted_ui",
+      },
+    });
+
+    expect(exportedEvents).toHaveLength(1);
+    expect(exportedEvents[0].tenantId).toBe("tenant-enterprise");
+    expect(exportedEvents[0].sessionId).toBe("sess-456");
+    expect(exportedEvents[0].traceId).toBe("trace-abc");
+    expect(exportedEvents[0].source).toBe("trusted_ui");
+  });
+
+  it("denials preserve tenant context in error events", async () => {
+    const events: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockResolvedValue({
+        allow: false,
+        reason: "tenant_quota_exceeded",
+      }),
+    };
+
+    const telemetry = {
+      onDecision: (event: DecisionTelemetryEvent) => events.push(event),
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:quota-agent",
+      authorityClient: mockClient,
+      telemetry,
+    });
+
+    await expect(
+      provider.authorize({
+        action: "shell.execute",
+        resource: "rm -rf /",
+        args: { cmd: "rm -rf /" },
+        context: { tenant_id: "tenant-restricted" },
+      }),
+    ).rejects.toThrow();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].outcome).toBe("deny");
+    expect(events[0].tenantId).toBe("tenant-restricted");
+    expect(events[0].reason).toBe("tenant_quota_exceeded");
+  });
+
+  it("handles missing tenant context gracefully", async () => {
+    const events: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockResolvedValue({ allow: true }),
+    };
+
+    const telemetry = {
+      onDecision: (event: DecisionTelemetryEvent) => events.push(event),
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:no-tenant",
+      authorityClient: mockClient,
+      telemetry,
+    });
+
+    await provider.authorize({
+      action: "fs.read",
+      resource: "/tmp/file.txt",
+      args: { path: "/tmp/file.txt" },
+      // No context provided
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].tenantId).toBeUndefined();
+    expect(events[0].sessionId).toBeUndefined();
+  });
+});

package/tests/non-web-evidence.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import {
+  OpenClawDesktopAccessibilityEvidenceProvider,
+  OpenClawTerminalEvidenceProvider,
+  buildDesktopEvidenceFromProvider,
+  buildTerminalEvidenceFromProvider,
+} from "../src/non-web-evidence.js";
+
+describe("non-web evidence providers", () => {
+  describe("legacy mode (useCanonicalHash=false)", () => {
+    it("builds terminal session state evidence", async () => {
+      const provider = new OpenClawTerminalEvidenceProvider(() => ({
+        sessionId: "s-1",
+        terminalId: "t-1",
+        cwd: "/workspace",
+        command: "cat secrets.txt",
+        transcript: "line1\nline2\n",
+        observedAt: "2026-02-20T08:00:00.000Z",
+        confidence: 0.92,
+      }));
+
+      const snapshot = await provider.captureTerminalSnapshot();
+      const evidence = await buildTerminalEvidenceFromProvider(provider, {
+        useCanonicalHash: false,
+      });
+
+      expect(snapshot.session_id).toBe("s-1");
+      expect(snapshot.transcript_hash).toEqual(expect.any(String));
+      expect(evidence).toMatchObject({
+        source: "terminal",
+        schema_version: "terminal-v1",
+        confidence: 0.92,
+      });
+      expect(evidence.state_hash).toEqual(expect.any(String));
+    });
+
+    it("builds desktop accessibility state evidence", async () => {
+      const provider = new OpenClawDesktopAccessibilityEvidenceProvider(() => ({
+        appName: "Terminal",
+        windowTitle: "Deploy Prod",
+        focusedRole: "button",
+        focusedName: "Confirm",
+        uiTreeText: "root > dialog > button:Confirm",
+        observedAt: "2026-02-20T08:01:00.000Z",
+        confidence: 0.88,
+      }));
+
+      const snapshot = await provider.captureAccessibilitySnapshot();
+      const evidence = await buildDesktopEvidenceFromProvider(provider, {
+        useCanonicalHash: false,
+      });
+
+      expect(snapshot.ui_tree_hash).toEqual(expect.any(String));
+      expect(evidence).toMatchObject({
+        source: "desktop_accessibility",
+        schema_version: "desktop-a11y-v1",
+        confidence: 0.88,
+      });
+      expect(evidence.state_hash).toEqual(expect.any(String));
+    });
+  });
+
+  describe("canonical mode (default)", () => {
+    it("builds terminal evidence with canonical schema version", async () => {
+      const provider = new OpenClawTerminalEvidenceProvider(() => ({
+        sessionId: "s-1",
+        terminalId: "t-1",
+        cwd: "/workspace",
+        command: "npm test",
+        transcript: "\x1b[32mPASS\x1b[0m all tests",
+        observedAt: "2026-02-20T08:00:00.000Z",
+        confidence: 0.95,
+      }));
+
+      const evidence = await buildTerminalEvidenceFromProvider(provider);
+
+      expect(evidence).toMatchObject({
+        source: "terminal",
+        schema_version: "terminal:v1.0",
+        confidence: 0.95,
+      });
+      expect(evidence.state_hash).toMatch(/^sha256:[a-f0-9]{64}$/);
+    });
+
+    it("builds desktop evidence with canonical schema version", async () => {
+      const provider = new OpenClawDesktopAccessibilityEvidenceProvider(() => ({
+        appName: "Firefox",
+        windowTitle: "GitHub",
+        focusedRole: "button",
+        focusedName: "Submit",
+        uiTreeText: "window > form > button:Submit",
+        observedAt: "2026-02-20T08:01:00.000Z",
+        confidence: 0.9,
+      }));
+
+      const evidence = await buildDesktopEvidenceFromProvider(provider);
+
+      expect(evidence).toMatchObject({
+        source: "desktop_accessibility",
+        schema_version: "desktop:v1.0",
+        confidence: 0.9,
+      });
+      expect(evidence.state_hash).toMatch(/^sha256:[a-f0-9]{64}$/);
+    });
+
+    it("produces stable hashes for equivalent terminal inputs", async () => {
+      // Same content with different whitespace/ANSI codes
+      const provider1 = new OpenClawTerminalEvidenceProvider(() => ({
+        sessionId: "s-1",
+        command: "  npm   test  ",
+        transcript: "\x1b[32mOK\x1b[0m",
+      }));
+
+      const provider2 = new OpenClawTerminalEvidenceProvider(() => ({
+        sessionId: "s-1",
+        command: "npm test",
+        transcript: "OK",
+      }));
+
+      const evidence1 = await buildTerminalEvidenceFromProvider(provider1);
+      const evidence2 = await buildTerminalEvidenceFromProvider(provider2);
+
+      // Canonical hashing should produce identical hashes
+      expect(evidence1.state_hash).toBe(evidence2.state_hash);
+    });
+
+    it("produces stable hashes for equivalent desktop inputs", async () => {
+      // Same content with different whitespace
+      const provider1 = new OpenClawDesktopAccessibilityEvidenceProvider(() => ({
+        appName: "  Firefox  ",
+        windowTitle: "  GitHub  ",
+        focusedRole: "BUTTON",
+        focusedName: "  Submit  ",
+      }));
+
+      const provider2 = new OpenClawDesktopAccessibilityEvidenceProvider(() => ({
+        appName: "Firefox",
+        windowTitle: "GitHub",
+        focusedRole: "button",
+        focusedName: "Submit",
+      }));
+
+      const evidence1 = await buildDesktopEvidenceFromProvider(provider1);
+      const evidence2 = await buildDesktopEvidenceFromProvider(provider2);
+
+      // Canonical hashing should produce identical hashes
+      expect(evidence1.state_hash).toBe(evidence2.state_hash);
+    });
+
+    it("passes raw transcript for canonical hashing in SDK", async () => {
+      const provider = new OpenClawTerminalEvidenceProvider(() => ({
+        sessionId: "s-1",
+        transcript: "\x1b[31mERROR\x1b[0m: something went wrong",
+      }));
+
+      const snapshot = await provider.captureTerminalSnapshot();
+
+      // transcript_hash now contains raw text (hashing is done by SDK when useCanonicalHash=true)
+      expect(snapshot.transcript_hash).toEqual(expect.any(String));
+      // Raw transcript with ANSI codes is 36 chars
+      expect(snapshot.transcript_hash).toBe("\x1b[31mERROR\x1b[0m: something went wrong");
+
+      // Verify the final evidence hash is canonical (sha256-prefixed)
+      const evidence = await buildTerminalEvidenceFromProvider(provider);
+      expect(evidence.state_hash).toMatch(/^sha256:[a-f0-9]{64}$/);
+    });
+  });
+});

package/tests/openclaw-hooks.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { HookEnvelope, OpenClawHooks } from "../src/openclaw-hooks.js";
+
+describe("OpenClawHooks", () => {
+  it("renders hook context shape", () => {
+    const env = new HookEnvelope({
+      toolName: "cmd.run",
+      args: { command: "echo hi" },
+      sessionId: "s1",
+      source: "trusted_ui",
+      tenantId: "t1",
+      userId: "u1",
+      traceId: "tr1",
+    });
+
+    expect(env.context()).toMatchObject({
+      source: "trusted_ui",
+      tenant_id: "t1",
+    });
+  });
+
+  it("routes cmd hooks through the shell guard", async () => {
+    const calls: string[] = [];
+    const hooks = new OpenClawHooks({
+      runShell: async ({ execute, args }) => {
+        calls.push("shell");
+        return execute(args);
+      },
+      readFile: async ({ execute, args }) => execute(args),
+      httpRequest: async ({ execute, args }) => execute(args),
+    });
+
+    const result = await hooks.onCmdRun(
+      new HookEnvelope({
+        toolName: "cmd.run",
+        args: { command: "echo hi" },
+        sessionId: "s1",
+        source: "trusted_ui",
+      }),
+      async (args) => args,
+    );
+
+    expect(result).toEqual({ command: "echo hi" });
+    expect(calls).toEqual(["shell"]);
+  });
+});

package/tests/openclaw-plugin-api.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { registerOpenClawPredicateTools } from "../src/openclaw-plugin-api.js";
+
+interface RegisteredTool {
+  name: string;
+  execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+}
+
+describe("registerOpenClawPredicateTools", () => {
+  it("registers cmd/fs/http tools via registerTool API", async () => {
+    const registered: RegisteredTool[] = [];
+    const api = {
+      registerTool: (tool: RegisteredTool) => {
+        registered.push(tool);
+      },
+    };
+    const calls: string[] = [];
+
+    registerOpenClawPredicateTools(api, {
+      executeCmdRun: async (args) => {
+        calls.push(`cmd:${String(args.command ?? "")}`);
+        return { ok: true };
+      },
+      executeFsReadFile: async (args) => {
+        calls.push(`fs:${String(args.path ?? "")}`);
+        return { ok: true };
+      },
+      executeHttpRequest: async (args) => {
+        calls.push(`http:${String(args.url ?? "")}`);
+        return { ok: true };
+      },
+    });
+
+    expect(registered.map((tool) => tool.name)).toEqual([
+      "predicate_cmd_run",
+      "predicate_fs_read_file",
+      "predicate_http_request",
+    ]);
+
+    await registered[0].execute("run-1", { command: "echo hi" });
+    await registered[1].execute("run-2", { path: "/tmp/demo" });
+    await registered[2].execute("run-3", { url: "https://example.com" });
+
+    expect(calls).toEqual([
+      "cmd:echo hi",
+      "fs:/tmp/demo",
+      "http:https://example.com",
+    ]);
+  });
+});

package/tests/provider.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from "vitest";
+import {
+  ActionDeniedError,
+  GuardedProvider,
+  SidecarUnavailableError,
+} from "../src/provider.js";
+
+describe("GuardedProvider", () => {
+  it("builds deterministic intent hash", () => {
+    const first = GuardedProvider.intentHash({ cmd: "ls", flags: ["-la"] });
+    const second = GuardedProvider.intentHash({ flags: ["-la"], cmd: "ls" });
+
+    expect(first).toBe(second);
+  });
+
+  it("fails closed when sidecar is unavailable", async () => {
+    const provider = new GuardedProvider({
+      principal: "p1",
+      config: { failClosed: true },
+      authorityClient: {
+        authorize: async () => {
+          throw new SidecarUnavailableError("down");
+        },
+      },
+    });
+
+    await expect(
+      provider.guardOrThrow({
+        action: "shell.execute",
+        resource: "echo hi",
+        args: { command: "echo hi" },
+      }),
+    ).rejects.toBeInstanceOf(SidecarUnavailableError);
+  });
+
+  it("returns null in fail-open mode when sidecar is unavailable", async () => {
+    const provider = new GuardedProvider({
+      principal: "p1",
+      config: { failClosed: false },
+      authorityClient: {
+        authorize: async () => {
+          throw new SidecarUnavailableError("down");
+        },
+      },
+    });
+
+    await expect(
+      provider.guardOrThrow({
+        action: "shell.execute",
+        resource: "echo hi",
+        args: { command: "echo hi" },
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it("emits decision telemetry for allow and deny", async () => {
+    const events: Array<{ outcome: string; reason?: string }> = [];
+    const provider = new GuardedProvider({
+      principal: "p1",
+      telemetry: {
+        onDecision: (event) => {
+          events.push({ outcome: event.outcome, reason: event.reason });
+        },
+      },
+      authorityClient: {
+        authorize: async (request) => ({
+          allow: request.action !== "fs.read",
+          reason: request.action === "fs.read" ? "explicit_deny" : "allowed",
+          mandateId: request.action === "fs.read" ? undefined : "mnd_ok",
+        }),
+      },
+    });
+
+    await expect(
+      provider.guardOrThrow({
+        action: "shell.execute",
+        resource: "echo hi",
+        args: { command: "echo hi" },
+        context: { source: "trusted_ui" },
+      }),
+    ).resolves.toBe("mnd_ok");
+
+    await expect(
+      provider.guardOrThrow({
+        action: "fs.read",
+        resource: "/etc/passwd",
+        args: { path: "/etc/passwd" },
+        context: { source: "untrusted_dm" },
+      }),
+    ).rejects.toBeInstanceOf(ActionDeniedError);
+
+    expect(events).toEqual([
+      { outcome: "allow", reason: "allowed" },
+      { outcome: "deny", reason: "explicit_deny" },
+    ]);
+  });
+
+  it("sends canonical wire request fields to authority client", async () => {
+    let captured: Record<string, unknown> | undefined;
+    const provider = new GuardedProvider({
+      principal: "agent:openclaw-local",
+      authorityClient: {
+        authorize: async (request) => {
+          captured = request as unknown as Record<string, unknown>;
+          return { allow: true, reason: "allowed", mandateId: "mnd_ok" };
+        },
+      },
+    });
+
+    await provider.guardOrThrow({
+      action: "shell.execute",
+      resource: "echo hi",
+      args: { command: "echo hi", flags: ["-n"] },
+      context: { source: "trusted_ui", session_id: "s1" },
+    });
+
+    expect(captured).toBeDefined();
+    expect(captured?.principal).toBe("agent:openclaw-local");
+    expect(captured?.action).toBe("shell.execute");
+    expect(captured?.resource).toBe("echo hi");
+    expect(captured?.intent_hash).toEqual(expect.any(String));
+    expect(captured?.labels).toEqual(["source:trusted_ui"]);
+  });
+
+  it("exports decision audit events with correlation context", async () => {
+    const exported: Array<Record<string, unknown>> = [];
+    const provider = new GuardedProvider({
+      principal: "agent:openclaw-local",
+      auditExporter: {
+        exportDecision: async (event) => {
+          exported.push(event as unknown as Record<string, unknown>);
+        },
+      },
+      authorityClient: {
+        authorize: async () => ({
+          allow: true,
+          reason: "allowed",
+          mandateId: "mnd_123",
+        }),
+      },
+    });
+
+    await provider.guardOrThrow({
+      action: "shell.execute",
+      resource: "echo hi",
+      args: { command: "echo hi" },
+      context: {
+        source: "trusted_ui",
+        session_id: "session-1",
+        tenant_id: "tenant-1",
+        trace_id: "trace-1",
+      },
+    });
+
+    expect(exported).toHaveLength(1);
+    expect(exported[0]).toMatchObject({
+      principal: "agent:openclaw-local",
+      action: "shell.execute",
+      outcome: "allow",
+      mandateId: "mnd_123",
+      sessionId: "session-1",
+      tenantId: "tenant-1",
+      traceId: "trace-1",
+    });
+  });
+
+  it("does not block authorization if audit export fails", async () => {
+    const provider = new GuardedProvider({
+      principal: "agent:openclaw-local",
+      auditExporter: {
+        exportDecision: async () => {
+          throw new Error("audit export unavailable");
+        },
+      },
+      authorityClient: {
+        authorize: async () => ({
+          allow: true,
+          reason: "allowed",
+          mandateId: "mnd_456",
+        }),
+      },
+    });
+
+    await expect(
+      provider.guardOrThrow({
+        action: "shell.execute",
+        resource: "echo ok",
+        args: { command: "echo ok" },
+        context: { source: "trusted_ui" },
+      }),
+    ).resolves.toBe("mnd_456");
+  });
+
+  it("preserves deny reason and redacts sensitive resource in audit export", async () => {
+    const exported: Array<Record<string, unknown>> = [];
+    const provider = new GuardedProvider({
+      principal: "agent:openclaw-local",
+      auditExporter: {
+        exportDecision: async (event) => {
+          exported.push(event as unknown as Record<string, unknown>);
+        },
+      },
+      authorityClient: {
+        authorize: async () => ({
+          allow: false,
+          reason: "deny_sensitive_read_from_untrusted_context",
+        }),
+      },
+    });
+
+    await expect(
+      provider.guardOrThrow({
+        action: "fs.read",
+        resource: "/Users/demo/.ssh/id_rsa",
+        args: { path: "/Users/demo/.ssh/id_rsa" },
+        context: { source: "untrusted_dm" },
+      }),
+    ).rejects.toBeInstanceOf(ActionDeniedError);
+
+    expect(exported).toHaveLength(1);
+    expect(exported[0]).toMatchObject({
+      outcome: "deny",
+      reason: "deny_sensitive_read_from_untrusted_context",
+      resource: "[REDACTED]",
+    });
+  });
+});