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 +4 -4
- data/README.ja.md +17 -7
- data/README.md +18 -8
- data/docs/DIAGNOSTICS.ja.md +83 -2
- data/docs/DIAGNOSTICS.md +98 -2
- data/docs/PUBLIC_API.md +11 -0
- data/docs/RELEASE_161_CANDIDATE.md +7 -4
- data/docs/RUBY_INTEGRATION.ja.md +15 -11
- data/docs/RUBY_INTEGRATION.md +15 -12
- data/lib/ap2_mandate_verifier/payment.rb +27 -21
- data/lib/ap2_mandate_verifier/payment_acceptance.rb +59 -10
- data/lib/ap2_mandate_verifier/payment_diagnostics.rb +78 -0
- data/lib/ap2_mandate_verifier/payment_receipt.rb +14 -9
- data/lib/ap2_mandate_verifier/selective_payment.rb +14 -10
- data/lib/ap2_mandate_verifier.rb +1 -0
- metadata +4 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9c2ce93037e11a4317d9c4c4f42ff1a9fccbe996277df3dcca9c34d41466de5f
|
|
4
|
+
data.tar.gz: 286a66784e21aa6de46d3efef055abd759e84147fe5593b224afada65b9e6902
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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
|
|
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.
|
|
17
|
-
AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.
|
|
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
|
|
37
|
-
|
|
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.
|
|
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
|
|
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.
|
|
17
|
-
AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.
|
|
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
|
|
39
|
-
|
|
40
|
-
|
|
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.
|
data/docs/DIAGNOSTICS.ja.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
#
|
|
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
|
-
|
|
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
|
-
#
|
|
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
|
-
**
|
|
14
|
-
|
|
15
|
-
The
|
|
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
|
|
data/docs/RUBY_INTEGRATION.ja.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
合成の登場者とSQLiteの模擬processorだけを使い、Rails・A2A・外部アカウント・実決済は不要です。
|
|
9
9
|
**組込みを理解するための実装例であり、本番の認証・認可backendではありません。**
|
|
10
10
|
|
|
11
|
-
## 1. Docker
|
|
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
|
|
40
|
-
|
|
41
|
-
公開1.6.0
|
|
42
|
-
|
|
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
|
-
|
|
45
|
-
|
|
44
|
+
既存の分離したRuby環境(MRI 3.4.12または4.0.9)へ、以下の公開版とSQLite driverを
|
|
45
|
+
版固定で導入します。SQLiteはSDKでは任意ですが、この永続化サンプルでは必要です。
|
|
46
|
+
同梱CLIの実行にリポジトリは不要です:
|
|
46
47
|
|
|
47
48
|
```sh
|
|
48
|
-
|
|
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
|
|
56
|
-
|
|
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
|
|
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状態は
|
data/docs/RUBY_INTEGRATION.md
CHANGED
|
@@ -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
|
|
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
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
-
|
|
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
|
|
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
|
-
|
|
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?
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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)
|
data/lib/ap2_mandate_verifier.rb
CHANGED
|
@@ -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.
|
|
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
|
+
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:
|
|
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: []
|