[bbdu3]

Summary

Support deferred OAuth authorization for web applications, allowing the authorization code flow to resume through a subsequent callback request, including across different PHP workers.

Adds RedirectAuthorizationHandler, AuthorizationPendingException, and OAuthAuthenticator::finishAuthorization(), with persistent, single-use authorization state and regression tests.

Fixes #630.

Motivation and Context

AuthorizationHandlerInterface::authorize() currently expects callback parameters within the same call, which does not fit web applications where authorization redirects and callbacks are handled by separate HTTP requests.

This change implements the approach :

• The handler throws AuthorizationPendingException with the authorization URL.
• The authenticator persists the pending flow before propagating the exception.
• The callback route calls finishAuthorization() to validate the response, exchange the authorization code, and store the tokens.
• The application can then retry the original MCP operation.

Test

Unit tests

All 54 OAuthAuthenticator tests pass, covering cross-instance completion, PKCE context preservation, state validation and replay prevention, issuer validation, user storage isolation, and offline_access fallback.

Storage tests cover interleaved writes, atomic consumption across instances, issuer-specific cleanup, and malformed records.

HTTP integration tests

All 10 OAuth integration tests pass against local authorization and MCP server fixtures.

The cross-process regression test verifies that:

• Authorization can be completed in separate PHP processes.
• Only one competing callback succeeds.
• The persisted token can access a protected MCP tool.
• Replayed callbacks are rejected.

Broader checks

• Full unit suite: 1,742 tests, with the same 5 pre-existing Windows-related failures and 1 skipped test as the baseline. i confirmed these failures are not regression introduced in this PR.
• PHPStan: same 5 pre-existing errors, no new errors.
• PHP CS Fixer passes for changed PHP files.
• git diff --check passes.

Breaking Changes

None. Existing interfaces and synchronous authorization remain compatible.

CredentialStorageInterface is unchanged. Deferred authorization requires:

• Persistent storage implementing PendingAuthorizationStorageInterface.
• Catching AuthorizationPendingException and redirecting to its authorization URL.
• Recreating the authenticator in the callback route with the same configuration and session-scoped storage.
• Calling finishAuthorization() before retrying the MCP operation.

Types of Changes

• Bug fix (non-breaking change)
• New feature (non-breaking change)
• Documentation update