policy コマンド

policyコマンドは、KovaでAPI鍵に適用するポリシーを管理するためのコマンドです。ポリシーを使用することで、AIエージェントの操作を制限し、セキュリティを強化できます。

構文

kova policy <subcommand> [options]

サブコマンド一覧

policy create

JSONファイルからポリシーを作成します。作成されたポリシーは、kova init の AI 接続設定で新規 API 鍵に適用するか、既存 API 鍵には kova key rotate でロールアウトできます。

構文

kova policy create --file <path> [--allow-outside-cwd]

オプション

ポリシーファイル制約

ポリシーファイルには以下の制約があります:

ポリシーファイル形式

ポリシーは フラットな制約フィールドではなく rules[] 配列 で定義します。ルール type は snake_case です。

allowedChains / allowedTokens / maxAmount / requireApproval といった camelCase のフラット形式は kova では使えません。チェーン制限は allowed_chains、トークン制限は spending_limit の (chain, token) ペアで表現します。

ポリシー制約の例

基本的なポリシー（チェーン制限 + 有効期限）:

{
  "id": "policy_basic",
  "name": "基本ポリシー",
  "version": 1,
  "created_at": "2026-07-07T12:00:00.000Z",
  "action": "deny",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:8453", "eip155:1"] },
    { "type": "expires_at", "timestamp": "2027-01-01T00:00:00Z" }
  ]
}

厳格なポリシー（累積上限 + チェーン制限）:

{
  "id": "policy_strict",
  "name": "厳格なポリシー",
  "version": 1,
  "created_at": "2026-07-07T12:00:00.000Z",
  "action": "deny",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:8453"] },
    { "type": "spending_limit", "chain": "eip155:8453", "token": "USDC", "daily_limit": "10" },
    { "type": "expires_at", "timestamp": "2027-01-01T00:00:00Z" }
  ]
}

テストネット専用ポリシー:

{
  "id": "policy_testnet",
  "name": "テストネットポリシー",
  "version": 1,
  "created_at": "2026-07-07T12:00:00.000Z",
  "action": "deny",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:11155111", "eip155:84532"] },
    { "type": "spending_limit", "chain": "eip155:84532", "token": "USDC", "daily_limit": "100" },
    { "type": "spending_limit", "chain": "eip155:84532", "token": "NATIVE", "daily_limit": "0.1" }
  ]
}

使用例

基本的な使用:

kova policy create --file ./policies/basic-policy.json

出力例:

{
  "ok": true,
  "data": {
    "policy": {
      "id": "policy_basic",
      "name": "基本ポリシー",
      "executable": false,
      "registered": true
    }
  }
}

カレントディレクトリ外のファイルを使用:

kova policy create --file ~/policies/strict-policy.json --allow-outside-cwd

重要な注意点

1. ファイルパス: デフォルトではカレントディレクトリ内のファイルのみ許可されます。外部ファイルを使用する場合は--allow-outside-cwdを指定してください。
2. CAIP-2形式: allowed_chains の chain_ids は CAIP-2 形式（eip155:8453）で指定してください。
3. トークン制限: 独立した allowed_tokens ルールはありません。許可トークンは spending_limit の (chain, token) ペアで定義します（1 件でも spending_limit があると whitelist として fail-closed に動作）。
4. 金額の単位: spending_limit の daily_limit / monthly_limit は人間可読形式（"100" = 100 USDC）で指定してください。

policy list

作成済みのポリシー一覧を表示します。

構文

kova policy list

オプション

このサブコマンドにはオプションはありません。

使用例

kova policy list

出力例:

{
  "ok": true,
  "data": {
    "policies": [
      {
        "id": "policy-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "基本ポリシー",
        "createdAt": "2026-03-28T00:00:00Z"
      },
      {
        "id": "policy-b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "厳格なポリシー",
        "createdAt": "2026-03-27T00:00:00Z"
      }
    ]
  }
}

