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 标志。请参阅钱包设置；认证指南可参考创建支付凭证技能。

• 身份命令可通过 CLI 使用，而不能通过其 MCP 工具使用。
• 只有 request 需要 Link 认证。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；对于新的服务，请使用新的 AAT。请勿将已弹出的令牌放回令牌池。

如需由 Agent 管理分配，请改为导出一批令牌：

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

请先确认服务质询中的受众和随机数属于预期服务，再使用其确切值。三个选项均为必填项。仅当用户任务授权了其他请求的声明时，才重复使用 --claim。将质询值作为单独的进程参数传递，或在 shell 中安全地加引号。

输出示例：

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

present 会使用已保存的持有者密钥在本地签名，并且不会更改这些文件。请及时发送证明。底层凭证可重复使用，直至过期；但随机数使用后或过期时，请获取新的质询。

发送并恢复

仅为预期端点设置标头。保留受质疑操作的方法、正文、会话、交互标识符以及任何必需的 AAT。避免使用全局浏览器标头或会将证明转发到其他源的重定向。只有在服务接受请求后，才报告成功。

• ATTESTATION_POOL_EMPTY：请求一批令牌，然后弹出一个令牌。
• list 中的错误：检查报告的文件或错误，而不是将其视为存储为空。
• 声明不可用：检查 claim_names；不要披露额外声明或原始凭证。
• 持有者密钥缺失或不匹配：保留文件，并恢复正确的密钥，或明确获取新凭证。
• 受众或 nonce 被拒绝：在再次提交前，检查预期服务及其当前质询。