smpebble/vlei-sandbox

vLEI サンドボックス

GLEIF検証可能LEI信頼チェーンの実用的なモデルです。インフラ不要で数秒で動作し、シミュレーションだけでは不十分になった場合に実際のKERIAスタックへのパスも提供します。

なぜこれが必要か

vLEIの導入障壁は、主に付随的なものです。KERIキーイベントログ、ACDC連鎖クレデンシャル、CESRエンコーディング、GLEIFガバナンス階層といった概念は学習可能ですが、通常の最初のステップはDockerコンテナの立ち上げ、OOBIの解決、マルチシグセレモニーの調整であり、たった一つのクレデンシャルを発行する前にこれらを行う必要があります。この順序は、vLEIが自分たちの問題に適合するかどうかを検討している人にとっては逆効果です。

このスキルはその順序を逆転させます。モックモードでは、本当のEd25519署名、本当のCESRエンコーディング、本当の自己アドレス指定識別子、本当のエッジ演算子の強制を、Python以外の依存関係ゼロで提供します。クレデンシャルスキームを設計し、意図的に破壊し、検証者が何を受け入れ、何を受け入れないかを正確に理解できます。ラップトップ上で、オフラインで、午後には完了します。その後、本番環境に移行できます。

2つのモード

	モック（デフォルト）	本番モード
必要条件	Python 3.8+	Docker Compose v2.23+
起動時間	即時	約60秒（イメージプル）
署名	本当のEd25519	本当のEd25519
SAID / CESR	本当	本当
ウィットネス、OOBI、IPEX	モデル化により省略	実際のプロトコル
マルチシグ、委任セレモニー	簡略化	完全
適している用途	クレデンシャル設計、検証ロジック、教育、デモ	統合、プロトコル動作、プレプロダクション

ユーザーが明示的にプロトコルレベルの動作を必要としない限り、モックモードから始めてください。ほとんどのアプリケーション設計上の質問は、こちらのモードでより速く回答を得られます。

はじめに

すべては1つのスクリプトで実行されます。スキルディレクトリから実行します：

python scripts/vlei_sandbox.py demo

これにより、6段階の信頼チェーン全体（GLEIFがQVIを認定し、QVIが法的主体クレデンシャルを発行し、主体が公的役割を承認し、QVIがOORクレデンシャルを発行し、主体が直接ECRクレデンシャルを発行）を構築し、結果を信頼のルートまで検証し、実行するすべてのチェックを表示します。最初にこれを実行してください。解説付きの出力は、エコシステム全体の仕組みを最も速く理解できる方法であり、強力なライブデモとしても機能します。

次に、何が壊れるかを示します：

python vlei_sandbox.py status                     # クレデンシャルとSAIDを一覧表示
python vlei_sandbox.py revoke --said <LE SAID>    # 主体クレデンシャルを取り消し
python vlei_sandbox.py verify --said <OOR SAID>   # 失敗する -- チェーンが崩壊した

この一連の操作（1つのクレデンシャルを取り消し、その下にあるすべてが失敗するのを確認する）は、どの図よりも核心的な概念を伝えます。権限はリンクされており、アサートされるものではないのです。

コマンドリファレンス

セットアップ

python vlei_sandbox.py init [--force]
python vlei_sandbox.py demo [--lei <18文字>] [--person 名前] [--role 役割] [--context-role 役割]
python vlei_sandbox.py status

アクター（AIDコントローラー）

python vlei_sandbox.py actor add --alias gleif --registry gleifRegistry --root
python vlei_sandbox.py actor add --alias qvi --registry qviRegistry --delegator gleif
python vlei_sandbox.py actor list
python vlei_sandbox.py actor rotate --alias qvi      # 事前ローテーション：AIDは存続

--rootはエコシステムの信頼のルートをマークします。--delegatorは委任開始（dip）イベントを生成し、GLEIFがAIDをQVIに委任する方法をミラーリングします。

クレデンシャル

python vlei_sandbox.py issue --type qvi      --issuer gleif --holder qvi --lei <LEI>
python vlei_sandbox.py issue --type le       --issuer qvi --holder le --lei <LEI> --auth <QVI SAID>
python vlei_sandbox.py issue --type oor-auth --issuer le --holder qvi --lei <LEI> \
    --person "Jane Doe" --role "最高経営責任者" --subject-aid <person AID> --auth <LE SAID>
python vlei_sandbox.py issue --type oor      --issuer qvi --holder person --lei <LEI> \
    --person "Jane Doe" --role "最高経営責任者" --auth <OOR AUTH SAID>
python vlei_sandbox.py issue --type ecr      --issuer le --holder person --lei <LEI> \
    --person "Jane Doe" --context-role "貿易金融責任者" --auth <LE SAID>

python vlei_sandbox.py revoke --said <SAID>
python vlei_sandbox.py verify --said <SAID>
python vlei_sandbox.py present --said <SAID> --out presentation.json

issueに--jsonを追加すると完全なACDCが表示されます。組み込みフラグを超えた属性には--data '{"key":"value"}'を使用します。

このツールは、ガバナンスルールに違反する発行を拒否します。権限エッジのないクレデンシャル、間違ったクレデンシャルタイプへのエッジ、チェックサムに失敗するLEIなどです。これらの拒否はデモンストレーションする価値があります。モデルが単にJSONを装飾するのではなく、何かを強制していることを示しています。