ポリシーが存在しない場合:

{
  "ok": true,
  "data": {
    "policies": []
  }
}

policy update

既存ポリシーの rules を対話的に編集します。owner-only 操作のため TTY と passphrase 入力が必要で、agent（非対話）モードからは実行できません。

対話エディタでは以下の 4 種類のルールを追加・編集・削除できます:

• spending_limit — 累積上限
• allowed_chains — 許可チェーン制限
• expires_at — ポリシー有効期限
• sign_allowlist — 署名許可リスト（permit / typed-data / message）

max_value は executable policy として kova init で自動生成されるため、対話エディタの対象外です。変更する場合は policy remove → policy create で作り直してください。

構文

kova policy update [--id <id>]

オプション

policy update は常に対話モードで起動します（非対話の rule 操作フラグは現状未提供）。

対話フロー

実行すると以下の選択肢が表示されます。

Apply changes? で Yes を選ぶと変更が適用されます。No または途中での Ctrl+C キャンセルでは何も書き換えません。

動作（atomic update）

1. 対象ポリシーを参照中の API 鍵 ID を一覧から収集
2. ポリシー削除 → 編集後ポリシーの再作成を順に実行（policy.version は +1）
3. 再作成が失敗した場合、元のポリシーの再 create で復元を試みる（復元失敗時は重大エラーとして OWS_ERROR を返す）
4. 成功時、参照中の各 API 鍵に対して新しい policy hash を再記録
5. API 鍵 (id, secret, expiry) と ~/.kova/spend.json の累積カウンタは触らない

使用例

kova policy update --id policy-a1b2c3d4-e5f6-7890-abcd-ef1234567890

成功時の出力例:

{
  "ok": true,
  "data": {
    "updated": {
      "id": "policy-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "基本ポリシー",
      "rulesCount": 2
    }
  }
}

キャンセル時の出力例:

{
  "ok": true,
  "data": {
    "updated": false,
    "cancelled": true
  }
}

重要な注意点

1. owner-only: 非対話（agent / 非 TTY）環境からは実行できません。passphrase が一致しない場合は OWS_ERROR を返します（message に “passphrase” を含む）。
2. version は自動 +1: 編集ごとに policy.version が単調増加し、参照中 API 鍵の policy hash も再記録されます。tampering 検出を担保するため、再記録に失敗した場合はポリシー更新自体を rollback します。
3. 累積カウンタはリセットされない: ~/.kova/spend.json には触らないため、spending_limit の日次/月次累積はそのまま保持されます。
4. 編集可能ルール: 対話エディタでは spending_limit / allowed_chains / expires_at / sign_allowlist の 4 種類を編集できます。max_value を変更する場合は policy remove → policy create の作り直しが必要です。

spending_limit ルール

spending_limit は ApiKeySigner（agent）経路でのみ評価される累積上限ルールです。signer.enforce() が事前評価し、上限超過時は fail-closed で POLICY_DENIED となります。

スキーマ

1 ルール = 1 (chain, token) の組。複数の chain / token を制限するには spending_limit ルールを複数並べます。

例

{
  "type": "spending_limit",
  "chain": "eip155:8453",
  "token": "USDC",
  "daily_limit": "100",
  "monthly_limit": "1000"
}

複数 chain / token を組み合わせる例:

"rules": [
  { "type": "spending_limit", "chain": "eip155:1",   "token": "USDC",   "daily_limit": "100",  "monthly_limit": "1000" },
  { "type": "spending_limit", "chain": "eip155:137", "token": "USDC",   "daily_limit": "50",   "monthly_limit": "500"  },
  { "type": "spending_limit", "chain": "eip155:1",   "token": "NATIVE", "daily_limit": "0.05", "monthly_limit": "0.5"  }
]

whitelist 挙動（fail-closed）

spending_limit ルールが 1 つでも存在するポリシーは whitelist として動作 します。送金対象の (chain, token) に一致するルールが無い場合は、上限未設定として素通しせず POLICY_DENIED で拒否されます。許可したい token ごとに spending_limit ルールを追加してください。

