ap2_mandate_verifier 0.2.1 → 0.4.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 +73 -189
- data/docs/DIAGNOSTICS.ja.md +77 -0
- data/docs/DIAGNOSTICS.md +90 -0
- data/docs/SUPPORT_CONTRACT.md +23 -7
- data/lib/ap2_mandate_verifier/diagnostic.rb +85 -0
- data/lib/ap2_mandate_verifier/input_builder.rb +265 -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 +1 -0
- metadata +7 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d2630c74f49f2d59ee5895eb439c229c9269b202129e6574a3f2d627e302c565
|
|
4
|
+
data.tar.gz: 67055aafefb47cf5fe76cd3e5e78711de31496f715abe5e7fadf5e7f1fe293e2
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: b90c9022582083189cfc9fe8edbe641c2f4a51618c60a6ad877c8ce479cd70d1fcf84bf2520d1e79565cbb4cef457dc804ce28ab972dcb9a1f05ffa9f03f8d9a
|
|
7
|
+
data.tar.gz: 2aa4c0cbfbc879de935c15b93621fd3ac4f38990f9df414b0e322cceda844e5d226facfddb1678255908ff8cf2065b3640167fe6d619946bc729f3be8316c94b
|
data/README.md
CHANGED
|
@@ -1,228 +1,112 @@
|
|
|
1
|
-
# AP2 Mandate Verifier — 0.
|
|
1
|
+
# AP2 Mandate Verifier — 0.3.0
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Unreleased 0.4.0 candidate:** adds `result.diagnostic` with stage, safe field, reason and English/Japanese guidance. See the [diagnostic guide](docs/DIAGNOSTICS.md). Ordinary installation below still selects published 0.3.0; use the guide’s local candidate path to try diagnostics.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[日本語](README.ja.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
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.**
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
`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.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Try the local demo
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.3.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. Compare synthetic normal, tampered and expired cases, including actual status/code and Evidence presence. It is local-only; it does not issue real challenges, consume nonces or execute purchases.
|
|
14
14
|
|
|
15
|
-
|
|
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.
|
|
15
|
+
## Install
|
|
25
16
|
|
|
26
|
-
|
|
17
|
+
Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
|
|
27
18
|
|
|
28
19
|
```sh
|
|
29
|
-
|
|
30
|
-
gem install ap2_mandate_verifier --version 0.2.0
|
|
20
|
+
gem install ap2_mandate_verifier --version 0.3.0
|
|
31
21
|
```
|
|
32
22
|
|
|
33
|
-
|
|
23
|
+
Or add to your Gemfile:
|
|
34
24
|
|
|
35
25
|
```ruby
|
|
36
|
-
gem "ap2_mandate_verifier", "= 0.
|
|
26
|
+
gem "ap2_mandate_verifier", "= 0.3.0"
|
|
37
27
|
```
|
|
38
28
|
|
|
39
|
-
|
|
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.
|
|
45
|
-
|
|
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.
|
|
47
|
-
|
|
48
|
-
After obtaining the prepared candidate Gem and checking its SHA256 against that record, install it in your chosen isolated environment:
|
|
49
|
-
|
|
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
|
-
```
|
|
54
|
-
|
|
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.
|
|
56
|
-
|
|
57
|
-
## Verification APIs: 0.2.0 and compatibility
|
|
58
|
-
|
|
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`.
|
|
60
|
-
|
|
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. |
|
|
66
|
-
|
|
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.
|
|
92
|
-
|
|
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.
|
|
94
|
-
|
|
95
|
-
See [SUPPORT_CONTRACT](docs/SUPPORT_CONTRACT.md) for exact required shapes, bounds and failure codes.
|
|
96
|
-
|
|
97
|
-
## Environment, compatibility and maintenance
|
|
29
|
+
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).
|
|
98
30
|
|
|
99
|
-
|
|
31
|
+
## A small InputBuilder example
|
|
100
32
|
|
|
101
|
-
|
|
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
|
|
106
|
-
|
|
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.
|
|
108
|
-
|
|
109
|
-
```sh
|
|
110
|
-
set -eu
|
|
111
|
-
curl --fail --location --proto '=https' --proto-redir '=https' \
|
|
112
|
-
--output AP2_RESEARCH_INPUTS.json \
|
|
113
|
-
https://raw.githubusercontent.com/cuichangquan/ap2-mandate-verifier/f6d4f83d396b75505256dba5769a54a8f065eeea/research/stage15/results/R3/INPUTS.json
|
|
114
|
-
printf '%s\n' '41ad845a7ea82a9c7316c9ef11fb8ee5281453afafe2b4932c7217c1936562c1 AP2_RESEARCH_INPUTS.json' | shasum -a 256 -c -
|
|
115
|
-
# Save the Ruby example below as research_example.rb, then:
|
|
116
|
-
ruby research_example.rb
|
|
117
|
-
```
|
|
33
|
+
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.
|
|
118
34
|
|
|
119
35
|
```ruby
|
|
120
36
|
require "ap2_mandate_verifier"
|
|
121
37
|
require "json"
|
|
122
|
-
require "
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
38
|
+
require "tmpdir"
|
|
39
|
+
|
|
40
|
+
builder = AP2MandateVerifier::InputBuilder
|
|
41
|
+
fixtures = File.join(__dir__, "examples/input_builder")
|
|
42
|
+
read = ->(name) { JSON.parse(File.binread(File.join(fixtures, "#{name}.json"))) }
|
|
43
|
+
trust_at = ->(now) do
|
|
44
|
+
builder.trust(snapshot: read.call("trust_snapshot"), tenant_id: "synthetic-tenant",
|
|
45
|
+
issuer: {"identity" => "issuer", "purpose" => "checkout", "key_ref" => "issuer-1"},
|
|
46
|
+
agent: {"identity" => "agent", "purpose" => "checkout", "key_ref" => "agent-1"},
|
|
47
|
+
merchant: {"identity" => "shop", "purpose" => "checkout", "key_ref" => "merchant-1"},
|
|
48
|
+
verified_at: now)
|
|
49
|
+
end
|
|
50
|
+
wires = read.call("signed_wires").transform_keys(&:to_sym) # Preserve String bytes.
|
|
51
|
+
|
|
52
|
+
# Before issuance: independent order/trust and Host-chosen challenge information.
|
|
53
|
+
prepared = builder.prepare(trust: trust_at.call(1_800_000_000),
|
|
54
|
+
order: read.call("order"), root_presentation: wires.fetch(:root_presentation),
|
|
55
|
+
host_checkout_jws: wires.fetch(:host_checkout_jws),
|
|
56
|
+
challenge_id: "synthetic-challenge", nonce: "n", issuer_id: "synthetic-host",
|
|
57
|
+
not_before: 1_799_998_000, not_after: 1_800_002_000)
|
|
58
|
+
|
|
59
|
+
Dir.mktmpdir do |directory|
|
|
60
|
+
record = File.join(directory, "challenge.json")
|
|
61
|
+
File.binwrite(record, prepared) # Demo persistence; the Host owns real storage.
|
|
62
|
+
|
|
63
|
+
# Later: load the saved bytes, and independently obtain current order/trust.
|
|
64
|
+
now = 1_800_000_000 # Supplied synthetic clock, not a production time source.
|
|
65
|
+
result = builder.verify(trust: trust_at.call(now),
|
|
66
|
+
saved_challenge: builder.restore(saved_challenge: File.binread(record)),
|
|
67
|
+
order: read.call("order"), **wires,
|
|
68
|
+
expected_challenge_issuer_id: "synthetic-host",
|
|
69
|
+
clock_source_id: "fixed-synthetic-clock", verified_at: now)
|
|
70
|
+
puts "#{result.status}/#{result.code}; evidence=#{!result.evidence.nil?}"
|
|
71
|
+
raise "Verification did not succeed; stop" unless result.success?
|
|
147
72
|
end
|
|
148
73
|
```
|
|
149
74
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
## Understanding the result
|
|
75
|
+
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.
|
|
153
76
|
|
|
154
|
-
|
|
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. |
|
|
77
|
+
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.
|
|
159
78
|
|
|
160
|
-
|
|
79
|
+
## Results and responsibility boundaries
|
|
161
80
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
| Keyword | Input contract |
|
|
81
|
+
| Result | Meaning and next step |
|
|
165
82
|
| --- | --- |
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
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. |
|
|
173
|
-
|
|
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.
|
|
175
|
-
|
|
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.
|
|
177
|
-
|
|
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.
|
|
179
|
-
|
|
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.
|
|
181
|
-
|
|
182
|
-
## Exclusions and safe stopping
|
|
183
|
-
|
|
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.
|
|
83
|
+
| `: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. |
|
|
84
|
+
| `:rejected`, `rejected? == true` | No Evidence. Stop and inspect `result.code`. |
|
|
85
|
+
| `:unavailable`, `unavailable? == true` | No Evidence. Stop; a dependency or processing failure is not proof of invalid business data. |
|
|
185
86
|
|
|
186
|
-
|
|
87
|
+
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.
|
|
187
88
|
|
|
188
|
-
|
|
89
|
+
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.
|
|
189
90
|
|
|
190
|
-
|
|
91
|
+
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.
|
|
191
92
|
|
|
192
|
-
|
|
93
|
+
### Which API should I use?
|
|
193
94
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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).
|
|
201
|
-
|
|
202
|
-
## Illustrated concepts (Japanese diagrams)
|
|
203
|
-
|
|
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.
|
|
205
|
-
|
|
206
|
-
### AP2 overview (Japanese)
|
|
207
|
-
|
|
208
|
-

