ap2_mandate_verifier 1.2.0 → 1.4.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,97 @@
1
+ # frozen_string_literal: true
2
+ # Ordinary installed Gem only. No test fixtures, source-path loading or network.
3
+ require "ap2_mandate_verifier"
4
+ require "openssl"
5
+
6
+ module SelectiveCheckoutExample
7
+ M = AP2MandateVerifier
8
+ PROFILE = M::SelectiveCheckout::PROFILE_REF
9
+ NOW = 1_800_000_000
10
+ def self.totals(n) = %w[subtotal total].map { |type| {"type" => type, "amount" => n} }
11
+ def self.run
12
+ provider, agent, merchant = Array.new(3) { OpenSSL::PKey::EC.generate("prime256v1") }
13
+ seller = {"id" => "shop", "name" => "Office supplies"}
14
+ # This protected record is created AFTER application authentication, display
15
+ # of these conditions and authority/consent checks. No approved flag is proof.
16
+ requirements = [{"id" => "choice", "quantity" => 1,
17
+ "acceptable_items" => %w[A B].map { |id| {"id" => id, "title" => "Product #{id}"} }},
18
+ {"id" => "required", "quantity" => 2, "acceptable_items" => [{"id" => "C", "title" => "Product C"}]}]
19
+ full = M::SelectiveCheckout.issue_open(allowed_merchants: [seller, {"id" => "private-shop", "name" => "Private alternative merchant"}],
20
+ requirements: requirements, candidate_policy: :independent,
21
+ agent_public_key_pem: agent.public_to_pem, issued_at: NOW, expires_at: NOW + 600,
22
+ signer: M::CheckoutJWT.es256_signer(private_key: provider), public_key_pem: provider.public_to_pem)
23
+ # Store full securely. The complete candidate universe is not sent to the merchant.
24
+ opening = M::SelectiveCheckout.select(open_sd_jwt: full.root_presentation,
25
+ merchant_index: 0, item_indices: [[1], [0]])
26
+ visible = opening.root_presentation.split("~", -1)[1...-1].map do |part|
27
+ JSON.parse(Base64.urlsafe_decode64(part))
28
+ end
29
+ raise "privacy boundary failed" if JSON.generate(visible).include?("private-shop") ||
30
+ visible.any? { |disclosure| disclosure[1] == {"id" => "A", "title" => "Product A"} }
31
+ puts "Checkout retained full disclosures=#{full.root_presentation.count('~') - 1}; sent=#{opening.root_presentation.count('~') - 1}"
32
+ puts "Checkout issuer JWT unchanged=#{full.root_presentation.split('~').first == opening.root_presentation.split('~').first}; unselected candidate values not sent"
33
+ # Merchant Checkout has three rows, including C in two distinct rows.
34
+ lines = %w[B C C].each_with_index.map do |id, i|
35
+ {"id" => "row-#{i}", "item" => {"id" => id, "title" => "Product #{id}", "price" => 100},
36
+ "quantity" => 1, "totals" => totals(100)}
37
+ end
38
+ order = {"id" => "office-1", "merchant" => seller, "status" => "ready_for_complete",
39
+ "currency" => "USD", "line_items" => lines, "totals" => totals(300), "links" => []}
40
+ inferred = M::SelectiveCheckout.select_for_checkout(open_sd_jwt: full.root_presentation, checkout: order)
41
+ raise "selection mismatch" unless inferred.root_presentation == opening.root_presentation
42
+ checkout = M::CheckoutJWT.sign(checkout: order, profile_ref: PROFILE,
43
+ signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
44
+
45
+ # Host enrollment and challenge are synthetic authenticated application data.
46
+ roles = %w[Issuer Agent Merchant]
47
+ records = roles.zip([provider, agent, merchant]).map do |role, key|
48
+ {"role" => role, "identity" => role == "Merchant" ? "shop" : role.downcase,
49
+ "tenant_id" => "tenant", "purpose" => "checkout", "key_ref" => role.downcase,
50
+ "public_key_pem" => key.public_to_pem, "active" => true, "not_before" => NOW - 1, "not_after" => NOW + 1000}
51
+ end
52
+ selectors = records.to_h { |record| [record["role"].downcase.to_sym, record.slice("identity", "purpose", "key_ref")] }
53
+ trust = M::InputBuilder.trust(snapshot: {"id" => "registry", "policy_version" => "1", "active" => true,
54
+ "not_before" => NOW - 1, "not_after" => NOW + 1000, "records" => records},
55
+ tenant_id: "tenant", verified_at: NOW, profile_ref: PROFILE, **selectors)
56
+ host_order = {"tenant_id" => "tenant", "buyer_account_id" => "buyer", "order_id" => "office-1",
57
+ "merchant_id" => "shop", "audience" => "merchant-host", "order_version" => "1", "currency" => "USD", "expected_total" => 300}
58
+ host_inputs = {trust: trust, order: host_order, root_presentation: opening.root_presentation, host_checkout_jws: checkout.jwt}
59
+ saved = M::InputBuilder.prepare(**host_inputs, challenge_id: "challenge-1", nonce: "synthetic-one-use-nonce",
60
+ issuer_id: "host", not_before: NOW, not_after: NOW + 60)
61
+ # Agent receives public trust, Open, Checkout, challenge and its own signer.
62
+ # Provider signer/private key is not an input to this operation.
63
+ closed = M::SelectiveCheckout.issue_closed(root_presentation: opening.root_presentation, checkout_jwt: checkout.jwt,
64
+ trusted_issuer_public_key_pem: provider.public_to_pem, agent_public_key_pem: agent.public_to_pem,
65
+ trusted_merchant_public_key_pem: merchant.public_to_pem, expected_merchant_id: "shop",
66
+ audience: "merchant-host", nonce: "synthetic-one-use-nonce", verified_at: NOW,
67
+ signer: M::CheckoutJWT.es256_signer(private_key: agent))
68
+ wire = M::SelectiveCheckout.present(root_presentation: closed.root_presentation,
69
+ terminal_jws: closed.terminal_jws, checkout_jwt: closed.checkout_jwt)
70
+ checked = M::InputBuilder.verify(**host_inputs, terminal_jws: wire.terminal_jws,
71
+ saved_challenge: M::InputBuilder.restore(saved_challenge: saved), expected_challenge_issuer_id: "host",
72
+ clock_source_id: "synthetic-clock", verified_at: NOW)
73
+ raise "verification failed" unless checked.success?
74
+ puts "Open -> Agent Closed -> merchant evidence: verified=true; rows=3; requirements=2"
75
+ # These are ALTERNATIVE synthetic application outcomes, never two executions.
76
+ %w[Success Error].each do |outcome|
77
+ fields = outcome == "Success" ? {order_id: "office-1"} : {error: "policy_rejected", error_description: "Application declined"}
78
+ receipt = M::CheckoutReceipt.sign(closed_sd_jwt: wire.closed_sd_jwt, profile_ref: PROFILE,
79
+ issuer: "shop", outcome: outcome, issued_at: NOW, **fields,
80
+ signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
81
+ result = M::CheckoutReceipt.verify(jwt: receipt.jwt, closed_sd_jwt: wire.closed_sd_jwt,
82
+ profile_ref: PROFILE, trusted_public_key_pem: merchant.public_to_pem, expected_issuer: "shop",
83
+ not_before: NOW, not_after: NOW + 60, verified_at: NOW)
84
+ raise "receipt failed" unless result.verified? && result.outcome == outcome
85
+ puts "Receipt #{outcome}: authentic=true; purchase_succeeded=#{result.purchase_succeeded?}"
86
+ end
87
+ # Application state, not an SDK purchase permit: durable transaction/CAS in
88
+ # real code must consume approval/challenge/order once and save its receipt.
89
+ states = {"success" => :consumed, "error" => :requires_new_policy_decision, "missing_receipt" => :pending}
90
+ raise "unknown replay" unless states["missing_receipt"] == :pending
91
+ puts "Success=consumed; Error=policy decision; missing Receipt/uncertain commit=pending"
92
+ puts "Synthetic only; evidence and Receipt authenticity are not payment completion."
93
+ {opening: opening, closed: closed, result: checked, host_inputs: host_inputs, saved: saved,
94
+ keys: [provider, agent, merchant], requirements: requirements, checkout: order}
95
+ end
96
+ end
97
+ SelectiveCheckoutExample.run if $PROGRAM_NAME == __FILE__
@@ -0,0 +1,72 @@
1
+ # frozen_string_literal: true
2
+ # Installed SDK only. Confidential issuance stays local; simulated payments only.
3
+ require "ap2_mandate_verifier"
4
+ require_relative "selective_checkout"
5
+ module SelectiveCheckoutPaymentExample
6
+ M = AP2MandateVerifier
7
+ NOW = SelectiveCheckoutExample::NOW
8
+ def self.run
9
+ state = SelectiveCheckoutExample.run
10
+ provider, agent, merchant = state.fetch(:keys)
11
+ signer = ->(key) { M::CheckoutJWT.es256_signer(private_key: key) }
12
+ checkout = state.fetch(:closed).checkout_jwt
13
+ chosen_instrument = {"id" => "synthetic-card-A", "type" => "card"}
14
+ details = M::Payment.details(checkout_jwt: checkout, trusted_merchant_public_key_pem: merchant.public_to_pem,
15
+ expected_merchant_id: "shop", payment_instrument: chosen_instrument)
16
+ payees = [details.fetch("payee"), {"id" => "another-shop", "name" => "Private alternative payee"}]
17
+ instruments = [chosen_instrument, {"id" => "private-alternative-B", "type" => "card"}]
18
+ conditions = [{"type" => "payment.amount_range", "currency" => "USD", "min" => 100, "max" => 300},
19
+ {"type" => "payment.allowed_payees", "allowed" => payees},
20
+ {"type" => "payment.allowed_payment_instruments", "allowed" => instruments}]
21
+ # This list comes from the app's PROTECTED approval record: every crossproduct
22
+ # combination is expressly approved. Do not expand a correlated subset here.
23
+ approved_combinations = [[0, 0], [0, 1], [1, 0], [1, 1]]
24
+ full = M::SelectivePayment.issue_open(open_checkout_sd_jwt: state.fetch(:opening).root_presentation,
25
+ checkout_profile_ref: M::SelectiveCheckout::PROFILE_REF,
26
+ constraints: conditions, fixed: {}, approved_combinations: approved_combinations, selective: :both,
27
+ agent_public_key_pem: agent.public_to_pem, issued_at: NOW, expires_at: NOW+60,
28
+ signer: signer.call(provider), public_key_pem: provider.public_to_pem)
29
+ reduced = M::SelectivePayment.select(open_sd_jwt: full, payee_index: 0, instrument_index: 0)
30
+ transmitted_disclosures = reduced.split("~", -1)[1...-1]
31
+ visible = transmitted_disclosures.map { |wire| JSON.parse(Base64.urlsafe_decode64(wire)) }
32
+ hidden_leaves = full.split("~", -1)[1...-1].select do |wire|
33
+ value = JSON.parse(Base64.urlsafe_decode64(wire))[1]
34
+ value == payees[1] || value == instruments[1]
35
+ end
36
+ raise "privacy boundary failed" unless (hidden_leaves & transmitted_disclosures).empty? &&
37
+ !JSON.generate(visible).include?("Private alternative") && !JSON.generate(visible).include?("private-alternative-B")
38
+ # Keep full confidential issuance in protected storage; send only reduced.
39
+ # No original unselected disclosure or confidential full wire is printed.
40
+ puts "Retained locally: payees=2; instruments=2; disclosures=#{full.count('~')-1}; bytes=#{full.bytesize}"
41
+ puts "Sent: chosen payee=shop; chosen instrument=synthetic-card-A; disclosures=#{reduced.count('~')-1}; bytes=#{reduced.bytesize}"
42
+ puts "Issuer JWT unchanged=#{full.split('~').first == reduced.split('~').first}; presentation bytes changed=#{full != reduced}"
43
+ closed = M::SelectivePayment.issue_closed(open_presentation: reduced, payment: details,
44
+ trusted_provider_public_key_pem: provider.public_to_pem, agent_public_key_pem: agent.public_to_pem,
45
+ audience: "credential-provider", nonce: "synthetic-selective-payment-nonce", verified_at: NOW,
46
+ signer: signer.call(agent))
47
+ restored = M::SelectivePayment.present(open_presentation: reduced, closed_sd_jwt: closed.closed_sd_jwt)
48
+ checkout_inputs = M::InputBuilder.inputs(**state.fetch(:host_inputs), saved_challenge: state.fetch(:saved),
49
+ terminal_jws: state.fetch(:closed).terminal_jws, expected_challenge_issuer_id: "host",
50
+ clock_source_id: "synthetic-clock", verified_at: NOW)
51
+ verified = M::SelectivePayment.verify(open_presentation: restored.open_sd_jwt, closed_sd_jwt: restored.closed_sd_jwt,
52
+ checkout_inputs: checkout_inputs, expected_payment: details, trusted_provider_public_key_pem: provider.public_to_pem,
53
+ expected_agent_public_key_pem: agent.public_to_pem, expected_audience: "credential-provider",
54
+ expected_nonce: "synthetic-selective-payment-nonce", verified_at: NOW)
55
+ raise "selective verification failed" unless verified.verified?
56
+ puts "Selected Payment verified=true; unselected candidate values/disclosures were not sent"
57
+ %w[Success Error].each do |outcome|
58
+ fields = outcome == "Success" ? {psp_confirmation_id: "synthetic-psp", network_confirmation_id: "synthetic-network"} :
59
+ {error: "declined", error_description: "Simulated rejection"}
60
+ receipt = M::PaymentReceipt.sign(closed_sd_jwt: restored.closed_sd_jwt, issuer: "processor",
61
+ payment_id: "synthetic-selective-payment", outcome: outcome, issued_at: NOW, **fields,
62
+ signer: signer.call(merchant), public_key_pem: merchant.public_to_pem)
63
+ checked = M::PaymentReceipt.verify(jwt: receipt.jwt, closed_sd_jwt: restored.closed_sd_jwt,
64
+ trusted_public_key_pem: merchant.public_to_pem, expected_issuer: "processor", expected_payment_id: "synthetic-selective-payment",
65
+ not_before: NOW, not_after: NOW+60, verified_at: NOW)
66
+ raise "receipt failed" unless checked.verified? && checked.outcome == outcome
67
+ puts "Payment Receipt #{outcome}: authentic=#{checked.verified?}; reported_success=#{checked.payment_succeeded?}"
68
+ end
69
+ puts "Synthetic only. Verification is not execution permission; one-use atomic state belongs to the app; unknown outcome remains pending."
70
+ end
71
+ end
72
+ SelectiveCheckoutPaymentExample.run if $PROGRAM_NAME == __FILE__
@@ -72,7 +72,7 @@ module AP2MandateVerifier
72
72
 
73
73
  def self.validate!(checkout, profile_ref: TrustContext::PROFILE_REF)
74
74
  profile_ref = InputValidator.snapshot!(profile_ref, max_bytes: 256)
75
- if profile_ref == ScopedConstraints::MULTI_PROFILE_REF
75
+ if [ScopedConstraints::MULTI_PROFILE_REF, TrustContext::SELECTIVE_PROFILE_REF].include?(profile_ref)
76
76
  ScopedConstraints.multi_checkout!(checkout)
77
77
  return nil
78
78
  end
@@ -113,7 +113,7 @@ module AP2MandateVerifier
113
113
  value = InputValidator.parse!(wire)
114
114
  shape!(value, %w[format_version profile_ref profile_version challenge], "saved_challenge")
115
115
  invalid!("saved_challenge", :unsupported_saved_format) unless
116
- [TrustContext::PROFILE_REF, TrustContext::MULTI_PROFILE_REF].include?(value["profile_ref"])
116
+ [TrustContext::PROFILE_REF, TrustContext::MULTI_PROFILE_REF, TrustContext::SELECTIVE_PROFILE_REF].include?(value["profile_ref"])
117
117
  profile = TrustContext.profile!(value["profile_ref"])
118
118
  invalid!("saved_challenge", :unsupported_saved_format) unless value.values_at("format_version", "profile_ref", "profile_version") ==
119
119
  [FORMAT_VERSION, profile[:ref], profile[:version]]
@@ -36,71 +36,90 @@ module AP2MandateVerifier
36
36
 
37
37
  # Checkout JWT and key must be from independently trusted application state.
38
38
  # This prepares data, not consent or a verified Checkout Mandate.
39
- def self.details(checkout_jwt:, trusted_merchant_public_key_pem:, expected_merchant_id:, payment_instrument:)
39
+ def self.details(checkout_jwt:, trusted_merchant_public_key_pem:, expected_merchant_id:, payment_instrument:,
40
+ profile_ref: PROFILE_REF, pisp: nil, execution_date: nil)
41
+ profile = PaymentPolicy.profile!(profile_ref)
42
+ if PaymentPolicy.enabled?(profile)
43
+ planned = InputBuilder.send(:copy!, {"pisp" => pisp, "execution_date" => execution_date})
44
+ PaymentPolicy.details!(planned)
45
+ else
46
+ raise Invalid unless pisp.nil? && execution_date.nil?
47
+ end
40
48
  checked = CheckoutJWT.verify(jwt: checkout_jwt, trusted_public_key_pem: trusted_merchant_public_key_pem,
41
49
  expected_merchant_id: expected_merchant_id, profile_ref: ScopedConstraints::MULTI_PROFILE_REF)
42
50
  instrument = InputBuilder.send(:copy!, payment_instrument)
43
51
  instrument!(instrument)
44
- ResearchEvidence.send(:copy_frozen, {"transaction_id" => checked.checkout_hash,
52
+ value = {"transaction_id" => checked.checkout_hash,
45
53
  "payee" => checked.checkout.fetch("merchant"), "payment_instrument" => instrument,
46
54
  "payment_amount" => {"currency" => checked.checkout.fetch("currency"),
47
- "amount" => ScopedConstraints.multi_checkout!(checked.checkout)}})
55
+ "amount" => ScopedConstraints.multi_checkout!(checked.checkout)}}
56
+ if PaymentPolicy.enabled?(profile)
57
+ value.merge!(planned)
58
+ end
59
+ ResearchEvidence.send(:copy_frozen, copy_details!(value, profile_ref: profile))
48
60
  end
49
61
 
50
62
  # Protected approval record must cover every payment detail, not just amount.
51
- def self.issue_direct(payment:, approved_payment:, issued_at:, expires_at:, signer:, public_key_pem:)
52
- value = copy_details!(payment)
53
- raise Invalid unless value == copy_details!(approved_payment)
63
+ def self.issue_direct(payment:, approved_payment:, issued_at:, expires_at:, signer:, public_key_pem:, profile_ref: PROFILE_REF)
64
+ profile_ref = PaymentPolicy.profile!(profile_ref)
65
+ value = copy_details!(payment, profile_ref: profile_ref)
66
+ raise Invalid unless value == copy_details!(approved_payment, profile_ref: profile_ref)
54
67
  closed = value.merge("vct" => "mandate.payment.1", "iat" => issued_at, "exp" => expires_at)
55
- closed!(closed)
56
- Presentation.send(:new, nil, sign_root!(closed, signer, public_key_pem))
68
+ closed!(closed, profile_ref: profile_ref)
69
+ Presentation.send(:new, nil, sign_root!(closed, signer, public_key_pem, profile_ref: profile_ref))
57
70
  end
58
71
 
59
72
  # Reference is calculated over exact original Open Checkout, never rebuilt JSON.
60
73
  # The app authenticates consent to these conditions before invoking this API.
61
74
  def self.issue_open(open_checkout_sd_jwt:, constraints:, fixed:, agent_public_key_pem:,
62
- issued_at:, expires_at:, signer:, public_key_pem:)
75
+ issued_at:, expires_at:, signer:, public_key_pem:, checkout_profile_ref: ScopedConstraints::MULTI_PROFILE_REF,
76
+ profile_ref: PROFILE_REF, candidate_policy: nil)
77
+ profile_ref = PaymentPolicy.profile!(profile_ref)
78
+ PaymentPolicy.candidate_policy!(profile_ref, candidate_policy)
63
79
  RootSignature.send(:dependencies!)