累積記録

• 累積値は ~/.kova/spend.json に token 別・chain 別・base-unit BigInt 文字列 で記録されます（USD 換算は使いません）。
• ERC-20 calldata 内の amount を累積記録する処理は現時点で未対応です。send の --token で指定された amount のみが累積されます。

評価対象の entry point

spending_limit は send / call / sign（tx entry points）でのみ評価されます。sign_message / sign_typed_data / sign_hash / sign_authorization は対象外です（署名系は sign_allowlist ルールが担当）。

注: 以前存在した kova pay（x402 マイクロペイメント）は v0.x から削除されました。

policy remove

ポリシーを削除します。削除されたポリシーに関連付けられたAPI鍵は、ポリシー制約なしで動作するようになります。

構文

kova policy remove --id <id>

オプション

使用例

kova policy remove --id policy-a1b2c3d4-e5f6-7890-abcd-ef1234567890

出力例:

{
  "ok": true,
  "data": {
    "message": "Policy 'policy-a1b2c3d4-e5f6-7890-abcd-ef1234567890' has been removed successfully."
  }
}

重要な注意点

1. 参照中の API 鍵があれば削除拒否: そのポリシーを参照している API 鍵が 1 つでも存在する場合、policy remove は POLICY_DENIED で削除をブロックします。なお kova key rotate は旧鍵の policy_ids をそのまま新鍵に引き継ぐため、ローテーションだけでは参照は外れません。CLI から API 鍵を直接 revoke する手段は現状提供されていないため、運用を新ポリシー側に切り替えてから OWS ダッシュボード等で旧鍵を revoke し、その後 policy remove を実行してください。新規エージェントを別ポリシーセットで立て直したい場合は kova init を実行できます（既存ポリシーは別途整理が必要）。

   {
     "ok": false,
     "error": {
       "code": "POLICY_DENIED",
       "message": "Policy \"policy-...\" is referenced by API key \"api-...\". Rotate the API key first (\"kova key rotate\"), or create a new agent with \"kova init\"."
     }
   }

2. 復元不可: 削除されたポリシーは復元できません。必要に応じて再作成してください。
3. rules を編集したいだけなら policy update: ポリシーを丸ごと作り直す代わりに、対話的に rule を編集できる kova policy update も利用できます。

よくあるエラーと対処法

INVALID_PARAMS

エラーメッセージ（ファイルが大きすぎる）:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Policy file exceeds maximum size of 256KB."
  }
}

対処法:

• ポリシーファイルのサイズを256KB以下に削減する
• 不要な制約を削除する

エラーメッセージ（無効なチェーン）:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid chain ID 'base'. Use CAIP-2 format (e.g., 'eip155:8453')."
  }
}

対処法:

• allowed_chains の chain_ids を CAIP-2 形式（eip155:8453）に修正する
• サポートされているチェーンを確認する

OWS_ERROR

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "OWS_ERROR",
    "message": "Failed to create policy: Invalid JSON format."
  }
}

対処法:

• ポリシーファイルのJSON形式を確認する
• オンラインJSONバリデーターで構文をチェックする
• 禁止キー（__proto__, prototype, constructor）を使用していないか確認する

FILE_NOT_FOUND

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Policy file not found: ./policies/unknown.json"
  }
}

対処法:

• ファイルパスを確認する
• カレントディレクトリ外のファイルを使用する場合は--allow-outside-cwdを指定する
• ファイルが存在することを確認する（ls -la ./policies/）

POLICY_DENIED

エラーメッセージ（参照中の API 鍵を持つポリシーを削除しようとした場合）:

{
  "ok": false,
  "error": {
    "code": "POLICY_DENIED",
    "message": "Policy \"policy-...\" is referenced by API key \"api-...\". Rotate the API key first (\"kova key rotate\"), or create a new agent with \"kova init\"."
  }
}

