ap2_mandate_verifier 0.8.0 → 1.0.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 +32 -15
- data/README.md +42 -16
- data/SECURITY.md +82 -0
- data/docs/BUYER_DIRECT_CHECKOUT.md +8 -5
- data/docs/CONDITIONAL_CHECKOUT.md +8 -5
- data/docs/INPUT_BUILDER.md +182 -0
- data/docs/POST_RELEASE_MAINTENANCE.md +160 -0
- data/docs/PUBLIC_API.md +198 -0
- data/docs/RELEASE_100_CANDIDATE.md +113 -0
- data/docs/SUPPORT_CONTRACT.md +50 -5
- metadata +13 -8
- data/docs/RELEASE_080_CANDIDATE.md +0 -109
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# 公開後の整備 / Post-release maintenance
|
|
2
|
+
|
|
3
|
+
現在の配布版は[0.8.0](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.8.0)です。フレームワーク非依存のAP2 Ruby SDKとして、対応profileにおけるDirect/条件付き購入委任の発行・提示・検証・Checkout Receipt確認を提供します。現行API・対応範囲は[SUPPORT_CONTRACT](SUPPORT_CONTRACT.md)、公開物と導入確認は[0.8.0公開記録](POST_RELEASE_080.md)を参照してください。**1.0.0は未公開候補**であり、候補の状態と検証は[1.0.0準備記録](RELEASE_100_CANDIDATE.md)に分けて記録します。
|
|
4
|
+
|
|
5
|
+
The current distribution is 0.8.0, a framework-independent Ruby SDK for the documented AP2 Checkout profiles. It includes Direct and conditional issuance, presentation, verification and Receipt confirmation. Version 1.0.0 is an unpublished candidate. Historical prerelease/candidate/prepublication statements below describe their original stages, not current availability.
|
|
6
|
+
|
|
7
|
+
実Issuer信頼・特定Host本番GO・Phase 2-BはHOLDを維持します。一般AP2互換性・Phase2-A全面PASS・E10全面GOは未成立です。EvidenceはHost ALLOW・nonce消費・決済許可ではありません。
|
|
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.
|
|
9
|
+
|
|
10
|
+
## 公開物と証拠 / Artifacts and evidence
|
|
11
|
+
|
|
12
|
+
| 配布先 / Distribution | 版 / Version | bytes | SHA256 |
|
|
13
|
+
| --- | --- | ---: | --- |
|
|
14
|
+
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.8.0) | 0.8.0(現行配布版 / current release) | 79,872 | `6c07664e4291aa8bc025b152075869322411a0d99861e1267959f1794e99acec` |
|
|
15
|
+
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0) | 0.1.0(歴史記録 / historical) | 34,304 | `37b2a235b6fab2d9d9765ae985dd9db27afd3b2c5407fe263a6b65314550db32` |
|
|
16
|
+
| [RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0.pre.3) | 0.1.0.pre.3 | 37,888 | `8ad627818dc69b450d0fba970dafaf368ec42dd64fb51eec631731027de3882c` |
|
|
17
|
+
| [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
|
+
0.8.0の公式配布物は保持候補およびsource `5a7394c1b98f000b321423e2c2f80d50b5157808` の全29 payloadと照合済みです。公開日時・照合・対応MRIでの公式Gem導入確認は[0.8.0公開記録](POST_RELEASE_080.md)が根拠です。この表は現行版と以下の歴史記録の対象を示し、全リリース一覧ではありません。
|
|
20
|
+
The 0.8.0 publication record identifies the exact source, distributed artifact and installed-Gem checks. Its observations do not validate a newly built 1.0.0 artifact. The table preserves the historical artifacts discussed below; it is not a complete version inventory.
|
|
21
|
+
|
|
22
|
+
### 歴史記録:0.1.0公開 / Historical 0.1.0 publication
|
|
23
|
+
|
|
24
|
+
0.1.0はOwnerのexact-artifact S7承認後、2026-10-26 08:35:32 UTCに公開。08:37:27 UTCの照合で公式版一覧・所有者`cuichangquan`・実配布bytes・保持R2のSHA/sizeが一致し、13 payload/18 source manifest項目も照合済みです。[公開receiptと限界](../research/stable010_release_linux_package/README.md#rubygems-publication-verified)が根拠です。版別APIの初回404とMFA停止は当時の記録として保持し、公開後照合で再pushはしていません。GitHubのsource snapshotは配布Gemと同一bytesではありません。
|
|
25
|
+
Stable 0.1.0 publication was verified against official versions/owners metadata and the downloaded distribution. This exact-artifact S7 approval does not grant actual Host production GO or authorize a later release. Published artifacts and original validation evidence remain immutable.
|
|
26
|
+
|
|
27
|
+
### 歴史記録:pre.3/pre.2 / Historical prereleases
|
|
28
|
+
|
|
29
|
+
pre3は2026-10-23に所有者 `cuichangquan` が公開し、Ownerが公式API・実配布物・MBA原本の一致を確認しました。
|
|
30
|
+
今回のMac mini監査ではRubyGems閲覧取得不能/APIへのDNS解決失敗のため独立再確認できていません。
|
|
31
|
+
これは昨日の公開検証記録を否定するものでも、今回の再検証成功を示すものでもありません。
|
|
32
|
+
The Owner's 2026-10-23 publication check matched the official API, distributed
|
|
33
|
+
pre3 archive and MBA original under owner `cuichangquan`. The subsequent Mac mini
|
|
34
|
+
audit could not independently refetch RubyGems (page/API retrieval unavailable,
|
|
35
|
+
local API DNS resolution failed); it does not constitute another successful
|
|
36
|
+
publication validation.
|
|
37
|
+
|
|
38
|
+
[PR177](https://github.com/cuichangquan/ap2-mandate-verifier/pull/177) records
|
|
39
|
+
`MBA409-PRE3PACKAGE02-20261023`: MBA Darwin arm64, MRI4.0.9,13 payload identities,
|
|
40
|
+
10 loaded libraries and52 installed checks (42 saved independent expectations,
|
|
41
|
+
7 legacy APIs,2 input rejections,1 constructor rejection). It did not rerun885
|
|
42
|
+
source regressions. **pre3 Linux subsequently passed [run40038620413 attempt1](https://github.com/cuichangquan/ap2-mandate-verifier/actions/runs/40038620413).** The earlier NOT_RUN status was historical and is superseded by that pre3 observation. The successful pre2 Linux
|
|
43
|
+
[run39939021098 attempt1](https://github.com/cuichangquan/ap2-mandate-verifier/actions/runs/39939021098)
|
|
44
|
+
is historical pre2 evidence, not a pre3 package or independent Linux Oracle run.
|
|
45
|
+
Unknown safety, runtime/native attestation and worst-case CPU/RSS/concurrency
|
|
46
|
+
remain unproved; historical communication-accounting gaps remain unresolved.
|
|
47
|
+
|
|
48
|
+
## 文書と再公開の境界 / Documentation and publication
|
|
49
|
+
|
|
50
|
+
READMEとSUPPORT_CONTRACTはGem同梱対象です。公開Gem内の文書は包装時点のスナップショットとして保持し、
|
|
51
|
+
「RubyGems未公開」等の古い記載はmainの文書で追補します。現在のmainは同梱文書と異なります。
|
|
52
|
+
同じ版を再ビルドしても公開Gemと同一ではなく、公開SHA・包装検証を引き継ぎません。
|
|
53
|
+
公開Gem・タグ・Releaseは上書きせず、文書訂正だけの再リリースは行いません。
|
|
54
|
+
Gemの次版が必要になったときに、同梱文書・候補metadataを別途見直します。
|
|
55
|
+
README and SUPPORT_CONTRACT are packaged files. Published copies remain immutable
|
|
56
|
+
packaging snapshots; main supplements their stale unpublished wording. Current
|
|
57
|
+
main differs from packaged documentation. A same-version rebuild is not the
|
|
58
|
+
published artifact and inherits neither its SHA nor package-validation evidence.
|
|
59
|
+
Do not overwrite published Gems, tags or Releases. Documentation corrections alone
|
|
60
|
+
do not require a new Gem release. Review packaged documents and candidate metadata
|
|
61
|
+
when a separately approved next version is needed.
|
|
62
|
+
|
|
63
|
+
## 受付 / Reporting
|
|
64
|
+
|
|
65
|
+
- 通常の不具合・導入問題 / Ordinary bugs and installation issues:
|
|
66
|
+
[GitHub Issues](https://github.com/cuichangquan/ap2-mandate-verifier/issues).
|
|
67
|
+
Include Gem version, artifact SHA if known, Ruby/OS/dependency versions,
|
|
68
|
+
sanitized minimal synthetic reproduction, expected/actual behavior and scope.
|
|
69
|
+
- 脆弱性 / Suspected vulnerabilities: follow [SECURITY.md](../SECURITY.md).
|
|
70
|
+
Do not publish exploit details in Issues or PRs. Never include credentials,
|
|
71
|
+
private keys, real Mandates/nonces or personal data in either reporting route.
|
|
72
|
+
- Owner `cuichangquan` is the initial maintainer contact through these GitHub
|
|
73
|
+
routes. Triage distinguishes reproducible defects, unsupported profiles,
|
|
74
|
+
environment failures and security concerns. No response/fix deadline or
|
|
75
|
+
production support commitment is promised.
|
|
76
|
+
|
|
77
|
+
## 1.xの保守・互換性方針案 / Proposed 1.x maintenance and compatibility
|
|
78
|
+
|
|
79
|
+
以下は1.0.0公開に向けた保守方針案です。1.0.0の公開済み表示や、旧版への保守保証ではありません。公開面の対象は[PUBLIC_API](PUBLIC_API.md)、対応profile・信頼前提・環境は[SUPPORT_CONTRACT](SUPPORT_CONTRACT.md)に定義します。
|
|
80
|
+
|
|
81
|
+
- **保守対象:** 1.x公開後は、最新の1.xマイナー系列の最新patchを対象とします。新しい1.xマイナーが公開された後、以前のマイナー系列・0.x・preへのbackportは約束しません。固定保守年数、受付・修正・開示期限、SLA、24時間対応も約束しません。重大未対処問題や保守不能が判明した場合はHOLDとし、対象版・理由・利用者が取れる対応を明記します。
|
|
82
|
+
- **patch:** 文書化された公開契約を保つ不具合修正です。以前誤って受理した不正・未対応入力を拒否して既存契約を回復するセキュリティ修正は含み得ます。その場合も影響版・受理範囲の変化・理由・必要な移行を開示します。
|
|
83
|
+
- **minor:** 既存の公開契約を保つAPI追加、明示選択するprofileの追加、非推奨化の告知です。既定profileや保存済み原文の扱いを黙って変更しません。非推奨化するAPIは移行先を示してminorで告知し、削除は次のmajor以降とします。固定の暦日猶予は設けません。
|
|
84
|
+
- **major:** 公開API、結果・エラーの契約、既定動作、既存profileの受理条件、保存形式、対応環境に対する非互換変更です。セキュリティ対策という理由だけで、文書化された契約変更を互換patchとして扱いません。必要な修正を互換性のために放置せず、影響と移行を明示して適切な版で対応します。
|
|
85
|
+
|
|
86
|
+
Once 1.x is released, the proposal 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
|
+
|
|
88
|
+
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
|
+
|
|
90
|
+
## 依存と回帰 / Dependencies and regression
|
|
91
|
+
|
|
92
|
+
担当はOwner/保守者です。Owner採用済みの手動見直し頻度は月1回、および関連advisory判明時・次版判断前です。
|
|
93
|
+
1.xの保守対象案は前節のとおりです。現行0.8.0の報告窓口は維持しますが、旧版backport・固定保守年数・SLAは約束しません。
|
|
94
|
+
これは定期監視・自動実行・対応期限が稼働中だという宣言でも、実行の包括承認でもありません。
|
|
95
|
+
2026-10-24 JSTの設定確認ではPrivate vulnerability reportingを有効化し、Dependabot alerts/security updatesは無効、version更新用設定ファイルはなしと記録しました。
|
|
96
|
+
これは当時の設定記録であり、今回の文書整備では現在の設定の再確認やDependabot・CI・認証設定の変更はしていません。
|
|
97
|
+
The Owner-adopted manual cadence is monthly, on relevant advisory discovery
|
|
98
|
+
and before a next release. The proposed 1.x maintenance scope is above; the current
|
|
99
|
+
0.8.0 reporting routes remain available without a backport or SLA promise. This is
|
|
100
|
+
not an active scheduled monitor, automatic execution authority or response/fix
|
|
101
|
+
deadline. The 2026-10-24 JST setting record is historical: private reporting was
|
|
102
|
+
enabled, Dependabot alerts/security updates were disabled and no version-update
|
|
103
|
+
configuration was present. This documentation update neither rechecks nor changes
|
|
104
|
+
those settings.
|
|
105
|
+
|
|
106
|
+
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
|
+
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
|
+
|
|
109
|
+
Before proposing an update, assess official Ruby/JSON/JWT/base64/OpenSSL/Digest
|
|
110
|
+
advisories and the actual native providers, affected scope and reproducibility.
|
|
111
|
+
Keep exact dependency pins until a scoped change is approved; do not silently
|
|
112
|
+
accept a later provider or relabel historical manifests/results.
|
|
113
|
+
|
|
114
|
+
文書のみの変更はリンク・日英整合・版/SHA・証拠範囲・CI triggerを静的確認します。
|
|
115
|
+
依存/コード/包装を変更する場合は、差分に応じて現行のVerifier・InputBuilder・署名/Receipt・Direct・条件付き委任の回帰と、必要な独立正常・因果負例/Schema比較を計画します。
|
|
116
|
+
新しい配布候補では、対応MRIごとの通常インストール、候補metadata、全payloadのsource/archive/installed一致、公開APIだけを使う例を確認します。実施範囲・件数・未実施はその版の記録に保存し、旧版の固定件数を現在の合格基準や新しいPASSとして流用しません。
|
|
117
|
+
新しい結果は版・source SHA・runtime/provider・入力/期待値・環境・runを区別して保存します。
|
|
118
|
+
Linuxの保存期待値再生を独立Oracle再実行とは呼びません。失敗・未知・不一致はSTOP/HOLDです。
|
|
119
|
+
For documentation-only changes, statically check links, bilingual consistency,
|
|
120
|
+
version/SHA identities, evidence scope and CI triggers. Dependency/code/package
|
|
121
|
+
changes need a diff-based validation plan covering the affected current modules
|
|
122
|
+
and relevant independent positive/causal-negative or Schema comparisons. New
|
|
123
|
+
candidates require ordinary installation on both supported MRI versions, metadata
|
|
124
|
+
and complete source/archive/installed payload comparisons, and public-API examples.
|
|
125
|
+
Record the actual scope, counts and NOT_RUN work per release rather than copying
|
|
126
|
+
old counts or PASS results. Preserve new evidence separately by version, source SHA,
|
|
127
|
+
runtime/provider, inputs/expectations, environment and run. Saved-expectation
|
|
128
|
+
replays are not independent Oracle reruns. Failure, uncertainty or mismatch means
|
|
129
|
+
STOP/HOLD. Builds, installs, dynamic tests, Actions, dependency changes and releases
|
|
130
|
+
need their own explicit scope/approval; this document grants none.
|
|
131
|
+
|
|
132
|
+
The [0.8.0 publication record](POST_RELEASE_080.md) remains evidence for that distribution. The [1.0.0 candidate record](RELEASE_100_CANDIDATE.md) reports its own completed and pending validation; this maintenance plan does not assert that those checks have run.
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
## 歴史記録:未公開0.1.0候補と採用済み保守条件(2026-10-26 UTC)
|
|
136
|
+
|
|
137
|
+
公開物の表はpre3/pre2のままです。**0.1.0は未公開候補**であり、[候補source・Mac/Ubuntu結果](../research/stable010_candidate/README.md)を別記録に保存します。候補43,008B / SHA256 `0553645fa6c067dd8d7a7a1a7cdf13799370393e76dc3bc4ba161ab2ca5981b0`、両環境13 payload/10 loaded/52 installedが確認済み。候補内の未実施記述は包装時点snapshotで、後続Ubuntu成功は外部追補を参照してください。再包装や公開済みGem/tag/Releaseの上書きはしません。
|
|
138
|
+
|
|
139
|
+
前節の月次/勧告時/次版前の手動見直しをOwnerが具体条件として採用しました。担当はOwner/保守者、通常不具合はIssues、脆弱性はSECURITYの非公開窓口です。初回安定系列の最新修正版のみを対象とし、pre/旧系列backport・一定年数・受付/修正期限・24時間対応は約束しません。更新/廃止/保守終了は対象版・理由・移行先と状態を告知し、固定猶予期間は設けません。自動監視は稼働中と扱わず、担当不在/保守不能/重大未対処問題はHOLDです。
|
|
140
|
+
|
|
141
|
+
上記の一般的な回帰計画は全件再実行の義務ではありません。今回の版/文書/包装期待値の差分では、製品10件・固定依存と既存証拠を照合して885を再利用し、新候補の包装/導入を両環境各1回確認しました。147は885の内数、旧runtime独立比較や保存期待値再生は新独立Oracleではありません。追加検証は具体的不足に応じ別承認とし、今回追加試験/取得/build/Actions/公開はなしです。
|
|
142
|
+
|
|
143
|
+
Provider/component確認と全面安全性は別です。D1/D2停止とD3限定成功、JSON公式修正ソース根拠とGHSA metadata不整合、OS dyld/全binding・通信全量・物理容量peak等の未証明を保持します。最後にexact archive・配布先・保証範囲・残余を示すS7公開GOが必要で、特定Host本番GOは別/HOLDです。
|
|
144
|
+
|
|
145
|
+
The public-artifact table still lists pre3/pre2 only. Candidate0.1.0 has separate Mac/Ubuntu evidence; its packaging snapshots are supplemented externally without rebuilding. Adopted maintenance covers the latest patch in the initial stable series, with manual monthly/advisory/pre-release review, existing reporting routes and explicit update/deprecation notices; no backport/fixed-term/SLA/24-hour promises or automatic monitoring. Diff-based historical evidence reuse is not a fresh885 run. Publication and specific Host production GO remain separate and unapproved.
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
## Historical R2 preparation / 歴史記録:公開向け文書のR2
|
|
150
|
+
|
|
151
|
+
The0.1.0 consumer documentation now describes the fixed verification contract and installation only after official listing, without declaring publication. Earlier candidate/R1/pre3 descriptions above are historical. A newly built R2 archive has separate [source and validation evidence](../research/stable010_release_linux_package/README.md); R1's43,008B archive and observations are not reused as new-byte validation. Existing maintenance scope/reporting routes/exclusions remain unchanged. RubyGems publication and specific Host production GO still require separate authorization.
|
|
152
|
+
|
|
153
|
+
0.1.0の公開向け文書を整理しましたが、公開済みとは表示しません。旧candidate/R1/pre3は履歴として保持し、新R2は別archive・別証拠です。採用済み保守条件・窓口・保証除外は不変で、Gem公開GO・特定Host本番GOは別途必要です。
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
## Historical prepublication supplement / 歴史記録:公開前R2検証追補
|
|
157
|
+
|
|
158
|
+
The new34,304B R2 archive (SHA256 `37b2a235b6fab2d9d9765ae985dd9db27afd3b2c5407fe263a6b65314550db32`) passed Mac and [Ubuntu run40288305150 attempt1](https://github.com/cuichangquan/ap2-mandate-verifier/actions/runs/40288305150) payload13/loaded10/installed52 checks with matching payload/dependency identities. See [exact results and limitations](../research/stable010_release_linux_package/README.md). This is distinct from R1/pre3, not a new885 or independent Oracle run. Source/packaged bytes remain frozen. No Gem, tag or Release publication occurred; S7 and specific Host production GO remain HOLD. Existing maintenance policy and reporting routes are unchanged.
|
|
159
|
+
|
|
160
|
+
新R2はMac/Ubuntuで限定包装検証済みですが未公開です。provider確認を全面安全性へ昇格せず、JSON勧告metadata不整合、OS dyld/全binding、総通信/physical peak等の未証明を保持します。原結果のhash/読戻し後に今回分だけを清掃し、旧停止履歴・証拠・archiveは保持。追加build/試験/Actions/取得はこの追補作業では行いません。
|
data/docs/PUBLIC_API.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Ruby SDK public API — 1.0.0 candidate
|
|
2
|
+
|
|
3
|
+
**Status: unpublished 1.0.0 preparation. Published stable remains 0.8.0.**
|
|
4
|
+
This document defines the proposed 1.x contract for the existing Checkout APIs;
|
|
5
|
+
it adds no runtime behavior, renames or broader accepted formats. Candidate
|
|
6
|
+
validation and remaining release decisions belong to
|
|
7
|
+
[the preparation record](RELEASE_100_CANDIDATE.md).
|
|
8
|
+
|
|
9
|
+
The SDK supports human-approved Direct orders and conditional Open → Agent Closed
|
|
10
|
+
delegation for the documented profiles. It runs in plain Ruby. Payment Mandates,
|
|
11
|
+
general AP2/Schema compatibility, real Issuer enrollment and application payment
|
|
12
|
+
execution are outside this contract. The adopted AP2 source remains
|
|
13
|
+
`b4587ac1d055888a73b4b21750973cffba961793`.
|
|
14
|
+
|
|
15
|
+
## Supported entry points
|
|
16
|
+
|
|
17
|
+
All names below are under `AP2MandateVerifier`. Require the Gem with
|
|
18
|
+
`require "ap2_mandate_verifier"`. Arguments are keywords unless shown otherwise;
|
|
19
|
+
the linked contracts specify their complete fields, exact Ruby types and limits.
|
|
20
|
+
No implicit coercion, trust discovery or default current clock is provided.
|
|
21
|
+
|
|
22
|
+
| Entry | Role and returned value | Detailed contract |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| `ConditionalCheckout.issue_open` | Sign approved merchant/product/quantity conditions for one registered Agent; return `ConditionalCheckout::Open`. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
|
|
25
|
+
| `ConditionalCheckout.issue_closed` | Check Open, Agent binding, Merchant Checkout and conditions; sign and return `ConditionalCheckout::Closed`. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
|
|
26
|
+
| `ConditionalCheckout.present` | Restore original Open, terminal and Checkout strings with structural/binding checks; return `ConditionalCheckout::Closed`. This is not signature authentication. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
|
|
27
|
+
| `Buyer.issue_closed` | Sign a Direct order whose original Checkout equals the app's approved original; return `Buyer::Issued`. | [Direct API](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
28
|
+
| `Buyer.present_closed` | Preserve the Direct wire after structural checks; return a frozen String. This is not signature authentication. | [Direct API](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
29
|
+
| `Buyer.verify` | Verify the supported Direct presentation against independently supplied keys, expected Checkout and time; return `Buyer::Verification`. | [Direct API](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
30
|
+
| `CheckoutJWT.sign` / `.verify` | Sign a supported merchant-authored Checkout / authenticate it against an independent merchant key and identity; return `CheckoutJWT::Signed` / `CheckoutJWT::Verification`. | [Signing](MERCHANT_SIGNING.md#minimal-executable-example), [verification](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
31
|
+
| `CheckoutJWT.es256_signer(private_key:)` | Return a signing callable over an application-owned OpenSSL P-256 private key. | [Signer contract](MERCHANT_SIGNING.md#minimal-executable-example) |
|
|
32
|
+
| `CheckoutReceipt.reference` / `.sign` / `.verify` | Calculate the exact final-Mandate reference / sign an explicit app outcome / authenticate a Receipt; return a frozen String / `CheckoutReceipt::Signed` / `CheckoutReceipt::Verification`. | [Receipt contract](MERCHANT_SIGNING.md#checkout-receipt-contract-and-specification-discrepancy) |
|
|
33
|
+
|
|
34
|
+
### Full Open → Agent Closed verification and input preparation
|
|
35
|
+
|
|
36
|
+
| Entry | Role and returned value |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `InputBuilder.trust` / `.restore_trust` | Assemble a selected trust snapshot / restore original trust and selection strings; return `InputBuilder::Trust`. The app authenticates provenance and currentness. |
|
|
39
|
+
| `InputBuilder.prepare` / `.restore` | Prepare a versioned challenge record / validate and preserve its original bytes; return a frozen String. Neither operation issues or consumes a nonce. |
|
|
40
|
+
| `InputBuilder.inputs` | Assemble the seven complete-verification keyword inputs as a frozen Hash. It does not produce Evidence. |
|
|
41
|
+
| `InputBuilder.verify` | Assemble business inputs and run complete Open → Agent Closed verification; return `ResearchResult` or non-success `Result`. |
|
|
42
|
+
| `verify_checkout` / `verify_research` | Run the same complete Open → Agent Closed pipeline with the seven raw inputs below. `verify_research` remains supported without a deprecation warning. |
|
|
43
|
+
| `ResearchResult.verify` | Retained factory for that same pipeline and input contract. Prefer the module-level or InputBuilder entry for new integrations. |
|
|
44
|
+
|
|
45
|
+
The seven raw keywords are `trust_json:`, `selection_json:`, `host_json:`,
|
|
46
|
+
`root_presentation:`, `terminal_jws:`, `host_checkout_jws:` and `verified_at:`.
|
|
47
|
+
The first six are original Strings; `verified_at` is an independently supplied
|
|
48
|
+
integer Unix timestamp. These entries do not accept the separate Direct format.
|
|
49
|
+
See [business inputs and restoration](INPUT_BUILDER.md) and
|
|
50
|
+
[raw input fields](SUPPORT_CONTRACT.md#full-entry-and-required-inputs).
|
|
51
|
+
|
|
52
|
+
### Preserved partial-verification APIs
|
|
53
|
+
|
|
54
|
+
These published entries remain supported; they are not reclassified as private.
|
|
55
|
+
All return non-success `Result` values with `success? == false` and `evidence == nil`,
|
|
56
|
+
including when their limited check passes. They do not replace either complete
|
|
57
|
+
verification entry.
|
|
58
|
+
|
|
59
|
+
| Entry | Maximum meaning of a passing check |
|
|
60
|
+
| --- | --- |
|
|
61
|
+
| `verify(presentation_json:)` | JSON syntax only: `:unverified / :verification_not_implemented`. |
|
|
62
|
+
| `verify_root_signature(root_jws:, trusted_issuer_public_key_pem:)` | One Root signature, not disclosure closure or authority. |
|
|
63
|
+
| `verify_root_disclosures(presentation:, trusted_issuer_public_key_pem:)` | The existing single-product Root disclosure profile and signature. |
|
|
64
|
+
| `verify_purchase_binding(**inputs)` | The documented Root/Agent/Merchant purchase binding checks. |
|
|
65
|
+
| `verify_scoped_constraints(**inputs)` | The selected supported purchase constraints. |
|
|
66
|
+
| `verify_trusted_scoped_constraints(trust_json:, selection_json:, **inputs)` | Supplied trust selection plus scoped constraints; not the full Host challenge/order contract. |
|
|
67
|
+
| `verify_host_binding(**inputs)` | The supported Host binding checks, without minting successful Evidence through this legacy wrapper. |
|
|
68
|
+
|
|
69
|
+
Existing keyword sets, defaults and partial-pass codes are preserved. See the
|
|
70
|
+
[module entry definitions](../lib/ap2_mandate_verifier.rb) and the
|
|
71
|
+
[Result/Evidence contract](SUPPORT_CONTRACT.md#result-and-evidence).
|
|
72
|
+
|
|
73
|
+
## Result, object and failure contracts
|
|
74
|
+
|
|
75
|
+
Each API keeps its existing result convention. Do not call `success?` on every
|
|
76
|
+
returned object or infer authorization from an object merely being present.
|
|
77
|
+
|
|
78
|
+
| API family | Success | Non-success |
|
|
79
|
+
| --- | --- | --- |
|
|
80
|
+
| Complete Open → Closed verification | `ResearchResult`: `status == :verified_research`, `code == :scoped_research_verified`, `success? == true`, immutable Evidence. | `Result`: rejected or unavailable, `success? == false`, no Evidence. |
|
|
81
|
+
| `InputBuilder.verify` assembly | Enters the complete verifier. | Malformed assembly, including missing/unknown keywords: `:rejected / :invalid_host_context`. Dependency/unexpected assembly failure: `:unavailable / :research_verification_unavailable`. Core results keep their codes. |
|
|
82
|
+
| Other InputBuilder calls | Trust, String or input Hash as listed above. | Checked malformed business input raises `InputBuilder::Invalid`; argument-binding, dependency and unexpected exceptions can propagate. These methods do not promise a Result wrapper. |
|
|
83
|
+
| `Buyer.verify` | `verified? == true`, `code == :direct_checkout_verified`, checked claims. | `verified? == false`, `code == :direct_checkout_verification_failed`, no claims. Dependency/internal failures use this same code. |
|
|
84
|
+
| `CheckoutJWT.sign` / `.verify` / `.es256_signer` | The listed object or callable. | Redacted `CheckoutJWT::Invalid`. Verification does not return a false Verification object. |
|
|
85
|
+
| Buyer issuance/presentation; Conditional issuance/presentation | The listed object or original wire. | Redacted `Buyer::Invalid` or `ConditionalCheckout::Invalid`. |
|
|
86
|
+
| Receipt reference/signing | The listed String or Signed object. | Redacted `CheckoutReceipt::Invalid`. |
|
|
87
|
+
| Receipt verification | `verified? == true`; separately inspect `outcome`, `purchase_succeeded?` or `purchase_rejected?`. | `verified? == false` and both purchase predicates false; no claims. Codes: `:receipt_verification_failed`, `:receipt_issuer_mismatch`, `:receipt_reference_mismatch`, `:receipt_time_mismatch`. |
|
|
88
|
+
|
|
89
|
+
The four signing/presentation `Invalid` classes above inherit `ArgumentError` and
|
|
90
|
+
use fixed redacted messages without the original cause. A generic `Invalid` or
|
|
91
|
+
verification-failed code does **not** distinguish invalid data from unavailable
|
|
92
|
+
signing/dependency processing. Hold the operation; diagnose through protected app
|
|
93
|
+
observability. A remote signer may have completed signing before a transport
|
|
94
|
+
failure: reconcile the app's issuance record before issuing again.
|
|
95
|
+
|
|
96
|
+
Missing/unknown keywords to `verify_checkout`, `verify_research` and
|
|
97
|
+
`ResearchResult.verify` return `:unavailable / :research_verification_unavailable`.
|
|
98
|
+
Ruby positional-argument errors or invalid keyword expansion can raise before an
|
|
99
|
+
entry executes. Exceptions, process failure and missing results never authorize
|
|
100
|
+
an operation. Existing status/code meanings are preserved; human-readable error
|
|
101
|
+
or diagnostic wording is not a machine interface.
|
|
102
|
+
|
|
103
|
+
### Supported returned objects and constructors
|
|
104
|
+
|
|
105
|
+
| Type | Supported reads |
|
|
106
|
+
| --- | --- |
|
|
107
|
+
| `Result`, `ResearchResult` | `status`, `code`, `success?`, `rejected?`, `unverified?`, `unavailable?`, `evidence`, `diagnostic`. |
|
|
108
|
+
| `ResearchEvidence` | `[](field)` and `to_h`: the existing immutable Evidence v2 facts, including contract/profile identities and checked bindings. |
|
|
109
|
+
| `InputBuilder::Trust` | `trust_json`, `selection_json`. |
|
|
110
|
+
| `CheckoutJWT::Signed` | `jwt`, `checkout_hash`. |
|
|
111
|
+
| `CheckoutJWT::Verification` | `verified?`, `jwt`, `checkout_hash`, `checkout`, `profile_ref`. |
|
|
112
|
+
| `Buyer::Issued` | `closed_sd_jwt`. |
|
|
113
|
+
| `Buyer::Verification` | `verified?`, `code`, `checkout`, `checkout_hash`, `reference`, `expires_at`. |
|
|
114
|
+
| `ConditionalCheckout::Open` | `root_presentation`. |
|
|
115
|
+
| `ConditionalCheckout::Closed` | `root_presentation`, `terminal_jws`, `checkout_jwt`, `closed_sd_jwt`. |
|
|
116
|
+
| `CheckoutReceipt::Signed` | `jwt`, `reference`. |
|
|
117
|
+
| `CheckoutReceipt::Verification` | `verified?`, `code`, `outcome`, `purchase_succeeded?`, `purchase_rejected?`, `order_id`, `error`, `error_description`. |
|
|
118
|
+
| `Diagnostic` | `stage`, `field`, `reason`, `hint(locale: :en)`, `to_h(locale: :en)`, `[](key)`; `:ja` provides Japanese hints. |
|
|
119
|
+
| `InputBuilder::Invalid` | `diagnostic`, which may be nil if diagnostic construction fails. |
|
|
120
|
+
|
|
121
|
+
`Result.new(status:, code:, diagnostic: nil)` is retained. It accepts only
|
|
122
|
+
registered non-success status/code pairs and raises `ArgumentError` for unsupported
|
|
123
|
+
pairs. It cannot construct successful Evidence. Result/Evidence-producing object
|
|
124
|
+
constructors other than this non-success constructor are private: obtain those
|
|
125
|
+
objects from their listed factories, not `.new`, reflection or deserialization.
|
|
126
|
+
Exception classes are rescue targets, not proof objects. No exception message,
|
|
127
|
+
backtrace or mutable Ruby object identity authenticates a check.
|
|
128
|
+
These objects assume a trusted Ruby process; private construction is API
|
|
129
|
+
discipline, not a sandbox against hostile Ruby code or reflection.
|
|
130
|
+
|
|
131
|
+
Diagnostics are optional guidance. Success has no failure diagnostic; diagnostic
|
|
132
|
+
failure cannot change a verdict. Existing machine identifiers retain their meaning;
|
|
133
|
+
wording/translations and internal lookup-table layout are not frozen.
|
|
134
|
+
See [diagnostic semantics](DIAGNOSTICS.md).
|
|
135
|
+
|
|
136
|
+
## Profiles and defaults
|
|
137
|
+
|
|
138
|
+
Profile version and Gem version are separate. All three profiles below remain v1.
|
|
139
|
+
|
|
140
|
+
| Profile identifier | Selection and supported lifecycle |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `ap2.checkout.single_merchant_sku` | Default for optional `profile_ref:` on InputBuilder trust, CheckoutJWT and CheckoutReceipt. Existing one-product Open → Agent Closed verification. |
|
|
143
|
+
| `ap2.checkout.single_merchant_multi_item` | Explicit selection for those APIs; implicit fixed choice of ConditionalCheckout. One merchant/currency, 1–8 lines, all candidate disclosures and exact quantity allocation. |
|
|
144
|
+
| `ap2.checkout.direct.single_merchant` | Fixed Buyer API profile; pass `Buyer::PROFILE_REF` explicitly to Receipt APIs. One merchant/currency and 1–8 exact-order lines. |
|
|
145
|
+
|
|
146
|
+
Supported profile constants include `TrustContext::PROFILE_REF`, `PROFILE_VERSION`,
|
|
147
|
+
`PROFILE_BODY` and `PROFILE_HASH`, and its corresponding `MULTI_PROFILE_REF`,
|
|
148
|
+
`MULTI_PROFILE_VERSION`, `MULTI_PROFILE_BODY` and `MULTI_PROFILE_HASH` constants.
|
|
149
|
+
`ConditionalCheckout::PROFILE_REF`, `Buyer::PROFILE_REF` and `Buyer::CHECKOUT_PROFILE`
|
|
150
|
+
are supported as well. Their names and existing v1 values remain stable, including
|
|
151
|
+
the constants used by the documented raw-input example. Profile definitions/hashes,
|
|
152
|
+
accepted shapes, bounds, original-wire reference rules and defaults are
|
|
153
|
+
compatibility-sensitive even when implemented by other internal constants.
|
|
154
|
+
See [multi-item limits](MULTI_ITEM_CHECKOUT.md) and
|
|
155
|
+
[Direct limits](BUYER_DIRECT_CHECKOUT.md#profile-and-limits).
|
|
156
|
+
No received claim selects trusted policy; unknown profiles and constraints fail closed.
|
|
157
|
+
|
|
158
|
+
## Persistence and trust boundaries
|
|
159
|
+
|
|
160
|
+
- Persist exact signed JWT/SD-JWT and disclosure strings. `ConditionalCheckout.present`
|
|
161
|
+
restores its three original strings; `Buyer.present_closed` restores its one
|
|
162
|
+
original wire. Neither authenticates a restored presentation.
|
|
163
|
+
- Persist InputBuilder preparation format `"1"` and original trust/selection JSON.
|
|
164
|
+
Use `restore` / `restore_trust`; do not regenerate hashes or issue-time references
|
|
165
|
+
to make changed state match. Restoration does not authenticate storage, establish
|
|
166
|
+
freshness or prove an unused nonce.
|
|
167
|
+
- Receipt reference covers only the final original Closed SD-JWT: `terminal_jws + "~"`
|
|
168
|
+
for the existing conditional profile, or the entire disclosed Direct wire with
|
|
169
|
+
its terminal `~`. It is not the Open chain hash, compact-only JWT or rebuilt JSON.
|
|
170
|
+
- `ResearchEvidence#to_h` is an immutable inspection view, not a signed transport
|
|
171
|
+
credential. There is no JSON/Hash/Marshal reconstruction API for authenticated
|
|
172
|
+
Evidence, results, Trust or other checked objects. Persisted original wires must
|
|
173
|
+
be verified again against current independent inputs.
|
|
174
|
+
- Signing callbacks receive frozen ASCII JWS signing input and return 64 binary
|
|
175
|
+
JOSE ES256 signature bytes. The SDK verifies the returned signature with the
|
|
176
|
+
independently supplied public key. The app owns signer access, timeouts, key
|
|
177
|
+
custody and lifecycle; Provider signing material never enters the Agent API.
|
|
178
|
+
- The app authenticates users, consent, registry/keys/revocation, current orders
|
|
179
|
+
and time. It rechecks authorization, atomically consumes/reserves state, handles
|
|
180
|
+
duplicates and reconciles uncertain outcomes. The SDK performs no network, DB
|
|
181
|
+
or payment operation. An authentic Error Receipt is not permission to retry;
|
|
182
|
+
a missing or unverifiable Receipt leaves the application outcome unknown.
|
|
183
|
+
|
|
184
|
+
## Compatibility and internal boundary
|
|
185
|
+
|
|
186
|
+
The proposed 1.x [versioning, maintenance and deprecation policy](POST_RELEASE_MAINTENANCE.md)
|
|
187
|
+
applies to these calls, types, machine meanings, profiles and persistence contracts.
|
|
188
|
+
The `research` names and syntax-only `verify` keep their current meanings. No 0.8.0
|
|
189
|
+
API migration is required by this candidate; an actual 1.0.0 publication remains a
|
|
190
|
+
separate release decision.
|
|
191
|
+
|
|
192
|
+
Internal `verified_*!` handoffs are not supported ways to inject checked facts;
|
|
193
|
+
[the existing support contract](SUPPORT_CONTRACT.md#result-and-evidence) already
|
|
194
|
+
excludes them. Private helpers, unlisted validator/factory helpers, diagnostic
|
|
195
|
+
catalogs, internal constant layouts and research/test scripts are implementation
|
|
196
|
+
details, not extension hooks. Ruby visibility alone does not make them an SDK API.
|
|
197
|
+
This does not remove the published partial-verification entries above, their
|
|
198
|
+
observable error behavior, or the documented profile identities and bounds.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# 1.0.0 release candidate preparation
|
|
2
|
+
|
|
3
|
+
**Unpublished candidate. The currently published release is 0.8.0.**
|
|
4
|
+
The candidate Gem has version `1.0.0`; that metadata is not a publication record.
|
|
5
|
+
The [preparation evidence](evidence/1.0.0_preparation.json) identifies the actual
|
|
6
|
+
source, archive, observed checks and remaining gates. A later publication must
|
|
7
|
+
identify the exact approved bytes separately.
|
|
8
|
+
|
|
9
|
+
## Purpose and supported scope
|
|
10
|
+
|
|
11
|
+
1.0.0 establishes the [public Ruby API](PUBLIC_API.md) and
|
|
12
|
+
[1.x compatibility and maintenance policy](POST_RELEASE_MAINTENANCE.md).
|
|
13
|
+
It keeps the 0.8.0 runtime implementation and supported Checkout profiles.
|
|
14
|
+
|
|
15
|
+
| Workflow | Included in the public contract |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| Merchant Checkout | Sign and verify the supported original Checkout JWT. |
|
|
18
|
+
| Direct human-approved order | Issue, present and verify the Provider-signed exact order. |
|
|
19
|
+
| Conditional purchase | Issue Open conditions; generate/present Agent-signed Closed; verify the complete chain with independent current trust, order, challenge and time inputs. |
|
|
20
|
+
| Checkout Receipt | Reference the exact final Closed SD-JWT; sign and verify authentic Success/Error outcomes. |
|
|
21
|
+
|
|
22
|
+
All workflows are plain Ruby. Rails is an integration example. A 1.0.0 SDK
|
|
23
|
+
version does not assert coverage of every AP2 feature, certification, application
|
|
24
|
+
authorization or payment execution. The adopted official AP2 source stays at
|
|
25
|
+
`b4587ac1d055888a73b4b21750973cffba961793`.
|
|
26
|
+
|
|
27
|
+
## Changes from 0.8.0
|
|
28
|
+
|
|
29
|
+
- Explicit public API, return/exception, profile/default and persistence contracts.
|
|
30
|
+
- Current SDK metadata, security reporting, maintenance and product guidance.
|
|
31
|
+
- Aligned 1.0.0 package checks and development lockfile; newly packaged public API,
|
|
32
|
+
input preparation, security and maintenance documentation.
|
|
33
|
+
- Independent Python-generated conditional inputs exercised through the public
|
|
34
|
+
complete verifier and Receipt APIs, including installed-Gem mode and signed
|
|
35
|
+
negative controls. Existing internal-boundary comparisons remain separate.
|
|
36
|
+
|
|
37
|
+
There are no runtime `lib/` changes, profile/default changes, new runtime
|
|
38
|
+
dependencies or renamed APIs. Existing `verify_research`, research-named results,
|
|
39
|
+
syntax-only `verify`, saved preparation format `"1"` and Evidence v2 remain.
|
|
40
|
+
MRI 3.4.12 and 4.0.9 remain the formally supported versions. Installation metadata
|
|
41
|
+
`>= 3.4.12, < 4.1` does not certify every version in that range. Runtime pins remain
|
|
42
|
+
JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1.
|
|
43
|
+
|
|
44
|
+
## Migration and candidate inspection
|
|
45
|
+
|
|
46
|
+
Applications using documented 0.8.0 APIs need no source migration for this
|
|
47
|
+
candidate. A dependency such as `~> 0.8.0` does not select 1.0.0. After publication,
|
|
48
|
+
use an explicit compatible constraint (for example `~> 1.0`) and update this Gem
|
|
49
|
+
in the application's lockfile. Do not treat a successful verification, an
|
|
50
|
+
authentic Receipt or successful installation as application purchase permission.
|
|
51
|
+
|
|
52
|
+
To inspect a prepared local candidate, install its exact file in an isolated
|
|
53
|
+
Gem environment whose fixed dependencies are already installed:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
gem install --local --no-document /absolute/path/ap2_mandate_verifier-1.0.0.gem
|
|
57
|
+
ruby -rap2_mandate_verifier -e 'puts Gem.loaded_specs.fetch("ap2_mandate_verifier").version'
|
|
58
|
+
ruby -e 'spec = Gem::Specification.find_by_name("ap2_mandate_verifier", "= 1.0.0"); load File.join(spec.full_gem_path, "examples/conditional_checkout.rb")'
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The standalone synthetic example covers Open → Agent Closed → complete
|
|
62
|
+
verification → Success/Error Receipt. The application's identity, consent,
|
|
63
|
+
key custody, revocation, persistent replay protection and payment integration
|
|
64
|
+
remain its responsibility. Unknown execution outcomes remain pending until the
|
|
65
|
+
application reconciles them.
|
|
66
|
+
|
|
67
|
+
## Required release evidence
|
|
68
|
+
|
|
69
|
+
| Check | Required evidence |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| Scope and compatibility | Diff against the 0.8.0 baseline; unchanged runtime code, profile definitions/defaults and five dependency pins; public API/source review. |
|
|
72
|
+
| Source regression | Existing 17 suite entry points on both supported MRI versions, preserving individual results without double-counting transitive suites. |
|
|
73
|
+
| Exact package | One final archive built after packaged content is fixed; SHA256/size and all payloads matched against source and ordinary installation on both Rubies. |
|
|
74
|
+
| Installed behavior | Original saved-input/oracle checks, diagnostics, signing/Direct/multi-item/conditional examples and conditional tests loaded from the installed Gem. |
|
|
75
|
+
| Interoperability | Pinned official Python source and recorded dependencies; external signatures, original-wire hashes, supported Schema and complete public verification; signed causal negatives and authentic Success/Error Receipts. |
|
|
76
|
+
| Review and repository gates | Independent review of the actual final source, no unresolved substantive P1/P2, applicable branch protection and bounded CI recorded separately from local tests. |
|
|
77
|
+
| Publication | Owner approval for the exact source/archive, followed by RubyGems distribution comparison and exact-source public tag/Release. Preparation does not perform these actions. |
|
|
78
|
+
|
|
79
|
+
The existing Debian-container source/package procedure is
|
|
80
|
+
`scripts/check_ruby_compatibility.sh` followed by
|
|
81
|
+
`scripts/check_candidate_package.sh OUTPUT_DIR ABSOLUTE_GEM_PATH`.
|
|
82
|
+
Pass the **same archive** to each supported Ruby; separately built CI candidates
|
|
83
|
+
do not establish byte identity across runtimes.
|
|
84
|
+
|
|
85
|
+
The conditional interoperability command, from this source checkout, is:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
AP2_INSTALLED=1 AP2_GEM_VERSION=1.0.0 \
|
|
89
|
+
AP2_OFFICIAL_ROOT=/absolute/path/to/pinned-ap2 \
|
|
90
|
+
PYTHONPATH=/absolute/path/to/pinned-ap2/code/sdk/python \
|
|
91
|
+
python test/conditional_interop.py
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`PATH` must select the supported Ruby, and `GEM_HOME`/`GEM_PATH` must select the
|
|
95
|
+
normally installed candidate and fixed dependencies. No product source directory
|
|
96
|
+
may be added to Ruby's load path in installed mode. The Python check asserts
|
|
97
|
+
official source/Schema location consistency and must be run with the recorded
|
|
98
|
+
fixed source and dependency identities. Its supported inline Closed subset does
|
|
99
|
+
not include the official helper's selectively disclosed terminal representation.
|
|
100
|
+
|
|
101
|
+
## Preparation boundary
|
|
102
|
+
|
|
103
|
+
This work follows the Owner's request to prepare 1.0.0, from main
|
|
104
|
+
`7facf5e21699c754eb3e046ee2c653c6ce2c16cf`. Review covers the public contract,
|
|
105
|
+
metadata/package checks and the additional independent test; the application's
|
|
106
|
+
trust registry and current business state remain independent test inputs.
|
|
107
|
+
Existing Issue #101 process and separate legacy research gates are retained.
|
|
108
|
+
Unexpected source/dependency drift, secret exposure, unplanned external cost,
|
|
109
|
+
inconclusive checks or substantive review findings block release readiness.
|
|
110
|
+
|
|
111
|
+
Current public distribution remains 0.8.0 until its successor is actually
|
|
112
|
+
published and verified. A local pass, review result, PR or candidate artifact is
|
|
113
|
+
not a release, real-Issuer attestation or production authorization.
|
data/docs/SUPPORT_CONTRACT.md
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
|
-
#
|
|
1
|
+
# AP2 Checkout Ruby SDK — support contract and history
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Current contract and unpublished 1.0.0 preparation
|
|
4
|
+
|
|
5
|
+
**Published stable remains 0.8.0. The working 1.0.0 candidate is unpublished.**
|
|
6
|
+
The candidate preserves the existing product implementation and acceptance
|
|
7
|
+
contracts. Its intended 1.x public surface is catalogued in
|
|
8
|
+
[PUBLIC_API](PUBLIC_API.md); candidate evidence and outstanding decisions are in
|
|
9
|
+
[the preparation record](RELEASE_100_CANDIDATE.md). Historical observations below
|
|
10
|
+
are not new 1.0.0 test results.
|
|
11
|
+
|
|
12
|
+
| Current supported flow | Contract |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| Direct exact-order approval | Checkout authentication, Provider Closed issuance, original presentation, full Direct verification and Receipt confirmation: [Direct](BUYER_DIRECT_CHECKOUT.md). |
|
|
15
|
+
| Conditional purchase delegation | Provider Open issuance, Agent Closed generation/presentation, existing full verification and Receipt confirmation: [Conditional Checkout](CONDITIONAL_CHECKOUT.md). |
|
|
16
|
+
| Existing verification and business inputs | Both Open → Agent Closed profiles, InputBuilder trust/preparation/restoration, immutable Result/Evidence and supplemental diagnostics: [public API](PUBLIC_API.md). |
|
|
17
|
+
| Merchant signing and Receipts | Checkout signing and explicit Success/Error outcome authentication with original-wire references: [Merchant signing](MERCHANT_SIGNING.md). |
|
|
18
|
+
|
|
19
|
+
Formal support remains MRI 3.4.12 and MRI 4.0.9 with JSON 2.19.9, JWT 3.3.0,
|
|
20
|
+
base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. The Gem's Ruby resolution range
|
|
21
|
+
does not certify every intervening version, engine, OS or native provider.
|
|
22
|
+
AP2 source `b4587ac1d055888a73b4b21750973cffba961793`, the three documented v1
|
|
23
|
+
profile identities and InputBuilder preparation format `1` remain unchanged.
|
|
24
|
+
|
|
25
|
+
Each API retains its result/exception convention, including the existing `research`
|
|
26
|
+
names and partial APIs' non-success behavior. A verification failure or signing
|
|
27
|
+
`Invalid` is not automatically proof of malformed business data; see
|
|
28
|
+
[failure handling](PUBLIC_API.md#result-object-and-failure-contracts).
|
|
29
|
+
The app owns current trust, consent, durable state and final execution. Ruby SDK
|
|
30
|
+
support does not establish general AP2 compatibility, Payment support, actual
|
|
31
|
+
Issuer trust or a particular Host's production authorization.
|
|
32
|
+
|
|
33
|
+
The [maintenance policy](POST_RELEASE_MAINTENANCE.md) governs proposed 1.x
|
|
34
|
+
versioning, dependency changes, security corrections and deprecation. The sections
|
|
35
|
+
below preserve older publication evidence and API details; statements explicitly
|
|
36
|
+
scoped to old versions do not remove the current flows listed above.
|
|
37
|
+
|
|
38
|
+
## Published 0.8.0 conditional delegation
|
|
4
39
|
|
|
5
40
|
`ConditionalCheckout.issue_open/issue_closed/present` add conditional delegation
|
|
6
41
|
issuance and original-wire presentation under the unchanged explicit multi-item
|
|
@@ -8,7 +43,12 @@ profile v1. [Contract, errors, limits and application responsibilities](CONDITIO
|
|
|
8
43
|
The packaged standalone example uses only public installed APIs. No old default,
|
|
9
44
|
profile definition/hash, Result/Evidence/diagnostic, saved record or Receipt
|
|
10
45
|
acceptance condition is changed. All candidates remain required; no new selective
|
|
11
|
-
disclosure profile is introduced. Published stable
|
|
46
|
+
disclosure profile is introduced. Published stable is 0.8.0, registered
|
|
47
|
+
2026-11-01 06:01:31.103 UTC and compared 06:03:20 UTC: 79,872 bytes, SHA256
|
|
48
|
+
`6c07664e4291aa8bc025b152075869322411a0d99861e1267959f1794e99acec`.
|
|
49
|
+
All29 payloads match published source `5a7394c1b98f000b321423e2c2f80d50b5157808`.
|
|
50
|
+
[Publication and new installed-Gem checks](POST_RELEASE_080.md). The archive's
|
|
51
|
+
candidate-time documents remain unchanged; repository updates do not replace it.
|
|
12
52
|
|
|
13
53
|
Published 0.7.0 adds the separate [Direct buyer module](BUYER_DIRECT_CHECKOUT.md):
|
|
14
54
|
merchant Checkout verification before human approval, Provider-signed issuance,
|
|
@@ -118,13 +158,13 @@ Gem-owned signature/original-wire/closure, delegation, binding, supplied-trust s
|
|
|
118
158
|
Host inputs must be authenticated, independent of the token and current: trust/keys/profile/revocation/rollback protection, clock and order/challenge state. Recheck before use; atomically consume nonce with order CAS, reconcile unknown results as PENDING, and decide final ALLOW/payment separately.
|
|
119
159
|
Evidence is immutable checked facts in the same trusted Ruby process, not ALLOW or a transport credential. JSON/Hash reconstruction does not authenticate it. Rejection, unavailability, exceptions and no result never authorize an operation. Trusted Ruby is a precondition, not a malicious-Ruby sandbox.
|
|
120
160
|
|
|
121
|
-
No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds.
|
|
161
|
+
No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds. Direct and conditional issuance/presentation are supported by their separate contracts above. Rails adapters, real payments and Host DB operations remain outside the Gem. Separate merchant signing/Checkout Receipt APIs are documented in [MERCHANT_SIGNING](MERCHANT_SIGNING.md).
|
|
122
162
|
Supported-input semantics and existing API/status/code/Evidence contracts must not change silently. Security-driven acceptance narrowing requires impact/reason/migration disclosure; breaking required-field/profile/API changes must be explicit. Dependency updates are not automatically compatible.
|
|
123
163
|
|
|
124
164
|
The published 0.2.0 and historical baseline below is MRI4.0.9 plus JSON2.19.9/JWT3.3.0/base640.3.0/OpenSSL gem4.0.2/Digest3.2.1, with the exact observed MBA arm64-darwin25 and Ubuntu24.04/x86_64 configurations. RubyGems version constraints do not enforce MRI/OS/provider identity. All OS versions, other engines/architectures and arbitrary provider updates are not supported by past observations.
|
|
125
165
|
Historical D3 observed MBA component identities and four selected crypto symbol sources; OS dyld hashes/all symbol bindings/global runtime security remain unproved. JSON2.19.9 official IO-buffer fix/tag/source identity is adopted static evidence; inconsistent GHSA patched-version metadata remains recorded. Neither observation is global S3 PASS. The earlier R1 archive subsequently passed Mac/Ubuntu packaging checks. It is a different archive; see the separate release-package record for current bytes and observations.
|
|
126
166
|
|
|
127
|
-
|
|
167
|
+
Maintenance contact: Owner cuichangquan via repository Issues for ordinary bugs and private vulnerability reporting for vulnerabilities. No secrets, real Mandates or personal data in reports. Current maintenance scope and versioning are in [POST_RELEASE_MAINTENANCE](POST_RELEASE_MAINTENANCE.md); no prerelease/old-series backport, fixed support years, response/fix/disclosure deadline or 24/7 promise is added here.
|
|
128
168
|
Manual dependency/provider review is adopted monthly, on relevant advisories and before releases; no active automatic monitor is implied. Updates/deprecation/end of support must identify affected versions, reason and migration path without inventing a fixed notice period. Known major unaddressed issues or inability to maintain mean HOLD, not a blanket disclaimer.
|
|
129
169
|
|
|
130
170
|
## Existing API/limits and historical evidence baseline
|
|
@@ -242,6 +282,11 @@ constructors do not sandbox malicious Ruby/reflection in that same process.
|
|
|
242
282
|
|
|
243
283
|
## Parsing, schema and time boundaries
|
|
244
284
|
|
|
285
|
+
The single-product shape/count statements in this section preserve the original
|
|
286
|
+
profile. The [multi-item](MULTI_ITEM_CHECKOUT.md) and
|
|
287
|
+
[Direct](BUYER_DIRECT_CHECKOUT.md) contracts specify their separate shapes and
|
|
288
|
+
limits; the [conditional API](CONDITIONAL_CHECKOUT.md) reuses the multi-item profile.
|
|
289
|
+
|
|
245
290
|
Header/payload parse before signature enforces strict bounded syntax only.
|
|
246
291
|
JSON2.19.9 duplicate rejection remains on, including escaped duplicate keys;
|
|
247
292
|
BOM/comments/trailing commas/nonfinite numbers are rejected. JOSE is fixed alg/
|