@mzzsfy/dsh-auto-trust-all 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @mzzsfy/dsh-auto-trust-all
+
+DeepSeek Harness web 入口插件:动态信任所有实际到达的 Host,并将 web 默认绑定翻转为全部网卡——`dsh web` 零参数启动等效 `dsh web --host 0.0.0.0 --trusted-host=<任何实际到达的 host>`。
+
+设计文档见 [docs/design/dsh-auto-trust-all.md](../../docs/design/dsh-auto-trust-all.md)。
+
+## 功能
+
+- **动态信任**:包装 webServer 全部路由(exact / prefix / upgrade / fallback,含激活前已注册与后续新注册),请求到达即提取 Host 头(与官方信任闸门同构的 WHATWG 解析:小写、去端口、IPv6 保留方括号),去重后注册进 `webRuntime.trustedHosts`,闸门每请求实时读数组,无需重启。泛域名(`*.example.com`)等无法枚举的入口不再需要改启动命令。
+- **FIFO 容量**:注册域名容量 `maxHosts` 默认 100,超出按注册先后淘汰最早者;官方初始条目(部署派生的局域网 IP 等)不参与淘汰。内存总量恒定有界。容量按激活代记账:插件重载前注册的条目留存于信任清单但不参与新一代记账,重启即归零。
+- **console 输出**:启动时输出一行状态横幅(绑定、容量、既有信任条目);此后每次注册输出 `auto-trust-all: registered host <域名>`、每次淘汰输出 `auto-trust-all: evicted host <域名>`,直接 grep dsh console 即可做入口审计。
+- **默认绑定翻转**:bundle patch 覆盖官方 webserver 行的 host 默认值为 `0.0.0.0`;显式 `--host 127.0.0.1` 仍生效(表达式读 webStartup 服务,只翻默认值)。
+- **认证层不动**:只影响官方 Host/Origin 信任闸门(官方文档明言"绝不建立身份"的可达性闸门);原生浏览器 cookie 认证与 dsh-web-startup-auth 会话闸门原样保留,安全增量趋近于零。
+- **干净降级**:冷启动时 `webRuntime` 尚未就绪属预期,插件挂服务激活事件自动延迟启用;官方 web 面形态变化导致其真缺失时保持静默待命,不产生启动 pending、不影响 dsh 启动与其余功能。
+
+## 配置(无 GUI)
+
+唯一配置项 `maxHosts`(注册域名容量,自然数,默认 100)。走 cordis 行级配置,在 profile 的 `cordis.patch.yml`(或 `~/.dsh/cordis.patch.yml`)追加覆盖行,重启 dsh web 生效:
+
+```yaml
+- id: auto-trust-all
+  config:
+    maxHosts: 200
+```
+
+容量按激活代记账:修改 `maxHosts` 需重启 dsh web 生效,新容量只约束其后注册的条目,插件热重载换代的遗留条目视同官方条目留存;重启 dsh web 则动态条目全部归零。
+
+## 安装
+
+任何 `dsh plugin add`(开发或发布安装)都会把 node_modules 里的既有 junction 重建为实体目录,装完必须重跑 `node scripts/dev-link.mjs all` 恢复工作副本挂载,否则改仓库源码不生效。
+
+发布版安装:
+
+```sh
+dsh plugin --profile web add @mzzsfy/dsh-auto-trust-all
+```
+
+发布前开发安装(在仓库根目录执行——`file:` 相对路径按执行时所在目录锚定):
+
+```sh
+dsh plugin --profile web add file:./packages/dsh-auto-trust-all
+```
+
+bundle patch 随下次 dsh 重启生效。开发安装的依赖行是 `file:` 过渡态,发布后由 `dev-link.mjs all` 归一为 semver。
+
+patch 覆盖官方 webserver 行的 config 是整体替换语义,本包已完整镜像官方全部键;该镜像由 `test/patch.test.mjs` 快照锁定——但该测试读不到官方安装目录,**不能**自动检出上游增删键。dsh 升级后请用 `dsh web --dump-default-config` 对照官方 webserver 行核对键集,发现新键需同步 `cordis.patch.yml`。
+
+## 与其他插件的关系
+
+- **dsh-web-startup-auth**:完全共存。本插件不提供任何 cordis 服务,零服务冲突;两者都会遮蔽 webServer 注册方法包装路由,委托链在任意激活顺序下保持正确(会话检查与 Host 注册同时生效)。未认证请求至多完成 Host 登记(纯观察),首个拦截点始终是会话闸门。
+- **dream-skin 等同构自守卫插件**:同样实时读 `webRuntime.trustedHosts`,本插件的注册对它们同步生效。
+
+## 安全边界
+
+放行的是可达性闸门:攻击者可让任意域名指向本服务并到达登录页(受 startup-auth IP 限速约束),拿不到任何数据。闸门内建的 `sec-fetch-site: cross-site` 拒绝与 Origin 同源检查独立于信任清单,不受本插件影响。泛解析范围控制与防火墙仍是运维责任。
+
+原生 cookie 会话按 `主机:端口` 绑定,每个新入口(各子域、各内网 IP 形态)都需要各自登录一次——这是 dsh 原生行为,与本插件无关。
+
+## 开发
+
+```sh
+cd packages/dsh-auto-trust-all
+node --test "test/*.test.mjs"
+```
+
+宿主半区改动经 dev-link junction 热重载;冒烟验证步骤见设计文档。

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# The auto-trust-all bundle patch, two operations in order:
+# 1. Override the official webserver row's config: the host default flips from
+#    loopback to all-interfaces, so a bare `dsh web` equals
+#    `dsh web --host 0.0.0.0`; an explicit `--host` still wins because the
+#    expression reads the webStartup service. The config object REPLACES the
+#    row's config wholesale (patch semantics are not a deep merge), so every
+#    official key is mirrored here; sync this list when upstream changes it.
+#    The name field guards against id collision: a mismatching row is skipped
+#    with a loader warning instead of being clobbered.
+# 2. Insert this plugin as one entry; its host half wraps webServer routes and
+#    registers every arriving Host header into webRuntime.trustedHosts.
+
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  config:
+    host: !!js ctx.webStartup.host ?? '0.0.0.0'
+    port: !!js ctx.webStartup.port ?? 3080
+    compression: gzip
+    compressionLevel: 1
+    compressionThresholdBytes: 1024
+
+- insert:
+    - id: auto-trust-all
+      name: '@mzzsfy/dsh-auto-trust-all'

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mzzsfy/dsh-auto-trust-all",
+  "description": "动态信任所有实际到达的 Host:包装 webServer 路由把 Host 头实时注册进 webRuntime.trustedHosts,并将 web 默认绑定翻转为 0.0.0.0,泛域名入口免改启动命令;认证层(原生 cookie 与 startup-auth 会话)原样保留",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "npmPublish": "npm publish --access public --provenance=false --registry=https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.1014.top:83/mzzsfy/dsh-plugin.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "files": [
+    "src",
+    "test",
+    "cordis.patch.yml",
+    "README.md"
+  ]
+}

