@clawdreyhepburn/carapace 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdreyhepburn/carapace",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Cedar policy enforcement for agent tool access via OpenClaw's before_tool_call hook.",
   "license": "Apache-2.0",
   "type": "module",

package/policies/00-schema.cedar

@@ -0,0 +1,30 @@
+// 00-schema.cedar — Cedar schema declaration for Carapace deployment
+//
+// This is NOT a policy. It declares the entity types, actions, and
+// context shapes that the policies in this directory reference.
+//
+// Carapace uses the Jans:: namespace by default
+// (see cedar-engine-cedarling.ts: `namespace ?? "Jans"`).
+//
+// Entity types:
+//   - Workload: the principal making the request (the agent / sub-agent)
+//   - Shell:    a shell binary, e.g. Jans::Shell::"rm"
+//   - Tool:     an MCP tool, e.g. Jans::Tool::"filesystem/write_file"
+//   - API:      an external API by hostname, e.g. Jans::API::"api.github.com"
+//
+// Actions:
+//   - exec_command: applies to Shell resources
+//   - call_tool:    applies to Tool resources
+//   - call_api:     applies to API resources
+//
+// Context fields (optional, populated by Carapace at evaluation time):
+//   - args:   string — the full argv joined for shell/tool calls
+//   - method: string — HTTP method for API calls (GET, POST, etc.)
+//   - path:   string — URL path for API calls
+
+// NOTE: Cedar's schema is declared in a separate JSON or .cedarschema file
+// in some deployments. Carapace synthesizes its schema at runtime in
+// cedar-engine-cedarling.ts. This file is human-readable documentation
+// of what that synthesized schema looks like; the real schema is built
+// in code. We keep this file as 00-schema.cedar so policy authors can
+// see the shape without digging into TypeScript.

package/policies/10-shell-deny.cedar

@@ -0,0 +1,51 @@
+// 10-shell-deny.cedar — Hard-deny shell binaries that are dangerous on this Mac mini.
+//
+// In Cedar, forbid wins over permit. These run unconditionally for any principal,
+// so even if a future permit rule matches, these still deny.
+//
+// Categories:
+//   1. Destructive filesystem ops    — rm, rmdir, dd, mkfs, format, diskutil
+//   2. Privilege escalation          — sudo, su, launchctl, systemctl
+//   3. Permission/ownership change   — chmod, chown, chgrp
+//   4. Credential access             — security, ssh-keygen, gpg, op, pass
+//   5. Shell wrappers (bypass risk)  — bash, sh, zsh, env, xargs
+//   6. Network recon                 — nmap, tcpdump, netcat, nc
+
+// --- 1. Destructive filesystem ---
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"rm");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"rmdir");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"dd");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"mkfs");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"format");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"diskutil");
+
+// --- 2. Privilege escalation ---
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"sudo");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"su");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"launchctl");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"systemctl");
+
+// --- 3. Permission / ownership ---
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"chmod");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"chown");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"chgrp");
+
+// --- 4. Credential access ---
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"security");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"ssh-keygen");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"gpg");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"op");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"pass");
+
+// --- 5. Shell wrappers (close the bypass) ---
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"bash");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"sh");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"zsh");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"env");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"xargs");
+
+// --- 6. Network recon ---
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"nmap");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"tcpdump");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"netcat");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"nc");

package/policies/20-shell-permit.cedar

@@ -0,0 +1,60 @@
+// 20-shell-permit.cedar — Allowlist of safe shell binaries for this workload.
+//
+// Carapace evaluates with default-deny. Without a matching `permit`, every shell
+// call is denied. These are the binaries the Clawdrey deployment actually needs.
+//
+// We restrict to `principal is Jans::Workload` so only properly-typed agents
+// can use these — humans calling shell directly bypass Carapace entirely.
+
+// --- Read-only inspection ---
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"cat");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"ls");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"grep");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"find");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"head");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"tail");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"wc");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"file");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"stat");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"which");
+
+// --- Filesystem operations (non-destructive) ---
+// Note: rm is forbidden in 10-shell-deny.cedar. Use `trash` instead — recoverable.
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"mkdir");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"cp");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"mv");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"trash");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"touch");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"ln");
+
+// --- Dev tools ---
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"git");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"node");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"npm");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"npx");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"python3");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"pip3");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"cargo");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"rustc");
+
+// --- macOS-specific helpers Clawdrey actually uses ---
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"osascript");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"pbcopy");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"pbpaste");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"open");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"SwitchAudioSource");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"cliclick");
+
+// --- Skills CLI tools (himalaya, gog, imsg, gh, jq, rg, ffmpeg, sox) ---
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"himalaya");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"gog");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"imsg");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"gh");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"jq");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"rg");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"ffmpeg");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"ffprobe");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"sox");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"whisper");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"curl");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"wget");

