multicorn-shield 0.1.10 → 0.1.15

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.
 
@@ -77,6 +155,42 @@ await shield.logAction({
 
 That gives you a consent screen, scoped permissions, and an audit trail.
 
+## Dashboard
+
+Every action, approval, and permission is visible in real time at [app.multicorn.ai](https://app.multicorn.ai).
+
+**Sign up:** [https://app.multicorn.ai](https://app.multicorn.ai)
+
+With the dashboard you can:
+
+- See all agents and their activity
+- Approve or reject pending actions
+- Configure per-agent permissions (read/write/execute per service)
+- Set spending limits
+- View the full audit trail with hash-chain integrity
+
+The dashboard works with both the SDK integration and the MCP proxy. No extra setup needed.
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/overview-page.png" alt="Dashboard overview showing total actions, blocked count, spend, and live activity feed" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/approvals-card.png" alt="Approval card with one-tap approve/reject and permission duration options" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/activity-log-list.png" alt="Filterable activity log showing every agent action with status" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/consent-screen.png" alt="Consent screen where users grant agent permissions" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/agent-page-with-stats.png" alt="Agent detail page with action stats and budget tracking" width="800" />
+</p>
+
 ## Built with Shield
 
 Multicorn is developed using AI coding agents. Primarily Cursor for code generation and GitHub Actions as the deployment agent. Every one of those agents runs under Shield.

package/dist/multicorn-proxy.js

@@ -506,6 +506,9 @@ function dollarsToCents(dollars) {
 // src/proxy/interceptor.ts
 var BLOCKED_ERROR_CODE = -32e3;
 var SPENDING_BLOCKED_ERROR_CODE = -32001;
+var INTERNAL_ERROR_CODE = -32002;
+var SERVICE_UNREACHABLE_ERROR_CODE = -32003;
+var AUTH_ERROR_CODE = -32004;
 function parseJsonRpcLine(line) {
   const trimmed = line.trim();
   if (trimmed.length === 0) return null;
@@ -550,6 +553,39 @@ function buildSpendingBlockedResponse(id, reason, dashboardUrl) {
     }
   };
 }
+function buildInternalErrorResponse(id) {
+  const message = "Action blocked: Shield encountered an internal error and cannot verify permissions. Check proxy logs for details.";
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: INTERNAL_ERROR_CODE,
+      message
+    }
+  };
+}
+function buildServiceUnreachableResponse(id, dashboardUrl) {
+  const message = `Action blocked: Shield cannot verify permissions (service unreachable). Configure offline behaviour at ${dashboardUrl}`;
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: SERVICE_UNREACHABLE_ERROR_CODE,
+      message
+    }
+  };
+}
+function buildAuthErrorResponse(id) {
+  const message = "Action blocked: Shield API key is invalid or has been revoked. Run npx multicorn-proxy init to reconfigure.";
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: AUTH_ERROR_CODE,
+      message
+    }
+  };
+}
 function extractServiceFromToolName(toolName) {
   const idx = toolName.indexOf("_");
   return idx === -1 ? toolName : toolName.slice(0, idx);
@@ -600,6 +636,13 @@ function deriveDashboardUrl(baseUrl) {
     return "https://app.multicorn.ai";
   }
 }
+var ShieldAuthError = class _ShieldAuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ShieldAuthError";
+    Object.setPrototypeOf(this, _ShieldAuthError.prototype);
+  }
+};
 async function loadCachedScopes(agentName) {
   try {
     const raw = await readFile(SCOPES_PATH, "utf8");
@@ -643,8 +686,18 @@ async function findAgentByName(agentName, apiKey, baseUrl) {
   } catch {
     return null;
   }
-  if (!response.ok) return null;
-  const body = await response.json();
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      return { id: "", name: agentName, scopes: [], authInvalid: true };
+    }
+    return null;
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return null;
+  }
   if (!isApiSuccessResponse(body)) return null;
   const agents = body.data;
   if (!Array.isArray(agents)) return null;
@@ -665,6 +718,11 @@ async function registerAgent(agentName, apiKey, baseUrl) {
     signal: AbortSignal.timeout(8e3)
   });
   if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      throw new ShieldAuthError(
+        `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
+      );
+    }
     throw new Error(
       `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
     );
