ap2_mandate_verifier 0.8.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b6973632ca480195ff57ea153dba920906287f8064357e0cd1069e75b2da58e1
4
- data.tar.gz: 3f20dac53518631270fb9c9ff7e84dc0e9f8ae96cb78189431cb7f8d20e4f99f
3
+ metadata.gz: 9c57f86a63b5438f3160544896ad16f2376372a60fe12368432ab70244b1a612
4
+ data.tar.gz: 4257f8474101c2f7de0876c963b7205d2be5da17cd22d70917cee56efc155639
5
5
  SHA512:
6
- metadata.gz: 1be1321379cc84f7a517a546486d146eee9b978f8139ea9940c894f46661b1d4fa3266e8a0d90c454b00cae0c19869885905470c14e38a141e06e5aa577fbfd4
7
- data.tar.gz: 2da4d81e6fbcfdd4bd03bad264fe150e31974671e536fdfa6e62387ec4d934d8c57c3dc7294a37981d930d018a4bf5477efaf77d3c20ab654e7fafd9e9cc0bce
6
+ metadata.gz: 5611e738d912999083d6b440c0126e8e3166a079de2378dbe02a5cd5968a1e66c2ef395409587853e0576005050e0078e86ba0093956c22e442e400732743ba9
7
+ data.tar.gz: 646096deea75cb2154b5258c796f5f75338a67d36fc4944cd465148f41ea87faf517ddd02d4e04478b2054ea4caa8b8789cac50a2d8afc23d7efd4ee1b307709
data/README.ja.md CHANGED
@@ -1,20 +1,28 @@
1
- # AP2 Mandate Verifier — 0.7.0
1
+ # AP2 Mandate Verifier — Checkout委任のRuby SDK
2
2
 
3
3
  [English](README.md)
4
4
 
5
- ## 0.8.0候補:条件付き購入委任(未公開)
5
+ **公開済み安定版は0.8.0です。1.0.0は準備中の未公開候補です。**
6
+
7
+ 1.0.0では、既存のDirectと条件付きCheckoutの公開API・保守契約を明確にします。
8
+ 0.8.0の引数・既定値・profile・結果の意味・保存形式を維持します。
9
+ 以下の公開版インストール手順は引き続き0.8.0です。
10
+ [公開API契約](docs/PUBLIC_API.md)、[保守方針](docs/POST_RELEASE_MAINTENANCE.md)、
11
+ [候補版の準備状況](docs/RELEASE_100_CANDIDATE.md)を参照してください。
12
+
13
+ ## 条件付き購入委任 — 0.8.0公開済み
6
14
 
7
15
  `ConditionalCheckout.issue_open`、`.issue_closed`、`.present` を追加します。
8
16
  A/Bから1個とCを2個という条件を承認サービスが登録Agent鍵へOpenとして発行し、
9
17
  Agentが条件に合う販売者署名CheckoutをClosedにします。既存 `InputBuilder.verify` と
10
18
  `CheckoutReceipt.sign/verify` へ接続します。全候補開示の複数商品profileを維持し、
11
19
  Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CONDITIONAL_CHECKOUT.md)、
12
- [公開判断資料](docs/RELEASE_080_CANDIDATE.md)を参照してください。
20
+ [Release実行例](docs/RELEASE_080.md)・[公開照合記録](docs/POST_RELEASE_080.md)を参照してください。
13
21
 
14
- 正式対応MRI 3.4.12/4.0.9で、候補manifestに対応するローカルGemを取得した後:
22
+ 正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
15
23
 
16
24
  ```sh
17
- gem install --local ./ap2_mandate_verifier-0.8.0.gem
25
+ gem install ap2_mandate_verifier --version 0.8.0
18
26
  ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.8.0").full_gem_path')/examples/conditional_checkout.rb"
19
27
  ```
20
28
 
@@ -22,9 +30,9 @@ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0
22
30
  3明細・候補選択・異なる要件数量・同一商品の別行からSuccess/Error Receiptまで動きます。
23
31
  Success後は消費済み、Error後は再提示方針を再判断、Receipt未到着や結果不明は保留です。
24
32
  本人認証・同意・購買権限・信頼先登録・永続的な重複防止・注文や決済の実行はアプリ責務です。
25
- 0.7.0利用者の移行は不要で、既存既定値・保存形式を維持します。0.8.0は未公開候補です。
33
+ 0.7.0利用者の移行は不要で、既存既定値・保存形式を維持します。0.8.0は公開済みです。
26
34
 
