ap2_mandate_verifier 0.3.0 → 0.5.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: 1367482ba612018a83790debee921f546003a7eabc0b43341602d9e3c1d4f9a6
4
- data.tar.gz: 92d43d757d99b941a8724a4e4f4a9bbe450ae1b5f297cb5b6ec86c0007c915ba
3
+ metadata.gz: 1e3f167538858b19e86097908f19d31235a3d6bf1f2478b13d0a3aa049ab527b
4
+ data.tar.gz: 818e4c88efa929adcc209710c6d8e042a601820589a80bf20e7115db2700f00e
5
5
  SHA512:
6
- metadata.gz: 444098518c421863e6a4ffaf41c33312f6634d88ddad3ad11402613bf068cbfbf0740351de43a4a5d1a8571c3d0b349d7e4697d3afa5c297fb1c08427683f8c8
7
- data.tar.gz: 5bd155bc56710aea9a84a70d0c0c7342fa26b0d0523694691b06e727a16977dd42d5257f08f8f2dc71d27a231409fa5bc11dd0d8770282d91797b16a56dc7987
6
+ metadata.gz: fe38d275af6ada51fbc70b2dbbf8d7d1c822d49304f839e0b9ca2b575b24ccd2e123c3b04c58862b30e90b375afe28c0c34a4376841f69f07e6c8438fc0abd1a
7
+ data.tar.gz: 9a0cf42696c264f27b62b674fe6ba1c10c5916434cc3b83b8582e15d78c103a9ea4dee976610f09bb3c84c8fe2a7b6b9c2152b17b637fd8359c0738d2f2b24b9
data/README.md CHANGED
@@ -1,225 +1,140 @@
1
- # AP2 Mandate Verifier — 0.3.0 candidate
1
+ # AP2 Mandate Verifier — 0.4.0
2
2
 
3
- The unpublished 0.3.0 candidate adds `InputBuilder`: map authenticated business records once, prepare and persist a challenge, then supply independent current state to the complete verifier. No hand-written trust/selection/Host JSON or hashes are needed. Start with the [runnable business-data example and Rails mapping](docs/INPUT_BUILDER.md). Existing seven-input APIs remain supported. Published installation below remains 0.2.1 until release approval.
3
+ [日本語](README.ja.md)
4
4
 
5
- [Japanese / 日本語](README.ja.md)
5
+ 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.**
6
6
 
7
- 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.
7
+ `InputBuilder` converts business records into verification inputs: it creates the Gem-specific trust/selection/Host JSON, fingerprints and original-wire digests for you. You still choose whom to trust and supply the expected order, challenge state and clock. The Gem is Rails-independent and performs no network, database or payment operations.
8
8
 
9
- ## Start with the local demo
9
+ ## Try the local demo
10
10
 
11
- 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.
11
+ The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.4.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 is local-only; it does not issue real challenges, consume nonces or execute purchases.
12
12
 
