predicate-claw 0.1.0

package/src/openclaw_predicate_provider/cli.py

@@ -0,0 +1,160 @@
+"""CLI utilities for provider configuration and sidecar smoke checks."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from typing import Any
+
+from .config import ProviderConfig
+from .errors import ActionDeniedError, SidecarUnavailableError
+from .provider import GuardedProvider
+
+
+def _parse_json_arg(raw: str, label: str) -> dict[str, Any]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON for {label}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be a JSON object")
+    return value
+
+
+def _build_config(args: argparse.Namespace) -> ProviderConfig:
+    return ProviderConfig(
+        sidecar_authorize_url=args.sidecar_url,
+        request_timeout_ms=args.timeout_ms,
+        fail_closed=not args.fail_open,
+        authorization_backend=args.authorization_backend,
+        agentidentity_policy_file=args.agentidentity_policy_file,
+        agentidentity_signing_key=args.agentidentity_signing_key,
+        agentidentity_ttl_seconds=args.agentidentity_ttl_seconds,
+    )
+
+
+def _cmd_validate_config(args: argparse.Namespace) -> int:
+    config = _build_config(args)
+    print("Configuration valid")
+    print(f"sidecar_authorize_url={config.sidecar_authorize_url}")
+    print(f"request_timeout_ms={config.request_timeout_ms}")
+    print(f"fail_closed={config.fail_closed}")
+    print(f"authorization_backend={config.authorization_backend}")
+    return 0
+
+
+async def _cmd_smoke_authorize_async(args: argparse.Namespace) -> int:
+    config = _build_config(args)
+    provider = GuardedProvider(principal=args.principal, config=config)
+    context = _parse_json_arg(args.context_json, "context")
+    payload = _parse_json_arg(args.args_json, "args")
+    try:
+        mandate_id = await provider.guard_or_raise(
+            action=args.action,
+            resource=args.resource,
+            args=payload,
+            context=context,
+        )
+    except ActionDeniedError as exc:
+        print(f"DENY: {exc}")
+        return 2
+    except SidecarUnavailableError as exc:
+        print(f"ERROR: {exc}")
+        return 3
+
+    print("ALLOW")
+    print(f"mandate_id={mandate_id}")
+    return 0
+
+
+def _cmd_smoke_authorize(args: argparse.Namespace) -> int:
+    return asyncio.run(_cmd_smoke_authorize_async(args))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="openclaw-predicate-provider",
+        description="CLI for OpenClaw Predicate provider scaffolding.",
+    )
+    parser.add_argument(
+        "--sidecar-url",
+        default="http://127.0.0.1:4000/v1/authorize",
+        help="Predicate sidecar authorize URL.",
+    )
+    parser.add_argument(
+        "--timeout-ms",
+        type=int,
+        default=300,
+        help="Request timeout in milliseconds.",
+    )
+    parser.add_argument(
+        "--fail-open",
+        action="store_true",
+        help="Disable fail-closed mode (for debugging only).",
+    )
+    parser.add_argument(
+        "--authorization-backend",
+        choices=["http_sidecar", "agentidentity_local"],
+        default="http_sidecar",
+        help="Authorization backend implementation.",
+    )
+    parser.add_argument(
+        "--agentidentity-policy-file",
+        default=None,
+        help="Policy file path for agentidentity_local backend.",
+    )
+    parser.add_argument(
+        "--agentidentity-signing-key",
+        default=None,
+        help="Signing key for agentidentity_local backend.",
+    )
+    parser.add_argument(
+        "--agentidentity-ttl-seconds",
+        type=int,
+        default=300,
+        help="Mandate TTL for agentidentity_local backend bootstrap.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate = subparsers.add_parser(
+        "validate-config",
+        help="Validate and print effective configuration.",
+    )
+    validate.set_defaults(handler=_cmd_validate_config)
+
+    smoke = subparsers.add_parser(
+        "smoke-authorize",
+        help="Run one authorization check against sidecar.",
+    )
+    smoke.add_argument("--principal", default="openclaw-agent-local")
+    smoke.add_argument("--action", default="shell.execute")
+    smoke.add_argument("--resource", default="echo hello")
+    smoke.add_argument(
+        "--args-json",
+        default='{"command":"echo hello"}',
+        help="JSON object for action arguments.",
+    )
+    smoke.add_argument(
+        "--context-json",
+        default='{"source":"trusted_ui","session_id":"smoke"}',
+        help="JSON object for context values.",
+    )
+    smoke.set_defaults(handler=_cmd_smoke_authorize)
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        return int(args.handler(args))
+    except ValueError as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/openclaw_predicate_provider/config.py

@@ -0,0 +1,42 @@
+"""Configuration models for OpenClaw Predicate provider."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ProviderConfig(BaseModel):
+    """Runtime settings for sidecar authorization checks."""
+
+    sidecar_authorize_url: str = Field(
+        default="http://127.0.0.1:4000/v1/authorize",
+        description="Predicate sidecar authorize endpoint.",
+    )
+    request_timeout_ms: int = Field(
+        default=300,
+        ge=50,
+        le=10000,
+        description="Authorization request timeout in milliseconds.",
+    )
+    fail_closed: bool = Field(
+        default=True,
+        description="Block action if sidecar check fails unexpectedly.",
+    )
+    authorization_backend: Literal["http_sidecar", "agentidentity_local"] = Field(
+        default="http_sidecar",
+        description="Authorization execution backend.",
+    )
+    agentidentity_policy_file: str | None = Field(
+        default=None,
+        description="Optional policy file for AgentIdentity local client bootstrap.",
+    )
+    agentidentity_signing_key: str | None = Field(
+        default=None,
+        description="Optional signing key for AgentIdentity local client bootstrap.",
+    )
+    agentidentity_ttl_seconds: int = Field(
+        default=300,
+        ge=30,
+        le=86400,
+        description="TTL used when bootstrapping AgentIdentity local client.",
+    )

