CLI

ninka-authz コマンドラインインターフェースのリファレンスです。

概要

npm パッケージ: ninka-authz：npm install ninka-authz でインストールします。
実行ファイル: ninka-authz：通常は npx ninka-authz <command> として実行します。
Node.js: 20 以降が必要です。

現在の --help に表示される usage は次のとおりです。

usage: ninka-authz <command>

  init [--bare]        Set up ninka/ and the agent rules (AGENTS.md); --bare omits the sample policy
  compile [files...]   Sekisho + Rego + manifest + types + WASM (pinned opa, fetched once)
  build                compile, but fail when the pinned opa toolchain is unavailable (CI use)
  verify               Recompile and require byte-identity with ninka/out/ and the
                       Consumer Projections (CI gate)
  explain <policy>     Human-readable summary of a policy
  docs                 Serve the Authorization Reference for this project (local, read-only)
       [--port N]      Listen on a different port (default 4173)
       [--no-open]     Do not open a browser
       [-o <dir>]      Export a static snapshot into <dir> instead of serving

  --workspace <dir>    Use <dir> instead of ninka/ (global; every command above accepts it)
  --out <file>         Write the Consumer Projection to <file>, instead of <source root>/generated/ninka.ts
                       (init, compile, build; verify checks that file — not remembered, so a
                       later run, verify included, resolves again)
  --out-csharp <file>  Also write the C# Consumer Projection to <file> (compile and build;
                       verify checks that file). C# has no source-root convention to resolve,
                       so this names the file

--help または -h は usage を表示して exit 0 で終了し、コマンド本体は実行しません。--version はありません。

ワークスペースの決まり方

--workspace <dir> を渡すと、そのディレクトリを Ninka の authoring workspace として使います。このフラグはすべてのコマンドで利用できます。

フラグを省略した場合は、カレントディレクトリ直下の ninka/ を使います。存在しなければ失敗し、旧 authz/ へ黙ってフォールバックすることはありません。init だけは、選択したワークスペースを新しく作成できます。

ワークスペースには *.tegata.json、任意の vocabulary.json、スキーマのコピー、生成された out/ などが入ります。

TypeScript Consumer Projection の出力先

init・compile・build は、実行のたびに次の順で TypeScript の Consumer Projection の出力先を決めます。

--out <file> があれば、その .ts ファイル
tsconfig.json の compilerOptions.rootDir があれば <rootDir>/generated/ninka.ts
src/ と lib/ のどちらか一方だけがあれば、その下の generated/ninka.ts
src/ と lib/ が両方あり rootDir も --out も無ければ、出力先を一意に決められないためエラー
どちらの source root も無ければ、TypeScript の Consumer Projection は生成しない

init は必要に応じて src/ を作るため、通常の scaffold では src/generated/ninka.ts が生成先になります。

--out の値は保存されません。後から verify を実行すると出力先をもう一度解決するため、compile --out ... を使うプロジェクトでは verify にも同じパスを渡してください。

C# の Consumer Projection は --out-csharp <file> で出力先を明示します。Ninka は C# について source root から出力先を推測しません。

終了コードの基本

状況	終了コード
成功	`0`
コマンドが無い / 未知のコマンド	`2`
CLI の構文・引数エラー	`2`
スキーマ・関所・validation・I/O・toolchain・export などの実行時エラー	`1`

以下では、コマンド固有の違いを説明します。

`ninka-authz init [--bare] [--out <file>]`

Ninka のワークスペースと初期ファイルを作成します。既に存在するファイルは上書きせず、スキップします。

フラグ	意味
`--bare`	サンプルの `ninka/invoice-access.tegata.json` を作らない
`--out <file>`	TypeScript Consumer Projection の出力先をこのファイルにする

既定の scaffold では主に次を作ります。

パス	用途
`ninka/tegata-0.1.schema.json`	エディタや AI エージェントが参照する Tegata JSON Schema
`ninka/invoice-access.tegata.json`	サンプルポリシー。`--bare` では作らない
`ninka/vocabulary.json`	初期のプロジェクト語彙
`src/`	TypeScript の source root が無い場合だけ作成
`AGENTS.md`	AI コーディングエージェント向けの Ninka ルール
`.gitignore`	`ninka/out/bundles/*.wasm` を既定で Git 管理から外す Ninka のブロック

Ninka は lib/authz.ts のようなアプリケーション用ラッパーを生成しません。Ninka が生成して所有するアプリケーション境界は Consumer Projection です。独自の composition root が必要なら、それはアプリケーション側のコードとして実装します。

AGENTS.md が既にあり、## Ninka Authorization Rules セクションが無ければ追記します。同セクションが既に存在する場合は上書きしません。.gitignore も Ninka 自身のブロックについて同様に扱います。

scaffold 後に手形が一つ以上ある場合、init はコンパイル工程も実行します。OPA が利用できなければ、WASM を必要としないソース由来の成果物までは compile と同様に生成できます。

