@jayyuen66/dsh-plugin-shared 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @jayyuen66/dsh-plugin-shared
 
-[English](./README.md) · [简体中文](./README.zh.md)
+[English](./README.md) · [简体中文](./README.zh-CN.md)
 
 ## What this package is
 
@@ -33,7 +33,7 @@ End users do not install or enable it separately: any consumer package pulls it
 | | |
 | --- | --- |
 | Node.js | `^22.19.0 \|\| >=24.0.0`, the same clause as the harness root |
-| dsh | `>= 0.2.1-alpha.1`, declared as an **optional** peer (this package needs no host at import time) |
+| dsh | `>= 0.2.1-alpha.2`, declared as an **optional** peer (this package needs no host at import time) |
 | Module format | ESM only. `require()` works only where Node supports `require(esm)` |
 | Tree shaking | `"sideEffects": false` |
 
@@ -64,7 +64,7 @@ The subpath column is the in-package specifier; value imports must prefix it wit
 | `./lib/record` | `isRecord`, `fieldOf` |
 | `./lib/errors` | `errorText`: semantics aligned with the official `@deepseek-ai/dsh-llm` `errorChain` (cause chain, `AggregateError` members, empty message falling back to `name`, cross-realm `message` read off the value itself, hostile getters degraded), implemented locally with zero dependencies |
 | `./lib/jsonl` | `shrinkJsonlTail`: the pure decision half of JSONL tail halving; trigger policy and error exit stay with the caller |
-| `./lib/trust` | `requestTrust` / `guardTrust` / `trustRejectionText`: request-trust predicate for `/_dsh/*` endpoints (Host authority → `sec-fetch-site` allow-list → byte-exact Origin) |
+| `./lib/trust` | `requestTrust` / `guardTrust` / `trustRejectionText`: request-trust predicate for `/_dsh/*` endpoints (Host authority → `sec-fetch-site` allow-list → byte-exact Origin), plus `isNonLoopbackBindHost` to derive `servingNonLoopback` from the `webServer.host` bind literal |
 | `./lib/job-outcome` | `jobOutcomeOf` + `SettledProcess` + `JobOutcome`: maps a settled subprocess onto the official job registry's outcome |
 | `./lib/canonicalize-region-paths` | Build-time string helper that folds rolldown's `//#region <path>` markers into a `process.cwd()`-independent form. Exported as a subpath precisely because runtime consumers should not pay an import for it |
 
@@ -97,11 +97,12 @@ The sonarjs entry point is resolved lazily, inside `definePluginConfig()`. Impor
 
 ## Dependencies
 
-Seven declared dependencies, all `@deepseek-ai/*`:
+`dependencies` is empty; the seven `@deepseek-ai/*` packages appear only in `peerDependencies` and `devDependencies`. `test/publish-manifest.test.ts` enforces this — it is not a style preference:
 
