本 API はすべての呼び出しが直接的な金銭的影響を持ち、機微なサーバー認証情報にアクセスし得るという前提で設計されています。したがってセキュリティ要件は REST デフォルトをはるかに上回ります。
実装済みのセキュリティ管理策
- HMAC-SHA256: すべてのリクエストはメソッド、パス、タイムスタンプ、ノンス、ボディハッシュにわたって HMAC-SHA256 で署名されます。検証は定数時間（hash_equals）で行われます。
- AES-256-GCM: シークレットは AES-256-GCM 暗号化のみで永続化されます（libsodium 使用）。マスターキーはデータベースの外部 /etc/kh-reseller-api/master.key.v{N} に保管されます。
- Replay protection: タイムスタンプ許容範囲 +-300 秒、ノンスキャッシュ 600 秒。正しく署名されたリクエストは再送できません。
- Scope-based authorization: キーごとの明示的なスコープリスト。書き込みおよび機微なスコープは明示的に有効化する必要があります。
- IP whitelist (optional): キーごとに任意の IP 許可リスト（CIDR 記法、IPv4 および IPv6 対応）。
- Rate limit: 多層構造：キーごと（分単位＋日単位）および IP ごと（分単位）。バースト許容付きのトークンバケット方式です。
- Idempotency: 発注および破壊的なサービスアクションには Idempotency-Key が必要です。ネットワーク再試行に対して 24 時間のリプレイ防止が働きます。
- Tenant isolation: すべてのデータベースクエリはアカウント ID で厳格にフィルタリングされます。テナント間アクセスは構造的に不可能です。
- Tamper-evident audit log: すべてのリクエストはチェーンハッシュ（chain_hash[n] = sha256(chain_hash[n-1] || row_n)）付きで監査ログに記録されます。事後の改ざんはハッシュの不一致により即座に検知されます。
- Credentials.read alerting: すべての credentials.read 呼び出しは専用の監査エントリーを生成し、必要に応じてアカウントオーナーに確認メールが送信されます。
- SSRF-guarded webhooks: Webhook URL は保存前に検証されます：HTTPS 必須、DNS 解決はパブリック IP のみを返す必要があります（RFC1918 不可、リンクローカル不可）。
リセラー側でのベストプラクティス
- シークレットはシークレットマネージャー（HashiCorp Vault、AWS Secrets Manager、Doppler、1Password）に保管してください。コード内や Git リポジトリには絶対に置かないでください。
- シークレットは定期的にローテーションしてください（少なくとも年 1 回、または人事異動時）。カスタマーポータルからワンクリックで実行でき、旧シークレットは即座に無効化されます。
- ユースケースごとに最小スコープの専用キーを 1 つ用意してください（可能なら読み取り専用）。「神モード」キーは作らないでください。
- 統合が固定 IP（クラウド、踏み台）から実行される場合は IP 許可リストを設定してください。
- Idempotency-Key はサーバー側で生成して永続化し、再試行のたびに新しい値を生成しないでください。推奨：論理的な注文ごとに UUIDv4 を使用してください。
- 自社の URL に Webhook を設定し、少なくとも order.created と credentials.read をイベントストリームとして監視してください。
セキュリティ報告
セキュリティ上の問題は security@kernelhost.com まで内密にご報告ください。PGP 鍵はご請求に応じて提供します。24 時間以内の返信を保証します。バグバウンティプログラムは準備中です。
