ap2_mandate_verifier 0.6.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: dbeaa8817a128ad64b2307ae68a86cb2c36f40e710dc459f28354e24b3b251f9
4
- data.tar.gz: 70d40f6293a88043e0f29f10b00e337418ae6819f91cffcb55db8f6c68f21785
3
+ metadata.gz: 2455816539364170899a8ac40faa98c464835c72c0fd2db52847f013bf373da7
4
+ data.tar.gz: 183bfc7a0d3077cf81b741d6f55f92e48b3fb07a190fdcf5b829b03a6bdb0a0e
5
5
  SHA512:
6
- metadata.gz: bd6ba8a1c4be5e8b81ff589624ab17d3e1d3861d49cb8aad457abf96708c2446b996381dc0c948f868538c6b80ae9d2ef45d1c693e2e1fa1cf6874df085faeb5
7
- data.tar.gz: 7652d380a3ab2024016f0442672b384f6f8e8eecbec416318b1c9224cc8a954c3be1600e5eb1125f1f9eaa5b172609b41e6c0a3074564c0932bc897ae1f8d2ec
6
+ metadata.gz: 10212bb6d0720c0590920d3454a76207e6f23c31f7f9d84aeee9d11e3346fd23535b4b02a50d5442b0a6d1297e2132c3386895c3b2bff6a19fa0ccc5e2398e3e
7
+ data.tar.gz: aa86c67bb678296eeb094fe28c4e4c0df964fbaf1a974e963b543217db7d6c8e7b4457d9fbc6889e9338cf8cfcda9d5a932f6a92545df4ef4adb5c5f3621428e
data/README.md CHANGED
@@ -1,14 +1,14 @@
1
- # AP2 Mandate Verifier — 0.6.0 preparation
1
+ # AP2 Mandate Verifier — 0.6.0
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).
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
6
 
7
7
  ## Multiple items and quantities
8
8
 
9
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
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).
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
12
 
13
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.**
14
14
 
@@ -16,27 +16,27 @@ Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile.
16
16
 
17
17
  ## Try the local demo
18
18
 
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.
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.
20
20
 
21
21
  ## Install
22
22
 
23
23
  Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
24
24
 
25
25
  ```sh
26
- gem install ap2_mandate_verifier --version 0.5.0
26
+ gem install ap2_mandate_verifier --version 0.6.0
27
27
  ```
28
28
 
29
29
  Or add to your Gemfile:
30
30
 
31
31
  ```ruby
32
- gem "ap2_mandate_verifier", "= 0.5.0"
32
+ gem "ap2_mandate_verifier", "= 0.6.0"
33
33
  ```
34
34
 
35
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).
36
36
 
37
37
  ## Merchant signing and Receipt
38
38
 
39
- Create a signed checkout, then sign the application's explicit outcome. These additive APIs are included in published 0.5.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
40
  Here `checkout` is the application order Hash, `key` its P-256 signing key,
41
41
  `received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
42
42
 
@@ -125,13 +125,13 @@ Exceptions, process failure and missing results also never authorize an operatio
125
125
 
126
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.
127
127
 
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.
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.
129
129
 
130
130
  ### Which API should I use?
131
131
 
132
132
  | Entry | Role |
133
133
  | --- | --- |
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. |
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. |
135
135
  | `verify_checkout(**inputs)` | Direct complete verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
136
136
  | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
137
137
  | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
@@ -142,8 +142,20 @@ Malformed assembly arguments, including missing keywords, to `InputBuilder.verif
142
142
 
143
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).
144
144
  - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
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.
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.
146
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.
147
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.
148
148
 
149
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,8 +1,8 @@
1
1
  # Merchant Checkout signing and Receipt
2
2
 
3
- ## Explicit multi-item selection — 0.6.0 preparation
3
+ ## Explicit multi-item selection — published 0.6.0
4
4
 
