設定リファレンス

必須のシークレット保護設定

Docker の起動またはランタイム登録の前に、互いに独立したランダムな 32 バイトの Base64 シークレットを 3 個設定してください。すべてのノードで同じキーを使い、再起動後も保持します。HMAC_KEY と JWT_KEY は別の署名シークレットです。openssl rand -base64 32 を個別に 3 回実行してください。

Docker 環境変数	ASP.NET Core 設定
`DB_ENCRYPTION_KEY`	`SecretProtection:DatabasePasswords:Keys:db-1`
`DML_ENCRYPTION_KEY`	`SecretProtection:DmlPayloads:Keys:dml-1`
`DML_FINGERPRINT_KEY`	`SecretProtection:DmlFingerprintKey`

SecretProtection:DatabasePasswords:ActiveKeyId を db-1、SecretProtection:DmlPayloads:ActiveKeyId を dml-1 に設定します。キーの欠落、不正な値、使い回しは起動エラーになります。サンプルのプレースホルダーは意図的に無効です。

HsSqlAgent.Hosting は SecretProtection を自動的にバインドします。モジュール構成のホストでは明示的にバインドします。

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

新規 bootstrap MCP キーには Bootstrap:Databases:*:McpKeys:*:Key を明示してください。起動時にキーを生成したりログに記録したりしません。既存の暗号化された DB パスワードは再入力が必要です。既存環境を変更する前にアップグレードガイドを確認してください。

資格情報の保存とキーローテーション

DB パスワードは AES-256-GCM で暗号化され、用途と信頼済みレコードの SecretBindingId に結び付けられます。永続化された実行ペイロードは RequestId に結び付きます。旧形式の復号フォールバックはありません。ICryptoService は呼び出し元のキーバイト列ではなく、コンテキスト文字列を受け取ります。

暗号化キーをローテーションする際は、新旧キーを異なる ID で全ノードに配布し、ActiveKeyId を切り替えてパスワードを再保存します。保留中または過去のペイロードを調査する間は旧 DML キーを保持してください。独立した fingerprint key はバージョン管理されません。変更前に承認を処理し終え、過去の witness 調査用に旧シークレットを保存します。

ExtraSettings で使用できるのは JSON の真偽値 Encrypt と TrustServerCertificate のみです。未知・重複フィールド、文字列、不正な JSON は拒否されます。接続テストとヘルスチェックはドライバー詳細を公開せず、汎用の DB_CONNECTION_FAILED を返します。

Doctor の security.secret-protection は秘密値を返さず、キー ID、Base64 形式、長さ、独立性を検証します。公開サンプルキーは Production 以外では警告、Production ではエラーです。非アクティブな保持キーも対象です。無効なプレースホルダーは全環境でエラーになり、Doctor の起動前に設定検証で停止する場合があります。

hs-sql-agent には 3 つの利用形態がありますが、セキュリティ境界は共通です。

方式	設定モデル
Docker / ToolBox	`.env.example` による完全な単独サービス設定
`HsSqlAgent.Hosting`	ASP.NET Core configuration を使う同じ標準第一方構成
`HsSqlAgent.Server`	Host が Capability ごとの Options を明示的に選択

DML 承認

第一方の既定 Provider は MCP Elicitation です。単独 Docker と HsSqlAgent.Hosting は、SQL 実行 primitive を変えずに公式の汎用 Webhook adapter へ切り替えられます。

環境変数	用途
`DML_APPROVAL_PROVIDER`	`McpElicitation` または `Webhook`
`DML_APPROVAL_WEBHOOK_ENDPOINT`	外部承認サービス endpoint
`DML_APPROVAL_WEBHOOK_CALLBACK_URL`	pending approval を完了する公開 callback URL
`DML_APPROVAL_WEBHOOK_SIGNING_SECRET`	Webhook signing secret、32 UTF-8 bytes 以上

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

未知の Provider 名は起動時に失敗します。非同期 Provider は Pending を返せます。Durable Resume には Admin Store が必要で、保護された Resume Intent と Approval Fingerprint を保存します。

モジュール式 HsSqlAgent.Server は HsSqlAgent.Approvals.Webhook または独自 IDmlApprovalProvider を登録できます。承認 Provider に Database Connection、Transaction、検証済み Plan、commit primitive は渡りません。

Application と Control Plane

単独サービス設定には Application Hosting、Admin Database、MCP HMAC/Public Endpoint、内蔵 Admin JWT、SMTP/Password Reset、OIDC/MFA、Bootstrap、Audit、Health、Delivery、Cache、Rate Limit、Policy Sync、Outbound Delivery Sync、SQL Concurrency、Prometheus、OTLP が含まれます。

HMAC_KEY と JWT_KEY は異なる 32 bytes 以上の secrets にしてください。保護された Identity State を使う場合は DATA_PROTECTION_KEY_PATH を永続化します。

単一 Instance と分散 Provider

単一 Instance は SQLite Admin Database と process-local Memory Provider を利用できます。複数 Instance では共有 Admin Database と、Cache、Rate Limiting、Security Policy Sync、Outbound Delivery Sync、SQL Concurrency の Redis-backed Provider を利用します。

Observability

Prometheus は PROMETHEUS_ENABLED、PROMETHEUS_HOST、PROMETHEUS_PORT の専用 Listener、OTLP は OTLP_ENDPOINT と OTEL_SERVICE_NAME で設定します。

Embedded .NET Host

HsSqlAgent.Hosting は完全な標準構成を所有します。HsSqlAgent.Server は AddHsSqlAgentCore() から始め、選択した Capability の Options だけ検証します。Host Authorization は内蔵 Identity を置き換えられ、DML 承認 Provider も独立して差し替えられます。

デプロイ、ASP.NET Core 統合、Safe DMLも参照してください。