dsh-feishu-auth 0.1.1 → 0.1.3

package/AGENTS.md

@@ -24,6 +24,7 @@ DSH（DeepSeek Harness）Web 界面的飞书 OAuth 登录网关。一个 Cordis
 | `lib/pages.js` | 提示页（拒绝 / 错误 / 未就绪 / 已登出），全部内联样式 |
 | `enable.patch.yml` / `disable.patch.yml` | 启用 / 停用 overlay |
 | `test/` | `node --test`，零依赖，替身自建 |
+| `docs/architecture.md` / `docs/release.md` | 内部设计（拦截层身份、两段式交接）与发版流程（staged + trusted publishing） |
 
 零运行时依赖：只用 node 内置模块，所以在没 `pnpm install` 过的 profile 里也能直接引用。
 
@@ -110,6 +111,8 @@ feishu-auth[error] 拿不到 harness 的入口地址（connection 服务不可
 2. 在本机 `dsh web` 实测：启动自检 + 未登录 302 + 完整交接 200；涉及卸载/重载的改动要额外验「停用 → 401、再启用 → 302」。
 3. 提交并推送 `git push origin main`（仓库 `jianghuifr/dsh-feishu-auth`，带 `dsh-plugin` topic）。
 4. 影响用户可见行为或配置语义的改动，同步更新 [README.md](README.md) 和 [AGENTS.md](AGENTS.md)（本文）以及架构文档中的对应事实。
+5. 发版：`npm version patch` → 推 tag → CI 走 `npm stage publish`（OIDC，无 token）→ 在 npmjs 批准后上线。详见 [docs/release.md](docs/release.md)。
+6. 合并改动 `.github/workflows/` 的 PR 时，执行合并的凭据必须带 `workflow` scope（GitHub 对 OAuth App / PAT 的硬限制，与改动内容无关）：用 gh CLI 就先 `gh auth refresh -s workflow` 补授权，或改用网页合并，或本地应用同样改动后直接推 `main`。
 
 ## 与 dsh 版本的耦合点
 

package/docs/architecture.md

@@ -14,12 +14,26 @@ flowchart TB
     CFG -->|"是"| FC["503 未就绪页<br/>（故障关闭）"]
     CFG -->|"否"| AU{"有效会话 Cookie?"}
     AU -->|"否"| DN["导航: 302 → 飞书授权页<br/>其它: 401 JSON"]
-    AU -->|"是"| HO{"需要 harness 交接?"}
-    HO -->|"是"| EX["303 → /?token=…<br/>+ 20s 交接标记"]
-    HO -->|"否"| PS["交给 harness 原分发逻辑"]
+    AU -->|"是"| HO{"需要 harness 交接?<br/>（请求前判定）"}
+    HO -->|"是"| EX["303 → /?token=…<br/>+ 阶梯 0"]
+    HO -->|"否"| PS["交给 harness 原分发逻辑<br/>并盯住它的回答"]
+    PS -->|"harness 回 401"| LD{"恢复阶梯"}
+    LD -->|"阶梯 0"| EN["200 同站重进页<br/>+ 阶梯 1"]
+    LD -->|"阶梯 1"| EX2["303 → /?token=…<br/>+ 阶梯 2"]
+    LD -->|"阶梯 2"| ST["200「还差一步」页<br/>+ 清阶梯"]
+    EN --> PS
+    EX2 --> PS
 ```
 
-「需要 harness 交接」的判定：`GET/HEAD` 导航请求、路径是 `/`、URL 上没有 `token` 参数、请求里没有 `dsh-auth-` 开头的 Cookie，且没有交接标记（见下）。
+「需要 harness 交接」有两条触发路径：
+
+1. **请求前判定**：`GET/HEAD` 导航请求、路径是 `/`、URL 上没有 `token` 参数、请求里没有 `dsh-auth-` 开头的 Cookie，且没有阶梯 Cookie。够用即走 `/?token=…`。
+2. **响应后判定（恢复阶梯）**：判定 1 只能看到 `dsh-auth-*` **存不存在**，看不到浏览器到底交没交上来。有两种状态会让已登录的页面请求仍被 harness 打回 401：
+
+   - **凭据作废**：harness 只在「根请求携带本进程启动令牌」时签发 `dsh-auth-*`，进程一重启，浏览器手里那份签名就验不过了；
+   - **凭据被扣下**：harness 那张 Cookie 是 `SameSite=Strict`，而浏览器若正沿一条**跨站跳转链**走（飞书 OAuth 回调就是，且这条链上的后续跳转都留在链里），链内所有请求都不会带上它——尽管它已经存好了。
+
+   两种状态的共同可靠信号就是 harness 自己的 401，所以页面入口的响应被 401 打回时，不把它转给用户，而是按阶梯走一步（阶梯值记在 `dsh-feishu-handoff` 里，见「两段式交接与恢复阶梯」）。
 
 ## 拦截层
 
@@ -57,31 +71,44 @@ sequenceDiagram
     L->>G2: dispose（是最新层 → 还原 original）
 ```
 
