ap2_mandate_verifier 0.8.0 → 1.1.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.
@@ -0,0 +1,203 @@
1
+ # Ruby SDK public API — 1.0.0
2
+
3
+ **Status: published 1.0.0.**
4
+ This document defines the 1.x contract for the existing Checkout APIs.
5
+ The 1.0.0 release preserves the 0.8.0 runtime behavior, API names and accepted
6
+ formats. Exact distribution identity and validation are in
7
+ [the publication record](POST_RELEASE_100.md); the earlier
8
+ [preparation record](RELEASE_100_CANDIDATE.md) retains its historical status.
9
+
10
+ The SDK supports human-approved Direct orders and conditional Open → Agent Closed
11
+ delegation for the documented profiles. It runs in plain Ruby. Payment Mandates,
12
+ general AP2/Schema compatibility, real Issuer enrollment and application payment
13
+ execution are outside this contract. The adopted AP2 source remains
14
+ `b4587ac1d055888a73b4b21750973cffba961793`.
15
+
16
+ ## Supported entry points
17
+
18
+ All names below are under `AP2MandateVerifier`. Require the Gem with
19
+ `require "ap2_mandate_verifier"`. Arguments are keywords unless shown otherwise;
20
+ the linked contracts specify their complete fields, exact Ruby types and limits.
21
+ No implicit coercion, trust discovery or default current clock is provided.
22
+
23
+ | Entry | Role and returned value | Detailed contract |
24
+ | --- | --- | --- |
25
+ | `ConditionalCheckout.issue_open` | Sign approved merchant/product/quantity conditions for one registered Agent; return `ConditionalCheckout::Open`. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
26
+ | `ConditionalCheckout.issue_closed` | Check Open, Agent binding, Merchant Checkout and conditions; sign and return `ConditionalCheckout::Closed`. | [Conditional API](CONDITIONAL_CHECKOUT.md#public-api-design) |
27
+ | `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) |
28
+ | `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) |
29
+ | `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) |
30
+ | `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) |
31
+ | `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) |
32
+ | `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) |
33
+ | `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) |
34
+
35
+ ### Full Open → Agent Closed verification and input preparation
36
+
37
+ | Entry | Role and returned value |
38
+ | --- | --- |
39
+ | `InputBuilder.trust` / `.restore_trust` | Assemble a selected trust snapshot / restore original trust and selection strings; return `InputBuilder::Trust`. The app authenticates provenance and currentness. |
40
+ | `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. |
41
+ | `InputBuilder.inputs` | Assemble the seven complete-verification keyword inputs as a frozen Hash. It does not produce Evidence. |
42
+ | `InputBuilder.verify` | Assemble business inputs and run complete Open → Agent Closed verification; return `ResearchResult` or non-success `Result`. |
43
+ | `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. |
44
+ | `ResearchResult.verify` | Retained factory for that same pipeline and input contract. Prefer the module-level or InputBuilder entry for new integrations. |
45
+
46
+ The seven raw keywords are `trust_json:`, `selection_json:`, `host_json:`,
47
+ `root_presentation:`, `terminal_jws:`, `host_checkout_jws:` and `verified_at:`.
48
+ The first six are original Strings; `verified_at` is an independently supplied
49
+ integer Unix timestamp. These entries do not accept the separate Direct format.
50
+ See [business inputs and restoration](INPUT_BUILDER.md) and
51
+ [raw input fields](SUPPORT_CONTRACT.md#full-entry-and-required-inputs).
52
+
53
+ ### Preserved partial-verification APIs
54
+
55
+ These published entries remain supported; they are not reclassified as private.
56
+ All return non-success `Result` values with `success? == false` and `evidence == nil`,
57
+ including when their limited check passes. They do not replace either complete
58
+ verification entry.
59
+
60
+ | Entry | Maximum meaning of a passing check |
61
+ | --- | --- |
62
+ | `verify(presentation_json:)` | JSON syntax only: `:unverified / :verification_not_implemented`. |
63
+ | `verify_root_signature(root_jws:, trusted_issuer_public_key_pem:)` | One Root signature, not disclosure closure or authority. |
64
+ | `verify_root_disclosures(presentation:, trusted_issuer_public_key_pem:)` | The existing single-product Root disclosure profile and signature. |
65
+ | `verify_purchase_binding(**inputs)` | The documented Root/Agent/Merchant purchase binding checks. |
66
+ | `verify_scoped_constraints(**inputs)` | The selected supported purchase constraints. |
67
+ | `verify_trusted_scoped_constraints(trust_json:, selection_json:, **inputs)` | Supplied trust selection plus scoped constraints; not the full Host challenge/order contract. |
68
+ | `verify_host_binding(**inputs)` | The supported Host binding checks, without minting successful Evidence through this legacy wrapper. |
69
+
70
+ Existing keyword sets, defaults and partial-pass codes are preserved. See the
71
+ [module entry definitions](../lib/ap2_mandate_verifier.rb) and the
72
+ [Result/Evidence contract](SUPPORT_CONTRACT.md#result-and-evidence).
73
+
74
+ ## Result, object and failure contracts
75
+
76
+ Each API keeps its existing result convention. Do not call `success?` on every
77
+ returned object or infer authorization from an object merely being present.
78
+
79
+ | API family | Success | Non-success |
80
+ | --- | --- | --- |
81
+ | Complete Open → Closed verification | `ResearchResult`: `status == :verified_research`, `code == :scoped_research_verified`, `success? == true`, immutable Evidence. | `Result`: rejected or unavailable, `success? == false`, no Evidence. |
82
+ | `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. |
83
+ | 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. |
84
+ | `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. |
85
+ | `CheckoutJWT.sign` / `.verify` / `.es256_signer` | The listed object or callable. | Redacted `CheckoutJWT::Invalid`. Verification does not return a false Verification object. |
86
+ | Buyer issuance/presentation; Conditional issuance/presentation | The listed object or original wire. | Redacted `Buyer::Invalid` or `ConditionalCheckout::Invalid`. |
87
+ | Receipt reference/signing | The listed String or Signed object. | Redacted `CheckoutReceipt::Invalid`. |
88
+ | 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`. |
89
+
90
+ The four signing/presentation `Invalid` classes above inherit `ArgumentError` and
91
+ use fixed redacted messages without the original cause. A generic `Invalid` or
92
+ verification-failed code does **not** distinguish invalid data from unavailable
93
+ signing/dependency processing. Hold the operation; diagnose through protected app
94
+ observability. A remote signer may have completed signing before a transport
95
+ failure: reconcile the app's issuance record before issuing again.
96
+
97
+ Missing/unknown keywords to `verify_checkout`, `verify_research` and
98
+ `ResearchResult.verify` return `:unavailable / :research_verification_unavailable`.
99
+ Ruby positional-argument errors or invalid keyword expansion can raise before an
100
+ entry executes. Exceptions, process failure and missing results never authorize
101
+ an operation. Existing status/code meanings are preserved; human-readable error
102
+ or diagnostic wording is not a machine interface.
103
+
104
+ ### Supported returned objects and constructors
105
+
106
+ | Type | Supported reads |
107
+ | --- | --- |
108
+ | `Result`, `ResearchResult` | `status`, `code`, `success?`, `rejected?`, `unverified?`, `unavailable?`, `evidence`, `diagnostic`. |
109
+ | `ResearchEvidence` | `[](field)` and `to_h`: the existing immutable Evidence v2 facts, including contract/profile identities and checked bindings. |
110
+ | `InputBuilder::Trust` | `trust_json`, `selection_json`. |
111
+ | `CheckoutJWT::Signed` | `jwt`, `checkout_hash`. |
112
+ | `CheckoutJWT::Verification` | `verified?`, `jwt`, `checkout_hash`, `checkout`, `profile_ref`. |
113
+ | `Buyer::Issued` | `closed_sd_jwt`. |
114
+ | `Buyer::Verification` | `verified?`, `code`, `checkout`, `checkout_hash`, `reference`, `expires_at`. |
115
+ | `ConditionalCheckout::Open` | `root_presentation`. |
116
+ | `ConditionalCheckout::Closed` | `root_presentation`, `terminal_jws`, `checkout_jwt`, `closed_sd_jwt`. |
117
+ | `CheckoutReceipt::Signed` | `jwt`, `reference`. |
118
+ | `CheckoutReceipt::Verification` | `verified?`, `code`, `outcome`, `purchase_succeeded?`, `purchase_rejected?`, `order_id`, `error`, `error_description`. |
119
+ | `Diagnostic` | `stage`, `field`, `reason`, `hint(locale: :en)`, `to_h(locale: :en)`, `[](key)`; `:ja` provides Japanese hints. |
120
+ | `InputBuilder::Invalid` | `diagnostic`, which may be nil if diagnostic construction fails. |
121
+
122
+ `Result.new(status:, code:, diagnostic: nil)` is retained. It accepts only
123
+ registered non-success status/code pairs and raises `ArgumentError` for unsupported
124
+ pairs. It cannot construct successful Evidence. Result/Evidence-producing object
125
+ constructors other than this non-success constructor are private: obtain those
126
+ objects from their listed factories, not `.new`, reflection or deserialization.
127
+ Exception classes are rescue targets, not proof objects. No exception message,
128
+ backtrace or mutable Ruby object identity authenticates a check.
129
+ These objects assume a trusted Ruby process; private construction is API
130
+ discipline, not a sandbox against hostile Ruby code or reflection.
131
+
132
+ Diagnostics are optional guidance. Success has no failure diagnostic; diagnostic
133
+ failure cannot change a verdict. Existing machine identifiers retain their meaning;
134
+ wording/translations and internal lookup-table layout are not frozen.
135
+ See [diagnostic semantics](DIAGNOSTICS.md).
136
+
137
+ ## Profiles and defaults
138
+
139
+ Profile version and Gem version are separate. All three profiles below remain v1.
140
+
141
+ | Profile identifier | Selection and supported lifecycle |
142
+ | --- | --- |
143
+ | `ap2.checkout.single_merchant_sku` | Default for optional `profile_ref:` on InputBuilder trust, CheckoutJWT and CheckoutReceipt. Existing one-product Open → Agent Closed verification. |
144
+ | `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. |
145
+ | `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. |
146
+
147
+ Supported profile constants include `TrustContext::PROFILE_REF`, `PROFILE_VERSION`,
148
+ `PROFILE_BODY` and `PROFILE_HASH`, and its corresponding `MULTI_PROFILE_REF`,
149
+ `MULTI_PROFILE_VERSION`, `MULTI_PROFILE_BODY` and `MULTI_PROFILE_HASH` constants.
150
+ `ConditionalCheckout::PROFILE_REF`, `Buyer::PROFILE_REF` and `Buyer::CHECKOUT_PROFILE`
151
+ are supported as well. Their names and existing v1 values remain stable, including
152
+ the constants used by the documented raw-input example. Profile definitions/hashes,
153
+ accepted shapes, bounds, original-wire reference rules and defaults are
154
+ compatibility-sensitive even when implemented by other internal constants.
155
+ See [multi-item limits](MULTI_ITEM_CHECKOUT.md) and
156
+ [Direct limits](BUYER_DIRECT_CHECKOUT.md#profile-and-limits).
157
+ No received claim selects trusted policy; unknown profiles and constraints fail closed.
158
+
159
+ ## Persistence and trust boundaries
160
+
161
+ - Persist exact signed JWT/SD-JWT and disclosure strings. `ConditionalCheckout.present`
162
+ restores its three original strings; `Buyer.present_closed` restores its one
163
+ original wire. Neither authenticates a restored presentation.
164
+ - Persist InputBuilder preparation format `"1"` and original trust/selection JSON.
165
+ Use `restore` / `restore_trust`; do not regenerate hashes or issue-time references
166
+ to make changed state match. Restoration does not authenticate storage, establish
167
+ freshness or prove an unused nonce.
168
+ - Receipt reference covers only the final original Closed SD-JWT: `terminal_jws + "~"`
169
+ for the existing conditional profile, or the entire disclosed Direct wire with
170
+ its terminal `~`. It is not the Open chain hash, compact-only JWT or rebuilt JSON.
171
+ - `ResearchEvidence#to_h` is an immutable inspection view, not a signed transport
172
+ credential. There is no JSON/Hash/Marshal reconstruction API for authenticated
173
+ Evidence, results, Trust or other checked objects. Persisted original wires must
174
+ be verified again against current independent inputs.
175
+ - Signing callbacks receive frozen ASCII JWS signing input and return 64 binary
176
+ JOSE ES256 signature bytes. The SDK verifies the returned signature with the
177
+ independently supplied public key. The app owns signer access, timeouts, key
178
+ custody and lifecycle; Provider signing material never enters the Agent API.
179
+ - The app authenticates users, consent, registry/keys/revocation, current orders
180
+ and time. It rechecks authorization, atomically consumes/reserves state, handles
181
+ duplicates and reconciles uncertain outcomes. The SDK performs no network, DB
182
+ or payment operation. An authentic Error Receipt is not permission to retry;
183
+ a missing or unverifiable Receipt leaves the application outcome unknown.
184
+
185
+ ## Compatibility and internal boundary
186
+
187
+ The 1.x [versioning, maintenance and deprecation policy](POST_RELEASE_MAINTENANCE.md)
188
+ applies to these calls, types, machine meanings, profiles and persistence contracts.
189
+ The `research` names and syntax-only `verify` keep their current meanings.
190
+ Documented 0.8.0 API use needs no source migration. Dependency constraints must
191
+ allow 1.0.0; see [upgrading from 0.8.0](../README.md#upgrading-from-080).
192
+
193
+ Internal `verified_*!` handoffs are not supported ways to inject checked facts;
194
+ [the existing support contract](SUPPORT_CONTRACT.md#result-and-evidence) already
195
+ excludes them. Private helpers, unlisted validator/factory helpers, diagnostic
196
+ catalogs, internal constant layouts and research/test scripts are implementation
197
+ details, not extension hooks. Ruby visibility alone does not make them an SDK API.
198
+ This does not remove the published partial-verification entries above, their
199
+ observable error behavior, or the documented profile identities and bounds.
200
+
201
+ ## Additive unpublished 1.1.0 candidate
202
+
203
+ The preceding 1.0.0 Checkout contract remains unchanged. New `Payment` and `PaymentReceipt` APIs have a separate [candidate contract](PAYMENT.md); they are not available in published 1.0.0.
@@ -0,0 +1,119 @@
1
+ > Historical preparation snapshot. 1.0.0 was subsequently published on
2
+ > 2026-11-01 08:13:29.733 UTC; the 102,912-byte official distribution matches
3
+ > the retained candidate and all 33 payloads match the release source.
4
+ > See [publication](POST_RELEASE_100.md) and [current release/upgrade](RELEASE_100.md).
5
+ > Unpublished and pending statements below describe the preparation checkpoint.
6
+
7
+ # 1.0.0 candidate — historical preparation
8
+
9
+ **Unpublished candidate. The currently published release is 0.8.0.**
10
+ The candidate Gem has version `1.0.0`; that metadata is not a publication record.
11
+ The [preparation evidence](evidence/1.0.0_preparation.json) identifies the actual
12
+ source, archive, observed checks and remaining gates. A later publication must
13
+ identify the exact approved bytes separately.
14
+
15
+ ## Purpose and supported scope
16
+
17
+ 1.0.0 establishes the [public Ruby API](PUBLIC_API.md) and
18
+ [1.x compatibility and maintenance policy](POST_RELEASE_MAINTENANCE.md).
19
+ It keeps the 0.8.0 runtime implementation and supported Checkout profiles.
20
+
21
+ | Workflow | Included in the public contract |
22
+ | --- | --- |
23
+ | Merchant Checkout | Sign and verify the supported original Checkout JWT. |
24
+ | Direct human-approved order | Issue, present and verify the Provider-signed exact order. |
25
+ | Conditional purchase | Issue Open conditions; generate/present Agent-signed Closed; verify the complete chain with independent current trust, order, challenge and time inputs. |
26
+ | Checkout Receipt | Reference the exact final Closed SD-JWT; sign and verify authentic Success/Error outcomes. |
27
+
28
+ All workflows are plain Ruby. Rails is an integration example. A 1.0.0 SDK
29
+ version does not assert coverage of every AP2 feature, certification, application
30
+ authorization or payment execution. The adopted official AP2 source stays at
31
+ `b4587ac1d055888a73b4b21750973cffba961793`.
32
+
33
+ ## Changes from 0.8.0
34
+
35
+ - Explicit public API, return/exception, profile/default and persistence contracts.
36
+ - Current SDK metadata, security reporting, maintenance and product guidance.
37
+ - Aligned 1.0.0 package checks and development lockfile; newly packaged public API,
38
+ input preparation, security and maintenance documentation.
39
+ - Independent Python-generated conditional inputs exercised through the public
40
+ complete verifier and Receipt APIs, including installed-Gem mode and signed
41
+ negative controls. Existing internal-boundary comparisons remain separate.
42
+
43
+ There are no runtime `lib/` changes, profile/default changes, new runtime
44
+ dependencies or renamed APIs. Existing `verify_research`, research-named results,
45
+ syntax-only `verify`, saved preparation format `"1"` and Evidence v2 remain.
46
+ MRI 3.4.12 and 4.0.9 remain the formally supported versions. Installation metadata
47
+ `>= 3.4.12, < 4.1` does not certify every version in that range. Runtime pins remain
48
+ JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1.
49
+
50
+ ## Migration and candidate inspection
51
+
52
+ Applications using documented 0.8.0 APIs need no source migration for this
53
+ candidate. A dependency such as `~> 0.8.0` does not select 1.0.0. After publication,
54
+ use an explicit compatible constraint (for example `~> 1.0`) and update this Gem
55
+ in the application's lockfile. Do not treat a successful verification, an
56
+ authentic Receipt or successful installation as application purchase permission.
57
+
58
+ To inspect a prepared local candidate, install its exact file in an isolated
59
+ Gem environment whose fixed dependencies are already installed:
60
+
61
+ ```sh
62
+ gem install --local --no-document /absolute/path/ap2_mandate_verifier-1.0.0.gem
63
+ ruby -rap2_mandate_verifier -e 'puts Gem.loaded_specs.fetch("ap2_mandate_verifier").version'
64
+ 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")'
65
+ ```
66
+
67
+ The standalone synthetic example covers Open → Agent Closed → complete
68
+ verification → Success/Error Receipt. The application's identity, consent,
69
+ key custody, revocation, persistent replay protection and payment integration
70
+ remain its responsibility. Unknown execution outcomes remain pending until the
71
+ application reconciles them.
72
+
73
+ ## Required release evidence
74
+
75
+ | Check | Required evidence |
76
+ | --- | --- |
77
+ | Scope and compatibility | Diff against the 0.8.0 baseline; unchanged runtime code, profile definitions/defaults and five dependency pins; public API/source review. |
78
+ | Source regression | Existing 17 suite entry points on both supported MRI versions, preserving individual results without double-counting transitive suites. |
79
+ | 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. |
80
+ | Installed behavior | Original saved-input/oracle checks, diagnostics, signing/Direct/multi-item/conditional examples and conditional tests loaded from the installed Gem. |
81
+ | 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. |
82
+ | 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. |
83
+ | 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. |
84
+
85
+ The existing Debian-container source/package procedure is
86
+ `scripts/check_ruby_compatibility.sh` followed by
87
+ `scripts/check_candidate_package.sh OUTPUT_DIR ABSOLUTE_GEM_PATH`.
88
+ Pass the **same archive** to each supported Ruby; separately built CI candidates
89
+ do not establish byte identity across runtimes.
90
+
91
+ The conditional interoperability command, from this source checkout, is:
92
+
93
+ ```sh
94
+ AP2_INSTALLED=1 AP2_GEM_VERSION=1.0.0 \
95
+ AP2_OFFICIAL_ROOT=/absolute/path/to/pinned-ap2 \
96
+ PYTHONPATH=/absolute/path/to/pinned-ap2/code/sdk/python \
97
+ python test/conditional_interop.py
98
+ ```
99
+
100
+ `PATH` must select the supported Ruby, and `GEM_HOME`/`GEM_PATH` must select the
101
+ normally installed candidate and fixed dependencies. No product source directory
102
+ may be added to Ruby's load path in installed mode. The Python check asserts
103
+ official source/Schema location consistency and must be run with the recorded
104
+ fixed source and dependency identities. Its supported inline Closed subset does
105
+ not include the official helper's selectively disclosed terminal representation.
106
+
107
+ ## Preparation boundary
108
+
109
+ This work follows the Owner's request to prepare 1.0.0, from main
110
+ `7facf5e21699c754eb3e046ee2c653c6ce2c16cf`. Review covers the public contract,
111
+ metadata/package checks and the additional independent test; the application's
112
+ trust registry and current business state remain independent test inputs.
113
+ Existing Issue #101 process and separate legacy research gates are retained.
114
+ Unexpected source/dependency drift, secret exposure, unplanned external cost,
115
+ inconclusive checks or substantive review findings block release readiness.
116
+
117
+ Current public distribution remains 0.8.0 until its successor is actually
118
+ published and verified. A local pass, review result, PR or candidate artifact is
119
+ not a release, real-Issuer attestation or production authorization.
@@ -0,0 +1,30 @@
1
+ # 1.1.0 candidate — publication requires Owner approval
2
+
3
+ Status: unpublished candidate. Published 1.0.0 remains available and unchanged. The source version 1.1.0 is a proposal for additive Payment APIs under the existing 1.x Checkout contract. Do not tag, publish GitHub Release, push/yank RubyGems, announce or deploy on the basis of this document.
4
+
5
+ ## Proposed GitHub Release body
6
+
7
+ Adds framework-independent Direct and conditional Payment Mandates, strict payment conditions/Checkout binding, original-wire persistence/reference helpers, and signed Success/Error Payment Receipts. Existing Checkout API defaults/profiles/results remain unchanged. Payment verification authenticates supported facts; applications still own consent/trust, durable atomic one-use state and payment execution.
8
+
9
+ ```ruby
10
+ payment = AP2MandateVerifier::Payment.details(
11
+ checkout_jwt: original_checkout_from_trusted_order,
12
+ trusted_merchant_public_key_pem: registered_merchant_key,
13
+ expected_merchant_id: current_merchant_id,
14
+ payment_instrument: selected_instrument_from_application)
15
+ # After app authentication and consent: issue_direct(payment: payment,
16
+ # approved_payment: protected_consent_record, ...). See examples/payment.rb.
17
+ ```
18
+
19
+ Supported: one immediate payment, integer minor units, exact payee/instrument and amount range, optional fixed values, one Agent hop. General selective disclosure, recurrence/budgets, PISP/execution_date/risk_data, live processors and A2A/MCP are outside this profile and reject. See [Payment API and specification decisions](PAYMENT.md).
20
+
21
+ ## Approval checklist and publication procedure
22
+
23
+ 1. Confirm latest reviewed/merged source SHA, package contents/source equality, Gem filename/bytes/SHA256 and immutable evidence record in Issue #235. Verify both supported MRI endpoint tests, installed examples, existing Checkout regression, official pinned SDK/Schema bidirectional interoperability and latest-HEAD independent review. Any unresolved substantive finding or missing required test means HOLD.
24
+ 2. Owner explicitly chooses version and approves the exact artifact SHA256, tag/Release and publication/announcement separately. Until then stop. If version/source/artifact changes, rebuild once and repeat affected validation/review; do not reuse approval for a different artifact.
25
+ 3. With separate approval, verify `sha256sum` of the approved Gem and `gem specification ... --local`; push that exact file using Owner-controlled RubyGems credentials. Do not rebuild during publication. Create/push the approved tag on the recorded source SHA and publish the approved Release body only when separately authorized.
26
+ 4. After approved publication, fetch public RubyGems version metadata and distribution, compare SHA256 and dependency/file metadata, install it into a new isolated environment, run packaged Direct/conditional examples and both Receipt outcomes, check README links/version claims. Record evidence before calling publication verified. Unknown outcomes require reconciliation, never blind retry/yank.
27
+
28
+ No publication/deployment workflow is added. Existing product CI is a read-only source/package validation workflow. Existing research HOLDs remain independent.
29
+
30
+ Runtime dependencies remain pinned: json=2.19.9, jwt=3.3.0, base64=0.3.0, openssl=4.0.2, digest=3.2.1. MRI test endpoints remain 3.4.12 and 4.0.9; installation range >=3.4.12,<4.1 is not a claim of formal support for every intermediate Ruby.
@@ -1,6 +1,54 @@
1
- # Fixed-profile AP2 verification — published 0.7.0 / history
2
-
3
- ## Unpublished 0.8.0 additive candidate
1
+ # AP2 Checkout Ruby SDK — support contract and history
2
+
3
+ ## Current contract — published 1.0.0
4
+
5
+ **Published stable is 1.0.0.** It preserves the 0.8.0 product implementation and
6
+ acceptance contracts. The stable 1.x public surface is catalogued in
7
+ [PUBLIC_API](PUBLIC_API.md); exact distribution identity and validation are in
8
+ [the publication record](POST_RELEASE_100.md). The earlier
9
+ [preparation record](RELEASE_100_CANDIDATE.md) and older observations below retain
10
+ their historical scope; they are not new post-publication test results.
11
+
12
+ Registered 2026-11-01 **08:13:29.733 UTC**; official download comparison completed
13
+ **08:16:01 UTC**. The 102,912-byte Gem, SHA256
14
+ `a107101b0178c54ba417be7a2bd7e22feb2fd9a07bda089043e8c5ea8e65e12b`,
15
+ matches the retained candidate exactly, and all 33 payloads match source
16
+ `59e344ad865ed867d0993120456f9411d82bcdec`. Source association comes from
17
+ candidate/payload comparison, not RubyGems source attestation.
18
+ [Publication receipt](evidence/1.0.0_publication.json). The published Gem's documents
19
+ retain their preparation snapshot; repository updates do not rebuild or replace it.
20
+
21
+ | Current supported flow | Contract |
22
+ | --- | --- |
23
+ | Direct exact-order approval | Checkout authentication, Provider Closed issuance, original presentation, full Direct verification and Receipt confirmation: [Direct](BUYER_DIRECT_CHECKOUT.md). |
24
+ | Conditional purchase delegation | Provider Open issuance, Agent Closed generation/presentation, existing full verification and Receipt confirmation: [Conditional Checkout](CONDITIONAL_CHECKOUT.md). |
25
+ | 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). |
26
+ | Merchant signing and Receipts | Checkout signing and explicit Success/Error outcome authentication with original-wire references: [Merchant signing](MERCHANT_SIGNING.md). |
27
+
28
+ Formal support remains MRI 3.4.12 and MRI 4.0.9 with JSON 2.19.9, JWT 3.3.0,
29
+ base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. The Gem's Ruby resolution range
30
+ does not certify every intervening version, engine, OS or native provider.
31
+ AP2 source `b4587ac1d055888a73b4b21750973cffba961793`, the three documented v1
32
+ profile identities and InputBuilder preparation format `1` remain unchanged.
33
+
34
+ Each API retains its result/exception convention, including the existing `research`
35
+ names and partial APIs' non-success behavior. A verification failure or signing
36
+ `Invalid` is not automatically proof of malformed business data; see
37
+ [failure handling](PUBLIC_API.md#result-object-and-failure-contracts).
38
+ The app owns current trust, consent, durable state and final execution. Ruby SDK
39
+ support does not establish general AP2 compatibility, Payment support, actual
40
+ Issuer trust or a particular Host's production authorization.
41
+
42
+ The [maintenance policy](POST_RELEASE_MAINTENANCE.md) governs 1.x
43
+ versioning, dependency changes, security corrections and deprecation. The sections
44
+ below preserve older publication evidence and API details; statements explicitly
45
+ scoped to old versions do not remove the current flows listed above.
46
+
47
+ Documented 0.8.0 API use needs no source migration. A constraint such as `~> 0.8.0`
48
+ does not select 1.0.0; use an appropriate 1.x constraint such as `~> 1.0` and update
49
+ the application lockfile. See [release and migration notes](RELEASE_100.md).
50
+
51
+ ## Historical 0.8.0: conditional delegation
4
52
 
5
53
  `ConditionalCheckout.issue_open/issue_closed/present` add conditional delegation
6
54
  issuance and original-wire presentation under the unchanged explicit multi-item
@@ -8,7 +56,12 @@ profile v1. [Contract, errors, limits and application responsibilities](CONDITIO
8
56
  The packaged standalone example uses only public installed APIs. No old default,
9
57
  profile definition/hash, Result/Evidence/diagnostic, saved record or Receipt
10
58
  acceptance condition is changed. All candidates remain required; no new selective
11
- disclosure profile is introduced. Published stable remains 0.7.0.
59
+ disclosure profile is introduced. Version 0.8.0 was registered
60
+ 2026-11-01 06:01:31.103 UTC and compared 06:03:20 UTC: 79,872 bytes, SHA256
61
+ `6c07664e4291aa8bc025b152075869322411a0d99861e1267959f1794e99acec`.
62
+ All29 payloads match published source `5a7394c1b98f000b321423e2c2f80d50b5157808`.
63
+ [Publication and new installed-Gem checks](POST_RELEASE_080.md). The archive's
64
+ candidate-time documents remain unchanged; repository updates do not replace it.
12
65
 
13
66
  Published 0.7.0 adds the separate [Direct buyer module](BUYER_DIRECT_CHECKOUT.md):
14
67
  merchant Checkout verification before human approval, Provider-signed issuance,
@@ -21,7 +74,7 @@ match source `9b4b78a7ed9aa95e7d35e01a64efc1281ba95be3`.
21
74
  [Publication record](PROJECT_STATUS.md#070-publication). Older version statements below
22
75
  retain their historical scope; they do not exclude the new Direct APIs.
23
76
 
24
- ## Current source: explicit multi-item profile
77
+ ## Historical 0.6.0: explicit multi-item profile
25
78
 
26
79
  Published **0.6.0** adds the explicitly
27
80
  selected `ap2.checkout.single_merchant_multi_item` v1 across input preparation,
@@ -118,13 +171,13 @@ Gem-owned signature/original-wire/closure, delegation, binding, supplied-trust s
118
171
  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.
119
172
  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.
120
173
 
121
- No worst-case CPU/RSS/concurrency or numeric SLA is promised. Host process/time/memory/concurrency limits supplement, not replace, Gem finite input bounds. Product Mandate issuance/presentation, 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).
174
+ 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).
122
175
  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.
123
176
 
124
177
  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.
125
178
  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.
126
179
 
127
- Initial maintenance contact: Owner cuichangquan via repository Issues for ordinary bugs and private vulnerability reporting for vulnerabilities. No secrets, real Mandates or personal data in reports. Maintain only the latest patch in the selected initial stable series; no prerelease/old-series backport, fixed support years, response/fix/disclosure deadline or 24/7 promise.
180
+ 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.
128
181
  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.
129
182
 
130
183
  ## Existing API/limits and historical evidence baseline
@@ -242,6 +295,11 @@ constructors do not sandbox malicious Ruby/reflection in that same process.
242
295
 
243
296
  ## Parsing, schema and time boundaries
244
297
 
298
+ The single-product shape/count statements in this section preserve the original
299
+ profile. The [multi-item](MULTI_ITEM_CHECKOUT.md) and
300
+ [Direct](BUYER_DIRECT_CHECKOUT.md) contracts specify their separate shapes and
301
+ limits; the [conditional API](CONDITIONAL_CHECKOUT.md) reuses the multi-item profile.
302
+
245
303
  Header/payload parse before signature enforces strict bounded syntax only.
246
304
  JSON2.19.9 duplicate rejection remains on, including escaped duplicate keys;
247
305
  BOM/comments/trailing commas/nonfinite numbers are rejected. JOSE is fixed alg/
@@ -0,0 +1,67 @@
1
+ # frozen_string_literal: true
2
+ # Installed Gem only; every payment/processor result is synthetic.
3
+ require "ap2_mandate_verifier"
4
+ require_relative "conditional_checkout"
5
+ module PaymentExample
6
+ M = AP2MandateVerifier
7
+ NOW = ConditionalCheckoutExample::NOW
8
+ def self.run
9
+ state = ConditionalCheckoutExample.run
10
+ provider, agent, merchant = state.fetch(:keys)
11
+ sign = ->(key) { M::CheckoutJWT.es256_signer(private_key: key) }
12
+ checkout = state.fetch(:closed).checkout_jwt
13
+ # External application selects the instrument and independently trusts order/key.
14
+ details = M::Payment.details(checkout_jwt: checkout, trusted_merchant_public_key_pem: merchant.public_to_pem,
15
+ expected_merchant_id: "shop", payment_instrument: {"id" => "synthetic-card", "type" => "card"})
16
+ direct_checkout = M::Buyer.issue_closed(checkout_jwt: checkout, approved_checkout_jwt: checkout,
17
+ trusted_merchant_public_key_pem: merchant.public_to_pem, expected_merchant_id: "shop",
18
+ issued_at: NOW, expires_at: NOW+60, signer: sign.call(provider), public_key_pem: provider.public_to_pem)
19
+ direct_inputs = {closed_sd_jwt: direct_checkout.closed_sd_jwt, expected_checkout_jwt: checkout,
20
+ trusted_provider_public_key_pem: provider.public_to_pem, trusted_merchant_public_key_pem: merchant.public_to_pem,
21
+ expected_merchant_id: "shop", verified_at: NOW}
22
+ # In a real application approved_payment is read from its protected consent record.
23
+ direct = M::Payment.issue_direct(payment: details, approved_payment: details, issued_at: NOW,
24
+ expires_at: NOW+60, signer: sign.call(provider), public_key_pem: provider.public_to_pem)
25
+ base = {expected_payment: details, trusted_provider_public_key_pem: provider.public_to_pem, verified_at: NOW}
26
+ direct_check = M::Payment.verify(**base, closed_sd_jwt: direct.closed_sd_jwt, checkout_mode: :direct, checkout_inputs: direct_inputs)
27
+ raise "Direct failed" unless direct_check.verified?
28
+
29
+ conditions = [{"type" => "payment.amount_range", "currency" => "USD", "max" => 300},
30
+ {"type" => "payment.allowed_payees", "allowed" => [details.fetch("payee")]},
31
+ {"type" => "payment.allowed_payment_instruments", "allowed" => [details.fetch("payment_instrument")]}]
32
+ opening = M::Payment.issue_open(open_checkout_sd_jwt: state.fetch(:opening).root_presentation,
33
+ constraints: conditions, fixed: {"payment_instrument" => details.fetch("payment_instrument")},
34
+ agent_public_key_pem: agent.public_to_pem, issued_at: NOW, expires_at: NOW+60,
35
+ signer: sign.call(provider), public_key_pem: provider.public_to_pem)
36
+ closed = M::Payment.issue_closed(open_sd_jwt: opening, payment: details,
37
+ trusted_provider_public_key_pem: provider.public_to_pem, agent_public_key_pem: agent.public_to_pem,
38
+ audience: "credential-provider", nonce: "synthetic-payment-nonce", verified_at: NOW, signer: sign.call(agent))
39
+ restored = M::Payment.present(open_sd_jwt: opening, closed_sd_jwt: closed.closed_sd_jwt)
40
+ # Reuse existing complete Checkout input preparation; no facts from Payment claims.
41
+ raw = M::InputBuilder.inputs(**state.fetch(:host_inputs), saved_challenge: state.fetch(:saved),
42
+ terminal_jws: state.fetch(:closed).terminal_jws, expected_challenge_issuer_id: "host",
43
+ clock_source_id: "synthetic-clock", verified_at: NOW)
44
+ checked = M::Payment.verify(**base, closed_sd_jwt: restored.closed_sd_jwt, open_sd_jwt: restored.open_sd_jwt,
45
+ checkout_mode: :conditional, checkout_inputs: raw, expected_agent_public_key_pem: agent.public_to_pem,
46
+ expected_audience: "credential-provider", expected_nonce: "synthetic-payment-nonce")
47
+ raise "Conditional failed" unless checked.verified?
48
+ puts "Direct and conditional Payment: verified; no execution permission granted"
49
+ [direct, restored].each do |payment|
50
+ # Alternative simulated outcomes, never two actual executions.
51
+ %w[Success Error].each do |outcome|
52
+ fields = outcome == "Success" ? {psp_confirmation_id: "synthetic-psp", network_confirmation_id: "synthetic-network"} :
53
+ {error: "declined", error_description: "Simulated rejection"}
54
+ receipt = M::PaymentReceipt.sign(closed_sd_jwt: payment.closed_sd_jwt, issuer: "processor",
55
+ payment_id: "synthetic-payment", outcome: outcome, issued_at: NOW, **fields,
56
+ signer: sign.call(merchant), public_key_pem: merchant.public_to_pem)
57
+ result = M::PaymentReceipt.verify(jwt: receipt.jwt, closed_sd_jwt: payment.closed_sd_jwt,
58
+ trusted_public_key_pem: merchant.public_to_pem, expected_issuer: "processor", expected_payment_id: "synthetic-payment",
59
+ not_before: NOW, not_after: NOW+60, verified_at: NOW)
60
+ raise "Receipt failed" unless result.verified? && result.outcome == outcome
61
+ puts "Payment Receipt #{outcome}: authentic=#{result.verified?}; reported_success=#{result.payment_succeeded?}"
62
+ end
63
+ end
64
+ puts "Synthetic only. Persist one-use state atomically. Missing/invalid Receipt = pending; no automatic retry."
65
+ end
66
+ end
67
+ PaymentExample.run if $PROGRAM_NAME == __FILE__