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 接口，並將插件與配套的認證包一起安裝。