portage-ucp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a9198c70ed7abc380268adc344d7496c049a3c78c0ed28b16944e3b27d9d01ba
+  data.tar.gz: c076c1b4e544825d0db160bf2453fed3e256b2024c7aafb8f431227ec22364ef
+SHA512:
+  metadata.gz: 80aac639014575e4416c3e477f451bf9cb25b3cd69ab8a3cda512bd19243d51a95b54c5086b738fc9140be4e0318cb17b81a30767f2ba6b18546b6cd22e9a33b
+  data.tar.gz: dc0f578ee8d379f9f12c4605dcaf37757d5518f2764087186669a4809773b5bd869192328a0027ef61fd36f5a4dbc629697841e57f9065c96a9a5d5d7796c11a

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+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.
+
+## [0.1.0] - Unreleased
+
+- Initial pre-release. Protocol-only core: `Adapter` contract, capability
+  registry, manifest builder, MCP server wrapper, offline `SchemaValidator`,
+  `portage-ucp-check` CLI.
+- `Portage::Ucp::Support`: shared building blocks the adapter gems mix in
+  (money conversion, totals shapes, idempotency dedup, checkout-state
+  tracking, `ApiError`, 404-to-nil reads, Net::HTTP JSON client, OAuth token
+  exchange). Not used by the core gem's own request path.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,97 @@
+# portage-ucp
+
+Protocol-only core gem: expose a commerce backend to AI shopping agents over **MCP**
+([Model Context Protocol](https://modelcontextprotocol.io)) and **UCP**
+([Universal Commerce Protocol](https://ucp.dev)) at once. Zero commerce-backend
+dependencies — works with any backend that implements `Adapter`, Shopify or
+otherwise. Adapter gems (`portage-ucp-shopify`, `portage-ucp-wix`, ...) are
+consumers of this gem, not dependencies of it.
+
+See the [root README](https://github.com/tomtom87/Portage#readme) for the full
+walkthrough (an agent discovering a manifest and buying a snowboard end to end),
+security model, and adapter comparison table. This README covers just what lives
+in this gem.
+
+## What it ships
+
+| Class | Role |
+|---|---|
+| `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::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. |
+| `Portage::Ucp::SchemaValidator` | Validates data against UCP's own vendored JSON Schemas/OpenRPC docs, offline. |
+| `Portage::Ucp::Resolver` / `exe/portage-ucp-check` | Probes any store's homepage/`.well-known/ucp` and recommends the matching adapter gem. |
+
+Security defaults are all locked down, not permissive-by-omission —
+`UnconfiguredAuthenticator` rejects every mutating call until you configure a real
+one, `PaymentTokenGuard` rejects raw card numbers before they reach your `Adapter`,
+and manifest signing is opt-in. Full detail in the root README's
+[Security hooks](https://github.com/tomtom87/Portage#security-hooks--nothing-is-permissive-by-default)
+section.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp"
+```
+
+```bash
+bundle install
+```
+
+## Usage
+
+```ruby
+require "portage/ucp"
+
+class MyAdapter < Portage::Ucp::Adapter
+  def search_catalog(query:, limit:) = ...
+  def get_product(product_id:) = ...
+  def create_cart(line_items:, idempotency_key:) = ...
+  # override only the capabilities you support
+end
+
+Portage::Ucp.configure do |config|
+  config.authenticator = MyAuthenticator.new
+  config.rate_limiter = MyRateLimiter.new
+  config.business = { name: "Your Store", url: "https://your-shop.example" }
+end
+
+server = Portage::Ucp::Mcp::Server.build(adapter: MyAdapter.new)
+server.start
+```
+
+See the root README's [Usage](https://github.com/tomtom87/Portage#usage)
+and the [detailed walkthrough](https://github.com/tomtom87/Portage/blob/main/docs/walkthrough.md)
+for the full agent-side conversation, manifest/webhook Rack mounting, and a real
+adapter to model your own against.
+
+## Checking any store
+
+```bash
+bundle exec portage-ucp-check your-shop.example
+```
+
+Tries `/.well-known/ucp` first; falls back to platform detection and names the
+matching `portage-ucp-<adapter>` gem, live-probing it if credentials are already in
+env. See the root README's [Checking any store](https://github.com/tomtom87/Portage#checking-any-store)
+section for sample output.
+
+## Development
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+See the [design log](https://github.com/tomtom87/Portage/blob/main/docs/design-log.md) for the
+design rationale and decision history behind this project.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage-ucp-check

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Point this at any storefront URL and find out what portage-ucp can do with
+# it: whether it already serves a native /.well-known/ucp manifest, and if
+# not, which portage-ucp-<adapter> gem matches the platform — probed live
+# when that adapter's env vars (see each gem's README) are already set.
+#
+#   portage-ucp-check https://your-shop.myshopify.com
+#   portage-ucp-check your-shop.myshopify.com   # scheme defaults to https
+
+require "json"
+require "portage/ucp"
+
+url = ARGV.first
+if url.nil? || url.empty?
+  warn "usage: portage-ucp-check <store url>"
+  exit 1
+end
+
+report = Portage::Ucp::Check.call(url)
+puts JSON.pretty_generate(report)
+
+found_something = !report[:native_ucp].nil? || report.dig(:live_probe, :status) == "ok"
+exit(found_something ? 0 : 1)

data/lib/portage/ucp/adapter.rb

@@ -0,0 +1,58 @@
+module Portage
+  module Ucp
+    # @abstract Subclass and override the methods for the capabilities you support.
+    #   Unoverridden methods leave that capability out of the manifest.
+    class Adapter
+      # --- Catalog (dev.ucp.shopping.catalog) ---
+      # @return [Array<Portage::Ucp::Product>]
+      def search_catalog(query:, limit:) = not_implemented
+      # @return [Portage::Ucp::Product, nil]
+      def get_product(product_id:) = not_implemented
+
+      # --- Cart (dev.ucp.shopping.cart) ---
+      # Full-replacement semantics, matching UCP's real cart methods: create/
+      # update take the complete desired line_items list, not a single item.
+      # `line_items:` is an array of request-shaped hashes (e.g.
+      # `{product_id:, quantity:}`) — the adapter looks up product data and
+      # builds the response's Item/Total/LineItem itself.
+      # @return [Portage::Ucp::Cart]
+      def get_cart(cart_id:) = not_implemented
+      # @return [Portage::Ucp::Cart]
+      def create_cart(line_items:, idempotency_key:) = not_implemented
+      # @return [Portage::Ucp::Cart]
+      def update_cart(cart_id:, line_items:, idempotency_key:) = not_implemented
+      # @return [Portage::Ucp::Cart]
+      def cancel_cart(cart_id:, idempotency_key:) = not_implemented
+
+      # --- Checkout (dev.ucp.shopping.checkout) ---
+      # @return [Portage::Ucp::Checkout]
+      def create_checkout(line_items:, idempotency_key:) = not_implemented
+      # @return [Portage::Ucp::Checkout]
+      def get_checkout(checkout_id:) = not_implemented
+      # Full-replacement, same as update_cart — line_items is required on
+      # checkout update per the real spec.
+      # @return [Portage::Ucp::Checkout]
+      def update_checkout(checkout_id:, line_items:, idempotency_key:) = not_implemented
+      # @param payment_token [String] single-use token from a UCP payment handler / AP2
+      #   exchange — NEVER a raw PAN.
+      # @return [Portage::Ucp::Checkout]
+      def complete_checkout(checkout_id:, payment_token:, idempotency_key:) = not_implemented
+      # @return [Portage::Ucp::Checkout]
+      def cancel_checkout(checkout_id:, idempotency_key:) = not_implemented
+
+      # --- Order (dev.ucp.shopping.order) ---
+      # @return [Portage::Ucp::Order, nil]
+      def get_order(order_id:) = not_implemented
+
+      # --- Identity Linking (dev.ucp.shopping.identity, OAuth 2.0) ---
+      # @return [Portage::Ucp::Identity] linked profile for an exchanged OAuth token
+      def link_identity(oauth_token:) = not_implemented
+
+      private
+
+      def not_implemented
+        raise Portage::Ucp::NotImplementedError, "#{self.class} does not implement this capability"
+      end
+    end
+  end
+end

data/lib/portage/ucp/authenticator.rb

@@ -0,0 +1,26 @@
+module Portage
+  module Ucp
+    # @abstract Pluggable auth contract (§9). Given the MCP server_context for a
+    #   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:`).
+    class Authenticator
+      def call(_server_context)
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+    end
+
+    # The default when no authenticator is configured: rejects every call it
+    # is asked to authenticate. Never permissive by default (§9).
+    class UnconfiguredAuthenticator < Authenticator
+      def call(_server_context)
+        raise Portage::Ucp::AuthenticationError,
+              "no authenticator configured — mutating capabilities reject all calls until one is set"
+      end
+    end
+  end
+end

data/lib/portage/ucp/capabilities/cart.rb

@@ -0,0 +1,16 @@
+module Portage
+  module Ucp
+    module Capabilities
+      CART = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.cart",
+        version: "1",
+        actions: {
+          "create_cart" => :create_cart,
+          "get_cart" => :get_cart,
+          "update_cart" => :update_cart,
+          "cancel_cart" => :cancel_cart
+        }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capabilities/catalog.rb

@@ -0,0 +1,11 @@
+module Portage
+  module Ucp
+    module Capabilities
+      CATALOG = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.catalog",
+        version: "1",
+        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capabilities/checkout.rb

@@ -0,0 +1,17 @@
+module Portage
+  module Ucp
+    module Capabilities
+      CHECKOUT = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.checkout",
+        version: "1",
+        actions: {
+          "create_checkout" => :create_checkout,
+          "get_checkout" => :get_checkout,
+          "update_checkout" => :update_checkout,
+          "complete_checkout" => :complete_checkout,
+          "cancel_checkout" => :cancel_checkout
+        }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capabilities/identity_linking.rb

@@ -0,0 +1,13 @@
+module Portage
+  module Ucp
+    module Capabilities
+      IDENTITY_LINKING = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.identity",
+        version: "1",
+        actions: { "link_identity" => :link_identity }
+      )
+
+      ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING].freeze
+    end
+  end
+end

data/lib/portage/ucp/capabilities/order.rb

@@ -0,0 +1,11 @@
+module Portage
+  module Ucp
+    module Capabilities
+      ORDER = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.order",
+        version: "1",
+        actions: { "get_order" => :get_order }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capability.rb

@@ -0,0 +1,27 @@
+module Portage
+  module Ucp
+    # A named, versioned UCP capability (e.g. "dev.ucp.shopping.catalog") mapping
+    # UCP action names to the Adapter methods that back them.
+    class Capability
+      attr_reader :name, :version, :actions
+
+      def initialize(name:, version:, actions:)
+        @name = name
+        @version = version
+        @actions = actions
+      end
+
+      # Advertised only if at least one backing Adapter method is overridden —
+      # see Portage::Ucp::Adapter for why (contract can grow without breaking adapters).
+      def advertised_for?(adapter)
+        actions.values.any? { |method_name| overridden?(adapter, method_name) }
+      end
+
+      private
+
+      def overridden?(adapter, method_name)
+        adapter.class.instance_method(method_name).owner != Portage::Ucp::Adapter
+      end
+    end
+  end
+end

data/lib/portage/ucp/capability_negotiator.rb

@@ -0,0 +1,40 @@
+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.
+    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/lib/portage/ucp/capability_registry.rb

@@ -0,0 +1,21 @@
+module Portage
+  module Ucp
+    class CapabilityRegistry
+      def initialize(capabilities:)
+        @capabilities = capabilities
+      end
+
+      def self.default
+        new(capabilities: Portage::Ucp::Capabilities::ALL)
+      end
+
+      def advertised(adapter)
+        @capabilities.select { |capability| capability.advertised_for?(adapter) }
+      end
+
+      def find(name)
+        @capabilities.find { |capability| capability.name == name }
+      end
+    end
+  end
+end

data/lib/portage/ucp/check.rb

@@ -0,0 +1,96 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Portage
+  module Ucp
+    # `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
+    # 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
+    # confirmed-working adapter, not just a guess.
+    class Check
+      MANIFEST_PATH = "/.well-known/ucp".freeze
+      REDIRECT_LIMIT = 5
+
+      def self.call(url) = new(url).call
+
+      def initialize(url)
+        raw = url.to_s.strip
+        raw = "https://#{raw}" unless raw =~ %r{\Ahttps?://}i
+        @uri = URI.parse(raw)
+      end
+
+      def call
+        manifest = fetch_manifest
+        return { url: @uri.to_s, native_ucp: manifest } if manifest
+
+        body, headers = fetch_homepage
+        platform = Resolver.detect_platform(body, headers)
+
+        report = { url: @uri.to_s, native_ucp: nil, platform: platform&.name, recommended_gem: platform&.gem }
+        report[:live_probe] = probe(platform) if platform
+        report
+      end
+
+      private
+
+      def fetch_manifest
+        manifest_uri = @uri.dup
+        manifest_uri.path = MANIFEST_PATH
+        response = get(manifest_uri)
+        return nil unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue StandardError
+        nil
+      end
+
+      def fetch_homepage
+        response = get(@uri)
+        return [nil, {}] unless response.is_a?(Net::HTTPSuccess)
+
+        [response.body, response.to_hash]
+      rescue StandardError
+        [nil, {}]
+      end
+
+      def probe(platform)
+        env = Resolver.env_for(platform)
+        missing = Resolver.missing_env(platform, env)
+        return { status: "skipped", reason: "missing env vars: #{missing.join(', ')}" } if missing.any?
+
+        run_probe(platform, env)
+      end
+
+      def run_probe(platform, env)
+        adapter = Resolver.build_adapter(platform, env)
+        product = adapter.search_catalog(query: "", limit: 1)&.first
+        { status: "ok", sample_product: product && { id: product.id, title: product.title } }
+      rescue LoadError
+        { status: "skipped", reason: "gem not installed: #{platform.gem}" }
+      rescue StandardError => e
+        { status: "error", reason: "#{e.class}: #{e.message}" }
+      end
+
+      def get(uri, limit = REDIRECT_LIMIT)
+        raise Portage::Ucp::Error, "too many redirects" if limit.zero?
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: 5, read_timeout: 5) do |http|
+          http.get(uri.request_uri, { "User-Agent" => "portage-ucp-check" })
+        end
+
+        case response
+        when Net::HTTPRedirection
+          get(URI.join(uri, response["location"]), limit - 1)
+        else
+          response
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/configuration.rb

@@ -0,0 +1,35 @@
+require "logger"
+
+module Portage
+  module Ucp
+    # Global defaults, set once via `Portage::Ucp.configure { |c| ... }`. Nothing
+    # requires this — every collaborator can still be passed explicitly to
+    # Mcp::Server.build/Manifest.new — but it's the one place a consumer wires
+    # up their authenticator/rate limiter/logger without threading them
+    # through every call site.
+    class Configuration
+      attr_accessor :registry, :authenticator, :rate_limiter, :logger,
+                    :business, :signer, :payment_handlers, :signing_keys, :services
+
+      def initialize
+        @registry = CapabilityRegistry.default
+        @authenticator = UnconfiguredAuthenticator.new
+        @rate_limiter = NullRateLimiter.new
+        @logger = Logger.new($stdout)
+        @payment_handlers = []
+        @signing_keys = []
+        @services = []
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+    end
+  end
+end

data/lib/portage/ucp/dispatcher.rb

@@ -0,0 +1,39 @@
+module Portage
+  module Ucp
+    # Accepts a UCP-shaped request (capability + action + arguments), routes it
+    # through the CapabilityRegistry to the backing Adapter method, and wraps
+    # the result as MCP's dual content/structuredContent output (see §5).
+    class Dispatcher
+      def initialize(adapter:, registry: CapabilityRegistry.default)
+        @adapter = adapter
+        @registry = registry
+      end
+
+      def call(capability:, action:, arguments: {})
+        capability_definition = @registry.find(capability)
+        raise UnknownCapabilityError, capability if capability_definition.nil?
+
+        raise CapabilityNotAdvertisedError, capability unless capability_definition.advertised_for?(@adapter)
+
+        method_name = capability_definition.actions[action]
+        raise UnknownActionError, action if method_name.nil?
+
+        Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
+
+        result = @adapter.public_send(method_name, **arguments)
+        wrap(capability, result)
+      end
+
+      private
+
+      def wrap(capability_name, result)
+        unless result.respond_to?(:to_wire_h)
+          return { content: [{ type: "text", text: result.inspect }], structuredContent: result }
+        end
+
+        payload = Portage::Ucp::WireEnvelope.wrap(capability_name, result.to_wire_h)
+        { content: [{ type: "text", text: payload.inspect }], structuredContent: payload }
+      end
+    end
+  end
+end

data/lib/portage/ucp/errors.rb

@@ -0,0 +1,12 @@
+module Portage
+  module Ucp
+    class Error < StandardError; end
+    class NotImplementedError < Error; end
+    class UnknownCapabilityError < Error; end
+    class UnknownActionError < Error; end
+    class CapabilityNotAdvertisedError < Error; end
+    class AuthenticationError < Error; end
+    class RawPanRejectedError < Error; end
+    class RateLimitExceededError < Error; end
+  end
+end

data/lib/portage/ucp/manifest.rb

@@ -0,0 +1,58 @@
+require "json"
+require "base64"
+
+module Portage
+  module Ucp
+    # Builds the /.well-known/ucp discovery document: protocol version, the
+    # business's advertised capabilities (only those the Adapter overrides —
+    # see Capability#advertised_for?), payment handlers, signing keys, and the
+    # services array (transport + endpoint, e.g. {transport: "mcp", endpoint:
+    # "https://..."}) a client needs to find where to actually connect.
+    # Signing keys are never generated here — see §9, consumer-provided only.
+    class Manifest
+      UCP_VERSION = "2026-04-08".freeze
+
+      # @param signer [#kid, #sign] optional. Consumer-provided — the gem never
+      #   generates or stores keys itself (§9). `sign(canonical_json_string)`
+      #   must return raw signature bytes; `kid` identifies which entry in
+      #   `signing_keys` verifies it (supports a current+next key set for
+      #   rotation — the caller picks which signer/kid pair is "current").
+      #   Algorithm-agnostic by design: the gem doesn't dictate Ed25519 vs RSA.
+      def initialize(adapter:, business: Portage::Ucp.configuration.business, registry: Portage::Ucp.configuration.registry,
+                     payment_handlers: Portage::Ucp.configuration.payment_handlers,
+                     signing_keys: Portage::Ucp.configuration.signing_keys, signer: Portage::Ucp.configuration.signer,
+                     services: Portage::Ucp.configuration.services)
+        @adapter = adapter
+        @business = business
+        @registry = registry
+        @payment_handlers = payment_handlers
+        @signing_keys = signing_keys
+        @signer = signer
+        @services = services
+      end
+
+      def to_h
+        payload = {
+          ucp_version: UCP_VERSION,
+          business: @business,
+          services: @services,
+          capabilities: @registry.advertised(@adapter).map do |capability|
+            { name: capability.name, version: capability.version }
+          end,
+          payment_handlers: @payment_handlers,
+          signing_keys: @signing_keys
+        }
+        return payload unless @signer
+
+        payload.merge(signature: sign(payload))
+      end
+
+      private
+
+      def sign(payload)
+        canonical = JSON.generate(payload)
+        { kid: @signer.kid, value: Base64.strict_encode64(@signer.sign(canonical)) }
+      end
+    end
+  end
+end