feat!: identity linking OAuth 2.0 foundation with capability-driven scopes

[amithanda]

Overview

This PR establishes the OAuth 2.0 foundation for the Identity Linking capability
(dev.ucp.common.identity_linking). It is an intentionally scoped first step —
business-hosted OAuth 2.0 only — designed so that delegated identity providers
and non-OAuth auth mechanisms can be added in future PRs as non-breaking
extensions.

Context: #265 introduced a mechanism registry and capability-driven scopes
but shipped a critical bug where the intersection algorithm's scope-dependency
pruning rule gated checkout behind identity linking, breaking guest checkout.
#329 reverted it. #330 proposed a full redesign including delegated IdP and
identity chaining. This PR carries forward the improvements from both without
the delegated IdP complexity, and lays explicit extensibility groundwork for
that work to land cleanly.

---

What Changed

New: source/schemas/common/identity_linking.json

Schema for the identity linking capability. Two context-specific views, nested
under "dev.ucp.common.identity_linking" in $defs per the project's
capability schema convention:

• platform_schema: passthrough — platforms advertise support; no
  auth-specific config needed.
• business_schema: requires config.capabilities — a map declaring
  which capabilities offer buyer-scoped features and whether buyer identity
  is required for each.

The config object uses additionalProperties: true with a $comment
naming one reserved extension point:

• providers — map of trusted identity providers keyed by reverse-domain,
  with a type discriminator defaulting to oauth2. This single extension
  point covers delegated IdP, identity chaining, and future non-OAuth
  mechanisms such as wallet attestation (future PR).

New: identity_required error code (error_code.json)

Standard protocol signal for the case where a capability is configured with
auth_required: true and a request arrives without a buyer identity token.
Businesses MAY include a continue_url in the error body for buyer
onboarding flows.

Rewrite: docs/specification/identity-linking.md

Major rewrite of the spec. Key sections:

Access levels. Capabilities operate at three access levels — public,
agent-authenticated, buyer-authenticated. Identity linking upgrades capabilities
to buyer-authenticated access. Capabilities are never excluded from
capability negotiation based on identity linking. This directly addresses the
root cause of the #265 bug.

