認証とプリンシパル

すべての RPC 接続は initialize ハンドシェイク中に プリンシパル をバインドし、各メソッド呼び出しは、現在の設定がそのプリンシパルに付与している権限と照合されます。このページでは、プロバイダーセット、ローカルユーザーの一覧、パーミッションプロファイル、そして最も重要な既存のリモート接続に生じる変更点について説明します。

1パスでのモデル

1. provider は認証情報を 1 つ検証します。ハンドシェイクで明示的な auth_token が指定されると、auth_provider で指定された provider（既定値は native、ゲートウェイのペアリングトークン）が選択されます。トークンがない場合、ローカルの Unix ソケットはカーネルのピア uid を peercred provider に提示します。選択された provider による拒否は最終的なものであり、認証情報が別の provider で再試行されることはありません。

2. 共有リゾルバーは、検証済みの ID を正規のプリンシパル ID と、設定によってその ID に割り当てられたパーミッションプロファイルへ対応付けます。OIDC の ID は、検証済みの issuer と subject の組で識別され、ローカルのロスター ID は、永続的な [users.<name>] のプリンシパル ID で識別されます。

3. RPCメソッドのうち、2つのハンドシェイクメソッドを除くすべては、必要なリソース動詞の権限に分類され、その権限がなければ拒否されます。initializeは認証情報そのものを伴い、cert/renewは、プリンシパルではなく、それを提示する相互TLSクライアント証明書によって認証されます。きめ細かなセレクタは、この上に組み合わさって適用されます:

   • config writes check config_write_paths;
   • session/new と session/prompt は、エージェントのセレクタを確認し、そのエージェントのポリシーで読み取りと書き込みの両方が許可されたディレクトリにセッションのワークスペースを限定します。これはワークスペースがリクエストで指定された場合、再開されたセッションに保存されていた場合、永続セッションから復元された場合のいずれにも適用されます。セッションは要求されたパスの表記ではなく、解決後のディレクトリに紐付けられるため、許可後にシンボリックリンクされた cwd の参照先を変更してもセッションは移動しません。また、そのようなエイリアス経由で保持されているライブセッションは拒否されます。他のセッションメソッドは、What this layer does not do (yet) で説明されているとおり、まだエージェントをチェックしません;
   • SOPの実行または承認には、そのSOPが実行するすべてのエージェントが必要で、セッションと同じツールセレクターのルールが適用されます。また、SOPの作成・保存・削除には、そのSOPが実行するエージェントが必要です。ステップにもプロシージャにもエージェントが指定されていないステップは、設定済みのエージェントエイリアスのうちソート順で最初のものとみなされます。これは、ヘッドレスエグゼキューターがフォールバックとして使用するエージェントです。決定論的なプロシージャのステップも含め、すべてのステップが対象になります。
   • 添付ファイル、パーソナリティファイル、エージェントを指定するコスト照会、cron ジョブは、いずれもエージェントセレクターを確認します。ローカルパスで送信される添付ファイルは、宛先エージェントのポリシーで読み取りが許可されている絶対パスも指定しなければなりません。フリートのコスト概要は、エージェント別の内訳にはプリンシパルのエージェントのみを表示しますが、その合計値とモデル別の使用量は引き続きすべてのエージェントを対象とします;
   • fs/list_dir は、呼び出し元のプリンシパルが利用できる有効なエージェントのポリシーで、そのエージェントに読み取りが許可されている絶対パスのみを一覧表示します。相対パス、.. コンポーネント、そして Windows では、ネットワークパスおよびデバイスパスを拒否します。 これらのルートは、各エージェントの解決済みポリシーに由来します。ポリシーには、そのリスクプロファイル、workspace.access が読み取りアクセス（セッションワークスペースの場合は読み取りと書き込み）を付与する兄弟ワークスペース、そして読み取り専用の共有スキルディレクトリが含まれます。ワークスペース限定ではないエージェント（自律性が full のもの、workspace_only = false を持つリスクプロファイル、yolo プリセット、または workspace.unrestricted_filesystem = true のもの）は、禁止パス以外の任意のパスを読み取れます。そのため、そのようなエージェントを利用できるプリンシパルは、そのエージェントが到達できる任意の場所にあるセッションを一覧表示したり開いたりできます。

   session/new と session/prompt は、セッションのキューで待機した後にこれらのチェックを再度実行します。そのため、主体が権限を縮小される前、または認証情報が期限切れになる前にキューへ入ったリクエストは、順番が来た時点で拒否されます。

認可は、zerocodeの設定エディタが使用するデーモンのRPC設定メソッド経由の編集については即時に反映されます。この方法で[permission_profiles]、[users]、[oidc]、またはsecurity.trust_daemon_uidを編集すると、保存時にポリシーが再コンパイルされます。既存のネイティブトークン接続およびローカル接続は、次の操作時に再解決され、再接続も再起動も不要です。OIDC接続は再度初期化する必要があります。

デーモンの外部で行われた編集（config.tomlを直接編集する場合、Webダッシュボード経由、またはzeroclaw config setを使用する場合）は、次回のデーモンのリロードまたは再起動時に適用されます。

ゲートウェイのペアリング制御からゲートウェイのペアリングトークンを失効させると、そのトークンで認証された接続は、次の操作の前に無効になります。

設定を編集して（RPC経由でも、ディスク上でも）gateway.paired_tokensからトークンを削除しても、実行中のデーモンには影響せず、そのトークンを使用している接続は引き続き認可されたままです。この削除は次回のデーモンのリロードまたは再起動時に適用されます。ただし、それまでにゲートウェイを通じて行われたペアリング変更により、そのトークンを含む現在のトークンセットが設定に書き戻された場合は除きます。

トークンの失効は、ペアリング制御から行ってください。

プロバイダー

ローカル接続

