dsh-feishu-auth 0.1.2 → 0.2.0

package/AGENTS.md

@@ -19,6 +19,7 @@ DSH（DeepSeek Harness）Web 界面的飞书 OAuth 登录网关。一个 Cordis
 | `lib/gate.js` | 网关引擎：分发拦截与层标记、OAuth 端点、拒绝策略、harness 两段式交接 |
 | `lib/feishu.js` | 飞书接口：授权 URL、换 user_access_token、读用户信息 |
 | `lib/session.js` | HMAC 签名 Cookie（会话 / state）、密钥文件读写 |
+| `lib/client.js` | 浏览器半边：设置面板「退出登录」入口，注册进插槽 `settings.action` |
 | `lib/config.js` | 配置解析与 Cookie 名、TTL 常量 |
 | `lib/urls.js` | Host 规范化、回调地址推导、`next` 开放重定向防护、导航请求判定 |
 | `lib/pages.js` | 提示页（拒绝 / 错误 / 未就绪 / 已登出），全部内联样式 |
@@ -60,9 +61,10 @@ cd ~/.dsh/plugins/dsh-feishu-auth && node --test    # 单元用例
 | --- | --- |
 | 启动日志 | `飞书登录已挂载 …` + `网关自检通过（未登录 → HTTP 401，已登录 → HTTP 404）`，无 `[error]` |
 | 未登录访问（浏览器式请求） | `302 → /feishu-auth/login?next=…`；`/api` 无 cookie 时是 `401` JSON |
-| 完整登录交接 | `GET /` → `303 /?token=…` → harness 下发 `dsh-auth-*` cookie → 再访问 `/` 得 `200` 且返回真实应用页 |
+| 完整登录交接 | `GET /` → harness 回 401 时给 **200 同站重进页**（自动跳回 `/`）→ 再访问 `/` 得 `200` 真实应用页；harness 不回 401 时走 `303 /?token=…` → 下发 `dsh-auth-*` → 再访问 `/` 得 `200` |
 | 停用验证 | 探针应从 `302`（网关在岗）变成 `401`（harness 自己的门）——这是确认层真的被摘掉的唯一可靠信号 |
 | `/feishu-auth/status` | `{"gate":"enforce","authenticated":…}` |
+| 设置页入口 | 打开设置面板：头部「关闭」左边出现「退出登录」；点击后落到「已退出登录」页，浏览器里本插件与 harness 的 Cookie 都清空 |
 
 ## 配置项的生效语义
 
@@ -89,7 +91,7 @@ feishu-auth[error] 拿不到 harness 的入口地址（connection 服务不可
 | 现象 | 处理 |
 | --- | --- |
 | 所有请求 503 | 凭证不在进程环境里：确认 `~/.dsh/.env` 后重启 |
-| 登录成功后停在 harness 的 401 页 | 网关没拿到 harness 入口地址（日志有 error 行）：检查 `ctx.inject(['connection'])` 是否仍被 dsh 支持 |
+| 页面打不开（0.1.3 之前会停在 harness 的 401 页） | 网关自己收尾：先给同站重进页、再换新凭据，两轮都不行才给「还差一步」页并打 warn。若日志里完全没有恢复行、只有 `[error]` 说拿不到入口地址 → 检查 `ctx.inject(['connection'])` 是否仍被 dsh 支持 |
 | 飞书报 `redirect_uri unmatch` | 回调地址没登记/不一致；临时隧道换域名后必须补登记 |
 | 飞书报 `20010` | 账号不在应用可用范围，或应用版本未发布 |
 | 想立刻放行 | `disable.patch.yml` 启动一次，或给该行加 `disabled: true` 后重启 |
@@ -101,7 +103,8 @@ feishu-auth[error] 拿不到 harness 的入口地址（connection 服务不可
 - **绝不用身份比较判断服务成员。** `ctx.webServer` 是 Cordis traceable 服务，成员读取每次都返回新的包装 Proxy：`server.match === 你的函数` 恒为 false。识别自己的层只能靠符号标记，解包靠 `Symbol.for('cordis.original')`。详见架构文档。
 - **挂载/卸载必须幂等。** 热重载时新层可能先于旧层的 disposer 挂上：只允许最新层卸载，发现遗留层要复用它的原始实现而不是往上叠。
 - **新增行为要补用例**，并确认「旧实现下该用例会红」——否则它没锁住任何东西。
