バージョン 1.0.0-alpha.1最新
第 2.19 章
すべての拡張機能が継承するルール
3つの軸での分離、UNO を介したコンピューティング、ルーターを介したAI(人工知能)、組織所有のキー、およびライセンスチェック。各ルールがコードにとって何を意味し、どのゲートがそれを強制するのか、そしてなぜ自分で記述する代わりにそれを継承するのかについて説明します。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

私の異常レビュープラグインが最初に送った拒否応答は、私自身に対するものでした。別のプラットフォームでの習慣から、ボディに組織のIDを含めて新しいレビューをPOSTするテストクライアントを書いたところ、プラグインは私のハンドラーが実行される前に次のように応答しました。
{
"error": true,
"code": "TENANT_NOT_A_PARAMETER",
"message": "The request body names the organisation. Tenancy comes from the token.",
"resolved": ["tenant", "owner"],
"missing": [],
"troubleshooting": ["Remove organizationId from the body. The organisation is read from your sign-in."]
}私はそのチェックを書いていませんでした。これは、SDK(ソフトウェア開発キット)テンプレートがすべての/apiルートに組み込むスコープガードに付属していたもので、ボディ内のIDが呼び出し元自身のIDであっても発動します。これが本章全体に共通するパターンです。すなわち、少数のルールがあり、それぞれが継承されたメカニズムによって強制され、コードがそれを迂回しようとするとビルドを失敗させるゲートが備わっています。Nexusでは、プラグインはプラットフォームから分離機能を継承し、ゲートがそれを監査します。
ルールは5つあり、以下のセクションで順番に取り上げます。3つの軸での分離、UNOディスパッチのみを経由して実行されるコンピュート、AI Provider Routerのみを経由するAI(人工知能)、組織に帰属するモデルキー、そしてライセンスに照らしてチェックされるライセンス対象機能です。また、すべてのマニフェストは、これらのうち3つを1つの文章ブロックで再宣明します。
ルール1:認証されたリクエストからの、3つの軸での分離
拡張機能におけるすべての読み取りと書き込みは3つの軸でスコープ設定され、すべてのツール呼び出しとスキルディスパッチも同様です。
| 軸 | カラム | 示す内容 | 境界の強さ |
|---|---|---|---|
| テナント | organization_id |
どの組織か | 厳格な境界。記録された読み取り専用の付与を通じてのみ越えられる |
| オーナー | owner_user_id |
組織内のどの人物か | 個人的なものすべてについて、同一組織内であっても非公開 |
| ユニット | business_unit_id |
組織のどの部分か | テナント内のオプションのフェンス |
所有者(owner)軸は、初心者が間違えやすい軸です。メールボックスは個人的なものであり、保存されたビューや個人のデータから派生したグラフも同様です。同じ組織、同じユニット、同じロールの2人のメンバーであっても、互いの所有者スコープの行を見ることはできません。一方、承認やケースレコードなどの組織の成果物では、所有者は来歴(プロビナンス)を表します。つまり、誰が行動したかを記録し、読み取りはテナントにスコープ設定されるため、監査証跡はそれを必要とする人々に可視化されたままになります。どちらの種類にするかはテーブルごとに決定し、ルート内の特別なケースとしてではなく、リポジトリ層でエンコードします。
これらの軸は、認証されたリクエストのみから取得されます。環境変数から供給することはできず、クエリパラメータ、パスセグメント、クライアントヘッダー、またはビルド定数からも供給できません。SDKは誤った記述を困難にしています。resolveScope(identity, options)には組織パラメータが一切ありません。組織はidentityの内部にあり、検証済みのトークンのみがそれを生成します。IDを受け渡すための経路は存在しないのです。
テナントを指定するボディが無視されるのではなく拒否されるのは、そのためです。ガードは、orgId、organizationId、organization_id、tenant、tenantIdの5つのフィールド名のいずれも拒否します。フィールドを黙って無視すると、呼び出し元にそのフィールドが機能すると誤解させてしまいます。最初の呼び出し元がテストして自分のデータが表示されると、次の呼び出し元は別の組織のIDを送信するでしょう。最初のリクエストで拒否することで、誰かが誤った前提の上に構築を始める前に、契約(コントラクト)を明確に示します。同じルールがディスパッチのinputParamsにも適用されます。組織IDを含むスキルの入力は、ディスパッチ時に拒否されます。
ユニット軸は、宣言して強制するか、まったく使用しないかのどちらかです。needsUnit: trueを宣言するルートは、クレデンシャルがユニットを解決できない場合、missing[]内にunitを指定して拒否します。サブドメインやヘッダーからユニットを合成したり、デフォルト値を設定したりしないでください。作られたユニットは組織の実際のユニットとは異なるフェンスを形成し、結合すべきではない行を結合してしまいます。
述語を表現できないサーフェスは拒否する
ルートが、ある行がどのテナントおよび所有者に属するか、またユニットが必要な場合にどのユニットに属するかを特定できない場合、そのルートは拒否します。フォールバックとしての組織全体の読み取りや、プレースホルダー値は存在しません。プレースホルダーは最悪の選択肢です。なぜなら、プレースホルダーは1つの値であり、値は行と一致してしまうからです。テナントとユーザーの両方を文字列'unknown'にデフォルト設定したツールルーターは、呼び出した誰に対しても組織全体のデータを提供してしまいました。テナント境界において、?? 'unknown'は欠陥です。
拒否応答はプラットフォーム上のどこでも同じ形式を持ち、クライアントが修正方法をレンダリングするのに十分な情報を含んでいます。
{
"error": true,
"code": "SCOPE_PREDICATE_MISSING",
"message": "Request cannot be scoped to a tenant from the presented credential.",
"resolved": ["tenant", "owner"],
"missing": ["unit"],
"troubleshooting": [
"The credential resolved tenant+owner; this route additionally requires a business unit.",
"Select a business unit in the client and retry — re-authentication will not change this outcome."
]
}errorは常にtrueです。codeはプラットフォームのコードカタログから取得されます。resolved[]は導出された軸を示し、missing[]はルートが必要としたが取得できなかった軸を示します。troubleshooting[]は実際にそれを修正する方法を示します。単なる「forbidden」だけでは、誰にも何も伝わりません。
クライアントの対処方法が異なるため、401と403は明確に区別してください。
| ステータス | 意味 | クライアントの動作 |
|---|---|---|
| 401 | 未認証 | 再サインインする |
| 403 | 認証済みだが、リクエストのスコープを設定できない、または呼び出し元に権限がない | 再試行を停止し、リクエストを変更する |
スコープの拒否を401として応答すると、クライアントは何度サインインしても終わらないサインインループに陥ります。セッションを破棄して再サインインし、再試行しては再び401を受け取るという動作を繰り返し、ユーザーは永遠に回り続けるスピナーを見つめることになります。
さらに2つのメカニズムによって、この拒否は完全なものになります。ハンドラー内部では、scopeOf(req)がスコープを読み取る唯一の方法であり、ガードが実行されていなければ例外をスローします。そしてガードはボディのパース後、どのハンドラーよりも前に実行されます。述語なしで到達可能になったハンドラーは、インシデントレポートではなくエラーバジェットに計上されるよう、意図的にMIDDLEWARE_ORDERING_ERRORを伴う500を返します。
データベースは単独で同じ境界を維持する
コードフェンスとデータベースフェンスは1つの法則に対する2つのメカニズムであり、その両方が提供されます。
スコープ設定されたテーブルに対するすべてのステートメントは、SDKのtenantFence(scope)を組み合わせて構成します。手作業で述語を記述することは決してありません。また、すべてのステートメントはwithScopedTxの内部で実行されます。これは、単一のデータベース関数を通じてその1つのトランザクションに対して3つの軸をバインドし、2回目のバインド(SCOPE_ALREADY_BOUND)を拒否します。その裏では、スキーマ内のすべてのテーブルで行レベルセキュリティ(RLS)が強制されており、リクエストパスが接続するロール自体がバインドされたテナントを変更することはできません。行レベルセキュリティをバイパスできるロールとして接続するプロセスは、DB_ROLE_BYPASSES_ISOLATIONを出して起動を拒否します。コードについては第2.22章「プラグインランタイム」で、ロールがどのようにレンダリングされるかについては第2.21章「プラグインSDK」で説明します。
唯一の越境:記録された付与
テナント境界を越える方法はただ1つだけです。行を保持する組織が、どの組織がどのテーブルを、どの合意の下でどれだけの期間読み取れるかを指定する付与(グラント)を記録します。データベースはその読み取りを読み取り専用にし、すべての参照は読み取りの前に、両方の組織においてIDのみで記録されます。書き込みが境界を越えることは決してありません。別の企業に渡される作業はメッセージとして移動します。所有者および管理者ロールは境界を越えて読み取ることは一切なく、組織間の読み取りを許可する権限が彼らを除外していない場合、マニフェストは拒否されます。境界を越える別の方法を望むプラグインがあっても、それは認められません。
ルール2:すべてのコンピューティングは UNO ディスパッチを介して実行される
ワークフローエンジンであるUNOが、唯一のコンピュートパスです。コードがモデルプロバイダーやエンジンを直接フェッチすることは決してなく、キューやワークフローホストに対しても同様です。ディスパッチエンドポイントに1つのエンベロープを送信し、識別子を含む202を受け取ります。結果はポーリングまたはコールバックによって届きます。
これに伴い3つの習慣が必要になりますが、テンプレートにはすでにその3つすべてが備わっています。
- 1つのファイルがディスパッチURLを所有します。
UNO_DISPATCH_URLは設定ローダーで一度だけ読み取られ、クラスター内のアドレスでなければなりません。インストール環境から外部へは何も出ないため、パブリックなアドレスは起動時に拒否されます。 - このサーフェスがディスパッチできるものの閉じた許可リストを1つ持ちます。ブラウザから渡された任意のスキルIDをディスパッチしてしまうバックエンドは、他のプラグインのスキルや誰か他の人のモデル予算を消費するスキルを含む、レジストリ内のすべてのスキルに対する汎用プロキシになってしまいます。このリストは名前空間付きジョブタイプのモジュールレベルの定数であり、環境変数には決してしません。リストにないIDは
SKILL_NOT_ALLOWEDで拒否されます。 - 返ってきたものを再チェックします。ジョブを読み戻す際、SDKのクライアントは返された行の
organization_idを、ネットワーク呼び出しのこちら側にある呼び出し元のテナントと比較します。呼び出しの向こう側にしか存在しないフェンスは、単なる慣習に過ぎません。
ルール3:すべてのAIは AI Provider Router を経由する
プラグインは、どこであってもモデルへの呼び出しを行いません。package.json内にプロバイダーSDKはなく、環境内にモデルキーもなく、リレーもありません。ルーターだけが組織のプロバイダークレデンシャルを保持し、最終的なプロバイダーとモデルの決定を下します。
プラグインができることは、登録時にマニフェストスキルのレジストリ行で希望を表明することです。
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}ルーターは、組織がそのプロバイダーを有効化しクレデンシャルを設定している場合にのみ、希望を尊重します。そうでない場合は、組織自身のプールから代替を選択します。capabilityProfileは選択を行わず、フィルタリングを行います。また、そのdataResidencyフィールドは厳格な管轄権の制約であり、ルーターはそれを満たすか、さもなくば拒否します。ほとんどのスキルでは、これらすべてを省略するのが正しいデフォルトです。その場合、組織自身のロール割り当てが決定を下し、支払うのもその組織自身となります。
2種類の拒否が返されますが、それらはまったく異なる意味を持ちます。
| コード | ステータス | 意味 |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | コードがルーター自体を呼び出そうとしました。停止してください。これは設計通りに拒否している境界(シーム)であり、再試行はできません |
MODEL_CAPABILITY_UNAVAILABLE |
422 | プロファイルを満たすモデルを持つ有効なプロバイダーがありません。プロファイルを緩和するか、組織が対応可能なプロバイダーを有効化します |
NO_PROVIDER_FOR_ROLE |
422 | 組織がこのロールのルーティングを設定していません。ルーターの修復テキストをユーザーに表示してください |
後半のペアはログではなく、画面に表示すべきものです。デフォルトのモデルもフォールバックプロバイダーも存在しません。組織が設定していないロールは、何を設定すべきかを示す一文を伴って明確に失敗します。
プラグインがルーターに対して行える唯一の読み取りは、runtime/ai-routeからのeffectiveRoute()です。これは、AIリクエストを送信することなく、サインインしている組織に対してルーターがどのプロバイダーとモデルを選択するかを応答し、該当するモデルがない場合はルーターの拒否理由を文章で返します。これについては第2.22章「プラグインランタイム」で示しています。
トラストラダー(信頼の階段)によってもう1つの境界線が加わります。ルーターに到達する2つのマニフェストスキルティア(tool_usingとllm_only)を宣言できるのは、coreおよびverifiedプラグインのみです。それ以外のすべては決定論的な作業を仲介し、モデルに到達する部分はプラットフォームに任せることになります。
ルール4:キーは組織に帰属する
各組織は独自のプロバイダーアカウントとキーを持ち込み、自身の請求を支払います。キーは組織のAIプロバイダープール内に存在し、コンソールから組織自身の管理者によって管理され、ルーターが呼び出し時にそれを解決します。テナントの背後に共有のプラットフォームキーは存在しないため、ある組織が別の組織の予算を消費することはありません。
拡張機能にとって、それは3つのことを意味します。
- コード内であれ、設定内であれ、シークレットストア内であれ、モデルキーを決して保持してはいけません。読み取り可能なキーが存在すると
no-credentialsゲートがビルドを失敗させ、キーが存在すると設定ローダーが起動を拒否します。 - 組織のキーを決して列挙してはいけません。プラグインがそれを必要としていると考える場合、要件の置き場所が間違っています。
- キーを持たない組織はAIの回答を得られません。これは想定される状態であり、専用の画面が必要です。不足しているロールを示し、修復方法を引用した上で、ユーザーをプロバイダー設定へと案内してください。これを空の結果としてレンダリングしてはいけません。
ルール5:ライセンス対象の機能はライセンスと照合される
インストール環境がCommunityフロアを超えて利用できる機能は、ただ1つの場所から決まります。それはAdverantが署名し、インストール環境上で公開鍵のみを用いて検証されるライセンス文書です。拡張機能は、トークン内のプラン名や設定内のフラグなど、それより弱い情報源から判断を下すことは決してありません。
プラグインにおいて、機能をライセンスに結び付ける最も簡単な方法は、その機能を保護する権限(ライト)に設定することです。マニフェストのrightsレジスター内の権限は、licence機能を指定できます。
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}組織のライセンスにcompliance-packsが含まれていない場合、その権限で保護されたルートを呼び出す人は誰でも、どのようなロールやシートを保持していても、LICENCE_LOCKED(403)で拒否されます。この拒否応答には、機能名とそれを含むライセンス、そして誰がそれを有効にできるかが示されます。
ライセンスの状態も重要です。ライセンスが有効であるか警告期間内にある間、ライセンス対象機能は動作し、猶予期間(グレースピリオド)中も動作し続けますが、猶予期間中はLICENCE_IN_GRACEという通知が表示されます。ライセンスが猶予期間を過ぎると制限がかかります。実行中の作業や読み取りは継続し、エクスポートやセキュリティ更新も同様ですが、ライセンス対象機能の下で新しい何かを作成しようとするとLICENCE_LOCKEDで拒否されます。作成パスは、その応答が返ることを想定して構築してください。
プラグインがエンタイトルメントチェックに対して組織がある機能を保持しているかどうかを尋ねると、単なるブーリアンではなく、判定結果(バーディクト)が返されます。「到達不能」と「到達可能でノー」は異なる事実であり、異なるコード(ENTITLEMENT_UNREACHABLE(502)とENTITLEMENT_DENIED(403))を持ちます。一時的な到達不能によって、すべての顧客が密かに無料フロアへダウングレードされるようなことがあってはなりません。
MANIFEST_SCOPE_WIDENEDの状態で保留されます。マニフェストは法則を再度明示しています。
すべてのv2マニフェストは、3つの必須の文を含むarchitectureブロックを持っており、バリデーターがその文言を固定しています。自身のインストール環境向けに構築するプラグインでは、それらは次のようになります。
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}これらの文はチェックされます。マニフェストで法則に同意しながら、コードでモデルプロバイダーをフェッチするようなプラグインは、自身の契約において嘘をついていることになり、ゲートはその嘘を検出可能にするために存在します。
各ルールを強制するゲート
SDKは、22の準拠ゲートを1つのコマンドnexus-gatesとして提供します。第2.21章「プラグインSDK」ですべてのゲートについて説明しています。ここでは、それらが維持するルールごとにグループ化して示します。
| ルール | ゲート | ビルドを失敗させる要因 |
|---|---|---|
| ルート層での分離 | scope-adherence, one-fence, rights-register, crud-adherence |
スコープガードのない/apiルート、手書きされた2つ目のテナント述語、権限のないスコープルート、権限が何も指定していない変更系ルート |
| SQLでの分離 | sql-fence, no-set-config |
フェンスのないスコープ設定されたテーブルに対するステートメント、テナント設定自体をバインドするプラグインコード |
| データベースでの分離 | migrations-are-scoped, rls-present, db-role-honest |
軸またはテナント先頭キーが欠落しているテーブル、強制された行レベルセキュリティがないテーブル、所有者またはスーパーユーザーとして接続するリクエストパス |
| 唯一の境界越え | grants-declared |
マニフェストが宣言していないマイグレーション内で付与されたテーブル、または手作業で特権が渡された読み取りシート |
| UNO経由のコンピュート | no-direct-compute |
モデルプロバイダーやエンジン、またはキューやワークフローホストへの直接フェッチ、ディスパッチURLの2つ目の読み取り元 |
| AIとキー | no-credentials |
リポジトリまたは環境内で読み取り可能なモデルプロバイダークレデンシャル |
| 宣言された契約 | api-contract, platform-clients, declared-input |
登録されているが宣言されていないルート、または宣言されているが登録されていないルート、インポートされているが指定されていないプラットフォームクライアント |
すべてのゲートには、それを発動させるために作られたフィクスチャで失敗することを証明するセルフテストがあります。npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testはそれらすべてを実行します。自身のフィクスチャで失敗しなくなったゲートは、機能を停止しています。
レビューを依頼する前に
これは、同僚にプラグインのレビューを依頼する前に私が確認するリストです。各行は、Corrán Orbitalのレビュアーから少なくとも一度は差し戻されたことのある項目です。
- すべての
/apiルートがスコープガードを登録しており、唯一の匿名ルートはallowAnonymous: trueを伴ってauth: publicと宣言された完全一致パスのみである。 - スコープガードが提供するすべてのルートがマニフェストのレジスターから
rightを指定しており、独自の権限チェックを持つハンドラーが存在しない。 - どのハンドラーも、ボディ、クエリ、またはヘッダーから組織、人物、またはユニットを読み取っていない。
- スコープ設定されたテーブルに対するすべてのステートメントが
withScopedTx内部のtenantFenceを経由しており、リポジトリ内のどこからもset_configを呼び出していない。 - すべてのテーブルが3つの軸カラム、
organization_idから始まるプライマリキー、およびテナントを含む複合外部キーを持っている。 - ディスパッチURLが1つのファイルでのみ読み取られており、ディスパッチ許可リストが名前空間付きジョブタイプの定数である。
package.json内のどこからもモデルプロバイダーと通信しておらず、環境内にキーが存在しない。- 一部のライセンスにのみ含まれるすべての機能が、それを保護する権限上で自身の
licenceを指定している。 npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testがグリーンであり、npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.jsonも同様である。
これら9つすべてが満たされていれば、レビューは製品そのものについての議論になります。それこそがレビュアーの時間を費やすべき対象です。
プラットフォームがこれらのルールを強制する理由
上記の各ルールはかつてどこかで単なる慣習であり、どの慣習も同じように破綻しました。つまり、それを覚えていたルートは問題なく、忘れた1つのルートがインシデントになったのです。オプションのミドルウェアとして適用されたビジネスユニットのフェンスは、6つの独立した方法でバイパスされましたが、そのすべてがオプトインしなかったルートでした。テナントIDを書き換える環境変数は、ある組織に別の組織の1,406件の連絡先を提供してしまいましたが、作成対象のPodにとっては正しかったため、レビューでは正しく見えたのです。
そのためプラットフォームは、すべてのサーフェスがすでに通過している場所に述語を配置しています。すなわち、スコープガードとフェンス関数、トランザクションラッパーと強制された行レベルセキュリティ、そしてディスパッチクライアントの内部です。さらにゲートがすべてのルートとステートメント、すべてのインポートを列挙し、それらのメカニズムを経由せずにスコープ設定されたテーブルやモデル、コンピュートエンジンに到達するものがあればビルドを失敗させます。この設計の代償として、最初のプラグインは制約が多いと感じられるでしょう。しかしその見返りとして、データへ至る他の経路が存在しないため、1000個目のプラグインは、作成者がその機能の存在を知らなくても分離されるのです。
これらすべてには正直な限界があります。ゲートはコードがメカニズムを経由していることを証明しますが、製品ロジックが正しいことまでは証明できません。クエリを所有者の行に正しくスコープ設定しているルートであっても、正しい所有者に誤った行を表示してしまう可能性はあります。第2.22章「プラグインランタイム」にある分離テストキットは、各フェンスを順番に取り除きながら、別の組織として、また同僚としてすべてのルートを攻撃します。私なら、ここまでの内容に関する自分自身の解釈を信用する前に、まずそのテストを実行するでしょう。

