@llmindset/hf-mcp 0.3.2 → 0.3.3

package/src/jobs/schema-help.ts

@@ -7,7 +7,7 @@ import { z } from 'zod';
 
 export type AnyZodType = z.ZodType<unknown, z.ZodTypeDef, unknown>;
 
-export interface FieldDetails {
+interface FieldDetails {
 	key: string;
 	description?: string;
 	typeLabel: string;
@@ -19,7 +19,7 @@ export interface FieldDetails {
 /**
  * Unwrap optional/default/nullable wrappers to find the core type definition.
  */
-export function unwrapType(zodType: AnyZodType): {
+function unwrapType(zodType: AnyZodType): {
 	baseType: AnyZodType;
 	isOptional: boolean;
 	isNullable: boolean;
@@ -72,7 +72,7 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 /**
  * Generate a human-readable type label from a Zod type definition
  */
-export function labelForType(zodType: AnyZodType): string {
+function labelForType(zodType: AnyZodType): string {
 	if (zodType instanceof z.ZodString) {
 		return 'string';
 	}
@@ -151,7 +151,7 @@ export function extractFieldDetails(schema: AnyZodType): FieldDetails[] {
 /**
  * Format a default value for display in help text
  */
-export function formatDefaultValue(value: unknown): string | undefined {
+function formatDefaultValue(value: unknown): string | undefined {
 	if (value === undefined) {
 		return undefined;
 	}

package/src/jobs/sse-handler.ts

@@ -1,4 +1,5 @@
 import type { LogEvent } from './types.js';
+import { fetchWithProfile, NETWORK_FETCH_PROFILES } from '../network/fetch-profile.js';
 
 /**
  * Default duration to wait for logs when not detached (in milliseconds)
@@ -18,7 +19,7 @@ export const DEFAULT_MAX_LOG_LINES = 20;
 /**
  * Options for fetching logs via SSE
  */
-export interface SseLogOptions {
+interface SseLogOptions {
 	/** Maximum time to collect logs in milliseconds (default: 10000 = 10s) */
 	maxDuration?: number;
 	/** Maximum number of lines to return (default: 20) */
@@ -30,7 +31,7 @@ export interface SseLogOptions {
 /**
  * Result from fetching logs
  */
-export interface SseLogResult {
+interface SseLogResult {
 	/** Log lines collected */
 	logs: string[];
 	/** Whether the job finished during collection */
@@ -69,9 +70,12 @@ export async function fetchJobLogs(url: string, options: SseLogOptions = {}): Pr
 			headers['Authorization'] = `Bearer ${token}`;
 		}
 
-		const response = await fetch(url, {
-			headers,
-			signal: controller.signal,
+		const { response } = await fetchWithProfile(url, NETWORK_FETCH_PROFILES.externalHttps(), {
+			timeoutMs: maxDuration,
+			requestInit: {
+				headers,
+				signal: controller.signal,
+			},
 		});
 
 		if (!response.ok) {
@@ -140,8 +144,9 @@ export async function fetchJobLogs(url: string, options: SseLogOptions = {}): Pr
 		// Close the reader
 		await reader.cancel();
 	} catch (error) {
-		// If aborted due to timeout, that's expected
-		if ((error as Error).name !== 'AbortError') {
+		// Timeouts abort the stream while waiting for more SSE chunks.
+		// Treat any timeout-triggered abort as expected truncation.
+		if (!truncated && !controller.signal.aborted) {
 			throw error;
 		}
 	} finally {

package/src/logger.ts

@@ -1,6 +1,6 @@
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
 
-export interface Logger {
+interface Logger {
 	trace: (...args: unknown[]) => void;
 	debug: (...args: unknown[]) => void;
 	info: (...args: unknown[]) => void;

package/src/network/fetch-profile.ts

@@ -0,0 +1,112 @@
+import { safeFetch, type SafeFetchResult } from './safe-fetch.js';
+import {
+	createExternalHttpsPolicy,
+	createGradioMcpHostPolicy,
+	createGradioSchemaHostPolicy,
+	createHfDocsPolicy,
+	createHttpOrHttpsPolicy,
+	createHuggingFaceHubPolicy,
+	createLocalhostHttpPolicy,
+	isLocalhostHostname,
+	type UrlProtocol,
+	type UrlPolicy,
+} from './url-policy.js';
+
+const DEFAULT_TIMEOUT_MS = 12_500;
+const DEFAULT_MAX_REDIRECTS = 3;
+
+export interface SafeFetchProfile {
+	urlPolicy: UrlPolicy;
+	timeoutMs: number;
+	maxRedirects: number;
+	externalOnly: boolean;
+}
+
+export interface FetchWithProfileOptions {
+	requestInit?: RequestInit;
+	timeoutMs?: number;
+}
+
+export async function fetchWithProfile(
+	url: string | URL,
+	profile: SafeFetchProfile,
+	options: FetchWithProfileOptions = {}
+): Promise<SafeFetchResult> {
+	return safeFetch(url, {
+		urlPolicy: profile.urlPolicy,
+		timeoutMs: options.timeoutMs ?? profile.timeoutMs,
+		maxRedirects: profile.maxRedirects,
+		externalOnly: profile.externalOnly,
+		requestInit: options.requestInit,
+	});
+}
+
+export const NETWORK_FETCH_PROFILES = {
+	externalHttps(): SafeFetchProfile {
+		return {
+			urlPolicy: createExternalHttpsPolicy(),
+			timeoutMs: DEFAULT_TIMEOUT_MS,
+			maxRedirects: DEFAULT_MAX_REDIRECTS,
+			externalOnly: true,
+		};
+	},
+	httpOrHttpsPermissive(): SafeFetchProfile {
+		return {
+			urlPolicy: createHttpOrHttpsPolicy(),
+			timeoutMs: DEFAULT_TIMEOUT_MS,
+			maxRedirects: DEFAULT_MAX_REDIRECTS,
+			externalOnly: false,
+		};
+	},
+	streamableProxy(): SafeFetchProfile {
+		return {
+			urlPolicy: createHttpOrHttpsPolicy(),
+			timeoutMs: 0,
+			maxRedirects: DEFAULT_MAX_REDIRECTS,
+			externalOnly: false,
+		};
+	},
+	hfHub(): SafeFetchProfile {
+		return {
+			urlPolicy: createHuggingFaceHubPolicy(),
+			timeoutMs: DEFAULT_TIMEOUT_MS,
+			maxRedirects: DEFAULT_MAX_REDIRECTS,
+			externalOnly: true,
+		};
+	},
+	hfDocs(): SafeFetchProfile {
+		return {
+			urlPolicy: createHfDocsPolicy(),
+			timeoutMs: DEFAULT_TIMEOUT_MS,
+			maxRedirects: 5,
+			externalOnly: true,
+		};
+	},
+	localhostHttp(): SafeFetchProfile {
+		return {
+			urlPolicy: createLocalhostHttpPolicy(),
+			timeoutMs: DEFAULT_TIMEOUT_MS,
+			maxRedirects: 2,
+			externalOnly: false,
+		};
+	},
+	gradioSchemaHost(hostname: string): SafeFetchProfile {
+		return {
+			urlPolicy: createGradioSchemaHostPolicy(hostname),
+			timeoutMs: 10_000,
+			maxRedirects: 2,
+			externalOnly: !isLocalhostHostname(hostname),
+		};
+	},
+	gradioMcpHost(
+		hostname: string,
+		allowedProtocol: UrlProtocol
+	): SafeFetchProfile {
+		return {
+			urlPolicy: createGradioMcpHostPolicy(hostname, allowedProtocol),
+			timeoutMs: 0,
+			maxRedirects: 0,
+			externalOnly: !isLocalhostHostname(hostname) && process.env.NODE_ENV !== 'test',
+		};
+	},
+};

package/src/network/index.ts

@@ -0,0 +1,4 @@
+export * from './url-policy.js';
+export * from './ip-policy.js';
+export * from './safe-fetch.js';
+export * from './fetch-profile.js';

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { assertExternalAddress, isIpInternalOrReserved } from './ip-policy.js';
+
+describe('ip-policy', () => {
+	it('classifies internal/reserved IPv4 ranges', () => {
+		expect(isIpInternalOrReserved('127.0.0.1')).toBe(true);
+		expect(isIpInternalOrReserved('10.1.2.3')).toBe(true);
+		expect(isIpInternalOrReserved('172.20.10.2')).toBe(true);
+		expect(isIpInternalOrReserved('192.168.1.1')).toBe(true);
+		expect(isIpInternalOrReserved('8.8.8.8')).toBe(false);
+	});
+
+	it('classifies internal/reserved IPv6 ranges', () => {
+		expect(isIpInternalOrReserved('::1')).toBe(true);
+		expect(isIpInternalOrReserved('fc00::1')).toBe(true);
+		expect(isIpInternalOrReserved('fe80::1')).toBe(true);
+		expect(isIpInternalOrReserved('2001:db8::1')).toBe(true);
+		expect(isIpInternalOrReserved('2607:f8b0:4005:80a::200e')).toBe(false);
+	});
+
+	it('blocks internal literal addresses in assertExternalAddress', async () => {
+		await expect(assertExternalAddress('127.0.0.1')).rejects.toThrow('Blocked internal or reserved address');
+		await expect(assertExternalAddress('::1')).rejects.toThrow('Blocked internal or reserved address');
+	});
+
+	it('allows external literal addresses in assertExternalAddress', async () => {
+		await expect(assertExternalAddress('8.8.8.8')).resolves.toBeUndefined();
+	});
+});

package/src/network/ip-policy.ts

@@ -0,0 +1,206 @@
+export interface ExternalAddressOptions {
+	allowDnsRebindMitigation?: boolean;
+}
+
+function normalizeIpLiteral(host: string): string {
+	if (host.startsWith('[') && host.endsWith(']')) {
+		return host.slice(1, -1);
+	}
+	return host;
+}
+
+function parseIpv4ToInt(ip: string): number {
+	const parts = ip.split('.').map((part) => Number.parseInt(part, 10));
+	if (parts.length !== 4 || parts.some((part) => Number.isNaN(part) || part < 0 || part > 255)) {
+		throw new Error(`Invalid IPv4 address: ${ip}`);
+	}
+
+	return parts.reduce((acc, part) => acc * 256 + part, 0);
+}
+
+function ipv4InRange(ipValue: number, start: string, end: string): boolean {
+	const startValue = parseIpv4ToInt(start);
+	const endValue = parseIpv4ToInt(end);
+	return ipValue >= startValue && ipValue <= endValue;
+}
+
+function isIpv4InternalOrReserved(ip: string): boolean {
+	const value = parseIpv4ToInt(ip);
+
+	return (
+		ipv4InRange(value, '0.0.0.0', '0.255.255.255') ||
+		ipv4InRange(value, '10.0.0.0', '10.255.255.255') ||
+		ipv4InRange(value, '100.64.0.0', '100.127.255.255') ||
+		ipv4InRange(value, '127.0.0.0', '127.255.255.255') ||
+		ipv4InRange(value, '169.254.0.0', '169.254.255.255') ||
+		ipv4InRange(value, '172.16.0.0', '172.31.255.255') ||
+		ipv4InRange(value, '192.0.0.0', '192.0.0.255') ||
+		ipv4InRange(value, '192.0.2.0', '192.0.2.255') ||
+		ipv4InRange(value, '192.88.99.0', '192.88.99.255') ||
+		ipv4InRange(value, '192.168.0.0', '192.168.255.255') ||
+		ipv4InRange(value, '198.18.0.0', '198.19.255.255') ||
+		ipv4InRange(value, '198.51.100.0', '198.51.100.255') ||
+		ipv4InRange(value, '203.0.113.0', '203.0.113.255') ||
+		ipv4InRange(value, '224.0.0.0', '239.255.255.255') ||
+		ipv4InRange(value, '240.0.0.0', '255.255.255.255')
+	);
+}
+
+function parseIpv6ToBigInt(ip: string): bigint {
+	const zoneIndex = ip.indexOf('%');
+	const zoneStripped = zoneIndex >= 0 ? ip.slice(0, zoneIndex) : ip;
+
+	let working = zoneStripped;
+	if (working.includes('.')) {
+		const lastColon = working.lastIndexOf(':');
+		if (lastColon < 0) {
+			throw new Error(`Invalid IPv6 address: ${ip}`);
+		}
+		const ipv4Part = working.slice(lastColon + 1);
+		const ipv4Value = parseIpv4ToInt(ipv4Part);
+		const high = ((ipv4Value >>> 16) & 0xffff).toString(16);
+		const low = (ipv4Value & 0xffff).toString(16);
+		working = `${working.slice(0, lastColon)}:${high}:${low}`;
+	}
+
+	const split = working.split('::');
+	if (split.length > 2) {
+		throw new Error(`Invalid IPv6 address: ${ip}`);
+	}
+
+	const left = split[0] ? split[0].split(':').filter(Boolean) : [];
+	const right = split[1] ? split[1].split(':').filter(Boolean) : [];
+	const missingCount = 8 - (left.length + right.length);
+
+	if (split.length === 1 && missingCount !== 0) {
+		throw new Error(`Invalid IPv6 address: ${ip}`);
+	}
+
+	if (missingCount < 0) {
+		throw new Error(`Invalid IPv6 address: ${ip}`);
+	}
+
+	const full = [...left, ...Array.from({ length: missingCount }, () => '0'), ...right];
+	if (full.length !== 8) {
+		throw new Error(`Invalid IPv6 address: ${ip}`);
+	}
+
+	let value = 0n;
+	for (const part of full) {
+		const segment = Number.parseInt(part, 16);
+		if (Number.isNaN(segment) || segment < 0 || segment > 0xffff) {
+			throw new Error(`Invalid IPv6 address: ${ip}`);
+		}
+		value = (value << 16n) + BigInt(segment);
+	}
+
+	return value;
+}
+
+function isIpv6InCidr(ipValue: bigint, prefixValue: bigint, prefixLength: number): boolean {
+	const hostBits = 128n - BigInt(prefixLength);
+	const mask = ((1n << BigInt(prefixLength)) - 1n) << hostBits;
+	return (ipValue & mask) === (prefixValue & mask);
+}
+
+function isIpv6InternalOrReserved(ip: string): boolean {
+	const value = parseIpv6ToBigInt(ip);
+
+	if (value === 0n || value === 1n) {
+		return true;
+	}
+
+	// IPv4-mapped IPv6 ::ffff:a.b.c.d
+	if (value >> 32n === 0xffffn) {
+		const ipv4Value = Number(value & 0xffffffffn);
+		const octet1 = (ipv4Value >>> 24) & 0xff;
+		const octet2 = (ipv4Value >>> 16) & 0xff;
+		const octet3 = (ipv4Value >>> 8) & 0xff;
+		const octet4 = ipv4Value & 0xff;
+		return isIpv4InternalOrReserved(
+			`${octet1.toString()}.${octet2.toString()}.${octet3.toString()}.${octet4.toString()}`
+		);
+	}
+
+	return (
+		isIpv6InCidr(value, 0xfc00n << 112n, 7) || // Unique local
+		isIpv6InCidr(value, 0xfe80n << 112n, 10) || // Link-local
+		isIpv6InCidr(value, 0xff00n << 112n, 8) || // Multicast
+		isIpv6InCidr(value, 0x20010db8n << 96n, 32) || // Documentation
+		isIpv6InCidr(value, 0x20010010n << 96n, 28) // ORCHID
+	);
+}
+
+export function isIpInternalOrReserved(ip: string): boolean {
+	const normalizedIp = normalizeIpLiteral(ip);
+	const ipVersion = detectIpVersion(normalizedIp);
+	if (ipVersion === 0) {
+		throw new Error(`Invalid IP address: ${ip}`);
+	}
+
+	if (ipVersion === 4) {
+		return isIpv4InternalOrReserved(normalizedIp);
+	}
+
+	return isIpv6InternalOrReserved(normalizedIp);
+}
+
+async function lookupAll(hostname: string): Promise<string[]> {
+	const { lookup } = await import('node:dns/promises');
+	const results = await lookup(hostname, { all: true, verbatim: true });
+	return results.map((entry) => entry.address);
+}
+
+function detectIpVersion(candidate: string): 0 | 4 | 6 {
+	try {
+		parseIpv4ToInt(candidate);
+		return 4;
+	} catch {
+		// continue to ipv6 parsing
+	}
+
+	try {
+		parseIpv6ToBigInt(candidate);
+		return 6;
+	} catch {
+		return 0;
+	}
+}
+
+export async function assertExternalAddress(hostname: string, options: ExternalAddressOptions = {}): Promise<void> {
+	const { allowDnsRebindMitigation = true } = options;
+	const normalized = hostname.trim().replace(/\.+$/, '');
+
+	if (!normalized) {
+		throw new Error('Hostname is required for external address check');
+	}
+
+	const ipLiteral = normalizeIpLiteral(normalized);
+	const ipVersion = detectIpVersion(ipLiteral);
+	if (ipVersion !== 0) {
+		if (isIpInternalOrReserved(ipLiteral)) {
+			throw new Error(`Blocked internal or reserved address: ${ipLiteral}`);
+		}
+		return;
+	}
+
+	const firstLookup = await lookupAll(normalized);
+	if (firstLookup.length === 0) {
+		throw new Error(`No DNS records found for hostname: ${normalized}`);
+	}
+
+	for (const address of firstLookup) {
+		if (isIpInternalOrReserved(address)) {
+			throw new Error(`Blocked internal or reserved address for hostname ${normalized}: ${address}`);
+		}
+	}
+
+	if (allowDnsRebindMitigation) {
+		const secondLookup = await lookupAll(normalized);
+		for (const address of secondLookup) {
+			if (isIpInternalOrReserved(address)) {
+				throw new Error(`Blocked internal or reserved address for hostname ${normalized}: ${address}`);
+			}
+		}
+	}
+}

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');
+	});
+});