dsh-webui-oauth 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.7.1
+
+兼容 dsh **0.2.2-rc.1**：`webServer.fallback` 从函数改成了 `{ resource }`。
+
+### 修复：访问 `/` 返回 500 空响应（nginx 日志 `500 0`）
+
+- **现象**：升级到 dsh 0.2.2-rc.1 后，访问 `/` 在完成核心 token 交换后返回
+  `500`，body 为空；nginx 访问日志表现为 `500 0`。
+- **原因**：0.2.2-rc.1 起 `webServer.fallback` 不再一定是函数——
+  `dsh-host-frontend-static` 注册的是 `{ resource }`（Fetch 风格
+  `resource(request, peer) -> Response`）。插件仍按 `await fallback(req, res)`
+  调用，抛 `TypeError: fallback is not a function`，被外层 `catch` 兜成
+  `500` + 空 body。
+- **修复**：新增 `serveFallback()` 统一分派三种形状：
+  1. 函数（旧核心）；
+  2. `{ resource }` + `webServer.serveResource`（0.2.2-rc.1+）；
+  3. `{ handler }`（部分中间版本）。
+  没有 fallback 时返回 `false`，由调用方 404——不再把"形状不匹配"误报成 500。
+
+### 安全：资源型 fallback 也必须上闸门
+
+此前 `wrapExistingFallback` 只处理 `typeof === 'function'`，遇到 `{ resource }`
+直接跳过，等于把兜底入口留给匿名请求。现在：
+
+- `resource(request, peer)` 会被包装：从 Fetch Request 的 `cookie` 头取会话，
+  未登录返回 `401 Response`，已登录原样放行；
+- `registerFallback` 注册时的三种形状都会在注册那一刻上闸门；
+- `undo` 会把 `resource` / `handler` 原样还原。
+
+### 测试
+
+- 新增 `test/fallback-shape.test.mjs`（19 项）：三种形状分派、无 fallback /
+  未知形状 / 缺 `serveResource` 均不抛异常、资源型 fallback 的匿名拒绝与
+  登录放行、`undo` 还原。
+- 全量 18 个测试文件、488 项断言通过。
+
 ## 0.7.0
 
 新增**「仅允许 SSO」**开关；同时修复一个会把 OIDC 绑定悄悄弄丢的老问题。

package/README.en.md

@@ -401,6 +401,7 @@ wired into `npm test`).
 
 ## Known limits
 
+- **Fallback shape on dsh 0.2.2-rc.1**: since that version `webServer.fallback` may be `{ resource }` (that is how `dsh-host-frontend-static` registers it) instead of a function. The plugin now handles function / `{ resource }` / `{ handler }`; a resource fallback is gated as well. If `/` returns an empty `500` after upgrading (nginx logs `500 0`), make sure the plugin is ≥ 0.7.1.
 - **Inherent runtime-wrapping window**: between a route-object replacement (service hot-reload) and the next rescan (≤10s) there is an unprotected window; the fail-closed check on enabling covers the "initially exposed" case, so this window only affects hot-reload during runtime.
 - **WebSocket and `trustedHosts`**: in reverse-proxy / LAN deployments (non-loopback Host), WS downlinks need the public hostname added to `client-connection.trustedHosts` in the DSH config (see "Architecture").
 - **Proxy on a different host**: if the reverse proxy is not on the same machine as DSH (non-loopback peer), the proxy headers are not trusted and rate limiting aggregates per proxy IP (degrades to a global bucket).

package/README.md

