@llmindset/hf-mcp 0.3.2 → 0.3.4

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,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { assertExternalAddress, isIpInternalOrReserved } from './ip-policy.js';
+
+const { lookupMock } = vi.hoisted(() => ({
+	lookupMock: vi.fn(),
+}));
+
+vi.mock('node:dns/promises', () => ({
+	lookup: lookupMock,
+}));
+
+describe('ip-policy', () => {
+	afterEach(() => {
+		lookupMock.mockReset();
+		delete process.env.ALLOW_INTERNAL_ADDRESS_HOSTS;
+	});
+
+	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();
+	});
+
+	it('blocks hostnames resolving to internal addresses by default', async () => {
+		lookupMock.mockResolvedValue([{ address: '10.0.246.93' }]);
+
+		await expect(assertExternalAddress('huggingface.co')).rejects.toThrow(
+			'Blocked internal or reserved address for hostname huggingface.co: 10.0.246.93'
+		);
+	});
+
+	it('allows allowlisted hostnames to resolve to internal addresses', async () => {
+		process.env.ALLOW_INTERNAL_ADDRESS_HOSTS = 'huggingface.co,*.hf.space';
+		lookupMock.mockResolvedValue([{ address: '10.0.246.93' }]);
+
+		await expect(assertExternalAddress('huggingface.co')).resolves.toBeUndefined();
+		await expect(assertExternalAddress('demo.hf.space')).resolves.toBeUndefined();
+	});
+});

package/src/network/ip-policy.ts

@@ -0,0 +1,252 @@
+export interface ExternalAddressOptions {
+	allowDnsRebindMitigation?: boolean;
+}
+
+const INTERNAL_ADDRESS_HOST_ALLOWLIST_ENV = 'ALLOW_INTERNAL_ADDRESS_HOSTS';
+
+function normalizeHostname(hostname: string): string {
+	return hostname.trim().toLowerCase().replace(/\.+$/, '');
+}
+
+function getInternalAddressHostAllowlist(): string[] {
+	const raw = process.env[INTERNAL_ADDRESS_HOST_ALLOWLIST_ENV];
+	if (!raw) {
+		return [];
+	}
+
+	return raw
+		.split(',')
+		.map((entry) => normalizeHostname(entry))
+		.filter((entry) => entry.length > 0);
+}
+
+function hostnameMatchesPattern(hostname: string, pattern: string): boolean {
+	if (pattern.startsWith('*.')) {
+		const baseDomain = pattern.slice(2);
+		if (!baseDomain) {
+			return false;
+		}
+		return hostname === baseDomain || hostname.endsWith(`.${baseDomain}`);
+	}
+
+	return hostname === pattern;
+}
+
+function isInternalAddressAllowedForHostname(hostname: string): boolean {
+	const normalizedHostname = normalizeHostname(hostname);
+	if (!normalizedHostname) {
+		return false;
+	}
+
+	const allowlist = getInternalAddressHostAllowlist();
+	if (allowlist.length === 0) {
+		return false;
+	}
+
+	return allowlist.some((pattern) => hostnameMatchesPattern(normalizedHostname, pattern));
+}
+
+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 = normalizeHostname(hostname);
+
+	if (!normalized) {
+		throw new Error('Hostname is required for external address check');
+	}
+
+	const allowInternalAddress = isInternalAddressAllowedForHostname(normalized);
+
+	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) && !allowInternalAddress) {
+			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) && !allowInternalAddress) {
+				throw new Error(`Blocked internal or reserved address for hostname ${normalized}: ${address}`);
+			}
+		}
+	}
+}