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.
@@ -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.
@@ -1,4 +1,65 @@
1
- # Fixed-profile AP2 verification — published 0.6.0 / history
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. 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).
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
- 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.
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 — unpublished 0.7.0 candidate
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__