Aggrega Plugin 信頼レコードスキーマ
自動生成されたリファレンスです。手動で編集しないでください。公開されている JSON Schema から再生成してください。
スキーマ ID: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
受理または拒否の判定を返す各アタッチメント、すなわち ir-verdict または render-verdict ロールの plugins.governance アタッチメントと、すべての plugins.linter アタッチメントについて、信頼されたプラグインの識別情報を機械生成で記録したものです。ロックファイルの隣の plugins-trust.yaml に置かれ、ロックファイルとともにコミットされます。バージョン管理の外にあるレコードは誰もレビューできず、何とも比較できないためです。書き込むのは aggrega pull で、これらのアタッチメントのいずれかを初めて解決したときにファイルを作成し、アタッチメントを解決するたびにアタッチメントごとのレコードを追加します。設定されたアタッチメントの一部についてのみレコードを持つファイルは、破損した状態ではなく有効な中間状態です。読み込むのは aggrega build、aggrega lint --release、aggrega validate --release、および aggrega serve と aggrega mcp を通じて到達する同じ操作です。いずれも、これらのアタッチメントが実行される前にワークスペース設定をレコードと照合します。2 種類の不一致は、異なる理由で拒否されます。解決されたアーティファクトダイジェストが記録されたダイジェストと異なるプラグインは、実行されずに拒否されます。実行されようとしているプラグインが、レコードのレビュー対象となったプラグインではないためです。また、設定されたどの判定アタッチメントにも対応しないレコードエントリは実行を停止させます。ゲートを取り除いてもレンダリングされるバイトは何も変わらないため、レビュー済みのゲートなしで生成された出力は、そのゲートが承認した出力と区別できないためです。ビルド、リリーススコープの lint、リリーススコープの検証は、コマンドラインからでも、aggrega serve や aggrega mcp を通じてでも、コンテンツキャッシュから読み込むこれらの各プラグインを、読み込む時点で、そのレコードが持つ signature と照合します。これは、ビルドが各ロックファイルエントリをそのエントリが持つものと照合するのと同じです。後述の signature を参照してください。逆方向、すなわちレコードがまだ保持していない設定済みアタッチメントは、先に述べた中間状態であり、どちらの比較もこれを拒否しません。また、レコードが存在しない場合はエントリを一切保持しないため、何も固定せず、どちらの比較もそれについて何も拒否しません。署名要件は、エントリが欠けていても免れない唯一の照合であり、後述の signature で説明します。エントリがレコードから除かれるのは明示的なアップグレード時のみです。プラグインを指定した aggrega pull --upgrade は、どの判定アタッチメントもそのプラグインを指定しなくなった場合にそのプラグインのエントリを削除し、引数なしの aggrega pull --upgrade はそのようなエントリをすべて削除します。通常の aggrega pull はエントリの識別情報を再解決せず、エントリを削除もしません。したがって、対応するもののないエントリによる停止は、次回の実行によってではなく、意図的にそう指示することによって解消されます。最後のエントリが削除されたレコードは、削除されるのではなく空になります。空のレコードは有効なレコードです。何も保持しないため何も固定せず、レコードが存在しない場合とまったく同様に、どちらの比較もそれについて何も拒否しません。各レコードはプラグイン自身の識別座標によってアドレス指定され、選択されたバージョンとアーティファクトダイジェストをフィールドとして持ちます。そのため、バージョンの変更は新しいアドレスの下の新しいレコードではなく、既存レコードのフィールドの変更になります。これにより、バージョンが変わったプラグインを、ファイル上でもその差分上でも、初めて記録されたプラグインと区別できます。その識別情報に加えて、レコードは名指しするアーティファクトについての 2 つの事実を持ち、いずれも検証された場合にのみ記録されます。1 つは、公開者がアーティファクトに付与した非推奨情報で、それが見つかり署名が検証された場合に記録されます。もう 1 つは、aggrega pull がプラグイン自身の署名を検証したときに記録した検証済み署名の事実で、ロックファイルエントリが持つものと同じ事実が同じキーで記録されます。いずれも記録されたアーティファクトについての事実であり、第二の識別情報ではありません。そのため、通常の pull は照合対象の識別情報を乱すことなくこれらを記録します。ファイルがそれ以外に記録するものは何もありません。ファイル自体への署名も、ルール入力も、解決の来歴(レジストリホストや、書き込んだマシン上のパス)も、時刻も記録しません。そのため、同じ解決はいつどこで実行しても同じバイトを生成します。plugins.governance 判定アタッチメントの外部ルールファイルは、ロックファイルの verdict_inputs にダイジェストとして記録されます。plugins.linter アタッチメントのルール入力はどちらのファイルにも記録されません。ビルドがバイト単位で再現するものはすべて、代わりにロックファイルで固定されます。判定アタッチメントはレンダリングされる出力にまったく影響しないため、その識別情報はロックファイルではなくここに記録されます。スキーマ進化の方針: 新しいトップレベルセクションの追加は SemVer-MINOR(追加的)、既存セクション内への新しいフィールドの追加は SemVer-MINOR、キーの削除や制約の厳格化は SemVer-MAJOR です。
トップレベルの型: object
プロパティ
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
plugins | object[] | いいえ | 判定を返すアタッチメントに対して信頼されたプラグインごとに 1 つのレコードで、プラグインの識別座標によってアドレス指定されます。同時に 2 つの判定ロールにアタッチされたプラグイン(ir-verdict と render-verdict の両方にバインドされた同じガバナンスプラグイン)は単一のレコードになります。記録される対象はアタッチメントではなくプラグインの識別情報であり、2 つのアタッチメントは同じアーティファクトを読み込むためです。レコードは座標の昇順で出力されます。デフォルト: [] |
version | const 1 | はい | 信頼レコードのスキーマバージョン: 1。スキーマに SemVer-MAJOR の変更が入るとこの値が増加します。定数: 1 |
追加のプロパティは許可されません。
plugins-trust.plugins[]
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
deprecation | object | いいえ | digest が指すアーティファクト上で、署名され信頼されたマーカーが見つかったときに記録される、検証済みの遡及的な非推奨マーカーです。マーカーは、非推奨とするアーティファクトの署名付き OCI リファラーであり、アーティファクトを再公開することなく公開後にアタッチされます。そのため、ここにすでに記録されているプラグインを後から非推奨にできます。撤回の段階である retracted の重大度では、アーティファクトは単に非推奨とされるのではなく、選択対象から除外されます。これはこのレコードがすでにアドレス指定しているアーティファクトに関する事実であり、第二の識別情報ではありません。そのため aggrega pull は resolved_version と digest をそのままにしたままマーカーを追加できます。マーカーを記録しても何も採用されません。マーカーは、解決されたダイジェストがすでに記録されているダイジェストと等しい場合にのみ記録されます。異なるバイトを報告する解決は識別情報の変更であり、このレコード自身の規則に従い、実行がそれを要求しない限り拒否されます。記録されたマーカーを消去するものはありません。マーカーは、それを保持するレコードとともに、そのレコードを置き換えるか削除する明示的なアップグレードによってのみ取り除かれます。aggrega build、aggrega lint --release、aggrega validate --release、および aggrega serve と aggrega mcp を通じて到達する同じ操作は、マーカーを保持するプラグインを名前で示します。そうしなければ、非推奨のゲートが何も知らされないまま取得、キャッシュ、実行されるためです。また、ワークスペースの build.halt_on_deprecated_severity ダイヤルが、ビルドをそこで停止するか、単に通知するかを決定します。 |
plugin | string | はい | プラグインの識別座標です。ソケットセグメントと素の名前をスラッシュで連結したもので、governance/aggrega-security-baseline のようになります。素の名前はそのソケット内でのみ一意であるため、異なるソケットにある同名の 2 つのプラグインを区別するのはソケットセグメントです。座標には意図的にバージョンを含めません。これにより、バージョンの変更が無関係なレコードとしてではなく、下記の resolved_version への編集として見えるようになります。 |
resolved_version | string | はい | レコードが書き込まれたときにこのプラグインに対して選択された具体的なバージョンです(例: 1.2.3)。単一のパスセグメントとして記録されるため、/、\、.. を含みません。パターン: ^([^/\\.]|\.[^/\\.])*\.?$。 |
digest | string | はい | 解決されたプラグインアーティファクトのコンテンツダイジェストで、sha256: の後に 64 文字の小文字の 16 進数が続く形式です。これは、コンテンツアドレスが比較されるすべての場所で書かれる形式です。パターン: ^sha256:[a-f0-9]{64}$。 |
signature | VerifiedSignature | いいえ | aggrega pull が、digest が指すアーティファクトについて、解決元レジストリの信頼ポリシーに照らしてこのプラグイン自身の署名を検証したときに記録される、検証済み署名の事実です。pull は、これらのアタッチメントのいずれかのために解決するすべてのプラグインの署名を毎回検証し、見つかった内容をここに記録します。レコードが保持していた内容を置き換え、署名を検証できなかった場合は削除しますが、レコードが照合される識別情報には影響しません。ビルド、リリーススコープの lint、またはリリーススコープの検証がプラグインを実行する前に、この事実が指すキャッシュされた署名バンドルが再ハッシュされ、blob が存在しないか異なる場合は実行が停止します。また、コンテンツキャッシュから読み込まれたプラグインについては、署名がどのアーティファクトに対して作成されたかをそのバンドルから読み取り、読み込んだプラグインとは異なるアーティファクトに対して作成されていた場合は停止します。そのため、別のプラグインのエントリからコピーされた signature は、署名要件の内容にかかわらず拒否されます。そこでは署名は検証されないため、このプラグイン自身のアーティファクト向けに作成され、手動でキャッシュに書き込まれたバンドルは、pull が検証したものと区別されません。さらに、ワークスペースの信頼設定がコンテンツキャッシュから読み込まれたプラグインに署名を要求する場合(これは aggrega pull がプラグインを検証するときに適用する要件であり、pull が署名を記録しないことを許すスキップや advisory レジストリは、実行の続行も許します)、そのプラグインの signature を持たないレコード、またはそのプラグインのエントリがまったくないレコードは実行を停止させ、プラグインと署名を要求する設定を名前で示します。カタログディレクトリから、またはコンパイラバイナリ内のコピーから読み込まれたプラグインは、この要件の対象になりません。 |
追加のプロパティは許可されません。
plugins-trust.plugins[].deprecation
digest が指すアーティファクト上で、署名され信頼されたマーカーが見つかったときに記録される、検証済みの遡及的な非推奨マーカーです。マーカーは、非推奨とするアーティファクトの署名付き OCI リファラーであり、アーティファクトを再公開することなく公開後にアタッチされます。そのため、ここにすでに記録されているプラグインを後から非推奨にできます。撤回の段階である retracted の重大度では、アーティファクトは単に非推奨とされるのではなく、選択対象から除外されます。これはこのレコードがすでにアドレス指定しているアーティファクトに関する事実であり、第二の識別情報ではありません。そのため aggrega pull は resolved_version と digest をそのままにしたままマーカーを追加できます。マーカーを記録しても何も採用されません。マーカーは、解決されたダイジェストがすでに記録されているダイジェストと等しい場合にのみ記録されます。異なるバイトを報告する解決は識別情報の変更であり、このレコード自身の規則に従い、実行がそれを要求しない限り拒否されます。記録されたマーカーを消去するものはありません。マーカーは、それを保持するレコードとともに、そのレコードを置き換えるか削除する明示的なアップグレードによってのみ取り除かれます。aggrega build、aggrega lint --release、aggrega validate --release、および aggrega serve と aggrega mcp を通じて到達する同じ操作は、マーカーを保持するプラグインを名前で示します。そうしなければ、非推奨のゲートが何も知らされないまま取得、キャッシュ、実行されるためです。また、ワークスペースの build.halt_on_deprecated_severity ダイヤルが、ビルドをそこで停止するか、単に通知するかを決定します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
message | string | はい | マーカーが保持する、人が読める非推奨メッセージです。通常は移行先の案内です。マーカーに個別のメッセージがない場合は、代わりにその理由がここに記録されるため、報告される文が空になることはありません。 |
severity | string (enum) | はい | マーカーの重大度で、warning < error < retracted の順です。この重大度が設定された停止しきい値以上の場合にビルドは停止し、それ以外の場合は通知されます。これは、他のすべての非推奨レポートが参照するのと同じ規則、同じダイヤルです。retracted は撤回の段階であり、この重大度のアーティファクトは選択対象から除外されます。一方、2 つの通知用の重大度では選択可能なままです。許可される値: "warning"、"error"、"retracted" |
追加のプロパティは許可されません。
定義
VerifiedSignature
pull が、解決元のレジストリのトラストポリシーに照らしてアーティファクトの署名を検証したときに記録する、検証済み署名の事実です。両方のレコードがこれに用いる唯一の形であり、ロックファイルではその各エントリに、このレコードでは各プラグインに用いられるため、検証済み署名はどちらのファイルでも同じように読めます。検証モード、一致したキーレスの identity/issuer(キーレスの場合)またはピン留めされた鍵のフィンガープリント(鍵ありの場合)、および pull がキャッシュした署名バンドルのコンテンツアドレス化されたダイジェストを記録します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
bundle_digest | string | はい | キャッシュされた署名バンドル blob の SHA-256 ダイジェストで、sha256: の後に 64 文字の小文字の 16 進数が続く形式です。キャッシュ blob を指すためパスを構成し、/、\、.. を含みません(これらは sha256: 形式によってすでに除外されています)。また、ビルド、リリーススコープの lint、およびリリーススコープの検証が、その blob を再ハッシュして照合する対象です。パターン: ^sha256:[a-f0-9]{64}$。 |
identity | string | いいえ | 署名の検証済み署名者です。キーレス署名の場合は署名証明書のサブジェクト、キー付き署名の場合は keyed:sha256: の後に固定された公開鍵の PEM テキストの SHA-256 が続くものです。 |
issuer | string | いいえ | キーレス署名の検証済み OIDC 発行者です。キー付き署名の場合は空です。 |
mode | string (enum) | はい | 署名を受け入れた検証モードです。許可される値: "keyless"、"keyed" |
追加のプロパティは許可されません。