会话续期 edisoncks/dsh-cookie-renew

dsh-cookie-renew

为 DSH web GUI 的浏览器会话 cookie 做滑动续期。

DSH 只在 GET / 的 ?token= 交换过程中签发一次 dsh-auth- cookie，带绝对过期时间（connection.cookieMaxAgeDays，默认 30 天）。之后没有任何机制刷新它，所以哪怕浏览器每天都访问，一旦这个绝对有效期走完，也得重新打开带 token 的启动 URL。

这个宿主插件让会话在 GUI 使用期间保持存活。它监听 Connection 的 connection/request 瀑布钩子——这个钩子包住每个通过准入的 /api HTTP 请求——当 cookie 的剩余寿命低于总寿命的某个比例时，重新跑一遍 DSH 自己的 token 交换，把新的 Set-Cookie 挂到当前响应上。

- 只有一个运行时依赖（@deepseek-ai/schemastery），仅宿主侧，Node >= 20。
- 从固定 tag 安装： dsh plugin --profile web add github:edisoncks/dsh-cookie-renew#v1.0.0 （见 安装）。
- 从不读取签名密钥，也从不自己签 cookie。
- 把 30 天的绝对凭证变成可续期的凭证（见 注意事项）。

工作原理

1. connection/request 在 /api 准入之后、响应写出之前触发。监听器始终调用 next()，所以 API 流量不受影响。
2. 插件找到 dsh-auth- cookie，其载荷里写着请求的规范化 authority（HTTP 下是 host:port，TLS 下是 https://host[:port]）。载荷只是调度提示——它的签名不被信任，也不做校验。载荷退化或已经过期的候选会被跳过，所以陈旧或被植入的值无法掩盖真正的 cookie。
3. 当 remaining <= lifetime * renewBelowFraction 且节流已过，它就签发一个替换：
- ctx.connection.authenticatedUrl() 暴露进程启动 token；
- ctx.connection.authorizeIndex() 针对合成的 { method: 'GET', url: '/?token=…', headers } 请求跑真正的交换；
- 捕获到的 Set-Cookie 写入真实响应。
4. 进程 token 从不持久化，cookie 在 DSH 重启后依然可用，因为签名密钥存在 $DSH_HOME/.credentials.yaml。

续期节奏

续期是事件驱动的，不是定时触发的：在越过阈值后的第一个 /api 请求上发生，前提是页面开着。

| 访问频率 | 默认 30 天寿命、0.5 阈值下的续期情况 |
| 每天 | 大约每 15 天一次；过期时间保持在 15 到 30 天之后。 |
| 每 20–29 天 | 每次访问续期一次。 |
| 一个长期闲置的标签页 | 闲置期间不续期；最后一次签发的过期时间仍然有效，所以闲置满整个寿命的标签页仍会丢失会话。 |

minIntervalMinutes 是防止签发风暴的下限，不是续期节奏。

安装

这个包是 DSH 的包束。它的 package.json 声明了 dsh.bundle.patch: ./cordis.patch.yml，该文件通过一行 insert: 挂载插件。
在配置档（dsh.profile.bundles）里选中这个包束，既会加载它，也会让它出现在侧边栏的 Plugins → Installed plugins 页面，并带一个开关。

从 GitHub 安装带标签的发布版本。dsh plugin 会把命令转发给配置档内的 pnpm，所以一条命令就能写入依赖并选中包束：

dsh plugin --profile web add github:edisoncks/dsh-cookie-renew#v1.0.0

要固定标签，不要固定分支：#main 会在下次安装时重新解析成该分支当时的内容，而 #v1.0.0 固定的是已发布的提交。pnpm 会自己安装这个包唯一的运行时依赖（@deepseek-ai/schemastery），所以不涉及本地 npm install。

这条命令是 ~/.dsh/profiles/web/package.json 里两处改动的简写：

"dependencies": {
"dsh-cookie-renew": "github:edisoncks/dsh-cookie-renew#v1.0.0"
},
"dsh": {
"profile": {
"bundles": ["…", "dsh-cookie-renew"]
}
}

如果配置档里已经列出这个依赖，只需选中包束：把 "dsh-cookie-renew" 加到 dsh.profile.bundles，或者在 Plugins → Installed plugins 下拨动它的开关。

package.json 没有 private 字段，也没有发布到任何注册表；git 标签就是分发渠道。

从本地检出安装

要在工作副本上开发，改用链接方式安装：

(cd "$HOME/codes/dsh-cookie-renew" && npm install)
dsh plugin --profile web add link:"$HOME/codes/dsh-cookie-renew"

link: 安装直接从检出目录解析：检出目录需要有自己的 node_modules，而且包的 files 列表和 engines.dsh 版本约束都不会生效。一个包只有一个依赖条目，所以切回来就是同样的 add，换成 github:…#vX.Y.Z 说明符，它会替换掉 link: 条目。

