ap2_mandate_verifier 0.6.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dbeaa8817a128ad64b2307ae68a86cb2c36f40e710dc459f28354e24b3b251f9
4
- data.tar.gz: 70d40f6293a88043e0f29f10b00e337418ae6819f91cffcb55db8f6c68f21785
3
+ metadata.gz: b6973632ca480195ff57ea153dba920906287f8064357e0cd1069e75b2da58e1
4
+ data.tar.gz: 3f20dac53518631270fb9c9ff7e84dc0e9f8ae96cb78189431cb7f8d20e4f99f
5
5
  SHA512:
6
- metadata.gz: bd6ba8a1c4be5e8b81ff589624ab17d3e1d3861d49cb8aad457abf96708c2446b996381dc0c948f868538c6b80ae9d2ef45d1c693e2e1fa1cf6874df085faeb5
7
- data.tar.gz: 7652d380a3ab2024016f0442672b384f6f8e8eecbec416318b1c9224cc8a954c3be1600e5eb1125f1f9eaa5b172609b41e6c0a3074564c0932bc897ae1f8d2ec
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,14 +1,39 @@
1
- # AP2 Mandate Verifier — 0.6.0 preparation
1
+ # AP2 Mandate Verifier — 0.7.0
2
2
 
3
3
  [日本語](README.ja.md)
4
4
 
5
- Published stable is **0.5.0**. This checkout prepares additive multi-item support for **0.6.0**, which is not published. Review, CI, final package validation and Owner publication approval are separate gates; see [current status](docs/PROJECT_STATUS.md).
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
 
9
34
  Explicitly select `profile_ref: "ap2.checkout.single_merchant_multi_item"` when creating trust with `InputBuilder.trust`, signing a checkout with `CheckoutJWT.sign`, and using `CheckoutReceipt.reference/sign/verify`. The complete verifier follows the authenticated trust selection. The default `ap2.checkout.single_merchant_sku` v1 retains its exact definition, hash and one-line acceptance range.
10
35
 
11
- The new v1 profile supports one merchant, one checkout, one currency and up to eight lines, with different quantities and repeated product IDs on distinct lines. It matches all disclosed product candidates using integer maximum flow: every requirement and every ordered unit must be consumed exactly once. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md) and [synthetic runnable lifecycle](examples/multi_item_checkout.rb).
36
+ The new v1 profile supports one merchant, one checkout, one currency and up to eight lines, with different quantities and repeated product IDs on distinct lines. It matches all disclosed product candidates using integer maximum flow: every requirement and every ordered unit must be consumed exactly once. Quantity shortages and extras reject. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md), [synthetic runnable lifecycle](examples/multi_item_checkout.rb), and [official Python SDK differences](docs/MULTI_ITEM_INTEROP.md) for shortage, empty-candidate and Receipt-reference behavior.
12
37
 
13
38
  Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile. The Gem checks signed data against independently supplied Host trust and order information, then returns immutable Evidence. **Verification success is not purchase or payment permission.**
14
39
 
