ap2_mandate_verifier 0.7.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: 2455816539364170899a8ac40faa98c464835c72c0fd2db52847f013bf373da7
4
- data.tar.gz: 183bfc7a0d3077cf81b741d6f55f92e48b3fb07a190fdcf5b829b03a6bdb0a0e
3
+ metadata.gz: 9c57f86a63b5438f3160544896ad16f2376372a60fe12368432ab70244b1a612
4
+ data.tar.gz: 4257f8474101c2f7de0876c963b7205d2be5da17cd22d70917cee56efc155639
5
5
  SHA512:
6
- metadata.gz: 10212bb6d0720c0590920d3454a76207e6f23c31f7f9d84aeee9d11e3346fd23535b4b02a50d5442b0a6d1297e2132c3386895c3b2bff6a19fa0ccc5e2398e3e
7
- data.tar.gz: aa86c67bb678296eeb094fe28c4e4c0df964fbaf1a974e963b543217db7d6c8e7b4457d9fbc6889e9338cf8cfcda9d5a932f6a92545df4ef4adb5c5f3621428e
6
+ metadata.gz: 5611e738d912999083d6b440c0126e8e3166a079de2378dbe02a5cd5968a1e66c2ef395409587853e0576005050e0078e86ba0093956c22e442e400732743ba9
7
+ data.tar.gz: 646096deea75cb2154b5258c796f5f75338a67d36fc4944cd465148f41ea87faf517ddd02d4e04478b2054ea4caa8b8789cac50a2d8afc23d7efd4ee1b307709
data/README.ja.md ADDED
@@ -0,0 +1,199 @@
1
+ # AP2 Mandate Verifier — Checkout委任のRuby SDK
2
+
3
+ [English](README.md)
4
+
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公開済み
14
+
15
+ `ConditionalCheckout.issue_open`、`.issue_closed`、`.present` を追加します。
16
+ A/Bから1個とCを2個という条件を承認サービスが登録Agent鍵へOpenとして発行し、
17
+ Agentが条件に合う販売者署名CheckoutをClosedにします。既存 `InputBuilder.verify` と
18
+ `CheckoutReceipt.sign/verify` へ接続します。全候補開示の複数商品profileを維持し、
19
+ Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CONDITIONAL_CHECKOUT.md)、
20
+ [Release実行例](docs/RELEASE_080.md)・[公開照合記録](docs/POST_RELEASE_080.md)を参照してください。
21
+
22
+ 正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
23
+
24
+ ```sh
25
+ gem install ap2_mandate_verifier --version 0.8.0
26
+ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.8.0").full_gem_path')/examples/conditional_checkout.rb"
27
+ ```
28
+
29
+ [Ruby単体の実行例](examples/conditional_checkout.rb)はインストール済み公開APIだけを使い、
30
+ 3明細・候補選択・異なる要件数量・同一商品の別行からSuccess/Error Receiptまで動きます。
31
+ Success後は消費済み、Error後は再提示方針を再判断、Receipt未到着や結果不明は保留です。
32
+ 本人認証・同意・購買権限・信頼先登録・永続的な重複防止・注文や決済の実行はアプリ責務です。
33
+ 0.7.0利用者の移行は不要で、既存既定値・保存形式を維持します。0.8.0は公開済みです。
34
+
35
+ 公開済み安定版は **0.8.0** です。Open発行・Agent Closed生成/提示を完全検証とReceiptへ接続し、1販売者・1〜8明細・複数商品・数量・候補選択を扱います。既存DirectとOpen→Closedの契約を維持します。[公開記録](docs/PROJECT_STATUS.md#080-publication)を参照してください。
36
+
37
+ ## 複数商品と数量
38
+
39
+ 新profile `ap2.checkout.single_merchant_multi_item` v1は、`InputBuilder.trust`、`CheckoutJWT.sign`、`CheckoutReceipt.reference/sign/verify` に `profile_ref:` を渡して明示選択します。完全検証は認証済みtrustの選択に従います。既定の `ap2.checkout.single_merchant_sku` v1は定義・hash・1明細の受理範囲を維持します。
40
+
41
+ 単一販売者・単一Checkout・単一通貨で最大8明細を扱い、数量違いと同一商品の別行を支持します。開示候補の商品IDを整数最大流で照合し、全要件と全注文数量を過不足なく一度ずつ充当します。数量不足・余剰は拒否し、要件IDと明細IDは別の識別子です。[詳細・移行案内](docs/MULTI_ITEM_CHECKOUT.md)、[合成入力による一連の動作例](examples/multi_item_checkout.rb)、[公式Python SDKとの数量不足・空候補・Receipt参照の差異](docs/MULTI_ITEM_INTEROP.md)を参照してください。
42
+
43
+ Rubyで購入委任データを検証する、AP2の固定profile向けGemです。署名データを、Hostが独立して渡す信頼情報・注文情報と照合し、不変のEvidenceを返します。**検証成功は購入許可・決済許可ではありません。**
44
+
45
+ `InputBuilder` は業務情報から検証入力を作り、Gem独自のtrust/selection/Host JSON、fingerprint、署名原文のdigest計算を担当します。誰を信頼するかの選択、期待する注文・Challenge状態・時計は利用者が渡します。Rails非依存で、通信・DB・決済処理は行いません。
46
+
47
+ ## ローカルデモを試す
48
+
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消費・購入や決済は行いません。
50
+
51
+ ## インストール
52
+
53
+ 正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
54
+
55
+ ```sh
56
+ gem install ap2_mandate_verifier --version 0.8.0
57
+ ```
58
+
59
+ BundlerのGemfile:
60
+
61
+ ```ruby
62
+ gem "ap2_mandate_verifier", "= 0.8.0"
63
+ ```
64
+
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)を参照してください。
66
+
67
+ ## 販売者署名とReceipt
68
+
69
+ 注文JWTを署名し、利用アプリが明示した処理結果をReceiptとして署名できます。
70
+ 0.5.0で追加され、0.8.0でも利用できるAPIです。この抜粋は既定の単一商品profileです。`checkout`は注文Hash、`key`はアプリ所有のP-256鍵、
71
+ `received_closed_sd_jwt`は受信した最終inline SD-JWT原文、`now`はアプリの時計です。
72
+
73
+ ```ruby
74
+ signing = AP2MandateVerifier::CheckoutJWT
75
+ signed = signing.sign(checkout: checkout, signer: signing.es256_signer(private_key: key),
76
+ public_key_pem: key.public_to_pem)
77
+ # signed.jwtの原文を保持し、InputBuilderのhost_checkout_jwsへ渡します。
78
+ receipt = AP2MandateVerifier::CheckoutReceipt.sign(closed_sd_jwt: received_closed_sd_jwt,
79
+ issuer: "shop", outcome: "Error", error: "declined", error_description: "Application declined",
80
+ issued_at: now, signer: signing.es256_signer(private_key: key), public_key_pem: key.public_to_pem)
81
+ ```
82
+
83
+ 受信時は独立した信頼鍵・期待署名者・明示時刻範囲・対象Mandateの原文参照を照合します。
84
+ 真正な拒否は `verified? == true`、`purchase_succeeded? == false` です。
85
+ [完全動作例](examples/merchant_signing.rb)と[対応原文形状・SDKとの差異](docs/MERCHANT_SIGNING.md)を参照してください。
86
+
87
+ ## InputBuilderの最小例
88
+
89
+ 導入後、このリポジトリをcheckoutし、以下をルートの `quick_start.rb` として保存して `ruby quick_start.rb` を実行します。[`examples/input_builder/`](examples/input_builder/)のJSONファイルは、明示された合成注文・公開鍵登録情報と署名原文Stringです。インストール済みGemには含まれません。保存署名には期限があるため固定の合成時計を使います。実登録や本番の現在情報として再利用しないでください。
90
+
91
+ ```ruby
92
+ require "ap2_mandate_verifier"
93
+ require "json"
94
+ require "tmpdir"
95
+
96
+ builder = AP2MandateVerifier::InputBuilder
97
+ fixtures = File.join(__dir__, "examples/input_builder")
98
+ read = ->(name) { JSON.parse(File.binread(File.join(fixtures, "#{name}.json"))) }
99
+ trust_at = ->(now) do
100
+ builder.trust(snapshot: read.call("trust_snapshot"), tenant_id: "synthetic-tenant",
101
+ issuer: {"identity" => "issuer", "purpose" => "checkout", "key_ref" => "issuer-1"},
102
+ agent: {"identity" => "agent", "purpose" => "checkout", "key_ref" => "agent-1"},
103
+ merchant: {"identity" => "shop", "purpose" => "checkout", "key_ref" => "merchant-1"},
104
+ verified_at: now)
105
+ end
106
+ wires = read.call("signed_wires").transform_keys(&:to_sym) # 原文Stringのbytesを保持。
107
+
108
+ # 発行前:独立した注文・信頼情報と、Hostが選んだChallenge情報。
109
+ prepared = builder.prepare(trust: trust_at.call(1_800_000_000),
110
+ order: read.call("order"), root_presentation: wires.fetch(:root_presentation),
111
+ host_checkout_jws: wires.fetch(:host_checkout_jws),
112
+ challenge_id: "synthetic-challenge", nonce: "n", issuer_id: "synthetic-host",
113
+ not_before: 1_799_998_000, not_after: 1_800_002_000)
114
+
115
+ Dir.mktmpdir do |directory|
116
+ record = File.join(directory, "challenge.json")
117
+ File.binwrite(record, prepared) # デモ用保存。本物の保存処理はHostの責任。
118
+
119
+ # 検証時:保存原文を読み戻し、現在の注文・信頼情報を独立して取得。
120
+ now = 1_800_000_000 # 外部から供給する合成時計。本番の時刻取得ではない。
121
+ result = builder.verify(trust: trust_at.call(now),
122
+ saved_challenge: builder.restore(saved_challenge: File.binread(record)),
123
+ order: read.call("order"), **wires,
124
+ expected_challenge_issuer_id: "synthetic-host",
125
+ clock_source_id: "fixed-synthetic-clock", verified_at: now)
126
+ puts "#{result.status}/#{result.code}; evidence=#{!result.evidence.nil?}"
127
+ raise "Verification did not succeed; stop" unless result.success?
128
+ end
129
+ ```
130
+
131
+ 変更していない合成入力の期待値は `verified_research/scoped_research_verified; evidence=true` です。準備・保存・後の検証を1プロセス内で示す例であり、実発行や原子的消費を実装していません。実連携では、認証済みの登録・注文情報を明示的に対応付け、署名原文を保持します。構造化業務入力にはStringキーの通常のRuby値を使い、ActiveRecordオブジェクトそのものは渡しません。
132
+
133
+ 検証時に `prepare` をやり直したり、保存hash/参照を現在値に合わせて更新したりしないでください。注文・信頼情報・署名原文の変化は検出できるままにします。保存済みtrust JSONは `restore_trust` で再シリアライズせず読み戻せます。[完全例](examples/input_builder.rb)には正常・改ざん・期限切れがあり、[利用案内](docs/INPUT_BUILDER.ja.md)に業務field・原文復元・Railsモデル対応付けを示しています。
134
+
135
+ ## 結果と責任境界
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
+
141
+ | 結果 | 意味と利用者の処理 |
142
+ | --- | --- |
143
+ | `:verified_research` / `:scoped_research_verified`、`success? == true` | 不変のEvidenceに固定profileの検査事実があります。購入を許可するかは、Hostが別途判断します。 |
144
+ | `:rejected`、`rejected? == true` | Evidenceなし。停止して `result.code` を確認します。 |
145
+ | `:unavailable`、`unavailable? == true` | Evidenceなし。停止します。依存・処理の失敗だけで業務入力が不正とは断定しません。 |
146
+
147
+ 失敗時は追加の確認ヒントを取得できます。成功時の診断は `nil` です。
148
+
149
+ ```ruby
150
+ if (diagnostic = result.diagnostic)
151
+ puts diagnostic.to_h(locale: :ja) # 英語は :en
152
+ end
153
+ ```
154
+
155
+ `stage / field / reason / hint` は確認候補であり、status/codeや判定を変えません。特定不能な項目・原因は断定しません。[詳しい診断ガイド](docs/DIAGNOSTICS.ja.md)を参照してください。
156
+
157
+ 例外・プロセス終了・結果なしでも、購入を許可しません。raw入力・nonceをログに出したり、シリアライズしたEvidenceを認証済みの資格情報として扱ったりしないでください。
158
+
159
+ Gemは署名、支持する開示閉包、委任、購入/Host binding、制約・期限を検査します。Hostは認証済み・独立・最新のtrust/鍵/失効、注文・Challenge状態、時計を供給します。実行直前に現在状態と期限を再照合し、nonceの原子消費+注文CAS、不明結果の回復、最終許可・決済判断を担当します。`prepare`/`restore` は保存元の認証やnonce未使用を証明しません。
160
+
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です。
162
+
163
+ ### APIの使い分け
164
+
165
+ | 入口 | 役割 |
166
+ | --- | --- |
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も呼出側が渡します。 |
173
+ | `verify_research(**inputs)` | 同じ7入力検証経路の維持された名称。非推奨警告はありません。 |
174
+ | `verify(presentation_json:)` | 旧JSON構文検査のみ。成功Evidenceを返しません。 |
175
+
176
+ `InputBuilder.verify` の不足keywordを含む組み立て引数不正は `:rejected / :invalid_host_context`、組み立て中の依存・予期しない失敗は `:unavailable / :research_verification_unavailable` です。完全検証に入った後のcodeは維持します。一方、直接の `verify_checkout`/`verify_research` の不足・未知keywordは `:unavailable / :research_verification_unavailable` です。これらの非成功では、すべて `success? == false`、`evidence == nil` になります。形状・上限・Rubyの引数束縛上の注意は[正確な契約](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs)を参照してください。
177
+
178
+ ## 詳細リンク
179
+
180
+ - [1.x候補の公開API・失敗・profile・保存契約](docs/PUBLIC_API.md)。従来の部分検証APIも維持し、成功Evidenceを返さない意味を変えません。
181
+ - [業務情報の一連の利用とRails対応付け](docs/INPUT_BUILDER.ja.md)、[完全Ruby例](examples/input_builder.rb)、[変更前の例](examples/input_builder_before.rb)。
182
+ - [支持入力・上限・Result/Evidence契約](docs/SUPPORT_CONTRACT.md)、[Issuer/Host責務](docs/ISSUER_HOST_MINIMUM_CONTRACT.md)。
183
+ - [0.8.0 Release notes](docs/RELEASE_080.md)、[公開・撤回記録](docs/PROJECT_STATUS.md)、[変更履歴](CHANGELOG.md)。リポジトリREADMEの変更で公開Gemを再build・置換しません。
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の概念)。履歴は保存していますが、現在の連携手順や対応範囲を広げる根拠ではありません。
185
+ - [脆弱性報告](SECURITY.md)、[保守方針](docs/POST_RELEASE_MAINTENANCE.md)、[製品方針](docs/PRODUCT_VISION.md)。秘密鍵・実Mandate・個人情報を報告に含めないでください。
186
+
187
+ MIT。[LICENSE](LICENSE)を参照。
188
+
189
+ ### 購入側Direct Checkout(公開済み0.7.0)
190
+
191
+ `CheckoutJWT.verify`で承認前に販売者署名を検証し、Trusted Surfaceの
192
+ 承認バックエンドから`Buyer.issue_closed`を呼びます。Shopping Agentは
193
+ `Buyer.present_closed`で提示し、販売者は`Buyer.verify`で検証します。
194
+ Receiptは`profile_ref: Buyer::PROFILE_REF`で生成・確認します。
195
+ 1販売者・1〜8明細・複数商品と数量を一貫して扱えます。既存2profileと
196
+ Open→Agent ClosedのAPI契約は維持します。
197
+ [仕様・責任境界](docs/BUYER_DIRECT_CHECKOUT.md)と
198
+ [承認からReceiptまでの実行例](examples/direct_checkout.rb)を参照してください。
199
+ 検証成功は購買権限や実決済成功を意味しません。[短い動作確認済みサンプル](docs/RELEASE_070.md)も参照してください。
data/README.md CHANGED
@@ -1,8 +1,44 @@
1
- # AP2 Mandate Verifier — 0.6.0
1
+ # AP2 Mandate Verifier — Ruby SDK for Checkout delegation
2
2
 
3
3
  [日本語](README.ja.md)
4
4
 
5
- Published stable is **0.6.0**, adding explicitly selected multi-item support. The published Gem matches the reviewed source and approved candidate; see [the publication record](docs/PROJECT_STATUS.md#060-publication).
5
+ **Published stable: 0.8.0. Working candidate: 1.0.0, not published.**
6
+
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`:
17
+ approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
18
+ a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
19
+ `CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
20
+ multi-item profile. Provider private keys never enter Agent operations.
21
+ [API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [release sample](docs/RELEASE_080.md), [publication verification](docs/POST_RELEASE_080.md).
22
+
23
+ Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
24
+
25
+ ```sh
26
+ gem install ap2_mandate_verifier --version 0.8.0
27
+ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.8.0").full_gem_path')/examples/conditional_checkout.rb"
28
+ ```
29
+
30
+ The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
31
+ public APIs, three rows, candidate choice, different requirement quantities and
32
+ repeated products through both Receipt outcomes. Success consumes the operation;
33
+ Error requires a new policy decision; missing Receipt or uncertain effect remains
34
+ pending. Authentication, consent, enrollment, durable replay prevention and actual
35
+ order/payment execution remain app-owned. Existing users need no migration;
36
+ 0.7.0 defaults and saved formats remain unchanged.
37
+
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).
6
42
 
7
43
  ## Multiple items and quantities
8
44
 
@@ -16,27 +52,27 @@ Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile.
16
52
 
17
53
  ## Try the local demo
18
54
 
19
- The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.6.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.
20
56
 
21
57
  ## Install
22
58
 
23
59
  Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
24
60
 
25
61
  ```sh
26
- gem install ap2_mandate_verifier --version 0.6.0
62
+ gem install ap2_mandate_verifier --version 0.8.0
27
63
  ```
28
64
 
29
65
  Or add to your Gemfile:
30
66
 
31
67
  ```ruby
32
- gem "ap2_mandate_verifier", "= 0.6.0"
68
+ gem "ap2_mandate_verifier", "= 0.8.0"
33
69
  ```
34
70
 
35
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).
36
72
 
