[chr-hertel]

Part of #316 - first slice of the client authorization in chr-hertel#53, which is too big to review in one go.

Pass auth: to HttpTransport and every request gets authenticated, a refused one gets retried if the authenticator can do something about it:

$transport = new HttpTransport('https://mcp.example.com/mcp', auth: new BearerToken($accessToken));

BearerToken is the only implementation for now, OAuth builds on AuthenticatorInterface in the next slices. No discovery or sign-in here, so the conformance baseline doesn't change yet.

[BC Break] A 401 or 403 now fails with an AuthorizationException that names the challenge, also without auth: - it was a RequestException before. connect() wraps it in a ConnectionException, without a retry.

[Copilot]

🟡 Changes recommended

Authentication defects can falsely report handshake success after a rejected notification, send empty or truncated retry payloads, block retries on unclosed response bodies, and misclassify SSE resumption authorization failures.

4 open issues

• Propagate authorization failures for initialization notifications · New
• Close rejected response before sending authenticated retry · New
• Prevent retrying non-replayable request bodies · New
• Map resumption authorization failures to AuthorizationException · New

What changed in this PR

Adds client HTTP authentication as the first slice of #316, supporting existing bearer tokens and an extension point for future OAuth flows without adding discovery or sign-in.

Changes:

• Adds HttpTransport::auth, BearerToken, and a PSR-18 decorator with bounded authentication retries.
• Introduces AuthorizationException for refused requests and documents the compatibility change.
• Adds tests for credential injection, challenge handling, and request-body replay.

File	Description
tests/​Unit/​Client/​Transport/​HttpTransportTest.php	Tests credential injection and authorization failures.
tests/​Unit/​Client/​Auth/​AuthenticatingHttpClientTest.php	Tests authentication, retry limits, and body replay.
src/​Exception/​AuthorizationException.php	Adds a dedicated authorization exception.
src/​Client/​Transport/​HttpTransport.php	Integrates authentication and maps refused POST requests.
src/​Client/​Auth/​BearerToken.php	Supplies fixed bearer-token credentials.
src/​Client/​Auth/​AuthenticatorInterface.php	Defines credential and challenge-handling hooks.
src/​Client/​Auth/​AuthenticatingHttpClient.php	Adds the authenticating HTTP client decorator.
src/​Client.php	Updates exception annotations.
docs/​client/​transports.md	Documents authentication configuration and extension points.
docs/​client/​errors.md	Documents authorization errors and connection wrapping.
CHANGELOG.md	Records authentication support and the exception compatibility break.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The retry test’s string cast implicitly rewinds the stream, so it passes even without the decorator’s explicit rewind; using getContents() would verify that the body is restored before retrying.

1 open issue

• Test retry restores consumed request body · New

4 resolved since last review

• Propagate authorization failures for initialization notifications
• Map resumption authorization failures to AuthorizationException
• Prevent retrying non-replayable request bodies
• Close rejected response before sending authenticated retry

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Rewinding the request body to byte zero on retry can change the submitted payload when the stream initially starts at a nonzero position; retries must restore the original position.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Retries rewind seekable request bodies to byte zero

src/​Client/​Auth/​AuthenticatingHttpClient.php:72

With a seekable body initially positioned past byte zero, an HTTP client that reads using getContents() sends from that position on the first attempt, but this rewind makes the retry send the entire stream. This can change the submitted payload (for example, payload becomes prefix:payload); capture the initial stream position before the first send and seek back to it for retries.

1 resolved since last review

• Test retry restores consumed request body

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because an unpublished finding identifies an unclosed response body when authentication challenge handling throws.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues block the bearer-token authentication changes.

No open issues 🎉

_{Review effort: Balanced}