@eddyskywalker/dsh-chatgpt-subscription 0.2.16 → 0.2.17

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- 修复开启系统代理的机器上 `web_fetch` 必然失败的问题：DSH 内置抓取 provider 在连接前解析、校验并固定目标地址，而代理工具（Clash/Mihomo 等）的 fake-ip DNS 会把域名解析成 `198.18.0.0/15` 里的保留地址（实测 `api.github.com` → `198.18.0.17`），于是每次调用都以 `WEB_BLOCKED_URL`（`resolves to a non-public IP address`）结束——代理根本没被用上。DSH 只在进程环境变量里读到代理时才走代理，看不到系统代理。现在只要插件配置了可用代理（系统代理自动检测或自定义代理），`web_fetch` 就改用本插件的抓取 provider：由代理解析源站，与 DSH 对“走代理的请求”采用的语义一致；未配置代理时仍由内置 provider 抓取，其解析与固定策略不变。
+- 抓取 provider 新增地址策略 `src/host/fetch-address-policy.ts`，保留内置 provider 安全边界中不需要 DNS 的那一半：URL 里写明的 IP 字面量只有全球可路由单播才放行（loopback、私网、链路本地、CGNAT、多播、保留地址、IPv6 转换与隧道前缀一律拒绝）；域名用本机解析器检查一次，落在私网（含 `localhost`、`127.0.0.1.nip.io` 这类）一律拒绝；只有代理的 fake-ip 答案被接受，本机解析不出的域名交给代理处理。与内置 provider 的差别是不再固定（pin）连接地址——fake-ip 环境下这一步无法成立，已在 README 的安全边界中写明。
+- 代理偏好在运行时变化（例如系统代理 ↔ 直连）会重新选择抓取后端；选择 ChatGPT 搜索来源时同时切换搜索与抓取的行为保持不变。
+- 新增 `test/fetch-address-policy.test.ts`（地址分类、fake-ip 识别、私网解析拒绝、解析失败放行），并扩充 `test/codex-fetch.test.ts`、`test/search-provider-switcher.test.ts`、`test/web-provider-lifecycle.test.ts` 覆盖抓取 provider 的拒绝路径与后端切换。
+
 ## 0.2.15 - 2026-09-11
 
 - 新增子代理模型授权守卫：DSH 的「Subagent」允许列表（`subagent-model-selection`）原本只在模型**显式**填写 `provider`/`model` 时生效，而委派调用不填路由时子代理会继承父级模型——于是 DeepSeek 会话里的子代理仍会在未授权模型上运行。插件现在在 Host 工具注册表上注册一个单调守卫（`ctx.tools.guard`），当调用会话（或最近的、记录了策略的祖先会话）带有允许列表时，任何生效路由不在此列表内的委派都会在子代理启动前被拒绝，拒绝理由里带上全部已授权路由，模型据此重试即可选中合规模型。

package/README.md

@@ -121,7 +121,9 @@ DSH 模型选择器应显示 **“Codex（ChatGPT 订阅）”**。6 Astra 与 G
 
 **设置 → Codex 订阅 → 网络代理** 同时控制 GPT 与 Antigravity（Gemini）的 Host 请求，可选择系统代理（自动检测）、自定义代理或直连。Gemini 模型生成、网页登录后的令牌交换、令牌刷新、账号信息、项目发现、配额与模型目录查询均使用此设置；修改后对后续请求生效，无需重启 DSH。浏览器中的 Google 授权页面使用浏览器自己的网络设置。
 