64
- root = checkout_open!(open_checkout_sd_jwt)
80
+ root = checkout_open!(open_checkout_sd_jwt, profile_ref: checkout_profile_ref)
65
81
  conditions = InputBuilder.send(:copy!, constraints)
66
82
  raise Invalid unless conditions.instance_of?(Array)
67
83
  conditions << {"type" => "payment.reference", "conditional_transaction_id" => digest(root)}
68
84
  value = InputBuilder.send(:copy!, fixed)
69
- raise Invalid unless value.instance_of?(Hash) && (value.keys - FIELDS.drop(1)).empty?
85
+ raise Invalid unless value.instance_of?(Hash) && (value.keys - PaymentPolicy.fields(profile_ref).drop(1)).empty?
70
86
  opening = value.merge("vct" => "mandate.payment.open.1", "iat" => issued_at, "exp" => expires_at,
71
87
  "cnf" => {"jwk" => RootSignature.public_jwk!(agent_public_key_pem)}, "constraints" => conditions)
72
- open!(opening)
73
- sign_root!(opening, signer, public_key_pem).freeze
88
+ open!(opening, profile_ref: profile_ref)
89
+ sign_root!(opening, signer, public_key_pem, profile_ref: profile_ref).freeze
74
90
  end
75
91
 
76
92
  # Provider signer is deliberately absent. Existing signed Open grants the hop.
