portage-ucp 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7888232b409966ef29fae287d17d6af418dd676e12ad53a7ef7d30d7178f6ae6
-  data.tar.gz: e967bbb103d6911ca4ed8d4fb1204687cd8a2c7a51e3ab7675db5420b7eb0623
+  metadata.gz: 4f3dd667eb94ccfb68762797d5020e233f282d941b4790503a812b01067be09f
+  data.tar.gz: bb3cb10f93333cb720172aa427f2b09b03d186c03b98485b63a8dca9dae8a302
 SHA512:
-  metadata.gz: 3f78f566ac2ee41da063ae9a96a658707bf481f8f9ee791e288fc2d78ce0325ed147c2423a137b06350b3ddb5f64f09c17a5ba6967894e7795ef72c90d6f1384
-  data.tar.gz: 61a0ec7f01125fb8da2e0eb74fdc03b50d4fc94e38a3863e8366b1932cc871ab3787253d3199845a4a18a1902245fb7b2d3ca336b2bd896a82c4ce011d187f5b
+  metadata.gz: 58b3c2ab0aad754862745bf0381e8e37987d2fa8c4da6f80c6460284cb4242d7f9c45e74b83918f6ab032770f38467f6bb62f08cefa06555e2de2dedead2e588
+  data.tar.gz: e9dd08412d7fb321da9118ceb01804a71894da1bca6a7263ffab5ed3efda335657e5c1c2d3bf52d027056bd4a88ab0e6889eacdb9c454103e595ed961a0b885a

data/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [Unreleased]
+
+## [0.12.0] - 2026-10-05
+
+- **Removed the unused `services/shopping/embedded.openrpc.json` schema.** Nothing loaded or listed it (`SchemaValidator` only reads `mcp.openrpc.json`); it just shipped in the gem. Patch-level.
+
+- **Breaking: removed `Portage::Ucp::CapabilityNegotiator`.** Nothing in the gem, the CLI or any adapter ever called `#negotiate`, so no request path used it; it was public but dead. Anyone requiring it directly must carry their own version intersection. Minor-level change for a pre-1.0 gem.
+
+- **Breaking: removed `Dispatcher#call`'s `agent_profile:` keyword and `SchemaValidator#valid?`.** `Dispatcher#call` accepted `agent_profile:` and ignored it (`Mcp::Server` still logs the profile itself, it just no longer passes it on); a caller passing it now gets an `ArgumentError`. Nothing called `SchemaValidator#valid?`; use `errors_for(...).empty?`. Minor-level change for a pre-1.0 gem.
+
+- **Fixed: `Security::Signature` now raises `MalformedSignatureError` for a trusted JWK whose `x` or `y` isn't valid base64url.** It used to leak a raw `ArgumentError`, which `Rack::SignatureVerification` doesn't rescue, so the request failed with a 500 instead of the 401 `invalid_signature` every other bad signature gets. `Ap2::MandateSignature` already mapped the same input to `InvalidMandateError`. Patch-level.
+
+- **Breaking: `Security::Signature::CURVES`, `Security::Signature::EC_PUBLIC_KEY_OID`, `Ap2::MandateSignature::CURVES` and `Ap2::MandateSignature::EC_PUBLIC_KEY_OID` moved to the new `Security::EcJwk`.** Both verifiers carried identical copies of the curve table and the JWK-to-public-key and raw-to-DER helpers; they now share `Security::EcJwk`, which takes the error class each one raises, so verification and its errors are unchanged. The unread `openssl_name` curve field is gone. Nothing outside the two verifiers read the constants; anyone who did should use `Security::EcJwk::CURVES`. Minor-level change for a pre-1.0 gem.
+
+- **Security hardening: `Security::Signature` compares `Content-Digest` with `OpenSSL.fixed_length_secure_compare`** instead of a hand-rolled Ruby byte loop, keeping the length check first so a wrong-length digest is still a `DigestMismatchError`. No behaviour change otherwise. Patch-level.
+
+## [0.11.0] - 2026-09-29
+
+- `Portage::Ucp::Check` (and `portage-ucp-check`) now follows a `<link rel="ucp" href="...">`
+  manifest pointer in the homepage when `/.well-known/ucp` is missing, the same fallback
+  `portage buy` uses. The report adds `manifest_url` when the manifest came from that link.
+
+- Documentation only, no code change. Fixes two wrong comments. `Authenticator`
+  pointed at a `mutating_only:` option that `Mcp::Server.build` doesn't have:
+  it only authenticates tools whose adapter method takes `idempotency_key:`,
+  and no option changes that. `Manifest#to_h` read as if this manifest reports
+  `"version": "2026-08-25"`. That is what live Shopify stores serve. This
+  manifest reports `UCP_VERSION`, `"2026-04-08"`.
+
 ## [0.10.0] - 2026-09-25
 
 - **Proxy support** (`docs/plans/proxy-support.md` Phases 1 and 3).

data/README.md

@@ -19,7 +19,7 @@ in this gem.
 | `Portage::Ucp::Adapter` | The contract your backend implements — override only the catalog/cart/checkout/order/identity methods you support; the rest stay unadvertised. |
 | `Portage::Ucp::CapabilityRegistry` | Figures out which capabilities an `Adapter` actually backs. |
 | `Portage::Ucp::Dispatcher` | Routes a capability+action call to the right `Adapter` method. |
