multicorn-shield 0.1.0

package/dist/openclaw-hook/HOOK.md

@@ -0,0 +1,75 @@
+---
+name: multicorn-shield
+description: "Multicorn Shield governance for OpenClaw. Checks permissions, logs actions, and enforces controls via the Shield API."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "shield",
+        "events": ["agent:tool_call"],
+        "requires": { "env": ["MULTICORN_API_KEY"] },
+        "primaryEnv": "MULTICORN_API_KEY",
+      },
+  }
+---
+
+# Multicorn Shield (Gateway Hook - Deprecated)
+
+> **This gateway hook is deprecated.** Gateway hooks cannot intercept tool calls.
+> Use the **Plugin API** version instead:
+>
+> ```bash
+> cd multicorn-shield && npm run build
+> openclaw plugins install --link ./dist/openclaw-plugin/index.js
+> openclaw plugins enable multicorn-shield
+> openclaw gateway restart
+> ```
+>
+> 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.
+
+## What it does
+
+- Checks every tool call (read, write, exec, browser, message) against your Shield permissions
+- Blocks tools you haven't granted access to, with a clear message to the agent
+- Opens the Shield consent page in your browser on first use
+- Logs all activity to the Shield dashboard (fire-and-forget, doesn't slow down the agent)
+
+## Setup (Deprecated - use the plugin instead)
+
+```bash
+# 1. Copy the hook
+cp -r multicorn-shield ~/.openclaw/hooks/
+
+# 2. Set your API key
+export MULTICORN_API_KEY=mcs_your_key_here
+
+# 3. Enable it
+openclaw hooks enable multicorn-shield
+
+# 4. Restart the gateway
+openclaw gateway restart
+```
+
+## Environment variables
+
+| Variable             | Required | Default                  | Description                                                                   |
+| -------------------- | -------- | ------------------------ | ----------------------------------------------------------------------------- |
+| MULTICORN_API_KEY    | Yes      | -                        | Your Multicorn API key (starts with `mcs_`)                                   |
+| MULTICORN_BASE_URL   | No       | https://api.multicorn.ai | Shield API base URL                                                           |
+| MULTICORN_AGENT_NAME | No       | Derived from session     | Override the agent name shown in the dashboard                                |
+| MULTICORN_FAIL_MODE  | No       | open                     | `open` = allow tool calls when the API is unreachable. `closed` = block them. |
+
+## How permissions map
+
+| OpenClaw tool  | Shield permission |
+| -------------- | ----------------- |
+| read           | filesystem:read   |
+| write, edit    | filesystem:write  |
+| exec, process  | terminal:execute  |
+| browser        | browser:execute   |
+| message        | messaging:write   |
+| sessions_spawn | agents:execute    |
+
+Tools not in this list are tracked under their own name with `execute` permission.

package/dist/openclaw-hook/handler.js

@@ -0,0 +1,447 @@
+import { readFile, mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { spawn } from 'child_process';
+
+// Multicorn Shield hook for OpenClaw (DEPRECATED - use the plugin instead) - https://multicorn.ai
+
+// src/openclaw/types.ts
+function isToolCallEvent(event) {
+  if (event.type !== "agent" || event.action !== "tool_call") return false;
+  const ctx = event.context;
+  return typeof ctx["toolName"] === "string" && typeof ctx["toolArguments"] === "object" && ctx["toolArguments"] !== null;
+}
+
+// src/openclaw/tool-mapper.ts
+var TOOL_MAP = {
+  // OpenClaw built-in tools
+  read: { service: "filesystem", permissionLevel: "read" },
+  write: { service: "filesystem", permissionLevel: "write" },
+  edit: { service: "filesystem", permissionLevel: "write" },
+  exec: { service: "terminal", permissionLevel: "execute" },
+  browser: { service: "browser", permissionLevel: "execute" },
+  message: { service: "messaging", permissionLevel: "write" },
+  process: { service: "terminal", permissionLevel: "execute" },
+  sessions_spawn: { service: "agents", permissionLevel: "execute" },
+  // Common integration tools (MCP servers, skills, etc.)
+  // Gmail
+  gmail: { service: "gmail", permissionLevel: "execute" },
+  gmail_send: { service: "gmail", permissionLevel: "write" },
+  gmail_read: { service: "gmail", permissionLevel: "read" },
+  // Google Calendar
+  google_calendar: { service: "google_calendar", permissionLevel: "execute" },
+  calendar: { service: "google_calendar", permissionLevel: "execute" },
+  calendar_create: { service: "google_calendar", permissionLevel: "write" },
+  calendar_read: { service: "google_calendar", permissionLevel: "read" },
+  // Google Drive
+  google_drive: { service: "google_drive", permissionLevel: "execute" },
+  drive: { service: "google_drive", permissionLevel: "execute" },
+  drive_read: { service: "google_drive", permissionLevel: "read" },
+  drive_write: { service: "google_drive", permissionLevel: "write" },
+  // Slack
+  slack: { service: "slack", permissionLevel: "execute" },
+  slack_send: { service: "slack", permissionLevel: "write" },
+  slack_read: { service: "slack", permissionLevel: "read" },
+  slack_message: { service: "slack", permissionLevel: "write" },
+  // Payments
+  payments: { service: "payments", permissionLevel: "execute" },
+  payment: { service: "payments", permissionLevel: "execute" },
+  stripe: { service: "payments", permissionLevel: "execute" }
+};
+function mapToolToScope(toolName, command) {
+  const normalized = toolName.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return { service: "unknown", permissionLevel: "execute" };
+  }
+  const known = TOOL_MAP[normalized];
+  if (known !== void 0) {
+    return known;
+  }
+  const integrationPrefixes = {
+    gmail: "gmail",
+    google_calendar: "google_calendar",
+    calendar: "google_calendar",
+    google_drive: "google_drive",
+    drive: "google_drive",
+    slack: "slack",
+    payments: "payments",
+    payment: "payments",
+    stripe: "payments"
+  };
+  for (const [prefix, service] of Object.entries(integrationPrefixes)) {
+    if (normalized.startsWith(prefix + "_") || normalized === prefix) {
+      let permissionLevel = "execute";
+      if (normalized.includes("_read") || normalized.includes("_get") || normalized.includes("_list")) {
+        permissionLevel = "read";
+      } else if (normalized.includes("_write") || normalized.includes("_send") || normalized.includes("_create") || normalized.includes("_update") || normalized.includes("_delete")) {
+        permissionLevel = "write";
+      }
+      return { service, permissionLevel };
+    }
+  }
+  return { service: normalized, permissionLevel: "execute" };
+}
+var MULTICORN_DIR = join(homedir(), ".multicorn");
+var SCOPES_PATH = join(MULTICORN_DIR, "scopes.json");
+async function loadCachedScopes(agentName) {
+  try {
+    const raw = await readFile(SCOPES_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isScopesCacheFile(parsed)) return null;
+    const entry = parsed[agentName];
+    return entry?.scopes ?? null;
+  } catch {
+    return null;
+  }
+}
+async function saveCachedScopes(agentName, agentId, scopes) {
+  await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
+  let existing = {};
+  try {
+    const raw = await readFile(SCOPES_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (isScopesCacheFile(parsed)) existing = parsed;
+  } catch {
+  }
+  const updated = {
+    ...existing,
+    [agentName]: {
+      agentId,
+      scopes,
+      fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  await writeFile(SCOPES_PATH, JSON.stringify(updated, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+function isScopesCacheFile(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/openclaw/shield-client.ts
+var REQUEST_TIMEOUT_MS = 5e3;
+var AUTH_HEADER = "X-Multicorn-Key";
+function isApiSuccess(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return obj["success"] === true;
+}
+function isAgentSummary(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["id"] === "string" && typeof obj["name"] === "string";
+}
+function isAgentDetail(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return Array.isArray(obj["permissions"]);
+}
+function isPermissionEntry(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 || typeof obj["revoked_at"] === "string");
+}
+async function findAgentByName(agentName, apiKey, baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/v1/agents`, {
+      headers: { [AUTH_HEADER]: apiKey },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    if (!isApiSuccess(body)) return null;
+    const agents = body.data;
+    if (!Array.isArray(agents)) return null;
+    const match = agents.find((a) => isAgentSummary(a) && a.name === agentName);
+    return match ?? null;
+  } catch {
+    return null;
+  }
+}
+async function registerAgent(agentName, apiKey, baseUrl) {
+  const response = await fetch(`${baseUrl}/api/v1/agents`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      [AUTH_HEADER]: apiKey
+    },
+    body: JSON.stringify({ name: agentName }),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
+    );
+  }
+  const body = await response.json();
+  if (!isApiSuccess(body) || !isAgentSummary(body.data)) {
+    throw new Error(`Failed to register agent "${agentName}": unexpected response format.`);
+  }
+  return body.data.id;
+}
+async function findOrRegisterAgent(agentName, apiKey, baseUrl) {
+  const existing = await findAgentByName(agentName, apiKey, baseUrl);
+  if (existing !== null) return existing;
+  try {
+    const id = await registerAgent(agentName, apiKey, baseUrl);
+    return { id, name: agentName };
+  } catch {
+    return null;
+  }
+}
+async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/v1/agents/${agentId}`, {
+      headers: { [AUTH_HEADER]: apiKey },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    if (!response.ok) return [];
+    const body = await response.json();
+    if (!isApiSuccess(body)) return [];
+    const detail = body.data;
+    if (!isAgentDetail(detail)) return [];
+    const scopes = [];
+    for (const perm of detail.permissions) {
+      if (!isPermissionEntry(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;
+  } catch {
+    return [];
+  }
+}
+async function logAction(payload, apiKey, baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/v1/actions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        [AUTH_HEADER]: apiKey
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      process.stderr.write(
+        `[multicorn-shield] Action log failed: HTTP ${String(response.status)}.
+`
+      );
+    }
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[multicorn-shield] Action log failed: ${detail}.
+`);
+  }
+}
+var POLL_INTERVAL_MS2 = 3e3;
+var POLL_TIMEOUT_MS2 = 5 * 60 * 1e3;
+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();
+    }
+    return "https://app.multicorn.ai";
+  } catch {
+    return "https://app.multicorn.ai";
+  }
+}
+function buildConsentUrl(agentName, dashboardUrl) {
+  const base = dashboardUrl.replace(/\/+$/, "");
+  const params = new URLSearchParams({ agent: agentName });
+  return `${base}/consent?${params.toString()}`;
+}
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+  } catch {
+    process.stderr.write(
+      `[multicorn-shield] Could not open browser. Visit this URL to grant permissions:
+${url}
+`
+    );
+  }
+}
+async function waitForConsent(agentId, agentName, apiKey, baseUrl) {
+  const dashboardUrl = deriveDashboardUrl(baseUrl);
+  const consentUrl = buildConsentUrl(agentName, dashboardUrl);
+  process.stderr.write(
+    `[multicorn-shield] Opening consent page...
+${consentUrl}
+Waiting for you to grant access in the Multicorn dashboard...
+`
+  );
+  openBrowser(consentUrl);
+  const deadline = Date.now() + POLL_TIMEOUT_MS2;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS2);
+    const scopes = await fetchGrantedScopes(agentId, apiKey, baseUrl);
+    if (scopes.length > 0) {
+      process.stderr.write("[multicorn-shield] Permissions granted.\n");
+      return scopes;
+    }
+  }
+  throw new Error(
+    `Consent not granted within ${String(POLL_TIMEOUT_MS2 / 6e4)} minutes. Grant access at ${dashboardUrl} and restart the gateway.`
+  );
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/openclaw/hook/handler.ts
+var agentRecord = null;
+var grantedScopes = [];
+var consentInProgress = false;
+var lastScopeRefresh = 0;
+var SCOPE_REFRESH_INTERVAL_MS = 6e4;
+function readConfig() {
+  const apiKey = process.env["MULTICORN_API_KEY"] ?? "";
+  const baseUrl = process.env["MULTICORN_BASE_URL"] ?? "https://api.multicorn.ai";
+  const agentName = process.env["MULTICORN_AGENT_NAME"] ?? null;
+  const failModeRaw = process.env["MULTICORN_FAIL_MODE"] ?? "open";
+  const failMode = failModeRaw === "closed" ? "closed" : "open";
+  return { apiKey, baseUrl, agentName, failMode };
+}
+function resolveAgentName(sessionKey, envOverride) {
+  if (envOverride !== null && envOverride.trim().length > 0) {
+    return envOverride.trim();
+  }
+  const parts = sessionKey.split(":");
+  const name = parts[1];
+  if (name !== void 0 && name.trim().length > 0) {
+    return name.trim();
+  }
+  return "openclaw";
+}
+async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
+  if (agentRecord !== null && Date.now() - lastScopeRefresh < SCOPE_REFRESH_INTERVAL_MS) {
+    return "ready";
+  }
+  if (agentRecord === null) {
+    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;
+      });
+      lastScopeRefresh = Date.now();
+      return "ready";
+    }
+  }
+  if (agentRecord === null) {
+    const record = await findOrRegisterAgent(agentName, apiKey, baseUrl);
+    if (record === null) {
+      if (failMode === "closed") {
+        return "block";
+      }
+      process.stderr.write(
+        "[multicorn-shield] Could not reach Shield API. Running without permission checks.\n"
+      );
+      return "skip";
+    }
+    agentRecord = record;
+  }
+  const scopes = await fetchGrantedScopes(agentRecord.id, apiKey, baseUrl);
+  grantedScopes = scopes;
+  lastScopeRefresh = Date.now();
+  if (scopes.length > 0) {
+    await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+    });
+  }
+  return "ready";
+}
+async function ensureConsent(agentName, apiKey, baseUrl) {
+  if (grantedScopes.length > 0 || consentInProgress || agentRecord === null) return;
+  consentInProgress = true;
+  try {
+    const scopes = await waitForConsent(agentRecord.id, agentName, apiKey, baseUrl);
+    grantedScopes = scopes;
+    await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+    });
+  } finally {
+    consentInProgress = false;
+  }
+}
+function isPermitted(event) {
+  const mapping = mapToolToScope(event.context.toolName);
+  return grantedScopes.some(
+    (scope) => scope.service === mapping.service && scope.permissionLevel === mapping.permissionLevel
+  );
+}
+var handler = async (event) => {
+  if (!isToolCallEvent(event)) return;
+  const config = readConfig();
+  if (config.apiKey.length === 0) {
+    process.stderr.write(
+      "[multicorn-shield] MULTICORN_API_KEY is not set. Skipping permission checks.\n"
+    );
+    return;
+  }
+  const agentName = resolveAgentName(event.sessionKey, config.agentName);
+  const readiness = await ensureAgent(agentName, config.apiKey, config.baseUrl, config.failMode);
+  if (readiness === "block") {
+    event.messages.push(
+      "Permission denied: Multicorn Shield could not verify permissions. The Shield API is unreachable and fail-closed mode is enabled."
+    );
+    return;
+  }
+  if (readiness === "skip") {
+    return;
+  }
+  await ensureConsent(agentName, config.apiKey, config.baseUrl);
+  const mapping = mapToolToScope(event.context.toolName);
+  const permitted = isPermitted(event);
+  if (!permitted) {
+    const capitalizedService = mapping.service.charAt(0).toUpperCase() + mapping.service.slice(1);
+    event.messages.push(
+      `Permission denied: ${capitalizedService} ${mapping.permissionLevel} access is not allowed. Visit the Multicorn Shield dashboard to manage permissions.`
+    );
+    void logAction(
+      {
+        agent: agentName,
+        service: mapping.service,
+        actionType: event.context.toolName,
+        status: "blocked"
+      },
+      config.apiKey,
+      config.baseUrl
+    );
+    return;
+  }
+  void logAction(
+    {
+      agent: agentName,
+      service: mapping.service,
+      actionType: event.context.toolName,
+      status: "approved"
+    },
+    config.apiKey,
+    config.baseUrl
+  );
+};
+function resetState() {
+  agentRecord = null;
+  grantedScopes = [];
+  consentInProgress = false;
+  lastScopeRefresh = 0;
+}
+
+export { handler, readConfig, resetState, resolveAgentName };