@@ -411,6 +411,7 @@ IdP 侧日志确认完整往返：`discovery → jwks → authorize(issued code)
 
 ## 已知边界
 
+- **dsh 0.2.2-rc.1 的 fallback 形状**：该版本起 `webServer.fallback` 可能是 `{ resource }`（`dsh-host-frontend-static` 就是这样注册的），而不再是函数。插件已兼容函数 / `{ resource }` / `{ handler }` 三种形状；资源型 fallback 同样会被闸门包装。若升级后 `/` 返回 `500` 且 body 为空（nginx 日志 `500 0`），请确认插件版本 ≥ 0.7.1。
 - **运行时包装的固有窗口**：路由对象被替换（服务热重载）到下一次重扫之间（≤10s）存在未保护窗口；启用认证时的 fail-closed 已挡住「初始裸奔」，此窗口仅影响运行中的热重载场景。
 - **WS 与 trustedHosts**：反代/局域网（非回环 Host）下，WS 下行需在 dsh 配置 `client-connection.trustedHosts` 中加入对外域名（见「架构」节）。
 - **反代不同机**：若反代与 DSH 不在同一台机器（对端非回环），代理头不被信任，限流将按代理 IP 聚合（退化为全局桶）。

package/index.js

@@ -1154,6 +1154,41 @@ function wantsHtml(req) {
   }
 }
 
+/**
+ * 把请求交给 webServer 的 fallback。
+ *
+ * 0.2.2-rc.1 起 fallback 不再一定是函数：dsh-host-frontend-static 注册的是
+ * `{ resource }`（Fetch 风格的 `resource(request, peer) -> Response`）。
+ * 旧代码直接 `await fallback(req, res)` 会抛 TypeError（fallback is not a function），
+ * 被外层 catch 兜成 `500` + 空 body——nginx 访问日志里就是 `500 0`。
+ *
+ * 这里统一三种形状：
+ *   1. 函数（旧核心 / 第三方 handler）；
+ *   2. `{ resource }` + webServer.serveResource（0.2.2-rc.1+）；
+ *   3. `{ handler }`（部分中间版本）。
+ *
+ * @returns {Promise<boolean>} 是否已由 fallback 处理；false 表示没有 fallback，
+ *   调用方应自行返回 404（不要把"没有 fallback"误报成 500）。
+ */
+export async function serveFallback(ctx, req, res) {
+  const ws = ctx && ctx.webServer
+  if (!ws) return false
+  const fallback = ws.fallback
+  if (typeof fallback === 'function') {
+    await fallback(req, res)
+    return true
+  }
+  if (fallback && typeof fallback.resource === 'function' && typeof ws.serveResource === 'function') {
+    await ws.serveResource(req, res, new URL(req.url || '/', 'http://x'), fallback.resource)
+    return true
+  }
+  if (fallback && typeof fallback.handler === 'function') {
+    await fallback.handler(req, res)
+    return true
+  }
+  return false
+}
+
 function rejectUpgrade401(socket) {
   try {
     socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 13\r\n\r\nunauthorized\n')
@@ -1373,7 +1408,12 @@ function installRouteGate(ctx, checkRequest, log, options) {
   // ---------------- fallback 也要包 ----------------
   // fallback 是"未被任何具名路由认领"的兜底处理器。它同样可能被第三方插件占据，
   // 若不管，攻击者只要找到一个不存在的路径就可能落到未鉴权的 fallback 上。
-  const wrappedFallbacks = new WeakSet()
+  //
+  // 0.2.2-rc.1 起 fallback 还可能是 { resource }（Fetch 风格）：既不能当函数调用
+  // （TypeError），也不能放任它绕过闸门。两种形状分别包装。
+  const wrappedFallbacks = new WeakSet()   // 原始 handler 函数
+  const wrappedResources = new WeakSet()   // 原始 resource 函数
+
   const gateFallback = (handler) => {
     if (typeof handler !== 'function' || wrappedFallbacks.has(handler)) return handler
     const original = handler
@@ -1385,23 +1425,71 @@ function installRouteGate(ctx, checkRequest, log, options) {
       }
       return original(req, res)
     }
-    wrappedFallbacks.add(gated)
+    wrappedFallbacks.add(original)
     fallbackWrapped = true
     log('wrapped fallback handler')
     return gated
   }
 
-  // 已经就位的 fallback：直接替换属性（保留原函数以便 undo）。
+  const gateResource = (resource) => {
+    if (typeof resource !== 'function' || wrappedResources.has(resource)) return resource
+    const original = resource
+    const gated = async (request, peer) => {
+      // resource 收到的是 Fetch Request；checkRequest 只依赖 cookie 头。
+      const cookie = request && request.headers && typeof request.headers.get === 'function'
+        ? (request.headers.get('cookie') || '')
+        : ''
+      const headers = { cookie }
+      if (!checkRequest({ method: request && request.method, url: request && request.url, headers })) {
+        return new Response('unauthorized', {
+          status: 401,
+          headers: { 'content-type': 'text/plain; charset=utf-8' },
+        })
+      }
+      return original(request, peer)
+    }
+    wrappedResources.add(original)
+    fallbackWrapped = true
+    log('wrapped fallback resource')
+    return gated
+  }
+
+  // 已经就位的 fallback：按形状替换（保留原值以便 undo）。
   const wrapExistingFallback = () => {
     const current = ws.fallback
-    if (typeof current !== 'function') return
-    if (wrappedFallbacks.has(current)) return
-    if (current.__dshWuaGated === true) return
-    const gated = gateFallback(current)
-    if (gated === current) return
-    gated.__dshWuaGated = true
-    ws.fallback = gated
-    undos.push(() => { if (ws.fallback === gated) ws.fallback = current })
+    if (typeof current === 'function') {
+      if (wrappedFallbacks.has(current)) return
+      if (current.__dshWuaGated === true) return
+      const gated = gateFallback(current)
+      if (gated === current) return
+      gated.__dshWuaGated = true
+      ws.fallback = gated
+      undos.push(() => { if (ws.fallback === gated) ws.fallback = current })
+      return
+    }
+    if (current && typeof current === 'object') {
+      if (typeof current.resource === 'function') {
+        if (wrappedResources.has(current.resource)) { fallbackWrapped = true; return }
+        if (current.resource.__dshWuaGated === true) return
+        const original = current.resource
+        const gated = gateResource(original)
+        if (gated === original) return
+        gated.__dshWuaGated = true
+        current.resource = gated
+        undos.push(() => { if (current.resource === gated) current.resource = original })
+        return
+      }
+      if (typeof current.handler === 'function') {
+        if (wrappedFallbacks.has(current.handler)) { fallbackWrapped = true; return }
+        if (current.handler.__dshWuaGated === true) return
+        const original = current.handler
+        const gated = gateFallback(original)
+        if (gated === original) return
+        gated.__dshWuaGated = true
+        current.handler = gated
+        undos.push(() => { if (current.handler === gated) current.handler = original })
+      }
+    }
   }
 
   // ---------------- 注册时即拦截（消除重扫窗口） ----------------
@@ -1432,8 +1520,28 @@ function installRouteGate(ctx, checkRequest, log, options) {
   // registerFallback 走的是属性赋值而非 Map，单独接管。
   if (typeof ws.registerFallback === 'function') {
     const originalRegisterFallback = ws.registerFallback
-    ws.registerFallback = function patchedRegisterFallback (handler) {
-      return originalRegisterFallback.call(this, gateFallback(handler))
+    ws.registerFallback = function patchedRegisterFallback (fallback) {
+      // 三种形状都要上闸门：函数 / { resource } / { handler }。
+      try {
+        if (typeof fallback === 'function') {
+          fallback = gateFallback(fallback)
+        } else if (fallback && typeof fallback === 'object') {
+          if (typeof fallback.resource === 'function' && !wrappedResources.has(fallback.resource)) {
+            const gated = gateResource(fallback.resource)
+            if (gated !== fallback.resource) {
+              gated.__dshWuaGated = true
+              fallback.resource = gated
+            }
+          } else if (typeof fallback.handler === 'function' && !wrappedFallbacks.has(fallback.handler)) {
+            const gated = gateFallback(fallback.handler)
+            if (gated !== fallback.handler) {
+              gated.__dshWuaGated = true
+              fallback.handler = gated
+            }
+          }
+        }
+      } catch (e) { /* 包装失败不阻断注册，靠重扫兜底 */ }
+      return originalRegisterFallback.call(this, fallback)
     }
     undos.push(() => { ws.registerFallback = originalRegisterFallback })
   }
@@ -3399,11 +3507,9 @@ export async function apply(ctx) {
               return
             }
           }
-          const fallback = ctx.webServer.fallback
-          if (fallback !== undefined) {
-            await fallback(req, res)
-            return
-          }
+          // fallback 可能是函数，也可能是 { resource }（0.2.2-rc.1+）。
+          // 交给 serveFallback 统一分派，避免 TypeError → 500 空响应。
+          if (await serveFallback(ctx, req, res)) return
           res.writeHead(404)
           res.end()
           return

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "node test/redirect-scheme.test.mjs && node test/proxy-host.test.mjs && node test/trusted-origin.test.mjs && node test/oidc.test.mjs && node test/oidc-state-ttl.test.mjs && node test/set-cookie-multi.test.mjs && node test/oidc-integration.test.mjs && node test/oidc-config-store.test.mjs && node test/adopt-data-dir.test.mjs && node test/oidc-ec.test.mjs && node test/jwks-refresh.test.mjs && node test/oidc-bind.test.mjs && node test/client-bundle-id.test.mjs && node test/client-prefill.test.mjs && node test/displace-original.test.mjs && node test/oidc-redirect-matrix.test.mjs && node test/gate-default-deny.test.mjs"
+    "test": "node test/redirect-scheme.test.mjs && node test/proxy-host.test.mjs && node test/trusted-origin.test.mjs && node test/oidc.test.mjs && node test/oidc-state-ttl.test.mjs && node test/set-cookie-multi.test.mjs && node test/oidc-integration.test.mjs && node test/oidc-config-store.test.mjs && node test/adopt-data-dir.test.mjs && node test/oidc-ec.test.mjs && node test/jwks-refresh.test.mjs && node test/oidc-bind.test.mjs && node test/client-bundle-id.test.mjs && node test/client-prefill.test.mjs && node test/displace-original.test.mjs && node test/oidc-redirect-matrix.test.mjs && node test/gate-default-deny.test.mjs && node test/fallback-shape.test.mjs"
   },
   "exports": {
     ".": "./index.js",