Support scope challenge handling and 403s properly

[irvinebroque]

Support permission upgrades.

The MCP authorization specification describes HTTP 403 Bearer challenges with insufficient_scope errors

Runtime Insufficient Scope Errors

When a client makes a request with an access token with insufficient scope during runtime operations, the server SHOULD respond with:
HTTP 403 Forbidden status code (per RFC 6750 Section 3.1)
WWW-Authenticate header with the Bearer scheme and additional parameters:
error="insufficient_scope" - indicating the specific type of authorization failure
scope="required_scope1 required_scope2" - specifying the minimum scopes needed for the operation
resource_metadata - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
error_description (optional) - human-readable description of the error

Today we don't support these properly. This is a bit of a hack to add an observer to handle this better.

Depends on #255. — Preserve useful Cloudflare API errors in tool results — that should be reviewed first

Really don't think this is one-shot right implementation, putting up draft so that we can discuss how we would want to handle

[mattzcarey]

Thanks Brendan, this draft set out the problem well. Replaced by #261 (on top of #259 and #260), which answers with the spec's 403 insufficient_scope using workers-oauth-provider's insufficientScope().

Differences from this draft:

• It challenges only after Cloudflare actually refuses, so no reviewed-operations table is needed. The permission-name mapping is only used to name a scope, and a connection that already holds an accepted scope is never challenged, so it can't loop.
• Replay safety: an endpoint tool sends one request. For execute, the sandbox wraps fetch and reports whether every request was a read or was refused. Its report is untrusted, but lying gains nothing: code can trigger the same challenge by calling the endpoint. The host accepts only catalog scopes the connection lacks.
• 2025-era POSTs from OAuth connections are served as JSON so the 403 can replace the result. Your ?oauthChallenge=tool idea is kept as ?scopeChallenge=tool for ChatGPT.