DeepSeek Harness 客户端连接授权插件介绍

前言¶

DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在使用默认的客户端连接处理时，通常缺乏细粒度的外部请求授权能力，无法在远程入口处强制执行特定的访问控制策略。sperictao/dsh-client-connection-authz 插件旨在解决这个问题，它作为官方 dsh-client-connection 的替代品，在保留原有行为的基础上，增加了一层由外部认证包提供的 ConnectionRequestAuthorizer，确保只有满足特定条件的请求才能通过。

插件定位¶

这是一个为 DeepSeek Harness 客户端连接提供认证能力的替换包。它由 sperictao 维护，基于 MIT 许可证。插件在保留官方 HTTP、共享/独立 RPC、WebSocket 和浏览器 client 原有行为的基础上，通过注入授权逻辑来控制连接请求。

核心功能¶

行为保留：完全保留官方内置连接的 HTTP、RPC、WebSocket 和浏览器 client 行为。
授权拦截：在所有远程入口前增加 ConnectionRequestAuthorizer，由外部插件实现具体的授权逻辑。
禁用内置：通过双重匹配（id + name）机制禁用内置的 @deepseek-ai/dsh-client-connection，避免误伤其他复用该 id 的插件。
强制注入：强制注入 connectionRequestAuthorizer，不提供匿名模式降级。如果认证插件缺失或配置失败，连接将拒绝启动。
本地旁路防护：有效本地旁路必须同时满足回环 Host 和回环 TCP peer；仅伪造 Host: 127.0.0.1 仍会进入 authorizer。
浏览器安全：浏览器侧替换官方 bundle 并校验唯一 id，防止静默漂移。

安装与启用¶

此插件故意不能单独启用，必须与提供 ConnectionRequestAuthorizer 的认证包一起安装。

假设我们要与 dsh-auth-tailscale 认证包一起安装，命令如下：

# 使用 gh 登录凭据或已配置公钥的 SSH URL
dsh plugin --profile web add \
  git+https://github.com/sperictao/dsh-client-connection-authz.git \
  git+https://github.com/sperictao/dsh-auth-tailscale.git

授权接口说明¶

插件依赖外部实现 ConnectionRequestAuthorizer 接口，该接口定义如下：

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

facts 参数包含传输方式、channel、endpoint、headers、TCP peer address 以及目标要求的 authority。
* trusted-host：普通 API、普通 RPC 和两个 WebSocket downlink。
* loopback：设置、凭据、宿主文件操作等特权 API；认证插件只有显式授予更高权限才能让远程调用通过。

执行顺序固定为：Host/Origin/DNS-rebinding fence → 本地回环判断 → 外部 authorizer → body 读取/协议升级/业务 handler。

兼容性与注意事项¶

依赖范围：本包与 DeepSeek Harness 版本的兼容性仅以 package.json 中的依赖声明（依赖范围）为事实来源，例如 ^0.1.6-alpha.1。
私有仓库：提供认证功能的两个仓库目前为 private，安装时需确保已登录 GitHub 或配置了 SSH 密钥。
版本兼容：兼容 DeepSeek Harness 0.1.0-rc.x 及依赖范围 ^0.1.6-alpha.1。

总结¶

该插件为 DSH 客户端连接提供了可控的授权层，适合需要严格控制远程访问权限的场景。开发者需自行实现 ConnectionRequestAuthorizer 接口，并将插件与配套的认证包一起安装。