ap2_mandate_verifier 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1e3f167538858b19e86097908f19d31235a3d6bf1f2478b13d0a3aa049ab527b
4
- data.tar.gz: 818e4c88efa929adcc209710c6d8e042a601820589a80bf20e7115db2700f00e
3
+ metadata.gz: dbeaa8817a128ad64b2307ae68a86cb2c36f40e710dc459f28354e24b3b251f9
4
+ data.tar.gz: 70d40f6293a88043e0f29f10b00e337418ae6819f91cffcb55db8f6c68f21785
5
5
  SHA512:
6
- metadata.gz: fe38d275af6ada51fbc70b2dbbf8d7d1c822d49304f839e0b9ca2b575b24ccd2e123c3b04c58862b30e90b375afe28c0c34a4376841f69f07e6c8438fc0abd1a
7
- data.tar.gz: 9a0cf42696c264f27b62b674fe6ba1c10c5916434cc3b83b8582e15d78c103a9ea4dee976610f09bb3c84c8fe2a7b6b9c2152b17b637fd8359c0738d2f2b24b9
6
+ metadata.gz: bd6ba8a1c4be5e8b81ff589624ab17d3e1d3861d49cb8aad457abf96708c2446b996381dc0c948f868538c6b80ae9d2ef45d1c693e2e1fa1cf6874df085faeb5
7
+ data.tar.gz: 7652d380a3ab2024016f0442672b384f6f8e8eecbec416318b1c9224cc8a954c3be1600e5eb1125f1f9eaa5b172609b41e6c0a3074564c0932bc897ae1f8d2ec
data/README.md CHANGED
@@ -1,35 +1,44 @@
1
- # AP2 Mandate Verifier — 0.4.0
1
+ # AP2 Mandate Verifier — 0.6.0 preparation
2
2
 
3
3
  [日本語](README.ja.md)
4
4
 
5
+ Published stable is **0.5.0**. This checkout prepares additive multi-item support for **0.6.0**, which is not published. Review, CI, final package validation and Owner publication approval are separate gates; see [current status](docs/PROJECT_STATUS.md).
6
+
7
+ ## Multiple items and quantities
8
+
9
+ Explicitly select `profile_ref: "ap2.checkout.single_merchant_multi_item"` when creating trust with `InputBuilder.trust`, signing a checkout with `CheckoutJWT.sign`, and using `CheckoutReceipt.reference/sign/verify`. The complete verifier follows the authenticated trust selection. The default `ap2.checkout.single_merchant_sku` v1 retains its exact definition, hash and one-line acceptance range.
10
+
11
+ The new v1 profile supports one merchant, one checkout, one currency and up to eight lines, with different quantities and repeated product IDs on distinct lines. It matches all disclosed product candidates using integer maximum flow: every requirement and every ordered unit must be consumed exactly once. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md) and [synthetic runnable lifecycle](examples/multi_item_checkout.rb).
12
+
5
13
  Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile. The Gem checks signed data against independently supplied Host trust and order information, then returns immutable Evidence. **Verification success is not purchase or payment permission.**
6
14
 
7
15
  `InputBuilder` converts business records into verification inputs: it creates the Gem-specific trust/selection/Host JSON, fingerprints and original-wire digests for you. You still choose whom to trust and supply the expected order, challenge state and clock. The Gem is Rails-independent and performs no network, database or payment operations.
8
16
 
9
17
  ## Try the local demo
10
18
 
11
- The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.4.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. Compare synthetic normal, tampered and expired cases, including actual status/code, diagnostics and Evidence presence. It is local-only; it does not issue real challenges, consume nonces or execute purchases.
19
+ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.5.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. Compare synthetic normal, tampered and expired cases, including actual status/code, diagnostics and Evidence presence. Merchant signing and authentic Success/Error Receipts are also available. It is local-only; it does not issue real challenges, consume nonces or execute purchases.
12
20
 
13
21
  ## Install
14
22
 
15
23
  Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
16
24
 
17
25
  ```sh
18
- gem install ap2_mandate_verifier --version 0.4.0
26
+ gem install ap2_mandate_verifier --version 0.5.0
19
27
  ```
20
28
 
21
29
  Or add to your Gemfile:
22
30
 
23
31
  ```ruby
24
- gem "ap2_mandate_verifier", "= 0.4.0"
32
+ gem "ap2_mandate_verifier", "= 0.5.0"
25
33
  ```
26
34
 
27
35
  Runtime dependencies are pinned to JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. Normal installation may download/build dependencies; do not relax the pins to work around a conflict. The Ruby resolution interval is not certification of every Ruby version, OS or native provider. See the [support contract](docs/SUPPORT_CONTRACT.md).
28
36
 
29
- ## Merchant signing and Receipt (unpublished 0.5.0 candidate)
37
+ ## Merchant signing and Receipt
30
38
 
31
- Create a signed checkout, then sign the application's explicit outcome. These
32
- additive APIs are available from the candidate source, not published 0.4.0:
39
+ Create a signed checkout, then sign the application's explicit outcome. These additive APIs are included in published 0.5.0.
40
+ Here `checkout` is the application order Hash, `key` its P-256 signing key,
41
+ `received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
33
42
 
34
43
  ```ruby
35
44
  signing = AP2MandateVerifier::CheckoutJWT