-**搜索与抓取来源** 同时切换 DSH 的搜索和网页抓取后端。选择 ChatGPT 来源后，网页由本插件在 Host 抓取，并使用上述网络代理设置；纯 TUN 模式可使用直连，流量由虚拟网卡接管。来源切换即时生效，DSH web 服务重载后会重新注册插件后端，并保留切回 DSH 默认来源所需的配置。选择 DSH 默认来源时，抓取仍遵循 DSH 自身的代理及非公网地址校验策略。
+**搜索与抓取来源** 切换 DSH 的搜索后端；网页抓取后端在有可用代理时自动改用本插件。选择 ChatGPT 来源后，网页由本插件在 Host 抓取，并使用上述网络代理设置；纯 TUN 模式可使用直连，流量由虚拟网卡接管。来源切换即时生效，DSH web 服务重载后会重新注册插件后端，并保留切回 DSH 默认来源所需的配置。
+
+**网页抓取后端（web_fetch）** DSH 内置抓取 provider 会先解析域名、校验并固定解析结果，而且只在进程环境变量里读到代理时才走代理——系统代理对它不可见。代理工具（Clash/Mihomo 等）常把域名解析成自己的 fake-ip 地址（默认 `198.18.0.0/15`），于是内置 provider 直接以 `WEB_BLOCKED_URL`（resolves to a non-public IP address）拒绝，代理根本没被用上。因此只要插件配置了可用代理（**网络代理** 选系统代理且检测到，或填写自定义代理），`web_fetch` 就改用本插件的 provider：由代理解析源站，与 DSH 对“走代理的请求”采用的语义一致；未配置代理时仍由 DSH 内置 provider 抓取，保留其解析与固定策略。若在纯 TUN 模式下把代理设为**直连**，内置 provider 会重新接管，此时可改回系统代理让插件接管抓取。
 
 卸载前建议先在设置页点击 **“注销”**，它会删除当前平台的凭据和 Host 内存中的额度缓存。
 
@@ -170,6 +172,7 @@ Antigravity 的 Gemini 用量以流结束时的上游累计计数为准，缓存
 - Windows token bundle 使用 CurrentUser DPAPI；明文只经过 Host 内存和 PowerShell stdin/stdout；
 - macOS token bundle 存入登录钥匙串，通过系统 `security` 命令读写；明文只经过 Host 内存和 `security` 命令行参数，Keychain 在本机加密保存；
 - Linux token bundle 原子写入当前用户私有文件并在读取时校验普通文件、所有者与 `0600` 权限，同时拒绝符号链接；该文件没有应用层加密，同 UID 进程、root、备份和磁盘快照仍可读取；
+- 本插件抓取 provider 的地址策略：URL 里直接写明的 IP 字面量只有在全球可路由单播时才放行（loopback、私网、链路本地、CGNAT、多播、保留地址、IPv6 转换与隧道前缀一律拒绝）；域名会先用本机解析器检查一次，解析结果落在私网时同样拒绝，只有代理的 fake-ip 地址（`198.18.0.0/15`）被接受——那正是本机代理声称拥有该域名的表现；本机解析不出的域名交给代理处理。与 DSH 内置 provider 的差别是不固定（pin）连接地址，因为 fake-ip 环境下这一步无法成立；
 - 所有平台的 token 都不会进入浏览器、`settings.yaml` 或日志；
 - 工具调用只有在参数是完整 JSON 对象时才产生可执行的 `block-end`；畸形参数终止本次生成；
 - 所有修改状态的路由只接受同源 JSON POST，并校验 `Origin` 与 `Host`。
@@ -212,6 +215,7 @@ npm pack --dry-run
 | 额度显示旧数据 | 设置页会保留最后成功值；等待 15 秒节流窗口后手动刷新 |
 | 429 | 插件遵守 `Retry-After`，不会高频轮询；模型请求由 DSH retry policy 有界重试 |
 | 模型不可用 | 检查 ChatGPT 套餐、workspace 权限与当前模型可用性 |
+| `web_fetch` 报 `resolves to a non-public IP address` | 机器启用了系统代理（fake-ip DNS），但插件没有可用代理可接管抓取：在 **设置 → Codex 订阅 → 网络代理** 选择系统代理（自动检测）或填写自定义代理 |
 | DPAPI 读取失败 | 确认 DSH 以创建凭据时的同一 Windows 用户运行；必要时清理凭据后重新登录 |
 | Linux 凭据存储不可用 | 确认凭据属于当前用户且权限为 `0600`，父目录权限为 `0700`；修复权限或注销后重新登录 |
 | Linux 上工具调用语法错误 | 确认 DSH 暴露的是 `bash`、`sh` 或 `shell`，并使用相应的 Bash/POSIX 语法与 `/` 路径 |

