Référence de configuration

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.

Stockage des identifiants et rotation des clés

Les mots de passe DB utilisent AES-256-GCM, lié à la finalité et au SecretBindingId de l’enregistrement de confiance. Les charges d’exécution persistantes sont liées au RequestId. Aucun déchiffrement de secours de l’ancien format n’est disponible. ICryptoService reçoit une chaîne de contexte plutôt que des octets de clé fournis par l’appelant.

Pour renouveler un trousseau, distribuez les anciennes et nouvelles clés sous des ID distincts à tous les nœuds, changez ActiveKeyId, puis enregistrez les mots de passe à nouveau. Gardez les anciennes clés DML tant que des charges en attente ou historiques doivent être inspectées. La clé d’empreinte indépendante n’est pas versionnée : terminez les approbations avant de la changer et conservez les anciens secrets pour l’inspection des témoins historiques.

ExtraSettings accepte uniquement les booléens JSON Encrypt et TrustServerCertificate. Les champs inconnus ou dupliqués, les chaînes et le JSON invalide sont refusés. Tests de connexion et sondes de santé renvoient un message générique DB_CONNECTION_FAILED sans détails du pilote.

Le contrôle Doctor security.secret-protection valide les ID, le Base64, la longueur et l’indépendance sans renvoyer les secrets. Les clés d’exemple publiques produisent un avertissement hors Production et une erreur en Production, y compris sous des ID inactifs conservés. Les valeurs fictives invalides sont des erreurs partout ; une configuration invalide peut bloquer le démarrage avant que Doctor soit disponible.

hs-sql-agent propose trois modes d’utilisation avec la même frontière de sécurité.

Approbation DML

MCP Elicitation est le Provider officiel par défaut. Docker autonome et HsSqlAgent.Hosting peuvent sélectionner l’adapter Webhook officiel sans modifier la primitive d’exécution SQL.

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

Un nom de Provider inconnu fait échouer le démarrage. Un Provider asynchrone peut retourner Pending ; le Durable Resume exige l’Admin Store afin de conserver le Resume Intent protégé et les Approval Fingerprints.

Un Host HsSqlAgent.Server modulaire peut enregistrer HsSqlAgent.Approvals.Webhook ou son propre IDmlApprovalProvider. Le Provider ne reçoit ni Database Connection, ni Transaction, ni Plan validé, ni primitive de commit.

Application et Control Plane

La configuration autonome couvre Application Hosting, Admin Database, MCP HMAC/Public Endpoint, JWT Admin intégré, SMTP/Password Reset, OIDC/MFA, Bootstrap, Audit, Health, Delivery, Cache, Rate Limit, Policy Sync, Outbound Delivery Sync, SQL Concurrency, Prometheus et OTLP.

HMAC_KEY et JWT_KEY doivent être deux secrets distincts d’au moins 32 bytes. Persistez DATA_PROTECTION_KEY_PATH lorsque l’Identity State protégé est utilisé.

Instance unique et Providers distribués

Une instance unique peut utiliser SQLite pour l’Admin Database et des Providers Memory locaux. Plusieurs Instances doivent utiliser une Admin Database partagée et les Providers Redis-backed pour Cache, Rate Limiting, Security Policy Sync, Outbound Delivery Sync et SQL Concurrency.

Observability

Prometheus utilise un Listener séparé configuré par PROMETHEUS_ENABLED, PROMETHEUS_HOST, PROMETHEUS_PORT. OTLP utilise OTLP_ENDPOINT et OTEL_SERVICE_NAME.

Host .NET intégré

HsSqlAgent.Hosting possède la composition standard complète. HsSqlAgent.Server part de AddHsSqlAgentCore() et ne valide que les Options des Capabilities sélectionnées. Host Authorization peut remplacer l’Identity intégrée, et le Provider d’approbation DML peut être remplacé indépendamment.

Voir Déploiement, Intégration ASP.NET Core et Safe DML.