dsh-webui-oauth 0.7.3 → 0.7.5

package/index.js

@@ -157,6 +157,7 @@ import { readFileSync, writeFileSync, appendFileSync, accessSync, mkdirSync, unl
 import { fileURLToPath } from "node:url";
 import { resolve as resolvePath } from "node:path";
 import { promisify } from "node:util";
+import { AsyncLocalStorage } from "node:async_hooks";
 // 宿主适配层（DSH Desktop 的 dsh-desktop-* 标记透传）。
 // 整体摘除：删掉本行 + 网关里两处标着「宿主适配层」的代码块 + lib/desktop-adapter.js。
 import { desktopAdapter } from './lib/desktop-adapter.js';
@@ -473,11 +474,33 @@ async function readOidcConfig(ctx, creds) {
   return { oidc: null, legacy: false }
 }
 
-/** 写入 OIDC 配置（独立文件，0600 由数据目录权限兜底）。 */
-async function writeOidcConfig(ctx, oidc) {
+/**
+ * 读取插件配置文件的**全部**顶层字段（不止 oidc）。
+ * 用于在不破坏其它配置的前提下写入 remoteTrust 等新字段。
+ */
+async function readPluginConfigFile(ctx) {
+  try {
+    const raw = await ctx.fs.readText(await ctx.fs.resolve(oidcConfigPath()))
+    const parsed = raw ? JSON.parse(raw) : null
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch (e) {
+    return {}
+  }
+}
+
+/** 合并写入插件配置文件的顶层字段，保留未提及的键。 */
+async function writePluginConfigFile(ctx, patch) {
   ensureDataDir()
+  const current = await readPluginConfigFile(ctx)
+  const next = { ...current, ...patch }
   const target = await ctx.fs.resolve(oidcConfigPath())
-  await ctx.fs.writeText(target, JSON.stringify({ v: 1, oidc }), undefined, undefined, { mode: 'danger-full-access' })
+  await ctx.fs.writeText(target, JSON.stringify(next), undefined, undefined, { mode: 'danger-full-access' })
+  return next
+}
+
+/** 写入 OIDC 配置（独立文件，0600 由数据目录权限兜底）。保留其它顶层字段。 */
+async function writeOidcConfig(ctx, oidc) {
+  await writePluginConfigFile(ctx, { v: 1, oidc })
 }
 
 /** 从凭据对象里剥离历史遗留的 oidc 段（迁移到独立文件后不再重复保存）。 */
@@ -1051,6 +1074,11 @@ f.addEventListener('submit', function (ev) {
 
 const API_PREFIX = '/api'
 const PLUGINS_PREFIX = '/plugins'
+
+// 每次 /api 请求的上下文：官方 DeepSeek 登录需要知道"浏览器用的是哪个回环 origin"，
+// 以便把回调 origin 选成同一 host（cookie 才能对上）。用 AsyncLocalStorage 而不是
+// 全局变量，避免并发请求互相串。
+const apiRequestStore = new AsyncLocalStorage()
 // alpha.2 起事件流 WebSocket 由 dsh-api-gateway 的 /api/remote.mux 承载；
 // 旧的 events.mux/events.host 已删除。候选列表仅用于"核心事件流是否就位"的
 // fail-closed 判断；实际包装已改为**所有** upgrade 路由（见 installRouteGate）。
@@ -1070,12 +1098,15 @@ const UPGRADE_CANDIDATES = ['/api/remote.mux', '/api/events.mux', '/api/events.h
 // 公开（允许匿名）的**精确路径**。只放行登录/OIDC 往返所必需的最小集合：
 // 少一条登录就进不去，多一条就可能泄露数据。新增请写进 remote-web-ui.publicPaths，
 // 不要直接改这里——部署差异不该进代码。
+//
+// 注意：**不包含** /oauth/callback（官方 DeepSeek 账号登录的回调）。它由账号平台
+// 在登录开始时动态注册，必须持有插件会话才能访问；远程部署下浏览器根本到不了
+// 这个回环地址，改由本插件的「回调中转」端点代为完成（见 oauthRelay）。
 const PUBLIC_EXACT_PATHS = new Set([
   '/dsh-webui-oauth/login',        // 登录页 GET + 提交 POST
   '/dsh-webui-oauth/setup',        // 首次初始化（由 setup token 把关）
   '/dsh-webui-oauth/oidc/login',   // SSO 发起（未绑定时内部拒绝）
   '/dsh-webui-oauth/oidc/callback',// IdP 回跳（state + PKCE + 验签把关）
-  '/oauth/callback',               // 账号平台的 OAuth 回跳（state 常量时间比对）
 ])
 
 // 本插件自己注册的端点：内部**逐个**自带 checkRequest（公开的那几个按设计放行）。
@@ -1095,6 +1126,9 @@ const SELF_GATED_EXACT_PATHS = new Set([
   '/dsh-webui-oauth/oidc/unbind',
   '/dsh-webui-oauth/oidc/callback',
   '/dsh-webui-oauth/oidc/logout',
+  '/dsh-webui-oauth/oidc/reauth',
+  '/dsh-webui-oauth/oauth-relay',
+  '/dsh-webui-oauth/remote-trust',
 ])
 
 /**
@@ -1151,6 +1185,100 @@ export function matchesPublicPath(path, patterns) {
   return false
 }
 
+// ---------------- 官方 DeepSeek 账号登录（远程回环回调中转） ----------------
+//
+// 上游 deepseek-account-platform 的 loginOrigin() **只接受**
+// http://localhost|127.0.0.1|[::1]:<port>（显式非零端口），不支持反代域名。
+// 远程部署下：
+//   1) 把 startSignIn 的 callbackOrigin 改写成回环地址（同 host 优先，保证 cookie）；
+//   2) 浏览器授权后会被重定向到 http://127.0.0.1:<port>/oauth/callback——
+//      用户机器上通常没有这个服务，页面打不开但地址栏里有完整回调 URL；
+//   3) 设置页的「回调中转」把该 URL 粘贴回来，插件在服务端**内部重放**给账号平台
+//      注册的 /oauth/callback handler（直接调原始 handler，跳过闸门）。
+//
+// 因此 /oauth/callback **不需要公开**：它仍受会话闸门保护；中转端点自己也要求会话。
+
+/** 判断一个 origin 是否是上游 loginOrigin() 接受的回环 HTTP origin。 */
+export function isLoopbackLoginOrigin(value) {
+  try {
+    const u = new URL(String(value || ''))
+    if (u.protocol !== 'http:') return false
+    if (!['localhost', '127.0.0.1', '[::1]'].includes(u.hostname)) return false
+    if (!u.port || Number(u.port) === 0) return false
+    if (u.pathname !== '/' || u.search || u.hash || u.username || u.password) return false
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+/**
+ * 校验用户粘贴回来的回调 URL，并抽出 query 串。
+ * 只接受 http://{localhost|127.0.0.1|[::1]}:<本机端口>/oauth/callback 且
+ * code/state 各恰好一个——既防 SSRF/开放重定向，也防误粘贴。
+ *
+ * @returns {{ ok: true, query: string } | { ok: false, error: string }}
+ */
+export function parseOAuthRelayUrl(raw, port) {
+  if (typeof raw !== 'string' || !raw.trim()) return { ok: false, error: 'invalid-url' }
+  let u
+  try { u = new URL(raw.trim()) } catch (e) { return { ok: false, error: 'invalid-url' } }
+  if (u.protocol !== 'http:') return { ok: false, error: 'invalid-url' }
+  if (!['localhost', '127.0.0.1', '[::1]'].includes(u.hostname)) return { ok: false, error: 'invalid-url' }
+  if (!u.port || Number(u.port) !== Number(port)) return { ok: false, error: 'invalid-url' }
+  if (u.pathname !== '/oauth/callback') return { ok: false, error: 'invalid-url' }
+  if (u.username || u.password || u.hash) return { ok: false, error: 'invalid-url' }
+  const codes = u.searchParams.getAll('code')
+  const states = u.searchParams.getAll('state')
+  if (codes.length !== 1 || states.length !== 1 || !codes[0]) return { ok: false, error: 'invalid-url' }
+  return { ok: true, query: u.searchParams.toString() }
+}
+
+/**
+ * 把官方账号登录的 callbackOrigin 桥接到回环地址。
+ * 版本兼容：deepseekAccount 服务不存在 / 方法签名变化时静默跳过，不影响其他功能。
+ *
+ * @returns {boolean} 是否注册了桥接
+ */
+export function installAccountLoginBridge(ctx) {
+  try {
+    if (!ctx || typeof ctx.inject !== 'function') return false
+    ctx.inject(['deepseekAccount'], (scoped) => {
+      try {
+        const account = scoped.deepseekAccount
+        if (!account || typeof account.startSignIn !== 'function') return
+        if (account.startSignIn.__dshWuaBridged === true) return
+        const raw = account.startSignIn
+        const original = raw.bind(account)
+        const bridged = function (client, callbackOrigin, loginSource) {
+          let origin = callbackOrigin
+          if (!isLoopbackLoginOrigin(origin)) {
+            // 本地访问：请求 Host 就是回环时优先用它（cookie 同 host，回调可直接命中）。
+            // 远程访问：回落到 127.0.0.1:<本机端口>，由用户把回调 URL 粘贴回来。
+            const host = (apiRequestStore.getStore() || {}).host || ''
+            const port = ctx.webServer && ctx.webServer.port
+            origin = isLoopbackHost(host) && /:\d+$/.test(String(host))
+              ? 'http://' + host
+              : 'http://127.0.0.1:' + (port || 3080)
+          }
+          return original(client, origin, loginSource)
+        }
+        bridged.__dshWuaBridged = true
+        account.startSignIn = bridged
+        try {
+          scoped.effect(() => () => {
+            if (account.startSignIn === bridged) account.startSignIn = raw
+          }, 'dsh-webui-oauth: account login bridge')
+        } catch (e) { /* ignore */ }
+        try { ctx.logger.info('[dsh-webui-oauth] deepseek account login bridge active (loopback callback)') } catch (e) { /* ignore */ }
+      } catch (e) { /* 账号平台结构变化：跳过 */ }
+    })
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
 // ---------------- 远程访问信任（原 dsh-remote-trust 的可选内置） ----------------
 //
 // 背景：dsh-client-connection 用 `__DSH_TRANSPORT__.ownsHost === true` 或页面 hostname
@@ -1201,19 +1329,25 @@ export function remoteTrustEnabled(ctx) {
  *
  * @returns {boolean} 是否已安装
  */
-export function installRemoteTrust(ctx) {
-  if (!remoteTrustEnabled(ctx)) return false
+export function applyRemoteTrust(ctx, enabled) {
+  if (!enabled) return { ok: true, off: null }
   const ws = ctx && ctx.webServer
   if (!ws || typeof ws.tapIndex !== 'function') {
-    try { ctx.logger.warn('[dsh-webui-oauth] remote-web-ui.trustRemoteHost 已启用，但 webServer.tapIndex 不可用；未注入 ownsHost') } catch (e) { /* ignore */ }
-    return false
+    try { ctx.logger.warn('[dsh-webui-oauth] 远程访问信任已启用，但 webServer.tapIndex 不可用；未注入 ownsHost') } catch (e) { /* ignore */ }
+    return { ok: false, off: null }
   }
   const off = ws.tapIndex(injectRemoteTrust)
   try {
     if (typeof ctx.effect === 'function') ctx.effect(() => off, 'dsh-webui-oauth: remote trust index tap')
   } catch (e) { /* ignore */ }
   try { ctx.logger.info('[dsh-webui-oauth] remote trust index tap registered (__DSH_TRANSPORT__.ownsHost = true)') } catch (e) { /* ignore */ }
-  return true
+  return { ok: true, off }
+}
+
+/** 兼容旧调用：按 settings 配置安装一次。 */
+export function installRemoteTrust(ctx) {
+  if (!remoteTrustEnabled(ctx)) return false
+  return applyRemoteTrust(ctx, true).ok
 }
 
 /** 该请求是否是一次浏览器导航（而不是 fetch/XHR 的接口调用）。 */
@@ -1458,8 +1592,16 @@ function installRouteGate(ctx, checkRequest, log, options) {
         delete req.headers['sec-fetch-mode']
         delete req.headers['sec-fetch-dest']
       }
+      // 记录本次 /api 请求的 Host：官方 DeepSeek 登录的 startSignIn 需要据此
+      // 选择回环回调 origin（同一 host，cookie 才能对上）。仅 /api 需要。
+      if (route.path === API_PREFIX) {
+        return apiRequestStore.run({ host: (req.headers && req.headers.host) || '' }, () => original(req, res))
+      }
       return original(req, res)
     }
+    // 供「回调中转」在服务端内部重放 /oauth/callback：直接调用原始 handler，
+    // 绕过闸门的会话检查（中转端点自己已经做了 checkRequest）。
+    wrapped.__dshWuaOriginal = original
     route.handler = wrapped
     return () => { route.handler = original }
   }
@@ -2629,7 +2771,33 @@ export async function apply(ctx) {
   refreshSsoOnly().catch(() => {})
 
   // 远程访问信任（可选）：反代域名下让设置页可用。默认关闭；tapIndex 缺失时安全降级。
-  installRemoteTrust(ctx)
+  // 配置来源：插件配置 remoteTrust（设置页按钮写入），其次 settings 的
+  // remote-web-ui.trustRemoteHost（兼容手工配置）。
+  let remoteTrustOff = null
+  let remoteTrustFlag = false
+  const setRemoteTrustEnabled = (enabled) => {
+    if (!enabled) {
+      if (remoteTrustOff) { try { remoteTrustOff() } catch (e) { /* ignore */ } remoteTrustOff = null }
+      remoteTrustFlag = false
+      return true
+    }
+    if (remoteTrustOff) { remoteTrustFlag = true; return true }
+    const applied = applyRemoteTrust(ctx, true)
+    if (applied.ok) {
+      remoteTrustOff = applied.off
+      remoteTrustFlag = true
+      return true
+    }
+    remoteTrustFlag = false
+    return false
+  }
+  readPluginConfigFile(ctx).then((cfg) => {
+    const enabled = cfg.remoteTrust === true || remoteTrustEnabled(ctx)
+    setRemoteTrustEnabled(enabled)
+  }).catch(() => {})
+
+  // 官方 DeepSeek 账号登录：把 callbackOrigin 桥接到回环地址（远程部署由中继端点完成）。
+  installAccountLoginBridge(ctx)
   if (!gate.ok()) {
     ctx.logger.error('[dsh-webui-oauth] ROUTE GATE INCOMPLETE — ' + gate.problems().join('; ')
       + '. /api and/or WebSocket may be unprotected; the gate will still wrap them if they register later.')
@@ -2663,12 +2831,31 @@ export async function apply(ctx) {
   // 授权请求状态表（TTL + 容量上限），见 makeOidcStateStore 的说明。
   // 必须在后台定时器使用 purge 之前定义。
   const oidcStateStore = makeOidcStateStore()
+
+  // 敏感操作（保存配置 / 禁用 / 解绑）的 SSO 复验令牌：
+  // 一次性、2 分钟。密码被禁用（仅允许 SSO）时，用户仍可用 SSO 完成二次验证。
+  const reauthTokens = new Map()
+  const REAUTH_TTL_MS = 2 * 60 * 1000
+  const mintReauthToken = (username) => {
+    const token = randomBytes(16).toString('hex')
+    reauthTokens.set(token, { username, expiresAt: Date.now() + REAUTH_TTL_MS })
+    return token
+  }
+  const consumeReauthToken = (token) => {
+    if (typeof token !== 'string' || !token) return null
+    const rec = reauthTokens.get(token)
+    if (!rec) return null
+    reauthTokens.delete(token)
+    if (rec.expiresAt <= Date.now()) return null
+    return rec
+  }
   const purgeExpiredOidcStates = oidcStateStore.purge
 
   // 后台任务：过期会话清理 + enabled 状态刷新
   const bgTimer = setInterval(async () => {
     const now = Date.now()
     for (const [k, s] of sessions.live) if (s.expiresAt <= now) sessions.delete(k)
+    for (const [k, v] of reauthTokens) if (v.expiresAt <= now) reauthTokens.delete(k)
     purgeExpiredOidcStates()
     try {
       const creds = await readCredentials(ctx)
@@ -2935,8 +3122,8 @@ export async function apply(ctx) {
           username: enabled ? creds.username : null,
           ttl: ttlOf(creds),
           sessionsPersisted: sessions.ok,
-          // 远程访问信任（可选）：是否按 remote-web-ui.trustRemoteHost 注入了 ownsHost。
-          remoteTrust: remoteTrustEnabled(ctx),
+          // 远程访问信任（可选）：是否已注入 ownsHost。
+          remoteTrust: remoteTrustFlag,
           // 核心兜底席位形态（handler | resource | absent | unknown）：核心升级后
           // 如果这里变成 unknown，文档请求会 404 —— 排查时先看这个字段。
           fallback: fallbackShape(ctx.webServer),
@@ -3056,7 +3243,9 @@ export async function apply(ctx) {
           }
         }
         if (wasEnabled) {
-          const curValid = current && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash)
+          // 支持 SSO 复验令牌（「仅允许 SSO」时密码登录入口不可用）
+          const reauthOk = !!consumeReauthToken(body.reauthToken)
+          const curValid = reauthOk || (current && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash))
           if (!curValid) {
             await auditLog(ctx, 'configure_failure', { username, ip: meta.ip, ua: meta.ua, detail: '当前密码不正确' })
             sendJson(res, 200, { ok: false, error: 'current-invalid' })
@@ -3223,7 +3412,8 @@ export async function apply(ctx) {
           sendJson(res, 200, { ok: true })
           return
         }
-        const curValid = current && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash)
+        const reauthOk = !!consumeReauthToken(body.reauthToken)
+        const curValid = reauthOk || (current && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash))
         if (!curValid) {
           await auditLog(ctx, 'disable_failure', { username: creds.username, ip: meta.ip, ua: meta.ua, detail: '当前密码不正确' })
           sendJson(res, 200, { ok: false, error: 'current-invalid' })
@@ -3359,6 +3549,39 @@ export async function apply(ctx) {
     },
   }), 'dsh-webui-oauth: oidc login')
 
+  // OIDC 复验：GET /dsh-webui-oauth/oidc/reauth
+  //
+  // 用于「保存认证配置 / 禁用认证 / 解绑」前的二次验证。要求已登录会话；
+  // 走一次 IdP 授权后，回调只签发一次性复验令牌（2 分钟），不新建会话。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-webui-oauth/oidc/reauth',
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          sendJson(res, 405, { error: '仅支持 GET' })
+          return
+        }
+        if (!checkRequest(req)) {
+          sendJson(res, 401, { error: 'unauthorized' })
+          return
+        }
+        const creds0 = await readCredentials(ctx)
+        if (!(await oidcEnabled(creds0))) {
+          sendJson(res, 200, { ok: false, error: 'oidc-not-configured' })
+          return
+        }
+        if (!isOidcBound(creds0)) {
+          sendJson(res, 200, { ok: false, error: 'oidc-not-bound' })
+          return
+        }
+        await startOidcAuthorize(ctx, req, res, 'reauth')
+      } catch (e) {
+        sendJson(res, 500, { error: e && e.message ? e.message : String(e) })
+      }
+    },
+  }), 'dsh-webui-oauth: oidc reauth')
+
   // 发起 OIDC 绑定授权：GET /dsh-webui-oauth/oidc/bind
   //
   // 必须先持有有效的本地会话（已登录）——绑定语义是"把我这个管理员账号
@@ -3406,7 +3629,8 @@ export async function apply(ctx) {
         const creds = await readCredentials(ctx)
         const meta = requestMeta(req)
         const current = String(body.current || '')
-        const curValid = current && creds && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash)
+        const reauthOk = !!consumeReauthToken(body.reauthToken)
+        const curValid = reauthOk || (current && creds && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash))
         if (!curValid) {
           await auditLog(ctx, 'oidc_unbind_failure', { username: creds && creds.username ? creds.username : null, ip: meta.ip, ua: meta.ua, detail: '当前密码不正确' })
           sendJson(res, 200, { ok: false, error: 'current-invalid' })
@@ -3556,6 +3780,25 @@ export async function apply(ctx) {
 
         // 用途分支：绑定 vs 登录。purpose 来自服务端 state 表（见 startOidcAuthorize），
         // 浏览器无法通过改 URL 把绑定流程降级成登录流程。
+        // SSO 复验：用于保存配置/禁用/解绑的二次验证，不新建会话。
+        if (st.purpose === 'reauth') {
+          const bound = boundSubOf(creds)
+          if (!bound) {
+            await auditLog(ctx, 'oidc_login_failure', { username: auditName, ip: meta.ip, ua: meta.ua, detail: '复验时尚未绑定身份' })
+            redirectBackToApp(ctx, req, res, 'oidcerr=not-bound', clearStateCookie)
+            return
+          }
+          if (!safeTokenEquals(String(rawSub), bound)) {
+            await auditLog(ctx, 'oidc_login_failure', { username: auditName, ip: meta.ip, ua: meta.ua, detail: '复验身份不匹配' })
+            redirectBackToApp(ctx, req, res, 'oidcerr=sub-mismatch', clearStateCookie)
+            return
+          }
+          const token = mintReauthToken(rawSub)
+          await auditLog(ctx, 'oidc_reauth_success', { username: auditName, ip: meta.ip, ua: meta.ua })
+          redirectBackToApp(ctx, req, res, 'oidcreauth=' + token, clearStateCookie)
+          return
+        }
+
         if (st.purpose === 'bind') {
           // 绑定：把本次校验通过的 sub 记进凭据文件。
           // 保留原有 username/hash/ttl，只加 boundSub —— 用 spread 以免漏字段。
@@ -3632,6 +3875,118 @@ export async function apply(ctx) {
     },
   }), 'dsh-webui-oauth: oidc logout')
 
+  // 远程访问信任开关：POST /dsh-webui-oauth/remote-trust
+  //
+  // 设置页按钮调用。写插件配置（不碰核心 settings），并动态安装/移除 index tap。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-webui-oauth/remote-trust',
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: '仅支持 POST' })
+          return
+        }
+        if (!checkRequest(req)) {
+          sendJson(res, 401, { error: 'unauthorized' })
+          return
+        }
+        const body = await readJsonBody(req, res)
+        if (body === null) return
+        if (typeof body.enabled !== 'boolean') {
+          sendJson(res, 200, { ok: false, error: 'invalid', reason: 'enabled 须为 boolean' })
+          return
+        }
+        await writePluginConfigFile(ctx, { remoteTrust: body.enabled })
+        const applied = setRemoteTrustEnabled(body.enabled)
+        if (!applied) {
+          sendJson(res, 200, {
+            ok: false,
+            error: 'tap-index-unavailable',
+            reason: '当前核心不支持 webServer.tapIndex，无法注入 ownsHost',
+          })
+          return
+        }
+        const meta = requestMeta(req)
+        await auditLog(ctx, 'remote_trust', {
+          username: null, ip: meta.ip, ua: meta.ua,
+          detail: body.enabled ? '已开启远程访问信任' : '已关闭远程访问信任',
+        })
+        sendJson(res, 200, { ok: true, enabled: remoteTrustFlag })
+      } catch (e) {
+        sendJson(res, 500, { error: 'remote-trust-failed' })
+      }
+    },
+  }), 'dsh-webui-oauth: remote trust toggle')
+
+  // 官方 DeepSeek 登录的「回调中转」：POST /dsh-webui-oauth/oauth-relay
+  //
+  // 远程部署下，浏览器授权后会被重定向到 http://127.0.0.1:<port>/oauth/callback
+  // （上游只允许回环回调），用户机器上通常没有这个服务。设置页让用户把地址栏
+  // 里的完整 URL 粘贴回来，这里在服务端内部重放给账号平台注册的 handler。
+  //
+  // 安全性：
+  //   - 端点本身要求插件会话（SELF_GATED_EXACT_PATHS，不公开）；
+  //   - 只接受本机端口的 /oauth/callback + 单个 code/state（防 SSRF/开放重定向）；
+  //   - state 与 PKCE 由账号平台校验，且一次性。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-webui-oauth/oauth-relay',
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: '仅支持 POST' })
+          return
+        }
+        if (!checkRequest(req)) {
+          sendJson(res, 401, { error: 'unauthorized' })
+          return
+        }
+        const body = await readJsonBody(req, res)
+        if (body === null) return
+        const parsed = parseOAuthRelayUrl(body.url, ctx.webServer.port)
+        if (!parsed.ok) {
+          sendJson(res, 200, { ok: false, error: parsed.error, hint: '请粘贴浏览器地址栏里完整的 http://127.0.0.1:<端口>/oauth/callback?... 地址' })
+          return
+        }
+        const route = ctx.webServer.exact && ctx.webServer.exact.get
+          ? ctx.webServer.exact.get('/oauth/callback')
+          : undefined
+        const handler = route && route.handler
+          ? (route.handler.__dshWuaOriginal || route.handler)
+          : null
+        if (typeof handler !== 'function') {
+          sendJson(res, 200, { ok: false, error: 'no-pending', hint: '没有进行中的官方登录，请先在设置 → 账号里点登录，再粘贴回调地址' })
+          return
+        }
+        const fakeReq = {
+          method: 'GET',
+          url: '/oauth/callback?' + parsed.query,
+          headers: Object.assign({}, req.headers || {}, { host: '127.0.0.1:' + ctx.webServer.port }),
+          socket: { remoteAddress: '127.0.0.1' },
+        }
+        const fakeRes = {
+          statusCode: 200, headers: {}, body: null,
+          writeHead(s, h) { this.statusCode = s; if (h) for (const k of Object.keys(h)) this.headers[String(k).toLowerCase()] = h[k] },
+          setHeader(k, v) { this.headers[String(k).toLowerCase()] = v },
+          getHeader(k) { return this.headers[String(k).toLowerCase()] },
+          end(b) { this.body = b === undefined ? '' : String(b) },
+          destroy() {},
+          on() { return this },
+        }
+        await handler(fakeReq, fakeRes)
+        const meta = requestMeta(req)
+        await auditLog(ctx, 'oauth_relay', {
+          username: null, ip: meta.ip, ua: meta.ua,
+          detail: '已重放官方登录回调（状态 ' + fakeRes.statusCode + '）',
+        })
+        sendJson(res, 200, { ok: true, accepted: true })
+      } catch (e) {
+        sendJson(res, 500, { error: 'oauth-relay-failed' })
+      }
+    },
+  }), 'dsh-webui-oauth: oauth relay')
+
   // ---------------- 传输层拦截 ----------------
 
   // 兜底拦截：所有未被 exact / 更长前缀认领的请求（index.html、/assets/*、SPA 路由等）