package/lib/index.js

@@ -3,6 +3,8 @@ import z from "@deepseek-ai/schemastery";
 import * as LlmModule from "@deepseek-ai/dsh-llm";
 import { HarnessError, LlmAdapter, LlmError, ProviderRequestId, ReasoningEffortId, attributionHeaders, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { WebError } from "@deepseek-ai/dsh-web";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
 import { createUserMessage } from "@deepseek-ai/dsh-llm/message";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
@@ -274,6 +276,225 @@ var CodexChatGptAdapter = class extends LlmAdapter {
 	}
 };
 //#endregion
+//#region src/host/fetch-address-policy.ts
+/**
+* Destination policy for this plugin's fetch provider.
+*
+* DSH's built-in provider resolves every destination and validates and pins the
+* address before it connects. That cannot work on a machine whose proxy answers
+* DNS with its own fake-ip range (`198.18.0.0/15` for Clash/Mihomo, the usual
+* companion of a system proxy): the hostname is ordinary, the answer is reserved
+* space, and every request is refused before the proxy that could have resolved
+* it is ever consulted. This provider exists for that machine, so it cannot
+* validate names the way the built-in one does.
+*
+* It keeps the half of the policy that needs no resolution — an address the URL
+* states outright is refused unless it is globally reachable unicast, because a
+* proxy on this machine must not become a path into loopback or a LAN — and it
+* also refuses a name this machine resolves into private space. Only the proxy's
+* own fake-ip answers are accepted, since that is what the proxy's name
+* resolution looks like from here; the URL hostname still reaches the proxy
+* intact, so the proxy decides where the name really goes.
+*
+* @module dsh-chatgpt-subscription/fetch-address-policy
+*/
+/**
+* Every IPv4 range a fetch may not target: "this network", private space,
+* carrier-grade NAT, loopback, link-local, IETF assignments, documentation,
+* the 6to4 relay anycast, the benchmarking range the mainstream proxy tools use
+* for fake-ip answers, multicast, and reserved space including the broadcast
+* address.
+*/
+const NON_PUBLIC_IPV4 = [
+	"0.0.0.0/8",
+	"10.0.0.0/8",
+	"100.64.0.0/10",
+	"127.0.0.0/8",
+	"169.254.0.0/16",
+	"172.16.0.0/12",
+	"192.0.0.0/24",
+	"192.0.2.0/24",
+	"192.88.99.0/24",
+	"192.168.0.0/16",
+	"198.18.0.0/15",
+	"198.51.100.0/24",
+	"203.0.113.0/24",
+	"224.0.0.0/4",
+	"240.0.0.0/4"
+];
+/** The fake-ip range the mainstream proxy tools hand out for the names they own. */
+const FAKE_IP_RANGE = "198.18.0.0/15";
+/**
+* Resolve one hostname to every address the local resolver returns, or to no
+* addresses when it cannot.
+*
+* A failure is not evidence of a local destination: the configured proxy
+* resolves the origin itself, so a name this machine cannot resolve must not
+* fail a request the proxy could have served.
+*
+* @param hostname - the URL hostname, without brackets.
+* @returns the resolved addresses, or an empty list when resolution failed.
+*/
+async function lookupHostAddresses(hostname) {
+	try {
+		return (await lookup(hostname, {
+			all: true,
+			verbatim: true
+		})).map((answer) => answer.address);
+	} catch {
+		return [];
+	}
+}
+/**
+* Whether a host is stated as an IP address rather than as a name.
+*
+* @param hostname - a URL hostname, bracketed or not.
+* @returns true when the host is an IPv4 or IPv6 literal.
+*/
+function isIpLiteral(hostname) {
+	return isIP(unbracket(hostname)) !== 0;
+}
+/**
+* Whether an address is one only a proxy's fake-ip resolver hands out. The IANA
+* benchmarking range carries no real host, so an answer inside it is this
+* machine's proxy claiming the name, not a private destination.
+*
+* @param address - a textual IPv4 (or IPv4-mapped IPv6) address.
+* @returns true when the address is inside the proxy fake-ip range.
+*/
+function isProxyFakeIpAddress(address) {
+	const value = ipv4Value(unbracket(address).replace(/^::ffff:/i, ""));
+	return value !== void 0 && inRange(value, FAKE_IP_RANGE);
+}
+/**
+* Whether an address is globally reachable unicast. IPv4-mapped IPv6 is
+* classified by the IPv4 address it embeds; every other IPv6 address is public
+* only inside `2000::/3`, which excludes loopback, unique-local, link-local,
+* multicast, and the transition and translation prefixes whose real destination
+* cannot be seen from the address alone.
+*
+* @param address - a textual IPv4 or IPv6 address, bracketed or not.
+* @returns true only for a public unicast destination.
+*/
+function isPublicIpAddress(address) {
+	const unbracketed = unbracket(address);
+	const family = isIP(unbracketed);
+	if (family === 4) return isPublicIpv4(unbracketed);
+	if (family !== 6) return false;
+	const mapped = unbracketed.replace(/^::ffff:/i, "");
+	if (isIP(mapped) === 4) return isPublicIpv4(mapped);
+	return isPublicIpv6(unbracketed);
+}
+/**
+* Whether a hostname is an IP literal no request may target.
+*
+* @param hostname - a URL hostname, bracketed or not.
+* @returns true when the host is a literal address that is not public.
+*/
+function isNonPublicIpLiteral(hostname) {
+	const unbracketed = unbracket(hostname);
+	return isIP(unbracketed) !== 0 && !isPublicIpAddress(unbracketed);
+}
+/**
+* Refuse a fetch destination the local network policy exists to keep out of
+* reach, before any request is made.
+*
+* @param hostname - the URL hostname, bracketed or not.
+* @param addresses - every address the local resolver returned for the host.
+* @throws WebError `WEB_BLOCKED_URL` for a non-public literal, or for a name
+*   this machine resolves into private space that is not the proxy's fake-ip.
+*/
+function assertPublicFetchTarget(hostname, addresses) {
+	if (isNonPublicIpLiteral(hostname)) throw new WebError(`URL hostname "${hostname}" is not a public IP address`, "WEB_BLOCKED_URL");
+	for (const address of addresses) {
+		if (isPublicIpAddress(address) || isProxyFakeIpAddress(address)) continue;
+		throw new WebError(`URL hostname "${hostname}" resolves to a non-public IP address`, "WEB_BLOCKED_URL");
+	}
+}
+/** Whether a dotted quad is public, using {@link NON_PUBLIC_IPV4}. */
+function isPublicIpv4(address) {
+	const value = ipv4Value(address);
+	if (value === void 0) return false;
+	return !NON_PUBLIC_IPV4.some((cidr) => inRange(value, cidr));
+}
+/** Whether a 32-bit address sits inside one `a.b.c.d/prefix` range. */
+function inRange(value, cidr) {
+	const slash = cidr.indexOf("/");
+	const network = ipv4Value(cidr.slice(0, slash));
+	const prefix = Number(cidr.slice(slash + 1));
+	if (network === void 0 || !Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false;
+	const mask = prefix === 0 ? 0 : 4294967295 << 32 - prefix >>> 0;
+	return (value & mask) >>> 0 === (network & mask) >>> 0;
+}
+/** Parse a dotted quad into its 32-bit value, or `undefined` when it is not one. */
+function ipv4Value(address) {
+	const parts = address.split(".");
+	if (parts.length !== 4) return void 0;
+	let value = 0;
+	for (const part of parts) {
+		if (!/^\d{1,3}$/.test(part)) return void 0;
+		const octet = Number(part);
+		if (octet > 255) return void 0;
+		value = (value << 8 | octet) >>> 0;
+	}
+	return value;
+}
+/** Whether an IPv6 literal is inside `2000::/3` and outside its blocked sub-ranges. */
+function isPublicIpv6(address) {
+	const words = ipv6Words(address);
+	if (words === void 0) return false;
+	const [first = 0, second = 0] = words;
+	if ((first >> 8 & 224) !== 32) return false;
+	if (first === 8193) {
+		if (second === 3512) return false;
+		if (second === 0) return false;
+		if (second === 2) return false;
+		if ((second & 65520) === 16) return false;
+		if ((second & 65520) === 32) return false;
+	}
+	if (first === 8194) return false;
+	if (first === 16383 && second <= 4095) return false;
+	return true;
+}
+/** Parse an IPv6 literal into its eight 16-bit words, or `undefined` when it is not one. */
+function ipv6Words(address) {
+	const zone = address.indexOf("%");
+	const halves = (zone === -1 ? address : address.slice(0, zone)).split("::");
+	if (halves.length > 2) return void 0;
+	const head = parseIpv6Half(halves[0] ?? "");
+	if (head === void 0) return void 0;
+	if (halves.length === 1) return head.length === 8 ? head : void 0;
+	const tail = parseIpv6Half(halves[1] ?? "");
+	if (tail === void 0) return void 0;
+	const gap = 8 - head.length - tail.length;
+	if (gap < 1) return void 0;
+	return [
+		...head,
+		...new Array(gap).fill(0),
+		...tail
+	];
+}
+/** Parse one '::'-free half of an IPv6 literal, expanding a trailing dotted quad. */
+function parseIpv6Half(segment) {
+	if (segment === "") return [];
+	const words = [];
+	for (const piece of segment.split(":")) {
+		if (piece.includes(".")) {
+			const value = ipv4Value(piece);
+			if (value === void 0) return void 0;
+			words.push(value >>> 16, value & 65535);
+			continue;
+		}
+		if (!/^[0-9a-fA-F]{1,4}$/.test(piece)) return void 0;
+		words.push(parseInt(piece, 16));
+	}
+	return words;
+}
+/** WHATWG URL keeps brackets around an IPv6 hostname; IP parsers do not. */
+function unbracket(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+//#endregion
 //#region src/host/codex-fetch.ts
 const DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 const DEFAULT_MAX_BODY_CHARS = 1e5;
@@ -281,6 +502,7 @@ function createCodexFetchProvider(options = {}) {
 	const fetchFn = options.fetchFn ?? fetch;
 	const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
 	const maxBodyChars = options.maxBodyChars ?? DEFAULT_MAX_BODY_CHARS;
+	const resolveHostAddresses = options.resolveHostAddresses ?? lookupHostAddresses;
 	return {
 		id: CODEX_FETCH_PROVIDER_ID,
 		available: () => true,
@@ -293,6 +515,7 @@ function createCodexFetchProvider(options = {}) {
 				throw new WebError(`invalid URL: ${targetUrl}`, "WEB_INVALID_URL", { cause: error });
 			}
 			if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") throw new WebError(`unsupported URL scheme "${parsedUrl.protocol}" (only http and https are allowed)`, "WEB_INVALID_URL");
+			assertPublicFetchTarget(parsedUrl.hostname, isIpLiteral(parsedUrl.hostname) ? [] : await resolveHostAddresses(parsedUrl.hostname));
 			let response;
 			try {
 				response = await fetchFn(targetUrl, {
@@ -3538,7 +3761,7 @@ var SearchProviderSwitcher = class {
 	constructor(loader) {
 		this.loader = loader;
 	}
-	async select(preference) {
+	async select(preference, options = {}) {
 		const entry = this.findWebEntry();
 		if (entry === null) return;
 		const config = currentConfig(entry);
@@ -3547,9 +3770,9 @@ var SearchProviderSwitcher = class {
 			this.originalFetchProvider = typeof config.fetchProvider === "string" && config.fetchProvider !== "codex-subscription" ? config.fetchProvider : void 0;
 			this.initialized = true;
 		}
-		const selected = preference === "codex" ? CODEX_SEARCH_PROVIDER_ID : void 0;
-		const nextSearch = selected ?? this.originalSearchProvider;
-		const nextFetch = selected ? CODEX_FETCH_PROVIDER_ID : this.originalFetchProvider;
+		const codexSelected = preference === SEARCH_PROVIDER_CODEX;
+		const nextSearch = codexSelected ? CODEX_SEARCH_PROVIDER_ID : this.originalSearchProvider;
+		const nextFetch = codexSelected || options.pluginFetch === true ? CODEX_FETCH_PROVIDER_ID : this.originalFetchProvider;
 		if (config.searchProvider === nextSearch && config.fetchProvider === nextFetch) return;
 		const nextConfig = { ...config };
 		if (nextSearch === void 0) delete nextConfig.searchProvider;
@@ -5958,9 +6181,10 @@ function apply(ctx, pluginConfig = {}) {
 			reasoningSummary: () => preferences.status().reasoningSummary
 		}), preferences);
 		const searchSwitcher = new SearchProviderSwitcher(ctx.loader);
-		const applySearchPreference = (searchProvider = preferences.status().searchProvider) => {
-			searchSwitcher.select(searchProvider).catch((error) => {
-				ctx.logger.warn(`[dsh-chatgpt-subscription] Search provider preference could not be applied: ${error instanceof Error ? error.message : String(error)}`);
+		const applyWebProviders = (current = preferences.status()) => {
+			const pluginFetch = proxyManager.resolveActiveProxyUrl() !== null;
+			searchSwitcher.select(current.searchProvider, { pluginFetch }).catch((error) => {
+				ctx.logger.warn(`[dsh-chatgpt-subscription] Web provider selection could not be applied: ${error instanceof Error ? error.message : String(error)}`);
 			});
 		};
 		const disposeRoutes = registerRoutes(ctx, oauth, usage, preferences, proxyManager);
@@ -5969,9 +6193,9 @@ function apply(ctx, pluginConfig = {}) {
 		ctx.inject(["web"], (ctx) => {
 			ctx.web.registerSearchProvider(createCodexSearchProvider(oauth, { fetchFn: proxyFetch }));
 			ctx.web.registerFetchProvider(createCodexFetchProvider({ fetchFn: proxyFetch }));
-			applySearchPreference();
+			applyWebProviders();
 		});
-		const disposePreferenceWatch = preferences.watch((next) => applySearchPreference(next.searchProvider));
+		const disposePreferenceWatch = preferences.watch((next) => applyWebProviders(next));
 		return () => {
 			disposePreferenceWatch();
 			disposeImageTool();

package/lib/types/host/codex-fetch.d.ts

@@ -1,9 +1,16 @@
 import { type WebFetchProvider } from '@deepseek-ai/dsh-web';
 type FetchLike = typeof fetch;
+/** Resolves a hostname to every address this machine's resolver returns. */
+export type HostAddressResolver = (hostname: string) => Promise<readonly string[]>;
 export interface CodexFetchProviderOptions {
     fetchFn?: FetchLike;
     maxResponseBytes?: number;
     maxBodyChars?: number;
+    /**
+     * Address lookup behind the destination policy. Overridden only by focused
+     * tests; the policy itself is what every request goes through.
+     */
+    resolveHostAddresses?: HostAddressResolver;
 }
 export declare function createCodexFetchProvider(options?: CodexFetchProviderOptions): WebFetchProvider;
 export {};

package/lib/types/host/codex-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex-fetch.d.ts","sourceRoot":"","sources":["../../../src/host/codex-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,gBAAgB,EAA6C,MAAM,sBAAsB,CAAA;AAGjH,KAAK,SAAS,GAAG,OAAO,KAAK,CAAA;AAE7B,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAKD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,gBAAgB,CAqFlB"}
+{"version":3,"file":"codex-fetch.d.ts","sourceRoot":"","sources":["../../../src/host/codex-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,gBAAgB,EAA6C,MAAM,sBAAsB,CAAA;AAIjH,KAAK,SAAS,GAAG,OAAO,KAAK,CAAA;AAE7B,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;AAElF,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,mBAAmB,CAAA;CAC3C;AAKD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,gBAAgB,CAgGlB"}

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

@@ -0,0 +1,78 @@
+/**
+ * Destination policy for this plugin's fetch provider.
+ *
+ * DSH's built-in provider resolves every destination and validates and pins the
+ * address before it connects. That cannot work on a machine whose proxy answers
+ * DNS with its own fake-ip range (`198.18.0.0/15` for Clash/Mihomo, the usual
+ * companion of a system proxy): the hostname is ordinary, the answer is reserved
+ * space, and every request is refused before the proxy that could have resolved
+ * it is ever consulted. This provider exists for that machine, so it cannot
+ * validate names the way the built-in one does.
+ *
+ * It keeps the half of the policy that needs no resolution — an address the URL
+ * states outright is refused unless it is globally reachable unicast, because a
+ * proxy on this machine must not become a path into loopback or a LAN — and it
+ * also refuses a name this machine resolves into private space. Only the proxy's
+ * own fake-ip answers are accepted, since that is what the proxy's name
+ * resolution looks like from here; the URL hostname still reaches the proxy
+ * intact, so the proxy decides where the name really goes.
+ *
+ * @module dsh-chatgpt-subscription/fetch-address-policy
+ */
+/**
+ * Resolve one hostname to every address the local resolver returns, or to no
+ * addresses when it cannot.
+ *
+ * A failure is not evidence of a local destination: the configured proxy
+ * resolves the origin itself, so a name this machine cannot resolve must not
+ * fail a request the proxy could have served.
+ *
+ * @param hostname - the URL hostname, without brackets.
+ * @returns the resolved addresses, or an empty list when resolution failed.
+ */
+export declare function lookupHostAddresses(hostname: string): Promise<readonly string[]>;
+/**
+ * Whether a host is stated as an IP address rather than as a name.
+ *
+ * @param hostname - a URL hostname, bracketed or not.
+ * @returns true when the host is an IPv4 or IPv6 literal.
+ */
+export declare function isIpLiteral(hostname: string): boolean;
+/**
+ * Whether an address is one only a proxy's fake-ip resolver hands out. The IANA
+ * benchmarking range carries no real host, so an answer inside it is this
+ * machine's proxy claiming the name, not a private destination.
+ *
+ * @param address - a textual IPv4 (or IPv4-mapped IPv6) address.
+ * @returns true when the address is inside the proxy fake-ip range.
+ */
+export declare function isProxyFakeIpAddress(address: string): boolean;
+/**
+ * Whether an address is globally reachable unicast. IPv4-mapped IPv6 is
+ * classified by the IPv4 address it embeds; every other IPv6 address is public
+ * only inside `2000::/3`, which excludes loopback, unique-local, link-local,
+ * multicast, and the transition and translation prefixes whose real destination
+ * cannot be seen from the address alone.
+ *
+ * @param address - a textual IPv4 or IPv6 address, bracketed or not.
+ * @returns true only for a public unicast destination.
+ */
+export declare function isPublicIpAddress(address: string): boolean;
+/**
+ * Whether a hostname is an IP literal no request may target.
+ *
+ * @param hostname - a URL hostname, bracketed or not.
+ * @returns true when the host is a literal address that is not public.
+ */
+export declare function isNonPublicIpLiteral(hostname: string): boolean;
+/**
+ * Refuse a fetch destination the local network policy exists to keep out of
+ * reach, before any request is made.
+ *
+ * @param hostname - the URL hostname, bracketed or not.
+ * @param addresses - every address the local resolver returned for the host.
+ * @throws WebError `WEB_BLOCKED_URL` for a non-public literal, or for a name
+ *   this machine resolves into private space that is not the proxy's fake-ip.
+ */
+export declare function assertPublicFetchTarget(hostname: string, addresses: readonly string[]): void;
+//# sourceMappingURL=fetch-address-policy.d.ts.map

package/lib/types/host/fetch-address-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-address-policy.d.ts","sourceRoot":"","sources":["../../../src/host/fetch-address-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAkCH;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAOtF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAQ5F"}

package/lib/types/host/search-provider-switcher.d.ts

@@ -3,13 +3,27 @@ import type { SearchProviderPreference } from '../shared/contracts.ts';
 interface LoaderLike {
     entries(): Iterable<Entry>;
 }
+/** What one selection asks for on top of the settings preference. */
+export interface WebProviderSelectionOptions {
+    /**
+     * Whether this plugin's fetch provider must serve the `web_fetch` tool.
+     *
+     * DSH's built-in provider resolves and pins every destination before it
+     * connects and routes through a proxy only when the process environment names
+     * one, so an OS-level proxy plus the fake-ip DNS that usually comes with it
+     * fails every fetch with `WEB_BLOCKED_URL`. Selecting this plugin's provider
+     * hands the origin's resolution to the configured proxy — the same
+     * proxied-hop semantics DSH applies to a URL it routes through a proxy.
+     */
+    readonly pluginFetch?: boolean;
+}
 export declare class SearchProviderSwitcher {
     private readonly loader;
     private originalSearchProvider;
     private originalFetchProvider;
     private initialized;
     constructor(loader: LoaderLike);
-    select(preference: SearchProviderPreference): Promise<void>;
+    select(preference: SearchProviderPreference, options?: WebProviderSelectionOptions): Promise<void>;
     private findWebEntry;
 }
 export {};

package/lib/types/host/search-provider-switcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-provider-switcher.d.ts","sourceRoot":"","sources":["../../../src/host/search-provider-switcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAG9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAEtE,UAAU,UAAU;IAClB,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAA;CAC3B;AAED,qBAAa,sBAAsB;IAKrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,sBAAsB,CAAoB;IAClD,OAAO,CAAC,qBAAqB,CAAoB;IACjD,OAAO,CAAC,WAAW,CAAQ;gBAEE,MAAM,EAAE,UAAU;IAEzC,MAAM,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCjE,OAAO,CAAC,YAAY;CAOrB"}
+{"version":3,"file":"search-provider-switcher.d.ts","sourceRoot":"","sources":["../../../src/host/search-provider-switcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAG9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAEtE,UAAU,UAAU;IAClB,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAA;CAC3B;AAED,qEAAqE;AACrE,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,qBAAa,sBAAsB;IAKrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,sBAAsB,CAAoB;IAClD,OAAO,CAAC,qBAAqB,CAAoB;IACjD,OAAO,CAAC,WAAW,CAAQ;gBAEE,MAAM,EAAE,UAAU;IAEzC,MAAM,CAAC,UAAU,EAAE,wBAAwB,EAAE,OAAO,GAAE,2BAAgC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkC5G,OAAO,CAAC,YAAY;CAOrB"}

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAqCxC,yDAAyD;AACzD,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAA;IACpC,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;CAC9C;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAI3B,CAAA;AAEF,eAAO,MAAM,MAAM,UAAqE,CAAA;AAExF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,GAAE,MAAW,GAAG,IAAI,CA0FnE;AAED,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,mBAAmB,EACnB,2BAA2B,EAC3B,sBAAsB,EACtB,iCAAiC,EACjC,4BAA4B,EAC5B,kBAAkB,EAClB,cAAc,EACd,gCAAgC,EAChC,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,wCAAwC,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAClF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACtF,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,YAAY,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAClE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,iBAAiB,GAClB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAClG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAsCxC,yDAAyD;AACzD,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAA;IACpC,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;CAC9C;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAI3B,CAAA;AAEF,eAAO,MAAM,MAAM,UAAqE,CAAA;AAExF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,GAAE,MAAW,GAAG,IAAI,CAsGnE;AAED,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,mBAAmB,EACnB,2BAA2B,EAC3B,sBAAsB,EACtB,iCAAiC,EACjC,4BAA4B,EAC5B,kBAAkB,EAClB,cAAc,EACd,gCAAgC,EAChC,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,wCAAwC,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAClF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACtF,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,YAAY,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAClE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,iBAAiB,GAClB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAClG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eddyskywalker/dsh-chatgpt-subscription",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "DSH provider plugin for Codex access through a ChatGPT subscription.",
   "author": {
     "name": "eddyskywalker",