@llmindset/hf-mcp 0.3.2 → 0.3.4

package/src/network/safe-fetch.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createExternalHttpsPolicy, createHfDocsPolicy } from './url-policy.js';
+import { safeFetch } from './safe-fetch.js';
+
+describe('safeFetch', () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+		vi.unstubAllGlobals();
+	});
+
+	it('follows redirects manually and validates each hop', async () => {
+		const fetchMock = vi
+			.fn()
+			.mockResolvedValueOnce(new Response('', { status: 302, headers: { location: '/docs/next' } }))
+			.mockResolvedValueOnce(new Response('ok', { status: 200 }));
+		vi.stubGlobal('fetch', fetchMock);
+
+		const result = await safeFetch('https://huggingface.co/docs/start', {
+			urlPolicy: createHfDocsPolicy(),
+			externalOnly: true,
+		});
+
+		expect(result.redirectsFollowed).toBe(1);
+		expect(result.finalUrl.toString()).toBe('https://huggingface.co/docs/next');
+		expect(fetchMock).toHaveBeenCalledTimes(2);
+		expect(fetchMock.mock.calls[0]?.[0]).toBe('https://huggingface.co/docs/start');
+		expect(fetchMock.mock.calls[1]?.[0]).toBe('https://huggingface.co/docs/next');
+	});
+
+	it('rejects redirect to disallowed host', async () => {
+		const fetchMock = vi
+			.fn()
+			.mockResolvedValueOnce(new Response('', { status: 302, headers: { location: 'https://example.com/path' } }));
+		vi.stubGlobal('fetch', fetchMock);
+
+		await expect(
+			safeFetch('https://huggingface.co/docs/start', {
+				urlPolicy: createHfDocsPolicy(),
+				externalOnly: true,
+			})
+		).rejects.toThrow('URL hostname is not allowed');
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+	});
+
+	it('enforces redirect limits', async () => {
+		const fetchMock = vi
+			.fn()
+			.mockResolvedValueOnce(new Response('', { status: 302, headers: { location: '/docs/a' } }))
+			.mockResolvedValueOnce(new Response('', { status: 302, headers: { location: '/docs/b' } }));
+		vi.stubGlobal('fetch', fetchMock);
+
+		await expect(
+			safeFetch('https://huggingface.co/docs/start', {
+				urlPolicy: createHfDocsPolicy(),
+				maxRedirects: 1,
+			})
+		).rejects.toThrow('Redirect limit exceeded');
+	});
+
+	it('enforces timeout', async () => {
+		const fetchMock = vi.fn().mockImplementation(
+			(_url: string, init?: RequestInit) =>
+				new Promise((_, reject) => {
+					const signal = init?.signal;
+					signal?.addEventListener(
+						'abort',
+						() => {
+							reject(new DOMException('aborted', 'AbortError'));
+						},
+						{ once: true }
+					);
+				})
+		);
+		vi.stubGlobal('fetch', fetchMock);
+
+		await expect(
+			safeFetch('https://example.com/file.wav', {
+				urlPolicy: createExternalHttpsPolicy(),
+				timeoutMs: 5,
+			})
+		).rejects.toThrow('Request timed out');
+	});
+
+	it('keeps caller abort signal active while streaming response body', async () => {
+		const fetchMock = vi.fn().mockImplementation((_url: string, init?: RequestInit) => {
+			const stream = new ReadableStream<Uint8Array>({
+				start(controller) {
+					init?.signal?.addEventListener(
+						'abort',
+						() => {
+							controller.error(new DOMException('aborted', 'AbortError'));
+						},
+						{ once: true }
+					);
+				},
+				pull() {
+					return new Promise<void>(() => {});
+				},
+			});
+
+			return Promise.resolve(new Response(stream, { status: 200 }));
+		});
+		vi.stubGlobal('fetch', fetchMock);
+
+		const controller = new AbortController();
+		const { response } = await safeFetch('https://example.com/file.wav', {
+			urlPolicy: createExternalHttpsPolicy(),
+			timeoutMs: 500,
+			requestInit: { signal: controller.signal },
+		});
+
+		const reader = response.body?.getReader();
+		if (!reader) {
+			throw new Error('Expected response body to exist');
+		}
+
+		const readPromise = Promise.race([
+			reader.read(),
+			new Promise<never>((_, reject) => {
+				setTimeout(() => {
+					reject(new Error('stream read did not abort'));
+				}, 100);
+			}),
+		]);
+		controller.abort();
+
+		await expect(readPromise).rejects.toMatchObject({ name: 'AbortError' });
+	});
+
+	it('enforces timeout while streaming response body', async () => {
+		const fetchMock = vi.fn().mockImplementation((_url: string, init?: RequestInit) => {
+			const stream = new ReadableStream<Uint8Array>({
+				start(controller) {
+					init?.signal?.addEventListener(
+						'abort',
+						() => {
+							controller.error(new DOMException('aborted', 'AbortError'));
+						},
+						{ once: true }
+					);
+				},
+				pull() {
+					return new Promise<void>(() => {});
+				},
+			});
+
+			return Promise.resolve(new Response(stream, { status: 200 }));
+		});
+		vi.stubGlobal('fetch', fetchMock);
+
+		const { response } = await safeFetch('https://example.com/file.wav', {
+			urlPolicy: createExternalHttpsPolicy(),
+			timeoutMs: 10,
+		});
+
+		const reader = response.body?.getReader();
+		if (!reader) {
+			throw new Error('Expected response body to exist');
+		}
+
+		const readPromise = Promise.race([
+			reader.read(),
+			new Promise<never>((_, reject) => {
+				setTimeout(() => {
+					reject(new Error('stream read did not timeout'));
+				}, 200);
+			}),
+		]);
+
+		await expect(readPromise).rejects.toMatchObject({ name: 'AbortError' });
+	});
+
+	it('blocks internal destinations when externalOnly is enabled', async () => {
+		await expect(
+			safeFetch('https://127.0.0.1/x', {
+				urlPolicy: createExternalHttpsPolicy(),
+				externalOnly: true,
+			})
+		).rejects.toThrow('Blocked internal or reserved address');
+	});
+});

