feat(test-servers): a CIMD showcase fixture that serves its own client metadata document

[cliffhall]

Closes #2306

⚠️ Do not merge before #2304 (the v2.6.0 milestone merge). That PR's guarantee is that its tree is byte-identical to origin/v2/main; landing this first breaks that equality and drags v2.7.0 work into the 2.6.0 release. This is milestoned v2.7.0 for that reason.

Why

In CIMD (SEP-991) the client_id is a URL that the authorization server dereferences to learn the client's metadata. Nothing in this repo served such a document, so a fixture could advertise client_id_metadata_document_supported and still be unusable — exercising CIMD meant standing up a second host by hand.

That is why #2242 shipped verified by its tests alone, and why the v2.6.0 release smoke recorded it as the one contribution with an observable UI surface that could not be reached. This PR is that missing piece, and #2242 has now been driven by hand against it.

What's here

• oauth.clientMetadata / oauth.clientMetadataPath and a route serving the document when supportCIMD is on. Gated on supportCIMD as well as on the document's presence: advertising a client the server would then refuse to honour is a worse fixture than serving nothing.
• The document's client_id is derived from the request, not from a configured issuer, so it stays correct when the harness picks the port — which the integration test does.
• test-servers/configs/oauth-cimd-http.json.
• An integration test in the established src/test/integration/mcp/ shape.
• A docs/test-servers.md section.

supportDCR: false is load-bearing, not tidiness

With DCR available, a CIMD failure silently succeeds via dynamic registration and the reproduction proves nothing.

This is not hypothetical — it happened while building this. A misconfigured run connected happily and Connection Info read Dynamic (DCR) with a test_client_… id. It reads as success until you check the client id, which is precisely the confusion #2242 is about. With DCR off, CIMD is the only path that can complete, so reaching a connected state is itself the assertion.

The test pins it so it stays that way:

expect(metadata.registration_endpoint).toBeUndefined();

Verification

npm run local:gate — pass, in a dedicated worktree with its own full npm install. Web tests went 418 files / 8001 tests → 419 / 8005, i.e. exactly the four added here; 11 smokes OK.

Driven end to end against the fixture (this is what cleared the v2.6.0 ledger finding):

Connection Info → OAuth Details
  Status              AUTHORIZED
  Client ID           https://127.0.0.1:8443/client-metadata.json
  Client registration Client ID Metadata (CIMD)

The authorize request carried client_id=https%3A%2F%2F127.0.0.1%3A8443%2Fclient-metadata.json against a server advertising no registration_endpoint, so nothing about it could have been DCR.

What this does not fix — #2305

That drive needed a self-signed HTTPS listener holding nothing but the JSON document, plus NODE_TLS_REJECT_UNAUTHORIZED=0 in the test server's environment so its own fetch of the document would succeed.

The reason is our own validation, not the SDK's: getCimdClientMetadataUrlError rejects any CIMD metadata URL that is not HTTPS, with no loopback exemption, and applies that to client.json on disk as well as to the settings form. So this server's http:// document is not a legal clientMetadataUrl. It exists for the authorization-server side of the flow and for the assertions in this PR's test.

Filed as #2305 — the same over-narrow allow-list shape as #2280 / #1944, from the other side. This PR delivers the fixture; #2305 is what would make it pleasant to use.

Two things worth knowing, now in the docs

• CIMD is install-level config (client.json → cimd.{enabled,clientMetadataUrl}, reachable from Client settings), not per-server. A clientMetadataUrl written into a catalog entry's oauth block is silently ignored.
• A deep link creates its own server entry rather than reusing a configured one, so it cannot carry per-server OAuth config.

No UI or TUI surface changes, so no screenshots apply.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RsmR1iQstcrEzJFmgZXGLi

[Copilot]

🟡 Changes recommended

The configurable path validation and exact query-bearing client_id handling must be corrected before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a CIMD showcase fixture that serves its own client metadata document.

Changes:

• Adds configurable CIMD metadata serving.
• Adds a DCR-disabled showcase fixture.
• Adds integration coverage and documentation.

File summaries

File	Review
test-servers/src/test-server-oauth.ts	Serves CIMD metadata. Requires path validation and preserving query parameters in the returned client_id (moderate).
test-servers/src/load-config.ts	Adds CIMD configuration fields; clientMetadataPath validation is required (moderate).
test-servers/src/composable-test-server.ts	Exposes CIMD options; programmatic path validation is required (moderate).
test-servers/configs/oauth-cimd-http.json	Defines the CIMD showcase fixture.
docs/test-servers.md	Documents CIMD testing; contains an inaccurate fixed-port warning (nit).
clients/web/src/test/integration/mcp/oauth-cimd-fixture.test.ts	Tests fixture metadata and DCR exclusion.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[cliffhall]

Copilot review round 1 — all three findings addressed (a8cbc50)

Replies are inline on each thread; mirrored here because inline replies go hidden once the fix is pushed.

1. clientMetadataPath unvalidated (test-server-oauth.ts) — fixed. It now goes through the same isOriginRelativePath check as the other two metadata paths, in both places: loadConfig for the JSON route, and a clientMetadataPath(config) helper that throws at server setup for a ServerConfig built in code. The error message states why this one is sharper: the value becomes the document's own client_id, so //other-host/doc would publish a client id naming a host this server does not serve. Scope note: the setup check runs where the route is registered (supportCIMD && clientMetadata), so with CIMD off an unused bad path stays inert.

2. client_id dropped a query-bearing document URL — fixed. Built from req.originalUrl now, so /client-metadata.json?profile=a answers with a client_id byte-identical to the URL fetched. Reflecting the query is safe: it only lands in a JSON string, the path half is pinned by the matched route, and the configured path is now validated to carry no query of its own.

3. Docs fixed-port warning — removed. It was carried over from the fixture above and wrong twice (no issuerUrl is configured; the client_id is request-derived). Replaced with the accurate note, which now points at the fixed-port dependency that does bite — redirect_uris.

Test strength

Three tests added to oauth-cimd-fixture.test.ts, each mutation-checked against its own guard (7 tests in the file):

guard removed	failing test	result
client_id from originalUrl → registered route	preserves a query-bearing document URL in the client_id it publishes	1 failed, 6 passed
loadConfig path check	rejects a clientMetadataPath that would publish a foreign client_id	1 failed, 6 passed
server-setup path check	rejects the same path built programmatically rather than from JSON	1 failed, 6 passed

One guard removed fails exactly one test, so each is detected and none is redundant. Restored: 7 passed.

Verification

npm run local:gate — pass, in this PR's worktree. One caveat worth recording: the first run went red at smoke:web:firefox with MCP Inspector PORT IS IN USE at http://127.0.0.1:6298, caused by a concurrent gate run in another worktree on this machine, not by this diff (which touches no client source). Re-run once that finished: smoke:web:firefox OK on all three legs, local:storybook 123 files / 525 tests passed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UWGH2ytPzSPxnp4cibaV3Z

[Copilot]

🟢 Approval recommended

The implementation satisfies the linked issue’s acceptance criteria with appropriate validation, integration coverage, and documentation.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.