-| `Portage::Ucp::Mcp::Server` | Wraps an `Adapter` as an MCP server — one `MCP::Tool` per advertised action, stdio or Streamable HTTP. |
+| `Portage::Ucp::Mcp::Server` | Wraps an `Adapter` as an MCP server — one `MCP::Tool` per advertised action; serve it over stdio or Streamable HTTP with the `mcp` gem's transports. |
 | `Portage::Ucp::Manifest` | Builds the signed `/.well-known/ucp` discovery document. |
 | `Portage::Ucp::Rack::ManifestEndpoint` | Serves that manifest over Rack. |
 | `Portage::Ucp::Rack::WebhookEndpoint` | HMAC-verified inbound order-lifecycle webhooks. |
@@ -32,7 +32,7 @@ in this gem.
 | `Portage::Ucp::PolicyGuard` / `Portage::Ucp::Policy` | Per-transaction/rolling/velocity caps and a merchant allowlist, checked before `complete_checkout` dispatch; configured via `portage-cli`'s `portage policy show/set`. |
 | `Portage::Ucp::Support::OfferRanking` / `Portage::Ucp::Support::Escalation` | The offer-ranking rule (buyable, then priced, then cheapest, ties stable) and the escalation rule (`requires_escalation`, then a mismatch). `portage-ucp-decision` wraps both as typed verdicts; `portage-cli` calls them directly. |
 | `Portage::Ucp::PaymentEnrollmentGuard` | Validates every `create_payment_enrollment`/`get_payment_enrollment` result an `Adapter` returns — `status` must be `"pending"` (with a `setup_url`, no `payment_token`) or `"complete"` (with a `payment_token`, no `setup_url`). Runs automatically in `Dispatcher#call`. |
-| `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and shape-only validation (required fields + expiry — not cryptographic verification) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
+| `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and validation (required fields + expiry, plus signature verification when `mandate_trusted_keys` is configured) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
 
 Security defaults are all locked down, not permissive-by-omission —
 `UnconfiguredAuthenticator` rejects every mutating call until you configure a real

data/lib/portage/ucp/ap2/mandate_signature.rb

@@ -1,5 +1,6 @@
 require "openssl"
 require "base64"
+require_relative "../security/ec_jwk"
 
 module Portage
   module Ucp
@@ -14,13 +15,12 @@ module Portage
       #
       # Same ECDSA/JWK wire conventions as Security::Signature (P-256
       # mandatory/P-384 optional, raw r||s signature bytes, JWK x/y
-      # coordinates) since that curve support is already proven against this
-      # gem's RFC 9421 verifier — but deliberately a separate class, not a
-      # shared one: a mandate isn't an HTTP request (no method/path/headers
-      # to canonicalize, just PaymentMandate#signing_payload), and
-      # Security::Signature's own class doc already frames every signing
-      # story in this gem as deliberately distinct rather than unified under
-      # one abstraction.
+      # coordinates), and the same Security::EcJwk helpers for them, since
+      # that curve support is already proven against this gem's RFC 9421
+      # verifier. The verifier itself stays separate: a mandate isn't an
+      # HTTP request (no method/path/headers to canonicalize, just
+      # PaymentMandate#signing_payload), and Security::Signature's own class
+      # doc frames every signing story in this gem as deliberately distinct.
       #
       # Trust anchor: `trusted_keys` here is the mandate *issuer's* key set
       # (the shopper's agent, or the agent platform vouching for it) — a
@@ -30,12 +30,6 @@ module Portage
       # convention, reused again here rather than inventing a second
       # differently-shaped key config for the same job).
       module MandateSignature
-        CURVES = {
-          "P-256" => { oid: "1.2.840.10045.3.1.7", coord: 32, digest: "SHA256" },
-          "P-384" => { oid: "1.3.132.0.34", coord: 48, digest: "SHA384" }
-        }.freeze
-        EC_PUBLIC_KEY_OID = "1.2.840.10045.2.1".freeze
-
         # @param mandate [PaymentMandate]
         # @param trusted_keys [Array<Hash>, #call] JWK hash set (or
         #   resolver #call(kid) => JWK hash or nil), keyed by `kid` — see
@@ -49,8 +43,8 @@ module Portage
           curve = curve_for!(jwk)
           raw_signature = sized_signature!(mandate, curve)
 
-          key = ec_public_key(jwk, curve)
-          der = raw_to_der(raw_signature, curve[:coord])
+          key = Security::EcJwk.public_key(jwk, curve, error: Portage::Ucp::InvalidMandateError)
+          der = Security::EcJwk.raw_to_der(raw_signature, curve[:coord])
           verified = key.verify(curve[:digest], der, mandate.signing_payload)
           raise Portage::Ucp::InvalidMandateError, "mandate signature does not verify" unless verified
 
@@ -75,7 +69,9 @@ module Portage
           raise Portage::Ucp::InvalidMandateError, "unsupported key type #{kty.inspect}" unless kty == "EC"
 
           crv = jwk["crv"] || jwk[:crv]
-          CURVES.fetch(crv) { raise Portage::Ucp::InvalidMandateError, "unsupported curve #{crv.inspect}" }
+          Security::EcJwk::CURVES.fetch(crv) do
+            raise Portage::Ucp::InvalidMandateError, "unsupported curve #{crv.inspect}"
+          end
         end
         private_class_method :curve_for!
 
@@ -104,44 +100,6 @@ module Portage
           raise Portage::Ucp::InvalidMandateError, "mandate signature isn't valid base64"
         end
         private_class_method :decode_signature
