dsh-webui-oauth 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.5.1
+
+修复 OIDC 密钥轮换后长时间无法登录的问题。**使用 OIDC/SSO 的部署建议升级。**
+
+### 修复：IdP 轮换签名密钥后，最长 1 小时内无法登录
+
+- **现象**：IdP 轮换签名密钥（换 `kid` 或换算法，如 RS256 → ES256）后，所有 OIDC 登录
+  持续失败，审计记录 `id_token 验证失败: no-signing-key`；重启 dsh 才恢复。
+- **原因**：discovery + JWKS 有 1 小时内存缓存，而缓存命中时不校验"当前 token 的 kid
+  是否还在缓存里"。轮换后缓存里那把旧 key 永远匹配不上，且代码不做任何刷新。
+- **修复**：验签失败且错误属于签名类（`no-signing-key` / `bad-signature`）时，绕过缓存
+  强制重取一次 JWKS 再验；成功后回写缓存，并在审计里记一条 `oidc_jwks_refreshed`，
+  便于运维确认确实发生了密钥轮换。正常路径仍走缓存，不会被架空。
+- **实测**：先在 RS256 IdP 登录（建立缓存），仅把 IdP 换成 ES256，同一 dsh 进程内再登录——
+  修复前必失败，修复后自动恢复。
+
+### 其他
+
+- `makeDiscoveryCache(fetchImpl)` / `fetchOidcDiscovery(issuer, { fetchImpl })` 新增可选的
+  fetch 注入点，仅供测试使用（可在无网络、无 TLS 的环境下完整测试缓存与刷新逻辑）。
+- 新增 `test/jwks-refresh.test.mjs`（14 项）：缓存命中、密钥轮换、refresh 失败不污染缓存、
+  跨源 `jwks_uri` 仍被拒。全量 288 项断言通过。
+
 ## 0.5.0
 
 安全加固与正确性修复。**建议所有用户升级**，其中「原版共存」与「算法绑定」两项在特定部署下会导致严重问题。

package/README.en.md

@@ -345,6 +345,7 @@ Preconditions: **no** `remote-web-ui.publicBaseUrl` configured, `trustBrowserOri
 - **HTTPS proxy that sends no protocol header**: the post-login redirect scheme depends on ① `remote-web-ui.publicBaseUrl` or ② an `X-Forwarded-Proto` / `Forwarded` header from the proxy. With neither, it can only fall back to `http` (the browser then handshakes against the TLS port and the page looks frozen after clicking Login). Pick one: declare the public address in `settings.yaml`, or make the proxy send `proxy_set_header X-Forwarded-Proto $scheme;`. Note `publicBaseUrl` only applies when it matches the request Host, which is what keeps LAN direct access from being rewritten to the public address.
 - **Proxy rewrites Host without forwarding the original host header**: the server then has no browser-side address at all, so without a configured `publicBaseUrl` no correct redirect is possible (it points at the internal upstream port); and `publicBaseUrl` does not apply either, because its authority no longer matches. **The only workable fix is to have the proxy send `X-Forwarded-Host`** (Caddy does by default) or to preserve the original Host. See the measured table in section C of "End-to-end test results".
 - **`--trusted-host` is not optional**: after desktop password login, requests that hit `/api` directly depend on `--trusted-host <public-host:port>`; the remote-web-ui pairing flow (`/remote` channel) does not. Dropping the flag makes every `/api` call return 403.
+- **JWKS caching and key rotation**: discovery + JWKS are cached in memory for 1 hour. After an IdP rotates its signing key the cached key no longer matches; the plugin then **automatically** bypasses the cache, re-fetches once and records an `oidc_jwks_refreshed` audit entry (since 0.5.1). The cost is one extra JWKS request per rotation; an IdP that rotates repeatedly within a very short window can make logins occasionally slower.
 - **Limits of audit pseudonymization**: the HMAC key lives in the same data directory (0600); a local attacker who can read it can brute-force the IP space — pseudonymization protects against "plaintext IPs at rest", not against an attacker with file access.
 - Sessions live in `sessions.jsonl`: they survive restarts (expiry unchanged); uninstalling/disabling the plugin does not affect credentials.
 - Threat model is "browser/network clients": local processes that can read/write the host's memory or files are out of scope.

package/README.md

@@ -362,6 +362,7 @@ IdP 侧日志确认完整往返：`discovery → jwks → authorize(issued code)
 - **HTTPS 反代且未下发协议头**：登录后跳转的 scheme 依赖 ①`remote-web-ui.publicBaseUrl` 或 ②反代下发的 `X-Forwarded-Proto`/`Forwarded`。两者都没有时只能兜底 `http`（此时 https 端口会握手失败、页面「点了没反应」）。请二选一：在 `settings.yaml` 声明对外地址，或让反代 `proxy_set_header X-Forwarded-Proto $scheme;`。注意 `publicBaseUrl` 仅在与请求 Host 一致时生效，用来避免把局域网直连改写到公网。
 - **反代改写 Host 且不下发原始主机头**：此时服务端拿不到浏览器侧地址，未配置 `publicBaseUrl` 得不到正确跳转（会指向内网 upstream 端口）；而 `publicBaseUrl` 因 authority 不匹配同样不生效。**唯一可行的解法是让反代下发 `X-Forwarded-Host`**（Caddy 默认下发）或保留原始 Host。详见「全流程实测结果」C 节的实测总表。
 - **`--trusted-host` 不能省**：桌面浏览器用密码登录后**直连 `/api`** 的请求依赖 `--trusted-host <对外域名:端口>`；而 remote-web-ui 的配对流（`/remote` 通道）不需要它。删掉该参数会导致 `/api` 全 403。