`ninka-authz compile [files...] [--out <file>] [--out-csharp <file>]`

手形をコンパイルします。

引数 / フラグ	意味
`[files...]`	指定した手形だけをコンパイルする。省略時はワークスペースのポリシーを対象にする
`--out <file>`	TypeScript Consumer Projection の出力先
`--out-csharp <file>`	C# Consumer Projection も指定パスへ生成する

JSON Schema、各ポリシーの関所検査、ポリシー集合と語彙をまたぐ検査を行います。拒否される検査があればコンパイルを停止します。

これらに通ると、Rego・manifest・input contract など、手形から直接導出できる成果物を ninka/out/ に書き出します。OPA toolchain を利用でき、WASM の build と生成 validation に成功した場合は、生成物がさらに増えます。実行 bundle、validation ファイル、そして指定された Consumer Projection です。

OPA 自体を解決できない場合、通常の compile は回復可能な経路を取ります。WASM build をスキップしたことを報告し、WASM を必要としない成果物までは書き出します。新しい bundle が無いため、その実行 material を埋め込む新しい Consumer Projection も生成しません。

正確な出力ファイルは生成ファイルを参照してください。

終了コード

通常の成功、および仕様で認められた OPA-unavailable の soft path は 0
スキーマ・関所の拒否、validation 失敗、I/O エラー、OPA が生成されたポリシーを拒否した場合などは 1
CLI の構文エラーは 2

`ninka-authz build [--out <file>] [--out-csharp <file>]`

compile と同じコンパイル工程を実行しますが、一つだけ条件が厳しくなります。実行 bundle を必ず生成できなければなりません。

OPA toolchain を解決・実行できない場合や、OPA が実行されたのに有効な bundle を生成できない場合、build は compile の soft path へは進まず失敗します。

CI やパッケージングなど、実行可能な認可 bundle が必須の工程で使います。

終了コード

必要な bundle を含めて build に成功した場合だけ 0
bundle を生成できない場合や、その他の validation / 実行時エラーは 1
CLI の構文エラーは 2

`ninka-authz verify [--out <file>] [--out-csharp <file>]`

verify は、ディスク上の生成状態が、現在のワークスペースと toolchain の契約から導かれる状態と一致するかを検査します。

Git は参照しません。 ファイルの存在やバイト一致は filesystem 上の事実です。そのファイルをリポジトリで追跡するかどうかは、別の Git 方針です。

フラグ	意味
`--out <file>`	TypeScript Consumer Projection をこのパスで検査する
`--out-csharp <file>`	C# Consumer Projection をこのパスで検査する。省略時は C# projection を検査しない

手形から直接導出できる成果物

ポリシーごとに Rego をメモリ上で再生成し、artifact tree 上の .rego とバイト単位で比較します。manifest についても、ソースから再計算できるフィールドを導出し直して比較します。generated_by は仕様や artifact identity ではなく provenance なので、再計算可能フィールドとは別に扱います。

ワークスペース全体の input-contract.json も同じように再導出して比較します。

Bundle と validation

固定された OPA toolchain を利用できる場合は、次を検査します。

policy と bundle の binding
entrypoint
Rego の系譜
module のハッシュ
build metadata
生成された validation ファイル
WASM に対する validation の再実行また、必要な再 build を行い、既存ファイル同士の辻褄だけではなく再現性を確認します。

成果物同士が整合していても、現在の手形と toolchain から再現できなければ verify は失敗します。

別の Ninka リリースで生成された状態は、provenance 契約に基づいて stale by upgrade として扱われる場合があります。provenance はバイト再現性の代わりにはならないため、現在のリリースで build し直します。

Consumer Projection

verify は compile と同じ規則で TypeScript の出力先を解決し、または --out で指定されたパスを使います。検証済みの成果物から Consumer Projection を再生成し、ディスク上のファイルとバイト単位で比較します。

C# projection は --out-csharp を渡した場合だけ検査します。

verify 自体はどちらの projection も書き換えません。projection の不一致は、artifact tree の不一致とは別の finding として報告します。

`not checked`

WASM まで完全に再現性を検査するには固定された OPA toolchain が必要です。toolchain 自体を取得できない場合、WASM / build / validation の一部は「一致した」とせず、明示的に not checked と報告されることがあります。これは toolchain unavailable による非失敗の skip です。

一方、前段ですでに fatal な finding があり、その結果として後段の義務を検査できなかった場合にも not checked は表示されます。この場合、実行全体は失敗します。

したがって not checked は常に「その義務は確認できていない」という意味です。「一致した」という意味ではありません。

bundle 不在と Git 管理は別

必要な bundle が ninka/out/bundles/ に無く、その環境で bundle を build できる場合は verify の失敗です。