-
-        # Same DER-from-raw-JWK-coordinates construction as
-        # Security::Signature#ec_public_key, for the same reason: the
-        # OpenSSL::PKey::EC#public_key= setter no longer works since EC keys
-        # became immutable in the openssl gem's OpenSSL 3.0 support.
-        def self.ec_public_key(jwk, curve)
-          x = decode_base64url(jwk["x"] || jwk[:x])
-          y = decode_base64url(jwk["y"] || jwk[:y])
-          raise Portage::Ucp::InvalidMandateError, "JWK missing x/y" if x.nil? || y.nil?
-
-          octet_string = "\x04".b + x + y
-          der = OpenSSL::ASN1::Sequence.new([
-                                              OpenSSL::ASN1::Sequence.new([
-                                                                            OpenSSL::ASN1::ObjectId.new(EC_PUBLIC_KEY_OID),
-                                                                            OpenSSL::ASN1::ObjectId.new(curve[:oid])
-                                                                          ]),
-                                              OpenSSL::ASN1::BitString.new(octet_string)
-                                            ]).to_der
-          OpenSSL::PKey::EC.new(der)
-        end
-        private_class_method :ec_public_key
-
-        def self.raw_to_der(raw_signature, coord)
-          r = OpenSSL::BN.new(raw_signature.byteslice(0, coord), 2)
-          s = OpenSSL::BN.new(raw_signature.byteslice(coord, coord), 2)
-          OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]).to_der
-        end
-        private_class_method :raw_to_der
-
-        def self.decode_base64url(value)
-          return nil unless value
-
-          padded = value + ("=" * ((4 - (value.length % 4)) % 4))
-          Base64.urlsafe_decode64(padded)
-        rescue ArgumentError
-          raise Portage::Ucp::InvalidMandateError, "JWK coordinate isn't valid base64url"
-        end
-        private_class_method :decode_base64url
       end
     end
   end

data/lib/portage/ucp/authenticator.rb

@@ -4,10 +4,11 @@ module Portage
     #   tool call, return an auth context (any truthy value) or raise
     #   Portage::Ucp::AuthenticationError. There is deliberately no default that
     #   allows anonymous mutation — an unconfigured server rejects every
-    #   mutating capability call (see UNCONFIGURED below). Read-only catalog
-    #   calls MAY be left open at the consumer's explicit choice by not
-    #   requiring authentication for those specific actions (see
-    #   Mcp::Server.build's `mutating_only:`).
+    #   mutating capability call (see UnconfiguredAuthenticator below).
+    #   Mcp::Server.build calls it only for mutating tools: those whose
+    #   adapter method takes `idempotency_key:`. Every other tool (catalog
+    #   search, product, cart, checkout and order lookups) never reaches it,
+    #   and Server.build has no option to change that.
     class Authenticator
       def call(_server_context)
         raise NotImplementedError, "#{self.class} must implement #call"

data/lib/portage/ucp/check.rb

@@ -8,7 +8,9 @@ module Portage
     # `portage-ucp-check <url>` — point it at any storefront and find out what
     # portage-ucp can do with it. Checks for a native `/.well-known/ucp`
     # manifest first (the store may already speak UCP without this gem, see
-    # README's "Why /.well-known/ucp?"); if there isn't one, detects the
+    # README's "Why /.well-known/ucp?"), then a `<link rel="ucp" href=...>`
+    # manifest pointer in the homepage (the same fallback `portage buy`
+    # follows); if there isn't one, detects the
     # commerce platform from the page itself (see Resolver) and names
     # the matching portage-ucp-<adapter> gem — probing it live when that
     # adapter's env vars are already set, so "best match" means a
@@ -30,6 +32,10 @@ module Portage
         return { url: @uri.to_s, native_ucp: manifest } if manifest
 
         body, headers = fetch_homepage
+        linked = manifest_link(body)
+        manifest = linked && fetch_json(linked)
+        return { url: @uri.to_s, native_ucp: manifest, manifest_url: linked.to_s } if manifest
+
         platform = Resolver.detect_platform(body, headers)
 
         report = { url: @uri.to_s, native_ucp: nil, platform: platform&.name, recommended_gem: platform&.gem }
@@ -42,7 +48,11 @@ module Portage
       def fetch_manifest
         manifest_uri = @uri.dup
         manifest_uri.path = MANIFEST_PATH
-        response = get(manifest_uri)
+        fetch_json(manifest_uri)
+      end
+
+      def fetch_json(uri)
+        response = get(uri)
         return nil unless response.is_a?(Net::HTTPSuccess)
 
         JSON.parse(response.body)
@@ -59,6 +69,18 @@ module Portage
         [nil, {}]
       end
 
