[Server] Extract CORS handling into CorsMiddleware by chr-hertel · Pull Request #277 · modelcontextprotocol/php-sdk

chr-hertel · 2026-04-11T14:06:46Z

Summary

Extracts inline CORS handling from StreamableHttpTransport into a dedicated CorsMiddleware (PSR-15)
CorsMiddleware is automatically prepended to the middleware chain, handling OPTIONS preflight and applying CORS headers to all responses
Changes default Access-Control-Allow-Origin from * (allow all) to not set (block cross-origin), with explicit opt-in via allowedOrigins
- addressing a security design flaw reported by @srikanthramu
- Fix Hardcoded Wildcard CORS (Access-Control-Allow-Origin: *) #280

Breaking Changes

The $corsHeaders constructor parameter on StreamableHttpTransport is replaced by ?CorsMiddleware $corsMiddleware
Default CORS behavior no longer sets Access-Control-Allow-Origin: * — use new CorsMiddleware(allowedOrigins: ['*']) to restore

CodeWithKyrian · 2026-04-11T15:36:54Z

This is a solid refactor...makes a lot of sense.

One thing I was wondering though: instead of introducing a dedicated $corsMiddleware parameter on the transport, would it be feasible to just work with the existing $middleware array?

For example:

accept CorsMiddleware as part of the middleware list
detect if it’s already present
ensure it’s in the correct position (e.g. prepend or reorder if needed)
optionally inject a default if none is provided

That way everything stays within a single middleware pipeline instead of splitting configuration paths.

I get that this might complicate the setup a bit, so maybe that’s why you went this route...but I was just curious if you explored that approach at all?

chr-hertel · 2026-04-11T16:00:10Z

@CodeWithKyrian Thanks, yeah, true - so similar to the approach in #260, right?

CodeWithKyrian · 2026-04-11T16:03:15Z

Yes exactly!

soyuka · 2026-04-14T06:19:10Z

+
+        if (!$hasCorsMiddleware) {
+            array_unshift($this->middleware, new CorsMiddleware());
+        }


let's say I use the mcp bundle with the famous https://github.com/nelmio/NelmioCorsBundle how am I going to avoid conflicts?

Haven't tested, but we'd need a way to opt-out completely you mean?

yes can we just remove these checks? we add it by default in our server in here but lets not add it if not found as it prevents other libraries to do their own cors handling.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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 modelcontextprotocol#260 (DNS rebinding), modelcontextprotocol#277 (CORS extraction) and modelcontextprotocol#306 (protocol version validation).

chr-hertel · 2026-05-17T20:08:20Z

Closed in favor of #307

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 modelcontextprotocol#260 (DNS rebinding), modelcontextprotocol#277 (CORS extraction) and modelcontextprotocol#306 (protocol version validation).

…ultMiddleware() factory (#307) * [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>

chr-hertel added this to the 0.5.0 milestone Apr 11, 2026

chr-hertel changed the title ~~Extract CORS handling into CorsMiddleware~~ [Server] Extract CORS handling into CorsMiddleware Apr 11, 2026

chr-hertel added the Server Issues & PRs related to the Server component label Apr 11, 2026

chr-hertel force-pushed the refactor/cors-middleware branch 5 times, most recently from 2812af8 to 2ed3d9c Compare April 11, 2026 14:25

chr-hertel marked this pull request as ready for review April 11, 2026 14:27

chr-hertel requested review from CodeWithKyrian, Nyholm and soyuka as code owners April 11, 2026 14:27

chr-hertel added the breaking change Breaking the Backwards Compatibility Promise label Apr 11, 2026

chr-hertel mentioned this pull request Apr 11, 2026

Hardcoded Wildcard CORS (Access-Control-Allow-Origin: *) #280

Closed

chr-hertel force-pushed the refactor/cors-middleware branch 2 times, most recently from d4bb9f4 to e69f03c Compare April 11, 2026 17:57

soyuka reviewed Apr 14, 2026

View reviewed changes

[Server] refactor: extract CORS handling into CorsMiddleware

a19723e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chr-hertel force-pushed the refactor/cors-middleware branch from 8d26c5c to a19723e Compare April 20, 2026 19:24

chr-hertel modified the milestones: 0.5.0, 0.6.0 Apr 26, 2026

sveneld mentioned this pull request May 13, 2026

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

Merged

4 tasks

chr-hertel closed this May 17, 2026

chr-hertel deleted the refactor/cors-middleware branch May 17, 2026 20:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Server] Extract CORS handling into CorsMiddleware#277

[Server] Extract CORS handling into CorsMiddleware#277
chr-hertel wants to merge 1 commit into
mainfrom
refactor/cors-middleware

chr-hertel commented Apr 11, 2026 •

edited

Loading

Uh oh!

CodeWithKyrian commented Apr 11, 2026

Uh oh!

chr-hertel commented Apr 11, 2026

Uh oh!

CodeWithKyrian commented Apr 11, 2026

Uh oh!

soyuka Apr 14, 2026

Uh oh!

chr-hertel Apr 14, 2026

Uh oh!

soyuka May 12, 2026

Uh oh!

chr-hertel commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

chr-hertel commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Changes

Uh oh!

CodeWithKyrian commented Apr 11, 2026

Uh oh!

chr-hertel commented Apr 11, 2026

Uh oh!

CodeWithKyrian commented Apr 11, 2026

Uh oh!

soyuka Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

chr-hertel Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

soyuka May 12, 2026

Choose a reason for hiding this comment

Uh oh!

chr-hertel commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chr-hertel commented Apr 11, 2026 •

edited

Loading