@clawdreyhepburn/carapace 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.4.0] - 2026-03-23
+
+### Breaking Changes
+- Removed agent hierarchy (OvidToken registration, agent context injection)
+- Removed three-valued decisions (allow-proven/allow-unproven). All decisions are binary allow/deny.
+- Removed `src/agent-context.ts` and `src/attenuation.ts`
+
+### Added
+- `CarapacePolicySource` implementing PolicySource interface for OVID-ME integration
+- `/api/policy-source` endpoint on GUI server
+
+### Changed
+- Cedar evaluation simplified to binary allow/deny
+- LLM proxy no longer injects agent context into Cedar evaluation
+
+For per-agent mandate evaluation, see @clawdreyhepburn/ovid-me.
+
+## [0.3.2] - 2026-03-19
+- Agent hierarchy, three-valued decisions, OVID integration (now removed)

package/README.md

@@ -2,12 +2,13 @@
   <h1 align="center">🦞 Carapace</h1>
   <p align="center"><strong>Your agent's exoskeleton.</strong></p>
   <p align="center">
-    Controls what your AI agent can do — which tools it can use, which commands it can run, and which websites it can talk to. If a policy says no, the agent can't do it.
+    The deployment-level policy ceiling for AI agents. Controls which tools, commands, and APIs your agent can access. Simple allow/deny Cedar evaluation — if a policy says no, it's no. For per-agent mandate evaluation, see <a href="https://github.com/clawdreyhepburn/ovid-me">@clawdreyhepburn/ovid-me</a>.
   </p>
   <p align="center">
     <a href="#how-it-works">How It Works</a> •
     <a href="#installation">Installation</a> •
     <a href="#quick-start">Quick Start</a> •
+    <a href="#policy-source">Policy Source</a> •
     <a href="docs/SECURITY.md">Security Guide</a> •
     <a href="docs/RECOMMENDED-POLICIES.md">Recommended Policies</a> •
     <a href="#the-control-gui">Control GUI</a> •
@@ -17,6 +18,10 @@
 
 ---
 
+<p align="center">
+  <img src="docs/carapace_proxy_tool_filter_flow_v3.svg" alt="Carapace proxy filtering tool calls" width="700">
+</p>
+
 ## What is Carapace?
 
 AI agents can do a lot. They can read and write files, run shell commands, call APIs, send emails, push code — anything you give them access to. That's powerful, but it's also dangerous. An agent that can delete files can delete *all* files. An agent that can call APIs can send your data anywhere.
@@ -335,6 +340,33 @@ forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"pa
 
 ---
 
