前言¶

DeepSeek Harness (DSH) 采用「一切皆插件」的设计理念。在使用 DSH 构建需要远程访问或 API 服务的场景时，接入身份鉴权是安全部署的关键。dsh-auth-tailscale 是一个适配器插件，它为 dsh-client-connection-authz 插件提供 connectionRequestAuthorizer 实现。该插件利用 Tailscale Serve 注入并防伪处理的身份信息，帮助开发者实现基于精确用户白名单、普通使用能力和管理能力的访问控制。

核心功能¶

本插件作为 Tailscale Serve 的认证层，主要实现以下能力：

1. 身份注入与防伪：处理 Tailscale-User-Login、Tailscale-User-Name 和 Tailscale-App-Capabilities 头，这些头由 Tailscale Serve 生成。
2. 精细权限控制：
   • 精确用户 allowlist：通过白名单限制具体登录账号。
   • 普通使用能力：通过 App Capability 限制普通 API/WS 访问。
   • 独立管理能力：通过 App Capability 限制对 loopback 特权接口的访问。
3. Fail-Closed 机制：当缺少身份信息、身份格式非法（如非法 RFC 2047 编码）、Capability JSON 无效或权限不足时，插件拒绝访问。

安装¶

安装前需确保当前 GitHub 登录凭据有权读取私有仓库。安装命令如下：

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

说明：两个仓库目前是私有的。上述命令使用 HTTPS 凭据，你也可以改用已配置公钥的 SSH URL。

配置¶

插件通过 bundle patch 从环境变量读取策略。建议同时使用 allowlist 和 capabilities 以构建多层防御：

示例配置：

export DSH_TAILSCALE_ALLOWED_LOGINS='alice@example.com,bob@example.com'
export DSH_TAILSCALE_USE_CAPABILITY='example.com/cap/dsh'
export DSH_TAILSCALE_ADMIN_CAPABILITY='example.com/cap/dsh-admin'

部署示例¶

为了确保身份头可信，必须配合 Tailscale Serve 使用，并限制 DSH 的监听地址。

1. 启动 DSH
将 DSH 绑定到回环地址，避免直接暴露：

dsh --profile web \
  --host 127.0.0.1 \
  --port 3080 \
  --trusted-host your-node.your-tailnet.ts.net

2. 配置 Tailscale Serve
Serve 负责终止 HTTPS、注入身份头并转发 capabilities：

tailscale serve --bg \
  --accept-app-caps=example.com/cap/dsh,example.com/cap/dsh-admin \
  3080

3. Tailscale Grants 配置
在 tailnet policy 中配置 App Capability：

{
  "grants": [
    {
      "src": ["group:dsh-users"],
      "dst": ["tag:dsh-host"],
      "app": {
        "example.com/cap/dsh": [{}]
      }
    },
    {
      "src": ["group:dsh-admins"],
      "dst": ["tag:dsh-host"],
      "app": {
        "example.com/cap/dsh": [{}],
        "example.com/cap/dsh-admin": [{}]
      }
    }
  ]
}

注意事项¶

• Fail-Closed 行为：未设置或解析为空的 allowlist 是合法配置，插件会拒绝全部远程登录（启动时会打一条 warn），不会退回匿名访问。
• 监听地址限制：dsh 必须绑定 127.0.0.1，不要绑定 0.0.0.0，也不要用公开的 Funnel 代替私有 Serve。
• Tagged Devices：插件要求 Tailscale-User-Login，因此 tagged-device-only 的调用会被拒绝。
• 大小写敏感：Login 匹配是精确的，不自动转小写。
• 编码格式：非 ASCII identity/capability header 只接受 UTF-8 RFC 2047 Q 编码；格式异常不回退原文。
• Capability 结构：顶层必须是 object，每个值必须是非空 object 数组；危险原型键会被拒绝。
• 本地伪造风险：同机其它进程仍可能伪造 localhost 请求头，这是本机进程信任边界，并非 Tailscale 能解决的远程边界问题。

兼容范围¶

本插件无 dsh 运行时依赖（仅依赖 cordis + schemastery + authz 插件的类型接口），与 dsh 版本解耦。其兼容性完全依赖于对 @dsh-external/dsh-client-connection-authz 的 peer 范围（^0.1.6-alpha.1-authz.1），需跟随 authz 插件版本滚动对齐。

结语¶

该插件通过 Tailscale Serve 提供了一套标准化的身份鉴权方案，适合需要在 DSH 中集成精细权限控制的场景。使用时需注意其 Fail-Closed 的安全策略以及本机进程信任边界。

• GitHub 仓库：sperictao/dsh-auth-tailscale
• 插件目录：SkillHub