77
93
  def self.issue_closed(open_sd_jwt:, payment:, trusted_provider_public_key_pem:, agent_public_key_pem:,
78
- audience:, nonce:, verified_at:, signer:)
94
+ audience:, nonce:, verified_at:, signer:, profile_ref: PROFILE_REF)
95
+ profile_ref = PaymentPolicy.profile!(profile_ref)
79
96
  agent_public_key_pem = InputValidator.snapshot!(agent_public_key_pem, max_bytes: 1_024)
80
- opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem)
81
- open!(opening); valid_now!(opening, verified_at)
97
+ opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
98
+ open!(opening, profile_ref: profile_ref); valid_now!(opening, verified_at)
82
99
  raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(agent_public_key_pem)}
83
- value = copy_details!(payment).merge("vct" => "mandate.payment.1", "iat" => verified_at, "exp" => opening.fetch("exp"))
84
- closed!(value); conditions!(opening, value)
100
+ value = copy_details!(payment, profile_ref: profile_ref).merge("vct" => "mandate.payment.1", "iat" => verified_at, "exp" => opening.fetch("exp"))
101
+ closed!(value, profile_ref: profile_ref); conditions!(opening, value, profile_ref: profile_ref)
85
102
  audience = InputValidator.snapshot!(audience, max_bytes: 512)
