ap2_mandate_verifier 1.5.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.ja.md +19 -8
- data/README.md +19 -8
- data/SECURITY.md +7 -3
- data/docs/LONG_PAYMENT.md +82 -0
- data/docs/PAYMENT_ACCEPTANCE.md +3 -1
- data/docs/PUBLIC_API.md +10 -2
- data/docs/RECURRING_PAYMENT.md +54 -0
- data/docs/RELEASE_150_CANDIDATE.md +2 -0
- data/docs/RELEASE_160_CANDIDATE.md +30 -0
- data/docs/SUPPORT_CONTRACT.md +6 -2
- data/examples/conditional_checkout.rb +3 -3
- data/examples/long_payment.rb +116 -0
- data/examples/long_payment_acceptance.rb +89 -0
- data/examples/recurring_payment.rb +99 -0
- data/lib/ap2_mandate_verifier/checkout_jwt.rb +1 -1
- data/lib/ap2_mandate_verifier/checkout_receipt.rb +10 -1
- data/lib/ap2_mandate_verifier/conditional_checkout.rb +43 -19
- data/lib/ap2_mandate_verifier/input_builder.rb +1 -1
- data/lib/ap2_mandate_verifier/long_payment.rb +201 -0
- data/lib/ap2_mandate_verifier/payment.rb +52 -12
- data/lib/ap2_mandate_verifier/payment_acceptance/long_sqlite_store.rb +272 -0
- data/lib/ap2_mandate_verifier/payment_acceptance/recurring_sqlite_store.rb +124 -0
- data/lib/ap2_mandate_verifier/payment_acceptance/sqlite_store.rb +38 -10
- data/lib/ap2_mandate_verifier/payment_acceptance.rb +28 -6
- data/lib/ap2_mandate_verifier/payment_policy.rb +7 -2
- data/lib/ap2_mandate_verifier/purchase_binding.rb +11 -5
- data/lib/ap2_mandate_verifier/recurring_payment.rb +111 -0
- data/lib/ap2_mandate_verifier/root_disclosures.rb +9 -6
- data/lib/ap2_mandate_verifier/scoped_constraints.rb +1 -1
- data/lib/ap2_mandate_verifier/selective_payment.rb +1 -1
- data/lib/ap2_mandate_verifier/trust_context.rb +6 -0
- data/lib/ap2_mandate_verifier.rb +4 -0
- metadata +16 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ce60e2a051e6be158dcc52ffb595dce1dbdcce31787e9ac8687b118c480dfe23
|
|
4
|
+
data.tar.gz: c60eee06cf772b4beadace507bab58248edd917422fdcc9144275f075cc7f69a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 02a135e0e44c0d53a72cd55a15d2a866d3b435e68b99915f4895ea24076607aed58d7c3582873cd24ef085b91b0bbb0eab195696de5ee2053624576e7b75976e
|
|
7
|
+
data.tar.gz: e1d350045f8cd90436f2244974d1a4b23e5f899c53b37b473edb8ee466418332129c5bfdb673a00e06e7c207465f2ef65b3afdbfdf6e0271137d3762c5a760fc
|
data/README.ja.md
CHANGED
|
@@ -1,8 +1,19 @@
|
|
|
1
1
|
# AP2 Mandate Verifier — Checkout・PaymentのRuby SDK
|
|
2
2
|
|
|
3
|
-
### 1.
|
|
3
|
+
### 1.6.0候補:長期Openと月次JPY受理
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
明示的な長期profileで、同じCheckout/Payment Openを承認済みUTCカレンダー月に継続利用できます。内容の期限は最大400日でも、提示証明と開始時の実行期限は短く検証します。保護された権限世代・Root/鍵更新・原子的な期間/回数/JPY予約で、再送や更新による枠のリセットを防ぎます。旧profile・既定API・7入力契約は維持。未公開で、最終公開判断はOwnerに留保します。[契約・API・Pythonとの差](docs/LONG_PAYMENT.md)、[12期間のRuby受理・Receipt例](examples/long_payment_acceptance.rb)、[公開前確認](docs/RELEASE_160_CANDIDATE.md)。短期の[ON_DEMAND完全/選択的profile](docs/RECURRING_PAYMENT.md)も利用できます。
|
|
6
|
+
|
|
7
|
+
```ruby
|
|
8
|
+
# Protected enrollment + current authority synchronization are application duties.
|
|
9
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
10
|
+
execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
|
|
11
|
+
usage = store.usage(**trusted_series_scope) # reservations, not settlement
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
### 公開済み1.5.0:Payment受理の原子性と冪等性支援
|
|
15
|
+
|
|
16
|
+
保護された業務上の支払い単位を原子的に予約し、開始前に全検証をやり直します。応答消失・結果不明では自動再実行せず、元のReceiptを照合して復旧できます。[公開照合記録](docs/POST_RELEASE_150.md)。[組込み・永続store・安全性契約](docs/PAYMENT_ACCEPTANCE.md)、[Ruby単体の復旧例](examples/payment_acceptance.rb)、[公開前の確認](docs/RELEASE_150_CANDIDATE.md)。
|
|
6
17
|
|
|
7
18
|
```ruby
|
|
8
19
|
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
@@ -31,13 +42,13 @@ dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inp
|
|
|
31
42
|
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)。検証成功は実行許可ではなく、永続的・原子的な単発利用管理と実決済は利用アプリの責任です。
|
|
32
43
|
|
|
33
44
|
```sh
|
|
34
|
-
gem install ap2_mandate_verifier --version 1.
|
|
35
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.
|
|
45
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
46
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/payment.rb"
|
|
36
47
|
```
|
|
37
48
|
|
|
38
49
|
[English](README.md)
|
|
39
50
|
|
|
40
|
-
**公開済み安定版は1.
|
|
51
|
+
**公開済み安定版は1.5.0です。**
|
|
41
52
|
|
|
42
53
|
1.0.0では、既存のDirectと条件付きCheckoutの公開API・保守契約を確立しました。
|
|
43
54
|
0.8.0の引数・既定値・profile・結果の意味・保存形式と製品実装を維持します。
|
|
@@ -57,8 +68,8 @@ Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CO
|
|
|
57
68
|
正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
|
|
58
69
|
|
|
59
70
|
```sh
|
|
60
|
-
gem install ap2_mandate_verifier --version 1.
|
|
61
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.
|
|
71
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
72
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
62
73
|
```
|
|
63
74
|
|
|
64
75
|
[Ruby単体の実行例](examples/conditional_checkout.rb)はインストール済み公開APIだけを使い、
|
|
@@ -88,7 +99,7 @@ Rubyで購入委任データを検証する、AP2の固定profile向けGemです
|
|
|
88
99
|
正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
|
|
89
100
|
|
|
90
101
|
```sh
|
|
91
|
-
gem install ap2_mandate_verifier --version 1.
|
|
102
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
92
103
|
```
|
|
93
104
|
|
|
94
105
|
BundlerのGemfile:
|
data/README.md
CHANGED
|
@@ -1,8 +1,19 @@
|
|
|
1
1
|
# AP2 Mandate Verifier — Ruby SDK for Checkout and Payment
|
|
2
2
|
|
|
3
|
-
### 1.
|
|
3
|
+
### 1.6.0 candidate: long Open and monthly JPY acceptance
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
An explicit long profile reuses the same signed Checkout/Payment Open pair across approved UTC calendar months. Content can last up to400days while each outer proof/start stays short-lived. Protected authority epochs, root/key replacement and atomic period/count/JPY reservations prevent retries or renewal from resetting allowance. Old profiles/defaults and the seven-input contract are unchanged. Unpublished; Owner release decision pending. [Contract/API and Python differences](docs/LONG_PAYMENT.md), [twelve-period Ruby acceptance/Receipt example](examples/long_payment_acceptance.rb), [release gates](docs/RELEASE_160_CANDIDATE.md). The bounded [ON_DEMAND complete/selective profiles](docs/RECURRING_PAYMENT.md) remain available.
|
|
6
|
+
|
|
7
|
+
```ruby
|
|
8
|
+
# Protected enrollment + current authority synchronization are application duties.
|
|
9
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
10
|
+
execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
|
|
11
|
+
usage = store.usage(**trusted_series_scope) # reservations, not settlement
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
### Published1.5.0: transactional Payment acceptance
|
|
15
|
+
|
|
16
|
+
Reserve a protected business occurrence atomically, reverify before one fenced start, and recover the original Receipt after response loss without reopening an uncertain attempt. [Verified publication](docs/POST_RELEASE_150.md). [Integration/store/security contract](docs/PAYMENT_ACCEPTANCE.md), [plain Ruby recovery example](examples/payment_acceptance.rb), [release gates](docs/RELEASE_150_CANDIDATE.md).
|
|
6
17
|
|
|
7
18
|
```ruby
|
|
8
19
|
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
@@ -31,13 +42,13 @@ Published1.2.0 adds explicit `SelectivePayment` candidate-array disclosure: reta
|
|
|
31
42
|
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
43
|
|
|
33
44
|
```sh
|
|
34
|
-
gem install ap2_mandate_verifier --version 1.
|
|
35
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.
|
|
45
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
46
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/payment.rb"
|
|
36
47
|
```
|
|
37
48
|
|
|
38
49
|
[日本語](README.ja.md)
|
|
39
50
|
|
|
40
|
-
**Published stable: 1.
|
|
51
|
+
**Published stable: 1.5.0.**
|
|
41
52
|
|
|
42
53
|
1.0.0 establishes the stable public contract for the existing
|
|
43
54
|
Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
|
|
@@ -61,8 +72,8 @@ multi-item profile. Provider private keys never enter Agent operations.
|
|
|
61
72
|
Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
|
|
62
73
|
|
|
63
74
|
```sh
|
|
64
|
-
gem install ap2_mandate_verifier --version 1.
|
|
65
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.
|
|
75
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
76
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
66
77
|
```
|
|
67
78
|
|
|
68
79
|
The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
|
|
@@ -96,7 +107,7 @@ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readm
|
|
|
96
107
|
Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
|
|
97
108
|
|
|
98
109
|
```sh
|
|
99
|
-
gem install ap2_mandate_verifier --version 1.
|
|
110
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
100
111
|
```
|
|
101
112
|
|
|
102
113
|
Or add to your Gemfile:
|
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.
|
|
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.
|
|
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
|
-
|
|
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,82 @@
|
|
|
1
|
+
# Long Open Payment: explicit JPY / UTC monthly profile (1.6.0 candidate)
|
|
2
|
+
|
|
3
|
+
`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.
|
|
4
|
+
|
|
5
|
+
## Scope and official boundary
|
|
6
|
+
|
|
7
|
+
- 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.
|
|
8
|
+
- 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.
|
|
9
|
+
- 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.
|
|
10
|
+
- 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.
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
## Public lifecycle
|
|
17
|
+
|
|
18
|
+
`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.
|
|
19
|
+
|
|
20
|
+
`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).
|
|
21
|
+
|
|
22
|
+
```ruby
|
|
23
|
+
a = AP2MandateVerifier::PaymentAcceptance
|
|
24
|
+
store = a::LongSQLiteStore.create(path: protected_new_path) # Explicit offline bootstrap only.
|
|
25
|
+
service = a::Service.new(store: store)
|
|
26
|
+
|
|
27
|
+
# Authenticated consent backend; complete retained Opens stay confidential.
|
|
28
|
+
store.authorize_series!(tenant_id: tenant, merchant_id: merchant, approval_id: stable_consent_id,
|
|
29
|
+
payment_open: full_payment_open, checkout_open: full_checkout_open,
|
|
30
|
+
trust_json: current_trust_json, selection_json: current_selection_json, verified_at: trusted_now,
|
|
31
|
+
schedule_policy_id: a::LongSQLiteStore::SCHEDULE_POLICY,
|
|
32
|
+
periods: [{id: "2028-01", not_before: january_start_utc, not_after: february_start_utc}])
|
|
33
|
+
# Enroll the exact independently approved occurrence through existing authorize!.
|
|
34
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
35
|
+
execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
|
|
36
|
+
# Application invokes its processor using execution.processor_key; SDK makes no call.
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
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.
|
|
40
|
+
|
|
41
|
+
## UTC calendar-month contract
|
|
42
|
+
|
|
43
|
+
`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**.
|
|
44
|
+
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
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.
|
|
48
|
+
|
|
49
|
+
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.
|
|
50
|
+
|
|
51
|
+
## Current authority and atomic state
|
|
52
|
+
|
|
53
|
+
`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.
|
|
54
|
+
|
|
55
|
+
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.
|
|
56
|
+
|
|
57
|
+
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.
|
|
58
|
+
|
|
59
|
+
**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.
|
|
60
|
+
|
|
61
|
+
Protected backend operations (not request-facing flags):
|
|
62
|
+
|
|
63
|
+
| API | Behavior |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| `usage(**series_scope)` | Reservation totals, current Root reference/epoch and active flags. Not settled spend or payment permission. |
|
|
66
|
+
| `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. |
|
|
67
|
+
| `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. |
|
|
68
|
+
| `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. |
|
|
69
|
+
| `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. |
|
|
70
|
+
| `revoke_series!(**series_scope)` | Permanently stops the agreement. Re-enrollment/replacement cannot reactivate it or refund allowance. |
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
## Evidence and exclusions
|
|
79
|
+
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
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.
|
data/docs/PAYMENT_ACCEPTANCE.md
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
# Payment acceptance and idempotency support (
|
|
1
|
+
# Payment acceptance and idempotency support (published1.5.0)
|
|
2
|
+
|
|
3
|
+
[Verified public distribution](POST_RELEASE_150.md).
|
|
2
4
|
|
|
3
5
|
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
6
|
|
data/docs/PUBLIC_API.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Ruby SDK public API — 1.x
|
|
2
2
|
|
|
3
|
-
**Status: published 1.
|
|
3
|
+
**Status: published 1.5.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
|
-
##
|
|
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,54 @@
|
|
|
1
|
+
# Repeated Payment approval: explicit JPY/ON_DEMAND subset (1.6.0 candidate)
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Specification boundary
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
## Measured interoperability
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
## Integration
|
|
22
|
+
|
|
23
|
+
`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.
|
|
24
|
+
|
|
25
|
+
```ruby
|
|
26
|
+
m = AP2MandateVerifier
|
|
27
|
+
store = m::PaymentAcceptance::RecurringSQLiteStore.create(path: protected_new_path)
|
|
28
|
+
service = m::PaymentAcceptance::Service.new(store: store)
|
|
29
|
+
|
|
30
|
+
# Protected authenticated consent backend; retain the COMPLETE Open confidentially.
|
|
31
|
+
store.authorize_series!(tenant_id: "tenant", merchant_id: "shop", approval_id: "consent-42",
|
|
32
|
+
open_sd_jwt: full_open, profile_ref: m::RecurringPayment::PROFILE_REF,
|
|
33
|
+
trusted_provider_public_key_pem: provider_key, expected_agent_public_key_pem: agent_key,
|
|
34
|
+
verified_at: trusted_now)
|
|
35
|
+
# Enroll each real occurrence with existing authorize!, its exact Checkout/Payment
|
|
36
|
+
# and pinned Receipt context. IDs are stable authenticated Host state, never client UUIDs.
|
|
37
|
+
accepted = service.accept(**trusted_occurrence_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
38
|
+
execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
|
|
39
|
+
# Application processor call uses execution.processor_key. This SDK makes no call.
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`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.
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
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.
|
|
47
|
+
|
|
48
|
+
## Persistence and compatibility
|
|
49
|
+
|
|
50
|
+
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.
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
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 candidate covers bounded ON_DEMAND repeated use within existing validity; the broader monthly-subscription goal remains deferred pending a precise safe contract.
|
|
@@ -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
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 1.6.0 candidate: long Open and UTC-monthly JPY acceptance
|
|
2
|
+
|
|
3
|
+
Unpublished preparation; RubyGems, formal tag and GitHub Release require OwnerGO. No production/payment authority follows from tests, review or merge. The earlier bounded ON_DEMAND candidate is retained separately as historical evidence; it is not replaced in the registry.
|
|
4
|
+
|
|
5
|
+
## Proposed notes and primary use
|
|
6
|
+
|
|
7
|
+
New explicit `LongPayment` complete Checkout/Payment profiles reuse one signed Open pair across approved UTC calendar months. Their shared content `iat`/`exp` stays fixed (maximum400days); outer KB proofs, challenge/order/current keys and starts are fresh. Existing defaults, seven-input contract and old600/7200second profiles remain unchanged. The bounded `RecurringPayment` complete/selective profiles remain available.
|
|
8
|
+
|
|
9
|
+
Optional schema3 `PaymentAcceptance::LongSQLiteStore` atomically checks current protected authority, active Root, period/count/JPY budget and occurrence state. Protected CAS Root/Issuer/Agent replacement preserves complete economic terms, principal identities, original agreement end and accumulated usage. Authority invalidation/revocation blocks starts; old pending Tickets never revive through a generation update. Unknown/Error/crash never refunds capacity, reissues a Ticket or loses the first signed wires/Receipt reference.
|
|
10
|
+
|
|
11
|
+
```ruby
|
|
12
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
13
|
+
execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
|
|
14
|
+
# execution.valid_until is short; the application owns prompt processor dispatch.
|
|
15
|
+
usage = store.usage(**trusted_series_scope) # reserved totals/current epoch, not settlement
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
[12-period installed Ruby lifecycle](../examples/long_payment_acceptance.rb), [wire-only lifecycle](../examples/long_payment.rb), [API/security/migration/Python contract](LONG_PAYMENT.md).
|
|
19
|
+
|
|
20
|
+
## Exact boundary
|
|
21
|
+
|
|
22
|
+
The additional MONTHLY meaning is an explicit Host/profile policy: one immutable window within each UTC calendar month, no more than one window per month. It is not generic AP2 calendar conformance, rolling intervals, local timezone/DST billing or catch-up. JPY budget uses exact signed integers; the current Python evaluator's100xJPY conversion and missing cadence evaluation are documented disagreements. Actual SDK constructors/facade/chain/Schema comparisons use explicit Enum/profile/integer/inline adapters, not a claim of unmodified high-level compatibility.
|
|
23
|
+
|
|
24
|
+
External trust/consent/order provenance and freshness, registry synchronization into the ledger, nonce/order CAS, one protected authoritative store, history migration, processor idempotency/query and settlement remain application responsibilities. No built-in external revocation feed, scheduler, payment call, remote exactly-once, auto-refund or automatic schema1/2 migration is supplied. Long selective/PISP/date combinations, other currencies/timezones and arbitrary AP2 formats remain unsupported.
|
|
25
|
+
|
|
26
|
+
## Release gates
|
|
27
|
+
|
|
28
|
+
Both supportedMRI3.4.12/4.0.9 full regressions and the same physically installed archive; every payload source/archive/installed byte hash; 12-month leap-year positives, causal signed negatives/current key tests; independent8process same-period/count/budget races, realSIGKILL/restart, fsynced mock effects, rollback, Root/key replacement, revocation and original historical Receipt; installed pinnedPython interop with exactwire disagreements; optional-driver absence; normal demo regression and strict candidate context; independent latest-HEAD review with no unresolved substantiveP1/P2; Draft-first PRs, successful CI, reviewed/merged tree equality; fixed-builder repeat and merged-source byte-identical build.
|
|
29
|
+
|
|
30
|
+
Source/hash/count evidence is recorded outside its own package. Only an explicit OwnerGO for the final exact archive permits one publication attempt. Verify actual registry bytes before formal tag/Release; inspect uncertain outcomes before retries. No merge/push workflow may publish or deploy.
|
data/docs/SUPPORT_CONTRACT.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
# AP2 Checkout Ruby SDK — support contract and history
|
|
2
2
|
|
|
3
|
-
## Current published
|
|
3
|
+
## Current published scope
|
|
4
4
|
|
|
5
|
-
Published stable is1.
|
|
5
|
+
Published stable is1.5.0: [verified publication](POST_RELEASE_150.md). It adds opt-in [transactional Payment acceptance](PAYMENT_ACCEPTANCE.md) while preserving all existing1.x verifier APIs, defaults and stored formats. The SQLite reference adapter additionally requires optional pinned driver2.10.2 and a protected local persistent filesystem; other adapters require their own atomicity/durability validation. No new external exactly-once or production authorization guarantee is made.
|
|
6
|
+
|
|
7
|
+
## Unpublished1.6.0 subset
|
|
8
|
+
|
|
9
|
+
The additive candidate retains bounded JPY/ON_DEMAND profiles and adds an explicit complete [LongPayment JPY/UTC-month profile](LONG_PAYMENT.md), with up to400day content, fresh proof/start checks and optional schema3 authority/period storage. General calendar/timezone semantics and other currencies remain unsupported. Existing schema1/2,1.x defaults and short-profile limits remain unchanged; no automatic history migration is provided.
|
|
6
10
|
|
|
7
11
|
## Historical1.0.0 baseline contract
|
|
8
12
|
|
|
@@ -8,7 +8,7 @@ module ConditionalCheckoutExample
|
|
|
8
8
|
PROFILE = M::ConditionalCheckout::PROFILE_REF
|
|
9
9
|
NOW = 1_800_000_000
|
|
10
10
|
def self.totals(n) = %w[subtotal total].map { |type| {"type" => type, "amount" => n} }
|
|
11
|
-
def self.run
|
|
11
|
+
def self.run(currency: "USD")
|
|
12
12
|
provider, agent, merchant = Array.new(3) { OpenSSL::PKey::EC.generate("prime256v1") }
|
|
13
13
|
seller = {"id" => "shop", "name" => "Office supplies"}
|
|
14
14
|
# This protected record is created AFTER application authentication, display
|
|
@@ -25,7 +25,7 @@ module ConditionalCheckoutExample
|
|
|
25
25
|
"quantity" => 1, "totals" => totals(100)}
|
|
26
26
|
end
|
|
27
27
|
order = {"id" => "office-1", "merchant" => seller, "status" => "ready_for_complete",
|
|
28
|
-
"currency" =>
|
|
28
|
+
"currency" => currency, "line_items" => lines, "totals" => totals(300), "links" => []}
|
|
29
29
|
checkout = M::CheckoutJWT.sign(checkout: order, profile_ref: PROFILE,
|
|
30
30
|
signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
|
|
31
31
|
|
|
@@ -41,7 +41,7 @@ module ConditionalCheckoutExample
|
|
|
41
41
|
"not_before" => NOW - 1, "not_after" => NOW + 1000, "records" => records},
|
|
42
42
|
tenant_id: "tenant", verified_at: NOW, profile_ref: PROFILE, **selectors)
|
|
43
43
|
host_order = {"tenant_id" => "tenant", "buyer_account_id" => "buyer", "order_id" => "office-1",
|
|
44
|
-
"merchant_id" => "shop", "audience" => "merchant-host", "order_version" => "1", "currency" =>
|
|
44
|
+
"merchant_id" => "shop", "audience" => "merchant-host", "order_version" => "1", "currency" => currency, "expected_total" => 300}
|
|
45
45
|
host_inputs = {trust: trust, order: host_order, root_presentation: opening.root_presentation, host_checkout_jws: checkout.jwt}
|
|
46
46
|
saved = M::InputBuilder.prepare(**host_inputs, challenge_id: "challenge-1", nonce: "synthetic-one-use-nonce",
|
|
47
47
|
issuer_id: "host", not_before: NOW, not_after: NOW + 60)
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# Installed SDK only. Synthetic wire fixtures; no storage or payment execution.
|
|
3
|
+
require "ap2_mandate_verifier"
|
|
4
|
+
require "openssl"
|
|
5
|
+
|
|
6
|
+
module LongPaymentExample
|
|
7
|
+
M = AP2MandateVerifier
|
|
8
|
+
L = M::LongPayment
|
|
9
|
+
T0 = Time.utc(2028, 1, 1).to_i
|
|
10
|
+
EXP = Time.utc(2029, 1, 1).to_i
|
|
11
|
+
PERIODS = (1..12).to_h do |month|
|
|
12
|
+
finish = month == 12 ? Time.utc(2029,1,1).to_i : Time.utc(2028,month+1,1).to_i
|
|
13
|
+
[format("2028-%02d",month), [Time.utc(2028,month,1).to_i,finish].freeze]
|
|
14
|
+
end.freeze
|
|
15
|
+
SELLER = {"id" => "shop", "name" => "Synthetic Long Shop"}.freeze
|
|
16
|
+
REQUIREMENTS = [{"id" => "monthly", "quantity" => 1,
|
|
17
|
+
"acceptable_items" => [{"id" => "long-item", "title" => "Monthly supplies"}]}].freeze
|
|
18
|
+
def self.now(period) = PERIODS.fetch(period)[0] + 3600
|
|
19
|
+
def self.signer(key) = M::CheckoutJWT.es256_signer(private_key: key)
|
|
20
|
+
def self.totals(n) = %w[subtotal total].map { |kind| {"type" => kind, "amount" => n} }
|
|
21
|
+
def self.cart(period, amount = 40000)
|
|
22
|
+
raise "unknown synthetic period/amount" unless PERIODS.key?(period) && amount.instance_of?(Integer) && amount.between?(1,100000)
|
|
23
|
+
{"id" => "long-#{period}-#{amount}", "merchant" => SELLER, "status" => "ready_for_complete", "currency" => "JPY", "links" => [],
|
|
24
|
+
"line_items" => [{"id" => "row-1", "quantity" => 1, "item" => {"id" => "long-item", "title" => "Monthly supplies", "price" => amount}, "totals" => totals(amount)}], "totals" => totals(amount)}
|
|
25
|
+
end
|
|
26
|
+
def self.inputs(period:, checkout_open:, payment_open:, checkout_jwt:, checkout_closed:, payment_closed:,
|
|
27
|
+
provider:, agent:, merchant:, amount: 40000, authority: {})
|
|
28
|
+
at = now(period)
|
|
29
|
+
raise "unknown synthetic authority option" unless (authority.keys - %i[snapshot_id policy_version not_before not_after issuer agent merchant]).empty?
|
|
30
|
+
start = authority.fetch(:not_before,T0-1); finish = authority.fetch(:not_after,EXP)
|
|
31
|
+
keys = [authority.fetch(:issuer,provider),authority.fetch(:agent,agent),authority.fetch(:merchant,merchant)]
|
|
32
|
+
records = %w[Issuer Agent Merchant].zip(keys).map do |role,key|
|
|
33
|
+
{"role" => role,"identity" => role == "Merchant" ? "shop" : role.downcase,"tenant_id" => "long-tenant","purpose" => "checkout",
|
|
34
|
+
"key_ref" => role.downcase,"public_key_pem" => key,"active" => true,"not_before" => start,"not_after" => finish}
|
|
35
|
+
end
|
|
36
|
+
selectors = records.to_h { |r| [r["role"].downcase.to_sym,r.slice("identity","purpose","key_ref")] }
|
|
37
|
+
trust = M::InputBuilder.trust(snapshot: {"id" => authority.fetch(:snapshot_id,"long-registry-1"),"policy_version" => authority.fetch(:policy_version,"long-authority-1"),
|
|
38
|
+
"active" => true,"not_before" => start,"not_after" => finish,"records" => records},tenant_id:"long-tenant",verified_at:at,
|
|
39
|
+
profile_ref:L::CHECKOUT_PROFILE_REF,**selectors)
|
|
40
|
+
value = cart(period,amount)
|
|
41
|
+
order = {"tenant_id" => "long-tenant","buyer_account_id" => "synthetic-buyer","order_id" => value.fetch("id"),"merchant_id" => "shop",
|
|
42
|
+
"audience" => "merchant-host","order_version" => "1","currency" => "JPY","expected_total" => amount}
|
|
43
|
+
host = {trust:trust,order:order,root_presentation:checkout_open,host_checkout_jws:checkout_jwt}
|
|
44
|
+
saved = M::InputBuilder.prepare(**host,challenge_id:"challenge-#{period}-#{amount}",nonce:"checkout-nonce-#{period}-#{amount}",issuer_id:"host",
|
|
45
|
+
not_before:at-1,not_after:at+120)
|
|
46
|
+
raw = M::InputBuilder.inputs(**host,saved_challenge:saved,terminal_jws:checkout_closed.delete_suffix("~"),expected_challenge_issuer_id:"host",
|
|
47
|
+
clock_source_id:"synthetic-clock-#{period}",verified_at:at)
|
|
48
|
+
payment = L.details(checkout_jwt:checkout_jwt,trusted_merchant_public_key_pem:merchant,expected_merchant_id:"shop",payment_instrument:{"id"=>"synthetic-card","type"=>"card"})
|
|
49
|
+
{open_sd_jwt:payment_open,closed_sd_jwt:payment_closed,checkout_mode: :conditional,checkout_inputs:raw,expected_payment:payment,
|
|
50
|
+
trusted_provider_public_key_pem:provider,expected_agent_public_key_pem:agent,expected_audience:"payment-host",
|
|
51
|
+
expected_nonce:"payment-nonce-#{period}-#{amount}",verified_at:at,profile_ref:L::PROFILE_REF}
|
|
52
|
+
end
|
|
53
|
+
class Fixture
|
|
54
|
+
attr_reader :provider,:agent,:merchant,:checkout_open,:payment_open,:issued_at,:expires_at
|
|
55
|
+
def initialize(max_occurrences:12,budget:480000,amount:40000,provider:nil,agent:nil,merchant:nil,
|
|
56
|
+
issued_at:T0,expires_at:EXP,requirements:REQUIREMENTS,seller:SELLER,fixed:{},authority:{})
|
|
57
|
+
@provider,@agent,@merchant = [provider,agent,merchant].map { |key| key || OpenSSL::PKey::EC.generate("prime256v1") }
|
|
58
|
+
@issued_at,@expires_at,@amount = issued_at,expires_at,amount
|
|
59
|
+
@max_occurrences,@budget,@requirements,@seller,@fixed,@authority = max_occurrences,budget,requirements,seller,fixed,authority
|
|
60
|
+
@checkout_open = L.issue_checkout_open(merchant:seller,requirements:requirements,agent_public_key_pem:@agent.public_to_pem,
|
|
61
|
+
issued_at:issued_at,expires_at:expires_at,signer:LongPaymentExample.signer(@provider),public_key_pem:@provider.public_to_pem).root_presentation
|
|
62
|
+
cs = [{"type"=>"payment.amount_range","currency"=>"JPY","min"=>1,"max"=>100000},
|
|
63
|
+
{"type"=>"payment.allowed_payees","allowed"=>[seller]},
|
|
64
|
+
{"type"=>"payment.allowed_payment_instruments","allowed"=>[{"id"=>"synthetic-card","type"=>"card"}]},
|
|
65
|
+
{"type"=>"payment.agent_recurrence","frequency"=>"MONTHLY","max_occurrences"=>max_occurrences},
|
|
66
|
+
{"type"=>"payment.budget","currency"=>"JPY","max"=>budget}]
|
|
67
|
+
@payment_open = L.issue_open(open_checkout_sd_jwt:@checkout_open,constraints:cs,fixed:fixed,candidate_policy: :independent,
|
|
68
|
+
agent_public_key_pem:@agent.public_to_pem,issued_at:issued_at,expires_at:expires_at,
|
|
69
|
+
signer:LongPaymentExample.signer(@provider),public_key_pem:@provider.public_to_pem)
|
|
70
|
+
end
|
|
71
|
+
def month(period, amount = nil, **options)
|
|
72
|
+
raise "unknown synthetic month option" unless (options.keys - %i[amount authority merchant]).empty?
|
|
73
|
+
value = options.fetch(:amount,amount || @amount); at = LongPaymentExample.now(period)
|
|
74
|
+
merchant = options.fetch(:merchant,@merchant)
|
|
75
|
+
cart = LongPaymentExample.cart(period,value)
|
|
76
|
+
jwt = M::CheckoutJWT.sign(checkout:cart,profile_ref:L::CHECKOUT_PROFILE_REF,signer:LongPaymentExample.signer(merchant),public_key_pem:merchant.public_to_pem).jwt
|
|
77
|
+
closed_checkout = L.issue_checkout_closed(root_presentation:@checkout_open,checkout_jwt:jwt,trusted_issuer_public_key_pem:@provider.public_to_pem,
|
|
78
|
+
agent_public_key_pem:@agent.public_to_pem,trusted_merchant_public_key_pem:merchant.public_to_pem,expected_merchant_id:"shop",audience:"merchant-host",
|
|
79
|
+
nonce:"checkout-nonce-#{period}-#{value}",verified_at:at,signer:LongPaymentExample.signer(@agent))
|
|
80
|
+
payment = L.details(checkout_jwt:jwt,trusted_merchant_public_key_pem:merchant.public_to_pem,expected_merchant_id:"shop",payment_instrument:{"id"=>"synthetic-card","type"=>"card"})
|
|
81
|
+
closed_payment = L.issue_closed(open_sd_jwt:@payment_open,payment:payment,trusted_provider_public_key_pem:@provider.public_to_pem,
|
|
82
|
+
agent_public_key_pem:@agent.public_to_pem,audience:"payment-host",nonce:"payment-nonce-#{period}-#{value}",verified_at:at,signer:LongPaymentExample.signer(@agent))
|
|
83
|
+
verify = LongPaymentExample.inputs(period:period,checkout_open:@checkout_open,payment_open:@payment_open,checkout_jwt:jwt,
|
|
84
|
+
checkout_closed:closed_checkout.closed_sd_jwt,payment_closed:closed_payment.closed_sd_jwt,provider:@provider.public_to_pem,
|
|
85
|
+
agent:@agent.public_to_pem,merchant:merchant.public_to_pem,amount:value,authority:options.fetch(:authority,@authority))
|
|
86
|
+
raise "synthetic long wire verification failed" unless L.verify(**verify).verified?
|
|
87
|
+
receipts = [{kind:"checkout",key:merchant.public_to_pem,jwt:M::CheckoutReceipt.sign(closed_sd_jwt:closed_checkout.closed_sd_jwt,profile_ref:L::CHECKOUT_PROFILE_REF,
|
|
88
|
+
issuer:"processor",outcome:"Success",order_id:cart.fetch("id"),issued_at:at,signer:LongPaymentExample.signer(merchant),public_key_pem:merchant.public_to_pem).jwt},
|
|
89
|
+
{kind:"payment",key:merchant.public_to_pem,jwt:M::PaymentReceipt.sign(closed_sd_jwt:closed_payment.closed_sd_jwt,profile_ref:L::PROFILE_REF,
|
|
90
|
+
issuer:"processor",outcome:"Success",payment_id:"payment-#{period}",issued_at:at,psp_confirmation_id:"synthetic-psp",network_confirmation_id:"synthetic-net",
|
|
91
|
+
signer:LongPaymentExample.signer(merchant),public_key_pem:merchant.public_to_pem).jwt}]
|
|
92
|
+
{period:period,now:at,amount:value,cart:cart,checkout_jwt:jwt,checkout_closed:closed_checkout.closed_sd_jwt,payment_closed:closed_payment.closed_sd_jwt,
|
|
93
|
+
expected_payment:payment,verify_inputs:verify,receipts:receipts}
|
|
94
|
+
end
|
|
95
|
+
def rotate(provider:,agent:,merchant:@merchant,issued_at:,authority:)
|
|
96
|
+
self.class.new(provider:provider,agent:agent,merchant:merchant,issued_at:issued_at,expires_at:@expires_at,max_occurrences:@max_occurrences,budget:@budget,
|
|
97
|
+
amount:@amount,requirements:@requirements,seller:@seller,fixed:@fixed,authority:authority)
|
|
98
|
+
end
|
|
99
|
+
def public_fixture
|
|
100
|
+
months = PERIODS.keys.select { |period| @issued_at <= LongPaymentExample.now(period) && LongPaymentExample.now(period) < @expires_at }.map { |period| month(period) }
|
|
101
|
+
{t0:@issued_at,exp:@expires_at,checkout_open:@checkout_open,payment_open:@payment_open,provider:@provider.public_to_pem,agent:@agent.public_to_pem,
|
|
102
|
+
merchant:@merchant.public_to_pem,profiles:{checkout:L::CHECKOUT_PROFILE_REF,payment:L::PROFILE_REF},periods:PERIODS,months:months}
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
def self.run
|
|
106
|
+
fixture = Fixture.new
|
|
107
|
+
months = PERIODS.keys.map { |period| fixture.month(period) }
|
|
108
|
+
raise "changed long Open" unless months.all? { |m| m[:verify_inputs][:open_sd_jwt] == fixture.payment_open && m[:verify_inputs][:checkout_inputs][:root_presentation] == fixture.checkout_open }
|
|
109
|
+
puts "Long wire: all 12 leap-year months verified with the same complete Open Checkout and Open Payment"
|
|
110
|
+
puts "Shared content iat/exp preserved; outer proof, current trust, challenge and order verified freshly"
|
|
111
|
+
puts "Wire verification reserves no occurrence or budget; protected Host period/authority storage is required"
|
|
112
|
+
puts "Synthetic only; no payment, settlement or generic MONTHLY calendar conformance is established"
|
|
113
|
+
fixture
|
|
114
|
+
end
|
|
115
|
+
end
|
|
116
|
+
LongPaymentExample.run if $PROGRAM_NAME == __FILE__
|