LEI計算（ISO 17442-1）

python vlei_sandbox.py lei make YZ83GD8L7GG84979J5     # -> YZ83GD8L7GG84979J516
python vlei_sandbox.py lei check YZ83GD8L7GG84979J516  # -> 有効

ダイアグラム

python vlei_sandbox.py chain --out chain.mmd    # Mermaid形式、スライドやドキュメントにそのまま使用可能

本番環境

python vlei_sandbox.py real scaffold   # docker-compose.yamlをプロジェクトにコピー
python vlei_sandbox.py real up
python vlei_sandbox.py real status
python vlei_sandbox.py real logs
python vlei_sandbox.py real down

ユーザーとの連携

ユーザーが実際に決定しようとしている内容に合わせて深さを調整します。

「vLEIについて説明して」 -- demoを実行し、その出力を順に説明します。先に講義をしないでください。成果物の方が理論よりも説得力があり、出力内のナレーションは、必要な順序で概念をカバーしています。

「vLEIは<問題>を解決できますか？」 -- 回答する前にreferences/application-patterns.mdを読んでください。正直な答えは多くの場合「部分的に」であり、そこに記載されている制約（LEIのコスト、検証されたことと信頼できることの違い）は、実際の意思決定において機能よりも重要です。

「Xのクレデンシャルを設計するのを手伝って」 -- モックモードでモデル化します。アクターを作成し、チェーンを発行し、その後意図的に攻撃します。権限なしでの発行、間違ったタイプへの連鎖、親クレデンシャルの取り消しを試みます。モックモードでこのような攻撃に耐えられる設計は、実際に構築する価値があります。

「どうやって統合するのですか？」 -- references/real-environment.mdを読んでください。KERIをエッジに留める方向に推奨します。プロトコルを話す1つの検証サービスと、下流の通常のJSONです。

「私のX.509 / 既存のPKIは近道になりますか？」 -- 率直に答えてください。ISO 17442-2（X.509におけるLEI）と17442-3（ACDCにおけるLEI）は並行するパスであり、変換パイプラインではありません。既存のPKIは、QVIによる企業代表者の検証に情報を提供するアイデンティティ保証源として真に価値がありますが、標準化された形式変換は存在せず、それを変換として位置づけることはGLEIFや規制当局との接触に耐えられません。詳細はreferences/trust-chain.mdにあります。

参考資料

必要に応じて読んでください。事前にすべてを読む必要はありません：

• references/trust-chain.md -- クレデンシャルタイプ、ACDCの構造、エッジ演算子、完全な検証者チェックリスト、ISO 17442シリーズのマッピング、既知のスキーマSAID。クレデンシャル構造や「検証済み」の意味に関する質問に答える前に読んでください。
• references/real-environment.md -- Dockerスタック、Signify-TSクライアントパターン、IPEXプレゼンテーション、既知の摩擦、本番環境への道のり。realモードに触れたり、統合コードを書いたりする前に読んでください。
• references/application-patterns.md -- 4つの実用的なアプリケーションパターン、5つの標準クレデンシャルタイプを超えた拡張方法、検証者設計チェックリスト、懐疑論者が指摘する前に提起すべき2つの制約。スコープ定義やアプリケーション提案の前に読んでください。

実装ノート

• 忠実度。 SAID、CESR修飾、エッジ演算子、TEL取り消しセマンティクス、事前ローテーションはすべて仕様通りに動作します。署名は本当のEd25519であり、verify呼び出しのたびに検証されます。
• ダイジェストアルゴリズム。 KERIのデフォルトはBlake3-256（CESRコードE）です。Blake3はPython標準ライブラリに含まれていないため、サンドボックスはBlake2b-256（コードF）にフォールバックします。これも有効なCESRダイジェストコードです。したがって、識別子はEではなくFで始まります。ただし、オプションのblake3パッケージがインストールされている場合は、本番環境と完全に一致します：pip install blake3。ユーザーがプレフィックスの違いに気づいた場合は、このことを伝えてください。これは置換であり、エラーではありません。
• 署名バックエンド。 cryptographyまたはPyNaClが存在する場合はそれらを使用し、それ以外の場合は依存関係のない純粋PythonのEd25519実装を使用します。initでどちらが使用されているかが報告されます。
• 状態。 作業ディレクトリに単一の読み取り可能な.vlei/state.jsonファイルが作成されます。自由に検査してください。KELとTELをプレーンなJSONとして見ることは有益です。秘密鍵のシードが含まれているため、これはサンドボックスのアーティファクトであり、コミットしたり、実際の用途に再利用したりしてはいけません。
• 意図的に欠落しているもの。 ウィットネスレシート、有線でのOOBI解決、IPEXメッセージ交換、マルチシグしきい値、ウォッチャー。これらは、クレデンシャル設計を変更しないプロトコルの関心事です。それらが問題になった場合は、realモードを使用してください。

移植性

このスキルはプレーンなPythonとMarkdownで構成され、フレームワーク依存関係がないため、Claude Code、Codex、Gemini CLI、または素のターミナルでそのまま動作します。ファイルを読み取り、シェルコマンドを実行できるエージェントは、必要なものをすべて備えています。エージェントがSKILL.mdではなくAGENTS.mdを読み取る場合、両方が存在し、同じ内容を指しています。