package/policies/30-shell-path-guards.cedar

@@ -0,0 +1,86 @@
+// 30-shell-path-guards.cedar — Conditional denies based on path arguments.
+//
+// These run AFTER 20-shell-permit.cedar in evaluation. Cedar's "forbid wins"
+// semantics means a permit + a matching forbid still results in deny.
+//
+// Pattern: even when an otherwise-permitted shell binary is invoked, we
+// forbid it if its arguments touch sensitive paths.
+//
+// `context.args` is set by Carapace at evaluation time (see cedar-engine
+// for how args are flattened into a single string for `like` matching).
+
+// --- Block reads of sensitive credential / config paths ---
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"cat"
+) when {
+  context has args &&
+  (context.args like "*/.ssh/*" ||
+   context.args like "*/.aws/*" ||
+   context.args like "*/.env*" ||
+   context.args like "*/.gnupg/*" ||
+   context.args like "*/.openclaw/credentials/*" ||
+   context.args like "*/.config/openclaw/*" ||
+   context.args like "*id_rsa*" ||
+   context.args like "*id_ed25519*")
+};
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"head"
+) when {
+  context has args &&
+  (context.args like "*/.ssh/*" ||
+   context.args like "*/.aws/*" ||
+   context.args like "*/.openclaw/credentials/*")
+};
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"tail"
+) when {
+  context has args &&
+  (context.args like "*/.ssh/*" ||
+   context.args like "*/.aws/*" ||
+   context.args like "*/.openclaw/credentials/*")
+};
+
+// --- Block writes/copies/moves into protected directories ---
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"cp"
+) when {
+  context has args &&
+  (context.args like "*/.ssh/*" ||
+   context.args like "*/.aws/*" ||
+   context.args like "*/.openclaw/credentials/*" ||
+   context.args like "*/etc/*")
+};
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"mv"
+) when {
+  context has args &&
+  (context.args like "*/.ssh/*" ||
+   context.args like "*/.aws/*" ||
+   context.args like "*/.openclaw/credentials/*" ||
+   context.args like "*/etc/*")
+};
+
+// --- Block git config writes that could change SSH/credential paths ---
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"git"
+) when {
+  context has args &&
+  context.args like "*config*" &&
+  (context.args like "*credential.helper*" ||
+   context.args like "*core.sshCommand*")
+};

package/policies/40-api-policy.cedar

@@ -0,0 +1,70 @@
+// 40-api-policy.cedar — Outbound HTTP/API gating.
+//
+// Carapace identifies APIs by hostname (Jans::API::"host.name") and
+// gates them under Jans::Action::"call_api". Optional context.method
+// can scope a permit to read-only verbs (GET/HEAD).
+
+// --- Hard denies: known data exfiltration / paste services ---
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"pastebin.com");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"hastebin.com");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"transfer.sh");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"file.io");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"webhook.site");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"requestbin.com");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"ngrok.io");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"pipedream.net");
+
+// --- Hard denies: localhost / loopback (prevent SSRF / side-channel exfil) ---
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"127.0.0.1");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"0.0.0.0");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"localhost");
+
+// --- Permit: developer / package registries (full access) ---
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"api.github.com");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"github.com");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"raw.githubusercontent.com");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"registry.npmjs.org");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"pypi.org");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"crates.io");
+
+// --- Permit: model providers (Clawdrey's own brain APIs) ---
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"api.anthropic.com");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"api.openai.com");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"api.elevenlabs.io");
+
+// --- Permit: read-only access to general web (GET/HEAD only) ---
+// Specific safe documentation and reference sources we use a lot.
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"docs.openclaw.ai"
+) when {
+  context has method && (context.method == "GET" || context.method == "HEAD")
+};
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"learn.microsoft.com"
+) when {
+  context has method && (context.method == "GET" || context.method == "HEAD")
+};
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"developer.mozilla.org"
+) when {
+  context has method && (context.method == "GET" || context.method == "HEAD")
+};
+
+// --- Permit: own infrastructure ---
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"clawdrey.com");
+
+// --- Notes ---
+// Posting to social platforms (api.x.com, api.linkedin.com, discord.com, slack.com)
+// is intentionally not permit'd here — it must go through curated paths
+// (e.g. ~/.openclaw/workspace/scripts/x-api.py for X) that have their own
+// review surface. If you need to permit one of those for a specific scenario,
+// add a focused permit policy with `principal is` constrained to a labeled
+// agent type, not the broad Workload.

package/policies/50-tool-policy.cedar