+      # `<link rel="ucp" href="...">` in either attribute order, resolved
+      # against the store URL.
+      def manifest_link(body)
+        return nil unless body
+
+        match = body.match(/<link[^>]+rel=["']ucp["'][^>]+href=["']([^"']+)["']/i) ||
+                body.match(/<link[^>]+href=["']([^"']+)["'][^>]+rel=["']ucp["']/i)
+        match && URI.join(@uri, match[1])
+      rescue URI::Error
+        nil
+      end
+
       def probe(platform)
         env = Resolver.env_for(platform)
         missing = Resolver.missing_env(platform, env)

data/lib/portage/ucp/dispatcher.rb

@@ -76,13 +76,7 @@ module Portage
       #   Dispatcher.call is also the conformance kit's
       #   (lib/portage/ucp/rspec.rb) and specs' direct entry point, outside
       #   any MCP request (§23).
-      # @param agent_profile [String, nil] caller-supplied `ucp-agent.profile`
-      #   hint from `_meta` (see Mcp::Server.agent_profile_for). Dispatcher
-      #   has no direct Observability.log call of its own to thread this
-      #   into — accepted here purely so callers that already pass
-      #   correlation_id: have a matching, equally optional slot; existing
-      #   callers that omit it are unaffected.
-      def call(capability:, action:, arguments: {}, correlation_id: nil, agent_profile: nil)
+      def call(capability:, action:, arguments: {}, correlation_id: nil)
         capability_definition = @registry.find(capability)
         raise UnknownCapabilityError, capability if capability_definition.nil?
 

data/lib/portage/ucp/manifest.rb

@@ -32,10 +32,11 @@ module Portage
       end
 
       # Nests everything under a "ucp" envelope, and keys `capabilities` by
-      # capability name (matching what live Shopify UCP rollouts — Casper,
-      # Allbirds, Glossier, and 34+ others — actually serve as of manifest
-      # "version": "2026-08-25"; see docs/well-known-ucp.md and
-      # portage-ucp-client's Client.discover, which this shape now matches).
+      # capability name. That is the shape live Shopify UCP rollouts (Casper,
+      # Allbirds, Glossier, and 34+ others) serve under their own manifest
+      # "version": "2026-08-25", and the shape portage-ucp-client's
+      # Client.discover reads. Only the shape is borrowed: `version` here is
+      # still UCP_VERSION ("2026-04-08"), the spec revision this gem targets.
       def to_h
         ucp = {
           version: UCP_VERSION,

data/lib/portage/ucp/mcp/server.rb

@@ -70,7 +70,7 @@ module Portage
                          capability: capability.name, action: action_name, arguments: kwargs)
 
           result = context.dispatcher.call(capability: capability.name, action: action_name, arguments: kwargs,
-                                           correlation_id: correlation_id, agent_profile: agent_profile)
+                                           correlation_id: correlation_id)
           ::MCP::Tool::Response.new(result[:content], structured_content: result[:structuredContent])
         end
 

data/lib/portage/ucp/schema_validator.rb

@@ -34,10 +34,6 @@ module Portage
         schemer.validate(data).map { |error| JSONSchemer::Errors.pretty(error) }
       end
 
-      def valid?(relative_path, data)
-        errors_for(relative_path, data).empty?
-      end
-
       # Method names declared by a vendored OpenRPC document, e.g.
       # "services/shopping/mcp.openrpc.json" -> %w[create_checkout get_cart ...].
       def method_names(relative_path)

data/lib/portage/ucp/security/ec_jwk.rb

@@ -0,0 +1,56 @@
+require "openssl"
+require "base64"
+
+module Portage
+  module Ucp
+    module Security
+      # The ECDSA/JWK wire conventions Security::Signature (RFC 9421
+      # requests) and Ap2::MandateSignature (payment mandates) share: P-256
+      # mandatory, P-384 optional, a public key from the JWK's raw x/y
+      # coordinates, and raw r||s signature bytes (never ASN.1/DER on the
+      # wire). `coord` is the byte length of each of r/s and of x/y.
+      #
+      # Each caller passes the error class it raises for a malformed JWK, so
+      # a bad key stays a SignatureError for one and an InvalidMandateError
+      # for the other.
+      module EcJwk
+        CURVES = {
+          "P-256" => { oid: "1.2.840.10045.3.1.7", coord: 32, digest: "SHA256" },
+          "P-384" => { oid: "1.3.132.0.34", coord: 48, digest: "SHA384" }
+        }.freeze
+        EC_PUBLIC_KEY_OID = "1.2.840.10045.2.1".freeze
+
+        module_function
+
+        # Builds the public key from raw DER rather than
+        # OpenSSL::PKey::EC#public_key= — that setter no longer works since
+        # EC keys became immutable in the openssl gem's OpenSSL 3.0 support.
+        def public_key(jwk, curve, error:)
+          x = decode_base64url(jwk["x"] || jwk[:x], error: error)
+          y = decode_base64url(jwk["y"] || jwk[:y], error: error)
+          raise error, "JWK missing x/y" if x.nil? || y.nil?
+
+          octet_string = "\x04".b + x + y
+          algorithm = OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::ObjectId.new(EC_PUBLIC_KEY_OID),
+                                                   OpenSSL::ASN1::ObjectId.new(curve[:oid])])
+          OpenSSL::PKey::EC.new(OpenSSL::ASN1::Sequence.new([algorithm, OpenSSL::ASN1::BitString.new(octet_string)]).to_der)
+        end
+
+        def raw_to_der(raw_signature, coord)
+          r = OpenSSL::BN.new(raw_signature.byteslice(0, coord), 2)
+          s = OpenSSL::BN.new(raw_signature.byteslice(coord, coord), 2)
+          OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]).to_der
+        end
+
+        def decode_base64url(value, error:)
+          return nil unless value
+
+          padded = value + ("=" * ((4 - (value.length % 4)) % 4))
+          Base64.urlsafe_decode64(padded)
+        rescue ArgumentError
+          raise error, "JWK coordinate isn't valid base64url"
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/security/signature.rb

@@ -1,5 +1,6 @@
 require "openssl"
 require "base64"
+require_relative "ec_jwk"
 
 module Portage
   module Ucp
@@ -43,16 +44,6 @@ module Portage
       # the gem doesn't assume single-platform trust, without inventing
       # multi-platform discovery logic that isn't pinned anywhere yet.
       class Signature