13
- For a Japanese walkthrough of the three demo scenarios, see the [Zenn article](https://zenn.dev/ccq/articles/7f9643f96fe5c7).
13
+ ## Install
14
14
 
15
- ## Choose your starting point
16
-
17
- | Route | Start here |
18
- | --- | --- |
19
- | 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. |
20
- | Ruby without the demo: MRI 3.4.12 or 4.0.9 | Follow [installation](#distribution-and-installation), then the [saved synthetic example](#try-the-saved-synthetic-example) below. |
21
-
22
- 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.
23
-
24
- ## Distribution and installation
25
-
26
- [0.2.1 is published on RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.2.1). This is the fixed-profile, verifier-only stable release; the research prerelease pre3 is a separate artifact.
27
-
28
- Use an MRI 3.4.12 or 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.
15
+ Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
29
16
 
30
17
  ```sh
31
- ruby --version # MRI 3.4.12 or MRI 4.0.9
32
- gem install ap2_mandate_verifier --version 0.2.1
18
+ gem install ap2_mandate_verifier --version 0.4.0
33
19
  ```
34
20
 
35
- Bundler Gemfile:
21
+ Or add to your Gemfile:
36
22
 
37
23
  ```ruby
38
- gem "ap2_mandate_verifier", "= 0.2.1"
24
+ gem "ap2_mandate_verifier", "= 0.4.0"
39
25
  ```
40
26
 
41
- 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.
42
- 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.
43
-
44
- ## Ruby 3.4.12 compatibility and published artifact
45
-
46
- 0.2.1 formally supports 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 version or another engine supported.
47
-
48
- Both versions were measured on Debian 12/arm64 with official Ruby bookworm images: 885 source regressions, 190 additional checkout cases and 7 metadata cases passed per Ruby. The same final Gem passed ordinary installation, all 13 payload-file comparisons, 10 normally loaded product files and 118 installed cases on each version. Exact providers and evidence are in the [compatibility record](docs/RUBY_3_4_12_COMPATIBILITY.md). Historical macOS/Ubuntu observations are separate and do not establish 0.2.1 compatibility there.
49
-
50
- Published 2026-10-30 11:51:55.894 UTC; verified 11:53:55 UTC. Official RubyGems metadata, distribution bytes and the retained final Gem matched: **34,816 bytes**, SHA256 `a4ab7e0f6c9bd87355695369374f8e6e2dad104fb673700e9f616053afe6e114`, source `5a02bc3a192e16aa3628cf7899617623b0aed78c`. Owner `cuichangquan`, platform `ruby`, non-prerelease, not yanked at verification. The [v0.2.1 GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.2.1) uses that exact source tag.
51
-
52
- The Gem's packaged README/contract retain their preparation snapshot. These repository updates do not rebuild or replace the published bytes. GitHub source archives differ from the RubyGems Gem. Seven inputs, fixed profile, Fail Closed, Result/Evidence v2 and existing API meanings remain unchanged; publication does not establish Host production GO.
53
-
54
- ## Verification APIs: 0.2.1 and compatibility
55
-
56
- **The installation commands and saved example use published 0.2.1 and its recommended `verify_checkout` entry.** Existing 0.1.0 applications can continue using `verify_research`; it remains available in 0.2.1 without a deprecation warning. Installing 0.1.0 does not provide `verify_checkout`.
27
+ 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).
57
28
 
58
- | Entry | Availability and contract |
59
- | --- | --- |
60
- | `verify_checkout(**inputs)` | Recommended full-verification entry since 0.2.0, retained in 0.2.1. Delegates directly to `ResearchResult.verify` without changing inputs or the verification pipeline. |
61
- | `verify_research(**inputs)` | Full-verification entry in published 0.1.0; retained unchanged in v0.2.1, without a deprecation warning. |
62
- | `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. |
29
+ ## Merchant signing and Receipt (unpublished 0.5.0 candidate)
63
30
 
64
- 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:
31
+ Create a signed checkout, then sign the application's explicit outcome. These
32
+ additive APIs are available from the candidate source, not published 0.4.0:
65
33
 
66
34
  ```ruby
67
- result = AP2MandateVerifier.verify_checkout(
68
- trust_json: full.fetch("trust_json"),
69
- selection_json: full.fetch("selection_json"),
70
- host_json: full.fetch("host_json"),
71
- root_presentation: full.fetch("root_presentation"),
72
- terminal_jws: full.fetch("terminal_jws"),
73
- host_checkout_jws: full.fetch("host_checkout_jws"),
74
- verified_at: full.fetch("verified_at")
75
- )
35
+ signing = AP2MandateVerifier::CheckoutJWT
36
+ signed = signing.sign(checkout: checkout, signer: signing.es256_signer(private_key: key),
37
+ public_key_pem: key.public_to_pem)
38
+ # Retain signed.jwt unchanged; use it as InputBuilder's host_checkout_jws.
39
+ receipt = AP2MandateVerifier::CheckoutReceipt.sign(closed_sd_jwt: received_closed_sd_jwt,
40
+ issuer: "shop", outcome: "Error", error: "declined", error_description: "Application declined",
41
+ issued_at: now, signer: signing.es256_signer(private_key: key), public_key_pem: key.public_to_pem)
76
42
  ```
77
43
 
78
- 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.
79
-
80
- 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.
81
-
82
- ## Supported contract
83
-
84
- - AP2 pinned source `b4587ac1d055888a73b4b21750973cffba961793`, registered profile `ap2.checkout.single_merchant_sku` v1: exact body/hash and seven supported shapes.
85
-
86
- - ES256/P256, Open1→Closed1, three fixed disclosure positions, one Merchant/SKU/line, USD/EUR/JPY and empty links; unknown/unsupported forms are rejected.
87
-
88
- - 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.
89
-
90
- - 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.
44
+ Receipt verification separately checks a trusted public key, expected issuer,
45
+ explicit time window and original closed-Mandate reference. An authentic Error
46
+ Receipt has `verified? == true` and `purchase_succeeded? == false`.
47
+ See the [complete API example, supported wire shape and SDK differences](docs/MERCHANT_SIGNING.md).
91
48
 
92
- See [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for exact required shapes, bounds and failure codes.
49
+ ## A small InputBuilder example
93
50
 
94
- ## Environment, compatibility and maintenance
95
-
96
- The supported MRI versions are 3.4.12 and 4.0.9 with fixed dependencies; current 0.2.1 measurements cover the exact Debian 12/arm64 configurations in the compatibility record above. Earlier MRI 4.0.9 MBA/macOS arm64 and Ubuntu 24.04/x86_64 observations retain their historical scope. Distinguish [historical release-package/provider evidence](research/stable010_release_linux_package/README.md) from the current artifact. Other OS versions, engines, architectures and arbitrary provider updates are not covered.
97
-
98
- 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.
99
-
100
- 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.
101
-
102
- ## Try the saved synthetic example
103
-
104
- 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.
105
-
106
- ```sh
107
- set -eu
108
- curl --fail --location --proto '=https' --proto-redir '=https' \
109
- --output AP2_RESEARCH_INPUTS.json \
110
- https://raw.githubusercontent.com/cuichangquan/ap2-mandate-verifier/f6d4f83d396b75505256dba5769a54a8f065eeea/research/stage15/results/R3/INPUTS.json
111
- printf '%s\n' '41ad845a7ea82a9c7316c9ef11fb8ee5281453afafe2b4932c7217c1936562c1 AP2_RESEARCH_INPUTS.json' | shasum -a 256 -c -
112
- # Save the Ruby example below as research_example.rb, then:
113
- ruby research_example.rb
114
- ```
51
+ After installation, use a checkout of this repository. Save the following as `quick_start.rb` in its root and run `ruby quick_start.rb`. The JSON files under [`examples/input_builder/`](examples/input_builder/) contain explicit synthetic order/registration records and original signed Strings; they are not part of the installed Gem. Their fixed clock is intentional because the saved signatures expire. These are test inputs, not real enrollment or current production data.
115
52
 
116
53
  ```ruby
117
54
  require "ap2_mandate_verifier"
118
55
  require "json"
119
- require "digest"
120
-
121
- raw = File.binread("AP2_RESEARCH_INPUTS.json")
122
- expected = "41ad845a7ea82a9c7316c9ef11fb8ee5281453afafe2b4932c7217c1936562c1"
123
- raise "fixture checksum mismatch" unless Digest::SHA256.hexdigest(raw) == expected
124
-
125
- full = JSON.parse(raw).fetch("FULL")
126
- inputs = {
127
- trust_json: full.fetch("trust_json"),
128
- selection_json: full.fetch("selection_json"),
129
- host_json: full.fetch("host_json"),
130
- root_presentation: full.fetch("root_presentation"),
131
- terminal_jws: full.fetch("terminal_jws"),
132
- host_checkout_jws: full.fetch("host_checkout_jws"),
133
- verified_at: full.fetch("verified_at")
134
- }
135
-
136
- result = AP2MandateVerifier.verify_checkout(**inputs)
137
- puts "status=#{result.status} code=#{result.code}"
138
- if result.success?
139
- checked_facts = result.evidence.to_h # Detached, deeply frozen in-process facts.
140
- puts "Scoped verification succeeded; this is NOT purchase authorization."
141
- # No payment, order update or nonce consumption is performed here.
142
- else
143
- raise "Verification did not succeed; stop."
56
+ require "tmpdir"
57
+
58
+ builder = AP2MandateVerifier::InputBuilder
59
+ fixtures = File.join(__dir__, "examples/input_builder")
60
+ read = ->(name) { JSON.parse(File.binread(File.join(fixtures, "#{name}.json"))) }
61
+ trust_at = ->(now) do
62
+ builder.trust(snapshot: read.call("trust_snapshot"), tenant_id: "synthetic-tenant",
63
+ issuer: {"identity" => "issuer", "purpose" => "checkout", "key_ref" => "issuer-1"},
64
+ agent: {"identity" => "agent", "purpose" => "checkout", "key_ref" => "agent-1"},
65
+ merchant: {"identity" => "shop", "purpose" => "checkout", "key_ref" => "merchant-1"},
66
+ verified_at: now)
67
+ end
68
+ wires = read.call("signed_wires").transform_keys(&:to_sym) # Preserve String bytes.
69
+
70
+ # Before issuance: independent order/trust and Host-chosen challenge information.
71
+ prepared = builder.prepare(trust: trust_at.call(1_800_000_000),
72
+ order: read.call("order"), root_presentation: wires.fetch(:root_presentation),
73
+ host_checkout_jws: wires.fetch(:host_checkout_jws),
74
+ challenge_id: "synthetic-challenge", nonce: "n", issuer_id: "synthetic-host",
75
+ not_before: 1_799_998_000, not_after: 1_800_002_000)
76
+
77
+ Dir.mktmpdir do |directory|
78
+ record = File.join(directory, "challenge.json")
79
+ File.binwrite(record, prepared) # Demo persistence; the Host owns real storage.
80
+
81
+ # Later: load the saved bytes, and independently obtain current order/trust.
82
+ now = 1_800_000_000 # Supplied synthetic clock, not a production time source.
83
+ result = builder.verify(trust: trust_at.call(now),
84
+ saved_challenge: builder.restore(saved_challenge: File.binread(record)),
85
+ order: read.call("order"), **wires,
86
+ expected_challenge_issuer_id: "synthetic-host",
87
+ clock_source_id: "fixed-synthetic-clock", verified_at: now)
88
+ puts "#{result.status}/#{result.code}; evidence=#{!result.evidence.nil?}"
89
+ raise "Verification did not succeed; stop" unless result.success?
144
90
  end
145
91
  ```
146
92
 
147
- 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.
148
-
149
- ## Understanding the result
93
+ Expected for these unchanged synthetic inputs: `verified_research/scoped_research_verified; evidence=true`. This example models preparation, persistence and later verification in one process; it does not implement real issuance or atomic consumption. In an application, map authenticated registry/order records explicitly and preserve the original signed bytes. Structured business inputs use plain Ruby values with String keys, not ActiveRecord objects.
150
94
 
151
- | Outcome | `status` and predicate | Evidence and handling |
152
- | --- | --- | --- |
153
- | Successful scoped verification | `:verified_research`; `success? == true`; `code == :scoped_research_verified` | Present: checked facts, **not purchase authorization**. Host responsibilities still apply. |
154
- | Rejected | `:rejected`; `rejected? == true` | Absent (`nil`). Stop; inspect `result.code` for the rejection reason. |
155
- | Verification unavailable | `:unavailable`; `unavailable? == true` | Absent (`nil`). Stop; a dependency or verification failure does not by itself establish that the input is invalid. |
95
+ Do not call `prepare` again during verification or update saved hashes/references to match current values. Changed orders, trust or signed bytes must remain detectable. Persisted trust JSON can be loaded with `restore_trust` without reserializing it. The [complete example](examples/input_builder.rb) includes normal/tampered/expired cases; the [input guide](docs/INPUT_BUILDER.md) explains the business fields, exact restoration and Rails model mapping.
156
96
 
157
- 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.
97
+ ## Results and responsibility boundaries
158
98
 
159
- ## Real inputs and responsibility boundaries
160
-
161
- | Keyword | Input contract |
99
+ | Result | Meaning and next step |
162
100
  | --- | --- |
163
- | `trust_json` | Original JSON String for authenticated Host trust snapshot, profile and public-key registration. |
164
- | `selection_json` | Independently selected tenant, profile version and role/identity/purpose/key references. |
165
- | `host_json` | Authenticated current order binding, issued challenge, expected issuer and clock identity. |
166
- | `root_presentation` | Original signed Root presentation String, preserving disclosure order and trailing `~`. |
167
- | `terminal_jws` | Original Agent terminal compact JWS String. |
168
- | `host_checkout_jws` | Original Merchant Checkout compact JWT String frozen by the Host. |
169
- | `verified_at` | Integer Unix seconds supplied by an external trusted clock. |
170
-
171
- 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.
172
-
173
- 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.
174
-
175
- 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.
176
-
177
- 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.
178
-
179
- ## Exclusions and safe stopping
180
-
181
- 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.
182
-
183
- 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.
184
-
185
- ## Evidence and history
101
+ | `:verified_research` / `:scoped_research_verified`, `success? == true` | Immutable Evidence contains checked facts for the fixed profile. The Host must still decide whether to authorize the purchase. |
102
+ | `:rejected`, `rejected? == true` | No Evidence. Stop and inspect `result.code`. |
103
+ | `:unavailable`, `unavailable? == true` | No Evidence. Stop; a dependency or processing failure is not proof of invalid business data. |
186
104
 
187
- 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 [historical 0.2.0 publication record](docs/PROJECT_STATUS.md#020公開済み--現在の配布状態).
105
+ On failure, inspect supplemental check candidates. Successful results have no failure diagnostic.
188
106
 
189
- 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.
190
-
191
- 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.
192
-
193
- 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.
194
-
195
- [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.
196
-
197
- [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).
198
-
199
- ## Illustrated concepts (Japanese diagrams)
200
-
201
- 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.
202
-
203
- ### AP2 overview (Japanese)
204
-
205
- ![AP2 overview (Japanese)](docs/assets/ap2-overview.png)
107
+ ```ruby
108
+ if (diagnostic = result.diagnostic)
109
+ puts diagnostic.to_h(locale: :en) # :ja for Japanese
110
+ end
111
+ ```
206
112
 
207
- ### Delegation and Host responsibility boundaries (Japanese)
113
+ `stage / field / reason / hint` are guidance; they do not change status/code or the verdict. Unknown fields/causes are not asserted. See the [diagnostic guide](docs/DIAGNOSTICS.md).
208
114
 
209
- ![Delegation and Host responsibility boundaries (Japanese)](docs/assets/ap2-delegation-trust-flow.png)
115
+ Exceptions, process failure and missing results also never authorize an operation. Do not log raw inputs/nonces or treat serialized Evidence as an authenticated credential.
210
116
 
211
- ### Mandate anatomy (Japanese)
117
+ 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.
212
118
 
213
- ![Mandate anatomy (Japanese)](docs/assets/mandate-anatomy.png)
119
+ Supported scope is the fixed `ap2.checkout.single_merchant_sku` profile v1: ES256/P256, one Merchant/SKU/cart line, USD/EUR/JPY and the documented disclosure shapes. Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer interoperability, signing/Receipt generation, Rails adapters, DB/payment execution and numeric performance guarantees are outside this release. Real Issuer/Host production GO and Phase 2-B remain separate HOLDs.
214
120
 
215
- ### SD-JWT and delegation concepts (Japanese)
121
+ ### Which API should I use?
216
122
 
217
- ![SD-JWT and delegation concepts (Japanese)](docs/assets/sd-jwt-delegation-chain.png)
123
+ | Entry | Role |
124
+ | --- | --- |
125
+ | `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.4.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
126
+ | `verify_checkout(**inputs)` | Direct complete verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
127
+ | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
128
+ | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
218
129
 
219
- ### Fail-closed attack patterns and Host replay prevention (Japanese)
130
+ Malformed assembly arguments, including missing keywords, to `InputBuilder.verify` return `:rejected / :invalid_host_context`. Assembly dependency/unexpected failures return `:unavailable / :research_verification_unavailable`; results from the complete core retain their codes. In contrast, missing/unknown keywords to the direct `verify_checkout` / `verify_research` entries return `:unavailable / :research_verification_unavailable`. Every such failure has `success? == false` and `evidence == nil`. See [the exact contract](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs) for shapes, bounds and Ruby argument-binding caveats.
220
131
 
221
- ![Fail-closed attack patterns and Host replay prevention (Japanese)](docs/assets/attack-patterns-fail-closed.png)
132
+ ## More detail
222
133
 
223
- ## License
134
+ - [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).
135
+ - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
136
+ - [Published 0.4.0 release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.4.0), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
137
+ - [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.
138
+ - [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.
224
139
 
225
140
  MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,76 @@
1
+ # 失敗時の診断(公開済み 0.4.0)
2
+
3
+ Gem内部を追わず、失敗した検査と次の確認候補を取得できます。診断は補助情報です。
4
+ 既存呼び出し、status/code、固定profile、Fail Closed、非成功時のEvidenceなし契約は不変です。
5
+ 成功時のdiagnosticはnilです。診断処理が失敗してもnilとなり、検証結果は変わりません。
6
+ ヒントから購入・決済の許可を判断しないでください。
7
+
8
+ ## Before / After
9
+
10
+ ```ruby
11
+ result = AP2MandateVerifier::InputBuilder.verify(**host_arguments)
12
+ # 従来の利用方法も引き続き有効
13
+ puts "#{result.status}/#{result.code}"
14
+ # 追加の診断
15
+ if (diagnostic = result.diagnostic)
16
+ puts diagnostic.to_h(locale: :ja) # 英語は :en(既定)
17
+ # stage: :input_assembly, field: "order.currency",
18
+ # reason: :missing_required_field, hint: "文書記載の必須項目を…"
19
+ end
20
+ ```
21
+
22
+ 診断は変更不能なDiagnosticオブジェクトです。stage、field、reason、hint(locale:)と
23
+ 変更不能なHashを返すto_h(locale:)を利用できます。diagnostic[:stage]等も利用可能です
24
+ (hintは英語)。未対応localeは英語になります。機械判読識別子は翻訳せず、アプリ独自の
25
+ 翻訳も可能です。ヒントの文面は固定契約ではないので文字列一致で判定しないでください。
26
+ 今後、診断の詳細が追加される場合があります。検証結果には従来のstatus/codeを使います。
27
+
28
+ 純粋なBuilder補助メソッドtrust・restore_trust・prepare・restore・inputsは、従来どおり
29
+ 不備時にInputBuilder::Invalid(ArgumentErrorの子クラス)を送出します。
30
+ rescueしてerror.diagnosticを確認できます。依存障害の例外型は維持します。
31
+ 例外を成功扱いせず、入力原文・任意の依存例外メッセージ・例外チェーンをログに出さないでください。
32
+
33
+ | stage / field / reason | 意味と次の確認 |
34
+ | --- | --- |
35
+ | input_assembly / order.currency / missing_required_field | 独立した現在の注文情報から通貨を取得してください。 |
36
+ | input_assembly / order.expected_total / invalid_type | 価格の表示文字列ではなく最小単位のIntegerを渡してください。 |
37
+ | input_assembly / order / unknown_field | 文書の注文項目一覧と照合してください。未知項目名は表示しません。 |
38
+ | input_assembly / saved_challenge / unsupported_saved_format | 保存形式とprofileの版の対応を確認してください。受理させるために保存済みの版を書き換えないでください。 |
39
+ | host_binding / nil / host_binding_mismatch | 保存記録と独立した現在の注文・trust・期待issuer・原文digestを比較してください。具体的な不一致項目は特定していません。 |
40
+ | purchase_binding / nil / invalid_purchase_time | 独立した時計、署名済みOpen・Closedの有効期間、terminal proofの時刻窓を確認してください。どの時刻が誤りかは断定しません。 |
41
+ | verification_unavailable / nil / 既存code | 検証を完了できません。対応依存・実行環境を確認し、業務データ不正と決めつけないでください。 |
42
+ | verification / nil / undetermined | 安全に詳しく診断できません。API契約とstatus/codeを確認してください。 |
43
+
44
+ stageは失敗検査の分類であり、実行経路の証明ではありません。既存invalid_root_signatureは
45
+ Root以外にAgent・Merchant署名でも使われるため、signature_verificationと表示します。
46
+ 犯人や根本原因を断定しません。必須不足を未知項目より先に表示します。グラフ上限、parse、
47
+ 下位検査等ではfieldがnil・理由が汎用になる場合があります。診断は一件だけで、後続検査は
48
+ 未実行の場合があります。
49
+
50
+ 既存Resultの全コードに対し、JSON・バイト、署名、Root開示、購入・委任、制約・schema、
51
+ trust選択、Host・challengeの確認候補を提供します。旧unverifiedには保証範囲の案内を返し、
52
+ 完全検証成功にはしません。工程・項目・理由・ヒントは既知候補のみです。値、未知の項目名、
53
+ 署名原文、鍵、nonce、個人情報、stack traceは保持・表示しません。診断はEvidenceではなく、
54
+ 元入力の再構築もできません。
55
+
56
+ ## 公開版をローカルで試す
57
+
58
+ 対応MRI 3.4.12または4.0.9と固定依存を備えた環境で、公開済み0.4.0を通常導入し、
59
+ リポジトリのチェックアウトから例を実行してください。
60
+
61
+ ```sh
62
+ gem install ap2_mandate_verifier --version 0.4.0
63
+ ruby examples/input_builder.rb valid
64
+ ruby examples/input_builder.rb tampered
65
+ ruby examples/input_builder.rb expired
66
+ ruby examples/input_builder.rb missing_currency
67
+ ruby examples/input_builder.rb wrong_total_type
68
+ ruby examples/input_builder.rb unknown_order_field
69
+ ruby examples/input_builder.rb unsupported_saved_format
70
+ ```
71
+
72
+ 正常はEvidenceあり、改ざんはhost_binding_mismatch、期限切れはinvalid_purchase_timeです。
73
+ 後半4例はrejected / invalid_host_contextのまま、理由が順にmissing_required_field、invalid_type、
74
+ unknown_field、unsupported_saved_formatになります。合成fixtureの固定時刻を使います。
75
+ 業務データの対応・保存責務は[InputBuilderガイド](INPUT_BUILDER.ja.md)を参照してください。
76
+ Gemの公開は、実Issuer接続、本番購入許可、Phase 2-B移行を意味しません。
@@ -0,0 +1,88 @@
1
+ # Failure diagnostics (published 0.4.0)
2
+
3
+ Diagnostics help you inspect a failed check without reading gem internals. They
4
+ are supplemental: existing calls, status/code, fixed profile, Fail Closed and
5
+ non-success `evidence == nil` are unchanged. A successful result has
6
+ `diagnostic == nil`. A diagnostic failure also returns nil and cannot change a
7
+ verification result. Never make a payment/authorization decision from a hint.
8
+
9
+ ## Before / after
10
+
11
+ ```ruby
12
+ result = AP2MandateVerifier::InputBuilder.verify(**host_arguments)
13
+ # Before (still supported):
14
+ puts "#{result.status}/#{result.code}"
15
+ # After:
16
+ if (diagnostic = result.diagnostic)
17
+ puts diagnostic.to_h(locale: :en) # :ja for Japanese
18
+ # stage: :input_assembly, field: "order.currency",
19
+ # reason: :missing_required_field, hint: "Supply ..."
20
+ end
21
+ ```
22
+
23
+ `Diagnostic` is immutable, with `stage`, `field`, `reason`, `hint(locale: :en)`
24
+ and `to_h(locale: :en)` readers. `diagnostic[:stage]` etc. also work (English
25
+ hint). Unsupported locales fall back to English. Machine identifiers are not
26
+ translated; applications may translate them themselves. Hints are guidance,
27
+ not stable text for matching. New diagnostic detail may be added in later
28
+ versions. Continue to use status/code for the verifier outcome.
29
+
30
+ Pure Builder helpers (`trust`, `restore_trust`, `prepare`, `restore`, `inputs`)
31
+ still raise `InputBuilder::Invalid < ArgumentError` for malformed input. Rescue
32
+ it and inspect `error.diagnostic`; do not treat an exception as success.
33
+ Unavailable dependency errors retain their existing exception types. Do not log
34
+ raw inputs, arbitrary provider exception messages, or full exception chains.
35
+
36
+ ## What to check
37
+
38
+ | Diagnostic | Meaning and next check |
39
+ | --- | --- |
40
+ | `input_assembly / order.currency / missing_required_field` | Obtain currency from independent current order data. |
41
+ | `input_assembly / order.expected_total / invalid_type` | Pass an Integer in minor units, not a formatted price String. |
42
+ | `input_assembly / order / unknown_field` | Compare with documented order fields; the unknown name is deliberately withheld. |
43
+ | `input_assembly / saved_challenge / unsupported_saved_format` | Check saved format/profile version compatibility. Never edit the saved version to force acceptance. |
44
+ | `host_binding / nil / host_binding_mismatch` | Compare saved challenge with independent current order, trust, issuer and original wire digests. The exact mismatching member is not identified. |
45
+ | `purchase_binding / nil / invalid_purchase_time` | Check independent clock, signed Open/Closed validity and terminal proof window. The code does not establish which time source is wrong. |
46
+ | `verification_unavailable / nil / <existing code>` | Verification could not finish. Check supported dependencies/runtime; do not label business data invalid. |
47
+ | `verification / nil / undetermined` | No safe precise diagnosis is available. Inspect the API contract and status/code. |
48
+
49
+ A stage names a failed check category, not an attested execution trace. In
50
+ particular, the legacy `invalid_root_signature` code can arise when checking
51
+ Root, Agent or Merchant signatures: `signature_verification` deliberately does
52
+ not name a specific signer. No hint identifies a malicious actor or proves a
53
+ root cause. Missing fields take precedence over unknown fields. Bounded graph,
54
+ parse or lower-level validation failures may have `field == nil` and a generic
55
+ reason. Only one diagnostic is returned; later checks may not have run.
56
+
57
+ The catalog covers every existing Result code: JSON/byte checks, signatures,
58
+ Root disclosures, purchase/delegation binding, scoped schema/constraints,
59
+ trust selection and Host/challenge checks. Legacy `unverified` results receive
60
+ scope guidance, not full-verification success. Diagnostic fields, reasons and
61
+ hints come from a closed catalog. No values, arbitrary field names, signed
62
+ wires, public/private keys, nonce, PII or stack traces are retained or emitted.
63
+ The diagnostic is not Evidence and cannot reconstruct original inputs.
64
+
65
+ ## Try the published release locally
66
+
67
+ Normally install published 0.4.0 in an environment with supported MRI
68
+ (3.4.12 or 4.0.9) and pinned dependencies. Run the examples from a repository checkout:
69
+
70
+ ```sh
71
+ gem install ap2_mandate_verifier --version 0.4.0
72
+ ruby examples/input_builder.rb valid
73
+ ruby examples/input_builder.rb tampered
74
+ ruby examples/input_builder.rb expired
75
+ ruby examples/input_builder.rb missing_currency
76
+ ruby examples/input_builder.rb wrong_total_type
77
+ ruby examples/input_builder.rb unknown_order_field
78
+ ruby examples/input_builder.rb unsupported_saved_format
79
+ ```
80
+
81
+ The successful example returns Evidence, tampered returns
82
+ `host_binding_mismatch`, expired returns `invalid_purchase_time`, and the four
83
+ assembly examples return `rejected / invalid_host_context` with diagnostic
84
+ reasons `missing_required_field`, `invalid_type`, `unknown_field` and
85
+ `unsupported_saved_format`. Synthetic fixture clocks are intentional. See
86
+ [InputBuilder](INPUT_BUILDER.md) for data mapping and storage responsibilities.
87
+ Gem availability does not imply real Issuer interoperability, production
88
+ authorization or Phase 2-B GO.