86
103
  nonce = InputValidator.snapshot!(nonce, max_bytes: 512)
87
104
  text!(audience, 512); text!(nonce, 512)
88
105
  claims = {"delegate_payload" => [value], "iat" => verified_at,
89
106
  "aud" => audience, "nonce" => nonce, "sd_hash" => digest(root)}
90
- preflight!(claims, "kb+sd-jwt")
107
+ claims["ap2_profile"] = profile_ref if PaymentPolicy.enabled?(profile_ref)
108
+ preflight!(claims, "kb+sd-jwt", profile_ref: profile_ref)
91
109
  terminal = MerchantSignature.sign!(claims, signer, agent_public_key_pem, typ: "kb+sd-jwt")
92
110
  Presentation.send(:new, root, terminal + "~")
93
111
  end
94
112
 
95
113
  # Original-byte restoration only. All authentication belongs to verify.
96
- def self.present(closed_sd_jwt:, open_sd_jwt: nil)
97
- closed, wire = final!(closed_sd_jwt, conditional: !open_sd_jwt.nil?)
98
- closed!(closed.fetch("delegate_payload").first)
114
+ def self.present(closed_sd_jwt:, open_sd_jwt: nil, profile_ref: PROFILE_REF)
115
+ profile_ref = PaymentPolicy.profile!(profile_ref)
116
+ closed, wire = final!(closed_sd_jwt, conditional: !open_sd_jwt.nil?, profile_ref: profile_ref)
117
+ closed!(closed.fetch("delegate_payload").first, profile_ref: profile_ref)
99
118
  if open_sd_jwt
