predicate-claw 0.1.0

package/src/provider.ts

@@ -0,0 +1,220 @@
+import crypto from "node:crypto";
+import type { AuthorizationRequest } from "@predicatesystems/authority";
+import {
+  type AuthorityAdapter,
+  createDefaultAuthorityAdapter,
+} from "./authority-client.js";
+import { defaultProviderConfig, type ProviderConfig } from "./config.js";
+import { ActionDeniedError, SidecarUnavailableError } from "./errors.js";
+
+export interface GuardRequest {
+  action: string;
+  resource: string;
+  args: Record<string, unknown>;
+  context?: Record<string, unknown>;
+}
+
+export interface GuardedProviderOptions {
+  principal: string;
+  config?: Partial<ProviderConfig>;
+  authorityClient?: AuthorityAdapter;
+  telemetry?: GuardTelemetry;
+  auditExporter?: DecisionAuditExporter;
+}
+
+export interface DecisionTelemetryEvent {
+  principal: string;
+  action: string;
+  resource: string;
+  outcome: "allow" | "deny" | "error";
+  reason?: string;
+  mandateId?: string;
+  sessionId?: string;
+  tenantId?: string;
+  userId?: string;
+  traceId?: string;
+  source?: string;
+  timestamp: string;
+}
+
+export interface GuardTelemetry {
+  onDecision?(event: DecisionTelemetryEvent): void;
+}
+
+export interface DecisionAuditExporter {
+  exportDecision(event: DecisionTelemetryEvent): Promise<void> | void;
+}
+
+export class GuardedProvider {
+  private readonly principal: string;
+  private readonly config: ProviderConfig;
+  private readonly authorityClient: AuthorityAdapter;
+  private readonly telemetry?: GuardTelemetry;
+  private readonly auditExporter?: DecisionAuditExporter;
+
+  constructor(options: GuardedProviderOptions) {
+    this.principal = options.principal;
+    this.config = { ...defaultProviderConfig, ...(options.config ?? {}) };
+    this.authorityClient =
+      options.authorityClient ?? createDefaultAuthorityAdapter(this.config);
+    this.telemetry = options.telemetry;
+    this.auditExporter = options.auditExporter;
+  }
+
+  static intentHash(args: Record<string, unknown>): string {
+    const encoded = stableJson(args);
+    return crypto.createHash("sha256").update(encoded).digest("hex");
+  }
+
+  async authorize(request: GuardRequest): Promise<string | null> {
+    const wireRequest: AuthorizationRequest = {
+      principal: this.principal,
+      action: request.action,
+      resource: request.resource,
+      intent_hash: GuardedProvider.intentHash(request.args),
+      labels: labelsFromContext(request.context),
+    };
+
+    try {
+      const decision = await this.authorityClient.authorize(wireRequest);
+      if (decision.allow) {
+        await this.emitDecisionEvent({
+          principal: this.principal,
+          action: request.action,
+          resource: redactResource(request.action, request.resource),
+          outcome: "allow",
+          reason: decision.reason,
+          mandateId: decision.mandateId,
+          ...contextFields(request.context),
+          timestamp: new Date().toISOString(),
+        });
+        return decision.mandateId ?? null;
+      }
+      await this.emitDecisionEvent({
+        principal: this.principal,
+        action: request.action,
+        resource: redactResource(request.action, request.resource),
+        outcome: "deny",
+        reason: decision.reason ?? "denied_by_policy",
+        mandateId: decision.mandateId,
+        ...contextFields(request.context),
+        timestamp: new Date().toISOString(),
+      });
+      throw new ActionDeniedError(decision.reason ?? "denied_by_policy");
+    } catch (error) {
+      if (error instanceof ActionDeniedError) {
+        throw error;
+      }
+      if (error instanceof SidecarUnavailableError) {
+        await this.emitDecisionEvent({
+          principal: this.principal,
+          action: request.action,
+          resource: redactResource(request.action, request.resource),
+          outcome: "error",
+          reason: error.message,
+          ...contextFields(request.context),
+          timestamp: new Date().toISOString(),
+        });
+        throw error;
+      }
+      await this.emitDecisionEvent({
+        principal: this.principal,
+        action: request.action,
+        resource: redactResource(request.action, request.resource),
+        outcome: "error",
+        reason: "Predicate sidecar unavailable",
+        ...contextFields(request.context),
+        timestamp: new Date().toISOString(),
+      });
+      throw new SidecarUnavailableError("Predicate sidecar unavailable");
+    }
+  }
+
+  async guardOrThrow(request: GuardRequest): Promise<string | null> {
+    try {
+      return await this.authorize(request);
+    } catch (error) {
+      if (
+        error instanceof SidecarUnavailableError &&
+        this.config.failClosed === false
+      ) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  private async emitDecisionEvent(event: DecisionTelemetryEvent): Promise<void> {
+    this.telemetry?.onDecision?.(event);
+    if (!this.auditExporter) {
+      return;
+    }
+    try {
+      await this.auditExporter.exportDecision(event);
+    } catch {
+      // Best-effort export; authorization path must not fail on telemetry sink issues.
+    }
+  }
+}
+
+function labelsFromContext(
+  context: Record<string, unknown> | undefined,
+): string[] {
+  if (!context) return [];
+  const labels: string[] = [];
+  const source = context.source;
+  if (typeof source === "string" && source.length > 0) {
+    labels.push(`source:${source}`);
+  }
+  return labels;
+}
+
+function contextFields(
+  context: Record<string, unknown> | undefined,
+): Pick<
+  DecisionTelemetryEvent,
+  "sessionId" | "tenantId" | "userId" | "traceId" | "source"
+> {
+  return {
+    sessionId:
+      typeof context?.session_id === "string" ? context.session_id : undefined,
+    tenantId:
+      typeof context?.tenant_id === "string" ? context.tenant_id : undefined,
+    userId: typeof context?.user_id === "string" ? context.user_id : undefined,
+    traceId:
+      typeof context?.trace_id === "string" ? context.trace_id : undefined,
+    source: typeof context?.source === "string" ? context.source : undefined,
+  };
+}
+
+function redactResource(action: string, resource: string): string {
+  if (action === "fs.read" || action === "fs.write") {
+    const lowered = resource.toLowerCase();
+    if (
+      lowered.includes("/.ssh/") ||
+      lowered.includes("/etc/") ||
+      lowered.includes("id_rsa") ||
+      lowered.includes("credentials")
+    ) {
+      return "[REDACTED]";
+    }
+  }
+  return resource;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => stableJson(v)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).sort(
+      ([a], [b]) => a.localeCompare(b),
+    );
+    return `{${entries
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableJson(v)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export { ActionDeniedError, SidecarUnavailableError } from "./errors.js";

package/src/runtime-integration.ts

@@ -0,0 +1,68 @@
+import { HookEnvelope, type OpenClawHooks } from "./openclaw-hooks.js";
+
+type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface ToolRegistry {
+  get(toolName: string): ToolHandler;
+  set(toolName: string, handler: ToolHandler): void;
+}
+
+export interface RuntimeIntegratorOptions {
+  hooks: Pick<OpenClawHooks, "onCmdRun" | "onFsRead" | "onHttpRequest">;
+  contextBuilder?: (toolName: string, args: Record<string, unknown>) => HookEnvelope;
+}
+
+export class OpenClawRuntimeIntegrator {
+  private readonly hooks: RuntimeIntegratorOptions["hooks"];
+  private readonly contextBuilder: (
+    toolName: string,
+    args: Record<string, unknown>,
+  ) => HookEnvelope;
+
+  constructor(options: RuntimeIntegratorOptions) {
+    this.hooks = options.hooks;
+    this.contextBuilder = options.contextBuilder ?? defaultContextBuilder;
+  }
+
+  register(registry: ToolRegistry): void {
+    this.wrapCmdRun(registry);
+    this.wrapFsRead(registry);
+    this.wrapHttpRequest(registry);
+  }
+
+  private wrapCmdRun(registry: ToolRegistry): void {
+    const original = registry.get("cmd.run");
+    registry.set("cmd.run", async (args: Record<string, unknown>) => {
+      const envelope = this.contextBuilder("cmd.run", args);
+      return this.hooks.onCmdRun(envelope, original);
+    });
+  }
+
+  private wrapFsRead(registry: ToolRegistry): void {
+    const original = registry.get("fs.readFile");
+    registry.set("fs.readFile", async (args: Record<string, unknown>) => {
+      const envelope = this.contextBuilder("fs.readFile", args);
+      return this.hooks.onFsRead(envelope, original);
+    });
+  }
+
+  private wrapHttpRequest(registry: ToolRegistry): void {
+    const original = registry.get("http.request");
+    registry.set("http.request", async (args: Record<string, unknown>) => {
+      const envelope = this.contextBuilder("http.request", args);
+      return this.hooks.onHttpRequest(envelope, original);
+    });
+  }
+}
+
+function defaultContextBuilder(
+  toolName: string,
+  args: Record<string, unknown>,
+): HookEnvelope {
+  return new HookEnvelope({
+    toolName,
+    args,
+    sessionId: "unknown-session",
+    source: "unknown-source",
+  });
+}

package/src/web-evidence.ts

@@ -0,0 +1,95 @@
+import crypto from "node:crypto";
+import {
+  buildWebStateEvidence,
+  buildWebStateEvidenceFromRuntimeSnapshot,
+  type RuntimeSnapshotLike,
+  type StateEvidence,
+  type WebStateSnapshot,
+} from "@predicatesystems/authority";
+
+/**
+ * Runtime context captured from OpenClaw web agent execution environment.
+ * Maps to ts-predicate-authority WebStateSnapshot contract.
+ */
+export interface WebRuntimeContext {
+  url?: string;
+  title?: string;
+  domHtml?: string;
+  domHash?: string;
+  visibleText?: string;
+  visibleTextHash?: string;
+  eventId?: string;
+  observedAt?: string;
+  dominantGroupKey?: string;
+  snapshotTimestamp?: string;
+  confidence?: number;
+  confidenceReasons?: string[];
+}
+
+/**
+ * Provider interface for web state evidence capture.
+ * Implementations should capture browser/DOM state from the agent runtime.
+ */
+export interface WebEvidenceProvider {
+  captureWebSnapshot(): Promise<WebStateSnapshot>;
+}
+
+/**
+ * OpenClaw-specific web evidence provider.
+ * Captures web state from the agent runtime and maps to TS SDK contract.
+ */
+export class OpenClawWebEvidenceProvider implements WebEvidenceProvider {
+  constructor(
+    private readonly capture: () =>
+      | Promise<WebRuntimeContext>
+      | WebRuntimeContext,
+  ) {}
+
+  async captureWebSnapshot(): Promise<WebStateSnapshot> {
+    const runtime = await this.capture();
+    return {
+      url: runtime.url,
+      title: runtime.title,
+      dom_hash: runtime.domHash ?? sha256(runtime.domHtml ?? ""),
+      visible_text_hash:
+        runtime.visibleTextHash ?? sha256(runtime.visibleText ?? ""),
+      event_id: runtime.eventId,
+      observed_at: runtime.observedAt ?? new Date().toISOString(),
+      dominant_group_key: runtime.dominantGroupKey,
+      snapshot_timestamp: runtime.snapshotTimestamp,
+      confidence: runtime.confidence,
+      confidence_reasons: runtime.confidenceReasons,
+    };
+  }
+}
+
+/**
+ * Build StateEvidence from an OpenClaw web evidence provider.
+ */
+export async function buildWebEvidenceFromProvider(
+  provider: WebEvidenceProvider,
+  options?: { schemaVersion?: string },
+): Promise<StateEvidence> {
+  const snapshot = await provider.captureWebSnapshot();
+  return buildWebStateEvidence({
+    snapshot,
+    schemaVersion: options?.schemaVersion ?? "v1",
+  });
+}
+
+/**
+ * Convenience adapter for predicate-runtime snapshot output.
+ * Maps RuntimeSnapshotLike to StateEvidence directly.
+ */
+export function buildWebEvidenceFromRuntimeSnapshot(
+  snapshot: RuntimeSnapshotLike,
+  options?: { schemaVersion?: string },
+): StateEvidence {
+  return buildWebStateEvidenceFromRuntimeSnapshot(snapshot, {
+    schemaVersion: options?.schemaVersion ?? "v1",
+  });
+}
+
+function sha256(input: string): string {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}

package/tests/adapter.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import { ToolAdapter } from "../src/adapter.js";
+import { ActionDeniedError } from "../src/errors.js";
+
+describe("ToolAdapter", () => {
+  it("maps cmd.run to shell.execute", async () => {
+    const seen: Array<{ action: string; resource: string }> = [];
+    const adapter = new ToolAdapter({
+      guardOrThrow: async ({ action, resource }) => {
+        seen.push({ action, resource });
+        return "mnd_test";
+      },
+    });
+
+    const result = await adapter.runShell({
+      args: { command: "echo hi" },
+      context: { source: "trusted_ui" },
+      execute: async (args) => args,
+    });
+
+    expect(result).toEqual({ command: "echo hi" });
+    expect(seen).toEqual([{ action: "shell.execute", resource: "echo hi" }]);
+  });
+
+  it("bubbles deny errors", async () => {
+    const adapter = new ToolAdapter({
+      guardOrThrow: async () => {
+        throw new ActionDeniedError("denied_by_policy");
+      },
+    });
+
+    await expect(
+      adapter.readFile({
+        args: { path: "/etc/passwd" },
+        context: { source: "untrusted_dm" },
+        execute: async (args) => args,
+      }),
+    ).rejects.toBeInstanceOf(ActionDeniedError);
+  });
+
+  it("maps fs.readFile to fs.read", async () => {
+    const seen: Array<{ action: string; resource: string }> = [];
+    const adapter = new ToolAdapter({
+      guardOrThrow: async ({ action, resource }) => {
+        seen.push({ action, resource });
+        return "mnd_test";
+      },
+    });
+
+    await adapter.readFile({
+      args: { path: "/tmp/demo.txt" },
+      context: { source: "trusted_ui" },
+      execute: async (args) => args,
+    });
+
+    expect(seen).toEqual([{ action: "fs.read", resource: "/tmp/demo.txt" }]);
+  });
+
+  it("maps http.request to net.http", async () => {
+    const seen: Array<{ action: string; resource: string }> = [];
+    const adapter = new ToolAdapter({
+      guardOrThrow: async ({ action, resource }) => {
+        seen.push({ action, resource });
+        return "mnd_test";
+      },
+    });
+
+    await adapter.httpRequest({
+      args: { url: "https://example.com" },
+      context: { source: "trusted_ui" },
+      execute: async (args) => args,
+    });
+
+    expect(seen).toEqual([{ action: "net.http", resource: "https://example.com" }]);
+  });
+});