@seldonframe/mcp 1.59.1 → 1.59.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.59.1",
+  "version": "1.59.2",
   "mcpName": "io.github.seldonframe/mcp",
   "description": "Open-source GoHighLevel alternative for agencies. 146+ MCP tools that let Claude Code spin up white-labeled client workspaces — CRM, booking, intake forms, landing pages, AI chatbot, and pre-wired agent archetypes (speed-to-lead, missed-call-text-back, review-requester) — in minutes. AGPL-3.0.",
   "license": "AGPL-3.0-or-later",
@@ -17,8 +17,9 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "check:syntax": "node --check --input-type=module < src/index.js && node --check --input-type=module < src/client.js && node --check --input-type=module < src/tools.js && node --check --input-type=module < src/welcome.js",
-    "prepublishOnly": "npm run check:syntax"
+    "check:syntax": "node --check --input-type=module < src/index.js && node --check --input-type=module < src/client.js && node --check --input-type=module < src/tools.js && node --check --input-type=module < src/welcome.js && node --check --input-type=module < src/security.js",
+    "test": "node --test tests/*.test.mjs",
+    "prepublishOnly": "npm run check:syntax && npm run test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4"

package/src/client.js

@@ -2,6 +2,10 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join } from "node:path";
 import { VERSION } from "./welcome.js";
+// v1.59.2 — SSRF guard for fetchText, which fetches operator-supplied URLs
+// directly from the MCP server's machine (fetch_source_for_soul's
+// underlying implementation). See src/security.js for the guard + tests.
+import { assertPublicHttpUrl } from "./security.js";
 
 const API_BASE =
   process.env.SELDONFRAME_API_BASE ?? "https://app.seldonframe.com/api/v1";
@@ -170,18 +174,48 @@ export async function api(method, path, opts = {}) {
   return data;
 }
 