100
- opening, root = root!(open_sd_jwt)
101
- open!(opening)
119
+ opening, root = root!(open_sd_jwt, profile_ref: profile_ref)
120
+ open!(opening, profile_ref: profile_ref)
102
121
  raise Invalid unless closed.fetch("sd_hash") == digest(root)
103
- conditions!(opening, closed.fetch("delegate_payload").first)
122
+ conditions!(opening, closed.fetch("delegate_payload").first, profile_ref: profile_ref)
104
123
  end
105
124
  Presentation.send(:new, open_sd_jwt && root, wire)
106
125
  end
@@ -110,7 +129,16 @@ module AP2MandateVerifier
110
129
  # Direct uses Buyer.verify; conditional uses verify_checkout's seven inputs.
111
130
  def self.verify(closed_sd_jwt:, checkout_mode:, checkout_inputs:, expected_payment:,
112
131
  trusted_provider_public_key_pem:, verified_at:, open_sd_jwt: nil,
113
- expected_agent_public_key_pem: nil, expected_audience: nil, expected_nonce: nil)
132
+ expected_agent_public_key_pem: nil, expected_audience: nil, expected_nonce: nil,
133
+ profile_ref: PROFILE_REF, trusted_pisp: nil, execution_at: nil)
134
+ profile_ref = PaymentPolicy.profile!(profile_ref)
135
+ context = PaymentPolicy.context!(profile_ref, trusted_pisp, execution_at)
136
+ trusted_provider_public_key_pem = InputValidator.snapshot!(trusted_provider_public_key_pem, max_bytes: 1_024)
137
+ if checkout_mode == :conditional
138
+ expected_agent_public_key_pem = InputValidator.snapshot!(expected_agent_public_key_pem, max_bytes: 1_024)
139
+ expected_audience = InputValidator.snapshot!(expected_audience, max_bytes: 512)
140
+ expected_nonce = InputValidator.snapshot!(expected_nonce, max_bytes: 512)
141
+ end
114
142
  CheckoutReceipt.send(:epoch!, verified_at)
115
143
  raise Invalid unless checkout_inputs.instance_of?(Hash) && checkout_inputs[:verified_at] == verified_at
116
144
  fields = case checkout_mode
@@ -129,14 +157,14 @@ module AP2MandateVerifier
129
157
  if checkout_mode == :conditional
130
158
  expected_agent_public_key_pem = InputValidator.snapshot!(expected_agent_public_key_pem, max_bytes: 1_024)
131
159
  end
132
- expected = copy_details!(expected_payment)
160
+ expected = copy_details!(expected_payment, profile_ref: profile_ref)
133
161
  case checkout_mode
134
162
  when :direct
135
163
  raise Invalid if open_sd_jwt || expected_agent_public_key_pem || expected_audience || expected_nonce
136
164
  checked = Buyer.verify(**checkout_inputs)
137
165
  raise Invalid unless checked.verified? && expected.fetch("transaction_id") == checked.checkout_hash
138
166
  bind_checkout!(expected, checked.checkout)
139
- claims, wire = verified_root!(closed_sd_jwt, trusted_provider_public_key_pem)
167
+ claims, wire = verified_root!(closed_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
140
168
  when :conditional
141
169
  checked = AP2MandateVerifier.verify_checkout(**checkout_inputs)
142
170
  raise Invalid unless checked.success?
@@ -150,10 +178,10 @@ module AP2MandateVerifier
150
178
  # Full Checkout verifier already authenticated these exact JWT bytes.
151
179
  payload = jwt_payload!(checkout, "JWT")
152
180
  bind_checkout!(expected, payload)
153
- opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem)
154
- open!(opening); valid_now!(opening, verified_at)
181
+ opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
182
+ open!(opening, profile_ref: profile_ref); valid_now!(opening, verified_at)
155
183
  raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(expected_agent_public_key_pem)}
156
- terminal, wire = final!(closed_sd_jwt, conditional: true)
184
+ terminal, wire = final!(closed_sd_jwt, conditional: true, profile_ref: profile_ref)
157
185
  RootSignature.verified_payload!(wire.split("~", -1).first, expected_agent_public_key_pem,
158
186
  expected_typ: "kb+sd-jwt", max_bytes: 32_768)
159
187
  expected_audience = InputValidator.snapshot!(expected_audience, max_bytes: 512)
@@ -163,28 +191,31 @@ module AP2MandateVerifier
163
191
  terminal.fetch("sd_hash") == digest(root) && terminal.fetch("iat") <= verified_at &&
164
192
  verified_at - terminal.fetch("iat") <= 300
165
193
  claims = terminal.fetch("delegate_payload").first
166
- closed!(claims); valid_now!(claims, verified_at)
194
+ closed!(claims, profile_ref: profile_ref); valid_now!(claims, verified_at)
167
195
  raise Invalid unless terminal.fetch("iat") == claims.fetch("iat") && claims.fetch("iat") >= opening.fetch("iat") &&
