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 +4 -4
- data/README.ja.md +32 -15
- data/README.md +42 -16
- data/SECURITY.md +82 -0
- data/docs/BUYER_DIRECT_CHECKOUT.md +8 -5
- data/docs/CONDITIONAL_CHECKOUT.md +8 -5
- data/docs/INPUT_BUILDER.md +182 -0
- data/docs/POST_RELEASE_MAINTENANCE.md +160 -0
- data/docs/PUBLIC_API.md +198 -0
- data/docs/RELEASE_100_CANDIDATE.md +113 -0
- data/docs/SUPPORT_CONTRACT.md +50 -5
- metadata +13 -8
- data/docs/RELEASE_080_CANDIDATE.md +0 -109
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9c57f86a63b5438f3160544896ad16f2376372a60fe12368432ab70244b1a612
|
|
4
|
+
data.tar.gz: 4257f8474101c2f7de0876c963b7205d2be5da17cd22d70917cee56efc155639
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5611e738d912999083d6b440c0126e8e3166a079de2378dbe02a5cd5968a1e66c2ef395409587853e0576005050e0078e86ba0093956c22e442e400732743ba9
|
|
7
|
+
data.tar.gz: 646096deea75cb2154b5258c796f5f75338a67d36fc4944cd465148f41ea87faf517ddd02d4e04478b2054ea4caa8b8789cac50a2d8afc23d7efd4ee1b307709
|
data/README.ja.md
CHANGED
|
@@ -1,20 +1,28 @@
|
|
|
1
|
-
# AP2 Mandate Verifier —
|
|
1
|
+
# AP2 Mandate Verifier — Checkout委任のRuby SDK
|
|
2
2
|
|
|
3
3
|
[English](README.md)
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
[
|
|
20
|
+
[Release実行例](docs/RELEASE_080.md)・[公開照合記録](docs/POST_RELEASE_080.md)を参照してください。
|
|
13
21
|
|
|
14
|
-
正式対応MRI 3.4.12/4.0.9
|
|
22
|
+
正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
|
|
15
23
|
|
|
16
24
|
```sh
|
|
17
|
-
gem install --
|
|
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.
|
|
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
|
-
[
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
| `
|
|
156
|
-
| `
|
|
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.
|
|
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 —
|
|
1
|
+
# AP2 Mandate Verifier — Ruby SDK for Checkout delegation
|
|
2
2
|
|
|
3
3
|
[日本語](README.ja.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Published stable: 0.8.0. Working candidate: 1.0.0, not published.**
|
|
6
6
|
|
|
7
|
-
The
|
|
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
|
|
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
|
|
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 --
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
| `
|
|
160
|
-
| `
|
|
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.
|
|
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
|
|
110
|
-
|
|
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
|
|
175
|
-
|
|
176
|
-
|
|
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
|
|
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:
|
|
115
|
-
evidence are
|
|
116
|
-
No
|
|
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.
|