モジュール XIX — 自前の API と manage-as-code サーフェス

モジュール XIX はエンジンに後付けされた機能ではありません — それはエンジンのサーフェスそのもので ある。他のすべてのモジュールは同じファーストパーティ API を通じて外界に到達し、Web UI は並行する 別物ではなく、まさにその契約の上のプレゼンテーションレイヤーです。本ページは、そのサーフェスが 現在何を公開し、control plane をコードとしてどう管理するか、その実際の境界と共にリファレンス します。

API 契約

エンジンは /v1 配下で一つの REST API を話し（chi ルーター、堅牢化された http.Server）、 その焦点を絞った凍結された gRPC ミラーを話します（olivares.api.v1: サーバー情報、エージェントの 読み取り／作成、監査検証、加えて標準のヘルスサービス）。gRPC は意図的なサブセットであって完全な パリティではありません — 新しいエンドポイントはまず REST に着地します。両方のケーブルは同じ authenticate → resolve-tenant → authorize チェーンを実行し、エラーを同一にマッピングするため、 not-found はどちらのワイヤー上でもクロステナントのリソースと区別がつきません。

REST サーフェスは、製品が作成したスキーマから直接 API リファレンス で レンダリングされる OpenAPI 3.1 契約として公開されます。そのドキュメントが安定コアサーフェスの 記録上の契約です。モジュールルートは別の beta ドキュメントとして module-route リファレンス で公開されます（以下の誠実な限界を参照）。 同じ機能はターミナルからも駆動できます — CLI リファレンス を参照 — なぜなら CLI はエンジンであって、その上のラッパーではないからです。

認証とワイヤー

認証は JWT ではなく不透明なサーバーサイドベアラートークンです。 トークンは用途別にプレフィックス されます（セッション対 API キー）; サーバーは公開セレクターとシークレットの SHA-256 のみを 永続化し、シークレットを定数時間で比較します。manage-as-code ワークフローにとって重要な帰結: トークンは即座に失効可能で、クレームやシークレットを運ばず、暗号パースの攻撃サーフェスを 追加しません。API トークンは (tenant, role) にバインドされるか、バインドされないシステムレベルの 資格情報です; テナントヘッダーがバインドされたトークンと食い違うリクエストは拒否され、決して サイレントに拡大されません。

manage-as-code: Terraform プロバイダー

terraform-provider-olivares プロバイダーは独立した Go モジュールであり純粋な REST クライアントです — エンジンコアやコネクター SDK を決してインポートせず、大きなプロバイダーの依存 ツリーをコアのサプライチェーンの外に保ちます。エンドポイント、機密の API トークン、オプションの テナントで設定され、意図的に小さく宣言されたオブジェクトのセットを管理します:

種別	名前	管理対象
resource	olivares_agent	エージェントのカタログ定義（完全な CRUD + インポート）
resource	olivares_policy	ガバナンスポリシー宣言
resource	olivares_agent_identity_binding	エージェントの非人間アイデンティティへのバインディング
resource	olivares_deployment	デプロイメント定義（望ましい状態、宣言的）
data source	olivares_policies / olivares_identities	ガバナンス下のロスターの読み取り専用ビュー
data source	olivares_access_edges	R/RW アクセスマップと permitted-vs-observed ドリフト
data source	olivares_deployment / olivares_server_info	デプロイメント定義; エンジンメタデータ

これらがプロバイダーが提供する唯一のリソースとデータソースです。olivares_deployment の宣言は 望ましい状態を control plane に記録します — インフラに触れません; apply パスは モジュール VII に属し、デナイクローズドなシームです。

誠実な限界

• olivares_deployment は宣言する; デプロイしない。 このリソースはモジュール VII のルートを 通じてデプロイメント定義を書き込みます。実際のインフラに対するライブな apply/retire は、 オペレーターがエグゼキューターをプロビジョニングするまで 503 を返すデナイクローズドなシーム です — HCL でデプロイメントを宣言しても、あなたの estate を変更することは決してありません。
• 安定 OpenAPI はワイヤーの全体ではない。 安定コアサーフェスは公開された 契約（/openapi.json）にあります。モジュールルート（例えばアクセスマップとドリフトの読み取り、 プロバイダーが使うガバナンスおよびデプロイメントのルート）は、別の beta ドキュメント（/openapi.beta.json、 module-route リファレンス）として公開されます。それらのフィールドレベルの形は、 安定スキーマではなく製品の型付きインターフェースの中に存在します。
• gRPC は凍結されたサブセットであって、完全な API ではない。 ファーストパーティの自動化のために いくつかの読み取り／作成と監査の操作をミラーします; REST に存在するからといってエンドポイントが gRPC に存在すると仮定しないでください。
• プロバイダーのサーフェスは意図的に小さい。 4 つのリソースと 5 つのデータソース — IaC として API 全体ではありません。そのセットの外にあるものは、現在 HCL で宣言されるのではなく REST/CLI で 管理されます。
• ライセンスは証明であって、決して機能ゲートではない。 製品はそのライセンスの下で完全です; オフラインのライセンスチェックは保有者とステータスを記録するだけで、いかなる API リクエストや ブートも無効化、ディグレード、ブロックすることは決してありません。

デフォルトで安全

提供エンジンはデフォルトで安全です: TLS はオン（何も供給されなければ初回ブート時に自己署名証明書が 生成される）、バインドはデフォルトで localhost、ローカルでのリッスンは認可の免除ではありません。 新規インストールには資格情報がありません — ワンタイムのセットアップトークンを stdout にミントし、 最初の管理者が作成されるまですべての保護されたエンドポイントを拒否します。監査は追記専用で ハッシュチェーン化されており、Ed25519 で署名されたチェックポイントが、チェックポイント以前の 履歴の書き換えを暗号学的に検知可能にします。

イベンティングプラットフォーム（モジュール XIX のアウトバウンド側）

イベンティングプラットフォームが出荷されて以来（modules/eventing）、モジュール XIX のサーフェスは テナントのセルフサービス・イベントサブスクリプションも含みます: バスイベントのカタログ （edge.observed、cost.sampled、finding.reported、audit.recorded、…）に対する型付き サブスクリプションで、永続的な at-least-once デリバリー — バックオフ付きリトライ、デッド レターキュー、カーソルからのリプレイ — を、HMAC 署名された webhook または SIEM シンク へ提供します。通知モジュール （XV）は依然としてオペレーターがプロビジョニングした宛先への アラートルーターです; イベンティングはインテグレーター向けのプラットフォームです。 付随する読み取り専用のポスチャーエクスポート（modules/posture-export）は、コントロール タワーが製品のグラウンドトゥルースのポスチャー — アクセスグラフ、ドリフト、インベントリー、 ファインディング — を ref/ハッシュ/リレーションのみとしてポーリングできるようにし、エクスポート 自体が監査されます。

関連

• API リファレンス — コアサーフェスのレンダリングされた OpenAPI 3.1 契約。
• API 安定性ポリシー — このサーフェスのバージョン管理、非推奨／サンセット のシグナリング、サポート期間。
• クライアント SDK を使う — ファーストパーティの Go/Python/TypeScript クライアント。
• CLI リファレンス — olivares バイナリからの同じ機能。
• control plane をコードとして管理する — Terraform プロバイダーガイド。
• モジュール VII — デプロイメント — olivares_deployment が 作用する場所（503 シーム）。
• モジュールカタログ — Govern/Observe 対 Actuate の区分。
• 誠実さと限界 — 現在何が作用し何が作用しないか。
• アーキテクチャ概要 — このサーフェスが乗るエンジン レイヤー。