predicate-claw 0.1.0

package/dist/tests/provider.test.js

@@ -0,0 +1,190 @@
+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 = [];
+        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;
+        const provider = new GuardedProvider({
+            principal: "agent:openclaw-local",
+            authorityClient: {
+                authorize: async (request) => {
+                    captured = request;
+                    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 = [];
+        const provider = new GuardedProvider({
+            principal: "agent:openclaw-local",
+            auditExporter: {
+                exportDecision: async (event) => {
+                    exported.push(event);
+                },
+            },
+            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 = [];
+        const provider = new GuardedProvider({
+            principal: "agent:openclaw-local",
+            auditExporter: {
+                exportDecision: async (event) => {
+                    exported.push(event);
+                },
+            },
+            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]",
+        });
+    });
+});

package/dist/tests/runtime-integration.test.d.ts

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

package/dist/tests/runtime-integration.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { HookEnvelope } from "../src/openclaw-hooks.js";
+import { OpenClawRuntimeIntegrator } from "../src/runtime-integration.js";
+class Registry {
+    handlers = {
+        "cmd.run": async (args) => ({ tool: "cmd.run", args }),
+        "fs.readFile": async (args) => ({ tool: "fs.readFile", args }),
+        "http.request": async (args) => ({ tool: "http.request", args }),
+    };
+    get(toolName) {
+        return this.handlers[toolName];
+    }
+    set(toolName, handler) {
+        this.handlers[toolName] = handler;
+    }
+    invoke(toolName, args) {
+        return this.handlers[toolName](args);
+    }
+}
+describe("OpenClawRuntimeIntegrator", () => {
+    it("wraps sensitive handlers and routes through hooks", async () => {
+        const seen = [];
+        const registry = new Registry();
+        const hooks = {
+            onCmdRun: async (envelope, execute) => {
+                seen.push(`cmd:${envelope.toolName}`);
+                return execute(envelope.args);
+            },
+            onFsRead: async (envelope, execute) => {
+                seen.push(`fs:${envelope.toolName}`);
+                return execute(envelope.args);
+            },
+            onHttpRequest: async (envelope, execute) => {
+                seen.push(`http:${envelope.toolName}`);
+                return execute(envelope.args);
+            },
+        };
+        const integrator = new OpenClawRuntimeIntegrator({
+            hooks,
+            contextBuilder: (toolName, args) => new HookEnvelope({
+                toolName,
+                args,
+                sessionId: "s1",
+                source: "trusted_ui",
+                tenantId: "t1",
+            }),
+        });
+        integrator.register(registry);
+        const cmd = await registry.invoke("cmd.run", { command: "echo hi" });
+        const fs = await registry.invoke("fs.readFile", { path: "/tmp/demo" });
+        const http = await registry.invoke("http.request", { url: "https://example.com" });
+        expect(cmd).toMatchObject({ tool: "cmd.run" });
+        expect(fs).toMatchObject({ tool: "fs.readFile" });
+        expect(http).toMatchObject({ tool: "http.request" });
+        expect(seen).toEqual(["cmd:cmd.run", "fs:fs.readFile", "http:http.request"]);
+    });
+});

package/dist/tests/web-evidence.test.d.ts

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

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

@@ -0,0 +1,89 @@
+import crypto from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { buildWebEvidenceFromProvider, buildWebEvidenceFromRuntimeSnapshot, OpenClawWebEvidenceProvider, } from "../src/web-evidence.js";
+function sha256(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+describe("web evidence providers", () => {
+    it("builds web state evidence from OpenClaw runtime context", async () => {
+        const mockContext = {
+            url: "https://example.com/dashboard",
+            title: "Dashboard - Example App",
+            domHtml: "<html><body><h1>Dashboard</h1></body></html>",
+            visibleText: "Dashboard",
+            eventId: "evt-123",
+            observedAt: "2026-02-20T12:00:00Z",
+            dominantGroupKey: "main-content",
+            confidence: 0.95,
+            confidenceReasons: ["stable_dom", "no_pending_requests"],
+        };
+        const provider = new OpenClawWebEvidenceProvider(() => mockContext);
+        const evidence = await buildWebEvidenceFromProvider(provider);
+        expect(evidence.source).toBe("browser");
+        expect(evidence.schema_version).toBe("v1");
+        expect(evidence.state_hash).toBeDefined();
+        expect(typeof evidence.state_hash).toBe("string");
+        expect(evidence.confidence).toBe(0.95);
+    });
+    it("computes dom_hash when domHtml provided without domHash", async () => {
+        const domHtml = "<html><body>Test</body></html>";
+        const expectedHash = sha256(domHtml);
+        const provider = new OpenClawWebEvidenceProvider(() => ({
+            url: "https://example.com",
+            domHtml,
+        }));
+        const snapshot = await provider.captureWebSnapshot();
+        expect(snapshot.dom_hash).toBe(expectedHash);
+    });
+    it("computes visible_text_hash when visibleText provided without hash", async () => {
+        const visibleText = "Hello World";
+        const expectedHash = sha256(visibleText);
+        const provider = new OpenClawWebEvidenceProvider(() => ({
+            url: "https://example.com",
+            visibleText,
+        }));
+        const snapshot = await provider.captureWebSnapshot();
+        expect(snapshot.visible_text_hash).toBe(expectedHash);
+    });
+    it("uses provided hashes when available", async () => {
+        const precomputedDomHash = "abc123";
+        const precomputedTextHash = "def456";
+        const provider = new OpenClawWebEvidenceProvider(() => ({
+            url: "https://example.com",
+            domHash: precomputedDomHash,
+            visibleTextHash: precomputedTextHash,
+        }));
+        const snapshot = await provider.captureWebSnapshot();
+        expect(snapshot.dom_hash).toBe(precomputedDomHash);
+        expect(snapshot.visible_text_hash).toBe(precomputedTextHash);
+    });
+    it("builds evidence from predicate-runtime snapshot format", () => {
+        const runtimeSnapshot = {
+            url: "https://example.com/page",
+            timestamp: "2026-02-20T12:00:00Z",
+            dominant_group_key: "content-area",
+            diagnostics: {
+                confidence: 0.88,
+                reasons: ["dom_stable"],
+            },
+        };
+        const evidence = buildWebEvidenceFromRuntimeSnapshot(runtimeSnapshot);
+        expect(evidence.source).toBe("browser");
+        expect(evidence.schema_version).toBe("v1");
+        expect(evidence.confidence).toBe(0.88);
+    });
+    it("handles async capture functions", async () => {
+        const asyncCapture = async () => {
+            await new Promise((resolve) => setTimeout(resolve, 1));
+            return {
+                url: "https://async.example.com",
+                title: "Async Page",
+            };
+        };
+        const provider = new OpenClawWebEvidenceProvider(asyncCapture);
+        const snapshot = await provider.captureWebSnapshot();
+        expect(snapshot.url).toBe("https://async.example.com");
+        expect(snapshot.title).toBe("Async Page");
+        expect(snapshot.observed_at).toBeDefined();
+    });
+});