168
196
  claims.fetch("exp") <= opening.fetch("exp")
169
- conditions!(opening, claims)
197
+ conditions!(opening, claims, profile_ref: profile_ref)
170
198
  reference = opening.fetch("constraints").find { |c| c["type"] == "payment.reference" }
171
199
  raise Invalid unless reference.fetch("conditional_transaction_id") == digest(checkout_inputs.fetch(:root_presentation))
172
200
  else raise Invalid
173
201
  end
174
- closed!(claims); valid_now!(claims, verified_at)
175
- raise Invalid unless claims.slice(*FIELDS) == expected
202
+ closed!(claims, profile_ref: profile_ref); valid_now!(claims, verified_at)
203
+ PaymentPolicy.bind_context!(claims, context) if context
204
+ raise Invalid unless claims.slice(*PaymentPolicy.fields(profile_ref)) == expected
176
205
  Verification.send(:new, claims, wire)
177
206
  rescue StandardError, LoadError
178
207
  Verification.send(:new)
179
208
  end
180
209
 
181
- def self.reference(closed_sd_jwt:)
210
+ def self.reference(closed_sd_jwt:, profile_ref: PROFILE_REF)
211
+ profile_ref = InputValidator.snapshot!(profile_ref, max_bytes: 256)
212
+ raise Invalid unless profile_ref == PROFILE_REF || PaymentPolicy.enabled?(profile_ref)
182
213
  # No trust or authorization claim: parse either supported final grammar.
183
214
  wire = InputValidator.snapshot!(closed_sd_jwt, max_bytes: 32_769)
184
215
  payload = jwt_payload!(wire.split("~", -1).first, nil)
185
216
  conditional = payload.key?("sd_hash")
186
- final, original = final!(wire, conditional: conditional)
187
- closed!(final.fetch("delegate_payload").first)
217
+ final, original = final!(wire, conditional: conditional, profile_ref: profile_ref)
218
+ closed!(final.fetch("delegate_payload").first, profile_ref: profile_ref)
188
219
  digest(original).freeze
189
220
  end
190
221
 
@@ -193,19 +224,25 @@ module AP2MandateVerifier
193
224
  value.fetch("payment_amount") == {"currency" => checkout.fetch("currency"),
194
225
  "amount" => ScopedConstraints.multi_checkout!(checkout)}
195
226
  end
196
- def self.copy_details!(value)
227
+ def self.copy_details!(value, profile_ref: PROFILE_REF)
197
228
  value = InputBuilder.send(:copy!, value)
198
- exact!(value, FIELDS)
229
+ exact!(value, PaymentPolicy.fields(profile_ref))
199
230
  raise Invalid unless value["transaction_id"].instance_of?(String) && value["transaction_id"].match?(/\A[A-Za-z0-9_-]{43}\z/)
200
231
  payee!(value["payee"]); amount!(value["payment_amount"]); instrument!(value["payment_instrument"])
232
+ PaymentPolicy.details!(value) if PaymentPolicy.enabled?(profile_ref)
201
233
  value
202
234
  end
203
- def self.closed!(value)
204
- exact!(value, FIELDS + %w[vct iat exp])
235
+ def self.closed!(value, profile_ref: PROFILE_REF)
236
+ exact!(value, PaymentPolicy.fields(profile_ref) + %w[vct iat exp])
205
237
  raise Invalid unless value["vct"] == "mandate.payment.1"
206
- copy_details!(value.slice(*FIELDS)); times!(value)
238
+ copy_details!(value.slice(*PaymentPolicy.fields(profile_ref)), profile_ref: profile_ref); times!(value)
207
239
  end
208
- def self.open!(value)
240
+ def self.open!(value, profile_ref: PROFILE_REF)
241
+ if PaymentPolicy.enabled?(profile_ref)
242
+ base = PaymentPolicy.constraints!(value)
243
+ open!(base)
244
+ return nil
245
+ end
209
246
  raise Invalid unless value.instance_of?(Hash) && (value.keys - FIELDS.drop(1) - %w[vct iat exp cnf constraints]).empty?
210
247
  raise Invalid unless value["vct"] == "mandate.payment.open.1"
211
248
  times!(value); exact!(value["cnf"], ["jwk"])
@@ -236,7 +273,13 @@ module AP2MandateVerifier
236
273
  end
237
274
  end
238
275
  end
239
- def self.conditions!(opening, closed)
276
+ def self.conditions!(opening, closed, profile_ref: PROFILE_REF)
277
+ if PaymentPolicy.enabled?(profile_ref)
278
+ PaymentPolicy.conditions!(opening, closed)
279
+ base = PaymentPolicy.constraints!(opening)
280
+ conditions!(base, closed)
281
+ return nil
282
+ end
240
283
  FIELDS.drop(1).each { |f| raise Invalid if opening.key?(f) && opening[f] != closed[f] }
241
284
  opening.fetch("constraints").each do |c|
242
285
  case c["type"]
@@ -271,9 +314,15 @@ module AP2MandateVerifier
271
314
  CheckoutReceipt.send(:epoch!, now)
272
315
  raise Invalid unless v.fetch("iat") <= now && now < v.fetch("exp")
273
316
  end
274
- def self.checkout_open!(wire)
317
+ def self.checkout_open!(wire, profile_ref: ScopedConstraints::MULTI_PROFILE_REF)
275
318
  wire = InputValidator.snapshot!(wire)
276
- opening = RootDisclosures.send(:structural_root!, wire).fetch("delegate_payload").first
319
+ profile = InputValidator.snapshot!(profile_ref, max_bytes: 256)
320
+ opening = if profile == TrustContext::SELECTIVE_PROFILE_REF
321
+ SelectiveCheckout.send(:parse!, wire, complete: false).fetch(:opening)
322
+ else
323
+ raise Invalid unless profile == ScopedConstraints::MULTI_PROFILE_REF
324
+ RootDisclosures.send(:structural_root!, wire).fetch("delegate_payload").first
325
+ end
277
326
  raise Invalid unless opening.fetch("vct") == "mandate.checkout.open.1"
278
327
  wire
279
328
  end
@@ -286,7 +335,7 @@ module AP2MandateVerifier
286
335
  raise Invalid unless RootSignature.send(:decode!, parts[2], 64).bytesize == 64
287
336
  InputValidator.parse!(RootSignature.send(:decode!, parts[1], 24_576))
288
337
  end
289
- def self.final!(source, conditional:)
338
+ def self.final!(source, conditional:, profile_ref: PROFILE_REF)
290
339
  wire = InputValidator.snapshot!(source, max_bytes: 32_769)
291
340
  raise Invalid unless wire.ascii_only? && wire.end_with?("~") && [1, 2].include?(wire.count("~"))
292
341
  compact, *parts = wire.split("~", -1)
@@ -294,6 +343,10 @@ module AP2MandateVerifier
294
343
  claims = jwt_payload!(compact, conditional ? "kb+sd-jwt" : "example+sd-jwt")
295
344
  fields = conditional ? %w[delegate_payload iat aud nonce sd_hash] : %w[delegate_payload _sd_alg]
296
345
  fields += ["_sd_alg"] if conditional && claims.key?("_sd_alg")
346
+ if PaymentPolicy.enabled?(profile_ref)
347
+ fields += ["ap2_profile"]
348
+ raise Invalid unless claims["ap2_profile"] == profile_ref
349
+ end
297
350
  exact!(claims, fields)
298
351
  raise Invalid if claims.key?("_sd_alg") && claims["_sd_alg"] != "sha-256"
299
352
  if conditional
@@ -314,33 +367,34 @@ module AP2MandateVerifier
314
367
  end
315
368
  [claims, wire]
316
369
  end
317
- def self.root!(source)
318
- claims, wire = final!(source, conditional: false)
370
+ def self.root!(source, profile_ref: PROFILE_REF)
371
+ claims, wire = final!(source, conditional: false, profile_ref: profile_ref)
319
372
  [claims.fetch("delegate_payload").first, wire]
320
373
  end
321
- def self.verified_root!(source, key)
322
- value, wire = root!(source)
374
+ def self.verified_root!(source, key, profile_ref: PROFILE_REF)
375
+ value, wire = root!(source, profile_ref: profile_ref)
323
376
  RootSignature.verified_payload!(wire.split("~", -1).first, key, max_bytes: 32_768)
324
377
  [value, wire]
325
378
  end
326
- def self.sign_root!(value, signer, key)
379
+ def self.sign_root!(value, signer, key, profile_ref: PROFILE_REF)
327
380
  RootSignature.send(:dependencies!)
328
381
  require "securerandom"
329
382
  disclosure = Buyer.send(:encode, [Buyer.send(:encode, SecureRandom.random_bytes(16)), value])
330
383
  claims = {"delegate_payload" => [{"..." => digest(disclosure)}], "_sd_alg" => "sha-256"}
331
- preflight!(claims, "example+sd-jwt", disclosure)
384
+ claims["ap2_profile"] = profile_ref if PaymentPolicy.enabled?(profile_ref)
385
+ preflight!(claims, "example+sd-jwt", disclosure, profile_ref: profile_ref)
332
386
  wire = MerchantSignature.sign!(claims, signer, key,
333
387
  typ: "example+sd-jwt") + "~" + disclosure + "~"
334
- final!(wire, conditional: false)
388
+ final!(wire, conditional: false, profile_ref: profile_ref)
335
389
  wire
336
390
  end
337
- def self.preflight!(claims, typ, disclosure = nil)
391
+ def self.preflight!(claims, typ, disclosure = nil, profile_ref: PROFILE_REF)
338
392
  # Bound every new Mandate signature before remote signer effects. ES256
339
393
  # signatures have a fixed 64-byte width; this performs no cryptography.
340
394
  compact = [Buyer.send(:encode, {"alg" => "ES256", "typ" => typ}),
341
395
  Buyer.send(:encode, claims), Buyer.send(:encode, "\0" * 64)].join(".")
342
396
  wire = compact + "~" + (disclosure ? disclosure + "~" : "")
343
- final!(wire, conditional: typ == "kb+sd-jwt")
397
+ final!(wire, conditional: typ == "kb+sd-jwt", profile_ref: profile_ref)
344
398
  end
345
399
  def self.digest(wire) = Base64.urlsafe_encode64(Digest::SHA256.digest(wire), padding: false)
346
400
  def self.exact!(v, fields) = PurchaseBinding.send(:exact!, v, fields)
