portage-ucp 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e47e8018ba5966b67205cb9046efdf0e8f0edbe9ab58eef1e7613232a5b6b27
-  data.tar.gz: c5eaa266f8d88a7fda16a822e0eb0b6aad82465b1e6adbf36abe08e7d2c859c4
+  metadata.gz: 3030cd7b510d8e0e829878dd48ab11fd18f70e0d0e5cac5107852ead26a0077c
+  data.tar.gz: 7e6abed9cd7ea40da3ee5f8681ec69f80a6f8c852e8956901f4fce1b383816da
 SHA512:
-  metadata.gz: '053845855d29f395fb001b78d13622798aadf54c8dc087c88bdf32a943e65e992e7d6d79a3f9a5c86232ebfb8f65f36eb1137888bd9a806e2ceeeef045a57789'
-  data.tar.gz: 6e1cec328b2d07567d4441340fe177367db3bbe7e094aa93388446cb062ea948e600abeb353dcf31b3833f7f76d2ccc189c275a44ab4c5ea546b94e4f3c152d7
+  metadata.gz: 4c4dddb8b6aaeaa674d270400287420f3bcbbfc028c8d38b9482fe53fe2cb47b493711cd7fffe50051b892b49f720f4332ba0e3af89fe595df9d46cdf80c5306
+  data.tar.gz: 5b1c1ee5a21fae8d7c8821c43820bcdcca15f54001e9d6e25af3b4916965da69a1bedb144faadb06ec222c11a59d3cd7e60c753579a4d8931924f51e62f06b78

data/CHANGELOG.md

@@ -6,6 +6,20 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-13
+
+- **Added: optional `policies:` on `Cart`, `Checkout`, `Order`, `Product`, `CatalogSearchResult` and `ProductDetail`** (UCP 2026-08-25 `policies[]`). An array of `policy.json` hashes (`type` and `description` required; `applies_to` and `url` optional), default `[]`, omitted from the wire payload when empty. `portage-ucp-shopify` 0.7.0 supplies it (design-log §60).
+
+## [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.

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/adapter.rb

@@ -105,7 +105,7 @@ module Portage
 
       # --- Reorder (app.portage-ucp.reorder — Portage extension, not part of
       # the UCP spec: dev.ucp.dev has no reorder/cart-hydration capability as
-      # of the 2026-04-08 spec) ---
+      # of the 2026-08-25 spec) ---
       # Hydrates a cart from a previous order's line items so a caller doesn't
       # have to re-walk get_order + create_cart itself. Re-checks each item's
       # current price/availability rather than replaying the order's snapshot

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/security/signature.rb

@@ -7,7 +7,7 @@ module Portage
     module Security
       # Verifies that an inbound agent request carries a valid RFC 9421 HTTP
       # Message Signature, per UCP's own signature spec
-      # (ucp.dev/2026-04-08/specification/signatures/, pinned 2026-09-15 —
+      # (ucp.dev/2026-08-25/specification/signatures/, pinned 2026-09-15 —
       # this is the piece §22 of the design log flagged as unresearched
       # before writing code, now checked against the live spec rather than
       # guessed). This is a distinct concern from three other signing

data/lib/portage/ucp/value_objects.rb

@@ -115,9 +115,10 @@ module Portage
     # (Shopify/Wix metafields etc.) — see Portage::Ucp::Shopify.configure's
     # metadata_field.
     Product = Data.define(:id, :title, :description, :price_range, :variants, :handle, :url, :categories,
-                          :list_price_range, :media, :options, :tags, :metadata, :rating) do
+                          :list_price_range, :media, :options, :tags, :metadata, :rating, :policies) do
       def initialize(id:, title:, description:, price_range:, variants:, handle: nil, url: nil, categories: [],
-                     list_price_range: nil, media: [], options: [], tags: [], metadata: nil, rating: nil)
+                     list_price_range: nil, media: [], options: [], tags: [], metadata: nil, rating: nil,
+                     policies: [])
         super
       end
 
@@ -135,6 +136,7 @@ module Portage
         h["media"] = media.map(&:to_wire_h) unless media.empty?
         h["options"] = options.map(&:to_wire_h) unless options.empty?
         h["tags"] = tags unless tags.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end
@@ -144,12 +146,13 @@ module Portage
     # isn't schema-conformant (search_response requires `ucp` + `products` at
     # the top level, not a bare array). `messages` entries are left as plain
     # wire-shaped hashes, same rationale as Variant#barcodes above.
