@cloudflare/workers-oauth-provider 0.10.4 → 1.1.0

package/dist/oauth-provider.d.ts

@@ -324,6 +324,178 @@ declare class AuthorizationError extends Error {
 }
 declare function isValidOAuthScopeToken(scopeToken: string): boolean;
 //#endregion
+//#region src/oauth-resource-server.d.ts
+/** RFC 9728 metadata published by a standalone OAuth resource server. */
+interface OAuthResourceMetadata {
+  /** The one canonical HTTPS identifier for this protected resource. */
+  resource: string;
+  /** Authorization server issuers that can issue tokens for this resource. */
+  authorization_servers: string[];
+  /** Minimal scopes used to access the protected resource. */
+  scopes_supported?: string[];
+  /** Bearer-token presentation methods. This implementation supports only `header`. */
+  bearer_methods_supported?: string[];
+  /** Human-readable protected-resource name. */
+  resource_name?: string;
+}
+/** Successful result returned by the application's token validator. */
+interface OAuthResourceTokenValidation<Props> {
+  /** Application data exposed to the protected handler as `ctx.props`. */
+  props: Props;
+  /** Canonical audience to which the token is bound. */
+  audience: string;
+  /** Optional absolute expiry as seconds since the Unix epoch. */
+  expiresAt?: number;
+  /**
+   * Scopes the token carries. `OAuthAuthorizationServer.validateToken()` always reports them;
+   * a handler needs them to answer with {@link insufficientScope}.
+   */
+  scope?: string[];
+  /** Subject the token was issued for. */
+  userId?: string;
+  /** Client the token was issued to. */
+  clientId?: string;
+}
+/**
+ * What the host verified about the bearer token before calling the handler, exposed as
+ * `ctx.auth` beside the application's `ctx.props`. Both hosts set it: `OAuthResourceServer`
+ * from the validator's result, `OAuthProvider` from its own token record.
+ */
+interface OAuthResourceAuth {
+  /** The token as presented. It is already in the request's `Authorization` header; never log it. */
+  token: string;
+  /** Canonical resource the token was accepted for. */
+  audience: string;
+  /** Absolute expiry as seconds since the Unix epoch, when known. */
+  expiresAt?: number;
+  /** Scopes the token carries; empty when the validator reported none. */
+  scope: string[];
+  /** Subject the token was issued for, when known. */
+  userId?: string;
+  /** Client the token was issued to, when known. */
+  clientId?: string;
+}
+/** The execution context a protected handler receives: `props` from the validator, `auth` from the host. */
+type OAuthResourceContext<Props> = ExecutionContext<Props> & {
+  readonly auth: OAuthResourceAuth;
+};
+/**
+ * Validates a bearer token presented to one resource. `null` for a token that is not
+ * valid for that resource; a thrown error fails closed as `503`.
+ */
+type OAuthResourceTokenValidator<Props> = (resource: string, token: string) => Promise<OAuthResourceTokenValidation<Props> | null>;
+/**
+ * Protected application handler called after successful token validation: an object with
+ * `fetch`, or a `WorkerEntrypoint` subclass instantiated per request with `(ctx, env)`. Either
+ * way `ctx.props` carries what the validator returned and `ctx.auth` what the host verified.
+ */
+type OAuthResourceHandler<Env, Props> = {
+  fetch(request: Request, env: Env, ctx: OAuthResourceContext<Props>): Response | Promise<Response>;
+} | (new (ctx: OAuthResourceContext<Props>, env: Env) => {
+  fetch(request: Request): Response | Promise<Response>;
+});
+/** Configuration for {@link OAuthResourceServer}. */
+interface OAuthResourceServerOptions<Env = Cloudflare.Env, Props = unknown> {
+  /** RFC 9728 metadata, including this server's one canonical resource. */
+  resourceMetadata: OAuthResourceMetadata;
+  /** Application handler for the canonical resource URL and its path descendants. */
+  handler: OAuthResourceHandler<Env, Props>;
+  /**
+   * The validator for a request. The host calls what you return with this server's
+   * canonical resource and the bearer token, so neither is repeated here.
+   *
+   * - The authorization server in another Worker, over a Service Binding to a
+   *   `WorkerEntrypoint` that exposes `OAuthAuthorizationServer.validateToken()`:
+   *   `(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`.
+   */
+  validateToken(env: Env, request: Request): OAuthResourceTokenValidator<Props>;
+}
+/**
+ * The response for a valid token that lacks the scopes an operation needs (RFC 6750 §3.1,
+ * MCP scope challenge handling): `403` with `WWW-Authenticate: Bearer error="insufficient_scope"`,
+ * the `scope` the operation requires and the `resource_metadata` URL the client already knows.
+ * Name every scope the operation needs in one response; clients treat the list as complete.
+ *
+ * ```ts
+ * if (!ctx.auth.scope.includes('calendar:write')) return insufficientScope(ctx.auth, ['calendar:write']);
+ * ```
+ */
+declare function insufficientScope(auth: OAuthResourceAuth, scope: string[], description?: string): Response;
+/**
+ * One OAuth protected resource, in the authorization server's Worker or its own. Publishes
+ * RFC 9728 metadata, challenges unauthenticated requests, validates the bearer token through
+ * the configured `validateToken`, enforces audience and expiry on what it returns, and routes
+ * only the canonical resource and its descendants to the application handler.
+ *
+ * `export default new OAuthResourceServer({ … })`, or dispatch to `fetch()` from your own
+ * router, exactly as with `OAuthAuthorizationServer`.
+ */
+declare class OAuthResourceServer<Env = Cloudflare.Env, Props = unknown> {
+  #private;
+  constructor(options: OAuthResourceServerOptions<Env, Props>);
+  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;
+/**
+ * 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.
+ */
+declare function resourceMatches(requested: string, granted: string): boolean;
+//#endregion
 //#region src/oauth-provider.d.ts
 /**
  * Enum representing OAuth grant types
@@ -337,8 +509,8 @@ declare enum GrantType {
 /**
  * Aliases for either type of Handler that makes .fetch required
  */
-type ExportedHandlerWithFetch<Env = Cloudflare.Env> = ExportedHandler<Env> & Pick<Required<ExportedHandler<Env>>, 'fetch'>;
-type WorkerEntrypointWithFetch<Env = Cloudflare.Env> = WorkerEntrypoint<Env> & {
+type ExportedHandlerWithFetch<Env = Cloudflare.Env, Props = unknown> = ExportedHandler<Env, unknown, unknown, Props> & Pick<Required<ExportedHandler<Env, unknown, unknown, Props>>, 'fetch'>;
+type WorkerEntrypointWithFetch<Env = Cloudflare.Env, Props = {}> = WorkerEntrypoint<Env, Props> & {
   fetch: NonNullable<WorkerEntrypoint['fetch']>;
 };
 /**
@@ -382,16 +554,36 @@ interface TokenExchangeCallbackResult {
   /**
    * 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. If returned during
-   * refresh token exchange, it will be ignored.
+   * 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`.
    */
   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.
+   *
+   * 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
+   * the credentials it proxies. Must be an integer of at least 60 seconds.
+   */
+  refreshTokenIdleTTL?: number;
   /**
    * Optional scopes for the new access token. Values outside the scope ceiling
    * for the current grant flow are ignored. If omitted, the effective requested
    * scopes are used.
    */
   accessTokenScope?: string[];
+  /**
+   * Permit a token exchange whose authenticated client differs from the client the
+   * subject token's grant was issued to. Cross-client exchange is rejected with
+   * `invalid_request` unless the callback returns `true` here, so impersonation
+   * across clients is always a deliberate policy decision.
+   */
+  allowCrossClientExchange?: boolean;
 }
 /**
  * Options for token exchange callback functions
@@ -402,9 +594,17 @@ interface TokenExchangeCallbackOptions {
    */
   grantType: GrantType;
   /**
-   * Client that received this grant
+   * Client authenticated on this token request. For `authorization_code` and
+   * `refresh_token` it is always the grant's client. For token exchange it is the
+   * exchanging client, which may differ from {@link subjectClientId}.
    */
   clientId: string;
+  /**
+   * Client the underlying grant was issued to. Equal to `clientId` except during a
+   * cross-client token exchange, which the callback must explicitly allow with
+   * {@link TokenExchangeCallbackResult.allowCrossClientExchange}.
+   */
+  subjectClientId: string;
   /**
    * User who authorized this grant
    */
@@ -425,6 +625,8 @@ interface TokenExchangeCallbackOptions {
    * Effective scopes selected for this token before applying the callback result.
    */
   requestedScope: string[];
+  /** Canonical protected resource selected for this grant and token. */
+  resource: string;
   /**
    * Application-specific properties currently associated with this grant
    */
@@ -504,11 +706,40 @@ interface ResolveExternalTokenResult {
    *
    * A JWT may carry this value as an `aud` claim. For an opaque API token or
    * PAT, the callback can supply the local resource URI as policy after
-   * successful validation. When `resourceMetadata.resource` is configured,
-   * this value is required and must match it exactly.
+   * successful validation. This value is required and must identify the
+   * configured canonical `resourceMetadata.resource`: ASCII case in the scheme
+   * and host is folded and an empty path equals `/`, while port, path, query,
+   * and trailing slash are compared exactly.
    */
-  audience?: string | string[];
+  audience: string;
 }
+/** RFC 9728 metadata owned by one protected resource server. */
+interface OAuthProtectedResourceMetadata {
+  /**
+   * The protected resource identifier HTTPS URL (RFC 9728 `resource` field).
+   * Configure an RFC 3986-safe HTTPS producer URL with lowercase scheme/host
+   * and no userinfo, default port, fragment, or dot segments.
+   */
+  resource: string;
+  /**
+   * Authorization server issuers that can issue tokens for this resource.
+   * In the legacy combined configuration this defaults to the token endpoint
+   * origin. In the role-based configuration it defaults to the configured AS
+   * issuer.
+   */
+  authorization_servers?: string[];
+  /** Minimal scopes required for basic protected-resource functionality. */
+  scopes_supported?: string[];
+  /** Methods by which bearer tokens can be presented. Defaults to `["header"]`. */
+  bearer_methods_supported?: string[];
+  /** Human-readable name for this resource. */
+  resource_name?: string;
+}
+/**
+ * Existing combined authorization-server and protected-resource configuration.
+ * This shape remains supported in 1.0 and is normalized to a one-resource
+ * role-based provider internally.
+ */
 interface OAuthProviderOptions<Env = Cloudflare.Env> {
   /**
    * URL(s) for API routes. Requests with URLs starting with any of these prefixes
@@ -572,6 +803,18 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * For example: 3600 = 1 hour, 2592000 = 30 days
    */
   refreshTokenTTL?: number;
+  /**
+   * Idle lifetime for refresh tokens in seconds. When set, every successful refresh
+   * moves the grant's expiry to this many seconds after the refresh, so a grant lives
+   * for as long as the client keeps using it and expires once it has been idle for
+   * this long. `refreshTokenTTL` still sets the lifetime of a new grant, and
+   * `tokenExchangeCallback` can override the idle lifetime per refresh by returning
+   * `refreshTokenIdleTTL`. Must be an integer of at least 60 seconds.
+   *
+   * Leave unset for a fixed lifetime, where a grant expires `refreshTokenTTL` seconds
+   * after the code exchange however often it is refreshed.
+   */
+  refreshTokenIdleTTL?: number;
   /**
    * Time-to-live for dynamically registered clients in seconds.
    * Defaults to 90 days (7,776,000 seconds).
@@ -655,10 +898,10 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    *
    * If the function returns a Response, that will be used in place of the OAuthProvider's default one.
    *
-   * `internal` (when present) carries a tagged, server-side-only reason that the library
-   * deliberately did NOT put on the wire — used for richer diagnostics where the public
-   * response must stay generic (e.g. JWT validation failures on the EMA path). Backwards
-   * compatible: existing callbacks ignoring this field continue to work unchanged.
+   * `internal` carries the stable, server-side-only reason for the error — often more
+   * specific than what the wire deliberately reveals (RFC 6749 §5.2), e.g. which refresh-token
+   * check failed or which EMA validation fired. It is never placed on the wire. See
+   * {@link OAuthErrorInternal}.
    *
    * `request` (when present) is the HTTP request that produced the error response, so the
    * callback can correlate the error with per-request state such as request-keyed telemetry.
@@ -670,11 +913,7 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
     description: string;
     status: number;
     headers: Record<string, string>;
-    internal?: {
-      category: string;
-      reason: string;
-      detail?: unknown;
-    };
+    internal: OAuthErrorInternal;
     request?: Request;
   }) => Response | void;
   /**
@@ -685,59 +924,58 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    */
   clientIdMetadataDocumentEnabled?: boolean;
   /**
-   * When true, requested-vs-granted resource validation compares origins only
-   * (scheme + host + port) instead of exact URIs. This allows an origin-only
-   * grant such as `https://server.com` to accept `https://server.com/mcp`, but
-   * also ignores path and query differences. Configured canonical resources
-   * always use exact matching.
-   *
-   * Defaults to false (strict exact matching per RFC 8707).
-   *
-   * @deprecated This comparison is unsafe for shared-origin multi-path or
-   * multi-tenant deployments. Prefer configuring `resourceMetadata.resource`.
+   * 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-`.
    */
-  resourceMatchOriginOnly?: boolean;
+  cookiePrefix?: string;
   /**
-   * Optional metadata for RFC 9728 OAuth 2.0 Protected Resource Metadata.
+   * Metadata for RFC 9728 OAuth 2.0 Protected Resource Metadata.
    * Controls the response served at /.well-known/oauth-protected-resource.
-   *
-   * If not provided, the endpoint will be automatically generated using the request origin
-   * as the resource identifier, and the token endpoint's origin as the authorization server.
    */
-  resourceMetadata?: {
-    /**
-     * The protected resource identifier URL (RFC 9728 `resource` field).
-     *
-     * Configuring this value pins grants and access-token audiences to this
-     * exact resource. An omitted authorization resource defaults to this value,
-     * and an omitted token-request resource inherits it from the grant. Without
-     * configuration, explicit RFC 8707 resource indicators are accepted and
-     * omission remains unbound for backwards compatibility.
-     */
-    resource?: string;
-    /**
-     * List of authorization server issuer URLs that can issue tokens for this resource.
-     * If not set, defaults to the token endpoint's origin (consistent with the issuer
-     * in authorization server metadata).
-     */
-    authorization_servers?: string[];
-    /**
-     * Minimal scopes required for basic protected resource functionality.
-     * These scopes are advertised in Protected Resource Metadata and used as
-     * baseline bearer challenge guidance. `offline_access` is omitted because
-     * refresh-token issuance is an authorization server capability.
-     */
-    scopes_supported?: string[];
-    /**
-     * Methods by which bearer tokens can be presented to this resource.
-     * Defaults to ["header"].
-     */
-    bearer_methods_supported?: string[];
-    /**
-     * Human-readable name for this resource.
-     */
-    resource_name?: string;
-  };
+  resourceMetadata: OAuthProtectedResourceMetadata;
+}
+/**
+ * Functional authorization-server surface for the role-based API.
+ * The application owns the interactive authorization route and uses
+ * `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'> & {
+  /** Canonical RFC 8414 issuer. */
+  issuer: string;
+  /**
+   * Canonical identifiers of every protected resource this authorization server issues
+   * tokens for, whether hosted in this Worker through `OAuthResourceServer` or by another
+   * Worker or service. At least one is required. The registry is fixed at construction,
+   * so `defaultResource` and `legacyGrantResource` are checked before the first request,
+   * and `validateToken()` rejects for a resource that is not listed.
+   */
+  resources: readonly string[];
+  /** Resource selected for a new authorization request that omits `resource`. */
+  defaultResource?: string;
+  /**
+   * Migration destination for pre-resource grants and access tokens. Changing it
+   * re-targets every surviving unbound record, so keep it fixed for the migration window.
+   */
+  legacyGrantResource?: string;
+};
+/** Audience-checked token context suitable for a private Service Binding. */
+interface ValidatedAccessToken<T = any> {
+  props: T;
+  audience: string;
+  expiresAt: number;
+  scope: string[];
+  userId: string;
+  clientId: string;
+}
+/**
+ * The RPC surface a `WorkerEntrypoint` exposes around {@link OAuthAuthorizationServer.validateToken},
+ * as a resource Worker sees it through a Service Binding. Hand a resource server the bound
+ * method as its validator: `validateToken: (env) => env.AUTH_SERVER.validateToken`.
+ */
+interface AuthorizationServerBinding<Props = any> {
+  validateToken(resource: string, token: string): Promise<ValidatedAccessToken<Props> | null>;
 }
 /**
  * Helper methods for OAuth operations provided to handler functions
@@ -768,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
@@ -852,9 +1137,11 @@ interface ExchangeTokenOptions {
    */
   scope?: string[];
   /**
-   * Optional target audience/resource for the new token (maps to resource parameter per RFC 8707)
+   * Optional canonical target audience/resource for the new token (maps to the
+   * resource parameter per RFC 8707). When present, it must match the
+   * provider's configured resource.
    */
-  aud?: string | string[];
+  aud?: string;
   /**
    * Optional TTL override for the new token in seconds (must not exceed subject token's remaining lifetime)
    */
@@ -893,9 +1180,10 @@ interface AuthRequest {
    */
   codeChallengeMethod?: string;
   /**
-   * Resource parameter indicating target resource(s) (RFC 8707)
+   * Canonical target resource (RFC 8707). Parsed authorization requests
+   * always contain the provider's configured resource.
    */
-  resource?: string | string[];
+  resource?: string;
   /**
    * Authorization server issuer recorded while parsing this request.
    * Include it as `iss` in successful and error authorization responses.
@@ -1015,10 +1303,12 @@ interface CompleteAuthorizationOptions {
    */
   revokeExistingGrants?: boolean;
   /**
-   * Maximum number of grants to fetch per page when revoking existing
-   * grants. Only used when revokeExistingGrants is not false.
-   * Must be a positive integer. Values above Cloudflare KV's 1000-key page
-   * limit are clamped to 1000. Defaults to 50.
+   * 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;
 }
@@ -1125,7 +1415,7 @@ interface TokenResponse {
    * Resource indicator(s) for the issued access token (RFC 8707 Section 2.2)
    * SHOULD be included to indicate the resource server(s) for which the token is valid
    */
-  resource?: string | string[];
+  resource: string;
 }
 /**
  * Shared fields for Token and TokenSummary
@@ -1328,6 +1618,8 @@ interface GrantSummary {
    * grants created before this field was introduced.
    */
   redirectUri?: string;
+  /** Canonical protected resource, absent only on a pre-resource legacy grant. */
+  resource?: string | string[];
 }
 /**
  * OAuth 2.0 Provider implementation for Cloudflare Workers
@@ -1360,6 +1652,43 @@ declare class OAuthProvider<Env = Cloudflare.Env> {
    */
   purgeExpiredData(env: Env, options?: PurgeOptions): Promise<PurgeResult>;
 }
+/**
+ * The authorization-server role on its own. It serves discovery, token, revocation and
+ * registration endpoints from `fetch()`, exposes the interactive authorization flow through
+ * `getOAuthApi()`, and validates its access tokens for any declared resource through
+ * `validateToken()`. Resources are hosted, in this Worker or another, by
+ * `OAuthResourceServer`, whose `validateToken` points back here.
+ */
+declare class OAuthAuthorizationServer<Env = Cloudflare.Env> {
+  #private;
+  constructor(options: OAuthAuthorizationServerOptions<Env>);
+  /**
+   * Validate an access token for one declared resource: the token's KV record is loaded, its
+   * audience checked against `resource`, and its props decrypted. Resolves `null` for a token
+   * that is not valid for that resource, and rejects for a resource this server does not
+   * declare.
+   *
+   * This is what a resource server calls, whether it shares this Worker or reaches it over a
+   * Service Binding. For the latter, expose it from a `WorkerEntrypoint`:
+   *
+   * ```ts
+   * 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);
+   *   }
+   * }
+   * ```
+   */
+  validateToken<T = any>(resource: string, token: string, env: Env): Promise<ValidatedAccessToken<T> | null>;
+  /** Serve protocol-owned authorization-server endpoints, excluding the application authorization UI. */
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+  /** Obtain helpers for scheduled jobs or custom code outside a fetch dispatch. */
+  getOAuthApi(env: Env): OAuthHelpers;
+  purgeExpiredData(env: Env, options?: PurgeOptions): Promise<PurgeResult>;
+}
 /**
  * Gets OAuthHelpers for the given environment
  * @param options - Configuration options for the OAuth provider
@@ -1371,6 +1700,24 @@ 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.
  */
@@ -1392,6 +1739,13 @@ interface OAuthErrorOptions {
    * 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.
@@ -1418,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) {
@@ -1523,18 +1878,6 @@ declare class CimdFetchError extends Error {
    */
   constructor(metadataUrl: string, cause: unknown);
 }
-/**
- * Validates a resource URI per RFC 8707 Section 2
- * @param uri - The URI string to validate
- * @returns true if valid, false otherwise
- */
-declare function validateResourceUri(uri: string): boolean;
-/**
- * Checks if a requested resource matches a granted resource.
- * When originOnly is true, compares only the origin (scheme + host + port),
- * allowing path-aware resources to match origin-only grants.
- */
-declare function resourceMatches(requested: string, granted: string, originOnly: boolean): boolean;
 /**
  * Decodes a base64url-encoded string to bytes.
  */
@@ -1551,4 +1894,4 @@ declare function getJwtCryptoAlgorithms(alg: string): {
   verifyAlgorithm: Parameters<SubtleCrypto['verify']>[0];
 };
 //#endregion
-export { AuthRequest, AuthorizationError, type AuthorizationErrorCode, type AuthorizationErrorOptions, 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, OAuthError, OAuthErrorOptions, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthTokenErrorCode, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, base64UrlToBytes, getJwtCryptoAlgorithms, getOAuthApi, 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 };