対処法:

• 先に kova key rotate で参照中の API 鍵をローテーションする
• もしくは kova init で新しいポリシー + API 鍵セットを構築し、旧ポリシーを参照する API 鍵を整理する

OWS_ERROR（passphrase 不一致）

エラーメッセージ（policy update などの owner-only 操作で passphrase が一致しない場合）:

{
  "ok": false,
  "error": {
    "code": "OWS_ERROR",
    "message": "Master wallet passphrase mismatch"
  }
}

対処法:

• 正しい passphrase を入力する
• passphrase を忘れた場合は kova wallet reset-passphrase で seed phrase から復旧する
• 詳細は error-codes.md を参照

ルール type 一覧

サポートされているチェーン（allowed_chains / spending_limit.chain）:

• eip155:1 - Ethereum Mainnet
• eip155:8453 - Base
• eip155:137 - Polygon
• eip155:42161 - Arbitrum
• eip155:10 - Optimism
• eip155:11155111 - Sepolia
• eip155:84532 - Base Sepolia
• eip155:80002 - Polygon Amoy
• eip155:43114 - Avalanche
• eip155:43113 - Fuji

主なトークン（spending_limit.token）:

• NATIVE - ネイティブトークン（ETH / POL 等ではなく予約語 NATIVE）
• USDC, USDT, JPYC 等 - ERC-20 シンボル

requireApproval に相当する機能は kova にはありません。高リスク操作は owner-only（passphrase 必須）と agent モード（policy-gated）の分離で制御します。

実用的なポリシー例

マイクロペイメント用ポリシー

小額送金のみ許可する構成:

{
  "id": "policy_micro",
  "name": "マイクロペイメントポリシー",
  "version": 1,
  "created_at": "2026-07-07T12:00:00.000Z",
  "action": "deny",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:8453"] },
    { "type": "spending_limit", "chain": "eip155:8453", "token": "USDC", "daily_limit": "1" }
  ]
}

開発用ポリシー

開発環境用（テストネットのみ）:

{
  "id": "policy_dev",
  "name": "開発用ポリシー",
  "version": 1,
  "created_at": "2026-07-07T12:00:00.000Z",
  "action": "deny",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:11155111", "eip155:84532"] },
    { "type": "spending_limit", "chain": "eip155:84532", "token": "USDC", "daily_limit": "100" },
    { "type": "spending_limit", "chain": "eip155:84532", "token": "NATIVE", "daily_limit": "0.1" }
  ]
}

本番用ポリシー

本番環境用（高セキュリティ）:

{
  "id": "policy_prod",
  "name": "本番用ポリシー",
  "version": 1,
  "created_at": "2026-07-07T12:00:00.000Z",
  "action": "deny",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:8453"] },
    { "type": "spending_limit", "chain": "eip155:8453", "token": "USDC", "daily_limit": "50", "monthly_limit": "500" },
    { "type": "expires_at", "timestamp": "2027-01-01T00:00:00Z" },
    { "type": "sign_allowlist", "messagePattern": "^Login:" }
  ]
}

関連コマンド

• key - ポリシーを適用したAPI鍵を作成・失効
• wallet - ウォレットを作成・管理
• send - 送金（ポリシー制約が適用される）
• error-codes - POLICY_DENIED / OWS_ERROR 等のエラー詳細

次のステップ

• ポリシー作成後: kova init の AI 接続設定で新規 API 鍵にポリシーを適用するか、key rotate で既存 API 鍵に反映しましょう
• ポリシー編集: policy update で spending_limit ルールを対話的にメンテナンスできます
• AIエージェント統合: AIエージェント統合ガイドでポリシーを使った安全なエージェント運用を学びましょう
• セキュリティ: セキュリティガイドでポリシーのベストプラクティスを確認しましょう
• 署名制御: sign_allowlist ルールで permit / typed-data / message の署名範囲を制限できます