ap2_mandate_verifier 0.3.0 → 0.5.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.
@@ -4,10 +4,22 @@ module AP2MandateVerifier
4
4
  # Pure, fixed-profile conversion of authenticated Host business information.
5
5
  # Preparation is not issuance, verification, nonce consumption or Host ALLOW.
6
6
  module InputBuilder
7
+ VERIFY_FIELDS = %i[trust saved_challenge order root_presentation terminal_jws host_checkout_jws
8
+ expected_challenge_issuer_id clock_source_id verified_at].freeze
7
9
  FORMAT_VERSION = "1"
8
10
  ORDER_FIELDS = %w[tenant_id buyer_account_id order_id merchant_id audience order_version currency expected_total].freeze
9
11
  RECORD_FIELDS = (TrustContext::RECORD_FIELDS - %w[profile_ref profile_version algorithm key_fingerprint]).freeze
10
- class Invalid < ArgumentError; end
12
+ class Invalid < ArgumentError
13
+ def initialize(field = nil, reason = :invalid_builder_input)
14
+ @field, @reason = field, reason
15
+ super("invalid input-builder information")
16
+ end
17
+ def diagnostic
18
+ Diagnostic.builder(@field, @reason)
19
+ rescue StandardError, LoadError
20
+ nil
21
+ end
22
+ end
11
23
 
12
24
  class Trust
13
25
  attr_reader :trust_json, :selection_json
@@ -24,8 +36,9 @@ module AP2MandateVerifier
24
36
  def self.trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:)
25
37
  verified_at = copy!(verified_at)
26
38
  source = copy!(snapshot)
27
- shape!(source, %w[id policy_version active not_before not_after records])
28
- invalid! unless source["records"].instance_of?(Array) && source["records"].length.between?(1, 16)
39
+ shape!(source, %w[id policy_version active not_before not_after records], "snapshot")
40
+ invalid!("snapshot.records", :invalid_type) unless source["records"].instance_of?(Array)
41
+ invalid!("snapshot.records", :invalid_value) unless source["records"].length.between?(1, 16)
29
42
  source["records"].each do |record|
30
43
  shape!(record, RECORD_FIELDS)
31
44
  record.merge!("profile_ref" => TrustContext::PROFILE_REF, "profile_version" => TrustContext::PROFILE_VERSION,
@@ -37,7 +50,7 @@ module AP2MandateVerifier
37
50
  "profile_ref" => TrustContext::PROFILE_REF, "profile_version" => TrustContext::PROFILE_VERSION,
38
51
  "profile_definition_hash" => TrustContext::PROFILE_HASH,
39
52
  "Issuer" => copy!(issuer), "Agent" => copy!(agent), "Merchant" => copy!(merchant)}
