@openviking/opencode-plugin 2026.9.10 → 2026.9.21

package/lib/shared/credentials.mjs

@@ -2,11 +2,11 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
 
 const DEFAULT_OVCLI_CONF_PATH = join(homedir(), ".openviking", "ovcli.conf");
 const DEFAULT_OV_CONF_PATH = join(homedir(), ".openviking", "ov.conf");
-const DEFAULT_BASE_URL = "http://127.0.0.1:1933";
+const DEFAULT_TIMEOUT_MS = 15000;
+const MIN_TIMEOUT_MS = 1000;
 
 function str(val, fallback = "") {
   if (typeof val === "string" && val.trim()) return val.trim();
@@ -108,6 +108,88 @@ export function loadCredentialFiles(env = process.env) {
   };
 }
 
+/**
+ * The environment variables that name part of the connection. Any one of them
+ * set is what takes the chain off ovcli.conf in `auto` mode, so a variable
+ * that only tunes how the chain runs must not be on this list: an
+ * `OPENVIKING_AUTH_MODE` exported on its own would otherwise unpin the file.
+ */
+export const CREDENTIAL_ENV_VARS = [
+  "OPENVIKING_URL",
+  "OPENVIKING_BASE_URL",
+  "OPENVIKING_MCP_URL",
+  "OPENVIKING_BEARER_TOKEN",
+  "OPENVIKING_API_KEY",
+  "OPENVIKING_ACCOUNT",
+  "OPENVIKING_USER",
+  "OPENVIKING_PEER_ID",
+];
+
+/** Every environment variable `resolveConnection` reads. */
+export const CONNECTION_ENV_VARS = [
+  ...CREDENTIAL_ENV_VARS,
+  "OPENVIKING_AUTH_MODE",
+  "OPENVIKING_CREDENTIAL_SOURCE",
+  "OPENVIKING_CREDENTIALS_SOURCE",
+  "OPENVIKING_CLI_CONFIG_FILE",
+  "OPENVIKING_CONFIG_FILE",
+];
+
+function isSection(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * ov.conf spells its sections snake_case while a host may call itself
+ * `claude-code` or `trae-cn`, so both spellings land on the same block. The
+ * normalization stays inline rather than importing `config-schema.mjs`, which
+ * the portable agent-plugins bundle would then have to ship as well.
+ */
+function sectionKey(harness) {
+  return String(harness || "").trim().toLowerCase().replace(/-/g, "_");
+}
+
+/** The calling harness's own section of ov.conf. */
+function harnessSection(ovFile, harness) {
+  const section = ovFile[sectionKey(harness)];
+  return isSection(section) ? section : {};
+}
+
+/**
+ * ovcli.conf's `plugin` section as this harness sees it: the shared scalars,
+ * then `plugin.<harness>` over them in both spellings, the hyphenated one last.
+ * `loadPluginSettings` merges the same way for every other knob, and the two
+ * must agree or a key would win in the hooks and lose here.
+ */
+function pluginSection(cliFile, harness) {
+  const plugin = isSection(cliFile.plugin) ? cliFile.plugin : {};
+  const merged = {};
+  for (const [key, value] of Object.entries(plugin)) {
+    if (!isSection(value)) merged[key] = value;
+  }
+  const key = sectionKey(harness);
+  for (const candidate of [key, key.replace(/_/g, "-")]) {
+    if (candidate && isSection(plugin[candidate])) Object.assign(merged, plugin[candidate]);
+  }
+  return merged;
+}
+
+/** A knob-file scalar as the schema coerces a string knob: `12345` is "12345". */
+function scalar(value) {
+  return value === undefined || value === null ? "" : String(value).trim();
+}
+
+const AUTH_MODES = ["trusted", "api_key"];
+
+function normalizeAuthMode(value) {
+  const mode = str(value, "").toLowerCase();
+  return AUTH_MODES.includes(mode) ? mode : "";
+}
+
+function authModeIn(section) {
+  return normalizeAuthMode(section.authMode) || normalizeAuthMode(section.auth_mode);
+}
+
 function sourceMode(env) {
   const raw = str(env.OPENVIKING_CREDENTIAL_SOURCE, str(env.OPENVIKING_CREDENTIALS_SOURCE, "auto"))
     .toLowerCase();
@@ -117,123 +199,177 @@ function sourceMode(env) {
 }
 
 function hasEnvCredentialFields(env) {
-  return Boolean(
-    str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, "")) ||
-    str(env.OPENVIKING_MCP_URL, "") ||
-    str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, "")) ||
-    str(env.OPENVIKING_ACCOUNT, "") ||
-    str(env.OPENVIKING_USER, "") ||
-    str(env.OPENVIKING_PEER_ID, ""),
-  );
+  return CREDENTIAL_ENV_VARS.some((name) => str(env[name], ""));
 }
 
