AP2 Mandates AP2加密指令扩展

基本信息

• Capability Name：dev.ucp.shopping.ap2_mandate
• Version：2026-01-11
• 官方规范：ap2-mandates.md

概述

AP2 Mandates 扩展使用 可验证数字凭证 实现用户意图和授权的安全交换。

当此能力协商并激活时，它将标准结账会话转换为加密绑定的协议：

• 商家 必须 在结账响应中嵌入加密签名，证明条款（价格、行项目）是真实的。
• 平台 必须 在 complete 操作期间提供加密签名的证明（Mandates），证明用户明确授权了特定的结账状态和资金转移。

安全绑定： 一旦此扩展在能力交集协商中激活，会话即 安全锁定。任何一方都不能恢复到标准（无保护）结账流程。

设计

所有 AP2 特定字段在请求和响应中嵌套在 ap2 对象下。这提供了：

• Schema 模块化 — 基础结账 schema 保持清洁；AP2 添加一个包含其所有数据的字段。
• 一致的正则化 — 一条规则：从商家的签名计算中排除 ap2。未来的 AP2 字段自动处理。
• 扩展共存 — 多个安全扩展可以共存而不会发生命名空间冲突。
• 能力信号 — ap2 对象的存在清楚地表明 AP2 处于活动状态。

发现与协商

商家 Profile 广告

商家通过将 dev.ucp.shopping.ap2_mandate 添加到其 /.well-known/ucp 中的 capabilities 列表来声明支持。

商家 Profile 示例：

{
  "capabilities": [
    {
      "name": "dev.ucp.shopping.ap2_mandate",
      "version": "2026-01-11",
      "spec": "https://ucp.dev/specification/ap2-mandates",
      "schema": "https://ucp.dev/schemas/shopping/ap2_mandate.json",
      "extends": "dev.ucp.shopping.checkout",
      "config": {
        "vp_formats_supported": {
          "dc+sd-jwt": { }
        }
      }
    }
  ]
}

激活和会话锁定

1. 平台广告其 Profile URI（传输特定机制）。
2. 商家获取 Profile 并计算交集。
3. 如果 dev.ucp.shopping.ap2_mandate 出现在交集中：
   • 商家 必须 在所有结账响应中包含 ap2.merchant_authorization。
   • 商家 不得 接受缺少 ap2.checkout_mandate 的 complete_checkout 请求。
   • 平台 必须 在向用户展示结账之前验证商家的签名。

加密要求

签名算法

所有签名 必须 使用以下算法之一：

商家授权

商家 必须 使用 JWS 分离内容 格式在结账响应正文中的 ap2.merchant_authorization 下嵌入其签名。

带嵌入签名的结账响应：

{
  "id": "chk_abc123",
  "status": "ready_for_complete",
  "currency": "USD",
  "line_items": [...],
  "totals": [...],
  "ap2": {
    "merchant_authorization": "eyJhbGciOiJFUzI1NiIsImtpZCI6Im1lcmNoYW50XzIwMjUifQ..<signature>"
  }
}

Mandate 结构

Mandate 是带密钥绑定的 SD-JWT 凭证（+kb）。平台 必须 生成两个不同的 mandate 工件：

正则化

对于 JSON 负载的签名计算，实现 必须 使用 JSON Canonicalization Scheme (JCS)，定义在 RFC 8785 中。

正则化规则： 计算商家的签名时，完全排除 ap2 字段。

Mandate 流程

步骤 1：结账创建与签名

平台发起会话。商家返回带有响应正文中嵌入的 ap2.merchant_authorization 的 Checkout 对象。

示例响应：

{
  "id": "chk_abc123",
  "status": "ready_for_complete",
  "currency": "USD",
  "line_items": [...],
  "totals": [...],
  "ap2": {
    "merchant_authorization": "eyJhbGciOiJFUzI1NiIsImtpZCI6Im1lcmNoYW50XzIwMjUifQ..<signature>"
  }
}

平台 必须 验证签名。

步骤 2：用户同意与 Mandate 生成

当用户确认购买时，平台 必须 促进生成加密可验证的 mandates。

选项 1：可信平台提供商

可信平台提供商代表用户生成 mandate 凭证。平台提供商 必须 确保 mandates 仅在来自可信、确定性渠道的明确用户同意后才创建。

选项 2：数字支付凭证

用户拥有商家信任的来源（例如：银行或网络发行的数字支付凭证）发行的 VDC。

步骤 3：提交（complete_checkout）

一旦 mandates 生成，平台在完成请求中提交它们：

{
  "payment_data": {
      "id": "instr_1",
      "handler_id": "gpay",
      "type": "card",
      "credential": {
        "type": "PAYMENT_GATEWAY",
        "token": "examplePaymentMethodToken"
      }
  },
  "ap2": {
     "checkout_mandate": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZjK3NkLWp3dCJ9..."
  }
}

• ap2.checkout_mandate：包含完整结账（带有 ap2.merchant_authorization）的 SD-JWT+kb 结账 mandate
• payment_data.token：包含 payment mandate（复合令牌）

验证与处理

商家验证

收到 complete 请求后，商家 必须：

1. 强制协商： 如果协商了 AP2，如果缺少 ap2.checkout_mandate，则以 mandate_required 错误码拒绝请求。

2. 验证 Mandate： 解码并验证 SD-JWT 签名、密钥绑定和过期。

3. 提取嵌入的结账： 从验证的 mandate claims 中提取结账对象。

4. 验证商家授权： 确认嵌入结账中的 ap2.merchant_authorization 是商家自己的有效签名。

5. 验证条款匹配： 确认嵌入的结账条款与当前会话状态（id、totals、line_items）匹配。

错误码