predicate-claw 0.1.0

package/examples/README.md

@@ -0,0 +1,171 @@
+# OpenClaw Predicate Provider Examples
+
+This directory contains examples and test harnesses for the OpenClaw Predicate Provider.
+
+## Hack vs Fix Demo
+
+This demo shows the OpenClaw prompt-injection risk path and the
+`PredicateClaw` protection path.
+
+### Goal
+
+Demonstrate that:
+
+1. An unguarded tool call can read a sensitive file when prompted from an
+   untrusted source, and
+2. The Predicate-guarded path blocks the same action with deterministic policy.
+
+### Scenario in Plain Language
+
+- **Hack path:** Injected context (`source: untrusted_dm`) attempts
+  `fs.read` on `~/.ssh/id_rsa` and succeeds when unguarded.
+- **Fix path:** Same action goes through `GuardedProvider + ToolAdapter`,
+  maps to Predicate action/resource contract, and receives deny decision.
+
+### Fast Local Run
+
+From `PredicateClaw/`:
+
+```bash
+npm test -- tests/hack-vs-fix-demo.test.ts
+```
+
+Expected:
+
+- Test passes
+- Unguarded branch returns sensitive payload string
+- Guarded branch throws `ActionDeniedError` with deny reason
+  `deny_sensitive_read_from_untrusted_context`
+
+## Docker Adversarial Testing
+
+### Why Docker?
+
+Running adversarial tests (simulating prompt injection attacks like "read my
+SSH keys" or "curl malware") directly on your machine is risky. If the provider
+has a bug, the attack could execute. Docker isolates failures to the container.
+
+### Quick Start
+
+From the `PredicateClaw/` directory:
+
+**Option 1: Docker Compose (recommended)**
+
+```bash
+# Run the "Hack vs Fix" demo test
+docker compose -f examples/docker/docker-compose.test.yml run --rm provider-demo
+
+# Run full CI checks (typecheck + all tests)
+docker compose -f examples/docker/docker-compose.test.yml run --rm provider-ci
+```
+
+**Option 2: Build and run directly**
+
+```bash
+# Build the test image
+docker build -t openclaw-provider-test -f examples/docker/Dockerfile.test .
+
+# Run demo test
+docker run --rm -it openclaw-provider-test npm run test:demo
+
+# Run full CI
+docker run --rm -it openclaw-provider-test npm run test:ci
+```
+
+### Expected Output
+
+```
+ RUN  v4.x.x /app
+
+ ✓ tests/hack-vs-fix-demo.test.ts (1 test)
+   ✓ shows unguarded exfil path and guarded deny path
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+```
+
+The test verifies:
+
+- Unguarded call returns sensitive data
+- Guarded call throws `ActionDeniedError`
+- Deny reason is stable and auditable
+
+### Testing with a Live Sidecar
+
+To test against a real `predicate-authorityd` sidecar (not mocked):
+
+```bash
+# Start sidecar on host
+predicate-authorityd --port 9090
+
+# Run container with host network access
+docker run --rm -it --network=host openclaw-provider-test npm test
+```
+
+The `--network=host` lets the container reach `localhost:9090` where your
+sidecar runs.
+
+## Video Recording Checklist (for Launch Asset)
+
+1. Show baseline unguarded action succeeds for sensitive read.
+2. Show guarded provider enabled with identical prompt/context.
+3. Show deny result and user-facing blocked message.
+4. Show test command and green output as reproducible evidence.
+
+## Non-Web Evidence Provider Demo
+
+Demonstrates terminal and desktop accessibility evidence providers with canonical
+hashing for reproducible `state_hash` computation.
+
+### Run the Demo
+
+```bash
+npx tsx examples/non-web-evidence-demo.ts
+```
+
+### What It Shows
+
+1. **Terminal Evidence** - Captures command-line state with:
+   - Path normalization (`/workspace/./src/../src` → `/workspace/src`)
+   - Whitespace collapsing (`git   status` → `git status`)
+   - ANSI code stripping (removes color codes)
+   - Timestamp normalization (`[12:34:56]` → `[TIMESTAMP]`)
+   - Secret redaction (environment variables like `AWS_SECRET_KEY`)
+
+2. **Desktop Evidence** - Captures accessibility tree state with:
+   - App name normalization
+   - UI tree text normalization
+   - Whitespace handling
+
+3. **Hash Stability** - Proves that minor variations produce identical hashes
+   when canonicalization is enabled.
+
+### API Usage
+
+```typescript
+import {
+  OpenClawTerminalEvidenceProvider,
+  buildTerminalEvidenceFromProvider,
+} from "predicate-claw";
+
+const provider = new OpenClawTerminalEvidenceProvider(() => ({
+  sessionId: "my-session",
+  cwd: process.cwd(),
+  command: "npm test",
+  transcript: "...",
+}));
+
+const evidence = await buildTerminalEvidenceFromProvider(provider, {
+  useCanonicalHash: true, // default
+});
+
+console.log(evidence.state_hash); // sha256:...
+```
+
+## Other Examples
+
+- `openclaw_integration_example.py` - Python integration example
+- `runtime_registry_example.py` - Runtime registration example
+- `openclaw-plugin-smoke/` - OpenClaw plugin smoke test
+- `policy/` - Example policy files
+- `docker/` - Docker test harness files

package/examples/docker/Dockerfile.test

@@ -0,0 +1,16 @@
+FROM node:22-slim
+
+WORKDIR /app
+
+# Install Node dependencies first for better layer caching.
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Copy TypeScript sources, tests, and examples used by demo/test scripts.
+COPY tsconfig.json vitest.config.ts ./
+COPY src ./src
+COPY tests ./tests
+COPY examples ./examples
+
+# Default to the reproducible Hack-vs-Fix demo test.
+CMD ["npm", "run", "test:demo"]

package/examples/docker/README.md

@@ -0,0 +1,48 @@
+# Docker Adversarial Test Harness
+
+Use this TypeScript-first container setup for isolated provider demo/testing.
+
+## Option 1: Run with Docker Compose (recommended)
+
+From `openclaw-predicate-provider/`:
+
+```bash
+docker compose -f examples/docker/docker-compose.test.yml run --rm provider-demo
+```
+
+This runs the reproducible Hack-vs-Fix demo test (`npm run test:demo`) in an
+isolated container.
+
+Run full CI-equivalent checks in container:
+
+```bash
+docker compose -f examples/docker/docker-compose.test.yml run --rm provider-ci
+```
+
+This runs `npm run test:ci` (`typecheck` + full test suite).
+
+## Option 2: Build and run image directly
+
+Build:
+
+```bash
+docker build -t openclaw-provider-test -f examples/docker/Dockerfile.test .
+```
+
+Run demo test:
+
+```bash
+docker run --rm -it openclaw-provider-test npm run test:demo
+```
+
+Run full checks:
+
+```bash
+docker run --rm -it openclaw-provider-test npm run test:ci
+```
+
+## Expected behavior
+
+- Demo test reproduces "Hack vs Fix" flow and passes.
+- Denied actions surface stable reason codes.
+- Sensitive resource values are redacted in audit export telemetry.

package/examples/docker/docker-compose.test.yml

@@ -0,0 +1,16 @@
+services:
+  provider-demo:
+    build:
+      context: ../..
+      dockerfile: examples/docker/Dockerfile.test
+    environment:
+      NODE_ENV: test
+    command: ["npm", "run", "test:demo"]
+
+  provider-ci:
+    build:
+      context: ../..
+      dockerfile: examples/docker/Dockerfile.test
+    environment:
+      NODE_ENV: test
+    command: ["npm", "run", "test:ci"]

package/examples/non-web-evidence-demo.ts

@@ -0,0 +1,184 @@
+/**
+ * Non-Web Evidence Provider Demo
+ *
+ * This example demonstrates how to use the terminal and desktop accessibility
+ * evidence providers with canonical hashing for reproducible state_hash computation.
+ *
+ * The canonicalization ensures that minor variations (ANSI codes, timestamps,
+ * whitespace) don't break hash verification.
+ *
+ * Run with: npx tsx examples/non-web-evidence-demo.ts
+ */
+
+import {
+  OpenClawTerminalEvidenceProvider,
+  OpenClawDesktopAccessibilityEvidenceProvider,
+  buildTerminalEvidenceFromProvider,
+  buildDesktopEvidenceFromProvider,
+  type TerminalRuntimeContext,
+  type DesktopRuntimeContext,
+} from "../src/index.js";
+
+// ============================================================================
+// Terminal Evidence Demo
+// ============================================================================
+
+async function demoTerminalEvidence(): Promise<void> {
+  console.log("=".repeat(60));
+  console.log("Terminal Evidence Provider Demo");
+  console.log("=".repeat(60));
+
+  // Simulated terminal runtime context (in real usage, capture from actual terminal)
+  const terminalContext: TerminalRuntimeContext = {
+    sessionId: "demo-session-001",
+    terminalId: "term-1",
+    cwd: "/workspace/./src/../src", // Will be normalized to /workspace/src
+    command: "git   status  ", // Extra whitespace will be collapsed
+    // Transcript with ANSI codes and timestamps that will be normalized
+    transcript: `\x1b[32m[12:34:56]\x1b[0m Running git status...
+On branch main
+Your branch is up to date with 'origin/main'.
+
+\x1b[33mnothing to commit, working tree clean\x1b[0m`,
+    env: {
+      HOME: "/home/user",
+      PATH: "/usr/bin:/bin",
+      AWS_SECRET_KEY: "should-be-redacted", // Secrets are redacted
+      EDITOR: "vim",
+    },
+  };
+
+  // Create provider with capture function
+  const terminalProvider = new OpenClawTerminalEvidenceProvider(
+    () => terminalContext,
+  );
+
+  // Build evidence with canonical hashing (default)
+  const terminalEvidence = await buildTerminalEvidenceFromProvider(
+    terminalProvider,
+    { useCanonicalHash: true },
+  );
+
+  console.log("\nTerminal Evidence:");
+  console.log(JSON.stringify(terminalEvidence, null, 2));
+
+  // Demonstrate hash stability - same content with different formatting
+  const terminalContext2: TerminalRuntimeContext = {
+    ...terminalContext,
+    cwd: "/workspace/src", // Same path after normalization
+    command: "git status", // Same command after whitespace collapse
+    // Same content without ANSI codes and different timestamps
+    transcript: `[09:00:00] Running git status...
+On branch main
+Your branch is up to date with 'origin/main'.
+
+nothing to commit, working tree clean`,
+  };
+
+  const terminalProvider2 = new OpenClawTerminalEvidenceProvider(
+    () => terminalContext2,
+  );
+
+  const terminalEvidence2 = await buildTerminalEvidenceFromProvider(
+    terminalProvider2,
+    { useCanonicalHash: true },
+  );
+
+  console.log("\nTerminal Evidence (normalized variant):");
+  console.log(JSON.stringify(terminalEvidence2, null, 2));
+
+  const hashesMatch = terminalEvidence.state_hash === terminalEvidence2.state_hash;
+  console.log(`\nHashes match: ${hashesMatch ? "YES (canonicalization working)" : "NO"}`);
+}
+
+// ============================================================================
+// Desktop Accessibility Evidence Demo
+// ============================================================================
+
+async function demoDesktopEvidence(): Promise<void> {
+  console.log("\n" + "=".repeat(60));
+  console.log("Desktop Accessibility Evidence Provider Demo");
+  console.log("=".repeat(60));
+
+  // Simulated desktop accessibility context
+  const desktopContext: DesktopRuntimeContext = {
+    appName: "  Visual Studio Code  ", // Will be trimmed and normalized
+    windowTitle: "main.ts - my-project",
+    focusedRole: "editor",
+    focusedName: "Text Editor",
+    // Simulated UI tree text (in real usage, capture from OS accessibility API)
+    uiTreeText: `
+      Window: Visual Studio Code
+        Toolbar:
+          Button:   New File
+          Button: Save
+        Editor:
+          TextArea: main.ts content
+        StatusBar:
+          Label: Ln 42, Col 15
+    `,
+    confidence: 0.95,
+  };
+
+  // Create provider with capture function
+  const desktopProvider = new OpenClawDesktopAccessibilityEvidenceProvider(
+    () => desktopContext,
+  );
+
+  // Build evidence with canonical hashing
+  const desktopEvidence = await buildDesktopEvidenceFromProvider(
+    desktopProvider,
+    { useCanonicalHash: true },
+  );
+
+  console.log("\nDesktop Evidence:");
+  console.log(JSON.stringify(desktopEvidence, null, 2));
+
+  // Demonstrate hash stability with whitespace variations
+  const desktopContext2: DesktopRuntimeContext = {
+    ...desktopContext,
+    appName: "Visual Studio Code", // Same after normalization
+    // Same content with different whitespace
+    uiTreeText: `Window: Visual Studio Code
+Toolbar:
+Button: New File
+Button: Save
+Editor:
+TextArea: main.ts content
+StatusBar:
+Label: Ln 42, Col 15`,
+  };
+
+  const desktopProvider2 = new OpenClawDesktopAccessibilityEvidenceProvider(
+    () => desktopContext2,
+  );
+
+  const desktopEvidence2 = await buildDesktopEvidenceFromProvider(
+    desktopProvider2,
+    { useCanonicalHash: true },
+  );
+
+  console.log("\nDesktop Evidence (normalized variant):");
+  console.log(JSON.stringify(desktopEvidence2, null, 2));
+
+  const hashesMatch = desktopEvidence.state_hash === desktopEvidence2.state_hash;
+  console.log(`\nHashes match: ${hashesMatch ? "YES (canonicalization working)" : "NO"}`);
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main(): Promise<void> {
+  console.log("OpenClaw Non-Web Evidence Provider Demo");
+  console.log("Demonstrates canonical hashing for terminal and desktop contexts\n");
+
+  await demoTerminalEvidence();
+  await demoDesktopEvidence();
+
+  console.log("\n" + "=".repeat(60));
+  console.log("Demo complete!");
+  console.log("=".repeat(60));
+}
+
+main().catch(console.error);

package/examples/openclaw-plugin-smoke/index.ts

@@ -0,0 +1,30 @@
+import { registerOpenClawPredicateTools } from "../../dist/src/index.js";
+
+export default function register(api: {
+  registerTool: (
+    tool: {
+      name: string;
+      description?: string;
+      execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+    },
+    options?: { optional?: boolean },
+  ) => void;
+}) {
+  registerOpenClawPredicateTools(api, {
+    async executeCmdRun(args) {
+      return {
+        content: [{ type: "text", text: `smoke cmd: ${String(args.command ?? "")}` }],
+      };
+    },
+    async executeFsReadFile(args) {
+      return {
+        content: [{ type: "text", text: `smoke fs: ${String(args.path ?? "")}` }],
+      };
+    },
+    async executeHttpRequest(args) {
+      return {
+        content: [{ type: "text", text: `smoke http: ${String(args.url ?? "")}` }],
+      };
+    },
+  });
+}

package/examples/openclaw-plugin-smoke/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "openclaw-predicate-provider-smoke-plugin",
+  "name": "Predicate Smoke Plugin",
+  "description": "Local smoke plugin that registers Predicate-guarded OpenClaw tools.",
+  "version": "0.0.1",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/examples/openclaw-plugin-smoke/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "openclaw-predicate-provider-smoke-plugin",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  }
+}