-## 两段式交接
+## 两段式交接与恢复阶梯
 
 飞书登录只签发本插件自己的会话 Cookie。harness 另有一层签名 Cookie（`dsh-auth-<authority>`），只在一个**根请求带上本进程启动令牌**时签发。所以「能打开页面」需要两段都完成：
 
 1. 网关把浏览器跳到 `connection.authenticatedUrl()` 给出的 `/?token=<launch token>`；
 2. harness 校验令牌、下发 `dsh-auth-*`，再跳回干净的 `/`。
 
-`connection` 服务**只能**经 `ctx.inject(['connection'], cb)` 取（`ctx.get` 返回 undefined，属性访问直接抛错），所以在插件挂载时捕获成 `entryUrlProvider`，每次请求时调用。取不到时打一行 error，并在交接判定里退化为直接放行给 harness（让它自己的 401 页成为终点，避免无休止往返）。
+`connection` 服务**只能**经 `ctx.inject(['connection'], cb)` 取（`ctx.get` 返回 undefined，属性访问直接抛错），所以在插件挂载时捕获成 `entryUrlProvider`，每次请求时调用。取不到时打一行 error，交接判定退化为「不交接」。
+
+### 阶梯
+
+**`dsh-feishu-handoff`**（20 秒）记的是这台浏览器已经花掉的恢复步数，而不是一个 0/1 标记：
 
-**交接标记**（`dsh-feishu-handoff`，20 秒）是死循环的兜底：浏览器拒绝存 harness Cookie 时，`/` 与 `/?token=…` 之间只会来回一次。
+| 值 | 含义 | 这一层的回答 |
+| --- | --- | --- |
+| 无 | 还没试过 | harness 回 401 → **同站重进页**（200，`location.replace`），记 1 |
+| `0` | 只做过请求前交接 | 同上（同站重进） |
+| `1` | 已同站重进 | harness 回 401 → **`303 /?token=…`**，记 2 |
+| `2` | 重进 + 交接都试过 | harness 回 401 → **「还差一步」页**（200，给按钮与原因），并清掉阶梯 |
+
+为什么要「同站重进」这一步：harness 的 `dsh-auth-<authority>` 带 `SameSite=Strict`，而飞书 OAuth 回调落在浏览器眼里是一条**跨站链**——链上所有请求（包括回调后 303 到 `/?token=…`、harness 再 303 回 `/`）都不带 Strict Cookie。于是在 `/` 这一跳被 harness 打回 401，尽管 Cookie 已经存好。此时从**本站域内的文档**发起一次跳转（我们的重进页就是），导航的同站属性成立，Cookie 就带上了——一次跳转、无需重新登录。实测：harness 的墙页面上执行 `location.replace('/')` 即返回应用页。
+
+作废旧凭据（harness 重启）走的是下一步：`/?token=…` 会重新签发一张能验过的 Cookie；这条链从同站重进之后出发，因此也在同站上下文里，新 Cookie 立刻可用。
+
+阶梯尽头（用户浏览器连续两次都不交出凭据，例如无痕窗口或拦截扩展）由插件自己的页面收尾并打 warn——**harness 的 401 页任何时候都不会被直接转给用户**，因为那张页面只写着一个对用户毫无意义的内部 URL。
 
 ```mermaid
 sequenceDiagram
     participant B as 浏览器
     participant G as 网关
     participant H as harness
-    B->>G: GET /
-    G->>B: 302 /feishu-auth/login
-    B->>G: GET /feishu-auth/login
-    G->>B: 302 飞书授权页（+ state Cookie）
-    B->>G: GET /feishu-auth/callback?code=…&state=…
-    G->>B: 303 /?token=…（+ 会话 Cookie + 交接标记）
-    B->>H: GET /?token=…
-    H->>B: 303 /（+ dsh-auth-* Cookie）
-    B->>G: GET /（会话 + dsh-auth-*）
+    B->>H: GET /?token=…（跨站链内）
+    H->>B: 303 /（+ dsh-auth-* Strict Cookie，链内被扣下）
+    B->>G: GET /（会话有，Strict Cookie 没带上）
+    G->>H: 放行
+    H->>B: 401 认证墙
+    G->>B: 200 同站重进页（吞掉 401，阶梯 1）
+    B->>G: GET /（同站导航 → 带上 Strict Cookie）
     G->>H: 放行
     H->>B: 200 应用页
 ```
