From c45f53d495b91ded86bb017c43affe29d94113d8 Mon Sep 17 00:00:00 2001 From: Ju Liu Date: Fri, 21 Aug 2026 12:36:28 +0100 Subject: [PATCH] Back off on MCP auth failures across service-worker restarts The MV3 service worker restarts constantly and re-runs remote MCP reconciliation on every wake. A server that rejects the configured credential (HTTP 401/403) was re-attempted forever at that cadence, hammering remote endpoints around the clock. Auth rejections now record an exponential backoff (1min doubling to a 30min cap) in chrome.storage.session, so it survives worker restarts but never outlives the browsing session. While a window is active the connection attempt is skipped and the server status explains when the retry happens. Editing the server URL or auth token retries immediately, a successful connection resets the state, and storage failures fail open. Non-auth failures keep the existing behavior. --- src/lib/mcp/auth-backoff.ts | 124 ++++++++++++++++++ src/lib/mcp/client.ts | 32 ++++- tests/mcp-auth-backoff.test.ts | 229 +++++++++++++++++++++++++++++++++ tests/mcp-instructions.test.ts | 11 +- 4 files changed, 392 insertions(+), 4 deletions(-) create mode 100644 src/lib/mcp/auth-backoff.ts create mode 100644 tests/mcp-auth-backoff.test.ts diff --git a/src/lib/mcp/auth-backoff.ts b/src/lib/mcp/auth-backoff.ts new file mode 100644 index 0000000..b194b50 --- /dev/null +++ b/src/lib/mcp/auth-backoff.ts @@ -0,0 +1,124 @@ +/** + * Persistent backoff for MCP servers that reject our credential. + * + * The MV3 service worker restarts frequently and re-runs remote MCP + * reconciliation on every wake. In-memory state does not survive those + * restarts, so a server that answers 401/403 (expired token, missing + * upstream credential) would otherwise be re-attempted forever at the + * worker restart cadence — hammering the remote endpoint around the clock. + * + * State lives in chrome.storage.session: it survives worker restarts but is + * cleared when the browser closes, so a stale backoff can never outlive the + * browsing session. Entries are keyed by server URL plus a hash of the auth + * token, so editing either retries immediately. Storage problems fail open: + * backoff is an optimization, never a gate that can wedge connectivity. + */ + +import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; +import log from '../logger'; +import type { MCPServerConfig } from '../storage/config'; + +export const AUTH_BACKOFF_BASE_MS = 60_000; +export const AUTH_BACKOFF_MAX_MS = 30 * 60_000; + +/** Entries idle this long are dropped on the next write. */ +const PRUNE_AFTER_MS = 24 * 60 * 60_000; + +const STORAGE_KEY = 'mcpAuthBackoff'; + +export interface AuthBackoffEntry { + failures: number; + nextAttemptAt: number; +} + +type AuthBackoffTable = Record; + +/** HTTP 401/403 from the transport; anything else keeps normal retry behavior. */ +export function isAuthError(error: unknown): boolean { + return error instanceof StreamableHTTPError && (error.code === 401 || error.code === 403); +} + +export function authBackoffDelayMs(failures: number): number { + const doublings = Math.min(Math.max(failures, 1) - 1, 30); + return Math.min(AUTH_BACKOFF_BASE_MS * 2 ** doublings, AUTH_BACKOFF_MAX_MS); +} + +/** + * The token participates only as a hash: backoff keys are written to + * extension storage and must not persist the credential itself. + */ +function fnv1a(input: string): string { + let hash = 0x811c9dc5; + for (let i = 0; i < input.length; i++) { + hash ^= input.charCodeAt(i); + hash = Math.imul(hash, 0x01000193); + } + return (hash >>> 0).toString(16); +} + +function backoffKey(config: MCPServerConfig): string { + return `${config.url}#${fnv1a(config.authToken ?? '')}`; +} + +function storageArea(): chrome.storage.StorageArea | null { + if (typeof chrome === 'undefined' || !chrome.storage) return null; + return chrome.storage.session ?? null; +} + +async function readTable(): Promise { + const area = storageArea(); + if (!area) return {}; + try { + const stored = await area.get(STORAGE_KEY); + const table = stored[STORAGE_KEY]; + return table && typeof table === 'object' ? (table as AuthBackoffTable) : {}; + } catch { + log.warn('[MCPAuthBackoff] Failed to read backoff state'); + return {}; + } +} + +async function writeTable(table: AuthBackoffTable, now: number): Promise { + const area = storageArea(); + if (!area) return; + const pruned: AuthBackoffTable = {}; + for (const [key, entry] of Object.entries(table)) { + if (entry.nextAttemptAt > now - PRUNE_AFTER_MS) pruned[key] = entry; + } + try { + await area.set({ [STORAGE_KEY]: pruned }); + } catch { + log.warn('[MCPAuthBackoff] Failed to persist backoff state'); + } +} + +/** Returns the entry only while its retry window is still in the future. */ +export async function getActiveAuthBackoff( + config: MCPServerConfig +): Promise { + const entry = (await readTable())[backoffKey(config)]; + if (!entry || entry.nextAttemptAt <= Date.now()) return null; + return entry; +} + +export async function recordAuthFailure(config: MCPServerConfig): Promise { + const now = Date.now(); + const table = await readTable(); + const key = backoffKey(config); + const failures = (table[key]?.failures ?? 0) + 1; + const entry: AuthBackoffEntry = { + failures, + nextAttemptAt: now + authBackoffDelayMs(failures), + }; + table[key] = entry; + await writeTable(table, now); + return entry; +} + +export async function clearAuthBackoff(config: MCPServerConfig): Promise { + const table = await readTable(); + const key = backoffKey(config); + if (!(key in table)) return; + delete table[key]; + await writeTable(table, Date.now()); +} diff --git a/src/lib/mcp/client.ts b/src/lib/mcp/client.ts index 207d1e7..f876a77 100644 --- a/src/lib/mcp/client.ts +++ b/src/lib/mcp/client.ts @@ -9,6 +9,12 @@ import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validatio import type { Tool, CallToolResult, Resource } from '@modelcontextprotocol/sdk/types.js'; import log from '../logger'; import type { MCPServerConfig } from '../storage/config'; +import { + isAuthError, + getActiveAuthBackoff, + recordAuthFailure, + clearAuthBackoff, +} from './auth-backoff'; export interface MCPClientStatus { connected: boolean; @@ -35,6 +41,18 @@ export class MCPClientService { try { this.serverConfig = serverConfig; + // Auth rejections persist across service-worker restarts; skip the + // network attempt entirely while a backoff window is active. + const backoff = await getActiveAuthBackoff(serverConfig); + if (backoff) { + const retryInSeconds = Math.ceil((backoff.nextAttemptAt - Date.now()) / 1000); + return { + connected: false, + serverName: serverName || 'unknown', + error: `Authentication failed (HTTP 401/403). Retrying in ~${retryInSeconds}s; update the server URL or auth token to retry immediately.`, + }; + } + // Create StreamableHTTP transport with optional auth header const requestInit: RequestInit = {}; if (serverConfig.authToken) { @@ -69,16 +87,28 @@ export class MCPClientService { // Extract server instructions (guidance for LLMs on how to use tools) const instructions = this.client.getInstructions(); + await clearAuthBackoff(serverConfig); + return { connected: true, serverName: serverName || 'unknown', tools: toolsList, ...(instructions && { instructions }), }; - } catch { + } catch (error) { log.error('MCP server connection failed'); await this.disconnect(); + if (isAuthError(error)) { + await recordAuthFailure(serverConfig); + return { + connected: false, + serverName: serverName || 'unknown', + error: + 'Authentication failed (HTTP 401/403). Automatic retries are paused; check the server auth token.', + }; + } + return { connected: false, serverName: serverName || 'unknown', diff --git a/tests/mcp-auth-backoff.test.ts b/tests/mcp-auth-backoff.test.ts new file mode 100644 index 0000000..f68e051 --- /dev/null +++ b/tests/mcp-auth-backoff.test.ts @@ -0,0 +1,229 @@ +/** + * Auth-failure backoff for remote MCP connections. + * + * The MV3 service worker restarts constantly and re-runs remote MCP + * reconciliation on every wake. Without persistent memory, a server that + * rejects our credential (HTTP 401/403) is retried forever at the worker + * restart cadence. These tests pin the contract: auth failures back off + * exponentially across worker restarts, credential edits retry immediately, + * and non-auth failures keep the existing retry behavior. + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; +import { + isAuthError, + authBackoffDelayMs, + getActiveAuthBackoff, + recordAuthFailure, + clearAuthBackoff, + AUTH_BACKOFF_BASE_MS, + AUTH_BACKOFF_MAX_MS, +} from '../src/lib/mcp/auth-backoff'; +import { MCPClientService } from '../src/lib/mcp/client'; +import type { MCPServerConfig } from '../src/lib/storage/config'; + +const mockClientConnect = vi.fn(); +const mockListTools = vi.fn(); +const mockGetInstructions = vi.fn(); +const mockClose = vi.fn(); + +vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({ + Client: class { + connect = mockClientConnect; + listTools = mockListTools; + getInstructions = mockGetInstructions; + close = mockClose; + }, +})); + +vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', async (importOriginal) => { + const actual = + await importOriginal(); + return { + ...actual, + StreamableHTTPClientTransport: class { + constructor( + public url: URL, + public opts: unknown + ) {} + }, + }; +}); + +vi.mock('@modelcontextprotocol/sdk/validation/cfworker', () => ({ + CfWorkerJsonSchemaValidator: class {}, +})); + +function installSessionStorage(): void { + let store: Record = {}; + (chrome.storage as unknown as Record).session = { + get: vi.fn(async (keys?: string | string[]) => { + if (keys === undefined) return { ...store }; + const wanted = Array.isArray(keys) ? keys : [keys]; + const result: Record = {}; + for (const key of wanted) { + if (key in store) result[key] = structuredClone(store[key]); + } + return result; + }), + set: vi.fn(async (items: Record) => { + store = { ...store, ...structuredClone(items) }; + }), + remove: vi.fn(async (keys: string | string[]) => { + for (const key of Array.isArray(keys) ? keys : [keys]) { + delete store[key]; + } + }), + }; +} + +function serverConfig(overrides: Partial = {}): MCPServerConfig { + return { + transport: 'http', + url: 'https://mcp.example.test/mcp', + authToken: 'token-a', + ...overrides, + }; +} + +beforeEach(() => { + vi.clearAllMocks(); + vi.useFakeTimers(); + vi.setSystemTime(new Date('2026-01-01T00:00:00Z')); + installSessionStorage(); +}); + +afterEach(() => { + vi.useRealTimers(); +}); + +describe('isAuthError', () => { + it('recognizes HTTP 401 and 403 transport errors', () => { + expect(isAuthError(new StreamableHTTPError(401, 'Unauthorized'))).toBe(true); + expect(isAuthError(new StreamableHTTPError(403, 'Forbidden'))).toBe(true); + }); + + it('ignores other transport errors and generic failures', () => { + expect(isAuthError(new StreamableHTTPError(500, 'boom'))).toBe(false); + expect(isAuthError(new StreamableHTTPError(-1, 'bad content type'))).toBe(false); + expect(isAuthError(new Error('network down'))).toBe(false); + expect(isAuthError(undefined)).toBe(false); + }); +}); + +describe('authBackoffDelayMs', () => { + it('doubles per consecutive failure and caps at the maximum', () => { + expect(authBackoffDelayMs(1)).toBe(AUTH_BACKOFF_BASE_MS); + expect(authBackoffDelayMs(2)).toBe(AUTH_BACKOFF_BASE_MS * 2); + expect(authBackoffDelayMs(3)).toBe(AUTH_BACKOFF_BASE_MS * 4); + expect(authBackoffDelayMs(100)).toBe(AUTH_BACKOFF_MAX_MS); + }); +}); + +describe('backoff store', () => { + it('activates after a recorded failure and expires with time', async () => { + const config = serverConfig(); + expect(await getActiveAuthBackoff(config)).toBeNull(); + + await recordAuthFailure(config); + const entry = await getActiveAuthBackoff(config); + expect(entry).not.toBeNull(); + expect(entry!.failures).toBe(1); + expect(entry!.nextAttemptAt).toBe(Date.now() + AUTH_BACKOFF_BASE_MS); + + vi.advanceTimersByTime(AUTH_BACKOFF_BASE_MS + 1); + expect(await getActiveAuthBackoff(config)).toBeNull(); + }); + + it('escalates consecutive failures and resets on clear', async () => { + const config = serverConfig(); + await recordAuthFailure(config); + await recordAuthFailure(config); + const entry = await getActiveAuthBackoff(config); + expect(entry!.failures).toBe(2); + expect(entry!.nextAttemptAt).toBe(Date.now() + AUTH_BACKOFF_BASE_MS * 2); + + await clearAuthBackoff(config); + expect(await getActiveAuthBackoff(config)).toBeNull(); + await recordAuthFailure(config); + expect((await getActiveAuthBackoff(config))!.failures).toBe(1); + }); + + it('keys backoff by credential so URL or token edits retry immediately', async () => { + await recordAuthFailure(serverConfig()); + expect(await getActiveAuthBackoff(serverConfig({ authToken: 'token-b' }))).toBeNull(); + expect( + await getActiveAuthBackoff(serverConfig({ url: 'https://other.example.test/mcp' })) + ).toBeNull(); + }); + + it('fails open when session storage is unavailable', async () => { + delete (chrome.storage as unknown as Record).session; + const config = serverConfig(); + await expect(recordAuthFailure(config)).resolves.toBeDefined(); + expect(await getActiveAuthBackoff(config)).toBeNull(); + }); +}); + +describe('MCPClientService auth backoff integration', () => { + it('records a backoff on 401 and skips the next connection attempt', async () => { + mockClientConnect.mockRejectedValue(new StreamableHTTPError(401, 'Unauthorized')); + + const first = await new MCPClientService().connect(serverConfig(), 'remote'); + expect(first.connected).toBe(false); + expect(first.error).toMatch(/authentication/i); + expect(mockClientConnect).toHaveBeenCalledTimes(1); + + const second = await new MCPClientService().connect(serverConfig(), 'remote'); + expect(second.connected).toBe(false); + expect(second.error).toMatch(/authentication/i); + // Still in the backoff window: no new network attempt. + expect(mockClientConnect).toHaveBeenCalledTimes(1); + }); + + it('retries after the backoff window elapses', async () => { + mockClientConnect.mockRejectedValue(new StreamableHTTPError(401, 'Unauthorized')); + await new MCPClientService().connect(serverConfig(), 'remote'); + + vi.advanceTimersByTime(AUTH_BACKOFF_BASE_MS + 1); + await new MCPClientService().connect(serverConfig(), 'remote'); + expect(mockClientConnect).toHaveBeenCalledTimes(2); + + // Second consecutive failure doubles the window. + const entry = await getActiveAuthBackoff(serverConfig()); + expect(entry!.failures).toBe(2); + expect(entry!.nextAttemptAt).toBe(Date.now() + AUTH_BACKOFF_BASE_MS * 2); + }); + + it('does not back off on non-auth failures', async () => { + mockClientConnect.mockRejectedValue(new Error('network down')); + + await new MCPClientService().connect(serverConfig(), 'remote'); + await new MCPClientService().connect(serverConfig(), 'remote'); + expect(mockClientConnect).toHaveBeenCalledTimes(2); + expect(await getActiveAuthBackoff(serverConfig())).toBeNull(); + }); + + it('clears the backoff after a successful connection', async () => { + mockClientConnect.mockRejectedValueOnce(new StreamableHTTPError(401, 'Unauthorized')); + mockClientConnect.mockResolvedValue(undefined); + mockListTools.mockResolvedValue({ tools: [] }); + mockGetInstructions.mockReturnValue(undefined); + + await new MCPClientService().connect(serverConfig(), 'remote'); + vi.advanceTimersByTime(AUTH_BACKOFF_BASE_MS + 1); + + const result = await new MCPClientService().connect(serverConfig(), 'remote'); + expect(result.connected).toBe(true); + expect(await getActiveAuthBackoff(serverConfig())).toBeNull(); + }); + + it('retries immediately when the auth token changes', async () => { + mockClientConnect.mockRejectedValue(new StreamableHTTPError(401, 'Unauthorized')); + await new MCPClientService().connect(serverConfig(), 'remote'); + + await new MCPClientService().connect(serverConfig({ authToken: 'token-b' }), 'remote'); + expect(mockClientConnect).toHaveBeenCalledTimes(2); + }); +}); diff --git a/tests/mcp-instructions.test.ts b/tests/mcp-instructions.test.ts index 68971ea..a2d8aff 100644 --- a/tests/mcp-instructions.test.ts +++ b/tests/mcp-instructions.test.ts @@ -22,9 +22,14 @@ vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({ })), })); -vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({ - StreamableHTTPClientTransport: vi.fn(), -})); +vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', async (importOriginal) => { + const actual = + await importOriginal(); + return { + ...actual, + StreamableHTTPClientTransport: vi.fn(), + }; +}); // --- Import after mocks --- import { Client } from '@modelcontextprotocol/sdk/client/index.js';