40
- TrustContext::ROLES.each_key { |role| shape!(selection[role], %w[identity purpose key_ref]) }
53
+ TrustContext::ROLES.each_key { |role| shape!(selection[role], %w[identity purpose key_ref], role.downcase) }
41
54
  wire = json!({"snapshot" => {"id" => source["id"], "policy_version" => source["policy_version"],
42
55
  "content_hash" => selection["trust_content_hash"], "body" => body},
43
56
  "profile" => {"profile_ref" => TrustContext::PROFILE_REF, "version" => TrustContext::PROFILE_VERSION,
@@ -46,6 +59,8 @@ module AP2MandateVerifier
46
59
  context = TrustContext.verified_context!(trust_json: wire, selection_json: selected, verified_at: verified_at,
47
60
  expected_merchant_id: selection.fetch("Merchant").fetch("identity"))
48
61
  Trust.send(:new, wire, selected, context)
62
+ rescue Invalid
63
+ raise
49
64
  rescue RootSignature::Unavailable
50
65
  raise
51
66
  rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
@@ -61,6 +76,8 @@ module AP2MandateVerifier
61
76
  context = TrustContext.verified_context!(trust_json: wire, selection_json: selected,
62
77
  verified_at: copy!(verified_at), expected_merchant_id: selection.fetch("Merchant").fetch("identity"))
63
78
  Trust.send(:new, wire, selected, context)
79
+ rescue Invalid
80
+ raise
64
81
  rescue RootSignature::Unavailable
65
82
  raise
66
83
  rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError, NoMethodError
@@ -80,6 +97,8 @@ module AP2MandateVerifier
80
97
  saved = json!({"format_version" => FORMAT_VERSION, "profile_ref" => TrustContext::PROFILE_REF,
81
98
  "profile_version" => TrustContext::PROFILE_VERSION, "challenge" => challenge}, 32_768)
82
99
  restore(saved_challenge: saved)
100
+ rescue Invalid
101
+ raise
83
102
  rescue RootSignature::Unavailable
84
103
  raise
85
104
  rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
@@ -91,8 +110,8 @@ module AP2MandateVerifier
91
110
  def self.restore(saved_challenge:)
92
111
  wire = InputValidator.snapshot!(saved_challenge, max_bytes: 32_768)
93
112
  value = InputValidator.parse!(wire)
94
- shape!(value, %w[format_version profile_ref profile_version challenge])
95
- invalid! unless value.values_at("format_version", "profile_ref", "profile_version") ==
113
+ shape!(value, %w[format_version profile_ref profile_version challenge], "saved_challenge")
114
+ invalid!("saved_challenge", :unsupported_saved_format) unless value.values_at("format_version", "profile_ref", "profile_version") ==
96
115
  [FORMAT_VERSION, TrustContext::PROFILE_REF, TrustContext::PROFILE_VERSION]
97
116
  challenge = value["challenge"]
98
117
  shape!(challenge, HostBinding::CHALLENGE_FIELDS)
@@ -104,6 +123,8 @@ module AP2MandateVerifier
104
123
  %w[not_before not_after].each { |field| HostBinding.send(:time!, challenge[field]) }
105
124
  invalid! unless challenge["not_before"] < challenge["not_after"]
106
125
  wire
126
+ rescue Invalid
127
+ raise
107
128
  rescue RootSignature::Unavailable
108
129
  raise
109
130
  rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
@@ -121,6 +142,8 @@ module AP2MandateVerifier
121
142
  "expected_challenge_issuer_id" => copy!(expected_challenge_issuer_id), "clock_source_id" => copy!(clock_source_id)}
122
143
  {trust_json: trust.trust_json, selection_json: trust.selection_json, host_json: json!(host, 32_768),
123
144
  root_presentation: root, terminal_jws: terminal, host_checkout_jws: checkout, verified_at: verified_at}.freeze
145
+ rescue Invalid
146
+ raise
124
147
  rescue RootSignature::Unavailable
125
148
  raise
126
149
  rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
@@ -129,9 +152,14 @@ module AP2MandateVerifier
129
152
 
130
153
  # Building alone never produces Evidence; always enter the full old core.
131
154
  def self.verify(**arguments)
155
+ invalid!("arguments", :missing_required_field) unless VERIFY_FIELDS.all? { |field| arguments.key?(field) }
156
+ invalid!("arguments", :unknown_field) unless arguments.length == VERIFY_FIELDS.length
132
157
  AP2MandateVerifier.verify_checkout(**inputs(**arguments))
133
- rescue Invalid, ArgumentError
134
- Result.new(status: :rejected, code: :invalid_host_context)
158
+ rescue Invalid => error
159
+ Result.new(status: :rejected, code: :invalid_host_context, diagnostic: error.diagnostic)
160
+ rescue ArgumentError
161
+ Result.new(status: :rejected, code: :invalid_host_context,
162
+ diagnostic: Invalid.new.diagnostic)
135
163
  rescue InputValidator::Unavailable, RootSignature::Unavailable, LoadError
136
164
  Result.new(status: :unavailable, code: :research_verification_unavailable)
137
165
  rescue StandardError
@@ -139,13 +167,22 @@ module AP2MandateVerifier
139
167
  end
140
168
 
141
169
  def self.context!(trust, now)
142
- invalid! unless Object.instance_method(:instance_of?).bind_call(trust, Trust)
170
+ invalid!("trust", :invalid_type) unless Object.instance_method(:instance_of?).bind_call(trust, Trust)
143
171
  HostBinding.send(:time!, copy!(now))
144
172
  trust.instance_variable_get(:@context)
145
173
  end
146
174
  def self.binding!(context, order, root, checkout)
147
175
  value = copy!(order)
148
- shape!(value, ORDER_FIELDS)
176
+ shape!(value, ORDER_FIELDS, "order")
177
+ ORDER_FIELDS.each do |field|
178
+ expected = field == "expected_total" ? Integer : String
179
+ invalid!("order.#{field}", :invalid_type) unless value[field].instance_of?(expected)
180
+ end
181
+ HostBinding::B_IDS.grep_v(/profile/).each do |field|
182
+ invalid!("order.#{field}", :invalid_value) unless value[field].bytesize.between?(1, 256)
183
+ end
184
+ invalid!("order.currency", :invalid_value) unless ScopedConstraints::CURRENCIES.include?(value["currency"])
185
+ invalid!("order.expected_total", :invalid_value) unless value["expected_total"].between?(0, ScopedConstraints::MAX_AMOUNT)
149
186
  references = context.fetch(:references)
150
187
  value.merge!("profile_ref" => references.fetch("profile_ref"), "profile_version" => references.fetch("profile_version"),
151
188
  "approved_agent_key_fingerprint" => context.fetch(:agent_fingerprint),
@@ -154,10 +191,15 @@ module AP2MandateVerifier
154
191
  HostBinding.send(:binding!, value)
155
192
  value
156
193
  end
157
- def self.shape!(value, fields)
158
- invalid! unless value.instance_of?(Hash) && value.keys.sort == fields.sort
194
+ def self.shape!(value, fields, path = nil)
195
+ invalid!(path, :invalid_type) unless value.instance_of?(Hash)
196
+ missing = fields.find { |field| !value.key?(field) }
197
+ invalid!(path && "#{path}.#{missing}", :missing_required_field) if missing
198
+ invalid!(path, :unknown_field) unless value.keys.sort == fields.sort
199
+ end
200
+ def self.invalid!(field = nil, reason = :invalid_builder_input)
201
+ raise Invalid.new(field, reason), cause: nil
159
202
  end
160
- def self.invalid! = raise(Invalid, "invalid input-builder information")
161
203
  def self.json!(value, limit = InputValidator::MAX_BYTES)
162
204
  require "json"
163
205
  raise InputValidator::Unavailable, :json_dependency_unavailable unless JSON::VERSION == InputValidator::JSON_VERSION
@@ -206,6 +248,18 @@ module AP2MandateVerifier
206
248
  invalid!
207
249
  end
208
250
  end
251
+ # Validate keyword shape before Ruby's keyword errors can echo arbitrary
252
+ # caller-supplied names. Each captured implementation keeps its typed API.
253
+ %i[trust restore_trust prepare restore inputs].each do |name|
254
+ implementation = method(name)
255
+ fields = implementation.parameters.filter_map { |kind, field| field if kind == :keyreq }.freeze
256
+ define_singleton_method(name) do |**arguments|
257
+ missing = fields.find { |field| !arguments.key?(field) }
258
+ invalid!(missing&.to_s, :missing_required_field) if missing
259
+ invalid!("arguments", :unknown_field) unless arguments.length == fields.length
260
+ implementation.call(**arguments)
261
+ end
262
+ end
209
263
  private_class_method :context!, :binding!, :shape!, :invalid!, :json!, :copy!, :walk!
210
264
  end
211
265
  end
@@ -0,0 +1,22 @@
1
+ # frozen_string_literal: true
2
+
3
+ module AP2MandateVerifier
4
+ # Internal ES256 primitive. Callers must validate the payload's own profile.
5
+ module MerchantSignature
6
+ def self.sign!(claims, signer, public_key_pem)
7
+ RootSignature.send(:dependencies!)
8
+ payload = InputBuilder.send(:json!, claims, 12_000)
9
+ pem = InputValidator.snapshot!(public_key_pem, max_bytes: 1_024)
10
+ RootSignature.public_jwk!(pem)
11
+ header = Base64.urlsafe_encode64('{"alg":"ES256","typ":"JWT"}', padding: false)
12
+ input = "#{header}.#{Base64.urlsafe_encode64(payload, padding: false)}".freeze
13
+ raw = signer.call(input)
14
+ raise ArgumentError unless Object.instance_method(:instance_of?).bind_call(raw, String) &&
15
+ String.instance_method(:bytesize).bind_call(raw) == 64
16
+ signature = String.instance_method(:byteslice).bind_call(raw, 0, 64)
17
+ jwt = "#{input}.#{Base64.urlsafe_encode64(signature, padding: false)}"
18
+ raise ArgumentError unless RootSignature.verified_payload!(jwt, pem, expected_typ: "JWT", max_bytes: 16_384) == claims
19
+ jwt.freeze
20
+ end
21
+ end
22
+ end
@@ -67,6 +67,7 @@ module AP2MandateVerifier
67
67
  freeze
68
68
  end
69
69
  private_class_method :new, :allocate
70
+ def diagnostic = nil
70
71
  def status = :verified_research
71
72
  def code = :scoped_research_verified
72
73
  def success? = true
@@ -1,5 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "diagnostic"
4
+
3
5
  module AP2MandateVerifier
4
6
  # Legacy non-success type. The opt-in research entry uses a separate type.
5
7
  class Result
@@ -32,15 +34,23 @@ module AP2MandateVerifier
32
34
 
33
35
  attr_reader :status, :code
34
36
 
35
- def initialize(status:, code:)
37
+ def initialize(status:, code:, diagnostic: nil)
36
38
  unless CODES.fetch(status, []).include?(code)
37
39
  raise ArgumentError, "unsupported non-success result"
38
40
  end
39
41
  @status = status
40
42
  @code = code
43
+ @diagnostic = diagnostic if Object.instance_method(:instance_of?).bind_call(diagnostic, Diagnostic) && diagnostic.frozen?
41
44
  freeze
42
45
  end
43
46
 
47
+ # A diagnostic failure cannot affect the already determined verdict.
48
+ def diagnostic
49
+ @diagnostic || Diagnostic.for_result(status, code)
50
+ rescue StandardError, LoadError
51
+ nil
52
+ end
53
+
44
54
  def success? = false
45
55
  def evidence = nil
46
56
  def rejected? = status == :rejected
@@ -10,6 +10,9 @@ require_relative "ap2_mandate_verifier/trust_context"
10
10
  require_relative "ap2_mandate_verifier/host_binding"
11
11
  require_relative "ap2_mandate_verifier/research_result"
12
12
  require_relative "ap2_mandate_verifier/input_builder"
13
+ require_relative "ap2_mandate_verifier/merchant_signature"
14
+ require_relative "ap2_mandate_verifier/checkout_jwt"
15
+ require_relative "ap2_mandate_verifier/checkout_receipt"
13
16
 
14
17
  module AP2MandateVerifier
15
18
  # Accepts original JSON bytes only. Syntax validity is not AP2 validity,
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ap2_mandate_verifier
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AP2 Mandate Verifier contributors
@@ -89,11 +89,18 @@ extra_rdoc_files: []
89
89
  files:
90
90
  - LICENSE
91
91
  - README.md
92
+ - docs/DIAGNOSTICS.ja.md
93
+ - docs/DIAGNOSTICS.md
94
+ - docs/MERCHANT_SIGNING.md
92
95
  - docs/SUPPORT_CONTRACT.md
93
96
  - lib/ap2_mandate_verifier.rb
97
+ - lib/ap2_mandate_verifier/checkout_jwt.rb
98
+ - lib/ap2_mandate_verifier/checkout_receipt.rb
99
+ - lib/ap2_mandate_verifier/diagnostic.rb
94
100
  - lib/ap2_mandate_verifier/host_binding.rb
95
101
  - lib/ap2_mandate_verifier/input_builder.rb
96
102
  - lib/ap2_mandate_verifier/input_validator.rb
103
+ - lib/ap2_mandate_verifier/merchant_signature.rb
97
104
  - lib/ap2_mandate_verifier/purchase_binding.rb
98
105
  - lib/ap2_mandate_verifier/research_result.rb
99
106
  - lib/ap2_mandate_verifier/result.rb