Unixソケット上で、トークンを提示しない接続は、カーネルが報告するピアのuidによって識別されます。security.trust_daemon_uid が true（デフォルト）の間は、デーモンの自身のuidによる接続が、[users] の名簿の有無にかかわらず、信頼された共有オペレーターとしてフルアクセスで扱われます。そのため、名簿のないインストールでも、デーモンを実行しているアカウントについては従来どおりに動作します。

デーモンを実行するオペレーターは設定ファイルを所有しており、ローカルのみでのロックアウト復旧はこの権限に依存しています。Unix ソケットでは、security.trust_daemon_uid を false に設定すると、デーモン自身の UID を含むすべてのローカルピアが、ロスターを経由するか、トークンを提示する必要があります。この設定は、後述する Windows 名前付きパイプには効果がありません。

他の uid はすべて、明示的な [users.<name>].uid エントリによって対応付けられている必要があります。対応付けられていない uid（root を含む）がトークンを提示しない場合、ロスターの有無にかかわらずアクセスは拒否されます。共有オペレーターアクセスへのフォールバックはありません。リスナーはソケットを所有者専用として作成するため、現時点では、デーモン自身のアカウントと root だけがソケットに到達できます。ロスターのエントリは、他の uid が到達できるようになった後に何を行えるかを決定します。

Windowsの名前付きパイプはpeer uidを伝送しません。ロスターが存在しない場合は、パイプのACLが認証情報となり、ローカル接続は共有オペレーターとして扱われます。[users] ロスターが存在すると、ローカルクライアントはトークンを提示する必要があり、security.trust_daemon_uid は効果を持たず、デーモン自身のアカウントには信頼されたローカル経路がありません。ポリシーのコンパイル中も、ペアリング済みのゲートウェイトークンは共有オペレーターとして認証されるため、それを送信するクライアントは、WSS経由でもパイプ経由でも、ロスターをライブで修復できます。zerocodeのローカルパイプ接続はトークンを送信しないため、そのようなクライアントがない場合、ロックアウトはconfig.tomlを編集して再起動することで修復されます。

クライアントは initialize でシェル環境を転送できます。これにより、デーモンのサブプロセスがクライアントの PATH と認証情報ソケットを参照できます（環境変数の受け渡しを参照）。このスナップショットは、ローカル接続上のオペレーターレベルのプリンシパル（共有オペレーター、または admin = true が設定されたロースターのプリンシパル）に対してのみ保持されます。それ以外のプリンシパルおよびすべてのリモート接続には、代わりにデーモン自身の環境が提供されます。

セッションの作成または復元時に、資格が再度確認されます。転送された環境が空でないものを保持している既存のセッションは、現在認可されているローカルオペレーターだけが再開またはプロンプトを送信できます。WSS 経由で再接続した場合や、プロンプトのキュー待ち中に admin を失った場合、その環境は次のターンに引き継がれず、リクエストは実行前に拒否されます。転送された環境なしで続行するには、新しいセッションを作成してください。転送された値を持たないセッションは、他の認可チェックの対象となりますが、通常どおり再開できます。保持された環境は、そのセッションの存続期間中は変更できません。後続のリクエストを拒否しても、実行中のターンの下で保持された環境が書き換えられることはありません。再開には、現在の接続で認可された環境が、セッションの保持された環境と一致することも必要です。一致しない場合は、新しいセッションを作成してください。環境を持たないセッションは、admin が削除された後でも再開できます。

リカバリー

リモート認証のバイパスは提供されません。リモート接続では、必ず有効な認証情報を提示する必要があります。認可ポリシーがまだコンパイルできる間は、ペアリング済みのゲートウェイトークンまたはoperatorレベルのプリンシパルを保持するクライアントであれば、どこからでもロックアウトを修復できます。そのような認証情報がない場合、また deny-all 状態にある場合は、復旧経路は常にデーモンを実行しているホスト上で行われます。どのローカル経路が適用されるかは、ポリシーがまだコンパイルできるかどうかによって決まります。

ポリシーがコンパイルできず、ロックアウトされています。 認可は有効で、ローカルの信頼済みパスは Unix ソケット上で維持されています。Windows の場合は、上記の名前付きパスに関する注記を参照してください。デーモン自身の uid としてローカル接続してください。security.trust_daemon_uid = true（デフォルト）の場合、そのアカウントはロスターの内容に関係なく、信頼された共有オペレーターとして扱われます。その口経由で問題のあるエントリを修復できます。例えば zerocode の設定エディタで行うか、RPC の config/set で users.alice.uid を指定します。変更は保存時点でコンパイルされ、公開されます。config.toml を編集する、または zeroclaw config set を実行しても修復できますが、その場合はデーモンが設定を再読み込みするか再起動された後にのみ反映されます。

deny-all の承認済み状態によりロックアウトされています。 ポリシーがコンパイルされなかったため、承認済み状態は解決処理の前にすべてのプリンシパルを拒否します。デーモン自身の uid と共有オペレーターも含まれます。どの RPC でも修復できません。config/set と config/reload も、他のすべてと同様に拒否されます。所有者として config.toml を直接編集し、その後デーモンを再起動して、修復したセクションがコンパイル・公開されるようにしてください。デーモンは SIGHUP を無視するため、再読み込みには再起動が必要です。

security.trust_daemon_uid を false に設定すると、信頼された UID によるルートは無効になります。コンパイルは通るものの不適切なポリシーは、ペアリング済みのゲートウェイトークンを提示するクライアント、または管理者権限を持つ名簿上のプリンシパルによってライブで修復できます。それ以外の場合、どちらの状態でも修復方法は同じです。config.toml をその所有者として編集し、再起動してください。この設定をオフにするのは、それが許容できる場合に限ってください。

ユーザー名簿

zeroclaw config set users.<alias>.permission_profiles <value>

export ZEROCLAW_users__<alias>__permission_profiles=

zeroclaw config set users.<alias>.principal_id <value>

export ZEROCLAW_users__<alias>__principal_id=

zeroclaw config set users.<alias>.uid <value>

