Intégration ASP.NET Core

Une application ASP.NET Core dispose de deux points d’entrée NuGet. Choisissez selon les frontières que l’application hôte doit réellement maîtriser.

Pour un service autonome plutôt qu’un composant intégré dans un hôte .NET, utilisez l’image Docker officielle.

Intégrer le produit complet avec HsSqlAgent.Hosting

Installez le package complet :

dotnet add package HsSqlAgent.Hosting

Ajoutez puis activez l’hôte standard :

using HsSqlAgent.Hosting;

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

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

Cette composition et ce contrat de configuration sont les mêmes que ceux de l’hôte officiel ToolBox / Docker. Le binding des URL et la journalisation restent des responsabilités ASP.NET Core normales de l’hôte.

HsSqlAgent.Hosting inclut le runtime standard HsSqlAgent.Server ainsi que l’adaptateur officiel HsSqlAgent.Approvals.Webhook. Il n’ajoute aucun chargement dynamique de packages NuGet ou de DLL.

Choisir le fournisseur d’approbation DML

MCP Elicitation reste le mécanisme officiel par défaut :

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

Pour utiliser l’adaptateur Webhook générique officiel :

{
  "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"
    }
  }
}

Les variables d’environnement suivent la convention ASP.NET Core normale, par exemple DmlApproval__Provider=Webhook. Un nom de provider inconnu fait échouer le démarrage.

Pour un IDmlApprovalProvider personnalisé, utilisez HsSqlAgent.Server et enregistrez-le par injection de dépendances. Le système d’approbation ne reçoit jamais le droit d’exécuter du SQL arbitraire : HsSqlAgent conserve la validation, la liaison du fingerprint d’approbation, la revalidation de l’état courant et le commit final.

Construire une intégration sur mesure avec HsSqlAgent.Server

Installez le package modulaire :

dotnet add package HsSqlAgent.Server

Une application existante peut conserver son authentification et son autorisation tout en ajoutant uniquement les capacités HsSqlAgent dont elle a besoin :

var hs = builder.Services.AddHsSqlAgentCore();

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

Le pipeline ASP.NET Core reste sous le contrôle de l’hôte :

var app = builder.Build();

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

app.Run();

En mode autorisation déléguée à l’hôte, n’appelez pas AddHsSqlAgentBuiltInAuth(). HsSqlAgent utilise le HttpContext.User déjà authentifié, ne publie pas ses contrôleurs d’identité intégrés et n’installe pas son schéma d’identité.

Les canonical permissions comme /runtime/db-management.edit et /auth/role.view sont des identifiants stables de ressources d’autorisation, pas des routes. La policy de l’hôte peut les faire correspondre à son propre modèle de permissions.

Ajouter MCP uniquement si nécessaire

MCP reste une frontière de sécurité distincte pour l’accès machine :

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

Puis mappez-le après la construction de l’application :

app.UseHsSqlAgentMcp();

Les clés MCP, les périmètres d’outils et de tables, les limites de débit et la validation HMAC restent indépendants de l’autorisation humaine/administrative.

Utiliser l’identité intégrée uniquement si nécessaire

Si l’hôte veut le modèle JWT/member/role de HsSqlAgent, choisissez l’authentification intégrée plutôt que l’autorisation déléguée :

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

L’identité intégrée et l’autorisation déléguée à l’hôte sont mutuellement exclusives. Un hôte modulaire peut également ne pas monter l’interface d’administration intégrée.

Responsabilité des capacités

Une capacité non sélectionnée n’alloue ni ne valide ses options.

Surfaces HTTP actuelles

Le déplacement arbitraire de ces chemins n’est pas annoncé tant que le routage, les chemins/assets du frontend, les callbacks et les frontières de sécurité ne peuvent pas évoluer ensemble.

API de compatibilité

Les consommateurs existants peuvent continuer à utiliser AddHsSqlAgent() et UseHsSqlAgent(). Pour une nouvelle intégration, préférez l’entrée standard HsSqlAgent.Hosting ou AddHsSqlAgentCore() avec enregistrement explicite des capacités.

Documentation associée

• Déploiement
• Configuration
• DML sécurisé