dsh-webui-oauth 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.6.4
+
+修复 OIDC 回调结束后浏览器**停在 JSON 页面上**、需要手动回退的问题。
+
+### 修复：绑定/登录结束后自动回到应用并给出提示
+
+- **现象**：点「绑定 OIDC 身份」完成 IdP 往返后，浏览器停在一段 JSON 上
+  （如 `{"ok":true,"bound":true,"sub":"..."}`），必须手动按后退键回到设置页；
+  失败时同样如此（例如 `{"ok":false,"error":"oidc-authorize-failed",...}`）。
+- **原因**：回调端点直接 `sendJson` 渲染结果。但 OIDC 回调是**浏览器主导的顶层导航**
+  （用户点按钮 → 302 到 IdP → 302 回回调），渲染 JSON 等于把用户丢在一个死页面上，
+  而且看不出操作到底成没成功。
+- **修复**：成功与失败都 **302 回应用**，并带一个回执参数由前端提示：
+  - 成功：`?oidcbound=1` → 设置页提示「OIDC 身份绑定成功」；
+  - 失败：`?oidcerr=<原因>` → 按原因给出可读提示（授权失效 / 未绑定 / 身份不匹配）。
+  回跳复用 `postLoginRedirect()`，顺带完成核心的 launch-token → cookie 交换，
+  否则回到首页仍会被核心 401 拦住。前端读取回执后会用 `history.replaceState`
+  清掉 query，避免刷新时重复提示。
+
+### 安全
+
+- 回执里**不含** sub 等敏感值（只有 `oidcbound=1` / `oidcerr=原因码`），
+  避免把身份标识写进浏览器历史与访问日志。
+
+### 测试
+
+- `test/oidc-bind.test.mjs` 新增「绑定成功后必须回到应用」用例，并把失败路径断言
+  改为校验 302 + 回执；`test/oidc-integration.test.mjs` 的状态校验用例同步更新。
+- 已确认能抓出修复前的行为（回退成 sendJson 时 2 项 FAIL）。
+- 全量 342 项断言通过。
+
 ## 0.6.3
 
 修复部分 IdP 下**绑定 OIDC 立即失败**的问题（点「绑定 OIDC 身份」后立刻收到

package/index.js

@@ -2507,6 +2507,29 @@ export async function apply(ctx) {
    *
    * @returns {Promise<void>} 直接写响应，不返回内容
    */
+  /**
+   * 把浏览器送回应用，并带上一个回执码。
+   *
+   * 为什么需要它：OIDC 回调是**浏览器主导的顶层导航**——用户点「绑定」/「SSO 登录」，
+   * 浏览器 302 到 IdP，IdP 再 302 回本回调。如果这里渲染 JSON，用户就停在一个
+   * 死页面上，只能手动按后退键，而且不知道操作到底成没成功。
+   * 因此成功与失败都应 302 回应用，用 query 参数带上结果，由前端提示。
+   *
+   * 与登录路径一致地复用 postLoginRedirect()：既回到应用根，又能顺带完成
+   * 核心的 launch-token → cookie 交换（否则回到首页仍会被核心 401 拦住）。
+   *
+   * @param res 响应对象
+   * @param code 回执码，前端据此展示提示（如 oidcbound=1 / oidcerr=...）
+   * @param extraHeaders 额外的响应头（如清除一次性 state Cookie）
+   */
+  function redirectBackToApp(ctx2, req, res, code, extraHeaders) {
+    let target = '/'
+    try { target = postLoginRedirect(ctx2, req) || '/' } catch (e) { target = '/' }
+    const sep = target.includes('?') ? '&' : '?'
+    res.writeHead(302, { location: target + sep + code, ...(extraHeaders || {}) })
+    res.end()
+  }
+
   async function startOidcAuthorize(ctx2, req, res, purpose) {
     const creds = await readCredentials(ctx2)
     const o = await oidcOf(creds)
@@ -2688,20 +2711,20 @@ export async function apply(ctx) {
         if (!st) {
           const why = known ? 'state 已过期（TTL ' + Math.round(OIDC_STATE_TTL_MS / 60000) + ' 分钟）' : 'state 无效、已使用或不存在'
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: why })
-          sendJson(res, 200, { ok: false, error: 'oidc-invalid-state' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=invalid-state', clearStateCookie)
           return
         }
         // 登录 CSRF 绑定：回调必须由发起授权的同一浏览器完成（携带同值 Cookie）。
         // 只校验 state 存在于服务端集合不足以阻止“攻击者取 state、受害者完成回调”。
         if (cookieOf(req, COOKIE_OIDC_STATE) !== state) {
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: 'state Cookie 不匹配（疑似登录 CSRF）' })
-          sendJson(res, 200, { ok: false, error: 'oidc-invalid-state' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=invalid-state', clearStateCookie)
           return
         }
         if (!code) {
           const err = params.get('error') || 'missing-code'
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: '授权被拒或缺少 code: ' + sanitizeSub(err) })
-          sendJson(res, 200, { ok: false, error: 'oidc-authorize-failed', detail: err })
+          redirectBackToApp(ctx, req, res, 'oidcerr=' + encodeURIComponent(err), clearStateCookie)
           return
         }
         // 换 token（authorization_code + PKCE verifier + client_secret）
@@ -2761,7 +2784,7 @@ export async function apply(ctx) {
         }
         if (!vres.ok) {
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: 'id_token 验证失败: ' + vres.error })
-          sendJson(res, 200, { ok: false, error: 'oidc-invalid-id-token', detail: vres.error })
+          redirectBackToApp(ctx, req, res, 'oidcerr=' + encodeURIComponent(vres.error), clearStateCookie)
           return
         }
         const rawSub = vres.payload.sub
