@cloudflare/workers-oauth-provider 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 `@cloudflare/workers-oauth-provider` adds OAuth 2.1 authorization to HTTP APIs and remote MCP servers running on Cloudflare Workers.
 
+> **1.0 is out, with a new split API.** The authorization server (`OAuthAuthorizationServer`) and resource server (`OAuthResourceServer`) are now separate classes that can run in one Worker or several; the [quick start](#quick-start) shows both. The single-Worker `OAuthProvider` is still supported. Upgrading from 0.x? Read the [migration guide](docs/migration-1.0.md), or point your coding agent at the skill in [`skills/migrate-to-1.0/`](skills/migrate-to-1.0/SKILL.md), which also ships in the npm package.
+
 ## Install
 
 ```sh
@@ -33,108 +35,25 @@ See [Client registration](#client-registration) for the matching provider option
 
 ## Quick start
 
-The provider accepts either plain `ExportedHandler` objects or classes extending `WorkerEntrypoint`. This example uses both.
+An MCP deployment has two roles. The **authorization server** signs users in and issues tokens. The **resource server** is your MCP endpoint: it accepts those tokens and checks them with the authorization server over a [Service Binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/). Each is one class.
+
+### Authorization server Worker
 
 ```ts
-import {
-  AuthorizationError,
-  OAuthProvider,
-  type AuthRequest,
-  type OAuthHelpers,
-} from '@cloudflare/workers-oauth-provider';
+import { AuthorizationError, OAuthAuthorizationServer, type AuthRequest } from '@cloudflare/workers-oauth-provider';
 import { WorkerEntrypoint } from 'cloudflare:workers';
 
-interface AuthProps {
-  userId: string;
-  displayName: string;
-}
-
 interface Env {
   OAUTH_KV: KVNamespace;
-  OAUTH_PROVIDER: OAuthHelpers;
 }
 
-class McpApiHandler extends WorkerEntrypoint<Env, AuthProps> {
-  fetch(request: Request): Response {
-    return Response.json({
-      authenticated: true,
-      userId: this.ctx.props.userId,
-      displayName: this.ctx.props.displayName,
-    });
-  }
-}
-
-const defaultHandler: ExportedHandler<Env> = {
-  async fetch(request, env) {
-    const url = new URL(request.url);
-
-    if (url.pathname !== '/authorize') {
-      return new Response('Not found', { status: 404 });
-    }
-
-    // This parses the OAuth parameters and validates the client, redirect URI,
-    // response type, resource indicators, and configured PKCE restrictions.
-    let oauthRequest: AuthRequest;
-    try {
-      oauthRequest = await env.OAUTH_PROVIDER.parseAuthRequest(request);
-    } catch (error) {
-      if (!(error instanceof AuthorizationError)) throw error;
-      if (!error.redirectUri) {
-        // Unknown clients and invalid redirects must be rendered locally.
-        return new Response(error.description, { status: 400 });
-      }
-      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, 302);
-    }
-
-    const client = await env.OAUTH_PROVIDER.lookupClient(oauthRequest.clientId);
-
-    if (!client) {
-      return new Response('Unknown OAuth client', { status: 400 });
-    }
-
-    // Authenticate the user and obtain consent here. Do not automatically
-    // approve a request in production. This example assumes those steps have
-    // produced the following user and scope values.
-    const user = { id: 'user-123', displayName: 'Ada' };
-    const grantedScopes = oauthRequest.scope.filter((scope) => scope === 'mcp:read');
-
-    const { redirectTo } = await env.OAUTH_PROVIDER.completeAuthorization({
-      request: oauthRequest,
-      userId: user.id,
-      metadata: { clientName: client.clientName },
-      scope: grantedScopes,
-      props: {
-        userId: user.id,
-        displayName: user.displayName,
-      },
-    });
-
-    return Response.redirect(redirectTo, 302);
-  },
-};
-
-export default new OAuthProvider<Env>({
-  apiRoute: '/mcp',
-  apiHandler: McpApiHandler,
-  defaultHandler,
-
+const authorizationServer = new OAuthAuthorizationServer<Env>({
+  issuer: 'https://auth.example.com',
+  resources: ['https://mcp.example.com/mcp'],
   authorizeEndpoint: '/authorize',
   tokenEndpoint: '/oauth/token',
-
   scopesSupported: ['mcp:read'],
 
-  resourceMetadata: {
-    resource: 'https://mcp.example.com/mcp',
-    authorization_servers: ['https://mcp.example.com'],
-    scopes_supported: ['mcp:read'],
-    resource_name: 'Example MCP server',
-  },
-
   // Preferred for clients with no pre-existing relationship.
   // Also requires global_fetch_strictly_public in wrangler.jsonc.
   clientIdMetadataDocumentEnabled: true,
@@ -142,65 +61,128 @@ export default new OAuthProvider<Env>({
   // Optional compatibility fallback. MCP 2026 deprecates DCR for new clients.
   clientRegistrationEndpoint: '/oauth/register',
 });
-```
 
-## Protecting routes
-
-`apiRoute` and `apiHandler` protect one or more route prefixes with a single handler. Use `apiHandlers` when different prefixes need different handlers.
+async function authorize(request: Request, env: Env): Promise<Response> {
+  const oauth = authorizationServer.getOAuthApi(env);
+
+  // Parses the OAuth parameters and validates the client, redirect URI,
+  // response type, resource indicator, and PKCE.
+  let oauthRequest: AuthRequest;
+  try {
+    oauthRequest = await oauth.parseAuthRequest(request);
+  } catch (error) {
+    if (!(error instanceof AuthorizationError)) throw error;
+    if (!error.redirectUri) {
+      // Unknown clients and invalid redirects must be rendered locally.
+      return new Response(error.description, { status: 400 });
+    }
+    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);
+  }
 
-Before calling a protected handler, the provider reads the bearer token, rejects missing, invalid, or expired credentials, checks its audience, and exposes the authenticated application data through `ctx.props` and what it verified about the token through `ctx.auth` (`scope`, `userId`, `clientId`, `audience`, `expiresAt`). The handler does not need to parse or validate the token, but it still enforces application permissions such as scope, ownership, and tenancy; `insufficientScope(ctx.auth, scopes)` builds the MCP `403` challenge when a token lacks what an operation needs.
+  const client = await oauth.lookupClient(oauthRequest.clientId);
+  if (!client) return new Response('Unknown OAuth client', { status: 400 });
+
+  // Authenticate the user and obtain consent here. Never approve automatically
+  // in production; this example assumes those steps produced these values.
+  const user = { id: 'user-123', displayName: 'Ada' };
+  const { redirectTo } = await oauth.completeAuthorization({
+    request: oauthRequest,
+    userId: user.id,
+    metadata: { clientName: client.clientName },
+    scope: oauthRequest.scope.filter((scope) => scope === 'mcp:read'),
+    props: { userId: user.id, displayName: user.displayName },
+  });
+  return Response.redirect(redirectTo, 302);
+}
 
-Requests outside the protected route prefixes go to `defaultHandler`. In the example above, that handler owns `/authorize`.
+export default class AuthServer extends WorkerEntrypoint<Env> {
+  // Your /authorize page; everything else (discovery, token, revocation, registration) is the library's.
+  fetch(request: Request) {
+    if (new URL(request.url).pathname === '/authorize') return authorize(request, this.env);
+    return authorizationServer.fetch(request, this.env, this.ctx);
+  }
 
-## One authorization server with multiple MCP resources
+  // Called by resource Workers over their Service Binding.
+  validateToken(resource: string, token: string) {
+    return authorizationServer.validateToken(resource, token, this.env);
+  }
+}
+```
 
-`OAuthAuthorizationServer` is the authorization-server role on its own: discovery, token, revocation and registration endpoints from `fetch()`, the interactive flow through `getOAuthApi()`, and `validateToken(resource, token, env)` for any resource in its fixed `resources` registry. Each resource is hosted by `new OAuthResourceServer()`, whose `validateToken` option points back at the authorization server — in this Worker or another. Same host, same `ctx.props`, wherever the resource runs.
+### Resource server Worker
 
-**Same Worker.** Route the authorization server's origin to `authorizationServer.fetch()`, your `/authorize` page to `getOAuthApi()`, and each resource to its host. The validator is a direct call:
+```jsonc
+// wrangler.jsonc
+{
+  "services": [{ "binding": "AUTH_SERVER", "service": "auth-server" }],
+}
+```
 
 ```ts
-const authorizationServer = new OAuthAuthorizationServer<Env>({
-  issuer: 'https://auth.example.com',
-  resources: ['https://calendar.example.com/mcp'],
-  authorizeEndpoint: '/authorize',
-  tokenEndpoint: '/oauth/token',
-});
+import { OAuthResourceServer, type AuthorizationServerBinding } from '@cloudflare/workers-oauth-provider';
 
-const calendar = new OAuthResourceServer<Env, AuthProps>({
+interface AuthProps {
+  userId: string;
+  displayName: string;
+}
+
+interface Env {
+  AUTH_SERVER: AuthorizationServerBinding<AuthProps>;
+}
+
+export default new OAuthResourceServer<Env, AuthProps>({
   resourceMetadata: {
-    resource: 'https://calendar.example.com/mcp',
+    resource: 'https://mcp.example.com/mcp',
     authorization_servers: ['https://auth.example.com'],
+    scopes_supported: ['mcp:read'],
+    resource_name: 'Example MCP server',
+  },
+  validateToken: (env) => env.AUTH_SERVER.validateToken,
+  handler: {
+    fetch(request, env, ctx) {
+      // ctx.props: what completeAuthorization() stored. ctx.auth: the verified token (scope, userId, clientId, …).
+      return Response.json({ userId: ctx.props.userId, scope: ctx.auth.scope });
+    },
   },
-  validateToken: (env) => (resource, token) => authorizationServer.validateToken(resource, token, env),
-  handler: { fetch: (_request, _env, ctx) => Response.json({ userId: ctx.props.userId }) },
 });
 ```
 
-**Separate Workers.** The authorization Worker exposes `validateToken` from a `WorkerEntrypoint`; the resource Worker holds a Service Binding to it and hands the host that method. Nothing else to configure, and the validator is a binding, not a URL — it is not reachable from the public internet:
+The resource server publishes its RFC 9728 metadata, answers unauthenticated requests with a Bearer challenge that points at it, validates every token for its own resource only, and passes the handler `ctx.props` and `ctx.auth`. The handler still enforces permissions such as ownership and tenancy; `insufficientScope(ctx.auth, scopes)` builds the MCP `403` when a token lacks a scope an operation needs. The binding is not a URL, so the validator is not reachable from the public internet.
 
-```ts
-// auth Worker
-export default class AuthServer extends WorkerEntrypoint<Env> {
-  fetch(request: Request) {
-    return authorizationServer.fetch(request, this.env, this.ctx);
-  }
-  validateToken(resource: string, token: string) {
-    return authorizationServer.validateToken(resource, token, this.env);
-  }
-}
+### More resources, or one Worker
 
-// calendar Worker, with `"services": [{ "binding": "AUTH_SERVER", "service": "auth" }]` in wrangler.jsonc
-export default new OAuthResourceServer<Env, AuthProps>({
+- **Another MCP resource**: add it to `resources` and deploy another `OAuthResourceServer` with the same binding. A token issued for one resource is refused by every other.
+- **Both roles in one Worker**: construct the `OAuthResourceServer` next to the authorization server with a local validator, `validateToken: (env) => (resource, token) => authorizationServer.validateToken(resource, token, env)`, and route to it from your `fetch`.
+
+[docs/resource-servers.md](docs/resource-servers.md) covers both, including a three-domain Hono example, and how to accept another issuer's tokens at your own risk.
+
+## Single Worker: `OAuthProvider`
+
+When one Worker is both the authorization server and its only resource, which was the 0.x shape, `OAuthProvider` combines the two roles. Requests to `apiRoute` are protected and reach `apiHandler` with `ctx.props` and `ctx.auth`; everything else that isn't an OAuth endpoint goes to `defaultHandler`, which owns `/authorize` and reaches the same helpers as `env.OAUTH_PROVIDER`:
+
+```ts
+export default new OAuthProvider<Env>({
+  apiRoute: '/mcp', // or apiHandlers: { '/mcp': …, '/mcp/admin': … }
+  apiHandler: McpApiHandler, // an object with fetch, or a WorkerEntrypoint class
+  defaultHandler, // /authorize, using env.OAUTH_PROVIDER.parseAuthRequest() / completeAuthorization()
+  authorizeEndpoint: '/authorize',
+  tokenEndpoint: '/oauth/token',
+  scopesSupported: ['mcp:read'],
   resourceMetadata: {
-    resource: 'https://calendar.example.com/mcp',
-    authorization_servers: ['https://auth.example.com'],
+    resource: 'https://mcp.example.com/mcp',
+    authorization_servers: ['https://mcp.example.com'],
+    scopes_supported: ['mcp:read'],
   },
-  validateToken: (env) => env.AUTH_SERVER.validateToken,
-  handler,
+  clientIdMetadataDocumentEnabled: true,
 });
 ```
 
-Either way the resource server publishes its own RFC 9728 metadata, issues Bearer challenges that point at it, checks the returned audience against its canonical resource, and answers `503` when validation infrastructure fails. Tokens are opaque throughout; a validator returns the decrypted `props` the authorization flow stored. See [docs/resource-servers.md](docs/resource-servers.md) for the three-domain Hono example, the `AuthorizationServerBinding` type for your `Env`, and how to validate tokens from another issuer at your own risk.
+Every protected route must be the canonical `resource` path or a descendant of it; construction rejects anything else.
 
 ## How MCP authorization discovery works
 
@@ -222,10 +204,10 @@ For an MCP endpoint at `https://mcp.example.com/mcp`:
    ```
 
 4. That document identifies one or more authorization server issuers through `authorization_servers`.
-5. The client fetches RFC 8414 authorization server metadata from the selected issuer. In the single-origin quick start that is:
+5. The client fetches RFC 8414 authorization server metadata from the selected issuer. In the quick start that is:
 
    ```text
-   https://mcp.example.com/.well-known/oauth-authorization-server
+   https://auth.example.com/.well-known/oauth-authorization-server
    ```
 
 6. The metadata tells the client where to authorize, exchange tokens, and register if registration is enabled.
@@ -289,6 +271,8 @@ A typical flow has three steps:
 2. Authenticate the user, show consent, and decide which scopes to grant.
 3. Call `completeAuthorization()` and redirect to its returned `redirectTo` URL.
 
+[docs/consent-page.md](docs/consent-page.md) shows a safe consent page (what it must display, escaping client metadata, Allow and Deny) and which errors to redirect back to the client and which to render.
+
 `parseAuthRequest()` throws an exported `AuthorizationError` for expected request validation failures. Its optional `redirectUri` is present only after the client and exact registered redirect URI have been validated. Without it, render the error locally and never redirect. With it, the application can safely construct an OAuth error redirect using the error's `code`, `description`, original `state`, and RFC 9207 `issuer`, as shown in the quick start.
 
 `completeAuthorization()` repeats response-type validation before writing a grant or revoking existing grants. Validation errors from reconstructed requests are also typed as `AuthorizationError`, but applications should not construct redirects from untrusted reconstructed values; the redirect context is attached only by `parseAuthRequest()`.
@@ -422,23 +406,6 @@ Token exchange cannot change the resource. Both the subject-token audience and a
 
 Path-aware API validation uses path-boundary prefix matching. A canonical audience for `https://example.com/mcp` covers `/mcp` and `/mcp/tools`, but not `/mcp-other`. A canonical trailing slash remains significant.
 
-### Upgrading to 1.0
-
-The step-by-step guide, including an "Am I affected" checklist and an agent skill (`skills/migrate-to-1.0/`), is [docs/migration-1.0.md](docs/migration-1.0.md). The compatibility rules it relies on:
-
-The existing combined `OAuthProvider` configuration has one `resourceMetadata.resource`. That sole resource automatically acts as both the omitted-authorization default and the migration destination for grants created before resource binding, so existing single-resource clients can continue without adding a `resource` parameter.
-
-For a multi-resource `OAuthAuthorizationServer`, `defaultResource` and `legacyGrantResource` solve different compatibility problems:
-
-- `defaultResource` selects the resource for a new authorization request that omits `resource`.
-- `legacyGrantResource` is the server-controlled migration destination for an old stored grant or access token that has no resource. A client-supplied token-request parameter cannot choose or change this destination. It is deployment policy rather than an issuance-time claim, so changing it re-targets every surviving unbound record; keep it fixed for the migration window.
-
-Both values must name a declared resource and are checked at construction. If a multi-resource server omits `legacyGrantResource`, an old unbound grant cannot be migrated safely. A stored grant already bound to a registered resource keeps that resource, and a stored 0.x array that contains the registered resource resolves to it. A grant bound only to unregistered values fails its refresh with `invalid_grant`, which conformant clients answer by starting a new authorization.
-
-Previously issued access tokens with no audience keep working until they expire. They are treated as bound to the server-selected migration resource (the sole resource, or `legacyGrantResource`), and refresh binds the grant and returns a bound replacement token. A multi-resource server without `legacyGrantResource` has no safe destination, so it rejects such tokens and their refresh grants must be reauthorized. Multiple resources can share the same authorization server, provider implementation, and KV namespace; separate storage is an optional deployment boundary, not a resource-binding requirement.
-
-The 1.0 API removes `resourceMatchOriginOnly`, and a configuration that still sets it fails at construction. Canonical matching with scheme/host case tolerance replaces it.
-
 ## Scopes and step-up authorization
 
 `scopesSupported` is published only in authorization server metadata. Configure each protected resource's `resourceMetadata.scopes_supported` explicitly with the minimal scopes required for its basic functionality and baseline Bearer challenges.
@@ -454,6 +421,7 @@ The package also supports:
 - External API keys and bearer credentials through `resolveExternalToken` as an advanced compatibility feature.
 - Updating encrypted props, token scope, and token lifetimes with `tokenExchangeCallback`.
 - OAuth 2.0 Token Exchange when `allowTokenExchangeGrant` is enabled.
+- Signing users in through another OAuth provider (GitHub, Google, …) with per-client consent and browser-bound `state`. See [docs/upstream-sign-in.md](docs/upstream-sign-in.md).
 - Structured callback errors through the exported `OAuthError` and `ExternalTokenError` classes.
 - Custom error observation or responses through `onError`.
 - Experimental MCP Enterprise-Managed Authorization using ID-JAG assertions.
@@ -512,6 +480,7 @@ The existing `OAuthProvider` combined configuration uses these options:
 | `scopesSupported`                  | Publish authorization server scopes                                         | Omitted                                  |
 | `resourceMetadata.resource`        | Canonical HTTPS resource and token audience                                 | Required                                 |
 | `clientIdMetadataDocumentEnabled`  | Enable CIMD lookup and advertisement                                        | `false`                                  |
+| `cookiePrefix`                     | Prefix for the consent and upstream helpers' cookies (must be `__Host-…`)   | `__Host-oauth-`                          |
 | `allowPlainPKCE`                   | Permit the legacy plain PKCE method                                         | `false`                                  |
 | `allowImplicitFlow`                | Enable implicit token responses                                             | `false`                                  |
 | `disallowPublicClientRegistration` | Reject public clients at DCR                                                | `false`                                  |
@@ -540,6 +509,7 @@ Consult the exported `OAuthProviderOptions`, `OAuthAuthorizationServerOptions`,
 Handlers receive `env.OAUTH_PROVIDER`, which implements `OAuthHelpers`. It can:
 
 - Parse authorization requests and complete authorization.
+- Run a consent page and a third-party sign-in redirect safely (`beginConsent()`, `approveConsent()`, `denyConsent()`, `isConsentRemembered()`, `beginUpstream()`, `finishUpstream()`).
 - Look up, create, list, update, and delete clients.
 - List and revoke grants for a user.
 - Inspect internally issued tokens with `unwrapToken()`.

package/dist/oauth-provider.d.ts

@@ -439,6 +439,50 @@ declare class OAuthResourceServer<Env = Cloudflare.Env, Props = unknown> {
   fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
 }
 //#endregion
+//#region src/oauth-consent.d.ts
+/** Remember an approval so the consent page can be skipped for requests it already covers. */
+interface RememberConsentOptions {
+  /** HMAC key for the approvals cookie: at least 32 characters, from a Worker secret. */
+  secret: string;
+  /** How long an approval is remembered. Defaults to 30 days. */
+  maxAgeSeconds?: number;
+  /**
+   * The signed-in user, when you know them before consent (your own sign-in). The approval is then
+   * bound to them as well, so another account on the same browser is asked again. Without it an
+   * approval belongs to the browser, which suits a proxy server that only learns the user from the
+   * third party after consent.
+   */
+  subject?: string;
+}
+/** A consent page to render: post `handle` back to {@link approveConsent}; send `headers` with the page. */
+interface ConsentTransaction {
+  handle: string;
+  headers: Headers;
+}
+/** The approved authorization request, with the cookies to set on the next response. */
+interface ApprovedConsent {
+  request: AuthRequest;
+  headers: Headers;
+}
+/** Where to send the browser after the user declined, with the cookies to set on that redirect. */
+interface DeniedConsent {
+  request: AuthRequest;
+  /** The client's redirect URI with `error=access_denied`, its `state`, and `iss` (RFC 9207). */
+  redirectTo: string;
+  headers: Headers;
+}
+/** The `state` to send to the third-party provider, with the binding cookie to set on the redirect. */
+interface UpstreamTransaction {
+  state: string;
+  headers: Headers;
+}
+/** The authorization request and data saved by `beginUpstream()`, recovered at the callback. */
+interface ResumedUpstream<Data = unknown> {
+  request: AuthRequest;
+  data: Data;
+  headers: Headers;
+}
+//#endregion
 //#region src/oauth-resource.d.ts
 /** Validate an RFC 3986-safe HTTP(S) resource identifier for RFC 8707. */
 declare function validateResourceUri(uri: string): boolean;
@@ -879,6 +923,12 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * Defaults to false.
    */
   clientIdMetadataDocumentEnabled?: boolean;
+  /**
+   * Prefix for the cookies the consent and upstream helpers set (`<prefix>consent`,
+   * `<prefix>upstream`, `<prefix>approvals`). Must start with `__Host-`, which keeps them
+   * `Secure`, host-only and `Path=/`. Defaults to `__Host-oauth-`.
+   */
+  cookiePrefix?: string;
   /**
    * Metadata for RFC 9728 OAuth 2.0 Protected Resource Metadata.
    * Controls the response served at /.well-known/oauth-protected-resource.
@@ -956,6 +1006,53 @@ interface OAuthHelpers {
   completeAuthorization(options: CompleteAuthorizationOptions): Promise<{
     redirectTo: string;
   }>;
+  /**
+   * Whether an approval remembered by `approveConsent(…, { remember })` covers this request: the
+   * same client, redirect URI and resource, asking for a subset of the approved scopes. Pass the
+   * same `secret`, and the same `subject` if the approval was bound to a user. Don't call it to ask
+   * on every authorization.
+   */
+  isConsentRemembered(request: Request, authRequest: AuthRequest, remember: Pick<RememberConsentOptions, 'secret' | 'subject'>): Promise<boolean>;
+  /**
+   * Start a consent page for a request. Render your page with `handle` in the form and send
+   * `headers` with it: they bind the handle to this browser and forbid framing the page.
+   */
+  beginConsent(authRequest: AuthRequest): Promise<ConsentTransaction>;
+  /**
+   * Accept the consent form. `handle` is the value your form posted; the browser's binding cookie
+   * must match it, and it works once. `scope` is what the user approved: fewer or more than the
+   * client requested, each one in `scopesSupported`. `remember` stores the approval in a signed
+   * cookie for `isConsentRemembered()`. Send the returned `headers` on the next response.
+   * @throws AuthorizationError when the handle is missing, unbound, expired, or already used
+   */
+  approveConsent(request: Request, handle: string, options?: {
+    scope?: string[];
+    remember?: RememberConsentOptions;
+  }): Promise<ApprovedConsent>;
+  /**
+   * Decline the consent form: consumes the handle like `approveConsent()` and returns the redirect
+   * back to the client with `error=access_denied`, its `state` and `iss`. Send `headers` with the
+   * redirect (they include `Location`).
+   * @throws AuthorizationError when the handle is missing, unbound, expired, or already used
+   */
+  denyConsent(request: Request, handle: string, options?: {
+    description?: string;
+  }): Promise<DeniedConsent>;
+  /**
+   * Save an approved request before redirecting to a third-party provider, and get the `state`
+   * to send it. Call only after consent. `data` is returned at the callback, e.g. a PKCE verifier.
+   * Pass `headers` to add the binding cookie to headers you are already sending.
+   */
+  beginUpstream(authRequest: AuthRequest, options?: {
+    data?: unknown;
+    headers?: Headers;
+  }): Promise<UpstreamTransaction>;
+  /**
+   * At the third-party provider's callback, recover the approved request and your `data` from the
+   * `state` parameter. The browser's binding cookie must match, and it works once.
+   * @throws AuthorizationError when `state` is missing, unbound, expired, or already used
+   */
+  finishUpstream<Data = unknown>(request: Request): Promise<ResumedUpstream<Data>>;
   /**
    * Creates a new OAuth client
    * @param clientInfo - Partial client information to create the client with
@@ -1675,6 +1772,7 @@ interface OAuthErrorOptions {
  * async function refreshUpstream(props) {
  *   const res = await fetch(...);
  *   if (res.status === 401) {
+ *     // invalid_grant can never recover: the provider also revokes this grant and its tokens.
  *     throw new OAuthError('invalid_grant', { description: 'upstream refresh token is invalid' });
  *   }
  *   if (res.status === 429) {
@@ -1796,4 +1894,4 @@ declare function getJwtCryptoAlgorithms(alg: string): {
   verifyAlgorithm: Parameters<SubtleCrypto['verify']>[0];
 };
 //#endregion
-export { AuthRequest, AuthorizationError, type AuthorizationErrorCode, type AuthorizationErrorOptions, AuthorizationServerBinding, CimdFetchError, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, ExternalTokenError, ExternalTokenErrorOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthAuthorizationServer, OAuthAuthorizationServerOptions, OAuthError, OAuthErrorInternal, OAuthErrorOptions, OAuthHelpers, OAuthProtectedResourceMetadata, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthResourceAuth, OAuthResourceContext, OAuthResourceHandler, OAuthResourceMetadata, OAuthResourceServer, OAuthResourceServerOptions, OAuthResourceTokenValidation, OAuthResourceTokenValidator, OAuthTokenErrorCode, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, ValidatedAccessToken, base64UrlToBytes, getJwtCryptoAlgorithms, getOAuthApi, insufficientScope, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };
+export { type ApprovedConsent, AuthRequest, AuthorizationError, type AuthorizationErrorCode, type AuthorizationErrorOptions, AuthorizationServerBinding, CimdFetchError, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, CompleteAuthorizationOptions, type ConsentTransaction, type DeniedConsent, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, ExternalTokenError, ExternalTokenErrorOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthAuthorizationServer, OAuthAuthorizationServerOptions, OAuthError, OAuthErrorInternal, OAuthErrorOptions, OAuthHelpers, OAuthProtectedResourceMetadata, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthResourceAuth, OAuthResourceContext, OAuthResourceHandler, OAuthResourceMetadata, OAuthResourceServer, OAuthResourceServerOptions, OAuthResourceTokenValidation, OAuthResourceTokenValidator, OAuthTokenErrorCode, PurgeOptions, PurgeResult, type RememberConsentOptions, ResolveExternalTokenInput, ResolveExternalTokenResult, type ResumedUpstream, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, type UpstreamTransaction, ValidatedAccessToken, base64UrlToBytes, getJwtCryptoAlgorithms, getOAuthApi, insufficientScope, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };

package/dist/oauth-provider.js

@@ -678,7 +678,7 @@ function emaErrorToWire(e) {
 * only through the adapters' public interfaces.
 */
 /** SHA-256 a string and return its hex digest. */
-async function sha256Hex(input) {
+async function sha256Hex$1(input) {
 	const data = new TextEncoder().encode(input);
 	const buffer = await crypto.subtle.digest("SHA-256", data);
 	return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -701,7 +701,7 @@ const EMA_JTI_KV_PREFIX = "enterprise-jti:";
 function createKvJtiStore() {
 	return { async markUsed({ issuer, jti, exp, now, env }) {
 		const ttl = Math.max(EMA_JTI_MIN_TTL_SECONDS, exp - now);
-		const key = `${EMA_JTI_KV_PREFIX}${await sha256Hex(`${issuer}\n${jti}`)}`;
+		const key = `${EMA_JTI_KV_PREFIX}${await sha256Hex$1(`${issuer}\n${jti}`)}`;
 		if (await env.OAUTH_KV.get(key)) return err({
 			reason: "replayed",
 			jti
@@ -1549,6 +1549,317 @@ function appendHeaderValue$1(headers, name, value) {
 	headers.set(name, values.join(", "));
 }
 
+//#endregion
+//#region src/oauth-consent.ts
+/**
+* Consent and upstream-state primitives for authorization servers that sign users in through a
+* third-party OAuth provider (an MCP "proxy" server). They implement the protections the MCP
+* 2026-07-28 security best practices require under Confused Deputy → Mitigation:
+*
+* - consent per client before any redirect to the third party, with CSRF protection and anti-framing
+*   headers on the consent page;
+* - remembered consent, chosen per call, in a signed `__Host-` cookie bound to the client, its redirect
+*   URI and resource (and the user, when the caller knows them), reused only for a subset of the
+*   approved scopes;
+* - the approved scopes chosen on the consent page, from any the server supports;
+* - a random `state` stored server-side only after consent, bound to the browser by a `__Host-` cookie,
+*   single-use and short-lived.
+*
+* A transaction handle is 256 random bits. KV stores the record under the handle's SHA-256, encrypted
+* with a key derived from the handle, so KV alone reveals neither the request nor deployer data such as
+* a PKCE verifier. Each transaction has its own binding cookie, named after its hash and holding the
+* full hash, so several authorizations can be in flight in one browser (two tabs) without replacing each
+* other. Single use is `get` then `delete`, which KV cannot make atomic: two concurrent requests from the
+* same browser with the same handle could both pass; the cookie binding confines that to the browser
+* that started the transaction.
+*/
+const TRANSACTION_TTL_SECONDS = 600;
+/** Default for the provider's `cookiePrefix` option. */
+const DEFAULT_COOKIE_PREFIX = "__Host-oauth-";
+const DEFAULT_REMEMBER_SECONDS = 720 * 60 * 60;
+const MIN_SECRET_LENGTH = 32;
+const MAX_APPROVALS_COOKIE_BYTES = 3800;
+/** Throws a `TypeError` unless the prefix keeps the `__Host-` guarantees the MCP best practices require. */
+function consentCookies(prefix = DEFAULT_COOKIE_PREFIX) {
+	if (typeof prefix !== "string" || !prefix.startsWith("__Host-") || !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(prefix)) throw new TypeError("cookiePrefix must start with \"__Host-\" and contain only cookie-name characters");
+	return {
+		consent: `${prefix}consent`,
+		upstream: `${prefix}upstream`,
+		approvals: `${prefix}approvals`
+	};
+}
+function validateRememberConsentOptions(options) {
+	if (typeof options !== "object" || options === null) throw new TypeError("remember must be an object with a secret");
+	if (typeof options.secret !== "string" || options.secret.length < MIN_SECRET_LENGTH) throw new TypeError(`remember.secret must be a string of at least ${MIN_SECRET_LENGTH} characters`);
+	const maxAge = options.maxAgeSeconds;
+	if (maxAge !== void 0 && (!Number.isInteger(maxAge) || maxAge <= 0)) throw new TypeError("remember.maxAgeSeconds must be a positive integer");
+	if (options.subject !== void 0 && (typeof options.subject !== "string" || options.subject.length === 0)) throw new TypeError("remember.subject must be a non-empty string");
+}
+/** Start a consent transaction for an authorization request that must be shown to the user. */
+async function beginConsent(kv, cookies, request) {
+	const { handle, hash } = await createTransaction(kv, {
+		kind: "consent",
+		request
+	});
+	return {
+		handle,
+		headers: new Headers({
+			"Set-Cookie": bindingCookie(transactionCookieName(cookies.consent, hash), hash, TRANSACTION_TTL_SECONDS),
+			"Cache-Control": "no-store",
+			"Content-Security-Policy": "frame-ancestors 'none'",
+			"X-Frame-Options": "DENY"
+		})
+	};
+}
+/**
+* Consume a consent transaction the user approved. `scope`, when given, replaces the requested
+* scopes: the page may narrow them or offer more, but each must be one the server supports
+* (`supportedScopes`, from `scopesSupported`). `remember` stores the approval in a signed cookie.
+*/
+async function approveConsent(kv, cookies, supportedScopes, request, handle, options = {}) {
+	if (options.remember !== void 0) validateRememberConsentOptions(options.remember);
+	const transaction = await openTransaction(kv, request, cookies.consent, handle, "consent");
+	let approved = transaction.record.request;
+	if (options.scope !== void 0) {
+		const supported = supportedScopes ? new Set(supportedScopes) : void 0;
+		const valid = (scope) => typeof scope === "string" && isValidOAuthScopeToken(scope) && (!supported || supported.has(scope));
+		if (!Array.isArray(options.scope) || !options.scope.every(valid)) throw new AuthorizationError("invalid_scope", { description: "Approved scopes must be ones this server supports" });
+		approved = {
+			...approved,
+			scope: [...new Set(options.scope)]
+		};
+	}
+	await transaction.consume();
+	const headers = new Headers({ "Cache-Control": "no-store" });
+	headers.append("Set-Cookie", clearCookie(transaction.cookieName));
+	if (options.remember) headers.append("Set-Cookie", await rememberApproval(cookies, request, approved, options.remember));
+	return {
+		request: approved,
+		headers
+	};
+}
+/**
+* Consume a consent transaction the user declined, and build the OAuth error redirect back to the
+* client: `error=access_denied`, the client's `state`, and `iss`. The redirect URI comes from the
+* stored request, which `parseAuthRequest()` validated, never from the form.
+*/
+async function denyConsent(kv, cookies, request, handle, options = {}) {
+	const transaction = await openTransaction(kv, request, cookies.consent, handle, "consent");
+	await transaction.consume();
+	const record = transaction.record;
+	const redirect = new URL(record.request.redirectUri);
+	redirect.searchParams.set("error", "access_denied");
+	if (options.description) redirect.searchParams.set("error_description", options.description);
+	if (record.request.state) redirect.searchParams.set("state", record.request.state);
+	if (record.request.issuer) redirect.searchParams.set("iss", record.request.issuer);
+	const headers = new Headers({
+		"Cache-Control": "no-store",
+		Location: redirect.href
+	});
+	headers.append("Set-Cookie", clearCookie(transaction.cookieName));
+	return {
+		request: record.request,
+		redirectTo: redirect.href,
+		headers
+	};
+}
+/** Whether a remembered approval covers this request: same client, redirect URI and resource, subset of scopes. */
+async function isConsentRemembered(cookies, request, authRequest, remember) {
+	validateRememberConsentOptions(remember);
+	const approvals = await readApprovals(cookies, request, remember.secret);
+	const key = await approvalKey(authRequest, remember.subject);
+	const now = Math.floor(Date.now() / 1e3);
+	const approval = approvals.find((entry) => entry.k === key && entry.e > now);
+	if (!approval) return false;
+	const approvedScopes = new Set(approval.s);
+	return authRequest.scope.every((scope) => approvedScopes.has(scope));
+}
+/**
+* Save an approved authorization request before redirecting to the third-party provider, and get
+* the `state` to send it. Call only after consent. Pass `headers` to add the binding cookie to
+* headers you are already sending, such as `approveConsent()`'s.
+*/
+async function beginUpstream(kv, cookies, request, options = {}) {
+	const { handle, hash } = await createTransaction(kv, {
+		kind: "upstream",
+		request,
+		data: options.data
+	});
+	const headers = options.headers ?? new Headers();
+	headers.append("Set-Cookie", bindingCookie(transactionCookieName(cookies.upstream, hash), hash, TRANSACTION_TTL_SECONDS));
+	headers.set("Cache-Control", "no-store");
+	return {
+		state: handle,
+		headers
+	};
+}
+/** Recover the authorization request at the third-party provider's callback, from its `state` parameter. */
+async function finishUpstream(kv, cookies, request) {
+	const state = new URL(request.url).searchParams.get("state");
+	if (!state) throw new AuthorizationError("invalid_request", { description: "Missing state parameter" });
+	const transaction = await openTransaction(kv, request, cookies.upstream, state, "upstream");
+	await transaction.consume();
+	const headers = new Headers({ "Cache-Control": "no-store" });
+	headers.append("Set-Cookie", clearCookie(transaction.cookieName));
+	return {
+		request: transaction.record.request,
+		data: transaction.record.data,
+		headers
+	};
+}
+async function createTransaction(kv, record) {
+	const handle = base64url(crypto.getRandomValues(new Uint8Array(32)));
+	const hash = await sha256Hex(handle);
+	const iv = crypto.getRandomValues(new Uint8Array(12));
+	const sealed = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, await transactionKey(handle), new TextEncoder().encode(JSON.stringify(record)));
+	await kv.put(`transaction:${hash}`, `${base64url(iv)}.${base64url(new Uint8Array(sealed))}`, { expirationTtl: TRANSACTION_TTL_SECONDS });
+	return {
+		handle,
+		hash
+	};
+}
+async function openTransaction(kv, request, cookieBase, handle, kind) {
+	if (typeof handle !== "string" || handle.length === 0) throw new AuthorizationError("invalid_request", { description: "Missing transaction handle" });
+	const hash = await sha256Hex(handle);
+	const cookieName = transactionCookieName(cookieBase, hash);
+	const bound = readCookie(request, cookieName);
+	if (!bound) throw new AuthorizationError("invalid_request", { description: "This authorization was not started in this browser; start again" });
+	if (!timingSafeEqual(hash, bound)) throw new AuthorizationError("invalid_request", { description: "This authorization belongs to a different browser session; start again" });
+	const key = `transaction:${hash}`;
+	const expired = new AuthorizationError("invalid_request", { description: "This authorization expired or was already used; start again" });
+	const stored = await kv.get(key);
+	if (!stored) throw expired;
+	let record;
+	try {
+		const [iv, sealed] = stored.split(".");
+		const plain = await crypto.subtle.decrypt({
+			name: "AES-GCM",
+			iv: fromBase64url(iv)
+		}, await transactionKey(handle), fromBase64url(sealed));
+		record = JSON.parse(new TextDecoder().decode(plain));
+	} catch {
+		throw expired;
+	}
+	if (record.kind !== kind) throw expired;
+	return {
+		record,
+		cookieName,
+		consume: () => kv.delete(key)
+	};
+}
+/** Only the holder of the handle can decrypt its record; KV keeps the hash, not the handle. */
+async function transactionKey(handle) {
+	const material = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`oauth-transaction-key:${handle}`));
+	return crypto.subtle.importKey("raw", material, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+/** One binding cookie per transaction, so concurrent authorizations in one browser don't collide. */
+function transactionCookieName(base, hash) {
+	return `${base}-${hash.slice(0, 16)}`;
+}
+async function rememberApproval(cookies, request, approved, remember) {
+	const maxAge = remember.maxAgeSeconds ?? DEFAULT_REMEMBER_SECONDS;
+	const now = Math.floor(Date.now() / 1e3);
+	const key = await approvalKey(approved, remember.subject);
+	const approvals = (await readApprovals(cookies, request, remember.secret)).filter((entry) => entry.e > now && entry.k !== key);
+	approvals.push({
+		k: key,
+		s: approved.scope,
+		e: now + maxAge
+	});
+	let value = await signApprovals(approvals, remember.secret);
+	while (value.length > MAX_APPROVALS_COOKIE_BYTES && approvals.length > 1) {
+		approvals.shift();
+		value = await signApprovals(approvals, remember.secret);
+	}
+	const cookieMaxAge = Math.max(...approvals.map((entry) => entry.e)) - now;
+	return `${cookies.approvals}=${value}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=${cookieMaxAge}`;
+}
+async function readApprovals(cookies, request, secret) {
+	const value = readCookie(request, cookies.approvals);
+	if (!value) return [];
+	const [payload, signature] = value.split(".");
+	if (!payload || !signature) return [];
+	const key = await hmacKey(secret);
+	let valid = false;
+	try {
+		valid = await crypto.subtle.verify("HMAC", key, fromBase64url(signature), new TextEncoder().encode(payload));
+	} catch {
+		return [];
+	}
+	if (!valid) return [];
+	try {
+		const parsed = JSON.parse(new TextDecoder().decode(fromBase64url(payload)));
+		return Array.isArray(parsed) ? parsed.filter(isApproval) : [];
+	} catch {
+		return [];
+	}
+}
+async function signApprovals(approvals, secret) {
+	const payload = base64url(new TextEncoder().encode(JSON.stringify(approvals)));
+	const signature = await crypto.subtle.sign("HMAC", await hmacKey(secret), new TextEncoder().encode(payload));
+	return `${payload}.${base64url(new Uint8Array(signature))}`;
+}
+function isApproval(value) {
+	if (!value || typeof value !== "object") return false;
+	const entry = value;
+	return typeof entry.k === "string" && typeof entry.e === "number" && Array.isArray(entry.s) && entry.s.every((scope) => typeof scope === "string");
+}
+/** Approval is bound to the client, where its tokens go, which resource they are for, and the user if known. */
+async function approvalKey(request, subject) {
+	const material = JSON.stringify([
+		request.clientId,
+		request.redirectUri,
+		request.resource ?? null,
+		subject ?? null
+	]);
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(material));
+	return base64url(new Uint8Array(digest));
+}
+function hmacKey(secret) {
+	return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign", "verify"]);
+}
+function bindingCookie(name, value, maxAge) {
+	return `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=${maxAge}`;
+}
+function clearCookie(name) {
+	return `${name}=; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=0`;
+}
+function readCookie(request, name) {
+	const header = request.headers.get("Cookie");
+	if (!header) return void 0;
+	for (const part of header.split(";")) {
+		const separator = part.indexOf("=");
+		if (separator === -1) continue;
+		if (part.slice(0, separator).trim() === name) return part.slice(separator + 1).trim();
+	}
+}
+async function sha256Hex(value) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index++) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return difference === 0;
+}
+function base64url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64url(value) {
+	const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
+	return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+
 //#endregion
 //#region src/oauth-provider.ts
 const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
@@ -1744,6 +2055,7 @@ var OAuthProviderImpl = class {
 		};
 		this.validateEndpoint(this.options.authorizeEndpoint, "authorizeEndpoint");
 		this.validateEndpoint(this.options.tokenEndpoint, "tokenEndpoint");
+		this.consentCookies = consentCookies(this.options.cookiePrefix);
 		if (this.options.clientRegistrationEndpoint) this.validateEndpoint(this.options.clientRegistrationEndpoint, "clientRegistrationEndpoint");
 		if (roleBased) this.validateAuthorizationServerRouteIsolation();
 		this.resourceServers = configuredResourceServers.map(({ resourceMetadata, resolveExternalToken }) => {
@@ -2460,6 +2772,24 @@ var OAuthProviderImpl = class {
 	* token issuance or `tokenExchangeCallback`. Anything else is re-thrown so
 	* unexpected failures still surface as 500s.
 	*/
+	/**
+	* Run `tokenExchangeCallback`. An `invalid_grant` it throws means the grant can never work again
+	* (RFC 6749 §5.2: invalid, expired, or revoked; transient failures are `temporarily_unavailable`),
+	* so the grant it ran for is revoked, with its tokens, before the error answers. A failed
+	* revocation is logged and the callback's error still answers the request.
+	*/
+	async callTokenExchangeCallback(options, env) {
+		try {
+			return await Promise.resolve(this.options.tokenExchangeCallback(options));
+		} catch (error) {
+			if (error instanceof OAuthError && error.code === "invalid_grant") try {
+				await this.createOAuthHelpers(env).revokeGrant(options.grantId, options.userId);
+			} catch (revokeError) {
+				console.warn(`Failed to revoke grant ${options.grantId} after tokenExchangeCallback answered invalid_grant:`, revokeError);
+			}
+			throw error;
+		}
+	}
 	createOAuthErrorResponse(error) {
 		if (!(error instanceof OAuthError)) return void 0;
 		return this.createErrorResponse(error.code, error.options, error.options.internal ?? {
@@ -2613,7 +2943,7 @@ var OAuthProviderImpl = class {
 				resource: audience,
 				props: decryptedProps
 			};
-			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
+			const callbackResult = await this.callTokenExchangeCallback(callbackOptions, env);
 			if (callbackResult) {
 				if (callbackResult.newProps) {
 					grantProps = callbackResult.newProps;
@@ -2760,7 +3090,7 @@ var OAuthProviderImpl = class {
 				resource: audience,
 				props: decryptedProps
 			};
-			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
+			const callbackResult = await this.callTokenExchangeCallback(callbackOptions, env);
 			if (callbackResult) {
 				if (callbackResult.newProps) {
 					grantProps = callbackResult.newProps;
@@ -2946,7 +3276,7 @@ var OAuthProviderImpl = class {
 				resource: newAudience,
 				props: decryptedProps
 			};
-			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
+			const callbackResult = await this.callTokenExchangeCallback(callbackOptions, env);
 			if (crossClientExchange && callbackResult?.allowCrossClientExchange !== true) throw crossClientRejection();
 			if (callbackResult) {
 				let accessTokenProps = decryptedProps;
@@ -4037,6 +4367,7 @@ var OAuthProviderImpl = class {
 * async function refreshUpstream(props) {
 *   const res = await fetch(...);
 *   if (res.status === 401) {
+*     // invalid_grant can never recover: the provider also revokes this grant and its tokens.
 *     throw new OAuthError('invalid_grant', { description: 'upstream refresh token is invalid' });
 *   }
 *   if (res.status === 429) {
@@ -4496,11 +4827,11 @@ const WRAPPING_KEY_HMAC_KEY = new Uint8Array([
 */
 async function deriveKeyFromToken(tokenStr) {
 	const encoder = new TextEncoder();
-	const hmacKey = await crypto.subtle.importKey("raw", WRAPPING_KEY_HMAC_KEY, {
+	const hmacKey$1 = await crypto.subtle.importKey("raw", WRAPPING_KEY_HMAC_KEY, {
 		name: "HMAC",
 		hash: "SHA-256"
 	}, false, ["sign"]);
-	const hmacResult = await crypto.subtle.sign("HMAC", hmacKey, encoder.encode(tokenStr));
+	const hmacResult = await crypto.subtle.sign("HMAC", hmacKey$1, encoder.encode(tokenStr));
 	return await crypto.subtle.importKey("raw", hmacResult, { name: "AES-KW" }, false, ["wrapKey", "unwrapKey"]);
 }
 /**
@@ -4849,7 +5180,8 @@ var OAuthHelpersImpl = class {
 		};
 		if (!isPublicClient && secretToStore) updatedClient.clientSecret = secretToStore;
 		else delete updatedClient.clientSecret;
-		await this.provider.putRegisteredClient(this.env, updatedClient, Math.floor(Date.now() / 1e3));
+		if (client.registrationExpiresAt === void 0) await this.env.OAUTH_KV.put(`client:${updatedClient.clientId}`, JSON.stringify(updatedClient));
+		else await this.provider.putRegisteredClient(this.env, updatedClient, Math.floor(Date.now() / 1e3));
 		const response = toPublicClientInfo(updatedClient);
 		if (!isPublicClient && originalSecret) response.clientSecret = originalSecret;
 		return response;
@@ -4917,6 +5249,30 @@ var OAuthHelpersImpl = class {
 	* @param userId - The ID of the user who owns the grant
 	* @returns A Promise resolving when the revocation is confirmed.
 	*/
+	/** {@inheritDoc OAuthHelpers.isConsentRemembered} */
+	isConsentRemembered(request, authRequest, remember) {
+		return isConsentRemembered(this.provider.consentCookies, request, authRequest, remember);
+	}
+	/** {@inheritDoc OAuthHelpers.beginConsent} */
+	beginConsent(authRequest) {
+		return beginConsent(this.env.OAUTH_KV, this.provider.consentCookies, authRequest);
+	}
+	/** {@inheritDoc OAuthHelpers.approveConsent} */
+	approveConsent(request, handle, options) {
+		return approveConsent(this.env.OAUTH_KV, this.provider.consentCookies, this.provider.options.scopesSupported, request, handle, options);
+	}
+	/** {@inheritDoc OAuthHelpers.denyConsent} */
+	denyConsent(request, handle, options) {
+		return denyConsent(this.env.OAUTH_KV, this.provider.consentCookies, request, handle, options);
+	}
+	/** {@inheritDoc OAuthHelpers.beginUpstream} */
+	beginUpstream(authRequest, options) {
+		return beginUpstream(this.env.OAUTH_KV, this.provider.consentCookies, authRequest, options);
+	}
+	/** {@inheritDoc OAuthHelpers.finishUpstream} */
+	finishUpstream(request) {
+		return finishUpstream(this.env.OAUTH_KV, this.provider.consentCookies, request);
+	}
 	async revokeGrant(grantId, userId) {
 		const grantKey = `grant:${userId}:${grantId}`;
 		const tokenPrefix = `token:${userId}:${grantId}:`;

package/docs/advanced-configuration.md

@@ -220,7 +220,7 @@ onError({ code, 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 }`.
+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
 

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/upstream-sign-in.md

@@ -0,0 +1,93 @@
+# Signing in through another provider
+
+Many MCP servers don't have their own users: they sign people in with GitHub, Sentry, Google, or another OAuth provider, and call that provider's API with the user's token. The MCP server is still the authorization server for MCP clients, but its `/authorize` page hands the user to the third party and finishes when the third party redirects back.
+
+Every MCP client then reaches the third party through your one OAuth app. MCP's security best practices call this the [confused deputy problem](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices#confused-deputy-problem) and require consent per client before the redirect, a consent page that can't be framed or forged, and a `state` bound to the user's browser. The helpers below implement those requirements; the consent page itself is yours.
+
+## The flow
+
+```ts
+const oauth = authorizationServer.getOAuthApi(env); // or env.OAUTH_PROVIDER with OAuthProvider
+
+// GET /authorize: parse, then ask for consent.
+const request = await oauth.parseAuthRequest(req);
+const client = await oauth.lookupClient(request.clientId);
+const consent = await oauth.beginConsent(request);
+return new Response(renderConsentPage({ client, request, handle: consent.handle }), {
+  headers: consent.headers, // binding cookie, no framing, no caching
+});
+
+// POST /authorize: the user approved. Now, and only now, start the third-party redirect.
+const form = await req.formData();
+const approved = await oauth.approveConsent(req, String(form.get('handle')), {
+  scope: form.getAll('scope').map(String), // optional: the scopes the user ticked, from any in scopesSupported
+});
+const verifier = crypto.randomUUID() + crypto.randomUUID();
+const { state, headers } = await oauth.beginUpstream(approved.request, {
+  data: { verifier }, // returned at the callback; never sent to the third party
+  headers: approved.headers,
+});
+headers.set('Location', githubAuthorizeUrl({ state, codeChallenge: await s256(verifier) }));
+return new Response(null, { status: 302, headers });
+
+// GET /callback: recover the request, exchange the third party's code, finish.
+const { request: original, data, headers: clear } = await oauth.finishUpstream<{ verifier: string }>(req);
+const upstream = await exchangeGithubCode(new URL(req.url).searchParams.get('code')!, data.verifier);
+const { redirectTo } = await oauth.completeAuthorization({
+  request: original,
+  userId: upstream.user.id,
+  metadata: {},
+  scope: original.scope,
+  props: { githubToken: upstream.accessToken }, // encrypted; handlers get it in ctx.props
+});
+clear.set('Location', redirectTo);
+return new Response(null, { status: 302, headers: clear });
+```
+
+Build the consent page itself, and the Deny path (`denyConsent()`), as in [consent-page.md](consent-page.md), which also covers which errors to redirect and which to render. Validation failures throw `AuthorizationError` without a `redirectUri`: render them locally. A `TypeError` (bad options) or a storage failure is a bug or an outage, not the user's doing.
+
+`beginUpstream()` doesn't check consent itself: call it only after `approveConsent()`, or when `isConsentRemembered()` says yes. (A server whose clients are all pre-registered, with no dynamic registration, isn't required to ask per client and can call it directly.)
+
+If the third party sends the user back with an error (they declined there, or it failed), `finishUpstream()` still returns the original request, so answer the client with it:
+
+```ts
+const { request: original, headers } = await oauth.finishUpstream(req);
+const error = new URL(req.url).searchParams.get('error');
+if (error) {
+  const redirect = new URL(original.redirectUri);
+  redirect.searchParams.set('error', 'access_denied');
+  redirect.searchParams.set('state', original.state);
+  if (original.issuer) redirect.searchParams.set('iss', original.issuer);
+  headers.set('Location', redirect.href);
+  return new Response(null, { status: 302, headers });
+}
+```
+
+## What the helpers guarantee
+
+- **The consent page can't be forged or framed.** `beginConsent()` binds the handle to the browser with a `__Host-` cookie (`Secure`, `HttpOnly`, `SameSite=Lax`, ten minutes) and returns `Content-Security-Policy: frame-ancestors 'none'` and `X-Frame-Options: DENY`. A post from another site has the handle but not the cookie, and is refused.
+- **`state` exists only after consent.** `beginUpstream()` creates it, stores the approved request server-side, and binds it to the browser. The callback is refused without the matching cookie, so a stolen third-party code can't be replayed in another browser.
+- **Single use, ten minutes, several at once.** Each handle and `state` works once, and each has its own binding cookie, so two tabs can authorize at the same time. KV keys hold only the SHA-256 of the handle, and the record, including your `data` (a PKCE verifier, say), is encrypted with a key only the handle derives: reading KV alone reveals nothing. KV can't make `get`-then-`delete` atomic, so two simultaneous requests from the _same_ browser with the same handle could both pass; the cookie binding rules out anyone else.
+- **Nothing trusted comes from the form.** The authorization request is recovered from storage, not from hidden fields, so the page can't be made to approve a different client or redirect URI. `scope` is the page's to choose, fewer or more than the client requested, but only from `scopesSupported`.
+
+## Remembering consent
+
+Pass `remember` to `approveConsent()` and check `isConsentRemembered()` before showing the page; when it's remembered, go straight to `beginUpstream()`. See [consent-page.md](consent-page.md#remembering-consent), which also covers the cookie names.
+
+## When the third party revokes access
+
+Store the third party's refresh token in `props` and refresh it in `tokenExchangeCallback`. When it answers `invalid_grant`, the user has revoked your app or the token is gone for good. Throw `invalid_grant` too: the library revokes this grant, with its tokens, so the MCP client re-authorizes instead of retrying a grant that can never work. For a transient failure (the provider is down, rate limited), throw `temporarily_unavailable` instead, which leaves the grant for the retry.
+
+```ts
+tokenExchangeCallback: async ({ grantType, props }) => {
+  if (grantType !== 'refresh_token') return;
+  const upstream = await refreshGithubToken(props.githubRefreshToken);
+  if (upstream.error === 'bad_refresh_token') {
+    throw new OAuthError('invalid_grant', { description: 'GitHub access was revoked' }); // revokes this grant
+  }
+  if (!upstream.ok) {
+    throw new OAuthError('temporarily_unavailable', { description: 'GitHub is unavailable', statusCode: 503 });
+  }
+  return { newProps: { ...props, githubToken: upstream.accessToken, githubRefreshToken: upstream.refreshToken } };
+},
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",