ap2_mandate_verifier 1.6.0 → 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.
@@ -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.0
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-05 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
@@ -117,17 +117,23 @@ files:
117
117
  - docs/RELEASE_140_CANDIDATE.md
118
118
  - docs/RELEASE_150_CANDIDATE.md
119
119
  - docs/RELEASE_160_CANDIDATE.md
120
+ - docs/RELEASE_161_CANDIDATE.md
121
+ - docs/RUBY_INTEGRATION.ja.md
122
+ - docs/RUBY_INTEGRATION.md
120
123
  - docs/SELECTIVE_CHECKOUT.md
121
124
  - docs/SELECTIVE_PAYMENT.md
122
125
  - docs/SUPPORT_CONTRACT.md
123
126
  - docs/evidence/1.1.0_publication.json
124
127
  - examples/conditional_checkout.rb
128
+ - examples/integration/inputs.rb
129
+ - examples/integration/processor.rb
125
130
  - examples/long_payment.rb
126
131
  - examples/long_payment_acceptance.rb
127
132
  - examples/payment.rb
128
133
  - examples/payment_acceptance.rb
129
134
  - examples/payment_policy.rb
130
135
  - examples/recurring_payment.rb
136
+ - examples/ruby_integration.rb
131
137
  - examples/selective_checkout.rb
132
138
  - examples/selective_checkout_payment.rb
133
139
  - examples/selective_payment.rb
@@ -147,6 +153,7 @@ files:
147
153
  - lib/ap2_mandate_verifier/payment_acceptance/long_sqlite_store.rb
148
154
  - lib/ap2_mandate_verifier/payment_acceptance/recurring_sqlite_store.rb
149
155
  - lib/ap2_mandate_verifier/payment_acceptance/sqlite_store.rb
156
+ - lib/ap2_mandate_verifier/payment_diagnostics.rb
150
157
  - lib/ap2_mandate_verifier/payment_policy.rb
151
158
  - lib/ap2_mandate_verifier/payment_receipt.rb
152
159
  - lib/ap2_mandate_verifier/purchase_binding.rb