package/src/openclaw_predicate_provider/errors.py

@@ -0,0 +1,13 @@
+"""Error types surfaced by provider guard logic."""
+
+
+class GuardError(RuntimeError):
+    """Base guard error."""
+
+
+class ActionDeniedError(GuardError):
+    """Raised when policy denies a tool action."""
+
+
+class SidecarUnavailableError(GuardError):
+    """Raised when sidecar cannot be reached in fail-closed mode."""

package/src/openclaw_predicate_provider/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""Integration adapters for external runtimes."""
+
+from .openclaw_runtime import OpenClawRuntimeIntegrator
+
+__all__ = ["OpenClawRuntimeIntegrator"]

package/src/openclaw_predicate_provider/integrations/openclaw_runtime.py

@@ -0,0 +1,74 @@
+"""Runtime registration scaffold for OpenClaw tool hook integration."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Protocol
+
+from ..openclaw_hooks import HookEnvelope, OpenClawHooks
+
+AsyncToolHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+ContextBuilder = Callable[[str, dict[str, Any]], HookEnvelope]
+
+
+class ToolRegistryProtocol(Protocol):
+    """Minimal tool registry protocol expected from OpenClaw runtime."""
+
+    def get(self, tool_name: str) -> AsyncToolHandler:
+        """Return the current handler for a tool name."""
+
+    def set(self, tool_name: str, handler: AsyncToolHandler) -> None:
+        """Replace a handler for a tool name."""
+
+
+def _default_context_builder(tool_name: str, args: dict[str, Any]) -> HookEnvelope:
+    return HookEnvelope(
+        tool_name=tool_name,
+        args=args,
+        session_id="unknown-session",
+        source="unknown-source",
+    )
+
+
+class OpenClawRuntimeIntegrator:
+    """Registers guarded wrappers around OpenClaw runtime tool handlers."""
+
+    def __init__(
+        self,
+        hooks: OpenClawHooks,
+        context_builder: ContextBuilder | None = None,
+    ):
+        self._hooks = hooks
+        self._context_builder = context_builder or _default_context_builder
+
+    def register(self, registry: ToolRegistryProtocol) -> None:
+        """Wrap runtime handlers for sensitive tools with Predicate checks."""
+        self._wrap_cmd_run(registry)
+        self._wrap_fs_read(registry)
+        self._wrap_http_request(registry)
+
+    def _wrap_cmd_run(self, registry: ToolRegistryProtocol) -> None:
+        original = registry.get("cmd.run")
+
+        async def guarded(args: dict[str, Any]) -> Any:
+            envelope = self._context_builder("cmd.run", args)
+            return await self._hooks.on_cmd_run(envelope, original)
+
+        registry.set("cmd.run", guarded)
+
+    def _wrap_fs_read(self, registry: ToolRegistryProtocol) -> None:
+        original = registry.get("fs.readFile")
+
+        async def guarded(args: dict[str, Any]) -> Any:
+            envelope = self._context_builder("fs.readFile", args)
+            return await self._hooks.on_fs_read(envelope, original)
+
+        registry.set("fs.readFile", guarded)
+
+    def _wrap_http_request(self, registry: ToolRegistryProtocol) -> None:
+        original = registry.get("http.request")
+
+        async def guarded(args: dict[str, Any]) -> Any:
+            envelope = self._context_builder("http.request", args)
+            return await self._hooks.on_http_request(envelope, original)
+
+        registry.set("http.request", guarded)