条目的默认配置随包束补丁一起发布。在配置档自己的 cordis.patch.yml 里按条目 id 覆盖它：

- id: dsh-cookie-renew
name: dsh-cookie-renew
config:
renewBelowFraction: 0.5
minIntervalMinutes: 60

不要把这段覆盖包在 insert: 里——insert: 会新增第二个条目，而旧的手工接线安装用的就是它。裸行针对的是已存在的 id；id 不存在的裸行会被静默跳过。

package.json 声明了 engines.dsh: ^0.2.1-rc.3，这是本插件验证过的 harness 版本线，所以 dsh plugin 在超出该范围的运行时上会拒绝安装，而不是等到续期时才失败。

重启 dsh web 来挂载插件。现有 cookie 保持有效；不需要 token URL。

cookie 的生命周期本身仍来自 connection 行的 cookieMaxAgeDays。每次成功续期都会从签发那一刻起，把过期时间重置为完整的生命周期。

配置

| 字段 | 默认值 | 含义 |
| renewBelowFraction | 0.5 | 剩余有效期降到总有效期的这个比例或以下时续期。取值 (0, 1]；1 表示每个节流窗口内的第一次请求就续期。 |
| minIntervalMinutes | 60 | 同一个 authority 在这个窗口内绝不重复签发。0 关闭节流；超过 365 天的值会被拒绝。 |
| debug | false | 每次续期成功都通过 ctx.logger('cookie-renew') 记录日志。 |

Host 用插件的严格 Schemastery schema 校验配置档：两个数值字段用数字，debug 用布尔值，renewBelowFraction 保持在 (0, 1]，minIntervalMinutes 保持在 0 到 365 天之间。类型错误或超出范围的值会在加载时校验失败，这条插件条目因此不会激活；由于该条目是可选的，DSH 其余部分照常运行，启动警告会指出是哪个字段。
minIntervalMinutes: 0 是有意关闭节流。

Host 的设置描述符也由同一套严格 schema 支撑，所以设置表单或配置编辑器写入超出范围的值会被拒绝，配置档保持原样。插件导出 volatile 的 Config，并向 Host 设置服务注册 auto: true。这是应用内表单的宿主侧：Host 暴露描述符，但本包不带浏览器端，所以当前 Web GUI 没有表单可渲染。能根据 autoGenerate 描述符构建页面的客户端可以消费它们，包括每个字段的描述和边界；在那之前，请在配置档补丁里改这些值。

验证

打开 Settings → Built-in plugins → Plugin list，展开 Global，搜索 cookie。卡片会显示 Cookie Renew、它的描述、条目 id dsh-cookie-renew、模块 dsh-cookie-renew，以及一个活跃的 fiber。

这张卡片和侧边栏 Plugins 行都从 icon.svg 取 cookie 图标。

侧边栏 Plugins → Installed plugins 页面也会列出它，因为该页面管理配置档 bundles，而本包现在声明了一个。它的开关对应 dsh.profile.bundles 里是否存在 dsh-cookie-renew；开关关闭时包仍保持安装，重新打开会重新挂载条目，无需重装。

想快速实测，设置 debug: true 和 renewBelowFraction: 0.999，重启，然后加载页面一次：控制台会记录一次续期，cookie 的 Expires 跳到完整有效期。之后把比例改回去。

显示元数据

locale/en.json 和 locale/zh.json 提供标题和描述：

{
"meta": {
"title": "Cookie Renew",
"description": "Renews the DSH web browser session cookie before it expires."
}
}

清单通过 Node 的 ESM 解析器解析 <package>/locale/en.json 和 <package>/package.json，所以 package.json 必须导出这两个子路径：

"exports": {
".": "./lib/index.js",
"./locale/.json": "./locale/.json",
"./package.json": "./package.json"
}
缺少这些导出，清单会静默回退到包名，描述为空。

图标

icon.svg 是插件图标：36×36（1:1）的咬痕饼干，带巧克力豆，扁平 SVG，含两个渐变，无外部引用。package.json 中声明为 "icon": "./icon.svg"。

清单读取图标时不执行插件代码：

- 声明的路径是相对路径，必须留在包目录内。
- 文件为 SVG、PNG、JPEG 或 WebP，最大 256 KiB。
- 保持正方形——UI 会在标题旁的正方形格子中渲染它。
- 声明的 icon 优先于导出的 <package>/icon 子路径，且文件必须列在 package.json 的 files 中才会随包发布。

包结构

