@cloudflare/workers-oauth-provider 0.5.0 → 0.7.0

package/dist/oauth-provider.js

@@ -1,5 +1,675 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 
+//#region src/ema/constants.ts
+/**
+* Constants for MCP Enterprise-Managed Authorization (EMA).
+*
+* Co-located so that anyone touching the EMA code path sees every magic
+* number in one place. Public-facing defaults can be overridden via
+* `EmaOptions`.
+*/
+/** JWT `typ` header value required for ID-JAG assertions (RFC 8725 §3.11). */
+const EMA_ID_JAG_JWT_TYPE = "oauth-id-jag+jwt";
+/**
+* Grant-profile URN advertised in `authorization_grant_profiles_supported`
+* when EMA is configured (MCP Enterprise-Managed Authorization spec).
+*/
+const EMA_ID_JAG_GRANT_PROFILE = "urn:ietf:params:oauth:grant-profile:id-jag";
+/** Maximum compact JWT assertion size accepted at the token endpoint. */
+const EMA_MAX_JWT_BYTES = 16 * 1024;
+/** Maximum JWKS response size accepted from a trusted enterprise IdP. */
+const EMA_JWKS_MAX_SIZE_BYTES = 64 * 1024;
+/** Request timeout for JWKS fetches. */
+const EMA_JWKS_FETCH_TIMEOUT_MS = 1e4;
+/** Default JWKS cache TTL. */
+const EMA_DEFAULT_JWKS_CACHE_TTL_SECONDS = 300;
+/** Default allowed clock skew for ID-JAG time claim validation. */
+const EMA_DEFAULT_CLOCK_SKEW_SECONDS = 60;
+/** Default maximum accepted ID-JAG lifetime. */
+const EMA_DEFAULT_MAX_ASSERTION_LIFETIME_SECONDS = 300;
+/**
+* Minimum cool-down between JWKS force-refreshes per issuer.
+* Defends against attackers that send many assertions with random `kid`
+* values to amplify load on the IdP's JWKS endpoint.
+*/
+const EMA_JWKS_FORCE_REFRESH_COOLDOWN_SECONDS = 30;
+/** Default JWT signing algorithm assumed for a trusted issuer. */
+const EMA_DEFAULT_JWT_ALGORITHM = "RS256";
+/** JWT signing algorithms supported by the built-in WebCrypto verifier. */
+const EMA_SUPPORTED_JWT_ALGORITHMS = new Set(["RS256", "ES256"]);
+
+//#endregion
+//#region src/ema/result.ts
+const ok = (value) => ({
+	ok: true,
+	value
+});
+const err = (error) => ({
+	ok: false,
+	error
+});
+/**
+* Map an internal `EmaValidationError` to its public OAuth error code and
+* description. Most validation failures collapse to a single generic message
+* to avoid leaking which check failed to attackers probing the IdP. The
+* exceptions are RFC-prescribed distinct codes (`invalid_target` for
+* RFC 8707 resource issues, `invalid_request` for malformed input).
+*/
+function emaErrorToWire(e) {
+	switch (e.reason) {
+		case "assertion_missing": return {
+			code: "invalid_request",
+			message: "assertion is required"
+		};
+		case "invalid_scope_param": return {
+			code: "invalid_request",
+			message: "Invalid scope parameter format"
+		};
+		case "resource_invalid":
+		case "resource_mismatch": return {
+			code: "invalid_target",
+			message: "Invalid resource"
+		};
+		case "mapper_denied":
+		case "mapper_threw": return {
+			code: "invalid_grant",
+			message: "Assertion was not authorized"
+		};
+		case "invalid_mapped_user": return {
+			code: "invalid_grant",
+			message: "Invalid mapped user"
+		};
+		case "invalid_mapped_scope": return {
+			code: "invalid_grant",
+			message: "Invalid mapped scope"
+		};
+		case "invalid_mapped_props": return {
+			code: "invalid_grant",
+			message: "Invalid mapped props"
+		};
+		case "invalid_mapped_ttl": return {
+			code: "invalid_grant",
+			message: "Invalid access token TTL"
+		};
+		case "assertion_expired_after_processing": return {
+			code: "invalid_grant",
+			message: "Assertion has expired"
+		};
+		case "assertion_too_large":
+		case "assertion_malformed":
+		case "invalid_typ":
+		case "invalid_alg":
+		case "issuer_not_trusted":
+		case "no_matching_key":
+		case "signature_failed":
+		case "jwks_fetch_failed":
+		case "invalid_claim":
+		case "aud_mismatch":
+		case "expired":
+		case "iat_in_future":
+		case "nbf_in_future":
+		case "lifetime_too_long":
+		case "replayed":
+		case "client_id_mismatch": return {
+			code: "invalid_grant",
+			message: "Invalid assertion"
+		};
+	}
+}
+
+//#endregion
+//#region src/ema/util.ts
+/**
+* Tiny utility helpers used by EMA adapters.
+*
+* Lives in `src/ema/util.ts` rather than `src/util.ts` to keep the EMA
+* module self-contained — the main `oauth-provider.ts` reaches into here
+* only through the adapters' public interfaces.
+*/
+/** SHA-256 a string and return its hex digest. */
+async function sha256Hex(input) {
+	const data = new TextEncoder().encode(input);
+	const buffer = await crypto.subtle.digest("SHA-256", data);
+	return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+//#endregion
+//#region src/ema/jti.ts
+/**
+* Default `EmaJtiStore`: KV-backed `jti` replay marker.
+*
+* KV is eventually-consistent and does not provide compare-and-set, so two
+* concurrent requests with the same `jti` can both observe "not seen" and
+* succeed — the trade-off accepted here. Surrounding claim checks
+* (signature, `exp`, `nbf`, `aud`, `resource`, client binding) constrain
+* the practical attack window.
+*/
+/** Storage key prefix for replay markers. Stable across versions. */
+const EMA_JTI_KV_PREFIX = "enterprise-jti:";
+/** Create the default KV-backed JTI store. KV TTL handles cleanup. */
+function createKvJtiStore() {
+	return { async markUsed({ issuer, jti, exp, now, env }) {
+		const ttl = Math.max(1, exp - now);
+		const key = `${EMA_JTI_KV_PREFIX}${await sha256Hex(`${issuer}\n${jti}`)}`;
+		if (await env.OAUTH_KV.get(key)) return err({
+			reason: "replayed",
+			jti
+		});
+		await env.OAUTH_KV.put(key, "1", { expirationTtl: ttl });
+		return ok(void 0);
+	} };
+}
+
+//#endregion
+//#region src/ema/jwks.ts
+/**
+* Default `EmaJwksProvider`: fetches IdP signing keys with caching and a
+* force-refresh cool-down. The cool-down defends against attackers that
+* spam random `kid` values to amplify load on the IdP's JWKS endpoint.
+*
+* The cache lives inside the returned provider closure, so each
+* `OAuthProvider` instance has its own cache — no cross-instance bleed.
+*/
+/** Create the default JWKS provider — a closure with its own private cache. */
+function createDefaultJwksProvider(opts = {}) {
+	const cache = /* @__PURE__ */ new Map();
+	const cacheTtl = opts.cacheTtlSeconds ?? EMA_DEFAULT_JWKS_CACHE_TTL_SECONDS;
+	return { async fetch(issuer, { forceRefresh, now }) {
+		const cached = cache.get(issuer.issuer);
+		if (!forceRefresh && cached && cached.expiresAt > now) return ok(cached.jwks);
+		if (forceRefresh && cached && cached.nextForceRefreshAllowedAt > now) return ok(cached.jwks);
+		const abortController = new AbortController();
+		const timeoutId = setTimeout(() => abortController.abort(), EMA_JWKS_FETCH_TIMEOUT_MS);
+		try {
+			const response = await fetch(issuer.jwksUri, {
+				headers: { Accept: "application/json" },
+				signal: abortController.signal,
+				cf: { cacheEverything: true }
+			});
+			if (!response.ok) return err({
+				reason: "jwks_fetch_failed",
+				status: response.status
+			});
+			const contentLength = response.headers.get("content-length");
+			if (contentLength && parseInt(contentLength, 10) > EMA_JWKS_MAX_SIZE_BYTES) return err({
+				reason: "jwks_fetch_failed",
+				status: response.status
+			});
+			const rawJwks = await readJsonWithSizeLimit(response, EMA_JWKS_MAX_SIZE_BYTES);
+			if (!rawJwks.ok) return err({ reason: "jwks_fetch_failed" });
+			if (!Array.isArray(rawJwks.value.keys)) return err({ reason: "jwks_fetch_failed" });
+			const jwks = { keys: rawJwks.value.keys };
+			cache.set(issuer.issuer, {
+				jwks,
+				expiresAt: now + cacheTtl,
+				nextForceRefreshAllowedAt: now + EMA_JWKS_FORCE_REFRESH_COOLDOWN_SECONDS
+			});
+			return ok(jwks);
+		} catch {
+			return err({ reason: "jwks_fetch_failed" });
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	} };
+}
+/**
+* Streaming JSON reader that rejects responses exceeding `maxBytes`.
+* Bounds memory consumption before we attempt to JSON-parse the body.
+*/
+async function readJsonWithSizeLimit(response, maxBytes) {
+	if (!response.body) return { ok: false };
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				reader.cancel();
+				return { ok: false };
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const merged = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	try {
+		const parsed = JSON.parse(new TextDecoder().decode(merged));
+		if (typeof parsed !== "object" || parsed === null) return { ok: false };
+		return {
+			ok: true,
+			value: parsed
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+
+//#endregion
+//#region src/ema/parser.ts
+/**
+* Pure JWT parsing for ID-JAG assertions.
+*
+* Splits a compact JWS (`<base64url-header>.<base64url-payload>.<base64url-signature>`)
+* into its three parts, decodes header and payload as JSON, and exposes the
+* raw signing input + signature bytes for downstream signature verification.
+*
+* No I/O. No `this`. Returns `Result<ParsedIdJag, EmaValidationError>`.
+*/
+/**
+* Parse a compact JWS assertion.
+*
+* @param assertion The raw assertion string from the token request body.
+* @param maxBytes Reject assertions whose length exceeds this many bytes.
+*   Guards against memory exhaustion before any JSON parsing happens.
+*/
+function parseIdJag(assertion, maxBytes) {
+	if (typeof assertion !== "string" || assertion.length === 0) return err({ reason: "assertion_missing" });
+	if (assertion.length > maxBytes) return err({
+		reason: "assertion_too_large",
+		size: assertion.length,
+		max: maxBytes
+	});
+	const parts = assertion.split(".");
+	if (parts.length !== 3 || parts.some((part) => part.length === 0)) return err({ reason: "assertion_malformed" });
+	const [encodedHeader, encodedClaims, encodedSignature] = parts;
+	let header;
+	let rawClaims;
+	let signature;
+	try {
+		header = parseJwtJsonPart(encodedHeader);
+		rawClaims = parseJwtJsonPart(encodedClaims);
+		signature = base64UrlToBytes(encodedSignature);
+	} catch {
+		return err({ reason: "assertion_malformed" });
+	}
+	const signingInput = new TextEncoder().encode(`${encodedHeader}.${encodedClaims}`);
+	return ok({
+		header,
+		rawClaims,
+		signingInput,
+		signature
+	});
+}
+
+//#endregion
+//#region src/ema/signature.ts
+/**
+* JWK selection and ID-JAG signature verification.
+*
+* `selectJwk` is a pure picker; `verifyIdJagSignature` is the I/O-bearing
+* WebCrypto call. Both operate over an already-fetched JWKS.
+*/
+/**
+* Pick a signing key from a JWKS that matches the assertion header.
+*
+* Filters by:
+*   - `kid` (if the assertion header carries one)
+*   - JWK `use === 'sig'` (when present)
+*   - JWK `key_ops` containing `verify` (when present)
+*   - JWK `alg` matching (when present)
+*   - `kty` compatible with the requested `alg`
+*
+* If the assertion has a `kid`, the first matching key wins. Without a `kid`,
+* we only return a key if exactly one candidate matches — otherwise the
+* selection is ambiguous and we reject (caller may then force-refresh JWKS).
+*/
+function selectJwk(jwks, alg, kid) {
+	const matching = (jwks.keys ?? []).filter((key) => {
+		if (kid && key.kid !== kid) return false;
+		if (key.alg && key.alg !== alg) return false;
+		if (key.use && key.use !== "sig") return false;
+		if (Array.isArray(key.key_ops) && !key.key_ops.includes("verify")) return false;
+		if (alg.startsWith("RS") && key.kty !== "RSA") return false;
+		if (alg.startsWith("ES") && key.kty !== "EC") return false;
+		return true;
+	});
+	if (kid) {
+		const picked = matching[0];
+		if (!picked) return err({
+			reason: "no_matching_key",
+			kid
+		});
+		return ok(picked);
+	}
+	if (matching.length !== 1) return err({ reason: "no_matching_key" });
+	return ok(matching[0]);
+}
+/**
+* Verify an ID-JAG's compact-JWS signature using WebCrypto.
+*
+* Returns `false` on any WebCrypto-level failure (import or verify).
+* The caller is responsible for mapping `false` to the appropriate
+* `EmaValidationError`.
+*/
+async function verifyIdJagSignature(input) {
+	try {
+		const { importAlgorithm, verifyAlgorithm } = getJwtCryptoAlgorithms(input.alg);
+		const key = await crypto.subtle.importKey("jwk", input.jwk, importAlgorithm, false, ["verify"]);
+		return await crypto.subtle.verify(verifyAlgorithm, key, input.signature, input.signingInput);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/ema/validators.ts
+/**
+* Validate the JOSE header of an ID-JAG. Enforces the `typ=oauth-id-jag+jwt`
+* marker (RFC 8725 §3.11) and an `alg` within the AS's global allowlist.
+* Per-issuer `algorithms` is checked separately in `resolveTrustedIssuer`.
+*/
+function validateIdJagHeader(header, expectedTyp, supportedAlgs) {
+	const typ = header.typ;
+	if (typeof typ !== "string" || typ !== expectedTyp) return err({
+		reason: "invalid_typ",
+		got: typ
+	});
+	const alg = header.alg;
+	if (typeof alg !== "string" || alg === "none" || !supportedAlgs.has(alg)) return err({
+		reason: "invalid_alg",
+		got: alg
+	});
+	const kidRaw = header.kid;
+	return ok({
+		typ,
+		alg,
+		kid: typeof kidRaw === "string" && kidRaw.length > 0 ? kidRaw : void 0
+	});
+}
+/**
+* Resolve the `iss` claim through the deployer-supplied resolver, then
+* validate the returned configuration before signature verification ever
+* runs against it.
+*
+* Every failure here collapses to `issuer_not_trusted` so an attacker
+* cannot distinguish "unknown IdP" from "resolver returned a malformed
+* config" from "alg not in the IdP's allowlist".
+*
+* The resolver's returned `issuer` field MUST equal the input `iss`.
+* Otherwise a buggy resolver could be tricked into returning a config
+* for IdP B while validating a JWT that claims to be from IdP A,
+* which would let an attacker forge any IdP they like (since the JWKS
+* would be fetched from B's URI).
+*/
+async function resolveTrustedIssuer(input) {
+	const { iss, alg, resolver, env, request, clientInfo } = input;
+	if (typeof iss !== "string" || iss.length === 0) return err({
+		reason: "invalid_claim",
+		claim: "iss"
+	});
+	let resolved;
+	try {
+		resolved = await resolver({
+			iss,
+			env,
+			request,
+			clientInfo
+		});
+	} catch {
+		return err({
+			reason: "issuer_not_trusted",
+			iss
+		});
+	}
+	if (!resolved) return err({
+		reason: "issuer_not_trusted",
+		iss
+	});
+	if (resolved.issuer !== iss) return err({
+		reason: "issuer_not_trusted",
+		iss
+	});
+	if (!isWellFormedTrustedIssuer(resolved)) return err({
+		reason: "issuer_not_trusted",
+		iss
+	});
+	if (!(resolved.algorithms ?? [EMA_DEFAULT_JWT_ALGORITHM]).includes(alg)) return err({
+		reason: "issuer_not_trusted",
+		iss
+	});
+	return ok(resolved);
+}
+/**
+* Per-request structural validation of an `EmaTrustedIssuer` returned by
+* a dynamic resolver. Mirrors the construction-time checks that the
+* static-array shape used to get for free.
+*/
+function isWellFormedTrustedIssuer(issuer) {
+	let issuerUrl;
+	try {
+		issuerUrl = new URL(issuer.issuer);
+	} catch {
+		return false;
+	}
+	if (issuerUrl.protocol !== "https:") return false;
+	let jwksUrl;
+	try {
+		jwksUrl = new URL(issuer.jwksUri);
+	} catch {
+		return false;
+	}
+	if (jwksUrl.protocol !== "https:") return false;
+	const algorithms = issuer.algorithms ?? [EMA_DEFAULT_JWT_ALGORITHM];
+	if (algorithms.length === 0) return false;
+	for (const alg of algorithms) if (!EMA_SUPPORTED_JWT_ALGORITHMS.has(alg)) return false;
+	if (issuer.audience !== void 0) try {
+		new URL(issuer.audience);
+	} catch {
+		return false;
+	}
+	return true;
+}
+/**
+* Validate every required ID-JAG claim and produce a typed `ValidatedIdJag`.
+*
+* Enforces (in order):
+*   - presence + type of `iss`, `sub`, `aud`, `resource`, `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
+*   - `exp` is in the future
+*   - `iat` is not more than `clockSkewSeconds` in the future
+*   - `nbf` (if present) is ≤ `now + clockSkewSeconds`
+*   - `exp - iat` does not exceed `maxAssertionLifetimeSeconds + clockSkewSeconds`
+*   - `scope` (if present) conforms to RFC 6749 §3.3 grammar
+*/
+function validateIdJagClaims(input) {
+	const { rawClaims, trustedIssuer, expectedAudience, clientId, configuredResource, matchOriginOnly } = input;
+	const { now, clockSkewSeconds, maxAssertionLifetimeSeconds } = input;
+	const iss = readRequiredString(rawClaims, "iss");
+	if (!iss.ok) return iss;
+	if (iss.value !== trustedIssuer.issuer) return err({
+		reason: "issuer_not_trusted",
+		iss: iss.value
+	});
+	const sub = readRequiredString(rawClaims, "sub");
+	if (!sub.ok) return sub;
+	const aud = readAudienceClaim(rawClaims);
+	if (!aud.ok) return aud;
+	const resource = readRequiredString(rawClaims, "resource");
+	if (!resource.ok) return resource;
+	const claimClientId = readRequiredString(rawClaims, "client_id");
+	if (!claimClientId.ok) return claimClientId;
+	const jti = readRequiredString(rawClaims, "jti");
+	if (!jti.ok) return jti;
+	const exp = readNumericDateClaim(rawClaims, "exp");
+	if (!exp.ok) return exp;
+	const iat = readNumericDateClaim(rawClaims, "iat");
+	if (!iat.ok) return iat;
+	if (!(Array.isArray(aud.value) ? aud.value : [aud.value]).includes(expectedAudience)) return err({
+		reason: "aud_mismatch",
+		expected: expectedAudience,
+		got: aud.value
+	});
+	if (claimClientId.value !== clientId) return err({
+		reason: "client_id_mismatch",
+		expected: clientId,
+		got: claimClientId.value
+	});
+	if (!validateResourceUri(resource.value)) return err({
+		reason: "resource_invalid",
+		resource: resource.value
+	});
+	if (!resourceMatches(resource.value, configuredResource, matchOriginOnly)) return err({
+		reason: "resource_mismatch",
+		expected: configuredResource,
+		got: resource.value
+	});
+	if (exp.value + clockSkewSeconds <= now) return err({
+		reason: "expired",
+		exp: exp.value,
+		now
+	});
+	if (iat.value > now + clockSkewSeconds) return err({
+		reason: "iat_in_future",
+		iat: iat.value,
+		now,
+		skew: clockSkewSeconds
+	});
+	if (rawClaims.nbf !== void 0) {
+		const nbf = readNumericDateClaim(rawClaims, "nbf");
+		if (!nbf.ok) return nbf;
+		if (nbf.value > now + clockSkewSeconds) return err({
+			reason: "nbf_in_future",
+			nbf: nbf.value,
+			now,
+			skew: clockSkewSeconds
+		});
+	}
+	const lifetime = exp.value - iat.value;
+	if (lifetime > maxAssertionLifetimeSeconds + clockSkewSeconds) return err({
+		reason: "lifetime_too_long",
+		lifetime,
+		max: maxAssertionLifetimeSeconds
+	});
+	let scope;
+	let assertionScopes = [];
+	if (rawClaims.scope !== void 0) {
+		const parsed = readRequiredString(rawClaims, "scope");
+		if (!parsed.ok) return parsed;
+		const tokens = parsed.value.split(" ").filter(Boolean);
+		for (const token of tokens) if (!isValidOAuthScopeToken(token)) return err({
+			reason: "invalid_claim",
+			claim: "scope"
+		});
+		scope = parsed.value;
+		assertionScopes = tokens;
+	}
+	return ok({
+		claims: {
+			...rawClaims,
+			iss: iss.value,
+			sub: sub.value,
+			aud: aud.value,
+			resource: resource.value,
+			client_id: claimClientId.value,
+			jti: jti.value,
+			exp: exp.value,
+			iat: iat.value,
+			scope
+		},
+		resource: resource.value,
+		assertionScopes
+	});
+}
+/**
+* Parse the `scope` parameter of the token request and downscope it to the
+* assertion's own scope claim. If the request omits `scope`, the assertion's
+* scopes are used directly.
+*/
+function parseEmaScopeParam(scope, assertionScopes) {
+	let requested;
+	if (scope === void 0) requested = [...assertionScopes];
+	else if (typeof scope === "string") {
+		const tokens = scope.split(" ").filter(Boolean);
+		for (const token of tokens) if (!isValidOAuthScopeToken(token)) return err({ reason: "invalid_scope_param" });
+		requested = tokens;
+	} else if (Array.isArray(scope) && scope.every((value) => typeof value === "string")) {
+		requested = [];
+		for (const part of scope) {
+			const tokens = part.split(" ").filter(Boolean);
+			for (const token of tokens) if (!isValidOAuthScopeToken(token)) return err({ reason: "invalid_scope_param" });
+			requested.push(...tokens);
+		}
+	} else return err({ reason: "invalid_scope_param" });
+	if (assertionScopes.length > 0) {
+		const allowed = new Set(assertionScopes);
+		requested = requested.filter((token) => allowed.has(token));
+	}
+	return ok(requested);
+}
+/**
+* Validate the shape of the value returned by the deployer's `mapClaims`
+* callback. A `null` return is treated as a deny decision.
+*
+* The `userId.includes(':')` rejection mirrors the opaque token format
+* (`userId:grantId:secret`) used elsewhere in this provider.
+*/
+function validateEmaMapperResult(result) {
+	if (result === null) return err({ reason: "mapper_denied" });
+	if (typeof result !== "object") return err({ reason: "invalid_mapped_user" });
+	const r = result;
+	if (typeof r.userId !== "string" || r.userId.length === 0 || r.userId.includes(":")) return err({ reason: "invalid_mapped_user" });
+	if (!Array.isArray(r.scope) || !r.scope.every((s) => typeof s === "string" && isValidOAuthScopeToken(s))) return err({ reason: "invalid_mapped_scope" });
+	if (!("props" in r) || r.props === void 0) return err({ reason: "invalid_mapped_props" });
+	if (r.accessTokenTTL !== void 0) {
+		if (typeof r.accessTokenTTL !== "number" || !Number.isFinite(r.accessTokenTTL) || r.accessTokenTTL <= 0) return err({ reason: "invalid_mapped_ttl" });
+	}
+	return ok({
+		userId: r.userId,
+		scope: r.scope,
+		props: r.props,
+		metadata: r.metadata,
+		accessTokenTTL: r.accessTokenTTL
+	});
+}
+/**
+* Compute the access token TTL: mapper override wins, otherwise the AS
+* default. The assertion's `exp` is the lifetime of the grant, not of the
+* issued token (RFC 7523 §3); we only re-check it here to catch the
+* TOCTOU window between claim validation and token mint.
+*/
+function computeEmaAccessTokenTTL(input) {
+	const { configuredDefaultSeconds, assertionExp, mapperTtl, now } = input;
+	if (assertionExp - now <= 0) return err({ reason: "assertion_expired_after_processing" });
+	return ok(mapperTtl ?? configuredDefaultSeconds);
+}
+function readRequiredString(claims, claimName) {
+	const value = claims[claimName];
+	if (typeof value !== "string" || value.length === 0) return err({
+		reason: "invalid_claim",
+		claim: claimName
+	});
+	return ok(value);
+}
+function readAudienceClaim(claims) {
+	const aud = claims.aud;
+	if (typeof aud === "string" && aud.length > 0) return ok(aud);
+	if (Array.isArray(aud) && aud.length > 0 && aud.every((v) => typeof v === "string" && v.length > 0)) return ok(aud);
+	return err({
+		reason: "invalid_claim",
+		claim: "aud"
+	});
+}
+function readNumericDateClaim(claims, claimName) {
+	const value = claims[claimName];
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return err({
+		reason: "invalid_claim",
+		claim: claimName
+	});
+	return ok(value);
+}
+
+//#endregion
 //#region src/oauth-provider.ts
 const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
 if (!(typeof Cloudflare !== "undefined" && Cloudflare.compatibilityFlags?.global_fetch_strictly_public === true)) console.warn("CIMD (Client ID Metadata Document) is disabled: add '\"compatibility_flags\": [\"global_fetch_strictly_public\"]' to your wrangler.jsonc to enable. See: https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public");
@@ -18,6 +688,7 @@ 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";
+	GrantType$1["JWT_BEARER"] = "urn:ietf:params:oauth:grant-type:jwt-bearer";
 	return GrantType$1;
 }({});
 /**
@@ -110,6 +781,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			onError: ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`),
 			...options
 		};
+		this.validateEmaOptions(this.options.enterpriseManagedAuthorization);
+		if (this.options.enterpriseManagedAuthorization) {
+			this.jwksProvider = createDefaultJwksProvider({ cacheTtlSeconds: this.options.enterpriseManagedAuthorization.jwksCacheTtlSeconds });
+			this.jtiStore = createKvJtiStore();
+		}
 	}
 	/**
 	* Validates that an endpoint is either an absolute path or a full URL
@@ -145,6 +821,23 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		throw new TypeError(`${name} must be either an ExportedHandler object with a fetch method or a class extending WorkerEntrypoint`);
 	}
 	/**
+	* Validates MCP Enterprise-Managed Authorization configuration at construction time.
+	*
+	* Presence of `enterpriseManagedAuthorization` on options enables the feature —
+	* there is no separate `enabled` flag (which would silently disable EMA when
+	* forgotten). Configuration is checked structurally; runtime concerns
+	* (JWKS reachability etc.) are checked when assertions arrive.
+	*/
+	validateEmaOptions(options) {
+		if (!options) return;
+		if (typeof options.trustedIssuers !== "function") throw new TypeError("enterpriseManagedAuthorization.trustedIssuers must be a resolver function: (input) => EmaTrustedIssuer | null");
+		if (typeof options.mapClaims !== "function") throw new TypeError("enterpriseManagedAuthorization.mapClaims must be a function");
+		if (!this.options.resourceMetadata?.resource) throw new TypeError("enterpriseManagedAuthorization requires resourceMetadata.resource to be configured");
+		if (options.jwksCacheTtlSeconds !== void 0 && options.jwksCacheTtlSeconds <= 0) throw new TypeError("enterpriseManagedAuthorization.jwksCacheTtlSeconds must be greater than 0");
+		if (options.clockSkewSeconds !== void 0 && options.clockSkewSeconds < 0) throw new TypeError("enterpriseManagedAuthorization.clockSkewSeconds must be non-negative");
+		if (options.maxAssertionLifetimeSeconds !== void 0 && options.maxAssertionLifetimeSeconds <= 0) throw new TypeError("enterpriseManagedAuthorization.maxAssertionLifetimeSeconds must be greater than 0");
+	}
+	/**
 	* Main fetch handler for the Worker
 	* Routes requests to the appropriate handler based on the URL
 	* @param request - The HTTP request
@@ -173,7 +866,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			if (parsed instanceof Response) return this.addCorsHeaders(parsed, request);
 			let response;
 			if (parsed.isRevocationRequest) response = await this.handleRevocationRequest(parsed.body, env);
-			else response = await this.handleTokenRequest(parsed.body, parsed.clientInfo, env);
+			else response = await this.handleTokenRequest(parsed.body, parsed.clientInfo, env, url, request);
 			return this.addCorsHeaders(response, request);
 		}
 		if (this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) {
@@ -285,10 +978,16 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Promise with parsed body and client info, or error response
 	*/
 	async parseTokenEndpointRequest(request, env) {
-		if (request.method !== "POST") return this.createErrorResponse("invalid_request", "Method not allowed", 405);
+		if (request.method !== "POST") return this.createErrorResponse("invalid_request", {
+			description: "Method not allowed",
+			statusCode: 405
+		});
 		let contentType = request.headers.get("Content-Type") || "";
 		let body = {};
-		if (!contentType.includes("application/x-www-form-urlencoded")) return this.createErrorResponse("invalid_request", "Content-Type must be application/x-www-form-urlencoded", 400);
+		if (!contentType.includes("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();
 		for (const [key, value] of formData.entries()) {
 			const allValues = formData.getAll(key);
@@ -305,13 +1004,28 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			clientId = body.client_id;
 			clientSecret = body.client_secret || "";
 		}
-		if (!clientId) return this.createErrorResponse("invalid_client", "Client ID is required", 401);
+		if (!clientId) return this.createErrorResponse("invalid_client", {
+			description: "Client ID is required",
+			statusCode: 401
+		});
 		const clientInfo = await this.getClient(env, clientId);
-		if (!clientInfo) return this.createErrorResponse("invalid_client", "Client not found", 401);
+		if (!clientInfo) return this.createErrorResponse("invalid_client", {
+			description: "Client not found",
+			statusCode: 401
+		});
 		if (!(clientInfo.tokenEndpointAuthMethod === "none")) {
-			if (!clientSecret) return this.createErrorResponse("invalid_client", "Client authentication failed: missing client_secret", 401);
-			if (!clientInfo.clientSecret) return this.createErrorResponse("invalid_client", "Client authentication failed: client has no registered secret", 401);
-			if (await hashSecret(clientSecret) !== clientInfo.clientSecret) return this.createErrorResponse("invalid_client", "Client authentication failed: invalid client_secret", 401);
+			if (!clientSecret) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: missing client_secret",
+				statusCode: 401
+			});
+			if (!clientInfo.clientSecret) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: client has no registered secret",
+				statusCode: 401
+			});
+			if (await hashSecret(clientSecret) !== clientInfo.clientSecret) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: invalid client_secret",
+				statusCode: 401
+			});
 		}
 		return {
 			body,
@@ -363,6 +1077,13 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		else return endpoint;
 	}
 	/**
+	* Gets the authorization server issuer using the same derivation as RFC 8414 metadata.
+	*/
+	getAuthorizationServerIssuer(requestUrl) {
+		const tokenEndpoint = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
+		return new URL(tokenEndpoint).origin;
+	}
+	/**
 	* Adds CORS headers to a response
 	* @param response - The response to add CORS headers to
 	* @param request - The original request
@@ -393,6 +1114,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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 authorizationGrantProfilesSupported = [];
+		if (this.options.enterpriseManagedAuthorization) {
+			grantTypesSupported.push(GrantType.JWT_BEARER);
+			authorizationGrantProfilesSupported.push(EMA_ID_JAG_GRANT_PROFILE);
+		}
 		const metadata = {
 			issuer: new URL(tokenEndpoint).origin,
 			authorization_endpoint: authorizeEndpoint,
@@ -402,6 +1128,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			response_types_supported: responseTypesSupported,
 			response_modes_supported: ["query"],
 			grant_types_supported: grantTypesSupported,
+			...authorizationGrantProfilesSupported.length > 0 ? { authorization_grant_profiles_supported: authorizationGrantProfilesSupported } : {},
 			token_endpoint_auth_methods_supported: [
 				"client_secret_basic",
 				"client_secret_post",
@@ -440,12 +1167,33 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @param env - Cloudflare Worker environment variables
 	* @returns Response with token data or error
 	*/
-	async handleTokenRequest(body, clientInfo, env) {
-		const grantType = body.grant_type;
-		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");
+	async handleTokenRequest(body, clientInfo, env, requestUrl, request) {
+		try {
+			const grantType = body.grant_type;
+			if (grantType === GrantType.AUTHORIZATION_CODE) return await this.handleAuthorizationCodeGrant(body, clientInfo, env);
+			else if (grantType === GrantType.REFRESH_TOKEN) return await this.handleRefreshTokenGrant(body, clientInfo, env);
+			else if (grantType === GrantType.TOKEN_EXCHANGE && this.options.allowTokenExchangeGrant) return await this.handleTokenExchangeGrant(body, clientInfo, env);
+			else if (grantType === GrantType.JWT_BEARER) return await this.handleJwtBearerGrant(body, clientInfo, env, requestUrl, request);
+			else return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" });
+		} catch (error) {
+			const response = this.createOAuthErrorResponse(error);
+			if (response) return response;
+			throw error;
+		}
+	}
+	/**
+	* Build a structured OAuth `/token` error response from an OAuth error.
+	*
+	* The supported form is throwing this package's exported `OAuthError`.
+	* Anything else is re-thrown so unexpected failures still surface as 500s.
+	*
+	* Use `headers['Retry-After']` for rate-limit / transient-failure backoff
+	* hints (see RFC 7231 §7.1.3 — either an integer seconds value or an
+	* HTTP-date is allowed).
+	*/
+	createOAuthErrorResponse(error) {
+		if (!(error instanceof OAuthError)) return void 0;
+		return this.createErrorResponse(error.code, error.options);
 	}
 	/**
 	* Handles the authorization code grant type
@@ -459,27 +1207,27 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const code = body.code;
 		const redirectUri = body.redirect_uri;
 		const codeVerifier = body.code_verifier;
-		if (!code) return this.createErrorResponse("invalid_request", "Authorization code is required");
+		if (!code) return this.createErrorResponse("invalid_request", { description: "Authorization code is required" });
 		const codeParts = code.split(":");
-		if (codeParts.length !== 3) return this.createErrorResponse("invalid_grant", "Invalid authorization code format");
+		if (codeParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code format" });
 		const [userId, grantId, _] = codeParts;
 		const grantKey = `grant:${userId}:${grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) return this.createErrorResponse("invalid_grant", "Grant not found or authorization code expired");
+		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found or authorization code expired" });
 		if (!grantData.authCodeId) {
 			try {
 				await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
 			} catch {}
-			return this.createErrorResponse("invalid_grant", "Authorization code already used");
+			return this.createErrorResponse("invalid_grant", { description: "Authorization code already used" });
 		}
-		if (await hashSecret(code) !== grantData.authCodeId) return this.createErrorResponse("invalid_grant", "Invalid authorization code");
-		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", "Client ID mismatch");
+		if (await hashSecret(code) !== grantData.authCodeId) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code" });
+		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "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 && !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 (!redirectUri && !isPkceEnabled) return this.createErrorResponse("invalid_request", { description: "redirect_uri is required when not using PKCE" });
+		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", { description: "Invalid redirect URI" });
+		if (!isPkceEnabled && codeVerifier) return this.createErrorResponse("invalid_request", { description: "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");
+			if (!codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier is required for PKCE" });
 			let calculatedChallenge;
 			if (grantData.codeChallengeMethod === "S256") {
 				const data = new TextEncoder().encode(codeVerifier);
@@ -487,7 +1235,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				const hashArray = Array.from(new Uint8Array(hashBuffer));
 				calculatedChallenge = base64UrlEncode(String.fromCharCode(...hashArray));
 			} else calculatedChallenge = codeVerifier;
-			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", "Invalid PKCE code_verifier");
+			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", { description: "Invalid PKCE code_verifier" });
 		}
 		let accessTokenTTL = this.options.accessTokenTTL;
 		let refreshTokenTTL = this.options.refreshTokenTTL;
@@ -504,6 +1252,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				grantType: GrantType.AUTHORIZATION_CODE,
 				clientId: clientInfo.clientId,
 				userId,
+				grantId,
 				scope: grantData.scope,
 				requestedScope: tokenScopes,
 				props: decryptedProps
@@ -554,10 +1303,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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", "Requested resource was not included in the authorization request");
+			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", "The resource parameter must be a valid absolute URI without a fragment");
+		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,
@@ -588,20 +1337,20 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async handleRefreshTokenGrant(body, clientInfo, env) {
 		const refreshToken = body.refresh_token;
-		if (!refreshToken) return this.createErrorResponse("invalid_request", "Refresh token is required");
+		if (!refreshToken) return this.createErrorResponse("invalid_request", { description: "Refresh token is required" });
 		const tokenParts = refreshToken.split(":");
-		if (tokenParts.length !== 3) return this.createErrorResponse("invalid_grant", "Invalid token format");
+		if (tokenParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid token format" });
 		const [userId, grantId, _] = tokenParts;
 		const providedTokenHash = await generateTokenId(refreshToken);
 		const grantKey = `grant:${userId}:${grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) return this.createErrorResponse("invalid_grant", "Grant not found");
+		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found" });
 		const isCurrentToken = grantData.refreshTokenId === providedTokenHash;
 		const isPreviousToken = grantData.previousRefreshTokenId === providedTokenHash;
-		if (!isCurrentToken && !isPreviousToken) return this.createErrorResponse("invalid_grant", "Invalid refresh token");
-		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", "Client ID mismatch");
+		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", "Refresh token has expired");
+			if (Math.floor(Date.now() / 1e3) >= grantData.expiresAt) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		}
 		const newAccessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const accessTokenId = await generateTokenId(newAccessToken);
@@ -623,6 +1372,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				grantType: GrantType.REFRESH_TOKEN,
 				clientId: clientInfo.clientId,
 				userId,
+				grantId,
 				scope: grantData.scope,
 				requestedScope: tokenScopes,
 				props: decryptedProps
@@ -636,7 +1386,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 ("refreshTokenTTL" in callbackResult) return this.createErrorResponse("invalid_request", { description: "refreshTokenTTL cannot be changed during refresh token exchange" });
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 			if (grantPropsChanged) {
@@ -675,10 +1425,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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", "Requested resource was not included in the authorization request");
+			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", "The resource parameter must be a valid absolute URI without a fragment");
+		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 accessTokenData = {
 			id: accessTokenId,
 			grantId,
@@ -694,7 +1444,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				encryptedProps: encryptedAccessTokenProps
 			}
 		};
-		await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: accessTokenTTL });
+		try {
+			await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: accessTokenTTL });
+		} catch (error) {
+			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
+			throw error;
+		}
 		const tokenResponse = {
 			access_token: newAccessToken,
 			token_type: "bearer",
@@ -722,10 +1477,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	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");
+		if (!tokenSummary) throw new OAuthError("invalid_grant", { description: "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");
+		if (!grantData) throw new OAuthError("invalid_grant", { description: "Grant not found" });
 		let tokenScopes = this.downscope(requestedScopes, grantData.scope);
 		const originOnly = !!this.options.resourceMatchOriginOnly;
 		let newAudience = tokenSummary.audience;
@@ -733,21 +1488,21 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			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.some((granted) => resourceMatches(requested, granted, originOnly))) throw new OAuthError("invalid_target", "Requested resource was not included in the authorization request");
+				for (const requested of requestedResources) if (!grantedResources.some((granted) => resourceMatches(requested, granted, originOnly))) throw new OAuthError("invalid_target", { description: "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");
+			if (!parsedResource) throw new OAuthError("invalid_target", { description: "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");
+			if (expiresIn <= 0) throw new OAuthError("invalid_request", { description: "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");
+		if (!subjectTokenData) throw new OAuthError("invalid_grant", { description: "Subject token data not found" });
 		const encryptionKey = await unwrapKeyWithToken(subjectToken, subjectTokenData.wrappedEncryptionKey);
 		let accessTokenEncryptionKey = encryptionKey;
 		let encryptedAccessTokenProps = subjectTokenData.grant.encryptedProps;
@@ -757,6 +1512,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				grantType: GrantType.TOKEN_EXCHANGE,
 				clientId: clientInfo.clientId,
 				userId: tokenSummary.userId,
+				grantId: tokenSummary.grantId,
 				scope: tokenSummary.grant.scope,
 				requestedScope: tokenScopes,
 				props: decryptedProps
@@ -811,29 +1567,241 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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");
+		if (!subjectToken) return this.createErrorResponse("invalid_request", { description: "subject_token is required" });
+		if (!subjectTokenType) return this.createErrorResponse("invalid_request", { description: "subject_token_type is required" });
+		if (subjectTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token subject_token_type is supported" });
+		if (requestedTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "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");
+		else return this.createErrorResponse("invalid_request", { description: "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");
+			if (isNaN(requestedTTL) || requestedTTL <= 0) return this.createErrorResponse("invalid_request", { description: "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);
+			const response = this.createOAuthErrorResponse(error);
+			if (response) return response;
 			throw error;
 		}
 	}
 	/**
+	* Handles the MCP Enterprise-Managed Authorization JWT-bearer grant.
+	*
+	* Acts as a thin shell around `runEmaPipeline`: gate non-EMA traffic, run
+	* the pipeline, translate the typed `EmaValidationError` Result back to a
+	* standard OAuth wire response. All validation logic lives in pure
+	* functions in `src/ema/`.
+	*/
+	async handleJwtBearerGrant(body, clientInfo, env, requestUrl, request) {
+		const enterpriseOptions = this.options.enterpriseManagedAuthorization;
+		if (!enterpriseOptions) return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" });
+		if (clientInfo.tokenEndpointAuthMethod === "none") return this.createErrorResponse("invalid_client", {
+			description: "Enterprise-managed authorization requires client authentication",
+			statusCode: 401
+		});
+		const result = await this.runEmaPipeline({
+			body,
+			clientInfo,
+			env,
+			requestUrl,
+			request,
+			enterpriseOptions
+		});
+		const noCacheHeaders = {
+			"Cache-Control": "no-store",
+			Pragma: "no-cache"
+		};
+		if (!result.ok) {
+			const wire = emaErrorToWire(result.error);
+			return this.createErrorResponse(wire.code, {
+				description: wire.message,
+				headers: noCacheHeaders
+			}, {
+				category: "enterprise-managed-authorization",
+				reason: result.error.reason,
+				detail: result.error
+			});
+		}
+		return new Response(JSON.stringify(result.value), { headers: {
+			"Content-Type": "application/json",
+			...noCacheHeaders
+		} });
+	}
+	/**
+	* Runs the full EMA token-request pipeline as a chain of pure validators
+	* and adapter calls. Each step short-circuits on the first failure.
+	*
+	* Sequence:
+	*   parse → validate header → trust issuer → fetch JWKS → select key →
+	*   verify signature → validate claims → record jti → parse scope →
+	*   run mapper → validate mapper result → compute TTL → mint token.
+	*/
+	async runEmaPipeline(args) {
+		const { body, clientInfo, env, requestUrl, request, enterpriseOptions } = args;
+		const { jwksProvider, jtiStore } = this;
+		const configuredResource = this.options.resourceMetadata?.resource;
+		if (!jwksProvider || !jtiStore || !configuredResource) throw new Error("EMA pipeline invoked without configured adapters");
+		const now = Math.floor(Date.now() / 1e3);
+		const parsed = parseIdJag(body.assertion, EMA_MAX_JWT_BYTES);
+		if (!parsed.ok) return parsed;
+		const header = validateIdJagHeader(parsed.value.header, EMA_ID_JAG_JWT_TYPE, EMA_SUPPORTED_JWT_ALGORITHMS);
+		if (!header.ok) return header;
+		const alg = header.value.alg;
+		const trustedIssuer = await resolveTrustedIssuer({
+			iss: parsed.value.rawClaims.iss,
+			alg,
+			resolver: enterpriseOptions.trustedIssuers,
+			env,
+			request,
+			clientInfo
+		});
+		if (!trustedIssuer.ok) return trustedIssuer;
+		const verified = await this.verifyAssertionSignature({
+			parsed: parsed.value,
+			header: header.value,
+			trustedIssuer: trustedIssuer.value,
+			jwksProvider,
+			now
+		});
+		if (!verified.ok) return verified;
+		const claims = validateIdJagClaims({
+			rawClaims: parsed.value.rawClaims,
+			trustedIssuer: trustedIssuer.value,
+			expectedAudience: trustedIssuer.value.audience ?? this.getAuthorizationServerIssuer(requestUrl),
+			clientId: clientInfo.clientId,
+			configuredResource,
+			matchOriginOnly: !!this.options.resourceMatchOriginOnly,
+			now,
+			clockSkewSeconds: enterpriseOptions.clockSkewSeconds ?? EMA_DEFAULT_CLOCK_SKEW_SECONDS,
+			maxAssertionLifetimeSeconds: enterpriseOptions.maxAssertionLifetimeSeconds ?? EMA_DEFAULT_MAX_ASSERTION_LIFETIME_SECONDS
+		});
+		if (!claims.ok) return claims;
+		const markNow = Math.floor(Date.now() / 1e3);
+		const replay = await jtiStore.markUsed({
+			issuer: claims.value.claims.iss,
+			jti: claims.value.claims.jti,
+			exp: claims.value.claims.exp,
+			now: markNow,
+			env
+		});
+		if (!replay.ok) return replay;
+		const requestedScope = parseEmaScopeParam(body.scope, claims.value.assertionScopes);
+		if (!requestedScope.ok) return requestedScope;
+		let mapperOutput;
+		try {
+			mapperOutput = await enterpriseOptions.mapClaims({
+				claims: claims.value.claims,
+				clientInfo,
+				resource: claims.value.resource,
+				requestedScope: requestedScope.value,
+				request: args.request,
+				env
+			});
+		} catch {
+			return err({ reason: "mapper_threw" });
+		}
+		const mapped = validateEmaMapperResult(mapperOutput);
+		if (!mapped.ok) return mapped;
+		const issueNow = Math.floor(Date.now() / 1e3);
+		const ttl = computeEmaAccessTokenTTL({
+			configuredDefaultSeconds: this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL,
+			assertionExp: claims.value.claims.exp,
+			mapperTtl: mapped.value.accessTokenTTL,
+			now: issueNow
+		});
+		if (!ttl.ok) return ttl;
+		return ok(await this.issueEmaAccessToken({
+			clientId: clientInfo.clientId,
+			userId: mapped.value.userId,
+			mapperScope: mapped.value.scope,
+			mapperProps: mapped.value.props,
+			mapperMetadata: mapped.value.metadata,
+			assertionScopes: claims.value.assertionScopes,
+			resource: claims.value.resource,
+			accessTokenTTLSeconds: ttl.value,
+			env,
+			now: issueNow
+		}));
+	}
+	/**
+	* Verifies the ID-JAG signature against the trusted issuer's JWKS,
+	* force-refreshing once on a `kid` miss to accommodate IdP key rotation.
+	* Uses the in-memory cached JWKS fetcher with anti-DoS cool-down.
+	*/
+	async verifyAssertionSignature(args) {
+		const alg = args.header.alg;
+		const { jwksProvider } = args;
+		const initialJwks = await jwksProvider.fetch(args.trustedIssuer, {
+			forceRefresh: false,
+			now: args.now
+		});
+		if (!initialJwks.ok) return initialJwks;
+		let jwk = selectJwk(initialJwks.value, alg, args.header.kid);
+		if (!jwk.ok && args.header.kid) {
+			const refreshed = await jwksProvider.fetch(args.trustedIssuer, {
+				forceRefresh: true,
+				now: args.now
+			});
+			if (!refreshed.ok) return refreshed;
+			jwk = selectJwk(refreshed.value, alg, args.header.kid);
+		}
+		if (!jwk.ok) return jwk;
+		if (!await verifyIdJagSignature({
+			alg,
+			jwk: jwk.value,
+			signingInput: args.parsed.signingInput,
+			signature: args.parsed.signature
+		})) return err({ reason: "signature_failed" });
+		return ok(void 0);
+	}
+	/**
+	* Mints the access token for an authorized EMA request.
+	*
+	* Uses the same grant + access-token machinery as the authorization-code
+	* grant: encrypt the props, persist the grant under `grant:userId:grantId`,
+	* and create an opaque access token bound to the resource as audience.
+	*/
+	async issueEmaAccessToken(args) {
+		const tokenScopes = args.assertionScopes.length > 0 ? this.downscope(args.mapperScope, args.assertionScopes) : args.mapperScope;
+		const grantId = generateRandomString(16);
+		const { encryptedData, key: encryptionKey } = await encryptProps(args.mapperProps);
+		const grant = {
+			id: grantId,
+			clientId: args.clientId,
+			userId: args.userId,
+			scope: tokenScopes,
+			metadata: args.mapperMetadata ?? null,
+			encryptedProps: encryptedData,
+			createdAt: args.now,
+			expiresAt: args.now + args.accessTokenTTLSeconds,
+			resource: args.resource
+		};
+		await this.saveGrantWithTTL(args.env, `grant:${args.userId}:${grantId}`, grant, args.now);
+		return {
+			access_token: await this.createAccessToken({
+				userId: args.userId,
+				grantId,
+				clientId: args.clientId,
+				scope: tokenScopes,
+				encryptedProps: encryptedData,
+				encryptionKey,
+				expiresIn: args.accessTokenTTLSeconds,
+				audience: args.resource,
+				env: args.env
+			}),
+			token_type: "bearer",
+			expires_in: args.accessTokenTTLSeconds,
+			scope: tokenScopes.join(" "),
+			resource: args.resource
+		};
+	}
+	/**
 	* Handles OAuth 2.0 token revocation requests (RFC 7009)
 	* @param body - The parsed request body containing revocation parameters
 	* @param env - Cloudflare Worker environment variables
@@ -851,7 +1819,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async revokeToken(body, env) {
 		const token = body.token;
-		if (!token) return this.createErrorResponse("invalid_request", "Token parameter is required");
+		if (!token) return this.createErrorResponse("invalid_request", { description: "Token parameter is required" });
 		const tokenParts = token.split(":");
 		if (tokenParts.length !== 3) return new Response("", { status: 200 });
 		const [userId, grantId, _] = tokenParts;
@@ -909,20 +1877,35 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Response with client registration data or error
 	*/
 	async handleClientRegistration(request, env) {
-		if (!this.options.clientRegistrationEndpoint) return this.createErrorResponse("not_implemented", "Client registration is not enabled", 501);
-		if (request.method !== "POST") return this.createErrorResponse("invalid_request", "Method not allowed", 405);
-		if (parseInt(request.headers.get("Content-Length") || "0", 10) > 1048576) return this.createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
+		if (!this.options.clientRegistrationEndpoint) return this.createErrorResponse("not_implemented", {
+			description: "Client registration is not enabled",
+			statusCode: 501
+		});
+		if (request.method !== "POST") return this.createErrorResponse("invalid_request", {
+			description: "Method not allowed",
+			statusCode: 405
+		});
+		if (parseInt(request.headers.get("Content-Length") || "0", 10) > 1048576) return this.createErrorResponse("invalid_request", {
+			description: "Request payload too large, must be under 1 MiB",
+			statusCode: 413
+		});
 		let clientMetadata;
 		try {
 			const text = await request.text();
-			if (text.length > 1048576) return this.createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
+			if (text.length > 1048576) return this.createErrorResponse("invalid_request", {
+				description: "Request payload too large, must be under 1 MiB",
+				statusCode: 413
+			});
 			clientMetadata = JSON.parse(text);
 		} catch (error) {
-			return this.createErrorResponse("invalid_request", "Invalid JSON payload", 400);
+			return this.createErrorResponse("invalid_request", {
+				description: "Invalid JSON payload",
+				statusCode: 400
+			});
 		}
 		const authMethod = OAuthProviderImpl.validateStringField(clientMetadata.token_endpoint_auth_method) || "client_secret_basic";
 		const isPublicClient = authMethod === "none";
-		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", "Public client registration is not allowed");
+		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", { description: "Public client registration is not allowed" });
 		const clientId = generateRandomString(16);
 		let clientSecret;
 		let hashedSecret;
@@ -956,7 +1939,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			};
 			if (!isPublicClient && hashedSecret) clientInfo.clientSecret = hashedSecret;
 		} catch (error) {
-			return this.createErrorResponse("invalid_client_metadata", error instanceof Error ? error.message : "Invalid client metadata");
+			return this.createErrorResponse("invalid_client_metadata", { description: error instanceof Error ? error.message : "Invalid client metadata" });
 		}
 		const clientKvOptions = {};
 		if (this.options.clientRegistrationTTL !== void 0) clientKvOptions.expirationTtl = this.options.clientRegistrationTTL;
@@ -998,7 +1981,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const url = new URL(request.url);
 		const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource${url.pathname}`;
 		const authHeader = request.headers.get("Authorization");
-		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") });
+		if (!authHeader || !authHeader.startsWith("Bearer ")) return this.createErrorResponse("invalid_token", {
+			description: "Missing or invalid access token",
+			statusCode: 401,
+			headers: { "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;
@@ -1010,14 +1997,26 @@ 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": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
+		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", {
+			description: "Invalid access token",
+			statusCode: 401,
+			headers: { "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": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
+			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", {
+				description: "Access token expired",
+				statusCode: 401,
+				headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
+			});
 			if (tokenData.audience) {
 				const requestUrl = new URL(request.url);
 				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") });
+				if (!(Array.isArray(tokenData.audience) ? tokenData.audience : [tokenData.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", {
+					description: "Token audience does not match resource server",
+					statusCode: 401,
+					headers: { "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) {
@@ -1026,17 +2025,28 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				request,
 				env
 			});
-			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
+			if (!ext) return this.createErrorResponse("invalid_token", {
+				description: "Invalid access token",
+				statusCode: 401,
+				headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
+			});
 			if (ext.audience) {
 				const requestUrl = new URL(request.url);
 				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") });
+				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", {
+					description: "Token audience does not match resource server",
+					statusCode: 401,
+					headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") }
+				});
 			}
 			ctx.props = ext.props;
 		}
 		if (!env.OAUTH_PROVIDER) env.OAUTH_PROVIDER = this.createOAuthHelpers(env);
 		const apiHandler = this.findApiHandlerForUrl(url);
-		if (!apiHandler) return this.createErrorResponse("invalid_request", "No handler found for API route", 404);
+		if (!apiHandler) return this.createErrorResponse("invalid_request", {
+			description: "No handler found for API route",
+			statusCode: 404
+		});
 		if (apiHandler.type === HandlerType.EXPORTED_HANDLER) return apiHandler.handler.fetch(request, env, ctx);
 		else return new apiHandler.handler(ctx, env).fetch(request);
 	}
@@ -1058,7 +2068,24 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async saveGrantWithTTL(env, grantKey, grantData, now) {
 		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: grantData.expiresAt } : {};
-		await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
+		try {
+			await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
+		} catch (error) {
+			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
+			throw error;
+		}
+	}
+	throwRetryableTokenStorageErrorIfKvRateLimited(error) {
+		if (!this.isKvRateLimitError(error)) return;
+		throw new OAuthError("temporarily_unavailable", {
+			description: "Token issuance is temporarily unavailable; retry shortly",
+			statusCode: 429,
+			headers: { "Retry-After": "30" }
+		});
+	}
+	isKvRateLimitError(error) {
+		if (!(error instanceof Error)) return false;
+		return /KV .*failed: 429 Too Many Requests/i.test(error.message) || /429 Too Many Requests/i.test(error.message);
 	}
 	/**
 	* Fetches client information from KV storage or via CIMD (Client ID Metadata Document)
@@ -1115,7 +2142,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				encryptedProps
 			}
 		};
-		await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: expiresIn });
+		try {
+			await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: expiresIn });
+		} catch (error) {
+			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
+			throw error;
+		}
 		return accessToken;
 	}
 	/**
@@ -1276,19 +2308,23 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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
-	* @param status - HTTP status code (default: 400)
-	* @param headers - Additional headers to include
-	* @returns A Response object with the error
+	* Helper function to create OAuth error responses.
+	*
+	* `internal` (optional) carries a tagged, server-side-only reason. It is
+	* forwarded to the deployer's `onError` hook but never placed on the wire,
+	* so the public response stays RFC-compliant and free of information leak
+	* while the deployer can still observe which check failed.
 	*/
-	createErrorResponse(code, description, status = 400, headers = {}) {
+	createErrorResponse(code, options, internal) {
+		const { description } = options;
+		const responseStatus = options.statusCode ?? 400;
+		const responseHeaders = options.headers ?? {};
 		const customErrorResponse = this.options.onError?.({
 			code,
 			description,
-			status,
-			headers
+			status: responseStatus,
+			headers: responseHeaders,
+			...internal ? { internal } : {}
 		});
 		if (customErrorResponse) return customErrorResponse;
 		const body = JSON.stringify({
@@ -1296,23 +2332,66 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			error_description: description
 		});
 		return new Response(body, {
-			status,
+			status: responseStatus,
 			headers: {
 				"Content-Type": "application/json",
-				...headers
+				...responseHeaders
 			}
 		});
 	}
 };
 /**
-* Error class for OAuth operations
-* Carries OAuth error code and description for proper error responses
+* Structured OAuth 2.0 error.
+*
+* Throw from a `tokenExchangeCallback` (or any code it calls — the error
+* propagates naturally up through deep call stacks) to surface a standard
+* `/token` error response (`{ error, error_description }`) instead of a
+* generic `500 Internal Server Error`.
+*
+* Anything thrown that is **not** an `OAuthError` continues to surface as
+* a 500 so unexpected failures remain visible — the provider does not
+* catch-everything-and-return-400.
+*
+* @example
+* ```ts
+* import { OAuthError } from '@cloudflare/workers-oauth-provider';
+*
+* tokenExchangeCallback: async (options) => {
+*   if (options.grantType === 'refresh_token') {
+*     // refreshUpstream() may throw OAuthError from any depth
+*     return { newProps: await refreshUpstream(options.props) };
+*   }
+* }
+*
+* async function refreshUpstream(props) {
+*   const res = await fetch(...);
+*   if (res.status === 401) {
+*     throw new OAuthError('invalid_grant', { description: 'upstream refresh token is invalid' });
+*   }
+*   if (res.status === 429) {
+*     // Mirror upstream's Retry-After if present, otherwise pick a default.
+*     throw new OAuthError('temporarily_unavailable', {
+*       description: 'upstream rate limited',
+*       statusCode: 429,
+*       headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
+*     });
+*   }
+*   return await res.json();
+* }
+* ```
 */
 var OAuthError = class extends Error {
-	constructor(code, message) {
-		super(message);
-		this.code = code;
+	constructor(code, options) {
+		super(options.description);
 		this.name = "OAuthError";
+		this.code = code;
+		this.options = {
+			...options,
+			statusCode: options.statusCode ?? 400
+		};
+		this.description = this.options.description;
+		this.statusCode = this.options.statusCode;
+		this.headers = this.options.headers;
 	}
 };
 /**
@@ -1337,6 +2416,10 @@ const DEFAULT_PURGE_BATCH_SIZE = 50;
 */
 const TOKEN_LENGTH = 32;
 /**
+* RFC 6749 Section 3.3 scope-token grammar.
+*/
+const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+/**
 * Validates a resource URI per RFC 8707 Section 2
 * @param uri - The URI string to validate
 * @returns true if valid, false otherwise
@@ -1498,6 +2581,59 @@ function base64UrlEncode(str) {
 	return btoa(str).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 /**
+* Decodes a base64url-encoded string to bytes.
+*/
+function base64UrlToBytes(base64Url) {
+	const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+	const binaryString = atob(padded);
+	const bytes = new Uint8Array(binaryString.length);
+	for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+	return bytes;
+}
+/**
+* Parses a base64url-encoded JWT JSON part into an object.
+*/
+function parseJwtJsonPart(encoded) {
+	try {
+		const json = new TextDecoder().decode(base64UrlToBytes(encoded));
+		const parsed = JSON.parse(json);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("JWT part must be an object");
+		return parsed;
+	} catch {
+		throw new Error("Malformed JWT part");
+	}
+}
+function isValidOAuthScopeToken(scopeToken) {
+	return OAUTH_SCOPE_TOKEN_PATTERN.test(scopeToken);
+}
+/**
+* Gets WebCrypto import and verify parameters for supported JOSE algorithms.
+*/
+function getJwtCryptoAlgorithms(alg) {
+	if (alg === "RS256") {
+		const algorithm = {
+			name: "RSASSA-PKCS1-v1_5",
+			hash: "SHA-256"
+		};
+		return {
+			importAlgorithm: algorithm,
+			verifyAlgorithm: algorithm
+		};
+	}
+	if (alg === "ES256") return {
+		importAlgorithm: {
+			name: "ECDSA",
+			namedCurve: "P-256"
+		},
+		verifyAlgorithm: {
+			name: "ECDSA",
+			hash: "SHA-256"
+		}
+	};
+	throw new Error(`Unsupported JWT alg: ${alg}`);
+}
+/**
 * Encodes an ArrayBuffer as base64 string
 * @param buffer - The ArrayBuffer to encode
 * @returns The base64 encoded string
@@ -2075,4 +3211,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { GrantType, OAuthProvider, oauth_provider_default as default, getOAuthApi };
+export { GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };