ap2_mandate_verifier 1.0.0 → 1.1.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 +35 -20
- data/README.md +41 -24
- data/SECURITY.md +3 -3
- data/docs/PAYMENT.md +70 -0
- data/docs/POST_RELEASE_MAINTENANCE.md +18 -14
- data/docs/PUBLIC_API.md +15 -10
- data/docs/RELEASE_100_CANDIDATE.md +7 -1
- data/docs/RELEASE_110_CANDIDATE.md +30 -0
- data/docs/SUPPORT_CONTRACT.md +25 -12
- data/examples/payment.rb +67 -0
- data/lib/ap2_mandate_verifier/payment.rb +361 -0
- data/lib/ap2_mandate_verifier/payment_receipt.rb +87 -0
- data/lib/ap2_mandate_verifier.rb +2 -0
- metadata +12 -7
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ccf21e0f34ee869d06ba2c4009d4d05ade3dca6acaa7b5e1b9afec056885474d
|
|
4
|
+
data.tar.gz: ba4defd871108b94890efcb3c09f6b409ea09d6bbcab2eb07c4e1f31b35c5ca7
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 474c60bf1bd26c0954e4061a4e8f93aacd6745ba537c847e4bb39d19dc39cdd6adf551f9f17c345b936b3e533b5124be88f9942d8591e66dd6191d398f132959
|
|
7
|
+
data.tar.gz: 88849dd07b7fa91576bd6dfc2dffb1f6b0bc980de61c96fbab79ba41536161352d8f2359003403eddb312331ded32a6ade4393f5fefa54b70d50cbe93d544b77
|
data/README.ja.md
CHANGED
|
@@ -1,42 +1,47 @@
|
|
|
1
1
|
# AP2 Mandate Verifier — Checkout委任のRuby SDK
|
|
2
2
|
|
|
3
|
+
### 次期候補:Payment(未公開)
|
|
4
|
+
|
|
5
|
+
1.1.0案ではDirect/条件付きPayment Mandateと成功/エラーPayment Receiptを追加します。**まだ公開されていません。公開済み1.0.0はCheckout対応です。** [新API・制約・信頼境界](docs/PAYMENT.md)、[Ruby単体サンプル](examples/payment.rb)、[公開準備](docs/RELEASE_110_CANDIDATE.md)を参照してください。検証成功は実行許可ではなく、永続的・原子的な単発利用管理と実決済は利用アプリの責任です。
|
|
6
|
+
|
|
7
|
+
|
|
3
8
|
[English](README.md)
|
|
4
9
|
|
|
5
|
-
**公開済み安定版は
|
|
10
|
+
**公開済み安定版は1.0.0です。**
|
|
6
11
|
|
|
7
|
-
1.0.0では、既存のDirectと条件付きCheckoutの公開API
|
|
8
|
-
0.8.0の引数・既定値・profile
|
|
9
|
-
以下の公開版インストール手順は引き続き0.8.0です。
|
|
12
|
+
1.0.0では、既存のDirectと条件付きCheckoutの公開API・保守契約を確立しました。
|
|
13
|
+
0.8.0の引数・既定値・profile・結果の意味・保存形式と製品実装を維持します。
|
|
10
14
|
[公開API契約](docs/PUBLIC_API.md)、[保守方針](docs/POST_RELEASE_MAINTENANCE.md)、
|
|
11
|
-
[
|
|
15
|
+
[1.0.0 Release notes](docs/RELEASE_100.md)を参照してください。
|
|
16
|
+
公式配布Gemは保持候補と一致し、正確なsource・bytes・検証範囲は[公開照合記録](docs/POST_RELEASE_100.md)に記録しています。
|
|
12
17
|
|
|
13
|
-
## 条件付き購入委任
|
|
18
|
+
## 条件付き購入委任
|
|
14
19
|
|
|
15
|
-
|
|
20
|
+
0.8.0で追加した`ConditionalCheckout.issue_open`、`.issue_closed`、`.present` を利用できます。
|
|
16
21
|
A/Bから1個とCを2個という条件を承認サービスが登録Agent鍵へOpenとして発行し、
|
|
17
22
|
Agentが条件に合う販売者署名CheckoutをClosedにします。既存 `InputBuilder.verify` と
|
|
18
23
|
`CheckoutReceipt.sign/verify` へ接続します。全候補開示の複数商品profileを維持し、
|
|
19
24
|
Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CONDITIONAL_CHECKOUT.md)、
|
|
20
|
-
[
|
|
25
|
+
[条件付き委任のコード例](docs/RELEASE_080.md)・[1.0.0公開照合記録](docs/POST_RELEASE_100.md)を参照してください。
|
|
21
26
|
|
|
22
27
|
正式対応MRI 3.4.12/4.0.9で動くRuby単体の導入例です。source checkoutやRailsは不要です:
|
|
23
28
|
|
|
24
29
|
```sh
|
|
25
|
-
gem install ap2_mandate_verifier --version 0.
|
|
26
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.
|
|
30
|
+
gem install ap2_mandate_verifier --version 1.0.0
|
|
31
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.0.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
27
32
|
```
|
|
28
33
|
|
|
29
34
|
[Ruby単体の実行例](examples/conditional_checkout.rb)はインストール済み公開APIだけを使い、
|
|
30
35
|
3明細・候補選択・異なる要件数量・同一商品の別行からSuccess/Error Receiptまで動きます。
|
|
31
36
|
Success後は消費済み、Error後は再提示方針を再判断、Receipt未到着や結果不明は保留です。
|
|
32
37
|
本人認証・同意・購買権限・信頼先登録・永続的な重複防止・注文や決済の実行はアプリ責務です。
|
|
33
|
-
0.
|
|
38
|
+
文書化された0.8.0 APIの利用コードは変更不要です。依存制約の更新は下記を参照してください。
|
|
34
39
|
|
|
35
|
-
|
|
40
|
+
Directと条件付き委任は1販売者・1〜8明細・複数商品と数量を扱います。1.0.0でも既存DirectとOpen→Closedの契約を維持します。
|
|
36
41
|
|
|
37
42
|
## 複数商品と数量
|
|
38
43
|
|
|
39
|
-
|
|
44
|
+
複数明細profile `ap2.checkout.single_merchant_multi_item` v1は、`InputBuilder.trust`、`CheckoutJWT.sign`、`CheckoutReceipt.reference/sign/verify` に `profile_ref:` を渡して明示選択します。完全検証は認証済みtrustの選択に従います。既定の `ap2.checkout.single_merchant_sku` v1は定義・hash・1明細の受理範囲を維持します。
|
|
40
45
|
|
|
41
46
|
単一販売者・単一Checkout・単一通貨で最大8明細を扱い、数量違いと同一商品の別行を支持します。開示候補の商品IDを整数最大流で照合し、全要件と全注文数量を過不足なく一度ずつ充当します。数量不足・余剰は拒否し、要件IDと明細IDは別の識別子です。[詳細・移行案内](docs/MULTI_ITEM_CHECKOUT.md)、[合成入力による一連の動作例](examples/multi_item_checkout.rb)、[公式Python SDKとの数量不足・空候補・Receipt参照の差異](docs/MULTI_ITEM_INTEROP.md)を参照してください。
|
|
42
47
|
|
|
@@ -53,21 +58,31 @@ Rubyで購入委任データを検証する、AP2の固定profile向けGemです
|
|
|
53
58
|
正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
|
|
54
59
|
|
|
55
60
|
```sh
|
|
56
|
-
gem install ap2_mandate_verifier --version 0.
|
|
61
|
+
gem install ap2_mandate_verifier --version 1.0.0
|
|
57
62
|
```
|
|
58
63
|
|
|
59
64
|
BundlerのGemfile:
|
|
60
65
|
|
|
61
66
|
```ruby
|
|
62
|
-
gem "ap2_mandate_verifier", "
|
|
67
|
+
gem "ap2_mandate_verifier", "~> 1.0"
|
|
63
68
|
```
|
|
64
69
|
|
|
65
70
|
runtime依存はJSON 2.19.9、JWT 3.3.0、base64 0.3.0、OpenSSL gem 4.0.2、Digest 3.2.1に固定しています。通常導入には依存の取得・buildが伴い得ます。衝突回避のために固定条件を緩めないでください。Rubyの解決範囲は、その間の全Ruby版・OS・native providerへの対応保証ではありません。[対応契約](docs/SUPPORT_CONTRACT.md)を参照してください。
|
|
66
71
|
|
|
72
|
+
### 0.8.0からの更新
|
|
73
|
+
|
|
74
|
+
文書化された0.8.0 API・profile・既定値・保存形式は互換性を維持します。
|
|
75
|
+
`~> 0.8.0`等の依存制約では1.0.0を選択しないため、上記の`~> 1.0`へ変更し、
|
|
76
|
+
アプリケーションのlockfileを更新してください。
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
bundle update ap2_mandate_verifier
|
|
80
|
+
```
|
|
81
|
+
|
|
67
82
|
## 販売者署名とReceipt
|
|
68
83
|
|
|
69
84
|
注文JWTを署名し、利用アプリが明示した処理結果をReceiptとして署名できます。
|
|
70
|
-
0.5.0で追加され、0.
|
|
85
|
+
0.5.0で追加され、1.0.0でも利用できるAPIです。この抜粋は既定の単一商品profileです。`checkout`は注文Hash、`key`はアプリ所有のP-256鍵、
|
|
71
86
|
`received_closed_sd_jwt`は受信した最終inline SD-JWT原文、`now`はアプリの時計です。
|
|
72
87
|
|
|
73
88
|
```ruby
|
|
@@ -158,7 +173,7 @@ end
|
|
|
158
173
|
|
|
159
174
|
Gemは署名、支持する開示閉包、委任、購入/Host binding、制約・期限を検査します。Hostは認証済み・独立・最新のtrust/鍵/失効、注文・Challenge状態、時計を供給します。実行直前に現在状態と期限を再照合し、nonceの原子消費+注文CAS、不明結果の回復、最終許可・決済判断を担当します。`prepare`/`restore` は保存元の認証やnonce未使用を証明しません。
|
|
160
175
|
|
|
161
|
-
公開済み0.
|
|
176
|
+
公開済み1.0.0は既定の単一商品profileと明示選択の[複数明細profile](docs/MULTI_ITEM_CHECKOUT.md)を維持し、条件付き発行には後者を使います。全候補開示と既存上限を守り、未知・非対応形式は拒否します。一般AP2/全Schema、実Issuer互換性、新しい選択的開示profile、Rails adapter、DB/決済実行、数値性能保証は対象外です。実Issuer・実Hostの本番GOとPhase 2-Bは引き続き別のHOLDです。
|
|
162
177
|
|
|
163
178
|
### APIの使い分け
|
|
164
179
|
|
|
@@ -168,7 +183,7 @@ Gemは署名、支持する開示閉包、委任、購入/Host binding、制
|
|
|
168
183
|
| `Buyer.issue_closed/present_closed/verify` | 確定注文を承認するDirect発行・構造確認を伴う提示・Directの完全検証。 |
|
|
169
184
|
| `CheckoutJWT.sign/verify` | 販売者のCheckout署名と、承認前の真正性確認。 |
|
|
170
185
|
| `CheckoutReceipt.reference/sign/verify` | 最終Mandate原文の参照計算、明示的なアプリ結果の署名、Receiptの真正性確認。 |
|
|
171
|
-
| `InputBuilder.verify(**business_information)` |
|
|
186
|
+
| `InputBuilder.verify(**business_information)` | 推奨業務情報経路。入力を組み立て、完全検証します。発行前準備・復元は上の例の別処理です。 |
|
|
172
187
|
| `verify_checkout(**inputs)` | 既存の7入力を直接渡すOpen → Agent Closedの完全検証。trust/selection/Host JSONも呼出側が渡します。 |
|
|
173
188
|
| `verify_research(**inputs)` | 同じ7入力検証経路の維持された名称。非推奨警告はありません。 |
|
|
174
189
|
| `verify(presentation_json:)` | 旧JSON構文検査のみ。成功Evidenceを返しません。 |
|
|
@@ -177,10 +192,10 @@ Gemは署名、支持する開示閉包、委任、購入/Host binding、制
|
|
|
177
192
|
|
|
178
193
|
## 詳細リンク
|
|
179
194
|
|
|
180
|
-
- [1.x
|
|
195
|
+
- [1.xの公開API・失敗・profile・保存契約](docs/PUBLIC_API.md)。従来の部分検証APIも維持し、成功Evidenceを返さない意味を変えません。
|
|
181
196
|
- [業務情報の一連の利用とRails対応付け](docs/INPUT_BUILDER.ja.md)、[完全Ruby例](examples/input_builder.rb)、[変更前の例](examples/input_builder_before.rb)。
|
|
182
197
|
- [支持入力・上限・Result/Evidence契約](docs/SUPPORT_CONTRACT.md)、[Issuer/Host責務](docs/ISSUER_HOST_MINIMUM_CONTRACT.md)。
|
|
183
|
-
- [0.
|
|
198
|
+
- [1.0.0 Release notes](docs/RELEASE_100.md)、[公開・撤回記録](docs/PROJECT_STATUS.md)、[変更履歴](CHANGELOG.md)。リポジトリREADMEの変更で公開Gemを再build・置換しません。
|
|
184
199
|
- [固定commitの旧7入力・保存FULL例](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.ja.md#保存済み合成入力で試す)、[過去版の配布物・provider証拠](research/stable010_release_linux_package/README.md)、[過去の概念図](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.ja.md#図で見るap2の概念)。履歴は保存していますが、現在の連携手順や対応範囲を広げる根拠ではありません。
|
|
185
200
|
- [脆弱性報告](SECURITY.md)、[保守方針](docs/POST_RELEASE_MAINTENANCE.md)、[製品方針](docs/PRODUCT_VISION.md)。秘密鍵・実Mandate・個人情報を報告に含めないでください。
|
|
186
201
|
|
data/README.md
CHANGED
|
@@ -1,30 +1,38 @@
|
|
|
1
1
|
# AP2 Mandate Verifier — Ruby SDK for Checkout delegation
|
|
2
2
|
|
|
3
|
+
### Unpublished next candidate: Payment
|
|
4
|
+
|
|
5
|
+
The proposed 1.1.0 candidate adds Direct and conditional Payment Mandates plus signed Success/Error Payment Receipts. It is **not published**. Published 1.0.0 remains Checkout-only. See [Payment APIs, supported constraints and trust boundaries](docs/PAYMENT.md), the [plain Ruby lifecycle sample](examples/payment.rb), and [release preparation](docs/RELEASE_110_CANDIDATE.md). Verification does not grant execution permission; durable one-use state and actual payment remain application responsibilities.
|
|
6
|
+
|
|
7
|
+
|
|
3
8
|
[日本語](README.ja.md)
|
|
4
9
|
|
|
5
|
-
**Published stable:
|
|
10
|
+
**Published stable: 1.0.0.**
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
1.0.0 establishes the stable public contract for the existing
|
|
8
13
|
Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
|
|
9
|
-
profiles, result meanings
|
|
10
|
-
|
|
14
|
+
profiles, result meanings, saved formats and runtime implementation.
|
|
15
|
+
See [the public API contract](docs/PUBLIC_API.md),
|
|
11
16
|
[maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and
|
|
12
|
-
[
|
|
17
|
+
[1.0.0 release notes](docs/RELEASE_100.md). The official Gem matches the retained
|
|
18
|
+
candidate; [publication verification](docs/POST_RELEASE_100.md) records its exact
|
|
19
|
+
source, bytes and validation scope.
|
|
13
20
|
|
|
14
|
-
## Conditional purchase delegation
|
|
21
|
+
## Conditional purchase delegation
|
|
15
22
|
|
|
16
|
-
|
|
23
|
+
Available since 0.8.0, `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`
|
|
24
|
+
support this flow:
|
|
17
25
|
approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
|
|
18
26
|
a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
|
|
19
27
|
`CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
|
|
20
28
|
multi-item profile. Provider private keys never enter Agent operations.
|
|
21
|
-
[API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [
|
|
29
|
+
[API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [conditional code sample](docs/RELEASE_080.md) and [1.0.0 publication verification](docs/POST_RELEASE_100.md).
|
|
22
30
|
|
|
23
31
|
Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
|
|
24
32
|
|
|
25
33
|
```sh
|
|
26
|
-
gem install ap2_mandate_verifier --version 0.
|
|
27
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.
|
|
34
|
+
gem install ap2_mandate_verifier --version 1.0.0
|
|
35
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.0.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
28
36
|
```
|
|
29
37
|
|
|
30
38
|
The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
|
|
@@ -32,19 +40,18 @@ public APIs, three rows, candidate choice, different requirement quantities and
|
|
|
32
40
|
repeated products through both Receipt outcomes. Success consumes the operation;
|
|
33
41
|
Error requires a new policy decision; missing Receipt or uncertain effect remains
|
|
34
42
|
pending. Authentication, consent, enrollment, durable replay prevention and actual
|
|
35
|
-
order/payment execution remain app-owned.
|
|
36
|
-
|
|
43
|
+
order/payment execution remain app-owned. Documented 0.8.0 API use needs no source
|
|
44
|
+
migration; update the dependency constraint as described below.
|
|
37
45
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
[the publication record](docs/PROJECT_STATUS.md#080-publication).
|
|
46
|
+
Direct and conditional workflows cover one merchant and 1–8 Checkout lines,
|
|
47
|
+
including multiple products and quantities. Existing Direct and both Open→Closed
|
|
48
|
+
profiles retain their contracts in 1.0.0.
|
|
42
49
|
|
|
43
50
|
## Multiple items and quantities
|
|
44
51
|
|
|
45
52
|
Explicitly select `profile_ref: "ap2.checkout.single_merchant_multi_item"` when creating trust with `InputBuilder.trust`, signing a checkout with `CheckoutJWT.sign`, and using `CheckoutReceipt.reference/sign/verify`. The complete verifier follows the authenticated trust selection. The default `ap2.checkout.single_merchant_sku` v1 retains its exact definition, hash and one-line acceptance range.
|
|
46
53
|
|
|
47
|
-
The
|
|
54
|
+
The multi-item v1 profile supports one merchant, one checkout, one currency and up to eight lines, with different quantities and repeated product IDs on distinct lines. It matches all disclosed product candidates using integer maximum flow: every requirement and every ordered unit must be consumed exactly once. Quantity shortages and extras reject. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md), [synthetic runnable lifecycle](examples/multi_item_checkout.rb), and [official Python SDK differences](docs/MULTI_ITEM_INTEROP.md) for shortage, empty-candidate and Receipt-reference behavior.
|
|
48
55
|
|
|
49
56
|
Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile. The Gem checks signed data against independently supplied Host trust and order information, then returns immutable Evidence. **Verification success is not purchase or payment permission.**
|
|
50
57
|
|
|
@@ -59,20 +66,30 @@ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readm
|
|
|
59
66
|
Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
|
|
60
67
|
|
|
61
68
|
```sh
|
|
62
|
-
gem install ap2_mandate_verifier --version 0.
|
|
69
|
+
gem install ap2_mandate_verifier --version 1.0.0
|
|
63
70
|
```
|
|
64
71
|
|
|
65
72
|
Or add to your Gemfile:
|
|
66
73
|
|
|
67
74
|
```ruby
|
|
68
|
-
gem "ap2_mandate_verifier", "
|
|
75
|
+
gem "ap2_mandate_verifier", "~> 1.0"
|
|
69
76
|
```
|
|
70
77
|
|
|
71
78
|
Runtime dependencies are pinned to JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. Normal installation may download/build dependencies; do not relax the pins to work around a conflict. The Ruby resolution interval is not certification of every Ruby version, OS or native provider. See the [support contract](docs/SUPPORT_CONTRACT.md).
|
|
72
79
|
|
|
80
|
+
### Upgrading from 0.8.0
|
|
81
|
+
|
|
82
|
+
Documented 0.8.0 APIs, profiles, defaults and saved formats remain compatible.
|
|
83
|
+
A constraint such as `~> 0.8.0` excludes 1.0.0. Change it to `~> 1.0` as above and
|
|
84
|
+
update this Gem in the application's lockfile:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
bundle update ap2_mandate_verifier
|
|
88
|
+
```
|
|
89
|
+
|
|
73
90
|
## Merchant signing and Receipt
|
|
74
91
|
|
|
75
|
-
Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 0.
|
|
92
|
+
Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 1.0.0; the excerpt uses the default single-SKU profile.
|
|
76
93
|
Here `checkout` is the application order Hash, `key` its P-256 signing key,
|
|
77
94
|
`received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
|
|
78
95
|
|
|
@@ -165,7 +182,7 @@ Exceptions, process failure and missing results also never authorize an operatio
|
|
|
165
182
|
|
|
166
183
|
The Gem checks signatures, supported disclosure closure, delegation, purchase/Host bindings, constraints and validity. The Host supplies authenticated, independent and current trust/keys/revocation, order/challenge state and clock. Before acting, it rechecks current state and validity, atomically consumes the nonce with order CAS, handles uncertain outcomes, and makes the final authorization/payment decision. `prepare`/`restore` do not authenticate storage or prove an unused nonce.
|
|
167
184
|
|
|
168
|
-
Published 0.
|
|
185
|
+
Published 1.0.0 retains the default `ap2.checkout.single_merchant_sku` v1 and the
|
|
169
186
|
explicit [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Conditional issuance
|
|
170
187
|
uses that multi-item profile, with all candidates disclosed and existing limits.
|
|
171
188
|
Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer
|
|
@@ -181,7 +198,7 @@ Issuer/Host production GO and Phase 2-B remain separate HOLDs.
|
|
|
181
198
|
| `Buyer.issue_closed/present_closed/verify` | Direct exact-order issuance, structural presentation and full Direct verification. |
|
|
182
199
|
| `CheckoutJWT.sign/verify` | Merchant Checkout signing and authentication before approval. |
|
|
183
200
|
| `CheckoutReceipt.reference/sign/verify` | Original final-Mandate reference, explicit application outcome signing and Receipt authentication. |
|
|
184
|
-
| `InputBuilder.verify(**business_information)` | Recommended business-data path
|
|
201
|
+
| `InputBuilder.verify(**business_information)` | Recommended business-data path. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
|
|
185
202
|
| `verify_checkout(**inputs)` | Complete Open → Agent Closed verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
|
|
186
203
|
| `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
|
|
187
204
|
| `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
|
|
@@ -190,10 +207,10 @@ Malformed assembly arguments, including missing keywords, to `InputBuilder.verif
|
|
|
190
207
|
|
|
191
208
|
## More detail
|
|
192
209
|
|
|
193
|
-
- [
|
|
210
|
+
- [1.x public API, errors, profiles and persistence contract](docs/PUBLIC_API.md). Existing partial-verification APIs remain supported and never return successful Evidence.
|
|
194
211
|
- [Business-data lifecycle and Rails mapping](docs/INPUT_BUILDER.md), [complete Ruby example](examples/input_builder.rb) and [before/after example](examples/input_builder_before.rb).
|
|
195
212
|
- [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
|
|
196
|
-
- [0.
|
|
213
|
+
- [1.0.0 Release notes](docs/RELEASE_100.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
|
|
197
214
|
- [Pinned historical seven-input / saved FULL example](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#try-the-saved-synthetic-example), [older artifact/provider evidence](research/stable010_release_linux_package/README.md) and [historical conceptual diagrams](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#illustrated-concepts-japanese-diagrams). These records are preserved, not current integration instructions or broader support claims.
|
|
198
215
|
- [Security reporting](SECURITY.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and [product direction](docs/PRODUCT_VISION.md). Do not include secrets, real Mandates or personal data in reports.
|
|
199
216
|
|
data/SECURITY.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
## 現在の対象と限界 / Current scope
|
|
4
4
|
|
|
5
|
-
[Published 0.
|
|
5
|
+
[Published 1.0.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/1.0.0) is a framework-independent Ruby SDK for the documented AP2 Checkout profiles, including Direct and conditional issuance, presentation, verification and Checkout Receipt confirmation. See [publication evidence](docs/POST_RELEASE_100.md), the stable [PUBLIC_API](docs/PUBLIC_API.md) and [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for its scope and limitations.
|
|
6
6
|
|
|
7
|
-
現在の配布版は、対応profileのDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を備えた、フレームワーク非依存のRuby SDK **
|
|
7
|
+
現在の配布版は、対応profileのDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を備えた、フレームワーク非依存のRuby SDK **1.0.0**です。1.xの保守対象は最新マイナー系列の最新修正版のみとし、旧マイナー・0.x・preへのbackportは約束しません。現行版の報告窓口は以下のままです。保守対象・互換性・セキュリティ修正の扱いは[公開後の整備](docs/POST_RELEASE_MAINTENANCE.md)を参照してください。
|
|
8
8
|
|
|
9
|
-
The
|
|
9
|
+
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
10
|
|
|
11
11
|
Evidence is not Host ALLOW or payment permission. Real Issuer trust, specific Host production GO and Phase 2-B remain HOLD; general AP2/full Schema, full Phase2-A PASS, worst-resource/concurrency and global native/runtime safety are not established. No SLA, fixed support term or response/fix deadline is promised. Existing provider/JSON advisory-metadata and communication-accounting limitations remain recorded; publication does not erase them. New execution, changes or releases require their own approval.
|
|
12
12
|
|
data/docs/PAYMENT.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Payment APIs — unpublished 1.1.0 candidate
|
|
2
|
+
|
|
3
|
+
Published 1.0.0 remains the Checkout-only API contract. These additive APIs do not change its arguments, defaults, profiles, accepted inputs, results, storage or Checkout Receipt references. The Gem is framework independent; Rails is optional.
|
|
4
|
+
|
|
5
|
+
## Supported profile and specification
|
|
6
|
+
|
|
7
|
+
`Payment::PROFILE_REF = "ap2.payment.single.complete.1"`: one immediate payment, ES256/P-256, SHA256, one Provider root and at most one Agent hop, full content. Root/terminal accepts inline content or exactly one two-element content disclosure. Issuance uses one content disclosure for root and inline terminal. No other commitments/disclosures, nested SD, hidden claims, decoys, re-delegation or unknown fields are accepted. The profile is selected by these APIs, never by received claims.
|
|
8
|
+
|
|
9
|
+
Adopted source: [AP2 b4587ac1d055888a73b4b21750973cffba961793](https://github.com/google-agentic-commerce/AP2/tree/b4587ac1d055888a73b4b21750973cffba961793). Upstream e1ea56db72a6385bce3e5c1112b3a56ce60acb43 has the same relevant specification, Schemas and Python SDK. Decisions follow payment_mandate.json, open_payment_mandate.json, payment_receipt.json, types/amount.json and agent_authorization.md, with SDK behavior compared separately.
|
|
10
|
+
|
|
11
|
+
| Reference | Exact SHA256 input, base64url without padding |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| Payment transaction_id | Original Merchant Checkout JWT bytes |
|
|
14
|
+
| payment.reference.conditional_transaction_id | Original Open Checkout SD-JWT bytes, including disclosures in original order and terminal `~` |
|
|
15
|
+
| Agent sd_hash | Original Open Payment SD-JWT bytes including terminal `~` |
|
|
16
|
+
| Payment Receipt reference | Final Closed Payment SD-JWT alone, including disclosures and terminal `~`; excludes Open and `~~` separator |
|
|
17
|
+
|
|
18
|
+
Do not hash parsed/rebuilt JSON, compact-only JWT or the entire chain. `Presentation.chain` removes the Open's terminal `~`, then joins with `~~`; separate original strings remain authoritative for storage/hashing.
|
|
19
|
+
|
|
20
|
+
Closed `vct` is `mandate.payment.1`; Open is `mandate.payment.open.1`. Integer `iat` and `exp` are mandatory in this stricter profile, `iat <= verified_at < exp`, maximum lifetime 600 seconds. Conditional terminal iat equals Closed iat, cannot predate Open, cannot be more than 300 seconds old, and Closed exp cannot exceed Open exp. No clock defaults or skew at expiry. Amount is an integer minor unit in the existing supported Checkout currencies (USD/EUR/JPY), within existing scoped amount bounds. Decimal/float/bool values reject. Payee is the exact verified Checkout merchant, including name. Instrument has id/type and optional description; full object equality applies.
|
|
21
|
+
|
|
22
|
+
Open requires exactly one each of amount_range (currency, max and optional min), allowed_payees, allowed_payment_instruments and payment.reference. The first three are supplied to issuance; reference is calculated from supplied original Open Checkout. Lists allow 1–8 unique entries. Optional fixed payee/payment_amount/payment_instrument must remain completely unchanged. During verification the reference is matched to the Open in the fully verified Checkout chain. Recurrence/budget, PISP, execution_date/risk_data, arbitrary constraints, other algorithms and partial disclosure reject explicitly through the redacted failure contract.
|
|
23
|
+
|
|
24
|
+
## Public APIs and independent inputs
|
|
25
|
+
|
|
26
|
+
All methods are under `AP2MandateVerifier`, all parameters are keywords. See [executable plain Ruby example](../examples/payment.rb) for full calls.
|
|
27
|
+
|
|
28
|
+
| Method | Required inputs and result |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `Payment.details` | checkout_jwt, trusted_merchant_public_key_pem, expected_merchant_id, payment_instrument → immutable four-field payment Hash. Authenticates Merchant JWT and calculates amount/payee/transaction reference; does not authenticate consent or a Checkout Mandate. |
|
|
31
|
+
| `Payment.issue_direct` | payment, approved_payment, issued_at, expires_at, signer, public_key_pem → Presentation. Every payment field must equal the app's protected consent record. |
|
|
32
|
+
| `Payment.issue_open` | open_checkout_sd_jwt, constraints, fixed, agent_public_key_pem, issued_at, expires_at, signer, public_key_pem → original frozen Open String. App authenticates consent to conditions and the source of Open Checkout. |
|
|
33
|
+
| `Payment.issue_closed` | open_sd_jwt, payment, trusted_provider_public_key_pem, agent_public_key_pem, audience, nonce, verified_at, signer → Presentation. Verifies Provider, Agent binding, time and Open constraints. Full Checkout authentication occurs in verify; issuing alone grants no permission. |
|
|
34
|
+
| `Payment.present` | closed_sd_jwt, optional open_sd_jwt (default nil) → Presentation. Structural/binding checks only. |
|
|
35
|
+
| `Payment.verify` | closed_sd_jwt, checkout_mode (:direct/:conditional), checkout_inputs, expected_payment, trusted_provider_public_key_pem, verified_at; optional open_sd_jwt, expected_agent_public_key_pem, expected_audience, expected_nonce (all default nil) → Verification. Conditional requires all four optionals; Direct forbids them. |
|
|
36
|
+
| `Payment.reference` / `PaymentReceipt.reference` | closed_sd_jwt → frozen exact final-wire reference; structural validation, no authentication/authorization. |
|
|
37
|
+
|
|
38
|
+
Direct checkout_inputs is exactly the six `Buyer.verify` keywords; conditional is exactly the seven raw `verify_checkout` keywords. Both rerun complete existing Checkout verification at the same verified_at. Conditional raw inputs can be prepared using `InputBuilder.inputs`. Inputs are snapshotted before verification. The app must select expected Checkout, amount/currency/payee/instrument, keys, audience/challenge and time independently of received Payment data. Never calculate expectations by decoding received unverified Payment. Direct trusted consent backend may call issue_direct; a boolean from an Agent is not consent authentication.
|
|
39
|
+
|
|
40
|
+
`Presentation` exposes frozen open_sd_jwt (nil for Direct), closed_sd_jwt and chain. `Verification` exposes verified?, code (:payment_verified or :payment_verification_failed), immutable payment claims, reference and expires_at (nil on failure). It does not mint Checkout Evidence or an execution permit. Constructors are private. All issuance/preparation/presentation/reference failures, including missing/unknown keywords, raise redacted `Payment::Invalid < ArgumentError`, without cause. verify returns a failed Verification for missing/unknown keywords, malformed input, dependency/internal failures. Positional binding errors can raise. No failure distinguishes bad input from unavailable processing. Hold/reconcile uncertain signer outcomes before issuing again.
|
|
41
|
+
|
|
42
|
+
Wire limit is 32,769 bytes, one final `~` plus at most one content disclosure, decoded JWT body <=24,576 bytes; strict JSON duplicate/size/depth checks are reused. Checkout fields retain their existing bounds. No network/DB operations occur.
|
|
43
|
+
|
|
44
|
+
## Payment Receipt
|
|
45
|
+
|
|
46
|
+
`PaymentReceipt.sign` requires closed_sd_jwt, issuer, outcome (Success/Error), payment_id, issued_at, signer and public_key_pem. Success additionally requires psp_confirmation_id/network_confirmation_id; Error requires error/error_description. Opposite outcome fields are forbidden. Optional outcome fields default nil. IDs and issuer are nonempty strings <=512 bytes, error_description <=2,048 bytes. A fixed redacted `PaymentReceipt::Invalid` is raised on failure. Result exposes jwt/reference.
|
|
47
|
+
|
|
48
|
+
`PaymentReceipt.verify` requires jwt, closed_sd_jwt, trusted_public_key_pem, expected_issuer, expected_payment_id, not_before, not_after and verified_at. It authenticates ES256 JWT, exact outcome-specific fields, issuer/payment ID/reference and explicit time window: not_before <= iat <= verified_at <= not_after. Result exposes verified?, code (:payment_receipt_verified/:payment_receipt_verification_failed), outcome, payment_id, confirmation IDs, error and error_description; `payment_succeeded?` and `payment_rejected?` are both false on verification failure. Failure returns no claims. Receipt authentication does not re-authorize a Mandate or establish actual payment completion; it authenticates the selected issuer's reported outcome.
|
|
49
|
+
|
|
50
|
+
## Python/Schema differences and limits
|
|
51
|
+
|
|
52
|
+
- Schema const and normative text use `.1` vct suffix; stale descriptions omit it. Adopt const.
|
|
53
|
+
- Schema amounts/ranges are integer minor units; prose decimal examples are not accepted.
|
|
54
|
+
- Open reference is required by Schema contains; Python models allow missing reference. Ruby rejects it.
|
|
55
|
+
- Python preset payee matching prioritizes id and can ignore changed name/website; Ruby requires exact object. Unsupported preset PISP/risk_data reject instead of being ignored.
|
|
56
|
+
- Python admits broader timestamp numeric types/skew, other hashes, disclosure shapes and optional time. This profile intentionally does not.
|
|
57
|
+
- Python MandateClient.create always makes the content a disclosure even with empty metadata. Both complete content-disclosure and inline forms are accepted here. Its high-level chain parser fails to restore `~` for a disclosure-free root; when handling an external inline root use official verify_chain with separately parsed original segments. Ruby's issued root has a content disclosure. Interop tests use the official chain verifier, high-level MandateClient.verify for the issued disclosure-bearing root, and typed PaymentMandateChain.verify, not signature checks alone.
|
|
58
|
+
- Payment-specific status=Success/Error Schema wins over generic Receipt prose result naming. Ruby enforces mutually exclusive outcome fields. Python Receipt verification only checks reference-store membership; Ruby also requires independent issuer, payment ID and clock window.
|
|
59
|
+
|
|
60
|
+
## Application responsibilities and persistence
|
|
61
|
+
|
|
62
|
+
SDK verification is not final execution approval or payment success. User authentication/consent, key storage/enrollment/revocation, current order/trust policy, actual payment, durable one-use identity and atomic reservation/consumption belong to the app. Recheck them immediately before execution. No SDK object prevents replay across calls/processes. Persist original Open/final strings and exact Checkout inputs in protected storage; use present, then reverify with current external inputs. Never deserialize a successful Verification as proof. An authentic Error is not automatic retry permission. Missing/unverifiable Receipt or uncertain processing stays pending and requires reconciliation.
|
|
63
|
+
|
|
64
|
+
After installing the candidate Gem offline, run:
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
ruby -e 's=Gem::Specification.find_by_name("ap2_mandate_verifier", "1.1.0"); require File.join(s.full_gem_path, "examples/payment.rb"); PaymentExample.run'
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
All example keys/data/outcomes are synthetic. No live processor, Rails, database or network is needed.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# 公開後の整備 / Post-release maintenance
|
|
2
2
|
|
|
3
|
-
現在の配布版は[0.
|
|
3
|
+
現在の配布版は[1.0.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/1.0.0)です。フレームワーク非依存のAP2 Ruby SDKとして、対応profileにおけるDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を提供します。現行API・対応範囲は[PUBLIC_API](PUBLIC_API.md)・[SUPPORT_CONTRACT](SUPPORT_CONTRACT.md)、公開物と検証記録は[1.0.0公開記録](POST_RELEASE_100.md)を参照してください。[1.0.0準備記録](RELEASE_100_CANDIDATE.md)は当時の状態を残す履歴です。
|
|
4
4
|
|
|
5
|
-
The current distribution is 0.
|
|
5
|
+
The current distribution is 1.0.0, a framework-independent Ruby SDK with a stable public contract for the documented AP2 Checkout profiles. It includes Direct and conditional issuance, presentation, verification and Receipt confirmation. Historical prerelease/candidate/prepublication statements below describe their original stages, not current availability.
|
|
6
6
|
|
|
7
7
|
実Issuer信頼・特定Host本番GO・Phase 2-BはHOLDを維持します。一般AP2互換性・Phase2-A全面PASS・E10全面GOは未成立です。EvidenceはHost ALLOW・nonce消費・決済許可ではありません。
|
|
8
8
|
Real Issuer trust, specific Host production GO and Phase 2-B remain HOLD. General AP2 compatibility, full Phase2-A PASS and full E10 GO are not established. Evidence is not Host ALLOW, nonce consumption or payment permission.
|
|
@@ -11,13 +11,17 @@ Real Issuer trust, specific Host production GO and Phase 2-B remain HOLD. Genera
|
|
|
11
11
|
|
|
12
12
|
| 配布先 / Distribution | 版 / Version | bytes | SHA256 |
|
|
13
13
|
| --- | --- | ---: | --- |
|
|
14
|
-
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.
|
|
14
|
+
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/1.0.0) | 1.0.0(現行配布版 / current release) | 102,912 | `a107101b0178c54ba417be7a2bd7e22feb2fd9a07bda089043e8c5ea8e65e12b` |
|
|
15
|
+
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.8.0) | 0.8.0(歴史記録 / historical) | 79,872 | `6c07664e4291aa8bc025b152075869322411a0d99861e1267959f1794e99acec` |
|
|
15
16
|
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0) | 0.1.0(歴史記録 / historical) | 34,304 | `37b2a235b6fab2d9d9765ae985dd9db27afd3b2c5407fe263a6b65314550db32` |
|
|
16
17
|
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0.pre.3) | 0.1.0.pre.3 | 37,888 | `8ad627818dc69b450d0fba970dafaf368ec42dd64fb51eec631731027de3882c` |
|
|
17
18
|
| [GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.1.0.pre.2) | 0.1.0.pre.2 | 33,280 | `e910659bbebda7aa5f00d63fb579f3b56819d59b5ee7d8b1734a6331f01d8de4` |
|
|
18
19
|
|
|
19
|
-
0.
|
|
20
|
-
The 0.
|
|
20
|
+
1.0.0は2026-11-01 08:13:29.733 UTCに登録され、08:16:01 UTCに公式配布物と保持候補の完全一致、全33 payloadとsource `59e344ad865ed867d0993120456f9411d82bcdec` のtreeとの一致を確認しました。[公開receipt](evidence/1.0.0_publication.json)と[公開記録](POST_RELEASE_100.md)が根拠です。
|
|
21
|
+
The official 1.0.0 distribution matches the exact retained candidate and all 33 payloads of the release source. Source association comes from that byte/payload comparison, not RubyGems source attestation.
|
|
22
|
+
|
|
23
|
+
過去の0.8.0の公式配布物は保持候補およびsource `5a7394c1b98f000b321423e2c2f80d50b5157808` の全29 payloadと照合済みです。公開日時・照合・対応MRIでの公式Gem導入確認は[0.8.0公開記録](POST_RELEASE_080.md)に保持します。この表は現行版と以下の歴史記録の対象を示し、全リリース一覧ではありません。
|
|
24
|
+
The 0.8.0 observations remain evidence for that release. The table preserves the historical artifacts discussed below; it is not a complete version inventory.
|
|
21
25
|
|
|
22
26
|
### 歴史記録:0.1.0公開 / Historical 0.1.0 publication
|
|
23
27
|
|
|
@@ -74,36 +78,36 @@ when a separately approved next version is needed.
|
|
|
74
78
|
environment failures and security concerns. No response/fix deadline or
|
|
75
79
|
production support commitment is promised.
|
|
76
80
|
|
|
77
|
-
## 1.x
|
|
81
|
+
## 1.xの保守・互換性方針 / 1.x maintenance and compatibility
|
|
78
82
|
|
|
79
|
-
以下は1.0.0
|
|
83
|
+
以下は1.0.0の公開から適用する保守方針です。公開面の対象は[PUBLIC_API](PUBLIC_API.md)、対応profile・信頼前提・環境は[SUPPORT_CONTRACT](SUPPORT_CONTRACT.md)に定義します。0.x等の旧版へ新しい保守保証を与えるものではありません。
|
|
80
84
|
|
|
81
|
-
- **保守対象:** 1.x
|
|
85
|
+
- **保守対象:** 1.xでは、最新の1.xマイナー系列の最新patchを対象とします。新しい1.xマイナーが公開された後、以前のマイナー系列・0.x・preへのbackportは約束しません。固定保守年数、受付・修正・開示期限、SLA、24時間対応も約束しません。重大未対処問題や保守不能が判明した場合はHOLDとし、対象版・理由・利用者が取れる対応を明記します。
|
|
82
86
|
- **patch:** 文書化された公開契約を保つ不具合修正です。以前誤って受理した不正・未対応入力を拒否して既存契約を回復するセキュリティ修正は含み得ます。その場合も影響版・受理範囲の変化・理由・必要な移行を開示します。
|
|
83
87
|
- **minor:** 既存の公開契約を保つAPI追加、明示選択するprofileの追加、非推奨化の告知です。既定profileや保存済み原文の扱いを黙って変更しません。非推奨化するAPIは移行先を示してminorで告知し、削除は次のmajor以降とします。固定の暦日猶予は設けません。
|
|
84
88
|
- **major:** 公開API、結果・エラーの契約、既定動作、既存profileの受理条件、保存形式、対応環境に対する非互換変更です。セキュリティ対策という理由だけで、文書化された契約変更を互換patchとして扱いません。必要な修正を互換性のために放置せず、影響と移行を明示して適切な版で対応します。
|
|
85
89
|
|
|
86
|
-
|
|
90
|
+
The 1.x policy maintains only the latest patch of its latest minor series. No backports to older minors, 0.x or prereleases, fixed support term, response/fix/disclosure deadlines or SLA are promised. Patch releases preserve the documented public contract; minor releases add compatible capabilities or announce deprecations with migration guidance; incompatible public-contract changes require a major release. Deprecations are announced in a minor release, with removal no earlier than the next major and no fixed calendar notice period.
|
|
87
91
|
|
|
88
92
|
Security fixes may reject inputs previously accepted in violation of the documented contract, including in a patch release, with affected versions, reasons and migration disclosed. An actual documented-contract change is not automatically patch-compatible because it is security-related. Unsupported profiles, real Issuer trust and Host/payment duties are not brought into scope by the 1.0.0 version number. Dependency updates require an explicit compatibility assessment; they are not automatically compatible.
|
|
89
93
|
|
|
90
94
|
## 依存と回帰 / Dependencies and regression
|
|
91
95
|
|
|
92
96
|
担当はOwner/保守者です。Owner採用済みの手動見直し頻度は月1回、および関連advisory判明時・次版判断前です。
|
|
93
|
-
1.x
|
|
97
|
+
1.xの保守対象は前節のとおりです。現行1.0.0の報告窓口は維持しますが、旧版backport・固定保守年数・SLAは約束しません。
|
|
94
98
|
これは定期監視・自動実行・対応期限が稼働中だという宣言でも、実行の包括承認でもありません。
|
|
95
99
|
2026-10-24 JSTの設定確認ではPrivate vulnerability reportingを有効化し、Dependabot alerts/security updatesは無効、version更新用設定ファイルはなしと記録しました。
|
|
96
100
|
これは当時の設定記録であり、今回の文書整備では現在の設定の再確認やDependabot・CI・認証設定の変更はしていません。
|
|
97
101
|
The Owner-adopted manual cadence is monthly, on relevant advisory discovery
|
|
98
|
-
and before a next release. The
|
|
99
|
-
0.
|
|
102
|
+
and before a next release. The 1.x maintenance scope is above; the current
|
|
103
|
+
1.0.0 reporting routes remain available without a backport or SLA promise. This is
|
|
100
104
|
not an active scheduled monitor, automatic execution authority or response/fix
|
|
101
105
|
deadline. The 2026-10-24 JST setting record is historical: private reporting was
|
|
102
106
|
enabled, Dependabot alerts/security updates were disabled and no version-update
|
|
103
107
|
configuration was present. This documentation update neither rechecks nor changes
|
|
104
108
|
those settings.
|
|
105
109
|
|
|
106
|
-
1.0.0
|
|
110
|
+
1.0.0でも正式対応環境は広げません。MRI **3.4.12 / 4.0.9**、JSON **2.19.9**、JWT **3.3.0**、base64 **0.3.0**、OpenSSL gem **4.0.2**、Digest **3.2.1**の固定を維持します。RubyGemsの`>= 3.4.12, < 4.1`は依存解決範囲であり、その範囲の全Ruby版・他engine・OS/providerを検証済みとするものではありません。実測環境は各版の検証記録で区別します。
|
|
107
111
|
Formal runtime support remains exactly MRI 3.4.12 and 4.0.9 with the five dependency pins above. The Gem's Ruby resolution interval does not certify all versions or engines within it, or unmeasured OS/native-provider configurations.
|
|
108
112
|
|
|
109
113
|
Before proposing an update, assess official Ruby/JSON/JWT/base64/OpenSSL/Digest
|
|
@@ -129,7 +133,7 @@ replays are not independent Oracle reruns. Failure, uncertainty or mismatch mean
|
|
|
129
133
|
STOP/HOLD. Builds, installs, dynamic tests, Actions, dependency changes and releases
|
|
130
134
|
need their own explicit scope/approval; this document grants none.
|
|
131
135
|
|
|
132
|
-
The [0.
|
|
136
|
+
The [1.0.0 publication record](POST_RELEASE_100.md) identifies the current distribution and its evidence. The [1.0.0 preparation record](RELEASE_100_CANDIDATE.md) and [0.8.0 publication record](POST_RELEASE_080.md) retain their historical identities; old pending states and results are not relabelled as fresh checks.
|
|
133
137
|
|
|
134
138
|
|
|
135
139
|
## 歴史記録:未公開0.1.0候補と採用済み保守条件(2026-10-26 UTC)
|
data/docs/PUBLIC_API.md
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
# Ruby SDK public API — 1.0.0
|
|
1
|
+
# Ruby SDK public API — 1.0.0
|
|
2
2
|
|
|
3
|
-
**Status:
|
|
4
|
-
This document defines the
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
[the
|
|
3
|
+
**Status: published 1.0.0.**
|
|
4
|
+
This document defines the 1.x contract for the existing Checkout APIs.
|
|
5
|
+
The 1.0.0 release preserves the 0.8.0 runtime behavior, API names and accepted
|
|
6
|
+
formats. Exact distribution identity and validation are in
|
|
7
|
+
[the publication record](POST_RELEASE_100.md); the earlier
|
|
8
|
+
[preparation record](RELEASE_100_CANDIDATE.md) retains its historical status.
|
|
8
9
|
|
|
9
10
|
The SDK supports human-approved Direct orders and conditional Open → Agent Closed
|
|
10
11
|
delegation for the documented profiles. It runs in plain Ruby. Payment Mandates,
|
|
@@ -183,11 +184,11 @@ No received claim selects trusted policy; unknown profiles and constraints fail
|
|
|
183
184
|
|
|
184
185
|
## Compatibility and internal boundary
|
|
185
186
|
|
|
186
|
-
The
|
|
187
|
+
The 1.x [versioning, maintenance and deprecation policy](POST_RELEASE_MAINTENANCE.md)
|
|
187
188
|
applies to these calls, types, machine meanings, profiles and persistence contracts.
|
|
188
|
-
The `research` names and syntax-only `verify` keep their current meanings.
|
|
189
|
-
|
|
190
|
-
|
|
189
|
+
The `research` names and syntax-only `verify` keep their current meanings.
|
|
190
|
+
Documented 0.8.0 API use needs no source migration. Dependency constraints must
|
|
191
|
+
allow 1.0.0; see [upgrading from 0.8.0](../README.md#upgrading-from-080).
|
|
191
192
|
|
|
192
193
|
Internal `verified_*!` handoffs are not supported ways to inject checked facts;
|
|
193
194
|
[the existing support contract](SUPPORT_CONTRACT.md#result-and-evidence) already
|
|
@@ -196,3 +197,7 @@ catalogs, internal constant layouts and research/test scripts are implementation
|
|
|
196
197
|
details, not extension hooks. Ruby visibility alone does not make them an SDK API.
|
|
197
198
|
This does not remove the published partial-verification entries above, their
|
|
198
199
|
observable error behavior, or the documented profile identities and bounds.
|
|
200
|
+
|
|
201
|
+
## Additive unpublished 1.1.0 candidate
|
|
202
|
+
|
|
203
|
+
The preceding 1.0.0 Checkout contract remains unchanged. New `Payment` and `PaymentReceipt` APIs have a separate [candidate contract](PAYMENT.md); they are not available in published 1.0.0.
|
|
@@ -1,4 +1,10 @@
|
|
|
1
|
-
|
|
1
|
+
> Historical preparation snapshot. 1.0.0 was subsequently published on
|
|
2
|
+
> 2026-11-01 08:13:29.733 UTC; the 102,912-byte official distribution matches
|
|
3
|
+
> the retained candidate and all 33 payloads match the release source.
|
|
4
|
+
> See [publication](POST_RELEASE_100.md) and [current release/upgrade](RELEASE_100.md).
|
|
5
|
+
> Unpublished and pending statements below describe the preparation checkpoint.
|
|
6
|
+
|
|
7
|
+
# 1.0.0 candidate — historical preparation
|
|
2
8
|
|
|
3
9
|
**Unpublished candidate. The currently published release is 0.8.0.**
|
|
4
10
|
The candidate Gem has version `1.0.0`; that metadata is not a publication record.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 1.1.0 candidate — publication requires Owner approval
|
|
2
|
+
|
|
3
|
+
Status: unpublished candidate. Published 1.0.0 remains available and unchanged. The source version 1.1.0 is a proposal for additive Payment APIs under the existing 1.x Checkout contract. Do not tag, publish GitHub Release, push/yank RubyGems, announce or deploy on the basis of this document.
|
|
4
|
+
|
|
5
|
+
## Proposed GitHub Release body
|
|
6
|
+
|
|
7
|
+
Adds framework-independent Direct and conditional Payment Mandates, strict payment conditions/Checkout binding, original-wire persistence/reference helpers, and signed Success/Error Payment Receipts. Existing Checkout API defaults/profiles/results remain unchanged. Payment verification authenticates supported facts; applications still own consent/trust, durable atomic one-use state and payment execution.
|
|
8
|
+
|
|
9
|
+
```ruby
|
|
10
|
+
payment = AP2MandateVerifier::Payment.details(
|
|
11
|
+
checkout_jwt: original_checkout_from_trusted_order,
|
|
12
|
+
trusted_merchant_public_key_pem: registered_merchant_key,
|
|
13
|
+
expected_merchant_id: current_merchant_id,
|
|
14
|
+
payment_instrument: selected_instrument_from_application)
|
|
15
|
+
# After app authentication and consent: issue_direct(payment: payment,
|
|
16
|
+
# approved_payment: protected_consent_record, ...). See examples/payment.rb.
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Supported: one immediate payment, integer minor units, exact payee/instrument and amount range, optional fixed values, one Agent hop. General selective disclosure, recurrence/budgets, PISP/execution_date/risk_data, live processors and A2A/MCP are outside this profile and reject. See [Payment API and specification decisions](PAYMENT.md).
|
|
20
|
+
|
|
21
|
+
## Approval checklist and publication procedure
|
|
22
|
+
|
|
23
|
+
1. Confirm latest reviewed/merged source SHA, package contents/source equality, Gem filename/bytes/SHA256 and immutable evidence record in Issue #235. Verify both supported MRI endpoint tests, installed examples, existing Checkout regression, official pinned SDK/Schema bidirectional interoperability and latest-HEAD independent review. Any unresolved substantive finding or missing required test means HOLD.
|
|
24
|
+
2. Owner explicitly chooses version and approves the exact artifact SHA256, tag/Release and publication/announcement separately. Until then stop. If version/source/artifact changes, rebuild once and repeat affected validation/review; do not reuse approval for a different artifact.
|
|
25
|
+
3. With separate approval, verify `sha256sum` of the approved Gem and `gem specification ... --local`; push that exact file using Owner-controlled RubyGems credentials. Do not rebuild during publication. Create/push the approved tag on the recorded source SHA and publish the approved Release body only when separately authorized.
|
|
26
|
+
4. After approved publication, fetch public RubyGems version metadata and distribution, compare SHA256 and dependency/file metadata, install it into a new isolated environment, run packaged Direct/conditional examples and both Receipt outcomes, check README links/version claims. Record evidence before calling publication verified. Unknown outcomes require reconciliation, never blind retry/yank.
|
|
27
|
+
|
|
28
|
+
No publication/deployment workflow is added. Existing product CI is a read-only source/package validation workflow. Existing research HOLDs remain independent.
|
|
29
|
+
|
|
30
|
+
Runtime dependencies remain pinned: json=2.19.9, jwt=3.3.0, base64=0.3.0, openssl=4.0.2, digest=3.2.1. MRI test endpoints remain 3.4.12 and 4.0.9; installation range >=3.4.12,<4.1 is not a claim of formal support for every intermediate Ruby.
|