@@ -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.5.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. Merchant signing and authentic Success/Error Receipts are also available. It is local-only; it does not issue real challenges, consume nonces or execute purchases.
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.5.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.5.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 additive APIs are included in published 0.5.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.5.0 uses `ap2.checkout.single_merchant_sku` v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and the documented disclosure shapes. This checkout 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, product 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.
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.5.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
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,8 +167,20 @@ 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
- - [Published 0.5.0 release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.5.0), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
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).
175
+
176
+ ### Buyer Direct checkout (published 0.7.0)
177
+
178
+ Trusted Surface backends can verify a merchant Checkout before approval, issue a
179
+ Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
180
+ `AP2MandateVerifier::Buyer` module verifies Direct Closed-only presentations at
181
+ the merchant and uses `CheckoutReceipt` with `profile_ref: Buyer::PROFILE_REF`.
182
+ One merchant, 1–8 lines, multiple products and quantities are supported end to end.
183
+ Existing Open→Agent Closed APIs and both profiles retain their contracts.
184
+ See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
185
+ [runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
186
+ is not purchasing authority or payment success. See the [short verified buyer-flow sample](docs/RELEASE_070.md).
@@ -0,0 +1,180 @@
1
+ # Direct / Human Present Checkout — 0.7.0 published
2
+
3
+ This additive optional module implements Trusted Agent Provider approval of a
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
+ commit `b4587ac1d055888a73b4b21750973cffba961793`; no source upgrade is made.
6
+ The first example is one office supply purchase; **multiple products and lines
7
+ are required and supported throughout issuance, presentation, merchant verification
8
+ and Receipt verification**. See the [runnable integration](../examples/direct_checkout.rb).
9
+
10
+ ## Scope, roles and flow
11
+
12
+ 1. Shopping Agent obtains the merchant's original Checkout JWT.
13
+ 2. Trusted Surface backend calls `CheckoutJWT.verify` with an independently
14
+ registered merchant public key and expected merchant identity. It checks
15
+ current order state separately; this Checkout shape has no signed expiry.
16
+ 3. Application authenticates the purchasing employee, checks purchasing authority,
17
+ displays the verified products, quantities, currency and totals, and stores
18
+ the approved **original JWT** in a protected approval record. Bind the page,
19
+ authenticated session and approval transaction to that same record; protect
20
+ against CSRF, stale orders and concurrent replacement.
21
+ 4. Only that backend loads the record and calls `Buyer.issue_closed`. Its
22
+ `approved_checkout_jwt` must equal `checkout_jwt` byte for byte. This contract
23
+ detects substitution, but does not itself prove human identity or consent.
24
+ There is no `approved: true` parameter. Never let Agent input populate the
25
+ approval record, select the Provider signer, or call its signing endpoint.
26
+ 5. Agent receives the approved issuance wire and calls `Buyer.present_closed`.
27
+ It preserves the exact wire and both mandatory disclosures; no signing key
28
+ is needed. Issuance and presentation are separate responsibilities.
29
+ 6. Merchant calls `Buyer.verify` with independently enrolled Provider and merchant
30
+ keys, exact current Checkout JWT from its order database, identity and clock.
31
+ It rechecks order state and purchase policy, then atomically reserves the order
32
+ before applying any effect. Gem verification is not a purchase permission.
33
+ 7. Merchant explicitly supplies its application result to `CheckoutReceipt.sign`.
34
+ Buyer calls `CheckoutReceipt.verify` with the same original presented wire and
35
+ independently registered merchant key, issuer and explicit time window.
36
+ Demo Success means synthetic application acceptance, never payment success.
37
+
38
+ ## Public APIs and failures
39
+
40
+ `CheckoutJWT.verify(jwt:, trusted_public_key_pem:, expected_merchant_id:,
41
+ profile_ref: TrustContext::PROFILE_REF)` returns immutable `Verification` with
42
+ `verified?`, `jwt`, `checkout_hash`, deeply immutable `checkout`, `profile_ref`.
43
+ The default preserves the existing single-SKU shape; pass the existing multi-item
44
+ profile for multiple lines. Invalid input raises the existing redacted
45
+ `CheckoutJWT::Invalid`; it does not return partial authenticated claims.
46
+
47
+ `Buyer.issue_closed(checkout_jwt:, approved_checkout_jwt:,
48
+ trusted_merchant_public_key_pem:, expected_merchant_id:, issued_at:, expires_at:,
49
+ signer:, public_key_pem:)` returns immutable `Issued#closed_sd_jwt`. It rechecks
50
+ merchant signature and multi-item Checkout, approval-byte equality, integer epoch
51
+ and `0 < expires_at - issued_at <= 600` seconds. `signer.call` receives exact
52
+ ASCII JWS signing input and returns 64-byte JOSE ES256. The independently supplied
53
+ Provider public SPKI verifies the result before return. Remote signers own access
54
+ control, timeout and key lifecycle; Gem does not perform network I/O. Invalid
55
+ input, unsupported keys or signer failures raise redacted `Buyer::Invalid`
56
+ without a source cause. The same contract applies to `present_closed`.
57
+
58
+ `Buyer.present_closed(closed_sd_jwt:)` validates supported syntax, commitment
59
+ closure and embedded Checkout shape and returns a detached frozen original wire.
60
+ It does **not** authenticate signatures. Persist `Issued#closed_sd_jwt` unchanged
61
+ and restore by passing it to this API; never rebuild claims/disclosures. The
62
+ merchant must always call full `Buyer.verify`.
63
+
64
+ `Buyer.verify(closed_sd_jwt:, trusted_provider_public_key_pem:,
65
+ trusted_merchant_public_key_pem:, expected_checkout_jwt:, expected_merchant_id:,
66
+ verified_at:)` returns immutable `Buyer::Verification`. `verified? == true` means
67
+ all supported signature, commitment, schema subset, order-byte and time checks
68
+ passed. It exposes deeply immutable `checkout`, `checkout_hash`, `reference` and
69
+ `expires_at`. Failures return `code: :direct_checkout_verification_failed`, false
70
+ and no claims. Success code is `:direct_checkout_verified`. This new type does not
71
+ change existing Result/Evidence, their statuses or saved InputBuilder records.
72
+ Private Ruby constructors are API discipline, not a hostile-code sandbox.
73
+
74
+ For Direct wire use `profile_ref: Buyer::PROFILE_REF` with existing
75
+ `CheckoutReceipt.reference/sign/verify`. Other arguments, errors, result type,
76
+ Success/Error branch exclusivity, expected issuer and time-window checks stay
77
+ unchanged. Never infer application Success from a Gem verification result.
78
+
79
+ ## Profile and limits
80
+
81
+ Direct profile `ap2.checkout.direct.single_merchant` version 1 is selected by the
82
+ API/explicit Receipt argument, never by an untrusted profile claim. Merchant
83
+ Checkout validation reuses `ap2.checkout.single_merchant_multi_item` v1 **without
84
+ changing its contract**. There are 1–8 distinct line IDs, repeated product IDs
85
+ are allowed, quantities are integer 1–1,000,000, amounts/products/sums are integer
86
+ minor units 0–9,007,199,254,740,991. One merchant and currency (USD/EUR/JPY),
87
+ empty links, exactly subtotal/total per line and order, no unsupported fields,
88
+ taxes/shipping/discount engine. Every line and arithmetic result is checked.
89
+ All existing text and wire limits apply jointly; see [③](MULTI_ITEM_CHECKOUT.md).
90
+ Direct has no Open requirements/candidates or max-flow allocation to evaluate:
91
+ the entire exact order is approved. Changed rows/quantities require new approval.
92
+
93
+ ES256/P-256 only. SD-JWT root `typ: example+sd-jwt` (the fixed SDK root type),
94
+ exact payload `{delegate_payload: [{"...": digest}], _sd_alg: "sha-256"}`.
95
+ A 2-element disclosure reveals one Closed object (`vct`, `checkout_hash`, `iat`,
96
+ `exp`, `_sd`), and a 3-element disclosure reveals its `checkout_jwt`. Both are
97
+ required, parent then leaf. Issuance generates independent cryptographic 128-bit
98
+ salts; input salt strings have 22–128 base64url characters. No decoys, omitted,
99
+ extra, duplicated or unknown commitments/claims are accepted. Presentation has
100
+ exact form `<root>~<closed disclosure>~<checkout disclosure>~`. No KB-JWT,
101
+ `cnf`, Agent signature, aud or nonce is accepted here. These are Open→Closed
102
+ binding concerns, not universal Direct requirements. Trusted Provider enrollment
103
+ is external; keys embedded in received data never select trust.
104
+
105
+ In the existing Open→Closed flow, the Provider-signed Open content endorses the
106
+ Agent's public key through `cnf.jwk`; that key verifies the terminal Agent
107
+ signature and its binding to the preceding original SD-JWT, expected audience
108
+ and nonce. Direct instead trusts the Provider signature over the already closed
109
+ order itself and needs no Agent key endorsement. Open issuance, choosing fewer
110
+ disclosures and Agent signing therefore remain separate future APIs.
111
+
112
+ Maximum entire wire 32,768 bytes; Checkout JWT 16,384; root payload 2,048;
113
+ decoded disclosure 24,576; JSON depth 24. Existing strict JSON/canonical base64url
114
+ and finite number checks apply. Limits combine; counts alone do not guarantee
115
+ that a wire fits. `iat <= verified_at < exp`, integer epochs in the existing
116
+ safe epoch range, maximum lifetime 600 seconds, no implicit clock/skew. Applications
117
+ own trustworthy clocks, order validity and shorter approval policy.
118
+
119
+ ## Replay, durable state and receipts
120
+
121
+ Mandates are bearer authorizations for the exact order. Neither hashes nor nonce
122
+ comparison establish single use. Persist approval ID → original Checkout → issued
123
+ wire atomically, enforce unique approval issuance, and on merchant side enforce
124
+ UNIQUE(merchant, checkout ID) with current order/version and atomic state transition.
125
+ Return the saved outcome/Receipt for duplicates; do not repeat the effect. Record
126
+ `processing/unknown` before external effects and reconcile uncertain commits via
127
+ application order/payment status lookup, keeping them on hold instead of retrying.
128
+ The executable example demonstrates serialized duplicate handling and unknown
129
+ hold in memory; it is not durable across process restarts and is not production
130
+ DB integration. Real applications need transactional persistence and authorization.
131
+
132
+ Receipt reference is base64url(SHA256(**entire original presented SD-JWT**)),
133
+ including both disclosure bytes, order and terminal `~`. Never hash reserialized
134
+ claims, only compact JWT, an issuance with a different disclosure order or a
135
+ re-issued token with fresh salts. Reference syntax checks do not verify Provider
136
+ authority. Verify Mandate first and produce Receipt only for explicit application
137
+ outcomes. Receipt authenticity alone proves neither purchase nor payment.
138
+
139
+ ## Compatibility, interoperability and acceptance
140
+
141
+ Existing two profiles, InputBuilder save/restore, Result/Evidence, old API defaults
142
+ and legacy Receipt terminal syntax are unchanged. Direct is a new independent
143
+ entry; existing `verify_checkout` continues to handle its prior Open→Agent Closed
144
+ contract only. Passing Direct wire to old Receipt/default profile rejects.
145
+ No dependency or Ruby support change. Compatible feature version is published 0.7.0.
146
+
147
+ `test/buyer_interop.py` uses the fixed official `sd_jwt.create/verify`, unmodified
148
+ Closed Schema, JWT helpers and independent SHA256/commitment computation.
149
+ Ruby issuance is verified by Python; Python issuance by Ruby, including eight
150
+ lines, multiple products, differing quantities, receipts in both directions and
151
+ wrong-key/substitution/expiry/reference negatives. The SDK issuance disclosure
152
+ order may differ; the test selects parent-before-leaf using original disclosure
153
+ strings, without reserializing claims or changing signatures, then hashes that
154
+ actual presentation. This explicit restricted order is a local profile rule.
155
+ The SDK high-level Checkout chain helper requires Open+Closed; it is not a Direct
156
+ validator. Our Direct implementation uses its independent root SD-JWT primitives.
157
+
158
+ Receipt normative `sd_hash` includes disclosures and terminal `~`; SDK
159
+ `MandateClient.get_closed_mandate_jwt` extracts compact-only, so its recommended
160
+ reference differs. We follow normative original SD-JWT hashing. Checkout Receipt
161
+ uses Schema `status: Success/Error`, not generic prose `result: success/error`.
162
+ Existing max-flow shortage/empty-candidate SDK disagreements remain documented in
163
+ [MULTI_ITEM_INTEROP](MULTI_ITEM_INTEROP.md); Direct has no Open allocation, and
164
+ compatibility regression continues to test those profiles. No checks are omitted
165
+ to force agreement with SDK.
166
+
167
+ Acceptance includes approval-to-Receipt example, 3/8-line flows and both outcomes,
168
+ repeated products, reordered separately signed orders, rejection of 0/9 lines,
169
+ duplicate line IDs, invalid quantities/prices/totals/currency/links, wrong keys,
170
+ expiry/future time, missing disclosures, malformed signed combinations and unknown
171
+ formats. Existing source and ordinary-install regressions run on MRI 3.4.12/4.0.9.
172
+ Latest-HEAD independent review and branch protections are required before merge.
173
+
174
+ Open issuance, Agent Closed generation/selective disclosure/presentation, User
175
+ Credentials, multiple merchants, split orders and continuous autonomous buying
176
+ are follow-up candidates. Agent-to-Agent delegation is outside current AP2 scope,
177
+ not declared permanently forbidden. Real Issuer trust, actual demand, generic AP2
178
+ support and production safety are not established by synthetic test success.
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.