@@ -0,0 +1,38 @@
+// 50-tool-policy.cedar — MCP tool gating.
+//
+// Carapace identifies MCP tools by qualified name (Jans::Tool::"server/tool")
+// and gates them under Jans::Action::"call_tool".
+//
+// Strategy here: deny the destructive shapes explicitly, then permit
+// everything else for properly-typed Workload principals. This is the
+// inverse posture from shell (which is allowlist-only) because MCP tool
+// surfaces vary widely between deployments and we don't want every
+// new MCP server to require a policy update.
+
+// --- Hard denies: bulk-destructive tool patterns ---
+// Destructive filesystem
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"filesystem/delete_file");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"filesystem/delete_directory");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"filesystem/move_file");
+
+// Mass email destruction / spam
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"email/delete_all");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"email/empty_trash");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"email/send_bulk");
+
+// Database destruction / drift
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"database/drop_table");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"database/truncate");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"database/execute_sql");
+
+// Cloud destruction
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"aws/delete_bucket");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"aws/terminate_instance");
+forbid(principal, action == Jans::Action::"call_tool", resource == Jans::Tool::"gcp/delete_project");
+
+// --- Default-permit: any other MCP tool for properly-typed Workloads ---
+// This is the catch-all. For Carapace's posture today (additive, not
+// strict allowlist), permitting all `call_tool` for Workloads keeps
+// daily flow unblocked while the explicit `forbid`s above carve out
+// the dangerous shapes.
+permit(principal is Jans::Workload, action == Jans::Action::"call_tool", resource);

package/policies/schema.json