package/src/openclaw_predicate_provider/models.py

@@ -0,0 +1,19 @@
+"""Request/response contracts for sidecar authorization."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AuthorizationRequest(BaseModel):
+    principal: str
+    action: str
+    resource: str
+    intent_hash: str
+    context: dict[str, Any] = Field(default_factory=dict)
+
+
+class AuthorizationDecision(BaseModel):
+    allow: bool
+    reason: str | None = None
+    mandate_id: str | None = None

package/src/openclaw_predicate_provider/openclaw_hooks.py

@@ -0,0 +1,75 @@
+"""Thin OpenClaw hook interface for guarded tool execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Protocol
+
+from .adapter import ToolAdapter
+
+ToolExecutor = Callable[[dict[str, Any]], Awaitable[Any]]
+
+
+class OpenClawHookContext(Protocol):
+    """Protocol for hook context expected from OpenClaw runtime."""
+
+    session_id: str
+    source: str
+    tenant_id: str | None
+    user_id: str | None
+    trace_id: str | None
+
+
+@dataclass(slots=True)
+class HookEnvelope:
+    """Normalized hook payload for adapter consumption."""
+
+    tool_name: str
+    args: dict[str, Any]
+    session_id: str
+    source: str
+    tenant_id: str | None = None
+    user_id: str | None = None
+    trace_id: str | None = None
+
+    def context(self) -> dict[str, Any]:
+        """Render policy context claims sent to Predicate."""
+        return {
+            "session_id": self.session_id,
+            "source": self.source,
+            "tenant_id": self.tenant_id,
+            "user_id": self.user_id,
+            "trace_id": self.trace_id,
+        }
+
+
+class OpenClawHooks:
+    """Hook surface matching likely OpenClaw tool callback wiring."""
+
+    def __init__(self, adapter: ToolAdapter):
+        self._adapter = adapter
+
+    async def on_cmd_run(self, envelope: HookEnvelope, execute: ToolExecutor) -> Any:
+        return await self._adapter.run_shell(
+            args=envelope.args,
+            context=envelope.context(),
+            execute=execute,
+        )
+
+    async def on_fs_read(self, envelope: HookEnvelope, execute: ToolExecutor) -> Any:
+        return await self._adapter.read_file(
+            args=envelope.args,
+            context=envelope.context(),
+            execute=execute,
+        )
+
+    async def on_http_request(
+        self,
+        envelope: HookEnvelope,
+        execute: ToolExecutor,
+    ) -> Any:
+        return await self._adapter.http_request(
+            args=envelope.args,
+            context=envelope.context(),
+            execute=execute,
+        )

package/src/openclaw_predicate_provider/provider.py

