Skip to content

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

TypeScript

fix(web-search): validate fetch destinations and bound response resources

Alfredo Lopez607b9d539e9b
diff --git a/.github/workflows/ci-public.yml b/.github/workflows/ci-public.yml
index 293ca3c97..e11973d89 100644
--- a/.github/workflows/ci-public.yml
+++ b/.github/workflows/ci-public.yml
@@ -63,6 +63,7 @@ jobs:
- profile-ui
- desktop-app
- mcp-servers
+ - mcp-servers/web-search
- packages/desktop-app-links
- packages/workflow-runtime-core
- packages/workflow-sdk
diff --git a/Makefile b/Makefile
index 4eea8240c..33f905c1e 100644
--- a/Makefile
+++ b/Makefile
@@ -68,6 +68,7 @@ TEST_SERVICES := \
profile-ui \
desktop-app \
mcp-servers \
+ mcp-servers/web-search \
packages/desktop-app-links \
packages/workflow-runtime-core \
packages/workflow-sdk \
@@ -1417,3 +1418,7 @@ run-platform-security-gates: ## Execute the revised platform security gate runne
help: ## Show this help
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-24s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: test-web-search-image
+test-web-search-image: ## Build and test the fetch_page image locally under its branch lease
+ @bash scripts/minikube/with-t2-mutation-lock.sh -- bash scripts/tests/test-web-search-image.sh
diff --git a/mcp-servers/web-search/README.md b/mcp-servers/web-search/README.md
index 4950eecc1..7943a487d 100644
--- a/mcp-servers/web-search/README.md
+++ b/mcp-servers/web-search/README.md
@@ -40,4 +40,30 @@ This directory has no `mcpserver.yaml` or NetworkPolicy — unlike `airtable/` a
## Status
-Available; buildable and published to the container registry. No test suite yet (unlike `airtable/` and `mongodb/`). Referenced in `docs/deploy/minikube.md` (NetworkPolicy troubleshooting for a coordinator connecting to a `web-search` MCP server) and type-checked by `scripts/build-preflight.sh`. Minikube setup does not build or pull the image; the registry installs it on demand.
+Available; buildable and published to the container registry. Unit and isolated HTTP/MCP suites are available; see Regression tests below. Referenced in `docs/deploy/minikube.md` (NetworkPolicy troubleshooting for a coordinator connecting to a `web-search` MCP server) and type-checked by `scripts/build-preflight.sh`. Minikube setup does not build or pull the image; the registry installs it on demand.
+
+## fetch_page security contract
+
+`fetch_page` accepts HTTP(S) URLs without userinfo. It rejects non-public and
+special-purpose IPv4/IPv6 destinations, validates both DNS record families, pins
+the connection to the validated address, and validates every redirect. HTTPS
+redirects to HTTP are rejected. No ambient proxy is used. NetworkPolicy remains
+a complementary deployment control.
+
+The operation has a 15-second absolute deadline, five redirects maximum, a 1 MiB
+body limit before and after decompression, and four active calls per process.
+Additional calls fail immediately. `maxChars` remains the output display limit;
+it is not the download limit. Redirect and error bodies are destroyed without
+reading them. Encodings supported: identity, gzip, deflate and br.
+
+Errors expose a stable code without upstream details. Private destinations and
+oversized documents previously accepted are intentionally rejected.
+
+### Regression tests
+
+Use Node 24. `npm test` builds and executes the unit suite. `npm run test:network`
+uses the real MCP server and an isolated HTTP fixture inside Docker, with no
+external network or published ports. It requires a locally available
+`node:24-alpine` image and never pulls implicitly. Run Docker tests on the host,
+outside the native Codex sandbox. Only compiled code, dependencies and test files
+are mounted read-only. These protocol tests do not replace the Desktop journey.
diff --git a/mcp-servers/web-search/package-lock.json b/mcp-servers/web-search/package-lock.json
index ccebcf1c6..53ea972d7 100644
--- a/mcp-servers/web-search/package-lock.json
+++ b/mcp-servers/web-search/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@clerum/web-search-mcp",
- "version": "1.0.7",
+ "version": "1.0.8",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/web-search-mcp",
- "version": "1.0.7",
+ "version": "1.0.8",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
"express": "^4.21.2"
diff --git a/mcp-servers/web-search/package.json b/mcp-servers/web-search/package.json
index a2a1f5620..73d9b8c4f 100644
--- a/mcp-servers/web-search/package.json
+++ b/mcp-servers/web-search/package.json
@@ -1,12 +1,14 @@
{
"name": "@clerum/web-search-mcp",
- "version": "1.0.7",
+ "version": "1.0.8",
"type": "module",
"main": "dist/index.js",
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts",
- "start": "node dist/index.js"
+ "start": "node dist/index.js",
+ "test": "npm run build && node --test test/*.test.mjs",
+ "test:network": "npm run build && node test/run-network.mjs"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
diff --git a/mcp-servers/web-search/src/fetchPage.ts b/mcp-servers/web-search/src/fetchPage.ts
new file mode 100644
index 000000000..2610d8852
--- /dev/null
+++ b/mcp-servers/web-search/src/fetchPage.ts
@@ -0,0 +1,197 @@
+import http, { type IncomingMessage } from 'node:http'
+import https from 'node:https'
+import { isIP } from 'node:net'
+import { Transform, Writable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { checkServerIdentity as tlsCheck } from 'node:tls'
+import { createBrotliDecompress, createGunzip, createInflate } from 'node:zlib'
+import { parsePageUrl, resolvePageAddress } from './fetchPageDestination.js'
+import { FetchPageError } from './fetchPageError.js'
+
+export const FETCH_PAGE_LIMITS = Object.freeze({
+ timeoutMs: 15000,
+ maxBytes: 1024 * 1024,
+ maxRedirects: 5,
+ maxConcurrent: 4,
+})
+let active = 0 // Process-wide, including distinct MCP sessions.
+const redirects = new Set([301, 302, 303, 307, 308])
+
+/** Linear tag stripping, including malformed input with many unclosed '<'. */
+export function pageText(html: string): string {
+ const pieces: string[] = []
+ let offset = 0
+ while (offset < html.length) {
+ const start = html.indexOf('<', offset)
+ if (start === -1) {
+ pieces.push(html.slice(offset))
+ break
+ }
+ const end = html.indexOf('>', start + 1)
+ if (end === -1) {
+ pieces.push(html.slice(offset))
+ break
+ }
+ pieces.push(html.slice(offset, start), ' ')
+ offset = end + 1
+ }
+ return pieces.join('').replace(/\s+/g, ' ').trim()
+}
+
+function titleText(html: string): string {
+ const lower = html.toLowerCase()
+ const start = lower.indexOf('<title')
+ if (start === -1 || !/[\s>]/.test(lower[start + 6] ?? '')) return ''
+ const body = lower.indexOf('>', start + 6)
+ const end = lower.indexOf('</title>', body + 1)
+ return body < 0 || end < 0 ? '' : pageText(html.slice(body + 1, end))
+}
+
+function connect(url: URL, address: string, signal: AbortSignal): Promise<IncomingMessage> {
+ return new Promise((resolve, reject) => {
+ const hostname = url.hostname.replace(/^\[|\]$/g, '')
+ const client = url.protocol === 'https:' ? https : http
+ const req = client.request(
+ {
+ protocol: url.protocol,
+ hostname: address,
+ port: url.port || (url.protocol === 'https:' ? 443 : 80),
+ method: 'GET',
+ path: url.pathname + url.search,
+ agent: false,
+ signal,
+ maxHeaderSize: 16 * 1024,
+ headers: {
+ Host: url.host,
+ Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+ 'Accept-Encoding': 'identity',
+ 'User-Agent': 'EvenfireWebSearch/1.0',
+ },
+ ...(url.protocol === 'https:'
+ ? {
+ servername: isIP(hostname) ? undefined : hostname,
+ checkServerIdentity: (_host: string, cert: import('node:tls').PeerCertificate) =>
+ // HTTPS connects to the pinned IP, but authenticates the URL host.
+ tlsCheck(hostname, cert),
+ }
+ : {}),
+ },
+ resolve
+ )
+ req.once('error', reject)
+ req.end()
+ })
+}
+async function readBody(res: IncomingMessage, signal: AbortSignal): Promise<string> {
+ const length = res.headers['content-length']
+ if (
+ length !== undefined &&
+ (!/^\d+$/.test(length) || Number(length) > FETCH_PAGE_LIMITS.maxBytes)
+ ) {
+ throw new FetchPageError('response_too_large')
+ }
+ const encoding = (res.headers['content-encoding'] ?? 'identity').trim().toLowerCase()
+ const decoder =
+ encoding === 'identity'
+ ? undefined
+ : encoding === 'gzip'
+ ? createGunzip()
+ : encoding === 'deflate'
+ ? createInflate()
+ : encoding === 'br'
+ ? createBrotliDecompress()
+ : null
+ if (decoder === null) throw new FetchPageError('unsupported_encoding')
+ let wireBytes = 0
+ let decodedBytes = 0
+ const chunks: Buffer[] = []
+ const wire = new Transform({
+ transform(chunk: Buffer, _encoding, callback) {
+ wireBytes += chunk.length
+ callback(
+ wireBytes > FETCH_PAGE_LIMITS.maxBytes ? new FetchPageError('response_too_large') : null,
+ chunk
+ )
+ },
+ })
+ const sink = new Writable({
+ write(chunk: Buffer, _encoding, callback) {
+ decodedBytes += chunk.length
+ if (decodedBytes > FETCH_PAGE_LIMITS.maxBytes) {
+ callback(new FetchPageError('response_too_large'))
+ return
+ }
+ chunks.push(chunk)
+ callback()
+ },
+ })
+ if (decoder) await pipeline(res, wire, decoder, sink, { signal })
+ else await pipeline(res, wire, sink, { signal })
+ return Buffer.concat(chunks).toString('utf8')
+}
+
+export async function fetchPage(
+ input: string,
+ maxChars: number,
+ callerSignal?: AbortSignal
+): Promise<{ title: string; content: string }> {
+ if (!Number.isInteger(maxChars) || maxChars < 100 || maxChars > 100000)
+ throw new FetchPageError('invalid_url')
+ if (active >= FETCH_PAGE_LIMITS.maxConcurrent) throw new FetchPageError('busy')
+ active++
+ const controller = new AbortController()
+ const timeout = setTimeout(
+ () => controller.abort(new FetchPageError('deadline_exceeded')),
+ FETCH_PAGE_LIMITS.timeoutMs
+ )
+ const cancel = () => controller.abort(new FetchPageError('cancelled'))
+ if (callerSignal?.aborted) cancel()
+ else callerSignal?.addEventListener('abort', cancel, { once: true })
+ const seen = new Set<string>()
+ try {
+ let url = parsePageUrl(input)
+ for (let hop = 0; ; hop++) {
+ controller.signal.throwIfAborted()
+ if (seen.has(url.href)) throw new FetchPageError('redirect_limit')
+ seen.add(url.href)
+ const address = await resolvePageAddress(url, controller.signal)
+ const res = await connect(url, address, controller.signal)
+ try {
+ if (redirects.has(res.statusCode ?? 0)) {
+ if (hop >= FETCH_PAGE_LIMITS.maxRedirects) throw new FetchPageError('redirect_limit')
+ const location = res.headers.location
+ if (!location) throw new FetchPageError('upstream_failure')
+ let next: URL
+ try {
+ next = parsePageUrl(new URL(location, url).href)
+ } catch {
+ throw new FetchPageError('invalid_url')
+ }
+ if (url.protocol === 'https:' && next.protocol !== 'https:')
+ throw new FetchPageError('destination_blocked')
+ url = next
+ // Do not consume untrusted redirect bodies at all. No bytes from
+ // intermediate responses enter our accumulated body buffers.
+ continue
+ }
+ if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300)
+ throw new FetchPageError('upstream_failure')
+ const html = await readBody(res, controller.signal)
+ controller.signal.throwIfAborted()
+ return {
+ title: titleText(html).slice(0, maxChars),
+ content: pageText(html).slice(0, maxChars),
+ }
+ } finally {
+ res.destroy()
+ }
+ }
+ } catch (error) {
+ if (controller.signal.aborted) throw controller.signal.reason
+ throw error instanceof FetchPageError ? error : new FetchPageError('upstream_failure')
+ } finally {
+ clearTimeout(timeout)
+ callerSignal?.removeEventListener('abort', cancel)
+ active--
+ }
+}
diff --git a/mcp-servers/web-search/src/fetchPageDestination.ts b/mcp-servers/web-search/src/fetchPageDestination.ts
new file mode 100644
index 000000000..bd3e87f0f
--- /dev/null
+++ b/mcp-servers/web-search/src/fetchPageDestination.ts
@@ -0,0 +1,119 @@
+import { Resolver } from 'node:dns/promises'
+import { BlockList, isIP } from 'node:net'
+import { FetchPageError } from './fetchPageError.js'
+
+// Conservative public-web policy. Deliberately also excludes globally reachable
+// special-purpose services: they are not ordinary web destinations. Sources,
+// reviewed 2026-09-10 (both registries last updated 2025-10-09):
+// https://www.iana.org/assignments/iana-ipv4-special-registry/
+// https://www.iana.org/assignments/iana-ipv6-special-registry/
+const blocked = new BlockList()
+for (const [address, prefix] of [
+ ['0.0.0.0', 8],
+ ['10.0.0.0', 8],
+ ['100.64.0.0', 10],
+ ['127.0.0.0', 8],
+ ['169.254.0.0', 16],
+ ['172.16.0.0', 12],
+ ['192.0.0.0', 24],
+ ['192.0.2.0', 24],
+ ['192.31.196.0', 24],
+ ['192.52.193.0', 24],
+ ['192.88.99.0', 24],
+ ['192.168.0.0', 16],
+ ['192.175.48.0', 24],
+ ['198.18.0.0', 15],
+ ['198.51.100.0', 24],
+ ['203.0.113.0', 24],
+ ['224.0.0.0', 4],
+ ['240.0.0.0', 4],
+] as const)
+ blocked.addSubnet(address, prefix, 'ipv4')
+for (const [address, prefix] of [
+ ['2001::', 23],
+ ['2001:db8::', 32],
+ ['2002::', 16],
+ ['2620:4f:8000::', 48],
+ ['3fff::', 20],
+] as const)
+ blocked.addSubnet(address, prefix, 'ipv6')
+const globalV6 = new BlockList()
+globalV6.addSubnet('2000::', 3, 'ipv6')
+
+export function isPublicAddress(address: string): boolean {
+ const family = isIP(address)
+ if (family === 4) return !blocked.check(address, 'ipv4')
+ if (family !== 6 || address.includes('%')) return false
+ // ISATAP can encode an inner IPv4 destination in a global IPv6 prefix.
+ const canonical = new URL(`http://[${address}]/`).hostname.slice(1, -1)
+ const halves = canonical.split('::')
+ const left = halves[0] ? halves[0].split(':') : []
+ const right = halves.length > 1 && halves[1] ? halves[1].split(':') : []
+ const groups =
+ halves.length === 1
+ ? left
+ : [...left, ...Array(8 - left.length - right.length).fill('0'), ...right]
+ if ([0, 0x200].includes(parseInt(groups[4], 16)) && parseInt(groups[5], 16) === 0x5efe)
+ return false
+ // Only ordinary global unicast. This excludes mapped/compatible IPv4,
+ // NAT64, link/site-local, ULA, multicast and unallocated top-level spaces.
+ return globalV6.check(address, 'ipv6') && !blocked.check(address, 'ipv6')
+}
+
+export function parsePageUrl(input: string): URL {
+ if (Buffer.byteLength(input, 'utf8') > 8192 || /[\u0000-\u0020\u007f\\]/.test(input)) {
+ throw new FetchPageError('invalid_url')
+ }
+ let url: URL
+ try {
+ url = new URL(input)
+ } catch {
+ throw new FetchPageError('invalid_url')
+ }
+ if (
+ !['http:', 'https:'].includes(url.protocol) ||
+ !url.hostname ||
+ url.username ||
+ url.password ||
+ url.port === '0'
+ ) {
+ throw new FetchPageError('invalid_url')
+ }
+ url.hash = ''
+ return url
+}
+
+export async function resolvePageAddress(url: URL, signal: AbortSignal): Promise<string> {
+ signal.throwIfAborted()
+ const hostname = url.hostname.replace(/^\[|\]$/g, '')
+ if (isIP(hostname)) {
+ if (!isPublicAddress(hostname)) throw new FetchPageError('destination_blocked')
+ return hostname
+ }
+ const resolver = new Resolver({ timeout: 15000, tries: 1 })
+ const cancel = () => resolver.cancel()
+ signal.addEventListener('abort', cancel, { once: true })
+ try {
+ const records = await Promise.allSettled([
+ resolver.resolve4(hostname),
+ resolver.resolve6(hostname),
+ ])
+ signal.throwIfAborted()
+ const addresses: string[] = []
+ for (const result of records) {
+ if (result.status === 'fulfilled') addresses.push(...result.value)
+ // ENODATA is conclusive absence for this record type. NXDOMAIN paired
+ // with an answer is inconsistent, and SERVFAIL/timeouts are not absence.
+ else if ((result.reason as NodeJS.ErrnoException)?.code !== 'ENODATA') {
+ throw new FetchPageError('upstream_failure')
+ }
+ }
+ if (!addresses.length) throw new FetchPageError('upstream_failure')
+ if (addresses.some(address => !isPublicAddress(address)))
+ throw new FetchPageError('destination_blocked')
+ return addresses[0]
+ } finally {
+ signal.removeEventListener('abort', cancel)
+ resolver.cancel()
+ }
+}
diff --git a/mcp-servers/web-search/src/fetchPageError.ts b/mcp-servers/web-search/src/fetchPageError.ts
new file mode 100644
index 000000000..d5b9a713d
--- /dev/null
+++ b/mcp-servers/web-search/src/fetchPageError.ts
@@ -0,0 +1,18 @@
+export type FetchPageErrorCode =
+ | 'invalid_url'
+ | 'destination_blocked'
+ | 'redirect_limit'
+ | 'deadline_exceeded'
+ | 'response_too_large'
+ | 'unsupported_encoding'
+ | 'upstream_failure'
+ | 'busy'
+ | 'cancelled'
+
+/** Public errors contain no upstream URL, address, response body or native error. */
+export class FetchPageError extends Error {
+ constructor(readonly code: FetchPageErrorCode) {
+ super(code)
+ this.name = 'FetchPageError'
+ }
+}
diff --git a/mcp-servers/web-search/src/index.ts b/mcp-servers/web-search/src/index.ts
index dd89c8185..af15475d9 100644
--- a/mcp-servers/web-search/src/index.ts
+++ b/mcp-servers/web-search/src/index.ts
@@ -11,114 +11,101 @@
* - SEARCH_API_KEY: Brave Search API subscription token
* - PORT: HTTP port (default 3000)
*/
+import express, { Request, Response } from 'express'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { randomUUID } from 'crypto'
+import { z } from 'zod'
+import { fetchPage } from './fetchPage.js'
+import { FetchPageError } from './fetchPageError.js'
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import express, { Request, Response } from "express";
-import { randomUUID } from "crypto";
-import { z } from "zod";
+const PORT = parseInt(process.env.PORT || '3000', 10)
+const SEARCH_API_KEY = process.env.SEARCH_API_KEY || ''
-const PORT = parseInt(process.env.PORT || "3000", 10);
-const SEARCH_API_KEY = process.env.SEARCH_API_KEY || "";
-
-const BRAVE_SEARCH_BASE = "https://api.search.brave.com/res/v1";
+const BRAVE_SEARCH_BASE = 'https://api.search.brave.com/res/v1'
// ---------------------------------------------------------------------------
// Brave Search API helpers
// ---------------------------------------------------------------------------
interface WebResult {
- title: string;
- url: string;
- snippet: string;
+ title: string
+ url: string
+ snippet: string
}
interface NewsResult {
- title: string;
- url: string;
- date: string;
- snippet: string;
+ title: string
+ url: string
+ date: string
+ snippet: string
}
-async function braveWebSearch(
- query: string,
- maxResults: number,
-): Promise<WebResult[]> {
+async function braveWebSearch(query: string, maxResults: number): Promise<WebResult[]> {
const params = new URLSearchParams({
q: query,
count: String(maxResults),
- });
+ })
const res = await fetch(`${BRAVE_SEARCH_BASE}/web/search?${params}`, {
headers: {
- Accept: "application/json",
- "X-Subscription-Token": SEARCH_API_KEY,
+ Accept: 'application/json',
+ 'X-Subscription-Token': SEARCH_API_KEY,
},
- });
+ })
if (!res.ok) {
- throw new Error(`Brave Search API error: ${res.status} ${res.statusText}`);
+ throw new Error(`Brave Search API error: ${res.status} ${res.statusText}`)
}
const data = (await res.json()) as {
- web?: { results?: Array<{ title: string; url: string; description: string }> };
- };
+ web?: { results?: Array<{ title: string; url: string; description: string }> }
+ }
- return (data.web?.results ?? []).slice(0, maxResults).map((r) => ({
+ return (data.web?.results ?? []).slice(0, maxResults).map(r => ({
title: r.title,
url: r.url,
snippet: r.description,
- }));
+ }))
}
async function braveNewsSearch(
query: string,
- freshness: "day" | "week" | "month",
- maxResults: number,
+ freshness: 'day' | 'week' | 'month',
+ maxResults: number
): Promise<NewsResult[]> {
const params = new URLSearchParams({
q: query,
count: String(maxResults),
freshness,
- });
+ })
const res = await fetch(`${BRAVE_SEARCH_BASE}/news/search?${params}`, {
headers: {
- Accept: "application/json",
- "X-Subscription-Token": SEARCH_API_KEY,
+ Accept: 'application/json',
+ 'X-Subscription-Token': SEARCH_API_KEY,
},
- });
+ })
if (!res.ok) {
- throw new Error(`Brave News API error: ${res.status} ${res.statusText}`);
+ throw new Error(`Brave News API error: ${res.status} ${res.statusText}`)
}
const data = (await res.json()) as {
results?: Array<{
- title: string;
- url: string;
- age: string;
- description: string;
- }>;
- };
-
- return (data.results ?? []).slice(0, maxResults).map((r) => ({
+ title: string
+ url: string
+ age: string
+ description: string
+ }>
+ }
+
+ return (data.results ?? []).slice(0, maxResults).map(r => ({
title: r.title,
url: r.url,
date: r.age,
snippet: r.description,
- }));
-}
-
-// ---------------------------------------------------------------------------
-// HTML stripping helper
-// ---------------------------------------------------------------------------
-
-function stripHtml(html: string): string {
- return html
- .replace(/<[^>]*>/g, " ")
- .replace(/\s+/g, " ")
- .trim();
+ }))
}
// ---------------------------------------------------------------------------
@@ -127,17 +114,17 @@ function stripHtml(html: string): string {
function createMcpServer(): McpServer {
const server = new McpServer({
- name: "web-search",
- version: "1.0.0",
- });
+ name: 'web-search',
+ version: '1.0.0',
+ })
// -- Tool 1: web_search --------------------------------------------------
server.tool(
- "web_search",
- "Search the web using the Brave Search API. Returns titles, URLs, and snippets.",
+ 'web_search',
+ 'Search the web using the Brave Search API. Returns titles, URLs, and snippets.',
{
- query: z.string().describe("The search query"),
+ query: z.string().describe('The search query'),
maxResults: z
.number()
.int()
@@ -145,57 +132,57 @@ function createMcpServer(): McpServer {
.max(20)
.optional()
.default(5)
- .describe("Maximum number of results to return (default 5)"),
+ .describe('Maximum number of results to return (default 5)'),
},
async ({ query, maxResults }: { query: string; maxResults: number }) => {
if (!SEARCH_API_KEY) {
return {
content: [
{
- type: "text" as const,
+ type: 'text' as const,
text: JSON.stringify(
[
{
- title: "SEARCH_API_KEY not configured",
- url: "https://brave.com/search/api/",
+ title: 'SEARCH_API_KEY not configured',
+ url: 'https://brave.com/search/api/',
snippet:
- "Set the SEARCH_API_KEY environment variable with a valid Brave Search API subscription token to enable real web search.",
+ 'Set the SEARCH_API_KEY environment variable with a valid Brave Search API subscription token to enable real web search.',
},
],
null,
- 2,
+ 2
),
},
],
- };
+ }
}
try {
- const results = await braveWebSearch(query, maxResults);
+ const results = await braveWebSearch(query, maxResults)
return {
- content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
- };
+ content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }],
+ }
} catch (err) {
return {
content: [
{
- type: "text" as const,
+ type: 'text' as const,
text: `Error performing web search: ${err instanceof Error ? err.message : String(err)}`,
},
],
isError: true,
- };
+ }
}
- },
- );
+ }
+ )
// -- Tool 2: fetch_page --------------------------------------------------
server.tool(
- "fetch_page",
- "Fetch a web page and return its text content with HTML tags stripped.",
+ 'fetch_page',
+ 'Fetch a web page and return its text content with HTML tags stripped.',
{
- url: z.string().url().describe("The URL to fetch"),
+ url: z.string().url().describe('The URL to fetch'),
maxChars: z
.number()
.int()
@@ -203,221 +190,162 @@ function createMcpServer(): McpServer {
.max(100000)
.optional()
.default(10000)
- .describe("Maximum characters to return (default 10000)"),
+ .describe('Maximum characters to return (default 10000)'),
},
- async ({ url, maxChars }: { url: string; maxChars: number }) => {
+ async ({ url, maxChars }: { url: string; maxChars: number }, extra) => {
try {
- const controller = new AbortController();
- const timeout = setTimeout(() => controller.abort(), 15000);
-
- const res = await fetch(url, {
- headers: {
- "User-Agent":
- "Mozilla/5.0 (compatible; ClerumWebSearch/1.0; +https://clerum.io)",
- Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
- },
- signal: controller.signal,
- redirect: "follow",
- });
-
- clearTimeout(timeout);
-
- if (!res.ok) {
- return {
- content: [
- {
- type: "text" as const,
- text: `Error fetching page: HTTP ${res.status} ${res.statusText}`,
- },
- ],
- isError: true,
- };
- }
-
- const html = await res.text();
-
- // Extract title from <title> tag
- const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
- const title = titleMatch ? stripHtml(titleMatch[1]) : "";
-
- // Strip HTML and truncate
- const content = stripHtml(html).slice(0, maxChars);
-
- return {
- content: [
- {
- type: "text" as const,
- text: JSON.stringify({ title, content }, null, 2),
- },
- ],
- };
- } catch (err) {
- const message =
- err instanceof Error && err.name === "AbortError"
- ? "Request timed out after 15 seconds"
- : err instanceof Error
- ? err.message
- : String(err);
-
- return {
- content: [
- { type: "text" as const, text: `Error fetching page: ${message}` },
- ],
- isError: true,
- };
+ const result = await fetchPage(url, maxChars, extra.signal)
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+ } catch (error) {
+ const code = error instanceof FetchPageError ? error.code : 'upstream_failure'
+ return { content: [{ type: 'text' as const, text: code }], isError: true }
}
- },
- );
+ }
+ )
// -- Tool 3: search_news -------------------------------------------------
server.tool(
- "search_news",
- "Search recent news using the Brave Search API. Returns titles, URLs, dates, and snippets.",
+ 'search_news',
+ 'Search recent news using the Brave Search API. Returns titles, URLs, dates, and snippets.',
{
- query: z.string().describe("The news search query"),
+ query: z.string().describe('The news search query'),
freshness: z
- .enum(["day", "week", "month"])
+ .enum(['day', 'week', 'month'])
.optional()
- .default("week")
+ .default('week')
.describe('How recent the news should be: "day", "week", or "month" (default "week")'),
},
- async ({
- query,
- freshness,
- }: {
- query: string;
- freshness: "day" | "week" | "month";
- }) => {
+ async ({ query, freshness }: { query: string; freshness: 'day' | 'week' | 'month' }) => {
if (!SEARCH_API_KEY) {
return {
content: [
{
- type: "text" as const,
+ type: 'text' as const,
text: JSON.stringify(
[
{
- title: "SEARCH_API_KEY not configured",
- url: "https://brave.com/search/api/",
- date: "N/A",
+ title: 'SEARCH_API_KEY not configured',
+ url: 'https://brave.com/search/api/',
+ date: 'N/A',
snippet:
- "Set the SEARCH_API_KEY environment variable with a valid Brave Search API subscription token to enable real news search.",
+ 'Set the SEARCH_API_KEY environment variable with a valid Brave Search API subscription token to enable real news search.',
},
],
null,
- 2,
+ 2
),
},
],
- };
+ }
}
try {
- const results = await braveNewsSearch(query, freshness, 10);
+ const results = await braveNewsSearch(query, freshness, 10)
return {
- content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
- };
+ content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }],
+ }
} catch (err) {
return {
content: [
{
- type: "text" as const,
+ type: 'text' as const,
text: `Error performing news search: ${err instanceof Error ? err.message : String(err)}`,
},
],
isError: true,
- };
+ }
}
- },
- );
+ }
+ )
- return server;
+ return server
}
// ---------------------------------------------------------------------------
// Express + StreamableHTTP Transport
// ---------------------------------------------------------------------------
-const app = express();
+const app = express()
-const transports = new Map<string, StreamableHTTPServerTransport>();
+const transports = new Map<string, StreamableHTTPServerTransport>()
// Health endpoint
-app.get("/health", (_req: Request, res: Response) => {
+app.get('/health', (_req: Request, res: Response) => {
res.json({
- status: "ok",
- tools: ["web_search", "fetch_page", "search_news"],
+ status: 'ok',
+ tools: ['web_search', 'fetch_page', 'search_news'],
searchApiConfigured: !!SEARCH_API_KEY,
- });
-});
+ })
+})
// MCP StreamableHTTP endpoint
-app.post("/mcp", async (req: Request, res: Response) => {
+app.post('/mcp', async (req: Request, res: Response) => {
try {
- const sessionId = req.headers["mcp-session-id"] as string | undefined;
+ const sessionId = req.headers['mcp-session-id'] as string | undefined
// Existing session
if (sessionId && transports.has(sessionId)) {
- const transport = transports.get(sessionId)!;
- await transport.handleRequest(req, res);
- return;
+ const transport = transports.get(sessionId)!
+ await transport.handleRequest(req, res)
+ return
}
// New session (initialize)
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => randomUUID(),
- });
+ })
- const server = createMcpServer();
- await server.connect(transport);
+ const server = createMcpServer()
+ await server.connect(transport)
- await transport.handleRequest(req, res);
+ await transport.handleRequest(req, res)
- const assignedSessionId = (transport as any).sessionId as string | undefined;
+ const assignedSessionId = (transport as any).sessionId as string | undefined
if (assignedSessionId) {
- transports.set(assignedSessionId, transport);
- console.log(`[WebSearch] New session: ${assignedSessionId}`);
+ transports.set(assignedSessionId, transport)
}
+ const onTransportClose = transport.onclose
transport.onclose = () => {
+ // Preserve SDK cancellation of in-flight handlers when the session closes.
+ onTransportClose?.()
if (assignedSessionId) {
- transports.delete(assignedSessionId);
- console.log(`[WebSearch] Session closed: ${assignedSessionId}`);
+ transports.delete(assignedSessionId)
}
- };
+ }
} catch (err) {
- console.error("[WebSearch] Error handling MCP request:", err);
if (!res.headersSent) {
- res.status(500).json({ error: String(err) });
+ res.status(500).json({ error: 'MCP request failed' })
}
}
-});
+})
// GET /mcp for SSE session resumption
-app.get("/mcp", async (req: Request, res: Response) => {
- const sessionId = req.headers["mcp-session-id"] as string | undefined;
+app.get('/mcp', async (req: Request, res: Response) => {
+ const sessionId = req.headers['mcp-session-id'] as string | undefined
if (sessionId && transports.has(sessionId)) {
- const transport = transports.get(sessionId)!;
- await transport.handleRequest(req, res);
- return;
+ const transport = transports.get(sessionId)!
+ await transport.handleRequest(req, res)
+ return
}
- res.status(400).json({ error: "Bad request — send POST to initialize" });
-});
+ res.status(400).json({ error: 'Bad request — send POST to initialize' })
+})
// DELETE /mcp to close a session
-app.delete("/mcp", async (req: Request, res: Response) => {
- const sessionId = req.headers["mcp-session-id"] as string | undefined;
+app.delete('/mcp', async (req: Request, res: Response) => {
+ const sessionId = req.headers['mcp-session-id'] as string | undefined
if (sessionId && transports.has(sessionId)) {
- const transport = transports.get(sessionId)!;
- await transport.handleRequest(req, res);
- return;
+ const transport = transports.get(sessionId)!
+ await transport.handleRequest(req, res)
+ return
}
- res.status(400).json({ error: "No active session to close" });
-});
+ res.status(400).json({ error: 'No active session to close' })
+})
-app.listen(PORT, "0.0.0.0", () => {
- console.log(`[WebSearch] StreamableHTTP MCP server listening on port ${PORT}`);
+app.listen(PORT, '0.0.0.0', () => {
+ console.log(`[WebSearch] StreamableHTTP MCP server listening on port ${PORT}`)
console.log(
- `[WebSearch] Brave Search API: ${SEARCH_API_KEY ? "configured" : "NOT configured (mock responses enabled)"}`,
- );
-});
+ `[WebSearch] Brave Search API: ${SEARCH_API_KEY ? 'configured' : 'NOT configured (mock responses enabled)'}`
+ )
+})
diff --git a/mcp-servers/web-search/test/destination.test.mjs b/mcp-servers/web-search/test/destination.test.mjs
new file mode 100644
index 000000000..ea5ee652e
--- /dev/null
+++ b/mcp-servers/web-search/test/destination.test.mjs
@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict'
+import { Resolver } from 'node:dns/promises'
+import { mock, test } from 'node:test'
+import { isPublicAddress, parsePageUrl, resolvePageAddress } from '../dist/fetchPageDestination.js'
+
+const blocked = [
+ '0.1.2.3',
+ '10.0.0.1',
+ '100.64.0.1',
+ '100.127.255.255',
+ '127.0.0.1',
+ '169.254.1.1',
+ '172.16.0.1',
+ '172.31.255.255',
+ '192.0.0.9',
+ '192.0.2.1',
+ '192.31.196.1',
+ '192.52.193.1',
+ '192.88.99.1',
+ '192.168.1.1',
+ '192.175.48.1',
+ '198.18.0.1',
+ '198.19.255.255',
+ '198.51.100.1',
+ '203.0.113.1',
+ '224.0.0.1',
+ '255.255.255.255',
+ '::',
+ '::1',
+ '::ffff:127.0.0.1',
+ '::ffff:8.8.8.8',
+ '64:ff9b::a00:1',
+ '64:ff9b:1::1',
+ '100::1',
+ '100:0:0:1::1',
+ '2001::1',
+ '2001:1ff::1',
+ '2001:db8::1',
+ '2002:a00:1::1',
+ '2620:4f:8000::1',
+ '3fff::1',
+ '3fff:fff::1',
+ '5f00::1',
+ 'fc00::1',
+ 'fe80::1',
+ 'fec0::1',
+ 'ff02::1',
+ '2001:4860:1:2:0:5efe:a00:1',
+ '2001:4860:1:2:200:5efe:a00:1',
+ 'invalid',
+ 'fe80::1%eth0',
+]
+for (const ip of blocked) test(`blocks ${ip}`, () => assert.equal(isPublicAddress(ip), false))
+for (const ip of [
+ '8.8.8.8',
+ '100.63.255.255',
+ '100.128.0.0',
+ '172.15.255.255',
+ '172.32.0.0',
+ '198.17.255.255',
+ '198.20.0.0',
+ '2001:4860:4860::8888',
+ '2606:4700::1111',
+])
+ test(`permits ordinary public ${ip}`, () => assert.equal(isPublicAddress(ip), true))
+for (const input of [
+ 'file:///etc/passwd',
+ 'data:text/plain,ok',
+ 'ftp://example.test',
+ 'http://u:[email protected]',
+ 'http://example.test:0',
+ 'http://example.test/ a',
+ 'http://example.test\\@127.0.0.1',
+ 'http://[fe80::1%25eth0]/',
+ `http://example.test/${'a'.repeat(8192)}`,
+])
+ test('rejects invalid URL ' + input.slice(0, 50), () =>
+ assert.throws(() => parsePageUrl(input), { code: 'invalid_url' })
+ )
+for (const input of ['http://2130706433', 'http://0x7f000001', 'http://127.1', 'http://0177.0.0.1'])
+ test('normalizes disguised loopback ' + input, async () =>
+ assert.rejects(resolvePageAddress(parsePageUrl(input), new AbortController().signal), {
+ code: 'destination_blocked',
+ })
+ )
+test('DNS cannot hide a private AAAA behind public A', async t => {
+ t.mock.method(Resolver.prototype, 'resolve4', async () => ['8.8.8.8'])
+ t.mock.method(Resolver.prototype, 'resolve6', async () => ['::1'])
+ await assert.rejects(
+ resolvePageAddress(new URL('http://example.test'), new AbortController().signal),
+ { code: 'destination_blocked' }
+ )
+})
+test('record absence is allowed but DNS failures are not', async t => {
+ t.mock.method(Resolver.prototype, 'resolve4', async () => ['8.8.8.8'])
+ const lookup = t.mock.method(Resolver.prototype, 'resolve6', async () => {
+ throw Object.assign(new Error(), { code: 'ENODATA' })
+ })
+ assert.equal(
+ await resolvePageAddress(new URL('http://example.test'), new AbortController().signal),
+ '8.8.8.8'
+ )
+ for (const code of ['ETIMEOUT', 'ESERVFAIL', 'ENOTFOUND']) {
+ lookup.mock.mockImplementation(async () => {
+ throw Object.assign(new Error(), { code })
+ })
+ await assert.rejects(
+ resolvePageAddress(new URL('http://example.test'), new AbortController().signal),
+ { code: 'upstream_failure' }
+ )
+ }
+})
+test('already-cancelled resolution performs no DNS work', async t => {
+ const lookup = t.mock.method(Resolver.prototype, 'resolve4')
+ await assert.rejects(resolvePageAddress(new URL('http://example.test'), AbortSignal.abort()))
+ assert.equal(lookup.mock.callCount(), 0)
+})
diff --git a/mcp-servers/web-search/test/dns-fixture.mjs b/mcp-servers/web-search/test/dns-fixture.mjs
new file mode 100644
index 000000000..801a7733a
--- /dev/null
+++ b/mcp-servers/web-search/test/dns-fixture.mjs
@@ -0,0 +1,54 @@
+import dgram from 'node:dgram'
+
+/** Minimal authoritative UDP DNS fixture; only synthetic .test names. */
+export async function startDnsFixture() {
+ const server = dgram.createSocket('udp4')
+ const queries = new Map()
+ server.on('message', (packet, peer) => {
+ let offset = 12
+ const labels = []
+ while (offset < packet.length && packet[offset]) {
+ const length = packet[offset++]
+ if (length > 63 || offset + length > packet.length) return
+ labels.push(packet.toString('ascii', offset, offset + length))
+ offset += length
+ }
+ if (offset + 5 > packet.length) return
+ offset++
+ const type = packet.readUInt16BE(offset)
+ offset += 4
+ const name = labels.join('.')
+ const key = name + ':' + type
+ queries.set(key, (queries.get(key) ?? 0) + 1)
+ let data
+ if (name.endsWith('.test')) {
+ if (type === 1)
+ data = Buffer.from(
+ name === 'rebind.test' && queries.get(key) > 1 ? [127, 0, 0, 1] : [11, 198, 0, 2]
+ )
+ if (type === 28 && name === 'mixed.test')
+ data = Buffer.from('00000000000000000000000000000001', 'hex')
+ }
+ const header = Buffer.from(packet.subarray(0, 12))
+ header.writeUInt16BE(0x8180, 2)
+ header.writeUInt16BE(1, 4)
+ header.writeUInt16BE(data ? 1 : 0, 6)
+ header.writeUInt32BE(0, 8)
+ const parts = [header, packet.subarray(12, offset)]
+ if (data) {
+ const answer = Buffer.alloc(12)
+ answer.writeUInt16BE(0xc00c, 0)
+ answer.writeUInt16BE(type, 2)
+ answer.writeUInt16BE(1, 4)
+ answer.writeUInt32BE(0, 6)
+ answer.writeUInt16BE(data.length, 10)
+ parts.push(answer, data)
+ }
+ server.send(Buffer.concat(parts), peer.port, peer.address)
+ })
+ await new Promise((resolve, reject) => {
+ server.once('error', reject)
+ server.bind(53, '127.0.0.1', resolve)
+ })
+ return { queries, close: () => server.close() }
+}
diff --git a/mcp-servers/web-search/test/fetchPage.test.mjs b/mcp-servers/web-search/test/fetchPage.test.mjs
new file mode 100644
index 000000000..498278de1
--- /dev/null
+++ b/mcp-servers/web-search/test/fetchPage.test.mjs
@@ -0,0 +1,181 @@
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+import http from 'node:http'
+import { PassThrough } from 'node:stream'
+import { test } from 'node:test'
+import { brotliCompressSync, deflateSync, gzipSync } from 'node:zlib'
+import { FETCH_PAGE_LIMITS, fetchPage, pageText } from '../dist/fetchPage.js'
+
+// Unit-only transport double. Real sockets and MCP are separate required lanes.
+function upstream(t, responses) {
+ const options = []
+ t.mock.method(http, 'request', (opts, callback) => {
+ options.push(opts)
+ const request = new EventEmitter()
+ request.end = () =>
+ queueMicrotask(() => {
+ const response = new PassThrough()
+ const spec = responses.shift()
+ response.statusCode = spec.status ?? 200
+ response.headers = spec.headers ?? {}
+ callback(response)
+ response.end(spec.body ?? '<title>Example</title><p>Hello</p>')
+ })
+ return request
+ })
+ return options
+}
+test('legitimate content and pinned connection contract', async t => {
+ const options = upstream(t, [{}])
+ assert.deepEqual(await fetchPage('http://8.8.8.8/example?q=1', 100), {
+ title: 'Example',
+ content: 'Example Hello',
+ })
+ assert.equal(options[0].hostname, '8.8.8.8')
+ assert.equal(options[0].path, '/example?q=1')
+ assert.equal(options[0].agent, false)
+})
+test('private redirect never creates a second connection', async t => {
+ const calls = upstream(t, [{ status: 302, headers: { location: 'http://127.0.0.1' } }])
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'destination_blocked' })
+ assert.equal(calls.length, 1)
+})
+test('relative redirects and cycles', async t => {
+ upstream(t, [{ status: 302, headers: { location: '/next' } }, {}])
+ assert.equal((await fetchPage('http://8.8.8.8', 100)).content, 'Example Hello')
+ upstream(t, [{ status: 302, headers: { location: '/' } }])
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'redirect_limit' })
+})
+for (const [encoding, compress] of [
+ ['gzip', gzipSync],
+ ['deflate', deflateSync],
+ ['br', brotliCompressSync],
+]) {
+ test(encoding + ' decoded normally', async t => {
+ upstream(t, [{ headers: { 'content-encoding': encoding }, body: compress('hello') }])
+ assert.equal((await fetchPage('http://8.8.8.8', 100)).content, 'hello')
+ })
+ test(encoding + ' expansion is bounded', async t => {
+ upstream(t, [
+ {
+ headers: { 'content-encoding': encoding },
+ body: compress('x'.repeat(FETCH_PAGE_LIMITS.maxBytes + 1)),
+ },
+ ])
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'response_too_large' })
+ })
+}
+test('maxChars is not the byte ceiling; exact ceiling succeeds and +1 fails', async t => {
+ upstream(t, [
+ { body: 'x'.repeat(FETCH_PAGE_LIMITS.maxBytes) },
+ { body: 'x'.repeat(FETCH_PAGE_LIMITS.maxBytes + 1) },
+ {},
+ ])
+ assert.equal((await fetchPage('http://8.8.8.8', 100)).content.length, 100)
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'response_too_large' })
+ assert.equal((await fetchPage('http://8.8.8.8', 100)).title, 'Example')
+})
+test('unsupported encoding returns only a stable error', async t => {
+ upstream(t, [{ headers: { 'content-encoding': 'gzip, br' } }])
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { message: 'unsupported_encoding' })
+})
+test('linear stripping preserves malformed and ordinary text', () => {
+ assert.equal(pageText('a <b> c </b> d'), 'a c d')
+ const input = '<'.repeat(1000000)
+ assert.equal(pageText(input), input)
+})
+
+test('deadline remains active after headers and destroys the body', async t => {
+ t.mock.timers.enable({ apis: ['setTimeout'] })
+ const headers = Promise.withResolvers()
+ let response
+ t.mock.method(http, 'request', (_opts, callback) => {
+ const req = new EventEmitter()
+ req.end = () =>
+ queueMicrotask(() => {
+ response = new PassThrough()
+ response.statusCode = 200
+ response.headers = {}
+ callback(response)
+ response.write('partial')
+ headers.resolve()
+ })
+ return req
+ })
+ const pending = fetchPage('http://8.8.8.8', 100)
+ const rejected = assert.rejects(pending, { code: 'deadline_exceeded' })
+ await headers.promise
+ t.mock.timers.tick(FETCH_PAGE_LIMITS.timeoutMs)
+ await rejected
+ assert.equal(response.destroyed, true)
+})
+
+test('process-wide concurrency has no queue and abort releases every slot', async t => {
+ const requests = []
+ const allHeaders = Promise.withResolvers()
+ t.mock.method(http, 'request', (_opts, callback) => {
+ const req = new EventEmitter()
+ req.end = () =>
+ queueMicrotask(() => {
+ const res = new PassThrough()
+ res.statusCode = 200
+ res.headers = {}
+ requests.push(res)
+ callback(res)
+ if (requests.length === FETCH_PAGE_LIMITS.maxConcurrent) allHeaders.resolve()
+ })
+ return req
+ })
+ const controllers = Array.from(
+ { length: FETCH_PAGE_LIMITS.maxConcurrent },
+ () => new AbortController()
+ )
+ const rejected = controllers.map(controller =>
+ assert.rejects(fetchPage('http://8.8.8.8', 100, controller.signal), { code: 'cancelled' })
+ )
+ await allHeaders.promise
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'busy' })
+ for (const controller of controllers) controller.abort()
+ await Promise.all(rejected)
+ assert.equal(
+ requests.every(r => r.destroyed),
+ true
+ )
+ upstream(t, [{}])
+ assert.equal((await fetchPage('http://8.8.8.8', 100)).title, 'Example')
+})
+
+test('redirect hop limit terminates before another connection', async t => {
+ const responses = Array.from({ length: 6 }, (_, i) => ({
+ status: 302,
+ headers: { location: `/hop-${i}` },
+ }))
+ const calls = upstream(t, responses)
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'redirect_limit' })
+ assert.equal(calls.length, 6)
+})
+
+test('untrusted declared length is rejected before buffering', async t => {
+ upstream(t, [{ headers: { 'content-length': String(FETCH_PAGE_LIMITS.maxBytes + 1) } }])
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'response_too_large' })
+})
+
+test('compressed wire overhead is bounded independently of decoded size', async t => {
+ const { randomBytes } = await import('node:crypto')
+ const compressed = gzipSync(randomBytes(FETCH_PAGE_LIMITS.maxBytes))
+ assert.ok(compressed.length > FETCH_PAGE_LIMITS.maxBytes)
+ upstream(t, [{ headers: { 'content-encoding': 'gzip' }, body: compressed }])
+ await assert.rejects(fetchPage('http://8.8.8.8', 100), { code: 'response_too_large' })
+})
+
+test('DNS host connects only to the validated address and preserves Host', async t => {
+ const { Resolver } = await import('node:dns/promises')
+ t.mock.method(Resolver.prototype, 'resolve4', async () => ['8.8.8.8'])
+ t.mock.method(Resolver.prototype, 'resolve6', async () => {
+ throw Object.assign(new Error(), { code: 'ENODATA' })
+ })
+ const requests = upstream(t, [{}])
+ await fetchPage('http://fixture.test:8080/', 100)
+ assert.equal(requests[0].hostname, '8.8.8.8')
+ assert.equal(requests[0].headers.Host, 'fixture.test:8080')
+})
diff --git a/mcp-servers/web-search/test/mcp.network.mjs b/mcp-servers/web-search/test/mcp.network.mjs
new file mode 100644
index 000000000..9891070c2
--- /dev/null
+++ b/mcp-servers/web-search/test/mcp.network.mjs
@@ -0,0 +1,158 @@
+// Runs only in the isolated Linux network fixture; no global application mocks.
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import http from 'node:http'
+import https from 'node:https'
+import { after, test } from 'node:test'
+import { gzipSync } from 'node:zlib'
+import { startDnsFixture } from './dns-fixture.mjs'
+import { Client } from '/app/node_modules/@modelcontextprotocol/sdk/dist/esm/client/index.js'
+import { StreamableHTTPClientTransport } from '/app/node_modules/@modelcontextprotocol/sdk/dist/esm/client/streamableHttp.js'
+
+const content = '<title>Network fixture</title><p>issue198-real-result</p>'
+let trapHits = 0
+let slowClosed = 0
+const sockets = new Set()
+const dns = await startDnsFixture()
+let lastSni
+const tlsServer = https.createServer(
+ {
+ key: readFileSync('/fixture-tls/fixture-key.pem'),
+ cert: readFileSync('/fixture-tls/fixture-cert.pem'),
+ },
+ (req, res) => {
+ lastSni = req.socket.servername
+ if (req.url === '/downgrade') {
+ res.writeHead(302, { Location: 'http://fixture.test:8080/' })
+ res.end()
+ } else res.end(content)
+ }
+)
+await new Promise(resolve => tlsServer.listen(8443, '11.198.0.2', resolve))
+const upstream = http.createServer((req, res) => {
+ if (req.url === '/redirect') {
+ res.writeHead(302, { Location: 'http://127.0.0.1:8081/trap' })
+ res.end()
+ return
+ }
+ if (req.url === '/oversize') {
+ res.writeHead(200)
+ res.end('x'.repeat(1024 * 1024 + 1))
+ return
+ }
+ if (req.url === '/compressed') {
+ res.writeHead(200, { 'Content-Encoding': 'gzip' })
+ res.end(gzipSync('x'.repeat(1024 * 1024 + 1)))
+ return
+ }
+ if (req.url === '/slow') {
+ res.writeHead(200)
+ res.write('first')
+ // Intentionally active hostile upstream, not a test readiness sleep.
+ const interval = setInterval(() => res.write('x'), 50)
+ res.on('close', () => {
+ clearInterval(interval)
+ slowClosed++
+ })
+ return
+ }
+ res.end(content)
+})
+const trap = http.createServer((_req, res) => {
+ trapHits++
+ res.end('must-not-be-read')
+})
+for (const server of [upstream, trap, tlsServer])
+ server.on('connection', socket => {
+ sockets.add(socket)
+ socket.on('close', () => sockets.delete(socket))
+ })
+await Promise.all([
+ new Promise(r => upstream.listen(8080, '11.198.0.2', r)),
+ new Promise(r => trap.listen(8081, '127.0.0.1', r)),
+])
+const child = spawn(process.execPath, ['/app/dist/index.js'], { stdio: ['ignore', 'pipe', 'pipe'] })
+const client = new Client({ name: 'issue198-network', version: '1.0' })
+after(async () => {
+ await client.close()
+ child.kill()
+ for (const socket of sockets) socket.destroy()
+ upstream.close()
+ trap.close()
+ tlsServer.close()
+ dns.close()
+})
+await new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => reject(new Error('startup timeout')), 10000)
+ child.once('exit', () => {
+ clearTimeout(timeout)
+ reject(new Error('server exited'))
+ })
+ child.stdout.on('data', data => {
+ if (data.toString().includes('listening on port')) {
+ clearTimeout(timeout)
+ resolve()
+ }
+ })
+})
+await client.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3000/mcp')))
+const call = url =>
+ client.callTool({ name: 'fetch_page', arguments: { url } }, undefined, { timeout: 25000 })
+const errorCode = result => {
+ assert.equal(result.isError, true)
+ return result.content[0].text
+}
+test('real DNS pins a single answer and rejects mixed public/private records', async () => {
+ assert.notEqual((await call('http://rebind.test:8080/')).isError, true)
+ assert.equal(dns.queries.get('rebind.test:1'), 1)
+ assert.equal(errorCode(await call('http://mixed.test:8080/')), 'destination_blocked')
+})
+test('TLS validates original host and SNI, and blocks downgrade', async () => {
+ assert.notEqual((await call('https://fixture.test:8443/')).isError, true)
+ assert.equal(lastSni, 'fixture.test')
+ assert.equal(errorCode(await call('https://wrong.test:8443/')), 'upstream_failure')
+ assert.equal(errorCode(await call('https://fixture.test:8443/downgrade')), 'destination_blocked')
+})
+test('the real connector is listed and returns the real fixture content', async () => {
+ assert.ok((await client.listTools()).tools.some(t => t.name === 'fetch_page'))
+ const result = await call('http://11.198.0.2:8080/')
+ assert.notEqual(result.isError, true)
+ assert.deepEqual(JSON.parse(result.content[0].text), {
+ title: 'Network fixture',
+ content: 'Network fixture issue198-real-result',
+ })
+})
+test('direct and redirected private requests never touch the trap', async () => {
+ assert.equal(errorCode(await call('http://127.0.0.1:8081/trap')), 'destination_blocked')
+ assert.equal(errorCode(await call('http://11.198.0.2:8080/redirect')), 'destination_blocked')
+ assert.equal(trapHits, 0)
+})
+test('chunked and compressed bodies cannot bypass the byte limit', async () => {
+ for (const path of ['/oversize', '/compressed'])
+ assert.equal(errorCode(await call('http://11.198.0.2:8080' + path)), 'response_too_large')
+})
+test(
+ 'real deadline covers an active body; subsequent request succeeds',
+ { timeout: 22000 },
+ async () => {
+ const start = performance.now()
+ assert.equal(errorCode(await call('http://11.198.0.2:8080/slow')), 'deadline_exceeded')
+ assert.ok(performance.now() - start < 19000)
+ // Poll an observable cleanup signal, bounded by the test runner deadline.
+ await new Promise((resolve, reject) => {
+ const deadline = setTimeout(() => {
+ clearInterval(poll)
+ reject(new Error('upstream socket not closed'))
+ }, 1000)
+ const poll = setInterval(() => {
+ if (slowClosed) {
+ clearInterval(poll)
+ clearTimeout(deadline)
+ resolve()
+ }
+ }, 10)
+ })
+ assert.notEqual((await call('http://11.198.0.2:8080/')).isError, true)
+ }
+)
diff --git a/mcp-servers/web-search/test/run-network.mjs b/mcp-servers/web-search/test/run-network.mjs
new file mode 100644
index 000000000..c031301a3
--- /dev/null
+++ b/mcp-servers/web-search/test/run-network.mjs
@@ -0,0 +1,120 @@
+import { execFileSync, spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Development-only: no external network, published ports, or credential mounts.
+if (process.versions.node.split('.')[0] !== '24') throw new Error('Use Node 24 for network tests')
+const root = realpathSync(fileURLToPath(new URL('..', import.meta.url)))
+const image =
+ process.argv[2] === '--image' && process.argv.length === 4 ? process.argv[3] : undefined
+if (process.argv.length > 2 && !image)
+ throw new Error('Usage: run-network.mjs [--image local-image-id]')
+const endpoint =
+ process.env.DOCKER_HOST ||
+ execFileSync('docker', ['context', 'inspect', '--format', '{{.Endpoints.docker.Host}}'], {
+ encoding: 'utf8',
+ timeout: 10000,
+ }).trim()
+if (
+ !endpoint.startsWith('unix:///') &&
+ !/^tcp:\/\/(127\.0\.0\.1|localhost|\[::1\]):\d+$/.test(endpoint)
+)
+ throw new Error('A local Docker endpoint is required')
+const config = mkdtempSync(path.join(tmpdir(), 'issue198-docker-'))
+// Synthetic, one-day certificate generated locally, never committed.
+execFileSync(
+ 'openssl',
+ [
+ 'req',
+ '-x509',
+ '-newkey',
+ 'rsa:2048',
+ '-nodes',
+ '-keyout',
+ path.join(config, 'fixture-key.pem'),
+ '-out',
+ path.join(config, 'fixture-cert.pem'),
+ '-days',
+ '1',
+ '-subj',
+ '/CN=fixture.test',
+ '-addext',
+ 'subjectAltName=DNS:fixture.test,DNS:rebind.test,IP:11.198.0.2',
+ ],
+ { stdio: 'ignore', timeout: 10000 }
+)
+const name = 'issue198-network-' + randomUUID()
+const docker = ['--host', endpoint, '--config', config]
+const args = [
+ ...docker,
+ 'run',
+ '--rm',
+ '--pull=never',
+ '--name',
+ name,
+ '--network=none',
+ '--cap-drop=ALL',
+ '--cap-add=NET_ADMIN',
+ '--memory=256m',
+ '--cpus=1',
+ '--label',
+ 'evenfire.test=issue198-network',
+ '--mount',
+ `type=bind,src=${config},dst=/fixture-tls,readonly`,
+ '-e',
+ 'NODE_EXTRA_CA_CERTS=/fixture-tls/fixture-cert.pem',
+]
+for (const part of image ? ['test'] : ['dist', 'node_modules', 'test'])
+ args.push(
+ '--mount',
+ `type=bind,src=${realpathSync(path.join(root, part))},dst=/app/${part},readonly`
+ )
+args.push(
+ image ?? 'node:24-alpine',
+ 'sh',
+ '-ec',
+ 'ip addr add 11.198.0.2/32 dev lo; test -z "$(ip route show default)"; printf "nameserver 127.0.0.1\\n" > /etc/resolv.conf; node --test /app/test/mcp.network.mjs'
+)
+let child
+let timeout
+let interrupted = false
+const stop = () => {
+ interrupted = true
+ child?.kill('SIGTERM')
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+try {
+ child = spawn('docker', args, { stdio: 'inherit' })
+ timeout = setTimeout(stop, 60000)
+ const status = await new Promise((resolve, reject) => {
+ child.once('error', reject)
+ child.once('exit', resolve)
+ })
+ process.exitCode = interrupted || status !== 0 ? 1 : 0
+} finally {
+ clearTimeout(timeout)
+ process.removeListener('SIGINT', stop)
+ process.removeListener('SIGTERM', stop)
+ // Random name belongs exclusively to this invocation, including on timeout.
+ try {
+ execFileSync('docker', [...docker, 'rm', '-f', name], { stdio: 'ignore', timeout: 10000 })
+ } catch {
+ // --rm may already have removed it. Prove absence; a Docker failure is not cleanup.
+ try {
+ const remaining = execFileSync(
+ 'docker',
+ [...docker, 'ps', '-aq', '--filter', `name=^/${name}$`],
+ { encoding: 'utf8', timeout: 10000 }
+ ).trim()
+ if (remaining) throw new Error('The test container remains after cleanup')
+ } catch {
+ process.exitCode = 1
+ console.error('Could not verify removal of the isolated test container')
+ }
+ }
+ rmSync(config, { recursive: true, force: true })
+}
diff --git a/scripts/tests/test-web-search-image.sh b/scripts/tests/test-web-search-image.sh
new file mode 100755
index 000000000..25cb46668
--- /dev/null
+++ b/scripts/tests/test-web-search-image.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
+cd "$ROOT"
+source scripts/minikube/docker-cli-env.sh
+docker_cli_env_prepare
+trap docker_cli_env_cleanup EXIT
+revision="$(git rev-parse HEAD)"
+image="evenfire-web-search-test:${revision}"
+node scripts/minikube/run-with-deadline.mjs --timeout-seconds 300 --heartbeat-seconds 20 --kill-grace-seconds 5 --label web-search-image-build -- \
+ docker build --pull=false --label "org.opencontainers.image.revision=${revision}" -t "$image" mcp-servers/web-search
+image_id="$(docker image inspect "$image" --format '{{.Id}}')"
+[[ "$image_id" =~ ^sha256:[a-f0-9]{64}$ ]] || { echo 'Invalid local image identity' >&2; exit 1; }
+printf 'WEB_SEARCH_TEST_REVISION=%s\nWEB_SEARCH_TEST_IMAGE=%s\n' "$revision" "$image_id"
+node scripts/minikube/run-with-deadline.mjs --timeout-seconds 120 --heartbeat-seconds 20 --kill-grace-seconds 5 --label web-search-image-test -- \
+ node mcp-servers/web-search/test/run-network.mjs --image "$image_id"