package/src/network/safe-fetch.ts

@@ -0,0 +1,174 @@
+import { assertExternalAddress } from './ip-policy.js';
+import { parseAndValidateUrl, type UrlPolicy } from './url-policy.js';
+
+export interface SafeFetchOptions {
+	urlPolicy: UrlPolicy;
+	timeoutMs?: number;
+	maxRedirects?: number;
+	externalOnly?: boolean;
+	requestInit?: RequestInit;
+	stripSensitiveHeadersOnCrossHostRedirect?: boolean;
+}
+
+export interface SafeFetchResult {
+	response: Response;
+	finalUrl: URL;
+	redirectsFollowed: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 12500;
+const DEFAULT_MAX_REDIRECTS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const SENSITIVE_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie', 'x-hf-authorization']);
+
+function isRedirectStatus(status: number): boolean {
+	return REDIRECT_STATUSES.has(status);
+}
+
+function dropSensitiveHeaders(headersInit: HeadersInit | undefined): Headers {
+	const headers = new Headers(headersInit);
+	for (const key of SENSITIVE_HEADERS) {
+		headers.delete(key);
+	}
+	return headers;
+}
+
+function withMethodAndBody(requestInit: RequestInit, method: string, body: BodyInit | null | undefined): RequestInit {
+	const nextInit: RequestInit = {
+		...requestInit,
+		method,
+		redirect: 'manual',
+	};
+
+	if (body !== undefined && body !== null && method !== 'GET' && method !== 'HEAD') {
+		nextInit.body = body;
+	} else {
+		delete nextInit.body;
+	}
+
+	return nextInit;
+}
+
+async function fetchWithTimeout(url: URL, requestInit: RequestInit, timeoutMs: number): Promise<Response> {
+	if (timeoutMs <= 0) {
+		return fetch(url.toString(), {
+			...requestInit,
+			redirect: 'manual',
+		});
+	}
+
+	const outerSignal = requestInit.signal;
+
+	if (outerSignal) {
+		if (outerSignal.aborted) {
+			throw new Error('Request was aborted');
+		}
+	}
+
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	const signal = outerSignal ? AbortSignal.any([outerSignal, timeoutSignal]) : timeoutSignal;
+
+	try {
+		return await fetch(url.toString(), {
+			...requestInit,
+			signal,
+			redirect: 'manual',
+		});
+	} catch (error) {
+		if (error instanceof Error && error.name === 'AbortError') {
+			if (outerSignal?.aborted) {
+				throw new Error('Request was aborted');
+			}
+
+			if (timeoutSignal.aborted) {
+				throw new Error(`Request timed out after ${timeoutMs.toString()}ms`);
+			}
+
+			throw new Error(`Request timed out after ${timeoutMs.toString()}ms`);
+		}
+		throw error;
+	}
+}
+
+export async function safeFetch(url: string | URL, options: SafeFetchOptions): Promise<SafeFetchResult> {
+	const {
+		urlPolicy,
+		timeoutMs = DEFAULT_TIMEOUT_MS,
+		maxRedirects = DEFAULT_MAX_REDIRECTS,
+		externalOnly = false,
+		requestInit = {},
+		stripSensitiveHeadersOnCrossHostRedirect = true,
+	} = options;
+
+	if (maxRedirects < 0) {
+		throw new Error('maxRedirects must be >= 0');
+	}
+
+	let currentUrl = parseAndValidateUrl(url, urlPolicy);
+	if (externalOnly) {
+		await assertExternalAddress(currentUrl.hostname);
+	}
+
+	const baseHeaders = new Headers(requestInit.headers);
+	let currentMethod = (requestInit.method || 'GET').toUpperCase();
+	let currentBody = requestInit.body;
+	let redirectsFollowed = 0;
+
+	while (true) {
+		const currentInit = withMethodAndBody(
+			{
+				...requestInit,
+				headers: baseHeaders,
+			},
+			currentMethod,
+			currentBody
+		);
+
+		const response = await fetchWithTimeout(currentUrl, currentInit, timeoutMs);
+
+		if (!isRedirectStatus(response.status)) {
+			return {
+				response,
+				finalUrl: currentUrl,
+				redirectsFollowed,
+			};
+		}
+
+		if (redirectsFollowed >= maxRedirects) {
+			throw new Error(`Redirect limit exceeded (${maxRedirects.toString()})`);
+		}
+
+		const location = response.headers.get('location');
+		if (!location) {
+			throw new Error(`Redirect response missing Location header (status ${response.status.toString()})`);
+		}
+
+		const nextCandidate = new URL(location, currentUrl);
+		const nextUrl = parseAndValidateUrl(nextCandidate, urlPolicy);
+		if (externalOnly) {
+			await assertExternalAddress(nextUrl.hostname);
+		}
+
+		if (stripSensitiveHeadersOnCrossHostRedirect && currentUrl.origin !== nextUrl.origin) {
+			const filtered = dropSensitiveHeaders(baseHeaders);
+			baseHeaders.forEach((_, key) => {
+				baseHeaders.delete(key);
+			});
+			filtered.forEach((value, key) => {
+				baseHeaders.set(key, value);
+			});
+		}
+
+		if (response.status === 303 || ((response.status === 301 || response.status === 302) && currentMethod === 'POST')) {
+			currentMethod = 'GET';
+			currentBody = undefined;
+			baseHeaders.delete('content-length');
+			baseHeaders.delete('content-type');
+		}
+
+		redirectsFollowed += 1;
+		currentUrl = nextUrl;
+
+		await response.body?.cancel();
+	}
+}

package/src/network/url-policy.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import {
+	createExactHostPolicy,
+	createExternalHttpsPolicy,
+	createGradioMcpHostPolicy,
+	createGradioSchemaHostPolicy,
+	createHuggingFaceHubPolicy,
+	createLocalhostHttpPolicy,
+	createGradioMcpPolicy,
+	createHfDocsPolicy,
+	isLocalhostHostname,
+	parseAndValidateUrl,
+} from './url-policy.js';
+
+describe('url-policy', () => {
+	describe('HF docs policy', () => {
+		it('accepts valid Hugging Face docs and Gradio docs URLs', () => {
+			expect(() => parseAndValidateUrl('https://huggingface.co/docs/transformers', createHfDocsPolicy())).not.toThrow();
+			expect(() => parseAndValidateUrl('https://www.huggingface.co/docs/datasets', createHfDocsPolicy())).not.toThrow();
+			expect(() => parseAndValidateUrl('https://www.gradio.app/guides', createHfDocsPolicy())).not.toThrow();
+		});
+
+		it('rejects non-https or non-allowlisted hosts', () => {
+			expect(() => parseAndValidateUrl('http://huggingface.co/docs/transformers', createHfDocsPolicy())).toThrow(
+				'URL protocol is not allowed'
+			);
+			expect(() => parseAndValidateUrl('https://example.com/docs/transformers', createHfDocsPolicy())).toThrow(
+				'URL hostname is not allowed'
+			);
+		});
+
+		it('rejects traversal and encoded traversal variants', () => {
+			const variants = [
+				'https://huggingface.co/docs/../x',
+				'https://huggingface.co/docs/%2e%2e/x',
+				'https://huggingface.co/docs/%2e%2e%2fx',
+				'https://huggingface.co/docs/..%2fx',
+				'https://huggingface.co/docs/%2e%2e%5cx',
+				'https://huggingface.co/docs/%252e%252e%252fx',
+			];
+
+			for (const candidate of variants) {
+				expect(() => parseAndValidateUrl(candidate, createHfDocsPolicy())).toThrow();
+			}
+		});
+
+		it('enforces /docs/ prefix on HF hosts', () => {
+			expect(() => parseAndValidateUrl('https://huggingface.co/models/some-model', createHfDocsPolicy())).toThrow(
+				'Hugging Face docs URLs must remain under /docs/'
+			);
+		});
+	});
+
+	describe('Gradio MCP policy', () => {
+		it('accepts mcp endpoint URLs over https', () => {
+			expect(() =>
+				parseAndValidateUrl('https://demo-space.hf.space/gradio_api/mcp/', createGradioMcpPolicy())
+			).not.toThrow();
+			expect(() =>
+				parseAndValidateUrl('https://fake-mcp.local/gradio_api/mcp/', createGradioMcpPolicy())
+			).not.toThrow();
+		});
+
+		it('rejects invalid paths', () => {
+			expect(() => parseAndValidateUrl('https://demo-space.hf.space/not-mcp', createGradioMcpPolicy())).toThrow(
+				'URL path must start with /gradio_api/mcp'
+			);
+		});
+	});
+
+	describe('external https policy', () => {
+		it('rejects credentials in URL', () => {
+			expect(() => parseAndValidateUrl('https://user:pass@example.com/file.wav', createExternalHttpsPolicy())).toThrow(
+				'URL credentials are not allowed'
+			);
+		});
+	});
+
+	it('supports huggingface hub and localhost policy helpers', () => {
+		expect(() => parseAndValidateUrl('https://huggingface.co/api/models', createHuggingFaceHubPolicy())).not.toThrow();
+		expect(() => parseAndValidateUrl('http://localhost:7860/health', createLocalhostHttpPolicy())).not.toThrow();
+		expect(() => parseAndValidateUrl('https://example.com/x', createExactHostPolicy('example.com', 'https:'))).not.toThrow();
+		expect(() =>
+			parseAndValidateUrl(
+				'https://demo-space.hf.space/gradio_api/mcp/schema',
+				createGradioSchemaHostPolicy('demo-space.hf.space')
+			)
+		).not.toThrow();
+		expect(() =>
+			parseAndValidateUrl(
+				'https://demo-space.hf.space/gradio_api/mcp/',
+				createGradioMcpHostPolicy('demo-space.hf.space', 'https:')
+			)
+		).not.toThrow();
+		expect(isLocalhostHostname('localhost')).toBe(true);
+		expect(isLocalhostHostname('127.0.0.1')).toBe(true);
+		expect(isLocalhostHostname('[::1]')).toBe(true);
+		expect(isLocalhostHostname('example.com')).toBe(false);
+	});
+});