+## Policy Source
+
+Carapace is the **deployment-level policy ceiling** — it defines the maximum set of permissions any agent can have. For per-agent mandate evaluation (task-specific Cedar policy sets, delegation chains, subset proofs), see [`@clawdreyhepburn/ovid-me`](https://github.com/clawdreyhepburn/ovid-me).
+
+### How OVID-ME queries Carapace
+
+OVID-ME needs to know the deployment's effective Cedar policies to verify that a sub-agent's mandate is a subset of what the deployment allows. Carapace exposes this via the `PolicySource` interface:
+
+```typescript
+import { CarapacePolicySource } from '@clawdreyhepburn/carapace';
+
+const policySource = new CarapacePolicySource('~/.openclaw/mcp-policies/');
+const policies = await policySource.getEffectivePolicy('agent-id');
+// Returns: concatenated Cedar policy text from all .cedar files
+```
+
+The GUI also exposes an HTTP endpoint:
+
+```
+GET http://localhost:19820/api/policy-source?principal=<id>
+→ Returns Cedar policy text (text/plain)
+```
+
+Carapace policies are deployment-wide — the same policies apply to all principals. Principal-specific filtering happens in OVID-ME's mandate evaluation, not here.
+
+---
+
 ## Design Philosophy
 
 **Installing Carapace should never break your agent.** The default is `allow-all` — everything works exactly as before. You get visibility first (see what tools exist, what's being called) and control second (add restrictions when you're ready).
@@ -358,6 +390,7 @@ Most people should stay at step 3. Step 4 is for when you really understand your
 - **Prompt injection** — Someone tricks your agent into running dangerous commands. If the policy says `rm` is forbidden, it doesn't matter what the prompt says.
 - **Data exfiltration** — Your agent tries to send sensitive data to an external service. If the domain isn't permitted, the request is blocked.
 - **Privilege escalation** — An agent tries to use one permitted tool to accomplish what a forbidden tool would do. Cedar's forbid-always-wins makes this harder.
+- **Sub-agent over-privilege** — Carapace defines the deployment ceiling. For per-agent mandate enforcement, see [`@clawdreyhepburn/ovid-me`](https://github.com/clawdreyhepburn/ovid-me).
 
 ### What Carapace does NOT protect against
 
@@ -442,6 +475,7 @@ carapace/
 │   ├── cedar-engine-cedarling.ts # Cedarling WASM engine — real Cedar 4.4.2 evaluation
 │   ├── cedar-engine.ts           # Fallback engine (string matching, no WASM needed)
 │   ├── mcp-aggregator.ts         # Connects to MCP servers, discovers tools, proxies calls
+│   ├── policy-source.ts           # PolicySource for OVID-ME integration
 │   ├── types.ts                  # Shared TypeScript types
 │   └── gui/
 │       ├── server.ts             # HTTP server for the dashboard
@@ -482,6 +516,7 @@ More at [clawdrey.com](https://clawdrey.com).
 - **[Cedarling](https://github.com/JanssenProject/jans/tree/main/jans-cedarling)** — Cedar engine by [Gluu](https://gluu.org/), compiled to WebAssembly for speed.
 - **[MCP](https://modelcontextprotocol.io/)** — Open protocol for connecting AI agents to tools.
 - **[OpenClaw](https://github.com/openclaw/openclaw)** — Open-source AI agent platform.
+- **[OVID-ME](https://github.com/clawdreyhepburn/ovid-me)** — Per-agent mandate evaluation (uses Carapace as its policy source).
 
 ---
 

package/dist/cedar-engine-cedarling.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Cedarling-powered Cedar engine for MCP tool authorization.
+ *
+ * Uses Gluu's Cedarling WASM module for proper Cedar evaluation,
+ * JWT validation, and the Policy Store format. Falls back to the
+ * homebrew engine if WASM loading fails.
+ */
+import type { Logger, AuthzRequest, CedarDecision, VerifyResult, CedarSchemaInfo } from "./types.js";
+export interface CedarlingEngineOpts {
+    policyDir: string;
+    defaultPolicy: "deny-all" | "allow-all";
+    verify: boolean;
+    logger: Logger;
+    namespace?: string;
+    agentEntityType?: string;
+}
+export declare class CedarlingEngine {
+    private policyDir;
+    private defaultPolicy;
+    private shouldVerify;
+    private logger;
+    private namespace;
+    private agentEntityType;
+    private cedarling;
+    private wasmModule;
+    private policies;
+    private schemaJson;
+    private schemaRaw;
+    constructor(opts: CedarlingEngineOpts);
+    init(): Promise<void>;
+    /**
+     * Authorize a request using Cedarling WASM.
+     */
+    authorize(request: AuthzRequest): Promise<CedarDecision>;
+    /**
+     * Enable a resource by adding a permit policy and rebuilding Cedarling.
+     * resourceType: "Tool" | "Shell" | "API"
+     * action: the Cedar action name (e.g., "call_tool", "exec_command", "call_api")
+     */
+    enableResource(qualifiedName: string, resourceType?: string, action?: string): void;
+    /**
+     * Disable a resource by adding a forbid policy and rebuilding Cedarling.
+     */
+    disableResource(qualifiedName: string, resourceType?: string, action?: string): void;
+    /** Backwards-compatible aliases */
+    enableTool(qualifiedName: string): void;
+    disableTool(qualifiedName: string): void;
+    /**
+     * Check if a tool is enabled (synchronous check against local policy state).
+     * Checks both specific tool policies AND blanket policies (those without a specific tool name).
+     */
+    isToolEnabled(qualifiedName: string): boolean;
+    savePolicy(id: string, raw: string): void;
+    deletePolicy(id: string): boolean;
+    getDefaultPolicy(): "deny-all" | "allow-all";
+    getPolicies(): Array<{
+        id: string;
+        effect: string;
+        raw: string;
+    }>;
+    getSchema(): CedarSchemaInfo;
+    saveSchema(raw: string): void;
+    verify(): Promise<VerifyResult>;
+    private loadWasm;
+    /**
+     * Rebuild the Cedarling instance from current policies and schema.
+     * Called after any policy or schema change.
+     */
+    private rebuildCedarling;
+    /**
+     * Build a Cedarling Policy Store JSON from current policies and schema.
+     */
+    private buildPolicyStore;
+    private loadPoliciesFromDisk;
+    private writePolicyFile;
+    private removePolicyFile;
+    private writeDefaultSchema;
+    private buildDefaultSchemaJson;
+    private authorizeBasic;
+    private parseSchemaForGui;
+}