multicorn-shield 0.10.0 → 0.12.0

package/dist/shield-extension.js

@@ -22359,11 +22359,117 @@ async function writeExtensionBackup(claudeDesktopConfigPath, mcpServers) {
 
 // package.json
 var package_default = {
-  version: "0.10.0"};
+  version: "0.12.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;
 
+// src/extension/proxy-url-validator.ts
+var ProxyUrlValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProxyUrlValidationError";
+  }
+};
+function isPrivateOrReservedIpv4(hostname3) {
+  const parts = hostname3.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  const octets = [];
+  for (const p of parts) {
+    if (!/^\d{1,3}$/.test(p)) {
+      return false;
+    }
+    const n = Number.parseInt(p, 10);
+    if (Number.isNaN(n) || n < 0 || n > 255) {
+      return false;
+    }
+    octets.push(n);
+  }
+  const [a, b] = octets;
+  if (a === void 0 || b === void 0) {
+    return false;
+  }
+  if (a === 127) {
+    return true;
+  }
+  if (a === 10) {
+    return true;
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true;
+  }
+  if (a === 192 && b === 168) {
+    return true;
+  }
+  if (a === 169 && b === 254) {
+    return true;
+  }
+  if (a === 0 && b === 0 && octets[2] === 0 && octets[3] === 0) {
+    return true;
+  }
+  return false;
+}
+function isBlockedIpv6(host) {
+  const h = host.split("%")[0]?.toLowerCase() ?? host.toLowerCase();
+  if (h === "::1") {
+    return true;
+  }
+  if (h.startsWith("fe80:")) {
+    return true;
+  }
+  if (h.startsWith("fc") || h.startsWith("fd")) {
+    return true;
+  }
+  return false;
+}
+function hostForValidation(hostname3) {
+  if (hostname3.startsWith("[") && hostname3.endsWith("]")) {
+    return hostname3.slice(1, -1);
+  }
+  return hostname3;
+}
+function assertSafeProxyUrl(raw, options) {
+  let url2;
+  try {
+    url2 = new URL(raw);
+  } catch {
+    throw new ProxyUrlValidationError(`Invalid proxy URL: ${raw}`);
+  }
+  if (url2.protocol !== "https:" && url2.protocol !== "http:") {
+    throw new ProxyUrlValidationError(
+      `Unsupported proxy URL scheme: ${url2.protocol} - only https: and http: are allowed`
+    );
+  }
+  const hostname3 = url2.hostname;
+  if (hostname3.length === 0) {
+    throw new ProxyUrlValidationError(`Proxy URL has no hostname: ${raw}`);
+  }
+  if (options?.allowPrivateNetworks === true) {
+    return;
+  }
+  const host = hostForValidation(hostname3);
+  if (host.toLowerCase() === "localhost") {
+    throw new ProxyUrlValidationError(
+      `Proxy URL points to a private/reserved network address: ${url2.hostname}`
+    );
+  }
+  if (host.includes(":")) {
+    if (isBlockedIpv6(host)) {
+      throw new ProxyUrlValidationError(
+        `Proxy URL points to a private/reserved network address: ${url2.hostname}`
+      );
+    }
+    return;
+  }
+  if (isPrivateOrReservedIpv4(host)) {
+    throw new ProxyUrlValidationError(
+      `Proxy URL points to a private/reserved network address: ${url2.hostname}`
+    );
+  }
+}
+
 // src/extension/proxy-client.ts
 var MCP_PROTOCOL_VERSION = "2024-11-05";
 var ProxyConfigFetchError = class extends Error {
@@ -22404,8 +22510,12 @@ function isProxyConfigRow(v) {
   const o = v;
   return typeof o["proxy_url"] === "string" && o["proxy_url"].length > 0 && typeof o["server_name"] === "string" && typeof o["target_url"] === "string";
 }
-async function fetchProxyConfigs(baseUrl, apiKey, timeoutMs) {
+async function fetchProxyConfigs(baseUrl, apiKey, timeoutMs, options) {
   const url2 = `${normalizeBaseUrl(baseUrl)}/api/v1/proxy/config`;
+  assertSafeProxyUrl(
+    url2,
+    options?.allowPrivateNetworks === true ? { allowPrivateNetworks: true } : void 0
+  );
   let response;
   try {
     response = await fetch(url2, {
@@ -22563,6 +22673,10 @@ var ProxySession = class {
     this.nextId = 1;
     this.sessionId = null;
     this.closed = false;
+    assertSafeProxyUrl(
+      proxyUrl,
+      options?.allowPrivateNetworks === true ? { allowPrivateNetworks: true } : void 0
+    );
     this.proxyUrl = proxyUrl.replace(/\/+$/, "") + "/mcp";
     this.apiKey = apiKey;
     this.requestTimeoutMs = options?.requestTimeoutMs ?? 6e4;
@@ -23554,6 +23668,8 @@ async function autoCreateProxyConfig(baseUrl, apiKey, serverName, entry, agentNa
   const targetUrl = `stdio://${entry.command}/${entry.args.join("/")}`;
   const url2 = `${baseUrl.replace(/\/+$/, "")}/api/v1/proxy/config`;
   debugLog2(`[SHIELD] Auto-creating proxy config for "${serverName}".`);
+  const allowPrivateNetworks = process.env["MULTICORN_ALLOW_PRIVATE_PROXY_HOSTS"] === "1";
+  assertSafeProxyUrl(url2, { allowPrivateNetworks });
   let response;
   try {
     response = await fetch(url2, {
@@ -23589,9 +23705,6 @@ async function autoCreateProxyConfig(baseUrl, apiKey, serverName, entry, agentNa
   return true;
 }
 async function runShieldExtension() {
-  const debugBaseUrl = process.env["MULTICORN_BASE_URL"] ?? "";
-  const debugApiKeyPrefix = process.env["MULTICORN_API_KEY"]?.slice(0, 8) ?? "";
-  console.error(`[SHIELD-DEBUG] BASE_URL=${debugBaseUrl} API_KEY=${debugApiKeyPrefix}...`);
   const logger = createLogger(readLogLevel());
   const apiKey = readApiKey();
   if (apiKey === null) {
@@ -23686,6 +23799,7 @@ async function runShieldExtension() {
         `[SHIELD] Config read; ${String(serverCount)} MCP server(s) discovered (excluding Shield).`
       );
       debugLog2("[SHIELD] Resolving proxy configs (local config or API).");
+      const allowPrivateNetworks = process.env["MULTICORN_ALLOW_PRIVATE_PROXY_HOSTS"] === "1";
       let configs;
       const localConfigs = await readProxyConfigsFromLocalMulticornConfig();
       if (localConfigs.length > 0) {
@@ -23694,7 +23808,9 @@ async function runShieldExtension() {
       } else {
         debugLog2("[SHIELD] No local proxy configs; fetching from API.");
         try {
-          configs = await fetchProxyConfigs(baseUrl, apiKey, SETUP_TIMEOUT_MS);
+          configs = await fetchProxyConfigs(baseUrl, apiKey, SETUP_TIMEOUT_MS, {
+            allowPrivateNetworks
+          });
         } catch (e) {
           clearTimeout(setupTimeout);
           if (e instanceof ProxyConfigFetchError) {
@@ -23728,7 +23844,9 @@ async function runShieldExtension() {
               `[SHIELD] Auto-created ${String(createdCount)} proxy config(s); re-fetching from API.`
             );
             try {
-              configs = await fetchProxyConfigs(baseUrl, apiKey, SETUP_TIMEOUT_MS);
+              configs = await fetchProxyConfigs(baseUrl, apiKey, SETUP_TIMEOUT_MS, {
+                allowPrivateNetworks
+              });
             } catch (e) {
               const message = e instanceof Error ? e.message : String(e);
               debugLog2(`[SHIELD] Re-fetch after auto-creation failed: ${message}`);
@@ -23766,7 +23884,7 @@ async function runShieldExtension() {
       const toolsByProxy = /* @__PURE__ */ new Map();
       const sessionByProxyUrl = /* @__PURE__ */ new Map();
       for (const cfg of configs) {
-        const session = new ProxySession(cfg.proxy_url, apiKey);
+        const session = new ProxySession(cfg.proxy_url, apiKey, { allowPrivateNetworks });
         try {
           debugLog2(`[SHIELD] Initializing proxy session for ${cfg.server_name}.`);
           await session.initialize();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "author": "Multicorn AI Pty Ltd",
@@ -37,6 +37,7 @@
   "files": [
     "dist",
     "plugins/windsurf",
+    "plugins/cline",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"
@@ -45,13 +46,18 @@
     "access": "public",
     "provenance": true
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "dist/index.js",
+    "dist/index.cjs",
+    "dist/badge.js",
+    "src/badge/multicorn-badge.ts"
+  ],
   "engines": {
     "node": ">=20"
   },
   "lint-staged": {
     "*.ts": [
-      "eslint --fix",
+      "eslint --fix --no-warn-ignored",
       "prettier --write"
     ],
     "*.{json,md}": [
@@ -69,7 +75,7 @@
     "@open-wc/testing-helpers": "^3.0.1",
     "@size-limit/file": "^11.1.6",
     "@types/node": "^22.0.0",
-    "@vitest/coverage-istanbul": "^3.0.5",
+    "@vitest/coverage-v8": "^3.0.5",
     "eslint": "^9.19.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-unicorn": "^57.0.0",
@@ -97,6 +103,11 @@
       "path": "dist/index.cjs",
       "limit": "50 kB",
       "gzip": true
+    },
+    {
+      "path": "dist/badge.js",
+      "limit": "5 kB",
+      "gzip": true
     }
   ],
   "keywords": [
@@ -123,8 +134,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "lint": "eslint . && prettier --check .",
-    "lint:fix": "eslint --fix . && prettier --write .",
+    "lint": "eslint . --no-warn-ignored && prettier --check .",
+    "lint:fix": "eslint --fix . --no-warn-ignored && prettier --write .",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

package/plugins/cline/README.md

@@ -0,0 +1,61 @@
+# Multicorn Shield Cline plugin
+
+This folder ships **Shield hooks for the [Cline](https://github.com/cline/cline) VS Code extension**. The PreToolUse script asks Shield whether a pending tool call is allowed; the PostToolUse script records completed actions in the Shield audit trail.
+
+## Prerequisites
+
+- **Node.js** 20 or newer (hooks run as standalone Node scripts).
+- **Cline** v3.36 or newer with **Hooks** enabled in settings.
+
+Keep these three scripts together whenever you install by hand:
+
+- `hooks/scripts/pre-tool-use.cjs`
+- `hooks/scripts/post-tool-use.cjs`
+- `hooks/scripts/shared.cjs`
+
+## Installing the hooks
+
+**CLI (recommended):** run `npx multicorn-shield init` and follow prompts so the scripts are copied into Cline's hooks directory.
+
+**Manual:** copy the `hooks/scripts/` `.cjs` files into:
+
+`~/Documents/Cline/Hooks/`
+
+(or the equivalent Hooks path on your machine). Cline runs each hook with stdin JSON from its Hooks API.
+
+## Config file
+
+Path: **`~/.multicorn/config.json`**
+
+| Field     | Required | Description                                                                                                                                                                               |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`  | yes      | Multicorn API key used in the Shield request (`X-Multicorn-Key`).                                                                                                                         |
+| `baseUrl` | no       | API root. Defaults to `https://api.multicorn.ai` (no trailing slash). Non-local URLs must use `https://` or the hooks disable Shield (fail-open). `localhost` / `127.0.0.1` may use HTTP. |
+| `agents`  | no       | Array of `{ "name": "...", "platform": "cline" }` objects so the hooks know which Shield agent name to use. Legacy `agentName` string is still read if present.                           |
+
+Example:
+
+```json
+{
+  "apiKey": "mcs_your_key_here",
+  "baseUrl": "https://api.multicorn.ai",
+  "agents": [{ "name": "my-repo-agent", "platform": "cline" }]
+}
+```
+
+## How it works
+
+1. **PreToolUse:** before Cline runs a tool, stdin carries the pending request. The script maps the tool name to a Shield **service** and **actionType**, POSTs `status: pending` to `/api/v1/actions`, and reads the response. It either allows the tool (`cancel: false`) or blocks with an error message and optional consent workflow.
+2. **PostToolUse:** after the tool completes, stdin includes the outcome. The script POSTs `status: approved` with metadata (scrubbed parameters and result) so the audit log stays usable without stuffing large secrets into the payload.
+
+Both hooks reply with JSON on stdout. The post-hook always finishes with `{ "cancel": false }`.
+
+## Security model
+
+Shield wiring is **fail-open by design**. If config is missing, invalid for remote HTTP, or the API errors or times out, **actions are allowed** so work is not silently blocked because Shield is down. Deployers treat Shield as governance and auditing, not as a cryptographic boundary against a hostile process on the same machine.
+
+## Troubleshooting
+
+1. **Confirm hooks run:** temporarily add stderr output (not recommended long term), or tail Cline's hook output/logs if exposed. Successful runs should not spam the developer console unless there is an API warning.
+2. **Nothing reaches Shield:** check `config.json` path and `apiKey`, that `agents` includes `platform: "cline"` with the right `name`, and that `baseUrl` uses HTTPS on non-local installs.
+3. **Windows consent / browser:** the pre-hook opens the consent URL via `cmd.exe start`; if that fails, open the URL from the blocking message manually.

package/plugins/cline/hooks/scripts/post-tool-use.cjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Copyright (c) Multicorn AI Pty Ltd. MIT License. See LICENSE file.
+/**
+ * Cline PostToolUse hook: logs completed actions to the Shield audit trail.
+ * Reads JSON from stdin (Cline Hooks API), posts to Shield API.
+ * Always returns {"cancel": false} - post hooks never block.
+ */
+
+"use strict";
+
+const {
+  buildScrubbedParametersJson,
+  loadConfig,
+  logPrefix,
+  mapToolName,
+  postJson,
+  readStdin,
+  scrubResultForMetadata,
+} = require("./shared.cjs");
+
+const HOOK_PREFIX = logPrefix("post-hook");
+
+/**
+ * Outputs JSON response to stdout and exits.
+ */
+function respond() {
+  process.stdout.write(JSON.stringify({ cancel: false }) + "\n");
+  process.exit(0);
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch {
+    respond();
+    return;
+  }
+
+  const config = loadConfig();
+  if (config === null || config.apiKey.length === 0 || config.agentName.length === 0) {
+    respond();
+    return;
+  }
+
+  /** @type {Record<string, unknown>} */
+  let hookPayload;
+  try {
+    hookPayload = JSON.parse(raw.length > 0 ? raw : "{}");
+  } catch {
+    respond();
+    return;
+  }
+
+  const postToolUse = hookPayload.postToolUse;
+  if (postToolUse === null || typeof postToolUse !== "object") {
+    respond();
+    return;
+  }
+
+  const toolUse = /** @type {Record<string, unknown>} */ (postToolUse);
+  const toolName = typeof toolUse.tool === "string" ? toolUse.tool : "";
+
+  if (toolName.length === 0) {
+    respond();
+    return;
+  }
+
+  const { service, actionType } = mapToolName(toolName);
+
+  const paramsSerialized = buildScrubbedParametersJson(toolUse.parameters);
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    tool_name: toolName,
+    task_id: typeof hookPayload.taskId === "string" ? hookPayload.taskId : "",
+    cline_version: typeof hookPayload.clineVersion === "string" ? hookPayload.clineVersion : "",
+    parameters: paramsSerialized,
+    result: scrubResultForMetadata(toolUse.result),
+    timing: typeof toolUse.timing === "object" ? JSON.stringify(toolUse.timing) : "",
+    source: "cline",
+  };
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    agent: config.agentName,
+    service,
+    actionType,
+    status: "approved",
+    metadata,
+    platform: "cline",
+  };
+
+  try {
+    const res = await postJson(config.baseUrl, config.apiKey, payload);
+    const code = res.statusCode ?? 0;
+    if (code < 200 || code >= 300) {
+      throw new Error(`HTTP ${String(code)}`);
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `${HOOK_PREFIX} Warning: failed to log action to Shield audit trail. Detail: ${msg}\n`,
+    );
+  }
+
+  respond();
+}
+
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(
+    `${HOOK_PREFIX} Warning: failed to log action to Shield audit trail. Detail: ${msg}\n`,
+  );
+  respond();
+});