dsh-web-fetch-enhanced 0.0.3 → 0.0.5

package/README.en.md

@@ -29,7 +29,14 @@ 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;
+- **Dynamic system prompt alignment** — automatically injects explicit authorization guidance into the system prompt when non-public allowlists are configured, eliminating LLM refusal hallucinations when fetching authorized private destinations.
+
+## Compatibility & Support Policy
+
+- **Minimum Supported DSH Version**: `0.1.5-rc.2`
+- **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,14 @@ 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.5-rc.2`
+- **版本支持策略**：本插件**仅对 DeepSeek Harness 的 RC（Release Candidate）候选发布版本及后续稳定正式版提供支持**。由于 Alpha 或开发快照版本更迭频繁且缺乏稳定的 API 保证，本插件不再对 Alpha 等非 RC 阶段版本进行维护与适配。
 
 ## 快速开始
 

package/lib/index.js

@@ -4,6 +4,7 @@ import ipaddr from "ipaddr.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 import { deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
 import { lookup } from "node:dns/promises";
+import { proxyRouteFor } from "@deepseek-ai/dsh-http-proxy";
 //#region lib/types/address-policy.js
 /**
 * Immutable address policy. Public unicast remains allowed. A non-public address
@@ -39,6 +40,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 +223,16 @@ function embeddedIpv4Address(bytes, prefixLength) {
 	const beforeReservedOctet = 8 - prefixBytes;
 	return [...bytes.slice(prefixBytes, prefixBytes + beforeReservedOctet), ...bytes.slice(9, 13 - beforeReservedOctet)].join(".");
 }
+/**
+* Default proxy route resolver: resolves proxy route via @deepseek-ai/dsh-http-proxy.
+*/
+function defaultProxyRoute(url) {
+	const route = proxyRouteFor(url);
+	return route.proxied ? {
+		proxied: true,
+		dispatcher: route.dispatcher
+	} : { 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 +258,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 +419,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 +483,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);
@@ -573,8 +623,18 @@ const Config = z.object({
 	maxRedirects: z.number().default(5),
 	userAgent: z.string().default(DEFAULT_USER_AGENT)
 });
+/** Build prompt guidance copy informing the model of authorized non-public destinations. */
+function formatAllowlistPrompt(config) {
+	const cidrs = config.allowCidrs ?? [];
+	const hostnames = config.allowHostnames ?? [];
+	if (cidrs.length === 0 && hostnames.length === 0) return "";
+	const items = [];
+	if (cidrs.length > 0) items.push(`CIDRs: ${cidrs.join(", ")}`);
+	if (hostnames.length > 0) items.push(`hostnames: ${hostnames.join(", ")}`);
+	return `The operator has explicitly authorized web_fetch access to the following non-public destinations: [${items.join("; ")}]. You can safely fetch these endpoints.`;
+}
 /** 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 +652,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;
@@ -609,7 +669,9 @@ function apply(ctx, config) {
 				setSource: (source) => {
 					current = source;
 				},
-				onChange: () => {},
+				onChange: () => {
+					ctx.emit("system-prompt/change");
+				},
 				validate: (value) => {
 					if (resolveConfig(value).providerId !== providerId) throw new Error("web-fetch-enhanced: providerId cannot be changed through live settings");
 					createProvider(value);
@@ -628,6 +690,14 @@ function apply(ctx, config) {
 		settingsCtx.effect(() => () => {
 			if (isUnloading(ctx)) return;
 			current = () => config;
+			ctx.emit("system-prompt/change");
+		});
+	});
+	ctx.inject(["systemPrompt"], (promptCtx) => {
+		promptCtx.systemPrompt.section({
+			name: "web-fetch-enhanced:allowlist",
+			order: 2105,
+			text: () => formatAllowlistPrompt(current())
 		});
 	});
 	const dynamicProvider = {
@@ -665,4 +735,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, formatAllowlistPrompt, 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/client/AllowlistCard.d.ts

@@ -1,4 +1,4 @@
-import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { LocaleKey } from './locales.ts';
 export interface AllowlistSettings {
     allowCidrs?: string[];

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. */
@@ -38,8 +39,28 @@ export interface Config {
     userAgent?: string;
 }
 export declare const Config: z<Config>;
+interface SystemPromptSeam {
+    section(section: {
+        name: string;
+        order: number;
+        text: string | ((context?: unknown) => string);
+    }): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        systemPrompt?: SystemPromptSeam;
+    }
+    interface Events {
+        'system-prompt/change'(): void;
+    }
+}
+/** Build prompt guidance copy informing the model of authorized non-public destinations. */
+export declare function formatAllowlistPrompt(config: Config): string;
 /** 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,28 @@ 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: resolves proxy route via @deepseek-ai/dsh-http-proxy.
+ */
+export declare function defaultProxyRoute(url: URL): 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.5",
   "description": "Configurable non-public address allowlists for DeepSeek Harness web_fetch",
   "type": "module",
   "main": "./lib/index.js",
@@ -65,19 +65,20 @@
     "access": "public"
   },
   "engines": {
-    "node": "^22.19.0 || >=24.0.0"
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.1.5-rc.2"
   },
   "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.5-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.5-rc.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1 || ^3.18.2",
@@ -85,16 +86,16 @@
     "undici": "^8.10.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-web": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.5-rc.2",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.19.13",
     "@types/react": "~18.3.1",