export ZEROCLAW_users__<alias>__uid=

エントリ名は、principal_id で明示的に固定されていない限り、永続的な principal ID としても使われます。監査レコードは現在この ID をキーとしています。セッション、メモリ、承認はまだこの ID をキーとしていませんが（What this layer does not do (yet) を参照）、今後キーとするようになります。そのため、エントリの名前を変更しても後でデータが孤立しないように、同じ編集で principal_id に元の ID を設定してください。

OIDC

各[oidc.<alias>]エントリは、1つの発行者(issuer)との間の1つの信頼関係を表します。トークンの検証(オフラインのJWKSまたはRFC 7662のイントロスペクション)、クレームマッピング、有効期間の上限については、セクションリファレンスに記載されています:

zeroclaw config set oidc.<alias>.actor_claim <value>

export ZEROCLAW_oidc__<alias>__actor_claim=

zeroclaw config set oidc.<alias>.actor_claim_marks <value>

export ZEROCLAW_oidc__<alias>__actor_claim_marks=

zeroclaw config set oidc.<alias>.allowed_authorized_parties <value>

export ZEROCLAW_oidc__<alias>__allowed_authorized_parties=

zeroclaw config set oidc.<alias>.audience <value>

export ZEROCLAW_oidc__<alias>__audience=

zeroclaw config set oidc.<alias>.claim_path <value>

export ZEROCLAW_oidc__<alias>__claim_path=

zeroclaw config set oidc.<alias>.client_id <value>

export ZEROCLAW_oidc__<alias>__client_id=

zeroclaw config set oidc.<alias>.client_secret    # マスクされた入力、暗号化して保存

export ZEROCLAW_oidc__<alias>__client_secret=

zeroclaw config set oidc.<alias>.interactive_clients <value>

export ZEROCLAW_oidc__<alias>__interactive_clients=

zeroclaw config set oidc.<alias>.issuer <value>

export ZEROCLAW_oidc__<alias>__issuer=

zeroclaw config set oidc.<alias>.max_auth_lifetime_secs <value>

export ZEROCLAW_oidc__<alias>__max_auth_lifetime_secs=

zeroclaw config set oidc.<alias>.profile_map <value>

export ZEROCLAW_oidc__<alias>__profile_map=

zeroclaw config set oidc.<alias>.require_at_jwt <value>

export ZEROCLAW_oidc__<alias>__require_at_jwt=

zeroclaw config set oidc.<alias>.require_mfa <value>

export ZEROCLAW_oidc__<alias>__require_mfa=

zeroclaw config set oidc.<alias>.required_acr <value>

export ZEROCLAW_oidc__<alias>__required_acr=

zeroclaw config set oidc.<alias>.revalidation_secs <value>

export ZEROCLAW_oidc__<alias>__revalidation_secs=

zeroclaw config set oidc.<alias>.service_clients <value>

export ZEROCLAW_oidc__<alias>__service_clients=

zeroclaw config set oidc.<alias>.service_profile_map <value>

export ZEROCLAW_oidc__<alias>__service_profile_map=

zeroclaw config set oidc.<alias>.validation <value>

export ZEROCLAW_oidc__<alias>__validation=

登録中（提示用のトークンを取得中）

デーモンはトークンを検証するだけで、クライアントはトークンを IdP から取得します。CLI には、ブラウザを使用しない 2 つのフローが同梱されています:

# Device Authorization Grant（RFC 8628）を使ったインタラクティブなサインイン:
# prints a verification code to enter in any browser, waits for
# 承認後、アクセストークンを標準出力に書き込みます。
export ZEROCLAW_AUTH_TOKEN="$(zeroclaw oidc login corp)"

# 同じ方法をシステムブラウザ経由で実行: 認可コード + PKCE（S256のみ）
# with an RFC 8252 one-shot loopback listener. The mechanisms never
# 互いに逆戻りしてしまう。
export ZEROCLAW_AUTH_TOKEN="$(zeroclaw oidc login corp --browser)"

# ヘッドレスサービスプリンシパルの client_credentials 方式（要件：
# entryの client_secret):
export ZEROCLAW_AUTH_TOKEN="$(zeroclaw oidc token corp)"

進捗メッセージは標準エラー出力に出力され、標準出力にはトークンのみが出力されるため、どちらのコマンドもコマンド置換と組み合わせて使えます(oidc コマンドは、出力を行う可能性のある起動時の前処理より前に実行されます。OTPシードの開示も含みます)。トークンは保存されません。期限切れになる前に、RPCハンドシェイクで(または環境変数経由で)auth_token として提示し、その後で再登録してください。

クライアントが信頼するのは、エントリに記載された発行者（issuer）のみで、それ以外は信頼しません。ディスカバリドキュメントは、広告するエンドポイントを使用する前に、その発行者をそのまま正確に示している必要があります。認証情報を受け取るすべてのエンドポイントは、発行者と同じURLポリシーを満たさなければなりません（https、または完全一致するループバックホストに限りhttp）。リダイレクトは決して追従せず、レスポンスボディにはサイズ上限を設けます。トークンレスポンスは、空でないBearerアクセストークンを含む場合にのみ受け入れます。コンフィデンシャルクライアント（client_secretを持つエントリ）は、すべてのリクエストでHTTP Basic認証を用いて認証します。パブリッククライアントは、フォームにclient_idを送信します。

--browser は macOS と Linux ではシステムのブラウザを自動で開き、すべてのプラットフォームでサインイン URL も表示します。そのため、CLI を実行しているのと同じマシン上のブラウザで手動に開くこともできます（コールバックは CLI を実行しているホストのループバックポートに届きます）。ブラウザ起動ツールは CLI の標準入出力から切り離された状態で実行されるため、起動ツールが自身の stdout に出力した内容が結果を汚染することはありません。stdout に出力されるのはトークンのみです。

