DSH Plugins Marketplace

DSH Plugins

Plugins

/

dsh-auth-cookie-hygiene

C

dsh-auth-cookie-hygiene

Discovered

DSH Local Authentication Cookie Hygiene Plugin: Sends expiration headers for `dsh-auth-*` cookies belonging to stopped Hosts, preventing cookie pileup and HTTP 431 caused by random ports.

Machine translated

dsh-auth-cookie-hygiene

给 DSH 本地认证 Cookie 做卫生的插件:在本地 HTTP 响应里追加过期 Set-Cookie,让浏览器自己删掉已经停止的 Host 留下的 dsh-auth-* Cookie。

A DSH bundle plugin that expires stale loopback auth cookies, so a random-port desktop Host cannot pile them up until Cookie headers hit the HTTP 431 limit.

不修改安装包,不读写浏览器 Cookies 数据库,不碰签名密钥,不关闭认证,不调大请求头上限。

背景

DSH Desktop 每次启动会监听一个随机的 127.0.0.1 端口,并为该 Host 下发一个与之对应的 dsh-auth-* Cookie。浏览器不按端口隔离 Cookie,所以每个新端口都会多留一个 Cookie,旧端口的却永远不过期。用过一段时间后 Cookie 请求头会不断变长,最终在 HTTP parser 阶段被拒绝(431 Request Header Fields Too Large),表现为本地页面认证失败。

这个插件是预防性缓解,不是官方根治:

  • 已经大到被 parser 拒绝的请求根本没进到应用层,插件看不到,必须先离线清一次 Cookie。
  • 只有在判定旧端口确实没人监听时才清理,所以端口复原/进程切换的 TOCTOU 窗口无法彻底消除。
  • 依赖当前版本的 webServer.server 接入点与 v1 Cookie 格式,不承诺跨大版本兼容。

清理与保留规则

只处理字面量 127.0.0.1:端口 的本地 HTTP 请求,且 Host 端口必须与实际监听端口一致。只有同时满足以下条件的 Cookie 才会被下发过期头:

  1. 名字是 dsh-auth-*,格式自洽,且名字里的 authority 与其 SHA256 前缀相符(只做自洽性筛选,不代表验证真实签名);
  2. 该 authority 的端口两次新鲜探测均为 ECONNREFUSED,且两次间隔不小于 confirmGapMs;
  3. 不是当前 Host,也不是任何正在监听的 Host。

始终保留:当前 Host、其他在监听 Host、v2/API Cookie、非 127.0.0.1 或 HTTPS 形态的 Cookie、畸形/超长/判定不确定的 Cookie。探测超时或其他错误一律按「未知」处理并保留。

过期头只在已认证的首页响应(显式 200/303、非流式)上合并发送;401/403、隐式发送、write/flushHeaders 流式响应会立刻原样放行。原有的 Set-Cookie、状态码、Location 和响应体都不变。

安装

插件是一个标准的 DSH bundle 包,零运行时依赖(只用 Node 内置模块,需要 Node ≥ 22.13)。

git clone https://github.com/CECILIALOVE0616/dsh-auth-cookie-hygiene.git
cd dsh-auth-cookie-hygiene
npm pack            # 产出 dsh-auth-cookie-hygiene-<version>.tgz

然后在 DSH 的 profile 目录(与 cordis.patch.yml 同级)里:

  1. 安装依赖:npm install <tgz 路径>
  2. 把同名 bundle 加进 profile 配置的 dsh.profile.bundles
  3. 包内 dsh.bundle.patch 指向 cordis.patch.yml,由它把 backend 插件插进配置树:
- insert:
    - id: dsh-auth-cookie-hygiene
      name: dsh-auth-cookie-hygiene
  1. 重启 DSH,先走一遍 welcome / account 流程确认登录正常。

安装前备份 profile 并退出 DSH;不要在运行中的 profile 上并发改依赖。卸载时移除 bundle 与依赖再重启,effect 会释放挂钩。

配置

全部可选,非法值回落默认值。写在与上面同一个 insert 条目的 config 下即可。

键默认范围说明
enabledtrue—关掉后只挂载不清理
maxPerResponse81–32单次响应最多下发多少个过期头
maxExtraHeaderBytes3072256–16384单次响应追加头的字节上限
maxCandidatesPerRequest641–256单次请求最多解析多少个候选 Cookie
confirmTimeoutMs700100–5000等待新鲜探测的总预算;到点放行
probeTimeoutMs25020–5000单次 TCP 探测超时
confirmGapMs1200–60000两次拒绝探测之间的最小间隔
closedTtlMs30000100–600000「已关闭」缓存时长
openTtlMs15000100–600000「在监听」缓存时长
retryBackoffMs200050–60000探测失联后的重试退避
maxPorts2561–4096端口状态表上限
maxRecent51216–4096近期已处理 Cookie 记录上限
recentTtlMs3000000–3600000近期记录保留时长
serverPollMs5010–5000未接入时的轮询间隔
serverIdlePollMs200010–60000已接入后的轮询间隔
serverDeadlineMs300000–300000等待 WebServer 出现的最长时间,0 表示不限
debugfalse—输出接入与配置日志

