ap2_mandate_verifier 0.7.0 → 1.0.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.ja.md +199 -0
- data/README.md +63 -12
- data/SECURITY.md +82 -0
- data/docs/BUYER_DIRECT_CHECKOUT.md +13 -10
- data/docs/CONDITIONAL_CHECKOUT.md +171 -0
- data/docs/INPUT_BUILDER.md +182 -0
- data/docs/MERCHANT_SIGNING.md +1 -1
- data/docs/POST_RELEASE_MAINTENANCE.md +160 -0
- data/docs/PUBLIC_API.md +198 -0
- data/docs/RELEASE_100_CANDIDATE.md +113 -0
- data/docs/SUPPORT_CONTRACT.md +70 -4
- data/examples/conditional_checkout.rb +84 -0
- data/lib/ap2_mandate_verifier/conditional_checkout.rb +150 -0
- data/lib/ap2_mandate_verifier/merchant_signature.rb +7 -3
- data/lib/ap2_mandate_verifier/root_disclosures.rb +24 -1
- data/lib/ap2_mandate_verifier/scoped_constraints.rb +12 -7
- data/lib/ap2_mandate_verifier.rb +1 -0
- metadata +17 -7
data/docs/PUBLIC_API.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Ruby SDK public API — 1.0.0 candidate
|
|
2
|
+
|
|
3
|
+
**Status: unpublished 1.0.0 preparation. Published stable remains 0.8.0.**
|
|
4
|
+
This document defines the proposed 1.x contract for the existing Checkout APIs;
|
|
5
|
+
it adds no runtime behavior, renames or broader accepted formats. Candidate
|
|
6
|
+
validation and remaining release decisions belong to
|
|
7
|
+
[the preparation record](RELEASE_100_CANDIDATE.md).
|
|
8
|
+
|
|
9
|
+
The SDK supports human-approved Direct orders and conditional Open → Agent Closed
|
|
10
|
+
delegation for the documented profiles. It runs in plain Ruby. Payment Mandates,
|
|
11
|
+
general AP2/Schema compatibility, real Issuer enrollment and application payment
|
|
12
|
+
execution are outside this contract. The adopted AP2 source remains
|
|
13
|
+
`b4587ac1d055888a73b4b21750973cffba961793`.
|
|
14
|
+
|
|
15
|
+
## Supported entry points
|
|
16
|
+
|
|
17
|
+
All names below are under `AP2MandateVerifier`. Require the Gem with
|
|
18
|
+
`require "ap2_mandate_verifier"`. Arguments are keywords unless shown otherwise;
|
|
19
|
+
the linked contracts specify their complete fields, exact Ruby types and limits.
|
|
20
|
+
No implicit coercion, trust discovery or default current clock is provided.
|
|
21
|
+
|
|
22
|
+
| Entry | Role and returned value | Detailed contract |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| `ConditionalCheckout.issue_open` | Sign approved merchant/product/quantity conditions for one registered Agent; return `ConditionalCheckout::Open`. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
|
|
25
|
+
| `ConditionalCheckout.issue_closed` | Check Open, Agent binding, Merchant Checkout and conditions; sign and return `ConditionalCheckout::Closed`. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
|
|
26
|
+
| `ConditionalCheckout.present` | Restore original Open, terminal and Checkout strings with structural/binding checks; return `ConditionalCheckout::Closed`. This is not signature authentication. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
|
|
27
|
+
| `Buyer.issue_closed` | Sign a Direct order whose original Checkout equals the app's approved original; return `Buyer::Issued`. | [Direct API](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
28
|
+
| `Buyer.present_closed` | Preserve the Direct wire after structural checks; return a frozen String. This is not signature authentication. | [Direct API](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
29
|
+
| `Buyer.verify` | Verify the supported Direct presentation against independently supplied keys, expected Checkout and time; return `Buyer::Verification`. | [Direct API](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
30
|
+
| `CheckoutJWT.sign` / `.verify` | Sign a supported merchant-authored Checkout / authenticate it against an independent merchant key and identity; return `CheckoutJWT::Signed` / `CheckoutJWT::Verification`. | [Signing](MERCHANT_SIGNING.md#minimal-executable-example), [verification](BUYER_DIRECT_CHECKOUT.md#public-apis-and-failures) |
|
|
31
|
+
| `CheckoutJWT.es256_signer(private_key:)` | Return a signing callable over an application-owned OpenSSL P-256 private key. | [Signer contract](MERCHANT_SIGNING.md#minimal-executable-example) |
|
|
32
|
+
| `CheckoutReceipt.reference` / `.sign` / `.verify` | Calculate the exact final-Mandate reference / sign an explicit app outcome / authenticate a Receipt; return a frozen String / `CheckoutReceipt::Signed` / `CheckoutReceipt::Verification`. | [Receipt contract](MERCHANT_SIGNING.md#checkout-receipt-contract-and-specification-discrepancy) |
|
|
33
|
+
|
|
34
|
+
### Full Open → Agent Closed verification and input preparation
|
|
35
|
+
|
|
36
|
+
| Entry | Role and returned value |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `InputBuilder.trust` / `.restore_trust` | Assemble a selected trust snapshot / restore original trust and selection strings; return `InputBuilder::Trust`. The app authenticates provenance and currentness. |
|
|
39
|
+
| `InputBuilder.prepare` / `.restore` | Prepare a versioned challenge record / validate and preserve its original bytes; return a frozen String. Neither operation issues or consumes a nonce. |
|
|
40
|
+
| `InputBuilder.inputs` | Assemble the seven complete-verification keyword inputs as a frozen Hash. It does not produce Evidence. |
|
|
41
|
+
| `InputBuilder.verify` | Assemble business inputs and run complete Open → Agent Closed verification; return `ResearchResult` or non-success `Result`. |
|
|
42
|
+
| `verify_checkout` / `verify_research` | Run the same complete Open → Agent Closed pipeline with the seven raw inputs below. `verify_research` remains supported without a deprecation warning. |
|
|
43
|
+
| `ResearchResult.verify` | Retained factory for that same pipeline and input contract. Prefer the module-level or InputBuilder entry for new integrations. |
|
|
44
|
+
|
|
45
|
+
The seven raw keywords are `trust_json:`, `selection_json:`, `host_json:`,
|
|
46
|
+
`root_presentation:`, `terminal_jws:`, `host_checkout_jws:` and `verified_at:`.
|
|
47
|
+
The first six are original Strings; `verified_at` is an independently supplied
|
|
48
|
+
integer Unix timestamp. These entries do not accept the separate Direct format.
|
|
49
|
+
See [business inputs and restoration](INPUT_BUILDER.md) and
|
|
50
|
+
[raw input fields](SUPPORT_CONTRACT.md#full-entry-and-required-inputs).
|
|
51
|
+
|
|
52
|
+
### Preserved partial-verification APIs
|
|
53
|
+
|
|
54
|
+
These published entries remain supported; they are not reclassified as private.
|
|
55
|
+
All return non-success `Result` values with `success? == false` and `evidence == nil`,
|
|
56
|
+
including when their limited check passes. They do not replace either complete
|
|
57
|
+
verification entry.
|
|
58
|
+
|
|
59
|
+
| Entry | Maximum meaning of a passing check |
|
|
60
|
+
| --- | --- |
|
|
61
|
+
| `verify(presentation_json:)` | JSON syntax only: `:unverified / :verification_not_implemented`. |
|
|
62
|
+
| `verify_root_signature(root_jws:, trusted_issuer_public_key_pem:)` | One Root signature, not disclosure closure or authority. |
|
|
63
|
+
| `verify_root_disclosures(presentation:, trusted_issuer_public_key_pem:)` | The existing single-product Root disclosure profile and signature. |
|
|
64
|
+
| `verify_purchase_binding(**inputs)` | The documented Root/Agent/Merchant purchase binding checks. |
|
|
65
|
+
| `verify_scoped_constraints(**inputs)` | The selected supported purchase constraints. |
|
|
66
|
+
| `verify_trusted_scoped_constraints(trust_json:, selection_json:, **inputs)` | Supplied trust selection plus scoped constraints; not the full Host challenge/order contract. |
|
|
67
|
+
| `verify_host_binding(**inputs)` | The supported Host binding checks, without minting successful Evidence through this legacy wrapper. |
|
|
68
|
+
|
|
69
|
+
Existing keyword sets, defaults and partial-pass codes are preserved. See the
|
|
70
|
+
[module entry definitions](../lib/ap2_mandate_verifier.rb) and the
|
|
71
|
+
[Result/Evidence contract](SUPPORT_CONTRACT.md#result-and-evidence).
|
|
72
|
+
|
|
73
|
+
## Result, object and failure contracts
|
|
74
|
+
|
|
75
|
+
Each API keeps its existing result convention. Do not call `success?` on every
|
|
76
|
+
returned object or infer authorization from an object merely being present.
|
|
77
|
+
|
|
78
|
+
| API family | Success | Non-success |
|
|
79
|
+
| --- | --- | --- |
|
|
80
|
+
| Complete Open → Closed verification | `ResearchResult`: `status == :verified_research`, `code == :scoped_research_verified`, `success? == true`, immutable Evidence. | `Result`: rejected or unavailable, `success? == false`, no Evidence. |
|
|
81
|
+
| `InputBuilder.verify` assembly | Enters the complete verifier. | Malformed assembly, including missing/unknown keywords: `:rejected / :invalid_host_context`. Dependency/unexpected assembly failure: `:unavailable / :research_verification_unavailable`. Core results keep their codes. |
|
|
82
|
+
| Other InputBuilder calls | Trust, String or input Hash as listed above. | Checked malformed business input raises `InputBuilder::Invalid`; argument-binding, dependency and unexpected exceptions can propagate. These methods do not promise a Result wrapper. |
|
|
83
|
+
| `Buyer.verify` | `verified? == true`, `code == :direct_checkout_verified`, checked claims. | `verified? == false`, `code == :direct_checkout_verification_failed`, no claims. Dependency/internal failures use this same code. |
|
|
84
|
+
| `CheckoutJWT.sign` / `.verify` / `.es256_signer` | The listed object or callable. | Redacted `CheckoutJWT::Invalid`. Verification does not return a false Verification object. |
|
|
85
|
+
| Buyer issuance/presentation; Conditional issuance/presentation | The listed object or original wire. | Redacted `Buyer::Invalid` or `ConditionalCheckout::Invalid`. |
|
|
86
|
+
| Receipt reference/signing | The listed String or Signed object. | Redacted `CheckoutReceipt::Invalid`. |
|
|
87
|
+
| Receipt verification | `verified? == true`; separately inspect `outcome`, `purchase_succeeded?` or `purchase_rejected?`. | `verified? == false` and both purchase predicates false; no claims. Codes: `:receipt_verification_failed`, `:receipt_issuer_mismatch`, `:receipt_reference_mismatch`, `:receipt_time_mismatch`. |
|
|
88
|
+
|
|
89
|
+
The four signing/presentation `Invalid` classes above inherit `ArgumentError` and
|
|
90
|
+
use fixed redacted messages without the original cause. A generic `Invalid` or
|
|
91
|
+
verification-failed code does **not** distinguish invalid data from unavailable
|
|
92
|
+
signing/dependency processing. Hold the operation; diagnose through protected app
|
|
93
|
+
observability. A remote signer may have completed signing before a transport
|
|
94
|
+
failure: reconcile the app's issuance record before issuing again.
|
|
95
|
+
|
|
96
|
+
Missing/unknown keywords to `verify_checkout`, `verify_research` and
|
|
97
|
+
`ResearchResult.verify` return `:unavailable / :research_verification_unavailable`.
|
|
98
|
+
Ruby positional-argument errors or invalid keyword expansion can raise before an
|
|
99
|
+
entry executes. Exceptions, process failure and missing results never authorize
|
|
100
|
+
an operation. Existing status/code meanings are preserved; human-readable error
|
|
101
|
+
or diagnostic wording is not a machine interface.
|
|
102
|
+
|
|
103
|
+
### Supported returned objects and constructors
|
|
104
|
+
|
|
105
|
+
| Type | Supported reads |
|
|
106
|
+
| --- | --- |
|
|
107
|
+
| `Result`, `ResearchResult` | `status`, `code`, `success?`, `rejected?`, `unverified?`, `unavailable?`, `evidence`, `diagnostic`. |
|
|
108
|
+
| `ResearchEvidence` | `[](field)` and `to_h`: the existing immutable Evidence v2 facts, including contract/profile identities and checked bindings. |
|
|
109
|
+
| `InputBuilder::Trust` | `trust_json`, `selection_json`. |
|
|
110
|
+
| `CheckoutJWT::Signed` | `jwt`, `checkout_hash`. |
|
|
111
|
+
| `CheckoutJWT::Verification` | `verified?`, `jwt`, `checkout_hash`, `checkout`, `profile_ref`. |
|
|
112
|
+
| `Buyer::Issued` | `closed_sd_jwt`. |
|
|
113
|
+
| `Buyer::Verification` | `verified?`, `code`, `checkout`, `checkout_hash`, `reference`, `expires_at`. |
|
|
114
|
+
| `ConditionalCheckout::Open` | `root_presentation`. |
|
|
115
|
+
| `ConditionalCheckout::Closed` | `root_presentation`, `terminal_jws`, `checkout_jwt`, `closed_sd_jwt`. |
|
|
116
|
+
| `CheckoutReceipt::Signed` | `jwt`, `reference`. |
|
|
117
|
+
| `CheckoutReceipt::Verification` | `verified?`, `code`, `outcome`, `purchase_succeeded?`, `purchase_rejected?`, `order_id`, `error`, `error_description`. |
|
|
118
|
+
| `Diagnostic` | `stage`, `field`, `reason`, `hint(locale: :en)`, `to_h(locale: :en)`, `[](key)`; `:ja` provides Japanese hints. |
|
|
119
|
+
| `InputBuilder::Invalid` | `diagnostic`, which may be nil if diagnostic construction fails. |
|
|
120
|
+
|
|
121
|
+
`Result.new(status:, code:, diagnostic: nil)` is retained. It accepts only
|
|
122
|
+
registered non-success status/code pairs and raises `ArgumentError` for unsupported
|
|
123
|
+
pairs. It cannot construct successful Evidence. Result/Evidence-producing object
|
|
124
|
+
constructors other than this non-success constructor are private: obtain those
|
|
125
|
+
objects from their listed factories, not `.new`, reflection or deserialization.
|
|
126
|
+
Exception classes are rescue targets, not proof objects. No exception message,
|
|
127
|
+
backtrace or mutable Ruby object identity authenticates a check.
|
|
128
|
+
These objects assume a trusted Ruby process; private construction is API
|
|
129
|
+
discipline, not a sandbox against hostile Ruby code or reflection.
|
|
130
|
+
|
|
131
|
+
Diagnostics are optional guidance. Success has no failure diagnostic; diagnostic
|
|
132
|
+
failure cannot change a verdict. Existing machine identifiers retain their meaning;
|
|
133
|
+
wording/translations and internal lookup-table layout are not frozen.
|
|
134
|
+
See [diagnostic semantics](DIAGNOSTICS.md).
|
|
135
|
+
|
|
136
|
+
## Profiles and defaults
|
|
137
|
+
|
|
138
|
+
Profile version and Gem version are separate. All three profiles below remain v1.
|
|
139
|
+
|
|
140
|
+
| Profile identifier | Selection and supported lifecycle |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `ap2.checkout.single_merchant_sku` | Default for optional `profile_ref:` on InputBuilder trust, CheckoutJWT and CheckoutReceipt. Existing one-product Open → Agent Closed verification. |
|
|
143
|
+
| `ap2.checkout.single_merchant_multi_item` | Explicit selection for those APIs; implicit fixed choice of ConditionalCheckout. One merchant/currency, 1–8 lines, all candidate disclosures and exact quantity allocation. |
|
|
144
|
+
| `ap2.checkout.direct.single_merchant` | Fixed Buyer API profile; pass `Buyer::PROFILE_REF` explicitly to Receipt APIs. One merchant/currency and 1–8 exact-order lines. |
|
|
145
|
+
|
|
146
|
+
Supported profile constants include `TrustContext::PROFILE_REF`, `PROFILE_VERSION`,
|
|
147
|
+
`PROFILE_BODY` and `PROFILE_HASH`, and its corresponding `MULTI_PROFILE_REF`,
|
|
148
|
+
`MULTI_PROFILE_VERSION`, `MULTI_PROFILE_BODY` and `MULTI_PROFILE_HASH` constants.
|
|
149
|
+
`ConditionalCheckout::PROFILE_REF`, `Buyer::PROFILE_REF` and `Buyer::CHECKOUT_PROFILE`
|
|
150
|
+
are supported as well. Their names and existing v1 values remain stable, including
|
|
151
|
+
the constants used by the documented raw-input example. Profile definitions/hashes,
|
|
152
|
+
accepted shapes, bounds, original-wire reference rules and defaults are
|
|
153
|
+
compatibility-sensitive even when implemented by other internal constants.
|
|
154
|
+
See [multi-item limits](MULTI_ITEM_CHECKOUT.md) and
|
|
155
|
+
[Direct limits](BUYER_DIRECT_CHECKOUT.md#profile-and-limits).
|
|
156
|
+
No received claim selects trusted policy; unknown profiles and constraints fail closed.
|
|
157
|
+
|
|
158
|
+
## Persistence and trust boundaries
|
|
159
|
+
|
|
160
|
+
- Persist exact signed JWT/SD-JWT and disclosure strings. `ConditionalCheckout.present`
|
|
161
|
+
restores its three original strings; `Buyer.present_closed` restores its one
|
|
162
|
+
original wire. Neither authenticates a restored presentation.
|
|
163
|
+
- Persist InputBuilder preparation format `"1"` and original trust/selection JSON.
|
|
164
|
+
Use `restore` / `restore_trust`; do not regenerate hashes or issue-time references
|
|
165
|
+
to make changed state match. Restoration does not authenticate storage, establish
|
|
166
|
+
freshness or prove an unused nonce.
|
|
167
|
+
- Receipt reference covers only the final original Closed SD-JWT: `terminal_jws + "~"`
|
|
168
|
+
for the existing conditional profile, or the entire disclosed Direct wire with
|
|
169
|
+
its terminal `~`. It is not the Open chain hash, compact-only JWT or rebuilt JSON.
|
|
170
|
+
- `ResearchEvidence#to_h` is an immutable inspection view, not a signed transport
|
|
171
|
+
credential. There is no JSON/Hash/Marshal reconstruction API for authenticated
|
|
172
|
+
Evidence, results, Trust or other checked objects. Persisted original wires must
|
|
173
|
+
be verified again against current independent inputs.
|
|
174
|
+
- Signing callbacks receive frozen ASCII JWS signing input and return 64 binary
|
|
175
|
+
JOSE ES256 signature bytes. The SDK verifies the returned signature with the
|
|
176
|
+
independently supplied public key. The app owns signer access, timeouts, key
|
|
177
|
+
custody and lifecycle; Provider signing material never enters the Agent API.
|
|
178
|
+
- The app authenticates users, consent, registry/keys/revocation, current orders
|
|
179
|
+
and time. It rechecks authorization, atomically consumes/reserves state, handles
|
|
180
|
+
duplicates and reconciles uncertain outcomes. The SDK performs no network, DB
|
|
181
|
+
or payment operation. An authentic Error Receipt is not permission to retry;
|
|
182
|
+
a missing or unverifiable Receipt leaves the application outcome unknown.
|
|
183
|
+
|
|
184
|
+
## Compatibility and internal boundary
|
|
185
|
+
|
|
186
|
+
The proposed 1.x [versioning, maintenance and deprecation policy](POST_RELEASE_MAINTENANCE.md)
|
|
187
|
+
applies to these calls, types, machine meanings, profiles and persistence contracts.
|
|
188
|
+
The `research` names and syntax-only `verify` keep their current meanings. No 0.8.0
|
|
189
|
+
API migration is required by this candidate; an actual 1.0.0 publication remains a
|
|
190
|
+
separate release decision.
|
|
191
|
+
|
|
192
|
+
Internal `verified_*!` handoffs are not supported ways to inject checked facts;
|
|
193
|
+
[the existing support contract](SUPPORT_CONTRACT.md#result-and-evidence) already
|
|
194
|
+
excludes them. Private helpers, unlisted validator/factory helpers, diagnostic
|
|
195
|
+
catalogs, internal constant layouts and research/test scripts are implementation
|
|
196
|
+
details, not extension hooks. Ruby visibility alone does not make them an SDK API.
|
|
197
|
+
This does not remove the published partial-verification entries above, their
|
|
198
|
+
observable error behavior, or the documented profile identities and bounds.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# 1.0.0 release candidate preparation
|
|
2
|
+
|
|
3
|
+
**Unpublished candidate. The currently published release is 0.8.0.**
|
|
4
|
+
The candidate Gem has version `1.0.0`; that metadata is not a publication record.
|
|
5
|
+
The [preparation evidence](evidence/1.0.0_preparation.json) identifies the actual
|
|
6
|
+
source, archive, observed checks and remaining gates. A later publication must
|
|
7
|
+
identify the exact approved bytes separately.
|
|
8
|
+
|
|
9
|
+
## Purpose and supported scope
|
|
10
|
+
|
|
11
|
+
1.0.0 establishes the [public Ruby API](PUBLIC_API.md) and
|
|
12
|
+
[1.x compatibility and maintenance policy](POST_RELEASE_MAINTENANCE.md).
|
|
13
|
+
It keeps the 0.8.0 runtime implementation and supported Checkout profiles.
|
|
14
|
+
|
|
15
|
+
| Workflow | Included in the public contract |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| Merchant Checkout | Sign and verify the supported original Checkout JWT. |
|
|
18
|
+
| Direct human-approved order | Issue, present and verify the Provider-signed exact order. |
|
|
19
|
+
| Conditional purchase | Issue Open conditions; generate/present Agent-signed Closed; verify the complete chain with independent current trust, order, challenge and time inputs. |
|
|
20
|
+
| Checkout Receipt | Reference the exact final Closed SD-JWT; sign and verify authentic Success/Error outcomes. |
|
|
21
|
+
|
|
22
|
+
All workflows are plain Ruby. Rails is an integration example. A 1.0.0 SDK
|
|
23
|
+
version does not assert coverage of every AP2 feature, certification, application
|
|
24
|
+
authorization or payment execution. The adopted official AP2 source stays at
|
|
25
|
+
`b4587ac1d055888a73b4b21750973cffba961793`.
|
|
26
|
+
|
|
27
|
+
## Changes from 0.8.0
|
|
28
|
+
|
|
29
|
+
- Explicit public API, return/exception, profile/default and persistence contracts.
|
|
30
|
+
- Current SDK metadata, security reporting, maintenance and product guidance.
|
|
31
|
+
- Aligned 1.0.0 package checks and development lockfile; newly packaged public API,
|
|
32
|
+
input preparation, security and maintenance documentation.
|
|
33
|
+
- Independent Python-generated conditional inputs exercised through the public
|
|
34
|
+
complete verifier and Receipt APIs, including installed-Gem mode and signed
|
|
35
|
+
negative controls. Existing internal-boundary comparisons remain separate.
|
|
36
|
+
|
|
37
|
+
There are no runtime `lib/` changes, profile/default changes, new runtime
|
|
38
|
+
dependencies or renamed APIs. Existing `verify_research`, research-named results,
|
|
39
|
+
syntax-only `verify`, saved preparation format `"1"` and Evidence v2 remain.
|
|
40
|
+
MRI 3.4.12 and 4.0.9 remain the formally supported versions. Installation metadata
|
|
41
|
+
`>= 3.4.12, < 4.1` does not certify every version in that range. Runtime pins remain
|
|
42
|
+
JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1.
|
|
43
|
+
|
|
44
|
+
## Migration and candidate inspection
|
|
45
|
+
|
|
46
|
+
Applications using documented 0.8.0 APIs need no source migration for this
|
|
47
|
+
candidate. A dependency such as `~> 0.8.0` does not select 1.0.0. After publication,
|
|
48
|
+
use an explicit compatible constraint (for example `~> 1.0`) and update this Gem
|
|
49
|
+
in the application's lockfile. Do not treat a successful verification, an
|
|
50
|
+
authentic Receipt or successful installation as application purchase permission.
|
|
51
|
+
|
|
52
|
+
To inspect a prepared local candidate, install its exact file in an isolated
|
|
53
|
+
Gem environment whose fixed dependencies are already installed:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
gem install --local --no-document /absolute/path/ap2_mandate_verifier-1.0.0.gem
|
|
57
|
+
ruby -rap2_mandate_verifier -e 'puts Gem.loaded_specs.fetch("ap2_mandate_verifier").version'
|
|
58
|
+
ruby -e 'spec = Gem::Specification.find_by_name("ap2_mandate_verifier", "= 1.0.0"); load File.join(spec.full_gem_path, "examples/conditional_checkout.rb")'
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The standalone synthetic example covers Open → Agent Closed → complete
|
|
62
|
+
verification → Success/Error Receipt. The application's identity, consent,
|
|
63
|
+
key custody, revocation, persistent replay protection and payment integration
|
|
64
|
+
remain its responsibility. Unknown execution outcomes remain pending until the
|
|
65
|
+
application reconciles them.
|
|
66
|
+
|
|
67
|
+
## Required release evidence
|
|
68
|
+
|
|
69
|
+
| Check | Required evidence |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| Scope and compatibility | Diff against the 0.8.0 baseline; unchanged runtime code, profile definitions/defaults and five dependency pins; public API/source review. |
|
|
72
|
+
| Source regression | Existing 17 suite entry points on both supported MRI versions, preserving individual results without double-counting transitive suites. |
|
|
73
|
+
| Exact package | One final archive built after packaged content is fixed; SHA256/size and all payloads matched against source and ordinary installation on both Rubies. |
|
|
74
|
+
| Installed behavior | Original saved-input/oracle checks, diagnostics, signing/Direct/multi-item/conditional examples and conditional tests loaded from the installed Gem. |
|
|
75
|
+
| Interoperability | Pinned official Python source and recorded dependencies; external signatures, original-wire hashes, supported Schema and complete public verification; signed causal negatives and authentic Success/Error Receipts. |
|
|
76
|
+
| Review and repository gates | Independent review of the actual final source, no unresolved substantive P1/P2, applicable branch protection and bounded CI recorded separately from local tests. |
|
|
77
|
+
| Publication | Owner approval for the exact source/archive, followed by RubyGems distribution comparison and exact-source public tag/Release. Preparation does not perform these actions. |
|
|
78
|
+
|
|
79
|
+
The existing Debian-container source/package procedure is
|
|
80
|
+
`scripts/check_ruby_compatibility.sh` followed by
|
|
81
|
+
`scripts/check_candidate_package.sh OUTPUT_DIR ABSOLUTE_GEM_PATH`.
|
|
82
|
+
Pass the **same archive** to each supported Ruby; separately built CI candidates
|
|
83
|
+
do not establish byte identity across runtimes.
|
|
84
|
+
|
|
85
|
+
The conditional interoperability command, from this source checkout, is:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
AP2_INSTALLED=1 AP2_GEM_VERSION=1.0.0 \
|
|
89
|
+
AP2_OFFICIAL_ROOT=/absolute/path/to/pinned-ap2 \
|
|
90
|
+
PYTHONPATH=/absolute/path/to/pinned-ap2/code/sdk/python \
|
|
91
|
+
python test/conditional_interop.py
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`PATH` must select the supported Ruby, and `GEM_HOME`/`GEM_PATH` must select the
|
|
95
|
+
normally installed candidate and fixed dependencies. No product source directory
|
|
96
|
+
may be added to Ruby's load path in installed mode. The Python check asserts
|
|
97
|
+
official source/Schema location consistency and must be run with the recorded
|
|
98
|
+
fixed source and dependency identities. Its supported inline Closed subset does
|
|
99
|
+
not include the official helper's selectively disclosed terminal representation.
|
|
100
|
+
|
|
101
|
+
## Preparation boundary
|
|
102
|
+
|
|
103
|
+
This work follows the Owner's request to prepare 1.0.0, from main
|
|
104
|
+
`7facf5e21699c754eb3e046ee2c653c6ce2c16cf`. Review covers the public contract,
|
|
105
|
+
metadata/package checks and the additional independent test; the application's
|
|
106
|
+
trust registry and current business state remain independent test inputs.
|
|
107
|
+
Existing Issue #101 process and separate legacy research gates are retained.
|
|
108
|
+
Unexpected source/dependency drift, secret exposure, unplanned external cost,
|
|
109
|
+
inconclusive checks or substantive review findings block release readiness.
|
|
110
|
+
|
|
111
|
+
Current public distribution remains 0.8.0 until its successor is actually
|
|
112
|
+
published and verified. A local pass, review result, PR or candidate artifact is
|
|
113
|
+
not a release, real-Issuer attestation or production authorization.
|
data/docs/SUPPORT_CONTRACT.md
CHANGED
|
@@ -1,4 +1,65 @@
|
|
|
1
|
-
#
|
|
1
|
+
# AP2 Checkout Ruby SDK — support contract and history
|
|
2
|
+
|
|
3
|
+
## Current contract and unpublished 1.0.0 preparation
|
|
4
|
+
|
|
5
|
+
**Published stable remains 0.8.0. The working 1.0.0 candidate is unpublished.**
|
|
6
|
+
The candidate preserves the existing product implementation and acceptance
|
|
7
|
+
contracts. Its intended 1.x public surface is catalogued in
|
|
8
|
+
[PUBLIC_API](PUBLIC_API.md); candidate evidence and outstanding decisions are in
|
|
9
|
+
[the preparation record](RELEASE_100_CANDIDATE.md). Historical observations below
|
|
10
|
+
are not new 1.0.0 test results.
|
|
11
|
+
|
|
12
|
+
| Current supported flow | Contract |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| Direct exact-order approval | Checkout authentication, Provider Closed issuance, original presentation, full Direct verification and Receipt confirmation: [Direct](BUYER_DIRECT_CHECKOUT.md). |
|
|
15
|
+
| Conditional purchase delegation | Provider Open issuance, Agent Closed generation/presentation, existing full verification and Receipt confirmation: [Conditional Checkout](CONDITIONAL_CHECKOUT.md). |
|
|
16
|
+
| Existing verification and business inputs | Both Open → Agent Closed profiles, InputBuilder trust/preparation/restoration, immutable Result/Evidence and supplemental diagnostics: [public API](PUBLIC_API.md). |
|
|
17
|
+
| Merchant signing and Receipts | Checkout signing and explicit Success/Error outcome authentication with original-wire references: [Merchant signing](MERCHANT_SIGNING.md). |
|
|
18
|
+
|
|
19
|
+
Formal support remains MRI 3.4.12 and MRI 4.0.9 with JSON 2.19.9, JWT 3.3.0,
|
|
20
|
+
base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. The Gem's Ruby resolution range
|
|
21
|
+
does not certify every intervening version, engine, OS or native provider.
|
|
22
|
+
AP2 source `b4587ac1d055888a73b4b21750973cffba961793`, the three documented v1
|
|
23
|
+
profile identities and InputBuilder preparation format `1` remain unchanged.
|
|
24
|
+
|
|
25
|
+
Each API retains its result/exception convention, including the existing `research`
|
|
26
|
+
names and partial APIs' non-success behavior. A verification failure or signing
|
|
27
|
+
`Invalid` is not automatically proof of malformed business data; see
|
|
28
|
+
[failure handling](PUBLIC_API.md#result-object-and-failure-contracts).
|
|
29
|
+
The app owns current trust, consent, durable state and final execution. Ruby SDK
|
|
30
|
+
support does not establish general AP2 compatibility, Payment support, actual
|
|
31
|
+
Issuer trust or a particular Host's production authorization.
|
|
32
|
+
|
|
33
|
+
The [maintenance policy](POST_RELEASE_MAINTENANCE.md) governs proposed 1.x
|
|
34
|
+
versioning, dependency changes, security corrections and deprecation. The sections
|
|
35
|
+
below preserve older publication evidence and API details; statements explicitly
|
|
36
|
+
scoped to old versions do not remove the current flows listed above.
|
|
37
|
+
|
|
38
|
+
## Published 0.8.0 conditional delegation
|
|
39
|
+
|
|
40
|
+
`ConditionalCheckout.issue_open/issue_closed/present` add conditional delegation
|
|
41
|
+
issuance and original-wire presentation under the unchanged explicit multi-item
|
|
42
|
+
profile v1. [Contract, errors, limits and application responsibilities](CONDITIONAL_CHECKOUT.md).
|
|
43
|
+
The packaged standalone example uses only public installed APIs. No old default,
|
|
44
|
+
profile definition/hash, Result/Evidence/diagnostic, saved record or Receipt
|
|
45
|
+
acceptance condition is changed. All candidates remain required; no new selective
|
|
46
|
+
disclosure profile is introduced. Published stable is 0.8.0, registered
|
|
47
|
+
2026-11-01 06:01:31.103 UTC and compared 06:03:20 UTC: 79,872 bytes, SHA256
|
|
48
|
+
`6c07664e4291aa8bc025b152075869322411a0d99861e1267959f1794e99acec`.
|
|
49
|
+
All29 payloads match published source `5a7394c1b98f000b321423e2c2f80d50b5157808`.
|
|
50
|
+
[Publication and new installed-Gem checks](POST_RELEASE_080.md). The archive's
|
|
51
|
+
candidate-time documents remain unchanged; repository updates do not replace it.
|
|
52
|
+
|
|
53
|
+
Published 0.7.0 adds the separate [Direct buyer module](BUYER_DIRECT_CHECKOUT.md):
|
|
54
|
+
merchant Checkout verification before human approval, Provider-signed issuance,
|
|
55
|
+
Agent presentation, Direct merchant verification and whole-wire Receipt confirmation.
|
|
56
|
+
It supports one merchant, 1–8 lines and multiple products; existing Open→Closed
|
|
57
|
+
Result/Evidence/profile/save contracts are unchanged. Publication was verified at
|
|
58
|
+
2026-11-01 03:14:04 UTC: 64,000 bytes, SHA256
|
|
59
|
+
`baab8c68355b5e6c9351e7d86a836fab50652cdad662bbc99d1676c5e6134447`, all 24 payloads
|
|
60
|
+
match source `9b4b78a7ed9aa95e7d35e01a64efc1281ba95be3`.
|
|
61
|
+
[Publication record](PROJECT_STATUS.md#070-publication). Older version statements below
|
|
62
|
+
retain their historical scope; they do not exclude the new Direct APIs.
|
|
2
63
|
|
|
3
64
|
## Current source: explicit multi-item profile
|
|
4
65
|
|
|
@@ -97,13 +158,13 @@ Gem-owned signature/original-wire/closure, delegation, binding, supplied-trust s
|
|
|
97
158
|
Host inputs must be authenticated, independent of the token and current: trust/keys/profile/revocation/rollback protection, clock and order/challenge state. Recheck before use; atomically consume nonce with order CAS, reconcile unknown results as PENDING, and decide final ALLOW/payment separately.
|
|
98
159
|
Evidence is immutable checked facts in the same trusted Ruby process, not ALLOW or a transport credential. JSON/Hash reconstruction does not authenticate it. Rejection, unavailability, exceptions and no result never authorize an operation. Trusted Ruby is a precondition, not a malicious-Ruby sandbox.
|
|
99
160
|
|
|
100
|
-
No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds.
|
|
161
|
+
No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds. Direct and conditional issuance/presentation are supported by their separate contracts above. Rails adapters, real payments and Host DB operations remain outside the Gem. Separate merchant signing/Checkout Receipt APIs are documented in [MERCHANT_SIGNING](MERCHANT_SIGNING.md).
|
|
101
162
|
Supported-input semantics and existing API/status/code/Evidence contracts must not change silently. Security-driven acceptance narrowing requires impact/reason/migration disclosure; breaking required-field/profile/API changes must be explicit. Dependency updates are not automatically compatible.
|
|
102
163
|
|
|
103
164
|
The published 0.2.0 and historical baseline below is MRI4.0.9 plus JSON2.19.9/JWT3.3.0/base640.3.0/OpenSSL gem4.0.2/Digest3.2.1, with the exact observed MBA arm64-darwin25 and Ubuntu24.04/x86_64 configurations. RubyGems version constraints do not enforce MRI/OS/provider identity. All OS versions, other engines/architectures and arbitrary provider updates are not supported by past observations.
|
|
104
165
|
Historical D3 observed MBA component identities and four selected crypto symbol sources; OS dyld hashes/all symbol bindings/global runtime security remain unproved. JSON2.19.9 official IO-buffer fix/tag/source identity is adopted static evidence; inconsistent GHSA patched-version metadata remains recorded. Neither observation is global S3 PASS. The earlier R1 archive subsequently passed Mac/Ubuntu packaging checks. It is a different archive; see the separate release-package record for current bytes and observations.
|
|
105
166
|
|
|
106
|
-
|
|
167
|
+
Maintenance contact: Owner cuichangquan via repository Issues for ordinary bugs and private vulnerability reporting for vulnerabilities. No secrets, real Mandates or personal data in reports. Current maintenance scope and versioning are in [POST_RELEASE_MAINTENANCE](POST_RELEASE_MAINTENANCE.md); no prerelease/old-series backport, fixed support years, response/fix/disclosure deadline or 24/7 promise is added here.
|
|
107
168
|
Manual dependency/provider review is adopted monthly, on relevant advisories and before releases; no active automatic monitor is implied. Updates/deprecation/end of support must identify affected versions, reason and migration path without inventing a fixed notice period. Known major unaddressed issues or inability to maintain mean HOLD, not a blanket disclaimer.
|
|
108
169
|
|
|
109
170
|
## Existing API/limits and historical evidence baseline
|
|
@@ -221,6 +282,11 @@ constructors do not sandbox malicious Ruby/reflection in that same process.
|
|
|
221
282
|
|
|
222
283
|
## Parsing, schema and time boundaries
|
|
223
284
|
|
|
285
|
+
The single-product shape/count statements in this section preserve the original
|
|
286
|
+
profile. The [multi-item](MULTI_ITEM_CHECKOUT.md) and
|
|
287
|
+
[Direct](BUYER_DIRECT_CHECKOUT.md) contracts specify their separate shapes and
|
|
288
|
+
limits; the [conditional API](CONDITIONAL_CHECKOUT.md) reuses the multi-item profile.
|
|
289
|
+
|
|
224
290
|
Header/payload parse before signature enforces strict bounded syntax only.
|
|
225
291
|
JSON2.19.9 duplicate rejection remains on, including escaped duplicate keys;
|
|
226
292
|
BOM/comments/trailing commas/nonfinite numbers are rejected. JOSE is fixed alg/
|
|
@@ -394,7 +460,7 @@ failed or mismatched report is not success. No local path is a public evidence
|
|
|
394
460
|
URL. Raw local environment logs are not published by this package.
|
|
395
461
|
|
|
396
462
|
|
|
397
|
-
## Direct buyer module —
|
|
463
|
+
## Direct buyer module — published 0.7.0
|
|
398
464
|
|
|
399
465
|
Additive `CheckoutJWT.verify` and `Buyer.issue_closed/present_closed/verify`
|
|
400
466
|
implement Trusted Agent Provider / Human Present exact-order approval. Direct
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# Ordinary installed Gem only. No test fixtures, source-path loading or network.
|
|
3
|
+
require "ap2_mandate_verifier"
|
|
4
|
+
require "openssl"
|
|
5
|
+
|
|
6
|
+
module ConditionalCheckoutExample
|
|
7
|
+
M = AP2MandateVerifier
|
|
8
|
+
PROFILE = M::ConditionalCheckout::PROFILE_REF
|
|
9
|
+
NOW = 1_800_000_000
|
|
10
|
+
def self.totals(n) = %w[subtotal total].map { |type| {"type" => type, "amount" => n} }
|
|
11
|
+
def self.run
|
|
12
|
+
provider, agent, merchant = Array.new(3) { OpenSSL::PKey::EC.generate("prime256v1") }
|
|
13
|
+
seller = {"id" => "shop", "name" => "Office supplies"}
|
|
14
|
+
# This protected record is created AFTER application authentication, display
|
|
15
|
+
# of these conditions and authority/consent checks. No approved flag is proof.
|
|
16
|
+
requirements = [{"id" => "choice", "quantity" => 1,
|
|
17
|
+
"acceptable_items" => %w[A B].map { |id| {"id" => id, "title" => "Product #{id}"} }},
|
|
18
|
+
{"id" => "required", "quantity" => 2, "acceptable_items" => [{"id" => "C", "title" => "Product C"}]}]
|
|
19
|
+
opening = M::ConditionalCheckout.issue_open(merchant: seller, requirements: requirements,
|
|
20
|
+
agent_public_key_pem: agent.public_to_pem, issued_at: NOW, expires_at: NOW + 600,
|
|
21
|
+
signer: M::CheckoutJWT.es256_signer(private_key: provider), public_key_pem: provider.public_to_pem)
|
|
22
|
+
# Merchant Checkout has three rows, including C in two distinct rows.
|
|
23
|
+
lines = %w[B C C].each_with_index.map do |id, i|
|
|
24
|
+
{"id" => "row-#{i}", "item" => {"id" => id, "title" => "Product #{id}", "price" => 100},
|
|
25
|
+
"quantity" => 1, "totals" => totals(100)}
|
|
26
|
+
end
|
|
27
|
+
order = {"id" => "office-1", "merchant" => seller, "status" => "ready_for_complete",
|
|
28
|
+
"currency" => "USD", "line_items" => lines, "totals" => totals(300), "links" => []}
|
|
29
|
+
checkout = M::CheckoutJWT.sign(checkout: order, profile_ref: PROFILE,
|
|
30
|
+
signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
|
|
31
|
+
|
|
32
|
+
# Host enrollment and challenge are synthetic authenticated application data.
|
|
33
|
+
roles = %w[Issuer Agent Merchant]
|
|
34
|
+
records = roles.zip([provider, agent, merchant]).map do |role, key|
|
|
35
|
+
{"role" => role, "identity" => role == "Merchant" ? "shop" : role.downcase,
|
|
36
|
+
"tenant_id" => "tenant", "purpose" => "checkout", "key_ref" => role.downcase,
|
|
37
|
+
"public_key_pem" => key.public_to_pem, "active" => true, "not_before" => NOW - 1, "not_after" => NOW + 1000}
|
|
38
|
+
end
|
|
39
|
+
selectors = records.to_h { |record| [record["role"].downcase.to_sym, record.slice("identity", "purpose", "key_ref")] }
|
|
40
|
+
trust = M::InputBuilder.trust(snapshot: {"id" => "registry", "policy_version" => "1", "active" => true,
|
|
41
|
+
"not_before" => NOW - 1, "not_after" => NOW + 1000, "records" => records},
|
|
42
|
+
tenant_id: "tenant", verified_at: NOW, profile_ref: PROFILE, **selectors)
|
|
43
|
+
host_order = {"tenant_id" => "tenant", "buyer_account_id" => "buyer", "order_id" => "office-1",
|
|
44
|
+
"merchant_id" => "shop", "audience" => "merchant-host", "order_version" => "1", "currency" => "USD", "expected_total" => 300}
|
|
45
|
+
host_inputs = {trust: trust, order: host_order, root_presentation: opening.root_presentation, host_checkout_jws: checkout.jwt}
|
|
46
|
+
saved = M::InputBuilder.prepare(**host_inputs, challenge_id: "challenge-1", nonce: "synthetic-one-use-nonce",
|
|
47
|
+
issuer_id: "host", not_before: NOW, not_after: NOW + 60)
|
|
48
|
+
# Agent receives public trust, Open, Checkout, challenge and its own signer.
|
|
49
|
+
# Provider signer/private key is not an input to this operation.
|
|
50
|
+
closed = M::ConditionalCheckout.issue_closed(root_presentation: opening.root_presentation, checkout_jwt: checkout.jwt,
|
|
51
|
+
trusted_issuer_public_key_pem: provider.public_to_pem, agent_public_key_pem: agent.public_to_pem,
|
|
52
|
+
trusted_merchant_public_key_pem: merchant.public_to_pem, expected_merchant_id: "shop",
|
|
53
|
+
audience: "merchant-host", nonce: "synthetic-one-use-nonce", verified_at: NOW,
|
|
54
|
+
signer: M::CheckoutJWT.es256_signer(private_key: agent))
|
|
55
|
+
wire = M::ConditionalCheckout.present(root_presentation: closed.root_presentation,
|
|
56
|
+
terminal_jws: closed.terminal_jws, checkout_jwt: closed.checkout_jwt)
|
|
57
|
+
checked = M::InputBuilder.verify(**host_inputs, terminal_jws: wire.terminal_jws,
|
|
58
|
+
saved_challenge: M::InputBuilder.restore(saved_challenge: saved), expected_challenge_issuer_id: "host",
|
|
59
|
+
clock_source_id: "synthetic-clock", verified_at: NOW)
|
|
60
|
+
raise "verification failed" unless checked.success?
|
|
61
|
+
puts "Open -> Agent Closed -> merchant evidence: verified=true; rows=3; requirements=2"
|
|
62
|
+
# These are ALTERNATIVE synthetic application outcomes, never two executions.
|
|
63
|
+
%w[Success Error].each do |outcome|
|
|
64
|
+
fields = outcome == "Success" ? {order_id: "office-1"} : {error: "policy_rejected", error_description: "Application declined"}
|
|
65
|
+
receipt = M::CheckoutReceipt.sign(closed_sd_jwt: wire.closed_sd_jwt, profile_ref: PROFILE,
|
|
66
|
+
issuer: "shop", outcome: outcome, issued_at: NOW, **fields,
|
|
67
|
+
signer: M::CheckoutJWT.es256_signer(private_key: merchant), public_key_pem: merchant.public_to_pem)
|
|
68
|
+
result = M::CheckoutReceipt.verify(jwt: receipt.jwt, closed_sd_jwt: wire.closed_sd_jwt,
|
|
69
|
+
profile_ref: PROFILE, trusted_public_key_pem: merchant.public_to_pem, expected_issuer: "shop",
|
|
70
|
+
not_before: NOW, not_after: NOW + 60, verified_at: NOW)
|
|
71
|
+
raise "receipt failed" unless result.verified? && result.outcome == outcome
|
|
72
|
+
puts "Receipt #{outcome}: authentic=true; purchase_succeeded=#{result.purchase_succeeded?}"
|
|
73
|
+
end
|
|
74
|
+
# Application state, not an SDK purchase permit: durable transaction/CAS in
|
|
75
|
+
# real code must consume approval/challenge/order once and save its receipt.
|
|
76
|
+
states = {"success" => :consumed, "error" => :requires_new_policy_decision, "missing_receipt" => :pending}
|
|
77
|
+
raise "unknown replay" unless states["missing_receipt"] == :pending
|
|
78
|
+
puts "Success=consumed; Error=policy decision; missing Receipt/uncertain commit=pending"
|
|
79
|
+
puts "Synthetic only; evidence and Receipt authenticity are not payment completion."
|
|
80
|
+
{opening: opening, closed: closed, result: checked, host_inputs: host_inputs, saved: saved,
|
|
81
|
+
keys: [provider, agent, merchant], requirements: requirements, checkout: order}
|
|
82
|
+
end
|
|
83
|
+
end
|
|
84
|
+
ConditionalCheckoutExample.run if $PROGRAM_NAME == __FILE__
|