一方、bundles/*.wasm を Git で追跡するかどうかはこの判定と無関係です。init の既定では raw WASM を .gitignore に追加しますが、verify が検査するときに bundle がディスク上に存在していれば、その構成自体は正当です。

終了コード

必要な検査義務が失敗すれば 1、それ以外は 0 です。ただし exit 0 でも、上で説明した非失敗の not checked が含まれる場合があります。その義務を release gate として必要とする場合は、出力の内容も確認してください。

`ninka-authz explain <policy>`

一つのポリシーを人間向けに要約して表示します。ファイルは書き換えません。

<policy> には policy id または手形ファイルのパスを指定できます。各ルールの概要と、存在する場合は解釈の記録を表示します。

`ninka-authz docs [--port N] [--no-open] [-o <dir>]`

読み取り専用の Authorization Reference をローカルで表示するか、静的 snapshot として書き出します。

ninka-authz docs
ninka-authz docs -o ./reference

フラグ	意味
`--port N` / `--port=N`	既定の `4173` ではなく、`1`〜`65535` のポートを使う
`--no-open`	ブラウザを自動で開かない
`-o <dir>` / `--output <dir>` / `--output=<dir>`	サーバを起動せず、この親ディレクトリ以下へ静的 snapshot を書き出す。空文字列は不可。プロジェクトルートを指定するなら `-o .` と明示する

LIVE

サーバは 127.0.0.1 に bind します。LIVE は現在のプロジェクトを読みますが、手形や ninka/out/ を変更せず、代わりに compile を実行することもありません。

最後のコンパイル後に仕様が変わった場合、ポリシー自体は読めますが、コンパイル済みの状態は stale と表示され、成果物が再び仕様に対応するまで対話的な評価は利用できません。

SNAPSHOT

-o で指定するのは親ディレクトリです。成功するたびに、その下へ timestamp 付きのディレクトリを新規作成します。export の際にもプロジェクトをコンパイルせず、snapshot として公開できる成果物条件を満たしていなければ拒否します。

画面の使い方と公開時の注意点は Authorization Reference を参照してください。

OPA toolchain

Ninka は、生成した Rego から WASM を build するために OPA を使います。通常の経路では、OPA のバージョンと配布 binary を固定しています。

固定 OPA バージョン: 0.65.0
通常の解決では、PATH 上に偶然ある opa を利用しません

解決順

NINKA_OPA_PATH：呼び出し側が明示した binary を使う override
~/.cache/ninka/ 以下の Ninka cache（または NINKA_CACHE_DIR）
対象プラットフォーム用の asset を取得し、設定済み SHA-256 を検証して cache する

NINKA_OPA_PATH は明示的な escape hatch であり、Ninka が配布する pinned binary ではありません。このパスで指定した binary を Ninka が pinned distribution として checksum 検証することはなく、その binary を選定・管理する責任は指定した側にあります。

環境変数

変数	効果
`NINKA_OPA_PATH`	固定 distribution の解決を行わず、指定した OPA binary を使う
`NINKA_CACHE_DIR`	Ninka cache のディレクトリを変更する

自動解決に対応するプラットフォーム

darwin-x64
darwin-arm64
linux-x64
linux-arm64
win32-x64

それ以外のプラットフォームでは、互換性のある toolchain を用意して NINKA_OPA_PATH で明示します。

概要​

ワークスペースの決まり方​

TypeScript Consumer Projection の出力先​

終了コードの基本​

ninka-authz init [--bare] [--out <file>]​

ninka-authz compile [files...] [--out <file>] [--out-csharp <file>]​

終了コード​

ninka-authz build [--out <file>] [--out-csharp <file>]​

終了コード​

ninka-authz verify [--out <file>] [--out-csharp <file>]​

手形から直接導出できる成果物​

Bundle と validation​

Consumer Projection​

not checked​

bundle 不在と Git 管理は別​

終了コード​

ninka-authz explain <policy>​

ninka-authz docs [--port N] [--no-open] [-o <dir>]​

LIVE​

SNAPSHOT​

OPA toolchain​

解決順​

環境変数​

自動解決に対応するプラットフォーム​

関連項目​

概要

ワークスペースの決まり方

TypeScript Consumer Projection の出力先

終了コードの基本

`ninka-authz init [--bare] [--out <file>]`

`ninka-authz compile [files...] [--out <file>] [--out-csharp <file>]`

終了コード

`ninka-authz build [--out <file>] [--out-csharp <file>]`

終了コード

`ninka-authz verify [--out <file>] [--out-csharp <file>]`

手形から直接導出できる成果物

Bundle と validation

Consumer Projection

`not checked`

bundle 不在と Git 管理は別

終了コード

`ninka-authz explain <policy>`

`ninka-authz docs [--port N] [--no-open] [-o <dir>]`

LIVE

SNAPSHOT

OPA toolchain

解決順

環境変数

自動解決に対応するプラットフォーム

関連項目