dsh-web-fetch-enhanced 0.0.3 → 0.0.4

package/README.en.md

@@ -29,7 +29,13 @@ With an empty CIDR allowlist, the security boundary remains equivalent to the na
 - **Redirect revalidation** — same-origin redirects are resolved, validated, and pinned again at every hop;
 - **Anonymous bounded GET requests** — no cookies, Authorization header, or URL credentials;
 - **Resource limits** — URL length, response bytes, decoded characters, redirects, and time are bounded;
-- **IPv4 and IPv6 coverage** — including IPv4-mapped IPv6 and active DNS64 / NAT64 checks.
+- **IPv4 and IPv6 coverage** — including IPv4-mapped IPv6 and active DNS64 / NAT64 checks;
+- **Outbound HTTP proxy alignment** — seamlessly respects DSH global proxy routes (`HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY`), while refusing unvalidated private IP literals from bypassing address checks through the proxy.
+
+## Compatibility & Support Policy
+
+- **Minimum Supported DSH Version**: `0.1.2-rc.1`
+- **Support Policy**: This plugin **only supports DeepSeek Harness RC (Release Candidate) releases and future stable releases**. Compatibility is not maintained for rapid-moving Alpha or development snapshot versions.
 
 ## Quick start
 

package/README.md

@@ -29,7 +29,13 @@ DeepSeek Harness 原生 HTTP provider 默认拒绝所有非公网地址，这是
 - **重定向逐跳复核**：仅跟随同源重定向，并在每一跳重新解析、校验和固定地址；
 - **受限匿名请求**：只发送无 Cookie、无 Authorization、无 URL 凭据的 GET 请求；
 - **完整资源上限**：限制 URL、响应字节、解码字符、重定向次数和超时时间；
-- **IPv4 / IPv6 防护**：覆盖 IPv4-mapped IPv6 与活动 DNS64 / NAT64 目标检查。
+- **IPv4 / IPv6 防护**：覆盖 IPv4-mapped IPv6 与活动 DNS64 / NAT64 目标检查；
+- **全局出站代理协同**：无缝对接 DSH 全局 HTTP 代理路由（`HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY`），同时严格禁止非公网 IP 字面量越权走代理，杜绝内网 SSRF 风险。
+
+## 版本兼容性与支持策略
+
+- **最低支持的 DSH 版本**：`0.1.2-rc.1`
+- **版本支持策略**：本插件**仅对 DeepSeek Harness 的 RC（Release Candidate）候选发布版本及后续稳定正式版提供支持**。由于 Alpha 或开发快照版本更迭频繁且缺乏稳定的 API 保证，本插件不再对 Alpha 等非 RC 阶段版本进行维护与适配。
 
 ## 快速开始
 

package/lib/index.js

@@ -39,6 +39,22 @@ var AddressPolicy = class {
 		});
 	}
 };
+/** Return true only for globally reachable unicast, matching the native provider. */
+function isPublicIpAddress(input) {
+	const parsed = parseAddress(input);
+	return parsed !== void 0 && isPublicAddress(parsed);
+}
+/**
+* Whether a hostname is an IP literal that resolves to a non-public address.
+*
+* A proxied hop skips address resolution because the proxy resolves the origin,
+* but an IP literal needs no resolution. Handing an unverified non-public literal
+* to a proxy would risk reaching loopback or private services (SSRF).
+*/
+function isNonPublicIpLiteral(hostname) {
+	const unbracketed = stripIpv6Brackets(hostname);
+	return isIP(unbracketed) !== 0 && !isPublicIpAddress(unbracketed);
+}
 function isPublicAddress(address) {
 	return address.range() === "unicast";
 }
@@ -206,6 +222,22 @@ function embeddedIpv4Address(bytes, prefixLength) {
 	const beforeReservedOctet = 8 - prefixBytes;
 	return [...bytes.slice(prefixBytes, prefixBytes + beforeReservedOctet), ...bytes.slice(9, 13 - beforeReservedOctet)].join(".");
 }
+/**
+* Default proxy route resolver: safely resolves proxy route via @deepseek-ai/dsh-http-proxy if available,
+* gracefully degrading to direct routing if the module is absent.
+*/
+async function defaultProxyRoute(url) {
+	try {
+		const { proxyRouteFor } = await import("@deepseek-ai/dsh-http-proxy");
+		const route = proxyRouteFor(url);
+		return route.proxied ? {
+			proxied: true,
+			dispatcher: route.dispatcher
+		} : { proxied: false };
+	} catch {
+		return { proxied: false };
+	}
+}
 /** Fetch while preserving the URL hostname for Host and TLS SNI. */
 async function requestPinned(url, addresses, headers, signal) {
 	const { Agent, fetch } = await import("undici");
@@ -231,6 +263,24 @@ async function requestPinned(url, addresses, headers, signal) {
 		throw error;
 	}
 }
