メインコンテンツまでスキップ

Consumer Projection

Consumer Projection は、Ninka が生成した認可成果物とアプリケーションコードの間に置く、生成済みのインターフェースです。

Ninka は正規の成果物を ninka/out/ に書き出します。これらのファイルは検証、内容確認、再現性の確認、各種ツールからの参照に使いますが、アプリケーションコード自身が成果物ディレクトリの構造や bundle の結び付き、entrypoint の配置まで理解する必要はありません。

その代わりに Ninka は、policy reference、入力契約、実行 bundle、ランタイムが検証に使うメタデータを一つにまとめた、アプリケーション向けのソースファイルを生成します。

TypeScript では通常、次の場所に生成されます。

src/generated/ninka.ts

.NET では出力先を明示します。

npx ninka-authz build --out-csharp Generated/Ninka.g.cs

Consumer Projection は、コンパイル結果をアプリケーションへ受け渡すための生成コードです。認可ロジックをもう一度実装したものではありません。

何が入っているか​

言語ごとの表現は異なりますが、Consumer Projection には主に次が含まれます。

  • 生成された policy reference
  • 各ポリシーの入力契約
  • それらのポリシーが利用する実行 bundle
  • ランタイムが bundle を検証するための manifest / build metadata
  • 各 policy reference に対応する tegata_hash

一方、認可ルールをアプリケーションの条件分岐としてもう一度書き直したものは含みません。TypeScript の生成モジュールは Ninka runtime を import し、WASM の復号、検証、instantiate、評価は runtime が担当します。

なぜ必要なのか​

Consumer Projection が無ければ、アプリケーション側が次のような内部事情を知る必要があります。

  • 成果物がどこに置かれているか
  • どの manifest がどのポリシーに対応するか
  • どの実行 bundle にそのポリシーが入っているか
  • どの entrypoint を評価するか
  • policy id と生成された入力型をどう対応づけるか

これらはコンパイラとランタイム側の責任です。アプリケーションから見える境界は、もっと小さく保ちます。

コンパイル済みの認可
        ↓
Consumer Projection
        ↓
Ninka ランタイム
        ↓
アプリケーションの判定

Ninka インスタンスをどこで生成するか、いつ認可を呼ぶか、具体的な入力をどう組み立てるか、返された判定をどう適用するかはアプリケーション側が決めます。Ninka はアプリケーションの composition root を生成したり所有したりしません。

アプリケーションと一緒に管理できる生成コード​

Consumer Projection は生成コードですが、通常は、それを import するアプリケーションコードと一緒にリポジトリで管理します。

そうすることで、アプリケーションが利用する認可契約の変化をコードレビューで確認できます。また ninka-authz verify は、解決した出力先へ Consumer Projection を再生成し、ディスク上のファイルとバイト単位で一致するかを検査できます。

ただし Consumer Projection は ninka/out/ の一部ではありません。用途が異なります。

出力主な利用者
ninka/out/verify、Authorization Reference、各種ツール、必要に応じたディレクトリ読み込み型 runtime
Consumer Projectionアプリケーションコードと、そこから利用する Ninka runtime

raw WASM などを Git で追跡するかどうかは、これとは別のリポジトリ方針です。詳しくは 生成ファイル を参照してください。

実行時の結び付き​

生成された policy reference は、手形に書かれた正確な policy id と、その版の仕様から生成された tegataHash を持ちます。

runtime は、その reference を評価する前に、ハッシュが読み込んだ bundle の manifest と一致するかを確認します。そのため、ある版の手形から生成された Consumer Projection が、別の版のポリシーを気づかないまま評価することはありません。不一致は整合性エラーであり、allow / deny の認可判定として扱われません。

アプリケーションから使う入口は一つ​

TypeScript の生成モジュールは、次を export します。

createNinka
policies

アプリケーションは policies から、policy idを導出した名前(ハイフンを取り除いたcamelCase)でポリシーを選びます。手形に書かれたpolicy idそのものは変換されずreferenceに残り、生成された reference は、そのポリシーで check() に渡せる入力型も決めます。

.NET の Consumer Projection でも、同じ役割の policy reference と入力契約を提供し、コンパイル済みの実行 material をアプリケーションへ運びます。言語ごとに構文は違いますが、責任境界は同じです。

詳しくは ランタイム API、.NET ランタイム API、認可コンパイラ を参照してください。