+// v1.59.2 — this fetches a URL the OPERATOR supplies (fetch_source_for_soul's
+// "scrape my existing website" feature), directly from the machine the MCP
+// server runs on. Without a guard, an operator (or a compromised/malicious
+// upstream prompt) could point this at http://localhost:PORT, a LAN device,
+// or a cloud metadata endpoint and have the MCP process fetch it on their
+// behalf. assertPublicHttpUrl rejects non-public targets; redirects are
+// followed MANUALLY (max 3 hops) so a public URL that 30x's to a private
+// one can't slip past the initial check.
+const MAX_REDIRECTS = 3;
+
 export async function fetchText(url, { maxBytes = 256 * 1024 } = {}) {
-  const res = await fetch(url, {
-    headers: { "User-Agent": `seldonframe-mcp/${VERSION} (+soul-compiler)` },
-    redirect: "follow",
-  });
+  let currentUrl = url;
+  let res;
+  for (let hop = 0; ; hop++) {
+    await assertPublicHttpUrl(currentUrl);
+    res = await fetch(currentUrl, {
+      headers: { "User-Agent": `seldonframe-mcp/${VERSION} (+soul-compiler)` },
+      redirect: "manual",
+    });
+    const isRedirect = res.status >= 300 && res.status < 400;
+    if (!isRedirect) break;
+    if (hop >= MAX_REDIRECTS) {
+      throw new Error(
+        `Fetch ${url} failed: exceeded ${MAX_REDIRECTS} redirects (stopped at ${currentUrl}).`,
+      );
+    }
+    const location = res.headers.get("location");
+    if (!location) {
+      throw new Error(
+        `Fetch ${currentUrl} returned redirect status ${res.status} with no Location header.`,
+      );
+    }
+    // Location may be relative — resolve against the URL that produced it.
+    currentUrl = new URL(location, currentUrl).toString();
+  }
   if (!res.ok) {
     throw new Error(`Fetch ${url} failed: ${res.status} ${res.statusText}`);
   }
   const raw = await res.text();
   const truncated = raw.length > maxBytes;
   const html = truncated ? raw.slice(0, maxBytes) : raw;
-  return { html, truncated, status: res.status, final_url: res.url };
+  return { html, truncated, status: res.status, final_url: res.url || currentUrl };
 }
 
 export function htmlToText(html) {

package/src/security.js

@@ -0,0 +1,241 @@
+// v1.59.2 — security hardening helpers shared by tools.js.
+//
+// Two independent concerns live here:
+//   1. sniffImageKind — magic-byte detection so upload_workspace_image only
+//      ever forwards bytes that are actually image files (not arbitrary
+//      local files an agent was pointed at).
+//   2. assertPublicHttpUrl — an SSRF guard for machine-side fetches of
+//      operator-supplied URLs (fetch_source_for_soul today). Rejects
+//      loopback / private / link-local targets so the MCP process can't be
+//      used to probe the operator's own LAN or cloud metadata endpoints.
+//
+// Both are pure-ish (assertPublicHttpUrl takes an injectable `lookup` for
+// tests) and have zero dependency on the rest of tools.js so they can be
+// unit-tested in isolation (see tests/security.test.mjs).
+
+const MAX_SVG_BYTES = 1 * 1024 * 1024; // 1MB
+
+// Loose but sufficient: optional UTF-8 BOM, optional XML prolog, optional
+// DOCTYPE, then an <svg ...> or <svg> root tag. Case-insensitive.
+const SVG_PATTERN =
+  /^?\s*(<\?xml[^>]*>\s*)?(<!DOCTYPE[^>]*>\s*)?<svg[\s>]/i;
+
+/**
+ * Sniff the image kind of a buffer from its magic bytes. Returns one of
+ * "png" | "jpeg" | "gif" | "webp" | "svg", or null if the buffer doesn't
+ * look like a recognized image format.
+ *
+ * @param {Buffer} buffer
+ * @returns {"png"|"jpeg"|"gif"|"webp"|"svg"|null}
+ */
+export function sniffImageKind(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) return null;
+
+  // PNG: 89 50 4E 47 (plus the usual 0D 0A 1A 0A trailer, but the first
+  // four bytes are sufficient to identify it unambiguously).
+  if (
+    buffer.length >= 4 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47
+  ) {
+    return "png";
+  }
+
+  // JPEG: FF D8 FF
+  if (
+    buffer.length >= 3 &&
+    buffer[0] === 0xff &&
+    buffer[1] === 0xd8 &&
+    buffer[2] === 0xff
+  ) {
+    return "jpeg";
+  }
+
+  // GIF: ASCII "GIF8" (covers both GIF87a and GIF89a).
+  if (buffer.length >= 4 && buffer.toString("ascii", 0, 4) === "GIF8") {
+    return "gif";
+  }
+
+  // WebP: "RIFF" at offset 0, "WEBP" at offset 8.
+  if (
+    buffer.length >= 12 &&
+    buffer.toString("ascii", 0, 4) === "RIFF" &&
+    buffer.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    return "webp";
+  }
+
+  // SVG: text-based, so magic bytes don't apply — sniff the text instead.
+  // Bound the size before decoding so a huge non-image file doesn't get
+  // fully UTF-8-decoded just to fail this check.
+  if (buffer.length <= MAX_SVG_BYTES) {
+    const text = buffer.toString("utf8");
+    if (SVG_PATTERN.test(text)) return "svg";
+  }
+
+  return null;
+}
+
+// ── SSRF guard ──────────────────────────────────────────────────────────
+
+const BLOCKED_HOSTNAME_SUFFIXES = [".localhost", ".local", ".internal"];
+
+function isBlockedHostname(hostname) {
+  const host = hostname.toLowerCase();
+  if (host === "localhost") return true;
+  return BLOCKED_HOSTNAME_SUFFIXES.some((suffix) => host.endsWith(suffix));
+}
+
+/**
+ * Parse an IPv4 dotted-quad string into four octet numbers, or null if it
+ * isn't a valid literal IPv4 address.
+ * @param {string} host
+ * @returns {[number,number,number,number]|null}
+ */
+function parseIPv4(host) {
+  const parts = host.split(".");
+  if (parts.length !== 4) return null;
+  const octets = [];
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const n = Number(part);
+    if (n < 0 || n > 255) return null;
+    octets.push(n);
+  }
+  return octets;
+}
+
+/**
+ * Is this IPv4 (as an octet quad) inside a non-public range?
+ * @param {[number,number,number,number]} o
+ */
+function isNonPublicIPv4(o) {
+  const [a, b] = o;
+  if (a === 0) return true; // 0.0.0.0/8
+  if (a === 10) return true; // 10/8
+  if (a === 127) return true; // 127/8 (loopback)
+  if (a === 169 && b === 254) return true; // 169.254/16 (link-local)
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+  if (a === 192 && b === 168) return true; // 192.168/16
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64/10 (CGNAT)
+  return false;
+}
+
+/**
+ * Is this literal address (v4 or v6 string form) non-public? Handles
+ * IPv4-mapped IPv6 (::ffff:x.x.x.x) by unwrapping to the embedded IPv4.
+ * @param {string} address
+ */
+function isNonPublicIpLiteral(address) {
+  const addr = address.toLowerCase();
+
+  // IPv4-mapped IPv6: ::ffff:x.x.x.x (or the rarer ::ffff:0:x.x.x.x form).
+  const mappedMatch = addr.match(/^::ffff:(?:0:)?(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (mappedMatch) {
+    const v4 = parseIPv4(mappedMatch[1]);
+    return v4 ? isNonPublicIPv4(v4) : true; // malformed embedded v4 = reject
+  }
+
+  const v4 = parseIPv4(addr);
+  if (v4) return isNonPublicIPv4(v4);
+
+  // IPv6 literal checks.
+  if (addr === "::1") return true; // loopback
+  if (addr === "::") return true; // unspecified
+  if (/^fc[0-9a-f]{2}:/.test(addr) || /^fd[0-9a-f]{2}:/.test(addr)) {
+    return true; // fc00::/7 (unique local) — first byte 0xfc or 0xfd
+  }
+  if (/^fe[89ab][0-9a-f]:/.test(addr)) return true; // fe80::/10 (link-local)
+
+  // Not a recognized literal at all (shouldn't happen given callers only
+  // pass here after confirming it parses as an IP) — fail closed.
+  return false;
+}
+
+/**
+ * Does this string parse as a literal IP address (v4 or v6)? Deliberately
+ * simple — good enough to distinguish "the caller already resolved this to
+ * an IP" from "this is a hostname that still needs DNS resolution."
+ * @param {string} host
+ */
+function isIpLiteral(host) {
+  if (parseIPv4(host)) return true;
+  // Very small heuristic for IPv6 literal form: contains a colon and only
+  // hex digits / colons (optionally with an embedded dotted-quad tail for
+  // the IPv4-mapped form).
+  return /^[0-9a-f:]+(:\d{1,3}(?:\.\d{1,3}){3})?$/i.test(host) && host.includes(":");
+}
+
+/**
+ * Assert that a URL is safe for the MCP server (running on the operator's
+ * machine) to fetch directly: http(s) only, and resolves exclusively to
+ * public IP addresses. Throws with a clear message otherwise.
+ *
+ * Guards against SSRF-style abuse where an operator-supplied "scrape this
+ * URL" argument actually points at localhost, a LAN device, or a cloud
+ * metadata endpoint (169.254.169.254) reachable from wherever the MCP
+ * process happens to run.
+ *
+ * @param {string} urlString
+ * @param {{ lookup?: (hostname: string, opts: { all: true }) => Promise<{address:string,family:number}[]> }} [opts]
+ */
+export async function assertPublicHttpUrl(urlString, opts = {}) {
+  let parsed;
+  try {
+    parsed = new URL(urlString);
+  } catch {
+    throw new Error(`assertPublicHttpUrl: "${urlString}" is not a valid URL.`);
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `assertPublicHttpUrl: protocol "${parsed.protocol}" is not allowed for "${urlString}" — only http: and https: are permitted.`,
+    );
+  }
+
+  // URL.hostname strips brackets from IPv6 literals (e.g. "[::1]" -> "::1").
+  const hostname = parsed.hostname;
+
+  if (isBlockedHostname(hostname)) {
+    throw new Error(
+      `assertPublicHttpUrl: hostname "${hostname}" is blocked (localhost / .localhost / .local / .internal).`,
+    );
+  }
+
+  if (isIpLiteral(hostname)) {
+    if (isNonPublicIpLiteral(hostname)) {
+      throw new Error(
+        `assertPublicHttpUrl: "${hostname}" is not a public IP address.`,
+      );
+    }
+    return;
+  }
+
+  const lookup =
+    opts.lookup ?? (await import("node:dns/promises")).lookup;
+  let records;
+  try {
+    records = await lookup(hostname, { all: true });
+  } catch (err) {
+    throw new Error(
+      `assertPublicHttpUrl: DNS lookup for "${hostname}" failed — ${err?.message ?? err}`,
+    );
+  }
+
+  if (!Array.isArray(records) || records.length === 0) {
+    throw new Error(
+      `assertPublicHttpUrl: DNS lookup for "${hostname}" returned no addresses.`,
+    );
+  }
+
+  for (const record of records) {
+    const address = record?.address ?? record;
+    if (typeof address !== "string" || isNonPublicIpLiteral(address)) {
+      throw new Error(
+        `assertPublicHttpUrl: "${hostname}" resolves to a non-public address (${address}) — refusing to fetch.`,
+      );
+    }
+  }
+}

package/src/tools.js

@@ -31,6 +31,10 @@ import { buildFinalizeSummary } from "./finalize-summary.js";
 // the agent token budget that v1.10.0's image_data_b64 path was bound by.
 import { readFileSync } from "node:fs";
 import path from "node:path";
+// v1.59.2 — security hardening: image-content sniffing (upload_workspace_image)
+// and the SSRF guard for machine-side fetches of operator-supplied URLs
+// (fetch_source_for_soul). See src/security.js for details + tests.
+import { sniffImageKind, assertPublicHttpUrl } from "./security.js";
 
 const str = (description, extra = {}) => ({ type: "string", description, ...extra });
 const obj = (properties, required = []) => ({
@@ -1399,10 +1403,13 @@ export const TOOLS = [
   {
     name: "fetch_source_for_soul",
     description:
-      "Fetch a URL and return normalized text (headings + body, up to 256KB). Use this to gather raw content from the operator's existing website; then extract a structured business profile and save it with submit_soul. Zero LLM cost to SeldonFrame — extraction runs in this session.",
+      "Fetch a URL and return normalized text (headings + body, up to 256KB). Use this to gather raw content from the operator's existing website; then extract a structured business profile and save it with submit_soul. Zero LLM cost to SeldonFrame — extraction runs in this session. " +
+      "v1.59.2 — only public http(s) URLs are fetched: the MCP server rejects localhost / private-network / link-local targets (and any redirect that lands on one) before making the request. Use this for the operator's real, public-facing website only.",
     inputSchema: obj(
       {
-        url: str("Absolute URL to fetch."),
+        url: str(
+          "Absolute URL to fetch. Must be a public http(s) URL — localhost, LAN, and other private-network addresses are rejected.",
+        ),
       },
       ["url"],
     ),
@@ -4088,6 +4095,7 @@ export const TOOLS = [
       "(b) `local_file_path` (v1.10.1+) — absolute path on the operator's machine. The MCP server (running locally) reads the file and forwards bytes to the backend. Best path for files on the operator's desktop. file_name + content_type derived from the path. " +
       "(c) `image_data_b64` (legacy v1.10.0) — image bytes base64-encoded. Use only when you've generated bytes yourself (e.g. dynamic image gen) and there's no URL or path. Be aware: the encoded string consumes your tool-call token budget; for files >~12 KB raw, prefer (a) or (b). " +
       "Max 5 MB across all paths. Allowed types: image/png, image/jpeg, image/webp, image/svg+xml, image/gif. " +
+      "v1.59.2 — for local_file_path and image_data_b64, the MCP server sniffs the actual bytes (magic numbers / SVG root tag) before uploading anything; a file that isn't a recognized image format is rejected locally and never reaches the network. This tool cannot be used to exfiltrate arbitrary local files under an image_url. " +
       "Returns the public Blob URL on success; that URL is now live on the workspace's public surface within seconds. " +
       "Antifragile design: server only validates file shape + applies URL to the right column. Your LLM picks which slot ('they said logo, that maps to slot=logo'). As you get better at intent-mapping, the harness doesn't change.",
     inputSchema: obj(
@@ -4162,6 +4170,26 @@ export const TOOLS = [
             `upload_workspace_image: failed to read local_file_path "${filePath}" — ${err?.message ?? err}`,
           );
         }
+        // v1.59.2 — this is the local-file-read path (the MCP server reads
+        // whatever absolute path it's given). Enforce the size cap and
+        // sniff the actual bytes BEFORE they're base64'd and sent anywhere,
+        // so this tool can only ever upload real images — not an
+        // agent-mediated read of an arbitrary local file.
+        if (buf.length > 5 * 1024 * 1024) {
+          return {
+            ok: false,
+            error: "file_too_large",
+            message: `upload_workspace_image: "${filePath}" is ${buf.length} bytes, over the 5MB max.`,
+          };
+        }
+        if (sniffImageKind(buf) === null) {
+          return {
+            ok: false,
+            error: "not_an_image",
+            message:
+              "Not a recognized image file (png, jpeg, gif, webp, svg). This tool only uploads images.",
+          };
+        }
         // Derive file_name + content_type from the path extension, mirroring
         // the server-side image_url logic so the two paths feel identical
         // to the operator.
@@ -4186,12 +4214,40 @@ export const TOOLS = [
         }
       } else {
         // image_data_b64 — caller supplied bytes directly.
-        body.image_data_b64 = args.image_data_b64;
         if (!args.file_name || !args.content_type) {
           throw new Error(
             "upload_workspace_image: file_name and content_type are required with image_data_b64. (image_url and local_file_path auto-derive them.)",
           );
         }
+        // v1.59.2 — same bytes-in, sniff-before-send discipline as the
+        // local_file_path branch above (this tool only uploads images,
+        // regardless of which of the three sources supplied the bytes).
+        let decoded;
+        try {
+          decoded = Buffer.from(args.image_data_b64, "base64");
+        } catch (err) {
+          return {
+            ok: false,
+            error: "invalid_base64",
+            message: `upload_workspace_image: image_data_b64 could not be decoded — ${err?.message ?? err}`,
+          };
+        }
+        if (decoded.length > 5 * 1024 * 1024) {
+          return {
+            ok: false,
+            error: "file_too_large",
+            message: `upload_workspace_image: decoded image_data_b64 is ${decoded.length} bytes, over the 5MB max.`,
+          };
+        }
+        if (sniffImageKind(decoded) === null) {
+          return {
+            ok: false,
+            error: "not_an_image",
+            message:
+              "Not a recognized image file (png, jpeg, gif, webp, svg). This tool only uploads images.",
+          };
+        }
+        body.image_data_b64 = args.image_data_b64;
         body.file_name = args.file_name;
         body.content_type = args.content_type;
       }
@@ -4588,7 +4644,8 @@ export const TOOLS = [
       "The OPERATOR pays the LLM provider directly (Anthropic / OpenAI / etc.); SF charges separately for agent platform usage. " +
       "Stored encrypted at rest using the deployment's ENCRYPTION_KEY. " +
       "Operators get keys from console.anthropic.com (recommended for v1.26.x — best tool-use support) or platform.openai.com. " +
-      "v1.28+ AUTO-DETECT: pass api_key='env' (or omit api_key entirely) and the MCP server will read process.env.ANTHROPIC_API_KEY / OPENAI_API_KEY from its own environment. Most Claude Code users already have this set (it's how Claude Code works), so this lets a solo SF client onboard with zero key-paste step. Returns { ok: false, error: 'no_env_key' } if the env var isn't set; in that case the user must paste the key explicitly. " +
+      "v1.28+ AUTO-DETECT: pass api_key='env' (or omit api_key entirely) to read process.env.ANTHROPIC_API_KEY / OPENAI_API_KEY from the MCP server's own environment. " +
+      "v1.59.2 — CONSENT REQUIRED before storing an env-detected key: ask the user first ('I found an Anthropic key in your environment — OK to store it in your SeldonFrame workspace?'), then re-call with confirm_store_env_key: true. Without that flag, this tool reports the env var it found and stops — it does NOT transmit the value. A key passed explicitly via api_key is consent by definition and is never gated. Returns { ok: false, error: 'no_env_key' } if the env var isn't set; in that case the user must paste the key explicitly. " +
       "Skip if the workspace already has a key — agents fail-graceful with 'I'm not set up yet' if no key configured, so a 'not configured' chatbot response means CALL THIS TOOL.",
     inputSchema: obj(
       {
@@ -4600,8 +4657,13 @@ export const TOOLS = [
             "LLM provider. v1.26 ships full Anthropic support (tool use, streaming-ready). OpenAI support for chat is partial — recommend Anthropic for production agents.",
         },
         api_key: str(
-          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back. v1.28+ AUTO-DETECT: pass 'env' (literal string) or omit entirely to read process.env.{ANTHROPIC,OPENAI}_API_KEY from the MCP server's local environment.",
+          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back. v1.28+ AUTO-DETECT: pass 'env' (literal string) or omit entirely to read process.env.{ANTHROPIC,OPENAI}_API_KEY from the MCP server's local environment (subject to the confirm_store_env_key consent gate below). Passing the key explicitly here IS consent — it's never gated.",
         ),
+        confirm_store_env_key: {
+          type: "boolean",
+          description:
+            "Set true ONLY after the user has explicitly confirmed storing the API key found in this machine's environment variables in their SeldonFrame workspace.",
+        },
       },
       ["workspace_id", "provider"],
     ),
@@ -4628,6 +4690,20 @@ export const TOOLS = [
             envName,
           };
         }
+        // v1.59.2 — CONSENT GATE. Finding a key in the environment is not
+        // the same as the operator agreeing to store it server-side.
+        // Without explicit confirm_store_env_key: true, stop here and
+        // tell the agent to go get consent — never transmit the value.
+        if (args.confirm_store_env_key !== true) {
+          return {
+            ok: true,
+            needs_consent: true,
+            env_var_found: envName,
+            message:
+              `Found ${envName} in the environment. SeldonFrame can store this key in the workspace (server-side, used only to power the hosted chatbot/agent). ` +
+              `Ask the user for permission first, then re-call this tool with confirm_store_env_key: true.`,
+          };
+        }
       }
 
       const result = await api("POST", "/agents", {
@@ -5009,7 +5085,8 @@ export const TOOLS = [
       "(2) creates a website-chatbot agent with the FAQ + pricing facts + greeting you provide; " +
       "(3) publishes to status='test' so the operator can sandbox-test before going live (the eval gate runs only on 'live'); " +
       "(4) returns the embed snippet, dashboard URL, and clear next-steps. " +
-      "USE THIS as the default for natural-language 'create a chatbot' requests. Fall back to the primitive tools (configure_llm_provider + create_agent + publish_agent) only when you need a custom flow (e.g. agency managing multiple operators with separate Anthropic billing — pass anthropic_api_key explicitly per workspace).",
+      "USE THIS as the default for natural-language 'create a chatbot' requests. Fall back to the primitive tools (configure_llm_provider + create_agent + publish_agent) only when you need a custom flow (e.g. agency managing multiple operators with separate Anthropic billing — pass anthropic_api_key explicitly per workspace). " +
+      "v1.59.2 — CONSENT REQUIRED before storing an env-detected key: if no anthropic_api_key is passed and process.env.ANTHROPIC_API_KEY is found, this tool does NOT store it on the first call. It reports what it found and stops (nothing else in the bundle runs yet). Ask the user for permission, then re-call with confirm_store_env_key: true to proceed with the full bundle. If neither an explicit key nor an env key is present, the bundle proceeds anyway on the SeldonFrame platform key — no consent needed because nothing of the operator's is transmitted.",
     inputSchema: obj(
       {
         workspace_id: str("Workspace id (bearer workspace)."),
@@ -5045,8 +5122,13 @@ export const TOOLS = [
           "First message shown when chat opens (~120 chars). E.g. 'Hi! Asking about HVAC service in Phoenix? I can book you in or answer common questions.' Default if omitted: 'Hi! How can I help you today?'",
         ),
         anthropic_api_key: str(
-          "Optional explicit Anthropic API key (sk-ant-...). If omitted, reads from process.env.ANTHROPIC_API_KEY in the MCP server's environment. Pass explicitly for white-label scenarios (different operator = different Anthropic billing). Skipped entirely if the workspace already has a key configured.",
+          "Optional explicit Anthropic API key (sk-ant-...). If omitted, reads from process.env.ANTHROPIC_API_KEY in the MCP server's environment (subject to the confirm_store_env_key consent gate below). Pass explicitly for white-label scenarios (different operator = different Anthropic billing) — passing it here IS consent, never gated. Skipped entirely if the workspace already has a key configured.",
         ),
+        confirm_store_env_key: {
+          type: "boolean",
+          description:
+            "Set true ONLY after the user has explicitly confirmed storing the API key found in this machine's environment variables in their SeldonFrame workspace.",
+        },
       },
       ["workspace_id", "name"],
     ),
@@ -5072,6 +5154,24 @@ export const TOOLS = [
       // that v1.40.9 Sunset Plumbing test exposed.
       const explicitKey = args.anthropic_api_key;
       const envKey = process.env.ANTHROPIC_API_KEY;
+
+      // v1.59.2 — CONSENT GATE. An env-inherited key is about to be
+      // transmitted to the SF API and stored on the workspace; the
+      // operator hasn't agreed to that yet just by virtue of having the
+      // var set in their shell. Stop the ENTIRE bundle here (before
+      // create_agent / publish_agent run) and ask first. An explicit
+      // anthropic_api_key arg is consent by definition and skips this.
+      if (!explicitKey && envKey && args.confirm_store_env_key !== true) {
+        return {
+          ok: true,
+          needs_consent: true,
+          env_var_found: "ANTHROPIC_API_KEY",
+          message:
+            "Found ANTHROPIC_API_KEY in the environment. SeldonFrame can store this key in the workspace (server-side, used only to power the hosted chatbot/agent). " +
+            "Ask the user for permission first, then re-call this tool with confirm_store_env_key: true.",
+        };
+      }
+
       const keyToUse = explicitKey || envKey;
       let llmMode = "platform";
       if (keyToUse) {

package/src/welcome.js

@@ -8,7 +8,7 @@
 // stripped. `create_full_workspace` is the only workspace-creation
 // path mentioned anywhere in this briefing.
 
-export const VERSION = "1.59.1";
+export const VERSION = "1.59.2";
 
 export const WELCOME_MARKDOWN = `# SeldonFrame — create a real Business OS in one conversation
 
@@ -108,8 +108,17 @@ of v1.28.0 this is **ONE tool call**:
      // platform key automatically. Operator can BYOK later via
      // /settings/integrations/llm. Pass explicitly only when you need
      // per-workspace billing isolation (white-label / agency).
+     //
+     // v1.59.2 — if you omit anthropic_api_key AND the MCP server's
+     // environment has ANTHROPIC_API_KEY set, this call returns
+     // needs_consent: true instead of building anything. ASK THE USER
+     // before storing a key found in the environment ("I found an
+     // Anthropic key in your environment — OK to store it in your
+     // SeldonFrame workspace?"), then re-call with
+     // confirm_store_env_key: true.
    })
    // → returns { agent, embed_url, turn_api_url, turn_api_method: "POST", dashboard_url, llm_mode, next_steps }
+   // or, if an env key needs consent first: { ok: true, needs_consent: true, env_var_found, message }.
    // Internally: creates agent, publishes to test. Skips set_llm_key when
    // no key supplied (platform fallback in lib/ai/client.ts handles inference).
 
@@ -125,18 +134,25 @@ billing (e.g. Acme AI agency managing Cypress Pine HVAC + Sunset
 Dental), pass anthropic_api_key explicitly per workspace instead of
 relying on platform fallback.
 
-### v1.40.10 — LLM key handling
+### v1.40.10 — LLM key handling (v1.59.2 — consent gate on path 2)
 
 build_website_chatbot has THREE possible LLM-key paths, in priority
 order:
 
 1. **Explicit** — \`anthropic_api_key: 'sk-ant-...'\` arg → workspace
-   stored as BYOK, operator pays Anthropic directly.
+   stored as BYOK, operator pays Anthropic directly. Passing the key
+   explicitly IS consent — this path is never gated.
 2. **Env-inherited** — process.env.ANTHROPIC_API_KEY in the MCP
-   server's environment → workspace stored as BYOK with that key.
+   server's environment → the DEFAULT is to ASK FIRST, not store
+   silently. The first call (no confirm_store_env_key) returns
+   \`{ needs_consent: true, env_var_found, message }\` and does nothing
+   else. Tell the operator what was found and ask permission; only
+   after they agree, re-call with \`confirm_store_env_key: true\` to
+   store the key as BYOK and continue the bundle.
 3. **Platform fallback** — neither explicit nor env → no BYOK
-   stored. The workspace uses SeldonFrame's platform Anthropic key
-   automatically (via lib/ai/client.ts -> getAIClient). Operator
+   stored, no consent needed (nothing of the operator's is
+   transmitted). The workspace uses SeldonFrame's platform Anthropic
+   key automatically (via lib/ai/client.ts -> getAIClient). Operator
    sees no setup friction; they can BYOK later in
    /settings/integrations/llm.
 
@@ -145,7 +161,8 @@ the operator: "Your chatbot is using SeldonFrame's shared Anthropic
 key. You can switch to your own anytime in Settings → Integrations
 → LLM, no code changes needed." This removes the "where do I get an
 Anthropic key" question from the critical path of a first-time
-chatbot setup.
+chatbot setup — and it means path 2's consent step only ever comes up
+when an env key actually exists, not as a blocking default.
 
 For custom flows (different archetype, custom capability allowlist,
 multi-step blueprint construction), drop down to the primitives: