ap2_mandate_verifier 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1e3f167538858b19e86097908f19d31235a3d6bf1f2478b13d0a3aa049ab527b
4
- data.tar.gz: 818e4c88efa929adcc209710c6d8e042a601820589a80bf20e7115db2700f00e
3
+ metadata.gz: 2455816539364170899a8ac40faa98c464835c72c0fd2db52847f013bf373da7
4
+ data.tar.gz: 183bfc7a0d3077cf81b741d6f55f92e48b3fb07a190fdcf5b829b03a6bdb0a0e
5
5
  SHA512:
6
- metadata.gz: fe38d275af6ada51fbc70b2dbbf8d7d1c822d49304f839e0b9ca2b575b24ccd2e123c3b04c58862b30e90b375afe28c0c34a4376841f69f07e6c8438fc0abd1a
7
- data.tar.gz: 9a0cf42696c264f27b62b674fe6ba1c10c5916434cc3b83b8582e15d78c103a9ea4dee976610f09bb3c84c8fe2a7b6b9c2152b17b637fd8359c0738d2f2b24b9
6
+ metadata.gz: 10212bb6d0720c0590920d3454a76207e6f23c31f7f9d84aeee9d11e3346fd23535b4b02a50d5442b0a6d1297e2132c3386895c3b2bff6a19fa0ccc5e2398e3e
7
+ data.tar.gz: aa86c67bb678296eeb094fe28c4e4c0df964fbaf1a974e963b543217db7d6c8e7b4457d9fbc6889e9338cf8cfcda9d5a932f6a92545df4ef4adb5c5f3621428e
data/README.md CHANGED
@@ -1,35 +1,44 @@
1
- # AP2 Mandate Verifier — 0.4.0
1
+ # AP2 Mandate Verifier — 0.6.0
2
2
 
3
3
  [日本語](README.ja.md)
4
4
 