@@ -44,7 +53,7 @@ receipt = AP2MandateVerifier::CheckoutReceipt.sign(closed_sd_jwt: received_close
44
53
  Receipt verification separately checks a trusted public key, expected issuer,
45
54
  explicit time window and original closed-Mandate reference. An authentic Error
46
55
  Receipt has `verified? == true` and `purchase_succeeded? == false`.
47
- See the [complete API example, supported wire shape and SDK differences](docs/MERCHANT_SIGNING.md).
56
+ See the [complete runnable example](examples/merchant_signing.rb) and [API contract / SDK differences](docs/MERCHANT_SIGNING.md).
48
57
 
49
58
  ## A small InputBuilder example
50
59
 
@@ -116,13 +125,13 @@ Exceptions, process failure and missing results also never authorize an operatio
116
125
 
117
126
  The Gem checks signatures, supported disclosure closure, delegation, purchase/Host bindings, constraints and validity. The Host supplies authenticated, independent and current trust/keys/revocation, order/challenge state and clock. Before acting, it rechecks current state and validity, atomically consumes the nonce with order CAS, handles uncertain outcomes, and makes the final authorization/payment decision. `prepare`/`restore` do not authenticate storage or prove an unused nonce.
118
127
 
119
- Supported scope is the fixed `ap2.checkout.single_merchant_sku` profile v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and the documented disclosure shapes. Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer interoperability, signing/Receipt generation, Rails adapters, DB/payment execution and numeric performance guarantees are outside this release. Real Issuer/Host production GO and Phase 2-B remain separate HOLDs.
128
+ Published 0.5.0 uses `ap2.checkout.single_merchant_sku` v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and the documented disclosure shapes. This checkout adds the explicitly selected [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer interoperability, product Mandate issuance/presentation, Rails adapters, DB/payment execution and numeric performance guarantees remain outside scope. Real Issuer/Host production GO and Phase 2-B remain separate HOLDs.
120
129
 
121
130
  ### Which API should I use?
122
131
 
123
132
  | Entry | Role |
124
133
  | --- | --- |
125
- | `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.4.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
134
+ | `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.5.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
126
135
  | `verify_checkout(**inputs)` | Direct complete verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
127
136
  | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
128
137
  | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
@@ -133,7 +142,7 @@ Malformed assembly arguments, including missing keywords, to `InputBuilder.verif
133
142
 
134
143
  - [Business-data lifecycle and Rails mapping](docs/INPUT_BUILDER.md), [complete Ruby example](examples/input_builder.rb) and [before/after example](examples/input_builder_before.rb).
135
144
  - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
136
- - [Published 0.4.0 release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.4.0), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
145
+ - [Published 0.5.0 release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.5.0), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
137
146
  - [Pinned historical seven-input / saved FULL example](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#try-the-saved-synthetic-example), [older artifact/provider evidence](research/stable010_release_linux_package/README.md) and [historical conceptual diagrams](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#illustrated-concepts-japanese-diagrams). These records are preserved, not current integration instructions or broader support claims.
138
147
  - [Security reporting](SECURITY.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and [product direction](docs/PRODUCT_VISION.md). Do not include secrets, real Mandates or personal data in reports.
139
148
 
@@ -1,4 +1,23 @@
1
- # Merchant Checkout signing (unpublished candidate)
1
+ # Merchant Checkout signing and Receipt
2
+
3
+ ## Explicit multi-item selection — 0.6.0 preparation
4
+
5
+ Published 0.5.0 APIs below retain their default single-SKU behavior. This checkout
6
+ adds optional `profile_ref: "ap2.checkout.single_merchant_multi_item"` to
7
+ `CheckoutJWT.sign` and `CheckoutReceipt.reference/sign/verify`. Pass it consistently
8
+ when working with a multi-item Checkout. The new profile validates every line,
9
+ integer product/sum limits and unique line IDs before signing. Its
10
+ [full contract](MULTI_ITEM_CHECKOUT.md) covers quantities, candidate matching,
11
+ limits and migration; the [synthetic example](../examples/multi_item_checkout.rb)
12
+ connects signing with InputBuilder verification and both Receipt outcomes.
13
+
14
+ Receipt still references the complete original `<terminal_jws>~`, without
15
+ per-line hashes or a compact-only alternate. Profile selection validates the
16
+ supported embedded Checkout shape; reference computation alone does not verify
17
+ Mandate authorization. Result/Evidence and business-outcome separation remain
18
+ unchanged. 0.6.0 is not yet published; its final validation is recorded separately.
19
+
20
+ Published [0.5.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.5.0) includes these APIs. [Complete runnable synthetic example](../examples/merchant_signing.rb). The example is repository content, not part of the installed Gem.
2
21
 
3
22
  ## Scope and responsibility
4
23
 
@@ -11,8 +30,10 @@ merchant enrollment, persist an order, consume a nonce or make a payment.
11
30
  The adopted AP2 source remains
12
31
  [`b4587ac1d055888a73b4b21750973cffba961793`](https://github.com/google-agentic-commerce/AP2/tree/b4587ac1d055888a73b4b21750973cffba961793).
13
32
  Checkout-specific ordering is defined by the existing local fixed profile, not
14
- all UCP shapes. Unsupported fields, multiple items, nonempty links and unsupported
15
- currencies are rejected. Amounts are integer minor units; totals must agree.
33
+ all UCP shapes. Under the default profile, multiple items are rejected. The
34
+ explicit multi-item profile supports the documented bounded subset. Unsupported
35
+ fields, nonempty links and unsupported currencies are rejected in both profiles.
36
+ Amounts are integer minor units; totals must agree.
16
37
 
17
38
  ## Minimal executable example
18
39
 
@@ -0,0 +1,118 @@
1
+ # Multiple-item Checkout profile — 0.6.0 preparation
2
+
3
+ This is the contract for the additive, explicitly selected
4
+ `ap2.checkout.single_merchant_multi_item` version `1`. Published 0.5.0 remains
5
+ available with the unchanged `ap2.checkout.single_merchant_sku` v1 default.
6
+ Candidate test/CI/review/package completion is recorded separately in
7
+ [project status](PROJECT_STATUS.md); this document does not authorize publication.
8
+
9
+ ## Selection and lifecycle
10
+
11
+ Pass `profile_ref: "ap2.checkout.single_merchant_multi_item"` to:
12
+
13
+ - `InputBuilder.trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:, profile_ref:)`;
14
+ - `CheckoutJWT.sign(checkout:, signer:, public_key_pem:, profile_ref:)`;
15
+ - `CheckoutReceipt.reference`, `.sign` and `.verify`, alongside their existing arguments.
16
+
17
+ The complete `InputBuilder.verify` / seven-input `verify_checkout` pipeline
18
+ selects the profile from authenticated Host trust, never a token's self-claim.
19
+ Other arguments, Result status/code, supplemental diagnostic meaning, immutable
20
+ Evidence v2 and responsibility boundaries retain their existing meanings.
21
+ Lower-level purchase/constraint APIs accept an explicit `profile_ref:`; omitted
22
+ selection retains their old default.
23
+
24
+ For a complete synthetic preparation → saved challenge → restore → current-state
25
+ verification → Success/Error Receipt example, see
26
+ [`examples/multi_item_checkout.rb`](../examples/multi_item_checkout.rb).
27
+ Its test-only issuer/Agent construction is not a product Mandate issuance API.
28
+ The expected successful verifier result remains
29
+ `verified_research/scoped_research_verified`; an authentic Error Receipt has
30
+ `verified? == true`, `purchase_succeeded? == false`.
31
+
32
+ Persist the original challenge String and all signed Strings. Restore trust and
33
+ challenge bytes without reserializing them. Migration creates a new authenticated
34
+ profile selection and a new challenge before presentation; it never relabels or
35
+ repairs an old challenge. An old saved envelope remains an old-profile envelope.
36
+ Current profile, order, trust and signed-byte differences must remain detectable.
37
+
38
+ ## Product, requirement and line identity
39
+
40
+ There are three independent identities: requirement `id`, checkout line `id`,
41
+ and product `item.id` / candidate `id`. Requirement IDs must be unique within
42
+ requirements; line IDs must be unique within checkout lines. They need not match
43
+ each other. Candidate product IDs must be unique within each requirement.
44
+ Different requirements may contain overlapping candidate IDs.
45
+
46
+ Repeated product IDs on different checkout lines are supported. Quantity
47
+ allocation connects lines to requirements by product ID only for evaluation; it never deletes,
48
+ deduplicates, sorts or replaces signed lines. Titles remain bounded strings,
49
+ but product matching uses IDs. Price and totals are checked for every line.
50
+
51
+ An integer maximum-flow allocation must consume both all required quantities
52
+ and all ordered quantities. A unit cannot satisfy two requirements. For example,
53
+ requirements `{A or B: 1}` and `{A: 1}` accept `A: 1, B: 1`; a greedy allocation
54
+ which consumes A for the first requirement is insufficient. Missing units,
55
+ extra units and extra products reject. One requirement's quantity may be
56
+ distributed across its revealed candidate IDs.
57
+
58
+ Ordering does not change quantity satisfiability. A separately and correctly
59
+ signed checkout in another order has different original bytes and must be bound
60
+ by its own Mandate and Host challenge. Reordering an existing signed JWT or
61
+ reusing the previous reference is a signature/binding failure.
62
+
63
+ ## Closed subset and limits
64
+
65
+ These are Gem profile restrictions, not general AP2 requirements.
66
+
67
+ | Input | New v1 limit / supported form |
68
+ | --- | --- |
69
+ | Merchant / Checkout / currency | One each; USD, EUR or JPY |
70
+ | Checkout lines | 1–8; distinct line IDs |
71
+ | Requirements | 1–8; distinct requirement IDs |
72
+ | Candidates per requirement | 1–8; distinct product IDs within the requirement |
73
+ | Quantity per line / requirement | Integer 1–1,000,000 |
74
+ | Unit price / multiplication / summed total | Integer minor units, 0–9,007,199,254,740,991 |
75
+ | Line and Checkout totals | Exactly subtotal and total, each equal to its checked amount |
76
+ | Constraints | Ordered `checkout.line_items`, then `checkout.allowed_merchants`; no unknown constraints |
77
+ | Links / taxes / shipping / discount | Empty links; no tax, shipping or discount engine or extra total types |
78
+ | Root disclosures | Every candidate, the Open payload and allowed merchant; at most 66 |
79
+ | Disclosure segment / Root input | 8,192 / 131,072 bytes |
80
+ | Commitment walk | At most 2,048 visits; container depth 24; array length 16 |
81
+ | Checkout JWT / terminal JWS | Existing 16,384 / 32,768 byte limits |
82
+
83
+ All candidate positions must be array commitments under
84
+ `delegate_payload[0].disclosed.constraints[0].items[i].acceptable_items[j]`.
85
+ The Open payload and sole allowed merchant retain their existing commitment
86
+ positions. Missing, reused or unused disclosures and unsupported positions fail
87
+ closed. Bounds apply together: an input below one count cap can still exceed
88
+ the segment, wire or traversal cap. Oversized values are rejected, never truncated.
89
+ No unmeasured worst-case CPU, memory, concurrency or numeric SLA is promised.
90
+
91
+ ## Normative source and SDK differences
92
+
93
+ The AP2 source stays pinned to
94
+ `b4587ac1d055888a73b4b21750973cffba961793`. The Line Items normative text defines
95
+ maximum flow and requires both sides to be fully satisfied. Schema descriptions
96
+ and Python helper behavior must be compared independently; see
97
+ [the interoperability record](MULTI_ITEM_INTEROP.md) for measured cases and scope.
98
+ No generic AP2/full-Schema or real-Issuer conformance claim follows from synthetic
99
+ tests. Unrelated latest-spec changes are not adopted by this profile.
100
+
101
+ Receipt still uses Checkout-specific `status: Success/Error`. Its reference is
102
+ the original final closed SD-JWT `<terminal_jws>~`; no per-line receipt or
103
+ compact-only alternate hash is introduced. The existing
104
+ [Receipt specification/SDK differences](MERCHANT_SIGNING.md) remain applicable.
105
+
106
+ ## Host responsibilities
107
+
108
+ The Host independently supplies authenticated, current trust/keys/revocation,
109
+ clock, expected order/currency/total and saved challenge state. A total extracted
110
+ from the received checkout is not an independent expected order. It rechecks
111
+ state before acting, atomically consumes the nonce with order CAS, handles
112
+ uncertain outcomes and makes the final purchase/payment decision.
113
+
114
+ Verification success is checked Evidence, not Host ALLOW or payment success.
115
+ Receipt authenticity is separate from its explicit business outcome. Multiple
116
+ merchants, splitting one Open Mandate across Checkouts, Payment Mandates/Receipts,
117
+ product issuance/presentation, real payments and production operation are outside
118
+ this task. Formal MRI 3.4.12 / 4.0.9 and all five runtime dependency pins are unchanged.
@@ -1,8 +1,28 @@
1
- # Fixed-profile AP2 verification — published 0.4.0 / historical releases
1
+ # Fixed-profile AP2 verification — 0.6.0 preparation / published history
2
2
 
3
- Unpublished **0.5.0 candidate** adds separate [Merchant signing and Checkout Receipt APIs](MERCHANT_SIGNING.md). They do not broaden the existing Verifier profile or change Result/Evidence/status/code. Checkout Receipt uses the dedicated Schema and normative final SD-JWT reference; unsupported forms fail closed. No product Mandate issuance, payment, persistence or real key/trust management is included.
3
+ ## Current source: explicit multi-item profile
4
4
 
5
- Published 0.4.0 adds supplemental safe diagnostics; see [API and troubleshooting](DIAGNOSTICS.md). Existing verdict/Evidence contracts remain unchanged.
5
+ This checkout prepares **0.6.0**, not yet published. It adds the explicitly
6
+ selected `ap2.checkout.single_merchant_multi_item` v1 across input preparation,
7
+ restoration/current-state verification, Checkout signing and Checkout Receipts.
8
+ The [multi-item contract](MULTI_ITEM_CHECKOUT.md) defines the accepted shapes,
9
+ eight-line/eight-requirement/eight-candidate bounds, integer maximum-flow matching,
10
+ complete disclosures, exact original-byte binding and migration. Existing
11
+ `ap2.checkout.single_merchant_sku` v1 identifier/body/hash/acceptance range and all
12
+ default APIs remain unchanged. Historical single-profile statements below describe
13
+ their original releases; they do not exclude this separately selected addition.
14
+
15
+ Formal MRI 3.4.12 and 4.0.9, all five dependency pins, Result/status/code,
16
+ diagnostic and Evidence meanings remain unchanged. Tests, independent review,
17
+ CI and final archive identities must be read from the task's final validation
18
+ record; pending work is not a PASS. Publication/tag/Release operations require
19
+ Owner judgment and have not been performed for 0.6.0.
20
+
21
+ Published **0.5.0** adds separate [Merchant signing and Checkout Receipt APIs](MERCHANT_SIGNING.md). They do not broaden the existing Verifier profile or change Result/Evidence/status/code. Checkout Receipt uses the dedicated Schema and normative final SD-JWT reference; unsupported forms fail closed. No product Mandate issuance, payment, persistence or real key/trust management is included.
22
+
23
+ [0.5.0 publication record](PROJECT_STATUS.md#050-publication): 50,688 bytes, SHA256 `00b0ce0981070864c67a056906c5af204bbc5aaa80d029cb4a64294634367dd8`, approved source `bf796a53600c189b0cfe66c9cfcd1de8a353c03d`. Current repository examples/docs do not replace the published preparation snapshot.
24
+
25
+ Historical published 0.4.0 adds supplemental safe diagnostics; see [API and troubleshooting](DIAGNOSTICS.md). Existing verdict/Evidence contracts remain unchanged.
6
26
 
7
27
  [0.4.0 on RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.4.0) was registered 2026-10-31 04:25:06.427 UTC and compared at 04:26:15 UTC: owner `cuichangquan`, platform `ruby`, prerelease false, not yanked at comparison; 44,032 bytes, SHA256 `b212db01e7deb18dcef1199414f9d93ef43cb1f74b62baa55306de3955dfe177`. The download matches the saved reviewed artifact and all 17 payload files match source `fc42852f53c615f96d7c165a8de494b24b252519`. RubyGems does not independently attest the source SHA. Formal MRI support and all five runtime pins below are unchanged. [Publication record](PROJECT_STATUS.md#040-publication) and [validation scope](DIAGNOSTICS_VALIDATION.md). Packaged documentation retains its preparation snapshot; repository updates do not replace published bytes.
8
28
 
@@ -66,7 +86,7 @@ Gem-owned signature/original-wire/closure, delegation, binding, supplied-trust s
66
86
  Host inputs must be authenticated, independent of the token and current: trust/keys/profile/revocation/rollback protection, clock and order/challenge state. Recheck before use; atomically consume nonce with order CAS, reconcile unknown results as PENDING, and decide final ALLOW/payment separately.
67
87
  Evidence is immutable checked facts in the same trusted Ruby process, not ALLOW or a transport credential. JSON/Hash reconstruction does not authenticate it. Rejection, unavailability, exceptions and no result never authorize an operation. Trusted Ruby is a precondition, not a malicious-Ruby sandbox.
68
88
 
69
- No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds. Issuance, presentation generation, Receipt, Rails adapter, real payments and Host DB operations are outside this verifier.
89
+ No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds. Product Mandate issuance/presentation, Rails adapters, real payments and Host DB operations remain outside the Gem. Separate merchant signing/Checkout Receipt APIs are documented in [MERCHANT_SIGNING](MERCHANT_SIGNING.md).
70
90
  Supported-input semantics and existing API/status/code/Evidence contracts must not change silently. Security-driven acceptance narrowing requires impact/reason/migration disclosure; breaking required-field/profile/API changes must be explicit. Dependency updates are not automatically compatible.
71
91
 
72
92
  The published 0.2.0 and historical baseline below is MRI4.0.9 plus JSON2.19.9/JWT3.3.0/base640.3.0/OpenSSL gem4.0.2/Digest3.2.1, with the exact observed MBA arm64-darwin25 and Ubuntu24.04/x86_64 configurations. RubyGems version constraints do not enforce MRI/OS/provider identity. All OS versions, other engines/architectures and arbitrary provider updates are not supported by past observations.
@@ -81,7 +101,7 @@ The API/limit specification below preserves the existing contract. All pre2/pre3
81
101
 
82
102
  ## Supported proposition and environment
83
103
 
84
- The sole registered profile is `ap2.checkout.single_merchant_sku` version1,
104
+ The historical sole registered profile is `ap2.checkout.single_merchant_sku` version1,
85
105
  with the exact `TrustContext::PROFILE_BODY`/hash. Official AP2 source is fixed at
86
106
  b4587ac1d055888a73b4b21750973cffba961793; its subset-source reference027ed4734...
87
107
  is historical profile provenance, not runtime code attestation. Root typ is
@@ -20,10 +20,10 @@ module AP2MandateVerifier
20
20
  # signer.call receives the exact ASCII JWS signing input and must return a
21
21
  # 64-byte JOSE ES256 signature. The supplied independent public key verifies
22
22
  # the result before any signed object is returned (including remote signers).
23
- def self.sign(checkout:, signer:, public_key_pem:)
23
+ def self.sign(checkout:, signer:, public_key_pem:, profile_ref: TrustContext::PROFILE_REF)
24
24
  RootSignature.send(:dependencies!)
25
25
  value = InputBuilder.send(:copy!, checkout)
26
- validate!(value)
26
+ validate!(value, profile_ref: profile_ref)
27
27
  jwt = MerchantSignature.sign!(value, signer, public_key_pem)
28
28
  Signed.send(:new, jwt)
29
29
  rescue StandardError, LoadError
@@ -44,7 +44,13 @@ module AP2MandateVerifier
44
44
  raise Invalid.new, cause: nil
45
45
  end
46
46
 
47
- def self.validate!(checkout)
47
+ def self.validate!(checkout, profile_ref: TrustContext::PROFILE_REF)
48
+ profile_ref = InputValidator.snapshot!(profile_ref, max_bytes: 256)
49
+ if profile_ref == ScopedConstraints::MULTI_PROFILE_REF
50
+ ScopedConstraints.multi_checkout!(checkout)
51
+ return nil
52
+ end
53
+ raise Invalid unless profile_ref == TrustContext::PROFILE_REF
48
54
  c = ScopedConstraints
49
55
  c.send(:exact!, checkout, %w[currency id line_items links merchant status totals])
50
56
  c.send(:text!, checkout["id"])
@@ -71,8 +77,9 @@ module AP2MandateVerifier
71
77
  %i[sign es256_signer].each do |name|
72
78
  implementation = method(name)
73
79
  fields = implementation.parameters.filter_map { |kind, field| field if kind == :keyreq }.freeze
80
+ optional = implementation.parameters.filter_map { |kind, field| field if kind == :key }.freeze
74
81
  define_singleton_method(name) do |**arguments|
75
- raise Invalid.new, cause: nil unless (fields - arguments.keys).empty? && (arguments.keys - fields).empty?
82
+ raise Invalid.new, cause: nil unless (fields - arguments.keys).empty? && (arguments.keys - fields - optional).empty?
76
83
  implementation.call(**arguments)
77
84
  end
78
85
  end
@@ -32,7 +32,7 @@ module AP2MandateVerifier
32
32
 
33
33
  # Exact received final closed SD-JWT, no disclosures or additional hop.
34
34
  # A terminal compact JWS alone is intentionally not accepted or repaired.
35
- def self.reference(closed_sd_jwt:)
35
+ def self.reference(closed_sd_jwt:, profile_ref: TrustContext::PROFILE_REF)
36
36
  wire = InputValidator.snapshot!(closed_sd_jwt, max_bytes: 32_769)
37
37
  raise Invalid unless wire.ascii_only? && wire.end_with?("~") && wire.count("~") == 1
38
38
  compact = wire.byteslice(0, wire.bytesize - 1)
@@ -62,15 +62,16 @@ module AP2MandateVerifier
62
62
  checkout_header = InputValidator.parse!(RootSignature.send(:decode!, checkout_parts[0], 2_048))
63
63
  header!(checkout_header, "JWT")
64
64
  raise Invalid unless RootSignature.send(:decode!, checkout_parts[2], 64).bytesize == 64
65
- CheckoutJWT.send(:validate!, InputValidator.parse!(RootSignature.send(:decode!, checkout_parts[1], 12_000)))
65
+ CheckoutJWT.send(:validate!, InputValidator.parse!(RootSignature.send(:decode!, checkout_parts[1], 12_000)), profile_ref: profile_ref)
66
66
  raise Invalid unless closed["checkout_hash"] == hash(checkout)
67
67
  hash(wire).freeze
68
68
  rescue StandardError, LoadError
69
69
  raise Invalid.new, cause: nil
70
70
  end
71
71
 
72
- def self.sign(closed_sd_jwt:, issuer:, outcome:, issued_at:, signer:, public_key_pem:, order_id: nil, error: nil, error_description: nil)
73
- ref = reference(closed_sd_jwt: closed_sd_jwt)
72
+ def self.sign(closed_sd_jwt:, issuer:, outcome:, issued_at:, signer:, public_key_pem:, order_id: nil, error: nil, error_description: nil,
73
+ profile_ref: TrustContext::PROFILE_REF)
74
+ ref = reference(closed_sd_jwt: closed_sd_jwt, profile_ref: profile_ref)
74
75
  claims = {"iss" => issuer, "status" => outcome, "iat" => issued_at, "reference" => ref}
75
76
  claims["order_id"] = order_id unless order_id.nil?
76
77
  claims["error"] = error unless error.nil?
@@ -86,12 +87,13 @@ module AP2MandateVerifier
86
87
  # The Host supplies trusted enrollment key, expected signer and explicit time
87
88
  # window independently. JWT iss/kid are never used to choose trust.
88
89
  # Reference authenticates byte identity, not Mandate authorization/validity.
89
- def self.verify(jwt:, closed_sd_jwt:, trusted_public_key_pem:, expected_issuer:, not_before:, not_after:, verified_at:)
90
+ def self.verify(jwt:, closed_sd_jwt:, trusted_public_key_pem:, expected_issuer:, not_before:, not_after:, verified_at:,
91
+ profile_ref: TrustContext::PROFILE_REF)
90
92
  expected = InputValidator.snapshot!(expected_issuer, max_bytes: 512)
91
93
  text!(expected, 512)
92
94
  [not_before, not_after, verified_at].each { |t| epoch!(t) }
93
95
  raise Invalid unless not_before <= verified_at && verified_at <= not_after
94
- ref = reference(closed_sd_jwt: closed_sd_jwt)
96
+ ref = reference(closed_sd_jwt: closed_sd_jwt, profile_ref: profile_ref)
95
97
  claims = RootSignature.verified_payload!(jwt, trusted_public_key_pem, expected_typ: "JWT", max_bytes: 16_384)
96
98
  validate!(claims)
97
99
  return Verification.send(:new, :receipt_issuer_mismatch) unless claims["iss"] == expected
@@ -78,7 +78,8 @@ module AP2MandateVerifier
78
78
  host_checkout_jws: checkout, **context.fetch(:keys), expected_aud: binding["audience"],
79
79
  expected_nonce: challenge["nonce"], verified_at: verified_at,
80
80
  expected_checkout_id: binding["order_id"], expected_merchant_id: binding["merchant_id"],
81
- expected_currency: binding["currency"], expected_total_minor: binding["expected_total"])
81
+ expected_currency: binding["currency"], expected_total_minor: binding["expected_total"],
82
+ profile_ref: references.fetch("profile_ref"))
82
83
  open, closed, proof = details.values_at(:open, :closed, :terminal)
83
84
  starts = [context.fetch(:valid_from), challenge["not_before"], open["iat"], closed["iat"], proof["iat"]]
84
85
  ends = [context.fetch(:valid_until), challenge["not_after"], open["exp"], closed["exp"], proof["iat"] + 301]
@@ -33,28 +33,29 @@ module AP2MandateVerifier
33
33
 
34
34
  # All registry entries are preserved, including inactive/nonselected entries.
35
35
  # Selection is explicit Host policy, never extracted from signed claims.
36
- def self.trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:)
36
+ def self.trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:, profile_ref: TrustContext::PROFILE_REF)
37
37
  verified_at = copy!(verified_at)
38
+ profile = TrustContext.profile!(copy!(profile_ref))
38
39
  source = copy!(snapshot)
39
40
  shape!(source, %w[id policy_version active not_before not_after records], "snapshot")
40
41
  invalid!("snapshot.records", :invalid_type) unless source["records"].instance_of?(Array)
41
42
  invalid!("snapshot.records", :invalid_value) unless source["records"].length.between?(1, 16)
42
43
  source["records"].each do |record|
43
44
  shape!(record, RECORD_FIELDS)
44
- record.merge!("profile_ref" => TrustContext::PROFILE_REF, "profile_version" => TrustContext::PROFILE_VERSION,
45
+ record.merge!("profile_ref" => profile[:ref], "profile_version" => profile[:version],
45
46
  "algorithm" => "ES256", "key_fingerprint" => Digest::SHA256.hexdigest(record.fetch("public_key_pem")))
46
47
  end
47
48
  body = json!(source, 65_536)
48
49
  selection = {"trust_snapshot_id" => source["id"], "policy_version" => source["policy_version"],
49
50
  "trust_content_hash" => Digest::SHA256.hexdigest(body), "tenant_id" => copy!(tenant_id),
50
- "profile_ref" => TrustContext::PROFILE_REF, "profile_version" => TrustContext::PROFILE_VERSION,
51
- "profile_definition_hash" => TrustContext::PROFILE_HASH,
51
+ "profile_ref" => profile[:ref], "profile_version" => profile[:version],
52
+ "profile_definition_hash" => profile[:hash],
52
53
  "Issuer" => copy!(issuer), "Agent" => copy!(agent), "Merchant" => copy!(merchant)}
53
54
  TrustContext::ROLES.each_key { |role| shape!(selection[role], %w[identity purpose key_ref], role.downcase) }
54
55
  wire = json!({"snapshot" => {"id" => source["id"], "policy_version" => source["policy_version"],
55
56
  "content_hash" => selection["trust_content_hash"], "body" => body},
56
- "profile" => {"profile_ref" => TrustContext::PROFILE_REF, "version" => TrustContext::PROFILE_VERSION,
57
- "definition_hash" => TrustContext::PROFILE_HASH, "body" => TrustContext::PROFILE_BODY}})
57
+ "profile" => {"profile_ref" => profile[:ref], "version" => profile[:version],
58
+ "definition_hash" => profile[:hash], "body" => profile[:body]}})
58
59
  selected = json!(selection, 16_384)
59
60
  context = TrustContext.verified_context!(trust_json: wire, selection_json: selected, verified_at: verified_at,
60
61
  expected_merchant_id: selection.fetch("Merchant").fetch("identity"))
@@ -94,8 +95,8 @@ module AP2MandateVerifier
94
95
  "B" => binding!(context, order, root_presentation, host_checkout_jws),
95
96
  "not_before" => copy!(not_before), "not_after" => copy!(not_after), "state" => "issued"}
96
97
  HostBinding::REFERENCES.each { |field| challenge[field] = context.fetch(:references).fetch(field) }
97
- saved = json!({"format_version" => FORMAT_VERSION, "profile_ref" => TrustContext::PROFILE_REF,
98
- "profile_version" => TrustContext::PROFILE_VERSION, "challenge" => challenge}, 32_768)
98
+ saved = json!({"format_version" => FORMAT_VERSION, "profile_ref" => context.fetch(:references).fetch("profile_ref"),
99
+ "profile_version" => context.fetch(:references).fetch("profile_version"), "challenge" => challenge}, 32_768)
99
100
  restore(saved_challenge: saved)
100
101
  rescue Invalid
101
102
  raise
@@ -111,13 +112,16 @@ module AP2MandateVerifier
111
112
  wire = InputValidator.snapshot!(saved_challenge, max_bytes: 32_768)
112
113
  value = InputValidator.parse!(wire)
113
114
  shape!(value, %w[format_version profile_ref profile_version challenge], "saved_challenge")
115
+ invalid!("saved_challenge", :unsupported_saved_format) unless
116
+ [TrustContext::PROFILE_REF, TrustContext::MULTI_PROFILE_REF].include?(value["profile_ref"])
117
+ profile = TrustContext.profile!(value["profile_ref"])
114
118
  invalid!("saved_challenge", :unsupported_saved_format) unless value.values_at("format_version", "profile_ref", "profile_version") ==
115
- [FORMAT_VERSION, TrustContext::PROFILE_REF, TrustContext::PROFILE_VERSION]
119
+ [FORMAT_VERSION, profile[:ref], profile[:version]]
116
120
  challenge = value["challenge"]
117
121
  shape!(challenge, HostBinding::CHALLENGE_FIELDS)
118
122
  HostBinding.send(:binding!, challenge["B"])
119
123
  invalid! unless challenge["B"].values_at("profile_ref", "profile_version") ==
120
- [TrustContext::PROFILE_REF, TrustContext::PROFILE_VERSION]
124
+ profile.values_at(:ref, :version)
121
125
  %w[challenge_id nonce issuer_id trust_snapshot_id policy_version state].each { |field| HostBinding.send(:id!, challenge[field]) }
122
126
  %w[trust_content_hash profile_definition_hash].each { |field| HostBinding.send(:hash!, challenge[field]) }
123
127
  %w[not_before not_after].each { |field| HostBinding.send(:time!, challenge[field]) }
@@ -253,10 +257,11 @@ module AP2MandateVerifier
253
257
  %i[trust restore_trust prepare restore inputs].each do |name|
254
258
  implementation = method(name)
255
259
  fields = implementation.parameters.filter_map { |kind, field| field if kind == :keyreq }.freeze
260
+ optional = implementation.parameters.filter_map { |kind, field| field if kind == :key }.freeze
256
261
  define_singleton_method(name) do |**arguments|
257
262
  missing = fields.find { |field| !arguments.key?(field) }
258
263
  invalid!(missing&.to_s, :missing_required_field) if missing
259
- invalid!("arguments", :unknown_field) unless arguments.length == fields.length
264
+ invalid!("arguments", :unknown_field) unless (arguments.keys - fields - optional).empty?
260
265
  implementation.call(**arguments)
261
266
  end
262
267
  end
@@ -24,7 +24,8 @@ module AP2MandateVerifier
24
24
  def self.verified_details!(root_presentation:, terminal_jws:, host_checkout_jws:,
25
25
  trusted_issuer_public_key_pem:, expected_agent_public_key_pem:,
26
26
  trusted_merchant_public_key_pem:, expected_aud:, expected_nonce:,
27
- verified_at:, expected_checkout_id:, expected_merchant_id:)
27
+ verified_at:, expected_checkout_id:, expected_merchant_id:,
28
+ profile_ref: TrustContext::PROFILE_REF)
28
29
  # Snapshot every caller-owned byte string before starting cryptography.
29
30
  root_wire = InputValidator.snapshot!(root_presentation)
30
31
  terminal_wire = InputValidator.snapshot!(terminal_jws, max_bytes: 32_768)
@@ -39,7 +40,11 @@ module AP2MandateVerifier
39
40
  raise RootSignature::Unavailable, :purchase_context_unavailable unless integer?(verified_at) &&
40
41
  verified_at.between?(0, MAX_EPOCH)
41
42
 
42
- root = RootDisclosures.verified_root!(root_wire, issuer_pem)
43
+ root = if profile_ref == TrustContext::PROFILE_REF
44
+ RootDisclosures.verified_root!(root_wire, issuer_pem)
45
+ else
46
+ RootDisclosures.verified_root!(root_wire, issuer_pem, profile_ref: profile_ref)
47
+ end
43
48
  open = root.fetch("delegate_payload").first
44
49
  exact!(open, %w[cnf constraints exp iat vct])
45
50
  raise Rejected, :unsupported_purchase_profile unless open["vct"] == "mandate.checkout.open.1"
@@ -21,11 +21,13 @@ module AP2MandateVerifier
21
21
 
22
22
  # Internal handoff only: signature and entire closure are verified first.
23
23
  # AP2 semantics, constraints and Host authorization remain unvalidated.
24
- def self.verified_root!(source, issuer_pem)
24
+ def self.verified_root!(source, issuer_pem, profile_ref: TrustContext::PROFILE_REF)
25
+ multi = profile_ref == "ap2.checkout.single_merchant_multi_item"
26
+ raise Rejected, :unsupported_disclosure_profile unless multi || profile_ref == TrustContext::PROFILE_REF
25
27
  wire = InputValidator.snapshot!(source)
26
28
  raise Rejected, :invalid_root_presentation unless wire.ascii_only? && wire.end_with?("~")
27
29
  parts = wire.split("~", -1)
28
- raise Rejected, :invalid_root_presentation unless parts.size.between?(3, MAX_DISCLOSURES + 2) &&
30
+ raise Rejected, :invalid_root_presentation unless parts.size.between?(3, (multi ? 66 : MAX_DISCLOSURES) + 2) &&
29
31
  parts.last == "" && !parts.first.empty? && parts[1...-1].none?(&:empty?)
30
32
  # No disclosure decode, digest graph or trusted claims before signature.
31
33
  payload = RootSignature.verified_payload!(parts.first, issuer_pem)
@@ -48,13 +50,14 @@ module AP2MandateVerifier
48
50
  used = {}
49
51
  observed = []
50
52
  budget = [0]
51
- resolved = walk!(payload, [], mapping, used, observed, budget, 1)
52
- raise Rejected, :unsupported_disclosure_profile unless observed.sort_by(&:to_s) == PATHS.sort_by(&:to_s)
53
+ resolved = walk!(payload, [], mapping, used, observed, budget, 1, multi)
54
+ paths = multi ? multi_paths!(resolved) : PATHS
55
+ raise Rejected, :unsupported_disclosure_profile unless observed.sort_by(&:to_s) == paths.sort_by(&:to_s)
53
56
  raise Rejected, :extra_disclosure unless used.size == mapping.size
54
57
  resolved
55
58
  end
56
59
 
57
- def self.walk!(value, path, mapping, used, observed, budget, depth)
60
+ def self.walk!(value, path, mapping, used, observed, budget, depth, multi)
58
61
  budget[0] += 1
59
62
  raise Rejected, :disclosure_limit_exceeded if budget[0] > 2_048 ||
60
63
  (depth > 24 && (value.instance_of?(Hash) || value.instance_of?(Array)))
@@ -63,13 +66,14 @@ module AP2MandateVerifier
63
66
  raise Rejected, :unsupported_disclosure_profile if value.key?("_sd") || value.key?("...") ||
64
67
  (path != [] && value.key?("_sd_alg"))
65
68
  raise Rejected, :disclosure_limit_exceeded if value.size > 32
66
- value.to_h { |key, child| [key, walk!(child, path + [key], mapping, used, observed, budget, depth + 1)] }
69
+ value.to_h { |key, child| [key, walk!(child, path + [key], mapping, used, observed, budget, depth + 1, multi)] }
67
70
  when Array
68
71
  raise Rejected, :disclosure_limit_exceeded if value.size > 16
69
72
  value.each_with_index.map do |item, index|
70
73
  here = path + [index]
71
74
  if item.instance_of?(Hash) && item.key?("...")
72
- raise Rejected, :unsupported_disclosure_profile unless item.keys == ["..."] && PATHS.include?(here)
75
+ raise Rejected, :unsupported_disclosure_profile unless item.keys == ["..."] &&
76
+ (multi ? multi_path?(here) : PATHS.include?(here))
73
77
  digest = item["..."]
74
78
  raise Rejected, :invalid_disclosure unless digest.instance_of?(String) &&
75
79
  digest.bytesize == 43 && decode!(digest).bytesize == 32
@@ -77,9 +81,9 @@ module AP2MandateVerifier
77
81
  raise Rejected, :missing_disclosure unless mapping.key?(digest)
78
82
  used[digest] = true
79
83
  observed << here
80
- walk!(mapping.fetch(digest), here + ["disclosed"], mapping, used, observed, budget, depth + 1)
84
+ walk!(mapping.fetch(digest), here + ["disclosed"], mapping, used, observed, budget, depth + 1, multi)
81
85
  else
82
- walk!(item, here, mapping, used, observed, budget, depth + 1)
86
+ walk!(item, here, mapping, used, observed, budget, depth + 1, multi)
83
87
  end
84
88
  end
85
89
  else
@@ -87,6 +91,25 @@ module AP2MandateVerifier
87
91
  end
88
92
  end
89
93
 
94
+ def self.multi_path?(path)
95
+ return true if PATHS[0..1].include?(path)
96
+ path.size == 9 && path[0, 6] == ["delegate_payload", 0, "disclosed", "constraints", 0, "items"] &&
97
+ path[6].instance_of?(Integer) && path[6].between?(0, 7) &&
98
+ path[7] == "acceptable_items" && path[8].instance_of?(Integer) && path[8].between?(0, 7)
99
+ end
100
+
101
+ def self.multi_paths!(resolved)
102
+ items = resolved.dig("delegate_payload", 0, "constraints", 0, "items")
103
+ raise Rejected, :unsupported_disclosure_profile unless items.instance_of?(Array) && items.size.between?(1, 8)
104
+ paths = PATHS[0..1].dup
105
+ items.each_with_index do |item, i|
106
+ candidates = item.instance_of?(Hash) && item["acceptable_items"]
107
+ raise Rejected, :unsupported_disclosure_profile unless candidates.instance_of?(Array) && candidates.size.between?(1, 8)
108
+ candidates.each_index { |j| paths << ["delegate_payload", 0, "disclosed", "constraints", 0, "items", i, "acceptable_items", j] }
109
+ end
110
+ paths
111
+ end
112
+
90
113
  def self.decode!(part)
91
114
  raise Rejected, :invalid_disclosure unless part.match?(/\A[A-Za-z0-9_-]+\z/)
92
115
  raw = Base64.urlsafe_decode64(part + "=" * (-part.bytesize % 4))
@@ -95,6 +118,6 @@ module AP2MandateVerifier
95
118
  rescue ArgumentError
96
119
  raise Rejected, :invalid_disclosure
97
120
  end
98
- private_class_method :walk!, :decode!
121
+ private_class_method :walk!, :decode!, :multi_path?, :multi_paths!
99
122
  end
100
123
  end
@@ -6,6 +6,10 @@ module AP2MandateVerifier
6
6
  module ScopedConstraints
7
7
  MAX_AMOUNT = 9_007_199_254_740_991
8
8
  MAX_QUANTITY = 1_000_000
9
+ MULTI_PROFILE_REF = "ap2.checkout.single_merchant_multi_item"
10
+ MAX_LINES = 8
11
+ MAX_REQUIREMENTS = 8
12
+ MAX_CANDIDATES = 8
9
13
  CURRENCIES = %w[USD EUR JPY].freeze
10
14
  CORE_INSTANCE_OF = Object.instance_method(:instance_of?)
11
15
  class Rejected < RootSignature::Rejected; end
@@ -16,7 +20,7 @@ module AP2MandateVerifier
16
20
  end
17
21
 
18
22
  # Internal claims handoff after the complete existing limited profile.
19
- def self.verified_constraints!(expected_currency:, expected_total_minor:, **binding_inputs)
23
+ def self.verified_constraints!(expected_currency:, expected_total_minor:, profile_ref: TrustContext::PROFILE_REF, **binding_inputs)
20
24
  begin
21
25
  currency = InputValidator.snapshot!(expected_currency, max_bytes: 3)
22
26
  rescue InputValidator::Invalid
@@ -25,6 +29,12 @@ module AP2MandateVerifier
25
29
  raise RootSignature::Unavailable, :constraint_context_unavailable unless
26
30
  CURRENCIES.include?(currency) && CORE_INSTANCE_OF.bind_call(expected_total_minor, Integer) &&
27
31
  expected_total_minor.between?(0, MAX_AMOUNT)
32
+ if profile_ref == MULTI_PROFILE_REF
33
+ details = PurchaseBinding.verified_details!(**binding_inputs, profile_ref: profile_ref)
34
+ multi_constraints!(details, currency, expected_total_minor)
35
+ return details
36
+ end
37
+ raise Rejected, :unsupported_scoped_profile unless profile_ref == TrustContext::PROFILE_REF
28
38
  details = PurchaseBinding.verified_details!(**binding_inputs)
29
39
  open, checkout = details.values_at(:open, :checkout)
30
40
  constraints = open["constraints"]
@@ -76,6 +86,136 @@ module AP2MandateVerifier
76
86
  details
77
87
  end
78
88
 
89
+ # New profile only. IDs identify products; titles are descriptive text.
90
+ # Original arrays remain intact; this graph is solely a quantity proof.
91
+ def self.multi_constraints!(details, currency, expected_total)
92
+ open, checkout = details.values_at(:open, :checkout)
93
+ constraints = open["constraints"]
94
+ raise Rejected, :unsupported_constraint unless constraints.instance_of?(Array) && constraints.size == 2
95
+ required, allowed = constraints
96
+ exact!(required, %w[items type])
97
+ exact!(allowed, %w[allowed type])
98
+ raise Rejected, :unsupported_constraint unless required["type"] == "checkout.line_items" && allowed["type"] == "checkout.allowed_merchants"
99
+ requirements = bounded_array!(required["items"], MAX_REQUIREMENTS)
100
+ unique_ids!(requirements)
101
+ requirements.each do |requirement|
102
+ exact!(requirement, %w[acceptable_items id quantity])
103
+ quantity!(requirement["quantity"])
104
+ candidates = bounded_array!(requirement["acceptable_items"], MAX_CANDIDATES)
105
+ unique_ids!(candidates)
106
+ candidates.each do |candidate|
107
+ exact!(candidate, %w[id title])
108
+ text!(candidate["title"], 512)
109
+ end
110
+ end
111
+ merchant = one!(allowed["allowed"])
112
+ exact!(merchant, %w[id name])
113
+ text!(merchant["id"])
114
+ text!(merchant["name"], 512)
115
+ raise Rejected, :constraint_mismatch unless checkout["merchant"] == merchant
116
+ raise Rejected, :currency_mismatch unless checkout["currency"] == currency
117
+ amount = multi_checkout!(checkout)
118
+ raise Rejected, :amount_mismatch unless amount == expected_total
119
+ quantities_match!(requirements, checkout["line_items"])
120
+ end
121
+
122
+ # Also shared with the explicitly selected merchant signing profile.
123
+ def self.multi_checkout!(checkout)
124
+ exact!(checkout, %w[currency id line_items links merchant status totals])
125
+ text!(checkout["id"])
126
+ exact!(checkout["merchant"], %w[id name])
127
+ text!(checkout["merchant"]["id"])
128
+ text!(checkout["merchant"]["name"], 512)
129
+ text!(checkout["currency"], 3)
130
+ raise Rejected, :unsupported_scoped_profile unless CURRENCIES.include?(checkout["currency"]) &&
131
+ checkout["status"] == "ready_for_complete"
132
+ raise Rejected, :invalid_scoped_schema unless checkout["links"].instance_of?(Array)
133
+ raise Rejected, :unsupported_scoped_profile unless checkout["links"].empty?
134
+ lines = bounded_array!(checkout["line_items"], MAX_LINES)
135
+ unique_ids!(lines)
136
+ amount = 0
137
+ lines.each do |line|
138
+ exact!(line, %w[id item quantity totals])
139
+ quantity!(line["quantity"])
140
+ item = line["item"]
141
+ exact!(item, %w[id price title])
142
+ text!(item["id"])
143
+ text!(item["title"], 512)
144
+ amount!(item["price"])
145
+ line_amount = item["price"] * line["quantity"]
146
+ amount!(line_amount)
147
+ totals!(line["totals"], line_amount)
148
+ amount += line_amount
149
+ amount!(amount)
150
+ end
151
+ totals!(checkout["totals"], amount)
152
+ amount
153
+ end
154
+
155
+ def self.bounded_array!(value, limit)
156
+ raise Rejected, :invalid_scoped_schema unless value.instance_of?(Array)
157
+ raise Rejected, :constraint_limit_exceeded unless value.length.between?(1, limit)
158
+ value
159
+ end
160
+
161
+ def self.unique_ids!(values)
162
+ ids = values.map do |value|
163
+ raise Rejected, :invalid_scoped_schema unless value.instance_of?(Hash)
164
+ text!(value["id"])
165
+ value["id"]
166
+ end
167
+ raise Rejected, :invalid_scoped_schema unless ids.uniq.length == ids.length
168
+ end
169
+
170
+ # Integral max flow with reverse residual edges avoids greedy false rejects.
171
+ # At most 18 vertices, 64 candidate edges; capacities never expand per unit.
172
+ def self.quantities_match!(requirements, lines)
173
+ demand = requirements.sum { |requirement| requirement["quantity"] }
174
+ supply = lines.sum { |line| line["quantity"] }
175
+ raise Rejected, :constraint_mismatch unless demand == supply
176
+ sink = 1 + requirements.length + lines.length
177
+ residual = Array.new(sink + 1) { Array.new(sink + 1, 0) }
178
+ requirements.each_with_index do |requirement, i|
179
+ r = i + 1
180
+ residual[0][r] = requirement["quantity"]
181
+ ids = requirement["acceptable_items"].map { |candidate| candidate["id"] }
182
+ lines.each_with_index do |line, j|
183
+ residual[r][requirements.length + j + 1] = demand if ids.include?(line["item"]["id"])
184
+ end
185
+ end
186
+ lines.each_with_index { |line, j| residual[requirements.length + j + 1][sink] = line["quantity"] }
187
+ flow = 0
188
+ loop do
189
+ parents = Array.new(sink + 1)
190
+ parents[0] = 0
191
+ queue = [0]
192
+ until queue.empty? || parents[sink]
193
+ u = queue.shift
194
+ residual[u].each_with_index do |capacity, v|
195
+ next unless capacity > 0 && parents[v].nil?
196
+ parents[v] = u
197
+ queue << v
198
+ end
199
+ end
200
+ break unless parents[sink]
201
+ amount, v = demand, sink
202
+ until v == 0
203
+ u = parents[v]
204
+ amount = [amount, residual[u][v]].min
205
+ v = u
206
+ end
207
+ v = sink
208
+ until v == 0
209
+ u = parents[v]
210
+ residual[u][v] -= amount
211
+ residual[v][u] += amount
212
+ v = u
213
+ end
214
+ flow += amount
215
+ end
216
+ raise Rejected, :constraint_mismatch unless flow == demand
217
+ end
218
+
79
219
  def self.exact!(value, fields)
80
220
  raise Rejected, :invalid_scoped_schema unless value.instance_of?(Hash) && (fields - value.keys).empty?
81
221
  raise Rejected, :unsupported_scoped_profile unless (value.keys - fields).empty?
@@ -108,7 +248,8 @@ module AP2MandateVerifier
108
248
  raise Rejected, :unsupported_scoped_profile unless values.map { |entry| entry["type"] }.sort == %w[subtotal total]
109
249
  raise Rejected, :amount_mismatch unless values.all? { |entry| entry["amount"] == expected }
110
250
  end
111
- private_class_method :exact!, :one!, :text!, :quantity!, :amount!, :totals!
251
+ private_class_method :exact!, :one!, :text!, :quantity!, :amount!, :totals!,
252
+ :multi_constraints!, :bounded_array!, :unique_ids!, :quantities_match!
112
253
  private_constant :CORE_INSTANCE_OF
113
254
  end
114
255
  end
@@ -8,6 +8,22 @@ module AP2MandateVerifier
8
8
  PROFILE_REF = "ap2.checkout.single_merchant_sku"
9
9
  PROFILE_VERSION = "1"
10
10
  PROFILE_HASH = Digest::SHA256.hexdigest(PROFILE_BODY).freeze
11
+ MULTI_PROFILE_REF = "ap2.checkout.single_merchant_multi_item"
12
+ MULTI_PROFILE_VERSION = "1"
13
+ MULTI_PROFILE_BODY = '{"profile_ref":"ap2.checkout.single_merchant_multi_item","version":"1","ap2_source":"b4587ac1d055888a73b4b21750973cffba961793","algorithm":"ES256","key_format":"canonical-public-SPKI-P256-SHA256","root_type":"example+sd-jwt","terminal_type":"kb+sd-jwt","checkout_type":"JWT","disclosure_path_semantics":"root-walker-with-synthetic-disclosed-edges","disclosure_positions":["delegate_payload[0]","delegate_payload[0].disclosed.constraints[0].items[*].acceptable_items[*]","delegate_payload[0].disclosed.constraints[1].allowed[0]"],"constraints":["checkout.line_items","checkout.allowed_merchants"],"max_disclosures":66,"max_disclosure_segment_bytes":8192,"max_root_bytes":131072,"max_graph_nodes":2048,"max_graph_depth":24,"max_array_entries":16,"max_line_items":8,"max_requirements":8,"max_candidates_per_requirement":8,"quantity_matching":"integer-max-flow-product-id-exact-coverage","duplicate_line_ids":"reject","duplicate_requirement_ids":"reject","same_product_multiple_lines":"allow","amount_model":"integer-minor-unit-no-tax-shipping-discount"}'.freeze
14
+ MULTI_PROFILE_HASH = Digest::SHA256.hexdigest(MULTI_PROFILE_BODY).freeze
15
+
16
+ # Explicit Host policy registration. Signed token claims never select this.
17
+ def self.profile!(reference)
18
+ case reference
19
+ when PROFILE_REF
20
+ {ref: PROFILE_REF, version: PROFILE_VERSION, body: PROFILE_BODY, hash: PROFILE_HASH}.freeze
21
+ when MULTI_PROFILE_REF
22
+ {ref: MULTI_PROFILE_REF, version: MULTI_PROFILE_VERSION, body: MULTI_PROFILE_BODY, hash: MULTI_PROFILE_HASH}.freeze
23
+ else
24
+ reject!(:unsupported_trust_profile)
25
+ end
26
+ end
11
27
  ROLES = {"Issuer" => :trusted_issuer_public_key_pem,
12
28
  "Agent" => :expected_agent_public_key_pem,
13
29
  "Merchant" => :trusted_merchant_public_key_pem}.freeze
@@ -73,9 +89,10 @@ module AP2MandateVerifier
73
89
  selection.values_at("trust_snapshot_id", "policy_version", "trust_content_hash")
74
90
  live!(snapshot, verified_at, :inactive_trust_snapshot, :trust_snapshot_time_mismatch)
75
91
  _profile, wire = body!(trust["profile"], %w[profile_ref version], "definition_hash", 8_192)
76
- reject!(:unsupported_trust_profile) unless wire == PROFILE_BODY &&
77
- trust["profile"].values_at("profile_ref", "version", "definition_hash") == [PROFILE_REF, PROFILE_VERSION, PROFILE_HASH] &&
78
- selection.values_at("profile_ref", "profile_version", "profile_definition_hash") == [PROFILE_REF, PROFILE_VERSION, PROFILE_HASH]
92
+ profile = profile!(selection["profile_ref"])
93
+ reject!(:unsupported_trust_profile) unless wire == profile[:body] &&
94
+ trust["profile"].values_at("profile_ref", "version", "definition_hash") == profile.values_at(:ref, :version, :hash) &&
95
+ selection.values_at("profile_ref", "profile_version", "profile_definition_hash") == profile.values_at(:ref, :version, :hash)
79
96
  records = snapshot["records"]
80
97
  reject! unless records.instance_of?(Array) && records.length.between?(1, 16)
81
98
  records.each do |record|
@@ -83,7 +100,7 @@ module AP2MandateVerifier
83
100
  %w[identity tenant_id purpose key_ref profile_ref profile_version].each { |f| id!(record[f]) }
84
101
  reject! unless ROLES.key?(record["role"])
85
102
  window!(record)
86
- reject!(:unsupported_trust_profile) unless record.values_at("profile_ref", "profile_version", "algorithm") == [PROFILE_REF, PROFILE_VERSION, "ES256"]
103
+ reject!(:unsupported_trust_profile) unless record.values_at("profile_ref", "profile_version", "algorithm") == [profile[:ref], profile[:version], "ES256"]
87
104
  digest!(record["key_fingerprint"])
88
105
  begin
89
106
  RootSignature.public_jwk!(record["public_key_pem"])
@@ -98,9 +98,9 @@ module AP2MandateVerifier
98
98
  inputs = inputs.to_h do |key, value|
99
99
  [key, %i[verified_at expected_total_minor].include?(key) ? value : InputValidator.snapshot!(value)]
100
100
  end
101
- keys = TrustContext.keys!(trust_json: trust_json, selection_json: selection_json,
101
+ context = TrustContext.verified_context!(trust_json: trust_json, selection_json: selection_json,
102
102
  verified_at: inputs[:verified_at], expected_merchant_id: inputs[:expected_merchant_id])
103
- ScopedConstraints.check!(**inputs, **keys)
103
+ ScopedConstraints.check!(**inputs, **context.fetch(:keys), profile_ref: context.fetch(:references).fetch("profile_ref"))
104
104
  Result.new(status: :unverified, code: :scoped_constraints_verified_only)
105
105
  rescue InputValidator::Unavailable, RootSignature::Unavailable => error
106
106
  Result.new(status: :unavailable, code: error.code)
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.5.0
4
+ version: 0.6.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AP2 Mandate Verifier contributors
@@ -92,6 +92,7 @@ files:
92
92
  - docs/DIAGNOSTICS.ja.md
93
93
  - docs/DIAGNOSTICS.md
94
94
  - docs/MERCHANT_SIGNING.md
95
+ - docs/MULTI_ITEM_CHECKOUT.md
95
96
  - docs/SUPPORT_CONTRACT.md
96
97
  - lib/ap2_mandate_verifier.rb
97
98
  - lib/ap2_mandate_verifier/checkout_jwt.rb