@@ -94,7 +121,7 @@ sequenceDiagram
 | --- | --- | --- |
 | `dsh-feishu-session` | `sessionMaxAgeDays`（默认 14 天） | `kind=session`、`sub`（open_id）、`name`、`tenant`、`iat`、`exp` |
 | `dsh-feishu-state` | 10 分钟 | `kind=state`、`nonce`、`next`、`redirectUri`、`iat`、`exp` |
-| `dsh-feishu-handoff` | 20 秒 | 交接标记，防往返 |
+| `dsh-feishu-handoff` | 20 秒 | 恢复阶梯步数（`1` / `2`），防往返 |
 
 载荷统一是 `v1.<base64url(JSON)>.<base64url(HMAC-SHA256)>`，签名密钥是 `$DSH_HOME/feishu-auth/session-secret`（首次启动生成 32 字节、0600、原子写入；重启不变，所以登录态能跨重启存活）。校验用 `timingSafeEqual`，`state` 用常量时间比较防 CSRF。
 
@@ -107,7 +134,10 @@ sequenceDiagram
 | 缺 `appId` / `appSecret` | 故障关闭：所有请求 503「未就绪」页，日志 `[error]` 说明缺什么 |
 | 会话密钥文件不可读写 | 同上（内存里用临时密钥，重启即失效） |
 | `webServer.match` 不存在 | 挂载抛错，插件拒启动——无保护状态不允许运行 |
-| `connection` 服务取不到 | 记 error，交接退化为放行给 harness 的 401 页 |
+| `connection` 服务取不到 | 记 error；不交接，页面入口的 401 由恢复阶梯兜住（同站重进 → 插件自己的页面） |
+| harness 重启后浏览器仍带旧 `dsh-auth-*` | 响应后判定接管：harness 回 401 → 阶梯（同站重进 → 再交接一次）→ 用户无感恢复 |
+| 浏览器沿跨站链到达（飞书 OAuth 回调） | 同一条阶梯的第一步就是为此设计的：同站重进一次即带上 `SameSite=Strict` 的 `dsh-auth-*` |
+| 浏览器两次都不交凭据（无痕窗口 / 拦截扩展） | 阶梯走完 → 插件自己的「还差一步」页 + 一行 warn，不把 harness 的 401 页转给用户 |
 | 启动自检失败 | `[error]` 明确报出：未登录请求未被拦，或持有效会话仍被拒 |
 | 配置项（`allowedUsers` / `sessionMaxAgeDays`）非法 | `allowedUsers` 非法 → 致命（避免悄悄放宽到全员）；`sessionMaxAgeDays` 非法 → 回落默认值 |
 

package/docs/release.md

@@ -19,7 +19,7 @@ npm 路径靠 `package.json` 的 `dsh.bundle.patch` 声明自己是组合包，`
 ```bash
 npm ci               # 只装 devDependencies（eslint）；运行时零依赖
 npm run lint
-npm test             # node --test，39 个用例
+npm test             # node --test，45 个用例
 npm run verify       # lint + test —— CI 与 prepublishOnly 跑的就是它
 npm pack --dry-run   # 检查发布产物内容（15 个文件）
 ```
@@ -48,7 +48,7 @@ git push --follow-tags
 随后批准上线，二选一：
 
 - 网页：npmjs.com → 你的账号 → **Staged Packages** → 选中版本 → Approve（提示 2FA）
-- CLI：`npm stage list` 拿 stage id → `npm stage approve <stage-id>`（需 2FA）
+- CLI：`npm stage list` 拿 stage id → `npm stage approve <stage-id>`（需 2FA；npm 会要求到 `https://www.npmjs.com/auth/cli/…` 做一次浏览器认证，链接一次性且约几分钟过期，过期就重跑命令拿新链接）
 
 批准前可以验货：`npm stage download <stage-id>` 把 tarball 拉下来看，`npm stage reject <stage-id>` 丢弃。
 
