multicorn-shield 1.11.1 → 1.12.0

package/dist/openclaw-hook/HOOK.md

@@ -33,9 +33,11 @@ metadata:
 >     "entries": {
 >       "multicorn-shield": {
 >         "enabled": true,
->         "env": {
->           "MULTICORN_API_KEY": "mcs_your_key_here",
->           "MULTICORN_BASE_URL": "https://api.multicorn.ai"
+>         "config": {
+>           "apiKey": "${MULTICORN_API_KEY}",
+>           "baseUrl": "https://api.multicorn.ai",
+>           "agentName": "openclaw",
+>           "failMode": "closed"
 >         }
 >       }
 >     }

package/dist/openclaw-hook/handler.js

@@ -184,7 +184,7 @@ 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).";
+      const errorMsg = "[multicorn-shield] ERROR: Authentication failed. Your MULTICORN_API_KEY is invalid or expired. Check the key in ~/.multicorn/config.json (from npx multicorn-shield init) or ~/.openclaw/openclaw.json \u2192 plugins.entries.multicorn-shield.config.apiKey. Get a valid key from your Multicorn dashboard (Settings \u2192 API Keys).";
       process.stderr.write(`${errorMsg}
 `);
     }

package/dist/openclaw-plugin/multicorn-shield.js

@@ -189,7 +189,7 @@ 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).";
+      const errorMsg = "[multicorn-shield] ERROR: Authentication failed. Your MULTICORN_API_KEY is invalid or expired. Check the key in ~/.multicorn/config.json (from npx multicorn-shield init) or ~/.openclaw/openclaw.json \u2192 plugins.entries.multicorn-shield.config.apiKey. Get a valid key from your Multicorn dashboard (Settings \u2192 API Keys).";
       logger?.error(errorMsg);
       process.stderr.write(`${errorMsg}
 `);
@@ -491,20 +491,41 @@ function agentNameFromOpenclawPlatform(cfg) {
   }
   return void 0;
 }
+var ENV_REF_PATTERN = /^\$\{([A-Z_][A-Z0-9_]*)\}$/;
+function resolveConfigString(value) {
+  const raw = asString(value);
+  if (raw === void 0) return void 0;
+  const match = ENV_REF_PATTERN.exec(raw.trim());
+  if (match === null) return raw;
+  const envName = match[1];
+  if (envName === void 0) return void 0;
+  const fromEnv = process.env[envName];
+  return typeof fromEnv === "string" && fromEnv.length > 0 ? fromEnv : void 0;
+}
+function parseFailMode(value) {
+  if (value === "open") return "open";
+  if (value === "closed") return "closed";
+  return "closed";
+}
 function readConfig() {
   const pc = pluginConfig ?? {};
-  const resolvedApiKey = asString(cachedMulticornConfig?.apiKey) ?? asString(process.env["MULTICORN_API_KEY"]) ?? "";
-  const resolvedBaseUrl = asString(cachedMulticornConfig?.baseUrl) ?? asString(process.env["MULTICORN_BASE_URL"]) ?? "https://api.multicorn.ai";
+  const fromFileKey = asString(cachedMulticornConfig?.apiKey);
+  const fromPluginKey = resolveConfigString(pc["apiKey"]);
+  const fromEnvKey = asString(process.env["MULTICORN_API_KEY"]);
+  let apiKey = fromFileKey ?? fromPluginKey ?? fromEnvKey ?? "";
+  const fromPluginBase = resolveConfigString(pc["baseUrl"]);
+  const fromFileBase = asString(cachedMulticornConfig?.baseUrl);
+  const fromEnvBase = asString(process.env["MULTICORN_BASE_URL"]);
+  const baseUrl = fromPluginBase ?? fromFileBase ?? fromEnvBase ?? "https://api.multicorn.ai";
   const agentName = asString(pc["agentName"]) ?? process.env["MULTICORN_AGENT_NAME"] ?? agentNameFromOpenclawPlatform(cachedMulticornConfig) ?? asString(cachedMulticornConfig?.agentName) ?? null;
-  const failMode = "closed";
-  let apiKey = resolvedApiKey;
+  const failMode = parseFailMode(pc["failMode"]);
   if (apiKey.length > 0 && (!apiKey.startsWith("mcs_") || apiKey.length < 16)) {
     pluginLogger?.error(
       "Invalid API key format. Key must start with mcs_ and be at least 16 characters."
     );
     apiKey = "";
   }
-  return { apiKey, baseUrl: resolvedBaseUrl, agentName, failMode };
+  return { apiKey, baseUrl, agentName, failMode };
 }
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
@@ -919,4 +940,4 @@ function resetState() {
   hasLoggedFirstAction = false;
 }
 