+/**
+* Fetch through the dispatcher the proxy policy already installed, letting the proxy resolve the origin.
+* No address set is pinned because the proxy performs the lookup. The dispatcher is process-wide,
+* so connections are pooled and the caller does not close it.
+*/
+async function requestVia(dispatcher, url, headers, signal) {
+	const { fetch } = await import("undici");
+	return {
+		response: await fetch(url, {
+			method: "GET",
+			redirect: "manual",
+			headers,
+			signal,
+			dispatcher
+		}),
+		close: () => Promise.resolve()
+	};
+}
 /** Create a Node lookup callback that returns only the prevalidated answer set. */
 function createPinnedLookup(addresses) {
 	return (hostname, options, callback) => {
@@ -374,10 +424,12 @@ var EnhancedHttpFetchProvider = class {
 	id;
 	limits;
 	resolveAddresses;
-	constructor(id, limits, resolveAddresses) {
+	resolveProxy;
+	constructor(id, limits, resolveAddresses, resolveProxy = defaultProxyRoute) {
 		this.id = id;
 		this.limits = limits;
 		this.resolveAddresses = resolveAddresses;
+		this.resolveProxy = resolveProxy;
 	}
 	available() {
 		return true;
@@ -436,11 +488,14 @@ var EnhancedHttpFetchProvider = class {
 		}
 	}
 	async requestOnce(url, signal) {
+		const headers = {
+			"user-agent": this.limits.userAgent,
+			"accept": "text/html,application/xhtml+xml,text/*;q=0.9,application/json;q=0.8"
+		};
 		try {
-			return await requestPinned(url, await this.resolveAddresses(url.hostname, signal), {
-				"user-agent": this.limits.userAgent,
-				"accept": "text/html,application/xhtml+xml,text/*;q=0.9,application/json;q=0.8"
-			}, signal);
+			const route = await this.resolveProxy(url);
+			if (route.proxied && route.dispatcher && !isNonPublicIpLiteral(url.hostname)) return await requestVia(route.dispatcher, url, headers, signal);
+			return await requestPinned(url, await this.resolveAddresses(url.hostname, signal), headers, signal);
 		} catch (error) {
 			if (error instanceof WebError) throw error;
 			throw translateAbortOrNetwork(error, signal);
@@ -574,7 +629,7 @@ const Config = z.object({
 	userAgent: z.string().default(DEFAULT_USER_AGENT)
 });
 /** Construct the provider without mounting it, useful for tests and custom compositions. */
-function createProvider(config = {}) {
+function createProvider(config = {}, proxyResolver) {
 	const resolved = resolveConfig(config);
 	assertProviderId(resolved.providerId);
 	assertPositiveFinite("maxResponseBytes", resolved.maxResponseBytes);
@@ -592,7 +647,7 @@ function createProvider(config = {}) {
 		maxRedirects: resolved.maxRedirects,
 		userAgent: resolved.userAgent
 	};
-	return new EnhancedHttpFetchProvider(resolved.providerId, limits, createAllowlistResolver(policy));
+	return new EnhancedHttpFetchProvider(resolved.providerId, limits, createAllowlistResolver(policy), proxyResolver);
 }
 function isUnloading(ctx) {
 	const state = ctx.fiber?.state;
@@ -665,4 +720,4 @@ function assertNonNegativeInteger(field, value) {
 	if (!Number.isInteger(value) || value < 0) throw new Error(`web-fetch-enhanced: ${field} must be a non-negative integer`);
 }
 //#endregion
-export { Config, DEFAULT_PROVIDER_ID, DEFAULT_USER_AGENT, SETTINGS_NAMESPACE, apply, createProvider, inject, name };
+export { Config, DEFAULT_PROVIDER_ID, DEFAULT_USER_AGENT, SETTINGS_NAMESPACE, apply, createProvider, defaultProxyRoute, inject, isNonPublicIpLiteral, name };

package/lib/types/address-policy.d.ts

@@ -19,6 +19,14 @@ export declare class AddressPolicy {
 }
 /** Return true only for globally reachable unicast, matching the native provider. */
 export declare function isPublicIpAddress(input: string): boolean;
+/**
+ * Whether a hostname is an IP literal that resolves to a non-public address.
+ *
+ * A proxied hop skips address resolution because the proxy resolves the origin,
+ * but an IP literal needs no resolution. Handing an unverified non-public literal
+ * to a proxy would risk reaching loopback or private services (SSRF).
+ */
+export declare function isNonPublicIpLiteral(hostname: string): boolean;
 /** WHATWG URL retains brackets around IPv6 hostnames; IP parsers do not. */
 export declare function stripIpv6Brackets(hostname: string): string;
 //# sourceMappingURL=address-policy.d.ts.map

package/lib/types/index.d.ts

@@ -8,6 +8,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import { EnhancedHttpFetchProvider } from './provider.ts';
+import type { ProxyRouteResolver } from './resolver.ts';
 /** Explicit product User-Agent used by default. */
 export declare const DEFAULT_USER_AGENT = "dsh-web-fetch-enhanced/0.1.0";
 /** Default provider id; select it in the dsh-web row with fetchProvider. */
@@ -39,7 +40,10 @@ export interface Config {
 }
 export declare const Config: z<Config>;
 /** Construct the provider without mounting it, useful for tests and custom compositions. */
-export declare function createProvider(config?: Config): EnhancedHttpFetchProvider;
+export declare function createProvider(config?: Config, proxyResolver?: ProxyRouteResolver): EnhancedHttpFetchProvider;
+export { isNonPublicIpLiteral } from './address-policy.ts';
+export type { ProxyRouteResolver, ProxyRouteResult } from './resolver.ts';
+export { defaultProxyRoute } from './resolver.ts';
 /** Register the enhanced fetch provider and its live Web Profile settings section. */
 export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/provider.d.ts

@@ -1,5 +1,5 @@
 import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@deepseek-ai/dsh-web';
-import type { FetchResolver } from './resolver.ts';
+import type { FetchResolver, ProxyRouteResolver } from './resolver.ts';
 /** Resolved transport and response limits. */
 export interface HttpFetchLimits {
     maxResponseBytes: number;
@@ -13,7 +13,8 @@ export declare class EnhancedHttpFetchProvider implements WebFetchProvider {
     readonly id: string;
     private readonly limits;
     private readonly resolveAddresses;
-    constructor(id: string, limits: HttpFetchLimits, resolveAddresses: FetchResolver);
+    private readonly resolveProxy;
+    constructor(id: string, limits: HttpFetchLimits, resolveAddresses: FetchResolver, resolveProxy?: ProxyRouteResolver);
     available(): boolean;
     fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
     private followAndRead;

package/lib/types/resolver.d.ts

@@ -1,5 +1,5 @@
 import type { LookupAddress, LookupOptions } from 'node:dns';
-import type { Response } from 'undici';
+import type { Dispatcher, Response } from 'undici';
 import { AddressPolicy } from './address-policy.ts';
 /** DNS resolver shape used by Node and by focused tests. */
 export type AddressResolver = (hostname: string, options: {
@@ -22,8 +22,29 @@ export interface PinnedResponse {
 export declare function createAllowlistResolver(policy: AddressPolicy, resolver?: AddressResolver): FetchResolver;
 /** Resolve once and reject the complete answer set when any entry is disallowed. */
 export declare function resolveAllowedAddresses(hostname: string, signal: AbortSignal, policy: AddressPolicy, resolver?: AddressResolver): Promise<ValidatedAddress[]>;
+/** Result of resolving a URL through the outbound proxy policy. */
+export type ProxyRouteResult = {
+    readonly proxied: true;
+    readonly dispatcher: Dispatcher;
+} | {
+    readonly proxied: false;
+    readonly dispatcher?: undefined;
+};
+/** Function deciding whether a URL should be routed through an outbound proxy. */
+export type ProxyRouteResolver = (url: URL) => Promise<ProxyRouteResult> | ProxyRouteResult;
+/**
+ * Default proxy route resolver: safely resolves proxy route via @deepseek-ai/dsh-http-proxy if available,
+ * gracefully degrading to direct routing if the module is absent.
+ */
+export declare function defaultProxyRoute(url: URL): Promise<ProxyRouteResult>;
 /** Fetch while preserving the URL hostname for Host and TLS SNI. */
 export declare function requestPinned(url: URL, addresses: readonly ValidatedAddress[], headers: Record<string, string>, signal: AbortSignal): Promise<PinnedResponse>;
+/**
+ * Fetch through the dispatcher the proxy policy already installed, letting the proxy resolve the origin.
+ * No address set is pinned because the proxy performs the lookup. The dispatcher is process-wide,
+ * so connections are pooled and the caller does not close it.
+ */
+export declare function requestVia(dispatcher: Dispatcher, url: URL, headers: Record<string, string>, signal: AbortSignal): Promise<PinnedResponse>;
 type LookupCallback = (error: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void;
 /** Create a Node lookup callback that returns only the prevalidated answer set. */
 export declare function createPinnedLookup(addresses: readonly ValidatedAddress[]): (hostname: string, options: LookupOptions, callback: LookupCallback) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-web-fetch-enhanced",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Configurable non-public address allowlists for DeepSeek Harness web_fetch",
   "type": "module",
   "main": "./lib/index.js",
@@ -69,15 +69,21 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1 || ^4.0.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-web": "^0.1.1-rc.2 || ^0.1.2-alpha.1 || ^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-web": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.2-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-http-proxy": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1 || ^3.18.2",