webServer middleware layer (ctx.webServer.use): a request-level seam so plugins can guard /api

[thinkmoon]

Problem

Third-party plugins currently cannot apply any request-level policy on the shared /api channel. Three paths, all closed:

1. ctx.webServer.register({ kind: 'prefix', path: '/api', ... }) — duplicate (kind, path) registration throws, and client-connection already owns the /api prefix.
2. ctx.connection.rpc.intercept('/api', matches, handler) — the handler receives (endpoint, payload, signal) only: no headers, no cookies, no socket facts, so no plugin can even answer "who is calling". The interceptor slot is also exclusive (a second registration throws), and the WebSocket upgrade path (/api/events downlinks) bypasses interceptors entirely.
3. Shadowing individual methods with exact routes is fail-open: any method added later falls through to the unguarded channel.

Concrete impact (real incident, observed on dsh-host-webserver / dsh-client-connection 0.1.0-rc.7): a community plugin ships a scan-to-pair remote-control feature and documents a pairing gate ("unpaired devices get 403 on every /api call"). The intended seam — an api/gate waterfall event the plugin listens for — is never emitted by any published SDK version, so the gate is dead code. On a deployment that trusts a public tunnel host (--trusted-host <tunnel-domain>), an unpaired browser from any network gets a full 200 through /api: session listing, prompts, the whole desktop surface. The Host fence being "not an auth layer" is documented and correct — but today there is nowhere for a plugin to put an auth layer.

The underlying need is not one more event: it is the ability for a plugin to observe request-level facts (cookies, headers, socket address) before the RPC bridge, composable across plugins.

Proposal

Add a connect-style middleware chain to dsh-host-webserver, dispatched before the exact/prefix route tables:

ctx.webServer.use((req, res, next) => {
  // inspect req.headers.cookie, req.socket.remoteAddress, ...
  // write a response to veto, or call next() to pass
})

This generalizes the registration-order tap chain the webserver already runs for index.html bodies — applied to requests.

Why a middleware layer

Property	How it is met
Request-level facts	native IncomingMessage: cookies, Host, Origin, socket address all visible
Multi-plugin composition	a chain, not an exclusive slot: pairing fence, rate limiter, audit logger can each register
Full-channel coverage	POST /api, WebSocket upgrades, static pages — all pass the chain before route lookup
Pre-parse veto	rejection before JSON body buffering; the cheapest possible position

• Generic capability, not pairing-specific: the SDK stays policy-free (as documented), and middleware is where plugin policy lives.
• Purely additive: no change to the connection plugin, no change to route-table semantics; existing plugins unaffected.
• Familiar shape: anyone who has written express / Koa / Go net-http middleware has zero learning cost.

Design points to settle

• async middleware — should be supported (rate limiters need storage lookups)
• veto semantics — middleware that writes a response ends the chain without next()
• ordering — registration order, or explicit priority (the cordis fiber lifecycle may already provide a stable ordering)
• error handling — a throwing middleware must produce a 500 and abort the chain, never hang
• upgrades — same chain, or a use('upgrade', fn) variant
• optional sugar — use('/api', fn) prefix binding

Consumer example (pairing fence)

ctx.effect(() => ctx.webServer.use((req, res, next) => {
  if (!req.url?.startsWith('/api')) return next()
  if (isLoopbackClient(req)) return next()          // Host AND socket both loopback
  if (isPairedDeviceRequest(service, req)) return next()  // live paired-device cookie
  res.writeHead(403)
  res.end('forbidden')
}), 'remote-web-ui: api pairing fence')

Keeping both the Host check and the socket check in loopback classification means a LAN client forging Host: localhost still fails (its socket is not loopback) — a fact only the native request object carries.

Sketch of the SDK-side change

In dsh-host-webserver dispatch, before exact/prefix lookup:

for (const mw of this.middlewares) {
  let delegated = false
  await mw(req, res, () => { delegated = true })
  if (!delegated) return   // middleware wrote the response
}

Registration mirrors register() / registerFallback() with append-only list semantics (dispose removes on effect teardown).

Alternatives considered

• Emit an api/gate waterfall event from client-connection per /api request with the IncomingMessage: workable, but channel-specific, single-consumer-shaped, and it still misses upgrades and non-/api routes.
• Hand the Request object to rpc.intercept handlers: keeps the exclusive-slot problem (the slot would need to become a chain first) and still no upgrade coverage; at that point a middleware layer is the simpler, more general primitive.

Happy to turn this into a PR if the direction sounds right.

[zoahdev]

对照当前 main HEAD 99f6f02 逐条核验，你的问题描述全部成立：

现状核验（packages/host/webserver/src/index.ts）

1. register()：exact/prefix 双表，重复 (kind, path) 直接 throw（注释写明"route patterns are a composition-level contract"）——/api 前缀已被 client-connection/gateway 占用，第三方插件确实注册不上；
2. registerUpgrade()：精确路径升级路由，重复 throw（"one socket can have only one protocol owner"）——升级路径独立于 HTTP 路由表，你的"WebSocket 升级绕过拦截"说法成立；
3. registerFallback()：单座（second registration throws）；
4. tapIndex()：注册序变换链——提案里"中间件链"的形态在 index.html 变换上已有先例，语义和实现都可借鉴。

intercept 签名核验（packages/client/connection/src/rpc.ts）

intercept(channel: '/api', matches, handler: ConnectionRpcHandler, options)——handler 是解码后的 endpoint handler，确实拿不到 IncomingMessage/headers/cookie/socket；测试也断言了独占槽（"already has an interceptor" throw）。你"插件无法回答 who is calling"的说法准确。

api/gate 事件核验

connection 包 rpc.ts / index.ts 全文无 api/gate——该瀑布事件在任何已发布 SDK 版本里都不存在，你描述的"配对门是死代码"实锤。

对提案的补充意见（按设计点顺序）

1. 错误处理要对接现有的 per-request guard：Service.init 的 createServer handler 已经有一个外层 catch（route 抛错 → warn + 400，headersSent 时 destroy）——中间件抛错需要明确语义：建议中间件异常走 500（区别于路由异常的 400），并且不能依赖外层 guard 兜底（外层是 400，语义不对）。这是提案里"never hang"之外第二个需要测试钉住的点。
2. 升级路径建议命名镜像现有 API：use() + useUpgrade()，对齐 register/registerUpgrade 的命名习惯，比 use('upgrade', fn) 少一层特判；升级请求的 veto 语义（writeHead + destroy socket，没有 res.end 的概念）需要单独定义。
3. 排序用注册序即可：cordis effect 生命周期内注册序稳定，且 tapIndex 已有先例；显式 priority 留到真有跨插件排序需求再加，避免过早引入环检测。
4. 安全边界提醒：中间件是插件策略层，不是沙箱——HTTP 层校验能被重放/绕过（比如 CSWSH），配对门建议配合 cookie 的 SameSite 与短期 nonce；--trusted-host 公网隧道场景下这层是必须的，但文档应写明"middleware = policy, not security boundary"。
5. 最小测试面：use() 重复注册不抛（append-only，区别于 register）；disposer 在 effect teardown 移除；中间件抛错 → 500 且链中止；upgrade 请求过同一链；prefix 糖 use('/api', fn) 只匹配该前缀。

方向正确且是纯增量（不改 connection、不改路由表语义），值得转 PR。