|
|
209
|
-
|
|
210
|
-
### Delegation and Host responsibility boundaries (Japanese)
|
|
211
|
-
|
|
212
|
-

|
|
213
|
-
|
|
214
|
-
### Mandate anatomy (Japanese)
|
|
215
|
-
|
|
216
|
-

|
|
217
|
-
|
|
218
|
-
### SD-JWT and delegation concepts (Japanese)
|
|
219
|
-
|
|
220
|
-

|
|
95
|
+
| Entry | Role |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| `InputBuilder.verify(**business_information)` | Recommended business-data path in 0.3.0. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
|
|
98
|
+
| `verify_checkout(**inputs)` | Direct complete verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
|
|
99
|
+
| `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
|
|
100
|
+
| `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
|
|
221
101
|
|
|
222
|
-
|
|
102
|
+
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.
|
|
223
103
|
|
|
224
|
-
|
|
104
|
+
## More detail
|
|
225
105
|
|
|
226
|
-
|
|
106
|
+
- [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).
|
|
107
|
+
- [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
|
|
108
|
+
- [Published 0.3.0 release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.3.0), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
|
|
109
|
+
- [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.
|
|
110
|
+
- [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.
|
|
227
111
|
|
|
228
112
|
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,77 @@
|
|
|
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
|
+
公開済み0.3.0は変更しません。対応MRI 3.4.12または4.0.9と固定依存を備えた隔離環境で、
|
|
59
|
+
チェックアウトから候補を通常インストールしてください。
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
gem build ap2_mandate_verifier.gemspec
|
|
63
|
+
gem install --local --no-document ./ap2_mandate_verifier-0.4.0.gem
|
|
64
|
+
ruby examples/input_builder.rb valid
|
|
65
|
+
ruby examples/input_builder.rb tampered
|
|
66
|
+
ruby examples/input_builder.rb expired
|
|
67
|
+
ruby examples/input_builder.rb missing_currency
|
|
68
|
+
ruby examples/input_builder.rb wrong_total_type
|
|
69
|
+
ruby examples/input_builder.rb unknown_order_field
|
|
70
|
+
ruby examples/input_builder.rb unsupported_saved_format
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
正常はEvidenceあり、改ざんはhost_binding_mismatch、期限切れはinvalid_purchase_timeです。
|
|
74
|
+
後半4例はrejected / invalid_host_contextのまま、理由が順にmissing_required_field、invalid_type、
|
|
75
|
+
unknown_field、unsupported_saved_formatになります。合成fixtureの固定時刻を使います。
|
|
76
|
+
業務データの対応・保存責務は[InputBuilderガイド](INPUT_BUILDER.ja.md)を参照してください。
|
|
77
|
+
公開、実Issuer接続、本番購入許可、Phase 2-B移行を意味しません。
|
data/docs/DIAGNOSTICS.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Failure diagnostics (unreleased 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 candidate locally
|
|
66
|
+
|
|
67
|
+
Published 0.3.0 remains unchanged. Build and normally install the unpublished
|
|
68
|
+
candidate from this checkout in an isolated environment with the supported
|
|
69
|
+
MRI (3.4.12 or 4.0.9) and pinned dependencies:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
gem build ap2_mandate_verifier.gemspec
|
|
73
|
+
gem install --local --no-document ./ap2_mandate_verifier-0.4.0.gem
|
|
74
|
+
ruby examples/input_builder.rb valid
|
|
75
|
+
ruby examples/input_builder.rb tampered
|
|
76
|
+
ruby examples/input_builder.rb expired
|
|
77
|
+
ruby examples/input_builder.rb missing_currency
|
|
78
|
+
ruby examples/input_builder.rb wrong_total_type
|
|
79
|
+
ruby examples/input_builder.rb unknown_order_field
|
|
80
|
+
ruby examples/input_builder.rb unsupported_saved_format
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The successful example returns Evidence, tampered returns
|
|
84
|
+
`host_binding_mismatch`, expired returns `invalid_purchase_time`, and the four
|
|
85
|
+
assembly examples return `rejected / invalid_host_context` with diagnostic
|
|
86
|
+
reasons `missing_required_field`, `invalid_type`, `unknown_field` and
|
|
87
|
+
`unsupported_saved_format`. Synthetic fixture clocks are intentional. See
|
|
88
|
+
[InputBuilder](INPUT_BUILDER.md) for data mapping and storage responsibilities.
|
|
89
|
+
No publication, real Issuer connection, production authorization or Phase 2-B
|
|
90
|
+
GO is implied.
|
data/docs/SUPPORT_CONTRACT.md
CHANGED
|
@@ -1,17 +1,33 @@
|
|
|
1
|
-
# Fixed-profile AP2 verification — 0.
|
|
1
|
+
# Fixed-profile AP2 verification — published 0.3.0 / historical releases
|
|
2
|
+
|
|
3
|
+
Unreleased 0.4.0 adds supplemental safe diagnostics; see [API and troubleshooting](DIAGNOSTICS.md). Published 0.3.0 and existing verdict/Evidence contracts remain unchanged.
|
|
4
|
+
|
|
5
|
+
## Published 0.3.0 input assistance
|
|
6
|
+
|
|
7
|
+
`InputBuilder` is an additive, Rails-independent conversion layer for explicit authenticated Host business records, versioned challenge preparation/restoration, and independently obtained current state. `verify` enters the unchanged complete `verify_checkout` core; assembly/restore alone never returns Evidence. Existing seven inputs, fixed profile/AP2 source, Result/Evidence v2, MRI 3.4.12/4.0.9 and all five pinned runtime dependencies remain unchanged.
|
|
8
|
+
|
|
9
|
+
New business Hash/Array graphs are bounded before serialization and require plain built-ins with String keys; unknown fields, formats/profiles, conflicting keys and unsupported shapes fail closed. Persist the original returned challenge String and original signed wires. `restore_trust` validates and preserves exact stored trust/selection Strings. Rebuilding trust from business records creates a new snapshot whose exact bytes may differ; it must not repair old challenge references. Stored B/digests/references are never regenerated from current values. Host authentication, freshness/revocation, storage, issuance/atomic consumption and final authorization remain Host duties. See [input assistance](INPUT_BUILDER.md). Publication does not establish Host production authorization.
|
|
10
|
+
|
|
11
|
+
[0.3.0 is published on RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.3.0): registered 2026-10-31 01:31:40.743 UTC; official metadata fetched at 01:32:40 UTC and final comparison completed at 01:33:27 UTC. Owner `cuichangquan`, platform `ruby`, non-prerelease, not yanked at verification. Metadata, distributed Gem and saved final candidate matched: **37,376 bytes**, SHA256 `b3a31d5a8b0718f1085745dd4d97d85f210ff9a1628798110da9ff382ae546bd`, source `877f59195632f74714a60551b6afb22ac81d93e3`. RubyGems does not independently attest a source commit; the source association is from the retained reviewed candidate, whose bytes match the download. [v0.3.0 tag/Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.3.0) points to that exact source and was published at 01:35:52 UTC.
|
|
12
|
+
|
|
13
|
+
On Debian 12/arm64, MRI 3.4.12 and 4.0.9 each passed the merged-source existing885 + checkout190 + metadata7 + builder109 suites. The same final Gem passed ordinary installation, 14 source/archive/installed payload matches, 11 normally loaded product files and 134 installed cases per Ruby. Five runtime pins remain JSON2.19.9/JWT3.3.0/base640.3.0/OpenSSL gem4.0.2/Digest3.2.1. Scope and withdrawn-candidate history are in the [publication record](PROJECT_STATUS.md#030公開済み--現在の配布状態); these observations do not validate real Issuers, actual Hosts, performance or production GO.
|
|
14
|
+
|
|
15
|
+
The earlier archive SHA256 `5de6907cfcf0565ddaba1385b1d38ae113cc5e26d52259d769030237378a48a8` is withdrawn and was not published. [PR219](https://github.com/cuichangquan/ap2-mandate-verifier/pull/219) fixed its unregistered failure Result codes, unavailable classification and selector shape checks. Published failure handling reuses existing registered Result codes and preserves dependency-unavailable typing. The published Gem's README/contract remain the preparation snapshot; this repository update does not rebuild, repush or replace those bytes. GitHub source archives are separate from the RubyGems Gem.
|
|
2
16
|
|
|
3
17
|
**Fixed-profile verification contract; Evidence is not Host ALLOW or payment permission.**
|
|
4
18
|
Distribution availability is determined by the official RubyGems version listing, not by this document. Specific Host production GO remains separate.
|
|
5
19
|
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
20
|
Published research-only pre3 remains unchanged. Its historical observations below do not certify this new archive.
|
|
7
21
|
|
|
8
|
-
##
|
|
22
|
+
## Published 0.2.1 compatibility and artifact
|
|
23
|
+
|
|
24
|
+
[0.2.1 is published on RubyGems](https://rubygems.org/gems/ap2_mandate_verifier/versions/0.2.1). Formal runtime support is 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 installation requirement `>= 3.4.12, < 4.1` is a resolution interval, not certification of other Ruby versions or engines.
|
|
9
25
|
|
|
10
|
-
|
|
26
|
+
Both versions passed source885 + additional checkout190 + metadata7 on Debian 12/arm64 with official Ruby bookworm images. The same final artifact passed ordinary installation, 13 payload-file comparisons, 10 normally loaded product Ruby files and 118 installed cases per Ruby. Actual OS/native-provider identities and evidence are in the [compatibility record](RUBY_3_4_12_COMPATIBILITY.md). These measurements cover their exact recorded configurations; historical macOS/Ubuntu evidence below does not validate 0.2.1 there.
|
|
11
27
|
|
|
12
|
-
|
|
28
|
+
Published 2026-10-30 11:51:55.894 UTC; verified 11:53:55 UTC: owner `cuichangquan`, platform `ruby`, non-prerelease, not yanked at verification. Official metadata, distributed Gem and retained artifact matched: **34,816 bytes**, SHA256 `a4ab7e0f6c9bd87355695369374f8e6e2dad104fb673700e9f616053afe6e114`, source `5a02bc3a192e16aa3628cf7899617623b0aed78c`. The [v0.2.1 GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v0.2.1) tag points to that exact source.
|
|
13
29
|
|
|
14
|
-
|
|
30
|
+
Seven inputs, fixed profile, Fail Closed, Result/Evidence v2 and `verify_checkout` / `verify_research` / legacy `verify` meanings remain unchanged; product `lib/` is unchanged. Packaged README/contract retain the preparation snapshot. Repository publication updates do not rebuild or replace those bytes. GitHub source archives differ from the RubyGems Gem. Publication does not establish real Issuer trust, Host production GO or Phase 2-B; existing HOLDs remain.
|
|
15
31
|
|
|
16
32
|
## Published 0.2.0 API
|
|
17
33
|
|
|
@@ -35,7 +51,7 @@ Published 2026-10-30 06:43:10 UTC, verified 06:44:48 UTC: owner `cuichangquan`,
|
|
|
35
51
|
|
|
36
52
|
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
53
|
|
|
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 [
|
|
54
|
+
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 [0.2.0 publication record](PROJECT_STATUS.md#020公開済み--現在の配布状態).
|
|
39
55
|
|
|
40
56
|
## Verification contract
|
|
41
57
|
|
|
@@ -56,7 +72,7 @@ Manual dependency/provider review is adopted monthly, on relevant advisories and
|
|
|
56
72
|
|
|
57
73
|
## Existing API/limits and historical evidence baseline
|
|
58
74
|
|
|
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);
|
|
75
|
+
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); 0.2.1 has its separate compatibility record above. No old result is relabelled.
|
|
60
76
|
|
|
61
77
|
## Supported proposition and environment
|
|
62
78
|
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module AP2MandateVerifier
|
|
4
|
+
# Supplemental guidance, never a verification decision or an input echo.
|
|
5
|
+
# Only the closed catalog below can construct diagnostics. No input retained.
|
|
6
|
+
class Diagnostic
|
|
7
|
+
GROUPS = {
|
|
8
|
+
input_validation: [%i[invalid_input_type input_too_large invalid_encoding invalid_json duplicate_key input_too_deep],
|
|
9
|
+
"Check original String bytes, JSON syntax, duplicate keys and documented input limits.",
|
|
10
|
+
"原文のString型、JSON構文、重複キー、文書記載の入力上限を確認してください。"],
|
|
11
|
+
signature_verification: [%i[invalid_root_jws unsupported_root_header unsupported_root_algorithm unsupported_root_type invalid_root_payload invalid_root_signature],
|
|
12
|
+
"Check original signed Root/Agent/Merchant bytes, the fixed header profile and independently selected public keys. A signature failure alone does not identify which input is wrong.",
|
|
13
|
+
"署名原文、固定ヘッダー仕様、独立に選択した公開鍵を確認してください。署名失敗だけでは誤った入力を特定できません。"],
|
|
14
|
+
root_disclosures: [%i[invalid_root_presentation unsupported_disclosure_profile invalid_disclosure missing_disclosure duplicate_disclosure duplicate_commitment extra_disclosure disclosure_limit_exceeded],
|
|
15
|
+
"Check the complete original Root presentation and disclosures against the supported profile; do not repair received signed data.",
|
|
16
|
+
"原Root提示全体と開示を対応profileと照合してください。受信した署名データを補修しないでください。"],
|
|
17
|
+
purchase_binding: [%i[unsupported_purchase_profile agent_key_mismatch root_binding_mismatch audience_mismatch nonce_mismatch invalid_purchase_time delegation_claim_mismatch checkout_binding_mismatch checkout_identity_mismatch],
|
|
18
|
+
"Compare original Root, Agent and Merchant wires with independent Host audience, nonce, identity and clock inputs. The code identifies a failed check, not its underlying cause.",
|
|
19
|
+
"Root・Agent・Merchant原文と、Hostが独立に取得したaudience、nonce、主体、時刻を照合してください。コードは失敗した検査を示し、根本原因を断定しません。"],
|
|
20
|
+
constraints: [%i[invalid_scoped_schema unsupported_scoped_profile unsupported_constraint constraint_mismatch amount_mismatch currency_mismatch constraint_limit_exceeded],
|
|
21
|
+
"Compare signed constraints, checkout items, currency and minor-unit totals with independent current order data and the fixed profile.",
|
|
22
|
+
"署名済み制約、購入項目、通貨、最小単位の合計額を、独立した現在の注文情報および固定profileと照合してください。"],
|
|
23
|
+
trust_context: [%i[invalid_trust_context trust_context_mismatch unsupported_trust_profile inactive_trust_snapshot trust_snapshot_time_mismatch invalid_trust_key trust_key_not_found ambiguous_trust_key inactive_trust_key trust_key_time_mismatch],
|
|
24
|
+
"Check authenticated current trust snapshot, explicit role/key selection, active state and validity at the independent verification time. Never select trust from received claims.",
|
|
25
|
+
"認証された現在のtrust snapshot、明示的な役割・鍵選択、active状態、独立した検証時刻での有効期間を確認してください。受信claimから信頼先を選ばないでください。"],
|
|
26
|
+
host_binding: [%i[invalid_host_context host_binding_mismatch challenge_state_mismatch challenge_reference_mismatch challenge_time_mismatch invalid_host_validity],
|
|
27
|
+
"Compare the authenticated saved challenge with independent current order, trust references, expected issuer and time. Preserve the saved record; do not rebuild it from current values.",
|
|
28
|
+
"認証された保存済みchallengeと、独立した現在の注文、trust参照、期待issuer、時刻を照合してください。保存記録を現在値で作り直さないでください。"]
|
|
29
|
+
}.freeze
|
|
30
|
+
GROUPS.each_value { |entry| entry[0].freeze; entry.freeze }
|
|
31
|
+
SPECIAL = {
|
|
32
|
+
invalid_purchase_time: ["Check the independent clock and the signed Open/Closed validity and terminal proof time window. This does not establish whether the clock or signed times are wrong.",
|
|
33
|
+
"独立した時計、署名済みOpen・Closedの有効期間、terminal proofの時刻窓を確認してください。時計と署名時刻のどちらが誤っているかは断定できません。"]
|
|
34
|
+
}.freeze
|
|
35
|
+
BUILDER_HINTS = {
|
|
36
|
+
missing_required_field: ["Supply the documented required field from independent Host data.", "文書記載の必須項目を、独立したHost情報から渡してください。"],
|
|
37
|
+
invalid_type: ["Check the documented exact Ruby/JSON type; coercion and subclasses are not supported.", "文書記載のRuby・JSONの厳密な型を確認してください。暗黙変換やサブクラスは対応外です。"],
|
|
38
|
+
unknown_field: ["Remove unsupported fields using the documented schema. Unknown field names are intentionally omitted.", "文書記載の構造と照合し、未対応項目を除いてください。未知の項目名は意図的に表示しません。"],
|
|
39
|
+
unsupported_saved_format: ["Check the saved format/profile version against this gem. Restore original authenticated bytes; do not rewrite the version.", "保存形式・profileの版がGemの対応版か確認してください。認証された原文を復元し、版を書き換えないでください。"],
|
|
40
|
+
invalid_value: ["Check documented bounds and supported values for this field.", "この項目の文書記載の範囲と対応値を確認してください。"],
|
|
41
|
+
invalid_builder_input: ["Check the InputBuilder contract and bounded, plain Ruby input shapes. The exact cause could not be safely identified.", "InputBuilder契約と上限内の通常Ruby入力構造を確認してください。正確な原因は安全に特定できませんでした。"]
|
|
42
|
+
}.freeze
|
|
43
|
+
SPECIAL.each_value(&:freeze)
|
|
44
|
+
BUILDER_HINTS.each_value(&:freeze)
|
|
45
|
+
FIELDS = (%w[order trust verified_at saved_challenge snapshot snapshot.records issuer agent merchant arguments root_presentation terminal_jws host_checkout_jws trust_json selection_json expected_challenge_issuer_id clock_source_id challenge_id nonce issuer_id not_before not_after] +
|
|
46
|
+
%w[tenant_id buyer_account_id order_id merchant_id audience order_version currency expected_total].map { |f| "order.#{f}" } +
|
|
47
|
+
%w[id policy_version active not_before not_after records].map { |f| "snapshot.#{f}" } +
|
|
48
|
+
%w[format_version profile_ref profile_version challenge].map { |f| "saved_challenge.#{f}" } +
|
|
49
|
+
%w[issuer agent merchant].flat_map { |r| %w[identity purpose key_ref].map { |f| "#{r}.#{f}" } }).each(&:freeze).freeze
|
|
50
|
+
|
|
51
|
+
attr_reader :stage, :field, :reason
|
|
52
|
+
def initialize(stage, field, reason, hints)
|
|
53
|
+
@stage, @field, @reason = stage, field, reason
|
|
54
|
+
@hints = hints.map { |s| s.dup.freeze }.freeze
|
|
55
|
+
freeze
|
|
56
|
+
end
|
|
57
|
+
private_class_method :new, :allocate
|
|
58
|
+
def hint(locale: :en) = @hints[locale == :ja ? 1 : 0]
|
|
59
|
+
def to_h(locale: :en) = {stage: stage, field: field, reason: reason, hint: hint(locale: locale)}.freeze
|
|
60
|
+
def [](key) = to_h[key]
|
|
61
|
+
def dup = self
|
|
62
|
+
def clone(freeze: true) = self
|
|
63
|
+
def self.for_result(status, code)
|
|
64
|
+
return nil if status == :verified_research
|
|
65
|
+
known = Result::CODES.fetch(status, []).include?(code)
|
|
66
|
+
if status == :unavailable && known
|
|
67
|
+
return new(:verification_unavailable, nil, code,
|
|
68
|
+
["Verification could not be completed. Check supported dependency versions and service/runtime health; this is not proof of invalid business data.",
|
|
69
|
+
"検証を完了できませんでした。対応依存バージョンと実行環境の状態を確認してください。業務データ不正の証拠ではありません。"])
|
|
70
|
+
end
|
|
71
|
+
GROUPS.each do |stage, (codes, en, ja)|
|
|
72
|
+
return new(stage, nil, code, SPECIAL.fetch(code, [en, ja])) if known && codes.include?(code)
|
|
73
|
+
end
|
|
74
|
+
new(:verification, nil, :undetermined,
|
|
75
|
+
["No precise diagnostic is available. Check status/code and the documented API scope; do not infer checkout permission.",
|
|
76
|
+
"詳細診断はありません。status・codeとAPIの保証範囲を確認してください。購入許可とは解釈しないでください。"])
|
|
77
|
+
end
|
|
78
|
+
def self.builder(field, reason)
|
|
79
|
+
# Look up canonical strings; never retain a caller string or arbitrary key.
|
|
80
|
+
safe_field = FIELDS.find { |known| known == field }
|
|
81
|
+
safe_reason = BUILDER_HINTS.key?(reason) ? reason : :invalid_builder_input
|
|
82
|
+
new(:input_assembly, safe_field, safe_reason, BUILDER_HINTS.fetch(safe_reason))
|
|
83
|
+
end
|
|
84
|
+
end
|
|
85
|
+
end
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module AP2MandateVerifier
|
|
4
|
+
# Pure, fixed-profile conversion of authenticated Host business information.
|
|
5
|
+
# Preparation is not issuance, verification, nonce consumption or Host ALLOW.
|
|
6
|
+
module InputBuilder
|
|
7
|
+
VERIFY_FIELDS = %i[trust saved_challenge order root_presentation terminal_jws host_checkout_jws
|
|
8
|
+
expected_challenge_issuer_id clock_source_id verified_at].freeze
|
|
9
|
+
FORMAT_VERSION = "1"
|
|
10
|
+
ORDER_FIELDS = %w[tenant_id buyer_account_id order_id merchant_id audience order_version currency expected_total].freeze
|
|
11
|
+
RECORD_FIELDS = (TrustContext::RECORD_FIELDS - %w[profile_ref profile_version algorithm key_fingerprint]).freeze
|
|
12
|
+
class Invalid < ArgumentError
|
|
13
|
+
def initialize(field = nil, reason = :invalid_builder_input)
|
|
14
|
+
@field, @reason = field, reason
|
|
15
|
+
super("invalid input-builder information")
|
|
16
|
+
end
|
|
17
|
+
def diagnostic
|
|
18
|
+
Diagnostic.builder(@field, @reason)
|
|
19
|
+
rescue StandardError, LoadError
|
|
20
|
+
nil
|
|
21
|
+
end
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
class Trust
|
|
25
|
+
attr_reader :trust_json, :selection_json
|
|
26
|
+
def initialize(trust_json, selection_json, context)
|
|
27
|
+
@trust_json, @selection_json = trust_json.freeze, selection_json.freeze
|
|
28
|
+
@context = context
|
|
29
|
+
freeze
|
|
30
|
+
end
|
|
31
|
+
private_class_method :new
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
# All registry entries are preserved, including inactive/nonselected entries.
|
|
35
|
+
# Selection is explicit Host policy, never extracted from signed claims.
|
|
36
|
+
def self.trust(snapshot:, tenant_id:, issuer:, agent:, merchant:, verified_at:)
|
|
37
|
+
verified_at = copy!(verified_at)
|
|
38
|
+
source = copy!(snapshot)
|
|
39
|
+
shape!(source, %w[id policy_version active not_before not_after records], "snapshot")
|
|
40
|
+
invalid!("snapshot.records", :invalid_type) unless source["records"].instance_of?(Array)
|
|
41
|
+
invalid!("snapshot.records", :invalid_value) unless source["records"].length.between?(1, 16)
|
|
42
|
+
source["records"].each do |record|
|
|
43
|
+
shape!(record, RECORD_FIELDS)
|
|
44
|
+
record.merge!("profile_ref" => TrustContext::PROFILE_REF, "profile_version" => TrustContext::PROFILE_VERSION,
|
|
45
|
+
"algorithm" => "ES256", "key_fingerprint" => Digest::SHA256.hexdigest(record.fetch("public_key_pem")))
|
|
46
|
+
end
|
|
47
|
+
body = json!(source, 65_536)
|
|
48
|
+
selection = {"trust_snapshot_id" => source["id"], "policy_version" => source["policy_version"],
|
|
49
|
+
"trust_content_hash" => Digest::SHA256.hexdigest(body), "tenant_id" => copy!(tenant_id),
|
|
50
|
+
"profile_ref" => TrustContext::PROFILE_REF, "profile_version" => TrustContext::PROFILE_VERSION,
|
|
51
|
+
"profile_definition_hash" => TrustContext::PROFILE_HASH,
|
|
52
|
+
"Issuer" => copy!(issuer), "Agent" => copy!(agent), "Merchant" => copy!(merchant)}
|
|
53
|
+
TrustContext::ROLES.each_key { |role| shape!(selection[role], %w[identity purpose key_ref], role.downcase) }
|
|
54
|
+
wire = json!({"snapshot" => {"id" => source["id"], "policy_version" => source["policy_version"],
|
|
55
|
+
"content_hash" => selection["trust_content_hash"], "body" => body},
|
|
56
|
+
"profile" => {"profile_ref" => TrustContext::PROFILE_REF, "version" => TrustContext::PROFILE_VERSION,
|
|
57
|
+
"definition_hash" => TrustContext::PROFILE_HASH, "body" => TrustContext::PROFILE_BODY}})
|
|
58
|
+
selected = json!(selection, 16_384)
|
|
59
|
+
context = TrustContext.verified_context!(trust_json: wire, selection_json: selected, verified_at: verified_at,
|
|
60
|
+
expected_merchant_id: selection.fetch("Merchant").fetch("identity"))
|
|
61
|
+
Trust.send(:new, wire, selected, context)
|
|
62
|
+
rescue Invalid
|
|
63
|
+
raise
|
|
64
|
+
rescue RootSignature::Unavailable
|
|
65
|
+
raise
|
|
66
|
+
rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
|
|
67
|
+
invalid!
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
# Restore authenticated registry bytes without reserializing the snapshot
|
|
71
|
+
# or profile body. The Host remains responsible for freshness and provenance.
|
|
72
|
+
def self.restore_trust(trust_json:, selection_json:, verified_at:)
|
|
73
|
+
wire = InputValidator.snapshot!(trust_json)
|
|
74
|
+
selected = InputValidator.snapshot!(selection_json, max_bytes: 16_384)
|
|
75
|
+
selection = InputValidator.parse!(selected)
|
|
76
|
+
context = TrustContext.verified_context!(trust_json: wire, selection_json: selected,
|
|
77
|
+
verified_at: copy!(verified_at), expected_merchant_id: selection.fetch("Merchant").fetch("identity"))
|
|
78
|
+
Trust.send(:new, wire, selected, context)
|
|
79
|
+
rescue Invalid
|
|
80
|
+
raise
|
|
81
|
+
rescue RootSignature::Unavailable
|
|
82
|
+
raise
|
|
83
|
+
rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError, NoMethodError
|
|
84
|
+
invalid!
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
# Persist the returned original String in authenticated Host storage. A nonce
|
|
88
|
+
# and identifier must already have been chosen by the Host, independently.
|
|
89
|
+
def self.prepare(trust:, order:, root_presentation:, host_checkout_jws:, challenge_id:, nonce:, issuer_id:, not_before:, not_after:)
|
|
90
|
+
context = context!(trust, not_before)
|
|
91
|
+
TrustContext.verified_context!(trust_json: trust.trust_json, selection_json: trust.selection_json,
|
|
92
|
+
verified_at: not_before, expected_merchant_id: context.fetch(:selected_keys).find { |r| r["role"] == "Merchant" }.fetch("identity"))
|
|
93
|
+
challenge = {"challenge_id" => copy!(challenge_id), "nonce" => copy!(nonce), "issuer_id" => copy!(issuer_id),
|
|
94
|
+
"B" => binding!(context, order, root_presentation, host_checkout_jws),
|
|
95
|
+
"not_before" => copy!(not_before), "not_after" => copy!(not_after), "state" => "issued"}
|
|
96
|
+
HostBinding::REFERENCES.each { |field| challenge[field] = context.fetch(:references).fetch(field) }
|
|
97
|
+
saved = json!({"format_version" => FORMAT_VERSION, "profile_ref" => TrustContext::PROFILE_REF,
|
|
98
|
+
"profile_version" => TrustContext::PROFILE_VERSION, "challenge" => challenge}, 32_768)
|
|
99
|
+
restore(saved_challenge: saved)
|
|
100
|
+
rescue Invalid
|
|
101
|
+
raise
|
|
102
|
+
rescue RootSignature::Unavailable
|
|
103
|
+
raise
|
|
104
|
+
rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
|
|
105
|
+
invalid!
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
# Validate, but never regenerate, hash or repair persisted challenge fields.
|
|
109
|
+
# This does not authenticate the storage or attest that its nonce is unused.
|
|
110
|
+
def self.restore(saved_challenge:)
|
|
111
|
+
wire = InputValidator.snapshot!(saved_challenge, max_bytes: 32_768)
|
|
112
|
+
value = InputValidator.parse!(wire)
|
|
113
|
+
shape!(value, %w[format_version profile_ref profile_version challenge], "saved_challenge")
|
|
114
|
+
invalid!("saved_challenge", :unsupported_saved_format) unless value.values_at("format_version", "profile_ref", "profile_version") ==
|
|
115
|
+
[FORMAT_VERSION, TrustContext::PROFILE_REF, TrustContext::PROFILE_VERSION]
|
|
116
|
+
challenge = value["challenge"]
|
|
117
|
+
shape!(challenge, HostBinding::CHALLENGE_FIELDS)
|
|
118
|
+
HostBinding.send(:binding!, challenge["B"])
|
|
119
|
+
invalid! unless challenge["B"].values_at("profile_ref", "profile_version") ==
|
|
120
|
+
[TrustContext::PROFILE_REF, TrustContext::PROFILE_VERSION]
|
|
121
|
+
%w[challenge_id nonce issuer_id trust_snapshot_id policy_version state].each { |field| HostBinding.send(:id!, challenge[field]) }
|
|
122
|
+
%w[trust_content_hash profile_definition_hash].each { |field| HostBinding.send(:hash!, challenge[field]) }
|
|
123
|
+
%w[not_before not_after].each { |field| HostBinding.send(:time!, challenge[field]) }
|
|
124
|
+
invalid! unless challenge["not_before"] < challenge["not_after"]
|
|
125
|
+
wire
|
|
126
|
+
rescue Invalid
|
|
127
|
+
raise
|
|
128
|
+
rescue RootSignature::Unavailable
|
|
129
|
+
raise
|
|
130
|
+
rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
|
|
131
|
+
invalid!
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
def self.inputs(trust:, saved_challenge:, order:, root_presentation:, terminal_jws:, host_checkout_jws:,
|
|
135
|
+
expected_challenge_issuer_id:, clock_source_id:, verified_at:)
|
|
136
|
+
context = context!(trust, verified_at)
|
|
137
|
+
saved = InputValidator.parse!(restore(saved_challenge: saved_challenge))
|
|
138
|
+
root = InputValidator.snapshot!(root_presentation)
|
|
139
|
+
checkout = InputValidator.snapshot!(host_checkout_jws, max_bytes: 16_384)
|
|
140
|
+
terminal = InputValidator.snapshot!(terminal_jws, max_bytes: 32_768)
|
|
141
|
+
host = {"binding" => binding!(context, order, root, checkout), "challenge" => saved.fetch("challenge"),
|
|
142
|
+
"expected_challenge_issuer_id" => copy!(expected_challenge_issuer_id), "clock_source_id" => copy!(clock_source_id)}
|
|
143
|
+
{trust_json: trust.trust_json, selection_json: trust.selection_json, host_json: json!(host, 32_768),
|
|
144
|
+
root_presentation: root, terminal_jws: terminal, host_checkout_jws: checkout, verified_at: verified_at}.freeze
|
|
145
|
+
rescue Invalid
|
|
146
|
+
raise
|
|
147
|
+
rescue RootSignature::Unavailable
|
|
148
|
+
raise
|
|
149
|
+
rescue InputValidator::Invalid, RootSignature::Rejected, KeyError, TypeError
|
|
150
|
+
invalid!
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
# Building alone never produces Evidence; always enter the full old core.
|
|
154
|
+
def self.verify(**arguments)
|
|
155
|
+
invalid!("arguments", :missing_required_field) unless VERIFY_FIELDS.all? { |field| arguments.key?(field) }
|
|
156
|
+
invalid!("arguments", :unknown_field) unless arguments.length == VERIFY_FIELDS.length
|
|
157
|
+
AP2MandateVerifier.verify_checkout(**inputs(**arguments))
|
|
158
|
+
rescue Invalid => error
|
|
159
|
+
Result.new(status: :rejected, code: :invalid_host_context, diagnostic: error.diagnostic)
|
|
160
|
+
rescue ArgumentError
|
|
161
|
+
Result.new(status: :rejected, code: :invalid_host_context,
|
|
162
|
+
diagnostic: Invalid.new.diagnostic)
|
|
163
|
+
rescue InputValidator::Unavailable, RootSignature::Unavailable, LoadError
|
|
164
|
+
Result.new(status: :unavailable, code: :research_verification_unavailable)
|
|
165
|
+
rescue StandardError
|
|
166
|
+
Result.new(status: :unavailable, code: :research_verification_unavailable)
|
|
167
|
+
end
|
|
168
|
+
|
|
169
|
+
def self.context!(trust, now)
|
|
170
|
+
invalid!("trust", :invalid_type) unless Object.instance_method(:instance_of?).bind_call(trust, Trust)
|
|
171
|
+
HostBinding.send(:time!, copy!(now))
|
|
172
|
+
trust.instance_variable_get(:@context)
|
|
173
|
+
end
|
|
174
|
+
def self.binding!(context, order, root, checkout)
|
|
175
|
+
value = copy!(order)
|
|
176
|
+
shape!(value, ORDER_FIELDS, "order")
|
|
177
|
+
ORDER_FIELDS.each do |field|
|
|
178
|
+
expected = field == "expected_total" ? Integer : String
|
|
179
|
+
invalid!("order.#{field}", :invalid_type) unless value[field].instance_of?(expected)
|
|
180
|
+
end
|
|
181
|
+
HostBinding::B_IDS.grep_v(/profile/).each do |field|
|
|
182
|
+
invalid!("order.#{field}", :invalid_value) unless value[field].bytesize.between?(1, 256)
|
|
183
|
+
end
|
|
184
|
+
invalid!("order.currency", :invalid_value) unless ScopedConstraints::CURRENCIES.include?(value["currency"])
|
|
185
|
+
invalid!("order.expected_total", :invalid_value) unless value["expected_total"].between?(0, ScopedConstraints::MAX_AMOUNT)
|
|
186
|
+
references = context.fetch(:references)
|
|
187
|
+
value.merge!("profile_ref" => references.fetch("profile_ref"), "profile_version" => references.fetch("profile_version"),
|
|
188
|
+
"approved_agent_key_fingerprint" => context.fetch(:agent_fingerprint),
|
|
189
|
+
"root_presentation_digest" => Digest::SHA256.hexdigest(InputValidator.snapshot!(root)),
|
|
190
|
+
"checkout_jwt_digest" => Digest::SHA256.hexdigest(InputValidator.snapshot!(checkout, max_bytes: 16_384)))
|
|
191
|
+
HostBinding.send(:binding!, value)
|
|
192
|
+
value
|
|
193
|
+
end
|
|
194
|
+
def self.shape!(value, fields, path = nil)
|
|
195
|
+
invalid!(path, :invalid_type) unless value.instance_of?(Hash)
|
|
196
|
+
missing = fields.find { |field| !value.key?(field) }
|
|
197
|
+
invalid!(path && "#{path}.#{missing}", :missing_required_field) if missing
|
|
198
|
+
invalid!(path, :unknown_field) unless value.keys.sort == fields.sort
|
|
199
|
+
end
|
|
200
|
+
def self.invalid!(field = nil, reason = :invalid_builder_input)
|
|
201
|
+
raise Invalid.new(field, reason), cause: nil
|
|
202
|
+
end
|
|
203
|
+
def self.json!(value, limit = InputValidator::MAX_BYTES)
|
|
204
|
+
require "json"
|
|
205
|
+
raise InputValidator::Unavailable, :json_dependency_unavailable unless JSON::VERSION == InputValidator::JSON_VERSION
|
|
206
|
+
InputValidator.snapshot!(JSON.generate(value), max_bytes: limit)
|
|
207
|
+
end
|
|
208
|
+
|
|
209
|
+
# Bound and detach before JSON generation, including the pre-serialization
|
|
210
|
+
# graph. No coercion, subclass or singleton callback is invoked by copying.
|
|
211
|
+
def self.copy!(value)
|
|
212
|
+
budget = [0, 0]
|
|
213
|
+
walk!(value, 1, {}, budget)
|
|
214
|
+
end
|
|
215
|
+
def self.walk!(value, depth, ancestors, budget)
|
|
216
|
+
invalid! if depth > 16 || (budget[0] += 1) > 2048
|
|
217
|
+
invalid! unless Object.instance_method(:singleton_methods).bind_call(value, true).empty?
|
|
218
|
+
klass = Object.instance_method(:class).bind_call(value)
|
|
219
|
+
if klass == String
|
|
220
|
+
wire = InputValidator.snapshot!(value, max_bytes: 65_536)
|
|
221
|
+
invalid! if (budget[1] += wire.bytesize) > 131_072
|
|
222
|
+
wire.dup
|
|
223
|
+
elsif klass == Integer
|
|
224
|
+
invalid! unless value.between?(0, ScopedConstraints::MAX_AMOUNT)
|
|
225
|
+
value
|
|
226
|
+
elsif klass == TrueClass || klass == FalseClass || klass == NilClass
|
|
227
|
+
value
|
|
228
|
+
elsif klass == Hash || klass == Array
|
|
229
|
+
id = Object.instance_method(:object_id).bind_call(value)
|
|
230
|
+
invalid! if ancestors[id]
|
|
231
|
+
ancestors[id] = true
|
|
232
|
+
invalid! if value.size > 256
|
|
233
|
+
result = if klass == Array
|
|
234
|
+
value.map { |child| walk!(child, depth + 1, ancestors, budget) }
|
|
235
|
+
else
|
|
236
|
+
result = {}
|
|
237
|
+
value.each do |key, child|
|
|
238
|
+
invalid! unless Object.instance_method(:class).bind_call(key) == String
|
|
239
|
+
copied_key = walk!(key, depth + 1, ancestors, budget)
|
|
240
|
+
invalid! if result.key?(copied_key)
|
|
241
|
+
result[copied_key] = walk!(child, depth + 1, ancestors, budget)
|
|
242
|
+
end
|
|
243
|
+
result
|
|
244
|
+
end
|
|
245
|
+
ancestors.delete(id)
|
|
246
|
+
result
|
|
247
|
+
else
|
|
248
|
+
invalid!
|
|
249
|
+
end
|
|
250
|
+
end
|
|
251
|
+
# Validate keyword shape before Ruby's keyword errors can echo arbitrary
|
|
252
|
+
# caller-supplied names. Each captured implementation keeps its typed API.
|
|
253
|
+
%i[trust restore_trust prepare restore inputs].each do |name|
|
|
254
|
+
implementation = method(name)
|
|
255
|
+
fields = implementation.parameters.filter_map { |kind, field| field if kind == :keyreq }.freeze
|
|
256
|
+
define_singleton_method(name) do |**arguments|
|
|
257
|
+
missing = fields.find { |field| !arguments.key?(field) }
|
|
258
|
+
invalid!(missing&.to_s, :missing_required_field) if missing
|
|
259
|
+
invalid!("arguments", :unknown_field) unless arguments.length == fields.length
|
|
260
|
+
implementation.call(**arguments)
|
|
261
|
+
end
|
|
262
|
+
end
|
|
263
|
+
private_class_method :context!, :binding!, :shape!, :invalid!, :json!, :copy!, :walk!
|
|
264
|
+
end
|
|
265
|
+
end
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require_relative "diagnostic"
|
|
4
|
+
|
|
3
5
|
module AP2MandateVerifier
|
|
4
6
|
# Legacy non-success type. The opt-in research entry uses a separate type.
|
|
5
7
|
class Result
|
|
@@ -32,15 +34,23 @@ module AP2MandateVerifier
|
|
|
32
34
|
|
|
33
35
|
attr_reader :status, :code
|
|
34
36
|
|
|
35
|
-
def initialize(status:, code:)
|
|
37
|
+
def initialize(status:, code:, diagnostic: nil)
|
|
36
38
|
unless CODES.fetch(status, []).include?(code)
|
|
37
39
|
raise ArgumentError, "unsupported non-success result"
|
|
38
40
|
end
|
|
39
41
|
@status = status
|
|
40
42
|
@code = code
|
|
43
|
+
@diagnostic = diagnostic if Object.instance_method(:instance_of?).bind_call(diagnostic, Diagnostic) && diagnostic.frozen?
|
|
41
44
|
freeze
|
|
42
45
|
end
|
|
43
46
|
|
|
47
|
+
# A diagnostic failure cannot affect the already determined verdict.
|
|
48
|
+
def diagnostic
|
|
49
|
+
@diagnostic || Diagnostic.for_result(status, code)
|
|
50
|
+
rescue StandardError, LoadError
|
|
51
|
+
nil
|
|
52
|
+
end
|
|
53
|
+
|
|
44
54
|
def success? = false
|
|
45
55
|
def evidence = nil
|
|
46
56
|
def rejected? = status == :rejected
|
data/lib/ap2_mandate_verifier.rb
CHANGED
|
@@ -9,6 +9,7 @@ require_relative "ap2_mandate_verifier/scoped_constraints"
|
|
|
9
9
|
require_relative "ap2_mandate_verifier/trust_context"
|
|
10
10
|
require_relative "ap2_mandate_verifier/host_binding"
|
|
11
11
|
require_relative "ap2_mandate_verifier/research_result"
|
|
12
|
+
require_relative "ap2_mandate_verifier/input_builder"
|
|
12
13
|
|
|
13
14
|
module AP2MandateVerifier
|
|
14
15
|
# Accepts original JSON bytes only. Syntax validity is not AP2 validity,
|
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.
|
|
4
|
+
version: 0.4.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- AP2 Mandate Verifier contributors
|
|
8
8
|
bindir: bin
|
|
9
9
|
cert_chain: []
|
|
10
|
-
date:
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
11
|
dependencies:
|
|
12
12
|
- !ruby/object:Gem::Dependency
|
|
13
13
|
name: json
|
|
@@ -89,9 +89,13 @@ extra_rdoc_files: []
|
|
|
89
89
|
files:
|
|
90
90
|
- LICENSE
|
|
91
91
|
- README.md
|
|
92
|
+
- docs/DIAGNOSTICS.ja.md
|
|
93
|
+
- docs/DIAGNOSTICS.md
|
|
92
94
|
- docs/SUPPORT_CONTRACT.md
|
|
93
95
|
- lib/ap2_mandate_verifier.rb
|
|
96
|
+
- lib/ap2_mandate_verifier/diagnostic.rb
|
|
94
97
|
- lib/ap2_mandate_verifier/host_binding.rb
|
|
98
|
+
- lib/ap2_mandate_verifier/input_builder.rb
|
|
95
99
|
- lib/ap2_mandate_verifier/input_validator.rb
|
|
96
100
|
- lib/ap2_mandate_verifier/purchase_binding.rb
|
|
97
101
|
- lib/ap2_mandate_verifier/research_result.rb
|
|
@@ -121,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
121
125
|
- !ruby/object:Gem::Version
|
|
122
126
|
version: '0'
|
|
123
127
|
requirements: []
|
|
124
|
-
rubygems_version:
|
|
128
|
+
rubygems_version: 4.0.20
|
|
125
129
|
specification_version: 4
|
|
126
130
|
summary: Fixed-profile AP2 verification for Ruby
|
|
127
131
|
test_files: []
|