ap2_mandate_verifier 1.4.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 +31 -8
- data/README.md +31 -8
- data/SECURITY.md +8 -2
- data/docs/LONG_PAYMENT.md +82 -0
- data/docs/PAYMENT_ACCEPTANCE.md +90 -0
- data/docs/PAYMENT_POLICY.md +4 -2
- data/docs/PUBLIC_API.md +16 -2
- data/docs/RECURRING_PAYMENT.md +54 -0
- data/docs/RELEASE_140_CANDIDATE.md +2 -0
- data/docs/RELEASE_150_CANDIDATE.md +23 -0
- data/docs/RELEASE_160_CANDIDATE.md +30 -0
- data/docs/SUPPORT_CONTRACT.md +9 -1
- data/examples/conditional_checkout.rb +3 -3
- data/examples/long_payment.rb +116 -0
- data/examples/long_payment_acceptance.rb +89 -0
- data/examples/payment_acceptance.rb +77 -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 +344 -0
- data/lib/ap2_mandate_verifier/payment_acceptance.rb +285 -0
- 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 +6 -0
- metadata +22 -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,9 +1,32 @@
|
|
|
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
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)。
|
|
17
|
+
|
|
18
|
+
```ruby
|
|
19
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
20
|
+
dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inputs) if accepted.ticket
|
|
21
|
+
# 実際のprocessor呼出しはアプリ側。同じdispatch.processor_keyを使います。
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
検証成功・永続予約・決済完了は別の事象です。承認済みoccurrenceの保護、全worker共通の永続store、processorの冪等性・照会が必要です。旧1.xのverifierは変更せず、SQLite参照driverは任意の別依存です。
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
### 公開済み1.4.0:PISPと支払い実行日時の条件
|
|
28
|
+
|
|
29
|
+
承認したPISPと実行可能期間を指定し、アプリが独立して確認した決済サービス・実行予定時刻と照合できます。日時は解析した瞬間で比較し、旧1.xの既定動作を維持します。[仕様・API・公式との差](docs/PAYMENT_POLICY.md)、[3方式のRuby例](examples/payment_policy.rb)、[公開照合記録](docs/POST_RELEASE_140.md)。
|
|
7
30
|
|
|
8
31
|
### 公開済み1.3.0:CheckoutとPaymentの選択的開示
|
|
9
32
|
|
|
@@ -19,13 +42,13 @@
|
|
|
19
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)。検証成功は実行許可ではなく、永続的・原子的な単発利用管理と実決済は利用アプリの責任です。
|
|
20
43
|
|
|
21
44
|
```sh
|
|
22
|
-
gem install ap2_mandate_verifier --version 1.
|
|
23
|
-
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"
|
|
24
47
|
```
|
|
25
48
|
|
|
26
49
|
[English](README.md)
|
|
27
50
|
|
|
28
|
-
**公開済み安定版は1.
|
|
51
|
+
**公開済み安定版は1.5.0です。**
|
|
29
52
|
|
|
30
53
|
1.0.0では、既存のDirectと条件付きCheckoutの公開API・保守契約を確立しました。
|
|
31
54
|
0.8.0の引数・既定値・profile・結果の意味・保存形式と製品実装を維持します。
|
|
@@ -45,8 +68,8 @@ Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CO
|
|
|
45
68
|
正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
|
|
46
69
|
|
|
47
70
|
```sh
|
|
48
|
-
gem install ap2_mandate_verifier --version 1.
|
|
49
|
-
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"
|
|
50
73
|
```
|
|
51
74
|
|
|
52
75
|
[Ruby単体の実行例](examples/conditional_checkout.rb)はインストール済み公開APIだけを使い、
|
|
@@ -76,7 +99,7 @@ Rubyで購入委任データを検証する、AP2の固定profile向けGemです
|
|
|
76
99
|
正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
|
|
77
100
|
|
|
78
101
|
```sh
|
|
79
|
-
gem install ap2_mandate_verifier --version 1.
|
|
102
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
80
103
|
```
|
|
81
104
|
|
|
82
105
|
BundlerのGemfile:
|
data/README.md
CHANGED
|
@@ -1,9 +1,32 @@
|
|
|
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
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).
|
|
17
|
+
|
|
18
|
+
```ruby
|
|
19
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
20
|
+
dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inputs) if accepted.ticket
|
|
21
|
+
# Application-owned processor call uses dispatch.processor_key; no SDK payment call.
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
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.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
### Published1.4.0: PISP and execution-date Payment conditions
|
|
28
|
+
|
|
29
|
+
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).
|
|
7
30
|
|
|
8
31
|
### Published 1.3.0: selective Checkout and Payment
|
|
9
32
|
|
|
@@ -19,13 +42,13 @@ Published1.2.0 adds explicit `SelectivePayment` candidate-array disclosure: reta
|
|
|
19
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.
|
|
20
43
|
|
|
21
44
|
```sh
|
|
22
|
-
gem install ap2_mandate_verifier --version 1.
|
|
23
|
-
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"
|
|
24
47
|
```
|
|
25
48
|
|
|
26
49
|
[日本語](README.ja.md)
|
|
27
50
|
|
|
28
|
-
**Published stable: 1.
|
|
51
|
+
**Published stable: 1.5.0.**
|
|
29
52
|
|
|
30
53
|
1.0.0 establishes the stable public contract for the existing
|
|
31
54
|
Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
|
|
@@ -49,8 +72,8 @@ multi-item profile. Provider private keys never enter Agent operations.
|
|
|
49
72
|
Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
|
|
50
73
|
|
|
51
74
|
```sh
|
|
52
|
-
gem install ap2_mandate_verifier --version 1.
|
|
53
|
-
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"
|
|
54
77
|
```
|
|
55
78
|
|
|
56
79
|
The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
|
|
@@ -84,7 +107,7 @@ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readm
|
|
|
84
107
|
Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
|
|
85
108
|
|
|
86
109
|
```sh
|
|
87
|
-
gem install ap2_mandate_verifier --version 1.
|
|
110
|
+
gem install ap2_mandate_verifier --version 1.5.0
|
|
88
111
|
```
|
|
89
112
|
|
|
90
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,6 +16,8 @@ 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
|
|
|
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).
|
|
20
|
+
|
|
15
21
|
## 歴史記録:pre.3の対象と限界 / Historical pre.3 scope
|
|
16
22
|
|
|
17
23
|
`ap2_mandate_verifier 0.1.0.pre.3` is a fixed-profile research prerelease,
|
|
@@ -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.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Payment acceptance and idempotency support (published1.5.0)
|
|
2
|
+
|
|
3
|
+
[Verified public distribution](POST_RELEASE_150.md).
|
|
4
|
+
|
|
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.
|
|
6
|
+
|
|
7
|
+
## Stable identity and protected approval
|
|
8
|
+
|
|
9
|
+
A Checkout JWT hash (`transaction_id`), final Mandate hash or Receipt reference changes when an otherwise identical instruction is re-signed. None is sufficient as the business idempotency key. Use independently authenticated Host identifiers: `tenant_id`, `merchant_id` (the actual authority/account namespace), stable `operation_id`, `approval_id`, approved `occurrence_id` and `order_id`. Never allocate a fresh random operation/occurrence for each request or retry.
|
|
10
|
+
|
|
11
|
+
A protected Host approval backend must enroll the exact Checkout/payment semantics and pinned Receipt trust context before acceptance. `accept` cannot enroll or change authority from a received `approved: true` or arbitrary occurrence. The reference adapter enforces uniqueness of the business operation and of the approved occurrence. A secondary final-Closed-reference guard prevents dispatching the exact same final instruction under another occurrence. Wire hashes remain audit/Receipt bindings, not the sole replay key.
|
|
12
|
+
|
|
13
|
+
Canonical terms include the complete supported Checkout payload and payment fields. Only the technical Checkout-JWT hash is excluded from payment terms; parsed execution dates are normalized to exact instants. Changed amounts, products, provider/instrument or other terms conflict rather than create a new slot. JSON object key order is normalized; array order remains significant, so reordered business payload arrays can conservatively conflict. The original signed wires, Receipt reference and processor idempotency key stay pinned to the first reservation.
|
|
14
|
+
|
|
15
|
+
## Minimal integration
|
|
16
|
+
|
|
17
|
+
The optional SQLite reference adapter uses the separately installed `sqlite3 = 2.10.2` driver. It is not a new base-Gem runtime dependency. The ordinary verifier entry loads without SQLite. Missing driver/storage returns unavailable; there is no in-memory fallback.
|
|
18
|
+
|
|
19
|
+
```ruby
|
|
20
|
+
m = AP2MandateVerifier::PaymentAcceptance
|
|
21
|
+
# Protected one-time offline bootstrap only. Fails if the file already exists.
|
|
22
|
+
store = m::SQLiteStore.create(path: "/srv/app/payment_acceptance.sqlite3")
|
|
23
|
+
# Normal startup opens an EXISTING database; a lost file must never reset a ledger.
|
|
24
|
+
store = m::SQLiteStore.new(path: "/srv/app/payment_acceptance.sqlite3")
|
|
25
|
+
service = m::Service.new(store: store)
|
|
26
|
+
|
|
27
|
+
# All six IDs come from authenticated current application state.
|
|
28
|
+
scope = {tenant_id: "tenant-A", merchant_id: "shop", operation_id: "order-42/payment-1",
|
|
29
|
+
approval_id: "consent-99", occurrence_id: "payment-1", order_id: "order-42"}
|
|
30
|
+
# Call this only in the protected approval backend, never a request-driven flag.
|
|
31
|
+
store.authorize!(**scope, mode: :direct,
|
|
32
|
+
profile_ref: AP2MandateVerifier::Payment::PROFILE_REF,
|
|
33
|
+
checkout: approved_checkout, payment: approved_payment,
|
|
34
|
+
receipt_context: {trusted_public_key_pem: processor_public_key,
|
|
35
|
+
expected_issuer: "processor", expected_payment_id: "payment-42",
|
|
36
|
+
not_before: receipt_window_start, not_after: receipt_window_end})
|
|
37
|
+
|
|
38
|
+
accepted = service.accept(**scope, mode: :direct, verification_inputs: raw_payment_verify_inputs)
|
|
39
|
+
if accepted.ticket
|
|
40
|
+
# Fresh authenticated Host/trust/order/challenge/clock inputs; first wires unchanged.
|
|
41
|
+
dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_verify_inputs)
|
|
42
|
+
if dispatch
|
|
43
|
+
# Application-owned processor call MUST reuse dispatch.processor_key.
|
|
44
|
+
# The SDK itself performs no network request or payment.
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`mode` is `:direct`, `:conditional` or `:selective`. `verification_inputs` is the complete raw keyword hash of the corresponding existing `Payment.verify` or `SelectivePayment.verify`, including1.4 profile/context options where applicable. A caller-created verification result is not accepted as evidence. Current supported forms are fully verified; unsupported recurrence/budget formats remain rejected.
|
|
50
|
+
|
|
51
|
+
Enrollment, active authorization/occurrence checks, semantic comparison and reservation occur atomically in the reference DB. An immutable grant cannot be silently replaced; `revoke!` disables it without releasing an existing attempt. `start` reruns the full existing verification pipeline with fresh trusted inputs and requires every original signed Checkout/Payment wire to match. Payment expiry alone is insufficient: Checkout, trust and challenge can expire earlier. Grant/current-order/nonce checks in a production adapter must share its authoritative transaction with reservation/start CAS. A check in one DB followed by a CAS in another leaves a race; the reference grant is not a live connection to an external order or revocation service.
|
|
52
|
+
|
|
53
|
+
## States, retries and uncertain outcomes
|
|
54
|
+
|
|
55
|
+
| Observation | Meaning and permitted next step |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| `reserved` with opaque Ticket | First committed claim only; not purchase permission. Fresh `start` may yield one dispatch-coordination handle. |
|
|
58
|
+
| `pending` | Existing reservation/processing; no new Ticket or start rights. Read its stored original outcome/key. |
|
|
59
|
+
| `unknown` | Execution outcome uncertain; never automatically release, expire or take over. Query/reconcile using the original processor key. |
|
|
60
|
+
| `receipt_success` / `receipt_error` | Authentic reported Receipt outcome; no independent settlement or no-charge proof. No automatic re-execution. |
|
|
61
|
+
| `conflict` | Same operation/grant with different terms, scope or original instruction usage. No fresh slot. |
|
|
62
|
+
| `rejected` / `unavailable` | No capability. Unknown DB commit outcomes must not be treated as permission or retried as a new operation. |
|
|
63
|
+
|
|
64
|
+
Only the first successful fenced `reserved → processing` CAS returns an `Execution` handle. A crash after that commit but before a processor call can leave zero executions and a pending record. A crash after the call can leave one execution and the same pending record. The SDK cannot distinguish those cases by timeout. It intentionally provides no lease takeover, automatic release or re-execution API. Processor idempotency/lookup semantics and application reconciliation are necessary; database atomicity alone cannot cover an external side effect.
|
|
65
|
+
|
|
66
|
+
For an expired original presentation, use authenticated `lookup(**scope)` to retrieve existing state; it does not bypass fresh verification to create a new claim. Retrying with a re-signed equivalent presentation returns the first record without a Ticket. Never attach its old Receipt to a replacement Closed/Open wire. Returned first signed wires/reference describe the original attempt; no hidden candidate universe is reconstructed.
|
|
67
|
+
|
|
68
|
+
## Receipt and recovery
|
|
69
|
+
|
|
70
|
+
`finish(ticket:, receipt_jwt:, verified_at:)` authenticates a Receipt against the grant’s pinned issuer/key/payment ID/window and the first exact Closed bytes. Receipt time cannot predate successful start. `unknown(ticket:)` preserves an uncertain processing record. After a worker restart, `reconcile(**scope, receipt_jwt:, verified_at:)` may finalize processing/unknown with the same checks, but cannot return a Ticket or start again. `lookup(**scope)` is read-only.
|
|
71
|
+
|
|
72
|
+
A Receipt may arrive after the Mandate expires; its independently pinned Receipt window is distinct. Conflicting Receipt bytes/outcomes do not overwrite a completed record. Error Receipt, missing Receipt or response loss never frees the operation. Key rotation or changed Receipt trust after enrollment needs an explicit application recovery policy; the reference adapter does not silently replace trust.
|
|
73
|
+
|
|
74
|
+
## Reuse and new transactions
|
|
75
|
+
|
|
76
|
+
This API does not consume every Open Mandate globally. A reusable supported Open can lead to fresh Closed instructions for separately authorized new business occurrences. Those occurrences must be independently approved/enrolled and use their own stable operation identity. Arbitrary retry UUIDs are not new authority. The exact same final Closed cannot be dispatched twice under this local acceptance policy. Official recurrence/budget enforcement is not added by this release; applications must not infer reusable authority from an unsupported wire format.
|
|
77
|
+
|
|
78
|
+
## Persistence and adapter contract
|
|
79
|
+
|
|
80
|
+
SQLite is a local single-host reference using transactions, strict supported schema/index/FK checks, unique constraints, fencing and synchronous durable commits. Explicit initialization creates a private file; reopening requires the existing expected database. Missing/corrupt/unsupported schema is unavailable, with no repair/reset/migration or memory fallback. Use a protected local filesystem, one authoritative ledger for all workers and separate connections after fork. Do not create one ledger per worker or request.
|
|
81
|
+
|
|
82
|
+
Database deletion, rollback to an old backup, split-brain copies, broken filesystem locking/fsync, adversarial DB edits, NFS/multi-host replication or operator re-enrollment can invalidate protection. Restore must stop dispatch and reconcile against the processor. SQLite is not a distributed consensus service or a replacement for disaster recovery. Stored Checkout/payment terms and first wires may contain sensitive information; apply application access controls, retention and at-rest protection. Do not log Tickets/fences or raw payloads.
|
|
83
|
+
|
|
84
|
+
Custom adapters may integrate existing DB/Redis infrastructure but must implement atomic protected enrollment/uniqueness, read-and-claim, active-grant/order/occurrence CAS, no capability before durable commit, first-wire/processor-key retention, and monotonic fenced finalization. No check-then-insert, timeout reset or guessed success on I/O/commit error. They need their own independent concurrency/crash/durability tests; this SDK cannot attest an adapter’s persistence guarantees.
|
|
85
|
+
|
|
86
|
+
## Official evidence and guarantees
|
|
87
|
+
|
|
88
|
+
Adopted AP2 pin remains `b4587ac1d055888a73b4b21750973cffba961793`. Relevant docs/schema/SDK are byte-identical to observed official main `e1ea56db72a6385bce3e5c1112b3a56ce60acb43`; current changes there are outside those paths. [Issue346](https://github.com/google-agentic-commerce/AP2/issues/346), [Issue328](https://github.com/google-agentic-commerce/AP2/issues/328) and [Issue339](https://github.com/google-agentic-commerce/AP2/issues/339) remain discussions, not adopted requirements. [PR347](https://github.com/google-agentic-commerce/AP2/pull/347) adds sample reservations but does not establish stable business identity, terms binding and Receipt persistence as normative protocol behavior.
|
|
89
|
+
|
|
90
|
+
The [re-signing discussion](https://github.com/google-agentic-commerce/AP2/issues/346#issuecomment-6614173999) motivates stable merchant-scoped occurrences. AP2 still defines transaction_id from the Checkout JWT and Receipt reference from exact Closed bytes. Official SDK optional expected-Checkout bindings and hidden-constraint discussions do not relax this SDK’s existing strict verification. This local helper is application coordination around those cryptographic facts, not a new AP2 protocol or generic conformance/external exactly-once claim.
|
data/docs/PAYMENT_POLICY.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# PISP and execution-date Payment constraints (
|
|
1
|
+
# PISP and execution-date Payment constraints (published1.4.0)
|
|
2
2
|
|
|
3
3
|
New explicit complete/selective Payment profiles add `payment.allowed_pisps` and `payment.execution_date` without changing the existing1.x defaults. Direct and conditional issuance, presentation, strict verification, selective Checkout/Payment and Payment Receipt references share the existing cryptographic and Host verification paths. This SDK remains framework independent and performs no payment scheduling or execution.
|
|
4
4
|
|
|
@@ -45,7 +45,7 @@ The new profiles require both explicit `pisp` and `execution_date` in Closed and
|
|
|
45
45
|
|
|
46
46
|
The official PISP Schema describes the domain as secured by an eIDAS QWAC certificate. This library does not fetch/validate QWACs, establish legal authorization or authenticate a network endpoint from text. Applications own certificate/channel validation, enrollment, revocation and the provenance/freshness of their trusted PISP input. A syntactically valid domain or valid Mandate signature does not establish those facts.
|
|
47
47
|
|
|
48
|
-
`execution_at` is an independently controlled application execution-plan/operational instant. It must represent the same instant as signed `execution_date`. It is distinct from `verified_at`, which checks signature/Mandate freshness. Future plan verification does not prove that execution occurred or will later occur under that context. At the actual execution gate, the application must recheck the actual provider/time/current approval and a valid Mandate, atomically consume one-use state and reconcile uncertain outcomes. The SDK does not schedule, call a PISP or settle a payment.
|
|
48
|
+
`execution_at` is an independently controlled application execution-plan/operational instant. It must represent the same instant as signed `execution_date`. It is distinct from `verified_at`, which checks signature/Mandate freshness. Future plan verification does not prove that execution occurred or will later occur under that context. The existing maximum600secondMandate lifetime is unchanged; a future execution date does not extend its expiry. At the actual execution gate, the application must recheck the actual provider/time/current approval and a valid Mandate, atomically consume one-use state and reconcile uncertain outcomes. The SDK does not schedule, call a PISP or settle a payment.
|
|
49
49
|
|
|
50
50
|
## Date semantics
|
|
51
51
|
|
|
@@ -68,3 +68,5 @@ Direct Payment uses exact protected `approved_payment`, including PISP and execu
|
|
|
68
68
|
Adopted source remains AP2v0.2.0 `b4587ac1d055888a73b4b21750973cffba961793`: [Payment specification](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/docs/ap2/payment_mandate.md), [Open Schema](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/code/sdk/schemas/ap2/open_payment_mandate.json), [PISP Schema](https://github.com/google-agentic-commerce/AP2/blob/b4587ac1d055888a73b4b21750973cffba961793/code/sdk/schemas/ap2/types/pisp.json).
|
|
69
69
|
|
|
70
70
|
The normative text requires inclusive execution bounds. Schema permits weakly typed strings; it does not itself enforce this strict timestamp subset. The pinned Python evaluator compares date strings lexically and permits absent dates even with a date constraint. Its PISP evaluator does compare all three identity fields. Ruby’s parsed/context-bound behavior is an explicit safer supported subset, not an unqualified claim that all official high-level helpers behave identically. Source interoperability observed three lifecycle cases in each direction (Direct/complete conditional/selective conditional), twelve Receipt checks and62 negatives, plus six explicitly recorded upstream date-check disagreements. Separate positive variants cover PISP-only/date-only/one-sided constraints. Exact signed-wire hashes and actual runtime provenance are recorded with the candidate; supported claims do not extend to QWAC provenance, execution or generic AP2 conformance.
|
|
71
|
+
|
|
72
|
+
[Verified public artifact, tag and Release](POST_RELEASE_140.md). The original candidate preparation is retained as [historical evidence](RELEASE_140_CANDIDATE.md).
|
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
|
|
@@ -212,6 +212,20 @@ The additive `SelectiveCheckout` profile is available in published 1.3.0. See th
|
|
|
212
212
|
|
|
213
213
|
For the explicit selective Checkout profile, Evidence `original_root_graph_closure` records that every signed commitment and supplied disclosure was inspected and accounted for, allowing unresolved candidate leaves only at registered positions. It does not certify hidden preimages, their schema or uniqueness, or consent provenance. The checked scope covers the visible candidate subset and all mandatory conditions.
|
|
214
214
|
|
|
215
|
-
##
|
|
215
|
+
## Published1.4.0: explicit Payment policy profiles
|
|
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
|
+
|
|
219
|
+
## Published1.5.0: application-side Payment acceptance
|
|
220
|
+
|
|
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
|
+
|
|
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.4.0 candidate preparation
|
|
2
2
|
|
|
3
|
+
**Historical prepublication record.1.4.0 is now public; see [verified publication](POST_RELEASE_140.md). Do not repeat its push or substitute a rebuilt artifact.**
|
|
4
|
+
|
|
3
5
|
Status: release candidate preparation. Final exact-source/package/CI evidence and GO/HOLD recommendation are recorded in the PR and external manifest after verification. RubyGems publication, formalv1.4.0 tag, GitHub Release, announcements, deployment and real payment remain HOLD for Owner decision.
|
|
4
6
|
|
|
5
7
|
## Proposed notes
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# 1.5.0 release candidate preparation
|
|
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
|
+
|
|
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.
|
|
6
|
+
|
|
7
|
+
## Proposed notes and main use
|
|
8
|
+
|
|
9
|
+
1.5 adds opt-in transactional Payment acceptance: enroll a protected business occurrence, verify raw Mandates, reserve atomically, reverify before one fenced start and reconcile the original Receipt after uncertain outcomes. Re-signing does not create a new operation. Separately authorized new occurrences are supported without globally consuming every Open Mandate. Existing1.x verifier APIs/results and base runtime dependencies remain unchanged; SQLite reference persistence uses an optional pinned driver.
|
|
10
|
+
|
|
11
|
+
```ruby
|
|
12
|
+
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
13
|
+
dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inputs) if accepted.ticket
|
|
14
|
+
# Application-owned processor call reuses dispatch.processor_key; no SDK payment call.
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
State reservation, verification and settlement are distinct. No automatic release/takeover after timeout, Error Receipt, worker crash or response loss. Stable Host identity, protected enrollment, one authoritative durable store and processor lookup/idempotency remain application requirements. Receipt authenticity is not proof of settlement. Custom adapters need their own atomicity/durability tests.
|
|
18
|
+
|
|
19
|
+
## Final gates and publication procedure
|
|
20
|
+
|
|
21
|
+
Full supported MRI3.4.12/4.0.9 regressions; optional-driver absence isolation; source/installed acceptance tests; independent multi-process barrier/external counter/SIGKILL/restart and re-sign/new-occurrence controls; schema/commit/Receipt/expiry/privacy negatives; exact-HEAD independent review with zero unresolved P1/P2; Draft-first PRs, successful CI and verified merged-tree equality; candidate package metadata and every source/archive/installed file identical. Fixed builder/source-date epoch must reproduce the same archive; both MRIs install that one archive. Evidence/checksum remain outside their own package.
|
|
22
|
+
|
|
23
|
+
Only after Owner approves an exact candidate may publication begin. Recheck registry absence/source/bytes/review/CI; no blind retry of uncertain writes. Verify downloaded published bytes before formal tag/Release. No publication or deployment CI trigger may be added.
|
|
@@ -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,6 +1,14 @@
|
|
|
1
1
|
# AP2 Checkout Ruby SDK — support contract and history
|
|
2
2
|
|
|
3
|
-
## Current
|
|
3
|
+
## Current published scope
|
|
4
|
+
|
|
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.
|
|
10
|
+
|
|
11
|
+
## Historical1.0.0 baseline contract
|
|
4
12
|
|
|
5
13
|
**Published stable is 1.0.0.** It preserves the 0.8.0 product implementation and
|
|
6
14
|
acceptance contracts. The stable 1.x public surface is catalogued in
|