Add a scope selector for OAuth authorization-code clients

[atesgoral]

Why

The MCP 2026-07-28 scope-selection strategy recommends the challenge's scope, then PRM scopes_supported (intended as a minimal basic set). The Ruby SDK follows that default. Some hosted clients need a narrower per-user policy, including a first authorization request with no PRM defaults; authorization_request_validator can refuse but cannot change the selected scopes.

Fixes #578.

What changes

Add optional Provider.new(scope_selector:) for authorization-code clients. It receives a read-only array of valid PRM scopes_supported tokens when the SDK selects those defaults instead of a challenged scope, and returns an array containing a subset; [] requests none of those defaults. Malformed PRM tokens raise Flow::AuthorizationError before the callback; nil results and custom additions raise ArgumentError. One Hash membership index avoids repeated candidate-list scans. Challenged scopes and the step-up union bypass the selector, and provider fallback is unchanged. It runs before offline_access augmentation, authorization-request validation and client registration. The existing offline_access policy is unchanged; unsupported offline_access remains stripped from the flow's resolved scope. Returning [] does not guarantee an omitted scope parameter or prevent the authorization server from applying defaults (RFC 6749 Section 3.3).

With no selector, the SDK's spec-aligned scope selection and other OAuth grants are unchanged. This follows the application-policy hook pattern in the C# SDK and Go SDK.

Before client registration, the authorization-request validator sees the explicit scopes that will actually be sent, including a single prefilled endpoint scope when the flow has none. Endpoint query names are decoded once and reused by policy and URL assembly. Repeated scope parameters that would survive are rejected before validation/registration, even without a selector or validator; a nonempty flow scope still replaces endpoint scopes normally. This constrains the client request, not the authorization server's final grant.

Scope selection, illustrated

These examples assume no challenged scope, a Protected Resource Metadata (PRM) document advertising read write admin, and an authorization server (AS) supporting offline_access with a client declaring the refresh_token grant. The authorization-request validator shown here is optional.

Default versus application policy

The hook changes what the client requests, not what the AS grants. Returning [] requests no PRM defaults; in this example, the existing refresh-token policy still adds offline_access. It does not prevent AS defaults.

Placement in a hosted OAuth flow

This uses the existing two-leg OAuth flow from PR 573. The scope selector is the addition here; callback persistence and Flow#finish! are existing behavior. The host must inspect the actual granted scopes. Endpoint scope handling is prepared before policy approval: a nonempty flow scope replaces prefills; a single surviving endpoint scope is shown to the validator. Repeated scopes that would survive fail before registration.

Validation

• All 11 OAuth test files pass locally: 441 tests, 1,452 assertions.
• The full client suite, including OAuth, passes locally: 744 tests, 2,374 assertions.
• Ruby syntax checks and git diff --check pass.
• Direct Ruby RuboCop passes for the five changed Ruby files; no dependency or native-extension rebuild.

[koic]

Nit: the rest of this page cites sections as "RFC 6749 Section 3.3" and spells out "authorization server" rather than "AS" (lines 111 and 114); § is also the only non-ASCII character in the docs source.

[atesgoral]

Fixed in 3b9e57d, thanks!

[atesgoral]

Updated in 75c6c24. The selector is still PRM-only/subset-only. The validator now sees any surviving endpoint scope before registration; surviving repeated scope parameters are rejected. Subset checks use one hash index, and malformed PRM candidates fail before the callback. Tests, docs and diagrams are updated.