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 +4 -4
- data/README.md +93 -178
- data/docs/DIAGNOSTICS.ja.md +76 -0
- data/docs/DIAGNOSTICS.md +88 -0
- data/docs/MERCHANT_SIGNING.md +149 -0
- data/docs/SUPPORT_CONTRACT.md +16 -3
- data/lib/ap2_mandate_verifier/checkout_jwt.rb +81 -0
- data/lib/ap2_mandate_verifier/checkout_receipt.rb +143 -0
- data/lib/ap2_mandate_verifier/diagnostic.rb +85 -0
- data/lib/ap2_mandate_verifier/input_builder.rb +67 -13
- data/lib/ap2_mandate_verifier/merchant_signature.rb +22 -0
- data/lib/ap2_mandate_verifier/research_result.rb +1 -0
- data/lib/ap2_mandate_verifier/result.rb +11 -1
- data/lib/ap2_mandate_verifier.rb +3 -0
- metadata +8 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1e3f167538858b19e86097908f19d31235a3d6bf1f2478b13d0a3aa049ab527b
|
|
4
|
+
data.tar.gz: 818e4c88efa929adcc209710c6d8e042a601820589a80bf20e7115db2700f00e
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: fe38d275af6ada51fbc70b2dbbf8d7d1c822d49304f839e0b9ca2b575b24ccd2e123c3b04c58862b30e90b375afe28c0c34a4376841f69f07e6c8438fc0abd1a
|
|
7
|
+
data.tar.gz: 9a0cf42696c264f27b62b674fe6ba1c10c5916434cc3b83b8582e15d78c103a9ea4dee976610f09bb3c84c8fe2a7b6b9c2152b17b637fd8359c0738d2f2b24b9
|
data/README.md
CHANGED
|
@@ -1,225 +1,140 @@
|
|
|
1
|
-
# AP2 Mandate Verifier — 0.
|
|
1
|
+
# AP2 Mandate Verifier — 0.4.0
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[日本語](README.ja.md)
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
9
|
+
## Try the local demo
|
|
10
10
|
|
|
11
|
-
The [
|
|
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
|
-
|
|
13
|
+
## Install
|
|
14
14
|
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
|
|
21
|
+
Or add to your Gemfile:
|
|
36
22
|
|
|
37
23
|
```ruby
|
|
38
|
-
gem "ap2_mandate_verifier", "= 0.
|
|
24
|
+
gem "ap2_mandate_verifier", "= 0.4.0"
|
|
39
25
|
```
|
|
40
26
|
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
|
|
49
|
+
## A small InputBuilder example
|
|
93
50
|
|
|
94
|
-
|
|
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 "
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
97
|
+
## Results and responsibility boundaries
|
|
158
98
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
| Keyword | Input contract |
|
|
99
|
+
| Result | Meaning and next step |
|
|
162
100
|
| --- | --- |
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
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
|
-
|
|
105
|
+
On failure, inspect supplemental check candidates. Successful results have no failure diagnostic.
|
|
188
106
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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
|
-

|
|
107
|
+
```ruby
|
|
108
|
+
if (diagnostic = result.diagnostic)
|
|
109
|
+
puts diagnostic.to_h(locale: :en) # :ja for Japanese
|
|
110
|
+
end
|
|
111
|
+
```
|
|
206
112
|
|
|
207
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
121
|
+
### Which API should I use?
|
|
216
122
|
|
|
217
|
-
|
|
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
|
-
|
|
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
|
-
|
|
132
|
+
## More detail
|
|
222
133
|
|
|
223
|
-
|
|
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移行を意味しません。
|
data/docs/DIAGNOSTICS.md
ADDED
|
@@ -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.
|