use-link-identity

Link アイデンティティ

これらのコマンドはベータ版で、プレビューフラグなしで link-cli identity --help に表示されます。サービスが Link アテステーションまたは署名済みユーザークレームを受け付ける場合に使用します。

サービスからの要求	コマンド	JSON フィールド → HTTP ヘッダー
Link Agent Attestation Token（AAT）。多くの場合、WWW-Authenticate: PrivateToken を通じて要求されます	identity attestations pop	authorization → Authorization
署名済みクレーム。多くの場合、WWW-Authenticate: Identity-Presentation を通じて要求されます	identity credentials present	presentation → Identity-Presentation

AAT はユーザークレームを開示せずに、Link による発行を証明します。プレゼンテーションは選択したクレームを開示し、対象者とノンスに対して、クレデンシャルの保持者鍵を所持していることを証明します。サービスが両方を要求する場合は、両方のヘッダーを送信してください。

セットアップと取り扱い

Link Agent Wallet v0.27.0 以降を使用してください。link-cli --version で確認し、バージョンが古いかインストールされていない場合は、npm install -g @stripe/link-cli@latest でインストールまたは更新してください。LINK_IDENTITY_COMMANDS フラグは不要です。ウォレットのセットアップを参照し、create-payment-credential スキルの認証ガイダンスを再利用してください。

• アイデンティティコマンドは CLI から利用でき、MCP ツールからは利用できません。
• Link 認証が必要なのは request のみです。list、pop、present はローカルファイルを使用します。リクエストはパスとメタデータを返し、pop と present は証明情報を返します。
• --format json で標準出力を取得し、JSON パーサーまたは jq でプログラムから解析して、証明情報をそのまま HTTP クライアントまたはブラウザー自動化に渡してください。トークンやプレゼンテーションを手作業で書き写したり、再構築したり、再エンコードしたりしないでください。 証明情報、秘密鍵、クレーム値を会話ログやログファイルに含めないでください。受け渡し用ファイルには制限付きのアクセス権限を設定してください。
• キャッシュされたアイデンティティファイルはホームディレクトリに保存されます。--auth を変更したり、別のユーザーでログインしたりしても、キャッシュされたアイデンティティは切り替わりません。ユーザーごとに個別のホームディレクトリを使用してください。

アテステーション

# Inspect inventory.
link-cli identity attestations list --format json

# Refill only when needed. Count is required: 1–100.
link-cli identity attestations request --count 10 --format json

# Pop a token when ready to use it.
link-cli identity attestations pop --format json

errors と attestations を確認してください。storage: "pool" のエントリのみ pop で利用できます。total_token_count にはエクスポート分も含まれます。リクエストは ~/.link-cli/identity/attestations/pool.json に追記されます。

pop の出力例：

{
  "issuer": "https://api.link.com",
  "token_key_id": "<issuer-key-id>",
  "token": "<token>",
  "authorization": "PrivateToken token=\"<token-with-header-padding>\""
}

authorization はスキームと引用符も含めて、そのまま使用してください。pop はトークンをローカルから削除します。サーバー側での再利用ルールはサービスによって異なります。既存のやり取りに紐づく再試行では同じ AAT を使用し、新しいサービスでは新しいものを使用してください。取り出したトークンをプールに戻さないでください。

エージェント側で割り当てを管理する場合は、代わりに一括でエクスポートしてください。

link-cli identity attestations request --count 10 --output-file ./aats.json --format json

~/.link-cli/identity/attestations の外に新しいファイルを使用してください。tokens 配列と各エントリの authorization をプログラムから読み取ってください。エクスポートされたトークンは CLI プールに入りません。割り当て、並行処理、クリーンアップは呼び出し側の責任です。

クレデンシャルとプレゼンテーション

# Check errors, expired, expires_at, and claim_names.
link-cli identity credentials list --format json

# Request only if no usable credential exists for the intended user.
link-cli identity credentials request --format json

発行すると ~/.link-cli/identity/credentials/current.json が置き換えられ、~/.link-cli/identity/holder-key.jwk が作成または再利用されます。両方ともローカルに保管してください。present でクレームを選択します。

link-cli identity credentials present \
  --aud 'https://service.example' \
  --nonce '<nonce-from-challenge>' \
  --claim email \
  --format json

意図したサービスのものであることを確認したうえで、サービスからのチャレンジに記載された対象者とノンスをそのまま使用してください。3 つのオプションすべてが必須です。--claim を繰り返すのは、ユーザーのタスクで許可された、追加で要求されているクレームに限ってください。チャレンジ値は個別のプロセス引数として渡すか、シェルで安全に引用符で囲んでください。

出力例：

{"presentation":"<issuer-jwt>~<email-disclosure>~<key-binding-jwt>"}

present は保存済みの保持者鍵でローカル署名を行い、ファイルは変更しません。プレゼンテーションは速やかに送信してください。クレデンシャルは有効期限まで再利用できますが、ノンスが使用済みまたは期限切れになった後は、新しいチャレンジを取得してください。

送信と復旧

対象のエンドポイントにのみヘッダーを設定してください。チャレンジされた操作のメソッド、本文、セッション、インタラクション識別子、必要な AAT は変更せずに保持してください。ブラウザー全体に適用されるヘッダーや、別のオリジンに証明を転送するリダイレクトは避けてください。サービスがリクエストを受理した後にのみ、成功を報告してください。

• ATTESTATION_POOL_EMPTY：バッチをリクエストしてから、トークンを 1 つ取り出してください。
• list のエラー：ストレージが空だと判断せず、報告されたファイルまたはエラーを確認してください。
• 利用できないクレーム：claim_names を確認してください。余分なクレームや認証情報の生データは開示しないでください。
• 保有者キーの欠落または不一致：ファイルを保持し、正しいキーを復元するか、新しい認証情報を明示的に取得してください。
• オーディエンスまたはノンスによる拒否：提示する前に、対象のサービスと現在のチャレンジを確認してください。