ap2_mandate_verifier 1.5.0 → 1.6.1

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.
Files changed (40) hide show
  1. checksums.yaml +4 -4
  2. data/README.ja.md +95 -172
  3. data/README.md +119 -199
  4. data/SECURITY.md +7 -3
  5. data/docs/LONG_PAYMENT.md +84 -0
  6. data/docs/PAYMENT_ACCEPTANCE.md +8 -1
  7. data/docs/PUBLIC_API.md +10 -2
  8. data/docs/RECURRING_PAYMENT.md +56 -0
  9. data/docs/RELEASE_150_CANDIDATE.md +2 -0
  10. data/docs/RELEASE_160_CANDIDATE.md +30 -0
  11. data/docs/RELEASE_161_CANDIDATE.md +30 -0
  12. data/docs/RUBY_INTEGRATION.ja.md +204 -0
  13. data/docs/RUBY_INTEGRATION.md +222 -0
  14. data/docs/SUPPORT_CONTRACT.md +19 -2
  15. data/examples/conditional_checkout.rb +3 -3
  16. data/examples/integration/inputs.rb +169 -0
  17. data/examples/integration/processor.rb +39 -0
  18. data/examples/long_payment.rb +116 -0
  19. data/examples/long_payment_acceptance.rb +89 -0
  20. data/examples/recurring_payment.rb +99 -0
  21. data/examples/ruby_integration.rb +161 -0
  22. data/lib/ap2_mandate_verifier/checkout_jwt.rb +1 -1
  23. data/lib/ap2_mandate_verifier/checkout_receipt.rb +10 -1
  24. data/lib/ap2_mandate_verifier/conditional_checkout.rb +43 -19
  25. data/lib/ap2_mandate_verifier/input_builder.rb +1 -1
  26. data/lib/ap2_mandate_verifier/long_payment.rb +201 -0
  27. data/lib/ap2_mandate_verifier/payment.rb +52 -12
  28. data/lib/ap2_mandate_verifier/payment_acceptance/long_sqlite_store.rb +272 -0
  29. data/lib/ap2_mandate_verifier/payment_acceptance/recurring_sqlite_store.rb +124 -0
  30. data/lib/ap2_mandate_verifier/payment_acceptance/sqlite_store.rb +38 -10
  31. data/lib/ap2_mandate_verifier/payment_acceptance.rb +28 -6
  32. data/lib/ap2_mandate_verifier/payment_policy.rb +7 -2
  33. data/lib/ap2_mandate_verifier/purchase_binding.rb +11 -5
  34. data/lib/ap2_mandate_verifier/recurring_payment.rb +111 -0
  35. data/lib/ap2_mandate_verifier/root_disclosures.rb +9 -6
  36. data/lib/ap2_mandate_verifier/scoped_constraints.rb +1 -1
  37. data/lib/ap2_mandate_verifier/selective_payment.rb +1 -1
  38. data/lib/ap2_mandate_verifier/trust_context.rb +6 -0
  39. data/lib/ap2_mandate_verifier.rb +4 -0
  40. metadata +23 -6
data/README.md CHANGED
@@ -1,142 +1,131 @@
1
1
  # AP2 Mandate Verifier — Ruby SDK for Checkout and Payment
2
2
 
3
- ### 1.5.0 candidate: transactional Payment acceptance
3
+ [日本語](README.ja.md) · **Published stable: 1.6.0** · [Quick Start](docs/QUICK_START.md)
4
4
 
5
- Reserve a protected business occurrence atomically, reverify before one fenced start, and recover the original Receipt after response loss without reopening an uncertain attempt. This candidate is not published. [Integration/store/security contract](docs/PAYMENT_ACCEPTANCE.md), [plain Ruby recovery example](examples/payment_acceptance.rb), [release gates](docs/RELEASE_150_CANDIDATE.md).
5
+ Issue, present and verify supported AP2 Checkout and Payment Mandates in plain Ruby.
6
+ Use this Gem when your app needs to check what a buyer approved, what an Agent may
7
+ choose, and whether signed Checkout/Payment data stays within those conditions.
8
+ No Rails dependency. **Verification success is not purchase or payment success; the SDK never executes payments.**
6
9
 
