ASP.NET Core 整合

HsSqlAgent.Server 是可嵌入既有 ASP.NET Core host 的 class-library package。2.0.2 的新整合方式從 optionless core 開始，只明確選擇 host 真正需要的 capability。

安裝

dotnet add package HsSqlAgent.Server

既有 application 沿用自己的登入與權限

若 ASP.NET Core application 本來就有 authentication / authorization，這是建議的 embedding 方式。

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 已完成 authentication 的 HttpContext.User。

3. ASP.NET Core pipeline 由 host 自己掌握

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

   Modular host 模式下，UseHsSqlAgentAdminApi() 不會替 application 呼叫 MapControllers()；controller endpoint mapping 仍由 host 決定。

Host-authorization mode 不會 publish HsSqlAgent 內建的 AuthController、MemberController、RoleController，也不會安裝 HsSqlAgent identity schema，因此不需要 JWT、SMTP、password-reset 或 OIDC options。

HsSqlAgent Admin permission filter 會把本次要求的 stable canonical permission keys 放在 HsSqlAgentPermissionResource.Permissions，再交給指定的 host policy。Host 可以只用粗粒度 Admin role，也可以把 canonical key 對映到自己既有的細粒度 permission model。

MCP 獨立選用

MCP 是另一條 machine-access security boundary。只有 application 真的要 expose MCP server 時才加入：

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

Application build 完後再掛載：

app.UseHsSqlAgentMcp();

MCP key、tool scope、table scope、rate limit 與 HMAC validation 都與 human/Admin 的 host-authorization policy 分開。

需要時才使用內建 Admin identity

若 application 想使用 HsSqlAgent 自己的 JWT/member/role model，請明確選擇 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();

Built-in authentication schemes 都使用 HsSqlAgent namespace（HsSqlAgent.Jwt、HsSqlAgent.ExternalCookie、HsSqlAgent.Oidc），不會成為 host application 的 default scheme。Built-in identity 與 host-authorization mode 互斥。

Packaged Admin UI 也不是必選：

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

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

Capability-owned options

新程式只設定該 capability 真正擁有的 options：

沒有選到的 capability 不會建立或驗證它的 options。Modular API 保留原有 defaults；選 HostAuthorization 不會逼你設定 BuiltInAuth 的 JWT/OIDC/SMTP。

目前 HTTP surface

2.0.2 目前刻意固定這些 mount。Routing、frontend base path/assets、callback 與 security boundary 尚未能一起 relocation 前，不宣稱支援 arbitrary mount。

Legacy compatibility

既有 package consumer 仍可使用 aggregate API：

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

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

HsSqlAgentServiceOptions、AddHsSqlAgent()、UseHsSqlAgent() 保留為 compatibility surface；新整合應優先使用 AddHsSqlAgentCore() 加上 explicit capability registration。

相關文件