package/src/index.js

@@ -0,0 +1,159 @@
+// dsh-auto-trust-all Host 半区:把每个实际到达请求的 Host 头注册进
+// webRuntime.trustedHosts,令官方 Host/Origin 信任闸门(可达性闸门,官方文档
+// 明言"绝不建立身份")对泛域名等无法枚举的入口动态放行;原生 cookie 认证与
+// startup-auth 会话闸门不受影响。注册容量 FIFO 淘汰,启动状态与每次注册、
+// 淘汰均直接输出到 console,供用户确认生效与入口审计。
+
+import z from '@deepseek-ai/schemastery'
+
+export const name = 'dsh-auto-trust-all'
+
+// 仅静态声明跨版本基座服务;webRuntime 版本面较新且与本插件在同一波激活中
+// 就绪(strict get 要求提供方 fiber 已激活),按 AGENTS.md 兼容性规约走
+// 事件延迟激活,真缺失时保持静默订阅,不产生 pending
+export const inject = ['webServer']
+
+// 注册域名容量:约束本插件注册的条目(FIFO 淘汰最早者),下界 1 防零容量死循环;
+// 官方初始条目(局域网 IP 等)由部署派生,不在淘汰范围
+export const Config = z.object({
+  maxHosts: z.number().step(1).min(1).default(100).description('注册域名容量,超出按注册先后淘汰'),
+})
+
+// 闸门同构提取:new URL('http://' + authority).hostname,小写、去端口、IPv6 保留方括号
+function hostnameOf(headers) {
+  const header = headers ? headers.host : undefined
+  if (typeof header !== 'string' || header === '') return undefined
+  try {
+    return new URL('http://' + header).hostname
+  } catch {
+    return undefined
+  }
+}
+
+/** @param {import('@deepseek-ai/cordis').Context} ctx */
+export function apply(ctx, config) {
+  const maxHosts = config.maxHosts
+  const webServer = ctx.webServer
+  const ready = () => Array.isArray(ctx.get('webRuntime')?.trustedHosts)
+  let activated = false
+  let unregisterFailed = false
+
+  const activate = () => {
+    if (activated) return
+    const initialHosts = ctx.get('webRuntime')?.trustedHosts
+    if (!Array.isArray(initialHosts)) return
+    activated = true
+
+    const seen = new Set()
+    // FIFO 队列与去重集合同进出(淘汰即双删),规模随容量封顶;
+    // 两者与信任数组绑定,webRuntime 重建提供新数组时一并清空,旧域名重新登记
+    const queue = []
+    let seenFor = null
+
+    const registerHost = (req) => {
+      const hosts = ctx.get('webRuntime')?.trustedHosts
+      if (!Array.isArray(hosts)) return
+      if (hosts !== seenFor) {
+        seenFor = hosts
+        seen.clear()
+        queue.length = 0
+      }
+      const hostname = hostnameOf(req && req.headers)
+      if (hostname === undefined || seen.has(hostname)) return
+      // 数组查重:激活前已存在的条目(官方初始条目)只记入去重集合,不入淘汰队列
+      if (hosts.includes(hostname)) {
+        seen.add(hostname)
+        return
+      }
+      while (queue.length >= maxHosts) {
+        const oldest = queue.shift()
+        seen.delete(oldest)
+        const index = hosts.indexOf(oldest)
+        if (index < 0) continue
+        hosts.splice(index, 1)
+        console.log('auto-trust-all: evicted host ' + oldest)
+        break
+      }
+      seen.add(hostname)
+      queue.push(hostname)
+      hosts.push(hostname)
+      console.log('auto-trust-all: registered host ' + hostname)
+    }
+
+    // 注册函数挂载为 webServer 上的共享载体:插件重载/行级 config 变更时新
+    // activate 覆盖它,旧代包装动态改道到最新一代
+    webServer.autoTrustAllRegister = registerHost
+
+    // 标记防重复包装:本插件重载后旧包装仍在路由表内,已标记的 handler 不再叠加,
+    // 经共享载体继续服务
+    const WRAPPED = 'autoTrustAllWrapped'
+    const wrap = (handler) => {
+      if (typeof handler !== 'function' || handler[WRAPPED]) return handler
+      const wrapped = async (...args) => {
+        try {
+          const register = webServer.autoTrustAllRegister
+          register(args[0])
+        } catch (error) {
+          // 注册是纯观察,失败不阻断请求;限频告警防风暴
+          if (!unregisterFailed) {
+            unregisterFailed = true
+            console.warn('auto-trust-all: 注册调用失败,后续不再提示: ' + (error instanceof Error ? error.message : String(error)))
+          }
+        }
+        return handler(...args)
+      }
+      wrapped[WRAPPED] = true
+      return wrapped
+    }
+    const wrapRoute = (route) => {
+      route.handler = wrap(route.handler)
+    }
+
+    // 回溯:激活前已注册的路由原地替换 handler,请求分发实时读该属性即生效
+    for (const route of webServer.exact.values()) wrapRoute(route)
+    for (const route of webServer.prefixes.values()) wrapRoute(route)
+    for (const route of webServer.upgrades.values()) wrapRoute(route)
+    if (webServer.fallback !== undefined) webServer.fallback = wrap(webServer.fallback)
+
+    // 遮蔽注册方法拦截后续注册;委托捕获时的当前值而非原型方法,与 startup-auth
+    // 的同类遮蔽在任意激活顺序下都保持链式,不绕过它的会话包装;影子自身带标记,
+    // 重复激活不叠加遮蔽层
+    const SHADOWED = 'autoTrustAllShadowed'
+    const shadowMethod = (method, delegate) => {
+      const previous = webServer[method]
+      if (typeof previous !== 'function' || previous[SHADOWED]) return
+      const shadow = (argument) => delegate(argument, previous)
+      shadow[SHADOWED] = true
+      webServer[method] = shadow
+    }
+    shadowMethod('register', (route, previous) => {
+      wrapRoute(route)
+      return previous.call(webServer, route)
+    })
+    shadowMethod('registerUpgrade', (route, previous) => {
+      wrapRoute(route)
+      return previous.call(webServer, route)
+    })
+    shadowMethod('registerFallback', (handler, previous) => previous.call(webServer, wrap(handler)))
+
+    // 启动横幅:绑定、容量与既有信任条目一屏可见
+    console.log('auto-trust-all: 动态信任已启用 (bind ' + webServer.host + ', 容量 ' + maxHosts + '), 既有信任 ' + initialHosts.length + ' 项: ' + (initialHosts.join(', ') || '无'))
+  }
+
+  if (ready()) {
+    activate()
+  } else {
+    // 冷启动时序:webRuntime 提供方与本插件在同一波激活中,其 fiber 完成激活
+    // (转 state 2)时会对自有服务发 internal/service,彼时 strict get 可解析
+    console.log('auto-trust-all: webRuntime 未就绪,待其激活后自动启用')
+    ctx.on('internal/service', (name) => {
+      if (name === 'webRuntime') activate()
+    })
+  }
+
+  // 卸载即断开注册:载体置空函数,旧代包装退化为纯透传,信任放行随插件移除停止
+  return () => {
+    activated = true
+    webServer.autoTrustAllRegister = () => {}
+  }
+}

