ap2_mandate_verifier 0.1.0 → 0.2.1

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: c34a0bd3cd87a6ed543aa7342e48561114dd87962ef7e191f0708818f5bb73f0
4
- data.tar.gz: 93ac9fdc7ede629a930cdc62937c1261c07dafc4c9c5914fd769a1ed540d5602
3
+ metadata.gz: f45da719098900e3ddd4044f4285b6d2cb8df42e4ca23168b322ae96bdc4fce7
4
+ data.tar.gz: 661d44d4ac03ffa8427e68f9f121fc747f33056df6c7de007734ff3b583c7247
5
5
  SHA512:
6
- metadata.gz: 9d99c2fe1dbb1eb24cb884941e1c4bfccd2b3a8703f70e82777e3f848c134d2c209f2e1e1a1389f978262a08824365f1bbcf0911bd787a119791f9a2fb19e35e
7
- data.tar.gz: a8d10488368acc7179457c38143cbeb4ac60a8e6ca973591084504c7abee73fd65afe18016d679a7c5a5ef151839db96946dcb1047623e302e2f8423b9e84572
6
+ metadata.gz: 94c8b80c1eac4257ade9c329aaf80dfe75ed42d2ba1f54744a43167002520e6fd0b5457ab65392336b6090ee5a09314ee784a52e8e27b12f04d91da092b13a35
7
+ data.tar.gz: aa5d2eac3f0aaf2a69c9fe4a76c22e774cdcad44b8760f1405568bb47b6554225e2b36ea6ab1fa15dd4b50255a7115e74a82cd0299bf76757d7405035a292e08
data/README.md CHANGED
@@ -1,61 +1,108 @@
1
- # AP2 Mandate Verifier — 0.1.0
1
+ # AP2 Mandate Verifier — 0.2.1 candidate / published 0.2.0
2
2
 
3
- RubyでAP2の固定profileを検証する、Rails非依存のGemです。**署名の正しさだけで購入を許可しません。** 必要な検査が成立した場合に不変のEvidenceを返し、最終業務判断はHostが行います。
3
+ [Japanese / 日本語](README.ja.md)
4
4
 
5
5
  A Rails-independent Ruby Gem for a deliberately fixed AP2 verification profile. **A valid signature alone never authorizes a purchase.** Successful checks produce immutable Evidence; the Host makes the final business decision.
6
6
 
7
- ## 配布と導入 / Distribution and installation
7
+ ## Start with the local demo
8
8
 
