multicorn-shield 0.2.0 → 0.2.2

package/dist/proxy.d.ts

@@ -0,0 +1,235 @@
+import { Writable } from 'node:stream';
+
+/**
+ * JSON-RPC message parsing and tool call interception for the MCP proxy.
+ *
+ * Handles the MCP stdio transport (newline-delimited JSON-RPC 2.0). Provides
+ * types, parsers, and response builders used by the proxy to intercept
+ * `tools/call` requests before they reach the wrapped MCP server.
+ *
+ * @module proxy/interceptor
+ */
+interface JsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly method: string;
+    readonly params?: unknown;
+}
+interface JsonRpcResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: JsonRpcError;
+}
+interface JsonRpcError {
+    readonly code: number;
+    readonly message: string;
+}
+interface ToolCallParams {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+declare function parseJsonRpcLine(line: string): JsonRpcRequest | null;
+declare function extractToolCallParams(request: JsonRpcRequest): ToolCallParams | null;
+declare function buildBlockedResponse(id: string | number | null, service: string, permissionLevel: string, dashboardUrl: string): JsonRpcResponse;
+declare function buildSpendingBlockedResponse(id: string | number | null, reason: string, dashboardUrl: string): JsonRpcResponse;
+/**
+ * Internal error: Shield could not verify permissions due to an exception.
+ * Use when the proxy hits an unhandled error (fail-closed).
+ */
+declare function buildInternalErrorResponse(id: string | number | null): JsonRpcResponse;
+/**
+ * Service unreachable: Shield could not verify permissions (DNS, network, timeout).
+ * Distinct code (-32003) so callers can tell apart from permission-denied (-32000).
+ */
+declare function buildServiceUnreachableResponse(id: string | number | null, dashboardUrl: string): JsonRpcResponse;
+/**
+ * API key invalid or revoked (401/403 from service).
+ * Distinct code (-32004) so callers can tell apart from permission-denied (-32000).
+ */
+declare function buildAuthErrorResponse(id: string | number | null): JsonRpcResponse;
+declare function extractServiceFromToolName(toolName: string): string;
+declare function extractActionFromToolName(toolName: string): string;
+
+/**
+ * Permission levels that can be granted on a service scope.
+ *
+ * - `read`: observe data without modification
+ * - `write`: create or modify data
+ * - `execute`: trigger side-effects (e.g. send an email, make a payment)
+ * - `publish`: make existing content publicly accessible (e.g. deploy, publish, make live)
+ * - `create`: create new content that is immediately public (e.g. tweet, public commit, forum post)
+ */
+declare const PERMISSION_LEVELS: {
+    readonly Read: "read";
+    readonly Write: "write";
+    readonly Execute: "execute";
+    readonly Publish: "publish";
+    readonly Create: "create";
+};
+type PermissionLevel = (typeof PERMISSION_LEVELS)[keyof typeof PERMISSION_LEVELS];
+/**
+ * A single permission scope binding a service to an access level.
+ *
+ * For example, `{ service: "gmail", permissionLevel: "write" }` grants
+ * write access to the Gmail integration.
+ */
+interface Scope {
+    readonly service: string;
+    readonly permissionLevel: PermissionLevel;
+}
+
+/**
+ * Structured JSON logger for the MCP proxy.
+ *
+ * Writes to stderr only. Stdout is reserved for the MCP JSON-RPC transport.
+ * Log output is newline-delimited JSON so it can be parsed by log aggregators.
+ *
+ * @module proxy/logger
+ */
+
+declare const LOG_LEVELS: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+};
+type LogLevel = keyof typeof LOG_LEVELS;
+interface ProxyLogger {
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+}
+declare function createLogger(level: LogLevel, output?: Writable): ProxyLogger;
+declare function isValidLogLevel(value: unknown): value is LogLevel;
+
+/**
+ * Agent registration, scope fetching, consent flow, and scope caching.
+ *
+ * Handles the full lifecycle of connecting a proxy to the Multicorn service:
+ * finding or creating an agent record, fetching its granted scopes, and
+ * triggering the browser consent flow when the agent has no scopes yet.
+ *
+ * Scopes are cached in `~/.multicorn/scopes.json` for offline resilience
+ * and refreshed from the service every 60 seconds while the proxy runs.
+ * Cache is account-aware (keyed by agent name + API key).
+ *
+ * @module proxy/consent
+ */
+
+/**
+ * Derives the dashboard URL from the API base URL.
+ * - http://localhost:8080 -> http://localhost:5173
+ * - https://api.multicorn.ai -> https://app.multicorn.ai
+ * - Other URLs: replace "api" with "app" in the hostname, or use default
+ */
+declare function deriveDashboardUrl(baseUrl: string): string;
+/**
+ * Thrown when the Shield API returns 401 or 403 (API key invalid or revoked).
+ * Used so resolveAgentRecord can detect auth failure without ad-hoc property casts.
+ */
+declare class ShieldAuthError extends Error {
+    constructor(message: string);
+}
+interface AgentRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly scopes: readonly Scope[];
+    /** Set when the service returned 401/403; proxy must block with auth error message. */
+    readonly authInvalid?: boolean;
+}
+
+declare function findAgentByName(agentName: string, apiKey: string, baseUrl: string): Promise<AgentRecord | null>;
+declare function registerAgent(agentName: string, apiKey: string, baseUrl: string, platform?: string): Promise<string>;
+declare function fetchGrantedScopes(agentId: string, apiKey: string, baseUrl: string): Promise<readonly Scope[]>;
+
+/**
+ * Scope validation engine.
+ *
+ * Given a set of granted scopes and a requested action, determines whether
+ * the action is permitted. Returns a structured result with a human-readable
+ * reason when access is denied. No silent failures, no implicit grants.
+ *
+ * **Design principle (Jordan persona):** Every permission must be explicitly
+ * granted. `read` does **not** imply `write`; `write` does **not** imply
+ * `execute`. There is no wildcard or superuser bypass.
+ *
+ * @module scopes/scope-validator
+ */
+
+/**
+ * The outcome of a scope validation check.
+ *
+ * - When `allowed` is `true`, no `reason` is present.
+ * - When `allowed` is `false`, `reason` contains a descriptive explanation
+ *   of why the action was denied.
+ *
+ * @example
+ * ```ts
+ * const result = validateScopeAccess(granted, requested);
+ * if (!result.allowed) {
+ *   console.warn(`Denied: ${result.reason}`);
+ * }
+ * ```
+ */
+interface ValidationResult {
+    /** Whether the requested action is permitted by the granted scopes. */
+    readonly allowed: boolean;
+    /**
+     * Human-readable explanation of why the action was denied.
+     * Only present when `allowed` is `false`.
+     */
+    readonly reason?: string;
+}
+/**
+ * Check whether a single requested scope is covered by the granted set.
+ *
+ * Matching is **exact**: the granted set must contain an entry with the
+ * same `service` **and** `permissionLevel`. No implicit escalation is
+ * performed (e.g. `write` does not subsume `read`).
+ *
+ * @param grantedScopes - The scopes the agent has been granted via consent.
+ * @param requested - The scope required by the action the agent wants to perform.
+ * @returns A {@link ValidationResult} indicating whether access is allowed.
+ *
+ * @example
+ * ```ts
+ * const granted = [
+ *   { service: "gmail", permissionLevel: "read" },
+ *   { service: "gmail", permissionLevel: "write" },
+ * ];
+ *
+ * validateScopeAccess(granted, { service: "gmail", permissionLevel: "read" });
+ * // → { allowed: true }
+ *
+ * validateScopeAccess(granted, { service: "gmail", permissionLevel: "execute" });
+ * // → { allowed: false, reason: "Permission \"execute\" is not granted …" }
+ *
+ * validateScopeAccess(granted, { service: "slack", permissionLevel: "read" });
+ * // → { allowed: false, reason: "No permissions granted for service \"slack\" …" }
+ * ```
+ */
+declare function validateScopeAccess(grantedScopes: readonly Scope[], requested: Scope): ValidationResult;
+
+/**
+ * Maps MCP tool names (stdio servers, Claude Desktop) to Shield service and permission level.
+ *
+ * Uses explicit tables for common MCP servers (filesystem, terminal, browser) and the same
+ * integration-style prefix rules as OpenClaw's tool-mapper for names like `gmail_send_email`.
+ *
+ * @module mcp-tool-mapper
+ */
+
+interface McpToolScopeMapping {
+    readonly service: string;
+    readonly permissionLevel: PermissionLevel;
+    /** Original tool name for audit logs. */
+    readonly actionType: string;
+}
+/**
+ * Maps an MCP `tools/call` tool name to Shield `service` + `permissionLevel` for scope checks.
+ */
+declare function mapMcpToolToScope(toolName: string): McpToolScopeMapping;
+
+export { type AgentRecord, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LogLevel, type ProxyLogger, ShieldAuthError, type ToolCallParams, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };

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 };