predicate-claw 0.1.0

package/tests/runtime-integration.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { HookEnvelope } from "../src/openclaw-hooks.js";
+import { OpenClawRuntimeIntegrator } from "../src/runtime-integration.js";
+
+class Registry {
+  private handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "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: string) {
+    return this.handlers[toolName];
+  }
+
+  set(toolName: string, handler: (args: Record<string, unknown>) => Promise<unknown>) {
+    this.handlers[toolName] = handler;
+  }
+
+  invoke(toolName: string, args: Record<string, unknown>) {
+    return this.handlers[toolName](args);
+  }
+}
+
+describe("OpenClawRuntimeIntegrator", () => {
+  it("wraps sensitive handlers and routes through hooks", async () => {
+    const seen: string[] = [];
+    const registry = new Registry();
+    const hooks = {
+      onCmdRun: async (envelope: HookEnvelope, execute: (args: Record<string, unknown>) => Promise<unknown>) => {
+        seen.push(`cmd:${envelope.toolName}`);
+        return execute(envelope.args);
+      },
+      onFsRead: async (envelope: HookEnvelope, execute: (args: Record<string, unknown>) => Promise<unknown>) => {
+        seen.push(`fs:${envelope.toolName}`);
+        return execute(envelope.args);
+      },
+      onHttpRequest: async (
+        envelope: HookEnvelope,
+        execute: (args: Record<string, unknown>) => Promise<unknown>,
+      ) => {
+        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/tests/test_adapter.py

@@ -0,0 +1,46 @@
+import asyncio
+
+from openclaw_predicate_provider.adapter import ToolAdapter
+from openclaw_predicate_provider.errors import ActionDeniedError
+
+
+class _AllowGuard:
+    async def guard_or_raise(self, **_: object) -> str:
+        return "mnd_test"
+
+
+class _DenyGuard:
+    async def guard_or_raise(self, **_: object) -> str:
+        raise ActionDeniedError("denied_by_policy")
+
+
+async def _echo(args: dict[str, object]) -> dict[str, object]:
+    return args
+
+
+def test_run_shell_uses_expected_action_and_resource() -> None:
+    adapter = ToolAdapter(_AllowGuard())  # type: ignore[arg-type]
+    result = asyncio.run(
+        adapter.run_shell(
+            args={"command": "echo hi"},
+            context={"source": "trusted_ui"},
+            execute=_echo,
+        )
+    )
+    assert result["command"] == "echo hi"
+
+
+def test_denied_guard_bubbles_exception() -> None:
+    adapter = ToolAdapter(_DenyGuard())  # type: ignore[arg-type]
+    try:
+        asyncio.run(
+            adapter.read_file(
+                args={"path": "/etc/passwd"},
+                context={"source": "untrusted_dm"},
+                execute=_echo,
+            )
+        )
+    except ActionDeniedError as exc:
+        assert "denied" in str(exc)
+        return
+    raise AssertionError("Expected ActionDeniedError")

package/tests/test_cli.py

@@ -0,0 +1,26 @@
+from openclaw_predicate_provider.cli import build_parser
+
+
+def test_validate_config_command_parses() -> None:
+    parser = build_parser()
+    args = parser.parse_args(["validate-config"])
+    assert args.command == "validate-config"
+
+
+def test_smoke_authorize_command_parses_defaults() -> None:
+    parser = build_parser()
+    args = parser.parse_args(["smoke-authorize"])
+    assert args.command == "smoke-authorize"
+    assert args.action == "shell.execute"
+
+
+def test_validate_config_accepts_backend_switch() -> None:
+    parser = build_parser()
+    args = parser.parse_args(
+        [
+            "--authorization-backend",
+            "agentidentity_local",
+            "validate-config",
+        ]
+    )
+    assert args.authorization_backend == "agentidentity_local"

package/tests/test_openclaw_hooks.py

@@ -0,0 +1,53 @@
+import asyncio
+
+from openclaw_predicate_provider.openclaw_hooks import HookEnvelope, OpenClawHooks
+
+
+class _AdapterStub:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, dict, dict]] = []
+
+    async def run_shell(self, *, args, context, execute):  # noqa: ANN001
+        self.calls.append(("shell", args, context))
+        return await execute(args)
+
+    async def read_file(self, *, args, context, execute):  # noqa: ANN001
+        self.calls.append(("fs.read", args, context))
+        return await execute(args)
+
+    async def http_request(self, *, args, context, execute):  # noqa: ANN001
+        self.calls.append(("net.http", args, context))
+        return await execute(args)
+
+
+async def _echo(args):
+    return args
+
+
+def test_hook_envelope_context_shape() -> None:
+    env = HookEnvelope(
+        tool_name="cmd.run",
+        args={"command": "echo hi"},
+        session_id="s1",
+        source="trusted_ui",
+        tenant_id="t1",
+        user_id="u1",
+        trace_id="tr1",
+    )
+    ctx = env.context()
+    assert ctx["source"] == "trusted_ui"
+    assert ctx["tenant_id"] == "t1"
+
+
+def test_on_cmd_run_routes_to_shell_guard() -> None:
+    adapter = _AdapterStub()
+    hooks = OpenClawHooks(adapter)  # type: ignore[arg-type]
+    env = HookEnvelope(
+        tool_name="cmd.run",
+        args={"command": "echo hi"},
+        session_id="s1",
+        source="trusted_ui",
+    )
+    result = asyncio.run(hooks.on_cmd_run(env, _echo))
+    assert result["command"] == "echo hi"
+    assert adapter.calls[0][0] == "shell"

package/tests/test_provider.py

@@ -0,0 +1,59 @@
+import asyncio
+
+from openclaw_predicate_provider.config import ProviderConfig
+from openclaw_predicate_provider.errors import SidecarUnavailableError
+from openclaw_predicate_provider.provider import GuardedProvider
+
+
+def test_intent_hash_is_deterministic() -> None:
+    payload_a = {"cmd": "ls", "flags": ["-la"]}
+    payload_b = {"flags": ["-la"], "cmd": "ls"}
+
+    first = GuardedProvider._intent_hash(payload_a)
+    second = GuardedProvider._intent_hash(payload_b)
+
+    assert first == second
+
+
+class _UnavailableSidecar:
+    async def authorize(self, request):  # noqa: ANN001
+        raise SidecarUnavailableError("down")
+
+
+def test_guard_or_raise_fails_closed_on_sidecar_unavailable() -> None:
+    provider = GuardedProvider(
+        principal="p1",
+        config=ProviderConfig(fail_closed=True),
+    )
+    provider._sidecar = _UnavailableSidecar()  # type: ignore[assignment]
+
+    try:
+        asyncio.run(
+            provider.guard_or_raise(
+                action="shell.execute",
+                resource="echo hi",
+                args={"command": "echo hi"},
+                context={"source": "trusted_ui"},
+            )
+        )
+    except SidecarUnavailableError:
+        return
+    raise AssertionError("Expected SidecarUnavailableError in fail-closed mode")
+
+
+def test_guard_or_raise_allows_none_on_fail_open() -> None:
+    provider = GuardedProvider(
+        principal="p1",
+        config=ProviderConfig(fail_closed=False),
+    )
+    provider._sidecar = _UnavailableSidecar()  # type: ignore[assignment]
+
+    result = asyncio.run(
+        provider.guard_or_raise(
+            action="shell.execute",
+            resource="echo hi",
+            args={"command": "echo hi"},
+            context={"source": "trusted_ui"},
+        )
+    )
+    assert result is None

package/tests/test_runtime_integration.py

@@ -0,0 +1,77 @@
+import asyncio
+
+from openclaw_predicate_provider.integrations import OpenClawRuntimeIntegrator
+from openclaw_predicate_provider.openclaw_hooks import HookEnvelope
+
+
+class _Registry:
+    def __init__(self) -> None:
+        self._handlers = {
+            "cmd.run": self._cmd,
+            "fs.readFile": self._fs,
+            "http.request": self._http,
+        }
+
+    async def _cmd(self, args):
+        return {"tool": "cmd.run", "args": args}
+
+    async def _fs(self, args):
+        return {"tool": "fs.readFile", "args": args}
+
+    async def _http(self, args):
+        return {"tool": "http.request", "args": args}
+
+    def get(self, tool_name):
+        return self._handlers[tool_name]
+
+    def set(self, tool_name, handler):
+        self._handlers[tool_name] = handler
+
+    async def invoke(self, tool_name, args):
+        return await self._handlers[tool_name](args)
+
+
+class _HooksStub:
+    def __init__(self) -> None:
+        self.seen = []
+
+    async def on_cmd_run(self, envelope, execute):
+        self.seen.append(("cmd", envelope.tool_name, envelope.source))
+        return await execute(envelope.args)
+
+    async def on_fs_read(self, envelope, execute):
+        self.seen.append(("fs", envelope.tool_name, envelope.source))
+        return await execute(envelope.args)
+
+    async def on_http_request(self, envelope, execute):
+        self.seen.append(("http", envelope.tool_name, envelope.source))
+        return await execute(envelope.args)
+
+
+def _context_builder(tool_name: str, args: dict) -> HookEnvelope:
+    return HookEnvelope(
+        tool_name=tool_name,
+        args=args,
+        session_id="s1",
+        source="trusted_ui",
+        tenant_id="t1",
+    )
+
+
+def test_runtime_integrator_wraps_and_routes_handlers() -> None:
+    registry = _Registry()
+    hooks = _HooksStub()
+    integrator = OpenClawRuntimeIntegrator(
+        hooks=hooks,  # type: ignore[arg-type]
+        context_builder=_context_builder,
+    )
+    integrator.register(registry)
+
+    cmd = asyncio.run(registry.invoke("cmd.run", {"command": "echo hi"}))
+    fs = asyncio.run(registry.invoke("fs.readFile", {"path": "/tmp/demo"}))
+    http = asyncio.run(registry.invoke("http.request", {"url": "https://e.com"}))
+
+    assert cmd["tool"] == "cmd.run"
+    assert fs["tool"] == "fs.readFile"
+    assert http["tool"] == "http.request"
+    assert [x[0] for x in hooks.seen] == ["cmd", "fs", "http"]

package/tests/test_sidecar_client.py

@@ -0,0 +1,198 @@
+import asyncio
+from unittest.mock import patch
+
+import httpx
+
+from openclaw_predicate_provider.config import ProviderConfig
+from openclaw_predicate_provider.errors import SidecarUnavailableError
+from openclaw_predicate_provider.models import AuthorizationRequest
+from openclaw_predicate_provider.sidecar import SidecarClient
+
+
+class _DeniedResponseClient:
+    def __init__(self, timeout: float):  # noqa: ARG002
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):  # noqa: ANN001
+        return False
+
+    async def post(self, url: str, json: dict):  # noqa: ARG002
+        return httpx.Response(
+            status_code=403,
+            json={"reason": "explicit_deny", "mandate_id": "mnd123"},
+            request=httpx.Request("POST", url),
+        )
+
+
+class _AllowedResponseClient:
+    def __init__(self, timeout: float):  # noqa: ARG002
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):  # noqa: ANN001
+        return False
+
+    async def post(self, url: str, json: dict):  # noqa: ARG002
+        return httpx.Response(
+            status_code=200,
+            json={"reason": "allowed", "mandate_id": "mnd_ok"},
+            request=httpx.Request("POST", url),
+        )
+
+
+class _UnexpectedStatusClient:
+    def __init__(self, timeout: float):  # noqa: ARG002
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):  # noqa: ANN001
+        return False
+
+    async def post(self, url: str, json: dict):  # noqa: ARG002
+        return httpx.Response(
+            status_code=502,
+            json={"error": "bad_gateway"},
+            request=httpx.Request("POST", url),
+        )
+
+
+class _DeniedEmptyPayloadClient:
+    def __init__(self, timeout: float):  # noqa: ARG002
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):  # noqa: ANN001
+        return False
+
+    async def post(self, url: str, json: dict):  # noqa: ARG002
+        return httpx.Response(
+            status_code=403,
+            json={},
+            request=httpx.Request("POST", url),
+        )
+
+
+def _request() -> AuthorizationRequest:
+    return AuthorizationRequest(
+        principal="openclaw-agent-local",
+        action="shell.execute",
+        resource="echo hi",
+        intent_hash="abc123",
+        context={"source": "untrusted_dm"},
+    )
+
+
+def test_sidecar_403_propagates_reason_and_mandate_id() -> None:
+    request = _request()
+    client = SidecarClient(ProviderConfig())
+
+    with patch(
+        "openclaw_predicate_provider.sidecar.httpx.AsyncClient",
+        _DeniedResponseClient,
+    ):
+        decision = asyncio.run(client.authorize(request))
+
+    assert decision.allow is False
+    assert decision.reason == "explicit_deny"
+    assert decision.mandate_id == "mnd123"
+
+
+def test_sidecar_200_propagates_allow_and_mandate_id() -> None:
+    request = _request()
+    client = SidecarClient(ProviderConfig())
+
+    with patch(
+        "openclaw_predicate_provider.sidecar.httpx.AsyncClient",
+        _AllowedResponseClient,
+    ):
+        decision = asyncio.run(client.authorize(request))
+
+    assert decision.allow is True
+    assert decision.reason == "allowed"
+    assert decision.mandate_id == "mnd_ok"
+
+
+def test_unexpected_status_fails_closed_by_default() -> None:
+    request = _request()
+    client = SidecarClient(ProviderConfig(fail_closed=True))
+
+    with patch(
+        "openclaw_predicate_provider.sidecar.httpx.AsyncClient",
+        _UnexpectedStatusClient,
+    ):
+        try:
+            asyncio.run(client.authorize(request))
+        except SidecarUnavailableError:
+            return
+    raise AssertionError("Expected SidecarUnavailableError for fail-closed mode")
+
+
+def test_unexpected_status_can_fail_open_when_enabled() -> None:
+    request = _request()
+    client = SidecarClient(ProviderConfig(fail_closed=False))
+
+    with patch(
+        "openclaw_predicate_provider.sidecar.httpx.AsyncClient",
+        _UnexpectedStatusClient,
+    ):
+        decision = asyncio.run(client.authorize(request))
+
+    assert decision.allow is True
+    assert decision.reason == "fail_open_override"
+
+
+def test_403_empty_payload_uses_default_deny_reason() -> None:
+    request = _request()
+    client = SidecarClient(ProviderConfig())
+
+    with patch(
+        "openclaw_predicate_provider.sidecar.httpx.AsyncClient",
+        _DeniedEmptyPayloadClient,
+    ):
+        decision = asyncio.run(client.authorize(request))
+
+    assert decision.allow is False
+    assert decision.reason == "denied_by_policy"
+    assert decision.mandate_id is None
+
+
+class _LocalBackendStub:
+    def __init__(self, config: ProviderConfig):  # noqa: ARG002
+        self.called = False
+
+    def authorize(self, request: AuthorizationRequest):
+        self.called = True
+        return type(
+            "D",
+            (),
+            {"allow": False, "reason": "explicit_deny", "mandate_id": "mnd_local"},
+        )()
+
+
+def test_agentidentity_local_backend_is_selected() -> None:
+    request = AuthorizationRequest(
+        principal="openclaw-agent-local",
+        action="shell.execute",
+        resource="echo hi",
+        intent_hash="abc123",
+        context={"source": "untrusted_dm"},
+    )
+    with patch(
+        "openclaw_predicate_provider.sidecar.AgentIdentityLocalClient",
+        _LocalBackendStub,
+    ):
+        client = SidecarClient(ProviderConfig(authorization_backend="agentidentity_local"))
+        decision = asyncio.run(client.authorize(request))
+
+    assert decision.allow is False
+    assert decision.reason == "explicit_deny"
+    assert decision.mandate_id == "mnd_local"

package/tests/web-evidence.test.ts

@@ -0,0 +1,113 @@
+import crypto from "node:crypto";
+import { describe, expect, it } from "vitest";
+import {
+  buildWebEvidenceFromProvider,
+  buildWebEvidenceFromRuntimeSnapshot,
+  OpenClawWebEvidenceProvider,
+  type WebRuntimeContext,
+} from "../src/web-evidence.js";
+
+function sha256(input: string): string {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+describe("web evidence providers", () => {
+  it("builds web state evidence from OpenClaw runtime context", async () => {
+    const mockContext: WebRuntimeContext = {
+      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 (): Promise<WebRuntimeContext> => {
+      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();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    exclude: ["dist/**", "node_modules/**"],
+  },
+});