ASP.NET Core 整合

HsSqlAgent.Server 是可以嵌入既有 ASP.NET Core host 的類別庫套件。hs-sql-agent 的新整合方式從不帶選項的核心註冊開始，只明確加入 host 真正需要的 capability。

安裝

dotnet add package HsSqlAgent.Server

既有應用程式沿用自己的登入與權限

如果 ASP.NET Core 應用程式本來就有 authentication / authorization，建議採用這種嵌入方式。

1. 保留 host 原本的 authentication / authorization

   builder.Services.AddAuthentication(/* 既有 schemes */);
   
   builder.Services.AddAuthorization(options =>
   {
       options.AddPolicy("SqlAgentAdmin", policy =>
       {
           policy.RequireAuthenticatedUser();
           // 若要檢查細粒度 hs-sql-agent canonical permissions，
           // 在這裡加入你自己的 requirement / handler。
       });
   });

   HsSqlAgent 不會替換 host 的 default authentication scheme、authorization policy provider 或 default authorization policy。

2. 只加入需要的 hs-sql-agent capabilities

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

   這個模式不要呼叫 AddHsSqlAgentBuiltInAuth()；HsSqlAgent 會直接使用 host 已完成驗證的 HttpContext.User。

3. ASP.NET Core pipeline 仍由 host 掌握

   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseAuthorization();
   
   app.UseHsSqlAgentAdminApi();
   app.MapControllers();
   
   app.Run();

   在模組化 host 模式下，UseHsSqlAgentAdminApi() 不會替應用程式呼叫 MapControllers()；controller endpoint 的 mapping 仍由 host 決定。

HostAuthorization 模式不會發布 HsSqlAgent 內建的 AuthController、MemberController、RoleController，也不會安裝 HsSqlAgent 身分資料表，因此不需要設定 JWT、SMTP、password reset 或 OIDC options。

HsSqlAgent 的管理端權限 filter 會把本次要求的穩定 canonical permission keys 放進 HsSqlAgentPermissionResource.Permissions，再交給指定的 host policy。Host 可以只使用粗粒度的管理角色，也可以把 canonical key 對映到自己既有的細粒度權限模型。

MCP 可獨立選用

MCP 是另一條機器端存取的安全邊界。只有應用程式確實要提供 MCP server 時才加入：

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

應用程式建置完成後再掛載：

app.UseHsSqlAgentMcp();

MCP 金鑰、工具範圍、資料表範圍、速率限制與 HMAC validation，都和管理者使用的 HostAuthorization policy 分開。

需要時才使用內建管理端身分系統

如果應用程式想使用 HsSqlAgent 自己的 JWT/member/role 模型，請明確選擇 BuiltInAuth，而不是 HostAuthorization：

var hs = builder.Services.AddHsSqlAgentCore();

hs.AddHsSqlAgentRuntime();

hs.AddHsSqlAgentAdminStore(options =>
{
    options.Provider = "Sqlite";
    options.ConnectionString = "Data Source=hsagent.db";
});

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

hs.AddHsSqlAgentAdminApi();

內建 authentication schemes 都使用 HsSqlAgent namespace（HsSqlAgent.Jwt、HsSqlAgent.ExternalCookie、HsSqlAgent.Oidc），不會成為 host 應用程式的 default scheme。BuiltInAuth 與 HostAuthorization 互斥。

隨套件提供的管理 UI 也不是必選：

app.UseHsSqlAgentAdminApi();
app.MapControllers();
app.UseHsSqlAgentAdminUi();

不掛載 UI 時，Admin API 仍可由 host 自己的前端呼叫。

各 capability 負責自己的 options

新程式只需要設定實際啟用 capability 所擁有的 options：

沒有選到的 capability 不會建立或驗證它的 options。模組化 API 保留原有預設值；選擇 HostAuthorization 不會要求設定 BuiltInAuth 的 JWT/OIDC/SMTP。

目前 HTTP 掛載路徑

hs-sql-agent 目前刻意固定這些掛載位置。在 routing、frontend base path/assets、callback 與安全邊界能一起搬移之前，不宣稱支援任意掛載路徑。

舊版相容介面

既有套件使用者仍可使用整合式 API：

builder.Services.AddHsSqlAgent(options =>
{
    // Existing aggregate configuration.
});

var app = builder.Build();
app.UseHsSqlAgent().ServeAdminUi();

HsSqlAgentServiceOptions、AddHsSqlAgent()、UseHsSqlAgent() 都會保留作為相容介面；新的整合應優先使用 AddHsSqlAgentCore()，再明確註冊需要的 capability。

相關文件