不建议放大限额或等待时间:真正的约束是浏览器端的请求头总大小,不是这里。

开发与测试

npm test               # node --test "test/*.test.js"
npm run test:sandboxed # 受限环境下关掉测试进程隔离(Node 24+ 支持)

共 50 项测试,覆盖冷请求、活跃 Host 保留、v2/畸形输入、原登录头合并、401 不变、流式响应、探测超时与卸载放行,以及「无预热、无人工等待,连续 12 次重建 Host 后浏览器 Cookie jar 依然只有当前与另一个活跃 Host」。用 Electron 内置 Node 24.21.0 与 Node 24.22.1 均通过。

如果测试环境不允许 node --test 派生子进程(某些沙箱里会 spawn EPERM),改用 npm run test:sandboxed,它把 runner 的进程隔离关掉,在单个进程里跑同一个 glob。

模块职责:

文件职责
lib/cookie.jsCookie 解析、authority/name 校验、过期头构造
lib/liveness.js仅 127.0.0.1 的 TCP 探测与两次拒绝确认
lib/hook.js请求/响应门控,只在认证首页响应上合并过期头
lib/index.jsCordis 生命周期、webServer.server 接入、配置归一化

已知限制

  • 不修复已经触发的 431,只做预防。堆积较多时先退出 DSH 离线清理一次。
  • 插件不读取 credentials 里的签名密钥,因此无法验证 Cookie 真实性,只做格式自洽 + 端口关闭筛选。
  • 端口在探测与删除之间重新启用时可能误过期一个刚启用的实例,需要重新打开登录链接。
  • 单次响应默认最多 8 条过期头,意味着首屏可能清不完大量历史 Cookie,多刷新几次即可。
  • 真实桌面 profile 的 Electron welcome/account 全流程、Chromium 持久 Cookie 库的长期表现、DSH 升级后的兼容性,均未做完整验收。

许可

MIT

Comments

Loading…

Similar plugins

dsh-cookie-sweep

by ALingStudio

DSH desktop plugin: sweeps leftover login-cookie files on every start so they cannot pile up past the 16KB request-header limit (HTTP 431 / "Web authentication failed").

Manifest valid

★ 0

MIT

JavaScript

Oct 31, 2026

dsh plugin --profile web add dsh-cookie-sweep

by kevindawn11-hash

Cap DSH desktop session cookie lifetime to avoid HTTP 431 / Web authentication failed startup crash. 修复 DSH 桌面端 dsh-auth-* cookie 累积导致的启动崩溃。

Security & AuditManifest valid

★ 2

MIT

JavaScript

Oct 31, 2026

dsh plugin --profile web add dsh-cookie-guard

by zhkkjF

Raises the DSH Desktop Host header budget to 128 KiB and prunes stale dsh-auth cookies only on the launch-token response that mints the replacement, so random-port launches cannot lock the desktop out with HTTP 431.

Security & AuditDevelopment & InfrastructureManifest valid

★ 1

MIT

JavaScript

Nov 7, 2026

dsh plugin --profile web add dsh-cookie-sentinel

by jitianjiyan

为本地监听器预留足够的请求头预算,并在启动后退休旧启动 cookie,避免桌面欢迎握手被 431 永久锁死。

Security & AuditManifest valid

★ 34

↓ 2.7k/wk

MIT

JavaScript

Oct 31, 2026

dsh plugin --profile web add dsh-auth-cookie-guard

by iasiv5

DSH 插件:(Web Profile 专用)自动跳过 BrowserAuth,访问 Web 地址即可直接使用,无需每次复制启动 URL 中的随机 Token 到浏览器。

Security & AuditManifest valid

★ 4

↓ 940/wk

MIT

JavaScript

Nov 4, 2026

dsh plugin --profile web add @iasiv5/dsh-skip-browser-auth

Keeps DeepSeek Harness desktop dsh-auth-* session cookies bounded by deleting stale ones during the token exchange performed on every launch, so random-port accumulation cannot reach the 16 KiB reques

Development & InfrastructureManifest valid

★ 0

dsh plugin --profile web add dsh-cookie-fix