sentinelayer-cli 0.44.0 → 0.45.0

package/src/mcp/cli-command-tools.js

@@ -1,8 +1,10 @@
 import { spawn } from "node:child_process";
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import process from "node:process";
 
+import { bridgeAllowedInputs } from "./bridge-inputs.js";
 import { buildSentinelayerCliRegistryTemplate } from "./cli-registry.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -54,6 +56,11 @@ const SENSITIVE_COMMAND_PATHS = new Set([
   "ai.identity.events",
   "ai.identity.latest",
   "ai.identity.wait-for-otp",
+  // Resumes a local Codex session: --message-file and --cwd name files it reads (a dry run returns
+  // the message), and --model and --last choose what runs. Blocked outright, not only behind the
+  // approval gate; unblocking it needs an argument-bound approval, workspace-scoped paths, and a
+  // model and session that the caller cannot choose freely.
+  "session.wake.codex",
 ]);
 
 // Whole governance sub-trees under ai.identity (domain/target/site/legal-hold) are live
@@ -70,6 +77,10 @@ const SENSITIVE_COMMAND_PREFIXES = [
 ];
 const REDACTION_MARKER = "[REDACTED]";
 
+// Which inputs each command exposes is an explicit, default-deny list: src/mcp/bridge-inputs.js.
+// Nothing there names where a request goes, so a tool caller never chooses a destination for this
+// machine's credentials.
+
 function normalizeString(value) {
   return String(value == null ? "" : value).trim();
 }
@@ -117,11 +128,21 @@ function optionFlagFromFlags(flags) {
   return short ? short[0] : "";
 }
 
+// An input that names a file or directory: by its placeholder (<path>, <file>, <dir>) or its name.
+const PATH_PLACEHOLDER_RE = /<(?:[a-z-]*-)?(?:path|file|dir|directory|folder)s?(?:\.\.\.)?>/i;
+const PATH_NAME_RE = /^(?:cwd|path|paths|file|files|dir|out|output|plan|spec)$|^(?!(?:max|min|num)[A-Z]).*(?:Path|File|Dir|Directory|Folder)s?$/;
+
+function isPathLikeInput(name, flags = "") {
+  return PATH_NAME_RE.test(String(name || "")) || PATH_PLACEHOLDER_RE.test(String(flags || ""));
+}
+
 function normalizePositionalSpec(argument = {}, index = 0) {
+  const name = normalizePropertyName(argument.name, `arg${index + 1}`);
   return {
-    name: normalizePropertyName(argument.name, `arg${index + 1}`),
+    name,
     required: Boolean(argument.required),
     variadic: Boolean(argument.variadic),
+    pathLike: Boolean(argument.pathLike) || isPathLikeInput(name),
   };
 }
 
@@ -136,6 +157,7 @@ function normalizeOptionSpec(option = {}, index = 0) {
     expectsValue,
     variadic: Boolean(option.variadic),
     json: name === "json" || flag === "--json",
+    pathLike: Boolean(option.pathLike) || (expectsValue && isPathLikeInput(name, option.flags)),
   };
 }
 
@@ -227,6 +249,52 @@ function isAllowedInputValue(value) {
   return false;
 }
 