-- **不改客户端资产、不注入 DOM**：拦截只发生在 HTTP 层。
+- **不注入 DOM、不改 harness 的客户端资产**：要出现在界面上只走 dsh 的插槽（`lib/client.js`，见架构文档「客户端半边」），不要往页面里塞元素。
+- **浏览器半边必须保持「注册工厂」形态**：`lib/client.js` 顶层只允许 `window.__ModuleLoader__.load({ id, factory })`；`require` 与一切副作用都必须进 factory，否则运行时直接抛。
 - **提示页只用内联样式**，不能依赖被自己保护的静态资源。
 - 配置解析永不抛错：除凭证外的问题降级为默认值并记录；凭证缺失走故障关闭。
 
@@ -116,13 +119,15 @@ feishu-auth[error] 拿不到 harness 的入口地址（connection 服务不可
 
 ## 与 dsh 版本的耦合点
 
-升级 dsh 后优先复核这四处，任何一处变了都要同步适配：
+升级 dsh 后优先复核这几处，任何一处变了都要同步适配：
 
 | 依赖 | 用途 | 失效表现 |
 | --- | --- | --- |
 | `webServer.match(pathname)` 分发点 | 唯一的拦截缝隙 | 插件**拒绝启动**并报错（不会静默放过） |
-| `ctx.inject(['connection'])` | 取 harness 入口地址（两段式交接） | 日志 error；登录后停在 harness 的 401 页 |
+| `ctx.inject(['connection'])` | 取 harness 入口地址（两段式交接） | 日志 error；只剩同站重进这一步可救，跨站链那类场景会落到「还差一步」页 |
 | `dsh-auth-<authority>` Cookie 前缀 | 登出时清掉 harness 自己的 Cookie | 登出后可能被 harness 直接放回 |
 | `/?token=<launch token>` 兑换约定 | 交接第二段 | 同上 |
+| `dsh.client` + `exports["./client"]` 契约 | 浏览器半边的发现与托管（`/plugins/??<id>/client.js`） | 设置页里没有「退出登录」入口，`/plugins/…` 404 |
+| 插槽名 `settings.action`（`ctx.slots`） | 入口在设置面板里的位置 | 入口不出现；需换槽名并核对 `settings.*` 插槽目录 |
 
 另见架构文档「已知边界与风险」。

package/README.md

@@ -64,6 +64,12 @@ dsh web --no-open --host 0.0.0.0 --port 3080 --trusted-host <你的隧道域名>
 
 `allowedUsers` 该填什么：被拒的人会在页面上看到**他自己**的 `open_id`，抄进去保存即可——配置项热生效，不用重启。
 
