dsh-web-fetch-enhanced 0.0.2 → 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
 
@@ -178,7 +184,7 @@ Most users only need the two allowlists exposed in DSH Web. Manage other values
 | `maxRedirects` | `5` | Maximum same-origin redirect hops; `0` disables following |
 | `userAgent` | `dsh-web-fetch-enhanced/0.1.0` | User-Agent sent with each request |
 
-The default bundle uses the separate `http-enhanced` provider ID and leaves the native `http` provider installed. For manual composition or drop-in replacement, see:
+The default bundle uses the separate `http-enhanced` provider ID and explicitly disables the native `web-fetch-http` provider to avoid `WEB_PROVIDER_AMBIGUOUS` when subsequent Web plugins (such as search plugins) overwrite `id: web` configuration and unpin `fetchProvider`. For manual composition or drop-in replacement, see:
 
 - [coexisting provider example](examples/coexist.cordis.yml)
 - [drop-in replacement example](examples/drop-in.cordis.yml)

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 阶段版本进行维护与适配。
 
 ## 快速开始
 
@@ -178,7 +184,7 @@ wiki.corp.example
 | `maxRedirects` | `5` | 同源重定向最大跳数；`0` 表示不跟随 |
 | `userAgent` | `dsh-web-fetch-enhanced/0.1.0` | 每个请求使用的 User-Agent |
 
-默认安装采用独立的 `http-enhanced` provider ID，并保留原生 `http` provider。需要手动组合或 drop-in 替换时，参考：
+默认安装（通过 bundle `cordis.patch.yml`）采用独立的 `http-enhanced` provider ID，并显式禁用原生的 `web-fetch-http`，以避免后续其他 Web 插件（如 search 插件）覆盖 `id: web` 的 config 时因 `fetchProvider` 变成未指定而触发 `WEB_PROVIDER_AMBIGUOUS`。需要自定义组合或 drop-in 替换时，参考：
 
 - [独立 provider 示例](examples/coexist.cordis.yml)
 - [drop-in 替换示例](examples/drop-in.cordis.yml)

package/cordis.patch.yml

@@ -1,9 +1,10 @@
 # Optional Profile Bundle: select the enhanced HTTP fetch provider on the Host plane.
-# This layer is applied after @deepseek-ai/dsh-base. A patch replaces a row's
-# entire config, so both WebRuntime selector fields are restated here.
+# Disable the native HTTP fetch provider to avoid WEB_PROVIDER_AMBIGUOUS when fetchProvider is unpinned by later bundles.
+- id: web-fetch-http
+  disabled: true
+
 - id: web
   config:
-    searchProvider: deepseek-official
     fetchProvider: http-enhanced
 
 - insert:

package/docs/design.zh-CN.md

@@ -47,13 +47,13 @@ flowchart LR
 <code>ctx.web</code> 的选择是 ID 驱动而不是注册顺序驱动：
 
 - 配置 <code>fetchProvider: http-enhanced</code> 时只选择本插件默认 ID；
-- 保留原生 <code>http</code> provider 不会产生歧义，因为选择已显式固定；
+- 默认 bundle 会在 Profile 中显式禁用原生的 <code>web-fetch-http</code>，从而在多 Web 插件（如 search 插件）覆盖 <code>id: web</code> config 导致 <code>fetchProvider</code> 未固定时，系统只存在唯一的可用 fetch provider，避免 <code>WEB_PROVIDER_AMBIGUOUS</code>；
 - 未配置 ID 且存在多个可用 provider 时会报 <code>WEB_PROVIDER_AMBIGUOUS</code>；
 - 两个 provider 注册相同 ID 会立即报 <code>WEB_DUPLICATE_PROVIDER</code>。
 
 所以“覆盖原生”有两种明确模式：
 
-1. 推荐模式：本插件使用 <code>http-enhanced</code>，修改现有 web 行的 <code>fetchProvider</code>；
+1. 推荐模式：本插件使用 <code>http-enhanced</code>，修改现有 web 行的 <code>fetchProvider</code> 并禁用原生 <code>web-fetch-http</code>（由随包附带的 <code>cordis.patch.yml</code> 自动处理）；
 2. drop-in 模式：禁用原生 provider，本插件配置 <code>providerId: http</code>。
 
 不存在 last-wins 或自动 fallback。

package/examples/drop-in.cordis.yml

@@ -1,8 +1,6 @@
 # Profile user patch after installing the bundle, retaining fetchProvider: http.
-# A patch replaces a row's whole config, so both WebRuntime fields are restated.
 - id: web
   config:
-    searchProvider: deepseek-official
     fetchProvider: http
 
 # The native provider MUST be disabled to avoid duplicate provider id "http".

package/examples/manual.cordis.patch.yml

@@ -1,8 +1,10 @@
 # Manual Host overlay when the package is resolvable but its dsh.bundle layer
 # is not active. Bundle users should use coexist.cordis.yml instead.
+- id: web-fetch-http
+  disabled: true
+
 - id: web
   config:
-    searchProvider: deepseek-official
     fetchProvider: http-enhanced
 
 - insert:

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.2",
+  "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",