@@ -67,17 +67,17 @@ git push --follow-tags
 `stage` 不支持全新包，所以建包这一次必须手工做，之后一律走上面的 staged 流程。
 
 ```bash
-cd ~/.dsh/plugins/dsh-feishu-auth
+# 在你自己的仓库副本里执行
 npm login --registry https://registry.npmjs.org
 npm publish --access public --registry https://registry.npmjs.org
 ```
 
-- 必须显式指定 registry：本机 npm 默认源是镜像站，不加会发到镜像。
+- 若你的 npm 默认源是镜像（国内常见配置），必须显式带 `--registry https://registry.npmjs.org`，否则会发到镜像上。
 - 手工发布的 0.1.0 不带 provenance（provenance 需要 CI 的 OIDC）；从 0.1.1 起走流水线自动带。
 
 ## 版本号与 npm CLI
 
-`npm stage` 需要 npm CLI ≥ 11.15，本机是 11.6.2，所以本机要用 `npx npm@latest stage ...`；`ci.yml` 与 `release.yml` 里都显式 `npm install -g npm@latest`，不受 runner 自带版本影响。
+`npm stage` 需要 npm CLI ≥ 11.15：本地版本不够时用 `npx npm@latest stage ...`。`ci.yml` 与 `release.yml` 里都显式 `npm install -g npm@latest`，不受 runner 自带版本影响。
 
 包名 `dsh-feishu-auth` 已发布（`0.1.0`，2026-09-13；此前查官方 registry 为 404 即未占用）。此后发版一律走 staged 流程，账号需保持 2FA 开启。
 

package/lib/gate.js

@@ -26,7 +26,7 @@ import {
   STATE_TTL_MS,
 } from './config.js';
 import { buildAuthorizeUrl, exchangeCode, fetchUserInfo } from './feishu.js';
-import { renderDenied, renderError, renderLoggedOut, renderMisconfigured } from './pages.js';
+import { renderDenied, renderEntering, renderError, renderLoggedOut, renderMisconfigured, renderRecoveryStuck } from './pages.js';
 import { cookieNames, expiredCookie, generateToken, readCookie, safeEqual, serializeCookie, signPayload, verifyPayload } from './session.js';
 import { clientAddress, isNavigationRequest, normalizeAuthority, requestBaseUrl, sanitizeNext } from './urls.js';
 
@@ -163,9 +163,7 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
    * otherwise land on the harness's 401 page with no way forward.
    *
    * The `token` guard keeps the exchange request itself from looping, and the
-   * handoff marker bounds the attempt when a browser refuses to store the
-   * harness cookie — without it, such a browser would bounce between `/` and
-   * `/?token=…` forever.
+   * ladder cookie bounds the attempt (see {@link passthroughWatchingForAuthWall}).
    */
   function needsHarnessHandoff(req, url) {
     if (url.pathname !== '/') return false;
@@ -177,6 +175,40 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
     return names.some((name) => name.startsWith('dsh-auth-')) !== true;
   }
 
+  /**
+   * How many recovery steps this browser has already spent, from the ladder
+   * cookie: 0 when nothing has been tried (or only the pre-flight handoff),
+   * 1 after the same-site re-entry, 2 after a handoff that followed it.
+   *
+   * An unparsable value (for example the `1` a browser kept from an older
+   * release) counts as one step spent, which only makes the ladder move on
+   * sooner — never a loop.
+   */
+  function recoveryStep(req) {
+    const raw = readCookie(req?.headers?.cookie, HANDOFF_COOKIE);
+    if (typeof raw !== 'string') return 0;
+    const step = Number.parseInt(raw, 10);
+    return Number.isFinite(step) === true && step > 0 ? step : 0;
+  }
+
+  /** Send the browser through the harness's launch-token exchange. */
+  function handoffToHarness(req, res, target, step) {
+    redirect(res, 303, target, {
+      'set-cookie': serializeCookie(HANDOFF_COOKIE, String(step), {
+        maxAgeSeconds: HANDOFF_TTL_SECONDS,
+        secure: isSecure(requestBaseUrl(req)),
+      }),
+    });
+  }
+
+  /** Record a spent step without answering: used by the same-site re-entry page. */
+  function entryCookie(req, step) {
+    return serializeCookie(HANDOFF_COOKIE, String(step), {
+      maxAgeSeconds: HANDOFF_TTL_SECONDS,
+      secure: isSecure(requestBaseUrl(req)),
+    });
+  }
+
   /** Deliver the request to the harness exactly as it would have been delivered. */
   async function passthrough(req, res, route, server) {
     const target = typeof route?.handler === 'function' ? route.handler : server.fallback;
@@ -188,6 +220,97 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
     await target(req, res);
   }
 
