连接授权插件 sperictao/dsh-client-connection-authz

dsh-client-connection-authz

DeepSeek Harness 内置 connection 的完整替代包（当前跟线 0.1.7-alpha.1）。它保留官方 HTTP、共享/独立 RPC、WebSocket 和浏览器 client 行为，并在所有远程入口前增加一个由外部插件提供的 ConnectionRequestAuthorizer。

设计

本包的 bundle patch 做两件事：

1. 用 id + name 双重匹配禁用内置 @deepseek-ai/dsh-client-connection；如果上游改名，patch 会显式告警而不会误伤复用该 id 的其它插件。
2. 插入 @dsh-external/dsh-client-connection-authz，并强制注入 connectionRequestAuthorizer。认证插件缺失或配置失败时，connection 不会以匿名模式降级启动。

浏览器 bundle 来自官方 @deepseek-ai/dsh-client-connection（跟随 package.json 声明的依赖范围），构建时只替换模块表 id；脚本校验唯一 id 出现次数防止静默漂移，不校验上游精确版本。Host 源码基于 DeepSeek Harness commit 47f943859bef60e4160492346772ded9b24f765a，来源见 NOTICE.md。

授权接口

interface ConnectionRequestAuthorizer {
authorize(facts: ConnectionRequestFacts):
| { allowed: true; principal: ConnectionPrincipal }
| { allowed: false; status: 401 | 403 }
}

facts 包含 transport、channel、endpoint、headers、TCP peer address，以及目标要求的 authority：

- trusted-host：普通 API、普通 RPC 和两个 WebSocket downlink。
- loopback：设置、凭据、宿主文件操作等特权 API；认证插件只有显式授予更高权限才能让远程调用通过。

特权判定分两级，src/index.ts 的 isPrivilegedEndpoint 是唯一判定点：

1. PRIVILEGED_ENDPOINTS：混合命名空间里的单个特权端点（settings/*、 session/openWorkspacePath 等与普通端点同处一个命名空间）。
2. PRIVILEGED_NAMESPACES：整个命名空间都不存在 use-authority 方法的，按前缀整体判特权（terminal、workspace、workspaceFiles、account、 officeToPdf、cordisHostRunner/dynamicCordisRunner）。

第二级的存在理由：上游给命名空间加方法不算破坏性变更——0.1.7 把 terminal 控制器从 1 个方法扩到 10 个（create/write/resize/close…，直接在本机以系统用户权限开真实 PTY）。只维护精确端点名的话，上游每一次这样的扩张都静默失败开放。
判定按前缀是 fail-closed：多列一个永不匹配的命名空间没有代价，漏一个就是远程任意命令执行。

执行顺序固定为：Host/Origin/DNS-rebinding fence → 本地回环判断 → 外部 authorizer → body 读取/协议升级/业务 handler。有效本地旁路必须同时满足回环 Host 和回环 TCP peer；远端仅伪造 Host: 127.0.0.1 仍会进入 authorizer。共享 RPC 会在授权前把 handler 与 authority 快照为同一 target，避免授权后切换 interceptor 的时序绕过。

浏览器侧不再用页面 hostname 预先否决 Host-authority 界面。替换 bundle 会让既有 connection.isLoopback 消费者尝试配置、凭据、宿主文件等特权 RPC；这不是授权结论，每个请求仍必须通过上述 Host fence 与外部 authorizer。没有 admin capability 的远程身份只能得到 403，拥有 admin capability 的身份才会到达业务 handler。

安装

这个包故意不能单独启用；profile 还必须安装一个提供 authorizer 的认证包。例如与 dsh-auth-tailscale 一起安装：

gh auth setup-git
dsh plugin --profile web add \
git+https://github.com/sperictao/dsh-client-connection-authz.git \
git+https://github.com/sperictao/dsh-auth-tailscale.git

两个仓库目前是 private；上面的已验证路径使用当前 gh 登录为 Git 配置 HTTPS 凭据。也可以改用已配置公钥的 SSH URL。

开发

pnpm install
pnpm check

测试覆盖 HTTP、共享/独立 RPC、WebSocket、特权 authority、回环 Host 伪造和既有 trust fence。pnpm build 生成并校验官方浏览器 bundle。

兼容范围

依赖声明（package.json 的 ^0.1.7-alpha.1 等）是本包与 dsh 版本兼容性的唯一事实来源：范围语义承诺该包在任何满足范围的 dsh 版本下工作。升级 dsh 到新线时，只有当上游 d.ts 出现 breaking change 或依赖范围不再覆盖新线时才需要改代码，此时 bump 本包版本并把依赖范围同步到新下限（如 ^0.1.6-alpha.1 → ^0.1.7-alpha.1）。不能用锁死确切版本的方式"防漂移"——那只会让 pnpm 在 profile 里解出版本裂缝（rc.6 插件 + rc.8 核心的 boot 崩溃就是这么来的）。
0.1.6 → 0.1.7 正是这条政策预期的情况：上游 Connection 改了契约（HostConnectionHandle 新增 operator 与 admit；ConnectionRpcHandler 多一个 peer 参数并改返回可携带二进制附件的 ConnectionRpcHandlerResult），host 半边因此有代码改动；浏览器半边仍是官方产物加两处字符串替换，构建脚本的唯一 id 与 loopback 权威锚点在 0.1.7 产物里仍各命中一次，故未动。