Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): refresh the control JWT on a broker 401 and retry once (R2-B1)

Diego Zacarias23dae0e9f4f8
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index be772b741..ba135dd08 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.245",
+ "version": "0.1.246",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.245",
+ "version": "0.1.246",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 96ac29d9f..0c8c0791f 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.245",
+ "version": "0.1.246",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index 00137a50a..965e3edd1 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -858,6 +858,18 @@ export function brokerTokenProviderDeps(): BrokerTokenProviderDeps {
gatewayUrl: () => config.mcpHostGatewayUrl,
controlToken: () =>
loadPersistedWorkflowControlToken(workflowControlTokenFromConfig() ?? '') || undefined,
+ // Reactive recovery on a control-api 401, same as every sibling consumer
+ // (setupUsageReporting wires `refreshOnUnauthorized: () => refreshWithRecovery(auth)`
+ // into UsageReporter / GovernedRunReporter / ApprovalPromptHistoryClient).
+ // Reading `runtimeAuth` at call time — not capturing it — matters: the broker
+ // factory is built during MCP init, which can run before setupUsageReporting
+ // assigns it. Without the shared auth there is nothing to refresh, and the
+ // broker keeps its previous behaviour of throwing on 401.
+ refreshControlToken: async () => {
+ const auth = runtimeAuth
+ if (!auth) return
+ await refreshWithRecovery(auth)
+ },
}
}
diff --git a/mcp-host/src/mcp/__tests__/brokerControlTokenSource.test.ts b/mcp-host/src/mcp/__tests__/brokerControlTokenSource.test.ts
index 3f108de51..94193195b 100644
--- a/mcp-host/src/mcp/__tests__/brokerControlTokenSource.test.ts
+++ b/mcp-host/src/mcp/__tests__/brokerControlTokenSource.test.ts
@@ -46,11 +46,14 @@ const boot = vi.hoisted(() => {
const bootToken = jwt(nowSecs - 1200, nowSecs - 600, 'boot-seed')
// What the in-pod self-refresh minted afterwards.
const rotatedToken = jwt(nowSecs - 60, nowSecs + 540, 'rotated')
+ // A control JWT that already rotated once and then expired again — the state
+ // an idle pod reaches between proactive refreshes (~50 min apart).
+ const staleRotatedToken = jwt(nowSecs - 900, nowSecs - 300, 'rotated-then-expired')
process.env.MCP_HOST_GATEWAY_URL = 'http://gateway.test:8092'
process.env.MCP_HOST_WORKFLOW_CONTROL_TOKEN = bootToken
delete process.env.MCP_HOST_WORKFLOW_CONTROL_TOKEN_FILE
- return { bootToken, rotatedToken }
+ return { jwt, nowSecs, bootToken, rotatedToken, staleRotatedToken }
})
const tempDirs: string[] = []
@@ -76,11 +79,23 @@ function capturingFetch() {
)
}
-function bearerOf(fetchImpl: ReturnType<typeof capturingFetch>): string | undefined {
- const init = fetchImpl.mock.calls[0][1] as RequestInit
+function bearerOf(fetchImpl: ReturnType<typeof capturingFetch>, call = 0): string | undefined {
+ const init = fetchImpl.mock.calls[call][1] as RequestInit
return (init.headers as Record<string, string>).Authorization
}
+/** A fetch stub that answers 401 until `unlock()` flips it to 200. */
+function unauthorizedThenOk() {
+ let authorized = false
+ const impl = vi.fn(
+ async (_url: string, _init: RequestInit) =>
+ (authorized
+ ? { status: 200, json: async () => ({ token: 'downstream-oauth-token', expiresAt: null }) }
+ : { status: 401, json: async () => ({ error: 'unauthorized' }) }) as unknown as Response
+ )
+ return { impl, unlock: () => (authorized = true) }
+}
+
beforeEach(() => {
delete process.env.CLERUM_WORKFLOW_AUTH_STATE_DIR
})
@@ -133,3 +148,100 @@ describe('mcp-oauth broker control token source', () => {
expect(bearerOf(fetchImpl)).toBe(`Bearer ${boot.bootToken}`)
})
})
+
+describe('mcp-oauth broker control token recovery on 401', () => {
+ it('refreshes the control JWT and retries once when control-api answers 401', async () => {
+ useStateDir()
+ // Pod state after an earlier rotation that has since expired: BOTH the
+ // persisted control token and the boot seed are past their TTL, so
+ // loadPersistedWorkflowControlToken can only return the expired seed.
+ await persistRuntimeAuthTokens({
+ accessToken: 'rotated-access',
+ refreshToken: 'rotated-refresh',
+ mcpHostControlToken: boot.staleRotatedToken,
+ })
+
+ const freshToken = boot.jwt(boot.nowSecs - 5, boot.nowSecs + 595, 'refreshed')
+ const { impl, unlock } = unauthorizedThenOk()
+
+ const provider = createBrokerTokenProvider(
+ { name: 'mcp-clickup' },
+ { userId: 'alice' },
+ {
+ ...brokerTokenProviderDeps(),
+ fetchImpl: impl as unknown as typeof fetch,
+ // Stand in for refreshWithRecovery(runtimeAuth): control-api mints a new
+ // control JWT and userApprovalRequester persists it through
+ // persistRotatedTokens -> persistRuntimeAuthTokens (the real producer).
+ refreshControlToken: async () => {
+ await persistRuntimeAuthTokens({
+ accessToken: 'refreshed-access',
+ refreshToken: 'refreshed-refresh',
+ mcpHostControlToken: freshToken,
+ })
+ unlock()
+ },
+ }
+ )
+
+ const settled = await provider.resolve().catch((err: unknown) => err)
+
+ expect(impl).toHaveBeenCalledTimes(2)
+ expect(bearerOf(impl, 0)).toBe(`Bearer ${boot.bootToken}`)
+ expect(bearerOf(impl, 1)).toBe(`Bearer ${freshToken}`)
+ expect(settled).toBe('downstream-oauth-token')
+ })
+
+ it('does not retry when the refresh produced no new control token (no loop)', async () => {
+ useStateDir()
+ const { impl } = unauthorizedThenOk()
+ const refreshControlToken = vi.fn(async () => {
+ /* control-api answered without an mcpHostControlToken — nothing rotated */
+ })
+
+ const provider = createBrokerTokenProvider(
+ { name: 'mcp-clickup' },
+ { userId: 'alice' },
+ {
+ ...brokerTokenProviderDeps(),
+ fetchImpl: impl as unknown as typeof fetch,
+ refreshControlToken,
+ }
+ )
+
+ await expect(provider.resolve()).rejects.toThrow(
+ 'mcp-oauth broker returned 401 for mcp-clickup'
+ )
+ expect(refreshControlToken).toHaveBeenCalledTimes(1)
+ expect(impl).toHaveBeenCalledTimes(1)
+ })
+
+ it('surfaces the broker 401 (not the refresh error) when the refresh itself fails', async () => {
+ useStateDir()
+ const { impl } = unauthorizedThenOk()
+
+ const provider = createBrokerTokenProvider(
+ { name: 'mcp-clickup' },
+ { userId: 'alice' },
+ {
+ ...brokerTokenProviderDeps(),
+ fetchImpl: impl as unknown as typeof fetch,
+ refreshControlToken: async () => {
+ throw new Error('refresh recovery failed')
+ },
+ }
+ )
+
+ await expect(provider.resolve()).rejects.toThrow(
+ 'mcp-oauth broker returned 401 for mcp-clickup'
+ )
+ expect(impl).toHaveBeenCalledTimes(1)
+ })
+
+ it('wires refreshControlToken into the production broker deps', () => {
+ // The behaviour above is proven against the real provider; this pins the
+ // wiring itself, which is all main.ts can expose without a live runtimeAuth
+ // (it is module-private and only assigned by the startup paths).
+ expect(typeof brokerTokenProviderDeps().refreshControlToken).toBe('function')
+ })
+})
diff --git a/mcp-host/src/mcp/brokerTokenProvider.ts b/mcp-host/src/mcp/brokerTokenProvider.ts
index f10211a2f..883038aca 100644
--- a/mcp-host/src/mcp/brokerTokenProvider.ts
+++ b/mcp-host/src/mcp/brokerTokenProvider.ts
@@ -17,6 +17,8 @@
* forwarded (surfaces as the auth failure
* U5 later turns into connect_required).
* - missing gateway / control token → undefined (fail closed).
+ * - 401 → the mcp-host control JWT expired; refresh
+ * it ONCE and retry, then throw.
* - any other non-200 / malformed 200 body → throw (never forward a stale or
* empty token).
*/
@@ -37,6 +39,17 @@ export interface BrokerTokenProviderDeps {
gatewayUrl: () => string | undefined
/** The mcp-host control JWT (scope 'oauth:user-token'). */
controlToken: () => string | undefined
+ /**
+ * Mint a fresh mcp-host control JWT after control-api rejects the current one
+ * with 401, so `controlToken()` returns a live value on the retry. This is the
+ * same reactive recovery every sibling control-api consumer already gets
+ * (`refreshOnUnauthorized: () => refreshWithRecovery(auth)` in main.ts).
+ *
+ * NOTE: this is the CONTROL JWT (mcp-host → control-api), not the downstream
+ * OAuth token that `McpTokenProvider.refresh()` re-exchanges after an
+ * mcp-server 401. Omitted → no recovery, a 401 throws as before.
+ */
+ refreshControlToken?: () => Promise<void>
/** Injectable for tests; defaults to global fetch. */
fetchImpl?: typeof fetch
/** Bounded per-request timeout; defaults to DEFAULT_BROKER_FETCH_TIMEOUT_MS. */
@@ -71,17 +84,46 @@ export function createBrokerTokenProvider(
}
if (subject.userId) body.userId = subject.userId
if (subject.contextId) body.contextId = subject.contextId
+ const payload = JSON.stringify(body)
- const res = await fetchImpl(`${gatewayUrl}/api/v1/mcp-oauth/user-token`, {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- Authorization: `Bearer ${controlToken}`,
- },
- body: JSON.stringify(body),
- // A hung broker must not stall the lazy per-user connect.
- signal: AbortSignal.timeout(timeoutMs),
- })
+ const post = async (bearer: string): Promise<Response> =>
+ fetchImpl(`${gatewayUrl}/api/v1/mcp-oauth/user-token`, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: `Bearer ${bearer}`,
+ },
+ body: payload,
+ // A hung broker must not stall the lazy per-user connect.
+ signal: AbortSignal.timeout(timeoutMs),
+ })
+
+ let res = await post(controlToken)
+
+ // The control JWT has a ~10 min TTL and only rotates when the runtime-auth
+ // chain refreshes. An idle pod therefore reaches control-api with an expired
+ // bearer and gets 401 on every exchange, with nothing in this path to heal
+ // it. Refresh ONCE and retry; the `refreshed` latch plus the "token actually
+ // changed" check bound this to a single extra request per fetchToken() call,
+ // so a refresh that fails (or that control-api answers without a new control
+ // token) cannot loop.
+ if (res.status === 401 && deps.refreshControlToken) {
+ let rotated: string | undefined
+ try {
+ await deps.refreshControlToken()
+ rotated = deps.controlToken()
+ } catch (err) {
+ // Keep the stable broker error below as the surfaced failure; the cause
+ // is logged rather than swallowed.
+ console.warn(
+ `[BrokerTokenProvider] control token refresh failed after 401 for ${server.name}:`,
+ err instanceof Error ? err.message : String(err)
+ )
+ }
+ if (rotated && rotated !== controlToken) {
+ res = await post(rotated)
+ }
+ }
if (res.status === 200) {
const data = (await res.json()) as { token?: unknown; expiresAt?: unknown }