-    CatalogSearchResult = Data.define(:products, :messages) do
-      def initialize(products:, messages: []) = super
+    CatalogSearchResult = Data.define(:products, :messages, :policies) do
+      def initialize(products:, messages: [], policies: []) = super
 
       def to_wire_h
         h = { "products" => products.map(&:to_wire_h) }
         h["messages"] = messages unless messages.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end
@@ -161,8 +164,14 @@ module Portage
     # extension (interactive variant narrowing) — Adapter#get_product's
     # signature has no `selected:`/`preferences:` params to source it from
     # yet; unresearched, same status as design-log §16's other backlog items.
-    ProductDetail = Data.define(:product) do
-      def to_wire_h = { "product" => product.to_wire_h }
+    ProductDetail = Data.define(:product, :policies) do
+      def initialize(product:, policies: []) = super
+
+      def to_wire_h
+        h = { "product" => product.to_wire_h }
+        h["policies"] = policies unless policies.empty?
+        h
+      end
     end
 
     # One cost-breakdown entry (schemas/shopping/types/total.json). `amount` is a
@@ -198,6 +207,10 @@ module Portage
       end
     end
 
+    # `policies` (cart/checkout/order/catalog responses and products) is the
+    # 2026-08-25 policy.json array (return/warranty terms), optional and omitted
+    # when empty. Entries stay wire-shaped hashes (`type` and `description` are
+    # required, `applies_to`/`url` optional), same posture as `messages`.
     # schemas/shopping/types/link.json
     Link = Data.define(:type, :url, :title) do
       def initialize(type:, url:, title: nil) = super
@@ -272,6 +285,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 +296,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
@@ -378,13 +393,14 @@ module Portage
     # `discounts` is the dev.ucp.shopping.discount extension (optional on both
     # cart.json and its own schema) — omitted from the wire payload when empty,
     # same as Order#adjustments.
-    Cart = Data.define(:id, :line_items, :currency, :totals, :discounts) do
-      def initialize(id:, line_items:, currency:, totals:, discounts: Discounts.new) = super
+    Cart = Data.define(:id, :line_items, :currency, :totals, :discounts, :policies) do
+      def initialize(id:, line_items:, currency:, totals:, discounts: Discounts.new, policies: []) = super
 
       def to_wire_h
         h = { "id" => id, "line_items" => line_items.map(&:to_wire_h), "currency" => currency,
               "totals" => totals.map(&:to_wire_h) }
         h["discounts"] = discounts.to_wire_h unless discounts.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end
@@ -413,9 +429,9 @@ module Portage
     # omitted from the wire payload when empty), same posture as
     # Order#adjustments.
     Checkout = Data.define(:id, :status, :line_items, :currency, :totals, :links, :order, :discounts,
-                           :fulfillment) do
+                           :fulfillment, :policies) do
       def initialize(id:, status:, line_items:, currency:, totals:, links:, order: nil, discounts: Discounts.new,
-                     fulfillment: CheckoutFulfillment.new)
+                     fulfillment: CheckoutFulfillment.new, policies: [])
         super
       end
 
@@ -425,6 +441,7 @@ module Portage
         h["order"] = order.to_wire_h if order
         h["discounts"] = discounts.to_wire_h unless discounts.empty?
         h["fulfillment"] = fulfillment.to_wire_h unless fulfillment.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end
@@ -506,9 +523,9 @@ module Portage
     # line_items/fulfillment/currency/totals. `adjustments` is optional —
     # omitted from the wire payload when empty.
     Order = Data.define(:id, :checkout_id, :permalink_url, :line_items, :fulfillment, :currency, :totals,
-                        :adjustments) do
+                        :adjustments, :policies) do
       def initialize(id:, checkout_id:, permalink_url:, line_items:, fulfillment:, currency:, totals:,
-                     adjustments: [])
+                     adjustments: [], policies: [])
         super
       end
 
@@ -517,6 +534,7 @@ module Portage
               "line_items" => line_items.map(&:to_wire_h), "fulfillment" => fulfillment.to_wire_h,
               "currency" => currency, "totals" => totals.map(&:to_wire_h) }
         h["adjustments"] = adjustments.map(&:to_wire_h) unless adjustments.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.13.0".freeze
+    VERSION = "0.15.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"
+}