predicate-claw 0.1.0

package/tests/audit-event-e2e.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  type DecisionAuditExporter,
+  type DecisionTelemetryEvent,
+  GuardedProvider,
+  ActionDeniedError,
+} from "../src/provider.js";
+
+/**
+ * End-to-end audit event visibility tests.
+ *
+ * These tests verify that decision events flow correctly from the provider
+ * through to audit exporters in a format compatible with control-plane
+ * audit pipelines.
+ */
+describe("audit event visibility (e2e)", () => {
+  it("exports allow decisions with full context to audit sink", async () => {
+    const exportedEvents: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockResolvedValue({
+        allow: true,
+        reason: "policy_matched",
+        mandateId: "mandate-12345",
+      }),
+    };
+
+    const auditExporter: DecisionAuditExporter = {
+      exportDecision: async (event) => {
+        exportedEvents.push(event);
+      },
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:e2e-test-agent",
+      authorityClient: mockClient,
+      auditExporter,
+    });
+
+    await provider.authorize({
+      action: "shell.execute",
+      resource: "npm install lodash",
+      args: { cmd: "npm install lodash" },
+      context: {
+        tenant_id: "tenant-prod",
+        session_id: "sess-e2e-001",
+        user_id: "user-developer",
+        trace_id: "trace-e2e-xyz",
+        source: "trusted_ui",
+      },
+    });
+
+    // Verify event was exported
+    expect(exportedEvents).toHaveLength(1);
+
+    const event = exportedEvents[0];
+
+    // Verify control-plane compatible fields
+    expect(event.principal).toBe("agent:e2e-test-agent");
+    expect(event.action).toBe("shell.execute");
+    expect(event.resource).toBe("npm install lodash");
+    expect(event.outcome).toBe("allow");
+    expect(event.reason).toBe("policy_matched");
+    expect(event.mandateId).toBe("mandate-12345");
+
+    // Verify tenant/session context
+    expect(event.tenantId).toBe("tenant-prod");
+    expect(event.sessionId).toBe("sess-e2e-001");
+    expect(event.userId).toBe("user-developer");
+    expect(event.traceId).toBe("trace-e2e-xyz");
+    expect(event.source).toBe("trusted_ui");
+
+    // Verify timestamp is ISO format
+    expect(event.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it("exports deny decisions with redacted sensitive resources", async () => {
+    const exportedEvents: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockResolvedValue({
+        allow: false,
+        reason: "sensitive_path_blocked",
+      }),
+    };
+
+    const auditExporter: DecisionAuditExporter = {
+      exportDecision: async (event) => {
+        exportedEvents.push(event);
+      },
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:sensitive-test",
+      authorityClient: mockClient,
+      auditExporter,
+    });
+
+    await expect(
+      provider.authorize({
+        action: "fs.read",
+        resource: "/home/user/.ssh/id_rsa",
+        args: { path: "/home/user/.ssh/id_rsa" },
+        context: { tenant_id: "tenant-sec" },
+      }),
+    ).rejects.toThrow(ActionDeniedError);
+
+    expect(exportedEvents).toHaveLength(1);
+
+    const event = exportedEvents[0];
+    expect(event.outcome).toBe("deny");
+    expect(event.reason).toBe("sensitive_path_blocked");
+    // Resource should be redacted for sensitive paths
+    expect(event.resource).toBe("[REDACTED]");
+  });
+
+  it("exports error events when sidecar is unavailable", async () => {
+    const exportedEvents: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi.fn().mockRejectedValue(new Error("Connection refused")),
+    };
+
+    const auditExporter: DecisionAuditExporter = {
+      exportDecision: async (event) => {
+        exportedEvents.push(event);
+      },
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:error-test",
+      authorityClient: mockClient,
+      auditExporter,
+    });
+
+    await expect(
+      provider.authorize({
+        action: "net.http",
+        resource: "https://api.example.com",
+        args: { url: "https://api.example.com" },
+        context: { tenant_id: "tenant-error" },
+      }),
+    ).rejects.toThrow();
+
+    expect(exportedEvents).toHaveLength(1);
+
+    const event = exportedEvents[0];
+    expect(event.outcome).toBe("error");
+    expect(event.tenantId).toBe("tenant-error");
+  });
+
+  it("handles audit exporter failures gracefully (best-effort)", async () => {
+    let callCount = 0;
+
+    const mockClient = {
+      authorize: vi.fn().mockResolvedValue({ allow: true }),
+    };
+
+    const failingExporter: DecisionAuditExporter = {
+      exportDecision: async () => {
+        callCount++;
+        throw new Error("Audit sink unavailable");
+      },
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:failing-audit",
+      authorityClient: mockClient,
+      auditExporter: failingExporter,
+    });
+
+    // Should not throw even though exporter fails
+    const result = await provider.authorize({
+      action: "fs.read",
+      resource: "/workspace/safe-file.txt",
+      args: { path: "/workspace/safe-file.txt" },
+    });
+
+    // Authorization should succeed despite audit failure
+    expect(result).toBeNull(); // No mandate ID returned in this case
+    expect(callCount).toBe(1); // Exporter was called
+  });
+
+  it("chains multiple decision events with consistent trace context", async () => {
+    const exportedEvents: DecisionTelemetryEvent[] = [];
+
+    const mockClient = {
+      authorize: vi
+        .fn()
+        .mockResolvedValueOnce({ allow: true, mandateId: "m1" })
+        .mockResolvedValueOnce({ allow: true, mandateId: "m2" })
+        .mockResolvedValueOnce({ allow: false, reason: "rate_limited" }),
+    };
+
+    const auditExporter: DecisionAuditExporter = {
+      exportDecision: async (event) => {
+        exportedEvents.push(event);
+      },
+    };
+
+    const provider = new GuardedProvider({
+      principal: "agent:chained-ops",
+      authorityClient: mockClient,
+      auditExporter,
+    });
+
+    const sharedContext = {
+      tenant_id: "tenant-chain",
+      session_id: "sess-chain",
+      trace_id: "trace-chain-root",
+    };
+
+    // First operation - allowed
+    await provider.authorize({
+      action: "fs.read",
+      resource: "/workspace/config.json",
+      args: { path: "/workspace/config.json" },
+      context: sharedContext,
+    });
+
+    // Second operation - allowed
+    await provider.authorize({
+      action: "net.http",
+      resource: "https://api.internal/fetch",
+      args: { url: "https://api.internal/fetch" },
+      context: sharedContext,
+    });
+
+    // Third operation - denied
+    try {
+      await provider.authorize({
+        action: "shell.execute",
+        resource: "curl external.com",
+        args: { cmd: "curl external.com" },
+        context: sharedContext,
+      });
+    } catch {
+      // Expected denial
+    }
+
+    expect(exportedEvents).toHaveLength(3);
+
+    // All events should share the same trace context
+    for (const event of exportedEvents) {
+      expect(event.tenantId).toBe("tenant-chain");
+      expect(event.sessionId).toBe("sess-chain");
+      expect(event.traceId).toBe("trace-chain-root");
+    }
+
+    // Verify outcomes
+    expect(exportedEvents[0].outcome).toBe("allow");
+    expect(exportedEvents[0].mandateId).toBe("m1");
+    expect(exportedEvents[1].outcome).toBe("allow");
+    expect(exportedEvents[1].mandateId).toBe("m2");
+    expect(exportedEvents[2].outcome).toBe("deny");
+    expect(exportedEvents[2].reason).toBe("rate_limited");
+  });
+});

package/tests/authority-client.test.ts

@@ -0,0 +1,52 @@
+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/tests/circuit-breaker.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  calculateBackoff,
+  CircuitBreaker,
+  CircuitOpenError,
+  defaultBackoffConfig,
+  defaultCircuitBreakerConfig,
+  withCircuitBreaker,
+  type CircuitState,
+} 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: Array<{ from: CircuitState; to: CircuitState }> = [];
+
+    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<number>();
+
+    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/tests/conftest.py

@@ -0,0 +1,9 @@
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))

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

@@ -0,0 +1,114 @@
+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: string) => {
+      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: Array<{ policyVersionMismatch: boolean; stale: boolean }> = [];
+    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);
+  });
+});