multicorn-shield 0.1.10 → 0.1.13

package/README.md

@@ -10,6 +10,12 @@ The permissions and control layer for AI agents. Open source.
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/multicorn-shield)](https://bundlephobia.com/package/multicorn-shield)
 
+## Demo
+
+<p align="center">
+  <img src="https://multicorn.ai/images/demo.gif" alt="Multicorn Shield demo: agent blocked, user approves in dashboard, agent proceeds" width="800" />
+</p>
+
 ## Why?
 
 AI agents are getting access to your email, calendar, bank accounts, and code repositories. Today, most agents operate with no permission boundaries: they can read, write, and spend with no oversight. Multicorn Shield gives developers a single SDK to enforce what agents can do, track what they did, and let users stay in control.
@@ -48,7 +54,79 @@ That's it. Every tool call now goes through Shield's permission layer, and activ
 
 See the [full MCP proxy guide](https://multicorn.ai/docs/mcp-proxy) for Claude Code, OpenClaw, and generic MCP client examples.
 
-### Option 2: Integrate the SDK
+### Option 2: OpenClaw Plugin (native integration)
+
+If you're running [OpenClaw](https://openclaw.ai), Shield integrates directly as a plugin. No proxy layer, no code changes. The plugin intercepts every tool call at the infrastructure level before it executes.
+
+**Step 1: Install and configure**
+
+```bash
+npm install -g multicorn-shield
+npx multicorn-proxy init
+```
+
+Enter your API key when prompted. This saves your key to `~/.multicorn/config.json` and configures the OpenClaw hook environment.
+
+**Step 2: Build the plugin**
+
+```bash
+cd $(npm root -g)/multicorn-shield
+npm run build
+```
+
+**Step 3: Register with OpenClaw**
+
+Add the plugin path to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": ["<npm-root>/multicorn-shield/dist/openclaw-plugin/index.js"]
+    },
+    "entries": {
+      "multicorn-shield": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+Replace `<npm-root>` with the output of `npm root -g`.
+
+**Step 4: Restart and verify**
+
+```bash
+openclaw gateway restart
+openclaw plugins list
+```
+
+You should see `multicorn-shield` in the loaded plugins list.
+
+**How it works**
+
+1. Agent tries to use a tool (read files, run commands, send emails)
+2. Shield intercepts via `before_tool_call` and checks permissions
+3. First time: A consent screen opens in your browser so you can authorize the agent
+4. Authorized actions: Proceed immediately
+5. New or elevated actions: Blocked with a link to the dashboard where you approve or reject
+6. Everything is logged to your Multicorn dashboard
+
+The plugin maps OpenClaw tools to Shield permission scopes automatically:
+
+| OpenClaw Tool       | Shield Scope     |
+| ------------------- | ---------------- |
+| read                | filesystem:read  |
+| write, edit         | filesystem:write |
+| exec                | terminal:execute |
+| exec (rm, mv, sudo) | terminal:write   |
+| browser             | browser:execute  |
+| message             | messaging:write  |
+
+Destructive commands (rm, mv, sudo, chmod) are detected automatically and require separate write-level approval.
+
+### Option 3: Integrate the SDK
 
 For full control over consent screens, spending limits, and action logging, use the SDK directly in your application code.
 

package/dist/multicorn-proxy.js

@@ -704,6 +704,9 @@ async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
   return scopes;
 }
 function openBrowser(url) {
+  if (process.env["NODE_ENV"] === "test" || process.env["VITEST"] === "true") {
+    return;
+  }
   const platform = process.platform;
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();

package/dist/openclaw-hook/handler.js

@@ -273,6 +273,16 @@ var POLL_INTERVAL_MS2 = 3e3;
 var POLL_TIMEOUT_MS2 = 5 * 60 * 1e3;
 function deriveDashboardUrl(baseUrl) {
   try {
+    const envBase = process.env["MULTICORN_BASE_URL"];
+    if (typeof envBase === "string" && envBase.trim().length > 0) {
+      const trimmed = envBase.trim();
+      if (trimmed.includes("localhost") || trimmed.includes("127.0.0.1")) {
+        baseUrl = /^https?:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
+      }
+    }
+    if (!/^https?:\/\//i.test(baseUrl) && (baseUrl.includes("localhost") || baseUrl.includes("127.0.0.1"))) {
+      baseUrl = `http://${baseUrl}`;
+    }
     const url = new URL(baseUrl);
     if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
       url.port = "5173";
@@ -301,6 +311,9 @@ function buildConsentUrl(agentName, dashboardUrl, scope) {
   return `${base}/consent?${params.toString()}`;
 }
 function openBrowser(url) {
+  if (process.env["NODE_ENV"] === "test" || process.env["VITEST"] === "true") {
+    return;
+  }
   const platform = process.platform;
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   try {
@@ -315,6 +328,7 @@ ${url}
 }
 async function waitForConsent(agentId, agentName, apiKey, baseUrl, scope, logger) {
   const dashboardUrl = deriveDashboardUrl(baseUrl);
+  console.error("[SHIELD] buildConsentUrl baseUrl:", baseUrl);
   const consentUrl = buildConsentUrl(agentName, dashboardUrl, scope);
   process.stderr.write(
     `[multicorn-shield] Opening consent page...

package/dist/openclaw-plugin/index.js

@@ -335,6 +335,16 @@ var POLL_INTERVAL_MS2 = 3e3;
 var POLL_TIMEOUT_MS2 = 5 * 60 * 1e3;
 function deriveDashboardUrl(baseUrl) {
   try {
+    const envBase = process.env["MULTICORN_BASE_URL"];
+    if (typeof envBase === "string" && envBase.trim().length > 0) {
+      const trimmed = envBase.trim();
+      if (trimmed.includes("localhost") || trimmed.includes("127.0.0.1")) {
+        baseUrl = /^https?:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
+      }
+    }
+    if (!/^https?:\/\//i.test(baseUrl) && (baseUrl.includes("localhost") || baseUrl.includes("127.0.0.1"))) {
+      baseUrl = `http://${baseUrl}`;
+    }
     const url = new URL(baseUrl);
     if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
       url.port = "5173";
@@ -363,6 +373,9 @@ function buildConsentUrl(agentName, dashboardUrl, scope) {
   return `${base}/consent?${params.toString()}`;
 }
 function openBrowser(url) {
+  if (process.env["NODE_ENV"] === "test" || process.env["VITEST"] === "true") {
+    return;
+  }
   const platform = process.platform;
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   try {
@@ -377,6 +390,7 @@ ${url}
 }
 async function waitForConsent(agentId, agentName, apiKey, baseUrl, scope, logger) {
   const dashboardUrl = deriveDashboardUrl(baseUrl);
+  console.error("[SHIELD] buildConsentUrl baseUrl:", baseUrl);
   const consentUrl = buildConsentUrl(agentName, dashboardUrl, scope);
   process.stderr.write(
     `[multicorn-shield] Opening consent page...
@@ -703,6 +717,46 @@ async function beforeToolCall(event, ctx) {
     if (!hasScope(grantedScopes, requestedScope) && agentRecord !== null) {
       await ensureConsent(agentName, config.apiKey, config.baseUrl, mapping);
       console.error("[SHIELD] ensureConsent result: completed (blocked path)");
+      const scopes = await fetchGrantedScopes(
+        agentRecord.id,
+        config.apiKey,
+        config.baseUrl,
+        pluginLogger ?? void 0
+      );
+      grantedScopes = scopes;
+      lastScopeRefresh = Date.now();
+      if (Array.isArray(scopes) && scopes.length > 0) {
+        await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+        });
+      }
+      const recheckResult = await checkActionPermission(
+        {
+          agent: agentName,
+          service: mapping.service,
+          actionType,
+          status: "approved",
+          metadata: { description }
+        },
+        config.apiKey,
+        config.baseUrl,
+        pluginLogger ?? void 0
+      );
+      if (recheckResult.status === "approved") {
+        const refreshedScopes = await fetchGrantedScopes(
+          agentRecord.id,
+          config.apiKey,
+          config.baseUrl,
+          pluginLogger ?? void 0
+        );
+        grantedScopes = refreshedScopes;
+        lastScopeRefresh = Date.now();
+        if (Array.isArray(refreshedScopes) && refreshedScopes.length > 0) {
+          await saveCachedScopes(agentName, agentRecord.id, refreshedScopes).catch(() => {
+          });
+        }
+        console.error("[SHIELD] DECISION: allow (re-check after consent)");
+        return void 0;
+      }
     }
     const capitalizedService = mapping.service.charAt(0).toUpperCase() + mapping.service.slice(1);
     const dashboardUrl = deriveDashboardUrl(config.baseUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "type": "module",