fix: make CIMD explicitly opt-in via clientIdMetadataDocumentEnabled

[mattzcarey]

Summary

Fixes #156

Three changes to make CIMD (Client ID Metadata Document) robust and explicitly opt-in:

1. Explicit opt-in via clientIdMetadataDocumentEnabled

CIMD previously auto-enabled whenever the global_fetch_strictly_public compatibility flag was present. This caused 500 crashes for servers where URL-shaped client_ids (e.g. https://claude.ai/oauth/mcp-oauth-client-metadata) hit bot-protected endpoints, since there was no way to disable CIMD independently of the compat flag.

• Added clientIdMetadataDocumentEnabled?: boolean to OAuthProviderOptions (defaults to false)
• When not enabled (default): URL-formatted client_ids fall through to standard KV lookup — no fetch, no crash
• When enabled without compat flag: throws a clear error telling you to add global_fetch_strictly_public
• When enabled with compat flag: CIMD works as before
• Metadata endpoint reports client_id_metadata_document_supported: true only when both the option and compat flag are set

2. Graceful CIMD fetch failure handling

When CIMD is enabled and the metadata fetch fails (size limit exceeded, timeout, HTTP error, invalid JSON, network error, metadata validation failure), getClient() now catches the error and returns null instead of throwing. This means:

• Callers see "Invalid client" instead of an unhandled 500 error
• The token endpoint returns a proper invalid_client OAuth error response (HTTP 401), which the typescript-sdk client can catch and retry with DCR
• No more production crashes from bot-protected endpoints

3. Structured error logging

CIMD fetch failures are logged via console.warn with the client URL and error message, so operators can debug issues without the error propagating as a 500:

CIMD fetch failed for https://client.example.com/metadata.json: Failed to fetch client metadata: HTTP 404

Usage

new OAuthProvider({
  clientIdMetadataDocumentEnabled: true, // opt-in to CIMD
  // ...
})

Source changes (src/oauth-provider.ts)

• Added clientIdMetadataDocumentEnabled option to OAuthProviderOptions
• getClient(): new CIMD opt-in gate → KV fallback when disabled; try/catch with console.warn when enabled
• Metadata endpoint: client_id_metadata_document_supported now requires both option AND compat flag

Test plan

• All 251 tests pass (5 new test groups added)
• Explicit opt-in tests: default falls through to KV, metadata reports false, enabled+flag works, enabled-no-flag throws
• Error logging tests: verifies console.warn is called with client URL and error details for HTTP failures, timeouts, size limits, and validation failures
• Token endpoint test: CIMD failure returns proper invalid_client OAuth error (401)
• Existing CIMD success tests updated to use clientIdMetadataDocumentEnabled: true
• Existing failure tests updated to expect "Invalid client" instead of specific internal errors
• Typecheck passes
• Prettier passes
• Deployed to staging (staging.mcp.cloudflare.com) and tested with Claude.ai as client — both CIMD disabled and enabled modes work correctly

[changeset-bot]

🦋 Changeset detected

Latest commit: 97ae17c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/workers-oauth-provider	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/workers-oauth-provider/@cloudflare/workers-oauth-provider@158

commit: 97ae17c

[mattzcarey]

Tested on staging

Deployed to staging.mcp.cloudflare.com (cloudflare/mcp) and verified:

1. CIMD disabled (default): URL-shaped client_ids (e.g. https://claude.ai/oauth/mcp-oauth-client-metadata) no longer crash the server — they fall through to KV lookup gracefully.
2. CIMD enabled (clientIdMetadataDocumentEnabled: true): CIMD works as expected with the compat flag. Failures are logged via console.warn and return "Invalid client" instead of 500.
3. Typecheck passes with the new option in cloudflare/mcp.

Tested with Claude.ai as the client.