@xneog/dsh-web-fetch-http 0.1.0 → 0.1.3-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/web-fetch-http/README.md
-README.md: 5589a8e8605a64ae9ef5f6d9978a9b63331d5b0d
-README.zh.md: e9cf98feb9065947af1321c87562a2ae9ac21315
+README.md: 44aad8a83078587057230927e5cb69ba715a0934
+README.zh.md: e70be385f6180175f2b51ef269968c235e9b31cd

package/README.md

@@ -1,44 +1,125 @@
+---
+description: "The anonymous public HTTP(S) fetch backend for ctx.web: how deployments mount bounded, safe URL retrieval with same-origin redirects and text-only decoding."
+kind: "package-reference"
+---
+
 # @xneog/dsh-web-fetch-http
 
 English | [中文](README.zh.md)
 
-An anonymous public HTTP(S) `WebFetchProvider` for the harness [web capability seam](../web/README.md) (`ctx.web`). It retrieves a concrete URL and returns a status code plus bounded decoded content.
+## Summary
+
+With `dsh-web-fetch-http`, the harness can fetch public HTTP(S) pages through the web service (`ctx.web`) and get their status code plus bounded, decoded content without sending credentials. Choose it when a composition needs safe retrieval with URL validation, public-address resolution, connection pinning, same-origin redirects, byte and character caps, and an explicit product `User-Agent`. It returns non-2xx responses as results rather than errors, and rejects non-public destinations, binary data, and unsupported content types. The model-facing `web_fetch` tool lives in `dsh-tool-web`, which renders this provider's bodies.
+
+## Table of Contents
 
-This is an **implementation** package: it registers a provider into `ctx.web`, it does not own the key and it does not register a model-facing tool. It is a function/namespace plugin (`inject: ['web']`).
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
 
-## Responsibility split
+-----
 
-The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, a resource-backstop timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@xneog/dsh-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource.
+<a id="use-this-package"></a>
+## Use this package
 
-The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-tool-call-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
+Mount the provider in a composition that already loads the web service; it registers as the `http` fetch provider, so `ctx.web.fetch()` resolves it automatically when it is the only usable fetch backend — or pin it with `fetchProvider: http`.
 
-A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct service caller whose provider budget elapsed.
+### When to choose it
 
-## Transport hygiene
+Choose this backend when a deployment must fetch public pages with bounded output and safe transport: no credentials are sent, every resolved address must be public, each connection is pinned to the validated answer set, redirects cannot escape the origin, and every response is capped.
 
