diff --git a/.github/ISSUE_TEMPLATE/spec-issue.md b/.github/ISSUE_TEMPLATE/spec-issue.md index 3b068ca..0b56fc0 100644 --- a/.github/ISSUE_TEMPLATE/spec-issue.md +++ b/.github/ISSUE_TEMPLATE/spec-issue.md @@ -34,4 +34,4 @@ labels: specification - [ ] 影响实现行为（需同步更新样例、产品接入或后续参考实现） - [ ] 破坏性变更（影响已有实现的兼容性） -ACT 2.1 已定稿。新增规范行为不会直接写入 ACT 2.1，应按治理流程进入未来版本和公开决策记录。 +ACT 2.1 已定稿。新增规范行为不会直接写入 ACT 2.1，应面向未来协议版本提出。 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9723b78..8b91209 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -31,8 +31,19 @@ ## 破坏性变更或未来版本提案 - + ## 测试 + +## AI 辅助使用 + + + +- [ ] 我已人工检查 AI 生成或修改的内容，并对提交结果负责 +- [ ] 我已核对其中涉及的协议语义、产品事实、链接和引用 +- [ ] 我没有向未经批准的 AI 服务提供密钥、支付凭证、个人信息或未脱敏证据 diff --git a/CHANGELOG.md b/CHANGELOG.md index 73d3eea..1c81f90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,11 @@ # Changelog -本文件记录各公开发布版本的变更。版本标识与发布日期与 [`release-manifest.json`](release-manifest.json) 及 [`governance/releases/`](governance/releases/) 中的发布记录保持一致；规范定版日期以 [`governance/decisions/`](governance/decisions/) 的决策记录为准。规范语义变更遵循 [GOVERNANCE.md](GOVERNANCE.md)：ACT 2.1 已定版，非勘误性质的规范性变更须以新的协议版本发布。 +本文件记录各公开发布版本的变更。版本标识、发布日期、规范定版日期和发布内容以 [`release-manifest.json`](release-manifest.json) 为准。ACT 2.1 已定版，非勘误性质的规范性变更须以新的协议版本发布。 + +## Repository maintenance — 2026-08-27 + +- 将 TSD-CRD 参考实现的实现基线、架构、快速开始、安全模型和可选扩展说明集中到 `integrations/tsd-crd/`，可运行代码继续保留在 `code/samples/tsd-crd-reference/`。 +- 明确 TSD-CRD 是 ACT 2.1 的规范性协议子篇；`reference-v1` 机器 Profile、Reference Implementation 及其实现指南不增加或替代 ACT 2.1 协议要求。 ## Repository update — 2026-08-24 @@ -11,13 +16,13 @@ ## ACT 2.1 — 2026-08-14 -- 发布 ADD、CID、PSD、TSD 四域规范，以及独立 A402 接入协议和 L1/L2/L3 场景指南。 +- 发布协议概览及 ADD、CID、PSD、TSD 四域规范；A402 和 L1/L2/L3 均由支付服务域正文定义，提取文档仅作为非规范性便捷指南。 - 将 A402 JSON Schema、fixtures 与测试断言作为非规范性机器实现产物发布。 - 提供通用本地 A402 样例、支付宝买卖方接入示例、沙箱验证指引和机器支付 Demo。 - 采用 `docs/`、`code/`、`integrations/` 三层结构，明确协议、通用工程产物与产品实现边界。 -- 公开发布树仅包含 ACT 2.1 规范、实现辅助产物、样例、产品接入和必要治理记录，不包含 ACT 2.0 或内部治理资料。 +- 公开发布树仅包含 ACT 2.1 规范、实现辅助产物、样例、产品接入和必要项目政策，不包含 ACT 2.0 或内部过程资料。 - 收口 ISR 术语、CID–PSD 机器契约边界和公共协议入口的版本权威说明。 - 支付宝买方预检对齐官网 Node.js 22+ / npm 10+ 要求，并固定仓库维护的 ACT–Alipay 集成映射标识。 - 卖方示例补充有效账单复用、Proof 拒绝后的先对账恢复规则和交易号最小披露，避免重复支付或返回过期账单。 -- Demo 明确区分引导演示、官方沙箱事件与证据回放，并移除活动过程材料。 +- Demo 收敛为不连接真实支付的 L1/L2/L3 引导演示；官方沙箱仅保留为支付宝集成的外部验证环境。 - 将仓库质量与发布程序收敛到 `tools/` 主架构，统一提供 `./tools/verify.sh` 验证入口，并明确工具不定义协议语义。 diff --git a/CODE_OF_CONDUCT.en.md b/CODE_OF_CONDUCT.en.md new file mode 100644 index 0000000..21f5b9a --- /dev/null +++ b/CODE_OF_CONDUCT.en.md @@ -0,0 +1,95 @@ +# Contributor Covenant Code of Conduct + +[简体中文](CODE_OF_CONDUCT.md) | English + +## Our Pledge + +As members, contributors, and maintainers of the ACT Protocol community, we are committed to providing an open, inclusive, professional, and respectful environment. We pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual orientation. + +Because ACT Protocol relates to payments and financial services, we place particular emphasis on the following principles: + +- **Integrity and transparency:** Be honest and open in discussions about specification design and implementation. +- **Safety first:** Put fund safety and user privacy first. +- **Professional collaboration:** Approach every technical discussion professionally and responsibly. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- Using welcoming and inclusive language. +- Respecting differing viewpoints and experiences, especially when evaluating technical approaches. +- Gracefully accepting constructive criticism and focusing on the technical issue rather than the individual. +- Focusing on what is best for the protocol ecosystem. +- Showing empathy toward other community members. +- Reporting security issues responsibly through the security disclosure process. +- Providing specific and actionable feedback when reviewing code and specifications. + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind. +- Trolling, insulting or derogatory comments, and personal or political attacks. +- Public or private harassment. +- Publishing another person's private information, such as a physical or email address, without explicit permission. +- Other conduct that could reasonably be considered inappropriate in a professional setting. +- Knowingly spreading misleading information about protocol security. +- Retaliating against or threatening contributors who report security vulnerabilities. + +## Enforcement Responsibilities + +Project maintainers are responsible for: + +1. Clarifying the standards of acceptable behavior. +2. Taking appropriate and fair corrective action in response to unacceptable behavior. +3. Maintaining the order and quality of technical discussions. +4. Protecting contributors who responsibly disclose security issues. + +Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that do not align with this Code of Conduct. They may temporarily or permanently ban contributors whose behavior is rude, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies to: + +- Project spaces and all public communication channels, including GitHub Issues, pull requests, and Discussions. +- Project-related technical meetings and events. +- One-to-one communications when representing the project. +- Activity on official social media accounts. +- Conduct outside project repositories or community spaces when it is related to the project. + +## Enforcement + +### Reporting + +Use the reporting and blocking tools provided by the hosting platform for Code of Conduct incidents. Do not disclose the identities, contact details, conversation records, or other sensitive information of affected people in a public Issue, Discussion, or pull request. + +Security vulnerabilities must not be reported through this channel. Follow the [Security Policy](SECURITY.md) and submit them to AntSRC. + +### Handling Process + +1. **Receipt:** The maintainer confirms the report after it has been received and initially reviewed. +2. **Assessment:** The urgency and validity of the report are assessed. +3. **Investigation:** The maintainer may contact relevant parties and collect additional information when necessary. +4. **Decision:** Appropriate action is selected based on the circumstances. +5. **Follow-up:** The reporter is informed of the outcome where possible, subject to privacy protections. + +### Corrective Actions + +Depending on the severity of the violation, actions may include: + +- A verbal or written warning. +- Temporary restriction from project participation, such as a commenting restriction. +- Permanent restriction from project participation. +- Legal action in cases involving malicious security-related conduct, where appropriate. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 3.0, with modifications for ACT Protocol. + +References: + +- [Contributor Covenant v3.0](https://www.contributor-covenant.org/version/3/0/code_of_conduct/) +- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) +- [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md) + +--- + +*Last updated: August 2026* diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 1696382..01cf210 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,5 +1,7 @@ # 贡献者公约行为准则 +[English](CODE_OF_CONDUCT.en.md) | 简体中文 + ## 我们的承诺 作为 ACT Protocol 社区的成员、贡献者和维护者，我们致力于打造一个开放、包容、专业且相互尊重的协作环境。我们承诺，参与我们的项目和社区将为每个人提供无骚扰的体验，无论其年龄、体型、残疾、种族、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何。 @@ -57,7 +59,7 @@ ### 报告渠道 -请通过 ACT 项目公开联系邮箱 `alipay.ai@service.alipay.com` 私密提交，并在邮件主题中注明“ACT Code of Conduct”。请不要通过公开 Issue、Discussion 或 PR 披露受影响人员身份、联系方式、对话记录或其他敏感细节。紧急的平台滥用行为也可以同时使用代码托管平台自身的举报和屏蔽能力。 +行为准则事件请使用代码托管平台提供的举报和屏蔽能力。请不要通过公开 Issue、Discussion 或 PR 披露受影响人员身份、联系方式、对话记录或其他敏感细节。 安全漏洞不使用本渠道，应按[安全披露政策](SECURITY.md)提交至 AntSRC。 diff --git a/CONTRIBUTING.en.md b/CONTRIBUTING.en.md new file mode 100644 index 0000000..46e371d --- /dev/null +++ b/CONTRIBUTING.en.md @@ -0,0 +1,36 @@ +# Contributing to ACT Protocol + +[简体中文](CONTRIBUTING.md) | English + +Thank you for contributing to ACT Protocol. Read the [Code of Conduct](CODE_OF_CONDUCT.en.md) and existing issues before starting. + +## Choose the Right Entry Point + +- Specification errata, clarifications, or proposals for a future version: [Specification issue template](.github/ISSUE_TEMPLATE/spec-issue.md) +- Samples, Schema, product integrations, demos, or tooling: [Implementation issue template](.github/ISSUE_TEMPLATE/implementation-issue.md) +- A change ready for submission: [Pull request template](.github/PULL_REQUEST_TEMPLATE.md) +- Security vulnerabilities: do not open a public issue; follow the private process in the [Security Policy](SECURITY.md) + +## Submit a Change + +1. Open an issue before proposing protocol semantics, new behavior, or a breaking change. Security vulnerabilities must use the private channel specified in [SECURITY.md](SECURITY.md). +2. Keep each pull request focused and identify whether it changes the protocol, machine-readable artifacts, a product integration, or documentation. +3. Add tests appropriate to the change and run `./tools/verify.sh`. +4. Explain compatibility and security impact in the pull request. + +ACT 2.1 is final. Typographical corrections and clarifications that do not change meaning may be applied. New normative behavior must target a future protocol version. JSON Schema, integrations, and examples must not add requirements that are absent from the specification. + +Product integrations must cite current official product sources, keep credentials out of the repository, and avoid presenting local tests as real sandbox evidence. + +Contributors confirm that they have the right to submit their material. Accepted contributions use the license assigned to the relevant file or directory by [LICENSE](LICENSE). No additional CLA or DCO sign-off is currently required. + +## AI-Assisted Contributions and Reviews + +AI tools may be used to assist with code, specification text, documentation, tests, and reviews. They do not replace the judgment or responsibility of contributors and reviewers. + +- Disclose the areas in which AI materially contributed to the pull request, such as code generation, translation, test generation, research organization, or review suggestions. Routine completion that did not produce material content does not need to be disclosed. +- Before submission, personally review generated content, run the appropriate tests, and take responsibility for accuracy, security, license compliance, and the final result. +- Do not provide secrets, tokens, payment credentials, personal information, unsanitized evidence, or other sensitive material to an AI service that has not been approved for that data. +- Do not directly rely on AI-generated protocol semantics, product APIs, error codes, links, citations, or compatibility conclusions. Verify each of them against the ACT specification, official product sources, and actual test results. +- Treat AI review output as advisory. Reviewers should pay particular attention to fabricated facts, missed edge cases, inadequate tests, insecure code, incorrect translations, and attempts to let machine artifacts or product behavior redefine protocol semantics. +- The pull request author remains responsible for the submitted content. The project maintainer makes the final acceptance decision. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b775f1..9817fcf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,36 @@ -# Contributing to ACT Protocol +# 贡献指南 -Thank you for contributing. Read the [Code of Conduct](CODE_OF_CONDUCT.md), [governance rules](GOVERNANCE.md), and existing issues before starting. +[English](CONTRIBUTING.en.md) | 简体中文 -## Repository map +感谢你参与 ACT Protocol。开始前请阅读[行为准则](CODE_OF_CONDUCT.md)并查看现有 Issue。 -- `docs/`: ACT 2.1 specification, flows and explanatory material. -- `code/`: machine artifacts, product-neutral samples and demos. -- `integrations/`: provider-specific integrations, including Alipay. -- `tools/`: active repository quality and release tooling; it does not define protocol semantics. +## 选择入口 -## Workflow +- 协议勘误、澄清或未来版本建议：[规范 Issue 模板](.github/ISSUE_TEMPLATE/spec-issue.md) +- 样例、Schema、产品接入、Demo 或工具问题：[实现 Issue 模板](.github/ISSUE_TEMPLATE/implementation-issue.md) +- 准备提交变更：[Pull Request 模板](.github/PULL_REQUEST_TEMPLATE.md) +- 安全漏洞：不要创建公开 Issue，请按[安全政策](SECURITY.md)私密提交 -1. Open an issue for protocol semantics, new behavior or a breaking change. Security vulnerabilities must use the private channel in [SECURITY.md](SECURITY.md). -2. Keep each pull request focused and identify whether it changes protocol, implementation artifacts, a product integration or documentation. -3. Add tests appropriate to the change and run `./tools/verify.sh`. -4. Explain compatibility, security and source impact in the pull request. +## 提交变更 -ACT 2.1 is final. Typographical fixes and clarifications may update it without changing meaning; new normative behavior requires a future version and an accepted public decision. JSON Schema and examples must not silently expand normative requirements. +1. 涉及协议语义、新行为或破坏性变更时，请先创建 Issue。安全漏洞必须通过 [SECURITY.md](SECURITY.md) 指定的私密渠道提交。 +2. 每个 Pull Request 应聚焦单一主题，并说明变更属于协议、机器产物、产品接入还是文档。 +3. 根据变更补充相应测试，并运行 `./tools/verify.sh`。 +4. 在 Pull Request 中说明兼容性和安全影响。 -Product integrations must cite current official product sources, keep credentials out of the repository and avoid presenting local tests as real sandbox evidence. +ACT 2.1 已定稿。文字勘误和不改变含义的澄清可以更新；新增规范性行为必须面向未来协议版本。JSON Schema、产品接入和示例不得增加协议正文中不存在的要求。 -Contributors confirm they have the right to submit their material. Accepted contributions use the license assigned to the relevant file or directory by [LICENSE](LICENSE). No additional CLA or DCO sign-off is currently required. +产品接入必须引用当前有效的官方产品来源，不得向仓库提交凭证，也不得把本地测试表述为真实沙箱证据。 + +贡献者应确认有权提交相关内容。被接受的贡献适用 [LICENSE](LICENSE) 对相应文件或目录规定的许可证。目前不要求额外签署 CLA 或进行 DCO sign-off。 + +## AI 辅助贡献与评审 + +可以使用 AI 工具辅助编写代码、规范文本、文档、测试和评审，但 AI 不能替代贡献者或评审者的判断与责任。 + +- 在 Pull Request 中说明 AI 实际参与的范围，例如代码生成、翻译、测试生成、资料整理或评审建议；仅使用普通补全且未形成实质内容时无需披露。 +- 提交前由贡献者本人检查生成内容，运行相应测试，并对准确性、安全性、许可证合规性和最终结果负责。 +- 不得将密钥、Token、支付凭证、个人信息、未脱敏证据或其他敏感资料提交给未经批准的 AI 服务。 +- 不得直接采用 AI 生成的协议语义、产品 API、错误码、链接、引用或兼容性结论；必须与 ACT 规范、官方产品来源和实际测试结果逐项核对。 +- AI 评审结果仅作为辅助意见。评审者应重点检查虚构事实、遗漏边界条件、不充分测试、不安全代码、错误翻译，以及机器产物或产品行为反向定义协议语义的问题。 +- Pull Request 的作者仍对提交内容负责，最终接受决定由项目维护者作出。 diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index 3c7c683..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,27 +0,0 @@ -# ACT Protocol Governance - -ACT Protocol is an Ant Group open-source project. This document governs maintenance of the published ACT 2.1 specification and future protocol evolution. - -## Principles - -- Protocol discussions and decisions are public except for security or legally restricted material. -- ACT Core remains product-neutral. Product documentation cannot redefine protocol semantics. -- Changes preserve cross-domain consistency across ADD, CID, PSD and TSD. -- Normative text, implementation artifacts and product integrations are reviewed as separate layers. - -## Roles - -Maintainers listed in [MAINTAINERS.md](MAINTAINERS.md) review changes, keep releases coherent and resolve repository issues. Domain experts may review protocol changes. Additional maintainers are added through a public, recorded decision based on sustained contribution. - -## Changes - -- Editorial fixes and broken links may be merged with one maintainer approval. -- Clarifications must not add requirements and require review by a maintainer familiar with the affected domain. -- New fields, components, wire behavior or breaking changes require a public proposal, compatibility and security analysis, cross-domain review, implementation evidence where applicable, and an accepted decision record. -- Product integration changes require current official product sources and must not modify ACT Core to match one provider. - -ACT 2.1 is final. Normative changes beyond errata are published in a new protocol version. Machine schemas in `code/` remain implementation artifacts unless a future specification explicitly incorporates them. - -## Decisions and releases - -Accepted protocol and project decisions are recorded in `governance/decisions/`. Release notes are recorded in `governance/releases/`. Every release must pass repository checks, preserve licensing and security guidance, and state the evidence behind implementation or interoperability claims. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index c525273..10a41b3 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,10 +1,7 @@ -# Maintainers +# Maintainer -| Area | Maintainer | Responsibility | -|---|---|---| -| ACT specification | 观岳 | Normative semantics, errata and future protocol revisions | -| Repository and integrations | 念箴 | Architecture, Alipay integration, tests and releases | +| Maintainer | Responsibility | +|---|---| +| [@freeman1128](https://github.com/freeman1128) | ACT specification maintenance, repository architecture, integrations, tests and releases | -Use the repository review workflow for changes. Report security issues through the private channel in [SECURITY.md](SECURITY.md), not to personal contacts or public issues. - -Public project coordination: `alipay.ai@service.alipay.com`. Code of Conduct reports must follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Repository permissions and review assignment are managed through the hosting organization's maintainer team rather than personal credentials recorded in this file. +Report security issues through the private channel in [SECURITY.md](SECURITY.md), not through personal contacts or public issues. Code of Conduct reports must follow [CODE_OF_CONDUCT.en.md](CODE_OF_CONDUCT.en.md). diff --git a/README.en.md b/README.en.md index 6f0b7b4..6e3263b 100644 --- a/README.en.md +++ b/README.en.md @@ -9,7 +9,7 @@ ACT (Agentic Commerce Trust Protocol) is an open protocol for agentic commerce. | Goal | Entry | |---|---| | Read ACT 2.1 | [Specification overview](docs/specification/overview.en.md) | -| Understand end-to-end flows | [Scenarios](docs/flows/scenarios.en.md) | +| Understand end-to-end flows | [Scenarios and Business Flows](docs/specification/scenarios.en.md) | | Run the TSD-CRD credit-association reference flow | [TSD-CRD Reference Implementation](code/samples/tsd-crd-reference/README.md) | | Run the safe local A402 sample | [Local A402 Sample](code/samples/local-a402/README.md) | | Explore the interactive flow | [Web Showcase](code/web-client/alipay-ai-pay-showcase/README.md) | @@ -17,21 +17,21 @@ ACT (Agentic Commerce Trust Protocol) is an open protocol for agentic commerce. For a first visit: read the [English overview](docs/specification/overview.en.md), keep the [bilingual glossary](docs/glossary.md) open, run the local sample, and then choose the buyer or seller Alipay integration. The local sample intentionally demonstrates safe rejection rather than manufacturing payment success; a successful paid delivery requires verified proof from the official product workflow. -Human-readable protocol text lives in `docs/specification/`. JSON Schemas, fixtures, and tests live in `code/schemas/`; they support implementation without adding requirements that are absent from the specification. +The five human-readable specification documents and the non-normative scenario guide live in `docs/specification/`. A402 and commerce-to-payment integration guides are grouped with the Alipay reference integration under `integrations/alipay/`. JSON Schemas, fixtures, and tests live in `code/schemas/`; they support implementation without adding requirements that are absent from the specification. -ACT 2.1 is available in both [Chinese](docs/specification/overview.md) and [English](docs/specification/overview.en.md). The English documents are official informative translations of the final 2.1 publication; if a translation discrepancy is found, the Chinese publication remains controlling until the discrepancy is resolved through project governance. +ACT 2.1 is available in both [Chinese](docs/specification/overview.md) and [English](docs/specification/overview.en.md). The English documents are official informative translations of the final 2.1 publication; if a translation discrepancy is found, the Chinese publication remains controlling until the translation is corrected in a subsequent repository release. -The files under `docs/specification/` in this repository release are the sole versioned ACT 2.1 specification publication. [act-protocol.com](https://www.act-protocol.com/) is a project-information entry point. Website content that is not explicitly labeled ACT 2.1 is informative and is not a normative source for this release. If a web page omits a component, uses a different structure, or conflicts with this release, it MUST NOT override or interpret the repository's ACT 2.1 requirements. +The overview and four domain specifications under `docs/specification/` are the sole versioned ACT 2.1 normative publication in this repository release; the scenario guide is explicitly non-normative. [act-protocol.com](https://www.act-protocol.com/) is a project-information entry point. Website content that is not explicitly labeled ACT 2.1 is informative and is not a normative source for this release. If a web page omits a component, uses a different structure, or conflicts with this release, it MUST NOT override or interpret the repository's ACT 2.1 requirements. ## Repository layout ```text -docs/ ACT 2.1 specification, flows, and supporting material +docs/specification/ ACT 2.1 specification and non-normative scenarios code/schemas/ Machine-readable implementation artifacts code/samples/ Runnable protocol samples code/web-client/ Interactive demo -integrations/alipay/ Alipay reference integration and validation -governance/ Accepted project decisions and release records +integrations/tsd-crd/ TSD-CRD reference implementation guidance +integrations/alipay/ Integration guides, Alipay reference code, and validation tools/ Repository quality and release tooling ``` @@ -65,4 +65,4 @@ Run all checks with Python 3, Node.js 22.18+, JDK 8+, and Maven 3.8+: ./tools/verify.sh ``` -See [CONTRIBUTING.md](CONTRIBUTING.md), [GOVERNANCE.md](GOVERNANCE.md), and [SECURITY.md](SECURITY.md). Documentation is licensed under CC BY 4.0; code is licensed under Apache License 2.0. Copyright Ant Group Co., Ltd. +See [CONTRIBUTING.en.md](CONTRIBUTING.en.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.en.md](CODE_OF_CONDUCT.en.md). Documentation is licensed under CC BY 4.0; code is licensed under Apache License 2.0. Copyright Ant Group Co., Ltd. diff --git a/README.md b/README.md index 4f4f058..c7e90cd 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ ACT（Agentic Commerce Trust Protocol）是面向智能体商业交互的开放 | 目标 | 入口 | |---|---| | 阅读 ACT 2.1 | [协议概览](docs/specification/overview.md) | -| 理解完整业务流程 | [典型场景](docs/flows/scenarios.md) | +| 理解完整业务流程 | [典型场景与业务流程](docs/specification/scenarios.md) | | 运行 TSD-CRD 信用关联参考链路 | [TSD-CRD Reference Implementation](code/samples/tsd-crd-reference/README.md) | | 本地运行安全的 A402 样例 | [Local A402 Sample](code/samples/local-a402/README.md) | | 查看交互演示 | [Web Showcase](code/web-client/alipay-ai-pay-showcase/README.md) | @@ -25,24 +25,23 @@ ACT（Agentic Commerce Trust Protocol）是面向智能体商业交互的开放 Local A402 Sample 有意不伪造支付成功。真实资源交付必须来自已经验真的支付证明，因此“本地安全失败路径”和“官网沙箱成功路径”是两个不同的接入阶段。TSD-CRD Reference Implementation 同样只使用 Mock 能力和测试密钥，不是生产信用服务。 -ACT 2.1 的人类可读协议正文位于 `docs/specification/`。JSON Schema、fixtures 和测试位于 `code/schemas/`，用于帮助实现与验证，不增加协议正文未规定的要求。 +ACT 2.1 的五份规范正文和非规范性场景指南位于 `docs/specification/`。A402 与 Commerce–Payment 接入指南随支付宝参考接入放在 `integrations/alipay/`。JSON Schema、fixtures 和测试位于 `code/schemas/`，用于帮助实现与验证，不增加协议正文未规定的要求。 -本仓库发布版本中的 `docs/specification/` 是 ACT 2.1 唯一的版本化规范正文。[act-protocol.com](https://www.act-protocol.com/) 是项目信息入口；未明确标注 ACT 2.1 版本的网页内容属于信息性材料，不是本 Release 的规范来源。网页如果遗漏本 Release 的组件、采用不同结构或与正文冲突，只能按网页自身标明的版本理解，不得用于覆盖或解释本仓库的 ACT 2.1 要求。 +本仓库发布版本中，`docs/specification/` 下的协议概览和四份域规范共同构成 ACT 2.1 唯一的版本化规范正文；场景指南明确为非规范性材料。[act-protocol.com](https://www.act-protocol.com/) 是项目信息入口；未明确标注 ACT 2.1 版本的网页内容属于信息性材料，不是本 Release 的规范来源。网页如果遗漏本 Release 的组件、采用不同结构或与正文冲突，只能按网页自身标明的版本理解，不得用于覆盖或解释本仓库的 ACT 2.1 要求。 ## 仓库结构 ```text act-protocol/ -├── docs/ # ACT 2.1 规范、流程和附录 -│ ├── specification/ -│ └── flows/ +├── docs/ # ACT 2.1 规范、场景与附加文档 +│ └── specification/ # 五份规范正文 + 非规范性场景指南 ├── code/ # Schema、样例和演示 │ ├── schemas/ │ ├── samples/ │ └── web-client/ ├── integrations/ -│ └── alipay/ # 支付宝参考接入代码与验证 -├── governance/ # 已接受的项目决策与发布记录 +│ ├── tsd-crd/ # TSD-CRD 参考实现指南 +│ └── alipay/ # 接入指南、支付宝参考代码与验证 └── tools/ # 仓库质量与发布工具 ``` @@ -108,7 +107,6 @@ npm --prefix code/web-client/alipay-ai-pay-showcase run demo ## 项目政策 - [贡献指南](CONTRIBUTING.md) -- [治理说明](GOVERNANCE.md) - [安全政策](SECURITY.md) - [行为准则](CODE_OF_CONDUCT.md) - [版本记录](CHANGELOG.md) diff --git a/code/README.md b/code/README.md index eefa6d0..8ee5cb0 100644 --- a/code/README.md +++ b/code/README.md @@ -8,4 +8,4 @@ This directory contains executable and machine-readable assets. It does not defi | [`samples/`](samples/README.md) | Small runnable samples and the TSD-CRD reference implementation | | [`web-client/`](web-client/README.md) | Interactive protocol demonstrations | -The ACT 2.1 text is under [`docs/specification/`](../docs/specification/README.md). Product-specific code belongs under [`integrations/`](../integrations/README.md). +The ACT 2.1 text is under [`docs/specification/`](../docs/specification/README.md). Reference implementation guidance and product-specific code belong under [`integrations/`](../integrations/README.md). diff --git a/code/samples/tsd-crd-reference/README.md b/code/samples/tsd-crd-reference/README.md index 168b399..7409f3d 100644 --- a/code/samples/tsd-crd-reference/README.md +++ b/code/samples/tsd-crd-reference/README.md @@ -25,7 +25,7 @@ ACT 2.1 信用关联子篇（TSD-CRD）的可执行参考实现、本地 Sandbox 协议正文规定业务语义；[`code/schemas/tsd-crd/reference-v1`](../../schemas/tsd-crd/reference-v1/README.md) 补充一套非规范性机器可读格式；本目录提供其中一种可运行实现。三者冲突时，以 ACT 2.1 协议正文为准。 -详细说明见[协议基线](docs/protocol-baseline.md)和 [Reference Profile v1](../../schemas/tsd-crd/reference-v1/README.md)。本目录由独立 TSD-CRD 仓库提交 `fdf7006d97ae06645dce82400fac2dff964691f2` 迁入；迁入时保留 `reference-v1` 的 wire 字段和固定签名向量。 +详细说明见[参考实现基线](../../../integrations/tsd-crd/implementation-baseline.md)和 [Reference Profile v1](../../schemas/tsd-crd/reference-v1/README.md)。本目录由独立 TSD-CRD 仓库提交 `fdf7006d97ae06645dce82400fac2dff964691f2` 迁入；迁入时保留 `reference-v1` 的 wire 字段和固定签名向量。 ## 两种主体确认方式 @@ -36,7 +36,7 @@ ACT 2.1 信用关联子篇（TSD-CRD）的可执行参考实现、本地 Sandbox 这里的“一层”和“两层”只指信用关联凭证的签名结构，不包括 HTTPS、回调验签或其他传输层保护。 -协议不要求 Agent 提交公钥、使用 Agent 私钥签署挑战值或完成 `AgentControlProof`。基于 nonce 的 Agent 密钥持有证明属于可选安全扩展，不在 P0 默认流程和基础一致性测试范围内。当前仓库只有[设计说明](docs/agent-key-possession-extension.md)，尚未实现对应代码。它不能替代主体确认或签发方签名。 +协议不要求 Agent 提交公钥、使用 Agent 私钥签署挑战值或完成 `AgentControlProof`。基于 nonce 的 Agent 密钥持有证明属于可选安全扩展，不在 P0 默认流程和基础一致性测试范围内。当前仓库只有[设计说明](../../../integrations/tsd-crd/agent-key-possession-extension.md)，尚未实现对应代码。它不能替代主体确认或签发方签名。 ## P0 范围 @@ -88,12 +88,13 @@ Demo 默认使用 `ATTESTED_CONFIRMATION`，通过 Mock 主体确认服务完成 Sandbox 对验证请求、DIRECT 主体确认、查询授权及生命周期变更采用失败关闭策略：必须注入可信公钥解析器并完成身份—公钥绑定和 Ed25519 验签；未配置解析器、无法解析密钥或证明无效时直接拒绝。Demo 使用进程内临时测试密钥和显式测试身份绑定，生产实现必须替换为可信密钥目录或等效信任来源。 -更多运行说明见[快速开始](docs/quickstart.md)。Sandbox 的接口以非规范性 [OpenAPI](../../schemas/tsd-crd/reference-v1/openapi/openapi.yaml) 为准，创建申请使用 `POST /v1/association-applications`。 +更多运行说明见[快速开始](../../../integrations/tsd-crd/quickstart.md)。Sandbox 的接口以 `reference-v1` [OpenAPI](../../schemas/tsd-crd/reference-v1/openapi/openapi.yaml) 为准，创建申请使用 `POST /v1/association-applications`。 ## 目录结构 ```text act-protocol/ +├── integrations/tsd-crd/ # 实现指南、架构和安全边界 ├── code/schemas/tsd-crd/reference-v1/ │ ├── schemas/ # JSON Schema │ ├── openapi/ # HTTP API 描述 @@ -108,11 +109,10 @@ act-protocol/ │ ├── cli/ # CLI 和 Demo 入口 │ └── conformance/ # 一致性测试 Runner ├── test/ # 单元和集成测试 - ├── examples/ # 可运行示例 - └── docs/ # 架构、协议和安全说明 + └── examples/ # 可运行示例 ``` -架构和依赖边界见 [架构说明](docs/architecture.md)。 +架构和依赖边界见 [架构说明](../../../integrations/tsd-crd/architecture.md)。 ## 非生产边界 @@ -124,7 +124,7 @@ act-protocol/ - 不要把内存存储、Mock 身份确认和固定映射规则用于生产。 - 生产实现必须自行补充密钥管理、数据保护、审计、合规、可用性和风险控制。 -详见[安全模型](docs/security-model.md)和仓库的[安全政策](../../../SECURITY.md)。 +详见[安全模型](../../../integrations/tsd-crd/security-model.md)和仓库的[安全政策](../../../SECURITY.md)。 ## 参与贡献 diff --git a/code/schemas/a402/README.md b/code/schemas/a402/README.md index 1c8be2a..ed83a24 100644 --- a/code/schemas/a402/README.md +++ b/code/schemas/a402/README.md @@ -4,7 +4,7 @@ > Schema：JSON Schema Draft 2020-12 > 产物版本：`2.1-artifact.1`；对应规范：ACT 2.1 -本目录是 ACT 2.1 A402 的 HTTP-first 实现辅助产物。它约束 **Base64URL 解码后的 UTF-8 JSON**；对应协议语义见 [ACT 2.1 A402](../../../docs/specification/a402.md)。产品接入可以映射这些语义，但不得反向改变规范。它不是 ACT 2.1 的规范性 Schema，也不构成 Conformance 契约。 +本目录是 ACT 2.1 A402 的 HTTP-first 实现辅助产物。它约束 **Base64URL 解码后的 UTF-8 JSON**；对应接入说明见 [ACT 2.1 A402](../../../integrations/alipay/a402.md)，规范语义以[支付服务域](../../../docs/specification/payment-services.md)为准。产品接入可以映射这些语义，但不得反向改变规范。它不是 ACT 2.1 的规范性 Schema，也不构成 Conformance 契约。 权威入口： diff --git a/code/schemas/a402/tests/README.md b/code/schemas/a402/tests/README.md index 51cccb2..279222a 100644 --- a/code/schemas/a402/tests/README.md +++ b/code/schemas/a402/tests/README.md @@ -17,4 +17,4 @@ 目录只保存已定稿的测试断言。ACT 2.1 未标准化的消息形态、依赖路径或机器错误对象属于明确的规范边界，不在本目录追踪规范演进事项。 -`test_level` 表示验证所需环境，不等同于 RFC 2119 的 MUST/SHOULD/MAY。规范约束强度只能由治理后的规范文本决定，不能由测试类型反推。 +`test_level` 表示验证所需环境，不等同于 RFC 2119 的 MUST/SHOULD/MAY。规范约束强度只能由正式规范文本决定，不能由测试类型反推。 diff --git a/code/schemas/a402/tests/a402-assertions.json b/code/schemas/a402/tests/a402-assertions.json index 0163f9e..780e4e7 100644 --- a/code/schemas/a402/tests/a402-assertions.json +++ b/code/schemas/a402/tests/a402-assertions.json @@ -7,7 +7,7 @@ { "id": "A402-TEST-001", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#act-21-a402-支付接入协议", + "source": "../../../../integrations/alipay/a402.md#act-21-a402-支付接入协议", "applies_to": [ "INS/L1", "DEL/L2", @@ -29,7 +29,7 @@ { "id": "A402-TEST-002", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#22-返回支付诉求", + "source": "../../../../integrations/alipay/a402.md#22-返回支付诉求", "applies_to": [ "HTTP binding", "resource server" @@ -52,7 +52,7 @@ { "id": "A402-TEST-003", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#25-卖方验证支付证明", + "source": "../../../../integrations/alipay/a402.md#25-卖方验证支付证明", "applies_to": [ "resource server" ], @@ -73,7 +73,7 @@ { "id": "A402-TEST-004", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#25-卖方验证支付证明", + "source": "../../../../integrations/alipay/a402.md#25-卖方验证支付证明", "applies_to": [ "resource server", "payment service" @@ -94,7 +94,7 @@ { "id": "A402-TEST-005", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#26-交付资源与履约确认", + "source": "../../../../integrations/alipay/a402.md#26-交付资源与履约确认", "applies_to": [ "resource server", "delivery" @@ -115,7 +115,7 @@ { "id": "A402-TEST-006", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#24-携带支付证明重新访问", + "source": "../../../../integrations/alipay/a402.md#24-携带支付证明重新访问", "applies_to": [ "buyer", "resource server" @@ -136,7 +136,7 @@ { "id": "A402-TEST-007", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#25-卖方验证支付证明", + "source": "../../../../integrations/alipay/a402.md#25-卖方验证支付证明", "applies_to": [ "resource server", "delivery" @@ -157,7 +157,7 @@ { "id": "A402-TEST-008", "kind": "test-assertion", - "source": "../../../../docs/specification/a402.md#7-错误响应", + "source": "../../../../integrations/alipay/a402.md#7-错误响应", "applies_to": [ "buyer", "resource server", diff --git a/code/web-client/alipay-ai-pay-showcase/README.md b/code/web-client/alipay-ai-pay-showcase/README.md index ac7e171..24417f6 100644 --- a/code/web-client/alipay-ai-pay-showcase/README.md +++ b/code/web-client/alipay-ai-pay-showcase/README.md @@ -1,246 +1,41 @@ -# ACT 2.1 Machine Payment Showcase +# ACT × Alipay AI Pay Guided Showcase -> 类型：Demo / Non-normative。支持内置场景演示和脱敏证据回放。 +本 Demo 说明“Agent 在调研过程中如何购买专业数据”，以左右对照方式展示业务执行、参与方、ACT 2.1 组件和支付宝产品映射。 -本 Demo 用于向观众展示买方 Agent 与卖方收费服务如何通过 ACT 支付服务域和 A402 形成一条机器支付闭环。它不实现钱包、支付、验凭证或沙箱，只消费接入示例与官方产品能力产生的脱敏事件。 +> **范围：Guided Demo / Non-normative / No real payment** +> 本 Demo 不连接支付宝沙箱、钱包、支付接口或验款接口，不接收真实事件，也不执行支付。 -引导演示可切换三个授权级别： +## 演示内容 -- `L1`：`PSD-PMT-BND + PSD-PAY-INS + A402`。用户逐笔在场、笔笔核身确认，Agent 不可自动扣款；首次使用还展示官方开通与绑定路径，所有二维码均为不可扫码的 UI 占位图； -- `L2`：`ADD + PSD-PAY-DEL + A402`。用户预先明确商品、商户、金额和次数并签发 `SPECIFIED IAC`，完全匹配后由 Agent 自动执行这一笔； -- `L3`：`ADD + PSD-PAY-AUP + A402`。用户只定义任务目标与预算边界，Agent 自主选择服务并执行多笔子支付，每笔重新校验边界。 - -支付宝公开产品事实仅覆盖页面明确映射的 L1 开通绑定、Agent 支付与 AI 按量付费。本仓库不提供支付宝 L2/L3 接入实现；页面中的 L2/L3 只演示 ACT 2.1 已定稿的协议语义，不代表支付宝产品能力。真实开通、绑定和二维码以[支付宝钱包指南](https://aipay.alipay.com/wallet-guide)及官方支付页面为准。 - -主页面采用“协议过程舞台”，阅读顺序固定为： - -1. 阶段导航：按所选级别展示 PMT-BND/ADD、CID、A402、INS/DEL/AUP 和履约； -2. 参与方：用户、Buyer Agent、收费服务、PSP，以及 L2/L3 的授权服务； -3. 当前消息：明确展示发送方、接收方、消息方向和线上的协议消息； -4. 四层映射：同一动作对应的 ACT 2.1、integration mapping、HTTP/Workflow 与支付宝产品能力； -5. 业务结果：资源保持锁定、成功交付或因异常拒绝交付； -6. 关联与证据：请求、订单、资源、支付交易与履约的脱敏关联链。 - -引导模式的 L1 成功路径为 16 步，L2/L3 为 14 步；异常场景会在对应恢复状态停止。官方沙箱事件和证据回放使用 Adapter 的 11 步 L1 证据基线，幂等重放共 14 步，避免 UI 说明步骤改变既有证据接口。 - -## 开箱即用的三种模式 - -| 模式 | 是否开箱可用 | 数据含义 | -|---|---|---| -| `GUIDED_DEMO` | 是 | 内置说明性数据，用于完整体验页面与讲解路径；始终标注 `NOT PAYMENT EVIDENCE` | -| `LIVE_SANDBOX` | 需要事件 Adapter | 消费官网沙箱与接入示例产生的真实脱敏 SSE；仓库本身不提供沙箱 | -| `SANITIZED_REPLAY` | 需要真实证据文件 | 播放已经通过验证的官网沙箱脱敏记录 | - -`GUIDED_DEMO` 解决首次运行时的空白问题，但不会被证据校验器接受，也不能用于任何产品兼容声明。 - -## 官方沙箱事件 / Replay 的 L1 证据链路 - -```text -CAPABILITY_NEGOTIATED -→ ORDER_CONFIRMED -→ RESOURCE_REQUESTED -→ PAYMENT_REQUIRED -→ USER_AUTHORIZATION_REQUIRED -→ PAYMENT_PROCESSING -→ PAYMENT_RESULT_RECEIVED -→ RESOURCE_REQUEST_RETRIED -→ PAYMENT_VERIFIED -→ RESOURCE_DELIVERED -→ FULFILLMENT_CONFIRMED -``` - -状态必须来自实际接入事件，不得由 UI 定时器自动推进为成功。 - -Guided Demo 还可切换： - -- 首次绑定：检查支付能力、打开官方授权二维码、返回不落日志的短时绑定指令； -- L2 定向委托：签发和验证 `SPECIFIED IAC`，再由 DEL 执行指定交易； -- L3 自主支付：签发 `BOUNDED IAC`，每笔检查任务范围和剩余预算后由 AUP 执行； -- 支付结果待确认：查询原交易，禁止重复支付； -- Proof 不匹配：拒绝交付； -- 验款暂不可用：返回可重试错误，禁止猜测成功； -- 幂等重放：完成首轮 11 步后再次提交同一请求，形成 14 步证据；返回既有结果且不重复扣款、交付或履约确认。 - -## 两种证据运行模式 - -| 模式 | 事件来源 | 用途 | 展示要求 | -|---|---|---|---| -| `LIVE_SANDBOX` | 官方 Skill/CLI、卖方接入示例、支付宝 Sandbox/OpenAPI | 联调观察 | 显示 Sandbox，不输出凭证和密钥 | -| `SANITIZED_REPLAY` | 已验证链路的脱敏事件记录 | 网络或沙箱异常时备用 | 全程明显显示 Replay，不冒充实时支付 | - -## 运行证据校验器 - -本目录不附带虚构成功数据。第一次沙箱验证后，将每个状态写成一行 NDJSON，再运行： - -```bash -npm test -node validate-evidence.mjs /absolute/path/to/sanitized-events.ndjson -``` - -校验器按场景要求状态严格有序，验证能力来源、非规范性 artifact 方法格式、请求指纹以及订单/资源/金额/交易关联不变量，并拒绝 `MOCK` 模式、明显的密钥字段和完整 `Payment-Proof`。成功场景要求 11 个状态；幂等重放要求 14 个状态和不重复副作用证据；失败场景必须停在对应失败终态。它证明的是演示证据完整性和映射一致性，不代替支付验款或 ACT Conformance。 - -## 启动 Web 演示台 - -需要 Node.js 18 或更高版本，不需要安装第三方依赖： - -```bash -cd code/web-client/alipay-ai-pay-showcase -npm test -npm run build -npm run demo -``` - -浏览器打开终端输出的本地地址，默认选择 `GUIDED_DEMO`。选择场景并点击“播放当前场景”即可观看完整状态机，不需要账号、密钥、沙箱或 Replay 文件。 - -### Live Sandbox - -`npm run demo` 同时启动仅监听 `127.0.0.1` 的脱敏事件 Bridge： - -```text -GET /events SSE 事件流 -POST /events 提交下一个脱敏事件 -GET /events/state 查询当前序号 -GET /events/export 完整链路导出为 Live NDJSON；未完成时返回 409 -POST /events/reset 开始一条新链路 -``` - -页面切换到 Live 后，默认连接同源 `/events`。Bridge 会补充序号、Sandbox 模式和观察时间，严格拒绝乱序、Mock 来源和敏感字段；它不接收或代理支付请求。 - -开始一次新验证： - -```bash -curl -X POST http://127.0.0.1:4173/events/reset -``` - -Live 事件由接入 Adapter 或演示编排器生成；官方 Skill/CLI、卖方服务和支付宝 OpenAPI 仍是产品行为来源。 - -#### 买方 Agent Adapter - -先为本次验证生成只用于证据关联的脱敏引用，例如： - -```bash -export ACT_DEMO_CORRELATION_REF=corr-sha256-a1b2 -export ACT_DEMO_VALIDATION_ID=E2E-YYYYMMDD-NNN -``` - -Buyer Adapter 接受宿主 Agent 产生的脱敏结构化信号，并把它们转换为 Demo 状态。它不调用支付、不解析 CLI 对客文本，也不接受完整 Proof。 - -```bash -npm run adapt:buyer -- /absolute/path/to/sanitized-buyer-signal.json -``` - -双方确认支付能力时，宿主 Agent 提交： - -```json -{ - "signal": "CAPABILITY_SELECTED", - "observed_from": "HOST_AGENT", - "source": "your-agent-runtime", - "evidence_ref": "E2E-YYYYMMDD-NNN#capability", - "correlation_ref": "corr-sha256-a1b2", - "method_id": "act-integration:a402/alipay-ai-pay", - "method_version": "1.0.0", - "psp_id": "alipay", - "endpoint_ref": "endpoint-sha256-redacted", - "method_schema_ref": "schema-sha256-redacted", - "capability_source_ref": "capability-sha256-redacted", - "capability_source_validated": true -} -``` - -`act-integration:a402/alipay-ai-pay` 是本仓库为 ACT A402 与支付宝 AI 按量付费映射维护的非规范性集成标识，不是支付宝产品报文字段，也不代表 ACT 全局注册。官方沙箱联调证据必须固定使用已发布的映射版本，并同时记录仓库 Commit 和已核验的支付宝产品来源。订单确认使用 `ORDER_CONFIRMED` 信号并提供独立 `commerce_confirmation_ref`；A402 `request_fingerprint` 与支付订单引用由卖方在生成 `Payment-Needed` 时建立，不能伪装成 CID 确认摘要。 - -宿主 Agent 只有在官方支付宝支付工作流产生对应真实状态后，才能依次提交： - -| Adapter 信号 | `observed_from` | Demo 状态 | +| 场景 | 核心区别 | 支付宝实现边界 | |---|---|---| -| `AUTHORIZATION_REQUIRED` | `OFFICIAL_ALIPAY_PAYMENT_SKILL` | `USER_AUTHORIZATION_REQUIRED` | -| `PAYMENT_STARTED` | `OFFICIAL_ALIPAY_PAYMENT_SKILL` | `PAYMENT_PROCESSING` | -| `PAYMENT_SUCCEEDED` | `OFFICIAL_ALIPAY_PAYMENT_SKILL` | `PAYMENT_RESULT_RECEIVED` | -| `PAYMENT_PENDING` | `OFFICIAL_ALIPAY_PAYMENT_SKILL` | `PAYMENT_PENDING` | +| L1 / `PSD-PAY-INS` | 用户对每一笔支付核身确认 | 展示支付宝绑定、支付卡片和二维码占位图，均不可扫码 | +| L2 / `PSD-PAY-DEL` | 用户预先明确商品、商户、金额和次数，匹配后自动支付 | 仅演示 ACT 2.1 语义，本仓库不声明支付宝 L2 实现 | +| L3 / `PSD-PAY-AUP` | 用户给出任务与预算边界，Agent 在边界内自主选择和支付 | 仅演示 ACT 2.1 语义，本仓库不声明支付宝 L3 实现 | -`PAYMENT_SUCCEEDED` 必须提供脱敏 `transaction_ref` 和 `proof_ref`；`PAYMENT_PENDING` 必须提供 `recovery_action`。错误来源、能力声明来源未验证、关联事实漂移、敏感字段或乱序事件都会被拒绝。 +每个场景均展示 `CID-PCA-NEG`、商业确认、资源请求、HTTP 402、`Payment-Needed`、支付处理、携 `Payment-Proof` 重试原请求、验款、资源交付和履约确认。异常选项覆盖支付结果未知、Proof 不匹配、验款不可用和幂等重试。 -#### 卖方接入 Adapter +## 运行 -在卖方服务的本地环境中增加： +在仓库根目录执行： ```bash -ACT_DEMO_BRIDGE_URL=http://127.0.0.1:4173/events -ACT_DEMO_VALIDATION_ID=E2E-YYYYMMDD-NNN -ACT_DEMO_CORRELATION_REF=corr-sha256-redacted +npm --prefix code/web-client/alipay-ai-pay-showcase run demo ``` -启用后，卖方接入示例会以非阻断方式输出： - -- 首次资源请求； -- 402 账单； -- 携 Proof 的原请求重试； -- 官方验款通过； -- 资源交付； -- 卖方履约确认。 - -验款拒绝时输出 `PROOF_REJECTED`；验款服务不可用时输出 `VERIFICATION_UNAVAILABLE`。失败终态不再输出资源交付。 - -未配置这两个变量时，卖方行为与之前完全一致。Adapter 连接失败不会改变支付、验款或交付结果。 - -### Sanitized Replay +浏览器打开 `http://127.0.0.1:4173/`，选择 L1、L2 或 L3，再逐步或自动播放。 -在页面切换到 Replay，选择通过校验器的 NDJSON 文件。页面会先验证所选场景的完整状态链，再允许逐步或自动播放，并始终显示 `SANITIZED REPLAY`。 +## 边界 -仓库不附带成功 Replay。第一份 Replay 必须来自已经通过的官网沙箱验证。 +- 页面中的订单、金额、交易引用、二维码和结果均为说明性演示数据。 +- Demo 不验证真实 `Payment-Proof`，不提供支付成功证据，也不构成一致性认证。 +- ACT 语义以 [`docs/specification/`](../../../docs/specification/README.md) 中的正式规范为准。 +- 支付宝产品接入以 [AIPay 官网](https://aipay.alipay.com/callpay)及其官方接入文档为准；本仓库只在 [`integrations/alipay/`](../../../integrations/alipay/README.md) 提供参考接入。 +- 官网沙箱由支付宝提供和运行，本 Demo 不复制、不代理，也不提供“连接沙箱”功能。 -完成一条 Live 链路后，先导出原始脱敏事件： +## 检查 ```bash -curl --fail http://127.0.0.1:4173/events/export \ - --output /absolute/path/to/live-sandbox-evidence.ndjson -node validate-evidence.mjs /absolute/path/to/live-sandbox-evidence.ndjson +npm --prefix code/web-client/alipay-ai-pay-showcase test +npm --prefix code/web-client/alipay-ai-pay-showcase run build ``` - -人工复核文件不含密钥、令牌、完整 Proof、完整业务标识或可重放请求后，生成 Replay： - -```bash -npm run prepare:replay -- /absolute/path/to/live-sandbox-evidence.ndjson \ - --validation-id E2E-YYYYMMDD-NNN \ - --reviewed-by review-record-ref \ - --ack-sanitized \ - > /absolute/path/to/sanitized-replay.ndjson -node validate-evidence.mjs /absolute/path/to/sanitized-replay.ndjson -``` - -`--ack-sanitized` 是人工复核声明，不是自动脱敏功能。工具会再次检查完整性和明显敏感文本，但不能代替安全审查。 - -## 复用的接入与样例 - -- [买方 Agent Payment](../../../integrations/alipay/buyer-agent/README.md) -- [卖方 Metered REST Provider](../../../integrations/alipay/seller-java/README.md) -- [通用本地 A402 样例](../../samples/local-a402/README.md) - -Demo 不能复制这些目录中的协议或产品逻辑。需要改变支付处理时先修改并验证相应接入，再由 Demo 消费其事件。 - -沙箱联调使用 [AIPay 官网接入指南](https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html)；完成后按 [ACT 沙箱验证补充](../../../integrations/alipay/validation/README.md)生成脱敏证据。 - -## 安全边界 - -不得进入 Demo 制品、日志、录屏或 Replay 数据： - -- 私钥、公钥文件路径以外的密钥内容； -- 绑定码、支付密码、访问令牌和 `app_auth_token`； -- 完整 `Payment-Proof` 或 `client_session`； -- 可重放 HTTP 请求； -- 完整订单号、交易号和用户标识。 - -## ACT 2.1 与产品事实 - -ACT 2.1 使用 `method_id`、`CID-PCA-NEG` 和 `Payment-Validation`。Demo 在界面中并列展示 ACT 语义和支付宝实现映射，不修改支付宝官网产品报文；对于 `Payment-Validation`，当前只展示： - -```text -ACT 2.1 Payment-Validation → Alipay payment.verify result -``` - -这不是在声明支付宝官网已支持同名响应 Header。产品接入、沙箱与正式接口事实始终以 AIPay 官网为准。 - -## 能力边界 - -Guided Demo、Live Bridge、多场景状态机、Buyer Runtime Adapter、卖方接入 Adapter、完整证据导出和 Replay 准备工具均已提供。Guided Demo 是说明性数据；Live 与 Replay 只有在接入官方 Skill/CLI 和官网沙箱产生真实脱敏事件后，才能作为特定版本的互操作证据。 diff --git a/code/web-client/alipay-ai-pay-showcase/bridge-server.mjs b/code/web-client/alipay-ai-pay-showcase/bridge-server.mjs deleted file mode 100644 index cb43af8..0000000 --- a/code/web-client/alipay-ai-pay-showcase/bridge-server.mjs +++ /dev/null @@ -1,267 +0,0 @@ -import { createServer } from "node:http"; -import { readFile, stat } from "node:fs/promises"; -import { extname, join, normalize } from "node:path"; -import { assertNoSensitiveFields, statesForScenario, validateEvidenceEvent } from "./validate-evidence.mjs"; - -const types = { - ".css": "text/css; charset=utf-8", - ".html": "text/html; charset=utf-8", - ".js": "text/javascript; charset=utf-8", - ".json": "application/json; charset=utf-8", -}; - -const displayFields = new Set([ - "state", - "source", - "evidence_ref", - "amount", - "currency", - "resource_id", - "goods_name", - "seller_name", - "result_summary", - "scenario", - "correlation_ref", - "method_id", - "method_version", - "psp_id", - "endpoint_ref", - "method_schema_ref", - "capability_source_ref", - "capability_source_validated", - "commerce_confirmation_ref", - "request_ref", - "request_digest", - "request_fingerprint", - "http_method", - "order_ref", - "proof_ref", - "transaction_ref", - "delivery_ref", - "fulfillment_ref", - "product_fulfillment_status", - "profile_mapping", - "validation_mapping", - "idempotent_replay", - "payment_action", - "delivery_action", - "fulfillment_action", - "tsd_evidence_ref", - "recovery_action", -]); - -const inheritedContextFields = [ - "method_id", "method_version", "psp_id", "endpoint_ref", "method_schema_ref", - "capability_source_ref", "capability_source_validated", "commerce_confirmation_ref", - "request_ref", "request_fingerprint", "http_method", "order_ref", "proof_ref", - "transaction_ref", "amount", "currency", "resource_id", "profile_mapping", -]; - -export function createDemoServer({ root, host = "127.0.0.1", port = 4173 }) { - const clients = new Set(); - const events = []; - let scenario = "SUCCESS"; - let listeningPort = null; - - const server = createServer(async (request, response) => { - const url = new URL(request.url, `http://${request.headers.host || `${host}:${port}`}`); - - if (request.method === "GET" && url.pathname === "/events") { - response.writeHead(200, { - "Content-Type": "text/event-stream; charset=utf-8", - "Cache-Control": "no-store", - "Connection": "keep-alive", - "X-Accel-Buffering": "no", - }); - response.write(": ACT demo event stream\n\n"); - events.forEach((event) => response.write(`data: ${JSON.stringify(event)}\n\n`)); - clients.add(response); - request.on("close", () => clients.delete(response)); - return; - } - - if (request.method === "GET" && url.pathname === "/events/state") { - const requiredStates = statesForScenario(scenario); - sendJson(response, 200, { - scenario, - event_count: events.length, - next_state: requiredStates[events.length] || null, - complete: events.length === requiredStates.length, - }); - return; - } - - if (request.method === "GET" && url.pathname === "/events/export") { - const requiredStates = statesForScenario(scenario); - if (events.length !== requiredStates.length) { - sendJson(response, 409, { - error: "evidence_incomplete", - scenario, - event_count: events.length, - expected_count: requiredStates.length, - next_state: requiredStates[events.length] || null, - }); - return; - } - response.writeHead(200, { - "Content-Type": "application/x-ndjson; charset=utf-8", - "Content-Disposition": "attachment; filename=act-live-sandbox-evidence.ndjson", - "Cache-Control": "no-store", - }); - response.end(`${events.map((event) => JSON.stringify(event)).join("\n")}\n`); - return; - } - - if (request.method === "POST" && url.pathname === "/events/reset") { - try { - const body = await readOptionalJson(request); - const nextScenario = body?.scenario || "SUCCESS"; - const requiredStates = statesForScenario(nextScenario); - scenario = nextScenario; - events.splice(0, events.length); - broadcast(clients, "event: reset\ndata: {}\n\n"); - sendJson(response, 200, { scenario, event_count: 0, next_state: requiredStates[0] }); - } catch (error) { - sendJson(response, 400, { error: "reset_rejected", message: error.message }); - } - return; - } - - if (request.method === "POST" && url.pathname === "/events") { - try { - const input = await readJson(request); - assertNoSensitiveFields(input); - if (events.length === 0 && input.scenario) scenario = input.scenario; - const event = normalizeEvent(input, events.length, scenario, events); - validateEvidenceEvent(event, events.length, "LIVE_SANDBOX", scenario); - const prior = events.at(-1); - if (prior && Date.parse(event.occurred_at) < Date.parse(prior.occurred_at)) { - throw new Error("event timestamps must not move backwards"); - } - events.push(event); - broadcast(clients, `data: ${JSON.stringify(event)}\n\n`); - sendJson(response, 202, event); - } catch (error) { - sendJson(response, 400, { error: "event_rejected", message: error.message }); - } - return; - } - - if (request.method !== "GET" && request.method !== "HEAD") { - sendJson(response, 405, { error: "method_not_allowed" }); - return; - } - - await serveStatic(root, url.pathname, request.method, response); - }); - - return { - async start() { - await new Promise((resolve, reject) => { - server.once("error", reject); - server.listen(port, host, () => { - server.removeListener("error", reject); - listeningPort = server.address().port; - resolve(); - }); - }); - }, - port() { - if (listeningPort === null) throw new Error("server is not listening"); - return listeningPort; - }, - async close() { - clients.forEach((client) => client.end()); - clients.clear(); - if (!server.listening) return; - await new Promise((resolve, reject) => - server.close((error) => error ? reject(error) : resolve())); - }, - }; -} - -function normalizeEvent(input, index, scenario, priorEvents) { - const event = { - sequence: index + 1, - mode: "LIVE_SANDBOX", - environment: "SANDBOX", - scenario, - occurred_at: input.occurred_at || new Date().toISOString(), - }; - for (const key of inheritedContextFields) { - for (let priorIndex = priorEvents.length - 1; priorIndex >= 0; priorIndex -= 1) { - if (priorEvents[priorIndex][key] !== undefined) { - event[key] = priorEvents[priorIndex][key]; - break; - } - } - } - for (const key of displayFields) { - if (input[key] !== undefined) event[key] = input[key]; - } - return event; -} - -async function readOptionalJson(request) { - const chunks = []; - let size = 0; - for await (const chunk of request) { - size += chunk.length; - if (size > 4 * 1024) throw new Error("reset body is too large"); - chunks.push(chunk); - } - if (chunks.length === 0) return null; - try { - return JSON.parse(Buffer.concat(chunks).toString("utf8")); - } catch { - throw new Error("event body is not valid JSON"); - } -} - -async function readJson(request) { - const chunks = []; - let size = 0; - for await (const chunk of request) { - size += chunk.length; - if (size > 32 * 1024) throw new Error("event body is too large"); - chunks.push(chunk); - } - if (chunks.length === 0) throw new Error("event body is empty"); - try { - return JSON.parse(Buffer.concat(chunks).toString("utf8")); - } catch { - throw new Error("event body is not valid JSON"); - } -} - -function broadcast(clients, message) { - clients.forEach((client) => client.write(message)); -} - -async function serveStatic(root, pathname, method, response) { - const candidate = normalize(join(root, pathname === "/" ? "index.html" : pathname)); - if (!candidate.startsWith(`${root}/`) && candidate !== root) { - sendJson(response, 403, { error: "forbidden" }); - return; - } - try { - const metadata = await stat(candidate); - const path = metadata.isDirectory() ? join(candidate, "index.html") : candidate; - const body = method === "HEAD" ? null : await readFile(path); - response.writeHead(200, { - "Content-Type": types[extname(path)] || "application/octet-stream", - "Cache-Control": "no-store", - }); - response.end(body); - } catch { - sendJson(response, 404, { error: "not_found" }); - } -} - -function sendJson(response, status, body) { - response.writeHead(status, { - "Content-Type": "application/json; charset=utf-8", - "Cache-Control": "no-store", - }); - response.end(JSON.stringify(body)); -} diff --git a/code/web-client/alipay-ai-pay-showcase/bridge-server.test.mjs b/code/web-client/alipay-ai-pay-showcase/bridge-server.test.mjs deleted file mode 100644 index 75dbb91..0000000 --- a/code/web-client/alipay-ai-pay-showcase/bridge-server.test.mjs +++ /dev/null @@ -1,209 +0,0 @@ -import test from "node:test"; -import assert from "node:assert/strict"; -import { dirname, join } from "node:path"; -import { fileURLToPath } from "node:url"; -import { createDemoServer } from "./bridge-server.mjs"; - -const root = join(dirname(fileURLToPath(import.meta.url)), "public"); -const capabilityFacts = { - method_id: "act-integration:a402/alipay-ai-pay", - method_version: "1.0.0", - psp_id: "alipay", - endpoint_ref: "endpoint-sha256-a1b2", - method_schema_ref: "schema-sha256-a1b2", - capability_source_ref: "capability-sha256-a1b2", - capability_source_validated: true, -}; -const chainFacts = { - commerce_confirmation_ref: "commerce-sha256-a1b2", - request_ref: "req-sha256-a1b2", - request_fingerprint: "sha-256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", - http_method: "GET", - order_ref: "order-sha256-a1b2", - resource_id: "resource-demo", - amount: "0.01", - currency: "CNY", - profile_mapping: "ALIPAY_PRODUCT_PAYLOAD_TO_ACT_2_1_EVIDENCE", - transaction_ref: "trade-sha256-a1b2", - proof_ref: "proof-sha256-a1b2", -}; - -async function withServer(run) { - const demo = createDemoServer({ root, port: 0 }); - await demo.start(); - try { - await run(`http://127.0.0.1:${demo.port()}`); - } finally { - await demo.close(); - } -} - -test("accepts the next sanitized live event and reports state", async () => { - await withServer(async (base) => { - const accepted = await fetch(`${base}/events`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - state: "CAPABILITY_NEGOTIATED", - source: "buyer-agent-adapter", - evidence_ref: "E2E-20260725-001#step-1", - correlation_ref: "corr-sha256-a1b2", - ...capabilityFacts, - }), - }); - assert.equal(accepted.status, 202); - const event = await accepted.json(); - assert.equal(event.sequence, 1); - assert.equal(event.mode, "LIVE_SANDBOX"); - assert.equal(event.environment, "SANDBOX"); - - const state = await fetch(`${base}/events/state`).then((response) => response.json()); - assert.deepEqual(state, { - scenario: "SUCCESS", - event_count: 1, - next_state: "ORDER_CONFIRMED", - complete: false, - }); - }); -}); - -test("rejects out-of-order and sensitive events", async () => { - await withServer(async (base) => { - const outOfOrder = await fetch(`${base}/events`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - state: "PAYMENT_VERIFIED", - source: "seller-provider", - evidence_ref: "E2E-20260725-002#step-5", - correlation_ref: "corr-sha256-a1b2", - }), - }); - assert.equal(outOfOrder.status, 400); - - const sensitive = await fetch(`${base}/events`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - state: "CAPABILITY_NEGOTIATED", - source: "buyer-agent-adapter", - evidence_ref: "E2E-20260725-002#step-1", - correlation_ref: "corr-sha256-a1b2", - ...capabilityFacts, - payment_proof: "must-not-enter-demo", - }), - }); - assert.equal(sensitive.status, 400); - assert.match((await sensitive.json()).message, /forbidden sensitive field/); - }); -}); - -test("reset clears the live sequence", async () => { - await withServer(async (base) => { - await fetch(`${base}/events`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - state: "CAPABILITY_NEGOTIATED", - source: "buyer-agent-adapter", - evidence_ref: "E2E-20260725-003#step-1", - correlation_ref: "corr-sha256-a1b2", - ...capabilityFacts, - }), - }); - const reset = await fetch(`${base}/events/reset`, { method: "POST" }); - assert.equal(reset.status, 200); - assert.deepEqual(await reset.json(), { - scenario: "SUCCESS", - event_count: 0, - next_state: "CAPABILITY_NEGOTIATED", - }); - }); -}); - -test("accepts a complete correlated success chain", async () => { - await withServer(async (base) => { - const states = [ - "CAPABILITY_NEGOTIATED", "ORDER_CONFIRMED", "RESOURCE_REQUESTED", "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", "PAYMENT_PROCESSING", "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", "PAYMENT_VERIFIED", "RESOURCE_DELIVERED", - "FULFILLMENT_CONFIRMED", - ]; - for (const [index, state] of states.entries()) { - const response = await fetch(`${base}/events`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - state, - source: index < 2 ? "buyer-agent-adapter" : "official-sandbox-workflow", - evidence_ref: `E2E-20260725-004#step-${index + 1}`, - correlation_ref: "corr-sha256-complete", - ...(state === "CAPABILITY_NEGOTIATED" ? capabilityFacts : {}), - ...(state === "ORDER_CONFIRMED" ? { commerce_confirmation_ref: chainFacts.commerce_confirmation_ref } : {}), - ...(state === "RESOURCE_REQUESTED" ? { request_ref: chainFacts.request_ref, http_method: "GET" } : {}), - ...(state === "PAYMENT_REQUIRED" ? { - request_fingerprint: chainFacts.request_fingerprint, - order_ref: chainFacts.order_ref, - resource_id: chainFacts.resource_id, - amount: chainFacts.amount, - currency: chainFacts.currency, - profile_mapping: chainFacts.profile_mapping, - } : {}), - ...(state === "PAYMENT_RESULT_RECEIVED" ? { - transaction_ref: chainFacts.transaction_ref, - proof_ref: chainFacts.proof_ref, - } : {}), - ...(state === "PAYMENT_VERIFIED" ? { - validation_mapping: "ACT 2.1 evidence ← Alipay payment.verify result", - } : {}), - ...(state === "RESOURCE_DELIVERED" ? { delivery_ref: "delivery-sha256-a1b2" } : {}), - ...(state === "FULFILLMENT_CONFIRMED" ? { - fulfillment_ref: "fulfillment-sha256-a1b2", - product_fulfillment_status: "CONFIRMED", - } : {}), - }), - }); - assert.equal(response.status, 202, `expected ${state} to be accepted`); - } - assert.deepEqual(await fetch(`${base}/events/state`).then((response) => response.json()), { - scenario: "SUCCESS", - event_count: 11, - next_state: null, - complete: true, - }); - const evidence = await fetch(`${base}/events/export`); - assert.equal(evidence.status, 200); - const lines = (await evidence.text()).trim().split("\n").map(JSON.parse); - assert.equal(lines.length, 11); - assert.equal(lines[0].mode, "LIVE_SANDBOX"); - }); -}); - -test("refuses to export an incomplete live chain", async () => { - await withServer(async (base) => { - const response = await fetch(`${base}/events/export`); - assert.equal(response.status, 409); - const body = await response.json(); - assert.equal(body.error, "evidence_incomplete"); - assert.equal(body.next_state, "CAPABILITY_NEGOTIATED"); - }); -}); - -test("supports an explicit failure scenario and rejects invalid reset scenarios", async () => { - await withServer(async (base) => { - const reset = await fetch(`${base}/events/reset`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ scenario: "PROOF_MISMATCH" }), - }); - assert.equal(reset.status, 200); - assert.equal((await reset.json()).scenario, "PROOF_MISMATCH"); - - const rejected = await fetch(`${base}/events/reset`, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ scenario: "UNKNOWN" }), - }); - assert.equal(rejected.status, 400); - }); -}); diff --git a/code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.mjs b/code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.mjs deleted file mode 100644 index 79b8e40..0000000 --- a/code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.mjs +++ /dev/null @@ -1,141 +0,0 @@ -import { readFile } from "node:fs/promises"; -import { pathToFileURL } from "node:url"; -import { assertNoSensitiveFields } from "./validate-evidence.mjs"; - -const SIGNALS = Object.freeze({ - CAPABILITY_SELECTED: { - state: "CAPABILITY_NEGOTIATED", - observedFrom: "HOST_AGENT", - required: [ - "method_id", "method_version", "psp_id", "endpoint_ref", "method_schema_ref", - "capability_source_ref", - ], - }, - ORDER_CONFIRMED: { - state: "ORDER_CONFIRMED", - observedFrom: "HOST_AGENT", - required: ["commerce_confirmation_ref"], - }, - AUTHORIZATION_REQUIRED: { - state: "USER_AUTHORIZATION_REQUIRED", - observedFrom: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - required: [], - }, - PAYMENT_STARTED: { - state: "PAYMENT_PROCESSING", - observedFrom: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - required: [], - }, - PAYMENT_SUCCEEDED: { - state: "PAYMENT_RESULT_RECEIVED", - observedFrom: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - required: ["transaction_ref", "proof_ref"], - }, - PAYMENT_PENDING: { - state: "PAYMENT_PENDING", - observedFrom: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - required: ["recovery_action"], - }, -}); - -const COMMON_REQUIRED = ["source", "evidence_ref", "correlation_ref", "observed_from"]; -const FORWARDED_FIELDS = new Set([ - "source", - "evidence_ref", - "correlation_ref", - "method_id", - "method_version", - "psp_id", - "endpoint_ref", - "method_schema_ref", - "capability_source_ref", - "capability_source_validated", - "commerce_confirmation_ref", - "request_ref", - "request_digest", - "request_fingerprint", - "http_method", - "order_ref", - "proof_ref", - "transaction_ref", - "amount", - "currency", - "resource_id", - "goods_name", - "seller_name", - "result_summary", - "recovery_action", -]); -const INPUT_FIELDS = new Set(["signal", "observed_from", ...FORWARDED_FIELDS]); - -export function toDemoEvent(input) { - if (!input || typeof input !== "object" || Array.isArray(input)) { - throw new Error("buyer adapter input must be a JSON object"); - } - assertNoSensitiveFields(input, "buyer adapter input"); - for (const key of Object.keys(input)) { - if (!INPUT_FIELDS.has(key)) throw new Error(`unsupported buyer adapter field: ${key}`); - } - - const definition = SIGNALS[input.signal]; - if (!definition) { - throw new Error(`signal must be one of: ${Object.keys(SIGNALS).join(", ")}`); - } - if (input.observed_from !== definition.observedFrom) { - throw new Error( - `${input.signal} must be observed from ${definition.observedFrom}, not ${input.observed_from || "missing"}`, - ); - } - for (const field of [...COMMON_REQUIRED, ...definition.required]) { - if (typeof input[field] !== "string" || input[field].trim() === "") { - throw new Error(`${input.signal} requires ${field}`); - } - } - if (input.signal === "CAPABILITY_SELECTED" && input.capability_source_validated !== true) { - throw new Error("CAPABILITY_SELECTED requires capability_source_validated=true"); - } - if (/mock/i.test(input.source)) throw new Error("source must identify a non-Mock runtime"); - - const event = { state: definition.state }; - for (const field of FORWARDED_FIELDS) { - if (input[field] !== undefined) event[field] = input[field]; - } - return event; -} - -export async function postBuyerSignal(input, { - bridge = process.env.ACT_DEMO_BRIDGE_URL || "http://127.0.0.1:4173/events", - fetchImpl = fetch, -} = {}) { - const event = toDemoEvent(input); - const response = await fetchImpl(bridge, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(event), - }); - const result = await response.json(); - if (!response.ok) { - throw new Error(`${result.error || "event rejected"}: ${result.message || response.status}`); - } - return result; -} - -async function readInput(path) { - if (!path) throw new Error("usage: node buyer-event-adapter.mjs "); - if (path !== "-") return JSON.parse(await readFile(path, "utf8")); - const chunks = []; - for await (const chunk of process.stdin) chunks.push(chunk); - return JSON.parse(Buffer.concat(chunks).toString("utf8")); -} - -async function main() { - const result = await postBuyerSignal(await readInput(process.argv[2])); - process.stdout.write(`accepted ${result.sequence} ${result.state}\n`); -} - -if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { - main().catch((error) => { - process.stderr.write(`[FAIL] ${error.message}\n`); - process.exitCode = 1; - }); -} diff --git a/code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.test.mjs b/code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.test.mjs deleted file mode 100644 index ce3a87c..0000000 --- a/code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.test.mjs +++ /dev/null @@ -1,89 +0,0 @@ -import test from "node:test"; -import assert from "node:assert/strict"; -import { postBuyerSignal, toDemoEvent } from "./buyer-event-adapter.mjs"; - -const common = { - source: "codex-with-official-alipay-payment-skill", - evidence_ref: "E2E-20260727-001#buyer", - correlation_ref: "corr-sha256-a1b2", -}; - -test("maps host and official payment signals to demo states", () => { - assert.deepEqual(toDemoEvent({ - ...common, - signal: "CAPABILITY_SELECTED", - observed_from: "HOST_AGENT", - method_id: "act-integration:a402/alipay-ai-pay", - method_version: "1.0.0", - psp_id: "alipay", - endpoint_ref: "endpoint-sha256-a1b2", - method_schema_ref: "schema-sha256-a1b2", - capability_source_ref: "capability-sha256-a1b2", - capability_source_validated: true, - }), { - state: "CAPABILITY_NEGOTIATED", - source: common.source, - evidence_ref: common.evidence_ref, - correlation_ref: common.correlation_ref, - method_id: "act-integration:a402/alipay-ai-pay", - method_version: "1.0.0", - psp_id: "alipay", - endpoint_ref: "endpoint-sha256-a1b2", - method_schema_ref: "schema-sha256-a1b2", - capability_source_ref: "capability-sha256-a1b2", - capability_source_validated: true, - }); - - assert.equal(toDemoEvent({ - ...common, - signal: "PAYMENT_SUCCEEDED", - observed_from: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - transaction_ref: "trade-sha256-8c11", - proof_ref: "proof-sha256-8c11", - }).state, "PAYMENT_RESULT_RECEIVED"); -}); - -test("rejects wrong provenance, sensitive material, and incomplete success", () => { - assert.throws(() => toDemoEvent({ - ...common, - signal: "PAYMENT_STARTED", - observed_from: "HOST_AGENT", - }), /must be observed from OFFICIAL_ALIPAY_PAYMENT_SKILL/); - - assert.throws(() => toDemoEvent({ - ...common, - signal: "PAYMENT_SUCCEEDED", - observed_from: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - payment_proof: "must-not-enter-demo", - }), /forbidden sensitive field/); - - assert.throws(() => toDemoEvent({ - ...common, - signal: "PAYMENT_SUCCEEDED", - observed_from: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - }), /requires transaction_ref/); -}); - -test("posts only the mapped, allow-listed event", async () => { - let submitted; - const result = await postBuyerSignal({ - ...common, - signal: "PAYMENT_PENDING", - observed_from: "OFFICIAL_ALIPAY_PAYMENT_SKILL", - recovery_action: "QUERY_ORIGINAL_PAYMENT", - }, { - bridge: "http://bridge.invalid/events", - fetchImpl: async (url, init) => { - submitted = { url, init, body: JSON.parse(init.body) }; - return new Response(JSON.stringify({ sequence: 7, state: "PAYMENT_PENDING" }), { - status: 202, - headers: { "Content-Type": "application/json" }, - }); - }, - }); - - assert.equal(result.state, "PAYMENT_PENDING"); - assert.equal(submitted.url, "http://bridge.invalid/events"); - assert.equal(submitted.body.state, "PAYMENT_PENDING"); - assert.equal(submitted.body.observed_from, undefined); -}); diff --git a/code/web-client/alipay-ai-pay-showcase/emit-event.mjs b/code/web-client/alipay-ai-pay-showcase/emit-event.mjs deleted file mode 100644 index ca73cd6..0000000 --- a/code/web-client/alipay-ai-pay-showcase/emit-event.mjs +++ /dev/null @@ -1,124 +0,0 @@ -const allowedStates = [ - "CAPABILITY_NEGOTIATED", - "ORDER_CONFIRMED", - "RESOURCE_REQUESTED", - "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", - "PAYMENT_PROCESSING", - "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", - "PAYMENT_VERIFIED", - "RESOURCE_DELIVERED", - "FULFILLMENT_CONFIRMED", - "PAYMENT_PENDING", - "PROOF_REJECTED", - "VERIFICATION_UNAVAILABLE", -]; -const allowedOptions = new Set([ - "source", - "evidence-ref", - "amount", - "currency", - "resource-id", - "goods-name", - "seller-name", - "result-summary", - "scenario", - "correlation-ref", - "method-id", - "method-version", - "psp-id", - "endpoint-ref", - "method-schema-ref", - "capability-source-ref", - "commerce-confirmation-ref", - "request-ref", - "request-digest", - "request-fingerprint", - "http-method", - "order-ref", - "proof-ref", - "transaction-ref", - "fulfillment-ref", - "delivery-ref", - "profile-mapping", - "product-fulfillment-status", - "validation-mapping", - "recovery-action", - "bridge", -]); - -const [state, ...args] = process.argv.slice(2); -if (!allowedStates.includes(state)) { - fail(`state must be one of: ${allowedStates.join(", ")}`); -} - -const options = parseOptions(args); -if (!options.source) fail("--source is required"); -if (!options["evidence-ref"]) fail("--evidence-ref is required"); -if (!options["correlation-ref"]) fail("--correlation-ref is required"); -if (/mock/i.test(options.source)) fail("--source must identify a non-Mock runtime source"); - -const bridge = options.bridge || process.env.ACT_DEMO_BRIDGE_URL || "http://127.0.0.1:4173/events"; -const event = { - state, - source: options.source, - evidence_ref: options["evidence-ref"], - scenario: options.scenario, - correlation_ref: options["correlation-ref"], - method_id: options["method-id"], - method_version: options["method-version"], - psp_id: options["psp-id"], - endpoint_ref: options["endpoint-ref"], - method_schema_ref: options["method-schema-ref"], - capability_source_ref: options["capability-source-ref"], - capability_source_validated: options["capability-source-ref"] ? true : undefined, - commerce_confirmation_ref: options["commerce-confirmation-ref"], - request_ref: options["request-ref"], - request_digest: options["request-digest"], - request_fingerprint: options["request-fingerprint"], - http_method: options["http-method"], - order_ref: options["order-ref"], - proof_ref: options["proof-ref"], - transaction_ref: options["transaction-ref"], - fulfillment_ref: options["fulfillment-ref"], - delivery_ref: options["delivery-ref"], - profile_mapping: options["profile-mapping"], - product_fulfillment_status: options["product-fulfillment-status"], - validation_mapping: options["validation-mapping"], - recovery_action: options["recovery-action"], - amount: options.amount, - currency: options.currency, - resource_id: options["resource-id"], - goods_name: options["goods-name"], - seller_name: options["seller-name"], - result_summary: options["result-summary"], -}; -Object.keys(event).forEach((key) => event[key] === undefined && delete event[key]); - -const response = await fetch(bridge, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(event), -}); -const result = await response.json(); -if (!response.ok) fail(`${result.error || "event rejected"}: ${result.message || response.status}`); -process.stdout.write(`accepted ${result.sequence} ${result.state}\n`); - -function parseOptions(values) { - const result = {}; - for (let index = 0; index < values.length; index += 2) { - const flag = values[index]; - const value = values[index + 1]; - if (!flag?.startsWith("--") || value === undefined) fail("options must use --name value pairs"); - const name = flag.slice(2); - if (!allowedOptions.has(name)) fail(`unsupported option: --${name}`); - result[name] = value; - } - return result; -} - -function fail(message) { - process.stderr.write(`[FAIL] ${message}\n`); - process.exit(1); -} diff --git a/code/web-client/alipay-ai-pay-showcase/event-format.md b/code/web-client/alipay-ai-pay-showcase/event-format.md deleted file mode 100644 index 1ea5b25..0000000 --- a/code/web-client/alipay-ai-pay-showcase/event-format.md +++ /dev/null @@ -1,80 +0,0 @@ -# Showcase 事件格式 - -> 状态：Demo event format / Non-normative。该格式只服务于演示编排与证据审查，不是 ACT 协议消息。 - -本格式只接受 `LIVE_SANDBOX` 和 `SANITIZED_REPLAY` 作为证据模式。Web 演示台内置的 `GUIDED_DEMO` 是说明性 UI 数据，校验器会拒绝将其作为支付证据。 - -证据文件使用 NDJSON，每行一个对象。成功闭环必须按顺序包含 11 个状态： - -```json -{"sequence":1,"state":"CAPABILITY_NEGOTIATED","scenario":"SUCCESS","mode":"LIVE_SANDBOX","source":"buyer-agent-quickstart","environment":"SANDBOX","occurred_at":"2026-07-22T12:00:00Z","evidence_ref":"E2E-20260722-001#step-1","correlation_ref":"corr-sha256-a1b2","method_id":"act-integration:a402/alipay-ai-pay","method_version":"1.0.0","psp_id":"alipay","endpoint_ref":"endpoint-sha256-redacted","method_schema_ref":"schema-sha256-redacted","capability_source_ref":"capability-sha256-redacted","capability_source_validated":true} -``` - -```text -CAPABILITY_NEGOTIATED -→ ORDER_CONFIRMED -→ RESOURCE_REQUESTED -→ PAYMENT_REQUIRED -→ USER_AUTHORIZATION_REQUIRED -→ PAYMENT_PROCESSING -→ PAYMENT_RESULT_RECEIVED -→ RESOURCE_REQUEST_RETRIED -→ PAYMENT_VERIFIED -→ RESOURCE_DELIVERED -→ FULFILLMENT_CONFIRMED -``` - -| 字段 | 要求 | -|---|---| -| `sequence` | 从 1 开始连续递增 | -| `state` | 必须属于所选场景的状态机，并严格有序 | -| `scenario` | `SUCCESS`、`PAYMENT_PENDING`、`PROOF_MISMATCH`、`VERIFICATION_UNAVAILABLE` 或 `IDEMPOTENT_REPLAY`；缺省为 `SUCCESS` | -| `mode` | 全文件统一为 `LIVE_SANDBOX` 或 `SANITIZED_REPLAY` | -| `source` | 产生该事件的接入示例、官方能力或验款步骤；不得为 Mock | -| `environment` | Live 模式必须为 `SANDBOX` | -| `occurred_at` | 可解析的 ISO 8601 时间，且不得倒序 | -| `evidence_ref` | 指向脱敏验证记录的引用，不得包含凭证或可重放 URL | -| `correlation_ref` | 同一链路共享的脱敏关联引用；不得使用完整业务订单号或交易号 | -| `sanitized` | Replay 模式必须为 `true` | -| `origin_validation_id` | Replay 模式必须引用原沙箱验证编号 | -| `method_id`、`method_version` | 所有状态必须保持一致；ID 使用非规范性 A402 artifact 命名空间格式，版本使用 SemVer | -| `psp_id`、`endpoint_ref`、`method_schema_ref` | `CAPABILITY_NEGOTIATED` 必填，使用脱敏引用展示协商结果 | -| `capability_source_ref`、`capability_source_validated` | 证明能力声明来自已验证来源；未验证不得进入支付 | -| `commerce_confirmation_ref` | `ORDER_CONFIRMED` 必填，是独立 CID 商业确认引用，不是 A402 请求指纹 | -| `request_fingerprint` | 从 `PAYMENT_REQUIRED` 到验款、交付保持一致，格式为 `sha-256:` | -| `order_ref`、`resource_id` | 从 `PAYMENT_REQUIRED` 开始稳定关联原账单与收费资源 | -| `proof_ref`、`transaction_ref` | 支付成功后必填，只允许脱敏引用 | -| `delivery_ref`、`fulfillment_ref` | 分别记录资源交付和产品履约确认，二者不得互相替代 | - -向本地 Live Bridge 的 `POST /events` 提交事件时，只需发送 `state`、`source`、`evidence_ref` 和允许的展示字段。Bridge 会补充 `sequence`、`mode=LIVE_SANDBOX`、`environment=SANDBOX` 和 `occurred_at`。这些是观察器元数据，不代替产品交易时间。 - -完整链路可通过 `GET /events/export` 导出；链路未到合法终态时接口返回 `409 evidence_incomplete`，避免将半条链路误作成功证据。Buyer Agent 应优先使用 [`buyer-event-adapter.mjs`](buyer-event-adapter.mjs) 接入结构化运行时状态，而不是直接拼装 Demo 状态。 - -页面允许下列可选展示字段，它们必须是脱敏摘要： - -| 字段 | 用途 | -|---|---| -| `amount`、`currency` | 展示账单金额，不表达金额单位换算规则 | -| `resource_id` | 展示脱敏资源标识 | -| `goods_name`、`seller_name` | 展示用户可理解的交易摘要 | -| `result_summary` | 展示不含敏感数据的交付或校验结论 | -| `method_id`、`psp_id` | 展示支付方法与 PSP 的发现、选择和回显 | -| `request_ref`、`request_digest`、`http_method` | 证明支付前后的原请求保持一致 | -| `order_ref`、`transaction_ref`、`fulfillment_ref` | 构成订单、支付与履约的脱敏关联链 | -| `validation_mapping` | 说明 ACT 2.1 `Payment-Validation` 语义与支付宝 `payment.verify` 的产品映射 | -| `profile_mapping` | 明确当前事实来自 Alipay integration mapping，而不是支付宝报文中的 ACT artifact 字段 | -| `idempotent_replay`、`payment_action`、`delivery_action`、`fulfillment_action` | 第二次请求证明没有新支付、没有重复非幂等交付、没有重复履约确认 | -| `recovery_action` | 失败终态对应的机器可执行恢复动作 | - -失败链路是合法证据，不得补造成功事件： - -- `PAYMENT_PENDING`：终止于 `PAYMENT_PENDING`，查询原交易且不得再次付款； -- `PROOF_MISMATCH`：终止于 `PROOF_REJECTED`，不得交付； -- `VERIFICATION_UNAVAILABLE`：终止于 `VERIFICATION_UNAVAILABLE`，按原交易重试验款且不得交付。 -- `IDEMPOTENT_REPLAY`：先完成 11 步正常链路，再追加第二次 `RESOURCE_REQUEST_RETRIED → PAYMENT_VERIFIED → RESOURCE_DELIVERED`；最终事件必须声明 `idempotent_replay=true`、`NO_NEW_PAYMENT`、`RETURN_PRIOR_RESULT` 和 `NOT_REPEATED`。 - -TSD 证据不属于上述 11/14 步成功条件。若实现异步形成脱敏 TSD 证据，可以使用独立 `tsd_evidence_ref` 展示，但不得由 `fulfillment.confirm` 自动推导或冒充。 - -页面不显示任意扩展字段，并递归拒绝明显的密钥、令牌、完整 Proof、`client_session`、绑定码和密码字段。 - -不要写入业务响应全文。金额、订单和资源关联结论应保存在[端到端验证证据](../../../integrations/alipay/validation/evidence-template.md)中，事件仅保留引用。 diff --git a/code/web-client/alipay-ai-pay-showcase/guided-demo.test.mjs b/code/web-client/alipay-ai-pay-showcase/guided-demo.test.mjs new file mode 100644 index 0000000..7a1d165 --- /dev/null +++ b/code/web-client/alipay-ai-pay-showcase/guided-demo.test.mjs @@ -0,0 +1,28 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import test from "node:test"; + +const index = await readFile(new URL("./public/index.html", import.meta.url), "utf8"); +const app = await readFile(new URL("./public/app.js", import.meta.url), "utf8"); +const packageJson = JSON.parse(await readFile(new URL("./package.json", import.meta.url), "utf8")); + +test("offers guided L1, L2, and L3 scenarios", () => { + for (const level of ["L1", "L2", "L3"]) { + assert.match(index, new RegExp(`value="${level}"`)); + assert.match(app, new RegExp(`${level}: \\[`)); + } +}); + +test("does not expose a sandbox, live-event, or evidence-replay mode", () => { + const published = `${index}\n${app}\n${JSON.stringify(packageJson.scripts)}`; + for (const marker of ["LIVE_SANDBOX", "SANITIZED_REPLAY", "liveTab", "replayTab", "连接官方沙箱事件", "证据回放"]) { + assert.equal(published.includes(marker), false, `unexpected demo mode: ${marker}`); + } +}); + +test("keeps the demo explicitly non-operational", () => { + assert.match(index, /不会连接或执行真实支付/); + assert.equal(packageJson.scripts.emit, undefined); + assert.equal(packageJson.scripts["adapt:buyer"], undefined); + assert.equal(packageJson.scripts["prepare:replay"], undefined); +}); diff --git a/code/web-client/alipay-ai-pay-showcase/package.json b/code/web-client/alipay-ai-pay-showcase/package.json index 0de7080..6737102 100644 --- a/code/web-client/alipay-ai-pay-showcase/package.json +++ b/code/web-client/alipay-ai-pay-showcase/package.json @@ -6,10 +6,7 @@ "scripts": { "demo": "node server.mjs", "dev": "node server.mjs", - "emit": "node emit-event.mjs", - "adapt:buyer": "node buyer-event-adapter.mjs", - "prepare:replay": "node prepare-replay.mjs", "build": "node build.mjs", - "test": "node --test *.test.mjs" + "test": "node --test guided-demo.test.mjs" } } diff --git a/code/web-client/alipay-ai-pay-showcase/prepare-replay.mjs b/code/web-client/alipay-ai-pay-showcase/prepare-replay.mjs deleted file mode 100644 index 958e479..0000000 --- a/code/web-client/alipay-ai-pay-showcase/prepare-replay.mjs +++ /dev/null @@ -1,69 +0,0 @@ -import { readFile } from "node:fs/promises"; -import { pathToFileURL } from "node:url"; -import { parseEvents, validateEvents } from "./validate-evidence.mjs"; - -const FORBIDDEN_TEXT = [ - /-----BEGIN [A-Z ]*PRIVATE KEY-----/i, - /\b(?:access_token|app_auth_token|payment-proof|client_session|binding_code|password)\b/i, - /\bsk-[A-Za-z0-9_-]{12,}\b/, -]; - -export function createReplay(events, { validationId, reviewedBy, ackSanitized }) { - const live = validateEvents(events); - if (live.mode !== "LIVE_SANDBOX") throw new Error("replay input must be LIVE_SANDBOX evidence"); - if (!validationId?.trim()) throw new Error("--validation-id is required"); - if (!reviewedBy?.trim()) throw new Error("--reviewed-by is required"); - if (ackSanitized !== true) throw new Error("--ack-sanitized is required after manual review"); - - const serialized = JSON.stringify(events); - for (const pattern of FORBIDDEN_TEXT) { - if (pattern.test(serialized)) throw new Error(`evidence contains forbidden sensitive text: ${pattern}`); - } - - const replay = events.map((event) => ({ - ...event, - mode: "SANITIZED_REPLAY", - sanitized: true, - origin_validation_id: validationId.trim(), - sanitization_review_ref: reviewedBy.trim(), - })); - validateEvents(replay); - return replay; -} - -function parseArguments(args) { - const [path, ...options] = args; - const parsed = { path, ackSanitized: false }; - for (let index = 0; index < options.length; index += 1) { - const option = options[index]; - if (option === "--ack-sanitized") { - parsed.ackSanitized = true; - continue; - } - const value = options[index + 1]; - if (!value) throw new Error(`${option} requires a value`); - if (option === "--validation-id") parsed.validationId = value; - else if (option === "--reviewed-by") parsed.reviewedBy = value; - else throw new Error(`unsupported option: ${option}`); - index += 1; - } - return parsed; -} - -async function main() { - const options = parseArguments(process.argv.slice(2)); - if (!options.path) { - throw new Error( - "usage: node prepare-replay.mjs live.ndjson --validation-id --reviewed-by --ack-sanitized", - ); - } - const replay = createReplay(parseEvents(await readFile(options.path, "utf8")), options); - process.stdout.write(`${replay.map((event) => JSON.stringify(event)).join("\n")}\n`); -} - -if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { - main().catch((error) => { - process.stderr.write(`[FAIL] ${error.message}\n`); - process.exitCode = 1; - }); -} diff --git a/code/web-client/alipay-ai-pay-showcase/prepare-replay.test.mjs b/code/web-client/alipay-ai-pay-showcase/prepare-replay.test.mjs deleted file mode 100644 index 999f0eb..0000000 --- a/code/web-client/alipay-ai-pay-showcase/prepare-replay.test.mjs +++ /dev/null @@ -1,67 +0,0 @@ -import test from "node:test"; -import assert from "node:assert/strict"; -import { createReplay } from "./prepare-replay.mjs"; -import { SCENARIO_STATES, validateEvents } from "./validate-evidence.mjs"; - -function liveEvents() { - return SCENARIO_STATES.SUCCESS.map((state, index) => ({ - sequence: index + 1, - state, - scenario: "SUCCESS", - mode: "LIVE_SANDBOX", - environment: "SANDBOX", - source: index < 2 ? "buyer-agent-runtime" : "official-sandbox-workflow", - occurred_at: `2026-07-27T12:00:${String(index).padStart(2, "0")}Z`, - evidence_ref: `E2E-20260727-001#step-${index + 1}`, - correlation_ref: "corr-sha256-a1b2", - method_id: "act-integration:a402/alipay-ai-pay", - method_version: "1.0.0", - psp_id: "alipay", - endpoint_ref: "endpoint-sha256-a1b2", - method_schema_ref: "schema-sha256-a1b2", - capability_source_ref: "capability-sha256-a1b2", - capability_source_validated: true, - commerce_confirmation_ref: "commerce-sha256-a1b2", - request_ref: "req-sha256-41bd", - request_fingerprint: "sha-256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", - http_method: "GET", - order_ref: "order-sha256-92ae", - resource_id: "resource-demo", - amount: "0.01", - currency: "CNY", - profile_mapping: "ALIPAY_PRODUCT_PAYLOAD_TO_ACT_2_1_EVIDENCE", - transaction_ref: "trade-sha256-8c11", - proof_ref: "proof-sha256-8c11", - delivery_ref: "delivery-sha256-8c11", - fulfillment_ref: "fulfillment-sha256-8c11", - product_fulfillment_status: "CONFIRMED", - ...(state === "PAYMENT_VERIFIED" ? { validation_mapping: "ACT 2.1 evidence ← Alipay payment.verify result" } : {}), - })); -} - -test("creates a validator-compatible replay after explicit review", () => { - const replay = createReplay(liveEvents(), { - validationId: "E2E-20260727-001", - reviewedBy: "review-20260727-a", - ackSanitized: true, - }); - assert.equal(validateEvents(replay).mode, "SANITIZED_REPLAY"); - assert.equal(replay[0].origin_validation_id, "E2E-20260727-001"); - assert.equal(replay[0].sanitization_review_ref, "review-20260727-a"); -}); - -test("refuses unreviewed or sensitive evidence", () => { - assert.throws(() => createReplay(liveEvents(), { - validationId: "E2E-20260727-001", - reviewedBy: "review-20260727-a", - ackSanitized: false, - }), /ack-sanitized/); - - const unsafe = liveEvents(); - unsafe[1].result_summary = "app_auth_token must-not-leak"; - assert.throws(() => createReplay(unsafe, { - validationId: "E2E-20260727-001", - reviewedBy: "review-20260727-a", - ackSanitized: true, - }), /forbidden sensitive text/); -}); diff --git a/code/web-client/alipay-ai-pay-showcase/public/app.js b/code/web-client/alipay-ai-pay-showcase/public/app.js index 24632e5..12f042e 100644 --- a/code/web-client/alipay-ai-pay-showcase/public/app.js +++ b/code/web-client/alipay-ai-pay-showcase/public/app.js @@ -394,10 +394,9 @@ const authorizationCopy = { const elements = Object.fromEntries( [ "actBinding", "actComponent", "actDomain", "agentMessage", "alipayProduct", "controlStatus", - "correlationChain", "currentState", "eventCounter", "eventStreamUrl", "evidenceDetails", "baselineValue", "footerScenarioValue", - "evidenceRef", "exchangeCard", "fromActor", "directionArrow", "layerCode", "liveForm", - "liveTab", "methodId", "modeBadge", "phaseRail", "playReplay", - "replayControls", "replayFile", "replayTab", "playDemo", "demoControls", "demoTab", + "correlationChain", "currentState", "eventCounter", "evidenceDetails", "baselineValue", "footerScenarioValue", + "evidenceRef", "exchangeCard", "fromActor", "directionArrow", "layerCode", + "methodId", "modeBadge", "phaseRail", "playDemo", "demoControls", "resetDemo", "resourceCard", "resourceDescription", "resourceId", "resourcePrice", "resourceState", "resourceTitle", "scenarioSelect", "stateExplanation", "stepDemo", "stepReplay", "taskResult", "taskStatusDot", "timeline", "toActor", "wireBadge", "wireMessage", @@ -412,26 +411,15 @@ const elements = Object.fromEntries( ].map((id) => [id, document.getElementById(id)]), ); -let mode = "GUIDED_DEMO"; +const mode = "GUIDED_DEMO"; let scenario = "SUCCESS"; let authorizationLevel = "L1"; let events = []; -let replayEvents = []; -let replayIndex = 0; -let replayTimer = null; -let eventSource = null; let demoEvents = []; let demoIndex = 0; let demoTimer = null; -const operationalL1Flow = [ - "CAPABILITY_NEGOTIATED", "ORDER_CONFIRMED", "RESOURCE_REQUESTED", "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", "PAYMENT_PROCESSING", "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", "PAYMENT_VERIFIED", "RESOURCE_DELIVERED", "FULFILLMENT_CONFIRMED", -]; - function successFlow() { - if (mode !== "GUIDED_DEMO") return operationalL1Flow; return authorizationFlows[authorizationLevel] || authorizationFlows.L1; } @@ -751,23 +739,13 @@ function renderAuthorizationCard(stateId = null, failure = false) { elements.authorizationFacts.innerHTML = facts.map((fact) => `${fact}`).join(""); } -function setMode(nextMode) { +function resetGuidedDemo() { stopInputs(); - mode = nextMode; - authorizationLevel = mode === "GUIDED_DEMO" ? elements.authorizationSelect.value : "L1"; - scenario = mode === "GUIDED_DEMO" ? elements.scenarioSelect.value : "SUCCESS"; + authorizationLevel = elements.authorizationSelect.value; + scenario = elements.scenarioSelect.value; events = []; - replayEvents = []; - replayIndex = 0; demoEvents = createDemoEvents(); demoIndex = 0; - elements.demoTab.classList.toggle("active", mode === "GUIDED_DEMO"); - elements.liveTab.classList.toggle("active", mode === "LIVE_SANDBOX"); - elements.replayTab.classList.toggle("active", mode === "SANITIZED_REPLAY"); - elements.demoControls.classList.toggle("hidden", mode !== "GUIDED_DEMO"); - elements.authorizationSummary.classList.toggle("hidden", mode !== "GUIDED_DEMO"); - elements.liveForm.classList.toggle("hidden", mode !== "LIVE_SANDBOX"); - elements.replayControls.classList.toggle("hidden", mode !== "SANITIZED_REPLAY"); const baseline = authorizationLevel === "L1" ? "PMT-BND + INS / L1 + A402" : authorizationLevel === "L2" ? "ADD + DEL / L2 + A402" : "ADD + AUP / L3 + A402"; elements.baselineValue.textContent = baseline; @@ -790,37 +768,21 @@ function setMode(nextMode) { elements.layerExplanation.textContent = authorizationLevel === "L1" ? "先看懂上面的购买故事，再用这里核对协议边界：ACT 描述协商、授权和支付服务消息；支付宝产品完成支付与验款；示例服务负责真正的数据交付。" : "本档只对照 ACT 2.1 的授权与支付语义；PSP 是协议角色，本仓库未提供支付宝 L2/L3 接入实现；示例服务只负责资源交付。"; - if (mode === "GUIDED_DEMO") { - elements.modeBadge.textContent = authorizationLevel === "L1" - ? "引导演示 · 非支付证据" - : `ACT 2.1 ${authorizationLevel} · 无支付宝实现`; - elements.modeBadge.className = "mode-badge demo"; - setStatus(authorizationLevel === "L1" - ? "说明性数据展示首次绑定、笔笔核身确认和 A402 恢复，不代表真实支付或兼容性证据。" - : `${authorizationLevel} 演示 ACT 2.1 协议语义；本仓库未提供对应的支付宝实现。`); - } else if (mode === "LIVE_SANDBOX") { - elements.eventStreamUrl.value = `${window.location.origin}/events`; - elements.modeBadge.textContent = "官方沙箱事件 · 未连接"; - elements.modeBadge.className = "mode-badge live"; - setStatus("Demo 不生成支付结果。请连接真实脱敏事件流。"); - } else { - elements.modeBadge.textContent = "REPLAY · NO FILE"; - elements.modeBadge.className = "mode-badge replay"; - setStatus("请选择由官网沙箱链路生成的脱敏 NDJSON。"); - } + elements.modeBadge.textContent = authorizationLevel === "L1" + ? "引导演示 · 非支付证据" + : `ACT 2.1 ${authorizationLevel} · 无支付宝实现`; + elements.modeBadge.className = "mode-badge demo"; + setStatus(authorizationLevel === "L1" + ? "说明性数据展示首次绑定、笔笔核身确认和 A402 恢复，不代表真实支付或兼容性证据。" + : `${authorizationLevel} 演示 ACT 2.1 协议语义；本仓库未提供对应的支付宝实现。`); renderTimeline(); renderPhaseRail(); render(); } function stopInputs() { - if (eventSource) eventSource.close(); - eventSource = null; - if (replayTimer) clearInterval(replayTimer); if (demoTimer) clearInterval(demoTimer); - replayTimer = null; demoTimer = null; - elements.playReplay.textContent = "播放"; elements.playDemo.textContent = "播放当前场景"; } @@ -925,14 +887,7 @@ function validateEvent(event, expectedIndex, expectedMode) { if (!event.evidence_ref || !event.correlation_ref) throw new Error("事件缺少证据或关联引用"); if (!Number.isFinite(Date.parse(event.occurred_at))) throw new Error("事件时间格式无效"); validateDemoEvidence(event, expectedIndex); - if (expectedMode === "LIVE_SANDBOX" && event.environment !== "SANDBOX") { - throw new Error("Live 事件必须声明 SANDBOX 环境"); - } - if (expectedMode === "SANITIZED_REPLAY" && (event.sanitized !== true || !event.origin_validation_id)) { - throw new Error("Replay 事件必须包含脱敏标记和原验证编号"); - } - if (expectedMode === "GUIDED_DEMO" - && (event.source !== demoBase.source || event.evidence_ref !== demoBase.evidence_ref)) { + if (event.source !== demoBase.source || event.evidence_ref !== demoBase.evidence_ref) { throw new Error("演示预览不能冒充支付证据"); } } @@ -996,16 +951,6 @@ function validateDemoEvidence(event, expectedIndex) { } } -function parseNdjson(text) { - return text.split(/\r?\n/).filter((line) => line.trim()).map((line, index) => { - try { - return JSON.parse(line); - } catch { - throw new Error(`第 ${index + 1} 行不是有效 JSON`); - } - }); -} - function addEvent(event) { validateEvent(event, events.length, mode); validateChainInvariants(event); @@ -1224,7 +1169,7 @@ function stepDemo() { if (demoIndex === demoEvents.length) { stopInputs(); elements.playDemo.textContent = "重新播放"; - setStatus("当前场景演示完成。以上为说明性数据，不是支付或沙箱验证证据。"); + setStatus("当前场景演示完成。以上为说明性数据，不是真实支付或兼容性证据。"); } } catch (error) { stopInputs(); @@ -1232,13 +1177,10 @@ function stepDemo() { } } -elements.demoTab.addEventListener("click", () => setMode("GUIDED_DEMO")); -elements.liveTab.addEventListener("click", () => setMode("LIVE_SANDBOX")); -elements.replayTab.addEventListener("click", () => setMode("SANITIZED_REPLAY")); -elements.scenarioSelect.addEventListener("change", () => setMode("GUIDED_DEMO")); -elements.authorizationSelect.addEventListener("change", () => setMode("GUIDED_DEMO")); +elements.scenarioSelect.addEventListener("change", resetGuidedDemo); +elements.authorizationSelect.addEventListener("change", resetGuidedDemo); elements.stepDemo.addEventListener("click", stepDemo); -elements.resetDemo.addEventListener("click", () => setMode("GUIDED_DEMO")); +elements.resetDemo.addEventListener("click", resetGuidedDemo); elements.playDemo.addEventListener("click", () => { if (demoIndex >= demoEvents.length) { events = []; @@ -1259,116 +1201,4 @@ elements.playDemo.addEventListener("click", () => { if (demoIndex < demoEvents.length) demoTimer = setInterval(stepDemo, 900); }); -elements.liveForm.addEventListener("submit", (submitEvent) => { - submitEvent.preventDefault(); - const url = elements.eventStreamUrl.value.trim(); - if (!url) return setStatus("请输入只输出脱敏事件的 SSE 地址。", true); - stopInputs(); - events = []; - scenario = "SUCCESS"; - renderTimeline(); - render(); - eventSource = new EventSource(url); - elements.modeBadge.textContent = "官方沙箱事件 · 连接中"; - setStatus("正在连接由官方沙箱链路产生的脱敏事件流…"); - eventSource.onopen = () => { - elements.modeBadge.textContent = "官方沙箱事件 · 已连接"; - setStatus("已连接。等待真实事件，不会自动推进状态。"); - }; - eventSource.onmessage = (message) => { - try { - const next = JSON.parse(message.data); - if (events.length === 0 && next.scenario) { - scenario = next.scenario; - if (!["SUCCESS", "PAYMENT_PENDING", "PROOF_MISMATCH", "VERIFICATION_UNAVAILABLE", "IDEMPOTENT_REPLAY"].includes(scenario)) { - throw new Error(`不支持场景 ${scenario}`); - } - renderTimeline(); - } - addEvent(next); - setStatus(`已接收 ${events.length} / ${flow().length} 个真实事件。`); - } catch (error) { - eventSource.close(); - setStatus(`事件流已停止：${error.message}`, true); - } - }; - eventSource.addEventListener("reset", () => { - events = []; - scenario = "SUCCESS"; - renderTimeline(); - render(); - setStatus("事件 Bridge 已重置，等待新的真实链路。"); - }); - eventSource.onerror = () => { - eventSource.close(); - elements.modeBadge.textContent = "官方沙箱事件 · 已断开"; - setStatus("事件流连接中断。页面不会推断后续支付结果。", true); - }; -}); - -elements.replayFile.addEventListener("change", async () => { - stopInputs(); - events = []; - replayIndex = 0; - try { - const file = elements.replayFile.files[0]; - if (!file) return; - replayEvents = parseNdjson(await file.text()); - scenario = replayEvents[0]?.scenario || "SUCCESS"; - if (!["SUCCESS", "PAYMENT_PENDING", "PROOF_MISMATCH", "VERIFICATION_UNAVAILABLE", "IDEMPOTENT_REPLAY"].includes(scenario)) { - throw new Error(`不支持场景 ${scenario}`); - } - renderTimeline(); - if (replayEvents.length !== flow().length) throw new Error(`Replay 必须包含当前场景的 ${flow().length} 个状态`); - replayEvents.forEach((event, index) => validateEvent(event, index, "SANITIZED_REPLAY")); - elements.playReplay.disabled = false; - elements.stepReplay.disabled = false; - elements.modeBadge.textContent = "SANITIZED REPLAY"; - setStatus(`已验证 ${file.name}。尚未播放，不代表实时支付。`); - render(); - } catch (error) { - replayEvents = []; - elements.playReplay.disabled = true; - elements.stepReplay.disabled = true; - elements.modeBadge.textContent = "REPLAY · REJECTED"; - setStatus(`拒绝加载：${error.message}`, true); - } -}); - -elements.stepReplay.addEventListener("click", () => { - if (replayIndex >= replayEvents.length) return; - try { - addEvent(replayEvents[replayIndex++]); - if (replayIndex === replayEvents.length) { - elements.stepReplay.disabled = true; - elements.playReplay.disabled = true; - setStatus("Replay 播放完成。内容来自已验证链路的脱敏记录。"); - } - } catch (error) { - setStatus(`Replay 已停止：${error.message}`, true); - } -}); - -elements.playReplay.addEventListener("click", () => { - if (replayTimer) { - clearInterval(replayTimer); - replayTimer = null; - elements.playReplay.textContent = "继续"; - return; - } - elements.playReplay.textContent = "暂停"; - replayTimer = setInterval(() => { - if (replayIndex >= replayEvents.length) { - clearInterval(replayTimer); - replayTimer = null; - elements.playReplay.textContent = "播放"; - elements.playReplay.disabled = true; - elements.stepReplay.disabled = true; - setStatus("Replay 播放完成。内容来自已验证链路的脱敏记录。"); - return; - } - addEvent(replayEvents[replayIndex++]); - }, 900); -}); - -setMode("GUIDED_DEMO"); +resetGuidedDemo(); diff --git a/code/web-client/alipay-ai-pay-showcase/public/index.html b/code/web-client/alipay-ai-pay-showcase/public/index.html index 5c4d5a9..e10508a 100644 --- a/code/web-client/alipay-ai-pay-showcase/public/index.html +++ b/code/web-client/alipay-ai-pay-showcase/public/index.html @@ -37,11 +37,6 @@

Agent 在调研过程中
如何购买专业数据

DEMO CONTROL

选择场景并控制左右两侧同步运行
-
- - - -
@@ -70,20 +65,8 @@

Agent 在调研过程中
如何购买专业数据

- - -
- 引导演示只解释协议，不代表真实支付或沙箱验证。 + 引导演示只解释协议，不会连接或执行真实支付。
@@ -122,7 +105,7 @@

Agent 任务执行

支付宝绑定演示二维码 · 不可扫码 - +
diff --git a/code/web-client/alipay-ai-pay-showcase/public/styles.css b/code/web-client/alipay-ai-pay-showcase/public/styles.css index b9a2e21..49de5fd 100644 --- a/code/web-client/alipay-ai-pay-showcase/public/styles.css +++ b/code/web-client/alipay-ai-pay-showcase/public/styles.css @@ -38,7 +38,7 @@ body { -webkit-font-smoothing: antialiased; } button, input, select { font: inherit; } -button, .file-button { min-height: 44px; } +button { min-height: 44px; } h1, h2, h3, p { margin-top: 0; } a { color: inherit; } .shell { width: min(1460px, 100%); margin: auto; padding: 18px clamp(18px, 3.5vw, 54px) 30px; } @@ -79,8 +79,6 @@ a { color: inherit; } box-shadow: var(--shadow-sm); } .mode-badge.demo { border-color: #cfe2ff; background: var(--blue-soft); color: var(--blue); } -.mode-badge.live { border-color: #bfeada; background: var(--green-soft); color: var(--green); } -.mode-badge.replay { border-color: #ffe0b7; background: var(--orange-soft); color: #c96a0a; } .intro { display: grid; @@ -167,7 +165,6 @@ main { margin-top: 14px; } } .playback-toolbar-heading .section-kicker { margin-bottom: 4px; } .playback-toolbar-heading strong { display: block; font-size: 12px; } -.playback-toolbar .mode-tabs { margin-bottom: 0; } .playback-toolbar .control-status { margin-bottom: -4px; } .authorization-summary { display: grid; @@ -708,27 +705,8 @@ main { margin-top: 14px; } .timeline-item.failure.current { border-color: #ffc0bb; background: var(--red-soft); color: var(--red); } .control-deck { margin-top: 15px; padding-top: 15px; border-top: 1px solid var(--line); } -.mode-tabs { - display: inline-flex; - gap: 3px; - margin-bottom: 10px; - padding: 3px; - border-radius: 12px; - background: #f0f3f7; -} -.mode-tab { - padding: 0 15px; - border: 0; - border-radius: 9px; - background: transparent; - color: var(--muted); - cursor: pointer; - font-size: 10px; - transition: background .2s, color .2s, box-shadow .2s; -} -.mode-tab.active { background: #fff; color: var(--text); box-shadow: 0 2px 9px rgba(35, 55, 80, .08); } .input-row { display: grid; grid-template-columns: minmax(155px, .85fr) minmax(180px, 1fr) auto auto auto; gap: 8px; } -.input-row select, .input-row input[type="url"] { +.input-row select { min-width: 0; padding: 0 13px; border: 1px solid var(--line-strong); @@ -739,8 +717,8 @@ main { margin-top: 14px; } font: 10px var(--mono); transition: border-color .2s, box-shadow .2s; } -.input-row select:focus, .input-row input[type="url"]:focus { border-color: #91bbf7; box-shadow: 0 0 0 3px rgba(22, 119, 255, .10); } -.primary-button, .secondary-button, .step-button, .file-button { +.input-row select:focus { border-color: #91bbf7; box-shadow: 0 0 0 3px rgba(22, 119, 255, .10); } +.primary-button, .secondary-button, .step-button { display: grid; place-items: center; padding: 0 17px; @@ -751,14 +729,13 @@ main { margin-top: 14px; } transition: transform .16s, box-shadow .16s, border-color .16s, background .16s; } .primary-button { border: 0; background: linear-gradient(110deg, var(--blue-bright), var(--blue)); color: #fff; box-shadow: 0 7px 18px rgba(22, 119, 255, .20); } -.secondary-button, .step-button, .file-button { border: 1px solid var(--line-strong); background: #fff; color: var(--text); } +.secondary-button, .step-button { border: 1px solid var(--line-strong); background: #fff; color: var(--text); } .step-button { border-color: #c7dcfb; color: var(--blue); } -.primary-button:hover, .secondary-button:hover, .step-button:hover, .file-button:hover { transform: translateY(-1px); box-shadow: 0 7px 18px rgba(30, 55, 86, .10); } +.primary-button:hover, .secondary-button:hover, .step-button:hover { transform: translateY(-1px); box-shadow: 0 7px 18px rgba(30, 55, 86, .10); } .control-status { min-height: 18px; margin-top: 9px; color: var(--muted); font-size: 9px; } .control-status.error { color: var(--red); } button:disabled { cursor: not-allowed; opacity: .42; transform: none !important; box-shadow: none !important; } -button:focus-visible, .file-button:focus-visible, a:focus-visible { outline: 3px solid rgba(22, 119, 255, .22); outline-offset: 2px; } -input[type="file"] { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0, 0, 0, 0); } +button:focus-visible, a:focus-visible { outline: 3px solid rgba(22, 119, 255, .22); outline-offset: 2px; } .lower-grid { display: grid; grid-template-columns: 1.08fr .92fr; gap: 14px; margin-top: 14px; } .layer-panel, .detail-panel { min-height: 350px; padding: 24px; } @@ -836,7 +813,6 @@ footer a:hover { text-decoration: underline; } .topbar { grid-template-columns: 1fr auto; min-height: 56px; } .demo-workbench { grid-template-columns: 1fr; } .playback-toolbar-heading { display: grid; } - .playback-toolbar .mode-tabs { width: 100%; } .authorization-summary { grid-template-columns: 44px 1fr; } .authorization-summary-facts { grid-column: 1 / -1; justify-content: flex-start; } .purchase-story.business-pane { position: static; } @@ -851,9 +827,7 @@ footer a:hover { text-decoration: underline; } .actors { grid-template-columns: 1fr 1fr; } .actor p { display: none; } .input-row { grid-template-columns: 1fr 1fr; } - .input-row select, .input-row input[type="url"] { grid-column: 1 / -1; min-height: 44px; } - .mode-tabs { display: grid; grid-template-columns: repeat(3, 1fr); } - .mode-tab { padding: 0 10px; } + .input-row select { grid-column: 1 / -1; min-height: 44px; } .story-flow, .fact-grid { grid-template-columns: 1fr; } .layer-panel, .detail-panel, .stage, .purchase-story { padding: 18px; } .purchase-heading { display: grid; } @@ -867,7 +841,7 @@ footer a:hover { text-decoration: underline; } .mode-badge { max-width: 150px; } .actors { grid-template-columns: 1fr; } .input-row { grid-template-columns: 1fr; } - .primary-button, .secondary-button, .step-button, .file-button { width: 100%; } + .primary-button, .secondary-button, .step-button { width: 100%; } } @media (prefers-reduced-motion: reduce) { *, *::before, *::after { scroll-behavior: auto !important; transition-duration: .01ms !important; animation-duration: .01ms !important; } diff --git a/code/web-client/alipay-ai-pay-showcase/server.mjs b/code/web-client/alipay-ai-pay-showcase/server.mjs index 9440b1d..db75d9c 100644 --- a/code/web-client/alipay-ai-pay-showcase/server.mjs +++ b/code/web-client/alipay-ai-pay-showcase/server.mjs @@ -1,18 +1,53 @@ -import { dirname, join } from "node:path"; +import { createServer } from "node:http"; +import { readFile, stat } from "node:fs/promises"; +import { dirname, extname, join, normalize } from "node:path"; import { fileURLToPath } from "node:url"; -import { createDemoServer } from "./bridge-server.mjs"; const root = join(dirname(fileURLToPath(import.meta.url)), "public"); const port = Number(process.env.PORT || 4173); -const demo = createDemoServer({ root, port }); +const host = "127.0.0.1"; +const contentTypes = { + ".css": "text/css; charset=utf-8", + ".html": "text/html; charset=utf-8", + ".js": "text/javascript; charset=utf-8", +}; -await demo.start(); -process.stdout.write(`ACT showcase: http://127.0.0.1:${demo.port()}\n`); -process.stdout.write(`Live event bridge: http://127.0.0.1:${demo.port()}/events\n`); +const server = createServer(async (request, response) => { + if (!["GET", "HEAD"].includes(request.method || "")) { + response.writeHead(405, { "Content-Type": "text/plain; charset=utf-8" }); + response.end("Method Not Allowed"); + return; + } + const url = new URL(request.url || "/", `http://${host}:${port}`); + const candidate = normalize(join(root, url.pathname === "/" ? "index.html" : url.pathname)); + if (!candidate.startsWith(`${root}/`)) { + response.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" }); + response.end("Forbidden"); + return; + } + try { + const metadata = await stat(candidate); + const path = metadata.isDirectory() ? join(candidate, "index.html") : candidate; + const body = request.method === "HEAD" ? null : await readFile(path); + response.writeHead(200, { + "Content-Type": contentTypes[extname(path)] || "application/octet-stream", + "Cache-Control": "no-store", + }); + response.end(body); + } catch { + response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }); + response.end("Not Found"); + } +}); + +await new Promise((resolve, reject) => { + server.once("error", reject); + server.listen(port, host, resolve); +}); +process.stdout.write(`ACT showcase: http://${host}:${port}/\n`); for (const signal of ["SIGINT", "SIGTERM"]) { - process.on(signal, async () => { - await demo.close(); - process.exit(0); + process.on(signal, () => { + server.close(() => process.exit(0)); }); } diff --git a/code/web-client/alipay-ai-pay-showcase/validate-evidence.mjs b/code/web-client/alipay-ai-pay-showcase/validate-evidence.mjs deleted file mode 100644 index c9b23c5..0000000 --- a/code/web-client/alipay-ai-pay-showcase/validate-evidence.mjs +++ /dev/null @@ -1,234 +0,0 @@ -import { readFile } from "node:fs/promises"; -import { pathToFileURL } from "node:url"; - -export const SCENARIO_STATES = Object.freeze({ - SUCCESS: [ - "CAPABILITY_NEGOTIATED", - "ORDER_CONFIRMED", - "RESOURCE_REQUESTED", - "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", - "PAYMENT_PROCESSING", - "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", - "PAYMENT_VERIFIED", - "RESOURCE_DELIVERED", - "FULFILLMENT_CONFIRMED", - ], - PAYMENT_PENDING: [ - "CAPABILITY_NEGOTIATED", - "ORDER_CONFIRMED", - "RESOURCE_REQUESTED", - "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", - "PAYMENT_PROCESSING", - "PAYMENT_PENDING", - ], - PROOF_MISMATCH: [ - "CAPABILITY_NEGOTIATED", - "ORDER_CONFIRMED", - "RESOURCE_REQUESTED", - "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", - "PAYMENT_PROCESSING", - "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", - "PROOF_REJECTED", - ], - VERIFICATION_UNAVAILABLE: [ - "CAPABILITY_NEGOTIATED", - "ORDER_CONFIRMED", - "RESOURCE_REQUESTED", - "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", - "PAYMENT_PROCESSING", - "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", - "VERIFICATION_UNAVAILABLE", - ], - IDEMPOTENT_REPLAY: [ - "CAPABILITY_NEGOTIATED", - "ORDER_CONFIRMED", - "RESOURCE_REQUESTED", - "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", - "PAYMENT_PROCESSING", - "PAYMENT_RESULT_RECEIVED", - "RESOURCE_REQUEST_RETRIED", - "PAYMENT_VERIFIED", - "RESOURCE_DELIVERED", - "FULFILLMENT_CONFIRMED", - "RESOURCE_REQUEST_RETRIED", - "PAYMENT_VERIFIED", - "RESOURCE_DELIVERED", - ], -}); - -export const REQUIRED_STATES = SCENARIO_STATES.SUCCESS; - -const MODES = new Set(["LIVE_SANDBOX", "SANITIZED_REPLAY"]); -const FORBIDDEN_KEYS = /(^|_)(secret|private_key|access_token|app_auth_token|payment_proof|client_session|binding_code|password)($|_)/i; -const METHOD_ID = /^[a-z][a-z0-9+.-]*:[a-z0-9][a-z0-9._/-]*$/; -const ALIPAY_INTEGRATION_METHOD_ID = "act-integration:a402/alipay-ai-pay"; -const METHOD_VERSION = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?$/; -const REQUEST_FINGERPRINT = /^sha-256:[A-Za-z0-9_-]{43}$/; - -export function parseEvents(input) { - const lines = input.split(/\r?\n/).filter((line) => line.trim() !== ""); - return lines.map((line, index) => { - try { - return JSON.parse(line); - } catch (error) { - throw new Error(`line ${index + 1} is not valid JSON: ${error.message}`); - } - }); -} - -export function assertNoSensitiveFields(value, location = "event") { - if (!value || typeof value !== "object") return; - for (const [key, child] of Object.entries(value)) { - if (FORBIDDEN_KEYS.test(key)) throw new Error(`${location} contains forbidden sensitive field: ${key}`); - assertNoSensitiveFields(child, `${location}.${key}`); - } -} - -export function statesForScenario(scenario) { - const states = SCENARIO_STATES[scenario]; - if (!states) throw new Error(`unsupported scenario: ${scenario ?? "missing"}`); - return states; -} - -export function validateEvidenceEvent(event, index, mode, scenario = "SUCCESS") { - const requiredStates = statesForScenario(scenario); - if (!MODES.has(mode)) throw new Error(`unsupported demo mode: ${mode ?? "missing"}`); - assertNoSensitiveFields(event, `event ${index + 1}`); - if (event.sequence !== index + 1) throw new Error(`event ${index + 1} has a non-contiguous sequence`); - if (event.state !== requiredStates[index]) throw new Error(`event ${index + 1} must be ${requiredStates[index]}`); - if (event.mode !== mode) throw new Error("all events must use the same mode"); - if ((event.scenario || "SUCCESS") !== scenario) throw new Error("all events must use the same scenario"); - if (typeof event.source !== "string" || event.source.trim() === "" || /mock/i.test(event.source)) { - throw new Error(`event ${index + 1} must identify a non-Mock source`); - } - if (typeof event.evidence_ref !== "string" || event.evidence_ref.trim() === "") { - throw new Error(`event ${index + 1} is missing evidence_ref`); - } - const time = Date.parse(event.occurred_at); - if (!Number.isFinite(time)) throw new Error(`event ${index + 1} has an invalid occurred_at`); - if (typeof event.correlation_ref !== "string" || event.correlation_ref.trim() === "") { - throw new Error(`event ${index + 1} is missing correlation_ref`); - } - if (!METHOD_ID.test(event.method_id || "")) throw new Error("method_id must use the A402 artifact namespace syntax"); - if (event.method_id !== ALIPAY_INTEGRATION_METHOD_ID) { - throw new Error(`method_id must identify the published Alipay integration mapping: ${ALIPAY_INTEGRATION_METHOD_ID}`); - } - if (!METHOD_VERSION.test(event.method_version || "")) throw new Error("method_version must be SemVer"); - validateStateFacts(event, index, requiredStates, scenario); - if (mode === "LIVE_SANDBOX" && event.environment !== "SANDBOX") { - throw new Error(`event ${index + 1} must declare the SANDBOX environment`); - } - if (mode === "SANITIZED_REPLAY" && (event.sanitized !== true || !event.origin_validation_id)) { - throw new Error(`event ${index + 1} must identify a sanitized source validation`); - } -} - -function validateStateFacts(event, index, requiredStates, scenario) { - if (event.state === "CAPABILITY_NEGOTIATED") { - requireStrings(event, ["psp_id", "endpoint_ref", "method_schema_ref", "capability_source_ref"]); - if (event.capability_source_validated !== true) { - throw new Error("capability source must be validated before payment selection"); - } - } - if (event.state === "ORDER_CONFIRMED") { - requireStrings(event, ["commerce_confirmation_ref"]); - } - if (["PAYMENT_REQUIRED", "RESOURCE_REQUEST_RETRIED", "PAYMENT_VERIFIED", "RESOURCE_DELIVERED"].includes(event.state)) { - requireStrings(event, ["order_ref", "resource_id"]); - if (!REQUEST_FINGERPRINT.test(event.request_fingerprint || "")) { - throw new Error(`${event.state} must carry a valid request_fingerprint`); - } - } - if (event.state === "PAYMENT_REQUIRED") { - requireStrings(event, ["amount", "currency", "profile_mapping"]); - } - if (event.state === "PAYMENT_RESULT_RECEIVED") { - requireStrings(event, ["transaction_ref", "proof_ref"]); - } - if (event.state === "PAYMENT_VERIFIED") { - requireStrings(event, ["transaction_ref", "validation_mapping"]); - } - if (event.state === "RESOURCE_DELIVERED") { - requireStrings(event, ["transaction_ref", "delivery_ref"]); - } - if (event.state === "FULFILLMENT_CONFIRMED") { - requireStrings(event, ["transaction_ref", "fulfillment_ref"]); - if (event.product_fulfillment_status !== "CONFIRMED") { - throw new Error("fulfillment confirmation must remain an independent confirmed product fact"); - } - } - if (scenario === "IDEMPOTENT_REPLAY" && index === requiredStates.length - 1) { - if (event.idempotent_replay !== true - || event.payment_action !== "NO_NEW_PAYMENT" - || event.delivery_action !== "RETURN_PRIOR_RESULT" - || event.fulfillment_action !== "NOT_REPEATED") { - throw new Error("idempotent replay must prove no repeated payment, delivery, or fulfillment confirmation"); - } - } -} - -function requireStrings(event, fields) { - for (const field of fields) { - if (typeof event[field] !== "string" || event[field].trim() === "") { - throw new Error(`${event.state} is missing ${field}`); - } - } -} - -export function validateEvents(events) { - const mode = events[0]?.mode; - const scenario = events[0]?.scenario || "SUCCESS"; - const requiredStates = statesForScenario(scenario); - if (events.length !== requiredStates.length) { - throw new Error(`expected ${requiredStates.length} events for ${scenario}, received ${events.length}`); - } - let previousTime = 0; - const invariants = new Map(); - const invariantFields = [ - "correlation_ref", "method_id", "method_version", "psp_id", "commerce_confirmation_ref", - "order_ref", "resource_id", "request_fingerprint", "amount", "currency", "transaction_ref", - ]; - events.forEach((event, index) => { - validateEvidenceEvent(event, index, mode, scenario); - const time = Date.parse(event.occurred_at); - if (time < previousTime) throw new Error("event timestamps must not move backwards"); - previousTime = time; - for (const field of invariantFields) { - if (event[field] === undefined) continue; - if (invariants.has(field) && invariants.get(field) !== event[field]) { - throw new Error(`${field} changes inside one evidence chain`); - } - invariants.set(field, event[field]); - } - }); - - return { - mode, - scenario, - event_count: events.length, - first_state: events[0].state, - final_state: events.at(-1).state, - }; -} - -async function main() { - const path = process.argv[2]; - if (!path) throw new Error("usage: node validate-evidence.mjs /absolute/path/to/events.ndjson"); - const result = validateEvents(parseEvents(await readFile(path, "utf8"))); - process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); -} - -if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { - main().catch((error) => { - process.stderr.write(`[FAIL] ${error.message}\n`); - process.exitCode = 1; - }); -} diff --git a/code/web-client/alipay-ai-pay-showcase/validate-evidence.test.mjs b/code/web-client/alipay-ai-pay-showcase/validate-evidence.test.mjs deleted file mode 100644 index b790516..0000000 --- a/code/web-client/alipay-ai-pay-showcase/validate-evidence.test.mjs +++ /dev/null @@ -1,138 +0,0 @@ -import test from "node:test"; -import assert from "node:assert/strict"; -import { REQUIRED_STATES, SCENARIO_STATES, validateEvents } from "./validate-evidence.mjs"; - -function liveEvents() { - return REQUIRED_STATES.map((state, index) => ({ - sequence: index + 1, - state, - mode: "LIVE_SANDBOX", - source: index < 3 ? "buyer-agent-quickstart" : "alipay-sandbox-workflow", - environment: "SANDBOX", - occurred_at: new Date(Date.UTC(2026, 6, 22, 12, 0, index)).toISOString(), - evidence_ref: `E2E-20260722-001#step-${index + 1}`, - scenario: "SUCCESS", - correlation_ref: "corr-sha256-a1b2", - method_id: "act-integration:a402/alipay-ai-pay", - method_version: "1.0.0", - psp_id: "alipay", - endpoint_ref: "endpoint-sha256-a1b2", - method_schema_ref: "schema-sha256-a1b2", - capability_source_ref: "capability-sha256-a1b2", - capability_source_validated: true, - commerce_confirmation_ref: "commerce-sha256-a1b2", - request_ref: "req-sha256-a1b2", - request_fingerprint: "sha-256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", - order_ref: "order-sha256-c3d4", - resource_id: "resource-demo", - amount: "0.01", - currency: "CNY", - profile_mapping: "ALIPAY_PRODUCT_PAYLOAD_TO_ACT_2_1_EVIDENCE", - transaction_ref: "trade-sha256-e5f6", - proof_ref: "proof-sha256-e5f6", - delivery_ref: "delivery-sha256-e5f6", - fulfillment_ref: "fulfillment-sha256-e5f6", - product_fulfillment_status: "CONFIRMED", - ...(state === "PAYMENT_VERIFIED" ? { validation_mapping: "ACT 2.1 evidence ← Alipay payment.verify result" } : {}), - })); -} - -test("accepts a complete ordered sandbox evidence chain", () => { - assert.deepEqual(validateEvents(liveEvents()), { - mode: "LIVE_SANDBOX", - scenario: "SUCCESS", - event_count: 11, - first_state: "CAPABILITY_NEGOTIATED", - final_state: "FULFILLMENT_CONFIRMED", - }); -}); - -test("accepts a terminal failure scenario without claiming delivery", () => { - const states = [ - "CAPABILITY_NEGOTIATED", "ORDER_CONFIRMED", "RESOURCE_REQUESTED", "PAYMENT_REQUIRED", - "USER_AUTHORIZATION_REQUIRED", "PAYMENT_PROCESSING", "PAYMENT_PENDING", - ]; - const events = states.map((state, index) => ({ - sequence: index + 1, - state, - scenario: "PAYMENT_PENDING", - mode: "LIVE_SANDBOX", - source: "official-sandbox-adapter", - environment: "SANDBOX", - occurred_at: new Date(Date.UTC(2026, 6, 22, 13, 0, index)).toISOString(), - evidence_ref: `E2E-PENDING#step-${index + 1}`, - correlation_ref: "corr-sha256-pending", - method_id: "act-integration:a402/alipay-ai-pay", - method_version: "1.0.0", - psp_id: "alipay", - endpoint_ref: "endpoint-sha256-p1", - method_schema_ref: "schema-sha256-p1", - capability_source_ref: "capability-sha256-p1", - capability_source_validated: true, - commerce_confirmation_ref: "commerce-sha256-p1", - request_ref: "req-sha256-p1", - request_fingerprint: "sha-256:BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", - order_ref: "order-sha256-p1", - resource_id: "resource-pending", - amount: "0.01", - currency: "CNY", - profile_mapping: "ALIPAY_PRODUCT_PAYLOAD_TO_ACT_2_1_EVIDENCE", - transaction_ref: "trade-sha256-p1", - proof_ref: "proof-sha256-p1", - })); - assert.equal(validateEvents(events).final_state, "PAYMENT_PENDING"); -}); - -test("rejects a manufactured source", () => { - const events = liveEvents(); - events[4].source = "local-mock-payment"; - assert.throws(() => validateEvents(events), /non-Mock source/); -}); - -test("rejects sensitive payment material", () => { - const events = liveEvents(); - events[4].payment_proof = "must-not-be-recorded"; - assert.throws(() => validateEvents(events), /forbidden sensitive field/); -}); - -test("requires replay provenance on every replay event", () => { - const events = liveEvents().map((event) => ({ ...event, mode: "SANITIZED_REPLAY", sanitized: true })); - assert.throws(() => validateEvents(events), /sanitized source validation/); -}); - -test("rejects invalid method identifiers and cross-step fingerprint drift", () => { - const invalidMethod = liveEvents(); - invalidMethod.forEach((event) => { event.method_id = "alipay-ai-pay"; }); - assert.throws(() => validateEvents(invalidMethod), /A402 artifact namespace syntax/); - - const unpublishedMapping = liveEvents(); - unpublishedMapping.forEach((event) => { event.method_id = "example:a402/alipay-ai-pay"; }); - assert.throws(() => validateEvents(unpublishedMapping), /published Alipay integration mapping/); - - const changedFingerprint = liveEvents(); - changedFingerprint[8].request_fingerprint = "sha-256:BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"; - assert.throws(() => validateEvents(changedFingerprint), /request_fingerprint changes/); -}); - -test("requires a real second submission for idempotent replay evidence", () => { - const base = liveEvents()[0]; - const events = SCENARIO_STATES.IDEMPOTENT_REPLAY.map((state, index) => ({ - ...base, - sequence: index + 1, - state, - scenario: "IDEMPOTENT_REPLAY", - occurred_at: new Date(Date.UTC(2026, 6, 22, 14, 0, index)).toISOString(), - evidence_ref: `E2E-REPLAY#step-${index + 1}`, - validation_mapping: state === "PAYMENT_VERIFIED" - ? "ACT 2.1 evidence ← Alipay payment.verify result" - : undefined, - })); - assert.throws(() => validateEvents(events), /must prove no repeated payment/); - Object.assign(events.at(-1), { - idempotent_replay: true, - payment_action: "NO_NEW_PAYMENT", - delivery_action: "RETURN_PRIOR_RESULT", - fulfillment_action: "NOT_REPEATED", - }); - assert.equal(validateEvents(events).event_count, 14); -}); diff --git a/docs/README.md b/docs/README.md index 3e4b4ea..7bb5b5d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # ACT 2.1 Documentation -This directory is the human-readable ACT 2.1 documentation set. ACT 2.1 is published in Chinese with an official informative English translation. If a translation discrepancy is found, the Chinese publication remains controlling until the discrepancy is resolved through project governance. +This directory is the human-readable ACT 2.1 documentation set. ACT 2.1 is published in Chinese with an official informative English translation. If a translation discrepancy is found, the Chinese publication remains controlling until the translation is corrected in a subsequent repository release. | Document | English | 中文 | |---|---|---| @@ -9,13 +9,14 @@ This directory is the human-readable ACT 2.1 documentation set. ACT 2.1 is publi | Commerce Interaction Domain | [English](specification/commerce-interaction.en.md) | [中文](specification/commerce-interaction.md) | | Payment Services Domain | [English](specification/payment-services.en.md) | [中文](specification/payment-services.md) | | Trust Services Domain | [English](specification/trust-services.en.md) | [中文](specification/trust-services.md) | -| A402 payment access protocol | [English](specification/a402.en.md) | [中文](specification/a402.md) | -| Commerce-to-payment negotiation | [English](specification/commerce-payment-negotiation.en.md) | [中文](specification/commerce-payment-negotiation.md) | -| Scenarios and business flows | [English](flows/scenarios.en.md) | [中文](flows/scenarios.md) | +| Scenarios and Business Flows (non-normative) | [English](specification/scenarios.en.md) | [中文](specification/scenarios.md) | + +Non-normative Alipay integration guides: [A402 payment access](../integrations/alipay/a402.en.md) / [中文](../integrations/alipay/a402.md), and [commerce-to-payment connection](../integrations/alipay/commerce-payment-negotiation.en.md) / [中文](../integrations/alipay/commerce-payment-negotiation.md). - [Glossary](glossary.md) - [FAQ](faq.md) +- [TSD-CRD Reference Implementation guide](../integrations/tsd-crd/README.md) -Protocol requirements are defined only by the specification documents. Runnable artifacts are under [`code/`](../code/README.md), and product-specific implementations are under [`integrations/`](../integrations/README.md). +Protocol requirements are defined only by the overview and four domain specifications. The scenario guide and integration guides are non-normative. Runnable artifacts are under [`code/`](../code/README.md), while reference implementation guidance and product-specific implementations are under [`integrations/`](../integrations/README.md). -The non-normative TSD-CRD machine profile and runnable reference implementation are under [`code/schemas/tsd-crd/`](../code/schemas/tsd-crd/README.md) and [`code/samples/tsd-crd-reference/`](../code/samples/tsd-crd-reference/README.md). +TSD-CRD is a normative subprotocol of the ACT 2.1 Trust Services Domain. Its optional `reference-v1` machine profile and runnable reference implementation are under [`code/schemas/tsd-crd/`](../code/schemas/tsd-crd/README.md) and [`code/samples/tsd-crd-reference/`](../code/samples/tsd-crd-reference/README.md); human-readable implementation guidance is centralized under [`integrations/tsd-crd/`](../integrations/tsd-crd/README.md). diff --git a/docs/assets/specification/act-2.1-protocol-framework.png b/docs/assets/specification/act-2.1-protocol-framework.png new file mode 100644 index 0000000..ac5fcf8 Binary files /dev/null and b/docs/assets/specification/act-2.1-protocol-framework.png differ diff --git a/docs/assets/specification/act-2.1-scenario-1-immediate-payment.png b/docs/assets/specification/act-2.1-scenario-1-immediate-payment.png new file mode 100644 index 0000000..d0645fd Binary files /dev/null and b/docs/assets/specification/act-2.1-scenario-1-immediate-payment.png differ diff --git a/docs/assets/specification/act-2.1-scenario-2-platform-delegated-payment.png b/docs/assets/specification/act-2.1-scenario-2-platform-delegated-payment.png new file mode 100644 index 0000000..9c68469 Binary files /dev/null and b/docs/assets/specification/act-2.1-scenario-2-platform-delegated-payment.png differ diff --git a/docs/assets/specification/act-2.1-scenario-3-dedicated-agent-payment.png b/docs/assets/specification/act-2.1-scenario-3-dedicated-agent-payment.png new file mode 100644 index 0000000..3f15132 Binary files /dev/null and b/docs/assets/specification/act-2.1-scenario-3-dedicated-agent-payment.png differ diff --git a/docs/assets/specification/act-2.1-scenario-4-autonomous-payment.png b/docs/assets/specification/act-2.1-scenario-4-autonomous-payment.png new file mode 100644 index 0000000..9a2c544 Binary files /dev/null and b/docs/assets/specification/act-2.1-scenario-4-autonomous-payment.png differ diff --git a/docs/assets/specification/act-2.1-trust-requirements.png b/docs/assets/specification/act-2.1-trust-requirements.png new file mode 100644 index 0000000..f226384 Binary files /dev/null and b/docs/assets/specification/act-2.1-trust-requirements.png differ diff --git a/docs/faq.md b/docs/faq.md index 02eff62..1461340 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -18,7 +18,7 @@ Under [`code/schemas/`](../code/schemas/README.md). It currently contains A402 a ## Is the TSD-CRD Sandbox a production credit service? -No. [`code/samples/tsd-crd-reference/`](../code/samples/tsd-crd-reference/README.md) is a non-normative, non-production reference implementation using Mock identity/credit providers, in-memory state, and temporary test keys. Its tests and basic conformance runner do not prove full ACT 2.1 conformance or production readiness. +No. The [TSD-CRD Reference Implementation guide](../integrations/tsd-crd/README.md) documents a non-production implementation under [`code/samples/tsd-crd-reference/`](../code/samples/tsd-crd-reference/README.md) using Mock identity/credit providers, in-memory state, and temporary test keys. TSD-CRD remains a normative ACT 2.1 subprotocol, but this particular implementation's tests and basic conformance runner do not prove full ACT 2.1 conformance or production readiness. ## Where do I configure an Alipay sandbox? diff --git a/docs/flows/scenarios.en.md b/docs/flows/scenarios.en.md deleted file mode 100644 index 92929a2..0000000 --- a/docs/flows/scenarios.en.md +++ /dev/null @@ -1,130 +0,0 @@ -# ACT 2.1 Scenarios and Business Flows - -[中文](scenarios.md) | English - -> **Status: ACT 2.1 Informative Scenario Guide / Non-normative** -> **For understanding cross-domain composition. This is not an independent protocol component, an implementation specification, or conformance evidence.** -> **Version baseline: 2026-08-11 (UTC+8).** -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** - -This guide combines ADD, CID, PSD, and TSD into end-to-end business scenarios. It helps developers decide when an IAC is required, which payment-authorization level applies, when trustworthy events are created asynchronously, and when associated credit is verified on demand. This document is the versioned ACT 2.1 scenario guide in this release. The [Scenarios and Business Flows](https://www.act-protocol.com/documentation/scenarios) page on the ACT Protocol website is an unversioned informative reference and does not override this release. - -ACT 2.1 explicitly includes L1/L2/L3 in its scenario classification and component list and includes `PSD-PAY-A402`. This guide is consistent with the [Payment Services Domain](../specification/payment-services.en.md): A402 is an independent access component usable by INS, DEL, and AUP, not a new authorization level. If this guide conflicts with a domain specification, the domain specification controls. - -## 1. Select the authorization scenario first - -| Scenario | User present during execution | Authorization basis | PSD scenario | Common account form | -|---|---|---|---|---| -| 1. Real-time, user-present instant payment | Yes | User confirmation before funds processing for this payment | `PSD-PAY-INS` / L1 | Bound payment tool | -| 2. Directed delegation for a platform or multi-tenant Agent | No | `SPECIFIED` IAC plus verified binding between the Agent and the concrete delegator | `PSD-PAY-DEL` / L2 | Bound tool or optional sub-account | -| 3. Directed delegation for a user-dedicated Agent | No | `SPECIFIED` IAC bound to one unique dedicated Agent identity | `PSD-PAY-DEL` / L2 | Optional `PSD-AGT-SUB` | -| 4. Autonomous delegated payment | No | `BOUNDED` IAC; multiple payments may occur during the task | `PSD-PAY-AUP` / L3 | Isolated account commonly recommended, but not protocol-mandatory | - -HTTP 402 is not a fifth authorization level. `PSD-PAY-A402` presents payment requirements, retries with Proof, validates credentials, and delivers resources. INS/DEL/AUP determine who authorizes, when confirmation occurs, and which boundaries the PSP must validate. - -## 2. Responsibilities of the four domains in one business chain - -```mermaid -flowchart LR - ADD["ADD: intent, ISR, IAC, and state"] --> CID["CID: discovery, intent transfer, payment negotiation, and transaction confirmation"] - CID --> PSD["PSD: payment tools, authorization checks, payment, and A402"] - PSD --> FUL["Business fulfillment or resource delivery"] - ADD -. "intent_id / delegation_id" .-> TSD["TSD: trusted attestation and credit association"] - CID -. "order / decision" .-> TSD - PSD -. "payment transaction" .-> TSD - FUL -. "fulfillment" .-> TSD -``` - -`TSD-ATT` attestation reporting is an asynchronous, non-blocking supplemental flow. Incomplete attestation reporting SHOULD NOT stop an online payment that has already satisfied ADD/CID/PSD conditions. Conversely, a failed business or payment flow MUST NOT fabricate a completion event. - -`TSD-CRD-VER` is on-demand credit verification. It MAY be called synchronously during the business's own risk decision or used offline; it is not part of the attestation-reporting chain. Its `PASS` result means only that associated-credit verification passed for the specified scope, purpose, and point in time. It does not constitute an IAC, transaction admission, a credit grant, or payment approval. - -## 3. Scenario one: user-present instant payment - -### 3.1 Flow - -1. The Agent uses `ADD-INT-ICS` to capture and structure the current purchase intent. This scenario does not require a pre-issued IAC. -2. The Agent uses `CID-MER-CAT` / `CID-INT-XFR` to discover candidates, compares them locally, and presents the product or service, amount, currency, and counterparty to the user. -3. The user confirms the transaction. The parties MAY align payment capabilities through `CID-PCA-NEG` and form an order transaction number and confirmation result through `CID-CART-CFM`. -4. The Agent initiates `PSD-PAY-INS`. The PSP checks replay protection, Agent signature, payment tool, and identity binding, and obtains user confirmation for this payment before funds processing. -5. The PSP returns the payment result. When A402 is used, the Agent retries the original resource request with `Payment-Proof`, and the seller validates it before delivery. -6. Payment and fulfillment completion events MAY enter TSD asynchronously. - -### 3.2 Critical boundaries - -- User confirmation of transaction content and PSP confirmation before funds processing MUST refer to the same order, amount, currency, and payee. -- A402 resource retry occurs after the payment result and is not a substitute for `PSD-PAY-INS` authorization. -- `act:payment:transaction-completed` MAY be reported after payment. `act:commerce:fulfillment-completed` can be reported only after actual fulfillment. - -## 4. Scenario two: directed delegation for a platform or multi-tenant Agent - -### 4.1 Establish delegation - -1. The Agent captures an explicit purchase target and creates a `SPECIFIED` ISR. -2. After user confirmation, `ADD-IAC-ISS` issues an IAC. The IAC SHOULD identify the concrete delegator, delegated Agent, target boundary, amount, validity period, and permitted payment methods. -3. A platform Agent MUST be able to prove the binding between the current runtime or tenant context and the concrete delegator in the IAC. A general platform Agent identity alone MUST NOT represent an arbitrary user. -4. After the IAC becomes active, `act:delegation:delegation-issued` MAY be reported asynchronously. - -### 4.2 Selection, confirmation, and payment - -1. The Agent discovers candidates and decides locally. It MAY asynchronously record `act:commerce:decision-logged`. -2. `CID-CART-CFM` performs preflight validation of per-payment and cumulative amounts, merchant, category, payment method, and price deviation, then creates an order confirmation. It MAY asynchronously record `act:commerce:cart-confirmed`. -3. The Agent locally checks the IAC and payment tool, then constructs a `PSD-PAY-DEL` request containing the complete IAC, `delegation_id`, and order transaction number. -4. The PSP authoritatively validates replay protection, Agent signature, IAC signature, state and delegate, delegator or payment-tool binding, and consistency of order, amount, and authorization boundaries. Local checks cannot replace PSP checks. -5. After successful payment, fulfillment proceeds through A402 or a conventional order interface. Payment and fulfillment become separate events. - -## 5. Scenario three: directed delegation for a user-dedicated Agent - -Scenario three reuses the `SPECIFIED` IAC, transaction confirmation, and `PSD-PAY-DEL` flow from scenario two, with these differences: - -- the Agent is bound to one user's device, account, or controlled runtime and has a unique, verifiable Agent identity; -- `agent_id` in the IAC identifies that dedicated identity, and the PSP validates its signature using the corresponding public key or trusted identity material; -- `PSD-AGT-SUB` MAY isolate balance, limits, and keys. Without a sub-account, payment-tool binding, limits, and risk control MUST provide equivalent boundaries. - -A “dedicated Agent” is not inherently trustworthy and does not permit skipping IAC state, order consistency, replay protection, signatures, or payment-tool checks. - -## 6. Scenario four: autonomous delegated payment - -### 6.1 Authorization and task decomposition - -1. The user confirms the task goal, total budget, time, permitted services, merchants, categories and payment methods, and exception-handling boundaries. -2. `ADD-IAC-ISS` issues a `BOUNDED` IAC. A dedicated sub-account MAY provide funds isolation when necessary, but the source describes it only as common or recommended, not as an AUP requirement. -3. The Agent decomposes the task locally and discovers multiple service providers. Reasoning and planning algorithms are outside ACT. - -### 6.2 Every sub-payment - -1. The Agent MAY use `CID-PCA-NEG` to select an available payment method. -2. Before each payment, it checks the IAC validity window, cumulative budget, per-payment amount, provider or category, payment method, and current account state. -3. A paid service MAY return HTTP 402. The Agent uses `Payment-Needed` and its completed AUP authorization decision to construct the payment request. -4. The PSP authoritatively validates replay protection, Agent and IAC signatures and state, amount and cumulative budget, provider, category and method, and any sub-account in use. -5. On success, the PSP produces a payment result or Proof. The seller MUST validate the Proof, transaction state, and original-request correlation before delivery. -6. Repeat the flow for later subtasks. The Agent updates cumulative budget only from authoritative PSP success results. - -### 6.3 Task completion - -After the task completes or terminates, the Agent MAY request IAC revocation. IAC revocation and expiration trigger their respective TSD events. Each payment, resource delivery, and final fulfillment remains a distinct fact. “Task complete” MUST NOT backfill a payment or delivery that did not occur. - -## 7. Cross-domain correlation and recovery invariants - -An end-to-end chain SHOULD at least correlate: - -- ADD `intent_id`, the delegated scenario's `delegation_id`, and IAC state; -- CID requests, candidates, transaction confirmation, merchant order, and payment-capability result; -- PSD payment request, merchant order or resource, payment transaction number, Proof, and validation result; -- TSD unique attestation-record identifier and optional upstream-record reference. - -Recovery MUST distinguish retrieving candidates again, confirming the transaction again, initiating a new payment, querying an unknown payment result, retrying the original resource with Proof, validating Proof again, and retrying fulfillment confirmation. If the payment result is unknown, query authoritative state first; do not automatically create a second payment. Valid Proof does not bypass resource or order consistency or duplicate-delivery protection. - -## 8. Developer adoption guidance - -- For a first real product integration, prioritize L1: `ADD-INT-ICS + CID-CART-CFM + PSD-PMT-BND + PSD-PAY-INS + PSD-PAY-A402`. -- Before implementing L2/L3, provide IAC issuance, state queries, Agent identity and keys, authoritative PSP authorization validation, and complete exception recovery. Adding only `delegation_id` to a request is insufficient. -- TSD normative semantics are final, but this repository does not include a runnable ACT Trust Chain or production credit service. The [TSD-CRD Reference Implementation](../../code/samples/tsd-crd-reference/README.md) uses only Mock capabilities and in-memory state; product logs, demos, or baseline consistency results do not establish full TSD conformance or production integration. - -## 9. Sources - -- Scenario source: [Scenarios and Business Flows](https://www.act-protocol.com/documentation/scenarios) -- ADD: [Authorization & Delegation Domain](https://www.act-protocol.com/documentation/delegation) -- CID: [Commerce Interaction Domain](https://www.act-protocol.com/documentation/commerce) -- PSD: [Payment Services Domain](https://www.act-protocol.com/documentation/payment) -- TSD: [Trust Services Domain](https://www.act-protocol.com/documentation/trust) diff --git a/docs/flows/scenarios.md b/docs/flows/scenarios.md deleted file mode 100644 index b47467c..0000000 --- a/docs/flows/scenarios.md +++ /dev/null @@ -1,129 +0,0 @@ -# ACT 2.1 典型场景与业务流程 - -中文 | [English](scenarios.en.md) - -> **状态：ACT 2.1 Informative Scenario Guide / Non-normative** -> **用于理解跨域组合，不是独立协议组件、正式实现规范或 Conformance 证据。** -> **版本基线：2026-08-11（UTC+8）。** - -本文把 ADD、CID、PSD 和 TSD 组合成端到端业务场景，帮助开发者判断何时需要 IAC、采用哪一种支付授权级别、何时异步形成可信事件，以及何时按需验证关联信用。本 Release 中的本文是 ACT 2.1 的版本化场景指南；ACT Protocol 官网的[典型场景与业务流程](https://www.act-protocol.com/documentation/scenarios)是未版本化的信息性参考，不覆盖本 Release。 - -ACT 2.1 在场景分类和组件清单中明确 L1/L2/L3，并列入 `PSD-PAY-A402`。本指南与[支付服务域](../specification/payment-services.md)一致：A402 是可被 INS、DEL、AUP 引用的独立接入组件，不是新的授权等级。若场景说明与域正文发生冲突，以对应域正文为准。 - -## 1. 先选择授权场景 - -| 场景 | 用户在执行时是否在场 | 授权基础 | PSD 场景 | 常见账户形态 | -|---|---|---|---|---| -| 1. 实时在场即时支付 | 是 | 本笔资金处理前的用户确认 | `PSD-PAY-INS` / L1 | 已绑定支付工具 | -| 2. 平台/多租户 Agent 定向委托 | 否 | `SPECIFIED` IAC，并验证 Agent 与具体委托人的绑定 | `PSD-PAY-DEL` / L2 | 绑定工具或可选子账户 | -| 3. 用户专属 Agent 定向委托 | 否 | `SPECIFIED` IAC，IAC 绑定唯一专属 Agent 身份 | `PSD-PAY-DEL` / L2 | 可选 `PSD-AGT-SUB` | -| 4. 自主化委托支付 | 否 | `BOUNDED` IAC；任务周期内可发生多笔支付 | `PSD-PAY-AUP` / L3 | 通常建议隔离账户，但不是协议必备 | - -HTTP 402 不是第五种授权级别。`PSD-PAY-A402` 负责提出支付要求、携 Proof 重试、验凭和交付；INS/DEL/AUP 决定谁授权、何时确认和 PSP 必须验证哪些边界。 - -## 2. 四域在一条业务链中的职责 - -```mermaid -flowchart LR - ADD["ADD：意图、ISR、IAC 与状态"] --> CID["CID：发现、意图传递、支付协商与交易确认"] - CID --> PSD["PSD：支付工具、授权核验、支付与 A402"] - PSD --> FUL["业务履约或资源交付"] - ADD -. "intent_id / delegation_id" .-> TSD["TSD：可信存证与关联信用"] - CID -. "order / decision" .-> TSD - PSD -. "payment transaction" .-> TSD - FUL -. "fulfillment" .-> TSD -``` - -`TSD-ATT` 存证上报是异步、非阻塞的附加流程。未完成存证上报不应使已经满足 ADD/CID/PSD 条件的在线支付停在主链路；相反，业务或支付失败也不得伪造完成事件。 - -`TSD-CRD-VER` 是按需信用验证，可在业务自己的风险判断阶段同步调用，也可以离线使用；它不属于存证上报链路。其 `PASS` 只表示指定范围、目的和时点下的关联信用验证通过，不构成 IAC、交易准入、授信或支付批准。 - -## 3. 场景一：用户在场的即时支付 - -### 3.1 流程 - -1. Agent 通过 `ADD-INT-ICS` 获取和结构化当前购买意图；本场景不需要预先签发 IAC。 -2. Agent 使用 `CID-MER-CAT` / `CID-INT-XFR` 发现候选，本地比较后向用户展示商品或服务、金额、币种和交易对手。 -3. 用户确认交易；双方可通过 `CID-PCA-NEG` 对齐支付能力，并通过 `CID-CART-CFM` 形成订单交易号和确认结果。 -4. Agent 发起 `PSD-PAY-INS`；PSP 检查防重放、Agent 签名、支付工具及身份绑定，并在资金处理前取得本笔用户确认。 -5. PSP 返回支付结果；采用 A402 时，Agent 携 `Payment-Proof` 重试原资源请求，卖方验凭后交付。 -6. 支付与履约完成事件可以异步进入 TSD。 - -### 3.2 关键边界 - -- 用户确认交易内容与 PSP 的资金处理前确认必须围绕同一订单、金额、币种和收款方。 -- A402 的资源重试发生在支付结果之后，不是 `PSD-PAY-INS` 的授权替代。 -- 可以上报 `act:payment:transaction-completed`；只有实际履约完成后才能上报 `act:commerce:fulfillment-completed`。 - -## 4. 场景二：平台或多租户 Agent 的定向委托 - -### 4.1 建立委托 - -1. Agent 获取明确购买目标，生成 `SPECIFIED` ISR。 -2. 用户确认后，`ADD-IAC-ISS` 签发 IAC；IAC 应能识别具体委托人、受托 Agent、目标边界、金额、有效期和允许的支付方式。 -3. 平台型 Agent 必须能证明当前运行实例/租户上下文与 IAC 中具体委托人的绑定，不能仅凭平台的通用 Agent 身份代表任意用户。 -4. IAC 生效后可异步上报 `act:delegation:delegation-issued`。 - -### 4.2 选择、确认和支付 - -1. Agent 发现候选并在本地决策；可以异步记录 `act:commerce:decision-logged`。 -2. `CID-CART-CFM` 对单笔/累计金额、商户、类目、支付方式和价格偏差执行前置检验，形成订单确认；可以异步记录 `act:commerce:cart-confirmed`。 -3. Agent 本地检查 IAC 和支付工具，再构造 `PSD-PAY-DEL` 请求，携带完整 IAC、`delegation_id` 和订单交易号。 -4. PSP 权威验证请求防重放、Agent 签名、IAC 签名/状态/受托方、委托人或支付工具绑定、订单/金额与授权边界；本地检查不能替代 PSP 检查。 -5. 支付成功后按 A402 或传统订单接口履约；支付与履约事件分别形成。 - -## 5. 场景三：用户专属 Agent 的定向委托 - -场景三沿用场景二的 `SPECIFIED` IAC、交易确认和 `PSD-PAY-DEL` 流程，区别在于： - -- Agent 与单一用户的设备、账号或受控运行环境绑定，并具有唯一、可验证的 Agent 身份； -- IAC 中的 `agent_id` 指向该专属身份，PSP 使用对应公钥或受信身份材料验签； -- 可以使用 `PSD-AGT-SUB` 隔离余额、额度和密钥；若不使用子账户，也必须由支付工具绑定、额度和风控提供等价边界。 - -“专属 Agent”不意味着天然可信，也不意味着可以跳过 IAC 状态、订单一致性、防重放、签名或支付工具检查。 - -## 6. 场景四：自主化委托支付 - -### 6.1 授权和任务分解 - -1. 用户确认任务目标、总预算、时间、允许的服务/商户/类目/支付方法和异常处理边界。 -2. `ADD-IAC-ISS` 签发 `BOUNDED` IAC；必要时准备专属子账户作为资金隔离，但来源只将其描述为常见/推荐做法，不构成 AUP 强制条件。 -3. Agent 在本地拆解任务并发现多个服务提供方；推理和规划算法不属于 ACT。 - -### 6.2 每一笔子支付 - -1. Agent 可通过 `CID-PCA-NEG` 选择当前可用支付方法。 -2. 每笔支付前检查 IAC 时间窗、累计预算、单笔金额、服务方/类目、支付方式和当前账户状态。 -3. 收费服务可返回 HTTP 402；Agent 根据 `Payment-Needed` 和已完成的 AUP 授权判断构造支付请求。 -4. PSP 权威验证防重放、Agent/IAC 签名和状态、金额与累计预算、服务方/类目/方法，以及按需使用的子账户。 -5. 成功后形成支付结果/Proof；卖方必须验证 Proof、交易状态和原请求关联后才交付。 -6. 对后续子任务重复上述流程。Agent 只以 PSP 权威成功结果更新累计预算。 - -### 6.3 任务结束 - -任务完成或终止后，Agent 可以请求吊销 IAC；IAC 吊销或到期分别触发相应 TSD 事件。每笔支付、资源交付和最终履约仍是不同事实，不能用“任务完成”回填未发生的支付或交付。 - -## 7. 跨域关联和恢复不变量 - -一条端到端链路至少应能关联： - -- ADD 的 `intent_id`，委托场景中的 `delegation_id` 和 IAC 状态； -- CID 的请求、候选、交易确认、商户订单和支付能力结果； -- PSD 的支付请求、商户订单/资源、支付交易号、Proof 和验证结果； -- TSD 的存证记录唯一标识和可选上游记录引用。 - -恢复时必须区分：重新获取候选、重新确认交易、重新发起支付、查询未知支付结果、携 Proof 重试原资源、重新验凭和重试履约确认。支付结果未知时先查询权威状态，不能自动创建第二笔支付；Proof 有效也不能绕过资源/订单一致性和防重复交付检查。 - -## 8. 开发者采用建议 - -- 首期真实产品接入优先实现 L1：`ADD-INT-ICS + CID-CART-CFM + PSD-PMT-BND + PSD-PAY-INS + PSD-PAY-A402`。 -- 实现 L2/L3 前，需要同时具备 IAC 签发、状态查询、Agent 身份/密钥、PSP 权威授权核验和完整异常恢复，不能只在请求中增加 `delegation_id`。 -- TSD 规范语义已经定稿，但本仓库没有可运行的 ACT Trust Chain 或生产信用服务。[TSD-CRD Reference Implementation](../../code/samples/tsd-crd-reference/README.md) 只使用 Mock 能力和内存状态；产品日志、Demo 或基础一致性结果不得据此声明已完成 TSD 全量 Conformance 或生产接入。 - -## 9. 来源 - -- 场景事实源：[典型场景与业务流程](https://www.act-protocol.com/documentation/scenarios) -- ADD：[委托授权域](https://www.act-protocol.com/documentation/delegation) -- CID：[商业交互域](https://www.act-protocol.com/documentation/commerce) -- PSD：[支付服务域](https://www.act-protocol.com/documentation/payment) -- TSD：[信任服务域](https://www.act-protocol.com/documentation/trust) diff --git a/docs/specification/README.md b/docs/specification/README.md index 45ac345..8987d70 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -1,6 +1,6 @@ # ACT 2.1 Specification -ACT 2.1 is organized into four domains and their cross-domain payment access rules. English files are official informative translations of the final Chinese publication. If a translation discrepancy is found, the Chinese publication remains controlling until governance resolves it. +ACT 2.1 consists of the protocol overview and four domain specifications. Those five finalized Chinese documents are the complete normative publication. English files are official informative translations; if a translation discrepancy is found, the Chinese publication remains controlling until the translation is corrected in a subsequent repository release. Requirement keywords in both languages follow the [normative-language table](overview.en.md#normative-language). The corresponding [Chinese table](overview.md#规范性用语) is controlling. @@ -11,7 +11,13 @@ Requirement keywords in both languages follow the [normative-language table](ove | Commerce Interaction Domain | [English](commerce-interaction.en.md) | [中文](commerce-interaction.md) | | Payment Services Domain | [English](payment-services.en.md) | [中文](payment-services.md) | | Trust Services Domain | [English](trust-services.en.md) | [中文](trust-services.md) | -| A402 payment access protocol | [English](a402.en.md) | [中文](a402.md) | -| Commerce-to-payment negotiation | [English](commerce-payment-negotiation.en.md) | [中文](commerce-payment-negotiation.md) | -The scenario guide is informative: [English](../flows/scenarios.en.md) / [中文](../flows/scenarios.md). JSON Schemas, examples, and test vectors are implementation aids under [`code/schemas/`](../../code/schemas/README.md); the TSD-CRD `reference-v1` profile is explicitly non-normative. +The scenario guide is part of the specification documentation set but is non-normative: + +| Guide | English | 中文 | +|---|---|---| +| Scenarios and Business Flows | [English](scenarios.en.md) | [中文](scenarios.md) | + +Non-normative A402 and commerce-to-payment guides are grouped under the [Alipay reference integration](../../integrations/alipay/README.md). JSON Schemas and fixtures are implementation aids under [`code/schemas/`](../../code/schemas/README.md). + +TSD-CRD's normative requirements are part of the Trust Services Domain. The optional [`reference-v1` machine profile](../../code/schemas/tsd-crd/reference-v1/README.md), [runnable reference implementation](../../code/samples/tsd-crd-reference/README.md), and [implementation guide](../../integrations/tsd-crd/README.md) are implementation aids and do not add or replace ACT 2.1 requirements. diff --git a/docs/specification/authorization-delegation.en.md b/docs/specification/authorization-delegation.en.md index 0413855..e08dff5 100644 --- a/docs/specification/authorization-delegation.en.md +++ b/docs/specification/authorization-delegation.en.md @@ -2,156 +2,343 @@ [中文](authorization-delegation.md) | English -> **Chinese source publication: ACT 2.1 Specification / Final / Normative** -> **The protocol content is final. Conformance with this specification requires independent conformance evidence.** -> **Version baseline: 2026-08-11 (UTC+8).** -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +# Scope +## Domain Positioning +Authorization & Delegation Domain (Authorization & Delegation Domain, ADD) provides the expression, confirmation, structured constraints of user intent, authorization credential issuances and their life-cycle management rules that provide an expressionable, binding, verifiable and retroactive basis of authorization for Agent representing User commercial activities. + +## Domain Responsibilities +This domain covers the following: + ++ User's original intentAccess, clarification, confirmation and structured expression; ++ Intent Structuring Result (ISR) generation and reference; ++ Intent Authorization Credential (IAC) construction, issuance and sealing; ++ IAC Life cycle state and its visible semantics. + +The following are not regulated in this domain: + ++ Front-end interactive styles, hint engineering, model reasoning processes and multi-modular bottom recognition algorithms; ++ Specific identity infrastructure, private key hosting and signature services internalization; ++ Commodity discovery, transaction negotiation, Cart Confirmation, payment channel communication, settlement of funds. + +# The list of components and relationships in this field +## Component Overview +Authorization & Delegation Domain consists of three protocol components, which together complete the available links from User's original intent to authorization credential. The functional position of the components is as follows: + ++ **ADD-INT-ICS: Intentional and structured expression.** Be responsible for receiving User's original intent, completing the necessary semantic clarifications, User confirmation and structured expression, resulting in Intent Structuring Result to be quoted in the subsequent authorization process. ++ **ADD-IAC-ISS: Intent Authorization Credential for issuance.** Be responsible for encapsulating the structured intent as authorization credential as cross-domain verifiable and completing the necessary signature or issuance actions. ++ **ADD-IAC-LCM: Intent Authorization Credential Life cycle management.** Responsible for defining and managing IAC changes in state and their visible semantics during the life of the period. + +## Core Object & Identification +To maintain consistency in internal and cross-domain processing, ADD uses a set of standard core objects and identification keys to describe the critical state in the User authorized link. The core objects of this domain and their effects can be summarized as follows: + +|** Object or Identification**|** Meaning**|** Mainly Generate Location**|** Main Use Location**| +| --- | --- | --- | --- | +|User's original intent|User Original commercial intent expressed in natural language or other type of input.|ADD-INT-ICS|ADD-INT-ICS, and relevant processing elements for ex post verification, as necessary.| +|`intent_id`|user intent logo for cross-intention confirmation, structured expression and subsequent cross-domain reference|ADD-INT-ICS|ADD Internal domain, and other fields Intent Context that need to be quoted| +|Intent Structuring Result
(Intent Structured Research, ISR)|Expression of structured rules for User commercial objectives, constraints and boundaries|ADD-INT-ICS|ADD-IAC-ISS, and other fields where reference to the rule is required| +|Intent Authorization Credential (Intent Assessment Credit, IAC)|authorization credential Object after ISR can be verified|ADD-IAC-ISS|ADD-IAC-LCM, Payment Services Domain, Trust Services Domain| +|`delegation_id`|IAC unique sign for the life cycle to mark a formal authorization credential|ADD-IAC-ISS|ADD-IAC-LCM, Payment Services Domain, Trust Services Domain| +|Authorized Status|IAC Current available status, e.g. Active, Suspended, Revoked, Expired|ADD-IAC-LCM|Payment Services Domain, and other elements that need to be judged on the validity of the delegation of authority| + +## Dependence and Cross-domain Reference +ADD-INT-ICS forms the basis for the issuance of ADD-IAC-ISS. ADD-IAC-ISS forms IAC and `delegation_id` form the subject of ADD-IAC-LCM, and the state of authorization given ADD-IAC-LCM will affect the subsequent acceptance of authorization credential. + +Commerce Interaction Domain primarily references ISR and the relevant constraint context to support product discovery, intent transmission, and transaction confirmation. Payment Services Domain primarily references IAC, `delegation_id`, and authorization status results to support authorization verification in payment requests. The trusted attestation subsection of Trust Services Domain centrally maintains the relevant event types and attestation governance rules; this domain does not redefine them. + +# ADD-INT-ICS: Intentional acquisition and structured expression +## Overview +Intent to obtain and structured expression (Intent Capture and Structured Exchange, ADD-INT-ICS) provides for User's original intent acquisition, semantic clarification, User confirmation and structured expression processing requirements. + +The objective of this component is to translate User original commercial intent, expressed in natural language or other input, into Intent Structuring Result that can be quoted and validated by a follow-up authorization process (Intent Processed Research, ISR). + +This component does not regulate specific human interfaces, hint engineering, model reasoning processes and multi-modular bottom recognition algorithms. + +## Participants and prefix +This component covers the following Participants: User and the User side Agent to receive, interpret, clarify, confirm and generate ISR. + +Before entering this component, SHALL satisfies the following preconditions: + ++ An effective interactive context with User has been established on User side Agent. ++ User is capable of expressing commercial intent in such a way as to achieve party-supported input. ++ User side Agent has the capability to retain original intent and output ISR locally. + +## Data structure and field tables +Two core objects are involved in the treatment of this component: User original intent (`conversation_history`) and Intent Structuring Result (ISR). + +Of these, `conversation_history` is used to carry User's original intent and its original context references; ISR is used to carry the structured expression resulting from clarification, confirmation and as a basis for ADD-IAC-ISS input. + +### User's original intent +`conversation_history` is the structure carrying User's original intent for recording the original content expressed in this intent link User or its verifiable summary and context references. + +|** Field name**|** Type**|** Existence**|** Conditions of restraint**|** Annotations**| +| --- | --- | --- | --- | --- | +|`user_intent_raw`|string or array [object]|Conditionally required|Exists with `user_intent_raw_digest` at least one|User original intent Content. This can be in the form of dialogue log arrays (objects with `role`, `content`, `create_time`, or in the form of pure text strings.| +|`user_intent_raw_digest`|string|Conditionally required|Exists with `user_intent_raw` at least one|User's original intent Summary values. This applies to the presence of multi-modular information such as voice, pictures, interactive cards in Intent Context, which does not allow for direct transmission of the full original intent content.| +|`input_mode`|array[string]|Optional|Numerical elements SHALL be input mode count values|User enters to support a mix of multiple modes of input.| +|`context_ref`|string|Conditionally required|must exist when `user_intent_raw_digest` exists|Reference pointing to the relevant session, local record or external storage location; the corresponding original content SHALL allow the calculation of summary values consistent with `user_intent_raw_digest`.| + +Of which: + ++ The examples of `user_intent_raw` are as follows. + +```plain +"user_intent_raw": [ + { + "role": "USER", + "content": "Please secure me a second-class ticket to Harbin on January 20.", + "create_time": "2025-12-23T10:28:00Z" + }, + { + "role": "ASSISTANT", + "content": "Train G123 still has tickets at CNY 600. Would you like me to monitor availability and place the order automatically?", + "create_time": "2025-12-23T10:28:05Z" + }, + { + "role": "USER", + "content": "Yes. Keep the limit under CNY 600 and check several times each day.", + "create_time": "2025-12-23T10:29:00Z" + } +] +``` + ++ Input_mode count values as follows + - `TEXT`: text input; + - `VOICE`: voice input; + - `IMAGE`: photo input; + - `INTERACTIVE_CARD`: Interactive cards; + - `OTHER`: Other inputs. + +This allows you to expand other input mode count values, but SHALL NOT changes the basic semantics of the above field. + +### Intent Structuring Result (ISR) +ISR is the core output object of this component, which is used to express the result of a structured intent resulting from semantic understanding, clarification and confirmation of User. This section defines ISR as a data dictionary, with only the name of the field, the type of field and the semantic of the field, and does not agree on the conditions for the existence of the field in this section. The specific existence of the field requirements is further regulated by the subsequent scenario rules, IAC issuance rules and sections of the relevant components. + +#### Basic fields +|** Field name**|** Type**|** Binding statements**|** Annotations**| +| --- | --- | --- | --- | +|`conversation_history`|object|SHALL meeting 3.3.1 definitions|Object User's original intent| +|`intent_id`|string|The only one in this chain of intent.|Mark user intent| +|`delegation_mode`|string|Enumeration values: `SPECIFIED`/ `BOUNDED`|Commission Mode| +|`validity_start_time`|string|ISO 8601 UTC|Start of commission| +|`validity_end_time`|string|ISO 8601 UTC, SHALL later than `validity_start_time`|Mandate end time| +|`max_total_amount`|number|SHALL greater than or equal to 0, keep 2 decimal places accurate|Maximum total amount authorized| +|`currency`|string|ISO 4217|Currency| +|`allowed_payment_methods`|array[string]|There's at least one way of allowing it.|Allowed List payment method| +|`agent_id`|string|SHALL be an identifiable Agent identifier|Implementation of Agent markings| +|`user_confirmation_method`|string|Defined by Accelerator|User Confirmation| +|`user_confirmation_timestamp`|string|must exist when `user_confirmation_method` exists; ISO 8601 UTC|Confirmation time User| +|`ext`|object|SHALL meeting 3.3.3 definitions|Standard extension field and private extension field namespace.| + +Delegation_mode extracts: + +|** Enumeration values**|** Semantic**|** Applicability**| +| --- | --- | --- | +|`SPECIFIED`|Targeted commissioning, authorization Scope is locked within a specified purchase target, Merchant or a clearer transaction boundary|User Invisible and Target-Specified| +|`BOUNDED`|Boundary commissioning, authorization to set mission objectives and behavioural boundaries only, with the option of Agent autonomous decision-making within the boundary|User Unaccompanied and autonomous decision-making within the border Agent| + +#### Standard Extension Fields +Includes three standard extensions: `ext.commerce`, `ext.agent_behavior` and `ext.fulfillment`. These extensions are used to carry goods and Merchant binding, Agent behavioural strategies and compliance requirements. + +`ext.commerce` field table: + +|** Field name**|** Type**|** Conditions of restraint**|** Annotations**| +| --- | --- | --- | --- | +|`max_single_amount`|number|SHALL greater than or equal to 0; SHALL NOT greater than `max_total_amount`|Single maximum amount| +|`min_single_amount`|number|SHALL greater than or equal to 0; SHALL NOT greater than `max_single_amount`|Single minimum amount| +|`allowed_categories`|array[string]|Element values defined by the achiever|The White List.| +|`forbidden_categories`|array[string]|Element values defined by the achiever|Class blacklist| +|`allowed_merchants`|array[string]|Element value SHALL be identifiable as Merchant|Merchant White List| +|`forbidden_merchants`|array[string]|Element value SHALL be identifiable as Merchant|Merchant Blacklist| + +`ext.agent_behavior` field table: + +|** Field name**|** Type**|** Conditions of restraint**|** Annotations**| +| --- | --- | --- | --- | +|`price_deviation_tolerance`|number|Percentage difference|Percentage change in price| +|`price_deviation_action`|string|Enumeration values: `PAUSE_AND_NOTIFY`/ `AUTO_CANCEL`|Handle actions when price differentials are exceeded| +|`on_payment_failure`|string|Enumeration values: `AUTO_RETRY`/ `CANCEL`|Payment Failed Method| +|`max_retry_count`|integer|SHALL greater than or equal to 0|Maximum number of retries| + +`ext.fulfillment` field table: + +|** Field name**|** Type**|** Conditions of restraint**|** Annotations**| +| --- | --- | --- | --- | +|`delivery_time_requirement`|string|Accomplishment-defining format|Time limits for distribution or performance| +|`delivery_address`|string|SHALL Reference for parsable or structured addresses|Distribution Address| + +#### Private extension +Except for standard extension fields, this protocol supports the carrying of private extension fields by `ext.vendor_private` as their logo. Private expansion fields may not change the existing semantics of ISR core fields or standard extension fields. +For unidentifiable private extension fields, the receiving party may ignore those parts of the core constraint understanding, but SHALL NOT changes the interpretation of ISR core semantics. + +## Processing of requests +### original intentAccess +User sideagent SHALL receives User original commercial intent and forms `conversation_history` object. + +Agent Records directly and transmits the full user_intent_raw. Agent calculates `user_intent_raw_digest` and points `context_ref` to relevant sessions or local records in situations where voice, pictures, interactive cards, etc. are not available to directly record and transmit the full original intent conversation. +If this input contains multiple modes of input, Agent can record the hybrid mode in `input_mode`. + +### Preliminary understanding and structured draft generation +After obtaining original intent, the User side Agent should be given a preliminary semantic understanding and extract the core elements related to commercial commissioning. These elements may include, but are not limited to, commissioning objectives, monetary boundaries, time boundaries, payment method limits, Merchant or class restraints, compliance requirements and Agent behavioural strategies. On this basis, Agent SHALL generate drafts ISR. + +### Intended clarifications and draft updates +When original intent is ambiguous, key constraints are missing, conditions are incomplete or there is a clear conflict, the User sideagent SHALL initiate clarification to User. The clarification process may be a single or multiple round; the specific interaction is determined by the party who achieved it and does not belong to the norm of this protocol Scope. + +After each valid clarification, the draft ISR should be updated so that it is gradually reduced to a structured outcome that expresses the true intent and border conditions of User. + +### Confirmation User +Once the draft ISR has reached an understandable and identifiable level, the User side agent SHOULD display the structured summary to User in an understandable manner and is confirmed by User. The confirmation SHALL be sufficient to reflect the core objectives of this mandate and the main boundary. + +### ISR Output +User Upon confirmation, User sideagent SHALL generate the final ISR. If subsequent issuance is required Intent Authorization Credential, ADD-IAC-ISS SHALL be used as the basis for the entry ISR. + +### Retention original intent +At User sideagent SHOULD, original records relating to this intent link or their verifiable references are kept locally to support subsequent dispute resolution, manual review or audit. +The duration of the retention period SHOULD be not less than the duration of the reasonable dispute resolution period following the completion of the mission. -The Authorization & Delegation Domain (ADD) specifies the expression, confirmation, and structured constraints of user intent, the issuance of authorization credentials, and their lifecycle management. It provides an expressive, constrained, verifiable, and traceable authorization foundation for an Agent acting on behalf of a user in commercial activities. +# Signature ADD-IAC-ISS: Intent Authorization Credential +## Overview +User Intent Authorization Credentialissuance (Intent Cooperation Central Insurance, ADD-IAC-ISS) on how to translate the final ISR into commerce interaction, payment execution and trusted attestation User Intent Authorization Credential (IAC) to be followed up by commerce interaction, trusted attestation Intent Authorization Credential. -This document is the official informative English translation of the normative ACT 2.1 Authorization & Delegation Domain text in this release. The [ACT Protocol Authorization & Delegation page](https://www.act-protocol.com/documentation/delegation) is an unversioned informative reference. +This component defines the business semantics of IAC, the boundary of the pending signature load, the sealing requirements of the voucher and the process of issuance. -## 1. Scope and boundaries +IAC is entered for the final ISR but ultimately ISR does not necessarily have all the contents in the IAC to be signed; only fields that constitute the basis for the authorized boundary, enforcement constraints and subsequent verifications will SHALL be included in the IAC signature Scope. -ADD covers: +## Participants and prefix +This component involves the following Participants: Principal, entrusted with Agent, and the realization component or service that provides signature, key call or document seal support. +In practical terms, the issuance process can be carried out in conjunction with security capabilities such as identity verification, protected interaction, key access control and control certificates, but the related security capabilities can be provided by external security support protocols. -- capture, clarification, confirmation, and structured expression of the user's original intent; -- creation and referencing of an Intent Structured Result (ISR); -- construction, issuance, and packaging of an Intent Authorization Credential (IAC); -- IAC lifecycle states, state transitions, and validity checks. +Before entering this component, SHALL satisfies the following preconditions: -ADD does not specify front-end presentation, prompt engineering, model reasoning, or multimodal recognition algorithms. It also does not specify the internal implementation of identity infrastructure, private-key custody, or signing services. Product discovery and transaction confirmation belong to CID; payment and funds processing belong to PSD; evidence event structures and governance belong to TSD. ++ The final ISR has been formed and has entered the confirmation chain for User. User confirmation actions for the final ISR can be triggered directly by the authorization issued IAC. ++ The designation Agent of the mandate has been clarified, along with the modalities of the mandate, its duration and the main binding boundaries. ++ The achiever has the capacity to generate `delegation_id`, construct IAC to be signed, implement normative processing and output ultimately IAC. ++ IAC The signature private key SHALL be hosted by the controlled key management capability and signed in a credible execution environment or an equivalent controlled signature environment; the business application shall not disclose or hold the signature key for IAC issuance in an explicit manner. When ASL is used by the implementer as a security support protocol, the issuer ' s identification, key call, signature generation, control certificate and related status queries can be completed by ASL-IDN, ASL-INF-KMS and ASL-INF-SEE, respectively. -## 2. Components and core objects +## Data structure and field tables +### IAC to be signed load +The IAC to be signed payload is based on the final ISR screening and reorganization of authorized business subjects to express “who authorizes which Agent within what boundaries to act on its behalf”. IAC to be signed payload SHOULD be defined as follows: -| Component | Purpose | Primary output | -|---|---|---| -| `ADD-INT-ICS` | Capture, clarify, confirm, and structure user intent | Original user intent, ISR, `intent_id` | -| `ADD-IAC-ISS` | Select authorization boundaries from the final ISR, normalize, sign, and package them | IAC, `delegation_id` | -| `ADD-IAC-LCM` | Manage active, suspended, resumed, revoked, and expired IAC states | Queryable authorization state | +|** Field name**|** Type**|** Existence**|** Binding statements**|** Annotations**| +| --- | --- | --- | --- | --- | +|`delegation_id`|string|Required|Only identifier for this IAC|The only mark of this IAC is also the primary mark of this authorized life cycle| +|`intent_id`|string|Optional|ISR Upstream when the mark is generated|Corresponding user intent sign(s); can be used to establish IAC correspondence with ISR upstream when ISR has been generated| +|`conversation_history`|object|Conditionally required|When `intent_id` is not generated and the achiever carries the object original intent directly; if available, SHALL meets the definition of 3.3.1.|When `intent_id` is not generated, `conversation_history` can directly serve as the basis for upstream input for this mandate; this approach is more appropriate for the smaller byte scenario User's original intent| +|`delegator_identity`|string|Required|Authorisation of the issuer identifier, i.e. the client identifier|Authorization of the issuer ' s identifier, usually corresponding to Principal or the subject identifier initiated on behalf of Principal| +|`agent_id`|string|Required|Trusted identification Agent|Identification of Agent authorized for follow-up actions| +|`delegation_mode`|string|Optional|Enumeration values: `SPECIFIED` / `BOUNDED`, default value when not completed `SPECIFIED`|Commission Mode| +|`validity_start_time`|string|Required|ISO 8601 UTC|Time of validity of authorization| +|`validity_end_time`|string|Required|ISO 8601 UTC, SHALL later than `validity_start_time`|Time of expiry of authorization| +|`max_total_amount`|number|Required|SHALL greater than or equal to 0, keep 2 decimal places accurate|Maximum total amount authorized| +|`currency`|string|Optional|ISO 4217; Default for unfilled `CNY`|Currency| +|`allowed_payment_methods`|array[string]|Optional|If entered Scope for signature, SHALL remain consistent with the semantics of the field ISR|Allowed List payment method| +|`user_confirmation_method`|string|Optional|Defined by Accelerator|User Confirmation or nuclei| +|`user_confirmation_timestamp`|string|Conditionally required|SHALL Sync presence when `user_confirmation_method` exists; ISO 8601 UTC|User Time of completion of confirmation or nuclei| +|`source_isr_digest`|string|Optional|Excerpt values used to express upstream ISR or their agreed summary Scope|Fill in if the achiever needs a more stable cross-domain verification anchor| +|`ext`|object|Optional|ISR Extension bounds to IAC, SHALL directly follow the `ext` structure and field syntax of ISR|Expand Field Naming Space| -| Object or identifier | Normative semantics | Downstream use | -|---|---|---| -| Original user intent | The original commercial intent expressed by the user through natural language or another modality | ADD processing and necessary retrospective review | -| `intent_id` | Identifier spanning intent confirmation, ISR, and cross-domain flows | CID, PSD, TSD | -| ISR | Structured rule expression of the user's goals, constraints, and boundaries | IAC issuance and CID rule validation | -| IAC | Verifiable packaging of authorization boundaries | PSD DEL/AUP and TSD | -| `delegation_id` | Unique identifier for one IAC and its lifecycle | LCM, PSD, TSD | -| Authorization state | Whether the IAC can currently be accepted | CID, PSD, and other verifiers | +Treatment of `ext`: -## 3. `ADD-INT-ICS`: intent capture and structured expression ++ IAC If you need to carry the extension restriction in ISR, SHALL simply follow the namespace and field syntax of `ext` in ISR. ++ Whether or not to include an extension field in the signature of IAC is determined by the fulfilment party on the basis of whether or not it affects the subsequent authorization; no requirement to sign all of the extensions in ISR together with IAC. -### 3.1 Original user intent +### Eventually IAC +Ultimately IAC is a verifiable authorization credential object formed by the completion of the signature, encapsulation and addition of the necessary metadata on the basis of IAC signature loads. This chapter defines only its components and its semantic boundaries in the final IAC without specifying a specific field-level structure to be achieved in a format compatible with the different document envelopes. -`conversation_history` carries the user's original content, or a verifiable digest and contextual reference to that content: +Ultimately IAC may include the following components: -| Field | Presence | Normative semantics | -|---|---|---| -| `user_intent_raw` | Conditionally required | At least one of `user_intent_raw` and `user_intent_raw_digest` MUST be present | -| `user_intent_raw_digest` | Conditionally required | Digest of the original intent; at least one of this field and `user_intent_raw` MUST be present | -| `input_mode` | Optional | `TEXT`, `VOICE`, `IMAGE`, `INTERACTIVE_CARD`, or `OTHER`; values may be combined | -| `context_ref` | Conditionally required | Required when a digest is present; the referenced content MUST reproduce the same digest | ++ `protected_header` or equivalent encapsulation metadata for the expression of algorithm identification, type of encapsulation, key location information and necessary configuration identifiers. ++ `credential_metadata` for the expression of underlying metadata such as the issuer, the trustee, the time of issuance, the time of entry into force, the time of expiry and the certificate identifier. ++ `credential_subject` or equivalent service load area to carry the IAC signature load as defined in 4.3.1. ++ `proof` for the purpose of expressing a certificate of signature generated for the agreed signature Scope. ++ `status_reference` to support follow-up status queries, life-cycle management or related verification links. ++ `control_proof_ref` is an optional component; in a high-risk issuance scenario, it can be used to refer to a control certificate or a summary thereof in relation to the current call for the signature. -Additional input modes MUST NOT change the basic semantics of existing fields. When the complete original content cannot be transferred, only the digest and reference MAY be transferred, but the implementation MUST still protect the verifiability, access control, and retention period of the original record. +## Processing of requests +### ISR Integrity check and confirmation trigger +Trusted to receive agent SHALL final ISR and to check that it has reached the status of confirmation and issuance of User, has a clear commissioning model, Agent marking, validity period and primary authorized boundary. In the event that ISR ultimately lacks the key authorization information necessary to constitute IAC, SHALL NOT enters the formal issuance process. -### 3.2 ISR data dictionary +User Confirmation actions for the final ISR may be issued directly as trigger actions for IAC. SHOULD NOT Compulsory confirmation of User on the same authorized matter due to design Protocol Flow. -ACT 2.1 defines ISR as a data dictionary, not a frozen wire schema. It specifies names, types, and semantics, but does not assign uniform presence requirements to every field in this table. Scenario rules, IAC issuance rules, and downstream components apply further constraints. +### IAC to be signed load construction +agent SHALL be entrusted with the construction of the IAC to be signed payload based on the final ISR and the identification of fields into this IAC signature Scope. SHALL be then based on the principle of “based ISR filtering and reorganization” and SHALL NOT will eventually be ISR as a whole. IAC -| Field | Normative semantics | -|---|---| -| `conversation_history` | Original user-intent object | -| `intent_id` | Identifier unique within the current intent chain | -| `delegation_mode` | `SPECIFIED` or `BOUNDED` | -| `validity_start_time` / `validity_end_time` | ISO 8601 UTC validity window; the end MUST be later than the start | -| `max_total_amount` / `currency` | Maximum total authorized amount and ISO 4217 currency | -| `allowed_payment_methods` | Permitted payment methods | -| `agent_id` | Identifier of the executing Agent | -| `user_confirmation_method` / `user_confirmation_timestamp` | User confirmation method and time | -| `ext` | Namespaces for standard and private extensions | +### Normative treatment +Before entering the signature, the achiever shall perform a definitive normative treatment of IAC to be performed in the agreed signature Scope to ensure consistency between cross-domain signatures and abstracts. The issuer in the same deployment will keep the field name, regularize rules and the signature entered into the boundary by the certifying party SHALL, otherwise the signature or summary verification will fail. -`SPECIFIED` applies when the target, merchant, or transaction boundary is explicit. `BOUNDED` applies when the user specifies a task goal and behavioral boundaries while allowing the Agent to make concrete choices within those boundaries. +If JSON is used as a payload expression, SHOULD applies the regulatory treatment of JSON Canonicalization Scheme (JCS) as defined by RFC 8785. -### 3.3 Standard extensions +### Signature Generation +After the formalization has been completed, the achieving party should enter the agreed signature into the executed signature, generating `proof` of IAC. -| Extension block | Fields | -|---|---| -| `ext.commerce` | `max_single_amount`, `min_single_amount`, `allowed_categories`, `forbidden_categories`, `allowed_merchants`, `forbidden_merchants` | -| `ext.agent_behavior` | `price_deviation_tolerance`, `price_deviation_action`, `on_payment_failure`, `max_retry_count` | -| `ext.fulfillment` | `delivery_time_requirement`, `delivery_address` | +### Certificate Envelope +When the result of the signature is obtained, the person SHALL assemble the pending signature load, certificate metadata, signature certificate and necessary references to information as final IAC. The sealed IAC SHALL be able to express the issuer, be trusted Agent, authorized boundaries, validity period and signature certificate, and will support subsequent independent verification. -`price_deviation_action` uses `PAUSE_AND_NOTIFY` or `AUTO_CANCEL`. `on_payment_failure` uses `AUTO_RETRY` or `CANCEL`. `ext.vendor_private` MAY carry private extensions, but MUST NOT change the semantics of core fields or standard extensions. Unrecognized private fields that do not affect core constraints MAY be ignored. +## Seal and signature requirements +This component uses a non-encapsulation rule for IAC; it achieves a mapable cover of a certificate type, a JWS type envelope or other equivalent to validate expression, but the selected envelope SHALL be able to stabilize the carrier ' s issuer, trustee, time limit, IAC pending signature load and signature certificate. This version uses W3C VC-JWT as one of the recommended means of realization, but is not the only cover format. -### 3.4 Processing requirements +Signature Scope SHALL be clearly stated by the implementer and is consistent within the same deployment. By default, the signature input SHALL be a IAC to be signed or its equivalent normative expression in the agreed signature Scope, rather than a full ISR original text. In the context of the JSON regularization, SHALL retains the original name of the field, SHALL NOT changes the synonym of the signature input due to the style of automatic transformation of the serial framework field. -1. The user-side Agent captures the original intent and forms `conversation_history`. -2. The Agent creates an ISR draft. If it encounters ambiguity, missing critical constraints, or conflicts, it clarifies them and updates the draft. -3. The Agent presents the primary goals and boundaries in a form the user can understand and creates the final ISR after obtaining confirmation. -4. When a downstream IAC is needed, `ADD-IAC-ISS` uses the final ISR as its input basis. -5. The original intent, or a verifiable reference to it, SHOULD be retained under access control for a reasonable dispute period. The implementation determines the exact duration and medium according to applicable legal and governance requirements. +When the implementer uses ASL as a security support protocol, normative references can be made in the following manner: -## 4. `ADD-IAC-ISS`: Intent Authorization Credential issuance ++ The signature generation of IAC can be `Sign` completed by reference to ASL-INF-KMS, matching the signature key use SHALL with the signature use authorization credential, SHALL NOT with other uses. ++ User recognition, local sensitive interaction and signature call under a high-risk authorization scenario, SHOULD combined with ASL-INF-SEE protected interactive capability and ASL-INF-KMS control certification capability. ++ SHOULD refers to ASL-INF-KMS control certification capabilities when the signature is required to record evidence calling for access control strategies, and carries `control_proof_ref` or equivalent references in IAC at the end. -### 4.1 Issuance boundary +# ADD-IAC-LCM: Intent Authorization Credential Life cycle management +## Overview +Intent Authorization Credential Lifecycle Management (Intent Autoration Central Life Cycle Management, ADD-IAC-LCM) defines IAC legal status, status migration rules and treatment requirements. -An IAC is not an indiscriminate copy of the final ISR. Only content that forms the authorization boundary, execution constraints, and basis for downstream verification enters the payload to be signed. A single user confirmation of the final ISR MAY directly trigger issuance; the workflow SHOULD NOT require the user to reconfirm the same matter solely because of process design. +This component applies to the status management, authentication and related certificate processing of IAC issued. -Before issuance, the delegated Agent, delegation mode, validity period, and principal constraints MUST already be explicit. The signing private key MUST be held by a controlled key-management capability and used within a trusted execution environment or an equivalently controlled environment. Business applications MUST NOT hold the issuance private key in plaintext. +## Definitions State Machine +IAC The rules of legality and flow within their life cycle are as follows. -### 4.2 IAC payload to be signed +|** Status Value**|** Semantic**|** Trigger Condition**|** Restorability**| +| --- | --- | --- | --- | +|`Active`|Valid, available at commerce interaction and payable.|IAC Completed and not suspended or cancelled during its validity|—| +|`Suspended`|Pause, temporarily unavailable.|Principal or risk control system initiated temporary suspension, and the voucher has not been terminated|Restoreable| +|`Expired`|Expired, not available|`validity_end_time` Arrival, system automatically activated|Unrecoverable.| +|`Revoked`|Cancelled, permanently unusable|Principal or entrusted Agent to initiate a permanent revocation|Unrecoverable.| -| Field | Presence | Normative semantics | -|---|---|---| -| `delegation_id` | Required | Unique identifier for the IAC and authorization lifecycle | -| `intent_id` | Optional | Correlates the IAC with the upstream ISR | -| `conversation_history` | Conditionally required | Used when no `intent_id` is present and the original-intent object is carried directly | -| `delegator_identity` | Required | Identifier of the delegator or the subject issuing on the delegator's behalf | -| `agent_id` | Required | Identifier of the Agent authorized to act | -| `delegation_mode` | Optional | `SPECIFIED` / `BOUNDED`; defaults to `SPECIFIED` | -| `validity_start_time` / `validity_end_time` | Required | ISO 8601 UTC authorization window | -| `max_total_amount` | Required | Maximum total authorized amount | -| `currency` | Optional | ISO 4217; defaults to `CNY` | -| `allowed_payment_methods` | Optional | Retains ISR semantics when included in the signed scope | -| `user_confirmation_method` / `user_confirmation_timestamp` | Optional / conditionally required | User confirmation method and time | -| `source_isr_digest` | Optional | Digest of the upstream ISR or an agreed digest scope | -| `ext` | Optional | ISR extension constraints that affect authorization verification | +## Status migration rules +The IAC status migration rules are as follows. -Whether an `ext` field is included in the signed scope depends on whether it affects downstream authorization verification. The IAC is not required to sign every ISR extension field. +|** Current Status**|** Target Status**|** Trigger Condition**|** Is it counterproductive?**| +| --- | --- | --- | --- | +|`Active`|`Suspended`|Principal or risk control system initiating temporary hangup|Yes.| +|`Suspended`|`Active`|Principal or risk control system unmounted|Yes.| +|`Active`|`Revoked`|Principal or commissioned Agent to initiate the revocation|Yes| +|`Suspended`|`Revoked`|Principal or commissioned Agent to initiate the revocation|Yes| +|`Active`|`Expired`|Arrival at `validity_end_time`|Yes| +|`Suspended`|`Expired`|`validity_end_time`Arrivals|Yes| -### 4.3 Final IAC and signatures +Of which `Revoked` and `Expired` are final. IAC may not be restored to Active or Suspended. Suspended is temporarily restricted and can only be lifted and returned to Active under clearly defined restoration conditions. -The final IAC MAY consist of `protected_header`, `credential_metadata`, `credential_subject`, `proof`, `status_reference`, and, in high-risk scenarios, an optional `control_proof_ref`. The source specification defines the semantic boundaries of these parts but does not yet freeze a final field-level envelope. +## Processing of requests +### Effective status +IAC Upon issuance, if the current time has entered its active time window and it has not been suspended or revoked, the status SHALL be `Active`. The IAC status of `Active` may be followed by commerce interaction, payment execution and authorization of verification is routinely quoted. -Before signing, the agreed signing scope MUST be deterministically canonicalized. JSON payloads SHOULD use RFC 8785 JCS. Issuers and verifiers in the same deployment MUST use consistent field names, canonicalization rules, and signing-input boundaries. Implementations MAY map the IAC to a verifiable-credential envelope, a JWS-style envelope, or an equivalent representation. W3C VC-JWT is one recommended approach, not the only allowed format. +### Suspend +Principal or a risk control system may be temporarily suspended for the duration of IAC. After that, the state of IAC shall be changed to `Suspended`. IAC in `Suspended` status shall not continue to be used for commerce interaction, payment execution or authorization verification. +agent SHOULD Step to Report `act:delegation:delegation-suspended` Testimony Event. -## 5. `ADD-IAC-LCM`: lifecycle management +### Unstagger +IAC, in `Suspended` state, can be removed from operation by Principal or by the risk control system. After release, IAC state SHALL be restored to `Active`. +agent SHOULD Step to Report `act:delegation:delegation-resumed` Testimony Event. -### 5.1 States and transitions +### Cancel +After cancellation, the status of IAC shall be changed to `Revoked`. IAC in `Revoked` status shall not continue to be used for commerce interaction, payment for execution or authorization of verification. +agent SHOULD Step to Report `act:delegation:delegation-revoked` Testimony Event. -| State | Semantics | Recoverability | -|---|---|---| -| `Active` | Within the validity window and neither suspended nor revoked; available for downstream use | — | -| `Suspended` | Temporarily unavailable | MAY return to `Active` | -| `Revoked` | Permanently revoked | Terminal | -| `Expired` | `validity_end_time` has been reached | Terminal | +### Autoprocessing due +When `validity_end_time` arrives, IAC status SHALL be automatically changed to `Expired`. IAC in `Expired` status shall not continue for commerce interaction, payment for execution or authorization of verification. +agent SHOULD Step to Report `act:delegation:delegation-expired` Testimony Event. -Allowed transitions are `Active → Suspended`, `Suspended → Active`, `Active/Suspended → Revoked`, and `Active/Suspended → Expired`. `Revoked` and `Expired` MUST NOT return to another state. +## Authentication status verification +In the follow-up, when citing IAC, SHALL confirms at least the following: -### 5.2 State handling and validation ++ Whether IAC is in a valid time window. ++ IAC Whether the current status is `Active`. ++ IAC Whether there are known suspensions, revocations or expirys. -- A `Suspended`, `Revoked`, or `Expired` IAC MUST NOT continue to be used for commerce interaction, payment execution, or authorization validation. -- Suspension, resumption, revocation, and expiration SHOULD be reported asynchronously as `act:delegation:delegation-suspended`, `delegation-resumed`, `delegation-revoked`, and `delegation-expired`. TSD defines the event structure. -- A processor that references an IAC MUST at least check the validity window, confirm that the current state is `Active`, and check for known suspension, revocation, or expiration results. -- Before making a final decision, the processor MUST obtain the current state through `status_reference`. If the state service is temporarily unavailable, the latest locally successful result and `validity_end_time` MAY be used for temporary risk control, but this is not a basis for permanently omitting state checks. - -## 6. Current machine-contract boundary - -ACT 2.1 defines the data dictionaries, presence requirements, and processing semantics, but does not publish an ISR/IAC JSON Schema, envelope version, algorithm suite, state-query protocol, event Schema, or standard error object. This repository does not invent those machine contracts from examples or descriptive text. - -## 7. Sources - -- Related ADD website reference: [Authorization & Delegation Domain](https://www.act-protocol.com/documentation/delegation); content not labeled ACT 2.1 is not a normative source for this release -- Cross-domain scenarios: [Scenarios and business flows](https://www.act-protocol.com/documentation/scenarios) -- CID: [Commerce Interaction Domain](https://www.act-protocol.com/documentation/commerce) -- PSD: [Payment Services Domain](https://www.act-protocol.com/documentation/payment) -- TSD: [Trust Services Domain](https://www.act-protocol.com/documentation/trust) +The processor can obtain the current status by `status_reference` before making a final authorization validity judgement. When the status service is temporarily unavailable, the process can perform interim risk control based on the last local successful query and `validity_end_time`. diff --git a/docs/specification/authorization-delegation.md b/docs/specification/authorization-delegation.md index ab3bfa2..1b10ddb 100644 --- a/docs/specification/authorization-delegation.md +++ b/docs/specification/authorization-delegation.md @@ -2,155 +2,343 @@ 中文 | [English](authorization-delegation.en.md) -> **状态：ACT 2.1 Specification / Final / Normative** -> **协议内容已经定稿；是否符合本规范需要独立 Conformance 证据。** -> 版本基线：2026-08-11（UTC+8） +# 范围 +## 本域定位 +委托授权域（Authorization & Delegation Domain, ADD）规定用户意图的表达、确认、结构化约束、授权凭证签发及其生命周期管理规则，为智能体代表用户开展商业活动提供可表达、可约束、可验证、可追溯的授权基础。 + +## 本域职责范围 +本域覆盖以下内容： + ++ 用户原始意图的获取、澄清、确认与结构化表达； ++ 意图结构化结果（ISR）的生成与引用； ++ 意图授权凭证（IAC）的构造、签发与封装； ++ IAC 生命周期状态及其可见语义。 + +本域不规范以下内容： + ++ 前端交互样式、提示词工程、模型推理过程及多模态底层识别算法； ++ 具体身份基础设施、私钥托管实现和签名服务内部实现； ++ 商品发现、交易协商、购物车确认、支付渠道报文、资金清算结算。 + +# 本域组件列表与关系 +## 组件总览 +委托授权域由三个协议组件构成，它们共同完成从用户原始意图输入到授权凭证可用的完整链路。各组件的功能定位如下： + ++ **ADD-INT-ICS：意图获取及结构化表达。** 负责接收用户原始意图，完成必要的语义澄清、用户确认和结构化表达，形成后续授权流程可引用的意图结构化结果。 ++ **ADD-IAC-ISS：意图授权凭证签发。** 负责将结构化意图封装为跨域可验证的授权凭证，并完成必要的签名或签发动作。 ++ **ADD-IAC-LCM：意图授权凭证生命周期管理。** 负责定义和管理 IAC 在有效期内的状态变化及其可见语义。 + +## 核心对象与标识 +为保持本域内部及跨域处理的一致性，ADD 使用一组标准核心对象和标识键来描述用户授权链路中的关键状态。本域核心对象及其作用可概括如下： + +| **对象或标识** | **含义** | **主要产生位置** | **主要使用位置** | +| --- | --- | --- | --- | +| 用户原始意图 | 用户以自然语言或其他输入方式表达的原始商业意图内容。 | ADD-INT-ICS | ADD-INT-ICS，以及必要时用于事后核查的相关处理环节。 | +| `intent_id` | 用户意图标识，用于贯穿意图确认、结构化表达及后续跨域引用 | ADD-INT-ICS | ADD 域内部，以及需要引用该意图上下文的其他域 | +| 意图结构化结果
（Intent Structured Result, ISR） | 对用户商业目标、约束和边界的结构化规则表达 | ADD-INT-ICS | ADD-IAC-ISS，以及需要引用该规则的其他域 | +| 意图授权凭证 (Intent Authorization Credential, IAC) | 对 ISR 进行可验证封装后的授权凭证对象 | ADD-IAC-ISS | ADD-IAC-LCM、支付服务域、信任服务域 | +| `delegation_id` | IAC 的生命周期唯一标识，用于标识一个正式的授权凭证 | ADD-IAC-ISS | ADD-IAC-LCM、支付服务域、信任服务域 | +| 授权状态 | IAC 当前是否可用的状态，如 Active、Suspended、Revoked、Expired | ADD-IAC-LCM | 支付服务域，以及其他需要判断授权有效性的处理环节 | + +## 依赖与跨域引用 +ADD-INT-ICS 形成的 ISR 构成 ADD-IAC-ISS 的签发依据。ADD-IAC-ISS 形成的 IAC 和 `delegation_id` 构成 ADD-IAC-LCM 的管理对象，ADD-IAC-LCM 给出的授权状态将影响后续环节是否接受该授权凭证。 + +商业交互域主要引用 ISR 及相关约束上下文，以支持商品发现、意图传递和交易确认。支付服务域主要引用 IAC、`delegation_id` 及授权状态结论，以支持支付请求中的授权校验。信任服务域可信存证子篇统一维护相关事件类型和存证治理规则，本域不重复定义。 + +# ADD-INT-ICS：意图获取及结构化表达 +## 概述 +意图获取及结构化表达（Intent Capture and Structured Expression, ADD-INT-ICS）规定用户原始意图的获取、语义澄清、用户确认和结构化表达的处理要求。 + +本组件的目标是将用户以自然语言或其他输入方式表达的原始商业意图，转化为可被后续授权流程引用和校验的意图结构化结果（Intent Structured Result, ISR）。 + +本组件不规范具体的人机交互界面、提示词工程、模型推理过程及多模态底层识别算法。 + +## 参与方与前置条件 +本组件涉及以下参与方：用户，以及负责接收、解析、澄清、确认并生成 ISR 的用户侧智能体。 + +进入本组件前，应满足以下前置条件： + ++ 用户侧智能体已建立与用户的有效交互上下文。 ++ 用户能够以实现方支持的输入方式表达商业意图。 ++ 用户侧智能体具备本地留存原始意图以及输出 ISR 的能力。 + +## 数据结构与字段表 +本组件处理过程中涉及两个核心对象：用户原始意图（`conversation_history`），以及意图结构化结果（ISR）。 + +其中，`conversation_history` 用于承载用户原始意图及其原始上下文引用；ISR 用于承载经澄清、确认后形成的结构化表达结果，并作为 ADD-IAC-ISS 的输入基础。 + +### 用户原始意图 +`conversation_history` 是承载用户原始意图的结构体，用于记录用户在本次意图链路中表达的原始内容，或其可校验的摘要与上下文引用。 + +| **字段名** | **类型** | **存在性** | **约束条件** | **说明** | +| --- | --- | --- | --- | --- | +| `user_intent_raw` | string或array[object] | 条件必备 | 与 `user_intent_raw_digest`至少一项存在 | 用户原始意图内容。可采用对话记录数组形式（每条为含`role`、`content`、`create_time`的对象），也可采用纯文本字符串形式。 | +| `user_intent_raw_digest` | string | 条件必备 | 与 `user_intent_raw`至少一项存在 | 用户原始意图的摘要值。适用于意图上下文中存在语音、图片、交互式卡片等多模态信息时，不方便直接传递完整原始意图内容的情形。 | +| `input_mode` | array[string] | 可选 | 数组元素应为输入模式枚举值 | 用户输入方式，支持多种输入方式的混合。 | +| `context_ref` | string | 条件必备 | 当存在 `user_intent_raw_digest`时必须存在 | 指向相关会话、本地记录或外部存储位置的引用；该引用对应的原始内容应能计算出与 `user_intent_raw_digest`一致的摘要值。 | + +其中： + ++ `user_intent_raw` 的示例如下。 + +```plain +"user_intent_raw": [ + { + "role": "USER", + "content": "帮我抢一张1月20号回哈尔滨的票，二等座。", + "create_time": "2025-12-23T10:28:00Z" + }, + { + "role": "ASSISTANT", + "content": "查询到G123次还有票，价格600元，需要帮您自动监控下单吗？", + "create_time": "2025-12-23T10:28:05Z" + }, + { + "role": "USER", + "content": "好的，限额600以内，每天帮我多刷几次。", + "create_time": "2025-12-23T10:29:00Z" + } +] +``` + ++ input_mode 枚举值如下 + - `TEXT`：文本输入； + - `VOICE`：语音输入； + - `IMAGE`：图片输入； + - `INTERACTIVE_CARD`：交互式卡片； + - `OTHER`：其他输入方式。 + +实现方可扩展其他输入模式枚举值，但不应改变上述字段的基本语义。 + +### 意图结构化结果（ISR） +ISR 是本组件的核心输出对象，用于表达经语义理解、澄清和用户确认后形成的结构化意图结果。鉴于不同业务场景对字段完备性的要求不同，本节将 ISR 定义为数据字典，仅规定字段名称、字段类型与字段语义，不统一规定本节中的字段存在性条件。字段的具体存在要求，由后续场景规则、IAC 签发规则及相关组件章节进一步约束。 + +#### 基本字段 +| **字段名** | **类型** | **约束说明** | **说明** | +| --- | --- | --- | --- | +| `conversation_history` | object | 应符合 3.3.1 定义 | 用户原始意图对象 | +| `intent_id` | string | 在本次意图链路内唯一 | 用户意图标识 | +| `delegation_mode` | string | 枚举值：`SPECIFIED` / `BOUNDED` | 委托模式 | +| `validity_start_time` | string | ISO 8601 UTC | 委托起始时间 | +| `validity_end_time` | string | ISO 8601 UTC，且应晚于`validity_start_time` | 委托结束时间 | +| `max_total_amount` | number | 应大于或等于 0，精度保留 2 位小数 | 授权总金额上限 | +| `currency` | string | ISO 4217 | 币种 | +| `allowed_payment_methods` | array[string] | 至少包含一种允许方式 | 允许的支付方式列表 | +| `agent_id` | string | 应为可识别的智能体标识 | 执行智能体标识 | +| `user_confirmation_method` | string | 由实现方定义枚举 | 用户确认方式 | +| `user_confirmation_timestamp` | string | 当存在 `user_confirmation_method`时必须存在；ISO 8601 UTC | 用户确认时间 | +| `ext` | object | 应符合 3.3.3 定义 | 标准扩展字段及私有扩展字段命名空间。 | + +delegation_mode 取值说明： + +| **枚举值** | **语义** | **适用情形** | +| --- | --- | --- | +| `SPECIFIED` | 定向委托，授权范围已锁定在明确的购买目标、商户或较明确的交易边界内 | 用户不在场且购买目标已明确的场景 | +| `BOUNDED` | 边界委托，授权只设定任务目标与行为边界，具体选择可由智能体在边界内自主决策 | 用户不在场且由智能体在边界内自主决策的场景 | + +#### 标准扩展字段 +包括三类标准扩展块：`ext.commerce`、`ext.agent_behavior` 和 `ext.fulfillment`。这些扩展字段用于承载商品与商户约束、智能体行为策略以及履约要求。 + +`ext.commerce`字段表： + +| **字段名** | **类型** | **约束条件** | **说明** | +| --- | --- | --- | --- | +| `max_single_amount` | number | 应大于或等于 0；如存在，不应大于 `max_total_amount` | 单笔最高金额 | +| `min_single_amount` | number | 应大于或等于 0；如存在，不应大于 `max_single_amount` | 单笔最低金额 | +| `allowed_categories` | array[string] | 元素值由实现方定义 | 品类白名单 | +| `forbidden_categories` | array[string] | 元素值由实现方定义 | 品类黑名单 | +| `allowed_merchants` | array[string] | 元素值应为可识别商户标识 | 商户白名单 | +| `forbidden_merchants` | array[string] | 元素值应为可识别商户标识 | 商户黑名单 | + +`ext.agent_behavior`字段表： + +| **字段名** | **类型** | **约束条件** | **说明** | +| --- | --- | --- | --- | +| `price_deviation_tolerance` | number | 表示百分比容差 | 价格变动容差百分比 | +| `price_deviation_action` | string | 枚举值：`PAUSE_AND_NOTIFY`/`AUTO_CANCEL` | 超出价格容差时的处理动作 | +| `on_payment_failure` | string | 枚举值：`AUTO_RETRY`/ `CANCEL` | 支付失败处理方式 | +| `max_retry_count` | integer | 应大于或等于 0 | 最大重试次数 | + +`ext.fulfillment`字段表： + +| **字段名** | **类型** | **约束条件** | **说明** | +| --- | --- | --- | --- | +| `delivery_time_requirement` | string | 由实现方定义格式 | 配送或履约时效要求 | +| `delivery_address` | string | 应为可解析地址或结构化地址引用 | 配送地址 | + +#### 私有扩展 +除标准扩展字段外，本协议支持通过 `ext.vendor_private` 作为标识进行私有扩展字段的承载。私有扩展字段不得改变 ISR 核心字段及标准扩展字段的既有语义。 +对于无法识别的私有扩展字段，接收方可忽略其不影响核心约束理解的部分，但不应改变对 ISR 核心语义的解释结果。 + +## 处理要求 +### 原始意图获取 +用户侧智能体应接收用户提出的原始商业意图，并形成 `conversation_history` 对象。 + +智能体宜直接记录并传递完整的 user_intent_raw。在存在语音、图片、交互式卡片等不便直接记录并传递完整原始意图对话内容的场景中，智能体可计算`user_intent_raw_digest`，并通过 `context_ref` 指向相关会话或本地记录。 +如本次输入包含多种输入方式，智能体可在 `input_mode` 中记录混合输入模式。 + +### 初步理解与结构化草稿生成 +在获取原始意图后，用户侧智能体应对其进行初步语义理解，并提取与商业委托相关的核心要素。这些要素可包括但不限于委托目标、金额边界、时间边界、支付方式限制、商户或品类约束、履约要求和智能体行为策略。在此基础上，智能体应生成 ISR 草稿。 + +### 意图澄清与草稿更新 +当原始意图存在歧义、关键约束缺失、条件不完整或存在明显冲突时，用户侧智能体应向用户发起澄清。澄清过程可以是单轮或多轮；具体交互方式由实现方决定，不属于本协议规范范围。 + +每次有效澄清后，智能体应对 ISR 草稿进行更新，使其逐步收敛为能够表达用户真实意图和边界条件的结构化结果。 + +### 用户确认 +在 ISR 草稿达到可理解、可确认的程度后，用户侧智能体宜以用户可理解的方式向用户展示结构化摘要，并获取用户确认。确认内容应足以反映本次委托的核心目标及主要边界。 + +### ISR 输出 +用户确认完成后，用户侧智能体应生成最终 ISR。若后续需要签发意图授权凭证，则 ADD-IAC-ISS 应以该 ISR 作为输入依据。 + +### 原始意图留存 +用户侧智能体宜在本地保留与本次意图链路相关的原始记录或其可验证引用，以支持后续争议处理、人工复核或审计。 +保留期限宜不短于对应委托任务完成后的合理争议处理周期。具体留存时长、留存介质和访问控制方式，可由实现方依据适用的数据保护法律法规和内部治理要求自行确定。 -委托授权域（Authorization & Delegation Domain，ADD）规定用户意图的表达、确认、结构化约束、授权凭证签发和生命周期管理，为 Agent 代表用户开展商业活动提供可表达、可约束、可验证、可追溯的授权基础。 +# ADD-IAC-ISS：意图授权凭证签发 +## 概述 +用户意图授权凭证签发（Intent Authorization Credential Issuance, ADD-IAC-ISS）规定如何将最终 ISR 转化为可被后续商业交互、支付执行和可信存证环节引用与校验的用户意图授权凭证（IAC）。 -本域是 ACT 2.1 的规范性委托授权域文本。本 Release 中的本文是 2.1 版本化正文；[ACT Protocol 委托授权域网页](https://www.act-protocol.com/documentation/delegation)是未版本化的信息性参考。 +本组件规定 IAC 的业务语义、待签名载荷边界、凭证封装要求以及签发处理流程。 -## 1. 范围与边界 +IAC 的输入对象是最终 ISR，但最终 ISR 中的内容并不一定都进入 IAC 的待签名载荷；只有构成授权边界、执行约束和后续核验依据的字段，才应纳入 IAC 的签名范围。 -ADD 覆盖： +## 参与方与前置条件 +本组件涉及以下参与方：委托人、受托智能体，以及负责提供签名、密钥调用或凭证封装支持的实现组件或服务。 +在具体实现中，签发过程可结合身份校验、受保护交互、密钥访问控制和控制证明等安全能力完成，但相关安全能力可由外部安全支撑协议提供。 -- 用户原始意图的获取、澄清、确认和结构化表达； -- 意图结构化结果（Intent Structured Result，ISR）的生成与引用； -- 意图授权凭证（Intent Authorization Credential，IAC）的构造、签发和封装； -- IAC 的生命周期状态、状态迁移和有效性检查。 +进入本组件前，应满足以下前置条件： -ADD 不规范前端样式、提示词工程、模型推理和多模态识别算法，也不规定身份基础设施、私钥托管或签名服务的内部实现。商品发现和交易确认属于 CID；支付与资金处理属于 PSD；存证事件结构和治理属于 TSD。 ++ 已形成最终 ISR，并已进入面向用户的确认环节。用户对最终 ISR 的确认动作，可直接作为 IAC 签发的授权触发。 ++ 已明确本次授权的受托智能体标识，以及与该授权对应的委托模式、有效期和主要约束边界。 ++ 实现方已具备生成 `delegation_id`、构造 IAC 待签名载荷、执行规范化处理并输出最终 IAC 的能力。 ++ IAC 的签名私钥应由受控密钥管理能力托管，并在可信执行环境或等效受控签名环境中完成签名；业务应用不得以明文方式直接暴露或持有用于 IAC 签发的签名密钥。当实现方采用 ASL 作为安全支撑协议时，签发方身份校验、密钥调用、签名生成、控制证明和相关状态查询，可分别引用 ASL-IDN、ASL-INF-KMS 和 ASL-INF-SEE 等能力完成。 -## 2. 组件与核心对象 +## 数据结构与字段表 +### IAC 待签名载荷 +IAC 待签名载荷是基于最终 ISR 筛选并重组得到的授权业务对象，用于表达“谁在什么边界内授权哪个智能体代表其行动”。IAC 待签名载荷宜定义如下： -| 组件 | 作用 | 主要输出 | -|---|---|---| -| `ADD-INT-ICS` | 获取、澄清、确认并结构化用户意图 | 用户原始意图、ISR、`intent_id` | -| `ADD-IAC-ISS` | 从最终 ISR 选择授权边界，完成规范化、签名和封装 | IAC、`delegation_id` | -| `ADD-IAC-LCM` | 管理 IAC 的有效、暂停、恢复、吊销和到期 | 可查询的授权状态 | +| **字段名** | **类型** | **存在性** | **约束说明** | **说明** | +| --- | --- | --- | --- | --- | +| `delegation_id` | string | 必备 | 本次 IAC 的唯一标识 | 本次 IAC 的唯一标识，也是本次授权生命周期的主标识 | +| `intent_id` | string | 可选 | 当上游 ISR 已生成该标识时可填写 | 所对应的用户意图标识；当上游 ISR 已生成该标识时，可用于建立 IAC 与上游 ISR 的对应关系 | +| `conversation_history` | object | 条件必备 | 当未生成`intent_id`，且实现方采用直接携带原始意图对象的方式时可填写；如存在，应符合 3.3.1 定义。 | 当未生成 `intent_id`时，可由 `conversation_history`直接作为本次授权的上游输入依据；该方式更适用于字节数较小的用户原始意图场景 | +| `delegator_identity` | string | 必备 | 授权签发方标识，即委托方的身份标识 | 授权签发方标识，通常对应委托人或代表委托人发起签发的主体标识 | +| `agent_id` | string | 必备 | 受托智能体的身份标识 | 被授权执行后续动作的智能体标识 | +| `delegation_mode` | string | 可选 | 枚举值：`SPECIFIED` / `BOUNDED` ，未填写时默认值为`SPECIFIED` | 委托模式 | +| `validity_start_time` | string | 必备 | ISO 8601 UTC | 授权生效时间 | +| `validity_end_time` | string | 必备 | ISO 8601 UTC，且应晚于 `validity_start_time` | 授权失效时间 | +| `max_total_amount` | number | 必备 | 应大于或等于 0，精度保留 2 位小数 | 授权总金额上限 | +| `currency` | string | 可选 | ISO 4217；未填写时默认值为 `CNY` | 金额币种 | +| `allowed_payment_methods` | array[string] | 可选 | 如进入签名范围，应保持与 ISR 中字段语义一致 | 允许的支付方式列表 | +| `user_confirmation_method` | string | 可选 | 由实现方定义枚举 | 用户确认或核身方式 | +| `user_confirmation_timestamp` | string | 条件必备 | 当存在 `user_confirmation_method`时应同步存在；ISO 8601 UTC | 用户完成确认或核身的时间 | +| `source_isr_digest` | string | 可选 | 用于表达上游 ISR 或其约定摘要范围的摘要值 | 当实现方需要更稳定的跨域核验锚点时可填写 | +| `ext` | object | 可选 | 如需将 ISR 的扩展约束纳入 IAC，应直接沿用 ISR 的 `ext`结构与字段语义 | 扩展字段命名空间 | -| 对象或标识 | 规范语义 | 下游引用 | -|---|---|---| -| 用户原始意图 | 用户以自然语言或其他方式表达的原始商业意图 | ADD 内部及必要的事后核查 | -| `intent_id` | 贯穿意图确认、ISR 和跨域流程的意图标识 | CID、PSD、TSD | -| ISR | 用户目标、约束和边界的结构化规则表达 | IAC 签发、CID 规则检验 | -| IAC | 对授权边界进行可验证封装后的凭证 | PSD 的 DEL/AUP、TSD | -| `delegation_id` | 一份 IAC 及其生命周期的唯一标识 | LCM、PSD、TSD | -| 授权状态 | IAC 当前是否可以被接受 | CID、PSD 及其他核验方 | +对 `ext` 的处理： -## 3. `ADD-INT-ICS`：意图获取及结构化表达 ++ IAC 如需承载 ISR 中的扩展约束，应直接沿用 ISR 中 `ext` 的命名空间与字段语义。 ++ 是否将某一扩展字段纳入 IAC 的签名范围，由实现方依据其是否影响后续授权核验来决定；不要求将 ISR 中的全部扩展字段一并签入 IAC。 -### 3.1 用户原始意图 +### 最终 IAC +最终 IAC 是在 IAC 待签名载荷基础上完成签名、封装和必要元数据补充后形成的可验证授权凭证对象。本章对最终 IAC 仅定义其组成部分及其语义边界，暂不规定具体字段级结构，以兼容不同凭证封装格式下的实现。 -`conversation_history` 用于承载用户原始内容，或其可校验摘要和上下文引用： +最终 IAC 可包括以下组成部分： -| 字段 | 存在性 | 规范语义 | -|---|---|---| -| `user_intent_raw` | 条件必备 | 与 `user_intent_raw_digest` 至少一项存在 | -| `user_intent_raw_digest` | 条件必备 | 原始意图摘要；与 `user_intent_raw` 至少一项存在 | -| `input_mode` | 可选 | `TEXT`、`VOICE`、`IMAGE`、`INTERACTIVE_CARD`、`OTHER`，可组合 | -| `context_ref` | 条件必备 | 有摘要时必备；所指内容应能得到相同摘要 | ++ `protected_header` 或等价封装元数据，用于表达算法标识、封装类型、密钥寻址信息和必要的配置标识。 ++ `credential_metadata`，用于表达签发方、受托方、签发时间、生效时间、失效时间和凭证标识等基础元数据。 ++ `credential_subject` 或等价业务载荷区，用于承载 4.3.1 定义的 IAC 待签名载荷。 ++ `proof`，用于表达对约定签名范围所生成的签名证明。 ++ `status_reference`，用于支持后续状态查询、生命周期管理或相关校验环节。 ++ `control_proof_ref`，为可选组成部分；在高风险签发场景中，可用于引用与本次签名调用相关的控制证明或其摘要。 -扩展输入模式不得改变既有字段的基础语义。完整原文不便传递时，可以只传摘要和引用，但实现方仍应保护原始记录的可验证性、访问控制和留存周期。 +## 处理要求 +### ISR 完整性检查与确认触发 +受托智能体应接收最终 ISR，并检查其是否已达到可供用户确认和签发的状态，是否具备明确的委托模式、智能体标识、有效期和主要授权边界。如最终 ISR 缺少构成 IAC 所必需的关键授权信息，则不应进入正式签发步骤。 -### 3.2 ISR 数据字典 +用户对最终 ISR 的确认动作，可直接作为 IAC 签发的触发动作。不宜因协议流程设计而强制要求用户就同一授权事项进行重复确认。 -ACT 2.1 将 ISR 定义为数据字典，而不是冻结的 wire Schema：它规定名称、类型和语义，但不统一规定本表全部字段的存在性。场景规则、IAC 签发规则和下游组件负责进一步约束。 +### IAC 待签名载荷构造 +受托智能体应基于最终 ISR 构造 IAC 待签名载荷，并明确哪些字段进入本次 IAC 的签名范围。此时应遵循“基于 ISR 筛选并重组”的原则，而不应将最终 ISR 原样整体封装为 IAC。 -| 字段 | 规范语义 | -|---|---| -| `conversation_history` | 用户原始意图对象 | -| `intent_id` | 当前意图链路内唯一标识 | -| `delegation_mode` | `SPECIFIED` 或 `BOUNDED` | -| `validity_start_time` / `validity_end_time` | ISO 8601 UTC 有效时间窗，结束晚于开始 | -| `max_total_amount` / `currency` | 授权总金额上限及 ISO 4217 币种 | -| `allowed_payment_methods` | 允许的支付方式 | -| `agent_id` | 执行 Agent 标识 | -| `user_confirmation_method` / `user_confirmation_timestamp` | 用户确认方式与时间 | -| `ext` | 标准和私有扩展命名空间 | +### 规范化处理 +在进入签名前，实现方应对约定签名范围内的 IAC 待签名载荷执行确定性的规范化处理，以确保跨域验签和摘要比对的一致性。同一部署中的签发方与验证方应保持字段命名、规范化规则和签名输入边界一致，否则将导致验签或摘要校验失败。 -`SPECIFIED` 用于目标、商户或交易边界已明确的定向委托；`BOUNDED` 用于用户只确定任务目标和行为边界、具体选择由 Agent 在边界内决定的委托。 +如采用 JSON 作为载荷表达方式，宜采用 RFC 8785 所定义的 JSON Canonicalization Scheme（JCS）执行规范化处理。 -### 3.3 标准扩展 +### 签名生成 +在完成规范化后，实现方应对约定签名输入执行签名，生成 IAC 的 `proof`。 -| 扩展块 | 字段 | -|---|---| -| `ext.commerce` | `max_single_amount`、`min_single_amount`、`allowed_categories`、`forbidden_categories`、`allowed_merchants`、`forbidden_merchants` | -| `ext.agent_behavior` | `price_deviation_tolerance`、`price_deviation_action`、`on_payment_failure`、`max_retry_count` | -| `ext.fulfillment` | `delivery_time_requirement`、`delivery_address` | +### 凭证封装 +取得签名结果后，实现方应将 IAC 待签名载荷、凭证元数据、签名证明及必要引用信息组装为最终 IAC。封装后的 IAC 应能够稳定表达签发方、受托智能体、授权边界、有效期和签名证明，并支持后续独立校验。 -`price_deviation_action` 使用 `PAUSE_AND_NOTIFY` 或 `AUTO_CANCEL`；`on_payment_failure` 使用 `AUTO_RETRY` 或 `CANCEL`。`ext.vendor_private` 可承载私有扩展，但不得改变核心字段或标准扩展的语义；不认识且不影响核心约束的私有字段可以忽略。 +## 封装与签名要求 +本组件对 IAC 采用封装无关规则；具体实现可映射到可验证凭证类封装、JWS 类封装或其他等价可验证表达方式，但所选封装应能够稳定承载签发方、受托方、时效、IAC 待签名载荷和签名证明。本版本将 W3C VC-JWT 作为推荐实现方式之一，但并非唯一封装格式。 -### 3.4 处理要求 +签名范围应由实现方明确声明，并在同一部署内保持稳定一致。默认情况下，签名输入应是“约定签名范围内的 IAC 待签名载荷或其等价规范化表示”，而不是完整 ISR 原文。实现方在进行 JSON 规范化时，应保留字段原始命名，不应因序列化框架自动转换字段风格而改变签名输入语义。 -1. 用户侧 Agent 获取原始意图并形成 `conversation_history`。 -2. Agent 生成 ISR 草稿；遇到歧义、关键约束缺失或冲突时进行澄清并更新草稿。 -3. Agent 以用户可理解的方式展示核心目标和边界，取得确认后生成最终 ISR。 -4. 后续需要 IAC 时，`ADD-IAC-ISS` 以最终 ISR 为输入依据。 -5. 原始意图或其可验证引用宜在合理争议周期内受控留存；具体时长和介质由实现方依据法律与治理要求决定。 +当实现方采用 ASL 作为安全支撑协议时，可按以下方式进行规范性引用： -## 4. `ADD-IAC-ISS`：意图授权凭证签发 ++ IAC 的签名生成可引用 ASL-INF-KMS 的 `Sign` 能力完成，相关签名密钥用途应与授权凭证签名用途相匹配，不应与其他用途密钥混用。 ++ 高风险授权场景下的用户确认、本地敏感交互和签名调用，宜结合 ASL-INF-SEE 的受保护交互能力与 ASL-INF-KMS 的控制证明能力完成。 ++ 当需要记录签名调用满足访问控制策略的证据时，宜引用 ASL-INF-KMS 的控制证明能力，并在最终 IAC 中携带 `control_proof_ref` 或等价引用。 -### 4.1 签发边界 +# ADD-IAC-LCM：意图授权凭证生命周期管理 +## 概述 +意图授权凭证生命周期管理（Intent Authorization Credential Life Cycle Management, ADD-IAC-LCM）定义 IAC 的合法状态、状态迁移规则和处理要求。 -IAC 不是最终 ISR 的无差别复制。只有构成授权边界、执行约束和后续核验依据的内容才进入待签名载荷。用户对最终 ISR 的一次确认可以直接触发签发，不宜因流程设计要求用户对同一事项重复确认。 +本组件适用于已签发 IAC 的状态管理、授权校验和相关存证处理。 -签发前应已经明确受托 Agent、委托模式、有效期和主要约束；签名私钥必须由受控密钥管理能力托管，并在可信执行环境或等效受控环境中使用，业务应用不得明文持有签发私钥。 +## 状态机定义 +IAC 在其生命周期内的合法状态及流转规则如下。 -### 4.2 IAC 待签名载荷 +| **状态值** | **语义** | **触发条件** | **可恢复性** | +| --- | --- | --- | --- | +| `Active` | 有效，可用于商业交互与支付。 | IAC 已完成签发，且处于有效期内，未被暂停或吊销 | — | +| `Suspended` | 暂停，临时不可使用 | 委托人或风控系统发起临时挂起，且凭证尚未终止 | 可恢复 | +| `Expired` | 已过期，不可使用 | `validity_end_time` 到达，系统自动触发 | 不可恢复 | +| `Revoked` | 已吊销，永久不可使用 | 委托人或受托智能体主动触发永久吊销 | 不可恢复 | -| 字段 | 存在性 | 规范语义 | -|---|---|---| -| `delegation_id` | 必备 | IAC 与授权生命周期的唯一标识 | -| `intent_id` | 可选 | 与上游 ISR 建立关联 | -| `conversation_history` | 条件必备 | 无 `intent_id` 且直接携原始意图对象时使用 | -| `delegator_identity` | 必备 | 委托人或代表其签发的主体标识 | -| `agent_id` | 必备 | 被授权执行动作的 Agent 标识 | -| `delegation_mode` | 可选 | `SPECIFIED` / `BOUNDED`；缺省为 `SPECIFIED` | -| `validity_start_time` / `validity_end_time` | 必备 | ISO 8601 UTC 授权时间窗 | -| `max_total_amount` | 必备 | 授权总金额上限 | -| `currency` | 可选 | ISO 4217；缺省为 `CNY` | -| `allowed_payment_methods` | 可选 | 进入签名范围时沿用 ISR 语义 | -| `user_confirmation_method` / `user_confirmation_timestamp` | 可选 / 条件必备 | 用户确认方式与时间 | -| `source_isr_digest` | 可选 | 上游 ISR 或约定摘要范围的摘要值 | -| `ext` | 可选 | 影响授权核验的 ISR 扩展约束 | +## 状态迁移规则 +IAC 的状态迁移规则如下。 -是否把某一 `ext` 字段纳入签名范围，取决于它是否影响后续授权核验；不要求将 ISR 的所有扩展字段全部签入 IAC。 +| **当前状态** | **目标状态** | **触发条件** | **是否可逆** | +| --- | --- | --- | --- | +| `Active` | `Suspended` | 委托人或风控系统发起临时挂起 | 是 | +| `Suspended` | `Active` | 委托人或风控系统解除挂起 | 是 | +| `Active` | `Revoked` | 委托人或受托智能体发起吊销 | 否 | +| `Suspended` | `Revoked` | 委托人或受托智能体发起吊销 | 否 | +| `Active` | `Expired` | `validity_end_time` 到达 | 否 | +| `Suspended` | `Expired` | `validity_end_time`到达 | 否 | -### 4.3 最终 IAC 与签名 +其中`Revoked` 和 `Expired` 为终态。进入终态后的 IAC 不得恢复为 Active 或 Suspended。Suspended 为临时限制状态，仅可依据明确的恢复条件解除挂起并返回 Active。 -最终 IAC 可由以下部分组成：`protected_header`、`credential_metadata`、`credential_subject`、`proof`、`status_reference`，以及高风险场景可选的 `control_proof_ref`。来源只定义这些部分的语义边界，暂不冻结字段级最终封装。 +## 处理要求 +### 生效状态 +IAC 完成签发后，如当前时间已进入其有效时间窗口，且未被暂停或吊销，则其状态应为 `Active`。处于 `Active` 状态的 IAC，可被后续商业交互、支付执行和授权核验环节正常引用。 -签名前必须对约定签名范围执行确定性规范化；JSON 载荷宜采用 RFC 8785 JCS。同一部署的签发方和验证方必须保持字段名称、规范化规则和签名输入边界一致。实现可以映射到可验证凭证类封装、JWS 类封装或等价形式；W3C VC-JWT 是推荐方式之一，不是唯一格式。 +### 临时挂起 +委托人或风控系统可在 IAC 有效期内发起临时挂起。挂起后，IAC 状态应变更为 `Suspended`。处于 `Suspended` 状态的 IAC 不得继续用于商业交互、支付执行或授权校验。 +智能体宜异步上报 `act:delegation:delegation-suspended` 存证事件。 -## 5. `ADD-IAC-LCM`：生命周期管理 +### 解除挂起 +处于 `Suspended` 状态的 IAC，可由委托人或风控系统发起解除挂起操作。解除后，IAC 状态应恢复为 `Active`。 +智能体宜异步上报 `act:delegation:delegation-resumed` 存证事件。 -### 5.1 状态和转移 +### 吊销 +委托人或受托智能体可在 IAC 有效期内发起吊销。吊销后，IAC 状态应变更为 `Revoked`。处于 `Revoked` 状态的 IAC 不得继续用于商业交互、支付执行或授权校验。 +智能体宜异步上报 `act:delegation:delegation-revoked` 存证事件。 -| 状态 | 语义 | 可恢复性 | -|---|---|---| -| `Active` | 在有效时间窗内且未暂停/吊销，可供后续使用 | — | -| `Suspended` | 临时不可使用 | 可恢复到 `Active` | -| `Revoked` | 永久吊销 | 终态 | -| `Expired` | 到达 `validity_end_time` | 终态 | +### 到期自动处理 +当 `validity_end_time` 到达时，IAC 状态应自动变更为 `Expired`。处于 `Expired` 状态的 IAC 不得继续用于商业交互、支付执行或授权校验。 +智能体宜异步上报 `act:delegation:delegation-expired` 存证事件。 -允许的迁移是：`Active → Suspended`、`Suspended → Active`、`Active/Suspended → Revoked`、`Active/Suspended → Expired`。`Revoked` 和 `Expired` 不得恢复。 +## 授权状态校验 +后续环节在引用 IAC 时，应至少校验以下内容： -### 5.2 状态处理和校验 ++ IAC 是否处于有效时间窗口内。 ++ IAC 当前状态是否为 `Active`。 ++ IAC 是否存在已知的暂停、吊销或到期结果。 -- `Suspended`、`Revoked` 或 `Expired` IAC 不得继续用于商业交互、支付执行或授权校验。 -- 暂停、恢复、吊销和到期宜异步上报 `act:delegation:delegation-suspended`、`delegation-resumed`、`delegation-revoked`、`delegation-expired`；事件结构由 TSD 定义。 -- 引用 IAC 的处理方至少检查有效时间窗、当前状态为 `Active`，以及是否存在已知暂停、吊销或到期结果。 -- 最终判断前应通过 `status_reference` 获取当前状态。状态服务暂时不可达时，可使用本地最近一次成功结果和 `validity_end_time` 做临时风险控制，但这不是永久忽略状态检查的依据。 - -## 6. 当前机器契约边界 - -ACT 2.1 明确了数据字典、存在性和处理语义，但没有发布 ISR/IAC JSON Schema、封装版本、算法套件、状态查询协议、事件 Schema 或标准错误对象。本仓库不从示例或描述推造这些机器契约。 - -## 7. 来源 - -- ADD 相关网站参考：[委托授权域](https://www.act-protocol.com/documentation/delegation)；未标明 ACT 2.1 的网页内容不是本 Release 的规范来源 -- 跨域场景参考：[典型场景与业务流程](https://www.act-protocol.com/documentation/scenarios) -- CID：[商业交互域](https://www.act-protocol.com/documentation/commerce) -- PSD：[支付服务域](https://www.act-protocol.com/documentation/payment) -- TSD：[信任服务域](https://www.act-protocol.com/documentation/trust) +处理方在作出最终授权有效性判断前，应通过 `status_reference` 获取当前状态。当状态服务暂时不可达时，处理方可基于本地最近一次成功查询结果和 `validity_end_time` 进行临时风险控制。 diff --git a/docs/specification/commerce-interaction.en.md b/docs/specification/commerce-interaction.en.md index ee22d87..8884cb8 100644 --- a/docs/specification/commerce-interaction.en.md +++ b/docs/specification/commerce-interaction.en.md @@ -2,174 +2,353 @@ [中文](commerce-interaction.md) | English -> **Chinese source publication: ACT 2.1 Specification / Final / Normative** -> **The protocol content is final. Conformance with this specification requires independent conformance evidence.** -> **Version baseline: 2026-08-11 (UTC+8).** -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +# Scope +## Domain Positioning +Commerce Interaction Domain (Commerce Interaction Domain, CID) provides for a uniform, citation and commerce interaction synonym between Agent and Merchant, Merchant-side Agent or other Agent for the pre-payment identification of goods or services, Intent Context transmission, alignment of capacity to pay and transaction recognition. -The Commerce Interaction Domain (CID) specifies the commercial-interaction semantics that precede payment execution: how goods or services become machine-readable candidates, how intent context is transferred, how the parties align payment capabilities, and how a transaction is finally confirmed before entering the Payment Services Domain. +## Domain Responsibilities +This domain covers the following: -This document is the official informative English translation of the normative ACT 2.1 Commerce Interaction Domain text in this release. The [ACT Protocol Commerce Interaction page](https://www.act-protocol.com/documentation/commerce) is an unversioned informative reference. ++ (b) Minimum information requirements for the discovery of goods and services; ++ Organization, transmission and return of candidate results Intent Context; ++ Payment Capability Advertisement, capacity recognition and capacity consultation; ++ Cart Confirmation, pre-checking of rules and confirmation of transactions; ++ Pre-payment business consensus to form key objects, state semantics and cross-domain reference relationships. -## 1. Scope and boundaries +The following are not regulated in this domain: -CID covers: ++ Agent Internal decision algorithms, ranking strategies, preference extrapolations and model reasoning processes; ++ Merchant In-house operations processing, stock deductions, order management and performance systems achieved; ++ Generic multi-operative Agent collaboration protocols, tasking and service discovery protocols; -- minimum information requirements for product and service discovery results; -- organization and transfer of intent context and return of candidate results; -- declaration, confirmation, and negotiation of payment capabilities; -- cart confirmation, preflight rule validation, and transaction-confirmation results; -- objects, state semantics, and cross-domain references needed for commercial consensus before payment. +# The list of components and relationships in this field +## Component Overview +Commerce Interaction Domain consists of four protocol components that jointly complete the full chain from the discovery of goods or services, Intent Context transfer and pre-payment capacity, to the completion of the transaction and the beginning of the payment phase. -CID does not specify: +The functional positioning of the components is as follows. -- an Agent's internal reasoning, ranking, preference inference, or decision algorithms; -- a merchant's internal operations, inventory deduction, order management, or fulfillment implementation; -- general multi-Agent collaboration, task orchestration, or service-discovery protocols; -- payment execution, credential validation, or funds processing, which belong to the [Payment Services Domain](payment-services.en.md); -- common structures and governance for trustworthy events, which belong to the Trust Services Domain. ++ **CID-MER-CAT: Merchant Catalog interface.** Regulates the minimum information requirements when opening the catalogue of goods or services in structured form to Merchant to support machine-readable goods or services. ++ **CID-INT-XFR: Intent Context Passage.** Responsible for regulating the Buyer Agent transmission of Intent Context to Merchant or to the platform in relation to the current mandate, and for receiving requests/responses to the outcome of the candidate goods or services. ++ **CID-PCA-NEG: Payment Capability Negotiation.** It is responsible for regulating the process of capacity statements and consultations between buyers and sellers before payments can be made, using payment method, Payment Service Provider, interface endpoints and associated load modes. ++ **CID-CART-CFM: Cart Confirmation.** Be responsible for regulating the process of final confirmation and pre-checking of rules on the subject matter of the transaction, the amount, conditions of performance and related constraints before entering the payment process Buyer Agent. -## 2. Components and core objects +## Core Object & Identification +Commerce Interaction Domain uses a standard core set of objects and identifiers to describe key information at the pre-payment stage. The core objects of the domain and their role can be summarized as follows. -| Component | Purpose | Primary output | -|---|---|---| -| `CID-MER-CAT` | Product and service catalog interface; specifies minimum discovery-result information without defining one catalog protocol | Candidate product or service results | -| `CID-INT-XFR` | Transfer the current task's intent context to a merchant or platform and receive candidates | Request-correlated candidate results or errors | -| `CID-PCA-NEG` | Align payment methods, providers, endpoints, and payload modes before payment | Payment-capability negotiation result | -| `CID-CART-CFM` | Finally confirm the transaction subject, amount, fulfillment terms, and authorization constraints | Transaction-confirmation result that PSD can reference | +|** Object or Identification**|** Meaning**|** Mainly Generate Location**|** Main Use Location**| +| --- | --- | --- | --- | +|Intent Context|Buyer Agent Structured Intent Information around Current Tasks, Carrying Needs, Constraints and Necessary Backgrounds, and Upstream Inputs as Commodity Screening, Matching and Transaction Recognition|ADD-INT-ICS, also constructed locally by Buyer Agent based on upstream intent objects, if necessary|Candidate matching process CID-INT-XFR, CID-CART-CFM, and Merchant or platform| +|Results of candidate goods or services|Merchant, platform or selleragent returned the structured candidate results for the pre-screening, comparison and follow-up rule test at Buyer Agent|CID-MER-CAT、CID-INT-XFR|CID-CART-CFM and Buyer Agent local decision-making processes| +|Transaction confirmation result|The final confirmation of the order as a result of phase Cart Confirmation typically includes the subject matter of the transaction, the amount, Merchant identification, the order transaction number and related confirmation time information|CID-CART-CFM|Payment Services Domain, and trusted attestation with ex post facto dispute resolution support| +|Results Payment Capability Negotiation|Convergence between buyers and sellers on the use of payment method, Payment Service Provider, interface endpoints and methodological models|CID-PCA-NEG|payment request Construction and implementation of subsequent Payment Services Domain| -The domain uses four core object types: +## Dependence and Cross-domain Reference +Both CID-MER-CAT and CID-INT-XFR may be used as upstream sources for candidate products or service outcomes to provide subsequent Cart Confirmation input. -| Object | Produced by | Primarily used by | -|---|---|---| -| Intent context | `ADD-INT-ICS`, or locally constructed by the Buyer Agent from upstream intent | `CID-INT-XFR`, `CID-CART-CFM`, and candidate matching | -| Candidate product or service result | `CID-MER-CAT`, `CID-INT-XFR` | Local buyer decision and `CID-CART-CFM` | -| Payment-capability negotiation result | `CID-PCA-NEG` | Payment-request construction and path selection | -| Transaction-confirmation result | `CID-CART-CFM` | PSD and subsequent evidence and dispute handling | +The role of CID-PCA-NEG occurs primarily in the pre-payment phase and is used to determine, if necessary, the payment method, Payment Service Provider and interface endpoints used for the transaction, thus providing the basis for the subsequent payment request construction. -ADD provides ISR and related constraint context to CID. PSD consumes the transaction-confirmation result, order transaction number, and payment-capability negotiation result. TSD maintains event types and evidence-governance rules; CID does not redefine them. +CID-CART-CFM is the key component in the field for pre-discovering, screening, negotiating and forming the final confirmation of the order level, the output of which will have a direct impact on whether the subsequent Payment Services Domain can initiate payment execution. -## 3. `CID-MER-CAT`: product and service catalog interface +Authorization & Delegation Domain primarily provides this domain with ISR and the relevant constraint context; Payment Services Domain primarily references the transaction confirmation result, order transaction number, and Payment Capability Negotiation result produced by this domain; the trusted attestation subsection of Trust Services Domain centrally maintains the relevant event types and attestation governance rules, which are not redefined here. Agent credit association statements defined in the credit association subsection may be used as an auxiliary input when screening products or services in this domain. -### 3.1 Minimum information requirements +# CID-MER-CAT: Merchant Catalog Interface +## Overview +Merchant Catalog Interface (Catalog Interface, CID-MER-CAT) sets the minimum information requirements for Merchant opening a structured catalogue of goods or services to Agent to support machine-readable discovery of goods or services. The candidate goods or services output of this component may serve as upstream input for Buyer Agent subsequent comparative decision-making and Cart Confirmation. -Each product or service detail that a Buyer Agent can consume MUST contain: +The current version of this component does not define a uniform catalogue protocol for the time being, but provides for the minimum information requirements to be met by SHALL before commerce interaction enters the follow-up. -- a product or service identifier uniquely resolvable globally or within the merchant domain; -- a product or service name; -- a category or classification usable for matching intent constraints; -- an explicit listed price and currency unit. +This component does not regulate the sorting logic of cataloguing, recommended algorithms, Merchant internal commodity modelling, and internal processing Merchant such as stock deductions, price calculations and order performance. -The result SHOULD additionally contain: +## Participants and prefix +This component involves the following Participants: Merchant or platform for providing information on goods or services, and Buyer Agent for initiating cataloguing visits and consuming returns. -- inventory, saleability, or service-availability state; -- price-expiration time or quote-update time; -- delivery, fulfillment, or service-completion time; -- merchant identifier, merchant-reference URL, or detail-reference URL. +Before entering this component, SHALL satisfies the following preconditions. -A result that does not satisfy the minimum information requirements SHOULD NOT directly enter `CID-CART-CFM`. If the result can only be displayed, the implementation SHOULD first obtain the information needed for preflight rule validation. ++ Merchant or the platform already has the capacity to provide external information on structured goods or services. ++ Buyer Agent The basic commercial context relevant to the current mission has been established and allows for local screening, comparison or subsequent confirmation of return results. ++ When the subsequent link needs to be tested under user intent against the binding enforcement rules, Buyer Agent SHALL be able to link the directory back to the relevant Intent Context provided by Authorization & Delegation Domain. -### 3.2 Content intentionally not standardized +## Minimum return information requirement +Merchant returned catalogue data for goods or services SHALL meet the minimum information availability requirement to ensure that follow-up commerce interaction and confirmation before payment can proceed normally. -ACT 2.1 does not specify a common catalog path, HTTP method, authentication, pagination, retrieval ranking, recommendation algorithm, or merchant-internal product model. Implementations MAY reuse an industry protocol, merchant API, or platform catalog, provided that the result satisfies the minimum information requirements above. +For each item of goods or services available for Buyer Agent consumption, the return result SHALL contain the following information. -## 4. `CID-INT-XFR`: intent-context transfer ++ Goods or services identification, SHALL, is the only globally or in the Merchant domain that can be deciphered. ++ Trade name or service name, SHALL may support Buyer Agent and subsequent processing to identify the subject of the transaction. ++ Commodity group or service category, SHALL support subsequent alignment with user intent binding. ++ Clear pricing and currency units, SHALL support value comparisons, rule pre-tests and pre-payment confirmations. -### 4.1 Intent context +In addition to the minimum information required above, the return result on the side of Merchant SHOULD further contains the following information. -Intent context is organized around the current task and commonly includes: ++ Current stock, marketable status or service availability. ++ The price is valid at the deadline or the price update. ++ Anticipated delivery times, time limits for performance or service delivery. ++ Merchant Identification, Merchant Reference Address or Trade Details Reference Address. -- purchase or service requirements explicitly expressed by the user; -- supplemental requirements inferred by the Agent from confirmed context; -- constraints such as amount, category, merchant, and fulfillment timing; -- background strictly necessary for candidate matching; -- preference information that the implementation permits and that is applicable. +Buyer Agent SHOULD NOT is used directly for Cart Confirmation or for payment of pre-connection when the results of the directory cannot be satisfied. When the return result is only shown and is not sufficient to support the pre-checking of the rules, the achiever SHOULD supplements the necessary fields before entering CID-CART-CFM. -Explicit requirements and constraints SHOULD be primary. Implicit requirements or preferences MUST NOT conflict with user-confirmed constraints or ISR/IAC authorization boundaries. The implementation is responsible for informed consent and data protection. +> The current version of ACT does not provide for uniform access paths, request methods, authentication mechanisms and page breaks for the directory interface. +> -### 4.2 Requests, responses, and updates +## Statement of compatibility +This may be achieved in conjunction with existing industry protocols, Merchant open interfaces or existing catalogue services of the platform, as long as its return results meet the minimum information requirements specified in this component. -A request SHOULD include a unique request identifier, intent context, necessary cross-domain correlation identifiers, constraints, response-format requirements, and source-authentication information. The response MUST be correlatable to the original request and MUST at least return candidate details that can be filtered and confirmed. If the request cannot be processed, the response MUST return machine-recognizable error semantics. +# CID-INT-XFR: Intent Context Passage +## Overview +Intent ContextTransfer, CID-INT-XFR provides for Buyer Agent transmission to Merchant or to the platform of Merchant and receives a request/response process for the results of the candidate goods or services. Intent Context used for this component may be quoted as ISR and associated binding syntax, and may be entered upstream as a follow-up candidate selection, pre-test and Cart Confirmation. -Each multi-turn update MUST receive a new request identifier and correlate to the preceding request. It SHOULD carry only changes from the current turn. Error semantics SHOULD cover malformed input, no matches, restricted access, constraint conflicts, and excessive request frequency. The Buyer Agent MAY use these errors to retry, switch merchants, adjust the request, or notify the user. +This component deals with the matching of intent transmission with candidate at the pre-payment stage and does not regulate internal intent understanding, preference extrapolation and decision algorithms Buyer Agent. -The Buyer Agent MAY query multiple merchants or platforms concurrently. Candidate aggregation, comparison, and final decision remain local implementation concerns and are not CID protocol rules. +## Participants and prefix +This component involves the following Participants: Buyer Agent for initiating the intended request, and Merchant for receiving the request and returning the candidate results, the platform or its proxy interface. -## 5. `CID-PCA-NEG`: payment-capability negotiation +Before entering this component, SHALL satisfies the following preconditions. -### 5.1 Capability declaration ++ Buyer Agent The basic commercial context relevant to the current mission has been established and can be constructed to transmit Intent Context. ++ Merchant or the platform already has the capacity to receive intended requests and return to structured candidate results. ++ When the subsequent link needs to be tested against User objectives and binding enforcement rules, Buyer Agent SHALL be able to connect Intent Context to the relevant binding synonyms provided by Authorization & Delegation Domain. -A seller, merchant, or its Agent MAY declare payment-negotiation capabilities under an Agent Card `capabilities` node, or publish `act-payment-capability.json` at an agreed location. The declaration MUST express: +## Composition Intent Context +Buyer Agent Passes Intent Context SHALL organize around current tasks and can support Merchant or platform matching. Intent Context typically include the following. -- negotiation mode; -- supported payment methods; -- the payment service provider for each method; -- payment-interface endpoints; -- payload mode or structure description. ++ Visible intent demand, i.e. User clearly expressed purchase target or service demand. ++ Implicit intent needs, i.e. Buyer Agent supplementary needs based on the context of the current mandate, User confirmed information or continuous interactive content. ++ Limitations, i.e., amount, category, Merchant, time for performance, etc., relevant to the task. ++ The necessary background information, i.e. the additional context required to complete the candidate matching. ++ Preferable information that may be transmitted with the permission of the realizing party and subject to the applicable conditions. -An Agent Card MAY use `capability_url` to reference a one-way capability declaration, or `negotiation_endpoint` to reference a two-way negotiation interface. The source documentation provides structural examples; it does not provide a JSON Schema, version-negotiation mechanism, or signature format that can independently establish formal compatibility. +Visible intent needs and constraints SHOULD be the main components of Intent Context. Implicit intent needs and preferences can be transmitted as optional messages that conflict with the authorized boundary as expressed in ISR/ IAC by User explicitly identified binding conditions or Authorization & Delegation Domain. -### 5.2 One-way declaration +When transmitting information about hidden intent needs or preferences, the achiever SHALL processes the relevant informed consent and data protection requirements on its own. -The Buyer Agent reads the seller's published capabilities and filters `supported_methods` for methods that satisfy the transaction conditions and upstream authorization constraints. The selected result MUST at least identify: +## Requests and responses +Buyer Agent When initiating a request for intent, SHALL constructs can be analysed by Merchant or the Platform. The request contains the following key elements. -- `method_id`: payment-method identifier; -- `psp_id`: payment service provider identifier; -- `endpoint`: endpoint for the subsequent payment request; -- `method_schema_url`: description of the method payload structure. ++ Request for marking to be used only to mark the current request and to support a response link. ++ Intent Context related to current mandate. ++ Link identifiers used when cross-domain linkages are required. ++ Required binding conditions and responsiveness to formal requirements. ++ Request for authentication information from sources. -If no method matches, the Buyer Agent MUST NOT proceed to payment. +At least SHALL contain details of the goods or services that can be selected for subsequent screening and confirmation. When Merchant or the platform is unable to return the valid candidate, SHALL return the wrong response and gives the wrong synonym that can be identified by Buyer Agent. -### 5.3 Two-way negotiation +## Dynamic Update and Wrong Semantics +Buyer Agent SHALL Supports the dynamic update of Intent Context in multiple rounds of interaction. Each dynamic update generates a new request identifier and links it to the previous request. The dynamic update request SHOULD carries only the intended content of this change. -The Buyer Agent sends a request to `negotiation_endpoint`. The request semantics include the Buyer Agent identifier, buyer-supported methods, currency, and estimated amount. The seller returns the method, PSP, endpoint, and method Schema that match the current transaction conditions. +When Merchant or the platform is unable to process the request normally, the wrong synonym SHOULD cover the categories of error in format, lack of matching results, restricted access, restricted conflicts and excessive frequency of requests. Buyer Agent Depending on the type of error, retrying, switching Merchant, adjustment request or notification User. -If the parties share no method, the Buyer Agent MUST NOT proceed to payment and MUST switch methods, switch counterparties, or terminate the transaction according to business policy. When multiple results exist, final ranking and selection are handled locally by the Buyer Agent. +## Multiple Merchant route +In the actual business network, Buyer Agent can be accompanied by a request for intent to multiple Merchant or platforms and a summary of the results of each party’s return. The comparison of the results with the final decision is Buyer Agent local processing, which is not part of this component instruction Scope. -### 5.4 Security requirements +> Note: Where key business nodes need to be recorded, this will be achieved before the `act:commerce:decision-logged` event marker is used for follow-up certificate processing after the decision is completed. +> -Before using a capability declaration, the Buyer Agent MUST verify that it came from the capability address declared by the merchant. When parsing the result, it MUST check consistency among critical fields such as `psp_id`, `endpoint`, and `method_schema_url` to prevent forgery, tampering, or substitution. If the source cannot be verified or a critical-field check fails, capability matching and payment MUST NOT continue. +# CID-PCA-NEG: Payment Capability Negotiation +## Overview +Payment Capability Negotiation (Payment Capitalisation, CID-PCA-NEG) provides for a process of capacity statement and consultation between buyers and sellers on the use of payment method, Payment Service Provider, interface endpoints and related load modalities before entering payment execution. -## 6. `CID-CART-CFM`: cart confirmation +This component applies mainly to multiple agentic commerce interactive scenarios in which the seller Agent participates, as well as to other scenarios where capacity to pay needs to be aligned before payment is made. The output of this component Payment Capability Negotiation can be used as a follow-up Payment Services Domain construct payment request and input to choose the payment path. -### 6.1 Preflight rule validation +This component does not define common service discovery, information exchange, tasking and collaborative interaction protocols, but only regulates the semantics of Payment Capability Advertisement and Payment Capability Negotiation required to pay for the pre-connection. -Before payment, the Buyer Agent MUST validate the proposed transaction against: +## Participants and prefix +This component involves the following: Participants: Buyer Agent initiating Payment Capability Negotiation, and Merchant external declaration of capacity to pay and return to the results of the consultations, Agent seller or its proxy interface. -- per-transaction and cumulative amount boundaries; -- allowed and forbidden categories; -- allowed and forbidden merchants; -- delivery, completion, or service-fulfillment timing; -- whether the final price is within the permitted tolerance; -- ISR/IAC authorization boundaries in delegated-payment scenarios. +Before entering this component, SHALL satisfies the following preconditions. -If any validation fails, the transaction MUST NOT proceed directly to payment. If an out-of-bounds policy already exists, that policy MUST be applied. `PAUSE_AND_NOTIFY` waits for the user to reconfirm or adjust constraints; `AUTO_CANCEL` records the reason and terminates. If there is no explicit policy, the implementation SHOULD pause and notify by default. ++ The buyer and the seller have developed a basic commercial context in which to enter the pre-payment phase. ++ Buyer Agent already identifies the amount of the transaction, the currency, the subject of the transaction and other necessary transaction parameters. ++ The seller ' s side has the capability to publish Payment Capability Advertisement or respond to Payment Capability Negotiation requests. ++ When the transaction is subject to user intent or authorized boundaries, Buyer Agent SHALL be able to determine the availability of the candidate payment method according to the relevant binding syntax. -### 6.2 Submission, locking, and result +## Payment Capability Advertisement +### Declaration Mode +The seller's side can make its Payment Capability Advertisement public through a standardized path. Under the seller's Agent scene, Payment Capability Advertisement can be published through `capabilities` node in its Agent Card, with a statement of the mode of consultation supported by the seller and the corresponding interface address. -After validation passes, the confirmation request SHOULD include product or service details, final price, currency, fulfillment requirements, and necessary correlation context. After accepting, the counterparty MUST lock the order-level price, inventory, or service capacity and return a stably referenceable order transaction number. If locking fails, the counterparty MUST return an explicit failure and MUST NOT treat the transaction as confirmed. +Payment Capability Advertisement SHALL be able to convey the following message. -The transaction-confirmation result SHOULD at least contain: ++ Modalities for consultations supported by this party. ++ The list of payment methods supported by this side. ++ Each corresponding Payment Service Provider identifier. ++ Each corresponding payment interface endpoint payment method. ++ Each corresponding load mode or description of the payload structure payment method. -- confirmed product or service details; -- final amount and currency; -- counterparty identifier; -- order transaction number; -- confirmation time; -- necessary cross-domain correlation identifiers. +When the seller's side supports the one-way declaration model, SHALL in its public capability description is able to provide `capability_url` or equivalent capability statement portals, for example, Agent Card: -This does not require the payment request to contain the entire cart. A402 establishes minimum correlation through order, resource, amount, and currency, and MAY reference a separate confirmation object through `commerce_confirmation`. See the [commerce-to-payment connection rules](commerce-payment-negotiation.en.md). +```plain +{ + "agent_id": "did:act:alipay.com/Agent-alice-001", + "capabilities": { + "act:payment:negotiation": { + "mode": "one-way", + "capability_url": "https://merchant.com/.well-known/act-payment-capability.json" + } + } +} +``` -## 7. Current machine-contract boundary +When the seller's side supports the two-way negotiation model, SHALL of its public capability description provides `negotiation_endpoint` or the interface portal for the equivalent, for example, Agent Card: -Two-way negotiation requests use `currency`; responses and the “no common method” decision use `supported_methods`. `amount_currency` and `matched_methods` are not ACT 2.1 field names. +```plain +{ + "agent_id": "did:act:enterprise.com/premiumbot-02", + "capabilities": { + "act:payment:negotiation": { + "mode": "two-way", + "negotiation_endpoint": "https://api.enterprise.com/act/payment/negotiate" + } + } +} +``` -This document consistently uses the existing field names `capability_url`, `psp_id`, and `method_schema_url`. Spellings without underscores are not additional wire fields. ACT 2.1 does not publish the corresponding JSON Schema, version negotiation, signature, authentication, redirect, or cache rules. Implementations MUST NOT expand examples into additional normative requirements. +### One-way declaration mode +The one-way declaration model applies to a scenario where the seller side is fully open Payment Capability Advertisement, Buyer Agent which is directly accessible without additional consultation and interaction. Under this model, Buyer Agent SHALL reads Payment Capability Advertisement which is publicly available on the seller side and selects payment method from `supported_methods` the candidate matching the terms of the transaction. -The source mentions `act:commerce:decision-logged` and `act:commerce:cart-confirmed` as event identifiers that later evidence may reference. Event structure and governance remain part of TSD. +When Buyer Agent is bound by payment method from an upstream intention or authorized boundary, SHALL be chosen only from a candidate payment method that meets the relevant restriction. -## 8. Sources +Buyer Agent After the screening has been completed, SHALL extracts the corresponding `method_id`, `psp_id`, `endpoint` and `method_schema_url` for subsequent payment request construction input. -- Related CID website reference: [Commerce Interaction Domain](https://www.act-protocol.com/documentation/commerce); content not labeled ACT 2.1 is not a normative source for this release -- Related PSD website reference: [Payment Services Domain](https://www.act-protocol.com/documentation/payment); content not labeled ACT 2.1 is not a normative source for this release -- Cross-domain reference: [Protocol Overview](https://www.act-protocol.com/documentation/overview) +If there is no available match in the public statement payment method, Buyer Agent SHALL NOT continues to be paid. + +Examples of the format of the capacity to pay document (`act-payment-capability.json`) are as follows: + +```plain +{ + "version": "1.0", + "role": "payee", + "agent_id": "did:act:merchant.com/servicebot-01", + "supported_methods": [ + { + "method_id": "urn:act:payment:alipay", + "psps": [ + { + "psp_id": "urn:act:psp:alipay-official", + "endpoint": "https://openapi.alipay.com/act-psp/v1", + "method_schema_url": "https://alipay.com/act/schemas/payment-payload.json" + } + ] + } + ] +} +``` + +### Two-way consultation model +The two-way consultation model applies to situations where the seller ' s side needs to match payment method with the context of the buyer ' s request. Under this model, Buyer Agent SHALL initiate a request for consultation with `negotiation_endpoint` declared to the seller ' s side. + +The request SHOULD contain at least the following elements. + ++ `agent_id`, to mark Buyer Agent for initiating consultations. ++ `buyer_supported_methods` for a list of payment method acceptable to the buyer at present. ++ `currency`, to be used to declare the currency of the transaction. ++ `estimated_amount`, to be used to state the estimated amount of the transaction. + +Upon receipt of the request by the seller, SHALL return the result of capacity to pay that matches the current terms of the transaction. `supported_methods` SHOULD in the response contains at least the following elements. + ++ `method_id` for marking success payment method. ++ `psp_id` for marking Payment Service Provider corresponding to payment method. ++ `endpoint`, to identify the target interface address for follow-up payment request. ++ `method_schema_url` to identify the corresponding payment load description for payment method. + +When `supported_methods` is empty, SHALL be deemed to have failed to complete the matching of capacity to pay. In that case, Buyer Agent SHALL NOT continues to enter the payment phase and SHALL decides whether to replace payment method, replace the counterparty or terminate the transaction in accordance with the business strategy. + +The examples are as follows: + +**First step (buyer initiated)**: Buyer Agent Send HTTP POST request to `negotiation_endpoint` declared by seller Agent containing a list of payment method intended items supported by buyer, currency and estimated amount: + +```plain +{ + "agent_id": "did:act:platform.com/Agent-alice-001", + "buyer_supported_methods": ["urn:act:payment:alipay", "urn:act:payment:credit_card"], + "currency": "CNY", + "estimated_amount": 500.00 +} +``` + +**Second step (seller response)** The seller Agent returns the matching payment method and the corresponding PSP information: + +```plain +{ + "supported_methods": [ + { + "method_id": "urn:act:payment:alipay", + "psp_id": "urn:act:psp:alipay-official", + "endpoint": "https://openapi.alipay.com/act-psp/v1", + "method_schema_url": "https://alipay.com/act/schemas/payment-payload.json" + } + ] +} +``` + +If the response `supported_methods` is empty, it indicates that the parties have no available common payment method and that the transaction cannot continue, Buyer Agent SHALL suspends the process and gives feedback to Principal. + +## Outcome of the consultations +The final output of Payment Capability Negotiation aligns a set of capabilities available for subsequent payment. The result is at least SHALL to specify four parameters: `method_id`, `psp_id`, `endpoint` and `method_schema_url`. + +Where there are multiple optional outcomes, the selection logic is Buyer Agent locally and this component is not specified. + +## Security Considerations +Buyer Agent Before using Payment Capability Advertisement (`act-payment-capability.json`), the source should be verified and the statement confirmed as having been issued by the business's stated capability address (`capabilityurl`). + +Buyer Agent In the analysis of `supported_methods`, the paragraphs `pspid`, `endpoint`, and `methodschemaurl` are checked consistently to avoid Payment Service Provider unauthorized access due to the falsification, alteration or replacement of a capability statement. + +Payment Capability Advertisement for failure to confirm the source or key fields, Buyer Agent may not continue to use its initiation of a subsequent capacity to pay matching or payment process. + +# CID-CART-CFM: Cart Confirmation +## Overview +Cart Confirmation(Cart Regulation, CID-CART-CFM) requires Buyer Agent to enforce the treatment requirements for final confirmation of the subject matter, amount, terms of performance and related constraints of the transaction before entering the payment process. + +This component assumes the responsibility for order-level confirmation in the pre-payment phase, which is used to anchor the results of front-line goods or services discovery, candidate screening, matching of conditions and matching of capacity to pay into the confirmation of transactions that can be entered into payment execution. + +This component does not regulate internal candidate comparison algorithms, ranking strategies and decision logic Buyer Agent or internal order management, inventory deductions and compliance systems. + +## Participants and prefix +This component involves the following Participants: Buyer Agent for initiating the confirmation of the transaction, and Merchant for receiving the confirmation request and generating the order-level result, platform, seller Agent or its proxy interface. + +Before entering this component, SHALL satisfies the following preconditions. + ++ Buyer Agent Candidatures for identifiable goods or services have been obtained. ++ The subject matter of the transaction, the amount, currency and necessary performance information are clearly identified. ++ When the transaction is controlled by User objectives, bounds or authorized borders, Buyer Agent can be quoted in the relevant meanings of intent and constraint provided by Authorization & Delegation Domain. + +## Pre-test for rules +Cart Confirmation Before formally submitting Cart Confirmation to the counterparty and obtaining the order transaction number, Buyer Agent SHALL pre-tests the rules for enforcement of the transaction to be confirmed, based on the relevant intent and binding information of the current mission. Buyer Agent SHALL When the transaction involves commissioning payments, further verification is performed in conjunction with the language of the authorized boundary provided by Authorization & Delegation Domain. + +The pre-check SHOULD of the rules covers the following dimensions. + ++ The amount test, including whether the single sum exceeds the permitted amount Scope and whether the cumulative amount boundary is exceeded at the time of the cumulative constraint. ++ The category Scope test, i.e. whether the goods or services to be purchased meet the permitted category or do not trigger the prohibited category restriction. ++ MerchantScope test, i.e. whether the counterparty meets the permitted Merchant or does not trigger the ban Merchant. ++ The time limit test for performance, i.e. whether the expected delivery, delivery or service performance time meets the established requirements. ++ The price tolerance test, i.e. the final confirmation that the price falls within Scope permitted price fluctuations. + +Additional tests may also be added to the above when the realizing party has other business-related necessary verification items, but SHALL NOT weakens the basic verification semantics of this component definition. + +## Treatment when the test is failed +Buyer Agent SHALL NOT goes directly to the payment stage when either rule pre-checks are not passed. + ++ Buyer Agent SHALL be implemented in accordance with the intended or authorized transboundary disposal strategy in the border. ++ If the transboundary disposal strategy is suspended and notified, Buyer Agent SHALL suspends the current confirmation process and waits for User recertification or adjustment of the constraints. ++ If the cross-border treatment strategy is automatically cancelled, Buyer Agent SHALL terminates the current commerce interaction and records the reasons for the cancellation. ++ If no clear transboundary treatment strategy is foreseen, Buyer Agent SHOULD defaults on a suspended and notified treatment. + +## Submit lock and order generation +When the pre-rule test is passed, Buyer Agent may be submitted to the counterparty with a request Cart Confirmation. The confirmation request SHOULD includes, at a minimum, the details of the goods or services to be identified, the final price, the currency, the performance requirements and the relevant context as necessary. + +After accepting a request for confirmation, the counterparty should lock the relevant price, inventory or service capacity to the order level and generate the order transaction number back to Buyer Agent. The order transaction number returned by the counterparty SHALL be able to be consistently quoted at the subsequent payment execution stage. + +When the counterparty is unable to complete the order locking, SHALL return a clear failure or incorrect semantic, and Buyer Agent SHALL NOT the confirmation is considered successful. + +## Transaction confirmation result +Upon completion of Cart Confirmation, Buyer Agent SHALL forms the confirmation of the transaction. + +The transaction confirmation results SHOULD include at least the following. + ++ Details of goods or services identified. ++ Final recognition of the amount and currency. ++ Counterpart identification. ++ Order trade number. ++ Confirm time information. ++ Link identifiers used when cross-domain linkages are required. + +> Note: When key commercial nodes need to be recorded, this will be achieved in order to use the `act:commerce:cart-confirmed` event marker for follow-up certificate processing after Cart Confirmation completion. +> diff --git a/docs/specification/commerce-interaction.md b/docs/specification/commerce-interaction.md index e1eae82..9885e7d 100644 --- a/docs/specification/commerce-interaction.md +++ b/docs/specification/commerce-interaction.md @@ -2,173 +2,353 @@ 中文 | [English](commerce-interaction.en.md) -> **状态：ACT 2.1 Specification / Final / Normative** -> **协议内容已经定稿；是否符合本规范需要独立 Conformance 证据。** -> 版本基线：2026-08-11（UTC+8） +# 范围 +## 本域定位 +商业交互域（Commerce Interaction Domain, CID）规定智能体与商户、商户侧智能体或其他智能体之间，在支付执行前围绕商品或服务发现、意图上下文传递、支付能力对齐和交易确认所遵循的交互规则，为智能体商业中的支付前阶段提供统一、可引用、可衔接的商业交互语义。 -商业交互域（Commerce Interaction Domain，CID）规定支付执行前的商业交互语义：商品或服务如何形成机器可读候选，意图上下文如何传递，双方如何对齐支付能力，以及交易如何在进入支付服务域前完成最终确认。 +## 本域职责范围 +本域覆盖以下内容： -本域是 ACT 2.1 的规范性商业交互域文本。本 Release 中的本文是 2.1 版本化正文；[ACT Protocol 商业交互域网页](https://www.act-protocol.com/documentation/commerce)是未版本化的信息性参考。 ++ 商品与服务发现结果的最低信息要求； ++ 意图上下文的组织、传递与候选结果返回； ++ 支付能力声明、能力确认与能力协商； ++ 购物车确认、规则前置检验及交易确认结果； ++ 支付前商业共识形成所需的关键对象、状态语义和跨域引用关系。 -## 1. 范围与边界 +本域不规范以下内容： -CID 覆盖： ++ 智能体内部决策算法、排序策略、偏好推断及模型推理过程； ++ 商户内部经营处理、库存扣减、订单管理和履约系统实现； ++ 通用多智能体协作协议、任务编排与服务发现协议； -- 商品与服务发现结果的最低信息要求； -- 意图上下文的组织、传递和候选结果返回； -- 支付能力声明、确认与协商； -- 购物车确认、规则前置检验和交易确认结果； -- 支付前商业共识所需的对象、状态语义和跨域引用。 +# 本域组件列表与关系 +## 组件总览 +商业交互域由四个协议组件构成，它们共同完成从商品或服务发现、意图上下文传递与支付前能力协商，到交易确认完成并进入支付阶段的完整链路。 -CID 不规范： +各组件的功能定位如下。 -- Agent 内部的推理、排序、偏好推断和决策算法； -- 商户内部的经营、库存扣减、订单管理和履约实现； -- 通用多 Agent 协作、任务编排和服务发现协议； -- 支付执行、凭证验证和资金处理。这些属于[支付服务域](payment-services.md)； -- 可信事件的统一结构和存证治理。这些属于信任服务域。 ++ **CID-MER-CAT：商品与服务目录接口。** 负责规范商户向智能体开放结构化商品或服务目录时的最低信息要求，以支持机器可读的商品或服务发现。 ++ **CID-INT-XFR ：意图上下文传递。** 负责规范买方智能体向商户或平台传递与当前任务相关的意图上下文，并接收候选商品或服务结果的请求/响应过程。 ++ **CID-PCA-NEG：支付能力协商。** 负责规范买卖双方在支付前对可用支付方式、支付服务方、接口端点及相关载荷模式进行能力声明与协商的过程。 ++ **CID-CART-CFM：购物车确认。** 负责规范买方智能体在进入支付流程前，对交易标的、金额、履约条件及相关约束执行最终确认和规则前置检验的过程。 -## 2. 组件与核心对象 +## 核心对象与标识 +为保持本域内部处理以及与其他域之间引用关系的一致性，商业交互域使用一组标准核心对象和标识来描述支付前阶段的关键信息。本域核心对象及其作用可概括如下。 -| 组件 | 作用 | 主要输出 | -|---|---|---| -| `CID-MER-CAT` | 商品与服务目录接口；规定发现结果的最低信息要求，不规定统一目录协议 | 候选商品或服务结果 | -| `CID-INT-XFR` | 向商户或平台传递当前任务的意图上下文并接收候选结果 | 可关联请求的候选结果或错误 | -| `CID-PCA-NEG` | 在支付前对齐支付方式、支付服务方、端点和载荷模式 | 支付能力协商结果 | -| `CID-CART-CFM` | 对交易标的、金额、履约条件和授权约束做最终确认 | 可供支付服务域引用的交易确认结果 | +| **对象或标识** | **含义** | **主要产生位置** | **主要使用位置** | +| --- | --- | --- | --- | +| 意图上下文 | 买方智能体围绕当前任务构造的结构化意图信息，承载需求、约束和必要背景，并作为商品筛选、匹配和交易确认的上游输入 | ADD-INT-ICS，必要时也可由买方智能体基于上游意图对象在本地构造 | CID-INT-XFR、CID-CART-CFM，以及商户或平台的候选匹配过程 | +| 候选商品或服务结果 | 商户、平台或卖方智能体返回的结构化候选结果，用于买方智能体执行筛选、比较和后续规则前置检验 | CID-MER-CAT、CID-INT-XFR | CID-CART-CFM，以及买方智能体本地决策过程 | +| 交易确认结果 | 购物车确认阶段形成的订单级最终确认结果，通常包括交易标的、金额、商户标识、订单交易号及相关确认时间信息 | CID-CART-CFM | 支付服务域，以及可信存证与事后争议处理支持环节 | +| 支付能力协商结果 | 买卖双方就可用支付方式、支付服务方、接口端点及方法模式形成的一致结果 | CID-PCA-NEG | 后续支付服务域的支付请求构造与执行 | -本域使用四类核心对象： +## 依赖与跨域引用 +CID-MER-CAT 和 CID-INT-XFR 都可作为候选商品或服务结果的上游来源，为后续购物车确认提供输入。 -| 对象 | 产生位置 | 主要使用位置 | -|---|---|---| -| 意图上下文 | `ADD-INT-ICS`，或买方 Agent 基于上游意图在本地构造 | `CID-INT-XFR`、`CID-CART-CFM` 和候选匹配 | -| 候选商品或服务结果 | `CID-MER-CAT`、`CID-INT-XFR` | 买方本地决策和 `CID-CART-CFM` | -| 支付能力协商结果 | `CID-PCA-NEG` | 支付请求构造和路径选择 | -| 交易确认结果 | `CID-CART-CFM` | 支付服务域，以及后续证据和争议处理 | +CID-PCA-NEG 的作用主要发生在支付前衔接阶段，用于在需要时确定本次交易所采用的支付方式、支付服务方和接口端点，从而为后续支付请求构造提供依据。 -委托授权域向 CID 提供 ISR 及相关约束上下文。支付服务域消费交易确认结果、订单交易号和支付能力协商结果。信任服务域维护事件类型及存证治理规则，CID 不重复定义。 +CID-CART-CFM 是本域中承接前序发现、筛选、协商结果并形成订单级最终确认的关键组件，其输出结果将直接影响后续支付服务域是否能够发起支付执行。 -## 3. `CID-MER-CAT`：商品与服务目录接口 +委托授权域主要向本域提供 ISR 及相关约束上下文；支付服务域主要引用本域形成的交易确认结果、订单交易号、支付能力协商结果；信任服务域可信存证子篇统一维护相关事件类型和存证治理规则，本域不重复定义。信用关联子篇中定义的智能体信用关联声明可用于本域商品或服务筛选的辅助判断。 -### 3.1 最低信息要求 +# CID-MER-CAT：商品与服务目录接口 +## 概述 +商品与服务目录接口（Catalog Interface，CID-MER-CAT）规定商户向智能体开放结构化商品或服务目录时的最低信息要求，以支持机器可读的商品或服务发现。本组件输出的候选商品或服务结果，可作为买方智能体后续比较决策和购物车确认的上游输入。 -每个可供买方 Agent 消费的商品或服务明细应包含： +本组件当前版本暂时不定义统一的目录协议，而是规定目录结果在进入后续商业交互前应满足的最低信息要求。 -- 可在全局或商户域内唯一解析的商品或服务标识； -- 商品或服务名称； -- 可用于意图约束匹配的类目或类别； -- 明确的标价和货币单位。 +本组件不规范目录检索排序逻辑、推荐算法、商户内部商品建模方式，以及库存扣减、价格计算和订单履约等商户内部处理。 -返回结果宜进一步包含： +## 参与方与前置条件 +本组件涉及以下参与方：提供商品或服务信息的商户或平台，以及发起目录访问并消费返回结果的买方智能体。 -- 库存、可售或服务可用状态； -- 价格有效截止时间或报价更新时间； -- 配送、履约或交付时间； -- 商户标识、商户引用地址或详情引用地址。 +进入本组件前，应满足以下前置条件。 -不满足最低信息要求的结果不宜直接进入 `CID-CART-CFM`。若结果只能用于展示，实现方宜先补齐规则前置检验所需的信息。 ++ 商户或平台已具备对外提供结构化商品或服务信息的能力。 ++ 买方智能体已建立与当前任务相关的基本商业上下文，并能够对返回结果进行本地筛选、比较或后续确认处理。 ++ 当后续链路需要依据用户意图与约束执行规则检验时，买方智能体应能够将目录返回结果与委托授权域提供的相关意图上下文相衔接。 -### 3.2 当前明确不统一的内容 +## 最低返回信息要求 +商户侧返回的商品或服务目录数据应满足最低信息可用性要求，以确保后续商业交互和支付前确认能够正常开展。 -ACT 2.1 不规定统一目录接口的调用路径、HTTP 方法、认证、分页、检索排序、推荐算法或商户内部商品模型。实现方可以复用行业协议、商户 API 或平台目录，只要结果满足上述最低信息要求。 +对于每一条可供买方智能体消费的商品或服务明细，返回结果应包含以下信息。 -## 4. `CID-INT-XFR`：意图上下文传递 ++ 商品或服务标识，应为全局唯一或在商户域内可唯一解析的标识。 ++ 商品名称或服务名称，应能够支持买方智能体和后续处理环节识别交易标的。 ++ 商品类目或服务类别，应能够支持后续与用户意图约束进行匹配。 ++ 明确的标价及货币单位，应能够支撑金额比较、规则前置检验和支付前确认。 -### 4.1 意图上下文 +除上述最低必备信息外，商户侧返回结果宜进一步包含以下信息。 -意图上下文围绕当前任务组织，通常包括： ++ 当前库存状态、可售状态或服务可用状态。 ++ 价格有效截止时间或报价更新时间。 ++ 预计配送时间、履约时效或服务交付时间。 ++ 商户标识、商户引用地址或商品详情引用地址。 -- 用户明确表达的购买或服务需求； -- Agent 基于已确认上下文归纳的补充需求； -- 金额、类目、商户、履约时效等约束； -- 候选匹配所需的必要背景； -- 经实现方允许且适用的偏好信息。 +当目录结果无法满足最低信息要求时，买方智能体不宜直接将该结果用于购物车确认或支付前衔接。当返回结果仅适用于展示而不足以支持规则前置检验时，实现方宜在进入 CID-CART-CFM 前补充获取必要字段。 -显式需求和约束宜作为主要内容。隐式需求或偏好不得与用户已确认的约束或 ISR/IAC 授权边界冲突；知情同意和数据保护由实现方负责。 +> ACT 当前版本暂不对目录接口的调用路径、请求方法、认证机制和分页方式作统一规定。 +> -### 4.2 请求、响应与更新 +## 兼容性说明 +实现方可结合现有行业协议、商户开放接口或平台既有目录服务完成对接，只要其返回结果能够满足本组件规定的最低信息要求即可。 -请求宜包含唯一请求标识、意图上下文、必要的跨域关联标识、约束、响应格式要求和来源认证信息。响应应能关联原请求，并至少返回可供筛选和确认的候选明细；无法处理时应返回机器可识别的错误语义。 +# CID-INT-XFR：意图上下文传递 +## 概述 +意图上下文传递（Intent Context Transfer，CID-INT-XFR）规定买方智能体向商户或平台传递与当前任务相关的意图上下文，并接收候选商品或服务结果的请求/响应过程。本组件使用的意图上下文可引用委托授权域形成的 ISR 及相关约束语义，并作为后续候选筛选、规则前置检验和购物车确认的上游输入。 -多轮更新应生成新的请求标识并关联前序请求，宜只携带本轮变化内容。错误语义宜覆盖：格式错误、无匹配结果、访问受限、约束冲突和请求过频。买方 Agent 可据此重试、切换商户、调整请求或通知用户。 +本组件处理的是支付前阶段的意图传递与候选匹配，不规范买方智能体内部的意图理解、偏好推断和决策算法。 -买方 Agent 可以并发请求多个商户或平台；候选汇总、比较和最终决策仍属于本地实现，不属于 CID 协议规则。 +## 参与方与前置条件 +本组件涉及以下参与方：发起意图请求的买方智能体，以及接收请求并返回候选结果的商户、平台或其代理接口。 -## 5. `CID-PCA-NEG`：支付能力协商 +进入本组件前，应满足以下前置条件。 -### 5.1 能力声明 ++ 买方智能体已建立与当前任务相关的基本商业上下文，并能够构造可传递的意图上下文。 ++ 商户或平台已具备接收意图请求并返回结构化候选结果的能力。 ++ 当后续链路需要依据用户目标与约束执行规则检验时，买方智能体应能够将意图上下文与委托授权域提供的相关约束语义相衔接。 -卖方、商户或其 Agent 可以在 Agent Card 的 `capabilities` 节点声明支付协商能力，也可以在约定地址发布 `act-payment-capability.json`。声明应能表达： +## 意图上下文构成 +买方智能体传递的意图上下文应围绕当前任务组织，并能够支持商户或平台开展候选匹配。意图上下文通常包括以下内容。 -- 协商模式； -- 支持的支付方式； -- 每种方式对应的支付服务方； -- 支付接口端点； -- 载荷模式或结构说明。 ++ 显式意图需求，即用户明确表达的购买目标或服务需求。 ++ 隐式意图需求，即买方智能体基于当前任务上下文、用户已确认信息或连续交互内容归纳形成的补充需求。 ++ 约束条件，即与本次任务相关的金额、类目、商户、履约时效等边界信息。 ++ 必要背景信息，即为完成候选匹配所需的补充上下文。 ++ 经实现方允许且在适用条件下可传递的偏好信息。 -Agent Card 可以使用 `capability_url` 指向单向能力声明，或使用 `negotiation_endpoint` 指向双向协商接口。来源文档提供的是结构示例，并未给出可直接宣称正式兼容的 JSON Schema、版本协商或签名格式。 +显式意图需求和约束条件宜作为意图上下文的主要组成部分。隐式意图需求和偏好信息可作为可选信息传递，不应与用户已明确确认的约束条件或委托授权域形成的 ISR/IAC 所表达的授权边界相冲突。 -### 5.2 单向声明 +当传递隐式意图需求或偏好信息时，实现方应自行处理相关的知情同意与数据保护要求。 -买方 Agent 读取卖方公开能力，从 `supported_methods` 中筛选符合交易条件和上游授权约束的方法。选择结果至少应明确： +## 请求与响应要求 +买方智能体发起意图请求时，应构造可被商户或平台解析的请求报文。请求报文宜包含以下关键要素。 -- `method_id`：支付方法标识； -- `psp_id`：支付服务方标识； -- `endpoint`：后续支付请求端点； -- `method_schema_url`：方法载荷结构说明。 ++ 请求标识，用于唯一标识本次请求并支持响应关联。 ++ 与当前任务相关的意图上下文。 ++ 在需要跨域关联时使用的关联标识。 ++ 必要的约束条件和响应格式要求。 ++ 请求来源认证信息。 -没有匹配方法时，不得继续进入支付阶段。 +商户或平台返回的响应报文应能够与原请求建立对应关系。响应结果至少应包含可供后续筛选和确认使用的候选商品或服务明细。当商户或平台无法返回有效候选结果时，应返回错误响应，并给出可被买方智能体识别的错误语义。 -### 5.3 双向协商 +## 动态更新与错误语义 +买方智能体应支持在多轮交互中对意图上下文进行动态更新。每次动态更新应生成新的请求标识，并与前序请求建立关联。动态更新请求宜仅携带本次发生变化的意图内容。 -买方 Agent 向 `negotiation_endpoint` 发起请求。请求语义包括买方 Agent 标识、买方支持的方法、币种和预估金额；卖方返回与当前交易条件匹配的方法、PSP、端点和方法 Schema。 +当商户或平台无法正常处理请求时，错误语义宜覆盖格式错误、无匹配结果、访问受限、约束冲突和请求过频等类别。买方智能体可根据错误类型决定重试、切换商户、调整请求或通知用户。 -双方没有共同方法时，买方 Agent 不得继续支付，并应根据业务策略更换方法、交易对手或终止交易。多个结果的最终排序和选择由买方 Agent 本地处理。 +## 多商户路由 +在实际商业网络中，买方智能体可同时向多个商户或平台并发发送意图请求，并汇总各方返回的候选结果。候选结果的比较与最终决策属于买方智能体本地处理过程，不属于本组件规范范围。 -### 5.4 安全要求 +> 注：在需要记录关键商业节点时，实现方可在决策完成后引用 `act:commerce:decision-logged` 事件标识开展后续存证处理。 +> -买方 Agent 在使用能力声明前，应验证它来自商户已声明的能力地址。解析结果时，应检查 `psp_id`、`endpoint`、`method_schema_url` 等关键字段的一致性，防止声明被伪造、篡改或替换。来源无法确认或关键字段校验失败时，不得继续能力匹配或支付。 +# CID-PCA-NEG：支付能力协商 +## 概述 +支付能力协商（Payment Capability Negotiation，CID-PCA-NEG）规定在需要进入支付执行前，买卖双方就可用支付方式、支付服务方、接口端点及相关载荷模式进行能力声明与协商的过程。 -## 6. `CID-CART-CFM`：购物车确认 +本组件主要适用于卖方智能体参与的多智能体商业交互场景，也可用于其他需要在支付前完成支付能力对齐的场景。本组件输出的支付能力协商结果，可作为后续支付服务域构造支付请求和选择支付路径的输入。 -### 6.1 规则前置检验 +本组件不定义通用的服务发现、消息交换、任务编排与协作交互协议，而仅规范支付前衔接所需的支付能力声明与支付能力协商语义。 -进入支付前，买方 Agent 应针对拟确认交易检验： +## 参与方与前置条件 +本组件涉及以下参与方：发起支付能力协商的买方智能体，以及对外声明支付能力并返回协商结果的商户、卖方智能体或其代理接口。 -- 单笔和累计金额边界； -- 允许或禁止的类目； -- 允许或禁止的商户； -- 配送、交付或服务履约时效； -- 最终价格是否在允许容差内； -- 委托支付场景中的 ISR/IAC 授权边界。 +进入本组件前，应满足以下前置条件。 -任一检验失败时不得直接进入支付。若已有越界策略，应执行该策略；`PAUSE_AND_NOTIFY` 等待用户重新确认或调整约束，`AUTO_CANCEL` 记录原因并终止。没有明确策略时，宜默认暂停并通知。 ++ 买卖双方已经形成可进入支付前衔接阶段的基本商业上下文。 ++ 买方智能体已能够识别本次交易的金额、币种、交易对象及其他必要交易参数。 ++ 卖方一侧已具备对外发布支付能力声明或响应支付能力协商请求的能力。 ++ 当本次交易受用户意图或授权边界约束时，买方智能体应能够依据相关约束语义判断候选支付方式是否可用。 -### 6.2 提交、锁定与结果 +## 支付能力声明 +### 声明模式 +卖方一侧可通过标准化路径对外公开其支付能力声明。在卖方智能体场景下，支付能力声明可通过其 Agent Card 中的 `capabilities` 节点进行发布，并声明本方支持的协商模式及对应接口地址。当实现方支持独立的支付能力声明文件时，也可在约定地址发布 `act-payment-capability.json` 文件。 -检验通过后，确认请求宜包含商品或服务明细、最终价格、币种、履约要求和必要关联上下文。交易对手接受后，应完成订单级价格、库存或服务能力锁定并返回可稳定引用的订单交易号；无法锁定时应返回明确失败，不得视为确认成功。 +支付能力声明应能够表达以下信息。 -交易确认结果宜至少包含： ++ 本方支持的协商模式。 ++ 本方支持的支付方式列表。 ++ 每种支付方式对应的支付服务方标识。 ++ 每种支付方式对应的支付接口端点。 ++ 每种支付方式对应的载荷模式或载荷结构说明。 -- 已确认的商品或服务明细； -- 最终金额与币种； -- 交易对手标识； -- 订单交易号； -- 确认时间； -- 必要的跨域关联标识。 +当卖方一侧支持单向声明模式时，其公开能力描述中应能够提供 `capability_url` 或等价能力声明入口，其 Agent Card 示例如下： -支付请求不因此必须携带完整购物车。A402 使用订单、资源、金额和币种建立最小关联，并可通过 `commerce_confirmation` 引用独立确认对象；具体关系见[商业交互到支付的连接规则](commerce-payment-negotiation.md)。 +```plain +{ + "agent_id": "did:act:alipay.com/agent-alice-001", + "capabilities": { + "act:payment:negotiation": { + "mode": "one-way", + "capability_url": "https://merchant.com/.well-known/act-payment-capability.json" + } + } +} +``` -## 7. 当前机器契约边界 +当卖方一侧支持双向协商模式时，其公开能力描述中应能够提供 `negotiation_endpoint` 或等价协商接口入口，其 Agent Card 示例如下： -双向协商请求使用 `currency`，响应和“无共同方法”判断使用 `supported_methods`；`amount_currency` 和 `matched_methods` 不是 ACT 2.1 的字段名。 +```plain +{ + "agent_id": "did:act:enterprise.com/premiumbot-02", + "capabilities": { + "act:payment:negotiation": { + "mode": "two-way", + "negotiation_endpoint": "https://api.enterprise.com/act/payment/negotiate" + } + } +} +``` -本文统一使用既有字段名 `capability_url`、`psp_id`、`method_schema_url`；不将缺少下划线的拼写解释为新增 wire 字段。ACT 2.1 未发布相应 JSON Schema、版本协商、签名、认证、重定向和缓存规则；实现不得把示例扩写成额外规范要求。 +### 单向声明模式 +单向声明模式适用于卖方一侧已完整公开支付能力声明，买方智能体可直接读取而无需额外协商交互的场景。在该模式下，买方智能体应读取卖方一侧公开的支付能力声明，并从 `supported_methods` 中筛选出与本次交易条件相匹配的候选支付方式。 -来源提到的 `act:commerce:decision-logged` 和 `act:commerce:cart-confirmed` 是后续存证可引用的事件标识；事件结构和治理仍属于信任服务域。 +当买方智能体存在来自上游意图或授权边界的支付方式约束时，应仅从满足相关约束的候选支付方式中进行选择。 -## 8. 来源 +买方智能体在完成筛选后，应提取所选支付方式对应的 `method_id`、`psp_id`、`endpoint` 和 `method_schema_url`，作为后续支付请求构造输入。 -- CID 相关网站参考：[商业交互域](https://www.act-protocol.com/documentation/commerce)；未标明 ACT 2.1 的网页内容不是本 Release 的规范来源 -- PSD 相关网站参考：[支付服务域](https://www.act-protocol.com/documentation/payment)；未标明 ACT 2.1 的网页内容不是本 Release 的规范来源 -- 跨域上位参考：[协议概览](https://www.act-protocol.com/documentation/overview) +若公开声明中不存在可用的匹配支付方式，买方智能体不应继续进入支付阶段。 + +支付能力文件（`act-payment-capability.json`）的格式示例如下： + +```plain +{ + "version": "1.0", + "role": "payee", + "agent_id": "did:act:merchant.com/servicebot-01", + "supported_methods": [ + { + "method_id": "urn:act:payment:alipay", + "psps": [ + { + "psp_id": "urn:act:psp:alipay-official", + "endpoint": "https://openapi.alipay.com/act-psp/v1", + "method_schema_url": "https://alipay.com/act/schemas/payment-payload.json" + } + ] + } + ] +} +``` + +### 双向协商模式 +双向协商模式适用于卖方一侧需要根据买方请求上下文动态匹配支付方式的场景。在该模式下，买方智能体应向卖方一侧声明的 `negotiation_endpoint` 发起协商请求。 + +该请求宜至少包含以下要素。 + ++ `agent_id`，用于标识发起协商的买方智能体。 ++ `buyer_supported_methods`，用于声明买方当前可接受的支付方式列表。 ++ `currency`，用于声明本次交易使用的币种。 ++ `estimated_amount`，用于声明本次交易的预估金额。 + +卖方一侧收到请求后，应返回与当前交易条件相匹配的支付能力结果。响应结果中的 `supported_methods` 宜至少包含以下要素。 + ++ `method_id`，用于标识匹配成功的支付方式。 ++ `psp_id`，用于标识该支付方式对应的支付服务方。 ++ `endpoint`，用于标识后续支付请求的目标接口地址。 ++ `method_schema_url`，用于标识该支付方式对应的支付载荷结构说明。 + +当 `supported_methods` 为空时，应视为双方未能完成支付能力对齐。在该情况下，买方智能体不应继续进入支付阶段，并应根据业务策略决定是否更换支付方式、更换交易对手或终止本次交易。 + +示例如下： + +**第一步（买方发起）**：买方智能体向卖方智能体声明的`negotiation_endpoint` 发送 HTTP POST 请求，请求体包含买方支持的支付方式列表、意图品类、货币及预估金额： + +```plain +{ + "agent_id": "did:act:platform.com/agent-alice-001", + "buyer_supported_methods": ["urn:act:payment:alipay", "urn:act:payment:credit_card"], + "currency": "CNY", + "estimated_amount": 500.00 +} +``` + +**第二步（卖方响应）**：卖方智能体返回匹配的支付方式及对应的 PSP 信息： + +```plain +{ + "supported_methods": [ + { + "method_id": "urn:act:payment:alipay", + "psp_id": "urn:act:psp:alipay-official", + "endpoint": "https://openapi.alipay.com/act-psp/v1", + "method_schema_url": "https://alipay.com/act/schemas/payment-payload.json" + } + ] +} +``` + +若响应中 `supported_methods` 为空，则表示双方无可用的共同支付方式，本次交易无法继续，买方智能体应中止流程并向委托人反馈。 + +## 协商结果 +支付能力协商的最终输出，为一组可供后续支付使用的能力对齐结果。该结果至少应能够明确 `method_id`、`psp_id`、`endpoint` 和 `method_schema_url` 四项参数。 + +当存在多个可选结果时，具体选择逻辑由买方智能体本地处理，本组件不作规定。 + +## 安全考虑 +买方智能体在使用支付能力声明（`act-payment-capability.json`）前，应对其来源进行校验，并确认该声明系由商家已声明的能力地址（`capabilityurl`）发布。 + +买方智能体在解析 `supported_methods` 时，宜对其中的 `pspid`、`endpoint`、`methodschemaurl` 等字段进行一致性检查，避免因能力声明被伪造、篡改或替换而误接入非预期支付服务方。 + +对于来源无法确认或关键字段校验失败的支付能力声明，买方智能体不得继续使用其发起后续支付能力匹配或支付流程。 + +# CID-CART-CFM：购物车确认 +## 概述 +购物车确认（Cart Confirmation，CID-CART-CFM）规定买方智能体在进入支付流程前，对本次交易标的、金额、履约条件及相关约束执行最终确认的处理要求。 + +本组件承担支付前阶段的订单级确认职责，用于将前序商品或服务发现、候选筛选、条件匹配及支付能力对齐结果固化为可进入支付执行的交易确认结果。 + +本组件不规范买方智能体内部的候选比较算法、排序策略和决策逻辑，也不规范商户内部的订单管理、库存扣减和履约系统实现。 + +## 参与方与前置条件 +本组件涉及以下参与方：发起交易确认的买方智能体，以及接收确认请求并生成订单级结果的商户、平台、卖方智能体或其代理接口。 + +进入本组件前，应满足以下前置条件。 + ++ 买方智能体已获取可供确认的商品或服务候选结果。 ++ 本次交易的标的、金额、币种及必要履约信息已经能够被明确识别。 ++ 当本次交易受用户目标、约束或授权边界控制时，买方智能体已能够引用委托授权域提供的相关意图与约束语义。 + +## 规则前置检验 +在正式向交易对手提交购物车确认并获取订单交易号之前，买方智能体应依据当前任务相关的意图与约束信息，对本次拟确认交易执行规则前置检验。当本次交易涉及委托支付时，买方智能体应进一步结合委托授权域提供的授权边界语义开展校验。 + +规则前置检验宜覆盖以下维度。 + ++ 金额检验，包括单笔金额是否超出允许范围，以及在存在累计约束时是否超出累计额度边界。 ++ 类目范围检验，即拟购买商品或服务是否符合允许类目或未触发禁止类目限制。 ++ 商户范围检验，即交易对手是否符合允许商户范围或未触发禁止商户限制。 ++ 履约时效检验，即预计配送、交付或服务履约时间是否满足既定要求。 ++ 价格容差检验，即最终确认价格是否落在允许的价格波动范围内。 + +当实现方存在其他与业务相关的必要校验项时，也可在上述基础上增加补充检验，但不应削弱本组件定义的基本校验语义。 + +## 检验未通过时的处理 +当任一规则前置检验未通过时，买方智能体不应直接进入支付阶段。 + ++ 若相关意图或授权边界中已预设越界处理策略，买方智能体应按照该策略执行。 ++ 若越界处理策略为暂停并通知，买方智能体应中止当前确认流程，并等待用户重新确认或调整约束。 ++ 若越界处理策略为自动取消，买方智能体应终止本次商业交互，并记录取消原因。 ++ 若未预设明确的越界处理策略，买方智能体宜默认采用暂停并通知的处理方式。 + +## 提交锁定与订单生成 +当规则前置检验通过后，买方智能体可向交易对手提交购物车确认请求。确认请求宜至少包括本次拟确认的商品或服务明细、最终价格、币种、履约要求以及必要的关联上下文。 + +交易对手在接受确认请求后，应对相关价格、库存或服务能力执行订单级锁定，并生成订单交易号返回给买方智能体。交易对手返回的订单交易号应能够在后续支付执行阶段被稳定引用。 + +当交易对手无法完成订单级锁定时，应返回明确的失败结果或错误语义，买方智能体不应将该次确认视为成功。 + +## 交易确认结果 +购物车确认完成后，买方智能体应形成交易确认结果。 + +交易确认结果宜至少包括以下内容。 + ++ 已确认的商品或服务明细。 ++ 最终确认金额及币种。 ++ 交易对手标识。 ++ 订单交易号。 ++ 确认时间信息。 ++ 在需要跨域关联时使用的关联标识。 + +> 注：在需要记录关键商业节点时，实现方可在购物车确认完成后引用 `act:commerce:cart-confirmed` 事件标识开展后续存证处理。 +> diff --git a/docs/specification/overview.en.md b/docs/specification/overview.en.md index e0078fc..3563f6c 100644 --- a/docs/specification/overview.en.md +++ b/docs/specification/overview.en.md @@ -1,81 +1,203 @@ -# ACT 2.1 Specification Overview +# ACT 2.1 Protocol Overview [中文](overview.md) | English -> **Source status: ACT 2.1 / Final** -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +# Introduction +In the Internet business phase, which is dominated by information retrieval and page browsing, User is the direct implementer of business decision-making and payment. The transaction takes place between User and the business platform, User in real-time viewing of the goods, clicking on the list, and confirming payments on a case-by-case basis through interface. This premise is changing with the deep penetration of AI Agent technology. Agent Starts on behalf of User service discovery, commodity price, transaction negotiation and even payment execution, User from "real-time operator" to "target setr and authorized person". -ACT (Agentic Commerce Trust Protocol) defines the authorization, transaction, payment, and trust-coordination semantics for commercial activities involving agents. ACT 2.1 contains four capability domains connected into complete business flows through cross-domain components. +While bringing about efficiency gains, this change has also brought about confidence challenges that traditional business and payment systems need to face and address: -## Normative language ++ First, in agentic commerce, the subject of the transaction is separated. User is responsible for proposing objectives and constraints, Agent is responsible for implementing decision-making and operations, Merchant and Payment Service Provider are seen as proxy requests for transactions; “who wishes, who operates, who is responsible” is no longer as natural as traditional e-commerce. ++ Second, the transaction is based on a change from User real-time confirmation to User ex post facto authorization, Agent ex post facto execution. This means that the system not only answers whether a transaction has been successful, but also whether it is within the original authorized boundary User, whether it has been faithfully implemented user intent, and whether the results of the execution can be traced and explained. ++ Finally, the efficiency of implementation Agent may result in a significant increase in transaction numbers and transaction complexity, with corresponding disputes, audits, and risk-control pressures being magnified simultaneously. Traditional manual review-by-hand processing will make it difficult to adapt to scalable Agent transactions, and commercial systems will require standardized recording and certification mechanisms that can be automated. -The Chinese ACT 2.1 publication uses the following requirement strengths. Every domain specification and cross-domain connection rule is interpreted according to this table: +In any case, agentic commerce does not create a single chain of security, but rather an overall migration of the basis of trust in transactions: trust is no longer based on the natural premise of “real-time human presence”, but must be clearly established through a mechanism of protocols that can be expressed, communicated, verified and traced. -| Chinese source term | Requirement strength | English equivalent | -|---|---|---| -| 应, 必须 | mandatory | `MUST` | -| 不应, 不得 | prohibited | `MUST NOT` | -| 宜 | recommended | `SHOULD` | -| 不宜 | discouraged | `SHOULD NOT` | -| 可, 可以 | optional | `MAY` | +ACT (Agentic Commerce Trust Protocol, Agentic Commerce Trust Protocol) is a set of application-level trust protocols designed to address the above-mentioned challenges, covering the full commercial chain from user intent expression, authorization and delegation, commerce interaction payment execution to trusted attestation. ACT does not replace the existing payment network, Merchant system or identity infrastructure, but rather provides a layer of trust organization for the agentic commerce scene, enabling each Participants to achieve delegation of authority, consistency of transactions, payment control and enforceability within the framework of a unified protocol. -For field presence, “required” means the field MUST be present with a valid value; “conditionally required” means it MUST be present with a valid value when the stated condition holds; and “optional” means it MAY be present and, when present, MUST have a valid value. Uppercase normative terms in this translation preserve the requirement strength of the Chinese versioned publication. If a translation discrepancy is found, the Chinese publication controls. +This document, which is the ACT protocol outline, defines the protocol ' s Scope boundary, birth background needs, Design Goals and Principles, Overall Framework, Participants role and terminology system and is the top reference document for each domain specification document. -## 1. Four capability domains +# Scope +This Protocol is directed towards the scenario of Agent engaging in commercial transactions and regulates the level of trust and collaboration between User, Agent, Merchant, Payment Service Provider and related Trust Service Provider for the completion of authorized, enforceable and verifiable commercial transactions. -| Domain | Responsibility | Specification | -|---|---|---| -| ADD | Express user intent and issue and manage authorization credentials that an Agent can execute | [Authorization & Delegation Domain](authorization-delegation.en.md) | -| CID | Discover goods or services, transfer intent, negotiate payment capabilities, and confirm transactions | [Commerce Interaction Domain](commerce-interaction.en.md) | -| PSD | Manage payment tools, authorization levels, payment execution, validation, state, and error recovery | [Payment Services Domain](payment-services.en.md) | -| TSD | Provide trustworthy evidence and trust associations for cross-domain facts | [Trust Services Domain](trust-services.en.md) | +This Protocol regulates, inter alia, the following four types of protocol activities: -The [scenario guide](../flows/scenarios.en.md) explains how the four domains compose. If a scenario description conflicts with a domain specification, the corresponding domain specification controls. ++ authorization and delegation: an act of protocol formed around the boundaries of expression, delegation of enforcement powers and their effects user intent. ++ commerce interaction: The act of protocol that occurs around the discovery of goods or services, the confirmation of terms of trade and the commercial consensus before payment. ++ Payment execution: an act of protocol occurring around payment evidence use, payment request initiation, payment result return and its alignment with upstream authorization and transaction confirmation. ++ trusted attestation: Actions in support of protocols that occur around the recording of key business events, the execution of fact-checks and subsequent disputes. -## 2. Payment Services components +This Protocol does not regulate the following: -| Type | Component | Meaning | -|---|---|---| -| Payment tool | `PSD-PMT-BND` | Establish a restricted payment-tool reference so the Agent does not handle raw account credentials | -| Account isolation | `PSD-AGT-SUB` | Provide an optional dedicated sub-account and lifecycle management for an Agent | -| L1 | `PSD-PAY-INS` | The user is present and completes per-payment identity and authorization confirmation before funds are processed | -| L2 | `PSD-PAY-DEL` | The transaction intent, including goods, merchant, and amount, is explicit, and the Agent pays automatically within the authorization boundary | -| L3 | `PSD-PAY-AUP` | The Agent autonomously selects and pays within task, budget, and policy boundaries | -| Payment access | `PSD-PAY-A402` | Use HTTP 402 to exchange payment requirements, payment proof, and validation results | ++ Specific interactive experiences between Agent and User are achieved, including the front-end interface, the natural language dialogue approach, the introduction project and the tasking strategy. ++ Commercial Participants own operating regulations, including commodity pricing, inventory management, order performance, after-sale processing and other operational details. ++ Rules for the liquidation and settlement of funds for the base payment infrastructure. ++ The internal risk control model, the anti-fraud algorithm and the internal audit strategy within the participating agencies. ++ Details on the realization of technologies that are not directly part of the application layer of confidence and collaboration, such as ground-level communications transmission, infrastructure deployment, system transportation and other technologies. -L1, L2, and L3 answer *why the Agent is authorized to pay*. A402 answers *how payment requirements and proof are exchanged*. A402 can be used by all three authorization levels and is not itself an authorization level. +# Trust Requirements for Agentic Commerce +The core needs in ACT are grouped into four categories: authorization and delegation (R1), commerce interaction (R2), payment services(R3) and trust services (R4). The four categories of needs correspond to Agent, respectively, why they represent User actions, how to develop a common understanding of transactions, how to complete payment implementation and how to validate implementation results. -## 3. Basic A402 flow +Together, these four types of requirements form the basis of the design of the protocol ACT and delineate the four subsequent capability areas. -```text -Buyer Agent → Paid Service: request resource -Paid Service → Buyer Agent: 402 + Payment-Needed -Buyer Agent → Payment Service: authorized payment -Payment Service → Buyer Agent: payment result / proof -Buyer Agent → Paid Service: retry original request + Payment-Proof -Paid Service → Payment Service: verify proof -Paid Service → Buyer Agent: deliver resource -``` +![](../assets/specification/act-2.1-trust-requirements.png) -See the [A402 payment access protocol](a402.en.md) for the complete requirements. See [CID–PSD negotiation](commerce-payment-negotiation.en.md) for the connection rules between commerce interaction and payment. +**authorization and delegation Requirements (R1)** -## 4. Protocol and implementation boundary ++ The need for authorization and delegation addresses how user intent can be reliably expressed and serves as a uniform basis for subsequent business behaviour. ++ Under User real-time presence, a structured expression of intent helps to support subsequent commodity matching, transaction negotiation and confirmation of payment; under User non-real-time presence, this expression further forms the basis of the mandate Agent for self-execution. The core consists of two points: user intent authorization and delegation per se SHALL be credible, and SHALL intent and authorized boundary SHALL be able to be structured to support transmission, understanding and validation of the follow-up. -- `docs/specification/` defines ACT 2.1. -- `code/schemas/` provides JSON Schemas, fixtures, and test-support artifacts. -- `integrations/` connects ACT to specific products. -- `code/samples/` and `code/web-client/` demonstrate implementation approaches and business flows. +**commerce interaction Requirement (R2)** -Machine-readable artifacts, product code, and demos MUST NOT add or modify protocol requirements. Alipay fields, APIs, signing, onboarding, and sandbox behavior are governed by the [official AIPay materials](https://aipay.alipay.com/callpay) and are not part of the ACT specification. ++ The need for commerce interaction addresses how Agent can efficiently and accurately match and interface user intent with goods or services. ++ This could be achieved by providing structured catalogues of goods or services to Agent, Agent passing Intent Context to Merchant side, or by combining them with more effective matching mechanisms. On this basis, there could also be interaction between Agent and Merchant around the process of asking for quotations, inventory confirmation, confirmation of terms and synergy of services. -## 5. Developer entry points +**payment services Requirement (R3)** -| Goal | Entry point | -|---|---| -| Understand A402 locally | [Local A402 Sample](../../code/samples/local-a402/README.md) | -| Run the interactive demo | [Machine Payment Showcase](../../code/web-client/alipay-ai-pay-showcase/README.md) | -| Integrate Alipay buyer capabilities | [Alipay Buyer Agent](../../integrations/alipay/buyer-agent/README.md) | -| Integrate an Alipay seller | [Alipay Seller Java](../../integrations/alipay/seller-java/README.md) | -| Validate an Alipay sandbox flow | [Alipay Validation](../../integrations/alipay/validation/README.md) | ++ The need for payment services addresses how the transaction results are translated into payments that meet the intent of User and that can be confirmed in User authorized Scope. ++ This category covers both the recognition of payments in real-time presence at User and the recognition of payments at User, initiated within the pre-established authorized boundary at Agent. At the same time, as collaboration between Agent increases, protocols also need to fit new payment scenarios such as Agent high frequency, autonomous small payments, etc. -Return to the [documentation index](../README.md). +**Trust service requirements (R4)** + ++ Trust service requirements are directed towards confidence-building, certification and governance-related matters in agentic commerce, which may include, inter alia, transaction certificates, identity management, reputation management, and credit association. + +# Protocol Design Goals and Principles +## Design Goals +Based on the analysis of Trust Requirements in Chapter 3, ACT is expected to achieve the following objectives at the level of protocol. + ++ **user intent may be expressed:** User Objectives, constraints and preferences in commercial activities can be expressed in a structured manner and serve as a common basis for follow-up commerce interaction, implementation of payments and validation of results. ++ **The authorized borders may specify:** The authority Agent to act User can be clearly defined and communicated, identified and verified in the follow-up process to avoid the implicit extension or abuse of the authorization Scope. ++ **The transaction process can be linked to:** From user intent, commerce interaction to payment execution, key links in the chain of transactions can be kept consecutively, enabling Participants to form a common understanding of the same transaction. ++ **Payable to implement appropriate:** The protocol supports payment requirements in different scenarios, such as User presence, User absence and Agent autonomous payment between Agent, and enables payment result compliance with User payment intent and authorization Scope. ++ **Key results can be validated by:** Critical events in business activities can provide a verifiable and retroactive record that provides a basis for dispute resolution, audit and subsequent governance. + +Together, these objectives form the overall orientation of the design of the ACT protocol, starting with user intent, subject to authorized boundaries, with trade links and payment execution as the main link, with the result being validated as a trust loop. + +## Design Principles +ACT for the Protocol Design Principles as follows. + ++ **Compatibility:** The protocol takes fully into account compatibility with existing commercial and payment infrastructure and prioritizes the use of designs coordinated with existing standards, interfaces and security mechanisms to reduce access and eco-refitting costs. ++ **Progressive evolution:** Given that agentic commerce is still in the process of sustainable development, protocol-building does not require a step-by-step approach, but a step-by-step refinement and upgrading based on industrial practices and landscape needs to avoid excessive advance design. ++ **Open:** The protocol does not bind a particular manufacturer, platform or technology warehouse, supports multiple modes of realization and multiple types of service provider access, and guarantees different ecological Participants interfaces under open conditions. ++ **Inclusiveness:** The protocol may refer to, absorb or accommodate other mature open protocols on specific modules, avoid duplication of construction and avoid creating a fragmented system of protocols. ++ **Portability:** The protocol maintains a combination of modular design features and minimizes unnecessary hidden reliance to support flexible combinations and independent evolution in different scenarios. ++ **Security and privacy priorities:** The protocol is designed to take fully into account security controls and privacy protection mechanisms, including, but not limited to, minimum privileges, access controls, encrypted transmissions, identification requirements, etc. ++ **Separation of entity from role:** By virtue of their role in the abstract of functions and responsibilities, a specific operational entity may assume one or more roles according to its own circumstances, thus enhancing the adaptability of the protocol to different business organizational patterns. + +# Overall Protocol Framework +## Overall Architecture Diagram +The ACT protocol framework uses the protocol stack structure of the sub-domain organization, consisting of Authorization & Delegation Domain, Commerce Interaction Domain, Payment Services Domain and Trust Services Domain. The domain contains several protocol modules that together support the full chain of expression, trade negotiation, and payment execution and results validation from user intent. The modules are interconnected, and they can evolve independently and be flexible, so ACT is not a single protocol, but a system of protocols for sustainable expansion. + +The modules listed in the figure below are the overall component view of the current version of the protocol. The official component name, number, object definition and cross-domain reference relationships for each domain are based on the corresponding domain specification document; the typical use scene for which the protocol is currently oriented can be found in the " Typical scene and business process " document. + +![](../assets/specification/act-2.1-protocol-framework.png) + +## Four Capability Domains and Primary Protocol Modules +### Authorization & Delegation Domain +**Positioning:** Authorization & Delegation DomainGuidance Principal (i.e. User where the intent is presented in the specific scene and the authority is granted) confers its commercial intent and operational authority on the complete process of Agent in a verifiable manner. It covers the period from Scope to Principal the expression of natural language intent, to Agent the holding of complete validity User Intent Authorization Credential and, accordingly, to represent Principal action in subsequent commerce interaction and payment execution. + +**Key protocol modules:** + ++ **Intentional acquisition and structured expression:** Regulates the process of receiving, semantic clarification, confirmation and structured expression of Principaloriginal intent, resulting in the Intent Structuring Result that can be cited in the subsequent authorization process. ++ **Issued User Intent Authorization Credential** Regulates the transformation of structured intent into a cross-domain verifiable process of issuance and signature authorization credential. ++ **Intent Authorization Credential Life cycle management** Code authorization credential for full life-cycle flow mechanisms from entry into force, temporary suspension, release from suspension, active revocation to expiry. + +### Commerce Interaction Domain +**Positioning**: Commerce Interaction DomainOrdinance Agent and Merchant, Merchant-side Agent or other Agent rules of interaction around the discovery, transmission of intent, content consultation, Payment Capability Negotiation and Cart Confirmation of goods or services. The goal is to achieve an efficient and accurate match and interface between user intent and goods services in a variety of interactive ways. + +**Key protocol modules:** + ++ **Merchant Catalog Interface**: Regulates Merchant the opening of interfaces to Agent structured goods or service catalogues to support Agent efficient access to information on goods or services. ++ **Intent Context Passage** Code Buyer Agent transmits Intent Context relevant to the current mandate to Merchant or to the platform to support more precise candidate, matching and dynamic pathways. ++ **Cart Confirmation**• Regulate the interactive process between buyers and sellers of confirmation of final commodity lists, amounts and the state of the transaction and preparation for the payment phase. ++ **Interaction between consultations and collaboration on services**: Code Agent interacts with Merchant, Merchant-side Agent or other counterparty regarding consultations and collaboration on transactions. In the current version, this module is reduced to Payment Capability Negotiation, and primarily regulates the ability of buyers and sellers to declare, match and consult with payment method, Payment Service Provider, interface end points and related load modes before payment is made. + +### Payment Services Domain +**Positioning** The main interactive process of payment is initiated to Payment Service Provider upon completion of Cart Confirmation. It covers payment request the structure, authorization of verification, execution of transactions, return of results and related status management to support uniform synonyms in different payment scenarios. + +**Key protocol modules:** + ++ **Payment Method Binding**: Guideline Principal to complete Payment Service Provider capacity to pay and to establish a process for Agent for the use of payment marks or other equivalent payment instrument quotations. ++ **Agent-specific Sub-account Management** Regulates the opening of an exclusive sub-account for a specific Agent and manages its accompanying authentication key and life cycle. ++ **Instant User Payment:** The process of prompt payment, completion of confirmation of payment and receipt of payment result is initiated in Principal real-time presence. ++ **User-directed Delegated Payment:** Code Principal for non-real-time presence, Buyer Agent is based on a valid Intent Authorization Credential process for initiating and accepting Payment Service Provider targeted commissioning. ++ **Autonomous Delegated Payment:** Regulation Principal Unaccompanied scene Buyer Agent for the autonomous conduct of multiple rounds of commercial decision-making and payment under Intent Authorization Credential within the authorized boundary. ++ **Payment access based on HTTP 402 (A402 payment process)** A universal payment access interface based on HTTP 402 between Buyer Agent the seller's service provider and Payment Service Provider can serve as a single access point to the above-mentioned payment scenario components. + +### Trust Services Domain +**Positioning:** Trust Services Domain is the confidence infrastructure level of the ACT protocol, which provides confidence services such as trusted attestation, agentcredit association, Agent identity management, Agent reputation management for agentic commerce ecological agentic commerce. Its role is to provide a common trust base for cross-institutional, cross-subject business collaboration and to support dispute management, risk identification and subsequent governance. The current version of the Focus Regulation trusted attestation is related to agentcredit association components, Agent identity management, reputation management, etc., can serve as an extension of the subsequent version. + +**Main Protocol Subsections:** + ++ **agentic commercetrusted attestation** Regulates the preservation of the record and long-term retention of key node information during agentic commerce interaction to provide an objective and verifiable factual basis for dealing with transactions disputes. ++ **agentcredit association:** The establishment of a Agent relationship with its associated subject credit association, the generation and mapping of associated credit statements, life-cycle management, search authorization and standardized certification provide a verifiable associated-credit reference for Agent when its own credit data are insufficient. ++ **Agent Identity management** Agent capacity for registration, authentication and analysis of identity for participation at commerce interaction, supporting the verification of identity and legality of the transaction at Participants. ++ **Agent Honorary management** To regulate the multi-dimensional evaluation and ongoing tracking of historical behaviour in Agent, provide a searchable basis for the credibility of the transaction Participants and support governance and restraint of the breach Agent. + +# Protocol Participants +## Primary Participants +### Principal +Principal is the author of the commercial intent and the authorized source of Agent commercial activity on its behalf. +Principal is responsible for expressing its own transaction objectives, constraints and preferences, and for confirming the intent or result, if necessary. Principal may also be directly involved in key points such as confirmation of payment in a real-time scenario. + +### Agent +Agent is the core executive role in the protocol to receive the intent and authorization of Principal and to complete subsequent business operations on behalf of Principal in the authorization Scope. +Depending on their location and responsibilities, Agent may be shown as Agent side Agent, Merchant-side Agent or as an automated executive with other Agent directly interacting in a given scene. +Agent may be involved in the process of interpretation of intent, transmission of information, matching of goods or services, negotiation of transactions, Cart Confirmation, initiation of payments and return of results. + +### Merchant or Service Provider +Merchant or Service Provider is the provider of goods, services or performance capacity and the provider of business in interaction agentic commerce. +Its main functions include opening the catalogue of goods or services, responding to Intent Context, participating in transaction consultations, confirming the outcome of the transaction and fulfilling the corresponding service or delivery obligations upon completion of the transaction. +In part achieved, Merchant or Service Provider could also deploy its own Merchant-side Agent to participate in automated interactive processes. + +### Payment Service Provider +Payment Service Provider is Participants for capacity to pay to provide and execute transactions for the purpose of carrying payment request, completing authorization to verify, executing payments and returning payment result. Its duties may include Payment Method Binding, immediate payment processing, commissioning payment processing, Agent payment support and related status management. +Payment-related payment proof, special sub-accounts or other payment base capabilities may be provided either by Payment Service Provider itself or by the associated professional service module. + +### Trust Service Provider +Trust Service Provider is Participants to provide identification, documentation, certification and related governance support capacity. +In the current version of the protocol, the focus of its responsibilities is on key event certificates, signature verification, chain anchoring inquiries and dispute resolution support. +Given the wide coverage of this type of service Scope, the current version of the protocol describes it as a uniform classification. As the protocol evolves and the industry division of labour is refined, the capacity can then be further broken down into more detailed service roles or types. + +## Participant Relationships +In a typical scenario, Principal first expresses its intent and completes its authorization to Agent, then commerce interaction undertakes commerce interaction with Merchant or Service Provider and initiates payment request with Payment Service Provider when payment conditions are in place; the key results can be Trust Service Provider to provide documentation, validation or other trust support services. This relationship reflects the basic synergy links from ACT, authorization and delegation, commerce interaction, payment implementation to trust service support. + +It should be noted that each Participants in this protocol is based on an abstract function and responsibility and does not foresee a correspondence between it and a specific operational entity. The same entity may assume one or more of the agreed roles under the operational model, and the same agreed roles may be assumed by different entities. Protocol Participants The division is mainly used to clarify the functional positioning, interaction and boundaries of responsibility of the parties in the ACT link, rather than to define the way in which the specific organization operates. + +# Terms and Normative Language +This chapter provides a uniform description of the core terms and normative expressions used in the ACT protocol, with a view to reducing differences in understanding between the different chapters and providing a consistent language base for the subsequent domain-specific rule descriptions. + +## Terminology +This chapter defines only the basic terms used for cross-domain overlap, with more detailed fields, status and reporting terms, which can be further refined in the corresponding domain document. + +|Terminology in Chinese|Terminology English|Explanation of terms| +| :--- | :--- | :--- | +|user intent|User Intent|Principal Objectives, conditions, preferences and related binding information in a business activity.| +|authorization credential|Authorization Credential|Proof used to carry and express the authorized relationship and its boundaries and for subsequent identification and verification.| +|commerce interaction|Commerce Interaction|Interactive process around the discovery of goods or services, transmission of intent, negotiation of transactions, Cart Confirmation, etc.| +|Transaction confirmation|Transaction Confirmation|(b) The process by which the buyer and the seller agree on the list of goods or services, the amount of money and the terms of the related transactions.| +|Payment execution|Payment Execution|(c) Initiate a process of payment request, complete authorization to verify, execute payments and return to payment result where payment conditions are in place.| +|trusted attestation|Trusted Attestation|The recording, validation and retention of critical events or results in a business activity in support of dispute resolution, audit and ex post facto traceability.| +|Cross-domain operational information|Cross-Domain Business Information|Business information transmitted, quoted or validated on an ongoing basis between authorization and delegation, commerce interaction, payment services and trust services.| + +## Normative Language +This Protocol adopts the following Normative Language: + ++ “SHALL (SHALL)” denotes a requirement that must be met; ++ “SHALL NOT (SHALL NOT)” denotes requirements that must be avoided; ++ “SHOULD (SHOULD)” indicates the recommended requirements; ++ “SHOULD NOT(SHOLD NOT)” indicates the requirement to be avoided; ++ “may” indicates an optional requirement. + +Existing protocol on the field: + ++ The word “necessary” indicates that the field must exist and have a valid value; ++ (a) “Conditions must” means that they must exist and have a valid value at the time the particular condition is established; ++ “Optional” indicates that the field is allowed to exist and that the value must be valid at the time of its existence. + +## Editorial Conventions +In order to maintain consistency throughout the text, this Protocol provides for the following common formulations in part: + ++ In the overview section of the protocol, use such role expressions as “Principal “Agent” “Merchant or Service Provider” “Payment Service Provider” “Trust Service Provider”. ++ In the context of the specific domain rule, a formulation such as “Buyer Agent” “Merchant-side Agent” “Payment Service Provider” may be used, but its meaning is consistent with the definition in this chapter. ++ SHALL Supplementary provisions apply when the specific domain document provides a more detailed description of a term, without conflict with the basic definition in this chapter. diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 51e6cd2..4d17b74 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -1,80 +1,203 @@ -# ACT 2.1 规范概览 +# ACT 2.1 协议概览 中文 | [English](overview.en.md) -> **状态：ACT 2.1 / Final** +# 引言 +在以信息检索和页面浏览为主的互联网商业阶段，用户是商业决策和支付行为的直接执行者。交易发生在用户与商业平台之间，用户通过界面实时查看商品、主动点击下单、逐笔确认支付。随着 AI 智能体技术的深度渗透，这一前提正在改变。智能体开始代表用户进行服务发现、商品比价、交易协商乃至支付执行，用户从"实时操作者"演变为"目标设定者与授权人"。 -ACT（Agentic Commerce Trust Protocol）定义智能体参与商业活动时的授权、交易、支付和信任协作语义。ACT 2.1 包含四个能力域，并以跨域组件连接完整业务流程。 +这一变化在带来效率提升的同时，也带来了传统商业与支付体系需要面对和解决的信任挑战： -## 规范性用语 ++ 首先，在智能体商业中，交易的责任主体发生了分离。用户负责提出目标和约束，智能体负责执行决策与操作，商户和支付服务方看到的则是被代理后的交易请求；“谁的意愿、谁的操作、谁应负责”不再像传统电商那样天然一致。 ++ 其次，交易依据从“用户实时确认”转变为“用户事前授权、智能体事后执行”。这意味着，系统不仅要回答一笔交易是否成功，更要回答这笔交易是否在用户原始授权边界内、是否忠实执行了用户意图、以及执行结果是否能够被追溯和解释。 ++ 最后，智能体的执行效率可能带来交易笔数和交易复杂度的显著提升，相应的争议、审计与风控压力也会同步放大。传统依赖人工逐笔复核的处理方式将难以适应规模化代理交易，商业系统需要可被自动化处理的标准化记录与验证机制。 + +总之，智能体商业带来的不是单一环节的安全问题，而是交易信任基础的整体迁移：信任不再建立在“人实时在场”的天然前提上，而必须通过一套可表达、可传递、可校验、可追溯的协议机制来显式建立。 + +ACT（Agentic Commerce Trust Protocol，智能体商业信任协议）是一套应对上述挑战而设计的应用层信任协议，覆盖从用户意图表达、委托授权、商业交互、支付执行到可信存证的完整商业链路。ACT 不替代现有的支付网络、商户系统或身份基础设施，而是在其之上提供一层面向智能体商业场景的信任编排能力，使各参与方能够在统一的协议框架下实现授权约束、交易一致性、支付控制与执行可验证性。 + +本文档为 ACT 协议总纲，定义协议的范围边界、诞生背景需求、设计目标与原则、整体框架、参与方角色及术语体系，是各域规范文档的上位参考文件。 + +# 范围 +本协议面向智能体参与商业交易的场景，规范用户、智能体、商户、支付服务方及相关信任服务提供方之间，为完成一笔可被授权、可被执行、可被验证的商业交易所需的应用层信任协作机制。 + +本协议主要规范以下四类协议活动： + ++ 委托授权：围绕用户意图表达、执行权限授予及其效力边界所形成的协议行为。 ++ 商业交互：围绕商品或服务发现、交易条件确认及支付前商业共识形成所发生的协议行为。 ++ 支付执行：围绕支付凭据使用、支付请求发起、支付结果返回及其与上游授权和交易确认关系保持一致所发生的协议行为。 ++ 可信存证：围绕关键商业事件记录、执行事实核验及后续争议处理支持所发生的协议行为。 + +本协议不规范以下内容： + ++ 智能体与用户之间的具体交互体验实现，包括前端界面、自然语言对话方式、提示词工程及任务编排策略。 ++ 商业参与方自身的经营管理规则，包括商品定价、库存管理、订单履约、售后处理及其他业务运营细节。 ++ 底层支付基础设施的资金清算与结算规则。 ++ 各参与机构内部的风控模型、反欺诈算法及内部审核策略等。 ++ 底层通信传输、基础设施部署、系统运维及其他不直接属于应用层信任协作范畴的技术实现细节。 + +# 智能体商业信任需求 +ACT 将智能体商业中的核心需求归纳为四类：委托授权（R1）、商业交互（R2）、支付服务（R3）和信任服务（R4）。四类需求分别对应智能体为何可以代表用户行动、如何形成交易共识、如何完成支付执行以及如何对执行结果进行验证。 + +上述四类需求共同构成 ACT 协议设计的基础，并对应后续四大能力域的划分。 + +![](../assets/specification/act-2.1-trust-requirements.png) + +**委托授权需求（R1）** + ++ 委托授权需求解决的是用户意图如何被可信表达，并成为后续商业行为的统一依据。 ++ 在用户实时在场场景下，结构化的意图表达有助于支撑后续商品匹配、交易协商和支付确认；在用户不实时在场场景下，这种表达进一步构成智能体自主执行的授权基础。核心包括两点：一是用户意图委托授权本身应可信，二是意图与授权边界应能够被结构化表达，以支持后续环节的传递、理解和校验。 + +**商业交互需求（R2）** + ++ 商业交互需求解决的是智能体如何高效、精准地完成用户意图与商品或服务之间的匹配与对接。 ++ 实现这一目标的方式可以包括：商户向智能体提供结构化的商品或服务目录信息，智能体向商户侧传递与本次任务相关的意图上下文，或结合两者形成更有效的匹配机制。在此基础上，智能体与商户之间还可以围绕询价、库存确认、条款确认和服务协同等过程开展交互。 + +**支付服务需求（R3）** + ++ 支付服务需求解决的是交易结果如何转化为符合用户支付意图、并能够确认处于用户授权范围内的支付行为。 ++ 该类需求既覆盖用户实时在场时的支付确认场景，也覆盖用户不在场时在预设授权边界内由智能体发起的支付场景。同时，随着智能体之间协作增多，协议还需要适配智能体间高频、自主的小额支付等新型支付场景。 + +**信任服务需求（R4）** + ++ 信任服务需求面向智能体商业中的信任建立、验证与治理相关事项，其范围可包括交易存证、身份管理、声誉管理、信用关联等方面。 -ACT 2.1 的中文规范采用以下要求强度，所有域正文和跨域连接规则均按本表解释： +# 协议设计目标与原则 +## 设计目标 +基于第 3 章的信任需求分析，ACT 希望在协议层面达成以下目标。 -| 中文用语 | 要求强度 | 英文等价用语 | -|---|---|---| -| 应、必须 | 强制满足 | `MUST` | -| 不应、不得 | 强制禁止 | `MUST NOT` | -| 宜 | 推荐满足 | `SHOULD` | -| 不宜 | 建议避免 | `SHOULD NOT` | -| 可、可以 | 可选 | `MAY` | ++ **用户意图可表达：**用户在商业活动中的目标、约束和偏好，能够以结构化方式表达，并作为后续商业交互、支付执行和结果验证的共同依据。 ++ **授权边界可明确：**智能体代表用户行动的权限范围能够被清晰界定，并在后续执行过程中得到传递、识别和校验，避免授权范围被隐式扩大或滥用。 ++ **交易过程可衔接：**从用户意图、商业交互到支付执行，交易链路中的关键环节能够保持前后衔接，使各参与方对同一笔交易形成一致理解。 ++ **支付执行可适配：**协议能够支持用户在场、用户不在场以及智能体间高频自主支付等不同场景下的支付需求，并使支付结果符合用户支付意图与授权范围。 ++ **关键结果可验证：**商业活动中的关键事件能够形成可核验、可追溯的记录，为争议处理、审计和后续治理提供依据。 -字段存在性中的“必备”表示字段必须存在且具有有效值；“条件必备”表示条件成立时必须存在且具有有效值；“可选”表示允许存在，存在时其值必须有效。英文翻译中的大写规范词必须保持相同要求强度；翻译差异仍以中文版本化正文为准。 +上述目标共同构成 ACT 协议设计的总体导向：以用户意图为起点，以授权边界为前提，以交易衔接和支付执行为主链路，以结果可验证为信任闭环。 -## 1. 四个能力域 +## 设计原则 +ACT 协议的设计原则如下。 -| 域 | 职责 | 规范入口 | -|---|---|---| -| ADD | 表达用户意图，签发并管理 Agent 可执行的授权凭证 | [委托授权域](authorization-delegation.md) | -| CID | 商品或服务发现、意图传递、支付能力协商和交易确认 | [商业交互域](commerce-interaction.md) | -| PSD | 支付工具、授权等级、支付执行、验证、状态和错误恢复 | [支付服务域](payment-services.md) | -| TSD | 为跨域事实提供可信存证和信用关联能力 | [信任服务域](trust-services.md) | ++ **兼容性：** 协议充分考虑与现有商业与支付基础设施的兼容，优先采用与现行标准、接口和安全机制相协调的设计，降低接入成本和生态改造成本。 ++ **渐进演进：** 考虑到智能体商业仍处于持续发展过程中，协议建设不求一步到位，而是根据产业实践和场景需求逐步细化与升级，避免过度超前设计。 ++ **开放性：** 协议不绑定特定厂商、平台或技术栈，支持多种实现方式和多类服务提供方接入，保障不同生态参与方在开放条件下进行对接。 ++ **包容性：** 协议在具体模块上可引用、吸收或兼容其他成熟开放协议，避免重复建设，也避免形成彼此割裂的协议体系。 ++ **可组合性：** 协议在模块设计上保持可组合特征，尽量减少不必要的隐式依赖，以支持不同场景下的灵活组合和独立演进。 ++ **安全与隐私优先：** 协议在设计中充分考虑安全控制与隐私保护机制，包括但不限于最小权限、访问控制、加密传输、身份认证等要求。 ++ **实体与角色分离：** 协议按照功能与权责抽象角色，具体业务实体可根据自身情况承担一个或多个角色，从而增强协议对不同业务组织形态的适应性。 -[典型场景](../flows/scenarios.md)说明四个域如何组合。场景说明与域正文冲突时，以对应域正文为准。 +# 协议总体框架 +## 总体架构框图 +ACT 协议框架采用分域组织的协议栈结构，由委托授权域、商业交互域、支付服务域和信任服务域构成。各域包含若干协议模块，共同支撑从用户意图表达、交易协商到支付执行和结果验证的完整链路。各模块既相互衔接，又可独立演进和灵活组合，因此 ACT 不是单一协议，而是一套可持续扩展的协议栈体系。 -## 2. 支付服务域组件 +下图所列模块为协议当前版本的总体组件视图。各域的正式组件名称、编号、对象定义和跨域引用关系，以相应域规范文档为准；协议当前面向的典型使用场景可参见《典型场景与业务流程》文档。 -| 类型 | 组件 | 含义 | -|---|---|---| -| 支付工具 | `PSD-PMT-BND` | 建立受限的支付工具引用，避免 Agent 接触原始账户凭证 | -| 账户隔离 | `PSD-AGT-SUB` | 为 Agent 提供可选的专属子账户与生命周期管理 | -| L1 | `PSD-PAY-INS` | 用户在场，资金处理前逐笔核身确认 | -| L2 | `PSD-PAY-DEL` | 商品、商户、金额等交易意图已明确，Agent 在授权范围内自动支付 | -| L3 | `PSD-PAY-AUP` | Agent 在任务、预算和策略边界内自主选择并支付 | -| 支付接入 | `PSD-PAY-A402` | 使用 HTTP 402 交换支付要求、支付证明和验证结果 | +![](../assets/specification/act-2.1-protocol-framework.png) -L1、L2 和 L3 回答“Agent 凭什么支付”；A402 回答“支付要求和证明如何交换”。A402 可以被三个授权等级引用，不属于其中任何一个等级。 +## 四大能力域与主要协议模块 +### 委托授权域 +**定位：**委托授权域规范委托人（即在具体场景中提出意图并授予权限的用户）将其商业意图和行动授权，以可验证的方式赋予智能体的完整过程。其覆盖范围从委托人表达自然语言意图开始，到智能体持有完整有效的用户意图授权凭证，并据此在后续商业交互和支付执行中代表委托人行动为止。 -## 3. A402 基本流程 +**主要协议模块：** -```text -Buyer Agent → Paid Service: request resource -Paid Service → Buyer Agent: 402 + Payment-Needed -Buyer Agent → Payment Service: authorized payment -Payment Service → Buyer Agent: payment result / proof -Buyer Agent → Paid Service: retry original request + Payment-Proof -Paid Service → Payment Service: verify proof -Paid Service → Buyer Agent: deliver resource -``` ++ **意图获取及结构化表达：**规范对委托人原始意图的接收、语义澄清、确认和结构化表达过程，形成后续授权流程可引用的意图结构化结果。 ++ **用户意图授权凭证签发**：规范将结构化意图转化为跨域可验证授权凭证的签发与签名过程。 ++ **意图授权凭证生命周期管理**：规范授权凭证从生效、临时挂起、解除挂起、主动吊销到到期失效的全生命周期状态流转机制。 -完整要求见 [A402 接入协议](a402.md)。商业交互到支付的连接规则见 [CID–PSD 协商](commerce-payment-negotiation.md)。 +### 商业交互域 +**定位**：商业交互域规范智能体与商户、商户侧智能体或其他智能体之间，围绕商品或服务发现、意图传递、内容协商、支付能力协商和购物车确认等环节所遵循的交互规则。其目标是在多种交互方式下，实现用户意图与商品服务之间的高效、精准匹配与对接。 -## 4. 协议与实现边界 +**主要协议模块：** + ++ **商品与服务目录接口**：规范商户向智能体开放结构化商品或服务目录的接口要求，支持智能体高效获取商品或服务信息。 ++ **意图上下文传递**：规范买方智能体向商户或平台传递与当前任务相关的意图上下文，以支持更精准的候选推荐、匹配和动态路由。 ++ **购物车确认**：规范买卖双方对最终商品清单、金额和交易状态进行确认，并为进入支付阶段做好准备的交互过程。 ++ **服务协商与协作交互**： 规范智能体与商户、商户侧智能体或其他交易对手之间围绕交易达成所开展的协商与协作交互。当前版本中，本模块先收敛为支付能力协商，主要规范买卖双方在支付前对可用支付方式、支付服务方、接口端点及相关载荷模式进行能力声明、匹配与协商。 + +### 支付服务域 +**定位**：支付服务域规范智能体在完成购物车确认后，向支付服务方发起支付的主要交互过程。其覆盖范围包括支付请求构造、授权核验、交易执行、结果返回以及相关状态管理等环节，以支持不同支付场景下的统一语义表达。 + +**主要协议模块：** + ++ **支付方式绑定**：规范委托人向支付服务方完成智能体支付能力开通，并为智能体建立可用支付标记或其他等价支付工具引用的过程。 ++ **智能体专属子账户管理**：规范为特定智能体开立专属子账户，并对其配套验证密钥及生命周期进行管理。 ++ **用户即时支付：**规范委托人实时在场场景下，发起即时支付、完成支付确认并接收支付结果的过程。 ++ **用户定向委托支付：**规范委托人不实时在场场景下，买方智能体基于有效意图授权凭证发起定向委托支付并接受支付服务方核验的过程。 ++ **自主化委托支付：**规范委托人不在场场景下，买方智能体依据授权边界内的意图授权凭证自主开展多轮商业决策与支付的过程。 ++ **基于 HTTP 402 的支付接入（A402支付流程）**：规范买方智能体、卖方服务方与支付服务方之间基于 HTTP 402 的通用支付接入交互机制，可作为上述支付场景组件的统一接入入口。 + +### 信任服务域 +**定位：**信任服务域是 ACT 协议的信任基础设施层，为智能体商业生态中的参与方提供可信存证、智能体信用关联、智能体身份管理、智能体声誉管理等信任服务。其作用是为跨机构、跨主体的商业协作提供共同信任基础，并支撑争议处理、风险识别和后续治理。当前版本重点规范可信存证与智能体信用关联相关组件，智能体身份管理、声誉管理等能力可作为后续版本的扩展方向。 + +**主要协议子篇：** + ++ **智能体商业可信存证**：规范对智能体商业交互过程中的关键节点信息进行防篡改记录与长期留存，为交易纠纷处理提供客观、可验证的事实依据。 ++ **智能体信用关联：**规范智能体与其关联主体之间信用关联关系的建立、关联信用声明的生成与映射、生命周期管理、查询授权与标准化验证，为智能体在自身信用数据不足时提供可验证的关联信用做为参考。 ++ **智能体身份管理**：规范参与商业交互的智能体身份注册、认证与解析能力，支持交易参与方对智能体身份归属和合法性进行验证。 ++ **智能体声誉管理**：规范对智能体在商业交互中的历史行为进行多维度评价与持续追踪，为交易参与方提供可查询的信誉依据，并支持对失信智能体进行治理与约束。 + +# 协议参与方 +## 主要参与方 +### 委托人 +委托人是商业意图的提出者，也是智能体代表其开展商业活动的授权来源。 +委托人负责表达自身的交易目标、约束条件和偏好，并在需要时对相关意图或结果进行确认。在用户实时在场的场景下，委托人还可以直接参与支付确认等关键环节。 + +### 智能体 +智能体是协议中的核心执行角色，用于接收委托人的意图与授权，并在授权范围内代表委托人完成后续商业操作。 +根据所处位置和职责不同，智能体可以表现为用户侧智能体、商户侧智能体，或在特定场景中与其他智能体进行直接交互的自动化执行主体。 +智能体可以参与意图解析、信息传递、商品或服务匹配、交易协商、购物车确认、支付发起以及结果回传等环节。 + +### 商户或服务提供方 +商户或服务提供方是商品、服务或履约能力的提供者，是智能体商业交互中的业务供给方。 +其主要职责包括开放商品或服务目录、响应意图上下文、参与交易协商、确认交易结果，并在交易完成后履行相应服务或交付义务。 +在部分实现中，商户或服务提供方也可以部署自身的商户侧智能体，以参与自动化交互流程。 + +### 支付服务提供方 +支付服务提供方是负责支付能力提供与交易执行的参与方，用于承接支付请求、完成授权核验、执行支付并返回支付结果。其职责可包括支付方式绑定、即时支付处理、委托支付处理、智能体间支付支持以及相关状态管理等。 +与支付相关的支付凭证、专用子账户或其他支付基础能力，可以由支付服务提供方自行提供，也可以由其关联的专业服务模块提供。 + +### 信任服务提供方 +信任服务提供方是负责提供身份、存证、验证及相关治理支撑能力的参与方。 +协议当前版本中，其职责重点包括关键事件存证、签名校验、链上锚定查询以及争议处理支持等。 +考虑到该类服务覆盖范围较广，协议当前版本对其作统一归类描述。随着协议演进和产业分工细化，相关能力后续还可以进一步拆分为更细的服务角色或服务类型。 + +## 参与方关系 +在典型场景下，委托人首先向智能体表达意图并完成授权，随后智能体与商户或服务提供方开展商业交互，并在具备支付前提后向支付服务提供方发起支付请求；相关关键结果可由信任服务提供方提供记录、验证或其他信任支撑服务。这一关系体现了 ACT 从委托授权、商业交互、支付执行到信任服务支撑的基本协同链路。 + +需要说明的是，本协议中的各参与方系基于功能与职责抽象的协议角色，不预设其与具体业务实体之间的一一对应关系。同一实体可以根据实际业务模式承担一个或多个协议角色，同一协议角色也可以由不同实体分别承担。协议参与方的划分主要用于明确各方在 ACT 链路中的功能定位、交互关系和责任边界，而不用于限定具体的组织实施方式。 + +# 术语与规范性用语 +本章对 ACT 协议中使用的核心术语和规范性表述进行统一说明，以减少不同章节之间的理解偏差，并为后续各域的具体规则描述提供一致的语言基础。 + +## 术语 +本章仅定义跨域复用的基础术语，更细的字段、状态和报文术语，可在相应域文档中进一步细化。 + +| 术语中文 | 术语英文 | 术语解释 | +| :--- | :--- | :--- | +| 用户意图 | User Intent | 委托人在某一商业活动中的目标、条件、偏好及相关约束信息。 | +| 授权凭证 | Authorization Credential | 用于承载和表达授权关系及其边界、并可供后续环节识别和校验的凭据。 | +| 商业交互 | Commerce Interaction | 围绕商品或服务发现、意图传递、交易协商、购物车确认等环节开展的交互过程。 | +| 交易确认 | Transaction Confirmation | 买卖双方就商品或服务清单、金额及相关交易条件形成一致结果的过程。 | +| 支付执行 | Payment Execution | 在具备支付前提的情况下发起支付请求、完成授权核验、执行支付并返回支付结果的过程。 | +| 可信存证 | Trusted Attestation | 对商业活动中的关键事件或结果进行记录、校验和留存，以支持争议处理、审计和事后追溯。 | +| 跨域业务信息 | Cross-Domain Business Information | 在委托授权、商业交互、支付服务和信任服务之间被持续传递、引用或验证的业务信息。 | + +## 规范性用语 +本协议采用以下规范性用语： -- `docs/specification/` 定义 ACT 2.1。 -- `code/schemas/` 提供 JSON Schema、fixtures 和测试辅助资产。 -- `integrations/` 连接具体产品。 -- `code/samples/` 和 `code/web-client/` 展示实现方式和业务流程。 ++ “应 (SHALL)”表示必须满足的要求； ++ “不应 (SHALL NOT)”表示必须避免的要求； ++ “宜 (SHOULD)”表示推荐满足的要求； ++ “不宜 (SHOULD NOT)”表示建议避免的要求； ++ “可 (MAY)”表示可选满足的要求。 -机器资产、产品代码和 Demo 不得增加或修改协议要求。支付宝字段、API、签名、开户和沙箱行为以 [AIPay 官方资料](https://aipay.alipay.com/callpay)为准，不属于 ACT 规范。 +关于字段存在性约定： -## 5. 开发者入口 ++ “必备”表示字段必须存在且具备有效值； ++ “条件必备”表示在特定条件成立时必须存在且具备有效值； ++ “可选”表示字段允许存在，存在时值必须有效。 -| 目标 | 入口 | -|---|---| -| 本地理解 A402 | [Local A402 Sample](../../code/samples/local-a402/README.md) | -| 运行交互 Demo | [Machine Payment Showcase](../../code/web-client/alipay-ai-pay-showcase/README.md) | -| 接入支付宝买方能力 | [Alipay Buyer Agent](../../integrations/alipay/buyer-agent/README.md) | -| 接入支付宝卖方能力 | [Alipay Seller Java](../../integrations/alipay/seller-java/README.md) | -| 验证支付宝沙箱链路 | [Alipay Validation](../../integrations/alipay/validation/README.md) | +## 表述约定 +为保持全文一致性，本协议对部分常用表述作如下约定： -返回[文档导航](../README.md)。 ++ 在协议概览部分，使用“委托人”“智能体”“商户或服务提供方”“支付服务提供方”“信任服务提供方”等角色表述。 ++ 在涉及具体域规则时，可根据上下文使用“买方智能体”“商户侧智能体”“支付服务方”等更贴近场景的表述，但其含义应与本章定义保持一致。 ++ 当具体域文档对某一术语作出更细化说明时，应在不与本章基本定义相冲突的前提下适用其补充规定。 diff --git a/docs/specification/payment-services.en.md b/docs/specification/payment-services.en.md index 350bc0f..d2456bf 100644 --- a/docs/specification/payment-services.en.md +++ b/docs/specification/payment-services.en.md @@ -2,239 +2,646 @@ [中文](payment-services.md) | English -> **Chinese source publication: ACT 2.1 Specification / Final / Normative** -> **Version baseline: 2026-08-11 (UTC+8).** This document is the official informative English translation of the normative ACT 2.1 PSD text. The terms **MUST**, **MUST NOT**, **SHOULD**, and **SHOULD NOT** preserve the corresponding requirement strengths from the Chinese publication. Product compatibility and conformance still require independent evidence. -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +# Scope +## Domain Positioning +Payment Services Domain (Payment Services Domain, PSD) provides for Agent to initiate interactive rules for payment, acceptance of payment verification, acquisition of payment result and treatment of the related state after completion of the pre-payment commercial confirmation, providing a uniform, verifiable, compatible payment services synonym for the payment execution phase in agentic commerce. -## 1. Scope and boundaries +## Domain Responsibilities +This domain covers the following: -The Payment Services Domain (PSD) describes payment-tool preparation, account isolation, payment-authorization checks, payment execution, result return, credential validation, and related state semantics after commercial confirmation. ++ Payment Method Binding and payment instrument Reference management; ++ Agent-specific Sub-account and its associated certification capacity management; ++ Universal payment access interactive (PSD-PAY-A402) based on HTTP 402; ++ Three types of payment scenarios under different attendance and autonomy: Instant User Payment, User-directed Delegated Payment and Autonomous Delegated Payment; ++ payment request Structure, payment instrument citation, authorization to verify, payment execution and status return; ++ Pays the critical objects, state semantics and cross-domain reference relationships required for the implementation phase. -This domain covers: +The following are not regulated in this domain: -- payment-method binding and payment-tool references; -- Agent-dedicated sub-accounts and supporting verification capabilities; -- the INS/L1, DEL/L2, and AUP/L3 payment scenarios; -- A402 payment requirements, Proof, validation, and resource-recovery access; -- payment requests, results, states, errors, and cross-domain references. ++ Merchant Internal order performance, inventory disposal and business systems achieved; ++ (b) Information on the ground liquidation network, the processing of funds for settlement and the internal mechanisms of the corridor; ++ Payment Service Provider Internal risk control strategy achieved, routed strategy and account core system achieved. -This domain does not define merchant-internal inventory and fulfillment systems, underlying clearing networks, or PSP-internal risk and routing implementations. It also does not redefine Alipay onboarding, sandbox, or API operations. +# The list of components and relationships in this field +## Component Overview +Payment Services Domain consists of six protocol components, divided into payment access programme components and payment scene components, which together complete the full chain from payment instrument readiness, account segregation and payment authorization to payment implementation and outcome status management. -Version and implementation boundaries: +Payment scenario component: -1. This document is the versioned ACT 2.1 text in this release. The [Payment Services Domain](https://www.act-protocol.com/documentation/payment) on the ACT Protocol website is an unversioned informative reference. -2. `PSD-PAY-A402` is an independent access component that INS/L1, DEL/L2, and AUP/L3 can use. -3. Alipay channel fields, APIs, signatures, and sandbox flows belong only to the Alipay implementation layer and MUST NOT rewrite this specification. -4. The public package does not restore `specs/2.0`, legacy Schemas, or legacy examples. Wire details not defined by ACT 2.1 are non-normative implementation artifacts or future-version work. ++ **PSD-PMT-BND: Payment Method Binding.** Responsible for regulating Principal the process of completing Payment Service Provider capacity to pay and establishing Agent payment marks or equivalent payment instrument quotations. ++ **PSD-AGT-SUB: Agent-specific Sub-account Management.** Responsible for regulating the opening of an exclusive sub-account with a financial isolation capability for a specific Agent and managing its accompanying authentication key and life cycle process. ++ **PSD-PAY-INS: Instant User Payment.** Responsible for regulating the process of prompt payment, completion of confirmation of payment and receipt of payment result in real-time presence. ++ **PSD-PAY-DEL: User-directed Delegated Payment.** Responsible for regulating the process in which Buyer Agent initiates directed delegated payment based on a SPECIFIED mode IAC and accepts PSP verification when Principal is not present in real time. ++ **PSD-PAY-AUP: Autonomous Delegated Payment.** Responsible for regulating the process in which Buyer Agent autonomously conducts multiple rounds of commercial decision-making and payment within the authorization boundary based on a `BOUNDED` mode IAC when Principal is not present in real time. -## 2. Component overview +Payment access programme components: -| Component | Type | Normative responsibility | Normative boundary | -|---|---|---|---| -| `PSD-PMT-BND` | Payment tool | Establish a restricted payment-tool reference and manage its valid state | A wallet-aggregation product is not equivalent to this entire component | -| `PSD-AGT-SUB` | Account isolation | Establish an optional Agent-dedicated sub-account and verification-key lifecycle | Optional; not required for AUP | -| `PSD-PAY-INS` | L1 scenario | Immediate payment with the user present and confirming each payment | May use A402, MCP, or API access | -| `PSD-PAY-DEL` | L2 scenario | Directed delegated payment for an explicitly identified subject | May use A402, MCP, or API access | -| `PSD-PAY-AUP` | L3 scenario | Autonomous delegated payment under a `BOUNDED` IAC | Defines authorization and payment semantics; access interactions are carried by A402 or another component | -| `PSD-PAY-A402` | Access protocol | HTTP 402, three Header types, payloads, state, idempotency, and error recovery | Independent component usable by INS, DEL, and AUP | ++ **PSD-PAY-A402: payment access based on HTTP 402.** General payment access based on HTTP 402 status code is interactive and can be quoted as required by each payment scenario component. -## 3. Core objects and cross-domain references +## Core Object & Identification +Payment Services Domain uses a standard core set of objects and identifiers to describe key information for the payment implementation phase. The core objects of the field and their roles can be summarized as follows. -| Object or identifier | Normative semantics | Produced by / source | Primary consumer | -|---|---|---|---| -| Payment-tool reference | Restricted payment instrument that does not reveal raw account data; may be a token, sub-account identifier, or equivalent credential | `PSD-PMT-BND`, `PSD-AGT-SUB` | INS, DEL, AUP | -| Merchant order information | Merchant order number and necessary context correlating the transaction subject, amount, and payment handling | Commerce interaction or Seller Service | All three payment scenarios | -| Payment-capability negotiation result | Selected payment method, PSP, endpoint, and method Schema | `CID-PCA-NEG` or equivalent mechanism | A402, DEL, AUP, and INS when needed | -| IAC | Delegated-authorization boundary | `ADD-IAC-ISS` | DEL, AUP | -| `delegation_id` | Stable correlation for one delegated-authorization lifecycle | Authorization & Delegation Domain | DEL, AUP, later evidence | -| Payment request | Combination of transaction, tool, amount, time, unique request identifier, and integrity material | INS, DEL, AUP | PSP or payment acceptor | -| Payment result | PSP-provided transaction number, order correlation, state, and time | PSP | Buyer, merchant, later evidence | -| Payment requirement / Proof / validation result | Resource-payment requirement, payment evidence, and validation or recovery result | A402 and the payment method | Buyer, seller, PSP | +|** Object or Identification**|** Meaning**|** Mainly Generate Location**|** Main Use Location**| +| --- | --- | --- | --- | +|payment instrument Reference|Available references to the payment instrument used to identify payment instruments at the time of payment may be shown as proof of payment mark, sub-account mark or other equivalent payment instrument|PSD-PMT-BND、PSD-AGT-SUB|PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP、PSD-PAY-A402| +|Merchant side order number|Order-level confirmation result from Commerce Interaction Domain; the order number identifies the product information, amount, and other information for the current transaction.|CID-CART-CFM|Payment Services Domain Payment execution components| +|Results Payment Capability Negotiation|Pre-payment capability alignment results from Commerce Interaction Domain to determine the payment method, Payment Service Provider interface endpoint and load mode used for this payment|CID-PCA-NEG|PSD-PAY-A402, PSD-PAY-DEL, PSD-PAY-AUP and, if necessary, PSD-PAY-INS| +|User Intent Authorization Credential(IAC)|Intent Authorization Credential issued Authorization & Delegation Domain for the expression of authorized boundaries for commissioning or autonomous payment|ADD-IAC-ISS|PSD-PAY-DEL、PSD-PAY-AUP| +|`delegation_id`|authorization and delegation voucher life-cycle markers for stable association with the same authorization chain in payment execution, authorization verification and subsequent certificates|ADD-IAC-ISS|PSD-PAY-DEL、PSD-PAY-AUP| +|payment request|Buyer Agent Standardized payment execution request for the construction of Payment Service Provider to carry transaction confirmation information, payment instrument reference, time stamp, request unique identification and necessary signature material.|PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP|PSP or related payment recipient| +|payment result|Payment Service Provider Returned payment execution results, usually including trade flow numbers, associated order markings, trade status and transaction time information|PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP|Buyer Agent, Merchant side and follow-up certificate processing| -A conventional merchant-platform order flow connects commerce interaction and payment through a merchant order number. With A402, the seller MAY return order or resource identifiers such as `out_trade_no` and `resource_id` in `Payment-Needed`. ACT 2.1 does not require the three payment-scenario requests to carry a complete cart and does not define `Payment-Needed` as a complete `CID-CART-CFM` object. +## Dependence and Cross-domain Reference +PSD-PMT-BND and PSD-AGT-SUB provide the basis of payment instrument for the payment of implementation, respectively: the former provides payment instrument quotations for Principal main account, and the latter provides a specific Agent financial segregation account and its authentication key. -## 4. `PSD-PMT-BND`: payment-method binding +Before initiating payment, PSD-PAY-INS, PSD-PAY-DEL, and PSD-PAY-AUP reference the transaction confirmation result produced by Commerce Interaction Domain; PSD-PAY-DEL and PSD-PAY-AUP additionally reference User Intent Authorization Credential provided by Authorization & Delegation Domain. -### 4.1 Purpose and prerequisites +When the counterparty is the seller Agent or payment method to be consulted dynamically, PSD-PAY-DEL and PSD-PAY-AUP may also refer to Payment Capability Negotiation resulting from CID-PCA-NEG to determine payment method, Payment Service Provider and interface endpoints. -This component establishes a usable payment-tool reference for an Agent, allowing it to pay within authorization boundaries without directly holding the delegator's raw payment-account information. +PSD-PAY-A402 as a universal payment access option can be cited as required by PSD-PAY-INS, PSD-PAY-DEL, PSD-PAY-AUP. -Prerequisites: +Under the scenario Agent-specific Sub-account, the generation, authentication key binding and key failure processing of payment authorizations can be achieved by relying on the key management and security enforcement capabilities provided by ASL. -- the delegator actively expresses the intention to enable payment for a specified Agent; -- the Agent has an identity that the account service provider or PSP can identify consistently; -- the provider can verify the delegator, generate a reference, manage the binding, and query its valid state. +Trust Services Domain Harmonized rules for maintaining the governance of the type and certificate of events related to payments; Payment Services Domain used only the incident identifier in the relevant components and did not define the structure of the event or the governance mechanism in its own domain. -### 4.2 Flow +# PSD-PMT-BND: Payment Method Binding +## Overview +Payment Method Binding (Payment Method Binding, PSD-PMT-BND) provides for Principal completion of capacity to pay at Payment Service Provider or account service and establishment of basic processes and requirements for Agent to be quoted at payment instrument. -1. The delegator actively initiates enablement and is redirected or connected to a trusted confirmation interface of the account service provider or PSP. -2. The provider verifies the delegator's identity and binding intent and displays the Agent and authorization scope to be bound. -3. After successful verification, the provider generates a payment token or equivalent reference bound to the real account, Agent identity, and limits such as validity, amount, and merchant scope. -4. Only the restricted reference is delivered to the Agent; raw account credentials are not delivered. -5. On every subsequent payment, the PSP rechecks the reference state and its binding to the initiating Agent. +The objective of this component is to enable Agent to complete the payment using the authorized payment instrument in the execution of subsequent payments while avoiding direct exposure to Agent of the original payment account information. -Identity-verification failure, unregistered Agent identity, account or amount restrictions, and reference-generation failure MUST NOT produce a valid reference that can continue to payment. Later payment checks MUST detect expiration, freezing, closure, or identity mismatch. +In the Agent payment scenario, agent SHALL NOT holds directly or has access to Principal original payment account information. -### 4.3 Product boundary +## Participants and prefix +This component involves the following Participants: Principal, Buyer Agent and Payment Service Provider or account service providers that provide Payment Method Binding services. -Enablement, authorization, checking, and unbinding in the Alipay AI wallet form an aggregated product lifecycle. An Alipay integration MAY map relevant results to “payment tool ready,” but MUST NOT claim that the complete wallet product is identical to a `PSD-PMT-BND` protocol message. +Before entering this component, SHALL satisfies the following preconditions. -## 5. `PSD-AGT-SUB`: Agent-dedicated sub-account ++ Effective interaction with Buyer Agent has been established and there is a clear desire to open up capacity to pay for Agent. ++ Buyer Agent SHALL have an identification that can be identified and bound by Payment Service Provider or account service. ++ Payment Service Provider or account service SHALL have the capability of Principal identification, payment instrument reference generation, binding relationship management and validity verification. -### 5.1 Purpose and prerequisites +## Basic processes +Payment Method Binding SHOULD was activated by Principal. Principal Following the launch of the Agent platform, the SHOULD platform directed the request to Payment Service Provider or the account service side to complete identification and binding confirmation. -This component provides account-level funds isolation for a highly autonomous Agent. It is an optional risk-control mechanism for DEL/AUP, not an A402 transport and not mandatory for every AUP implementation. +**The first step is identification and confirmation of will.** Payment Service Provider or account service provider should verify Principal identification and binding willingness, which may include biometric recognition, payment passwords, dynamic authentication codes or other means of realizing support. During the verification process, Payment Service Provider or account service provider SHALL clearly shows Principal this binding fiduciary Agent identification and associated authorization Scope to ensure that the binding is based on an informed confirmation. -Prerequisites: +**The second step is to generate and release payment instrument references** Payment Service Provider or the account service generate a payment mark or other equivalent payment instrument quotation and bind it to Principal real funds accounts, Agent fiduciary identification and related restrictions. The relevant restrictions may include the validity period, monetary ceiling and other restrictions on the use of the party ' s definition. Once the attachment is completed, Payment Service Provider or the account service will send it to Buyer Agent under payment instrument quotation for use as a payment tool in payment request. -- the delegator actively requests a separate funds boundary for a specified Agent; -- the Agent has a stable, bindable identity; -- the PSP supports sub-account opening, funding or limits, freezing, unfreezing, closure, and state queries. +## Processing of requests +The payment instrument citation (payment mark), SHALL formed by this component, stabilizes the association with the following information: Principal true financial account, Agent fiduciary identifier, and the subject ' s own state of validity. -### 5.2 Management and key requirements +Payment Service Provider or the account service provider can verify the validity of the payment instrument reference and its consistency with the identity of Buyer Agent for initiating the payment at subsequent payment request. -- A sub-account MUST bind the delegator, Agent identity, and current state. -- The delegator MAY fund it or set an available limit; the Agent can pay only within the available balance or limit. -- A payment MAY submit the sub-account identifier and authorization material generated by a dedicated key. -- The PSP MUST validate the sub-account state, Agent binding, and authorization material together. -- When the sub-account is frozen or closed, or the Agent identity becomes invalid, associated verification keys MUST become invalid as well. -- Keys SHOULD be generated and used in a protected environment. The relevant security capability determines the specific KMS or secure-execution implementation; PSD does not prescribe an algorithm or hardware. +If the reference to payment instrument is expired, expired, or does not match the current identity of Agent, Payment Service Provider or the account server SHALL NOT continues to accept payment request. -Failure results MUST at least distinguish account-opening or state failure, insufficient balance or limit, binding mismatch, invalid authorization material, and invalidated keys. A failure MUST NOT bypass the main-account isolation boundary and continue debiting funds. +## Failed to process +Payment Service Provider or account service SHALL rejects this binding request and returns the identifiable failure result if the identification, payment instrument reference generation or binding relationship has failed. -## 6. `PSD-PAY-INS`: instant payment / L1 +The semantic SHOULD of the cause of the failure covers at least the failure of identification, the failure of Agent identification, the excess of account amount and other anomalies that make payment instrument citation impossible. -### 6.1 Scenario and prerequisites +The failure of binding SHALL NOT gives rise to valid payment instrument quotations that can continue to be paid for. -INS applies when the user is present in real time and decides on one payment. Its authorization basis is the user's confirmation for that payment, obtained by the PSP before funds processing; a pre-issued IAC is not required. +The established binding relationship is also recognized as not available in the subsequent payment verification if it has lapsed, frozen or cancelled. -Before the flow begins: +# PSD-AGT-SUB: Agent-specific Sub-account Management +## Overview +Agent-specific Sub-account Management (Agent-Dedicated Sub-Account Management, PSD-AGT-SUB) provides for the opening of an exclusive sub-account with financial isolation capability for a specific Agent, along with its accompanying certification key binding and life-cycle management requirements. +The objective of this component is to provide a mechanism of account-level risk segregation for Agent, which is more autonomous, so that Principal main account is not directly exposed to the payment risk of Agent autonomous execution. -- preflight commerce rules and cart confirmation have been completed and merchant order information is available; with A402, order or resource identifiers may instead be obtained from `Payment-Needed`; -- the Agent holds a valid payment-tool reference produced by `PSD-PMT-BND`; -- the PSP can validate the Agent, request integrity, and payment-tool reference and can provide a user-confirmation interface; -- when A402, MCP, or an API is used, the selected access approach has been determined. +## Participants and prefix +This component covers the following: Participants: Principal, Buyer Agent and Payment Service Provider for the opening, validation and management of sub-accounts. -The payment request uses the merchant order number and necessary payment facts such as amount and currency. A complete cart is not a payment-request field specified by this component. An implementation MUST NOT invent product-upload fields merely because the preceding flow included cart confirmation. +Before entering this component, SHALL satisfies the following preconditions. -### 6.2 Five-step flow ++ Principal has clearly expressed a desire to establish separate payment boundaries for specific Agent funds. ++ Buyer Agent SHALL already has a stable identifier that can be identified and bound; under the exclusive Agent scenario, the identity is usually more closely tied to Principal equipment, account number or operating environment. ++ Payment Service Provider SHALL have basic managerial capacity for the opening, filling, freezing, unfrozen, write-off and status queries of sub-accounts. -1. **Payment preparation:** a conventional merchant-platform order flow obtains a merchant order number; an A402 flow obtains identifiers such as `out_trade_no` and `resource_id` from `Payment-Needed`. -2. **Construct and send the instant-payment request:** correlate at least a unique request identifier, merchant order, payment-tool reference, amount, currency, timestamp, Agent identity, and a signature over critical facts. -3. **PSP baseline validation:** check replay protection, freshness, Agent signature, tool state, and identity binding. On failure, user confirmation MUST NOT begin. -4. **Per-payment user confirmation:** display amount, currency, payee, and payment method. Identity and authorization confirmation for this payment MUST complete before funds processing. The PSP determines the concrete identity-verification method. -5. **Payment execution and state return:** the PSP debits or reserves funds, returns transaction number, order, state, and time to the buyer, and SHOULD also notify the merchant. +## Sub-account management requirements +An Agent-specific Sub-account SHOULD be opened at the Principal's initiative. -Resource access after payment is not a sixth INS payment step. With A402, the Buyer retries the original resource request with `Payment-Proof`, and the seller validates it before delivery. A conventional merchant-platform order flow fulfills according to its own interface rules. +Payment Service Provider complete SHALL identification and establish a binding relationship between sub-account, trusted Agent identification and associated authentication keys during opening. -### 6.3 Handling and error semantics +Once a sub-account has been opened, Principal may be recharged or made available to enable Agent to be paid within the established balance or amount Scope. -The amount, currency, order, and information displayed to the user MUST be consistent with the confirmed transaction. Error semantics SHOULD at least include: +In the follow-up payment process, the Buyer Agent portable sub-account identification and the corresponding authorization of payment is initiated, while Payment Service Provider is verified and processed on the basis of the binding relationship and the status of the account. -| Category | Handling and recovery | -|---|---| -| Duplicate request | Do not replay payment directly; first query the existing result or start a new business request with a new request identifier | -| Expired request | Confirm that the transaction remains valid, then create new time context | -| Invalid Agent signature or integrity | Repair identity, key, or signature material before retrying | -| Invalid payment tool or identity mismatch | Rebind or choose another valid tool; do not open the confirmation interface | -| Amount or order differs from the confirmation result | Reconfirm the transaction; do not silently rewrite it | -| User cancellation, identity-verification failure, or timeout | Do not debit; product policy determines whether confirmation can be retried | -| Payment-execution failure or unknown result | Query the authoritative result first; a timeout MUST NOT directly create a second payment | +Payment Service Provider SHALL support freezing or write-off of sub-accounts when wind abnormality triggers, Principal voluntary application or Agent identity lapses. -## 7. `PSD-PAY-DEL`: directed delegated payment / L2 +After the sub-account has been cancelled or invalidated, the relevant authentication key is also SHALL synchronized to expire and SHALL NOT continues to be used for subsequent payments. -### 7.1 Scenario and prerequisites +## Exclusive Key Tie +The sub-account SHOULD contain an exclusive authentication key to support a valid authentication of the authorization of payment to the sub-account. The authentication key may be an asymmetric or symmetrical program; it may only be achieved by selecting the applicable mode in accordance with security requirements and conditions of deployment. -DEL expresses the L2 pattern in which a person first determines an explicit subject and the Agent executes. The user MAY be absent during execution and per-payment identity verification is not required. The authorization basis is an IAC that remains valid at execution time. +When the sub-account is opened, the relevant key or authentication material SHOULD be generated in a protected enforcement environment and is bound to the sub-account identifier for registration as the basis for subsequent validation. -Prerequisites: +In the subsequent payment process, Buyer Agent may be based on the authentication key to generate a message authorizing payment, Payment Service Provider to verify that payment request is consistent with the current sub-account and its binding Agent. -- the user has confirmed an explicit subject and an effective IAC has been issued; -- a merchant order and transaction confirmation exist; -- the Agent holds a payment-tool reference, or an available dedicated sub-account and authorization material; -- the A402, MCP, or API access approach has been selected; -- identity, connection, authorization, and key implementations support signatures, binding, and IAC validation. +When the sub-account is frozen or cancelled, the authentication key associated with the sub-account is also disabled by SHALL; after the sub-account has lapsed, Payment Service Provider SHALL NOT continues to receive payment request. -### 7.2 Four-step flow +For the bottom security mechanism for key generation, call for protection and disablement, this component is not repeatedly defined for practical realization; the capability can be supported by the ASL security enforcement and key management capability, with corresponding modules `ASL-INF-SEE` and `ASL-INF-KMS`. -1. **Agent local preflight:** check IAC state and validity, per-payment and cumulative limits, merchant scope, payment method, and tool state. On failure, do not send a payment request. -2. **Construct the payment request:** correlate a unique request identifier, merchant order, complete IAC and `delegation_id`, amount and currency, payment tool, timestamp, Agent identity, and signature over critical fields. -3. **PSP authoritative authorization validation:** in order, check replay protection, Agent signature, IAC signature/state/delegate, financial constraints, necessary semantic constraints, and sub-account authorization material. -4. **Payment execution and state return:** after successful validation, debit or reserve funds and return transaction number, delegation identifier, order, state, and time. The Agent updates its local cumulative amount only from a successful PSP result. The PSP SHOULD also notify the merchant. +## **Processing requests and failures** +The sub-accounts managed by this component are at least SHALL capable of stabilizing the information associated with the sub-account identifier, the fiduciary Agent identifier, the current state of the account and the authentication key status associated with it. -After payment, an A402 flow retries with Proof and validates before delivery; a conventional merchant-platform order flow fulfills according to its interface. The access flow does not change DEL's IAC authorization boundary. +The achievement of such limitations as maximum balances, single amounts, cumulative amounts, validity periods or the application of mission Scope may require further allocation of sub-accounts, depending on the operation, to support risk segregation for more finer particles. -### 7.3 Handling and error semantics +Payment Service Provider SHALL be able to identify the basic life cycle state of the sub-account, including, at a minimum, the state of availability, freezing and cancellation, and decide whether to accept subsequent payment request. -An Agent's local preflight cannot replace authoritative PSP validation. The PSP's cumulative-limit decision MUST use authoritative historical successful amounts. +When a sub-account is not opened, the balance is insufficient, the state is abnormal, the binding relationship is inconsistent or the authentication key is invalid, Payment Service Provider SHALL rejects the related payment or management operation and returns the identifiable failure result. -In addition to INS errors, DEL retains at least these semantics: +The semantic SHOULD of the cause of the failure covers at least the failure to verify the identity, the failure to open the sub-account, the freezing of the sub-account, the cancellation of the sub-account, the insufficient balance and the invalidation of the authentication key. -| Category | Handling and recovery | -|---|---| -| IAC expired, revoked, or suspended | Do not retry directly; wait for restoration or obtain new authorization | -| Delegated Agent identity mismatch | Repair authorization or binding; do not blindly retry under another identity | -| Per-payment or cumulative amount exceeded | Adjust the transaction or obtain new authorization | -| Merchant or payment method outside authorization scope | Change the transaction approach or obtain new authorization | -| Insufficient balance | Add funds or choose another permitted payment tool before deciding whether to retry | -| Order or amount differs from confirmed snapshot | Reconfirm the transaction; do not silently reuse old authorization | -| Invalid sub-account or authorization material | Restore account or key state, or terminate the transaction | +# PSD-PAY-A402: Payment Process Based on HTTP 402 +## Overview +This component definition is Buyer Agent, Merchant/resource service provider interacts with a generic payment access line based on the HTTP 402 status code (Payment Required): Buyer Agent access to paid resources or services, and the seller ' s service returns 402 status code and bill when no valid proof of payment is found; the buyer completes payment that meets the requirements of the payment scene; the seller certifies the delivery of resources and completes the confirmation of performance. -## 8. `PSD-PAY-AUP`: autonomous delegated payment / L3 +This component may be referenced as needed by `PSD-PAY-INS`, `PSD-PAY-DEL`, and `PSD-PAY-AUP`. When referenced, it carries only the payment access interaction mechanism and does not replace other specific requirements of each scenario component, such as IAC constraints, cumulative amount boundaries, or sub-account management. -### 8.1 Scenario and prerequisites +## Participants and prefix +This component involves the following Participants: -AUP expresses goal-driven L3 autonomous decision and execution. The user confirms a task in advance and issues a `BOUNDED` IAC. The Agent MAY determine the counterparty, time, and execution path within the authorization boundary, and multiple payments MAY occur during one task lifecycle. ++ **Buyer Agent** Request for seller ' s resources or services, analysis of claims for payment, performance of authorized verification Principal, acquisition and submission of proof of payment. ++ **Seller's services** The seller's side may be Merchant, platform, seller Agent or its proxy interface, which is referred to as the seller's service provider in this component. ++ **Payment Service Provider (PSP)**: To receive payments under specific payment methods, to generate proof of payment, to provide certification of payment and to receive the required confirmation of performance. ++ **Principal**: confirm payments in real time in `PSD-PAY-INS` scenes; predefined authorized boundaries in `PSD-PAY-DEL` and `PSD-PAY-AUP` scenes by Intent Authorization Credential or sub-accounts, etc. ++ **Merchant or resource provider**: may be the same subject as the seller's service provider, or the seller's service provider may provide it with the resources to access and pay access capacity. -Prerequisites: +Before entering this component, SHALL satisfies the following conditions: -- a valid `BOUNDED` IAC is used; a `SPECIFIED` IAC does not form the authorization basis of this component; -- the Agent has decomposed the task, but the complete transaction subject need not be known initially; -- the Agent holds an available payment tool and uses a dedicated sub-account when needed; -- `CID-PCA-NEG` or equivalent negotiation has completed when dynamic selection is required; -- the normal path does not require real-time identity verification for every payment, but risk anomalies, ambiguous authorization, significant price changes, or near-limit conditions MAY pause and escalate to the user. ++ The seller ' s service provider SHALL be able to identify steadily the resources, services or orders to be charged and has the capacity to generate the only `resource_id` and `out_trade_no`. ++ Buyer Agent SHALL have the capability to identify HTTP 402 status code, to interpret Base64URL code Header, to select `method_id` supported and to verify Principal enabling rules. ++ Between Participants it has been determined that `CID-PCA-NEG` or the equivalent mechanism is available at payment method. -### 8.2 Five-step flow +## Interactive flow +The following process describes the single payment access process, which can be repeated many times during a full mission implementation cycle. -1. The seller returns a payment requirement associated with a resource or service through A402, MCP, or an API. -2. The Agent performs a real-time self-check against the `BOUNDED` IAC, task state, cumulative budget, per-payment limit, counterparty, service category, payment method, and tool state. -3. After the self-check passes, the Agent submits a payment request containing the `BOUNDED` IAC, `delegation_id`, transaction identifier, amount and currency, tool, time, and signature material. -4. The PSP checks replay protection, Agent and IAC authorization, financial and semantic constraints, account state, and risk. -5. After validation passes, the PSP processes funds and returns a payment-authorization result credential, transaction number, delegation identifier, state, and time. The Agent updates its local cumulative amount only from a successful PSP result. The PSP SHOULD also notify the merchant. +**Step 1: Request for fee-paying resources** -After payment, the A402 flow handles Proof retry, seller validation, resource delivery, and fulfillment confirmation. A conventional merchant-platform order flow follows its interface rules. Payment, Proof validation, resource delivery, and fulfillment confirmation remain distinct facts. +The request may be `GET`, `POST` or other HTTP method defined by the seller’s provider. -The [A402 protocol](a402.en.md) defines access-layer Headers, baseline payloads, common states, and error categories. AUP does not redefine them. +Buyer Agent The initial request is usually not accompanied by `Payment-Proof`; if carried, the seller ' s services SHALL verify its format, duration, binding of the transaction and whether it has been repeated. -### 8.3 Handling and error boundaries +**Step 2: Return to payment claims** -AUP reuses DEL error semantics for an expired, revoked, or suspended IAC; identity mismatch; per-payment or cumulative amount violations; insufficient balance; and merchant-scope violations. A402 or the corresponding access approach defines access-specific errors such as Proof-validation failures. ACT 2.1 does not freeze AUP-specific machine error codes. An implementation MUST report the stage in which failure occurred and MUST NOT equate payment success with resource delivery. +If the current request is not supported by proof of payment, or if the proof of payment is not certified, the seller ' s serviceer SHALL return HTTP `402 Payment Required` and carries a payment bill coded Base64URL on `Payment-Needed` Header. -## 9. Common security and processing invariants +```plain +HTTP/1.1 402 Payment Required +Payment-Needed: +Content-Type: application/json -1. Scenario authorization checks occur before funds processing. -2. Agent-local checks cannot replace authoritative PSP validation. -3. A unique request identifier, time window, and signature or equivalent integrity protection provide replay and tamper resistance. -4. Payment success, valid Proof, delivered resource, and confirmed fulfillment are distinct facts. -5. Payment-request retry, original-resource-request retry, and fulfillment-confirmation retry are different operations. -6. Selecting A402, MCP, or an API MUST NOT change the INS/DEL/AUP authorization level. -7. Raw account data, private keys, and complete Proof MUST NOT enter an untrusted Agent context, logs, or demo events. -8. If the authoritative payment result is unknown, query it first; do not automatically create a second payment because of a timeout. +{ + "error": "Payment Needed", + "message": "Please pay CNY 0.01 to access this resource", + "resource_id": "RES_1739836600000_abc123" +} +``` -## 10. A402 reference +Response is used only for debugging, logs and human readable tips; Buyer Agent payment information for machine processing SHALL be based on `Payment-Needed` Header. -When A402 is used, the scenario component supplies the [A402 access protocol](a402.en.md) with a completed authorization decision and payment-method context. A402 is responsible for: +**Step 3: Buyer undertakes scene verification and payment** -- `402 Payment Required`; -- `Payment-Needed`, `Payment-Proof`, and optional `Payment-Validation`; -- `method_id` and method extensions; -- Proof validation, replay protection, original-request correlation, and resource release; -- common state, errors, timeouts, idempotency, and recovery semantics. +After the Buyer Agent resolution `Payment-Needed`, SHALL performs the pre-judgement of the scene: -When MCP or an API is used, it MUST provide equivalent results and an explicit mapping to the common states. ACT 2.1 does not define a new message format for those interfaces. ++ In the `PSD-PAY-INS` scene, SHALL leads Principal to real-time payment confirmation. ++ In the `PSD-PAY-DEL` scenario, SHALL verify the validity of the SPECIFIED mode IAC, amount, cumulative amount, Merchant Scope, and allowed payment methods. ++ In the `PSD-PAY-AUP` scenario, SHALL verify the validity of the `BOUNDED` mode IAC, task Scope, cumulative budget, resource category, and Agent-specific Sub-account status. -## 11. Sources +If either condition is not met, Buyer Agent SHALL NOT continues to initiate payment and SHALL terminates the transaction in accordance with the pre-set strategy, switchs the counterparty or informs Principal processing. -- Related PSD website reference: [Payment Services Domain](https://www.act-protocol.com/documentation/payment); content not labeled ACT 2.1 is not a normative source for this release -- Higher-level reference: [Protocol Overview](https://www.act-protocol.com/documentation/overview) -- Alipay product facts: [AI metered-payment integration guide](https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html) +After the validation, Buyer Agent SHALL initiate payment to PSP or method-designated endpoints under the corresponding payment method norm `method_id` and obtains a certificate of the results of payment authorization. payment method, payment instrument, funds deduction, IAC verification and risk control strategy remains defined by the corresponding PSD scenario component and payment method component, A402 without repetition. + +**Step 4: Retry visits with payment certificates** + +After payment has been successful, Buyer Agent shall initiate a new request for the original resource or service and carry in `Payment-Proof` Header information such as payment certificates, PSP Trade Stream and buyer session identification. + +```plain +GET /market/XXXX/trend HTTP/1.1 +Payment-Proof: +``` + +**Step 5: Seller certifying payment** + +The seller ' s service provider SHALL interprets `Payment-Proof` and uses the PSP or letter-certification service according to the corresponding methodological norm `method_id` to verify the proof of payment as follows: + ++ **Validity of documents** Check the signature, validity period, revocation status, etc. of `payment_proof` and confirm that the certificate itself is valid. ++ **Responsiveness** Check whether the certificate has been duplicated and prevent the same payment certificate from being used for multiple resource visits. ++ **Coherence**: Verify that the paragraphs `trade_no` and `resource_id` in the certificate are consistent with the current request for resource visits and confirm that the certificate corresponds to the resources requested for payment. + +If any verification is not made, the seller's service SHALL refuses to pay for access to the resources and returns the wrong semantics that can be identified by Buyer Agent. + +**Step 6: Delivery of resources and recognition of performance** + +The seller’s services can then return to the machine’s readable certification and performance by `Payment-Validation` Header in a successful response. + +```plain +HTTP/1.1 200 OK +Payment-Validation: +Content-Type: application/json + +{ + "status": "PAYMENT_VALIDATED", + "trade_no": "2026040900828111317760000001xxxx", + "resource_id": "RES_1739836600000_abc123", + "resource": "XXXXXXXXXXXX" +} +``` + +After completing the delivery of resources or the performance of services, the seller ' s service provider initiated a confirmation of performance to the PSP in accordance with the specific method of payment. + +Upon completion of the payment transaction, PSP SHOULD be reported as `act:payment:transaction-completed` certificated events providing a factual basis for subsequent audits, dispute processing and task billings. + +## HTTP Header Extension Field +This component uses the following three types of HTTP Header fields. Three Header Value SHALL use Base64URL-coded format UTF-8 JSON. + +|Header Name|User|Time to use| +| --- | --- | --- | +|`Payment-Needed`|Seller's services|`HTTP 402` for the statement of payment claims and core parameters.| +|`Payment-Proof`|Buyer Agent|The buyer used it again when requesting resources or services with proof of the payment of the result of the authorization.| +|`Payment-Validation`|Seller's services|The seller returns after the results of the payment warrant have been certified.| + +## Method of payment (metal_id) +This component identifies the specific method of payment through `method_id`, and the corresponding method regulates the independent maintenance of the relevant rules in the document. + +Each payment method regulates the documentation of the independent method used to define the method ' s request construction, the extension field requirements, the signature algorithm, the PSP verification logic, the method of return of the certificate of payment result and the rules for allocation of error codes. + +Before entering this component, the buyers and sellers may consult and confirm `method_id`, `psp_id`, `endpoint` and `method_schema_url` as direct inputs for subsequent payment request construction and execution. + +## Payload Structure +The payment load is structured into two levels: the base load field and the payment method extension field. The base load field is used to define a set of standard elements shared by each payment method to ensure interoperability between different realizations. The payment method extension field is used to carry business parameters specific to the specific payment method, but does not change the standard semantic of the base load field. + +Each of the three Header payloads uses two layers of `Protocol + method` (pre-Base64URL code). + +### Baseload field +|Fields|Type|Annotations| +| --- | --- | --- | +|`method_id`|string|The payment method identifier is used to identify the specific method of payment used in the transaction.| +|`out_trade_no`|string|External order numbers, used for control, etc., of transactions.| +|`amount`|string|Payments, SHOULD in string format to avoid floating point accuracy problems.| +|`currency`|string|The currency of the transaction, SHOULD be expressed in the standard currency code.| +|`resource_id`|string|Resource identifiers to bind payments and resource access to prevent misappropriation of vouchers.| +|`pay_before`|string|The payment deadline is used to limit the time window for payment and reduce the risk of readmission.| +|`seller_unique_id`|string|The sole identifier of the seller ' s service provider.| +|`buyer_unique_id`|string|Buyer Agent Unique identifier.| +|`payment_proof`|string|A certificate of payment of the results of the authorization is used to mark the successful outcome of the authorization of payment.| +|`trade_no`|string|Trade stream number or trade unique identification number, generated by PSP and used for transaction tracking.| +|`expires_at`|string|(c) The deadline for the payment of certificates of authorized results.| +|`signer_id`|string|The only signer ' s identifier is used to identify the person that generated the signature of the message.| +|`signature_content`|string|Signing value to be used to ensure the integrity of the message and the verifiability of the source.| +|`signature_type`|string|The type of signature algorithm used to indicate the algorithm identifier required for the authentication of the signature of the message.| + +### Payment Method Extension Fields +The payment method extension field is used to fit the business scenario of the specific payment method, and the buyer and seller and the PSP may allow the addition of specific parameters to the method Scope in the methodological specifications. Such extension parameters may include the account identifier map key, commodity information, signature over the Scope declaration, or other payment-method-specific attributes. + +The definition, restraint and use of the extended field is defined by the corresponding payment method to regulate the independent description of the document. + +### Example of payload Payment-Needed +Using two layers of `Protocol + method` (before Base64URL code): + +```json +{ + "protocol": { + "out_trade_no": "ORDER_1739836600000_abc123", + "amount": "0.01", + "currency": "CNY", + "resource_id": "RES_1739836600000_abc123", + "pay_before": "2026-03-25T12:00:00+08:00", + "seller_signature": "YYYYxxxx=", + "seller_sign_type": "RSA2", + "seller_unique_id": "2088xxxxxxxx" + }, + "method": { + "seller_name": "Test Merchant", + "seller_id": "2088xxxxxxxx", + "seller_app_id": "app_123456", + "goods_name": "Test Product", + "seller_unique_id_key": "seller_id", + "service_id": "xxxx_12344" + } +} +``` + +### Example of payload Payment-Proof +Using two layers of `Protocol + method` (before Base64URL code): + +```json +{ + "protocol": { + "payment_proof": "7cf8a6a93c924e13eaa4bf20c3a487f30d1fbdb759a1f229b4091b7d0158xxxx", + "trade_no": "2026040900828111317760000001xxxx" + }, + "method": { + "client_session": "xxxxxxxxxxxxxsCiAgICAic2Vzc2lvbklkIjogInh4IiwKICAgICJzaWduYXR1cmUiOiAi5Yqg562+5ZCO57uT5p6c77yM6YCa6L+HY3JlZGVudGlhbElk5Yqg562+YWdlbnRUb2tlbiArIHNlc3Npb25JZCkiCn0=" + } +} +``` + +## Transaction Status +This component defines the state of the transaction described below, and the internal state of each payment method SHALL be mapped to the state below and then exported externally. + +|Status Code|Status Name|Annotations|Transferable to Status| +| --- | --- | --- | --- | +|`CREATE`|Create|Initial Status|`WAIT_BUYER_PAY`| +|`WAIT_BUYER_PAY`|Waiting for the buyer to pay.|The buyer has not yet completed payment|`WAIT_SELLER_FULFILLMENT`、`TRADE_CLOSED`| +|`WAIT_SELLER_FULFILLMENT`|Waiting for the seller to perform|The buyer paid for the performance of the seller ' s services|`WAIT_BUYER_RECEIPT`、`TRADE_CLOSED`| +|`WAIT_BUYER_RECEIPT`|Waiting for the buyer to write back.|The seller performed the contract, awaiting confirmation from the buyer|`TRADE_FINISHED`、`TRADE_CLOSED`| +|`TRADE_FINISHED`|The deal is done.|Final|None| +|`TRADE_CLOSED`|Transactions closed|Final, applicable to closed status after refund or cancellation|None| + +## Error Response +An error response SHOULD cover the semantic categories of signature verification, request parameters, identification, amount and asset, risk control, trading status, payment certificate certification and system anomalies. Buyer Agent and the seller's services may decide to retry, switch payment method, change the counterparty or terminate the transaction in accordance with the wrong synonym. + +|Semantic Category|Annotations|Retry proposal| +| --- | --- | --- | +|Signature verification error|Signature verification failed or the signature type is unsupported|Direct retry is generally not recommended; first check the signature material, signer identifier, and algorithm configuration| +|Request parameter error|Parameters are invalid, amount format error, time format error, or request expired|Once the submission has been amended, it may be re-examined; if it has expired, re-acquire the claim for payment SHALL| +|Protocol verification error|The protocol does not exist, the protocol is invalid, or the methodological norm does not match|Direct retry is not recommended, SHALL pre-validation of payment method configuration and protocol version| +|Agent identity verification error|Buyer Agent or seller service identity verification failed|Direct retry is not recommended; first check identity documents, public-key material, and binding relationships| +|Quantities and asset verification errors|Insufficient amount, insufficient balance or failure to verify asset accounts|It can be repeated after the balance has been filled, the amount adjusted or the payment instrument replaced| +|Restraint and Wind Control Error|User restricted, stroke control strategy, or authorized boundaries not satisfied|It is generally not recommended to try again immediately, SHALL pending release of the risk control or re-authorization. ]| +|Transaction status error|The transaction does not exist, or the current transaction is not allowed to proceed|Do not recommend a direct retry, SHALL first query the transaction status and do some sort of processing| +|Refund error|Excess of amount of refund or failure to process refunds|Subject to the cause of failure; transfer of personnel as necessary or follow-up reimbursement process| +|Performance reply error|Failure to perform, or abnormality in the return of performance results|You can decide whether or not to try again in conjunction with policy and compliance query results, etc.| +|Payment authorization result credential verification error|The credential is empty, expired, missing, invalid, or inconsistent with the current subject, transaction, or resource|Direct retry is generally not recommended; obtain a valid credential or initiate payment again| +|System error|Intra-system anomalies or downstream service failures|A limited number of re-tests by index exit strategy, manual transfer or alarm after crossing the threshold| + +# PSD-PAY-INS: Instant User Payment (L1 scene) +## Overview +Instant User Payment (Instant Payment,PSD-PAY-INS) applies to Principal real-time presence and prompt confirmation of the purchase to complete the payment. + +In that scenario, Principal participation in the closed circle of purchasing decisions in their entirety, and therefore no pre-issuance of Intent Authorization Credential; Principal prompt confirmation completed at Payment Service Provider cashier is in itself the legal basis for authorization of this payment. + +In this component, AI participates in the transaction, but a human ultimately makes and executes the decision. Payment decision authority remains with the User. Before debiting funds, the Payment Service Provider SHALL verify the User for each payment (for example, by face, fingerprint, QR-code scan, password, or verification code); the Agent's role is to place the order and initiate the payment request on the User's behalf. From a payment-security and risk-control perspective, this is the L1 scenario. + +> Note: The current protocol only defines the model payment request initiated from Agent to Payment Service Provider, which will be followed by an extension of support for the model payment request initiated from Merchant to Payment Service Provider. +> + +## Preconditions +This component covers the following: Participants: Principal, Buyer Agent, seller or Merchant side system, and Payment Service Provider for the payment of payments for receipt, verification and processing of funds. + +Before entering this component, SHALL satisfies the following preconditions. + ++ Principal has expressed a real-time purchase intention to Buyer Agent and Buyer Agent has pre-screened the rule with Cart Confirmation process to obtain information on Merchant-side orders to be paid. ++ Buyer Agent SHALL holds valid payment instrument references in `PSD-PMT-BND` for this payment scene. ++ Payment Service Provider SHALL be capable of verifying the validity of payment instrument references, verifying the integrity of Buyer Agent identifications and requests, and initiating a payment counter or confirmation interface for Principal upon completion of the examination. ++ The payment interaction process may be based on `PSD-PAY-A402` processes, or on the traditional Merchant process under the Merchant platform; the interface may be achieved through the MCP interface, the API interface, etc., and determined by Participants in consultation with the scene based on capacity. + +## Process Steps +The following process describes the single, instant payment process. Buyer Agent enforces the corresponding rules of interaction with Payment Service Provider SHALL on the basis of the established payment interaction process (`PSD-PAY-A402` or traditional Merchant under platform) and the manner in which the corresponding interface is achieved (MCP interface, API interface, etc.). + +**Step 1: Pre-payment** + +Buyer Agent After completing commerce interaction with the seller’s service provider or Merchant side system, SHALL obtains the transaction identifier information necessary to connect the front-end commercial intent to the back-end settlement of funds. + ++ Buyer Agent SHALL completes the rule pre-check with Cart Confirmation process and obtains Merchant side order number when using the Merchant sub-payment process. ++ When the `PSD-PAY-A402` access process is used, Buyer Agent may be responded to by the seller ' s services by `HTTP 402 Payment Required` and by `Payment-Needed` returning the corresponding order or resource identifier (e.g. `out_trade_no`, `resource_id`, etc.) for the current payment. + +**Step 2: Construct and send immediate payment request** + +Buyer Agent At the launch of Payment Service Provider, the request SHOULD contain at least the following core elements. + ++ This request is for the sole global identifier to be used for weight proofing. ++ Merchant side order number to be used for product information consistency verification. ++ payment instrument Quoted for prior binding. ++ This payment is in the amount and in the currency of the payment. ++ Time stamp requested for the timescale verification of Payment Service Provider. ++ Buyer Agent Identity and signature of key elements of this request. + +**Step 3: Payment Service Provider Basic verification** + +Payment Service Provider After receiving immediate payment request, the basic verification, which includes, at a minimum, a request for a single marking to protect against re-entry, a request for a time stamp to be time-barred, a Buyer Agent signature validity check, and a payment instrument reference validity check, is completed. + +For payment instrument quotation, Payment Service Provider SHALL confirms that it is unexpired, unexpired and consistent with the Buyer Agent identity binding that initiated this payment request. + +If either of these checks is not passed, Payment Service Provider SHALL NOT continues to enter the register confirmation process and SHALL directly returns the corresponding failure result. + +**Step 4: Call up the cashier and Principal for immediate confirmation** + +After all basic verifications have been completed, Payment Service Provider SHALL calls to Principal the cashier or confirmation window. + +At least SHALL display the amount of the payment and the currency, the name of the receipt Merchant and the corresponding field in payment request. + +Principal Upon completion of the confirmation by means of biometric recognition, payment password, dynamic authentication code or other Payment Service Provider support, Payment Service Provider SHALL record the nuclei used for this confirmation and the confirmation time stamp as evidence of authorization for this payment. + +This step is the core feature of the L1 scenario: Payment Service Provider SHALL complete User identity verification and confirmation for each payment before funds are debited. The identity verification method (e.g., facial recognition, fingerprint, QR-code scanning, password, or verification code) is determined by Payment Service Provider based on its risk-control strategy and terminal environment; this protocol does not prescribe a specific method. + +**Step 5: Pay execution and status returns.** + +Upon immediate confirmation Principal, Payment Service Provider SHALL interpret payment instrument references to the corresponding true payment account and effect the deduction or amount freeze. + +The Payment Service Provider SHALL synchronously return the payment result to the Buyer Agent. The response SHOULD include at least the Payment Service Provider transaction identifier, Merchant order number, transaction status, and transaction timestamp. + +The Payment Service Provider SHOULD also notify the Merchant-side system of the payment result to support order-status updates and subsequent fulfillment. + +Upon completion of the payment transaction, Payment Service Provider SHOULD anecdotal events are reported at `act:payment:transaction-completed` to support subsequent dispute resolution and audit retroactive. + +> **Notes:** Upon completion of payment, Buyer Agent may be used to access paid resources or services and trigger compliance: +> +> + When the `PSD-PAY-A402` access process is used, Buyer Agent may carry `Payment-Proof` another access to the paid resources or services, and the seller ' s service provider certifies the release of the resources or initiates performance, as defined by `PSD-PAY-A402`. +> + Resource access and compliance are defined by the interface corresponding to the Merchant platform when the Merchant platform line payment process is used. +> +> Regardless of the payment interaction process, the interface is available through the MCP interface, the API interface, etc. +> + +## Processing of requests ++ Buyer Agent When constructed immediately payment request, SHALL to ensure consistency in the amount paid, currency and order information on side Merchant, and SHALL NOT to modify the identified core elements of the transaction without permission. ++ Payment Service Provider complete all basic verifications before the register is called; unverified request SHALL NOT enters the register confirmation process. ++ Payment Service Provider Shows payment information for Principal that is strictly consistent with the corresponding field in the request to ensure that Principal is confirmed with full knowledge. ++ In the L1 scenario, Payment Service Provider SHALL complete User identity verification and confirmation before funds are debited; a payment request for which identity verification and confirmation have not been completed SHALL NOT enter the funds-debiting stage. The identity verification method is determined by Payment Service Provider based on its risk-control strategy and terminal environment. + +## Error Response +Error response in instant payment, SHOULD overwrites the following semantic categories. + +|** Semantic Category**|** Annotations**|** Retry proposal**| +| --- | --- | --- | +|Request repeated.|The only marking requested has been used and the attack is suspected to be repeated.|SHALL NOT Directly retrying; SHALL replacement request only marked and restarted.| +|Expiry of request|The time stamp requested exceeds the valid window Payment Service Provider accepted.|The test may be repeated after the time stamp is regenerated and after confirmation that the request is still valid.| +|Invalid Agent signature|Buyer Agent signature verification failed|SHALL NOT retry directly; first correct the signature material or verify the identity binding relationship.| +|Invalid quote payment instrument|payment instrument Quotes do not exist, are no longer valid, expired or not available.|SHALL NOT Directly retry; SHALL may be rebound or replaced at payment instrument.| +|payment instrument citation does not match Agent identity|The current reference to payment instrument does not correspond to the identity binding of Buyer Agent for initiating the request.|SHALL NOT Directly retry; SHALL amend the binding relationship or replace the legitimate sponsor.| +|Confirm failure User|Principal Failed, cancelled or not confirmed within a specified time frame.|Re-launch confirmation may be permitted on the basis of operational strategy.| +|Payment execution failed|Following the adoption of the basic verification and confirmation User, the transfer of funds, the freeze of amounts or access to roads have failed by stage.|A decision may be made whether to allow a re-test based on the reasons for failure; the tunnel can be re-tried at short notice, and account or risk control abnormalities usually re-try directly at SHOULD NOT.| + +# PSD-PAY-DEL: User-directed Delegated Payment (L2 scene) +## Overview +User-directed Delegated Payment (Delegated Payment, PSD-PAY-DEL) applies in the absence of Principal and is Intent Authorization Credential pre-issued on the basis of Principal and autonomously completes the scenario of procedural payments within the authorized boundary. + +Unlike `PSD-PAY-INS`, the basis of authorization for this component is not Payment Service Provider real-time confirmation, but Principal pre-issued and valid at the time of payment. The scenario described in this component is also referred to as the L2 scenario in terms of security risk protection. + +> Note: The current protocol only defines the model payment request initiated from Agent to Payment Service Provider, which will be followed by an extension of support for the model payment request initiated from Merchant to Payment Service Provider. +> + +## Apply scene and prefix conditions +This component applies to User alibi (Human-Not-Present) and the object of the purchase is clearly defined in the initial interaction and directed commissioning scenario. + +In the platform Agent scenario, in order to prevent User excesses and confusion with identity, payment of SHALL be made with attention to the binding of the platform Agent identity with the specific Principal identity; in the exclusive Agent scenario, payment is usually made directly by anchoring the exclusive Agent identity and may be further sequestered with the exclusive sub-account. + +From the point of view of the payment interaction, the L2 scenario usually uses the traditional Merchant platform line payment process (Principal for pre-defined purchases, Agent for completion of orders and payments on the side of Merchant; when the subject of Agent access is provided in the form of a fee-paying resource or service, the PSD-PAY-A402 access process may also be used, with the seller's service initiating a payment claim through HTTP 402. Two payment interactions can be achieved through the MCP interface, the API interface, etc. + +Before entering this component, SHALL satisfies the following preconditions. + ++ Principal SHALL Completed intent and issued valid Intent Authorization Credential (IAC); Buyer Agent pre-checked with Cart Confirmation for Merchant outstanding order information. ++ At the level of payment instrument, Buyer Agent SHALL be either available for payment instrument or available for Agent-specific Sub-account and its payment authorization. ++ For requests for signature protection, identity binding, authorization credential verification and bottom key call mechanisms, this component does not repeat the definition of its security achievement, and the relevant capabilities can be supported by ASL identity, connection, authorization and key management capabilities. + +## Process Steps +The following process describes the single-directed commissioning process. Buyer Agent and Payment Service Provider SHALL implement the corresponding interactive rules based on the defined payment interaction process and the manner in which the corresponding interface is achieved. + +**Step 1: Agent end-end rule self-check** + +Buyer Agent Before the tectonic commission payment request, SHALL to perform local pre-screening in conjunction with the currently held IAC, at least: IAC is valid, the current period falls within IAC the authorized period Scope, the current amount of payment does not exceed the maximum amount of a single amount, the sum of this amount and the cumulative amount of the locally saved deduction does not exceed the total authorized amount, the target Merchant is within Scope allowed, and the proposed use of payment method is in the permitted list payment method. + +Local pre-screening is a pre-filtration mechanism of Buyer Agent; if the pre-screening is not passed, Buyer Agent SHALL NOT continues to initiate commissioning payment request. + +**Step 2: Construct and send the commission payment request** + +Buyer Agent When initiating the commission payment request to Payment Service Provider, the request SHOULD includes, at a minimum, the unique identification requested, the Merchant side order number, the full Intent Authorization Credential and its commissioning identifier, the amount and currency of the current payment, payment instrument certificates, the time stamp requested, and the Buyer Agent identification and signature of key elements. + +When the exclusive sub-account is not used, payment instrument is usually payment instrument quoted in the output `PSD-PMT-BND`; when the exclusive sub-account is used, payment instrument is SHALL a secret of payment authorization generated by the sub-account identifier and its exclusive key. + +The signature covers Scope SHOULD at least the unique identification, commissioning mark, Merchant side order number, payment amount, currency and time stamp of the request to ensure that the key elements are not tampered with. + +**Step 3: Payment Service Provider side authorization verification** + +Payment Service Provider After receiving the commission payment request, SHALL completes the rectification, Buyer Agent signature verification, IAC validity verification, IAC financial binding verification and, if necessary, semantic binding verification. + ++ Validity verification IAC includes, at a minimum, verification of validity of signature IAC, IAC unexpired unsuspensed, Agent fiduciary identification in IAC consistent with the identification Buyer Agent in the request, and the commissioning mode is a valid enumeration value as defined in this protocol. ++ The financial layer binding verification includes at least single-value, cumulative and payment method matching verifications. ++ Semantic binding may be performed as required by achievement, e.g. to verify whether the receipt Merchant is in the permitted Merchant Scope or to compare the requested element to User original intent. ++ If an exclusive sub-account is used, Payment Service Provider shall also verify the authorization of payment generated by the exclusive key of the sub-account. + +If any verification is not made, Payment Service Provider SHALL rejects the request and returns the corresponding failure semantic. + +**Step 4: Payment execution and status returns** + +After all verifications have been completed, the deductions or amounts of funds have been frozen at Payment Service Provider SHALL; when the exclusive sub-account has been used, the funds SHALL have been transferred or frozen directly from that sub-account. + +The Payment Service Provider SHALL synchronously return the payment result to the Buyer Agent. The response SHOULD include at least the globally unique transaction identifier generated by the Payment Service Provider, the delegation identifier associated with the payment, the Merchant order number, transaction status, and transaction timestamp. + +After receiving a successful response, the Buyer Agent SHALL update its local cumulative-debit cache using the successful transaction amount confirmed by the Payment Service Provider. + +The Payment Service Provider SHOULD also notify the Merchant-side system of the payment result to support order-status updates and subsequent fulfillment. + +Upon completion of the payment transaction, Payment Service Provider SHOULD anecdotal events are reported at `act:payment:transaction-completed` to support subsequent dispute resolution and audit retroactive. + +> Note: Upon completion of payment, Buyer Agent may be used to access paid resources or services and trigger performance: +> +> + When the `PSD-PAY-A402` access process is used, Buyer Agent may carry `Payment-Proof` another access to the paid resources or services, and the seller ' s service provider certifies the release of the resources or initiates performance, as defined by `PSD-PAY-A402`. +> + Resource access and compliance are defined by the interface corresponding to the traditional Merchant platform line payment process. +> +> Regardless of the payment interaction process, the interface is available through the MCP interface, the API interface, etc. +> + +## Processing of requests ++ Buyer Agent Before initiating commissioning, local pre-screening is completed and SHALL NOT requests that clearly exceed the authorized boundary continue to be sent to Payment Service Provider. ++ Buyer Agent SHALL ensure that the payment amount, payment currency, and Merchant-side order number in the delegated payment request are consistent with the preceding Cart Confirmation result. ++ Payment Service Provider Completing the validity verification and binding verification of IAC, and SHALL NOT continuing the non-approval request at the withholding stage, pending the processing of funds. ++ When the exclusive sub-account model is used, Payment Service Provider, in addition to verifying IAC, verify the validity of the sub-account status and its payment authorization secret and confirm its validity in relation to the current Buyer Agent identity and sub-account binding. ++ Payment Service Provider The determination of the cumulative amount is based on the amount of historical successful transactions that it has identified, while SHALL NOT relies only on Buyer Agent local statements. ++ The authorizing effect of commissioning payments SHALL be strictly limited to the boundary as defined in IAC, SHALL NOT exceeding the original authorization Scope by being procedurally implemented payment request. + +## Error Response +Based on the syntax of the error response of the `PSD-PAY-INS` component definition, this section primarily expands the syntax of the error response associated with the use of Intent Authorization Credential (IAC) and the level boundary. + +|** Semantic Category**|** Annotations**|** Retry proposal**| +| --- | --- | --- | +|IAC Expired|Intent Authorization Credential has exceeded its validity and cannot continue to be the basis of authorization for this commission.|SHALL NOT Directly retry; SHALL re-enactment of valid authorization.| +|IAC Cancelled|Intent Authorization Credential has been revoked and cannot continue to be paid for.|SHALL NOT Directly retry.| +|IAC Paused|Intent Authorization Credential is currently suspended and not available for new payment request.|Normally SHALL NOT is to be retried directly; SHALL be to be restored or reauthorized.| +|Unmatched identity Agent|The Buyer Agent identifier in IAC is not consistent with the Buyer Agent identifier in the request.|SHALL NOT Directly retry; SHALL Amend binding relationships or replace legitimate sponsors.| +|Single amount exceeding limit|This payment exceeds the single amount ceiling set at IAC.|SHALL NOT Directly retry; SHALL adjustment of amounts or reauthorization.| +|Cumulative amount exceeded|The sum of the current payment and the cumulative amount confirmed exceeds the total authorized amount of IAC.|SHALL NOT Directly retry; SHALL Adjustments or reauthorizations.| +|Insufficient balance|The debit account or the exclusive sub-account balance is insufficient to complete the current payment.|The operational strategy can be used to determine whether to try again after the balance has been replenished.| +|Merchant Not in Scope|Collections Merchant are not in the permitted Merchant Scope.|SHALL NOT Directly retry; SHALL Replace Merchant or reauthorize.| + +# PSD-PAY-AUP: Autonomous Delegated Payment (L3 scene) +## Overview +Autonomous Delegated Payment (autonomous Delegad Payment, AUP) applies in the absence of Principal and is based on `BOUNDED` pre-issued `BOUNDED` model Intent Authorization Credential for the autonomous conduct of multiple rounds of commercial decision-making and payments within the authorized boundary. + +As in `PSD-PAY-DEL`, the basis of authorization for this component is not Principal real-time confirmation on Payment Service Provider cashier, but Principal pre-issued and still valid at the time of payment Intent Authorization Credential. The difference is that the object of purchase for the `PSD-PAY-DEL` scenario is clearly identified in the initial interaction, Buyer Agent the payment is executed in accordance with the directive, and Buyer Agent the scenario is autonomous within the authorized boundary to determine the object of the transaction, the time of the transaction and the path of execution, and can initiate multiple payments within a mission cycle. + +## Participants and prefix +This component covers Buyer Agent, the seller's service provider, Payment Service Provider PSP, and the ability to provide the upstream authorization base Authorization & Delegation Domain if required. + +In the platform Agent scenario, in order to prevent User excesses and confusion with identity, payment of SHALL be made with attention to the binding of the platform Agent identity with the specific Principal identity; in the exclusive Agent scenario, payment is usually made directly by anchoring the exclusive Agent identity and may be further sequestered with the exclusive sub-account. + +From the point of view of the payment interaction process, L3 under the scenario Buyer Agent usually uses `PSD-PAY-A402` access (a payment claim is initiated by the seller's service provider through HTTP 402); it may also use the traditional Merchant platform under-list payment process or other access option. Both types of payment interaction can be achieved through the MCP interface, the API interface, etc. + +Before entering this component, SHALL satisfies the following preconditions. + ++ Principal has completed and has been issued a valid `BOUNDED` model Intent Authorization Credential. ++ Buyer Agent has completed the task of dismantling and obtaining resources or service targets to be visited. ++ Buyer Agent Available at payment instrument; under an autonomous commissioning scenario, SHOULD completes the payment authorization in combination with Agent-specific Sub-account and its accompanying proprietary key capability. ++ If necessary, the buyer and seller can complete Payment Capability Negotiation on the basis of `CID-PCA-NEG`, specifying the method of payment for subsequent payments, Payment Service Provider, the target interface address and the corresponding payload structure description. ++ For requests for signature protection, identity binding, authorization credential verification and bottom key call mechanisms, this component does not repeat the definition of its security achievement, and the relevant capabilities can be supported by ASL identity, connection, authorization and key management capabilities. + +## Process Steps +The following process describes the single Autonomous Delegated Payment process; the process can recur over a full mission implementation cycle. The process involves steps that interact with the payment access option, Buyer Agent with the seller's SHALL based on the payment interaction process (`PSD-PAY-A402` or the traditional Merchant single payment process under the platform) and how the corresponding interface is achieved (MCP interface, API interface, etc.). + +**Step 1: Return of the seller ' s service provider ' s claim for payment** + +Buyer Agent When requesting resources or services from a seller's service provider for which payment is required, the seller's service provider SHALL return the claim for payment according to the payment interaction process adopted. When using `PSD-PAY-A402` access, the seller service provider SHALL return the `HTTP 402 Payment Required` status code and declares the core parameters of this payment through `Payment-Needed` response head; SHALL return the claim for payment for the equivalent price in accordance with the corresponding process. Merchant This response was used to clarify to Buyer Agent the corresponding payment request for the visit, the payment time window and the basis for the subsequent request. + +**Step 2: Buyer Agent Implementation of the rules on self-inspection in real time** + +Buyer Agent Before deciding whether to continue paying, SHALL in conjunction with the currently held `BOUNDED` model Intent Authorization Credential and local task status implementation rules, self-checks include, at a minimum: + ++ (a) Whether the current period is still in the validity of the mandate IAC; ++ Whether the sum of the cumulative amount paid and the current amount exceeds the total authorized amount of IAC; ++ Whether the current payment exceeds the maximum amount of IAC; ++ Whether the counterparty and the type of service meet the constraints IAC; ++ To be used payment method in the list of payment method allowed; ++ Whether payment instrument (including exclusive sub-accounts) is available. + +Local cache cumulative payment recognition SHALL be calculated as the amount of the successful payment transaction returned by PSP; the default is zero before the first payment. + +If either condition is not met, Buyer Agent SHALL NOT continues to initiate payment and SHALL terminates the transaction in accordance with the pre-set strategy, switchs the counterparty or informs Principal processing. + +**Step 3: Buyer Agent Submitted payment request** + +If self-checked, Buyer Agent SHALL be bound by this component scenario and the normative structure of the access programme payment request and submitted to PSP for processing. + +SHALL in payment request includes the `BOUNDED` model on which this payment is based and its commissioning identifier, transaction identifier information, payment amount and currency, payment instrument certificate, request time information, and Buyer Agent signature for key elements. + +When the exclusive sub-account is not used, payment instrument is payment instrument quoted in the output `PSD-PMT-BND`, and when the exclusive sub-account is used, payment instrument is SHALL be the document generated by the sub-account SHALL and its exclusive key to authorize payment, consistent with payment instrument for `PSD-PAY-DEL`. + +**Step 4: PSP Verification** + +After receiving payment request, SHALL completes the following in turn: + ++ (b) Validation of the weight check, Buyer Agent signature; ++ Validity of `BOUNDED` model Intent Authorization Credential (valid signature, unexpired unsuspensed, entrusted Agent identifier consistent with Buyer Agent identifier in request, valid list value); ++ Financial-level binding verification (single cap, cumulative cap, payment method matching); ++ Semantic binding verification (receipt Merchant in IAC permitted Scope and consistency of request elements with User's original intent); ++ Audit of account status, balance and risk control strategy. + +If an exclusive sub-account is used, PSP also SHALL validates the validity of the payment authorization message generated by the exclusive key to the sub-account and verifies the balance or amount available for the sub-account. If any verification is not made, the PSP SHALL rejects the request and returns the corresponding failure syntax. + +**Step 5: Payment execution and status returns** + +The PSP returns to Buyer Agent a certificate of the results of the payment, which includes at least SHOULD the only global trade flow code generated by Payment Service Provider, the commissioning identifier for this payment connection, the status of the transaction and the time stamp. + +Upon receipt of a successful response, SHALL updates the local cumulative debit cache with PSP recognition of successful transaction amounts. The PSP SHOULD sync will notify payment result side system Merchant to support order status updates and subsequent performance processing. + +Upon completion of the payment transaction, PSP SHOULD be reported as `act:payment:transaction-completed` certificated events providing a factual basis for subsequent audits, dispute processing and task billings. + +> Note: Resource visits, certificate validation and performance delivery after payment is completed, implemented on the basis of the payment interaction process used: +> +> + When the `PSD-PAY-A402` access process is used, Buyer Agent carries the `Payment-Proof` re-access to the resource at the head of the request; the seller ' s service is directed to verify the validity, non-repetition and consistency of the PSP certificate with the current resource access request, returning the validation results through `Payment-Validation` response head and releasing the resource or initiating performance. Specific interactive details are defined by `PSD-PAY-A402`. +> + When a traditional Merchant platform line payment process is used, resource access, certification and performance delivery are defined by the interface to which the process corresponds. +> +> The specific interactive mechanisms for service performance, compliance buy-back and archiving confirmation are defined by the rules of the access programme and the corresponding payment methods used. +> + +## Processing of requests ++ Buyer Agent Before initiating Autonomous Delegated Payment, SHALL complete the local rule self-check and SHALL NOT continue to send requests that clearly exceed the authorized boundary in `BOUNDED` mode IAC to PSP. ++ Buyer Agent SHALL ensure that the payment amount, payment currency, and Merchant-side order number in the payment request are consistent with the preceding commercial confirmation result. ++ The PSP completes the validity verification and binding verification of IAC pending the processing of funds, and SHALL NOT continues the non-approval request to the deduction phase. ++ When the exclusive sub-account model is used, the PSP, in addition to verifying IAC, verifys the validity of the sub-account status and its payment authorization secret and confirms its validity in relation to the current Buyer Agent identity and sub-account binding. ++ PSP's assessment of the cumulative amount is based on the amount of historical successful transactions that it has identified, while SHALL NOT relies only on Buyer Agent local statements. ++ The validity of the authorization Autonomous Delegated Payment is strictly limited to the boundary defined in the `BOUNDED` model IAC, and SHALL NOT is exceeded by the procedural implementation of payment request the original mandate Scope. + +## Error Response +Based on the `PSD-PAY-DEL` definition of error response syntax, the wrong response of this component is mainly related to the `BOUNDED` model IAC and the autonomous entrusting boundary. The wrong response of the access program (e.g. payment authorization certificate certification error) is defined by `PSD-PAY-A402` or the corresponding access program regulation by `PSD-PAY-A402`. diff --git a/docs/specification/payment-services.md b/docs/specification/payment-services.md index ae6e3dd..844b268 100644 --- a/docs/specification/payment-services.md +++ b/docs/specification/payment-services.md @@ -2,238 +2,646 @@ 中文 | [English](payment-services.en.md) -> **状态：ACT 2.1 Specification / Final / Normative** -> **版本基线：2026-08-11（UTC+8）。** 本文是 ACT 2.1 的规范性 PSD 文本。文中的“应/不应/宜”表达规范要求；具体产品兼容和 Conformance 仍需独立证据。 +# 范围 +## 本域定位 +支付服务域（Payment Services Domain, PSD）规定智能体在完成支付前商业确认后，向支付服务方发起支付、接受支付核验、获取支付结果并处理相关状态的交互规则，为智能体商业中的支付执行阶段提供统一、可校验、可衔接的支付服务语义。 -## 1. 范围与边界 +## 本域职责范围 +本域覆盖以下内容： -支付服务域（Payment Services Domain，PSD）描述商业确认之后的支付工具准备、账户隔离、支付授权检查、支付执行、结果回传、凭证验证和相关状态语义。 ++ 支付方式绑定及支付工具引用管理； ++ 智能体专属子账户及其相关验证能力管理； ++ 基于 HTTP 402 的通用支付接入交互（PSD-PAY-A402）； ++ 不同在场性与自主度下的三类支付场景：用户即时支付、用户定向委托支付和自主化委托支付； ++ 支付请求构造、支付工具引用、授权核验、支付执行和状态回传； ++ 支付执行阶段所需的关键对象、状态语义和跨域引用关系。 -本域覆盖： +本域不规范以下内容： -- 支付方式绑定和支付工具引用； -- Agent 专属子账户及配套验证能力； -- INS/L1、DEL/L2、AUP/L3 三类支付场景； -- A402 支付要求、Proof、验证和资源恢复接入； -- 支付请求、支付结果、状态、错误和跨域引用。 ++ 商户内部订单履约、库存处理和业务系统实现； ++ 底层清算网络报文、资金清算结算处理及通道内部机制； ++ 支付服务方内部风控策略实现、路由策略和账户核心系统实现。 -本域不定义商户内部库存与履约系统、底层清算网络、PSP 内部风控和路由实现，也不重复定义支付宝产品的开户、沙箱和 API 操作。 +# 本域组件列表与关系 +## 组件总览 +支付服务域由六个协议组件构成，分为支付接入方案组件与支付场景组件两类，它们共同完成从支付工具准备、账户隔离与支付授权，到支付执行与结果状态管理的完整链路。 -版本与实现边界： +支付场景组件： -1. ACT 2.1 Release 中的本文是 2.1 版本化文本；ACT Protocol 官网[支付服务域](https://www.act-protocol.com/documentation/payment)是未版本化的信息性参考。 -2. `PSD-PAY-A402` 是独立接入组件，可被 INS/L1、DEL/L2、AUP/L3 引用。 -3. 支付宝渠道字段、API、签名和沙箱流程只进入支付宝实现层，不反向改写本规范。 -4. 公开包不恢复 `specs/2.0`、旧 Schema 或旧示例；ACT 2.1 没有规定的 wire 细节属于非规范性实现产物或未来版本工作。 ++ **PSD-PMT-BND：支付方式绑定。**负责规范委托人向支付服务方完成智能体支付能力开通，并为智能体建立可用支付标记或等价支付工具引用的过程。 ++ **PSD-AGT-SUB：智能体专属子账户管理。**负责规范为特定智能体开立具有资金隔离能力的专属子账户，并管理其配套验证密钥及生命周期的过程。 ++ **PSD-PAY-INS：用户即时支付。**负责规范委托人实时在场情况下，发起即时支付、完成支付确认并接收支付结果的过程。 ++ **PSD-PAY-DEL：用户定向委托支付。**负责规范委托人不实时在场情况下，买方智能体依据 SPECIFIED 模式 IAC 发起定向委托支付并接受 PSP 核验的过程。 ++ **PSD-PAY-AUP：自主化委托支付。**负责规范委托人不实时在场情况下，买方智能体依据 BOUNDED 模式 IAC 在授权边界内自主开展多轮商业决策与支付的过程。 -## 2. 组件总览 +支付接入方案组件： -| 组件 | 类型 | 规范职责 | 规范边界 | -|---|---|---|---| -| `PSD-PMT-BND` | 支付工具 | 建立受限支付工具引用并管理其有效状态 | 钱包聚合产品不整体等同于本组件 | -| `PSD-AGT-SUB` | 账户隔离 | 建立可选的 Agent 专属子账户及验证密钥生命周期 | 可选能力，不是 AUP 必备条件 | -| `PSD-PAY-INS` | L1 场景 | 用户在场并逐笔确认的即时支付 | 可结合 A402、MCP 或 API 接入 | -| `PSD-PAY-DEL` | L2 场景 | 明确标的下的定向委托支付 | 可结合 A402、MCP 或 API 接入 | -| `PSD-PAY-AUP` | L3 场景 | `BOUNDED` IAC 下的自主化委托支付 | 规定授权与支付语义，接入交互由 A402 等组件承载 | -| `PSD-PAY-A402` | 接入协议 | HTTP 402、三类 Header、载荷、状态、幂等与错误恢复 | 独立组件，可被 INS、DEL、AUP 引用 | ++ **PSD-PAY-A402：基于 HTTP 402 的支付接入。**负责规范买方智能体、卖方服务方与支付服务方之间基于 HTTP 402 状态码的通用支付接入交互，可被各支付场景组件按需引用。 -## 3. 核心对象与跨域引用 +## 核心对象与标识 +为保持本域内部处理以及与其他域之间引用关系的一致性，支付服务域使用一组标准核心对象和标识来描述支付执行阶段的关键信息。本域核心对象及其作用可概括如下。 -| 对象或标识 | 规范语义 | 产生/来源 | 主要使用方 | -|---|---|---|---| -| 支付工具引用 | 不暴露原始账户信息的受限付款工具引用；可以是 Token、子账户标识或等价凭据 | `PSD-PMT-BND`、`PSD-AGT-SUB` | INS、DEL、AUP | -| 商户侧订单信息 | 用于关联交易标的、金额和支付处理的商户侧订单号及必要上下文 | 商业交互流程或卖方服务方 | 三类支付场景 | -| 支付能力协商结果 | 所选支付方法、PSP、端点和方法 Schema | `CID-PCA-NEG` 或等价机制 | A402、DEL、AUP，必要时 INS | -| IAC | 委托授权边界 | `ADD-IAC-ISS` | DEL、AUP | -| `delegation_id` | 稳定关联一次委托授权生命周期 | 委托授权域 | DEL、AUP、后续证据 | -| 支付请求 | 交易、工具、金额、时间、请求唯一标识和完整性材料的组合 | INS、DEL、AUP | PSP 或支付受理方 | -| 支付结果 | PSP 返回的交易号、订单关联、状态和时间 | PSP | 买方、商户、后续证据 | -| 支付要求/Proof/验证结果 | 资源收费要求、支付证明和验证/恢复结果 | A402 与支付方法 | 买方、卖方、PSP | +| **对象或标识** | **含义** | **主要产生位置** | **主要使用位置** | +| --- | --- | --- | --- | +| 支付工具引用 | 支付执行时用于标识付款工具的可用引用对象，可表现为支付标记、子账户标识或其他等价支付工具凭据 | PSD-PMT-BND、PSD-AGT-SUB | PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP、PSD-PAY-A402 | +| 商户侧订单号 | 来自商业交互域的订单级确认结果，通过订单号标识本次交易的商品信息、金额等信息 | CID-CART-CFM | 支付服务域各支付执行组件 | +| 支付能力协商结果 | 来自商业交互域的支付前能力对齐结果，用于确定本次支付所采用的支付方式、支付服务方、接口端点及载荷模式 | CID-PCA-NEG | PSD-PAY-A402、PSD-PAY-DEL、PSD-PAY-AUP，以及必要时的 PSD-PAY-INS | +| 用户意图授权凭证（IAC） | 委托授权域签发的意图授权凭证，用于表达委托支付或自主支付的授权边界 | ADD-IAC-ISS | PSD-PAY-DEL、PSD-PAY-AUP | +| `delegation_id` | 委托授权凭证生命周期标识，用于在支付执行、授权核验和后续存证中稳定关联同一次授权链路 | ADD-IAC-ISS | PSD-PAY-DEL、PSD-PAY-AUP | +| 支付请求 | 买方智能体面向支付服务方构造的标准化支付执行请求，承载交易确认信息、支付工具引用、时间戳、请求唯一标识及必要签名材料。 | PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP | PSP 或相关支付受理方 | +| 支付结果 | 支付服务方返回的支付执行结果，通常包括交易流水号、关联订单标识、交易状态和交易时间信息 | PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP | 买方智能体、商户侧以及后续存证处理 | -传统商户平台下单流程以商户侧订单号连接商业交互与支付；采用 A402 时，卖方可通过 `Payment-Needed` 返回 `out_trade_no`、`resource_id` 等订单或资源标识。ACT 2.1 没有要求三类支付请求传输完整购物车，也没有把 `Payment-Needed` 等同于完整的 `CID-CART-CFM` 对象。 +## 依赖与跨域引用 +PSD-PMT-BND 和 PSD-AGT-SUB 分别提供两类支付执行所需的支付工具基础：前者提供面向委托人主账户的支付工具引用，后者提供面向特定智能体的资金隔离账户及其验证密钥。 -## 4. `PSD-PMT-BND`：支付方式绑定 +PSD-PAY-INS、PSD-PAY-DEL 和 PSD-PAY-AUP 在支付发起前，引用商业交互域形成的交易确认结果；其中，PSD-PAY-DEL 和 PSD-PAY-AUP 还需要进一步引用委托授权域提供的用户意图授权凭证。 -### 4.1 目的与前置条件 +当交易对手为卖方智能体或支付方式需动态协商时，PSD-PAY-DEL 和 PSD-PAY-AUP 还可引用 CID-PCA-NEG 形成的支付能力协商结果，以确定支付方式、支付服务方和接口端点。 -本组件为 Agent 建立可用的支付工具引用，使其能在授权范围内付款而不直接持有委托人的原始支付账户信息。 +PSD-PAY-A402 作为通用支付接入方案，可被 PSD-PAY-INS、PSD-PAY-DEL、PSD-PAY-AUP 按需引用。 -前置条件： +在采用智能体专属子账户的场景下，支付授权密文的生成、验证密钥绑定和密钥失效处理，可依赖 ASL 提供的密钥管理与安全执行能力实现。 -- 委托人主动表达为指定 Agent 开通支付能力的意愿； -- Agent 具有可被账户服务方或 PSP 稳定识别的身份； -- 服务方能够核验委托人、生成引用、管理绑定关系并查询有效状态。 +信任服务域统一维护支付相关事件类型与存证治理规则；支付服务域仅在相关组件中引用事件标识，不在本域重复定义事件结构或治理机制。 -### 4.2 流程 +# PSD-PMT-BND：支付方式绑定 +## 概述 +支付方式绑定（Payment Method Binding，PSD-PMT-BND）规定委托人向支付服务方或账户服务方完成智能体支付能力开通，并为智能体建立可用支付工具引用的基本流程和要求。 -1. 委托人主动触发开通，跳转或连接到账户服务方/PSP 的可信确认界面。 -2. 服务方核验委托人身份和绑定意愿，并展示被绑定的 Agent 与授权范围。 -3. 核验通过后生成支付 Token 或等价引用，绑定真实账户、Agent 身份和有效期/额度/商户等限制。 -4. 仅向 Agent 下发受限引用，不下发原始账户凭证。 -5. 后续每次支付时，PSP 重新检查引用状态及其与发起 Agent 的绑定一致性。 +本组件的目标是使智能体在后续支付执行过程中能够使用经过授权的支付工具完成支付，同时避免原始支付账户信息直接暴露给智能体。 -身份核验失败、Agent 未注册、账户或额度限制、引用生成失败都不得产生可继续支付的有效引用。引用过期、冻结、注销或身份不匹配时必须被后续支付检查识别。 +在智能体支付场景中，智能体不应直接持有或接触委托人的原始支付账户信息。可通过支付标记（Payment Token）或其他等价支付工具引用，将真实账户与受托智能体身份标识建立受限绑定，并可进一步配置有效期、金额上限、适用商户范围等限制条件。 -### 4.3 产品边界 +## 参与方与前置条件 +本组件涉及以下参与方：委托人、买方智能体，以及提供支付方式绑定服务的支付服务方或账户服务方。在具体实现中，支付标记服务能力可由支付服务方自身提供，也可由独立的支付标记服务方提供。 -支付宝 AI 钱包的开通、授权、检查和解绑是产品聚合生命周期。支付宝接入实现可以把其中相关结果映射为“支付工具已就绪”，但不得声称整个钱包产品等同于 `PSD-PMT-BND` 的协议消息。 +进入本组件前，应满足以下前置条件。 -## 5. `PSD-AGT-SUB`：Agent 专属子账户 ++ 委托人已建立与买方智能体的有效交互关系，并明确希望为该智能体开通支付能力。 ++ 买方智能体应已具备可被支付服务方或账户服务方识别和绑定的身份标识。 ++ 支付服务方或账户服务方应具备委托人身份核验、支付工具引用生成、绑定关系管理和有效性校验能力。 -### 5.1 目的与前置条件 +## 基本流程 +支付方式绑定宜由委托人主动触发。委托人在智能体平台发起支付开通请求后，平台宜将相关请求引导至支付服务方或账户服务方侧完成身份核验和绑定确认。 -本组件为自主性较高的 Agent 提供账户级资金隔离。它是 DEL/AUP 可选的风险控制方式，不是 A402 传输机制，也不是所有 AUP 实现的强制条件。 +**第一步是身份核验与意愿确认。**支付服务方或账户服务方应对委托人身份及绑定意愿进行核验，核验方式可包括生物识别、支付密码、动态验证码或其他实现方支持的方式。在核验过程中，支付服务方或账户服务方应向委托人明确展示本次绑定的受托智能体身份标识及相关授权范围，确保绑定行为建立在知情确认基础上。 -前置条件： +**第二步是生成与下发支付工具引用**。身份核验通过后，支付服务方或账户服务方生成支付标记，或生成其他等价的支付工具引用，并将其与委托人真实资金账户、受托智能体身份标识以及相关限制条件建立绑定关系。相关限制条件可包括有效期、金额上限及其他实现方定义的使用约束。绑定完成后，支付服务方或账户服务方将支付工具引用下发给买方智能体，供其在后续支付请求中作为付款工具标识使用。 -- 委托人主动申请为指定 Agent 建立独立资金边界； -- Agent 具有稳定、可绑定的身份； -- PSP 支持子账户开立、充值/额度、冻结、解冻、注销和状态查询。 +## 处理要求 +本组件形成的支付工具引用（支付标记），应能稳定关联以下信息：委托人的真实资金账户、受托智能体身份标识，以及该引用对象自身的有效状态。 -### 5.2 管理与密钥要求 +支付服务方或账户服务方在受理后续支付请求时，应能够校验支付工具引用是否有效，以及其与发起支付的买方智能体身份是否保持一致。 -- 子账户应绑定委托人、Agent 身份和当前状态。 -- 委托人可以充值或设置可用额度；Agent 只能在可用余额/额度内付款。 -- 支付时可以提交子账户标识及专属密钥生成的授权材料。 -- PSP 应同时验证子账户状态、Agent 绑定关系和授权材料。 -- 冻结、注销或 Agent 身份失效时，关联验证密钥必须联动失效。 -- 密钥宜在受保护环境中生成和使用；具体 KMS/安全执行实现由相应安全能力负责，PSD 不自行规定算法或硬件。 +若支付工具引用已过期、失效，或与当前智能体身份不匹配，支付服务方或账户服务方不应继续受理相关支付请求。 -失败结果至少区分账户开立/状态失败、余额或额度不足、绑定不一致、授权材料无效和密钥失效。失败不得绕过主账户隔离边界继续扣款。 +## 失败处理 +若身份核验、支付工具引用生成或绑定关系建立过程中发生失败，支付服务方或账户服务方应拒绝本次绑定请求，并返回可区分的失败结果。 -## 6. `PSD-PAY-INS`：即时支付 / L1 +失败原因的语义宜至少覆盖身份核验失败、智能体身份未注册、账户额度超限以及其他导致支付工具引用无法建立的异常情况。 -### 6.1 场景与前置条件 +绑定失败不应产生可继续用于支付的有效支付工具引用。 -INS 适用于用户实时在场并决定单笔支付的场景。授权基础是 PSP 在资金处理前取得的本笔用户确认，不要求预先签发 IAC。 +已建立的绑定关系如发生失效、冻结或注销，也应在后续支付校验中被识别为不可用状态。 -进入流程前： +# PSD-AGT-SUB：智能体专属子账户管理 +## 概述 +智能体专属子账户管理（Agent-Dedicated Sub-Account Management，PSD-AGT-SUB）规定为特定智能体开立具有资金隔离能力的专属子账户，以及与之配套的验证密钥绑定和生命周期管理要求。 +本组件的目标是为自主性较高的智能体提供账户级风险隔离机制，使委托人主账户不直接暴露于智能体自主执行的支付风险之中。 -- 已完成商业交互所需的规则前置检验与购物车确认，并取得待支付的商户侧订单信息；采用 A402 时也可由 `Payment-Needed` 取得订单或资源标识； -- Agent 持有 `PSD-PMT-BND` 输出的有效支付工具引用； -- PSP 能校验 Agent、请求完整性和支付工具引用，并能向用户提供确认界面； -- 使用 A402/MCP/API 时，所选接入方案已确定。 +## 参与方与前置条件 +本组件涉及以下参与方：委托人、买方智能体，以及负责子账户开立、验证和管理的支付服务方。 -支付请求使用商户侧订单号以及金额、币种等必要支付要素；完整购物车不是本组件规定的支付请求字段。实现不得因为前序流程包含购物车确认而虚构产品上送字段。 +进入本组件前，应满足以下前置条件。 -### 6.2 五步流程 ++ 委托人已明确希望为特定智能体建立独立的支付资金边界。 ++ 买方智能体应已具备可被识别和绑定的稳定身份标识；在专属型智能体场景下，该身份通常与委托人设备、账号或运行环境保持更强绑定关系。 ++ 支付服务方应具备子账户开立、充值、冻结、解冻、注销和状态查询等基础管理能力。 -1. **支付前置准备**：传统商户平台下单流程取得商户侧订单号；A402 流程从 `Payment-Needed` 取得 `out_trade_no`、`resource_id` 等订单或资源标识。 -2. **构造并发送即时支付请求**：至少关联请求唯一标识、商户订单、支付工具引用、金额、币种、时间戳、Agent 身份和关键要素签名。 -3. **PSP 基础校验**：检查防重放、时效、Agent 签名、工具状态和身份绑定；失败时不得进入用户确认。 -4. **用户逐笔确认**：向用户展示金额、币种、收款方和支付方式；资金处理前必须完成本笔核身确认。具体核身方式由 PSP 决定。 -5. **支付执行与状态回传**：PSP 扣划或冻结资金，向买方返回交易号、订单、状态和时间，并宜同步通知商户。 +## 子账户管理要求 +智能体专属子账户宜由委托人主动申请开立。 -支付完成后的资源访问不是 INS 的第六个支付步骤：采用 A402 时携 `Payment-Proof` 重试原资源并验凭交付；传统商户平台下单流程按其接口规范履约。 +支付服务方在开立过程中应完成委托人身份核验，并建立子账户、受托智能体身份标识和相关验证密钥之间的绑定关系。 -### 6.3 处理与错误语义 +子账户开立后，委托人可按需向其充值或设置可用额度，使智能体在既定余额或额度范围内执行支付。 -金额、币种、订单和展示给用户的信息必须与已确认交易一致。错误语义至少包括： +在后续支付过程中，买方智能体可携带子账户标识以及相应的支付授权密文发起支付，支付服务方则依据绑定关系和账户状态完成验证与处理。 -| 类别 | 处理/恢复方向 | -|---|---| -| 请求重复 | 不直接重放支付；先查询既有结果或以新的请求标识重新发起新的业务请求 | -| 请求过期 | 确认交易仍有效后生成新的时间上下文 | -| Agent 签名/完整性无效 | 修复身份、密钥或签名材料后再发起 | -| 支付工具无效或身份不匹配 | 重新绑定或更换合法支付工具，不进入确认界面 | -| 金额/订单与确认结果不一致 | 重新确认交易，不静默改写 | -| 用户取消、核身失败或超时 | 不扣款；是否重新确认由产品策略决定 | -| 支付执行失败或结果未知 | 优先查询权威结果，禁止因超时直接创建第二笔支付 | +当风控异常触发、委托人主动申请或智能体身份失效时，支付服务方应支持对子账户执行冻结或注销处理。 -## 7. `PSD-PAY-DEL`：定向委托支付 / L2 +子账户注销或失效后，其相关验证密钥也应同步失效，不应继续用于后续支付。 -### 7.1 场景与前置条件 +## 专属密钥绑定 +子账户宜配套专属验证密钥，以支持对子账户支付授权的有效验证。该验证密钥可采用非对称方案或对称方案；实现方可依据安全要求与部署条件选择适用方式。 -DEL 表达“人先决定明确标的、Agent 执行”的 L2 场景。用户在执行时可以不在场，也不需要逐笔核身；授权基础是执行时仍有效的 IAC。 +子账户开立时，相关密钥或验证材料宜在受保护执行环境中生成，并与子账户标识完成绑定注册，作为后续验证依据。 -前置条件： +在后续支付过程中，买方智能体可基于该验证密钥生成支付授权密文，支付服务方据此验证支付请求是否与当前子账户及其绑定智能体一致。 -- 用户已确认明确标的并签发有效 IAC； -- 已形成商户订单和交易确认； -- Agent 持有支付工具引用，或可用专属子账户及授权材料； -- 已确定 A402/MCP/API 接入方案； -- 身份、连接、授权和密钥实现可以支撑签名、绑定和 IAC 验证。 +当子账户被冻结或注销时，与其关联的验证密钥也应联动失效；失效后，支付服务方不应继续接受该子账户的支付请求。 -### 7.2 四步流程 +对于密钥生成、调用保护和失效处理的底层安全机制，本组件不重复定义具体实现；相关能力可由 ASL协议的安全执行与密钥管理能力提供支撑，对应模块为 `ASL-INF-SEE` 和 `ASL-INF-KMS`。 -1. **Agent 本地预检**：检查 IAC 状态和有效期、单笔/累计额度、商户范围、支付方式和工具状态；失败时不发送支付请求。 -2. **构造支付请求**：关联请求唯一标识、商户订单、完整 IAC 与 `delegation_id`、金额/币种、支付工具、时间戳、Agent 身份和关键字段签名。 -3. **PSP 权威授权核验**：依次检查防重放、Agent 签名、IAC 签名/状态/受托方、金融约束、必要的语义约束以及子账户授权材料。 -4. **支付执行与状态回传**：核验通过后扣划/冻结，返回交易号、委托标识、订单、状态和时间；Agent 仅以 PSP 成功结果更新本地累计额，PSP 宜同步通知商户。 +## **处理要求与失败处理** +本组件管理的子账户，至少应能够稳定关联以下信息：子账户标识、受托智能体身份标识、账户当前状态，以及与其关联的验证密钥状态。 -支付完成后，采用 A402 时携 Proof 重试并验凭交付；传统商户平台下单流程按其接口规范履约。该接入流程不改变 DEL 的 IAC 授权边界。 +实现方可根据业务需要进一步为子账户配置余额上限、单笔额度、累计额度、有效期或适用任务范围等限制条件，以支持更细粒度的风险隔离。 -### 7.3 处理与错误语义 +支付服务方应能够识别子账户的基本生命周期状态，至少包括可用、冻结和注销等状态，并据此决定是否接受后续支付请求。 -Agent 本地预检不能替代 PSP 权威核验。PSP 的累计额度判断必须以权威历史成功金额为准。 +当子账户未开立、余额不足、状态异常、绑定关系不一致或验证密钥无效时，支付服务方应拒绝相关支付或管理操作，并返回可区分的失败结果。 -除 INS 错误外，DEL 至少保留以下语义： +失败原因的语义宜至少覆盖身份核验失败、子账户未开立、子账户已冻结、子账户已注销、余额不足和验证密钥无效等情况。 -| 类别 | 处理/恢复方向 | -|---|---| -| IAC 过期、吊销或暂停 | 不直接重试；等待恢复或重新授权 | -| 受托 Agent 身份不匹配 | 修复授权/绑定关系，不更换身份后盲目重试 | -| 单笔或累计金额超限 | 调整交易或重新授权 | -| 商户/支付方式不在授权范围 | 更换交易方案或重新授权 | -| 余额不足 | 补足资金或更换允许的支付工具后再决定是否重试 | -| 订单/金额与确认快照不一致 | 重新确认交易，不静默沿用旧授权 | -| 子账户或授权材料无效 | 恢复账户/密钥状态或终止交易 | +# PSD-PAY-A402：基于 HTTP 402 的支付流程 +## 概述 +本组件定义买方智能体、商户/资源服务方与支付服务方之间基于 HTTP 402 状态码（Payment Required）的通用支付接入交互：买方智能体访问付费资源或服务，卖方服务方在未发现有效付款证明时返回 402 状态码和账单；买方完成符合所在支付场景约束的付款后，携带支付证明再次访问；卖方验证通过后交付资源，并完成履约确认。 -## 8. `PSD-PAY-AUP`：自主化委托支付 / L3 +本组件可被 `PSD-PAY-INS`、`PSD-PAY-DEL`、`PSD-PAY-AUP` 按需引用。当被引用时，本组件只承载支付接入交互机制，不替代各场景组件中的其他具体要求（如 IAC 约束、累计额度边界、子账户管理等）。 -### 8.1 场景与前置条件 +## 参与方与前置条件 +本组件涉及以下参与方： -AUP 表达目标驱动的 L3 自主决策与执行。用户预先确认任务并签发 `BOUNDED` IAC；交易对象、时点和执行路径可以由 Agent 在授权边界内决定，并可在一个任务周期内发生多笔支付。 ++ **买方智能体**：请求卖方资源或服务，解析支付诉求，执行委托人的授权校验，取得并提交支付证明。 ++ **卖方服务方**：提供需付费资源或服务，生成付款账单，验证支付证明，并完成资源交付或服务履约。卖方一侧可以是商户、平台、卖方智能体或其代理接口，在本组件中统一称为卖方服务方。 ++ **支付服务方（PSP）**：根据具体支付方法受理支付、生成支付证明、提供支付证明验证能力，并接收必要的履约确认。 ++ **委托人**：在`PSD-PAY-INS`场景中实时确认支付；在 `PSD-PAY-DEL`和`PSD-PAY-AUP` 场景中通过意图授权凭证或子账户等方式预先定义授权边界。 ++ **商户或资源提供方**：可与卖方服务方为同一主体，也可由卖方服务方代其提供资源访问与支付接入能力。 -前置条件： +进入本组件前，应满足以下条件： -- 使用有效的 `BOUNDED` IAC；`SPECIFIED` IAC 不构成本组件的授权基础； -- Agent 已完成任务拆解，但初始时不要求交易标的完全确定； -- Agent 持有可用支付工具，必要时使用专属子账户； -- 需要动态选择时已完成 `CID-PCA-NEG` 或等价协商； -- 正常路径不要求逐笔实时核身，但风险异常、授权模糊、价格显著波动或额度临界时可以暂停并升级给用户。 ++ 卖方服务方应可稳定识别待收费的资源、服务或订单，并具备生成对应唯一的 `resource_id` 和 `out_trade_no`的能力。 ++ 买方智能体应具备识别 HTTP 402 状态码、解析 Base64URL 编码 Header、选择支持的 `method_id` 并执行委托人授权规则校验的能力。 ++ 参与方之间已通过 `CID-PCA-NEG` 或等价机制确定可用支付方式。 -### 8.2 五步流程 +## 交互流程 +以下流程描述单次支付接入过程；在一个完整任务执行周期内，该过程可循环发生多次。 -1. 卖方按 A402/MCP/API 返回与资源或服务关联的支付要求。 -2. Agent 依据 `BOUNDED` IAC、任务状态、累计预算、单笔限额、交易对手、服务类别、支付方式和工具状态进行实时自检。 -3. 自检通过后，Agent 提交包含 `BOUNDED` IAC、`delegation_id`、交易标识、金额/币种、工具、时间和签名材料的支付请求。 -4. PSP 执行防重放、Agent/IAC、金融与语义约束、账户和风险检查。 -5. 核验通过后 PSP 处理资金并返回支付授权结果凭证、交易号、委托标识、状态和时间；Agent 只以 PSP 成功结果更新本地累计额，PSP 宜同步通知商户。 +**步骤一：请求付费资源** -支付完成后，A402 流程负责 Proof 重试、卖方验凭、资源交付与履约确认；传统商户平台下单流程按其接口规范执行。支付、Proof 验证、资源交付与履约确认仍是不同事实。 +买方智能体向卖方服务方发起资源、工具、API、数字内容或服务请求。请求可为 `GET`、`POST` 或其他由卖方服务方定义的 HTTP 方法。 -接入层 Header、基础载荷、通用状态和错误类别全部由[A402](a402.md)负责；AUP 不再重复定义。 +买方智能体首次请求时通常不携带 `Payment-Proof`；若携带，卖方服务方应先验证其格式、有效期、交易绑定关系及是否已被重复履约。 -### 8.3 处理与错误边界 +**步骤二：返回支付诉求** -AUP 复用 DEL 的 IAC 已过期/吊销/暂停、身份不匹配、单笔/累计金额超限、余额不足和商户不在范围内等错误语义。接入方案相关的 Proof 验证等错误由 A402 或对应接入方案定义。ACT 2.1 没有冻结 AUP 专属机器错误码；实现必须报告失败发生在哪一阶段，不能把支付成功等同于资源已交付。 +若当前请求没有可用支付证明，或支付证明未通过验证，卖方服务方应返回 HTTP `402 Payment Required`，并在 `Payment-Needed` Header 中携带经 Base64URL 编码的支付账单。 -## 9. 共同安全与处理不变量 +```plain +HTTP/1.1 402 Payment Required +Payment-Needed: +Content-Type: application/json -1. 场景授权检查先于资金处理。 -2. Agent 本地检查不能替代 PSP 权威核验。 -3. 请求唯一标识、时间窗和签名/等价完整性保护用于防重放和防篡改。 -4. 支付成功、Proof 有效、资源已交付和履约已确认是不同事实。 -5. 支付请求重试、原资源请求重试和履约确认重试是不同操作。 -6. A402、MCP 或 API 的选择不得改变 INS/DEL/AUP 的授权等级。 -7. 原始账户、私钥和完整 Proof 不得进入不受信的 Agent 上下文、日志或演示事件。 -8. 权威支付结果未知时先查询，不因超时自动创建第二笔支付。 +{ + "error": "Payment Needed", + "message": "请先支付 0.01 CNY 以访问资源", + "resource_id": "RES_1739836600000_abc123" +} +``` -## 10. A402 引用 +响应体仅用于调试、日志和人类可读提示；买方智能体用于机器处理的支付信息应以 `Payment-Needed` Header 为准。 -采用 A402 时，场景组件向[A402 接入协议](a402.md)提供已完成的授权判断和支付方法上下文。A402 负责： +**步骤三：买方进行场景校验与支付** -- `402 Payment Required`； -- `Payment-Needed`、`Payment-Proof` 和可选 `Payment-Validation`； -- `method_id` 与方法扩展； -- Proof 验证、防重放、原请求关联和资源放行； -- 通用状态、错误、超时、幂等与恢复语义。 +买方智能体解析 `Payment-Needed` 后，应先执行所在场景的前置判断： -采用 MCP/API 时，应提供等价结果并建立到通用状态的显式映射。ACT 2.1 没有为这些接口定义新的消息格式。 ++ 在`PSD-PAY-INS`场景中，应引导委托人进行实时支付确认。 ++ 在 `PSD-PAY-DEL`场景中，应校验 SPECIFIED IAC 有效性、金额、累计额度、商户范围和允许支付方式。 ++ 在 `PSD-PAY-AUP`场景中，应校验 BOUNDED IAC 有效性、任务范围、累计预算、资源类别和智能体专属子账户状态。 -## 11. 来源 +任一条件不满足时，买方智能体不应继续发起支付，并应按预设策略终止本次交易、切换交易对手或通知委托人处理。 -- PSD 相关网站参考：[支付服务域](https://www.act-protocol.com/documentation/payment)；未标明 ACT 2.1 的网页内容不是本 Release 的规范来源 -- 上位参考：[协议概览](https://www.act-protocol.com/documentation/overview) -- 支付宝产品事实：[AI 按量付费接入指南](https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html) +校验通过后，买方智能体应依据 `method_id` 对应的支付方法规范向 PSP 或方法指定端点发起支付，并取得支付授权结果凭证。支付方式、支付工具、资金扣划、IAC 核验及风控策略仍由相应 PSD 场景组件和支付方法组件规定，A402 不重复定义。 + +**步骤四：携带支付证明重试访问** + +支付成功后，买方智能体应对原资源或服务发起新的请求，并在 `Payment-Proof` Header 中携带支付证明、PSP 交易流水号和买方会话标识等信息。 + +```plain +GET /market/XXXX/trend HTTP/1.1 +Payment-Proof: +``` + +**步骤五：卖方验证支付证明** + +卖方服务方应解析 `Payment-Proof`，并依据 `method_id` 对应方法规范调用 PSP 或受信验证服务，对支付证明进行以下核验： + ++ **凭证有效性**：核验 `payment_proof` 的签名、有效期、吊销状态等，确认凭证本身合法有效。 ++ **防重放性**：核验该凭证是否已被重复履约，防止同一支付证明被多次用于资源访问。 ++ **一致性**：核验凭证中的 `trade_no`、`resource_id` 等字段与当前资源访问请求的一致性，确认凭证对应的就是本次请求的付费资源。 + +任一核验未通过时，卖方服务方应拒绝付费资源访问，并返回可被买方智能体识别的错误语义。 + +**步骤六：交付资源与履约确认** + +验凭通过后，卖方服务方应返回资源内容、启动服务履约或确认订单可继续处理。卖方服务方可在成功响应中通过 `Payment-Validation` Header 返回机器可读的验证及履约状态。 + +```plain +HTTP/1.1 200 OK +Payment-Validation: +Content-Type: application/json + +{ + "status": "PAYMENT_VALIDATED", + "trade_no": "2026040900828111317760000001xxxx", + "resource_id": "RES_1739836600000_abc123", + "resource": "XXXXXXXXXXXX" +} +``` + +卖方服务方在完成资源交付或服务履约后，应按具体支付方法规范向 PSP 发起履约确认。 + +支付交易完成后，PSP 宜异步上报 `act:payment:transaction-completed` 存证事件，为后续审计、争议处理和任务账单回溯提供事实依据。 + +## HTTP Header 扩展字段 +本组件使用以下三类 HTTP Header 字段。三个 Header 的 Header Value 应采用 Base64URL 编码的 UTF-8 JSON 格式。 + +| Header 名称 | 使用方 | 使用时机 | +| --- | --- | --- | +| `Payment-Needed` | 卖方服务方 | `HTTP 402` 响应时，用于声明支付诉求及核心参数。 | +| `Payment-Proof` | 买方智能体 | 买方携带支付授权结果凭证再次请求资源或服务时使用。 | +| `Payment-Validation` | 卖方服务方 | 卖方在支付授权结果凭证验证完成后的结果返回。如验证通过直接返回付费资源或服务；如验证未通过返回错误码。 | + +## 支付方法（method_id） +本组件通过 `method_id` 标识具体支付方法，并由对应的方法规范文档独立维护相关规则。 + +每个支付方法对应独立的方法规范文档，用于定义该方法的请求构造方式、扩展字段要求、签名算法、PSP 核验逻辑、支付授权结果凭证返回方式及错误码分配规则。 + +在进入本组件前，买卖双方可通过 `CID-PCA-NEG` 协商并确认 `method_id`、`psp_id`、`endpoint` 与 `method_schema_url`，作为后续支付请求构造与执行的直接输入。 + +## 支付载荷（Payload）结构 +支付载荷在结构上划分为两个层次：基础载荷字段与支付方法扩展字段。基础载荷字段用于定义各支付方法共享的标准要素集合，以保证不同实现之间的互操作性。支付方法扩展字段用于承载具体支付方法特有的业务参数，但不得改变基础载荷字段的标准语义。 + +三个 Header 的载荷均采用 `Protocol + method` 的两层结构（Base64URL 编码前）。 + +### 基础载荷字段 +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `method_id` | string | 支付方法标识符，用于标识本次交易采用的具体支付方法。 | +| `out_trade_no` | string | 外部订单号，用于幂等控制和交易关联。 | +| `amount` | string | 支付金额，宜采用字符串格式以避免浮点精度问题。 | +| `currency` | string | 交易币种，宜采用标准货币代码表示。 | +| `resource_id` | string | 资源标识，用于绑定支付与资源访问，防止凭证挪用。 | +| `pay_before` | string | 支付截止时间，用于限定支付有效时间窗口并降低重放风险。 | +| `seller_unique_id` | string | 卖方服务方唯一标识。 | +| `buyer_unique_id` | string | 买方智能体唯一标识。 | +| `payment_proof` | string | 支付授权结果凭证，用于标识支付授权成功结果。 | +| `trade_no` | string | 交易流水号或交易唯一标识号，由 PSP 生成并用于交易追踪。 | +| `expires_at` | string | 支付授权结果凭证的有效截止时间。 | +| `signer_id` | string | 签名者唯一标识，用于标识生成报文签名的主体。 | +| `signature_content` | string | 签名值，用于保证报文完整性与来源可验证性。 | +| `signature_type` | string | 签名算法类型，用于指示报文签名验证所需的算法标识。 | + +### 支付方法扩展字段 +支付方法扩展字段用于适配具体支付方法的业务场景，可由买卖双方及 PSP 在方法规范允许范围内附加方法特定参数。这类扩展参数可包括账户标识映射键、商品信息、签名覆盖范围声明或其他的支付方法专属属性。 + +扩展字段的定义、约束及使用方式，应由对应的支付方法规范文档独立说明。 + +### Payment-Needed 载荷示例 +采用 `Protocol + method` 的两层结构（Base64URL 编码前）： + +```json +{ + "protocol": { + "out_trade_no": "ORDER_1739836600000_abc123", + "amount": "0.01", + "currency": "CNY", + "resource_id": "RES_1739836600000_abc123", + "pay_before": "2026-03-25T12:00:00+08:00", + "seller_signature": "YYYYxxxx=", + "seller_sign_type": "RSA2", + "seller_unique_id": "2088xxxxxxxx" + }, + "method": { + "seller_name": "测试商家", + "seller_id": "2088xxxxxxxx", + "seller_app_id": "app_123456", + "goods_name": "测试商品", + "seller_unique_id_key": "seller_id", + "service_id": "xxxx_12344" + } +} +``` + +### Payment-Proof 载荷示例 +采用 `Protocol + method` 的两层结构（Base64URL 编码前）： + +```json +{ + "protocol": { + "payment_proof": "7cf8a6a93c924e13eaa4bf20c3a487f30d1fbdb759a1f229b4091b7d0158xxxx", + "trade_no": "2026040900828111317760000001xxxx" + }, + "method": { + "client_session": "xxxxxxxxxxxxxsCiAgICAic2Vzc2lvbklkIjogInh4IiwKICAgICJzaWduYXR1cmUiOiAi5Yqg562+5ZCO57uT5p6c77yM6YCa6L+HY3JlZGVudGlhbElk5Yqg562+YWdlbnRUb2tlbiArIHNlc3Npb25JZCkiCn0=" + } +} +``` + +## 交易状态 +本组件定义下述交易状态，各支付方法内部状态应映射到下列状态后再对外输出。 + +| 状态码 | 状态名 | 说明 | 可转入状态 | +| --- | --- | --- | --- | +| `CREATE` | 创建 | 初始状态 | `WAIT_BUYER_PAY` | +| `WAIT_BUYER_PAY` | 等待买家支付 | 买方尚未完成支付 | `WAIT_SELLER_FULFILLMENT`、`TRADE_CLOSED` | +| `WAIT_SELLER_FULFILLMENT` | 等待卖方履约 | 买方已支付，等待卖方服务方履约 | `WAIT_BUYER_RECEIPT`、`TRADE_CLOSED` | +| `WAIT_BUYER_RECEIPT` | 等待买家回执 | 卖方已履约，等待买方确认 | `TRADE_FINISHED`、`TRADE_CLOSED` | +| `TRADE_FINISHED` | 交易完成 | 终态 | 无 | +| `TRADE_CLOSED` | 交易关闭 | 终态，适用于退款或取消后的关闭状态 | 无 | + +## 错误响应 +错误响应宜覆盖签名校验、请求参数、身份校验、额度与资产、风控、交易状态、支付授权结果凭证验证及系统异常等语义类别。买方智能体和卖方服务方可依据错误语义决定是否重试、切换支付方式、更换交易对手或终止本次交易。 + +| 语义类别 | 说明 | 重试建议 | +| --- | --- | --- | +| 签名校验错误 | 签名验证失败，或签名类型不受支持 | 一般不建议直接重试，应先检查签名材料、签名者标识及算法配置 | +| 请求参数错误 | 参数非法、金额格式错误、时间格式错误，或请求已过期 | 修正报文后可重试；若已过期，应重新获取支付诉求 | +| 协议校验错误 | 协议不存在、协议无效，或方法规范不匹配 | 不建议直接重试，应先校验支付方法配置与协议版本 | +| 智能体身份校验错误 | 买方智能体或卖方服务方身份验证失败 | 不建议直接重试，应先检查身份文档、公钥材料及绑定关系 | +| 额度与资产校验错误 | 额度不足、余额不足，或资产账户校验失败 | 可在补足余额、调整额度或更换支付工具后重试 | +| 限权与风控错误 | 用户被限权、命中风控策略，或授权边界不满足 | 一般不建议立即重试，应先等待风控解除或重新取得授权 | +| 交易状态错误 | 交易不存在，或当前交易状态不允许继续处理 | 不建议直接重试，应先查询交易状态并做幂等处理 | +| 退款错误 | 退款金额超限，或退款处理失败 | 视失败原因处理；必要时转人工或走后续补偿流程 | +| 履约回执错误 | 履约失败，或履约结果回执异常 | 可结合幂等策略与履约状态查询结果决定是否重试 | +| 支付授权结果凭证验证错误 | 凭证为空、凭证已过期或不存在、凭证状态无效，或其与当前主体、交易、资源不一致 | 一般不建议直接重试，应重新获取有效凭证或重新发起支付 | +| 系统错误 | 系统内部异常或下游服务故障 | 可按指数退避策略有限次重试，超过阈值后转人工或告警 | + +# PSD-PAY-INS：用户即时支付（L1场景） +## 概述 +用户即时支付（Instant Payment，PSD-PAY-INS）适用于委托人实时在场，并对本次购买行为进行即时确认后完成支付的场景。 + +在该场景下，委托人全程参与购买决策闭环，因此无需预先签发意图授权凭证；委托人在支付服务方收银台完成的即时确认行为，本身即构成本次支付的合法授权依据。 + +本组件对应场景中，交易有 AI 参与，最终由人决策和执行，表现为指令驱动、笔笔确认，支付决策权保留在用户手中。资金扣划前，支付服务方应完成用户核身确认（如人脸/指纹/扫码等），智能体角色为"代为下单与发起支付请求"。从支付安全风险防控角度，本组件中所描述的场景又称为L1场景。 + +> 注：当前协议中仅定义了由智能体向支付服务方发起支付请求的模式，后续将扩展支持由商户向支付服务方发起支付请求的模式。 +> + +## 前置条件 +本组件涉及以下参与方：委托人、买方智能体、卖方或商户侧系统，以及负责支付受理、校验和资金处理的支付服务方。 + +进入本组件前，应满足以下前置条件。 + ++ 委托人已向买方智能体表达实时购买意图，且买方智能体已在商业交互域完成规则前置检验与购物车确认流程，获得待支付的商户侧订单信息。 ++ 买方智能体应已持有在 `PSD-PMT-BND` 中为本次支付场景建立的有效支付工具引用。 ++ 支付服务方应能够校验支付工具引用有效性、验证买方智能体身份与请求完整性，并在校验通过后唤起面向委托人的支付收银台或确认界面。 ++ 支付交互流程可基于`PSD-PAY-A402`流程，也可基于传统的商户平台下单支付流程；接口实现方式可包括 MCP 接口、API 接口等，由参与方依据能力与场景协商确定。 + +## 流程步骤 +以下流程描述单次即时支付过程。买方智能体与支付服务方应依据所确定的支付交互流程（`PSD-PAY-A402`或传统商户平台下单支付）及对应接口实现方式（MCP 接口、API 接口等）执行相应交互规则。 + +**步骤一：支付前置准备** + +买方智能体在与卖方服务方或商户侧系统完成商业交互后，应取得本次支付所必需的交易标识信息，用于连接前端商业意图与后端资金清算处理。具体形式依据所采用的支付交互流程而定： + ++ 当采用商户平台下单支付流程时，买方智能体应在商业交互域完成规则前置检验与购物车确认流程，并取得商户侧订单号。 ++ 当采用 `PSD-PAY-A402` 接入流程时，买方智能体可在请求付费资源或服务时，由卖方服务方通过 `HTTP 402 Payment Required` 响应及 `Payment-Needed` 返回本次支付所对应的订单或资源标识（如 `out_trade_no`、`resource_id` 等）。 + +**步骤二：构造并发送即时支付请求** + +买方智能体向支付服务方发起即时支付请求时，请求内容宜至少包含以下核心要素。 + ++ 本次请求的全局唯一标识，用于防重放校验。 ++ 商户侧订单号，用于支付商品信息的一致性校验。 ++ 前期绑定得到的支付工具引用。 ++ 本次支付金额及币种。 ++ 请求时间戳，用于支付服务方执行时效性验证。 ++ 买方智能体身份标识，以及对本次请求关键要素的签名。 + +**步骤三：支付服务方基础校验** + +支付服务方在接收到即时支付请求后，应先完成基础校验，基础校验至少包括请求唯一标识防重放校验、请求时间戳时效性校验、买方智能体签名有效性校验，以及支付工具引用有效性校验。 + +对于支付工具引用，支付服务方应确认其未过期、未失效，且与发起本次支付请求的买方智能体身份绑定关系一致。 + +上述任一校验未通过时，支付服务方不应继续进入收银台确认流程，而应直接返回对应失败结果。 + +**步骤四：唤起收银台与委托人即时确认** + +在基础校验全部通过后，支付服务方应向委托人唤起支付收银台或确认弹窗。 + +收银台中至少应展示本次支付金额及币种、收款商户名称和支付方式，且展示内容应与即时支付请求中的对应字段保持一致。 + +委托人通过生物识别、支付密码、动态验证码或其他支付服务方支持的方式完成确认后，支付服务方应记录本次确认所使用的核身方式及确认时间戳，作为本次支付的授权证据。 + +本步骤为 L1 场景的核心特征：资金扣划前，支付服务方应完成用户笔笔核身确认。核身方式（如人脸/指纹/扫码/密码/验证码等）由支付服务方依据风控策略和终端环境决定，本协议不做具体规定。 + +**步骤五：支付执行与状态回传。** + +委托人完成即时确认后，支付服务方应将支付工具引用解析到对应的真实支付账户，并执行资金扣划或额度冻结处理。 + +支付服务方应将支付结果同步返回买方智能体，返回内容宜至少包括支付服务方交易流水号、商户侧订单号、交易状态和交易时间戳。 + +支付服务方宜同步将支付结果通知商户侧系统，以支持订单状态更新和后续履约处理。 + +支付交易完成后，支付服务方宜异步上报 `act:payment:transaction-completed` 存证事件，以支持后续争议处理和审计追溯。 + +> **注：**支付完成后，买方智能体可依据所采用的支付交互流程访问付费资源或服务并触发履约： +> +> + 当采用 `PSD-PAY-A402` 接入流程时，买方智能体可携带 `Payment-Proof` 再次访问付费资源或服务，卖方服务方验证凭证后放行资源或启动履约，具体交互细节由 `PSD-PAY-A402` 规范定义。 +> + 当采用商户平台下单支付流程时，资源访问与履约由该流程对应的接口规范定义。 +> +> 无论采用何种支付交互流程，相关接口均可通过 MCP 接口、API 接口等方式实现。 +> + +## 处理要求 ++ 买方智能体在构造即时支付请求时，应确保支付金额、币种和商户侧订单信息保持一致，不应擅自修改已确认的交易核心要素。 ++ 支付服务方在唤起收银台前，应完成所有基础校验；未通过校验的请求不应进入收银台确认流程。 ++ 支付服务方展示给委托人的支付信息，应与请求中相应字段严格一致，以确保委托人是在充分知情的条件下完成确认。 ++ 在 L1 场景中，支付服务方应在资金扣划前完成用户核身确认；未完成核身确认的支付请求不应进入资金扣划阶段。核身方式由支付服务方依据风控策略和终端环境决定。 + +## 错误响应 +即时支付中的错误响应，宜覆盖以下语义类别。 + +| **语义类别** | **说明** | **重试建议** | +| --- | --- | --- | +| 请求重复 | 请求唯一标识已被使用，疑似重放攻击。 | 不应直接重试；应更换请求唯一标识后重新发起。 | +| 请求已过期 | 请求时间戳超出支付服务方接受的有效窗口。 | 可在重新生成时间戳并确认请求仍有效后重试。 | +| 智能体签名无效 | 买方智能体签名验证失败。 | 不应直接重试；应先修正签名材料或校验身份绑定关系。 | +| 支付工具引用无效 | 支付工具引用不存在、已失效、已过期或不可用。 | 不应直接重试；应先重新绑定或更换可用支付工具。 | +| 支付工具引用与智能体身份不匹配 | 当前支付工具引用与发起请求的买方智能体身份绑定关系不一致。 | 不应直接重试；应先修正绑定关系或更换合法发起方。 | +| 用户确认失败 | 委托人在收银台核身失败、取消确认或未在规定时间内完成确认。 | 可按业务策略决定是否允许用户重新发起确认。 | +| 支付执行失败 | 基础校验与用户确认通过后，资金扣划、额度冻结或通道路由阶段发生失败。 | 可根据失败原因决定是否允许重试；通道瞬时异常可重试，账户或风控异常通常不宜直接重试。 | + +# PSD-PAY-DEL：用户定向委托支付（L2场景） +## 概述 +用户定向委托支付（Delegated Payment，PSD-PAY-DEL）适用于委托人不在场情形下，由买方智能体依据委托人预先签发的意图授权凭证，在授权边界内自主完成程序化支付的场景。 + +本组件对应场景中，交易由人先决策、由 AI 负责执行。委托人预先明确购买标的并签发意图授权凭证，买方智能体在授权边界内执行既定支付，无需用户笔笔核身。与 `PSD-PAY-INS` 不同，本组件的授权基础不是支付服务方收银台上的委托人实时确认，而是委托人预先签发且在支付时仍然有效的意图授权凭证。从支付安全风险防控角度，本组件中所描述的场景又称为L2场景。 + +> 注：当前协议中仅定义了由智能体向支付服务方发起支付请求的模式，后续将扩展支持由商户向支付服务方发起支付请求的模式。 +> + +## 适用场景与前置条件 +本组件适用于用户不在场（Human-Not-Present）且购买标的已在初始交互中明确的定向委托支付场景。 + +在平台型智能体场景中，为防范跨用户越权与身份混淆，支付核验应同时关注平台智能体身份与具体委托人身份的绑定关系；在专属型智能体场景中，支付核验通常直接锚定专属智能体身份，并可进一步结合专属子账户实现资金隔离。 + +从支付交互流程角度，L2 场景通常采用传统商户平台下单支付流程（委托人预先明确购买标的，智能体在商户侧完成下单与支付）；当智能体访问的标的以付费资源或服务形式提供时，也可采用 PSD-PAY-A402 接入流程，由卖方服务方通过 HTTP 402 发起支付诉求。两种支付交互流程均可通过 MCP 接口、API 接口等方式实现。 + +进入本组件前，应满足以下前置条件。 + ++ 委托人应已完成意图确认并向买方智能体签发有效的意图授权凭证（IAC）；买方智能体已在商业交互域完成规则前置检验与购物车确认，获得待支付的商户侧订单信息。 ++ 在支付工具层面，买方智能体应已持有可用的支付工具引用，或已具备可用的智能体专属子账户及其支付授权密文。 ++ 对于请求签名保护、身份绑定、授权凭证校验和底层密钥调用机制，本组件不重复定义其安全实现，相关能力可由 ASL 的身份、连接、授权和密钥管理能力提供支撑。 + +## 流程步骤 +以下流程描述单次定向委托支付过程。买方智能体与支付服务方应依据所确定的支付交互流程及对应接口实现方式执行相应交互规则。 + +**步骤一：智能体端规则自检** + +买方智能体在构造委托支付请求前，应结合当前持有的 IAC 执行本地预检，至少包括：IAC 处于有效状态、当前时间落在 IAC 授权有效期范围内、本次支付金额不超过单笔金额上限、本次金额与本地缓存的累计扣款确认额之和不超过授权总额上限、目标商户位于允许范围内，以及拟使用支付方式属于允许支付方式列表。 + +本地预检是买方智能体的前置过滤机制；若预检未通过，买方智能体不应继续发起委托支付请求。本地缓存的累计扣款确认额，应以支付服务方返回的支付成功交易金额计算；首次支付前默认为零。 + +**步骤二：构造并发送委托支付请求** + +买方智能体向支付服务方发起委托支付请求时，请求内容宜至少包括：请求唯一标识、商户侧订单号、完整的意图授权凭证及其委托标识、本次支付金额与币种、支付工具凭据、请求时间戳，以及买方智能体身份标识和对关键要素的签名。 + +当未使用专属子账户时，支付工具凭据通常为 `PSD-PMT-BND` 输出的支付工具引用；当使用专属子账户时，支付工具凭据应为子账户标识及其专属密钥生成的支付授权密文。 + +签名覆盖范围宜至少包括请求唯一标识、委托标识、商户侧订单号、支付金额、币种和请求时间戳，以保障关键要素不可被篡改。 + +**步骤三：支付服务方侧授权核验** + +支付服务方接收到委托支付请求后，应按顺序完成防重放校验、买方智能体签名验证、IAC 有效性核验、金融层约束核验，以及必要时的语义层约束核验。其中： + ++ IAC 有效性核验至少包括：验证 IAC 签名有效、IAC 未过期未吊销未暂停、IAC 中受托智能体标识与请求中买方智能体身份标识一致，以及委托模式属于本协议定义的有效枚举值。 ++ 金融层约束核验至少包括单笔金额校验、累计额度校验和支付方式匹配校验。 ++ 语义层约束核验可按实现需要执行，例如核验收款商户是否位于允许商户范围内，或比对请求要素与用户原始意图是否一致。 ++ 若使用专属子账户，支付服务方还应对子账户专属密钥生成的支付授权密文进行有效性验证。 + +任一核验未通过时，支付服务方应拒绝本次请求，并返回相应失败语义。 + +**步骤四：支付执行与状态回传** + +所有核验通过后，支付服务方应完成资金扣划或额度冻结；在采用专属子账户时，资金应直接从该子账户划扣或冻结。 + +支付服务方应将支付结果同步返回买方智能体，返回内容宜至少包括支付服务方生成的全局唯一交易流水号、本次支付关联的委托标识、商户侧订单号、交易状态以及交易时间戳。 + +买方智能体在收到成功响应后，应以支付服务方返回的支付成功交易金额确认额更新本地累计扣款缓存。 + +支付服务方宜同步将支付结果通知商户侧系统，以支持订单状态更新和后续履约处理。 + +支付交易完成后，支付服务方宜异步上报 `act:payment:transaction-completed` 存证事件，以支持后续争议处理和审计追溯。 + +> 注：支付完成后，买方智能体可依据所采用的支付交互流程访问付费资源或服务并触发履约： +> +> + 当采用 `PSD-PAY-A402` 接入流程时，买方智能体可携带 `Payment-Proof` 再次访问付费资源或服务，卖方服务方验证凭证后放行资源或启动履约，具体交互细节由 `PSD-PAY-A402` 规范定义。 +> + 当采用传统商户平台下单支付流程时，资源访问与履约由该流程对应的接口规范定义。 +> +> 无论采用何种支付交互流程，相关接口均可通过 MCP 接口、API 接口等方式实现。 +> + +## 处理要求 ++ 买方智能体在发起委托支付前，应先完成本地预检，不应将明显超出 IAC 授权边界的请求继续发送给支付服务方。 ++ 买方智能体构造的委托支付请求，应确保支付金额、支付币种和商户侧订单号与前序购物车确认结果保持一致。 ++ 支付服务方在执行资金处理前，应完成 IAC 有效性核验和约束核验，不应将未通过核验的请求继续进入扣款阶段。 ++ 当采用专属子账户模式时，支付服务方除核验 IAC 外，还应校验子账户状态及其支付授权密文是否有效，并确认其与当前买方智能体身份及子账户绑定关系保持有效。 ++ 支付服务方对累计额度的判断，应以其自身确认的历史成功交易金额为准，而不应仅依赖买方智能体本地声明。 ++ 委托支付的授权效力应严格受限于 IAC 所定义的边界，不应因为支付请求被程序化执行而突破原始授权范围。 + +## 错误响应 +在`PSD-PAY-INS` 组件定义的错误响应语义基础上，本节主要扩展定义与使用意图授权凭证（IAC）和额度边界相关的错误响应语义。 + +| **语义类别** | **说明** | **重试建议** | +| --- | --- | --- | +| IAC 已过期 | 意图授权凭证已超过有效期，不可继续作为本次委托支付的授权依据。 | 不应直接重试；应重新取得有效授权。 | +| IAC 已吊销 | 意图授权凭证已被吊销，不可继续用于支付。 | 不应直接重试。 | +| IAC 已暂停 | 意图授权凭证当前处于暂停状态，不可用于新的支付请求。 | 通常不应直接重试；应等待恢复或重新授权。 | +| 智能体身份不匹配 | IAC 中受托智能体标识与请求中的买方智能体身份标识不一致。 | 不应直接重试；应修正绑定关系或更换合法发起方。 | +| 单笔金额超限 | 本次支付金额超出 IAC 设定的单笔金额上限。 | 不应直接重试；应调整金额或重新授权。 | +| 累计金额超限 | 本次支付金额与已确认累计金额之和超出 IAC 设定的授权总额上限。 | 不应直接重试；应调整额度或重新授权。 | +| 余额不足 | 扣款账户或专属子账户余额不足，无法完成本次支付。 | 可按业务策略决定是否在补足余额后重试。 | +| 商户不在范围内 | 收款商户不在 IAC 允许的商户范围内。 | 不应直接重试；应更换商户或重新授权。 | + +# PSD-PAY-AUP：自主化委托支付（L3场景） +## 概述 +自主化委托支付（Autonomous Delegated Payment，AUP）适用于委托人不在场情形下，由买方智能体依据委托人预先签发的 `BOUNDED` 模式意图授权凭证，在授权边界内自主开展多轮商业决策与支付的场景。 + +与 `PSD-PAY-DEL` 相同，本组件的授权基础不是支付服务方收银台上的委托人实时确认，而是委托人预先签发且在支付时仍然有效的意图授权凭证。区别在于，`PSD-PAY-DEL`场景的购买标的已在初始交互中明确，买方智能体按照指令执行支付，而本场景的买方智能体在授权边界内自主决定交易对象、交易时点及执行路径，并可在一个任务周期内发起多笔支付。从支付安全风险防控角度，本组件中所描述的场景又称为L3场景。 + +## 参与方与前置条件 +本组件涉及买方智能体、卖方服务方、支付服务方 PSP，以及在需要时提供上游授权依据的委托授权域相关能力。其中，买方智能体负责自主决策与支付发起，卖方服务方负责提供资源或服务，PSP 负责支付受理、核验、资金处理与结果返回。 + +在平台型智能体场景中，为防范跨用户越权与身份混淆，支付核验应同时关注平台智能体身份与具体委托人身份的绑定关系；在专属型智能体场景中，支付核验通常直接锚定专属智能体身份，并可进一步结合专属子账户实现资金隔离。 + +从支付交互流程角度，L3 场景下买方智能体在自主探索付费资源或服务过程中，通常采用 `PSD-PAY-A402` 接入流程（由卖方服务方通过 HTTP 402 发起支付诉求）；也可采用传统商户平台下单支付流程或其他接入方案。两种支付交互流程均可通过 MCP 接口、API 接口等方式实现。 + +进入本组件前，应满足以下前置条件。 + ++ 委托人已完成自主委托任务确认，并签发有效的 `BOUNDED` 模式意图授权凭证。 ++ 买方智能体已完成任务拆解，并获得待访问的资源或服务目标。 ++ 买方智能体已具备可用的支付工具；在自主委托场景下，宜结合智能体专属子账户及其配套专属密钥能力完成支付授权。 ++ 在需要时，买卖双方可依据 `CID-PCA-NEG` 完成支付能力协商，明确后续支付所采用的支付方法、支付服务方、目标接口地址及对应的载荷结构说明。 ++ 对于请求签名保护、身份绑定、授权凭证校验和底层密钥调用机制，本组件不重复定义其安全实现，相关能力可由 ASL 的身份、连接、授权和密钥管理能力提供支撑。 + +## 流程步骤 +以下流程描述单次自主化委托支付过程；在一个完整任务执行周期内，该过程可循环发生多次。流程中涉及支付接入方案交互的步骤，买方智能体与卖方服务方应依据所采用的支付交互流程（`PSD-PAY-A402` 或传统商户平台下单支付流程）及对应接口实现方式（MCP 接口、API 接口等）执行相应交互规则。 + +**步骤一：卖方服务方返回支付诉求** + +买方智能体向卖方服务方请求资源或服务时，若该资源或服务需要付费，卖方服务方应按所采用的支付交互流程返回支付诉求。当采用 `PSD-PAY-A402` 接入流程时，卖方服务方应返回 `HTTP 402 Payment Required` 状态码，并通过 `Payment-Needed` 响应头声明本次支付的核心参数；当采用传统商户平台下单支付流程时，应按对应流程规范返回等价的支付诉求信息。该响应用于向买方智能体明确本次访问所对应的支付要求、支付时间窗口以及后续请求构造依据。 + +**步骤二：买方智能体执行规则实时自检** + +买方智能体在决定是否继续支付前，应结合当前持有的 `BOUNDED` 模式意图授权凭证及本地任务状态执行规则实时自检，自检内容至少包括： + ++ 当前时间是否仍在 IAC 授权有效期内； ++ 累计支付金额与本次金额之和是否超出 IAC 授权总额上限； ++ 本次支付金额是否超出 IAC 单笔金额上限； ++ 交易对手及服务类别是否满足 IAC 约束； ++ 拟使用支付方式是否在 IAC 允许的支付方式列表内； ++ 拟使用支付工具（含专属子账户）状态是否可用。 + +本地缓存的累计支付确认额，应以 PSP 返回的支付成功交易金额计算；首次支付前默认为零。 + +任一条件不满足时，买方智能体不应继续发起支付，并应按预设策略终止本次交易、切换交易对手或通知委托人处理。 + +**步骤三：买方智能体提交支付请求** + +若自检通过，买方智能体应依据本组件场景约束及所采用接入方案的规范构造支付请求，并向 PSP 提交处理。 + +支付请求中应包含本次支付所依据的 `BOUNDED` 模式意图授权凭证及其委托标识、交易标识信息、支付金额与币种、支付工具凭据、请求时间信息，以及买方智能体对关键要素的签名。 + +当未使用专属子账户时，支付工具凭据通常为 `PSD-PMT-BND` 输出的支付工具引用；当使用专属子账户时，支付工具凭据应为子账户标识及其专属密钥生成的支付授权密文，与 `PSD-PAY-DEL` 的支付工具凭据规则一致。 + +**步骤四：PSP 核验** + +PSP 接收到支付请求后，应依次完成以下核验： + ++ 防重放校验、买方智能体签名验证； ++ `BOUNDED` 模式意图授权凭证有效性核验（签名有效、未过期未吊销未暂停、受托智能体标识与请求中买方智能体身份标识一致、委托模式属于有效枚举值）； ++ 金融层约束核验（单笔金额上限、累计额度上限、支付方式匹配）； ++ 语义层约束核验（收款商户是否位于 IAC 允许范围内、请求要素与用户原始意图是否一致）； ++ 账户状态、余额和风控策略校验。 + +若使用专属子账户，PSP 还应验证子账户专属密钥生成的支付授权密文的有效性，并核验该子账户余额或可用额度状态。任一核验未通过时，PSP 应拒绝本次请求，并返回相应失败语义。 + +**步骤五：支付执行与状态回传** + +全部核验通过后，PSP 应执行资金扣划或额度冻结；在采用专属子账户时，资金应直接从该子账户划扣或冻结。PSP 向买方智能体返回支付授权结果凭证，返回内容宜至少包括支付服务方生成的全局唯一交易流水号、本次支付关联的委托标识、交易状态以及交易时间戳。 + +买方智能体在收到成功响应后，应以 PSP 返回的支付成功交易金额确认额更新本地累计扣款缓存。PSP 宜同步将支付结果通知商户侧系统，以支持订单状态更新和后续履约处理。 + +支付交易完成后，PSP 宜异步上报 `act:payment:transaction-completed` 存证事件，为后续审计、争议处理和任务账单回溯提供事实依据。 + +> 注：支付完成后的资源访问、凭证验证与履约交付，依据所采用的支付交互流程执行： +> +> + 当采用 `PSD-PAY-A402` 接入流程时，买方智能体在请求头中携带 `Payment-Proof` 再次访问资源；卖方服务方向 PSP 核验凭证有效性、防重复性及与当前资源访问请求的一致性，验证通过后通过 `Payment-Validation` 响应头返回验证结果并放行资源或启动履约。具体交互细节由 `PSD-PAY-A402` 规范定义。 +> + 当采用传统商户平台下单支付流程时，资源访问、凭证验证与履约交付由该流程对应的接口规范定义。 +> +> 无论采用何种支付交互流程，相关接口均可通过 MCP 接口、API 接口等方式实现。服务履约、履约回执及归档确认的具体交互机制由所采用接入方案的规范及相应支付方法规范定义。 +> + +## 处理要求 ++ 买方智能体在发起自主化委托支付前，应先完成本地规则自检，不应将明显超出 `BOUNDED` 模式 IAC 授权边界的请求继续发送给 PSP。 ++ 买方智能体构造的支付请求，应确保支付金额、支付币种和商户侧订单号与前序商业确认结果保持一致。 ++ PSP 在执行资金处理前，应完成 IAC 有效性核验和约束核验，不应将未通过核验的请求继续进入扣款阶段。 ++ 当采用专属子账户模式时，PSP 除核验 IAC 外，还应校验子账户状态及其支付授权密文是否有效，并确认其与当前买方智能体身份及子账户绑定关系保持有效。 ++ PSP 对累计额度的判断，应以其自身确认的历史成功交易金额为准，而不应仅依赖买方智能体本地声明。 ++ 自主化委托支付的授权效力应严格受限于 `BOUNDED` 模式 IAC 所定义的边界，不应因为支付请求被程序化执行而突破原始授权范围。 + +## 错误响应 +在 `PSD-PAY-DEL` 定义的错误响应语义基础上，本组件的错误响应主要与 `BOUNDED` 模式 IAC 和自主委托边界相关，可复用 `PSD-PAY-DEL` 中 IAC 已过期、IAC 已吊销、IAC 已暂停、智能体身份不匹配、单笔金额超限、累计金额超限、余额不足、商户不在范围内等错误语义。接入方案相关的错误响应（如支付授权结果凭证验证错误等）由 `PSD-PAY-A402` 或对应接入方案规范定义。 diff --git a/docs/specification/scenarios.en.md b/docs/specification/scenarios.en.md new file mode 100644 index 0000000..501e850 --- /dev/null +++ b/docs/specification/scenarios.en.md @@ -0,0 +1,252 @@ +# ACT 2.1 Typical Scenarios and Business Processes + +[中文](scenarios.md) | English + +# Overview +This section uses typical commercial scenarios supported by the ACT Protocol to explain how delegation authorization, commerce interaction, payment execution, and trust services connect across end-to-end processes, providing scenario-based implementation references for protocol adopters. This document focuses on the applicable conditions, key business steps, and cross-domain interface relationships in each scenario. + +# Scenario Classification Framework +Payment scenarios in agentic commerce are abstracted into three levels based on the principal's presence and the Agent's autonomy in commercial decision-making: + ++ **L1 User Instant Payment**: The principal participates in the purchase decision loop in real time. AI participates in intent understanding and product matching, but the principal must complete identity verification and confirmation for every payment before funds are debited, and the principal retains payment decision authority. This level does not require an Intent Authorization Credential (IAC) to be issued in advance; the principal's real-time confirmation for the current transaction serves as the basis for payment authorization. ++ **L2 User-Specified Delegated Payment**: The principal is not present in real time, and the purchase target has already been specified during the initial interaction. The principal issues an Intent Authorization Credential in advance, authorizing the Agent to execute programmatically toward the specified purchase target within defined boundaries. In general, the principal does not need to intervene again for each transaction during execution. ++ **L3 Autonomous Delegated Payment**: The principal is not present in real time, and the specific purchase target is determined autonomously by the Agent during execution within the authorization boundaries. The principal issues an Intent Authorization Credential in advance and sets only the task objective and boundary conditions, such as the total budget cap, category scope, and task validity period. Within those boundaries, the Agent autonomously completes task decomposition, service discovery, multi-round negotiation, commercial decision-making, and multiple autonomous payments. + +The core basis of the three-level classification is the combination of two dimensions: "principal presence" and "Agent autonomy in commercial decision-making." The former distinguishes between the principal being present in real time (Human-Present) and the principal not being present (Human-Not-Present); the latter distinguishes between directed execution toward a specified objective and autonomous decision-making by the Agent within authorization boundaries. L1 corresponds to "real-time presence + principal decision-making," L2 to "absence + directed execution," and L3 to "absence + autonomous decision-making." Based on these two dimensions, ACT defines four typical scenarios, as shown in the following table. + +| **Scenario** | **Level** | **Principal Presence** | **Dependency on Intent Authorization Credential (IAC)** | **Agent Autonomy in Commercial Decision-Making** | +| --- | --- | --- | --- | --- | +| Scenario 1: User Instant Payment | L1 | Present in real time | No IAC needs to be issued in advance | The principal confirms and makes key decisions in real time | +| Scenario 2: Specified Delegated Payment (Platform Agent) | L2 | Not present | Depends on an IAC, with delegation mode set to SPECIFIED | The Agent performs programmatic, directed execution toward the objective already specified by the principal | +| Scenario 3: Specified Delegated Payment (Dedicated Agent) | L2 | Not present | Depends on an IAC, with delegation mode set to SPECIFIED | The Agent performs programmatic, directed execution toward the objective already specified by the principal | +| Scenario 4: Autonomous Delegated Payment | L3 | Not present | Depends on an IAC, with delegation mode set to BOUNDED | The Agent autonomously conducts multiple rounds of commercial decision-making and payment within the authorization boundaries | + +The following sections describe the key processes and differentiated requirements for each scenario. + +# ACT Protocol Component List +| **Protocol Domain** | **Protocol ID** | **Protocol Name** | **Protocol Description** | +| --- | --- | --- | --- | +| Authorization & Delegation Domain
(ADD) | ADD-INT-ICS | Intent Capture and Structured Expression | Captures, normalizes, and structures the user's delegation intent | +| | ADD-IAC-ISS | Intent Authorization Credential Issuance | Generates and issues an IAC authorization credential based on the structured user intent | +| | ADD-IAC-LCM | Intent Authorization Credential Life Cycle Management | Manages the activation, suspension, resumption, revocation, and expiration states of an IAC | +| Commerce Interaction Domain
(CID) | CID-MER-CAT | Catalog Interface | Provides standardized access to product, service, and merchant catalogs | +| | CID-INT-XFR | Intent Context Transfer | Transfers intent context to appropriate merchants and obtains matching product and service recommendations | +| | CID-PCA-NEG | Payment Capability Negotiation | Negotiates available payment methods, PSPs, payment endpoints, and other payment capability information | +| | CID-CART-CFM | Cart Confirmation | Performs final confirmation of an order, cart, or transaction details before payment | +| Payment Services Domain
(PSD) | PSD-PMT-BND | Payment Method Binding | Binds available payment methods as the basis for subsequent payment processes | +| | PSD-AGT-SUB | Agent-Dedicated Sub-Account Management | Manages dedicated sub-accounts for Agent operations and the related payment control capabilities | +| | PSD-PAY-A402 | HTTP 402-Based Payment Process | Specifies a general HTTP 402-based payment access and interaction mechanism among the buyer Agent, seller service provider, and payment service provider, which can serve as a unified access point for payment scenario components | +| | PSD-PAY-INS | User Instant Payment | Completes payment processing in real time and produces a payment completion result. | +| | PSD-PAY-DEL | User-Specified Delegated Payment | Based on an Intent Authorization Credential in SPECIFIED mode, enables an Agent to initiate a specified delegated payment while the principal is not present and accept verification by the payment service provider | +| | PSD-PAY-AUP | Autonomous Delegated Payment | Based on an Intent Authorization Credential in BOUNDED mode, enables an Agent to autonomously conduct multiple rounds of commercial decision-making and payment within the authorization boundaries | +| Trust Services Domain
(TSD) | TSD-ATT-EVT | Attestation Event | Defines the recording unit for attestation events covering key cross-domain actions and state changes | +| | TSD-ATT-OFF | Offline Attestation Record | Creates standardized attestation records that can be stored, transmitted, and verified offline | +| | TSD-ATT-OCA | On-Chain Attestation Anchor | Anchors attestation digests to the ACT Trust Chain to enhance verifiability and tamper resistance | +| | TSD-ATT-SVF | Signature Verification Flow | Defines the consistency verification process for attestation records, digests, on-chain anchors, and signatures | +| | TSD-ATT-DSP | Dispute Resolution | Supports dispute handling and adjudication | +| | TSD-CRD-ASC | Credit Association Establishment | Specifies the mechanism for establishing credit associations between an associated entity and an Agent, and for issuing credentials | +| | TSD-CRD-MAP | Associated Credit Mapping | Specifies mapping rules and version management from the associated entity's credit claims to the Agent's associated credit claims | +| | TSD-CRD-LCM | Credit Association Lifecycle Management | Specifies the state machine for credit association credentials and mechanisms for suspension, revocation, expiration, reassessment, and other lifecycle operations | +| | TSD-CRD-VER | Associated Credit Verification | Specifies standardized verification of credit associations and associated credit information by third parties | +| | TSD-CRD-AUTH | Credit Query Authorization | Specifies the associated entity's authorization mechanism for associated credit verification queries | + +# Scenario 1: User Instant Payment +## Scenario Description +This scenario applies when the principal is present in real time and the purchase target has been specified during the current interaction. The principal confirms the product and authorizes payment in real time during the current interaction, without requiring an IAC to be issued in advance. + +**Typical example:** The principal tells the Agent, "Order these headphones for me." After the Agent discovers the product, the principal confirms it on the spot and completes the payment. + +## Main Business Process + +![](../assets/specification/act-2.1-scenario-1-immediate-payment.png) + +**Step 1: The principal expresses a purchase intent.** +The principal submits a purchase request to the Agent in natural language. + +**Step 2: Intent structuring and intent confirmation.** +With reference to ADD-INT-ICS, the Agent may convert the natural-language intent into standardized, structured constraint information and present it to the principal in a readable form for confirmation. Constraints that may be specified include the purchase category, amount cap, validity period, payment method constraints, fulfillment timing requirements, and other key conditions. + +**Step 3: Product discovery or merchant routing.** +When obtaining product details or screening candidate products, the Agent may obtain a merchant's structured product catalog with reference to CID-MER-CAT, or transfer intent context to a merchant or platform with reference to CID-INT-XFR to obtain more precise candidate results. + +**Step 4: The principal confirms the product and willingness to pay in real time.** +The Agent presents candidate products to the principal, who selects the transaction target on the spot and confirms the willingness to pay. This step is an application-layer internal interaction, and its result serves as a direct prerequisite for initiating the subsequent payment. + +**Step 5: Payment capability negotiation (optional).** +The Agent may read the payment capability information declared by the merchant with reference to CID-PCA-NEG to confirm the payment method and payment service provider to be used for this payment. + +**Step 6: Payment initiation and PSP verification.** +The Agent should construct a payment request based on PSD-PAY-INS and initiate an instant payment with the PSP. The PSP verifies the payment request, including at least replay protection checks and validation of the Agent's signature, and may initiate a principal identity verification challenge as needed. If verification fails, the PSP should reject the payment and return the corresponding error result. After all checks pass, the PSP returns the payment authorization result. + +**Step 7: Merchant fulfillment.** +After confirming payment authorization, the merchant fulfills the order. This is an internal merchant business process and falls outside the scope of this protocol specification. + +**[Attestation] Attestation of the payment completion event (optional).** +Implementers may asynchronously attest the `act:payment:transaction-completed` event. Such attestation may provide factual evidence of payment completion for subsequent dispute resolution and create a traceable historical record of the Agent's behavior. + +# Scenario 2: Specified Delegated Payment (Platform Agent) +## Scenario Description +This scenario applies to specified delegation where the principal is not present and the purchase target has already been specified during the initial interaction. The principal must issue a SPECIFIED IAC in advance, authorizing the platform Agent to complete subsequent commercial discovery, transaction confirmation, and programmatic payment within defined boundaries. In general, the principal does not need to intervene again in real time during execution. + +A platform Agent typically uses a multi-tenant shared architecture, meaning that multiple principals share the same platform Agent identity. Therefore, payment verification in this scenario should also consider the binding between the platform Agent identity and the specific principal identity, reducing the risks of cross-principal overreach and identity confusion. + +**Typical example:** The principal tells the platform Agent, "Book me a flight to Beijing tomorrow morning for no more than CNY 1,200." After identity verification and credential issuance, the Agent completes the search, comparison, ordering, and payment within the authorization boundaries. + +## Main Business Process + +![](../assets/specification/act-2.1-scenario-2-platform-delegated-payment.png) + +### Phase 1: Intent Structuring and Credential Issuance +**Step 1: The principal expresses an intent.** +The principal expresses the purchase request in natural language. + +**Step 2: Intent structuring and intent confirmation.** +With reference to ADD-INT-ICS, the Agent may convert the natural-language intent into standardized, structured constraint information and present it to the principal in a readable form for confirmation. + +**Step 3: Issue the IAC.** +After the principal confirms the intent rules, the Agent should complete principal identity verification and execute the signature in a secure environment with reference to ADD-IAC-ISS, with the delegation mode set to `SPECIFIED`. The credential and its unique identifier generated in this step will be continuously referenced in subsequent commerce interactions, payment execution, and attestation to maintain information consistency across the full process. + +**[Attestation] Attestation of the credential issuance event (optional).** +After the IAC is issued, implementers may asynchronously submit the `act:delegation:delegation-issued` attestation event. + +### Phase 2: Commerce Interaction +**Step 1: Product discovery or merchant routing.** +The Agent may obtain a merchant's structured product catalog with reference to CID-MER-CAT, or transfer intent context to a merchant or platform with reference to CID-INT-XFR. + +**Step 2: Product comparison and decision-making.** +The Agent compares candidate results based on the structured intent constraints and makes a purchase decision. This reasoning process is an internal application-layer implementation, but the Agent may generate a structured decision summary locally to explain the basis for its selection afterward. + +**[Attestation] Attestation of the Agent decision event (optional).** +Implementers may asynchronously submit the `act:commerce:decision-logged` attestation event to provide evidence of the Agent's decision for subsequent dispute resolution. + +**Step 3: Cart confirmation and rule self-check.** +Before submitting the cart, the Agent should perform a rule self-check based on CID-CART-CFM to confirm that the transaction complies with all authorization boundaries and constraints defined in the IAC. After all checks pass, the Agent submits the cart and obtains an order transaction number. If any constraint is not satisfied, the Agent follows the boundary-handling strategy predefined in the IAC, such as notifying the principal for renewed confirmation or automatically canceling the transaction. + +**[Attestation] Attestation of the cart confirmation event (optional).** +After cart confirmation is completed, implementers may asynchronously submit the `act:commerce:cart-confirmed` attestation event to provide transaction confirmation evidence for subsequent dispute resolution. + +### Phase 3: Payment Execution +**Step 1: Payment capability confirmation (optional).** +With reference to CID-PCA-NEG, the Agent may confirm the payment method and payment service provider to be used for the payment. + +**Step 2: Payment initiation and PSP verification.** +The Agent should construct a delegated payment request based on PSD-PAY-DEL. The request should carry the IAC and order transaction number, be signed by the Agent, and then be submitted to the PSP. The PSP should perform replay protection checks, Agent signature verification, IAC validity verification, consistency verification between the principal identity and payment credentials, and consistency verification between the order transaction parameters and the authorization boundaries. If verification fails, the PSP should reject the payment request and return the corresponding error result. After all checks pass, the PSP returns the payment result. + +The process and diagram above use a traditional merchant-platform ordering and payment process for illustration. The buyer Agent may also initiate payment using the PSD-PAY-A402 payment process. + +**[Attestation] Attestation of the payment completion event (optional).** +After payment is completed, implementers may asynchronously submit the `act:payment:transaction-completed` attestation event to provide factual payment evidence for subsequent dispute resolution. + +**Step 3: Merchant fulfillment.** +After confirming payment authorization, the merchant completes fulfillment. This is an internal merchant business process and falls outside the scope of this protocol specification. + +**[Attestation] Attestation of the fulfillment completion event (optional).** +After merchant fulfillment, implementers may asynchronously submit the `act:commerce:fulfillment-completed` attestation event to provide fulfillment status evidence for subsequent dispute resolution. + +# Scenario 3: Specified Delegated Payment (Dedicated Agent) +## Scenario Description +This scenario also applies to specified delegation where the principal is not present and the purchase target has already been specified during the initial interaction, but the executing entity is a dedicated Agent strongly bound to the principal's device, account, or runtime environment. + +Unlike the multi-tenant platform Agent in Scenario 2, a dedicated Agent has an independent and unique dedicated identity, and payment verification can be anchored directly to that dedicated Agent identity. When supported by the payment service provider, this scenario may also establish an independent sub-account for the dedicated Agent, isolating the risk of the Agent's payment behavior from the principal's primary account. + +**Typical example:** Through their dedicated Agent, the principal says, "Buy me the book *Artificial Intelligence: A Modern Approach* for no more than CNY 150." After identity verification and credential issuance, the dedicated Agent completes the search, comparison, ordering, and payment. + +## Main Business Process + +![](../assets/specification/act-2.1-scenario-3-dedicated-agent-payment.png) + +This scenario is generally consistent with Scenario 2 in the fundamental processes of intent structuring and credential issuance, commerce interaction, cart confirmation, delegated payment execution, and asynchronous attestation. These processes are not repeated in this section. Only the substantive differences from Scenario 2 are highlighted below. + +**Difference 1: Dedicated Agent identity initialization** + +When a dedicated Agent first establishes a secure binding with the principal's device or runtime environment, it should complete registration and verification with the relevant identity service and obtain a unique identity identifier that can be recognized and verified within the ACT ecosystem. This initialization is generally performed only once upon initial binding. When the same dedicated Agent subsequently initiates another commercial delegation, it may directly reuse the existing identity. + +**Difference 2: Delegate identifier in the IAC and signature verification method** + +In this scenario, the delegate identifier in the IAC should contain the dedicated Agent's unique Agent identifier. When verifying the payment request, the PSP should verify the signature of the Agent initiating the payment request using the public key material corresponding to that Agent ID. + +**Difference 3: Dedicated sub-account support** + +If the principal has enabled an independent sub-account for the dedicated Agent, the Agent and the payment service provider may establish the dedicated sub-account, bind its identifier, and manage its lifecycle with reference to PSD-AGT-SUB. For a specific payment, the payment request should carry the corresponding sub-account identifier. During verification, the PSP should also verify the sub-account balance or limit status and debit funds or reserve the limit according to the applicable rules. If no independent sub-account is enabled, the transaction may instead be processed using payment credential separation and risk-control mechanisms. + +# Scenario 4: Autonomous Delegated Payment +## Scenario Description +This scenario applies when the principal is not present and the specific purchase target is determined autonomously by the Agent during execution within the authorization boundaries. Unlike the specified delegation in Scenarios 2 and 3, the principal does not need to specify a particular transaction target during the initial stage and only needs to set the task objective and boundary conditions, such as the total budget cap, service category scope, and task validity period. Within these authorization boundaries, the Agent may autonomously complete task decomposition, service discovery, multi-round negotiation, and multiple autonomous payments, without the principal intervening in each transaction throughout the process. + +To control the risk of high-frequency machine-to-machine transactions, this scenario generally requires the buyer Agent to use a dedicated independent sub-account, isolating risk from the principal's primary account. + +**Typical example:** The principal asks a dedicated Agent to prepare a research report. The Agent autonomously purchases capabilities or data in sequence from a data service Agent, a literature retrieval Agent, and others, then delivers the result to the principal after all subtasks have been completed. + +## Main Business Process + +![](../assets/specification/act-2.1-scenario-4-autonomous-payment.png) + +### Phase 1: Task Delegation and Credential Issuance +**Step 1: The principal expresses an autonomous delegation task.** +The principal expresses the task objective and boundary constraints to the buyer Agent, such as the permitted service category scope, total budget cap, and task deadline. + +**Step 2: Structured intent and rule confirmation.** +With reference to ADD-INT-ICS, the buyer Agent may express the task objective and constraints in a structured form and present the key constraints to the principal for confirmation. + +**Step 3: Issue an autonomous delegation IAC.** +After the principal confirms, the buyer Agent should complete identity verification and signing with reference to ADD-IAC-ISS, with the delegation mode set to `BOUNDED`. After credential issuance, the principal generally does not need to reconfirm each of the subsequent autonomous payments initiated by the buyer Agent within the boundaries. + +**Step 4: Prepare the dedicated sub-account (optional).** +The buyer Agent checks the balance or available limit of the dedicated independent sub-account. If it is insufficient, the Agent may remind the principal to add funds or adjust the budget cap. + +**[Attestation] Attestation of the credential issuance event (optional).** +After the IAC is issued, implementers may asynchronously submit the `act:delegation:delegation-issued` attestation event. + +### Phase 2: Task Decomposition and Service Discovery +**Step 1: Task decomposition.** +The buyer Agent decomposes the overall task into several subtasks and plans the execution path. This process is internal Agent reasoning and falls outside the scope of this protocol specification. + +**Step 2: Service discovery.** +Through a service marketplace or another discovery mechanism, the buyer Agent may screen service provider Agents that satisfy the intent constraints and form a candidate list. When screening service provider Agents, the buyer Agent may reference the Agent's associated credit claims from the Trust Services Domain, as described in the Credit Association sub-specification, as auxiliary inputs for evaluating the trustworthiness of service providers. + +**Step 3: Payment capability negotiation (optional).** +With reference to CID-PCA-NEG, the buyer Agent may negotiate payment capabilities with the selected service provider Agent and confirm a matching payment method and payment service provider. + +### Phase 3: Multi-Round Agent-to-Agent Autonomous Payments +The following process describes a single autonomous payment. It may be repeated multiple times during a complete task execution cycle. + +**Step 1: Real-time rule self-check.** +Before initiating each autonomous payment, the buyer Agent should verify whether the current time is within the credential validity period, whether the sum of the cumulative payment amount and the current amount exceeds the total cap, whether the service provider and service category satisfy the constraints, and whether the payment method falls within the authorization scope. If any condition is not met, the Agent should terminate the current payment and handle it according to the predefined strategy. When the remaining limit or validity period approaches a predefined threshold, the Agent may proactively send an alert to the principal. + +**Step 2: Payment trigger and message construction.** +After receiving a service request from the buyer Agent, the service provider Agent may request payment by returning `HTTP 402 Payment Required` with reference to PSD-PAY-A402, and state the payment amount, payment method, payee identifier, and other necessary payment parameters for the service in the response. After receiving the payment request, the buyer Agent constructs an autonomous delegated payment request message based on PSD-PAY-AUP, carries the BOUNDED IAC and the current payment parameters, and signs the message. The buyer Agent should submit the payment request message directly to the agreed PSP to request payment authorization for the service. + +The process and diagram above use the PSD-PAY-A402 payment process for illustration. The buyer Agent may also initiate payment through a traditional merchant-platform ordering and payment process. + +**Step 3: PSP verification and payment authorization.** +After receiving the payment request, the PSP performs scenario-specific verification for autonomous delegated payment based on PSD-PAY-AUP, including replay protection checks, buyer Agent signature verification, BOUNDED IAC validity verification, verification of the current amount and cumulative limit boundaries, and verification of the dedicated sub-account balance or available limit. + +The verification requirements above are independent of the payment access method. Whether PSD-PAY-A402 or a traditional merchant-platform ordering and payment process is used, the PSP should perform these scenario-specific checks. If verification fails, the PSP should reject the payment and return a failure result or the corresponding error information to the buyer Agent. If all checks pass, the PSP should return a successful payment result, or a payment authorization result and credential that can be referenced and verified during subsequent service delivery. The buyer Agent may proceed to the subsequent service request stage only after receiving a successful payment result. + +**Step 4: Service delivery and continuation of subtasks.** +After receiving another service request from the buyer Agent, the service provider Agent should verify the payment result, payment credential, or payment-related identifier carried in the request, and verify the payment status with the payment service provider using the verification method agreed with the payment service provider, to confirm that the payment corresponding to the request has been completed or that the related payment authorization is valid. The service provider Agent may deliver the corresponding data or service result only after confirming that payment has been completed, or that the related payment authorization is valid and acceptable. + +The buyer Agent continues with the next subtask until all subtasks are completed. + +**[Attestation] Attestation of a single payment completion event (optional).** +After each autonomous payment is completed, implementers may asynchronously submit the `act:payment:transaction-completed` attestation event. Multiple payment records under the same delegated task may be further aggregated into a complete task bill to support auditing and dispute resolution after task completion. + +### Phase 4: Task Completion and Bill Review +**Step 1: Task completion and result delivery.** +After all subtasks are completed, the buyer Agent aggregates the results and delivers the task output to the principal. + +**Step 2: Credential revocation (optional).** +If the credential has not expired when the task is completed, the buyer Agent may proactively trigger credential revocation with reference to ADD-IAC-LCM to terminate possible subsequent payment activity. + +**Step 3: Bill review.** +The principal may review all payment records initiated by the buyer Agent during task execution and the related result summaries. + +**[Attestation] Attestation of the credential revocation or expiration event (optional).** +If the credential is proactively revoked, implementers may asynchronously submit the `act:delegation:delegation-revoked` attestation event. If the credential becomes invalid upon expiration, they may asynchronously submit the `act:delegation:delegation-expired` attestation event. + +# General Notes on Asynchronous Attestation Processing +All steps marked [Attestation] in the scenarios in this document are asynchronous, non-blocking operations. Their execution timing should not block or affect the normal progression of the main commerce interaction and payment processes. + +Whether related attestation events are submitted, and which participant is responsible for submitting them, may be determined based on the business risk level, dispute resolution requirements, and implementation architecture. However, for attestation events that have been submitted, their event types, payload structures, signature verification methods, and subsequent verification rules should comply with the unified requirements of the Trust Services Domain. + +In the current protocol version, typical attestable events include credential issuance, Agent decision logging, cart confirmation, payment completion, fulfillment completion, and credential revocation or expiration. Together, these events form an important factual basis for subsequent dispute resolution, auditing, and retrospective tracing. diff --git a/docs/specification/scenarios.md b/docs/specification/scenarios.md new file mode 100644 index 0000000..254895a --- /dev/null +++ b/docs/specification/scenarios.md @@ -0,0 +1,252 @@ +# ACT 2.1 典型场景与业务流程 + +中文 | [English](scenarios.en.md) + +# 概述 +本部分通过 ACT 协议支持的典型商业场景，说明委托授权、商业交互、支付执行与信任服务在端到端链路中的衔接关系，为协议采纳方提供场景化实施参照。本文档重点描述各场景下的适用条件、关键业务步骤与跨域接口关系。 + +# 场景分类框架 +将智能体商业中的支付场景按委托人在场性与智能体商业决策自主度，抽象为三个级别： + ++ **L1 用户即时支付**：委托人实时在场参与购买决策闭环，AI 参与意图理解与商品匹配，但资金扣划前必须完成委托人笔笔核身确认，支付决策权在委托人。该级别无需预先签发意图授权凭证（IAC），由委托人当次实时确认作为支付授权基础。 ++ **L2 用户定向委托支付**：委托人不实时在场，购买标的在初始交互中已明确。委托人预先签发意图授权凭证，授权智能体在既定边界内按照明确的购买标的定向执行，执行过程中一般无需委托人逐笔再次介入。 ++ **L3 自主化委托支付**：委托人不实时在场，且具体购买标的由智能体在执行过程中于授权边界内自主决定。委托人预先签发意图授权凭证，仅设定任务目标及边界条件（如总预算上限、品类范围、任务有效期限等），智能体在边界内自主完成任务拆解、服务发现、多轮协商、商业决策及多次自主化支付。 + +上述三级分类的核心依据是"委托人在场性"与"智能体商业决策自主度"两个维度的组合：前者区分为委托人实时在场（Human-Present）与委托人不在场（Human-Not-Present）两类；后者区分为按既定目标的定向执行，以及在授权边界内由智能体自主决策两类。L1 对应"实时在场+委托人决策"，L2 对应"不在场+定向执行"，L3 对应"不在场+自主决策"。按照上述两个维度，ACT 整理了四类典型场景，如下表所示。 + +| **场景** | **L级别** | **委托人在场性** | **对意图授权凭证（IAC）的依赖** | **智能体商业决策自主度** | +| --- | --- | --- | --- | --- | +| 场景一：用户即时支付 | L1 | 实时在场 | 无需预先签发 IAC | 委托人实时确认并作出关键决策 | +| 场景二：定向委托支付（平台型智能体） | L2 | 不在场 | 依赖 IAC，委托模式为 SPECIFIED | 智能体按委托人已明确的目标程序化定向执行 | +| 场景三：定向委托支付（专属型智能体） | L2 | 不在场 | 依赖 IAC，委托模式为 SPECIFIED | 智能体按委托人已明确的目标程序化定向执行 | +| 场景四：智能体自主委托支付 | L3 | 不在场 | 依赖 IAC，委托模式为 BOUNDED | 智能体在授权边界内自主开展多轮商业决策与支付 | + +后续各节按场景分别说明其关键流程及差异化要求。 + +# ACT协议组件列表 +| **所属协议域** | **协议编号** | **协议名称** | **协议描述** | +| --- | --- | --- | --- | +| 委托授权域
（Authorization & Delegation Domain, ADD） | ADD-INT-ICS | 意图获取与结构化表达
（Intent Capture and Structured Expression） | 面向用户委托意图的采集、规范化与结构化表达 | +| | ADD-IAC-ISS | 意图授权凭证签发（Intent Authorization Credential Issuance） | 基于结构化的用户意图生成并签发 IAC 授权凭证 | +| | ADD-IAC-LCM | 意图授权凭证生命周期管理 （Intent Authorization Credential Life Cycle Management） | 管理 IAC 的激活、暂停、恢复、撤销与过期状态 | +| 商业交互域
（Commerce Interaction Domain, CID） | CID-MER-CAT | 商家目录接口
（Catalog Interface） | 提供商品、服务与商家目录的标准化访问入口 | +| | CID-INT-XFR | 意图上下文传递
（Intent Context Transfer） | 将意图上下文传递给合适的商家，并获得相匹配的产品和服务推荐 | +| | CID-PCA-NEG | 支付能力协商
（Payment Capability Negotiation） | 用于协商可用支付方式、PSP 与支付端点等支付能力信息 | +| | CID-CART-CFM | 购物车确认
（Cart Confirmation） | 在支付前对订单、购物车或交易内容进行最终确认 | +| 支付服务域
（Payment Services Domain, PSD） | PSD-PMT-BND | 支付方式绑定
（Payment Method Binding） | 绑定可用支付方式，为后续支付流程提供基础 | +| | PSD-AGT-SUB | 智能体专属子账户管理（Agent-Dedicated Sub-Account Management） | 管理面向智能体运行的专属子账户及相关支付控制能力 | +| | PSD-PAY-A402 | 基于 HTTP 402 的支付流程 | 规范买方智能体、卖方服务方与支付服务方之间基于 HTTP 402 的通用支付接入交互机制，可作为支付场景组件的统一接入入口 | +| | PSD-PAY-INS | 用户即时支付
（Instant Payment） | 用于实时完成支付处理并产生支付完成结果。 | +| | PSD-PAY-DEL | 用户定向委托支付
（Delegated Payment） | 基于意图授权凭证（SPECIFIED模式），由智能体在委托人不在场场景下发起定向委托支付并接受支付服务方核验 | +| | PSD-PAY-AUP | 自主化委托支付（Autonomous Delegated Payment） | 基于意图授权凭证（BOUNDED模式），由智能体在授权边界内自主开展多轮商业决策与支付 | +| 信任服务域
（Trust Services Domain, TSD） | TSD-ATT-EVT | 存证事件
（Attestation Event） | 定义跨域关键行为和状态变化的存证事件记录单元 | +| | TSD-ATT-OFF | 离线存证记录
（Offline Attestation Record） | 形成可离线保存、传输和校验的标准化存证记录 | +| | TSD-ATT-OCA | 链上存证锚定
（On-Chain Attestation Anchor） | 将存证摘要锚定到 ACT Trust Chain 以增强可验证性与防篡改性 | +| | TSD-ATT-SVF | 签名核验流程
（Signature Verification Flow） | 定义对存证记录、摘要、链上锚定和签名的一致性校验流程 | +| | TSD-ATT-DSP | 争议处理
（Dispute Resolution） | 争议处理与裁决支撑 | +| | TSD-CRD-ASC | 信用关联建立（Credit Association Establishment） | 规范关联主体与智能体之间信用关联关系的建立机制与凭证签发 | +| | TSD-CRD-MAP | 关联信用映射（Associated Credit Mapping） | 规范关联主体信用声明到智能体关联信用声明的映射规则与版本管理 | +| | TSD-CRD-LCM | 信用关联生命周期管理（Credit Association Lifecycle Management） | 规范信用关联凭证的状态机及暂停、撤销、过期、重新评估等管理机制 | +| | TSD-CRD-VER | 关联信用验证（Associated Credit Verification） | 规范第三方对信用关联关系及关联信用信息的标准化验证 | +| | TSD-CRD-AUTH | 信用查询授权（Credit Query Authorization） | 规范关联主体对关联信用验证的查询授权机制 | + +# 场景一：用户即时支付 +## 场景描述 +本场景适用于委托人实时在场，且购买标的已在当次交互中明确的即时购买情形。委托人在当次交互中实时完成商品确认与支付授权，无需预先签发 IAC。 + +**典型示例：** 委托人对智能体说"帮我下单这款耳机"，智能体完成商品发现后，由委托人当场确认并完成支付。 + +## 主要业务流程 + +![](../assets/specification/act-2.1-scenario-1-immediate-payment.png) + +**步骤 1：委托人表达购买意图。** +委托人以自然语言向智能体提出购买需求。 + +**步骤 2：意图结构化与意图确认。** +智能体可参照 ADD-INT-ICS，将自然语言意图转换为标准化的结构化约束信息，并以可读形式呈现给委托人确认。可明确的约束内容包括购买类别、金额上限、有效期、支付方式约束、履约时效要求等关键条件。 + +**步骤 3：商品发现或商户路由。** +智能体获取商品详情或筛选候选商品时，可参照 CID-MER-CAT 获取商户结构化商品目录，也可参照 CID-INT-XFR 向商户或平台传递意图上下文以获取更精准的候选结果。 + +**步骤 4：委托人实时确认商品与支付意愿。** +智能体向委托人呈现候选商品，由委托人当场选定交易对象并确认支付意愿。该步骤属于应用层内部交互，其结果将作为后续支付发起的直接前提。 + +**步骤 5：支付能力协商（可选）。** +智能体可参照 CID-PCA-NEG 读取商户声明的支付能力信息，以确认本次支付所采用的支付方式与支付服务方。 + +**步骤 6：支付发起与 PSP 核验。** +智能体应依据 PSD-PAY-INS 构造支付请求并向 PSP 发起即时支付。PSP 对支付请求进行核验，应至少包括防重放校验、智能体签名有效性验证等内容，并可根据需要发起委托人核身挑战。如核验未通过，PSP 应拒绝本次支付并返回相应错误结果；全部核验通过后，PSP 返回支付授权结果。 + +**步骤 7：商户履约。** +商户在确认支付授权后完成订单履约。该过程属于商户内部业务流程，不属于本协议规范范围。 + +**【存证】支付完成事件存证（可选）。** +实现方可对 `act:payment:transaction-completed` 事件进行异步存证。此类存证可为事后争议处理提供支付完成事实依据，也可为智能体积累可追溯的历史行为记录。 + +# 场景二：定向委托支付（平台型智能体） +## 场景描述 +本场景适用于委托人不在场，且购买标的在初始交互中已被明确的定向委托情形。委托人需预先签发 SPECIFIED 类型的 IAC，授权平台型智能体在既定边界内完成后续商业发现、交易确认与程序化支付，执行过程中一般无需委托人再次实时介入。 + +平台型智能体通常采用多租户共享架构，即多个委托人共享同一平台智能体身份。因此，本场景的支付核验应同时考虑平台智能体身份与具体委托人身份之间的绑定关系，以降低跨委托人越权与身份混淆的风险。 + +**典型示例：** 委托人对平台型智能体说"帮我订明天上午飞北京的机票，不超过 1200 元"，完成核身与凭证签发后，由智能体在授权边界内完成查询、比价、下单与支付。 + +## 主要业务流程 + +![](../assets/specification/act-2.1-scenario-2-platform-delegated-payment.png) + +### 阶段一：意图结构化与凭证签发 +**步骤 1：委托人表达意图。** +委托人以自然语言表达购买需求。 + +**步骤 2：意图结构化与意图确认。** +智能体可参照 ADD-INT-ICS，将自然语言意图转换为标准化的结构化约束信息，并以可读形式呈现给委托人确认。 + +**步骤 3：签发 IAC。** +委托人确认意图规则后，智能体应参照 ADD-IAC-ISS，完成委托人核身并在安全环境中执行签名，委托模式应设定为 `SPECIFIED`。本步骤生成的凭证及其唯一标识，将在后续商业交互、支付执行和存证过程中持续被引用，以保持全链路信息一致性。 + +**【存证】凭证签发事件存证（可选）。** +IAC 签发完成后，实现方可异步提交 `act:delegation:delegation-issued` 存证事件。 + +### 阶段二：商业交互 +**步骤 1：商品发现或商户路由。** +智能体可参照 CID-MER-CAT 获取商户结构化商品目录，也可参照 CID-INT-XFR 向商户或平台传递意图上下文。 + +**步骤 2：商品比较与决策。** +智能体依据结构化意图约束对候选结果进行比较，并形成购买决策。该推理过程属于应用层内部实现，但智能体可在本地生成结构化决策摘要，以便事后说明选择依据。 + +**【存证】智能体决策事件存证（可选）。** +实现方可异步提交 `act:commerce:decision-logged` 存证事件，为后续争议处理提供智能体决策依据。 + +**步骤 3：购物车确认与规则自检。** +智能体在提交购物车前，应依据 CID-CART-CFM 执行规则自检，确认本次交易符合 IAC 中定义的全部授权边界与约束条件。全部通过后，智能体提交购物车并获得订单交易号；若存在约束不满足情形，则按 IAC 中预设的边界处理策略执行，例如通知委托人重新确认或自动取消。 + +**【存证】购物车确认事件存证（可选）。** +购物车确认完成后，实现方可异步提交 `act:commerce:cart-confirmed` 存证事件，为后续争议处理提供交易确认依据。 + +### 阶段三：支付执行 +**步骤 1：支付能力确认（可选）。** +智能体可参照 CID-PCA-NEG，确认本次支付所采用的支付方式与支付服务方。 + +**步骤 2：支付发起与 PSP 核验。** +智能体应依据 PSD-PAY-DEL 构造委托支付请求，请求中应携带 IAC 与订单交易号，并由智能体完成签名后提交给 PSP。PSP 应执行防重放校验、智能体签名验证、IAC 有效性校验、委托人身份与支付凭据一致性校验，以及订单交易参数与授权边界一致性校验。如核验未通过，PSP 应拒绝本次支付请求并返回对应错误结果；全部核验通过后，PSP 返回支付结果。 + +上述流程及示意图采用传统商户平台下单支付流程进行描述；买方智能体也可采用 PSD-PAY-A402 支付流程发起支付。 + +**【存证】支付完成事件存证（可选）。** +支付完成后，实现方可异步提交 `act:payment:transaction-completed` 存证事件，为后续争议处理提供支付事实依据。 + +**步骤 3：商户履约。** +商户在确认支付授权后完成履约。该过程属于商户内部业务流程，不属于本协议规范范围。 + +**【存证】履约完成事件存证（可选）。** +商户履约后，实现方可异步提交 `act:commerce:fulfillment-completed` 存证事件，为后续争议处理提供履约状态依据。 + +# 场景三：定向委托支付（专属型智能体） +## 场景描述 +本场景同样适用于委托人不在场、购买标的已在初始交互中明确的定向委托情形，但执行主体为与委托人设备、账号或运行环境强绑定的专属型智能体。 + +与场景二的多租户平台型智能体不同，专属型智能体拥有独立且唯一的专属身份，支付核验可直接锚定该专属智能体身份进行验证。在满足支付服务方能力条件时，本场景还可支持为专属型智能体设立独立子账户，以实现智能体支付行为与委托人主账户之间的风险隔离。 + +**典型示例：** 委托人通过自己的专属智能体说"帮我买《人工智能：现代方法》这本书，不超过 150 元"，完成核身与凭证签发后，由专属智能体完成查询、比价、下单与支付。 + +## 主要业务流程 + +![](../assets/specification/act-2.1-scenario-3-dedicated-agent-payment.png) + +本场景在意图结构化与凭证签发、商业交互、购物车确认、委托支付执行及异步存证等基础流程上，与场景二总体一致，本节不再重复展开。以下仅对其与场景二存在实质差异的部分作重点说明。 + +**差异点一：专属智能体身份初始化** + +当专属型智能体首次与委托人设备或运行环境建立安全绑定关系时，应向身份相关服务完成注册与验证，获得在 ACT 生态中可被识别和核验的唯一身份标识。此初始化操作通常仅在首次绑定时执行一次；后续同一专属智能体再次发起商业委托时，可直接复用既有身份。 + +**差异点二：IAC 中受托方标识及签名校验方式** + +在本场景中，IAC 的受托方标识应填写专属智能体的唯一智能体标识。PSP 在核验支付请求时，应基于该 Agent ID 所对应的公钥材料，对发起支付请求的智能体签名进行验证。 + +**差异点三：专属子账户支持** + +若委托人为专属型智能体启用了独立子账户，则智能体与支付服务方可参照 PSD-AGT-SUB 完成专属子账户的建立、标识绑定及生命周期管理；在具体支付时，支付请求中应携带相应子账户标识，PSP 在核验阶段应同时验证子账户余额或额度状态，并按规则完成扣款或额度冻结。若未启用独立子账户，也可基于支付凭据区分与风险控制机制完成交易处理。 + +# 场景四：智能体自主委托支付 +## 场景描述 +本场景适用于委托人不在场，且具体购买标的由智能体在执行过程中于授权边界内自主决定的情形。与场景二、三中的定向委托不同，委托人无需在初始阶段明确指定具体交易对象，只需设定任务目标及边界条件，例如总预算上限、服务品类范围、任务有效期限等。在该授权边界内，智能体可自主完成任务拆解、服务发现、多轮协商及多次自主化支付，全程无需委托人逐笔介入。 + +为控制机器间高频交易风险，本场景通常要求买方智能体使用专属独立子账户，以实现与委托人主账户的风险隔离。 + +**典型示例：** 委托人要求专属智能体撰写一份研报，智能体自主依次向数据服务智能体、文献检索智能体等购买能力或数据，并在全部子任务完成后向委托人交付结果。 + +## 主要业务流程 + +![](../assets/specification/act-2.1-scenario-4-autonomous-payment.png) + +### 阶段一：任务委托与凭证签发 +**步骤 1：委托人表达自主委托任务。** +委托人向买方智能体表达任务目标及边界约束，例如服务类别范围、总预算上限和任务截止时间等。 + +**步骤 2：结构化意图与规则确认。** +买方智能体可参照 ADD-INT-ICS 对任务目标和约束进行结构化表达，并将关键约束内容呈现给委托人确认。 + +**步骤 3：签发自主委托 IAC。** +委托人确认后，买方智能体应参照 ADD-IAC-ISS 完成核身与签名，委托模式应设定为 `BOUNDED`。凭证签发完成后，后续买方智能体在边界内发起的多轮自主化支付一般无需委托人逐笔再次确认。 + +**步骤 4：专属子账户准备（可选）。** +买方智能体检查专属独立子账户的余额或可用额度状态；如不足，可提醒委托人补充资金或调整预算上限。 + +**【存证】凭证签发事件存证（可选）。** +IAC 签发完成后，实现方可异步提交 `act:delegation:delegation-issued` 存证事件。 + +### 阶段二：任务拆解与服务发现 +**步骤 1：任务拆解。** +买方智能体将整体任务拆解为若干子任务，并规划执行路径。该过程属于智能体内部推理，不属于本协议规范范围。 + +**步骤 2：服务发现。** +买方智能体可通过服务市场或其他发现机制，筛选符合意图约束条件的服务方智能体，并形成候选列表。在筛选服务方智能体时，买方智能体可按需引用信任服务域的智能体关联信用声明（参照信用关联子篇）作为服务方信任评估的辅助参考输入。 + +**步骤 3：支付能力协商（可选）。** +买方智能体可参照 CID-PCA-NEG，与选定的服务方智能体完成支付能力协商，确认匹配的支付方式与支付服务方。 + +### 阶段三：多轮智能体对智能体自主化支付 +以下流程描述单次自主化支付过程；在一个完整任务执行周期内，该过程可循环发生多次。 + +**步骤 1：规则实时自检。** +每次发起自主化支付前，买方智能体应验证：当前时间是否在凭证有效期内、累计支付金额与本次金额之和是否超出总额上限、服务提供方及服务类别是否满足约束，以及支付方式是否在授权范围内。任一条件不满足时，智能体应终止本次支付，并按预设策略处理。当剩余额度或有效期接近预设阈值时，智能体可主动向委托人发送预警。 + +**步骤 2：支付触发与报文构造。** +服务方智能体在收到买方智能体的服务请求后，可通过返回 `HTTP 402 Payment Required` 的方式提出支付要求（参照 PSD-PAY-A402），并在响应中说明本次服务对应的支付金额、支付方式、收款方标识及其他必要支付参数。买方智能体在接收到该支付要求后，依据 PSD-PAY-AUP 构造本次自主化委托支付请求报文，携带 BOUNDED 模式 IAC 及本次支付参数，并完成签名。该支付请求报文应由买方智能体直接提交至约定的 PSP，用于申请本次服务对应的支付授权。 + +上述流程及示意图采用 PSD-PAY-A402 支付流程进行描述；买方智能体也可基于传统商户平台下单支付流程发起支付。 + +**步骤 3：PSP 核验与支付授权。** +PSP 在收到支付请求后，依据 PSD-PAY-AUP 执行自主化委托支付的场景核验，包括防重放校验、买方智能体签名验证、BOUNDED 模式 IAC 有效性核验、本次金额与累计额度边界核验，以及专属子账户余额或可用额度核验。 + +上述核验要求与支付接入方式相互独立，无论采用 PSD-PAY-A402 还是传统商户平台下单支付流程，PSP 均应完成上述场景核验。如核验未通过，PSP 应拒绝本次支付，并向买方智能体返回失败结果或对应错误信息。如全部核验通过，PSP 应返回支付成功结果，或返回可供后续服务交付阶段引用和校验的支付授权结果及凭证。买方智能体在获得支付成功结果后，方可进入后续服务请求阶段。 + +**步骤 4：服务交付与子任务继续。** +服务方智能体在收到买方智能体再次发起的服务请求后，应对请求中携带的支付结果、支付凭证或支付相关标识进行校验，并按照与支付服务方约定的校验方式向支付服务方核验本次支付状态，以确认该请求所对应的支付已完成，或者相关支付授权处于有效状态。仅在确认支付已完成，或者确认相关支付授权有效且可接受后，服务方智能体方可交付相应数据或服务结果。 + +买方智能体继续执行下一子任务，直至全部子任务完成。 + +**【存证】单次支付完成事件存证（可选）。** +每次自主化支付完成后，实现方可异步提交 `act:payment:transaction-completed` 存证事件。同一委托任务下的多笔支付记录，可进一步聚合形成完整的任务账单，以支持任务完成后的审计和争议处理。 + +### 阶段四：任务完成与账单回溯 +**步骤 1：任务完成与结果交付。** +所有子任务完成后，买方智能体汇总结果并向委托人交付任务输出。 + +**步骤 2：凭证吊销（可选）。** +若任务完成时凭证尚未过期，买方智能体可参照 ADD-IAC-LCM 主动触发凭证吊销，以终止后续可能的支付行为。 + +**步骤 3：账单回溯。** +委托人可查看本次任务执行过程中买方智能体发起的全部支付记录及相关结果摘要。 + +**【存证】凭证吊销或过期事件存证（可选）。** +若凭证被主动吊销，实现方可异步提交 `act:delegation:delegation-revoked` 存证事件；若凭证因到期而失效，可异步提交 `act:delegation:delegation-expired` 存证事件。 + +# 存证异步处理通用说明 +本文档各场景中标注为【存证】的步骤，均为异步非阻塞操作，其执行时序不应阻塞或影响商业交互与支付主流程的正常推进。 + +是否提交相关存证事件，以及由哪一参与方负责提交，可根据业务风险等级、争议处理要求及实现架构作具体安排。但对于已经提交的存证事件，其事件类型、载荷结构、签名校验方式及后续核验规则，应符合信任服务域的统一规定。 + +在协议当前版本中，典型可存证的事件包括凭证签发、智能体决策记录、购物车确认、支付完成、履约完成以及凭证吊销或过期等。这些事件共同构成后续争议处理、审计和事后追溯的重要事实基础。 diff --git a/docs/specification/trust-services.en.md b/docs/specification/trust-services.en.md index ea611b9..a296624 100644 --- a/docs/specification/trust-services.en.md +++ b/docs/specification/trust-services.en.md @@ -2,227 +2,1014 @@ [中文](trust-services.md) | English -> **Chinese source publication: ACT 2.1 Specification / Final / Normative** -> **The protocol content is final. Conformance with this specification requires independent conformance evidence.** -> **Version baseline: 2026-08-11 (UTC+8).** -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +# First: trusted attestation -The Trust Services Domain (TSD) provides verifiable, traceable, and reviewable trust support for cross-domain ACT facts. It contains two parallel parts: Trusted Attestation and Credit Association. +# Scope +## Subdomain Positioning +trusted attestation (Trusted Attestation) is one of the sub-sections of Trust Services Domain. This sub-section provides for a unified record, reference and certification of key business events in the ACT protocol, which provides a trusted basis for authorization, commerce interaction, payment of performance and performance-related facts, which are traceable, verifiable and subject to review. -This document is the official informative English translation of the normative ACT 2.1 Trust Services Domain text in this release. The [ACT Protocol Trust Services page](https://www.act-protocol.com/documentation/trust) is an unversioned informative reference. +## Subdomain Scope and Boundaries +This sub-section covers the following: -## 1. Relationship and boundaries of the two parts ++ (a) Types of incidents documented and their marking rules; ++ Standard load structure and minimum required elements for the certificated event; ++ Rules for the submission, signature, anchor reference and status indication of the event attestation; ++ (b) Basic verification rules for reference, validation and dispute resolution of the certificate results; ++ Cross-domain incident reference relationships and their consistency requirements; ++ The sub-section provides for ACT Trust Chain as a chain anchoring infrastructure to carry summary anchors for key business events and to support unmistakable verifications in the cross-agency context. -| Part | Problem addressed | Components | -|---|---|---| -| Trusted Attestation | How critical business events form off-chain evidence, on-chain anchors, verification results, and dispute-handling chains | `TSD-ATT-EVT`, `TSD-ATT-OFF`, `TSD-ATT-OCA`, `TSD-ATT-SVF`, `TSD-ATT-DSP` | -| Credit Association | When an Agent lacks sufficient independent credit, how it can reference the credit of an associated subject within a restricted scope while keeping source, authorization, and state verifiable | `TSD-CRD-ASC`, `TSD-CRD-MAP`, `TSD-CRD-LCM`, `TSD-CRD-VER`, `TSD-CRD-AUTH` | +The following are not regulated in this sub-section: -Trusted Attestation is only one part of TSD and is not equivalent to the whole domain. Credit Association specifies associated subjects, credentials, declarations and mapped values, query-authorization modes, the `ASSOCIATED_CREDIT` source marker, confirmation methods, and responsibility boundaries. ++ Internal realization of specific bottom books, block chains, time stamp services, databases or third-party documentation infrastructure; ++ The internal audit platforms Participants, the legal processing system and the operational operating system were implemented. -Trusted Attestation does not specify the internal implementation of an underlying blockchain, timestamp service, database, or third-party evidence facility. Credit Association does not specify credit-scoring models, credit-granting rules, payment-risk decisions, cross-institution conversion rules, or independent Agent credit or reputation mechanisms. Product logs, payment receipts, or credit results do not automatically become TSD-conforming protocol objects merely because they exist. +## 1.3 trusted attestation Value statement +The sub-chapter uses a two-tiered certificate structure, “Current full record-up + summary anchoring on the chain”: under the chain, complete business events are maintained with explicit and signed material and only protected summary anchors are included in the chain to satisfy operational verifiability, privacy protection and cross-agency Trust Requirements. -# Part I: Trusted Attestation +The central objective of this design is not to centralize the original business data for third-party preservation, but to establish a minimum level of trust that is necessary and mutually verifiable, provided that each party has the maximum degree of autonomy to keep the original data. When a dispute, audit or compliance verification occurs, the relevant Participants presents the original records retained by the party on demand and compares them with the pre-enclosed summary of the chain, thereby proving that the record has not been tampered with subsequently. -## 2. Architecture and cross-domain relationship +Since the chain only preserves a light quantitative summary without a full-volume business statement, the book enables the retention of the critical certification capacity required for cross-agency validation while controlling storage costs and reducing the risk of spills of sensitive information. At the same time, the chain anchor is maintained by a multi-party consensus and does not rely on any single platform or a single Participants log endorsement, making it more neutral and credible than a single-point log system. Based on this mechanism, trusted attestation serves not only historical memory, but also serves as a common basis for subsequent signature verification, causal chain traceability and dispute resolution. -Trusted Attestation uses a two-layer architecture of **complete off-chain record plus on-chain digest anchoring**. Participants retain event plaintext and signing material off-chain. Only the minimum necessary digest and index are written on-chain; complete business plaintext is not stored on-chain. An on-chain anchor proves that a digest was anchored earlier and does not replace the original off-chain evidence. +# List of sub-components and relation +## Component Overview +The sub-section trusted attestation consists of five protocol components that jointly complete the full chain from the definition of critical business events, the production of chain-based certificate records, the chain-based summary anchoring, to ex post facto verification and dispute resolution support. -TSD centrally maintains the registry of attestation event types. ADD, CID, and PSD reference event identifiers without redefining event structures or attestation governance. Cross-domain evidence chains primarily correlate `intent_id`, `delegation_id`, merchant order transaction number, payment transaction number, and the attestation record's unique identifier. +The functional positioning of the components is as follows. -Attestation MUST occur asynchronously after the business event completes and SHOULD NOT block the main transaction flow or affect online payment latency. ++ **TSD-ATT-EVT: Definition of the type of event to be documented.** Responsible for defining key event types and their standard semantics that can be included at ACT throughout the business chain as a single entry for the processing of subsequent certificates in the sub-chapter. ++ **TSD-ATT-OFF: Sub-chain record-keeping.** It is responsible for regulating the requirements of Participants for the generation, preservation and management of complete documentation at the local level so that key business events can form a retroactive and verifiable first-hand evidence vehicle. ++ **TSD-ATT-OCA: Certificate anchors on the chain.** Regulates the extraction of the minimum summary information necessary from the chain record and the inclusion of the requirement of ACT Trust Chain in order to create a time anchor and cross-institutional basis for validation of the chain that cannot be altered. ++ **TSD-ATT-SVF: Sign verification process.** Responsible for regulating the standard steps for consistent verification of record-keeping, signature material and chain anchorages under the chain in the context of dispute resolution, audit or compliance verification. ++ **TSD-ATT-DSP: Dispute process.** Regulate the process framework for each Participants certificate of proof based on chain record, chain anchors and verification findings. -## 3. `TSD-ATT-EVT`: event-type registry +## Core Object & Identification +In order to maintain consistency between the internal processing of the sub-section and the citation relationships with other domains, the sub-section uses a set of standard core objects and identifiers to describe key messages in the trusted attestation link. The core object of the sub-section and its role can be summarized as follows. -The event namespace is `act::`. The current standard set is: +|** Object or Identification**|** Meaning**|** Mainly Generate Location**|** Main Use Location**| +| --- | --- | --- | --- | +|Testified Events|Standardized event expression for ACT key business node of the full chain to clarify what is to be documented and the unified semantic of the event|TSD-ATT-EVT|TSD-ATT-OFF, TSD-ATT-OCA, and associated processes in other domains when referring to the deposition event identifier| +|Only identifier for record-keeping|For the sole identification of the record of the certificate under a chain and as the main key to stabilize the link between the record under the chain and the anchor point on the chain|TSD-ATT-OFF|TSD-ATT-OCA、TSD-ATT-SVF、TSD-ATT-DSP| +|Underlink record.|A complete record of events generated by Participants and kept locally, usually containing the content of events, Participants information, summary value and signature material, as a first-hand object of evidence in the handling of disputes|TSD-ATT-OFF|TSD-ATT-OCA、TSD-ATT-SVF、TSD-ATT-DSP| +|Store anchor on the chain|Light Quantified Summary Certificate taken from the chain record to create unmovable anchor record on ACT Trust Chain|TSD-ATT-OCA|TSD-ATT-SVF, TSD-ATT-DSP and cross-agency verification scenes| +|Validate conclusion|Standard results resulting from consistent verification of chain records, signature materials and chain anchors to determine whether the records are complete, authentic and unmistakable|TSD-ATT-SVF|TSD-ATT-DSP, and follow-up on audit, compliance verification, etc.| +|Requests for settlement of disputes|A request for evidence or processing initiated by a disputing party in relation to a particular chain of transactions, usually relating to a specific business event, a transaction identifier and a description of the dispute|TSD-ATT-DSP|TSD-ATT-DSP and related arbitration, verification and processing| -| Event identifier | Trigger semantics | -|---|---| -| `act:delegation:intent-created` | The user confirms intent and a result available for authorization processing is formed | -| `act:delegation:delegation-issued` | An IAC is issued and enters `Active` | -| `act:delegation:delegation-suspended` | An IAC is suspended | -| `act:delegation:delegation-resumed` | An IAC returns from suspension to active use | -| `act:delegation:delegation-revoked` | An IAC is revoked | -| `act:delegation:delegation-expired` | An IAC expires | -| `act:commerce:decision-logged` | The Buyer Agent completes candidate comparison or records a decision | -| `act:commerce:cart-confirmed` | Transaction confirmation completes and the transaction may enter payment | -| `act:payment:transaction-completed` | Payment completes and produces a payment result | -| `act:commerce:fulfillment-completed` | Merchant-order fulfillment completes | +## Dependence and Cross-domain Reference +TSD-ATT-EVT is the logical starting point for this sub-section to define which key business nodes can be included in trusted attestation and the unified semantics of these events. -This component currently freezes only event identifiers and basic trigger semantics. It does not define a complete `event_body`, field-level validation, signature envelope, or on-chain format for each event type. +TSD-ATT-OFF Generates under-chain documentation according to the type of event defined by TSD-ATT-EVT and forms the subject of evidence relied upon for anchoring and ex post verification in the subsequent chain. -## 4. `TSD-ATT-OFF`: off-chain attestation record +TSD-ATT-OCA Further references to core summary information in the chain certificate record, completing the chain anchoring, thus providing a cross-institutionally verifiable basis for tampering with the chain record. -### 4.1 Record composition +TSD-ATT-SVF also relies on the chain record and chain anchor to perform consistency verifications in order to arrive at a standardized verification conclusion. -An off-chain record has six parts: basic metadata, end-to-end correlation and provenance identifiers, privacy and inference-resistance elements, participant list, `event_body`, and digital signatures. +TSD-ATT-DSP is based on chain records, chain anchors and verification findings to organize evidence, verification and processing processes in the context of the dispute. -| Part | Minimum semantics | -|---|---| -| Basic metadata | Unique attestation-record identifier, event type, business-event time, record-creation time, and structure version | -| Chain identifiers | Required `intent_id`; conditionally required `delegation_id` in delegated scenarios; conditionally required merchant order number after confirmation; conditionally required payment transaction number after payment; optional upstream-record reference | -| Privacy and digest | An independent high-entropy random salt for each record, payload hash, and hash-algorithm identifier | -| Participant list | At least one participant identifier and role; the represented principal MAY also be recorded when acting by proxy | -| `event_body` | Necessary business plaintext for the current event, or privacy-processed business facts | -| Digital signature | Signer, algorithm, Base64url signature value, and signed scope | +Together, these relationships constitute a closed ring link to the “definition of the event — scarring under the chain — anchoring on the chain — ex post facto verification — dispute resolution”. -Business-event time and record-creation time MUST be recorded separately and SHOULD use ISO 8601 UTC. Once created, a record MUST NOT be structurally changed without a new version. +trusted attestation sub-sections maintain a unified register of the type of event for which the certificate is filed; Authorization & Delegation Domain, Commerce Interaction Domain and Payment Services Domain refer only to the event identifier in the relevant components and do not repeat the structure of the event or the certificate governance rules within their respective domains. -### 4.2 Privacy, hashing, and signatures +On cross-domain links, the sub-chapters create a link of evidence across the entire chain from authorization, confirmation of transactions, payment execution to dispute resolution, mainly through the `intent_id`, `delegation_id`, Merchant side order transaction number, payment transaction flow and unique identification of certificate records. -- Every record MUST use an independent, cryptographically secure random salt with an original length of at least 128 bits. Salts MUST NOT be reused across records. -- Canonicalize `event_body` and the participant list with RFC 8785 JCS, concatenate the canonical byte sequence with the original salt bytes, then hash with SHA-256 or SM3 and store the digest as Base64url. -- `event_body` MUST NOT contain high-sensitivity plaintext such as real names, identity-document numbers, contact details, bank-card numbers, or payment-account numbers. Fields that cannot be recorded in plaintext SHOULD store a digest with explicit semantics. -- The signature MUST cover at least `event_body`, participant list, random salt, unique attestation-record identifier, and business-event time. Every record MUST contain at least the initiator's signature and MAY contain joint signatures. -- Historical records MUST NOT be rewritten because of a protocol upgrade. A parser selects compatible logic using the record structure version. +# TSD-ATT-EVT: Definition of the type of certificated event +## Overview +TSD-ATT-EVT (Attestation event) is used to define the standard storage event type in the ACT trusted attestation system and to harmonize the incident identifiers and basic semantics on key operational nodes Authorization & Delegation Domain, Commerce Interaction Domain and Payment Services Domain. +This component performs the role of a global event type registration form in the system, and includes trusted attestationScope for key events, SHALL for which registration and reference is consolidated in this component. -## 5. `TSD-ATT-OCA`: on-chain attestation anchor +This component defines only the type of key event that can be documented and does not define the temporary state of operation within each business area, the step of realization or the private intermediate event of the manufacturer. -An on-chain anchor and its off-chain record have a one-to-one mapping through the unique record identifier and payload hash. The anchor SHOULD use JWS Compact Serialization. Its header MUST at least express the algorithm and key reference. Its payload expresses: +The current protocol specifies only the standard certificate type of event and its underlying trigger semantics, and does not specify the complete `event_body` structure of each event, field level verification rules, signature sealing or chain anchoring formats. -- unique record identifier, protocol or structure version, event type, and business-event time; -- JWT issuance or anchor-submission time; -- `intent_id` and, when applicable, `delegation_id`, order number, and payment transaction number; -- submitter identity, payload hash, hash algorithm, and ACT Trust Chain privacy-channel identifier; -- optional extensions that contain no business plaintext or sensitive identity or payment-account information. +## Participants and prefix +Participants includes Authorization & Delegation Domain, Commerce Interaction Domain and Payment Services Domain related to the generation of critical business events, as well as the manager responsible for maintaining registration information on the type of documented event. -Submitting the same unique record identifier is idempotent: a node MUST reject duplicate anchoring and return the existing block height or equivalent location. An anchor MUST NOT be overwritten after being written. Later supplements use a new record or a compatible extension. +Before entering this component, SHALL satisfies the following preconditions. -ACT 2.1 identifies ACT Trust Chain as the anchoring infrastructure but does not define a directly implementable public node interface, network parameters, authentication, JWS field names, or Schema. These are future implementation or later-version work and MUST NOT be invented by this repository. ++ The relevant business area SHALL have been identified for inclusion in the key business nodes at trusted attestation Scope and their completion conditions. ++ The relevant Participants SHALL be able to provide stable business linkages markers to support chain-based records, chain anchors and cross-domain links in dispute resolution. ++ The above-mentioned associated identification SHOULD includes at least `intent_id` and may further include `delegation_id` and each business area transaction identifier, depending on the specific scene. -## 6. `TSD-ATT-SVF`: signature verification +## Basic requirements +The standard event-type naming space in this component is in the form of `act::`, where `domain` indicates the business field to which the event belongs, and `event` indicates the specific critical business event within that domain. -Verification follows **off-chain before on-chain, digest before signature, current record before upstream chain**: +The standard event type SHALL have a stable, enumerable, cross-domain-referenced character, SHALL NOT changing its basic semantics due to a single difference. The same business event can be documented separately at Participants, but Participants at the time of reference uses the same standard event identifier and is understood in a consistent trigger syntax. -1. Retrieve the complete off-chain record by its unique identifier. -2. Obtain the public key that was valid at the business-event time from a DID document, ACT Trust Chain trust registry, or another trusted source. If unavailable, return `PUBLIC_KEY_UNAVAILABLE`. -3. Recompute the payload hash using the same JCS, salt, and algorithm. On mismatch, return `PAYLOAD_HASH_MISMATCH`. -4. Verify each declared signed scope. On invalid signature, return `SIGNATURE_INVALID`. -5. Query the on-chain anchor and compare the hash. If absent, return `ANCHOR_NOT_FOUND`; if different, return `CHAIN_HASH_MISMATCH`. The source recommends a 30-second timeout and at most three retries, returning `ANCHOR_QUERY_TIMEOUT` after the final timeout. -6. If an upstream-record reference exists, the causal chain MAY be verified recursively. -7. Return `VERIFIED` after all required checks pass. +SHOULD reports of documented events that take place at the end of the business event, SHOULD NOT takes over the main business process path, and SHOULD NOT affects the processing of online transactions. -Temporary unavailability of an external dependency does not mean the record was tampered with. `VERIFIED` means only that cryptographic checks and on-chain/off-chain consistency pass; it is not a final no-dispute conclusion for contractual, regulatory, or arbitration purposes. +## Standard type of event +The standard type of event included in the current version TSD-ATT-EVT is as follows. -## 7. `TSD-ATT-DSP`: dispute handling +|Event type identification|Own Field|Trigger Time| +| --- | --- | --- | +|`act:delegation:intent-created`
|ADD|user intent Trigger when confirmation is completed and the result of intent is available for subsequent authorization| +|`act:delegation:delegation-issued`
|ADD|Intent Authorization Credential Trigger when issuance is completed and active| +|`act:delegation:delegation-suspended`
|ADD|Intent Authorization Credential Trigger when hung| +|`act:delegation:delegation-resumed`
|ADD|Intent Authorization Credential Triggered when restored to Active status by Suspended| +|`act:delegation:delegation-revoked`
|ADD|Intent Authorization Credential Trigger when revoked| +|`act:delegation:delegation-expired`
|ADD|Intent Authorization Credential Trigger when expiry| +|`act:commerce:decision-logged`
|CID|Buyer Agent Trigger when candidate comparison or decision is completed| +|`act:commerce:cart-confirmed`
|CID|Cart Confirmation Trigger when transaction confirmation is completed and entered for start-up payment| +|`act:payment:transaction-completed`
|PSD|Trigger when payment transactions are completed and form payment result| +|`act:commerce:fulfillment-completed`
|CID|Merchant Trigger when performance of the side order is completed| -Dispute handling is organized as **application, evidence submission, verification, and disposition**. A disputing party submits the dispute type, correlation identifiers, and description. Each party submits its off-chain records. The processor runs `TSD-ATT-SVF`. An arbitrator or processor makes a disposition based on the evidence and verification results. +These events constitute the standard set of events in the current version trusted attestation, covering key nodes such as mandate formation and change of status, business confirmation, performance completion and payment completion. -This component defines only the workflow framework. The arbitrating body, evidence-submission deadline, evidence priority, supplemental-evidence rules, and final-decision rules are determined by network agreements, governance documents, or legal arrangements and are not conclusions of the current TSD specification. +# TSD-ATT-OFF: Subchain record-keeping +## Overview +The standard structure, method of generation, preservation requirements and cross-domain chain rules for recording under the chain in the ACT system are the basic components of Participants for local credible trails of critical business events. -# Part II: Credit Association +This component carries elements such as the statement of business event to be certified, Participants identification, link identification, load of Hashi and digital signatures, which are used to provide a verifiable original basis for anchoring, signature verification and dispute resolution on the subsequent chain, without explicitly placing the business on the chain. -## 8. Principles, objects, and components +## Participants and prefix +Participants includes Participants related to the generation of critical business events and documentary responsibility in Authorization & Delegation Domain, Commerce Interaction Domain and Payment Services Domain, as well as a depository service provider who can be entrusted with record-keeping or search services. -An associated subject may be a natural person, legal entity, or organization with a verified development, deployment, operational, controlling, or other relationship to the Agent. Associated credit is only a supplemental risk reference for an explicit purpose, scope, and validity period: +Before entering this component, SHALL satisfies the following preconditions. -- the source MUST be marked `ASSOCIATED_CREDIT`; -- it MUST NOT be represented as the Agent's independent credit, independent reputation, credit rating, or credit capacity; -- it MUST NOT expand or replace an IAC authorization boundary; -- it MUST NOT replace payment authorization, account validation, anti-fraud, anti-money-laundering, or other independent controls; -- a verification result does not directly constitute transaction admission, credit granting, or payment approval. ++ The relevant operational event SHALL have met the trigger conditions for the corresponding standard type of event in TSD-ATT-EVT, and the initiating or record generator SHALL be able to obtain a stable business connection sign, including at least `intent_id`, and may further include `delegation_id`, Merchant side order transaction and payment trade stream water. ++ The record generator also has SHALL available signature private keys, decryptionable identifiers, recognized time expressions, and local secure storage capacity or fiduciary storage arrangements that meet the requirements before the record is stored under the creation chain. -| Component | Purpose | -|---|---| -| `TSD-CRD-ASC` | Establish the association and issue a Credit Association Credential | -| `TSD-CRD-MAP` | Map the associated subject's credit declaration into an Agent associated-credit declaration | -| `TSD-CRD-LCM` | Manage credential suspension, resumption, revocation, expiration, replacement, and reassessment | -| `TSD-CRD-VER` | Verify the credential itself or further verify current associated-credit information | -| `TSD-CRD-AUTH` | Constrain the subject, purpose, data items, and frequency of associated-credit queries | +## Basic requirements +Under-chain certificate record SHALL be generated by structured data models and can be stabilized by subsequent loads of Hashi calculations, digital signatures, chain anchoring and verification processes, so that records cannot undergo structural changes without version numbers once they are generated. -Core objects include a Credit Association Application, Credit Association Credential, associated-subject credit declaration, Agent associated-credit declaration, associated-credit mapped value, credit-query authorization, and credit-verification record. +Under-chain certificate record SHALL adhere to the principle of “business completion, proof-of-assist reporting” and the actual time of occurrence of an operational event is recorded separately from the time of creation of the certificate record SHALL to clarify the difference between the time of completion of the business and the time of deposit. -## 9. `TSD-CRD-ASC`: establishing credit association +The CSR SHALL support the four capabilities of cross-domain chain, privacy protection, protection from tampering and accountability, i.e., ability to restore the chain, avoid sensitive explicit leaks, detect subsequent modifications through Hashi and signatures, and identify who is responsible for the authenticity of the record. -### 9.1 Flow +## Underlink recorder structure +Under-chain documentation records consist of six parts: basic metadata, full-chain links and tracer identification, privacy and inference elements, Participants list, event load `event_body`, digital signature; to achieve the addition of an extended field without compromising compatibility. -1. The associated subject submits the Agent identifier, association evidence, role, purpose, scope, and replay-resistance elements. -2. The credit service provider verifies subject identity, association, and role match, and obtains confirmation of the Agent, purpose, scope, validity, query authorization, and revocation method. -3. The credit service provider creates an Agent associated-credit declaration according to `TSD-CRD-MAP`. -4. The Credit Association Credential issuer creates and signs the credential. Its state after issuance is `ACTIVE`. +In addition to expanding fields, the core field SHALL in each part has a stable semantic and SHALL have a consistent naming or one-map relationship with the relevant fields TSD-ATT-EVT, TSD-ATT-OCA, TSD-ATT-SVF to avoid ambiguity at the bottom of the chain and at the verification stage. -### 9.2 Credential semantics +### Basic metadata +Basic metadata are used to identify “what this record is, what version it belongs to, when the business occurs, when the record is generated” as the only identification for each record, ensuring that the record is accurately located and analysed across versions. -The credential MUST at least express credential, application, Agent, associated-subject, and issuer identifiers; association-evidence reference; confirmation method; associated-credit mapped value; `ASSOCIATED_CREDIT` source marker; mapping rule and version; association-confirmation statement; applicable purpose and scope; issuance and effective time; state-query information; and issuer signature. A reference to the associated-subject credit declaration is conditionally required when associated-credit information is provided. +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Only identifier for record-keeping|Required|The value given by the record generator at the time of creation, as soon as SHALL NOT changes| +|Event type identification|Required|SHALL be the registered number of entries in TSD-ATT-EVT| +|Business event time|Required|Actual occurrence of business events (non-documented record creation time) recorded by the sponsor at the completion of the event| +|Certificate record creation time|Required|Certificate record creation time, later than business event time, reflecting anecdotal reporting| +|Certificate record structure version number|Required|For future versions to be compatible| -The declaration reference, mapped value, and mapping-rule identifier and version form a three-part traceability set. If any element is missing, the mapped value MUST NOT be independently interpreted, compared, or used. +The record generator SHALL record the time of the business event and the time of the creation of the record of the record of the record of the record of the record of the record of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction, and the time of the creation of the record of the record of the record of the record of the record of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the business of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the record of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the record of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the transaction of the record of the record of the record of the record of the transaction -The confirmation method is one of: +### Full link and trace identification +The full chain link and the tracer mark are used to record “what business link this matter belongs to” and to provide a complete end-to-end causal chain of evidence at different Participants points of time, ensuring that the complete picture of the transaction can be restored in the event of a dispute. -- `DIRECT_SIGNATURE`: the associated subject signs the application and critical confirmation content as an inner signature; after verification, the issuer adds an outer signature, producing two signature layers. -- `ATTESTED_CONFIRMATION`: the associated subject completes identity verification and interactive confirmation through the credit service provider; the credential contains only the issuer's outer signature. +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Intentional markings|Required|Global business process master key, all certificates of the same business process SHALL carry the same intent identification| +|Delegated identification|Conditionally required|Carrying SHALL commission payment scene| +|Merchant side order transaction number|Conditionally required|Events after Cart Confirmation SHALL carry| +|Pay the Trade Stream.|Conditionally required|Pays for events following execution SHALL carried, corresponding to PSP return value| +|References to upstream certificates|Optional|Unique identification of the record of evidence pointing to a related upstream event; SHOULD carried when there is a specified upstream event, which can be used to construct the end-to-end causal chain of evidence| -The association-confirmation statement MUST explicitly state role, scope, purpose, and responsibility boundary. It proves only the subject's confirmation of the association and permitted use; it does not guarantee the Agent's transaction, payment, or fulfillment result. A confirmation MUST NOT be reused for another Agent, subject, role, purpose, scope, or application. +The intended identification (`intent_id`) SHALL be used as a global lead chain that crosses ADD, CID, PSD, and TSD, while the other identifiers are used as auxiliary strings at different stages of the operation. +When there is a clear causal link between the current event and the critical upstream event, the record generator SHOULD fills in the reference to the upstream certificate record to support TSD-ATT-SVF in the implementation of a back-to-back upstream chain check, if necessary. -When a core field changes materially, a new credential MUST be issued and related through a predecessor-credential reference. The old credential MUST NOT be overwritten. +### Privacy and inference-proof elements +The privacy and inference elements are used to address the “how to ensure that records are not tampered with without explicit exposure” and to reduce the risk of inversion of certificate content through known operational data by introducing random salinity values that make the summary values of each record unique and unpredictable. -## 10. `TSD-CRD-MAP`: associated-credit mapping +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Random salt value|Required|Each certificate record SHOULD contain an independent high entropy random salt value of not less than 128 bit in original length and is generated using a password safe random number generator.| +|Load Hash|Required|The event load and the Participants list are treated in a standardized manner and the password summary values obtained are calculated in conjunction with random salinity values; SHOULD be stored in Base64url code.| +|Hash algorithm identifier|Required|The current version supports SHA-256 or SM3; if subsequent versions support other algorithms, SHALL adopt the explicit statement of the field.| -The associated-subject credit declaration is an independent object and SHOULD include a declaration identifier or version, credit service provider, issuance time, validity period, and signature or equivalent proof. The Credit Association Credential references it rather than directly carrying its original credit content. +The steps in the calculation of the load of Hashi are as follows. -The credit service provider determines the concrete score, level, and mapping model. TSD requires only that: ++ Deals with the event load with the Participants list field by the RFC 8785 JSON Regularization Program (JCS) as a byte sequence. ++ Collapse the byte sequence with the original byte of the random salt value, in the order of " Regulate the byte series ∥ salt value byte ". ++ Performs SHA-256 or SM3 calculations for collage results. ++ Stores the calculation with the Base64url encoding as a load of Hash. -- every mapping rule has a unique identifier and version; -- results from different rules or versions MUST NOT be directly compared or converted without rule information; -- the declaration reference, mapped value, and rule version are retained and verified together; -- the mapped result has an upper bound and usage boundary independent of the associated subject's own credit; -- the Agent MUST NOT directly inherit all credit permissions, limits, lending capacity, or business qualifications of the associated subject. +The record generator SHALL ensure that a separate random salt value is used for each chain under the certificate, and SHALL NOT repeats the same salt value between multiple records. +When the event load is identical, but with a different random salt value, the recalculated load Hash value is also SHALL different, a feature that is part of this component's insulation design. -A mapped value MAY be a level, interval, state, limit, multidimensional attribute, or another structured form. The source does not freeze a common data structure. +### Participants List +The list Participants records the identity of the parties involved in this business event, specifying “who is involved in this business and who is involved in what role” so that the attribution of responsibility can be clearly established when the dispute arises. -## 11. `TSD-CRD-LCM`: lifecycle +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Mark Participants|Required|Who confirmed the incident?| +|Role Participants|Required|In what capacity the incident was confirmed; the list may include: the payer Agent, the payee Agent, Merchant, Payment Service Provider, Principalagent, the provider of the certificate| +|Agency identification|Optional|When Participants is acting on behalf of other entities (e.g. Agent platform type User completed on behalf of a specific User), record the identity of the Agent| -| State | Semantics | -|---|---| -| `PENDING` | Application created; confirmation, mapping, or issuance incomplete | -| `ACTIVE` | Credential valid and available for in-scope verification | -| `SUSPENDED` | Suspended; MUST NOT produce new passing results | -| `REVOKED` | Irreversibly revoked; terminal | -| `EXPIRED` | Validity period exceeded; terminal | +The list Participants of each record includes at least one role to ensure that each record has a clear responsibility to initiate in order to be traced. The list of roles may include participants identified by the protocol, such as the payer Agent, the payee Agent, Merchant, Payment Service Provider, Principal Agent, the certificated service provider. -Allowed transitions are `PENDING → ACTIVE/REVOKED/EXPIRED`, `ACTIVE → SUSPENDED/REVOKED/EXPIRED`, and `SUSPENDED → ACTIVE/REVOKED/EXPIRED`. The associated subject MAY suspend or revoke voluntarily. The credit service provider MAY trigger suspension or revocation because of anomalies in a declaration, association, evidence, or risk. The issuer applies and records the state change. +The list Participants may contain more than Participants entries when multiple joint certificates exist, but its role SHALL remain clear and non-duplicable. -A change to the associated-subject credit declaration, mapping rule, supporting evidence, role, purpose, scope, or another core field triggers reassessment. First suspend the old credential and recompute the declaration and mapping. If a core field changed, issue a new credential and move the old credential to `REVOKED` after the new credential becomes effective. If there is no material change and the old credential has not expired, it MAY be restored. Historical verification records retain the state at the time, but a relying party MUST be able to identify a later revocation. +The Participants logo SHALL be able to be adapted to the system ' s identity mechanism or to the external lettered identity mechanism, thereby supporting subsequent public key acquisition and accountability judgement. -## 12. `TSD-CRD-VER`: associated-credit verification +### Event Load +The event load (`event_body`) carries “what exactly happened in this matter” as a central part of the chain-based certificate record to preserve key explicits and business elements of the current business node and as a direct basis for reconciling transaction details in the handling of disputes. -Verification has two levels: +The collection of event loads is determined by the type of event, and this component only defines the location, existence and privacy of this part in the chain-based certificate record, and does not list all exclusive fields of different type of event in this section. -1. **Credit Association Credential verification:** check the request, replay protection, requester identity, outer signature, and inner signature when necessary; then verify subject, Agent, role, purpose, scope, the three mapping elements, and current `ACTIVE` state. This level does not retrieve the associated subject's original credit information and therefore does not require credit-query authorization. -2. **Associated-credit information verification:** after level one passes, verify credit-query authorization, current validity of the associated-subject credit declaration, mapping-rule version, and current state of the Agent associated-credit declaration; return only authorized data under data minimization. +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Event Load|Required|Operations that carry current critical business events are explicit and essential business elements whose fields are determined by events-type dynamics| +|Preset Extension Fields|Optional|For carrying additional information that does not affect core authentication; SHOULD NOT contains sensitive data such as sensitive personal information or original payment account numbers| -A request MUST at least express the request identifier and version, credit relying party, Agent, verification level, business purpose or context, requested data items, credential, request time, replay-resistance elements, and request proof. Level two also requires the associated-subject credit-declaration reference. +The event load SHALL NOT contains the following sensitive information: Principal complete identity information, such as real name, document number, contact information, and original payment account number, such as bank card number, payment account number, etc. -A response expresses the verification record, level actually completed, `PASS` / `FAIL` / `INCONCLUSIVE` / `REVIEW_REQUIRED`, reason code, credential state, applicable scope, result time and expiration time, purpose restriction, and response proof. Only when level two passes and is authorized MAY the response return `ASSOCIATED_CREDIT`, mapped value, declaration validity, and mapping-rule version. +The event load may contain non-sensitive business elements such as amounts, currencies, commodity snapshots, time stamp; for fields that cannot be explicitly recorded due to privacy requirements, SHOULD be replaced by a Hashi summary of the corresponding field and is identified with a “summary” or “Hashi” suffix in the synonym of the field. -A critical failure MUST NOT return `PASS`. Insufficient evidence or an unavailable dependency returns `INCONCLUSIVE`. Reassessment in progress or a need for a higher assurance level returns `REVIEW_REQUIRED`. Standard reason-code categories include request, proof, freshness, replay, missing or expired authorization, revoked or out-of-scope authorization, unresolvable Agent, missing or inactive credential, invalid proof, unavailable or invalid credit declaration, and unsupported mapping rule. +### Organisation +A digital signature is used to answer “who is responsible for the authenticity of the record”, to bind Participants identification and the contents of the record through a password signature, to ensure that anything can be discovered by tampering with it, and to provide an irrefutable evidentiary basis for the record under the chain. -## 13. `TSD-CRD-AUTH`: credit-query authorization +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Signing party identifier|Required|Format with Participants Identification| +|Signing algorithm identifier|Required|A signature algorithm value supported by this protocol| +|Sign Value|Required|Base64url Encoding| +|The signature overwrites the description Scope|Required|Overwrite: Event load, Participants list, random salt values, unique identifier for record-keeping, five fields of business event time| -Credit-query authorization permits only querying or verifying associated-credit information. It does not authorize a transaction, payment, fulfillment, or other commercial action. Authorization MUST bind the credit relying party, optional platform proxy, Agent scope, verification level, business purpose, requested data items, validity period, and result-use restrictions. Platform-proxy queries MUST also have a machine-readable frequency limit such as `max_requests_per_window` and `window_duration`. +Each certificate record SHALL contain at least one signature generated by the sponsor of the record and other Participants joint signatures may be attached to enhance the evidentiary effect. -Two authorization modes exist: +The signer's public key SHOULD be obtained from the identity document to which it corresponds or from the letter-registry information to support the subsequent TSD-ATT-SVF signing process. -- **Per-query authorization:** every level-two verification notifies the associated subject for confirmation and independently binds requester, Agent, purpose, data items, request identifier, and validity time. -- **Platform-proxy query:** the associated subject authorizes an explicit platform subject in advance to query within a restricted scope and period without per-query participation. The platform proxy MUST NOT delegate that authority or use results outside the authorized purpose. +## Load Hash calculation requirements +In order to avoid a difference in achieving inconsistent summaries due to the serialization differences of JSON, the record generator should regulate the use of RFC 8785 JCS for the object in calculating the load of Hashi and executing the digital signature. -Every verification MUST check authorization state and request scope. After revocation, a new valid level-two verification result MUST NOT be produced. Responses MUST follow data minimization. +The minimum input set SHALL for the load Hashi includes the list of `event_body` and the list of Participants and SHALL participate in the operation with the independent random salt carried by this record to ensure the sole binding relationship and re-placement feature between the chain record and the chain anchor. -## 14. Current machine-contract and implementation boundary +The same entry records complete consistency of the result of the double calculation of the load Hashi SHALL without changes to the business content, Participants list and salinity values, otherwise it is deemed not to meet the requirements of this component. -ACT 2.1 freezes the business semantics, object-presence requirements, states, and reason codes for Credit Association, but it does not freeze common English wire field names, normative JSON Schemas, version negotiation, error envelopes, or a common HTTP interface for all of TSD. The following still do not constitute formal ACT 2.1 machine contracts: +## Storage and retention requirements +Under-chain certificate records may be stored autonomously by each Participants or may be commissioned to be stored on behalf of the provider of the certificate, but irrespective of who keeps them, the responsibility for the authenticity of the content of the record remains with the originator or signatory of the record, and the provider of the certificate does not acquire the power to modify the original record by proxy. -- public ACT Trust Chain network, node interface, authentication, privacy channels, and formal JWS payload Schema; -- field-level Schema and submission or query interface for each `event_body`; -- identity resolution, historical public-key retrieval, state-query, and registry protocols shared across TSD sub-specifications; -- domain-wide algorithm negotiation, transport envelopes, and conformance profiles. +Under-chain record SHOULD be maintained for a period of time in accordance with applicable laws and regulations, the dispute resolution cycle and the operational risk exposure period, and during the retention period SHALL be guaranteed as searchable, exportable, verifiable and capable of removing, covering and back-up recovery. -The repository provides an explicitly non-normative TSD-CRD Reference Profile at [`code/schemas/tsd-crd/reference-v1`](../../code/schemas/tsd-crd/reference-v1/README.md) and a local Reference Implementation at [`code/samples/tsd-crd-reference`](../../code/samples/tsd-crd-reference/README.md). The Profile selects `camelCase` fields, Ed25519, a deterministic JSON signing projection, and a local HTTP binding. These are optional implementation conventions and MUST NOT be used to reinterpret ACT 2.1 requirements or as a common TSD wire contract. +When the protocol version is upgraded, the structure of the generated record and the verifiable content SHALL NOT is rewritten and the solver SHALL selects the corresponding resolution logic based on the structure version number in the record to ensure that the historical evidence is valid for the long term. -The reference implementation uses only Mock identity, credit, and mapping providers, in-memory storage, and temporary test keys. Passing Schema validation, tests, and the baseline consistency runner proves only that the current `reference-v1` path satisfies the repository checks that were executed. It is not proof of full ACT 2.1 conformance, a real credit service, an ACT Trust Chain node, or production security. The repository still does not invent a credit model, an on-chain network, or production identity and key infrastructure. +# TSD-ATT-OCA: Certificate anchor on the chain +## Overview +TSD-ATT-OCA (On-Chain Actation Anchor) sets the standard structure, submission requirements and chain writing rules for ACT trusted attestation proof anchors in the chain, which are standard components of the chain record entry into ACT Trust Chain. The chain anchor is a light quantitative metadata document derived from the chain certificate record, which does not contain full business specifications, but carries the minimum required index, summary and signature information to provide a non-falterable cross-agency authentication on the multi-consensual ledger. -## 15. Sources +Any unilateral modification of the original text at the bottom of the chain, which is the only link between the chain-based proof anchor and the corresponding chain-based record, would result in the recalculated Hashi values not being consistent with the chain-based anchor, thus preventing subsequent verification. -- Related TSD website reference: [Trust Services Domain](https://www.act-protocol.com/documentation/trust); content not labeled ACT 2.1 is not a normative source for this release -- ADD: [Authorization & Delegation Domain](https://www.act-protocol.com/documentation/delegation) -- Cross-domain scenarios: [Scenarios and business flows](https://www.act-protocol.com/documentation/scenarios) +## Participants and prefix +Participants includes Participants areas responsible for the generation and submission of anchors in the chain, certificate service providers who can be trusted to submit anchors, and ACT Trust Chain node operators responsible for the capacity to write and search anchors. + +Before entering this component, SHALL satisfies the following preconditions. + ++ The standard type of event has been determined in SHALL for the relevant operational event, and its chain-based record SHALL have been generated in accordance with TSD-ATT-OFF requirements, with the only basic fields for the record-keeping, the type of event, the time of the business event, the intention to mark and the load of the Hash value. ++ If the certification service provider is acting as the anchor of the chain, the certificate service provider is only responsible for submitting or searching on behalf, and does not acquire the right to modify or authenticate the contents of the original record under the chain by writing by the Chargé d ' affaires. + +## Basic requirements +The chain proof anchor SHALL follows the Design Principles under the "Current preservation of complete clear and minimal summary on the chain" to ensure inter-agency validation while preserving commercial privacy and storage costs on the chain of control. + +The chain anchor SHALL be capable of establishing a stable one-simulation relationship with the corresponding chain bottom certificate record, in which the sole identifier of the record is used for record-level binding, and the carrying Hash value is used for content-level binding, which together support subsequent chain bottom consistency verification. + +The chain anchor SHOULD be submitted by step after the completion of the business event and the production of the chain-based certificate record, SHALL NOT obstructs the original main business process and SHOULD NOT affects the processing of online transactions. + +The chain anchor SHALL serves as a credible index of proof rather than a complete body of evidence and, in the event of a dispute or audit, continues to SHALL to be a source of original evidence using the chain-based evidence record, which is then combined with the chain anchor to complete the integrity and unmovable verification. + +## Validation anchor structure +The chain proof anchor uses a two-tiered data model, i.e. the base field layer and the extended field layer, where the base field layer is the core element for all anchor points SHALL and the extended field layer is used to fit the additional properties of a given deployment scenario. + +The anchor SHOULD be encapsulated in the form of JWS Compact Management and is written at ACT Trust Chain, the head of the encapsulation SHALL contain the signature algorithm and signature key reference and the load section carries the anchor field as defined by this component. + +### Head request +JWS head SHALL contain at least the signature algorithm and signature key reference to support the source identification and subsequent signature processing of the chain anchor. + +The specific naming and coding of the head field can be determined by achieving layers compatible with JWS Compact Management, but SHALL NOT affects the stable resolution and cross-institutional recognition of anchor loads. + +### Load Fields +The JWT payload contains the following fields. + +|** field syntax**|** Existence**|** Annotations**| +| --- | --- | --- | +|Only identifier for record-keeping|Required|Strictly consistent with the sole marking of the chain-based record-keeping, achieving the only binding of the two| +|protocol version number|Required|Certificate record structure version number| +|Event type identification|Required|SHALL be the registered number of entries in TSD-ATT-EVT| +|Business event time|Required|Consistent with the time of the business event recorded under the chain, use ISO 8601 UTC at SHOULD| +|JWT issuance time|Required|Time of submission of this anchor point to the chain| +|Intentional markings|Required|Global business process tracking marker| +|Delegated identification|Conditionally required|Carrying SHALL commission payment scene| +|Merchant side order transaction number|Conditionally required|Events after Cart Confirmation SHALL carry| +|Pay the Trade Stream.|Conditionally required|Transport of payment type event SHALL| +|Submitting party identifier|Required|Submit Participants identification for this anchor| +|Load Hash|Required|Fully consistent with the loading of the Hash in the chain certificate record, SHOULD using the Base64url code is the only coded basis for the binding of the two| +|Hash algorithm identifier|Required|Current version supports SHA-256 or SM3 and aligns SHALL with the Halshi algorithm statement in the chain record| +|Privacy Channel Identification|Required|ACT Trust Chain's privacy channel identifier for multiple data isolation| +|Preset Extension Fields|Optional|Additional attributes used to fit specific scenes, SHOULD NOT containing business specifications or personal identity information| + +## Structure Map Requirements +The unique identification of the certificate record in the chain anchor, the protocol version number, the event type identification, the time of the business event, the intent marking, the commissioning identification, the order transaction number, the payment transaction flow and the load of the Hashi value, SHALL be consistent with or can be mapped at the relevant field in the corresponding chain certificate record. + +The submitting identifier is used to mark “who submitted the anchor point to the chain” and is not, of course, equivalent to the full collection of Participants in the chain record, so that the Participants list and digital signature information in the backlink record is fully verified at the time of the dispute. + +The introduction of the extended field SHALL NOT destroys the stable semantics of the base field layer and has led to different interpretations of the core of the same anchor point by different institutions. + +## Technical requirements +ACT Trust Chain Node Operator SHOULD provide a standard chain anchoring interface for submission of requests in the form of JWS Compact Security and for return to the chain where the results can be used for subsequent inquiries and verification. + +The only identified anchor in the same certificate record requests SHALL to be considered as an operation, etc., and node SHALL refuses to duplicate and, in response, returns information on the height or equivalent chain of blocks where the anchor already exists, in order to prevent a repetition of anchoring of the same event. + +The chained data structure SHOULD NOT contains sensitive elements such as explicit, sensitive personal information or original payment account numbers, SHOULD contain only deminious Hashi, anonymous indexing and extension without sensitive content, in order to perpetuate the privacy protection principle of the system's “clear and chain-based summary”. + +When an extension of the protocol level occurs in the Hashi algorithm, version number or associated identifier recorded under the chain, the chain anchor achieves SHALL the ability to maintain compatible resolution of the existing version, SHALL NOT destroying the validity of the historical anchor as the new version is online. + +Once the chain anchor has been written, the SHALL NOT is overwritten; if subsequent linkage information is required for business replenishment, SHOULD be achieved by the compatibility of the new chain recording or extension fields, while SHALL NOT returns the existing core anchor content. + +# TSD-ATT-SVF: Sign verification process +## Overview +TSD-ATT-SVF (Signature Verification Flow) is used to specify standard steps for ex post-cipheral verification of documented event records in the ACT trusted attestation system for uniform call in dispute processing, compliance audit and inter-agency verification scenarios. +This component is used to verify the integrity, validity of the signature and consistency of the record under the chain, thus determining whether a record of the certificate can be considered as credible evidence that has not been tampered with and is imputable. + +## Participants and prefix +Participants includes the initiating business Participants, the record holder responsible for the provision of the chain certificate record, the depository service provider for the provision of a surrogate or search service, and the operator of the chain anchor search ACT Trust Chain node. + +Before entering this component, SHALL satisfies the following preconditions. + ++ Verify that the initiating party SHALL be able to obtain the full text of the certificate under the chain to be verified, or at least the sole identifier of the certificate record and the corresponding complete record through a local storage or certificate service provider search interface. ++ The initiating party can also SHALL acquire the signature party's identifier for the current valid public key or historical valid public key and the ability to access the anchor points on the search chain, otherwise the complete authentication closure loop cannot be completed. + +## Basic requirements +The signature verification SHALL follows the sequenced approach of “first, second, first summary, then signature, first current record, then upstream chain” in order to avoid moving directly into higher-cost or more complex subsequent verification steps in the absence of confirmation of base consistency. + +When recalculating the load of Hashi during the verification process, SHALL recalculates the summary values in accordance with the established algorithm using the same normative rule as TSD-ATT-OFF, i.e. following the regularization of the event load and the Participants list with the RFC 8785 JCS. + +If either step is reached with a clear failure conclusion that would negate the credibility of the record, the verification process can be terminated and the corresponding error code returned without the need to proceed with the subsequent steps. + +If the verification cannot be completed simply because external dependence is unavailable, e.g. the chain search time-out or the current valid public key is not available, SHALL return the result of the “summary not available” or “public key not available”, while SHALL NOT miscalculates the record. + +## Checking steps +### Step 1: Retrieval of the record under the chain +Verify that the originator SHALL retrieves the full certificate from the chain storage based on the unique identifier of the certificate record; if the record is held by the certificate provider, SHALL be obtained through the certificate provider search interface. + +The bottom record SHALL of the recovered chain contains at least the core elements required for verification of basic metadata, full chain links and tracer identification, Participants lists, event loads, loads of Hashi values and digital signatures, otherwise the conditions for entering the follow-up verification process are not met. + +### Step 2: Obtaining the public key for signature +Verify the signature party identifier corresponding to each signature element in the digital signature array of the originator SHALL and obtain its public key material for signing. + +For the DID format identification, the public key SHOULD be obtained from the DID document corresponding to that identifier; for the institutional identifier registered in the ACT Trust Chain Trust Register, the public key SHOULD be retrieved from the Trust Register. + +Approving party SHOULD further validates the validity of the public key acquired at the time of the business event, including whether it has rotated, is invalid and is still within Scope the time available for historical signature verification. + +If it is not possible to obtain the current valid public key of the signatory or a valid public key that can be used for historical verification, SHALL terminates the password check and returns `PUBLIC_KEY_UNAVAILABLE`. + +### Step 3: Recalculating and comparing the load of Hashi +Checks that the incident load in the chain response certificate record and the Participants list are recalculated with the random salt value stored in the record in accordance with the algorithm TSD-ATT-OFF. + +Recalculated loads of SHALL be consistent bytes with the loads stored in the bottom certificate record; if not, indicate that the content of the local record or its structured elements may have been changed. + +The verification process SHALL terminates and returns `PAYLOAD_HASH_MISMATCH` when the local recalculation results are inconsistent with the summary kept in the record. + +### Step four: Password checking +The approving party SHALL performs a password-checking each signature element in the digital signature array using the corresponding public key obtained in the second step. +At the time of the examination, SHALL ensure that the signature covers Scope consistent with the covered object stated in TSD-ATT-OFF, including at least the event load, Participants list, random salinity values, unique identification of the record and the time of the operational event. + +If any signature element fails to verify, SHALL return `SIGNATURE_INVALID` and SHOULD with the signature identifier corresponding to the failed signature in order to subsequently locate the subject of the responsibility or screen for the difference. + +If the record contains multiple signatures, the certifying authority will decide, in accordance with the operational rules, whether to require a successful verification of all signatures, but at least SHALL ensure that the collection of signatures deemed valid meets the minimum credible requirements of the scene. + +### Step 5: Chain anchor verification +Approving party SHALL search ACT Trust Chain for the sole identification of the chain anchor in the certificate record and confirm the existence of the anchor. +If the anchor is present, the verification also compares SHALL the loads in the chain anchors to the full consistency of the loads in the 3rd local recalculations. + +The chain query SHOULD sets a time limit of 30 seconds and SHOULD retrys up to 3 times after the time has elapsed; if the time is still exceeded, SHALL return `ANCHOR_QUERY_TIMEOUT` and SHALL NOT determines it to be `VERIFIED` or `CHAIN_HASH_MISMATCH`. + +If anchors exist but there is a discrepancy between the Hashi values in the chain, then SHALL return `CHAIN_HASH_MISMATCH`; if no corresponding anchor points exist in the chain, SHALL return `ANCHOR_NOT_FOUND`. + +### Step six: Continuous validation of the upstream causal chain +If the reference field to the upstream certificate record is present in the current bottom-chain record, the verification should be carried out step 1 to step 5 of the upstream link certificate record to which it is directed, so that the complete end-to-effect chain of evidence can be constructed step by step. + +This step is optional, but of high value in cross-domain dispute resolution, as it supports the overall consistency review of key nodes such as authorization, confirmation, payment, performance by extending the verification of single-point events to a chain-level fact. + +### Step seven: Return to check. +Upon completion of the above-mentioned steps, the Approving Party returns the Standardized Validation Conclusions SHALL to ensure consistency of understanding of the results between the different institutions and the different achievements. + +The verification conclusion SHALL NOT is defined freely, while SHALL gives priority to the use of standard count values specified in this component to support subsequent dispute management, audit trails and automated inter-system interfaces. + +## Validate conclusion +|** Validate conclusion**|** Meaning**| +| --- | --- | +|`VERIFIED`
|The signature is valid, the chain is consistent and the record is intact.| +|`PAYLOAD_HASH_MISMATCH`
|The local recalculated summary is not consistent with the summary stored in the certificate record, which may have been tampered with.| +|`SIGNATURE_INVALID`
|The signature authentication failed and SHOULD was accompanied by a failed signature party identifier.| +|`CHAIN_HASH_MISMATCH`
|An anchor in the chain exists, but the chain summary is not consistent with the local recalculation results, and there may be tampering on or under the chain.| +|`ANCHOR_NOT_FOUND`
|Corresponding anchors do not exist on the chain, and the evidence may not have succeeded in uplinking.| +|`ANCHOR_QUERY_TIMEOUT`
|The chain search is timed out and no final check can be concluded at this time.| +|`PUBLIC_KEY_UNAVAILABLE`
|Could not get the signatory's current valid public key or a valid public key for historical verification, and there may be key rotation or failure to resolve it.| + +When the result is `VERIFIED`, merely indicating that the record has been verified at the level of passwords and in the context of chain consistency is not automatically equivalent to business conduct that has been finally confirmed as uncontested in the sense of a contract, regulatory or controversial decision. + +When the result is not `VERIFIED`, the successor SHOULD takes measures such as additional evidence, re-examination, request for a return to the record or access to the dispute process in combination with the type of failure, while SHOULD NOT treats all failures in the same way. + +## Technical requirements +The verification of data-processing rules consistent with SHALL and TSD-ATT-OFF and TSD-ATT-OCA, particularly with regard to JCS standardization, Hashi algorithm selection, Base64url coding and field mapping, SHALL NOT resulted in different validations of the same records in different institutions as a result of the discrepancy. + +For chain anchors with JWS Compact Regulation, the achieving party corrects the separation and verification of the head, payload and signature parts at SHALL during the decomposition and signature, and ensures that the algorithm statement is consistent with the actual signature algorithm to reduce the risk of the algorithm replacing or defusing the ambiguity. + +The verification system SHOULD retains the process audit log, including the timing of the verification, the verification of the sponsor, the source of the public key used, the results of the chain search and the final verification findings, with a view to restoring the validation process in the subsequent dispute resolution. + +When the signatory rotates the key, SHALL be verified by comparing the time of the business event with the time of validity of the key and continues to be allowed to complete the historical signature check using the old key when the business event time falls within the validity of the old key to ensure long-term validation of historical evidence. + +# **TSD-ATT-DSP: Dispute process** +## Overview +TSD-ATT-DSP (Dispute Resolution) is used to define the process framework in the event of a dispute in the ACT protocol transaction, specifying how each Participants evidence, verification and disposal is based on a chain record and chain anchor. + +This component is an important application export of the trusted attestation system, and the practical value of the certification mechanism is realized mainly through the dispute management landscape. + +This component defines only the process framework and basic requirements; the attribution of decision-making authority to final arbitration, such as the Platform ' s arbitration, industry arbitration committee or judicial body, as otherwise agreed by Participants in an access protocol or related legal arrangement, does not belong to this protocol norm Scope. + +## Participants and prefix +Participants includes the applicant for the dispute, the respondent or other relevant transactions Participants, the processor or arbiter responsible for receiving and organizing the verification, the provider of the certificate of storage or authentication services for the chain record, and the operator of the ACT Trust Chain node providing the chain anchor search capability. + +Before entering this component, SHALL satisfies the following preconditions. + ++ The disputed matter SHOULD already has associated markings that can be used to locate the business link, such as intent identification, commissioning identification, Merchant side order transaction number or one or more of the payment transaction flow numbers, to support the retrieval and chaining of relevant documentary records. ++ The relevant Participants SHALL be capable of providing a complete chain record of certificates retained by the parent, or of extracting the corresponding records from a local storage or certificate service provider search interface based on the unique identifier of the record. ++ The processor also has SHALL capability to search for anchor points on the ACT Trust Chain chain and to obtain valid public key material corresponding to the signatory ' s identifier to complete the bottom chain consistency check and signature validity check. ++ If it is not possible to obtain the necessary public key material for the chain record, chain anchor or signature verification, this component may enter the admissibility and evidence phase, but may not be able to complete the full standardized closure loop. + +## Basic processes +The handling of the dispute SHOULD follows the order in which the “claim in dispute—the parties provide evidence—the documentary examination—forms a disposition” in order to ensure a clear course of processing, a clear boundary of responsibility and a uniform basis for verification. + +The SHALL disputing party submits the type of dispute, the associated identification and description of the dispute for the location of the business link; the relevant Participants SHALL submits the certificate record under the chain within the prescribed time limit; the processing party shall perform the TSD-ATT-SVF verification of the documentary record of the link to the dispute and use the verification findings as an important basis for disposal. + +The decision of the arbitrator or the processing party, after combining the parties' evidentiary material with the findings of verification, shall be considered as one of the grounds of the presumption against the party if a Participants fails to provide the documentary record within a specified time limit or if its documentary record confirms the conclusion that it is not `VERIFIED`. + +|** Process phase**|** Main requirements**| +| --- | --- | +|Dispute application|Submission by the disputing party of the type of dispute, associated identification to locate the business link and description of the dispute| +|Evidence by the parties|Relevant Participants certificates submitted under the chain within the prescribed time limit| +|Certificate Validation|Processors carry out TSD-ATT-SVF verifications of the supporting records on the chain of dispute, with findings as an important basis| +|Disposed conclusions|Processor ' s decision to dispose of consolidated evidentiary material and verification findings| + +## Processing of requests +The dispute management SHALL insists on the basic principle of “based on the original record, based on a password check, and based on a chain anchor as a basis for protection against tampering”, avoiding relying only on unilateral oral statements, logshots of platforms or non-validable secondary compilations to reach conclusions. + +In the course of processing, the chain record is the source of the original evidence, the chain anchor is used to prove that the summary has been pre-established and cannot be tampered with, and the signature verification process is used to confirm the integrity of the record, the validity of the signature and the consistency of the chain. + +Detailed classification of disputes, time limits for proof, mechanisms for recognizance, evidentiary priorities and rules for final adjudication could be further refined in subsequent versions of the protocol or accompanying governance documents, and it is sufficient that this chapter maintains a lightweight process design. + +# Part Two: credit association + +# Scope +## Subdomain Positioning +credit association(Credit Association) is one of the sub-sections of Trust Services Domain. This sub-section provides for the establishment of a Agent relationship between credit association and its associated subject, Agent associated credit statements generation, life cycle management, query authorization and certification rules to provide verifiable reference to Agent related credit in the event of insufficient credit data. + +Related subjects may be natural persons, legal persons or other organizations that have a development, deployment, operation, control or other empirical link to Agent. credit association By establishing a verifiable credit association certificate, the associated subject ' s credit information can be invoked within the explicit application of Scope and form an associated credit statement to the designated Agent. + +> Note: Linked credit is a different source of credit than Agent independent credit or independent reputation. Linked credit is used to express a restricted credit reference to the designation Agent under a valid credit association relationship with the associated subject credit information; Agent Independent credit or independent reputation is used to express Agent its own historical performance in commerce interaction. Associated credit may not be expressed directly as Agent its own credit rating, reputation or creditworthiness. +> + +## Subdomain Scope and Boundaries +This sub-section covers the following: + ++ Application, confirmation, issuance and structural regulation of credit association certificates between related subjects and Agent; ++ Mapping rules, source tags and version management for associated subject credit statements to Agent associated credit statements and associated credit map values; ++ Life cycle management such as credit association vouchers and Agent associated credit statements entry into force, suspension, revocation, expiry, replacement and reassessment; ++ (a) A mechanism for authorization of inquiries by associated subjects for credit validation, including sub-authorizations and platform proxy queries; ++ Mechanisms for standardized verification of credit association relationships and associated credit information by third parties. + +The following are not regulated in this sub-section: + ++ Credit evaluation models, Agent reputation scoring formulas, rules for the award of transactions, rules for the decision-making of payment risks or rules for the conversion of credit across institutions; ++ Agent Mechanisms to create an independent credit or an independent reputation based on its own conduct, performance, dispute or other historical record; ++ Internal realization of any manufacturer, platform, Identity Service Provider, credit information provider, credit provider, payment agency or other Participants. + +## Value statement credit association +When doing business on behalf of User or an organization, the counterparty to the transaction, platform, and risk management system usually need to refer to its identity, behavioral records, and credit information. However, the newly created Agent or an insufficient Agent of behavioural data may not have created a referenceable reputation of its own credit or independence, creating a trust gap. + +credit association By establishing a credit association relationship between a verifiable related subject and Agent, the credit-dependent party is able to provide a supplementary credit reference to Agent associated credit statements, based on the credit information of the associated subject, for a clear purpose, Scope and for a period of time. + +The value of this mechanism is reflected in three main areas: + ++ For Agent, associated credit can provide a complementary reference to trust for their involvement in business collaboration when their own credit data are insufficient. ++ For trading opponents, platforms and credit-dependent parties, the verifiable credit association relationship and Agent associated credit statements provide a standardized risk reference base that helps them to make business judgements in the context of their own strategies. ++ For ecology Participants, credit association may be traced to an identifiable associated subject so that linkages, sources of credit, application of Scope and state changes can be recorded, verified and audited. + +credit association values depend on associated relationships, Agent associated credit statements, search authorizations and verifiable results for verifiable, retroactive, revocable and independent review. + +# List of sub-components and relation +## Component Overview +The sub-section credit association consists of five protocol components, which together complete the full link established at credit association, associated credit generation, life cycle management, search authorization and independent validation. + +The functional positioning of the components is as follows. + ++ **TSD-CRD-ASC: credit association Create.** The mechanism for establishing the relationship credit association between the related subject and Agent, including the associated prefix, the credit association voucher structure and the associated subject identification and issuance process. ++ **TSD-CRD-MAP: Associated credit mapping.** Regulates mapping rules, source tags and version management between associated body credit statements, credit association vouchers and Agent associated credit statements. ++ **TSD-CRD-LCM:credit association Life cycle management.** Responsible for regulatory mechanisms such as credit association vouchers and Agent associated credit statements, state flow, and suspension, revocation, expiry, replacement and reassessment. ++ **TSD-CRD-VER: Associated credit certification.** Regulate the level of certification, information structure, certification process and cause code for the standardized certification of credit association relationships and associated credit information by third parties. ++ **TSD-CRD-AUTH: Credit search authorization.** Responsible for regulating the authorization mechanisms of associated subjects for the certification of associated credit, including sub-authorizations and platform agency queries. + +## Core Object & Identification +credit association uses a standard core set of objects and identifiers to describe key information in the credit association link. The core objects of the subtext and their effects are as follows. + +|Object or Identification|Meaning|Mainly Generate Location|Main Use Location| +| :--- | :--- | :--- | :--- | +|Application credit association|Pending confirmation request by associated subject and Agent before credit association|TSD-CRD-ASC|TSD-CRD-ASC| +|Certificate credit association|Proof of credit association relation, association Scope, confirmation mode and status information between associated subject and Agent|TSD-CRD-ASC|TSD-CRD-MAP、TSD-CRD-LCM、TSD-CRD-VER| +|Associated Subject Credit Declarations|Statements of credit ratings, compartmentalities, status or other credit information issued by credit service guidelines to related subjects|Credit providers|TSD-CRD-MAP、TSD-CRD-VER| +|Agent Linked Credit Statement|Validable credit statements issued by a credit provider against a designation Agent based on valid credit association vouchers, associated subject credit statements and map rules|TSD-CRD-MAP|TSD-CRD-LCM、TSD-CRD-VER| +|Associated Credit Map Values|Credit content expressed externally in Agent associated credit statements may be in the form of ratings, compartments, status, limits, multi-dimensional attributes or other structured form|TSD-CRD-MAP|TSD-CRD-VER| +|Credit query authorization|The associated subject allows a specific requesting party or Agent of the Platform to certify the associated credit information within the limits of Scope|TSD-CRD-AUTH|TSD-CRD-VER| +|Credit verification records|Record of results after validation of credit association vouchers, Agent associated credit statements, search authorization and status|TSD-CRD-VER|Credit-dependent parties, follow-up certificates and dispute resolution| + +Of these, credit association vouchers are used to demonstrate the link between the related subject and Agent; the associated subject credit statements are used to express the credit information of the related subject; and Agent associated credit statements are used to express the relevant credit information based on the association and the related subject's credit information Agent. + +The associated credit map SHALL clearly marks its credit source `ASSOCIATED_CREDIT` and may not be expressed as Agent its own independent credit or reputation. + +## Dependence and Cross-domain Reference +credit association sub-sections can be quoted as required by Authorization & Delegation Domain, Commerce Interaction Domain and Payment Services Domain. Commerce Interaction Domain may refer to the results of the associated credit certification at the point of entry to the transaction, the choice of the counterparty, and Payment Services Domain may refer to the results of the associated credit certification at its risk management, level strategy or unusual treatment. + +Linked credit certification results are entered only as risk reference or business decision-making, and may not be extended, modified, covered or replaced by Authorization & Delegation Domain authorized boundaries, nor may they be a substitute for the payment authorization, account verification, anti-fraud, anti-money-laundering or other independent risk control required by Payment Services Domain. + +# TSD-CRD-ASC: credit association Create +## Overview +TSD-CRD-ASC Establishment to define the relationship between the related subject and Agent, including the associated pre-condition, the standard structure of credit association vouchers and the associated subject identification and issuance process. + +This component is the logical starting point for sub-section credit association. Once the associated subject has completed the identification, relationship verification and confirmation through this component, the issuer of credit association produces a certified credit association certificate, which provides the basis for subsequent associated credit mapping, life-cycle management and independent validation. + +## Participants and prefix +This component covers the following Participants: associated subject, Agent, credit provider and credit association certificate issuer. + ++ The subject of association is a natural person, legal person or other organization having a development, deployment, operation, control, liability or other empirical link to Agent; ++ Credit service providers assume responsibility for the identification of related subjects, the verification of relationships and related credit services; ++ The issuer of credit association certificate is responsible for the generation and issuance of credit association certificate; ++ The credit provider and the issuer of the credit association certificate may be the same entity or may be borne separately by different entities. + +Before entering this component, SHALL satisfies the following preconditions: + ++ The identity of the subject concerned can be verified by the credit provider; ++ (a) Agent with a decipherable identifier, as well as identification documents, control materials or equivalents that can be used to verify the connection; ++ The subject(s) can provide evidence of their association with Agent; ++ credit association in the application SHALL identifies the relevant subject, Agent, the relevant role, the applicable purpose, the application of Scope and other necessary restrictions. + +SHALL provide control material or equivalent proof that matches its control Scope when the associated subject declares that the associated actor is the controller, operator or other actor involved in physical control. SHALL provide evidence that matches its declared role when the associated subject is the developer, the deployer or other non-controlled actor. + +## Process Steps +**Step 1: Initiate credit association application** + +Associated entities initiate credit association applications to credit providers and submit identifications, relevant identification documents or supporting material, associated roles, purpose of use, application of Scope and re-entry elements to be associated with Agent. + +The credit provider performs a preliminary verification of the application, confirms that the application is complete, that the request has not been re-issued, and generates credit association applications pending confirmation. + +**Step II: Verification of the identity and relation of the relevant subject** + +The credit provider carries out an identification check of the applicant at credit association to confirm that his/her identity is consistent with the alleged affiliation. + +Credit providers SHALL further verify the connection of the related subject to Agent, including but not limited to the associated role of development, deployment, operation, control or other declaration. After the linkage verification, the associated subject SHALL further confirms the information to be associated with Agent, the associated role, the applicable purpose, the application of Scope, the validity period, the means of searching for authorization and the manner of revocation. + +**Step 3: Generate credit association certificates to be issued** + +The credit service provider produces the associated credit statement in relation to Agent in accordance with the associated credit map rules specified in `TSD-CRD-MAP`, based on the credit association application verified and confirmed by the related subject. + +The credit provider SHALL shall notify the issuer of credit association certificates of the resulting Agent associated credit statements, as well as of the confirmed related subject ' s association information with Agent, the applicable purpose, the application of Scope, the confirmation of the relationship statement and the confirmation material, for the production and issuance of credit association certificates. + +**Step 4: credit association Certificates issued** + +credit association certificate issuer SHALL produces credit association certificate according to the certificate structure defined in Section 3.4, based on the certified credit association application, the associated entity confirmation results and the associated credit statement Agent generated by the credit provider. + +credit association The issuer of the certificate shall sign the key field of the certificate. The reference to the associated subject ' s credit statement, the associated credit map value, the map rule identifier and version of the certificate, SHALL be consistent with the Agent associated credit statement generated by the credit provider. + +Upon the issuance of the credit association certificate, it will be placed in the state of `ACTIVE`. credit association certificate issuer SHALL provide credit association valid certificate to Agent or its trustee for subsequent associated credit mapping and associated credit validation scenes. + +## credit association voucher structure +The credit association voucher contains the following fields. + +|field syntax|Existence|Annotations| +| --- | --- | --- | +|Certificate Identification|Required|credit association certificate unique identification| +|Certificate Version|Required|Document structure version currently in use| +|credit association Request for identification|Required|credit association application pointing to this document| +|Mark Agent|Required|Mark the current credit association corresponding to Agent| +|Associated Subject Identification|Required|Identify the relevant subject of the current credit association| +|Associated roles|Optional|The role of the associated subject in relation to Agent, such as the developer, the deployer, the operator, the controller, the responsible subject or other defined role| +|Issuer identifier|Required|Current identity of issuer of credit association| +|Reference to Agent|Required|Identification document, control material, supporting documents or references to equivalent material to verify the connection between the subject and Agent| +|Related Subject Recognition|Required|`DIRECT_SIGNATURE` or `ATTESTED_CONFIRMATION`| +|Associated Subject Credit Statement Reference|Conditionally required|Need to provide associated credit information, pointing to the related subject ' s credit statements| +|Associated Credit Map Values|Required|Linked credit expression after mapping to Agent, which may take the form of ranking, partition, state, limit, multi-dimensional properties or other structured form| +|Associated credit source tags|Required|Identification of associated credit sources, with value `ASSOCIATED_CREDIT`| +|Map rule identifier and version|Required|Map rules and versions used to identify associated credit mapping values| +|Statement of confirmation of association|Required|Confirmation of the connection of the subject to the designation Agent, the associated role, the purpose of application, the application of Scope and the boundary of responsibility| +|Purpose of application|Required|credit association Allowed for business purposes| +|Application Scope|Required|credit association Applicable scene, type of transaction, type of requesting party or other restriction| +|Public key controlled by associated subject|Conditionally required|The confirmation method is `DIRECT_SIGNATURE` required to verify the inner layer signature of the associated subject| +|Associated body signature value|Conditionally required|Confirmation by `DIRECT_SIGNATURE` required, i.e. associated body inner layer signature value| +|Associated Subject Signing algorithm|Conditionally required|Identification by means of `DIRECT_SIGNATURE`, identifying algorithms and versions of signatures in the inner layer| +|Time of issue|Required|Document Generation Time| +|Entry into force time|Required|Validation time of document| +|Expiry Time|Optional|Validation time of certificate| +|Status Query Information|Required|Quoted or Equivalent Information for Querying the Current Status of the Document| +|Presequenced voucher references|Optional|Forward sequence when association replaces, renews or association supports rotates| +|Signing value of certificate issuer|Required|External signature value of credit association certificate issuer to key field of certificate| +|Credential issuer signature algorithm|Required|Identifies the algorithm and version used for the outer signature| + +Of these, the associated subject credit statements, the associated credit map value, the map rule identifier and the version constitute the three traceable elements of the associated credit map. + +### Related Subject Recognition +The two approaches SHALL have the same core semantics: the associated entity clearly knows and agrees to establish credit association with the designation Agent, confirming that the results may not be diverted to other Agent, other associated subjects, other purposes, Scope or other credit association applications. + ++ **DIRECT_SIGNATURE**: The associated entity uses its controlled private signature key to sign credit association directly to the key element. credit association The issuer of the certificate verifies the internal signature of the associated subject and then signs the credit association certificate externally with its own private signature key. In this way the certificate has two layers of signature. ++ **ATTESTED_CONFIRMATION**: The related subject completes the identification and cross-identification by the credit provider, and the certificate is issued by the credit association issuer on the basis of the credit provider's confirmation. + +### Signature data Scope +Under `DIRECT_SIGNATURE` confirmation, the associated subject shall sign the credit association application and its confirmation at the inner level. + ++ Internal signatures SHALL cover, at a minimum: credit association application marking, Agent identification, associated subject identification, associated role, references to association evidence, association confirmation statements, associated credit mapping information, applicable purpose, application Scope, validity period, issuer identification and re-discharge protection elements. + +Regardless of the means of confirmation, the issuer of the credit association certificate shall sign the document at the outer level. + ++ The external signature SHALL cover the identification of the certificate, the version of the document, the issuer ' s identifier, the identification of the associated subject, and all core fields in the credit association certificate except for status information, signature information and the reference to the pre-certificate; and SHALL also covers the public key information required for the internal signature of the associated subject and its authentication under `DIRECT_SIGNATURE`. + +The certificate ' s current status, status query information, pre-certificate references, external signature values and outer signature algorithms do not participate in the outer signature data Scope. The current status SHALL be maintained separately by the State Machine system referred to in the status query information; the state flow SHALL NOT invalidates the certificate signature and SHALL corresponds to the status management mechanism `TSD-CRD-LCM`. + +## Processing of requests +The credit provider SHALL certifies the validity of the material in relation to the related subject and Agent and prevents another person from initiating an application credit association on the basis of unauthorized Agent identity, controlled material, associated role or subject. + +The correlation certification includes the following scenarios: + ++ **Initial Authentication** At credit association application stage, the applicant is identified as true and relevant, and there is a correlation between the applicant and Agent that matches his declared role; only after certification can the relevant subject confirm and issue the certificate. ++ **Continuous revalidation** SHALL triggers a re-certification when the associated certifying material is rotated, controlled material changes, key leak signs are identified, Agent operating subject is changed, the associated subject is in an abnormal state of identity or has reached the pre-set re-certification cycle. ++ **Unusual disposal**: credit association certificate SHALL transferred to `SUSPENDED` or `REVOKED` at `SUSPENDED` or at `REVOKED` when a re-certification has not been made, or when a credit provider finds that the association is likely to lapse, is forged or exceeds the declared Scope. + +The results of the confirmation by the associated subject may not be diverted to other Agent, other related subjects, other associated roles, other purposes, other applicable Scope or other credit association applications. + +The link in the certificate confirms the associated role, link SHALL identified by the related subject, the purpose of application and the application of the boundary, and may not be empty or use vague and potentially misleading statements. The link confirmation statement is used only to prove that the relevant subject ' s confirmation of the credit association relationship and its use Scope does not constitute a commitment to the result of the transaction, payment, performance or other business conduct Agent. + +SHALL issues new credit association certificates and establishes a link by reference to prior documents when the related subject, Agent, associated role, supporting information, confirmation of association, associated subject credit statements, associated credit map values, mapping rules, applicable purpose, application of Scope or a material change of validity. + +# TSD-CRD-MAP: Associated credit mapping +## Overview +TSD-CRD-MAP (Associated Credit Mapping) is used to specify map rules for associated subject credit statements to Agent associated credit statements. + +This component sets out the requirements for standardization of the associated credit mapping process and the expression of Agent associated credit statements and associated credit mapping values; it does not specify the specific mapping rules themselves. The specific mapping rules are self-fulfilled by credit providers according to their credit model, risk strategy and business requirements. + +This component is quoted in the credit association voucher issuance process at `TSD-CRD-ASC`. The credit provider converts the associated subject's credit statement to Agent associated credit statements in accordance with applicable map rules, and provides the associated credit map value and associated map information to credit association certificate issuer as the basis for the generation of the relevant credit information in credit association certificate. + +## Participants and prefix +This component involves the following Participants: credit provider, and credit association certificate issuer. + +Before entering this component, SHALL satisfies the following preconditions: + ++ The associated subject has completed the identification check and confirmed the application credit association; ++ The link between the subject and Agent has been verified by the credit provider; ++ A credit service provider has obtained a credit statement of the relevant subject or a verifiable reference; ++ The necessary information has been identified in the application credit association, related subjects, associated roles, applicable purposes, application Scope and duration. + +The credit provider SHALL completes the associated credit map before the credit association certificate is issued and provides the results to the credit association certificate issuer. + +## Associated Subject Credit Declarations +The associated subject credit statement is the credit information statement provided by the credit service approach to the related subject and is the input basis for the associated credit map. + +Credit services are able to determine the content of the related subject’s credit statements, the manner of disclosure and access controls based on applicable data protection, privacy protection and business rules. + +The associated subject credit statement SHOULD contain the following metadata: + ++ (b) Declaration marking; ++ (a) The version of the declaration; ++ (b) Credit service provider identification; ++ (a) The time of issue; ++ (a) Duration; ++ Signature or equivalent. + +The credit content of the credit statements of associated subjects, such as rank, spacing, amount, state, multi-dimensional rating or other credit attributes, is issued by the credit service provider in accordance with its credit model. + +## Associated Credit Map Rules +This sub-section does not prescribe rules for a specific associated credit mapping. + +The associated credit mapping process SHALL meets the following standardization requirements. + +**Map rule identification and version:** + ++ Each associated credit mapping rule SHALL have a uniquely identifiable rule identifier and version within Scope management of the credit provider. ++ The map rule identifier and version SHALL be carried on credit association vouchers to identify which map value is generated by. When the map rule is iterative, adjusted or replaced, SHALL update the rule version. The associated credit map values generated by different rules or versions are not directly compared, converted or explained without the rule identifier and version information. + +**Retroactive:** + ++ The associated subject credit statement quotes, the associated credit map value, the map rule identifier and the version together constitute the three traceable elements of the associated credit map. ++ The associated credit map value SHALL be the result of a specified map rule and version that acts on a given associated subject's credit statement. The three elements SHALL be able to be traced back to be saved and validated with credit association vouchers, without which the associated credit map value may not be used as a relevant credit information that can be interpreted, compared or used independently. ++ credit association The issuer of the certificate, when issuing the certificate, verifies the integrity and consistency of the three elements retroactively. + +**Limitations on credit privileges:** + ++ Associated credit may not directly inherit Agent the full credit authority, credit line, creditworthiness or other business qualification of the related subject. ++ Credit service providers should set a ceiling or boundary for the use of the associated credit map that is independent of the related subject ' s own credit, and identify the relevant credit information that can be consulted at Scope, taking into account the associated role, the applicable purpose, the application of Scope, the duration of the period and other risk limits. + +## Agent Associated credit statements and associated credit mapping values +Agent Associated Credit Statements are credit statements generated by credit providers against designated Agent based on valid credit association applications, associated subject credit statements and associated credit mapping rules. + +Agent Linked credit statements are expressed by associated credit mapping values, source information, map basis and use of boundaries. + ++ **Associated Credit Map Values**: Generated by this component to express the results of the credit mapping associated with the designation Agent, which may be in the form of ranking, partition, state, limit, multi-dimensional properties or other forms. ++ **Source Information**: Includes references to related subject credit statements and associated credit source tags. The associated credit source tag SHALL be `ASSOCIATED_CREDIT` and may not be labelled Agent as independent credit or independent reputation. ++ **Map Source**: Includes map rule identifiers and versions, which are used to identify the mapping rules used to generate associated credit map values. ++ **Use boundary**: Includes the purpose of application, the application of Scope, the duration of application and other necessary restrictions. + +The specific data structure of the associated credit map value is defined by the credit provider according to its credit model. The sub-section does not provide for a uniform data structure. The associated credit map value, regardless of the expression, is SHALL to meet the three retroactivity limits and cannot be interpreted independently from the reference and map rule logo and version of the related subject ' s credit statement. + +# TSD-CRD-LCM:credit association Life cycle management +## Overview +TSD-CRD-LCM (Credit Association Lifecycle Management) is used to specify the life cycle of credit association vouchers State Machine, state flow rules, and regulatory mechanisms such as suspension, revocation, expiry, replacement and reassessment. + +This component ensures that the associated subject can revoke credit association and that credit services can trigger suspension and reassessment in the event of a change in the credit statements of the related subject, change in the association relationship, or risk event. credit association When the core field of the voucher changes, SHALL NOT covers the original document, while SHALL issues a new credit association certificate and establishes a prior certificate reference to ensure that the process is retroactive, auditable and subject to review. + +The status of the credit association certificate determines whether the associated credit information it carries can be used for subsequent association credit certification. + +## Participants and prefix +This component involves the following Participants: related subject, credit provider, credit association certificate issuer and credit certification service provider. + +Before entering this component, SHALL satisfies the following preconditions: + ++ credit association application created or credit association certificate issued; ++ credit association The issuer of the certificate is capable of maintaining or searching for the state of the certificate; ++ Credit service providers are able to identify changes in the credit statements, affiliations or other relevant information of related subjects. + +## Life cycle state +The credit association certificate has the following life-cycle status. + +|Status|Meaning| +| --- | --- | +|`PENDING`|credit association application has been created, but the identification of the associated subject, the associated credit map or the issuance of the certificate has not yet been completed| +|`ACTIVE`|credit association vouchers are valid and can be used for associated credit authentication in Scope applicable| +|`SUSPENDED`|credit association vouchers are temporarily suspended and may not result in a new valid associated credit certification result| +|`REVOKED`|The certificate credit association has been revoked and may not be restored to its state of validity| +|`EXPIRED`|credit association certificate is no longer valid and may no longer be used for associated credit certification| + +Of these, `SUSPENDED` may be distinguished by the cause of the trigger as the active suspension of the associated subject, the suspension of the risk to the credit provider, or other suspension. + +## State flow rules +```plain + + ┌─────────────┐ + │ PENDING │ + └──────┬──────┘ + ┌───────────┼───────────┐ + ▼ ▼ ▼ + ┌────────┐ ┌──────────┐ ┌─────────┐ + │ ACTIVE │ │ REVOKED │ │ EXPIRED │ + └───┬────┘ └──────────┘ └─────────┘ + │ ▲ + │ │ + ▼ │ + ┌───────────┐ + │ SUSPENDED │ + └─────┬─────┘ + ├──────────────► REVOKED + └──────────────► EXPIRED +``` + +The permitted state flow is as follows: + ++ `PENDING → ACTIVE`: credit association application has completed the identification of the associated subject, the associated credit map and the issuance of the certificate, and the certificate is valid; ++ `PENDING → REVOKED`: credit association application withdrawn or terminated; ++ `PENDING → EXPIRED`: credit association The application exceeds the validity period but does not complete the issuance of the certificate; ++ `ACTIVE → SUSPENDED`: credit association vouchers are temporarily suspended; ++ `ACTIVE → REVOKED`: credit association vouchers have been withdrawn or replaced with new documents as a result of a material change in the associated credit information, association or other core field; ++ `ACTIVE → EXPIRED`: credit association certificate is beyond the validity period; ++ `SUSPENDED → ACTIVE`: return to effect after the reasons for the suspension have been removed; ++ `SUSPENDED → REVOKED`: Confirmation of SHALL withdrawal during suspension, or replacement of original documents with new documents; ++ `SUSPENDED → EXPIRED`: The suspension period exceeds the validity period. + +`REVOKED` and `EXPIRED` shall be final and shall not be transferred to another state. + +## Suspension and restoration +`SUSPENDED` states can be initiated by: + ++ **Associated Subject Active Pause** The associated entity can request the suspension of the credit association voucher for its own needs. ++ **Credit provider risk paused**: The credit service may notify the issuer of the certificate of credit association to suspend the certificate, on the basis of an abnormal credit statement of the related subject, an abnormal association relationship, an abnormal behaviour Agent, failure to certify the association, failure to verify the control material or other risk judgement. ++ **credit association Certificate issuer ' s performance status change** credit association The issuer of the certificate executes the suspension, reinstatement or revocation of the change of status and maintains a record of the change of status in accordance with a valid order of the credit provider or related subject. + +During `SUSPENDED`, a credit certification service provider may not produce a new pass result on the basis of the certificate. + +## Re-evaluation and replacement of vouchers +The credit provider SHALL triggers a reassessment when the associated subject ' s credit statements, the associated credit mapping rules, the supporting material, the associated role, the applicable purpose, the application of Scope or other core fields have changed that may affect the validity of the associated credit information. + +The reassessment process is as follows: + +1. The credit service provider identifies changes in the credit statements, affiliations or other relevant information of the related subject and advises the issuer of credit association to suspend the original credit association certificate; +2. Agent Linked credit statements and associated credit mapping values are regenerated by credit service providers based on changed information and applicable map rules; +3. Credit providers judge whether the reassessment results in a change in the core field in the original credit association voucher; +4. If the core field changes, SHALL generate new credit association vouchers as specified in `TSD-CRD-ASC` and quotes the associated document through a pre-certificate; +5. After the entry into force of the new document, the original document SHALL was converted to `REVOKED` status; +6. The original certificate may be restored to `ACTIVE` only if it is re-evaluated that the information on which the original document is based has not changed substantially and the original document has not exceeded the validity period. + +The reference to the associated subject ' s credit statement in credit association certificate, the associated credit map value, the map rule identifier and version, the link certificate, the associated role, the purpose of application, the application of Scope and the validity period are all core fields. + +During the reassessment period, the original certificate is in `SUSPENDED` state and the credit certification service may not produce a new `PASS` certification result on the basis of the certificate. + +## Undo +A credit provider or a credit association issuer of a certificate may revoke credit association documents at any time. + +The revocation is the irreversible act of the certificate level. After the revocation, the certificate SHALL enters the state `REVOKED` and may not be restored to the state of validity. + +After the original certificate has been withdrawn, the associated subject may re-initiate the application credit association; when re-established credit association, SHALL generate a new credit association voucher and can be quoted as having been withdrawn by reference to the previous document. + +After the revocation takes effect, the credit certification service may no longer produce a new `PASS` authentication result based on the certificate. The resulting historical certification record SHALL retains the certificate status and authentication results at the time of its creation, but the searcher SHALL be able to recognize that the document has been revoked at a later point. + +# TSD-CRD-VER: Associated credit certification +## Overview +TSD-CRD-VER (Associated Credit Assistance) provides a mechanism for credit relying parties to perform standardized verification of agentcredit association relationships and associated credit information, including certification levels, certification processes, certification requests and responses to submissions and standard cause codes. + +Validation is divided into two levels: + ++ **Association Relationship Verification:** Validate the integrity of the credit association credential's signature, the associated subject's confirmation, and the validity of its current status; ++ **Association Credit Information Validation**: Further query and verify the current validity of the associated subject's credit statements and associated credit mapping information on the basis of credit association certificate authentication. + +Credit association credential verification does not involve querying the associated subject's credit information and therefore does not require credit query authorization. Verification of associated credit information involves querying or confirming the associated subject's credit statement and SHALL obtain valid credit query authorization from the associated subject; see `TSD-CRD-AUTH` for the specific authorization rules. + +A credit-dependent party SHALL make business decisions independently of its own rules. + +## Participants and prefix +This component involves the following Participants: credit relying party, credit certification service party, credit association certificate issuer, credit service provider. + +Before entering this component, SHALL satisfies the following preconditions: + ++ credit association vouchers issued; ++ Credit-dependent parties are able to provide Agent identification to be validated and credit association vouchers or their references; ++ The credit certification service provider is able to obtain authentication material and status information from the issuer of the credit association certificate; ++ When performing the authentication of the associated credit information, the credit-dependent party has obtained a valid credit search authorization for the related subject. + +## Validation process +### Credit Association Credential Verification +Credit certification service providers SHALL perform the following: + +1. (b) Validation of the version of the request, the required fields, the marking of the request, the time of the request and the elements of protection against redundancies; +2. Validation of the identity of the party relying on credit and proof of claim; +3. Obtaining credit association certificates to verify the validity of credit association signatures issued at the outer level; +4. Validation of the inner layer signature of the associated subject under `DIRECT_SIGNATURE` confirmation; +5. Validate the Agent identifier in the credit association certificate, the associated subject identifier, the associated role, the purpose of application and the application of Scope for consistency with the present request; +6. (a) Query the certificate status query and confirm that credit association the certificate is in `ACTIVE`; +7. Validates the integrity of the associated credit map information, such as references to associated subject credit statements, associated credit map values, map rule identifiers and versions, and is consistent with the records in credit association vouchers. + +The credit association certificate certification does not require the credit certification service provider to recalculate the internal mapping model of the credit provider, nor does it require it to obtain the original content of the associated subject credit statement. + +credit association Certificates shall not return to `PASS` and shall not enter the associated credit information authentication if any critical step fails. + +### **Association Credit Information Validation** +The associated credit information verification SHALL be implemented after the certification of credit association certificates. + +1. Validation of credit query authorization is currently valid; +2. (a) To inquire of credit service providers or confirm that the related subject ' s credit statements are currently valid and have not been revoked, corrected, replaced or marked as invalid; +3. (a) Verifying that the map markings and versions recorded in credit association certificates are still identifiable and applicable; +4. Confirms that Agent associated credit statements and associated credit map values remain operational; +5. (b) The content of the response is tailored in accordance with the minimum disclosure principle and authorized data items and returns only those data items that are necessary and mandated for this validation; +6. Generates a certificate of response to the certification results and keeps a record of the certification. + +No key step shall be returned `PASS` if it fails. + +SHALL return `INCONCLUSIVE` and cannot be substituted by default when insufficient evidence is available or it is not possible to determine clearly whether the certification has been passed. + +SHALL return `REVIEW_REQUIRED` when the credit association voucher is in the process of reassessment, the associated credit information needs to be reconfirmed, or the related subject confirms that the strength does not match the strength required by the business. + +## Authentication request +The certification request contains the following fields. + +|field syntax|Existence|Annotations| +| --- | --- | --- | +|Request for identification|Required|For processing ethos and correlation of results| +|Request for text version|Required|Request for text structure version| +|Credit-dependent party identifier|Required|Credit-dependent party initiating certification| +|Mark Agent|Required|Verified Agent| +|Verification level|Required|Credit Association Credential Verification or Associated Credit Information Verification| +|Associated Subject Credit Statement Reference|Conditionally required|Associated credit information validation required| +|Operational purpose|Required|Purpose for which validation results are used| +|Operational context|Required|Minimum correlation information for order, commission, transaction or risk decisions| +|Data requested entry|Required|Pool of fields, declarations or validation conclusions expected to return| +|Certificate credit association|Required|credit association certificate to be validated or references thereto| +|Request Time|Required|Request generation time| +|Element of protection against redundancies|Required|Random number, quail etc. or equivalent| +|Proof of request|Required|Overwrite signature or equivalent certificate for requested key fields| + +## Verify Response +The validation response contains the following fields. + +|field syntax|Existence|Annotations| +| --- | --- | --- | +|Request for identification|Required|Correspond to original authentication request| +|Validation record identifier|Required|The only mark on this validation.| +|Mark Agent|Required|Verified Agent| +|Validation level completed|Required|The highest level of authentication actually completed, with a value of credit association certificate authentication or associated credit information authentication| +|Authentication Results|Required|`PASS`, `FAIL`, `INCONCLUSIVE` or `REVIEW_REQUIRED`| +|Reason code|Required|Explanation of validation results| +|Support status credit association|Required|Document 's Current Life Cycle Status| +|Associated credit source tags|Conditionally required|Linked credit information validated and returned with a value of `ASSOCIATED_CREDIT`| +|Associated Credit Map Values|Conditionally required|Linked credit information validation required for authorized return of relevant credit information| +|Validity of associated subject credit statements|Conditionally required|Revert the current validity of the related subject 's credit statement when the associated credit information is verified| +|Map rule identifier and version|Conditionally required|Linked credit information verified and required to return associated credit information| +|Application Scope|Required|This validation is allowed at Scope| +|Result generation time|Required|Validation completion time| +|Due Expiry|Required|Re-validate SHALL beyond that time| +|Status Query Information|Optional|For checking the follow-up status of credit association vouchers or validation results| +|Purpose Limiting Tags|Required|Mark the results of this validation only for specified business purposes| +|Response certificate|Required|Overwrite signature or equivalent proof for key fields| + +Response SHALL follows the minimum disclosure principle: + ++ credit association voucher validates response SHALL NOT to the original content of the associated subject ' s credit statement or associated credit map value; ++ The associated credit information authentication does not default on the return of the associated subject ' s original identity information, the original content of the related subject ' s credit statement or the internal map basis of the credit service; ++ Fields that exceed the Scope search authorization or the requested data entry Scope are cropped and not returned. + +## Standard reason code +|Reason code|Meaning| +| --- | --- | +|`VERIFIED`|The specified authentication level has been passed| +|`INVALID_REQUEST`|Invalid request structure, version or mandatory field| +|`REQUEST_PROOF_INVALID`|The request signature or equivalent proof failed verification| +|`REQUEST_EXPIRED`|Request to exceed allowed time window| +|`REPLAY_DETECTED`|Request for marking or weighting elements have been used| +|`AUTHORIZATION_REQUIRED`|Linked credit information authentication lacked valid credit search authorization| +|`AUTHORIZATION_EXPIRED`|Credit search authorization expired| +|`AUTHORIZATION_REVOKED`|Credit search authorization revoked.| +|`AUTHORIZATION_SCOPE_MISMATCH`|Credit relying party, Agent, certification level, business purpose or data item exceeding delegated authority Scope| +|`AGENT_NOT_REGISTERED`|The Agent identity cannot be resolved or verified| +|`ASSOCIATION_CREDENTIAL_NOT_FOUND`|No credit association credential was found| +|`ASSOCIATION_CREDENTIAL_NOT_ACTIVE`|credit association certificate pending confirmation, suspension, revocation or expiry| +|`ASSOCIATION_PROOF_INVALID`|The credential signature, associated subject's inner signature, or other association proof failed verification| +|`CREDIT_ASSERTION_UNAVAILABLE`|Unable to obtain associated subject credit statements or validity information for authentication of associated credit information| +|`CREDIT_ASSERTION_INVALID`|The associated subject ' s credit statements are invalid, expired, revoked, corrected or invalidated| +|`MAPPING_POLICY_UNSUPPORTED`|Unidentifiable, unsupported or unable to apply map rule identifiers and versions| +|`INCONCLUSIVE`|Insufficient evidence or necessary reliance not available for the time being| +|`REVIEW_REQUIRED`|Need for manual or higher level of assurance| + +# TSD-CRD-AUTH: Credit search authorization +## Overview +TSD-CRD-AUTH (Credit Query Assessment) is used to provide a search authorization mechanism for associated subjects for the authentication of associated credit, and only to limit the information search and authentication required for the authentication of associated credit to Scope, which does not constitute an authorization for Agent transactions, payments, performance or other commercial acts. + +When a credit relying party performs the authentication of associated credit information, the current validity of the associated subject’s credit statements and associated credit mapping information needs to be sought or confirmed by the credit service provider. The process may involve the related subject’s credit information, so SHALL obtains a valid credit search authorization from the related subject. + +## Participants and prefix +This component covers the following Participants: related subjects, credit-dependent parties, credit providers, credit-certification service providers and platform agents. + +Of which: + ++ The related subject is the authorized person for the credit search; ++ The credit relying party is the subject of a request for the use of associated credit certification results; ++ The credit provider is responsible for maintaining the credit statements of the related subject, the status of authorization or the related search capability; ++ Credit certification services are responsible for verifying authorization and producing certification results during the certification process; ++ The Agent body of the Platform is the subject of the performance or assistance in the execution of the credit query under the Platform proxy query model, with the prior authorization of the associated entity and within the limits of Scope. + +Before entering this component, SHALL satisfies the following preconditions: + ++ credit association vouchers have been issued and are in `ACTIVE` status; ++ Associated subjects can be validated and have the capacity to make authorization confirmations; ++ The credit relying party has clearly linked the business purpose of the credit certification, the requested data item and the relevant business context; ++ Under the Platform proxy query model, the Platform proxy body has been clearly identified and authorized by the associated subject. + +## Elements of a mandate +The credit search authorization SHOULD specifies the following elements: + ++ (b) Credit relying party identity: credit relying party identifier allowing requests or the use of associated credit certification results; ++ (a) Platform proxy body identity: the identification of the Platform Agent who is allowed to perform the query or confirmation on behalf of the Platform Agent when using the Platform proxy query model; ++ agentScope: allowed to be marked Agent or Agent Scope; ++ Level of certification: the level of certification to which this authorization applies and the default is the authentication of the relevant credit information; ++ Business purpose: the business purpose for which the results of the associated credit validation are permitted; ++ Data requested: fields, declarations or a collection of validated conclusions that allow search, validation or return; ++ Duration: the time of validity and expiry of the credit search authorization; ++ Frequency limit: the maximum frequency allowed to perform a query or validation during the validity of the authorization; necessary under the Platform proxy query model; ++ Limitations on the use of results: Validation of the result to allow preservation, duration of storage, transmission to other subjects and other necessary limitations. + +The credit query authorization SHALL be clearly linked to the related subject, Agent, the level of certification, the purpose of the business and the requested data item and may not be reused beyond the subject, Agent, purpose or data item of the authorization Scope. + +## Delegation of authority model +Credit query authorization is divided into sub-authorizations and platform proxy queries. Both models meet the requirements of authorization SHALL to be clear, authorization is verifiable, results are restricted and authorization can be revoked. + +### Sub-authorizations +Under the sub-authorization model, each time a credit-dependent party initiates a request for the authentication of a related credit information, the credit-servicing party or the credit-certification service party SHALL notifys the related subject of a sequential confirmation. + +The delegation of authority and associated credit information validation was completed in the same interaction and the process was as follows: + +1. (b) The initiation by credit-dependent parties of requests for the authentication of related credit information; +2. (b) The credit provider or the credit certification service provider notifys the related subject for authorization confirmation; +3. The associated entity identifies the credit-dependent party, Agent, the business purpose, the requested data item and the time of validity of the inquiry; +4. Credit certification services perform the authentication of associated credit information and return the certification results. + +Sub-delegation applies to situations where ad hoc inquiries, high-sensitive inquiries or related subjects need to be informed on a case-by-case basis. + +The authorization shall not be diverted to other credit-dependent parties, other Agent, other business purposes, other requests or other authentication scenes. + +### Platform Agent Query +In the Platform proxy query mode, the associated entity pre-authorizes the designation of the Agent of the Platform to perform or assist in the performance of the associated credit query on behalf of Scope and within a limited period of time. + +The associated subject SHALL explicitly authorizes the following: + ++ (a) Acting body of the Platform; ++ Verifiable agentScope; ++ Validation level, default for associated credit information authentication; ++ Credit-dependent parties or permitted credit-dependent parties Scope; ++ Operational purpose; ++ Data items requested; ++ Frequency limits; ++ (a) Duration; ++ Restrictions on the use of validation results. + +The frequency limit SHALL be expressed in machine-readable measurements such as `max_requests_per_window` and `window_duration` to avoid any ambiguity as to whether the number or frequency of queries exceeds the authorized Scope. + +Each time a Platform Agent executes or assists in carrying out a query, SHALL carries the operational context and validates the identity of the Platform Agent, the status of the authority, the authority Scope and the consistency of the request. + +A Platform Agent may no longer perform a new valid associated credit information authentication based on the associated entity’s withdrawal of the authorization. A Platform Agent may not use search capabilities, validation results or authorization to quote scenes other than those used for the purpose of the authorization, or transfer authorization to an unauthorized third party or provide information beyond the authorization Scope. + +## Processing of requests +Credit queries are authorized to process SHALL the following requirements: + ++ The credit provider or credit certification service SHALL maintain the authorized status and verifies that the authorization is currently valid and covers the current certification request at each time the relevant credit information is validated; ++ SHALL Identify the Agent of the Platform, the credit-dependent party Scope, Agent Scope, the business purpose, the requested data item, frequency limits, the validity period and the limitations on the use of the results; the Agent of the Platform SHALL verify that the request is not in excess of the authorization Scope at each query or validation; ++ The credit provider SHALL return only the associated credit information in the authorized Scope and necessary to satisfy the purpose of the business, in accordance with the minimum disclosure principle; ++ Credit relying parties, credit providers, credit certification service providers and Platform agents shall not use the results of the certification for scenarios other than the authorized purposes or disclose information beyond the authorized Scope to an unauthorized third party. diff --git a/docs/specification/trust-services.md b/docs/specification/trust-services.md index b10d369..9eb2567 100644 --- a/docs/specification/trust-services.md +++ b/docs/specification/trust-services.md @@ -2,226 +2,1014 @@ 中文 | [English](trust-services.en.md) -> **状态：ACT 2.1 Specification / Final / Normative** -> **协议内容已经定稿；是否符合本规范需要独立 Conformance 证据。** -> **版本基线：2026-08-11（UTC+8）。** +# 第一篇：可信存证 -信任服务域（Trust Services Domain，TSD）为 ACT 的跨域事实提供可验证、可追溯和可复核的信任支撑，包含两个并列子篇：可信存证（Trusted Attestation）与信用关联（Credit Association）。 +# 范围 +## 本子篇定位 +可信存证（Trusted Attestation）是信任服务域的子篇之一。本子篇规定 ACT 协议中关键业务事件的统一存证、引用与验证规则，为授权、商业交互、支付执行和履约相关事实提供可追溯、可校验、可复核的信任基础。 -本域是 ACT 2.1 的规范性信任服务域文本。ACT 2.1 Release 中的本文是 2.1 版本化文本；[ACT Protocol 信任服务域网页](https://www.act-protocol.com/documentation/trust)是未版本化的信息性参考。 +## 本子篇范围与边界 +本子篇覆盖以下内容： -## 1. 子篇关系与边界 ++ 存证事件类型及其标识规则； ++ 存证事件的标准载荷结构与最小必填要素； ++ 存证事件的提交、签名、锚定引用和状态表示规则； ++ 存证结果的查询、验证与争议处理所需的基础校验规则； ++ 跨域事件引用关系及其一致性要求； ++ 本子篇规定以 ACT Trust Chain 作为链上锚定基础设施，用于承载关键业务事件的摘要锚点，并支持跨机构场景下的不可篡改校验。 -| 子篇 | 解决的问题 | 组件 | -|---|---|---| -| 可信存证 | 关键业务事件如何形成链下证据、链上锚点、核验结果和争议处理链路 | `TSD-ATT-EVT`、`TSD-ATT-OFF`、`TSD-ATT-OCA`、`TSD-ATT-SVF`、`TSD-ATT-DSP` | -| 信用关联 | Agent 自身信用不足时，如何在受限范围内引用关联主体信用，并确保来源、授权和状态可验证 | `TSD-CRD-ASC`、`TSD-CRD-MAP`、`TSD-CRD-LCM`、`TSD-CRD-VER`、`TSD-CRD-AUTH` | +本子篇不规范以下内容： -可信存证只是信任服务域的子篇之一，不等同于整个 TSD。信用关联子篇规定关联主体、凭证/声明/映射值、查询授权模式、`ASSOCIATED_CREDIT` 来源标记、确认方式和责任边界。 ++ 具体底层账本、区块链、时间戳服务、数据库或第三方存证基础设施的内部实现； ++ 各参与方内部审计平台、法务处理系统和业务运营系统实现。 -可信存证不规定底层区块链、时间戳服务、数据库或第三方存证设施的内部实现。信用关联不规定信用评分模型、授信规则、支付风险决策、跨机构换算规则或 Agent 独立信用/声誉机制。任何产品日志、支付回执或信用结果都不会仅因存在而自动成为符合 TSD 的协议对象。 +## 1.3 可信存证价值说明 +本子篇采用“链下完整记录 + 链上摘要锚定”的双层存证架构：链下保留完整业务事件明文与签名材料，链上仅写入防篡改摘要锚点，以同时满足业务可核验性、隐私保护与跨机构信任需求。 -# 第一篇：可信存证 +这一设计的核心目标，不是将原始业务数据集中交由第三方保存，而是在各方尽量自主保管原始数据的前提下，建立一套最小必要且可被共同验证的信任基础。当争议、审计或合规核查发生时，相关参与方再按照需求出示本方保留的原始记录，并与链上已预先锚定的摘要进行一致性比对，从而证明记录在事后未被篡改。 + +由于链上仅保存轻量化摘要而不保存全量业务明文，本子篇能够在控制存储成本、减少敏感信息外溢风险的同时，保留跨机构验证所需的关键证明能力。同时，链上锚点由多方共识维护，不依赖任何单一平台或单一参与方的日志背书，因此相较于单点日志系统更具中立性与公信力。基于这一机制，可信存证不仅服务于历史留痕，更是后续签名核验、因果链追溯和争议处理得以成立的共同基础。 + +# 本子篇组件列表与关系 +## 组件总览 +可信存证子篇由五个协议组件构成，它们共同完成从关键业务事件定义、链下存证记录生成、链上摘要锚定，到事后核验与争议处理支持的完整链路。 + +各组件的功能定位如下。 + ++ **TSD-ATT-EVT：存证事件类型定义。** 负责定义 ACT 业务全链路中可以纳入可信存证的关键事件类型及其标准语义，作为本子篇后续存证处理的统一入口。 ++ **TSD-ATT-OFF：链下存证记录。** 负责规范参与方在本地生成、保存和管理完整存证记录的要求，使关键业务事件能够形成可追溯、可核验的一手证据载体。 ++ **TSD-ATT-OCA：链上存证锚点。** 负责规范从链下存证记录中提取最小必要摘要信息并写入 ACT Trust Chain 的要求，以形成不可篡改的链上时间锚点和跨机构验证依据。 ++ **TSD-ATT-SVF：签名核验流程。** 负责规范在争议处理、审计或合规核查场景下，对链下记录、签名材料和链上锚点执行一致性核验的标准步骤。 ++ **TSD-ATT-DSP：争议处理流程。** 负责规范各参与方基于链下存证记录、链上锚点及核验结论开展举证、核验和处理的流程框架。 + +## 核心对象与标识 +为保持本子篇内部处理以及与其他域之间引用关系的一致性，本子篇使用一组标准核心对象和标识来描述可信存证链路中的关键信息。本子篇核心对象及其作用可概括如下。 + +| **对象或标识** | **含义** | **主要产生位置** | **主要使用位置** | +| --- | --- | --- | --- | +| 存证事件 | 对 ACT 全链路关键业务节点的标准化事件表达，用于明确“什么事情可被存证”以及该事件的统一语义 | TSD-ATT-EVT | TSD-ATT-OFF、TSD-ATT-OCA，以及其他域在引用存证事件标识时的相关处理环节 | +| 存证记录唯一标识 | 用于唯一标识一条链下存证记录，并作为链下记录与链上锚点之间稳定绑定的主键 | TSD-ATT-OFF | TSD-ATT-OCA、TSD-ATT-SVF、TSD-ATT-DSP | +| 链下存证记录 | 由参与方按统一要求生成并本地保存的完整事件记录，通常承载事件内容、参与方信息、摘要值及签名材料，是争议处理时的一手证据对象 | TSD-ATT-OFF | TSD-ATT-OCA、TSD-ATT-SVF、TSD-ATT-DSP | +| 链上存证锚点 | 从链下存证记录提取的轻量化摘要凭证，用于在 ACT Trust Chain 上形成不可篡改的锚定记录 | TSD-ATT-OCA | TSD-ATT-SVF、TSD-ATT-DSP，以及跨机构核验场景 | +| 核验结论 | 对链下记录、签名材料和链上锚点执行一致性校验后形成的标准结果，用于判断记录是否完整、真实且未被篡改 | TSD-ATT-SVF | TSD-ATT-DSP，以及审计、合规核查等后续处理环节 | +| 争议处理请求 | 争议方围绕特定交易链路发起的举证或处理请求，通常关联具体业务事件、交易标识及争议说明 | TSD-ATT-DSP | TSD-ATT-DSP 及相关仲裁、核验处理环节 | + +## 依赖与跨域引用 +TSD-ATT-EVT 是本子篇的逻辑起点，用于定义哪些关键业务节点可以被纳入可信存证以及这些事件的统一语义。 + +TSD-ATT-OFF 依据 TSD-ATT-EVT 所定义的事件类型生成链下存证记录，并形成后续链上锚定和事后核验所依赖的主体证据对象。 + +TSD-ATT-OCA 进一步引用链下存证记录中的核心摘要信息，完成链上锚定，从而为链下记录提供跨机构可验证的防篡改依据。 + +TSD-ATT-SVF 同时依赖链下存证记录和链上存证锚点执行一致性校验，以形成标准化核验结论。 + +TSD-ATT-DSP 则以链下记录、链上锚点及核验结论为重要依据，组织争议场景下的举证、核验和处理流程。 + +上述关系共同构成“事件定义—链下留痕—链上锚定—事后核验—争议处理”的闭环链路。 + +可信存证子篇统一维护存证事件类型注册表；委托授权域、商业交互域和支付服务域仅在相关组件中引用事件标识符，不在各自域内重复定义事件结构或存证治理规则。 + +在跨域串联上，本子篇主要通过 `intent_id`、`delegation_id`、商户侧订单交易号、支付交易流水号和存证记录唯一标识等对象，建立从授权、交易确认、支付执行到争议处理的全链路证据关联关系。 + +# TSD-ATT-EVT：存证事件类型定义 +## 概述 +TSD-ATT-EVT（Attestation Event） 用于定义 ACT 可信存证体系中的标准存证事件类型，统一委托授权域、商业交互域和支付服务域在关键业务节点上的事件标识与基础语义。 +本组件在体系中承担全局事件类型注册表的作用，凡纳入可信存证范围的关键事件，应在本组件中统一登记和引用。 + +本组件仅定义可被存证的关键事件类型，不定义各业务域内部的临时状态、实现步骤或厂商私有中间事件。后续如新增需统一存证的关键业务节点，应继续沿用本组件的命名方式和注册方式扩展事件类型。 + +当前协议仅规定标准存证事件类型及其基础触发语义，不规定各事件的完整 `event_body` 结构、字段级校验规则、签名封装方式或链上锚定格式。 + +## 参与方及前置条件 +TSD-ATT-EVT 的参与方包括委托授权域、商业交互域和支付服务域中产生关键业务事件的相关参与方，以及负责维护存证事件类型注册信息的管理方。 + +进入本组件前，应满足以下前置条件。 + ++ 相关业务域应已明确本子篇可纳入可信存证范围的关键业务节点及其完成条件。 ++ 相关参与方应能够提供稳定的业务关联标识，以支持链下记录、链上锚点和争议处理过程中的跨域串联。 ++ 前述关联标识宜至少包括 `intent_id`，并可根据具体场景进一步包括 `delegation_id` 及各业务域交易标识。 + +## 基本要求 +本组件中的标准事件类型命名空间采用 `act::` 形式，其中 `domain` 表示事件所属业务域，`event` 表示该域内的具体关键业务事件。 + +标准事件类型应具备稳定、可枚举、可跨域引用的特性，不应因单一实现差异改变其基础语义。同一业务事件可由不同参与方分别进行存证，但相关参与方在引用时应使用同一标准事件标识，并保持一致的触发语义理解。 + +存证事件的上报宜在业务事件完成后异步进行，不宜占用业务主流程路径，也不宜影响在线交易处理时延。 + +## 标准事件类型 +当前版本纳入 TSD-ATT-EVT 的标准事件类型如下。 + +| 事件类型标识 | 所属域 | 触发时机 | +| --- | --- | --- | +| `act:delegation:intent-created`
| ADD | 用户意图完成确认并形成可用于后续授权处理的意图结果时触发 | +| `act:delegation:delegation-issued`
| ADD | 意图授权凭证签发完成并进入 Active 状态时触发 | +| `act:delegation:delegation-suspended`
| ADD | 意图授权凭证被挂起时触发 | +| `act:delegation:delegation-resumed`
| ADD | 意图授权凭证由 Suspended 状态恢复为 Active 状态时触发 | +| `act:delegation:delegation-revoked`
| ADD | 意图授权凭证被吊销时触发 | +| `act:delegation:delegation-expired`
| ADD | 意图授权凭证到期失效时触发 | +| `act:commerce:decision-logged`
| CID | 买方智能体完成候选比较或决策留痕时触发 | +| `act:commerce:cart-confirmed`
| CID | 购物车确认完成并进入可发起支付的交易确认状态时触发 | +| `act:payment:transaction-completed`
| PSD | 支付交易完成并形成支付结果时触发 | +| `act:commerce:fulfillment-completed`
| CID | 商户侧订单履约完成时触发 | + +上述事件构成当前版本可信存证的标准事件集合，覆盖授权形成与状态变化、商业确认、履约完成和支付完成等关键节点。后续可按业务需要扩展事件类型。 + +# TSD-ATT-OFF：链下存证记录 +## 概述 +TSD-ATT-OFF（Offline Attestation Record）用于规定 ACT 可信存证体系中链下存证记录的标准结构、生成方式、保存要求与跨域串联规则，是各参与方对关键业务事件进行本地可信留痕的基础组件。 + +本组件承载需被证明的业务事件明文、参与方身份、链路关联标识、负载哈希与数字签名等内容，用于在不将业务明文上链的前提下，为后续链上锚定、签名核验和争议处理提供可验证的原始依据。 + +## 参与方及前置条件 +TSD-ATT-OFF 的参与方包括在委托授权域、商业交互域和支付服务域中产生关键业务事件并承担存证责任的相关参与方，以及可受托提供记录保存或查询服务的存证服务提供方。 + +进入本组件前，应满足以下前置条件。 + ++ 相关业务事件应已达到 TSD-ATT-EVT 中对应标准事件类型的触发条件，且事件发起方或记录生成方应能够取得稳定的业务关联标识，至少包括 `intent_id`，并可按场景进一步包括 `delegation_id`、商户侧订单交易号和支付交易流水号。 ++ 记录生成方在创建链下存证记录前，还应具备可用的签名私钥、可解析的身份标识、公认的时间表示方式，以及符合要求的本地安全存储能力或受托存储安排。 + +## 基本要求 +链下存证记录应以结构化数据模型生成，并应能够被后续的负载哈希计算、数字签名、链上锚定和核验流程稳定解析，因此记录一经生成不得进行无版本号的结构性变更。 + +链下存证记录应坚持“业务先完成、存证后异步上报”的原则，业务事件实际发生时间与存证记录创建时间应分别记录，以明确业务完成时点与存证落盘时点之间的差异。 + +链下存证记录应支持跨域串联、隐私保护、防篡改和可追责四项能力，即能够还原链路、避免敏感明文外泄、通过哈希和签名发现事后修改，并明确由谁对记录真实性负责。 + +## 链下存证记录结构 +链下存证记录由六个部分构成：基础元数据、全链路串联与溯源标识、隐私与防推断要素、参与方列表、事件载荷 `event_body`、数字签名；实现方可在不破坏兼容性的前提下增加扩展字段。 + +除扩展字段外，各部分中的核心字段应具有稳定语义，并应与 TSD-ATT-EVT、TSD-ATT-OCA、TSD-ATT-SVF 的相关字段保持一致命名或一一映射关系，以避免链下、链上和核验阶段出现字段歧义。 + +### 基础元数据 +基础元数据用于标识“这条记录是什么、属于哪个版本、业务何时发生、记录何时生成”，是每条记录的唯一身份证明，确保存证记录可被精确定位和跨版本解析。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 存证记录唯一标识 | 必备 | 由记录生成方在创建时赋值，一经生成不应更改 | +| 事件类型标识 | 必备 | 应为 TSD-ATT-EVT 中已注册的枚举值 | +| 业务事件时间 | 必备 | 业务事件实际发生时间（非存证记录创建时间），由发起方在事件完成时记录 | +| 存证记录创建时间 | 必备 | 存证记录创建时间，可晚于业务事件时间，体现异步上报 | +| 存证记录结构版本号 | 必备 | 供未来版本兼容处理 | + +记录生成方应分别记录业务事件时间和存证记录创建时间，不得以单一时间字段同时表达两者含义。业务事件时间和存证记录创建时间均宜采用 ISO 8601 UTC 格式表达，以便后续链上锚定、核验和争议处理保持一致。 + +### 全链路串联与溯源标识 +全链路串联与溯源标识用于记录“这件事属于哪条业务链路”，将分散在不同参与方、不同时间点产生的孤立存证记录串联为一条完整的端到端因果证据链，确保争议时能够还原完整交易全貌。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 意图标识 | 必备 | 全局业务流程主键，同一业务流程所有存证记录应携带相同意图标识 | +| 委托标识 | 条件必备 | 委托支付场景中应携带 | +| 商户侧订单交易号 | 条件必备 | 购物车确认之后的事件应携带 | +| 支付交易流水号 | 条件必备 | 支付执行之后的事件应携带，与 PSP 返回值一致 | +| 上游存证记录引用 | 可选 | 指向上游关联事件的存证记录唯一标识；当存在明确上游事件时宜携带，可用于构建端到端因果证据链 | + +意图标识（`intent_id`）应作为跨 ADD、CID、PSD、TSD 的全局主串联键使用，其他标识符则作为不同业务阶段的辅助串联键。 +当当前事件与上游关键事件之间具有明确因果关系时，记录生成方宜填写上游存证记录引用，以支持 TSD-ATT-SVF 在必要时执行递归式上游链路核验。 + +### 隐私与防推断要素 +隐私与防推断要素用于解决“如何在不暴露明文的前提下保证记录不可篡改”，并通过引入随机盐值使每条记录的摘要值唯一且不可预测，以降低通过已知业务数据反推存证内容的风险。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 随机盐值 | 必备 | 每条存证记录宜包含一个独立的高熵随机盐值，原始长度不低于 128 位，使用密码学安全随机数生成器生成。 | +| 负载哈希值 | 必备 | 对事件载荷与参与方列表按规范化方式处理后，并结合随机盐值计算得到的密码学摘要值；宜以 Base64url 编码保存。 | +| 哈希算法标识 | 必备 | 当前版本可支持 SHA-256 或 SM3；如后续版本支持其他算法，应通过该字段显式声明。 | + +负载哈希计算步骤如下。 + ++ 将事件载荷与参与方列表字段按 RFC 8785 JSON 规范化方案（JCS）处理为规范字节序列。 ++ 将规范字节序列与随机盐值原始字节拼接，拼接顺序为“规范字节序列 ∥ 盐值字节”。 ++ 对拼接结果执行 SHA-256 或 SM3 计算。 ++ 将计算结果以 Base64url 编码存储为负载哈希值。 + +记录生成方应确保每条链下存证记录使用独立随机盐值，不应在多条记录间复用同一盐值。 +当事件载荷内容完全相同但随机盐值不同，重新计算出的负载哈希值也应不同，这一特性是本组件防推断设计的一部分。 + +### 参与方列表 +参与方列表记录本次业务事件中涉及的各方主体身份，明确“谁参与了这件事、以什么角色参与”，以便争议发生时责任归属清晰可查。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 参与方标识 | 必备 | 谁存证了这次事件 | +| 参与方角色 | 必备 | 以什么身份存证了这次事件；枚举值可包括：付款方智能体、收款方智能体、商户、支付服务方、委托人智能体、存证服务提供方 | +| 被代理方标识 | 可选 | 当该参与方是代理其他实体行事（例如平台型智能体代表某位具体用户完成操作）时，记录被代理方的标识 | + +每条存证记录的参与方列表应包含至少一个角色，以确保每条记录都有明确的责任发起方可被追溯。角色枚举可包括付款方智能体、收款方智能体、商户、支付服务方、委托人智能体、存证服务提供方等受协议识别的参与角色。 + +当存在多方联合存证时，参与方列表可包含多个参与方条目，但其角色含义应保持清晰且不可重复歧义。 + +参与方标识应能够与本体系身份机制或外部受信身份机制对应解析，从而支撑后续签名公钥获取和责任归属判断。 + +### 事件载荷 +事件载荷（`event_body` ）承载“这件事具体发生了什么”，是链下存证记录中保存当前业务节点关键明文与业务要素的核心部分，也是争议处理时核对交易细节的直接依据。 + +事件载荷的字段集合由事件类型决定，本组件仅定义该部分在链下存证记录中的位置、存在性与隐私约束，不在本节穷举不同事件类型的全部专属字段。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 事件载荷 | 必备 | 承载当前关键业务事件的业务明文与必要业务要素，其字段由事件类型动态决定 | +| 预留扩展字段 | 可选 | 用于承载不影响核心可验证性的补充信息；不宜包含高敏感个人信息或原始支付账号等敏感数据 | + +事件载荷不应包含以下敏感信息：委托人完整身份信息，如真实姓名、证件号、联系方式等个人身份信息，以及原始支付账号，如银行卡号、支付账户号等。 + +事件载荷可包含金额、货币、商品快照摘要、时间戳等非敏感业务要素；对于因隐私要求无法明文记录的字段，宜以对应字段的哈希摘要替代，并在字段语义命名中以“摘要”或“哈希”后缀加以标识。 + +### 数字签名 +数字签名用于回答“谁对这条记录的真实性负责”，通过密码学签名将参与方身份与记录内容绑定，确保任何事后篡改均可被发现，并为链下存证记录提供不可抵赖的证据基础。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 签名方标识 | 必备 | 格式同参与方标识 | +| 签名算法标识 | 必备 | 须为本协议支持的签名算法枚举值 | +| 签名值 | 必备 | Base64url 编码 | +| 签名覆盖范围说明 | 必备 | 覆盖：事件载荷、参与方列表、随机盐值、存证记录唯一标识、业务事件时间五个字段 | + +每条存证记录应至少包含一个由存证记录发起方生成的签名，其他参与方可附加联合签名以增强证据效力。 + +签名方公钥宜从其身份标识对应的身份文档或受信注册信息中获取，以支撑后续 TSD-ATT-SVF 的验签流程。 + +## 负载哈希计算要求 +为避免不同实现因 JSON 序列化差异而产生不一致摘要，记录生成方在计算负载哈希和执行数字签名时，应对相关对象使用 RFC 8785 JCS 进行规范化处理。 + +负载哈希的最小输入集合应包括 `event_body` 与参与方列表，且应与本条记录所携带的独立随机盐共同参与运算，以保证链下记录与链上锚点之间的唯一绑定关系和防重放特性。 + +同一条记录在不变更业务内容、参与方列表和盐值的前提下，重复计算负载哈希应得到完全一致的结果，否则视为实现不符合本组件要求。 + +## 存储与保留要求 +链下存证记录可由各参与方自主存储，也可委托存证服务提供方代为存储，但无论由谁保存，记录内容的真实性责任仍由记录发起方或签名方承担，存证服务提供方不因代存而取得修改原始记录的权限。 + +链下存证记录宜按适用法律法规、争议处理周期和业务风险暴露期设置保留期限，且在保留期内应保证记录可检索、可导出、可校验，并具备防删除、防覆盖和备份恢复能力。 + +当协议版本升级时，已生成记录的结构和可验证内容不应被回写变更，解析方应依据记录中的结构版本号选择相应的解析逻辑，以保证历史证据长期有效。 + +# TSD-ATT-OCA：链上存证锚点 +## 概述 +TSD-ATT-OCA（On-Chain Attestation Anchor）用于规定 ACT 可信存证体系中链上存证锚点的标准结构、提交要求与链上写入规则，是链下存证记录进入 ACT Trust Chain 的标准承接组件。链上存证锚点是基于链下存证记录提取的轻量化元数据凭证，链上不存放全量业务明文，而是承载最小必要索引、摘要哈希和签名相关信息，以在多方共识账本上提供不可篡改的跨机构可验证证明。 + +链上存证锚点通过负载哈希与对应链下存证记录唯一绑定，任何对链下原文的单方面修改，都会导致重新计算的哈希值与链上锚点不一致，从而无法通过后续核验。 + +## 参与方及前置条件 +TSD-ATT-OCA 的参与方包括负责生成并提交链上锚点的各域参与方、可受托代为提交锚点的存证服务提供方，以及负责承载锚点写入与查询能力的 ACT Trust Chain 节点运营机构。 + +进入本组件前，应满足以下前置条件。 + ++ 相关业务事件应已在 TSD-ATT-EVT 中完成标准事件类型判定，且其对应链下存证记录应已依 TSD-ATT-OFF 要求生成完成，并具备存证记录唯一标识、事件类型标识、业务事件时间、意图标识及负载哈希值等基础字段。 ++ 若由存证服务提供方代为提交链上锚点，存证服务提供方仅承担代提交或代查询职责，不因代办写入而取得对链下原始记录内容的修改权或真实性背书权。 + +## 基本要求 +链上存证锚点应遵循“链下保存完整明文、链上保存最小必要摘要”的设计原则，以在保护商业隐私和控制链上存储成本的同时，保证跨机构可验证性。 + +链上锚点应能够与对应链下存证记录建立稳定的一一映射关系，其中存证记录唯一标识用于记录级绑定，负载哈希值用于内容级绑定，二者共同支撑后续的链上链下一致性核验。 + +链上锚点宜在业务事件完成并生成链下存证记录后异步提交，不应阻塞原有业务主流程，也不宜影响在线交易处理时延。 + +链上锚点应作为可信证明索引而非完整证据本体，发生争议或审计时，仍应以链下存证记录作为原始证据来源，再结合链上锚点完成完整性和不可篡改性验证。 + +## 存证锚点结构 +链上存证锚点采用两层数据模型，即基础字段层与扩展字段层，其中基础字段层为所有锚点应具备的核心要素，扩展字段层用于适配特定部署场景的附加属性。 + +锚点宜采用 JWS Compact Serialization 形式封装后写入 ACT Trust Chain，封装后的头部应包含签名算法标识与签名密钥引用标识，载荷部分则承载本组件定义的锚点字段。 + +### 头部要求 +JWS 头部应至少包含签名算法标识与签名密钥引用标识，以支持链上锚点来源身份识别和后续验签处理。 + +头部字段的具体命名和编码方式可由实现层在兼容 JWS Compact Serialization 的前提下确定，但不应影响锚点载荷的稳定解析和跨机构互认。 + +### 载荷字段 +JWT 载荷包含以下字段。 + +| **字段语义** | **存在性** | **说明** | +| --- | --- | --- | +| 存证记录唯一标识 | 必备 | 与链下存证记录的唯一标识严格一致，实现两者的唯一绑定 | +| 协议版本号 | 必备 | 存证记录结构版本号 | +| 事件类型标识 | 必备 | 应为 TSD-ATT-EVT 中已注册的枚举值 | +| 业务事件时间 | 必备 | 与链下存证记录的业务事件时间一致，宜采用 ISO 8601 UTC 表达 | +| JWT 签发时间 | 必备 | 本锚点提交至链上的时间 | +| 意图标识 | 必备 | 全局业务流程追踪标识 | +| 委托标识 | 条件必备 | 委托支付场景中应携带 | +| 商户侧订单交易号 | 条件必备 | 购物车确认之后的事件应携带 | +| 支付交易流水号 | 条件必备 | 支付类事件应携带 | +| 提交方身份标识 | 必备 | 提交本锚点的参与方身份标识 | +| 负载哈希值 | 必备 | 与链下存证记录中负载哈希值完全一致，宜采用 Base64url 编码，是两者唯一绑定的密码学依据 | +| 哈希算法标识 | 必备 | 当前版本可支持 SHA-256 或 SM3，并应与链下记录中的哈希算法声明保持一致 | +| 隐私通道标识 | 必备 | ACT Trust Chain 的隐私通道标识，用于多方数据隔离 | +| 预留扩展字段 | 可选 | 用于适配特定场景的附加属性，不宜包含业务明文或个人身份信息 | + +## 结构映射要求 +链上锚点中的存证记录唯一标识、协议版本号、事件类型标识、业务事件时间、意图标识、委托标识、订单交易号、支付交易流水号和负载哈希值，应与对应链下存证记录中的相关字段保持一致或可一一映射。 + +提交方身份标识用于标识“是谁将该锚点提交到链上”，而不当然等同于链下存证记录中的全部参与方集合，因此在发生争议时仍应回溯链下记录中的参与方列表和数字签名信息进行完整核验。 + +扩展字段的引入不应破坏基础字段层的稳定语义，也不应导致不同机构对同一锚点的核心可验证内容产生不同解释。 -## 2. 架构与跨域关系 +## 技术要求 +ACT Trust Chain 节点运营机构宜提供标准链上锚点写入接口，用于接受以 JWS Compact Serialization 形式封装的锚点提交请求，并返回可用于后续查询和核验的链上受理结果。 -可信存证采用“链下完整记录 + 链上摘要锚定”的双层架构：链下由参与方保留事件明文与签名材料；链上只写入最小必要摘要和索引，不保存完整业务明文。链上锚点用于证明摘要已被预先锚定，不取代链下原始证据。 +相同存证记录唯一标识的锚点请求应视为幂等操作，节点应拒绝重复提交，并在响应中返回已存在锚点的区块高度或等效链上定位信息，以防止同一事件被重复锚定。 -信任服务域统一维护存证事件类型注册表；ADD、CID 和 PSD 只引用事件标识，不重复定义事件结构或存证治理。跨域证据链主要使用 `intent_id`、`delegation_id`、商户侧订单交易号、支付交易流水号和存证记录唯一标识串联。 +链上数据结构不宜存放业务明文、敏感个人信息或原始支付账号等高敏感要素，宜仅包含脱敏哈希、匿名化索引及不包含敏感内容的扩展位，以延续本体系“链下明文、链上摘要”的隐私保护原则。 -存证应在业务事件完成后异步进行，不宜阻塞交易主流程或影响在线支付时延。 +当链下记录的哈希算法、版本号或关联标识发生协议级扩展时，链上锚点实现应保持对既有版本的兼容解析能力，不应因新版本上线而破坏历史锚点的可验证性。 -## 3. `TSD-ATT-EVT`：事件类型注册 +链上锚点一经写入，不应被覆盖式修改；如后续因业务补充需要新增关联信息，宜通过新增链上记录或扩展字段的兼容方式实现，而不应回写既有核心锚点内容。 -事件命名空间采用 `act::`。当前标准集合是： +# TSD-ATT-SVF：签名核验流程 +## 概述 +TSD-ATT-SVF（Signature Verification Flow）用于规定 ACT 可信存证体系中对已存证事件记录进行事后密码学核验的标准步骤，供各参与方在争议处理、合规审计和跨机构核验场景中统一调用。 +本组件用于验证链下存证记录的完整性、签名有效性以及链上链下一致性，从而判断某条存证记录是否可被认定为未经篡改且可归责的可信证据。 -| 事件标识 | 触发语义 | -|---|---| -| `act:delegation:intent-created` | 用户确认意图并形成可供授权处理的结果 | -| `act:delegation:delegation-issued` | IAC 签发并进入 `Active` | -| `act:delegation:delegation-suspended` | IAC 被暂停 | -| `act:delegation:delegation-resumed` | IAC 从暂停恢复为有效 | -| `act:delegation:delegation-revoked` | IAC 被吊销 | -| `act:delegation:delegation-expired` | IAC 到期 | -| `act:commerce:decision-logged` | 买方 Agent 完成候选比较或决策留痕 | -| `act:commerce:cart-confirmed` | 交易确认完成并可进入支付 | -| `act:payment:transaction-completed` | 支付完成并形成支付结果 | -| `act:commerce:fulfillment-completed` | 商户订单履约完成 | +## 参与方及前置条件 +TSD-ATT-SVF 的参与方包括发起核验的业务参与方、负责提供链下存证记录的记录持有方、提供代存或代查服务的存证服务提供方，以及提供链上锚点查询能力的 ACT Trust Chain 节点运营机构。 -本组件当前只冻结事件标识和基础触发语义，不规定每类事件的完整 `event_body`、字段级校验、签名封装或链上格式。 +进入本组件前，应满足以下前置条件。 -## 4. `TSD-ATT-OFF`：链下存证记录 ++ 核验发起方应能够取得待核验的链下存证记录全文，或至少取得其存证记录唯一标识并通过本地存储或存证服务提供方查询接口获取对应完整记录。 ++ 核验发起方还应能够获取签名方身份标识对应的当前有效公钥或历史有效公钥，并具备查询链上锚点的能力，否则无法完成完整核验闭环。 -### 4.1 记录组成 +## 基本要求 +签名核验应遵循“先链下、后链上，先摘要、后验签，先当前记录、后上游链路”的顺序化核验思路，以避免在基础一致性未确认的情况下直接进入更高成本或更复杂的后续核验步骤。 -链下记录由六部分构成：基础元数据、全链路串联与溯源标识、隐私与防推断要素、参与方列表、`event_body`、数字签名。 +核验过程中重新计算负载哈希时，应使用与 TSD-ATT-OFF 一致的规范化规则，即对事件载荷与参与方列表按 RFC 8785 JCS 进行规范化处理后，再按既定算法重新计算摘要值。 -| 部分 | 最小语义 | -|---|---| -| 基础元数据 | 存证记录唯一标识、事件类型、业务事件时间、记录创建时间、结构版本 | -| 链路标识 | 必备 `intent_id`；委托场景条件必备 `delegation_id`；确认后条件必备商户订单号；支付后条件必备支付交易号；可选上游记录引用 | -| 隐私与摘要 | 每条记录独立高熵随机盐、负载哈希、哈希算法标识 | -| 参与方列表 | 至少一个参与方标识和角色；代理行事时可记录被代理方 | -| `event_body` | 当前事件的必要业务明文或经隐私处理的业务要素 | -| 数字签名 | 签名方、算法、Base64url 签名值和签名覆盖范围 | +任一步骤若已得到足以否定记录可信性的明确失败结论，核验流程可终止并返回对应错误码，而不必继续执行后续步骤。 -业务事件时间和记录创建时间必须分开记录，宜使用 ISO 8601 UTC。记录一经生成不得无版本号地结构性改变。 +若仅因外部依赖不可用而无法完成核验，例如链上查询超时或当前有效公钥无法获取，则应返回“暂不可得结论”或“公钥不可用”类结果，而不应将其误判为记录已被篡改。 -### 4.2 隐私、哈希和签名 +## 核验步骤 +### 第一步：取回链下存证记录 +核验发起方应根据存证记录唯一标识从链下存储中取回完整存证记录；若记录由存证服务提供方 代存，则应通过存证服务提供方查询接口获取。 -- 每条记录使用独立、密码学安全且原始长度不低于 128 位的随机盐，不得跨记录复用。 -- 对 `event_body` 与参与方列表使用 RFC 8785 JCS 规范化，按“规范字节序列 ∥ 盐值原始字节”拼接后执行 SHA-256 或 SM3，并以 Base64url 保存摘要。 -- `event_body` 不得包含真实姓名、证件号、联系方式、银行卡号、支付账号等高敏感明文；无法明文记录的字段宜保存带明确语义的摘要。 -- 签名至少覆盖 `event_body`、参与方列表、随机盐、存证记录唯一标识和业务事件时间。每条记录至少包含发起方签名，可增加联合签名。 -- 历史记录不得因协议升级被回写；解析方依据记录结构版本选择兼容逻辑。 +取回的链下存证记录应至少包含基础元数据、全链路串联与溯源标识、参与方列表、事件载荷、负载哈希值和数字签名等核验所需核心内容，否则不满足进入后续核验流程的条件。 -## 5. `TSD-ATT-OCA`：链上存证锚点 +### 第二步：获取签名方公钥 +核验发起方应解析数字签名数组中每个签名元素对应的签名方身份标识，并据此获取其用于验签的公钥材料。 -链上锚点与链下记录通过记录唯一标识和负载哈希建立一一映射。锚点宜使用 JWS Compact Serialization 封装；头部至少表达算法和密钥引用，载荷表达： +对于 DID 格式的身份标识，公钥宜从该身份标识对应的 DID 文档中获取；对于在 ACT Trust Chain 信任注册表中登记的机构标识，公钥宜从信任注册表中查询获取。 -- 记录唯一标识、协议/结构版本、事件类型和业务事件时间； -- JWT 签发/锚点提交时间； -- `intent_id`，以及条件适用的 `delegation_id`、订单号和支付交易号； -- 提交方身份、负载哈希、哈希算法和 ACT Trust Chain 隐私通道标识； -- 不包含业务明文或敏感身份/支付账号的可选扩展。 +核验方宜进一步验证所获取公钥在业务事件时间点上的有效性，包括是否已轮换、是否失效以及是否仍处于可用于历史签名核验的有效时间范围内。 -相同记录唯一标识的提交是幂等操作：节点应拒绝重复锚定并返回既有区块高度或等价定位信息。锚点写入后不得覆盖式修改；后续补充通过新记录或兼容扩展完成。 +若无法获取签名方当前有效公钥或可用于历史核验的有效公钥，则应终止密码学验签并返回 `PUBLIC_KEY_UNAVAILABLE`。 -ACT 2.1 指定 ACT Trust Chain 为锚定基础设施，但没有定义可直接实现的公开节点接口、网络参数、认证、JWS 字段名或 Schema；这些属于未来实现或后续版本工作，不能由开源仓库虚构。 +### 第三步：重新计算并比对负载哈希 +核验方应对链下存证记录中的事件载荷与参与方列表按 RFC 8785 JCS 规范化后，结合记录中保存的随机盐值，按照 TSD-ATT-OFF 规定的算法重新计算负载哈希。 -## 6. `TSD-ATT-SVF`：签名核验 +重新计算得到的负载哈希值应与链下存证记录中存储的负载哈希值逐字节一致；若不一致，则说明本地记录内容或其结构化要素可能已发生变更。 -核验遵循“先链下后链上、先摘要后验签、先当前记录后上游链路”： +当本地重新计算结果与记录内保存的摘要不一致时，核验流程应终止并返回 `PAYLOAD_HASH_MISMATCH`。 -1. 按记录唯一标识取回完整链下记录。 -2. 从 DID 文档、ACT Trust Chain 信任注册或其他受信来源获取业务事件时点有效的公钥；不可得时返回 `PUBLIC_KEY_UNAVAILABLE`。 -3. 用相同 JCS、盐值和算法重算负载哈希；不一致返回 `PAYLOAD_HASH_MISMATCH`。 -4. 对声明的签名覆盖范围逐项验签；无效返回 `SIGNATURE_INVALID`。 -5. 查询链上锚点并比对哈希；不存在返回 `ANCHOR_NOT_FOUND`，不一致返回 `CHAIN_HASH_MISMATCH`。来源建议 30 秒超时、最多 3 次重试，最终超时返回 `ANCHOR_QUERY_TIMEOUT`。 -6. 存在上游记录引用时，可递归核验因果链。 -7. 全部必要检查通过后返回 `VERIFIED`。 +### 第四步：密码学验签 +核验方应使用第二步获取的对应公钥，对数字签名数组中的每个签名元素逐一执行密码学验签。 +验签时应确保签名覆盖范围与 TSD-ATT-OFF 中声明的覆盖对象一致，至少包括事件载荷、参与方列表、随机盐值、存证记录唯一标识和业务事件时间。 -外部依赖暂不可用不等同于记录被篡改。`VERIFIED` 只表示密码学和链上链下一致性通过，不代表合同、监管或仲裁意义上的最终无争议结论。 +任一签名元素验证失败时，应返回 `SIGNATURE_INVALID`，并宜附带失败签名对应的签名方身份标识，以便后续定位责任主体或排查实现差异。 -## 7. `TSD-ATT-DSP`：争议处理 +若记录包含多个签名，验证方可根据业务规则决定是否要求全部签名都成功验证，但至少应保证被认定为有效的签名集合满足本场景的最低可信要求。 -争议处理按“申请—举证—核验—处置”组织：争议方提交争议类型、关联标识和说明；各方提交本方链下记录；处理方执行 `TSD-ATT-SVF`；仲裁或处理方综合证据和核验结果作出处置。 +### 第五步：链上锚点核验 +核验方应向 ACT Trust Chain 查询该存证记录唯一标识对应的链上锚点，并确认该锚点已存在。 +若锚点存在，核验方还应比对链上锚点中的负载哈希值与第三步本地重新计算得到的负载哈希值是否完全一致。 -本组件只定义流程框架。仲裁主体、举证期限、证据优先级、补证和最终裁决规则由入网协议、治理文件或法律安排确定，不属于当前 TSD 协议结论。 +链上查询宜设置超时时间为 30 秒，超时后宜重试最多 3 次；若最终仍超时，则应返回 `ANCHOR_QUERY_TIMEOUT`，而不应将其判定为 `VERIFIED` 或 `CHAIN_HASH_MISMATCH`。 + +若锚点存在但链上链下哈希值不一致，则应返回 `CHAIN_HASH_MISMATCH`；若链上不存在对应锚点，则应返回 `ANCHOR_NOT_FOUND`。 + +### 第六步：上游因果链递归核验 +若当前链下存证记录中存在上游存证记录引用字段，核验方可对其指向的上游关联存证记录递归执行第一步至第五步，以逐级构建完整的端到端因果证据链。 + +该步骤为可选步骤，但在跨域争议处理中具有较高价值，因为它能够把单点事件核验扩展为链路级事实还原，从而支持对授权、确认、支付、履约等关键节点进行整体一致性审查。 + +### 第七步：返回核验结论 +在完成前述步骤后，核验方应返回标准化核验结论，以保证不同机构和不同实现之间对核验结果的理解一致。 + +核验结论不应由自由文本随意定义，而应优先使用本组件规定的标准枚举值，以支撑后续争议处理、审计留痕和系统间自动化对接。 + +## 核验结论 +| **核验结论** | **含义** | +| --- | --- | +| `VERIFIED`
| 签名有效，链上链下一致，记录完整未篡改。 | +| `PAYLOAD_HASH_MISMATCH`
| 本地重新计算的摘要与存证记录中存储的摘要不一致，本地记录可能已被篡改。 | +| `SIGNATURE_INVALID`
| 签名验证失败，宜附带失败的签名方身份标识。 | +| `CHAIN_HASH_MISMATCH`
| 链上锚点存在，但链上摘要与本地重新计算结果不一致，链上或链下可能存在篡改。 | +| `ANCHOR_NOT_FOUND`
| 链上不存在对应锚点，存证可能未成功上链。 | +| `ANCHOR_QUERY_TIMEOUT`
| 链上查询超时，当前无法形成最终核验结论。 | +| `PUBLIC_KEY_UNAVAILABLE`
| 无法获取签名方当前有效公钥或用于历史核验的有效公钥，可能存在密钥轮换或解析失败情况。 | + +当核验结果为 `VERIFIED` 时，仅表示该记录在密码学层面和链上链下一致性层面通过核验，并不当然等同于相关业务行为在合同、监管或争议裁决意义上已经被最终确认无争议。 + +当核验结果为非 `VERIFIED` 时，后续处理方宜结合失败类型分别采取补充举证、重新查询、要求补交记录或进入争议处理流程等措施，而不宜将所有失败结果作同一处理。 + +## 技术要求 +核验实现应与 TSD-ATT-OFF 和 TSD-ATT-OCA 保持一致的数据处理规则，特别是在 JCS 规范化、哈希算法选择、Base64url 编码和字段映射方面，不应因实现差异导致同一记录在不同机构处产生不同核验结论。 + +对于采用 JWS Compact Serialization 封装的链上锚点，实现方在解析和验签时应正确处理头部、载荷和签名三部分的分离与校验，并确保算法声明与实际验签算法一致，以降低算法替换或解析歧义带来的风险。 + +核验系统宜保留过程性审计日志，包括核验时间、核验发起方、所使用公钥来源、链上查询结果和最终核验结论，以便在后续争议处理中还原核验过程。 + +当签名方发生密钥轮换时，核验实现应依据业务事件时间与密钥有效时间段进行比对，在业务事件时间落入旧密钥有效期内时继续允许使用旧密钥完成历史签名核验，以保证历史证据长期可验证。 + +# **TSD-ATT-DSP：争议处理流程** +## 概述 +TSD-ATT-DSP（Dispute Resolution）用于规定 ACT 协议交易中发生争议时的处理流程框架，明确各参与方如何基于链下存证记录和链上锚点开展举证、核验与处置。 + +本组件是可信存证体系的重要应用出口，存证机制的实际价值主要通过争议处理场景得以兑现。 + +本组件仅定义流程框架和基本要求；最终仲裁的决策权归属，例如平台仲裁、行业仲裁委员会或司法机构，由各参与方在入网协议或相关法律安排中另行约定，不属于本协议规范范围。 + +## 参与方及前置条件 +TSD-ATT-DSP 的参与方包括争议申请方、被申请方或其他相关交易参与方、负责受理并组织核验的处理方或仲裁方、提供链下存证记录代存或代查服务的存证服务提供方，以及提供链上锚点查询能力的 ACT Trust Chain 节点运营机构。 + +进入本组件前，应满足以下前置条件。 + ++ 争议事项宜已经具备可用于定位业务链路的关联标识，例如意图标识、委托标识、商户侧订单交易号或支付交易流水号中的一种或多种，以支持相关存证记录的检索与串联。 ++ 相关参与方应能够提供本方留存的完整链下存证记录，或能够依据存证记录唯一标识通过本地存储或存证服务提供方查询接口取回对应记录。 ++ 处理方还应具备查询 ACT Trust Chain 链上锚点的能力，并能够获取签名方身份标识对应的有效公钥材料，以完成链上链下一致性核验和签名有效性核验。 ++ 如无法取得必要的链下记录、链上锚点或签名核验所需公钥材料，则本组件可进入受理和举证阶段，但可能无法完成完整的标准化核验闭环。 + +## 基本流程 +争议处理宜按“争议申请—各方举证—存证核验—形成处置结论”的顺序进行，以保证处理路径清晰、责任边界明确和核验依据统一。 + +争议方应提交争议类型、用于定位业务链路的关联标识及争议描述；相关参与方应在规定时限内提交本方链下存证记录；处理方应对争议链路上的存证记录执行 TSD-ATT-SVF 核验，并将核验结论作为处置的重要依据。 + +仲裁方或处理方在综合各方举证材料与核验结论后作出处置决定；若某参与方未能在规定时限内提供存证记录，或其存证记录核验结论为非 `VERIFIED`，处理方可将此作为对该方不利的推定依据之一。 + +| **流程阶段** | **主要要求** | +| --- | --- | +| 争议申请 | 争议方提交争议类型、用于定位业务链路的关联标识及争议描述 | +| 各方举证 | 各相关参与方在规定时限内提交本方链下存证记录 | +| 存证核验 | 处理方对争议链路上的存证记录执行 TSD-ATT-SVF 核验，核验结论作为重要依据 | +| 处置结论 | 处理方综合举证材料与核验结论作出处置决定 | + +## 处理要求 +争议处理应坚持“以原始记录为基础、以密码学核验为准绳、以链上锚点为防篡改依据”的基本原则，避免仅依赖单方口头说明、平台日志截图或不可核验的二次整理材料形成结论。 + +在处理过程中，链下存证记录是原始证据来源，链上锚点用于证明其摘要已被事先锚定且不可事后篡改，签名核验流程则用于确认记录完整性、签名有效性与链上链下一致性。 + +详细的争议分类、举证时限、补证机制、证据优先级和最终裁决规则可在后续协议版本或配套治理文件中进一步完善，本章保持轻量级流程设计即可。 # 第二篇：信用关联 -## 8. 原则、对象与组件 +# 范围 +## 本子篇定位 +信用关联（Credit Association）是信任服务域的子篇之一。本子篇规定 ACT 协议中智能体与其关联主体之间信用关联关系的建立、智能体关联信用声明的生成、生命周期管理、查询授权与验证规则，为智能体在自身信用数据不足时提供可验证的关联信用参考。 + +关联主体可以是与智能体具有开发、部署、运营、控制或其他经验证关联关系的自然人、法人或其他组织。信用关联通过建立可验证的信用关联凭证，使关联主体信用信息能够在明确的适用范围内被引用，并形成面向指定智能体的关联信用声明。 + +> 注：关联信用与智能体独立信用或独立声誉属于不同信用来源。关联信用用于表达关联主体信用信息在有效信用关联关系下对指定智能体形成的受限信用参考；智能体独立信用或独立声誉用于表达智能体自身在商业交互中的历史表现。关联信用不得直接表述为智能体自身已经取得的信用等级、声誉等级或授信能力。查询方如同时使用关联信用与智能体独立信用或独立声誉信息时，需分别识别其来源、生成时间、适用范围和有效状态。 +> + +## 本子篇范围与边界 +本子篇覆盖以下内容： + ++ 关联主体与智能体之间信用关联凭证的申请、确认、签发及结构规范； ++ 关联主体信用声明到智能体关联信用声明及关联信用映射值的映射规则、来源标记和版本管理； ++ 信用关联凭证及智能体关联信用声明的生效、暂停、撤销、过期、替换和重新评估等生命周期管理； ++ 关联主体对信用验证的查询授权机制，包括逐次授权和平台代理查询； ++ 第三方对信用关联关系及关联信用信息进行标准化验证的机制。 + +本子篇不规范以下内容： + ++ 信用评价模型、智能体声誉评分公式、交易授信规则、支付风险决策规则或跨机构信用换算规则； ++ 智能体基于自身行为、履约、争议或其他历史记录形成独立信用或独立声誉的机制； ++ 任一厂商、平台、身份服务方、信用信息提供方、信用服务方、支付机构或其他参与方的内部实现。 + +## 信用关联价值说明 +当智能体代表用户或组织执行商业行为时，交易对手方、平台和风险管理系统通常需要参考其身份、行为记录和信用信息。然而，新创建的智能体或行为数据不足的智能体，可能尚未形成可供参考的自身信用或独立声誉，从而产生信任缺口。 + +信用关联通过建立可验证的关联主体与智能体之间的信用关联关系，使信用依赖方能够在明确的目的、范围和有效期内，参考关联主体信用信息所形成的智能体关联信用声明，为智能体提供补充性的信用参考。 + +这一机制的价值主要体现在以下三个方面： + ++ 对智能体而言，关联信用可在其自身信用数据不足时，为其参与商业协作提供补充性的信任参考。 ++ 对交易对手方、平台及信用依赖方而言，可验证的信用关联关系和智能体关联信用声明提供了标准化的风险参考依据，有助于其结合自身策略作出业务判断。 ++ 对生态参与方而言，信用关联可将智能体与可识别的关联主体建立可追溯联系，使关联关系、信用来源、适用范围和状态变化能够被记录、核验和审计。 + +信用关联的价值依赖于关联关系、智能体关联信用声明、查询授权和验证结果的可验证、可追溯、可撤销和可独立复核。具体机制由本子篇各协议组件规定。 + +# 本子篇组件列表与关系 +## 组件总览 +信用关联子篇由五个协议组件构成，共同完成信用关联建立、关联信用生成、生命周期管理、查询授权和独立验证的完整链路。 + +各组件的功能定位如下。 + ++ **TSD-CRD-ASC：信用关联建立。**负责规范关联主体与智能体之间信用关联关系的建立机制，包括关联前置条件、信用关联凭证结构及关联主体确认与签发流程。 ++ **TSD-CRD-MAP：关联信用映射。**负责规范关联主体信用声明、信用关联凭证与智能体关联信用声明之间的映射规则、来源标记和版本管理。 ++ **TSD-CRD-LCM：信用关联生命周期管理。**负责规范信用关联凭证及智能体关联信用声明的状态机、状态流转，以及暂停、撤销、过期、替换和重新评估等管理机制。 ++ **TSD-CRD-VER：关联信用验证。**负责规范第三方对信用关联关系及关联信用信息进行标准化验证的验证等级、报文结构、验证流程和原因码。 ++ **TSD-CRD-AUTH：信用查询授权。**负责规范关联主体对关联信用验证的授权机制，包括逐次授权和平台代理查询两种模式。 + +## 核心对象与标识 +为保持本子篇内部处理以及与其他域之间引用关系的一致性，信用关联子篇使用一组标准核心对象和标识描述信用关联链路中的关键信息。本子篇核心对象及其作用如下。 + +| 对象或标识 | 含义 | 主要产生位置 | 主要使用位置 | +| :--- | :--- | :--- | :--- | +| 信用关联申请 | 关联主体与智能体建立信用关联前形成的待确认请求 | TSD-CRD-ASC | TSD-CRD-ASC | +| 信用关联凭证 | 证明关联主体与智能体之间信用关联关系、关联范围、确认方式及状态信息的可验证对象 | TSD-CRD-ASC | TSD-CRD-MAP、TSD-CRD-LCM、TSD-CRD-VER | +| 关联主体信用声明 | 信用服务方针对关联主体发布的信用等级、区间、状态或其他信用信息声明 | 信用服务方 | TSD-CRD-MAP、TSD-CRD-VER | +| 智能体关联信用声明 | 信用服务方基于有效信用关联凭证、关联主体信用声明及映射规则，针对指定智能体签发的可验证信用声明 | TSD-CRD-MAP | TSD-CRD-LCM、TSD-CRD-VER | +| 关联信用映射值 | 智能体关联信用声明中对外表达的信用内容，可采用等级、区间、状态、限额、多维属性或其他结构化形式 | TSD-CRD-MAP | TSD-CRD-VER | +| 信用查询授权 | 关联主体允许特定请求方或平台代理主体在限定范围内验证关联信用信息的授权 | TSD-CRD-AUTH | TSD-CRD-VER | +| 信用验证记录 | 对信用关联凭证、智能体关联信用声明、查询授权及其状态完成验证后形成的结果记录 | TSD-CRD-VER | 信用依赖方、后续存证与争议处理 | + +其中，信用关联凭证用于证明关联主体与智能体之间的关联关系；关联主体信用声明用于表达关联主体的信用信息；智能体关联信用声明用于表达基于该关联关系和关联主体信用信息形成的、与指定智能体相关的关联信用信息。 + +关联信用映射值应明确标记其信用来源为 `ASSOCIATED_CREDIT`，不得被表述为智能体自身独立信用或独立声誉。 + +## 依赖与跨域引用 +信用关联子篇可被委托授权域、商业交互域和支付服务域按需引用。商业交互域可在交易准入、交易对手选择等环节引用关联信用验证结果；支付服务域可在其风险管理、额度策略或异常处理等步骤引用关联信用验证结果。 + +关联信用验证结果仅作为风险参考或业务决策输入，不得扩大、修改、覆盖或替代委托授权域规定的授权边界，也不得替代支付服务域所要求的支付授权、账户校验、反欺诈、反洗钱或其他独立风险控制。 + +# TSD-CRD-ASC：信用关联建立 +## 概述 +TSD-CRD-ASC（Credit Association Establishment）用于规定关联主体与智能体之间信用关联关系的建立机制，包括关联前置条件、信用关联凭证的标准结构及关联主体确认与签发流程。 + +本组件是信用关联子篇的逻辑起点。关联主体通过本组件完成身份核验、关联关系核验与确认后，由信用关联凭证签发方生成可验证的信用关联凭证，为后续关联信用映射、生命周期管理与独立验证提供基础。 + +## 参与方与前置条件 +本组件涉及以下参与方：关联主体、智能体、信用服务方与信用关联凭证签发方。其中： + ++ 关联主体是与智能体具有开发、部署、运营、控制、责任承担或其他经验证关联关系的自然人、法人或其他组织； ++ 信用服务方承担关联主体身份核验、关联关系核验及相关信用服务职责； ++ 信用关联凭证签发方负责生成并签发信用关联凭证； ++ 信用服务方与信用关联凭证签发方可以是同一实体，也可以由不同实体分别承担。 + +进入本组件前，应满足以下前置条件： + ++ 关联主体的身份可被信用服务方验证； ++ 智能体具有可解析的身份标识，以及可用于验证关联关系的身份凭证、控制材料或等效证明材料； ++ 关联主体能够提供其与该智能体之间关联关系的证明材料； ++ 信用关联申请中应明确关联主体、智能体、关联角色、适用目的、适用范围及其他必要限制。 + +当关联主体声明其关联角色为控制者、运营者或其他涉及智能体实际控制的角色时，应能够提供与其控制范围相匹配的控制材料或等效证明。关联主体为开发者、部署者或其他非控制角色时，应提供与其声明角色相匹配的关联证明材料。 + +## 流程步骤 +**步骤一：发起信用关联申请** + +关联主体向信用服务方发起信用关联申请，并提交拟关联智能体的身份标识、相关身份凭证或证明材料、关联角色、使用目的、适用范围及防重放要素。 + +信用服务方对申请材料进行初步校验，确认申请报文完整、请求未被重放，并生成待确认的信用关联申请。 + +**步骤二：关联主体身份与关联关系核验** + +信用服务方对信用关联申请者进行身份核验，确认其身份与所声称的关联主体一致。 + +信用服务方应进一步核验关联主体与智能体之间的关联关系，包括但不限于开发、部署、运营、控制或其他声明的关联角色。关联关系核验通过后，关联主体应进一步确认拟关联的智能体、关联角色、适用目的、适用范围、有效期、查询授权方式及撤销方式等信息。 + +**步骤三：生成待签发信用关联凭证** + +信用服务方依据已核验并经关联主体确认的信用关联申请，按照 `TSD-CRD-MAP` 规定的关联信用映射规则，生成与该智能体相关的关联信用声明。 + +信用服务方应将已生成的智能体关联信用声明，以及经确认的关联主体与智能体关联关系信息、适用目的、适用范围、关联关系确认声明和确认材料，一并通知信用关联凭证签发方，用于生成和签发信用关联凭证。 + +**步骤四：信用关联凭证签发** + +信用关联凭证签发方应根据已核验的信用关联申请、关联主体确认结果及信用服务方生成的智能体关联信用声明，按照 3.4 节定义的凭证结构生成信用关联凭证。 + +信用关联凭证签发方应对凭证关键字段进行签名。凭证中的关联主体信用声明引用、关联信用映射值、映射规则标识及版本，应与信用服务方生成的智能体关联信用声明保持一致。 + +信用关联凭证签发后，其状态置为 `ACTIVE`。信用关联凭证签发方应将已生效的信用关联凭证提供给智能体或其受托主体留存，用于后续关联信用映射和关联信用验证场景。 + +## 信用关联凭证结构 +信用关联凭证包含以下字段。 + +| 字段语义 | 存在性 | 说明 | +| --- | --- | --- | +| 凭证标识 | 必备 | 信用关联凭证的唯一标识 | +| 凭证版本 | 必备 | 当前使用的凭证结构版本 | +| 信用关联申请标识 | 必备 | 指向本凭证对应的信用关联申请 | +| 智能体标识 | 必备 | 标识当前信用关联所对应的智能体 | +| 关联主体标识 | 必备 | 标识当前信用关联所对应的关联主体 | +| 关联角色 | 可选 | 关联主体与智能体之间的关系角色，如开发者、部署者、运营者、控制者、责任承担主体或其他经定义角色 | +| 签发方标识 | 必备 | 当前信用关联凭证签发方身份 | +| 与智能体关系证明材料引用 | 必备 | 用于验证关联主体与智能体之间关联关系的身份凭证、控制材料、证明文件或等效材料引用 | +| 关联主体确认方式 | 必备 | `DIRECT_SIGNATURE`或 `ATTESTED_CONFIRMATION` | +| 关联主体信用声明引用 | 条件必备 | 需要提供关联信用信息时必备，指向关联主体信用声明 | +| 关联信用映射值 | 必备 | 映射后提供给智能体的关联信用表达，可采用等级、区间、状态、限额、多维属性或其他结构化形式 | +| 关联信用来源标记 | 必备 | 标识关联信用来源，取值为 `ASSOCIATED_CREDIT` | +| 映射规则标识及版本 | 必备 | 标识生成关联信用映射值所采用的映射规则及版本 | +| 关联关系确认声明 | 必备 | 关联主体对其与指定智能体之间的关联关系、关联角色、适用目的、适用范围以及责任边界作出的确认声明 | +| 适用目的 | 必备 | 信用关联允许被使用的业务目的 | +| 适用范围 | 必备 | 信用关联适用的场景、交易类型、请求方类别或其他限制 | +| 关联主体控制的公钥 | 条件必备 | 确认方式采用 `DIRECT_SIGNATURE`时必备，用于验证关联主体内层签名 | +| 关联主体签名值 | 条件必备 | 确认方式采用 `DIRECT_SIGNATURE`时必备，即关联主体内层签名值 | +| 关联主体签名算法 | 条件必备 | 确认方式采用 `DIRECT_SIGNATURE`时必备，标识内层签名所用算法及版本 | +| 签发时间 | 必备 | 凭证生成时间 | +| 生效时间 | 必备 | 凭证开始生效时间 | +| 过期时间 | 可选 | 凭证失效时间 | +| 状态查询信息 | 必备 | 用于查询凭证当前状态的引用或等效信息 | +| 前序凭证引用 | 可选 | 关联替换、续期或关联证明材料轮换时指向前序凭证 | +| 凭证签发方签名值 | 必备 | 信用关联凭证签发方对凭证关键字段的外层签名值 | +| 凭证签发方签名算法 | 必备 | 标识外层签名所用算法及版本 | + +其中，关联主体信用声明引用、关联信用映射值、映射规则标识及版本构成关联信用映射的可追溯三要素。 + +### 关联主体确认方式 +关联主体确认方式采用以下方式之一。两种方式应具有相同的核心语义：关联主体明确知悉并同意其与指定智能体建立信用关联，确认结果不得被转用于其他智能体、其他关联主体、其他目的、其他范围或其他信用关联申请。 + ++ **DIRECT_SIGNATURE**：关联主体使用其控制的签名私钥，对信用关联关键要素直接签名。信用关联凭证签发方核验关联主体内层签名后，再以自身签名私钥对信用关联凭证进行外层签名。此方式下凭证具有两层签名。 ++ **ATTESTED_CONFIRMATION**：关联主体通过信用服务方完成身份核验与交互确认，由信用关联凭证签发方基于信用服务方的确认结果签发凭证。此方式下凭证仅具有信用关联凭证签发方的外层签名。 + +### 签名数据范围 +在 `DIRECT_SIGNATURE` 确认方式下，关联主体应对信用关联申请及其确认内容进行内层签名。 + ++ 内层签名应至少覆盖：信用关联申请标识、智能体标识、关联主体标识、关联角色、关联关系证明材料引用、关联关系确认声明、关联信用映射信息、适用目的、适用范围、有效期、签发方标识及防重放要素。 + +无论采用何种确认方式，信用关联凭证签发方均应对凭证进行外层签名。 + ++ 外层签名应覆盖凭证标识、凭证版本、签发方标识、关联主体确认方式，以及信用关联凭证中除状态信息、签名信息和前序凭证引用外的全部核心字段；在 `DIRECT_SIGNATURE` 方式下，还应覆盖关联主体内层签名及其验证所需公钥信息。 + +凭证当前状态、状态查询信息、前序凭证引用、外层签名值及外层签名算法不参与外层签名数据范围。当前状态应由状态查询信息所指向的状态机制单独维护；状态流转不应使凭证签名失效，并应与 `TSD-CRD-LCM` 的状态管理机制一致。 + +## 处理要求 +信用服务方应验证关联主体与智能体之间关联关系证明材料的有效性，防止他人以未获授权的智能体身份、控制材料、关联角色或主体身份发起信用关联申请。 + +关联关系验证包括以下场景： + ++ **初始验证**：在信用关联申请阶段完成，确认申请者身份真实、关联角色明确，且申请者与智能体之间存在与其声明角色相匹配的关联关系；验证通过后方可进入关联主体确认与凭证签发环节。 ++ **持续重验证**：在信用关联凭证有效期内，按周期或事件触发进行。当关联证明材料轮换、控制材料变更、密钥泄露迹象被识别、智能体运行主体发生变更、关联主体身份状态异常或达到预设重验证周期时，应触发重新验证。 ++ **异常处置**：重验证未通过，或信用服务方发现关联关系可能失效、被伪造或超出已声明范围时，信用关联凭证应按照 `TSD-CRD-LCM` 转入 `SUSPENDED` 或 `REVOKED` 状态。 + +关联主体确认结果不得被转用于其他智能体、其他关联主体、其他关联角色、其他目的、其他适用范围或其他信用关联申请。 + +凭证中的关联关系确认声明应明确关联主体所确认的关联角色、关联关系范围、适用目的和适用边界，不得为空或采用可能误导的模糊表述。关联关系确认声明仅用于证明关联主体对信用关联关系及其使用范围的确认，不构成对智能体交易、支付、履约或其他商业行为结果的承诺。 + +关联主体、智能体、关联角色、关联关系证明材料、关联关系确认声明、关联主体信用声明、关联信用映射值、映射规则、适用目的、适用范围或有效期发生实质变化时，应签发新的信用关联凭证，并通过前序凭证引用建立关联关系。 + +# TSD-CRD-MAP：关联信用映射 +## 概述 +TSD-CRD-MAP（Associated Credit Mapping）用于规定关联主体信用声明到智能体关联信用声明的映射规则。 + +本组件规定关联信用映射过程的标准化要求，以及智能体关联信用声明和关联信用映射值的表达规范；不规定具体映射规则本身。具体映射规则由信用服务方按照其信用模型、风险策略和业务要求自行实现。 + +本组件在信用关联凭证签发流程中被 `TSD-CRD-ASC` 引用。信用服务方依据本组件的要求，将关联主体信用声明按照适用映射规则转换为智能体关联信用声明，并将关联信用映射值及相关映射信息提供给信用关联凭证签发方，作为信用关联凭证中关联信用信息的生成依据。 + +## 参与方与前置条件 +本组件涉及以下参与方：信用服务方、信用关联凭证签发方。 + +进入本组件前，应满足以下前置条件： + ++ 关联主体已完成身份核验并确认信用关联申请； ++ 关联主体与智能体之间的关联关系已通过信用服务方核验； ++ 信用服务方已取得关联主体信用声明或其可验证引用； ++ 信用关联申请中已明确智能体、关联主体、关联角色、适用目的、适用范围及有效期等必要信息。 -关联主体可以是与 Agent 具有开发、部署、运营、控制或其他已验证关系的自然人、法人或组织。关联信用只是在明确目的、范围和有效期内形成的补充性风险参考： +信用服务方应在信用关联凭证签发前完成关联信用映射，并将映射结果提供给信用关联凭证签发方。 -- 必须标记来源为 `ASSOCIATED_CREDIT`； -- 不得表述为 Agent 自身独立信用、独立声誉、信用等级或授信能力； -- 不得扩大或替代 IAC 授权边界； -- 不得替代支付授权、账户校验、反欺诈、反洗钱或其他独立风控； -- 验证结果不直接构成交易准入、授信或支付批准。 +## 关联主体信用声明 +关联主体信用声明是信用服务方针对关联主体提供的信用信息声明，是关联信用映射的输入依据。 -| 组件 | 作用 | -|---|---| -| `TSD-CRD-ASC` | 建立关联关系并签发信用关联凭证 | -| `TSD-CRD-MAP` | 将关联主体信用声明映射为 Agent 关联信用声明 | -| `TSD-CRD-LCM` | 管理凭证暂停、恢复、撤销、过期、替换和重评估 | -| `TSD-CRD-VER` | 验证凭证本身或进一步验证当前关联信用信息 | -| `TSD-CRD-AUTH` | 约束关联信用信息查询的主体、目的、数据项和频率 | +关联主体信用声明是独立对象，信用关联凭证通过引用方式关联该声明，不直接承载其原始信用内容。信用服务方可根据适用的数据保护、隐私保护和业务规则，决定关联主体信用声明的具体内容、披露方式和访问控制方式。 -核心对象包括信用关联申请、信用关联凭证、关联主体信用声明、Agent 关联信用声明、关联信用映射值、信用查询授权和信用验证记录。 +关联主体信用声明宜包含以下元数据： -## 9. `TSD-CRD-ASC`：信用关联建立 ++ 声明标识； ++ 声明版本； ++ 信用服务方标识； ++ 签发时间； ++ 有效期； ++ 签名或等效证明。 -### 9.1 流程 +关联主体信用声明中的信用内容，例如等级、区间、额度、状态、多维评分或其他信用属性，由信用服务方按照其信用模型发布。本子篇不规定关联主体信用声明的统一内容形式、统一等级体系或统一评分方法。 -1. 关联主体提交 Agent 标识、关联证明、角色、目的、范围和防重放要素。 -2. 信用服务方验证主体身份、关联关系和角色匹配，并取得对 Agent、目的、范围、有效期、查询授权和撤销方式的确认。 -3. 信用服务方按 `TSD-CRD-MAP` 生成 Agent 关联信用声明。 -4. 信用关联凭证签发方生成并签名凭证；签发后状态为 `ACTIVE`。 +## 关联信用映射规则 +本子篇不规定具体关联信用映射规则。关联信用映射规则由信用服务方根据其信用模型、风险策略和业务要求自行制定和实施。 -### 9.2 凭证语义 +关联信用映射过程应满足以下标准化要求。 -凭证至少表达凭证/申请/Agent/关联主体/签发方标识、关联证明引用、确认方式、关联信用映射值、`ASSOCIATED_CREDIT` 来源标记、映射规则及版本、关联关系确认声明、适用目的和范围、签发/生效时间、状态查询信息和签发方签名。需要提供关联信用信息时，关联主体信用声明引用为条件必备。 +**映射规则标识及版本：** -关联主体信用声明引用、映射值、映射规则标识及版本构成可追溯三要素。缺少任一项，不得把映射值独立解释、比较或使用。 ++ 每个关联信用映射规则应具有在信用服务方管理范围内可唯一识别的规则标识及版本。 ++ 映射规则标识及版本应携带于信用关联凭证中，用于标识关联信用映射值由何种映射规则生成。映射规则发生迭代、调整或替换时，应更新规则版本。不同规则或不同版本产生的关联信用映射值，不得在缺少规则标识及版本信息的情况下直接比较、换算或解释。 -确认方式二选一： +**可追溯：** -- `DIRECT_SIGNATURE`：关联主体对申请和关键确认内容作内层签名；签发方核验后再作外层签名，形成两层签名。 -- `ATTESTED_CONFIRMATION`：关联主体通过信用服务方完成身份核验和交互确认；凭证只有签发方外层签名。 ++ 关联主体信用声明引用、关联信用映射值、映射规则标识及版本共同构成关联信用映射的可追溯三要素。 ++ 关联信用映射值应为指定映射规则及版本作用于指定关联主体信用声明的结果。可追溯三要素应随信用关联凭证一并保存和验证，缺少其中任一项时，不得将关联信用映射值作为可独立解释、比较或使用的关联信用信息。 ++ 信用关联凭证签发方在签发凭证时，应校验可追溯三要素的完整性和一致性。信用验证服务方在验证关联信用信息时，应校验相关引用、规则标识及版本与凭证中记录的信息一致。 -关联关系确认声明必须明确角色、范围、目的和责任边界。它只证明主体对关联关系及使用范围的确认，不承诺 Agent 的交易、支付或履约结果。确认不得转用于其他 Agent、主体、角色、目的、范围或申请。 +**信用权限约束:** -核心字段发生实质变化时必须签发新凭证，并以“前序凭证引用”建立关系，不得覆盖旧凭证。 ++ 关联信用不得使智能体直接继承关联主体的全部信用权限、信用额度、授信能力或其他业务资格。 ++ 信用服务方应对关联信用映射结果设置独立于关联主体自身信用的使用上限或边界，并结合关联角色、适用目的、适用范围、有效期及其他风险限制，明确关联信用信息可被参考的范围。 -## 10. `TSD-CRD-MAP`：关联信用映射 +## 智能体关联信用声明与关联信用映射值 +智能体关联信用声明是信用服务方基于有效信用关联申请、关联主体信用声明和关联信用映射规则，针对指定智能体生成的信用声明。 -关联主体信用声明是独立对象，宜带有声明标识/版本、信用服务方、签发时间、有效期和签名/等价证明。信用关联凭证通过引用关联它，不直接承载其原始信用内容。 +智能体关联信用声明由关联信用映射值、来源信息、映射依据和使用边界共同表达。 -具体评分、等级和映射模型由信用服务方决定，TSD 只要求： ++ **关联信用映射值**：由本组件生成，用于表达与指定智能体相关的信用映射结果，可采用等级、区间、状态、限额、多维属性或其他形式。 ++ **来源信息**：包括关联主体信用声明引用及关联信用来源标记。关联信用来源标记应为 `ASSOCIATED_CREDIT`，不得标记为智能体独立信用或独立声誉。 ++ **映射依据**：包括映射规则标识及版本，用于识别生成关联信用映射值所使用的映射规则。 ++ **使用边界**：包括适用目的、适用范围、有效期及其他必要限制。其中，适用目的和适用范围由关联主体在 `TSD-CRD-ASC` 的信用关联流程中确认。 -- 每条映射规则有可唯一识别的标识和版本； -- 不同规则/版本的结果不得在缺少规则信息时直接比较或换算； -- 声明引用、映射值和规则版本共同保留并验证； -- 映射结果有独立于关联主体自身信用的上限和使用边界； -- Agent 不得直接继承关联主体全部信用权限、额度、授信能力或业务资格。 +关联信用映射值的具体数据结构由信用服务方按照其信用模型定义。本子篇不规定统一数据结构。无论采用何种表达形式，关联信用映射值均应满足可追溯三要素约束，不得脱离关联主体信用声明引用和映射规则标识及版本被独立解释。 -映射值可以是等级、区间、状态、限额、多维属性或其他结构化形式；来源不冻结统一数据结构。 +# TSD-CRD-LCM：信用关联生命周期管理 +## 概述 +TSD-CRD-LCM（Credit Association Lifecycle Management）用于规定信用关联凭证的生命周期状态机、状态流转规则，以及暂停、撤销、过期、替换和重新评估等管理机制。 -## 11. `TSD-CRD-LCM`：生命周期 +本组件确保关联主体可撤销信用关联，信用服务方可在关联主体信用声明变化、关联关系变化或风险事件发生时触发暂停与重新评估。信用关联凭证的核心字段发生变化时，不应覆盖原凭证，而应签发新的信用关联凭证并建立前序凭证引用关系，以保证相关处理过程可追溯、可审计和可复核。 -| 状态 | 语义 | -|---|---| -| `PENDING` | 申请已创建，确认、映射或签发未完成 | -| `ACTIVE` | 凭证有效，可在范围内用于验证 | -| `SUSPENDED` | 暂停，不得产生新的通过结果 | -| `REVOKED` | 不可逆撤销，终态 | -| `EXPIRED` | 超过有效期，终态 | +信用关联凭证的状态决定其所承载关联信用信息是否可被用于后续关联信用验证。 -允许 `PENDING → ACTIVE/REVOKED/EXPIRED`、`ACTIVE → SUSPENDED/REVOKED/EXPIRED`、`SUSPENDED → ACTIVE/REVOKED/EXPIRED`。关联主体可主动暂停或撤销；信用服务方可因声明、关联、证明或风险异常触发暂停/撤销；签发方执行并保存状态变化。 +## 参与方与前置条件 +本组件涉及以下参与方：关联主体、信用服务方、信用关联凭证签发方与信用验证服务方。 -关联主体信用声明、映射规则、证明材料、角色、目的、范围或其他核心字段变化时触发重新评估：先暂停旧凭证，重算声明和映射；核心字段变化则签发新凭证，新凭证生效后旧凭证进入 `REVOKED`；无实质变化且未过期时可以恢复旧凭证。历史验证记录保留当时状态，但查询方必须能识别后续撤销。 +进入本组件前，应满足以下前置条件： -## 12. `TSD-CRD-VER`：关联信用验证 ++ 信用关联申请已创建，或信用关联凭证已签发； ++ 信用关联凭证签发方具备维护或查询凭证状态的能力； ++ 信用服务方能够识别关联主体信用声明、关联关系或其他相关信息的变化。 -验证分两级： +## 生命周期状态 +信用关联凭证具有以下生命周期状态。 -1. **信用关联凭证验证**：检查请求、防重放、请求方身份、外层签名，必要时检查内层签名，并核对主体、Agent、角色、目的、范围、映射三要素和当前 `ACTIVE` 状态；不查询关联主体信用原文，因此不需要信用查询授权。 -2. **关联信用信息验证**：在第一级通过后，验证信用查询授权、关联主体信用声明当前有效性、映射规则版本和 Agent 关联信用声明当前状态，并按最小披露返回获授权数据。 +| 状态 | 含义 | +| --- | --- | +| `PENDING` | 信用关联申请已创建，但关联主体确认、关联信用映射或凭证签发尚未完成 | +| `ACTIVE` | 信用关联凭证已生效，可在适用范围内用于关联信用验证 | +| `SUSPENDED` | 信用关联凭证被临时暂停，不得据此产生新的有效关联信用验证结果 | +| `REVOKED` | 信用关联凭证已被撤销，不得恢复为有效状态 | +| `EXPIRED` | 信用关联凭证已超过有效期，不得再用于关联信用验证 | -请求至少表达请求标识/版本、信用依赖方、Agent、验证等级、业务目的/上下文、请求数据项、凭证、请求时间、防重放要素和请求证明；第二级还要提供关联主体信用声明引用。 +其中，`SUSPENDED` 状态可根据触发原因区分为关联主体主动暂停、信用服务方风险暂停或其他暂停情形。具体暂停原因应通过状态变更原因码记录，不单设独立生命周期状态。 -响应表达验证记录、实际完成等级、`PASS` / `FAIL` / `INCONCLUSIVE` / `REVIEW_REQUIRED`、原因码、凭证状态、适用范围、结果时间/过期时间、目的限定和响应证明。第二级通过且获授权时，才可返回 `ASSOCIATED_CREDIT`、映射值、声明有效性和映射规则版本。 +## 状态流转规则 +```plain -关键失败不得返回 `PASS`；证据不足或依赖不可用返回 `INCONCLUSIVE`；重评估中或需要更高保证等级时返回 `REVIEW_REQUIRED`。标准原因码包括请求/证明/时效/重放、授权缺失/过期/撤销/范围不符、Agent 不可解析、凭证不存在/非有效/证明无效、信用声明不可得/无效、映射规则不支持等类别。 + ┌─────────────┐ + │ PENDING │ + └──────┬──────┘ + ┌───────────┼───────────┐ + ▼ ▼ ▼ + ┌────────┐ ┌──────────┐ ┌─────────┐ + │ ACTIVE │ │ REVOKED │ │ EXPIRED │ + └───┬────┘ └──────────┘ └─────────┘ + │ ▲ + │ │ + ▼ │ + ┌───────────┐ + │ SUSPENDED │ + └─────┬─────┘ + ├──────────────► REVOKED + └──────────────► EXPIRED +``` -## 13. `TSD-CRD-AUTH`：信用查询授权 +允许的状态流转如下： -信用查询授权只允许查询或验证关联信用信息，不构成交易、支付、履约或其他商业行为授权。授权应绑定信用依赖方、可选平台代理主体、Agent 范围、验证等级、业务目的、请求数据项、有效期、结果使用限制；平台代理查询还必须有机器可读频率限制，例如 `max_requests_per_window` 与 `window_duration`。 ++ `PENDING → ACTIVE`：信用关联申请已完成关联主体确认、关联信用映射及凭证签发，凭证生效； ++ `PENDING → REVOKED`：信用关联申请被撤销或终止； ++ `PENDING → EXPIRED`：信用关联申请超过有效期但未完成凭证签发； ++ `ACTIVE → SUSPENDED`：信用关联凭证被临时暂停； ++ `ACTIVE → REVOKED`：信用关联凭证被撤销，或因关联信用信息、关联关系或其他核心字段发生实质变化而被新凭证替换； ++ `ACTIVE → EXPIRED`：信用关联凭证超过有效期； ++ `SUSPENDED → ACTIVE`：暂停原因消除后恢复生效； ++ `SUSPENDED → REVOKED`：暂停期间确认应撤销，或原凭证被新凭证替换； ++ `SUSPENDED → EXPIRED`：暂停期间超过有效期。 -两种授权模式： +`REVOKED` 与 `EXPIRED` 为终态，不得流转至其他状态。 -- **逐次授权**：每次第二级验证都通知关联主体确认，独立绑定请求方、Agent、目的、数据项、请求标识和有效时间。 -- **平台代理查询**：关联主体预先授权明确的平台主体在限定范围和期限内查询，无需逐次参与；平台代理不得转授权或把结果用于授权目的之外。 +## 暂停与恢复 +`SUSPENDED` 状态可由以下主体发起： -每次验证都必须检查授权状态与请求范围。撤销后不得产生新的有效第二级验证结果；响应必须遵守最小披露。 ++ **关联主体主动暂停**：关联主体可因自身需要请求暂停信用关联凭证。关联主体确认恢复条件满足后，可请求将凭证恢复为 `ACTIVE`。 ++ **信用服务方风险暂停**：信用服务方可基于关联主体信用声明异常、关联关系异常、智能体行为异常、关联证明材料失效、控制材料重验证未通过或其他风险判断，通知信用关联凭证签发方暂停凭证。风险消除后，由信用服务方确认是否恢复。 ++ **信用关联凭证签发方执行状态变更**：信用关联凭证签发方根据信用服务方或关联主体的有效指令执行暂停、恢复或撤销等状态变更，并维护状态变更记录。 -## 14. 当前机器契约与实现边界 +`SUSPENDED` 期间，信用验证服务方不得基于该凭证产生新的通过验证结果。 -ACT 2.1 已冻结信用关联的业务语义、对象必备性、状态和原因码，但没有冻结整个 TSD 统一的英文 wire 字段名、规范性 JSON Schema、版本协商、错误封装或统一 HTTP 接口。以下内容仍不构成 ACT 2.1 的正式机器契约： +## 重新评估与凭证替换 +当关联主体信用声明、关联信用映射规则、关联关系证明材料、关联角色、适用目的、适用范围或其他核心字段发生可能影响关联信用信息有效性的变化时，信用服务方应触发重新评估。 -- ACT Trust Chain 公开网络、节点接口、认证、隐私通道和正式 JWS 载荷 Schema； -- 每种 `event_body` 的字段级 Schema 与事件提交/查询接口； -- TSD 各子篇共用的身份解析、历史公钥获取、状态查询和注册协议； -- 全域统一的算法协商、传输封装和 Conformance Profile。 +重新评估流程如下： -仓库在 [`code/schemas/tsd-crd/reference-v1`](../../code/schemas/tsd-crd/reference-v1/README.md) 提供一套明确标为非规范性的 TSD-CRD Reference Profile，并在 [`code/samples/tsd-crd-reference`](../../code/samples/tsd-crd-reference/README.md) 提供本地 Reference Implementation。该 Profile 选择 `camelCase` 字段、Ed25519、确定性 JSON 签名投影和本地 HTTP 绑定，只是可选实现约定，不能反向解释为 ACT 2.1 要求或 TSD 统一 wire 契约。 +1. 信用服务方识别关联主体信用声明、关联关系或其他相关信息发生变化，并通知信用关联凭证签发方暂停原信用关联凭证； +2. 信用服务方依据变更后的信息及适用映射规则，重新生成智能体关联信用声明和关联信用映射值； +3. 信用服务方判断重新评估结果是否导致原信用关联凭证中的核心字段发生变化； +4. 如核心字段发生变化，应按照 `TSD-CRD-ASC` 的规定生成新的信用关联凭证，并通过前序凭证引用关联原凭证； +5. 新凭证生效后，原凭证应转为 `REVOKED` 状态； +6. 如重新评估确认原凭证所依据的信息未发生实质变化，且原凭证未超过有效期，信用关联凭证签发方可将原凭证恢复为 `ACTIVE`。 -参考实现只使用 Mock 身份/信用/映射、内存存储和临时测试密钥。Schema 校验、测试和基础一致性 Runner 通过，仅证明当前 `reference-v1` 路径满足仓库内已执行检查；不等于 ACT 2.1 全量 Conformance、真实信用服务、ACT Trust Chain 节点或生产安全证明。仓库仍不虚构信用模型、链上网络或生产身份/密钥基础设施。 +信用关联凭证中的关联主体信用声明引用、关联信用映射值、映射规则标识及版本、关联关系证明材料、关联角色、适用目的、适用范围及有效期，均属于核心字段。核心字段发生变化时，不得覆盖式修改原凭证。 -## 15. 来源 +重新评估期间，原凭证处于 `SUSPENDED` 状态，信用验证服务方不得基于该凭证产生新的 `PASS` 验证结果。 -- TSD 相关网站参考：[信任服务域](https://www.act-protocol.com/documentation/trust)；未标明 ACT 2.1 的网页内容不是本 Release 的规范来源 -- ADD：[委托授权域](https://www.act-protocol.com/documentation/delegation) -- 跨域场景参考：[典型场景与业务流程](https://www.act-protocol.com/documentation/scenarios) +## 撤销 +关联主体可随时撤销信用关联凭证。信用服务方或信用关联凭证签发方也可在发现关联关系失效、关联主体信用声明无效、关联证明材料被伪造、风险事件发生或其他应撤销情形时，撤销信用关联凭证。 + +撤销是凭证级不可逆操作。凭证撤销后应进入 `REVOKED` 状态，且不得恢复为有效状态。 + +关联主体在原凭证撤销后，仍可重新发起信用关联申请；重新建立信用关联时，应生成新的信用关联凭证，并可通过前序凭证引用关联已撤销凭证。 + +撤销生效后，信用验证服务方不得再基于该凭证产生新的 `PASS` 验证结果。已生成的历史验证记录应保留其生成时的凭证状态和验证结果，但查询方应能够识别该凭证在后续时点已被撤销。 + +# TSD-CRD-VER：关联信用验证 +## 概述 +TSD-CRD-VER（Associated Credit Verification）用于规定信用依赖方对智能体信用关联关系及关联信用信息进行标准化验证的机制，包括验证等级、验证流程、验证请求与响应报文及标准原因码。 + +验证分为两个等级： + ++ **信用关联凭证验证**：验证信用关联凭证本身的签名完整性、关联主体确认信息及当前状态有效性； ++ **关联信用信息验证**：在信用关联凭证验证基础上，进一步查询并验证关联主体信用声明及关联信用映射信息的当前有效性。 + +信用关联凭证验证不涉及对关联主体信用信息的查询，因此不需要信用查询授权。关联信用信息验证涉及关联主体信用声明的查询或确认，应取得关联主体的有效信用查询授权，具体授权规则见 `TSD-CRD-AUTH`。 + +验证结果仅说明相关协议对象在指定时点是否满足对应验证等级的要求，不直接构成交易准入、授信、支付批准、风险判断或其他业务决策结论。信用依赖方应基于自身规则独立作出业务决策。 + +## 参与方与前置条件 +本组件涉及以下参与方：信用依赖方、信用验证服务方、信用关联凭证签发方、信用服务方。 + +进入本组件前，应满足以下前置条件： + ++ 信用关联凭证已签发； ++ 信用依赖方能够提供待验证智能体标识及信用关联凭证或其引用； ++ 信用验证服务方能够取得信用关联凭证签发方的验证材料及状态查询信息； ++ 执行关联信用信息验证时，信用依赖方已取得关联主体的有效信用查询授权。 + +## 验证流程 +### 信用关联凭证验证 +信用验证服务方应执行以下处理： + +1. 校验请求报文版本、必备字段、请求标识、请求时间及防重放要素； +2. 验证信用依赖方身份及请求证明； +3. 取得信用关联凭证，验证信用关联凭证签发方外层签名的有效性； +4. 在 `DIRECT_SIGNATURE` 确认方式下，验证关联主体内层签名的有效性； +5. 校验信用关联凭证中的智能体标识、关联主体标识、关联角色、适用目的及适用范围与本次请求的一致性； +6. 查询凭证状态查询信息，确认信用关联凭证当前状态为 `ACTIVE`； +7. 校验关联主体信用声明引用、关联信用映射值、映射规则标识及版本等关联信用映射信息完整，并与信用关联凭证中的记录一致。 + +信用关联凭证验证不要求信用验证服务方重算信用服务方内部映射模型，也不要求其取得关联主体信用声明原始内容。 + +信用关联凭证验证任一关键步骤失败时，不得返回 `PASS`，且不得进入关联信用信息验证。 + +### **关联信用信息验证** +关联信用信息验证应在信用关联凭证验证通过后执行。信用验证服务方应执行以下处理： + +1. 验证信用查询授权当前有效； +2. 向信用服务方查询或确认关联主体信用声明当前有效，未被撤销、纠正、替换或标记为失效； +3. 校验信用关联凭证中记录的映射规则标识及版本仍可被识别和适用； +4. 确认智能体关联信用声明及关联信用映射值仍处于可使用状态； +5. 按最小披露原则和授权数据项裁剪响应内容，仅返回本次验证所必需且已获授权的数据项； +6. 对验证结果生成响应证明，并保存验证记录。 + +任何关键步骤失败时，不得返回 `PASS`。 + +证据不足或无法明确判断验证是否通过时，应返回 `INCONCLUSIVE`，不得以默认通过替代。 + +当信用关联凭证处于重新评估期间、关联信用信息需要重新确认，或关联主体确认强度不符合业务所要求强度时，应返回 `REVIEW_REQUIRED`。 + +## 验证请求 +验证请求包含以下字段。 + +| 字段语义 | 存在性 | 说明 | +| --- | --- | --- | +| 请求标识 | 必备 | 用于幂等处理和结果关联 | +| 请求报文版本 | 必备 | 请求报文结构版本 | +| 信用依赖方标识 | 必备 | 发起验证的信用依赖方 | +| 智能体标识 | 必备 | 被验证智能体 | +| 验证等级 | 必备 | 信用关联凭证验证 或 关联信用信息验证 | +| 关联主体信用声明引用 | 条件必备 | 关联信用信息验证时必备 | +| 业务目的 | 必备 | 验证结果的使用目的 | +| 业务上下文 | 必备 | 订单、委托、交易或风险决策的最小关联信息 | +| 请求数据项 | 必备 | 期望返回的字段、声明或验证结论集合 | +| 信用关联凭证 | 必备 | 待验证的信用关联凭证或其引用 | +| 请求时间 | 必备 | 请求生成时间 | +| 防重放要素 | 必备 | 随机数、幂等键或等效要素 | +| 请求证明 | 必备 | 覆盖请求关键字段的签名或等效证明 | + +## 验证响应 +验证响应包含以下字段。 + +| 字段语义 | 存在性 | 说明 | +| --- | --- | --- | +| 请求标识 | 必备 | 对应原验证请求 | +| 验证记录标识 | 必备 | 本次验证结果的唯一标识 | +| 智能体标识 | 必备 | 被验证智能体 | +| 已完成验证等级 | 必备 | 实际完成的最高验证等级，取值为信用关联凭证验证 或 关联信用信息验证 | +| 验证结果 | 必备 | `PASS`、`FAIL`、`INCONCLUSIVE` 或 `REVIEW_REQUIRED` | +| 原因码 | 必备 | 解释验证结果 | +| 信用关联凭证状态 | 必备 | 凭证当前生命周期状态 | +| 关联信用来源标记 | 条件必备 | 关联信用信息验证通过且返回关联信用信息时必备，取值为 `ASSOCIATED_CREDIT` | +| 关联信用映射值 | 条件必备 | 关联信用信息验证通过且已获授权返回相关信用信息时必备 | +| 关联主体信用声明有效性 | 条件必备 | 关联信用信息验证时返回关联主体信用声明当前是否有效 | +| 映射规则标识及版本 | 条件必备 | 关联信用信息验证通过且返回关联信用信息时必备 | +| 适用范围 | 必备 | 本次验证结果允许使用的范围 | +| 结果生成时间 | 必备 | 验证完成时间 | +| 结果过期时间 | 必备 | 超过该时间后应重新验证 | +| 状态查询信息 | 可选 | 用于检查信用关联凭证或验证结果后续状态 | +| 目的限定标记 | 必备 | 标识本次验证结果仅限指定业务目的使用 | +| 响应证明 | 必备 | 覆盖响应关键字段的签名或等效证明 | + +响应应遵循最小披露原则： + ++ 信用关联凭证验证响应不应返回关联主体信用声明原始内容或关联信用映射值； ++ 关联信用信息验证不默认返回关联主体原始身份信息、关联主体信用声明原始内容或信用服务方内部映射依据； ++ 超出查询授权范围或请求数据项范围的字段，应被裁剪而不予返回。 + +## 标准原因码 +| 原因码 | 含义 | +| --- | --- | +| `VERIFIED` | 指定验证等级已通过 | +| `INVALID_REQUEST` | 请求结构、版本或必备字段不合法 | +| `REQUEST_PROOF_INVALID` | 请求签名或等效证明验证失败 | +| `REQUEST_EXPIRED` | 请求超出允许时间窗 | +| `REPLAY_DETECTED` | 请求标识或防重放要素已被使用 | +| `AUTHORIZATION_REQUIRED` | 关联信用信息验证缺少有效信用查询授权 | +| `AUTHORIZATION_EXPIRED` | 信用查询授权已过期 | +| `AUTHORIZATION_REVOKED` | 信用查询授权已撤销 | +| `AUTHORIZATION_SCOPE_MISMATCH` | 信用依赖方、智能体、验证等级、业务目的或数据项超出授权范围 | +| `AGENT_NOT_REGISTERED` | 智能体身份无法解析或无法验证 | +| `ASSOCIATION_CREDENTIAL_NOT_FOUND` | 未找到信用关联凭证 | +| `ASSOCIATION_CREDENTIAL_NOT_ACTIVE` | 信用关联凭证处于待确认、暂停、撤销或过期状态 | +| `ASSOCIATION_PROOF_INVALID` | 信用关联凭证签名、关联主体内层签名或其他关联证明验证失败 | +| `CREDIT_ASSERTION_UNAVAILABLE` | 无法取得关联信用信息验证所需的关联主体信用声明或有效性信息 | +| `CREDIT_ASSERTION_INVALID` | 关联主体信用声明无效、过期、已撤销、已纠正或已失效 | +| `MAPPING_POLICY_UNSUPPORTED` | 无法识别、不支持或无法适用映射规则标识及版本 | +| `INCONCLUSIVE` | 证据不足或必要依赖暂不可用 | +| `REVIEW_REQUIRED` | 需要人工或更高保证等级复核 | + +# TSD-CRD-AUTH：信用查询授权 +## 概述 +TSD-CRD-AUTH（Credit Query Authorization）用于规定关联主体对关联信用验证的查询授权机制，仅用于限定关联信用验证所需的信息查询和验证范围，不构成对智能体交易、支付、履约或其他商业行为的授权。 + +当信用依赖方执行关联信用信息验证时，需要向信用服务方查询或确认关联主体信用声明及关联信用映射信息的当前有效性。该过程可能涉及关联主体信用信息，因此应取得关联主体的有效信用查询授权。 + +## 参与方与前置条件 +本组件涉及以下参与方：关联主体、信用依赖方、信用服务方、信用验证服务方及平台代理主体。 + +其中： + ++ 关联主体是信用查询授权的授权人； ++ 信用依赖方是请求使用关联信用验证结果的主体； ++ 信用服务方负责维护关联主体信用声明、授权状态或相关查询能力； ++ 信用验证服务方负责在验证过程中校验授权并生成验证结果； ++ 平台代理主体是在平台代理查询模式下，经关联主体预先授权，在限定范围内执行或协助执行信用查询的主体。 + +进入本组件前，应满足以下前置条件： + ++ 信用关联凭证已签发且处于 `ACTIVE` 状态； ++ 关联主体可被验证并具备作出授权确认的能力； ++ 信用依赖方已明确关联信用验证的业务目的、请求数据项和相关业务上下文； ++ 平台代理查询模式下，平台代理主体已被关联主体明确识别和授权。 + +## 授权要素 +信用查询授权宜明确以下要素： + ++ 信用依赖方身份：允许请求或使用关联信用验证结果的信用依赖方标识； ++ 平台代理主体身份：采用平台代理查询模式时，允许代为执行查询或确认的平台代理主体标识； ++ 智能体范围：允许被验证的智能体标识或智能体范围； ++ 验证等级：本授权适用的验证等级，默认为关联信用信息验证； ++ 业务目的：关联信用验证结果允许使用的业务目的； ++ 请求数据项：允许查询、验证或返回的字段、声明或验证结论集合； ++ 有效期：信用查询授权的生效时间和失效时间； ++ 频率限制：在授权有效期内允许执行查询或验证的频率上限；平台代理查询模式下必备； ++ 结果使用限制：验证结果是否允许保存、保存期限、是否允许向其他主体传递及其他必要限制。 + +信用查询授权应与关联主体、智能体、验证等级、业务目的及请求数据项建立明确关联，不得被超出授权范围的主体、智能体、目的或数据项复用。 + +## 授权模式 +信用查询授权分为逐次授权和平台代理查询两种模式。两种模式均应满足授权范围明确、授权状态可验证、结果用途受限和授权可撤销等要求。 + +### 逐次授权 +逐次授权模式下，信用依赖方每次发起关联信用信息验证请求时，信用服务方或信用验证服务方应通知关联主体进行逐次确认。 + +逐次授权与关联信用信息验证在同次交互中完成，处理流程如下： + +1. 信用依赖方发起关联信用信息验证请求； +2. 信用服务方或信用验证服务方通知关联主体进行授权确认； +3. 关联主体确认本次查询的信用依赖方、智能体、业务目的、请求数据项及有效时间； +4. 信用验证服务方执行关联信用信息验证并返回验证结果。 + +逐次授权适用于临时查询、高敏感查询或关联主体需要逐次知情的场景。 + +每次逐次授权应具有独立授权或确认记录，并绑定信用依赖方、智能体、验证等级、业务目的、请求数据项、请求标识及有效时间。逐次授权不得被转用于其他信用依赖方、其他智能体、其他业务目的、其他请求或其他验证场景。 + +### 平台代理查询 +平台代理查询模式下，关联主体预先授权指定平台代理主体在限定范围和期限内代为执行或协助执行关联信用查询。后续关联信用信息验证可在授权范围内进行，无需关联主体逐次参与确认。 + +关联主体应明确授权以下内容： + ++ 平台代理主体； ++ 可验证的智能体范围； ++ 验证等级，默认为关联信用信息验证； ++ 信用依赖方或允许的信用依赖方范围； ++ 业务目的； ++ 请求数据项； ++ 频率限制； ++ 有效期； ++ 验证结果的使用限制。 + +频率限制应采用机器可读的计量方式表达，例如 `max_requests_per_window` 与 `window_duration`，避免不同参与方对查询次数或频率是否超出授权范围产生歧义。 + +平台代理主体每次执行或协助执行查询时，应携带本次业务上下文，并校验平台代理主体身份、授权状态、授权范围及本次请求的一致性。 + +关联主体撤销授权后，平台代理主体不得再基于该授权执行新的有效关联信用信息验证。平台代理主体不得将查询能力、验证结果或授权引用用于授权目的之外的场景，也不得向未被授权的第三方转授权或提供超出授权范围的信息。 + +## 处理要求 +信用查询授权处理应满足以下要求： + ++ 信用服务方或信用验证服务方应维护授权状态，并在每次关联信用信息验证时校验授权当前有效且覆盖本次验证请求； ++ 平台代理查询应明确平台代理主体、信用依赖方范围、智能体范围、业务目的、请求数据项、频率限制、有效期及结果使用限制；平台代理主体应在每次查询或验证时校验本次请求未超出授权范围； ++ 信用服务方应依据最小披露原则，仅返回授权范围内且满足本次业务目的所必需的关联信用信息； ++ 信用依赖方、信用服务方、信用验证服务方及平台代理主体不得将验证结果用于授权目的之外的场景，也不得向未被授权的第三方披露超出授权范围的信息。 diff --git a/governance/README.md b/governance/README.md deleted file mode 100644 index b796163..0000000 --- a/governance/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Governance records - -The public governance directory contains accepted decisions relevant to the ACT 2.1 release: - -- [ACT 2.1 finalization](decisions/act-2.1-finalization-2026-08-11.md) -- [Copyright and contribution policy](decisions/legal-and-contribution-policy.md) -- [ACT 2.1 release note](releases/2026-08-14-act-2.1-publication.md) - -Historical authoring work, internal readiness reviews, event plans, and superseded records are intentionally not part of the release tree. Protocol evolution follows [GOVERNANCE.md](../GOVERNANCE.md) and contributions follow [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/governance/decisions/act-2.1-finalization-2026-08-11.md b/governance/decisions/act-2.1-finalization-2026-08-11.md deleted file mode 100644 index 2744211..0000000 --- a/governance/decisions/act-2.1-finalization-2026-08-11.md +++ /dev/null @@ -1,7 +0,0 @@ -# ACT 2.1 finalization decision - -> Status: Accepted · 2026-08-11 - -ACT 2.1 ADD, CID, PSD and TSD semantics are final and normative. The scenario guide is informative. A402 schemas, fixtures and assertions under `code/schemas/` are non-normative implementation artifacts. Product integrations and demos do not define ACT semantics or prove conformance. - -The Chinese source files declared normative by `release-manifest.json` are the sole normative ACT 2.1 publication text in this release. English files under `docs/specification/` are official informative translations. [act-protocol.com](https://www.act-protocol.com/) is a project-information entry point; content not explicitly labeled ACT 2.1 is informative and does not override this release. Interoperability and production claims require separate evidence. diff --git a/governance/decisions/legal-and-contribution-policy.md b/governance/decisions/legal-and-contribution-policy.md deleted file mode 100644 index 8773095..0000000 --- a/governance/decisions/legal-and-contribution-policy.md +++ /dev/null @@ -1,19 +0,0 @@ -# Copyright, licensing, and contribution policy - -> Status: Accepted project policy / Non-normative -> Updated: 2026-08-11 - -This record states the publication-safe project decision. It is not legal advice. - -## Confirmed policy - -- Copyright holder: `Ant Group Co., Ltd.` -- Specifications and documentation: Creative Commons Attribution 4.0 International, subject to the directory allocation in [`LICENSE`](../../LICENSE). -- Code, JSON Schema, fixtures, scripts, and executable examples: Apache License 2.0, subject to the directory allocation in [`LICENSE`](../../LICENSE). -- Inbound contributions: no additional contributor agreement or DCO sign-off is currently required. Contributors represent that they have the right to submit the material and accepted contributions use the license applicable to the contributed file or directory. - -This removes the former signing and pull-request verification dependency. Normal review, provenance checks, third-party notice requirements, and maintainer approval still apply. - -## Publication boundary - -This decision is sufficient to describe ownership and outbound licensing in a public source snapshot. The private security reporting channel is [AntSRC](https://security.alipay.com/), operated by the Ant Group Security Emergency Response Center. diff --git a/governance/releases/2026-08-14-act-2.1-publication.md b/governance/releases/2026-08-14-act-2.1-publication.md deleted file mode 100644 index 32e8365..0000000 --- a/governance/releases/2026-08-14-act-2.1-publication.md +++ /dev/null @@ -1,9 +0,0 @@ -# ACT 2.1 release - -> Status: Final · 2026-08-14 - -ACT 2.1 publishes the four domain specifications, A402, and the informative scenario guide under `docs/`. Machine-readable A402 assets under `code/schemas/` are implementation aids. Product-neutral samples live under `code/samples/`; Alipay-specific code and validation guidance live under `integrations/alipay/`. - -The release does not claim ACT conformance, production certification or verified Alipay sandbox interoperability. Run `./tools/verify.sh` before publishing a release snapshot. - -The publication snapshot was hardened on 2026-08-15 with stable version-boundary wording, Alipay environment checks, an integration-local method identifier, safer payment-rejection recovery, and clearer demo labeling. These changes do not alter ACT 2.1 normative semantics. diff --git a/integrations/README.md b/integrations/README.md index 36fc386..e886e9f 100644 --- a/integrations/README.md +++ b/integrations/README.md @@ -1,7 +1,8 @@ # Integrations -Product integrations connect ACT semantics to an official product surface without redefining the protocol. +Reference implementation guidance and product integrations are kept outside the specification tree. They explain or connect ACT semantics without redefining the protocol. +- [TSD-CRD Reference Implementation Guide](tsd-crd/README.md) - [Alipay Reference Integration](alipay/README.md) -Each integration must identify its official product documentation, keep credentials out of the repository, distinguish local tests from real sandbox evidence, and avoid copying an official sandbox. +Reference implementation guidance must state its non-normative and non-production boundaries. Product integrations must identify their official product documentation, keep credentials out of the repository, distinguish local tests from real sandbox evidence, and avoid copying an official sandbox. diff --git a/integrations/alipay/README.md b/integrations/alipay/README.md index dc72b80..9b57a1b 100644 --- a/integrations/alipay/README.md +++ b/integrations/alipay/README.md @@ -4,6 +4,8 @@ This directory demonstrates how ACT 2.1 can be connected to the public Alipay AI | Directory | Purpose | |---|---| +| [`a402.md`](a402.md) / [`a402.en.md`](a402.en.md) | Non-normative ACT A402 integration guide used by this reference integration | +| [`commerce-payment-negotiation.md`](commerce-payment-negotiation.md) / [`commerce-payment-negotiation.en.md`](commerce-payment-negotiation.en.md) | Non-normative guide connecting commerce negotiation to payment | | [`buyer-agent/`](buyer-agent/README.md) | Preflight and handoff to the official Alipay Agent Payment installer | | [`seller-java/`](seller-java/README.md) | Java seller service using the Alipay SDK for proof verification and fulfillment confirmation | | [`validation/`](validation/README.md) | Sandbox preflight and sanitized evidence guidance | @@ -19,6 +21,8 @@ Use the official sources for current product behavior: This repository does not duplicate account opening, application registration, credential issuance, or the official sandbox. Never commit application private keys, Alipay public keys, tokens, complete payment proofs, or replayable payment URLs. +The two Markdown integration guides in this directory explain ACT semantics for implementers. They are not Alipay product documentation and do not override either the ACT domain specifications or the official Alipay sources above. + ## Boundary ACT defines cross-product roles and interaction semantics. Alipay documentation defines product fields, APIs, signing, authorization, and operational behavior. If the two layers differ, the integration must expose the mapping explicitly; product behavior must not be rewritten into the ACT specification. diff --git a/docs/specification/a402.en.md b/integrations/alipay/a402.en.md similarity index 96% rename from docs/specification/a402.en.md rename to integrations/alipay/a402.en.md index 18656cc..7db3baa 100644 --- a/docs/specification/a402.en.md +++ b/integrations/alipay/a402.en.md @@ -2,10 +2,11 @@ [中文](a402.md) | English -> **Chinese source publication: ACT 2.1 Specification / Final / Normative** +> **Status: ACT 2.1 / Final / Non-normative extracted guide** > Component: `PSD-PAY-A402` > **Version baseline: 2026-08-11 (UTC+8).** -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the translation is corrected in a subsequent repository release.** +> This guide extracts and explains `PSD-PAY-A402` from the [Payment Services Domain](../../docs/specification/payment-services.en.md). It adds no normative semantics. If it differs from that domain specification, the domain specification controls. `PSD-PAY-A402` defines a general payment-access interaction based on HTTP `402 Payment Required` among a Buyer Agent, Seller Service, and payment service provider. The Buyer Agent accesses a paid resource or service. If no valid payment proof is available, the Seller Service returns a payment requirement. After the Buyer completes a payment that satisfies the current payment-scenario constraints, it accesses the resource again with payment proof. The seller delivers the resource and completes fulfillment confirmation only after successful validation. @@ -244,7 +245,7 @@ The repository provides **Implementation Artifact / Non-normative** choices for ## 9. Related materials - Related ACT Protocol website reference: [Payment Services Domain](https://www.act-protocol.com/documentation/payment); content not labeled ACT 2.1 is not a normative source for this release -- Higher-level protocol: [ACT 2.1 Specification Overview](overview.en.md) -- Payment scenarios: [Payment Services Domain](payment-services.en.md) -- Payment-capability negotiation: [Commerce Interaction Domain](commerce-interaction.en.md) +- Higher-level protocol: [ACT 2.1 Specification Overview](../../docs/specification/overview.en.md) +- Payment scenarios: [Payment Services Domain](../../docs/specification/payment-services.en.md) +- Payment-capability negotiation: [Commerce Interaction Domain](../../docs/specification/commerce-interaction.en.md) - Non-normative machine artifacts: [A402 schemas and fixtures](../../code/schemas/a402/README.md) diff --git a/docs/specification/a402.md b/integrations/alipay/a402.md similarity index 95% rename from docs/specification/a402.md rename to integrations/alipay/a402.md index 67a5f49..3857983 100644 --- a/docs/specification/a402.md +++ b/integrations/alipay/a402.md @@ -2,9 +2,10 @@ 中文 | [English](a402.en.md) -> **状态：ACT 2.1 Specification / Final / Normative** -> 组件：`PSD-PAY-A402` +> **状态：ACT 2.1 / Final / Non-normative extracted guide** +> 组件：`PSD-PAY-A402` > **版本基线：2026-08-11（UTC+8）。** +> 本文为[支付服务域](../../docs/specification/payment-services.md)中 `PSD-PAY-A402` 的便捷提取与实现说明；不新增规范语义。若本文与支付服务域正文不一致，以支付服务域正文为准。 `PSD-PAY-A402` 定义买方智能体、卖方服务方与支付服务方之间基于 HTTP `402 Payment Required` 的通用支付接入交互：买方智能体访问付费资源或服务；卖方服务方在没有有效支付证明时返回支付诉求；买方完成符合当前支付场景约束的付款后，携带支付证明重新访问；卖方验证通过后交付资源并完成履约确认。 @@ -243,7 +244,7 @@ ACT 2.1 A402 没有规定： ## 9. 相关资料 - ACT Protocol 相关网站参考：[支付服务域](https://www.act-protocol.com/documentation/payment)；未标明 ACT 2.1 的网页内容不是本 Release 的规范来源 -- 上位协议：[ACT 2.1 规范概览](overview.md) -- 支付场景：[支付服务域](payment-services.md) -- 支付能力协商：[商业交互域](commerce-interaction.md) +- 上位协议：[ACT 2.1 规范概览](../../docs/specification/overview.md) +- 支付场景：[支付服务域](../../docs/specification/payment-services.md) +- 支付能力协商：[商业交互域](../../docs/specification/commerce-interaction.md) - 非规范性机器资产：[A402 schemas and fixtures](../../code/schemas/a402/README.md) diff --git a/integrations/alipay/buyer-agent/README.md b/integrations/alipay/buyer-agent/README.md index 0a8587a..16a3179 100644 --- a/integrations/alipay/buyer-agent/README.md +++ b/integrations/alipay/buyer-agent/README.md @@ -64,9 +64,3 @@ npm view @alipay/agent-payment@latest version dist.integrity - 留存不包含绑定码、密码或完整凭证的脱敏证据。 然后按[端到端验证清单](../validation/README.md)与收费资源完成联调。 - -## 5. 接入 Sandbox Showcase（可选） - -真实联调需要可视化时，宿主 Agent 可在官方支付工作流产生真实状态后，调用 [Buyer Event Adapter](../../../code/web-client/alipay-ai-pay-showcase/buyer-event-adapter.mjs)。Adapter 只接收脱敏的结构化状态与关联引用，不执行支付、不解析 CLI 对客文本，也不能接收完整 `Payment-Proof`。 - -运行时接线和信号格式见 [Demo 的买方 Adapter 说明](../../../code/web-client/alipay-ai-pay-showcase/README.md#买方-agent-adapter)。没有官方 Skill/CLI 的真实结果时不得提交成功信号。 diff --git a/docs/specification/commerce-payment-negotiation.en.md b/integrations/alipay/commerce-payment-negotiation.en.md similarity index 88% rename from docs/specification/commerce-payment-negotiation.en.md rename to integrations/alipay/commerce-payment-negotiation.en.md index 516fe77..f25e18e 100644 --- a/docs/specification/commerce-payment-negotiation.en.md +++ b/integrations/alipay/commerce-payment-negotiation.en.md @@ -2,13 +2,13 @@ [中文](commerce-payment-negotiation.md) | English -> **Chinese source publication: ACT 2.1 Specification / Final / Normative** -> This translation records the normative connection defined by the Chinese publication between the Commerce Interaction Domain and the Payment Services Domain. See the [Commerce Interaction Domain](commerce-interaction.en.md) for the complete CID translation. -> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the discrepancy is resolved through project governance.** +> **Status: ACT 2.1 / Final / Non-normative cross-domain guide** +> This guide summarizes the connection between the Commerce Interaction Domain and Payment Services Domain without adding normative semantics. See the complete [Commerce Interaction Domain](../../docs/specification/commerce-interaction.en.md) and [Payment Services Domain](../../docs/specification/payment-services.en.md); those domain specifications control if this guide differs. +> **Translation status: Official English translation / Informative. If a translation discrepancy is found, the Chinese ACT 2.1 publication remains controlling until the translation is corrected in a subsequent repository release.** ## 1. Purpose -`CID-PCA-NEG` determines the mutually usable payment method and access information before the parties enter payment interaction. The Payment Services Domain treats this component, or an equivalent mechanism, as a prerequisite for A402 and allows INS, DEL, and AUP to select A402, a conventional merchant-platform order-and-pay flow, or the corresponding MCP/API interface. +`CID-PCA-NEG` determines the mutually usable payment method and access information before the parties enter payment interaction. The Payment Services Domain treats this component, or an equivalent mechanism, as a prerequisite for A402 and allows INS, DEL, and AUP to select Skill, A402, a conventional merchant-platform order-and-pay flow, or the corresponding MCP/OpenAPI interface. The negotiation result in the source documentation covers at least: diff --git a/docs/specification/commerce-payment-negotiation.md b/integrations/alipay/commerce-payment-negotiation.md similarity index 90% rename from docs/specification/commerce-payment-negotiation.md rename to integrations/alipay/commerce-payment-negotiation.md index a51f138..7b8e5ea 100644 --- a/docs/specification/commerce-payment-negotiation.md +++ b/integrations/alipay/commerce-payment-negotiation.md @@ -2,12 +2,12 @@ 中文 | [English](commerce-payment-negotiation.en.md) -> **状态：ACT 2.1 Specification / Final / Normative** -> 本文记录商业交互域与支付服务域的规范连接关系；完整 CID 见[商业交互域](commerce-interaction.md)。 +> **状态：ACT 2.1 / Final / Non-normative cross-domain guide** +> 本文归纳商业交互域与支付服务域的连接关系，不新增规范语义；完整规则见[商业交互域](../../docs/specification/commerce-interaction.md)与[支付服务域](../../docs/specification/payment-services.md)，如有不一致以域正文为准。 ## 1. 作用 -`CID-PCA-NEG` 用于在进入支付交互前确定双方可使用的支付方法和接入信息。《支付服务域》把它或等价机制作为 A402 的前置能力，并允许 INS、DEL、AUP 选择 A402、传统商户平台下单支付或相应 MCP/API 接口。 +`CID-PCA-NEG` 用于在进入支付交互前确定双方可使用的支付方法和接入信息。《支付服务域》把它或等价机制作为 A402 的前置能力，并允许 INS、DEL、AUP 选择 Skill、A402、传统商户平台下单支付或相应 MCP/OpenAPI 接口。 源文档给出的协商结果至少涉及： diff --git a/integrations/alipay/seller-java/.env.example b/integrations/alipay/seller-java/.env.example index bd53a87..ad9b69a 100644 --- a/integrations/alipay/seller-java/.env.example +++ b/integrations/alipay/seller-java/.env.example @@ -18,11 +18,6 @@ ALIPAY_PORT=8080 # Optional for third-party application calls. # ALIPAY_APP_AUTH_TOKEN=replace-with-app-auth-token -# Optional local ACT Demo observer. It receives sanitized state only. -# ACT_DEMO_BRIDGE_URL=http://127.0.0.1:4173/events -# ACT_DEMO_VALIDATION_ID=E2E-YYYYMMDD-NNN -# ACT_DEMO_CORRELATION_REF=corr-sha256-redacted - # Non-normative implementation-artifact metadata. The defaults are example-only and # must not be used for a Sandbox Verified or production compatibility claim. # ACT_A402_METHOD_ID=act-integration:a402/alipay-ai-pay diff --git a/integrations/alipay/seller-java/README.md b/integrations/alipay/seller-java/README.md index 7517b58..1e9a41d 100644 --- a/integrations/alipay/seller-java/README.md +++ b/integrations/alipay/seller-java/README.md @@ -75,15 +75,9 @@ curl -i http://127.0.0.1:8080/paid-resource - 资源交付后异步执行履约确认。 - 日志和资源响应只输出脱敏 `transaction_ref`，不输出完整交易号、密钥或完整凭证。 -## 5. 可选 Sandbox Showcase 事件 - -本示例可以向本机 [Demo Bridge](../../../code/web-client/alipay-ai-pay-showcase/README.md#live-sandbox)发送脱敏状态。配置 `ACT_DEMO_BRIDGE_URL`、`ACT_DEMO_VALIDATION_ID` 和双方共享的 `ACT_DEMO_CORRELATION_REF` 后，它会观察首次资源请求、402、携 Proof 的原请求重试、验款结论、资源交付和履约确认。Buyer Adapter 必须先输出能力协商与独立商业确认，并在调用官方支付能力时输出 L1 授权、处理状态和支付结果。 - `ACT_A402_METHOD_ID` 和 `ACT_A402_METHOD_VERSION` 只用于非规范性实现产物的可信本地上下文及防重键，不会写入支付宝产品报文，也不是支付宝产品字段。仓库为这份映射固定使用集成层标识 `act-integration:a402/alipay-ai-pay` 和版本 `1.0.0`；它由本仓库维护，不声称由支付宝产品返回，也不是 ACT 2.1 的全局注册项。官方沙箱联调证据应同时记录该映射版本、仓库 Commit 和支付宝官方产品来源。 -该功能默认关闭、异步执行且失败不阻断产品链路。它不发送完整账单、Proof、交易号、订单号、`client_session`、签名或密钥。用户授权和支付处理中状态必须由实际官方 Agent Payment Adapter 提供。 - -## 6. 距离生产使用仍有差距 +## 5. 距离生产使用仍有差距 本示例有意使用内存账单和履约记录。生产使用前必须替换为持久化、原子化存储，并补充： diff --git a/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/DemoEventSink.java b/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/DemoEventSink.java deleted file mode 100644 index 4035235..0000000 --- a/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/DemoEventSink.java +++ /dev/null @@ -1,115 +0,0 @@ -package org.actprotocol.quickstart.alipay; - -import com.fasterxml.jackson.databind.ObjectMapper; - -import java.io.OutputStream; -import java.net.HttpURLConnection; -import java.net.URL; -import java.nio.charset.StandardCharsets; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.concurrent.ExecutorService; -import java.util.concurrent.Executors; -import java.util.concurrent.TimeUnit; - -interface DemoEventSink extends AutoCloseable { - void emit(String state, Map details); - - @Override - void close(); - - static DemoEventSink fromEnvironment() { - String bridgeUrl = System.getenv("ACT_DEMO_BRIDGE_URL"); - if (bridgeUrl == null || bridgeUrl.trim().isEmpty()) return noop(); - String validationId = System.getenv("ACT_DEMO_VALIDATION_ID"); - if (validationId == null || validationId.trim().isEmpty()) { - throw new IllegalArgumentException( - "ACT_DEMO_VALIDATION_ID is required when ACT_DEMO_BRIDGE_URL is set"); - } - String correlationRef = System.getenv("ACT_DEMO_CORRELATION_REF"); - if (correlationRef == null || correlationRef.trim().isEmpty()) { - throw new IllegalArgumentException( - "ACT_DEMO_CORRELATION_REF is required when ACT_DEMO_BRIDGE_URL is set"); - } - return new HttpDemoEventSink( - bridgeUrl.trim(), validationId.trim(), correlationRef.trim()); - } - - static DemoEventSink noop() { - return new DemoEventSink() { - @Override - public void emit(String state, Map details) {} - - @Override - public void close() {} - }; - } - - final class HttpDemoEventSink implements DemoEventSink { - private final String bridgeUrl; - private final String validationId; - private final String correlationRef; - private final ObjectMapper json = new ObjectMapper(); - private final ExecutorService executor = Executors.newSingleThreadExecutor(); - - HttpDemoEventSink(String bridgeUrl, String validationId, String correlationRef) { - this.bridgeUrl = bridgeUrl; - this.validationId = validationId; - this.correlationRef = correlationRef; - } - - @Override - public void emit(String state, Map details) { - Map event = new LinkedHashMap<>(); - event.put("state", state); - event.put("source", "metered-rest-provider"); - event.put("evidence_ref", validationId + "#" + state.toLowerCase()); - event.put("correlation_ref", correlationRef); - event.putAll(details); - executor.submit(() -> post(event)); - } - - private void post(Map event) { - HttpURLConnection connection = null; - try { - byte[] body = json.writeValueAsBytes(event); - connection = (HttpURLConnection) new URL(bridgeUrl).openConnection(); - connection.setRequestMethod("POST"); - connection.setConnectTimeout(500); - connection.setReadTimeout(1000); - connection.setDoOutput(true); - connection.setRequestProperty("Content-Type", "application/json"); - connection.setFixedLengthStreamingMode(body.length); - try (OutputStream output = connection.getOutputStream()) { - output.write(body); - } - int status = connection.getResponseCode(); - if (status < 200 || status >= 300) { - System.err.println("ACT demo event rejected: " + stateOf(event) + " HTTP " + status); - } - } catch (Exception exception) { - System.err.println( - "ACT demo event unavailable: " + stateOf(event) + " " - + exception.getClass().getSimpleName()); - } finally { - if (connection != null) connection.disconnect(); - } - } - - private static String stateOf(Map event) { - Object state = event.get("state"); - return state == null ? "unknown" : String.valueOf(state); - } - - @Override - public void close() { - executor.shutdown(); - try { - if (!executor.awaitTermination(2, TimeUnit.SECONDS)) executor.shutdownNow(); - } catch (InterruptedException exception) { - executor.shutdownNow(); - Thread.currentThread().interrupt(); - } - } - } -} diff --git a/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/Main.java b/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/Main.java index 724c933..d996756 100644 --- a/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/Main.java +++ b/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/Main.java @@ -9,8 +9,7 @@ public static void main(String[] args) throws Exception { PaidResourceServer server = new PaidResourceServer( config, gateway, - new BillSigner.Rsa2(config.privateKey), - DemoEventSink.fromEnvironment()); + new BillSigner.Rsa2(config.privateKey)); Runtime.getRuntime().addShutdownHook(new Thread(server::close)); server.start(); System.out.println("ACT Alipay paid resource listening on http://localhost:" diff --git a/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/PaidResourceServer.java b/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/PaidResourceServer.java index a85f61a..ccffad7 100644 --- a/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/PaidResourceServer.java +++ b/integrations/alipay/seller-java/src/main/java/org/actprotocol/quickstart/alipay/PaidResourceServer.java @@ -27,7 +27,6 @@ final class PaidResourceServer implements AutoCloseable { private final Config config; private final AlipayGateway gateway; private final BillSigner signer; - private final DemoEventSink demoEvents; private final A402Codec codec = new A402Codec(); private final ObjectMapper json = new ObjectMapper(); private final Map bills = new ConcurrentHashMap<>(); @@ -40,18 +39,9 @@ final class PaidResourceServer implements AutoCloseable { private HttpServer server; PaidResourceServer(Config config, AlipayGateway gateway, BillSigner signer) { - this(config, gateway, signer, DemoEventSink.noop()); - } - - PaidResourceServer( - Config config, - AlipayGateway gateway, - BillSigner signer, - DemoEventSink demoEvents) { this.config = config; this.gateway = gateway; this.signer = signer; - this.demoEvents = demoEvents; } void start() throws IOException { @@ -85,39 +75,20 @@ private void paidResource(HttpExchange exchange) throws IOException { String requestFingerprint = requestFingerprint(exchange); String requestRef = digestRef("request|" + requestFingerprint); if (proofHeader == null || proofHeader.trim().isEmpty()) { - demoEvents.emit("RESOURCE_REQUESTED", mapOf( - "resource_id", config.resourceId, - "goods_name", config.goodsName, - "http_method", exchange.getRequestMethod(), - "request_ref", requestRef)); paymentRequired(exchange, "Payment Needed", requestFingerprint, requestRef); return; } try { - demoEvents.emit("RESOURCE_REQUEST_RETRIED", mapOf( - "resource_id", config.resourceId, - "http_method", exchange.getRequestMethod(), - "request_ref", requestRef, - "request_fingerprint", requestFingerprint, - "result_summary", "original resource request retried with proof reference")); Models.PaymentProof proof = codec.decodePaymentProof(proofHeader); Models.VerificationResult verified = gateway.verify(proof); Models.BillRecord bill = verified.outTradeNo == null ? null : bills.get(verified.outTradeNo); if (!verified.active) { - demoEvents.emit("PROOF_REJECTED", mapOf( - "resource_id", config.resourceId, - "recovery_action", "DO_NOT_DELIVER · REISSUE_AFTER_VERIFIED_INACTIVE", - "result_summary", "Payment proof is inactive")); paymentRequired(exchange, "Payment proof is inactive", requestFingerprint, requestRef); return; } String rejection = rejectionReason(proof, verified, bill, requestFingerprint); if (rejection != null) { - demoEvents.emit("PROOF_REJECTED", mapOf( - "resource_id", config.resourceId, - "recovery_action", "DO_NOT_DELIVER · RECONCILE_BEFORE_NEW_PAYMENT", - "result_summary", rejection)); proofRejected(exchange, rejection); return; } @@ -139,52 +110,20 @@ private void paidResource(HttpExchange exchange) throws IOException { } String transactionRef = digestRef("trade|" + verified.tradeNo); - String deliveryRef = digestRef("delivery|" + deliveryKey); - demoEvents.emit("PAYMENT_VERIFIED", mapOf( - "amount", verified.amount, - "currency", config.currency, - "resource_id", verified.resourceId, - "order_ref", bill.orderRef, - "request_fingerprint", bill.requestFingerprint, - "transaction_ref", transactionRef, - "validation_mapping", "ACT 2.1 evidence <- Alipay payment.verify result", - "result_summary", "active and merchant bill checks passed")); sendJson(exchange, 200, mapOf( "resource_id", config.resourceId, "content", "This resource was released after Alipay payment verification.", "transaction_ref", transactionRef, "idempotent_replay", !firstDelivery)); - demoEvents.emit("RESOURCE_DELIVERED", mapOf( - "resource_id", verified.resourceId, - "order_ref", bill.orderRef, - "request_fingerprint", bill.requestFingerprint, - "transaction_ref", transactionRef, - "delivery_ref", deliveryRef, - "idempotent_replay", !firstDelivery, - "payment_action", firstDelivery ? "ORIGINAL_PAYMENT" : "NO_NEW_PAYMENT", - "delivery_action", firstDelivery ? "COMMIT_DELIVERY" : "RETURN_PRIOR_RESULT", - "fulfillment_action", firstDelivery ? "SCHEDULE_CONFIRMATION" : "NOT_REPEATED", - "result_summary", firstDelivery - ? "paid resource delivered" - : "idempotent resource response")); - if (firstDelivery) confirmFulfillmentAsync( - verified.tradeNo, transactionRef, deliveryRef, bill.orderRef); + if (firstDelivery) confirmFulfillmentAsync(verified.tradeNo); } catch (IllegalArgumentException exception) { - demoEvents.emit("PROOF_REJECTED", mapOf( - "resource_id", config.resourceId, - "recovery_action", "DO_NOT_DELIVER · REQUEST_VALID_PROOF", - "result_summary", "invalid proof encoding or shape")); sendJson(exchange, 400, mapOf( "error", "invalid_payment_proof", "message", "Invalid Payment-Proof", "recovery_action", "request_valid_proof")); } catch (Exception exception) { System.err.println("payment verification unavailable: " + safeMessage(exception)); - demoEvents.emit("VERIFICATION_UNAVAILABLE", mapOf( - "resource_id", config.resourceId, - "recovery_action", "RETRY_SAME_VERIFICATION · DO_NOT_DELIVER", - "result_summary", "official verification temporarily unavailable")); exchange.getResponseHeaders().set("Retry-After", "3"); sendJson(exchange, 503, mapOf("error", "payment_verification_unavailable")); } @@ -218,23 +157,12 @@ private void paymentRequired( String requestRef) throws IOException { try { Models.BillRecord record = currentOrNewBill(requestFingerprint, requestRef); - Models.PaymentNeeded bill = record.value; String encoded = codec.encodePaymentNeeded(record.value); exchange.getResponseHeaders().set("Payment-Needed", encoded); sendJson(exchange, 402, mapOf( "error", "Payment Needed", "message", message, "resourceId", config.resourceId)); - demoEvents.emit("PAYMENT_REQUIRED", mapOf( - "amount", bill.protocol.amount, - "currency", bill.protocol.currency, - "resource_id", bill.protocol.resourceId, - "request_ref", record.requestRef, - "request_fingerprint", record.requestFingerprint, - "order_ref", record.orderRef, - "profile_mapping", "ALIPAY_PRODUCT_PAYLOAD_TO_ACT_2_1_EVIDENCE", - "goods_name", bill.method.goodsName, - "seller_name", bill.method.sellerName)); } catch (Exception exception) { System.err.println("cannot create payment requirement: " + safeMessage(exception)); sendJson(exchange, 500, mapOf("error", "payment_requirement_unavailable")); @@ -284,23 +212,11 @@ private Models.BillRecord newBill(String requestFingerprint, String requestRef) return record; } - private void confirmFulfillmentAsync( - String tradeNo, - String transactionRef, - String deliveryRef, - String orderRef) { + private void confirmFulfillmentAsync(String tradeNo) { fulfillmentExecutor.submit(() -> { try { gateway.confirmFulfillment(tradeNo); System.out.println("fulfillment confirmed for trade " + redact(tradeNo)); - demoEvents.emit("FULFILLMENT_CONFIRMED", mapOf( - "resource_id", config.resourceId, - "order_ref", orderRef, - "transaction_ref", transactionRef, - "delivery_ref", deliveryRef, - "fulfillment_ref", digestRef("fulfillment|" + tradeNo), - "product_fulfillment_status", "CONFIRMED", - "result_summary", "seller fulfillment confirmed")); } catch (Exception exception) { // A production implementation must persist this job and retry with backoff. System.err.println( @@ -383,6 +299,5 @@ public void close() { if (server != null) server.stop(0); serverExecutor.shutdownNow(); fulfillmentExecutor.shutdownNow(); - demoEvents.close(); } } diff --git a/integrations/alipay/validation/README.md b/integrations/alipay/validation/README.md index 0bc953a..3d011cd 100644 --- a/integrations/alipay/validation/README.md +++ b/integrations/alipay/validation/README.md @@ -56,7 +56,3 @@ cd integrations/alipay/seller-java - 未解决问题属于 Protocol、Product、Binding 还是 Implementation。 不得记录账号、密钥、绑定码、支付密码、完整 Proof、`client_session` 或可重放请求。 - -Demo 的脱敏事件格式见 [Demo 事件格式](../../../code/web-client/alipay-ai-pay-showcase/event-format.md)。Replay 只能来自已通过的官网沙箱链路。 - -完整 Live 链路通过后，使用 Demo Bridge 的 `GET /events/export` 导出 NDJSON。人工完成脱敏复核后，再通过 `prepare-replay.mjs` 添加原验证编号和复核记录；未完成链路、未明确确认脱敏或包含明显敏感文本的文件不能生成合法 Replay。 diff --git a/integrations/tsd-crd/README.md b/integrations/tsd-crd/README.md new file mode 100644 index 0000000..cba3432 --- /dev/null +++ b/integrations/tsd-crd/README.md @@ -0,0 +1,28 @@ +# TSD-CRD Reference Implementation Guide + +本目录集中说明 ACT 2.1 TSD-CRD（信用关联）参考实现的实现基线、架构、运行方式、安全边界和可选扩展。 + +> **状态：Implementation guidance / Informative / Non-production。** +> TSD-CRD 是 ACT 2.1 的规范性协议内容；本目录只解释仓库中的 `reference-v1` Profile 和 Reference Implementation，不增加、替代或修改 ACT 2.1 的协议要求。 + +## 权威关系 + +| 层次 | 入口 | 定位 | +| --- | --- | --- | +| ACT 2.1 TSD-CRD 协议正文 | [信任服务域](../../docs/specification/trust-services.md) | 规范性协议要求 | +| `reference-v1` | [机器可读 Profile](../../code/schemas/tsd-crd/reference-v1/README.md) | 可选的机器表达和互操作 Profile | +| Reference Implementation | [可运行实现](../../code/samples/tsd-crd-reference/README.md) | 非生产参考实现、Sandbox、CLI 和测试 | + +发生冲突时，以 ACT 2.1 信任服务域正文为准。采用 `reference-v1` 的实现还必须满足该 Profile 的字段、签名投影和固定向量约束。 + +## 文档导航 + +- [参考实现基线](implementation-baseline.md)：协议正文、机器 Profile 和参考实现之间的边界。 +- [架构说明](architecture.md)：代码分层、组件映射、依赖方向和可替换能力。 +- [快速开始](quickstart.md)：从仓库根目录运行测试、Demo、Sandbox 和基础一致性检查。 +- [安全模型](security-model.md)：参考实现的信任边界、威胁控制和生产实现责任。 +- [可选 Agent 密钥持有证明扩展](agent-key-possession-extension.md)：尚未纳入 P0 或基础一致性检查的扩展设计。 + +## 范围边界 + +这些文档和参考实现不提供真实身份核验、真实信用服务、生产密钥管理、持久化、高可用或完整 ACT 2.1 Conformance 证明。验证结果只能作为业务输入，不直接构成交易准入、授信、支付批准或风险判断。 diff --git a/code/samples/tsd-crd-reference/docs/agent-key-possession-extension.md b/integrations/tsd-crd/agent-key-possession-extension.md similarity index 96% rename from code/samples/tsd-crd-reference/docs/agent-key-possession-extension.md rename to integrations/tsd-crd/agent-key-possession-extension.md index cc567a2..6ef6b11 100644 --- a/code/samples/tsd-crd-reference/docs/agent-key-possession-extension.md +++ b/integrations/tsd-crd/agent-key-possession-extension.md @@ -1,5 +1,7 @@ # 可选 Agent 密钥持有证明扩展设计说明 +> **状态：Optional extension design / Informative / Not implemented。** + ## 定位 本扩展用于证明请求方持有某个 Agent 公钥对应的私钥。它是参考实现的可选增强，不属于： diff --git a/code/samples/tsd-crd-reference/docs/architecture.md b/integrations/tsd-crd/architecture.md similarity index 80% rename from code/samples/tsd-crd-reference/docs/architecture.md rename to integrations/tsd-crd/architecture.md index 2e8025c..c39411b 100644 --- a/code/samples/tsd-crd-reference/docs/architecture.md +++ b/integrations/tsd-crd/architecture.md @@ -1,5 +1,7 @@ # 架构说明 +> 本文说明 `code/samples/tsd-crd-reference/` 的参考实现架构，不规定 ACT 2.1 的唯一实现方式。 + ## 目标 架构服务于三个目标： @@ -21,20 +23,20 @@ flowchart TD VECTORS["Test Vectors"] --> CONF ``` -依赖方向从入口指向用例和核心。`src/core` 不依赖 HTTP、CLI、文件系统或具体确认服务。 +依赖方向从入口指向用例和核心。`code/samples/tsd-crd-reference/src/core` 不依赖 HTTP、CLI、文件系统或具体确认服务。 ## 目录职责 | 目录 | 职责 | | --- | --- | -| `../../schemas/tsd-crd/reference-v1` | 非规范性 Schema、OpenAPI、标准报文和测试向量 | -| `src/core` | 协议对象、不变量、签名投影、状态机、授权和验证规则 | -| `src/application` | ASC、MAP、LCM、AUTH、VER 用例编排 | -| `src/adapters` | 内存存储、Mock 身份确认、虚构信用和固定映射 | -| `src/http` | 本地 Sandbox HTTP 入口 | -| `src/cli` | Demo 和命令行入口 | -| `src/conformance` | 测试向量加载、执行和报告 | -| `../../schemas/tsd-crd/reference-v1/test-vectors` | 与实现无关的正常和异常向量 | +| `code/schemas/tsd-crd/reference-v1` | Schema、OpenAPI、标准报文和测试向量 | +| `code/samples/tsd-crd-reference/src/core` | 协议对象、不变量、签名投影、状态机、授权和验证规则 | +| `code/samples/tsd-crd-reference/src/application` | ASC、MAP、LCM、AUTH、VER 用例编排 | +| `code/samples/tsd-crd-reference/src/adapters` | 内存存储、Mock 身份确认、虚构信用和固定映射 | +| `code/samples/tsd-crd-reference/src/http` | 本地 Sandbox HTTP 入口 | +| `code/samples/tsd-crd-reference/src/cli` | Demo 和命令行入口 | +| `code/samples/tsd-crd-reference/src/conformance` | 测试向量加载、执行和报告 | +| `code/schemas/tsd-crd/reference-v1/test-vectors` | 与实现无关的正常和异常向量 | ## 五组件映射 diff --git a/code/samples/tsd-crd-reference/docs/protocol-baseline.md b/integrations/tsd-crd/implementation-baseline.md similarity index 90% rename from code/samples/tsd-crd-reference/docs/protocol-baseline.md rename to integrations/tsd-crd/implementation-baseline.md index 00ab525..37e473f 100644 --- a/code/samples/tsd-crd-reference/docs/protocol-baseline.md +++ b/integrations/tsd-crd/implementation-baseline.md @@ -1,15 +1,18 @@ -# 协议基线 +# TSD-CRD Reference Implementation 基线 + +> **定位：Implementation guidance / Informative。** +> TSD-CRD 是 ACT 2.1 的规范性协议内容；本文说明仓库参考实现如何对应协议正文和 `reference-v1`，不构成第二份协议正文。 ## 当前基线 -本目录实现 ACT 2.1 信任服务域中的[信用关联子篇](../../../../docs/specification/trust-services.md)。 +[`code/samples/tsd-crd-reference/`](../../code/samples/tsd-crd-reference/README.md) 实现 ACT 2.1 信任服务域中的[信用关联子篇](../../docs/specification/trust-services.md)。 实现分为三层： | 层次 | 作用 | 是否规范性来源 | | --- | --- | --- | | ACT 2.1 TSD-CRD 正文 | 定义参与方、业务语义、对象、流程和约束 | 是 | -| [`reference-v1`](../../../schemas/tsd-crd/reference-v1/README.md) | 补充 JSON 字段、格式、算法和 HTTP 表达 | 否，除非实现明确采用该 Profile | +| [`reference-v1`](../../code/schemas/tsd-crd/reference-v1/README.md) | 补充 JSON 字段、格式、算法和 HTTP 表达 | 否，除非实现明确采用该 Profile | | 参考实现 | 提供可运行的 Sandbox、CLI 和测试 | 否 | 发生冲突时，以 ACT 2.1 正文为准。实现或 Profile 中新增的字段和流程不能反向解释为协议要求，基础一致性测试通过也不构成 ACT 2.1 全量 Conformance 声明。 diff --git a/code/samples/tsd-crd-reference/docs/quickstart.md b/integrations/tsd-crd/quickstart.md similarity index 76% rename from code/samples/tsd-crd-reference/docs/quickstart.md rename to integrations/tsd-crd/quickstart.md index 2700d6c..671afea 100644 --- a/code/samples/tsd-crd-reference/docs/quickstart.md +++ b/integrations/tsd-crd/quickstart.md @@ -1,5 +1,7 @@ # 快速开始 +除非另有说明，以下命令均从 `act-protocol/` 仓库根目录执行。 + ## 环境 - Node.js `>= 22.18` @@ -9,13 +11,13 @@ ```bash node --version -npm test +npm --prefix code/samples/tsd-crd-reference test ``` ## 运行 Demo ```bash -npm run demo +npm --prefix code/samples/tsd-crd-reference run demo ``` 默认 Demo 使用 `ATTESTED_CONFIRMATION`： @@ -33,17 +35,17 @@ npm run demo ## 启动 Sandbox ```bash -npm run start +npm --prefix code/samples/tsd-crd-reference run start ``` -Sandbox 只监听本地开发接口，具体路径以非规范性 [OpenAPI](../../../schemas/tsd-crd/reference-v1/openapi/openapi.yaml) 为准。 +Sandbox 只监听本地开发接口，具体路径以 `reference-v1` [OpenAPI](../../code/schemas/tsd-crd/reference-v1/openapi/openapi.yaml) 为准。 创建一笔 ATTESTED 申请： ```bash curl -sS http://127.0.0.1:8787/v1/association-applications \ -H 'content-type: application/json' \ - --data-binary @examples/association-application-sandbox.json + --data-binary @code/samples/tsd-crd-reference/examples/association-application-sandbox.json ``` 确认并签发凭证： @@ -71,20 +73,20 @@ curl -sS http://127.0.0.1:8787/v1/association-applications/association-applicati ## 运行一致性测试 ```bash -npm run conformance +npm --prefix code/samples/tsd-crd-reference run conformance ``` Runner 读取： -- [`reference-v1/test-vectors/valid/`](../../../schemas/tsd-crd/reference-v1/test-vectors/valid/) 中的正常向量。 -- [`reference-v1/test-vectors/invalid/`](../../../schemas/tsd-crd/reference-v1/test-vectors/invalid/) 中的篡改、过期、撤销和越权向量。 +- [`reference-v1/test-vectors/valid/`](../../code/schemas/tsd-crd/reference-v1/test-vectors/valid/) 中的正常向量。 +- [`reference-v1/test-vectors/invalid/`](../../code/schemas/tsd-crd/reference-v1/test-vectors/invalid/) 中的篡改、过期、撤销和越权向量。 Agent 密钥持有扩展不计入基础一致性结果。 ## 运行全部测试 ```bash -npm test +npm --prefix code/samples/tsd-crd-reference test ``` 测试失败时先检查： diff --git a/code/samples/tsd-crd-reference/docs/security-model.md b/integrations/tsd-crd/security-model.md similarity index 95% rename from code/samples/tsd-crd-reference/docs/security-model.md rename to integrations/tsd-crd/security-model.md index 759ebbf..a884b86 100644 --- a/code/samples/tsd-crd-reference/docs/security-model.md +++ b/integrations/tsd-crd/security-model.md @@ -1,8 +1,10 @@ # 安全模型 +> 本文说明 `code/samples/tsd-crd-reference/` 的参考实现安全边界，不替代 ACT 2.1 协议正文、生产系统威胁建模、安全评审或合规评估。 + ## 适用范围 -本文说明参考实现的信任边界和已知限制。它不替代生产系统的威胁建模、安全评审或合规评估。 +本文覆盖参考实现的信任边界和已知限制。 ## 参与方 diff --git a/release-manifest.json b/release-manifest.json index 40d8854..e7723f6 100644 --- a/release-manifest.json +++ b/release-manifest.json @@ -3,7 +3,7 @@ "release": "ACT 2.1", "release_date": "2026-08-14", "specification_finalized": "2026-08-11", - "updated": "2026-08-25", + "updated": "2026-09-03", "languages": { "normative": "zh-CN", "official_informative_translations": ["en"] @@ -14,17 +14,17 @@ "commerce-interaction-zh": {"path": "docs/specification/commerce-interaction.md", "status": "final", "normative": true}, "payment-services-zh": {"path": "docs/specification/payment-services.md", "status": "final", "normative": true}, "trust-services-zh": {"path": "docs/specification/trust-services.md", "status": "final", "normative": true}, - "a402-zh": {"path": "docs/specification/a402.md", "status": "final", "normative": true}, - "commerce-payment-negotiation-zh": {"path": "docs/specification/commerce-payment-negotiation.md", "status": "final", "normative": true}, + "scenarios-zh": {"path": "docs/specification/scenarios.md", "status": "informative", "normative": false}, + "a402-zh": {"path": "integrations/alipay/a402.md", "status": "non-normative-extracted-guide", "normative": false}, + "commerce-payment-negotiation-zh": {"path": "integrations/alipay/commerce-payment-negotiation.md", "status": "non-normative-cross-domain-guide", "normative": false}, "specification-overview-en": {"path": "docs/specification/overview.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/overview.md"}, "authorization-delegation-en": {"path": "docs/specification/authorization-delegation.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/authorization-delegation.md"}, "commerce-interaction-en": {"path": "docs/specification/commerce-interaction.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/commerce-interaction.md"}, "payment-services-en": {"path": "docs/specification/payment-services.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/payment-services.md"}, "trust-services-en": {"path": "docs/specification/trust-services.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/trust-services.md"}, - "a402-en": {"path": "docs/specification/a402.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/a402.md"}, - "commerce-payment-negotiation-en": {"path": "docs/specification/commerce-payment-negotiation.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/commerce-payment-negotiation.md"}, - "scenarios-zh": {"path": "docs/flows/scenarios.md", "status": "informative", "normative": false}, - "scenarios-en": {"path": "docs/flows/scenarios.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/flows/scenarios.md"}, + "scenarios-en": {"path": "docs/specification/scenarios.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "docs/specification/scenarios.md"}, + "a402-en": {"path": "integrations/alipay/a402.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "integrations/alipay/a402.md"}, + "commerce-payment-negotiation-en": {"path": "integrations/alipay/commerce-payment-negotiation.en.md", "status": "official-informative-translation", "normative": false, "translation_of": "integrations/alipay/commerce-payment-negotiation.md"}, "a402-machine-artifacts": {"path": "code/schemas/a402/README.md", "status": "implementation-artifact", "normative": false}, "tsd-crd-reference-profile": {"path": "code/schemas/tsd-crd/reference-v1/README.md", "status": "implementation-artifact", "normative": false}, "local-a402-sample": {"path": "code/samples/local-a402/README.md", "status": "sample", "normative": false}, diff --git a/tools/quality/check_repository.py b/tools/quality/check_repository.py index 2e3676b..ee2bf14 100644 --- a/tools/quality/check_repository.py +++ b/tools/quality/check_repository.py @@ -61,10 +61,11 @@ def structure_errors() -> list[str]: "docs/specification/commerce-interaction.md", "docs/specification/commerce-interaction.en.md", "docs/specification/payment-services.md", "docs/specification/payment-services.en.md", "docs/specification/trust-services.md", "docs/specification/trust-services.en.md", - "docs/specification/a402.md", "docs/specification/a402.en.md", - "docs/specification/commerce-payment-negotiation.md", - "docs/specification/commerce-payment-negotiation.en.md", - "docs/flows/scenarios.md", "docs/flows/scenarios.en.md", + "docs/specification/scenarios.md", "docs/specification/scenarios.en.md", + "integrations/alipay/a402.md", "integrations/alipay/a402.en.md", + "integrations/alipay/commerce-payment-negotiation.md", + "integrations/alipay/commerce-payment-negotiation.en.md", + "integrations/tsd-crd/README.md", "code/schemas/a402/README.md", "code/schemas/a402/payment-needed.schema.json", "code/schemas/tsd-crd/reference-v1/README.md", "code/schemas/tsd-crd/reference-v1/schemas/association-credential.schema.json", @@ -82,7 +83,8 @@ def structure_errors() -> list[str]: forbidden = [ "specs", "code/examples", "integrations/profiles", "integrations/bindings", "docs/architecture", "docs/getting-started", "docs/project", - "governance/audits", "governance/internal", + "code/samples/tsd-crd-reference/docs", + "docs/reference-implementations/tsd-crd", ] errors += [ f"obsolete release path contains publishable files: {p}" @@ -141,8 +143,6 @@ def manifest_errors() -> list[str]: "docs/specification/commerce-interaction.md", "docs/specification/payment-services.md", "docs/specification/trust-services.md", - "docs/specification/a402.md", - "docs/specification/commerce-payment-negotiation.md", } declared_normative = { component.get("path") @@ -163,21 +163,16 @@ def translation_errors() -> list[str]: ("docs/specification/commerce-interaction.md", "docs/specification/commerce-interaction.en.md"), ("docs/specification/payment-services.md", "docs/specification/payment-services.en.md"), ("docs/specification/trust-services.md", "docs/specification/trust-services.en.md"), - ("docs/specification/a402.md", "docs/specification/a402.en.md"), + ("docs/specification/scenarios.md", "docs/specification/scenarios.en.md"), + ("integrations/alipay/a402.md", "integrations/alipay/a402.en.md"), ( - "docs/specification/commerce-payment-negotiation.md", - "docs/specification/commerce-payment-negotiation.en.md", + "integrations/alipay/commerce-payment-negotiation.md", + "integrations/alipay/commerce-payment-negotiation.en.md", ), - ("docs/flows/scenarios.md", "docs/flows/scenarios.en.md"), ] - translation_marker = "Translation status: Official English translation / Informative" for source_name, translation_name in pairs: source = (ROOT / source_name).read_text(encoding="utf-8") translation = (ROOT / translation_name).read_text(encoding="utf-8") - if translation_marker not in translation: - errors.append(f"{translation_name}: missing official informative translation marker") - if "Chinese ACT 2.1 publication remains controlling" not in translation: - errors.append(f"{translation_name}: missing Chinese controlling-language notice") source_headings = HEADING.findall(source) translation_headings = HEADING.findall(translation) if source_headings != translation_headings: @@ -210,7 +205,7 @@ def release_wording_errors() -> list[str]: r"public protocol entry point[^\n]*(?:authority|controls)|官网同步完成前)", re.I ), } - checked = [p for p in files("*.md") if "governance/decisions" not in p.as_posix()] + checked = files("*.md") checked += files("*.json") for path in checked: text = path.read_text(encoding="utf-8") diff --git a/tools/quality/create_public_snapshot.py b/tools/quality/create_public_snapshot.py index 8a415df..249db80 100644 --- a/tools/quality/create_public_snapshot.py +++ b/tools/quality/create_public_snapshot.py @@ -12,7 +12,6 @@ ROOT = Path(__file__).resolve().parents[2] -PRIVATE_PREFIXES = ("governance/internal/",) SENSITIVE_NAMES = {".env", "id_rsa", "id_ed25519"} SENSITIVE_SUFFIXES = {".key", ".p12", ".pfx"} @@ -29,9 +28,6 @@ def repository_paths() -> list[Path]: if not raw: continue relative = Path(raw.decode("utf-8")) - portable = relative.as_posix() - if portable.startswith(PRIVATE_PREFIXES): - continue source = ROOT / relative if source.is_file() or source.is_symlink(): paths.append(relative) @@ -61,8 +57,6 @@ def build_snapshot(destination: Path) -> int: target.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(source, target, follow_symlinks=False) - if (destination / "governance/internal").exists(): - raise RuntimeError("private governance material leaked into public snapshot") return len(paths)