-- `@deepseek-ai/dsh-output-retention` is a **value** import (`truncateEnd`), so it must ship as a dependency.
-- The other six are referenced only by the published `.d.ts`. They are declared because an undeclared type import does not fail loudly — it silently degrades. `lib/job-outcome` used to take `ShellProcess` and `JobOutcome` from packages no consumer tree was required to contain, so with `skipLibCheck: true` a wrong `status` or `exitCode` produced no error at all and `jobOutcomeOf`'s return type collapsed to `any`. Under pnpm's isolated layout none of them resolve at all.
-- Versions follow the host: exact pins inside the `dsh-*` family, `~` for `cordis`, matching what the host bundle itself declares so the same copy is reused rather than duplicated.
+- **Putting them in `dependencies` disables the consumer's host.** Consumers are dsh plugins installed into a profile (`nodeLinker: hoisted`, `autoInstallPeers: false`). Any host package listed under `dependencies` is written into the profile as a **real directory**, coexisting with the copy the host process already loaded. `@deepseek-ai/dsh-tools` keys its `TOOL_RUNTIME_SCHEDULER` with a plain `Symbol` (not `Symbol.for`), so symbol identity is per module instance: the host's `dsh-agent-loop` reads a `ToolRuntime` mounted from the duplicate using its own copy's symbol, gets `undefined`, and **every native tool call throws** `Cannot read properties of undefined (reading 'prepare')` — the whole profile loses its tools. This package's build, typecheck and tests all stay green right up to that point, so the invariant has to live in the manifest.
+- `@deepseek-ai/dsh-output-retention` is a **value** import (`truncateEnd`) and is provided by the host at runtime, so it is a required peer.
+- The other six are referenced only by the published `.d.ts`, so they are optional peers plus devDependencies: the peer keeps the type surface honest — `lib/job-outcome` used to take `ShellProcess` and `JobOutcome` from packages no consumer tree was required to contain, so with `skipLibCheck: true` a wrong `status` or `exitCode` produced no error at all and `jobOutcomeOf`'s return type collapsed to `any` — while devDependencies let this repository compile and test. Profiles never install peers, so no duplicate appears.
+- Versions follow the host: exact pins throughout the `dsh-*` family and for `cordis`, matching what the host bundle itself declares so the same copy is reused rather than duplicated.
 
 Known upstream limitation: `@deepseek-ai/dsh-llm`'s own declarations import `@deepseek-ai/dsh-attachment`, which it does not declare. It is reached transitively through `dsh-session`, so a consumer running with `skipLibCheck: false` sees `TS2307` from *that* package, not from this one.
 
@@ -110,7 +111,7 @@ Known upstream limitation: `@deepseek-ai/dsh-llm`'s own declarations import `@de
 `main` and `exports` point at `dist/` only. There is no second, source-shaped manifest.
 
 - `publishConfig` carries `access` and `registry` and nothing else. Putting `main`/`exports` there was wrong: pnpm merges those onto the top level when publishing and npm does not, so publishing with npm shipped a package whose fourteen entry points named files that were not in the tarball.
-- `files` is `icon.svg`, `dist`, `config/*.json`, `README.zh.md`. npm always adds `package.json`, `LICENSE` and `README.md`; `README.zh.md` is listed explicitly so the Chinese copy ships too.
+- `files` is `icon.svg`, `dist`, `config/*.json`, `README.zh-CN.md`. npm always adds `package.json`, `LICENSE` and `README.md`; `README.zh-CN.md` is listed explicitly so the Chinese copy ships too.
 - `build` starts by deleting `dist/`, because `files` takes the whole directory and a renamed facet would otherwise keep publishing its orphan artifact.
 - `prepare` runs `build`. It does not run when a consumer installs from the registry; it exists so packing, publishing and workspace links always ship a fresh `dist/`.
 - Node throws `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` for `.ts` inside `node_modules`, which is exactly where a published package is loaded from, so an artifact is mandatory. The barrel's declaration file is generated by `build-host.mjs` because source-form `export * from "./http.ts"` specifiers are not resolvable by consumers.
@@ -126,6 +127,7 @@ Known upstream limitation: `@deepseek-ai/dsh-llm`'s own declarations import `@de
 - **`errorText` now returns more text** (same name and signature). It went from a single `message` layer to the official `errorChain` semantics: a cause chain renders as `outer: inner`, an `AggregateError` appends `[e1; e2]`, an empty message falls back to `Error.name`, and a cross-realm `Error` yields its own `message` instead of `String()`'s `"Error: ..."`. **Callers that regex the old text must re-check** (a `exec` that pulls a number out of parentheses, for example).
 - `editPathOf` returns a `kind`-discriminated `EditTarget` with only `write` / `read-view`: `"skip"` was never produced, and leaving it in the type only pushed consumers into writing unreachable branches. When no path can be read it still returns the matching arm with `path` set to `undefined`.
 - `isCrossOrigin` / `queryParam` / `checkCsrf` / `requestTrust` / `guardTrust` widened their first parameter from `IncomingMessage` to `HttpRequest`. `readBody` / `guardBody` still take `IncomingMessage` because they consume the request body and `PartialRequest` does not guarantee async iteration.
