@cloudflare/workers-oauth-provider 0.6.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)) {
@@ -384,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
@@ -414,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,
@@ -423,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",
@@ -461,12 +1167,13 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @param env - Cloudflare Worker environment variables
 	* @returns Response with token data or error
 	*/
-	async handleTokenRequest(body, clientInfo, env) {
+	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);
@@ -545,6 +1252,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				grantType: GrantType.AUTHORIZATION_CODE,
 				clientId: clientInfo.clientId,
 				userId,
+				grantId,
 				scope: grantData.scope,
 				requestedScope: tokenScopes,
 				props: decryptedProps
@@ -664,6 +1372,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				grantType: GrantType.REFRESH_TOKEN,
 				clientId: clientInfo.clientId,
 				userId,
+				grantId,
 				scope: grantData.scope,
 				requestedScope: tokenScopes,
 				props: decryptedProps
@@ -803,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
@@ -881,6 +1591,217 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 	}
 	/**
+	* 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
@@ -1387,12 +2308,14 @@ 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 options - Error response options
-	* @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, options) {
+	createErrorResponse(code, options, internal) {
 		const { description } = options;
 		const responseStatus = options.statusCode ?? 400;
 		const responseHeaders = options.headers ?? {};
@@ -1400,7 +2323,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			code,
 			description,
 			status: responseStatus,
-			headers: responseHeaders
+			headers: responseHeaders,
+			...internal ? { internal } : {}
 		});
 		if (customErrorResponse) return customErrorResponse;
 		const body = JSON.stringify({
@@ -1492,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
@@ -1653,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
@@ -2230,4 +3211,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { GrantType, OAuthError, OAuthProvider, oauth_provider_default as default, getOAuthApi };
+export { GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };