feat!: delegated IdP, identity chaining, and capability-driven scope model

[igrigorik]

Redesign identity linking for multi-merchant agentic commerce. Businesses can offer delegated identity providers, allowing buyers to authenticate through a trusted IdP (e.g., Google, Shop) instead of creating a per-merchant account. Platforms can support these IdPs to streamline identity linking — authenticate once, reuse across businesses that trusts the same provider.

This PR carries builds on / supersedes #265, reverted in #329.

Delegated Identity Providers

The current identity linking spec assumes 1:1 — each business operates its own OAuth authorization server, requiring a full OAuth dance per merchant. In agentic commerce, where platforms shop across many businesses on a buyer's behalf, this means N merchants = N handoffs.

Businesses can now declare trusted identity providers in config.providers, keyed by reverse-domain identifier:

"dev.ucp.common.identity_linking": [{
  "config": {
    "providers": {
      "com.google": {
        "auth_url": "https://accounts.google.com/"
      },
      "com.example.merchant": {
        "auth_url": "https://merchant.example.com/"
      }
    }
  }
}]

Here the business trusts Google as an external IdP and also lists itself (com.example.merchant) for business-hosted OAuth — both use the same discovery mechanism. Each provider's auth_url is resolved via RFC 8414, with OIDC /.well-known/openid-configuration fallback on 404.

Two distinct flows:

• Account Linking: One-time OAuth flow between platform and IdP. Standard Authorization Code + PKCE, with support for additional grant types (device authorization for headless agents via RFC 8628).
• Accelerated IdP Flow: Platform already holds a valid IdP token (e.g., from Google), chains the buyer's identity to a new business without a browser redirect — per draft-ietf-oauth-identity-chaining-08.

Identity chaining

The accelerated flow implements a two-phase pattern:

1. Platform requests a JWT authorization grant from the IdP via token exchange (RFC 8693), using the resource parameter to identify the target business
2. Platform presents the JWT grant to the business's token endpoint via JWT bearer assertion (RFC 7523)
3. Business validates the grant, resolves buyer identity, issues its own access token

The IdP controls consent — it MUST NOT issue grants for businesses the buyer has not authorized. Businesses MAY auto-provision accounts or return a continue_url for buyer onboarding (terms acceptance, etc.). Two independent token lifecycles with independent revocation. Refresh tokens SHOULD NOT be issued per the chaining draft.

Capability-driven scope model

Scopes define the permissions an identified buyer grants to a platform within a capability. Unlike #265's approach of annotating individual capability schemas with identity_scopes, scope declarations live centrally on the identity linking config. This is because whether a capability requires buyer auth is a business decision — a B2B wholesaler gates catalog access, a B2C retailer serves it publicly.

Three access levels

Level	Authentication	Example
Public	None	Browse a public catalog
Agent-authenticated	Platform credentials	Guest checkout, read agent's own orders
Buyer-authenticated	Platform + buyer identity	Saved addresses, full order history, personalized pricing

Identity linking upgrades capabilities to buyer-authenticated access. Capabilities are never pruned from the intersection based on identity linking; there is no capability pruning algorithm.

Config shape

Building on the provider example, businesses declare which capabilities offer buyer-scoped features alongside their trusted IdPs:

"dev.ucp.common.identity_linking": [{
  "config": {
    "providers": {
      "com.google": {
        "auth_url": "https://accounts.google.com/"
      }
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": {},
      "dev.ucp.shopping.order": {
        "required": true,
        "scopes": ["read", "manage"]
      }
    }
  }
}]

• Absent from capabilities map: no buyer-scoped features (fully public)
• Present, no required: accessible without buyer auth, identity upgrades the experience
• required: true: business returns identity_required error without buyer identity
• scopes: sub-scope operation groups defined by each capability's spec, joined with colon on the wire (e.g., dev.ucp.shopping.order:read)
• Scope tokens use capability names directly — no separate scope namespace

Carried forward from #265

• PKCE MUST (platforms and businesses)
• iss validation MUST (RFC 9207, both sides)
• Exact redirect_uri matching MUST (businesses)
• scopes_supported MUST in RFC 8414 metadata
• 2-step discovery hierarchy: RFC 8414 primary, OIDC fallback on 404 only, strict abort on other errors
• JWT authorization grants: 60s lifetime, jti single-use enforcement

---

Type of change

• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to not work as expected, including removal of schema files
  or fields)
• I have added ! to my PR title (e.g., feat!: remove field).

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[aglazer]

Thanks @igrigorik. Agree with the changes. Great addition to UCP!