multicorn-shield 0.2.1 → 0.4.0

package/dist/proxy.js

@@ -0,0 +1,438 @@
+import 'child_process';
+import 'stream';
+
+// 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;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  return isJsonRpcRequest(parsed) ? parsed : null;
+}
+function extractToolCallParams(request) {
+  if (request.method !== "tools/call") return null;
+  if (typeof request.params !== "object" || request.params === null) return null;
+  const params = request.params;
+  const name = params["name"];
+  const args = params["arguments"];
+  if (typeof name !== "string") return null;
+  if (typeof args !== "object" || args === null) return null;
+  return { name, arguments: args };
+}
+function buildBlockedResponse(id, service, permissionLevel, dashboardUrl) {
+  const displayService = capitalize(service);
+  const message = `Action blocked by Multicorn Shield: agent does not have ${permissionLevel} access to ${displayService}. Configure permissions at ${dashboardUrl}`;
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: BLOCKED_ERROR_CODE,
+      message
+    }
+  };
+}
+function buildSpendingBlockedResponse(id, reason, dashboardUrl) {
+  const message = `Action blocked by Multicorn Shield: ${reason}. Review spending limits at ${dashboardUrl}`;
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: SPENDING_BLOCKED_ERROR_CODE,
+      message
+    }
+  };
+}
+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);
+}
+function extractActionFromToolName(toolName) {
+  const idx = toolName.indexOf("_");
+  return idx === -1 ? "call" : toolName.slice(idx + 1);
+}
+function isJsonRpcRequest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  if (obj["jsonrpc"] !== "2.0") return false;
+  if (typeof obj["method"] !== "string") return false;
+  const id = obj["id"];
+  const validId = id === null || id === void 0 || typeof id === "string" || typeof id === "number";
+  return validId;
+}
+function capitalize(str) {
+  if (str.length === 0) return str;
+  const first = str[0];
+  return first !== void 0 ? first.toUpperCase() + str.slice(1) : str;
+}
+function deriveDashboardUrl(baseUrl) {
+  try {
+    const url = new URL(baseUrl);
+    if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+      url.port = "5173";
+      url.protocol = "http:";
+      return url.toString();
+    }
+    if (url.hostname === "api.multicorn.ai") {
+      url.hostname = "app.multicorn.ai";
+      return url.toString();
+    }
+    if (url.hostname.includes("api")) {
+      url.hostname = url.hostname.replace("api", "app");
+      return url.toString();
+    }
+    if (url.protocol === "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+      return "https://app.multicorn.ai";
+    }
+    return "https://app.multicorn.ai";
+  } catch {
+    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 findAgentByName(agentName, apiKey, baseUrl) {
+  let response;
+  try {
+    response = await fetch(`${baseUrl}/api/v1/agents`, {
+      headers: { "X-Multicorn-Key": apiKey },
+      signal: AbortSignal.timeout(8e3)
+    });
+  } catch {
+    return null;
+  }
+  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;
+  const match = agents.find(
+    (a) => isAgentSummaryShape(a) && a.name === agentName
+  );
+  if (match === void 0) return null;
+  return { id: match.id, name: match.name, scopes: [] };
+}
+async function registerAgent(agentName, apiKey, baseUrl, platform) {
+  const response = await fetch(`${baseUrl}/api/v1/agents`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Multicorn-Key": apiKey
+    },
+    body: JSON.stringify({ name: agentName, ...platform ? { platform } : {} }),
+    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)}.`
+    );
+  }
+  const body = await response.json();
+  if (!isApiSuccessResponse(body)) {
+    throw new Error(`Failed to register agent "${agentName}": unexpected response format.`);
+  }
+  if (!isAgentSummaryShape(body.data)) {
+    throw new Error(`Failed to register agent "${agentName}": response missing agent ID.`);
+  }
+  return body.data.id;
+}
+async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
+  let response;
+  try {
+    response = await fetch(`${baseUrl}/api/v1/agents/${agentId}`, {
+      headers: { "X-Multicorn-Key": apiKey },
+      signal: AbortSignal.timeout(8e3)
+    });
+  } catch {
+    return [];
+  }
+  if (!response.ok) return [];
+  const body = await response.json();
+  if (!isApiSuccessResponse(body)) return [];
+  const agentDetail = body.data;
+  if (!isAgentDetailShape(agentDetail)) return [];
+  const scopes = [];
+  for (const perm of agentDetail.permissions) {
+    if (!isPermissionShape(perm)) continue;
+    if (perm.revoked_at !== null) continue;
+    if (perm.read) scopes.push({ service: perm.service, permissionLevel: "read" });
+    if (perm.write) scopes.push({ service: perm.service, permissionLevel: "write" });
+    if (perm.execute) scopes.push({ service: perm.service, permissionLevel: "execute" });
+  }
+  return scopes;
+}
+function isApiSuccessResponse(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return obj["success"] === true;
+}
+function isAgentSummaryShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["id"] === "string" && typeof obj["name"] === "string";
+}
+function isAgentDetailShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return Array.isArray(obj["permissions"]);
+}
+function isPermissionShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["service"] === "string" && typeof obj["read"] === "boolean" && typeof obj["write"] === "boolean" && typeof obj["execute"] === "boolean" && (obj["revoked_at"] === null || obj["revoked_at"] === void 0 || typeof obj["revoked_at"] === "string");
+}
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+function createLogger(level, output = process.stderr) {
+  const minLevel = LOG_LEVELS[level];
+  function write(logLevel, msg, data) {
+    if (LOG_LEVELS[logLevel] < minLevel) return;
+    const entry = {
+      level: logLevel,
+      time: (/* @__PURE__ */ new Date()).toISOString(),
+      msg,
+      ...data
+    };
+    output.write(JSON.stringify(entry) + "\n");
+  }
+  return {
+    debug: (msg, data) => {
+      write("debug", msg, data);
+    },
+    info: (msg, data) => {
+      write("info", msg, data);
+    },
+    warn: (msg, data) => {
+      write("warn", msg, data);
+    },
+    error: (msg, data) => {
+      write("error", msg, data);
+    }
+  };
+}
+function isValidLogLevel(value) {
+  return typeof value === "string" && Object.hasOwn(LOG_LEVELS, value);
+}
+
+// src/types/index.ts
+var PERMISSION_LEVELS = {
+  Read: "read",
+  Write: "write",
+  Execute: "execute",
+  Publish: "publish",
+  Create: "create"
+};
+
+// src/scopes/scope-parser.ts
+var VALID_PERMISSION_LEVELS = new Set(Object.values(PERMISSION_LEVELS));
+[...VALID_PERMISSION_LEVELS].join(", ");
+function formatScope(scope) {
+  return `${scope.permissionLevel}:${scope.service}`;
+}
+
+// src/scopes/scope-validator.ts
+function validateScopeAccess(grantedScopes, requested) {
+  const isGranted = grantedScopes.some(
+    (granted) => granted.service === requested.service && granted.permissionLevel === requested.permissionLevel
+  );
+  if (isGranted) {
+    return { allowed: true };
+  }
+  const serviceScopes = grantedScopes.filter((g) => g.service === requested.service);
+  if (serviceScopes.length > 0) {
+    const grantedLevels = serviceScopes.map((g) => `"${g.permissionLevel}"`).join(", ");
+    return {
+      allowed: false,
+      reason: `Permission "${requested.permissionLevel}" is not granted for service "${requested.service}". Currently granted permission level(s): ${grantedLevels}. Requested scope "${formatScope(requested)}" requires explicit consent.`
+    };
+  }
+  return {
+    allowed: false,
+    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.`
+  };
+}
+
+// src/mcp-tool-mapper.ts
+var FILESYSTEM_READ_TOOLS = /* @__PURE__ */ new Set([
+  "read_file",
+  "read_text_file",
+  "read_media_file",
+  "read_multiple_files",
+  "list_directory",
+  "list_dir",
+  "directory_tree",
+  "tree",
+  "get_file_info",
+  "stat",
+  "search_files",
+  "glob_file_search",
+  "list_allowed_directories",
+  "file_search"
+]);
+var FILESYSTEM_WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "write_file",
+  "edit_file",
+  "create_directory",
+  "mkdir",
+  "move_file",
+  "rename",
+  "delete_file",
+  "remove_file",
+  "copy_file"
+]);
+var TERMINAL_EXECUTE_TOOLS = /* @__PURE__ */ new Set([
+  "run_terminal_cmd",
+  "execute_command",
+  "terminal_run",
+  "run_command"
+]);
+var BROWSER_EXECUTE_TOOLS = /* @__PURE__ */ new Set([
+  "web_fetch",
+  "fetch_url",
+  "browser_navigate",
+  "navigate",
+  "mcp_web_fetch"
+]);
+var INTEGRATION_SERVICE_BY_PREFIX = {
+  gmail: "gmail",
+  google_calendar: "google_calendar",
+  calendar: "google_calendar",
+  google_drive: "google_drive",
+  drive: "google_drive",
+  slack: "slack",
+  payments: "payments",
+  payment: "payments",
+  stripe: "payments",
+  github: "github",
+  gitlab: "gitlab",
+  notion: "notion",
+  linear: "linear",
+  jira: "jira"
+};
+function inferPermissionFromToolName(normalized) {
+  if (normalized.includes("_read") || normalized.includes("_get") || normalized.includes("_list") || normalized.endsWith("_fetch") || normalized.includes("_search")) {
+    return "read";
+  }
+  if (normalized.includes("_write") || normalized.includes("_send") || normalized.includes("_create") || normalized.includes("_update") || normalized.includes("_delete") || normalized.includes("_push") || normalized.includes("_commit") || normalized.includes("_post") || normalized.includes("_patch")) {
+    return "write";
+  }
+  return "execute";
+}
+function mapMcpToolToScope(toolName) {
+  const actionType = toolName.trim();
+  const normalized = actionType.toLowerCase();
+  if (normalized.length === 0) {
+    return { service: "unknown", permissionLevel: "execute", actionType };
+  }
+  if (FILESYSTEM_READ_TOOLS.has(normalized)) {
+    return { service: "filesystem", permissionLevel: "read", actionType };
+  }
+  if (FILESYSTEM_WRITE_TOOLS.has(normalized)) {
+    return { service: "filesystem", permissionLevel: "write", actionType };
+  }
+  if (TERMINAL_EXECUTE_TOOLS.has(normalized)) {
+    return { service: "terminal", permissionLevel: "execute", actionType };
+  }
+  if (BROWSER_EXECUTE_TOOLS.has(normalized)) {
+    return { service: "browser", permissionLevel: "execute", actionType };
+  }
+  if (normalized === "read") {
+    return { service: "filesystem", permissionLevel: "read", actionType };
+  }
+  if (normalized === "write" || normalized === "edit") {
+    return { service: "filesystem", permissionLevel: "write", actionType };
+  }
+  if (normalized === "exec") {
+    return { service: "terminal", permissionLevel: "execute", actionType };
+  }
+  if (normalized.startsWith("git_")) {
+    const permissionLevel2 = inferPermissionFromToolName(normalized);
+    return { service: "git", permissionLevel: permissionLevel2, actionType };
+  }
+  for (const [prefix, service] of Object.entries(INTEGRATION_SERVICE_BY_PREFIX)) {
+    if (normalized.startsWith(`${prefix}_`) || normalized === prefix) {
+      const permissionLevel2 = inferPermissionFromToolName(normalized);
+      return { service, permissionLevel: permissionLevel2, actionType };
+    }
+  }
+  const idx = normalized.indexOf("_");
+  if (idx === -1) {
+    return { service: normalized, permissionLevel: "execute", actionType };
+  }
+  const head = normalized.slice(0, idx);
+  const tail = normalized.slice(idx + 1);
+  let permissionLevel = "execute";
+  if (tail.includes("read") || tail.includes("list") || tail.includes("get") || tail.includes("search") || tail.includes("fetch")) {
+    permissionLevel = "read";
+  } else if (tail.includes("write") || tail.includes("send") || tail.includes("create") || tail.includes("update") || tail.includes("delete") || tail.includes("remove")) {
+    permissionLevel = "write";
+  }
+  return { service: head, permissionLevel, actionType };
+}
+
+export { ShieldAuthError, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };