ap2_mandate_verifier 1.6.1 → 1.7.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: 53f698e6233c03447e9fb25839be671cd7f9f5c4ff408591ef105b3c9bb56b93
4
- data.tar.gz: dc5abf9cd5ed43af26849387a096a5d61260dd19e4403e43668dcac18cf2cde9
3
+ metadata.gz: 9c2ce93037e11a4317d9c4c4f42ff1a9fccbe996277df3dcca9c34d41466de5f
4
+ data.tar.gz: 286a66784e21aa6de46d3efef055abd759e84147fe5593b224afada65b9e6902
5
5
  SHA512:
6
- metadata.gz: 9325702accbcbaea4a5dcc30e9ea59becad3f5388a7a84b55c2ffca8855ce8d6b3da26a3b0dad0bfc88a3594114fa59a13be9ef3df807a521419cda5b002e909
7
- data.tar.gz: d850bb7f276caef54abc4af488b565fc4387363824e30259da59f89806e3b7954d1b043b9115e37babf06c0a1292ecc96bd7c3ede989f47d78e0e2822f14df06
6
+ metadata.gz: ec58dc924497469507f0d64584130188cd3bfa0af356aef018f158025ee10013aa0f2ac2a20a920ceb3930799d4b99cad2a3d8a35e0129b6ca4215fbf9e66ae9
7
+ data.tar.gz: 1681af6d34ac0a7513c2cc5f6b5fedf7e7705f6a09ff61bf4e998eca8cd4a43e4f878095e46b9e3530bb93e68d74bc876ad94899e633921c86400a2bfa0ce005
data/README.ja.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # AP2 Mandate Verifier — Checkout・PaymentのRuby SDK
2
2
 
3
- [English](README.md) · **公開済み安定版:1.6.0** · [Quick Start](docs/QUICK_START.ja.md)
3
+ [English](README.md) · **公開済み安定版:1.6.1** · [Quick Start](docs/QUICK_START.ja.md)
4
4
 
5
5
  対応するAP2 Checkout・Payment MandateをRubyだけで発行・提示・検証できます。
6
6
  購入者が何を承認し、Agentが何を選べるか、署名済みの注文・支払いが条件を満たすかを
@@ -8,13 +8,15 @@
8
8
  **検証成功は購入・決済成功ではなく、SDKは決済を実行しません。**
9
9
 
10
10
 
11
- **対応環境:** MRI 3.4.12 / 4.0.9。公開GemはLinux ARM64・AMD64、macOS Intel・Apple Silicon、Windows Server 2022 X64でネイティブ検証に合格しました。記録したOSイメージでの実測であり、Railsデモの対応範囲とは別です。[検証範囲と再現方法](docs/PLATFORM_SUPPORT.md)を参照してください。
11
+ **対応環境:** MRI 3.4.12 / 4.0.9。既存の公開Gemネイティブ検証は**1.6.0**のLinux ARM64・AMD64、macOS Intel・Apple Silicon、Windows Server 2022 X64が対象で、新CLIの検証ではありません。[既存の検証範囲と再現方法](docs/PLATFORM_SUPPORT.md)と[1.6.1のLinux公開後検証](docs/POST_RELEASE_161.md)を分けて参照してください。Railsデモの対応範囲も別です。
12
12
 
13
13
  ## まず動かす
14
14
 
15
+ この最小SDK手順は**公開済み1.6.1**を使います。新CLIは[Gemだけで動かす組込み手順](docs/RUBY_INTEGRATION.ja.md)を使ってください。
16
+
15
17
  ```sh
16
- gem install ap2_mandate_verifier --version 1.6.0
17
- AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.0").full_gem_path')"
18
+ gem install ap2_mandate_verifier --version 1.6.1
19
+ AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.1").full_gem_path')"
18
20
  ruby "$AP2_GEM_DIR/examples/conditional_checkout.rb"
19
21
  ruby "$AP2_GEM_DIR/examples/payment.rb"
20
22
  ```
@@ -24,7 +26,7 @@ Gem同梱例で合成鍵・承認を作り、Mandateの発行・提示・検証
24
26
  アカウント・認証情報・DB・Railsは不要です。対応Ruby導入済みなら約10分が目安です。
25
27
  依存buildやDockerの初回取得には追加時間がかかる場合があります。
26
28
 
27
- **次へ:** [手順と期待出力を示すQuick Start](docs/QUICK_START.ja.md)で、
29
+ **次へ:** [手順と期待出力を示すQuick Start(1.6.0 baseline)](docs/QUICK_START.ja.md)で、
28
30
  12のUTC月と累計JPY予算超過の拒否まで試せます。
29
31
  [Dockerデモ](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)も公開済み**1.6.0**を使用し、
30
32
  ローカルのCheckout画面とRuby単体のPayment例を用意しています。
@@ -33,8 +35,9 @@ Gem同梱例で合成鍵・承認を作り、Mandateの発行・提示・検証
33
35
 
34
36
  **アプリへ組み込む場合:** [Ruby組込み・プロセス終了後の復旧ガイド](docs/RUBY_INTEGRATION.ja.md)で、
35
37
  保護されたアプリ入力、模擬結果の永続化、別プロセス復旧、安全な再送判断を確認してください。
36
- リポジトリ取得+公開1.6.0、または1.6.1候補の同梱CLIで実行します。
37
- 公開1.6.0には新CLIは含まれません。候補をregistry公開版と扱う前に1.6.1の公開状態を確認してください。
38
+ リポジトリ取得+公開1.6.0、または**公開済み1.6.1**の同梱CLIで実行します。
39
+ 1.6.1のCLIにはリポジトリ取得が不要です。公開1.6.0には新CLIは含まれません。
40
+ [1.6.1の配布物と検証記録](docs/POST_RELEASE_161.md)を参照してください。
38
41
 
39
42
  Checkoutは注文内容、Checkout Mandateはその承認・委任を表します。
40
43
  Payment MandateはCheckout承認を参照し、支払い条件を追加します。
@@ -165,3 +168,10 @@ end
165
168
 
166
169
 
167
170
  </details>
171
+
172
+ ### 次の候補:Payment以降の診断
173
+
174
+ 1.7.0候補ではPayment・Receipt・受理結果の任意の診断と、呼び出しごとの
175
+ `start_with_diagnostic`を追加します。従来の`start`のExecution/nil契約は維持します。
176
+ この変更では未公開です。[診断ガイド](docs/DIAGNOSTICS.ja.md)に英日ヒント、真正なError Receipt、
177
+ 結果不明の扱いと限界をまとめています。診断は再決済や利用枠解放の許可ではありません。
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # AP2 Mandate Verifier — Ruby SDK for Checkout and Payment
2
2
 
3
- [日本語](README.ja.md) · **Published stable: 1.6.0** · [Quick Start](docs/QUICK_START.md)
3
+ [日本語](README.ja.md) · **Published stable: 1.6.1** · [Quick Start](docs/QUICK_START.md)
4
4
 
5
5
  Issue, present and verify supported AP2 Checkout and Payment Mandates in plain Ruby.
6
6
  Use this Gem when your app needs to check what a buyer approved, what an Agent may
@@ -8,13 +8,15 @@ choose, and whether signed Checkout/Payment data stays within those conditions.
8
8
  No Rails dependency. **Verification success is not purchase or payment success; the SDK never executes payments.**
9
9
 
10
10
 
11
- **Platforms:** MRI 3.4.12 / 4.0.9; native published-Gem checks passed on Linux ARM64/AMD64, macOS Intel/Apple Silicon and Windows Server 2022 X64. These observations cover the recorded OS images; Rails demo compatibility is separate. See [platform evidence and reproduction](docs/PLATFORM_SUPPORT.md).
11
+ **Platforms:** MRI 3.4.12 / 4.0.9. Existing native published-Gem checks cover **1.6.0** on Linux ARM64/AMD64, macOS Intel/Apple Silicon and Windows Server 2022 X64, not the new CLI. See [platform evidence and reproduction](docs/PLATFORM_SUPPORT.md) and the separate [1.6.1 Linux publication checks](docs/POST_RELEASE_161.md). Rails demo compatibility is separate.
12
12
 
13
13
  ## Start here
14
14
 
15
+ This minimal SDK quick start uses **published 1.6.1**. For its integration CLI, use the [Gem-only integration instructions](docs/RUBY_INTEGRATION.md).
16
+
15
17
  ```sh
16
- gem install ap2_mandate_verifier --version 1.6.0
17
- AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.0").full_gem_path')"
18
+ gem install ap2_mandate_verifier --version 1.6.1
19
+ AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.1").full_gem_path')"
18
20
  ruby "$AP2_GEM_DIR/examples/conditional_checkout.rb"
19
21
  ruby "$AP2_GEM_DIR/examples/payment.rb"
20
22
  ```
@@ -25,7 +27,7 @@ Error Receipt reports failure. No account, credentials, database or Rails requir
25
27
  Allow about ten minutes with a supported Ruby already installed; dependency builds
26
28
  and Docker's first download can take longer.
27
29
 
28
- **Next:** [step-by-step Quick Start and expected output](docs/QUICK_START.md),
30
+ **Next:** [step-by-step Quick Start and expected output (1.6.0 baseline)](docs/QUICK_START.md),
29
31
  including twelve UTC months and a cumulative JPY budget rejection.
30
32
  [Docker demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)
31
33
  uses published **1.6.0**, with local Checkout screens and Ruby Payment examples.
@@ -35,9 +37,9 @@ uses published **1.6.0**, with local Checkout screens and Ruby Payment examples.
35
37
  **Integrating a real application?** Start with the [Ruby integration and restart
36
38
  recovery guide](docs/RUBY_INTEGRATION.md): protected application inputs, persistent
37
39
  mock results, separate-process recovery and safe retry decisions. Use this repository
38
- with published 1.6.0, or the bundled CLI in the 1.6.1 candidate. Public 1.6.0 does
39
- not include this CLI; verify the 1.6.1 publication status before treating a candidate
40
- as a registry release.
40
+ with published 1.6.0, or install **published 1.6.1** for the bundled CLI without a
41
+ repository checkout. Public 1.6.0 does not include this CLI. See the
42
+ [exact 1.6.1 distribution and verification](docs/POST_RELEASE_161.md).
41
43
 
42
44
  Checkout describes the order; a Checkout Mandate records approval/delegation for it.
43
45
  A Payment Mandate adds payment conditions and references the Checkout approval.
@@ -177,3 +179,11 @@ Do not call `prepare` again during verification or update saved hashes/reference
177
179
 
178
180
 
179
181
  </details>
182
+
183
+ ### Next candidate: Payment diagnostics
184
+
185
+ The 1.7.0 candidate adds optional Payment/Receipt/acceptance diagnostics and a
186
+ call-local `start_with_diagnostic` API while preserving `start`'s Execution/nil
187
+ contract. It is not published by this change. See [diagnostics](docs/DIAGNOSTICS.md)
188
+ for English/Japanese hints, authentic Error Receipt semantics and unknown-result
189
+ limits. Diagnostics never authorize a payment retry or quota release.
@@ -1,8 +1,10 @@
1
- # 失敗時の診断(公開済み 0.4.0)
1
+ # 診断
2
+
3
+ Checkout・InputBuilderは0.4.0で導入。Payment以降は1.7.0候補で追加。
2
4
 
3
5
  Gem内部を追わず、失敗した検査と次の確認候補を取得できます。診断は補助情報です。
4
6
  既存呼び出し、status/code、固定profile、Fail Closed、非成功時のEvidenceなし契約は不変です。
5
- 成功時のdiagnosticはnilです。診断処理が失敗してもnilとなり、検証結果は変わりません。
7
+ Checkout・InputBuilderの成功時のdiagnosticはnilです。診断処理が失敗してもnilとなり、検証結果は変わりません。
6
8
  ヒントから購入・決済の許可を判断しないでください。
7
9
 
8
10
  ## Before / After
@@ -74,3 +76,82 @@ ruby examples/input_builder.rb unsupported_saved_format
74
76
  unknown_field、unsupported_saved_formatになります。合成fixtureの固定時刻を使います。
75
77
  業務データの対応・保存責務は[InputBuilderガイド](INPUT_BUILDER.ja.md)を参照してください。
76
78
  Gemの公開は、実Issuer接続、本番購入許可、Phase 2-B移行を意味しません。
79
+
80
+ ## Payment以降の診断(1.7.0候補、この変更では未公開)
81
+
82
+ 上記0.4.0の説明はCheckout・InputBuilderの導入時期と過去の検証記録です。
83
+ 今回の追加は1.7.0候補です。Payment・Receiptのcode、述語、例外契約は維持します。
84
+ Direct・条件付き・Selective・Longの結果で`diagnostic`を取得できます。
85
+ 成功したPaymentはnil。真正で参照が一致するError Receiptは**検証成功**であり、
86
+ `payment_rejected? == true`、`payment_succeeded? == false`、診断は`reported_error`です。
87
+ 再決済や利用枠解放の許可ではありません。
88
+
89
+ ```ruby
90
+ payment = AP2MandateVerifier::Payment.verify(**payment_inputs)
91
+ puts payment.code # 拒否時は従来どおり :payment_verification_failed
92
+ puts payment.diagnostic&.to_h(locale: :ja)
93
+ # stage: :payment_verification, field: nil,
94
+ # reason: :payment_time_mismatch, hint: "..."
95
+
96
+ # 1回の試行ではどちらか一方だけ。診断のためにstartを繰り返さない。
97
+ observation = service.start_with_diagnostic(ticket: ticket,
98
+ verification_inputs: fresh_inputs)
99
+ execution = observation.execution # Executionまたはnil
100
+ puts observation.diagnostic&.to_h(locale: :ja)
101
+ # 従来のservice.start(...)は今までどおりExecutionまたはnil。
102
+ # nilなら決済を開始しない。未実行や安全な再試行を意味しない。
103
+
104
+ receipt = AP2MandateVerifier::PaymentReceipt.verify(**receipt_inputs)
105
+ if receipt.verified?
106
+ puts receipt.payment_rejected? # 真正なErrorならtrue
107
+ else
108
+ puts receipt.code # :payment_receipt_verification_failed
109
+ end
110
+ puts receipt.diagnostic&.to_h(locale: :ja)
111
+ ```
112
+
113
+ 引数・service・ticketの準備は[組み込み例](RUBY_INTEGRATION.ja.md)を参照してください。
114
+ この抜粋では独立した信頼情報、時刻、注文、保護された承認、永続保存先と決済処理を省略しています。
115
+ 診断の取得で検証・予約・開始・決済・保存先の再読込は行いません。
116
+ 旧版・成功・診断生成失敗で診断がnilでも、元の判定は変わりません。
117
+
118
+ ### 段階・理由と確認できる事実
119
+
120
+ | stage | 代表reason | 確認できる事実 |
121
+ | --- | --- | --- |
122
+ | `payment_verification` | `checkout_not_verified` | 内部Checkout検証が成功していない。原因は断定しない |
123
+ | `payment_verification` | `checkout_binding_mismatch` | 既存のCheckoutとPaymentの照合が不一致 |
124
+ | `payment_verification` | `payment_time_mismatch` | 既存のPayment内容有効期間検査が不一致 |
125
+ | `payment_verification` | `payment_conditions_mismatch` | 完全開示profileの既存支払い条件検査が不一致 |
126
+ | `payment_verification` | `payment_binding_mismatch` | 期待Paymentまたは証明の結び付けが不一致 |
127
+ | `payment_receipt_verification` | `receipt_reference_mismatch` | 発行者・支払いID・原Payment参照の既存照合が不一致 |
128
+ | `payment_receipt_verification` | `receipt_time_mismatch` | Receipt発行時刻または独立した許容期間が不一致 |
129
+ | `payment_receipt_verification` | `reported_error` | 真正なError報告。決済成功・再試行許可ではない |
130
+ | `payment_acceptance` | `pending`・`unknown`・`receipt_error` | 既存の結果status。追加読込による推測はしない |
131
+ | `payment_acceptance` | `conflict`・`unavailable` | 保存先の例外区分のみ。具体的原因・保存確定状態は不明 |
132
+ | `payment_execution` | `saved_binding_mismatch` | 最新指示または署名原文が保存済み記録と不一致 |
133
+ | `payment_execution` | `undetermined` | 実行ハンドルなし。期限切れ・競合・不確実な保存の識別はできない |
134
+
135
+ `invalid_arguments`はPayment・Receipt・Selective検証のキーワード形状拒否です。
136
+ `signed_input_rejected`は署名入力に関する型付き拒否で、暗号署名の失敗とは限りません。
137
+ `verification_unavailable`は依存関係・検証処理の明示的な利用不可です。
138
+ それ以外の例外は`undetermined`とし、例外全文やシナリオ名から原因を推測しません。
139
+ Mandate・鍵・nonce・非開示候補・支払い情報・外部例外全文は診断へ含めません。
140
+
141
+ 診断範囲は網羅的ではありません。Direct・条件付きからpolicy・継続・Longへ共通検査は届きますが、
142
+ 不正な構造・Selective開示・詳細なPISPや日付制約・Long権限・期間管理は詳細不明の場合があります。
143
+ 保存先の予約拒否だけでは、利用枠・回数超過と承認欠落・失効・その他の保護状態不正を区別できません。
144
+ 保存先ガイドに従って保護された承認、現在の期間・利用枠、保存済み処理を確認し、特定の原因と断定しないでください。
145
+ Receipt検証は実決済の完了証明ではありません。不明・タイムアウト・真正なErrorは自動再決済や利用枠解放の根拠になりません。
146
+
147
+ ### 保存と並行性
148
+
149
+ `StartResult`は呼び出しごとの変更不能オブジェクトです。serviceの`last_diagnostic`や
150
+ スレッド・Fiber共有の診断変数はありません。受理Resultの診断はfinish・reconcile・lookup・unknownも対象です。
151
+ 保存形式とStoreの公開インターフェースは変更しません。独自アダプターの結果に診断がない場合は
152
+ `respond_to?(:diagnostic)`とnilで扱ってください。
153
+
154
+ 保存するのはカタログ識別子だけとし、`Diagnostic.payment_flow(stage, reason)`で安全な定義へ戻せます。
155
+ 未知の組合せはnil、fieldは常にnilです。保存済みstage・field・reasonの一致を検査し、
156
+ 任意の保存済みhintを表示しないでください。未知値から原因を補完せず、表示時に復旧処理を始めないでください。
157
+ 将来のminor版で詳細が追加され得るため未知・nilのfallbackを持ち、制御は従来のstatus・codeに従います。
data/docs/DIAGNOSTICS.md CHANGED
@@ -1,8 +1,10 @@
1
- # Failure diagnostics (published 0.4.0)
1
+ # Diagnostics
2
+
3
+ Checkout/InputBuilder introduced in 0.4.0; Payment flow added in the 1.7.0 candidate.
2
4
 
3
5
  Diagnostics help you inspect a failed check without reading gem internals. They
4
6
  are supplemental: existing calls, status/code, fixed profile, Fail Closed and
5
- non-success `evidence == nil` are unchanged. A successful result has
7
+ non-success `evidence == nil` are unchanged. A successful Checkout/InputBuilder result has
6
8
  `diagnostic == nil`. A diagnostic failure also returns nil and cannot change a
7
9
  verification result. Never make a payment/authorization decision from a hint.
8
10
 
@@ -86,3 +88,97 @@ reasons `missing_required_field`, `invalid_type`, `unknown_field` and
86
88
  [InputBuilder](INPUT_BUILDER.md) for data mapping and storage responsibilities.
87
89
  Gem availability does not imply real Issuer interoperability, production
88
90
  authorization or Phase 2-B GO.
91
+
92
+ ## Payment flow (1.7.0 candidate; not published by this change)
93
+
94
+ The original 0.4.0 sections above describe Checkout/InputBuilder diagnostics and
95
+ historical evidence, not the version to install for this addition. Payment and
96
+ Receipt `code`, predicates and exception contracts are unchanged. Direct,
97
+ conditional, selective and Long verification expose `result.diagnostic`;
98
+ successful Payment verification has nil. Authentic matching Error Receipts are
99
+ **verified**, with `payment_rejected? == true`, `payment_succeeded? == false`,
100
+ and an explanatory `reported_error` diagnostic. This is not retry permission.
101
+
102
+ ```ruby
103
+ payment = AP2MandateVerifier::Payment.verify(**payment_inputs)
104
+ puts payment.code # still :payment_verification_failed on every failure
105
+ puts payment.diagnostic&.to_h(locale: :en)
106
+ # e.g. {stage: :payment_verification, field: nil,
107
+ # reason: :payment_time_mismatch, hint: "..."}
108
+
109
+ # Choose ONE start entry point per attempt, never both for diagnosis.
110
+ observation = service.start_with_diagnostic(ticket: ticket,
111
+ verification_inputs: fresh_inputs)
112
+ execution = observation.execution # Execution or nil
113
+ puts observation.diagnostic&.to_h(locale: :en)
114
+ # Existing service.start(...) still returns exactly Execution or nil.
115
+ # Do not dispatch when execution is nil. Nil proves neither non-execution
116
+ # nor that repeating start/payment is safe.
117
+
118
+ receipt = AP2MandateVerifier::PaymentReceipt.verify(**receipt_inputs)
119
+ if receipt.verified?
120
+ puts receipt.payment_rejected? # true for an authentic Error Receipt
121
+ else
122
+ puts receipt.code # :payment_receipt_verification_failed
123
+ end
124
+ puts receipt.diagnostic&.to_h(locale: :en)
125
+ ```
126
+
127
+ `payment_inputs`, `fresh_inputs`, `receipt_inputs`, `service` and `ticket` above
128
+ come from the [Ruby integration example](RUBY_INTEGRATION.md), not received hints.
129
+ The application supplies independent trust, clock, order, protected approval and
130
+ persistent storage. The excerpt omits those inputs and all processor operations.
131
+ No diagnostic getter repeats verification, reservation, start, settlement or reads
132
+ additional storage. An absent diagnostic is supported (old versions, success or
133
+ failed diagnostic generation); it never turns failure into success.
134
+
135
+ ### Stages, facts and limits
136
+
137
+ | Stage | Representative reason | Fact established |
138
+ | --- | --- | --- |
139
+ | `payment_verification` | `checkout_not_verified` | Nested Checkout verification did not succeed, not proof of its cause |
140
+ | `payment_verification` | `checkout_binding_mismatch` | An existing Checkout/payment binding comparison failed |
141
+ | `payment_verification` | `payment_time_mismatch` | Existing Payment content validity comparison failed |
142
+ | `payment_verification` | `payment_conditions_mismatch` | An existing complete-profile payment condition failed |
143
+ | `payment_verification` | `payment_binding_mismatch` | Expected payment or proof binding comparison failed |
144
+ | `payment_receipt_verification` | `receipt_reference_mismatch` | Existing issuer/payment-ID/original Payment reference comparison failed |
145
+ | `payment_receipt_verification` | `receipt_time_mismatch` | Existing Receipt or independent time window comparison failed |
146
+ | `payment_receipt_verification` | `reported_error` | Authentic matching Receipt reported Error, not verified settlement success |
147
+ | `payment_acceptance` | `pending`, `unknown`, `receipt_error` | Existing result status only, no extra state lookup |
148
+ | `payment_acceptance` | `conflict`, `unavailable` | Store reported that class of error, not a specific cause or commit state |
149
+ | `payment_execution` | `saved_binding_mismatch` | Fresh instruction or original signed wires differ from saved state |
150
+ | `payment_execution` | `undetermined` | No execution handle; cannot distinguish expiry, competing start or uncertain commit |
151
+
152
+ `invalid_arguments` identifies rejected keyword shape on Payment/Receipt/Selective
153
+ verify. `signed_input_rejected` describes a typed signed-input rejection, **not
154
+ necessarily a cryptographic signature failure**. `verification_unavailable`
155
+ describes an explicitly unavailable dependency/check. Other exceptions use
156
+ `undetermined`, never exception-message matching. Diagnostics do not disclose raw
157
+ Mandates, keys, nonce, candidate sets, payment data or exception text.
158
+
159
+ The same Payment checks feed Direct/conditional, policy, recurring and Long
160
+ profiles, but **coverage is deliberately not exhaustive**: malformed shapes,
161
+ selective disclosure checks, detailed PISP/date policies, Long authority and
162
+ period policies can remain `undetermined`. A store's rejected quota reservation
163
+ does not distinguish exhausted budget/count from missing/revoked approval or
164
+ other invalid protected state. Inspect protected approval, current period/quota
165
+ and stored attempts according to the store guide, without assuming any one cause.
166
+ Receipt validation does not establish real processor settlement. Unknown results,
167
+ timeouts and authentic Error never authorize automatic retries or quota release.
168
+
169
+ ### Persistence and concurrency
170
+
171
+ `StartResult` is immutable and call-local; there is no `last_diagnostic` on a
172
+ service and no shared thread/fiber diagnostic slot. `Result#diagnostic` on
173
+ acceptance also covers finish, reconcile, lookup and unknown results. Existing
174
+ store interfaces and persisted formats are unchanged. Custom adapters returning
175
+ nonstandard result objects need not expose diagnostics; applications may use
176
+ `respond_to?(:diagnostic)` and handle nil.
177
+
178
+ Persist catalog identifiers only. `Diagnostic.payment_flow(stage, reason)`
179
+ returns a trusted immutable catalog entry or nil for an unknown pair. Its field
180
+ is always nil. Validate the stored triple against that result; do not render
181
+ arbitrary stored hints, translate unknown values into a cause, or automatically
182
+ start recovery while reading diagnostics. Identifiers may gain detail in later
183
+ minor versions; keep an unknown/nil fallback and use existing status/code for
184
+ control flow. Do not use hints or diagnostic presence as authorization.
data/docs/PUBLIC_API.md CHANGED
@@ -229,3 +229,14 @@ For the explicit selective Checkout profile, Evidence `original_root_graph_closu
229
229
  ## 1.6.0 candidate: explicit long content / short proof
230
230
 
231
231
  `LongPayment` opts into separate long complete Checkout/Payment profiles while preserving existing defaults. `issue_checkout_open/issue_checkout_closed/present_checkout` and `details/issue_open/issue_closed/present/verify` follow existing role-separated inputs. `approved_pair!`, `current_authority!` and `authority!` are protected-backend helpers; none enrolls consent by itself. `PaymentAcceptance::LongSQLiteStore` adds explicit schema3 authority/period state, `authorize_series!`, CAS `update_authority!/invalidate_authority!/replace_root!/revoke_root!`, inherited permanent `revoke_series!` and current `usage`. `Execution.valid_until` exposes the checked short start deadline, including on existing acceptance results; it does not make an external processor call atomic or revoke an already returned handle. See [exact profile, UTC windows, trust duties, migration and SDK differences](LONG_PAYMENT.md).
232
+
233
+ ### Payment diagnostics (1.7.0 candidate)
234
+
235
+ `Payment::Verification#diagnostic` (including Selective/Long results),
236
+ `PaymentReceipt::Verification#diagnostic`, and `PaymentAcceptance::Result#diagnostic`
237
+ are optional immutable `Diagnostic` objects. `PaymentAcceptance::Service#start_with_diagnostic`
238
+ accepts the same keywords as `start`, runs the same single attempt, and returns an
239
+ immutable `StartResult` with `execution` (Execution or nil) and `diagnostic`.
240
+ Existing `start` retains Execution/nil, with unchanged exception normalization.
241
+ `Diagnostic.payment_flow(stage, reason)` restores a known catalog pair or nil;
242
+ this is not evidence or permission to execute. See [diagnostic limits](DIAGNOSTICS.md#payment-flow-170-candidate-not-published-by-this-change).
@@ -1,4 +1,7 @@
1
- # 1.6.1 patch release preparation
1
+ # 1.6.1 patch release preparation (historical)
2
+
3
+ **Published on 2026-11-10:** see the [publication and verification record](POST_RELEASE_161.md).
4
+ The preparation steps and gates below describe the prepublication process, not the current release status.
2
5
 
3
6
  ## Scope and status
4
7
 
@@ -10,9 +13,9 @@ The package includes the CLI, two helpers and English/Japanese guides already re
10
13
  The sample remains synthetic and Linux/Docker-validated; it grants no production or real-payment authority.
11
14
  The legacy published examples and the public **1.6.0** archive audits remain unchanged.
12
15
 
13
- **Candidate, not published:** registry publication, tag and GitHub Release are pending.
14
- Do not infer publication from this document, a green CI run, version metadata, or a merge.
15
- The current public baseline remains [1.6.0](https://github.com/cuichangquan/ap2-mandate-verifier/blob/main/docs/POST_RELEASE_160.md).
16
+ **Historical candidate status:** publication, tag and GitHub Release were pending during preparation.
17
+ Use the linked publication record for their verified current status; a green CI run or merge alone is not publication evidence.
18
+ The existing platform baseline remains [1.6.0](https://github.com/cuichangquan/ap2-mandate-verifier/blob/main/docs/POST_RELEASE_160.md).
16
19
 
17
20
  ## Required evidence and gates
18
21
 
@@ -8,7 +8,7 @@
8
8
  合成の登場者とSQLiteの模擬processorだけを使い、Rails・A2A・外部アカウント・実決済は不要です。
9
9
  **組込みを理解するための実装例であり、本番の認証・認可backendではありません。**
10
10
 
11
- ## 1. Dockerと公開Gemで動かす
11
+ ## 1. Docker(1.6.0 baseline)または公開済み1.6.1 Gemで動かす
12
12
 
13
13
  Docker導入済みが前提です。ホストへのRuby・SQLiteインストールは不要です。
14
14
  新しいcheckoutから実行します:
@@ -36,24 +36,28 @@ SDKはインストール先のGemディレクトリを指す必要があり、
36
36
  公開Gemでの実行を確認する際は`-Ilib`や`RUBYLIB`を追加しないでください。
37
37
  既存の`conditional_checkout.rb`、`payment.rb`、`payment_acceptance.rb`はGemだけで
38
38
  取得できる例です。[Quick Start](https://github.com/cuichangquan/ap2-mandate-verifier/blob/main/docs/QUICK_START.ja.md)に同梱場所の確認手順があります。
39
- 新CLIと補助ファイルは`1.6.1`に同梱します。公開前はsource-built **1.6.1候補**を
40
- 意味し、registryの公開版ではありません。公開1.6.0とは出所が異なり、
41
- 公開1.6.0のインストールだけでは新CLIを取得できません。
42
- 公開済みと扱う前に[リリース準備記録](RELEASE_161_CANDIDATE.md)とRubyGemsの版情報を確認してください。
39
+ 新CLIと補助ファイルは**公開済み1.6.1**に同梱しています。
40
+ 公開1.6.0のインストールだけでは新CLIを取得できません。上記Docker手順は意図的に
41
+ 公開1.6.0+リポジトリの実装例を維持しており、Gemだけの1.6.1実行とは別です。
42
+ [1.6.1の公開記録](POST_RELEASE_161.md)を参照してください。
43
43
 
44
- 1.6.1と任意のSQLite driverを分離したRuby環境へ導入した後は、同梱CLIの実行に
45
- リポジトリは不要です:
44
+ 既存の分離したRuby環境(MRI 3.4.12または4.0.9)へ、以下の公開版とSQLite driverを
45
+ 版固定で導入します。SQLiteはSDKでは任意ですが、この永続化サンプルでは必要です。
46
+ 同梱CLIの実行にリポジトリは不要です:
46
47
 
47
48
  ```sh
48
- AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier").full_gem_path')"
49
+ gem install ap2_mandate_verifier --version 1.6.1 --no-document
50
+ gem install sqlite3 --version 2.10.2 --no-document
51
+ AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.1").full_gem_path')"
49
52
  test -f "$AP2_GEM_DIR/examples/ruby_integration.rb"
50
53
  ruby "$AP2_GEM_DIR/examples/ruby_integration.rb" init /tmp/ap2-integration-new
51
54
  ruby "$AP2_GEM_DIR/examples/ruby_integration.rb" run /tmp/ap2-integration-new success
52
55
  ```
53
56
 
54
57
  `test`は同梱確認であり、別sourceへfallbackするものではありません。新しい保存先を使い、
55
- `init`を通すために既存状態を削除しないでください。次版公開までは、上記Docker/リポジトリ
56
- 経路が公開Gemを使う再現手順です。1.6.1の最終archive公開には別途Gateがあります。
58
+ `init`を通すために既存状態を削除しないでください。リポジトリのsourceを重ねないでください。
59
+ 以下は引き続きDocker/baseline経路を示します。Gemだけの1.6.1では同じsubcommandを
60
+ `ruby "$AP2_GEM_DIR/examples/ruby_integration.rb"`で呼び、永続的なローカル状態パスを指定します。
57
61
 
58
62
  時計はすべて仮想です。初期epochは**1,800,000,000**で、実時計を使いません。
59
63
  Mandate/challengeの期限は+60秒、遅延Receiptは独立した検証窓内の+120秒を使います。
@@ -135,7 +139,7 @@ CLIは完了したコマンドごとにJSON要約を出力します。正常系
135
139
 
136
140
  `ticket`は有無のbooleanだけで、実行能力の値ではありません。
137
141
  `sdk_version`、`sdk_load`、`ruby`、`fixture_clock`は実行環境を示します。Docker/公開版経路では
138
- `1.6.0`、`installed_gem`、`4.0.9`、`1800000000`が期待値です。1.6.1候補の同梱例では
142
+ `1.6.0`、`installed_gem`、`4.0.9`、`1800000000`が期待値です。公開済み1.6.1の同梱例では
139
143
  `sdk_version: 1.6.1`と実際に使用したRubyの版が出力されます。
140
144
  クラッシュ出力には`simulated_process_exit: 75`が付きます。照会結果がなければ
141
145
  `event: operator_reconciliation_required`、`result: unknown`となり、SDK状態は
@@ -10,7 +10,7 @@ It uses synthetic actors and a SQLite mock processor, without Rails, A2A, extern
10
10
  accounts or real payments. It is an integration demonstrator, **not a production
11
11
  authorization backend**.
12
12
 
13
- ## 1. Run with Docker and the published Gem
13
+ ## 1. Run with Docker (1.6.0 baseline) or the published 1.6.1 Gem
14
14
 
15
15
  Prerequisite: an existing Docker installation. No Ruby or SQLite installation on
16
16
  the host is needed. From a fresh repository checkout:
@@ -38,17 +38,19 @@ The SDK path must be the installed Gem directory, not this repository's `lib`.
38
38
  Do not add `-Ilib` or set `RUBYLIB` when claiming a published-Gem run. Existing
39
39
  `conditional_checkout.rb`, `payment.rb` and `payment_acceptance.rb` are already
40
40
  Gem-only examples. Follow the [Quick Start](https://github.com/cuichangquan/ap2-mandate-verifier/blob/main/docs/QUICK_START.md) to locate them.
41
- The CLI and its helper files are packaged in `1.6.1`. Before publication, this
42
- means the source-built **1.6.1 candidate**, not a registry release. Its provenance
43
- is different from public 1.6.0; installing public 1.6.0 alone does not supply this CLI.
44
- Check the [release preparation](RELEASE_161_CANDIDATE.md) and RubyGems version
45
- record before treating an archive as published.
41
+ The CLI and its helper files are now included in **published 1.6.1**. Installing
42
+ public 1.6.0 alone does not supply this CLI. The Docker route above intentionally
43
+ retains public 1.6.0 plus repository example source; it is not a Gem-only 1.6.1 run.
44
+ See the [1.6.1 publication record](POST_RELEASE_161.md).
46
45
 
47
- Once 1.6.1 has been installed in an isolated Ruby environment with the
48
- optional SQLite driver, no repository is needed to run its packaged CLI:
46
+ In an existing isolated Ruby environment (MRI 3.4.12 or 4.0.9), install the exact
47
+ public version and SQLite driver below. SQLite is optional for the SDK but required
48
+ by this durable sample. No repository is needed to run the packaged CLI:
49
49
 
50
50
  ```sh
51
- AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier").full_gem_path')"
51
+ gem install ap2_mandate_verifier --version 1.6.1 --no-document
52
+ gem install sqlite3 --version 2.10.2 --no-document
53
+ AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.1").full_gem_path')"
52
54
  test -f "$AP2_GEM_DIR/examples/ruby_integration.rb"
53
55
  ruby "$AP2_GEM_DIR/examples/ruby_integration.rb" init /tmp/ap2-integration-new
54
56
  ruby "$AP2_GEM_DIR/examples/ruby_integration.rb" run /tmp/ap2-integration-new success
@@ -56,8 +58,9 @@ ruby "$AP2_GEM_DIR/examples/ruby_integration.rb" run /tmp/ap2-integration-new su
56
58
 
57
59
  The `test` is a packaging check, not a fallback to another source. Use a new
58
60
  destination; do not remove an old state directory to make `init` succeed.
59
- Until a new version is published, the Docker/repository route above is the
60
- reproducible public route. Publication of the exact 1.6.1 archive is a separate gate.
61
+ Do not add a repository source overlay. The commands below continue to show the
62
+ Docker/baseline route; for Gem-only 1.6.1, invoke the same subcommands using
63
+ `ruby "$AP2_GEM_DIR/examples/ruby_integration.rb"` and a persistent local state path.
61
64
 
62
65
  All example time is virtual: the initial epoch is **1,800,000,000**, never the
63
66
  wall clock. Mandate/challenge expiry is +60 seconds; the delayed Receipt uses
@@ -148,7 +151,7 @@ path includes these fields (runtime metadata is omitted here):
148
151
 
149
152
  `ticket` is only a boolean, never the capability. `sdk_version`, `sdk_load`,
150
153
  `ruby` and `fixture_clock` identify the runtime. The Docker/public route reports
151
- `1.6.0`, `installed_gem`, `4.0.9` and `1800000000`; the bundled 1.6.1 candidate
154
+ `1.6.0`, `installed_gem`, `4.0.9` and `1800000000`; the published 1.6.1 bundled CLI
152
155
  reports `sdk_version: 1.6.1` and the Ruby version actually used. Crash output carries
153
156
  `simulated_process_exit: 75`. Missing query results report
154
157
  `event: operator_reconciliation_required` and `result: unknown`; the SDK may
@@ -8,7 +8,11 @@ module AP2MandateVerifier
8
8
  FIELDS = %w[transaction_id payee payment_amount payment_instrument].freeze
9
9
  MAX_LIFETIME = 600
10
10
  class Invalid < ArgumentError
11
- def initialize = super("invalid payment information")
11
+ attr_reader :diagnostic_reason
12
+ def initialize
13
+ @diagnostic_reason = :undetermined
14
+ super("invalid payment information")
15
+ end
12
16
  end
13
17
  class Presentation
14
18
  attr_reader :open_sd_jwt, :closed_sd_jwt
@@ -20,9 +24,10 @@ module AP2MandateVerifier
20
24
  private_class_method :new
21
25
  end
22
26
  class Verification
23
- attr_reader :code, :payment, :reference, :expires_at
24
- def initialize(payment = nil, wire = nil)
27
+ attr_reader :code, :payment, :reference, :expires_at, :diagnostic
28
+ def initialize(payment = nil, wire = nil, reason: :undetermined)
25
29
  @code = payment ? :payment_verified : :payment_verification_failed
30
+ @diagnostic = PaymentDiagnostics.build(:payment_verification, reason) unless payment
26
31
  if payment
27
32
  @payment = ResearchEvidence.send(:copy_frozen, payment)
28
33
  @reference = Payment.send(:digest, wire).freeze
@@ -174,53 +179,54 @@ module AP2MandateVerifier
174
179
  when :direct
175
180
  raise Invalid if open_sd_jwt || expected_agent_public_key_pem || expected_audience || expected_nonce
176
181
  checked = Buyer.verify(**checkout_inputs)
177
- raise Invalid unless checked.verified? && expected.fetch("transaction_id") == checked.checkout_hash
182
+ raise PaymentDiagnostics.invalid(Invalid, :checkout_not_verified) unless checked.verified?
183
+ raise PaymentDiagnostics.invalid(Invalid, :checkout_binding_mismatch) unless expected.fetch("transaction_id") == checked.checkout_hash
178
184
  bind_checkout!(expected, checked.checkout)
179
185
  claims, wire = verified_root!(closed_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
180
186
  when :conditional
181
187
  checked = AP2MandateVerifier.verify_checkout(**checkout_inputs)
182
- raise Invalid unless checked.success?
188
+ raise PaymentDiagnostics.invalid(Invalid, :checkout_not_verified) unless checked.success?
183
189
  checkout = checkout_inputs.fetch(:host_checkout_jws)
184
- raise Invalid unless expected.fetch("transaction_id") == digest(checkout)
190
+ raise PaymentDiagnostics.invalid(Invalid, :checkout_binding_mismatch) unless expected.fetch("transaction_id") == digest(checkout)
185
191
  # Fully verified Host evidence binds independent Merchant order state.
186
192
  binding = checked.evidence["checkout_binding"]
187
193
  amount = expected.fetch("payment_amount")
188
- raise Invalid unless expected.fetch("payee").fetch("id") == binding.fetch("merchant_id") &&
194
+ raise PaymentDiagnostics.invalid(Invalid, :checkout_binding_mismatch) unless expected.fetch("payee").fetch("id") == binding.fetch("merchant_id") &&
189
195
  amount.fetch("currency") == binding.fetch("currency") && amount.fetch("amount") == binding.fetch("expected_total")
190
196
  # Full Checkout verifier already authenticated these exact JWT bytes.
191
197
  payload = jwt_payload!(checkout, "JWT")
192
198
  bind_checkout!(expected, payload)
193
199
  opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
194
200
  open!(opening, profile_ref: profile_ref); valid_now!(opening, verified_at)
195
- raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(expected_agent_public_key_pem)}
201
+ raise PaymentDiagnostics.invalid(Invalid, :payment_binding_mismatch) unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(expected_agent_public_key_pem)}
196
202
  terminal, wire = final!(closed_sd_jwt, conditional: true, profile_ref: profile_ref)
197
203
  RootSignature.verified_payload!(wire.split("~", -1).first, expected_agent_public_key_pem,
198
204
  expected_typ: "kb+sd-jwt", max_bytes: 32_768)
199
205
  expected_audience = InputValidator.snapshot!(expected_audience, max_bytes: 512)
200
206
  expected_nonce = InputValidator.snapshot!(expected_nonce, max_bytes: 512)
201
207
  text!(expected_audience, 512); text!(expected_nonce, 512)
202
- raise Invalid unless terminal.fetch("aud") == expected_audience && terminal.fetch("nonce") == expected_nonce &&
208
+ raise PaymentDiagnostics.invalid(Invalid, :payment_binding_mismatch) unless terminal.fetch("aud") == expected_audience && terminal.fetch("nonce") == expected_nonce &&
203
209
  terminal.fetch("sd_hash") == digest(root) && terminal.fetch("iat") <= verified_at &&
204
210
  verified_at - terminal.fetch("iat") <= 300
205
211
  claims = terminal.fetch("delegate_payload").first
206
212
  closed!(claims, profile_ref: profile_ref); valid_now!(claims, verified_at)
207
213
  if PaymentPolicy.long?(profile_ref)
208
- raise Invalid unless %w[iat exp].all? { |f| claims.fetch(f) == opening.fetch(f) }
214
+ raise PaymentDiagnostics.invalid(Invalid, :payment_binding_mismatch) unless %w[iat exp].all? { |f| claims.fetch(f) == opening.fetch(f) }
209
215
  else
210
- raise Invalid unless terminal.fetch("iat") == claims.fetch("iat") && claims.fetch("iat") >= opening.fetch("iat") &&
216
+ raise PaymentDiagnostics.invalid(Invalid, :payment_binding_mismatch) unless terminal.fetch("iat") == claims.fetch("iat") && claims.fetch("iat") >= opening.fetch("iat") &&
211
217
  claims.fetch("exp") <= opening.fetch("exp")
212
218
  end
213
219
  conditions!(opening, claims, profile_ref: profile_ref)
214
220
  reference = opening.fetch("constraints").find { |c| c["type"] == "payment.reference" }
215
- raise Invalid unless reference.fetch("conditional_transaction_id") == digest(checkout_inputs.fetch(:root_presentation))
221
+ raise PaymentDiagnostics.invalid(Invalid, :checkout_binding_mismatch) unless reference.fetch("conditional_transaction_id") == digest(checkout_inputs.fetch(:root_presentation))
216
222
  else raise Invalid
217
223
  end
218
224
  closed!(claims, profile_ref: profile_ref); valid_now!(claims, verified_at)
219
225
  PaymentPolicy.bind_context!(claims, context) if context
220
- raise Invalid unless claims.slice(*PaymentPolicy.fields(profile_ref)) == expected
226
+ raise PaymentDiagnostics.invalid(Invalid, :payment_binding_mismatch) unless claims.slice(*PaymentPolicy.fields(profile_ref)) == expected
221
227
  Verification.send(:new, claims, wire)
222
- rescue StandardError, LoadError
223
- Verification.send(:new)
228
+ rescue StandardError, LoadError => error
229
+ Verification.send(:new, reason: PaymentDiagnostics.reason(error))
224
230
  end
225
231
 
226
232
  def self.reference(closed_sd_jwt:, profile_ref: PROFILE_REF)
@@ -313,14 +319,14 @@ module AP2MandateVerifier
313
319
  conditions!(base, closed)
314
320
  return nil
315
321
  end
316
- FIELDS.drop(1).each { |f| raise Invalid if opening.key?(f) && opening[f] != closed[f] }
322
+ FIELDS.drop(1).each { |f| raise PaymentDiagnostics.invalid(Invalid, :payment_conditions_mismatch) if opening.key?(f) && opening[f] != closed[f] }
317
323
  opening.fetch("constraints").each do |c|
318
324
  case c["type"]
319
- when "payment.allowed_payees" then raise Invalid unless c["allowed"].include?(closed["payee"])
320
- when "payment.allowed_payment_instruments" then raise Invalid unless c["allowed"].include?(closed["payment_instrument"])
325
+ when "payment.allowed_payees" then raise PaymentDiagnostics.invalid(Invalid, :payment_conditions_mismatch) unless c["allowed"].include?(closed["payee"])
326
+ when "payment.allowed_payment_instruments" then raise PaymentDiagnostics.invalid(Invalid, :payment_conditions_mismatch) unless c["allowed"].include?(closed["payment_instrument"])
321
327
  when "payment.amount_range"
322
328
  a = closed.fetch("payment_amount")
323
- raise Invalid unless a["currency"] == c["currency"] && a["amount"].between?(c.fetch("min", 0), c["max"])
329
+ raise PaymentDiagnostics.invalid(Invalid, :payment_conditions_mismatch) unless a["currency"] == c["currency"] && a["amount"].between?(c.fetch("min", 0), c["max"])
324
330
  when "payment.reference" # Checked against the verified Checkout chain in verify.
325
331
  else raise Invalid
326
332
  end
@@ -346,7 +352,7 @@ module AP2MandateVerifier
346
352
  end
347
353
  def self.valid_now!(v, now)
348
354
  CheckoutReceipt.send(:epoch!, now)
349
- raise Invalid unless v.fetch("iat") <= now && now < v.fetch("exp")
355
+ raise PaymentDiagnostics.invalid(Invalid, :payment_time_mismatch) unless v.fetch("iat") <= now && now < v.fetch("exp")
350
356
  end
351
357
  def self.checkout_open!(wire, profile_ref: ScopedConstraints::MULTI_PROFILE_REF)
352
358
  wire = InputValidator.snapshot!(wire)
@@ -447,7 +453,7 @@ module AP2MandateVerifier
447
453
  fields = implementation.parameters.map(&:last).freeze
448
454
  define_singleton_method(name) do |**args|
449
455
  unless (required - args.keys).empty? && (args.keys - fields).empty?
450
- next Verification.send(:new) if name == :verify
456
+ next Verification.send(:new, reason: :invalid_arguments) if name == :verify
451
457
  raise Invalid
452
458
  end
453
459
  implementation.call(**args)
@@ -5,7 +5,11 @@ module AP2MandateVerifier
5
5
  module PaymentAcceptance
6
6
  SCOPE = %w[tenant_id merchant_id operation_id approval_id occurrence_id order_id].freeze
7
7
  class Invalid < ArgumentError
8
- def initialize = super("invalid payment acceptance information")
8
+ attr_reader :diagnostic_reason
9
+ def initialize
10
+ @diagnostic_reason = :undetermined
11
+ super("invalid payment acceptance information")
12
+ end
9
13
  end
10
14
  class Unavailable < StandardError
11
15
  def initialize = super("payment acceptance storage unavailable")
@@ -23,9 +27,12 @@ module AP2MandateVerifier
23
27
  private_class_method :new
24
28
  end
25
29
  class Result
26
- attr_reader :status, :ticket, :closed_sd_jwt, :reference, :receipt_jwt, :processor_key, :signed_wires
27
- def initialize(status, record = nil, ticket = nil)
30
+ attr_reader :diagnostic, :status, :ticket, :closed_sd_jwt, :reference, :receipt_jwt, :processor_key, :signed_wires
31
+ def initialize(status, record = nil, ticket = nil, reason: nil)
28
32
  @status, @ticket = status, ticket
33
+ unless %i[reserved receipt_success].include?(status)
34
+ @diagnostic = PaymentDiagnostics.build(:payment_acceptance, reason || (%i[conflict unavailable pending unknown receipt_error].include?(status) ? status : :undetermined))
35
+ end
29
36
  if record
30
37
  @closed_sd_jwt, @reference, @receipt_jwt = record.values_at("closed_sd_jwt", "reference", "receipt_jwt").map { |v| v&.freeze }
31
38
  @processor_key = record.fetch("processor_key").freeze
@@ -48,6 +55,18 @@ module AP2MandateVerifier
48
55
  private_class_method :new
49
56
  end
50
57
 
58
+ # Per-call immutable observation; never an authorization or retry instruction.
59
+ class StartResult
60
+ attr_reader :execution, :diagnostic
61
+ def initialize(execution, reason = :undetermined)
62
+ @execution = execution
63
+ @diagnostic = PaymentDiagnostics.build(:payment_execution, reason) unless execution
64
+ freeze
65
+ end
66
+ def inspect = "#<AP2MandateVerifier::PaymentAcceptance::StartResult>"
67
+ private_class_method :new
68
+ end
69
+
51
70
  class Service
52
71
  def initialize(**arguments)
53
72
  raise Invalid.new, cause: nil unless arguments.keys == [:store]
@@ -64,14 +83,24 @@ module AP2MandateVerifier
64
83
  Result.send(:new, :conflict)
65
84
  rescue Unavailable
66
85
  Result.send(:new, :unavailable)
86
+ rescue Invalid => error
87
+ Result.send(:new, :rejected, reason: error.diagnostic_reason)
67
88
  rescue StandardError, LoadError
68
89
  Result.send(:new, :rejected)
69
90
  end
70
91
 
71
92
  def start(ticket:, verification_inputs:)
93
+ start_observation(ticket: ticket, verification_inputs: verification_inputs).execution
94
+ end
95
+
96
+ def start_with_diagnostic(ticket:, verification_inputs:)
97
+ start_observation(ticket: ticket, verification_inputs: verification_inputs)
98
+ end
99
+
100
+ def start_observation(ticket:, verification_inputs:)
72
101
  old = @store.ticket_record!(ticket: ticket)
73
102
  fresh = verified_record(old.fetch("mode").to_sym, verification_inputs, old.fetch("scope"))
74
- raise Invalid unless old.fetch("instruction") == fresh.fetch("instruction") && old.fetch("signed_wires") == fresh.fetch("signed_wires")
103
+ raise PaymentDiagnostics.invalid(Invalid, :saved_binding_mismatch) unless old.fetch("instruction") == fresh.fetch("instruction") && old.fetch("signed_wires") == fresh.fetch("signed_wires")
75
104
  record = if LongPayment.profile?(old.fetch("profile_ref"))
76
105
  @store.start_long!(ticket: ticket, verified_at: fresh.fetch("accepted_at"),
77
106
  instruction: fresh.fetch("instruction"), signed_wires: fresh.fetch("signed_wires"),
@@ -84,12 +113,22 @@ module AP2MandateVerifier
84
113
  # Existing adapters retain their public signature. The returned handle
85
114
  # must still expose the freshly verified shorter Host deadline.
86
115
  record = record.merge("valid_until" => [record.fetch("valid_until"), fresh.fetch("valid_until")].min)
87
- Execution.send(:new, record)
116
+ StartResult.send(:new, Execution.send(:new, record))
117
+ else
118
+ StartResult.send(:new, nil)
88
119
  end
120
+ rescue Unavailable
121
+ StartResult.send(:new, nil, :unavailable)
122
+ rescue Conflict
123
+ StartResult.send(:new, nil, :conflict)
124
+ rescue Invalid => error
125
+ StartResult.send(:new, nil, error.diagnostic_reason)
89
126
  rescue StandardError, LoadError
90
- nil # An uncertain commit NEVER produces an execution handle.
127
+ StartResult.send(:new, nil) # An uncertain commit NEVER produces a handle.
91
128
  end
92
129
 
130
+ private :start_observation
131
+
93
132
  private
94
133
  def verified_record(mode, verification_inputs, scope)
95
134
  args = PaymentAcceptance.copy!(verification_inputs)
@@ -102,7 +141,7 @@ module AP2MandateVerifier
102
141
  when :selective then SelectivePayment.verify(**args)
103
142
  else raise Invalid
104
143
  end
105
- raise Invalid unless result.verified?
144
+ raise PaymentDiagnostics.invalid(Invalid, :payment_not_verified) unless result.verified?
106
145
  checkout_args = args.fetch(:checkout_inputs)
107
146
  if mode == :direct
108
147
  checkout = Buyer.verify(**checkout_args)
@@ -150,6 +189,8 @@ module AP2MandateVerifier
150
189
  Result.send(:new, :conflict)
151
190
  rescue Unavailable
152
191
  Result.send(:new, :unavailable)
192
+ rescue Invalid => error
193
+ Result.send(:new, :rejected, reason: error.diagnostic_reason)
153
194
  rescue StandardError, LoadError
154
195
  Result.send(:new, :rejected)
155
196
  end
@@ -172,6 +213,8 @@ module AP2MandateVerifier
172
213
  Result.send(:new, :conflict)
173
214
  rescue Unavailable
174
215
  Result.send(:new, :unavailable)
216
+ rescue Invalid => error
217
+ Result.send(:new, :rejected, reason: error.diagnostic_reason)
175
218
  rescue StandardError, LoadError
176
219
  Result.send(:new, :rejected)
177
220
  end
@@ -194,12 +237,12 @@ module AP2MandateVerifier
194
237
  receipt = PaymentReceipt.verify(jwt: jwt, closed_sd_jwt: record.fetch("closed_sd_jwt"),
195
238
  profile_ref: record.fetch("profile_ref") == SelectivePayment::PROFILE_REF ? Payment::PROFILE_REF : record.fetch("profile_ref"),
196
239
  verified_at: verified_at, **context)
197
- raise Invalid unless receipt.verified?
240
+ raise PaymentDiagnostics.invalid(Invalid, :receipt_not_verified) unless receipt.verified?
198
241
  status = receipt.payment_succeeded? ? "receipt_success" : "receipt_error"
199
242
  @store.finish!(scope: record.fetch("scope"), ticket: ticket, receipt_jwt: jwt, status: status)
200
243
  end
201
244
 
202
- %i[accept start finish unknown reconcile lookup].each do |name|
245
+ %i[accept start start_with_diagnostic finish unknown reconcile lookup].each do |name|
203
246
  implementation = instance_method(name)
204
247
  required = implementation.parameters.filter_map { |kind, key| key if kind == :keyreq }.freeze
205
248
  allowed = implementation.parameters.filter_map { |kind, key| key if %i[keyreq key].include?(kind) }.freeze
@@ -208,7 +251,13 @@ module AP2MandateVerifier
208
251
  raise Invalid unless (required - arguments.keys).empty? && (rest || (arguments.keys - allowed).empty?)
209
252
  implementation.bind_call(self, **arguments)
210
253
  rescue StandardError, LoadError
211
- name == :start ? nil : Result.send(:new, :rejected)
254
+ if name == :start
255
+ nil
256
+ elsif name == :start_with_diagnostic
257
+ StartResult.send(:new, nil)
258
+ else
259
+ Result.send(:new, :rejected)
260
+ end
212
261
  end
213
262
  public name
214
263
  end
@@ -0,0 +1,78 @@
1
+ # frozen_string_literal: true
2
+
3
+ module AP2MandateVerifier
4
+ class Diagnostic
5
+ PAYMENT_FLOW = {
6
+ payment_verification: {
7
+ undetermined: ["Payment verification did not complete with a precise reason. Check inputs and runtime; no execution permission is established.", "Payment検証の詳細な理由は不明です。入力と実行環境を確認してください。実行許可ではありません。"].freeze,
8
+ invalid_arguments: ["Check the documented keyword arguments.", "文書記載のキーワード引数を確認してください。"].freeze,
9
+ checkout_not_verified: ["Checkout verification did not succeed. Inspect its separate result using the existing application flow, not by retrying payment.", "Checkout検証が成功していません。決済を再試行せず、既存のアプリ処理の検証結果を確認してください。"].freeze,
10
+ checkout_binding_mismatch: ["Compare the payment with the independently verified Checkout reference, merchant, amount and currency.", "Paymentと独立に検証したCheckoutの参照、販売者、金額、通貨を照合してください。"].freeze,
11
+ payment_time_mismatch: ["Compare the independent verification time with the signed validity window.", "独立した検証時刻と署名済み有効期間を照合してください。"].freeze,
12
+ payment_conditions_mismatch: ["Compare the signed payment conditions with the selected payment. Do not rewrite signed data.", "署名済み支払い条件と選択したPaymentを照合してください。署名データを書き換えないでください。"].freeze,
13
+ payment_binding_mismatch: ["Compare the signed Payment with independent expected payment and proof bindings.", "署名済みPaymentと独立した期待値・証明の結び付けを照合してください。"].freeze,
14
+ signed_input_rejected: ["A signed-input check rejected the input. Check its supported format and independently selected public keys; this does not identify a cryptographic failure.", "署名入力の検査が入力を拒否しました。対応形式と独立に選択した公開鍵を確認してください。暗号署名失敗とは断定できません。"].freeze,
15
+ verification_unavailable: ["Verification could not complete because a supported dependency/check was unavailable.", "対応依存関係または検証処理を利用できず、検証を完了できませんでした。"].freeze,
16
+ }.freeze,
17
+ payment_receipt_verification: {
18
+ verification_unavailable: ["Receipt verification could not complete because a dependency/check was unavailable.", "依存関係または検証処理を利用できずReceipt検証を完了できませんでした。"].freeze,
19
+ undetermined: ["Receipt verification failed without a precise diagnosis. It proves neither payment success nor a safe retry.", "Receipt検証失敗の詳細は不明です。支払い成功や安全な再試行の証拠ではありません。"].freeze,
20
+ invalid_arguments: ["Check the documented Receipt keyword arguments.", "文書記載のReceiptキーワード引数を確認してください。"].freeze,
21
+ receipt_time_mismatch: ["Compare the independent clock, allowed Receipt window and signed issue time.", "独立した時計、許容するReceipt期間、署名済み発行時刻を照合してください。"].freeze,
22
+ receipt_reference_mismatch: ["Compare the Receipt issuer, payment identifier and exact Payment reference with independent saved expectations.", "Receiptの発行者・支払い識別子・原Payment参照と、独立した保存済み期待値を照合してください。"].freeze,
23
+ signed_input_rejected: ["A signed-input check rejected Receipt or Payment input. Check original bytes, supported formats and independently trusted keys; the outcome is not yet verified.", "Receiptまたは原Paymentの入力検査が拒否しました。原文、対応形式、独立に信頼した公開鍵を確認してください。報告された結果は未検証です。"].freeze,
24
+ reported_error: ["An authentic matching Receipt reports Error. This is not verification failure, success, retry permission or permission to release quota.", "真正で参照が一致するReceiptがErrorを報告しています。検証失敗・成功・再試行許可・利用枠解放許可ではありません。"].freeze,
25
+ }.freeze,
26
+ payment_acceptance: {
27
+ undetermined: ["No precise acceptance diagnosis is available. Check saved state and the application contract; do not infer permission to execute.", "受理処理の詳細診断はありません。保存状態とアプリ契約を確認し、実行許可と解釈しないでください。"].freeze,
28
+ conflict: ["The store reported a conflict. Check protected approval and saved state; the specific conflicting condition is not known.", "保存先が競合を報告しました。保護された承認と保存状態を確認してください。具体的な競合条件は不明です。"].freeze,
29
+ unavailable: ["Storage was unavailable or its result uncertain. Reconcile saved state; do not retry payment or release quota automatically.", "保存先を利用できないか結果が不確実です。保存状態を照合し、自動再決済・利用枠解放をしないでください。"].freeze,
30
+ pending: ["An existing attempt is pending. Inspect saved state and reconcile; this is not permission for another execution.", "既存の処理が保留中です。保存状態の確認・照合を行ってください。再実行許可ではありません。"].freeze,
31
+ unknown: ["The execution outcome is unknown. Reconcile with the processor; never infer failure or release quota.", "実行結果は不明です。決済事業者と照合してください。失敗や利用枠解放を推測しないでください。"].freeze,
32
+ receipt_error: ["A verified Receipt reports Error. It does not permit another execution or quota release.", "検証済みReceiptがErrorを報告しています。再実行・利用枠解放の許可ではありません。"].freeze,
33
+ payment_not_verified: ["Payment verification did not succeed; no reservation was requested.", "Payment検証が成功せず、予約は要求していません。"].freeze,
34
+ receipt_not_verified: ["Receipt verification did not succeed; no finalization was requested.", "Receipt検証が成功せず、確定保存は要求していません。"].freeze,
35
+ }.freeze,
36
+ payment_execution: {
37
+ undetermined: ["No execution handle was returned. The cause and commit state are undetermined; this proves neither non-execution nor a safe retry.", "実行ハンドルは返りませんでした。原因・保存確定状態は不明です。未実行や安全な再試行の証拠ではありません。"].freeze,
38
+ unavailable: ["Storage was unavailable or uncertain. No execution handle was returned; reconcile, do not automatically retry.", "保存先を利用できないか結果が不確実です。実行ハンドルはありません。照合し、自動再試行しないでください。"].freeze,
39
+ conflict: ["The store reported a conflict; no execution handle was returned. Do not infer a safe retry.", "保存先が競合を報告し、実行ハンドルは返りませんでした。安全な再試行を推測しないでください。"].freeze,
40
+ payment_not_verified: ["Fresh Payment verification did not succeed. No start was requested; this says nothing about prior attempts.", "最新Payment検証が成功せず、開始保存は要求していません。過去の処理結果を示すものではありません。"].freeze,
41
+ saved_binding_mismatch: ["Fresh instruction or signed bytes differ from saved state. No start was requested; preserve the saved record.", "最新の指示または署名原文が保存状態と異なります。開始保存は要求していません。保存記録を維持してください。"].freeze,
42
+ }.freeze,
43
+ }.freeze
44
+ # Restore only known catalog identifiers. Unknown values never become text.
45
+ def self.payment_flow(stage, reason)
46
+ return nil unless Symbol === stage && Symbol === reason
47
+ hints = PAYMENT_FLOW.fetch(stage, {}).fetch(reason, nil)
48
+ hints && new(stage, nil, reason, hints)
49
+ end
50
+ end
51
+
52
+ module PaymentDiagnostics
53
+ def self.build(stage, reason)
54
+ Diagnostic.payment_flow(stage, reason)
55
+ rescue StandardError, LoadError
56
+ nil # Diagnostics never change a verification or storage decision.
57
+ end
58
+ # Private diagnostic metadata does not alter the public exception constructor.
59
+ def self.invalid(klass, reason)
60
+ error = klass.new
61
+ error.instance_variable_set(:@diagnostic_reason, reason)
62
+ error
63
+ end
64
+ def self.reason(error)
65
+ if error.instance_of?(Payment::Invalid) || error.instance_of?(PaymentReceipt::Invalid) || error.instance_of?(SelectivePayment::Invalid)
66
+ error.diagnostic_reason
67
+ elsif error.is_a?(LoadError) || error.is_a?(RootSignature::Unavailable) || error.is_a?(InputValidator::Unavailable)
68
+ :verification_unavailable
69
+ elsif error.is_a?(RootSignature::Rejected)
70
+ :signed_input_rejected
71
+ else
72
+ :undetermined
73
+ end
74
+ rescue StandardError, LoadError
75
+ :undetermined
76
+ end
77
+ end
78
+ end
@@ -4,7 +4,11 @@ module AP2MandateVerifier
4
4
  # Authenticity and reported outcome are separate. No automatic success/retry.
5
5
  module PaymentReceipt
6
6
  class Invalid < ArgumentError
7
- def initialize = super("invalid payment receipt information")
7
+ attr_reader :diagnostic_reason
8
+ def initialize
9
+ @diagnostic_reason = :undetermined
10
+ super("invalid payment receipt information")
11
+ end
8
12
  end
9
13
  class Signed
10
14
  attr_reader :jwt, :reference
@@ -15,9 +19,10 @@ module AP2MandateVerifier
15
19
  private_class_method :new
16
20
  end
17
21
  class Verification
18
- attr_reader :code, :outcome, :payment_id, :psp_confirmation_id, :network_confirmation_id, :error, :error_description
19
- def initialize(claims = nil)
22
+ attr_reader :diagnostic, :code, :outcome, :payment_id, :psp_confirmation_id, :network_confirmation_id, :error, :error_description
23
+ def initialize(claims = nil, reason: :undetermined)
20
24
  @code = claims ? :payment_receipt_verified : :payment_receipt_verification_failed
25
+ @diagnostic = PaymentDiagnostics.build(:payment_receipt_verification, claims ? :reported_error : reason) if !claims || claims["status"] == "Error"
21
26
  if claims
22
27
  @outcome, @payment_id, @psp_confirmation_id, @network_confirmation_id, @error, @error_description =
23
28
  claims.values_at("status", "payment_id", "psp_confirmation_id", "network_confirmation_id", "error", "error_description").map { |s| s&.freeze }
@@ -44,18 +49,18 @@ module AP2MandateVerifier
44
49
  def self.verify(jwt:, closed_sd_jwt:, trusted_public_key_pem:, expected_issuer:, expected_payment_id:,
45
50
  not_before:, not_after:, verified_at:, profile_ref: Payment::PROFILE_REF)
46
51
  [not_before, not_after, verified_at].each { |t| CheckoutReceipt.send(:epoch!, t) }
47
- raise Invalid unless not_before <= verified_at && verified_at <= not_after
52
+ raise PaymentDiagnostics.invalid(Invalid, :receipt_time_mismatch) unless not_before <= verified_at && verified_at <= not_after
48
53
  expected = InputValidator.snapshot!(expected_issuer, max_bytes: 512)
49
54
  id = InputValidator.snapshot!(expected_payment_id, max_bytes: 512)
50
55
  text!(expected, 512); text!(id, 512)
51
56
  ref = reference(closed_sd_jwt: closed_sd_jwt, profile_ref: profile_ref)
52
57
  claims = RootSignature.verified_payload!(jwt, trusted_public_key_pem, expected_typ: "JWT", max_bytes: 16_384)
53
58
  validate!(claims)
54
- raise Invalid unless claims["iss"] == expected && claims["payment_id"] == id && claims["reference"] == ref &&
55
- claims["iat"].between?(not_before, verified_at)
59
+ raise PaymentDiagnostics.invalid(Invalid, :receipt_reference_mismatch) unless claims["iss"] == expected && claims["payment_id"] == id && claims["reference"] == ref
60
+ raise PaymentDiagnostics.invalid(Invalid, :receipt_time_mismatch) unless claims["iat"].between?(not_before, verified_at)
56
61
  Verification.send(:new, claims)
57
- rescue StandardError, LoadError
58
- Verification.send(:new)
62
+ rescue StandardError, LoadError => error
63
+ Verification.send(:new, reason: PaymentDiagnostics.reason(error))
59
64
  end
60
65
  def self.validate!(claims)
61
66
  fields = %w[iss status iat reference payment_id] + case claims["status"]
@@ -75,7 +80,7 @@ module AP2MandateVerifier
75
80
  fields = implementation.parameters.map(&:last).freeze
76
81
  define_singleton_method(name) do |**args|
77
82
  unless (required - args.keys).empty? && (args.keys - fields).empty?
78
- next Verification.send(:new) if name == :verify
83
+ next Verification.send(:new, reason: :invalid_arguments) if name == :verify
79
84
  raise Invalid
80
85
  end
81
86
  implementation.call(**args)
@@ -9,7 +9,11 @@ module AP2MandateVerifier
9
9
  MAX_DISCLOSURES = 17
10
10
  AXES = {"payment.allowed_payees" => "payee", "payment.allowed_payment_instruments" => "payment_instrument"}.freeze
11
11
  class Invalid < ArgumentError
12
- def initialize = super("invalid selective payment information")
12
+ attr_reader :diagnostic_reason
13
+ def initialize
14
+ @diagnostic_reason = :undetermined
15
+ super("invalid selective payment information")
16
+ end
13
17
  end
14
18
 
15
19
  # All candidates and their exact Cartesian authorization come from a
@@ -133,32 +137,32 @@ module AP2MandateVerifier
133
137
  raise Invalid unless inputs.size == fields.size && fields.all? { |f| inputs.key?(f) } && inputs[:verified_at] == verified_at
134
138
  expected = Payment.send(:copy_details!, expected_payment, profile_ref: profile_ref)
135
139
  checkout = AP2MandateVerifier.verify_checkout(**inputs)
136
- raise Invalid unless checkout.success?
137
- raise Invalid unless expected.fetch("transaction_id") == digest(inputs.fetch(:host_checkout_jws))
140
+ raise PaymentDiagnostics.invalid(Payment::Invalid, :checkout_not_verified) unless checkout.success?
141
+ raise PaymentDiagnostics.invalid(Payment::Invalid, :checkout_binding_mismatch) unless expected.fetch("transaction_id") == digest(inputs.fetch(:host_checkout_jws))
138
142
  binding = checkout.evidence["checkout_binding"]
139
143
  amount = expected.fetch("payment_amount")
140
- raise Invalid unless expected.fetch("payee").fetch("id") == binding.fetch("merchant_id") &&
144
+ raise PaymentDiagnostics.invalid(Payment::Invalid, :checkout_binding_mismatch) unless expected.fetch("payee").fetch("id") == binding.fetch("merchant_id") &&
141
145
  amount.fetch("currency") == binding.fetch("currency") && amount.fetch("amount") == binding.fetch("expected_total")
142
146
  Payment.send(:bind_checkout!, expected, Payment.send(:jwt_payload!, inputs.fetch(:host_checkout_jws), "JWT"))
143
147
  parsed = authenticated!(open_presentation, provider, profile_ref: profile_ref)
144
148
  opening = parsed.fetch(:opening)
145
149
  Payment.send(:valid_now!, opening, verified_at)
146
- raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(agent)}
150
+ raise PaymentDiagnostics.invalid(Payment::Invalid, :payment_binding_mismatch) unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(agent)}
147
151
  terminal, wire = Payment.send(:final!, closed_sd_jwt, conditional: true, profile_ref: profile_ref)
148
152
  RootSignature.verified_payload!(wire.split("~", -1).first, agent,
149
153
  expected_typ: "kb+sd-jwt", max_bytes: 32_768)
150
154
  Payment.send(:text!, aud, 512); Payment.send(:text!, nonce, 512)
151
- raise Invalid unless terminal.fetch("aud") == aud && terminal.fetch("nonce") == nonce &&
155
+ raise PaymentDiagnostics.invalid(Payment::Invalid, :payment_binding_mismatch) unless terminal.fetch("aud") == aud && terminal.fetch("nonce") == nonce &&
152
156
  terminal.fetch("iat") <= verified_at && verified_at - terminal.fetch("iat") <= 300
153
157
  closed = terminal.fetch("delegate_payload").first
154
158
  bind_terminal!(parsed, terminal, closed, profile_ref: profile_ref)
155
159
  Payment.send(:valid_now!, closed, verified_at)
156
160
  ref = constraint!(opening, "payment.reference").fetch("conditional_transaction_id")
157
161
  PaymentPolicy.bind_context!(closed, context) if context
158
- raise Invalid unless ref == digest(inputs.fetch(:root_presentation)) && closed.slice(*PaymentPolicy.fields(profile_ref)) == expected
162
+ raise PaymentDiagnostics.invalid(Payment::Invalid, :payment_binding_mismatch) unless ref == digest(inputs.fetch(:root_presentation)) && closed.slice(*PaymentPolicy.fields(profile_ref)) == expected
159
163
  Payment::Verification.send(:new, closed, wire)
160
- rescue StandardError, LoadError
161
- Payment::Verification.send(:new)
164
+ rescue StandardError, LoadError => error
165
+ Payment::Verification.send(:new, reason: PaymentDiagnostics.reason(error))
162
166
  end
163
167
 
164
168
  def self.bind_terminal!(root, terminal, closed, profile_ref: PROFILE_REF)
@@ -256,7 +260,7 @@ module AP2MandateVerifier
256
260
  fields = implementation.parameters.map(&:last).freeze
257
261
  define_singleton_method(name) do |**args|
258
262
  unless (required - args.keys).empty? && (args.keys - fields).empty?
259
- next Payment::Verification.send(:new) if name == :verify
263
+ next Payment::Verification.send(:new, reason: :invalid_arguments) if name == :verify
260
264
  raise Invalid
261
265
  end
262
266
  implementation.call(**args)
@@ -15,6 +15,7 @@ require_relative "ap2_mandate_verifier/checkout_jwt"
15
15
  require_relative "ap2_mandate_verifier/checkout_receipt"
16
16
  require_relative "ap2_mandate_verifier/buyer"
17
17
  require_relative "ap2_mandate_verifier/conditional_checkout"
18
+ require_relative "ap2_mandate_verifier/payment_diagnostics"
18
19
  require_relative "ap2_mandate_verifier/payment"
19
20
  require_relative "ap2_mandate_verifier/payment_receipt"
20
21
  require_relative "ap2_mandate_verifier/selective_payment"
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ap2_mandate_verifier
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.6.1
4
+ version: 1.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AP2 Mandate Verifier contributors
8
8
  bindir: bin
9
9
  cert_chain: []
10
- date: 2026-11-10 00:00:00.000000000 Z
10
+ date: 2026-11-17 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
13
  name: json
@@ -153,6 +153,7 @@ files:
153
153
  - lib/ap2_mandate_verifier/payment_acceptance/long_sqlite_store.rb
154
154
  - lib/ap2_mandate_verifier/payment_acceptance/recurring_sqlite_store.rb
155
155
  - lib/ap2_mandate_verifier/payment_acceptance/sqlite_store.rb
156
+ - lib/ap2_mandate_verifier/payment_diagnostics.rb
156
157
  - lib/ap2_mandate_verifier/payment_policy.rb
157
158
  - lib/ap2_mandate_verifier/payment_receipt.rb
158
159
  - lib/ap2_mandate_verifier/purchase_binding.rb
@@ -186,7 +187,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
186
187
  - !ruby/object:Gem::Version
187
188
  version: '0'
188
189
  requirements: []
189
- rubygems_version: 4.0.20
190
+ rubygems_version: 3.6.9
190
191
  specification_version: 4
191
192
  summary: Ruby SDK for supported AP2 Checkout and Payment Mandates
192
193
  test_files: []