dsh-feishu-auth 0.1.2 → 0.1.3

package/docs/architecture.md

@@ -14,16 +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 原分发逻辑"]
-    PS -->|"harness 回 401<br/>（旧 dsh-auth-* 已作废）"| EX
+    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 交接」有两条触发路径：
 
-1. **请求前判定**：`GET/HEAD` 导航请求、路径是 `/`、URL 上没有 `token` 参数、请求里没有 `dsh-auth-` 开头的 Cookie，且没有交接标记（见下）。
-2. **响应后判定**：判定 1 只能看到 `dsh-auth-*` **存不存在**，但 harness 只在「根请求携带本进程启动令牌」时签发它——harness 一重启，浏览器手里那份旧 Cookie 就作废了，而它的存在反而压住了交接，把用户送上 harness 那张没有出口的 401 页。所以页面入口的请求交给 harness 之后还要看它的回答：**回 401 就再交接一次**（同样受交接标记约束）。
+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` 里，见「两段式交接与恢复阶梯」）。
 
 ## 拦截层
 
@@ -61,33 +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('/')` 即返回应用页。
 
-第 2 步的前提是「根请求带本进程的启动令牌」，所以 **harness 每次重启都会让浏览器里那份 `dsh-auth-*` 作废**。仅凭「Cookie 存不存在」判断交接会漏掉这种情况（旧 Cookie 还在，交接被压住，用户卡在 harness 的 401 页），因此交接判定同时看 harness 的回答：页面入口拿到 401 就再交接一次——老浏览器无需重新登录即可恢复。同理，交接后的 401 若再出现，交接标记会让它止步，把 harness 的 401 页作为终点而不是无尽往返。
+作废旧凭据（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 应用页
 ```
@@ -100,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。
 
@@ -113,8 +134,10 @@ sequenceDiagram
 | 缺 `appId` / `appSecret` | 故障关闭：所有请求 503「未就绪」页，日志 `[error]` 说明缺什么 |
 | 会话密钥文件不可读写 | 同上（内存里用临时密钥，重启即失效） |
 | `webServer.match` 不存在 | 挂载抛错，插件拒启动——无保护状态不允许运行 |
-| `connection` 服务取不到 | 记 error，交接退化为放行给 harness 的 401 页 |
-| harness 重启后浏览器仍带旧 `dsh-auth-*` | 响应后判定接管：harness 回 401 → 自动再交接一次（用户无感）；已带交接标记时不再重试，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 个文件）
 ```

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;
@@ -178,20 +176,39 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
   }
 
   /**
-   * Send the browser through the harness's launch-token exchange.
+   * 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.
    *
-   * The marker bounds retries: a browser that refuses to store the harness
-   * cookie would otherwise bounce between `/` and `/?token=…` forever.
+   * 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 handoffToHarness(req, res, target) {
+  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, '1', {
+      '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;
@@ -214,16 +231,24 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
    * Deliver a page navigation to the harness while watching for its auth wall.
    *
    * {@link needsHarnessHandoff} can only observe that a `dsh-auth-*` cookie
-   * *exists*, but the harness mints that cookie solely through its per-process
-   * launch-token exchange — so after a harness restart the cookie a browser
-   * still holds is worthless, and its presence suppresses the handoff, landing
-   * the user on the harness's terminal 401 page with no way forward.
+   * *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 harness's own answer is the dependable signal, so a 401 on a page
-   * navigation is answered with one more handoff. The exchange is left alone
-   * when there is nowhere to hand off to (no resolver), when this very request
-   * carries the marker (a browser that will not store the cookie), or when the
-   * harness answers anything other than 401 (that answer is forwarded as is).
+   * 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;
@@ -233,16 +258,10 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
       return;
     }
     const entryTarget = entryLocation(req, requested);
-    const canHandOff =
-      entryTarget !== requested &&
-      cookieNames(req?.headers?.cookie).includes(HANDOFF_COOKIE) !== true;
-    if (canHandOff !== true) {
-      await target(req, res);
-      return;
-    }
+    const step = recoveryStep(req);
 
-    // Swallow the auth wall before any of it reaches the socket, so the 303 can
-    // still be written on the very same response.
+    // 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;
@@ -270,7 +289,26 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
     } finally {
       restore();
     }
-    if (walled === true) handoffToHarness(req, res, entryTarget);
+    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. */
@@ -505,16 +543,17 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
     const requested = `${url.pathname}${url.search}`;
     if (needsHarnessHandoff(req, url)) {
       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) {
-        handoffToHarness(req, res, target);
+        handoffToHarness(req, res, target, 0);
         return;
       }
     }
-    // A stale `dsh-auth-*` cookie keeps needsHarnessHandoff quiet, so the page
-    // entry point also checks what the harness actually answers.
+    // 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;

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.2",
+  "version": "0.1.3",
   "description": "Feishu (Lark) OAuth login gate for the DeepSeek Harness web GUI.",
   "keywords": [
     "dsh",