| 路径 | 作用 |
| cordis.patch.yml | 包补丁：insert 默认配置的 dsh-cookie-renew 条目。加载器为包组合的就是这一层。 |
| lib/index.js | 宿主插件：name、inject: ['connection']、Config（易变 schema）、apply(ctx, config)，以及供测试使用的导出辅助函数。 |
| icon.svg | 正方形（36×36）插件图标，通过 package.json 的 icon 字段声明，清单以 data URL 形式内嵌。 |
| locale/en.json、locale/zh.json | 清单标题与描述。 |
| test/index.test.js | 阈值、节流、authority/v2 过滤、候选过滤、配置 schema（严格边界）与实时引用、诊断、失败处理、签发测试。 |
| package.json | ESM 包，dsh.bundle.patch 指向包补丁，icon 指向图标，一个依赖（@deepseek-ai/schemastery），engines.node >= 20，engines.dsh ^0.2.1-rc.3。 |
| LICENSE | MIT 许可证文本。 |
| CHANGELOG.md | 发布说明，每个 tag 一节。 |
| package-lock.json | 供 CI 的 npm ci 使用的锁文件；作为依赖被消费时忽略。 |
| .github/workflows/ci.yml | CI：在 Node 20/22/24 上跑 npm ci 和 npm test，外加打包文件列表检查。 |

测试

node --test test/*.test.js

测试套件只用 node:test，无需额外工具。CI 在 Node 20、22、24 上按锁文件运行，然后检查 npm pack 是否仍只打包预期文件。

发布

发布是 main 上名为 vX.Y.Z 的附注 git tag，CHANGELOG.md 记录变更。安装时应固定 tag（github:edisoncks/dsh-cookie-renew#v1.0.0），这样升级就是显式修改该 tag，而不是分支静默移动。

要发一版：改 package.json 的 version，在 CHANGELOG.md 加对应标题，提交，然后：

git tag -a v1.0.0 -m v1.0.0
git push --follow-tags

注意事项

- 仅在有效期内。 准入在钩子运行前就拒绝过期 cookie，所以会话过期后仍需打印出的 ?token= URL。这是保活，不是重新登录。
- 仅 /api HTTP 请求。 WebSocket 帧、静态资源和首页不会触发签发。每次页面加载都会发起 API 调用，所以正常使用
- 已覆盖。
- 绑定 0.2.1 系列。 钩子和两个 Connection 方法是公开的，包括合成的请求/响应结构；但 cookie 前缀、v1 载荷结构、authority 拼写、303 状态码和小写的 set-cookie 键都是内部实现。engines.dsh 锁定已验证的系列，遇到未知载荷版本只记录一次日志，不会静默停止。
- cookie 一旦被盗，就能无限续期。 让 GUI 只监听回环地址，或用 trustedHosts 和 TLS 限制暴露范围。
- 按 authority 区分。 浏览器发送 cookie 时忽略端口；DSH 则把这个 cookie 的名称和载荷绑定到请求的 authority（HTTP 下是 host:port，TLS 下是 https://host[:port]）。因此把 GUI 换到另一个端口后，需要重新换取 token。

卸载

先关掉插件，再移除——管理器会同时删掉 bundle 选择和配置档依赖：

dsh plugin --profile web remove dsh-cookie-renew

重启 dsh web。已有 cookie 在过期前仍然有效。如果你是在旧布局上手动安装的，还要从 ~/.dsh/profiles/web/cordis.patch.yml 里删掉残留的 - insert: 块，否则下次模块解析时这个条目会回来。

故障排查

- 在文件沙箱里安装时报 ERR_PNPM_STORE_DIR_OPEN_OPERATION_LOCK / 只读文件系统：pnpm 12 把存储操作锁放在 $XDG_RUNTIME_DIR 下，那里可能是只读的。改用 env -u XDG_RUNTIME_DIR dsh plugin … 重试。
- 没有续期：cookie 必须已经低于阈值。调低 renewBelowFraction，或启用 debug。
- 设置表单写入被拒：schema 是严格的；值超出范围或类型不对。配置档不变，插件继续运行。
- 手动改配置后插件条目报错：严格 schema 会拒绝错误类型和超出范围的值。在配置档补丁里修正该字段（设置 → 通用 → 打开配置文件），然后重启 dsh web；在此之前 DSH 其余部分照常运行，续期关闭。
- unsupported payload version 警告：DSH 改了 cookie 载荷格式。更新插件及其 engines.dsh 锁定；在此之前插件停止续期（不动现有 cookie）。
- could not mint ... status N：token 交换返回了意外状态（或没有 Set-Cookie）。通常意味着 harness 有变动；检查锁定。
- 挂载时报 Connection does not expose ...：harness 不再匹配锁定的范围。插件会自行禁用，而不是让每个请求都失败。
- 侧边栏 Plugins 页面里找不到插件：那个页面列出的是 bundle，所以检查 dsh.profile.bundles 里的 "dsh-cookie-renew"，以及 package.json 是否仍声明 dsh.bundle.patch。选了 bundle 却没有 bundle 补丁时，会以 not-bundle 问题显示。
- 启动时挂载该行：改动 bundle 选择或补丁后，重启 dsh web。

许可证

MIT © 2026 Edison Chong。