@@ -704,6 +762,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();
@@ -741,6 +802,9 @@ async function resolveAgentRecord(agentName, apiKey, baseUrl, logger) {
     return { id: "", name: agentName, scopes: cachedScopes };
   }
   let agent = await findAgentByName(agentName, apiKey, baseUrl);
+  if (agent?.authInvalid) {
+    return agent;
+  }
   if (agent === null) {
     try {
       logger.info("Agent not found. Registering.", { agent: agentName });
@@ -748,6 +812,9 @@ async function resolveAgentRecord(agentName, apiKey, baseUrl, logger) {
       agent = { id, name: agentName, scopes: [] };
       logger.info("Agent registered.", { agent: agentName, id });
     } catch (error) {
+      if (error instanceof ShieldAuthError) {
+        return { id: "", name: agentName, scopes: [], authInvalid: true };
+      }
       const detail = error instanceof Error ? error.message : String(error);
       logger.warn("Could not reach Multicorn service. Running with empty permissions.", {
         error: detail
@@ -812,6 +879,7 @@ function createProxyServer(config) {
   let spendingChecker = null;
   let grantedScopes = [];
   let agentId = "";
+  let authInvalid = false;
   let refreshTimer = null;
   let consentInProgress = false;
   const pendingLines = [];
@@ -864,40 +932,28 @@ function createProxyServer(config) {
     if (request.method !== "tools/call") return null;
     const toolParams = extractToolCallParams(request);
     if (toolParams === null) return null;
-    const service = extractServiceFromToolName(toolParams.name);
-    const action = extractActionFromToolName(toolParams.name);
-    const requestedScope = { service, permissionLevel: "execute" };
-    const validation = validateScopeAccess(grantedScopes, requestedScope);
-    config.logger.debug("Tool call intercepted.", {
-      tool: toolParams.name,
-      service,
-      allowed: validation.allowed
-    });
-    if (!validation.allowed) {
-      await ensureConsent(requestedScope);
-      const revalidation = validateScopeAccess(grantedScopes, requestedScope);
-      if (!revalidation.allowed) {
-        if (actionLogger !== null) {
-          if (!config.agentName || config.agentName.trim().length === 0) {
-            process.stderr.write("[multicorn-proxy] Cannot log action: agent name not resolved\n");
-          } else {
-            await actionLogger.logAction({
-              agent: config.agentName,
-              service,
-              actionType: action,
-              status: "blocked"
-            });
-          }
-        }
-        const blocked = buildBlockedResponse(request.id, service, "execute", config.dashboardUrl);
+    try {
+      if (authInvalid) {
+        const blocked = buildAuthErrorResponse(request.id);
         return JSON.stringify(blocked);
       }
-    }
-    if (spendingChecker !== null) {
-      const costCents = extractCostCents(toolParams.arguments);
-      if (costCents > 0) {
-        const spendResult = spendingChecker.checkSpend(costCents);
-        if (!spendResult.allowed) {
+      if (agentId.length === 0) {
+        const blocked = buildServiceUnreachableResponse(request.id, config.dashboardUrl);
+        return JSON.stringify(blocked);
+      }
+      const service = extractServiceFromToolName(toolParams.name);
+      const action = extractActionFromToolName(toolParams.name);
+      const requestedScope = { service, permissionLevel: "execute" };
+      const validation = validateScopeAccess(grantedScopes, requestedScope);
+      config.logger.debug("Tool call intercepted.", {
+        tool: toolParams.name,
+        service,
+        allowed: validation.allowed
+      });
+      if (!validation.allowed) {
+        await ensureConsent(requestedScope);
+        const revalidation = validateScopeAccess(grantedScopes, requestedScope);
+        if (!revalidation.allowed) {
           if (actionLogger !== null) {
             if (!config.agentName || config.agentName.trim().length === 0) {
               process.stderr.write(
@@ -912,29 +968,60 @@ function createProxyServer(config) {
               });
             }
           }
-          const blocked = buildSpendingBlockedResponse(
-            request.id,
-            spendResult.reason ?? "spending limit exceeded",
-            config.dashboardUrl
+          return JSON.stringify(
+            buildBlockedResponse(request.id, service, "execute", config.dashboardUrl)
           );
-          return JSON.stringify(blocked);
         }
-        spendingChecker.recordSpend(costCents);
       }
-    }
-    if (actionLogger !== null) {
-      if (!config.agentName || config.agentName.trim().length === 0) {
-        process.stderr.write("[multicorn-proxy] Cannot log action: agent name not resolved\n");
-      } else {
-        await actionLogger.logAction({
-          agent: config.agentName,
-          service,
-          actionType: action,
-          status: "approved"
-        });
+      if (spendingChecker !== null) {
+        const costCents = extractCostCents(toolParams.arguments);
+        if (costCents > 0) {
+          const spendResult = spendingChecker.checkSpend(costCents);
+          if (!spendResult.allowed) {
+            if (actionLogger !== null) {
+              if (!config.agentName || config.agentName.trim().length === 0) {
+                process.stderr.write(
+                  "[multicorn-proxy] Cannot log action: agent name not resolved\n"
+                );
+              } else {
+                await actionLogger.logAction({
+                  agent: config.agentName,
+                  service,
+                  actionType: action,
+                  status: "blocked"
+                });
+              }
+            }
+            const blocked = buildSpendingBlockedResponse(
+              request.id,
+              spendResult.reason ?? "spending limit exceeded",
+              config.dashboardUrl
+            );
+            return JSON.stringify(blocked);
+          }
+          spendingChecker.recordSpend(costCents);
+        }
       }
+      if (actionLogger !== null) {
+        if (!config.agentName || config.agentName.trim().length === 0) {
+          process.stderr.write("[multicorn-proxy] Cannot log action: agent name not resolved\n");
+        } else {
+          await actionLogger.logAction({
+            agent: config.agentName,
+            service,
+            actionType: action,
+            status: "approved"
+          });
+        }
+      }
+      return null;
+    } catch (error) {
+      config.logger.error("Tool call handler error.", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      const blocked = buildInternalErrorResponse(request.id);
+      return JSON.stringify(blocked);
     }
-    return null;
   }
   async function processLine(line) {
     const childProcess = child;
@@ -986,6 +1073,7 @@ function createProxyServer(config) {
     );
     agentId = agentRecord.id;
     grantedScopes = agentRecord.scopes;
+    authInvalid = agentRecord.authInvalid === true;
     config.logger.info("Agent resolved.", {
       agent: config.agentName,
       id: agentId,

package/dist/openclaw-hook/handler.js

@@ -156,19 +156,19 @@ function handleHttpError(status, logger, retryDelaySeconds) {
   }
   if (status === 429) {
     {
-      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action was not checked \u2014 proceeding with fail-open.";
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action blocked: Shield cannot verify permissions.";
       process.stderr.write(`${rateLimitMsg}
 `);
     }
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
   if (status >= 500 && status < 600) {
-    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action was not checked \u2014 proceeding with fail-open.`;
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action blocked: Shield cannot verify permissions.`;
     process.stderr.write(`${serverErrorMsg}
 `);
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
-  return { shouldBlock: false };
+  return { shouldBlock: true };
 }
 async function findAgentByName(agentName, apiKey, baseUrl, logger) {
   try {
@@ -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 → multicorn-shield.js}

@@ -162,21 +162,21 @@ function handleHttpError(status, logger, retryDelaySeconds) {
   }
   if (status === 429) {
     {
-      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action was not checked \u2014 proceeding with fail-open.";
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action blocked: Shield cannot verify permissions.";
       logger?.warn(rateLimitMsg);
       process.stderr.write(`${rateLimitMsg}
 `);
     }
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
   if (status >= 500 && status < 600) {
-    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action was not checked \u2014 proceeding with fail-open.`;
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action blocked: Shield cannot verify permissions.`;
     logger?.warn(serverErrorMsg);
     process.stderr.write(`${serverErrorMsg}
 `);
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
-  return { shouldBlock: false };
+  return { shouldBlock: true };
 }
 async function findAgentByName(agentName, apiKey, baseUrl, logger) {
   try {
@@ -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.15",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "type": "module",