ap2_mandate_verifier 1.3.0 → 1.4.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: 30a608bea84123fca2724d48ba8b2ee76b00aeeb6013b5b328c6d0a33744bd8f
4
- data.tar.gz: 60efae2c70da3138cb1046584fa4686353e3b0b92203c38938c9be23c5ae7957
3
+ metadata.gz: 412ad1e06628cf29cd6386aee72aa87e7f84b2abbcc5c117d56642312b138138
4
+ data.tar.gz: 6b8b9e3ab9f8501503185f34e4db692e5a55cda5413abeb791f23b21877dc702
5
5
  SHA512:
6
- metadata.gz: 120c8702536c4f00245874d2c8f160b3ce8a0b6368fb78564a4d3b65ee29dbce7628ef2cd2463ad11227c9107cca1a79e84d7385b8e6720faa3ee732db9ccdc8
7
- data.tar.gz: 81a9170e60e911059a6c081c9099229384d6f4b5676246ba375edffa33c784c32bef33a00c0da94fffb631e554016c3efeddc38917817a3bd533aa7bdd6f2adb
6
+ metadata.gz: 8b5f1a0f6b18626a856c2d059faed5f0b3fb043d41046113fe6e70c30758b9d994971257eeb9363cff38e71da89ecd6d25674dbaf87d461f262f25bc19cc0c9c
7
+ data.tar.gz: 48bad8d9969ab549f71d939819e3bef986b300951d7ea75b6b9f6fce3617337b20f0d1cf55f17ae2a0c8b8d219f1fbffee390640dfbfda809fa0e7e351449026
data/README.ja.md CHANGED
@@ -1,10 +1,14 @@
1
1
  # AP2 Mandate Verifier — Checkout・PaymentのRuby SDK
2
2
 
3
- ### 1.3.0候補:Checkoutの選択的開示
3
+ ### 1.4.0候補:PISPと支払い実行日時の条件
4
4
 
5
- 次期候補では、販売者・商品の非選択候補を送らず、全明細の必要数量を検証できます。CheckoutとPaymentの両方を選択的に開示するRuby単体例も用意します。まだ公開していません。[仕様・制限](docs/SELECTIVE_CHECKOUT.md)、[公開前の確認項目](docs/RELEASE_130_CANDIDATE.md)。以下の公開版導入手順は1.2.0です。
5
+ 次期候補では、承認したPISPと実行可能期間を指定し、アプリが独立して確認した決済サービス・実行予定時刻と照合できます。日時は文字列比較せず解析し、旧1.xの既定動作を維持します。まだ公開していません。[仕様・API・公式との差](docs/PAYMENT_POLICY.md)、[3方式を実行するRuby例](examples/payment_policy.rb)、[公開前の確認](docs/RELEASE_140_CANDIDATE.md)。
6
6
 
7
7
 
8
+ ### 公開済み1.3.0:CheckoutとPaymentの選択的開示
9
+
10
+ 承認済みの完全Openを安全に保持し、Checkoutの販売者・商品候補、Paymentの支払先・決済手段から必要な情報だけを提示できます。全必須条件と数量の検証を維持します。[仕様・API・Python差分](docs/SELECTIVE_CHECKOUT.md)、[Ruby単体の一連の例](examples/selective_checkout_payment.rb)、[公開照合記録](docs/POST_RELEASE_130.md)。
11
+
8
12
  ### 公開済み1.2.0:Payment候補の選択的開示
9
13
 
10
14
  公開済み1.2.0の明示的な`SelectivePayment` profileで、支払先・決済手段の非選択候補を送らずに検証できます。必須条件・委任・原文参照は省略しません。[API・プライバシー・Python差分](docs/SELECTIVE_PAYMENT.md)、[保持/送信を比較するRuby単体例](examples/selective_payment.rb)、[公開照合記録](docs/POST_RELEASE_120.md)。既存`Payment`の既定profileは変更しません。
@@ -15,13 +19,13 @@
15
19
  Direct/条件付きPayment Mandateと成功/エラーPayment Receiptを追加しました。[API・制約・信頼境界](docs/PAYMENT.md)、[Ruby単体サンプル](examples/payment.rb)、[公開照合記録](docs/POST_RELEASE_110.md)、[GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v1.1.0)。検証成功は実行許可ではなく、永続的・原子的な単発利用管理と実決済は利用アプリの責任です。
16
20
 
17
21
  ```sh
18
- gem install ap2_mandate_verifier --version 1.2.0
19
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.2.0").full_gem_path')/examples/payment.rb"
22
+ gem install ap2_mandate_verifier --version 1.3.0
23
+ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.3.0").full_gem_path')/examples/payment.rb"
20
24
  ```
21
25
 
22
26
  [English](README.md)
23
27
 
24
- **公開済み安定版は1.2.0です。**
28
+ **公開済み安定版は1.3.0です。**
25
29
 
26
30
  1.0.0では、既存のDirectと条件付きCheckoutの公開API・保守契約を確立しました。
27
31
  0.8.0の引数・既定値・profile・結果の意味・保存形式と製品実装を維持します。
@@ -41,8 +45,8 @@ Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CO
41
45
  正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
42
46
 
43
47
  ```sh
44
- gem install ap2_mandate_verifier --version 1.2.0
45
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.2.0").full_gem_path')/examples/conditional_checkout.rb"
48
+ gem install ap2_mandate_verifier --version 1.3.0
49
+ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.3.0").full_gem_path')/examples/conditional_checkout.rb"
46
50
  ```
47
51
 
48
52
  [Ruby単体の実行例](examples/conditional_checkout.rb)はインストール済み公開APIだけを使い、
@@ -72,7 +76,7 @@ Rubyで購入委任データを検証する、AP2の固定profile向けGemです
72
76
  正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
73
77
 
74
78
  ```sh
75
- gem install ap2_mandate_verifier --version 1.2.0
79
+ gem install ap2_mandate_verifier --version 1.3.0
76
80
  ```
77
81
 
78
82
  BundlerのGemfile:
data/README.md CHANGED
@@ -1,10 +1,14 @@
1
1
  # AP2 Mandate Verifier — Ruby SDK for Checkout and Payment
2
2
 
3
- ### 1.3.0 candidate: selective Checkout
3
+ ### 1.4.0 candidate: PISP and execution-date conditions
4
4
 
5
- The next candidate adds merchant and product candidate selection with all required quantities retained, plus a combined selective Checkout/Payment Ruby lifecycle. It is not published yet. [Contract and limitations](docs/SELECTIVE_CHECKOUT.md), [release gates](docs/RELEASE_130_CANDIDATE.md). Published installation instructions below remain on 1.2.0.
5
+ The next candidate adds explicit Payment profiles for approved PISPs and parsed inclusive execution windows, bound to independent application provider/time context. Existing1.x defaults remain unchanged. It is not published yet. [Contract/API/official differences](docs/PAYMENT_POLICY.md), [plain Ruby three-mode example](examples/payment_policy.rb), [release gates](docs/RELEASE_140_CANDIDATE.md).
6
6
 
7
7
 
8
+ ### Published 1.3.0: selective Checkout and Payment
9
+
10
+ Keep the complete approved Open confidential and disclose only the merchant/products needed for Checkout, then selected payee/instrument candidates for Payment. Every mandatory condition and quantity remains enforced. [Profile/API/privacy/Python limits](docs/SELECTIVE_CHECKOUT.md), [plain Ruby combined lifecycle](examples/selective_checkout_payment.rb), [verified publication](docs/POST_RELEASE_130.md).
11
+
8
12
  ### Published1.2.0: selective Payment
9
13
 
10
14
  Published1.2.0 adds explicit `SelectivePayment` candidate-array disclosure: retain confidential full issuance, send selected payee/instrument disclosures only, and verify every mandatory condition and exact original-wire reference. [Profile/API/privacy/Python limits](docs/SELECTIVE_PAYMENT.md), [plain Ruby retained-vs-sent example](examples/selective_payment.rb), [verified publication](docs/POST_RELEASE_120.md). Existing `Payment` defaults remain unchanged.
@@ -15,13 +19,13 @@ Published1.2.0 adds explicit `SelectivePayment` candidate-array disclosure: reta
15
19
  1.1.0 adds Direct and conditional Payment Mandates plus signed Success/Error Payment Receipts. [Payment APIs and constraints](docs/PAYMENT.md), [plain Ruby lifecycle sample](examples/payment.rb), [verified publication](docs/POST_RELEASE_110.md), [GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v1.1.0). Verification does not grant execution permission; durable atomic one-use state and actual payment remain application responsibilities.
16
20
 
17
21
  ```sh
18
- gem install ap2_mandate_verifier --version 1.2.0
19
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.2.0").full_gem_path')/examples/payment.rb"
22
+ gem install ap2_mandate_verifier --version 1.3.0
23
+ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.3.0").full_gem_path')/examples/payment.rb"
20
24
  ```
21
25
 
22
26
  [日本語](README.ja.md)
23
27
 
24
- **Published stable: 1.2.0.**
28
+ **Published stable: 1.3.0.**
25
29
 
26
30
  1.0.0 establishes the stable public contract for the existing
27
31
  Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
@@ -45,8 +49,8 @@ multi-item profile. Provider private keys never enter Agent operations.
45
49
  Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
46
50
 
47
51
  ```sh
48
- gem install ap2_mandate_verifier --version 1.2.0
49
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.2.0").full_gem_path')/examples/conditional_checkout.rb"
52
+ gem install ap2_mandate_verifier --version 1.3.0
53
+ ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.3.0").full_gem_path')/examples/conditional_checkout.rb"
50
54
  ```
51
55
 
52
56
  The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
@@ -80,7 +84,7 @@ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readm
80
84
  Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
81
85
 
82
86
  ```sh
83
- gem install ap2_mandate_verifier --version 1.2.0
87
+ gem install ap2_mandate_verifier --version 1.3.0
84
88
  ```
85
89
 
86
90
  Or add to your Gemfile:
@@ -0,0 +1,70 @@
1
+ # PISP and execution-date Payment constraints (1.4.0 candidate)
2
+
3
+ New explicit complete/selective Payment profiles add `payment.allowed_pisps` and `payment.execution_date` without changing the existing1.x defaults. Direct and conditional issuance, presentation, strict verification, selective Checkout/Payment and Payment Receipt references share the existing cryptographic and Host verification paths. This SDK remains framework independent and performs no payment scheduling or execution.
4
+
5
+ ## Ruby API
6
+
7
+ ```ruby
8
+ m = AP2MandateVerifier
9
+ profile = m::PaymentPolicy::PROFILE_REF
10
+ payment = m::Payment.details(**existing_checkout_details,
11
+ pisp: approved_pisp, execution_date: "2026-11-10T00:00:00Z",
12
+ profile_ref: profile)
13
+ constraints = existing_payment_constraints + [
14
+ {"type" => "payment.allowed_pisps", "allowed" => [approved_pisp]},
15
+ {"type" => "payment.execution_date",
16
+ "not_before" => "2026-11-10T00:00:00Z", "not_after" => "2026-11-30T23:59:59Z"}
17
+ ]
18
+ open = m::Payment.issue_open(**existing_open_inputs,
19
+ constraints: constraints, candidate_policy: :independent, profile_ref: profile)
20
+ # Existing issue_closed/present flow, with profile_ref: profile on each call.
21
+ checked = m::Payment.verify(**existing_verification_inputs,
22
+ profile_ref: profile,
23
+ trusted_pisp: authenticated_registry.fetch("processor-A"),
24
+ execution_at: independent_application_execution_at)
25
+ ```
26
+
27
+ Keep the application’s protected approval, authenticated registry and execution context distinct from received claims. Do not build the last two inputs by copying a received Payment. All existing parameters remain required; the snippets show only additions. The [complete installed Ruby example](../examples/payment_policy.rb) runs Direct, complete conditional and selective conditional Payment, rejects mismatched provider/time and an out-of-window date, then verifies both Receipt alternatives.
28
+
29
+ For `SelectivePayment`, use `PaymentPolicy::SELECTIVE_PROFILE_REF` on every lifecycle call (including `select`), retain its existing protected payee/instrument `approved_combinations` and `selective:` inputs, and add `candidate_policy: :independent` on issuance. `Payment.details` prepares the shared details using the new complete profile. Receipt `reference`, `sign` and `verify` take the corresponding explicit profile; final Closed bytes remain the reference source.
30
+
31
+ ## Which conditions are checked, and when?
32
+
33
+ | Condition | Issuance/Agent preparation | Verification |
34
+ | --- | --- | --- |
35
+ | PISP identity | Validate exact legal/brand/domain fields and approved allowlist membership | Authenticate signed chain; compare Closed PISP to independent trusted application PISP and any allowed set |
36
+ | Execution instant | Parse explicit Closed/fixed date and every supplied bound; enforce inclusive window | Compare signed instant with independent application `execution_at`, then all window/fixed conditions |
37
+ | Existing amount/payee/instrument | Retain existing complete or selective constraints | Retain complete Checkout/Host/order/challenge/reference verification |
38
+ | Receipt | Sign a reference to exact final Closed bytes | Authenticate issuer, outcome/time and exact reference; no settlement inference |
39
+
40
+ The new profiles require both explicit `pisp` and `execution_date` in Closed and both `trusted_pisp` and `execution_at` during verification. New Open constraints can contain either new type or both, with at least one. This is a deliberately strict subset: it does not silently interpret an omitted date as immediate execution. The old profiles retain their existing contract.
41
+
42
+ ## Independent trusted execution context
43
+
44
+ `trusted_pisp` must come from the application’s independently authenticated provider selection/registry/channel, not from a received token. Matching `expected_payment` alone is insufficient. Each PISP has exactly `legal_name`, `brand_name` and `domain_name`; all three compare exactly. Domain is canonical lowercase ASCII DNS in this supported profile (bounded valid labels; no URL, port, path, wildcard, trailing dot or unknown field). Names are bounded descriptive strings with no implicit Unicode or case normalization.
45
+
46
+ The official PISP Schema describes the domain as secured by an eIDAS QWAC certificate. This library does not fetch/validate QWACs, establish legal authorization or authenticate a network endpoint from text. Applications own certificate/channel validation, enrollment, revocation and the provenance/freshness of their trusted PISP input. A syntactically valid domain or valid Mandate signature does not establish those facts.
47
+
48
+ `execution_at` is an independently controlled application execution-plan/operational instant. It must represent the same instant as signed `execution_date`. It is distinct from `verified_at`, which checks signature/Mandate freshness. Future plan verification does not prove that execution occurred or will later occur under that context. At the actual execution gate, the application must recheck the actual provider/time/current approval and a valid Mandate, atomically consume one-use state and reconcile uncertain outcomes. The SDK does not schedule, call a PISP or settle a payment.
49
+
50
+ ## Date semantics
51
+
52
+ The supported subset is an explicit RFC3339 timestamp: Gregorian year0001..9999, uppercase `T`/`Z`, valid calendar/time, optional1..9 fractional digits and an explicit `Z` or numeric offset. Offsets must be syntactically valid; `-00:00` (unknown offset), date-only/local timestamps, invalid dates, leap seconds and unsupported precision are rejected. Parsing produces an exact rational instant, without floating-point rounding or lexical comparison.
53
+
54
+ `not_before` and `not_after` are inclusive. At least one bound must be present; if both are present the lower instant cannot exceed the upper. Equivalent offsets denote the same instant for window/context comparisons. A bound ending at `23:59:59Z` denotes that exact instant; later fractions of that second are outside the window. Specify the intended fractional precision or next boundary explicitly. An Open fixed `execution_date` additionally binds its exact string through Agent delegation; a different representation cannot replace that fixed value even if it denotes the same instant.
55
+
56
+ ## Profiles and compatibility
57
+
58
+ Use `PaymentPolicy::PROFILE_REF` (`ap2.payment.pisp_execution.complete.1`) with `Payment`, or `PaymentPolicy::SELECTIVE_PROFILE_REF` (`ap2.payment.pisp_execution.selective.1`) with `SelectivePayment`. Pass the corresponding explicit `profile_ref:` through issuance, selection/presentation, verification and Receipt APIs. New signed profile markers prevent silent cross-profile interpretation. Omitting the option preserves old defaults; old profiles reject the new fields/conditions/context.
59
+
60
+ For new Opens, `candidate_policy: :independent` explicitly means the protected consent approved independent PISP/payee/instrument sets. It is not proof of consent. Existing selective payee×instrument `approved_combinations` checks remain required. Correlated PISP/instrument/payee restrictions cannot be flattened into these sets; issue separate Opens for permitted combinations. Recurrence and cumulative budgets remain unsupported and fail closed.
61
+
62
+ PISP lists and execution conditions are mandatory visible content, including under `SelectivePayment`: the official Schema does not mark the PISP array as selectively disclosable. Only the existing payee/instrument candidate positions may be reduced. Keep complete issuance confidential; counts/order/issuer linkage and intentionally visible PISP conditions remain observable. Errors/diagnostics must not expose hidden candidate values or caller inputs.
63
+
64
+ Direct Payment uses exact protected `approved_payment`, including PISP and execution instant, rather than an Open constraint window. Conditional Payment adds Open constraints and keeps the exact reduced Checkout Open reference. `checkout_profile_ref:` still explicitly selects selective Checkout when used. Receipt authenticity remains a statement about signed reported outcome, not independent PISP/settlement confirmation.
65
+
66
+ ## Official source and Python boundary
67
+
68
+ Adopted source remains AP2v0.2.0 `b4587ac1d055888a73b4b21750973cffba961793`: [Payment specification](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/docs/ap2/payment_mandate.md), [Open Schema](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/code/sdk/schemas/ap2/open_payment_mandate.json), [PISP Schema](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/code/sdk/schemas/ap2/types/pisp.json).
69
+
70
+ The normative text requires inclusive execution bounds. Schema permits weakly typed strings; it does not itself enforce this strict timestamp subset. The pinned Python evaluator compares date strings lexically and permits absent dates even with a date constraint. Its PISP evaluator does compare all three identity fields. Ruby’s parsed/context-bound behavior is an explicit safer supported subset, not an unqualified claim that all official high-level helpers behave identically. Source interoperability observed three lifecycle cases in each direction (Direct/complete conditional/selective conditional), twelve Receipt checks and62 negatives, plus six explicitly recorded upstream date-check disagreements. Separate positive variants cover PISP-only/date-only/one-sided constraints. Exact signed-wire hashes and actual runtime provenance are recorded with the candidate; supported claims do not extend to QWAC provenance, execution or generic AP2 conformance.
data/docs/PUBLIC_API.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Ruby SDK public API — 1.x
2
2
 
3
- **Status: published 1.2.0; the original 1.0.0 Checkout contract below is preserved.**
3
+ **Status: published 1.3.0; the original 1.0.0 Checkout contract below is preserved.**
4
4
  This document defines the 1.x contract for the existing Checkout APIs.
5
5
  The 1.0.0 release preserves the 0.8.0 runtime behavior, API names and accepted
6
6
  formats. Exact distribution identity and validation are in
@@ -206,8 +206,12 @@ The preceding 1.0.0 Checkout contract remains unchanged. New `Payment` and `Paym
206
206
 
207
207
  New explicit `SelectivePayment` APIs are described in the [selective Payment contract](SELECTIVE_PAYMENT.md). They do not alter the published1.1.0 `Payment` default profile or Receipt reference format. They are available in1.2.0 and later, not in1.1.0.
208
208
 
209
- ## 1.3.0 candidate: selective Checkout
209
+ ## Published 1.3.0: selective Checkout
210
210
 
211
- The additive `SelectiveCheckout` profile is included in the 1.3.0 candidate. See the [candidate contract](SELECTIVE_CHECKOUT.md) for mandatory disclosure, independent candidate semantics, original-wire references and application responsibilities. It is not available in the published 1.2.0 package. Existing complete profile defaults are preserved.
211
+ The additive `SelectiveCheckout` profile is available in published 1.3.0. See the [candidate contract](SELECTIVE_CHECKOUT.md) for mandatory disclosure, independent candidate semantics, original-wire references and application responsibilities. It is not available in the published 1.2.0 package. Existing complete profile defaults are preserved.
212
212
 
213
213
  For the explicit selective Checkout profile, Evidence `original_root_graph_closure` records that every signed commitment and supplied disclosure was inspected and accounted for, allowing unresolved candidate leaves only at registered positions. It does not certify hidden preimages, their schema or uniqueness, or consent provenance. The checked scope covers the visible candidate subset and all mandatory conditions.
214
+
215
+ ## 1.4.0 candidate: explicit Payment policy profiles
216
+
217
+ `PaymentPolicy::PROFILE_REF` and `SELECTIVE_PROFILE_REF` opt into PISP/execution constraints in existing `Payment`, `SelectivePayment` and `PaymentReceipt` APIs via `profile_ref:`. Verification additionally requires independently trusted `trusted_pisp:` and `execution_at:`; missing context is never filled from claims. New Open issuance requires `candidate_policy: :independent`. Both new fields are mandatory in Closed, even when only one new Open constraint is used. See [strict parsing, condition stages, API additions and official limitations](PAYMENT_POLICY.md). Old defaults, grammar and result meanings remain unchanged. No scheduler/payment execution is added.
@@ -1,5 +1,7 @@
1
1
  # 1.3.0 release candidate preparation
2
2
 
3
+ **Historical prepublication record. 1.3.0 is now published; see [verified publication](POST_RELEASE_130.md). Do not repeat its push or rebuild a substitute artifact.**
4
+
3
5
  Status: release candidate prepared; final evidence and GO/HOLD judgment are tracked in [Issue #241](https://github.com/cuichangquan/ap2-mandate-verifier/issues/241). **Publication remains HOLD pending the Owner’s final decision.** RubyGems publication, formal v1.3.0 tag, GitHub Release and announcements require the Owner’s final approval. No production deployment or real payment is included.
4
6
 
5
7
  ## Proposed release notes
@@ -0,0 +1,17 @@
1
+ # 1.4.0 candidate preparation
2
+
3
+ Status: release candidate preparation. Final exact-source/package/CI evidence and GO/HOLD recommendation are recorded in the PR and external manifest after verification. RubyGems publication, formalv1.4.0 tag, GitHub Release, announcements, deployment and real payment remain HOLD for Owner decision.
4
+
5
+ ## Proposed notes
6
+
7
+ Ruby applications can constrain a conditional Payment to approved PISPs and an inclusive execution window, bind its signed plan to independently trusted application provider/time context, and combine it with selective Checkout/Payment and Success/Error Receipts. Direct Payment binds exact approved PISP/date details. Existing1.x defaults remain unchanged.
8
+
9
+ This explicit profile supports strict parsed RFC3339 instants and exact PISP identity; it does not authenticate QWACs from strings, schedule payments, prove consent provenance or settlement. PISP/date conditions stay visible. Independent allowlists cannot express correlated provider/payment-method policies; separate Opens are required. Recurrence/budget remain unsupported.
10
+
11
+ ## Final gates
12
+
13
+ Exact-source independent review with no unresolvedP1/P2; signed/context/date/crypto/SD/Receipt/privacy negatives; full regression and installed package verification under supportedMRI3.4.12/4.0.9; independent Python datetime oracle and pinned official SDK/Schema interoperability with discrepancies explicit; exactHEADCI; reproducible one-candidate archive and complete source/archive/installed file equality. Candidate source/size/hash, review/PR/CI links and GO/HOLD recommendation will be recorded externally to avoid self-referential checksums.
14
+
15
+ The fixed builder is existing MRI3.4.12/RubyGems3.6.9 with `SOURCE_DATE_EPOCH=1793750400`; build twice and compare complete archive bytes. Both supported MRI versions must install the same fixed-builder candidate. A different RubyGems builder may change metadata and must not be silently substituted. No checksum is embedded in its own package.
16
+
17
+ Only after Owner approves an exact candidate may publication begin. Recheck source/bytes/reviews/CI and registry absence immediately before a single owner-controlled interactive push. Never retry an ambiguous push; verify registry and downloaded bytes first. Formal tag/Release require matching published bytes and separately authorized release scope. No publish/deploy trigger may be introduced into CI.
@@ -1,4 +1,4 @@
1
- # Selective Checkout Mandates (1.3.0 candidate)
1
+ # Selective Checkout Mandates (published 1.3.0)
2
2
 
3
3
  This explicit profile lets an application retain a confidential complete Open Checkout Mandate and send only the merchant and product candidates needed for a purchase. Every requirement and quantity remains visible and enforced. The existing complete Checkout profiles and their defaults remain available.
4
4
 
@@ -39,7 +39,7 @@ Configure `InputBuilder.trust(..., profile_ref: SelectiveCheckout::PROFILE_REF)`
39
39
 
40
40
  For Payment, pass `checkout_profile_ref: SelectiveCheckout::PROFILE_REF` explicitly to `Payment.issue_open` or `SelectivePayment.issue_open`, and supply the reduced Checkout Open as `open_checkout_sd_jwt`. The default is unchanged. `SelectivePayment.verify` still takes the seven original Checkout verification inputs and rechecks the full Host-bound chain.
41
41
 
42
- Run the installed candidate’s [standalone Checkout example](../examples/selective_checkout.rb) and [combined Checkout/Payment example](../examples/selective_checkout_payment.rb). They generate synthetic keys in memory, compare retained/sent disclosures and authenticate both Success/Error Receipt alternatives without executing a purchase.
42
+ Run the installed Gem’s [standalone Checkout example](../examples/selective_checkout.rb) and [combined Checkout/Payment example](../examples/selective_checkout_payment.rb). They generate synthetic keys in memory, compare retained/sent disclosures and authenticate both Success/Error Receipt alternatives without executing a purchase.
43
43
 
44
44
  ## Verification and quantities
45
45
 
@@ -68,3 +68,5 @@ The adopted AP2 source remains pinned to `b4587ac1d055888a73b4b21750973cffba9617
68
68
  The pinned Python SDK high-level presentation helper does not expose this candidate selection/profile flow. Interoperability must distinguish official low-level signatures/chain/typed Schema checks from the strict subset adapter. In particular, its max-flow helper may accept an empty candidate list as a wildcard or accept underfilled demand; this SDK requires nonempty disclosed candidates and exact quantity coverage. Official SDK acceptance alone is not a strict quantity oracle.
69
69
 
70
70
  Source interoperability observed two Checkout scenarios in each direction, eight Success/Error Receipt checks and 28 negative controls under Ruby 3.4.12 / Python 3.11.2. The Python terminal adapter uses the official JWT primitive plus an exact reduced-wire `sd_hash`, because the SDK’s generic key-binding creator discloses its final payload while this supported Checkout grammar requires an inline final Closed payload. Source and installed-candidate evidence, final review and CI are recorded separately in the release preparation report; these limited synthetic observations do not establish production trust.
71
+
72
+ [Verified public artifact, tag and Release](POST_RELEASE_130.md). The original candidate preparation remains historical in [release preparation](RELEASE_130_CANDIDATE.md).
@@ -0,0 +1,101 @@
1
+ # frozen_string_literal: true
2
+ # Installed SDK only. Synthetic registry, approval and keys; no actual payment.
3
+ require "ap2_mandate_verifier"
4
+ require "time"
5
+ require_relative "selective_checkout"
6
+ module PaymentPolicyExample
7
+ M = AP2MandateVerifier
8
+ NOW = SelectiveCheckoutExample::NOW
9
+ def self.run
10
+ state = SelectiveCheckoutExample.run
11
+ provider, agent, merchant = state.fetch(:keys)
12
+ signer = ->(key) { M::CheckoutJWT.es256_signer(private_key: key) }
13
+ # These synthetic registry entries represent independently authenticated app
14
+ # state. Production code validates enrollment/channel/QWAC/revocation itself.
15
+ registry = {"processor-A" => {"legal_name" => "Example Payment Services Ltd.",
16
+ "brand_name" => "ExamplePay", "domain_name" => "pay.example"}}
17
+ trusted_pisp = registry.fetch("processor-A")
18
+ planned = Time.at(NOW + 3600).utc
19
+ date = planned.iso8601(3)
20
+ execution_at = planned.getlocal("+09:00").iso8601(3) # Same instant, different representation.
21
+ profile = M::PaymentPolicy::PROFILE_REF
22
+ selective_profile = M::PaymentPolicy::SELECTIVE_PROFILE_REF
23
+ checkout = state.fetch(:closed).checkout_jwt
24
+ details = M::Payment.details(checkout_jwt: checkout, trusted_merchant_public_key_pem: merchant.public_to_pem,
25
+ expected_merchant_id: "shop", payment_instrument: {"id" => "synthetic-card-A", "type" => "card"},
26
+ pisp: trusted_pisp, execution_date: date, profile_ref: profile)
27
+ direct_checkout = M::Buyer.issue_closed(checkout_jwt: checkout, approved_checkout_jwt: checkout,
28
+ trusted_merchant_public_key_pem: merchant.public_to_pem, expected_merchant_id: "shop", issued_at: NOW,
29
+ expires_at: NOW + 60, signer: signer.call(provider), public_key_pem: provider.public_to_pem)
30
+ direct_inputs = {closed_sd_jwt: direct_checkout.closed_sd_jwt, expected_checkout_jwt: checkout,
31
+ trusted_provider_public_key_pem: provider.public_to_pem, trusted_merchant_public_key_pem: merchant.public_to_pem,
32
+ expected_merchant_id: "shop", verified_at: NOW}
33
+ direct = M::Payment.issue_direct(payment: details, approved_payment: details, issued_at: NOW,
34
+ expires_at: NOW + 60, signer: signer.call(provider), public_key_pem: provider.public_to_pem, profile_ref: profile)
35
+ base = {expected_payment: details, trusted_provider_public_key_pem: provider.public_to_pem,
36
+ trusted_pisp: trusted_pisp, execution_at: execution_at, verified_at: NOW, profile_ref: profile}
37
+ direct_args = base.merge(closed_sd_jwt: direct.closed_sd_jwt, checkout_mode: :direct, checkout_inputs: direct_inputs)
38
+ raise "Direct policy verification failed" unless M::Payment.verify(**direct_args).verified?
39
+ wrong_pisp = trusted_pisp.merge("brand_name" => "Unapproved brand")
40
+ raise "PISP context mismatch accepted" if M::Payment.verify(**direct_args.merge(trusted_pisp: wrong_pisp)).verified?
41
+ raise "execution context mismatch accepted" if M::Payment.verify(**direct_args.merge(execution_at: (planned + 1).iso8601(3))).verified?
42
+ puts "Direct: approved PISP/date verified; wrong independent PISP/time rejected"
43
+
44
+ payees = [details.fetch("payee"), {"id" => "private-alternative", "name" => "Private alternative payee"}]
45
+ instruments = [details.fetch("payment_instrument"), {"id" => "private-card", "type" => "card"}]
46
+ conditions = [{"type" => "payment.amount_range", "currency" => "USD", "max" => 300},
47
+ {"type" => "payment.allowed_payees", "allowed" => payees},
48
+ {"type" => "payment.allowed_payment_instruments", "allowed" => instruments},
49
+ {"type" => "payment.allowed_pisps", "allowed" => [trusted_pisp]},
50
+ {"type" => "payment.execution_date", "not_before" => (planned - 1).iso8601(3), "not_after" => (planned + 1).iso8601(3)}]
51
+ open_args = {open_checkout_sd_jwt: state.fetch(:opening).root_presentation, constraints: conditions, fixed: {},
52
+ agent_public_key_pem: agent.public_to_pem, issued_at: NOW, expires_at: NOW + 60,
53
+ signer: signer.call(provider), public_key_pem: provider.public_to_pem,
54
+ checkout_profile_ref: M::SelectiveCheckout::PROFILE_REF, candidate_policy: :independent}
55
+ open = M::Payment.issue_open(**open_args, profile_ref: profile)
56
+ close_args = {payment: details, trusted_provider_public_key_pem: provider.public_to_pem,
57
+ agent_public_key_pem: agent.public_to_pem, audience: "credential-provider", nonce: "synthetic-policy-nonce",
58
+ verified_at: NOW, signer: signer.call(agent)}
59
+ closed = M::Payment.issue_closed(**close_args, open_sd_jwt: open, profile_ref: profile)
60
+ restored = M::Payment.present(open_sd_jwt: open, closed_sd_jwt: closed.closed_sd_jwt, profile_ref: profile)
61
+ raw = M::InputBuilder.inputs(**state.fetch(:host_inputs), saved_challenge: state.fetch(:saved),
62
+ terminal_jws: state.fetch(:closed).terminal_jws, expected_challenge_issuer_id: "host", clock_source_id: "synthetic-clock", verified_at: NOW)
63
+ expected_agent = {expected_agent_public_key_pem: agent.public_to_pem, expected_audience: "credential-provider", expected_nonce: "synthetic-policy-nonce"}
64
+ checked = M::Payment.verify(**base, **expected_agent, closed_sd_jwt: restored.closed_sd_jwt,
65
+ open_sd_jwt: restored.open_sd_jwt, checkout_mode: :conditional, checkout_inputs: raw)
66
+ raise "conditional policy verification failed" unless checked.verified?
67
+ begin
68
+ M::Payment.issue_closed(**close_args.merge(payment: details.merge("execution_date" => (planned + 2).iso8601(3))), open_sd_jwt: open, profile_ref: profile)
69
+ raise "outside execution window accepted"
70
+ rescue M::Payment::Invalid
71
+ puts "Conditional: allowed PISP/inclusive window verified; outside window rejected"
72
+ end
73
+ full = M::SelectivePayment.issue_open(**open_args, profile_ref: selective_profile,
74
+ approved_combinations: [[0,0],[0,1],[1,0],[1,1]], selective: :both)
75
+ reduced = M::SelectivePayment.select(open_sd_jwt: full, payee_index: 0, instrument_index: 0, profile_ref: selective_profile)
76
+ selective_closed = M::SelectivePayment.issue_closed(**close_args, open_presentation: reduced, profile_ref: selective_profile)
77
+ selective = M::SelectivePayment.present(open_presentation: reduced, closed_sd_jwt: selective_closed.closed_sd_jwt, profile_ref: selective_profile)
78
+ result = M::SelectivePayment.verify(**base.merge(profile_ref: selective_profile), **expected_agent,
79
+ open_presentation: reduced, closed_sd_jwt: selective.closed_sd_jwt, checkout_inputs: raw)
80
+ raise "selective policy verification failed" unless result.verified?
81
+ visible = reduced.split("~", -1)[1...-1].map { |s| JSON.parse(Base64.urlsafe_decode64(s)) }
82
+ raise "hidden candidate leaked" if JSON.generate(visible).include?("private-alternative") || JSON.generate(visible).include?("private-card")
83
+ puts "Selective: Checkout and Payment verified; unselected payee/instrument hidden; PISP/date conditions fully visible"
84
+ [[direct, profile], [restored, profile], [selective, selective_profile]].each do |payment, ref|
85
+ %w[Success Error].each do |outcome|
86
+ fields = outcome == "Success" ? {psp_confirmation_id: "synthetic-psp", network_confirmation_id: "synthetic-network"} :
87
+ {error: "declined", error_description: "Simulated refusal"}
88
+ receipt = M::PaymentReceipt.sign(closed_sd_jwt: payment.closed_sd_jwt, profile_ref: ref, issuer: "processor-A",
89
+ payment_id: "synthetic-policy-payment", outcome: outcome, issued_at: NOW, **fields,
90
+ signer: signer.call(merchant), public_key_pem: merchant.public_to_pem)
91
+ verified = M::PaymentReceipt.verify(jwt: receipt.jwt, closed_sd_jwt: payment.closed_sd_jwt, profile_ref: ref,
92
+ trusted_public_key_pem: merchant.public_to_pem, expected_issuer: "processor-A", expected_payment_id: "synthetic-policy-payment",
93
+ not_before: NOW, not_after: NOW + 60, verified_at: NOW)
94
+ raise "policy Receipt failed" unless verified.verified? && verified.outcome == outcome
95
+ end
96
+ end
97
+ puts "Success/Error Payment Receipts authenticated for all three modes"
98
+ puts "Synthetic plan only: no QWAC provenance, scheduling, execution permission or settlement is established."
99
+ end
100
+ end
101
+ PaymentPolicyExample.run if $PROGRAM_NAME == __FILE__
@@ -36,71 +36,90 @@ module AP2MandateVerifier
36
36
 
37
37
  # Checkout JWT and key must be from independently trusted application state.
38
38
  # This prepares data, not consent or a verified Checkout Mandate.
39
- def self.details(checkout_jwt:, trusted_merchant_public_key_pem:, expected_merchant_id:, payment_instrument:)
39
+ def self.details(checkout_jwt:, trusted_merchant_public_key_pem:, expected_merchant_id:, payment_instrument:,
40
+ profile_ref: PROFILE_REF, pisp: nil, execution_date: nil)
41
+ profile = PaymentPolicy.profile!(profile_ref)
42
+ if PaymentPolicy.enabled?(profile)
43
+ planned = InputBuilder.send(:copy!, {"pisp" => pisp, "execution_date" => execution_date})
44
+ PaymentPolicy.details!(planned)
45
+ else
46
+ raise Invalid unless pisp.nil? && execution_date.nil?
47
+ end
40
48
  checked = CheckoutJWT.verify(jwt: checkout_jwt, trusted_public_key_pem: trusted_merchant_public_key_pem,
41
49
  expected_merchant_id: expected_merchant_id, profile_ref: ScopedConstraints::MULTI_PROFILE_REF)
42
50
  instrument = InputBuilder.send(:copy!, payment_instrument)
43
51
  instrument!(instrument)
44
- ResearchEvidence.send(:copy_frozen, {"transaction_id" => checked.checkout_hash,
52
+ value = {"transaction_id" => checked.checkout_hash,
45
53
  "payee" => checked.checkout.fetch("merchant"), "payment_instrument" => instrument,
46
54
  "payment_amount" => {"currency" => checked.checkout.fetch("currency"),
47
- "amount" => ScopedConstraints.multi_checkout!(checked.checkout)}})
55
+ "amount" => ScopedConstraints.multi_checkout!(checked.checkout)}}
56
+ if PaymentPolicy.enabled?(profile)
57
+ value.merge!(planned)
58
+ end
59
+ ResearchEvidence.send(:copy_frozen, copy_details!(value, profile_ref: profile))
48
60
  end
49
61
 
50
62
  # Protected approval record must cover every payment detail, not just amount.
51
- def self.issue_direct(payment:, approved_payment:, issued_at:, expires_at:, signer:, public_key_pem:)
52
- value = copy_details!(payment)
53
- raise Invalid unless value == copy_details!(approved_payment)
63
+ def self.issue_direct(payment:, approved_payment:, issued_at:, expires_at:, signer:, public_key_pem:, profile_ref: PROFILE_REF)
64
+ profile_ref = PaymentPolicy.profile!(profile_ref)
65
+ value = copy_details!(payment, profile_ref: profile_ref)
66
+ raise Invalid unless value == copy_details!(approved_payment, profile_ref: profile_ref)
54
67
  closed = value.merge("vct" => "mandate.payment.1", "iat" => issued_at, "exp" => expires_at)
55
- closed!(closed)
56
- Presentation.send(:new, nil, sign_root!(closed, signer, public_key_pem))
68
+ closed!(closed, profile_ref: profile_ref)
69
+ Presentation.send(:new, nil, sign_root!(closed, signer, public_key_pem, profile_ref: profile_ref))
57
70
  end
58
71
 
59
72
  # Reference is calculated over exact original Open Checkout, never rebuilt JSON.
60
73
  # The app authenticates consent to these conditions before invoking this API.
61
74
  def self.issue_open(open_checkout_sd_jwt:, constraints:, fixed:, agent_public_key_pem:,
62
- issued_at:, expires_at:, signer:, public_key_pem:, checkout_profile_ref: ScopedConstraints::MULTI_PROFILE_REF)
75
+ issued_at:, expires_at:, signer:, public_key_pem:, checkout_profile_ref: ScopedConstraints::MULTI_PROFILE_REF,
76
+ profile_ref: PROFILE_REF, candidate_policy: nil)
77
+ profile_ref = PaymentPolicy.profile!(profile_ref)
78
+ PaymentPolicy.candidate_policy!(profile_ref, candidate_policy)
63
79
  RootSignature.send(:dependencies!)
64
80
  root = checkout_open!(open_checkout_sd_jwt, profile_ref: checkout_profile_ref)
65
81
  conditions = InputBuilder.send(:copy!, constraints)
66
82
  raise Invalid unless conditions.instance_of?(Array)
67
83
  conditions << {"type" => "payment.reference", "conditional_transaction_id" => digest(root)}
68
84
  value = InputBuilder.send(:copy!, fixed)
69
- raise Invalid unless value.instance_of?(Hash) && (value.keys - FIELDS.drop(1)).empty?
85
+ raise Invalid unless value.instance_of?(Hash) && (value.keys - PaymentPolicy.fields(profile_ref).drop(1)).empty?
70
86
  opening = value.merge("vct" => "mandate.payment.open.1", "iat" => issued_at, "exp" => expires_at,
71
87
  "cnf" => {"jwk" => RootSignature.public_jwk!(agent_public_key_pem)}, "constraints" => conditions)
72
- open!(opening)
73
- sign_root!(opening, signer, public_key_pem).freeze
88
+ open!(opening, profile_ref: profile_ref)
89
+ sign_root!(opening, signer, public_key_pem, profile_ref: profile_ref).freeze
74
90
  end
75
91
 
76
92
  # Provider signer is deliberately absent. Existing signed Open grants the hop.
77
93
  def self.issue_closed(open_sd_jwt:, payment:, trusted_provider_public_key_pem:, agent_public_key_pem:,
78
- audience:, nonce:, verified_at:, signer:)
94
+ audience:, nonce:, verified_at:, signer:, profile_ref: PROFILE_REF)
95
+ profile_ref = PaymentPolicy.profile!(profile_ref)
79
96
  agent_public_key_pem = InputValidator.snapshot!(agent_public_key_pem, max_bytes: 1_024)
80
- opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem)
81
- open!(opening); valid_now!(opening, verified_at)
97
+ opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
98
+ open!(opening, profile_ref: profile_ref); valid_now!(opening, verified_at)
82
99
  raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(agent_public_key_pem)}
83
- value = copy_details!(payment).merge("vct" => "mandate.payment.1", "iat" => verified_at, "exp" => opening.fetch("exp"))
84
- closed!(value); conditions!(opening, value)
100
+ value = copy_details!(payment, profile_ref: profile_ref).merge("vct" => "mandate.payment.1", "iat" => verified_at, "exp" => opening.fetch("exp"))
101
+ closed!(value, profile_ref: profile_ref); conditions!(opening, value, profile_ref: profile_ref)
85
102
  audience = InputValidator.snapshot!(audience, max_bytes: 512)
86
103
  nonce = InputValidator.snapshot!(nonce, max_bytes: 512)
87
104
  text!(audience, 512); text!(nonce, 512)
88
105
  claims = {"delegate_payload" => [value], "iat" => verified_at,
89
106
  "aud" => audience, "nonce" => nonce, "sd_hash" => digest(root)}
90
- preflight!(claims, "kb+sd-jwt")
107
+ claims["ap2_profile"] = profile_ref if PaymentPolicy.enabled?(profile_ref)
108
+ preflight!(claims, "kb+sd-jwt", profile_ref: profile_ref)
91
109
  terminal = MerchantSignature.sign!(claims, signer, agent_public_key_pem, typ: "kb+sd-jwt")
92
110
  Presentation.send(:new, root, terminal + "~")
93
111
  end
94
112
 
95
113
  # Original-byte restoration only. All authentication belongs to verify.
96
- def self.present(closed_sd_jwt:, open_sd_jwt: nil)
97
- closed, wire = final!(closed_sd_jwt, conditional: !open_sd_jwt.nil?)
98
- closed!(closed.fetch("delegate_payload").first)
114
+ def self.present(closed_sd_jwt:, open_sd_jwt: nil, profile_ref: PROFILE_REF)
115
+ profile_ref = PaymentPolicy.profile!(profile_ref)
116
+ closed, wire = final!(closed_sd_jwt, conditional: !open_sd_jwt.nil?, profile_ref: profile_ref)
117
+ closed!(closed.fetch("delegate_payload").first, profile_ref: profile_ref)
99
118
  if open_sd_jwt
100
- opening, root = root!(open_sd_jwt)
101
- open!(opening)
119
+ opening, root = root!(open_sd_jwt, profile_ref: profile_ref)
120
+ open!(opening, profile_ref: profile_ref)
102
121
  raise Invalid unless closed.fetch("sd_hash") == digest(root)
103
- conditions!(opening, closed.fetch("delegate_payload").first)
122
+ conditions!(opening, closed.fetch("delegate_payload").first, profile_ref: profile_ref)
104
123
  end
105
124
  Presentation.send(:new, open_sd_jwt && root, wire)
106
125
  end
@@ -110,7 +129,16 @@ module AP2MandateVerifier
110
129
  # Direct uses Buyer.verify; conditional uses verify_checkout's seven inputs.
111
130
  def self.verify(closed_sd_jwt:, checkout_mode:, checkout_inputs:, expected_payment:,
112
131
  trusted_provider_public_key_pem:, verified_at:, open_sd_jwt: nil,
113
- expected_agent_public_key_pem: nil, expected_audience: nil, expected_nonce: nil)
132
+ expected_agent_public_key_pem: nil, expected_audience: nil, expected_nonce: nil,
133
+ profile_ref: PROFILE_REF, trusted_pisp: nil, execution_at: nil)
134
+ profile_ref = PaymentPolicy.profile!(profile_ref)
135
+ context = PaymentPolicy.context!(profile_ref, trusted_pisp, execution_at)
136
+ trusted_provider_public_key_pem = InputValidator.snapshot!(trusted_provider_public_key_pem, max_bytes: 1_024)
137
+ if checkout_mode == :conditional
138
+ expected_agent_public_key_pem = InputValidator.snapshot!(expected_agent_public_key_pem, max_bytes: 1_024)
139
+ expected_audience = InputValidator.snapshot!(expected_audience, max_bytes: 512)
140
+ expected_nonce = InputValidator.snapshot!(expected_nonce, max_bytes: 512)
141
+ end
114
142
  CheckoutReceipt.send(:epoch!, verified_at)
115
143
  raise Invalid unless checkout_inputs.instance_of?(Hash) && checkout_inputs[:verified_at] == verified_at
116
144
  fields = case checkout_mode
@@ -129,14 +157,14 @@ module AP2MandateVerifier
129
157
  if checkout_mode == :conditional
130
158
  expected_agent_public_key_pem = InputValidator.snapshot!(expected_agent_public_key_pem, max_bytes: 1_024)
131
159
  end
132
- expected = copy_details!(expected_payment)
160
+ expected = copy_details!(expected_payment, profile_ref: profile_ref)
133
161
  case checkout_mode
134
162
  when :direct
135
163
  raise Invalid if open_sd_jwt || expected_agent_public_key_pem || expected_audience || expected_nonce
136
164
  checked = Buyer.verify(**checkout_inputs)
137
165
  raise Invalid unless checked.verified? && expected.fetch("transaction_id") == checked.checkout_hash
138
166
  bind_checkout!(expected, checked.checkout)
139
- claims, wire = verified_root!(closed_sd_jwt, trusted_provider_public_key_pem)
167
+ claims, wire = verified_root!(closed_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
140
168
  when :conditional
141
169
  checked = AP2MandateVerifier.verify_checkout(**checkout_inputs)
142
170
  raise Invalid unless checked.success?
@@ -150,10 +178,10 @@ module AP2MandateVerifier
150
178
  # Full Checkout verifier already authenticated these exact JWT bytes.
151
179
  payload = jwt_payload!(checkout, "JWT")
152
180
  bind_checkout!(expected, payload)
153
- opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem)
154
- open!(opening); valid_now!(opening, verified_at)
181
+ opening, root = verified_root!(open_sd_jwt, trusted_provider_public_key_pem, profile_ref: profile_ref)
182
+ open!(opening, profile_ref: profile_ref); valid_now!(opening, verified_at)
155
183
  raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(expected_agent_public_key_pem)}
156
- terminal, wire = final!(closed_sd_jwt, conditional: true)
184
+ terminal, wire = final!(closed_sd_jwt, conditional: true, profile_ref: profile_ref)
157
185
  RootSignature.verified_payload!(wire.split("~", -1).first, expected_agent_public_key_pem,
158
186
  expected_typ: "kb+sd-jwt", max_bytes: 32_768)
159
187
  expected_audience = InputValidator.snapshot!(expected_audience, max_bytes: 512)
@@ -163,28 +191,31 @@ module AP2MandateVerifier
163
191
  terminal.fetch("sd_hash") == digest(root) && terminal.fetch("iat") <= verified_at &&
164
192
  verified_at - terminal.fetch("iat") <= 300
165
193
  claims = terminal.fetch("delegate_payload").first
166
- closed!(claims); valid_now!(claims, verified_at)
194
+ closed!(claims, profile_ref: profile_ref); valid_now!(claims, verified_at)
167
195
  raise Invalid unless terminal.fetch("iat") == claims.fetch("iat") && claims.fetch("iat") >= opening.fetch("iat") &&
168
196
  claims.fetch("exp") <= opening.fetch("exp")
169
- conditions!(opening, claims)
197
+ conditions!(opening, claims, profile_ref: profile_ref)
170
198
  reference = opening.fetch("constraints").find { |c| c["type"] == "payment.reference" }
171
199
  raise Invalid unless reference.fetch("conditional_transaction_id") == digest(checkout_inputs.fetch(:root_presentation))
172
200
  else raise Invalid
173
201
  end
174
- closed!(claims); valid_now!(claims, verified_at)
175
- raise Invalid unless claims.slice(*FIELDS) == expected
202
+ closed!(claims, profile_ref: profile_ref); valid_now!(claims, verified_at)
203
+ PaymentPolicy.bind_context!(claims, context) if context
204
+ raise Invalid unless claims.slice(*PaymentPolicy.fields(profile_ref)) == expected
176
205
  Verification.send(:new, claims, wire)
177
206
  rescue StandardError, LoadError
178
207
  Verification.send(:new)
179
208
  end
180
209
 
181
- def self.reference(closed_sd_jwt:)
210
+ def self.reference(closed_sd_jwt:, profile_ref: PROFILE_REF)
211
+ profile_ref = InputValidator.snapshot!(profile_ref, max_bytes: 256)
212
+ raise Invalid unless profile_ref == PROFILE_REF || PaymentPolicy.enabled?(profile_ref)
182
213
  # No trust or authorization claim: parse either supported final grammar.
183
214
  wire = InputValidator.snapshot!(closed_sd_jwt, max_bytes: 32_769)
184
215
  payload = jwt_payload!(wire.split("~", -1).first, nil)
185
216
  conditional = payload.key?("sd_hash")
186
- final, original = final!(wire, conditional: conditional)
187
- closed!(final.fetch("delegate_payload").first)
217
+ final, original = final!(wire, conditional: conditional, profile_ref: profile_ref)
218
+ closed!(final.fetch("delegate_payload").first, profile_ref: profile_ref)
188
219
  digest(original).freeze
189
220
  end
190
221
 
@@ -193,19 +224,25 @@ module AP2MandateVerifier
193
224
  value.fetch("payment_amount") == {"currency" => checkout.fetch("currency"),
194
225
  "amount" => ScopedConstraints.multi_checkout!(checkout)}
195
226
  end
196
- def self.copy_details!(value)
227
+ def self.copy_details!(value, profile_ref: PROFILE_REF)
197
228
  value = InputBuilder.send(:copy!, value)
198
- exact!(value, FIELDS)
229
+ exact!(value, PaymentPolicy.fields(profile_ref))
199
230
  raise Invalid unless value["transaction_id"].instance_of?(String) && value["transaction_id"].match?(/\A[A-Za-z0-9_-]{43}\z/)
200
231
  payee!(value["payee"]); amount!(value["payment_amount"]); instrument!(value["payment_instrument"])
232
+ PaymentPolicy.details!(value) if PaymentPolicy.enabled?(profile_ref)
201
233
  value
202
234
  end
203
- def self.closed!(value)
204
- exact!(value, FIELDS + %w[vct iat exp])
235
+ def self.closed!(value, profile_ref: PROFILE_REF)
236
+ exact!(value, PaymentPolicy.fields(profile_ref) + %w[vct iat exp])
205
237
  raise Invalid unless value["vct"] == "mandate.payment.1"
206
- copy_details!(value.slice(*FIELDS)); times!(value)
238
+ copy_details!(value.slice(*PaymentPolicy.fields(profile_ref)), profile_ref: profile_ref); times!(value)
207
239
  end
208
- def self.open!(value)
240
+ def self.open!(value, profile_ref: PROFILE_REF)
241
+ if PaymentPolicy.enabled?(profile_ref)
242
+ base = PaymentPolicy.constraints!(value)
243
+ open!(base)
244
+ return nil
245
+ end
209
246
  raise Invalid unless value.instance_of?(Hash) && (value.keys - FIELDS.drop(1) - %w[vct iat exp cnf constraints]).empty?
210
247
  raise Invalid unless value["vct"] == "mandate.payment.open.1"
211
248
  times!(value); exact!(value["cnf"], ["jwk"])
@@ -236,7 +273,13 @@ module AP2MandateVerifier
236
273
  end
237
274
  end
238
275
  end
239
- def self.conditions!(opening, closed)
276
+ def self.conditions!(opening, closed, profile_ref: PROFILE_REF)
277
+ if PaymentPolicy.enabled?(profile_ref)
278
+ PaymentPolicy.conditions!(opening, closed)
279
+ base = PaymentPolicy.constraints!(opening)
280
+ conditions!(base, closed)
281
+ return nil
282
+ end
240
283
  FIELDS.drop(1).each { |f| raise Invalid if opening.key?(f) && opening[f] != closed[f] }
241
284
  opening.fetch("constraints").each do |c|