+- **`servingNonLoopback` must now come from `isNonLoopbackBindHost(webServer.host)`, not from `webServer.host === "0.0.0.0"`.** Host 0.2.1-alpha.2 changed `@deepseek-ai/dsh-host-webserver`'s `Config.host` from the two-value union `'127.0.0.1' | '0.0.0.0'` to any concrete local-interface IP literal and started rejecting wildcard bind addresses at load. The old comparison is therefore constant `false`: a plugin bound to a real interface address stops recognizing its own authority, and every LAN request comes back `403 untrusted host authority`. `TrustOptions` is unchanged, so this is not an API break — it is a fix for a derivation that silently stopped working. `test/trust.test.ts` cross-checks the new predicate against the official `isLoopbackHost`, which became a public export in the same host release.
 
 ## Quality gates
 

package/{README.zh.md → README.zh-CN.md}

@@ -1,6 +1,6 @@
 # @jayyuen66/dsh-plugin-shared
 
-[English](./README.md) · [简体中文](./README.zh.md)
+[English](./README.md) · [简体中文](./README.zh-CN.md)
 
 ## 这个包是什么
 
@@ -33,7 +33,7 @@ import { readBody, sendJson } from "@jayyuen66/dsh-plugin-shared/lib/http";
 | | |
 | --- | --- |
 | Node.js | `^22.19.0 \|\| >=24.0.0`，与 harness 根同款 |
-| dsh | `>= 0.2.1-alpha.1`，声明为 **optional** peer（本包 import 时不需要宿主在场） |
+| dsh | `>= 0.2.1-alpha.2`，声明为 **optional** peer（本包 import 时不需要宿主在场） |
 | 模块形态 | 仅 ESM。`require()` 只在支持 `require(esm)` 的 Node 上可用 |
 | Tree shaking | `"sideEffects": false` |
 
@@ -64,7 +64,7 @@ import { readBody, sendJson } from "@jayyuen66/dsh-plugin-shared/lib/http";
 | `./lib/record` | `isRecord`、`fieldOf` |
 | `./lib/errors` | `errorText`：语义对齐官方 `@deepseek-ai/dsh-llm` 的 `errorChain`（cause 链、`AggregateError` 成员、空 message 回退 name、跨 realm 取自有 message、敌意 getter 降级），本地零依赖实现 |
 | `./lib/jsonl` | `shrinkJsonlTail`：JSONL 尾部收缩的纯决策件；触发策略与错误出口留给调用方 |
-| `./lib/trust` | `requestTrust` / `guardTrust` / `trustRejectionText`：`/_dsh/*` 端点的请求信任判据（Host 权威 → `sec-fetch-site` 白名单 → Origin 逐字比对） |
+| `./lib/trust` | `requestTrust` / `guardTrust` / `trustRejectionText`：`/_dsh/*` 端点的请求信任判据（Host 权威 → `sec-fetch-site` 白名单 → Origin 逐字比对）；`isNonLoopbackBindHost`：由 `webServer.host` 那枚绑定字面量取 `servingNonLoopback` |
 | `./lib/job-outcome` | `jobOutcomeOf` + `SettledProcess` + `JobOutcome`：把落定的子进程映射成官方作业注册表的结局 |
 | `./lib/canonicalize-region-paths` | 构建期字符串件：把 rolldown 写的 `//#region <路径>` 折成与 `process.cwd()` 无关的形态。之所以只给子路径，就是为了让运行期消费方不必为它付一次导入 |
 
@@ -97,11 +97,12 @@ sonarjs 的入口是**惰性解析**的，发生在 `definePluginConfig()` 内
 
 ## 依赖
 
-七条 `dependencies`，全是 `@deepseek-ai/*`：
+`dependencies` 是空的；七枚 `@deepseek-ai/*` 只出现在 `peerDependencies` 与 `devDependencies` 里。这条由 `test/publish-manifest.test.ts` 钉住，不是风格偏好：
 