-export { afterToolCall, beforeToolCall, plugin, readConfig, register, resetState, resolveAgentName };
+export { afterToolCall, beforeToolCall, plugin, readConfig, register, resetState, resolveAgentName, resolveConfigString };

package/dist/openclaw-plugin/openclaw.plugin.json

@@ -9,7 +9,7 @@
     "properties": {
       "apiKey": {
         "type": "string",
-        "pattern": "^mcs_.{12,}$",
+        "pattern": "^(mcs_.{12,}|\\$\\{MULTICORN_API_KEY\\})$",
         "minLength": 16
       },
       "baseUrl": {

package/dist/shield-extension.js

@@ -22405,18 +22405,9 @@ var INIT_WIZARD_PLATFORM_REGISTRY = [
   },
   { slug: "other-mcp", displayName: "Local MCP / Other", section: "hosted" }
 ];
-(() => {
-  const itemsFor = (section) => INIT_WIZARD_PLATFORM_REGISTRY.filter((e) => e.section === section).map((e) => ({
-    platform: e.slug,
-    label: e.displayName
-  }));
-  return [
-    { title: "Recommended (native plugin)", items: itemsFor("native") },
-    { title: "Hosted proxy (MCP only)", items: itemsFor("hosted") }
-  ];
-})();
+var INIT_WIZARD_PICKER_NATIVE_SLUGS = INIT_WIZARD_PLATFORM_REGISTRY.filter((e) => e.section === "native").map((e) => e.slug);
 Object.fromEntries(
-  INIT_WIZARD_PLATFORM_REGISTRY.map((e, i) => [i + 1, e.slug])
+  INIT_WIZARD_PICKER_NATIVE_SLUGS.map((slug, i) => [i + 1, slug])
 );
 
 // src/extension/config-reader.ts
@@ -22518,7 +22509,7 @@ async function writeExtensionBackup(claudeDesktopConfigPath, mcpServers) {
 
 // package.json
 var package_default = {
-  version: "1.11.1"};
+  version: "1.12.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "author": "Multicorn AI Pty Ltd",
@@ -79,7 +79,8 @@
     "prepare": "husky || true",
     "release:patch": "npm version patch && pnpm publish",
     "release:minor": "npm version minor && pnpm publish",
-    "release:major": "npm version major && pnpm publish"
+    "release:major": "npm version major && pnpm publish",
+    "local": "pnpm build &&node dist/multicorn-shield.js init --base-url http://localhost:8080"
   },
   "lint-staged": {
     "*.ts": [
@@ -107,6 +108,7 @@
     "@size-limit/file": "^11.1.6",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.0.5",
+    "ajv": "^8.18.0",
     "eslint": "^9.19.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-unicorn": "^57.0.0",

package/plugins/windsurf/hooks/scripts/pre-action.cjs

@@ -1,7 +1,8 @@
 /**
  * Windsurf Cascade pre-hook: permission check before read, write, terminal, or MCP tool use.
  * Routes by stdin JSON field agent_action_name (see Windsurf Cascade Hooks docs).
- * Fail-closed on API errors once config is loaded. Fail-open if Shield is not configured.
+ * Fail-closed on API errors once config is loaded or Windsurf hooks are installed.
+ * Fail-open only when Shield is not configured (no config file and no installed hook copy).
  */
 
 "use strict";
@@ -110,12 +111,83 @@ function resolveWindsurfAgentName(obj) {
   return pickAgentNameForPlatform(obj, "windsurf", process.cwd());
 }
 
+/**
+ * @returns {string}
+ */
+function multicornConfigPath() {
+  return path.join(os.homedir(), ".multicorn", "config.json");
+}
+
+/**
+ * @returns {boolean}
+ */
+function configFileExists() {
+  try {
+    fs.accessSync(multicornConfigPath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {boolean}
+ */
+function isShieldWindsurfHooksInstalled() {
+  try {
+    fs.accessSync(path.join(os.homedir(), ".multicorn", "windsurf-hooks", "pre-action.cjs"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {boolean}
+ */
+function shouldEnforceGovernance() {
+  return configFileExists() || isShieldWindsurfHooksInstalled();
+}
+
+/**
+ * @param {string} baseUrl
+ * @returns {string}
+ */
+function apiHostFromBaseUrl(baseUrl) {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * @param {string} agentActionName
+ * @param {string} agentName
+ * @param {string} baseUrl
+ */
+function logInvocation(agentActionName, agentName, baseUrl) {
+  process.stderr.write(
+    `${LOG_PREFIX} check event=${agentActionName} agent=${agentName} api=${apiHostFromBaseUrl(baseUrl)}\n`,
+  );
+}
+
+/**
+ * @param {string} cause
+ * @param {string} fix
+ * @returns {never}
+ */
+function blockMisconfigured(cause, fix) {
+  process.stderr.write(`${LOG_PREFIX} Action blocked: ${cause}\n  ${fix}\n`);
+  process.exit(2);
+}
+
 /**
  * @returns {{ apiKey: string; baseUrl: string; agentName: string } | null}
  */
 function loadConfig() {
   try {
-    const configPath = path.join(os.homedir(), ".multicorn", "config.json");
+    const configPath = multicornConfigPath();
     const raw = fs.readFileSync(configPath, "utf8");
     const obj = JSON.parse(raw);
     const apiKey = typeof obj.apiKey === "string" ? obj.apiKey : "";
@@ -564,16 +636,13 @@ async function main() {
   try {
     raw = await readStdin();
   } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    process.stderr.write(`${LOG_PREFIX} could not read stdin (${msg}). Allowing action.\n`);
-    process.exit(0);
-  }
-
-  const config = loadConfig();
-  if (config === null) {
-    process.exit(0);
-  }
-  if (config.apiKey.length === 0 || config.agentName.length === 0) {
+    if (shouldEnforceGovernance()) {
+      const msg = e instanceof Error ? e.message : String(e);
+      blockMisconfigured(
+        `could not read stdin (${msg}), cannot verify permissions.`,
+        "Retry the action. If it keeps failing, check Windsurf hook configuration.",
+      );
+    }
     process.exit(0);
   }
 
@@ -582,8 +651,13 @@ async function main() {
   try {
     hookPayload = JSON.parse(raw.length > 0 ? raw : "{}");
   } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    process.stderr.write(`${LOG_PREFIX} invalid JSON (${msg}). Allowing action.\n`);
+    if (shouldEnforceGovernance()) {
+      const msg = e instanceof Error ? e.message : String(e);
+      blockMisconfigured(
+        `invalid JSON on stdin (${msg}), cannot verify permissions.`,
+        "Retry the action or reinstall hooks with npx multicorn-shield init.",
+      );
+    }
     process.exit(0);
   }
 
@@ -606,6 +680,32 @@ async function main() {
   }
   const { service, actionType } = mapped;
 
+  const config = loadConfig();
+  if (config === null) {
+    if (shouldEnforceGovernance()) {
+      blockMisconfigured(
+        "Shield config missing or unreadable, cannot verify permissions.",
+        "Run npx multicorn-shield init and complete setup, then check ~/.multicorn/config.json.",
+      );
+    }
+    process.exit(0);
+  }
+  if (config.apiKey.length === 0 || config.agentName.length === 0) {
+    if (shouldEnforceGovernance()) {
+      const cause =
+        config.apiKey.length === 0
+          ? "API key missing from Shield config, cannot verify permissions."
+          : "Windsurf agent name missing from Shield config, cannot verify permissions.";
+      blockMisconfigured(
+        cause,
+        "Run npx multicorn-shield init, paste a valid mcs_ key, and configure the Windsurf agent.",
+      );
+    }
+    process.exit(0);
+  }
+
+  logInvocation(agentActionName, config.agentName, config.baseUrl);
+
   let toolInfoSerialized;
   try {
     toolInfoSerialized =
@@ -614,10 +714,10 @@ async function main() {
         : JSON.stringify(toolInfo === undefined ? null : toolInfo);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    process.stderr.write(
-      `${LOG_PREFIX} could not serialize tool_info (${msg}). Allowing action.\n`,
+    blockMisconfigured(
+      `could not serialize tool_info (${msg}), cannot verify permissions.`,
+      "Retry the action. If it keeps failing, reinstall hooks with npx multicorn-shield init.",
     );
-    process.exit(0);
   }
 
   if (typeof toolInfoSerialized === "string" && toolInfoSerialized.length > 4096) {
@@ -718,6 +818,15 @@ async function main() {
     process.exit(2);
   }
 
+  if (statusCode === 401 || statusCode === 403) {
+    const host = apiHostFromBaseUrl(config.baseUrl);
+    process.stderr.write(
+      `${LOG_PREFIX} Action blocked: API key not recognized for ${host}.\n` +
+        `  Run npx multicorn-shield init and paste a valid key at the prompt.\n`,
+    );
+    process.exit(2);
+  }
+
   const httpDetail = bodyText.length > 300 ? `${bodyText.slice(0, 300)}...` : bodyText;
   process.stderr.write(
     `${LOG_PREFIX} Action blocked: Shield returned HTTP ${String(statusCode)}, cannot verify permissions.\n` +