@cloudflare/workers-oauth-provider 0.2.2 → 0.2.4

package/README.md

@@ -81,6 +81,12 @@ export default new OAuthProvider({
   // Defaults to false.
   allowImplicitFlow: false,
 
+  // Optional: Controls whether the plain PKCE code_challenge_method is allowed.
+  // OAuth 2.1 recommends using S256 exclusively as plain offers no cryptographic protection.
+  // When false, only S256 is accepted and advertised in the metadata endpoint.
+  // Defaults to true for backward compatibility.
+  allowPlainPKCE: true,
+
   // Optional: Controls whether public clients (clients without a secret, like SPAs)
   // can register via the dynamic client registration endpoint.
   // When true, only confidential clients can register.
@@ -304,6 +310,18 @@ new OAuthProvider({
 
 By default, the `onError` callback is set to ``({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`)``.
 
+## Standards Compliance
+
+This library implements the following OAuth and MCP specifications:
+
+- [OAuth 2.1 (draft-ietf-oauth-v2-1-13)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13) — Core authorization framework with PKCE
+- [OAuth 2.0 Authorization Server Metadata (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414) — `/.well-known/oauth-authorization-server` discovery endpoint
+- [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728) — `/.well-known/oauth-protected-resource` discovery endpoint
+- [OAuth 2.0 Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — Dynamic client registration endpoint
+- [OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document) — HTTPS URLs as client IDs
+
+These are the specifications required by the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+
 ## Implementation Notes
 
 ### End-to-end encryption

package/dist/oauth-provider.d.ts

@@ -2,11 +2,21 @@ import { WorkerEntrypoint } from "cloudflare:workers";
 
 //#region src/oauth-provider.d.ts
 
+/**
+ * Enum representing OAuth grant types
+ */
+declare enum GrantType {
+  AUTHORIZATION_CODE = "authorization_code",
+  REFRESH_TOKEN = "refresh_token",
+  TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange",
+}
 /**
  * Aliases for either type of Handler that makes .fetch required
  */
-type ExportedHandlerWithFetch = ExportedHandler & Pick<Required<ExportedHandler>, 'fetch'>;
-type WorkerEntrypointWithFetch = WorkerEntrypoint & Pick<Required<WorkerEntrypoint>, 'fetch'>;
+type ExportedHandlerWithFetch<Env = Cloudflare.Env> = ExportedHandler<Env> & Pick<Required<ExportedHandler<Env>>, 'fetch'>;
+type WorkerEntrypointWithFetch<Env = Cloudflare.Env> = WorkerEntrypoint<Env> & {
+  fetch: NonNullable<WorkerEntrypoint['fetch']>;
+};
 /**
  * Configuration options for the OAuth Provider
  */
@@ -42,6 +52,11 @@ interface TokenExchangeCallbackResult {
    * refresh token exchange, it will be ignored.
    */
   refreshTokenTTL?: number;
+  /**
+   * List of scopes authorized for the new access token
+   * (If undefined, the granted scopes will be used)
+   */
+  accessTokenScope?: string[];
 }
 /**
  * Options for token exchange callback functions
@@ -49,10 +64,8 @@ interface TokenExchangeCallbackResult {
 interface TokenExchangeCallbackOptions {
   /**
    * The type of grant being processed.
-   * 'authorization_code' for initial code exchange,
-   * 'refresh_token' for refresh token exchange.
    */
-  grantType: 'authorization_code' | 'refresh_token';
+  grantType: GrantType;
   /**
    * Client that received this grant
    */
@@ -65,6 +78,11 @@ interface TokenExchangeCallbackOptions {
    * List of scopes that were granted
    */
   scope: string[];
+  /**
+   * List of scopes that were requested for this token by the client
+   * (Will be the same as granted scopes unless client specifically requested a downscoping)
+   */
+  requestedScope: string[];
   /**
    * Application-specific properties currently associated with this grant
    */
@@ -103,7 +121,7 @@ interface ResolveExternalTokenResult {
    */
   audience?: string | string[];
 }
-interface OAuthProviderOptions {
+interface OAuthProviderOptions<Env = Cloudflare.Env> {
   /**
    * URL(s) for API routes. Requests with URLs starting with any of these prefixes
    * will be treated as API requests and require a valid access token.
@@ -121,7 +139,7 @@ interface OAuthProviderOptions {
    * Used with `apiRoute` for the single-handler configuration. This is incompatible with
    * the `apiHandlers` property. You must use either `apiRoute` + `apiHandler` OR `apiHandlers`, not both.
    */
-  apiHandler?: ExportedHandlerWithFetch | (new (ctx: ExecutionContext, env: any) => WorkerEntrypointWithFetch);
+  apiHandler?: ExportedHandlerWithFetch<Env> | (new (ctx: ExecutionContext, env: Env) => WorkerEntrypointWithFetch<Env>);
   /**
    * Map of API routes to their corresponding handlers for the multi-handler configuration.
    * The keys are the API routes (strings only, not arrays), and the values are the handlers.
@@ -132,12 +150,12 @@ interface OAuthProviderOptions {
    * `apiRoute` + `apiHandler` (single-handler configuration) OR `apiHandlers` (multi-handler
    * configuration), not both.
    */
-  apiHandlers?: Record<string, ExportedHandlerWithFetch | (new (ctx: ExecutionContext, env: any) => WorkerEntrypointWithFetch)>;
+  apiHandlers?: Record<string, ExportedHandlerWithFetch<Env> | (new (ctx: ExecutionContext, env: Env) => WorkerEntrypointWithFetch<Env>)>;
   /**
    * Handler for all non-API requests or API requests without a valid token.
    * Can be either an ExportedHandler object with a fetch method or a class extending WorkerEntrypoint.
    */
-  defaultHandler: ExportedHandler | (new (ctx: ExecutionContext, env: any) => WorkerEntrypointWithFetch);
+  defaultHandler: ExportedHandler<Env> | (new (ctx: ExecutionContext, env: Env) => WorkerEntrypointWithFetch<Env>);
   /**
    * URL of the OAuth authorization endpoint where users can grant permissions.
    * This URL is used in OAuth metadata and is not handled by the provider itself.
@@ -175,6 +193,20 @@ interface OAuthProviderOptions {
    * Defaults to false.
    */
   allowImplicitFlow?: boolean;
+  /**
+   * Controls whether the plain PKCE method is allowed.
+   * OAuth 2.1 recommends using S256 exclusively as plain offers no cryptographic protection.
+   * When set to false, only the S256 code_challenge_method will be accepted.
+   * Defaults to true for backward compatibility.
+   */
+  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
+   * and token exchange requests will be rejected.
+   * Defaults to false.
+   */
+  allowTokenExchangeGrant?: boolean;
   /**
    * Controls whether public clients (clients without a secret, like SPAs) can register via the
    * dynamic client registration endpoint. When true, only confidential clients can register.
@@ -214,6 +246,40 @@ interface OAuthProviderOptions {
     status: number;
     headers: Record<string, string>;
   }) => Response | void;
+  /**
+   * Optional 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).
+     * If not set, defaults to the request URL's origin.
+     */
+    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[];
+    /**
+     * Scopes supported by this protected resource.
+     * If not set, falls back to the top-level scopesSupported option.
+     */
+    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;
+  };
 }
 /**
  * Helper methods for OAuth operations provided to handler functions
@@ -285,6 +351,34 @@ interface OAuthHelpers {
    * @returns Promise resolving to token data with decrypted props, or null if token is invalid
    */
   unwrapToken<T = any>(token: string): Promise<TokenSummary<T> | null>;
+  /**
+   * Exchanges an existing access token for a new one with modified characteristics
+   * Implements OAuth 2.0 Token Exchange (RFC 8693)
+   * @param options - Options for token exchange including subject token and optional modifications
+   * @returns Promise resolving to token response with new access token
+   */
+  exchangeToken(options: ExchangeTokenOptions): Promise<TokenResponse>;
+}
+/**
+ * Options for token exchange operations (RFC 8693)
+ */
+interface ExchangeTokenOptions {
+  /**
+   * The subject token to exchange (existing access token)
+   */
+  subjectToken: string;
+  /**
+   * Optional narrowed set of scopes for the new token (must be subset of original grant scopes)
+   */
+  scope?: string[];
+  /**
+   * Optional target audience/resource for the new token (maps to resource parameter per RFC 8707)
+   */
+  aud?: string | string[];
+  /**
+   * Optional TTL override for the new token in seconds (must not exceed subject token's remaining lifetime)
+   */
+  expiresIn?: number;
 }
 /**
  * Parsed OAuth authorization request parameters
@@ -496,6 +590,22 @@ interface Grant {
    */
   resource?: string | string[];
 }
+/**
+ * OAuth 2.0 Token Response
+ * The response returned when exchanging authorization codes or refresh tokens
+ */
+interface TokenResponse {
+  access_token: string;
+  token_type: 'bearer';
+  expires_in: number;
+  refresh_token?: string;
+  scope: string;
+  /**
+   * 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[];
+}
 /**
  * Shared fields for Token and TokenSummary
  */
@@ -525,6 +635,10 @@ interface TokenBase {
    * Can be a single string or array of strings
    */
   audience?: string | string[];
+  /**
+   * List of scopes on this token
+   */
+  scope: string[];
 }
 /**
  * Token record stored in KV
@@ -643,13 +757,13 @@ interface GrantSummary {
  * Implements authorization code flow with support for refresh tokens
  * and dynamic client registration.
  */
-declare class OAuthProvider {
+declare class OAuthProvider<Env = Cloudflare.Env> {
   #private;
   /**
    * Creates a new OAuth provider instance
    * @param options - Configuration options for the provider
    */
-  constructor(options: OAuthProviderOptions);
+  constructor(options: OAuthProviderOptions<Env>);
   /**
    * Main fetch handler for the Worker
    * Routes requests to the appropriate handler based on the URL
@@ -658,7 +772,14 @@ declare class OAuthProvider {
    * @param ctx - Cloudflare Worker execution context
    * @returns A Promise resolving to an HTTP Response
    */
-  fetch(request: Request, env: any, ctx: ExecutionContext): Promise<Response>;
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
 }
+/**
+ * Gets OAuthHelpers for the given environment
+ * @param options - Configuration options for the OAuth provider
+ * @param env - Cloudflare Worker environment variables
+ * @returns An instance of OAuthHelpers
+ */
+declare function getOAuthApi<Env = Cloudflare.Env>(options: OAuthProviderOptions<Env>, env: Env): OAuthHelpers;
 //#endregion
-export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, Grant, GrantSummary, ListOptions, ListResult, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary };
+export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, getOAuthApi };

package/dist/oauth-provider.js

@@ -11,6 +11,15 @@ var HandlerType = /* @__PURE__ */ function(HandlerType$1) {
 	return HandlerType$1;
 }(HandlerType || {});
 /**
+* Enum representing OAuth grant types
+*/
+let GrantType = /* @__PURE__ */ function(GrantType$1) {
+	GrantType$1["AUTHORIZATION_CODE"] = "authorization_code";
+	GrantType$1["REFRESH_TOKEN"] = "refresh_token";
+	GrantType$1["TOKEN_EXCHANGE"] = "urn:ietf:params:oauth:grant-type:token-exchange";
+	return GrantType$1;
+}({});
+/**
 * OAuth 2.0 Provider implementation for Cloudflare Workers
 * Implements authorization code flow with support for refresh tokens
 * and dynamic client registration.
@@ -37,6 +46,15 @@ var OAuthProvider = class {
 	}
 };
 /**
+* Gets OAuthHelpers for the given environment
+* @param options - Configuration options for the OAuth provider
+* @param env - Cloudflare Worker environment variables
+* @returns An instance of OAuthHelpers
+*/
+function getOAuthApi(options, env) {
+	return new OAuthProviderImpl(options).createOAuthHelpers(env);
+}
+/**
 * Implementation class backing OAuthProvider.
 *
 * We use a PImpl pattern in `OAuthProvider` to make sure we don't inadvertently export any private
@@ -123,7 +141,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	async fetch(request, env, ctx) {
 		const url = new URL(request.url);
 		if (request.method === "OPTIONS") {
-			if (this.isApiRequest(url) || url.pathname === "/.well-known/oauth-authorization-server" || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
+			if (this.isApiRequest(url) || url.pathname === "/.well-known/oauth-authorization-server" || url.pathname === "/.well-known/oauth-protected-resource" || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
 				status: 204,
 				headers: { "Content-Length": "0" }
 			}), request);
@@ -132,6 +150,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const response = await this.handleMetadataDiscovery(url);
 			return this.addCorsHeaders(response, request);
 		}
+		if (url.pathname === "/.well-known/oauth-protected-resource") {
+			const response = this.handleProtectedResourceMetadata(url);
+			return this.addCorsHeaders(response, request);
+		}
 		if (this.isTokenEndpoint(url)) {
 			const parsed = await this.parseTokenEndpointRequest(request, env);
 			if (parsed instanceof Response) return this.addCorsHeaders(parsed, request);
@@ -176,6 +198,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			createdAt: tokenData.createdAt,
 			expiresAt: tokenData.expiresAt,
 			audience: tokenData.audience,
+			scope: tokenData.scope || grant.scope,
 			grant: {
 				clientId: grant.clientId,
 				scope: grant.scope,
@@ -268,8 +291,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns True if the URL matches the API route
 	*/
 	matchApiRoute(url, route) {
-		if (this.isPath(route)) return url.pathname.startsWith(route);
-		else {
+		if (this.isPath(route)) {
+			if (route === "/") return url.pathname === "/";
+			return url.pathname.startsWith(route);
+		} else {
 			const apiUrl = new URL(route);
 			return url.hostname === apiUrl.hostname && url.pathname.startsWith(apiUrl.pathname);
 		}
@@ -331,6 +356,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (this.options.clientRegistrationEndpoint) registrationEndpoint = this.getFullEndpointUrl(this.options.clientRegistrationEndpoint, requestUrl);
 		const responseTypesSupported = ["code"];
 		if (this.options.allowImplicitFlow) responseTypesSupported.push("token");
+		const grantTypesSupported = [GrantType.AUTHORIZATION_CODE, GrantType.REFRESH_TOKEN];
+		if (this.options.allowTokenExchangeGrant) grantTypesSupported.push(GrantType.TOKEN_EXCHANGE);
 		const metadata = {
 			issuer: new URL(tokenEndpoint).origin,
 			authorization_endpoint: authorizeEndpoint,
@@ -339,19 +366,38 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			scopes_supported: this.options.scopesSupported,
 			response_types_supported: responseTypesSupported,
 			response_modes_supported: ["query"],
-			grant_types_supported: ["authorization_code", "refresh_token"],
+			grant_types_supported: grantTypesSupported,
 			token_endpoint_auth_methods_supported: [
 				"client_secret_basic",
 				"client_secret_post",
 				"none"
 			],
 			revocation_endpoint: tokenEndpoint,
-			code_challenge_methods_supported: ["plain", "S256"],
+			code_challenge_methods_supported: this.options.allowPlainPKCE !== false ? ["plain", "S256"] : ["S256"],
 			client_id_metadata_document_supported: this.hasGlobalFetchStrictlyPublic()
 		};
 		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
 	}
 	/**
+	* Handles the OAuth Protected Resource Metadata endpoint
+	* Implements RFC 9728 for OAuth Protected Resource Metadata
+	* @param requestUrl - The URL of the incoming request
+	* @returns Response with protected resource metadata
+	*/
+	handleProtectedResourceMetadata(requestUrl) {
+		const rm = this.options.resourceMetadata;
+		const tokenEndpointUrl = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
+		const authServerOrigin = new URL(tokenEndpointUrl).origin;
+		const metadata = {
+			resource: rm?.resource ?? requestUrl.origin,
+			authorization_servers: rm?.authorization_servers ?? [authServerOrigin],
+			scopes_supported: rm?.scopes_supported ?? this.options.scopesSupported,
+			bearer_methods_supported: rm?.bearer_methods_supported ?? ["header"]
+		};
+		if (rm?.resource_name) metadata.resource_name = rm.resource_name;
+		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
+	}
+	/**
 	* Handles client authentication and token issuance via the token endpoint
 	* Supports authorization_code and refresh_token grant types
 	* @param body - The parsed request body
@@ -361,8 +407,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async handleTokenRequest(body, clientInfo, env) {
 		const grantType = body.grant_type;
-		if (grantType === "authorization_code") return this.handleAuthorizationCodeGrant(body, clientInfo, env);
-		else if (grantType === "refresh_token") return this.handleRefreshTokenGrant(body, clientInfo, env);
+		if (grantType === GrantType.AUTHORIZATION_CODE) return this.handleAuthorizationCodeGrant(body, clientInfo, env);
+		else if (grantType === GrantType.REFRESH_TOKEN) return this.handleRefreshTokenGrant(body, clientInfo, env);
+		else if (grantType === GrantType.TOKEN_EXCHANGE && this.options.allowTokenExchangeGrant) return this.handleTokenExchangeGrant(body, clientInfo, env);
 		else return this.createErrorResponse("unsupported_grant_type", "Grant type not supported");
 	}
 	/**
@@ -389,7 +436,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", "Client ID mismatch");
 		const isPkceEnabled = !!grantData.codeChallenge;
 		if (!redirectUri && !isPkceEnabled) return this.createErrorResponse("invalid_request", "redirect_uri is required when not using PKCE");
-		if (redirectUri && !clientInfo.redirectUris.includes(redirectUri)) return this.createErrorResponse("invalid_grant", "Invalid redirect URI");
+		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", "Invalid redirect URI");
 		if (!isPkceEnabled && codeVerifier) return this.createErrorResponse("invalid_request", "code_verifier provided for a flow that did not use PKCE");
 		if (isPkceEnabled) {
 			if (!codeVerifier) return this.createErrorResponse("invalid_request", "code_verifier is required for PKCE");
@@ -402,23 +449,23 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			} else calculatedChallenge = codeVerifier;
 			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", "Invalid PKCE code_verifier");
 		}
-		const accessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
-		const accessTokenId = await generateTokenId(accessToken);
 		let accessTokenTTL = this.options.accessTokenTTL;
 		let refreshTokenTTL = this.options.refreshTokenTTL;
 		const encryptionKey = await unwrapKeyWithToken(code, grantData.authCodeWrappedKey);
 		let grantEncryptionKey = encryptionKey;
 		let accessTokenEncryptionKey = encryptionKey;
 		let encryptedAccessTokenProps = grantData.encryptedProps;
+		let tokenScopes = this.downscope(body.scope, grantData.scope);
 		if (this.options.tokenExchangeCallback) {
 			const decryptedProps = await decryptProps(encryptionKey, grantData.encryptedProps);
 			let grantProps = decryptedProps;
 			let accessTokenProps = decryptedProps;
 			const callbackOptions = {
-				grantType: "authorization_code",
+				grantType: GrantType.AUTHORIZATION_CODE,
 				clientId: clientInfo.clientId,
 				userId,
 				scope: grantData.scope,
+				requestedScope: tokenScopes,
 				props: decryptedProps
 			};
 			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
@@ -430,6 +477,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
 				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = callbackResult.accessTokenTTL;
 				if ("refreshTokenTTL" in callbackResult) refreshTokenTTL = callbackResult.refreshTokenTTL;
+				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 			const grantResult = await encryptProps(grantProps);
 			grantData.encryptedProps = grantResult.encryptedData;
@@ -444,9 +492,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			}
 		}
 		const now = Math.floor(Date.now() / 1e3);
-		const accessTokenExpiresAt = now + accessTokenTTL;
 		const useRefreshToken = refreshTokenTTL !== 0;
-		const accessTokenWrappedKey = await wrapKeyWithToken(accessToken, accessTokenEncryptionKey);
 		delete grantData.authCodeId;
 		delete grantData.codeChallenge;
 		delete grantData.codeChallengeMethod;
@@ -471,26 +517,21 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		const audience = parseResourceParameter(body.resource || grantData.resource);
 		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", "The resource parameter must be a valid absolute URI without a fragment");
-		const accessTokenData = {
-			id: accessTokenId,
-			grantId,
-			userId,
-			createdAt: now,
-			expiresAt: accessTokenExpiresAt,
-			audience,
-			wrappedEncryptionKey: accessTokenWrappedKey,
-			grant: {
-				clientId: grantData.clientId,
-				scope: grantData.scope,
-				encryptedProps: encryptedAccessTokenProps
-			}
-		};
-		await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: accessTokenTTL });
 		const tokenResponse = {
-			access_token: accessToken,
+			access_token: await this.createAccessToken({
+				userId,
+				grantId,
+				clientId: grantData.clientId,
+				scope: tokenScopes,
+				encryptedProps: encryptedAccessTokenProps,
+				encryptionKey: accessTokenEncryptionKey,
+				expiresIn: accessTokenTTL,
+				audience,
+				env
+			}),
 			token_type: "bearer",
 			expires_in: accessTokenTTL,
-			scope: grantData.scope.join(" ")
+			scope: tokenScopes.join(" ")
 		};
 		if (refreshToken) tokenResponse.refresh_token = refreshToken;
 		if (audience) tokenResponse.resource = audience;
@@ -531,16 +572,18 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		let grantEncryptionKey = encryptionKey;
 		let accessTokenEncryptionKey = encryptionKey;
 		let encryptedAccessTokenProps = grantData.encryptedProps;
+		let tokenScopes = this.downscope(body.scope, grantData.scope);
 		let grantPropsChanged = false;
 		if (this.options.tokenExchangeCallback) {
 			const decryptedProps = await decryptProps(encryptionKey, grantData.encryptedProps);
 			let grantProps = decryptedProps;
 			let accessTokenProps = decryptedProps;
 			const callbackOptions = {
-				grantType: "refresh_token",
+				grantType: GrantType.REFRESH_TOKEN,
 				clientId: clientInfo.clientId,
 				userId,
 				scope: grantData.scope,
+				requestedScope: tokenScopes,
 				props: decryptedProps
 			};
 			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
@@ -553,6 +596,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
 				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = callbackResult.accessTokenTTL;
 				if ("refreshTokenTTL" in callbackResult) return this.createErrorResponse("invalid_request", "refreshTokenTTL cannot be changed during refresh token exchange");
+				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 			if (grantPropsChanged) {
 				const grantResult = await encryptProps(grantProps);
@@ -600,6 +644,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			createdAt: now,
 			expiresAt: accessTokenExpiresAt,
 			audience,
+			scope: tokenScopes,
 			wrappedEncryptionKey: accessTokenWrappedKey,
 			grant: {
 				clientId: grantData.clientId,
@@ -613,12 +658,139 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			token_type: "bearer",
 			expires_in: accessTokenTTL,
 			refresh_token: newRefreshToken,
-			scope: grantData.scope.join(" ")
+			scope: tokenScopes.join(" ")
 		};
 		if (audience) tokenResponse.resource = audience;
 		return new Response(JSON.stringify(tokenResponse), { headers: { "Content-Type": "application/json" } });
 	}
 	/**
+	* Core token exchange logic (RFC 8693)
+	* Performs the actual token exchange operation
+	* This method is not private because `OAuthHelpers` needs to call it. Note that since
+	* `OAuthProviderImpl` is not exposed outside this module, this is still effectively
+	* module-private.
+	* @param subjectToken - The subject token to exchange
+	* @param requestedScopes - Optional narrowed scopes (must be subset of original)
+	* @param requestedResource - Optional resource/audience (must be subset of original if original had resource)
+	* @param expiresIn - Optional TTL override in seconds
+	* @param clientInfo - The client making the exchange request
+	* @param env - Cloudflare Worker environment variables
+	* @returns Promise resolving to token response
+	* @throws OAuthError with OAuth error code and description
+	*/
+	async exchangeToken(subjectToken, requestedScopes, requestedResource, expiresIn, clientInfo, env) {
+		const tokenSummary = await this.unwrapToken(subjectToken, env);
+		if (!tokenSummary) throw new OAuthError("invalid_grant", "Invalid or expired subject token");
+		const grantKey = `grant:${tokenSummary.userId}:${tokenSummary.grantId}`;
+		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
+		if (!grantData) throw new OAuthError("invalid_grant", "Grant not found");
+		let tokenScopes = this.downscope(requestedScopes, grantData.scope);
+		let newAudience = tokenSummary.audience;
+		if (requestedResource) {
+			if (grantData.resource) {
+				const requestedResources = Array.isArray(requestedResource) ? requestedResource : [requestedResource];
+				const grantedResources = Array.isArray(grantData.resource) ? grantData.resource : [grantData.resource];
+				for (const requested of requestedResources) if (!grantedResources.includes(requested)) throw new OAuthError("invalid_target", "Requested resource was not included in the authorization request");
+			}
+			const parsedResource = parseResourceParameter(requestedResource);
+			if (!parsedResource) throw new OAuthError("invalid_target", "The resource parameter must be a valid absolute URI without a fragment");
+			newAudience = parsedResource;
+		}
+		const now = Math.floor(Date.now() / 1e3);
+		const subjectTokenRemainingLifetime = tokenSummary.expiresAt - now;
+		let accessTokenTTL = this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL;
+		if (expiresIn !== void 0) {
+			if (expiresIn <= 0) throw new OAuthError("invalid_request", "Invalid expires_in parameter");
+			accessTokenTTL = Math.min(expiresIn, subjectTokenRemainingLifetime);
+		} else accessTokenTTL = Math.min(accessTokenTTL, subjectTokenRemainingLifetime);
+		const subjectTokenData = await env.OAUTH_KV.get(`token:${tokenSummary.userId}:${tokenSummary.grantId}:${tokenSummary.id}`, { type: "json" });
+		if (!subjectTokenData) throw new OAuthError("invalid_grant", "Subject token data not found");
+		const encryptionKey = await unwrapKeyWithToken(subjectToken, subjectTokenData.wrappedEncryptionKey);
+		let accessTokenEncryptionKey = encryptionKey;
+		let encryptedAccessTokenProps = subjectTokenData.grant.encryptedProps;
+		if (this.options.tokenExchangeCallback) {
+			const decryptedProps = await decryptProps(encryptionKey, subjectTokenData.grant.encryptedProps);
+			const callbackOptions = {
+				grantType: GrantType.TOKEN_EXCHANGE,
+				clientId: clientInfo.clientId,
+				userId: tokenSummary.userId,
+				scope: tokenSummary.grant.scope,
+				requestedScope: tokenScopes,
+				props: decryptedProps
+			};
+			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
+			if (callbackResult) {
+				let accessTokenProps = decryptedProps;
+				if (callbackResult.newProps) {
+					if (!callbackResult.accessTokenProps) accessTokenProps = callbackResult.newProps;
+				}
+				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
+				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = Math.min(callbackResult.accessTokenTTL, subjectTokenRemainingLifetime);
+				if (accessTokenProps !== decryptedProps) {
+					const tokenResult = await encryptProps(accessTokenProps);
+					encryptedAccessTokenProps = tokenResult.encryptedData;
+					accessTokenEncryptionKey = tokenResult.key;
+				}
+				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
+			}
+		}
+		const tokenResponse = {
+			access_token: await this.createAccessToken({
+				userId: tokenSummary.userId,
+				grantId: tokenSummary.grantId,
+				clientId: tokenSummary.grant.clientId,
+				scope: tokenScopes,
+				encryptedProps: encryptedAccessTokenProps,
+				encryptionKey: accessTokenEncryptionKey,
+				expiresIn: accessTokenTTL,
+				audience: newAudience,
+				env
+			}),
+			issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
+			token_type: "bearer",
+			expires_in: accessTokenTTL,
+			scope: tokenScopes.join(" ")
+		};
+		if (newAudience) tokenResponse.resource = newAudience;
+		return tokenResponse;
+	}
+	/**
+	* Handles OAuth 2.0 token exchange requests (RFC 8693)
+	* Exchanges an existing access token for a new one with modified characteristics
+	* @param body - The parsed request body
+	* @param clientInfo - The authenticated client information
+	* @param env - Cloudflare Worker environment variables
+	* @returns Response with new token data or error
+	*/
+	async handleTokenExchangeGrant(body, clientInfo, env) {
+		const subjectToken = body.subject_token;
+		const subjectTokenType = body.subject_token_type;
+		const requestedTokenType = body.requested_token_type || "urn:ietf:params:oauth:token-type:access_token";
+		const requestedScope = body.scope;
+		const requestedResource = body.resource;
+		if (!subjectToken) return this.createErrorResponse("invalid_request", "subject_token is required");
+		if (!subjectTokenType) return this.createErrorResponse("invalid_request", "subject_token_type is required");
+		if (subjectTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", "Only access_token subject_token_type is supported");
+		if (requestedTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", "Only access_token requested_token_type is supported");
+		let requestedScopes;
+		if (requestedScope) if (typeof requestedScope === "string") requestedScopes = requestedScope.split(" ").filter(Boolean);
+		else if (Array.isArray(requestedScope)) requestedScopes = requestedScope;
+		else return this.createErrorResponse("invalid_request", "Invalid scope parameter format");
+		let expiresIn;
+		if (body.expires_in !== void 0) {
+			const requestedTTL = parseInt(body.expires_in, 10);
+			if (isNaN(requestedTTL) || requestedTTL <= 0) return this.createErrorResponse("invalid_request", "Invalid expires_in parameter");
+			expiresIn = requestedTTL;
+		}
+		try {
+			const tokenResponse = await this.exchangeToken(subjectToken, requestedScopes, requestedResource, expiresIn, clientInfo, env);
+			return new Response(JSON.stringify(tokenResponse), { headers: { "Content-Type": "application/json" } });
+		} catch (error) {
+			if (error instanceof OAuthError) return this.createErrorResponse(error.code, error.message);
+			throw error;
+		}
+	}
+	/**
 	* Handles OAuth 2.0 token revocation requests (RFC 7009)
 	* @param body - The parsed request body containing revocation parameters
 	* @param env - Cloudflare Worker environment variables
@@ -730,7 +902,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				tosUri: OAuthProviderImpl.validateStringField(clientMetadata.tos_uri),
 				jwksUri: OAuthProviderImpl.validateStringField(clientMetadata.jwks_uri),
 				contacts: OAuthProviderImpl.validateStringArray(clientMetadata.contacts),
-				grantTypes: OAuthProviderImpl.validateStringArray(clientMetadata.grant_types) || ["authorization_code", "refresh_token"],
+				grantTypes: OAuthProviderImpl.validateStringArray(clientMetadata.grant_types) || [
+					GrantType.AUTHORIZATION_CODE,
+					GrantType.REFRESH_TOKEN,
+					...this.options.allowTokenExchangeGrant ? [GrantType.TOKEN_EXCHANGE] : []
+				],
 				responseTypes: OAuthProviderImpl.validateStringArray(clientMetadata.response_types) || ["code"],
 				registrationDate: Math.floor(Date.now() / 1e3),
 				tokenEndpointAuthMethod: authMethod
@@ -770,8 +946,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Response from the API handler or error
 	*/
 	async handleApiRequest(request, env, ctx) {
+		const url = new URL(request.url);
+		const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource`;
 		const authHeader = request.headers.get("Authorization");
-		if (!authHeader || !authHeader.startsWith("Bearer ")) return this.createErrorResponse("invalid_token", "Missing or invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Missing or invalid access token\"" });
+		if (!authHeader || !authHeader.startsWith("Bearer ")) return this.createErrorResponse("invalid_token", "Missing or invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Missing or invalid access token") });
 		const accessToken = authHeader.substring(7);
 		const parts = accessToken.split(":");
 		const isPossiblyInternalFormat = parts.length === 3;
@@ -783,14 +961,14 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const id = await generateTokenId(accessToken);
 			tokenData = await env.OAUTH_KV.get(`token:${userId}:${grantId}:${id}`, { type: "json" });
 		}
-		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
+		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
 		if (tokenData) {
 			const now = Math.floor(Date.now() / 1e3);
-			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", "Access token expired", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
+			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", "Access token expired", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
 			if (tokenData.audience) {
 				const requestUrl = new URL(request.url);
-				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}`;
-				if (!(Array.isArray(tokenData.audience) ? tokenData.audience : [tokenData.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Invalid audience\"" });
+				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}`;
+				if (!(Array.isArray(tokenData.audience) ? tokenData.audience : [tokenData.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") });
 			}
 			ctx.props = await decryptProps(await unwrapKeyWithToken(accessToken, tokenData.wrappedEncryptionKey), tokenData.grant.encryptedProps);
 		} else if (this.options.resolveExternalToken) {
@@ -799,16 +977,15 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				request,
 				env
 			});
-			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
+			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
 			if (ext.audience) {
 				const requestUrl = new URL(request.url);
-				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}`;
-				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Invalid audience\"" });
+				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}`;
+				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") });
 			}
 			ctx.props = ext.props;
 		}
 		if (!env.OAUTH_PROVIDER) env.OAUTH_PROVIDER = this.createOAuthHelpers(env);
-		const url = new URL(request.url);
 		const apiHandler = this.findApiHandlerForUrl(url);
 		if (!apiHandler) return this.createErrorResponse("invalid_request", "No handler found for API route", 404);
 		if (apiHandler.type === HandlerType.EXPORTED_HANDLER) return apiHandler.handler.fetch(request, env, ctx);
@@ -856,6 +1033,45 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		return env.OAUTH_KV.get(clientKey, { type: "json" });
 	}
 	/**
+	* Creates and stores an access token
+	* @param params - Options for creating the access token
+	* @returns The access token string
+	*/
+	async createAccessToken(params) {
+		const { userId, grantId, clientId, scope, encryptedProps, encryptionKey, expiresIn, audience, env } = params;
+		const accessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
+		const now = Math.floor(Date.now() / 1e3);
+		const accessTokenId = await generateTokenId(accessToken);
+		const accessTokenData = {
+			id: accessTokenId,
+			grantId,
+			userId,
+			createdAt: now,
+			expiresAt: now + expiresIn,
+			audience,
+			scope,
+			wrappedEncryptionKey: await wrapKeyWithToken(accessToken, encryptionKey),
+			grant: {
+				clientId,
+				scope,
+				encryptedProps
+			}
+		};
+		await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: expiresIn });
+		return accessToken;
+	}
+	/**
+	* Downscopes requested scopes to only include those that are in the grant
+	* Filters out any requested scopes that are not in the granted scopes
+	* @param requestedScope - The scope parameter from the request (string or array)
+	* @param grantedScopes - The scopes that were granted in the authorization
+	* @returns The filtered scopes that are a subset of the granted scopes
+	*/
+	downscope(requestedScope, grantedScopes) {
+		if (!requestedScope) return grantedScopes;
+		return (typeof requestedScope === "string" ? requestedScope.split(" ").filter(Boolean) : requestedScope).filter((scope) => grantedScopes.includes(scope));
+	}
+	/**
 	* Checks if the global_fetch_strictly_public compatibility flag is enabled.
 	* This flag is required for CIMD to prevent SSRF attacks.
 	* See: https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public
@@ -993,6 +1209,14 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		return JSON.parse(text);
 	}
 	/**
+	* Builds a WWW-Authenticate header value with resource_metadata per RFC 9728 §5.1
+	*/
+	buildWwwAuthenticateHeader(resourceMetadataUrl, error, errorDescription) {
+		let header = `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", error="${error}"`;
+		if (errorDescription) header += `, error_description="${errorDescription}"`;
+		return header;
+	}
+	/**
 	* Helper function to create OAuth error responses
 	* @param code - OAuth error code (e.g., 'invalid_request', 'invalid_token')
 	* @param description - Human-readable error description
@@ -1022,6 +1246,17 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	}
 };
 /**
+* Error class for OAuth operations
+* Carries OAuth error code and description for proper error responses
+*/
+var OAuthError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "OAuthError";
+	}
+};
+/**
 * Default expiration time for access tokens (1 hour in seconds)
 */
 const DEFAULT_ACCESS_TOKEN_TTL = 3600;
