MongoDB 上可信任代理商业的授权分类账本

与 AP2 建立信任

Google 的 代理支付协议 (AP2) 提供一个开放、安全和可互操作的协议，为商家、金融机构和日常客户构建可信的生态系统。

图 1。信任层

AP2 通过可验证数字凭证 (VDC)——代理创建和交换的防篡改、经过密码签名的 JSON 负载来确保事务安全。AP2 将这些 VDC 分为三个核心任务：

• 意图授权：概述客户的要求，并定义 AI 代理可以代表客户进行采购的条件。

• 购物车授权：提供由商家和客户数签名的数字收据，以授权人工存在购买。

• 付款授权：创建与支付网络直接共享的可见性层，以安全地指示 AI 代理的参与。

VDC 充当永久数字合同。代理使用密码签名这些负载以捕获客户数意图。此过程为购物体验的每个步骤创建不可抵赖的 Atlas 审核追踪。

图 2。每个步骤都有可验证的证明的合同对话

图 3。用户界面中的意图可视化，展示每个意图在对话中的表示方式

借助 MongoDB Atlas 确保责任制

为了使这些加密 VDC 保持可信，系统必须将其存储在安全、可验证的环境中。Mandate Ledger Service 充当AI代理和数据库之间的保护性中间件。这个中间件的背后是MongoDB Atlas。

Atlas 提供企业级安全，支持防篡改的 Atlas 审核追踪。构建此架构以创建不可变的信任层，即授权分类账本服务，以扩展安全的代理商业。

设想一位客户数请求 AI 助手购买新智能手机。购物代理自主与商家协商，以找到最优惠的交易。授权分类帐本服务通过将每个请求、批准和结账步骤打包成经密码签名的 JSON 授权，记录整个过程。MongoDB Atlas 将每个授权存储为不可变的文档。此过程将简单的聊天转变为永久的、不可抵赖的意图证明。

此解决方案展示了如何在使用 AP2 协议的架构上构建 Mandate Ledger Service。

分类帐本服务：一层保护屏障

授权分类账本服务充当保护中间件，将商家代理连接到数据库。使用 FastAPI 或 gRPC 构建此服务。

图 5。任务分类帐本服务详细架构

通过三个独立的安全层处理所有代理请求：

• 身份验证层：验证 API 密钥以安全识别代理。它通过代理类型应用基于角色的访问控制 (RBAC)，以实施严格的代理权限。

• 业务逻辑层：执行核心请求验证和并发控制。它实施幂等性以进行安全网络重试，并支持严格的授权不可变性。

• 数据访问层：使用 MongoDB 客户端和优化索引来执行数据库操作。此层将 _id 字段定义为不可变的，并通过模式验证阻止所有更新和删除操作。

授权链：从意图到支付

每个 AP2 事务都会通过一系列结构化的加密签名授权进行。每个步骤都会在 MongoDB Atlas 中产生一个不可变的记录，从意图到付款创建完整的 Atlas 审核追踪。

图 6. Dataflow

要将事务从意图转移到付款，AP2 代理将完成以下事务序列：

1. 捕获客户的意图。购物代理将客户数的请求（例如“跑步鞋”的自然语言说明）转换为结构化的意图授权。意图授权捕获目标商家、可退款要求、购物车确认偏好和到期窗口。购物代理使用 EdDSA 代表客户签署授权，并以 signed 状态和锁定其内容的版本哈希将其发送给商家代理。

2. 存储意向授权。商家代理通过授权分类帐本服务将意向授权写入 Atlas。分类帐本服务验证请求，应用 RBAC，并且不可变地添加记录。

3. 创建购物车任务。商户代理构建购物车报价，其中包含完整的产品详细信息：商品名称、价格、货币、接受的付款方式和有效期。然后，商户代理通过 Mandate Ledger Service 将其存储在Atlas中，其中记录接收 proposed 状态和版本哈希以确保完整性。

4. 向客户提供购物车。商家代理将提议的购物车授权返回给购物代理，购物代理将可用的产品选项呈现给客户。