9
- 配布状況は[公式RubyGems版一覧](https://rubygems.org/gems/ap2_mandate_verifier/versions)が正本です。この文書や版情報の存在だけでは公開済みを意味しません。次のコマンドは**0.1.0が公式一覧に掲載された後**に使用します。公開前は未登録エラーになり得ます。旧研究版pre3は別の成果物です。
9
+ The [AP2 Mandate Verifier Demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo) calls the real verifier on synthetic valid, tampered and expired examples, with Docker local-startup instructions; it is not a hosted demo site, production payments or Host authorization.
10
10
 
11
- The [official RubyGems version list](https://rubygems.org/gems/ap2_mandate_verifier/versions) is authoritative for availability. This document and version metadata alone do not establish publication. Use these commands **once0.1.0 is listed**; before publication they may fail because the version is absent. Research prerelease pre3 is a separate artifact.
11
+ For a Japanese walkthrough of the three demo scenarios, see the [Zenn article](https://zenn.dev/ccq/articles/7f9643f96fe5c7).
12
12
 
13
- 既存のMRI4.0.9環境と利用者が選ぶGem隔離環境で使用します。通常の導入は依存取得・JSON native buildを伴い得ます。依存衝突や未知providerを許容するために固定条件を緩めないでください。
13
+ ## Choose your starting point
14
14
 
15
- Use an existing MRI4.0.9 environment and your chosen Gem isolation. Normal installation may fetch dependencies and build JSON native extensions. Stop on conflicts or unknown providers rather than relaxing pins.
15
+ | Route | Start here |
16
+ | --- | --- |
17
+ | Docker demo: compare three synthetic cases | Follow the [demo README](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) for local startup and valid / tampered / expired examples. Docker commands are maintained there. |
18
+ | Ruby without the demo: existing MRI 4.0.9 | Follow [installation](#distribution-and-installation), then the [saved synthetic example](#try-the-saved-synthetic-example) below. |
19
+
20
+ Both routes use the fixed-profile verifier, not payment execution or Host authorization. See the [supported contract](#supported-contract) for the scope. The goal is to make the choices understandable in about five minutes, not to promise a five-minute installation or build.
21
+
22
+ ## Distribution and installation
23
+
24
+ [0.2.0 is published on RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.2.0). This is the fixed-profile, verifier-only stable release; the research prerelease pre3 is a separate artifact.
25
+
26
+ Use an existing MRI 4.0.9 environment and your chosen Gem isolation. Normal installation may fetch dependencies and build JSON native extensions. Stop on conflicts or unknown providers rather than relaxing pins.
16
27
 
17
28
  ```sh
18
29
  ruby --version # MRI 4.0.9 required
19
- gem install ap2_mandate_verifier --version 0.1.0
30
+ gem install ap2_mandate_verifier --version 0.2.0
20
31
  ```
21
32
 
22
- BundlerのGemfile / Bundler Gemfile:
33
+ Bundler Gemfile:
23
34
 
24
35
  ```ruby
25
- gem "ap2_mandate_verifier", "= 0.1.0"
36
+ gem "ap2_mandate_verifier", "= 0.2.0"
26
37
  ```
27
38
 
28
- 固定runtime依存 / Fixed runtime dependencies:
29
- JSON2.19.9, JWT3.3.0, base640.3.0, OpenSSL gem4.0.2, Digest3.2.1.
30
- Bundler4.0.20は既存resolver基準でruntime依存ではありません / Bundler4.0.20 is the observed resolver baseline, not a runtime dependency.
31
- RubyGemsの版制約だけではMRI engine、OSや実native/providerの出所を保証しません / Gem version constraints alone do not enforce the MRI engine, OS or native-provider provenance.
39
+ Fixed runtime dependencies: JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1.
40
+ Bundler 4.0.20 is the observed resolver baseline, not a runtime dependency. Gem version constraints alone do not enforce the MRI engine, OS or native-provider provenance.
41
+
42
+ ## Unpublished 0.2.1 candidate: Ruby 3.4.12 compatibility
43
+
44
+ 0.2.1 is being prepared; RubyGems publication, a public tag and GitHub Release require a separate Owner decision. The published 0.2.0 commands above continue to require MRI 4.0.9.
32
45
 
33
- ## 対応範囲 / Supported contract
46
+ The candidate targets exactly MRI 3.4.12 and MRI 4.0.9 with the same five fixed dependencies. Its installation metadata permits Ruby `>= 3.4.12, < 4.1`; that interval does not declare every intermediate Ruby version or another engine supported. Initial validation uses Debian 12/arm64 and official Ruby bookworm images. Actual build, loaded-provider and installed-Gem results are tracked in the [compatibility record](docs/RUBY_3_4_12_COMPATIBILITY.md); fresh source regressions passed on both versions; exact-archive packaging checks are recorded there separately. Historical macOS/Ubuntu observations do not validate the candidate.
34
47
 
35
- - AP2固定source `b4587ac1d055888a73b4b21750973cffba961793`、登録profile `ap2.checkout.single_merchant_sku` v1の正確なbody/hash・7支持形状 / The exact registered profile v1 body/hash and seven supported shapes at the pinned AP2 source.
36
- - ES256/P256、Open1→Closed1、固定3開示位置、単一Merchant/SKU/行、USD/EUR/JPY、empty links。未知/非対応形式は拒否 / ES256/P256, Open1→Closed1, three fixed disclosure positions, one Merchant/SKU/line, USD/EUR/JPY and empty links; unknown/unsupported forms are rejected.
37
- - 厳格入力と有限上限、供給trust選択、Root原文署名と全域閉包、Agent/Merchant署名・委任・購入/Host binding、型/制約/期限をGemが検査 / The Gem checks strict bounded inputs, supplied trust selection, signed Root wire and full supported closure, Agent/Merchant signatures, delegation, purchase/Host binding, types, constraints and time.
38
- - 入口は既存 `verify_research`。名前と `verified_research/scoped_research_verified`・Evidence v2契約を維持。安定版番号でも一般AP2対応やHost許可へ昇格しない / The existing entry, result names and Evidence v2 contract remain unchanged; a stable version does not imply generic AP2 support or Host authorization.
48
+ After obtaining the prepared candidate Gem and checking its SHA256 against that record, install it in your chosen isolated environment:
39
49
 
40
- 正確な必須形状・全上限・失敗codeは[SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md)を参照してください。 / See [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for exact required shapes, bounds and failure codes.
50
+ ```sh
51
+ ruby --version # MRI 3.4.12 or MRI 4.0.9
52
+ gem install ./ap2_mandate_verifier-0.2.1.gem --no-document
53
+ ```
41
54
 
42
- ## 環境・互換性・保守 / Environment, compatibility and maintenance
55
+ This is ordinary installation from the candidate file and may fetch/build the fixed dependencies. Seven inputs, the fixed profile, Fail Closed behavior, Result/Evidence v2 and all existing API meanings are retained. Candidate preparation is separate from publication and Host production GO.
43
56
 
44
- 対象はMRI4.0.9と固定依存、観測されたMBA/macOS arm64 (`arm64-darwin25`) およびUbuntu24.04/x86_64の正確な構成です。[現行版の包装・provider証拠](research/stable010_release_linux_package/README.md)と[過去の環境記録](docs/VERIFIER_CORE_COMPLETION_CRITERIA.md#初回の対応環境保証範囲owner採用済み)を区別してください。OS全版・他engine/architecture・任意provider更新は保証しません。
57
+ ## Verification APIs: 0.2.0 and compatibility
45
58
 
46
- The baseline is MRI4.0.9 with fixed dependencies and the exact observed MBA/macOS arm64 and Ubuntu24.04/x86_64 configurations. Distinguish [release-package/provider evidence](research/stable010_release_linux_package/README.md) from [historical environment records](docs/VERIFIER_CORE_COMPLETION_CRITERIA.md#初回の対応環境保証範囲owner採用済み). Other OS versions, engines, architectures and arbitrary provider updates are not covered.
59
+ **The installation commands and saved example use published 0.2.0 and its recommended `verify_checkout` entry.** Existing 0.1.0 applications can continue using `verify_research`; it remains available in 0.2.0 without a deprecation warning. Installing 0.1.0 does not provide `verify_checkout`.
47
60
 
48
- 支持入力の判定意味・APIを黙って変更しません。安全性修正で受理を狭める場合は理由・影響・移行を明示し、破壊的なAPI/必須field/profile変更を区別します。依存更新は自動互換ではありません。
61
+ | Entry | Availability and contract |
62
+ | --- | --- |
63
+ | `verify_checkout(**inputs)` | Recommended full-verification entry in 0.2.0. Delegates directly to `ResearchResult.verify` without changing inputs or the verification pipeline. |
64
+ | `verify_research(**inputs)` | Full-verification entry in published 0.1.0; retained unchanged in v0.2.0, without a deprecation warning. |
65
+ | `verify(presentation_json:)` | Existing JSON syntax check only. Valid JSON returns `:unverified` / `:verification_not_implemented`, never successful Evidence. It is not a substitute for full verification. |
49
66
 
50
- Supported-input semantics and APIs do not change silently. Security-driven narrowing identifies reason, impact and migration; breaking API/required-field/profile changes are explicit. Dependency updates are not automatically compatible.
67
+ The recommended entry takes all seven inputs. In the saved example below, these values come from `full`; real integrations must supply the authenticated Host inputs described below:
68
+
69
+ ```ruby
70
+ result = AP2MandateVerifier.verify_checkout(
71
+ trust_json: full.fetch("trust_json"),
72
+ selection_json: full.fetch("selection_json"),
73
+ host_json: full.fetch("host_json"),
74
+ root_presentation: full.fetch("root_presentation"),
75
+ terminal_jws: full.fetch("terminal_jws"),
76
+ host_checkout_jws: full.fetch("host_checkout_jws"),
77
+ verified_at: full.fetch("verified_at")
78
+ )
79
+ ```
80
+
81
+ Both full-verification entries require all seven inputs listed under [responsibility boundaries](#real-inputs-and-responsibility-boundaries): six original Strings and externally supplied integer Unix seconds. Seven inputs and seven supported shapes are different concepts. Neither entry broadens the fixed profile below or supplies missing trust, Host state or time. Missing or unknown keywords return `:unavailable` / `:research_verification_unavailable`, with `success? == false` and `evidence == nil`; positional arguments or invalid keyword expansion can raise before verification begins.
82
+
83
+ The [result handling](#understanding-the-result) is unchanged: success remains `ResearchResult` with `:verified_research` / `:scoped_research_verified` and immutable Evidence v2; rejected and unavailable results have no Evidence. Evidence is checked facts, **not purchase authorization**. Exceptions or missing results must also stop the caller. See the [API migration plan](docs/V0_2_0_API_PLAN.md) for design history; its earlier implementation gates do not describe the published 0.1.0 artifact or replace this availability distinction.
84
+
85
+ ## Supported contract
86
+
87
+ - AP2 pinned source `b4587ac1d055888a73b4b21750973cffba961793`, registered profile `ap2.checkout.single_merchant_sku` v1: exact body/hash and seven supported shapes.
88
+
89
+ - ES256/P256, Open1→Closed1, three fixed disclosure positions, one Merchant/SKU/line, USD/EUR/JPY and empty links; unknown/unsupported forms are rejected.
90
+
91
+ - The Gem checks strict bounded inputs, supplied trust selection, signed Root wire and full supported closure, Agent/Merchant signatures, delegation, purchase/Host binding, types, constraints and time.
51
92
 
52
- 初回安定系列の最新修正版のみを保守対象とし、月次・関連勧告判明時・次版前に手動確認します。旧版backport・固定保守年数・受付/修正期限・24時間対応は約束しません。[SECURITY](SECURITY.md)と[保守方針](docs/POST_RELEASE_MAINTENANCE.md)を参照し、秘密鍵・実Mandate・個人情報を報告しないでください。
93
+ - Both full-verification entries above preserve `verified_research` / `scoped_research_verified` result names and the Evidence v2 contract; a stable version does not imply generic AP2 support or Host authorization.
53
94
 
54
- Maintenance covers the latest patch in the initial stable series, with manual monthly/advisory/pre-release review. No old-series backport, fixed support term, response/fix deadline or24/7 promise. See [SECURITY](SECURITY.md) and [maintenance](docs/POST_RELEASE_MAINTENANCE.md); never report private keys, real Mandates or personal data.
95
+ See [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for exact required shapes, bounds and failure codes.
55
96
 
56
- ## 保存済み合成入力で試す / Try the saved synthetic example
97
+ ## Environment, compatibility and maintenance
57
98
 
58
- 以下は既存の合格済みinstalled検査と同じ公開 `FULL` 入力を読む例です。入力JSONはGemに含まれません。固定commitから取得し、SHA256を確認してから使います。fixtureに秘密鍵は含まれません。fixtureのtrust/Host入力は**テスト専用の合成値**であり、実Issuer登録・現在の注文・実時刻として再利用してはいけません。`verified_at = 1800000000` は保存シナリオの固定時刻です。
99
+ The published 0.2.0 baseline is MRI 4.0.9 with fixed dependencies and the exact observed MBA/macOS arm64 and Ubuntu 24.04/x86_64 configurations. The 0.2.1 candidate targets MRI 3.4.12 and 4.0.9; its Debian 12/arm64 validation status is tracked separately above. Distinguish [release-package/provider evidence](research/stable010_release_linux_package/README.md) from [historical environment records](docs/VERIFIER_CORE_COMPLETION_CRITERIA.md#初回の対応環境保証範囲owner採用済み). Other OS versions, engines, architectures and arbitrary provider updates are not covered.
100
+
101
+ Supported-input semantics and APIs do not change silently. Security-driven narrowing identifies reason, impact and migration; breaking API/required-field/profile changes are explicit. Dependency updates are not automatically compatible.
102
+
103
+ Maintenance covers the latest patch in the initial stable series, with manual monthly/advisory/pre-release review. No old-series backport, fixed support term, response/fix deadline or 24/7 promise. See [SECURITY](SECURITY.md) and [maintenance](docs/POST_RELEASE_MAINTENANCE.md); never report private keys, real Mandates or personal data.
104
+
105
+ ## Try the saved synthetic example
59
106
 
60
107
  This example reads the same public `FULL` input used by the successful installed-Gem checks. The input JSON is not packaged in the Gem. Fetch it from the pinned commit and verify its SHA256 first. It contains no private keys. Its trust/Host assertions are **synthetic test data**, not real Issuer enrollment, a current order or a live clock. `verified_at = 1800000000` is the saved scenario's fixed evaluation time.
61
108
 
@@ -89,7 +136,7 @@ inputs = {
89
136
  verified_at: full.fetch("verified_at")
90
137
  }
91
138
 
92
- result = AP2MandateVerifier.verify_research(**inputs)
139
+ result = AP2MandateVerifier.verify_checkout(**inputs)
93
140
  puts "status=#{result.status} code=#{result.code}"
94
141
  if result.success?
95
142
  checked_facts = result.evidence.to_h # Detached, deeply frozen in-process facts.
@@ -100,66 +147,82 @@ else
100
147
  end
101
148
  ```
102
149
 
103
- この保存 `FULL` ケースの期待値は `status=:verified_research`、`code=:scoped_research_verified`、`success?=true` です。実入力・不支持入力・依存障害では同じ結果を期待しません。非成功ならEvidenceはnilです。例外やプロセス終了で結果がない場合も停止してください。Evidence全体やraw入力を安易にログへ出さないでください。
104
-
105
150
  For this saved `FULL` case, the expected result is `status=:verified_research`, `code=:scoped_research_verified`, `success?=true`. This is not the expected outcome for arbitrary real inputs, unsupported forms or dependency failures. Non-success results have nil Evidence. Exceptions or process termination without a result must also stop the caller. Avoid logging complete Evidence or raw inputs.
106
151
 
107
- ## 実入力と責任境界 / Real inputs and responsibility boundaries
152
+ ## Understanding the result
108
153
 
109
- | Keyword | 入力契約 / Input contract |
110
- | --- | --- |
111
- | `trust_json` | 認証済みHostの固定snapshot/profileと公開鍵登録を表すJSON原文String / Original JSON String for authenticated Host trust snapshot, profile and public-key registration. |
112
- | `selection_json` | 独立Hostが選択したtenant・profile版・Issuer/Agent/Merchantの識別/用途/鍵参照 / Independently selected tenant, profile version and role/identity/purpose/key references. |
113
- | `host_json` | 認証済み現在注文binding、issued challenge、発行元・時計識別 / Authenticated current order binding, issued challenge, expected issuer and clock identity. |
114
- | `root_presentation` | disclosure順と末尾`~`を維持した署名付きRoot提示原文String / Original signed Root presentation String, preserving disclosure order and trailing `~`. |
115
- | `terminal_jws` | Agent terminal compact JWS原文String / Original Agent terminal compact JWS String. |
116
- | `host_checkout_jws` | Hostが固定したMerchant Checkout compact JWT原文String / Original Merchant Checkout compact JWT String frozen by the Host. |
117
- | `verified_at` | 外部の信頼時計から供給する整数Unix秒 / Integer Unix seconds supplied by an external trusted clock. |
154
+ | Outcome | `status` and predicate | Evidence and handling |
155
+ | --- | --- | --- |
156
+ | Successful scoped verification | `:verified_research`; `success? == true`; `code == :scoped_research_verified` | Present: checked facts, **not purchase authorization**. Host responsibilities still apply. |
157
+ | Rejected | `:rejected`; `rejected? == true` | Absent (`nil`). Stop; inspect `result.code` for the rejection reason. |
158
+ | Verification unavailable | `:unavailable`; `unavailable? == true` | Absent (`nil`). Stop; a dependency or verification failure does not by itself establish that the input is invalid. |
118
159
 
119
- 正確な必須形状・型・上限は[SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs)を参照してください。tokenからtrustを自己登録したり、署名原文をparse/再encode/並べ替えして渡したりしません。Host-onlyなBuyer/account等の一致はIssuer署名による本人認証を意味しません。
160
+ An exception, process termination or missing result must also stop the caller without authorizing a purchase. The example above deliberately stops on every non-success result. See [Result and Evidence](docs/SUPPORT_CONTRACT.md#result-and-evidence) for details.
120
161
 
121
- See [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs) for exact required shapes, types and limits. Do not register trust from the presented token or parse/re-encode/reorder signed wire input. Matching Host-only Buyer/account fields does not establish Issuer-signed identity authentication.
162
+ ## Real inputs and responsibility boundaries
122
163
 
123
- `verify_research`の成功は固定profileにおける検証事実です。Hostは最新trust/失効/注文版/challenge/有効期限を再照合し、nonce原子消費+注文CASを自身で成立させる必要があります。Gemはこれを実行しません。EvidenceをJSON化して再入力し、真正性を回復するAPIもありません。旧 `verify(presentation_json:)` はJSON構文境界だけで、成功Evidenceを返しません。
164
+ | Keyword | Input contract |
165
+ | --- | --- |
166
+ | `trust_json` | Original JSON String for authenticated Host trust snapshot, profile and public-key registration. |
167
+ | `selection_json` | Independently selected tenant, profile version and role/identity/purpose/key references. |
168
+ | `host_json` | Authenticated current order binding, issued challenge, expected issuer and clock identity. |
169
+ | `root_presentation` | Original signed Root presentation String, preserving disclosure order and trailing `~`. |
170
+ | `terminal_jws` | Original Agent terminal compact JWS String. |
171
+ | `host_checkout_jws` | Original Merchant Checkout compact JWT String frozen by the Host. |
172
+ | `verified_at` | Integer Unix seconds supplied by an external trusted clock. |
124
173
 
125
- A successful `verify_research` result establishes scoped verification facts. The Host still must recheck latest trust/revocation/order version/challenge/time and atomically consume the nonce with order CAS. The Gem does not perform those operations. Serializing Evidence to JSON does not preserve or reconstruct authenticity through this API. Legacy `verify(presentation_json:)` checks only the JSON syntax boundary and never returns successful Evidence.
174
+ See [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs) for exact required shapes, types and limits. Do not register trust from the presented token or parse/re-encode/reorder signed wire input. Matching Host-only Buyer/account fields does not establish Issuer-signed identity authentication.
126
175
 
127
- 連携前に[Issuer登録前チェックリスト](docs/ISSUER_ONBOARDING_CHECKLIST.md)と[Issuer/Host最小契約](docs/ISSUER_HOST_MINIMUM_CONTRACT.md)を参照してください。実Issuerの信頼と特定Hostの本番運用GOは、このGemの版番号や検証成功では成立しません。契約と`research/`のHost/DBコードは合成研究の設計・限定観測であり、本番adapterとして提供するものではありません。
176
+ A successful result from either full-verification entry establishes scoped verification facts. The Host still must recheck latest trust/revocation/order version/challenge/time and atomically consume the nonce with order CAS. The Gem does not perform those operations. Serializing Evidence to JSON does not preserve or reconstruct authenticity through this API. Legacy `verify(presentation_json:)` checks only the JSON syntax boundary and never returns successful Evidence.
128
177
 
129
178
  Before integration, consult the [Issuer onboarding checklist](docs/ISSUER_ONBOARDING_CHECKLIST.md) and [Issuer/Host minimum contract](docs/ISSUER_HOST_MINIMUM_CONTRACT.md). Real-Issuer trust and a specific Host's production GO are not established by this Gem version or verification success. The contract and Host/DB code under `research/` describe synthetic research designs and limited observations, not a production adapter.
130
179
 
131
- `inputs`はtrust_json/selection_json/host_json/root_presentation/terminal_jws/
132
- host_checkout_jws/verified_atです。前3つのJSONは認証済みの独立Host入力として渡し、
133
- 提示tokenの自己申告から信頼を追加しません。raw nonceは入力専用、EvidenceにはSHA256だけを
134
- 投影します。Hash/JSONへ書き出したものを真正なEvidenceとして再入力するAPIはありません。
135
-
136
- 旧`verify`はJSON構文境界だけで、その他の低レベルverify入口と共にsuccess?=false/
137
- evidence=nilを維持します。呼出し例のsuccess?を旧APIへ流用してはいけません。
138
-
139
- ## 非保証と安全な停止 / Exclusions and safe stopping
180
+ Raw nonce values are input-only; Evidence projects their SHA256. Other low-level verification entries also keep `success?=false` and `evidence=nil`; do not apply the successful example to those entries.
140
181
 
141
- 一般AP2/全Schema、任意の実Issuer互換性、発行/提示/Receipt生成、Rails adapter、実決済、実Host/DB/失効運用、最悪CPU/RSS/並行性能・数値SLAは対象外です。無欠陥や全パス安全性を証明したとは主張しません。既知重大問題やGem自身の検査欠落をこの非保証表示で補いません。
182
+ ## Exclusions and safe stopping
142
183
 
143
184
  General AP2/full Schema, arbitrary real-Issuer interoperability, issuance/presentation/Receipt generation, Rails adapters, real payments/Host/DB/revocation operations, worst CPU/RSS/concurrency and numerical SLAs are outside scope. No defect-free/all-path safety proof is claimed; exclusions do not excuse known major defects or missing Gem checks.
144
185
 
145
- Hostはtokenから独立した認証済みtrust/鍵/profile・最新失効/時計/注文/challengeを供給し、Evidence使用直前に再照合し、nonce原子消費+注文CAS・PENDING回復・最終ALLOWを担当します。Gemの既存検査をHostへ移す意味ではありません。Evidenceは同一の信頼Rubyプロセス内の検査事実で、JSON/Hashから真正性を再構成しません。不明・拒否・不能・例外・結果なしは許可せず、Hostが外側の時間/メモリ/同時実行制限を設けます。
146
-
147
186
  The Host supplies authenticated token-independent trust/keys/profile and current revocation/clock/order/challenge state, rechecks before use, atomically consumes nonce with order CAS, reconciles PENDING and decides ALLOW. Existing Gem checks remain Gem responsibilities. Evidence is in-process checked facts in trusted Ruby, not a transport credential. Unknown/rejected/unavailable/exception/missing results never authorize; the Host provides outer time/memory/concurrency limits.
148
187
 
149
- ## 証拠と履歴 / Evidence and history
188
+ ## Evidence and history
189
+
190
+ The published 0.2.0 Gem is **33,280 bytes**, SHA256 `9a52e802de5a0564c34d198f4c4ad2c2b60791a8f1eb6e31db14c49e28e91f16`, from source commit `9b2e28d91fc4886722de7b9c39a5422e966953a9`. Publication on 2026-10-30 was verified against official RubyGems metadata, distribution bytes and the retained Gem. Its final Debian 12/arm64 / MRI 4.0.9 packaging observation matched all 13 payload files across source/archive/installation, loaded 10 product Ruby files normally and passed 118 installed cases using saved inputs/expected values. This is a limited observation, not a supported-platform expansion; source190/885 were not rerun in that packaging step. See [current publication status](docs/PROJECT_STATUS.md#020公開済み--現在の配布状態).
191
+
192
+ The packaged README and contract are snapshots from before publication. These repository documentation updates do not change the published Gem, require no rebuild, and do not transfer its validation to a rebuilt artifact. GitHub source archives contain repository source, not the RubyGems binary.
150
193
 
151
- 現在の新archiveのSHA・環境別結果・制限は[版別検証記録](research/stable010_release_linux_package/README.md)を参照してください。archiveのSHAを同梱文書へ自己埋込せず、外部manifestで識別します。SHAは配布bytesを識別するもので、Host trustや全面安全性を保証しません。
194
+ The published 0.1.0 archive is **34,304 bytes**, SHA256 `37b2a235b6fab2d9d9765ae985dd9db27afd3b2c5407fe263a6b65314550db32`. Official metadata, owner `cuichangquan`, downloaded distribution bytes and all 13 payload hashes were checked on 2026-10-26. See the [publication record](research/stable010_release_linux_package/README.md#rubygems-publication-verified). This repository README was reorganized after publication and differs from the packaged README; the published archive was not rebuilt.
152
195
 
153
196
  See the [versioned validation record](research/stable010_release_linux_package/README.md) for this archive's external SHA, per-environment observations and limits. The archive hash is kept outside its payload to avoid self-reference. A hash identifies bytes, not Host trust or global safety.
154
197
 
155
- [旧0.1.0候補R1](research/stable010_candidate/README.md)、[公開pre3](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0.pre.3)、[pre2 Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.1.0.pre.2)は別archiveです。旧NOT_RUN/停止/成功は各時点の記録として保持し、新archiveの実測へ読み替えません。885回帰(147は内数)と旧Ruby4.0.1独立比較の再利用は、新たな885実行やLinux独立Oracleを意味しません。
198
+ [Earlier 0.1.0 candidate R1](research/stable010_candidate/README.md), [published pre3](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0.pre.3) and [pre2 Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.1.0.pre.2) are different archives. Historical NOT_RUN/stops/passes remain tied to their original bytes and time. Reusing 885 regressions (including 147) and Ruby4.0.1 independent comparisons is not a fresh 885 run or Linux independent Oracle.
156
199
 
157
- [Earlier0.1.0 candidateR1](research/stable010_candidate/README.md), [publishedpre3](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.1.0.pre.3) and [pre2 Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.1.0.pre.2) are different archives. Historical NOT_RUN/stops/passes remain tied to their original bytes and time. Reusing885 regressions (including147) and Ruby4.0.1 independent comparisons is not a fresh885 run or Linux independent Oracle.
200
+ [Historical research documentation](https://github.com/cuichangquan/ap2-mandate-verifier/blob/2546d112b4bd4eaaf0a55b502f1c40b1fd61be65/README.md#research-documentation) does not override the current contract or release status. Future SDK plans are described in [PRODUCT_VISION](docs/PRODUCT_VISION.md).
158
201
 
159
- [過去READMEの研究資料一覧 / Historical research documentation](https://github.com/cuichangquan/ap2-mandate-verifier/blob/2546d112b4bd4eaaf0a55b502f1c40b1fd61be65/README.md#research-documentation)は履歴資料であり、現在の契約・公開状態より優先しません。将来のSDK構想は[PRODUCT_VISION](docs/PRODUCT_VISION.md)を参照してください。
202
+ ## Illustrated concepts (Japanese diagrams)
160
203
 
161
- ## License
204
+ These existing diagrams contain Japanese text and illustrate broader AP2 concepts, not the exact fixed-profile implementation contract. The fixed-profile contract above takes precedence. Issuer trust and current revocation are supplied and maintained by the Host; the Gem does not independently establish live external trust or revocation. Arbitrary chains, issuance, Payment Mandates and payment execution shown conceptually are not supported features of this release.
162
205
 
163
- MIT. See [LICENSE](LICENSE).
206
+ ### AP2 overview (Japanese)
207
+
208
+ ![AP2 overview (Japanese)](docs/assets/ap2-overview.png)
209
+
210
+ ### Delegation and Host responsibility boundaries (Japanese)
211
+
212
+ ![Delegation and Host responsibility boundaries (Japanese)](docs/assets/ap2-delegation-trust-flow.png)
213
+
214
+ ### Mandate anatomy (Japanese)
215
+
216
+ ![Mandate anatomy (Japanese)](docs/assets/mandate-anatomy.png)
164
217
 
218
+ ### SD-JWT and delegation concepts (Japanese)
165
219
 
220
+ ![SD-JWT and delegation concepts (Japanese)](docs/assets/sd-jwt-delegation-chain.png)
221
+
222
+ ### Fail-closed attack patterns and Host replay prevention (Japanese)
223
+
224
+ ![Fail-closed attack patterns and Host replay prevention (Japanese)](docs/assets/attack-patterns-fail-closed.png)
225
+
226
+ ## License
227
+
228
+ MIT. See [LICENSE](LICENSE).
@@ -1,10 +1,42 @@
1
- # Fixed-profile AP2 verification — 0.1.0
1
+ # Fixed-profile AP2 verification — 0.2.1 candidate / published 0.2.0
2
2
 
3
3
  **Fixed-profile verification contract; Evidence is not Host ALLOW or payment permission.**
4
4
  Distribution availability is determined by the official RubyGems version listing, not by this document. Specific Host production GO remains separate.
5
5
  Owner adopted the existing verification API and bounded stable-release conditions below. Publication and a specific Host's production operation are separate decisions; this contract does not authorize either.
6
6
  Published research-only pre3 remains unchanged. Its historical observations below do not certify this new archive.
7
7
 
8
+ ## Unpublished 0.2.1 compatibility candidate
9
+
10
+ The candidate's formal runtime targets are exactly MRI 3.4.12 and MRI 4.0.9, with JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1 unchanged. Bundler 4.0.20 is the resolver validation baseline, not a runtime dependency. The Gem's installation requirement `>= 3.4.12, < 4.1` is an interval for dependency resolution; it does not certify other Ruby versions or engines.
11
+
12
+ Initial validation targets Debian 12/arm64 with official Ruby bookworm images. Actual runtime/OS/native-provider identities, source regressions, ordinary installed-Gem checks and exact artifact identity are tracked in the [compatibility record](RUBY_3_4_12_COMPATIBILITY.md). Fresh source regressions passed on both versions; exact-archive packaging checks are recorded there separately. Historical observations below do not validate the new candidate. Platform/provider observations remain limited to their recorded configuration.
13
+
14
+ The candidate retains the seven inputs, fixed profile, Fail Closed behavior, Result/Evidence v2 and `verify_checkout` / `verify_research` / legacy `verify` meanings described below. Candidate implementation, completed validation, publication readiness and completed publication are separate states. RubyGems publication, a public tag and GitHub Release await a separate Owner decision. Real Issuer trust and Host production GO remain separate and HOLD.
15
+
16
+ ## Published 0.2.0 API
17
+
18
+ [0.2.0 is published on RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.2.0). The published artifact and final packaging observation are identified below; 0.1.0 and earlier candidate evidence retain their historical identities.
19
+
20
+ `verify_checkout(**inputs)` delegates directly to `ResearchResult.verify(**inputs)` without input transformation. It requires the same seven inputs listed below (six original Strings and externally supplied integer Unix seconds), fixed profile, bounds and trusted Host preconditions. `verify_research` is retained unchanged without deprecation warnings; `verify(presentation_json:)` remains syntax-only and never produces successful Evidence.
21
+
22
+ Both full entries preserve Result/ResearchResult, status/code and immutable Evidence v2. Missing or unknown keywords return `:unavailable` / `:research_verification_unavailable`, `success? == false`, `evidence == nil`. Positional arguments or invalid keyword expansion can raise before entry; exceptions and missing results never authorize an operation. Success remains `:verified_research` / `:scoped_research_verified`, checked facts rather than Host ALLOW. No profile, trust, revocation, Host or payment responsibility is broadened.
23
+
24
+ ## Limited prior 0.2.0 candidate observation
25
+
26
+ [PR #213](https://github.com/cuichangquan/ap2-mandate-verifier/pull/213) records a separately approved build/install/audit at source HEAD `771eebb1094c19931aadafd32feaa70e2caa48f6` (same tree as merged main `9b981be68a1abaf318a7ae78497b3d74d8aefdda`). The retained local candidate was 32,256 bytes, SHA256 `0a126e170e482fea5138865d658f4c21687dc238e595236456f687ceb8aab211`; it is not a published download or this document's new artifact.
27
+
28
+ The limited Debian 12/arm64 observation used MRI 4.0.9 and the fixed Gem dependencies, OpenSSL library 3.0.22 / OS package `libssl3:arm64 3.0.22-1~deb12u2`. All 13 payload files matched source/archive/installed bytes, ordinary RubyGems require loaded 10 product Ruby files, and 118 logical cases passed: research42 + checkout42 + unavailable24 + legacy7 + input rejection2 + constructor rejection1. Saved inputs/independent expected values were reused; source190/885 were not rerun in this attempt. Earlier auxiliary-diagnostic STOP records remain preserved in PR #213.
29
+
30
+ This is an additional bounded observation, not adoption of Debian as a supported platform or proof of general runtime security, symbol binding, whole-wire accounting or resource performance. The 0.1.0 baseline and historical evidence below retain their own artifact identities. README.md and this contract are packaged; editing them creates different candidate bytes. The preparation-time NOT_RUN statement applied before the separately approved final observation below; prior candidate results were not reused as validation of the final bytes. Real Issuer trust/revocation, actual Host operation, performance and production GO remain HOLD.
31
+
32
+ ## Published 0.2.0 artifact and final observation
33
+
34
+ Published 2026-10-30 06:43:10 UTC, verified 06:44:48 UTC: owner `cuichangquan`, version `0.2.0`, platform `ruby`, non-prerelease. Official RubyGems SHA, distributed Gem and retained Gem matched: **33,280 bytes**, SHA256 `9a52e802de5a0564c34d198f4c4ad2c2b60791a8f1eb6e31db14c49e28e91f16`. Source `9b2e28d91fc4886722de7b9c39a5422e966953a9`, tree `a7739f966416bdbc18cfee266efc93223a587407`.
35
+
36
+ This final candidate separately passed the limited Debian 12/arm64 / MRI 4.0.9 observation: all 13 payload files matched source/archive/installation, 10 product Ruby files loaded through ordinary require, and 118 installed cases passed (42 research +42 checkout +24 unavailable +7 legacy +2 invalid inputs +1 constructor). Fixed dependencies and saved inputs/expected values were reused; source190/885 were NOT_RUN in this packaging step. Final report SHA256 `4348837cc153c65633e36c83c7939540819f164f43588d8140656e5ab50c2ccd`; publication receipt SHA256 `4b8264c5b990b10ad76a3fa3f01fc4ca94e6a828664ab3cefe11e6792c94a139`. These identify retained local records, not public downloads.
37
+
38
+ Publication does not expand supported-platform guarantees or establish real Issuer trust, revocation, actual Host operation, performance, production GO or Phase 2-B. The published Gem's documents are the pre-publication snapshot. Repository-only follow-up edits do not alter its bytes and require no rebuild; rebuilt artifacts do not inherit its validation. GitHub source archives differ from the RubyGems Gem. See [current status](PROJECT_STATUS.md#020公開済み--現在の配布状態).
39
+
8
40
  ## Verification contract
9
41
 
10
42
  Preserve `verify_research`, its seven keyword inputs, existing status/code and Evidence v2 identifiers, and legacy APIs' non-success behavior. No API rename, new trust enrollment, remote lookup, DB or payment operation is added. Fixed AP2 commit b4587ac1d055888a73b4b21750973cffba961793 and the exact profile v1 body/hash, seven supported shapes, ES256/P256 and existing bounds remain unchanged.
@@ -16,7 +48,7 @@ Evidence is immutable checked facts in the same trusted Ruby process, not ALLOW
16
48
  No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds. Issuance, presentation generation, Receipt, Rails adapter, real payments and Host DB operations are outside this verifier.
17
49
  Supported-input semantics and existing API/status/code/Evidence contracts must not change silently. Security-driven acceptance narrowing requires impact/reason/migration disclosure; breaking required-field/profile/API changes must be explicit. Dependency updates are not automatically compatible.
18
50
 
19
- The proposed baseline remains MRI4.0.9 plus JSON2.19.9/JWT3.3.0/base640.3.0/OpenSSL gem4.0.2/Digest3.2.1, with the exact observed MBA arm64-darwin25 and Ubuntu24.04/x86_64 configurations. RubyGems version constraints do not enforce MRI/OS/provider identity. All OS versions, other engines/architectures and arbitrary provider updates are not supported by past observations.
51
+ The published 0.2.0 and historical baseline below is MRI4.0.9 plus JSON2.19.9/JWT3.3.0/base640.3.0/OpenSSL gem4.0.2/Digest3.2.1, with the exact observed MBA arm64-darwin25 and Ubuntu24.04/x86_64 configurations. RubyGems version constraints do not enforce MRI/OS/provider identity. All OS versions, other engines/architectures and arbitrary provider updates are not supported by past observations.
20
52
  Historical D3 observed MBA component identities and four selected crypto symbol sources; OS dyld hashes/all symbol bindings/global runtime security remain unproved. JSON2.19.9 official IO-buffer fix/tag/source identity is adopted static evidence; inconsistent GHSA patched-version metadata remains recorded. Neither observation is global S3 PASS. The earlier R1 archive subsequently passed Mac/Ubuntu packaging checks. It is a different archive; see the separate release-package record for current bytes and observations.
21
53
 
22
54
  Initial maintenance contact: Owner cuichangquan via repository Issues for ordinary bugs and private vulnerability reporting for vulnerabilities. No secrets, real Mandates or personal data in reports. Maintain only the latest patch in the selected initial stable series; no prerelease/old-series backport, fixed support years, response/fix/disclosure deadline or 24/7 promise.
@@ -24,7 +56,7 @@ Manual dependency/provider review is adopted monthly, on relevant advisories and
24
56
 
25
57
  ## Existing API/limits and historical evidence baseline
26
58
 
27
- The API/limit specification below preserves the existing contract. All pre2/pre3/MBA409/R1 observations are historical, not proof of a newly built archive. Exact current source/archive/installed identities and observations are recorded externally in [release-package evidence](../research/stable010_release_linux_package/README.md); no old result is relabelled.
59
+ The API/limit specification below preserves the existing contract. All pre2/pre3/MBA409/R1 observations are historical, not proof of a newly built archive. Historical release source/archive/installed identities and observations are recorded in [release-package evidence](../research/stable010_release_linux_package/README.md); the 0.2.1 candidate has its separate compatibility record above. No old result is relabelled.
28
60
 
29
61
  ## Supported proposition and environment
30
62
 
@@ -39,7 +71,7 @@ constraints, USD/EUR/JPY and empty links only. Other profiles/forms are rejected
39
71
  not accepted through a generic AP2/Schema fallback. This synthetic registered
40
72
  profile does not establish real Issuer enrollment or general interoperability.
41
73
 
42
- The supported baseline is MRI Ruby4.0.9 and JSON2.19.9/JWT3.3.0/base640.3.0/
74
+ The historical baseline described in this section is MRI Ruby4.0.9 and JSON2.19.9/JWT3.3.0/base640.3.0/
43
75
  OpenSSL gem4.0.2/Digest3.2.1, all fixed in the gemspec. These versions must be
44
76
  available through normal RubyGems/Bundler resolution; source-loadpath bypass
45
77
  or dependency replacement is not a compatibility contract. MBA409-20261023-BUILD02
@@ -125,4 +125,7 @@ module AP2MandateVerifier
125
125
  # All older methods continue to return non-success Result values.
126
126
  def self.verify_research(**inputs) = ResearchResult.verify(**inputs)
127
127
 
128
+ # Fixed-profile checkout verification; Evidence is not Host ALLOW or payment permission.
129
+ def self.verify_checkout(**inputs) = ResearchResult.verify(**inputs)
130
+
128
131
  end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ap2_mandate_verifier
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - AP2 Mandate Verifier contributors
8
8
  bindir: bin
9
9
  cert_chain: []
10
- date: 1980-01-02 00:00:00.000000000 Z
10
+ date: 2026-10-30 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
13
  name: json
@@ -80,8 +80,9 @@ dependencies:
80
80
  - !ruby/object:Gem::Version
81
81
  version: 3.2.1
82
82
  description: Stateless verification of the fixed AP2 profile with immutable Evidence
83
- using the existing verify_research API. Requires trusted Host inputs and the documented
84
- runtime; not Host authorization, payment permission or general AP2 conformance.
83
+ using verify_checkout and the retained verify_research API. Requires trusted Host
84
+ inputs and the documented runtime; not Host authorization, payment permission or
85
+ general AP2 conformance.
85
86
  executables: []
86
87
  extensions: []
87
88
  extra_rdoc_files: []
@@ -108,16 +109,19 @@ require_paths:
108
109
  - lib
109
110
  required_ruby_version: !ruby/object:Gem::Requirement
110
111
  requirements:
111
- - - '='
112
+ - - ">="
113
+ - !ruby/object:Gem::Version
114
+ version: 3.4.12
115
+ - - "<"
112
116
  - !ruby/object:Gem::Version
113
- version: 4.0.9
117
+ version: '4.1'
114
118
  required_rubygems_version: !ruby/object:Gem::Requirement
115
119
  requirements:
116
120
  - - ">="
117
121
  - !ruby/object:Gem::Version
118
122
  version: '0'
119
123
  requirements: []
120
- rubygems_version: 4.0.20
124
+ rubygems_version: 3.6.9
121
125
  specification_version: 4
122
126
  summary: Fixed-profile AP2 verification for Ruby
123
127
  test_files: []