Intégration ASP.NET Core

Protection des secrets obligatoire

Avant de démarrer Docker ou d’enregistrer le runtime, configurez trois secrets Base64 indépendants de 32 octets aléatoires. Conservez les mêmes clés sur tous les nœuds et après les redémarrages. HMAC_KEY et JWT_KEY restent des secrets de signature distincts. Exécutez séparément trois fois openssl rand -base64 32.

Définissez SecretProtection:DatabasePasswords:ActiveKeyId sur db-1 et SecretProtection:DmlPayloads:ActiveKeyId sur dml-1. Une clé absente, invalide ou réutilisée empêche le démarrage. Les valeurs fictives des exemples sont volontairement invalides.

HsSqlAgent.Hosting lie automatiquement SecretProtection. Un hôte modulaire doit le faire explicitement :

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

Pour les nouvelles clés MCP d’amorçage, fournissez explicitement Bootstrap:Databases:*:McpKeys:*:Key. Le démarrage ne génère plus ces clés et ne les journalise plus. Les mots de passe DB chiffrés existants doivent être saisis à nouveau. Consultez le guide de mise à niveau avant de modifier un déploiement existant.

Plusieurs modules peuvent appeler AddHsSqlAgentCore() sur le même IServiceCollection. Chaque capacité n’accepte sa configuration qu’au premier enregistrement ; toute redéfinition ultérieure échoue. Les collections de services distinctes restent isolées.

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(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();

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é