両方のコールバックアダプター（CLI のループバックリスナーとゲートウェイのコールバック）は、RFC 9207 の issuer チェックを強制します。iss パラメーターがフローを開始した issuer と一致しないレスポンスは、その code や error が処理される前に拒否されます。iss を含まないレスポンスは、このパラメーターが任意であり、すべての issuer がこれを送信するわけではないため、受け入れられます。コードの交換でアクセストークンと一緒に id_token が返される場合、その id_token は（issuer、audience、有効期限、このフローに紐づく nonce）をすべて検証された後、破棄されます。デーモンに提示されるのはアクセストークンのみです。エンロールメントクライアントは、ディスカバリー自体にも同様の警戒を適用します。設定された issuer と完全一致しない issuer（末尾のスラッシュを含む）を持つ .well-known/openid-configuration ドキュメントは、そこに記載されたいかなるエンドポイントも使用する前に拒否されます（RFC 8414 のチェック）。また、読み取るドキュメントのサイズには上限を設けています。これにより、悪意のある、あるいは壊れた issuer がフローを任意のエンドポイントへ誘導したり、上限のないボディを返したりすることはできません。

IdP の認証情報を持たないクライアント(Web ダッシュボードや zerocode)は、代わりにゲートウェイ経由で登録します。ゲートウェイは、設定されたエントリのクライアント認証情報を使って同じフローを中継します。GET /api/oidc/providers はエイリアスの一覧を返し、POST /api/oidc/{alias}/device/start と /device/poll はデバイスグラントを実行し、GET /oidc/login/{alias} はブラウザフローを実行します。ワンタイムのコールバックページは、トークンを postMessage(同一オリジンのみ)で開いたウィンドウに渡し、手動コピーをフォールバックとして用意しています。ゲートウェイは Cross-Origin-Opener-Policy: same-origin も送信するため、ポップアップが ID プロバイダーを経由して遷移すると window.opener が切断されます。そのため、現在のブラウザでは、そのページでの手動コピーが実際に機能する引き渡し方法であり、postMessage の仕様は Web ダッシュボードの後続対応のために用意されています。これらのルートは、登録が認証より前に行われる必要があるため認証なしで提供され、レート制限がかかっています。また、何の権限も付与せず、ユーザーが承認した後に IdP が付与したものを中継するだけです。設計の根拠と障害モードの一覧は、リポジトリ内の docs/security/oidc-browser-pkce-design-8289.md を参照してください。

レート制限は階層化されています。フローを開始するリクエスト（POST /api/oidc/{alias}/device/start、GET /oidc/login/{alias}、GET /oidc/callback）は、エンロールメント専用のゲートウェイのブルートフォース制限器のインスタンスにカウントされます。これは不正なペアリングトークンを制御するものと同じしきい値と同じロックアウトですが、独自の台帳で管理されます。そのため、エンロールメントからロックアウトされたアドレスでも、ペアリングや Webhook 署名の提示は可能であり、それらでロックアウトされても、エンロールメントはブロックされません。コールバックがカウントされるのは、非生産的な場合のみです。つまり、伴う state に対応する有効なフロー状態がない場合、発行者が一致しない場合、IdP がエラーを返した場合、認可コードがない場合、フロー進行中にエイリアスが削除された場合、またはコード交換に失敗した場合です。サインインを完了させるコールバックはコストがかからず、ゲートウェイの中継容量が使用中のため拒否したコールバックもコストがかかりません。これにより、同時にサインインする多数の人々が共有アドレスからロックアウトされることはありません。保留中フローストアが満杯のためにブラウザでのサインインが拒否された場合も、同じ理由で呼び出し元にコストはかかりません。プロバイダー一覧、デバイスポーリング、サインイン開始には、クライアントごとに1分あたり20リクエストのバジェットが適用されます。これは RFC 8628 の最小ポーリング間隔である5秒（1分あたり12回のポーリング）に余裕を持たせつつ、クライアントが連打できないようにするためのものです。ポーリングがカウントされるのは、IdP が slow_down を返した場合、またはデバイスコードを完全に拒否した場合です。これにより、不正なデバイスコードを中継するクライアントは、永続的にポーリングを続けるのではなく、既存のロックアウトに到達します。ゲートウェイ自身と IdP の間の転送失敗は呼び出し元に起因しないため、呼び出し元に課金されません。バジェットを超えた、またはロックアウトされたクライアントには、HTTP 429 と、遅延秒数を示す Retry-After が返されます。zerocode は、次のポーリングの前に少なくともその遅延時間を待機し、RFC の5秒増分より短くはしません（デバイスコードの残りの有効期間による上限は引き続き適用されます）。いかなる場合も、5秒に1回より速くポーリングすることはありません。すべてのクライアントを通じて、IdP への同時外向き中継は最大16件に制限されます。これにより、ゲートウェイが全クライアントに代わって IdP に対して行う処理の上限が決まります。保留中フローストアは同時に32件のブラウザサインインを保持し、1つのリモートクライアントが保持できるのは8件までです。これにより、サインインを開始しても完了させない呼び出し元が、それらのフローが有効な10分間、ストアを他のすべての利用者から奪うことはできません。ループバッククライアントは、他のゲートウェイ認証制限と同様に、クライアントごとのバジェットの対象外です。そのため、同一ホスト上にあるリバースプロキシは、クライアントごとの制限を実際の背後の呼び出し元に適用するために trust_forwarded_headers を有効にする必要があります。すべてのエンロールメントレスポンスには、ゲートウェイの no-referrer ポリシーに加えて Cache-Control: no-store と Pragma: no-cache が付与されます。これは、デバイスコードとアクセストークンがそれらのボディに含まれるためです。

zerocodeは、自身の設定から同じAPIを経由して登録（enrollment）を行います。[connection.wss] enroll_url はゲートウェイのHTTPオリジンを指定し、オプションでパスプレフィックスを含めることができます。ループバックアドレス（127.0.0.1、::1、localhost）を指す場合を除き、https://である必要があります。デバイスコードとその後のアクセストークンがこの経路を通るためです。また、リダイレクトは追従されないため、後から平文の経路が割り込むことはありません。

