predicate-claw 0.1.0

package/dist/tests/authority-client.test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { createAuthorityAdapter } from "../src/authority-client.js";
+describe("createAuthorityAdapter", () => {
+    it("maps SDK allow decisions", async () => {
+        const adapter = createAuthorityAdapter({
+            authorize: async () => ({
+                allowed: true,
+                reason: "allowed",
+                mandate_id: "mnd_ok",
+            }),
+        });
+        const decision = await adapter.authorize({
+            principal: "agent:openclaw-local",
+            action: "shell.execute",
+            resource: "echo hi",
+            intent_hash: "ih",
+            labels: [],
+        });
+        expect(decision).toEqual({
+            allow: true,
+            reason: "allowed",
+            mandateId: "mnd_ok",
+        });
+    });
+    it("maps SDK deny decisions", async () => {
+        const adapter = createAuthorityAdapter({
+            authorize: async () => ({
+                allowed: false,
+                reason: "explicit_deny",
+                mandate_id: undefined,
+            }),
+        });
+        const decision = await adapter.authorize({
+            principal: "agent:openclaw-local",
+            action: "fs.read",
+            resource: "/etc/passwd",
+            intent_hash: "ih",
+            labels: ["source:untrusted_dm"],
+        });
+        expect(decision).toEqual({
+            allow: false,
+            reason: "explicit_deny",
+            mandateId: undefined,
+        });
+    });
+});

package/dist/tests/circuit-breaker.test.d.ts

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

package/dist/tests/circuit-breaker.test.js