@@ -2774,7 +2797,8 @@ export async function apply(ctx) {
           // 保留原有 username/hash/ttl，只加 boundSub —— 用 spread 以免漏字段。
           await writeCredentials(ctx, { ...creds, boundSub: rawSub })
           await auditLog(ctx, 'oidc_bind_success', { username: auditName, ip: meta.ip, ua: meta.ua })
-          sendJson(res, 200, { ok: true, bound: true, sub: auditName }, clearStateCookie)
+          // 成功必须【把浏览器送回应用】，而不是停在 JSON 上（见 redirectBackToApp 说明）。
+          redirectBackToApp(ctx, req, res, 'oidcbound=1', clearStateCookie)
           return
         }
 
@@ -2784,12 +2808,12 @@ export async function apply(ctx) {
         const bound = boundSubOf(creds)
         if (!bound) {
           await auditLog(ctx, 'oidc_login_failure', { username: auditName, ip: meta.ip, ua: meta.ua, detail: '尚未绑定 OIDC 身份，拒绝登录' })
-          sendJson(res, 200, { ok: false, error: 'oidc-not-bound' }, clearStateCookie)
+          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: 'sub 与已绑定身份不匹配，拒绝登录' })
-          sendJson(res, 200, { ok: false, error: 'oidc-sub-mismatch', detail: '该 IdP 身份未被绑定到本 WebUI' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=sub-mismatch', clearStateCookie)
           return
         }
 

package/lib/client.js

@@ -146,6 +146,34 @@ window.__ModuleLoader__.load({
 					};
 				}, []);
 
+				// 读取 OIDC 回调带回来的回执。绑定/登录结束后浏览器会被 302 回应用，
+				// 结果通过 query 传递（oidcbound=1 / oidcerr=...）：因为是整页跳转，
+				// 组件重新挂载时才知道刚才发生了什么。
+				react.useEffect(() => {
+					let qs = ''
+					try { qs = String((location && location.search) || '') } catch (e) { qs = '' }
+					if (!qs) return
+					const p = new URLSearchParams(qs)
+					const bound = p.get('oidcbound')
+					const err = p.get('oidcerr')
+					if (bound === null && err === null) return
+					if (bound !== null) {
+						setBindMsg({ kind: 'ok', text: 'OIDC 身份绑定成功。此后只有该身份可通过 SSO 登录。' })
+					} else {
+						const LABELS = {
+							'invalid-state': '授权会话已失效或被中断，请重新发起绑定',
+							'not-bound': '尚未绑定任何 OIDC 身份，SSO 登录已被拒绝',
+							'sub-mismatch': '该 IdP 身份未被绑定到本 WebUI，登录已被拒绝',
+						}
+						setBindMsg({ kind: 'err', text: 'OIDC 操作失败：' + (LABELS[err] || err) })
+					}
+					// 清掉 query：否则用户刷新页面会重复看到这条提示。
+					try {
+						const clean = location.pathname + location.hash
+						history.replaceState(null, '', clean)
+					} catch (e) { /* 无 history 时忽略 */ }
+				}, []);
+
 				// 与服务端 passwordStrength 一致的同步校验
 				const SPECIAL_CHARS = /[!@#$%^&*()_+\-=\[\]{}|;:,.<>?/~]/;
 				function checkPassword(p) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "type": "module",
   "main": "index.js",
   "scripts": {