登録接続は、WSSの区間と同じ[connection.wss.tls]の信頼素材を使用します。すなわち、設定されたCA、skip_verify、および相互TLSのクライアント証明書です。この素材で証明書の検証が行われない場合、zerocodeはトークン受信後ではなく、デバイスコードを送信する前に確認を求めます。確認の対象は登録オリジン自体です。これは、その後セッションが接続するデーモンとは異なる場合があります。alwaysと回答すると、そのオリジンがskip_verify_routesに記録されます。非対話型の実行では確認を行う相手がいないため、登録はそこで停止します。

zerocodeは、すべてのポーリング待機時間をデバイスコードの残り有効期間に収まるよう切り詰め、有効期限切れ後はポーリングを行いません。有効期間が1時間を超える場合、またはポーリング間隔が5分を超える場合は、敵対的な応答に従ってスリープするのではなく、拒否します。アドバタイズされた間隔が0または1の場合は、RFC 8628のデフォルトである5秒に引き上げられます。これにより、ゲートウェイの応答によってzerocodeが1秒ごとのポーリングに陥ることはありません。そのようなポーリングは、クライアントごとの予算によってどのみち拒否されます。

受け取ったトークンは、そのセッションの間のみメモリ上に保持されます。

パーミッションプロファイル

zeroclaw config set permission_profiles.<alias>.admin <value>

export ZEROCLAW_permission_profiles__<alias>__admin=

zeroclaw config set permission_profiles.<alias>.allowed_agents <value>

export ZEROCLAW_permission_profiles__<alias>__allowed_agents=

zeroclaw config set permission_profiles.<alias>.allowed_tools <value>

export ZEROCLAW_permission_profiles__<alias>__allowed_tools=

zeroclaw config set permission_profiles.<alias>.config_write_paths <value>

export ZEROCLAW_permission_profiles__<alias>__config_write_paths=

zeroclaw config set permission_profiles.<alias>.grants <value>

export ZEROCLAW_permission_profiles__<alias>__grants=

プロファイルはデフォルト拒否です。リストにないリソースは拒否され、空のセレクターリストはインスタンスを一切許可せず、広範なアクセスには明示的な "*" セレクターまたは admin = true が必要です。複数のプロファイルは和集合でマージされます。cronジョブ、添付ファイル、パーソナリティファイル、エージェントごとのコスト照会、SOP作成では、allowed_agents = ["*"] は設定で定義されたエージェントのみを対象とし、リクエストで指定されたエイリアスは対象になりません。

ツールセレクタは、エージェントの組み立て時に、粗い粒度の権限付与の上で積集合として合成されます。モデルから利用するツール実行は tools = ["execute"] です。この権限を持たないプリンシパルは、allowed_tools に何が指定されていても（"*" を含む）、ツールのないセッションを受け取ります。この権限を保持している場合、制約付きプリンシパルが作成したセッションは、allowed_tools で指定されたツールのみを受け取ります（空のリストの場合はツールのないセッションになります）。これはエージェント自身のリスクプロファイルで許可されている範囲の上で適用されます。キューに入ったプロンプトが受理された後、認証情報の有効期限や失効を含めて、共有リゾルバーに対して認可が再チェックされます。現在のプリンシパルのセレクタは、静的ツール、遅延検索レジストリ、既にアクティブ化されたツール、およびピン留めされた MCP リソースコンテンツを絞り込みます。各ピン留めブロックは <server>__<uri> という名前で受理され、セレクタがその名前を指定しなくなると後続のプロンプトから取り除かれます。削除されたツールは再アクティブ化できません。再利用されたセッションは次のターンの前に絞り込まれ、再水和されたセッションは現在の権限で再構築されます。エージェントのセレクタは、ターンの前と再水和の前にチェックされます。

絞り込みによって既存のエージェントにツールが戻されることはありません。権限付与を拡大した後は、拡大されたツールの範囲を受け取るために新しいセッションを作成してください。エージェントには、新しい設定スナップショットや独立したプリンシパルポリシーのキャッシュは保存されません。

Deferred MCP指示は、残りの読み込み可能なツールから導出され、tool_search が公開されている場合にのみ表示されます。プリンシパルがオンデマンドで有効化するには、tool_search と指名された遅延MCPツールの両方が必要です。ヘルパーが暗黙的に付与されることはありません。許可された mode = "always" のMCPツールは事前有効化され、ヘルパーなしでも引き続き呼び出し可能です。

プリンシパルのツールセレクタまたはエージェントセレクタのいずれかが制限されている場合、delegate（bounded および independent）、spawn_subagent、execute_pipeline は、これらのツールをラップするスキルエイリアスを含めて利用できません。これらのネストされたパスは、現在の両方のプリンシパル上限をまだ持っていません。通常の親ターンは引き続き利用できます。管理者プリンシパル、および両方のセレクタが "*" に設定されたプリンシパルは、エージェントに設定されたネスト機能を引き続き保持します。

既存の8引数Rust コンストラクタ Agent::from_live_config_with_tui_env は引き続き利用できます。RPC は追加の from_live_config_with_tui_env_and_principal_tools コンストラクタを使用し、プロンプトの受け付け時に共有リゾルバの権限付与を再適用します。

そのコンポジションでは、エージェントのツールへのすべての経路はカバーされていません。cron ジョブと SOP の作成は、エージェントセレクターのみを確認しています。cron の権限を持つ制約付きプリンシパルは、そのエージェント向けの shell ジョブを作成したり、既存のエージェントジョブに新しいプロンプトを設定してトリガーしたりできます。SOP の作成または更新の権限を持つプリンシパルは、後でトリガーによって実行される手順を保存できます。cron および SOP 作成の権限は、エージェントのツールに対する権限として扱ってください。

Breaking change: リモートのWSSには認証が必要になりました