37
73
  ## Merchant signing and Receipt
38
74
 
39
- Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 0.6.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.
40
76
  Here `checkout` is the application order Hash, `key` its P-256 signing key,
41
77
  `received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
42
78
 
@@ -105,6 +141,10 @@ Do not call `prepare` again during verification or update saved hashes/reference
105
141
 
106
142
  ## Results and responsibility boundaries
107
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
+
108
148
  | Result | Meaning and next step |
109
149
  | --- | --- |
110
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. |
@@ -125,14 +165,24 @@ Exceptions, process failure and missing results also never authorize an operatio
125
165
 
126
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.
127
167
 
128
- Published 0.6.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, product 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.
129
175
 
130
176
  ### Which API should I use?
131
177
 
132
178
  | Entry | Role |
133
179
  | --- | --- |
134
- | `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.6.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
135
- | `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. |
136
186
  | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
137
187
  | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
138
188
 
@@ -140,15 +190,16 @@ Malformed assembly arguments, including missing keywords, to `InputBuilder.verif
140
190
 
141
191
  ## More detail
142
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.
143
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).
144
195
  - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
145
- - [0.6.0 Release notes](docs/RELEASE_060.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.
146
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.
147
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.
148
199
 
149
200
  MIT. See [LICENSE](LICENSE).
150
201
 
151
- ### Buyer Direct checkout (0.7.0 candidate, unpublished)
202
+ ### Buyer Direct checkout (published 0.7.0)
152
203
 
153
204
  Trusted Surface backends can verify a merchant Checkout before approval, issue a
154
205
  Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
@@ -158,4 +209,4 @@ One merchant, 1–8 lines, multiple products and quantities are supported end to
158
209
  Existing Open→Agent Closed APIs and both profiles retain their contracts.
159
210
  See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
160
211
  [runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
161
- is not purchasing authority or payment success. Candidate code is not in 0.6.0.
212
+ is not purchasing authority or payment success. See the [short verified buyer-flow sample](docs/RELEASE_070.md).
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/取得はこの追補作業では行いません。
@@ -1,7 +1,7 @@
1
- # Direct / Human Present Checkout — 0.7.0 candidate
1
+ # Direct / Human Present Checkout — 0.7.0 published
2
2
 
3
3
  This additive optional module implements Trusted Agent Provider approval of a
4
- fixed merchant-signed order. It is NOT published. Adopted source is AP2 v0.2.0,
4
+ fixed merchant-signed order. Published at 2026-11-01 03:12:46.522 UTC; [publication record](PROJECT_STATUS.md#070-publication). Adopted source is AP2 v0.2.0,
5
5
  commit `b4587ac1d055888a73b4b21750973cffba961793`; no source upgrade is made.
6
6
  The first example is one office supply purchase; **multiple products and lines
7
7
  are required and supported throughout issuance, presentation, merchant verification
@@ -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
@@ -142,7 +144,7 @@ Existing two profiles, InputBuilder save/restore, Result/Evidence, old API defau
142
144
  and legacy Receipt terminal syntax are unchanged. Direct is a new independent
143
145
  entry; existing `verify_checkout` continues to handle its prior Open→Agent Closed
144
146
  contract only. Passing Direct wire to old Receipt/default profile rejects.
145
- No dependency or Ruby support change. Compatible feature version is 0.7.0.
147
+ No dependency or Ruby support change. Compatible feature version is published 0.7.0.
146
148
 
147
149
  `test/buyer_interop.py` uses the fixed official `sd_jwt.create/verify`, unmodified
148
150
  Closed Schema, JWT helpers and independent SHA256/commitment computation.
@@ -171,10 +173,11 @@ 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
- No Gem/tag/Release publication, deployment, real payments or credentials are
180
- performed by this task.
182
+ Gem publication and its separately approved tag/Release are recorded in the
183
+ publication record. No deployment, real payments or real credentials are exercised.