multicorn-shield 0.1.2 → 0.1.5

package/dist/multicorn-proxy.js

@@ -128,6 +128,11 @@ function validateScopeAccess(grantedScopes, requested) {
     reason: `No permissions granted for service "${requested.service}". The agent has not been authorised to access this service. Request scope "${formatScope(requested)}" via the consent screen.`
   };
 }
+function hasScope(grantedScopes, requested) {
+  return grantedScopes.some(
+    (granted) => granted.service === requested.service && granted.permissionLevel === requested.permissionLevel
+  );
+}
 
 // src/logger/action-logger.ts
 function createActionLogger(config) {
@@ -639,9 +644,9 @@ function openBrowser(url) {
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
 }
-async function waitForConsent(agentId, agentName, apiKey, baseUrl, dashboardUrl, logger) {
-  const detectedScopes = detectScopeHints();
-  const consentUrl = buildConsentUrl(agentName, detectedScopes, dashboardUrl);
+async function waitForConsent(agentId, agentName, apiKey, baseUrl, dashboardUrl, logger, scope) {
+  const scopeStrings = scope ? [`${scope.service}:${scope.permissionLevel}`] : detectScopeHints();
+  const consentUrl = buildConsentUrl(agentName, scopeStrings, dashboardUrl);
   logger.info("Opening consent page in your browser.", { url: consentUrl });
   process.stderr.write(
     `
@@ -693,11 +698,12 @@ async function resolveAgentRecord(agentName, apiKey, baseUrl, logger) {
   return { ...agent, scopes };
 }
 function buildConsentUrl(agentName, scopes, dashboardUrl) {
+  const base = dashboardUrl.replace(/\/+$/, "");
   const params = new URLSearchParams({ agent: agentName });
   if (scopes.length > 0) {
     params.set("scopes", scopes.join(","));
   }
-  return `${dashboardUrl}/consent?${params.toString()}`;
+  return `${base}/consent?${params.toString()}`;
 }
 function detectScopeHints() {
   return [];
@@ -746,7 +752,9 @@ function createProxyServer(config) {
   let consentInProgress = false;
   const pendingLines = [];
   let draining = false;
+  let stopped = false;
   async function refreshScopes() {
+    if (stopped) return;
     if (agentId.length === 0) return;
     try {
       const scopes = await fetchGrantedScopes(agentId, config.apiKey, config.baseUrl);
@@ -761,18 +769,24 @@ function createProxyServer(config) {
       });
     }
   }
-  async function ensureConsent() {
-    if (grantedScopes.length > 0 || consentInProgress) return;
+  async function ensureConsent(requestedScope) {
     if (agentId.length === 0) return;
+    if (requestedScope !== void 0) {
+      if (hasScope(grantedScopes, requestedScope) || consentInProgress) return;
+    } else {
+      if (grantedScopes.length > 0 || consentInProgress) return;
+    }
     consentInProgress = true;
     try {
+      const scopeParam = requestedScope !== void 0 ? { service: requestedScope.service, permissionLevel: requestedScope.permissionLevel } : void 0;
       const scopes = await waitForConsent(
         agentId,
         config.agentName,
         config.apiKey,
         config.baseUrl,
         config.dashboardUrl,
-        config.logger
+        config.logger,
+        scopeParam
       );
       grantedScopes = scopes;
       await saveCachedScopes(config.agentName, agentId, scopes);
@@ -786,7 +800,6 @@ function createProxyServer(config) {
     if (request.method !== "tools/call") return null;
     const toolParams = extractToolCallParams(request);
     if (toolParams === null) return null;
-    await ensureConsent();
     const service = extractServiceFromToolName(toolParams.name);
     const action = extractActionFromToolName(toolParams.name);
     const requestedScope = { service, permissionLevel: "execute" };
@@ -797,20 +810,24 @@ function createProxyServer(config) {
       allowed: validation.allowed
     });
     if (!validation.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"
-          });
+      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);
+        return JSON.stringify(blocked);
       }
-      const blocked = buildBlockedResponse(request.id, service, "execute", config.dashboardUrl);
-      return JSON.stringify(blocked);
     }
     if (spendingChecker !== null) {
       const costCents = extractCostCents(toolParams.arguments);
@@ -880,6 +897,7 @@ function createProxyServer(config) {
     void drainQueue();
   }
   async function stop() {
+    stopped = true;
     if (refreshTimer !== null) {
       clearInterval(refreshTimer);
       refreshTimer = null;

package/dist/openclaw-hook/HOOK.md

@@ -25,6 +25,24 @@ metadata:
 > openclaw gateway restart
 > ```
 >
+> **Plugin Configuration:** Configure the plugin in `~/.openclaw/openclaw.json`:
+>
+> ```json
+> {
+>   "plugins": {
+>     "entries": {
+>       "multicorn-shield": {
+>         "enabled": true,
+>         "env": {
+>           "MULTICORN_API_KEY": "mcs_your_key_here",
+>           "MULTICORN_BASE_URL": "https://api.multicorn.ai"
+>         }
+>       }
+>     }
+>   }
+> }
+> ```
+>
 > See the plugin README for full instructions.
 
 Governance layer for OpenClaw agents. Every tool call is checked against your Shield permissions before it runs. Blocked actions never reach the tool. All activity - approved and blocked - shows up in your Shield dashboard.

package/dist/openclaw-hook/handler.js

@@ -123,6 +123,7 @@ function isScopesCacheFile(value) {
 // src/openclaw/shield-client.ts
 var REQUEST_TIMEOUT_MS = 5e3;
 var AUTH_HEADER = "X-Multicorn-Key";
+var authErrorLogged = false;
 function isApiSuccess(value) {
   if (typeof value !== "object" || value === null) return false;
   const obj = value;
@@ -143,13 +144,42 @@ function isPermissionEntry(value) {
   const obj = value;
   return typeof obj["service"] === "string" && typeof obj["read"] === "boolean" && typeof obj["write"] === "boolean" && typeof obj["execute"] === "boolean" && (obj["revoked_at"] === null || typeof obj["revoked_at"] === "string");
 }
-async function findAgentByName(agentName, apiKey, baseUrl) {
+function handleHttpError(status, logger, retryDelaySeconds) {
+  if (status === 401 || status === 403) {
+    if (!authErrorLogged) {
+      authErrorLogged = true;
+      const errorMsg = "[multicorn-shield] ERROR: Authentication failed. Your MULTICORN_API_KEY is invalid or expired. Check the key in your OpenClaw config (~/.openclaw/openclaw.json \u2192 plugins.entries.multicorn-shield.env.MULTICORN_API_KEY). Get a valid key from your Multicorn dashboard (Settings \u2192 API Keys).";
+      process.stderr.write(`${errorMsg}
+`);
+    }
+    return { shouldBlock: true };
+  }
+  if (status === 429) {
+    {
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action was not checked \u2014 proceeding with fail-open.";
+      process.stderr.write(`${rateLimitMsg}
+`);
+    }
+    return { shouldBlock: false };
+  }
+  if (status >= 500 && status < 600) {
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action was not checked \u2014 proceeding with fail-open.`;
+    process.stderr.write(`${serverErrorMsg}
+`);
+    return { shouldBlock: false };
+  }
+  return { shouldBlock: false };
+}
+async function findAgentByName(agentName, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/agents`, {
       headers: { [AUTH_HEADER]: apiKey },
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
-    if (!response.ok) return null;
+    if (!response.ok) {
+      handleHttpError(response.status, logger);
+      return null;
+    }
     const body = await response.json();
     if (!isApiSuccess(body)) return null;
     const agents = body.data;
@@ -160,7 +190,7 @@ async function findAgentByName(agentName, apiKey, baseUrl) {
     return null;
   }
 }
-async function registerAgent(agentName, apiKey, baseUrl) {
+async function registerAgent(agentName, apiKey, baseUrl, logger) {
   const response = await fetch(`${baseUrl}/api/v1/agents`, {
     method: "POST",
     headers: {
@@ -171,6 +201,7 @@ async function registerAgent(agentName, apiKey, baseUrl) {
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
   });
   if (!response.ok) {
+    handleHttpError(response.status);
     throw new Error(
       `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
     );
@@ -181,23 +212,26 @@ async function registerAgent(agentName, apiKey, baseUrl) {
   }
   return body.data.id;
 }
-async function findOrRegisterAgent(agentName, apiKey, baseUrl) {
-  const existing = await findAgentByName(agentName, apiKey, baseUrl);
+async function findOrRegisterAgent(agentName, apiKey, baseUrl, logger) {
+  const existing = await findAgentByName(agentName, apiKey, baseUrl, logger);
   if (existing !== null) return existing;
   try {
-    const id = await registerAgent(agentName, apiKey, baseUrl);
+    const id = await registerAgent(agentName, apiKey, baseUrl, logger);
     return { id, name: agentName };
   } catch {
     return null;
   }
 }
-async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
+async function fetchGrantedScopes(agentId, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/agents/${agentId}`, {
       headers: { [AUTH_HEADER]: apiKey },
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
-    if (!response.ok) return [];
+    if (!response.ok) {
+      handleHttpError(response.status, logger);
+      return [];
+    }
     const body = await response.json();
     if (!isApiSuccess(body)) return [];
     const detail = body.data;
@@ -215,7 +249,7 @@ async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
     return [];
   }
 }
-async function logAction(payload, apiKey, baseUrl) {
+async function logAction(payload, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/actions`, {
       method: "POST",
@@ -227,10 +261,7 @@ async function logAction(payload, apiKey, baseUrl) {
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
     if (!response.ok) {
-      process.stderr.write(
-        `[multicorn-shield] Action log failed: HTTP ${String(response.status)}.
-`
-      );
+      handleHttpError(response.status, logger);
     }
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
@@ -261,9 +292,12 @@ function deriveDashboardUrl(baseUrl) {
     return "https://app.multicorn.ai";
   }
 }
-function buildConsentUrl(agentName, dashboardUrl) {
+function buildConsentUrl(agentName, dashboardUrl, scope) {
   const base = dashboardUrl.replace(/\/+$/, "");
   const params = new URLSearchParams({ agent: agentName });
+  if (scope) {
+    params.set("scopes", `${scope.service}:${scope.permissionLevel}`);
+  }
   return `${base}/consent?${params.toString()}`;
 }
 function openBrowser(url) {
@@ -279,9 +313,9 @@ ${url}
     );
   }
 }
-async function waitForConsent(agentId, agentName, apiKey, baseUrl) {
+async function waitForConsent(agentId, agentName, apiKey, baseUrl, scope, logger) {
   const dashboardUrl = deriveDashboardUrl(baseUrl);
-  const consentUrl = buildConsentUrl(agentName, dashboardUrl);
+  const consentUrl = buildConsentUrl(agentName, dashboardUrl, scope);
   process.stderr.write(
     `[multicorn-shield] Opening consent page...
 ${consentUrl}
@@ -292,7 +326,7 @@ Waiting for you to grant access in the Multicorn dashboard...
   const deadline = Date.now() + POLL_TIMEOUT_MS2;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL_MS2);
-    const scopes = await fetchGrantedScopes(agentId, apiKey, baseUrl);
+    const scopes = await fetchGrantedScopes(agentId, apiKey, baseUrl, logger);
     if (scopes.length > 0) {
       process.stderr.write("[multicorn-shield] Permissions granted.\n");
       return scopes;
@@ -306,6 +340,13 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/scopes/scope-validator.ts
+function hasScope(grantedScopes2, requested) {
+  return grantedScopes2.some(
+    (granted) => granted.service === requested.service && granted.permissionLevel === requested.permissionLevel
+  );
+}
+
 // src/openclaw/hook/handler.ts
 var agentRecord = null;
 var grantedScopes = [];
@@ -368,11 +409,20 @@ async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
   }
   return "ready";
 }
-async function ensureConsent(agentName, apiKey, baseUrl) {
-  if (grantedScopes.length > 0 || consentInProgress || agentRecord === null) return;
+async function ensureConsent(agentName, apiKey, baseUrl, scope) {
+  if (agentRecord === null) return;
+  if (scope !== void 0) {
+    const requestedScope = {
+      service: scope.service,
+      permissionLevel: scope.permissionLevel
+    };
+    if (hasScope(grantedScopes, requestedScope) || consentInProgress) return;
+  } else {
+    if (grantedScopes.length > 0 || consentInProgress) return;
+  }
   consentInProgress = true;
   try {
-    const scopes = await waitForConsent(agentRecord.id, agentName, apiKey, baseUrl);
+    const scopes = await waitForConsent(agentRecord.id, agentName, apiKey, baseUrl, scope);
     grantedScopes = scopes;
     await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
     });
@@ -382,6 +432,7 @@ async function ensureConsent(agentName, apiKey, baseUrl) {
 }
 function isPermitted(event) {
   const mapping = mapToolToScope(event.context.toolName);
+  if (!grantedScopes || grantedScopes.length === 0) return false;
   return grantedScopes.some(
     (scope) => scope.service === mapping.service && scope.permissionLevel === mapping.permissionLevel
   );
@@ -406,8 +457,14 @@ var handler = async (event) => {
   if (readiness === "skip") {
     return;
   }
-  await ensureConsent(agentName, config.apiKey, config.baseUrl);
   const mapping = mapToolToScope(event.context.toolName);
+  const requestedScope = {
+    service: mapping.service,
+    permissionLevel: mapping.permissionLevel
+  };
+  if (!hasScope(grantedScopes, requestedScope)) {
+    await ensureConsent(agentName, config.apiKey, config.baseUrl, mapping);
+  }
   const permitted = isPermitted(event);
   if (!permitted) {
     const capitalizedService = mapping.service.charAt(0).toUpperCase() + mapping.service.slice(1);

package/dist/openclaw-plugin/index.js

@@ -1,10 +1,14 @@
-import { readFile, mkdir, writeFile } from 'fs/promises';
+import * as fs from 'fs';
+import * as path from 'path';
 import { join } from 'path';
+import * as os from 'os';
 import { homedir } from 'os';
+import { mkdir, readFile, writeFile } from 'fs/promises';
 import { spawn } from 'child_process';
 
 // Multicorn Shield plugin for OpenClaw - https://multicorn.ai
 
+
 // src/openclaw/tool-mapper.ts
 var TOOL_MAP = {
   // OpenClaw built-in tools
@@ -127,6 +131,7 @@ var AUTH_HEADER = "X-Multicorn-Key";
 var POLL_INTERVAL_MS = 3e3;
 var MAX_POLLS = 100;
 var POLL_TIMEOUT_MS = POLL_INTERVAL_MS * MAX_POLLS;
+var authErrorLogged = false;
 function isApiSuccess(value) {
   if (typeof value !== "object" || value === null) return false;
   const obj = value;
@@ -152,13 +157,50 @@ function isApprovalResponse(value) {
   const obj = value;
   return typeof obj["id"] === "string" && typeof obj["status"] === "string" && ["pending", "approved", "rejected", "expired"].includes(obj["status"]) && (obj["decided_at"] === null || typeof obj["decided_at"] === "string");
 }
-async function findAgentByName(agentName, apiKey, baseUrl) {
+function handleHttpError(status, logger, retryDelaySeconds) {
+  if (status === 401 || status === 403) {
+    if (!authErrorLogged) {
+      authErrorLogged = true;
+      const errorMsg = "[multicorn-shield] ERROR: Authentication failed. Your MULTICORN_API_KEY is invalid or expired. Check the key in your OpenClaw config (~/.openclaw/openclaw.json \u2192 plugins.entries.multicorn-shield.env.MULTICORN_API_KEY). Get a valid key from your Multicorn dashboard (Settings \u2192 API Keys).";
+      logger?.error(errorMsg);
+      process.stderr.write(`${errorMsg}
+`);
+    }
+    return { shouldBlock: true };
+  }
+  if (status === 429) {
+    if (retryDelaySeconds !== void 0) {
+      const rateLimitMsg = `[multicorn-shield] Rate limited by Shield API. Retrying in ${String(retryDelaySeconds)}s.`;
+      logger?.warn(rateLimitMsg);
+      process.stderr.write(`${rateLimitMsg}
+`);
+    } else {
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action was not checked \u2014 proceeding with fail-open.";
+      logger?.warn(rateLimitMsg);
+      process.stderr.write(`${rateLimitMsg}
+`);
+    }
+    return { shouldBlock: false };
+  }
+  if (status >= 500 && status < 600) {
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action was not checked \u2014 proceeding with fail-open.`;
+    logger?.warn(serverErrorMsg);
+    process.stderr.write(`${serverErrorMsg}
+`);
+    return { shouldBlock: false };
+  }
+  return { shouldBlock: false };
+}
+async function findAgentByName(agentName, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/agents`, {
       headers: { [AUTH_HEADER]: apiKey },
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
-    if (!response.ok) return null;
+    if (!response.ok) {
+      handleHttpError(response.status, logger);
+      return null;
+    }
     const body = await response.json();
     if (!isApiSuccess(body)) return null;
     const agents = body.data;
@@ -169,7 +211,7 @@ async function findAgentByName(agentName, apiKey, baseUrl) {
     return null;
   }
 }
-async function registerAgent(agentName, apiKey, baseUrl) {
+async function registerAgent(agentName, apiKey, baseUrl, logger) {
   const response = await fetch(`${baseUrl}/api/v1/agents`, {
     method: "POST",
     headers: {
@@ -180,6 +222,7 @@ async function registerAgent(agentName, apiKey, baseUrl) {
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
   });
   if (!response.ok) {
+    handleHttpError(response.status, logger);
     throw new Error(
       `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
     );
@@ -190,23 +233,26 @@ async function registerAgent(agentName, apiKey, baseUrl) {
   }
   return body.data.id;
 }
-async function findOrRegisterAgent(agentName, apiKey, baseUrl) {
-  const existing = await findAgentByName(agentName, apiKey, baseUrl);
+async function findOrRegisterAgent(agentName, apiKey, baseUrl, logger) {
+  const existing = await findAgentByName(agentName, apiKey, baseUrl, logger);
   if (existing !== null) return existing;
   try {
-    const id = await registerAgent(agentName, apiKey, baseUrl);
+    const id = await registerAgent(agentName, apiKey, baseUrl, logger);
     return { id, name: agentName };
   } catch {
     return null;
   }
 }
-async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
+async function fetchGrantedScopes(agentId, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/agents/${agentId}`, {
       headers: { [AUTH_HEADER]: apiKey },
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
-    if (!response.ok) return [];
+    if (!response.ok) {
+      handleHttpError(response.status, logger);
+      return [];
+    }
     const body = await response.json();
     if (!isApiSuccess(body)) return [];
     const detail = body.data;
@@ -224,7 +270,7 @@ async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
     return [];
   }
 }
-async function checkActionPermission(payload, apiKey, baseUrl) {
+async function checkActionPermission(payload, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/actions`, {
       method: "POST",
@@ -250,6 +296,14 @@ async function checkActionPermission(payload, apiKey, baseUrl) {
       }
       return { status: "pending", approvalId };
     }
+    if (response.status === 401 || response.status === 403) {
+      handleHttpError(response.status, logger);
+      return { status: "blocked" };
+    }
+    if (response.status === 429 || response.status >= 500 && response.status < 600) {
+      handleHttpError(response.status, logger);
+      return { status: "blocked" };
+    }
     return { status: "blocked" };
   } catch {
     return { status: "blocked" };
@@ -270,6 +324,14 @@ async function pollApprovalStatus(approvalId, apiKey, baseUrl, logger) {
           signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
         });
         if (!response.ok) {
+          if (response.status === 401 || response.status === 403) {
+            handleHttpError(response.status, logger);
+            return "timeout";
+          }
+          if (response.status === 429 || response.status >= 500 && response.status < 600) {
+            const retryDelay = retry < 2 ? Math.pow(2, retry) : void 0;
+            handleHttpError(response.status, logger, retryDelay);
+          }
           logDebug?.(
             `Poll ${String(pollCount + 1)} failed: HTTP ${String(response.status)}. Retrying...`
           );
@@ -326,7 +388,7 @@ async function pollApprovalStatus(approvalId, apiKey, baseUrl, logger) {
   }
   return "timeout";
 }
-async function logAction(payload, apiKey, baseUrl) {
+async function logAction(payload, apiKey, baseUrl, logger) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/actions`, {
       method: "POST",
@@ -338,10 +400,7 @@ async function logAction(payload, apiKey, baseUrl) {
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
     if (!response.ok) {
-      process.stderr.write(
-        `[multicorn-shield] Action log failed: HTTP ${String(response.status)}.
-`
-      );
+      handleHttpError(response.status, logger);
     }
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
@@ -372,9 +431,12 @@ function deriveDashboardUrl(baseUrl) {
     return "https://app.multicorn.ai";
   }
 }
-function buildConsentUrl(agentName, dashboardUrl) {
+function buildConsentUrl(agentName, dashboardUrl, scope) {
   const base = dashboardUrl.replace(/\/+$/, "");
   const params = new URLSearchParams({ agent: agentName });
+  if (scope) {
+    params.set("scopes", `${scope.service}:${scope.permissionLevel}`);
+  }
   return `${base}/consent?${params.toString()}`;
 }
 function openBrowser(url) {
@@ -390,9 +452,9 @@ ${url}
     );
   }
 }
-async function waitForConsent(agentId, agentName, apiKey, baseUrl) {
+async function waitForConsent(agentId, agentName, apiKey, baseUrl, scope, logger) {
   const dashboardUrl = deriveDashboardUrl(baseUrl);
-  const consentUrl = buildConsentUrl(agentName, dashboardUrl);
+  const consentUrl = buildConsentUrl(agentName, dashboardUrl, scope);
   process.stderr.write(
     `[multicorn-shield] Opening consent page...
 ${consentUrl}
@@ -403,7 +465,7 @@ Waiting for you to grant access in the Multicorn dashboard...
   const deadline = Date.now() + POLL_TIMEOUT_MS2;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL_MS2);
-    const scopes = await fetchGrantedScopes(agentId, apiKey, baseUrl);
+    const scopes = await fetchGrantedScopes(agentId, apiKey, baseUrl, logger);
     if (scopes.length > 0) {
       process.stderr.write("[multicorn-shield] Permissions granted.\n");
       return scopes;
@@ -417,6 +479,13 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/scopes/scope-validator.ts
+function hasScope(grantedScopes2, requested) {
+  return grantedScopes2.some(
+    (granted) => granted.service === requested.service && granted.permissionLevel === requested.permissionLevel
+  );
+}
+
 // src/openclaw/plugin/index.ts
 var agentRecord = null;
 var grantedScopes = [];
@@ -424,15 +493,45 @@ var consentInProgress = false;
 var lastScopeRefresh = 0;
 var pluginLogger = null;
 var pluginConfig;
+var connectionLogged = false;
 var SCOPE_REFRESH_INTERVAL_MS = 6e4;
 function readConfig() {
   const pc = pluginConfig ?? {};
-  const apiKey = asString(pc["apiKey"]) ?? process.env["MULTICORN_API_KEY"] ?? "";
-  const baseUrl = asString(pc["baseUrl"]) ?? process.env["MULTICORN_BASE_URL"] ?? "https://api.multicorn.ai";
+  let resolvedApiKey = asString(pc["apiKey"]) ?? process.env["MULTICORN_API_KEY"] ?? "";
+  let resolvedBaseUrl = asString(pc["baseUrl"]) ?? process.env["MULTICORN_BASE_URL"] ?? "";
+  if (!resolvedApiKey) {
+    try {
+      const configPath = path.join(os.homedir(), ".openclaw", "openclaw.json");
+      const configContent = fs.readFileSync(configPath, "utf-8");
+      const config = JSON.parse(configContent);
+      const hooks = config["hooks"];
+      const internal = hooks?.["internal"];
+      const entries = internal?.["entries"];
+      const shieldEntry = entries?.["multicorn-shield"];
+      const env = shieldEntry?.env;
+      if (env) {
+        const hookApiKey = asString(env["MULTICORN_API_KEY"]);
+        const hookBaseUrl = asString(env["MULTICORN_BASE_URL"]);
+        if (hookApiKey) {
+          resolvedApiKey = hookApiKey;
+          resolvedBaseUrl = resolvedBaseUrl || (hookBaseUrl ?? "https://api.multicorn.ai");
+          pluginLogger?.warn(
+            "Multicorn Shield: Reading config from hooks.internal.entries. For cleaner setup, set MULTICORN_API_KEY as a system environment variable."
+          );
+        } else if (hookBaseUrl) {
+          resolvedBaseUrl = resolvedBaseUrl || hookBaseUrl;
+        }
+      }
+    } catch {
+    }
+  }
+  if (!resolvedBaseUrl) {
+    resolvedBaseUrl = "https://api.multicorn.ai";
+  }
   const agentName = asString(pc["agentName"]) ?? process.env["MULTICORN_AGENT_NAME"] ?? null;
   const failModeRaw = asString(pc["failMode"]) ?? process.env["MULTICORN_FAIL_MODE"] ?? "open";
   const failMode = failModeRaw === "closed" ? "closed" : "open";
-  return { apiKey, baseUrl, agentName, failMode };
+  return { apiKey: resolvedApiKey, baseUrl: resolvedBaseUrl, agentName, failMode };
 }
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
@@ -456,15 +555,17 @@ async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
     const cached = await loadCachedScopes(agentName);
     if (cached !== null && cached.length > 0) {
       grantedScopes = cached;
-      void findOrRegisterAgent(agentName, apiKey, baseUrl).then((record) => {
-        if (record !== null) agentRecord = record;
-      });
+      void findOrRegisterAgent(agentName, apiKey, baseUrl, pluginLogger ?? void 0).then(
+        (record) => {
+          if (record !== null) agentRecord = record;
+        }
+      );
       lastScopeRefresh = Date.now();
       return "ready";
     }
   }
   if (agentRecord === null) {
-    const record = await findOrRegisterAgent(agentName, apiKey, baseUrl);
+    const record = await findOrRegisterAgent(agentName, apiKey, baseUrl, pluginLogger ?? void 0);
     if (record === null) {
       if (failMode === "closed") {
         return "block";
@@ -474,20 +575,45 @@ async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
     }
     agentRecord = record;
   }
-  const scopes = await fetchGrantedScopes(agentRecord.id, apiKey, baseUrl);
+  const scopes = await fetchGrantedScopes(
+    agentRecord.id,
+    apiKey,
+    baseUrl,
+    pluginLogger ?? void 0
+  );
   grantedScopes = scopes;
   lastScopeRefresh = Date.now();
   if (scopes.length > 0) {
     await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
     });
   }
+  if (!connectionLogged) {
+    connectionLogged = true;
+    pluginLogger?.info(`Multicorn Shield connected. Agent: ${agentName}`);
+  }
   return "ready";
 }
-async function ensureConsent(agentName, apiKey, baseUrl) {
-  if (grantedScopes.length > 0 || consentInProgress || agentRecord === null) return;
+async function ensureConsent(agentName, apiKey, baseUrl, scope) {
+  if (agentRecord === null) return;
+  if (scope !== void 0) {
+    const requestedScope = {
+      service: scope.service,
+      permissionLevel: scope.permissionLevel
+    };
+    if (hasScope(grantedScopes, requestedScope) || consentInProgress) return;
+  } else {
+    if (grantedScopes.length > 0 || consentInProgress) return;
+  }
   consentInProgress = true;
   try {
-    const scopes = await waitForConsent(agentRecord.id, agentName, apiKey, baseUrl);
+    const scopes = await waitForConsent(
+      agentRecord.id,
+      agentName,
+      apiKey,
+      baseUrl,
+      scope,
+      pluginLogger ?? void 0
+    );
     grantedScopes = scopes;
     await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
     });
@@ -581,7 +707,6 @@ async function beforeToolCall(event, ctx) {
   if (readiness === "skip") {
     return void 0;
   }
-  await ensureConsent(agentName, config.apiKey, config.baseUrl);
   const command = event.toolName === "exec" && typeof event.params["command"] === "string" ? event.params["command"] : void 0;
   const mapping = mapToolToScope(event.toolName, command);
   pluginLogger?.info(
@@ -607,9 +732,24 @@ async function beforeToolCall(event, ctx) {
       }
     },
     config.apiKey,
-    config.baseUrl
+    config.baseUrl,
+    pluginLogger ?? void 0
   );
   if (permissionResult.status === "approved") {
+    if (agentRecord !== null) {
+      const scopes = await fetchGrantedScopes(
+        agentRecord.id,
+        config.apiKey,
+        config.baseUrl,
+        pluginLogger ?? void 0
+      );
+      grantedScopes = scopes;
+      lastScopeRefresh = Date.now();
+      if (scopes.length > 0) {
+        await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+        });
+      }
+    }
     return void 0;
   }
   if (permissionResult.status === "pending" && permissionResult.approvalId !== void 0) {
@@ -642,6 +782,13 @@ async function beforeToolCall(event, ctx) {
       blockReason: "Approval request timed out after 5 minutes."
     };
   }
+  const requestedScope = {
+    service: mapping.service,
+    permissionLevel: mapping.permissionLevel
+  };
+  if (!hasScope(grantedScopes, requestedScope) && agentRecord !== null) {
+    await ensureConsent(agentName, config.apiKey, config.baseUrl, mapping);
+  }
   const capitalizedService = mapping.service.charAt(0).toUpperCase() + mapping.service.slice(1);
   const reason = `${capitalizedService} ${mapping.permissionLevel} access is not allowed. Visit the Multicorn Shield dashboard to manage permissions.`;
   return { block: true, blockReason: reason };
@@ -663,7 +810,8 @@ function afterToolCall(event, ctx) {
       }
     },
     config.apiKey,
-    config.baseUrl
+    config.baseUrl,
+    pluginLogger ?? void 0
   );
   return Promise.resolve();
 }
@@ -678,6 +826,14 @@ var plugin = {
     api.on("before_tool_call", beforeToolCall, { priority: 10 });
     api.on("after_tool_call", afterToolCall);
     api.logger.info("Multicorn Shield plugin registered.");
+    const config = readConfig();
+    if (config.apiKey.length === 0) {
+      api.logger.error(
+        "Multicorn Shield: No API key found. Set MULTICORN_API_KEY in your OpenClaw config (~/.openclaw/openclaw.json \u2192 plugins.entries.multicorn-shield.env.MULTICORN_API_KEY). Get a key from your Multicorn dashboard (Settings \u2192 API Keys)."
+      );
+    } else {
+      api.logger.info(`Multicorn Shield connecting to ${config.baseUrl}`);
+    }
   }
 };
 function register(api) {
@@ -692,6 +848,7 @@ function resetState() {
   lastScopeRefresh = 0;
   pluginLogger = null;
   pluginConfig = void 0;
+  connectionLogged = false;
 }
 
 export { afterToolCall, beforeToolCall, plugin, readConfig, register, resetState, resolveAgentName };

package/package.json

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