docs: clarify Accelerated IdP Flow subject token

[atakedemo]

Description

Motivation

The Accelerated IdP Flow currently describes Step 2 as:

subject_token: the platform's existing IdP access token

However, the specification does not define:

1. How the platform acquires this "existing" IdP access token — the prerequisite Account Linking Flow against the IdP itself is implied but never described, leaving implementors to guess.
2. What scopes the subject token must carry — the token exchange (RFC 8693) will fail at the IdP if the subject token lacks required scopes, but no minimum scope requirement is stated.
3. How the IdP establishes "the user has authorized identity sharing" — the IdP Requirements section mandates this check (The IdP MUST NOT issue grants for businesses the user has not authorized) without describing the consent model that satisfies it.

These gaps create ambiguity for both Platform implementors (how do I get a subject token?) and IdP implementors (which consent model should I implement?).

This is distinct from #667, which addresses trust-chain security gaps after a subject token is already in hand (client authentication for unregistered businesses and auth_url trust anchor).

Proposed Changes

Three additive documentation-only changes to docs/specification/common/identity-linking/index.md:

1. New ### Subject Token subsection in ## Accelerated IdP Flow

Inserted before ### Flow. Clarifies that:

• The subject token is obtained by running the standard OAuth 2.0 Authorization Code flow (with PKCE) against the IdP — the same pattern as Account Linking Flow, but targeting the IdP instead of a business.
• This initial IdP connection is a prerequisite: without it, platforms MUST fall back to direct OAuth on the business domain.
• The subject token MUST have been issued to the authenticated user (MUST NOT be reused across users).
• The token SHOULD carry at minimum openid scope; platforms SHOULD also pre-request scopes for any claims listed in target businesses' required_claims.

2. **Consent models.** paragraph in ## IdP Requirements

Inserted after the existing MUST list. Describes the two common consent patterns the IdP MAY implement:

• Platform-level consent: authorization captured once when the user connects to the platform at the IdP (e.g., openid scope at sign-in); IdP issues grants for any relying party thereafter.
• Per-business consent: IdP prompts the user interactively on first access to a new business; subsequent grants are silent.

Adds SHOULD guidance that IdPs document their model and that platforms communicate it to users.

3. New ### End-to-End Walkthrough (Accelerated IdP Flow) in ## Examples

Added after the existing Account Linking Flow walkthrough. Provides a complete step-by-step example covering:

• Prerequisite: subject token acquisition via Authorization Code flow at the IdP
• Step 1: platform discovers config.providers and selects a matching entry
• Step 2: token exchange request/response at the IdP (with decoded JWT authorization grant)
• Step 3: JWT bearer assertion request/response at the Business
• Step 4: authenticated requests using the business-issued access token

Normative Impact

None. All proposed text is documentation and SHOULD-level guidance. No existing MUST requirements are changed. The changes clarify existing implied behavior without adding new constraints.

Category (Required)

Please select one or more categories that apply to this change.

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

• #667 — Security gaps in delegated-IdP accelerated flow (distinct: addresses post-subject-token trust-chain vulnerabilities)
• #355 — RFC: Identity Linking, Identity Management, and Loyalty (closed; Phase 2 introduced the Accelerated IdP Flow without specifying consent timing)
• #330 — PR that merged the Accelerated IdP Flow (closed; subject token prerequisites were not addressed)

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

$ pre-commit run --all-files
Block corporate registries in uv.lock....................................Passed
Validate JSON examples (changed docs)....................................Passed
Validate JSON examples (full corpus).....................................Passed
Validator unit tests.....................................................Passed
cspell...................................................................Passed
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
check for added large files..............................................Passed
check that scripts with shebangs are executable..........................Passed
check that executables have shebangs.....................................Passed
ruff (legacy alias)......................................................Passed
ruff format..............................................................Passed
markdownlint.............................................................Passed
stylelint................................................................Passed
prettier-css.............................................................Passed