Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(mcp-host): evict revoked OAuth partitions via a grant-existence sweep
Diego Zacariasbeb28e9a0a5e
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 03b8c7ece..8f09f8437 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.299",+ "version": "0.1.300","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.299",+ "version": "0.1.300","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex 1a78ab7a3..06b11e05a 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.299",+ "version": "0.1.300","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.tsindex bdb65d5a2..52429ce7b 100644--- a/mcp-host/src/main.ts+++ b/mcp-host/src/main.ts@@ -92,6 +92,11 @@ import {} from './mcp/authorityLifecycle'import type { HandleMcpAuthorityPollFailureOptions } from './mcp/authorityLifecycle'import { type BrokerTokenProviderDeps, createBrokerTokenProvider } from './mcp/brokerTokenProvider'+import {+ buildGrantExistenceQueries,+ checkGrantExistence,+ selectRevokedPartitionKeys,+} from './mcp/grantExistenceClient'import { McpStatusHeartbeat } from './mcp/statusHeartbeat'import { startMcpInitializationInBackground } from './mcpBackgroundInit'import { IncomingMessageHandler, PendingTaskEntry } from './messageHandler'@@ -1203,6 +1208,55 @@ export function stopContextMapperPolling(): void {contextMapperPollRunner = null}+// Guards against a slow grant-existence batch overlapping the next tick: a+// sweep in flight makes the following tick a no-op rather than stacking a+// second concurrent batch (the tick cadence < the fetch timeout in the worst+// case).+let grantRevocationSweepInFlight = false++/**+ * Hot-revocation grant-sweep (mini-spec 13 §4.1/§4.2). On the eviction timer's+ * cadence, ask control-api whether the manager's live OAuth partitions still+ * have a grant, and evict the ones that no longer do. control-api is the sole+ * authority (D4): mcp-host asks, never recomputes "connected".+ *+ * Fail-OPEN on any transient error (unconfigured gateway/token, 5xx/timeout/403,+ * network): `checkGrantExistence` throws, we conserve EVERY partition, and the+ * 15-min idle-evict remains the backstop. Only a definitive `exists:false`+ * evicts. In-flight is respected inside `evictRevokedPartitions` exactly as in+ * the idle sweep — a partition with a live tool call is skipped this tick and+ * re-evaluated next tick, never queued for deferred eviction.+ */+async function runGrantRevocationSweep(manager: McpManager): Promise<void> {+ if (grantRevocationSweepInFlight) return+ const partitions = manager.listLiveOAuthPartitions()+ if (partitions.length === 0) return+ grantRevocationSweepInFlight = true+ try {+ const results = await checkGrantExistence(+ brokerTokenProviderDeps(),+ buildGrantExistenceQueries(partitions)+ )+ // A lifecycle swap (context change / revocation) may have replaced the+ // manager while the batch was in flight; the successor sweeps its own+ // partitions next tick. Never mutate a superseded manager.+ if (mcpManager !== manager) return+ const evicted = manager.evictRevokedPartitions(selectRevokedPartitionKeys(partitions, results))+ if (evicted > 0) {+ console.log(`[Main] Grant-sweep evicted ${evicted} revoked oauth MCP partition(s)`)+ }+ } catch (err: unknown) {+ // Fail-OPEN: a control-api/gateway blip must not tear down live sessions.+ // The thrown error never carries a token (see grantExistenceClient).+ console.warn(+ '[Main] MCP grant-revocation sweep failed; conserving partitions (fail-open):',+ err instanceof Error ? err.message : String(err)+ )+ } finally {+ grantRevocationSweepInFlight = false+ }+}+/*** Start periodic MCP status heartbeat. Keeps `observedAt` fresh on every* connected server and classifies tools/list failures without interrupting@@ -1239,6 +1293,10 @@ function startMcpStatusHeartbeat(): void {} catch (err: unknown) {console.error('[Main] MCP per-user partition eviction failed:', err)}+ // Then the hot-revocation grant-sweep (mini-spec 13): ask control-api whether+ // the live OAuth partitions still have a grant and evict the revoked ones.+ // Async + self-guarded; fails open on any error (see runGrantRevocationSweep).+ void runGrantRevocationSweep(mcpManager)}, interval)}diff --git a/mcp-host/src/mcp/__tests__/grantRevocationSweep.regression.test.ts b/mcp-host/src/mcp/__tests__/grantRevocationSweep.regression.test.tsnew file mode 100644index 000000000..00a6f9791--- /dev/null+++ b/mcp-host/src/mcp/__tests__/grantRevocationSweep.regression.test.ts@@ -0,0 +1,162 @@+/**+ * T3 regression (mini-spec 13 §6) — hot revocation of an OAuth grant must cut a+ * LIVE per-user partition.+ *+ * Invariant pinned (T5, written before the implementation): after the grant is+ * deleted, running the grant-sweep evicts the per-user partition and the NEXT+ * tool call does NOT reach the server — it surfaces `connect_required`.+ *+ * Runnable against the PARENT head (4fc33594), where the sweep does not exist:+ * - imports ONLY symbols present at the parent (no grantExistenceClient, no+ * listLiveOAuthPartitions), so the setup compiles and runs there;+ * - the eviction goes through `manager.evictRevokedPartitions?.(...)` — optional+ * so a parent lacking the method NO-OPS instead of throwing in setup.+ * At the parent the partition therefore survives, the next call reuses its baked+ * Bearer and succeeds, and the `connect_required` assertion FAILS (the whole+ * point of T3). With the fix, the partition is evicted, the re-admission finds+ * no grant (404 → token-less → 401), and `connect_required` is surfaced.+ *+ * The observable asserted is the tool-call RESULT (T4), not "evictPartition was+ * called". The `exists:false` decision is derived from the SAME grant store the+ * token mint reads (T1: not an independently hand-set boolean).+ */+import { beforeEach, describe, expect, it, vi } from 'vitest'+import type { McpServerInfo } from '../../types'+import { createBrokerTokenProvider } from '../brokerTokenProvider'+import type { McpTokenProvider } from '../client'+import {+ McpManager,+ type McpPrincipal,+ type McpTokenProviderFactory,+ serializeClientKey,+ userPrincipal,+} from '../manager'++// ─── SDK mocks: callTool 401s when the current transport carries no Bearer ─────+// A missing Authorization models "no grant → no token → the server rejects". The+// 401 is thus a CONSEQUENCE of the revoked grant, not a scripted queue entry.++interface MockTransport {+ requestHeaders: Record<string, string>+ close: ReturnType<typeof vi.fn>+}++const sdk: { transports: MockTransport[] } = { transports: [] }++function http401(): Error & { code: number } {+ const err = new Error('http 401') as Error & { code: number }+ err.code = 401+ return err+}++vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({+ Client: class MockClient {+ private transport: MockTransport | null = null+ connect = vi.fn(async (t: MockTransport) => {+ this.transport = t+ })+ close = vi.fn().mockResolvedValue(undefined)+ listTools = vi.fn(async () => ({+ tools: [{ name: 'do', description: 'demo tool', inputSchema: { type: 'object' } }],+ }))+ callTool = vi.fn(async () => {+ const auth = this.transport?.requestHeaders?.['Authorization']+ if (!auth) throw http401()+ return { content: [{ type: 'text', text: 'ok' }], authorization: auth }+ })+ },+}))++vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({+ StreamableHTTPClientTransport: class MockStreamable {+ requestHeaders: Record<string, string>+ close = vi.fn().mockResolvedValue(undefined)+ constructor(_url: URL, opts?: { requestInit?: { headers?: Record<string, string> } }) {+ this.requestHeaders = opts?.requestInit?.headers ?? {}+ sdk.transports.push(this as unknown as MockTransport)+ }+ },+}))++vi.mock('@modelcontextprotocol/sdk/client/sse.js', () => ({+ SSEClientTransport: class MockSSE {+ close = vi.fn().mockResolvedValue(undefined)+ },+}))++function oauthUserServer(name = 'gh'): McpServerInfo {+ return {+ name,+ transport: { type: 'streamableHttp', url: `http://${name}/mcp` },+ authKind: 'oauth-user',+ enabled: true,+ status: { deployed: true, ready: true },+ }+}++beforeEach(() => {+ sdk.transports = []+})++describe('T3 — grant-sweep cuts a live per-user partition (surfaces connect_required)', () => {+ it('after the grant is deleted, the swept partition re-admits token-less and 401s', async () => {+ // Grant store keyed by (server, userId) — the SAME source the token mint and+ // the (simulated here) existence check derive from.+ const grantStore = new Set<string>(['gh:alice'])++ // REAL broker token provider, only the network fetch is stubbed. Returns a+ // token while the grant exists, 404 no_grant once it is deleted.+ const fetchImpl = vi.fn(async (_url: string, init: RequestInit) => {+ const body = JSON.parse(init.body as string) as { mcpServerName: string; userId?: string }+ const has = grantStore.has(`${body.mcpServerName}:${body.userId ?? ''}`)+ return (has+ ? { status: 200, json: async () => ({ token: `tok-${body.userId}`, expiresAt: null }) }+ : { status: 404, json: async () => ({ error: 'no_grant' }) }) as unknown as Response+ })++ const factory: McpTokenProviderFactory = (+ server: McpServerInfo,+ principal: McpPrincipal+ ): McpTokenProvider =>+ principal.kind === 'user'+ ? createBrokerTokenProvider(+ server,+ { userId: principal.userId },+ {+ gatewayUrl: () => 'http://gw:8092',+ controlToken: () => 'ctl',+ fetchImpl: fetchImpl as unknown as typeof fetch,+ }+ )+ : { resolve: async () => undefined, refresh: async () => undefined }++ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthUserServer('gh'))++ // Alice's partition admitted while the grant exists → the call succeeds.+ const first = await manager.callTool('gh__do', {}, { userId: 'alice' })+ expect(first.isError).toBe(false)++ // Revoke the grant (deleteOAuthGrant semantics), then run the sweep. The key+ // is computed with the same serializer the manager uses; `exists:false` is+ // read off the shared grant store (alice's entry is now gone).+ grantStore.delete('gh:alice')+ const aliceKey = serializeClientKey('gh', userPrincipal('alice'))++ // Optional so the PARENT (no such method) no-ops here instead of throwing in+ // setup; with the fix it evicts the revoked partition.+ const evict = (manager as { evictRevokedPartitions?: (keys: string[]) => number })+ .evictRevokedPartitions+ const swept = evict ? evict.call(manager, [aliceKey]) : 0++ // Observable end-state: the next call re-admits, finds no grant, and 401s →+ // connect_required. On the parent, `swept === 0`, the partition survives, the+ // baked Bearer is reused and the call succeeds → this assertion FAILS.+ const second = await manager.callTool('gh__do', {}, { userId: 'alice' })+ expect(second.isError).toBe(true)+ expect(second.connectRequired).toEqual({ mcpServerName: 'gh' })++ // Sanity for the fixed run (a no-op assertion on the parent path).+ if (evict) expect(swept).toBe(1)+ })+})diff --git a/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.ts b/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.tsnew file mode 100644index 000000000..26ab3bdea--- /dev/null+++ b/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.ts@@ -0,0 +1,502 @@+/**+ * Hot-revocation grant-sweep (mini-spec 13 §4). Covers, with the REAL manager ++ * REAL grant-existence client (only the network fetch is stubbed):+ * - the decision table §4.2, one case per row:+ * exists:true → conserve+ * exists:false + idle → evict+ * exists:false + in-flight → skip this tick, evict once it drains+ * oauth-context SHARED → swept like a per-user partition+ * transient 5xx → fail-OPEN, conserve everything+ * static/none → not a candidate (never queried)+ * - `listLiveOAuthPartitions` exposure (skips the token-less oauth-user+ * representative, includes the oauth-context SHARED partition);+ * - the client: `checkGrantExistence` (200 / refresh-on-401 / non-200 throws /+ * unconfigured throws) and `selectRevokedPartitionKeys` correlation by+ * coordinate (not position).+ *+ * The `exists` fixtures are derived from the SAME grant store the token mint+ * reads (T1: never an independently hand-set boolean), and the response shape+ * mirrors control-api's echo-the-coordinates contract.+ */+import { beforeEach, describe, expect, it, vi } from 'vitest'+import type { McpServerInfo } from '../../types'+import type { BrokerTokenProviderDeps } from '../brokerTokenProvider'+import { createBrokerTokenProvider } from '../brokerTokenProvider'+import type { McpTokenProvider } from '../client'+import {+ type GrantExistsResult,+ buildGrantExistenceQueries,+ checkGrantExistence,+ selectRevokedPartitionKeys,+} from '../grantExistenceClient'+import {+ type LiveOAuthPartition,+ McpManager,+ type McpPrincipal,+ type McpTokenProviderFactory,+ serializeClientKey,+ userPrincipal,+} from '../manager'++// ─── transport-aware SDK mock (Bearer presence drives the 401) ────────────────++interface MockTransport {+ requestHeaders: Record<string, string>+ close: ReturnType<typeof vi.fn>+}+const sdk: {+ transports: MockTransport[]+ callToolImpl: ((auth: string) => Promise<unknown>) | null+} = { transports: [], callToolImpl: null }++vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({+ Client: class MockClient {+ private transport: MockTransport | null = null+ connect = vi.fn(async (t: MockTransport) => {+ this.transport = t+ })+ close = vi.fn().mockResolvedValue(undefined)+ listTools = vi.fn(async () => ({+ tools: [{ name: 'do', description: 'demo tool', inputSchema: { type: 'object' } }],+ }))+ callTool = vi.fn(async () => {+ const auth = this.transport?.requestHeaders?.['Authorization']+ // No Bearer models "no grant → no token"; the server rejects with 401.+ if (!auth) {+ const err = new Error('http 401') as Error & { code: number }+ err.code = 401+ throw err+ }+ if (sdk.callToolImpl) return sdk.callToolImpl(auth)+ return { content: [{ type: 'text', text: 'ok' }], authorization: auth }+ })+ },+}))++vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({+ StreamableHTTPClientTransport: class MockStreamable {+ requestHeaders: Record<string, string>+ close = vi.fn().mockResolvedValue(undefined)+ constructor(_url: URL, opts?: { requestInit?: { headers?: Record<string, string> } }) {+ this.requestHeaders = opts?.requestInit?.headers ?? {}+ sdk.transports.push(this as unknown as MockTransport)+ }+ },+}))++vi.mock('@modelcontextprotocol/sdk/client/sse.js', () => ({+ SSEClientTransport: class MockSSE {+ close = vi.fn().mockResolvedValue(undefined)+ },+}))++// ─── fixtures ─────────────────────────────────────────────────────────────────++function oauthUserServer(name = 'gh'): McpServerInfo {+ return {+ name,+ transport: { type: 'streamableHttp', url: `http://${name}/mcp` },+ authKind: 'oauth-user',+ enabled: true,+ status: { deployed: true, ready: true },+ }+}+function oauthContextServer(name = 'ctx-gh'): McpServerInfo {+ return {+ name,+ contextRef: 'ctx-1',+ transport: { type: 'streamableHttp', url: `http://${name}/mcp` },+ authKind: 'oauth-context',+ enabled: true,+ status: { deployed: true, ready: true },+ }+}+function staticServer(name = 'airtable'): McpServerInfo {+ return {+ name,+ transport: { type: 'streamableHttp', url: `http://${name}/mcp` },+ authKind: 'static',+ enabled: true,+ status: { deployed: true, ready: true },+ }+}++/**+ * A single fake `fetch` for both broker endpoints, reading a shared grant store.+ * `/user-token` mints while the grant exists (404 otherwise); `/grants/exists`+ * echoes the query coordinates and reports existence from the SAME store — the+ * control-api response shape reproduced faithfully.+ */+function brokerWiring(grantStore: Set<string>): {+ deps: BrokerTokenProviderDeps+ factory: McpTokenProviderFactory+ existsCalls: Array<Array<{ mcpServerName: string; userId?: string }>>+ failExistsWith?: (status: number) => void+} {+ const existsCalls: Array<Array<{ mcpServerName: string; userId?: string }>> = []+ let existsStatus = 200+ const fetchImpl = vi.fn(async (url: string, init: RequestInit) => {+ const body = JSON.parse(init.body as string)+ if (url.endsWith('/api/v1/mcp-oauth/user-token')) {+ const has = grantStore.has(`${body.mcpServerName}:${body.userId ?? ''}`)+ return (has+ ? {+ status: 200,+ json: async () => ({ token: `tok-${body.userId ?? 'ctx'}`, expiresAt: null }),+ }+ : { status: 404, json: async () => ({ error: 'no_grant' }) }) as unknown as Response+ }+ if (url.endsWith('/api/v1/mcp-oauth/grants/exists')) {+ existsCalls.push(body.queries)+ if (existsStatus !== 200) {+ return {+ status: existsStatus,+ json: async () => ({ error: 'boom' }),+ } as unknown as Response+ }+ const results: GrantExistsResult[] = body.queries.map(+ (q: { mcpServerName: string; userId?: string }) => ({+ mcpServerName: q.mcpServerName,+ ...(q.userId !== undefined ? { userId: q.userId } : {}),+ exists: grantStore.has(`${q.mcpServerName}:${q.userId ?? ''}`),+ })+ )+ return { status: 200, json: async () => ({ results }) } as unknown as Response+ }+ throw new Error(`unexpected url ${url}`)+ })+ const deps: BrokerTokenProviderDeps = {+ gatewayUrl: () => 'http://gw:8092',+ controlToken: () => 'ctl',+ fetchImpl: fetchImpl as unknown as typeof fetch,+ }+ const factory: McpTokenProviderFactory = (+ server: McpServerInfo,+ principal: McpPrincipal+ ): McpTokenProvider => {+ if (server.authKind === 'oauth-context') {+ return createBrokerTokenProvider(server, {}, deps)+ }+ if (server.authKind === 'oauth-user' && principal.kind === 'user') {+ return createBrokerTokenProvider(server, { userId: principal.userId }, deps)+ }+ return { resolve: async () => undefined, refresh: async () => undefined }+ }+ return { deps, factory, existsCalls, failExistsWith: (s: number) => (existsStatus = s) }+}++/** The sweep exactly as main.ts wires it (no duplicated decision logic). */+async function sweepOnce(manager: McpManager, deps: BrokerTokenProviderDeps): Promise<number> {+ const partitions = manager.listLiveOAuthPartitions()+ if (partitions.length === 0) return 0+ const results = await checkGrantExistence(deps, buildGrantExistenceQueries(partitions))+ return manager.evictRevokedPartitions(selectRevokedPartitionKeys(partitions, results))+}++beforeEach(() => {+ sdk.transports = []+ sdk.callToolImpl = null+})++// ─── decision table §4.2 ─────────────────────────────────────────────────────++describe('grant-sweep decision table (mini-spec 13 §4.2)', () => {+ it('exists:true → conserves the partition', async () => {+ const grantStore = new Set(['gh:alice'])+ const { deps, factory } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthUserServer('gh'))+ await manager.callTool('gh__do', {}, { userId: 'alice' })++ expect(await sweepOnce(manager, deps)).toBe(0)+ // Still usable — the baked Bearer is intact.+ const again = await manager.callTool('gh__do', {}, { userId: 'alice' })+ expect(again.isError).toBe(false)+ })++ it('exists:false + not in-flight → evicts now', async () => {+ const grantStore = new Set(['gh:alice', 'gh:bob'])+ const { deps, factory } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthUserServer('gh'))+ await manager.callTool('gh__do', {}, { userId: 'alice' })+ await manager.callTool('gh__do', {}, { userId: 'bob' })++ grantStore.delete('gh:alice') // only alice revoked+ expect(await sweepOnce(manager, deps)).toBe(1)++ // alice re-admits token-less → connect_required; bob still works.+ const a = await manager.callTool('gh__do', {}, { userId: 'alice' })+ expect(a.connectRequired).toEqual({ mcpServerName: 'gh' })+ const b = await manager.callTool('gh__do', {}, { userId: 'bob' })+ expect(b.isError).toBe(false)+ })++ it('exists:false + in-flight → skipped this tick, evicted once it drains', async () => {+ const grantStore = new Set(['gh:alice'])+ const { deps, factory } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthUserServer('gh'))++ // Hold alice's call open. `entered` fires only once the call is actually+ // inside client.callTool — i.e. AFTER the manager registered its in-flight+ // token — so the sweep below races nothing.+ let enter!: () => void+ const entered = new Promise<void>(r => (enter = r))+ let release!: () => void+ const gate = new Promise<void>(r => (release = r))+ sdk.callToolImpl = async () => {+ enter()+ await gate+ return { content: [{ type: 'text', text: 'ok' }] }+ }+ const inFlight = manager.callTool('gh__do', {}, { userId: 'alice' })+ await entered++ grantStore.delete('gh:alice')+ // In-flight → the sweep must NOT evict it.+ expect(await sweepOnce(manager, deps)).toBe(0)+ expect(manager.getConnectedServers()).toEqual(['gh'])++ // Release the call; the partition is now drained.+ release()+ await inFlight+ sdk.callToolImpl = null++ // Next sweep evicts it, and the following call surfaces connect_required.+ expect(await sweepOnce(manager, deps)).toBe(1)+ const after = await manager.callTool('gh__do', {}, { userId: 'alice' })+ expect(after.connectRequired).toEqual({ mcpServerName: 'gh' })+ })++ it('oauth-context SHARED + in-flight → skipped this tick, evicted once it drains', async () => {+ const grantStore = new Set(['ctx-gh:'])+ const { deps, factory } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthContextServer('ctx-gh'))++ // Hold a call open on the SHARED partition. `entered` fires only once the+ // call is inside client.callTool — after the manager registered its in-flight+ // token for the SHARED key.+ let enter!: () => void+ const entered = new Promise<void>(r => (enter = r))+ let release!: () => void+ const gate = new Promise<void>(r => (release = r))+ sdk.callToolImpl = async () => {+ enter()+ await gate+ return { content: [{ type: 'text', text: 'ok' }] }+ }+ const inFlight = manager.callTool('ctx-gh__do', {}, { userId: 'alice' })+ await entered++ grantStore.delete('ctx-gh:')+ // In-flight over the SHARED → the grant-sweep must NOT close it mid-call.+ expect(await sweepOnce(manager, deps)).toBe(0)+ expect(manager.getConnectedServers()).toEqual(['ctx-gh'])++ // Drain the call, then the next sweep evicts the SHARED partition.+ release()+ await inFlight+ sdk.callToolImpl = null+ expect(await sweepOnce(manager, deps)).toBe(1)+ expect(manager.getConnectedServers()).toEqual([])+ })++ it('oauth-context SHARED partition is swept like a per-user one', async () => {+ const grantStore = new Set(['ctx-gh:']) // context grant, no userId coordinate+ const { deps, factory, existsCalls } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthContextServer('ctx-gh'))+ // The SHARED partition connects with the context token.+ const first = await manager.callTool('ctx-gh__do', {}, { userId: 'alice' })+ expect(first.isError).toBe(false)++ grantStore.delete('ctx-gh:')+ expect(await sweepOnce(manager, deps)).toBe(1)+ // The query carried NO userId (context identity stays server-side).+ expect(existsCalls.at(-1)).toEqual([{ mcpServerName: 'ctx-gh' }])+ // The server is no longer connected (SHARED evicted).+ expect(manager.getConnectedServers()).toEqual([])+ })++ it('transient 5xx → fail-OPEN: nothing is evicted', async () => {+ const grantStore = new Set(['gh:alice'])+ const { deps, factory, failExistsWith } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthUserServer('gh'))+ await manager.callTool('gh__do', {}, { userId: 'alice' })++ grantStore.delete('gh:alice') // grant IS gone, but the check errors+ failExistsWith?.(503)++ // main.ts catches this throw and conserves; here we prove the client throws+ // BEFORE any eviction and the partition is left intact.+ await expect(sweepOnce(manager, deps)).rejects.toThrow(/503/)+ expect(manager.getConnectedServers()).toEqual(['gh'])+ // Still serving on the baked Bearer (conserved).+ const still = await manager.callTool('gh__do', {}, { userId: 'alice' })+ expect(still.isError).toBe(false)+ })++ it('static/none servers are never candidates (no query, no eviction)', async () => {+ const grantStore = new Set<string>()+ const { deps, factory, existsCalls } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(staticServer('airtable'))+ // A static server has a SHARED connection via the eager path (token-less here).+ expect(manager.listLiveOAuthPartitions()).toEqual([])+ expect(await sweepOnce(manager, deps)).toBe(0)+ expect(existsCalls).toEqual([]) // never queried+ })+})++// ─── listLiveOAuthPartitions exposure ────────────────────────────────────────++describe('listLiveOAuthPartitions', () => {+ it('exposes per-user partitions but not the token-less oauth-user representative', async () => {+ const grantStore = new Set(['gh:alice', 'gh:bob'])+ const { factory } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthUserServer('gh'))+ await manager.callTool('gh__do', {}, { userId: 'alice' })+ await manager.callTool('gh__do', {}, { userId: 'bob' })++ const live = manager.listLiveOAuthPartitions()+ // Only the two per-user partitions; the SHARED representative is excluded.+ expect(live).toHaveLength(2)+ expect(live.every(p => p.flavor === 'oauth-user' && p.serverName === 'gh')).toBe(true)+ expect(live.map(p => p.userId).sort()).toEqual(['alice', 'bob'])+ expect(live.map(p => p.key).sort()).toEqual(+ [+ serializeClientKey('gh', userPrincipal('alice')),+ serializeClientKey('gh', userPrincipal('bob')),+ ].sort()+ )+ })++ it('exposes the oauth-context SHARED partition (no userId)', async () => {+ const grantStore = new Set(['ctx-gh:'])+ const { factory } = brokerWiring(grantStore)+ const manager = new McpManager(undefined, undefined, factory)+ await manager.addServer(oauthContextServer('ctx-gh'))+ await manager.callTool('ctx-gh__do', {}, { userId: 'alice' })++ const live = manager.listLiveOAuthPartitions()+ expect(live).toEqual([+ {+ flavor: 'oauth-context',+ serverName: 'ctx-gh',+ key: serializeClientKey('ctx-gh', { kind: 'shared' }),+ },+ ])+ })+})++// ─── client unit tests ───────────────────────────────────────────────────────++function res(status: number, body: unknown): Response {+ return { status, json: async () => body } as unknown as Response+}++describe('checkGrantExistence', () => {+ it('returns the results array on 200', async () => {+ const fetchImpl = vi.fn(async () =>+ res(200, { results: [{ mcpServerName: 'gh', userId: 'alice', exists: false }] })+ )+ const out = await checkGrantExistence(+ {+ gatewayUrl: () => 'http://gw',+ controlToken: () => 'ctl',+ fetchImpl: fetchImpl as unknown as typeof fetch,+ },+ [{ mcpServerName: 'gh', userId: 'alice' }]+ )+ expect(out).toEqual([{ mcpServerName: 'gh', userId: 'alice', exists: false }])+ })++ it('refreshes the control token once on 401 and retries', async () => {+ let token = 'stale'+ const fetchImpl = vi.fn(async (_url: string, init: RequestInit) => {+ const bearer = (init.headers as Record<string, string>).Authorization+ return bearer === 'Bearer stale' ? res(401, {}) : res(200, { results: [] })+ })+ const refreshControlToken = vi.fn(async () => {+ token = 'fresh'+ })+ const out = await checkGrantExistence(+ {+ gatewayUrl: () => 'http://gw',+ controlToken: () => token,+ refreshControlToken,+ fetchImpl: fetchImpl as unknown as typeof fetch,+ },+ [{ mcpServerName: 'gh', userId: 'alice' }]+ )+ expect(refreshControlToken).toHaveBeenCalledTimes(1)+ expect(fetchImpl).toHaveBeenCalledTimes(2)+ expect(out).toEqual([])+ })++ it('throws on a non-200 (fail-open at the caller)', async () => {+ const fetchImpl = vi.fn(async () => res(403, {}))+ await expect(+ checkGrantExistence(+ {+ gatewayUrl: () => 'http://gw',+ controlToken: () => 'ctl',+ fetchImpl: fetchImpl as unknown as typeof fetch,+ },+ [{ mcpServerName: 'gh' }]+ )+ ).rejects.toThrow(/403/)+ })++ it('throws when the gateway URL is unconfigured', async () => {+ await expect(+ checkGrantExistence({ gatewayUrl: () => undefined, controlToken: () => 'ctl' }, [+ { mcpServerName: 'gh' },+ ])+ ).rejects.toThrow(/gateway/i)+ })++ it('returns [] without any fetch when there are no queries', async () => {+ const fetchImpl = vi.fn()+ const out = await checkGrantExistence(+ {+ gatewayUrl: () => 'http://gw',+ controlToken: () => 'ctl',+ fetchImpl: fetchImpl as unknown as typeof fetch,+ },+ []+ )+ expect(out).toEqual([])+ expect(fetchImpl).not.toHaveBeenCalled()+ })+})++describe('selectRevokedPartitionKeys — correlation by coordinate, not position', () => {+ it('picks only the revoked coordinate even when results are reordered', () => {+ const partitions: LiveOAuthPartition[] = [+ { flavor: 'oauth-user', serverName: 'gh', userId: 'alice', key: 'KEY-A' },+ { flavor: 'oauth-user', serverName: 'gh', userId: 'bob', key: 'KEY-B' },+ { flavor: 'oauth-context', serverName: 'ctx', key: 'KEY-CTX' },+ ]+ // Results out of order; only bob and the context grant are gone.+ const results: GrantExistsResult[] = [+ { mcpServerName: 'ctx', exists: false },+ { mcpServerName: 'gh', userId: 'alice', exists: true },+ { mcpServerName: 'gh', userId: 'bob', exists: false },+ ]+ expect(selectRevokedPartitionKeys(partitions, results).sort()).toEqual(['KEY-B', 'KEY-CTX'])+ })++ it('a missing/non-false exists conserves (fail-open)', () => {+ const partitions: LiveOAuthPartition[] = [+ { flavor: 'oauth-user', serverName: 'gh', userId: 'alice', key: 'KEY-A' },+ ]+ // A malformed entry without a boolean `exists` must NOT evict.+ const results = [{ mcpServerName: 'gh', userId: 'alice' }] as unknown as GrantExistsResult[]+ expect(selectRevokedPartitionKeys(partitions, results)).toEqual([])+ })+})diff --git a/mcp-host/src/mcp/grantExistenceClient.ts b/mcp-host/src/mcp/grantExistenceClient.tsnew file mode 100644index 000000000..43d37a118--- /dev/null+++ b/mcp-host/src/mcp/grantExistenceClient.ts@@ -0,0 +1,156 @@+/**+ * Grant-existence client for the hot-revocation poll-sweep (mini-spec 13+ * §4.1/§4.3). Sibling of `brokerTokenProvider.ts` — it reaches the SAME+ * control-api OAuth broker through the SAME workflow-approval gateway, reusing+ * that module's `BrokerTokenProviderDeps` (gateway URL + control JWT accessor ++ * refresh-on-401) and its house fetch timeout WITHOUT editing it. Where the+ * broker MINTS a per-connection token, this only ASKS — a read-only batch+ * `POST /api/v1/mcp-oauth/grants/exists` that returns booleans, never a token.+ *+ * D4 — control-api is the sole authority for the grant: mcp-host asks, never+ * recomputes "connected". The sweep that consumes this evicts a partition ONLY+ * on a definitive `exists:false`; ANY error here THROWS so the caller fails+ * OPEN (conserve every partition — a control-api/gateway blip must not tear down+ * live sessions; the 15-min idle-evict is the backstop, §4.2).+ */+import type { BrokerTokenProviderDeps } from './brokerTokenProvider'+import { DEFAULT_BROKER_FETCH_TIMEOUT_MS } from './brokerTokenProvider'+import type { LiveOAuthPartition } from './manager'++/**+ * One entry of the batch request. Mirrors control-api's `GrantExistsQuery`.+ * `userId` addresses an `oauth-user` grant; `oauth-context` sends neither+ * coordinate (control-api keys the shared grant by the server's authoritative+ * `contextRef`, server-side — mcp-host transports no context identity).+ */+export interface GrantExistsQuery {+ mcpServerName: string+ userId?: string+ contextId?: string+}++/**+ * One entry of the response. control-api ECHOES the query coordinates so the+ * consumer correlates by tuple, not by array position; `exists` is the only+ * new field. Never a token, never the authoritative contextRef, never a key.+ */+export interface GrantExistsResult {+ mcpServerName: string+ userId?: string+ contextId?: string+ exists: boolean+}++/**+ * POST the batch grant-existence query to the gateway and return control-api's+ * `results`. Reuses the broker's refresh-on-401 (an idle pod's control JWT+ * expires; refresh ONCE and retry — bounded to one extra request). THROWS on+ * every failure mode (unconfigured gateway/token, non-200 incl. 403/5xx,+ * malformed body, network/timeout) so the sweep fails OPEN. Never logs or+ * returns a token.+ */+export async function checkGrantExistence(+ deps: BrokerTokenProviderDeps,+ queries: readonly GrantExistsQuery[]+): Promise<GrantExistsResult[]> {+ if (queries.length === 0) return []+ const fetchImpl = deps.fetchImpl ?? fetch+ const timeoutMs = deps.timeoutMs ?? DEFAULT_BROKER_FETCH_TIMEOUT_MS++ const gatewayUrl = deps.gatewayUrl()?.trim()+ if (!gatewayUrl) {+ throw new Error('mcp-oauth grant-existence: gateway URL not configured')+ }+ const controlToken = deps.controlToken()+ if (!controlToken) {+ throw new Error('mcp-oauth grant-existence: control token unavailable')+ }+ const payload = JSON.stringify({ queries })++ const post = async (bearer: string): Promise<Response> =>+ fetchImpl(`${gatewayUrl}/api/v1/mcp-oauth/grants/exists`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Authorization: `Bearer ${bearer}`,+ },+ body: payload,+ // A hung broker must not stall the eviction tick past its cadence.+ signal: AbortSignal.timeout(timeoutMs),+ })++ let res = await post(controlToken)++ // Same reactive recovery as brokerTokenProvider: the control JWT has a ~10 min+ // TTL and an idle pod reaches control-api with an expired bearer. Refresh ONCE+ // and retry; the "token actually changed" check bounds this to a single extra+ // request, so a refresh that fails cannot loop.+ if (res.status === 401 && deps.refreshControlToken) {+ let rotated: string | undefined+ try {+ await deps.refreshControlToken()+ rotated = deps.controlToken()+ } catch {+ // Fall through with the original 401; the throw below surfaces the failure+ // (and the sweep conserves). The cause is not swallowed silently — the+ // caller logs the thrown error.+ }+ if (rotated && rotated !== controlToken) {+ res = await post(rotated)+ }+ }++ if (res.status !== 200) {+ throw new Error(`mcp-oauth grant-existence returned ${res.status}`)+ }+ const data = (await res.json()) as { results?: unknown }+ if (!Array.isArray(data.results)) {+ throw new Error('mcp-oauth grant-existence returned a malformed body')+ }+ return data.results as GrantExistsResult[]+}++/** Stable coordinate key. `oauth-context` carries no userId → normalized to null. */+function coordKey(mcpServerName: string, userId?: string): string {+ return JSON.stringify([mcpServerName, userId ?? null])+}++/**+ * Build the batch query for the live OAuth partitions. Single source of the+ * coordinate convention (D4-adjacent): `oauth-user` sends its `userId`,+ * `oauth-context` sends only `mcpServerName`. Paired with+ * `selectRevokedPartitionKeys`, which reverses the SAME convention.+ */+export function buildGrantExistenceQueries(+ partitions: readonly LiveOAuthPartition[]+): GrantExistsQuery[] {+ return partitions.map(p => {+ const q: GrantExistsQuery = { mcpServerName: p.serverName }+ if (p.userId !== undefined) q.userId = p.userId+ return q+ })+}++/**+ * Correlate the batch results back to partition keys BY COORDINATE (not array+ * position — two per-user partitions of one server must stay distinguishable)+ * and select the keys whose grant is definitively absent. Only a strict+ * `exists === false` selects a key; true, missing, or a malformed entry+ * conserves (fail-closed on definitive revocation, fail-OPEN on everything+ * else). Returns the partition keys the sweep passes to+ * `manager.evictRevokedPartitions`.+ */+export function selectRevokedPartitionKeys(+ partitions: readonly LiveOAuthPartition[],+ results: readonly GrantExistsResult[]+): string[] {+ const byCoord = new Map<string, string>()+ for (const p of partitions) byCoord.set(coordKey(p.serverName, p.userId), p.key)+ const keys: string[] = []+ for (const r of results) {+ if (r.exists !== false) continue+ const key = byCoord.get(coordKey(r.mcpServerName, r.userId))+ if (key) keys.push(key)+ }+ return keys+}diff --git a/mcp-host/src/mcp/manager.ts b/mcp-host/src/mcp/manager.tsindex 37bdcf813..70211a8b1 100644--- a/mcp-host/src/mcp/manager.ts+++ b/mcp-host/src/mcp/manager.ts@@ -74,6 +74,35 @@ export function serverNameFromClientKey(key: string): string {return (JSON.parse(key) as [string, string, string?])[1]}+/**+ * Recover the principal from a serialized ClientKey — inverse of the+ * discriminator `serializeClientKey` writes (`'u'` → user, else SHARED). Used by+ * the grant-sweep to tell a per-user partition from the token-less SHARED+ * representative of an oauth-user server.+ */+export function principalFromClientKey(key: string): McpPrincipal {+ const parsed = JSON.parse(key) as ['s' | 'u', string, string?]+ return parsed[0] === 'u' && typeof parsed[2] === 'string'+ ? userPrincipal(parsed[2])+ : SHARED_PRINCIPAL+}++/** The OAuth flavor of a live partition the hot-revocation sweep re-validates. */+export type OAuthPartitionFlavor = 'oauth-user' | 'oauth-context'++/**+ * A live OAuth partition exposed to the hot-revocation grant-sweep (mini-spec+ * 13 §4.1). `key` is the serialized ClientKey the sweep hands back to+ * `evictRevokedPartitions`; the coordinates address the grant in control-api+ * (`userId` present only for `oauth-user`).+ */+export interface LiveOAuthPartition {+ flavor: OAuthPartitionFlavor+ serverName: string+ userId?: string+ key: string+}+/** Factory that builds a per-connection token provider for an oauth server. */export type McpTokenProviderFactory = (server: McpServerInfo,@@ -529,10 +558,9 @@ export class McpManager {evictIdleUserPartitions(maxIdleMs: number, maxUserPartitions?: number): number {const now = Date.now()let evicted = 0- const inFlight = (key: string): boolean => (this.partitionInFlight.get(key)?.size ?? 0) > 0// TTL pass — never evict a partition with a live tool call.for (const [key, lastUsed] of [...this.partitionLastUsed]) {- if (inFlight(key)) continue+ if (this.partitionHasInFlightCall(key)) continueif (now - lastUsed >= maxIdleMs) {this.evictPartition(key)evicted += 1@@ -541,7 +569,7 @@ export class McpManager {// LRU-cap pass — same in-flight exemption; only idle partitions are candidates.if (maxUserPartitions !== undefined && this.partitionLastUsed.size > maxUserPartitions) {const ordered = [...this.partitionLastUsed.entries()]- .filter(([key]) => !inFlight(key))+ .filter(([key]) => !this.partitionHasInFlightCall(key)).sort((a, b) => a[1] - b[1])const overflow = this.partitionLastUsed.size - maxUserPartitionsfor (let i = 0; i < overflow && i < ordered.length; i++) {@@ -552,6 +580,70 @@ export class McpManager {return evicted}+ /**+ * List the live OAuth partitions whose grant the hot-revocation sweep must+ * re-validate against control-api (mini-spec 13 §4.1). Read-only and additive+ * — no live state is mutated. By flavor:+ * - `oauth-user`: every per-user partition (the token-less SHARED+ * representative carries no grant, so it is deliberately skipped).+ * - `oauth-context`: the single SHARED partition, which itself holds the+ * context grant (control-api keys it by the server's contextRef).+ * `static`/`none` servers contribute nothing.+ */+ listLiveOAuthPartitions(): LiveOAuthPartition[] {+ const partitions: LiveOAuthPartition[] = []+ for (const [serverName, keys] of this.byServer) {+ const authKind = this.serverInfos.get(serverName)?.authKind+ if (authKind === 'oauth-user') {+ for (const key of keys) {+ const principal = principalFromClientKey(key)+ if (principal.kind === 'user') {+ partitions.push({ flavor: 'oauth-user', serverName, userId: principal.userId, key })+ }+ }+ } else if (authKind === 'oauth-context') {+ const key = this.sharedKey(serverName)+ if (this.clients.has(key)) {+ partitions.push({ flavor: 'oauth-context', serverName, key })+ }+ }+ }+ return partitions+ }++ /**+ * Evict the OAuth partitions whose grant control-api reports absent (the+ * hot-revocation grant-sweep, mini-spec 13 §4.2). The caller supplies only the+ * keys of `exists:false` partitions; this reuses `evictPartition` under the+ * SAME in-flight exemption as `evictIdleUserPartitions` — a partition with a+ * live tool call is SKIPPED this tick and re-evaluated on the next sweep+ * (~30s) once `partitionInFlight` drains, never queued for deferred eviction.+ * Idempotent: a key with no live partition is a no-op and is not counted.+ * Returns the count evicted.+ */+ evictRevokedPartitions(keys: Iterable<string>): number {+ let evicted = 0+ for (const key of keys) {+ // Respect in-flight, via the SAME predicate the idle sweep uses: the+ // active call started authorized moments ago.+ if (this.partitionHasInFlightCall(key)) continue+ // Idempotent: nothing live under this key (already evicted / re-keyed).+ if (!this.clients.has(key)) continue+ this.evictPartition(key)+ evicted += 1+ }+ return evicted+ }++ /**+ * The in-flight exemption predicate shared by every eviction sweep (idle ++ * grant-revocation): a partition with ≥1 live tool-call token is NEVER evicted.+ * Single-sourced so the two sweeps can never drift on this invariant (D4).+ */+ private partitionHasInFlightCall(key: string): boolean {+ return (this.partitionInFlight.get(key)?.size ?? 0) > 0+ }+private releaseInFlight(key: string, token: symbol): void {// Remove only THIS call's token. If the partition was force-evicted and// re-admitted under a fresh Set, this no-ops on the new Set instead of@@ -763,6 +855,16 @@ export class McpManager {// Only the per-user oauth sabor gets per-user partitions. oauth-context and// static both resolve on the SHARED representative (the else branch below).const isOauthUser = info?.authKind === 'oauth-user'+ // oauth-context serves over the SHARED partition, but that partition IS+ // grant-sweep-evictable (listLiveOAuthPartitions exposes it). So it must also+ // pin an in-flight token for the call's duration, or the grant-sweep could+ // close the connection mid-call (respect-in-flight, spec §5). It does NOT+ // pin partitionLastUsed — that map drives the idle sweep, which must never+ // idle-evict a snapshot-driven oauth-context SHARED partition.+ const isOauthContext = info?.authKind === 'oauth-context'+ // Partitions the eviction sweeps can reclaim → the ones that must register+ // an in-flight claim while a call is running.+ const pinsInFlight = isOauthUser || isOauthContextlet key: stringif (isOauthUser) {@@ -839,8 +941,15 @@ export class McpManager {if (isOauthUser) {// Stamp usage only once the partition is confirmed live (a 'stale'// admission installs no client) so no phantom entry counts toward the cap.+ // oauth-user ONLY: partitionLastUsed feeds the idle sweep (LRU + TTL) whose+ // subjects are the per-user partitions; the oauth-context SHARED partition+ // is deliberately absent from it (never idle-evicted).this.partitionLastUsed.set(key, Date.now())- // Pin the partition against idle eviction for the duration of this call.+ }+ if (pinsInFlight) {+ // Pin the partition against BOTH eviction sweeps (idle + grant-revocation)+ // for the duration of this call — same register-on-enter / clear-in-finally+ // pattern for oauth-user per-user and oauth-context SHARED alike.let set = this.partitionInFlight.get(key)if (!set) {set = new Set()@@ -899,7 +1008,7 @@ export class McpManager {isError: true,}} finally {- if (isOauthUser) this.releaseInFlight(key, callToken)+ if (pinsInFlight) this.releaseInFlight(key, callToken)}}