package/test/patch.test.mjs

@@ -0,0 +1,30 @@
+// patch 文件形态断言:覆盖 webserver 行的 config 是整体替换语义(不深合并),
+// 本包必须镜像官方全部键。此测试只读本包 patch 文本,锁本地镜像形态快照——
+// 它读不到官方安装目录,上游增删键不会在此失败;dsh 升级后须用
+// `dsh web --dump-default-config` 对照官方 webserver 行核对键集。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const patchText = readFileSync(join(PKG_ROOT, 'cordis.patch.yml'), 'utf8')
+
+test('场景10 patch 形态: Given bundle patch Then webserver 行 name 防御且 host 默认翻转为全接口', () => {
+  // name 字段是 id 撞车防御:官方行改名即跳过并告警,而非误写他方行
+  assert.match(patchText, /- id: webserver\n  name: '@deepseek-ai\/dsh-host-webserver'/)
+  assert.match(patchText, /host: !!js ctx\.webStartup\.host \?\? '0\.0\.0\.0'/)
+})
+
+test('场景10 镜像契约: config 整体替换要求官方行全部键在场', () => {
+  // 与官方 dsh-web-app bundle 的 webserver config 逐键镜像,官方增删键时此处失败
+  assert.match(patchText, /port: !!js ctx\.webStartup\.port \?\? 3080/)
+  assert.match(patchText, /compression: gzip/)
+  assert.match(patchText, /compressionLevel: 1/)
+  assert.match(patchText, /compressionThresholdBytes: 1024/)
+})
+
+test('场景10 插件行: insert 操作指向本包', () => {
+  assert.match(patchText, /- insert:\n    - id: auto-trust-all\n      name: '@mzzsfy\/dsh-auto-trust-all'/)
+})