-- Accepts only `http:` and `https:` URLs; rejects credentials in URLs (`WEB_BLOCKED_URL`) and over-long/malformed URLs (`WEB_INVALID_URL`).
-- Enforces a max URL length, response byte cap (`WEB_FETCH_TOO_LARGE`), decoded body character cap, timeout (`WEB_FETCH_TIMEOUT`), and redirect hop cap.
-- Propagates the caller's abort signal (`WEB_ABORTED`) into the network request and the streaming read.
-- Follows only **same-origin** redirects; a cross-origin redirect fails with `WEB_REDIRECT_BLOCKED`, requiring a fresh tool call (the model of Claude Code's WebFetch).
-- Sends an explicit product `User-Agent`, never a browser disguise.
-- Rejects unsupported (e.g. binary) content types with `WEB_UNSUPPORTED_CONTENT_TYPE`.
+### Minimal configuration
 
-## Config
+Load the web service and the provider; configurable limits have safe defaults and validate at plugin construction, so an invalid value fails loudly instead of building a provider with nonsensical caps. The URL security limit is fixed at 2,048 characters.
 
-| Key | Default | Meaning |
+```yaml
+- name: '@xneog/dsh-web'
+- name: '@xneog/dsh-web-fetch-http'
+```
+
+| Field | Default | Meaning |
 |---|---|---|
-| `maxUrlLength` | `2048` | Maximum accepted request URL length. |
-| `maxResponseBytes` | `5_000_000` | Maximum response body size in bytes. |
-| `maxBodyChars` | `100_000` | Maximum decoded body length in characters. |
-| `timeoutMs` | `30_000` | Fetch timeout within Node's timer range — a resource backstop for direct `ctx.web.fetch()` callers, not the model-facing tool-call budget (that is `dsh-tool-call-timeout-policy`). |
-| `maxRedirects` | `5` | Maximum same-origin redirect hops (`0` follows none). |
-| `userAgent` | `deepseek-harness/…` | `User-Agent` header. |
+| `maxResponseBytes` | `5,000,000` | Maximum response body size in bytes |
+| `maxBodyChars` | `100,000` | Maximum decoded body length in characters |
+| `timeoutMs` | `30,000` | Fetch timeout — a resource backstop, not the model-facing tool budget |
+| `maxRedirects` | `5` | Maximum same-origin redirect hops (`0` follows none) |
+| `userAgent` | `xneog-harness/…` | `User-Agent` header sent on every request |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#xneogdsh-web-fetch-http) is the exhaustive source for every accepted field and its JSDoc.
+
+### What a fetch returns
+
+A successful call yields a `WebFetchResult`: the final URL after allowed redirects, the HTTP status code, a decoded body classified as `html` or `text`, and a `truncated` flag. A non-2xx response is a result, not an error — the status code is part of the fetched resource state; `WebError` is reserved for failures to safely retrieve or represent the resource.
+
+```text
+const page = await ctx.web.fetch({ url: 'https://example.com' })
+// page.body.kind === 'html' | 'text'; page.statusCode === 200 | 404 | ...
+```
+
+### Transport behavior
+
+The provider keeps requests anonymous and bounded: it accepts only `http:` and `https:` URLs without embedded credentials and rejects URLs over 2,048 characters. It resolves each hostname once, rejects the complete result if any IPv4 or IPv6 address is not public unicast, and pins the connection to that validated set. IPv6 checks discover the active DNS64 prefix and reject translations to non-public IPv4. Each same-origin redirect repeats resolution and pinning; cross-origin redirects fail and require a fresh call. The provider also enforces byte, character, hop, and time caps, rejects unsupported content types, and sends an explicit product `User-Agent`.
+
+### Failures and recovery
+
+Failures throw `WebError` with a machine-routable code: `WEB_INVALID_URL`, `WEB_BLOCKED_URL`, `WEB_FETCH_TOO_LARGE`, `WEB_FETCH_TIMEOUT`, `WEB_REDIRECT_BLOCKED`, `WEB_UNSUPPORTED_CONTENT_TYPE`, `WEB_ABORTED`, or `WEB_PROVIDER_ERROR`. Direct callers can route on the code; the model-facing `web_fetch` tool surfaces the failure text to the model under its own error wrapper.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the provider; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The package is built on one separation and one layered timeout:
 
-The numeric limits are validated at plugin construction: every cap except `maxRedirects` must be a positive finite number, and `maxRedirects` must be a non-negative integer. An invalid value throws rather than silently constructing a provider with nonsensical limits.
+- **Safe retrieval vs. presentation.** This provider owns URL validation, public-address enforcement, connection pinning, HTTP transport, redirect policy, caps, charset decoding, and binary rejection; `dsh-tool-web` owns HTML→markdown and truncation formatting. A non-2xx response is data, not failure.
+- **Two timeout layers.** The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers; the model-facing tool-call budget belongs to `dsh-tool-call-timeout-policy`, which arms `exec.signal`. When the outer deadline fires first the provider reports `WEB_ABORTED` and the policy replaces it with `TOOL_TIMEOUT`; `WEB_FETCH_TIMEOUT` therefore identifies a direct service caller whose provider budget elapsed.
 
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: config schema, limit validation, provider registration |
+| [`src/provider.ts`](src/provider.ts) | The `HttpFetchProvider`: pinned transport, redirect following, capped reads, charset decoding |
+| [`src/network.ts`](src/network.ts) | Public-address resolution, DNS64 discovery, and connection pinning |
+| [`src/policy.ts`](src/policy.ts) | URL validation, same-origin checks, content-type classification, charset parsing |
+| — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
+
+### Read path
+
+A fetch validates the URL, resolves the hostname once, rejects the complete answer set when any address is not public, and pins the connection to the accepted addresses. It repeats that check for each same-origin redirect; a cross-origin redirect or non-public target fails before response bytes are accepted. The final response is classified by `Content-Type`, decoded from its declared charset, and read under the byte cap; the decoded text is then truncated to the character cap.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared vocabulary to the service, the model-facing tools, and the design rationale.
+
+- [Web subsystem](../../../docs/subsystems/web.md) — the exhaustive fetch request/result vocabulary and error codes.
+- [Web package map](../README.md) — the six-package family and each role.
+- [dsh-web](../web/README.md) — the web service this provider registers into.
+- [dsh-tool-web](../tool-web/README.md) — the model-facing `web_fetch` tool that renders this provider's bodies.
+- [Generated configuration catalog](../../../docs/config-catalog.md#xneogdsh-web-fetch-http) — every accepted config field and its source declaration.
+- [Web capability seam decision](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) — why search and fetch share one provider-selection service.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-Indirectly, through [`dsh-tool-web`](../tool-web/README.md), which places this provider's `maxBodyChars`-bounded decoded text or markdown-shaped HTML under its fetch-result wrapper and retains provider failures while redirects, headers, and transport mechanics remain hidden.
+Indirectly, through `dsh-tool-web`, which renders this provider's `maxBodyChars`-bounded decoded text or markdown-shaped HTML under its fetch-result wrapper while redirects, headers, and transport limits remain hidden.
 
 #### KV Cache effect
 
@@ -46,6 +127,20 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **SSRF / private-network protection is deferred** — no blocking of private, loopback, link-local, multicast, or otherwise non-public destinations, no DNS-resolve-then-validate, no per-hop re-validation (see [the web capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)). Until it lands, this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets.
-- **Only textual content decodes** — html/xhtml and `text/*`-plus-JSON/XML families; a missing `Content-Type` or any binary type throws `WEB_UNSUPPORTED_CONTENT_TYPE`, and text-extractable PDF decoding is named deferred work.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the provider is unsafe or a poor fit. They are current package constraints.
+
+- **Only textual content decodes** — html/xhtml and `text/*` plus JSON/XML families; a missing `Content-Type` or any binary type throws `WEB_UNSUPPORTED_CONTENT_TYPE`, and text-extractable PDF decoding is named deferred work.
 - **Charset comes only from the `Content-Type` header** (UTF-8 default) — an HTML `<meta charset>` declaration is ignored, and a declared-but-unrecognized charset label throws rather than falling back.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,51 +1,146 @@
+---
+description: "ctx.web 的匿名公共 HTTP(S) 抓取后端：部署方如何挂载有界、安全的 URL 抓取，含同源重定向与仅文本解码。"
+kind: "package-reference"
+---
+
 # @xneog/dsh-web-fetch-http
 
 [English](README.md) | 中文
 
-一个匿名公共 HTTP(S) `WebFetchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它获取具体 URL，返回状态码和长度受限的解码内容。
+## 概述
+
+有了 `dsh-web-fetch-http`，harness 可以通过 web 服务（`ctx.web`）抓取公共 HTTP(S) 页面，并在不发送凭据的情况下获得状态码与有界、解码后的内容。当组合需要 URL 校验、公开地址解析、连接固定、仅同源重定向、字节和字符上限及显式产品 `User-Agent` 时选择它。它把非 2xx 响应作为结果而非错误返回，并拒绝非公开目标、二进制数据与不受支持的内容类型。面向模型的 `web_fetch` 工具位于 `dsh-tool-web`，由它渲染本提供方的正文。
+
+## 目录
 
-这是一个**实现**包：它向 `ctx.web` 注册提供方，不拥有该键，也不注册面向模型的工具。它是函数／命名空间插件（`inject: ['web']`）。
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
 
-## 职责拆分
+-----
 
-提供方拥有**安全资源获取**：URL 验证、HTTP 传输、重定向策略、资源兜底超时、中止传播、字节上限、charset 解码、内容类型分类与二进制拒绝。`@xneog/dsh-tool-web` 拥有**呈现**（HTML→markdown、截断格式）。非 2xx HTTP 响应是*结果*（状态码 + 解码主体），不是错误；`WebError` 只用于无法安全获取或表示资源的失败。
+<a id="use-this-package"></a>
+## 使用本包
 
-提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-tool-call-timeout-policy`](../../guard/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
+在已加载 web 服务的组合中挂载本提供方；它以 `http` 抓取提供方身份注册，因此当它是唯一可用的抓取后端时，`ctx.web.fetch()` 会自动解析到它——也可以用 `fetchProvider: http` 固定。
 
-已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接服务调用方的提供方预算已经耗尽。
+### 何时选择
 
-## 传输卫生
+当部署必须以有界输出和安全传输抓取公共页面时选择此后端：不发送凭据，每个已解析地址必须是公共地址，每次连接都固定到已校验的地址集合，重定向无法逃出源站，每个响应都有上限。
 
-- 只接受 `http:` 和 `https:` URL；拒绝 URL 中的凭据（`WEB_BLOCKED_URL`）以及过长／格式错误的 URL（`WEB_INVALID_URL`）。
-- 强制执行 URL 最大长度、响应字节上限（`WEB_FETCH_TOO_LARGE`）、解码主体字符上限、超时（`WEB_FETCH_TIMEOUT`）和重定向跳数上限。
-- 把调用方的中止信号（`WEB_ABORTED`）传播到网络请求与流式读取。
-- 只跟随**同源**重定向；跨源重定向以 `WEB_REDIRECT_BLOCKED` 失败，要求发起新的工具调用（沿用 Claude Code 的 WebFetch 模式）。
-- 发送显式的产品 `User-Agent`，绝不伪装成浏览器。
-- 不受支持的内容类型（例如二进制）以 `WEB_UNSUPPORTED_CONTENT_TYPE` 拒绝。
+### 最小配置
 
-## 配置
+加载 web 服务与本提供方；可配置上限都有安全默认值，并在插件构造时验证，因此无效值会响亮地失败，而不是构造出上限荒谬的提供方。URL 安全上限固定为 2,048 个字符。
 
-| 配置键 | 默认值 | 含义 |
+```yaml
+- name: '@xneog/dsh-web'
+- name: '@xneog/dsh-web-fetch-http'
+```
+
+| 字段 | 默认值 | 含义 |
 |---|---|---|
-| `maxUrlLength` | `2048` | 接受的请求 URL 最大长度。 |
-| `maxResponseBytes` | `5_000_000` | 响应主体最大字节数。 |
-| `maxBodyChars` | `100_000` | 解码主体最大字符数。 |
-| `timeoutMs` | `30_000` | Node 定时器范围内的抓取超时：直接 `ctx.web.fetch()` 调用方的资源兜底，而非面向模型的工具调用预算（后者属于 `dsh-tool-call-timeout-policy`）。 |
-| `maxRedirects` | `5` | 同源重定向最大跳数（`0` 表示完全不跟随）。 |
-| `userAgent` | `deepseek-harness/…` | `User-Agent` 标头。 |
+| `maxResponseBytes` | `5,000,000` | 响应主体最大字节数 |
+| `maxBodyChars` | `100,000` | 解码主体最大字符数 |
+| `timeoutMs` | `30,000` | 抓取超时——资源兜底，不是面向模型的工具预算 |
+| `maxRedirects` | `5` | 同源重定向最大跳数（`0` 表示不跟随） |
+| `userAgent` | `xneog-harness/…` | 每次请求发送的 `User-Agent` 标头 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#xneogdsh-web-fetch-http)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 抓取返回什么
+
+成功调用产生 `WebFetchResult`：允许的重定向之后的最终 URL、HTTP 状态码、分类为 `html` 或 `text` 的解码正文，以及 `truncated` 标志。非 2xx 响应是结果而非错误——状态码是被抓取资源状态的一部分；`WebError` 只用于无法安全获取或表示资源的失败。
+
+```text
+const page = await ctx.web.fetch({ url: 'https://example.com' })
+// page.body.kind === 'html' | 'text'; page.statusCode === 200 | 404 | ...
+```
+
+### 传输行为
+
+提供方保持请求匿名且有界：只接受不含内嵌凭据且不超过 2,048 个字符的 `http:` 与 `https:` URL。它只解析一次主机名；只要结果中有任何 IPv4 或 IPv6 地址不是公共单播地址，就拒绝整个结果，并把连接固定到已校验的地址集合。IPv6 检查会发现活动 DNS64 前缀，并拒绝指向非公开 IPv4 的转换地址。每次同源重定向都会重复解析与固定；跨源重定向会失败并要求重新调用。提供方还强制执行字节、字符、跳数和时间上限，拒绝不支持的内容类型，并发送显式产品 `User-Agent`。
+
+### 失败与恢复
+
+失败抛出携带可按机器路由 code 的 `WebError`：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_REDIRECT_BLOCKED`、`WEB_UNSUPPORTED_CONTENT_TYPE`、`WEB_ABORTED` 或 `WEB_PROVIDER_ERROR`。直接调用方可以按 code 路由；面向模型的 `web_fetch` 工具会在自己的错误包装层内把失败文本呈现给模型。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释提供方背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+本包建立在一个分离与一个分层超时之上：
 
-数值限制会在插件构造时验证：除 `maxRedirects` 外，每个上限都必须是正的有限数；`maxRedirects` 必须是非负整数。无效值会抛出异常，不会静默构造限制荒谬的提供方。
+- **安全获取与呈现分离。** 本提供方拥有 URL 校验、公开地址强制规则、连接固定、HTTP 传输、重定向策略、上限、charset 解码与二进制拒绝；`dsh-tool-web` 拥有 HTML→markdown 与截断格式化。非 2xx 响应是数据，不是失败。
+- **两层超时。** 提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方的资源兜底；面向模型的工具调用预算属于 `dsh-tool-call-timeout-policy`，由它触发 `exec.signal`。外层截止期限先到时，提供方报告 `WEB_ABORTED`，策略再以 `TOOL_TIMEOUT` 替换；因此 `WEB_FETCH_TIMEOUT` 标识的是提供方预算耗尽的直接服务调用方。
 
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：配置 schema、上限验证、提供方注册 |
+| [`src/provider.ts`](src/provider.ts) | `HttpFetchProvider`：固定连接、重定向跟随、有界读取、charset 解码 |
+| [`src/network.ts`](src/network.ts) | 公开地址解析、DNS64 发现与连接固定 |
+| [`src/policy.ts`](src/policy.ts) | URL 校验、同源检查、内容类型分类、charset 解析 |
+| — | 不发布运行时不变式伴生入口；上限在提供方处强制执行。 |
+
+### 读取路径
+
+抓取先校验 URL，只解析一次主机名，结果中只要有非公开地址就拒绝，并把连接固定到已接受地址。每次同源重定向都重复该检查；跨源重定向或非公开目标在接收响应字节前失败。最终响应按 `Content-Type` 分类、依声明的 charset 解码，并在字节上限内读取；解码后的文本再截断到字符上限。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享词汇逐步进入服务、面向模型的工具与设计依据。
+
+- [web 子系统](../../../docs/subsystems/web.zh.md)——穷尽式的抓取请求／结果词汇与错误码。
+- [web 包映射](../README.zh.md)——六包家族与各角色。
+- [dsh-web](../web/README.zh.md)——本提供方注册进入的 web 服务。
+- [dsh-tool-web](../tool-web/README.zh.md)——渲染本提供方正文的面向模型 `web_fetch` 工具。
+- [生成配置目录](../../../docs/config-catalog.zh.md#xneogdsh-web-fetch-http)——每个受支持配置字段及其源声明。
+- [web 能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-通过 [`dsh-tool-web`](../tool-web/README.md) 间接影响；该工具把此提供方经 `maxBodyChars` 限制的解码文本或由 HTML 转换得到的 markdown 置于抓取结果包装层中，并保留提供方失败；重定向、标头与传输机制保持隐藏。
+间接地，通过 `dsh-tool-web`：该工具把本提供方经 `maxBodyChars` 限制的解码文本或由 HTML 转换得到的 markdown 置于抓取结果包装层内，而重定向、标头与传输上限保持隐藏。
 
 #### KV Cache 影响
 
 不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明提供方何时不安全或不合适。它们是当前包约束。
+
+- **只解码文本内容**——包括 html/xhtml 与 `text/*` 加 JSON/XML 家族；缺少 `Content-Type` 或任何二进制类型都会抛出 `WEB_UNSUPPORTED_CONTENT_TYPE`，可提取文本的 PDF 解码属于明确的延期工作。
+- **charset 只来自 `Content-Type` 标头**（默认 UTF-8）——HTML `<meta charset>` 声明会被忽略；声明但无法识别的 charset 标签会抛出异常，而非回退。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
 
-- **SSRF／私有网络防护暂缓**：不会阻止私有、loopback、link-local、multicast 或其他非公开目标，也不进行 DNS 解析后验证或逐跳重新验证（见 [web 能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。在此功能落地前，该提供方是 SSRF 原语；能够访问敏感内部网络目标的部署**禁止启用它**。
-- **只解码文本内容**：包括 html/xhtml 与 `text/*` 加 JSON/XML 家族；缺少 `Content-Type` 或任何二进制类型都会抛出 `WEB_UNSUPPORTED_CONTENT_TYPE`，可提取文本的 PDF 解码属于明确的暂缓工作。
-- **charset 只来自 `Content-Type` 标头**（默认为 UTF-8）：HTML `<meta charset>` 声明会被忽略；声明但无法识别的 charset 标签会抛出异常，而非回退。
+</details>

package/lib/index.js

@@ -1,6 +1,257 @@
 import z from "@xneog/schemastery";
 import { WebError } from "@xneog/dsh-web";
 import { deadline, timeoutOf } from "@xneog/dsh-timeout";
+import { proxyRouteFor } from "@xneog/dsh-http-proxy";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import ipaddr from "ipaddr.js";
+//#region lib/types/network.js
+/**
+* Public-network resolution and address-pinned HTTP transport for `web-fetch-http`.
+* One DNS answer set is validated before Undici receives it through a custom lookup,
+* so the connection cannot resolve the hostname again to a private address.
+*
+* @module @xneog/dsh-web-fetch-http/network
+*/
+/** RFC 6052 prefix lengths that may carry an IPv4 destination through NAT64. */
+const RFC6052_PREFIX_LENGTHS = [
+	32,
+	40,
+	48,
+	56,
+	64,
+	96
+];
+const IPV4ONLY_DISCOVERY_HOST = "ipv4only.arpa";
+const IPV4ONLY_SENTINELS = new Set(["192.0.0.170", "192.0.0.171"]);
+/**
+* Return whether an address is globally reachable unicast. IPv4-mapped IPv6 is
+* classified by its embedded IPv4 address; transition and translation prefixes
+* remain blocked because their eventual IPv4 destination cannot be pinned here.
+*
+* @param input - textual IPv4 or IPv6 address.
+* @returns true only for a public unicast destination.
+*/
+function isPublicIpAddress(input) {
+	let parsed;
+	try {
+		parsed = ipaddr.parse(stripIpv6Brackets(input));
+	} catch {
+		return false;
+	}
+	if (parsed instanceof ipaddr.IPv4) return parsed.range() === "unicast";
+	if (parsed.isIPv4MappedAddress()) return parsed.toIPv4Address().range() === "unicast";
+	return parsed.range() === "unicast";
+}
+/**
+* Resolve a hostname once and reject the complete answer set if any destination
+* is not public. The returned addresses are the only ones the transport may use.
+*
+* @param hostname - URL hostname, including brackets when it is an IPv6 literal.
+* @param signal - aborts the wait for system resolution; an in-flight OS lookup may finish unused.
+* @param resolver - lookup implementation, overridden only by focused tests.
+* @returns the validated, non-empty address set.
+*/
+async function resolvePublicAddresses(hostname, signal, resolver = lookup) {
+	const unbracketed = stripIpv6Brackets(hostname);
+	const literalFamily = isIP(unbracketed);
+	const resolved = literalFamily === 0 ? await raceWithSignal(resolver(unbracketed, {
+		all: true,
+		order: "verbatim"
+	}), signal) : [{
+		address: unbracketed,
+		family: literalFamily
+	}];
+	if (resolved.length === 0) throw new WebError(`hostname "${hostname}" resolved to no addresses`, "WEB_PROVIDER_ERROR");
+	const nat64Prefixes = resolved.some((entry) => entry.family === 6 && isIP(entry.address) === 6) ? await discoverNat64Prefixes(signal, resolver) : [];
+	const addresses = [];
+	for (const entry of resolved) {
+		if (entry.family !== 4 && entry.family !== 6 || isIP(entry.address) !== entry.family) throw new WebError(`hostname "${hostname}" resolved to an invalid IP address`, "WEB_PROVIDER_ERROR");
+		if (!isPublicIpAddress(entry.address)) throw new WebError(`URL hostname "${hostname}" resolves to a non-public IP address`, "WEB_BLOCKED_URL");
+		const translatedIpv4 = translatedIpv4Address(entry.address, nat64Prefixes);
+		if (translatedIpv4 !== void 0 && !isPublicIpAddress(translatedIpv4)) throw new WebError(`URL hostname "${hostname}" resolves through NAT64 to a non-public IPv4 address`, "WEB_BLOCKED_URL");
+		addresses.push({
+			address: entry.address,
+			family: entry.family
+		});
+	}
+	return addresses;
+}
+/** Discover the active DNS64 prefix set using RFC 7050's reserved hostname. */
+async function discoverNat64Prefixes(signal, resolver) {
+	const discovered = await raceWithSignal(resolver(IPV4ONLY_DISCOVERY_HOST, {
+		all: true,
+		order: "verbatim"
+	}), signal);
+	const prefixes = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of discovered) {
+		if (entry.family !== 6 || isIP(entry.address) !== 6) continue;
+		const bytes = ipaddr.parse(entry.address).toByteArray();
+		for (const length of RFC6052_PREFIX_LENGTHS) {
+			const embedded = embeddedIpv4Address(bytes, length);
+			if (embedded === void 0 || !IPV4ONLY_SENTINELS.has(embedded)) continue;
+			const prefixBytes = bytes.slice(0, length / 8);
+			const key = `${String(length)}:${prefixBytes.join(".")}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			prefixes.push({
+				bytes: prefixBytes,
+				length
+			});
+		}
+	}
+	return prefixes;
+}
+/** Return the RFC 6052-embedded IPv4 address when an IPv6 address matches a discovered prefix. */
+function translatedIpv4Address(input, prefixes) {
+	if (isIP(input) !== 6) return void 0;
+	const bytes = ipaddr.parse(input).toByteArray();
+	for (const prefix of prefixes) {
+		if (!prefix.bytes.every((byte, index) => bytes[index] === byte)) continue;
+		const embedded = embeddedIpv4Address(bytes, prefix.length);
+		if (embedded !== void 0) return embedded;
+	}
+}
+/** Extract one IPv4 address from an RFC 6052 IPv6 layout. */
+function embeddedIpv4Address(bytes, prefixLength) {
+	if (prefixLength === 96) return bytes.slice(12, 16).join(".");
+	if (bytes[8] !== 0) return void 0;
+	const prefixBytes = prefixLength / 8;
+	const beforeReservedOctet = 8 - prefixBytes;
+	return [...bytes.slice(prefixBytes, prefixBytes + beforeReservedOctet), ...bytes.slice(9, 13 - beforeReservedOctet)].join(".");
+}
+/**
+* Whether a hostname is an IP literal that {@link resolvePublicAddresses} would refuse.
+*
+* A proxied hop skips those checks because the proxy resolves the origin, but a literal needs no
+* resolution: the address is already stated, and handing it to a proxy running on this machine
+* would reach exactly the loopback or private service the checks exist to keep out of reach.
+*
+* @param hostname - a URL's hostname, bracketed or not.
+* @returns true when the host is a literal address no request may be sent to.
+*/
+function isNonPublicIpLiteral(hostname) {
+	const unbracketed = stripIpv6Brackets(hostname);
+	return isIP(unbracketed) !== 0 && !isPublicIpAddress(unbracketed);
+}
+/**
+* Fetch through an agent whose lookup callback returns only the already validated address set. The
+* URL hostname remains intact for HTTP Host and TLS SNI.
+*
+* The agent is this request's own because the address set is: pinning is how this package refuses a
+* DNS answer that changes between validation and connection, and it may not apply process-wide —
+* an operator-configured MCP server or model endpoint on loopback is a supported destination, and
+* only the URLs this tool fetches are the model's to choose.
+*
+* @param url - validated HTTP(S) URL the policy does not route through a proxy.
+* @param addresses - public addresses returned by {@link resolvePublicAddresses}.
+* @param headers - request headers.
+* @param signal - request and body-read cancellation signal.
+* @returns a response plus the disposer its consumer must call.
+*/
+async function requestPinned(url, addresses, headers, signal) {
+	const { Agent, fetch } = await import("undici");
+	const dispatcher = new Agent({
+		autoSelectFamily: true,
+		connect: { lookup: createPinnedLookup(addresses) }
+	});
+	try {
+		return {
+			response: await fetch(url, {
+				method: "GET",
+				redirect: "manual",
+				headers,
+				signal,
+				dispatcher
+			}),
+			close: async () => {
+				await dispatcher.close();
+			}
+		};
+	} catch (error) {
+		await dispatcher.close();
+		throw error;
+	}
+}
+/**
+* Fetch through the dispatcher the proxy policy already installed, letting the proxy resolve the
+* origin.
+*
+* No address set is pinned because none exists to pin: the proxy performs the lookup, and a
+* connection pinned to a locally resolved address would reach the origin directly and defeat the
+* proxy. The dispatcher is the process-wide one, so hops share its connection pool and no caller
+* closes it.
+*
+* @param dispatcher - the route's dispatcher, from `proxyRouteFor`.
+* @param url - validated HTTP(S) URL the policy routes through a proxy.
+* @param headers - request headers.
+* @param signal - request and body-read cancellation signal.
+* @returns a response plus a disposer that releases nothing, so both paths close alike.
+*/
+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()
+	};
+}
+/** Production network operations kept as an object so provider tests can replace resolution only. */
+const publicHttpNetwork = {
+	resolve: resolvePublicAddresses,
+	request: requestPinned,
+	requestVia
+};
+/**
+* Build the connector lookup that serves a fixed validated answer set.
+*
+* @param addresses - public addresses retained from the preceding resolution.
+* @returns a Node-compatible lookup callback that performs no network resolution.
+*/
+function createPinnedLookup(addresses) {
+	return (hostname, options, callback) => {
+		const family = typeof options.family === "number" ? options.family : options.family === "IPv4" ? 4 : options.family === "IPv6" ? 6 : 0;
+		const eligible = family === 0 ? addresses : addresses.filter((address) => address.family === family);
+		const selected = eligible[0];
+		if (selected === void 0) {
+			callback(Object.assign(/* @__PURE__ */ new Error(`no validated address for ${hostname} in family ${family}`), {
+				code: "ENOTFOUND",
+				hostname
+			}), options.all === true ? [] : "", family);
+			return;
+		}
+		if (options.all === true) {
+			callback(null, eligible.map((address) => ({ ...address })));
+			return;
+		}
+		callback(null, selected.address, selected.family);
+	};
+}
+/** Race a non-cancellable OS lookup without letting it delay tool cancellation. */
+function raceWithSignal(promise, signal) {
+	const abortError = () => new Error("web fetch aborted during hostname resolution", { cause: signal.reason });
+	if (signal.aborted) return Promise.reject(abortError());
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			reject(abortError());
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", abort);
+		});
+	});
+}
+/** WHATWG URL retains brackets around IPv6 hostnames; IP parsers do not. */
+function stripIpv6Brackets(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+//#endregion
 //#region lib/types/policy.js
 /**
 * URL validation and content-type classification for the local HTTP(S) fetch
@@ -9,18 +260,17 @@ import { deadline, timeoutOf } from "@xneog/dsh-timeout";
 *
 * @module @xneog/dsh-web-fetch-http/policy
 */
+/** Maximum accepted request URL length enforced by the public fetch provider. */
+const WEB_FETCH_MAX_URL_LENGTH = 2048;
 /**
-* Validate a request URL against the basic transport hygiene the provider
-* enforces before any network access: http(s) only, no embedded credentials,
-* bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
-* (SSRF / private-network blocking is deferred — see the package Agent Note.)
+* Parse a request URL and enforce network-independent transport restrictions:
+* HTTP(S) only and no embedded credentials. The provider applies this before
+* resolving a destination.
 *
 * @param input - the raw URL string from the fetch request.
-* @param maxUrlLength - inclusive upper bound on `input`'s length.
 * @returns the parsed `URL`.
 */
-function validateFetchUrl(input, maxUrlLength) {
-	if (input.length > maxUrlLength) throw new WebError(`URL exceeds the maximum length of ${maxUrlLength}`, "WEB_INVALID_URL");
+function parseFetchUrl(input) {
 	let url;
 	try {
 		url = new URL(input);
@@ -32,9 +282,21 @@ function validateFetchUrl(input, maxUrlLength) {
 	return url;
 }
 /**
+* Validate a request URL against the provider's complete pre-network policy:
+* bounded length plus the restrictions enforced by {@link parseFetchUrl}.
+* Public-address resolution and connection pinning run after this check.
+*
+* @param input - the raw URL string from the fetch request.
+* @returns the parsed `URL`.
+*/
+function validateFetchUrl(input) {
+	if (input.length > 2048) throw new WebError(`URL exceeds the maximum length of ${WEB_FETCH_MAX_URL_LENGTH}`, "WEB_INVALID_URL");
+	return parseFetchUrl(input);
+}
+/**
 * Two URLs are same-origin when scheme, hostname, and port match. A redirect
 * that crosses origins is refused so each new origin requires a fresh tool call
-* (and thus a fresh provider/permission decision).
+* and public-address validation.
 *
 * @param a - one of the two URLs to compare.
 * @param b - the other URL to compare.
@@ -92,12 +354,10 @@ function decoderForCharset(charset) {
 //#endregion
 //#region lib/types/provider.js
 /**
-* Safe HTTP(S) retrieval for `ctx.web`: validates URLs, follows only same-origin redirects,
-* enforces time and size limits, classifies and decodes text, and leaves presentation to
-* `@xneog/dsh-tool-web`. Requests carry no browser cookies or ambient credentials.
-*
-* Private-network and SSRF protection is not implemented; do not enable this provider where
-* it can reach sensitive internal targets.
+* Safe HTTP(S) retrieval for `ctx.web`: validates and pins public IP destinations, follows
+* only same-origin redirects, enforces time and size limits, classifies and decodes text,
+* and leaves presentation to `@xneog/dsh-tool-web`. Requests carry no browser cookies
+* or ambient credentials.
 * @module @xneog/dsh-web-fetch-http/provider
 */
 var __addDisposableResource = function(env, value, async) {
@@ -163,9 +423,15 @@ const LOCAL_FETCH_PROVIDER_ID = "http";
 /** The anonymous public HTTP(S) fetch provider. */
 var HttpFetchProvider = class {
 	limits;
+	resolveAddresses;
 	id = LOCAL_FETCH_PROVIDER_ID;
-	constructor(limits) {
+	/**
+	* @param limits - resolved transport and response limits.
+	* @param resolveAddresses - resolver that rejects non-public destinations before returning.
+	*/
+	constructor(limits, resolveAddresses = publicHttpNetwork.resolve) {
 		this.limits = limits;
+		this.resolveAddresses = resolveAddresses;
 	}
 	/** No credentials to check — an anonymous public fetcher is always usable. */
 	available() {
@@ -190,49 +456,54 @@ var HttpFetchProvider = class {
 	}
 	/** Follow same-origin redirects up to the hop cap, then read the final response. */
 	async followAndRead(initialUrl, signal) {
-		let currentUrl = validateFetchUrl(initialUrl, this.limits.maxUrlLength);
+		let currentUrl = validateFetchUrl(initialUrl);
 		let redirectsFollowed = 0;
 		for (;;) {
-			const response = await this.requestOnce(currentUrl, signal);
-			if (isRedirectStatus(response.status)) {
-				if (redirectsFollowed >= this.limits.maxRedirects) {
-					await response.body?.cancel();
-					throw new WebError(`exceeded the maximum of ${this.limits.maxRedirects} redirects`, "WEB_REDIRECT_BLOCKED");
-				}
-				const location = response.headers.get("location");
-				if (location === null) {
-					await response.body?.cancel();
-					throw new WebError(`redirect response (HTTP ${response.status}) without a Location header`, "WEB_PROVIDER_ERROR");
-				}
-				const target = resolveRedirect(location, currentUrl);
-				let validatedTarget;
-				try {
-					validatedTarget = validateFetchUrl(target.toString(), this.limits.maxUrlLength);
-					if (!isSameOrigin(validatedTarget, currentUrl)) throw new WebError(`cross-origin redirect to ${validatedTarget.origin} is not followed automatically; retry against that URL directly`, "WEB_REDIRECT_BLOCKED");
-				} catch (error) {
+			const request = await this.requestOnce(currentUrl, signal);
+			const { response } = request;
+			try {
+				if (isRedirectStatus(response.status)) {
+					if (redirectsFollowed >= this.limits.maxRedirects) {
+						await response.body?.cancel();
+						throw new WebError(`exceeded the maximum of ${this.limits.maxRedirects} redirects`, "WEB_REDIRECT_BLOCKED");
+					}
+					const location = response.headers.get("location");
+					if (location === null) {
+						await response.body?.cancel();
+						throw new WebError(`redirect response (HTTP ${response.status}) without a Location header`, "WEB_PROVIDER_ERROR");
+					}
+					const target = resolveRedirect(location, currentUrl);
+					let validatedTarget;
+					try {
+						validatedTarget = validateFetchUrl(target.toString());
+						if (!isSameOrigin(validatedTarget, currentUrl)) throw new WebError(`cross-origin redirect to ${validatedTarget.origin} is not followed automatically; retry against that URL directly`, "WEB_REDIRECT_BLOCKED");
+					} catch (error) {
+						await response.body?.cancel();
+						throw error;
+					}
 					await response.body?.cancel();
-					throw error;
+					currentUrl = validatedTarget;
+					redirectsFollowed++;
+					continue;
 				}
-				await response.body?.cancel();
-				currentUrl = validatedTarget;
-				redirectsFollowed++;
-				continue;
+				return await this.readBody(response, currentUrl, signal);
+			} finally {
+				await request.close();
 			}
-			return await this.readBody(response, currentUrl, signal);
 		}
 	}
 	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 fetch(url, {
-				method: "GET",
-				redirect: "manual",
-				headers: {
-					"user-agent": this.limits.userAgent,
-					"accept": "text/html,application/xhtml+xml,text/*;q=0.9,application/json;q=0.8"
-				},
-				signal
-			});
+			const route = proxyRouteFor(url);
+			if (route.proxied && !isNonPublicIpLiteral(url.hostname)) return await publicHttpNetwork.requestVia(route.dispatcher, url, headers, signal);
+			const addresses = await this.resolveAddresses(url.hostname, signal);
+			return await publicHttpNetwork.request(url, addresses, headers, signal);
 		} catch (error) {
+			if (error instanceof WebError) throw error;
 			throw translateAbortOrNetwork(error, signal);
 		}
 	}
@@ -358,22 +629,19 @@ function translateAbortOrNetwork(error, signal) {
 //#endregion
 //#region lib/types/index.js
 /**
-* `@xneog/dsh-web-fetch-http`: registers an anonymous public HTTP(S)
-* `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
-* default-export service): it registers INTO the seam's fetch registry, like the
-* search providers register into the search registry.
+* Anonymous public HTTP(S) `WebFetchProvider` plugin. It contributes to the
+* `ctx.web` registry without owning the service.
 *
 * @module @xneog/dsh-web-fetch-http
 */
 const MAX_NODE_TIMER_DELAY_MS = 2147483647;
 /** Default `User-Agent`: an explicit product agent, never a browser disguise. */
-const DEFAULT_USER_AGENT = "deepseek-harness/0.0.1 (+https://github.com/deepseek-ai)";
+const DEFAULT_USER_AGENT = "xneog-harness/0.0.1 (+https://github.com/gomes007-alt)";
 /** Cordis plugin name used by loader diagnostics. */
 const name = "web-fetch-http";
 /** The web seam this provider registers into. */
 const inject = ["web"];
 const Config = z.object({
-	maxUrlLength: z.number().default(2048),
 	maxResponseBytes: z.number().default(5e6),
 	maxBodyChars: z.number().default(1e5),
 	timeoutMs: z.number().default(3e4),
@@ -396,13 +664,11 @@ function assertNonNegativeInteger(name, value) {
 /** Register the local HTTP(S) fetch provider with `ctx.web`. */
 function apply(ctx, config) {
 	const resolved = config;
-	assertPositiveFinite("maxUrlLength", resolved.maxUrlLength);
 	assertPositiveFinite("maxResponseBytes", resolved.maxResponseBytes);
 	assertPositiveFinite("maxBodyChars", resolved.maxBodyChars);
 	assertTimeoutMs(resolved.timeoutMs);
 	assertNonNegativeInteger("maxRedirects", resolved.maxRedirects);
 	const limits = {
-		maxUrlLength: resolved.maxUrlLength,
 		maxResponseBytes: resolved.maxResponseBytes,
 		maxBodyChars: resolved.maxBodyChars,
 		timeoutMs: resolved.timeoutMs,

package/lib/types/index.d.ts

@@ -1,25 +1,21 @@
 /**
- * `@xneog/dsh-web-fetch-http`: registers an anonymous public HTTP(S)
- * `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
- * default-export service): it registers INTO the seam's fetch registry, like the
- * search providers register into the search registry.
+ * Anonymous public HTTP(S) `WebFetchProvider` plugin. It contributes to the
+ * `ctx.web` registry without owning the service.
  *
  * @module @xneog/dsh-web-fetch-http
  */
 import type { Context } from '@xneog/cordis';
 import z from '@xneog/schemastery';
 export { LOCAL_FETCH_PROVIDER_ID, HttpFetchProvider, } from './provider.ts';
-export type { HttpFetchLimits } from './provider.ts';
+export type { HttpFetchLimits, HttpFetchResolver } from './provider.ts';
 /** Default `User-Agent`: an explicit product agent, never a browser disguise. */
-export declare const DEFAULT_USER_AGENT = "deepseek-harness/0.0.1 (+https://github.com/deepseek-ai)";
+export declare const DEFAULT_USER_AGENT = "xneog-harness/0.0.1 (+https://github.com/gomes007-alt)";
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "web-fetch-http";
 /** The web seam this provider registers into. */
 export declare const inject: string[];
 /** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
 export interface Config {
-    /** Maximum accepted request URL length. */
-    maxUrlLength?: number;
     /** Maximum response body size in bytes. */
     maxResponseBytes?: number;
     /** Maximum decoded body length in characters. */

package/lib/types/network.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Public-network resolution and address-pinned HTTP transport for `web-fetch-http`.
+ * One DNS answer set is validated before Undici receives it through a custom lookup,
+ * so the connection cannot resolve the hostname again to a private address.
+ *
+ * @module @xneog/dsh-web-fetch-http/network
+ */
+import type { LookupAddress, LookupOptions } from 'node:dns';
+import type { Dispatcher, Response } from 'undici';
+/** One address resolved and retained for the subsequent pinned connection. */
+export interface PublicAddress {
+    /** Canonical textual IPv4 or IPv6 address. */
+    readonly address: string;
+    /** Address family accepted by Node's connection lookup callback. */
+    readonly family: 4 | 6;
+}
+/** The result of one address-pinned request; closing releases its private pool. */
+export interface PinnedResponse {
+    /** HTTP response whose body remains readable until `close()` is called. */
+    readonly response: Response;
+    /** Release the request's dispatcher after the response body is consumed or cancelled. */
+    close(): Promise<void>;
+}
+/** Resolver signature used to test public-address policy without process DNS changes. */
+export type AddressResolver = (hostname: string, options: {
+    all: true;
+    order: 'verbatim';
+}) => Promise<LookupAddress[]>;
+/**
+ * Return whether an address is globally reachable unicast. IPv4-mapped IPv6 is
+ * classified by its embedded IPv4 address; transition and translation prefixes
+ * remain blocked because their eventual IPv4 destination cannot be pinned here.
+ *
+ * @param input - textual IPv4 or IPv6 address.
+ * @returns true only for a public unicast destination.
+ */
+export declare function isPublicIpAddress(input: string): boolean;
+/**
+ * Resolve a hostname once and reject the complete answer set if any destination
+ * is not public. The returned addresses are the only ones the transport may use.
+ *
+ * @param hostname - URL hostname, including brackets when it is an IPv6 literal.
+ * @param signal - aborts the wait for system resolution; an in-flight OS lookup may finish unused.
+ * @param resolver - lookup implementation, overridden only by focused tests.
+ * @returns the validated, non-empty address set.
+ */
+export declare function resolvePublicAddresses(hostname: string, signal: AbortSignal, resolver?: AddressResolver): Promise<PublicAddress[]>;
+/**
+ * Whether a hostname is an IP literal that {@link resolvePublicAddresses} would refuse.
+ *
+ * A proxied hop skips those checks because the proxy resolves the origin, but a literal needs no
+ * resolution: the address is already stated, and handing it to a proxy running on this machine
+ * would reach exactly the loopback or private service the checks exist to keep out of reach.
+ *
+ * @param hostname - a URL's hostname, bracketed or not.
+ * @returns true when the host is a literal address no request may be sent to.
+ */
+export declare function isNonPublicIpLiteral(hostname: string): boolean;
+/**
+ * Fetch through an agent whose lookup callback returns only the already validated address set. The
+ * URL hostname remains intact for HTTP Host and TLS SNI.
+ *
+ * The agent is this request's own because the address set is: pinning is how this package refuses a
+ * DNS answer that changes between validation and connection, and it may not apply process-wide —
+ * an operator-configured MCP server or model endpoint on loopback is a supported destination, and
+ * only the URLs this tool fetches are the model's to choose.
+ *
+ * @param url - validated HTTP(S) URL the policy does not route through a proxy.
+ * @param addresses - public addresses returned by {@link resolvePublicAddresses}.
+ * @param headers - request headers.
+ * @param signal - request and body-read cancellation signal.
+ * @returns a response plus the disposer its consumer must call.
+ */
+export declare function requestPinned(url: URL, addresses: readonly PublicAddress[], 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 none exists to pin: the proxy performs the lookup, and a
+ * connection pinned to a locally resolved address would reach the origin directly and defeat the
+ * proxy. The dispatcher is the process-wide one, so hops share its connection pool and no caller
+ * closes it.
+ *
+ * @param dispatcher - the route's dispatcher, from `proxyRouteFor`.
+ * @param url - validated HTTP(S) URL the policy routes through a proxy.
+ * @param headers - request headers.
+ * @param signal - request and body-read cancellation signal.
+ * @returns a response plus a disposer that releases nothing, so both paths close alike.
+ */
+export declare function requestVia(dispatcher: Dispatcher, url: URL, headers: Record<string, string>, signal: AbortSignal): Promise<PinnedResponse>;
+/** Production network operations kept as an object so provider tests can replace resolution only. */
+export declare const publicHttpNetwork: {
+    resolve: typeof resolvePublicAddresses;
+    request: typeof requestPinned;
+    requestVia: typeof requestVia;
+};
+type LookupCallback = (error: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void;
+/**
+ * Build the connector lookup that serves a fixed validated answer set.
+ *
+ * @param addresses - public addresses retained from the preceding resolution.
+ * @returns a Node-compatible lookup callback that performs no network resolution.
+ */
+export declare function createPinnedLookup(addresses: readonly PublicAddress[]): (hostname: string, options: LookupOptions, callback: LookupCallback) => void;
+export {};
+//# sourceMappingURL=network.d.ts.map

package/lib/types/policy.d.ts

@@ -5,23 +5,32 @@
  *
  * @module @xneog/dsh-web-fetch-http/policy
  */
+/** Maximum accepted request URL length enforced by the public fetch provider. */
+export declare const WEB_FETCH_MAX_URL_LENGTH = 2048;
 /** The body kinds this provider decodes. */
 export type FetchableKind = 'html' | 'text';
 /**
- * Validate a request URL against the basic transport hygiene the provider
- * enforces before any network access: http(s) only, no embedded credentials,
- * bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
- * (SSRF / private-network blocking is deferred — see the package Agent Note.)
+ * Parse a request URL and enforce network-independent transport restrictions:
+ * HTTP(S) only and no embedded credentials. The provider applies this before
+ * resolving a destination.
  *
  * @param input - the raw URL string from the fetch request.
- * @param maxUrlLength - inclusive upper bound on `input`'s length.
  * @returns the parsed `URL`.
  */
-export declare function validateFetchUrl(input: string, maxUrlLength: number): URL;
+export declare function parseFetchUrl(input: string): URL;
+/**
+ * Validate a request URL against the provider's complete pre-network policy:
+ * bounded length plus the restrictions enforced by {@link parseFetchUrl}.
+ * Public-address resolution and connection pinning run after this check.
+ *
+ * @param input - the raw URL string from the fetch request.
+ * @returns the parsed `URL`.
+ */
+export declare function validateFetchUrl(input: string): URL;
 /**
  * Two URLs are same-origin when scheme, hostname, and port match. A redirect
  * that crosses origins is refused so each new origin requires a fresh tool call
- * (and thus a fresh provider/permission decision).
+ * and public-address validation.
  *
  * @param a - one of the two URLs to compare.
  * @param b - the other URL to compare.

package/lib/types/provider.d.ts

@@ -1,17 +1,14 @@
 /**
- * Safe HTTP(S) retrieval for `ctx.web`: validates URLs, follows only same-origin redirects,
- * enforces time and size limits, classifies and decodes text, and leaves presentation to
- * `@xneog/dsh-tool-web`. Requests carry no browser cookies or ambient credentials.
- *
- * Private-network and SSRF protection is not implemented; do not enable this provider where
- * it can reach sensitive internal targets.
+ * Safe HTTP(S) retrieval for `ctx.web`: validates and pins public IP destinations, follows
+ * only same-origin redirects, enforces time and size limits, classifies and decodes text,
+ * and leaves presentation to `@xneog/dsh-tool-web`. Requests carry no browser cookies
+ * or ambient credentials.
  * @module @xneog/dsh-web-fetch-http/provider
  */
 import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@xneog/dsh-web';
+import type { PublicAddress } from './network.ts';
 /** Resolved provider limits (the plugin's schemastery Config supplies defaults). */
 export interface HttpFetchLimits {
-    /** Maximum accepted request URL length. */
-    maxUrlLength: number;
     /** Maximum response body size in bytes (read is aborted past this). */
     maxResponseBytes: number;
     /** Maximum decoded body length in characters (truncated past this). */
@@ -23,13 +20,20 @@ export interface HttpFetchLimits {
     /** `User-Agent` header sent on every request. */
     userAgent: string;
 }
+/** Resolve one hostname to an already policy-validated address set. */
+export type HttpFetchResolver = (hostname: string, signal: AbortSignal) => Promise<PublicAddress[]>;
 /** Stable id this provider registers under. */
 export declare const LOCAL_FETCH_PROVIDER_ID = "http";
 /** The anonymous public HTTP(S) fetch provider. */
 export declare class HttpFetchProvider implements WebFetchProvider {
     private readonly limits;
+    private readonly resolveAddresses;
     readonly id = "http";
-    constructor(limits: HttpFetchLimits);
+    /**
+     * @param limits - resolved transport and response limits.
+     * @param resolveAddresses - resolver that rejects non-public destinations before returning.
+     */
+    constructor(limits: HttpFetchLimits, resolveAddresses?: HttpFetchResolver);
     /** No credentials to check — an anonymous public fetcher is always usable. */
     available(): boolean;
     fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xneog/dsh-web-fetch-http",
   "description": "Anonymous public HTTP(S) fetch provider for the xneog web capability seam (ctx.web)",
-  "version": "0.1.0",
+  "version": "0.1.3-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -18,32 +18,29 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
-    "lib/invariant.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@xneog/dsh-invariants": "0.1.0",
-    "@xneog/dsh-timeout": "0.1.0",
-    "@xneog/dsh-web": "0.1.0",
-    "@xneog/cordis": "0.1.0"
+    "@xneog/cordis": "^4.0.2",
+    "@xneog/dsh-timeout": "^0.1.3-alpha.1",
+    "@xneog/dsh-http-proxy": "^0.1.3-alpha.1",
+    "@xneog/dsh-web": "^0.1.3-alpha.1"
   },
   "dependencies": {
-    "@xneog/schemastery": "0.1.0"
+    "ipaddr.js": "^2.5.0",
+    "undici": "^8.10.0",
+    "@xneog/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@xneog/dsh-invariants": "0.1.0",
-    "@xneog/dsh-timeout": "0.1.0",
-    "@xneog/dsh-web": "0.1.0",
-    "@xneog/cordis": "0.1.0"
+    "@xneog/cordis": "^4.0.2",
+    "@xneog/dsh-http-proxy": "^0.1.3-alpha.1",
+    "@xneog/dsh-timeout": "^0.1.3-alpha.1",
+    "@xneog/dsh-web": "^0.1.3-alpha.1"
   }
 }

package/lib/invariant.js

@@ -1,23 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@xneog/dsh-web-fetch-http`.
-* @module @xneog/dsh-web-fetch-http/invariant
-*/
-const PACKAGE_NAME = "@xneog/dsh-web-fetch-http";
-/** Cordis companion plugin name. */
-const name = "web-fetch-http-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: this package exposes no independent event sequence or mutable data relation
-* beyond contracts enforced at its owning seam.
-*/
-const install = () => {};
-/**
-* Register this package's invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@xneog/dsh-web-fetch-http`.
- * @module @xneog/dsh-web-fetch-http/invariant
- */
-import type { Context } from '@xneog/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "web-fetch-http-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map