+  /** Whether this request is the harness's own page entry point. */
+  function isPageNavigation(req, url) {
+    if (url.pathname !== '/') return false;
+    if (req.method !== 'GET' && req.method !== 'HEAD') return false;
+    return isNavigationRequest(req) === true;
+  }
+
+  /**
+   * Deliver a page navigation to the harness while watching for its auth wall.
+   *
+   * {@link needsHarnessHandoff} can only observe that a `dsh-auth-*` cookie
+   * *exists*; whether the browser actually hands it over is another matter.
+   * Two states produce the harness's wall on an authenticated page request:
+   *
+   * 1. The cookie is stale — it was minted by a previous harness process, so
+   *    its signature no longer verifies.
+   * 2. The cookie is fine but withheld: the harness mints it with
+   *    `SameSite=Strict`, and a browser that is following a cross-site chain
+   *    (the Feishu OAuth redirect, and every hop after it in that chain) does
+   *    not send it for the rest of that chain.
+   *
+   * The wall itself is the dependable signal for both, so it is swallowed and
+   * answered with one recovery step, never forwarded: serving the harness's
+   * page would show the user an error that names an internal URL they cannot
+   * act on. Step 1 re-enters from this origin (a same-site navigation, which
+   * sends the Strict cookie — this alone fixes case 2), step 2 runs the
+   * launch-token exchange (which mints a fresh cookie — case 1), and a browser
+   * that still walls after both gets a page that explains itself instead of a
+   * third round.
+   */
+  async function passthroughWatchingForAuthWall(req, res, route, server, requested) {
+    const target = typeof route?.handler === 'function' ? route.handler : server.fallback;
+    if (typeof target !== 'function') {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    const entryTarget = entryLocation(req, requested);
+    const step = recoveryStep(req);
+
+    // Swallow the auth wall before any of it reaches the socket, so the
+    // recovery answer can still be written on the very same response.
+    const originalWriteHead = res.writeHead;
+    const originalWrite = res.write;
+    const originalEnd = res.end;
+    let walled = false;
+    const restore = () => {
+      res.writeHead = originalWriteHead;
+      res.write = originalWrite;
+      res.end = originalEnd;
+    };
+    res.writeHead = function (status, ...rest) {
+      if (status === 401) {
+        walled = true;
+        return this;
+      }
+      return originalWriteHead.apply(this, [status, ...rest]);
+    };
+    res.write = function (...args) {
+      return walled === true ? true : originalWrite.apply(this, args);
+    };
+    res.end = function (...args) {
+      return walled === true ? this : originalEnd.apply(this, args);
+    };
+    try {
+      await target(req, res);
+    } finally {
+      restore();
+    }
+    if (walled !== true) return;
+
+    const canHandOff = entryTarget !== requested;
+    if (step <= 0) {
+      log.info(`harness 拒绝了页面请求（凭据未送达或被判失效），让浏览器从本站重新进入 ${requested}`);
+      sendHtml(res, 200, renderEntering({ target: requested }), { 'set-cookie': entryCookie(req, 1) });
+      return;
+    }
+    if (step === 1 && canHandOff === true) {
+      log.info('重新进入后仍被拒绝，改走 harness 的入口地址换取新凭据。');
+      handoffToHarness(req, res, entryTarget, 2);
+      return;
+    }
+    log.warn(
+      `这台浏览器连续两次都没把 DSH 的凭据交上来（${requested}）：请检查是否处于无痕窗口或 Cookie 被拦截；` +
+        '登录态本身有效，换个普通窗口即可访问。',
+    );
+    sendHtml(res, 200, renderRecoveryStuck({ target: requested, loginPath: `${prefix}${LOGIN_PATH}` }), {
+      'set-cookie': expiredCookie(HANDOFF_COOKIE, { secure: isSecure(requestBaseUrl(req)) }),
+    });
+  }
+
   /** Refuse an unauthenticated request: redirect browsers, 401 everything else. */
   function deny(req, res, url, principal) {
     if (mode === 'misconfigured') {
@@ -417,22 +540,24 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
       deny(req, res, url, principal);
       return;
     }
+    const requested = `${url.pathname}${url.search}`;
     if (needsHarnessHandoff(req, url)) {
-      const requested = `${url.pathname}${url.search}`;
       const target = entryLocation(req, requested);
-      // A resolver that is missing or throws degrades to the requested path.
-      // Redirecting to it would repeat this exact state forever, so fall
-      // through to the harness instead: its own 401 page is terminal.
+      // A resolver that is missing or throws degrades to the requested path:
+      // hand off only when there is somewhere to hand off to.
       if (target !== requested) {
-        redirect(res, 303, target, {
-          'set-cookie': serializeCookie(HANDOFF_COOKIE, '1', {
-            maxAgeSeconds: HANDOFF_TTL_SECONDS,
-            secure: isSecure(requestBaseUrl(req)),
-          }),
-        });
+        handoffToHarness(req, res, target, 0);
         return;
       }
     }
+    // A `dsh-auth-*` cookie in the request proves nothing about what the
+    // harness will accept, and a cookie the browser stores but withholds (see
+    // passthroughWatchingForAuthWall) is invisible from here — so the page
+    // entry point always checks what the harness actually answers.
+    if (isPageNavigation(req, url)) {
+      await passthroughWatchingForAuthWall(req, res, route, server, requested);
+      return;
+    }
     await passthrough(req, res, route, server);
   }
 

package/lib/pages.js

@@ -80,6 +80,55 @@ function facts(rows) {
   return items === '' ? '' : `<dl>${items}</dl>`;
 }
 
+/**
+ * Quote a value for a `<script>` context, so a URL built from the request can
+ * never close the tag or start a new statement.
+ * @param value - untrusted text.
+ * @returns a JavaScript string literal.
+ */
+function jsString(value) {
+  return JSON.stringify(String(value ?? '')).replaceAll('<', '\\u003c').replaceAll('>', '\\u003e').replaceAll('&', '\\u0026');
+}
+
+/**
+ * The page that re-enters the harness from this origin.
+ *
+ * The harness mints `dsh-auth-<authority>` with `SameSite=Strict`. A browser
+ * that arrives through a cross-site chain — the Feishu OAuth redirect is one,
+ * and the redirects that follow it stay in that chain — therefore does not send
+ * that cookie on the later hops of the same chain, and the harness answers its
+ * auth wall although the cookie is already stored. A navigation started from a
+ * document on this origin is same-site, so one extra hop carries the cookie.
+ * @param options - the path to re-enter.
+ * @returns the HTML document.
+ */
+export function renderEntering({ target }) {
+  const body = `
+<p>已通过飞书验证，正在进入…</p>
+<p class="note">如果没有自动跳转，<a href="${escapeHtml(target)}">点这里继续</a>。</p>
+<script>location.replace(${jsString(target)});</script>`;
+  return renderPage({ title: '正在进入 · DSH', heading: '正在进入 DSH', body });
+}
+
+/**
+ * The page shown when the recovery ladder is exhausted: the browser stored
+ * neither this gate's cookie nor the harness's, so no redirect can help and the
+ * harness's own wall (which names an internal URL the operator would have to
+ * dig out) is replaced with an actionable page.
+ * @param options - the path to retry and the login path.
+ * @returns the HTML document.
+ */
+export function renderRecoveryStuck({ target, loginPath }) {
+  const body = `
+<p>这台浏览器没有把 DSH 自己的凭据交给服务器，自动恢复已经试过两轮。</p>
+<p class="note">常见原因：无痕/隐私模式、拦下本站 Cookie 的拦截扩展、或浏览器把这次访问当成第三方上下文。换个普通窗口通常即可。</p>
+<div class="actions">
+<a class="button" href="${escapeHtml(target)}">再试一次</a>
+<a class="button" href="${escapeHtml(loginPath)}">重新登录</a>
+</div>`;
+  return renderPage({ title: '还差一步 · DSH', heading: '还差一步', body, tone: 'error' });
+}
+
 /**
  * The page an authenticated-but-unauthorized account sees: its own identifiers
  * and nothing about anyone else, so the operator can allowlist the right value.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-feishu-auth",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Feishu (Lark) OAuth login gate for the DeepSeek Harness web GUI.",
   "keywords": [
     "dsh",