242
285
  case c["type"]
@@ -292,7 +335,7 @@ module AP2MandateVerifier
292
335
  raise Invalid unless RootSignature.send(:decode!, parts[2], 64).bytesize == 64
293
336
  InputValidator.parse!(RootSignature.send(:decode!, parts[1], 24_576))
294
337
  end
295
- def self.final!(source, conditional:)
338
+ def self.final!(source, conditional:, profile_ref: PROFILE_REF)
296
339
  wire = InputValidator.snapshot!(source, max_bytes: 32_769)
297
340
  raise Invalid unless wire.ascii_only? && wire.end_with?("~") && [1, 2].include?(wire.count("~"))
298
341
  compact, *parts = wire.split("~", -1)
@@ -300,6 +343,10 @@ module AP2MandateVerifier
300
343
  claims = jwt_payload!(compact, conditional ? "kb+sd-jwt" : "example+sd-jwt")
301
344
  fields = conditional ? %w[delegate_payload iat aud nonce sd_hash] : %w[delegate_payload _sd_alg]
302
345
  fields += ["_sd_alg"] if conditional && claims.key?("_sd_alg")
346
+ if PaymentPolicy.enabled?(profile_ref)
347
+ fields += ["ap2_profile"]
348
+ raise Invalid unless claims["ap2_profile"] == profile_ref
349
+ end
303
350
  exact!(claims, fields)
304
351
  raise Invalid if claims.key?("_sd_alg") && claims["_sd_alg"] != "sha-256"
305
352
  if conditional
@@ -320,33 +367,34 @@ module AP2MandateVerifier
320
367
  end
321
368
  [claims, wire]
322
369
  end
323
- def self.root!(source)
324
- claims, wire = final!(source, conditional: false)
370
+ def self.root!(source, profile_ref: PROFILE_REF)
371
+ claims, wire = final!(source, conditional: false, profile_ref: profile_ref)
325
372
  [claims.fetch("delegate_payload").first, wire]
326
373
  end
327
- def self.verified_root!(source, key)
328
- value, wire = root!(source)
374
+ def self.verified_root!(source, key, profile_ref: PROFILE_REF)
375
+ value, wire = root!(source, profile_ref: profile_ref)
329
376
  RootSignature.verified_payload!(wire.split("~", -1).first, key, max_bytes: 32_768)
330
377
  [value, wire]
331
378
  end
332
- def self.sign_root!(value, signer, key)
379
+ def self.sign_root!(value, signer, key, profile_ref: PROFILE_REF)
333
380
  RootSignature.send(:dependencies!)
334
381
  require "securerandom"
335
382
  disclosure = Buyer.send(:encode, [Buyer.send(:encode, SecureRandom.random_bytes(16)), value])
336
383
  claims = {"delegate_payload" => [{"..." => digest(disclosure)}], "_sd_alg" => "sha-256"}
337
- preflight!(claims, "example+sd-jwt", disclosure)
384
+ claims["ap2_profile"] = profile_ref if PaymentPolicy.enabled?(profile_ref)
385
+ preflight!(claims, "example+sd-jwt", disclosure, profile_ref: profile_ref)
338
386
  wire = MerchantSignature.sign!(claims, signer, key,
339
387
  typ: "example+sd-jwt") + "~" + disclosure + "~"
340
- final!(wire, conditional: false)
388
+ final!(wire, conditional: false, profile_ref: profile_ref)
341
389
  wire
342
390
  end
343
- def self.preflight!(claims, typ, disclosure = nil)
391
+ def self.preflight!(claims, typ, disclosure = nil, profile_ref: PROFILE_REF)
344
392
  # Bound every new Mandate signature before remote signer effects. ES256
345
393
  # signatures have a fixed 64-byte width; this performs no cryptography.
346
394
  compact = [Buyer.send(:encode, {"alg" => "ES256", "typ" => typ}),
347
395
  Buyer.send(:encode, claims), Buyer.send(:encode, "\0" * 64)].join(".")
348
396
  wire = compact + "~" + (disclosure ? disclosure + "~" : "")
349
- final!(wire, conditional: typ == "kb+sd-jwt")
397
+ final!(wire, conditional: typ == "kb+sd-jwt", profile_ref: profile_ref)
350
398
  end
351
399
  def self.digest(wire) = Base64.urlsafe_encode64(Digest::SHA256.digest(wire), padding: false)
352
400
  def self.exact!(v, fields) = PurchaseBinding.send(:exact!, v, fields)
@@ -0,0 +1,115 @@
1
+ # frozen_string_literal: true
2
+
3
+ module AP2MandateVerifier
4
+ # Explicit, narrower operational-plan profile. No scheduling or QWAC proof.
5
+ module PaymentPolicy
6
+ PROFILE_REF = "ap2.payment.pisp_execution.complete.1".freeze
7
+ SELECTIVE_PROFILE_REF = "ap2.payment.pisp_execution.selective.1".freeze
8
+ FIELDS = %w[pisp execution_date].freeze
9
+ TYPES = %w[payment.allowed_pisps payment.execution_date].freeze
10
+ def self.enabled?(profile)
11
+ [PROFILE_REF, SELECTIVE_PROFILE_REF].include?(profile)
12
+ end
13
+ def self.profile!(value, selective: false)
14
+ profile = InputValidator.snapshot!(value, max_bytes: 256)
15
+ old, current = selective ? [SelectivePayment::PROFILE_REF, SELECTIVE_PROFILE_REF] : [Payment::PROFILE_REF, PROFILE_REF]
16
+ raise Payment::Invalid unless [old, current].include?(profile)
17
+ profile
18
+ end
19
+ def self.candidate_policy!(profile, policy)
20
+ raise Payment::Invalid unless enabled?(profile) ? policy == :independent : policy.nil?
21
+ end
22
+ def self.fields(profile) = Payment::FIELDS + (enabled?(profile) ? FIELDS : [])
23
+ def self.pisp!(value)
24
+ Payment.send(:exact!, value, %w[brand_name domain_name legal_name])
25
+ %w[legal_name brand_name].each { |f| Payment.send(:text!, value[f], 512) }
26
+ domain = value["domain_name"]
27
+ raise Payment::Invalid unless domain.instance_of?(String) && domain.bytesize.between?(1, 253) && domain.ascii_only? &&
28
+ domain.split(".", -1).all? { |label| label.bytesize.between?(1, 63) && label.match?(/\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/) }
29
+ end
30
+ # Exact decimal arithmetic; no permissive DateTime parsing/normalization.
31
+ def self.instant!(source)
32
+ value = InputValidator.snapshot!(source, max_bytes: 40)
33
+ m = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})\z/.match(value)
34
+ raise Payment::Invalid unless m
35
+ y, month, day, hour, minute, second = m.captures.first(6).map(&:to_i)
36
+ leap = y % 4 == 0 && (y % 100 != 0 || y % 400 == 0)
37
+ days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
38
+ raise Payment::Invalid unless y.between?(1, 9999) && month.between?(1, 12) && day.between?(1, days[month - 1]) &&
39
+ hour.between?(0, 23) && minute.between?(0, 59) && second.between?(0, 59) && m[8] != "-00:00"
40
+ offset = 0
41
+ unless m[8] == "Z"
42
+ oh, om = m[8][1..].split(":").map(&:to_i)
43
+ raise Payment::Invalid unless oh <= 23 && om <= 59
44
+ offset = (oh * 3600 + om * 60) * (m[8][0] == "-" ? -1 : 1)
45
+ end
46
+ # Gregorian days relative to 0001-01-01, with fractional seconds exact.
47
+ before = y - 1
48
+ count = before * 365 + before / 4 - before / 100 + before / 400 + days.first(month - 1).sum + day - 1
49
+ fraction = m[7] ? Rational(m[7].to_i, 10**m[7].size) : 0
50
+ count * 86400 + hour * 3600 + minute * 60 + second - offset + fraction
51
+ end
52
+ def self.details!(value)
53
+ pisp!(value.fetch("pisp")); instant!(value.fetch("execution_date"))
54
+ end
55
+ def self.constraints!(opening)
56
+ cs = opening.fetch("constraints")
57
+ raise Payment::Invalid unless cs.instance_of?(Array) && cs.size.between?(5, 6) && cs.all? { |c| c.instance_of?(Hash) }
58
+ extra = cs.select { |c| TYPES.include?(c["type"]) }
59
+ raise Payment::Invalid unless extra.size.between?(1, 2) && extra.map { |c| c["type"] }.uniq.size == extra.size
60
+ extra.each do |c|
61
+ if c["type"] == TYPES[0]
62
+ Payment.send(:exact!, c, %w[type allowed])
63
+ list = c["allowed"]
64
+ raise Payment::Invalid unless list.instance_of?(Array) && list.size.between?(1, 8) && list.uniq.size == list.size
65
+ list.each { |p| pisp!(p) }
66
+ else
67
+ raise Payment::Invalid unless (c.keys - %w[type not_before not_after]).empty? &&
68
+ c.key?("type") && (c.key?("not_before") || c.key?("not_after"))
69
+ lower = instant!(c["not_before"]) if c.key?("not_before")
70
+ upper = instant!(c["not_after"]) if c.key?("not_after")
71
+ raise Payment::Invalid if lower && upper && lower > upper
72
+ end
73
+ end
74
+ pisp!(opening["pisp"]) if opening.key?("pisp")
75
+ instant!(opening["execution_date"]) if opening.key?("execution_date")
76
+ # Reject already contradictory fixed plans before any signer effects.
77
+ extra.each do |c|
78
+ if c["type"] == TYPES[0] && opening.key?("pisp")
79
+ raise Payment::Invalid unless c["allowed"].include?(opening["pisp"])
80
+ elsif c["type"] == TYPES[1] && opening.key?("execution_date")
81
+ instant = instant!(opening["execution_date"])
82
+ raise Payment::Invalid if c.key?("not_before") && instant < instant!(c["not_before"])
83
+ raise Payment::Invalid if c.key?("not_after") && instant > instant!(c["not_after"])
84
+ end
85
+ end
86
+ opening.reject { |k,_| FIELDS.include?(k) }.merge("constraints" => cs.reject { |c| TYPES.include?(c["type"]) })
87
+ end
88
+ def self.conditions!(opening, closed)
89
+ details!(closed)
90
+ FIELDS.each { |f| raise Payment::Invalid if opening.key?(f) && opening[f] != closed[f] }
91
+ opening.fetch("constraints").each do |c|
92
+ if c["type"] == TYPES[0]
93
+ raise Payment::Invalid unless c["allowed"].include?(closed["pisp"])
94
+ elsif c["type"] == TYPES[1]
95
+ instant = instant!(closed["execution_date"])
96
+ raise Payment::Invalid if c.key?("not_before") && instant < instant!(c["not_before"])
97
+ raise Payment::Invalid if c.key?("not_after") && instant > instant!(c["not_after"])
98
+ end
99
+ end
100
+ end
101
+ # Never fills either expected context from claims or expected_payment.
102
+ def self.context!(profile, trusted_pisp, execution_at)
103
+ unless enabled?(profile)
104
+ raise Payment::Invalid unless trusted_pisp.nil? && execution_at.nil?
105
+ return nil
106
+ end
107
+ pisp = InputBuilder.send(:copy!, trusted_pisp)
108
+ pisp!(pisp)
109
+ [ResearchEvidence.send(:copy_frozen, pisp), instant!(execution_at)].freeze
110
+ end
111
+ def self.bind_context!(value, context)
112
+ raise Payment::Invalid unless value.fetch("pisp") == context[0] && instant!(value.fetch("execution_date")) == context[1]
113
+ end
114
+ end
115
+ end
@@ -29,10 +29,11 @@ module AP2MandateVerifier
29
29
  def payment_rejected? = verified? && outcome == "Error"