-- `@deepseek-ai/dsh-output-retention` 是**值导入**（`truncateEnd` 用它），所以必须是依赖。
-- 其余六枚只被发布出去的 `.d.ts` 引用。之所以要声明，是因为未声明的类型导入不会大声报错，而是静默降级：`lib/job-outcome` 的 `ShellProcess`/`JobOutcome` 曾经来自消费方根本不保证存在的包，于是在 `skipLibCheck: true` 下写错 `status` 或 `exitCode` 一条都不报，返回值类型直接塌成 `any`；而 pnpm 的隔离布局下这些包压根解析不到。
-- 版本口径跟着宿主走：`dsh-*` 家族内用精确钉，`cordis` 用 `~`，与宿主本体自己声明的一致，这样是复用同一份而不是装出第二份。
+- **写进 `dependencies` 会让消费方的宿主瘫掉。** 消费方是 dsh 插件，被装进 profile（`nodeLinker: hoisted`、`autoInstallPeers: false`）。宿主包只要出现在 `dependencies`，pnpm 就在 profile 里把它们落成**真实目录**，与宿主进程里已有的那份并存。而 `@deepseek-ai/dsh-tools` 的 `TOOL_RUNTIME_SCHEDULER` 是普通 `Symbol`（不是 `Symbol.for`），符号身份按模块实例计算——宿主 `dsh-agent-loop` 拿自己那份的 Symbol 去读由副本挂载出来的 `ToolRuntime`，得到 `undefined`，于是**每一次原生工具调用都抛** `Cannot read properties of undefined (reading 'prepare')`，整个 profile 的工具一起失效。本包的构建、类型检查与测试在这之前全部照绿，所以判据只能落在 manifest 面。
+- `@deepseek-ai/dsh-output-retention` 是**值导入**（`truncateEnd` 用它），运行期由宿主提供，因此是非 optional 的 peer。
+- 其余六枚只被发布出去的 `.d.ts` 引用，声明成 optional peer 加 dev：peer 保住类型面不静默降级——`lib/job-outcome` 的 `ShellProcess`/`JobOutcome` 曾经来自消费方根本不保证存在的包，于是在 `skipLibCheck: true` 下写错 `status` 或 `exitCode` 一条都不报，返回值类型直接塌成 `any`；dev 让本包自己的编译与测试解析得到。profile 不装 peer，所以不产生副本。
+- 版本口径跟着宿主走：`dsh-*` 家族内一律精确钉，`cordis` 也精确钉，与宿主本体自己声明的一致，这样是复用同一份而不是装出第二份。
 
 已知的上游限制：`@deepseek-ai/dsh-llm` 的声明文件引用了它自己没声明的 `@deepseek-ai/dsh-attachment`。它经 `dsh-session` 传递进来，所以开 `skipLibCheck: false` 的消费方会看到来自**那个包**的 `TS2307`，不是来自本包。
 
@@ -110,7 +111,7 @@ sonarjs 的入口是**惰性解析**的，发生在 `definePluginConfig()` 内
 `main` 与 `exports` 只指 `dist/`，不存在第二套源码形态的 manifest。
 
 - `publishConfig` 只带 `access` 和 `registry`。把 `main`/`exports` 放在那里是错的：pnpm 发布时会把它们合并到顶层，npm 不会——用 npm 发出去的包，十四个入口指向的都是 tarball 里不存在的文件。
-- `files` 是 `icon.svg`、`dist`、`config/*.json`、`README.zh.md`。npm 永远附带 `package.json`、`LICENSE` 和 `README.md`；`README.zh.md` 显式列出才会一起发。
+- `files` 是 `icon.svg`、`dist`、`config/*.json`、`README.zh-CN.md`。npm 永远附带 `package.json`、`LICENSE` 和 `README.md`；`README.zh-CN.md` 显式列出才会一起发。
 - `build` 第一步删除 `dist/`：`files` 整目录收，切面一旦改名，上一代孤儿产物会继续被发出去。
 - `prepare` 挂 `build`。消费方从 registry 安装时它不执行；它存在是为了让打包、发布与 workspace link 拿到的都是新鲜 `dist/`。
 - 必须有编译产物：Node 对 `node_modules` 里的 `.ts` 直接抛 `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`，而发出去的包正是躺在那里被载入的。barrel 的声明文件由 `build-host.mjs` 生成，因为源码形态的 `export * from "./http.ts"` 消费方解析不到。
