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 +4 -4
- data/README.md +20 -11
- data/docs/MERCHANT_SIGNING.md +24 -3
- data/docs/MULTI_ITEM_CHECKOUT.md +118 -0
- data/docs/SUPPORT_CONTRACT.md +25 -5
- data/lib/ap2_mandate_verifier/checkout_jwt.rb +11 -4
- data/lib/ap2_mandate_verifier/checkout_receipt.rb +8 -6
- data/lib/ap2_mandate_verifier/host_binding.rb +2 -1
- data/lib/ap2_mandate_verifier/input_builder.rb +16 -11
- data/lib/ap2_mandate_verifier/purchase_binding.rb +7 -2
- data/lib/ap2_mandate_verifier/root_disclosures.rb +33 -10
- data/lib/ap2_mandate_verifier/scoped_constraints.rb +143 -2
- data/lib/ap2_mandate_verifier/trust_context.rb +21 -4
- data/lib/ap2_mandate_verifier.rb +2 -2
- metadata +2 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: dbeaa8817a128ad64b2307ae68a86cb2c36f40e710dc459f28354e24b3b251f9
|
|
4
|
+
data.tar.gz: 70d40f6293a88043e0f29f10b00e337418ae6819f91cffcb55db8f6c68f21785
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: bd6ba8a1c4be5e8b81ff589624ab17d3e1d3861d49cb8aad457abf96708c2446b996381dc0c948f868538c6b80ae9d2ef45d1c693e2e1fa1cf6874df085faeb5
|
|
7
|
+
data.tar.gz: 7652d380a3ab2024016f0442672b384f6f8e8eecbec416318b1c9224cc8a954c3be1600e5eb1125f1f9eaa5b172609b41e6c0a3074564c0932bc897ae1f8d2ec
|
data/README.md
CHANGED
|
@@ -1,35 +1,44 @@
|
|
|
1
|
-
# AP2 Mandate Verifier — 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.
|
|
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.
|
|
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.
|
|
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
|
|
37
|
+
## Merchant signing and Receipt
|
|
30
38
|
|
|
31
|
-
Create a signed checkout, then sign the application's explicit outcome. These
|
|
32
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
|
data/docs/MERCHANT_SIGNING.md
CHANGED
|
@@ -1,4 +1,23 @@
|
|
|
1
|
-
# Merchant Checkout signing
|
|
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.
|
|
15
|
-
|
|
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.
|
data/docs/SUPPORT_CONTRACT.md
CHANGED
|
@@ -1,8 +1,28 @@
|
|
|
1
|
-
# Fixed-profile AP2 verification —
|
|
1
|
+
# Fixed-profile AP2 verification — 0.6.0 preparation / published history
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Current source: explicit multi-item profile
|
|
4
4
|
|
|
5
|
-
|
|
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.
|
|
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
|
-
|
|
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" =>
|
|
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" =>
|
|
51
|
-
"profile_definition_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" =>
|
|
57
|
-
"definition_hash" =>
|
|
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" =>
|
|
98
|
-
"profile_version" =>
|
|
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,
|
|
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
|
-
|
|
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.
|
|
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 =
|
|
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
|
-
|
|
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 == ["..."] &&
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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") == [
|
|
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"])
|
data/lib/ap2_mandate_verifier.rb
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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
|