30
30
  private_class_method :new
31
31
  end
32
- def self.reference(closed_sd_jwt:) = Payment.reference(closed_sd_jwt: closed_sd_jwt)
32
+ def self.reference(closed_sd_jwt:, profile_ref: Payment::PROFILE_REF) = Payment.reference(closed_sd_jwt: closed_sd_jwt, profile_ref: profile_ref)
33
33
  def self.sign(closed_sd_jwt:, issuer:, outcome:, payment_id:, issued_at:, signer:, public_key_pem:,
34
- psp_confirmation_id: nil, network_confirmation_id: nil, error: nil, error_description: nil)
35
- ref = reference(closed_sd_jwt: closed_sd_jwt)
34
+ psp_confirmation_id: nil, network_confirmation_id: nil, error: nil, error_description: nil,
35
+ profile_ref: Payment::PROFILE_REF)
36
+ ref = reference(closed_sd_jwt: closed_sd_jwt, profile_ref: profile_ref)
36
37
  claims = {"iss" => issuer, "status" => outcome, "payment_id" => payment_id, "iat" => issued_at, "reference" => ref}
37
38
  {"psp_confirmation_id" => psp_confirmation_id, "network_confirmation_id" => network_confirmation_id,
38
39
  "error" => error, "error_description" => error_description}.each { |k, v| claims[k] = v unless v.nil? }
@@ -41,13 +42,13 @@ module AP2MandateVerifier
41
42
  Signed.send(:new, MerchantSignature.sign!(claims, signer, public_key_pem), ref)
42
43
  end
43
44
  def self.verify(jwt:, closed_sd_jwt:, trusted_public_key_pem:, expected_issuer:, expected_payment_id:,
44
- not_before:, not_after:, verified_at:)
45
+ not_before:, not_after:, verified_at:, profile_ref: Payment::PROFILE_REF)
45
46
  [not_before, not_after, verified_at].each { |t| CheckoutReceipt.send(:epoch!, t) }
46
47
  raise Invalid unless not_before <= verified_at && verified_at <= not_after
47
48
  expected = InputValidator.snapshot!(expected_issuer, max_bytes: 512)
48
49
  id = InputValidator.snapshot!(expected_payment_id, max_bytes: 512)
49
50
  text!(expected, 512); text!(id, 512)
50
- ref = reference(closed_sd_jwt: closed_sd_jwt)
51
+ ref = reference(closed_sd_jwt: closed_sd_jwt, profile_ref: profile_ref)
51
52
  claims = RootSignature.verified_payload!(jwt, trusted_public_key_pem, expected_typ: "JWT", max_bytes: 16_384)
52
53
  validate!(claims)
53
54
  raise Invalid unless claims["iss"] == expected && claims["payment_id"] == id && claims["reference"] == ref &&
@@ -16,7 +16,9 @@ module AP2MandateVerifier
16
16
  # protected approval record. This confidential issuance MUST NOT be sent.
17
17
  def self.issue_open(open_checkout_sd_jwt:, constraints:, fixed:, approved_combinations:, selective:,
18
18
  agent_public_key_pem:, issued_at:, expires_at:, signer:, public_key_pem:,
19
- checkout_profile_ref: ScopedConstraints::MULTI_PROFILE_REF)
19
+ checkout_profile_ref: ScopedConstraints::MULTI_PROFILE_REF, profile_ref: PROFILE_REF, candidate_policy: nil)
20
+ profile_ref = PaymentPolicy.profile!(profile_ref, selective: true)
21
+ PaymentPolicy.candidate_policy!(profile_ref, candidate_policy)
20
22
  RootSignature.send(:dependencies!)
21
23
  raise Invalid unless %i[payees instruments both].include?(selective)
22
24
  checkout = Payment.send(:checkout_open!, open_checkout_sd_jwt, profile_ref: checkout_profile_ref)
@@ -24,10 +26,10 @@ module AP2MandateVerifier
24
26
  raise Invalid unless cs.instance_of?(Array)
25
27
  cs << {"type" => "payment.reference", "conditional_transaction_id" => digest(checkout)}
26
28
  value = InputBuilder.send(:copy!, fixed)
27
- raise Invalid unless value.instance_of?(Hash) && (value.keys - Payment::FIELDS.drop(1)).empty?
29
+ raise Invalid unless value.instance_of?(Hash) && (value.keys - PaymentPolicy.fields(profile_ref).drop(1)).empty?
28
30
  opening = value.merge("vct" => "mandate.payment.open.1", "iat" => issued_at, "exp" => expires_at,
29
31
  "cnf" => {"jwk" => RootSignature.public_jwk!(agent_public_key_pem)}, "constraints" => cs)
30
- Payment.send(:open!, opening)
32
+ Payment.send(:open!, opening, profile_ref: profile_ref)
31
33
  payees = constraint!(opening, "payment.allowed_payees").fetch("allowed")
32
34
  instruments = constraint!(opening, "payment.allowed_payment_instruments").fetch("allowed")
33
35
  pairs = InputBuilder.send(:copy!, approved_combinations)
@@ -47,18 +49,19 @@ module AP2MandateVerifier
47
49
  end
48
50
  content = []
49
51
  pointer = disclose!(opening, content)
50
- payload = {"ap2_profile" => PROFILE_REF, "_sd_alg" => "sha-256", "delegate_payload" => [pointer]}
52
+ payload = {"ap2_profile" => profile_ref, "_sd_alg" => "sha-256", "delegate_payload" => [pointer]}
51
53
  preview = [encode({"alg" => "ES256", "typ" => "example+sd-jwt"}), encode(payload), encode("\0" * 64)].join(".")
52
54
  wire = ([preview] + content + disclosures + [""]).join("~")
53
- parse!(wire, complete: true) # Full wire/disclosure bounds BEFORE signer effects.
55
+ parse!(wire, complete: true, profile_ref: profile_ref) # Full wire/disclosure bounds BEFORE signer effects.
54
56
  jwt = MerchantSignature.sign!(payload, signer, public_key_pem, typ: "example+sd-jwt")
55
57
  ([jwt] + content + disclosures + [""]).join("~").freeze
56
58
  end
57
59
 
58
60
  # Each selective index selects one original signed candidate slot. For an
59
61
  # inline/nonselective axis, pass nil: every approved inline value is visible.
60
- def self.select(open_sd_jwt:, payee_index:, instrument_index:)
61
- parsed = parse!(open_sd_jwt, complete: true)
62
+ def self.select(open_sd_jwt:, payee_index:, instrument_index:, profile_ref: PROFILE_REF)
63
+ profile_ref = PaymentPolicy.profile!(profile_ref, selective: true)
64
+ parsed = parse!(open_sd_jwt, complete: true, profile_ref: profile_ref)
62
65
  keep = [parsed.fetch(:content_digest)]
63
66
  {"payment.allowed_payees" => payee_index, "payment.allowed_payment_instruments" => instrument_index}.each do |type, index|
64
67
  c = constraint!(parsed.fetch(:original), type)
@@ -74,42 +77,47 @@ module AP2MandateVerifier
74
77
  end
75
78
  end
76
79
  wire = ([parsed.fetch(:compact)] + parsed.fetch(:disclosures).select { |d| keep.include?(digest(d)) } + [""]).join("~")
77
- parse!(wire, complete: false)
80
+ parse!(wire, complete: false, profile_ref: profile_ref)
78
81
  wire.freeze
79
82
  end
80
83
 
81
84
  def self.issue_closed(open_presentation:, payment:, trusted_provider_public_key_pem:, agent_public_key_pem:,
82
- audience:, nonce:, verified_at:, signer:)
85
+ audience:, nonce:, verified_at:, signer:, profile_ref: PROFILE_REF)
86
+ profile_ref = PaymentPolicy.profile!(profile_ref, selective: true)
83
87
  agent = InputValidator.snapshot!(agent_public_key_pem, max_bytes: 1_024)
84
88
  provider = InputValidator.snapshot!(trusted_provider_public_key_pem, max_bytes: 1_024)
85
89
  aud = InputValidator.snapshot!(audience, max_bytes: 512)
86
90
  challenge = InputValidator.snapshot!(nonce, max_bytes: 512)
87
- parsed = authenticated!(open_presentation, provider)
91
+ parsed = authenticated!(open_presentation, provider, profile_ref: profile_ref)
88
92
  opening = parsed.fetch(:opening)
89
93
  Payment.send(:valid_now!, opening, verified_at)
90
94
  raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(agent)}
91
- closed = Payment.send(:copy_details!, payment).merge("vct" => "mandate.payment.1", "iat" => verified_at, "exp" => opening.fetch("exp"))
92
- Payment.send(:closed!, closed); Payment.send(:conditions!, opening, closed)
95
+ closed = Payment.send(:copy_details!, payment, profile_ref: profile_ref).merge("vct" => "mandate.payment.1", "iat" => verified_at, "exp" => opening.fetch("exp"))
96
+ Payment.send(:closed!, closed, profile_ref: profile_ref); Payment.send(:conditions!, opening, closed, profile_ref: profile_ref)
93
97
  Payment.send(:text!, aud, 512); Payment.send(:text!, challenge, 512)
94
98
  claims = {"delegate_payload" => [closed], "iat" => verified_at, "aud" => aud, "nonce" => challenge,
95
99
  "sd_hash" => digest(parsed.fetch(:wire))}
96
- Payment.send(:preflight!, claims, "kb+sd-jwt")
100
+ claims["ap2_profile"] = profile_ref if PaymentPolicy.enabled?(profile_ref)
101
+ Payment.send(:preflight!, claims, "kb+sd-jwt", profile_ref: profile_ref)
97
102
  terminal = MerchantSignature.sign!(claims, signer, agent, typ: "kb+sd-jwt")
98
103
  Payment::Presentation.send(:new, parsed.fetch(:wire), terminal + "~")
99
104
  end
100
105
 
101
106
  # Structural restoration only. It never authenticates a stored presentation.
