fix(mcp): resolve the auth token per request so rotation needs no restart

Backport of dba-agent 5d7ffc3 (mcp/ portion only).

The MCP server is a long-lived stdio subprocess that snapshotted
DEEPSQL_AUTH_TOKEN once at spawn into an immutable config. Where a provisioner
rotates the token on disk without respawning the process, the captured token
eventually expires, every tool call silently 401s, and re-provisioning is ignored
by the dead process — a restart being the only remediation.

The bearer token is now resolved per request from DEEPSQL_TOKEN_FILE, cached by
mtime so disk is touched only when the file actually changes, with a single
re-read-and-retry on 401 when the token has since rotated. 403 is never retried
(RBAC denial, not stale creds), and installs with no token file keep using the
env snapshot, so editor and CLI behaviour is unchanged.

Scope note: the commit's hermes/deploy/provisioner.py and provision-profile.sh
changes are deliberately NOT ported — this distribution does not ship the
containerised agent. Nothing here writes DEEPSQL_TOKEN_FILE, and setup-agent.sh
mints a token with no expiry (POST /auth/mcp-tokens with no expiresAt), so the
rotation path is currently inert for self-host. It is ported for parity and for
anyone running their own provisioner; the env-snapshot fallback means it costs
nothing when unused.

Also documents why agent.provisioner-url defaults to a deepsql-agent container
that this stack does not run: provisioning is gated on agent.provision-secret,
which is unset by default, so the unreachable URL is never contacted and
setup-agent.sh writes the u-<user> profile locally instead. Behaviour unchanged;
the default value is untouched.

Tests: 259/259 (up from 252 — 7 ported cases covering token-file reads, the mtime
cache, the 401 retry, 403 not retrying, and createConfigFromEnv wiring).

Author: geekypunk

backend/src/main/java/com/dbaagent/service/AgentBridgeService.java

