[Server] Compose StreamableHttpTransport security middleware via defaultMiddleware() factory

[sveneld]

Summary

Replaces the implicit instanceof + array_unshift injection of CORS handling in StreamableHttpTransport with an explicit, composable PSR-15 stack exposed through a public StreamableHttpTransport::defaultMiddleware() factory. Adds three middleware that together cover the recommended HTTP-level hardening for MCP Streamable HTTP:

• CorsMiddleware — secure-by-default (no Access-Control-Allow-Origin header is set; cross-origin browser requests are blocked). Configurable allowedOrigins reflect a matching origin and automatically emit Vary: Origin so shared caches don't poison.
• DnsRebindingProtectionMiddleware — validates Origin/Host against an allowlist of hostnames (localhost variants by default).
• ProtocolVersionMiddleware — rejects requests carrying an unsupported Mcp-Protocol-Version header with 400 Bad Request (spec compliance).

The transport itself becomes oblivious to the middleware list. The $middleware constructor argument is nullable:

Passed value	Effect
omitted / null	Default secure stack from StreamableHttpTransport::defaultMiddleware()
[]	No middleware at all (e.g. when fronted by an application that already handles CORS/host validation)
explicit list	Used verbatim; mix and match by spreading ...StreamableHttpTransport::defaultMiddleware()

SESSION_HEADER and a new PROTOCOL_VERSION_HEADER are promoted to public constants on the transport so middleware can reuse them without duplicating string literals.

Why this design

The three open items below all reach for the same shape — a piece of mandatory security logic that the transport should apply unless the user opts out. PRs #260 and #277 each implement this with their own instanceof MyMiddlewareClass check + array_unshift inside the transport constructor. That pattern scales linearly with the number of "mandatory" middleware and breaks once a user supplies a custom implementation of the same concern under a different class name. Adding ProtocolVersionMiddleware for #306 would mean a third copy of the same pattern.

This PR collapses all three into a single composition model: the transport is a thin PSR-15 host, and the recommended stack lives in a factory the user can spread, filter, or replace. No instanceof magic, no surprise prepending, no position arguments to bypass.

Relation to other work

• [Server] Extract CORS handling into CorsMiddleware #277 (Extract CORS handling into CorsMiddleware) — same goal of replacing the inline withCorsHeaders() post-hook with a PSR-15 middleware. This PR additionally drops the instanceof CorsMiddleware auto-prepend in favour of defaultMiddleware() composition (which is what @CodeWithKyrian suggested in #277 review and @chr-hertel agreed with). Also addresses Hardcoded Wildcard CORS (Access-Control-Allow-Origin: *) #280 (wildcard CORS default) the same way [Server] Extract CORS handling into CorsMiddleware #277 does — Access-Control-Allow-Origin is no longer set by default. Adds Vary: Origin when reflecting a specific origin, which [Server] Extract CORS handling into CorsMiddleware #277 doesn't.
• [Server] Add DNS rebinding protection feature with middleware #260 (DNS rebinding protection) — same middleware concept and default allowlist (localhost, 127.0.0.1, [::1], ::1); avoids the instanceof DnsRebindingProtectionMiddleware auto-prepend pattern for the same scalability reason.
• Streamable HTTP accepts unsupported or malformed MCP-Protocol-Version headers instead of returning 400 #306 (Unsupported MCP-Protocol-Version accepted) — new ProtocolVersionMiddleware rejects with 400 Bad Request per spec. Tolerates a missing header (initialize round-trip / legacy clients don't send it); strict per-session version-match validation is out of scope for an HTTP-layer middleware and can be layered on if maintainers want it.

If maintainers prefer to land #260 / #277 separately first, this PR can be rebased onto them and reduced to the composition refactor + ProtocolVersionMiddleware. Happy to do that.

BC breaks

• StreamableHttpTransport::__construct — the $corsHeaders parameter is removed. The $middleware parameter consequently shifts one position. Positional callers passing the old $corsHeaders argument will get a TypeError at construction; switch to named arguments or drop the argument. logger/middleware are now positions 4/5 instead of 5/6.
• Default Access-Control-Allow-Origin is no longer *. Browser clients on a different origin will be blocked unless CorsMiddleware is configured with explicit allowedOrigins.

CHANGELOG.md entry added under 0.6.0.

Test plan

• vendor/bin/phpunit --testsuite=unit — 38 new/updated tests pass (3 middleware × ~10 tests each + transport integration). Full suite: 1 error + 2 failures are pre-existing on upstream/main (DocBlockParserTest missing Composer\Semver\VersionParser dev-dep, two DiscoveryTest fixtures) — verified by running the same tests against vanilla main with the branch stashed.
• vendor/bin/php-cs-fixer fix --dry-run — clean
• vendor/bin/phpstan analyse — clean for changed code; the one pre-existing error in DocBlockParserTest (missing dev-dep Composer\Semver\VersionParser) is unchanged
• Both OAuth examples (oauth-keycloak, oauth-microsoft) updated to spread the default stack so their behaviour is preserved

[chr-hertel]

Thanks for that proposal @sveneld - my solution was not on point, true.
i feel it is quite brittle for people to accidentally opt out of security features - the moment i would add my own custom middleware and forget to add the default ones, all protection is gone, right?

