portage-ucp 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3dd667eb94ccfb68762797d5020e233f282d941b4790503a812b01067be09f
-  data.tar.gz: bb3cb10f93333cb720172aa427f2b09b03d186c03b98485b63a8dca9dae8a302
+  metadata.gz: a245e863596f643972f10c9be20792055d6bf1d2925b90373571966896ee429a
+  data.tar.gz: ad0008e190d5c865e613b616653a7d5dbd5f6b19166f8f71723e57ae70ef7ce0
 SHA512:
-  metadata.gz: 58b3c2ab0aad754862745bf0381e8e37987d2fa8c4da6f80c6460284cb4242d7f9c45e74b83918f6ab032770f38467f6bb62f08cefa06555e2de2dedead2e588
-  data.tar.gz: e9dd08412d7fb321da9118ceb01804a71894da1bca6a7263ffab5ed3efda335657e5c1c2d3bf52d027056bd4a88ab0e6889eacdb9c454103e595ed961a0b885a
+  metadata.gz: d9a93b39705265b1095da290e5615ddbfcf3d3ea529d9b5863308ad99819c70b11ed77bc9805444a003b78c61bb418d4faa756617148d74b964b88beb90b5330
+  data.tar.gz: c2c95f6b3217ea2c2dc6b86318eaa845677b45c753b707ad2eb17f2ae7599f92fe457f7f82a34d46cfea26f1b5bfa8bc17ff4ee46459c94967c6de5ed6286611

data/CHANGELOG.md

@@ -6,6 +6,20 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-09
+
+Moves the gem to UCP 2026-08-25 (design-log §56-58). Minor-level for a pre-1.0 gem, with breaking config changes below.
+
+- **Breaking: `config.payment_handlers` is now a Hash of `reverse-domain-key => [entry, ...]`, each entry carrying an `id`.** Default is `{}` (was an Array). The manifest emits it as UCP 2026-08-25's keyed `payment_handlers` object with date `version`s; an Array no longer works. `config.services` arrays still work: they are keyed by service name and each entry gets a `version`. A services Hash already keyed by name passes through, keeping an entry's own `version`.
+- **Breaking: the manifest emits `keys` (a JWK Set) at the document root; `ucp.signing_keys` is gone.** Anything reading signing keys from `ucp.signing_keys` must read `keys`. Each key needs a `kid`.
+- **Changed: UCP version is 2026-08-25** (manifest, `WireEnvelope`, `SchemaValidator` default). Capabilities are keyed by reverse-domain name with a date `version` and `schema` URL, and the whole manifest validates against `profile.json#/$defs/business_schema`.
+- **Changed: `FulfillmentOption` `description` is sent as a `description.json` object** rather than a bare string, as 2026-08-25 requires.
+- **Removed: the vendored `schemas/2026-04-08/` tree.** `SchemaValidator.new(version: "2026-04-08")` no longer loads; only `schemas/2026-08-25/` ships. Nothing else in the workspace validated against it (`portage-ucp-client` reads remote profiles without vendored schemas, so stores still serving 2026-04-08 keep working).
+
+## [0.13.0] - 2026-10-07
+
+- **Added: `Support::CheckoutState` can ask the platform about a checkout this process doesn't track.** An adapter may define a private `platform_checkout_order(checkout_id)` that returns the `Order` its platform placed from that checkout, or nil. `#checkout_status` then reports `completed` for an id with no in-process record, the new `#checkout_order` returns its `OrderConfirmation`, and the new `#checkout_from_platform_order` rebuilds a completed `Checkout` from the order when the platform has already dropped the cart. A found order is cached through `#record_checkout_status`/`#record_order_checkout`; no order, no hook, or a lookup error keeps today's `incomplete`. This lets `portage orders reconcile`, which runs in a new process, see a checkout the shopper paid for in the browser (design-log §55). The `Adapter` contract is unchanged. Minor-level.
+
 ## [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.

data/lib/generators/portage/ucp/install/templates/portage_ucp.rb

@@ -14,8 +14,8 @@ Portage::Ucp.configure do |config|
 
   # config.signer = MySigner.new
   # config.signing_keys = []
-  # config.payment_handlers = []
-  # config.services = []
+  # config.payment_handlers = {} # { "com.example.pay" => [{ id: "..." }] }
+  # config.services = {}        # { "dev.ucp.shopping" => [{ transport: "mcp", endpoint: "..." }] }
   # config.mandate_trusted_keys = []
   # config.require_mandate_signature = false
 end

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

@@ -4,6 +4,7 @@ module Portage
       CART = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.cart",
         version: "1",
+        schema: "shopping/cart.json",
         actions: {
           "create_cart" => :create_cart,
           "get_cart" => :get_cart,

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

@@ -4,6 +4,7 @@ module Portage
       CATALOG = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.catalog",
         version: "1",
+        schema: "shopping/catalog_search.json",
         actions: { "search_catalog" => :search_catalog, "get_product" => :get_product,
                    "lookup_catalog" => :lookup_catalog }
       )

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

@@ -4,6 +4,7 @@ module Portage
       CHECKOUT = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.checkout",
         version: "1",
+        schema: "shopping/checkout.json",
         actions: {
           "create_checkout" => :create_checkout,
           "get_checkout" => :get_checkout,

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

@@ -8,6 +8,7 @@ module Portage
       DISCOUNT = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.discount",
         version: "1",
+        schema: "shopping/discount.json",
         actions: {},
         predicate: :discount_codes_supported?
       )

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

@@ -8,6 +8,7 @@ module Portage
       FULFILLMENT = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.fulfillment",
         version: "1",
+        schema: "shopping/fulfillment.json",
         actions: {},
         predicate: :fulfillment_supported?
       )

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

@@ -4,6 +4,7 @@ module Portage
       ORDER = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.order",
         version: "1",
