predicate-claw 0.1.0

package/dist/tests/load-latency.test.js

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from "vitest";
+import { GuardedProvider } from "../src/provider.js";
+/**
+ * Load and latency tests for high-frequency tool invocation paths.
+ *
+ * These tests verify that the provider can handle burst traffic while
+ * maintaining acceptable latency characteristics.
+ */
+describe("load and latency", () => {
+    it("handles burst of 100 sequential authorizations under 500ms total", async () => {
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({ allow: true, mandateId: "m1" }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:load-test",
+            authorityClient: mockClient,
+        });
+        const iterations = 100;
+        const start = performance.now();
+        for (let i = 0; i < iterations; i++) {
+            await provider.authorize({
+                action: "fs.read",
+                resource: `/workspace/file-${i}.txt`,
+                args: { path: `/workspace/file-${i}.txt` },
+            });
+        }
+        const elapsed = performance.now() - start;
+        expect(mockClient.authorize).toHaveBeenCalledTimes(iterations);
+        // 100 calls should complete well under 500ms with mocked client
+        expect(elapsed).toBeLessThan(500);
+    });
+    it("handles 50 concurrent authorizations", async () => {
+        const mockClient = {
+            authorize: vi.fn().mockImplementation(async () => {
+                // Simulate small network delay
+                await new Promise((r) => setTimeout(r, 1));
+                return { allow: true, mandateId: "m1" };
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:concurrent-test",
+            authorityClient: mockClient,
+        });
+        const concurrency = 50;
+        const start = performance.now();
+        const promises = Array.from({ length: concurrency }, (_, i) => provider.authorize({
+            action: "shell.execute",
+            resource: `echo test-${i}`,
+            args: { cmd: `echo test-${i}` },
+        }));
+        const results = await Promise.all(promises);
+        const elapsed = performance.now() - start;
+        expect(results).toHaveLength(concurrency);
+        expect(mockClient.authorize).toHaveBeenCalledTimes(concurrency);
+        // Concurrent calls should complete faster than sequential
+        expect(elapsed).toBeLessThan(200);
+    });
+    it("maintains intent_hash computation performance", () => {
+        const iterations = 1000;
+        const start = performance.now();
+        for (let i = 0; i < iterations; i++) {
+            GuardedProvider.intentHash({
+                cmd: `echo "iteration ${i}"`,
+                workdir: "/workspace",
+                env: { NODE_ENV: "test", ITERATION: String(i) },
+            });
+        }
+        const elapsed = performance.now() - start;
+        // 1000 hash computations should complete under 100ms
+        expect(elapsed).toBeLessThan(100);
+    });
+    it("measures p50/p95 latency for authorization calls", async () => {
+        const latencies = [];
+        const mockClient = {
+            authorize: vi.fn().mockImplementation(async () => {
+                // Simulate variable latency (1-5ms)
+                const delay = 1 + Math.random() * 4;
+                await new Promise((r) => setTimeout(r, delay));
+                return { allow: true };
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:latency-test",
+            authorityClient: mockClient,
+        });
+        const iterations = 50;
+        for (let i = 0; i < iterations; i++) {
+            const start = performance.now();
+            await provider.authorize({
+                action: "net.http",
+                resource: "https://api.example.com",
+                args: { url: "https://api.example.com" },
+            });
+            latencies.push(performance.now() - start);
+        }
+        latencies.sort((a, b) => a - b);
+        const p50 = latencies[Math.floor(iterations * 0.5)];
+        const p95 = latencies[Math.floor(iterations * 0.95)];
+        // Verify latency targets from design doc (with mocked overhead)
+        // Design targets: p50 < 25ms, p95 < 75ms
+        // With mocked 1-5ms delay, we expect p50 < 15ms, p95 < 20ms
+        expect(p50).toBeLessThan(25);
+        expect(p95).toBeLessThan(75);
+    });
+    it("handles mixed allow/deny outcomes under load", async () => {
+        let callCount = 0;
+        const mockClient = {
+            authorize: vi.fn().mockImplementation(async () => {
+                callCount++;
+                // Alternate between allow and deny
+                if (callCount % 3 === 0) {
+                    return { allow: false, reason: "rate_limited" };
+                }
+                return { allow: true, mandateId: `m${callCount}` };
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:mixed-test",
+            authorityClient: mockClient,
+        });
+        const iterations = 30;
+        const results = { allowed: 0, denied: 0 };
+        for (let i = 0; i < iterations; i++) {
+            try {
+                await provider.authorize({
+                    action: "fs.write",
+                    resource: `/workspace/file-${i}.txt`,
+                    args: { path: `/workspace/file-${i}.txt`, content: "data" },
+                });
+                results.allowed++;
+            }
+            catch {
+                results.denied++;
+            }
+        }
+        expect(results.allowed).toBe(20); // 2/3 allowed
+        expect(results.denied).toBe(10); // 1/3 denied
+        expect(mockClient.authorize).toHaveBeenCalledTimes(iterations);
+    });
+    it("telemetry emission does not block authorization path", async () => {
+        const telemetryDelays = [];
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({ allow: true }),
+        };
+        const slowTelemetry = {
+            onDecision: vi.fn().mockImplementation(() => {
+                // Simulate slow telemetry (should not block auth)
+                const start = performance.now();
+                while (performance.now() - start < 1) {
+                    // Busy wait 1ms
+                }
+                telemetryDelays.push(performance.now() - start);
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:telemetry-test",
+            authorityClient: mockClient,
+            telemetry: slowTelemetry,
+        });
+        const iterations = 10;
+        const start = performance.now();
+        for (let i = 0; i < iterations; i++) {
+            await provider.authorize({
+                action: "fs.read",
+                resource: `/file-${i}.txt`,
+                args: { path: `/file-${i}.txt` },
+            });
+        }
+        const elapsed = performance.now() - start;
+        // Even with slow telemetry, auth should complete reasonably fast
+        // Telemetry runs synchronously here, but in production would be async
+        expect(elapsed).toBeLessThan(100);
+        expect(slowTelemetry.onDecision).toHaveBeenCalledTimes(iterations);
+    });
+});

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

@@ -0,0 +1 @@
+export {};

package/dist/tests/multi-tenant-isolation.test.js

@@ -0,0 +1,146 @@
+import { describe, expect, it, vi } from "vitest";
+import { GuardedProvider, } from "../src/provider.js";
+describe("multi-tenant isolation", () => {
+    it("propagates tenant_id through authorization request", async () => {
+        const capturedRequests = [];
+        const mockClient = {
+            authorize: vi.fn().mockImplementation((req) => {
+                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 = [];
+        const mockClient = {
+            authorize: vi
+                .fn()
+                .mockResolvedValue({ allow: true, reason: "tenant_policy" }),
+        };
+        const telemetry = {
+            onDecision: (event) => 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 = [];
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({ allow: true }),
+        };
+        const auditExporter = {
+            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 = [];
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({
+                allow: false,
+                reason: "tenant_quota_exceeded",
+            }),
+        };
+        const telemetry = {
+            onDecision: (event) => 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 = [];
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({ allow: true }),
+        };
+        const telemetry = {
+            onDecision: (event) => 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/dist/tests/non-web-evidence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/non-web-evidence.test.js

@@ -0,0 +1,139 @@
+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/dist/tests/openclaw-hooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/openclaw-hooks.test.js

@@ -0,0 +1,38 @@
+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 = [];
+        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/dist/tests/openclaw-plugin-api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/openclaw-plugin-api.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { registerOpenClawPredicateTools } from "../src/openclaw-plugin-api.js";
+describe("registerOpenClawPredicateTools", () => {
+    it("registers cmd/fs/http tools via registerTool API", async () => {
+        const registered = [];
+        const api = {
+            registerTool: (tool) => {
+                registered.push(tool);
+            },
+        };
+        const calls = [];
+        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/dist/tests/provider.test.d.ts

@@ -0,0 +1 @@
+export {};