@@ -0,0 +1,88 @@
+{
+  "Jans": {
+    "entityTypes": {
+      "Workload": {
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "name": { "type": "EntityOrCommon", "name": "String", "required": false }
+          }
+        }
+      },
+      "Agent": {
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "role": { "type": "EntityOrCommon", "name": "String", "required": false }
+          }
+        }
+      },
+      "Shell": {
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "command": { "type": "EntityOrCommon", "name": "String", "required": false },
+            "workdir": { "type": "EntityOrCommon", "name": "String", "required": false }
+          }
+        }
+      },
+      "Tool": {
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "server": { "type": "EntityOrCommon", "name": "String", "required": false },
+            "name": { "type": "EntityOrCommon", "name": "String", "required": false }
+          }
+        }
+      },
+      "API": {
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "host": { "type": "EntityOrCommon", "name": "String", "required": false }
+          }
+        }
+      }
+    },
+    "actions": {
+      "exec_command": {
+        "appliesTo": {
+          "principalTypes": ["Workload", "Agent"],
+          "resourceTypes": ["Shell"],
+          "context": {
+            "type": "Record",
+            "attributes": {
+              "args": { "type": "EntityOrCommon", "name": "String", "required": false },
+              "workdir": { "type": "EntityOrCommon", "name": "String", "required": false }
+            }
+          }
+        }
+      },
+      "call_tool": {
+        "appliesTo": {
+          "principalTypes": ["Workload", "Agent"],
+          "resourceTypes": ["Tool"],
+          "context": {
+            "type": "Record",
+            "attributes": {
+              "args": { "type": "EntityOrCommon", "name": "String", "required": false }
+            }
+          }
+        }
+      },
+      "call_api": {
+        "appliesTo": {
+          "principalTypes": ["Workload", "Agent"],
+          "resourceTypes": ["API"],
+          "context": {
+            "type": "Record",
+            "attributes": {
+              "method": { "type": "EntityOrCommon", "name": "String", "required": false },
+              "path": { "type": "EntityOrCommon", "name": "String", "required": false }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/index.ts

@@ -5,6 +5,9 @@
  * No proxy, no baseUrl redirect, no models.json patching.
  */
 
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { CedarlingEngine } from "./cedar-engine-cedarling.js";
 import { McpAggregator } from "./mcp-aggregator.js";
 import { ControlGui } from "./gui/server.js";
@@ -13,6 +16,18 @@ import type { PluginConfig } from "./types.js";
 export const id = "carapace";
 export const name = "Carapace";
 
+/**
+ * Resolve the OpenClaw home directory the same way the runtime does:
+ * honor $OPENCLAW_HOME when set, otherwise fall back to ~/.openclaw.
+ * Used by the audit log and the setup/uninstall CLI so they never
+ * read/write the wrong config for users with a custom OPENCLAW_HOME.
+ */
+function openclawHome(): string {
+  const override = process.env.OPENCLAW_HOME;
+  if (override && override.trim() !== "") return override;
+  return join(homedir(), ".openclaw");
+}
+
 /**
  * OpenClaw plugin API shape (matches real runtime).
  */
@@ -36,6 +51,14 @@ interface OpenClawPluginApi {
     opts?: { optional?: boolean },
   ): void;
   registerHook?(hookName: string | string[], handler: (event: any) => Promise<any> | any, opts?: { name: string; description?: string; priority?: number }): void;
+  /**
+   * Typed hook registration. Exposed by the real OpenClaw runtime in full
+   * registration mode (see loader `registerTypedHook`). This is the API this
+   * plugin actually uses to install the `before_tool_call` hook — declared
+   * optional here because some test harnesses construct a stripped-down api
+   * shim without it.
+   */
+  on?(hookName: string, handler: (event: any, ctx?: any) => Promise<any> | any, opts?: { name?: string; description?: string; priority?: number }): void;
   registerCli?(fn: (ctx: { program: any }) => void, opts?: { commands: string[] }): void;
   registerGatewayMethod?(name: string, handler: (ctx: { respond: (ok: boolean, data: any) => void }) => void): void;
 }
@@ -64,10 +87,7 @@ function buildUpstreamConfig(proxyConfig: NonNullable<PluginConfig["proxy"]>): {
 // Audit log
 function appendAuditLog(entry: { timestamp: string; tool: string; decision: string; reasons: string[]; params?: any }): void {
   try {
-    const { appendFileSync, mkdirSync } = require("node:fs");
-    const { join } = require("node:path");
-    const { homedir } = require("node:os");
-    const logDir = join(homedir(), ".openclaw", "mcp-policies", "logs");
+    const logDir = join(openclawHome(), "mcp-policies", "logs");
     mkdirSync(logDir, { recursive: true });
     appendFileSync(join(logDir, "audit.log"), JSON.stringify(entry) + "\n", "utf-8");
   } catch {}
@@ -442,13 +462,9 @@ export default function register(api: OpenClawPluginApi) {
       cmd.command("setup")
         .description("Enable Carapace plugin in OpenClaw config")
         .action(async () => {
-          const { readFileSync, writeFileSync, existsSync } = require("node:fs");
-          const { join } = require("node:path");
-          const { homedir } = require("node:os");
-
           console.log("\n🦞 Carapace Setup\n");
 
-          const configPath = join(homedir(), ".openclaw", "openclaw.json");
+          const configPath = join(openclawHome(), "openclaw.json");
           let cfg: any = {};
           if (existsSync(configPath)) {
             cfg = JSON.parse(readFileSync(configPath, "utf-8"));
@@ -483,13 +499,9 @@ export default function register(api: OpenClawPluginApi) {
       cmd.command("uninstall")
         .description("Disable Carapace plugin")
         .action(async () => {
-          const { readFileSync, writeFileSync, existsSync } = require("node:fs");
-          const { join } = require("node:path");
-          const { homedir } = require("node:os");
-
           console.log("\n🦞 Carapace Uninstall\n");
 
-          const configPath = join(homedir(), ".openclaw", "openclaw.json");
+          const configPath = join(openclawHome(), "openclaw.json");
           if (!existsSync(configPath)) {
             console.log("  No config file found. Nothing to undo.\n");
             return;

package/src/llm-proxy.ts

@@ -63,6 +63,9 @@ export class LlmProxy {
     toolCallsDenied: 0,
   };
 
+  // In-memory audit log
+  private auditLog: Array<{ tool: string; decision: "allow" | "deny"; timestamp: string }> = [];
+
   constructor(opts: LlmProxyOpts) {
     this.port = opts.port;
     this.upstream = opts.upstream;
@@ -70,6 +73,10 @@ export class LlmProxy {
     this.logger = opts.logger;
   }
 
+  getAuditLog() {
+    return [...this.auditLog];
+  }
+
   async start(): Promise<void> {
     this.server = createServer(async (req, res) => {
       try {
@@ -600,6 +607,12 @@ export class LlmProxy {
       this.stats.toolCallsDenied++;
     }
 
+    this.auditLog.push({
+      tool: toolName,
+      decision: decision.decision,
+      timestamp: new Date().toISOString(),
+    });
+
     return decision.decision;
   }
 

package/src/policy-source.ts

@@ -41,4 +41,26 @@ export class CarapacePolicySource implements PolicySource {
     const policies = files.map(f => readFileSync(join(this.policyDir, f), "utf-8"));
     return policies.join("\n\n");
   }
+
+  /**
+   * Load Carapace's Cedar schema JSON from the policy directory.
+   *
+   * OVID-ME's WASM engine needs this to evaluate Carapace policies
+   * faithfully (entity types like `Shell`, `Tool`, `API`, action
+   * definitions). Pass the returned object to
+   * `evaluateMandateAsync(..., { externalSchema })` or
+   * `evaluateWithWasm(..., { externalSchema })`.
+   *
+   * Returns null when no schema.json is present; in that case OVID-ME
+   * falls back to its synthesized Agent + Resource schema.
+   */
+  async getSchema(): Promise<Record<string, any> | null> {
+    const schemaPath = join(this.policyDir, "schema.json");
+    if (!existsSync(schemaPath)) return null;
+    try {
+      return JSON.parse(readFileSync(schemaPath, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
 }