@@ -126,6 +127,7 @@ sonarjs 的入口是**惰性解析**的，发生在 `definePluginConfig()` 内
 - **`errorText` 的返回值变长了**（签名与名字不变）。它从"单层 message"扩成与官方 `errorChain` 同语义：cause 链拼成 `外: 内`、`AggregateError` 附 `[e1; e2]`、空 message 回退 `Error.name`、跨 realm 的 Error 取其自带 `message` 而不是 `String()` 的 `"Error: …"`。**依赖旧文本做正则匹配的调用方要重新核对**（例如按括号取数的那类 `exec`）。
 - `editPathOf` 的返回类型收成按 `kind` 判别的 `EditTarget`，只保留 `write` / `read-view` 两支——`"skip"` 从来不会被产出，留在类型里只会逼调用方写永不执行的分支。路径取不到时仍返回所属那一支、`path` 为 `undefined`。
 - `isCrossOrigin` / `queryParam` / `checkCsrf` / `requestTrust` / `guardTrust` 的首参数由 `IncomingMessage` **放宽**为 `HttpRequest`。`readBody` / `guardBody` 仍是 `IncomingMessage`：它们要消费请求体，而 `PartialRequest` 不保证可异步迭代。
+- **`servingNonLoopback` 现在要由 `isNonLoopbackBindHost(webServer.host)` 取，别再写 `webServer.host === "0.0.0.0"`。** 宿主 0.2.1-alpha.2 把 `@deepseek-ai/dsh-host-webserver` 的 `Config.host` 从 `'127.0.0.1' | '0.0.0.0'` 换成任意本机接口的 IP 字面量，并在载入时拒掉通配地址。于是那句旧比较恒为 false：绑在真实网卡地址上的插件认不出自己的权威，局域网来的请求整片吃 `403 untrusted host authority`。`TrustOptions` 的签名没动，所以这不是 API 破坏，而是一条**悄悄失效**的取值口径的修复。`test/trust.test.ts` 会把新谓词与官方 `isLoopbackHost`（同一次宿主发布里才转为公开导出）逐字面对表。
 
 ## 质量门
 

package/dist/index.js

