modelcontextprotocol/php-sdk
Watch
1
0
Fork
You've already forked php-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* [Server] Add CORS, DNS rebinding and protocol version middleware

Introduce three PSR-15 middleware for `StreamableHttpTransport` exposed
through a public `StreamableHttpTransport::defaultMiddleware()` factory
composed automatically when no middleware is passed.

- `CorsMiddleware`: secure-by-default (no `Access-Control-Allow-Origin`),
  configurable allowlist, reflects matching origin with `Vary: Origin`
  to protect shared caches.
- `DnsRebindingProtectionMiddleware`: validates `Origin`/`Host` against
  a hostname allowlist (localhost-only by default).
- `ProtocolVersionMiddleware`: rejects requests carrying an unsupported
  `Mcp-Protocol-Version` header with `400 Bad Request`.

The transport no longer applies CORS via an `instanceof + array_unshift`
post-hook; the middleware parameter is nullable — `null` installs the
secure defaults, `[]` disables them, and users compose by spreading
`StreamableHttpTransport::defaultMiddleware()`. `SESSION_HEADER` and
`PROTOCOL_VERSION_HEADER` are promoted to public constants so middleware
can reuse them.

BC breaks:
- The `corsHeaders` constructor parameter is removed; the `middleware`
  parameter shifts one position. Positional callers passing the old
  `corsHeaders` argument must switch to named arguments or drop it.
- Default `Access-Control-Allow-Origin` is no longer `*`.

Addresses #260 (DNS rebinding), #277 (CORS extraction) and #306
(protocol version validation).

* [Server] Address review feedback on middleware defaults

- CorsMiddleware: emit Access-Control-Allow-Methods/Headers only on
  preflight per CORS spec; tokenize Vary header to avoid substring
  false-positives; add allowCredentials flag that emits
  Access-Control-Allow-Credentials and throws when combined with
  wildcard origin.
- DnsRebindingProtectionMiddleware: return plain-text 403 body
  (HTTP-level rejection, not JSON-RPC); use parse_url(..., PHP_URL_HOST)
  for origin parsing; drop redundant unbracketed '::1' from default
  allowlist.
- ProtocolVersionMiddleware: use Error::forInvalidParams instead of
  forInvalidRequest -- JSON-RPC -32602 fits header-value rejection
  better.
- JsonRpcErrorResponse::create now accepts a JsonRpc\Error so callers
  choose the error code.
- StreamableHttpTransport: emit a warning log when an explicit empty
  middleware list is passed, so operators can spot accidental bypass
  of the default security stack.

* [Server] Fix CI: switch warning-log tests to PHPUnit mocks

Replace the anonymous AbstractLogger fixture in
StreamableHttpTransportTest with `$this->createMock(LoggerInterface::class)`
so the test does not declare a `log()` signature at all. That sidesteps
both the psr/log v1 LSP incompatibility (untyped parameter) and the
phpstan `missingType.parameter` complaint in one move, and matches how
the rest of the suite (CallToolHandlerTest etc.) fakes loggers.

* Update src/Server/Transport/Http/Middleware/CorsMiddleware.php

Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>

---------

Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>
This commit is contained in:
Volodymyr Panivko 2026-05-25 13:49:43 +02:00 • committed by GitHub
commit 293a5880e4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 1340 additions and 154 deletions
Download patch file Download diff file Expand all files Collapse all files

271
tests/Unit/Server/Transport/StreamableHttpTransportTest.php
View file

