feat: add withOAuthProtectedResource

[raulb]

What kind of change does this PR introduce?

Fixes AI-1071

What is the current behavior?

withOAuthProtectedResource (RFC 9728 OAuth Protected Resource middleware, metadata route + 401 enrichment) lives in https://github.com/supabase-community/edge-function-mcp-sandbox.

What is the new behavior?

Adds withOAuthProtectedResource, resourceMetadataResponse, and unauthorizedResponse as a new top-level module (src/oauth-protected-resource/), exported from the package root. Docs/examples are generalized.

Additional context

This other PR updates its code to make use of this new function, updating the notes-app example over to this package.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@113

commit: 4aa7dfb

[mandarini]

@raulb While rebasing this onto main I pushed some small commits: forwarding the platform second argument that withSupabase now consumes (post #88), wiring the ./oauth-protected-resource subpath export into tsdown/npm/JSR like the other submodules, and two behavior nits: the 401 enrichment no longer overwrites a WWW-Authenticate the handler already set, and the metadata endpoint now answers CORS (header on the 200, preflight on OPTIONS) so browser clients like MCP Inspector can read it. Routing, the 404 contract, and url.ts are untouched. Shout if you want any of it reverted.

[mandarini]

oh one more thing @raulb. Not a blocker. VSCode and Claude Code don't read the WWW-Authenticate hint. They probe /.well-known/oauth-protected-resource directly, and nothing serves that today. So those clients can't discover auth for functions using this middleware at all. That needs a platform-level fix (only the proxy can own the domain root). Is that on anyone's radar?

[raulb]

@raulb While rebasing this onto main I pushed some small commits: forwarding the platform second argument that withSupabase now consumes (post #88), wiring the ./oauth-protected-resource subpath export into tsdown/npm/JSR like the other submodules, and two behavior nits: the 401 enrichment no longer overwrites a WWW-Authenticate the handler already set, and the metadata endpoint now answers CORS (header on the 200, preflight on OPTIONS) so browser clients like MCP Inspector can read it. Routing, the 404 contract, and url.ts are untouched. Shout if you want any of it reverted.

@mandarini thank you! will review

oh one more thing @raulb. Not a blocker. VSCode and Claude Code don't read the WWW-Authenticate hint. They probe /.well-known/oauth-protected-resource directly, and nothing serves that today. So those clients can't discover auth for functions using this middleware at all. That needs a platform-level fix (only the proxy can own the domain root). Is that on anyone's radar?

@mandarini it was not on my radar. Scanned Linear and spotted this other issue. Is this what you're referring to? https://linear.app/supabase/issue/FDBKIN-15575/allow-hosting-well-known-endpoints-at-the-project-root-for-edge

[raulb]

@mandarini validated this with https://github.com/supabase-community/edge-function-mcp-sandbox/pull/9 and everything's working. I'll keep working on some other items separately, but let me know if this PR needs any more additional work. Thank you!

[mandarini]

@raulb Yes, that's exactly it. Clients that skip the WWW-Authenticate hint (VSCode, Claude Code) can only discover auth through a root-level /.well-known endpoint, so that ticket is the platform-side half of what this middleware does. One detail for whenever it gets built: the proxy will rewrite root probes to some internal path, and that target has to match what this middleware serves (today /{fn}/oauth-protected-resource), or the middleware can serve both. Nothing more needed on this PR from my side. Approving.