+        schema: "shopping/order.json",
         actions: {
           "get_order" => :get_order,
           "cancel_order" => :cancel_order,

data/lib/portage/ucp/capability.rb

@@ -3,7 +3,7 @@ module Portage
     # 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
+      attr_reader :name, :version, :actions, :schema
 
       # `predicate:` is for extension capabilities like
       # dev.ucp.shopping.discount and dev.ucp.shopping.fulfillment that add a
@@ -11,8 +11,13 @@ module Portage
       # there's no dedicated method whose override signals support, so the
       # adapter exposes a boolean method instead and the capability asks it
       # directly rather than inspecting `actions`.
-      def initialize(name:, version:, actions:, predicate: nil)
+      #
+      # `schema:` is the capability's schema path under a UCP revision's
+      # `schemas/` (e.g. "shopping/checkout.json"); the manifest turns it into
+      # the `schema` URL 2026-08-25 business profiles require.
+      def initialize(name:, version:, actions:, predicate: nil, schema: nil)
         @name = name
+        @schema = schema
         @version = version
         @actions = actions
         @predicate = predicate

data/lib/portage/ucp/configuration.rb

@@ -51,7 +51,7 @@ module Portage
         @authenticator = UnconfiguredAuthenticator.new
         @rate_limiter = NullRateLimiter.new
         @logger = Logger.new($stdout)
-        @payment_handlers = []
+        @payment_handlers = {}
         @signing_keys = []
         @services = []
         @require_mandate_signature = false

data/lib/portage/ucp/manifest.rb

@@ -6,11 +6,12 @@ module Portage
     # 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:
+    # services (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
+      UCP_VERSION = "2026-08-25".freeze
+      SERVICE_KEY = "dev.ucp.shopping".freeze
 
       # @param signer [#kid, #sign] optional. Consumer-provided — the gem never
       #   generates or stores keys itself (§9). `sign(canonical_json_string)`
@@ -35,26 +36,47 @@ module Portage
       # 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.
+      # Client.discover reads. As of 2026-08-25 the JWK Set is `keys` beside
+      # `ucp` (not `ucp.signing_keys`), and `services`, `capabilities` and
+      # `payment_handlers` are objects keyed by reverse-domain name whose
+      # entries carry a date `version` (capabilities also a `schema` URL,
+      # handlers an `id`). `services` still accepts the old bare array of
+      # entries, filed under SERVICE_KEY; `payment_handlers` must already be
+      # a Hash of key => [entry, ...].
       def to_h
         ucp = {
           version: UCP_VERSION,
           business: @business,
-          services: @services,
+          services: keyed(service_hash),
           capabilities: capability_hash,
-          payment_handlers: @payment_handlers,
-          signing_keys: @signing_keys
+          payment_handlers: keyed(@payment_handlers)
         }
         ucp = ucp.merge(signature: sign(ucp)) if @signer
 
-        { ucp: ucp }
+        { ucp: ucp, keys: @signing_keys }
       end
 
       private
 
       def capability_hash
-        @registry.advertised(@adapter).to_h { |capability| [capability.name, [{ version: capability.version }]] }
+        @registry.advertised(@adapter).to_h do |capability|
+          entry = { version: UCP_VERSION }
+          entry[:schema] = "https://ucp.dev/#{UCP_VERSION}/schemas/#{capability.schema}" if capability.schema
+          [capability.name, [entry]]
+        end
+      end
+
+      def service_hash
+        return @services if @services.is_a?(Hash)
+
+        @services.empty? ? {} : { SERVICE_KEY => @services }
+      end
+
+      # Every entry needs a version; the caller's own wins.
+      def keyed(entries_by_key)
+        entries_by_key.to_h do |key, entries|
+          [key, [entries].flatten(1).map { |entry| { version: UCP_VERSION }.merge(entry) }]
+        end
       end
 
       def sign(payload)

data/lib/portage/ucp/schema_validator.rb

@@ -9,12 +9,12 @@ module Portage
     # is the CI-safe equivalent).
     #
     # The vendored tree mirrors https://ucp.dev/<version>/... path-for-path
-    # (schemas/2026-04-08/schemas/shopping/cart.json <->
-    # https://ucp.dev/2026-04-08/schemas/shopping/cart.json), so every $ref
+    # (schemas/2026-08-25/schemas/shopping/cart.json <->
+    # https://ucp.dev/2026-08-25/schemas/shopping/cart.json), so every $ref
     # inside a vendored document — however deeply nested — resolves to another
     # vendored file with a single prefix rewrite, no network access needed.
     class SchemaValidator
-      def initialize(version: "2026-04-08", root: File.join(__dir__, "..", "..", "..", "schemas"))
+      def initialize(version: "2026-08-25", root: File.join(__dir__, "..", "..", "..", "schemas"))
         @base_url = "https://ucp.dev/#{version}/"
         @base_dir = File.expand_path(File.join(root, version))
       end

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

@@ -14,7 +14,9 @@ module Portage
       #
       # Both default rather than raise on an unknown id ("incomplete" and "",
       # respectively): a checkout this process didn't create is still
-      # schema-valid to report, just not information-complete.
+      # schema-valid to report, just not information-complete. An adapter
+      # can add a platform lookup for the unknown-id case (see
+      # #platform_order).
       module CheckoutState
         # Dispatcher wraps each adapter call in .with_observability rather
         # than writing [logger, correlation_id] onto an instance variable on
@@ -49,8 +51,77 @@ module Portage
 
         private
 
+        # A checkout this process has no record of falls back to the
+        # platform: `portage orders reconcile` runs in a new process, after
+        # the shopper paid in their browser, and the in-process hash alone
+        # would always say "incomplete" there (design-log §55). See
+        # #platform_order.
         def checkout_status(checkout_id)
-          (@checkout_status ||= {}).fetch(checkout_id, "incomplete")
+          recorded = (@checkout_status ||= {})[checkout_id]
+          return recorded if recorded
+
+          platform_order(checkout_id) ? "completed" : "incomplete"
+        end
+
+        # The order_confirmation for a checkout #platform_order found an order
+        # for, nil otherwise (an in-process #complete_checkout hands its own
+        # back directly).
+        def checkout_order(checkout_id)
+          order = (@platform_orders ||= {})[checkout_id]
+          order && Portage::Ucp::OrderConfirmation.new(id: order.id, permalink_url: order.permalink_url)
+        end
+
+        # For a #get_checkout whose cart read came back not-found: most
+        # platforms drop the cart once it becomes an order (BigCommerce
+        # deletes it on payment, Magento deactivates the quote), so a paid
+        # checkout would otherwise only ever read as not-found. This builds
+        # the completed Checkout from the order the platform reports for it.
+        # No order means nil: a vanished cart on its own is never read as a
+        # completion (docs/plans/handoff-reconcile.md, "Settle only on a
+        # `completed` status the store actually reports").
+        def checkout_from_platform_order(checkout_id)
+          order = platform_order(checkout_id)
+          return nil unless order
+
+          line_items = order.line_items.map do |li|
+            Portage::Ucp::LineItem.new(id: li.id, item: li.item, quantity: li.quantity[:total], totals: li.totals)
+          end
+          Portage::Ucp::Checkout.new(id: checkout_id, status: "completed", line_items: line_items,
+                                     currency: order.currency, totals: order.totals, links: [],
+                                     order: checkout_order(checkout_id))
+        end
+
+        # The optional per-adapter hook: an adapter that can ask its platform
+        # "did this checkout become a placed order?" defines a private
+        # `platform_checkout_order(checkout_id)` returning that Portage::Ucp::
+        # Order, or nil. Without the hook (or when this process already
+        # tracks the checkout) nothing changes. A found order is cached
+        # through #record_checkout_status/#record_order_checkout so the rest
+        # of this process agrees with it. A lookup error is swallowed: the
+        # caller gets today's in-process answer, which reconcile reads as
+        # "still pending", never as a settle. The hook is a private method
+        # rather than a new Adapter method or kwarg for the same §9/§23
+        # reason as .with_observability above.
+        def platform_order(checkout_id)
+          orders = (@platform_orders ||= {})
+          return orders[checkout_id] if orders.key?(checkout_id)
+
+          order = ask_platform(checkout_id)
+          return nil unless order
+
+          orders[checkout_id] = order
+          record_order_checkout(order.id, checkout_id)
+          record_checkout_status(checkout_id, "completed")
+          order
+        end
+
+        def ask_platform(checkout_id)
+          return nil if (@checkout_status ||= {}).key?(checkout_id)
+          return nil unless respond_to?(:platform_checkout_order, true)
+
+          platform_checkout_order(checkout_id)
+        rescue StandardError
+          nil
         end
 
         def record_checkout_status(checkout_id, status)

data/lib/portage/ucp/value_objects.rb

@@ -272,6 +272,8 @@ module Portage
 
     # schemas/shopping/types/fulfillment_option.json — a single priced choice
     # within a FulfillmentGroup (e.g. "Standard Shipping $5", "Express $15").
+    # `description` is a common/types/description.json object
+    # ({"plain"/"html"/"markdown" => ...}); a bare String is sent as `plain`.
     FulfillmentOption = Data.define(:id, :title, :totals, :description, :carrier, :earliest_fulfillment_time,
                                     :latest_fulfillment_time) do
       def initialize(id:, title:, totals:, description: nil, carrier: nil, earliest_fulfillment_time: nil,
@@ -281,7 +283,7 @@ module Portage
 
       def to_wire_h
         h = { "id" => id, "title" => title, "totals" => totals.map(&:to_wire_h) }
-        h["description"] = description if description
+        h["description"] = description.is_a?(String) ? { "plain" => description } : description if description
         h["carrier"] = carrier if carrier
         h["earliest_fulfillment_time"] = earliest_fulfillment_time if earliest_fulfillment_time
         h["latest_fulfillment_time"] = latest_fulfillment_time if latest_fulfillment_time

data/lib/portage/ucp/version.rb

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

data/lib/portage/ucp/wire_envelope.rb

@@ -6,7 +6,7 @@ module Portage
     # capability's minimum envelope shape live in one place, not duplicated
     # across value objects.
     module WireEnvelope
-      SPEC_VERSION = "2026-04-08".freeze
+      SPEC_VERSION = "2026-08-25".freeze
 
       ENVELOPES = {
         "dev.ucp.shopping.cart" => -> { { "version" => SPEC_VERSION } },

data/schemas/{2026-04-08 → 2026-08-25}/schemas/capability.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://ucp.dev/2026-04-08/schemas/capability.json",
+  "$id": "https://ucp.dev/2026-08-25/schemas/capability.json",
   "title": "UCP Capability",
   "description": "Schema for UCP capabilities and extensions. Extensions are capabilities with an 'extends' field. Uses reverse-domain naming for governance.",
   "$defs": {
     "base": {
       "allOf": [
         {
-          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/entity"
+          "$ref": "https://ucp.dev/2026-08-25/schemas/ucp.json#/$defs/entity"
         },
         {
           "type": "object",
@@ -15,14 +15,12 @@
             "extends": {
               "oneOf": [
                 {
-                  "type": "string",
-                  "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+                  "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
                 },
                 {
                   "type": "array",
                   "items": {
-                    "type": "string",
-                    "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+                    "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
                   },
                   "minItems": 1
                 }
@@ -50,10 +48,15 @@
     },
     "business_schema": {
       "title": "Capability (Business Schema)",
-      "description": "Capability configuration for business/merchant level. May include business-specific config overrides.",
+      "description": "Capability declaration for business/merchant discovery. Requires the `schema` URL so platforms can fetch and compose it during negotiation; may also include business-specific config overrides.",
       "allOf": [
         {
           "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "schema"
+          ]
         }
       ]
     },
@@ -67,4 +70,4 @@
       ]
     }
   }
-}
+}

data/schemas/2026-08-25/schemas/common/identity_linking.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-08-25/schemas/common/identity_linking.json",
+  "name": "dev.ucp.common.identity_linking",
+  "title": "Identity Linking",
+  "description": "Capability schema for identity linking. Businesses declare the user-authenticated scopes they offer in a flat 'scopes' map. Each key is the OAuth scope string as it appears on the wire ('{capability}:{scope}', e.g. 'dev.ucp.shopping.order:read'). Scope presence implies that the corresponding operations require user authentication. Operations not gated by any listed scope operate at whatever access level the business permits; UCP does not prescribe a default.",
+  "$defs": {
+    "scope_policy": {
+      "type": "object",
+      "title": "Scope Policy",
+      "description": "Per-scope policy and metadata — auth constraints (e.g. min_acr, max_token_age), declarative metadata (e.g. claims produced, consent descriptions), or any other scope-specific configuration. An empty object means user authentication is required with no additional policy. Open for non-breaking extension.",
+      "properties": {
+        "description": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/description.json",
+          "description": "Optional human-readable description of the scope that platforms can use to present and explain context (requirement and value) to the user."
+        }
+      },
+      "additionalProperties": true
+    },
+    "scope_token": {
+      "type": "string",
+      "description": "OAuth scope string formed by joining a capability name and a scope name with a colon: '{capability}:{scope}', e.g. 'dev.ucp.shopping.order:read'. Capability names use reverse-DNS naming; scope names denote the permission granted, defined by each capability's spec (e.g. 'read', 'manage', 'create'). Platforms request these strings verbatim in OAuth 'scope' parameters; issued tokens carry them in the 'scope' claim.",
+      "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+:[a-z][a-z0-9_]*$"
+    },
+    "provider": {
+      "type": "object",
+      "title": "Identity Provider",
+      "description": "A trusted identity provider for delegated authentication, keyed by the 'type' discriminator. 'oauth2' denotes an OAuth 2.0 / OIDC authorization server. Future versions MAY define additional types (e.g. wallet attestation) as non-breaking extensions; platforms MUST treat entries whose 'type' they do not support as filtered out (see Provider Selection).",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Provider mechanism discriminator. 'oauth2' for OAuth 2.0 / OIDC authorization servers. Additional values MAY be defined by future versions; the value is an open string, not a closed enum, so unrecognized types remain valid and are filtered at runtime."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "oauth2"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "auth_url"
+            ],
+            "properties": {
+              "auth_url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Base URL for authorization server metadata discovery. Platforms resolve metadata via RFC 8414 (/.well-known/oauth-authorization-server) with OIDC fallback (/.well-known/openid-configuration) on 404."
+              },
+              "required_claims": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "uniqueItems": true,
+                "description": "OIDC Core §5.1 claim names the business requires in the JWT authorization grant from this provider (e.g. 'email'). Optional pre-filter hint: platforms SHOULD skip this provider during selection when their upstream identity lacks any of the listed claim names. Reactive enforcement at the token endpoint remains mandatory regardless; this field expresses claim presence only, not value constraints."
+              }
+            }
+          }
+        }
+      ],
+      "additionalProperties": true
+    },
+    "dev.ucp.common.identity_linking": {
+      "platform_schema": {
+        "title": "Identity Linking (Platform)",
+        "description": "Platform-level identity linking capability declaration. Platforms advertise support for identity linking; no auth-specific config is required.",
+        "allOf": [
+          {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/platform_schema"
+          }
+        ]
+      },
+      "business_schema": {
+        "title": "Identity Linking (Business)",
+        "description": "Business-level identity linking configuration. Businesses declare the user-authenticated scopes they offer in 'config.scopes'.",
+        "allOf": [
+          {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/business_schema"
+          },
+          {
+            "type": "object",
+            "required": [
+              "config"
+            ],
+            "properties": {
+              "config": {
+                "type": "object",
+                "required": [
+                  "scopes"
+                ],
+                "properties": {
+                  "providers": {
+                    "type": "object",
+                    "description": "Map of trusted external identity providers keyed by reverse-domain identifier. Each key maps to an array of mechanism entries — an IdP namespace MAY offer multiple token acquisition mechanisms. Declares which upstream IdPs the business will accept JWT bearer assertions from for the Accelerated IdP Flow (chaining via RFC 8693 + RFC 7523). This field is additive: direct OAuth against the business domain via RFC 8414 discovery is always available regardless of 'providers' content. Businesses MUST NOT list their own authorization server here — chaining-to-self is degenerate, and direct OAuth covers that path. When absent, empty, or when no listed mechanism is supported by the platform, platforms run direct OAuth on the business domain.",
+                    "propertyNames": {
+                      "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
+                    },
+                    "additionalProperties": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/$defs/provider"
+                      }
+                    }
+                  },
+                  "scopes": {
+                    "type": "object",
+                    "description": "Map of user-authenticated scopes offered by this business. Each key is an OAuth scope string formed as '{capability}:{scope}' (e.g. 'dev.ucp.shopping.order:read'). Scope presence in this map declares that the corresponding operations require a user identity token. Operations not gated by any listed scope operate at whatever access level the business permits; UCP does not prescribe a default. Each value is a per-scope policy object (empty object means user auth required with no additional policy).",
+                    "propertyNames": {
+                      "$ref": "#/$defs/scope_token"
+                    },
+                    "additionalProperties": {
+                      "$ref": "#/$defs/scope_policy"
+                    }
+                  }
+                },
+                "additionalProperties": true
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "version": "2026-08-25"
+}