ASP.NET Core 整合

必要的秘密保護設定

啟動 Docker 或註冊執行階段前，請設定三組獨立、隨機產生的 32-byte Base64 秘密。所有節點須使用相同金鑰，重新啟動後也須保留。HMAC_KEY 與 JWT_KEY 仍為獨立的簽署秘密。請分別執行三次 openssl rand -base64 32。

將 SecretProtection:DatabasePasswords:ActiveKeyId 設為 db-1，SecretProtection:DmlPayloads:ActiveKeyId 設為 dml-1。缺少、無效或重複使用的金鑰會使啟動失敗；範例佔位值刻意設為無效。

HsSqlAgent.Hosting 會自動繫結 SecretProtection；模組化主機須明確繫結：

hs.AddHsSqlAgentRuntime(options =>
{
    builder.Configuration.GetSection("SecretProtection").Bind(options.SecretProtection);
});

新 bootstrap MCP 金鑰須明確提供 Bootstrap:Databases:*:McpKeys:*:Key，啟動時不再產生或記錄金鑰。既有加密資料庫密碼須重新輸入。變更既有部署前，請閱讀升級指南。

多個模組可在相同的 IServiceCollection 上呼叫 AddHsSqlAgentCore()。各能力只接受首次註冊時的設定，後續覆寫會失敗；不同的服務集合仍彼此隔離。

ASP.NET Core 應用現在有兩個 NuGet 入口。請依「宿主要掌握哪些邊界」來選，而不是把兩個套件當成同一層級的替代名稱。

若要把 hs-sql-agent 當成獨立服務，而不是嵌入 .NET 宿主，直接使用官方 Docker 映像。

用 HsSqlAgent.Hosting 嵌入完整產品

安裝完整主機套件：

dotnet add package HsSqlAgent.Hosting

加入並啟用標準主機：

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();
await app.RunAsync();

這與官方 ToolBox / Docker 主機使用相同的第一方能力組合與設定契約。URL 綁定與日誌仍由一般 ASP.NET Core 宿主負責。

HsSqlAgent.Hosting 會帶入標準 HsSqlAgent.Server 執行環境與官方 HsSqlAgent.Approvals.Webhook adapter；它不會加入執行期 NuGet 或 DLL 外掛載入機制。

選擇 DML 核准提供者

MCP Elicitation 仍是預設的第一方核准方式：

{
  "DmlApproval": {
    "Provider": "McpElicitation"
  }
}

要使用官方通用 Webhook adapter：

{
  "DmlApproval": {
    "Provider": "Webhook",
    "Webhook": {
      "Endpoint": "https://approval.example.com/hssqlagent/requests",
      "CallbackUrl": "https://sql-agent.example.com/api/hs-sql-agent/approvals/webhook",
      "SigningSecret": "replace-with-a-unique-secret-at-least-32-bytes"
    }
  }
}

環境變數沿用 ASP.NET Core 一般命名，例如 DmlApproval__Provider=Webhook。未知的 provider 名稱會在啟動時直接失敗。

若需要自訂 IDmlApprovalProvider，請改用 HsSqlAgent.Server 並透過相依性注入註冊。核准系統不會取得任意執行 SQL 的權力：SQL 驗證、核准 fingerprint 綁定、現況重新驗證與最終 commit 仍由 HsSqlAgent 負責。

用 HsSqlAgent.Server 建立客製整合

安裝模組化套件：

dotnet add package HsSqlAgent.Server

既有應用可保留自己的驗證與授權，只加入需要的 HsSqlAgent 能力：

var hs = builder.Services.AddHsSqlAgentCore();

hs.AddHsSqlAgentRuntime(options =>
{
    builder.Configuration.GetSection("SecretProtection").Bind(options.SecretProtection);
});
hs.AddHsSqlAgentAdminStore(options =>
{
    options.Provider = "Postgres";
    options.ConnectionString =
        builder.Configuration.GetConnectionString("HsSqlAgent")!;
});
hs.AddHsSqlAgentHostAuthorization("SqlAgentAdmin");
hs.AddHsSqlAgentAdminApi();

ASP.NET Core 管線仍由宿主掌握：

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseHsSqlAgentAdminApi();
app.MapControllers();

app.Run();

使用宿主授權時不要呼叫 AddHsSqlAgentBuiltInAuth()。HsSqlAgent 直接使用已驗證的 HttpContext.User，不發布內建身分控制器，也不安裝 HsSqlAgent 身分結構。

/runtime/db-management.edit、/auth/role.view 這類 canonical permission 是穩定的授權資源識別碼，不是路由。宿主 policy 可以把它們映射到既有權限模型。

需要 MCP 時再加入

MCP 仍是獨立的機器存取安全邊界：

hs.AddHsSqlAgentMcp(options =>
{
    options.PublicEndpoint = "https://example.com/mcp";
    options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!; // >= 32 bytes
});

建立應用後再掛載：

app.UseHsSqlAgentMcp();

MCP 金鑰、工具範圍、資料表範圍、速率限制與 HMAC 驗證，都與人員/管理端授權 policy 分開。

真的需要時才使用內建身分系統

若宿主要使用 HsSqlAgent 自己的 JWT/member/role 模型，請選擇內建驗證，而不是宿主授權：

hs.AddHsSqlAgentBuiltInAuth(options =>
{
    options.Jwt.SecretKey = builder.Configuration["JWT_KEY"]!; // >= 32 bytes
});

內建身分與宿主授權互斥；模組化宿主也可以選擇不掛載內建管理介面。

能力與設定責任

未選擇的能力不會配置或驗證它的設定。

目前 HTTP 掛載位置

在路由、前端 base path/靜態資產、callback 與安全邊界能一起移動以前，不宣告支援任意搬移這些路徑。

舊版相容 API

既有套件使用者仍可繼續使用 AddHsSqlAgent() 與 UseHsSqlAgent()。新的整合應優先選擇標準 HsSqlAgent.Hosting 入口，或使用 AddHsSqlAgentCore() 再明確註冊能力。

延伸閱讀

• 部署
• 設定
• 安全 DML