+function realpathOfNearestExisting(target) {
+  let current = target;
+  for (;;) {
+    try {
+      return fs.realpathSync.native(current);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return current;
+      current = parent;
+    }
+  }
+}
+
+function isInsideRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+// An input that names a file or directory stays inside the workspace: it is relative, does not
+// leave the workspace with "..", and does not leave it through a symlink (the nearest existing
+// ancestor's real path is checked). Returns the offending input's name, or "".
+function workspacePathInputError(tool = {}, input = {}, targetPath = process.cwd()) {
+  const metadata = tool.metadata || {};
+  const specs = [
+    ...(Array.isArray(metadata.positional) ? metadata.positional : []),
+    ...(Array.isArray(metadata.options) ? metadata.options : []),
+  ].filter((spec) => spec.pathLike);
+  if (specs.length === 0) return "";
+  const root = realpathOfNearestExisting(path.resolve(String(targetPath || ".")));
+  for (const spec of specs) {
+    const value = input[spec.name];
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (typeof item !== "string" || !item.trim()) continue;
+      const raw = item.trim();
+      if (path.isAbsolute(raw) || path.win32.isAbsolute(raw) || /^[A-Za-z]:/.test(raw) || raw.startsWith("~")) {
+        return spec.name;
+      }
+      const resolved = path.resolve(root, raw);
+      if (!isInsideRoot(root, resolved) || !isInsideRoot(root, realpathOfNearestExisting(resolved))) {
+        return spec.name;
+      }
+    }
+  }
+  return "";
+}
+
 function validateBridgeToolInput(tool = {}, input = {}) {
   if (!isPlainObject(input)) {
     return "input_must_be_object";
@@ -241,9 +309,59 @@ function validateBridgeToolInput(tool = {}, input = {}) {
       return `unsupported_input_type:${key}`;
     }
   }
+  const dashKey = dashLeadingValueKey(tool, input);
+  if (dashKey) {
+    return `unsupported_input_value:${dashKey}`;
+  }
+  return "";
+}
+
+// Positional and option values are copied into argv verbatim, and a value that starts with
+// "-" would be parsed as command-line syntax rather than as a value. The bridge does not
+// accept such values; the direct CLI remains available for them.
+function dashLeadingValueKey(tool = {}, input = {}) {
+  const metadata = tool.metadata || {};
+  const names = [
+    ...(Array.isArray(metadata.positional) ? metadata.positional : []).map((spec) => spec.name),
+    ...(Array.isArray(metadata.options) ? metadata.options : [])
+      .filter((spec) => spec.expectsValue && !spec.json)
+      .map((spec) => spec.name),
+  ];
+  for (const name of names) {
+    const value = input[name];
+    const items = Array.isArray(value) ? value : [value];
+    if (items.some((item) => typeof item === "string" && item.trimStart().startsWith("-"))) return name;
+    if (items.some((item) => typeof item === "number" && item < 0)) return name;
+  }
   return "";
 }
 