Security hardening (carried forward from #265 and #330):

• PKCE S256: MUST for all authorization code flows; plain MUST NOT be used
• iss validation: MUST (RFC 9207) — prevents Mix-Up Attacks; validation is
  unconditional, not gated on presence of the iss parameter
• Exact redirect_uri matching: MUST — no partial/prefix matching
• issuer byte-for-byte match: MUST — no normalization (trailing slash stripping
  is a known iss validation bypass)
• scopes_supported: MUST in RFC 8414 metadata — enables early scope mismatch
  detection before consent screen

Strict discovery hierarchy (carried forward from #265 and #330):

1. RFC 8414 (/.well-known/oauth-authorization-server) — 2xx: use it; 404:
   proceed to step 2; any other non-2xx response, network error, or timeout:
   MUST abort, MUST NOT fall through to step 2
2. OIDC fallback (/.well-known/openid-configuration) — 2xx: use it; any
   non-2xx response, network error, or timeout: MUST abort

Capability-driven scope model (redesigned from #265, aligned with #330):
Scope declarations live in config.capabilities on the identity linking config,
not as identity_scopes annotations on individual capability schemas. This is
architecturally correct because whether a capability requires buyer auth is a
business decision — a B2B wholesaler gates catalog access, a B2C retailer
doesn't. Per-schema annotations can't express this variance.

Scope naming uses capability names directly (dev.ucp.shopping.checkout,
dev.ucp.shopping.order:read) — reusing UCP's existing reverse-DNS governance
and eliminating a separate scope namespace. Replaces the old
ucp:scopes:checkout_session format.

Future Extensibility section — explicit normative spec for how future
versions extend this capability without breaking v1 implementations (see below).

Updated: docs/specification/overview.md

Identity linking added back to both business and platform profile examples
using the new config shape, including the auth_required field naming.

Fixed: docs/index.md

Scope naming in the RFC 8414 metadata example updated from
ucp:scopes:checkout_session to dev.ucp.shopping.checkout.

---

Forward Compatibility Design

The schema and spec are explicitly designed for non-breaking extension via a
single config.providers extension point.

config.providers — Delegated Identity Providers and Mechanism Extensibility

A future PR will add a config.providers map (keyed by reverse-domain
identifier) allowing businesses to declare trusted external identity providers
alongside their own hosted OAuth server. Each provider entry carries a type
discriminator defaulting to oauth2, making the map extensible to non-OAuth
mechanisms (wallet attestation, verifiable credentials) without introducing a
separate mechanisms array.

This covers two use cases:

• Delegated IdP: platforms with an existing IdP session can chain identity
  to new businesses without a browser redirect (per
  draft-ietf-oauth-identity-chaining-08), solving the N-merchant = N-OAuth-dances
  problem for agentic commerce.
• Non-OAuth mechanisms: future entries with a non-oauth2 type value
  enable wallet attestation and similar schemes. Platforms select the first
  entry whose type they support — analogous to TLS cipher suite negotiation,
  preserving business-preference ordering.

This addition is non-breaking because:

• config uses additionalProperties: true — the schema will not reject the
  new field
• The spec defines a normative forward-compat rule: platforms that do not
  recognize config.providers MUST ignore it and fall back to RFC 8414
  discovery on the business domain

---

Type of Change

• New feature (non-breaking addition of new capability schema)
• Breaking change (new scope naming convention replaces ucp:scopes:* format)
• Documentation update

Breaking Changes Justification

The scope naming convention change (ucp:scopes:checkout_session →
dev.ucp.shopping.checkout) is breaking for any implementation that hardcoded
the old format. The old format was defined in the pre-#265 spec and was never
part of a stable release — the capability was at Working Draft status throughout.
The new format is consistent with UCP's reverse-DNS naming governance and
eliminates the need for a parallel scope namespace.

---

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

[douglasborthwick-crypto]

Thanks for laying the extensibility groundwork explicitly. The reserved config.mechanisms slot and the RFC 8414 fallback rule together make it straightforward for non-OAuth mechanisms to land as non-breaking additions — exactly the shape we were looking for when we opened #264.

Once this lands, we can follow up with a concrete config.mechanisms entry for wallet attestation — JWKS-discovered public key, ES256-signed boolean verdict per evaluated condition, deterministic offline verification. The type discriminator pattern (chosen inside the array, TLS-cipher-suite-style) works cleanly for wallet auth since the business declares the supported chains and condition types per entry.

Happy to wait for this PR to merge before opening the follow-up so we're not creating extension-point churn.

[igrigorik]

@amithanda nice work on this, lots of good improvements!

We need to land support for delegated IdPs. This is a key and painfully missing feature, which we proposed the shape for in #330. Comparing the two branches, we need to reconcile and merge, and I think it's easier to build on what you've scoped here.

I took a run at bringing over additional logic from #330 in 603f4c8. Because your PR is against your own fork I can't open a stacked PR. That said, if the commit looks good, I can push it into your branch directly and we can continue iterating against your current branch and close out #330. PTAL, any objections?

---

With above in place, I think we can collapse providers vs mechanisms into single primitive. They are both attempting to answer the same question: "who does the business trust to vouch for buyers, and what proof protocol do they speak?"

An OAuth IdP and a wallet attestor both have:

• A reverse-domain trust anchor (com.google, com.example.attestor)
• A discovery mechanism (auth_url → RFC 8414, provider_jwks → JWKS endpoint)
• A proof format (OAuth tokens, ES256 signed payloads)
• An explicit trust relationship (business lists them)

Keeping them as separate keys creates ambiguity: are mechanisms alternatives to OAuth (platform picks one) or complements (identity via OAuth + wallet proof for eligibility)? The TLS cipher-suite negotiation analogy on mechanisms implies the former, but your actual use case in #264/#280 looks more like the latter.

Proposed reconciliation

Unify under providers with a type discriminator. Default type is oauth2 when absent — zero wire-format change for existing entries:

"config": {
  "providers": {
    "com.google": {
      "auth_url": "https://accounts.google.com/"
    },
    "com.example.merchant": {
      "auth_url": "https://merchant.example.com/"
    },
    "com.example.attestor": {
      "type": "wallet_attestation",
      "provider_jwks": "https://attestor.example.com/.well-known/jwks.json",
      ...
    }
  },
  "capabilities": { ... }
}

What this gets us:

• Single trust surface. Business declares all trusted identity/attestation sources in one map.
• Clean forward-compat. Platforms skip provider entries whose type they don't recognize. No separate "ignore unknown config fields" rule for a sibling key.

What we drop: The config.mechanisms reserved extension point. It's replaced by new type values on provider entries, which is a strictly simpler extension model.

The relationship between providers then becomes clear from context: a platform that finds both type: "oauth2" and type: "wallet_attestation" entries knows these are different proof protocols. Whether they're alternatives or complements depends on how config.capabilities references them — that's the follow-up design question for when wallet attestation lands, not something we need to over-specify now.

[igrigorik]

One gotcha that's bothering me with scopes as flat array of strings...

"dev.ucp.shopping.order": {
  "auth_required": true,
  "scopes": ["read", "manage"]
}

With above contract every scope inherits uniform requirements from a single auth_required flag at the capability level. Fine for simple cases, but I think we need more flexibility. Consider the following example...

B2C retailer

• search does not require buyer auth — public catalog access
• vip requires buyer authorization — unlocks premium/vip products and inventory

B2B wholesaler

• search requires buyer auth
• wholesale_pricing requires elevated auth context (e.g. hardware-backed auth)

Same capability (dev.ucp.shopping.catalog), overlapping but different scope vocabulary, and different access policies for different scopes. Array of strings can't capture this. Capability-level auth_required over-triggers for B2C (flags search as requiring auth) or under-triggers for B2B (can't signal scope step-up).

Rec: scope level policies + explicit scopes (no bare capability scope)

Each listed capability declares its scopes explicitly. Each scope is an object. Wire format is always capability:scope — there is no "bare capability name as scope". The resulting shape is:

"dev.ucp.common.identity_linking": [{
  "config": {
    "providers": { ... },
    "capabilities": {
      "dev.ucp.shopping.catalog": {
        "scopes": {
          "search": { "auth_required": false },
          "vip":    { "auth_required": true }
        }
      },
      "dev.ucp.shopping.order": {
        "scopes": {
          "read":   { "auth_required": true },
          "manage": { "auth_required": true, "min_acr": "urn:tl:TL3" }
        },
        "some_future_foo": "bar"
      }
    }
  }
}]

The contract is:

• Each listed capability MUST declare a scopes map with at least one entry.
• Scopes name always follow {capability}:{scope} convention.

What this unlocks

• Per-scope configs — e.g, auth_required can be defined with scope granularity
• Extensible scope configs — e.g., min_acr for step-up auth, max_token_age for freshness; ...
• Convention alignment — providers, capabilities, payment_handlers are all keyed maps

Alt: flat scopes map keyed by wire-format

"config": {
  "providers": { ... },
  "scopes": {
    "dev.ucp.shopping.catalog:search": { "auth_required": false },
    "dev.ucp.shopping.catalog:vip":    { "auth_required": true },
    "dev.ucp.shopping.order:read":     { "auth_required": true },
    "dev.ucp.shopping.order:manage":   { "auth_required": true, "min_acr": "..." }
  }
}

The benefit of the above pattern is that key is the exact scope that you can copy-pase into Oauth scope=. The tradeoff is that we lose grouping and future extensibility / ability to provide capability-wide config values.

[amithanda]

We should define scope groups for other core capabilities as well? Catalog, Cart and Order.

Added scopes for other capabilities. PTAL

[igrigorik]

Hmm, UCP-Identity-Token doesn't feel right. Let's step back...

In standard OAuth, client authentication happens at the /token endpoint (via client_secret_basic, private_key_jwt, mTLS, etc), not via a Bearer header at API time. Authorization at API time uses the access token that carries client_id claim. The user-authorized token IS the platform's presented credential to the resource server -- resource servers validate client_id/azp against expected values.

All that to say, we don't need to stack a "platform Bearer" and a "user Bearer." The collision Maxime flagged only appears because we listed OAuth Bearer as one of the platform auth options at API time -- which, in retrospect, I think is a mistake. OAuth Bearer at API time is the user-authorized token; it's not a separate platform credential.

I think we can unwind and fix this in this PR...

1. Drop OAuth Bearer from the platform auth options in cart-rest.md (line 540) and checkout-rest.md (line 1408). Platform identity at API time = HTTP Message Signatures (RFC 9421), mTLS, or API key.
2. Authorization: Bearer <user_token> unambiguously carries the user-authorized access token. Add a forward reference from those auth sections to identity-linking.md for scope vocabulary and validation requirements.
3. Drop UCP-Identity-Token

@maximenajim please sanity check!

[amithanda]

Thanks for the feedback. @igrigorik - I agree that we should avoid stacking a 'platform Bearer' and a 'user Bearer' and eliminate the need for a custom UCP-Identity-Token header.

However, rather than removing OAuth 2.0 completely from the list of options (which might imply UCP REST bindings don't support standard OAuth at all), I have updated the language in both cart-rest.md and checkout-rest.md to be more targeted based on OAuth 2.0 fundamentals:

OAuth 2.0: Via Authorization: Bearer {token} header. Identifies the platform for agent-authenticated access, or both platform and user for user-authenticated access (see Identity Linking).

Why this modified language is better than removing the option:

1. Aligns with Standard OAuth2: Per RFC 9068, a user-authorized access token already carries claims (like client_id or azp) identifying the client application it was issued to. Therefore, the user token is the platform's credential at API time.
2. Clarifies Both Access Levels: It explains that the same standard Authorization: Bearer header is used for both Agent-authenticated access (client credentials) and User-authenticated access (auth code flow).
3. Prevents Collision: By clarifying that the token represents both parties in the user flow, it makes it clear that a separate platform credential is not sent at API time, directly solving the collision problem without falsely implying that OAuth is unsupported.

Let me know what you think?

[igrigorik]

Per the TC sync, we converged on a split of responsibilities between UCP and OAuth (RFC8414) for expressing auth requirements vs availability vs runtime hints. As a think-out-loud sanity-check exercise, this means...

1. UCP config.scopes declare:
   • hard gates: scopes that require user auth for the operations they cover
   • optional description string on the scope that provides human-readable explanation of the required scope.
2. OAuth scopes_supported metadata (RFC 8414) declare the accepted scope vocabulary:
   • i.e. list every scope the AS will honor if requested
3. OAuth scopes_supported - UCP config.scopes is the optional layer: scopes offered but not gating operation.
4. UCP messages[] can be used as runtime contextual hints: per-request advisories ("sign in for member pricing") with a well-known info code and description (e.g. "sign-in to unlock member-pricing")

Example walkthrough

Step 1: discover capabilities

Agent fetches the UCP profile:

GET https://merchant.example.com/.well-known/ucp

{
  "ucp": {
    "capabilities": {
      "dev.ucp.shopping.catalog.search":   [{ ... }],
      "dev.ucp.shopping.checkout":         [{ ... }],
      "dev.ucp.common.identity_linking":   [{
        "config": {
          "scopes": {
            "dev.ucp.shopping.checkout:manage": {}
          }
        }
      }]
    }
  }
}

Agent learns:

• Catalog search and checkout are offered.
• Checkout :manage is a required gate — guest cannot complete checkout.
• Catalog has no required scope — guest search works.
• Identity linking is supported.

Step 2: discover auth machinery

The agent fetches the OAuth Authorization Server metadata:

GET https://merchant.example.com/.well-known/oauth-authorization-server

{
  "issuer": "https://merchant.example.com",
  "authorization_endpoint": "...",
  "token_endpoint": "...",
  "jwks_uri": "...",
  "scopes_supported": [
    "dev.ucp.shopping.checkout:manage",
    "dev.ucp.shopping.catalog.search:read"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["private_key_jwt", "none"],
  ...
}

Agent learns:

• Endpoints, JWKS, flow parameters, PKCE/client-auth requirements.
• The full vocabulary of scopes the AS will honor: :manage and .search:read.

Step 3: reason about the auth landscape

required = config.scopes              = { checkout:manage }
accepted = scopes_supported           = { checkout:manage, catalog.search:read }
optional = accepted - required        = { catalog.search:read }

Three sets, distinct semantics:

• Required: auth needed to access these operations.
• Accepted: the AS honors these scopes if the agent decides to request them.
• Optional (the diff): merchant offers but doesn't gate. The exact semantics of why and what benefits might be unlocked if the user signs in are dependent on the merchant and are left to the merchant to express -- e.g. by emitting a message on the response indicating benefits of sign-in.

Step N: runtime contextual hints

Static metadata answers "is auth available?" but not "is auth valuable in this request?" That's contextual to the merchant and their implementation (persisted carts and wishlists; loyalty tiers; saved address and prefs). The merchant signals this via an informational message in the operation response, using a well-known code:

{
  ...
  "messages": [
    {
      "type": "info",
      "code": "identity_optional",
      "content": "Sign in for member pricing and personalized results."
    }
  ]
}

The agent can present this as an opportunity to the user, and if accepted, it uses the defined machinery and dance of identity linking to negotiate appropriate scopes by introspecting the two discovery documents and relevant descriptions. As a reminder, info messages are non-blocking for related operations (can be ignored by agent).

p.s. identity_optional as counterpart to identity_required for gated operations.

[igrigorik]

@amithanda separate from above, pushed two updates, please sanity check:

• 4f20c58: support public clients via PKCE
• a1ef95e: normalize capability scope sections

[amithanda]

@igrigorik - thank you - both your updates look good. I added the change to add optional description for required scopes. Please feel free to approve, if everything looks good.

[igrigorik]

FYI, stacked a few more changes to document identity_optional and adopt WWW-Authenticate. Please sanity check, but otherwise I believe this is now good to land.

[igrigorik]

👍