[sveneld]

Yes, if you pass your own middleware list, the default protection middleware will not be applied automatically.

That is why in the examples I explicitly show that custom middleware should be merged with the default middleware, rather than replacing it entirely:

$transport = new StreamableHttpTransport(
    $request,
    logger: $logger,
    middleware: [
        ...StreamableHttpTransport::defaultMiddleware(),
        new AuthMiddleware($responseFactory),
    ],
);

This keeps the default security protections enabled while still allowing custom middleware to be added.

[soyuka]

this could have false positives, suggestion:

$tokens = array_map('strtolower', array_map('trim', explode(',', $current)));
if ('*' === trim($current) || in_array('origin', $tokens, true)) {
    return $response;
}

[soyuka]

These make sense only if in a preflight request, suggestion:

$isPreflight = 'OPTIONS' === $request->getMethod()
    && $request->hasHeader('Access-Control-Request-Method');

if ($isPreflight && !$response->hasHeader('Access-Control-Allow-Methods')) {
    $response = $response->withHeader('Access-Control-Allow-Methods', $this->allowedMethodsHeader);
}
if ($isPreflight && !$response->hasHeader('Access-Control-Allow-Headers')) {
    $response = $response->withHeader('Access-Control-Allow-Headers', $this->allowedHeadersHeader);
}

[soyuka]

Suggested change

	array $exposedHeaders = [StreamableHttpTransport::SESSION_HEADER],
	array $exposedHeaders = [StreamableHttpTransport::SESSION_HEADER],
	bool $allowCredentials = false,

[soyuka]

if ($this->isWildcard && $allowCredentials) {
    throw new InvalidArgumentException(
        'Access-Control-Allow-Origin: * is incompatible with Access-Control-Allow-Credentials: true.',
    );
}

[soyuka]

add Access-Control-Allow-Credentials: true

Something like:

  if ($this->allowCredentials && null !== $allowedOrigin
      && !$response->hasHeader('Access-Control-Allow-Credentials')) {
      $response = $response->withHeader('Access-Control-Allow-Credentials', 'true');
  }

• tests

[soyuka]

Suggested change

	$parsed = parse_url($origin);
	if (false === $parsed || !isset($parsed['host'])) {
	return false;
	}
	return \in_array(strtolower($parsed['host']), $this->allowedHosts, true);
	$host = parse_url($origin, \PHP_URL_HOST);
	if (!is_string($host) || '' === $host) {
	return false;
	}
	return \in_array(strtolower($host), $this->allowedHosts, true);

[soyuka]

Suggested change

	array $allowedHosts = ['localhost', '127.0.0.1', '[::1]', '::1'],
	array $allowedHosts = ['localhost', '127.0.0.1', '[::1]'],

Useless value will never get matched below

[soyuka]

Suggested change

	private function createForbiddenResponse(string $message): ResponseInterface
	{
	return JsonRpcErrorResponse::create($this->responseFactory, $this->streamFactory, 403, $message);
	}
	private function createForbiddenResponse(string $message): ResponseInterface
	{
	return $this->responseFactory->createResponse(403)
	->withHeader('Content-Type', 'text/plain')
	->withBody($this->streamFactory->createStream($message));
	}

I feel Error::forInvalidRequest($message) is wrong here.

[soyuka]

Suggested change

	public static function create(
	ResponseFactoryInterface $responseFactory,
	StreamFactoryInterface $streamFactory,
	int $statusCode,
	string $message,
	): ResponseInterface {
	$body = json_encode(Error::forInvalidRequest($message), \JSON_THROW_ON_ERROR);
	return $responseFactory
	->createResponse($statusCode)
	->withHeader('Content-Type', 'application/json')
	->withBody($streamFactory->createStream($body));
	}
	public static function create(
	ResponseFactoryInterface $responseFactory,
	StreamFactoryInterface $streamFactory,
	int $statusCode,
	Error $error,
	): ResponseInterface {
	$body = json_encode($error, \JSON_THROW_ON_ERROR);
	return $responseFactory->createResponse($statusCode)
	->withHeader('Content-Type', 'application/json')
	->withBody($streamFactory->createStream($body));
	}

[soyuka]

Suggested change

	return JsonRpcErrorResponse::create($this->responseFactory, $this->streamFactory, 400, $message);
	return JsonRpcErrorResponse::create($this->responseFactory, $this->streamFactory, 400, Error::forInvalidParams($message));

[sveneld]

Thanks for the review, @soyuka — all inline comments addressed in the latest commit:

• CorsMiddleware: Methods/Headers emitted only on preflight; Vary check is token-based now; added allowCredentials flag (emits the header, throws when combined with wildcard).
• DnsRebindingProtectionMiddleware: plain-text 403 body; parse_url(..., PHP_URL_HOST); dropped unreachable '::1' from the default allowlist.
• ProtocolVersionMiddleware + JsonRpcErrorResponse: helper now takes a JsonRpc\Error; the middleware passes Error::forInvalidParams($message).

@chr-hertel — on the "easy to opt out" concern: passing middleware: [] now emits a warning-level log through the transport's LoggerInterface, naming the disabled protections and pointing at the spread-defaults pattern. A visible signal in logs feels like the right weight for an explicit opt-out.