@@ -1047,14 +1282,23 @@ function validateResourceUri(uri) {
 	}
 }
 /**
-* Checks if a resource server matches an audience claim
-* RFC 7519 Section 4.1.3: audience values are case-sensitive strings
+* Checks if a resource server matches an audience claim.
+* Uses origin comparison (case-insensitive hostname via URL normalization)
+* and path-prefix matching on path boundaries for RFC 8707 resource indicators.
 * @param resourceServerUrl - The resource server URL (from request)
 * @param audienceValue - The audience value from token
 * @returns true if they match, false otherwise
 */
 function audienceMatches(resourceServerUrl, audienceValue) {
-	return resourceServerUrl === audienceValue;
+	try {
+		const resource = new URL(resourceServerUrl);
+		const audience = new URL(audienceValue);
+		if (resource.origin !== audience.origin) return false;
+		if (audience.pathname === "/" || audience.pathname === "") return true;
+		return resource.pathname === audience.pathname || resource.pathname.startsWith(audience.pathname + "/");
+	} catch {
+		return false;
+	}
 }
 /**
 * Parses and validates the resource parameter from a token request (RFC 8707)
@@ -1128,6 +1372,37 @@ function validateRedirectUriScheme(redirectUri) {
 	for (const dangerousScheme of dangerousSchemes) if (scheme === dangerousScheme) throw new Error("Invalid redirect URI");
 }
 /**
+* Checks if a URI is a loopback redirect URI (127.0.0.0/8 or ::1)
+* Per RFC 8252 Section 7.3, these get special port handling
+*/
+function isLoopbackUri(uri) {
+	try {
+		const host = new URL(uri).hostname;
+		if (host.match(/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/)) return true;
+		if (host === "::1" || host === "[::1]") return true;
+		return false;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates a redirect URI against registered URIs with RFC 8252 loopback support.
+* For loopback URIs (127.x.x.x, ::1), any port is allowed as long as scheme, host, path, and query match.
+* For non-loopback URIs, exact match is required.
+*/
+function isValidRedirectUri(requestUri, registeredUris) {
+	return registeredUris.some((registered) => {
+		if (isLoopbackUri(requestUri) && isLoopbackUri(registered)) try {
+			const reqUrl = new URL(requestUri);
+			const regUrl = new URL(registered);
+			return reqUrl.protocol === regUrl.protocol && reqUrl.hostname === regUrl.hostname && reqUrl.pathname === regUrl.pathname && reqUrl.search === regUrl.search;
+		} catch {
+			return false;
+		}
+		return requestUri === registered;
+	});
+}
+/**
 * Encodes a string as base64url (URL-safe base64)
 * @param str - The string to encode
 * @returns The base64url encoded string
@@ -1296,11 +1571,12 @@ var OAuthHelpersImpl = class {
 		const resource = parseResourceParameter(resourceParam);
 		if (resourceParam && !resource) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
 		if (responseType === "token" && !this.provider.options.allowImplicitFlow) throw new Error("The implicit grant flow is not enabled for this provider");
+		if (codeChallengeMethod === "plain" && this.provider.options.allowPlainPKCE === false) throw new Error("The plain PKCE method is not allowed. Use S256 instead.");
 		if (clientId) {
 			const clientInfo = await this.lookupClient(clientId);
 			if (!clientInfo) throw new Error(`Invalid client. The clientId provided does not match to this client.`);
 			if (clientInfo && redirectUri) {
-				if (!clientInfo.redirectUris.includes(redirectUri)) throw new Error(`Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.`);
+				if (!isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error(`Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.`);
 			}
 		}
 		return {
@@ -1333,7 +1609,7 @@ var OAuthHelpersImpl = class {
 		const { clientId, redirectUri } = options.request;
 		if (!clientId || !redirectUri) throw new Error("Client ID and Redirect URI are required in the authorization request.");
 		const clientInfo = await this.lookupClient(clientId);
-		if (!clientInfo || !clientInfo.redirectUris.includes(redirectUri)) throw new Error("Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.");
+		if (!clientInfo || !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error("Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.");
 		const grantId = generateRandomString(16);
 		const { encryptedData, key: encryptionKey } = await encryptProps(options.props);
 		const now = Math.floor(Date.now() / 1e3);
@@ -1365,6 +1641,7 @@ var OAuthHelpersImpl = class {
 				createdAt: now,
 				expiresAt: accessTokenExpiresAt,
 				audience,
+				scope: options.scope,
 				wrappedEncryptionKey: accessTokenWrappedKey,
 				grant: {
 					clientId: options.request.clientId,
@@ -1428,7 +1705,11 @@ var OAuthHelpersImpl = class {
 			tosUri: clientInfo.tosUri,
 			jwksUri: clientInfo.jwksUri,
 			contacts: clientInfo.contacts,
-			grantTypes: clientInfo.grantTypes || ["authorization_code", "refresh_token"],
+			grantTypes: clientInfo.grantTypes || [
+				GrantType.AUTHORIZATION_CODE,
+				GrantType.REFRESH_TOKEN,
+				...this.provider.options.allowTokenExchangeGrant ? [GrantType.TOKEN_EXCHANGE] : []
+			],
 			responseTypes: clientInfo.responseTypes || ["code"],
 			registrationDate: Math.floor(Date.now() / 1e3),
 			tokenEndpointAuthMethod
@@ -1570,6 +1851,19 @@ var OAuthHelpersImpl = class {
 	async unwrapToken(token) {
 		return await this.provider.unwrapToken(token, this.env);
 	}
+	/**
+	* Exchanges an existing access token for a new one with modified characteristics
+	* Implements OAuth 2.0 Token Exchange (RFC 8693)
+	* @param options - Options for token exchange including subject token and optional modifications
+	* @returns Promise resolving to token response with new access token
+	*/
+	async exchangeToken(options) {
+		const tokenSummary = await this.unwrapToken(options.subjectToken);
+		if (!tokenSummary) throw new Error("Invalid or expired subject token");
+		const clientInfo = await this.lookupClient(tokenSummary.grant.clientId);
+		if (!clientInfo) throw new Error("Client not found");
+		return await this.provider.exchangeToken(options.subjectToken, options.scope, options.aud, options.expiresIn, clientInfo, this.env);
+	}
 };
 /**
 * Default export of the OAuth provider
@@ -1578,4 +1872,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { OAuthProvider, oauth_provider_default as default };
+export { GrantType, OAuthProvider, oauth_provider_default as default, getOAuthApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",
@@ -31,7 +31,6 @@
     "pkg-pr-new": "^0.0.62",
     "prettier": "^3.7.4",
     "tsdown": "^0.18.1",
-    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },