@cloudflare/workers-oauth-provider 1.0.0 → 1.2.0

package/dist/oauth-provider.d.ts

@@ -1,5 +1,126 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 
+//#region src/oauth-error.d.ts
+
+/**
+ * The error your code throws to the library: from a `tokenExchangeCallback`, or from an
+ * `OAuthResourceServer`'s `validateToken`, to answer with a standard OAuth error response instead
+ * of a generic failure. Its own module so both hosts can use it without importing the package entry.
+ */
+/**
+ * The internal reason behind an error response, forwarded to the `onError` hook and never
+ * placed on the wire. `category` is a stable kebab-case subsystem (`client-authentication`,
+ * `authorization-code-grant`, `refresh-token-grant`, `token-exchange-grant`,
+ * `token-endpoint-request`, `token-revocation`, `token-issuance`, `resource-indicator`,
+ * `client-registration`, `client-id-metadata-document`, `protected-resource`,
+ * `enterprise-managed-authorization`, `token-exchange-callback`); `reason` is a stable
+ * snake_case slug naming the exact check that failed. Treat both like enum members in semver.
+ * `detail` may carry structured context such as a caught error; it is never a secret.
+ */
+interface OAuthErrorInternal {
+  /** Stable kebab-case subsystem that produced the error. */
+  category: string;
+  /** Stable snake_case slug naming the failed check, often more specific than the wire description. */
+  reason: string;
+  /** Optional structured context, e.g. the caught error or the offending parameter. */
+  detail?: unknown;
+}
+/**
+ * Options accepted by the {@link OAuthError} constructor.
+ */
+interface OAuthErrorOptions {
+  /**
+   * Human-readable text returned in the `error_description` field.
+   */
+  description: string;
+  /**
+   * HTTP status code for the error response. Defaults to `400`.
+   */
+  statusCode?: number;
+  /**
+   * Additional response headers.
+   *
+   * For transient failures (e.g. upstream rate limits), set
+   * `Retry-After` here so well-behaved clients back off instead of
+   * retry-storming. Per RFC 7231 §7.1.3 the value may be either a
+   * number of seconds or an HTTP-date.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Internal reason forwarded to the `onError` hook and never sent on the wire. The library
+   * sets it on every error it originates; a `tokenExchangeCallback` may set its own. An
+   * `OAuthError` thrown without one reaches `onError` as
+   * `{ category: 'token-exchange-callback', reason: 'callback_error', detail: error }`.
+   */
+  internal?: OAuthErrorInternal;
+  /**
+   * For `insufficient_scope` from an `OAuthResourceServer`'s `validateToken`: every scope the
+   * operation needs, named in the `403` challenge. Defaults to the resource's `requiredScopes`.
+   */
+  requiredScopes?: string[];
+}
+/**
+ * The OAuth error your code throws to the library, to answer with a standard OAuth error instead
+ * of a generic failure. It is honoured in two places:
+ *
+ * - **`tokenExchangeCallback`** (token endpoint): the response is `{ error, error_description }`
+ *   with `statusCode` (default `400`) and `headers`. `invalid_grant` also revokes the grant.
+ *   Anything else thrown is a `500`.
+ * - **`OAuthResourceServer`'s `validateToken`**: `invalid_token` is a `401` and
+ *   `insufficient_scope` a `403`, each with a Bearer challenge (the latter naming
+ *   `requiredScopes`); any other code keeps `statusCode` and `headers`, such as `429` with
+ *   `Retry-After`. Anything else thrown is a `503`.
+ *
+ * Unexpected failures stay visible that way: the library doesn't catch everything and return 400.
+ * (`OAuthProvider`'s `resolveExternalToken` uses `ExternalTokenError` instead.)
+ *
+ * @example
+ * ```ts
+ * import { OAuthError } from '@cloudflare/workers-oauth-provider';
+ *
+ * tokenExchangeCallback: async (options) => {
+ *   if (options.grantType === 'refresh_token') {
+ *     // refreshUpstream() may throw OAuthError from any depth
+ *     return { newProps: await refreshUpstream(options.props) };
+ *   }
+ * }
+ *
+ * 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) {
+ *     // Mirror upstream's Retry-After if present, otherwise pick a default.
+ *     throw new OAuthError('temporarily_unavailable', {
+ *       description: 'upstream rate limited',
+ *       statusCode: 429,
+ *       headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
+ *     });
+ *   }
+ *   return await res.json();
+ * }
+ * ```
+ */
+declare class OAuthError extends Error {
+  /** OAuth 2.0 error code. */
+  readonly code: string;
+  /** Options controlling the OAuth error response. */
+  readonly options: OAuthErrorOptions & {
+    statusCode: number;
+  };
+  /** Human-readable description sent in the `error_description` field. */
+  readonly description: string;
+  /** HTTP status code for the error response. */
+  readonly statusCode: number;
+  /** Additional response headers. */
+  readonly headers?: Record<string, string>;
+  /** Scopes an `insufficient_scope` challenge names. */
+  readonly requiredScopes?: string[];
+  constructor(code: string, options: OAuthErrorOptions);
+}
+//#endregion
 //#region src/ema/result.d.ts
 
 /**
@@ -289,7 +410,7 @@ interface EmaOptions<Env = Cloudflare.Env> {
    * Set to `true` to also accept public clients on this grant — for example
    * clients registered via a Client ID Metadata Document (CIMD), which are
    * always public (`none`) and therefore cannot present a client secret. The
-   * security trade-off is documented in the README: the trust then rests on
+   * security trade-off is documented in docs/advanced-configuration.md: the trust then rests on
    * the IdP-issued, signature-verified, short-lived, single-use ID-JAG
    * assertion (audience- and client-bound), together with the provider's
    * configured resource pinning, rather than on a separately presented client
@@ -310,6 +431,23 @@ interface AuthorizationErrorOptions {
   /** Authorization server issuer for RFC 9207 error responses. */
   issuer?: string;
 }
+/**
+ * The OAuth error redirect back to a client (RFC 6749 §4.1.2.1): `error`, an optional
+ * `error_description`, the client's `state`, and `iss` (RFC 9207). Pass only a request the
+ * library validated, from `parseAuthRequest()`, `finishUpstream()` or `approveConsent()`,
+ * never one rebuilt from user input.
+ *
+ * ```ts
+ * if (new URL(req.url).searchParams.get('error')) {
+ *   return Response.redirect(authorizationErrorRedirect(original, 'access_denied'), 302);
+ * }
+ * ```
+ */
+declare function authorizationErrorRedirect(request: {
+  redirectUri: string;
+  state?: string;
+  issuer?: string;
+}, code: AuthorizationErrorCode, description?: string): string;
 /**
  * Expected authorization-request validation failure. Absence of `redirectUri`
  * means a caller MUST render locally and MUST NOT redirect.
@@ -320,9 +458,13 @@ declare class AuthorizationError extends Error {
   readonly redirectUri?: string;
   readonly state?: string;
   readonly issuer?: string;
+  /**
+   * The ready-made error redirect back to the client, set only when a redirect is safe
+   * (`redirectUri` was validated). Without it, render the error locally.
+   */
+  readonly redirectTo?: string;
   constructor(code: AuthorizationErrorCode, options: AuthorizationErrorOptions);
 }
-declare function isValidOAuthScopeToken(scopeToken: string): boolean;
 //#endregion
 //#region src/oauth-resource-server.d.ts
 /** RFC 9728 metadata published by a standalone OAuth resource server. */
@@ -331,7 +473,10 @@ interface OAuthResourceMetadata {
   resource: string;
   /** Authorization server issuers that can issue tokens for this resource. */
   authorization_servers: string[];
-  /** Minimal scopes used to access the protected resource. */
+  /**
+   * Minimal scopes used to access the protected resource.
+   * @deprecated Use `requiredScopes`, which this becomes on the wire. Setting both is refused.
+   */
   scopes_supported?: string[];
   /** Bearer-token presentation methods. This implementation supports only `header`. */
   bearer_methods_supported?: string[];
@@ -398,6 +543,18 @@ type OAuthResourceHandler<Env, Props> = {
 interface OAuthResourceServerOptions<Env = Cloudflare.Env, Props = unknown> {
   /** RFC 9728 metadata, including this server's one canonical resource. */
   resourceMetadata: OAuthResourceMetadata;
+  /**
+   * The scopes required for accessing this resource (MCP: the minimal set for basic use). Published
+   * as its protected resource metadata's `scopes_supported` and named in the `401` challenge, so
+   * clients request them first; not the authorization server's catalogue, `scopesSupported`.
+   * Operations that need more ask for it with `insufficientScope()` (step-up). `offline_access` is
+   * removed automatically. Leave unset when your consent page picks the scopes.
+   *
+   * Advertised, not enforced: the handler decides whether a token is sufficient (`ctx.auth.scope`),
+   * because only it knows the deployment's scope hierarchy (a broader scope implying a narrower
+   * one), which MCP requires servers to honour.
+   */
+  requiredScopes?: string[];
   /** Application handler for the canonical resource URL and its path descendants. */
   handler: OAuthResourceHandler<Env, Props>;
   /**
@@ -409,7 +566,15 @@ interface OAuthResourceServerOptions<Env = Cloudflare.Env, Props = unknown> {
    *   `(env) => env.AUTH_SERVER.validateToken`
    * - The authorization server in this Worker:
    *   `(env) => (resource, token) => authorizationServer.validateToken(resource, token, env)`
-   * - Anything else, at your own risk: a function that validates the token for `resource`.
+   * - Anything else, at your own risk: a function that validates the token for `resource`,
+   *   such as one that recognises an upstream API's credentials and validates them itself
+   *   before falling back to the authorization server.
+   *
+   * Return `null` for a token that isn't valid here (a `401` challenge). Throw an `OAuthError`
+   * for a specific answer: `temporarily_unavailable` with `statusCode: 429` and a `Retry-After`
+   * header, `insufficient_scope` with `requiredScopes`, or `invalid_token` with a description.
+   * Anything else thrown is a validator failure (`503`). An `OAuthError` thrown in another
+   * Worker arrives over RPC as a plain `Error`, so throw it in this Worker's validator.
    */
   validateToken(env: Env, request: Request): OAuthResourceTokenValidator<Props>;
 }
@@ -439,18 +604,80 @@ declare class OAuthResourceServer<Env = Cloudflare.Env, Props = unknown> {
   fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
 }
 //#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;
+//#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;
+}
 /**
- * Whether a requested resource identifies a granted or configured resource.
- * Only ASCII case in the URI scheme and host is ignored, and an empty path is
- * equivalent to `/` (RFC 3986 §6.2.3), so a client that round-trips
- * `https://example.com` through a URL parser as `https://example.com/` still
- * names it. Port, path, query, a trailing slash after a path segment, user
- * information, and every other byte remain significant.
+ * What a consent page must show, per the MCP authorization spec and security best practices.
+ * Every string here may come from the client (dynamic registration or a CIMD document), so
+ * escape all of it before rendering.
  */
-declare function resourceMatches(requested: string, granted: string): boolean;
+interface ConsentDescription {
+  clientId: string;
+  /** The client's name, or its client ID when it gave none. Self-asserted unless `clientDomain` is set. */
+  clientName: string;
+  /**
+   * For a Client ID Metadata Document client: the hostname of its HTTPS client ID, a domain the
+   * client controls. Show it prominently. Absent for registered clients, whose names are unverified.
+   */
+  clientDomain?: string;
+  clientUri?: string;
+  logoUri?: string;
+  /** Where the tokens will be sent. */
+  redirectUri: string;
+  /**
+   * The redirect URI's hostname, which the page MUST display. A native app's private-use URI
+   * (`com.example.app:/callback`) has no host, so it's the whole URI instead.
+   */
+  redirectHost: string;
+  /**
+   * The redirect goes to a local app (`localhost`, `127.0.0.0/8`, `::1`). The page SHOULD warn:
+   * any local process could be listening, whatever name the client claims.
+   */
+  redirectIsLoopback: boolean;
+  /** The scopes being requested. */
+  scope: 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-provider.d.ts
 /**
@@ -508,19 +735,19 @@ interface TokenExchangeCallbackResult {
    */
   accessTokenTTL?: number;
   /**
-   * Override the default refresh token TTL (time-to-live) for this specific grant.
-   * Value should be in seconds.
-   * Note: This is only honored during authorization code exchange. Returning it during
-   * refresh token exchange is rejected with `invalid_request`; to extend a grant on
-   * refresh, return `refreshTokenIdleTTL`.
+   * Override the default refresh token TTL (time-to-live) for this specific grant, in seconds:
+   * `0` issues no refresh token, anything else must be an integer of at least 60. `undefined`
+   * keeps the provider's `refreshTokenTTL`; it never means "no expiry".
+   * Applies at authorization code exchange only and is ignored for other grant types, so one
+   * callback can return it for every grant; to extend a grant on refresh, return
+   * `refreshTokenIdleTTL`.
    */
   refreshTokenTTL?: number;
   /**
    * Idle lifetime for this grant's refresh token, in seconds from this refresh. The
-   * grant then expires that long after this refresh unless it is refreshed again. Only
-   * honored during refresh token exchange; returning it for another grant type is
-   * rejected with `invalid_request`. Overrides the provider's `refreshTokenIdleTTL`
-   * for this refresh.
+   * grant then expires that long after this refresh unless it is refreshed again. Applies to
+   * refresh token exchange only and is ignored for other grant types. Overrides the provider's
+   * `refreshTokenIdleTTL` for this refresh.
    *
    * Useful when the Worker is itself an OAuth client and has just rotated an upstream
    * refresh token: return the upstream lifetime and the grant lives exactly as long as
@@ -544,7 +771,7 @@ interface TokenExchangeCallbackResult {
 /**
  * Options for token exchange callback functions
  */
-interface TokenExchangeCallbackOptions {
+interface TokenExchangeCallbackOptions<Env = Cloudflare.Env> {
   /**
    * The type of grant being processed.
    */
@@ -587,6 +814,11 @@ interface TokenExchangeCallbackOptions {
    * Application-specific properties currently associated with this grant
    */
   props: any;
+  /**
+   * The Worker's environment for this request, so the callback can reach secrets and bindings
+   * (an upstream provider's client secret, say) without the provider being rebuilt per request.
+   */
+  env: Env;
 }
 /**
  * Options for the client registration callback (RFC 7591).
@@ -684,7 +916,10 @@ interface OAuthProtectedResourceMetadata {
    * issuer.
    */
   authorization_servers?: string[];
-  /** Minimal scopes required for basic protected-resource functionality. */
+  /**
+   * Minimal scopes required for basic protected-resource functionality.
+   * @deprecated Use `requiredScopes`, which this becomes on the wire. Setting both is refused.
+   */
   scopes_supported?: string[];
   /** Methods by which bearer tokens can be presented. Defaults to `["header"]`. */
   bearer_methods_supported?: string[];
@@ -756,6 +991,7 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * Defaults to 30 days (2,592,000 seconds).
    * Set to 0 to disable refresh tokens entirely.
    * Set to `undefined` explicitly for refresh tokens that never expire.
+   * Anything else must be an integer of at least 60 seconds (Cloudflare KV's minimum expiration window).
    * For example: 3600 = 1 hour, 2592000 = 30 days
    */
   refreshTokenTTL?: number;
@@ -776,27 +1012,16 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * Defaults to 90 days (7,776,000 seconds).
    * Clients created via the DCR endpoint will automatically expire after this duration.
    * Clients created via `OAuthHelpers.createClient()` are not affected by this setting.
-   * Set to `undefined` explicitly for clients that never expire.
+   * Set to `undefined` explicitly for clients that never expire; otherwise an integer of at
+   * least 60 seconds (Cloudflare KV's minimum expiration window).
    */
   clientRegistrationTTL?: number;
   /**
    * Scopes supported by the authorization server.
-   * These are advertised only in authorization server metadata; configure
-   * `resourceMetadata.scopes_supported` separately for protected resource requirements.
+   * These are advertised only in authorization server metadata; configure a resource's
+   * required scopes separately, with `requiredScopes`.
    */
   scopesSupported?: string[];
-  /**
-   * Controls whether the OAuth implicit flow is allowed.
-   * This flow is discouraged in OAuth 2.1 due to security concerns.
-   * Defaults to false.
-   */
-  allowImplicitFlow?: boolean;
-  /**
-   * Controls whether the legacy plain PKCE method is allowed.
-   * Defaults to false so PKCE challenges use S256 exclusively.
-   * Set to true only for compatibility with clients that cannot use S256.
-   */
-  allowPlainPKCE?: boolean;
   /**
    * Controls whether OAuth 2.0 Token Exchange (RFC 8693) is allowed.
    * When false, the token exchange grant type will not be advertised in metadata
@@ -834,7 +1059,7 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * The callback can return new props values that will be stored with the token or grant.
    * If the callback returns nothing or undefined for a props field, the original props will be used.
    */
-  tokenExchangeCallback?: (options: TokenExchangeCallbackOptions) => Promise<TokenExchangeCallbackResult | void> | TokenExchangeCallbackResult | void;
+  tokenExchangeCallback?: (options: TokenExchangeCallbackOptions<Env>) => Promise<TokenExchangeCallbackResult | void> | TokenExchangeCallbackResult | void;
   /**
    * Optional callback called when a provided bearer credential was not found
    * in the internal KV. It can validate an external OAuth access token, opaque
@@ -872,6 +1097,12 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
     internal: OAuthErrorInternal;
     request?: Request;
   }) => Response | void;
+  /**
+   * Accept RFC 8252 private-use URI scheme redirect URIs (for example `com.example.app:/oauth`)
+   * for native apps. By default redirect URIs must use `https`, or `http` on a loopback host, as
+   * MCP and OAuth 2.1 require; remote `http` is never accepted. Leave this off for MCP servers.
+   */
+  allowPrivateUseRedirectUris?: boolean;
   /**
    * Explicitly enable Client ID Metadata Document (CIMD) support.
    * When true, URL-formatted client_ids will be fetched as metadata documents.
@@ -879,11 +1110,29 @@ 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.
    */
   resourceMetadata: OAuthProtectedResourceMetadata;
+  /**
+   * The scopes required for accessing this resource (MCP: the minimal set for basic use). Published
+   * as its protected resource metadata's `scopes_supported` and named in the `401` challenge, so
+   * clients request them first; not the authorization server's catalogue, `scopesSupported`.
+   * Operations that need more ask for it with `insufficientScope()` (step-up). `offline_access` is
+   * removed automatically. Leave unset when your consent page picks the scopes.
+   *
+   * Advertised, not enforced: the handler decides whether a token is sufficient (`ctx.auth.scope`),
+   * because only it knows the deployment's scope hierarchy (a broader scope implying a narrower
+   * one), which MCP requires servers to honour.
+   */
+  requiredScopes?: string[];
 }
 /**
  * Functional authorization-server surface for the role-based API.
@@ -891,9 +1140,20 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
  * `getOAuthApi()` to parse and complete it; `fetch()` serves protocol-owned AS
  * endpoints such as metadata, token, revocation, and optional registration.
  */
-type OAuthAuthorizationServerOptions<Env = Cloudflare.Env> = Omit<OAuthProviderOptions<Env>, 'apiRoute' | 'apiHandler' | 'apiHandlers' | 'defaultHandler' | 'resourceMetadata' | 'resolveExternalToken'> & {
+type OAuthAuthorizationServerOptions<Env = Cloudflare.Env> = Omit<OAuthProviderOptions<Env>, 'apiRoute' | 'apiHandler' | 'apiHandlers' | 'defaultHandler' | 'authorizeEndpoint' | 'tokenEndpoint' | 'resourceMetadata' | 'requiredScopes' | 'resolveExternalToken'> & {
   /** Canonical RFC 8414 issuer. */
   issuer: string;
+  /**
+   * Your authorization endpoint, advertised in metadata. Route it before calling `fetch()`;
+   * `parseAuthRequest()` rejects requests that arrive anywhere else, so a mismatch fails on the
+   * first request. Defaults to `${issuer}/authorize`. A path is on the issuer's origin.
+   */
+  authorizeEndpoint?: string;
+  /**
+   * The token endpoint, which also handles revocation, served by `fetch()` and advertised in
+   * metadata. Defaults to `${issuer}/oauth/token`. A path is on the issuer's origin.
+   */
+  tokenEndpoint?: string;
   /**
    * Canonical identifiers of every protected resource this authorization server issues
    * tokens for, whether hosted in this Worker through `OAuthResourceServer` or by another
@@ -956,6 +1216,60 @@ interface OAuthHelpers {
   completeAuthorization(options: CompleteAuthorizationOptions): Promise<{
     redirectTo: string;
   }>;
+  /**
+   * The facts a consent page must show for a request: the client's name (and, for a Client ID
+   * Metadata Document client, its verified domain), the redirect URI's hostname, whether it goes
+   * to a local app, and the scopes. Every string may come from the client: escape it.
+   * @throws CimdFetchError when the client's metadata document cannot be resolved
+   */
+  describeConsent(authRequest: AuthRequest): Promise<ConsentDescription>;
+  /**
+   * 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
@@ -969,16 +1283,28 @@ interface OAuthHelpers {
    */
   listClients(options?: ListOptions): Promise<ListResult<ClientInfo>>;
   /**
-   * Updates an existing OAuth client
+   * Updates an existing OAuth client. Redirect URIs, grant types and response types are held to
+   * the same rules as registration. Client ID Metadata Document clients can't be updated here:
+   * their document owns their metadata.
    * @param clientId - The ID of the client to update
    * @param updates - Partial client information with fields to update
    * @returns A Promise resolving to the updated client info, or null if not found
+   * @throws Error when an update breaks the redirect URI policy or names an unsupported grant or response type
+   * @throws TypeError for a Client ID Metadata Document client while CIMD is enabled
    */
   updateClient(clientId: string, updates: Partial<ClientInfo>): Promise<ClientInfo | null>;
   /**
-   * Deletes an OAuth client
+   * Deletes an OAuth client, then revokes its grants and tokens across all users. The client
+   * can no longer authenticate, authorize or refresh as soon as the call starts. Access tokens
+   * it already holds stay valid until revocation reaches them or they expire (`accessTokenTTL`):
+   * validating an access token reads only the token record, never the client. If revocation is
+   * cut short (for example by a subrequest limit on a very large namespace), the call throws;
+   * call it again to continue, and `purgeExpiredData()` also removes the leftovers, which are
+   * orphaned grants by then.
+   * For a Client ID Metadata Document client there is no stored record: this revokes its grants,
+   * and the client can authorize again as long as its document resolves.
    * @param clientId - The ID of the client to delete
-   * @returns A Promise resolving when the deletion is confirmed.
+   * @returns A Promise resolving when the client and all its grants are gone.
    */
   deleteClient(clientId: string): Promise<void>;
   /**
@@ -1182,7 +1508,9 @@ interface CompleteAuthorizationOptions {
    */
   request: AuthRequest;
   /**
-   * Identifier for the user granting the authorization
+   * Identifier for the user granting the authorization. Must be non-empty and must not contain
+   * `:`, which separates the parts of issued tokens and storage keys; encode namespaced or
+   * composite IDs first (for example `encodeURIComponent('tenant:user')`).
    */
   userId: string;
   /**
@@ -1205,15 +1533,6 @@ interface CompleteAuthorizationOptions {
    * Set to false to allow multiple concurrent grants per user+client.
    */
   revokeExistingGrants?: boolean;
-  /**
-   * How many grants written by a version before 1.0 are read at once while
-   * revoking existing grants. Grants written by 1.0 or later carry their client,
-   * resource and redirect URI as KV key metadata and are matched from `list()`
-   * without being read, so this only bounds the fan-out for older grants. Only
-   * used when revokeExistingGrants is not false. Must be a positive integer;
-   * values above 1000 are clamped. Defaults to 50.
-   */
-  revokeExistingGrantsBatchSize?: number;
 }
 /**
  * Authorization grant record
@@ -1370,7 +1689,8 @@ interface Token extends TokenBase {
    */
   grant: {
     /**
-     * Client that received this grant
+     * Client this token was issued to: the grant's client, or, for a token from an allowed
+     * cross-client token exchange, the client that requested it (RFC 8693).
      */
     clientId: string;
     /**
@@ -1393,7 +1713,8 @@ interface TokenSummary<T = any> extends TokenBase {
    */
   grant: {
     /**
-     * Client that received this grant
+     * Client this token was issued to: the grant's client, or, for a token from an allowed
+     * cross-client token exchange, the client that requested it (RFC 8693).
      */
     clientId: string;
     /**
@@ -1465,6 +1786,12 @@ interface PurgeOptions {
    * Defaults to true.
    */
   purgeOrphanedTokens?: boolean;
+  /**
+   * Where to resume: the `cursor` from the previous invocation's result. Omit it to start
+   * a new sweep. Persist the returned cursor between invocations (for example in KV), or
+   * every invocation re-checks the same first `batchSize` records.
+   */
+  cursor?: string;
 }
 /**
  * Result of a purgeExpiredData garbage collection invocation
@@ -1478,8 +1805,10 @@ interface PurgeResult {
   tokensChecked: number;
   /** Number of token records purged (orphaned) */
   tokensPurged: number;
-  /** True if the full key space was scanned in this invocation (both grants and tokens) */
+  /** True once the sweep has covered both key spaces; there is no `cursor` then. */
   done: boolean;
+  /** Pass as `PurgeOptions.cursor` to the next invocation to continue this sweep. Absent when `done`. */
+  cursor?: string;
 }
 /**
  * Public representation of a grant, with sensitive data removed
@@ -1603,107 +1932,6 @@ declare function getOAuthApi<Env = Cloudflare.Env>(options: OAuthProviderOptions
  * Error class for OAuth operations
  * Carries OAuth error code and description for proper error responses
  */
-/**
- * The internal reason behind an error response, forwarded to the `onError` hook and never
- * placed on the wire. `category` is a stable kebab-case subsystem (`client-authentication`,
- * `authorization-code-grant`, `refresh-token-grant`, `token-exchange-grant`,
- * `token-endpoint-request`, `token-revocation`, `token-issuance`, `resource-indicator`,
- * `client-registration`, `client-id-metadata-document`, `protected-resource`,
- * `enterprise-managed-authorization`, `token-exchange-callback`); `reason` is a stable
- * snake_case slug naming the exact check that failed. Treat both like enum members in semver.
- * `detail` may carry structured context such as a caught error; it is never a secret.
- */
-interface OAuthErrorInternal {
-  /** Stable kebab-case subsystem that produced the error. */
-  category: string;
-  /** Stable snake_case slug naming the failed check, often more specific than the wire description. */
-  reason: string;
-  /** Optional structured context, e.g. the caught error or the offending parameter. */
-  detail?: unknown;
-}
-/**
- * Options accepted by the {@link OAuthError} constructor.
- */
-interface OAuthErrorOptions {
-  /**
-   * Human-readable text returned in the `error_description` field.
-   */
-  description: string;
-  /**
-   * HTTP status code for the error response. Defaults to `400`.
-   */
-  statusCode?: number;
-  /**
-   * Additional response headers.
-   *
-   * For transient failures (e.g. upstream rate limits), set
-   * `Retry-After` here so well-behaved clients back off instead of
-   * retry-storming. Per RFC 7231 §7.1.3 the value may be either a
-   * number of seconds or an HTTP-date.
-   */
-  headers?: Record<string, string>;
-  /**
-   * Internal reason forwarded to the `onError` hook and never sent on the wire. The library
-   * sets it on every error it originates; a `tokenExchangeCallback` may set its own. An
-   * `OAuthError` thrown without one reaches `onError` as
-   * `{ category: 'token-exchange-callback', reason: 'callback_error', detail: error }`.
-   */
-  internal?: OAuthErrorInternal;
-}
-/**
- * Structured OAuth 2.0 token-endpoint error.
- *
- * Throw from a `tokenExchangeCallback` or any code it calls to surface a
- * standard OAuth token response (`{ error, error_description }`) instead of a
- * generic `500 Internal Server Error`.
- *
- * Anything thrown that is **not** an `OAuthError` continues to surface as
- * a 500 so unexpected failures remain visible — the provider does not
- * catch-everything-and-return-400.
- *
- * @example
- * ```ts
- * import { OAuthError } from '@cloudflare/workers-oauth-provider';
- *
- * tokenExchangeCallback: async (options) => {
- *   if (options.grantType === 'refresh_token') {
- *     // refreshUpstream() may throw OAuthError from any depth
- *     return { newProps: await refreshUpstream(options.props) };
- *   }
- * }
- *
- * async function refreshUpstream(props) {
- *   const res = await fetch(...);
- *   if (res.status === 401) {
- *     throw new OAuthError('invalid_grant', { description: 'upstream refresh token is invalid' });
- *   }
- *   if (res.status === 429) {
- *     // Mirror upstream's Retry-After if present, otherwise pick a default.
- *     throw new OAuthError('temporarily_unavailable', {
- *       description: 'upstream rate limited',
- *       statusCode: 429,
- *       headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
- *     });
- *   }
- *   return await res.json();
- * }
- * ```
- */
-declare class OAuthError extends Error {
-  /** OAuth 2.0 error code. */
-  readonly code: string;
-  /** Options controlling the OAuth error response. */
-  readonly options: OAuthErrorOptions & {
-    statusCode: number;
-  };
-  /** Human-readable description sent in the `error_description` field. */
-  readonly description: string;
-  /** HTTP status code for the error response. */
-  readonly statusCode: number;
-  /** Additional response headers. */
-  readonly headers?: Record<string, string>;
-  constructor(code: string, options: OAuthErrorOptions);
-}
 /** Options accepted by the {@link ExternalTokenError} constructor. */
 interface ExternalTokenErrorOptions {
   /**
@@ -1780,20 +2008,5 @@ declare class CimdFetchError extends Error {
    */
   constructor(metadataUrl: string, cause: unknown);
 }
-/**
- * Decodes a base64url-encoded string to bytes.
- */
-declare function base64UrlToBytes(base64Url: string): Uint8Array;
-/**
- * Parses a base64url-encoded JWT JSON part into an object.
- */
-declare function parseJwtJsonPart(encoded: string): Record<string, unknown>;
-/**
- * Gets WebCrypto import and verify parameters for supported JOSE algorithms.
- */
-declare function getJwtCryptoAlgorithms(alg: string): {
-  importAlgorithm: Parameters<SubtleCrypto['importKey']>[2];
-  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 ConsentDescription, 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, type OAuthErrorInternal, type 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, authorizationErrorRedirect, getOAuthApi, insufficientScope };