@cloudflare/workers-oauth-provider 0.8.1 → 0.8.3

package/README.md

@@ -393,11 +393,11 @@ new OAuthProvider({
 
 Setup:
 
-1. Configure your IdP as an ID-JAG issuer with this worker's origin as the resource and a public JWKS endpoint.
+1. Configure your IdP as an ID-JAG issuer with a public JWKS endpoint. If it includes the optional `resource` claim, configure it with the MCP endpoint URL.
 2. Set `resourceMetadata.resource` to the MCP endpoint URL (required when EMA is enabled).
 3. Implement `trustedIssuers` as a resolver — for multi-tenant deployments it can read `env` / `clientInfo` to look up per-tenant IdP config without redeploying.
 
-The AS enforces `resolved.issuer === iss` (confused-deputy guard) and validates ID-JAG `typ`, signature, audience, client binding, resource, `exp` / `iat` / `nbf`, max lifetime, and `jti` replay. Refresh tokens are not issued for this grant — the ID-JAG itself is the renewable assertion.
+The AS enforces `resolved.issuer === iss` (confused-deputy guard) and validates ID-JAG `typ`, signature, audience, client binding, any supplied resource, `exp` / `iat` / `nbf`, max lifetime, and `jti` replay. When the optional `resource` claim is omitted, the AS uses `resourceMetadata.resource`, so issued tokens remain pinned to the configured MCP resource. Refresh tokens are not issued for this grant — the ID-JAG itself is the renewable assertion.
 
 ### Public clients
 
@@ -410,7 +410,7 @@ enterpriseManagedAuthorization: {
 }
 ```
 
-This is useful for clients registered via a [Client ID Metadata Document (CIMD)](https://modelcontextprotocol.io/), which are always public and therefore cannot present a client secret. With this enabled, trust rests on the IdP-issued, signature-verified, short-lived, single-use ID-JAG assertion (audience-, resource-, and client-bound) rather than on a separately presented client secret. Leave it unset (default `false`) to keep the spec-default behavior of requiring client authentication.
+This is useful for clients registered via a [Client ID Metadata Document (CIMD)](https://modelcontextprotocol.io/), which are always public and therefore cannot present a client secret. With this enabled, trust rests on the IdP-issued, signature-verified, short-lived, single-use ID-JAG assertion (audience- and client-bound), together with the provider's configured resource pinning, rather than on a separately presented client secret. Leave it unset (default `false`) to keep the spec-default behavior of requiring client authentication.
 
 Experimental — the MCP extension is still a draft.
 

package/dist/oauth-provider.d.ts

@@ -102,7 +102,11 @@ interface EmaIdJagClaims {
   sub: string;
   /** Authorization server issuer URL or URLs for which this assertion is intended. */
   aud: string | string[];
-  /** RFC 9728 resource identifier of the MCP server. */
+  /**
+   * Effective RFC 9728 resource identifier of the MCP server. When the ID-JAG
+   * omits its optional `resource` claim, the provider supplies its configured
+   * `resourceMetadata.resource` value.
+   */
   resource: string;
   /** OAuth client identifier this assertion was issued to. */
   client_id: string;
@@ -140,7 +144,10 @@ interface EmaClaimsMapperInput<Env = Cloudflare.Env> {
   claims: EmaIdJagClaims;
   /** Authenticated OAuth client that presented the assertion. */
   clientInfo: ClientInfo;
-  /** Validated MCP resource identifier from the assertion. */
+  /**
+   * Effective MCP resource identifier. Taken from the assertion when present,
+   * otherwise from the provider's configured `resourceMetadata.resource`.
+   */
   resource: string;
   /** Requested scopes after downscoping to the assertion's scope claim, if present. */
   requestedScope: string[];
@@ -281,8 +288,9 @@ interface EmaOptions<Env = Cloudflare.Env> {
    * always public (`none`) and therefore cannot present a client secret. The
    * security trade-off is documented in the README: the trust then rests on
    * the IdP-issued, signature-verified, short-lived, single-use ID-JAG
-   * assertion (audience-, resource-, and client-bound) rather than on a
-   * separately presented client secret.
+   * assertion (audience- and client-bound), together with the provider's
+   * configured resource pinning, rather than on a separately presented client
+   * secret.
    */
   allowPublicClients?: boolean;
 }
@@ -350,8 +358,9 @@ interface TokenExchangeCallbackResult {
    */
   refreshTokenTTL?: number;
   /**
-   * List of scopes authorized for the new access token
-   * (If undefined, the granted scopes will be used)
+   * 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[];
 }
@@ -380,12 +389,11 @@ interface TokenExchangeCallbackOptions {
    */
   grantId: string;
   /**
-   * List of scopes that were granted
+   * List of scopes on the underlying authorization grant.
    */
   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)
+   * Effective scopes selected for this token before applying the callback result.
    */
   requestedScope: string[];
   /**
@@ -782,7 +790,7 @@ interface ExchangeTokenOptions {
    */
   subjectToken: string;
   /**
-   * Optional narrowed set of scopes for the new token (must be subset of original grant scopes)
+   * Optional requested scopes for the new token. Issued scopes are limited to the subject token's scopes.
    */
   scope?: string[];
   /**

package/dist/oauth-provider.js

@@ -469,13 +469,14 @@ function isWellFormedTrustedIssuer(issuer) {
 	return true;
 }
 /**
-* Validate every required ID-JAG claim and produce a typed `ValidatedIdJag`.
+* Validate the ID-JAG claims and produce a typed `ValidatedIdJag`.
 *
 * Enforces (in order):
-*   - presence + type of `iss`, `sub`, `aud`, `resource`, `client_id`, `jti`, `exp`, `iat`
+*   - presence + type of `iss`, `sub`, `aud`, `client_id`, `jti`, `exp`, `iat`
 *   - `aud` contains the AS's expected audience
 *   - `client_id` matches the authenticated client
-*   - `resource` is a valid RFC 8707 URI and matches the AS's configured resource
+*   - optional `resource` is a valid RFC 8707 URI and matches the AS's configured resource
+*   - the configured resource is used when `resource` is omitted
 *   - `exp` is in the future
 *   - `iat` is not more than `clockSkewSeconds` in the future
 *   - `nbf` (if present) is ≤ `now + clockSkewSeconds`
@@ -495,7 +496,7 @@ function validateIdJagClaims(input) {
 	if (!sub.ok) return sub;
 	const aud = readAudienceClaim(rawClaims);
 	if (!aud.ok) return aud;
-	const resource = readRequiredString(rawClaims, "resource");
+	const resource = rawClaims.resource === void 0 ? ok(configuredResource) : readRequiredString(rawClaims, "resource");
 	if (!resource.ok) return resource;
 	const claimClientId = readRequiredString(rawClaims, "client_id");
 	if (!claimClientId.ok) return claimClientId;
@@ -989,13 +990,21 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			description: "Method not allowed",
 			statusCode: 405
 		});
-		let contentType = request.headers.get("Content-Type") || "";
+		const contentType = request.headers.get("Content-Type") || "";
 		let body = {};
-		if (!contentType.includes("application/x-www-form-urlencoded")) return this.createErrorResponse("invalid_request", {
+		if (contentType.split(";")[0].trim().toLowerCase() !== "application/x-www-form-urlencoded") return this.createErrorResponse("invalid_request", {
 			description: "Content-Type must be application/x-www-form-urlencoded",
 			statusCode: 400
 		});
-		const formData = await request.formData();
+		let formData;
+		try {
+			formData = await request.formData();
+		} catch {
+			return this.createErrorResponse("invalid_request", {
+				description: "Request body must be valid application/x-www-form-urlencoded data",
+				statusCode: 400
+			});
+		}
 		const processedKeys = /* @__PURE__ */ new Set();
 		for (const [key, value] of formData.entries()) {
 			if (processedKeys.has(key)) continue;
@@ -1263,6 +1272,14 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			} else calculatedChallenge = codeVerifier;
 			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", { description: "Invalid PKCE code_verifier" });
 		}
+		const originOnly = !!this.options.resourceMatchOriginOnly;
+		if (body.resource && grantData.resource) {
+			const requestedResources = Array.isArray(body.resource) ? body.resource : [body.resource];
+			const grantedResources = Array.isArray(grantData.resource) ? grantData.resource : [grantData.resource];
+			for (const requested of requestedResources) if (!grantedResources.some((granted) => resourceMatches(requested, granted, originOnly))) return this.createErrorResponse("invalid_target", { description: "Requested resource was not included in the authorization request" });
+		}
+		const audience = parseResourceParameter(body.resource || grantData.resource);
+		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
 		let accessTokenTTL = this.options.accessTokenTTL;
 		let refreshTokenTTL = this.options.refreshTokenTTL;
 		const encryptionKey = await unwrapKeyWithToken(code, grantData.authCodeWrappedKey);
@@ -1324,14 +1341,6 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			grantData.expiresAt = expiresAt;
 		}
 		await this.saveGrantWithTTL(env, grantKey, grantData, now);
-		const originOnly = !!this.options.resourceMatchOriginOnly;
-		if (body.resource && grantData.resource) {
-			const requestedResources = Array.isArray(body.resource) ? body.resource : [body.resource];
-			const grantedResources = Array.isArray(grantData.resource) ? grantData.resource : [grantData.resource];
-			for (const requested of requestedResources) if (!grantedResources.some((granted) => resourceMatches(requested, granted, originOnly))) return this.createErrorResponse("invalid_target", { description: "Requested resource was not included in the authorization request" });
-		}
-		const audience = parseResourceParameter(body.resource || grantData.resource);
-		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
 		const tokenResponse = {
 			access_token: await this.createAccessToken({
 				userId,
@@ -1501,7 +1510,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* `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 requestedScopes - Optional requested scopes, limited to the subject token's scopes
 	* @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
@@ -1515,7 +1524,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const grantKey = `grant:${tokenSummary.userId}:${tokenSummary.grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
 		if (!grantData) throw new OAuthError("invalid_grant", { description: "Grant not found" });
-		let tokenScopes = this.downscope(requestedScopes, grantData.scope);
+		let tokenScopes = this.downscope(requestedScopes, tokenSummary.scope);
 		const originOnly = !!this.options.resourceMatchOriginOnly;
 		let newAudience = tokenSummary.audience;
 		if (requestedResource) {
@@ -1565,7 +1574,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 					encryptedAccessTokenProps = tokenResult.encryptedData;
 					accessTokenEncryptionKey = tokenResult.key;
 				}
-				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
+				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, tokenSummary.scope);
 			}
 		}
 		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
@@ -2209,15 +2218,15 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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
+	* Restricts requested scopes to the scopes available for the current flow.
+	* If no scope is requested, all available scopes are returned.
 	* @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
+	* @param allowedScopes - The maximum scopes available for the current flow
+	* @returns The requested scopes that are included in the allowed scopes
 	*/
-	downscope(requestedScope, grantedScopes) {
-		if (!requestedScope) return grantedScopes;
-		return (typeof requestedScope === "string" ? requestedScope.split(" ").filter(Boolean) : requestedScope).filter((scope) => grantedScopes.includes(scope));
+	downscope(requestedScope, allowedScopes) {
+		if (!requestedScope) return allowedScopes;
+		return (typeof requestedScope === "string" ? requestedScope.split(" ").filter(Boolean) : requestedScope).filter((scope) => allowedScopes.includes(scope));
 	}
 	/**
 	* Checks if the global_fetch_strictly_public compatibility flag is enabled.

package/package.json

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