7
- ```ruby
8
- accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
9
- dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inputs) if accepted.ticket
10
- # Application-owned processor call uses dispatch.processor_key; no SDK payment call.
11
- ```
12
-
13
- Verification, durable reservation and settlement are separate. Use protected enrollment, one authoritative store and processor idempotency/lookup; no automatic timeout release. Existing1.x verifiers remain unchanged. The optional SQLite reference driver is installed separately.
14
-
15
-
16
- ### Published1.4.0: PISP and execution-date Payment conditions
17
-
18
- Explicit Payment profiles now constrain approved PISPs and parsed inclusive execution windows, bound to independent application provider/time context. Existing1.x defaults remain unchanged. [Contract/API/official differences](docs/PAYMENT_POLICY.md), [plain Ruby three-mode example](examples/payment_policy.rb), [verified publication](docs/POST_RELEASE_140.md).
19
-
20
- ### Published 1.3.0: selective Checkout and Payment
21
-
22
- 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).
23
-
24
- ### Published1.2.0: selective Payment
25
-
26
- 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.
27
-
28
-
29
- ### Payment lifecycle (since1.1.0)
30
-
31
- 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.
32
-
33
- ```sh
34
- gem install ap2_mandate_verifier --version 1.4.0
35
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.4.0").full_gem_path')/examples/payment.rb"
36
- ```
37
-
38
- [日本語](README.ja.md)
39
-
40
- **Published stable: 1.4.0.**
41
-
42
- 1.0.0 establishes the stable public contract for the existing
43
- Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
44
- profiles, result meanings, saved formats and runtime implementation.
45
- See [the public API contract](docs/PUBLIC_API.md),
46
- [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and
47
- [1.0.0 release notes](docs/RELEASE_100.md). The official Gem matches the retained
48
- candidate; [publication verification](docs/POST_RELEASE_100.md) records its exact
49
- source, bytes and validation scope.
50
-
51
- ## Conditional purchase delegation
52
-
53
- Available since 0.8.0, `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`
54
- support this flow:
55
- approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
56
- a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
57
- `CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
58
- multi-item profile. Provider private keys never enter Agent operations.
59
- [API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [conditional code sample](docs/RELEASE_080.md) and [1.0.0 publication verification](docs/POST_RELEASE_100.md).
60
-
61
- Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
62
-
63
- ```sh
64
- gem install ap2_mandate_verifier --version 1.4.0
65
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.4.0").full_gem_path')/examples/conditional_checkout.rb"
66
- ```
67
-
68
- The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
69
- public APIs, three rows, candidate choice, different requirement quantities and
70
- repeated products through both Receipt outcomes. Success consumes the operation;
71
- Error requires a new policy decision; missing Receipt or uncertain effect remains
72
- pending. Authentication, consent, enrollment, durable replay prevention and actual
73
- order/payment execution remain app-owned. Documented 0.8.0 API use needs no source
74
- migration; update the dependency constraint as described below.
75
-
76
- Direct and conditional workflows cover one merchant and 1–8 Checkout lines,
77
- including multiple products and quantities. Existing Direct and both Open→Closed
78
- profiles retain their contracts in 1.0.0.
79
-
80
- ## Multiple items and quantities
81
-
82
- 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.
83
-
84
- The multi-item v1 profile supports one merchant, one checkout, one currency and up to eight lines, with different quantities and repeated product IDs on distinct lines. It matches all disclosed product candidates using integer maximum flow: every requirement and every ordered unit must be consumed exactly once. Quantity shortages and extras reject. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md), [synthetic runnable lifecycle](examples/multi_item_checkout.rb), and [official Python SDK differences](docs/MULTI_ITEM_INTEROP.md) for shortage, empty-candidate and Receipt-reference behavior.
85
-
86
- 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.**
87
-
88
- `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.
89
10
 
90
- ## Try the local demo
11
+ **Platforms:** MRI 3.4.12 / 4.0.9; native published-Gem checks passed on Linux ARM64/AMD64, macOS Intel/Apple Silicon and Windows Server 2022 X64. These observations cover the recorded OS images; Rails demo compatibility is separate. See [platform evidence and reproduction](docs/PLATFORM_SUPPORT.md).
91
12
 
92
- The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.8.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. It retains the existing synthetic Open→Agent Closed verification, multi-item and Success/Error Receipt screens. It has no conditional approval/issuance UI; use the standalone Ruby example above for that lifecycle. It is local-only and performs no real challenge issuance, nonce consumption or purchase/payment.
93
-
94
- ## Install
95
-
96
- Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
97
-
98
- ```sh
99
- gem install ap2_mandate_verifier --version 1.4.0
100
- ```
101
-
102
- Or add to your Gemfile:
103
-
104
- ```ruby
105
- gem "ap2_mandate_verifier", "~> 1.0"
106
- ```
107
-
108
- 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).
109
-
110
- ### Upgrading from 0.8.0
111
-
112
- Documented 0.8.0 APIs, profiles, defaults and saved formats remain compatible.
113
- A constraint such as `~> 0.8.0` excludes 1.0.0. Change it to `~> 1.0` as above and
114
- update this Gem in the application's lockfile:
13
+ ## Start here
115
14
 