+- **JWKS 缓存与密钥轮换**：discovery + JWKS 有 1 小时内存缓存。IdP 轮换签名密钥后，缓存里那把旧 key 会匹配不上，此时插件**自动**绕过缓存重取一次并记 `oidc_jwks_refreshed` 审计（0.5.1 起）。代价是每次密钥轮换会有一次额外的 JWKS 请求；若 IdP 在极短时间内反复轮换，可能表现为登录偶发变慢。
 - **审计假名化的边界**：HMAC 密钥与审计日志同目录（0600），能读取密钥文件的本地攻击者可对 IP 空间暴力还原；假名化防的是「日志明文落盘」，不是防有文件权限的攻击者。
 - 会话存于数据目录 `sessions.jsonl`：重启后仍生效（到期时间不变）；关闭/卸载插件不影响凭据。
 - 威胁模型为「浏览器/网络客户端」：能直接读写宿主进程内存或文件的本地进程不在防护范围内。

package/index.js

@@ -200,7 +200,7 @@ async function dummyVerify(password) {
 }
 
 // 供测试与工具脚本使用（Cordis 加载时只消费 name/inject/apply，多余导出无副作用）
-export { hashPassword, verifyPassword, auditLog, readAuditEntries, resolveDataDirFrom, DATA_DIR, resolveRedirectScheme, postLoginRedirect, readOidcConfig, writeOidcConfig, configPath, oidcConfigPath, sendJson, makeOidcStateStore }
+export { hashPassword, verifyPassword, auditLog, readAuditEntries, resolveDataDirFrom, DATA_DIR, resolveRedirectScheme, postLoginRedirect, readOidcConfig, writeOidcConfig, configPath, oidcConfigPath, sendJson, makeOidcStateStore, makeDiscoveryCache }
 
 // ---------------- 数据目录与文件 ----------------
 
