Pre-authorization. Post-verification. Zero-trust AI agent security.
+
+ See how it works β
@@ -18,7 +20,7 @@
- 
+
diff --git a/docs/secureclaw-architecture.md b/docs/secureclaw-architecture.md
new file mode 100644
index 000000000000..bbcfb492fb49
--- /dev/null
+++ b/docs/secureclaw-architecture.md
@@ -0,0 +1,246 @@
+# SecureClaw Architecture
+
+## How SecureClaw Works
+
+SecureClaw adds a **zero-trust security layer** to OpenClaw by intercepting every tool call and enforcing authorization policies before execution.
+
+## Architecture Diagram
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β AI AGENT (OpenClaw) β
+β β
+β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ β
+β β Read β β Write β β Bash β β WebFetch β β
+β β Tool β β Tool β β Tool β β Tool β β
+β ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ β
+β β β β β β
+β ββββββββββββββββββββ΄βββββββββ¬ββββββββββ΄βββββββββββββββββββ β
+β β β
+β βΌ β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β SECURECLAW PLUGIN β β
+β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
+β β β before_tool_call Hook β β β
+β β β βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββ β β β
+β β β β Extract β β Build β β Call β β β β
+β β β β Action & ββββ Guard ββββ guardOrThrow() β β β β
+β β β β Resource β β Request β β via SDK β β β β
+β β β βββββββββββββββ βββββββββββββββ ββββββββββββ¬βββββββββββ β β β
+β β βββββββββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββ β β
+β ββββββββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββββββββββββ β
+β β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββ
+ β
+ βΌ
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β PREDICATE-CLAW SDK β
+β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β GuardedProvider β β
+β β β’ Formats authorization request β β
+β β β’ Handles fail-open/fail-closed modes β β
+β β β’ Emits telemetry events β β
+β β β’ Manages retries and timeouts β β
+β ββββββββββββββββββββββββββββββββββββββββββββββββββββ¬βββββββββββββββββββ β
+β β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββ
+ β
+ βΌ
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β PREDICATE AUTHORITY SIDECAR (Rust) β
+β β
+β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββββββββ β
+β β Policy Engine β β Decision β β Audit Log β β
+β β βββββββββββββ β β Evaluator β β βββββββββββββββββββββ β β
+β β β ALLOW β β β β β β β’ Decision ID β β β
+β β β rules β β β principal + β β β β’ Timestamp β β β
+β β βββββββββββββ€ βββββΆβ action + βββββΆβ β β’ Action/Resource β β β
+β β β DENY β β β resource β β β β’ Outcome β β β
+β β β rules β β β = ALLOW/DENY β β β β’ Mandate ID β β β
+β β βββββββββββββ β β β β βββββββββββββββββββββ β β
+β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββββββββ β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+## Request Flow
+
+```
+ββββββββββββ βββββββββββββ ββββββββββββββ ββββββββββββ ββββββββββββ
+β Agent β β SecureClawβ β predicate- β β Sidecar β β Tool β
+β Request β β Plugin β β claw SDK β β (Rust) β β Executionβ
+ββββββ¬ββββββ βββββββ¬ββββββ βββββββ¬βββββββ ββββββ¬ββββββ ββββββ¬ββββββ
+ β β β β β
+ β Tool Call β β β β
+ β (Read /etc/ β β β β
+ β passwd) β β β β
+ ββββββββββββββββββΆβ β β β
+ β β β β β
+ β β Extract: β β β
+ β β action=fs.read β β β
+ β β resource= β β β
+ β β /etc/passwd β β β
+ β βββββββββββββββββββΆ β β
+ β β β β β
+ β β β POST /authorizeβ β
+ β β β {principal, β β
+ β β β action, β β
+ β β β resource} β β
+ β β ββββββββββββββββββΆβ β
+ β β β β β
+ β β β β Evaluate β
+ β β β β Policies β
+ β β β β βββββββββ β
+ β β β β β β
+ β β β ββββββββββββ β
+ β β β β β
+ β β β DENY: β β
+ β β β sensitive_file β β
+ β β βββββββββββββββββββ β
+ β β β β β
+ β β ActionDenied β β β
+ β β Error β β β
+ β βββββββββββββββββββ β β
+ β β β β β
+ β BLOCKED: β β β β
+ β Action blocked β β β β
+ β sensitive_file β β β β
+ βββββββββββββββββββ β β β
+ β β β β β
+ β β β β Tool NOTβ
+ β β β β Executedβ
+ β β β β β
+```
+
+## OpenClaw vs SecureClaw Security Comparison
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β OPENCLAW (Original) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββ β
+β β Agent ββββββββββΆβ Tool ββββββββββΆβ System Resource β β
+β β (LLM) β Direct β Execution β Direct β (Files, Network, β β
+β β β Access β β Access β Shell, etc.) β β
+β βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββ β
+β β
+β β οΈ NO AUTHORIZATION GATE β
+β β οΈ Agent has direct access to all tools β
+β β οΈ No policy enforcement β
+β β οΈ No audit trail β
+β β οΈ Relies on LLM's judgment for safety β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+ vs
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β SECURECLAW (Enhanced) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ β
+β β Agent βββββΆβ SecureClaw βββββΆβ Predicate βββββΆβ System β β
+β β (LLM) β β Plugin β β Authority β β Resource β β
+β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ β
+β β β β
+β β β β
+β ββββββββΌβββββββ ββββββββΌβββββββ β
+β β BLOCKED β β ALLOW β β
+β β if denied β β with β β
+β β β β mandate β β
+β βββββββββββββββ βββββββββββββββ β
+β β
+β β
Zero-trust authorization gate β
+β β
Policy-based access control β
+β β
Immutable audit trail β
+β β
Fail-closed mode for critical environments β
+β β
LLM cannot bypass security policies β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+## Security Features Comparison
+
+| Feature | OpenClaw | SecureClaw |
+| ------------------------- | ---------------- | ------------------------- |
+| Tool execution | Direct | Policy-gated |
+| Authorization | None | Pre-execution check |
+| Policy engine | None | Predicate Authority |
+| Audit logging | Limited | Full decision trail |
+| Fail mode | N/A | Fail-open or fail-closed |
+| Sensitive file protection | User prompt only | Policy-enforced block |
+| Shell command filtering | None | Policy-based allow/deny |
+| Network request control | None | URL/domain policies |
+| Multi-tenant support | None | Principal-based isolation |
+
+## Policy Example
+
+```json
+{
+ "policies": [
+ {
+ "id": "block-sensitive-files",
+ "effect": "DENY",
+ "actions": ["fs.read", "fs.write"],
+ "resources": ["/etc/passwd", "/etc/shadow", "**/.ssh/**", "**/.env", "**/credentials*"],
+ "reason": "Sensitive system files are blocked"
+ },
+ {
+ "id": "allow-project-files",
+ "effect": "ALLOW",
+ "actions": ["fs.read", "fs.write"],
+ "resources": ["/home/*/projects/**"],
+ "principals": ["agent:claude-code"]
+ },
+ {
+ "id": "block-dangerous-commands",
+ "effect": "DENY",
+ "actions": ["shell.exec"],
+ "resources": ["rm -rf /*", "sudo *", "chmod 777 *", "curl * | bash"],
+ "reason": "Dangerous shell commands are blocked"
+ }
+ ]
+}
+```
+
+## Component Summary
+
+| Component | Role | Technology |
+| ------------------------------- | ----------------------------------------------- | -------------------- |
+| **SecureClaw Plugin** | Intercepts tool calls, extracts action/resource | TypeScript |
+| **predicate-claw SDK** | Client library for authorization requests | TypeScript |
+| **Predicate Authority Sidecar** | Policy evaluation, decision engine | Rust |
+| **Policy Store** | Defines allow/deny rules | JSON/YAML |
+| **Audit Log** | Records all authorization decisions | Tamper-proof storage |
+
+## Why SecureClaw is More Secure
+
+1. **Defense in Depth**: Even if an LLM is jailbroken or manipulated, the external policy engine enforces security boundaries.
+
+2. **Least Privilege**: Policies can restrict agents to only the resources they need, following the principle of least privilege.
+
+3. **Audit Trail**: Every authorization decision is logged with timestamp, action, resource, and outcome for compliance and forensics.
+
+4. **Fail-Closed Mode**: In high-security environments, if the sidecar is unavailable, all tool calls are blocked rather than allowed.
+
+5. **Separation of Concerns**: Security policy enforcement is decoupled from the AI agent, preventing prompt injection from bypassing security.
+
+6. **Multi-Tenant Isolation**: Different principals (agents, users, tenants) can have different permission sets.
+
+## Getting Started
+
+```bash
+# Install SecureClaw
+npm install secureclaw
+
+# Start the Predicate Authority sidecar
+predicate-authorityd --config policy.json
+
+# Configure SecureClaw plugin
+export SECURECLAW_SIDECAR_URL=http://localhost:8787
+export SECURECLAW_FAIL_CLOSED=true
+```
+
+See the [SecureClaw Plugin documentation](./secureclaw-plugin.md) for detailed configuration options.