package/examples/openclaw_integration_example.py

@@ -0,0 +1,41 @@
+"""Minimal OpenClaw integration sketch using ToolAdapter."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from openclaw_predicate_provider import GuardedProvider, ProviderConfig, ToolAdapter
+
+
+async def fake_cmd_tool(args: dict[str, Any]) -> dict[str, Any]:
+    """Represents the original OpenClaw cmd.run handler."""
+    return {"ok": True, "ran": args.get("command", "")}
+
+
+async def main() -> None:
+    config = ProviderConfig(
+        sidecar_authorize_url="http://127.0.0.1:4000/v1/authorize",
+        request_timeout_ms=300,
+        fail_closed=True,
+    )
+    provider = GuardedProvider(principal="openclaw-agent-local", config=config)
+    adapter = ToolAdapter(provider)
+
+    context = {
+        "source": "trusted_ui",
+        "session_id": "demo-session",
+        "tenant_id": "local-dev",
+    }
+    args = {"command": "echo hello"}
+
+    result = await adapter.run_shell(
+        args=args,
+        context=context,
+        execute=fake_cmd_tool,
+    )
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/examples/policy/README.md

@@ -0,0 +1,165 @@
+# Policy Starter Pack
+
+Ready-to-use policy templates for common OpenClaw security scenarios.
+
+## Quick Start
+
+1. Copy the relevant policy file to your sidecar config directory
+2. Customize paths and hosts for your environment
+3. Restart the sidecar to load the new policy
+
+```bash
+cp examples/policy/workspace-isolation.yaml ~/.predicate/policies/
+predicate-authorityd --policy-dir ~/.predicate/policies/
+```
+
+## Available Policies
+
+### 1. Workspace Isolation (`workspace-isolation.yaml`)
+
+Restricts file operations to a specific project directory. Ideal for:
+- Development agents working on a single project
+- CI/CD agents with bounded scope
+- Sandboxed coding assistants
+
+### 2. Sensitive Path Blocking (`sensitive-paths.yaml`)
+
+Blocks access to common sensitive paths:
+- SSH keys (`~/.ssh/*`)
+- Cloud credentials (`~/.aws/*`, `~/.gcloud/*`, `~/.azure/*`)
+- System configs (`/etc/*`)
+- Environment files (`.env`, `.env.*`)
+
+### 3. Source-Based Trust (`source-trust.yaml`)
+
+Different rules based on request source:
+- `trusted_ui` - Direct user interaction, more permissive
+- `untrusted_dm` - External messages, restrictive
+- `web_content` - Web page content, very restrictive
+
+### 4. Approved Hosts (`approved-hosts.yaml`)
+
+Allowlist for outbound HTTP requests:
+- Internal APIs
+- Known SaaS endpoints
+- Package registries
+
+### 5. Development Workflow (`dev-workflow.yaml`)
+
+Balanced policy for development agents:
+- Allow git, npm, cargo, etc.
+- Allow localhost HTTP
+- Block production endpoints
+- Block destructive commands
+
+### 6. Production Strict (`production-strict.yaml`)
+
+Maximum security for production agents:
+- Explicit allowlist only
+- No shell execution
+- Audit all decisions
+
+## Policy Syntax
+
+Policies use YAML format with the following structure:
+
+```yaml
+version: 1
+
+# Global defaults
+defaults:
+  effect: deny  # deny-by-default recommended
+
+# Rule definitions (evaluated in order)
+rules:
+  - id: unique_rule_id
+    effect: allow | deny
+    action: action.type | action.*
+    resource: path/pattern | [list, of, patterns]
+    when:                    # Optional conditions
+      source: trusted_ui
+      tenant_id: tenant-123
+
+# Metadata
+metadata:
+  name: Policy Name
+  description: What this policy does
+  version: 1.0.0
+```
+
+## Condition Reference
+
+### Source Labels
+
+| Source | Description | Trust Level |
+|--------|-------------|-------------|
+| `trusted_ui` | Direct user input from trusted UI | High |
+| `trusted_api` | Authenticated API request | High |
+| `untrusted_dm` | External message (DM, email) | Low |
+| `web_content` | Content from web pages | Very Low |
+| `system` | Internal system call | High |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `shell.execute` | Run shell command |
+| `fs.read` | Read file |
+| `fs.write` | Write file |
+| `net.http` | HTTP request |
+
+### Resource Patterns
+
+- Exact match: `/path/to/file`
+- Glob: `/workspace/**/*.ts`
+- Home expansion: `~/.ssh/*`
+- List: `["/etc/*", "/var/*"]`
+
+## Combining Policies
+
+Policies can be split across multiple files. The sidecar merges them:
+
+```bash
+~/.predicate/policies/
+├── base.yaml           # Global defaults
+├── workspace.yaml      # Project-specific rules
+└── team-overrides.yaml # Team customizations
+```
+
+Rules are evaluated in filename order. Later files can override earlier ones.
+
+## Testing Policies
+
+Use the policy tester to validate rules before deployment:
+
+```bash
+# Test a specific authorization request
+predicate-authorityd policy test \
+  --policy examples/policy/workspace-isolation.yaml \
+  --principal "agent:test" \
+  --action "fs.read" \
+  --resource "/workspace/src/main.ts" \
+  --context '{"source": "trusted_ui"}'
+
+# Expected output:
+# Decision: ALLOW
+# Matched rule: allow_workspace_reads
+```
+
+## Migration from Other Systems
+
+### From OpenClaw Sandbox
+
+If currently using OpenClaw's built-in sandbox:
+
+1. Start with `workspace-isolation.yaml`
+2. Add your existing sandbox paths to the allow list
+3. Run in audit mode first to catch missing rules
+
+### From HITL-only
+
+If currently using human-in-the-loop for all sensitive actions:
+
+1. Start with `production-strict.yaml`
+2. Gradually add allow rules for common patterns
+3. Keep HITL for truly exceptional cases