dsh-feishu-auth 0.1.0 → 0.1.2

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/README.md

@@ -48,7 +48,7 @@ dsh web --no-open --host 0.0.0.0 --port 3080 --trusted-host <你的隧道域名>
 
 装完后 profile 的 `dsh.profile.bundles` 会多一行，启动日志出现 `飞书登录已挂载` 和 `网关自检通过` 就绪。
 
-> npm 上还没有这个版本、或想跑本地源码？手工放一份仓库到 `~/.dsh/plugins/dsh-feishu-auth/`，再照 [AGENTS.md 的安装与激活](AGENTS.md#安装与激活) 在 profile 里插一行即可。tarball 离线安装也用 `dsh plugin ... add ./dsh-feishu-auth-0.1.0.tgz`。
+> 想跑本地源码（要改代码、或离线环境）？手工放一份仓库到 `~/.dsh/plugins/dsh-feishu-auth/`，再照 [AGENTS.md 的安装与激活](AGENTS.md#安装与激活) 在 profile 里插一行。tarball 离线安装用 `dsh plugin ... add ./dsh-feishu-auth-0.1.0.tgz`。
 
 权限（scope）不用申请，`open_id`、`union_id`、`tenant_key`、姓名直接可读。
 

package/docs/architecture.md

@@ -17,9 +17,13 @@ flowchart TB
     AU -->|"是"| HO{"需要 harness 交接?"}
     HO -->|"是"| EX["303 → /?token=…<br/>+ 20s 交接标记"]
     HO -->|"否"| PS["交给 harness 原分发逻辑"]
+    PS -->|"harness 回 401<br/>（旧 dsh-auth-* 已作废）"| EX
 ```
 
-「需要 harness 交接」的判定：`GET/HEAD` 导航请求、路径是 `/`、URL 上没有 `token` 参数、请求里没有 `dsh-auth-` 开头的 Cookie，且没有交接标记（见下）。
+「需要 harness 交接」有两条触发路径：
+
+1. **请求前判定**：`GET/HEAD` 导航请求、路径是 `/`、URL 上没有 `token` 参数、请求里没有 `dsh-auth-` 开头的 Cookie，且没有交接标记（见下）。
+2. **响应后判定**：判定 1 只能看到 `dsh-auth-*` **存不存在**，但 harness 只在「根请求携带本进程启动令牌」时签发它——harness 一重启，浏览器手里那份旧 Cookie 就作废了，而它的存在反而压住了交接，把用户送上 harness 那张没有出口的 401 页。所以页面入口的请求交给 harness 之后还要看它的回答：**回 401 就再交接一次**（同样受交接标记约束）。
 
 ## 拦截层
 
@@ -68,6 +72,8 @@ sequenceDiagram
 
 **交接标记**（`dsh-feishu-handoff`，20 秒）是死循环的兜底：浏览器拒绝存 harness Cookie 时，`/` 与 `/?token=…` 之间只会来回一次。
 
+第 2 步的前提是「根请求带本进程的启动令牌」，所以 **harness 每次重启都会让浏览器里那份 `dsh-auth-*` 作废**。仅凭「Cookie 存不存在」判断交接会漏掉这种情况（旧 Cookie 还在，交接被压住，用户卡在 harness 的 401 页），因此交接判定同时看 harness 的回答：页面入口拿到 401 就再交接一次——老浏览器无需重新登录即可恢复。同理，交接后的 401 若再出现，交接标记会让它止步，把 harness 的 401 页作为终点而不是无尽往返。
+
 ```mermaid
 sequenceDiagram
     participant B as 浏览器
@@ -108,6 +114,7 @@ sequenceDiagram
 | 会话密钥文件不可读写 | 同上（内存里用临时密钥，重启即失效） |
 | `webServer.match` 不存在 | 挂载抛错，插件拒启动——无保护状态不允许运行 |
 | `connection` 服务取不到 | 记 error，交接退化为放行给 harness 的 401 页 |
+| harness 重启后浏览器仍带旧 `dsh-auth-*` | 响应后判定接管：harness 回 401 → 自动再交接一次（用户无感）；已带交接标记时不再重试，401 页成为终点 |
 | 启动自检失败 | `[error]` 明确报出：未登录请求未被拦，或持有效会话仍被拒 |
 | 配置项（`allowedUsers` / `sessionMaxAgeDays`）非法 | `allowedUsers` 非法 → 致命（避免悄悄放宽到全员）；`sessionMaxAgeDays` 非法 → 回落默认值 |
 

package/docs/release.md

@@ -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>` 丢弃。
 
@@ -62,22 +62,24 @@ git push --follow-tags
 
 配成 stage-only 后，该 workflow 发起的 `npm publish` 会被 registry 拒绝，只有 `npm stage publish` 被接受。
 
-### 首次发布（只需一次，手工）
+### 首次发布（已完成：0.1.0 于 2026-09-13 手工发布）
+
+`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` 未被占用（2026-09-13 查 registry 返回 404）。首次发布前确认 npm 账号已开 2FA。
+包名 `dsh-feishu-auth` 已发布（`0.1.0`，2026-09-13；此前查官方 registry 为 404 即未占用）。此后发版一律走 staged 流程，账号需保持 2FA 开启。
 
 ## 依赖维护
 

package/lib/gate.js

@@ -177,6 +177,21 @@ export function createGate({ config, secret, fatalProblems = [], entryUrl, fetch
     return names.some((name) => name.startsWith('dsh-auth-')) !== true;
   }
 
+  /**
+   * Send the browser through the harness's launch-token exchange.
+   *
+   * The marker bounds retries: a browser that refuses to store the harness
+   * cookie would otherwise bounce between `/` and `/?token=…` forever.
+   */
+  function handoffToHarness(req, res, target) {
+    redirect(res, 303, target, {
+      'set-cookie': serializeCookie(HANDOFF_COOKIE, '1', {
+        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 +203,76 @@ 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*, 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.
+   *
+   * 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).
+   */
+  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 canHandOff =
+      entryTarget !== requested &&
+      cookieNames(req?.headers?.cookie).includes(HANDOFF_COOKIE) !== true;
+    if (canHandOff !== true) {
+      await target(req, res);
+      return;
+    }
+
+    // Swallow the auth wall before any of it reaches the socket, so the 303 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) handoffToHarness(req, res, entryTarget);
+  }
+
   /** Refuse an unauthenticated request: redirect browsers, 401 everything else. */
   function deny(req, res, url, principal) {
     if (mode === 'misconfigured') {
@@ -417,22 +502,23 @@ 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.
       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);
         return;
       }
     }
+    // A stale `dsh-auth-*` cookie keeps needsHarnessHandoff quiet, so the page
+    // entry point also 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/package.json

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