@@ -61,7 +61,21 @@ public AgentBridgeService(McpTokenService mcpTokenService) {
     @Value("${agent.provision-enabled:true}")
     private boolean provisionEnabled;
 
-    /** The agent container's internal provisioning endpoint (compose network). */
+    /**
+     * The agent provisioner endpoint.
+     *
+     * <p>The default names a {@code deepsql-agent} container this distribution does
+     * <em>not</em> ship: the self-host stack is four containers (postgres, valkey,
+     * backend, frontend) and Hermes runs on the host via
+     * {@code scripts/self-host/setup-agent.sh}. Nothing resolves that hostname here,
+     * so the default is unreachable by design and kept only for deployments running
+     * their own containerised provisioner.
+     *
+     * <p>That is harmless because provisioning is gated on {@code provisionSecret}
+     * below: unset — the default — no request is ever sent to this URL, and
+     * {@code setup-agent.sh} writes the {@code u-<user>} profile locally instead.
+     * Set both values only if you run your own provisioner.
+     */
     @Value("${agent.provisioner-url:http://deepsql-agent:8788/provision}")
     private String provisionerUrl;
 

mcp/deepsql-phase1-lib.js

@@ -1,3 +1,5 @@
+const fs = require("fs");
+
 const ALLOWED_READ_ONLY_KEYWORDS = new Set([
   "SELECT",
   "WITH",
@@ -1038,14 +1040,60 @@ function clampInteger(value, min, max, fallback) {
   return Math.min(max, Math.max(min, parsed));
 }
 
+// Live bearer-token resolution. The MCP server is a long-lived stdio
+// subprocess; inside the DeepSQL Agent container the provisioner rotates the
+// token on disk (DEEPSQL_TOKEN_FILE) WITHOUT respawning us. Reading the token
+// per request — cached by mtime so we only touch disk when the file actually
+// changes — lets a rotated token take effect with no container restart. Editor
+// and CLI installs set no token file and keep using the env snapshot
+// (config.authToken), so their behaviour is unchanged.
+let _tokenFileCache = null; // { path, mtimeMs, token }
+
+function readTokenFile(tokenFile) {
+  const stat = fs.statSync(tokenFile);
+  if (
+    _tokenFileCache &&
+    _tokenFileCache.path === tokenFile &&
+    _tokenFileCache.mtimeMs === stat.mtimeMs
+  ) {
+    return _tokenFileCache.token;
+  }
+  const token = fs.readFileSync(tokenFile, "utf8").trim();
+  _tokenFileCache = { path: tokenFile, mtimeMs: stat.mtimeMs, token };
+  return token;
+}
+
+function getAuthToken(config) {
+  if (config && config.tokenFile) {
+    try {
+      const token = readTokenFile(config.tokenFile);
+      if (token) {
+        return token;
+      }
+    } catch {
+      // Any stat/read error → fall back to the env token snapshot so we never
+      // hard-fail just because the file is momentarily missing mid-rewrite.
+    }
+  }
+  return (config && config.authToken) || "";
+}
+
+// Force the next getAuthToken() to re-read from disk regardless of mtime. Used
+// by the 401 self-heal path, where the provisioner may have just rewritten the
+// token file (same second → identical mtime granularity on some filesystems).
+function invalidateTokenCache() {
+  _tokenFileCache = null;
+}
+
 function buildHeaders(config, extraHeaders = {}) {
   const headers = {
     Accept: "application/json",
     ...extraHeaders,
   };
 
-  if (config.authToken) {
-    headers.Authorization = `Bearer ${config.authToken}`;
+  const authToken = getAuthToken(config);
+  if (authToken) {
+    headers.Authorization = `Bearer ${authToken}`;
   }
 
   // Origin-tracking headers so the backend audit row can distinguish
@@ -1070,13 +1118,13 @@ function resolveApiUrl(baseUrl, path) {
   return new URL(normalizedPath, baseUrl).toString();
 }
 
-async function callDeepSqlApi(config, path, { method = "GET", json, headers } = {}) {
+async function performFetch(config, path, { method = "GET", json, headers } = {}) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
   const url = resolveApiUrl(config.baseUrl, path);
 
   try {
-    const response = await fetch(url, {
+    return await fetch(url, {
       method,
       headers: buildHeaders(
         config,
@@ -1090,26 +1138,6 @@ async function callDeepSqlApi(config, path, { method = "GET", json, headers } =
       body: json == null ? undefined : JSON.stringify(json),
       signal: controller.signal,
     });
-
-    const rawBody = await response.text();
-    let payload = null;
-    if (rawBody) {
-      try {
-        payload = JSON.parse(rawBody);
-      } catch {
-        payload = rawBody;
-      }
-    }
-
-    if (!response.ok) {
-      const message =
-        (payload && typeof payload === "object" && payload.message) ||
-        response.statusText ||
-        "DeepSQL API request failed";
-      throw new DeepSqlApiError(message, response.status, payload);
-    }
-
-    return payload;
   } catch (error) {
     if (error.name === "AbortError") {
       throw new DeepSqlApiError(
@@ -1124,6 +1152,44 @@ async function callDeepSqlApi(config, path, { method = "GET", json, headers } =
   }
 }
 
+async function callDeepSqlApi(config, path, options = {}) {
+  const tokenBefore = getAuthToken(config);
+  let response = await performFetch(config, path, options);
+
+  // 401 self-heal: our long-lived subprocess may be holding a token the agent
+  // provisioner has since rotated on disk. Re-read the token file (bypassing
+  // the mtime cache) and retry exactly once if it actually changed. We
+  // deliberately do NOT retry 403 — that's an RBAC denial, not stale creds —
+  // and only retry when a tokenFile is configured (editor/CLI installs aren't).
+  if (response.status === 401 && config && config.tokenFile) {
+    invalidateTokenCache();
+    const tokenAfter = getAuthToken(config);
+    if (tokenAfter && tokenAfter !== tokenBefore) {
+      response = await performFetch(config, path, options);
+    }
+  }
+
+  const rawBody = await response.text();
+  let payload = null;
+  if (rawBody) {
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      payload = rawBody;
+    }
+  }
+
+  if (!response.ok) {
+    const message =
+      (payload && typeof payload === "object" && payload.message) ||
+      response.statusText ||
+      "DeepSQL API request failed";
+    throw new DeepSqlApiError(message, response.status, payload);
+  }
+
+  return payload;
+}
+
 function summarizeConnections(connections) {
   const lines = connections.map((connection) => {
     const name = connection.connectionName || connection.name || connection.id;
@@ -1677,7 +1743,7 @@ const CONNECTIONS_CACHE_TTL_MS = 30000;
 let _connectionsCache = null; // { key, ts, payload }
 
 async function fetchConnectionsCached(config) {
-  const key = `${(config && config.baseUrl) || ""}|${(config && config.authToken) || ""}`;
+  const key = `${(config && config.baseUrl) || ""}|${getAuthToken(config)}`;
   if (_connectionsCache && _connectionsCache.key === key
       && Date.now() - _connectionsCache.ts < CONNECTIONS_CACHE_TTL_MS) {
     return _connectionsCache.payload;
@@ -2273,6 +2339,10 @@ function createConfigFromEnv(env = process.env) {
   return {
     baseUrl,
     authToken: env.DEEPSQL_AUTH_TOKEN || "",
+    // Optional path to a file holding just the bearer token. When set (the
+    // agent-container case), getAuthToken reads it live per request so a
+    // provisioner-rotated token takes effect without respawning this process.
+    tokenFile: env.DEEPSQL_TOKEN_FILE || null,
     timeoutMs: clampInteger(env.DEEPSQL_MCP_TIMEOUT_MS, 1000, 600000, 120000),
     defaultUserId: env.DEEPSQL_MCP_USER_ID || "mcp-phase1",
     defaultProjectId: env.DEEPSQL_MCP_PROJECT_ID || "mcp-phase1",
@@ -2296,7 +2366,9 @@ module.exports = {
   containsForbiddenKeyword,
   createConfigFromEnv,
   firstKeyword,
+  getAuthToken,
   handleToolCall,
+  invalidateTokenCache,
   normalizeSqlForInspection,
   resolveApiUrl,
   splitStatements,

mcp/deepsql-phase1-lib.test.js

@@ -1,5 +1,8 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
 
 const {
   resolveApiUrl,
@@ -10,8 +13,47 @@ const {
   validateReadOnlySql,
   TOOL_DEFINITIONS,
   handleToolCall,
+  callDeepSqlApi,
+  createConfigFromEnv,
+  getAuthToken,
+  invalidateTokenCache,
 } = require("./deepsql-phase1-lib");
 
+function tmpTokenFile(contents) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dsql-tok-"));
+  const p = path.join(dir, "deepsql.token");
+  fs.writeFileSync(p, contents);
+  return p;
+}
+
+// Install a global.fetch stub that records the Authorization header on each
+// request and returns queued responses. Returns { authHeaders, restore }.
+// Each response entry is { status, ok, body, onCall? } — onCall fires before
+// the response is returned, letting a test rotate the token file mid-flight.
+function installFetchStub(responses) {
+  const authHeaders = [];
+  const original = global.fetch;
+  let i = 0;
+  global.fetch = async (_url, init) => {
+    authHeaders.push(init && init.headers ? init.headers.Authorization : undefined);
+    const spec = responses[Math.min(i, responses.length - 1)];
+    i += 1;
+    if (spec && typeof spec.onCall === "function") {
+      spec.onCall();
+    }
+    const status = spec?.status ?? 200;
+    return {
+      ok: spec?.ok ?? (status >= 200 && status < 300),
+      status,
+      statusText: spec?.statusText ?? "OK",
+      async text() {
+        return JSON.stringify(spec?.body ?? {});
+      },
+    };
+  };
+  return { authHeaders, restore: () => { global.fetch = original; } };
+}
+
 test("resolveApiUrl keeps the /api prefix for absolute-looking tool paths", () => {
   const result = resolveApiUrl("http://localhost:8080/api/", "/connections");
   assert.equal(result, "http://localhost:8080/api/connections");
@@ -870,3 +912,118 @@ test("Phase A tools that require connectionId reject empty input cleanly (no net
     assert.equal(calls.length, 0, `${name} must not hit the network on validation failure`);
   }
 });
+
+// ─── Live token resolution + 401 self-heal ─────────────────────────────────
+// The MCP server is a long-lived subprocess; in the agent container the token
+// is rotated on disk without respawning us. These tests cover getAuthToken's
+// mtime-cached live read, buildHeaders/callDeepSqlApi picking up a rotated
+// token, and the one-shot 401 self-heal retry.
+
+test("createConfigFromEnv wires DEEPSQL_TOKEN_FILE and keeps the env token fallback", () => {
+  const withFile = createConfigFromEnv({ DEEPSQL_TOKEN_FILE: "/x/y.token", DEEPSQL_AUTH_TOKEN: "z" });
+  assert.equal(withFile.tokenFile, "/x/y.token");
+  assert.equal(withFile.authToken, "z");
+  const without = createConfigFromEnv({});
+  assert.equal(without.tokenFile, null);
+});
+
+test("getAuthToken caches by mtime and re-reads only when the file changes", () => {
+  invalidateTokenCache();
+  const p = tmpTokenFile("tok1\n");
+  const cfg = { tokenFile: p, authToken: "envtok" };
+  const realRead = fs.readFileSync;
+  let reads = 0;
+  fs.readFileSync = (...a) => { reads += 1; return realRead(...a); };
+  try {
+    assert.equal(getAuthToken(cfg), "tok1");
+    assert.equal(getAuthToken(cfg), "tok1");
+    assert.equal(reads, 1, "unchanged mtime → served from cache, no second read");
+    const later = new Date(Date.now() + 10000);
+    fs.writeFileSync(p, "tok2\n");
+    fs.utimesSync(p, later, later);
+    assert.equal(getAuthToken(cfg), "tok2");
+    assert.equal(reads, 2, "mtime advanced → re-read from disk");
+  } finally {
+    fs.readFileSync = realRead;
+  }
+});
+
+test("getAuthToken falls back to the env token when no file / unreadable file", () => {
+  invalidateTokenCache();
+  assert.equal(getAuthToken({ authToken: "envtok" }), "envtok");
+  assert.equal(getAuthToken({ tokenFile: "/no/such/deepsql.token", authToken: "envtok" }), "envtok");
+  assert.equal(getAuthToken({ tokenFile: "/no/such/deepsql.token" }), "");
+});
+
+test("callDeepSqlApi sends the live token and reflects a rotation mid-process", async () => {
+  invalidateTokenCache();
+  const p = tmpTokenFile("tokA\n");
+  const cfg = { baseUrl: "http://test/api/", tokenFile: p, timeoutMs: 5000 };
+  const stub = installFetchStub([{ body: {} }, { body: {} }]);
+  try {
+    await callDeepSqlApi(cfg, "/connections");
+    const later = new Date(Date.now() + 10000);
+    fs.writeFileSync(p, "tokB\n");
+    fs.utimesSync(p, later, later);
+    await callDeepSqlApi(cfg, "/connections");
+  } finally {
+    stub.restore();
+  }
+  assert.equal(stub.authHeaders[0], "Bearer tokA");
+  assert.equal(stub.authHeaders[1], "Bearer tokB", "rotated token used without restart");
+});
+
+test("callDeepSqlApi self-heals a 401 by re-reading a rotated token and retrying once", async () => {
+  invalidateTokenCache();
+  const p = tmpTokenFile("stale\n");
+  const cfg = { baseUrl: "http://test/api/", tokenFile: p, timeoutMs: 5000 };
+  const stub = installFetchStub([
+    {
+      status: 401,
+      ok: false,
+      statusText: "Unauthorized",
+      body: { message: "unauthorized" },
+      // Provisioner rotates the token concurrently with the failing call.
+      onCall: () => {
+        const later = new Date(Date.now() + 10000);
+        fs.writeFileSync(p, "fresh\n");
+        fs.utimesSync(p, later, later);
+      },
+    },
+    { body: { ok: true } },
+  ]);
+  try {
+    const result = await callDeepSqlApi(cfg, "/connections");
+    assert.deepEqual(result, { ok: true });
+  } finally {
+    stub.restore();
+  }
+  assert.equal(stub.authHeaders.length, 2, "exactly one retry");
+  assert.equal(stub.authHeaders[0], "Bearer stale");
+  assert.equal(stub.authHeaders[1], "Bearer fresh");
+});
+
+test("callDeepSqlApi does not retry a 401 when no token file is configured", async () => {
+  invalidateTokenCache();
+  const cfg = { baseUrl: "http://test/api/", authToken: "envtok", timeoutMs: 5000 };
+  const stub = installFetchStub([{ status: 401, ok: false, statusText: "Unauthorized", body: { message: "nope" } }]);
+  try {
+    await assert.rejects(() => callDeepSqlApi(cfg, "/connections"), /nope/);
+  } finally {
+    stub.restore();
+  }
+  assert.equal(stub.authHeaders.length, 1, "env-only install must not retry");
+});
+
+test("callDeepSqlApi does not retry a 401 when the token file is unchanged", async () => {
+  invalidateTokenCache();
+  const p = tmpTokenFile("same\n");
+  const cfg = { baseUrl: "http://test/api/", tokenFile: p, timeoutMs: 5000 };
+  const stub = installFetchStub([{ status: 401, ok: false, statusText: "Unauthorized", body: { message: "nope" } }]);
+  try {
+    await assert.rejects(() => callDeepSqlApi(cfg, "/connections"), /nope/);
+  } finally {
+    stub.restore();
+  }
+  assert.equal(stub.authHeaders.length, 1, "unchanged token → no pointless retry");
+});