dsh-webui-oauth 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.7.2
+
+合并上游（Yuuz12/dsh-webui-auth）0.3.5–0.3.7 中**可安全合并**的部分；
+宿主载体桥 / 桌面端锁因会绕过现有门禁，未合并。
+
+### 合并：DSH Desktop 标记透传（upstream 0.3.5 / #8）
+
+- 新增 `lib/desktop-adapter.js`（自包含、可整体摘除）；
+- 渲染器加载时把 `dsh-desktop-*` 标记写入 HttpOnly Cookie（`dsh_wua_desktop`，12h）；
+- 之后落到干净 `/` 时 302 回带标记的 URL，修复桌面端 advanced/extended 模式下
+  12 个 layout 依赖插件停在 pending 的问题。
+- **不影响门禁**：`remember()` 在认证判定之前调用但只写 Cookie；`restore()` 只在
+  `checkRequest()` 通过之后调用。未登录请求带标记仍然去登录页。
+- 已加 9 项集成断言（oidc-bind 1f）+ 24 项纯函数断言。
+
+### 合并：审计日志 null/boolean 不再被字符串化（upstream 0.3.6）
+
+`auditLog` 原先把非 string/number 一律 `String()`，导致日志里出现字符串
+`"null"` / `"true"`。现在 null 与 boolean 原样保留。
+
+### 合并：fallback 诊断增强（upstream 0.3.7）
+
+我们在 0.7.1 已独立修复 `{ resource }` 兼容；本次补上可观测性：
+
+- `status` 新增 `fallback: 'handler' | 'resource' | 'absent' | 'unknown'`；
+- 启动日志输出 `core fallback seat: handler/resource`，unknown 时 error；
+- 形态不认识时输出**一次性**诊断，并返回带说明的 404（不再是空 body）。
+
+### 未合并（有意）
+
+- **宿主载体桥（0.3.6 C6）**：其 `isLoopbackPeer()` 只看 socket 地址。
+  本部署是 nginx 同机反代，所有请求的 socket 都是 127.0.0.1，等于"持有核心
+  Cookie 即可绕过插件会话/SSO"，与「仅允许 SSO」直接冲突。
+- **桌面端锁（0.3.6 C8）**：UI 级锁，对 Web 部署无价值。
+- **exact 路由覆盖（0.3.6 C7）**：我们的 deny-by-default 已覆盖全部 exact
+  （实测 `/plugins/events` 匿名 401），无需合并。
+
+### 测试
+
+- 新增 `test/desktop-marker.test.mjs`（24 项）、`test/audit-null.test.mjs`（7 项）；
+  `test/fallback-shape.test.mjs` 增加 7 项形状判定；`test/oidc-bind.test.mjs`
+  增加 9 项"桌面标记不影响门禁"集成断言。
+- 全量 20 个测试文件、535 项断言通过。
+
+## 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,15 @@ wired into `npm test`).
 
 ## Known limits
 
