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 client-provided scope parameter; 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 after the SDK's normal selection and offline_access augmentation, and returns valid replacement scope tokens or nil / [] to omit the URL's scope parameter. When configured, the selector also overrides prefilled scope parameters in the authorization endpoint query, so validation and the browser URL agree; no-selector behavior is preserved. It runs before authorization-request validation and client registration. Unsupported offline_access remains stripped. Filtering challenged scopes may leave the operation unauthorized; omitting scope does not prevent the AS from applying defaults (RFC 6749 §3.3).

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

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 nil or [] omits the client’s scope parameter; 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. Removing prefilled endpoint scopes when a selector is configured keeps the browser request consistent with the validator’s decision.

Validation

• All 11 OAuth test files pass locally: 424 tests, 1,366 assertions.
• Ruby syntax checks and git diff --check pass.
• Bundled RuboCop cannot bootstrap locally because this checkout lacks puma/native extensions; upstream CI validates lint.