@cloudflare/workers-oauth-provider 0.8.0 → 0.8.2

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;
 }

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;
@@ -639,9 +640,11 @@ function validateEmaMapperResult(result) {
 * TOCTOU window between claim validation and token mint.
 */
 function computeEmaAccessTokenTTL(input) {
-	const { configuredDefaultSeconds, assertionExp, mapperTtl, now } = input;
+	const { configuredDefaultSeconds, assertionExp, mapperTtl, now, minTtlSeconds } = input;
 	if (assertionExp - now <= 0) return err({ reason: "assertion_expired_after_processing" });
-	return ok(mapperTtl ?? configuredDefaultSeconds);
+	const ttl = mapperTtl ?? configuredDefaultSeconds;
+	if (ttl < minTtlSeconds) return err({ reason: "invalid_mapped_ttl" });
+	return ok(ttl);
 }
 function readRequiredString(claims, claimName) {
 	const value = claims[claimName];
@@ -785,6 +788,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			onError: ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`),
 			...options
 		};
+		if (!Number.isInteger(this.options.accessTokenTTL) || this.options.accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new TypeError(`accessTokenTTL must be an integer of at least ${KV_MIN_EXPIRATION_TTL_SECONDS} seconds (Cloudflare KV's minimum expiration window).`);
 		this.validateEmaOptions(this.options.enterpriseManagedAuthorization);
 		if (this.options.enterpriseManagedAuthorization) {
 			this.jwksProvider = createDefaultJwksProvider({ cacheTtlSeconds: this.options.enterpriseManagedAuthorization.jwksCacheTtlSeconds });
@@ -1375,7 +1379,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (!isCurrentToken && !isPreviousToken) return this.createErrorResponse("invalid_grant", { description: "Invalid refresh token" });
 		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "Client ID mismatch" });
 		if (grantData.expiresAt !== void 0) {
-			if (Math.floor(Date.now() / 1e3) >= grantData.expiresAt) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
+			const now$1 = Math.floor(Date.now() / 1e3);
+			if (grantData.expiresAt - now$1 < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		}
 		const newAccessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const accessTokenId = await generateTokenId(newAccessToken);
@@ -1432,10 +1437,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			}
 		}
 		const now = Math.floor(Date.now() / 1e3);
+		if (grantData.expiresAt !== void 0 && grantData.expiresAt - now < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		if (grantData.expiresAt !== void 0) {
 			const remainingRefreshTokenLifetime = grantData.expiresAt - now;
 			if (remainingRefreshTokenLifetime > 0) accessTokenTTL = Math.min(accessTokenTTL, remainingRefreshTokenLifetime);
 		}
+		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
 		const accessTokenExpiresAt = now + accessTokenTTL;
 		const accessTokenWrappedKey = await wrapKeyWithToken(newAccessToken, accessTokenEncryptionKey);
 		const newRefreshToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
@@ -1524,6 +1531,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		const now = Math.floor(Date.now() / 1e3);
 		const subjectTokenRemainingLifetime = tokenSummary.expiresAt - now;
+		if (subjectTokenRemainingLifetime < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_grant", { description: "Subject token is too close to expiry to exchange" });
 		let accessTokenTTL = this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL;
 		if (expiresIn !== void 0) {
 			if (expiresIn <= 0) throw new OAuthError("invalid_request", { description: "Invalid expires_in parameter" });
@@ -1561,6 +1569,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 		}
+		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
 		const tokenResponse = {
 			access_token: await this.createAccessToken({
 				userId: tokenSummary.userId,
@@ -1737,7 +1746,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			configuredDefaultSeconds: this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL,
 			assertionExp: claims.value.claims.exp,
 			mapperTtl: mapped.value.accessTokenTTL,
-			now: issueNow
+			now: issueNow,
+			minTtlSeconds: KV_MIN_EXPIRATION_TTL_SECONDS
 		});
 		if (!ttl.ok) return ttl;
 		return ok(await this.issueEmaAccessToken({
@@ -2114,7 +2124,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @param now - Current timestamp in seconds
 	*/
 	async saveGrantWithTTL(env, grantKey, grantData, now) {
-		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: grantData.expiresAt } : {};
+		const minExpiration = now + KV_MIN_EXPIRATION_TTL_SECONDS + KV_EXPIRATION_CLAMP_MARGIN_SECONDS;
+		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: Math.max(grantData.expiresAt, minExpiration) } : {};
 		try {
 			await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
 		} catch (error) {
@@ -2171,6 +2182,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async createAccessToken(params) {
 		const { userId, grantId, clientId, scope, encryptedProps, encryptionKey, expiresIn, audience, env } = params;
+		if (expiresIn < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
 		const accessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const now = Math.floor(Date.now() / 1e3);
 		const accessTokenId = await generateTokenId(accessToken);
@@ -2522,6 +2534,22 @@ const DEFAULT_REFRESH_TOKEN_TTL = 720 * 60 * 60;
 */
 const DEFAULT_CLIENT_REGISTRATION_TTL = 2160 * 60 * 60;
 /**
+* Minimum number of seconds an absolute KV expiration must be in the future.
+* Cloudflare KV rejects `put` calls whose `expiration` is less than 60 seconds
+* away with "400 Invalid expiration ... Expiration times must be at least 60
+* seconds in the future." We use this to treat near-expiry grants as expired and
+* to clamp absolute expirations when writing grants back to KV.
+*/
+const KV_MIN_EXPIRATION_TTL_SECONDS = 60;
+/**
+* Safety margin (seconds) added on top of `KV_MIN_EXPIRATION_TTL_SECONDS` when clamping an
+* absolute KV expiration. Absolute expirations are validated against KV's clock at the
+* moment the write is processed, so writing exactly `now + 60` can be rejected once
+* worker→KV latency or minor clock skew is accounted for. The margin keeps clamped writes
+* comfortably above KV's hard minimum without meaningfully extending a grant's lifetime.
+*/
+const KV_EXPIRATION_CLAMP_MARGIN_SECONDS = 5;
+/**
 * Default batch size for purgeExpiredData. Conservative to stay within
 * Cloudflare's 1000 subrequest limit per invocation.
 */

package/package.json

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