116
15
  ```sh
117
- bundle update ap2_mandate_verifier
118
- ```
119
-
120
- ## Merchant signing and Receipt
121
-
122
- Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 1.0.0; the excerpt uses the default single-SKU profile.
123
- Here `checkout` is the application order Hash, `key` its P-256 signing key,
124
- `received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
125
-
126
- ```ruby
127
- signing = AP2MandateVerifier::CheckoutJWT
128
- signed = signing.sign(checkout: checkout, signer: signing.es256_signer(private_key: key),
129
- public_key_pem: key.public_to_pem)
130
- # Retain signed.jwt unchanged; use it as InputBuilder's host_checkout_jws.
131
- receipt = AP2MandateVerifier::CheckoutReceipt.sign(closed_sd_jwt: received_closed_sd_jwt,
132
- issuer: "shop", outcome: "Error", error: "declined", error_description: "Application declined",
133
- issued_at: now, signer: signing.es256_signer(private_key: key), public_key_pem: key.public_to_pem)
16
+ gem install ap2_mandate_verifier --version 1.6.0
17
+ AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.0").full_gem_path')"
18
+ ruby "$AP2_GEM_DIR/examples/conditional_checkout.rb"
19
+ ruby "$AP2_GEM_DIR/examples/payment.rb"
134
20
  ```
135
21
 
136
- Receipt verification separately checks a trusted public key, expected issuer,
137
- explicit time window and original closed-Mandate reference. An authentic Error
138
- Receipt has `verified? == true` and `purchase_succeeded? == false`.
139
- See the [complete runnable example](examples/merchant_signing.rb) and [API contract / SDK differences](docs/MERCHANT_SIGNING.md).
22
+ These installed examples create synthetic keys and approvals, issue/present/verify
23
+ Mandates, then authenticate alternative Success and Error Receipts. An authentic
24
+ Error Receipt reports failure. No account, credentials, database or Rails required.
25
+ Allow about ten minutes with a supported Ruby already installed; dependency builds
26
+ and Docker's first download can take longer.
27
+
28
+ **Next:** [step-by-step Quick Start and expected output](docs/QUICK_START.md),
29
+ including twelve UTC months and a cumulative JPY budget rejection.
30
+ [Docker demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)
31
+ uses published **1.6.0**, with local Checkout screens and Ruby Payment examples.
32
+
33
+ ## Choose a workflow
34
+
35
+ **Integrating a real application?** Start with the [Ruby integration and restart
36
+ recovery guide](docs/RUBY_INTEGRATION.md): protected application inputs, persistent
37
+ mock results, separate-process recovery and safe retry decisions. Use this repository
38
+ with published 1.6.0, or the bundled CLI in the 1.6.1 candidate. Public 1.6.0 does
39
+ not include this CLI; verify the 1.6.1 publication status before treating a candidate
40
+ as a registry release.
41
+
42
+ Checkout describes the order; a Checkout Mandate records approval/delegation for it.
43
+ A Payment Mandate adds payment conditions and references the Checkout approval.
44
+ Receipts authenticate an application's reported outcome for the original final Mandate;
45
+ they do not independently prove settlement.
46
+
47
+ | Workflow | Use when | API / guide |
48
+ | --- | --- | --- |
49
+ | Direct | Buyer approves an exact signed order/payment | `Buyer`, `Payment.issue_direct` · [Checkout](docs/BUYER_DIRECT_CHECKOUT.md) / [Payment](docs/PAYMENT.md) |
50
+ | Conditional delegation | Buyer approves candidates and limits; registered Agent chooses within them | `ConditionalCheckout`, `Payment.issue_open/issue_closed/present` · [Checkout](docs/CONDITIONAL_CHECKOUT.md) |
51
+ | Selective disclosure | Keep the full approved Open private and send selected merchant/product or payee/instrument candidates | `SelectiveCheckout`, `SelectivePayment` · [Checkout](docs/SELECTIVE_CHECKOUT.md) / [Payment](docs/SELECTIVE_PAYMENT.md) |
52
+ | Long Open | Reuse one approved Checkout/Payment Open pair across explicit UTC months, with finite count and cumulative JPY budget | `LongPayment`, `PaymentAcceptance::LongSQLiteStore` · [contract](docs/LONG_PAYMENT.md) |
53
+
54
+ Direct and conditional Checkout support one merchant and up to eight lines with
55
+ quantities under the explicit multi-item profile. The default single-SKU profile
56
+ retains its one-line contract. Selective profiles retain all mandatory conditions
57
+ and quantities; candidate count/order and issuer-JWT linkability are not hidden.
58
+ Long Open is a separate complete-disclosure profile (content up to 400 days,
59
+ short-lived proofs); it does not compose with selective or PISP/date profiles.
60
+ **Its UTC-monthly profile is not full compliance with generic AP2 MONTHLY semantics.**
61
+
62
+ Other explicit options: [PISP / execution-date constraints](docs/PAYMENT_POLICY.md),
63
+ [transactional acceptance and recovery](docs/PAYMENT_ACCEPTANCE.md), and bounded
64
+ [ON_DEMAND count / JPY budget profiles](docs/RECURRING_PAYMENT.md).
65
+ Existing 1.x API signatures, defaults, profiles and saved formats remain supported.
66
+
67
+ ## Choose your API by role
68
+
69
+ | Your component | Start with |
70
+ | --- | --- |
71
+ | Merchant backend | `CheckoutJWT.sign`; `CheckoutReceipt.sign/verify` |
72
+ | Trusted approval backend | `CheckoutJWT.verify` before consent; `Buyer.issue_closed` or `ConditionalCheckout.issue_open`; corresponding Payment issuance |
73
+ | Registered Agent | `Buyer.present_closed`, or conditional `issue_closed/present`; selective variants for supported disclosure profiles. Provider private keys stay in the approval backend. |
74
+ | Merchant / payment verifier | `Buyer.verify` for Direct; `InputBuilder.prepare/restore/verify` for conditional Checkout; `Payment.verify` for Payment plus Checkout binding; explicit selective/long variants |
75
+ | Receipt consumer | `CheckoutReceipt.verify`, `PaymentReceipt.verify`; check authenticity **and** reported outcome |
76
+ | App managing durable Payment acceptance | `PaymentAcceptance::Service` and the appropriate protected store; [integration contract](docs/PAYMENT_ACCEPTANCE.md) |
77
+
78
+ `verify_checkout` (also `verify_research`) is the complete seven-input conditional
79
+ Checkout entry. `InputBuilder` is the recommended business-record adapter.
80
+ Legacy `verify(presentation_json:)` checks syntax only and never returns successful
81
+ Evidence. [Exact APIs and result/error conventions](docs/PUBLIC_API.md).
82
+
83
+ ## Install and support
84
+
85
+ Formal support: **MRI 3.4.12 and 4.0.9**. For this walkthrough use
86
+ `gem "ap2_mandate_verifier", "= 1.6.0"` in a Gemfile. Applications following stable
87
+ 1.x may use `"~> 1.0"` and review lockfile updates. `~> 0.8.0` excludes 1.x;
88
+ [upgrade notes](docs/RELEASE_100.md) retain the compatibility details.
89
+
90
+ Runtime pins: JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2,
91
+ Digest 3.2.1. Installation may download/build native dependencies. Do not loosen
92
+ pins to bypass a conflict. The resolution interval does not certify every Ruby,
93
+ OS or provider. [Support contract](docs/SUPPORT_CONTRACT.md).
94
+
95
+ ## Responsibilities before using this in your app
96
+
97
+ The core verifier performs no network or payment operations. Optional acceptance
98
+ stores perform local database transactions; SQLite requires a separately installed
99
+ driver. **Verification, durable reservation, application authorization and settlement
100
+ are separate events.**
101
+
102
+ Your app owns authentication, consent, protected approval records, independently
103
+ trusted current keys/revocation/profile policy, order/challenge state and clock.
104
+ It must recheck current authority, durably consume one-use state atomically, handle
105
+ uncertain results, and decide whether to call a processor. SDK acceptance and
106
+ Receipt authentication do not establish real Issuer trust or processor exactly-once.
107
+ Missing/invalid Receipt or unknown effect stays pending for reconciliation; do not
108
+ automatically retry or refund allowance on timeout/Error.
109
+
110
+ Unknown/unsupported forms fail closed. Exceptions, unavailable results and missing
111
+ results never authorize an operation. Do not log private keys, raw Mandates/nonces
112
+ or treat serialized Evidence as an authenticated credential. General AP2/all-Schema
113
+ conformance, real-Issuer interoperability and production GO are not claimed.
114
+ [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md),
115
+ [security policy](SECURITY.md), [acceptance boundaries](docs/PAYMENT_ACCEPTANCE.md).
116
+
117
+ ## Reference and retained evidence
118
+
119
+ - [Public API](docs/PUBLIC_API.md), [InputBuilder guide](docs/INPUT_BUILDER.md), [diagnostics](docs/DIAGNOSTICS.md).
120
+ - [1.6.0 publication verification](docs/POST_RELEASE_160.md), [changelog](CHANGELOG.md), [project/publication history](docs/PROJECT_STATUS.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md).
121
+ - [Merchant signing](docs/MERCHANT_SIGNING.md), [multiple items](docs/MULTI_ITEM_CHECKOUT.md), [Python differences](docs/MULTI_ITEM_INTEROP.md).
122
+
123
+ Historical release and research documents remain evidence for their recorded
124
+ versions, not the current onboarding path. Repository documentation changes do
125
+ not rebuild or replace the already published 1.6.0 Gem.
126
+
127
+ <details>
128
+ <summary>Source-checkout InputBuilder walkthrough (advanced)</summary>
140
129
 
141
130
  ## A small InputBuilder example
142
131
 
@@ -186,74 +175,5 @@ Expected for these unchanged synthetic inputs: `verified_research/scoped_researc
186
175
 
187
176
  Do not call `prepare` again during verification or update saved hashes/references to match current values. Changed orders, trust or signed bytes must remain detectable. Persisted trust JSON can be loaded with `restore_trust` without reserializing it. The [complete example](examples/input_builder.rb) includes normal/tampered/expired cases; the [input guide](docs/INPUT_BUILDER.md) explains the business fields, exact restoration and Rails model mapping.
188
177
 