@ -11,9 +11,12 @@
namespace Mcp\Tests\Unit\Server\Transport;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Server\Transport\Http\Middleware\CorsMiddleware;
use Mcp\Server\Transport\Http\Middleware\DnsRebindingProtectionMiddleware;
use Mcp\Server\Transport\Http\Middleware\ProtocolVersionMiddleware;
use Mcp\Server\Transport\StreamableHttpTransport;
use Nyholm\Psr7\Factory\Psr17Factory;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
use Psr\Http\Message\ResponseFactoryInterface;
@ -21,120 +24,201 @@ use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Log\LoggerInterface;
final class StreamableHttpTransportTest extends TestCase
{
public static function corsHeaderProvider(): iterable
private Psr17Factory $factory;
protected function setUp(): void
{
yield 'GET (middleware returns 401)' => ['GET', false, 401];
yield 'POST (middleware returns 401)' => ['POST', false, 401];
yield 'DELETE (middleware returns 401)' => ['DELETE', false, 401];
yield 'OPTIONS (middleware delegates -> transport handles preflight)' => ['OPTIONS', true, 204];
yield 'GET (middleware delegates -> transport handles preflight)' => ['GET', true, 405];
yield 'POST (middleware delegates -> transport handles preflight)' => ['POST', true, 202];
yield 'DELETE (middleware delegates -> transport handles preflight)' => ['DELETE', true, 400];
$this->factory = new Psr17Factory();
}
#[DataProvider('corsHeaderProvider')]
#[TestDox('CORS headers are always applied')]
public function testCorsHeader(string $method, bool $middlewareDelegatesToTransport, int $expectedStatusCode): void
#[TestDox('default middleware is applied when none is passed')]
public function testDefaultMiddlewareIsAppliedWhenOmitted(): void
{
$factory = new Psr17Factory();
$request = $factory->createServerRequest($method, 'https://example.com');
// Preflight: OPTIONS + Access-Control-Request-Method — CorsMiddleware advertises Methods/Headers only on preflight.
$request = $this->factory
->createServerRequest('OPTIONS', 'http://localhost/')
->withHeader('Host', 'localhost')
->withHeader('Access-Control-Request-Method', 'POST');
$middleware = new class($factory, $expectedStatusCode, $middlewareDelegatesToTransport) implements MiddlewareInterface {
public function __construct(
private ResponseFactoryInterface $responseFactory,
private int $expectedStatusCode,
private bool $middlewareDelegatesToTransport,
) {
}
$transport = new StreamableHttpTransport($request, $this->factory, $this->factory);
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
if ($this->middlewareDelegatesToTransport) {
return $handler->handle($request);
}
$response = $transport->listen();
return $this->responseFactory->createResponse($this->expectedStatusCode);
}
};
$this->assertSame(204, $response->getStatusCode());
$this->assertFalse($response->hasHeader('Access-Control-Allow-Origin')); // secure-by-default
$this->assertSame('GET, POST, DELETE', $response->getHeaderLine('Access-Control-Allow-Methods'));
$this->assertNotSame('', $response->getHeaderLine('Access-Control-Allow-Headers'));
$this->assertNotSame('', $response->getHeaderLine('Access-Control-Expose-Headers'));
}
#[TestDox('default middleware blocks non-localhost Origin')]
public function testDefaultMiddlewareBlocksRebindingAttempt(): void
{
$request = $this->factory
->createServerRequest('POST', 'http://localhost/')
->withHeader('Host', 'localhost')
->withHeader('Origin', 'http://evil.example.com');
$transport = new StreamableHttpTransport($request, $this->factory, $this->factory);
$response = $transport->listen();
$this->assertSame(403, $response->getStatusCode());
}
#[TestDox('default middleware rejects unsupported MCP-Protocol-Version')]
public function testDefaultMiddlewareRejectsUnsupportedProtocolVersion(): void
{
$request = $this->factory
->createServerRequest('POST', 'http://localhost/')
->withHeader('Host', 'localhost')
->withHeader(StreamableHttpTransport::PROTOCOL_VERSION_HEADER, '1900-01-01');
$transport = new StreamableHttpTransport($request, $this->factory, $this->factory);
$response = $transport->listen();
$this->assertSame(400, $response->getStatusCode());
}
#[TestDox('explicit empty middleware list disables defaults and emits a warning log')]
public function testEmptyMiddlewareListDisablesDefaultsAndWarns(): void
{
$request = $this->factory
->createServerRequest('POST', 'http://localhost/')
->withHeader('Host', 'evil.example.com')
->withHeader('Origin', 'http://evil.example.com');
$logger = $this->createMock(LoggerInterface::class);
$logger->expects($this->once())
->method('warning')
->with($this->stringContains('empty middleware list'));
$transport = new StreamableHttpTransport(
$request,
$factory,
$factory,
$this->factory,
$this->factory,
$logger,
[],
null,
[$middleware],
);
$response = $transport->listen();
$this->assertSame($expectedStatusCode, $response->getStatusCode(), $response->getBody()->getContents());
$this->assertTrue($response->hasHeader('Access-Control-Allow-Origin'));
$this->assertTrue($response->hasHeader('Access-Control-Allow-Methods'));
$this->assertTrue($response->hasHeader('Access-Control-Allow-Headers'));
$this->assertTrue($response->hasHeader('Access-Control-Expose-Headers'));
$this->assertSame('*', $response->getHeaderLine('Access-Control-Allow-Origin'));
$this->assertSame('GET, POST, DELETE, OPTIONS', $response->getHeaderLine('Access-Control-Allow-Methods'));
$this->assertSame(
'Accept,Authorization,Content-Type,Last-Event-ID,Mcp-Protocol-Version,Mcp-Session-Id',
$response->getHeaderLine('Access-Control-Allow-Headers')
);
$this->assertSame('Mcp-Session-Id', $response->getHeaderLine('Access-Control-Expose-Headers'));
// No CORS, no DNS rebinding check — transport just answers.
$this->assertNotSame(403, $response->getStatusCode());
$this->assertFalse($response->hasHeader('Access-Control-Allow-Origin'));
$this->assertFalse($response->hasHeader('Access-Control-Allow-Methods'));
}
#[TestDox('transport replaces existing CORS headers on the response')]
public function testCorsHeadersAreReplacedWhenAlreadyPresent(): void
#[TestDox('null middleware does not trigger the empty-list warning')]
public function testNullMiddlewareDoesNotWarn(): void
{
$factory = new Psr17Factory();
$request = $factory->createServerRequest('GET', 'https://example.com');
$request = $this->factory
->createServerRequest('OPTIONS', 'http://localhost/')
->withHeader('Host', 'localhost');
$middleware = new class($factory) implements MiddlewareInterface {
public function __construct(private ResponseFactoryInterface $responses)
{
}
$logger = $this->createMock(LoggerInterface::class);
$logger->expects($this->never())->method('warning');
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
return $this->responses->createResponse(200)
->withHeader('Access-Control-Allow-Origin', 'https://another.com');
}
};
$transport = new StreamableHttpTransport($request, $this->factory, $this->factory, $logger);
$transport->listen();
}
#[TestDox('custom middleware composes with default stack via spread')]
public function testDefaultsCanBeSpreadAndExtended(): void
{
$request = $this->factory
->createServerRequest('POST', 'http://localhost/')
->withHeader('Host', 'localhost');
$transport = new StreamableHttpTransport(
$request,
$factory,
$factory,
[],
$this->factory,
$this->factory,
null,
[$middleware],
[
...StreamableHttpTransport::defaultMiddleware(),
$this->stubAuth401(),
],
);
$response = $transport->listen();
$this->assertSame(200, $response->getStatusCode());
$this->assertSame('https://another.com', $response->getHeaderLine('Access-Control-Allow-Origin'));
$this->assertSame('GET, POST, DELETE, OPTIONS', $response->getHeaderLine('Access-Control-Allow-Methods'));
$this->assertSame(
'Accept,Authorization,Content-Type,Last-Event-ID,Mcp-Protocol-Version,Mcp-Session-Id',
$response->getHeaderLine('Access-Control-Allow-Headers')
);
$this->assertSame(401, $response->getStatusCode());
// CORS middleware is outermost — Expose-Headers is emitted on all responses, including 401.
$this->assertSame('Mcp-Session-Id', $response->getHeaderLine('Access-Control-Expose-Headers'));
}
#[TestDox('defaults can be filtered to drop DNS rebinding for proxy deployments')]
public function testDefaultsCanBeFilteredToDropDnsRebinding(): void
{
// Behind a reverse proxy: real Host is api.myapp.com, browser Origin is myapp.com.
// DnsRebindingProtectionMiddleware default (localhost-only) would 403 this — drop it.
$request = $this->factory
->createServerRequest('POST', 'http://api.myapp.com/')
->withHeader('Host', 'api.myapp.com')
->withHeader('Origin', 'https://myapp.com');
$transport = new StreamableHttpTransport(
$request,
$this->factory,
$this->factory,
null,
[
...array_filter(
StreamableHttpTransport::defaultMiddleware(),
static fn (MiddlewareInterface $m): bool => !$m instanceof DnsRebindingProtectionMiddleware,
),
$this->stubAuth401(),
],
);
$response = $transport->listen();
// Auth short-circuits with 401 — proves DNS rebinding didn't reject the request first.
$this->assertSame(401, $response->getStatusCode());
// CORS middleware is still in the chain — Expose-Headers attached to the 401.
$this->assertSame('Mcp-Session-Id', $response->getHeaderLine('Access-Control-Expose-Headers'));
}
#[TestDox('configured CorsMiddleware reflects matching Origin')]
public function testConfiguredCorsReflectsMatchingOrigin(): void
{
$request = $this->factory
->createServerRequest('POST', 'http://localhost/')
->withHeader('Host', 'localhost')
->withHeader('Origin', 'https://myapp.example.com');
$transport = new StreamableHttpTransport(
$request,
$this->factory,
$this->factory,
null,
[
new CorsMiddleware(allowedOrigins: ['https://myapp.example.com']),
new DnsRebindingProtectionMiddleware(allowedHosts: ['localhost']),
new ProtocolVersionMiddleware(),
],
);
$response = $transport->listen();
$this->assertSame('https://myapp.example.com', $response->getHeaderLine('Access-Control-Allow-Origin'));
}
#[TestDox('middleware runs before transport handles the request')]
public function testMiddlewareRunsBeforeTransportHandlesRequest(): void
{
$factory = new Psr17Factory();
$request = $factory->createServerRequest('OPTIONS', 'https://example.com');
$request = $this->factory->createServerRequest('OPTIONS', 'http://localhost/')
->withHeader('Host', 'localhost');
$state = new \stdClass();
$state->called = false;
$middleware = new class($state) implements MiddlewareInterface {
$spy = new class($state) implements MiddlewareInterface {
public function __construct(private \stdClass $state)
{
}
@ -149,11 +233,10 @@ final class StreamableHttpTransportTest extends TestCase
$transport = new StreamableHttpTransport(
$request,
$factory,
$factory,
[],
$this->factory,
$this->factory,
null,
[$middleware],
[$spy],
);
$response = $transport->listen();
@ -161,4 +244,34 @@ final class StreamableHttpTransportTest extends TestCase
$this->assertTrue($state->called);
$this->assertSame(204, $response->getStatusCode());
}
#[TestDox('non-middleware entries are rejected')]
public function testInvalidMiddlewareEntryThrows(): void
{
$request = $this->factory->createServerRequest('POST', 'http://localhost/');
$this->expectException(InvalidArgumentException::class);
new StreamableHttpTransport(
$request,
$this->factory,
$this->factory,
null,
[new \stdClass()], // @phpstan-ignore-line argument.type
);
}
private function stubAuth401(): MiddlewareInterface
{
return new class($this->factory) implements MiddlewareInterface {
public function __construct(private ResponseFactoryInterface $factory)
{
}
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
return $this->factory->createResponse(401);
}
};
}
}