-function deriveBaseUrl({ env, cliFile, ovFile, mode, useCli }) {
-  const envUrl = str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, ""));
-  const cliUrl = str(cliFile.url, "");
-
-  if (mode !== "cli" && envUrl) return envUrl.replace(/\/+$/, "");
-  if (useCli && cliUrl) return cliUrl.replace(/\/+$/, "");
-  if (mode !== "env" && cliUrl) return cliUrl.replace(/\/+$/, "");
-
-  const server = ovFile.server || {};
-  const ovUrl = str(server.url, "");
-  if (ovUrl) return ovUrl.replace(/\/+$/, "");
+function trimSlash(value) {
+  return value.replace(/\/+$/, "");
+}
 
-  const host = str(server.host, "127.0.0.1").replace("0.0.0.0", "127.0.0.1");
-  const port = Number.isFinite(Number(server.port)) ? Math.floor(Number(server.port)) : 1933;
-  return `http://${host}:${port}`;
+/** The first layer that holds a value, with the source label and file it names. */
+function firstLayer(layers) {
+  for (const [value, source, path = ""] of layers) {
+    if (value) return { value, source, path };
+  }
+  return { value: "", source: "none", path: "" };
 }
 
-export function resolveOpenVikingCredentials(env = process.env) {
-  const files = loadCredentialFiles(env);
+/**
+ * The one connection a harness has: which server, which key, whose identity,
+ * and whether that identity goes on the wire. Hooks reach it through
+ * `buildPluginConfig`, every MCP proxy through the same loader or through
+ * `buildProxyConnection`, so the two sides of one harness cannot disagree.
+ *
+ * Only three kinds of input count: what an embedding host named (`hostInput`),
+ * the environment, and the two files under `~/.openviking`. The working
+ * directory never does — an MCP proxy starts wherever its host launches it.
+ *
+ * ovcli.conf pins the chain when it names a url, key, identity or peer and the
+ * environment names none of those; pinned, the environment's credentials no
+ * longer apply. `OPENVIKING_CREDENTIAL_SOURCE` forces either side, and forced
+ * to `env` no file is read at all — which is what lets a parent process hand a
+ * resolved connection, including an empty key, to a child verbatim. Every chain
+ * runs host → env (unpinned) → ovcli.conf → its `plugin.<harness>` and
+ * `plugin` keys → ov.conf's harness section; the key then ends at
+ * `server.root_api_key`, which a pinned chain reaches only with
+ * `rootKeyFallback`, and the identity skips ov.conf's harness section when
+ * pinned. The auth mode reads the environment in either mode, then the
+ * `plugin` keys, the harness section and `server.auth_mode`; failing all of
+ * them, an identity from any layer means the deployment expects one.
+ */
+export function resolveConnection(harness, {
+  env = process.env,
+  files = null,
+  hostInput = {},
+  rootKeyFallback = false,
+} = {}) {
+  const name = str(harness, "");
+  const loaded = files || loadCredentialFiles(env);
+  const { cliFile, ovFile, cliPath, ovPath } = loaded;
+  const host = hostInput || {};
   const mode = sourceMode(env);
   const envHasCredentials = hasEnvCredentialFields(env);
-  const useCli = mode === "cli" ||
-    (mode === "auto" && !envHasCredentials && files.cliPath && hasCredentialFields(files.cliFile));
-  const cx = files.ovFile.codex || {};
-  const server = files.ovFile.server || {};
-
-  const baseUrl = deriveBaseUrl({ env, ...files, mode, useCli });
-
-  const apiKey = useCli
-    ? str(files.cliFile.api_key, "")
-    : (
-        str(env.OPENVIKING_BEARER_TOKEN, "") ||
-        str(env.OPENVIKING_API_KEY, "") ||
-        str(files.cliFile.api_key, "") ||
-        str(cx.apiKey, "") ||
-        str(server.root_api_key, "")
-      );
-
-  const account = useCli
-    ? str(files.cliFile.account, str(files.cliFile.account_id, ""))
-    : (
-        str(env.OPENVIKING_ACCOUNT, "") ||
-        str(files.cliFile.account, str(files.cliFile.account_id, "")) ||
-        str(cx.accountId, "")
-      );
-
-  const user = useCli
-    ? str(files.cliFile.user, str(files.cliFile.user_id, ""))
-    : (
-        str(env.OPENVIKING_USER, "") ||
-        str(files.cliFile.user, str(files.cliFile.user_id, "")) ||
-        str(cx.userId, "")
-      );
-
-  const peerId = useCli
-    ? str(files.cliFile.actor_peer_id, str(files.cliFile.peer_id, ""))
-    : (
-        str(env.OPENVIKING_PEER_ID, "") ||
-        str(files.cliFile.actor_peer_id, str(files.cliFile.peer_id, "")) ||
-        str(cx.peerId, str(cx.peer_id, ""))
-      );
-
-  const explicitMcpUrl = str(env.OPENVIKING_MCP_URL, "");
-  const mcpUrl = (mode !== "cli" && explicitMcpUrl) ? explicitMcpUrl : `${baseUrl.replace(/\/+$/, "")}/mcp`;
-
-  // The file that actually supplied the api_key, following the same chain —
-  // empty when the key came from the environment or was never found.
-  let credentialPath = "";
-  if (apiKey) {
-    if (useCli) credentialPath = files.cliPath;
-    else if (str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, ""))) credentialPath = "";
-    else if (str(files.cliFile.api_key, "")) credentialPath = files.cliPath;
-    else credentialPath = files.ovPath;
-  }
+  const pinned = mode === "cli" ||
+    (mode === "auto" && !envHasCredentials && Boolean(cliPath) && hasCredentialFields(cliFile));
+  const unpinned = (layer) => (pinned ? [] : [layer]);
+  const fromFiles = mode !== "env";
+  const filed = (...layers) => (fromFiles ? layers : []);
+  const plugin = pluginSection(cliFile, name);
+  const section = harnessSection(ovFile, name);
+  const server = isSection(ovFile.server) ? ovFile.server : {};
+
+  const key = firstLayer([
+    [str(host.apiKey, ""), "host"],
+    ...unpinned([str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, "")), "env"]),
+    ...filed(
+      [str(cliFile.api_key, ""), "ovcli", cliPath],
+      [scalar(plugin.apiKey), "ovcli", cliPath],
+      [scalar(section.apiKey), "ov", ovPath],
+    ),
+    ...((pinned && !rootKeyFallback) ? [] : filed([str(server.root_api_key, ""), "ov", ovPath])),
+  ]);
+
+  const identity = (hostValue, envName, cliValue, knob) => firstLayer([
+    [str(hostValue, ""), "host"],
+    ...unpinned([str(env[envName], ""), "env"]),
+    ...filed([cliValue, "ovcli", cliPath], [scalar(plugin[knob]), "ovcli", cliPath]),
+    ...(pinned ? [] : filed([str(section[knob], ""), "ov", ovPath])),
+  ]).value;
+  const account = identity(host.account, "OPENVIKING_ACCOUNT", str(cliFile.account, str(cliFile.account_id, "")), "accountId");
+  const user = identity(host.user, "OPENVIKING_USER", str(cliFile.user, str(cliFile.user_id, "")), "userId");
+
+  const peerId = firstLayer([
+    ...unpinned([str(env.OPENVIKING_PEER_ID, ""), "env"]),
+    ...filed([str(cliFile.actor_peer_id, str(cliFile.peer_id, "")), "ovcli"]),
+    ...(pinned ? [] : filed([str(section.peerId, str(section.peer_id, "")), "ov"])),
+  ]).value;
+
+  const authMode = normalizeAuthMode(host.authMode)
+    || normalizeAuthMode(env.OPENVIKING_AUTH_MODE)
+    || (fromFiles && (authModeIn(plugin) || authModeIn(section) || normalizeAuthMode(server.auth_mode)))
+    || ((account || user) ? "trusted" : "api_key");
+
+  const hostBaseUrl = trimSlash(str(host.baseUrl, ""));
+  const envUrl = pinned ? "" : str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, ""));
+  const fileUrl = fromFiles ? (str(cliFile.url, "") || str(server.url, "")) : "";
+  const baseUrl = hostBaseUrl || trimSlash(envUrl || fileUrl) || serverAddress(fromFiles ? server : {});
+  const envMcpUrl = pinned ? "" : str(env.OPENVIKING_MCP_URL, "");
+  const mcpUrl = (!hostBaseUrl && envMcpUrl) ? envMcpUrl : `${baseUrl}/mcp`;
 
   return {
-    ...files,
-    credentialSource: useCli ? "ovcli" : ((mode === "env" || envHasCredentials) ? "env" : "auto"),
-    credentialPath,
+    ...loaded,
+    harness: name,
+    credentialSource: pinned ? "ovcli" : ((mode === "env" || envHasCredentials) ? "env" : "auto"),
     baseUrl,
     mcpUrl,
-    apiKey,
+    apiKey: key.value,
     account,
     user,
     peerId,
-    hasApiKey: Boolean(apiKey),
+    authMode,
+    sendIdentityHeaders: authMode === "trusted",
+    hasApiKey: Boolean(key.value),
+    // Which layer supplied the key and the file behind it, empty when the key
+    // came from the host or the environment. A doctor and a 401 hint report it;
+    // `credentialSource` is the mode the chain ran in, not a file.
+    apiKeySource: key.source,
+    credentialPath: key.path,
   };
 }
 
