ap2_mandate_verifier 0.7.0 → 0.8.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 +182 -0
- data/README.md +36 -11
- data/docs/BUYER_DIRECT_CHECKOUT.md +5 -5
- data/docs/CONDITIONAL_CHECKOUT.md +168 -0
- data/docs/MERCHANT_SIGNING.md +1 -1
- data/docs/RELEASE_080_CANDIDATE.md +109 -0
- data/docs/SUPPORT_CONTRACT.md +23 -2
- data/examples/conditional_checkout.rb +84 -0
- data/lib/ap2_mandate_verifier/conditional_checkout.rb +150 -0
- data/lib/ap2_mandate_verifier/merchant_signature.rb +7 -3
- data/lib/ap2_mandate_verifier/root_disclosures.rb +24 -1
- data/lib/ap2_mandate_verifier/scoped_constraints.rb +12 -7
- data/lib/ap2_mandate_verifier.rb +1 -0
- metadata +6 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b6973632ca480195ff57ea153dba920906287f8064357e0cd1069e75b2da58e1
|
|
4
|
+
data.tar.gz: 3f20dac53518631270fb9c9ff7e84dc0e9f8ae96cb78189431cb7f8d20e4f99f
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 1be1321379cc84f7a517a546486d146eee9b978f8139ea9940c894f46661b1d4fa3266e8a0d90c454b00cae0c19869885905470c14e38a141e06e5aa577fbfd4
|
|
7
|
+
data.tar.gz: 2da4d81e6fbcfdd4bd03bad264fe150e31974671e536fdfa6e62387ec4d934d8c57c3dc7294a37981d930d018a4bf5477efaf77d3c20ab654e7fafd9e9cc0bce
|
data/README.ja.md
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# AP2 Mandate Verifier — 0.7.0
|
|
2
|
+
|
|
3
|
+
[English](README.md)
|
|
4
|
+
|
|
5
|
+
## 0.8.0候補:条件付き購入委任(未公開)
|
|
6
|
+
|
|
7
|
+
`ConditionalCheckout.issue_open`、`.issue_closed`、`.present` を追加します。
|
|
8
|
+
A/Bから1個とCを2個という条件を承認サービスが登録Agent鍵へOpenとして発行し、
|
|
9
|
+
Agentが条件に合う販売者署名CheckoutをClosedにします。既存 `InputBuilder.verify` と
|
|
10
|
+
`CheckoutReceipt.sign/verify` へ接続します。全候補開示の複数商品profileを維持し、
|
|
11
|
+
Agent処理へProvider秘密鍵を渡しません。[API・信頼境界](docs/CONDITIONAL_CHECKOUT.md)、
|
|
12
|
+
[公開判断資料](docs/RELEASE_080_CANDIDATE.md)を参照してください。
|
|
13
|
+
|
|
14
|
+
正式対応MRI 3.4.12/4.0.9で、候補manifestに対応するローカルGemを取得した後:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
gem install --local ./ap2_mandate_verifier-0.8.0.gem
|
|
18
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.8.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
[Ruby単体の実行例](examples/conditional_checkout.rb)はインストール済み公開APIだけを使い、
|
|
22
|
+
3明細・候補選択・異なる要件数量・同一商品の別行からSuccess/Error Receiptまで動きます。
|
|
23
|
+
Success後は消費済み、Error後は再提示方針を再判断、Receipt未到着や結果不明は保留です。
|
|
24
|
+
本人認証・同意・購買権限・信頼先登録・永続的な重複防止・注文や決済の実行はアプリ責務です。
|
|
25
|
+
0.7.0利用者の移行は不要で、既存既定値・保存形式を維持します。0.8.0は未公開候補です。
|
|
26
|
+
|
|
27
|
+
公開済み安定版は **0.7.0** です。Direct購入側の発行・提示・販売者検証・Receipt確認を追加し、1販売者・1〜8明細・複数商品に一貫対応します。既存Open→Closedの契約は維持します。[公開記録](docs/PROJECT_STATUS.md#070-publication)を参照してください。
|
|
28
|
+
|
|
29
|
+
## 複数商品と数量
|
|
30
|
+
|
|
31
|
+
新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明細の受理範囲を維持します。
|
|
32
|
+
|
|
33
|
+
単一販売者・単一Checkout・単一通貨で最大8明細を扱い、数量違いと同一商品の別行を支持します。開示候補の商品IDを整数最大流で照合し、全要件と全注文数量を過不足なく一度ずつ充当します。数量不足・余剰は拒否し、要件IDと明細IDは別の識別子です。[詳細・移行案内](docs/MULTI_ITEM_CHECKOUT.md)、[合成入力による一連の動作例](examples/multi_item_checkout.rb)、[公式Python SDKとの数量不足・空候補・Receipt参照の差異](docs/MULTI_ITEM_INTEROP.md)を参照してください。
|
|
34
|
+
|
|
35
|
+
Rubyで購入委任データを検証する、AP2の固定profile向けGemです。署名データを、Hostが独立して渡す信頼情報・注文情報と照合し、不変のEvidenceを返します。**検証成功は購入許可・決済許可ではありません。**
|
|
36
|
+
|
|
37
|
+
`InputBuilder` は業務情報から検証入力を作り、Gem独自のtrust/selection/Host JSON、fingerprint、署名原文のdigest計算を担当します。誰を信頼するかの選択、期待する注文・Challenge状態・時計は利用者が渡します。Rails非依存で、通信・DB・決済処理は行いません。
|
|
38
|
+
|
|
39
|
+
## ローカルデモを試す
|
|
40
|
+
|
|
41
|
+
[把握しやすいRailsデモ](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)は、公開済み0.7.0とInputBuilderを通常経路で使います。Docker手順ならホストへのRuby導入は不要です。正常・改ざん・期限切れのstatus/code・診断・Evidence有無に加え、複数商品と数量違い、後続明細の数量不足拒否、真正な成功/拒否Receiptも試せます。ローカル専用で、実Challenge発行・nonce消費・購入実行は行いません。
|
|
42
|
+
|
|
43
|
+
## インストール
|
|
44
|
+
|
|
45
|
+
正式対応は **MRI 3.4.12とMRI 4.0.9** です。利用者が選ぶGem環境で導入します。
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
gem install ap2_mandate_verifier --version 0.7.0
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
BundlerのGemfile:
|
|
52
|
+
|
|
53
|
+
```ruby
|
|
54
|
+
gem "ap2_mandate_verifier", "= 0.7.0"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
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)を参照してください。
|
|
58
|
+
|
|
59
|
+
## 販売者署名とReceipt
|
|
60
|
+
|
|
61
|
+
注文JWTを署名し、利用アプリが明示した処理結果をReceiptとして署名できます。
|
|
62
|
+
0.5.0で追加され、0.7.0でも利用できるAPIです。この抜粋は既定の単一商品profileです。`checkout`は注文Hash、`key`はアプリ所有のP-256鍵、
|
|
63
|
+
`received_closed_sd_jwt`は受信した最終inline SD-JWT原文、`now`はアプリの時計です。
|
|
64
|
+
|
|
65
|
+
```ruby
|
|
66
|
+
signing = AP2MandateVerifier::CheckoutJWT
|
|
67
|
+
signed = signing.sign(checkout: checkout, signer: signing.es256_signer(private_key: key),
|
|
68
|
+
public_key_pem: key.public_to_pem)
|
|
69
|
+
# signed.jwtの原文を保持し、InputBuilderのhost_checkout_jwsへ渡します。
|
|
70
|
+
receipt = AP2MandateVerifier::CheckoutReceipt.sign(closed_sd_jwt: received_closed_sd_jwt,
|
|
71
|
+
issuer: "shop", outcome: "Error", error: "declined", error_description: "Application declined",
|
|
72
|
+
issued_at: now, signer: signing.es256_signer(private_key: key), public_key_pem: key.public_to_pem)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
受信時は独立した信頼鍵・期待署名者・明示時刻範囲・対象Mandateの原文参照を照合します。
|
|
76
|
+
真正な拒否は `verified? == true`、`purchase_succeeded? == false` です。
|
|
77
|
+
[完全動作例](examples/merchant_signing.rb)と[対応原文形状・SDKとの差異](docs/MERCHANT_SIGNING.md)を参照してください。
|
|
78
|
+
|
|
79
|
+
## InputBuilderの最小例
|
|
80
|
+
|
|
81
|
+
導入後、このリポジトリをcheckoutし、以下をルートの `quick_start.rb` として保存して `ruby quick_start.rb` を実行します。[`examples/input_builder/`](examples/input_builder/)のJSONファイルは、明示された合成注文・公開鍵登録情報と署名原文Stringです。インストール済みGemには含まれません。保存署名には期限があるため固定の合成時計を使います。実登録や本番の現在情報として再利用しないでください。
|
|
82
|
+
|
|
83
|
+
```ruby
|
|
84
|
+
require "ap2_mandate_verifier"
|
|
85
|
+
require "json"
|
|
86
|
+
require "tmpdir"
|
|
87
|
+
|
|
88
|
+
builder = AP2MandateVerifier::InputBuilder
|
|
89
|
+
fixtures = File.join(__dir__, "examples/input_builder")
|
|
90
|
+
read = ->(name) { JSON.parse(File.binread(File.join(fixtures, "#{name}.json"))) }
|
|
91
|
+
trust_at = ->(now) do
|
|
92
|
+
builder.trust(snapshot: read.call("trust_snapshot"), tenant_id: "synthetic-tenant",
|
|
93
|
+
issuer: {"identity" => "issuer", "purpose" => "checkout", "key_ref" => "issuer-1"},
|
|
94
|
+
agent: {"identity" => "agent", "purpose" => "checkout", "key_ref" => "agent-1"},
|
|
95
|
+
merchant: {"identity" => "shop", "purpose" => "checkout", "key_ref" => "merchant-1"},
|
|
96
|
+
verified_at: now)
|
|
97
|
+
end
|
|
98
|
+
wires = read.call("signed_wires").transform_keys(&:to_sym) # 原文Stringのbytesを保持。
|
|
99
|
+
|
|
100
|
+
# 発行前:独立した注文・信頼情報と、Hostが選んだChallenge情報。
|
|
101
|
+
prepared = builder.prepare(trust: trust_at.call(1_800_000_000),
|
|
102
|
+
order: read.call("order"), root_presentation: wires.fetch(:root_presentation),
|
|
103
|
+
host_checkout_jws: wires.fetch(:host_checkout_jws),
|
|
104
|
+
challenge_id: "synthetic-challenge", nonce: "n", issuer_id: "synthetic-host",
|
|
105
|
+
not_before: 1_799_998_000, not_after: 1_800_002_000)
|
|
106
|
+
|
|
107
|
+
Dir.mktmpdir do |directory|
|
|
108
|
+
record = File.join(directory, "challenge.json")
|
|
109
|
+
File.binwrite(record, prepared) # デモ用保存。本物の保存処理はHostの責任。
|
|
110
|
+
|
|
111
|
+
# 検証時:保存原文を読み戻し、現在の注文・信頼情報を独立して取得。
|
|
112
|
+
now = 1_800_000_000 # 外部から供給する合成時計。本番の時刻取得ではない。
|
|
113
|
+
result = builder.verify(trust: trust_at.call(now),
|
|
114
|
+
saved_challenge: builder.restore(saved_challenge: File.binread(record)),
|
|
115
|
+
order: read.call("order"), **wires,
|
|
116
|
+
expected_challenge_issuer_id: "synthetic-host",
|
|
117
|
+
clock_source_id: "fixed-synthetic-clock", verified_at: now)
|
|
118
|
+
puts "#{result.status}/#{result.code}; evidence=#{!result.evidence.nil?}"
|
|
119
|
+
raise "Verification did not succeed; stop" unless result.success?
|
|
120
|
+
end
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
変更していない合成入力の期待値は `verified_research/scoped_research_verified; evidence=true` です。準備・保存・後の検証を1プロセス内で示す例であり、実発行や原子的消費を実装していません。実連携では、認証済みの登録・注文情報を明示的に対応付け、署名原文を保持します。構造化業務入力にはStringキーの通常のRuby値を使い、ActiveRecordオブジェクトそのものは渡しません。
|
|
124
|
+
|
|
125
|
+
検証時に `prepare` をやり直したり、保存hash/参照を現在値に合わせて更新したりしないでください。注文・信頼情報・署名原文の変化は検出できるままにします。保存済みtrust JSONは `restore_trust` で再シリアライズせず読み戻せます。[完全例](examples/input_builder.rb)には正常・改ざん・期限切れがあり、[利用案内](docs/INPUT_BUILDER.ja.md)に業務field・原文復元・Railsモデル対応付けを示しています。
|
|
126
|
+
|
|
127
|
+
## 結果と責任境界
|
|
128
|
+
|
|
129
|
+
| 結果 | 意味と利用者の処理 |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| `:verified_research` / `:scoped_research_verified`、`success? == true` | 不変のEvidenceに固定profileの検査事実があります。購入を許可するかは、Hostが別途判断します。 |
|
|
132
|
+
| `:rejected`、`rejected? == true` | Evidenceなし。停止して `result.code` を確認します。 |
|
|
133
|
+
| `:unavailable`、`unavailable? == true` | Evidenceなし。停止します。依存・処理の失敗だけで業務入力が不正とは断定しません。 |
|
|
134
|
+
|
|
135
|
+
失敗時は追加の確認ヒントを取得できます。成功時の診断は `nil` です。
|
|
136
|
+
|
|
137
|
+
```ruby
|
|
138
|
+
if (diagnostic = result.diagnostic)
|
|
139
|
+
puts diagnostic.to_h(locale: :ja) # 英語は :en
|
|
140
|
+
end
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`stage / field / reason / hint` は確認候補であり、status/codeや判定を変えません。特定不能な項目・原因は断定しません。[詳しい診断ガイド](docs/DIAGNOSTICS.ja.md)を参照してください。
|
|
144
|
+
|
|
145
|
+
例外・プロセス終了・結果なしでも、購入を許可しません。raw入力・nonceをログに出したり、シリアライズしたEvidenceを認証済みの資格情報として扱ったりしないでください。
|
|
146
|
+
|
|
147
|
+
Gemは署名、支持する開示閉包、委任、購入/Host binding、制約・期限を検査します。Hostは認証済み・独立・最新のtrust/鍵/失効、注文・Challenge状態、時計を供給します。実行直前に現在状態と期限を再照合し、nonceの原子消費+注文CAS、不明結果の回復、最終許可・決済判断を担当します。`prepare`/`restore` は保存元の認証やnonce未使用を証明しません。
|
|
148
|
+
|
|
149
|
+
公開済み0.7.0は既定の固定profile `ap2.checkout.single_merchant_sku` v1(ES256/P256、単一Merchant/SKU/cart行、USD/EUR/JPYと文書化した開示形状)を維持し、明示選択の[複数明細profile](docs/MULTI_ITEM_CHECKOUT.md)を追加します。未知・非対応形式は拒否します。一般AP2/全Schema、実Issuer互換性、Open Mandate発行・Agent Closed生成、Rails adapter、DB/決済実行、数値性能保証は対象外です。実Issuer・実Hostの本番GOとPhase 2-Bは引き続き別のHOLDです。
|
|
150
|
+
|
|
151
|
+
### APIの使い分け
|
|
152
|
+
|
|
153
|
+
| 入口 | 役割 |
|
|
154
|
+
| --- | --- |
|
|
155
|
+
| `InputBuilder.verify(**business_information)` | 0.7.0の推奨業務情報経路。入力を組み立て、完全検証します。発行前準備・復元は上の例の別処理です。 |
|
|
156
|
+
| `verify_checkout(**inputs)` | 既存の7入力を直接渡す完全検証。trust/selection/Host JSONも呼出側が渡します。 |
|
|
157
|
+
| `verify_research(**inputs)` | 同じ7入力検証経路の維持された名称。非推奨警告はありません。 |
|
|
158
|
+
| `verify(presentation_json:)` | 旧JSON構文検査のみ。成功Evidenceを返しません。 |
|
|
159
|
+
|
|
160
|
+
`InputBuilder.verify` の不足keywordを含む組み立て引数不正は `:rejected / :invalid_host_context`、組み立て中の依存・予期しない失敗は `:unavailable / :research_verification_unavailable` です。完全検証に入った後のcodeは維持します。一方、直接の `verify_checkout`/`verify_research` の不足・未知keywordは `:unavailable / :research_verification_unavailable` です。これらの非成功では、すべて `success? == false`、`evidence == nil` になります。形状・上限・Rubyの引数束縛上の注意は[正確な契約](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs)を参照してください。
|
|
161
|
+
|
|
162
|
+
## 詳細リンク
|
|
163
|
+
|
|
164
|
+
- [業務情報の一連の利用とRails対応付け](docs/INPUT_BUILDER.ja.md)、[完全Ruby例](examples/input_builder.rb)、[変更前の例](examples/input_builder_before.rb)。
|
|
165
|
+
- [支持入力・上限・Result/Evidence契約](docs/SUPPORT_CONTRACT.md)、[Issuer/Host責務](docs/ISSUER_HOST_MINIMUM_CONTRACT.md)。
|
|
166
|
+
- [0.7.0 Release notes](docs/RELEASE_070.md)、[公開・撤回記録](docs/PROJECT_STATUS.md)、[変更履歴](CHANGELOG.md)。リポジトリREADMEの変更で公開Gemを再build・置換しません。
|
|
167
|
+
- [固定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の概念)。履歴は保存していますが、現在の連携手順や対応範囲を広げる根拠ではありません。
|
|
168
|
+
- [脆弱性報告](SECURITY.md)、[保守方針](docs/POST_RELEASE_MAINTENANCE.md)、[製品方針](docs/PRODUCT_VISION.md)。秘密鍵・実Mandate・個人情報を報告に含めないでください。
|
|
169
|
+
|
|
170
|
+
MIT。[LICENSE](LICENSE)を参照。
|
|
171
|
+
|
|
172
|
+
### 購入側Direct Checkout(公開済み0.7.0)
|
|
173
|
+
|
|
174
|
+
`CheckoutJWT.verify`で承認前に販売者署名を検証し、Trusted Surfaceの
|
|
175
|
+
承認バックエンドから`Buyer.issue_closed`を呼びます。Shopping Agentは
|
|
176
|
+
`Buyer.present_closed`で提示し、販売者は`Buyer.verify`で検証します。
|
|
177
|
+
Receiptは`profile_ref: Buyer::PROFILE_REF`で生成・確認します。
|
|
178
|
+
1販売者・1〜8明細・複数商品と数量を一貫して扱えます。既存2profileと
|
|
179
|
+
Open→Agent ClosedのAPI契約は維持します。
|
|
180
|
+
[仕様・責任境界](docs/BUYER_DIRECT_CHECKOUT.md)と
|
|
181
|
+
[承認からReceiptまでの実行例](examples/direct_checkout.rb)を参照してください。
|
|
182
|
+
検証成功は購買権限や実決済成功を意味しません。[短い動作確認済みサンプル](docs/RELEASE_070.md)も参照してください。
|
data/README.md
CHANGED
|
@@ -1,8 +1,33 @@
|
|
|
1
|
-
# AP2 Mandate Verifier — 0.
|
|
1
|
+
# AP2 Mandate Verifier — 0.7.0
|
|
2
2
|
|
|
3
3
|
[日本語](README.ja.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 0.8.0 candidate: conditional purchase delegation (unpublished)
|
|
6
|
+
|
|
7
|
+
The candidate adds `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`:
|
|
8
|
+
approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
|
|
9
|
+
a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
|
|
10
|
+
`CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
|
|
11
|
+
multi-item profile. Provider private keys never enter Agent operations.
|
|
12
|
+
[API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [release decision material](docs/RELEASE_080_CANDIDATE.md).
|
|
13
|
+
|
|
14
|
+
Quick Start on MRI 3.4.12 or 4.0.9, using the locally built candidate identified by
|
|
15
|
+
the release manifest (0.8.0 is **not published**):
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
gem install --local ./ap2_mandate_verifier-0.8.0.gem
|
|
19
|
+
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "0.8.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
|
|
23
|
+
public APIs, three rows, candidate choice, different requirement quantities and
|
|
24
|
+
repeated products through both Receipt outcomes. Success consumes the operation;
|
|
25
|
+
Error requires a new policy decision; missing Receipt or uncertain effect remains
|
|
26
|
+
pending. Authentication, consent, enrollment, durable replay prevention and actual
|
|
27
|
+
order/payment execution remain app-owned. Existing users need no migration;
|
|
28
|
+
0.7.0 defaults and saved formats remain unchanged.
|
|
29
|
+
|
|
30
|
+
Published stable is **0.7.0**, adding Direct buyer Checkout issuance, presentation and merchant verification through Receipt confirmation. It supports one merchant and 1–8 lines with multiple products. Existing Open→Closed profiles retain their contracts; see [the publication record](docs/PROJECT_STATUS.md#070-publication).
|
|
6
31
|
|
|
7
32
|
## Multiple items and quantities
|
|
8
33
|
|
|
@@ -16,27 +41,27 @@ Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile.
|
|
|
16
41
|
|
|
17
42
|
## Try the local demo
|
|
18
43
|
|
|
19
|
-
The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.
|
|
44
|
+
The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.7.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. Compare synthetic normal, tampered and expired cases, including actual status/code, diagnostics and Evidence presence. It also demonstrates multiple products with differing quantities, later-line quantity rejection, and authentic Success/Error Receipts. It is local-only; it does not issue real challenges, consume nonces or execute purchases.
|
|
20
45
|
|
|
21
46
|
## Install
|
|
22
47
|
|
|
23
48
|
Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
|
|
24
49
|
|
|
25
50
|
```sh
|
|
26
|
-
gem install ap2_mandate_verifier --version 0.
|
|
51
|
+
gem install ap2_mandate_verifier --version 0.7.0
|
|
27
52
|
```
|
|
28
53
|
|
|
29
54
|
Or add to your Gemfile:
|
|
30
55
|
|
|
31
56
|
```ruby
|
|
32
|
-
gem "ap2_mandate_verifier", "= 0.
|
|
57
|
+
gem "ap2_mandate_verifier", "= 0.7.0"
|
|
33
58
|
```
|
|
34
59
|
|
|
35
60
|
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).
|
|
36
61
|
|
|
37
62
|
## Merchant signing and Receipt
|
|
38
63
|
|
|
39
|
-
Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 0.
|
|
64
|
+
Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 0.7.0; the excerpt uses the default single-SKU profile.
|
|
40
65
|
Here `checkout` is the application order Hash, `key` its P-256 signing key,
|
|
41
66
|
`received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
|
|
42
67
|
|
|
@@ -125,13 +150,13 @@ Exceptions, process failure and missing results also never authorize an operatio
|
|
|
125
150
|
|
|
126
151
|
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.
|
|
127
152
|
|
|
128
|
-
Published 0.
|
|
153
|
+
Published 0.7.0 retains the default `ap2.checkout.single_merchant_sku` v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and its documented disclosure shapes. It adds the explicitly selected [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer interoperability, Open Mandate issuance/presentation, Rails adapters, DB/payment execution and numeric performance guarantees remain outside scope. Real Issuer/Host production GO and Phase 2-B remain separate HOLDs.
|
|
129
154
|
|
|
130
155
|
### Which API should I use?
|
|
131
156
|
|
|
132
157
|
| Entry | Role |
|
|
133
158
|
| --- | --- |
|
|
134
|
-
| `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.
|
|
159
|
+
| `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.7.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
|
|
135
160
|
| `verify_checkout(**inputs)` | Direct complete verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
|
|
136
161
|
| `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
|
|
137
162
|
| `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
|
|
@@ -142,13 +167,13 @@ Malformed assembly arguments, including missing keywords, to `InputBuilder.verif
|
|
|
142
167
|
|
|
143
168
|
- [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).
|
|
144
169
|
- [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
|
|
145
|
-
- [0.
|
|
170
|
+
- [0.7.0 Release notes](docs/RELEASE_070.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
|
|
146
171
|
- [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.
|
|
147
172
|
- [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.
|
|
148
173
|
|
|
149
174
|
MIT. See [LICENSE](LICENSE).
|
|
150
175
|
|
|
151
|
-
### Buyer Direct checkout (0.7.0
|
|
176
|
+
### Buyer Direct checkout (published 0.7.0)
|
|
152
177
|
|
|
153
178
|
Trusted Surface backends can verify a merchant Checkout before approval, issue a
|
|
154
179
|
Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
|
|
@@ -158,4 +183,4 @@ One merchant, 1–8 lines, multiple products and quantities are supported end to
|
|
|
158
183
|
Existing Open→Agent Closed APIs and both profiles retain their contracts.
|
|
159
184
|
See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
|
|
160
185
|
[runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
|
|
161
|
-
is not purchasing authority or payment success.
|
|
186
|
+
is not purchasing authority or payment success. See the [short verified buyer-flow sample](docs/RELEASE_070.md).
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
# Direct / Human Present Checkout — 0.7.0
|
|
1
|
+
# Direct / Human Present Checkout — 0.7.0 published
|
|
2
2
|
|
|
3
3
|
This additive optional module implements Trusted Agent Provider approval of a
|
|
4
|
-
fixed merchant-signed order.
|
|
4
|
+
fixed merchant-signed order. Published at 2026-11-01 03:12:46.522 UTC; [publication record](PROJECT_STATUS.md#070-publication). Adopted source is AP2 v0.2.0,
|
|
5
5
|
commit `b4587ac1d055888a73b4b21750973cffba961793`; no source upgrade is made.
|
|
6
6
|
The first example is one office supply purchase; **multiple products and lines
|
|
7
7
|
are required and supported throughout issuance, presentation, merchant verification
|
|
@@ -142,7 +142,7 @@ Existing two profiles, InputBuilder save/restore, Result/Evidence, old API defau
|
|
|
142
142
|
and legacy Receipt terminal syntax are unchanged. Direct is a new independent
|
|
143
143
|
entry; existing `verify_checkout` continues to handle its prior Open→Agent Closed
|
|
144
144
|
contract only. Passing Direct wire to old Receipt/default profile rejects.
|
|
145
|
-
No dependency or Ruby support change. Compatible feature version is 0.7.0.
|
|
145
|
+
No dependency or Ruby support change. Compatible feature version is published 0.7.0.
|
|
146
146
|
|
|
147
147
|
`test/buyer_interop.py` uses the fixed official `sd_jwt.create/verify`, unmodified
|
|
148
148
|
Closed Schema, JWT helpers and independent SHA256/commitment computation.
|
|
@@ -176,5 +176,5 @@ Credentials, multiple merchants, split orders and continuous autonomous buying
|
|
|
176
176
|
are follow-up candidates. Agent-to-Agent delegation is outside current AP2 scope,
|
|
177
177
|
not declared permanently forbidden. Real Issuer trust, actual demand, generic AP2
|
|
178
178
|
support and production safety are not established by synthetic test success.
|
|
179
|
-
|
|
180
|
-
|
|
179
|
+
Gem publication and its separately approved tag/Release are recorded in the
|
|
180
|
+
publication record. No deployment, real payments or real credentials are exercised.
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# Conditional Checkout delegation — 0.8.0 candidate
|
|
2
|
+
|
|
3
|
+
Adopted AP2 v0.2.0 source remains `b4587ac1d055888a73b4b21750973cffba961793`.
|
|
4
|
+
This is an additive Ruby issuance API for the existing explicit
|
|
5
|
+
`ap2.checkout.single_merchant_multi_item` v1 profile. It does not relax old
|
|
6
|
+
profiles, add a general Schema engine, or establish real Issuer trust.
|
|
7
|
+
|
|
8
|
+
## Security proposition and responsibilities
|
|
9
|
+
|
|
10
|
+
An authenticated approval service issues an Open for one registered Agent key,
|
|
11
|
+
one merchant and 1–8 requirements, each with 1–8 candidate products and an exact
|
|
12
|
+
integer quantity. The Agent can close it only against an authentic merchant
|
|
13
|
+
Checkout that completely satisfies those requirements. All signed original
|
|
14
|
+
bytes are retained. The existing full verifier independently checks the result
|
|
15
|
+
against registered trust, the current order and Host challenge.
|
|
16
|
+
|
|
17
|
+
The application authenticates the person, obtains informed consent and purchasing
|
|
18
|
+
authority, protects the approved conditions and controls the Provider signer.
|
|
19
|
+
No boolean approval establishes consent. Provider key material is never passed
|
|
20
|
+
to the Agent. Agent and Merchant keys are independently registered, not trusted
|
|
21
|
+
because they appear in received tokens. Host owns challenge issuance, trusted
|
|
22
|
+
clock, current order, revocation, durable atomic consumption and execution.
|
|
23
|
+
SDK verification is evidence, never Host ALLOW or payment completion.
|
|
24
|
+
|
|
25
|
+
## Public API design
|
|
26
|
+
|
|
27
|
+
`ConditionalCheckout.issue_open(merchant:, requirements:, agent_public_key_pem:,
|
|
28
|
+
issued_at:, expires_at:, signer:, public_key_pem:)` returns immutable
|
|
29
|
+
`Open#root_presentation`. Merchant is `{id, name}`; requirements contain
|
|
30
|
+
`{id, quantity, acceptable_items: [{id, title}]}` with string keys. Input is a
|
|
31
|
+
protected application approval record, not untrusted Agent parameters.
|
|
32
|
+
|
|
33
|
+
`ConditionalCheckout.issue_closed(root_presentation:, checkout_jwt:,
|
|
34
|
+
trusted_issuer_public_key_pem:, agent_public_key_pem:,
|
|
35
|
+
trusted_merchant_public_key_pem:, expected_merchant_id:, audience:, nonce:,
|
|
36
|
+
verified_at:, signer:)` returns immutable `Closed` with original
|
|
37
|
+
`root_presentation`, `terminal_jws`, `closed_sd_jwt` and `checkout_jwt`.
|
|
38
|
+
It verifies Open signature, complete disclosure graph, schema subset, Agent
|
|
39
|
+
cnf, validity, Merchant signature and all quantity constraints before signing.
|
|
40
|
+
The signer receives frozen ASCII ES256 signing input and returns 64 JOSE bytes;
|
|
41
|
+
the supplied public key verifies the exact returned signature before success.
|
|
42
|
+
Signer network access, timeout and access control belong to the application.
|
|
43
|
+
|
|
44
|
+
`ConditionalCheckout.present(root_presentation:, terminal_jws:, checkout_jwt:)`
|
|
45
|
+
restores detached immutable original strings for transport/storage. It checks
|
|
46
|
+
bounded supported syntax and original-byte bindings, not authentication;
|
|
47
|
+
Merchant must use `InputBuilder.verify` / `verify_checkout` with independent
|
|
48
|
+
trust and Host inputs. The issuance object can be persisted as these three
|
|
49
|
+
strings; no claims or disclosures are reserialized during presentation.
|
|
50
|
+
Issuance/restoration failures raise a fixed redacted `ConditionalCheckout::Invalid`
|
|
51
|
+
without a cause. No partial claims, keys, nonce or raw tokens appear in errors.
|
|
52
|
+
|
|
53
|
+
## Wire contract, limits and completeness
|
|
54
|
+
|
|
55
|
+
Open uses ES256 root `example+sd-jwt`, one SD array commitment to Open content,
|
|
56
|
+
one to the merchant, and one per candidate. All candidates and constraints are
|
|
57
|
+
always disclosed; subset selection is not supported. Salts are random 128-bit
|
|
58
|
+
values. No omitted, extra, duplicate, unknown or decoy commitments are accepted.
|
|
59
|
+
The profile's original-byte, depth, graph, 8-line/requirement/candidate and amount
|
|
60
|
+
limits apply jointly. Quantity matching uses exact integral max flow by product
|
|
61
|
+
ID, including same-product separate rows. Unknown constraints fail closed.
|
|
62
|
+
|
|
63
|
+
Open carries `cnf.jwk`, `iat`, `exp`, two ordered constraints and
|
|
64
|
+
`vct: mandate.checkout.open.1`. Lifetime is positive and at most 7200 seconds;
|
|
65
|
+
all checks use explicit integer epochs and `iat <= now < exp`. Agent Closed
|
|
66
|
+
inherits Open `iat/exp` exactly, as required by this existing profile. Terminal
|
|
67
|
+
KB-SD-JWT has `typ: kb+sd-jwt`, `aud`, `nonce`, fresh `iat`, `sd_hash` of the
|
|
68
|
+
entire original Open SD-JWT including disclosures and trailing `~`, and one
|
|
69
|
+
inline Closed containing the exact merchant JWT and its SHA256 base64url hash.
|
|
70
|
+
There are no selective disclosures in this final Closed; its SD-JWT is exactly
|
|
71
|
+
`terminal_jws + "~"`. Audience and nonce come from the Host challenge and must
|
|
72
|
+
also be independently checked by the Merchant. Proof age is at most 300 seconds.
|
|
73
|
+
Agent signing uses the existing terminal limits (24,576 decoded claim bytes and
|
|
74
|
+
32,768 compact bytes), accommodating the embedded original Merchant JWT.
|
|
75
|
+
Merchant/Direct signing retain 12,000 decoded claim bytes and 16,384 wire bytes;
|
|
76
|
+
Checkout text/count limits and all joint effective bounds still apply.
|
|
77
|
+
|
|
78
|
+
Receipt `reference` is base64url without padding of SHA256 of **only the final
|
|
79
|
+
Closed SD-JWT**, including its trailing `~`. It excludes the preceding Open
|
|
80
|
+
chain, includes any disclosure bytes in profiles that have them, and never hashes
|
|
81
|
+
compact JWT alone or reconstructed JSON. This profile has zero final disclosures;
|
|
82
|
+
reordering Open disclosures changes the Agent's root binding but not that rule.
|
|
83
|
+
Existing `CheckoutReceipt.sign/verify` use the explicit multi-item profile.
|
|
84
|
+
|
|
85
|
+
## Application outcomes and compatibility
|
|
86
|
+
|
|
87
|
+
After evidence verification, the application reserves/consumes the approval,
|
|
88
|
+
challenge and order transactionally and signs its explicit Success/Error outcome.
|
|
89
|
+
Authentic Success confirms the merchant's recorded result; authentic Error is
|
|
90
|
+
not automatic permission to replay. Retry requires current order/approval/nonce
|
|
91
|
+
policy. Missing Receipt, transport errors or uncertain commits remain pending;
|
|
92
|
+
reconcile saved operation IDs rather than repeat a purchase blindly.
|
|
93
|
+
|
|
94
|
+
Direct, old single-product defaults, InputBuilder saved formats, diagnostics,
|
|
95
|
+
Result/Evidence and Receipt contracts remain unchanged. No migration is required.
|
|
96
|
+
This new API explicitly selects the existing multi-item profile; no token can
|
|
97
|
+
select policy. Payment Mandates, budgets, repeated/split/multi-merchant purchases,
|
|
98
|
+
User Credentials, Rails and tax/shipping/discount calculation are out of scope.
|
|
99
|
+
|
|
100
|
+
## Acceptance and independent evidence
|
|
101
|
+
|
|
102
|
+
Required checks: public-only installed example from conditions through both
|
|
103
|
+
Receipt outcomes; 1/8 rows, candidates, varying quantities, repeated product rows;
|
|
104
|
+
shortage/excess, wrong merchant/Agent/Open/Checkout, authentic invalid orders;
|
|
105
|
+
signature/hash/disclosure tampering, unknown/missing/duplicate fields, bounds,
|
|
106
|
+
expiry/future/proof-age boundaries, audience/nonce mismatch, exact receipt hash
|
|
107
|
+
scope and wrong key/issuer/time/reference; existing complete regression.
|
|
108
|
+
Official Python SDK primitives and unmodified pinned Schemas must independently
|
|
109
|
+
verify Ruby output and produce Ruby-accepted signed input. Normative specification,
|
|
110
|
+
SDK behavior and stricter local rules are recorded separately; SDK shortage and
|
|
111
|
+
empty-candidate differences remain in MULTI_ITEM_INTEROP.md. Latest-HEAD Codex
|
|
112
|
+
review and the same candidate Gem installed on both supported Rubies are required.
|
|
113
|
+
|
|
114
|
+
Status: implemented and locally tested; release gates and final package/review
|
|
115
|
+
evidence are tracked in RELEASE_080_CANDIDATE.md and the external manifest.
|
|
116
|
+
No RubyGems push, public tag/Release,
|
|
117
|
+
production connection or actual payment is authorized by this task.
|
|
118
|
+
|
|
119
|
+
## Official-source comparison and independent results
|
|
120
|
+
|
|
121
|
+
On 2026-11-01 official main is `e1ea56db72a6385bce3e5c1112b3a56ce60acb43`.
|
|
122
|
+
GitHub compare from the adopted commit changes only CHANGELOG, CONTRIBUTING,
|
|
123
|
+
README and uv.lock; normative docs, Schemas and SDK code are unchanged. Current
|
|
124
|
+
[Checkout](https://ap2-protocol.org/ap2/checkout_mandate/) and
|
|
125
|
+
[Agent Authorization](https://ap2-protocol.org/ap2/agent_authorization/) pages
|
|
126
|
+
were also read. Adoption stays pinned, with no dependency/source upgrade.
|
|
127
|
+
|
|
128
|
+
`test/conditional_interop.py` uses the pinned official `sd_jwt.create/verify`,
|
|
129
|
+
`kb_sd_jwt.verify`, JWT sign/verify helpers, unmodified Open/Closed/Checkout/Receipt
|
|
130
|
+
Schemas, independent commitment traversal and SHA256. Ruby Open/Closed is
|
|
131
|
+
verified by Python. Official Python Open issuance plus official JWT helper inline
|
|
132
|
+
Closed signing is accepted by Ruby; both Receipt outcomes work in both directions.
|
|
133
|
+
Keys remain in memory and no runtime network or remote Schema fallback is used.
|
|
134
|
+
|
|
135
|
+
The official high-level `kb_sd_jwt.create` always discloses `delegate_payload`
|
|
136
|
+
through a commitment and emits `_sd_alg`, even with empty metadata. Its output is
|
|
137
|
+
tested unchanged as an unsupported-form rejection. We do not strip signed claims
|
|
138
|
+
or weaken the existing inline-terminal profile to accept it. The supported inline
|
|
139
|
+
form uses official JWT signing and the same normative claim/hash rules, validated
|
|
140
|
+
independently. Choosing a new selective-disclosure terminal profile is future work.
|
|
141
|
+
This is bounded interoperability, not all SDK helpers or general AP2 compatibility.
|
|
142
|
+
|
|
143
|
+
The initial Codex P2 on restoration completeness was fixed by sharing the exact
|
|
144
|
+
Root closure walker for structural restoration. Restoration still authenticates
|
|
145
|
+
neither Root nor Agent signatures; full merchant verification remains mandatory.
|
|
146
|
+
Negative tests sign terminals bound to malformed/missing/duplicate Root disclosures
|
|
147
|
+
and require restoration rejection. Package/source results and final review status
|
|
148
|
+
are in [release preparation](RELEASE_080_CANDIDATE.md).
|
|
149
|
+
|
|
150
|
+
## Handling non-success without replay
|
|
151
|
+
|
|
152
|
+
```ruby
|
|
153
|
+
case result.status # from InputBuilder.verify / verify_checkout
|
|
154
|
+
when :verified_research
|
|
155
|
+
# Recheck current application authorization/order/trust; atomically reserve.
|
|
156
|
+
when :rejected
|
|
157
|
+
# Decline this presentation; do not execute or issue a Success Receipt.
|
|
158
|
+
when :unavailable
|
|
159
|
+
# Verification could not establish evidence; hold, diagnose and retry only
|
|
160
|
+
# verification under application policy, without executing the order.
|
|
161
|
+
end
|
|
162
|
+
# Missing/unverified Receipt after submission: retain operation_id => :pending,
|
|
163
|
+
# reconcile the merchant's saved result; do not resubmit a purchase blindly.
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Issuance `Invalid` similarly never means that an order was executed; a remote
|
|
167
|
+
signer error may have an uncertain signing outcome, so reconcile the application's
|
|
168
|
+
issuance record before reissuing. SDK operations here perform no payment side effect.
|
data/docs/MERCHANT_SIGNING.md
CHANGED
|
@@ -62,7 +62,7 @@ puts signed.checkout_hash.length # 43
|
|
|
62
62
|
`signed.jwt` is the frozen original compact JWT to transmit and retain. Supply
|
|
63
63
|
that exact String as `host_checkout_jws` to InputBuilder and Verifier; supply
|
|
64
64
|
`signed.checkout_hash` when a test or external Agent binds a Closed Mandate.
|
|
65
|
-
These 0.5/0.6 APIs do not issue a product Mandate. The
|
|
65
|
+
These 0.5/0.6 APIs do not issue a product Mandate. The published 0.7.0
|
|
66
66
|
[Direct buyer module](BUYER_DIRECT_CHECKOUT.md) adds a separate issuance flow.
|
|
67
67
|
Re-encoding claims or signing again
|
|
68
68
|
creates different original wire, even when the order is the same.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# 0.8.0 candidate — conditional Checkout delegation, unpublished
|
|
2
|
+
|
|
3
|
+
Compatible feature release preparation for approved conditional purchasing:
|
|
4
|
+
`ConditionalCheckout.issue_open` → Agent `.issue_closed` → `.present` → existing
|
|
5
|
+
full `InputBuilder.verify` → `CheckoutReceipt.sign/verify`. The installed
|
|
6
|
+
[standalone example](../examples/conditional_checkout.rb) uses A/B×1 and C×2,
|
|
7
|
+
three rows and repeated C products. [API/specification](CONDITIONAL_CHECKOUT.md).
|
|
8
|
+
|
|
9
|
+
Published stable remains 0.7.0, verified from the official RubyGems versions API
|
|
10
|
+
on 2026-11-01; 0.8.0 is absent, so no version-plan collision is currently observed.
|
|
11
|
+
0.7.0 source/tag is `9b4b78a7ed9aa95e7d35e01a64efc1281ba95be3`; its published
|
|
12
|
+
64,000-byte SHA256 is `baab8c68355b5e6c9351e7d86a836fab50652cdad662bbc99d1676c5e6134447`.
|
|
13
|
+
Current base main is `50f9639a4fe316556189088ab6b737a642f5f6e2`, initially no open PRs.
|
|
14
|
+
No verified prior artifact or previous task checkout was modified.
|
|
15
|
+
|
|
16
|
+
## Validation and compatibility
|
|
17
|
+
|
|
18
|
+
All 17 source-suite entry points pass offline on MRI 3.4.12 and 4.0.9. Existing
|
|
19
|
+
regression includes Direct, both old profiles, signed missing/unknown/duplicate
|
|
20
|
+
disclosures, original-wire binding, InputBuilder save/restore, Result/Evidence,
|
|
21
|
+
diagnostics and Receipt outcomes. New tests add 8 cases (123 assertions on MRI
|
|
22
|
+
3.4.12 / 126 on MRI 4.0.9, including installed-Gem execution) for
|
|
23
|
+
issuance, sign-before-check prevention, bounds, 8×8 candidate/requirement cases,
|
|
24
|
+
same-product separate rows, wrong keys/time/audience/nonce, restoration closure,
|
|
25
|
+
and exact final Closed Receipt reference. A long-ID/title eight-row Checkout
|
|
26
|
+
also completes through the larger existing Agent-terminal bounds while Merchant
|
|
27
|
+
JWT and Direct signing bounds remain unchanged. Suite counts include shared legacy
|
|
28
|
+
dependencies; no misleading aggregate of repeated assertion counters is claimed.
|
|
29
|
+
|
|
30
|
+
Official pinned Python comparison passes for signatures in both directions,
|
|
31
|
+
Open/Closed/Checkout/Receipt Schemas, complete Open commitments and normative
|
|
32
|
+
sd_hash including final `~`, both receipt outcomes and negative controls. SDK
|
|
33
|
+
high-level Closed helper emits an unsupported SD form; it is a rejection control,
|
|
34
|
+
not claimed accepted interoperability. Existing max-flow shortage/empty-candidate
|
|
35
|
+
differences and compact-only Receipt helper remain documented and fail closed.
|
|
36
|
+
|
|
37
|
+
Candidate Gem identity, corresponding final source SHA, payload hashes, byte size,
|
|
38
|
+
ordinary installation on both Rubies and exact example output are recorded in the
|
|
39
|
+
external candidate manifest beside the Gem. The Gem includes both READMEs, this
|
|
40
|
+
decision document, the API contract and the standalone example. Dependencies and
|
|
41
|
+
supported MRI versions are unchanged; old callers require no migration.
|
|
42
|
+
|
|
43
|
+
## Review and external-operation status
|
|
44
|
+
|
|
45
|
+
Initial independent Codex review found one substantive P2 (restoration Root
|
|
46
|
+
closure); fixed through shared structural parsing and signed negative regression.
|
|
47
|
+
GitHub review additionally found that the Merchant signing helper's 12,000-byte
|
|
48
|
+
claims / 16,384-byte JWS limits prevented valid larger Agent terminals. KB terminal
|
|
49
|
+
signing now uses its existing verifier's 24,576-byte payload / 32,768-byte wire
|
|
50
|
+
bounds only; JWT and Direct retain the old limits. Long-ID/title eight-row Ruby
|
|
51
|
+
and official Python signature/Schema/hash regressions exercise this fix.
|
|
52
|
+
Latest-HEAD independent review must be completed and identified in the external
|
|
53
|
+
verification report. Review no-findings alone is not a security proof.
|
|
54
|
+
|
|
55
|
+
Initial Draft PR branch push was denied by automatic approval review before
|
|
56
|
+
execution. Owner subsequently explicitly authorized the specified commit/branch
|
|
57
|
+
push, Draft PR, existing-budget CI, latest-HEAD Codex review/fixes and conditional
|
|
58
|
+
Squash Merge at 2026-11-01 14:41 JST. The branch was pushed and
|
|
59
|
+
[Draft PR #231](https://github.com/cuichangquan/ap2-mandate-verifier/pull/231)
|
|
60
|
+
created. No alternate route bypassed the denial; authorization resolved it first.
|
|
61
|
+
No owner approval review is submitted. Current exact-HEAD review, CI and merge
|
|
62
|
+
results are recorded in that PR and the external final verification report.
|
|
63
|
+
Only existing `merchant-source-package.yml` is expected to trigger for this diff:
|
|
64
|
+
two MRI jobs in one workflow run, existing Ubuntu runner/15-minute job timeout,
|
|
65
|
+
public dependencies, no secrets, extra cost zero. No workflow edits. Issue #101's
|
|
66
|
+
maximum 3 runs/PR is a ceiling, no blind reruns; the PR records every consumed run.
|
|
67
|
+
|
|
68
|
+
## Build and final candidate evidence
|
|
69
|
+
|
|
70
|
+
Use the final committed tree, existing pinned Docker images and no network:
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
gem build ap2_mandate_verifier.gemspec --output /out/ap2_mandate_verifier-0.8.0.gem
|
|
74
|
+
sh scripts/check_candidate_package.sh /out/package /out/ap2_mandate_verifier-0.8.0.gem
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Run source regression with `sh scripts/check_ruby_compatibility.sh /out/source`.
|
|
78
|
+
The packaging script installs the **same** built Gem with normal RubyGems
|
|
79
|
+
resolution (`gem install --local`), audits every source/archive/installed payload,
|
|
80
|
+
then executes detached old APIs and the example physically inside the installed
|
|
81
|
+
Gem. Reuse one artifact across both MRI runtimes. Do not substitute an earlier
|
|
82
|
+
working-tree package or rebuild a lookalike after approval. Exact source SHA and
|
|
83
|
+
Gem SHA cannot be embedded recursively in their own bytes; use external manifest.
|
|
84
|
+
|
|
85
|
+
## Publication decision and recovery plan
|
|
86
|
+
|
|
87
|
+
1. Review final source SHA, strict latest-HEAD review, all tests/independent
|
|
88
|
+
comparison, exact candidate manifest and remaining GitHub PR/CI gates.
|
|
89
|
+
2. Obtain separate Owner authorization for that exact Gem publication; **no push,
|
|
90
|
+
public tag or GitHub Release is authorized by this request**.
|
|
91
|
+
3. After explicit authorization only, RubyGems push the approved exact artifact,
|
|
92
|
+
fetch the official distribution and compare bytes/SHA/size and every payload.
|
|
93
|
+
4. Only under publication/tag/Release authorization, bind `v0.8.0` to its verified
|
|
94
|
+
source, publish release notes and update stable install guides/demo after the
|
|
95
|
+
registry version is actually available. A candidate README is not publication.
|
|
96
|
+
5. On mismatch, invalid dependency/content, signature or material regression,
|
|
97
|
+
stop rollout and retain evidence. Do not overwrite a published version; assess
|
|
98
|
+
scoped yank/patch publication with separate Owner decision. Keep 0.7.0 install
|
|
99
|
+
guidance until the successor is independently verified. Preserve original
|
|
100
|
+
saved mandates/challenges; do not reinterpret them under a changed profile.
|
|
101
|
+
|
|
102
|
+
Limits: one merchant/Checkout, all candidates disclosed, ES256/P-256, exact finite
|
|
103
|
+
profile, no real Issuer trust/production Host proof. Authentication/consent,
|
|
104
|
+
revocation/key lifecycle, persistence/CAS/nonce consumption, execution and payment
|
|
105
|
+
remain app responsibilities. Payment Mandates, budgets, repeating/split orders,
|
|
106
|
+
User Credentials and tax/shipping/discount engines remain out of scope.
|
|
107
|
+
Production/real wallet/payment/deployment, RubyGems push and public tag/Release
|
|
108
|
+
are NOT_RUN. Release readiness requires the final exact-HEAD PR/review/CI and
|
|
109
|
+
package gates; the external report records their actual completion state.
|
data/docs/SUPPORT_CONTRACT.md
CHANGED
|
@@ -1,4 +1,25 @@
|
|
|
1
|
-
# Fixed-profile AP2 verification — published 0.
|
|
1
|
+
# Fixed-profile AP2 verification — published 0.7.0 / history
|
|
2
|
+
|
|
3
|
+
## Unpublished 0.8.0 additive candidate
|
|
4
|
+
|
|
5
|
+
`ConditionalCheckout.issue_open/issue_closed/present` add conditional delegation
|
|
6
|
+
issuance and original-wire presentation under the unchanged explicit multi-item
|
|
7
|
+
profile v1. [Contract, errors, limits and application responsibilities](CONDITIONAL_CHECKOUT.md).
|
|
8
|
+
The packaged standalone example uses only public installed APIs. No old default,
|
|
9
|
+
profile definition/hash, Result/Evidence/diagnostic, saved record or Receipt
|
|
10
|
+
acceptance condition is changed. All candidates remain required; no new selective
|
|
11
|
+
disclosure profile is introduced. Published stable remains 0.7.0.
|
|
12
|
+
|
|
13
|
+
Published 0.7.0 adds the separate [Direct buyer module](BUYER_DIRECT_CHECKOUT.md):
|
|
14
|
+
merchant Checkout verification before human approval, Provider-signed issuance,
|
|
15
|
+
Agent presentation, Direct merchant verification and whole-wire Receipt confirmation.
|
|
16
|
+
It supports one merchant, 1–8 lines and multiple products; existing Open→Closed
|
|
17
|
+
Result/Evidence/profile/save contracts are unchanged. Publication was verified at
|
|
18
|
+
2026-11-01 03:14:04 UTC: 64,000 bytes, SHA256
|
|
19
|
+
`baab8c68355b5e6c9351e7d86a836fab50652cdad662bbc99d1676c5e6134447`, all 24 payloads
|
|
20
|
+
match source `9b4b78a7ed9aa95e7d35e01a64efc1281ba95be3`.
|
|
21
|
+
[Publication record](PROJECT_STATUS.md#070-publication). Older version statements below
|
|
22
|
+
retain their historical scope; they do not exclude the new Direct APIs.
|
|
2
23
|
|
|
3
24
|
## Current source: explicit multi-item profile
|
|
4
25
|
|
|
@@ -394,7 +415,7 @@ failed or mismatched report is not success. No local path is a public evidence
|
|
|
394
415
|
URL. Raw local environment logs are not published by this package.
|
|
395
416
|
|
|
396
417
|
|
|
397
|
-
## Direct buyer module —
|
|
418
|
+
## Direct buyer module — published 0.7.0
|
|
398
419
|
|
|
399
420
|
Additive `CheckoutJWT.verify` and `Buyer.issue_closed/present_closed/verify`
|
|
400
421
|
implement Trusted Agent Provider / Human Present exact-order approval. Direct
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# Ordinary installed Gem only. No test fixtures, source-path loading or network.
|
|
3
|
+
require "ap2_mandate_verifier"
|
|
4
|
+
require "openssl"
|
|
5
|
+
|
|
6
|
+
module ConditionalCheckoutExample
|
|
7
|
+
M = AP2MandateVerifier
|
|
8
|
+
PROFILE = M::ConditionalCheckout::PROFILE_REF
|
|
9
|
+
NOW = 1_800_000_000
|
|
10
|
+
def self.totals(n) = %w[subtotal total].map { |type| {"type" => type, "amount" => n} }
|
|
11
|
+
def self.run
|
|
12
|
+
provider, agent, merchant = Array.new(3) { OpenSSL::PKey::EC.generate("prime256v1") }
|
|
13
|
+
seller = {"id" => "shop", "name" => "Office supplies"}
|
|
14
|
+
# This protected record is created AFTER application authentication, display
|
|
15
|
+
# of these conditions and authority/consent checks. No approved flag is proof.
|
|
16
|
+
requirements = [{"id" => "choice", "quantity" => 1,
|
|
17
|
+
"acceptable_items" => %w[A B].map { |id| {"id" => id, "title" => "Product #{id}"} }},
|
|
18
|
+
{"id" => "required", "quantity" => 2, "acceptable_items" => [{"id" => "C", "title" => "Product C"}]}]
|
|
19
|
+
opening = M::ConditionalCheckout.issue_open(merchant: seller, requirements: requirements,
|
|
20
|
+
agent_public_key_pem: agent.public_to_pem, issued_at: NOW, expires_at: NOW + 600,
|
|
21
|
+
signer: M::CheckoutJWT.es256_signer(private_key: provider), public_key_pem: provider.public_to_pem)
|
|
22
|
+
# Merchant Checkout has three rows, including C in two distinct rows.
|
|
23
|
+
lines = %w[B C C].each_with_index.map do |id, i|
|
|
24
|
+
{"id" => "row-#{i}", "item" => {"id" => id, "title" => "Product #{id}", "price" => 100},
|
|
25
|
+
"quantity" => 1, "totals" => totals(100)}
|
|
26
|
+
end
|
|
27
|
+
order = {"id" => "office-1", "merchant" => seller, "status" => "ready_for_complete",
|
|
28
|
+
"currency" => "USD", "line_items" => lines, "totals" => totals(300), "links" => []}
|
|
29
|
+
checkout = M::CheckoutJWT.sign(checkout: order, profile_ref: PROFILE,
|
|
30
|
+
signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
|
|
31
|
+
|
|
32
|
+
# Host enrollment and challenge are synthetic authenticated application data.
|
|
33
|
+
roles = %w[Issuer Agent Merchant]
|
|
34
|
+
records = roles.zip([provider, agent, merchant]).map do |role, key|
|
|
35
|
+
{"role" => role, "identity" => role == "Merchant" ? "shop" : role.downcase,
|
|
36
|
+
"tenant_id" => "tenant", "purpose" => "checkout", "key_ref" => role.downcase,
|
|
37
|
+
"public_key_pem" => key.public_to_pem, "active" => true, "not_before" => NOW - 1, "not_after" => NOW + 1000}
|
|
38
|
+
end
|
|
39
|
+
selectors = records.to_h { |record| [record["role"].downcase.to_sym, record.slice("identity", "purpose", "key_ref")] }
|
|
40
|
+
trust = M::InputBuilder.trust(snapshot: {"id" => "registry", "policy_version" => "1", "active" => true,
|
|
41
|
+
"not_before" => NOW - 1, "not_after" => NOW + 1000, "records" => records},
|
|
42
|
+
tenant_id: "tenant", verified_at: NOW, profile_ref: PROFILE, **selectors)
|
|
43
|
+
host_order = {"tenant_id" => "tenant", "buyer_account_id" => "buyer", "order_id" => "office-1",
|
|
44
|
+
"merchant_id" => "shop", "audience" => "merchant-host", "order_version" => "1", "currency" => "USD", "expected_total" => 300}
|
|
45
|
+
host_inputs = {trust: trust, order: host_order, root_presentation: opening.root_presentation, host_checkout_jws: checkout.jwt}
|
|
46
|
+
saved = M::InputBuilder.prepare(**host_inputs, challenge_id: "challenge-1", nonce: "synthetic-one-use-nonce",
|
|
47
|
+
issuer_id: "host", not_before: NOW, not_after: NOW + 60)
|
|
48
|
+
# Agent receives public trust, Open, Checkout, challenge and its own signer.
|
|
49
|
+
# Provider signer/private key is not an input to this operation.
|
|
50
|
+
closed = M::ConditionalCheckout.issue_closed(root_presentation: opening.root_presentation, checkout_jwt: checkout.jwt,
|
|
51
|
+
trusted_issuer_public_key_pem: provider.public_to_pem, agent_public_key_pem: agent.public_to_pem,
|
|
52
|
+
trusted_merchant_public_key_pem: merchant.public_to_pem, expected_merchant_id: "shop",
|
|
53
|
+
audience: "merchant-host", nonce: "synthetic-one-use-nonce", verified_at: NOW,
|
|
54
|
+
signer: M::CheckoutJWT.es256_signer(private_key: agent))
|
|
55
|
+
wire = M::ConditionalCheckout.present(root_presentation: closed.root_presentation,
|
|
56
|
+
terminal_jws: closed.terminal_jws, checkout_jwt: closed.checkout_jwt)
|
|
57
|
+
checked = M::InputBuilder.verify(**host_inputs, terminal_jws: wire.terminal_jws,
|
|
58
|
+
saved_challenge: M::InputBuilder.restore(saved_challenge: saved), expected_challenge_issuer_id: "host",
|
|
59
|
+
clock_source_id: "synthetic-clock", verified_at: NOW)
|
|
60
|
+
raise "verification failed" unless checked.success?
|
|
61
|
+
puts "Open -> Agent Closed -> merchant evidence: verified=true; rows=3; requirements=2"
|
|
62
|
+
# These are ALTERNATIVE synthetic application outcomes, never two executions.
|
|
63
|
+
%w[Success Error].each do |outcome|
|
|
64
|
+
fields = outcome == "Success" ? {order_id: "office-1"} : {error: "policy_rejected", error_description: "Application declined"}
|
|
65
|
+
receipt = M::CheckoutReceipt.sign(closed_sd_jwt: wire.closed_sd_jwt, profile_ref: PROFILE,
|
|
66
|
+
issuer: "shop", outcome: outcome, issued_at: NOW, **fields,
|
|
67
|
+
signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
|
|
68
|
+
result = M::CheckoutReceipt.verify(jwt: receipt.jwt, closed_sd_jwt: wire.closed_sd_jwt,
|
|
69
|
+
profile_ref: PROFILE, trusted_public_key_pem: merchant.public_to_pem, expected_issuer: "shop",
|
|
70
|
+
not_before: NOW, not_after: NOW + 60, verified_at: NOW)
|
|
71
|
+
raise "receipt failed" unless result.verified? && result.outcome == outcome
|
|
72
|
+
puts "Receipt #{outcome}: authentic=true; purchase_succeeded=#{result.purchase_succeeded?}"
|
|
73
|
+
end
|
|
74
|
+
# Application state, not an SDK purchase permit: durable transaction/CAS in
|
|
75
|
+
# real code must consume approval/challenge/order once and save its receipt.
|
|
76
|
+
states = {"success" => :consumed, "error" => :requires_new_policy_decision, "missing_receipt" => :pending}
|
|
77
|
+
raise "unknown replay" unless states["missing_receipt"] == :pending
|
|
78
|
+
puts "Success=consumed; Error=policy decision; missing Receipt/uncertain commit=pending"
|
|
79
|
+
puts "Synthetic only; evidence and Receipt authenticity are not payment completion."
|
|
80
|
+
{opening: opening, closed: closed, result: checked, host_inputs: host_inputs, saved: saved,
|
|
81
|
+
keys: [provider, agent, merchant], requirements: requirements, checkout: order}
|
|
82
|
+
end
|
|
83
|
+
end
|
|
84
|
+
ConditionalCheckoutExample.run if $PROGRAM_NAME == __FILE__
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module AP2MandateVerifier
|
|
4
|
+
# Additive issuer/Agent APIs for the unchanged complete-disclosure profile.
|
|
5
|
+
module ConditionalCheckout
|
|
6
|
+
PROFILE_REF = ScopedConstraints::MULTI_PROFILE_REF
|
|
7
|
+
class Invalid < ArgumentError
|
|
8
|
+
def initialize = super("invalid conditional checkout information")
|
|
9
|
+
end
|
|
10
|
+
class Open
|
|
11
|
+
attr_reader :root_presentation
|
|
12
|
+
def initialize(wire)
|
|
13
|
+
@root_presentation = wire.freeze
|
|
14
|
+
freeze
|
|
15
|
+
end
|
|
16
|
+
private_class_method :new
|
|
17
|
+
end
|
|
18
|
+
class Closed
|
|
19
|
+
attr_reader :root_presentation, :terminal_jws, :checkout_jwt, :closed_sd_jwt
|
|
20
|
+
def initialize(root, terminal, checkout)
|
|
21
|
+
@root_presentation, @terminal_jws, @checkout_jwt = root.freeze, terminal.freeze, checkout.freeze
|
|
22
|
+
@closed_sd_jwt = (terminal + "~").freeze
|
|
23
|
+
freeze
|
|
24
|
+
end
|
|
25
|
+
private_class_method :new
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
def self.issue_open(merchant:, requirements:, agent_public_key_pem:, issued_at:, expires_at:, signer:, public_key_pem:)
|
|
29
|
+
RootSignature.send(:dependencies!)
|
|
30
|
+
merchant = InputBuilder.send(:copy!, merchant)
|
|
31
|
+
requirements = InputBuilder.send(:copy!, requirements)
|
|
32
|
+
constraints = [{"type" => "checkout.line_items", "items" => requirements},
|
|
33
|
+
{"type" => "checkout.allowed_merchants", "allowed" => [merchant]}]
|
|
34
|
+
ScopedConstraints.send(:multi_open!, constraints)
|
|
35
|
+
PurchaseBinding.send(:times!, {"iat" => issued_at, "exp" => expires_at}, issued_at)
|
|
36
|
+
agent = InputValidator.snapshot!(agent_public_key_pem, max_bytes: 1_024)
|
|
37
|
+
provider = InputValidator.snapshot!(public_key_pem, max_bytes: 1_024)
|
|
38
|
+
jwk = RootSignature.public_jwk!(agent)
|
|
39
|
+
disclosures = []
|
|
40
|
+
requirements.each do |requirement|
|
|
41
|
+
requirement["acceptable_items"] = requirement["acceptable_items"].map do |candidate|
|
|
42
|
+
disclose!(candidate, disclosures)
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
constraints[1]["allowed"] = [disclose!(merchant, disclosures)]
|
|
46
|
+
opening = {"vct" => "mandate.checkout.open.1", "iat" => issued_at, "exp" => expires_at,
|
|
47
|
+
"cnf" => {"jwk" => jwk}, "constraints" => constraints}
|
|
48
|
+
content = []
|
|
49
|
+
marker = disclose!(opening, content)
|
|
50
|
+
jwt = MerchantSignature.sign!({"delegate_payload" => [marker], "_sd_alg" => "sha-256"}, signer, provider,
|
|
51
|
+
typ: "example+sd-jwt")
|
|
52
|
+
wire = ([jwt] + content + disclosures + [""]).join("~")
|
|
53
|
+
open!(wire, provider, agent, issued_at)
|
|
54
|
+
Open.send(:new, wire)
|
|
55
|
+
rescue StandardError, LoadError
|
|
56
|
+
raise Invalid.new, cause: nil
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# Provider private key is deliberately absent from this Agent API.
|
|
60
|
+
def self.issue_closed(root_presentation:, checkout_jwt:, trusted_issuer_public_key_pem:,
|
|
61
|
+
agent_public_key_pem:, trusted_merchant_public_key_pem:, expected_merchant_id:,
|
|
62
|
+
audience:, nonce:, verified_at:, signer:)
|
|
63
|
+
root = InputValidator.snapshot!(root_presentation)
|
|
64
|
+
checkout = InputValidator.snapshot!(checkout_jwt, max_bytes: 16_384)
|
|
65
|
+
provider = InputValidator.snapshot!(trusted_issuer_public_key_pem, max_bytes: 1_024)
|
|
66
|
+
agent = InputValidator.snapshot!(agent_public_key_pem, max_bytes: 1_024)
|
|
67
|
+
merchant = InputValidator.snapshot!(trusted_merchant_public_key_pem, max_bytes: 1_024)
|
|
68
|
+
identity = InputValidator.snapshot!(expected_merchant_id, max_bytes: 256)
|
|
69
|
+
aud = InputValidator.snapshot!(audience, max_bytes: 512)
|
|
70
|
+
challenge = InputValidator.snapshot!(nonce, max_bytes: 512)
|
|
71
|
+
raise Invalid if aud.empty? || challenge.empty?
|
|
72
|
+
CheckoutReceipt.send(:epoch!, verified_at)
|
|
73
|
+
opening = open!(root, provider, agent, verified_at)
|
|
74
|
+
checked = CheckoutJWT.verify(jwt: checkout, trusted_public_key_pem: merchant,
|
|
75
|
+
expected_merchant_id: identity, profile_ref: PROFILE_REF)
|
|
76
|
+
ScopedConstraints.send(:multi_constraints!, {open: opening, checkout: checked.checkout},
|
|
77
|
+
checked.checkout.fetch("currency"), ScopedConstraints.multi_checkout!(checked.checkout))
|
|
78
|
+
closed = {"vct" => "mandate.checkout.1", "iat" => opening.fetch("iat"), "exp" => opening.fetch("exp"),
|
|
79
|
+
"checkout_jwt" => checkout, "checkout_hash" => checked.checkout_hash}
|
|
80
|
+
terminal = MerchantSignature.sign!({"aud" => aud, "nonce" => challenge, "iat" => verified_at,
|
|
81
|
+
"sd_hash" => digest(root), "delegate_payload" => [closed]}, signer, agent, typ: "kb+sd-jwt")
|
|
82
|
+
# Final handoff repeats the complete existing signature/condition path.
|
|
83
|
+
ScopedConstraints.check!(root_presentation: root, terminal_jws: terminal, host_checkout_jws: checkout,
|
|
84
|
+
trusted_issuer_public_key_pem: provider, expected_agent_public_key_pem: agent,
|
|
85
|
+
trusted_merchant_public_key_pem: merchant, expected_aud: aud, expected_nonce: challenge,
|
|
86
|
+
verified_at: verified_at, expected_checkout_id: checked.checkout.fetch("id"), expected_merchant_id: identity,
|
|
87
|
+
expected_currency: checked.checkout.fetch("currency"),
|
|
88
|
+
expected_total_minor: ScopedConstraints.multi_checkout!(checked.checkout), profile_ref: PROFILE_REF)
|
|
89
|
+
Closed.send(:new, root, terminal, checkout)
|
|
90
|
+
rescue StandardError, LoadError
|
|
91
|
+
raise Invalid.new, cause: nil
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
# Storage/transport only, never an authentication or authorization result.
|
|
95
|
+
def self.present(root_presentation:, terminal_jws:, checkout_jwt:)
|
|
96
|
+
root = InputValidator.snapshot!(root_presentation)
|
|
97
|
+
terminal = InputValidator.snapshot!(terminal_jws, max_bytes: 32_768)
|
|
98
|
+
checkout = InputValidator.snapshot!(checkout_jwt, max_bytes: 16_384)
|
|
99
|
+
# Exact commitment closure without claiming signature authentication.
|
|
100
|
+
opening = RootDisclosures.send(:structural_root!, root).fetch("delegate_payload").first
|
|
101
|
+
PurchaseBinding.send(:exact!, opening, %w[cnf constraints exp iat vct])
|
|
102
|
+
raise Invalid unless opening["vct"] == "mandate.checkout.open.1"
|
|
103
|
+
PurchaseBinding.send(:times!, opening, opening["iat"])
|
|
104
|
+
PurchaseBinding.send(:exact!, opening["cnf"], %w[jwk])
|
|
105
|
+
PurchaseBinding.send(:exact!, opening["cnf"]["jwk"], %w[kty crv x y])
|
|
106
|
+
jwk = opening["cnf"]["jwk"]
|
|
107
|
+
raise Invalid unless jwk["kty"] == "EC" && jwk["crv"] == "P-256" &&
|
|
108
|
+
%w[x y].all? { |f| RootSignature.send(:decode!, jwk[f], 32).bytesize == 32 }
|
|
109
|
+
ScopedConstraints.send(:multi_open!, opening["constraints"])
|
|
110
|
+
CheckoutReceipt.reference(closed_sd_jwt: terminal + "~", profile_ref: PROFILE_REF)
|
|
111
|
+
claims = InputValidator.parse!(RootSignature.send(:decode!, terminal.split(".", -1)[1], 24_576))
|
|
112
|
+
raise Invalid unless claims["sd_hash"] == digest(root) &&
|
|
113
|
+
claims.fetch("delegate_payload").first.fetch("checkout_jwt") == checkout &&
|
|
114
|
+
%w[iat exp].all? { |f| claims.fetch("delegate_payload").first[f] == opening[f] }
|
|
115
|
+
Closed.send(:new, root, terminal, checkout)
|
|
116
|
+
rescue StandardError, LoadError
|
|
117
|
+
raise Invalid.new, cause: nil
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
def self.open!(wire, provider, agent, now)
|
|
121
|
+
opening = RootDisclosures.verified_root!(wire, provider, profile_ref: PROFILE_REF).fetch("delegate_payload").first
|
|
122
|
+
PurchaseBinding.send(:exact!, opening, %w[cnf constraints exp iat vct])
|
|
123
|
+
raise Invalid unless opening["vct"] == "mandate.checkout.open.1"
|
|
124
|
+
PurchaseBinding.send(:times!, opening, now)
|
|
125
|
+
PurchaseBinding.send(:exact!, opening["cnf"], %w[jwk])
|
|
126
|
+
raise Invalid unless opening["cnf"]["jwk"] == RootSignature.public_jwk!(agent)
|
|
127
|
+
ScopedConstraints.send(:multi_open!, opening["constraints"])
|
|
128
|
+
opening
|
|
129
|
+
end
|
|
130
|
+
def self.digest(wire) = Base64.urlsafe_encode64(Digest::SHA256.digest(wire), padding: false)
|
|
131
|
+
def self.disclose!(value, disclosures)
|
|
132
|
+
require "securerandom"
|
|
133
|
+
salt = Base64.urlsafe_encode64(SecureRandom.random_bytes(16), padding: false)
|
|
134
|
+
wire = Base64.urlsafe_encode64(JSON.generate([salt, value]), padding: false)
|
|
135
|
+
disclosures << wire
|
|
136
|
+
{"..." => digest(wire)}
|
|
137
|
+
end
|
|
138
|
+
%i[issue_open issue_closed present].each do |name|
|
|
139
|
+
implementation = method(name)
|
|
140
|
+
fields = implementation.parameters.map(&:last).freeze
|
|
141
|
+
define_singleton_method(name) do |**arguments|
|
|
142
|
+
unless (fields - arguments.keys).empty? && (arguments.keys - fields).empty?
|
|
143
|
+
raise Invalid.new, cause: nil
|
|
144
|
+
end
|
|
145
|
+
implementation.call(**arguments)
|
|
146
|
+
end
|
|
147
|
+
end
|
|
148
|
+
private_class_method :open!, :digest, :disclose!
|
|
149
|
+
end
|
|
150
|
+
end
|
|
@@ -5,10 +5,13 @@ module AP2MandateVerifier
|
|
|
5
5
|
module MerchantSignature
|
|
6
6
|
def self.sign!(claims, signer, public_key_pem, typ: "JWT")
|
|
7
7
|
RootSignature.send(:dependencies!)
|
|
8
|
-
|
|
8
|
+
raise ArgumentError unless %w[JWT example+sd-jwt kb+sd-jwt].include?(typ)
|
|
9
|
+
terminal = typ == "kb+sd-jwt"
|
|
10
|
+
# A terminal embeds the original, already encoded Merchant JWT. Preserve
|
|
11
|
+
# Merchant/Direct bounds; only Agent terminals use their verifier limits.
|
|
12
|
+
payload = InputBuilder.send(:json!, claims, terminal ? 24_576 : 12_000)
|
|
9
13
|
pem = InputValidator.snapshot!(public_key_pem, max_bytes: 1_024)
|
|
10
14
|
RootSignature.public_jwk!(pem)
|
|
11
|
-
raise ArgumentError unless %w[JWT example+sd-jwt].include?(typ)
|
|
12
15
|
header = Base64.urlsafe_encode64(JSON.generate({"alg" => "ES256", "typ" => typ}), padding: false)
|
|
13
16
|
input = "#{header}.#{Base64.urlsafe_encode64(payload, padding: false)}".freeze
|
|
14
17
|
raw = signer.call(input)
|
|
@@ -16,7 +19,8 @@ module AP2MandateVerifier
|
|
|
16
19
|
String.instance_method(:bytesize).bind_call(raw) == 64
|
|
17
20
|
signature = String.instance_method(:byteslice).bind_call(raw, 0, 64)
|
|
18
21
|
jwt = "#{input}.#{Base64.urlsafe_encode64(signature, padding: false)}"
|
|
19
|
-
raise ArgumentError unless RootSignature.verified_payload!(jwt, pem, expected_typ: typ,
|
|
22
|
+
raise ArgumentError unless RootSignature.verified_payload!(jwt, pem, expected_typ: typ,
|
|
23
|
+
max_bytes: terminal ? 32_768 : 16_384) == claims
|
|
20
24
|
jwt.freeze
|
|
21
25
|
end
|
|
22
26
|
end
|
|
@@ -31,7 +31,30 @@ module AP2MandateVerifier
|
|
|
31
31
|
parts.last == "" && !parts.first.empty? && parts[1...-1].none?(&:empty?)
|
|
32
32
|
# No disclosure decode, digest graph or trusted claims before signature.
|
|
33
33
|
payload = RootSignature.verified_payload!(parts.first, issuer_pem)
|
|
34
|
+
resolve!(parts, payload, multi)
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# Internal structural restoration only. Never authenticates an issuer.
|
|
38
|
+
# Shares the exact closure walker with the authenticated verification path.
|
|
39
|
+
def self.structural_root!(source)
|
|
40
|
+
wire = InputValidator.snapshot!(source)
|
|
41
|
+
raise Rejected, :invalid_root_presentation unless wire.ascii_only? && wire.end_with?("~")
|
|
42
|
+
parts = wire.split("~", -1)
|
|
43
|
+
raise Rejected, :invalid_root_presentation unless parts.size.between?(3, 68) && parts.last == "" &&
|
|
44
|
+
parts[0...-1].none?(&:empty?)
|
|
45
|
+
jwt = parts.first.split(".", -1)
|
|
46
|
+
raise Rejected, :invalid_root_presentation unless jwt.size == 3
|
|
47
|
+
RootSignature.send(:dependencies!)
|
|
48
|
+
header = InputValidator.parse!(RootSignature.send(:decode!, jwt[0], 2_048))
|
|
49
|
+
CheckoutReceipt.send(:header!, header, "example+sd-jwt")
|
|
50
|
+
raise Rejected, :invalid_root_presentation unless RootSignature.send(:decode!, jwt[2], 64).bytesize == 64
|
|
51
|
+
payload = InputValidator.parse!(RootSignature.send(:decode!, jwt[1], 24_576))
|
|
52
|
+
resolve!(parts, payload, true)
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
def self.resolve!(parts, payload, multi)
|
|
34
56
|
raise Rejected, :unsupported_disclosure_profile unless
|
|
57
|
+
payload.instance_of?(Hash) &&
|
|
35
58
|
(payload.keys - %w[delegate_payload _sd_alg]).empty? &&
|
|
36
59
|
(!payload.key?("_sd_alg") || payload["_sd_alg"] == "sha-256") &&
|
|
37
60
|
payload["delegate_payload"].instance_of?(Array) && payload["delegate_payload"].size == 1
|
|
@@ -118,6 +141,6 @@ module AP2MandateVerifier
|
|
|
118
141
|
rescue ArgumentError
|
|
119
142
|
raise Rejected, :invalid_disclosure
|
|
120
143
|
end
|
|
121
|
-
private_class_method :walk!, :decode!, :multi_path?, :multi_paths!
|
|
144
|
+
private_class_method :walk!, :decode!, :multi_path?, :multi_paths!, :resolve!, :structural_root!
|
|
122
145
|
end
|
|
123
146
|
end
|
|
@@ -90,7 +90,16 @@ module AP2MandateVerifier
|
|
|
90
90
|
# Original arrays remain intact; this graph is solely a quantity proof.
|
|
91
91
|
def self.multi_constraints!(details, currency, expected_total)
|
|
92
92
|
open, checkout = details.values_at(:open, :checkout)
|
|
93
|
-
|
|
93
|
+
merchant, requirements = multi_open!(open["constraints"])
|
|
94
|
+
raise Rejected, :constraint_mismatch unless checkout["merchant"] == merchant
|
|
95
|
+
raise Rejected, :currency_mismatch unless checkout["currency"] == currency
|
|
96
|
+
amount = multi_checkout!(checkout)
|
|
97
|
+
raise Rejected, :amount_mismatch unless amount == expected_total
|
|
98
|
+
quantities_match!(requirements, checkout["line_items"])
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
# Internal shared closed-world Open grammar, also used before issuance.
|
|
102
|
+
def self.multi_open!(constraints)
|
|
94
103
|
raise Rejected, :unsupported_constraint unless constraints.instance_of?(Array) && constraints.size == 2
|
|
95
104
|
required, allowed = constraints
|
|
96
105
|
exact!(required, %w[items type])
|
|
@@ -112,11 +121,7 @@ module AP2MandateVerifier
|
|
|
112
121
|
exact!(merchant, %w[id name])
|
|
113
122
|
text!(merchant["id"])
|
|
114
123
|
text!(merchant["name"], 512)
|
|
115
|
-
|
|
116
|
-
raise Rejected, :currency_mismatch unless checkout["currency"] == currency
|
|
117
|
-
amount = multi_checkout!(checkout)
|
|
118
|
-
raise Rejected, :amount_mismatch unless amount == expected_total
|
|
119
|
-
quantities_match!(requirements, checkout["line_items"])
|
|
124
|
+
[merchant, requirements]
|
|
120
125
|
end
|
|
121
126
|
|
|
122
127
|
# Also shared with the explicitly selected merchant signing profile.
|
|
@@ -249,7 +254,7 @@ module AP2MandateVerifier
|
|
|
249
254
|
raise Rejected, :amount_mismatch unless values.all? { |entry| entry["amount"] == expected }
|
|
250
255
|
end
|
|
251
256
|
private_class_method :exact!, :one!, :text!, :quantity!, :amount!, :totals!,
|
|
252
|
-
:multi_constraints!, :bounded_array!, :unique_ids!, :quantities_match!
|
|
257
|
+
:multi_constraints!, :multi_open!, :bounded_array!, :unique_ids!, :quantities_match!
|
|
253
258
|
private_constant :CORE_INSTANCE_OF
|
|
254
259
|
end
|
|
255
260
|
end
|
data/lib/ap2_mandate_verifier.rb
CHANGED
|
@@ -14,6 +14,7 @@ require_relative "ap2_mandate_verifier/merchant_signature"
|
|
|
14
14
|
require_relative "ap2_mandate_verifier/checkout_jwt"
|
|
15
15
|
require_relative "ap2_mandate_verifier/checkout_receipt"
|
|
16
16
|
require_relative "ap2_mandate_verifier/buyer"
|
|
17
|
+
require_relative "ap2_mandate_verifier/conditional_checkout"
|
|
17
18
|
|
|
18
19
|
module AP2MandateVerifier
|
|
19
20
|
# Accepts original JSON bytes only. Syntax validity is not AP2 validity,
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: ap2_mandate_verifier
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.8.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- AP2 Mandate Verifier contributors
|
|
@@ -88,17 +88,22 @@ extensions: []
|
|
|
88
88
|
extra_rdoc_files: []
|
|
89
89
|
files:
|
|
90
90
|
- LICENSE
|
|
91
|
+
- README.ja.md
|
|
91
92
|
- README.md
|
|
92
93
|
- docs/BUYER_DIRECT_CHECKOUT.md
|
|
94
|
+
- docs/CONDITIONAL_CHECKOUT.md
|
|
93
95
|
- docs/DIAGNOSTICS.ja.md
|
|
94
96
|
- docs/DIAGNOSTICS.md
|
|
95
97
|
- docs/MERCHANT_SIGNING.md
|
|
96
98
|
- docs/MULTI_ITEM_CHECKOUT.md
|
|
99
|
+
- docs/RELEASE_080_CANDIDATE.md
|
|
97
100
|
- docs/SUPPORT_CONTRACT.md
|
|
101
|
+
- examples/conditional_checkout.rb
|
|
98
102
|
- lib/ap2_mandate_verifier.rb
|
|
99
103
|
- lib/ap2_mandate_verifier/buyer.rb
|
|
100
104
|
- lib/ap2_mandate_verifier/checkout_jwt.rb
|
|
101
105
|
- lib/ap2_mandate_verifier/checkout_receipt.rb
|
|
106
|
+
- lib/ap2_mandate_verifier/conditional_checkout.rb
|
|
102
107
|
- lib/ap2_mandate_verifier/diagnostic.rb
|
|
103
108
|
- lib/ap2_mandate_verifier/host_binding.rb
|
|
104
109
|
- lib/ap2_mandate_verifier/input_builder.rb
|