27
- 公開済み安定版は **0.7.0** です。Direct購入側の発行・提示・販売者検証・Receipt確認を追加し、1販売者・1〜8明細・複数商品に一貫対応します。既存Open→Closedの契約は維持します。[公開記録](docs/PROJECT_STATUS.md#070-publication)を参照してください。
35
+ 公開済み安定版は **0.8.0** です。Open発行・Agent Closed生成/提示を完全検証とReceiptへ接続し、1販売者・1〜8明細・複数商品・数量・候補選択を扱います。既存DirectとOpen→Closedの契約を維持します。[公開記録](docs/PROJECT_STATUS.md#080-publication)を参照してください。
28
36
 
29
37
  ## 複数商品と数量
30
38
 
@@ -38,20 +46,20 @@ Rubyで購入委任データを検証する、AP2の固定profile向けGemです
38
46
 
39
47
  ## ローカルデモを試す
40
48
 
41
- [把握しやすいRailsデモ](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)は、公開済み0.7.0とInputBuilderを通常経路で使います。Docker手順ならホストへのRuby導入は不要です。正常・改ざん・期限切れのstatus/code・診断・Evidence有無に加え、複数商品と数量違い、後続明細の数量不足拒否、真正な成功/拒否Receiptも試せます。ローカル専用で、実Challenge発行・nonce消費・購入実行は行いません。
49
+ [Railsデモ](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)は公開済み0.8.0とInputBuilderを通常経路で使います。既存のOpen→Agent Closed検証・複数商品・Success/Error Receipt画面を維持し、条件承認/発行UIは実装していません。その一連の処理は上記Ruby単体例を使ってください。DockerならホストRuby導入は不要で、実Challenge発行・nonce消費・購入や決済は行いません。
42
50
 
43
51
  ## インストール
44
52
 
45
53
  正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
46
54
 
47
55
  ```sh
48
- gem install ap2_mandate_verifier --version 0.7.0
56
+ gem install ap2_mandate_verifier --version 0.8.0
49
57
  ```
50
58
 
51
59
  BundlerのGemfile:
52
60
 
53
61
  ```ruby
54
- gem "ap2_mandate_verifier", "= 0.7.0"
62
+ gem "ap2_mandate_verifier", "= 0.8.0"
55
63
  ```
56
64
 
57
65
  runtime依存はJSON 2.19.9、JWT 3.3.0、base64 0.3.0、OpenSSL gem 4.0.2、Digest 3.2.1に固定しています。通常導入には依存の取得・buildが伴い得ます。衝突回避のために固定条件を緩めないでください。Rubyの解決範囲は、その間の全Ruby版・OS・native providerへの対応保証ではありません。[対応契約](docs/SUPPORT_CONTRACT.md)を参照してください。
@@ -59,7 +67,7 @@ runtime依存はJSON 2.19.9、JWT 3.3.0、base64 0.3.0、OpenSSL gem 4.0.2、Dig
59
67
  ## 販売者署名とReceipt
60
68
 
61
69
  注文JWTを署名し、利用アプリが明示した処理結果をReceiptとして署名できます。
62
- 0.5.0で追加され、0.7.0でも利用できるAPIです。この抜粋は既定の単一商品profileです。`checkout`は注文Hash、`key`はアプリ所有のP-256鍵、
70
+ 0.5.0で追加され、0.8.0でも利用できるAPIです。この抜粋は既定の単一商品profileです。`checkout`は注文Hash、`key`はアプリ所有のP-256鍵、
63
71
  `received_closed_sd_jwt`は受信した最終inline SD-JWT原文、`now`はアプリの時計です。
64
72
 
65
73
  ```ruby
@@ -126,6 +134,10 @@ end
126
134
 
127
135
  ## 結果と責任境界
128
136
 
137
+ 次の表は、InputBuilderまたは `verify_checkout` によるOpen → Agent Closedの
138
+ 完全検証に適用します。Direct・Checkout・Receiptは、それぞれの `verified?` や
139
+ 例外契約を維持します。[API別の結果・失敗契約](docs/PUBLIC_API.md#result-object-and-failure-contracts)を参照してください。
140
+
129
141
  | 結果 | 意味と利用者の処理 |
130
142
  | --- | --- |
131
143
  | `:verified_research` / `:scoped_research_verified`、`success? == true` | 不変のEvidenceに固定profileの検査事実があります。購入を許可するかは、Hostが別途判断します。 |
@@ -146,14 +158,18 @@ end
146
158
 
147
159
  Gemは署名、支持する開示閉包、委任、購入/Host binding、制約・期限を検査します。Hostは認証済み・独立・最新のtrust/鍵/失効、注文・Challenge状態、時計を供給します。実行直前に現在状態と期限を再照合し、nonceの原子消費+注文CAS、不明結果の回復、最終許可・決済判断を担当します。`prepare`/`restore` は保存元の認証やnonce未使用を証明しません。
148
160
 
149
- 公開済み0.7.0は既定の固定profile `ap2.checkout.single_merchant_sku` v1(ES256/P256、単一Merchant/SKU/cart行、USD/EUR/JPYと文書化した開示形状)を維持し、明示選択の[複数明細profile](docs/MULTI_ITEM_CHECKOUT.md)を追加します。未知・非対応形式は拒否します。一般AP2/全Schema、実Issuer互換性、Open Mandate発行・Agent Closed生成、Rails adapter、DB/決済実行、数値性能保証は対象外です。実Issuer・実Hostの本番GOとPhase 2-Bは引き続き別のHOLDです。
161
+ 公開済み0.8.0は既定の単一商品profileと明示選択の[複数明細profile](docs/MULTI_ITEM_CHECKOUT.md)を維持し、条件付き発行には後者を使います。全候補開示と既存上限を守り、未知・非対応形式は拒否します。一般AP2/全Schema、実Issuer互換性、新しい選択的開示profile、Rails adapter、DB/決済実行、数値性能保証は対象外です。実Issuer・実Hostの本番GOとPhase 2-Bは引き続き別のHOLDです。
150
162
 
151
163
  ### APIの使い分け
152
164
 
153
165
  | 入口 | 役割 |
154
166
  | --- | --- |
155
- | `InputBuilder.verify(**business_information)` | 0.7.0の推奨業務情報経路。入力を組み立て、完全検証します。発行前準備・復元は上の例の別処理です。 |
156
- | `verify_checkout(**inputs)` | 既存の7入力を直接渡す完全検証。trust/selection/Host JSONも呼出側が渡します。 |
167
+ | `ConditionalCheckout.issue_open/issue_closed/present` | 条件付き発行・原文提示。販売者による完全検証は別途必須です。 |
168
+ | `Buyer.issue_closed/present_closed/verify` | 確定注文を承認するDirect発行・構造確認を伴う提示・Directの完全検証。 |
169
+ | `CheckoutJWT.sign/verify` | 販売者のCheckout署名と、承認前の真正性確認。 |
170
+ | `CheckoutReceipt.reference/sign/verify` | 最終Mandate原文の参照計算、明示的なアプリ結果の署名、Receiptの真正性確認。 |
171
+ | `InputBuilder.verify(**business_information)` | 0.8.0の推奨業務情報経路。入力を組み立て、完全検証します。発行前準備・復元は上の例の別処理です。 |
172
+ | `verify_checkout(**inputs)` | 既存の7入力を直接渡すOpen → Agent Closedの完全検証。trust/selection/Host JSONも呼出側が渡します。 |
157
173
  | `verify_research(**inputs)` | 同じ7入力検証経路の維持された名称。非推奨警告はありません。 |
158
174
  | `verify(presentation_json:)` | 旧JSON構文検査のみ。成功Evidenceを返しません。 |
159
175
 
@@ -161,9 +177,10 @@ Gemは署名、支持する開示閉包、委任、購入/Host binding、制
161
177
 
162
178
  ## 詳細リンク
163
179
 
180
+ - [1.x候補の公開API・失敗・profile・保存契約](docs/PUBLIC_API.md)。従来の部分検証APIも維持し、成功Evidenceを返さない意味を変えません。
164
181
  - [業務情報の一連の利用とRails対応付け](docs/INPUT_BUILDER.ja.md)、[完全Ruby例](examples/input_builder.rb)、[変更前の例](examples/input_builder_before.rb)。
165
182
  - [支持入力・上限・Result/Evidence契約](docs/SUPPORT_CONTRACT.md)、[Issuer/Host責務](docs/ISSUER_HOST_MINIMUM_CONTRACT.md)。
166
- - [0.7.0 Release notes](docs/RELEASE_070.md)、[公開・撤回記録](docs/PROJECT_STATUS.md)、[変更履歴](CHANGELOG.md)。リポジトリREADMEの変更で公開Gemを再build・置換しません。
183
+ - [0.8.0 Release notes](docs/RELEASE_080.md)、[公開・撤回記録](docs/PROJECT_STATUS.md)、[変更履歴](CHANGELOG.md)。リポジトリREADMEの変更で公開Gemを再build・置換しません。
167
184
  - [固定commitの旧7入力・保存FULL例](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.ja.md#保存済み合成入力で試す)、[過去版の配布物・provider証拠](research/stable010_release_linux_package/README.md)、[過去の概念図](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.ja.md#図で見るap2の概念)。履歴は保存していますが、現在の連携手順や対応範囲を広げる根拠ではありません。
168
185
  - [脆弱性報告](SECURITY.md)、[保守方針](docs/POST_RELEASE_MAINTENANCE.md)、[製品方針](docs/PRODUCT_VISION.md)。秘密鍵・実Mandate・個人情報を報告に含めないでください。
169
186
 
data/README.md CHANGED
@@ -1,21 +1,29 @@
1
- # AP2 Mandate Verifier — 0.7.0
1
+ # AP2 Mandate Verifier — Ruby SDK for Checkout delegation
2
2
 
3
3
  [日本語](README.ja.md)
4
4
 
5
- ## 0.8.0 candidate: conditional purchase delegation (unpublished)
5
+ **Published stable: 0.8.0. Working candidate: 1.0.0, not published.**
6
6
 
7
- The candidate adds `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`:
7
+ The 1.0.0 preparation defines a maintained public contract for the existing
8
+ Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
9
+ profiles, result meanings and saved formats. The published installation commands
10
+ below still install 0.8.0. See [the public API contract](docs/PUBLIC_API.md),
11
+ [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and
12
+ [candidate preparation status](docs/RELEASE_100_CANDIDATE.md).
13
+
14
+ ## Conditional purchase delegation — published 0.8.0
15
+
16
+ Published 0.8.0 adds `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`:
8
17
  approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
9
18
  a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
10
19
  `CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
11
20
  multi-item profile. Provider private keys never enter Agent operations.
12
- [API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [release decision material](docs/RELEASE_080_CANDIDATE.md).
21
+ [API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [release sample](docs/RELEASE_080.md), [publication verification](docs/POST_RELEASE_080.md).
13
22
 
14
- Quick Start on MRI 3.4.12 or 4.0.9, using the locally built candidate identified by
15
- the release manifest (0.8.0 is **not published**):
23
+ Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
16
24
 
17
25
  ```sh
18
- gem install --local ./ap2_mandate_verifier-0.8.0.gem
26
+ gem install ap2_mandate_verifier --version 0.8.0
19
27
  ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.8.0").full_gem_path')/examples/conditional_checkout.rb"
20
28
  ```
21
29
 
@@ -27,7 +35,10 @@ pending. Authentication, consent, enrollment, durable replay prevention and actu
27
35
  order/payment execution remain app-owned. Existing users need no migration;
28
36
  0.7.0 defaults and saved formats remain unchanged.
29
37
 
30
- Published stable is **0.7.0**, adding Direct buyer Checkout issuance, presentation and merchant verification through Receipt confirmation. It supports one merchant and 1–8 lines with multiple products. Existing Open→Closed profiles retain their contracts; see [the publication record](docs/PROJECT_STATUS.md#070-publication).
38
+ Published stable is **0.8.0**. It adds conditional Open issuance and Agent Closed
39
+ generation/presentation through complete verification and Receipt confirmation.
40
+ Existing Direct and both Open→Closed profiles retain their contracts; see
41
+ [the publication record](docs/PROJECT_STATUS.md#080-publication).
31
42
 
32
43
  ## Multiple items and quantities
33
44
 
@@ -41,27 +52,27 @@ Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile.
41
52
 
42
53
  ## Try the local demo
43
54
 
44
- The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.7.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. Compare synthetic normal, tampered and expired cases, including actual status/code, diagnostics and Evidence presence. It also demonstrates multiple products with differing quantities, later-line quantity rejection, and authentic Success/Error Receipts. It is local-only; it does not issue real challenges, consume nonces or execute purchases.
55
+ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.8.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. It retains the existing synthetic Open→Agent Closed verification, multi-item and Success/Error Receipt screens. It has no conditional approval/issuance UI; use the standalone Ruby example above for that lifecycle. It is local-only and performs no real challenge issuance, nonce consumption or purchase/payment.
45
56
 
46
57
  ## Install
47
58
 
48
59
  Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
49
60
 
50
61
  ```sh
51
- gem install ap2_mandate_verifier --version 0.7.0
62
+ gem install ap2_mandate_verifier --version 0.8.0
52
63
  ```
53
64
 
54
65
  Or add to your Gemfile:
55
66
 
56
67
  ```ruby
57
- gem "ap2_mandate_verifier", "= 0.7.0"
68
+ gem "ap2_mandate_verifier", "= 0.8.0"
58
69
  ```
59
70
 
60
71
  Runtime dependencies are pinned to JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. Normal installation may download/build dependencies; do not relax the pins to work around a conflict. The Ruby resolution interval is not certification of every Ruby version, OS or native provider. See the [support contract](docs/SUPPORT_CONTRACT.md).
61
72
 
62
73
  ## Merchant signing and Receipt
63
74
 
64
- Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 0.7.0; the excerpt uses the default single-SKU profile.
75
+ Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 0.8.0; the excerpt uses the default single-SKU profile.
65
76
  Here `checkout` is the application order Hash, `key` its P-256 signing key,
66
77
  `received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
67
78
 
@@ -130,6 +141,10 @@ Do not call `prepare` again during verification or update saved hashes/reference
130
141
 
131
142
  ## Results and responsibility boundaries
132
143
 
144
+ The following table applies to complete Open → Agent Closed verification through
145
+ InputBuilder or `verify_checkout`. Direct, Checkout and Receipt APIs retain their
146
+ own `verified?` or exception contracts; see [all result conventions](docs/PUBLIC_API.md#result-object-and-failure-contracts).
147
+
133
148
  | Result | Meaning and next step |
134
149
  | --- | --- |
135
150
  | `:verified_research` / `:scoped_research_verified`, `success? == true` | Immutable Evidence contains checked facts for the fixed profile. The Host must still decide whether to authorize the purchase. |
@@ -150,14 +165,24 @@ Exceptions, process failure and missing results also never authorize an operatio
150
165
 
151
166
  The Gem checks signatures, supported disclosure closure, delegation, purchase/Host bindings, constraints and validity. The Host supplies authenticated, independent and current trust/keys/revocation, order/challenge state and clock. Before acting, it rechecks current state and validity, atomically consumes the nonce with order CAS, handles uncertain outcomes, and makes the final authorization/payment decision. `prepare`/`restore` do not authenticate storage or prove an unused nonce.
152
167
 
153
- Published 0.7.0 retains the default `ap2.checkout.single_merchant_sku` v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and its documented disclosure shapes. It adds the explicitly selected [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer interoperability, Open Mandate issuance/presentation, Rails adapters, DB/payment execution and numeric performance guarantees remain outside scope. Real Issuer/Host production GO and Phase 2-B remain separate HOLDs.
168
+ Published 0.8.0 retains the default `ap2.checkout.single_merchant_sku` v1 and the
169
+ explicit [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Conditional issuance
170
+ uses that multi-item profile, with all candidates disclosed and existing limits.
171
+ Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer
172
+ interoperability, new selective-disclosure profiles, Rails adapters, DB/payment
173
+ execution and numeric performance guarantees remain outside scope. Real
174
+ Issuer/Host production GO and Phase 2-B remain separate HOLDs.
154
175
 
155
176
  ### Which API should I use?
156
177
 
157
178
  | Entry | Role |
158
179
  | --- | --- |
159
- | `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.7.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
160
- | `verify_checkout(**inputs)` | Direct complete verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
180
+ | `ConditionalCheckout.issue_open/issue_closed/present` | Conditional issuance and original-wire presentation; full merchant verification remains required. |
181
+ | `Buyer.issue_closed/present_closed/verify` | Direct exact-order issuance, structural presentation and full Direct verification. |
182
+ | `CheckoutJWT.sign/verify` | Merchant Checkout signing and authentication before approval. |
183
+ | `CheckoutReceipt.reference/sign/verify` | Original final-Mandate reference, explicit application outcome signing and Receipt authentication. |
184
+ | `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.8.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
185
+ | `verify_checkout(**inputs)` | Complete Open → Agent Closed verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
161
186
  | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
162
187
  | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
163
188
 
@@ -165,9 +190,10 @@ Malformed assembly arguments, including missing keywords, to `InputBuilder.verif
165
190
 
166
191
  ## More detail
167
192
 
193
+ - [Proposed 1.x public API, errors, profiles and persistence contract](docs/PUBLIC_API.md). Existing partial-verification APIs remain supported and never return successful Evidence.
168
194
  - [Business-data lifecycle and Rails mapping](docs/INPUT_BUILDER.md), [complete Ruby example](examples/input_builder.rb) and [before/after example](examples/input_builder_before.rb).
169
195
  - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
170
- - [0.7.0 Release notes](docs/RELEASE_070.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
196
+ - [0.8.0 Release notes](docs/RELEASE_080.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
171
197
  - [Pinned historical seven-input / saved FULL example](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#try-the-saved-synthetic-example), [older artifact/provider evidence](research/stable010_release_linux_package/README.md) and [historical conceptual diagrams](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#illustrated-concepts-japanese-diagrams). These records are preserved, not current integration instructions or broader support claims.
172
198
  - [Security reporting](SECURITY.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and [product direction](docs/PRODUCT_VISION.md). Do not include secrets, real Mandates or personal data in reports.
173
199
 
data/SECURITY.md ADDED
@@ -0,0 +1,82 @@
1
+ # Security policy / 脆弱性の報告
2
+
3
+ ## 現在の対象と限界 / Current scope
4
+
5
+ [Published 0.8.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.8.0) is a framework-independent Ruby SDK for the documented AP2 Checkout profiles, including Direct and conditional issuance, presentation, verification and Checkout Receipt confirmation. See [publication evidence](docs/POST_RELEASE_080.md) and [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for its scope and limitations. **1.0.0 is an unpublished candidate**, with its proposed stable surface and release status in [PUBLIC_API](docs/PUBLIC_API.md) and [release preparation](docs/RELEASE_100_CANDIDATE.md).
6
+
7
+ 現在の配布版は、対応profileのDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を備えた、フレームワーク非依存のRuby SDK **0.8.0**です。**1.0.0は準備中の未公開候補**です。1.x公開後の保守対象案は最新マイナー系列の最新修正版のみとし、旧マイナー・0.x・preへのbackportは約束しません。現行版の報告窓口は以下のままです。保守対象・互換性・セキュリティ修正の扱いは[公開後の整備](docs/POST_RELEASE_MAINTENANCE.md)を参照してください。
8
+
9
+ The proposed 1.x policy covers only the latest patch of the latest 1.x minor series once released; older minors, 0.x and prereleases carry no backport promise. Existing reporting routes below remain available for the current release. See [maintenance and compatibility](docs/POST_RELEASE_MAINTENANCE.md). The pre.3, 0.1.0 candidate and R2 statements below are historical records of those stages, not the current release status.
10
+
11
+ Evidence is not Host ALLOW or payment permission. Real Issuer trust, specific Host production GO and Phase 2-B remain HOLD; general AP2/full Schema, full Phase2-A PASS, worst-resource/concurrency and global native/runtime safety are not established. No SLA, fixed support term or response/fix deadline is promised. Existing provider/JSON advisory-metadata and communication-accounting limitations remain recorded; publication does not erase them. New execution, changes or releases require their own approval.
12
+
13
+ EvidenceはHost ALLOW・決済許可ではありません。実Issuer信頼、特定Host本番GO、Phase 2-BはHOLDを維持し、一般AP2/全Schema・Phase2-A全面PASS・最悪資源/並行性能・native/runtime全面安全性は未証明です。SLA・固定保守年数・受付/修正期限は約束せず、既存のprovider/JSON勧告metadata・通信会計の限界を保持します。本記録は新たな実行・変更・公開を許可しません。
14
+
15
+ ## 歴史記録:pre.3の対象と限界 / Historical pre.3 scope
16
+
17
+ `ap2_mandate_verifier 0.1.0.pre.3` is a fixed-profile research prerelease,
18
+ not a production or stable product. General AP2 compatibility and full Phase2-A
19
+ PASS are not established. Issuance, presentation generation and a Rails SDK are
20
+ incomplete. Evidence is not Host ALLOW or payment permission. Publication does
21
+ not establish a security guarantee or a maintained-version/backport commitment.
22
+ 固定profileの研究用途限定・本番利用不可です。公開は安全性保証や保守版/バックポートの約束ではありません。
23
+
24
+ ## 非公開報告 / Private reporting
25
+
26
+ Use [GitHub Security Advisories](https://github.com/cuichangquan/ap2-mandate-verifier/security/advisories)
27
+ and choose **Report a vulnerability**. Private vulnerability reporting is enabled
28
+ for this repository. GitHub requires sign-in; repository administrators instead
29
+ see the draft-advisory workflow. See
30
+ [GitHub's reporting instructions](https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/report-privately).
31
+ Do not submit vulnerability details through public Issues or PRs.
32
+ [GitHub Security Advisories](https://github.com/cuichangquan/ap2-mandate-verifier/security/advisories)
33
+ の **Report a vulnerability** から非公開で報告してください。GitHubへのログインが必要です。
34
+ 管理権限のある利用者にはdraft advisoryの入口が表示されます。
35
+ 脆弱性の詳細を公開Issue/PRへ書かないでください。
36
+
37
+ Include the affected Gem version/source SHA, Ruby/OS/dependency versions,
38
+ sanitized synthetic steps to reproduce, expected/actual behavior and impact.
39
+ Do not send credentials, private keys, real Mandates/tokens/nonces or personal
40
+ data. Describe the issue with minimal synthetic examples instead.
41
+ 対象版/source SHA、環境、合成値による最小再現、期待/実結果と影響を記載してください。
42
+ 秘密鍵・認証情報・実Mandate/token/nonce・個人情報は送らないでください。
43
+
44
+ The initial maintainer contact is Owner `cuichangquan` through the private GitHub
45
+ report. No acknowledgement, fix or disclosure deadline is guaranteed. If the
46
+ reporting entry is unavailable, a public Issue may ask only for a private contact;
47
+ include no vulnerability details or sensitive data. Do not assume that silence
48
+ means safety or acceptance.
49
+ 窓口はGitHub経由のOwner `cuichangquan` です。受付・修正・公開の期限は保証しません。
50
+ 非公開報告が利用できない場合、公開Issueでは窓口確認だけを行い、詳細や機微情報は掲載しません。
51
+ 応答がないことを安全性や受理の証拠にしないでください。
52
+
53
+ Ordinary non-security bugs belong in
54
+ [Issues](https://github.com/cuichangquan/ap2-mandate-verifier/issues).
55
+ Dependency review and validation boundaries are in
56
+ [post-release maintenance](docs/POST_RELEASE_MAINTENANCE.md).
57
+ This policy does not authorize tests against real users, payments, external
58
+ services or production systems.
59
+
60
+
61
+ ## Historical candidate stage / 歴史記録:未公開候補の採用済み保守条件
62
+
63
+ The pre3 description above remains its historical scope. Candidate0.1.0 is validated but **not published**, and no specific Host production GO is granted. Its fixed-profile verification contract, exact environment evidence and exclusions are in [candidate evidence](research/stable010_candidate/README.md) and [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md). Publication requires separate S7 approval; no general AP2/real-Issuer/global-runtime safety guarantee follows.
64
+
65
+ Owner `cuichangquan` remains the initial contact through the routes above. For the initial stable series once separately released, support covers its latest patch only; no prerelease/older-series backport, fixed support term, response/fix/disclosure deadline or 24/7 service is promised. Manual Ruby/Gem/native/provider review is adopted monthly, on relevant advisory discovery and before a release. This is not an active automatic monitor or an unlimited approval to run tools. Security updates, deprecation and end of support identify affected versions, reasons and migration in release documentation; no fixed notice period is promised. Known major unaddressed issues or inability to maintain mean HOLD. New code, execution and publication retain their own approval boundaries.
66
+
67
+ pre3の歴史的範囲は保持します。0.1.0は限定検証済み・未公開候補です。初回安定系列の最新修正版のみを保守対象とする条件を採用済みですが、公開GOとは別です。担当/窓口は上記、月次・関連勧告判明時・次版前に手動確認し、自動監視/SLA/一定年数/旧版backportを約束しません。重大未対処問題・保守不能はHOLD。更新/廃止は対象版・理由・移行を明示します。
68
+
69
+
70
+
71
+ ## Historical R2 preparation / 歴史記録:公開向け文書のR2
72
+
73
+ The0.1.0 consumer documentation now describes the fixed verification contract and installation only after official listing, without declaring publication. Earlier candidate/R1/pre3 descriptions above are historical. A newly built R2 archive has separate [source and validation evidence](research/stable010_release_linux_package/README.md); R1's43,008B archive and observations are not reused as new-byte validation. Existing maintenance scope/reporting routes/exclusions remain unchanged. RubyGems publication and specific Host production GO still require separate authorization.
74
+
75
+ 0.1.0の公開向け文書を整理しましたが、公開済みとは表示しません。旧candidate/R1/pre3は履歴として保持し、新R2は別archive・別証拠です。採用済み保守条件・窓口・保証除外は不変で、Gem公開GO・特定Host本番GOは別途必要です。
76
+
77
+
78
+ ## Historical prepublication supplement / 歴史記録:公開前R2検証追補
79
+
80
+ The new34,304B R2 archive (SHA256 `37b2a235b6fab2d9d9765ae985dd9db27afd3b2c5407fe263a6b65314550db32`) passed Mac and [Ubuntu run40288305150 attempt1](https://github.com/cuichangquan/ap2-mandate-verifier/actions/runs/40288305150) payload13/loaded10/installed52 checks with matching payload/dependency identities. See [exact results and limitations](research/stable010_release_linux_package/README.md). This is distinct from R1/pre3, not a new885 or independent Oracle run. Source/packaged bytes remain frozen. No Gem, tag or Release publication occurred; S7 and specific Host production GO remain HOLD. Existing maintenance policy and reporting routes are unchanged.
81
+
82
+ 新R2はMac/Ubuntuで限定包装検証済みですが未公開です。provider確認を全面安全性へ昇格せず、JSON勧告metadata不整合、OS dyld/全binding、総通信/physical peak等の未証明を保持します。原結果のhash/読戻し後に今回分だけを清掃し、旧停止履歴・証拠・archiveは保持。追加build/試験/Actions/取得はこの追補作業では行いません。
@@ -106,8 +106,10 @@ In the existing Open→Closed flow, the Provider-signed Open content endorses th
106
106
  Agent's public key through `cnf.jwk`; that key verifies the terminal Agent
107
107
  signature and its binding to the preceding original SD-JWT, expected audience
108
108
  and nonce. Direct instead trusts the Provider signature over the already closed
109
- order itself and needs no Agent key endorsement. Open issuance, choosing fewer
110
- disclosures and Agent signing therefore remain separate future APIs.
109
+ order itself and needs no Agent key endorsement. In 0.7.0, Open issuance and
110
+ Agent signing were future work; published 0.8.0 adds those APIs separately in
111
+ [ConditionalCheckout](CONDITIONAL_CHECKOUT.md), preserving this Direct contract.
112
+ Choosing fewer disclosures remains unsupported.
111
113
 
112
114
  Maximum entire wire 32,768 bytes; Checkout JWT 16,384; root payload 2,048;
113
115
  decoded disclosure 24,576; JSON depth 24. Existing strict JSON/canonical base64url
@@ -171,9 +173,10 @@ expiry/future time, missing disclosures, malformed signed combinations and unkno
171
173
  formats. Existing source and ordinary-install regressions run on MRI 3.4.12/4.0.9.
172
174
  Latest-HEAD independent review and branch protections are required before merge.
173
175
 
174
- Open issuance, Agent Closed generation/selective disclosure/presentation, User
175
- Credentials, multiple merchants, split orders and continuous autonomous buying
176
- are follow-up candidates. Agent-to-Agent delegation is outside current AP2 scope,
176
+ Open issuance and Agent Closed generation/presentation were follow-ups at 0.7.0
177
+ and are now available in the separate 0.8.0 module. Selective-disclosure profiles,
178
+ User Credentials, multiple merchants, split orders and continuous autonomous buying
179
+ remain follow-up candidates. Agent-to-Agent delegation is outside current AP2 scope,
177
180
  not declared permanently forbidden. Real Issuer trust, actual demand, generic AP2
178
181
  support and production safety are not established by synthetic test success.
179
182
  Gem publication and its separately approved tag/Release are recorded in the
@@ -1,4 +1,8 @@
1
- # Conditional Checkout delegation — 0.8.0 candidate
1
+ # Conditional Checkout delegation — published 0.8.0
2
+
3
+ Published 2026-11-01 06:01:31.103 UTC. The official 79,872-byte Gem and all29
4
+ payloads match source `5a7394c1b98f000b321423e2c2f80d50b5157808`.
5
+ [Publication verification and installed examples](POST_RELEASE_080.md).
2
6
 
3
7
  Adopted AP2 v0.2.0 source remains `b4587ac1d055888a73b4b21750973cffba961793`.
4
8
  This is an additive Ruby issuance API for the existing explicit
@@ -111,10 +115,9 @@ SDK behavior and stricter local rules are recorded separately; SDK shortage and
111
115
  empty-candidate differences remain in MULTI_ITEM_INTEROP.md. Latest-HEAD Codex
112
116
  review and the same candidate Gem installed on both supported Rubies are required.
113
117
 
114
- Status: implemented and locally tested; release gates and final package/review
115
- evidence are tracked in RELEASE_080_CANDIDATE.md and the external manifest.
116
- No RubyGems push, public tag/Release,
117
- production connection or actual payment is authorized by this task.
118
+ Status: published after separate Owner authorization; final review/CI/source and
119
+ distribution evidence are linked in POST_RELEASE_080.md. The preparation snapshot
120
+ remains in RELEASE_080_CANDIDATE.md. No production or actual payment is performed.
118
121
 
119
122
  ## Official-source comparison and independent results
120
123
 
@@ -0,0 +1,182 @@
1
+ # Input assembly for explicit checkout profiles
2
+
3
+ ## Multi-item selection in published 0.6.0
4
+
5
+ Published stable 0.6.0 supports
6
+ `InputBuilder.trust(..., profile_ref: "ap2.checkout.single_merchant_multi_item")`.
7
+ Omitting `profile_ref:` retains the unchanged single-SKU v1 profile. The new
8
+ selection is authenticated Host policy, not extracted from Mandate claims.
9
+ `prepare`, `restore`, `restore_trust`, `inputs` and `verify` retain their existing
10
+ arguments and follow that validated profile. Saved profile identifiers and
11
+ definition hashes must agree with current trust and binding; no repair occurs.
12
+ The old saved format remains valid for its original profile, and migration
13
+ requires a new selection and challenge before presentation.
14
+
15
+ Use the same explicit `profile_ref:` for `CheckoutJWT.sign` and
16
+ `CheckoutReceipt.reference/sign/verify`. The [multi-item guide](MULTI_ITEM_CHECKOUT.md)
17
+ describes supported identities, quantities, disclosures and limits; the
18
+ [complete synthetic example](../examples/multi_item_checkout.rb) covers signing,
19
+ prepare/save/restore/current verification and genuine Success/Error Receipts.
20
+ The normal business-order mapping below still supplies independent Host values;
21
+ received signed claims never become their own expected total or trust input.
22
+
23
+ Published 0.4.0 includes supplemental safe diagnostics; see [API and troubleshooting](DIAGNOSTICS.md). Existing verdict/Evidence contracts remain unchanged.
24
+
25
+ `AP2MandateVerifier::InputBuilder` converts explicit Host business information into
26
+ the existing seven verification inputs. It performs no network, database, Rails,
27
+ nonce issuance/consumption or payment operation. A built input is not verified
28
+ Evidence. `InputBuilder.verify` always invokes the complete `verify_checkout` core.
29
+ The original `verify_checkout`, `verify_research` and older APIs remain available.
30
+
31
+ ## Run the complete Ruby example
32
+
33
+ After ordinary installation of published 0.4.0 (`gem install ap2_mandate_verifier --version 0.4.0`), run these repository examples:
34
+
35
+ ```sh
36
+ ruby examples/input_builder.rb valid
37
+ ruby examples/input_builder.rb tampered
38
+ ruby examples/input_builder.rb expired
39
+ ruby examples/input_builder_before.rb
40
+ ```
41
+
42
+ The example contains independent synthetic order and public-registration data,
43
+ original signed Strings, issue-time preparation, temporary-file persistence,
44
+ restoration, fresh current-state reads, verification, and result handling. It does
45
+ not read `full.json` or infer trusted keys, prices, identities or nonce from tokens.
46
+ No private keys are distributed. See `examples/input_builder/NOTICE.md` for source.
47
+ The fixed synthetic clock is intentional: these historical signatures expire.
48
+
49
+ ## Host mapping
50
+
51
+ All structured input keys are Strings. Exact plain Hash/Array/String/Integer and
52
+ boolean values are accepted; do not pass model objects, Symbols, subclasses,
53
+ custom coercions or unbounded graphs. Unknown fields are rejected. Pure assembly
54
+ methods raise `InputBuilder::Invalid` for malformed business information; a caller
55
+ must treat missing results or exceptions as failure, never authorization.
56
+
57
+ `verify` converts malformed assembly arguments to the existing immutable Result
58
+ `:rejected / :invalid_host_context`; dependency or unexpected assembly failures
59
+ return `:unavailable / :research_verification_unavailable`. Both are non-success
60
+ with no Evidence. Codes produced after entering the complete verifier are retained.
61
+
62
+ | Business source | Builder argument | Host responsibility |
63
+ | --- | --- | --- |
64
+ | Authenticated registry snapshot and public PEM keys | `trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:)` | Provenance, enrollment, revocation, freshness and explicit selection |
65
+ | Current order/account/tenant, merchant, audience, version, currency, total minor units | `order:` | Independent authoritative state; no values inferred from signed claims |
66
+ | Original received Root and Checkout Strings | `root_presentation:`, `host_checkout_jws:` | Preserve exact bytes, including Root disclosure order and trailing `~` |
67
+ | Host-chosen ID, nonce, issuer and validity | `prepare(...)` | Actual issuance and durable authenticated persistence |
68
+ | Saved preparation String | `restore(saved_challenge:)` | Authenticate storage; retain state and references without repair |
69
+ | Current trust/order, terminal String and trusted clock | `inputs(...)` / `verify(...)` | Independent reads, currentness and clock provenance |
70
+ | Verified Evidence | returned Result | Final authorization; recheck trust/order, atomic nonce consumption and order CAS |
71
+
72
+ A snapshot has `id`, `policy_version`, `active`, `not_before`, `not_after`, and
73
+ `records`. Each record supplies `role`, `identity`, `tenant_id`, `purpose`,
74
+ `key_ref`, `public_key_pem`, `active`, `not_before`, `not_after`. Public PEM must
75
+ already be canonical P256 SPKI. The builder adds the fixed profile, algorithm and
76
+ fingerprint; it preserves and validates every record, including nonselected ones.
77
+ Role selectors each contain `identity`, `purpose`, `key_ref`.
78
+
79
+ An order contains `tenant_id`, `buyer_account_id`, `order_id`, `merchant_id`,
80
+ `audience`, `order_version`, `currency`, `expected_total` (integer minor units).
81
+ The builder adds selected Agent fingerprint, raw wire digests and fixed profile.
82
+ It does not compare current values by overwriting issued values.
83
+
84
+ ## Rails mapping example
85
+
86
+ Rails is optional. This explicit mapping belongs to the application; the Gem does
87
+ not interpret ActiveRecord models or acquire trust. Only use values whose source
88
+ and currentness your Host has authenticated:
89
+
90
+ ```ruby
91
+ order_information = {
92
+ "tenant_id" => order.tenant.external_id,
93
+ "buyer_account_id" => order.buyer.external_id,
94
+ "order_id" => order.external_id,
95
+ "merchant_id" => order.merchant.external_id,
96
+ "audience" => configured_checkout_audience,
97
+ "order_version" => order.lock_version.to_s,
98
+ "currency" => order.currency,
99
+ "expected_total" => order.total_minor
100
+ }
101
+ # registry_snapshot and role selectors use the same explicit plain-value mapping.
102
+ # Save prepare(...) bytes in a protected challenge record before handing out nonce.
103
+ # Later load that record unchanged and independently reread current order/trust.
104
+ inputs = AP2MandateVerifier::InputBuilder.inputs(
105
+ trust: current_trust, saved_challenge: challenge.preparation_bytes,
106
+ order: order_information, root_presentation: received_root,
107
+ terminal_jws: received_terminal, host_checkout_jws: original_checkout,
108
+ expected_challenge_issuer_id: configured_host_id,
109
+ clock_source_id: trusted_clock_id, verified_at: trusted_clock_unix_seconds)
110
+ result = AP2MandateVerifier.verify_checkout(**inputs)
111
+ # success? is checked evidence, not a purchase/payment permission.
112
+ ```
113
+
114
+ Do not call `prepare` again during verification. Changes in order, selected Agent,
115
+ raw signed bytes, trust snapshot/policy or saved references must remain observable.
116
+ Restoration validates the storage envelope and does not authenticate its contents.
117
+ Changing a stored digest to match current data defeats the Host trust boundary.
118
+ Persist state changes separately under authenticated atomic Host operations; do
119
+ not replace an already-used challenge with a new issued preparation.
120
+
121
+ ## Before/after measurement
122
+
123
+ The checked-in runnable examples are the measurement material, rather than a
124
+ one-line call that hides initial setup or persistence. Count nonblank,
125
+ noncomment Ruby lines with:
126
+
127
+ ```sh
128
+ awk 'NF && $0 !~ /^[[:space:]]*#/ {n++} END {print n}' examples/input_builder_before.rb
129
+ awk 'NF && $0 !~ /^[[:space:]]*#/ {n++} END {print n}' examples/input_builder.rb
130
+ ```
131
+
132
+ Current source counts are **64 before / 42 after**. Both include initial mapping,
133
+ issue preparation, save/read, current-state construction and result handling.
134
+ The after example additionally selects three scenarios; this is a small synthetic
135
+ example, not a general application-effort benchmark or performance claim.
136
+
137
+ | Burden | Before | Recommended path |
138
+ | --- | --- | --- |
139
+ | Initial business mapping | Required | Required, explicit and source-owned |
140
+ | Trust/profile envelopes and selection references | Handwritten nested shapes | Gem-generated |
141
+ | Public-key fingerprint, snapshot-body hash, Root/Checkout digest | 4 caller-side SHA256 call sites | 0 |
142
+ | Challenge B and trust-reference transcription | Caller constructs and copies | Gem-generated at preparation |
143
+ | Daily verification | Assemble current B, host JSON, seven arguments | Restore saved bytes, map current state, call builder |
144
+ | Storage, trust authenticity, nonce state, final business decision | Host-owned | Host-owned |
145
+
146
+ The improvement removes mechanical transformations and repeated profile/reference
147
+ knowledge. It does not remove the first-time work of identifying authoritative
148
+ business data, registration policy or atomic Host operations.
149
+
150
+ ## Versions and migration
151
+
152
+ Gem version (current published `0.6.0`), AP2 source
153
+ `b4587ac1d055888a73b4b21750973cffba961793`, explicitly selected profile
154
+ (`ap2.checkout.single_merchant_sku` v1 or `ap2.checkout.single_merchant_multi_item` v1), and preparation format `1` are
155
+ separate identifiers. Unknown preparation/profile versions fail closed. There is
156
+ no generic future-profile fallback. New protocol requirements can require new
157
+ application data and an explicit migration or reissuance.
158
+
159
+ Keep existing seven-input integrations unchanged while adopting the builder for
160
+ new preparations. Existing raw Host JSON is not automatically upgraded into a
161
+ new issued challenge. Retain original signed bytes and authenticated saved
162
+ references. Reissue through the Host's normal authorization process when a stored
163
+ format cannot be supported; do not repair its digests or reinterpret its version.
164
+ See [SUPPORT_CONTRACT](SUPPORT_CONTRACT.md) and the [multi-item migration](MULTI_ITEM_CHECKOUT.md) for each profile's scope.
165
+
166
+ ### Restoring an existing trust snapshot
167
+
168
+ `trust(...)` creates a **new** snapshot body from business records. When your Host
169
+ persists an existing authenticated snapshot, keep `trust.trust_json` and
170
+ `trust.selection_json` as original Strings and reload them with:
171
+
172
+ ```ruby
173
+ current_trust = AP2MandateVerifier::InputBuilder.restore_trust(
174
+ trust_json: authenticated_registry.trust_bytes,
175
+ selection_json: authenticated_registry.selection_bytes,
176
+ verified_at: trusted_clock_unix_seconds)
177
+ ```
178
+
179
+ This preserves exact snapshot/profile body Strings and their existing digests.
180
+ Do not parse and regenerate a persisted trust body to suppress reference drift.
181
+ A restored snapshot must still be independently authenticated and current; loading
182
+ an older snapshot does not establish freshness or prevent rollback.