5
+ Published stable is **0.6.0**, adding explicitly selected multi-item support. The published Gem matches the reviewed source and approved candidate; see [the publication record](docs/PROJECT_STATUS.md#060-publication).
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. Quantity shortages and extras reject. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md), [synthetic runnable lifecycle](examples/multi_item_checkout.rb), and [official Python SDK differences](docs/MULTI_ITEM_INTEROP.md) for shortage, empty-candidate and Receipt-reference behavior.
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.6.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 also demonstrates multiple products with differing quantities, later-line quantity rejection, and authentic Success/Error Receipts. 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.6.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.6.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 APIs were added in 0.5.0 and remain available in 0.6.0; the excerpt uses the default single-SKU profile.
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.6.0 retains the default `ap2.checkout.single_merchant_sku` v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and its documented disclosure shapes. It 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.6.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,8 +142,20 @@ 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
+ - [0.6.0 Release notes](docs/RELEASE_060.md), [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
 
140
149
  MIT. See [LICENSE](LICENSE).
150
+
151
+ ### Buyer Direct checkout (0.7.0 candidate, unpublished)
152
+
153
+ Trusted Surface backends can verify a merchant Checkout before approval, issue a
154
+ Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
155
+ `AP2MandateVerifier::Buyer` module verifies Direct Closed-only presentations at
156
+ the merchant and uses `CheckoutReceipt` with `profile_ref: Buyer::PROFILE_REF`.
157
+ One merchant, 1–8 lines, multiple products and quantities are supported end to end.
158
+ Existing Open→Agent Closed APIs and both profiles retain their contracts.
159
+ See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
160
+ [runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
161
+ is not purchasing authority or payment success. Candidate code is not in 0.6.0.
@@ -0,0 +1,180 @@
1
+ # Direct / Human Present Checkout — 0.7.0 candidate
2
+
3
+ This additive optional module implements Trusted Agent Provider approval of a
4
+ fixed merchant-signed order. It is NOT published. Adopted source is AP2 v0.2.0,
5
+ commit `b4587ac1d055888a73b4b21750973cffba961793`; no source upgrade is made.
6
+ The first example is one office supply purchase; **multiple products and lines
7
+ are required and supported throughout issuance, presentation, merchant verification
8
+ and Receipt verification**. See the [runnable integration](../examples/direct_checkout.rb).
9
+
10
+ ## Scope, roles and flow
11
+
12
+ 1. Shopping Agent obtains the merchant's original Checkout JWT.
13
+ 2. Trusted Surface backend calls `CheckoutJWT.verify` with an independently
14
+ registered merchant public key and expected merchant identity. It checks
15
+ current order state separately; this Checkout shape has no signed expiry.
16
+ 3. Application authenticates the purchasing employee, checks purchasing authority,
17
+ displays the verified products, quantities, currency and totals, and stores
18
+ the approved **original JWT** in a protected approval record. Bind the page,
19
+ authenticated session and approval transaction to that same record; protect
20
+ against CSRF, stale orders and concurrent replacement.
21
+ 4. Only that backend loads the record and calls `Buyer.issue_closed`. Its
22
+ `approved_checkout_jwt` must equal `checkout_jwt` byte for byte. This contract
23
+ detects substitution, but does not itself prove human identity or consent.
24
+ There is no `approved: true` parameter. Never let Agent input populate the
25
+ approval record, select the Provider signer, or call its signing endpoint.
26
+ 5. Agent receives the approved issuance wire and calls `Buyer.present_closed`.
27
+ It preserves the exact wire and both mandatory disclosures; no signing key
28
+ is needed. Issuance and presentation are separate responsibilities.
29
+ 6. Merchant calls `Buyer.verify` with independently enrolled Provider and merchant
30
+ keys, exact current Checkout JWT from its order database, identity and clock.
31
+ It rechecks order state and purchase policy, then atomically reserves the order
32
+ before applying any effect. Gem verification is not a purchase permission.
33
+ 7. Merchant explicitly supplies its application result to `CheckoutReceipt.sign`.
34
+ Buyer calls `CheckoutReceipt.verify` with the same original presented wire and
35
+ independently registered merchant key, issuer and explicit time window.
36
+ Demo Success means synthetic application acceptance, never payment success.
37
+
38
+ ## Public APIs and failures
39
+
40
+ `CheckoutJWT.verify(jwt:, trusted_public_key_pem:, expected_merchant_id:,
41
+ profile_ref: TrustContext::PROFILE_REF)` returns immutable `Verification` with
42
+ `verified?`, `jwt`, `checkout_hash`, deeply immutable `checkout`, `profile_ref`.
43
+ The default preserves the existing single-SKU shape; pass the existing multi-item
44
+ profile for multiple lines. Invalid input raises the existing redacted
45
+ `CheckoutJWT::Invalid`; it does not return partial authenticated claims.
46
+
47
+ `Buyer.issue_closed(checkout_jwt:, approved_checkout_jwt:,
48
+ trusted_merchant_public_key_pem:, expected_merchant_id:, issued_at:, expires_at:,
49
+ signer:, public_key_pem:)` returns immutable `Issued#closed_sd_jwt`. It rechecks
50
+ merchant signature and multi-item Checkout, approval-byte equality, integer epoch
51
+ and `0 < expires_at - issued_at <= 600` seconds. `signer.call` receives exact
52
+ ASCII JWS signing input and returns 64-byte JOSE ES256. The independently supplied
53
+ Provider public SPKI verifies the result before return. Remote signers own access
54
+ control, timeout and key lifecycle; Gem does not perform network I/O. Invalid
55
+ input, unsupported keys or signer failures raise redacted `Buyer::Invalid`
56
+ without a source cause. The same contract applies to `present_closed`.
57
+
58
+ `Buyer.present_closed(closed_sd_jwt:)` validates supported syntax, commitment
59
+ closure and embedded Checkout shape and returns a detached frozen original wire.
60
+ It does **not** authenticate signatures. Persist `Issued#closed_sd_jwt` unchanged
61
+ and restore by passing it to this API; never rebuild claims/disclosures. The
62
+ merchant must always call full `Buyer.verify`.
63
+
64
+ `Buyer.verify(closed_sd_jwt:, trusted_provider_public_key_pem:,
65
+ trusted_merchant_public_key_pem:, expected_checkout_jwt:, expected_merchant_id:,
66
+ verified_at:)` returns immutable `Buyer::Verification`. `verified? == true` means
67
+ all supported signature, commitment, schema subset, order-byte and time checks
68
+ passed. It exposes deeply immutable `checkout`, `checkout_hash`, `reference` and
69
+ `expires_at`. Failures return `code: :direct_checkout_verification_failed`, false
70
+ and no claims. Success code is `:direct_checkout_verified`. This new type does not
71
+ change existing Result/Evidence, their statuses or saved InputBuilder records.
72
+ Private Ruby constructors are API discipline, not a hostile-code sandbox.
73
+
74
+ For Direct wire use `profile_ref: Buyer::PROFILE_REF` with existing
75
+ `CheckoutReceipt.reference/sign/verify`. Other arguments, errors, result type,
76
+ Success/Error branch exclusivity, expected issuer and time-window checks stay
77
+ unchanged. Never infer application Success from a Gem verification result.
78
+
79
+ ## Profile and limits
80
+
81
+ Direct profile `ap2.checkout.direct.single_merchant` version 1 is selected by the
82
+ API/explicit Receipt argument, never by an untrusted profile claim. Merchant
83
+ Checkout validation reuses `ap2.checkout.single_merchant_multi_item` v1 **without
84
+ changing its contract**. There are 1–8 distinct line IDs, repeated product IDs
85
+ are allowed, quantities are integer 1–1,000,000, amounts/products/sums are integer
86
+ minor units 0–9,007,199,254,740,991. One merchant and currency (USD/EUR/JPY),
87
+ empty links, exactly subtotal/total per line and order, no unsupported fields,
88
+ taxes/shipping/discount engine. Every line and arithmetic result is checked.
89
+ All existing text and wire limits apply jointly; see [③](MULTI_ITEM_CHECKOUT.md).
90
+ Direct has no Open requirements/candidates or max-flow allocation to evaluate:
91
+ the entire exact order is approved. Changed rows/quantities require new approval.
92
+
93
+ ES256/P-256 only. SD-JWT root `typ: example+sd-jwt` (the fixed SDK root type),
94
+ exact payload `{delegate_payload: [{"...": digest}], _sd_alg: "sha-256"}`.
95
+ A 2-element disclosure reveals one Closed object (`vct`, `checkout_hash`, `iat`,
96
+ `exp`, `_sd`), and a 3-element disclosure reveals its `checkout_jwt`. Both are
97
+ required, parent then leaf. Issuance generates independent cryptographic 128-bit
98
+ salts; input salt strings have 22–128 base64url characters. No decoys, omitted,
99
+ extra, duplicated or unknown commitments/claims are accepted. Presentation has
100
+ exact form `<root>~<closed disclosure>~<checkout disclosure>~`. No KB-JWT,
101
+ `cnf`, Agent signature, aud or nonce is accepted here. These are Open→Closed
102
+ binding concerns, not universal Direct requirements. Trusted Provider enrollment
103
+ is external; keys embedded in received data never select trust.
104
+
105
+ In the existing Open→Closed flow, the Provider-signed Open content endorses the
106
+ Agent's public key through `cnf.jwk`; that key verifies the terminal Agent
107
+ signature and its binding to the preceding original SD-JWT, expected audience
108
+ and nonce. Direct instead trusts the Provider signature over the already closed
109
+ order itself and needs no Agent key endorsement. Open issuance, choosing fewer
110
+ disclosures and Agent signing therefore remain separate future APIs.
111
+
112
+ Maximum entire wire 32,768 bytes; Checkout JWT 16,384; root payload 2,048;
113
+ decoded disclosure 24,576; JSON depth 24. Existing strict JSON/canonical base64url
114
+ and finite number checks apply. Limits combine; counts alone do not guarantee
115
+ that a wire fits. `iat <= verified_at < exp`, integer epochs in the existing
116
+ safe epoch range, maximum lifetime 600 seconds, no implicit clock/skew. Applications
117
+ own trustworthy clocks, order validity and shorter approval policy.
118
+
119
+ ## Replay, durable state and receipts
120
+
121
+ Mandates are bearer authorizations for the exact order. Neither hashes nor nonce
122
+ comparison establish single use. Persist approval ID → original Checkout → issued
123
+ wire atomically, enforce unique approval issuance, and on merchant side enforce
124
+ UNIQUE(merchant, checkout ID) with current order/version and atomic state transition.
125
+ Return the saved outcome/Receipt for duplicates; do not repeat the effect. Record
126
+ `processing/unknown` before external effects and reconcile uncertain commits via
127
+ application order/payment status lookup, keeping them on hold instead of retrying.
128
+ The executable example demonstrates serialized duplicate handling and unknown
129
+ hold in memory; it is not durable across process restarts and is not production
130
+ DB integration. Real applications need transactional persistence and authorization.
131
+
132
+ Receipt reference is base64url(SHA256(**entire original presented SD-JWT**)),
133
+ including both disclosure bytes, order and terminal `~`. Never hash reserialized
134
+ claims, only compact JWT, an issuance with a different disclosure order or a
135
+ re-issued token with fresh salts. Reference syntax checks do not verify Provider
136
+ authority. Verify Mandate first and produce Receipt only for explicit application
137
+ outcomes. Receipt authenticity alone proves neither purchase nor payment.
138
+
139
+ ## Compatibility, interoperability and acceptance
140
+
141
+ Existing two profiles, InputBuilder save/restore, Result/Evidence, old API defaults
142
+ and legacy Receipt terminal syntax are unchanged. Direct is a new independent
143
+ entry; existing `verify_checkout` continues to handle its prior Open→Agent Closed
144
+ contract only. Passing Direct wire to old Receipt/default profile rejects.
145
+ No dependency or Ruby support change. Compatible feature version is 0.7.0.
146
+
147
+ `test/buyer_interop.py` uses the fixed official `sd_jwt.create/verify`, unmodified
148
+ Closed Schema, JWT helpers and independent SHA256/commitment computation.
149
+ Ruby issuance is verified by Python; Python issuance by Ruby, including eight
150
+ lines, multiple products, differing quantities, receipts in both directions and
151
+ wrong-key/substitution/expiry/reference negatives. The SDK issuance disclosure
152
+ order may differ; the test selects parent-before-leaf using original disclosure
153
+ strings, without reserializing claims or changing signatures, then hashes that
154
+ actual presentation. This explicit restricted order is a local profile rule.
155
+ The SDK high-level Checkout chain helper requires Open+Closed; it is not a Direct
156
+ validator. Our Direct implementation uses its independent root SD-JWT primitives.
157
+
158
+ Receipt normative `sd_hash` includes disclosures and terminal `~`; SDK
159
+ `MandateClient.get_closed_mandate_jwt` extracts compact-only, so its recommended
160
+ reference differs. We follow normative original SD-JWT hashing. Checkout Receipt
161
+ uses Schema `status: Success/Error`, not generic prose `result: success/error`.
162
+ Existing max-flow shortage/empty-candidate SDK disagreements remain documented in
163
+ [MULTI_ITEM_INTEROP](MULTI_ITEM_INTEROP.md); Direct has no Open allocation, and
164
+ compatibility regression continues to test those profiles. No checks are omitted
165
+ to force agreement with SDK.
166
+
167
+ Acceptance includes approval-to-Receipt example, 3/8-line flows and both outcomes,
168
+ repeated products, reordered separately signed orders, rejection of 0/9 lines,
169
+ duplicate line IDs, invalid quantities/prices/totals/currency/links, wrong keys,
170
+ expiry/future time, missing disclosures, malformed signed combinations and unknown
171
+ formats. Existing source and ordinary-install regressions run on MRI 3.4.12/4.0.9.
172
+ Latest-HEAD independent review and branch protections are required before merge.
173
+
174
+ Open issuance, Agent Closed generation/selective disclosure/presentation, User
175
+ Credentials, multiple merchants, split orders and continuous autonomous buying
176
+ are follow-up candidates. Agent-to-Agent delegation is outside current AP2 scope,
177
+ not declared permanently forbidden. Real Issuer trust, actual demand, generic AP2
178
+ support and production safety are not established by synthetic test success.
179
+ No Gem/tag/Release publication, deployment, real payments or credentials are
180
+ performed by this task.
@@ -1,4 +1,24 @@
1
- # Merchant Checkout signing (unpublished candidate)
1
+ # Merchant Checkout signing and Receipt
2
+
3
+ ## Explicit multi-item selection — published 0.6.0
4
+
5
+ The APIs introduced in 0.5.0 retain their default single-SKU behavior. Published 0.6.0
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. The [0.6.0 publication record](PROJECT_STATUS.md#060-publication) identifies
19
+ the reviewed source, distribution and validation separately.
20
+
21
+ The original single-SKU signing/Receipt APIs were introduced in [0.5.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.5.0); the explicit multi-item selection above is available in 0.6.0. [Complete runnable single-SKU example](../examples/merchant_signing.rb). The example is repository content, not part of the installed Gem.
2
22
 
3
23
  ## Scope and responsibility
4
24
 
@@ -11,8 +31,10 @@ merchant enrollment, persist an order, consume a nonce or make a payment.
11
31
  The adopted AP2 source remains
12
32
  [`b4587ac1d055888a73b4b21750973cffba961793`](https://github.com/google-agentic-commerce/AP2/tree/b4587ac1d055888a73b4b21750973cffba961793).
13
33
  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.
34
+ all UCP shapes. Under the default profile, multiple items are rejected. The
35
+ explicit multi-item profile supports the documented bounded subset. Unsupported
36
+ fields, nonempty links and unsupported currencies are rejected in both profiles.
37
+ Amounts are integer minor units; totals must agree.
16
38
 
17
39
  ## Minimal executable example
18
40
 
@@ -40,7 +62,9 @@ puts signed.checkout_hash.length # 43
40
62
  `signed.jwt` is the frozen original compact JWT to transmit and retain. Supply
41
63
  that exact String as `host_checkout_jws` to InputBuilder and Verifier; supply
42
64
  `signed.checkout_hash` when a test or external Agent binds a Closed Mandate.
43
- The Gem does not issue a product Mandate API. Re-encoding claims or signing again
65
+ These 0.5/0.6 APIs do not issue a product Mandate. The unpublished 0.7.0
66
+ [Direct buyer module](BUYER_DIRECT_CHECKOUT.md) adds a separate issuance flow.
67
+ Re-encoding claims or signing again
44
68
  creates different original wire, even when the order is the same.
45
69
 
46
70
  `signer.call(signing_input)` receives the frozen ASCII `header.payload` and returns
@@ -0,0 +1,119 @@
1
+ # Multiple-item Checkout profile — published 0.6.0
2
+
3
+ This is the contract for the additive, explicitly selected
4
+ `ap2.checkout.single_merchant_multi_item` version `1`, available in published
5
+ 0.6.0. The `ap2.checkout.single_merchant_sku` v1 default remains unchanged.
6
+ Tests, review, distribution identity and publication are recorded separately in
7
+ [project status](PROJECT_STATUS.md#060-publication); publication does not authorize
8
+ a Host purchase or payment.
9
+
10
+ ## Selection and lifecycle
11
+
12
+ Pass `profile_ref: "ap2.checkout.single_merchant_multi_item"` to:
13
+
14
+ - `InputBuilder.trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:, profile_ref:)`;
15
+ - `CheckoutJWT.sign(checkout:, signer:, public_key_pem:, profile_ref:)`;
16
+ - `CheckoutReceipt.reference`, `.sign` and `.verify`, alongside their existing arguments.
17
+
18
+ The complete `InputBuilder.verify` / seven-input `verify_checkout` pipeline
19
+ selects the profile from authenticated Host trust, never a token's self-claim.
20
+ Other arguments, Result status/code, supplemental diagnostic meaning, immutable
21
+ Evidence v2 and responsibility boundaries retain their existing meanings.
22
+ Lower-level purchase/constraint APIs accept an explicit `profile_ref:`; omitted
23
+ selection retains their old default.
24
+
25
+ For a complete synthetic preparation → saved challenge → restore → current-state
26
+ verification → Success/Error Receipt example, see
27
+ [`examples/multi_item_checkout.rb`](../examples/multi_item_checkout.rb).
28
+ Its test-only issuer/Agent construction is not a product Mandate issuance API.
29
+ The expected successful verifier result remains
30
+ `verified_research/scoped_research_verified`; an authentic Error Receipt has
31
+ `verified? == true`, `purchase_succeeded? == false`.
32
+
33
+ Persist the original challenge String and all signed Strings. Restore trust and
34
+ challenge bytes without reserializing them. Migration creates a new authenticated
35
+ profile selection and a new challenge before presentation; it never relabels or
36
+ repairs an old challenge. An old saved envelope remains an old-profile envelope.
37
+ Current profile, order, trust and signed-byte differences must remain detectable.
38
+
39
+ ## Product, requirement and line identity
40
+
41
+ There are three independent identities: requirement `id`, checkout line `id`,
42
+ and product `item.id` / candidate `id`. Requirement IDs must be unique within
43
+ requirements; line IDs must be unique within checkout lines. They need not match
44
+ each other. Candidate product IDs must be unique within each requirement.
45
+ Different requirements may contain overlapping candidate IDs.
46
+
47
+ Repeated product IDs on different checkout lines are supported. Quantity
48
+ allocation connects lines to requirements by product ID only for evaluation; it never deletes,
49
+ deduplicates, sorts or replaces signed lines. Titles remain bounded strings,
50
+ but product matching uses IDs. Price and totals are checked for every line.
51
+
52
+ An integer maximum-flow allocation must consume both all required quantities
53
+ and all ordered quantities. A unit cannot satisfy two requirements. For example,
54
+ requirements `{A or B: 1}` and `{A: 1}` accept `A: 1, B: 1`; a greedy allocation
55
+ which consumes A for the first requirement is insufficient. Missing units,
56
+ extra units and extra products reject. One requirement's quantity may be
57
+ distributed across its revealed candidate IDs.
58
+
59
+ Ordering does not change quantity satisfiability. A separately and correctly
60
+ signed checkout in another order has different original bytes and must be bound
61
+ by its own Mandate and Host challenge. Reordering an existing signed JWT or
62
+ reusing the previous reference is a signature/binding failure.
63
+
64
+ ## Closed subset and limits
65
+
66
+ These are Gem profile restrictions, not general AP2 requirements.
67
+
68
+ | Input | New v1 limit / supported form |
69
+ | --- | --- |
70
+ | Merchant / Checkout / currency | One each; USD, EUR or JPY |
71
+ | Checkout lines | 1–8; distinct line IDs |
72
+ | Requirements | 1–8; distinct requirement IDs |
73
+ | Candidates per requirement | 1–8; distinct product IDs within the requirement |
74
+ | Quantity per line / requirement | Integer 1–1,000,000 |
75
+ | Unit price / multiplication / summed total | Integer minor units, 0–9,007,199,254,740,991 |
76
+ | Line and Checkout totals | Exactly subtotal and total, each equal to its checked amount |
77
+ | Constraints | Ordered `checkout.line_items`, then `checkout.allowed_merchants`; no unknown constraints |
78
+ | Links / taxes / shipping / discount | Empty links; no tax, shipping or discount engine or extra total types |
79
+ | Root disclosures | Every candidate, the Open payload and allowed merchant; at most 66 |
80
+ | Disclosure segment / Root input | 8,192 / 131,072 bytes |
81
+ | Commitment walk | At most 2,048 visits; container depth 24; array length 16 |
82
+ | Checkout JWT / terminal JWS | Existing 16,384 / 32,768 byte limits |
83
+
84
+ All candidate positions must be array commitments under
85
+ `delegate_payload[0].disclosed.constraints[0].items[i].acceptable_items[j]`.
86
+ The Open payload and sole allowed merchant retain their existing commitment
87
+ positions. Missing, reused or unused disclosures and unsupported positions fail
88
+ closed. Bounds apply together: an input below one count cap can still exceed
89
+ the segment, wire or traversal cap. Oversized values are rejected, never truncated.
90
+ No unmeasured worst-case CPU, memory, concurrency or numeric SLA is promised.
91
+
92
+ ## Normative source and SDK differences
93
+
94
+ The AP2 source stays pinned to
95
+ `b4587ac1d055888a73b4b21750973cffba961793`. The Line Items normative text defines
96
+ maximum flow and requires both sides to be fully satisfied. Schema descriptions
97
+ and Python helper behavior must be compared independently; see
98
+ [the interoperability record](MULTI_ITEM_INTEROP.md) for measured cases and scope.
99
+ No generic AP2/full-Schema or real-Issuer conformance claim follows from synthetic
100
+ tests. Unrelated latest-spec changes are not adopted by this profile.
101
+
102
+ Receipt still uses Checkout-specific `status: Success/Error`. Its reference is
103
+ the original final closed SD-JWT `<terminal_jws>~`; no per-line receipt or
104
+ compact-only alternate hash is introduced. The existing
105
+ [Receipt specification/SDK differences](MERCHANT_SIGNING.md) remain applicable.
106
+
107
+ ## Host responsibilities
108
+
109
+ The Host independently supplies authenticated, current trust/keys/revocation,
110
+ clock, expected order/currency/total and saved challenge state. A total extracted
111
+ from the received checkout is not an independent expected order. It rechecks
112
+ state before acting, atomically consumes the nonce with order CAS, handles
113
+ uncertain outcomes and makes the final purchase/payment decision.
114
+
115
+ Verification success is checked Evidence, not Host ALLOW or payment success.
116
+ Receipt authenticity is separate from its explicit business outcome. Multiple
117
+ merchants, splitting one Open Mandate across Checkouts, Payment Mandates/Receipts,
118
+ product issuance/presentation, real payments and production operation are outside
119
+ this task. Formal MRI 3.4.12 / 4.0.9 and all five runtime dependency pins are unchanged.
@@ -1,8 +1,39 @@
1
- # Fixed-profile AP2 verification — published 0.4.0 / historical releases
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.
4
-
5
- Published 0.4.0 adds supplemental safe diagnostics; see [API and troubleshooting](DIAGNOSTICS.md). Existing verdict/Evidence contracts remain unchanged.
1
+ # Fixed-profile AP2 verification — published 0.6.0 / history
2
+
3
+ ## Current source: explicit multi-item profile
4
+
5
+ Published **0.6.0** 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 archive identities are recorded separately in the
18
+ [0.6.0 publication record](PROJECT_STATUS.md#060-publication) and
19
+ [validation record](MULTI_ITEM_VALIDATION.md); pending work is not a PASS.
20
+
21
+ Registered 2026-10-31 **11:50:18.664 UTC**, official metadata/distribution
22
+ comparison completed **11:51:54 UTC**: 56,832 bytes, SHA256
23
+ `ff669a62717f91b2295b3cea1b68c6c4143c490d98df071fd322ad4b0007195d`,
24
+ source `baee59a603d08123adc0af50e57c8710ea62f4f9`. All 22 payloads match
25
+ the approved source and candidate, with unchanged five runtime pins and Ruby
26
+ requirement. Platform `ruby`, non-prerelease, not yanked at comparison.
27
+ Source association is established by candidate/distribution bytes, not RubyGems
28
+ source attestation. [Publication receipt](evidence/0.6.0_publication.json).
29
+ Packaged documents retain their preparation snapshot; these repository-only
30
+ updates do not rebuild, repush or replace the published Gem.
31
+
32
+ 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.
33
+
34
+ [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.
35
+
36
+ Historical published 0.4.0 adds supplemental safe diagnostics; see [API and troubleshooting](DIAGNOSTICS.md). Existing verdict/Evidence contracts remain unchanged.
6
37
 
7
38
  [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
39
 
@@ -66,7 +97,7 @@ Gem-owned signature/original-wire/closure, delegation, binding, supplied-trust s
66
97
  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
98
  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
99
 
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.
100
+ 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
101
  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
102
 
72
103
  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 +112,7 @@ The API/limit specification below preserves the existing contract. All pre2/pre3
81
112
 
82
113
  ## Supported proposition and environment
83
114
 
84
- The sole registered profile is `ap2.checkout.single_merchant_sku` version1,
115
+ The historical sole registered profile is `ap2.checkout.single_merchant_sku` version1,
85
116
  with the exact `TrustContext::PROFILE_BODY`/hash. Official AP2 source is fixed at
86
117
  b4587ac1d055888a73b4b21750973cffba961793; its subset-source reference027ed4734...
87
118
  is historical profile provenance, not runtime code attestation. Root typ is
@@ -362,3 +393,12 @@ The summary must explicitly identify the completed observation; a missing,
362
393
  failed or mismatched report is not success. No local path is a public evidence
363
394
  URL. Raw local environment logs are not published by this package.
364
395
 
396
+
397
+ ## Direct buyer module — unpublished 0.7.0 candidate
398
+
399
+ Additive `CheckoutJWT.verify` and `Buyer.issue_closed/present_closed/verify`
400
+ implement Trusted Agent Provider / Human Present exact-order approval. Direct
401
+ Receipt requires explicit `Buyer::PROFILE_REF`; existing defaults and 2profile
402
+ contracts are unchanged. Supports the existing 1–8-line multi-item Checkout subset
403
+ end to end. [Full input, failure, trust and replay contract](BUYER_DIRECT_CHECKOUT.md).
404
+ No general AP2, production authorization, payment or real-Issuer claim is added.