@cloudflare/workers-oauth-provider 0.10.4 → 1.1.0

package/docs/advanced-configuration.md

@@ -0,0 +1,370 @@
+# Advanced configuration
+
+This guide covers features that are useful for proxying another authorization system, changing token data during exchange, or operating the provider over time. Start with the main [README](../README.md) for MCP discovery, client registration, and a minimal Worker.
+
+## Token exchange callback
+
+`tokenExchangeCallback` runs during authorization code and refresh token exchanges. It is useful when the Worker also acts as an OAuth client to an upstream service.
+
+```ts
+new OAuthProvider({
+  // Other options...
+  tokenExchangeCallback: async (options) => {
+    if (options.grantType === 'authorization_code') {
+      const upstream = await exchangeUpstream(options.props.authorizationCode);
+      return {
+        accessTokenProps: {
+          ...options.props,
+          upstreamAccessToken: upstream.access_token,
+        },
+        newProps: {
+          ...options.props,
+          upstreamRefreshToken: upstream.refresh_token,
+        },
+        accessTokenTTL: upstream.expires_in,
+      };
+    }
+
+    if (options.grantType === 'refresh_token') {
+      const upstream = await refreshUpstream(options.props.upstreamRefreshToken);
+      return {
+        accessTokenProps: {
+          ...options.props,
+          upstreamAccessToken: upstream.access_token,
+        },
+        newProps: {
+          ...options.props,
+          upstreamRefreshToken: upstream.refresh_token,
+        },
+        accessTokenTTL: upstream.expires_in,
+        // The upstream just issued a new refresh token; let this grant live as long as it does.
+        refreshTokenIdleTTL: upstream.refresh_expires_in,
+      };
+    }
+  },
+});
+```
+
+The callback receives the grant type, client ID, user ID, grant ID, grant scopes, effective requested scopes, and decrypted props. It may return:
+
+- `accessTokenProps` for the current access token.
+- `newProps` for the grant and future refreshes.
+- `accessTokenTTL` for the current access token.
+- `refreshTokenTTL` during authorization code exchange.
+- `refreshTokenIdleTTL` during refresh token exchange, to move the grant's expiry to that many seconds from now.
+- `accessTokenScope` to narrow the current token.
+
+Return nothing to keep the existing values. If `newProps` is returned without `accessTokenProps`, the current access token also uses `newProps`.
+
+Throw `OAuthError` when an upstream failure should become an OAuth token response:
+
+```ts
+throw new OAuthError('temporarily_unavailable', {
+  description: 'The upstream authorization server is rate limited',
+  statusCode: 429,
+  headers: { 'Retry-After': '60' },
+});
+```
+
+Plain errors continue to surface as 500 responses.
+
+## OAuth 2.0 Token Exchange
+
+Set `allowTokenExchangeGrant: true` to enable RFC 8693. Clients can exchange an existing access token for a token with narrower scopes or a shorter lifetime. Token exchange cannot change the subject grant's registered canonical resource audience.
+
+Application code can also call:
+
+```ts
+await env.OAUTH_PROVIDER.exchangeToken({
+  subjectToken,
+  scope: ['documents:read'],
+  aud: 'https://mcp.example.com/mcp', // Must match the subject grant's resource
+  expiresIn: 900,
+});
+```
+
+The new token cannot exceed the subject token's scope ceiling or remaining lifetime. Its subject audience and any `aud` request value must resolve to the same registered resource. Subject-token failures return `invalid_request`, as RFC 8693 §2.2.2 requires.
+
+A client must register `urn:ietf:params:oauth:grant-type:token-exchange` in its `grant_types` to use the grant at the token endpoint. A token is exchanged by the client its grant was issued to. Exchanging a token that another client obtained is rejected with `invalid_request` unless `tokenExchangeCallback` allows that specific exchange. The callback sees both parties, so the decision can be per client pair:
+
+```ts
+tokenExchangeCallback: (options) => {
+  if (options.grantType === 'urn:ietf:params:oauth:grant-type:token-exchange') {
+    // options.clientId is the exchanging client; options.subjectClientId issued the grant.
+    const trusted = options.subjectClientId === options.clientId || DELEGATES.has(options.clientId);
+    return { allowCrossClientExchange: trusted };
+  }
+},
+```
+
+## Enterprise-managed authorization
+
+**Experimental.** The [MCP Enterprise-Managed Authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) is itself young, so the `enterpriseManagedAuthorization` option and its exported types (`EmaValidationError`, trust-policy shapes) are exempt from 1.x semver: they may change in a minor release, with the change documented in the changelog. Everything else on this page is stable API.
+
+The token endpoint accepts a validated ID-JAG assertion using the JWT bearer grant and returns an opaque, resource-bound access token.
+
+```ts
+new OAuthProvider({
+  // Other options...
+  resourceMetadata: { resource: 'https://mcp.example.com/mcp' },
+  enterpriseManagedAuthorization: {
+    trustedIssuers: async ({ iss }) =>
+      iss === 'https://idp.example.com'
+        ? {
+            issuer: iss,
+            jwksUri: 'https://idp.example.com/.well-known/jwks.json',
+            algorithms: ['RS256'],
+          }
+        : null,
+    mapClaims: async ({ claims, requestedScope }) => ({
+      userId: `enterprise-${encodeURIComponent(claims.sub)}`,
+      scope: requestedScope,
+      metadata: { issuer: claims.iss, subject: claims.sub },
+      props: { subject: claims.sub, email: claims.email },
+    }),
+  },
+});
+```
+
+The provider validates ID-JAG type, signature, issuer, audience, client binding, resource, timestamps, maximum lifetime, and replay identifier. The audience must be the authorization server issuer as a string or a single-element array. Assertions containing `authorization_details` or `cnf` fail closed until typed authorization-detail and DPoP processing are implemented. Refresh tokens are not issued for this grant.
+
+The grant requires client authentication by default. Set `allowPublicClients: true` only when public clients, including CIMD clients, must use it and the ID-JAG trust model is appropriate for the deployment.
+
+The default replay marker uses KV and is best effort across Cloudflare locations because KV is eventually consistent. Signature checks, short assertion lifetime, audience, resource, and client binding limit the replay window. The package does not currently expose a custom replay store, so do not describe ID-JAG redemption as globally single-use.
+
+## Client registration policy
+
+`clientRegistrationCallback` runs before a DCR client is stored. Return nothing to allow registration, or return an object to reject it:
+
+```ts
+clientRegistrationCallback: async ({ clientMetadata, request }) => {
+  if (!(await registrationIsAllowed(clientMetadata, request))) {
+    return {
+      code: 'access_denied',
+      description: 'Client registration is not permitted',
+      status: 403,
+    };
+  }
+};
+```
+
+The callback receives raw client metadata and a clone of the request whose body can still be read. If `software_statement` is present, the application is responsible for verifying it and applying its claims.
+
+`disallowPublicClientRegistration` affects DCR only. It does not prevent administrative code from creating a public client through `OAuthHelpers.createClient()`.
+
+## CIMD fetch errors
+
+A client ID Metadata Document can fail because of a timeout, network error, upstream response, or invalid document. Those failures are different from a client that does not exist.
+
+At the token endpoint, the provider keeps the wire response generic as `invalid_client`. It sends the diagnostic reason to `onError.internal` with category `client-id-metadata-document`, stable reason `metadata_resolution_failed`, the metadata URL, and the underlying message.
+
+`OAuthHelpers.lookupClient()`, `parseAuthRequest()`, `completeAuthorization()`, and `exchangeToken()` throw the exported `CimdFetchError` when they cannot resolve a CIMD client. `lookupClient()` returns `null` only when the client does not exist:
+
+```ts
+import { CimdFetchError } from '@cloudflare/workers-oauth-provider';
+
+try {
+  const client = await env.OAUTH_PROVIDER.lookupClient(clientId);
+} catch (error) {
+  if (error instanceof CimdFetchError) {
+    console.error(error.reason, error.metadataUrl, error.detail);
+  }
+  throw error;
+}
+```
+
+Do not log credentials or request bodies when recording these failures.
+
+## Custom error responses
+
+`onError` runs whenever the provider is about to return an OAuth error. Use it for logging or monitoring:
+
+```ts
+new OAuthProvider({
+  // Other options...
+  onError({ code, description, status, headers, internal }) {
+    console.warn({ code, description, status, headers, internal });
+  },
+});
+```
+
+Return a `Response` to replace the default response. Return nothing to use the provider's RFC-formatted response.
+
+### The internal reason
+
+Every OAuth error response the library builds — everything `onError` observes — carries `internal: { category, reason, detail? }`: the exact check that failed, which the wire response deliberately does not reveal (RFC 6749 §5.2). Bare non-OAuth responses (the credential-less `401` challenge, `404`/`405` on metadata URLs) carry no OAuth error and do not run `onError`. It exists only on the path to `onError` and is never sent to the client, so `error_description` can stay generic while logs and alerting key on stable slugs instead of matching text:
+
+```ts
+onError({ code, internal }) {
+  metrics.increment(`oauth.${internal.category}.${internal.reason}`);
+},
+```
+
+`category` names the subsystem (kebab-case), `reason` the failed check (snake_case); both are stable across versions — treat additions like new enum members. `detail`, when present, carries structured context such as the caught error, a CIMD fetch diagnosis, or the offending parameter name; it never carries a secret.
+
+| Category                           | Examples of `reason`                                                                                |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `token-endpoint-request`           | `method_not_allowed`, `repeated_parameter`, `grant_type_not_supported`, `grant_type_not_registered` |
+| `client-authentication`            | `client_not_found`, `client_secret_mismatch`, `multiple_authentication_methods`                     |
+| `client-id-metadata-document`      | `metadata_resolution_failed` and the other typed CIMD reasons                                       |
+| `authorization-code-grant`         | `code_replayed`, `code_verifier_mismatch`, `redirect_uri_mismatch`, `grant_not_found`               |
+| `refresh-token-grant`              | `refresh_token_mismatch`, `refresh_token_expired`, `client_mismatch`, `grant_not_found`             |
+| `token-exchange-grant`             | `subject_token_invalid`, `subject_token_near_expiry`, `requested_ttl_too_short`                     |
+| `enterprise-managed-authorization` | the typed EMA validator reasons (`signature_failed`, `replayed`, `aud_mismatch`, …)                 |
+| `resource-indicator`               | `resource_not_configured`, `resource_grant_mismatch`, `legacy_grant_unbound`                        |
+| `token-issuance`                   | `kv_rate_limited`, `requested_ttl_too_short`                                                        |
+| `token-revocation`                 | `token_missing`                                                                                     |
+| `client-registration`              | `json_malformed`, `metadata_invalid`, `callback_denied`, `payload_too_large`                        |
+| `protected-resource`               | `token_not_found`, `token_expired`, `audience_mismatch`, `resolver_rejected`                        |
+| `token-exchange-callback`          | `callback_error` — an `OAuthError` thrown by a deployer callback without its own `internal`         |
+
+`OAuthError(code, options)` supports token-endpoint errors from `tokenExchangeCallback`. `ExternalTokenError(code, options)` supports protected-resource errors from `resolveExternalToken`, including `requiredScopes` for an `insufficient_scope` challenge.
+
+Both classes accept a public `description`, `statusCode`, and response `headers`. Only the exported class intended for that callback boundary is converted. Other errors remain unexpected failures. An `OAuthError` may also set `options.internal` to give `onError` its own category and reason; without one it arrives as `{ category: 'token-exchange-callback', reason: 'callback_error', detail: error }`. An `invalid_grant` thrown from `tokenExchangeCallback` also revokes the grant the callback ran for, with its tokens: it means the grant can never work again. Use `temporarily_unavailable` for transient upstream failures (see [upstream-sign-in.md](upstream-sign-in.md#when-the-third-party-revokes-access)).
+
+## Token and client lifetimes
+
+| Option                  | Default           | Notes                                                                               |
+| ----------------------- | ----------------- | ----------------------------------------------------------------------------------- |
+| `accessTokenTTL`        | 3,600 seconds     | Must be at least 60 seconds because of KV limits                                    |
+| `refreshTokenTTL`       | 2,592,000 seconds | 30 days; set to `0` to disable refresh tokens; explicit `undefined` means no expiry |
+| `refreshTokenIdleTTL`   | unset             | Sliding expiry: each successful refresh moves the grant's expiry this far out       |
+| `clientRegistrationTTL` | 7,776,000 seconds | 90 days for DCR clients, renewed while in use; explicit `undefined` means no expiry |
+
+A refresh rotates the token. The newly issued token and the immediately previous token can both recover a refresh whose response was lost. Once the new token is used, the previous token is invalidated and another token is issued.
+
+Per-token `accessTokenTTL` and `refreshTokenTTL` overrides are available through `tokenExchangeCallback`.
+
+### Sliding expiry
+
+By default a grant's lifetime is fixed at the code exchange: it expires `refreshTokenTTL` seconds later no matter how often it is refreshed, which is the right policy when users must re-authenticate on a schedule. A Worker that proxies an upstream OAuth service usually wants the opposite: the grant should live as long as the upstream credentials it holds, and no longer.
+
+`refreshTokenIdleTTL` makes the lifetime slide. Every successful refresh moves the grant's expiry, and the KV expiration of its record, to that many seconds after the refresh. `refreshTokenTTL` still sets a new grant's lifetime, so "30 days to start, then at least weekly" is `refreshTokenTTL: 30 * 86400` with `refreshTokenIdleTTL: 7 * 86400`. A grant that never expired keeps that status until its first refresh, after which it too idles out.
+
+Returning `refreshTokenIdleTTL` from `tokenExchangeCallback` sets the lifetime for that one refresh and overrides the option, as in the example above. It sets rather than extends, so returning the upstream's remaining lifetime makes the grant track it exactly; return nothing when the upstream did not rotate and the option, or the fixed lifetime, applies.
+
+The slide is committed by the same grant write that rotates the refresh token. A callback that throws fails the refresh before that write, so a failed upstream refresh never renews the downstream grant. A grant that has already expired, including one that expires while a slow callback runs, is rejected with `invalid_grant` and is not revived. If the access-token write after the grant write fails, the grant is already rotated and extended, and the client's previous refresh token is still valid to retry with; that retry slides the expiry again.
+
+There is no built-in absolute maximum. A grant with `refreshTokenTTL: undefined` already lives indefinitely, and the callback is the place for lifetime policy: record the authorization time in `props` when the grant is created, and return a shrinking `refreshTokenIdleTTL`, or throw, once the grant is older than you allow.
+
+## KV cleanup
+
+KV TTLs remove expiring records automatically. `purgeExpiredData()` provides a defense-in-depth sweep for orphaned or expired grants and tokens:
+
+```ts
+const provider = new OAuthProvider({
+  // Options...
+});
+
+export default {
+  fetch(request, env, ctx) {
+    return provider.fetch(request, env, ctx);
+  },
+  async scheduled(_event, env) {
+    const result = await provider.purgeExpiredData(env, { batchSize: 100 });
+    console.log(result);
+  },
+};
+```
+
+The default batch size is 50. `result.done` reports whether both key spaces were scanned completely during that invocation.
+
+Deleting a client through `OAuthHelpers.deleteClient()` also revokes its grants and associated tokens across users.
+
+## Multiple protected handlers
+
+Use `apiHandlers` when different route prefixes need different handlers:
+
+```ts
+new OAuthProvider({
+  apiHandlers: {
+    '/api/users/': UsersApiHandler,
+    '/api/documents/': DocumentsApiHandler,
+    'https://api.example.com/': ExternalApiHandler,
+  },
+  // Other options...
+});
+```
+
+Use either `apiHandlers` or `apiRoute` plus `apiHandler`, not both. Routes can be paths or full URLs.
+
+## Helper access outside fetch
+
+`getOAuthApi(options, env)` returns `OAuthHelpers` for RPC methods and other Worker entrypoints that do not receive the injected `env.OAUTH_PROVIDER` value.
+
+## External token resolution
+
+`resolveExternalToken` accepts a bearer credential that was not issued or stored by this provider. It runs only after the internal token lookup fails. The credential can be an external OAuth access token, opaque API key, or personal access token (PAT).
+
+### MCP compatibility warning
+
+This is an advanced compatibility feature, not the normal MCP authorization flow. The MCP 2026-07-28 specification says:
+
+- MCP clients must not send tokens other than ones issued by the MCP server's authorization server.
+- MCP servers must accept only tokens intended for their own resource.
+- If an MCP server calls an upstream API, it must use a separate upstream token and must not forward the token received from the MCP client.
+
+Accepting an API key minted by an upstream API directly at the MCP endpoint therefore falls outside the MCP authorization profile. Setting `audience` in the callback applies the provider's local resource policy, but it does not change who issued the credential or make an upstream API key MCP-compliant.
+
+Some deployments intentionally use this compatibility pattern so users can present API keys minted by an existing upstream API. `resolveExternalToken` supports that choice, including validation through a trusted upstream endpoint and passing derived identity or permissions to the protected handler. If the handler forwards the same key to access upstream application data, that is token passthrough under the MCP security guidance and must not be described as MCP-conformant.
+
+The preferred MCP design is to issue a local, audience-bound access token for the MCP server and keep any separate upstream credential in encrypted `props`. When compatibility requires direct upstream keys, restrict validation and use to fixed upstream hosts, request the narrowest permissions possible, never log the key, do not include it in errors or metadata, and make the non-conformant trust model explicit to operators.
+
+### Validating an upstream API key
+
+```ts
+import { ExternalTokenError, OAuthProvider } from '@cloudflare/workers-oauth-provider';
+
+const MCP_RESOURCE = 'https://mcp.example.com/mcp';
+
+new OAuthProvider({
+  // Other options...
+  resourceMetadata: { resource: MCP_RESOURCE },
+
+  resolveExternalToken: async ({ token, request, env }) => {
+    const result = await validateUpstreamApiKey(token, request, env);
+
+    if (result.kind === 'invalid') return null;
+    if (result.kind === 'insufficient_scope') {
+      throw new ExternalTokenError('insufficient_scope', {
+        description: 'The API key needs account:read permission',
+        statusCode: 403,
+        requiredScopes: ['account:read'],
+      });
+    }
+    if (result.kind === 'rate_limited') {
+      throw new ExternalTokenError('temporarily_unavailable', {
+        description: 'API key validation is temporarily rate limited',
+        statusCode: 429,
+        headers: { 'Retry-After': result.retryAfter },
+      });
+    }
+
+    return {
+      props: {
+        upstreamSubject: result.subject,
+        permissions: result.permissions,
+      },
+
+      // An opaque key has no MCP audience claim. This is an explicit local
+      // policy binding applied only after successful validation.
+      audience: MCP_RESOURCE,
+    };
+  },
+});
+```
+
+The callback can:
+
+- Return `{ props, audience }` to authenticate. The audience is required, must be a single string, and must identify the configured canonical `resourceMetadata.resource`; scheme and host comparisons are ASCII case-insensitive and an empty path equals `/`, while port, path, query, and trailing slash are strict. An array is rejected.
+- Return `null` for a generic `401 invalid_token` response.
+- Throw the exported `ExternalTokenError` for an intentional structured response.
+
+`audience` means the local protected resource where the credential is accepted. It does not mean the issuer, user, upstream API, or permissions. For an opaque key, the callback supplies this as a local policy decision after validation. Do not use an upstream API URL as the audience for requests to the Worker.
+
+Unexpected errors, plain objects, `OAuthError`, and app-local lookalike classes are re-thrown so validator bugs remain visible as 500 responses. Existing callback behavior is unchanged unless the callback deliberately throws this package's `ExternalTokenError`.
+
+References:
+
+- [MCP access token handling](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#token-handling)
+- [MCP access token privilege restriction](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations#access-token-privilege-restriction)

package/docs/consent-page.md

@@ -0,0 +1,138 @@
+# Building a consent page
+
+Your `authorizeEndpoint` is your page: the library validates the request, and you sign the user in and ask whether this client may act for them. The consent helpers (`beginConsent()`, `approveConsent()`, `denyConsent()`, `isConsentRemembered()`) make that page safe to build. A server that signs users in through another provider also needs [upstream-sign-in.md](upstream-sign-in.md).
+
+## What the page must show
+
+From the MCP authorization spec and security best practices:
+
+- **The client's name**, and **the scopes** being granted.
+- **The redirect URI's hostname** (MUST): where the tokens will go.
+- **A warning when that hostname is `localhost`** (SHOULD). A CIMD client's name comes from its metadata document, but anyone can present that document and listen on a local port, so the name alone doesn't prove which app is asking.
+- **A CIMD client's domain**, prominently. Its `client_id` is a URL on a domain the client controls; a DCR client's name is self-asserted.
+- **No framing**, and a form that can't be forged: `beginConsent()` returns the headers and the browser-bound handle that do this.
+
+## Escape everything that came from the client
+
+`clientName`, `clientUri`, `logoUri` and the scope strings come from dynamic registration or a CIMD document, so an attacker chooses them. Rendered without escaping, they're script running on your authorization origin, next to your users' sessions.
+
+## A minimal page
+
+```ts
+import type { AuthRequest, ClientInfo } from '@cloudflare/workers-oauth-provider';
+
+const escape = (value: string) => value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+
+function consentPage(client: ClientInfo, request: AuthRequest, handle: string): string {
+  const name = escape(client.clientName ?? client.clientId);
+  const redirectHost = new URL(request.redirectUri).hostname;
+  const local = /^(localhost|127(\.\d{1,3}){3}|\[::1\])$/.test(redirectHost);
+  const origin = client.clientId.startsWith('https://')
+    ? `Published by <strong>${escape(new URL(client.clientId).hostname)}</strong>.`
+    : 'This app registered itself; its name is not verified.';
+  const scopes = request.scope
+    .map(
+      (scope) => `<label><input type="checkbox" name="scope" value="${escape(scope)}" checked> ${escape(scope)}</label>`
+    )
+    .join('<br>');
+  return `<!doctype html>
+<meta charset="utf-8">
+<title>Authorize ${name}</title>
+<h1>Allow ${name} to access your account?</h1>
+<p>${origin} Access will be sent to <strong>${escape(redirectHost)}</strong>.</p>
+${local ? '<p><strong>This sends access to an app on your computer.</strong> Continue only if you just started signing in from it.</p>' : ''}
+<form method="post">
+  <input type="hidden" name="handle" value="${escape(handle)}">
+  ${scopes}
+  <p><button name="decision" value="approve">Allow</button> <button name="decision" value="deny">Deny</button></p>
+</form>`;
+}
+```
+
+## Showing it, approving, declining
+
+```ts
+const oauth = authorizationServer.getOAuthApi(env); // or env.OAUTH_PROVIDER with OAuthProvider
+
+// GET /authorize (after signing the user in with your own session)
+const request = await oauth.parseAuthRequest(req);
+const client = await oauth.lookupClient(request.clientId);
+const consent = await oauth.beginConsent(request);
+consent.headers.set('Content-Type', 'text/html; charset=utf-8');
+return new Response(consentPage(client!, request, consent.handle), { headers: consent.headers });
+
+// POST /authorize
+const form = await req.formData();
+const handle = String(form.get('handle'));
+if (form.get('decision') !== 'approve') {
+  const denied = await oauth.denyConsent(req, handle); // redirect to the client: access_denied, state, iss
+  return new Response(null, { status: 302, headers: denied.headers });
+}
+const approved = await oauth.approveConsent(req, handle, { scope: form.getAll('scope').map(String) });
+const { redirectTo } = await oauth.completeAuthorization({
+  request: approved.request, // from storage, not from the form
+  userId: session.userId,
+  metadata: {},
+  scope: approved.request.scope,
+  props: { userId: session.userId },
+});
+approved.headers.set('Location', redirectTo);
+return new Response(null, { status: 302, headers: approved.headers });
+```
+
+The authorization request is kept server-side between the two requests; the form carries only the handle, which works once, for ten minutes, in the browser that opened the page. `scope` is what the user ticked: fewer or more than the client requested, each in `scopesSupported`.
+
+## Errors: redirect or render?
+
+A redirect back to the client is only safe once the client and its exact redirect URI are validated. Everything else is shown on your page.
+
+| Where it fails                                                                     | What to do                                                                                                                         |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `parseAuthRequest()` throws `AuthorizationError` **with** `redirectUri`            | Redirect to it with `error`, `error_description`, `state` and `iss` from the error (see the quick start)                           |
+| `parseAuthRequest()` throws `AuthorizationError` **without** `redirectUri`         | Render locally. Never redirect: the client or redirect URI isn't trusted                                                           |
+| `parseAuthRequest()` / `lookupClient()` throw `CimdFetchError`                     | Render locally: the client's metadata document couldn't be fetched (`error.reason`, `error.detail` for your logs)                  |
+| `approveConsent()`, `denyConsent()`, `finishUpstream()` throw `AuthorizationError` | Render locally: the page expired, was used, or was opened in another browser, or the scopes aren't supported. Offer to start again |
+| Any helper throws something else (`TypeError`, a KV failure)                       | A bug or an outage, not the user's doing: let it surface as a 500                                                                  |
+| The user clicks Deny                                                               | `denyConsent()`, then send its redirect                                                                                            |
+| A third-party provider returns `error=` to your callback                           | `finishUpstream()`, then redirect to the client with `access_denied` ([upstream-sign-in.md](upstream-sign-in.md))                  |
+| Token endpoint errors                                                              | The library answers them; observe them with `onError`                                                                              |
+
+```ts
+try {
+  // …the handlers above
+} catch (error) {
+  if (error instanceof AuthorizationError && error.redirectUri) {
+    const redirect = new URL(error.redirectUri);
+    redirect.searchParams.set('error', error.code);
+    redirect.searchParams.set('error_description', error.description);
+    if (error.state) redirect.searchParams.set('state', error.state);
+    if (error.issuer) redirect.searchParams.set('iss', error.issuer);
+    return Response.redirect(redirect.href, 302);
+  }
+  if (error instanceof AuthorizationError || error instanceof CimdFetchError) {
+    const message = error instanceof AuthorizationError ? error.description : 'This app could not be verified.';
+    return new Response(escape(message), { status: 400, headers: { 'Content-Type': 'text/plain; charset=utf-8' } });
+  }
+  throw error;
+}
+```
+
+## Remembering consent
+
+By default the page appears on every authorization, which also lets users re-authorize with different scopes. To skip it for clients a user already approved, pass `remember` when approving and check before showing the page:
+
+```ts
+const remember = { secret: env.CONSENT_SECRET, subject: session.userId }; // secret: 32+ chars, from a Worker secret
+
+if (await oauth.isConsentRemembered(req, request, remember)) {
+  // skip the page: complete the authorization (or start the third-party sign-in) directly
+}
+// …when approving:
+await oauth.approveConsent(req, handle, { scope, remember }); // maxAgeSeconds defaults to 30 days
+```
+
+Approvals live in a signed `__Host-` cookie, bound to the client ID, its redirect URI and the resource, and they cover only the scopes that were approved: asking for more brings the page back. Pass `subject` (the signed-in user) whenever you know it, so another account on the same browser is asked again. Without it an approval belongs to the browser, which is what a proxy server gets, since it learns the user from the third party only after consent.
+
+## Cookie names
+
+Each consent page and each third-party redirect gets its own short-lived cookie, `__Host-oauth-consent-…` or `__Host-oauth-upstream-…` (so two tabs can authorize at once), and remembered approvals live in `__Host-oauth-approvals`. Change the prefix with the `cookiePrefix` option if those collide with yours; it must start with `__Host-`.

package/docs/migration-1.0.md

@@ -0,0 +1,97 @@
+# Migrating from 0.x to 1.0
+
+1.0 binds every grant and access token to one canonical resource (RFC 8707 / RFC 9728) and adds role classes for multi-Worker deployments. Stored 0.x data keeps working — there is no KV migration. For most deployments the code diff is one field.
+
+## Am I affected?
+
+- **Single Worker on `OAuthProvider`** (the common shape): add `resourceMetadata: { resource }` if you don't have it. Usually that is the whole migration.
+- **You set `resourceMatchOriginOnly`**: remove it; construction now rejects it.
+- **You use `resolveExternalToken`**: return `audience` (now required).
+- **You registered clients over DCR with an explicit narrow `grant_types`**: registered grant types are now enforced at the token endpoint.
+- **Your clients send a different `redirect_uri` at code exchange than at authorization**: OAuth 2.1 §4.1.3 is now enforced.
+- **Nothing else**: existing grants, refresh tokens, access tokens and authorization codes keep working under the legacy rules below.
+
+## The canonical resource is required
+
+```diff
+ export default new OAuthProvider<Env>({
+   apiRoute: ['/mcp'],
+   apiHandler,
+   defaultHandler,
+   authorizeEndpoint: '/authorize',
+   tokenEndpoint: '/oauth/token',
++  resourceMetadata: { resource: 'https://mcp.example.com/mcp' },
+ });
+```
+
+`resource` is the URL your MCP clients connect to: an absolute HTTPS URI with lowercase scheme and host, no fragment, userinfo, default port, or dot segments. A bare origin (`https://mcp.example.com`) is allowed and covers every path. `http` is accepted only on loopback hosts, so `wrangler dev` works at `http://localhost:8787`.
+
+Construction validates the whole configuration against it and throws with a named rule when something is off:
+
+- Every `apiRoute` / `apiHandlers` key must be the resource's path or a path-boundary descendant (`/mcp` covers `/mcp` and `/mcp/tools`, not `/mcp-other`); absolute routes must be on the resource's origin.
+- The resource must not sit inside `/.well-known/oauth-protected-resource`.
+
+In 0.x the metadata document was derived per request when `resourceMetadata` was omitted; in 1.0 the configured resource is the identity every token is bound to, so it cannot be implicit.
+
+## Removed: `resourceMatchOriginOnly`
+
+A configuration that still sets it fails at construction. Audiences are now compared exactly against the canonical resource, with two tolerances: ASCII case in scheme and host is folded, and an empty path equals `/` (RFC 3986 §6.2.3). Port, path, query, and trailing slash stay strict.
+
+## `resolveExternalToken` names its audience
+
+`ResolveExternalTokenResult.audience` is required and a single string, and must be the configured canonical resource — a token accepted for another audience is a 401:
+
+```diff
+ resolveExternalToken: async ({ token }) => {
+   const session = await upstream.introspect(token);
+   if (!session) return null;
+-  return { props: { userId: session.sub } };
++  return { props: { userId: session.sub }, audience: 'https://mcp.example.com/mcp' };
+ },
+```
+
+## Registered grant types are enforced
+
+A token request for a grant type the client did not register fails with `unauthorized_client`. `refresh_token` is implied by `authorization_code`; token exchange must be registered explicitly (and enabled with `allowTokenExchangeGrant`). This is a data-side change: clients registered under 0.x with a deliberately narrow `grant_types` array may now be refused where 0.x ignored the field.
+
+## Token exchange
+
+- A subject token is exchanged by the client its grant was issued to. The cross-client case requires `tokenExchangeCallback` to return `allowCrossClientExchange: true`; the callback receives `subjectClientId` to decide.
+- Subject-token failures return `invalid_request`.
+- The exchange cannot retarget the resource: the subject token's audience and any explicit `resource` parameter must resolve to the same registered value.
+
+## `redirect_uri` is bound to the authorization request
+
+OAuth 2.1 §4.1.3: the `redirect_uri` presented at code exchange must equal the one used in the authorization request (0.x accepted any registered URI). Without PKCE, `redirect_uri` is required at exchange.
+
+## One grant per user, client, and resource
+
+Completing a new authorization replaces the user and client's earlier grant _for the same resource_ only. In 0.x replacement was per user and client, so a central server issuing tokens for several resources no longer drops one resource's grant when the user authorizes another.
+
+## Existing stored data — nothing to do
+
+- An access token stored without an audience keeps working until it expires. It is treated as bound to the migration resource: the sole configured resource, or `legacyGrantResource` on a multi-resource server.
+- Refresh binds the grant to that resource and returns a bound replacement token.
+- A stored 0.x audience array resolves to the registered resource it contains.
+- A grant bound only to unregistered values fails refresh with `invalid_grant`; conformant clients (Claude, the MCP SDKs) answer that by starting a fresh authorization.
+- A multi-resource `OAuthAuthorizationServer` without `legacyGrantResource` has no safe destination for unbound records and rejects them; set it for the migration window and keep it fixed.
+- Authorization codes issued by 0.x redeem under the same rules.
+
+## Type-level changes
+
+| 0.x                                                 | 1.0                 |
+| --------------------------------------------------- | ------------------- |
+| `ExchangeTokenOptions.aud?: string \| string[]`     | `aud?: string`      |
+| `AuthRequest.resource?: string \| string[]`         | `resource?: string` |
+| `TokenExchangeCallbackOptions.resource` (array-ish) | single `string`     |
+| `ResolveExternalTokenResult.audience?` (optional)   | required `string`   |
+
+## New in 1.0, adopt when useful
+
+None of these require changes to a migrated 0.x deployment:
+
+- **Role classes** — `OAuthAuthorizationServer` (one AS, many resources) and `OAuthResourceServer` (host a resource in the AS Worker or its own, validating over a Service Binding). See [resource-servers.md](resource-servers.md).
+- **`ctx.auth` and `insufficientScope()`** — handlers see the verified token facts beside `ctx.props` and answer scope shortfalls with the MCP `403` challenge. See the README's scopes section.
+- **`onError.internal`** — every library error carries a stable `{ category, reason }` for logs and alerting; the wire stays generic.
+- **`refreshTokenIdleTTL`** — opt-in sliding refresh-token expiry.
+- Dynamically registered clients in active use renew automatically; grant listing and revocation are KV-bounded.