102
- def self.present(open_presentation:, closed_sd_jwt:)
103
- root = parse!(open_presentation, complete: false)
104
- terminal, wire = Payment.send(:final!, closed_sd_jwt, conditional: true)
107
+ def self.present(open_presentation:, closed_sd_jwt:, profile_ref: PROFILE_REF)
108
+ profile_ref = PaymentPolicy.profile!(profile_ref, selective: true)
109
+ root = parse!(open_presentation, complete: false, profile_ref: profile_ref)
110
+ terminal, wire = Payment.send(:final!, closed_sd_jwt, conditional: true, profile_ref: profile_ref)
105
111
  closed = terminal.fetch("delegate_payload").first
106
- bind_terminal!(root, terminal, closed)
112
+ bind_terminal!(root, terminal, closed, profile_ref: profile_ref)
107
113
  Payment::Presentation.send(:new, root.fetch(:wire), wire)
108
114
  end
109
115
 
110
116
  def self.verify(open_presentation:, closed_sd_jwt:, checkout_inputs:, expected_payment:,
111
117
  trusted_provider_public_key_pem:, expected_agent_public_key_pem:,
112
- expected_audience:, expected_nonce:, verified_at:)
118
+ expected_audience:, expected_nonce:, verified_at:, profile_ref: PROFILE_REF, trusted_pisp: nil, execution_at: nil)
119
+ profile_ref = PaymentPolicy.profile!(profile_ref, selective: true)
120
+ context = PaymentPolicy.context!(profile_ref, trusted_pisp, execution_at)
113
121
  CheckoutReceipt.send(:epoch!, verified_at)
114
122
  agent = InputValidator.snapshot!(expected_agent_public_key_pem, max_bytes: 1_024)
115
123
  provider = InputValidator.snapshot!(trusted_provider_public_key_pem, max_bytes: 1_024)
@@ -123,7 +131,7 @@ module AP2MandateVerifier
123
131
  [key, key == :verified_at ? value : InputValidator.snapshot!(value, max_bytes: limits.fetch(key, 131_072))]
124
132
  end.freeze
125
133
  raise Invalid unless inputs.size == fields.size && fields.all? { |f| inputs.key?(f) } && inputs[:verified_at] == verified_at
126
- expected = Payment.send(:copy_details!, expected_payment)
134
+ expected = Payment.send(:copy_details!, expected_payment, profile_ref: profile_ref)
127
135
  checkout = AP2MandateVerifier.verify_checkout(**inputs)
128
136
  raise Invalid unless checkout.success?
129
137
  raise Invalid unless expected.fetch("transaction_id") == digest(inputs.fetch(:host_checkout_jws))
@@ -132,39 +140,40 @@ module AP2MandateVerifier
132
140
  raise Invalid unless expected.fetch("payee").fetch("id") == binding.fetch("merchant_id") &&
133
141
  amount.fetch("currency") == binding.fetch("currency") && amount.fetch("amount") == binding.fetch("expected_total")
134
142
  Payment.send(:bind_checkout!, expected, Payment.send(:jwt_payload!, inputs.fetch(:host_checkout_jws), "JWT"))
135
- parsed = authenticated!(open_presentation, provider)
143
+ parsed = authenticated!(open_presentation, provider, profile_ref: profile_ref)
136
144
  opening = parsed.fetch(:opening)
137
145
  Payment.send(:valid_now!, opening, verified_at)
138
146
  raise Invalid unless opening.fetch("cnf") == {"jwk" => RootSignature.public_jwk!(agent)}
139
- terminal, wire = Payment.send(:final!, closed_sd_jwt, conditional: true)
147
+ terminal, wire = Payment.send(:final!, closed_sd_jwt, conditional: true, profile_ref: profile_ref)
140
148
  RootSignature.verified_payload!(wire.split("~", -1).first, agent,
141
149
  expected_typ: "kb+sd-jwt", max_bytes: 32_768)
142
150
  Payment.send(:text!, aud, 512); Payment.send(:text!, nonce, 512)
143
151
  raise Invalid unless terminal.fetch("aud") == aud && terminal.fetch("nonce") == nonce &&
144
152
  terminal.fetch("iat") <= verified_at && verified_at - terminal.fetch("iat") <= 300
145
153
  closed = terminal.fetch("delegate_payload").first
146
- bind_terminal!(parsed, terminal, closed)
154
+ bind_terminal!(parsed, terminal, closed, profile_ref: profile_ref)
147
155
  Payment.send(:valid_now!, closed, verified_at)
148
156
  ref = constraint!(opening, "payment.reference").fetch("conditional_transaction_id")
149
- raise Invalid unless ref == digest(inputs.fetch(:root_presentation)) && closed.slice(*Payment::FIELDS) == expected
157
+ PaymentPolicy.bind_context!(closed, context) if context
158
+ raise Invalid unless ref == digest(inputs.fetch(:root_presentation)) && closed.slice(*PaymentPolicy.fields(profile_ref)) == expected
150
159
  Payment::Verification.send(:new, closed, wire)
151
160
  rescue StandardError, LoadError
152
161
  Payment::Verification.send(:new)
153
162
  end
154
163
 
155
- def self.bind_terminal!(root, terminal, closed)
164
+ def self.bind_terminal!(root, terminal, closed, profile_ref: PROFILE_REF)
156
165
  opening = root.fetch(:opening)
157
- Payment.send(:closed!, closed)
166
+ Payment.send(:closed!, closed, profile_ref: profile_ref)
158
167
  raise Invalid unless terminal.fetch("sd_hash") == digest(root.fetch(:wire)) && terminal.fetch("iat") == closed.fetch("iat") &&
159
168
  closed.fetch("iat") >= opening.fetch("iat") && closed.fetch("exp") <= opening.fetch("exp")
160
- Payment.send(:conditions!, opening, closed)
169
+ Payment.send(:conditions!, opening, closed, profile_ref: profile_ref)
161
170
  end
162
- def self.authenticated!(wire, key)
163
- parsed = parse!(wire, complete: false)
171
+ def self.authenticated!(wire, key, profile_ref: PROFILE_REF)
172
+ parsed = parse!(wire, complete: false, profile_ref: profile_ref)
164
173
  RootSignature.verified_payload!(parsed.fetch(:compact), key, max_bytes: 16_384)
165
174
  parsed
166
175
  end
167
- def self.parse!(source, complete:)
176
+ def self.parse!(source, complete:, profile_ref: PROFILE_REF)
168
177
  RootSignature.send(:dependencies!)
169
178
  wire = InputValidator.snapshot!(source, max_bytes: MAX_WIRE)
170
179
  raise Invalid unless wire.ascii_only? && wire.end_with?("~")
@@ -174,7 +183,7 @@ module AP2MandateVerifier
174
183
  compact = InputValidator.snapshot!(compact, max_bytes: 16_384)
175
184
  claims = Payment.send(:jwt_payload!, compact, "example+sd-jwt")
176
185
  Payment.send(:exact!, claims, %w[ap2_profile _sd_alg delegate_payload])
177
- raise Invalid unless claims["ap2_profile"] == PROFILE_REF && claims["_sd_alg"] == "sha-256" &&
186
+ raise Invalid unless claims["ap2_profile"] == profile_ref && claims["_sd_alg"] == "sha-256" &&
178
187
  claims["delegate_payload"].instance_of?(Array) && claims["delegate_payload"].size == 1
179
188
  pointer = claims.fetch("delegate_payload").first
180
189
  Payment.send(:exact!, pointer, ["..."])
@@ -218,7 +227,7 @@ module AP2MandateVerifier
218
227
  end
219
228
  raise Invalid if slots.values.all?(&:empty?)
220
229
  raise Invalid unless used.sort == values.keys.sort
221
- Payment.send(:open!, opening) # Only candidate markers were resolved/omitted.
230
+ Payment.send(:open!, opening, profile_ref: profile_ref) # Only candidate markers were resolved/omitted.
222
231
  {wire: wire, compact: compact, disclosures: disclosures, opening: opening,
223
232
  original: original, content_digest: content_digest, slots: slots, values: values}
224
233
  end
@@ -19,6 +19,7 @@ require_relative "ap2_mandate_verifier/payment"
19
19
  require_relative "ap2_mandate_verifier/payment_receipt"
20
20
  require_relative "ap2_mandate_verifier/selective_payment"
21
21
  require_relative "ap2_mandate_verifier/selective_checkout"
22
+ require_relative "ap2_mandate_verifier/payment_policy"
22
23
 
23
24
  module AP2MandateVerifier
24
25
  # 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: 1.3.0
4
+ version: 1.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AP2 Mandate Verifier contributors
@@ -83,8 +83,8 @@ description: 'Framework-independent Ruby SDK for supported AP2 Checkout profiles
83
83
  Merchant JWT signing, Direct and conditional Mandate issuance and presentation,
84
84
  full verification with immutable Evidence, Checkout Receipts, Direct and conditional
85
85
  Payment Mandates, and Payment Receipts. Adds opt-in selective Checkout and Payment
86
- candidate disclosure. Requires independently trusted application inputs; verification
87
- does not grant purchase or payment permission.'
86
+ disclosure plus explicit PISP and execution-date constraints. Requires independently
87
+ trusted application inputs; verification does not grant purchase or payment permission.'
88
88
  executables: []
89
89
  extensions: []
90
90
  extra_rdoc_files: []
@@ -101,6 +101,7 @@ files:
101
101
  - docs/MERCHANT_SIGNING.md
102
102
  - docs/MULTI_ITEM_CHECKOUT.md
103
103
  - docs/PAYMENT.md
104
+ - docs/PAYMENT_POLICY.md
104
105
  - docs/POST_RELEASE_110.md
105
106
  - docs/POST_RELEASE_MAINTENANCE.md
106
107
  - docs/PUBLIC_API.md
@@ -108,12 +109,14 @@ files:
108
109
  - docs/RELEASE_110_CANDIDATE.md
109
110
  - docs/RELEASE_120_CANDIDATE.md
110
111
  - docs/RELEASE_130_CANDIDATE.md
112
+ - docs/RELEASE_140_CANDIDATE.md
111
113
  - docs/SELECTIVE_CHECKOUT.md
112
114
  - docs/SELECTIVE_PAYMENT.md
113
115
  - docs/SUPPORT_CONTRACT.md
114
116
  - docs/evidence/1.1.0_publication.json
115
117
  - examples/conditional_checkout.rb
116
118
  - examples/payment.rb
119
+ - examples/payment_policy.rb
117
120
  - examples/selective_checkout.rb
118
121
  - examples/selective_checkout_payment.rb
119
122
  - examples/selective_payment.rb
@@ -128,6 +131,7 @@ files:
128
131
  - lib/ap2_mandate_verifier/input_validator.rb
129
132
  - lib/ap2_mandate_verifier/merchant_signature.rb
130
133
  - lib/ap2_mandate_verifier/payment.rb
134
+ - lib/ap2_mandate_verifier/payment_policy.rb
131
135
  - lib/ap2_mandate_verifier/payment_receipt.rb
132
136
  - lib/ap2_mandate_verifier/purchase_binding.rb
133
137
  - lib/ap2_mandate_verifier/research_result.rb