@@ -0,0 +1,115 @@
1
+ # frozen_string_literal: true
2
+
3
+ module AP2MandateVerifier
4
+ # Explicit, narrower operational-plan profile. No scheduling or QWAC proof.
5
+ module PaymentPolicy
6
+ PROFILE_REF = "ap2.payment.pisp_execution.complete.1".freeze
7
+ SELECTIVE_PROFILE_REF = "ap2.payment.pisp_execution.selective.1".freeze
8
+ FIELDS = %w[pisp execution_date].freeze
9
+ TYPES = %w[payment.allowed_pisps payment.execution_date].freeze
10
+ def self.enabled?(profile)
11
+ [PROFILE_REF, SELECTIVE_PROFILE_REF].include?(profile)
12
+ end
13
+ def self.profile!(value, selective: false)
14
+ profile = InputValidator.snapshot!(value, max_bytes: 256)
15
+ old, current = selective ? [SelectivePayment::PROFILE_REF, SELECTIVE_PROFILE_REF] : [Payment::PROFILE_REF, PROFILE_REF]
16
+ raise Payment::Invalid unless [old, current].include?(profile)
17
+ profile
18
+ end
19
+ def self.candidate_policy!(profile, policy)
20
+ raise Payment::Invalid unless enabled?(profile) ? policy == :independent : policy.nil?
21
+ end
22
+ def self.fields(profile) = Payment::FIELDS + (enabled?(profile) ? FIELDS : [])
23
+ def self.pisp!(value)
24
+ Payment.send(:exact!, value, %w[brand_name domain_name legal_name])
25
+ %w[legal_name brand_name].each { |f| Payment.send(:text!, value[f], 512) }
26
+ domain = value["domain_name"]
27
+ raise Payment::Invalid unless domain.instance_of?(String) && domain.bytesize.between?(1, 253) && domain.ascii_only? &&
28
+ domain.split(".", -1).all? { |label| label.bytesize.between?(1, 63) && label.match?(/\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/) }
29
+ end
30
+ # Exact decimal arithmetic; no permissive DateTime parsing/normalization.
31
+ def self.instant!(source)
32
+ value = InputValidator.snapshot!(source, max_bytes: 40)
33
+ m = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})\z/.match(value)
34
+ raise Payment::Invalid unless m
35
+ y, month, day, hour, minute, second = m.captures.first(6).map(&:to_i)
36
+ leap = y % 4 == 0 && (y % 100 != 0 || y % 400 == 0)
37
+ days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
38
+ raise Payment::Invalid unless y.between?(1, 9999) && month.between?(1, 12) && day.between?(1, days[month - 1]) &&
39
+ hour.between?(0, 23) && minute.between?(0, 59) && second.between?(0, 59) && m[8] != "-00:00"
40
+ offset = 0
41
+ unless m[8] == "Z"
42
+ oh, om = m[8][1..].split(":").map(&:to_i)
43
+ raise Payment::Invalid unless oh <= 23 && om <= 59
44
+ offset = (oh * 3600 + om * 60) * (m[8][0] == "-" ? -1 : 1)
45
+ end
46
+ # Gregorian days relative to 0001-01-01, with fractional seconds exact.
47
+ before = y - 1
48
+ count = before * 365 + before / 4 - before / 100 + before / 400 + days.first(month - 1).sum + day - 1
49
+ fraction = m[7] ? Rational(m[7].to_i, 10**m[7].size) : 0
50
+ count * 86400 + hour * 3600 + minute * 60 + second - offset + fraction
51
+ end
52
+ def self.details!(value)
53
+ pisp!(value.fetch("pisp")); instant!(value.fetch("execution_date"))
54
+ end
55
+ def self.constraints!(opening)
56
+ cs = opening.fetch("constraints")
57
+ raise Payment::Invalid unless cs.instance_of?(Array) && cs.size.between?(5, 6) && cs.all? { |c| c.instance_of?(Hash) }
58
+ extra = cs.select { |c| TYPES.include?(c["type"]) }
59
+ raise Payment::Invalid unless extra.size.between?(1, 2) && extra.map { |c| c["type"] }.uniq.size == extra.size
60
+ extra.each do |c|
61
+ if c["type"] == TYPES[0]
62
+ Payment.send(:exact!, c, %w[type allowed])
63
+ list = c["allowed"]
64
+ raise Payment::Invalid unless list.instance_of?(Array) && list.size.between?(1, 8) && list.uniq.size == list.size
65
+ list.each { |p| pisp!(p) }
66
+ else
67
+ raise Payment::Invalid unless (c.keys - %w[type not_before not_after]).empty? &&
68
+ c.key?("type") && (c.key?("not_before") || c.key?("not_after"))
69
+ lower = instant!(c["not_before"]) if c.key?("not_before")
70
+ upper = instant!(c["not_after"]) if c.key?("not_after")
71
+ raise Payment::Invalid if lower && upper && lower > upper
72
+ end
73
+ end
74
+ pisp!(opening["pisp"]) if opening.key?("pisp")
75
+ instant!(opening["execution_date"]) if opening.key?("execution_date")
76
+ # Reject already contradictory fixed plans before any signer effects.
77
+ extra.each do |c|
78
+ if c["type"] == TYPES[0] && opening.key?("pisp")
79
+ raise Payment::Invalid unless c["allowed"].include?(opening["pisp"])
80
+ elsif c["type"] == TYPES[1] && opening.key?("execution_date")
81
+ instant = instant!(opening["execution_date"])
82
+ raise Payment::Invalid if c.key?("not_before") && instant < instant!(c["not_before"])
83
+ raise Payment::Invalid if c.key?("not_after") && instant > instant!(c["not_after"])
84
+ end
85
+ end
86
+ opening.reject { |k,_| FIELDS.include?(k) }.merge("constraints" => cs.reject { |c| TYPES.include?(c["type"]) })
87
+ end
88
+ def self.conditions!(opening, closed)
89
+ details!(closed)
90
+ FIELDS.each { |f| raise Payment::Invalid if opening.key?(f) && opening[f] != closed[f] }
91
+ opening.fetch("constraints").each do |c|
92
+ if c["type"] == TYPES[0]
93
+ raise Payment::Invalid unless c["allowed"].include?(closed["pisp"])
94
+ elsif c["type"] == TYPES[1]
95
+ instant = instant!(closed["execution_date"])
96
+ raise Payment::Invalid if c.key?("not_before") && instant < instant!(c["not_before"])
97
+ raise Payment::Invalid if c.key?("not_after") && instant > instant!(c["not_after"])
98
+ end
99
+ end
100
+ end
101
+ # Never fills either expected context from claims or expected_payment.
102
+ def self.context!(profile, trusted_pisp, execution_at)
103
+ unless enabled?(profile)
104
+ raise Payment::Invalid unless trusted_pisp.nil? && execution_at.nil?
105
+ return nil
106
+ end
107
+ pisp = InputBuilder.send(:copy!, trusted_pisp)
108
+ pisp!(pisp)
109
+ [ResearchEvidence.send(:copy_frozen, pisp), instant!(execution_at)].freeze
110
+ end
111
+ def self.bind_context!(value, context)
112
+ raise Payment::Invalid unless value.fetch("pisp") == context[0] && instant!(value.fetch("execution_date")) == context[1]
113
+ end
114
+ end
115
+ end