@@ -1 +1 @@
-import{CROSS_ORIGIN_TEXT as e,checkCsrf as t,guardBody as n,isCrossOrigin as r,queryParam as i,readBody as a,sendJson as o}from"./http.js";import{fieldOf as s,isRecord as c}from"./record.js";import{editPathOf as l,parseToolArguments as u,scanToolEvents as d,toolArgumentsBad as f,toolEventRowsOf as p}from"./tool-events.js";import{claimApply as m}from"./card-apply.js";import{deriveProjectKey as h}from"./project-key.js";import{DEFAULT_LOCALE as g,LOCALE_PREFERENCE_FIELD as _,LOCALE_SETTINGS_NAMESPACE as v,messagesFor as y,resolveLocale as b,resolveLocalePreference as x}from"./locale.js";import{settleLessonCall as S}from"./lesson-bus.js";import{truncateEnd as C,truncateStart as w}from"./text.js";import{errorText as T}from"./errors.js";import{shrinkJsonlTail as E}from"./jsonl.js";import{guardTrust as D,requestTrust as O,trustRejectionText as k}from"./trust.js";import{jobOutcomeOf as A}from"./job-outcome.js";export{e as CROSS_ORIGIN_TEXT,g as DEFAULT_LOCALE,_ as LOCALE_PREFERENCE_FIELD,v as LOCALE_SETTINGS_NAMESPACE,t as checkCsrf,m as claimApply,h as deriveProjectKey,l as editPathOf,T as errorText,s as fieldOf,n as guardBody,D as guardTrust,r as isCrossOrigin,c as isRecord,A as jobOutcomeOf,y as messagesFor,u as parseToolArguments,i as queryParam,a as readBody,O as requestTrust,b as resolveLocale,x as resolveLocalePreference,d as scanToolEvents,o as sendJson,S as settleLessonCall,E as shrinkJsonlTail,f as toolArgumentsBad,p as toolEventRowsOf,C as truncateEnd,w as truncateStart,k as trustRejectionText};
+import{CROSS_ORIGIN_TEXT as e,checkCsrf as t,guardBody as n,isCrossOrigin as r,queryParam as i,readBody as a,sendJson as o}from"./http.js";import{fieldOf as s,isRecord as c}from"./record.js";import{editPathOf as l,parseToolArguments as u,scanToolEvents as d,toolArgumentsBad as f,toolEventRowsOf as p}from"./tool-events.js";import{claimApply as m}from"./card-apply.js";import{deriveProjectKey as h}from"./project-key.js";import{DEFAULT_LOCALE as g,LOCALE_PREFERENCE_FIELD as _,LOCALE_SETTINGS_NAMESPACE as v,messagesFor as y,resolveLocale as b,resolveLocalePreference as x}from"./locale.js";import{settleLessonCall as S}from"./lesson-bus.js";import{truncateEnd as C,truncateStart as w}from"./text.js";import{errorText as T}from"./errors.js";import{shrinkJsonlTail as E}from"./jsonl.js";import{guardTrust as D,isNonLoopbackBindHost as O,requestTrust as k,trustRejectionText as A}from"./trust.js";import{jobOutcomeOf as j}from"./job-outcome.js";export{e as CROSS_ORIGIN_TEXT,g as DEFAULT_LOCALE,_ as LOCALE_PREFERENCE_FIELD,v as LOCALE_SETTINGS_NAMESPACE,t as checkCsrf,m as claimApply,h as deriveProjectKey,l as editPathOf,T as errorText,s as fieldOf,n as guardBody,D as guardTrust,r as isCrossOrigin,O as isNonLoopbackBindHost,c as isRecord,j as jobOutcomeOf,y as messagesFor,u as parseToolArguments,i as queryParam,a as readBody,k as requestTrust,b as resolveLocale,x as resolveLocalePreference,d as scanToolEvents,o as sendJson,S as settleLessonCall,E as shrinkJsonlTail,f as toolArgumentsBad,p as toolEventRowsOf,C as truncateEnd,w as truncateStart,A as trustRejectionText};

package/dist/trust.js