package/test/wrap.test.mjs

@@ -0,0 +1,414 @@
+// 包装行为测试:mock webServer(实例形态与官方一致:三 Map + fallback 字段 +
+// 原型注册方法)与 mock webRuntime/ctx,不起真服务器。
+// Given-When-Then 场景见各用例注释,规格源 docs/design/dsh-auto-trust-all.md。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { apply, Config } from '../src/index.js'
+
+const DEFAULT_MAX_HOSTS = 100
+
+class MockWebServer {
+  exact = new Map()
+  prefixes = new Map()
+  upgrades = new Map()
+  fallback = undefined
+
+  constructor(host = '0.0.0.0') {
+    this.host = host
+  }
+
+  register(route) {
+    const table = route.kind === 'exact' ? this.exact : this.prefixes
+    table.set(route.path, route)
+    return () => table.delete(route.path)
+  }
+
+  registerUpgrade(route) {
+    this.upgrades.set(route.path, route)
+    return () => this.upgrades.delete(route.path)
+  }
+
+  registerFallback(handler) {
+    this.fallback = handler
+    return () => { this.fallback = undefined }
+  }
+}
+
+// 构造最小插件上下文:webServer 静态注入,webRuntime 经 ctx.get 可选探测
+// (与真实 cordis 语义一致),holder.current 支持测试中延迟就绪或换代;
+// ctx.on 收集事件监听器供模拟触发;console 输出经 t.mock 捕获,测试结束自动还原
+function createCtx({ trustedHosts = [], host = '0.0.0.0', webRuntimeReady = true } = {}) {
+  const webServer = new MockWebServer(host)
+  const holder = { current: webRuntimeReady ? { trustedHosts } : undefined }
+  const listeners = []
+  const ctx = {
+    webServer,
+    get: (name) => (name === 'webRuntime' ? holder.current : undefined),
+    on: (name, listener) => {
+      listeners.push([name, listener])
+      return () => {}
+    },
+  }
+  return { ctx, webServer, holder, trustedHosts, listeners }
+}
+
+const mockConsole = (t) => {
+  const output = []
+  t.mock.method(console, 'log', (...args) => output.push(['log', args.join(' ')]))
+  t.mock.method(console, 'warn', (...args) => output.push(['warn', args.join(' ')]))
+  return output
+}
+
+test('场景1 回溯包装: Given 激活前已注册路由 When 未注册 Host 请求到达 Then hostname 进信任清单且原 handler 透传', async (t) => {
+  const output = mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  const calls = []
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async (req, res) => { calls.push([req, res]) } })
+  webServer.register({ kind: 'prefix', path: '/api', handler: async () => { calls.push('prefix') } })
+  webServer.registerUpgrade({ path: '/ws', handler: async () => { calls.push('upgrade') } })
+
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  const route = webServer.exact.get('/api/x')
+  const req = { headers: { host: 'probe.jze100.com' } }
+  const res = {}
+  await route.handler(req, res)
+  await webServer.prefixes.get('/api').handler(req, res)
+  await webServer.upgrades.get('/ws').handler(req, {}, null)
+
+  assert.deepEqual(trustedHosts, ['probe.jze100.com'])
+  assert.equal(calls.length, 3)
+  assert.equal(calls[0][0], req)
+  assert.equal(calls[0][1], res)
+  assert.ok(output.some(([, message]) => message === 'auto-trust-all: registered host probe.jze100.com'))
+})
+
+test('场景2 去重: Given 同一 Host 重复请求 Then 数组只增一条', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'probe.jze100.com' } }, {})
+  await route.handler({ headers: { host: 'probe.jze100.com' } }, {})
+  await route.handler({ headers: { host: 'probe.jze100.com:8443' } }, {})
+
+  assert.deepEqual(trustedHosts, ['probe.jze100.com'])
+})
+
+test('场景3 提取形态: Given 带端口或大小写或 IPv6 括号的 Host 头 Then 注册闸门比较形态的 hostname', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'Probe.Jze100.com:8443' } }, {})
+  await route.handler({ headers: { host: '[::1]:3080' } }, {})
+
+  // WHATWG hostname 对 IPv6 保留方括号,与闸门 parseAuthority 的比较形态一致
+  assert.deepEqual(trustedHosts, ['probe.jze100.com', '[::1]'])
+})
+
+test('场景4 FIFO 容量: Given 达到 maxHosts When 新 Host 到达 Then 淘汰最早注册者且总量恒定', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: 2 })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'first.test' } }, {})
+  await route.handler({ headers: { host: 'second.test' } }, {})
+  await route.handler({ headers: { host: 'third.test' } }, {})
+
+  assert.deepEqual(trustedHosts, ['second.test', 'third.test'])
+})
+
+test('场景13 官方条目保护: Given 官方初始条目在场 When FIFO 淘汰 Then 只淘汰本插件注册的条目', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx({ trustedHosts: ['192.168.1.5'] })
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: 1 })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'first.test' } }, {})
+  await route.handler({ headers: { host: 'second.test' } }, {})
+
+  assert.deepEqual(trustedHosts, ['192.168.1.5', 'second.test'])
+})
+
+test('场景5 影子注册: Given 激活后新注册的路由 When 请求到达 Then 同样注册 Host 且注册语义不变', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  const disposer = webServer.register({ kind: 'exact', path: '/api/new', handler: async () => {} })
+  await webServer.exact.get('/api/new').handler({ headers: { host: 'late.jze100.com' } }, {})
+  disposer()
+
+  assert.deepEqual(trustedHosts, ['late.jze100.com'])
+  assert.equal(webServer.exact.has('/api/new'), false)
+})
+
+test('场景12 影子 upgrade: Given 激活后经影子方法注册的 upgrade 路由 When 请求到达 Then 同样注册 Host', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  webServer.registerUpgrade({ path: '/ws/new', handler: async () => {} })
+  await webServer.upgrades.get('/ws/new').handler({ headers: { host: 'ws.jze100.com' } }, {}, null)
+
+  assert.deepEqual(trustedHosts, ['ws.jze100.com'])
+})
+
+test('场景6a 影子链: Given 会话层先遮蔽注册方法 When 本插件激活后新路由注册 Then 会话包装与 Host 注册同时生效', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  // 模拟 startup-auth 先激活:实例属性遮蔽 register,包装 handler 模拟会话检查
+  const sessionChecked = []
+  const prototypeRegister = webServer.register
+  webServer.register = (route) => {
+    const original = route.handler
+    route.handler = async (req, res) => {
+      sessionChecked.push(req)
+      return original(req, res)
+    }
+    return prototypeRegister.call(webServer, route)
+  }
+
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+  webServer.register({ kind: 'exact', path: '/api/auth', handler: async () => {} })
+  const req = { headers: { host: 'chained.jze100.com' } }
+  await webServer.exact.get('/api/auth').handler(req, {})
+
+  assert.deepEqual(trustedHosts, ['chained.jze100.com'])
+  assert.deepEqual(sessionChecked, [req])
+})
+
+test('场景6b 影子链: Given 本插件先激活 When 会话层后遮蔽注册方法 Then 两者包装叠加且 Host 注册在内层', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  // 模拟 startup-auth 后激活:遮蔽时捕获当前值(本插件的影子)并叠加会话包装
+  const sessionChecked = []
+  const previousRegister = webServer.register
+  webServer.register = (route) => {
+    const original = route.handler
+    route.handler = async (req, res) => {
+      sessionChecked.push(req)
+      return original(req, res)
+    }
+    return previousRegister.call(webServer, route)
+  }
+
+  webServer.register({ kind: 'exact', path: '/api/auth', handler: async () => {} })
+  const req = { headers: { host: 'stacked.jze100.com' } }
+  await webServer.exact.get('/api/auth').handler(req, {})
+
+  assert.deepEqual(trustedHosts, ['stacked.jze100.com'])
+  assert.deepEqual(sessionChecked, [req])
+})
+
+test('场景7 fallback: Given 回溯与影子注册两条路径的 fallback 请求 Then 同样注册 Host', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  const existing = async () => {}
+  webServer.fallback = existing
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  await webServer.fallback({ headers: { host: 'via-fallback.jze100.com' } }, {})
+  webServer.registerFallback(async () => {})
+  await webServer.fallback({ headers: { host: 'via-shadow.jze100.com' } }, {})
+
+  assert.deepEqual(trustedHosts, ['via-fallback.jze100.com', 'via-shadow.jze100.com'])
+})
+
+test('场景8 脏输入: Given 无 Host 头或非法 Host 头 When 请求到达 Then 不注册不抛错且原 handler 照常执行', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  const calls = []
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async (req) => { calls.push(req) } })
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: {} }, {})
+  // 空格与超范围端口都是 WHATWG 解析拒绝的形态,闸门 parseAuthority 同样返回 undefined
+  await route.handler({ headers: { host: 'bad host' } }, {})
+  await route.handler({ headers: { host: 'host:99999' } }, {})
+  await route.handler({}, {})
+
+  assert.deepEqual(trustedHosts, [])
+  assert.equal(calls.length, 4)
+})
+
+test('场景9 幂等重载: Given 本插件重复激活(HMR 重载模拟) When 再次激活 Then 路由 handler 与影子方法都不叠加', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+  const wrappedOnce = webServer.exact.get('/api/x').handler
+  const shadowOnce = webServer.register
+  const fallbackShadowOnce = webServer.registerFallback
+
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  assert.equal(webServer.exact.get('/api/x').handler, wrappedOnce)
+  assert.equal(webServer.register, shadowOnce)
+  assert.equal(webServer.registerFallback, fallbackShadowOnce)
+  await webServer.exact.get('/api/x').handler({ headers: { host: 'reload.jze100.com' } }, {})
+  assert.deepEqual(trustedHosts, ['reload.jze100.com'])
+})
+
+test('场景11 启动横幅: Given 插件激活 Then console 输出绑定、容量与既有信任条目', (t) => {
+  const output = mockConsole(t)
+  const { ctx } = createCtx({ trustedHosts: ['192.168.1.5', 'lan.example.com'] })
+
+  apply(ctx, { maxHosts: 50 })
+
+  const banner = output.map(([, message]) => message).find((message) => message.includes('动态信任已启用'))
+  assert.ok(banner !== undefined)
+  assert.ok(output.some(([, message]) => message.includes('bind 0.0.0.0')))
+  assert.ok(output.some(([, message]) => message.includes('容量 50')))
+  assert.ok(output.some(([, message]) => message.includes('192.168.1.5, lan.example.com')))
+})
+
+test('场景11b 启动横幅空清单: Given 无既有条目 Then 输出"无"占位', (t) => {
+  const output = mockConsole(t)
+  const { ctx } = createCtx({ trustedHosts: [] })
+
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  assert.ok(output.some(([, message]) => message.includes('既有信任 0 项: 无')))
+})
+
+test('场景14 数组重建: Given webRuntime 提供新数组 When 已注册域名再次到达 Then 重新登记进新数组且队列随代重置', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, holder, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: 1 })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'first.test' } }, {})
+  assert.deepEqual(trustedHosts, ['first.test'])
+
+  // 模拟 web-app 行重载:webRuntime 重建,新数组只含官方初始条目
+  const rebuilt = ['10.0.0.2']
+  holder.current = { trustedHosts: rebuilt }
+  await route.handler({ headers: { host: 'first.test' } }, {})
+  assert.deepEqual(rebuilt, ['10.0.0.2', 'first.test'])
+
+  // 新一代容量 1 已满:second.test 到达淘汰 first.test,证明队列已随代重置
+  await route.handler({ headers: { host: 'second.test' } }, {})
+  assert.deepEqual(rebuilt, ['10.0.0.2', 'second.test'])
+})
+
+test('场景15 容量下界: Given maxHosts 小于 1 Then schema 校验拒绝,缺省解出默认 100', () => {
+  assert.ok(Config['~standard'].validate({ maxHosts: 0 }).issues)
+  assert.ok(Config['~standard'].validate({ maxHosts: -1 }).issues)
+  assert.ok(Config['~standard'].validate({ maxHosts: 1.5 }).issues)
+  assert.equal(Config['~standard'].validate({}).value.maxHosts, 100)
+})
+
+test('场景16 淘汰重访: Given 条目被 FIFO 淘汰 When 该域名再次到达 Then 重新注册(不被去重记忆拉黑)', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  apply(ctx, { maxHosts: 1 })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'first.test' } }, {})
+  await route.handler({ headers: { host: 'second.test' } }, {})
+  assert.deepEqual(trustedHosts, ['second.test'])
+
+  await route.handler({ headers: { host: 'first.test' } }, {})
+  assert.deepEqual(trustedHosts, ['first.test'])
+})
+
+test('场景17 换代移交: Given 行级 config 变更触发重跑 apply When 请求到达已包装路由 Then 注册走新一代容量', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  const dispose1 = apply(ctx, { maxHosts: 1 })
+
+  const route = webServer.exact.get('/api/x')
+  const wrappedOnce = route.handler
+  await route.handler({ headers: { host: 'first.test' } }, {})
+
+  // 模拟行级 config 变更:先卸载(carrier 置空)再重跑 apply,handler 带标记跳过
+  // 重包装,但共享载体被新代覆盖,旧包装经载体用新容量注册
+  dispose1()
+  assert.equal(webServer.autoTrustAllRegister('x'), undefined)
+  apply(ctx, { maxHosts: 2 })
+  assert.equal(route.handler, wrappedOnce)
+
+  await route.handler({ headers: { host: 'second.test' } }, {})
+  await route.handler({ headers: { host: 'third.test' } }, {})
+  // 新代只记自身条目:second/third 共 2 条未超容量,first 属上代遗留视同官方条目
+  assert.deepEqual(trustedHosts, ['first.test', 'second.test', 'third.test'])
+
+  await route.handler({ headers: { host: 'fourth.test' } }, {})
+  // 新代容量 2 生效:fourth 淘汰新代最早的 second,遗留条目不参与记账
+  assert.deepEqual(trustedHosts, ['first.test', 'third.test', 'fourth.test'])
+})
+
+test('场景18 延迟激活: Given 激活时 webRuntime 未就绪 When 挂事件监听且服务就绪事件到达 Then 自动完成激活', async (t) => {
+  const output = mockConsole(t)
+  const { ctx, webServer, holder, trustedHosts, listeners } = createCtx({ webRuntimeReady: false })
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  const handlerBefore = webServer.exact.get('/api/x').handler
+
+  const dispose = apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  // 未就绪路径:不包装、不挂载体,挂 internal/service 监听并输出等待行
+  assert.equal(webServer.exact.get('/api/x').handler, handlerBefore)
+  assert.equal(webServer.autoTrustAllRegister, undefined)
+  assert.deepEqual(listeners.map(([name]) => name), ['internal/service'])
+  assert.ok(output.some(([, message]) => message.includes('webRuntime 未就绪')))
+
+  // 模拟 web-app fiber 激活完成:runtime 就绪并发出服务事件
+  holder.current = { trustedHosts: [] }
+  const [, listener] = listeners[0]
+  listener('webRuntime')
+  assert.notEqual(webServer.exact.get('/api/x').handler, handlerBefore)
+  assert.equal(typeof webServer.autoTrustAllRegister, 'function')
+  assert.ok(output.some(([, message]) => message.includes('动态信任已启用')))
+
+  await webServer.exact.get('/api/x').handler({ headers: { host: 'late.jze100.com' } }, {})
+  assert.deepEqual(holder.current.trustedHosts, ['late.jze100.com'])
+  dispose()
+  assert.equal(webServer.autoTrustAllRegister('x'), undefined)
+})
+
+test('场景20 卸载断开: Given 已激活 When 卸载 Then 载体置空,后续请求纯透传不再注册', async (t) => {
+  mockConsole(t)
+  const { ctx, webServer, trustedHosts } = createCtx()
+  webServer.register({ kind: 'exact', path: '/api/x', handler: async () => {} })
+  const dispose = apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  const route = webServer.exact.get('/api/x')
+  await route.handler({ headers: { host: 'before.test' } }, {})
+  assert.deepEqual(trustedHosts, ['before.test'])
+
+  dispose()
+  await route.handler({ headers: { host: 'after.test' } }, {})
+  assert.deepEqual(trustedHosts, ['before.test'])
+})
+
+test('场景21 激活幂等: Given 事件路径激活后服务再次发事件 When 重复触发 Then 不重复激活(横幅与载体不换代)', (t) => {
+  const output = mockConsole(t)
+  const { ctx, webServer, holder, listeners } = createCtx({ webRuntimeReady: false })
+  apply(ctx, { maxHosts: DEFAULT_MAX_HOSTS })
+
+  holder.current = { trustedHosts: ['10.0.0.9'] }
+  const [, listener] = listeners[0]
+  listener('webRuntime')
+  const carrier = webServer.autoTrustAllRegister
+
+  listener('webRuntime')
+
+  assert.equal(webServer.autoTrustAllRegister, carrier)
+  assert.equal(output.filter(([, message]) => message.includes('动态信任已启用')).length, 1)
+})