@@ -0,0 +1,200 @@
+import { describe, expect, it, vi } from "vitest";
+import { calculateBackoff, CircuitBreaker, CircuitOpenError, defaultBackoffConfig, defaultCircuitBreakerConfig, withCircuitBreaker, } from "../src/circuit-breaker.js";
+describe("CircuitBreaker", () => {
+    it("starts in closed state", () => {
+        const breaker = new CircuitBreaker(defaultCircuitBreakerConfig);
+        expect(breaker.getState()).toBe("closed");
+        expect(breaker.allowRequest()).toBe(true);
+    });
+    it("opens after reaching failure threshold", () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 3,
+        });
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("closed");
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("closed");
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("open");
+        expect(breaker.allowRequest()).toBe(false);
+    });
+    it("transitions to half-open after reset timeout", async () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 1,
+            resetTimeoutMs: 50,
+        });
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("open");
+        expect(breaker.allowRequest()).toBe(false);
+        // Wait for reset timeout
+        await new Promise((r) => setTimeout(r, 60));
+        expect(breaker.allowRequest()).toBe(true);
+        expect(breaker.getState()).toBe("half_open");
+    });
+    it("closes after success threshold in half-open", async () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 1,
+            resetTimeoutMs: 10,
+            successThreshold: 2,
+        });
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("open");
+        await new Promise((r) => setTimeout(r, 15));
+        breaker.allowRequest(); // Triggers half-open
+        expect(breaker.getState()).toBe("half_open");
+        breaker.recordSuccess();
+        expect(breaker.getState()).toBe("half_open");
+        breaker.recordSuccess();
+        expect(breaker.getState()).toBe("closed");
+    });
+    it("reopens on failure in half-open state", async () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 1,
+            resetTimeoutMs: 10,
+        });
+        breaker.recordFailure();
+        await new Promise((r) => setTimeout(r, 15));
+        breaker.allowRequest();
+        expect(breaker.getState()).toBe("half_open");
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("open");
+    });
+    it("resets failure count on success in closed state", () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 3,
+        });
+        breaker.recordFailure();
+        breaker.recordFailure();
+        breaker.recordSuccess();
+        breaker.recordFailure();
+        breaker.recordFailure();
+        // Should still be closed because success reset the count
+        expect(breaker.getState()).toBe("closed");
+    });
+    it("tracks metrics correctly", () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 2,
+        });
+        breaker.recordSuccess();
+        breaker.recordSuccess();
+        breaker.recordFailure();
+        breaker.recordFailure();
+        breaker.allowRequest(); // Should be rejected
+        const metrics = breaker.getMetrics();
+        expect(metrics.totalSuccesses).toBe(2);
+        expect(metrics.totalFailures).toBe(2);
+        expect(metrics.totalRejections).toBe(1);
+        expect(metrics.state).toBe("open");
+    });
+    it("calls onStateChange callback", () => {
+        const stateChanges = [];
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 1,
+            onStateChange: (from, to) => stateChanges.push({ from, to }),
+        });
+        breaker.recordFailure();
+        expect(stateChanges).toHaveLength(1);
+        expect(stateChanges[0]).toEqual({ from: "closed", to: "open" });
+    });
+    it("can be manually reset", () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 1,
+        });
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("open");
+        breaker.reset();
+        expect(breaker.getState()).toBe("closed");
+        expect(breaker.allowRequest()).toBe(true);
+    });
+});
+describe("calculateBackoff", () => {
+    it("calculates exponential backoff", () => {
+        const config = { ...defaultBackoffConfig, jitterFactor: 0 };
+        expect(calculateBackoff(0, config)).toBe(100);
+        expect(calculateBackoff(1, config)).toBe(200);
+        expect(calculateBackoff(2, config)).toBe(400);
+        expect(calculateBackoff(3, config)).toBe(800);
+    });
+    it("respects max backoff", () => {
+        const config = { ...defaultBackoffConfig, jitterFactor: 0, maxMs: 500 };
+        expect(calculateBackoff(0, config)).toBe(100);
+        expect(calculateBackoff(1, config)).toBe(200);
+        expect(calculateBackoff(2, config)).toBe(400);
+        expect(calculateBackoff(3, config)).toBe(500); // Capped at max
+        expect(calculateBackoff(10, config)).toBe(500);
+    });
+    it("adds jitter within bounds", () => {
+        const config = { ...defaultBackoffConfig, jitterFactor: 0.5 };
+        const results = new Set();
+        for (let i = 0; i < 20; i++) {
+            results.add(calculateBackoff(0, config));
+        }
+        // With jitter, we should get varied results
+        expect(results.size).toBeGreaterThan(1);
+        // All results should be within expected range (100 +/- 50)
+        for (const result of results) {
+            expect(result).toBeGreaterThanOrEqual(50);
+            expect(result).toBeLessThanOrEqual(150);
+        }
+    });
+});
+describe("withCircuitBreaker", () => {
+    it("executes function and records success", async () => {
+        const breaker = new CircuitBreaker(defaultCircuitBreakerConfig);
+        const fn = vi.fn().mockResolvedValue("result");
+        const result = await withCircuitBreaker(breaker, fn);
+        expect(result).toBe("result");
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(breaker.getMetrics().totalSuccesses).toBe(1);
+    });
+    it("throws CircuitOpenError when circuit is open", async () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 1,
+        });
+        breaker.recordFailure();
+        expect(breaker.getState()).toBe("open");
+        const fn = vi.fn().mockResolvedValue("result");
+        await expect(withCircuitBreaker(breaker, fn)).rejects.toThrow(CircuitOpenError);
+        expect(fn).not.toHaveBeenCalled();
+    });
+    it("retries with backoff on failure", async () => {
+        const breaker = new CircuitBreaker({
+            ...defaultCircuitBreakerConfig,
+            failureThreshold: 10,
+        });
+        let attempts = 0;
+        const fn = vi.fn().mockImplementation(() => {
+            attempts++;
+            if (attempts < 3) {
+                return Promise.reject(new Error("fail"));
+            }
+            return Promise.resolve("success");
+        });
+        const result = await withCircuitBreaker(breaker, fn, {
+            maxRetries: 3,
+            backoffConfig: { ...defaultBackoffConfig, initialMs: 10, jitterFactor: 0 },
+        });
+        expect(result).toBe("success");
+        expect(fn).toHaveBeenCalledTimes(3);
+    });
+    it("respects isFailure predicate", async () => {
+        const breaker = new CircuitBreaker(defaultCircuitBreakerConfig);
+        const businessError = new Error("business_error");
+        const fn = vi.fn().mockRejectedValue(businessError);
+        // Business errors should not trigger circuit breaker
+        await expect(withCircuitBreaker(breaker, fn, {
+            isFailure: (e) => !(e instanceof Error && e.message === "business_error"),
+        })).rejects.toThrow("business_error");
+        // No failures recorded
+        expect(breaker.getMetrics().totalFailures).toBe(0);
+    });
+});

package/dist/tests/control-plane-sync.test.d.ts

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