+- **DSH Desktop**: `dsh-desktop-*` marker pass-through is supported (markers survive login and
+  re-login), but upstream 0.3.6's **host carrier bridge is intentionally not included**. That bridge
+  decides "loopback" purely from the socket address, and this deployment sits behind an nginx proxy on
+  the same host — every request's socket is `127.0.0.1`, so enabling it would mean "a core cookie is
+  enough to bypass the plugin session / SSO", which conflicts with the SSO-only policy. If you must use
+  DSH Desktop's shell-direct mode, use the upstream plugin and evaluate that bypass yourself.
+- **Audit field types**: since 0.7.2 `null` and booleans are written as-is (no longer stringified to
+  `"null"` / `"true"`); any log consumer that assumed every field is a string must be adjusted.
+- **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,9 @@ IdP 侧日志确认完整往返：`discovery → jwks → authorize(issued code)
 
 ## 已知边界
 
+- **DSH Desktop**：支持 `dsh-desktop-*` 标记透传（登录 / 退出后重登不再丢失标记），但**不提供**上游 0.3.6 的「宿主载体桥」。该桥只用 socket 是否回环来判定，而本部署是 nginx 同机反代——所有请求的 socket 都是 `127.0.0.1`，启用它等于"持有核心 Cookie 即可绕过插件会话 / SSO"，与「仅允许 SSO」冲突。若必须使用 DSH Desktop 的 shell 直连模式，请改用上游原版插件，并自行评估该旁路风险。
+- **审计日志字段类型**：0.7.2 起 `null` 与 boolean 原样写入（不再变成字符串 `"null"` / `"true"`）；旧日志解析代码若假设"所有字段都是字符串"，需相应调整。
+- **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

@@ -157,6 +157,9 @@ import { readFileSync, writeFileSync, appendFileSync, accessSync, mkdirSync, unl
 import { fileURLToPath } from "node:url";
 import { resolve as resolvePath } from "node:path";
 import { promisify } from "node:util";
+// 宿主适配层（DSH Desktop 的 dsh-desktop-* 标记透传）。
+// 整体摘除：删掉本行 + 网关里两处标着「宿主适配层」的代码块 + lib/desktop-adapter.js。
+import { desktopAdapter } from './lib/desktop-adapter.js';
 
 export const name = 'dsh-webui-oauth'
 
@@ -580,7 +583,11 @@ async function auditLog(ctx, event, fields) {
       let v = fields[key]
       if (v === undefined) continue
       if (key === 'ip' && typeof v === 'string') v = anonymizeIp(v)
-      entry[key] = typeof v === 'string' || typeof v === 'number' ? v : String(v)
+      // null / boolean 原样保留：早先一律 String()，日志里会出现字符串 "null"、
+      // "true"，读起来像出了故障（upstream 0.3.6 的同类修复）。
+      entry[key] = (v === null || typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+        ? v
+        : String(v)
     }
     appendFileSync(target, JSON.stringify(entry) + '\n', 'utf8')
   } catch (e) {
@@ -1154,6 +1161,97 @@ 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
+}
+
+/**
+ * 判断核心兜底席位的形状。
+ * 核心升级可能再次改变它（函数 → { resource } → ？），把形状单独抽出来，
+ * 既供 status 回显，也供启动自检与一次性诊断使用。
+ *
+ * @returns {'absent'|'handler'|'resource'|'unknown'}
+ */
+export function fallbackShape(webServer) {
+  if (!webServer) return 'absent'
+  const fallback = webServer.fallback
+  if (fallback === undefined) return 'absent'
+  if (typeof fallback === 'function') return 'handler'
+  if (fallback !== null && typeof fallback === 'object' &&
+      'resource' in fallback && typeof webServer.serveResource === 'function') return 'resource'
+  return 'unknown'
+}
+
+// 形状不兼容只报一次：每个文档请求都刷一条 error 会把日志淹掉。
+let fallbackProblemReported = false
+
+/**
+ * 形态不认识时的一次性诊断：说清期望什么、实际是什么，别让 500/空 404 掩盖过去。
+ * 仅写日志，不改变响应（响应由 sendFallbackUnavailable 负责）。
+ */
+export function reportFallbackProblem(ctx) {
+  if (fallbackProblemReported) return
+  fallbackProblemReported = true
+  try {
+    const ws = ctx && ctx.webServer
+    const fallback = ws ? ws.fallback : undefined
+    const actual = fallback === undefined
+      ? 'undefined'
+      : typeof fallback === 'function'
+        ? 'function'
+        : (fallback !== null && typeof fallback === 'object')
+          ? 'object { ' + Object.keys(fallback).join(', ') + ' }'
+          : typeof fallback
+    const canServe = !!(ws && typeof ws.serveResource === 'function')
+    ctx.logger.error('[dsh-webui-oauth] INCOMPATIBLE CORE: cannot hand the document back to'
+      + ' webServer.fallback — expected a handler function, or { resource } together with'
+      + ' webServer.serveResource(); got ' + actual
+      + ' (serveResource: ' + (canServe ? 'present' : 'missing') + ').'
+      + ' webServer.fallback shape may have changed again; authenticated pages answer 404 until the plugin is updated.')
+  } catch (e) { /* logging must never throw */ }
+}
+
+/** 形态不认识时给操作者一句能看懂的话，而不是空白页/500。 */
+export function sendFallbackUnavailable(res) {
+  res.writeHead(404, {
+    'content-type': 'text/plain; charset=utf-8',
+    'x-content-type-options': 'nosniff',
+    'cache-control': 'no-store',
+  })
+  res.end('dsh-webui-oauth: core webServer.fallback is unavailable or incompatible\n')
+}
+
 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 +1471,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 +1488,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 +1583,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 })
   }
@@ -2396,6 +2567,18 @@ export async function apply(ctx) {
       + '. /api and/or WebSocket may be unprotected; the gate will still wrap them if they register later.')
   }
 
+  // 核心兜底席位形状自检：认得出就报一句，认不出就明确报「不兼容当前核心版本」，
+  // 不要等到用户登录换 cookie 时才以 500/空页暴露。'absent' 可能只是
+  // frontend-static 尚未注册，留到首个文档请求时再诊断。
+  {
+    const shape = fallbackShape(ctx.webServer)
+    if (shape === 'handler' || shape === 'resource') {
+      ctx.logger.info('[dsh-webui-oauth] core fallback seat: ' + shape)
+    } else if (shape === 'unknown') {
+      ctx.logger.error('[dsh-webui-oauth] INCOMPATIBLE CORE: webServer.fallback is neither a handler function nor { resource } + webServer.serveResource(); authenticated pages will answer 404')
+    }
+  }
+
   ctx.logger.info('[dsh-webui-oauth] started, credentials file: ' + configPath())
   if (!enabledFlag) {
     // H1: token 同时落盘（0600，仅本机操作者可读），setup 成功后删除。
@@ -2684,6 +2867,9 @@ export async function apply(ctx) {
           username: enabled ? creds.username : null,
           ttl: ttlOf(creds),
           sessionsPersisted: sessions.ok,
+          // 核心兜底席位形态（handler | resource | absent | unknown）：核心升级后
+          // 如果这里变成 unknown，文档请求会 404 —— 排查时先看这个字段。
+          fallback: fallbackShape(ctx.webServer),
           gate: {
             ok: gate.ok(),
             problems: gate.problems().slice(0, 3),
@@ -3384,7 +3570,20 @@ export async function apply(ctx) {
     path: '',
     handler: async (req, res) => {
       try {
+        // ─────── 宿主适配层（DSH Desktop）· 整体摘除时删掉本块 ───────
+        // 必须在认证判定之前：退出登录是客户端自己 location.href = '/'，
+        // 服务端看不到带标记的 URL 被放弃，只能在加载时提前记住。
+        // 注意：remember() 只写 Cookie，不参与放行；门禁仍由 checkRequest 决定。
+        desktopAdapter.remember(req, res)
+        // ──────────────────────────────────────────────────────────
         if (checkRequest(req)) {
+          // ─────── 宿主适配层（DSH Desktop）· 整体摘除时删掉本块 ───────
+          // 核心 token→cookie 交换会把浏览器 303 到干净的 "/"，桌面端
+          // advanced / extended 模式依赖 URL 上的 dsh-desktop-* 标记才会接管
+          // layout 服务，这里把记住的标记补回 URL 再放行。
+          // 只在 checkRequest 通过之后调用：未认证请求绝不会走到这里。
+          if (desktopAdapter.restore(req, res)) return
+          // ──────────────────────────────────────────────────────────
           // alpha.2+：插件会话通过后，核心 BrowserAuth 可能仍未认领该浏览器
           // （核心 cookie 缺失/过期）。主动引导去带 launch token 的根 URL 完成
           // 核心 token→cookie 交换，否则 fallback 的 authorizeIndex 会 401 死锁。
@@ -3399,13 +3598,13 @@ export async function apply(ctx) {
               return
             }
           }
-          const fallback = ctx.webServer.fallback
-          if (fallback !== undefined) {
-            await fallback(req, res)
-            return
-          }
-          res.writeHead(404)
-          res.end()
+          // fallback 可能是函数，也可能是 { resource }（0.2.2-rc.1+）。
+          // 交给 serveFallback 统一分派，避免 TypeError → 500 空响应。
+          if (await serveFallback(ctx, req, res)) return
+          // 形态不认识 / 核心还没注册：明确报一次，并回带说明的 404，
+          // 不要留一个空 body 让运维去猜。
+          reportFallbackProblem(ctx)
+          sendFallbackUnavailable(res)
           return
         }
         res.writeHead(302, { location: loginLocation(req) })

package/lib/desktop-adapter.js

@@ -0,0 +1,205 @@
+/**
+ * DSH Desktop 适配层。
+ *
+ * 本模块与认证逻辑**完全解耦**：不 import 主模块的任何东西，只依赖 Node 内置能力，
+ * 因此可以整体删除而不影响认证本身。见文末「如何移除整个适配」。
+ *
+ * ── 为什么需要它（issue #8）────────────────────────────────────────────
+ * DSH Desktop 的 advanced / extended 模式会在组合层**禁用核心 `ui-layout` 行**
+ * （dsh-plugin-desktop 的 profile 组合按 mode 改写组合表），此时客户端 `layout`
+ * 服务的唯一提供者是桌面端自己的客户端插件，而它**只在 URL 带 `dsh-desktop-*`
+ * 标记时才生效** —— `parseDesktopClientEnvironment()` 在标记缺失时返回 undefined，
+ * `apply()` 随即直接 return，整个桌面端客户端插件不生效。
+ *
+ * 任何一次落到干净 "/" 的跳转都会丢掉这些标记，于是 12 个依赖 layout 的客户端插件
+ * 永远停在 pending，渲染器 30s 不上报健康，宿主弹出恢复模式对话框。已确认两条路径：
+ *
+ *   ① 首次登录：核心 token→cookie 交换把浏览器 303 到干净的 "/"；
+ *   ② 退出后重登：客户端自行 `location.href = '/'`（lib/client.js 的 onLogout 与
+ *      401 分支），服务端从头到尾没看到那个带标记的 URL 被放弃。
+ *
+ * ── 它做什么 ──────────────────────────────────────────────────────────
+ * 主动记忆 + 补投，而不是「跳转前才记」：
+ *
+ *   remember()  渲染器正常加载（URL 带标记）时就把标记写进 Cookie；
+ *   restore()   文档请求落到干净的 "/" 时，302 回带标记的 URL。
+ *
+ * 为什么必须「主动」：路径 ② 是客户端发起的跳转，服务端根本没有机会在跳转前做任何事，
+ * 等它收到 `GET /` 时标记早已不在。只有在加载时就把标记落盘，才能覆盖所有丢失路径。
+ *
+ * 暂存**刻意不清除**：清除会引入「记住 → 立刻清掉 → 退出后无处可补」的时序陷阱，
+ * 过期交给 Cookie 自身的 Max-Age（12h，且每次加载都会刷新）。
+ *
+ * ── 安全边界 ──────────────────────────────────────────────────────────
+ * 标记按 `dsh-desktop-` 前缀**整体透传**（刻意不做硬编码白名单——DSH Desktop 将来
+ * 新增一个标记时会再次静默弄坏桌面端启动，正是本 issue 的同类耦合），其中 `mode`
+ * 必须是 `compatibility`/`extended`/`advanced` 之一、值长度上限 64。跳转目标恒为
+ * 同源相对路径 "/"，**无开放重定向面**；网页版（无 `dsh-desktop-*` 标记）零影响。
+ *
+ * ── 如何移除整个适配 ──────────────────────────────────────────────────
+ *   1. 删掉 index.js 里两处标着「宿主适配层」的代码块（网关 handler 内，共 3 行代码）；
+ *   2. 删掉 index.js 顶部那行 import，连同它上面两行注释；
+ *   3. 删掉 index.js 导出块里提到本模块的那行注释；
+ *   4. 删掉本文件，并从 package.json 的 `files` 里去掉 `lib/desktop-adapter.js`。
+ *
+ * 已实测：只做 1+2 后 index.js 即可独立 `node --check` 通过，无任何悬空引用。
+ * 认证本身不依赖本模块 —— 移除后行为等价于 0.3.3：网页版不受影响，桌面端
+ * advanced / extended 模式会在登录跳转后再次出现 #8。
+ *
+ * ── 如何新增一个适配 ──────────────────────────────────────────────────
+ * 按同样形状导出即可：
+ *
+ *     { remember(req, res) -> boolean, restore(req, res) -> boolean }
+ *
+ * remember 在网关最前面**无条件**调用；restore 在插件会话校验通过后调用，
+ * 返回 true 表示已接管该请求（已发出响应，调用方应立即 return）。
+ * 两个函数都只应触碰响应头，不应改变认证判定。
+ */
+
+const DESKTOP_STASH_COOKIE = 'dsh_wua_desktop'
+const DESKTOP_STASH_TTL_SECONDS = 12 * 60 * 60
+
+/** 桌面端标记的统一前缀。 */
+const DESKTOP_MARKER_PREFIX = 'dsh-desktop-'
+
+/**
+ * 已知标记，仅用于固定补投时的 query 顺序；除此之外任何 `dsh-desktop-*` 键
+ * 都会一并透传（前向兼容）。
+ */
+const DESKTOP_MARKER_KEYS = [
+  'dsh-desktop-mode',
+  'dsh-desktop-platform',
+  'dsh-desktop-version',
+  'dsh-desktop-material',
+  'dsh-desktop-mica',
+  'dsh-desktop-titlebar-inset',
+]
+
+/** 桌面端合法模式，与 dsh-plugin-desktop 的 MODES 对齐；其它值一律不采信。 */
+const DESKTOP_MODES = new Set(['compatibility', 'extended', 'advanced'])
+
+/** 单个标记值的长度上限，防脏 cookie 撑爆响应头。 */
+const DESKTOP_MARKER_MAX_LENGTH = 64
+
+/**
+ * 读取请求 Cookie。
+ * 刻意不 import 主模块的同名工具：本模块要能被单独删掉，不能反向依赖认证实现。
+ */
+function cookieOf(req, name) {
+  const raw = req.headers && req.headers.cookie
+  if (!raw) return null
+  for (const part of String(raw).split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim()
+  }
+  return null
+}
+
+function parseUrl(urlString) {
+  try { return new URL(urlString || '/', 'http://dsh.invalid') } catch (e) { return null }
+}
+
+/**
+ * 从一组 search params 里收集可透传的桌面端标记；没有可透传项时返回 null。
+ * 已知键先出（顺序稳定），其余同前缀键按出现顺序跟进。
+ */
+function collectDesktopMarkers(params) {
+  // mode 是桌面端客户端插件的硬开关：它缺失或非法时 parseDesktopClientEnvironment
+  // 会直接 throw，此时补投 platform 之类的其余标记只会把渲染器推向失败，故整体放弃。
+  const mode = params.get(DESKTOP_MARKER_PREFIX + 'mode')
+  if (mode === null || !DESKTOP_MODES.has(mode)) return null
+  const markers = []
+  const seen = new Set()
+  const take = (key) => {
+    if (seen.has(key)) return
+    const value = params.get(key)
+    if (value === null || value === '' || value.length > DESKTOP_MARKER_MAX_LENGTH) return
+    seen.add(key)
+    markers.push([key, value])
+  }
+  for (const key of DESKTOP_MARKER_KEYS) take(key)
+  for (const key of params.keys()) {
+    if (key.startsWith(DESKTOP_MARKER_PREFIX)) take(key)
+  }
+  return markers.length > 0 ? markers : null
+}
+
+/** 从 URL 中提取可透传的桌面端标记；没有可透传项时返回 null。 */
+function desktopMarkersOf(urlString) {
+  const url = parseUrl(urlString)
+  if (url === null) return null
+  return collectDesktopMarkers(url.searchParams)
+}
+
+/** 暂存标记的 Set-Cookie 值。 */
+function desktopStashCookie(markers) {
+  const payload = markers.map(([k, v]) => k + '=' + encodeURIComponent(v)).join('&')
+  return DESKTOP_STASH_COOKIE + '=' + encodeURIComponent(payload) +
+    '; HttpOnly; SameSite=Lax; Path=/; Max-Age=' + DESKTOP_STASH_TTL_SECONDS
+}
+
+/** 读出暂存 cookie 并还原成 query 串（不含 "?"）；不可用/非法时返回 null。 */
+function desktopStashQuery(req) {
+  const raw = cookieOf(req, DESKTOP_STASH_COOKIE)
+  if (!raw) return null
+  let decoded = null
+  try { decoded = decodeURIComponent(raw) } catch (e) { return null }
+  // 走与提取端同一套规则：暂存内容来自客户端 Cookie，同样要过滤。
+  // 这套对称性是有承重的——补投出的 URL 必然能被 desktopMarkersOf 认出来，
+  // restore() 才不会在同一份标记上反复跳转。改任一侧都要同步改另一侧。
+  const markers = collectDesktopMarkers(new URLSearchParams(decoded))
+  if (markers === null) return null
+  return markers.map(([k, v]) => k + '=' + encodeURIComponent(v)).join('&')
+}
+
+/**
+ * 记住本次文档请求 URL 上的桌面端标记。
+ *
+ * 必须是「主动记忆」而非「跳转前才记」：退出登录是客户端自己 `location.href = '/'`，
+ * 服务端根本没机会看到那个带标记的 URL 被放弃——等它看到 `GET /` 时标记早已不在，
+ * 无从暂存。因此在渲染器正常加载（URL 带标记）时就落盘，之后无论标记在哪一步丢失
+ * （退出重登、会话过期、核心 token 交换、深链）都能补投回来。
+ *
+ * @returns true 表示写入了暂存 Cookie。
+ */
+function remember(req, res) {
+  if (req.method !== 'GET') return false
+  const url = parseUrl(req.url)
+  if (url === null || url.pathname !== '/') return false
+  const markers = desktopMarkersOf(req.url)
+  if (markers === null) return false
+  res.setHeader('Set-Cookie', desktopStashCookie(markers))
+  return true
+}
+
+/**
+ * 文档请求落到干净的 "/" 时，把记住的桌面端标记补回 URL。
+ * 刻意不清除暂存（见文件顶部说明），过期交给 Cookie 自身的 Max-Age。
+ *
+ * @returns true 表示已接管该请求（已发出 302，调用方应立即 return）。
+ */
+function restore(req, res) {
+  if (req.method !== 'GET') return false
+  const pending = desktopStashQuery(req)
+  if (pending === null) return false
+  const url = parseUrl(req.url)
+  if (url === null || url.pathname !== '/') return false
+  // 核心正在做 token→cookie 交换：必须放行，交换完成后它自己会 303 到干净的 "/"。
+  // 若在这里抢跳，核心的 dsh-auth-* cookie 永远拿不到，/api 会全 401。
+  if (url.searchParams.has('token')) return false
+  // 本次文档请求已经带标记，桌面端能正常启动，无需干预。
+  if (desktopMarkersOf(req.url) !== null) return false
+  res.writeHead(302, { location: '/?' + pending })
+  res.end()
+  return true
+}
+
+export const desktopAdapter = { name: 'dsh-desktop', remember, restore }
+
+// 纯函数供回归测试直接调用（见 test/redirect-scheme.test.mjs）
+export {
+  remember, restore,
+  desktopMarkersOf, desktopStashCookie, desktopStashQuery, collectDesktopMarkers,
+  DESKTOP_STASH_COOKIE, DESKTOP_MARKER_KEYS, DESKTOP_STASH_TTL_SECONDS,
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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 && node test/desktop-marker.test.mjs && node test/audit-null.test.mjs"
   },
   "exports": {
     ".": "./index.js",
@@ -16,6 +16,7 @@
   "files": [
     "index.js",
     "lib/client.js",
+    "lib/desktop-adapter.js",
     "cordis.patch.yml",
     "README.md",
     "README.en.md",