@@ -1690,13 +1690,15 @@ export function validateIdToken(idToken, opts) {
 // 仅接受 HTTPS issuer。返回 { ok, error, metadata }。
 export async function fetchOidcDiscovery(issuer, opts) {
   try {
+    // opts.fetchImpl 仅用于测试注入（见 makeDiscoveryCache 的说明）。
+    const doFetch = opts && typeof opts.fetchImpl === 'function' ? opts.fetchImpl : (...a) => fetch(...a)
     if (typeof issuer !== 'string' || !issuer.trim()) return { ok: false, error: 'bad-issuer', metadata: null }
     const issuerUrl = new URL(issuer.trim())
     if (issuerUrl.protocol !== 'https:') return { ok: false, error: 'issuer-not-https', metadata: null }
     // RFC 8414 / OIDC Discovery：issuer 路径拼接 .well-known。
     const base = issuerUrl.href.replace(/\/$/, '')
     const url = base + '/.well-known/openid-configuration'
-    const res = await fetch(url, {
+    const res = await doFetch(url, {
       headers: { accept: 'application/json', 'user-agent': 'dsh-webui-oauth/0.4.0' },
       // 不跟随重定向：issuer 是部署者配置的信任锚，跟随跳转就把它交给远端决定
       // （可被用来把 discovery 引到任意主机）。需要跳转的部署应直接配置最终 issuer。
@@ -1726,7 +1728,10 @@ export async function fetchOidcDiscovery(issuer, opts) {
 }
 
 // 拉取 JWKS 并缓存（内存 1h，失败则下次重试）。
-function makeDiscoveryCache() {
+function makeDiscoveryCache(fetchImpl) {
+  // fetchImpl 仅用于测试注入：默认用全局 fetch。这样缓存与刷新逻辑（含密钥轮换
+  // 后的重取）可以在无网络、无 TLS 的环境里被完整测试。
+  const doFetch = typeof fetchImpl === 'function' ? fetchImpl : (...args) => fetch(...args)
   const cache = new Map() // issuer -> { ts, metadata, jwks }
   async function get(issuer) {
     const now = Date.now()
@@ -1737,7 +1742,7 @@ function makeDiscoveryCache() {
     if (hit && now - hit.ts < 3600_000 && hit.metadata) {
       return { ok: true, error: null, metadata: hit.metadata, jwks: hit.jwks }
     }
-    const r = await fetchOidcDiscovery(issuer)
+    const r = await fetchOidcDiscovery(issuer, { fetchImpl: doFetch })
     if (!r.ok) return { ...r, jwks: null }
     let jwks = null
     // jwks_uri 必须与 issuer 同源：否则一次 discovery 响应就能把密钥来源指向任意主机
@@ -1748,7 +1753,7 @@ function makeDiscoveryCache() {
         if (jwksUrl.origin !== new URL(issuer).origin) {
           return { ok: false, error: 'jwks-cross-origin', metadata: r.metadata, jwks: null }
         }
-        const jres = await fetch(r.metadata.jwks_uri, { headers: { accept: 'application/json' }, redirect: 'error' })
+        const jres = await doFetch(r.metadata.jwks_uri, { headers: { accept: 'application/json' }, redirect: 'error' })
         if (jres.ok) {
           const jtxt = await jres.text()
           const parsed = JSON.parse(jtxt)
@@ -1763,7 +1768,25 @@ function makeDiscoveryCache() {
     cache.set(issuer, { ts: now, metadata: r.metadata, jwks })
     return { ok: true, error: null, metadata: r.metadata, jwks }
   }
-  return { get }
+  /**
+   * 跳过缓存强制重新拉取（`get` 的 force 参数）。
+   *
+   * 存在的理由：IdP 轮换签名密钥（kid 换新）后，缓存里那把旧 key 会让
+   * `findJwk` 找不到匹配 → `no-signing-key` / `bad-signature`，
+   * 而缓存 TTL 是 1 小时——等于密钥轮换后最长 1 小时无法登录。
+   * 实测过：同一个进程里把 IdP 的签名算法/密钥换掉，登录立刻开始失败，
+   * 重启进程才恢复（缓存被清空）。
+   *
+   * 调用方仅在【验签失败】且【本次用的是缓存】时才重试一次，避免把
+   * 缓存彻底架空（正常路径仍走缓存，不受影响）。
+   * @param {string} issuer
+   * @returns {Promise<object>} 与 get 同结构
+   */
+  async function refresh(issuer) {
+    cache.delete(issuer)
+    return get(issuer)
+  }
+  return { get, refresh }
 }
 
 /**
@@ -2505,7 +2528,23 @@ export async function apply(ctx) {
           return
         }
         // 验证 id_token
-        const vres = validateIdToken(idToken, { issuer: o.issuer, clientId: o.clientId, nonce: st.nonce, jwks: disc.jwks })
+        let vres = validateIdToken(idToken, { issuer: o.issuer, clientId: o.clientId, nonce: st.nonce, jwks: disc.jwks })
+        // IdP 轮换签名密钥（或更换签名算法）后，进程内缓存的 JWKS 会在最长 1 小时内
+        // 找不到 token 的 kid/alg。这类失败是可自愈的，但缓存不失效就让每个用户先坏一小时。
+        // 因此：签名相关失败时强制绕过缓存重取一次 JWKS，再验一次。
+        // 只在签名类错误上重试（no-signing-key / bad-signature）；claims 类错误重试没有意义。
+        if (!vres.ok && (vres.error === 'no-signing-key' || vres.error === 'bad-signature')) {
+          const originalError = vres.error   // 先记下原错误，后面 vres 会被覆盖
+          const fresh = await oidcDiscovery.refresh(o.issuer)
+          if (fresh.ok && fresh.jwks) {
+            const retry = validateIdToken(idToken, { issuer: o.issuer, clientId: o.clientId, nonce: st.nonce, jwks: fresh.jwks })
+            if (retry.ok) {
+              vres = retry
+              // 审计一次，便于运维发现 IdP 确实发生了密钥轮换（而非每次登录都触发）。
+              await auditLog(ctx, 'oidc_jwks_refreshed', { ip: meta.ip, ua: meta.ua, detail: '缓存 JWKS 未命中，已强制刷新并验签通过（原错误: ' + originalError + '）' })
+            }
+          }
+        }
         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 })

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.5.0",
+  "version": "0.5.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/client-bundle-id.test.mjs && node test/displace-original.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/client-bundle-id.test.mjs && node test/displace-original.test.mjs"
   },
   "exports": {
     ".": "./index.js",