前言¶

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