+## 退出登录
+
+**设置面板右上角有一个「退出登录」**（`关闭` 按钮左边）。它调 `/feishu-auth/logout`，会清掉本插件的会话 Cookie **和** harness 自己的 `dsh-auth-*`——后者是关键，只清前者的话 harness 会立刻把人放回去。
+
+标签页停在旧的 harness 报错页上时，按一次刷新即可恢复：网关会自己把浏览器接回来（同站重进 → 必要时换一份新凭据），**不需要重新登录**。
+
 ## 常见问题
 
 | 现象 | 处理 |

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 标记：
+
+| 值 | 含义 | 这一层的回答 |
+| --- | --- | --- |
+| 无 | 还没试过 | 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('/')` 即返回应用页。
 
-**交接标记**（`dsh-feishu-handoff`，20 秒）是死循环的兜底：浏览器拒绝存 harness Cookie 时，`/` 与 `/?token=…` 之间只会来回一次。
+作废旧凭据（harness 重启）走的是下一步：`/?token=…` 会重新签发一张能验过的 Cookie；这条链从同站重进之后出发，因此也在同站上下文里，新 Cookie 立刻可用。
 
-第 2 步的前提是「根请求带本进程的启动令牌」，所以 **harness 每次重启都会让浏览器里那份 `dsh-auth-*` 作废**。仅凭「Cookie 存不存在」判断交接会漏掉这种情况（旧 Cookie 还在，交接被压住，用户卡在 harness 的 401 页），因此交接判定同时看 harness 的回答：页面入口拿到 401 就再交接一次——老浏览器无需重新登录即可恢复。同理，交接后的 401 若再出现，交接标记会让它止步，把 harness 的 401 页作为终点而不是无尽往返。
+阶梯尽头（用户浏览器连续两次都不交出凭据，例如无痕窗口或拦截扩展）由插件自己的页面收尾并打 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,12 +121,21 @@ 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。
 
 被拒的账号会看到**他自己**的 `open_id`（便于运维填 `allowedUsers`），不泄露他人信息；所有插值经 `escapeHtml`。
 
+## 客户端半边
+
+设置面板里的「退出登录」入口由 `lib/client.js` 提供——插件唯一的浏览器侧代码，同时消费两个外部契约：
+
+- **dsh 的客户端插件机制**（`@deepseek-ai/dsh-client-modules`）：包在 `package.json` 里声明 `dsh.client`（`platform: web`、`immediately`），产物挂在 `exports["./client"]`。服务端扫描**所有**这样声明的包（不限于 `@deepseek-ai/*`），按模块图顺序合成 combo 脚本，浏览器侧由 `window.__ModuleLoader__` 惰性执行。产物必须是**注册工厂形态**：文件顶层只调用 `window.__ModuleLoader__.load({ id, factory })`，不得有任何副作用或 `require`（运行时会抛 `requested external … before the module system existed`）。本插件手写这个包装，所以仓库仍然零依赖、零构建。
+- **插槽 API**（`ctx.slots`）：`inject(name, …)` 等槽出现后再 `register`。用的是 `settings.action`——「content-column header, before Close」，`kind: list`、`replaceRisk: none`，因此我们的条目是**加**进去的，不替换任何既有 UI。`settings.action` 由设置面板条目在挂载时声明，所以必须先 `inject` 再注册。
+
+登出本身仍归服务端：入口只是一个指向 `/feishu-auth/logout` 的普通链接，由网关清掉自己的会话 Cookie **和** harness 的 `dsh-auth-*`——少了后者，harness 会当场上门把人放回去。
+
 ## 失败模式
 
 | 情形 | 行为 |
@@ -113,8 +143,11 @@ 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 页转给用户 |
+| 客户端 bundle 没被服务（`/plugins/…` 404） | 设置面板里当然也没有入口：核对 `package.json` 的 `dsh.client` + `exports["./client"]`、文件存在，以及件里注册的 `id` 与包名一致（运行时会对不上就抛） |
 | 启动自检失败 | `[error]` 明确报出：未登录请求未被拦，或持有效会话仍被拒 |
 | 配置项（`allowedUsers` / `sessionMaxAgeDays`）非法 | `allowedUsers` 非法 → 致命（避免悄悄放宽到全员）；`sessionMaxAgeDays` 非法 → 回落默认值 |
 

package/docs/release.md

@@ -19,11 +19,13 @@ npm 路径靠 `package.json` 的 `dsh.bundle.patch` 声明自己是组合包，`
 ```bash
 npm ci               # 只装 devDependencies（eslint）；运行时零依赖
 npm run lint
-npm test             # node --test，39 个用例
+npm test             # node --test，50 个用例
 npm run verify       # lint + test —— CI 与 prepublishOnly 跑的就是它
-npm pack --dry-run   # 检查发布产物内容（15 个文件）
+npm pack --dry-run   # 检查发布产物内容（16 个文件）
 ```
 
+`lib/client.js`（浏览器半边）是**手写**的 loader 包装，不是构建产物：文件顶层只允许 `window.__ModuleLoader__.load({ id, factory })`，任何顶层 `require` 或副作用都会被运行时拒绝。改动它的规范见 [docs/architecture.md 的「客户端半边」](architecture.md#客户端半边)。
+
 ## CI
 
 `.github/workflows/ci.yml`，在 push 到 `main`、PR、手动触发时跑：

package/lib/client.js

@@ -0,0 +1,103 @@
+/**
+ * Browser half of the gate: one「退出登录」entry in the settings panel.
+ *
+ * The server half owns `/feishu-auth/logout`, which clears this gate's session
+ * cookie AND the harness's own `dsh-auth-*`, so this half only has to put a link
+ * to it in front of the user.
+ *
+ * Two contracts come from dsh, and both are load-bearing:
+ *
+ * - The file is a **client bundle**: it registers a factory through
+ *   `window.__ModuleLoader__.load({ id, factory })` and does nothing else at the
+ *   top level. `@deepseek-ai/dsh-client-modules` serves it at
+ *   `/plugins/dsh-feishu-auth/client.js` (it discovers any package declaring
+ *   `dsh.client` plus `exports["./client"]`, not just `@deepseek-ai/*`), and the
+ *   runtime rejects a bundle that requests an external before the module system
+ *   exists. Hence: no top-level `require`, no top-level side effects.
+ * - The seat is the slot API's, not ours: `ctx.slots.inject(name, …)` waits for
+ *   the slot to exist — `settings.action` is declared by the settings panel
+ *   entry, so it only exists while that panel is mounted — and `register` adds
+ *   an entry beside the shipped ones (`id` of our own, so nothing is replaced).
+ *
+ * Styles stay inline: a client bundle may inject CSS from inside its factory
+ * closure, but one button does not justify a stylesheet.
+ * @module dsh-feishu-auth/client
+ */
+
+window.__ModuleLoader__.load({
+  id: 'dsh-feishu-auth',
+  factory: (require) => {
+    const module = { exports: {} };
+    const exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+    const React = require('react');
+
+    /** The seat: content-column header actions, rendered before the Close button. */
+    const SLOT = 'settings.action';
+    /** This entry's id inside that slot — ours, so the shipped entries stay. */
+    const ENTRY_ID = 'feishu-logout';
+    /** Where the server half signs this browser out. */
+    const LOGOUT_PATH = '/feishu-auth/logout';
+
+    /** Resting and hover looks, kept close to the shipped header actions. */
+    const REST = {
+      color: 'var(--dsw-alias-label-secondary, #6b6b70)',
+      background: 'transparent',
+    };
+    const HOVER = {
+      color: 'var(--dsw-alias-label-primary, #1d1d1f)',
+      background: 'var(--dsw-alias-fill-l2, rgba(127,127,127,.12))',
+    };
+
+    /**
+     * The entry itself: a plain link, so a middle-click or a reload-free
+     * navigation both reach the server half.
+     * @returns the anchor element.
+     */
+    function LogoutAction() {
+      const [state, setState] = React.useState(REST);
+      return React.createElement(
+        'a',
+        {
+          href: LOGOUT_PATH,
+          title: '清掉这台浏览器上的登录凭据',
+          style: {
+            ...state,
+            display: 'inline-flex',
+            alignItems: 'center',
+            height: '28px',
+            padding: '0 10px',
+            border: '0',
+            borderRadius: '8px',
+            font: 'inherit',
+            fontSize: '13px',
+            lineHeight: '18px',
+            textDecoration: 'none',
+            whiteSpace: 'nowrap',
+            cursor: 'pointer',
+            transition: 'color .12s, background .12s',
+          },
+          onMouseEnter: () => setState(HOVER),
+          onMouseLeave: () => setState(REST),
+        },
+        '退出登录',
+      );
+    }
+
+    const inject = ['slots'];
+
+    /**
+     * Register the entry, waiting for the settings panel to declare the slot.
+     * @param ctx - client plugin context.
+     */
+    function apply(ctx) {
+      ctx.slots.inject(SLOT, () =>
+        ctx.slots.register({ name: SLOT, id: ENTRY_ID, order: 100, label: '退出登录' }, LogoutAction),
+      );
+    }
+
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  },
+});

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.2.0",
   "description": "Feishu (Lark) OAuth login gate for the DeepSeek Harness web GUI.",
   "keywords": [
     "dsh",
@@ -18,6 +18,7 @@
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -40,6 +41,11 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [],
+      "platform": "web",
+      "immediately": true
     }
   },
   "scripts": {