-        # ECDSA only, per the spec: P-256 mandatory, P-384 optional. `coord`
-        # is the byte length of each of r/s in the required raw r||s
-        # signature encoding (never ASN.1/DER on the wire) and of the JWK's
-        # x/y coordinates.
-        CURVES = {
-          "P-256" => { openssl_name: "prime256v1", oid: "1.2.840.10045.3.1.7", coord: 32, digest: "SHA256" },
-          "P-384" => { openssl_name: "secp384r1", oid: "1.3.132.0.34", coord: 48, digest: "SHA384" }
-        }.freeze
-        EC_PUBLIC_KEY_OID = "1.2.840.10045.2.1".freeze
-
         SIGNATURE_INPUT_FORMAT = /\A(?<label>[!\w-]+)=\((?<components>[^)]*)\)(?<params>.*)\z/
         SIGNATURE_FORMAT = %r{\A[!\w-]+=:(?<value>[A-Za-z0-9+/=]+):\z}
 
@@ -220,56 +211,25 @@ module Portage
 
         def verify_ecdsa!(jwk, base, raw_signature)
           crv = jwk["crv"] || jwk[:crv]
-          curve = CURVES.fetch(crv) { raise MalformedSignatureError, "unsupported curve #{crv.inspect}" }
+          curve = EcJwk::CURVES.fetch(crv) { raise MalformedSignatureError, "unsupported curve #{crv.inspect}" }
           unless raw_signature.bytesize == curve[:coord] * 2
             raise InvalidSignatureError,
                   "signature is the wrong length for #{crv}"
           end
 
-          key = ec_public_key(jwk, curve)
-          der = raw_to_der(raw_signature, curve[:coord])
+          key = EcJwk.public_key(jwk, curve, error: MalformedSignatureError)
+          der = EcJwk.raw_to_der(raw_signature, curve[:coord])
           verified = key.verify(curve[:digest], der, base)
           raise InvalidSignatureError, "signature does not verify" unless verified
         rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::EC::Point::Error, OpenSSL::ASN1::ASN1Error => e
           raise InvalidSignatureError, "signature verification failed: #{e.message}"
         end
 
-        # Builds the public key from raw DER rather than
-        # OpenSSL::PKey::EC#public_key= — that setter no longer works since
-        # EC keys became immutable in the openssl gem's OpenSSL 3.0 support.
-        def ec_public_key(jwk, curve)
-          x = decode_base64url(jwk["x"] || jwk[:x])
-          y = decode_base64url(jwk["y"] || jwk[:y])
-          raise MalformedSignatureError, "JWK missing x/y" if x.nil? || y.nil?
-
-          octet_string = "\x04".b + x + y
-          der = OpenSSL::ASN1::Sequence.new([
-                                              OpenSSL::ASN1::Sequence.new([
-                                                                            OpenSSL::ASN1::ObjectId.new(EC_PUBLIC_KEY_OID),
-                                                                            OpenSSL::ASN1::ObjectId.new(curve[:oid])
-                                                                          ]),
-                                              OpenSSL::ASN1::BitString.new(octet_string)
-                                            ]).to_der
-          OpenSSL::PKey::EC.new(der)
-        end
-
-        def raw_to_der(raw_signature, coord)
-          r = OpenSSL::BN.new(raw_signature.byteslice(0, coord), 2)
-          s = OpenSSL::BN.new(raw_signature.byteslice(coord, coord), 2)
-          OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]).to_der
-        end
-
-        def decode_base64url(value)
-          return nil unless value
-
-          padded = value + ("=" * ((4 - (value.length % 4)) % 4))
-          Base64.urlsafe_decode64(padded)
-        end
-
+        # The length guard comes first: `expected` is from the sender's
+        # Content-Digest header, and fixed_length_secure_compare raises on
+        # a length mismatch.
         def digests_match?(expected, actual)
-          return false unless expected.bytesize == actual.bytesize
-
-          expected.bytes.zip(actual.bytes).reduce(0) { |acc, (byte_a, byte_b)| acc | (byte_a ^ byte_b) }.zero?
+          expected.bytesize == actual.bytesize && OpenSSL.fixed_length_secure_compare(expected, actual)
         end
       end
     end

data/lib/portage/ucp/support/proxy_config.rb

@@ -208,17 +208,13 @@ module Portage
           case spec
           when Profile then spec
           when :direct, "direct" then Profile::DIRECT
-          when Hash then Profile.new(**symbolize_keys(spec))
+          when Hash then Profile.new(**spec.transform_keys(&:to_sym))
           when String, Symbol
             @profiles[spec.to_s] || raise(ConfigError, "unknown proxy profile #{spec.inspect}")
           else
             raise ConfigError, "invalid proxy profile #{spec.inspect}"
           end
         end
-
-        def symbolize_keys(hash)
-          hash.each_with_object({}) { |(key, value), out| out[key.to_sym] = value }
-        end
       end
     end
   end

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.10.0".freeze
+    VERSION = "0.12.0".freeze
   end
 end

data/lib/portage/ucp.rb

@@ -62,7 +62,6 @@ require_relative "ucp/capabilities/payment_method"
 require_relative "ucp/capabilities/shopper_data"
 require_relative "ucp/capabilities/identity_linking"
 require_relative "ucp/capability_registry"
-require_relative "ucp/capability_negotiator"
 require_relative "ucp/dispatcher"
 require_relative "ucp/mcp/server"
 require_relative "ucp/rack/forwarded_request"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-25 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -168,7 +168,6 @@ files:
 - lib/portage/ucp/capabilities/reorder.rb
 - lib/portage/ucp/capabilities/shopper_data.rb
 - lib/portage/ucp/capability.rb
-- lib/portage/ucp/capability_negotiator.rb
 - lib/portage/ucp/capability_registry.rb
 - lib/portage/ucp/check.rb
 - lib/portage/ucp/configuration.rb
