predicate-claw 0.1.0

package/src/control-plane-sync.ts

@@ -0,0 +1,159 @@
+export interface ControlPlaneSyncConfig {
+  baseUrl: string;
+  tenantId: string;
+  timeoutMs?: number;
+}
+
+export interface PolicySyncSnapshot {
+  version: string;
+  cursor: string;
+  rules: unknown[];
+}
+
+export interface RevocationSyncSnapshot {
+  version: string;
+  cursor: string;
+  revoked: unknown[];
+}
+
+export interface ControlPlaneSyncStatus {
+  policyVersion: string;
+  revocationVersion: string;
+  pinnedPolicyVersion?: string;
+  policyVersionMismatch: boolean;
+  stale: boolean;
+  syncAgeMs: number;
+  lastSyncedAtMs: number;
+}
+
+export interface ControlPlaneSyncStatusTrackerOptions {
+  pinnedPolicyVersion?: string;
+  staleAfterMs?: number;
+  onStatus?: (status: ControlPlaneSyncStatus) => void;
+}
+
+export class ControlPlaneSyncClient {
+  private readonly baseUrl: string;
+  private readonly tenantId: string;
+  private readonly timeoutMs: number;
+
+  constructor(config: ControlPlaneSyncConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.tenantId = config.tenantId;
+    this.timeoutMs = config.timeoutMs ?? 3000;
+  }
+
+  async pullPolicySnapshot(
+    cursor?: string,
+  ): Promise<PolicySyncSnapshot> {
+    const url = new URL(`${this.baseUrl}/v1/policy/sync`);
+    url.searchParams.set("tenant_id", this.tenantId);
+    if (cursor) {
+      url.searchParams.set("cursor", cursor);
+    }
+    const response = await this.fetchWithTimeout(url.toString());
+    if (!response.ok) {
+      throw new Error(`policy sync failed: ${response.status}`);
+    }
+    return (await response.json()) as PolicySyncSnapshot;
+  }
+
+  async pullRevocationSnapshot(
+    cursor?: string,
+  ): Promise<RevocationSyncSnapshot> {
+    const url = new URL(`${this.baseUrl}/v1/revocations/sync`);
+    url.searchParams.set("tenant_id", this.tenantId);
+    if (cursor) {
+      url.searchParams.set("cursor", cursor);
+    }
+    const response = await this.fetchWithTimeout(url.toString());
+    if (!response.ok) {
+      throw new Error(`revocation sync failed: ${response.status}`);
+    }
+    return (await response.json()) as RevocationSyncSnapshot;
+  }
+
+  private async fetchWithTimeout(input: string): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(input, { signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+export class ControlPlaneSyncStatusTracker {
+  private readonly pinnedPolicyVersion?: string;
+  private readonly staleAfterMs: number;
+  private readonly onStatus?: (status: ControlPlaneSyncStatus) => void;
+  private latest?: {
+    policyVersion: string;
+    revocationVersion: string;
+    lastSyncedAtMs: number;
+  };
+
+  constructor(options?: ControlPlaneSyncStatusTrackerOptions) {
+    this.pinnedPolicyVersion = options?.pinnedPolicyVersion;
+    this.staleAfterMs = options?.staleAfterMs ?? 300000;
+    this.onStatus = options?.onStatus;
+  }
+
+  recordSync(
+    snapshot: { policy: PolicySyncSnapshot; revocations: RevocationSyncSnapshot },
+    nowMs: number = Date.now(),
+  ): ControlPlaneSyncStatus {
+    this.latest = {
+      policyVersion: snapshot.policy.version,
+      revocationVersion: snapshot.revocations.version,
+      lastSyncedAtMs: nowMs,
+    };
+    const status = this.snapshot(nowMs);
+    this.onStatus?.(status);
+    return status;
+  }
+
+  snapshot(nowMs: number = Date.now()): ControlPlaneSyncStatus {
+    if (!this.latest) {
+      return {
+        policyVersion: "unknown",
+        revocationVersion: "unknown",
+        pinnedPolicyVersion: this.pinnedPolicyVersion,
+        policyVersionMismatch: false,
+        stale: true,
+        syncAgeMs: Number.POSITIVE_INFINITY,
+        lastSyncedAtMs: 0,
+      };
+    }
+    const syncAgeMs = Math.max(0, nowMs - this.latest.lastSyncedAtMs);
+    const policyVersionMismatch =
+      typeof this.pinnedPolicyVersion === "string" &&
+      this.pinnedPolicyVersion.length > 0
+        ? this.latest.policyVersion !== this.pinnedPolicyVersion
+        : false;
+    return {
+      policyVersion: this.latest.policyVersion,
+      revocationVersion: this.latest.revocationVersion,
+      pinnedPolicyVersion: this.pinnedPolicyVersion,
+      policyVersionMismatch,
+      stale: syncAgeMs > this.staleAfterMs,
+      syncAgeMs,
+      lastSyncedAtMs: this.latest.lastSyncedAtMs,
+    };
+  }
+}
+
+export async function syncControlPlaneState(
+  client: ControlPlaneSyncClient,
+  cursors?: { policyCursor?: string; revocationCursor?: string },
+): Promise<{
+  policy: PolicySyncSnapshot;
+  revocations: RevocationSyncSnapshot;
+}> {
+  const [policy, revocations] = await Promise.all([
+    client.pullPolicySnapshot(cursors?.policyCursor),
+    client.pullRevocationSnapshot(cursors?.revocationCursor),
+  ]);
+  return { policy, revocations };
+}

package/src/errors.ts

@@ -0,0 +1,5 @@
+export class GuardError extends Error {}
+
+export class ActionDeniedError extends GuardError {}
+
+export class SidecarUnavailableError extends GuardError {}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./adapter.js";
+export * from "./authority-client.js";
+export * from "./circuit-breaker.js";
+export * from "./config.js";
+export * from "./control-plane-sync.js";
+export * from "./errors.js";
+export * from "./non-web-evidence.js";
+export * from "./web-evidence.js";
+export * from "./openclaw-hooks.js";
+export * from "./openclaw-plugin-api.js";
+export * from "./provider.js";
+export * from "./runtime-integration.js";

package/src/non-web-evidence.ts

@@ -0,0 +1,116 @@
+import {
+  type DesktopAccessibilityEvidenceProvider,
+  type DesktopAccessibilitySnapshot,
+  type StateEvidence,
+  type TerminalEvidenceProvider,
+  type TerminalSessionSnapshot,
+  buildDesktopAccessibilityStateEvidence,
+  buildTerminalStateEvidence,
+} from "@predicatesystems/authority";
+
+export interface TerminalRuntimeContext {
+  sessionId: string;
+  terminalId?: string;
+  cwd?: string;
+  command?: string;
+  /** Raw transcript text (will be canonicalized before hashing) */
+  transcript?: string;
+  observedAt?: string;
+  confidence?: number;
+  /** Environment variables (secrets will be redacted before hashing) */
+  env?: Record<string, string>;
+}
+
+export interface DesktopRuntimeContext {
+  appName?: string;
+  windowTitle?: string;
+  focusedRole?: string;
+  focusedName?: string;
+  /** Raw UI tree text (will be normalized before hashing) */
+  uiTreeText?: string;
+  /** Pre-computed UI tree hash (bypasses canonicalization) */
+  uiTreeHash?: string;
+  observedAt?: string;
+  confidence?: number;
+}
+
+export class OpenClawTerminalEvidenceProvider
+  implements TerminalEvidenceProvider
+{
+  constructor(
+    private readonly capture: () =>
+      | Promise<TerminalRuntimeContext>
+      | TerminalRuntimeContext,
+  ) {}
+
+  async captureTerminalSnapshot(): Promise<TerminalSessionSnapshot> {
+    const runtime = await this.capture();
+    return {
+      session_id: runtime.sessionId,
+      terminal_id: runtime.terminalId,
+      cwd: runtime.cwd,
+      command: runtime.command,
+      // Pass raw transcript - canonicalization happens in buildTerminalStateEvidence
+      // when useCanonicalHash is enabled. The field is named transcript_hash for
+      // backward compatibility but carries raw text when canonical hashing is used.
+      transcript_hash: runtime.transcript ?? "",
+      observed_at: runtime.observedAt ?? new Date().toISOString(),
+      confidence: runtime.confidence,
+    };
+  }
+}
+
+export class OpenClawDesktopAccessibilityEvidenceProvider
+  implements DesktopAccessibilityEvidenceProvider
+{
+  constructor(
+    private readonly capture: () =>
+      | Promise<DesktopRuntimeContext>
+      | DesktopRuntimeContext,
+  ) {}
+
+  async captureAccessibilitySnapshot(): Promise<DesktopAccessibilitySnapshot> {
+    const runtime = await this.capture();
+    // Pass raw UI tree text - canonicalization happens in buildDesktopAccessibilityStateEvidence
+    // when useCanonicalHash is enabled. Use pre-computed hash if available for legacy mode.
+    // The field is named ui_tree_hash for backward compatibility but carries raw text
+    // when canonical hashing is used.
+    return {
+      app_name: runtime.appName,
+      window_title: runtime.windowTitle,
+      focused_role: runtime.focusedRole,
+      focused_name: runtime.focusedName,
+      ui_tree_hash: runtime.uiTreeHash ?? runtime.uiTreeText ?? "",
+      observed_at: runtime.observedAt ?? new Date().toISOString(),
+      confidence: runtime.confidence,
+    };
+  }
+}
+
+export interface BuildEvidenceOptions {
+  /**
+   * Use canonical hashing with proper normalization.
+   * When true, applies ANSI stripping, timestamp normalization, whitespace
+   * collapsing, and other canonicalization rules for reproducible hashes.
+   * @default true
+   */
+  useCanonicalHash?: boolean;
+}
+
+export async function buildTerminalEvidenceFromProvider(
+  provider: TerminalEvidenceProvider,
+  options: BuildEvidenceOptions = {},
+): Promise<StateEvidence> {
+  const snapshot = await provider.captureTerminalSnapshot();
+  const useCanonicalHash = options.useCanonicalHash ?? true;
+  return buildTerminalStateEvidence({ snapshot, useCanonicalHash });
+}
+
+export async function buildDesktopEvidenceFromProvider(
+  provider: DesktopAccessibilityEvidenceProvider,
+  options: BuildEvidenceOptions = {},
+): Promise<StateEvidence> {
+  const snapshot = await provider.captureAccessibilitySnapshot();
+  const useCanonicalHash = options.useCanonicalHash ?? true;
+  return buildDesktopAccessibilityStateEvidence({ snapshot, useCanonicalHash });
+}

package/src/openclaw-hooks.ts

@@ -0,0 +1,76 @@
+import type { ToolAdapter } from "./adapter.js";
+
+export class HookEnvelope {
+  readonly toolName: string;
+  readonly args: Record<string, unknown>;
+  readonly sessionId: string;
+  readonly source: string;
+  readonly tenantId?: string;
+  readonly userId?: string;
+  readonly traceId?: string;
+
+  constructor(params: {
+    toolName: string;
+    args: Record<string, unknown>;
+    sessionId: string;
+    source: string;
+    tenantId?: string;
+    userId?: string;
+    traceId?: string;
+  }) {
+    this.toolName = params.toolName;
+    this.args = params.args;
+    this.sessionId = params.sessionId;
+    this.source = params.source;
+    this.tenantId = params.tenantId;
+    this.userId = params.userId;
+    this.traceId = params.traceId;
+  }
+
+  context(): Record<string, unknown> {
+    return {
+      session_id: this.sessionId,
+      source: this.source,
+      tenant_id: this.tenantId,
+      user_id: this.userId,
+      trace_id: this.traceId,
+    };
+  }
+}
+
+export class OpenClawHooks {
+  constructor(private readonly adapter: Pick<ToolAdapter, "runShell" | "readFile" | "httpRequest">) {}
+
+  onCmdRun(
+    envelope: HookEnvelope,
+    execute: (args: Record<string, unknown>) => Promise<unknown>,
+  ) {
+    return this.adapter.runShell({
+      args: envelope.args,
+      context: envelope.context(),
+      execute,
+    });
+  }
+
+  onFsRead(
+    envelope: HookEnvelope,
+    execute: (args: Record<string, unknown>) => Promise<unknown>,
+  ) {
+    return this.adapter.readFile({
+      args: envelope.args,
+      context: envelope.context(),
+      execute,
+    });
+  }
+
+  onHttpRequest(
+    envelope: HookEnvelope,
+    execute: (args: Record<string, unknown>) => Promise<unknown>,
+  ) {
+    return this.adapter.httpRequest({
+      args: envelope.args,
+      context: envelope.context(),
+      execute,
+    });
+  }
+}

package/src/openclaw-plugin-api.ts

@@ -0,0 +1,51 @@
+interface RegisteredTool {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+  execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+}
+
+interface OpenClawPluginApi {
+  registerTool(tool: RegisteredTool, options?: { optional?: boolean }): void;
+}
+
+interface PredicateToolHandlers {
+  executeCmdRun(args: Record<string, unknown>): Promise<unknown>;
+  executeFsReadFile(args: Record<string, unknown>): Promise<unknown>;
+  executeHttpRequest(args: Record<string, unknown>): Promise<unknown>;
+}
+
+export function registerOpenClawPredicateTools(
+  api: OpenClawPluginApi,
+  handlers: PredicateToolHandlers,
+): void {
+  api.registerTool(
+    {
+      name: "predicate_cmd_run",
+      description: "Guarded shell execution routed through Predicate Authority.",
+      execute: async (_id: string, params: Record<string, unknown>) =>
+        handlers.executeCmdRun(params),
+    },
+    { optional: true },
+  );
+
+  api.registerTool(
+    {
+      name: "predicate_fs_read_file",
+      description: "Guarded file read routed through Predicate Authority.",
+      execute: async (_id: string, params: Record<string, unknown>) =>
+        handlers.executeFsReadFile(params),
+    },
+    { optional: true },
+  );
+
+  api.registerTool(
+    {
+      name: "predicate_http_request",
+      description: "Guarded HTTP request routed through Predicate Authority.",
+      execute: async (_id: string, params: Record<string, unknown>) =>
+        handlers.executeHttpRequest(params),
+    },
+    { optional: true },
+  );
+}

package/src/openclaw_predicate_provider/__init__.py

@@ -0,0 +1,16 @@
+"""OpenClaw Predicate provider package."""
+
+from .adapter import ToolAdapter
+from .config import ProviderConfig
+from .integrations import OpenClawRuntimeIntegrator
+from .openclaw_hooks import HookEnvelope, OpenClawHooks
+from .provider import GuardedProvider
+
+__all__ = [
+    "ProviderConfig",
+    "GuardedProvider",
+    "ToolAdapter",
+    "OpenClawRuntimeIntegrator",
+    "HookEnvelope",
+    "OpenClawHooks",
+]

package/src/openclaw_predicate_provider/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/openclaw_predicate_provider/adapter.py

@@ -0,0 +1,84 @@
+"""OpenClaw adapter scaffolding for guarded tool execution."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from .provider import GuardedProvider
+
+ToolCallable = Callable[[dict[str, Any]], Awaitable[Any]]
+
+
+class ToolAdapter:
+    """Wrap tool handlers with Predicate guard checks."""
+
+    def __init__(self, guard: GuardedProvider):
+        self._guard = guard
+
+    async def run(
+        self,
+        *,
+        action: str,
+        resource: str,
+        args: dict[str, Any],
+        context: dict[str, Any],
+        execute: ToolCallable,
+    ) -> Any:
+        await self._guard.guard_or_raise(
+            action=action,
+            resource=resource,
+            args=args,
+            context=context,
+        )
+        return await execute(args)
+
+    async def run_shell(
+        self,
+        *,
+        args: dict[str, Any],
+        context: dict[str, Any],
+        execute: ToolCallable,
+    ) -> Any:
+        """Guard OpenClaw command execution."""
+        resource = str(args.get("command", ""))
+        return await self.run(
+            action="shell.execute",
+            resource=resource,
+            args=args,
+            context=context,
+            execute=execute,
+        )
+
+    async def read_file(
+        self,
+        *,
+        args: dict[str, Any],
+        context: dict[str, Any],
+        execute: ToolCallable,
+    ) -> Any:
+        """Guard OpenClaw file-read execution."""
+        resource = str(args.get("path", ""))
+        return await self.run(
+            action="fs.read",
+            resource=resource,
+            args=args,
+            context=context,
+            execute=execute,
+        )
+
+    async def http_request(
+        self,
+        *,
+        args: dict[str, Any],
+        context: dict[str, Any],
+        execute: ToolCallable,
+    ) -> Any:
+        """Guard OpenClaw outbound HTTP execution."""
+        resource = str(args.get("url", ""))
+        return await self.run(
+            action="net.http",
+            resource=resource,
+            args=args,
+            context=context,
+            execute=execute,
+        )

package/src/openclaw_predicate_provider/agentidentity_backend.py

@@ -0,0 +1,78 @@
+"""Optional AgentIdentity SDK-backed authorization backend."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .config import ProviderConfig
+from .errors import SidecarUnavailableError
+from .models import AuthorizationDecision, AuthorizationRequest
+
+if TYPE_CHECKING:
+    from predicate_authority.client import AuthorityClient
+
+
+class AgentIdentityLocalClient:
+    """Adapter that uses AgentIdentity local SDK authorization primitives."""
+
+    def __init__(self, config: ProviderConfig):
+        self._client = self._build_client(config)
+
+    @staticmethod
+    def _build_client(config: ProviderConfig) -> "AuthorityClient":
+        try:
+            from predicate_authority.client import AuthorityClient
+        except ImportError as exc:  # pragma: no cover - environment-dependent
+            raise SidecarUnavailableError(
+                "AgentIdentity SDK unavailable. Install predicate-authority package."
+            ) from exc
+
+        if config.agentidentity_policy_file and config.agentidentity_signing_key:
+            local_ctx = AuthorityClient.from_policy_file(
+                policy_file=config.agentidentity_policy_file,
+                secret_key=config.agentidentity_signing_key,
+                ttl_seconds=config.agentidentity_ttl_seconds,
+            )
+            return local_ctx.client
+        local_ctx = AuthorityClient.from_env()
+        return local_ctx.client
+
+    def authorize(self, request: AuthorizationRequest) -> AuthorizationDecision:
+        try:
+            from predicate_authority.integrations.sdk_python import (
+                SdkStepEvidence,
+                to_action_request,
+            )
+        except ImportError as exc:  # pragma: no cover - environment-dependent
+            raise SidecarUnavailableError(
+                "AgentIdentity sdk_python integration module unavailable."
+            ) from exc
+
+        state_hash = str(request.context.get("state_hash", request.intent_hash))
+        step = SdkStepEvidence(
+            principal_id=request.principal,
+            action=request.action,
+            resource=request.resource,
+            intent=request.intent_hash,
+            state_hash=state_hash,
+            tenant_id=_string_or_none(request.context.get("tenant_id")),
+            session_id=_string_or_none(request.context.get("session_id")),
+        )
+        decision = self._client.authorize(to_action_request(step))
+        mandate_id = decision.mandate.claims.mandate_id if decision.mandate else None
+        reason = (
+            decision.reason.value
+            if hasattr(decision.reason, "value")
+            else str(decision.reason)
+        )
+        return AuthorizationDecision(
+            allow=decision.allowed,
+            reason=reason,
+            mandate_id=mandate_id,
+        )
+
+
+def _string_or_none(value: Any) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value
+    return None