package/dist/tests/control-plane-sync.test.js

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ControlPlaneSyncClient, ControlPlaneSyncStatusTracker, syncControlPlaneState, } from "../src/control-plane-sync.js";
+describe("ControlPlaneSyncClient", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("pulls policy and revocation snapshots", async () => {
+        const fetchMock = vi.fn(async (input) => {
+            if (input.includes("/v1/policy/sync")) {
+                return {
+                    ok: true,
+                    status: 200,
+                    json: async () => ({
+                        version: "p-1",
+                        cursor: "pc-1",
+                        rules: [{ name: "allow-safe-read" }],
+                    }),
+                };
+            }
+            if (input.includes("/v1/revocations/sync")) {
+                return {
+                    ok: true,
+                    status: 200,
+                    json: async () => ({
+                        version: "r-1",
+                        cursor: "rc-1",
+                        revoked: [{ type: "principal", id: "agent:deny" }],
+                    }),
+                };
+            }
+            throw new Error(`Unexpected URL: ${input}`);
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new ControlPlaneSyncClient({
+            baseUrl: "http://127.0.0.1:9000",
+            tenantId: "tenant-a",
+        });
+        const result = await syncControlPlaneState(client, {
+            policyCursor: "p0",
+            revocationCursor: "r0",
+        });
+        expect(result.policy.version).toBe("p-1");
+        expect(result.revocations.version).toBe("r-1");
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+    it("throws on non-OK sync responses", async () => {
+        vi.stubGlobal("fetch", async () => ({
+            ok: false,
+            status: 503,
+            json: async () => ({ error: "unavailable" }),
+        }));
+        const client = new ControlPlaneSyncClient({
+            baseUrl: "http://127.0.0.1:9000",
+            tenantId: "tenant-a",
+        });
+        await expect(client.pullPolicySnapshot("c1")).rejects.toThrow("policy sync failed");
+    });
+    it("flags policy version mismatch against pinned version", () => {
+        const statuses = [];
+        const tracker = new ControlPlaneSyncStatusTracker({
+            pinnedPolicyVersion: "p-expected",
+            staleAfterMs: 300000,
+            onStatus: (status) => {
+                statuses.push({
+                    policyVersionMismatch: status.policyVersionMismatch,
+                    stale: status.stale,
+                });
+            },
+        });
+        const status = tracker.recordSync({
+            policy: { version: "p-actual", cursor: "pc-1", rules: [] },
+            revocations: { version: "r-1", cursor: "rc-1", revoked: [] },
+        }, 1000);
+        expect(status.policyVersionMismatch).toBe(true);
+        expect(status.stale).toBe(false);
+        expect(statuses).toEqual([{ policyVersionMismatch: true, stale: false }]);
+    });
+    it("reports stale sync state when sync age exceeds threshold", () => {
+        const tracker = new ControlPlaneSyncStatusTracker({
+            staleAfterMs: 5000,
+        });
+        tracker.recordSync({
+            policy: { version: "p-1", cursor: "pc-1", rules: [] },
+            revocations: { version: "r-1", cursor: "rc-1", revoked: [] },
+        }, 1000);
+        const status = tracker.snapshot(7001);
+        expect(status.stale).toBe(true);
+        expect(status.syncAgeMs).toBe(6001);
+    });
+});

package/dist/tests/hack-vs-fix-demo.test.d.ts

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

package/dist/tests/hack-vs-fix-demo.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { ToolAdapter } from "../src/adapter.js";
+import { ActionDeniedError, GuardedProvider } from "../src/provider.js";
+describe("Hack vs Fix demo scenario", () => {
+    it("shows unguarded exfil path and guarded deny path", async () => {
+        const injectedArgs = { path: "/Users/demo/.ssh/id_rsa" };
+        const injectedContext = { source: "untrusted_dm" };
+        const unguardedRead = async (args) => {
+            return `SECRET:${String(args.path)}`;
+        };
+        const hacked = await unguardedRead(injectedArgs);
+        expect(hacked).toContain("SECRET:/Users/demo/.ssh/id_rsa");
+        const guardedProvider = new GuardedProvider({
+            principal: "agent:openclaw-local",
+            authorityClient: {
+                authorize: async (request) => {
+                    const resource = String(request.resource ?? "");
+                    const labels = Array.isArray(request.labels) ? request.labels : [];
+                    const isUntrusted = labels.includes("source:untrusted_dm");
+                    const isSensitiveRead = request.action === "fs.read" &&
+                        (resource.includes("/.ssh/") || resource.startsWith("/etc/"));
+                    if (isUntrusted && isSensitiveRead) {
+                        return { allow: false, reason: "deny_sensitive_read_from_untrusted_context" };
+                    }
+                    return { allow: true, reason: "allowed", mandateId: "mnd_ok" };
+                },
+            },
+        });
+        const adapter = new ToolAdapter(guardedProvider);
+        await expect(adapter.readFile({
+            args: injectedArgs,
+            context: injectedContext,
+            execute: unguardedRead,
+        })).rejects.toBeInstanceOf(ActionDeniedError);
+    });
+});

package/dist/tests/jwks-rotation.test.d.ts

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

package/dist/tests/jwks-rotation.test.js

@@ -0,0 +1,232 @@
+import { describe, expect, it, vi } from "vitest";
+import { GuardedProvider } from "../src/provider.js";
+/**
+ * Integration tests for JWKS/key-rotation-driven policy contexts.
+ *
+ * These tests verify that the provider correctly handles scenarios where
+ * policy decisions depend on JWT validation contexts that may change
+ * during key rotation events.
+ *
+ * Note: The provider passes context fields to the sidecar, which handles
+ * actual JWKS validation. These tests verify context propagation and
+ * decision handling, not the JWKS validation itself.
+ */
+describe("JWKS and key rotation contexts", () => {
+    it("passes authorization request to sidecar for validation", async () => {
+        const capturedRequests = [];
+        const mockClient = {
+            authorize: vi.fn().mockImplementation((req) => {
+                capturedRequests.push(req);
+                return Promise.resolve({ allow: true });
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:jwks-test",
+            authorityClient: mockClient,
+        });
+        await provider.authorize({
+            action: "shell.execute",
+            resource: "npm install",
+            args: { cmd: "npm install" },
+            context: {
+                kid: "key-2024-02-20",
+                iss: "https://auth.example.com",
+                tenant_id: "tenant-a",
+                source: "trusted_ui",
+            },
+        });
+        expect(capturedRequests).toHaveLength(1);
+        expect(capturedRequests[0].principal).toBe("agent:jwks-test");
+        expect(capturedRequests[0].action).toBe("shell.execute");
+        expect(capturedRequests[0].labels).toContain("source:trusted_ui");
+    });
+    it("handles allow decisions from sidecar during key rotation", async () => {
+        // Sidecar accepts requests during rotation window
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({
+                allow: true,
+                reason: "valid_key",
+                mandateId: "mandate-rotation-1",
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:rotation-test",
+            authorityClient: mockClient,
+        });
+        // Both old and new key contexts should be accepted by sidecar
+        const result1 = await provider.authorize({
+            action: "fs.read",
+            resource: "/config.json",
+            args: { path: "/config.json" },
+            context: { kid: "key-v1", source: "trusted_ui" },
+        });
+        const result2 = await provider.authorize({
+            action: "fs.read",
+            resource: "/settings.json",
+            args: { path: "/settings.json" },
+            context: { kid: "key-v2", source: "trusted_ui" },
+        });
+        expect(result1).toBe("mandate-rotation-1");
+        expect(result2).toBe("mandate-rotation-1");
+        expect(mockClient.authorize).toHaveBeenCalledTimes(2);
+    });
+    it("handles deny decisions from sidecar for revoked keys", async () => {
+        let callCount = 0;
+        // Sidecar rejects old key, accepts new key
+        const mockClient = {
+            authorize: vi.fn().mockImplementation(async () => {
+                callCount++;
+                if (callCount === 1) {
+                    // First call with old key - rejected
+                    return { allow: false, reason: "key_revoked" };
+                }
+                // Second call with new key - accepted
+                return { allow: true, reason: "valid_key" };
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:post-rotation-test",
+            authorityClient: mockClient,
+        });
+        // Request with revoked old key
+        await expect(provider.authorize({
+            action: "shell.execute",
+            resource: "echo hello",
+            args: { cmd: "echo hello" },
+            context: { kid: "key-v1", source: "trusted_ui" },
+        })).rejects.toThrow("key_revoked");
+        // Request with valid new key
+        const result = await provider.authorize({
+            action: "shell.execute",
+            resource: "echo hello",
+            args: { cmd: "echo hello" },
+            context: { kid: "key-v2", source: "trusted_ui" },
+        });
+        expect(result).toBeNull(); // No mandate ID in this mock response
+    });
+    it("propagates issuer context for IdP validation", async () => {
+        const capturedRequests = [];
+        const mockClient = {
+            authorize: vi.fn().mockImplementation((req) => {
+                capturedRequests.push(req);
+                return Promise.resolve({ allow: true });
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:idp-test",
+            authorityClient: mockClient,
+        });
+        await provider.authorize({
+            action: "net.http",
+            resource: "https://api.internal.com/data",
+            args: { url: "https://api.internal.com/data" },
+            context: {
+                iss: "https://login.microsoftonline.com/tenant-id/v2.0",
+                aud: "api://predicate-authority",
+                sub: "user@example.com",
+                tenant_id: "tenant-azure",
+                source: "azure_entra",
+            },
+        });
+        expect(capturedRequests).toHaveLength(1);
+        expect(capturedRequests[0].labels).toContain("source:azure_entra");
+    });
+    it("handles expired token rejection from sidecar", async () => {
+        const mockClient = {
+            authorize: vi.fn().mockResolvedValue({
+                allow: false,
+                reason: "token_expired",
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:expired-test",
+            authorityClient: mockClient,
+        });
+        await expect(provider.authorize({
+            action: "fs.write",
+            resource: "/data.json",
+            args: { path: "/data.json", content: "{}" },
+            context: {
+                exp: Math.floor(Date.now() / 1000) - 3600,
+                iat: Math.floor(Date.now() / 1000) - 7200,
+                source: "trusted_ui",
+            },
+        })).rejects.toThrow("token_expired");
+    });
+    it("handles multiple concurrent requests with sidecar", async () => {
+        let concurrentCalls = 0;
+        let maxConcurrent = 0;
+        const mockClient = {
+            authorize: vi.fn().mockImplementation(async () => {
+                concurrentCalls++;
+                maxConcurrent = Math.max(maxConcurrent, concurrentCalls);
+                // Small delay to allow concurrency
+                await new Promise((r) => setTimeout(r, 5));
+                concurrentCalls--;
+                return { allow: true };
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:multi-key-test",
+            authorityClient: mockClient,
+        });
+        await Promise.all([
+            provider.authorize({
+                action: "fs.read",
+                resource: "/a.txt",
+                args: { path: "/a.txt" },
+                context: { session_id: "session-a", source: "trusted_ui" },
+            }),
+            provider.authorize({
+                action: "fs.read",
+                resource: "/b.txt",
+                args: { path: "/b.txt" },
+                context: { session_id: "session-b", source: "trusted_ui" },
+            }),
+            provider.authorize({
+                action: "fs.read",
+                resource: "/c.txt",
+                args: { path: "/c.txt" },
+                context: { session_id: "session-a", source: "trusted_ui" },
+            }),
+        ]);
+        expect(mockClient.authorize).toHaveBeenCalledTimes(3);
+        // Should have had some concurrent calls
+        expect(maxConcurrent).toBeGreaterThan(1);
+    });
+    it("includes source label for policy evaluation by key trust level", async () => {
+        const capturedRequests = [];
+        const mockClient = {
+            authorize: vi.fn().mockImplementation((req) => {
+                capturedRequests.push(req);
+                const labels = req.labels ?? [];
+                // Sidecar policy: only allow trusted sources
+                if (labels.includes("source:untrusted_dm")) {
+                    return Promise.resolve({ allow: false, reason: "untrusted_source" });
+                }
+                return Promise.resolve({ allow: true });
+            }),
+        };
+        const provider = new GuardedProvider({
+            principal: "agent:trust-test",
+            authorityClient: mockClient,
+        });
+        // Trusted source - allowed
+        await provider.authorize({
+            action: "shell.execute",
+            resource: "npm install",
+            args: { cmd: "npm install" },
+            context: { source: "trusted_ui" },
+        });
+        // Untrusted source - denied
+        await expect(provider.authorize({
+            action: "shell.execute",
+            resource: "curl evil.com",
+            args: { cmd: "curl evil.com" },
+            context: { source: "untrusted_dm" },
+        })).rejects.toThrow("untrusted_source");
+        expect(capturedRequests).toHaveLength(2);
+        expect(capturedRequests[0].labels).toContain("source:trusted_ui");
+        expect(capturedRequests[1].labels).toContain("source:untrusted_dm");
+    });
+});

package/dist/tests/load-latency.test.d.ts

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