@@ -1 +1 @@
-import{CROSS_ORIGIN_TEXT as e,sendJson as t}from"./http.js";import n from"node:os";const r=/* @__PURE__ */ new Set([`localhost`,`[::1]`]),i=/* @__PURE__ */ new Set([`same-origin`,`none`]),a=`bad-origin`;function o(e,t){let n=e.headers?.[t];return n===void 0?null:Array.isArray(n)?n.length===1?n.join(``):null:n}const s=/^[A-Za-z0-9._\-[\]:%]+$/u;function c(e){if(!s.test(e))return null;try{return new URL(`http://${e}`)}catch{return null}}function l(e){let t=e.toLowerCase();if(r.has(t))return!0;let n=t.split(`.`);return n.length===4&&n[0]===`127`&&n.every(e=>/^\d{1,3}$/u.test(e)&&Number(e)<=255)}function u(){let e=[];for(let t of Object.values(n.networkInterfaces()))for(let{family:n,address:r}of t??[])e.push(n===`IPv6`?`[${r}]`:r);return e}function d(e,t){return l(e)?!0:t.servingNonLoopback===!0&&(t.localInterfaceAddresses??u()).includes(e)}function f(e){let t=o(e,`sec-fetch-site`);return t===null||i.has(t)}function p(e){let t=e.socket?.remoteAddress;if(typeof t!=`string`||t===``)return null;let n=t.replaceAll(/^\[|\]$/gu,``).replace(/^::ffff:/iu,``);return l(n)||n===`::1`}function m(e,t){let n=e.headers?.host;if(Array.isArray(n)&&n.length!==1)return`rejected`;let r=o(e,`host`);if(r===null)return p(e)===!1?`rejected`:null;let i=c(r);return i===null||!d(i.hostname,t)?`rejected`:i}function h(e,t={}){let n=m(e,t);if(n===`rejected`)return`untrusted-host`;if(!f(e))return`cross-site`;let r=o(e,`origin`);if(r===null)return`trusted`;if(r===`null`||n===null)return a;let i=c(r.replace(/^[a-z][a-z0-9+.-]*:\/\//iu,``));return i===null?a:i.host===n.host?`trusted`:a}function g(t){return t===`untrusted-host`?`untrusted host authority`:e}function _(e,n,r={}){let i=h(e,r);return i===`trusted`?!0:n.headersSent||n.writableEnded?(console.error(`[shared/trust] rejecting after headers were sent:`,i),!1):(t(n,403,{ok:!1,error:g(i)}),!1)}export{_ as guardTrust,h as requestTrust,g as trustRejectionText};
+import{CROSS_ORIGIN_TEXT as e,sendJson as t}from"./http.js";import n from"node:os";import{isIPv4 as r,isIPv6 as i}from"node:net";const a=/* @__PURE__ */ new Set([`localhost`,`[::1]`]),o=/* @__PURE__ */ new Set([`same-origin`,`none`]);function s(e){let t=new URL(`http://[${e.split(`%`,1).join(``)}]`).hostname;return t===`[::1]`||t.startsWith(`[::ffff:7f`)}function c(e){return e===void 0?!1:r(e)?e.split(`.`,1).join(``)!==`127`:i(e)&&!s(e)}const l=`bad-origin`;function u(e,t){let n=e.headers?.[t];return n===void 0?null:Array.isArray(n)?n.length===1?n.join(``):null:n}const d=/^[A-Za-z0-9._\-[\]:%]+$/u;function f(e){if(!d.test(e))return null;try{return new URL(`http://${e}`)}catch{return null}}function p(e){let t=e.toLowerCase();if(a.has(t))return!0;let n=t.split(`.`);return n.length===4&&n[0]===`127`&&n.every(e=>/^\d{1,3}$/u.test(e)&&Number(e)<=255)}function m(){let e=[];for(let t of Object.values(n.networkInterfaces()))for(let{family:n,address:r}of t??[])e.push(n===`IPv6`?`[${r}]`:r);return e}function h(e,t){return p(e)?!0:t.servingNonLoopback===!0&&(t.localInterfaceAddresses??m()).includes(e)}function g(e){let t=u(e,`sec-fetch-site`);return t===null||o.has(t)}function _(e){let t=e.socket?.remoteAddress;if(typeof t!=`string`||t===``)return null;let n=t.replaceAll(/^\[|\]$/gu,``).replace(/^::ffff:/iu,``);return p(n)||n===`::1`}function v(e,t){let n=e.headers?.host;if(Array.isArray(n)&&n.length!==1)return`rejected`;let r=u(e,`host`);if(r===null)return _(e)===!1?`rejected`:null;let i=f(r);return i===null||!h(i.hostname,t)?`rejected`:i}function y(e,t={}){let n=v(e,t);if(n===`rejected`)return`untrusted-host`;if(!g(e))return`cross-site`;let r=u(e,`origin`);if(r===null)return`trusted`;if(r===`null`||n===null)return l;let i=f(r.replace(/^[a-z][a-z0-9+.-]*:\/\//iu,``));return i===null?l:i.host===n.host?`trusted`:l}function b(t){return t===`untrusted-host`?`untrusted host authority`:e}function x(e,n,r={}){let i=y(e,r);return i===`trusted`?!0:n.headersSent||n.writableEnded?(console.error(`[shared/trust] rejecting after headers were sent:`,i),!1):(t(n,403,{ok:!1,error:b(i)}),!1)}export{x as guardTrust,c as isNonLoopbackBindHost,y as requestTrust,b as trustRejectionText};

package/dist/types/trust.d.ts

@@ -4,11 +4,32 @@ import type { HttpRequest } from "./http.ts";
 export type TrustVerdict = "trusted" | "untrusted-host" | "cross-site" | "bad-origin";
 /** `requestTrust` / `guardTrust` 的可选入参。 */
 export interface TrustOptions {
-    /** 宿主是否绑在非回环地址上（`webServer.host === "0.0.0.0"`）。缺省按 false（保守）。 */
+    /**
+     * 宿主是否绑在非回环地址上——由 `isNonLoopbackBindHost(webServer.host)` 取，**不要**再自己比
+     * 字面量。缺省按 false（保守）。
+     */
     servingNonLoopback?: boolean;
     /** 注入本机地址面（测试用；缺省取 `os.networkInterfaces()` 的实际值）。 */
     localInterfaceAddresses?: readonly string[];
 }
+/**
+ * 绑定地址的字面量谓词：`webServer.host` → {@link TrustOptions.servingNonLoopback}。
+ *
+ * 为什么现在要由本包出这个谓词：`@deepseek-ai/dsh-host-webserver` 的 `Config.host` 在宿主
+ * 0.2.1-alpha.2 从 `'127.0.0.1' | '0.0.0.0'` 换成**任意本机接口 IP 字面量**，并把通配地址
+ * （`0.0.0.0`、`::` 及其映射形）**在载入时拒掉**。于是消费方沿用至今的那行
+ * `webServer.host === "0.0.0.0"` 恒为 false——非回环服务面换了形态（一枚真的网卡地址），
+ * 判据却还盯着那枚再也绑不上的字面量，局域网访问会被本模块整片拒成 403。
+ *
+ * 口径与官方 `isLoopbackHost` 对齐（台架见 `test/trust.test.ts`）。一处**刻意**分歧：非字面量
+ * （`localhost`、带方括号的 `[::1]`）本函数按 false，官方那侧 `!isLoopbackHost` 得 true。
+ * 宿主自身的 config 校验已经拒掉非字面量，那种值到不了这里；万一到了，false 收紧而非放宽
+ * 可放行的 Host 权威——这个方向上宁可错杀。
+ *
+ * @param host - `webServer.host` 的绑定值；读不到（缺字段、空串、非字面量）按只绑回环处理
+ * @returns 绑的是非回环接口地址时为 true
+ */
+export declare function isNonLoopbackBindHost(host: string | undefined): boolean;
 /**
  * 一次判据：Host 权威 → sec-fetch-site（白名单）→ Origin 逐字比对。
  * 纯函数、不写响应；写响应的样板在 `guardTrust`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayyuen66/dsh-plugin-shared",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "dsh 自研插件的共享工具库：tool 事件流记账扫描 + webServer HTTP 样板（sendJson/CORS/CSRF/body 限制）+ 卡片 apply 骨架 + 项目键派生 + 代理对安全截断。作为库包被 import，不由用户启用",
   "keywords": [
     "cordis",
@@ -24,7 +24,7 @@
     "icon.svg",
     "dist",
     "config/*.json",
-    "README.zh.md"
+    "README.zh-CN.md"
   ],
   "type": "module",
   "sideEffects": false,
@@ -103,41 +103,65 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "dependencies": {
-    "@deepseek-ai/cordis": "4.0.5-alpha.1",
-    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-output-retention": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-shell": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.1"
-  },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
-    "@types/node": "26.6.3",
-    "@vitest/coverage-v8": "5.0.2",
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-output-retention": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
+    "@types/node": "26.6.5",
+    "@vitest/coverage-v8": "5.0.3",
     "eslint-plugin-sonarjs": "4.2.2",
-    "oxfmt": "0.71.0",
-    "oxlint": "1.86.0",
-    "oxlint-tsgolint": "7.0.2003",
-    "rolldown": "1.2.11",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
+    "oxlint-tsgolint": "7.0.2004",
+    "rolldown": "1.2.13",
     "typescript": "7.0.2",
-    "vite": "8.3.1",
-    "vitest": "5.0.2"
+    "vite": "8.3.4",
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": "^0.2.1-alpha.1"
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-output-retention": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2"
   },
   "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
     "@deepseek-ai/dsh": {
       "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-jobs": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-shell": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
     }
   },
   "icon": "icon.svg",
   "engines": {
-    "dsh": ">=0.2.1-alpha.1",
+    "dsh": ">=0.2.1-alpha.2",
     "node": "^22.19.0 || >=24.0.0"
   },
   "scripts": {