5
- Published 0.5.0 APIs below retain their default single-SKU behavior. This checkout
5
+ The APIs introduced in 0.5.0 retain their default single-SKU behavior. Published 0.6.0
6
6
  adds optional `profile_ref: "ap2.checkout.single_merchant_multi_item"` to
7
7
  `CheckoutJWT.sign` and `CheckoutReceipt.reference/sign/verify`. Pass it consistently
8
8
  when working with a multi-item Checkout. The new profile validates every line,
@@ -15,9 +15,10 @@ Receipt still references the complete original `<terminal_jws>~`, without
15
15
  per-line hashes or a compact-only alternate. Profile selection validates the
16
16
  supported embedded Checkout shape; reference computation alone does not verify
17
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.
18
+ unchanged. The [0.6.0 publication record](PROJECT_STATUS.md#060-publication) identifies
19
+ the reviewed source, distribution and validation separately.
19
20
 
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.
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.
21
22
 
22
23
  ## Scope and responsibility
23
24
 
@@ -61,7 +62,9 @@ puts signed.checkout_hash.length # 43
61
62
  `signed.jwt` is the frozen original compact JWT to transmit and retain. Supply
62
63
  that exact String as `host_checkout_jws` to InputBuilder and Verifier; supply
63
64
  `signed.checkout_hash` when a test or external Agent binds a Closed Mandate.
64
- 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
65
68
  creates different original wire, even when the order is the same.
66
69
 
67
70
  `signer.call(signing_input)` receives the frozen ASCII `header.payload` and returns
@@ -1,10 +1,11 @@
1
- # Multiple-item Checkout profile — 0.6.0 preparation
1
+ # Multiple-item Checkout profile — published 0.6.0
2
2
 
3
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.
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.
8
9
 
9
10
  ## Selection and lifecycle
10
11
 
@@ -1,8 +1,8 @@
1
- # Fixed-profile AP2 verification — 0.6.0 preparation / published history
1
+ # Fixed-profile AP2 verification — published 0.6.0 / history
2
2
 
3
3
  ## Current source: explicit multi-item profile
4
4
 
5
- This checkout prepares **0.6.0**, not yet published. It adds the explicitly
5
+ Published **0.6.0** adds the explicitly
6
6
  selected `ap2.checkout.single_merchant_multi_item` v1 across input preparation,
7
7
  restoration/current-state verification, Checkout signing and Checkout Receipts.
8
8
  The [multi-item contract](MULTI_ITEM_CHECKOUT.md) defines the accepted shapes,
@@ -14,9 +14,20 @@ their original releases; they do not exclude this separately selected addition.
14
14
 
15
15
  Formal MRI 3.4.12 and 4.0.9, all five dependency pins, Result/status/code,
16
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.
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.
20
31
 
21
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.
22
33
 
@@ -382,3 +393,12 @@ The summary must explicitly identify the completed observation; a missing,
382
393
  failed or mismatched report is not success. No local path is a public evidence
383
394
  URL. Raw local environment logs are not published by this package.
384
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.
@@ -0,0 +1,153 @@
1
+ # frozen_string_literal: true
2
+
3
+ module AP2MandateVerifier
4
+ # Optional Direct/Human Present profile; never an Open -> Closed chain.
5
+ module Buyer
6
+ PROFILE_REF = "ap2.checkout.direct.single_merchant".freeze
7
+ CHECKOUT_PROFILE = ScopedConstraints::MULTI_PROFILE_REF
8
+ MAX_LIFETIME = 600
9
+ class Invalid < ArgumentError
10
+ def initialize = super("invalid direct checkout information")
11
+ end
12
+ class Issued
13
+ attr_reader :closed_sd_jwt
14
+ def initialize(wire)
15
+ @closed_sd_jwt = wire.freeze
16
+ freeze
17
+ end
18
+ private_class_method :new
19
+ end
20
+ class Verification
21
+ attr_reader :code, :checkout, :checkout_hash, :reference, :expires_at
22
+ def initialize(code, parsed = nil)
23
+ @code = code
24
+ if parsed
25
+ @checkout = parsed.fetch(:checkout)
26
+ @checkout_hash = parsed.fetch(:closed).fetch("checkout_hash").freeze
27
+ @expires_at = parsed.fetch(:closed).fetch("exp")
28
+ @reference = Buyer.send(:hash, parsed.fetch(:wire)).freeze
29
+ end
30
+ freeze
31
+ end
32
+ def verified? = code == :direct_checkout_verified
33
+ private_class_method :new
34
+ end
35
+
36
+ # Only the authenticated approval backend calls this method. The approved
37
+ # wire comes from its protected approval record, never an Agent boolean.
38
+ # This is an equality contract, not authentication of the approver.
39
+ def self.issue_closed(checkout_jwt:, approved_checkout_jwt:, trusted_merchant_public_key_pem:,
40
+ expected_merchant_id:, issued_at:, expires_at:, signer:, public_key_pem:)
41
+ wire = InputValidator.snapshot!(checkout_jwt, max_bytes: 16_384)
42
+ approved = InputValidator.snapshot!(approved_checkout_jwt, max_bytes: 16_384)
43
+ raise Invalid unless wire == approved
44
+ epoch!(issued_at); epoch!(expires_at)
45
+ raise Invalid unless expires_at > issued_at && expires_at - issued_at <= MAX_LIFETIME
46
+ checked = CheckoutJWT.verify(jwt: wire, trusted_public_key_pem: trusted_merchant_public_key_pem,
47
+ expected_merchant_id: expected_merchant_id, profile_ref: CHECKOUT_PROFILE)
48
+ require "securerandom"
49
+ disclosure = encode([encode(SecureRandom.random_bytes(16)), "checkout_jwt", checked.jwt])
50
+ closed = {"vct" => "mandate.checkout.1", "checkout_hash" => checked.checkout_hash,
51
+ "iat" => issued_at, "exp" => expires_at, "_sd" => [hash(disclosure)]}
52
+ content = encode([encode(SecureRandom.random_bytes(16)), closed])
53
+ payload = {"delegate_payload" => [{"..." => hash(content)}], "_sd_alg" => "sha-256"}
54
+ jwt = MerchantSignature.sign!(payload, signer, public_key_pem, typ: "example+sd-jwt")
55
+ result = "#{jwt}~#{content}~#{disclosure}~"
56
+ parse!(result)
57
+ Issued.send(:new, result)
58
+ rescue StandardError, LoadError
59
+ raise Invalid.new, cause: nil
60
+ end
61
+
62
+ # All two disclosures are required for this profile. No Agent signature,
63
+ # aud, nonce, or KB-JWT is added. Restoration preserves the exact bytes.
64
+ def self.present_closed(closed_sd_jwt:)
65
+ parse!(closed_sd_jwt).fetch(:wire)
66
+ rescue StandardError, LoadError
67
+ raise Invalid.new, cause: nil
68
+ end
69
+
70
+ # Merchant supplies independently registered Provider/Merchant keys and
71
+ # the exact current order from its own database. Success is not Host ALLOW.
72
+ def self.verify(closed_sd_jwt:, trusted_provider_public_key_pem:, trusted_merchant_public_key_pem:,
73
+ expected_checkout_jwt:, expected_merchant_id:, verified_at:)
74
+ epoch!(verified_at)
75
+ parsed = parse!(closed_sd_jwt)
76
+ RootSignature.verified_payload!(parsed.fetch(:jwt), trusted_provider_public_key_pem)
77
+ closed = parsed.fetch(:closed)
78
+ raise Invalid unless closed.fetch("iat") <= verified_at && verified_at < closed.fetch("exp")
79
+ expected = InputValidator.snapshot!(expected_checkout_jwt, max_bytes: 16_384)
80
+ raise Invalid unless closed.fetch("checkout_jwt") == expected
81
+ checked = CheckoutJWT.verify(jwt: expected, trusted_public_key_pem: trusted_merchant_public_key_pem,
82
+ expected_merchant_id: expected_merchant_id, profile_ref: CHECKOUT_PROFILE)
83
+ Verification.send(:new, :direct_checkout_verified, parsed.merge(checkout: checked.checkout))
84
+ rescue StandardError, LoadError
85
+ Verification.send(:new, :direct_checkout_verification_failed)
86
+ end
87
+
88
+ # Exact bounded grammar, not a general selective-disclosure resolver.
89
+ # Every commitment is consumed exactly once, without decoys/hidden fields.
90
+ def self.parse!(source)
91
+ RootSignature.send(:dependencies!)
92
+ wire = InputValidator.snapshot!(source, max_bytes: 32_768)
93
+ raise Invalid unless wire.ascii_only?
94
+ jwt, content, disclosure, tail, *extra = wire.split("~", -1)
95
+ raise Invalid unless tail == "" && extra.empty?
96
+ parts = jwt.split(".", -1)
97
+ raise Invalid unless parts.size == 3
98
+ header = InputValidator.parse!(RootSignature.send(:decode!, parts[0], 2_048))
99
+ CheckoutReceipt.send(:header!, header, "example+sd-jwt")
100
+ raise Invalid unless RootSignature.send(:decode!, parts[2], 64).bytesize == 64
101
+ payload = InputValidator.parse!(RootSignature.send(:decode!, parts[1], 2_048))
102
+ exact!(payload, %w[_sd_alg delegate_payload])
103
+ raise Invalid unless payload["_sd_alg"] == "sha-256"
104
+ pointer = ScopedConstraints.send(:one!, payload["delegate_payload"])
105
+ exact!(pointer, ["..."])
106
+ raise Invalid unless pointer["..."] == hash(content)
107
+ revealed = decode_disclosure!(content, 2)
108
+ closed = revealed[1]
109
+ exact!(closed, %w[_sd checkout_hash exp iat vct])
110
+ raise Invalid unless closed["vct"] == "mandate.checkout.1" && closed["_sd"] == [hash(disclosure)]
111
+ epoch!(closed["iat"]); epoch!(closed["exp"])
112
+ raise Invalid unless closed["exp"] > closed["iat"] && closed["exp"] - closed["iat"] <= MAX_LIFETIME
113
+ leaf = decode_disclosure!(disclosure, 3)
114
+ raise Invalid unless leaf[1] == "checkout_jwt"
115
+ checkout = InputValidator.snapshot!(leaf[2], max_bytes: 16_384)
116
+ raise Invalid unless closed["checkout_hash"] == hash(checkout)
117
+ # Parse supported merchant syntax too, without claiming its authenticity.
118
+ checkout_parts = checkout.split(".", -1)
119
+ raise Invalid unless checkout_parts.size == 3
120
+ checkout_header = InputValidator.parse!(RootSignature.send(:decode!, checkout_parts[0], 2_048))
121
+ CheckoutReceipt.send(:header!, checkout_header, "JWT")
122
+ raise Invalid unless RootSignature.send(:decode!, checkout_parts[2], 64).bytesize == 64
123
+ claims = InputValidator.parse!(RootSignature.send(:decode!, checkout_parts[1], 12_000))
124
+ CheckoutJWT.send(:validate!, claims, profile_ref: CHECKOUT_PROFILE)
125
+ {wire: wire, jwt: jwt, closed: closed.merge("checkout_jwt" => checkout)}
126
+ end
127
+ def self.decode_disclosure!(wire, size)
128
+ value = InputValidator.parse!(RootSignature.send(:decode!, wire, 24_576))
129
+ raise Invalid unless value.instance_of?(Array) && value.size == size &&
130
+ value[0].instance_of?(String) && value[0].match?(/\A[A-Za-z0-9_-]{22,128}\z/)
131
+ value
132
+ end
133
+ def self.epoch!(value) = CheckoutReceipt.send(:epoch!, value)
134
+ def self.exact!(value, fields) = PurchaseBinding.send(:exact!, value, fields)
135
+ def self.hash(wire) = Base64.urlsafe_encode64(Digest::SHA256.digest(wire), padding: false)
136
+ def self.encode(value)
137
+ require "json"
138
+ Base64.urlsafe_encode64(value.instance_of?(String) ? value : JSON.generate(value), padding: false)
139
+ end
140
+ %i[issue_closed present_closed verify].each do |name|
141
+ implementation = method(name)
142
+ fields = implementation.parameters.map(&:last).freeze
143
+ define_singleton_method(name) do |**arguments|
144
+ unless (fields - arguments.keys).empty? && (arguments.keys - fields).empty?
145
+ next Verification.send(:new, :direct_checkout_verification_failed) if name == :verify
146
+ raise Invalid.new, cause: nil
147
+ end
148
+ implementation.call(**arguments)
149
+ end
150
+ end
151
+ private_class_method :parse!, :decode_disclosure!, :epoch!, :exact!, :hash, :encode
152
+ end
153
+ end
@@ -17,6 +17,32 @@ module AP2MandateVerifier
17
17
  private_class_method :new
18
18
  end
19
19
 
20
+ class Verification
21
+ attr_reader :jwt, :checkout_hash, :checkout, :profile_ref
22
+ def initialize(jwt, checkout, profile_ref)
23
+ @jwt, @profile_ref = jwt, profile_ref
24
+ @checkout_hash = Base64.urlsafe_encode64(Digest::SHA256.digest(jwt), padding: false).freeze
25
+ @checkout = ResearchEvidence.send(:copy_frozen, checkout)
26
+ freeze
27
+ end
28
+ def verified? = true
29
+ private_class_method :new
30
+ end
31
+
32
+ # Merchant trust is selected by the application, never by received claims.
33
+ # Checkout has no signed expiry: the app must check current order state.
34
+ def self.verify(jwt:, trusted_public_key_pem:, expected_merchant_id:, profile_ref: TrustContext::PROFILE_REF)
35
+ wire = InputValidator.snapshot!(jwt, max_bytes: 16_384)
36
+ profile = InputValidator.snapshot!(profile_ref, max_bytes: 256)
37
+ merchant = InputValidator.snapshot!(expected_merchant_id, max_bytes: 512)
38
+ claims = RootSignature.verified_payload!(wire, trusted_public_key_pem, expected_typ: "JWT", max_bytes: 16_384)
39
+ validate!(claims, profile_ref: profile)
40
+ raise Invalid unless claims.fetch("merchant").fetch("id") == merchant
41
+ Verification.send(:new, wire, claims, profile)
42
+ rescue StandardError, LoadError
43
+ raise Invalid.new, cause: nil
44
+ end
45
+
20
46
  # signer.call receives the exact ASCII JWS signing input and must return a
21
47
  # 64-byte JOSE ES256 signature. The supplied independent public key verifies
22
48
  # the result before any signed object is returned (including remote signers).
@@ -74,7 +100,7 @@ module AP2MandateVerifier
74
100
  c.send(:totals!, checkout["totals"], total)
75
101
  nil
76
102
  end
77
- %i[sign es256_signer].each do |name|
103
+ %i[sign es256_signer verify].each do |name|
78
104
  implementation = method(name)
79
105
  fields = implementation.parameters.filter_map { |kind, field| field if kind == :keyreq }.freeze
80
106
  optional = implementation.parameters.filter_map { |kind, field| field if kind == :key }.freeze
@@ -33,6 +33,11 @@ module AP2MandateVerifier
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
35
  def self.reference(closed_sd_jwt:, profile_ref: TrustContext::PROFILE_REF)
36
+ profile_ref = InputValidator.snapshot!(profile_ref, max_bytes: 256)
37
+ if profile_ref == Buyer::PROFILE_REF
38
+ parsed = Buyer.send(:parse!, closed_sd_jwt)
39
+ return hash(parsed.fetch(:wire)).freeze
40
+ end
36
41
  wire = InputValidator.snapshot!(closed_sd_jwt, max_bytes: 32_769)
37
42
  raise Invalid unless wire.ascii_only? && wire.end_with?("~") && wire.count("~") == 1
38
43
  compact = wire.byteslice(0, wire.bytesize - 1)
@@ -3,19 +3,20 @@
3
3
  module AP2MandateVerifier
4
4
  # Internal ES256 primitive. Callers must validate the payload's own profile.
5
5
  module MerchantSignature
6
- def self.sign!(claims, signer, public_key_pem)
6
+ def self.sign!(claims, signer, public_key_pem, typ: "JWT")
7
7
  RootSignature.send(:dependencies!)
8
8
  payload = InputBuilder.send(:json!, claims, 12_000)
9
9
  pem = InputValidator.snapshot!(public_key_pem, max_bytes: 1_024)
10
10
  RootSignature.public_jwk!(pem)
11
- header = Base64.urlsafe_encode64('{"alg":"ES256","typ":"JWT"}', padding: false)
11
+ raise ArgumentError unless %w[JWT example+sd-jwt].include?(typ)
12
+ header = Base64.urlsafe_encode64(JSON.generate({"alg" => "ES256", "typ" => typ}), padding: false)
12
13
  input = "#{header}.#{Base64.urlsafe_encode64(payload, padding: false)}".freeze
13
14
  raw = signer.call(input)
14
15
  raise ArgumentError unless Object.instance_method(:instance_of?).bind_call(raw, String) &&
15
16
  String.instance_method(:bytesize).bind_call(raw) == 64
16
17
  signature = String.instance_method(:byteslice).bind_call(raw, 0, 64)
17
18
  jwt = "#{input}.#{Base64.urlsafe_encode64(signature, padding: false)}"
18
- raise ArgumentError unless RootSignature.verified_payload!(jwt, pem, expected_typ: "JWT", max_bytes: 16_384) == claims
19
+ raise ArgumentError unless RootSignature.verified_payload!(jwt, pem, expected_typ: typ, max_bytes: 16_384) == claims
19
20
  jwt.freeze
20
21
  end
21
22
  end
@@ -13,6 +13,7 @@ require_relative "ap2_mandate_verifier/input_builder"
13
13
  require_relative "ap2_mandate_verifier/merchant_signature"
14
14
  require_relative "ap2_mandate_verifier/checkout_jwt"
15
15
  require_relative "ap2_mandate_verifier/checkout_receipt"
16
+ require_relative "ap2_mandate_verifier/buyer"
16
17
 
17
18
  module AP2MandateVerifier
18
19
  # Accepts original JSON bytes only. Syntax validity is not AP2 validity,
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ap2_mandate_verifier
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AP2 Mandate Verifier contributors
@@ -89,12 +89,14 @@ extra_rdoc_files: []
89
89
  files:
90
90
  - LICENSE
91
91
  - README.md
92
+ - docs/BUYER_DIRECT_CHECKOUT.md
92
93
  - docs/DIAGNOSTICS.ja.md
93
94
  - docs/DIAGNOSTICS.md
94
95
  - docs/MERCHANT_SIGNING.md
95
96
  - docs/MULTI_ITEM_CHECKOUT.md
96
97
  - docs/SUPPORT_CONTRACT.md
97
98
  - lib/ap2_mandate_verifier.rb
99
+ - lib/ap2_mandate_verifier/buyer.rb
98
100
  - lib/ap2_mandate_verifier/checkout_jwt.rb
99
101
  - lib/ap2_mandate_verifier/checkout_receipt.rb
100
102
  - lib/ap2_mandate_verifier/diagnostic.rb