5. 接受购物车授权。客户选择一个选项。购物代理使用硬件支持的设备密钥代表客户共同签署购物车授权，并将接受的授权发送回商家代理。

6. 会签并确定购物车授权。商家代理将其加密签名添加到已接受的购物车中，并将完全双签的购物车授权存储在 Atlas 中，以 signed 状态锁定已协定的术语。

7. 创建付款授权。购物代理向凭证提供商查询以检索相应的付款令牌。购物代理会代客户创建并签署付款授权书，并将其发送给商家代理。凭证提供商从不返回完整的信用卡号码，这可确保购物代理不会访问原始数据。

8. 存储付款授权书。商家代理通过授权书分类帐本服务将签署的付款授权书写入 Atlas。分类帐本服务将此授权书直接共享给金融机构，以标记 AI 代理的参与，付款处理器使用此授权书将授权路由到付款网络。

代理无法修改或删除现有记录。MongoDB Atlas 实施只附加写入，因此完整的授权链（意图、购物车和支付）在任何时候都会保持完整，并可由审计代理独立验证。

授权分类账本：一个多态文档存储

mandate_ledger 集合在单个集合中存储所有三种授权类型。使用 entity_type 字段在查询时区分它们，这样就无需每种授权类型进行连接或分离集合。

所有文档共享同一个常见的信封结构：

{
  "entity_id": "IntentMandate_955181ea-11c3-4379-92c4-3e27c5f278d3",
  "entity_type": "IntentMandate",
  "version": 1,
  "status": "signed",
  "transaction_id": "txn_fca7db66-c769-4206-b891-7140af37f8f4",
  "user_id": "hunter-d53910cf-b9e2-4876-8668-8251c990e203",
  "created_by_agent": "merchant_agent_dev",
  "created_by_agent_type": "merchant-agent",
  "current_version_hash": "4a822a01468a27dfd...",
  "signatures": [...],
  "mandate_data": { ... }
}

mandate_data 字段携带类型特定的负载，其中每个授权类型都存储不同的数据结构：

"mandate_data": {
  "natural_language_description": "cheapest french press coffee maker",
  "merchants": [],
  "skus": [],
  "requires_refundability": true,
  "user_cart_confirmation_required": true,
  "intent_expiry": "2026-04-18T20:00:03.651746+00:00"
}

"mandate_data": {
  "contents": {
    "payment_request": {
      "method_data": [{ "supported_methods": "CARD", "data": { "network": ["mastercard", "paypal", "amex"] }}],
      "details": {
        "display_items": [
          { "label": "Standard Laptop", "amount": { "currency": "USD", "value": 1203.50 }, "refund_period": 30 },
          { "label": "Shipping", "amount": { "currency": "USD", "value": 2.00 }},
          { "label": "Tax", "amount": { "currency": "USD", "value": 1.50 }}
        ],
        "total": { "label": "Total", "amount": { "currency": "USD", "value": 1203.50 }}
      }
    },
    "shipping_address": { "recipient": "Bugs Bunny", "address_line": ["123 Main St"], "city": "Sample City", "country": "US" },
    "cart_expiry": "2026-04-17T20:29:05.197984+00:00"
  },
  "merchant_authorization": "eyJhbGciOiJSUzI1NiIs..."
}

"signatures": [
  { "signer_type": "shopping-agent", "algorithm": "EdDSA", "signed_at": "2026-04-17T19:59:49Z" },
  { "signer_type": "merchant-agent", "algorithm": "JWT",   "signed_at": "2026-04-17T19:59:50Z" }
]

"mandate_data": {
  "payment_mandate_contents": {
    "payment_details_total": { "label": "Total", "amount": { "currency": "USD", "value": 1203.50 }},
    "payment_response": {
      "method_name": "CARD",
      "details": { "token": { "value": "fake_payment_credential_token_5" }},
      "shipping_address": { "recipient": "Bugs Bunny", "address_line": ["123 Main St"], "city": "Sample City" },
      "payer_email": "bugsbunny@gmail.com"
    },
    "merchant_agent": "Generic Merchant",
    "timestamp": "2026-04-17T20:00:22.603453+00:00"
  },
  "user_authorization": "fake_cart_mandate_hash_cart_fb1b4c86..._fake_payment_mandate_hash_812843b2..."
}