@@ -192,6 +191,7 @@ files:
 - lib/portage/ucp/resolver.rb
 - lib/portage/ucp/rspec.rb
 - lib/portage/ucp/schema_validator.rb
+- lib/portage/ucp/security/ec_jwk.rb
 - lib/portage/ucp/security/errors.rb
 - lib/portage/ucp/security/signature.rb
 - lib/portage/ucp/support/amounts.rb
@@ -290,7 +290,6 @@ files:
 - schemas/2026-04-08/schemas/shopping/types/warning_code.json
 - schemas/2026-04-08/schemas/transports/embedded_config.json
 - schemas/2026-04-08/schemas/ucp.json
-- schemas/2026-04-08/services/shopping/embedded.openrpc.json
 - schemas/2026-04-08/services/shopping/mcp.openrpc.json
 homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp
 licenses:

data/lib/portage/ucp/capability_negotiator.rb

@@ -1,70 +0,0 @@
-module Portage
-  module Ucp
-    # Reconciles UCP's capability-version negotiation with MCP's own
-    # transport-level capability negotiation (§10) — they answer different
-    # questions and both apply regardless of transport:
-    # - MCP `initialize` negotiates protocol features (tools/resources/prompts).
-    # - This negotiator picks, per capability, which *version* both sides speak:
-    #   the platform's advertised versions intersected with the versions this
-    #   server (its registry + adapter) actually advertises.
-    #
-    # Over HTTP the platform's advertised versions come from the `UCP-Agent`
-    # header; over stdio there's no header, so they arrive in `initialize`
-    # params instead. Either way this class only deals in the parsed version
-    # list — transports are responsible for extracting it from their own
-    # request shape.
-    #
-    # §23 step 3: §12 promises a `capability_negotiated` event here, but
-    # #negotiate has no call site anywhere in this gem outside its own spec
-    # — nothing in the request path (transport `initialize` handling, or
-    # otherwise) invokes it yet. Wiring the event would mean building that
-    # call site first, which is a bigger change than threading a logger
-    # through an existing collaborator; left undone, and cut from §12
-    # rather than promised.
-    #
-    # §25: the reason there's no call site is structural, not just
-    # unbuilt. `mcp` 0.25.0's `MCP::Server#init`
-    # (lib/mcp/server.rb:608) never reads `params[:_meta]` and never calls
-    # `add_instrumentation_data`, unlike `call_tool` — so nothing at
-    # initialize time reaches `around_request`/`instrumentation_callback`
-    # or the `_meta` mechanism `Mcp::Server.correlation_id_for` already
-    # relies on (§23/§24). And over HTTP,
-    # `StreamableHTTPTransport#handle_initialization`
-    # (lib/mcp/server/transports/streamable_http_transport.rb:812) builds
-    # a `Rack::Request` with full headers but only pulls `HTTP_ORIGIN` out
-    # of it before handing the raw JSON body string to
-    # `ServerSession#handle_json` — a `UCP-Agent` header never crosses into
-    # the server at all. Wiring #negotiate for real means monkeypatching
-    # both (subclass/prepend `MCP::Server#init` to capture
-    # `clientInfo`/`_meta`, and `StreamableHTTPTransport#handle_initialization`
-    # to capture the `UCP-Agent` header), coupling this gem to `mcp`
-    # internals that could silently break on a `mcp` gem upgrade.
-    # Revisiting this needs either an upstream `mcp` gem hook at
-    # initialize time, or a deliberate decision to accept the monkeypatch
-    # coupling — not something to build silently as a side effect of
-    # another task.
-    class CapabilityNegotiator
-      def initialize(registry: CapabilityRegistry.default)
-        @registry = registry
-      end
-
-      # @param adapter [Portage::Ucp::Adapter]
-      # @param platform_versions [Hash<String, Array<String>>] capability name =>
-      #   versions the platform/agent advertises support for. A capability
-      #   absent from this hash falls back to "offer all business-advertised
-      #   versions, newest-first" (§10's stdio fallback, applied uniformly).
-      # @return [Hash<String, String>] capability name => negotiated version.
-      #   A capability with no version in common is omitted, not raised on —
-      #   it simply isn't usable for this session.
-      def negotiate(adapter:, platform_versions: {})
-        @registry.advertised(adapter).each_with_object({}) do |capability, negotiated|
-          business_versions = [capability.version]
-          offered = platform_versions[capability.name]
-
-          version = offered ? (offered & business_versions).first : business_versions.max
-          negotiated[capability.name] = version if version
-        end
-      end
-    end
-  end
-end

data/schemas/2026-04-08/services/shopping/embedded.openrpc.json

@@ -1,634 +0,0 @@
-{
-  "openrpc": "1.3.2",
-  "info": {
-    "title": "UCP Shopping Embedded Protocol",
-    "description": "Embedded Protocol (EP) methods for the UCP shopping service. Methods are sent from Merchant to Host via postMessage using JSON-RPC 2.0. Method prefixes indicate capability scope: ep.{capability} (i.e. ep.checkout). Schema references are logical pointers - actual payload shape is determined by negotiated capabilities.\n\nEmbedded Protocol is a client-to-client postMessage interface, so there is no endpoint URL to access this API. Platforms detect merchant support for this protocol based on the presence of `services[\"dev.ucp.shopping\"][transport=embedded]` in discovery responses.",
-    "version": "2026-04-08"
-  },
-  "servers": [],
-  "methods": [
-    {
-      "name": "ec.ready",
-      "summary": "Handshake from merchant to host",
-      "description": "Initiates the Embedded Checkout Protocol. Merchant declares which delegations it accepts and requests any additional authorization, host responds with optional channel upgrade, auth credential, and initial checkout state.",
-      "params": [
-        {
-          "name": "delegate",
-          "required": true,
-          "schema": {
-            "type": "array",
-            "description": "Delegation types the merchant accepts. Must be subset of checkout.embedded.delegations.",
-            "items": {
-              "type": "string",
-              "pattern": "^[a-z_]+(?:\\.[a-z_]+)*$"
-            },
-            "uniqueItems": true
-          }
-        },
-        {
-          "name": "auth",
-          "schema": {
-            "$ref": "#/components/schemas/auth"
-          }
-        }
-      ],
-      "result": {
-        "name": "readyResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Handshake response from host.",
-              "required": [
-                "ucp"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                },
-                "upgrade": {
-                  "type": "object",
-                  "description": "Channel upgrade instructions. If present, switch to provided MessagePort.",
-                  "properties": {
-                    "port": {
-                      "type": "object",
-                      "description": "MessagePort for upgraded channel. Runtime type is MessagePort."
-                    }
-                  }
-                },
-                "credential": {
-                  "type": "string",
-                  "description": "Requested authorization. Some common examples include API key and OAuth token."
-                },
-                "checkout": {
-                  "type": "object",
-                  "description": "Initial delegation state from host. Fields are permitted only when the corresponding delegation is accepted.",
-                  "properties": {
-                    "payment": {
-                      "$ref": "#/components/schemas/payment_instrument_selection"
-                    },
-                    "fulfillment": {
-                      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment.json"
-                    }
-                  }
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "name": "ec.auth",
-      "summary": "Authorization exchange between host & business.",
-      "description": "Augments Embedded Checkout Protocol by doing auth exchanges per business requirement. Can be used by business to refresh a previously exchanged authorization.",
-      "params": [
-        {
-          "name": "type",
-          "schema": {
-            "$ref": "#/components/schemas/type"
-          }
-        }
-      ],
-      "result": {
-        "name": "authResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Auth response from host containing the requested authorization data.",
-              "required": [
-                "ucp",
-                "credential"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                },
-                "credential": {
-                  "type": "string",
-                  "description": "Requested authorization. Some common examples include API key and OAuth token."
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "name": "ec.error",
-      "summary": "A session-level error has occurred.",
-      "description": "Business notifies host that a session-level error, unrelated to the checkout resource, has occurred.",
-      "params": [
-        {
-          "name": "error",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json",
-            "description": "Session-level error raised by the business."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.start",
-      "summary": "Checkout visible to buyer",
-      "description": "Merchant notifies host that checkout UI is visible and ready for interaction. Sent after successful ec.ready handshake.",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.complete",
-      "summary": "Checkout completed successfully",
-      "description": "Merchant notifies host that order has been placed successfully.",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Final checkout state."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.messages.change",
-      "summary": "Checkout messages changed",
-      "description": "Merchant notifies host that checkout.messages has changed. Includes errors, warnings, and info. Host should update UI accordingly.",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state with updated messages."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.line_items.change",
-      "summary": "Line items changed",
-      "description": "Merchant notifies host that checkout.line_items has changed (item added, removed, quantity updated).",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state with updated line items."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.buyer.change",
-      "summary": "Buyer information changed",
-      "description": "Merchant notifies host that checkout.buyer has changed (email, phone, address updated).",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state with updated buyer."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.totals.change",
-      "summary": "Checkout totals changed",
-      "description": "Merchant notifies host that checkout.totals has changed. Covers all total line updates including taxes, fees, discounts, and fulfillment costs. For changes that also affect a specific domain (e.g., fulfillment cost update), this message MUST be sent after the domain-specific change message (e.g., ec.fulfillment.change).",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state with updated totals."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.payment.change",
-      "summary": "Payment state changed",
-      "description": "Merchant notifies host that checkout.payment has changed (instrument selected, status updated).",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state with updated payment."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ec.payment.instruments_change_request",
-      "summary": "Request payment instrument change",
-      "description": "Merchant requests host to present payment instrument selection UI for the buyer to change their payment method.",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state."
-          }
-        }
-      ],
-      "result": {
-        "name": "instrumentsChangeResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Checkout state after instrument selection.",
-              "required": [
-                "ucp",
-                "checkout"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                },
-                "checkout": {
-                  "type": "object",
-                  "description": "Partial checkout update with payment instrument selection.",
-                  "properties": {
-                    "payment": {
-                      "$ref": "#/components/schemas/payment_instrument_selection"
-                    }
-                  }
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "name": "ec.payment.credential_request",
-      "summary": "Request payment credential",
-      "description": "Merchant requests host to collect payment credential for selected instrument (CVV, 3DS, wallet confirmation).",
-      "params": [
-        {
-          "name": "checkout",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
-            "description": "Current checkout state with selected instrument."
-          }
-        }
-      ],
-      "result": {
-        "name": "credentialResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Checkout state with payment credential ready for completion.",
-              "required": [
-                "ucp",
-                "checkout"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                },
-                "checkout": {
-                  "type": "object",
-                  "description": "Partial checkout update with payment credential.",
-                  "properties": {
-                    "payment": {
-                      "$ref": "#/components/schemas/payment_instruments"
-                    }
-                  }
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "name": "ec.window.open_request",
-      "summary": "Request window open",
-      "description": "The buyer activated a link within checkout. The host MUST present the content to the buyer and respond with a success result, or respond with a window_open_rejected_error error if host policy prevented the navigation.",
-      "params": [
-        {
-          "name": "url",
-          "required": true,
-          "schema": {
-            "type": "string",
-            "format": "uri",
-            "description": "The URL of the resource to present."
-          }
-        }
-      ],
-      "result": {
-        "name": "windowOpenResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Acknowledgement that the host handled the request.",
-              "required": [
-                "ucp"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json#/embedded/methods/ec.fulfillment.change"
-    },
-    {
-      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json#/embedded/methods/ec.fulfillment.address_change_request"
-    },
-    {
-      "name": "ep.cart.ready",
-      "summary": "Handshake from business to host",
-      "description": "Initiates the Embedded Cart Protocol. Business declares which delegation it supports and requests any additional authorization, host responds with optional channel upgrade and auth credential.",
-      "params": [
-        {
-          "name": "delegate",
-          "required": true,
-          "schema": {
-            "type": "array",
-            "description": "Delegation types the merchant accepts.",
-            "items": {
-              "type": "string",
-              "pattern": "^[a-z_]+(?:\\.[a-z_]+)*$"
-            },
-            "uniqueItems": true
-          }
-        },
-        {
-          "name": "auth",
-          "schema": {
-            "$ref": "#/components/schemas/auth"
-          }
-        }
-      ],
-      "result": {
-        "name": "readyResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Handshake response from host.",
-              "required": [
-                "ucp"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                },
-                "upgrade": {
-                  "type": "object",
-                  "description": "Channel upgrade instructions. If present, switch to provided MessagePort.",
-                  "properties": {
-                    "port": {
-                      "type": "object",
-                      "description": "MessagePort for upgraded channel. Runtime type is MessagePort."
-                    }
-                  }
-                },
-                "credential": {
-                  "type": "string",
-                  "description": "Requested authorization. Some common examples include API key and OAuth token."
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "name": "ep.cart.auth",
-      "summary": "Authorization exchange between host & business.",
-      "description": "Augments Embedded Cart Protocol by doing auth exchanges per business requirement. Can be used by business to refresh a previously exchanged authorization.",
-      "params": [
-        {
-          "name": "type",
-          "schema": {
-            "$ref": "#/components/schemas/type"
-          }
-        }
-      ],
-      "result": {
-        "name": "authResult",
-        "schema": {
-          "oneOf": [
-            {
-              "type": "object",
-              "description": "Auth response from host containing the requested authorization data.",
-              "required": [
-                "ucp",
-                "credential"
-              ],
-              "properties": {
-                "ucp": {
-                  "$ref": "#/components/schemas/ucp_success"
-                },
-                "credential": {
-                  "type": "string",
-                  "description": "Requested authorization. Some common examples include API key and OAuth token."
-                }
-              }
-            },
-            {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "name": "ep.cart.error",
-      "summary": "A session-level error has occurred.",
-      "description": "Business notifies host that a session-level error, unrelated to the cart resource, has occurred.",
-      "params": [
-        {
-          "name": "error",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json",
-            "description": "Session-level error raised by the business."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ep.cart.start",
-      "summary": "Cart visible to buyer",
-      "description": "Business notifies host that cart UI is visible and ready for interaction.",
-      "params": [
-        {
-          "name": "cart",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
-            "description": "Current cart state."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ep.cart.complete",
-      "summary": "Cart completed successfully",
-      "description": "Business notifies host that cart building has completed.",
-      "params": [
-        {
-          "name": "cart",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
-            "description": "Final cart state."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ep.cart.line_items.change",
-      "summary": "Line items changed",
-      "description": "Business notifies host that cart.line_items has changed (item added, removed, quantity updated).",
-      "params": [
-        {
-          "name": "cart",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
-            "description": "Current cart state with updated line items."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ep.cart.buyer.change",
-      "summary": "Buyer information changed",
-      "description": "Business notifies host that cart.buyer has changed (email, phone, name updated).",
-      "params": [
-        {
-          "name": "cart",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
-            "description": "Current cart state with updated buyer."
-          }
-        }
-      ]
-    },
-    {
-      "name": "ep.cart.messages.change",
-      "summary": "Cart messages changed",
-      "description": "Business notifies host that cart.messages has changed. Includes errors, warnings, and info. Host should update UI accordingly.",
-      "params": [
-        {
-          "name": "cart",
-          "required": true,
-          "schema": {
-            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
-            "description": "Current cart state with updated messages."
-          }
-        }
-      ]
-    }
-  ],
-  "components": {
-    "schemas": {
-      "ucp_success": {
-        "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/success"
-      },
-      "payment_instruments": {
-        "type": "object",
-        "description": "Payment instruments from host.",
-        "properties": {
-          "instruments": {
-            "type": "array",
-            "items": {
-              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json#/$defs/selected_payment_instrument"
-            },
-            "description": "Available payment instruments."
-          }
-        }
-      },
-      "payment_instrument_selection": {
-        "description": "Payment instruments with selected instrument ID.",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/payment_instruments"
-          },
-          {
-            "properties": {
-              "selected_instrument_id": {
-                "type": "string",
-                "description": "ID of the selected payment instrument."
-              }
-            }
-          }
-        ]
-      },
-      "type": {
-        "type": "string",
-        "description": "The type of authorization data business is requesting from the host.",
-        "examples": [
-          "oauth",
-          "api_key",
-          "jwt"
-        ]
-      },
-      "auth": {
-        "type": "object",
-        "properties": {
-          "type": {
-            "$ref": "#/components/schemas/type"
-          }
-        }
-      }
-    }
-  },
-  "x-delegations": [
-    "payment.instruments_change",
-    "payment.credential",
-    "fulfillment.address_change",
-    "window.open"
-  ]
-}