189
- ## Results and responsibility boundaries
190
-
191
- The following table applies to complete Open → Agent Closed verification through
192
- InputBuilder or `verify_checkout`. Direct, Checkout and Receipt APIs retain their
193
- own `verified?` or exception contracts; see [all result conventions](docs/PUBLIC_API.md#result-object-and-failure-contracts).
194
-
195
- | Result | Meaning and next step |
196
- | --- | --- |
197
- | `:verified_research` / `:scoped_research_verified`, `success? == true` | Immutable Evidence contains checked facts for the fixed profile. The Host must still decide whether to authorize the purchase. |
198
- | `:rejected`, `rejected? == true` | No Evidence. Stop and inspect `result.code`. |
199
- | `:unavailable`, `unavailable? == true` | No Evidence. Stop; a dependency or processing failure is not proof of invalid business data. |
200
-
201
- On failure, inspect supplemental check candidates. Successful results have no failure diagnostic.
202
-
203
- ```ruby
204
- if (diagnostic = result.diagnostic)
205
- puts diagnostic.to_h(locale: :en) # :ja for Japanese
206
- end
207
- ```
208
-
209
- `stage / field / reason / hint` are guidance; they do not change status/code or the verdict. Unknown fields/causes are not asserted. See the [diagnostic guide](docs/DIAGNOSTICS.md).
210
-
211
- Exceptions, process failure and missing results also never authorize an operation. Do not log raw inputs/nonces or treat serialized Evidence as an authenticated credential.
212
178
 
213
- 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.
214
-
215
- Published 1.0.0 retains the default `ap2.checkout.single_merchant_sku` v1 and the
216
- explicit [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Conditional issuance
217
- uses that multi-item profile, with all candidates disclosed and existing limits.
218
- Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer
219
- interoperability, new selective-disclosure profiles, Rails adapters, DB/payment
220
- execution and numeric performance guarantees remain outside scope. Real
221
- Issuer/Host production GO and Phase 2-B remain separate HOLDs.
222
-
223
- ### Which API should I use?
224
-
225
- | Entry | Role |
226
- | --- | --- |
227
- | `ConditionalCheckout.issue_open/issue_closed/present` | Conditional issuance and original-wire presentation; full merchant verification remains required. |
228
- | `Buyer.issue_closed/present_closed/verify` | Direct exact-order issuance, structural presentation and full Direct verification. |
229
- | `CheckoutJWT.sign/verify` | Merchant Checkout signing and authentication before approval. |
230
- | `CheckoutReceipt.reference/sign/verify` | Original final-Mandate reference, explicit application outcome signing and Receipt authentication. |
231
- | `InputBuilder.verify(**business_information)` | Recommended business-data path. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
232
- | `verify_checkout(**inputs)` | Complete Open → Agent Closed verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
233
- | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
234
- | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
235
-
236
- Malformed assembly arguments, including missing keywords, to `InputBuilder.verify` return `:rejected / :invalid_host_context`. Assembly dependency/unexpected failures return `:unavailable / :research_verification_unavailable`; results from the complete core retain their codes. In contrast, missing/unknown keywords to the direct `verify_checkout` / `verify_research` entries return `:unavailable / :research_verification_unavailable`. Every such failure has `success? == false` and `evidence == nil`. See [the exact contract](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs) for shapes, bounds and Ruby argument-binding caveats.
237
-
238
- ## More detail
239
-
240
- - [1.x public API, errors, profiles and persistence contract](docs/PUBLIC_API.md). Existing partial-verification APIs remain supported and never return successful Evidence.
241
- - [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).
242
- - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
243
- - [1.0.0 Release notes](docs/RELEASE_100.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
244
- - [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.
245
- - [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.
246
-
247
- MIT. See [LICENSE](LICENSE).
248
-
249
- ### Buyer Direct checkout (published 0.7.0)
250
-
251
- Trusted Surface backends can verify a merchant Checkout before approval, issue a
252
- Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
253
- `AP2MandateVerifier::Buyer` module verifies Direct Closed-only presentations at
254
- the merchant and uses `CheckoutReceipt` with `profile_ref: Buyer::PROFILE_REF`.
255
- One merchant, 1–8 lines, multiple products and quantities are supported end to end.
256
- Existing Open→Agent Closed APIs and both profiles retain their contracts.
257
- See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
258
- [runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
259
- is not purchasing authority or payment success. See the [short verified buyer-flow sample](docs/RELEASE_070.md).
179
+ </details>
data/SECURITY.md CHANGED
@@ -1,10 +1,14 @@
1
1
  # Security policy / 脆弱性の報告
2
2
 
3
+ ## 1.6.0 candidate boundary
4
+
5
+ The unpublished1.6.0 candidate adds bounded ON_DEMAND and separate explicit [long JPY/UTC-month profiles](docs/LONG_PAYMENT.md). Mandatory count/budget constraints remain visible; historical quota and current authority are enforced only by the protected atomic acceptance adapter. Long content up to400days is separate from short proof/start validity. External registry freshness/provenance and synchronization, consent, one authoritative ledger, current order/nonce CAS and processor reconciliation remain application responsibilities. No automatic revocation feed, refund, retry execution or settlement is supplied. Old short profiles remain unchanged.
6
+
3
7
  ## 現在の対象と限界 / Current scope
4
8
 
5
- [Published 1.4.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/1.4.0) is a framework-independent Ruby SDK for the documented AP2 Checkout profiles, including Direct/conditional Checkout and Payment, selective disclosure, PISP/date conditions and Receipt confirmation. See [publication evidence](docs/POST_RELEASE_140.md), the stable [PUBLIC_API](docs/PUBLIC_API.md) and [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for its scope and limitations.
9
+ [Published 1.5.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/1.5.0) is a framework-independent Ruby SDK for the documented AP2 Checkout profiles, including Direct/conditional Checkout and Payment, selective disclosure, PISP/date conditions and Receipt confirmation. See [publication evidence](docs/POST_RELEASE_150.md), the stable [PUBLIC_API](docs/PUBLIC_API.md) and [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for its scope and limitations.
6
10
 
7
- 現在の配布版は、対応profileのDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を備えた、フレームワーク非依存のRuby SDK **1.4.0**です。1.xの保守対象は最新マイナー系列の最新修正版のみとし、旧マイナー・0.x・preへのbackportは約束しません。現行版の報告窓口は以下のままです。保守対象・互換性・セキュリティ修正の扱いは[公開後の整備](docs/POST_RELEASE_MAINTENANCE.md)を参照してください。
11
+ 現在の配布版は、対応profileのDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を備えた、フレームワーク非依存のRuby SDK **1.5.0**です。1.xの保守対象は最新マイナー系列の最新修正版のみとし、旧マイナー・0.x・preへのbackportは約束しません。現行版の報告窓口は以下のままです。保守対象・互換性・セキュリティ修正の扱いは[公開後の整備](docs/POST_RELEASE_MAINTENANCE.md)を参照してください。
8
12
 
9
13
  The 1.x policy covers only the latest patch of the latest 1.x minor series; older minors, 0.x and prereleases carry no backport promise. Existing reporting routes below remain available for the current release. See [maintenance and compatibility](docs/POST_RELEASE_MAINTENANCE.md). The pre.3, 0.1.0 candidate and R2 statements below are historical records of those stages, not the current release status.
10
14
 
@@ -12,7 +16,7 @@ Evidence is not Host ALLOW or payment permission. Real Issuer trust, specific Ho
12
16
 
13
17
  EvidenceはHost ALLOW・決済許可ではありません。実Issuer信頼、特定Host本番GO、Phase 2-BはHOLDを維持し、一般AP2/全Schema・Phase2-A全面PASS・最悪資源/並行性能・native/runtime全面安全性は未証明です。SLA・固定保守年数・受付/修正期限は約束せず、既存のprovider/JSON勧告metadata・通信会計の限界を保持します。本記録は新たな実行・変更・公開を許可しません。
14
18
 
15
- 1.5.0 is an unpublished opt-in acceptance/idempotency candidate. Its store coordinates protected business occurrences and one start handle; it does not change existing verifier/Host authority contracts or prove external exactly-once/settlement. Store adapters, current authority/order/nonce CAS, filesystem/database recovery and processor lookup/idempotency require application guarantees. No memory fallback or timeout-based re-execution is safe. See [the candidate contract](docs/PAYMENT_ACCEPTANCE.md).
19
+ Published1.5.0 adds opt-in acceptance/idempotency support. Its store coordinates protected business occurrences and one start handle; it does not change existing verifier/Host authority contracts or prove external exactly-once/settlement. Store adapters, current authority/order/nonce CAS, filesystem/database recovery and processor lookup/idempotency require application guarantees. No memory fallback or timeout-based re-execution is safe. See [the acceptance contract](docs/PAYMENT_ACCEPTANCE.md).
16
20
 
17
21
  ## 歴史記録:pre.3の対象と限界 / Historical pre.3 scope
18
22
 
@@ -0,0 +1,84 @@
1
+ # Long Open Payment: explicit JPY / UTC monthly profile (1.6.0)
2
+
3
+ Published on RubyGems; [exact distribution and validation](POST_RELEASE_160.md). Packaged preparation notes retain their historical scope.
4
+
5
+ `LongPayment` supports one signed Open Checkout and one signed Open Payment reused across approved UTC calendar months. Every Closed preserves its own Open's content `iat`/`exp`; each outer KB proof is fresh, bound to audience/nonce/original presentation. Content validity and permission to start execution are separate. This is a framework-independent Ruby SDK; no Rails, scheduler or payment processor is required or invoked.
6
+
7
+ ## Scope and official boundary
8
+
9
+ - Explicit profiles: `LongPayment::CHECKOUT_PROFILE_REF` (`ap2.checkout.long_open.multi_item.1`) and `PROFILE_REF` (`ap2.payment.long_open.jpy_monthly.complete.1`). Complete disclosure, one merchant, integer JPY, mandatory finite occurrence cap and cumulative budget, `MONTHLY` with the Host policy below. All mandatory conditions are visible.
10
+ - Content lifetime is bounded to400days by this profile. Old Payment/Buyer profiles retain600seconds, old conditional Checkout7200seconds, old default APIs/results/formats and the seven-input Checkout contract remain unchanged. New signed markers and independently registered Host profile/hash prevent implicit selection or downgrade.
11
+ - No long selective disclosure, PISP/execution-date combination, non-JPY budget, generic recurrence, catch-up, refund or automatic execution. Existing selective/PISP/date APIs retain their original support.
12
+ - Official source remains pinned toAP2 `b4587ac1d055888a73b4b21750973cffba961793`; checked main `e1ea56db72a6385bce3e5c1112b3a56ce60acb43` has unchanged relevant docs/schema/SDK. Issues297/339/389 and PR340/368/377 remain unresolved/unmerged at investigation. The core specification is now under FIDO's standards process; no new normative monthly/unit resolution was identified in accessible public sources.
13
+
14
+ The Python SDK independently creates the outer KB `iat`; it does not force it equal to the delegated content `iat`. This profile preserves shared content times and refreshes only the proof. The Ruby verifier additionally enforces maximum proof age300seconds, no future proof, exact original Checkout/Payment reference binding and current Host-selected keys. A year-long content expiry never creates a year-long execution handle.
15
+
16
+ Python's cadence evaluator does not enforce frequency; its budget evaluator uses`int(max * 100)` regardless of currency. This profile uses the signed integer JPY value directly: one yen is one minor unit, with no float conversion/rounding or silent scaling. A receiver using the unmodified Python evaluator can accept more than this profile allows. Wire/crypto interoperability is not aggregate-policy conformance or an assurance that a remote Python consumer enforces these limits.
17
+
18
+ ## Public lifecycle
19
+
20
+ `LongPayment.issue_checkout_open/issue_checkout_closed/present_checkout` wrap the explicit Checkout profile. `issue_open/issue_closed/present/verify/details` wrap the matching Payment profile. Their signer/key/Checkout/challenge inputs follow the existing role-separated APIs. Provider private keys do not enter Agent operations. `approved_pair!` is a protected-backend helper authenticating BOTH complete signed Opens, current Issuer/Agent keys, exact Checkout reference and immutable economic terms; it does not enroll consent by itself.
21
+
22
+ `verify` is stateless: it authenticates this presentation and its visible conditions, **not historical quota or final payment permission**. Use the durable acceptance service for repeated use. [Installed Ruby wire example](../examples/long_payment.rb); [twelve-period acceptance/Receipt example](../examples/long_payment_acceptance.rb).
23
+
24
+ ```ruby
25
+ a = AP2MandateVerifier::PaymentAcceptance
26
+ store = a::LongSQLiteStore.create(path: protected_new_path) # Explicit offline bootstrap only.
27
+ service = a::Service.new(store: store)
28
+
29
+ # Authenticated consent backend; complete retained Opens stay confidential.
30
+ store.authorize_series!(tenant_id: tenant, merchant_id: merchant, approval_id: stable_consent_id,
31
+ payment_open: full_payment_open, checkout_open: full_checkout_open,
32
+ trust_json: current_trust_json, selection_json: current_selection_json, verified_at: trusted_now,
33
+ schedule_policy_id: a::LongSQLiteStore::SCHEDULE_POLICY,
34
+ periods: [{id: "2028-01", not_before: january_start_utc, not_after: february_start_utc}])
35
+ # Enroll the exact independently approved occurrence through existing authorize!.
36
+ accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
37
+ execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
38
+ # Application invokes its processor using execution.processor_key; SDK makes no call.
39
+ ```
40
+
41
+ Both original Opens must remain valid. Payment's reference commits to the exact Open Checkout presentation; replacing a parent Open or changing its disclosure bytes cannot silently preserve that reference. Merchant Checkout/order and Agent proofs are fresh per occurrence; the original signed Opens remain unchanged until authorized replacement.
42
+
43
+ ## UTC calendar-month contract
44
+
45
+ `SCHEDULE_POLICY` is `host.utc_calendar_month_windows.1`. It is an additional explicit Host/profile contract, **not an assertion that AP2 has settled MONTHLY semantics**.
46
+
47
+ The authenticated backend enrolls1–24 immutable windows with unique stable IDs, integer Unix epoch bounds and half-open`[not_before,not_after)` semantics. Each window must lie inside one UTC calendar month and the initial agreement interval; at most one window per UTC year/month is allowed. A window may be narrower than the month, but cannot span months or split one month into multiple allowances. Period order is normalized by start time; overlap/duplicate/out-of-range/unknown policy fails closed. Actual verification time selects the period; a caller-chosen ID cannot select another window.
48
+
49
+ This avoids ambiguous rolling-month, timezone/DST, missing-day/month-end and catch-up behavior. It does not support local-time billing calendars. End-of-January and start-of-February can be close in elapsed time while belonging to different UTC calendar months; this is not a rolling minimum interval. The consent UI must display the actual approved windows, total cap, counts and this calendar rule. SDK enrollment is not authentication, consent acquisition or proof of the trusted surface's display.
50
+
51
+ The budget is cumulative across the agreement, not reset each month. Count and amount are charged when first reservation commits, not when a Success Receipt arrives. reserved/processing/unknown/Success/Error all retain allowance. Retry, timeout, crash, expiry, revocation or presumed refund never releases a slot.
52
+
53
+ ## Current authority and atomic state
54
+
55
+ `LongSQLiteStore` uses an explicit new **schema3** with the optional existing`sqlite3=2.10.2` driver. Normal startup opens an existing protected database; missing/corrupt/wrong schema has no repair/reset/memory fallback. Schema1/2 stores reject long profiles, and do not auto-upgrade or migrate.
56
+
57
+ Initial enrollment pins immutable agreement bounds, full Checkout and Payment economic terms, authority principal identities/purposes/tenant, limits and windows. Stable tenant/merchant/consent/period/operation/order IDs come from authenticated business state, never client retry UUIDs or wire hashes. A new client-generated consent ID is not evidence of a new authorization. The same signed Root cannot enroll another merchant/consent in that tenant; alias tombstones survive revocation/replacement.
58
+
59
+ The ledger has a protected authority binding and monotonic epoch. Raw verification binds Payment Provider and Agent keys to the current Host-selected Checkout registry; it cannot self-select enrollment from a token. Reservation checks the active agreement, current Root, exact current authority binding and actual period, then inserts the attempt and charges quota in the same SQLite transaction. Start re-verifies complete raw inputs, requires the same first signed wires, current binding/accepted epoch and a fenced state transition. Execution validity intersects content, fresh Checkout/Payment proof, registry/key/challenge, period and immutable agreement ends. `Execution.valid_until` exposes that checked deadline. Applications must dispatch promptly and enforce the deadline/current authority at their processor boundary; the SDK cannot revoke an already returned object or atomically commit a remote payment with SQLite.
60
+
61
+ **An epoch is authoritative only for this ledger.** The application must authenticate the registry/consent/order source and synchronize external changes before making it available for acceptance/start. This SDK supplies no revocation network, freshness oracle, background polling or cross-database atomic transaction. A stale but still time-valid external snapshot is not automatically detected. Registry-source generation, anti-rollback and observation freshness are application guarantees; the ledger epoch does not manufacture those guarantees from a caller-provided snapshot. If the feed is unknown/stale, the protected backend must invalidate authority and stop dispatch. A separate external check followed later by an independent DB write does not establish atomic current authority.
62
+
63
+ Protected backend operations (not request-facing flags):
64
+
65
+ | API | Behavior |
66
+ | --- | --- |
67
+ | `usage(**series_scope)` | Reservation totals, current Root reference/epoch and active flags. Not settled spend or payment permission. |
68
+ | `update_authority!(**series_scope, expected_epoch:, trust_json:, selection_json:, verified_at:)` | CAS refresh for the same active Root's Issuer/Agent keys and immutable principals; Merchant key/registry version may change. Identical binding is idempotent. Changed binding increments epoch. |
69
+ | `invalidate_authority!(**series_scope, expected_epoch:)` | Holds all new acceptance/start and increments epoch. A trusted fresh update may resume authority; old-epoch Tickets do not revive. |
70
+ | `replace_root!(**series_scope, expected_epoch:, expected_root_reference:, payment_open:, checkout_open:, trust_json:, selection_json:, verified_at:)` | Authenticates new full pair/current keys. Preserves full economic contract/principals and original agreement end; retires old alias and increments epoch without resetting quota. |
71
+ | `revoke_root!(**series_scope, expected_epoch:)` | Permanently disables that Root alias and holds authority. A different authorized replacement may continue the same still-active agreement/history. |
72
+ | `revoke_series!(**series_scope)` | Permanently stops the agreement. Re-enrollment/replacement cannot reactivate it or refund allowance. |
73
+
74
+ Canonical key fingerprints use the existing SHA256 of canonical public SPKI **PEM bytes**, not arbitrary PEM variants or DER bytes. Root replacement permits new Issuer/Agent keys for the same principals and changed technical parent references/time/cnf, but rejects changed products/quantities/candidates/payee/instrument/currency/fixed terms/budget/count/profile or extended agreement end. New Root signatures do not mean a new budget.
75
+
76
+ Updating authority or replacing a Root conservatively invalidates old-generation reserved Tickets. No takeover, retry capability recovery or unstarted-attempt refund is supplied; operators must reconcile an uncertain attempt. Existing processing/unknown outcomes retain the original wires, processor key and Receipt trust context. An authentic original Receipt can finalize after expiry/revocation but never grants a new Ticket. Historical key compromise cannot be dated by Receipt.iat alone; trusted processor query/quarantine policy remains an application responsibility.
77
+
78
+ One authoritative durable local ledger must serve all workers. DB loss/rollback, stale restore, per-worker DBs, split-brain or unreviewed history import can invalidate protection. Original schema1/2 usage cannot be discarded by provisioning an empty schema3; migration/import requires a separately reviewed reconciliation process, and unknown history is HOLD. No external exactly-once/production durability/settlement guarantee is made.
79
+
80
+ ## Evidence and exclusions
81
+
82
+ Tests cover same Open pair over all12leap-year months, genuine signed negatives, old profile lifetime isolation, independent8process races with count/budget separated, fsynced mock effects, actual SIGKILL, rollback, Root/Issuer/Agent replacement, authority invalidation, revocation and historical Receipt references. These are synthetic tests, not real Issuer provenance, consent or processor execution.
83
+
84
+ Pinned official Python comparison uses actual SDK KB constructors, facade presentations, chain/typed/Schema verification and independent expected aud/nonce, with explicit JSON-mode Enum/integer-JPY/profile/inline adapters. Its known cadence/JPY/proof-age disagreements are recorded instead of weakened into parity. Unmodified high-level facade support, arbitrary AP2 formats, unknown constraints, other timezones/currencies, selective long profiles and real payment are outside this contract.
@@ -1,4 +1,11 @@
1
- # Payment acceptance and idempotency support (1.5.0 candidate)
1
+ # Payment acceptance and idempotency support (published1.5.0)
2
+
3
+ [Verified public distribution](POST_RELEASE_150.md).
4
+
5
+ For a runnable application walkthrough, see [Ruby integration and restart recovery](RUBY_INTEGRATION.md)
6
+ ([日本語](RUBY_INTEGRATION.ja.md)). It keeps application and mock processor state across
7
+ actual Ruby process termination. The older `examples/payment_acceptance.rb` reopens
8
+ a Store in the same process with an in-memory mock result; it is not a process-restart example.
2
9
 
3
10
  This opt-in application-side coordinator separates three events: cryptographic verification, durable reservation of an approved business occurrence, and an external payment processor’s outcome. Existing1.x verifiers and their result meanings remain unchanged. The SDK does not call a processor, transfer funds or promise distributed exactly-once execution.
4
11
 
data/docs/PUBLIC_API.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Ruby SDK public API — 1.x
2
2
 
3
- **Status: published 1.4.0; the original 1.0.0 Checkout contract below is preserved.**
3
+ **Status: published 1.6.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
@@ -216,8 +216,16 @@ For the explicit selective Checkout profile, Evidence `original_root_graph_closu
216
216
 
217
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.
218
218
 
219
- ## 1.5.0 candidate: application-side Payment acceptance
219
+ ## Published1.5.0: application-side Payment acceptance
220
220
 
221
221
  `PaymentAcceptance::Service` takes a transactional `store:` adapter. `accept` invokes existing raw verifiers then atomically checks an enrolled protected occurrence and reserves it; `start` requires fresh raw verification and exact first signed wires before fenced CAS. `finish`, `unknown`, `lookup` and `reconcile` retain first-wire/Receipt/processor-key bindings and never automatically release or reissue a Ticket. No existing verifier result is reinterpreted as Host ALLOW.
222
222
 
223
223
  `SQLiteStore.create(path:)` explicitly initializes once; `new(path:)` opens an existing supported database and requires optional `sqlite3 = 2.10.2`. Base runtime dependencies remain unchanged. `authorize!` and `revoke!` are protected Host operations, never request-derived approval flags. See [all parameters, states, adapter guarantees, supported reuse and recovery limits](PAYMENT_ACCEPTANCE.md).
224
+
225
+ ## 1.6.0 candidate: bounded JPY/ON_DEMAND recurrence
226
+
227
+ `RecurringPayment::PROFILE_REF` / `SELECTIVE_PROFILE_REF` explicitly require visible finite recurrence and integerJPY budget constraints. Existing `Payment` / `SelectivePayment` issuance, presentation and verification accept these explicitly; `RecurringPayment` supplies convenience wrappers. Stateless verification does not establish historical quota. `PaymentAcceptance::RecurringSQLiteStore` adds protected `authorize_series!`, `revoke_series!`, `usage` and the existing occurrence APIs; reservations atomically charge both count and JPY amount. No old schema/profile gains implicit support. See [exact scope, migration and responsibilities](RECURRING_PAYMENT.md). For these bounded ON_DEMAND profiles, calendar recurrence and longer-lived Mandates are unsupported; the separate explicit LongPayment profile below handles UTC calendar months. Non-JPY budgets remain unsupported.
228
+
229
+ ## 1.6.0 candidate: explicit long content / short proof
230
+
231
+ `LongPayment` opts into separate long complete Checkout/Payment profiles while preserving existing defaults. `issue_checkout_open/issue_checkout_closed/present_checkout` and `details/issue_open/issue_closed/present/verify` follow existing role-separated inputs. `approved_pair!`, `current_authority!` and `authority!` are protected-backend helpers; none enrolls consent by itself. `PaymentAcceptance::LongSQLiteStore` adds explicit schema3 authority/period state, `authorize_series!`, CAS `update_authority!/invalidate_authority!/replace_root!/revoke_root!`, inherited permanent `revoke_series!` and current `usage`. `Execution.valid_until` exposes the checked short start deadline, including on existing acceptance results; it does not make an external processor call atomic or revoke an already returned handle. See [exact profile, UTC windows, trust duties, migration and SDK differences](LONG_PAYMENT.md).
@@ -0,0 +1,56 @@
1
+ # Repeated Payment approval: explicit JPY/ON_DEMAND subset (1.6.0)
2
+
3
+ Published on RubyGems; [exact distribution and validation](POST_RELEASE_160.md). Packaged preparation notes retain their historical scope.
4
+
5
+ This additive profile supports several separately approved Payment occurrences under one signed Open, with finite occurrence and cumulative JPY reservation limits. It is not a scheduler, generic recurring-payment implementation or payment executor. Existing profiles, seven-input Checkout contract, default verifier results and 600-second Mandate lifetime remain unchanged. This bounded profile does not provide long subscriptions. The separate [LongPayment profile](LONG_PAYMENT.md) adds explicit UTC-calendar-month windows and long content with fresh proofs.
6
+
7
+ ## Specification boundary
8
+
9
+ Official AP2 v0.2.0 is pinned to `b4587ac1d055888a73b4b21750973cffba961793`. Investigated main `e1ea56db72a6385bce3e5c1112b3a56ce60acb43` has identical relevant specification/schema/SDK files. The [recurrence description](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/docs/ap2/payment_mandate.md#agent-recurrence) requires frequency separation and a maximum count; calendar/rolling periods, anchors and timezones remain unspecified. The Python evaluator checks count but not frequency. Issue297 remains open. `ON_DEMAND` is the sole supported frequency; calendar frequencies fail closed.
10
+
11
+ The [budget description](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/docs/ap2/payment_mandate.md#budget) requires cumulative approved amounts not to exceed `max`; schema `max:number` does not specify units. Python multiplies by100 regardless of currency. Issue339 and354 and proposed fixes in PR340/368/377 remain open/unmerged at investigation. We do not treat their Decimal/monetary-unit proposals as adopted specifications.
12
+
13
+ The explicit `ap2.payment.recurring.jpy_on_demand.complete.1` and `.selective.1` profiles accept **JPY integers only**, with one integer yen equal to one JPY minor unit. No float, rounding, fixed100 conversion or reinterpretation of another currency is performed. Thus the common major/minor-unit ambiguity does not require choosing an exchange scale. The Python evaluator's acceptance of2JPY under a1JPY budget is a measured disagreement, not behavior copied into this profile. These explicit profiles are a narrow Gem contract, not official certification or generic AP2 conformance.
14
+
15
+ Every Open must visibly include exactly one `payment.agent_recurrence` (`frequency: ON_DEMAND`, positive finite `max_occurrences`) and one `payment.budget` (`currency: JPY`, positive integer `max`), alongside the existing payee, instrument, amount range and Checkout reference constraints. Mandatory conditions cannot be hidden. In the selective profile, only registered payee/instrument candidate leaves may be withheld. An old profile never silently gains recurrence support.
16
+
17
+ ## Measured interoperability
18
+
19
+ The pinned official Python facade fails recurrence issuance with an Enum JSON-serialization error. Its generated Budget model also converts integer600 to600.0, which is outside this integer-only signed profile. The explicit low-level test adapter serializes enums in JSON mode, preserves the original integer JPY budget, and adds the signed profile marker. It does not claim that the unmodified high-level facade supports this profile.
20
+
21
+ Fresh Ruby/Python keys exercise complete and selective Open/Closed chains in both directions, official schema/typed parsing, eight alternative Success/Error Receipts and fifteen signed negative checks (missing/hidden mandatory constraints, unsupported frequency/count, exact presentation binding and Receipt reference). The official SDK is evaluated at zero historical usage; an independent oracle checks mandatory disclosure and selected-candidate privacy. These are scoped wire/crypto comparisons. Durable aggregate enforcement is exercised separately through the Ruby store/process tests and is not supplied or certified by the official SDK.
22
+
23
+ ## Integration
24
+
25
+ `RecurringPayment` provides issuance, selection, presentation and stateless verification for the explicit profiles. Stateless verification authenticates each presentation and visible per-payment limits; **it cannot establish historical count or remaining budget**. Applications requiring repeated acceptance use `PaymentAcceptance::Service` with `PaymentAcceptance::RecurringSQLiteStore`, or a separately validated adapter preserving the same transaction contract.
26
+
27
+ ```ruby
28
+ m = AP2MandateVerifier
29
+ store = m::PaymentAcceptance::RecurringSQLiteStore.create(path: protected_new_path)
30
+ service = m::PaymentAcceptance::Service.new(store: store)
31
+
32
+ # Protected authenticated consent backend; retain the COMPLETE Open confidentially.
33
+ store.authorize_series!(tenant_id: "tenant", merchant_id: "shop", approval_id: "consent-42",
34
+ open_sd_jwt: full_open, profile_ref: m::RecurringPayment::PROFILE_REF,
35
+ trusted_provider_public_key_pem: provider_key, expected_agent_public_key_pem: agent_key,
36
+ verified_at: trusted_now)
37
+ # Enroll each real occurrence with existing authorize!, its exact Checkout/Payment
38
+ # and pinned Receipt context. IDs are stable authenticated Host state, never client UUIDs.
39
+ accepted = service.accept(**trusted_occurrence_scope, mode: :conditional, verification_inputs: raw_inputs)
40
+ execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
41
+ # Application processor call uses execution.processor_key. This SDK makes no call.
42
+ ```
43
+
44
+ `authorize_series!` validates the complete signed Open, Provider signature, authorized Agent key, profile, validity and mandatory constraints. It pins the original issuer JWT reference and immutable full contract. Selected presentations retain that issuer JWT; changing disclosure subsets does not create a new allowance. Re-enrolling the same agreement cannot reset counters or reactivate revocation. A changed signed Open conflicts with the same protected agreement ID. Re-signing and arbitrary new IDs received from a client never justify new consent enrollment.
45
+
46
+ For each occurrence, existing `authorize!` still pins exact independently approved Checkout/payment semantics and Receipt trust. First reservation checks that active grant and the series, then atomically inserts the attempt **and increments both reserved count and amount in the same BEGIN IMMEDIATE/COMMIT**. An identical retry obtains no second Ticket and incurs no second charge. A conflict, invalid presentation, exceeded limit or failed transaction creates no execution handle. The reference store bounds one series to one merchant; the same tenant/Open or tenant/agreement cannot be re-enrolled under another merchant to multiply its quota.
47
+
48
+ Reserved, processing, unknown and terminal Success/Error attempts all retain their charged allowance. No timeout, error Receipt, restart, revocation or presumed refund releases it. This deliberately conservative accounting may consume allowance for a payment that never occurred. `usage(tenant_id:, merchant_id:, approval_id:)` reports reservation totals, not settled spending. `revoke_series!` blocks both new reservation and fresh start without deleting history. Receipt reconciliation can finalize original processing/unknown attempts after Mandate expiry, but never grants another Ticket or releases quota.
49
+
50
+ ## Persistence and compatibility
51
+
52
+ The recurring reference adapter uses an explicit **new schema2 database** with the same optional pinned `sqlite3=2.10.2` driver. Existing1.5 schema1 files remain unchanged and are opened by the original `SQLiteStore`; they reject new recurrence profiles. Neither adapter opens the other's schema or auto-creates, upgrades, repairs, migrates, resets or falls back to memory. Provisioning a new empty ledger is not migration of existing history. Applications with prior repeated-use history must stop and reconcile/import it through their own reviewed process before enrolling a series; starting at zero is unsafe.
53
+
54
+ One authoritative durable local ledger must serve every worker and occurrence for an agreement. A per-process database, multiple independent stores, rollback/loss, restoring a stale backup or splitting one consent into fresh IDs destroys the protection. Authenticated stable identities, genuine consent, full-Open confidentiality, current order/nonce/revocation CAS, processor idempotency/query and outcome reconciliation remain application duties. Custom adapters must make authorization, quota checks/updates, occurrence reservation and fenced start atomic with current authority. An external precheck followed by an independent database write is insufficient.
55
+
56
+ No actual Issuer/Host provenance, production durability, external exactly-once settlement, refund semantics, distributed coordination, automatic scheduling, non-JPY budgets or calendar recurrence is claimed. This profile covers bounded ON_DEMAND repeated use within existing validity; the separate [LongPayment contract](LONG_PAYMENT.md) defines the supported local UTC-calendar-month policy.
@@ -1,5 +1,7 @@
1
1
  # 1.5.0 release candidate preparation
2
2
 
3
+ Historical preparation snapshot: Owner subsequently approved publication; [actual distribution and release verification](POST_RELEASE_150.md). Production connections and real payments remain outside scope.
4
+
3
5
  Release candidate preparation; final exact-source/artifact/review/CI evidence is recorded in the PR and external manifest. RubyGems/public tag/GitHub Release/production connection/real payment remain HOLD pending Owner decision.
4
6
 
5
7
  ## Proposed notes and main use