付款：超精简的完成记录

payments 集合存储每个已完成事务的一个文档。此集合应用 扩展参考模式。

每个文档不会嵌入完整的授权内容，而是仅存储每个授权的授权 ID 和授权签名。这种设计可以使付款记录变得小而快速可读，同时在需要完整的 Atlas 审核追踪时，保留指向 mandate_ledger 集合中完整数据的直接指针。

{
  "payment_id": "pay_123c25ac-7b56-4e45-8dd1-30cdcda944c7",
  "transaction_id": "txn_6fbab918-2b5d-4ddd-89d8-fdb96e5648d9",
  "user_id": "hunter-263b752e-92be-4001-ab9d-38847811c663",
  "intent_mandate":  { "mandate_id": "IntentMandate_41bbeacf-...",  "signature": "0x_shopping_agent_sig_...", "timestamp": "2026-04-15T19:50:57Z" },
  "cart_mandate":    { "mandate_id": "CartMandate_c0e8f369-...",    "signature": "eyJhbGciOiJSUzI1NiIs...",  "timestamp": "2026-04-15T19:52:07Z" },
  "payment_mandate": { "mandate_id": "PaymentMandate_33c39b8c-...", "signature": "fake_cart_mandate_hash_...", "timestamp": "2026-04-15T19:53:53Z" },
  "amount": 28,
  "currency": "USD",
  "status": "SUCCESS",
  "payment_method_type": "CARD",
  "merchant_agent": "merchant_agent_dev",
  "payment_processor_agent": "payment_processor",
  "processed_at": "2026-04-15T19:54:14Z"
}

此设计有意使文档保持较小。完整的术语、行项和加密证明位于 mandate_ledger 集合中。付款记录仅用于确认事务已完成并提供重新构建完整 Atlas 审核链所需的三个指针。当需要完整追踪时，使用 transaction_id 字段在两个集合中进行连接。

API 密钥：安全代理身份识别

api_keys 集合管理 API 密钥，以安全识别代理。使用此集合存储调用服务的每个代理相关的密钥。

Atlas 审核日志：操作轨迹

audit_log 集合存储所有 API 操作，以便合规和调试。使用此集合记录服务级事件，例如授权创建、访问尝试和验证结果。此方法可防止扩展不可变的授权分类帐本本身。添加 TTL 索引，以在 90 天后自动删除记录。这可保留有用的操作追踪，同时使集合保持在界限内。

该集合包括以下关键字段：

• event_type: 标识操作类型，例如 mandate.created。

• entity_id: 引用相关授权。

• actor_agent_id: 捕获执行操作的代理。

• event_timestamp: 记录事件发生的时间，并支持 TTL 策略。

• expires_at: 定义 MongoDB 自动删除记录的时间。

幂等记录：安全重试处理

idempotency_records 集合存储幂等密钥以防止重复操作。使用此集合保留客户端提供的密钥、发出请求的代理和为该操作创建的分类账本条目。添加 TTL 索引以在 24 小时后自动删除记录。

该集合包括以下关键字段：

• idempotency_key: 存储客户端提供的唯一密钥，并要求索引。

• agent_id: 标识发出请求的代理。

• ledger_entry_id: 引用为原始请求创建的授权。

• expires_at: 定义 MongoDB 自动删除记录的时间。

先决条件

开始之前，请确保安装和配置以下内容：

• MongoDB Atlas 或自管理 MongoDB 7.0 或更高版本

• Python 3.13 (版本 3.13.x)

• uv 用于依赖管理

• Google API 密钥 或 Vertex AI 访问

• Docker 将服务作为容器运行

• Node.js 和 npm 用于前端应用程序

步骤