@promptev/context-engine 0.0.0 → 0.0.2

package/dist/express.js

@@ -1,6 +1,8 @@
 import { createRequire } from 'module';
 import { z } from 'zod';
-import { randomBytes, createHash, randomUUID, createCipheriv, createDecipheriv, createHmac } from 'crypto';
+import { randomBytes, createHash, randomUUID, createDecipheriv, createCipheriv, createHmac } from 'crypto';
+import { promises } from 'dns';
+import { isIP } from 'net';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -58,6 +60,9 @@ __export(db_exports, {
 function stripSqlNoise(sql) {
   return sql.replace(SQL_NOISE_RE, (m) => " ".repeat(m.length));
 }
+function stripSqlNoiseBackslash(sql) {
+  return sql.replace(SQL_NOISE_BACKSLASH_RE, (m) => " ".repeat(m.length));
+}
 function hasKeyword(sqlUpper, keyword) {
   return new RegExp(`\\b${keyword}\\b`).test(sqlUpper);
 }
@@ -186,24 +191,28 @@ async function executeQueryAsync(config, sql, maxRows, accessModeRaw) {
       `Invalid access_mode ${JSON.stringify(accessModeRaw)}; must be one of ${ALLOWED_ACCESS_MODES}`
     );
   }
-  const sqlUpper = stripSqlNoise(sql).trim().toUpperCase();
+  const sqlVariants = [
+    stripSqlNoise(sql).trim().toUpperCase(),
+    stripSqlNoiseBackslash(sql).trim().toUpperCase()
+  ];
+  const sqlUpper = sqlVariants[0];
   for (const keyword of ALWAYS_BLOCKED) {
-    if (hasKeyword(sqlUpper, keyword)) {
+    if ([...sqlVariants, sql.toUpperCase()].some((v) => hasKeyword(v, keyword))) {
       return { success: false, error: `${keyword} queries are not allowed` };
     }
   }
   if (accessMode === "readonly") {
-    if (!sqlUpper.startsWith("SELECT") && !sqlUpper.startsWith("WITH")) {
+    if (!sqlVariants.every((v) => v.startsWith("SELECT") || v.startsWith("WITH"))) {
       return { success: false, error: "Only SELECT queries are allowed in read-only mode" };
     }
     for (const keyword of READONLY_BLOCKED) {
-      if (hasKeyword(sqlUpper, keyword)) {
+      if (sqlVariants.some((v) => hasKeyword(v, keyword))) {
         return { success: false, error: `${keyword} queries are not allowed in read-only mode` };
       }
     }
   } else if (accessMode === "readwrite") {
     for (const keyword of READWRITE_BLOCKED) {
-      if (hasKeyword(sqlUpper, keyword)) {
+      if (sqlVariants.some((v) => hasKeyword(v, keyword))) {
         return { success: false, error: `${keyword} queries are not allowed in read-write mode` };
       }
     }
@@ -337,7 +346,7 @@ async function getSchemaText(config, selectedTables) {
   }
   return rowsToText(schemaRows);
 }
-var require2, MAX_ROWS, CONNECT_TIMEOUT, QUERY_TIMEOUT_MS, ALWAYS_BLOCKED, READONLY_BLOCKED, READWRITE_BLOCKED, ALLOWED_ACCESS_MODES, SQL_NOISE_RE;
+var require2, MAX_ROWS, CONNECT_TIMEOUT, QUERY_TIMEOUT_MS, ALWAYS_BLOCKED, READONLY_BLOCKED, READWRITE_BLOCKED, ALLOWED_ACCESS_MODES, SQL_NOISE_RE, SQL_NOISE_BACKSLASH_RE;
 var init_db = __esm({
   "src/tools/executors/db.ts"() {
     init_errors();
@@ -346,10 +355,22 @@ var init_db = __esm({
     CONNECT_TIMEOUT = 10;
     QUERY_TIMEOUT_MS = 3e4;
     ALWAYS_BLOCKED = ["GRANT", "REVOKE"];
-    READONLY_BLOCKED = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE", "TRUNCATE"];
-    READWRITE_BLOCKED = ["DELETE", "DROP", "TRUNCATE"];
+    READONLY_BLOCKED = [
+      "INSERT",
+      "UPDATE",
+      "DELETE",
+      "MERGE",
+      "DROP",
+      "ALTER",
+      "CREATE",
+      "TRUNCATE",
+      "DO",
+      "CALL"
+    ];
+    READWRITE_BLOCKED = ["DELETE", "DROP", "TRUNCATE", "DO", "CALL"];
     ALLOWED_ACCESS_MODES = ["readonly", "readwrite", "full"];
-    SQL_NOISE_RE = /'(?:[^']|'')*'|\$([A-Za-z_]\w*)?\$.*?\$\1?\$|--[^\n]*|\/\*[\s\S]*?\*\//g;
+    SQL_NOISE_RE = /\b[eE]'(?:[^'\\]|\\[\s\S]|'')*'|'(?:[^']|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g;
+    SQL_NOISE_BACKSLASH_RE = /'(?:[^'\\]|\\[\s\S]|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g;
   }
 });
 
@@ -357,16 +378,7 @@ var init_db = __esm({
 init_errors();
 
 // src/sentinels.ts
-var TrustedSentinel = class {
-  [Symbol.toStringTag] = "TRUSTED";
-  toString() {
-    return "TRUSTED";
-  }
-  valueOf() {
-    return true;
-  }
-};
-var TRUSTED = Object.freeze(new TrustedSentinel());
+var TRUSTED = /* @__PURE__ */ Symbol.for("context_engine.TRUSTED");
 
 // src/routing-core.ts
 var HandlerError = class extends Error {
@@ -400,6 +412,10 @@ var documentPatchSchema = z.object({
 var searchRequestSchema = z.object({
   query: z.string(),
   source_ids: z.array(z.string()).nullable().optional(),
+  // Narrows WITHIN a source and INTERSECTS with source_ids — it can only
+  // shrink the result set (the ACL predicate still applies in the same SQL
+  // conjunction), so exposing it needs no authorizeAcl-style grant check.
+  document_ids: z.array(z.string()).nullable().optional(),
   top_k: z.number().int().optional().default(10),
   mode: z.enum(["hybrid", "graph"]).optional().default("hybrid"),
   compress_to_tokens: z.number().int().nullable().optional()
@@ -428,17 +444,23 @@ function formStr(value) {
   return value === void 0 || value === null || value === "" ? null : String(value);
 }
 function resolveRequestPrincipals(value, opts) {
-  if (value === TRUSTED) return null;
+  if (value === TRUSTED) return TRUSTED;
   if (value == null) {
     throw new HandlerError(
       500,
       `${opts.surface}: the \`principals\` dependency returned null, which means TRUSTED CALLER \u2014 it disables ACL filtering and skips the check that stops a caller filing documents under groups it does not hold. This mount is misconfigured: return [] for an unauthenticated caller, or pass TRUSTED explicitly (from @promptev/context-engine) if the surface really is trusted.`
     );
   }
+  if (!Array.isArray(value) || value.some((p) => typeof p !== "string")) {
+    throw new HandlerError(
+      500,
+      `${opts.surface}: the \`principals\` dependency must return a list of principal strings, [] for an anonymous caller, or TRUSTED \u2014 got ${typeof value}.`
+    );
+  }
   return value;
 }
 function authorizeAcl(requested, principals) {
-  if (requested == null || principals == null) return;
+  if (requested == null || principals == null || principals === TRUSTED) return;
   if (!Array.isArray(requested)) {
     throw new HandlerError(422, "acl must be a list of principal strings");
   }
@@ -587,9 +609,11 @@ async function handleSearch(engine, payload, principals) {
   const parsed = searchRequestSchema.safeParse(payload);
   if (!parsed.success) throw zodError(parsed.error);
   const body = parsed.data;
+  for (const did of body.document_ids ?? []) requireValidUuid(did);
   try {
     const result = await engine.search(body.query, {
       sourceIds: body.source_ids,
+      documentIds: body.document_ids,
       principals: resolved,
       topK: body.top_k,
       mode: body.mode,
@@ -613,7 +637,7 @@ init_errors();
 
 // src/tools/acl.ts
 function aclVisible(acl, principals) {
-  if (principals === null) return true;
+  if (principals === null || principals === TRUSTED) return true;
   if (acl == null) return true;
   if (!acl.length) return false;
   const held = new Set(principals ?? []);
@@ -678,17 +702,24 @@ function rowToRecord(row) {
     toolName: String(row.tool_name),
     toolArgsFrozen: row.tool_args_frozen ?? {},
     sourceId: row.source_id ?? null,
+    approvalScope: row.approval_scope ?? null,
     principals: row.principals,
     status: String(row.status),
     approver: row.approver ?? null,
     approverMeta: row.approver_meta ?? null,
-    expiresAt: row.expires_at ? new Date(String(row.expires_at)) : null,
-    resolvedAt: row.resolved_at ? new Date(String(row.resolved_at)) : null,
-    createdAt: row.created_at ? new Date(String(row.created_at)) : null
+    expiresAt: toDate(row.expires_at),
+    resolvedAt: toDate(row.resolved_at),
+    createdAt: toDate(row.created_at)
   };
 }
+function toDate(value) {
+  if (value == null) return null;
+  if (value instanceof Date) return value;
+  return new Date(String(value));
+}
 function visibilitySql(principals, paramIndex) {
-  if (principals === null) return { sql: "TRUE", params: [] };
+  if (principals === null || principals === TRUSTED) return { sql: "TRUE", params: [] };
+  principals = principals;
   if (!principals.length) {
     return { sql: `(principals IS NULL OR principals = 'null'::jsonb)`, params: [] };
   }
@@ -697,41 +728,95 @@ function visibilitySql(principals, paramIndex) {
     params: [principals]
   };
 }
-async function createPending(engine, opts) {
+function claimVisibilitySql(principals, paramIndex) {
+  if (principals === null || principals === TRUSTED) return { sql: "TRUE", params: [] };
+  const noWall = `principals IS NULL OR principals = 'null'::jsonb OR principals = '[]'::jsonb`;
+  principals = principals;
+  if (!principals.length) return { sql: `(${noWall})`, params: [] };
+  return { sql: `(${noWall} OR principals ?| $${paramIndex}::text[])`, params: [principals] };
+}
+function validateApprovalScope(approvalScope) {
+  if (approvalScope === null || approvalScope === void 0) return null;
+  if (typeof approvalScope !== "string") {
+    throw new TypeError(`approvalScope must be a non-empty string or null, got ${typeof approvalScope}`);
+  }
+  if (!approvalScope) throw new Error("approvalScope must be a non-empty string or null, got ''");
+  return approvalScope;
+}
+function pendingRow(opts, approvalScope) {
   const policy = opts.policy ?? {};
   const frozen = structuredClone(opts.args);
   const createdAt = opts.now ?? /* @__PURE__ */ new Date();
   const timeout = Number(policy.timeout_minutes ?? DEFAULT_TIMEOUT_MINUTES);
   const expiresAt = new Date(createdAt.getTime() + timeout * 6e4);
+  const principals = opts.principals === void 0 || opts.principals === TRUSTED ? null : opts.principals;
+  return { frozen, createdAt, expiresAt, principals, approvalScope };
+}
+async function insertPending(engine, opts, row) {
   const id = randomUUID();
   await engine.pool.query(
     `INSERT INTO context_engine_tool_approvals
-      (id, tool_name, tool_args_frozen, source_id, principals, status, expires_at, created_at)
-     VALUES ($1,$2,$3::jsonb,$4,$5::jsonb,'pending',$6,$7)`,
+      (id, tool_name, tool_args_frozen, source_id, approval_scope, principals, status, expires_at, created_at)
+     VALUES ($1,$2,$3::jsonb,$4,$5,$6::jsonb,'pending',$7,$8)`,
     [
       id,
       opts.toolName,
-      JSON.stringify(frozen),
+      JSON.stringify(row.frozen),
       opts.sourceId ?? null,
-      opts.principals === void 0 ? null : JSON.stringify(opts.principals),
-      expiresAt,
-      createdAt
+      row.approvalScope,
+      row.principals === null ? null : JSON.stringify(row.principals),
+      row.expiresAt,
+      row.createdAt
     ]
   );
   return {
     id,
     toolName: opts.toolName,
-    toolArgsFrozen: frozen,
+    toolArgsFrozen: row.frozen,
     sourceId: opts.sourceId ?? null,
-    principals: opts.principals ?? null,
+    approvalScope: row.approvalScope,
+    principals: row.principals,
     status: "pending",
     approver: null,
     approverMeta: null,
-    expiresAt,
+    expiresAt: row.expiresAt,
     resolvedAt: null,
-    createdAt
+    createdAt: row.createdAt
   };
 }
+async function createPending(engine, opts) {
+  const approvalScope = validateApprovalScope(opts.approvalScope);
+  return insertPending(engine, opts, pendingRow(opts, approvalScope));
+}
+async function findOrCreatePending(engine, opts) {
+  const approvalScope = validateApprovalScope(opts.approvalScope);
+  if (approvalScope === null)
+    throw new Error("findOrCreatePending requires an approvalScope; use createPending");
+  const row = pendingRow(opts, approvalScope);
+  const frozenJson = JSON.stringify(row.frozen);
+  const sameCall = `tool_name = $1 AND approval_scope = $2 AND tool_args_frozen = $3::jsonb`;
+  const params = [opts.toolName, approvalScope, frozenJson, row.createdAt];
+  await engine.pool.query(
+    `UPDATE context_engine_tool_approvals SET status = 'expired'
+     WHERE ${sameCall} AND status = 'pending' AND expires_at <= $4`,
+    params
+  );
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const found = await engine.pool.query(
+      `SELECT * FROM context_engine_tool_approvals
+       WHERE ${sameCall} AND status = 'pending' AND (expires_at IS NULL OR expires_at > $4)
+       ORDER BY created_at ASC LIMIT 1`,
+      params
+    );
+    if (found.rows[0]) return rowToRecord(found.rows[0]);
+    try {
+      return await insertPending(engine, opts, row);
+    } catch (exc) {
+      if (exc?.code !== "23505") throw exc;
+    }
+  }
+  throw new Error("findOrCreatePending: lost the insert race twice and found no live pending row");
+}
 async function resolveApproval(engine, approvalId, decision, approver, meta = null, opts = {}) {
   if (decision !== "approved" && decision !== "rejected") {
     throw new Error(`invalid decision: ${JSON.stringify(decision)} (expected 'approved' or 'rejected')`);
@@ -778,6 +863,10 @@ async function listApprovals(engine, opts = {}) {
     params.push(opts.sourceId);
     clauses.push(`source_id = $${params.length}`);
   }
+  if (opts.approvalScope != null) {
+    params.push(opts.approvalScope);
+    clauses.push(`approval_scope = $${params.length}`);
+  }
   const vis = visibilitySql(principals, params.length + 1);
   clauses.push(vis.sql);
   params.push(...vis.params);
@@ -805,6 +894,10 @@ var ToolConfig = class _ToolConfig {
   requiresApproval;
   approvalPolicy;
   enabled;
+  /** Engine-opaque user metadata (documents have the same column). Stored
+   * and returned in CLEAR on the admin surface only — secrets go in
+   * `config`, which is encrypted. */
+  metaData;
   constructor(init) {
     this.id = init.id ?? null;
     this.name = init.name;
@@ -816,6 +909,7 @@ var ToolConfig = class _ToolConfig {
     this.requiresApproval = init.requiresApproval ?? init.requires_approval ?? false;
     this.approvalPolicy = init.approvalPolicy ?? init.approval_policy ?? {};
     this.enabled = init.enabled ?? true;
+    this.metaData = init.metaData ?? init.meta_data ?? {};
   }
   static fromUnknown(body) {
     if (!body || typeof body !== "object" || Array.isArray(body)) {
@@ -838,7 +932,8 @@ var ToolConfig = class _ToolConfig {
       acl: b.acl ?? null,
       requiresApproval: Boolean(b.requiresApproval ?? b.requires_approval ?? false),
       approvalPolicy: b.approvalPolicy ?? b.approval_policy ?? {},
-      enabled: b.enabled === void 0 ? true : Boolean(b.enabled)
+      enabled: b.enabled === void 0 ? true : Boolean(b.enabled),
+      metaData: b.metaData ?? b.meta_data ?? {}
     });
   }
 };
@@ -857,9 +952,26 @@ var SCHEMAS = {
         additionalProperties: { type: "string" },
         writeOnly: true
       },
+      // The request body TEMPLATE (the http executor reads it). Whether it
+      // round-trips is the USER's call — see `body_secret` and the
+      // conditional in `redactConfig`; listing it documents the shape, the
+      // redactor decides.
+      body: {
+        description: "Request body template; top-level keys merge with LLM parameters"
+      },
+      // Salman (2026-08-18): "give checkbox to user" — the author declares
+      // whether their body carries secrets. True (or ABSENT — every pre-flag
+      // row, fail closed) masks body values like headers; an explicit false
+      // round-trips the body in clear like `url`. The flag round-trips.
+      body_secret: {
+        type: "boolean",
+        description: "Body values are write-only (mask like headers)"
+      },
       parameters: {
         type: "object",
-        description: "Static/user-fixed parameters sent on every call"
+        description: "Static/user-fixed parameters sent on every call",
+        // The canonical home of a static api_key — secret by position.
+        writeOnly: true
       },
       llmParameters: {
         type: "object",
@@ -890,7 +1002,13 @@ var SCHEMAS = {
         default: "readonly"
       },
       max_rows: { type: "integer", default: 1e3 },
-      selected_tables: { type: "array", items: { type: "string" } }
+      selected_tables: { type: "array", items: { type: "string" } },
+      // Dialect connection identifiers the db executor reads — same
+      // sensitivity class as `database`, listed so they round-trip instead
+      // of dying to redactConfig's default-deny.
+      service_name: { type: "string" },
+      schema_name: { type: "string" },
+      warehouse: { type: "string" }
     },
     required: ["engine", "database"]
   },
@@ -922,11 +1040,306 @@ function configSchema(kind) {
   if (!schema) throw new Error(`unknown tool kind: ${JSON.stringify(kind)}`);
   return schema;
 }
+var REDACTED_SENTINEL = "__redacted__";
+var ConfigTemplateError = class extends Error {
+};
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function maskValue(value) {
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = maskValue(v);
+    return out;
+  }
+  if (Array.isArray(value)) return value.map(maskValue);
+  return REDACTED_SENTINEL;
+}
+function containsSentinel(value) {
+  if (typeof value === "string") return value === REDACTED_SENTINEL;
+  if (Array.isArray(value)) return value.some(containsSentinel);
+  if (isPlainObject(value)) return Object.values(value).some(containsSentinel);
+  return false;
+}
+function redactConfig(kind, config) {
+  const props = (SCHEMAS[kind]?.properties ?? {}) || {};
+  const out = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (kind === "http" && key === "body") {
+      out[key] = config.body_secret === false ? structuredClone(value) : maskValue(value);
+      continue;
+    }
+    const spec = props[key];
+    if (spec === void 0 || spec.writeOnly) {
+      out[key] = maskValue(value);
+    } else {
+      out[key] = structuredClone(value);
+    }
+  }
+  return out;
+}
+function mergeRedacted(incoming, stored) {
+  const resolve = (value, kept, keptPresent, path) => {
+    if (isPlainObject(value)) {
+      const keptDict = isPlainObject(kept) ? kept : {};
+      const out2 = {};
+      for (const [k, v] of Object.entries(value)) {
+        out2[k] = resolve(v, keptDict[k], k in keptDict, path ? `${path}.${k}` : k);
+      }
+      return out2;
+    }
+    if (Array.isArray(value)) {
+      const keptList = Array.isArray(kept) ? kept : [];
+      return value.map((v, i) => resolve(v, keptList[i], i < keptList.length, `${path}[${i}]`));
+    }
+    if (value === REDACTED_SENTINEL) {
+      if (!keptPresent) {
+        throw new ConfigTemplateError(
+          `config.${path} is ${JSON.stringify(REDACTED_SENTINEL)} but there is no stored value to keep \u2014 re-enter the secret or omit the field`
+        );
+      }
+      return kept;
+    }
+    return value;
+  };
+  const keptRoot = stored ?? {};
+  const out = {};
+  for (const [k, v] of Object.entries(incoming)) {
+    out[k] = resolve(v, keptRoot[k], k in keptRoot, k);
+  }
+  return out;
+}
+function encryptDict(data, key) {
+  const nonce = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  const plaintext = Buffer.from(JSON.stringify(data), "utf8");
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([nonce, ciphertext, tag]).toString("base64");
+}
+function decryptDict(token, key) {
+  const raw = Buffer.from(token, "base64");
+  const nonce = raw.subarray(0, 12);
+  const tag = raw.subarray(raw.length - 16);
+  const ciphertext = raw.subarray(12, raw.length - 16);
+  const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+  decipher.setAuthTag(tag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return JSON.parse(plaintext.toString("utf8"));
+}
+function getSecretKey(config) {
+  const secretKey = config.secretKey;
+  if (!secretKey) {
+    throw new Error(
+      "ContextEngineConfig.secretKey (env CE_SECRET_KEY) is not configured \u2014 a base64url-encoded 32-byte AES key is required to encrypt/decrypt tool configs that hold secrets."
+    );
+  }
+  return Buffer.from(secretKey, "base64url");
+}
+function hmacSha256Hex(key, value) {
+  const k = typeof key === "string" ? Buffer.from(key) : key;
+  return createHmac("sha256", k).update(value, "utf8").digest("hex");
+}
+var MAX_RESPONSE_BYTES = 1e6;
+var MAX_REDIRECTS = 5;
+function isRedirect(resp) {
+  return resp.status >= 300 && resp.status < 400 || resp.type === "opaqueredirect";
+}
+var EgressDenied = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EgressDenied";
+  }
+};
+var resolver = {
+  async lookup(host) {
+    const answers = await promises.lookup(host, { all: true, verbatim: true });
+    return answers.map((a) => a.address);
+  }
+};
+var V4_PRIVATE = [
+  ["0.0.0.0", 8],
+  // "this network" / unspecified
+  ["10.0.0.0", 8],
+  // RFC 1918
+  ["100.64.0.0", 10],
+  // RFC 6598 carrier-grade NAT — overlay VPNs, pod CIDRs
+  ["127.0.0.0", 8],
+  // loopback
+  ["169.254.0.0", 16],
+  // link-local, incl. the cloud metadata address
+  ["172.16.0.0", 12],
+  // RFC 1918
+  ["192.168.0.0", 16],
+  // RFC 1918
+  ["224.0.0.0", 4],
+  // multicast
+  ["240.0.0.0", 4],
+  // reserved
+  ["255.255.255.255", 32]
+  // broadcast (inside 240/4; spelled out anyway)
+];
+var V6_PRIVATE = [
+  ["::", 128],
+  // unspecified
+  ["::1", 128],
+  // loopback
+  ["::ffff:0:0", 96],
+  // IPv4-mapped — the wrapped v4 is checked too
+  ["64:ff9b::", 96],
+  // NAT64 — the wrapped v4 is checked too
+  ["2002::", 16],
+  // 6to4 — the wrapped v4 is checked too, and this is denied
+  ["fc00::", 7],
+  // unique local
+  ["fe80::", 10],
+  // link-local
+  ["fec0::", 10],
+  // site-local (deprecated, still configured)
+  ["ff00::", 8],
+  // multicast
+  ["3fff::", 20]
+  // documentation
+];
+function parseV4(text) {
+  const parts = text.split(".");
+  if (parts.length !== 4) return null;
+  const out = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) {
+    const part = parts[i];
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const value = Number(part);
+    if (value > 255) return null;
+    out[i] = value;
+  }
+  return out;
+}
+function parseV6(text) {
+  let body = text.split("%")[0] ?? "";
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon < 0) return null;
+  const tail = body.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const v4 = parseV4(tail);
+    if (!v4) return null;
+    const hi = (v4[0] << 8 | v4[1]).toString(16);
+    const lo = (v4[2] << 8 | v4[3]).toString(16);
+    body = `${body.slice(0, lastColon + 1)}${hi}:${lo}`;
+  }
+  const halves = body.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const rest = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  let groups;
+  if (halves.length === 1) {
+    if (head.length !== 8) return null;
+    groups = head;
+  } else {
+    const missing = 8 - head.length - rest.length;
+    if (missing < 0) return null;
+    groups = [...head, ...Array(missing).fill("0"), ...rest];
+  }
+  const out = new Uint8Array(16);
+  for (let i = 0; i < 8; i++) {
+    const group = groups[i];
+    if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+    const value = Number.parseInt(group, 16);
+    out[2 * i] = value >> 8;
+    out[2 * i + 1] = value & 255;
+  }
+  return out;
+}
+function parseAddress(text) {
+  const family = isIP(text);
+  if (family === 4) return parseV4(text);
+  if (family === 6) return parseV6(text);
+  return null;
+}
+function inNet(addr, net, prefix) {
+  if (addr.length !== net.length) return false;
+  const whole = prefix >> 3;
+  for (let i = 0; i < whole; i++) if (addr[i] !== net[i]) return false;
+  const bits = prefix & 7;
+  if (bits === 0) return true;
+  const mask = 255 << 8 - bits;
+  return (addr[whole] & mask) === (net[whole] & mask);
+}
+function compile(table) {
+  return table.map(([cidr, prefix]) => {
+    const bytes = parseAddress(cidr);
+    if (!bytes) throw new Error(`egress: unparseable network ${cidr}`);
+    return [bytes, prefix];
+  });
+}
+var V4_NETS = compile(V4_PRIVATE);
+var V6_NETS = compile(V6_PRIVATE);
+var MAPPED_V4 = compile([["::ffff:0:0", 96]])[0];
+var NAT64 = compile([["64:ff9b::", 96]])[0];
+var SIXTOFOUR = compile([["2002::", 16]])[0];
+function embeddedV4(bytes) {
+  if (inNet(bytes, MAPPED_V4[0], MAPPED_V4[1]) || inNet(bytes, NAT64[0], NAT64[1])) {
+    return bytes.subarray(12, 16);
+  }
+  if (inNet(bytes, SIXTOFOUR[0], SIXTOFOUR[1])) return bytes.subarray(2, 6);
+  return null;
+}
+function addressIsPrivate(address) {
+  const bytes = parseAddress(address);
+  if (!bytes) return true;
+  if (bytes.length === 4) return V4_NETS.some(([net, prefix]) => inNet(bytes, net, prefix));
+  const embedded = embeddedV4(bytes);
+  if (embedded && V4_NETS.some(([net, prefix]) => inNet(embedded, net, prefix))) return true;
+  return V6_NETS.some(([net, prefix]) => inNet(bytes, net, prefix));
+}
+async function isPrivateAddress(host) {
+  let name = (host ?? "").trim().toLowerCase().replace(/^\.+|\.+$/g, "");
+  if (!name) return true;
+  if (name === "localhost") return true;
+  if (name.startsWith("[") && name.endsWith("]")) name = name.slice(1, -1);
+  if (isIP(name)) return addressIsPrivate(name);
+  let addresses;
+  try {
+    addresses = await resolver.lookup(name);
+  } catch {
+    return true;
+  }
+  if (!addresses.length) return true;
+  return addresses.some((address) => addressIsPrivate(address.split("%")[0] ?? address));
+}
+async function assertEgressAllowed(url, opts) {
+  let parsed;
+  try {
+    parsed = new URL(url ?? "");
+  } catch {
+    throw new EgressDenied(`egress denied: ${JSON.stringify(url)} is not a valid URL`);
+  }
+  const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+  if (scheme !== "http" && scheme !== "https") {
+    throw new EgressDenied(
+      `egress denied: unsupported URL scheme ${JSON.stringify(scheme)} \u2014 http tools may only reach http/https`
+    );
+  }
+  if (opts.allowPrivate) return;
+  const host = parsed.hostname;
+  if (await isPrivateAddress(host)) {
+    throw new EgressDenied(
+      `egress denied: ${host || "(no host)"} is a private, loopback, link-local or metadata address; set allowPrivateEgress to permit it`
+    );
+  }
+}
 
 // src/version.ts
 var __version__ = "0.0.0";
 
 // src/tools/executors/mcp-client.ts
+async function checkEgress(url, allowPrivate) {
+  let checked = url;
+  const scheme = (/^([a-z0-9+.-]+):/i.exec(url ?? "")?.[1] ?? "").toLowerCase();
+  if (scheme === "ws") checked = `http:${url.slice(scheme.length + 1)}`;
+  else if (scheme === "wss") checked = `https:${url.slice(scheme.length + 1)}`;
+  await assertEgressAllowed(checked, { allowPrivate });
+}
+var REDIRECT_MESSAGE = "MCP server redirected; register the final URL";
 var MCPError = class _MCPError extends Error {
   code;
   data;
@@ -955,10 +1368,12 @@ function parseSseBuffer(raw) {
 var HttpTransport = class {
   kind = "http";
   url;
+  allowPrivate;
   baseHeaders;
   sessionId = null;
-  constructor(url, headers) {
+  constructor(url, headers, allowPrivate = false) {
     this.url = url;
+    this.allowPrivate = allowPrivate;
     this.baseHeaders = {
       ...headers,
       "Content-Type": "application/json",
@@ -966,6 +1381,7 @@ var HttpTransport = class {
     };
   }
   async connect() {
+    await checkEgress(this.url, this.allowPrivate);
   }
   async close() {
     this.sessionId = null;
@@ -979,10 +1395,17 @@ var HttpTransport = class {
     const resp = await fetch(this.url, {
       method: "POST",
       headers: this.buildHeaders(),
-      body: JSON.stringify(msg)
+      body: JSON.stringify(msg),
+      // `redirect: "manual"`: a followed redirect would carry this POST —
+      // headers, Authorization and all — to a destination `connect()`'s
+      // check never saw. A 3xx is reported, never chased.
+      redirect: "manual"
     });
     const sid = resp.headers.get("Mcp-Session-Id");
     if (sid) this.sessionId = sid;
+    if (isRedirect(resp)) {
+      throw new MCPError(resp.status, REDIRECT_MESSAGE);
+    }
     if (resp.status >= 400) {
       const body = await resp.text();
       console.error(`[HTTP Transport] ${resp.status} from ${this.url}: ${body.slice(0, 300)}`);
@@ -1015,11 +1438,20 @@ var SseTransport = class {
   eventsUrl;
   baseUrl;
   headers;
+  allowPrivate;
+  /** Where the server told us to POST — it arrives in an `endpoint` event on
+   * the stream, so it is server-chosen and hence checked. Private: the only
+   * way in is the parser, which is the path a real server takes. */
   postUrl = null;
+  /** The last POST endpoint cleared by the egress check. The check costs a
+   * DNS resolution and the endpoint changes at most once per connection, so
+   * it is not repeated per message. */
+  checkedPostUrl = null;
   queue = [];
   waiters = [];
   abort = null;
-  constructor(url, headers) {
+  constructor(url, headers, allowPrivate = false) {
+    this.allowPrivate = allowPrivate;
     this.eventsUrl = url.replace(/\/$/, "");
     if (url.endsWith("/events")) this.baseUrl = url.slice(0, -7);
     else if (url.endsWith("/sse")) this.baseUrl = url.slice(0, -4);
@@ -1032,14 +1464,19 @@ var SseTransport = class {
     else this.queue.push(msg);
   }
   async connect() {
+    await checkEgress(this.eventsUrl, this.allowPrivate);
     this.abort = new AbortController();
     void this.listen();
   }
   async listen() {
     const resp = await fetch(this.eventsUrl, {
       headers: { ...this.headers, Accept: "text/event-stream" },
-      signal: this.abort?.signal
+      signal: this.abort?.signal,
+      redirect: "manual"
     });
+    if (isRedirect(resp)) {
+      throw new MCPError(resp.status, REDIRECT_MESSAGE);
+    }
     if (!resp.ok) throw new Error(`SSE ${resp.status}`);
     if (!resp.body) throw new Error("SSE response has no body");
     const reader = resp.body.getReader();
@@ -1091,11 +1528,19 @@ var SseTransport = class {
       }
     }
     const postUrl = this.postUrl || this.baseUrl;
+    if (postUrl !== this.checkedPostUrl) {
+      await checkEgress(postUrl, this.allowPrivate);
+      this.checkedPostUrl = postUrl;
+    }
     const resp = await fetch(postUrl, {
       method: "POST",
       headers: { ...this.headers, "Content-Type": "application/json" },
-      body: JSON.stringify(msg)
+      body: JSON.stringify(msg),
+      redirect: "manual"
     });
+    if (isRedirect(resp)) {
+      throw new MCPError(resp.status, REDIRECT_MESSAGE);
+    }
     if (!resp.ok) throw new Error(`SSE POST ${resp.status}`);
     try {
       const data = await resp.json();
@@ -1114,14 +1559,17 @@ var WsTransport = class {
   kind = "websocket";
   url;
   headers;
+  allowPrivate;
   ws = null;
   queue = [];
   waiters = [];
-  constructor(url, headers) {
+  constructor(url, headers, allowPrivate = false) {
     this.url = url;
+    this.allowPrivate = allowPrivate;
     this.headers = headers;
   }
   async connect() {
+    await checkEgress(this.url, this.allowPrivate);
     const WS = globalThis.WebSocket;
     if (!WS) throw new Error("WebSocket is not available in this runtime");
     this.ws = new WS(this.url);
@@ -1162,21 +1610,27 @@ var MCPClient = class _MCPClient {
   tools = [];
   resources = [];
   headers;
-  constructor(url, headers = null) {
+  allowPrivate;
+  constructor(url, headers = null, opts = {}) {
     this.url = url;
     this.headers = headers ?? {};
-    this.transport = _MCPClient.createTransport(url, this.headers);
+    this.allowPrivate = opts.allowPrivate ?? false;
+    this.transport = _MCPClient.createTransport(url, this.headers, this.allowPrivate);
   }
-  static createTransport(url, headers) {
+  static createTransport(url, headers, allowPrivate = false) {
     if (url.startsWith("stdio:") || url === "stdio") {
       throw new Error("stdio MCP transport is not supported (cloud deployments use SSE/HTTP/WebSocket)");
     }
-    if (url.startsWith("ws://") || url.startsWith("wss://")) return new WsTransport(url, headers);
+    if (url.startsWith("ws://") || url.startsWith("wss://")) {
+      return new WsTransport(url, headers, allowPrivate);
+    }
     if (url.startsWith("sse+http://") || url.startsWith("sse+https://") || url.endsWith("/events") || url.endsWith("/sse")) {
       const clean = url.replace("sse+http://", "http://").replace("sse+https://", "https://");
-      return new SseTransport(clean, headers);
+      return new SseTransport(clean, headers, allowPrivate);
+    }
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      return new HttpTransport(url, headers, allowPrivate);
     }
-    if (url.startsWith("http://") || url.startsWith("https://")) return new HttpTransport(url, headers);
     throw new Error(`Unsupported URL: ${url} (use http(s)://, ws(s)://, or .../sse)`);
   }
   nextId() {
@@ -1228,7 +1682,15 @@ var MCPClient = class _MCPClient {
     await this.transport.send({ jsonrpc: "2.0", method, params: params ?? {} });
   }
   async connect() {
-    await this.transport.connect();
+    try {
+      await this.transport.connect();
+    } catch (e) {
+      try {
+        await this.transport.close();
+      } catch {
+      }
+      throw e;
+    }
     if (!(this.transport instanceof HttpTransport)) {
       this.connected = true;
       void this.recvLoop();
@@ -1311,7 +1773,7 @@ var MCPClient = class _MCPClient {
     }
     this.id = 0;
     this.pending.clear();
-    this.transport = _MCPClient.createTransport(url, headers);
+    this.transport = _MCPClient.createTransport(url, headers, this.allowPrivate);
     await this.connect();
     await this.listTools();
   }
@@ -1319,11 +1781,11 @@ var MCPClient = class _MCPClient {
 var MCPRegistry = class {
   clients = /* @__PURE__ */ new Map();
   healthTask = null;
-  async connect(name, url, headers = null, token = null) {
+  async connect(name, url, headers = null, token = null, allowPrivate = false) {
     this.clients.delete(name);
     const hdrs = { ...headers ?? {} };
     if (token) hdrs.Authorization = hdrs.Authorization ?? `Bearer ${token}`;
-    const client = new MCPClient(url, hdrs);
+    const client = new MCPClient(url, hdrs, { allowPrivate });
     await client.connect();
     await client.listTools();
     this.clients.set(name, client);
@@ -1375,8 +1837,18 @@ var MCPRegistry = class {
 };
 var PromptevMCP = class {
   clients = new MCPRegistry();
+  allowPrivate;
+  /**
+   * `allowPrivate` is the operator knob `allowPrivateEgress`, carried down to
+   * every transport this facade builds. It defaults to `false`, so a
+   * construction site that forgets to pass it denies private destinations
+   * rather than permitting them.
+   */
+  constructor(opts = {}) {
+    this.allowPrivate = opts.allowPrivate ?? false;
+  }
   async addServer(name, url, opts = {}) {
-    await this.clients.connect(name, url, opts.headers ?? null, opts.token ?? null);
+    await this.clients.connect(name, url, opts.headers ?? null, opts.token ?? null, this.allowPrivate);
   }
   async shutdown() {
     await this.clients.shutdown();
@@ -1416,37 +1888,6 @@ function emitToolCall(hooks, event) {
     log.warn("onToolCall callback raised; swallowing");
   }
 }
-function encryptDict(data, key) {
-  const nonce = randomBytes(12);
-  const cipher = createCipheriv("aes-256-gcm", key, nonce);
-  const plaintext = Buffer.from(JSON.stringify(data), "utf8");
-  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
-  const tag = cipher.getAuthTag();
-  return Buffer.concat([nonce, ciphertext, tag]).toString("base64");
-}
-function decryptDict(token, key) {
-  const raw = Buffer.from(token, "base64");
-  const nonce = raw.subarray(0, 12);
-  const tag = raw.subarray(raw.length - 16);
-  const ciphertext = raw.subarray(12, raw.length - 16);
-  const decipher = createDecipheriv("aes-256-gcm", key, nonce);
-  decipher.setAuthTag(tag);
-  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-  return JSON.parse(plaintext.toString("utf8"));
-}
-function getSecretKey(config) {
-  const secretKey = config.secretKey;
-  if (!secretKey) {
-    throw new Error(
-      "ContextEngineConfig.secretKey (env CE_SECRET_KEY) is not configured \u2014 a base64url-encoded 32-byte AES key is required to encrypt/decrypt tool configs that hold secrets."
-    );
-  }
-  return Buffer.from(secretKey, "base64url");
-}
-function hmacSha256Hex(key, value) {
-  const k = typeof key === "string" ? Buffer.from(key) : key;
-  return createHmac("sha256", k).update(value, "utf8").digest("hex");
-}
 
 // src/redaction.ts
 var EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
@@ -1726,6 +2167,7 @@ async function logToolCall(engine, row) {
 init_db();
 
 // src/tools/executors/http.ts
+init_errors();
 var TIMEOUT_MS = 3e4;
 var SENSITIVE_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
   "set-cookie",
@@ -1734,6 +2176,8 @@ var SENSITIVE_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
   "proxy-authenticate",
   "www-authenticate"
 ]);
+var REDIRECT_STATUS = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
+var CROSS_ORIGIN_HEADERS = /* @__PURE__ */ new Set(["authorization", "proxy-authorization", "cookie"]);
 function percentEncode(value) {
   return encodeURIComponent(value).replace(
     /[!'()*]/g,
@@ -1764,10 +2208,38 @@ function withQuery(url, params) {
   if (!q) return url;
   return url.includes("?") ? `${url}&${q}` : `${url}?${q}`;
 }
+async function readCapped(resp) {
+  if (!resp.body) return { text: await resp.text(), truncated: false };
+  const reader = resp.body.getReader();
+  const chunks = [];
+  let size = 0;
+  let truncated = false;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(Buffer.from(value));
+      size += value.byteLength;
+    }
+    if (size > MAX_RESPONSE_BYTES) {
+      truncated = true;
+      await reader.cancel();
+      break;
+    }
+  }
+  const bytes = Buffer.concat(chunks);
+  return {
+    text: (truncated ? bytes.subarray(0, MAX_RESPONSE_BYTES) : bytes).toString("utf8"),
+    truncated
+  };
+}
 async function defaultRequest(init) {
   let url = init.url;
   if (init.params) url = withQuery(url, init.params);
   const headers = { ...init.headers ?? {} };
+  if (!Object.keys(headers).some((k) => k.toLowerCase() === "accept-encoding")) {
+    headers["Accept-Encoding"] = "identity";
+  }
   let body;
   if (init.json !== void 0) {
     headers["Content-Type"] = headers["Content-Type"] ?? headers["content-type"] ?? "application/json";
@@ -1779,25 +2251,47 @@ async function defaultRequest(init) {
     method: init.method,
     headers,
     body,
-    redirect: "follow",
+    // Redirects are followed by hand in `executeHttp` — an automatic follow
+    // would jump to a destination no egress check ever saw.
+    redirect: "manual",
     signal: AbortSignal.timeout(TIMEOUT_MS)
   });
   const respHeaders = {};
   resp.headers.forEach((v, k) => {
     respHeaders[k] = v;
   });
-  const text = await resp.text();
+  const { text, truncated } = await readCapped(resp);
   return {
     status: resp.status,
     headers: respHeaders,
+    truncated,
     async json() {
-      return JSON.parse(text);
+      return JSON.parse(text.replace(/^/, ""));
     },
     async text() {
       return text;
     }
   };
 }
+function nextHop(init, status, location) {
+  const current = new URL(init.url);
+  const target = new URL(location, current);
+  let method = init.method;
+  if ((status === 302 || status === 303) && method !== "HEAD") method = "GET";
+  else if (status === 301 && method === "POST") method = "GET";
+  let headers = { ...init.headers ?? {} };
+  if (current.origin !== target.origin) {
+    headers = Object.fromEntries(
+      Object.entries(headers).filter(([k]) => !CROSS_ORIGIN_HEADERS.has(k.toLowerCase()))
+    );
+  }
+  const hop = { method, url: target.toString(), headers };
+  if (method === init.method) {
+    if (init.json !== void 0) hop.json = init.json;
+    if (init.content !== void 0) hop.content = init.content;
+  }
+  return hop;
+}
 async function executeHttp(config, args, opts = {}) {
   const method = String(config.method ?? "GET").toUpperCase();
   let url = config.url;
@@ -1818,7 +2312,7 @@ async function executeHttp(config, args, opts = {}) {
       }
     }
   }
-  const requestInit = {
+  let requestInit = {
     method,
     url: url ?? "",
     headers
@@ -1854,23 +2348,50 @@ async function executeHttp(config, args, opts = {}) {
     }
   }
   const client = opts.client;
-  const resp = client ? await client.request(requestInit) : await defaultRequest(requestInit);
+  const allowPrivate = opts.allowPrivate ?? false;
+  let resp;
+  let hops = 0;
+  for (; ; ) {
+    await assertEgressAllowed(requestInit.url, { allowPrivate });
+    resp = client ? await client.request(requestInit) : await defaultRequest(requestInit);
+    const location = resp.headers.location ?? resp.headers.Location;
+    if (!REDIRECT_STATUS.has(resp.status) || !location) break;
+    if (hops >= MAX_REDIRECTS) {
+      throw new EngineActionError(`too many redirects (more than ${MAX_REDIRECTS}) starting at ${url}`);
+    }
+    hops += 1;
+    requestInit = nextHop(requestInit, resp.status, location);
+  }
   const contentType = resp.headers["content-type"] ?? resp.headers["Content-Type"] ?? "";
-  let data;
+  let text = "";
   try {
-    data = contentType.includes("application/json") ? await resp.json() : await resp.text();
+    text = await resp.text();
   } catch {
-    data = await resp.text();
+    text = "";
+  }
+  const bytes = Buffer.from(text, "utf8");
+  const truncated = resp.truncated === true || bytes.byteLength > MAX_RESPONSE_BYTES;
+  let data;
+  if (truncated) {
+    data = bytes.subarray(0, MAX_RESPONSE_BYTES).toString("utf8");
+  } else {
+    try {
+      data = contentType.includes("application/json") ? await resp.json() : text;
+    } catch {
+      data = text;
+    }
   }
   const safeHeaders = {};
   for (const [k, v] of Object.entries(resp.headers)) {
     if (!SENSITIVE_RESPONSE_HEADERS.has(k.toLowerCase())) safeHeaders[k] = v;
   }
-  return {
+  const result = {
     status_code: resp.status,
     headers: safeHeaders,
     data
   };
+  if (truncated) result.truncated = true;
+  return result;
 }
 
 // src/tools/registry.ts
@@ -2000,8 +2521,13 @@ var UPDATABLE_COLUMNS = /* @__PURE__ */ new Set([
   "requires_approval",
   "approvalPolicy",
   "approval_policy",
-  "enabled"
+  "enabled",
+  "metaData",
+  "meta_data"
 ]);
+function allowPrivateEgress(engine) {
+  return Boolean(engine?.config?.allowPrivateEgress);
+}
 function toolVisible(ct, principals) {
   return aclVisible(ct.acl, principals);
 }
@@ -2083,11 +2609,19 @@ function redactToolResult(result, policy, opts) {
   if (failed.length) note.rules_failed = failed;
   return [redacted, note];
 }
-function rowToToolConfig(row, engine) {
-  let config = {};
-  if (row.config_encrypted) {
-    config = decryptDict(String(row.config_encrypted), getSecretKey(engine.config));
+function cryptoKey(engine) {
+  const key = getSecretKey(engine.config);
+  if (key.length !== 32) {
+    throw new Error(`CE_SECRET_KEY is malformed: decoded to ${key.length} bytes, need 32`);
   }
+  return key;
+}
+function decryptRowConfig(row, engine) {
+  if (!row.config_encrypted) return {};
+  return decryptDict(String(row.config_encrypted), cryptoKey(engine));
+}
+function rowToToolConfig(row, engine, config) {
+  config ??= decryptRowConfig(row, engine);
   return new ToolConfig({
     id: String(row.id),
     name: String(row.name),
@@ -2098,9 +2632,24 @@ function rowToToolConfig(row, engine) {
     acl: row.acl != null ? [...row.acl] : null,
     requiresApproval: Boolean(row.requires_approval),
     approvalPolicy: row.approval_policy ?? {},
-    enabled: Boolean(row.enabled)
+    enabled: Boolean(row.enabled),
+    metaData: row.meta_data ?? {}
   });
 }
+function rowToToolConfigLenient(row, engine) {
+  if (!row.config_encrypted) return rowToToolConfig(row, engine, {});
+  const key = cryptoKey(engine);
+  let config;
+  try {
+    config = decryptDict(String(row.config_encrypted), key);
+  } catch {
+    console.warn(
+      `tool ${String(row.id)} (${String(row.name)}): config_error \u2014 its stored config could not be decrypted (was the secret key rotated?); leaving it out of the tool set`
+    );
+    return null;
+  }
+  return rowToToolConfig(row, engine, config);
+}
 async function loadPersistedCanonicals(engine, sourceId) {
   const params = [];
   let sql = `SELECT * FROM context_engine_tools WHERE enabled IS TRUE`;
@@ -2111,7 +2660,9 @@ async function loadPersistedCanonicals(engine, sourceId) {
   const result = await engine.pool.query(sql, params);
   const canonicals = [];
   for (const row of result.rows) {
-    canonicals.push(...canonicalFromConfig(rowToToolConfig(row, engine)));
+    const tc = rowToToolConfigLenient(row, engine);
+    if (tc === null) continue;
+    canonicals.push(...canonicalFromConfig(tc));
   }
   return canonicals;
 }
@@ -2123,13 +2674,18 @@ async function mergedTools(engine, sourceId) {
 async function registerTool(engine, tc) {
   canonicalFromConfig(tc);
   const config = tc.config ?? {};
-  const configEncrypted = Object.keys(config).length ? encryptDict(config, getSecretKey(engine.config)) : null;
+  if (containsSentinel(config)) {
+    throw new ConfigTemplateError(
+      `config contains the ${JSON.stringify(REDACTED_SENTINEL)} placeholder \u2014 a redacted template cannot be registered as a new tool; re-enter the secret values`
+    );
+  }
+  const configEncrypted = Object.keys(config).length ? encryptDict(config, cryptoKey(engine)) : null;
   const id = randomUUID();
   await engine.pool.query(
     `INSERT INTO context_engine_tools
        (id, name, kind, description, source_id, acl, config_encrypted,
-        requires_approval, approval_policy, enabled)
-     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10)`,
+        requires_approval, approval_policy, enabled, meta_data)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11::jsonb)`,
     [
       id,
       tc.name,
@@ -2140,7 +2696,8 @@ async function registerTool(engine, tc) {
       configEncrypted,
       tc.requiresApproval,
       JSON.stringify(tc.approvalPolicy ?? {}),
-      tc.enabled
+      tc.enabled,
+      JSON.stringify(tc.metaData ?? {})
     ]
   );
   return id;
@@ -2157,12 +2714,41 @@ async function updateTool(engine, id, opts) {
   let i = 1;
   for (const [key, value] of Object.entries(fields)) {
     if (key === "config") {
+      let config = value;
+      if (config && containsSentinel(config)) {
+        if (Object.hasOwn(fields, "kind") && fields.kind !== row.kind) {
+          throw new ConfigTemplateError(
+            "cannot change kind and keep redacted secrets in one PATCH \u2014 re-enter the config in full"
+          );
+        }
+        if (config.body_secret === false && containsSentinel(config.body)) {
+          throw new ConfigTemplateError(
+            `body_secret cannot be turned off while the body still contains ${JSON.stringify(REDACTED_SENTINEL)} \u2014 re-enter the body to declassify it`
+          );
+        }
+        if (!row.config_encrypted) {
+          throw new ConfigTemplateError(
+            `config contains ${JSON.stringify(REDACTED_SENTINEL)} but this tool has no stored config to keep \u2014 re-enter the secret values`
+          );
+        }
+        const key2 = cryptoKey(engine);
+        let stored;
+        try {
+          stored = decryptDict(String(row.config_encrypted), key2);
+        } catch (exc) {
+          throw new ConfigTemplateError(
+            `the stored config cannot be decrypted (was the secret key rotated?) \u2014 re-enter the config in full, without ${JSON.stringify(REDACTED_SENTINEL)} values`,
+            { cause: exc }
+          );
+        }
+        config = mergeRedacted(config, stored);
+      }
       sets.push(`config_encrypted = $${i++}`);
-      params.push(value ? encryptDict(value, getSecretKey(engine.config)) : null);
+      params.push(config && Object.keys(config).length ? encryptDict(config, cryptoKey(engine)) : null);
     } else if (UPDATABLE_COLUMNS.has(key)) {
-      const col = key === "sourceId" ? "source_id" : key === "requiresApproval" ? "requires_approval" : key === "approvalPolicy" ? "approval_policy" : key;
+      const col = key === "sourceId" ? "source_id" : key === "requiresApproval" ? "requires_approval" : key === "approvalPolicy" ? "approval_policy" : key === "metaData" ? "meta_data" : key;
       sets.push(`${col} = $${i++}`);
-      params.push(col === "approval_policy" ? JSON.stringify(value ?? {}) : value);
+      params.push(col === "approval_policy" || col === "meta_data" ? JSON.stringify(value ?? {}) : value);
     }
   }
   sets.push(`updated_at = now()`);
@@ -2171,7 +2757,8 @@ async function updateTool(engine, id, opts) {
     `UPDATE context_engine_tools SET ${sets.join(", ")} WHERE id = $${i} RETURNING *`,
     params
   );
-  return rowToToolConfig(updated.rows[0], engine);
+  const row_ = updated.rows[0];
+  return rowToToolConfigLenient(row_, engine) ?? rowToToolConfig(row_, engine, {});
 }
 async function deleteTool(engine, id, opts = {}) {
   const existing = await engine.pool.query(`SELECT * FROM context_engine_tools WHERE id = $1`, [id]);
@@ -2238,17 +2825,38 @@ function probeFailure(exc, kind) {
   console.warn(`test_tool(kind=${kind}) failed:`, exc, "->", category);
   return { ok: false, error: category };
 }
-async function testTool(_engine, tc) {
+async function testTool(engine, tc) {
   const kind = tc.kind;
   const config = tc.config ?? {};
+  if (containsSentinel(config)) {
+    throw new ConfigTemplateError(
+      `config contains the ${JSON.stringify(REDACTED_SENTINEL)} placeholder \u2014 a probe would send it verbatim as the credential; re-enter the secret values`
+    );
+  }
   if (kind === "http") {
     const url = config.url;
     if (!url) return { ok: false, error: "http config missing 'url'" };
     try {
-      const resp = await fetch(url, {
+      await assertEgressAllowed(url, { allowPrivate: allowPrivateEgress(engine) });
+    } catch (exc) {
+      if (exc instanceof EgressDenied) {
+        console.warn(`testTool(kind=http) refused: ${exc.message}`);
+        return { ok: false, error: "egress_denied" };
+      }
+      throw exc;
+    }
+    const client = engine?._toolHttpClient ?? null;
+    try {
+      const resp = client ? await client.request({
+        method: "HEAD",
+        url,
+        headers: config.headers ?? {}
+      }) : await fetch(url, {
         method: "HEAD",
         headers: config.headers ?? {},
-        redirect: "follow",
+        // No automatic follow: a redirect would reach a destination the
+        // check above never saw.
+        redirect: "manual",
         signal: AbortSignal.timeout(1e4)
       });
       return { ok: resp.status < 500, status_code: resp.status };
@@ -2269,12 +2877,16 @@ async function testTool(_engine, tc) {
     const url = config.url;
     if (!url) return { ok: false, error: "mcp config missing 'url'" };
     const token = config.oauth_token ?? config.bearer ?? config.access_token;
-    const mcp = new PromptevMCP();
+    const mcp = new PromptevMCP({ allowPrivate: allowPrivateEgress(engine) });
     try {
       await mcp.addServer(tc.name, url, { token: token ?? null });
       const client = mcp.clients.get(tc.name);
       return { ok: true, tools: client.tools.map((t) => t.name) };
     } catch (exc) {
+      if (exc instanceof EgressDenied) {
+        console.warn(`testTool(kind=mcp) refused: ${exc.message}`);
+        return { ok: false, error: "egress_denied" };
+      }
       return probeFailure(exc, "mcp");
     } finally {
       await mcp.shutdown();
@@ -2282,11 +2894,20 @@ async function testTool(_engine, tc) {
   }
   return { ok: false, error: `test_tool does not support kind=${JSON.stringify(kind)}` };
 }
-async function findAndClaimApproved(engine, toolName, args, sourceId) {
+async function findAndClaimApproved(engine, toolName, args, sourceId, principals, approvalScope) {
   const claimedAt = /* @__PURE__ */ new Date();
+  const params = [toolName];
+  let scopeSql = "approval_scope IS NULL";
+  if (approvalScope !== null) {
+    params.push(approvalScope);
+    scopeSql = `approval_scope = $${params.length}`;
+  }
+  const wall = claimVisibilitySql(principals, params.length + 1);
+  params.push(...wall.params);
   const candidates = await engine.pool.query(
-    `SELECT * FROM context_engine_tool_approvals WHERE tool_name = $1 AND status = 'approved'`,
-    [toolName]
+    `SELECT * FROM context_engine_tool_approvals
+     WHERE tool_name = $1 AND status = 'approved' AND ${scopeSql} AND ${wall.sql}`,
+    params
   );
   for (const row of candidates.rows) {
     if ((row.source_id ?? null) !== (sourceId ?? null)) continue;
@@ -2303,7 +2924,7 @@ async function findAndClaimApproved(engine, toolName, args, sourceId) {
   }
   return null;
 }
-async function dispatchMcp(ct, config, args) {
+async function dispatchMcp(ct, config, args, opts = {}) {
   const url = config.url;
   if (!url) throw new EngineActionError(`mcp tool ${ct.callName} config missing 'url'`);
   const headers = { ...config.headers ?? {} };
@@ -2312,7 +2933,7 @@ async function dispatchMcp(ct, config, args) {
   if (token) headers.Authorization = `Bearer ${token}`;
   else if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
   const toolName = String(ct.raw?.tool_name ?? ct.displayName);
-  const mcp = new PromptevMCP();
+  const mcp = new PromptevMCP({ allowPrivate: opts.allowPrivate ?? false });
   try {
     await mcp.addServer(ct.callName, url, { headers: Object.keys(headers).length ? headers : null });
     const client = mcp.clients.get(ct.callName);
@@ -2323,7 +2944,10 @@ async function dispatchMcp(ct, config, args) {
 }
 async function dispatch(engine, ct, config, args) {
   if (ct.kind === "http") {
-    return executeHttp(config, args, { client: engine._toolHttpClient ?? null });
+    return executeHttp(config, args, {
+      client: engine._toolHttpClient ?? null,
+      allowPrivate: allowPrivateEgress(engine)
+    });
   }
   if (ct.kind === "db") {
     const query = String(args.query ?? "");
@@ -2338,7 +2962,9 @@ async function dispatch(engine, ct, config, args) {
     }
     return result;
   }
-  if (ct.kind === "mcp") return dispatchMcp(ct, config, args);
+  if (ct.kind === "mcp") {
+    return dispatchMcp(ct, config, args, { allowPrivate: allowPrivateEgress(engine) });
+  }
   if (ct.kind === "function") {
     const fn = ct.raw?.callable;
     if (!fn) throw new EngineActionError(`function tool ${ct.callName} has no callable`);
@@ -2359,10 +2985,20 @@ async function decryptCtConfig(engine, toolId) {
   ]);
   const row = result.rows[0];
   if (!row?.config_encrypted) return {};
-  return decryptDict(String(row.config_encrypted), getSecretKey(engine.config));
+  return decryptDict(String(row.config_encrypted), cryptoKey(engine));
+}
+var warnedUnscoped = /* @__PURE__ */ new Set();
+function warnUnscopedApproval(callName) {
+  if (warnedUnscoped.has(callName)) return;
+  warnedUnscoped.add(callName);
+  process.emitWarning(
+    `executeTool(${JSON.stringify(callName)}) needs an approval but was called without approvalScope. The record is opened and matched UNSCOPED (tool + args + sourceId, behind the principals wall). Pass approvalScope: <opaque string> (e.g. a run id) so approvals are claimable only within that scope; a gated call without one will be refused in the next release.`,
+    { type: "DeprecationWarning", code: "CE_APPROVAL_SCOPE_MISSING" }
+  );
 }
 async function executeTool(engine, callName, args, opts = {}) {
   const runtimeArgs = args ?? {};
+  const approvalScope = validateApprovalScope(opts.approvalScope);
   const ct = findTool(await mergedTools(engine, opts.sourceId ?? null), callName);
   if (!ct) throw new EngineActionError(`tool not found: ${callName}`);
   if (!toolVisible(ct, opts.principals ?? null)) {
@@ -2371,22 +3007,32 @@ async function executeTool(engine, callName, args, opts = {}) {
   const publicArgs = stripUnderscoreArgs(runtimeArgs);
   let approvalId = null;
   if (shouldRequireApproval(ct, publicArgs)) {
-    approvalId = await findAndClaimApproved(engine, ct.callName, publicArgs, opts.sourceId ?? null);
+    if (approvalScope === null) warnUnscopedApproval(callName);
+    approvalId = await findAndClaimApproved(
+      engine,
+      ct.callName,
+      publicArgs,
+      opts.sourceId ?? null,
+      opts.principals ?? null,
+      approvalScope
+    );
     if (approvalId == null) {
-      const record = await createPending(engine, {
+      const pendingOpts = {
         toolName: ct.callName,
         args: publicArgs,
         sourceId: opts.sourceId ?? null,
         principals: opts.principals ?? null,
         policy: ct.approvalPolicy ?? {}
-      });
+      };
+      const record = approvalScope === null ? await createPending(engine, pendingOpts) : await findOrCreatePending(engine, { ...pendingOpts, approvalScope });
       const reason = ct.requiresApproval ? "tool requires approval" : `approval policy condition met: ${ct.approvalPolicy?.condition}`;
       return {
         approval_required: {
           approval_id: String(record.id),
           tool_name: ct.callName,
           args: publicArgs,
-          reason
+          reason,
+          expires_at: record.expiresAt ? record.expiresAt.toISOString() : null
         }
       };
     }
@@ -2411,8 +3057,9 @@ async function executeTool(engine, callName, args, opts = {}) {
   let truncated = false;
   if (success) {
     try {
+      const redactPrincipals = opts.principals === TRUSTED ? null : opts.principals ?? null;
       const [redacted] = redactToolResult(rawResult, engine.config.redaction, {
-        principals: opts.principals ?? null,
+        principals: redactPrincipals,
         secretKey: engine.config.secretKey,
         hooks: engine.hooks
       });
@@ -2457,6 +3104,9 @@ var DISCOVERY_TIMEOUT_MS = 1e4;
 var TOKEN_TIMEOUT_MS = 15e3;
 var PROBE_TIMEOUT_MS = 5e3;
 var REGISTER_TIMEOUT_MS = 1e4;
+async function checkEgress2(url, allowPrivate) {
+  await assertEgressAllowed(url, { allowPrivate });
+}
 function report(hooks, exc, ctx) {
   if (hooks) emitError(hooks, exc, ctx);
   else console.error("[context-engine] mcp_oauth error:", exc, "| ctx=", ctx);
@@ -2487,11 +3137,16 @@ async function fetchJson(url, opts = {}) {
     method: opts.method ?? "GET",
     headers: opts.headers,
     body: opts.body,
-    redirect: opts.redirect ?? "follow",
+    // Never followed: a redirect reaches a destination no egress check saw,
+    // and on the token endpoint it would forward the client secret with it.
+    redirect: opts.redirect ?? "manual",
     signal: AbortSignal.timeout(opts.timeout ?? DISCOVERY_TIMEOUT_MS)
   });
   return {
+    // `type` rides along so callers can tell an opaque redirect (status 0)
+    // from a request that simply failed — see `isRedirect`.
     status: resp.status,
+    type: resp.type,
     json: () => resp.json(),
     text: () => resp.text()
   };
@@ -2499,6 +3154,7 @@ async function fetchJson(url, opts = {}) {
 async function discoverOauthMetadata(serverUrl, opts = {}) {
   const parsed = new URL(serverUrl);
   const base = `${parsed.protocol}//${parsed.host}`;
+  await checkEgress2(base, opts.allowPrivate ?? false);
   const wellKnownUrl = `${base}/.well-known/oauth-authorization-server`;
   try {
     const resp = await fetchJson(wellKnownUrl, { timeout: DISCOVERY_TIMEOUT_MS });
@@ -2549,7 +3205,7 @@ async function discoverOauthMetadata(serverUrl, opts = {}) {
         timeout: PROBE_TIMEOUT_MS,
         redirect: "manual"
       });
-      if ([200, 302, 303, 400].includes(resp.status)) {
+      if (resp.status === 200 || resp.status === 400 || resp.status === 302 || resp.status === 303 || resp.type === "opaqueredirect") {
         return {
           authorization_endpoint: `${base}${authPath}`,
           token_endpoint: `${base}${tokenPath}`,
@@ -2564,6 +3220,7 @@ async function discoverOauthMetadata(serverUrl, opts = {}) {
   return null;
 }
 async function registerOauthClient(registrationEndpoint, redirectUri, clientName = "Promptev Context Engine", opts = {}) {
+  await checkEgress2(registrationEndpoint, opts.allowPrivate ?? false);
   const payload = {
     client_name: clientName,
     redirect_uris: [redirectUri],
@@ -2634,6 +3291,7 @@ async function exchangeCodeForToken(state, code, store, opts = {}) {
   if (!pending) throw new Error("Invalid or expired OAuth state \u2014 please try connecting again");
   const tokenEndpoint = pending.token_endpoint;
   if (!tokenEndpoint) throw new Error("No token_endpoint in stored OAuth state");
+  await checkEgress2(tokenEndpoint, opts.allowPrivate ?? false);
   const body = new URLSearchParams({
     grant_type: "authorization_code",
     code,
@@ -2697,8 +3355,8 @@ function coerceUuid(value) {
   }
   return value;
 }
-function toolRowPublic(row) {
-  return {
+function toolRowPublic(row, opts = {}) {
+  const out = {
     id: String(row.id),
     name: row.name,
     kind: row.kind,
@@ -2707,8 +3365,36 @@ function toolRowPublic(row) {
     acl: row.acl != null ? [...row.acl] : null,
     requires_approval: row.requires_approval,
     approval_policy: row.approval_policy ?? {},
-    enabled: row.enabled
+    enabled: row.enabled,
+    // Engine-opaque user metadata — admin surface only (the agent-facing
+    // listTools/searchTools views never carry it), returned in clear:
+    // secrets belong in `config`.
+    meta_data: row.meta_data ?? {}
   };
+  if (opts.template && row.config_encrypted) {
+    try {
+      if (!opts.templateKey) throw new Error("no secret key configured");
+      out.config_redacted = redactConfig(
+        String(row.kind),
+        decryptDict(String(row.config_encrypted), opts.templateKey)
+      );
+    } catch {
+      out.config_error = "undecryptable";
+    }
+  }
+  return out;
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;");
+}
+function authorizeToolAcl(requested, principals) {
+  if (requested == null && principals !== TRUSTED) {
+    throw new HandlerError(
+      403,
+      "a tool without an acl is visible to every principal; only a trusted mount may register one \u2014 pass acl with principals you hold"
+    );
+  }
+  authorizeAcl(requested, principals);
 }
 function resolveCaller(value, surface) {
   return resolveRequestPrincipals(value, { surface });
@@ -2734,10 +3420,27 @@ function popupCloseHtml(success, message, targetOrigin, tokenData = null) {
   if (tokenData && success) payload.token = tokenData;
   const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
   const title = success ? "Connected" : "Failed";
-  return `<!DOCTYPE html><html><head><title>Context Engine MCP OAuth</title></head><body style="font-family:system-ui;text-align:center;padding:40px;"><h2>${title}</h2><p>${message}</p><p style="font-size:12px;">This window will close automatically&hellip;</p><script>try {  var d = JSON.parse(atob("${encoded}"));  if (window.opener) window.opener.postMessage(d, "${targetOrigin}");} catch (e) { console.error('postMessage error', e); }setTimeout(function () { window.close(); }, 1500);</script></body></html>`;
+  return `<!DOCTYPE html><html><head><title>Context Engine MCP OAuth</title></head><body style="font-family:system-ui;text-align:center;padding:40px;"><h2>${title}</h2><p>${escapeHtml(message)}</p><p style="font-size:12px;">This window will close automatically&hellip;</p><script>try {  var d = JSON.parse(atob("${encoded}"));  if (window.opener) window.opener.postMessage(d, "${targetOrigin}");} catch (e) { console.error('postMessage error', e); }setTimeout(function () { window.close(); }, 1500);</script></body></html>`;
 }
 function createToolsHandlers(engine, opts = {}) {
   const store = opts.pendingStore ?? new InMemoryPendingStore();
+  const configTemplate = opts.configTemplate ?? false;
+  const templateKey = () => {
+    if (!configTemplate) return null;
+    let key;
+    try {
+      key = getSecretKey(engine.config);
+    } catch {
+      return null;
+    }
+    if (key.length !== 32) {
+      console.warn(
+        `CE_SECRET_KEY is malformed: decoded to ${key.length} bytes, need 32; tool config templates will degrade to config_error`
+      );
+      return null;
+    }
+    return key;
+  };
   const redirectBaseUrl = (opts.redirectBaseUrl ?? "").replace(/\/$/, "");
   let targetOrigin = "";
   try {
@@ -2750,11 +3453,12 @@ function createToolsHandlers(engine, opts = {}) {
     async createTool(body, principals) {
       const caller = resolveCaller(principals, "POST /tools");
       const tc = ToolConfig.fromUnknown(body);
-      authorizeAcl(tc.acl, caller);
+      authorizeToolAcl(tc.acl, caller);
       try {
         const toolId = engine.registerTool ? await engine.registerTool(tc) : await registerTool(engine, tc);
         return { id: toolId };
       } catch (exc) {
+        if (exc instanceof ConfigTemplateError) throw new HandlerError(400, exc.message);
         if (exc instanceof Error && /canonicalFromConfig|kind=/.test(exc.message)) {
           throw new HandlerError(400, String(exc));
         }
@@ -2770,7 +3474,8 @@ function createToolsHandlers(engine, opts = {}) {
         sql += ` WHERE source_id = $1`;
       }
       const result = await engine.pool.query(sql, params);
-      const tools = result.rows.filter((row) => aclVisible(row.acl != null ? [...row.acl] : null, caller)).map(toolRowPublic);
+      const key = templateKey();
+      const tools = result.rows.filter((row) => aclVisible(row.acl != null ? [...row.acl] : null, caller)).map((row) => toolRowPublic(row, { template: configTemplate, templateKey: key }));
       return { tools };
     },
     async getTool(toolId, principals) {
@@ -2781,7 +3486,7 @@ function createToolsHandlers(engine, opts = {}) {
       if (!row || !aclVisible(row.acl != null ? [...row.acl] : null, caller)) {
         throw new HandlerError(404, `tool not found: ${toolId}`);
       }
-      return toolRowPublic(row);
+      return toolRowPublic(row, { template: configTemplate, templateKey: templateKey() });
     },
     async updateToolRoute(toolId, body, principals) {
       const caller = resolveCaller(principals, "PATCH /tools/{tool_id}");
@@ -2796,12 +3501,31 @@ function createToolsHandlers(engine, opts = {}) {
         acl: "acl",
         requires_approval: "requiresApproval",
         approval_policy: "approvalPolicy",
-        enabled: "enabled"
+        enabled: "enabled",
+        meta_data: "metaData"
       };
       for (const [k, dest] of Object.entries(map)) {
         if (Object.hasOwn(body, k)) fields[dest] = body[k];
       }
-      if ("acl" in fields) authorizeAcl(fields.acl, caller);
+      const wireName = {
+        requiresApproval: "requires_approval",
+        approvalPolicy: "approval_policy",
+        metaData: "meta_data"
+      };
+      for (const field of [
+        "name",
+        "kind",
+        "description",
+        "requiresApproval",
+        "approvalPolicy",
+        "enabled",
+        "metaData"
+      ]) {
+        if (field in fields && fields[field] == null) {
+          throw new HandlerError(400, `${wireName[field] ?? field} cannot be null`);
+        }
+      }
+      if ("acl" in fields) authorizeToolAcl(fields.acl, caller);
       try {
         const updated = engine.updateTool ? await engine.updateTool(toolId, { principals: caller, ...fields }) : await updateTool(engine, toolId, { principals: caller, ...fields });
         return {
@@ -2813,9 +3537,11 @@ function createToolsHandlers(engine, opts = {}) {
           acl: updated.acl,
           requires_approval: updated.requiresApproval,
           approval_policy: updated.approvalPolicy,
-          enabled: updated.enabled
+          enabled: updated.enabled,
+          meta_data: updated.metaData
         };
       } catch (exc) {
+        if (exc instanceof ConfigTemplateError) throw new HandlerError(400, exc.message);
         if (exc instanceof EngineActionError) throw new HandlerError(404, String(exc.message));
         throw exc;
       }
@@ -2834,7 +3560,12 @@ function createToolsHandlers(engine, opts = {}) {
     },
     async testToolRoute(body) {
       const tc = ToolConfig.fromUnknown(body);
-      return engine.testTool ? engine.testTool(tc) : testTool(engine, tc);
+      try {
+        return await (engine.testTool ? engine.testTool(tc) : testTool(engine, tc));
+      } catch (exc) {
+        if (exc instanceof ConfigTemplateError) throw new HandlerError(400, exc.message);
+        throw exc;
+      }
     },
     toolSchemaRoute(kind) {
       try {
@@ -2843,14 +3574,30 @@ function createToolsHandlers(engine, opts = {}) {
         throw new HandlerError(404, `unknown tool kind: ${JSON.stringify(kind)}`);
       }
     },
-    async executeToolRoute(body, principals) {
+    /**
+     * `approvalScope` is resolved by the adapter's `approvalScope` option —
+     * SERVER-SIDE, never from the body. A body key of the same name is
+     * ignored exactly like a body `principals`: a client that could name
+     * its own scope could claim another scope's approvals. Absent, the
+     * execution runs unscoped (the deprecated legacy path). A malformed
+     * scope is the host's wiring bug, so it surfaces as a 500, never a 4xx
+     * the client might "fix" by changing its body.
+     */
+    async executeToolRoute(body, principals, approvalScope = null) {
       const caller = resolveCaller(principals, "POST /tools/execute");
       if (!body.call_name) throw new HandlerError(422, "call_name is required");
+      let scope;
+      try {
+        scope = validateApprovalScope(approvalScope);
+      } catch (exc) {
+        throw new HandlerError(500, `approvalScope resolver: ${exc.message}`);
+      }
       try {
         const exec = engine.executeTool ?? ((n, a, o) => executeTool(engine, n, a, o));
         return await exec(body.call_name, body.args ?? null, {
           sourceId: body.source_id,
-          principals: caller
+          principals: caller,
+          approvalScope: scope
         });
       } catch (exc) {
         if (exc instanceof EngineActionError) throw new HandlerError(404, String(exc.message));
@@ -2858,7 +3605,7 @@ function createToolsHandlers(engine, opts = {}) {
       }
     },
     async mcpConnectAndList(body) {
-      const mcp = new PromptevMCP();
+      const mcp = new PromptevMCP({ allowPrivate: allowPrivateEgress(engine) });
       try {
         await mcp.addServer(body.server_name, body.url, { token: body.token, headers: body.headers });
         const client = mcp.clients.get(body.server_name);
@@ -2873,10 +3620,20 @@ function createToolsHandlers(engine, opts = {}) {
           requires_oauth: false
         };
       } catch (exc) {
+        if (exc instanceof EgressDenied) throw new HandlerError(400, String(exc.message));
         const msg = String(exc);
         const statusMatch = /HTTP (401|403)/.exec(msg);
         if (statusMatch || /401|403/.test(msg)) {
-          const metadata = await discoverOauthMetadata(body.url, { hooks: engine.hooks });
+          let metadata;
+          try {
+            metadata = await discoverOauthMetadata(body.url, {
+              hooks: engine.hooks,
+              allowPrivate: allowPrivateEgress(engine)
+            });
+          } catch (denied) {
+            if (denied instanceof EgressDenied) throw new HandlerError(400, String(denied.message));
+            throw denied;
+          }
           if (metadata) {
             return {
               server: body.server_name,
@@ -2902,7 +3659,16 @@ function createToolsHandlers(engine, opts = {}) {
       if (!redirectUri) {
         throw new HandlerError(500, "redirectBaseUrl is required to start MCP OAuth");
       }
-      const metadata = await discoverOauthMetadata(body.server_url, { hooks: engine.hooks });
+      let metadata;
+      try {
+        metadata = await discoverOauthMetadata(body.server_url, {
+          hooks: engine.hooks,
+          allowPrivate: allowPrivateEgress(engine)
+        });
+      } catch (exc) {
+        if (exc instanceof EgressDenied) throw new HandlerError(400, String(exc.message));
+        throw exc;
+      }
       if (!metadata) {
         throw new HandlerError(502, "MCP server does not support OAuth \u2014 no authorization endpoint found");
       }
@@ -2914,11 +3680,12 @@ function createToolsHandlers(engine, opts = {}) {
             String(metadata.registration_endpoint),
             redirectUri,
             "Promptev Context Engine",
-            { hooks: engine.hooks }
+            { hooks: engine.hooks, allowPrivate: allowPrivateEgress(engine) }
           );
           clientId = reg.client_id ?? null;
           clientSecret = reg.client_secret || clientSecret;
-        } catch {
+        } catch (exc) {
+          if (exc instanceof EgressDenied) throw new HandlerError(400, String(exc.message));
         }
       }
       try {
@@ -2941,7 +3708,8 @@ function createToolsHandlers(engine, opts = {}) {
       }
       try {
         const tokenResult = await exchangeCodeForToken(query.state, query.code, store, {
-          hooks: engine.hooks
+          hooks: engine.hooks,
+          allowPrivate: allowPrivateEgress(engine)
         });
         return {
           html: html(true, "Connected successfully", {
@@ -3119,7 +3887,13 @@ function createExpressRouter(engine, opts) {
   );
   router.post(
     "/tools/execute",
-    wrap(async (req) => tools.executeToolRoute(req.body, await opts.principals(req)))
+    wrap(
+      async (req) => tools.executeToolRoute(
+        req.body,
+        await opts.principals(req),
+        opts.approvalScope ? await opts.approvalScope(req) : null
+      )
+    )
   );
   router.get(
     "/tools/:tool_id",