dsh-auth-proxy

dsh-auth-proxy

DSH Web GUI 的令牌鉴权反向代理插件：在 dsh web 前面加一道静态令牌登录墙。宿主侧在 127.0.0.1:<port>（默认 8443）监听，未认证访问显示内置登录页，校验令牌后签发 HttpOnly 会话 cookie，再把 HTTP 与 WebSocket 流量转发给回环 dsh webserver。零 DSH 源码改动： webserver 保持监听 127.0.0.1:3080，本插件持有对外 socket。

browser ──► auth proxy :8443 (127.0.0.1) ──► dsh webserver 127.0.0.1:3080
                ├─ 未认证 → 内置登录页
                ├─ POST 令牌 → HttpOnly 会话 cookie
                └─ 已认证 → 转发 HTTP + WebSocket

功能

• 内置登录页（POST /__dsh_auth/login 校验令牌），登出走 POST /__dsh_auth/logout。
• 令牌比对使用 SHA-256 + timingSafeEqual，避免时序侧信道。
• 会话 cookie：HttpOnly; SameSite=Lax; Path=/，永久有效（Max-Age 10 年）且无状态： 值为 payload.signature（HMAC-SHA256，密钥由令牌派生），服务端不存会话，重启后 cookie 依然有效； 更换令牌会使所有已登录会话立即失效（全体下线），登出仅清除客户端 cookie。
• IP 白名单（支持 CIDR，IPv4）可整体绕过令牌；失败登录锁定（按 IP，阈值与时长可配）。
• 配置实时可改：设置页注册成一个独立的 settings.section 分区（与 Models/General 同级， 非插件列表内的折叠卡片），经 ctx.settingsScope 读写 dsh-auth-proxy 命名空间——收 revision 栅栏、 由 Host 的 settings validate 校验并持久化，非自建 HTTP 写接口；对纯 HTTP 局域网地址自动注入 crypto.randomUUID polyfill，保证前端 RPC 可用。
• 局域网地址可正常编辑 web-ui 设置（主题、语言、插件配置等）：dsh web 客户端按页面源判定回环， 非回环来源会把设置面降级为只读；代理转发 HTML 时注入 loopback-compat 脚本，把 connection.isLoopback 打开——与代理把 Host/Origin 改回回环后服务端按回环放行的事实一致， 鉴权仍由本插件令牌墙把关。
• 状态可视：宿主终端直接打印 dsh-auth-proxy: listening on http://<host>:<port>（console.log 镜像， dsh web 不把插件 ctx.logger 打到终端），设置卡片同样显示实际监听地址；通过 accessUrls 声明的 入口地址（可含 HTTPS 域名）会展示在卡片与登录页，多域名场景一眼可知该用哪个 URL。
• 品牌层（proxy 前置重写）：brand.enabled 开启后，转发页改标题（含 document.title 拦截）、 换 favicon（内联 SVG 或本机 SVG 文件）、改写 PWA manifest（name/short_name/icons）、可选注入 Copilot 侧边栏/英雄区视觉（brand.logo，包裹官方 brand 图像 —— 无需新增 client 包）。所有重写都 发生在代理 forward 路径，内网直连 127.0.0.1:3080 完全不受影响；关闭开关则零干预。
• web-all remote-web-ui 兼容（/remote 前缀还原）：web-all 0.3.13 起 dsh-remote-web-ui 的 client 端嵌在 web-all/client.js 聚合包内无法摘除，在非回环来源页面（即经本代理访问）会把 /api/*、/sidebar/*、/git/*、/pet/* 改写为 /remote/api/*；该插件 host 半通常保持禁用（配对 vs 令牌验证），/remote 镜像路由不存在，改写后的请求上游即 405（设置/模型选择/workspace 会话全挂）。代理在转发 HTTP 与 WebSocket upgrade 时剥离 /remote 门控前缀、还原原始路径，让 RPC/流式接口可达；非 /remote 门控的请求原样透传。
• 移动端设置面板适配（≤768px 两步式交互）：web-all 设置对话框在窄屏仍用固定 188px 左导航列，内容区被挤到 ~132px。代理注入纯表现层 CSS+JS：打开设置时先展示完整左侧导航（188px 带文字标签、内容隐藏），点选分区后导航自动收成 44px 图标 rail、内容区展开占满；左下角浮动 ≡ 按钮随时展开/收起导航。选择器按结构匹配（[role="dialog"][data-dsh-surface] > nav、[class*="nav*"]）而非 css-module hash 类名，web-all 升级 rehash 不破坏。
• 移动端设置对话框 transform 包含块中和：web-all 移动端响应式层给侧边栏抽屉设 transform: translateX(0)（展开动画用），即便恒等矩阵也创建包含块——嵌套其内的 position:fixed 设置对话框退化为抽屉定位（inset:0 只盖 320px 而非全视口）。设置对话框打开时经 :has() 中和该 transform（[data-pane="sidebar"]:has([role="dialog"][data-dsh-surface]) { transform: none }），overlay 恢复全视口、面板达到 calc(100vw - 48px)（内容区 276→298px）。该选择器仅在设置对话框存在时命中，会话列表抽屉展开动画不受影响。
• 无 TLS，禁绑通配/公网：监听地址仅允许回环与内网（默认 127.0.0.1）；0.0.0.0、:: 与公网 IP 在保存与启动时都会被拒绝。外部访问请在前面挂 TLS 反向代理，回指本监听地址。

安装与卸载

dsh plugin 把参数转发给 pnpm，在 profile 目录安装依赖，并按 dsh.bundle 声明自动把插件 挂进 web profile roster（即 cordis.patch.yml 的 auth-proxy 行），无需额外激活步骤。

安装（npm 发布版与 GitHub 直装二选一）：

# npm 发布版
dsh plugin --profile web add @wxyzh/dsh-auth-proxy

# 或 GitHub 直装（固定 tag 版本）
dsh plugin --profile web add github:wxyzh/dsh-auth-proxy#v0.1.0

本地开发用 link 方式（无需发布，直接挂源码目录）：

dsh plugin --profile web add link:<abs 路径>/dsh-auth-proxy

卸载（无论以哪种方式安装，都用包名）：

dsh plugin --profile web remove @wxyzh/dsh-auth-proxy

说明：dsh plugin 需要 pnpm 在 PATH 上；GitHub 直装时若 pnpm 拦截 prepare 构建脚本， 按 CLI 提示在 profile 的 pnpm-workspace.yaml 添加 allowBuilds 键后重试。本插件是宿主 + 浏览器双半插件：宿主侧 src/index.ts，浏览器侧 src/client/（设置卡片）。

配置

组合入口配置（cordis.patch.yml）：

令牌：推荐用环境变量引用，不要把字面量写进配置：

token: !!js process.env.DSH_AUTH_TOKEN

安全默认：令牌为空或仍是占位符 change-me 时，代理保持禁用、绝不监听——只有配了真实令牌才会开放端口。

配置分层（改动前先读 AGENTS.md）：dsh-settings scope 是唯一写入路径——Host 用 installSettingsSection 注册 dsh-auth-proxy 命名空间（base = 组合入口，用户文档层由部署的 settings provider（如 dsh-settings-file）持久化，无 settings 服务时退化为组合入口）；设置分区经 ctx.settingsScope 读写，revision 栅栏 + Host validate 把关，监听 host 策略在 validate 钩子拒绝。 不存在自建的卡片配置文件（旧的 ~/.dsh/dsh-auth-proxy.json 权威已废弃）。令牌占位符是合法存储值， 代理保持禁用。运行态只读探测走 GET /api/dsh-auth-proxy/status（listening / tokenSet / accessUrls）， 永不回传令牌值，只回 tokenSet 布尔。

安全说明

• 代理即网络边缘：不信任 X-Forwarded-For（客户端可伪造，信任即白名单/锁定绕过）， 转发前剥离 x-forwarded-for / x-real-ip。
• 监听地址策略：无 TLS 意味着绑到通配（0.0.0.0/::）或公网 IP 会把明文令牌暴露到网络， 因此默认 127.0.0.1，且仅接受回环与内网地址（127/8、10/8、172.16/12、192.168/16、169.254/16、 ::1）；保存时由 settings validate 钩子拒绝、启动时由 sync() 拒绝，双重把关，日志与卡片会给出原因。外部访问请用 TLS 反向代理 （nginx/Caddy 等）终止加密后回指 127.0.0.1:8443，accessUrls 里填对外域名。
• 无 TLS：即使仅内网监听，令牌仍经明文 HTTP 传输，同网段可嗅探。这是为局域网 HTTP 可用性做的取舍； 需要加密传输时请在前方套 TLS 终结。
• 会话为无状态签名 cookie（HMAC 密钥派生自令牌，重启不失效）；无单点剔除能力——更换令牌即全体下线， 登出仅清客户端 cookie；失败计数由定时清理兜底（每 30 分钟扫描，闲置超 1 小时的记录清除）。锁定为按 IP，IPv6 字面量（如 ::1）不匹配 IPv4 白名单。

开发

• 构建：npm run build（tsc 出宿主侧 lib/types/ + tsdown 出浏览器侧 lib/client.js）。
• 本机坑（junction 开发副本）：npm run build / pnpm run build 会触发 prepare 里的 pnpm install，reify 跟随 node_modules/@deepseek-ai junction 可能破坏全局 dsh 内核。只改宿主侧（src/index.ts）时用 tsc -p <临时 host-only tsconfig>（include 仅 src/index.ts、exclude src/client）输出到 lib/types/，不要跑 npm run build；详见 AGENTS.md。
• 类型检查：npm run typecheck。
• 冒烟测试：npm run smoke（驱动构建产物，覆盖空/占位令牌不监听、登录流程、XFF 伪造不绕过白名单、 热更新不重建、改端口重建、占位令牌禁用、拒绝公网监听地址、HTML 双脚本注入、无状态会话重启存活与换令牌全体下线）。
• 仓库规则与安全不变式见 AGENTS.md；许可见 LICENSE（MIT）。

已知限制

• 会话永久有效且无状态（签名 cookie，重启不失效）；无单点剔除，改令牌即全体下线、登出仅清 cookie，属预期；失败计数表由定时清理兜底。
• 移动端适配耦合 web-all 结构：设置面板折叠/宽度优化依赖 web-all 当前的 DOM/CSS 结构（已尽量用结构选择器抗 css-module rehash，但 web-all 语义级重构仍可能失效）；注入的选择器未来若不再匹配，需按新版结构复查。
• /remote 前缀剥离是通用的前缀还原：转发层对所有以 /remote 开头的路径做剥离（当前仅 web-all remote-web-ui client 会生成此类路径）；若未来有其他插件主动使用 /remote/* 路径，会被一并还原，需要留意。
• 当前目录已是 git 仓库（初始提交已建）。