リモートのWSS接続では、今後、initialize で auth_token を提示する必要があります。認証なしのリモートフォールバックはありません。

[wss] リスナーが有効で、認証情報の経路が存在しない設定（[oidc.<alias>] がなく、ペアリング済みトークンもなく、gateway.require_pairing = false の状態）は、設定の検証で拒否されるため、サポートされているどのインターフェースでも保存できません。この形の設定がすでにディスク上にある場合でも、起動は成功します。デーモンは起動しますが、リスナーはリモートからのすべてのハンドシェイクを拒否します。オペレーターが設定を修復するにはデーモンを起動できる必要があるため、この設定の読み込みは拒否されません。

[oidc.<alias>]、[users]、[permission_profiles] セクションが無効な場合は別のケースです。この場合は認可ポリシー自体がコンパイルできないため、デーモンは全拒否の accepted 状態をインストールし、セクションが修復されてリロードされるまでその旨をログに記録します。この状態では、リモート接続とローカル接続のどちらでも、デーモン自身の uid を含むすべてのプリンシパルが拒否されます。そのため、修復は上記の Recovery で説明しているディスク上の修復作業で行う必要があります。

Japanese translation of the string, keeping “zerocode” unchanged as it is a project name:

既存のリモート zerocode ユーザー向けの移行

1. ゲートウェイとペアリングして、ベアラートークンを取得してください。

2. 設定ファイルで zerocode にトークンを指定する場合:

   [connection.wss]
   uri = "wss://daemon.example.com:9443"
   auth_token = "zc_..."
   

   またはシェルのZEROCLAW_AUTH_TOKEN環境変数で指定できます。この環境変数は設定ファイルの値より優先され、認証情報をファイルに残さずに済みます。

   または、それを含むファイルを指定して:

   [connection.wss]
   uri = "wss://daemon.example.com:9443"
   auth_token_file = "/etc/zeroclaw/zerocode-bearer"
   

   優先順位は ZEROCLAW_AUTH_TOKEN、auth_token_file、auth_token の順です。Unix のパーミッションビットを持つプラットフォームでは、他のアカウントが読み取れる参照先ファイルは使用されず、警告を出してスキップされます。その場合、同じ順序で次のソースが適用されます。それ以外の環境では、ファイルの ACL だけが唯一の保護手段となります。

   環境変数の使用を推奨します。トークンを代わりに設定ファイルに保存する場合、zerocode はそのファイルを所有者のみ読み書き可能（0700 の設定ディレクトリ内で 0600）にして書き込み、以前に作成されたファイルのパーミッションも修正します。これは Unix のパーミッションビットを持つプラットフォームの場合です。パーミッションビットがないプラットフォームでは、ディレクトリの ACL だけが保護手段となるため、そのファイルは機密情報として扱ってください。

OIDCアクセストークンも、auth_provider = "oidc.<alias>" を使って同じように動作します。

ゲートウェイの HTTP API