-function main() {
-  const cmd = process.argv[2] || "";
-  if (cmd === "mcp-url") {
-    process.stdout.write(resolveOpenVikingCredentials().mcpUrl);
-    return;
-  }
-  if (cmd === "has-api-key") {
-    process.stdout.write(resolveOpenVikingCredentials().hasApiKey ? "1" : "0");
-    return;
-  }
-  if (cmd === "has-peer-id") {
-    process.stdout.write(resolveOpenVikingCredentials().peerId ? "1" : "0");
-    return;
-  }
-  process.stderr.write("usage: ov-credentials.mjs <mcp-url|has-api-key|has-peer-id>\n");
-  process.exitCode = 2;
+function serverAddress(server) {
+  const host = str(server.host, "127.0.0.1").replace("0.0.0.0", "127.0.0.1");
+  const port = Number.isFinite(Number(server.port)) ? Math.floor(Number(server.port)) : 1933;
+  return `http://${host}:${port}`;
+}
+
+function envFlag(env, name) {
+  const raw = str(env[name], "").toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
 }
 
-if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
-  main();
+function clampTimeout(value) {
+  const raw = str(value, "");
+  const parsed = raw ? Number(raw) : NaN;
+  return Math.max(MIN_TIMEOUT_MS, Math.floor(Number.isFinite(parsed) ? parsed : DEFAULT_TIMEOUT_MS));
+}
+
+/**
+ * Everything a stdio MCP proxy needs, for a package that ships no hooks.
+ *
+ * `buildPluginConfig` answers the same question one layer up, but reaching it
+ * means vendoring the knob schema and the workspace layers — a closure the
+ * portable agent-plugins bundle would carry in git to send one HTTP header.
+ * This is the same connection plus what a proxy adds to it: the User-Agent,
+ * the request timeout, and the debug log.
+ *
+ * The api_key ends at `server.root_api_key` even when ovcli.conf pinned the
+ * chain to itself. A portable package has no installer to migrate anyone, so
+ * an install that names only a `url` there keeps the key it has always used.
+ */
+export function buildProxyConnection(harness, { env = process.env, manifestUrl = "", version = "" } = {}) {
+  const name = str(harness);
+  const connection = resolveConnection(name, { env, rootKeyFallback: true });
+  return {
+    harness: name,
+    userAgent: buildUserAgent(name, str(version) || (manifestUrl ? readManifestVersion(manifestUrl) : "")),
+    baseUrl: connection.baseUrl,
+    mcpUrl: connection.mcpUrl,
+    apiKey: connection.apiKey,
+    account: connection.account,
+    user: connection.user,
+    peerId: connection.peerId,
+    authMode: connection.authMode,
+    sendIdentityHeaders: connection.sendIdentityHeaders,
+    credentialSource: connection.credentialSource,
+    apiKeySource: connection.apiKeySource,
+    credentialPath: connection.credentialPath,
+    hasApiKey: connection.hasApiKey,
+    cliPath: connection.cliPath,
+    ovPath: connection.ovPath,
+    timeoutMs: clampTimeout(env.OPENVIKING_TIMEOUT_MS),
+    debug: envFlag(env, "OPENVIKING_DEBUG"),
+    debugLogPath: str(env.OPENVIKING_DEBUG_LOG)
+      || join(homedir(), ".openviking", "logs", `${name}.log`),
+  };
 }

package/lib/shared/mcp-proxy-config.mjs

@@ -12,9 +12,56 @@
 import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
 
+import { CONNECTION_ENV_VARS, CREDENTIAL_ENV_VARS } from "./credentials.mjs";
+
 export const DEFAULT_PROXY_TIMEOUT_MS = 15000;
 const MIN_PROXY_TIMEOUT_MS = 1000;
 
+/**
+ * Every variable that changes what an MCP proxy sends. Hooks inherit their
+ * host's whole environment; a host that hands its MCP servers an allowlist
+ * instead (Codex's `env_vars`) has to name each of these, or the proxy
+ * resolves a different connection from the hooks beside it.
+ */
+export const MCP_PROXY_ENV_VARS = [
+  ...CONNECTION_ENV_VARS,
+  "OPENVIKING_HOME",
+  "OPENVIKING_STATE_DIR",
+  "OPENVIKING_RECALL_PEER_SCOPE",
+  "OPENVIKING_TIMEOUT_MS",
+  "OPENVIKING_DEBUG",
+  "OPENVIKING_DEBUG_LOG",
+  "OPENVIKING_EXTRA_HEADERS",
+];
+
+/**
+ * A resolved connection as the environment of a child proxy process.
+ *
+ * The other way across the process boundary, for a host that cannot hand its
+ * MCP servers the inputs (DSH drops credential-shaped names from what a child
+ * inherits): the parent resolves once and the child reads the answer back. The
+ * forced `env` source makes that exact — the child reads no file, so a key the
+ * parent left empty stays empty instead of falling through to
+ * `server.root_api_key`. Every credential variable is written, the empty ones
+ * too, because the rest of the parent's environment still reaches the child:
+ * an `OPENVIKING_ACCOUNT` the parent's pinned chain ignored must not fill the
+ * gap there.
+ */
+export function forwardConnectionEnv(connection) {
+  const env = Object.fromEntries(CREDENTIAL_ENV_VARS.map((name) => [name, ""]));
+  return {
+    ...env,
+    OPENVIKING_CREDENTIAL_SOURCE: "env",
+    OPENVIKING_URL: connection.baseUrl,
+    OPENVIKING_MCP_URL: connection.mcpUrl,
+    OPENVIKING_API_KEY: connection.apiKey || "",
+    OPENVIKING_ACCOUNT: connection.account || "",
+    OPENVIKING_USER: connection.user || "",
+    OPENVIKING_PEER_ID: connection.peerId || "",
+    OPENVIKING_AUTH_MODE: connection.authMode,
+  };
+}
+
 export function trimSlash(value) {
   return String(value || "").replace(/\/+$/, "");
 }
@@ -55,7 +102,7 @@ export function defaultCredentialPaths(env = process.env) {
  * start: the proxy is what carries every memory tool, and taking those away
  * because a scope preference cannot be honoured costs the user far more than
  * the wider search does. Only the harness whose parent process injects the peer
- * (dsh, `mcp.mjs:27`) can satisfy this without the user setting it.
+ * (dsh, `mcp-env.mjs`) can satisfy this without the user setting it.
  */
 export function resolveMcpActorPeerId({
   peerId = "",
@@ -79,6 +126,67 @@ function uniq(values) {
   return [...new Set(values.filter(Boolean))];
 }
 
+/**
+ * Parse `OPENVIKING_EXTRA_HEADERS` into a plain string→string map.
+ *
+ * Some private deployments sit behind gateways that require custom headers
+ * (a tenant/vault name, a signed token, a region hint) on every request. The
+ * proxy has no other seam to inject those: the credential file's own
+ * `extra_headers` field is intentionally not exported to MCP callers (see
+ * `workspace-config.mjs` `FORBIDDEN_KEYS`), so this env-only escape hatch keeps
+ * that boundary while letting an operator unblock a strict upstream.
+ *
+ * The value is a JSON object; anything else is ignored with a stderr warning
+ * rather than crashing the proxy — a bad env var must not take down the whole
+ * memory tool surface. Reserved names (`Content-Type`, `Accept`,
+ * `MCP-Protocol-Version`, `Mcp-Session-Id`, `Authorization`) are dropped: they
+ * are set by the proxy itself and letting the env override them would break
+ * session negotiation or expose the wrong credential.
+ */
+const RESERVED_HEADER_NAMES = new Set([
+  "content-type",
+  "accept",
+  "mcp-protocol-version",
+  "mcp-session-id",
+  "authorization",
+]);
+
+export function parseExtraHeaders(raw, { onWarn = null } = {}) {
+  const source = String(raw || "").trim();
+  if (!source) return {};
+  const warn = (message) => {
+    if (typeof onWarn === "function") onWarn(message);
+    else process.stderr.write(`${message}\n`);
+  };
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (err) {
+    warn(`OPENVIKING_EXTRA_HEADERS is not valid JSON; ignoring (${err.message})`);
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    warn("OPENVIKING_EXTRA_HEADERS must be a JSON object of string values; ignoring");
+    return {};
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    const name = String(key || "").trim();
+    if (!name) continue;
+    if (RESERVED_HEADER_NAMES.has(name.toLowerCase())) {
+      warn(`OPENVIKING_EXTRA_HEADERS: ignoring reserved header "${name}"`);
+      continue;
+    }
+    if (value === null || value === undefined) continue;
+    if (typeof value === "object") {
+      warn(`OPENVIKING_EXTRA_HEADERS: header "${name}" must be a scalar; ignoring`);
+      continue;
+    }
+    out[name] = String(value);
+  }
+  return out;
+}
+
 /**
  * Shape a harness's loaded config into the object `createOpenVikingMcpProxy`
  * expects.
@@ -86,7 +194,9 @@ function uniq(values) {
  * `mcpUrl` wins over `baseUrl` when both are given, so a harness that lets the
  * user pin an explicit MCP URL keeps that behavior. `watchedPaths` are the
  * harness's own extra files; the shared defaults are appended and the result
- * deduplicated.
+ * deduplicated. `sendIdentityHeaders` carries the harness's resolved auth mode
+ * so an `api_key` server, which reads the identity out of the key and ignores
+ * the headers, never sees the operator's account and user on the wire.
  */
 export function buildMcpProxyConfig({
   baseUrl = "",
@@ -94,6 +204,7 @@ export function buildMcpProxyConfig({
   apiKey = "",
   account = "",
   user = "",
+  sendIdentityHeaders = false,
   peerId = "",
   userAgent = "",
   timeoutMs,
@@ -102,13 +213,18 @@ export function buildMcpProxyConfig({
   credentialSource = "auto",
   credentialPath = "",
   watchedPaths = [],
+  extraHeaders = null,
   env = process.env,
 } = {}) {
+  const resolvedExtraHeaders = extraHeaders && typeof extraHeaders === "object" && !Array.isArray(extraHeaders)
+    ? { ...extraHeaders }
+    : parseExtraHeaders(env.OPENVIKING_EXTRA_HEADERS);
   return {
     mcpUrl: mcpUrl || `${trimSlash(baseUrl)}/mcp`,
     apiKey: apiKey || "",
     account: account || "",
     user: user || "",
+    sendIdentityHeaders: sendIdentityHeaders === true,
     peerId: peerId || "",
     userAgent: userAgent || "",
     timeoutMs: Math.max(
@@ -120,5 +236,41 @@ export function buildMcpProxyConfig({
     credentialSource: credentialSource || "auto",
     credentialPath: credentialPath || "",
     watchedPaths: uniq([...watchedPaths, ...defaultCredentialPaths(env)]),
+    extraHeaders: resolvedExtraHeaders,
   };
 }
+
+/**
+ * The proxy config for a resolved harness config, mapped in one place.
+ *
+ * Every proxy used to copy fields out of its loader by hand, and the copies
+ * drifted: two dropped `mcpUrl`, so `OPENVIKING_MCP_URL` reached the hooks and
+ * not the tools. `cfg` is what `buildPluginConfig` or `buildProxyConnection`
+ * returned. `peerId` replaces the actor peer only for a harness whose parent
+ * process resolved it (dsh); everywhere else a long-lived proxy may send one
+ * only when actor-scoped recall asks for it.
+ */
+export function toMcpProxyConfig(cfg, {
+  env = process.env,
+  peerId = undefined,
+  debug = cfg.debug,
+  debugLogPath = cfg.debugLogPath,
+} = {}) {
+  return buildMcpProxyConfig({
+    baseUrl: cfg.baseUrl,
+    mcpUrl: cfg.mcpUrl,
+    apiKey: cfg.apiKey,
+    account: cfg.account,
+    user: cfg.user,
+    sendIdentityHeaders: cfg.sendIdentityHeaders,
+    peerId: peerId === undefined ? resolveMcpActorPeerId(cfg) : peerId,
+    userAgent: cfg.userAgent,
+    timeoutMs: cfg.timeoutMs,
+    debug,
+    debugLogPath,
+    credentialSource: cfg.credentialSource,
+    credentialPath: cfg.credentialPath || "",
+    watchedPaths: [cfg.cliPath, cfg.ovPath],
+    env,
+  });
+}

package/lib/shared/mcp-proxy-core.mjs

@@ -9,6 +9,8 @@
 import { statSync } from "node:fs";
 import { createInterface } from "node:readline";
 
+import { buildOvHeaders } from "./ov-http.mjs";
+
 const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
 const DELETE_TIMEOUT_MS = 2000;
 const MAX_CONCURRENT_REQUESTS = 16;
@@ -240,21 +242,27 @@ export function createOpenVikingMcpProxy({
   }
 
   function headersForRequest(includeSession = true) {
-    const headers = {
-      "Content-Type": "application/json",
-      "Accept": "application/json, text/event-stream",
-      // Always the proxy's current version (default, then server-negotiated) —
-      // never the client's un-negotiated ask, which strict upstreams reject
-      // with HTTP 400 before initialize negotiation can run.
-      "MCP-Protocol-Version": protocolVersion,
-    };
-    if (includeSession && sessionId) headers["Mcp-Session-Id"] = sessionId;
-    if (proxyConfig.apiKey) headers.Authorization = `Bearer ${proxyConfig.apiKey}`;
-    if (proxyConfig.account) headers["X-OpenViking-Account"] = proxyConfig.account;
-    if (proxyConfig.user) headers["X-OpenViking-User"] = proxyConfig.user;
-    if (proxyConfig.peerId) headers["X-OpenViking-Actor-Peer"] = proxyConfig.peerId;
-    if (proxyConfig.userAgent) headers["User-Agent"] = proxyConfig.userAgent;
-    return headers;
+    const built = buildOvHeaders(proxyConfig, {
+      actorPeerId: proxyConfig.peerId,
+      extraHeaders: {
+        "Accept": "application/json, text/event-stream",
+        // Always the proxy's current version (default, then server-negotiated) —
+        // never the client's un-negotiated ask, which strict upstreams reject
+        // with HTTP 400 before initialize negotiation can run.
+        "MCP-Protocol-Version": protocolVersion,
+        ...(includeSession && sessionId ? { "Mcp-Session-Id": sessionId } : {}),
+      },
+    });
+    // Operator-supplied extras (OPENVIKING_EXTRA_HEADERS) merged with the
+    // proxy's own headers winning — the env-only escape hatch fills gaps for
+    // strict private-gateway upstreams (tenant/vault names, region hints)
+    // without letting a stray env var override authentication or session
+    // negotiation.
+    const opExtras = proxyConfig.extraHeaders;
+    if (opExtras && typeof opExtras === "object") {
+      return { ...opExtras, ...built };
+    }
+    return built;
   }
 
   function writeMessage(obj) {