fix: support path-suffixed well-known URLs for protected resource metadata (RFC 9728 §3.1)

[mattzcarey]

Summary

The /.well-known/oauth-protected-resource endpoint currently only matches the exact path, which is correct for origin-level resources but does not support resources with path components (e.g., /mcp). This is non-compliant with RFC 9728 §3.1 and the MCP Authorization Spec (draft 2025-03-26).

The Problem

When a resource identifier contains a path (e.g., https://example.com/mcp), RFC 9728 §3.1 requires the well-known URI to be constructed by inserting the well-known prefix between the authority and path:

If the resource identifier value contains a path or query component, any terminating slash (/) following the host component MUST be removed before inserting /.well-known/ and the well-known URI path suffix between the host component and the path and/or query components.

So for resource https://example.com/mcp, the metadata URL is:

GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
Host: example.com

RFC 9728 §3.3 then requires the resource value in the response to match:

The resource value returned MUST be identical to the protected resource's resource identifier value into which the well-known URI path suffix was inserted to create the URL used to retrieve the metadata. If these values are not identical, the data contained in the response MUST NOT be used.

The MCP spec explicitly requires this:

Well-Known URI: Serve metadata at a well-known URI as specified in RFC 9728. This can be either:

• At the path of the server's MCP endpoint: https://example.com/.well-known/oauth-protected-resource/public/mcp
• At the root: https://example.com/.well-known/oauth-protected-resource

The Fix

• Route both exact (/.well-known/oauth-protected-resource) and path-prefixed (/.well-known/oauth-protected-resource/*) requests to the metadata handler
• Derive the resource identifier by removing the well-known prefix from the request path (e.g., /.well-known/oauth-protected-resource/mcp → https://example.com/mcp)
• Handle OPTIONS/CORS preflight for path-suffixed variants
• Explicit resourceMetadata.resource overrides still take precedence

Test plan

• Existing tests pass (297/297)
• New test: path-based resource identifier returns correct resource field
• New test: nested path-based resource identifier (/api/v1/mcp)
• New test: OPTIONS preflight for path-suffixed URLs returns 204 with CORS
• New test: custom resourceMetadata.resource overrides derived value

[changeset-bot]

🦋 Changeset detected

Latest commit: d0ada69

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	Patch

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@173

commit: d0ada69