ゲートウェイの設定およびオンボーディング用ルート（/api/config*、/api/quickstart/*、/api/channels/bind）は、認証を構造的に強制しています。ルートレイヤーのミドルウェアが1つでルートグループ全体を保護するため、個々のハンドラーが認証チェックを持つことも、そのチェックを忘れることもありません。このミドルウェアは、同じプロバイダーレジストリとリゾルバーを通じて、RPC経路と同じプリンシパルモデルを扱います:

• paired bearer (Authorization: Bearer zc_...) は、従来どおり完全なアクセス権を持つ共有オペレーターに解決されます。拒否時は従来の 401 形式を維持します。
• OIDC bearer を X-ZeroClaw-Auth-Provider: oidc.<alias> ヘッダーとともに提示すると、そのプロバイダーによって検証され、スコープ付きのプリンシパルに解決されます。プロバイダーの選択は明示的に行われ、RPC ハンドシェイクの auth_provider フィールドと同じ仕組みです。指定されたプロバイダーによる拒否が最終的な判断となり、プロバイダー間のフォールバックは一切行われません。
• CORSのプリフライトリクエスト（OPTIONS）は、これまでと同様に認証なしで通過します。GET、HEAD、POST、PUT、PATCH、DELETE以外のメソッドはすべて拒否されます。

スコープ付きプリンシパルの Config 権限は2段階で適用されます。ルートレイヤーは HTTP メソッドごとに粗い下限を設けており、読み取りには read が必要で、それ以外には create、update、delete のいずれか少なくとも1つが必要です。そのため、読み取り専用のプリンシパルが変更系のハンドラに到達することはありません。各変更系ハンドラは、最初の副作用が発生する前に書き込みセット全体を認可します。書き込みセットとは、その変更によって永続化されるすべての設定パスであり、各パスは設定に対する作用によって分類されます（新たに作成するパスは create、削除するパスは delete、それ以外は update）。そのうえでプロファイルの config_write_paths セレクタと照合されます。分類は HTTP メソッドではなく操作に従います。POST /api/config/map-key によるマップキーの作成や、新しいエイリアスの下での PUT による暗黙的な作成には create が必要です。JSON Patch の remove と DELETE /api/config/map-key には delete が必要です。名前の変更には、移動元に対する delete と移動先に対する create が必要です。削除やリネームのカスケードによって他の場所で書き換えられる参照も、書き込みセットに含まれます。書き込みセットの中に1つでも未認可のメンバーがあれば、バッチやカスケードを含む変更全体が拒否され、何も書き込まれません。書き込みセットを事前に列挙できない操作（ファイルのスキーマ移行や Quickstart の適用など）には * セレクタが必要です。永続化の境界では、書き込まれようとしているパスをハンドラが認可したものと照合し直すため、ハンドラが認可された範囲を超えて永続化することはできません。

ポリシーが変わるのは、この永続化の境界においてのみです。設定を書き込むハンドラーは、その設定からコンパイルした認可状態を次の受理済みリビジョンとして公開します。すべてのリクエストは、現時点の受理済みスナップショットに対して検証・解決されます。リクエストパス上ではポリシーを再コンパイルしないため、並行する永続化より前に設定を読み込んだリクエストが、新しいポリシーを古いポリシーで上書きしてしまうことは決して起こりません。プロバイダーの検証設定、ロスター、またはプロファイルに対して永続化された変更は、次のリクエストから有効になります。デーモン自身のRPCサーフェスは独立したライブ設定を保持しており、ゲートウェイの書き込みフラグがトリガーするリロードを通じて同じ状態に到達します。その他のゲートウェイのサーフェスは、ハンドラーごとにペアリングチェックを維持しており、この層の採用は後続の作業で行います。

認証情報のライフサイクル

• 有効期限切れは、期限の時点で接続の認可を終了します。クライアントは新しいトークンで再初期化します。
• イントロスペクションの再検証: OIDCイントロスペクションのIDには再検証の期限があり、期限を過ぎると、クライアントが再初期化(IdPに対して再検証を行う)するまで、次の操作は拒否されます。
• ペアリングの取り消しは、接続の次の操作の前に適用されます。
• ログのサブスクリプション: 開いているlogs/subscribeストリームは配信のたびに再検証され、認証情報の有効期限が切れた場合、ペアリングが取り消された場合、またはプリンシパルがLogs:Readを失った場合、その最初の配信以降に終了します。
• ポリシーの変更: 設定の保存時に [oidc]、[users]、[permission_profiles]、security.trust_daemon_uid のいずれも変更されていない場合、すべてのバインディングはそのまま維持されます。これらのいずれかが変更されると、新しいポリシーが公開されます。ネイティブトークン接続およびローカル接続は、その新しいポリシーに対してその場で再解決されます。ただし、デーモンは OIDC ベアラートークンを保持しないため、OIDC 接続での次の操作は、クライアントが再初期化されるまで拒否されます。
• tui_id/tui_sig による再接続の仕組みは継続性のみを担います。TUI のレジストリ上の ID を保持しますが、いかなる権限も付与しません。すべての initialize は認証情報を再提示します。

セッション分離

すべてのスコープ付きプリンシパルが作成するセッションは、ライブストアとディスク上(チャットバックエンドおよびACPストア)の両方で、そのプリンシパルのIDが刻印されます。スコープ付きプリンシパルは、自身のセッションのみを閲覧・操作できます。一覧は絞り込まれ、読み取りと変更操作では、「存在しないか、所有されていない」という単一の統一された拒否応答が返されるため(存在の有無を探ることはできません)、破壊的な削除は所有者条件付きのストレージ文として実行されます。また、進行中の承認は、それが発生したセッションの所有者に対してのみ解決されます。この変更以前に作成されたセッション、またはアンスコープ接続によって作成されたセッションには所有者がありません。これらは、アンスコープ接続からは引き続き完全に閲覧可能であり、スコープ付きプリンシパルからは不可視のままです。

認証済みのすべてのプリンシパルは PRIVATE メモリを持ちます。メモリ操作はプリンシパルごとの plane を読み書きし、その plane の所有者はすべてのストレージ文に含まれて、agent、namespace、tenant の各次元と組み合わされます（同じキーでも、2つの agent の下では2つの行になります）。plane はプリンシパルのアイデンティティに従い、管理者バイパスには従いません。名前付き管理者のメモリは、その管理者自身の private plane です。そのため、ユーザーを昇格または降格しても、そのユーザーのノートが見えなくなったり、書き込み先が変わったりすることはありません。デフォルトで shared plane に属するのは、未認証の共有オペレーターだけです。管理者バイパスを持つ呼び出し元は、memory/* リクエストで plane = "shared" を明示的に指定できます。この指定は監査されます。スコープ付きプリンシパルはこれを指定できません。

この2つのプレーンは双方向で互いに干渉できません。共有書き込みはプライベート行のストレージキーを指定することも、プライベート行を上書きすることもできません。プライベート書き込みが共有行を変換することはありません。通常のエクスポートとMarkdownスナップショットには共有行のみが含まれます。従来の一括パージの対象も共有行のみです。プライベート行のエクスポートとパージは、所有者情報を伴う操作を通じて行われます。

principal が作成したセッションのメモリハンドルは、そのセッションの生存期間中ずっと、その principal のプライベートプレーンに固定されます。後からセッションをプロンプトするのが誰であっても同様です（管理者が回収済みのセッションを復元する場合も、耐久性のあるオーナーのプレーン上で復元されます）。そのため、スコープ付きセッション内のメモリツールとターンごとのリコールは、共有プレーンに一切アクセスしません。スコープ付きセッションに共有プレーンを開放するグラントは存在しません。プライベートへの書き込みは、共有への書き込みと同じコンテンツスキャンおよびポリシーゲートを通過します。メモリ監査が有効な場合、プライベート操作はスコープ全体を含めて監査されます。principal をサポートしないメモリバックエンド（現時点では markdown、lucid、postgres、qdrant）では、プライベートメモリはスコープを黙って解除するのではなく、明確な拒否によってフェイルクローズします。スコープ付きセッションの場合、これはそのメモリツールが拒否されることを意味します。

[security.nevis] からの移行

Nevis IAM 連携は削除されました。これは認証経路に一度も組み込まれておらず、有効化しても誰も認証されていなかったため、廃止しても稼働中の動作は変わりません。古いconfig.tomlが引き続き読み込めるよう、この設定テーブルは引き続き受け付けられます。デーモンは読み込み時にテーブル内のすべての値を破棄し、代替先を示す警告を1件ログに出力します。そして次回の保存時に、全体保存でも、CLI、ダッシュボード、RPCが単一の編集に使う増分保存でも、config.tomlからそのテーブルを削除します。この削除はそのテーブルのみに影響し、コメントや他のセクションはバイト単位でそのまま保持されます。自動変換は行われません。代替スタックには、古いテーブルが保持していなかった値（audience、プロファイルの権限付与）が必要だからです。

アップグレード前に、config.toml を保護された場所にコピーしてください。アップグレード後は、保存のたびに config.toml.bak がファイルの隣に書き込み中だけ作成され、書き込みが永続化された後に削除されます。そのため .bak は恒久的なバックアップにはなりません。自分で保存したコピーには、廃止されたテーブルが残っており、設定されていた場合は平文の client_secret も含まれるため、それらのコピーはシークレット情報として扱ってください。不要になったら、IdP 側で Nevis のクライアント資格情報を失効させてください。

Field by field:

Validate before you restart, so a typo does not lock everyone out (see Recovery under Local connections for the way back if it does). Two routes do that:

Wait, I need to translate to Japanese. Let me produce the translation.

再起動する前に検証すると、設定のタイプミスによって全員がロックアウトされるのを防げます（タイプミスが起きた場合の復旧方法は、Local connections の Recovery を参照してください）。これを行う方法は2つあります:

• デーモンの RPC 設定メソッド（zerocode の設定エディタ）を通じて、新しい [oidc.<alias>] と [permission_profiles] のエントリを書き込みます。デーモンは、何も保存・反映される前に認可セクションを検証します。そのため、存在しない profile_map のターゲットや audience の欠落は、理由とともに拒否され、以前のポリシーが引き続き有効になります。

• config.toml を手で編集した場合は、先に CLI から ZEROCLAW_AUTH_TOKEN="$(zeroclaw oidc login <alias>)" を実行してください。このコマンドは編集後のファイルを読み込み、検証に通らない [oidc.<alias>] エントリ(issuer、audience、検証モード、クライアントフィールド)を拒否します。検証に成功すると、設定済みのクライアントで IdP に実際にサインインするため、デーモンが再起動してその設定を使う前に、issuer、クライアント ID、シークレットが正しいことを確認できます。

  ただし、このチェックはエントリ自体を対象とするもので、profile_map の参照先は検証しません。[permission_profiles] に存在しない名前を指す profile_map の値は、デーモンによってのみ検出されます。デーモンはポリシーのコンパイルを拒否し、Recovery に記載されている全拒否状態で起動します。そのため、再起動前に名前を目視で確認するか、RPC 経由の手段を使ってください。

リモート接続で認証情報が提示されない場合は、すべて拒否されます。どちらの経路でも接続は開かれません。

ロールバックは設定データの操作であり、コードの巻き戻しとは異なります。バイナリを元に戻すと古い型は復元されますが、config.toml から既に削除されたテーブルは、どの操作によっても復元されません。アップグレード前に取得した保護済みのコピーを戻すか、テーブルを手動で再追加してください。今回の廃止ではスキーマバージョンは変わらないため、ダウングレードしたバイナリは移行手順なしで復元後のファイルを読み込めます。

この層がまだ行わないこと

統合とガバナンスは共有プレーンの行を導出するもので、プライベートセッションには実行されません。また、別のプリンシパルのプライベートメモリへの管理者アクセスは、現時点で公開された経路がありません（既定で拒否）。sops/runs と sops/run-detail は、実行したエージェントに関係なく、Sops:Read を保持するプリンシパルに対して、すべての手順の実行履歴を返します。これは cron の履歴とは異なります。Gateway の HTTP ルートは既存のペアリングチェックを維持し、チャネルの ID はこのプリンシパルモデルに解決されません。

security.trust_daemon_uid = true（デフォルト）であり、ポリシーがコンパイルされる場合、Unix ソケット上のデーモン自身の uid は完全なアクセス権を保持します。そのため、[users] ユーザー一覧がなく、認証セクションが有効な単一オペレーター構成のインストールは、従来どおり動作します。

権限プロファイルは、プリンシパルが RPC 経由で実行できる操作を制限します。ただし、プリンシパルがエージェントに実行させるコードを隔離するものではありません。セッションのターン、cron ジョブ、SOP のステップはデーモンのアカウントで実行されます。Unix では、そのコードはデーモンの uid としてローカルソケットに接続できます。security.trust_daemon_uid = true（デフォルト）の間、この uid は共有オペレーターとして扱われます。それ以外の場合は、その uid に対応付けられたロスターのエントリが適用されます。ロスターがない Windows では、パイプを介して共有オペレーターとして扱われます。また、そのコードは config.toml を編集でき、デーモンは次回の再読み込みまたは再起動時にその変更を適用します。security.trust_daemon_uid = false を設定しても、これらの動作は変わりません。セッション、cron、または SOP の実行や作成は、オペレーターアクセスを委ねても信頼できるプリンシパルにのみ許可してください。エージェントプロセスがソケットと config.toml に触れられないようにする OS レベルの隔離だけが、このコードを実際に分離できます。

一部の設定パス自体が権限を持つため、広範な config_write_paths の付与は、検証済みの末端設定のみを対象とする場合を除き、オペレーターアクセスとして扱ってください。例えば:

• permission_profiles、users、oidc、security、または gateway.paired_tokens に書き込める権限を持つプリンシパルは、あらゆる権限を自分自身に付与できてしまいます;
• agents、risk_profiles、cron、channels、またはプロバイダー設定に書き込める者は、どのエージェントが実行されるか、どのツールを使うか、どこを読み書きできるかを変更できます;
• mcp、mcp_bundles、または tunnel.custom.start_command に書き込める者は、デーモンアカウントが起動するプログラムを選択できます。

Config:Update は、ディスク上の config.toml の内容を適用する config/reload も付与します。

zerocode のリモートディレクトリピッカーは、デーモンのファイルシステムルートで開きます。オペレーター権限を持たないプリンシパルは、/ の読み取りを許可するポリシーを持つ有効なエージェント（ワークスペース限定ではないエージェントなど）を経由する場合にのみ、そこを一覧表示できます。それ以外のそのようなプリンシパルに対しては、許可されたルート内で開かれるまで、ピッカーがそこでの拒否を報告します。