@@ -0,0 +1,69 @@
+"""Guard wrapper used to enforce Predicate checks around tool calls."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from .config import ProviderConfig
+from .errors import ActionDeniedError, SidecarUnavailableError
+from .models import AuthorizationRequest
+from .sidecar import SidecarClient
+
+
+class GuardedProvider:
+    """Entry point for OpenClaw tool-guard integration."""
+
+    def __init__(self, principal: str, config: ProviderConfig | None = None):
+        self._principal = principal
+        self._config = config or ProviderConfig()
+        self._sidecar = SidecarClient(self._config)
+
+    @staticmethod
+    def _intent_hash(args: dict[str, Any]) -> str:
+        encoded = json.dumps(args, separators=(",", ":"), sort_keys=True)
+        return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+    async def authorize(
+        self,
+        *,
+        action: str,
+        resource: str,
+        args: dict[str, Any],
+        context: dict[str, Any],
+    ) -> str | None:
+        """Authorize a tool call and return optional mandate id."""
+        request = AuthorizationRequest(
+            principal=self._principal,
+            action=action,
+            resource=resource,
+            intent_hash=self._intent_hash(args),
+            context=context,
+        )
+        decision = await self._sidecar.authorize(request)
+
+        if decision.allow:
+            return decision.mandate_id
+        raise ActionDeniedError(decision.reason or "denied_by_policy")
+
+    async def guard_or_raise(
+        self,
+        *,
+        action: str,
+        resource: str,
+        args: dict[str, Any],
+        context: dict[str, Any],
+    ) -> str | None:
+        """Fail-closed wrapper used by sensitive tool adapters."""
+        try:
+            return await self.authorize(
+                action=action,
+                resource=resource,
+                args=args,
+                context=context,
+            )
+        except SidecarUnavailableError:
+            if self._config.fail_closed:
+                raise
+            return None

package/src/openclaw_predicate_provider/py.typed

@@ -0,0 +1 @@
+

package/src/openclaw_predicate_provider/sidecar.py

@@ -0,0 +1,59 @@
+"""HTTP client wrapper for Predicate sidecar authorization."""
+
+from __future__ import annotations
+
+import httpx
+
+from .agentidentity_backend import AgentIdentityLocalClient
+from .config import ProviderConfig
+from .errors import SidecarUnavailableError
+from .models import AuthorizationDecision, AuthorizationRequest
+
+
+class SidecarClient:
+    """Small client used by provider guard checks."""
+
+    def __init__(self, config: ProviderConfig):
+        self._config = config
+        self._local_backend = (
+            AgentIdentityLocalClient(config)
+            if config.authorization_backend == "agentidentity_local"
+            else None
+        )
+
+    async def authorize(self, request: AuthorizationRequest) -> AuthorizationDecision:
+        if self._local_backend is not None:
+            return self._local_backend.authorize(request)
+        return await self._authorize_http(request)
+
+    async def _authorize_http(self, request: AuthorizationRequest) -> AuthorizationDecision:
+        timeout_s = self._config.request_timeout_ms / 1000.0
+        try:
+            async with httpx.AsyncClient(timeout=timeout_s) as client:
+                resp = await client.post(
+                    self._config.sidecar_authorize_url,
+                    json=request.model_dump(),
+                )
+        except httpx.HTTPError as exc:
+            raise SidecarUnavailableError("Predicate sidecar unavailable") from exc
+
+        if resp.status_code == 200:
+            body = resp.json() if resp.content else {}
+            return AuthorizationDecision(
+                allow=True,
+                reason=body.get("reason"),
+                mandate_id=body.get("mandate_id"),
+            )
+        if resp.status_code == 403:
+            body = resp.json()
+            return AuthorizationDecision(
+                allow=False,
+                reason=body.get("reason", "denied_by_policy"),
+                mandate_id=body.get("mandate_id"),
+            )
+
+        if self._config.fail_closed:
+            raise SidecarUnavailableError(
+                f"Unexpected sidecar response status: {resp.status_code}"
+            )
+        return AuthorizationDecision(allow=True, reason="fail_open_override")