+// The inputs a command does not expose, and whether that leaves it unusable through the bridge:
+// it has no entry, or an argument or a required option is not listed.
+function unlistedInputs(commandPathKey, schema = {}, positionalSource = [], optionSource = []) {
+  const allowed = bridgeAllowedInputs(commandPathKey);
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const withheld = new Set();
+  let unusable = !allowed;
+  for (const argument of positionalSource) {
+    if (!allowed?.has(argument.name)) unusable = true;
+  }
+  for (const option of optionSource) {
+    const { name } = normalizeOptionSpec(option);
+    if (allowed?.has(name)) continue;
+    withheld.add(name);
+    if (required.has(name)) unusable = true;
+  }
+  return { withheld, unusable };
+}
+
+function withoutInputs(schema = {}, names = new Set()) {
+  if (names.size === 0) return schema;
+  const properties = Object.fromEntries(Object.entries(schema.properties || {}).filter(([key]) => !names.has(key)));
+  const required = (Array.isArray(schema.required) ? schema.required : []).filter((key) => !names.has(key));
+  return { ...schema, properties, ...(Array.isArray(schema.required) ? { required } : {}) };
+}
+
 function normalizeRegistryTool(tool = {}) {
   const metadata = tool.metadata || {};
   const cliPath = Array.isArray(metadata.cliPath)
@@ -258,19 +376,28 @@ function normalizeRegistryTool(tool = {}) {
       ? metadata.arguments
       : [];
   const optionSource = Array.isArray(metadata.options) ? metadata.options : [];
-  const options = optionSource.map(normalizeOptionSpec).filter((option) => option.flag);
+  const rawSchema = normalizeInputSchema(tool);
+  const { withheld, unusable } = unlistedInputs(commandPathKey, rawSchema, positionalSource, optionSource);
+  const options = optionSource
+    .map(normalizeOptionSpec)
+    .filter((option) => option.flag && !withheld.has(option.name));
   const name = normalizeToolName(tool.name || commandPathKey);
-  const blockedReason = blockedReasonForCommandPath(commandPathKey);
+  const blockedReason =
+    blockedReasonForCommandPath(commandPathKey) || (unusable ? "blocked_unlisted_input" : "");
+  // The approval flag is enforced, not described: a tool that requires human approval (or whose
+  // flag is missing) is runtime-blocked until a server-validated, argument-bound approval exists.
+  const approvalRequired = tool.security?.requires_human_approval !== false;
+  const runtimeBlockReason = blockedReason || (approvalRequired ? "approval_required" : "");
   const security = {
     ...(tool.security || {}),
-    ...(blockedReason ? { runtime_blocked: true, runtime_block_reason: blockedReason } : {}),
+    ...(runtimeBlockReason ? { runtime_blocked: true, runtime_block_reason: runtimeBlockReason } : {}),
   };
 
   return {
     name,
     title: tool.title || `sl ${cliPath.join(" ")}`.trim(),
     description: tool.description || `Run SentinelLayer CLI command sl ${cliPath.join(" ")}.`,
-    inputSchema: normalizeInputSchema(tool),
+    inputSchema: withoutInputs(rawSchema, withheld),
     security,
     annotations: {
       ...(tool.annotations || {}),
@@ -283,9 +410,11 @@ function normalizeRegistryTool(tool = {}) {
       cliPath,
       positional: positionalSource.map(normalizePositionalSpec),
       options,
+      withheldOptions: [...withheld].sort(),
       supportsJson: options.some((option) => option.json),
       blocked: Boolean(metadata.blocked) || Boolean(blockedReason),
       blockedReason: metadata.blockedReason || blockedReason,
+      approvalRequired,
     },
   };
 }
@@ -488,6 +617,10 @@ export function createCliCommandMcpToolHandlers(
     targetPath = process.cwd(),
     executeCliCommandFn = executeCliCommand,
     env = process.env,
+    // Every CLI tool requires human approval, and no server-validated, argument-bound approval
+    // exists yet, so none is approved. Tests pass a validator to exercise the bridge itself; the
+    // MCP server passes none, and its dispatcher refuses these tools before any handler runs.
+    approve = () => false,
   } = {},
 ) {
   const handlers = {};
@@ -510,6 +643,21 @@ export function createCliCommandMcpToolHandlers(
           tool: tool.name,
         };
       }
+      // a blocked tool, or one without approval, is refused before its inputs are looked at
+      if (tool.metadata.blocked) {
+        return {
+          ok: false,
+          reason: tool.metadata.blockedReason || "blocked_cli_command",
+          tool: tool.name,
+        };
+      }
+      if (tool.metadata.approvalRequired !== false && !approve(tool, input)) {
+        return {
+          ok: false,
+          reason: "approval_required",
+          tool: tool.name,
+        };
+      }
       const inputError = validateBridgeToolInput(tool, input);
       if (inputError) {
         return {
@@ -519,10 +667,12 @@ export function createCliCommandMcpToolHandlers(
           tool: tool.name,
         };
       }
-      if (tool.metadata.blocked) {
+      const pathInput = workspacePathInputError(tool, input, targetPath);
+      if (pathInput) {
         return {
           ok: false,
-          reason: tool.metadata.blockedReason || "blocked_cli_command",
+          reason: "path_outside_workspace",
+          detail: pathInput,
           tool: tool.name,
         };
       }

package/src/mcp/registry.js

@@ -896,13 +896,14 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "session_locks",
         title: "List Senti File Locks",
         description:
-          "List active authoritative file leases for a session.",
+          "List active authoritative file leases for a session. In an agent context it runs on the agent's admission (agentId, else SENTINELAYER_AGENT_ID).",
         input_schema: {
           type: "object",
           additionalProperties: false,
           required: ["sessionId"],
           properties: {
             sessionId: { type: "string" },
+            agentId: { type: "string" },
           },
         },
         transport: {

package/src/mcp/session-stdio-server.js

@@ -13,7 +13,14 @@ import { eventMatchesAgent } from "../session/listener.js";
 import { isSessionControlEvent } from "../session/control-events.js";
 import { buildObservations } from "../session/recall/observations.js";
 import { createMemoryService } from "../engram/index.js";
-import { assertCanonicalAgentId, canonicalAgentId, withAgentAdmission } from "../session/admission-auth.js";
+import {
+  AdmissionCredentialRefused,
+  assertCanonicalAgentId,
+  canonicalAgentId,
+  withAgentAdmission,
+} from "../session/admission-auth.js";
+import { hasStoredAdmissionCredentials, storedAdmissionAgentsForSession } from "../session/admission.js";
+import { sessionRouteClass } from "../session/route-classes.js";
 import {
   SESSION_REACTION_TYPES,
   isSessionReactionType,
@@ -886,43 +893,63 @@ async function persistSessionEvent({
   };
 }
 
-// Local MCP tools that act AS an agent: post, raise attention, react, reply, act on a
-// message, lease files, or advance that agent's read cursor. Each runs inside the
-// agent's admission scope, the same canonical path native `sl session` actor commands
-// use. A live stored admission is the only credential its requests carry; an expired,
-// malformed or mis-bound one is refused before any request; a credential the API
-// refuses (401/403) is final. With no stored admission a tool behaves as before.
-export const SESSION_MCP_ACTOR_TOOLS = Object.freeze([
-  "poll_inbox",
-  "read_history",
-  "send_message",
-  "attention_request",
-  "session_action",
-  "session_react",
-  "session_reply",
-  "session_lock",
-  "session_unlock",
-]);
+function refuseOutsideAdmission(reason) {
+  throw new AdmissionCredentialRefused(
+    `This tool runs for an agent on this machine and needs an admission it can bind to: ${reason}. ` +
+      `It will not fall back to other credentials.`,
+    { reason: "session_admission_not_bound" },
+  );
+}
 
-function actorAgentId(toolName, input = {}) {
-  const raw =
-    normalizeString(input.agentId || input.agent_id || input.agent) ||
-    (toolName === "read_history" ? normalizeString(process.env.SENTINELAYER_AGENT_ID) : "");
-  if (!raw) return "";
+/**
+ * An agent context is a process that acts for an agent: SENTINELAYER_AGENT_ID is set, or
+ * this machine stores any agent admission credential (usable or not).
+ */
+export async function isAgentContext({ env = process.env } = {}) {
+  return Boolean(normalizeString(env.SENTINELAYER_AGENT_ID)) || (await hasStoredAdmissionCredentials());
+}
+
+/**
+ * The one credential policy for local MCP session tools, by the tool's class in
+ * SESSION_ROUTE_CLASSES (src/session/route-classes.js):
+ *   - exempt-local tools, and every tool outside an agent context: run as before
+ *   - owner tools: refused in an agent context
+ *   - the session stores an admission on this machine (in any state): the tool binds to the
+ *     admission of the agent it names (input agentId, else SENTINELAYER_AGENT_ID) and runs
+ *     inside its scope; naming no agent, an agent holding none of the session's admissions,
+ *     or an expired, malformed or mis-bound admission is refused before any request
+ *   - the session stores none: legacy-data-plane tools run as before; control, owner and
+ *     unclassified (including newly added) tools are refused before any request
+ */
+export async function runInSessionToolContext(name, input = {}, run, { env = process.env } = {}) {
+  const routeClass = sessionRouteClass(`mcp:${name}`);
+  if (routeClass === "exempt-local") return run(input);
+  if (!(await isAgentContext({ env }))) return run(input);
+  if (routeClass === "owner") refuseOutsideAdmission("owner actions are not available to agents");
+  const sessionId = normalizeString(input.sessionId || input.session_id || input.session);
+  if (!sessionId) refuseOutsideAdmission("no session id was given");
+  const stored = await storedAdmissionAgentsForSession(sessionId);
+  if (stored.length === 0) {
+    if (routeClass === "legacy-data-plane") return run(input);
+    refuseOutsideAdmission(`session ${sessionId} stores no admission on this machine and "${name}" needs one`);
+  }
+  const raw = normalizeString(input.agentId || input.agent_id || input.agent) || normalizeString(env.SENTINELAYER_AGENT_ID);
+  if (!raw) refuseOutsideAdmission("no agent id was given");
   // One canonical identity for authorisation and execution (see admission-auth.js).
   assertCanonicalAgentId(raw, "agentId");
-  return canonicalAgentId(raw);
+  const agentId = canonicalAgentId(raw);
+  if (!stored.includes(agentId)) {
+    refuseOutsideAdmission(`agent "${agentId}" holds none of the admissions stored for session ${sessionId}`);
+  }
+  // live: runs inside the admission scope; an expired, malformed or mis-bound one is refused there.
+  // The file was seen above, so one removed since then refuses too: never a fallback.
+  return withAgentAdmission(sessionId, agentId, () => run(input), { requireStored: true });
 }
 
-function routeActorToolsThroughAdmission(handlers) {
-  for (const name of SESSION_MCP_ACTOR_TOOLS) {
+export function routeAgentToolsThroughAdmission(handlers, { env = process.env } = {}) {
+  for (const name of Object.keys(handlers)) {
     const run = handlers[name];
-    handlers[name] = async (input = {}) => {
-      const agentId = actorAgentId(name, input);
-      // No agent named: the tool's own validation reports it (read_history reads as the user).
-      if (!agentId) return run(input);
-      return withAgentAdmission(requireSessionId(input), agentId, () => run(input));
-    };
+    handlers[name] = (input = {}) => runInSessionToolContext(name, input, run, { env });
   }
   return handlers;
 }
@@ -1336,7 +1363,7 @@ export function createSessionMcpToolHandlers({
       });
     },
   };
-  return routeActorToolsThroughAdmission(handlers);
+  return routeAgentToolsThroughAdmission(handlers);
 }
 
 export const SESSION_MCP_TOOLS = Object.freeze([
@@ -1625,13 +1652,14 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_locks",
     title: "List Senti File Locks",
     description:
-      "List active authoritative file leases for a session.",
+      "List active authoritative file leases for a session. In an agent context it runs on the agent's admission (agentId, else SENTINELAYER_AGENT_ID).",
     inputSchema: {
       type: "object",
       additionalProperties: false,
       required: ["sessionId"],
       properties: {
         sessionId: { type: "string", minLength: 1 },
+        agentId: { type: "string", minLength: 1 },
       },
     },
   },
@@ -1712,6 +1740,45 @@ function jsonRpcError(id, code, message, data = undefined) {
   });
 }
 
+// The dispatcher enforces each tool's published policy before its handler runs. A tool that
+// requires human approval is refused: approval would have to be server-validated and bound to the
+// call's arguments, and no such approval exists yet. A runtime-blocked tool is refused too. Refused
+// tools are not advertised by tools/list, and a call to one gets a specific JSON-RPC error.
+export const MCP_HUMAN_APPROVAL_REQUIRED = Object.freeze({ code: -32001, reason: "human_approval_required" });
+export const MCP_TOOL_BLOCKED = Object.freeze({ code: -32002, reason: "tool_blocked" });
+
+function toolRefusal(tool) {
+  const security = isPlainObject(tool?.security) ? tool.security : {};
+  if (security.requires_human_approval === true) return MCP_HUMAN_APPROVAL_REQUIRED.reason;
+  if (tool?.metadata?.bridge === "cli-command" && security.requires_human_approval !== false) {
+    return MCP_HUMAN_APPROVAL_REQUIRED.reason;
+  }
+  if (security.runtime_blocked === true || tool?.metadata?.blocked === true) return MCP_TOOL_BLOCKED.reason;
+  return "";
+}
+
+function terminalCommandFor(tool, toolName) {
+  const cliPath = Array.isArray(tool?.metadata?.cliPath) ? tool.metadata.cliPath : toolName.replace(/^sl\./, "").split(".");
+  return `sl ${cliPath.join(" ")}`;
+}
+
+function refusalError(id, toolName, tool, reason) {
+  if (reason === MCP_HUMAN_APPROVAL_REQUIRED.reason) {
+    return jsonRpcError(
+      id,
+      MCP_HUMAN_APPROVAL_REQUIRED.code,
+      `Human approval is required for ${toolName}. It is not available over the MCP bridge in this version; run \`${terminalCommandFor(tool, toolName)}\` in a terminal instead.`,
+      { reason, tool: toolName },
+    );
+  }
+  return jsonRpcError(
+    id,
+    MCP_TOOL_BLOCKED.code,
+    `${toolName} is not available over the MCP bridge; run \`${terminalCommandFor(tool, toolName)}\` in a terminal instead.`,
+    { reason, tool: toolName },
+  );
+}
+
 export async function handleMcpJsonRpcMessage(
   message,
   {
@@ -1761,7 +1828,7 @@ export async function handleMcpJsonRpcMessage(
   if (method === "tools/list") {
     if (isNotification) return null;
     return jsonRpcSuccess(id, {
-      tools: tools.map((tool) => toMcpTool(tool)),
+      tools: tools.filter((tool) => !toolRefusal(tool)).map((tool) => toMcpTool(tool)),
     });
   }
 
@@ -1770,6 +1837,18 @@ export async function handleMcpJsonRpcMessage(
     const toolName = normalizeString(message.params?.name);
     const args = isPlainObject(message.params?.arguments) ? message.params.arguments : {};
     const handler = handlers[toolName];
+    const tool = (Array.isArray(tools) ? tools : []).find((candidate) => normalizeString(candidate?.name) === toolName);
+    const refusal = typeof handler === "function" && tool ? toolRefusal(tool) : "";
+    if (refusal) {
+      return refusalError(id, toolName, tool, refusal);
+    }
+    if (typeof handler === "function" && !tool) {
+      // a handler without a published definition has no policy to check: refused
+      return jsonRpcSuccess(
+        id,
+        buildToolResult({ ok: false, reason: "unknown_tool", tool: toolName }, { isError: true }),
+      );
+    }
     if (typeof handler !== "function") {
       return jsonRpcSuccess(
         id,

package/src/mcp/smoke.js

@@ -1,5 +1,11 @@
 import process from "node:process";
 
+import {
+  CredentialDestinationRefused,
+  credentialedRequest,
+  isCredential,
+  userCredential,
+} from "../auth/credential-destinations.js";
 import { DEFAULT_REQUEST_TIMEOUT_MS } from "../auth/http.js";
 import { requestHostedMcpAccessToken } from "./token-service.js";
 
@@ -75,7 +81,7 @@ function summarizeJsonRpcError(error, secrets = []) {
 async function postJsonRpc({
   fetchImpl,
   url,
-  accessToken,
+  credential,
   payload,
   timeoutMs,
   redactionSecrets = [],
@@ -83,15 +89,18 @@ async function postJsonRpc({
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const response = await fetchImpl(url, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "Content-Type": "application/json",
+    // fetchImpl is the transport credentialedRequest calls, after its origin check.
+    const response = await credentialedRequest(
+      credential,
+      url,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
       },
-      body: JSON.stringify(payload),
-      signal: controller.signal,
-    });
+      { fetchImpl },
+    );
     const text = await response.text().catch(() => "");
     let json = null;
     if (text) {
@@ -108,6 +117,7 @@ async function postJsonRpc({
       detail: json ? "" : redactMcpSmokeText(text, redactionSecrets),
     };
   } catch (error) {
+    if (error instanceof CredentialDestinationRefused) throw error;
     const aborted = Boolean(error) && error.name === "AbortError";
     return {
       reached: false,
@@ -172,6 +182,12 @@ export async function runHostedMcpSmoke({
   if (!accessToken) {
     throw new Error("Hosted MCP token mint succeeded but returned no access token.");
   }
+  // The minted bearer as a credential: the mint's own hosted MCP credential, or the bare token bound
+  // to the configured API. Any other credential (an agent's admission, say) is not accepted here.
+  if (minted.credential !== undefined && !(isCredential(minted.credential) && minted.credential.source === "hosted_mcp")) {
+    throw new TypeError("The hosted MCP mint must return a hosted MCP credential.");
+  }
+  const credential = minted.credential || (await userCredential(accessToken, { env, homeDir, source: "hosted_mcp" }));
   const redactionSecrets = [accessToken];
 
   const mcpUrl = joinUrl(minted.apiUrl, "/mcp");
@@ -181,7 +197,7 @@ export async function runHostedMcpSmoke({
   const toolsResponse = await postJsonRpc({
     fetchImpl,
     url: mcpUrl,
-    accessToken,
+    credential,
     timeoutMs: normalizedTimeoutMs,
     redactionSecrets,
     payload: {
@@ -247,7 +263,7 @@ export async function runHostedMcpSmoke({
       const eventsResponse = await postJsonRpc({
         fetchImpl,
         url: mcpUrl,
-        accessToken,
+        credential,
         timeoutMs: normalizedTimeoutMs,
         redactionSecrets,
         payload: {

package/src/mcp/token-service.js

@@ -1,5 +1,6 @@
 import process from "node:process";
 
+import { credentialFor, isAuthenticated, userCredential } from "../auth/credential-destinations.js";
 import { DEFAULT_REQUEST_TIMEOUT_MS, requestJsonMutation } from "../auth/http.js";
 import {
   DEFAULT_API_TOKEN_TTL_DAYS,
@@ -39,12 +40,6 @@ function buildApiPath(apiUrl, pathSuffix) {
   return `${base}/${suffix}`;
 }
 
-function toAuthHeader(token) {
-  return {
-    Authorization: `Bearer ${String(token || "").trim()}`,
-  };
-}
-
 function applyScope(body, { scope = "", scopes } = {}) {
   const normalizedScope = String(scope || "").trim();
   const normalizedScopes = Array.isArray(scopes)
@@ -118,7 +113,7 @@ export async function requestHostedMcpAccessToken({
     tokenTtlDays,
     homeDir,
   });
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
   }
 
@@ -135,17 +130,20 @@ export async function requestHostedMcpAccessToken({
     {
       method: "POST",
       operationName: "mcp-token-mint",
-      headers: toAuthHeader(session.token),
+      credential: await credentialFor(session, { env, homeDir }),
       body,
       timeoutMs: normalizedTimeoutMs,
     }
   );
+  const accessToken = String(response.access_token || "");
 
   return {
     apiUrl: session.apiUrl,
     authSource: session.source,
     rotated: Boolean(session.rotated),
-    accessToken: String(response.access_token || ""),
+    accessToken,
+    // the minted bearer, bound to the configured API like the token that minted it
+    credential: await userCredential(accessToken, { env, homeDir, source: "hosted_mcp" }),
     tokenType: String(response.token_type || "Bearer"),
     expiresIn: Number(response.expires_in || 0),
     expiresAt: String(response.expires_at || ""),

package/src/memory/retrieval.js

@@ -1,6 +1,8 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { credentialedRequest } from "../auth/credential-destinations.js";
+
 function normalizeString(value) {
   return String(value || "").trim();
 }
@@ -506,6 +508,7 @@ export async function queryHybridRetriever({
   provider = "local",
   apiEndpoint = "",
   apiKey = "",
+  credential = null,
   fetchImpl = globalThis.fetch,
 } = {}) {
   const normalizedProvider = normalizeString(provider).toLowerCase() || "local";
@@ -534,12 +537,18 @@ export async function queryHybridRetriever({
   }
 
   try {
-    const response = await fetchImpl(String(apiEndpoint), {
+    // The user's credential goes only to its own origin (credentialedRequest); a dedicated memory
+    // API key is that service's own key, sent to the endpoint configured for it.
+    const send = (init) =>
+      credential
+        ? credentialedRequest(credential, String(apiEndpoint), init, { fetchImpl })
+        : fetchImpl(String(apiEndpoint), {
+            ...init,
+            headers: { ...init.headers, ...(normalizeString(apiKey) ? { authorization: `Bearer ${apiKey}` } : {}) },
+          });
+    const response = await send({
       method: "POST",
-      headers: {
-        "content-type": "application/json",
-        ...(normalizeString(apiKey) ? { authorization: `Bearer ${apiKey}` } : {}),
-      },
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({
         query: normalizeString(query),
         limit: Math.max(1, Math.floor(normalizeNumber(limit, 12))),