@cloudflare/workers-oauth-provider 0.2.2 → 0.2.3

package/dist/oauth-provider.d.ts

@@ -2,6 +2,14 @@ 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
  */
@@ -42,6 +50,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 +62,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 +76,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
    */
@@ -175,6 +191,13 @@ interface OAuthProviderOptions {
    * Defaults to false.
    */
   allowImplicitFlow?: 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.
@@ -285,6 +308,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 +547,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 +592,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
@@ -660,5 +731,12 @@ declare class OAuthProvider {
    */
   fetch(request: Request, env: any, 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(options: OAuthProviderOptions, env: any): 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
@@ -176,6 +194,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,
@@ -331,6 +350,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,7 +360,7 @@ 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",
@@ -361,8 +382,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");
 	}
 	/**
@@ -402,23 +424,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 +452,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 +467,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 +492,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 +547,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 +571,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 +619,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			createdAt: now,
 			expiresAt: accessTokenExpiresAt,
 			audience,
+			scope: tokenScopes,
 			wrappedEncryptionKey: accessTokenWrappedKey,
 			grant: {
 				clientId: grantData.clientId,
@@ -613,12 +633,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 +877,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
@@ -789,7 +940,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", "Access token expired", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
 			if (tokenData.audience) {
 				const requestUrl = new URL(request.url);
-				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}`;
+				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": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Invalid audience\"" });
 			}
 			ctx.props = await decryptProps(await unwrapKeyWithToken(accessToken, tokenData.wrappedEncryptionKey), tokenData.grant.encryptedProps);
@@ -802,7 +953,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
 			if (ext.audience) {
 				const requestUrl = new URL(request.url);
-				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}`;
+				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": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Invalid audience\"" });
 			}
 			ctx.props = ext.props;
@@ -856,6 +1007,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
@@ -1022,6 +1212,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 +1248,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)
@@ -1365,6 +1575,7 @@ var OAuthHelpersImpl = class {
 				createdAt: now,
 				expiresAt: accessTokenExpiresAt,
 				audience,
+				scope: options.scope,
 				wrappedEncryptionKey: accessTokenWrappedKey,
 				grant: {
 					clientId: options.request.clientId,
@@ -1428,7 +1639,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 +1785,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 +1806,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.3",
   "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"
   },