@better-auth/oauth-provider 1.7.0-beta.8 → 1.7.0-rc.0

package/dist/{introspect-BXNvkz8S.mjs → introspect-DvHp2a64.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-wcPFST8Q.mjs";
-import { A as collectExtensionUserInfoClaims, C as toAudienceClaim, F as getSupportedGrantTypes, I as hasUserInfoClaimExtension, N as getExtensionGrantHandler, O as collectExtensionAccessTokenClaims, S as storeToken, T as validateClientCredentials, a as getClient, c as getStoredToken, f as normalizeTimestampValue, i as extractClientCredentials, k as collectExtensionIdTokenClaims, l as isPKCERequired, m as parseClientMetadata, n as decryptStoredClientSecret, o as getJwtPlugin, r as destructureCredentials, t as clientAllowsGrant, v as resolveSessionAuthTime, w as toResourceList, y as resolveSubjectIdentifier } from "./utils-Baq6atYN.mjs";
+import { A as collectExtensionUserInfoClaims, C as toAudienceClaim, F as getSupportedGrantTypes, I as hasUserInfoClaimExtension, N as getExtensionGrantHandler, O as collectExtensionAccessTokenClaims, S as storeToken, T as validateClientCredentials, a as getClient, c as getStoredToken, f as normalizeTimestampValue, i as extractClientCredentials, k as collectExtensionIdTokenClaims, l as isPKCERequired, m as parseClientMetadata, n as decryptStoredClientSecret, o as getJwtPlugin, r as destructureCredentials, t as clientAllowsGrant, v as resolveSessionAuthTime, w as toResourceList, y as resolveSubjectIdentifier } from "./utils-DO8lmoDw.mjs";
 import { APIError } from "better-auth/api";
-import { generateRandomString } from "better-auth/crypto";
+import { generateRandomString, symmetricDecrypt, symmetricEncrypt } from "better-auth/crypto";
 import { APIError as APIError$1 } from "better-call";
 import { logger } from "@better-auth/core/env";
 import * as z from "zod";
@@ -9,6 +9,156 @@ import { createDpopReplayStore, enforceDpopBinding, generateCodeChallenge, getCo
 import { SignJWT, base64url, createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 import { resolveSigningKey, signJWT, toExpJWT } from "better-auth/plugins";
 import { SafeUrlSchema } from "@better-auth/core/utils/redirect-uri";
+//#region src/authentication-context.ts
+const RESERVED_ID_TOKEN_CLAIMS = new Set([
+	"iss",
+	"sub",
+	"aud",
+	"exp",
+	"nbf",
+	"iat",
+	"jti",
+	"auth_time",
+	"nonce",
+	"acr",
+	"amr",
+	"azp",
+	"sid",
+	"at_hash",
+	"c_hash",
+	"s_hash"
+]);
+/**
+* Removes provider-owned ID token claim names from custom claims.
+*
+* `customIdTokenClaims` is an extension point for additional claims. It must not
+* replace the issuer, subject, audience, lifetime, nonce, authorized party,
+* token-binding hashes, session binding, or authentication context that the
+* provider owns.
+*/
+function stripReservedIdTokenClaims(claims) {
+	if (!claims) return {};
+	const stripped = [];
+	const safeClaims = Object.create(null);
+	for (const [key, value] of Object.entries(claims)) {
+		if (RESERVED_ID_TOKEN_CLAIMS.has(key)) {
+			stripped.push(key);
+			continue;
+		}
+		safeClaims[key] = value;
+	}
+	if (stripped.length > 0) logger.warn(`oauth-provider: stripped reserved id-token claim name(s): ${stripped.join(", ")}. The AS owns these claim values.`);
+	return safeClaims;
+}
+//#endregion
+//#region src/claims-request.ts
+const claimRequestMemberSchema = z.union([z.null(), z.record(z.string(), z.unknown())]);
+const claimsRequestObjectSchema = z.object({
+	userinfo: z.record(z.string(), claimRequestMemberSchema).optional(),
+	id_token: z.record(z.string(), claimRequestMemberSchema).optional()
+}).passthrough();
+function parseClaimsRequestValue(value) {
+	if (typeof value === "string") try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+	return value;
+}
+function parseClaimsRequestObject(value) {
+	const parsed = parseClaimsRequestValue(value);
+	const result = claimsRequestObjectSchema.safeParse(parsed);
+	return result.success ? result.data : void 0;
+}
+const claimsRequestParameterSchema = z.union([z.string(), z.record(z.string(), z.unknown())]).superRefine((value, ctx) => {
+	if (!parseClaimsRequestObject(value)) ctx.addIssue({
+		code: "custom",
+		message: "claims must be a JSON object"
+	});
+});
+function getRequestedUserInfoClaims(value, supportedClaims) {
+	const userInfoClaims = parseClaimsRequestObject(value)?.userinfo;
+	if (!userInfoClaims) return [];
+	const names = Object.keys(userInfoClaims);
+	if (!supportedClaims) return names;
+	const allowed = new Set(supportedClaims);
+	return names.filter((name) => allowed.has(name));
+}
+function filterClaimsRequestUserInfoClaims(value, allowedUserInfoClaims) {
+	const claimsRequest = parseClaimsRequestObject(value);
+	if (!claimsRequest) return void 0;
+	const allowedClaimSet = new Set(allowedUserInfoClaims);
+	const userInfoClaims = Object.fromEntries(Object.entries(claimsRequest.userinfo ?? {}).filter(([claim]) => allowedClaimSet.has(claim)));
+	const filteredClaimsRequest = Object.keys(userInfoClaims).length ? {
+		...claimsRequest,
+		userinfo: userInfoClaims
+	} : Object.fromEntries(Object.entries(claimsRequest).filter(([key]) => key !== "userinfo"));
+	return Object.keys(filteredClaimsRequest).length ? filteredClaimsRequest : void 0;
+}
+//#endregion
+//#region src/standard-claims.ts
+function splitDisplayName(name) {
+	const parts = name.split(" ").filter((part) => part !== "");
+	if (parts.length <= 1) return {};
+	return {
+		given: parts.slice(0, -1).join(" "),
+		family: parts.at(-1)
+	};
+}
+/**
+* The OIDC Standard Claims (OIDC Core §5.1) that Better Auth resolves from its
+* own user model, each paired with the scope that requests it (§5.4).
+*
+* This is the single source for UserInfo scope-claim resolution, individual
+* `claims.userinfo` resolution, the discovery `claims_supported` advertisement,
+* and the bound on requested claim names. Adding a standard claim Better Auth
+* can resolve means adding one entry here, not editing UserInfo, the metadata,
+* and the plugin init separately.
+*
+* These claims are delivered only at the UserInfo endpoint, never the ID token:
+* the authorization code flow always issues an access token, so §5.4 routes
+* scope-requested claims to UserInfo. Deployments that support further standard
+* profile claims (such as `birthdate` or `zoneinfo`) supply them through
+* `customUserInfoClaims` and advertise them in `claims_supported`.
+*/
+const STANDARD_CLAIMS = {
+	name: {
+		scope: "profile",
+		resolve: (user) => user.name ?? void 0
+	},
+	picture: {
+		scope: "profile",
+		resolve: (user) => user.image ?? void 0
+	},
+	given_name: {
+		scope: "profile",
+		resolve: (user) => splitDisplayName(user.name).given
+	},
+	family_name: {
+		scope: "profile",
+		resolve: (user) => splitDisplayName(user.name).family
+	},
+	email: {
+		scope: "email",
+		resolve: (user) => user.email ?? void 0
+	},
+	email_verified: {
+		scope: "email",
+		resolve: (user) => user.emailVerified ?? false
+	}
+};
+const STANDARD_CLAIM_NAMES = Object.keys(STANDARD_CLAIMS);
+/**
+* The claim names this provider advertises it can supply (discovery
+* `claims_supported`): the operator's `advertisedMetadata.claims_supported`
+* override when set, otherwise the scope-derived standard set computed at plugin
+* init. Used both to advertise and to bound requested `claims.userinfo` names so
+* a client cannot pin arbitrary attacker-controlled strings onto stored tokens.
+*/
+function getSupportedClaims(opts) {
+	return opts.advertisedMetadata?.claims_supported ?? opts.claims ?? [];
+}
+//#endregion
 //#region src/claims.ts
 /**
 * Claim names the authorization server owns on a JWT access token, which no
@@ -851,11 +1001,12 @@ const dpopJktSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "dpop_jkt must be
 */
 const authorizationQuerySchema = z.object({
 	response_type: z.string().pipe(z.enum(["code"])).optional(),
+	request: z.string().optional(),
 	request_uri: z.string().optional(),
 	redirect_uri: SafeUrlSchema.optional(),
 	scope: z.string().optional(),
 	state: z.string().optional(),
-	client_id: z.string(),
+	client_id: z.string().min(1, "client_id is required"),
 	prompt: authorizationPromptSchema.optional(),
 	display: z.string().optional(),
 	ui_locales: z.string().optional(),
@@ -866,10 +1017,11 @@ const authorizationQuerySchema = z.object({
 	code_challenge: z.string().optional(),
 	code_challenge_method: z.string().pipe(z.enum(["S256"])).optional(),
 	nonce: z.string().optional(),
+	claims: claimsRequestParameterSchema.optional(),
 	dpop_jkt: dpopJktSchema.optional(),
 	resource: z.union([ResourceUriSchema, z.array(ResourceUriSchema).min(1)]).optional()
 }).passthrough();
-const storedAuthorizationQuerySchema = authorizationQuerySchema.extend({ redirect_uri: SafeUrlSchema });
+const storedAuthorizationQuerySchema = authorizationQuerySchema.extend({ redirect_uri: SafeUrlSchema.optional() });
 /**
 * Runtime schema for the authorization code verification value.
 * Validates structure on deserialization from the JSON blob stored in the DB.
@@ -930,27 +1082,20 @@ const clientRegistrationRequestSchema = z.object({
 //#endregion
 //#region src/userinfo.ts
 /**
-* Provides shared /userinfo and id_token claims functionality
+* Builds the standard OIDC claims (OIDC Core §5.1) for the UserInfo response.
+*
+* A claim is included when its backing scope was granted, or when it was named
+* individually through the `claims.userinfo` request parameter (§5.4, §5.5).
+* `sub` is always present. Values come from the one claim registry, so the
+* advertisement, the scope mapping, and the resolution cannot drift apart.
 *
 * @see https://openid.net/specs/openid-connect-core-1_0.html#NormalClaims
 */
-function userNormalClaims(user, scopes) {
-	const name = user.name.split(" ").filter((v) => v !== "");
-	const profile = {
-		name: user.name ?? void 0,
-		picture: user.image ?? void 0,
-		given_name: name.length > 1 ? name.slice(0, -1).join(" ") : void 0,
-		family_name: name.length > 1 ? name.at(-1) : void 0
-	};
-	const email = {
-		email: user.email ?? void 0,
-		email_verified: user.emailVerified ?? false
-	};
-	return {
-		sub: user.id ?? void 0,
-		...scopes.includes("profile") ? profile : {},
-		...scopes.includes("email") ? email : {}
-	};
+function userNormalClaims(user, scopes, requestedClaims = []) {
+	const requested = new Set(requestedClaims);
+	const claims = { sub: user.id ?? void 0 };
+	for (const [name, definition] of Object.entries(STANDARD_CLAIMS)) if (scopes.includes(definition.scope) || requested.has(name)) claims[name] = definition.resolve(user);
+	return claims;
 }
 /**
 * Returns the defined-valued entries of `claims`, dropping any key already
@@ -976,17 +1121,33 @@ function pickClaims(claims, base) {
 	}
 	return next;
 }
+function getUserInfoAccessToken(ctx) {
+	const authorization = ctx.headers?.get("authorization");
+	const headerAccessTokenAuthorization = parseAccessTokenAuthorization(authorization);
+	const bodyToken = ctx.request?.method === "POST" ? ctx.body?.access_token ?? void 0 : void 0;
+	if (headerAccessTokenAuthorization && bodyToken) throw new APIError("BAD_REQUEST", {
+		error_description: "Multiple access token transport methods are not allowed",
+		error: "invalid_request"
+	});
+	const accessTokenAuthorization = headerAccessTokenAuthorization ?? (bodyToken ? {
+		scheme: "Bearer",
+		token: bodyToken
+	} : void 0);
+	return {
+		authorization: accessTokenAuthorization,
+		token: accessTokenAuthorization?.token
+	};
+}
 /**
 * Handles the /oauth2/userinfo endpoint
 */
 async function userInfoEndpoint(ctx, opts) {
-	const authorization = ctx.headers?.get("authorization");
-	const accessTokenAuthorization = parseAccessTokenAuthorization(authorization);
+	const { authorization: accessTokenAuthorization } = getUserInfoAccessToken(ctx);
 	if (!accessTokenAuthorization?.token) throw new APIError("UNAUTHORIZED", {
-		error_description: "authorization header not found",
+		error_description: "access token not found",
 		error: "invalid_request"
 	});
-	const jwt = await requireActiveAccessToken(ctx, opts, accessTokenAuthorization.token);
+	const { payload: jwt, requestedUserInfoClaims: requestedClaims } = await requireActiveAccessTokenWithClaims(ctx, opts, accessTokenAuthorization.token);
 	if (getDpopJktFromPayload(jwt) && !ctx.request) throw new APIError("UNAUTHORIZED", {
 		error_description: "DPoP-bound access token requires an HTTP request context",
 		error: "invalid_token"
@@ -1023,7 +1184,7 @@ async function userInfoEndpoint(ctx, opts) {
 		error_description: "user not found",
 		error: "invalid_request"
 	});
-	const baseUserClaims = userNormalClaims(user, scopes ?? []);
+	const baseUserClaims = userNormalClaims(user, scopes ?? [], requestedClaims);
 	const clientId = jwt.client_id ?? jwt.azp;
 	const client = clientId && (opts.pairwiseSecret || hasUserInfoClaimExtension(opts)) ? await getClient(ctx, opts, clientId) : void 0;
 	if (opts.pairwiseSecret && client) baseUserClaims.sub = await resolveSubjectIdentifier(user.id, client, opts);
@@ -1033,12 +1194,14 @@ async function userInfoEndpoint(ctx, opts) {
 		user,
 		scopes,
 		jwt,
-		client: client ?? void 0
+		client: client ?? void 0,
+		requestedClaims
 	}) : {};
 	const additionalInfoUserClaims = opts.customUserInfoClaims && scopes?.length ? await opts.customUserInfoClaims({
 		user,
 		scopes,
-		jwt
+		jwt,
+		requestedClaims
 	}) : {};
 	return {
 		...baseUserClaims,
@@ -1049,6 +1212,7 @@ async function userInfoEndpoint(ctx, opts) {
 }
 //#endregion
 //#region src/token.ts
+const ID_TOKEN_SCOPE_CLAIM_GUARDS = Object.fromEntries(STANDARD_CLAIM_NAMES.map((name) => [name, void 0]));
 /**
 * Token presentation scheme implied by a confirmation: a DPoP key thumbprint
 * (`jkt`) yields `"DPoP"`; any other confirmation (including mTLS `x5t#S256`)
@@ -1183,24 +1347,22 @@ async function computeOidcHash(token, signingAlg) {
 async function createIdToken(ctx, opts, user, client, scopes, nonce, sessionId, authTime, accessToken, extraClaims) {
 	const iat = Math.floor(Date.now() / 1e3);
 	const exp = iat + (opts.idTokenExpiresIn ?? 36e3);
-	const userClaims = userNormalClaims(user, scopes);
 	const resolvedSub = await resolveSubjectIdentifier(user.id, client, opts);
 	const authTimeSec = authTime != null ? Math.floor(authTime.getTime() / 1e3) : void 0;
-	const acr = "urn:mace:incommon:iap:bronze";
-	const customClaims = opts.customIdTokenClaims ? await opts.customIdTokenClaims({
+	const customClaims = stripReservedIdTokenClaims(opts.customIdTokenClaims ? await opts.customIdTokenClaims({
 		user,
 		scopes,
 		metadata: parseClientMetadata(client.metadata)
-	}) : {};
+	}) : void 0);
 	const jwtPluginOptions = opts.disableJwtPlugin ? void 0 : getJwtPlugin(ctx.context).options;
 	const resolvedKey = !opts.disableJwtPlugin && !jwtPluginOptions?.jwt?.sign ? await resolveSigningKey(ctx, jwtPluginOptions) : void 0;
 	const signingAlg = opts.disableJwtPlugin ? "HS256" : resolvedKey?.alg ?? jwtPluginOptions?.jwks?.keyPairConfig?.alg;
 	const atHash = accessToken ? await computeOidcHash(accessToken, signingAlg) : void 0;
 	const emitSid = Boolean(client.enableEndSession || client.backchannelLogoutUri);
 	const payload = {
-		...userClaims,
+		...ID_TOKEN_SCOPE_CLAIM_GUARDS,
 		auth_time: authTimeSec,
-		acr,
+		acr: "0",
 		...customClaims,
 		at_hash: atHash,
 		iss: jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL,
@@ -1211,7 +1373,8 @@ async function createIdToken(ctx, opts, user, client, scopes, nonce, sessionId,
 		exp,
 		sid: emitSid ? sessionId : void 0
 	};
-	Object.assign(payload, pickClaims(extraClaims, payload));
+	const additiveClaims = stripReservedIdTokenClaims(extraClaims);
+	Object.assign(payload, pickClaims(additiveClaims, payload));
 	if (opts.disableJwtPlugin && !client.clientSecret) return;
 	const idToken = opts.disableJwtPlugin ? await new SignJWT(payload).setProtectedHeader({ alg: "HS256" }).sign(new TextEncoder().encode(await decryptStoredClientSecret(ctx, opts.storeClientSecret, client.clientSecret))) : await signJWT(ctx, {
 		options: jwtPluginOptions,
@@ -1246,7 +1409,7 @@ async function decodeRefreshToken(opts, token) {
 	});
 	return opts.formatRefreshToken?.decrypt ? opts.formatRefreshToken?.decrypt(token) : { token };
 }
-async function createOpaqueAccessToken(ctx, opts, user, client, scopes, payload, resources, referenceId, refreshId, confirmation) {
+async function createOpaqueAccessToken(ctx, opts, user, client, scopes, payload, resources, referenceId, authorizationCodeId, refreshId, confirmation, requestedUserInfoClaims) {
 	const iat = payload.iat ?? Math.floor(Date.now() / 1e3);
 	const exp = payload?.exp ?? iat + (opts.accessTokenExpiresIn ?? 3600);
 	const token = opts.generateOpaqueAccessToken ? await opts.generateOpaqueAccessToken() : generateRandomString(32, "A-Z", "a-z");
@@ -1258,9 +1421,11 @@ async function createOpaqueAccessToken(ctx, opts, user, client, scopes, payload,
 			sessionId: payload?.sid,
 			userId: user?.id,
 			referenceId,
+			authorizationCodeId,
 			resources,
 			refreshId,
 			confirmation,
+			requestedUserInfoClaims: requestedUserInfoClaims?.length ? requestedUserInfoClaims : void 0,
 			scopes,
 			createdAt: /* @__PURE__ */ new Date(iat * 1e3),
 			expiresAt: /* @__PURE__ */ new Date(exp * 1e3)
@@ -1315,7 +1480,24 @@ async function invalidateRefreshFamily(ctx, clientId, userId) {
 		}]
 	});
 }
-async function createRefreshToken(ctx, opts, user, referenceId, client, scopes, payload, originalRefresh, authTime, resources, confirmation) {
+async function revokeTokensIssuedForAuthorizationCode(ctx, authorizationCodeId) {
+	const deleteIssuedTokens = async (model) => {
+		try {
+			await ctx.context.adapter.deleteMany({
+				model,
+				where: [{
+					field: "authorizationCodeId",
+					value: authorizationCodeId
+				}]
+			});
+		} catch (error) {
+			ctx.context.logger.error("authorization code replay cleanup failed", error);
+		}
+	};
+	await deleteIssuedTokens("oauthAccessToken");
+	await deleteIssuedTokens("oauthRefreshToken");
+}
+async function createRefreshToken(ctx, opts, user, referenceId, authorizationCodeId, client, scopes, payload, originalRefresh, authTime, resources, confirmation, requestedUserInfoClaims) {
 	const iat = payload.iat ?? Math.floor(Date.now() / 1e3);
 	const exp = payload?.exp ?? iat + (opts.refreshTokenExpiresIn ?? 2592e3);
 	const token = opts.generateRefreshToken ? await opts.generateRefreshToken() : generateRandomString(32, "A-Z", "a-z");
@@ -1326,8 +1508,10 @@ async function createRefreshToken(ctx, opts, user, referenceId, client, scopes,
 		sessionId,
 		userId: user.id,
 		referenceId,
+		authorizationCodeId,
 		authTime,
 		confirmation,
+		requestedUserInfoClaims: requestedUserInfoClaims?.length ? requestedUserInfoClaims : void 0,
 		scopes,
 		resources,
 		createdAt: /* @__PURE__ */ new Date(iat * 1e3),
@@ -1340,6 +1524,13 @@ async function createRefreshToken(ctx, opts, user, referenceId, client, scopes,
 		})).id,
 		token: await encodeRefreshToken(opts, token, sessionId)
 	};
+	const rotatedAt = /* @__PURE__ */ new Date(iat * 1e3);
+	const rotationUpdate = {
+		revoked: rotatedAt,
+		rotatedAt
+	};
+	const reuseInterval = opts.refreshTokenReuseInterval ?? 0;
+	if (reuseInterval > 0) rotationUpdate.rotationReplayExpiresAt = /* @__PURE__ */ new Date((iat + reuseInterval) * 1e3);
 	if (!await ctx.context.adapter.incrementOne({
 		model: "oauthRefreshToken",
 		where: [{
@@ -1351,7 +1542,7 @@ async function createRefreshToken(ctx, opts, user, referenceId, client, scopes,
 			value: null
 		}],
 		increment: {},
-		set: { revoked: /* @__PURE__ */ new Date(iat * 1e3) }
+		set: rotationUpdate
 	})) throw new APIError("BAD_REQUEST", {
 		error_description: "invalid refresh token",
 		error: "invalid_grant"
@@ -1420,6 +1611,126 @@ async function resolveDpopTokenBinding(ctx, opts, params) {
 		throw error;
 	}
 }
+function normalizeReplayValues(values) {
+	return values ? [...new Set(values)].sort() : void 0;
+}
+function sameReplayValues(left, right) {
+	const normalizedLeft = normalizeReplayValues(left);
+	const normalizedRight = normalizeReplayValues(right);
+	if (normalizedLeft === void 0 || normalizedRight === void 0) return normalizedLeft === normalizedRight;
+	if (normalizedLeft.length !== normalizedRight.length) return false;
+	return normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+function confirmationReplayKey(confirmation) {
+	if (!confirmation) return;
+	if ("jkt" in confirmation) return `jkt:${confirmation.jkt}`;
+	return `x5t#S256:${confirmation["x5t#S256"]}`;
+}
+function sameConfirmation(left, right) {
+	return confirmationReplayKey(left) === confirmationReplayKey(right);
+}
+function isConfirmation(value) {
+	if (!value || typeof value !== "object") return false;
+	const confirmation = value;
+	return typeof confirmation.jkt === "string" && confirmation["x5t#S256"] === void 0 || typeof confirmation["x5t#S256"] === "string" && confirmation.jkt === void 0;
+}
+function isTokenType(value) {
+	return value === "Bearer" || value === "DPoP";
+}
+function isOAuthTokenResponse(value) {
+	if (!value || typeof value !== "object") return false;
+	const response = value;
+	return typeof response.access_token === "string" && typeof response.expires_in === "number" && typeof response.expires_at === "number" && isTokenType(response.token_type) && typeof response.scope === "string" && (response.refresh_token === void 0 || typeof response.refresh_token === "string") && (response.id_token === void 0 || typeof response.id_token === "string");
+}
+function isRefreshTokenRotationReplay(value) {
+	if (!value || typeof value !== "object") return false;
+	const replay = value;
+	const request = replay.request;
+	return !!request && Array.isArray(request.effectiveScopes) && request.effectiveScopes.every((scope) => typeof scope === "string") && (request.requestedResources === void 0 || Array.isArray(request.requestedResources) && request.requestedResources.every((resource) => typeof resource === "string")) && (request.confirmation === void 0 || isConfirmation(request.confirmation)) && isOAuthTokenResponse(replay.response);
+}
+function buildRefreshTokenRotationReplayRequest(params) {
+	const requestedResources = normalizeReplayValues(params.requestedResources);
+	return {
+		effectiveScopes: normalizeReplayValues(params.effectiveScopes) ?? [],
+		...requestedResources ? { requestedResources } : {},
+		...params.confirmation ? { confirmation: params.confirmation } : {}
+	};
+}
+function sameRefreshTokenRotationReplayRequest(left, right) {
+	return sameReplayValues(left.effectiveScopes, right.effectiveScopes) && sameReplayValues(left.requestedResources, right.requestedResources) && sameConfirmation(left.confirmation, right.confirmation);
+}
+async function encryptRefreshTokenRotationReplay(ctx, replay) {
+	return symmetricEncrypt({
+		key: ctx.context.secretConfig,
+		data: JSON.stringify(replay)
+	});
+}
+async function decryptRefreshTokenRotationReplay(ctx, value) {
+	const decrypted = await symmetricDecrypt({
+		key: ctx.context.secretConfig,
+		data: value
+	});
+	const parsed = JSON.parse(decrypted);
+	if (!isRefreshTokenRotationReplay(parsed)) return;
+	return parsed;
+}
+function isWithinRefreshTokenReuseInterval(refreshToken) {
+	return !!refreshToken.rotatedAt && !!refreshToken.rotationReplayExpiresAt && refreshToken.rotationReplayExpiresAt >= /* @__PURE__ */ new Date();
+}
+async function storeRefreshTokenRotationReplay(ctx, opts, refreshToken, request, response) {
+	if ((opts.refreshTokenReuseInterval ?? 0) <= 0) return;
+	await ctx.context.adapter.update({
+		model: "oauthRefreshToken",
+		where: [{
+			field: "id",
+			value: refreshToken.id
+		}],
+		update: { rotationReplayResponse: await encryptRefreshTokenRotationReplay(ctx, {
+			request,
+			response
+		}) }
+	});
+}
+async function getRefreshTokenRotationReplay(ctx, refreshToken, request) {
+	if (!isWithinRefreshTokenReuseInterval(refreshToken)) return;
+	if (!refreshToken.rotationReplayResponse) return;
+	try {
+		const replay = await decryptRefreshTokenRotationReplay(ctx, refreshToken.rotationReplayResponse);
+		if (!replay || !sameRefreshTokenRotationReplayRequest(replay.request, request)) return;
+		return replay.response;
+	} catch (error) {
+		ctx.context.logger.error("refresh token rotation replay failed", error);
+		return;
+	}
+}
+async function resolveRefreshTokenRotationReplayRequest(ctx, opts, params) {
+	const iat = Math.floor(Date.now() / 1e3);
+	const grantIssuance = await resolveResourceGrantIssuance(ctx, opts, {
+		clientId: params.client.clientId,
+		requestedScopes: params.scopes,
+		resources: params.resources,
+		refreshToken: params.refreshToken,
+		iat,
+		scopeExpiresAtSeconds: iat + (opts.accessTokenExpiresIn ?? 3600)
+	});
+	const confirmation = await resolveDpopTokenBinding(ctx, opts, {
+		client: params.client,
+		grantIssuance,
+		refreshToken: params.refreshToken
+	});
+	return buildRefreshTokenRotationReplayRequest({
+		effectiveScopes: grantIssuance.effectiveScopes,
+		requestedResources: params.resources,
+		confirmation
+	});
+}
+function replayRefreshTokenRotationResponse(ctx, response) {
+	const now = Math.floor(Date.now() / 1e3);
+	return ctx.json({
+		...response,
+		expires_in: Math.max(0, response.expires_at - now)
+	});
+}
 async function createUserTokens(ctx, opts, params) {
 	const { client, scopes, user, grantType, referenceId, sessionId, nonce, refreshToken: existingRefreshToken, authTime, verificationValue } = params;
 	const iat = Math.floor(Date.now() / 1e3);
@@ -1473,11 +1784,12 @@ async function createUserTokens(ctx, opts, params) {
 		verificationValue,
 		refreshToken: existingRefreshToken
 	});
-	const earlyRefreshToken = isRefreshToken && user && !isJwtAccessToken ? await createRefreshToken(ctx, opts, user, referenceId, client, effectiveScopes, {
+	const requestedUserInfoClaims = params.requestedUserInfoClaims ?? existingRefreshToken?.requestedUserInfoClaims ?? [];
+	const earlyRefreshToken = isRefreshToken && user && !isJwtAccessToken ? await createRefreshToken(ctx, opts, user, referenceId, params.authorizationCodeId, client, effectiveScopes, {
 		iat,
 		exp: refreshTokenExp,
 		sid: sessionId
-	}, existingRefreshToken, authTime, refreshResources, confirmation) : void 0;
+	}, existingRefreshToken, authTime, refreshResources, confirmation, requestedUserInfoClaims) : void 0;
 	const accessTokenClaims = isJwtAccessToken ? await resolveAccessTokenClaims({
 		ctx,
 		opts,
@@ -1504,13 +1816,13 @@ async function createUserTokens(ctx, opts, params) {
 		iat,
 		exp,
 		sid: sessionId
-	}, params?.resources, referenceId, earlyRefreshToken?.id, confirmation), earlyRefreshToken ? earlyRefreshToken : isRefreshToken && user ? createRefreshToken(ctx, opts, user, referenceId, client, effectiveScopes, {
+	}, params?.resources, referenceId, params.authorizationCodeId, earlyRefreshToken?.id, confirmation, requestedUserInfoClaims), earlyRefreshToken ? earlyRefreshToken : isRefreshToken && user ? createRefreshToken(ctx, opts, user, referenceId, params.authorizationCodeId, client, effectiveScopes, {
 		iat,
 		exp: refreshTokenExp,
 		sid: sessionId
-	}, existingRefreshToken, authTime, refreshResources, confirmation) : void 0]);
+	}, existingRefreshToken, authTime, refreshResources, confirmation, requestedUserInfoClaims) : void 0]);
 	const idToken = isIdToken ? await createIdToken(ctx, opts, user, client, effectiveScopes, nonce, sessionId, authTime, accessToken, additionalIdTokenClaims) : void 0;
-	return ctx.json({
+	const responseBody = {
 		...customFields,
 		...params.tokenResponse ?? {},
 		access_token: accessToken,
@@ -1520,37 +1832,61 @@ async function createUserTokens(ctx, opts, params) {
 		refresh_token: refreshToken?.token,
 		scope: effectiveScopes.join(" "),
 		id_token: idToken
-	});
+	};
+	if (existingRefreshToken?.id && refreshToken?.id) try {
+		await storeRefreshTokenRotationReplay(ctx, opts, existingRefreshToken, buildRefreshTokenRotationReplayRequest({
+			effectiveScopes,
+			requestedResources: params.resources,
+			confirmation
+		}), responseBody);
+	} catch (error) {
+		ctx.context.logger.error("failed to store refresh token rotation replay", error);
+	}
+	return ctx.json(responseBody);
 }
 /** Checks verification value */
 async function checkVerificationValue(ctx, opts, code, client_id, redirect_uri, resource) {
-	const verification = await ctx.context.internalAdapter.consumeVerificationValue(await storeToken(opts.storeTokens, code, "authorization_code"));
-	if (!verification) throw new APIError("UNAUTHORIZED", {
-		error_description: "invalid code",
-		error: "invalid_grant"
-	});
+	const authorizationCodeId = await storeToken(opts.storeTokens, code, "authorization_code");
+	const verification = await ctx.context.internalAdapter.consumeVerificationValue(authorizationCodeId);
+	if (!verification) {
+		await revokeTokensIssuedForAuthorizationCode(ctx, authorizationCodeId);
+		throw new APIError("BAD_REQUEST", {
+			error_description: "invalid code",
+			error: "invalid_grant"
+		});
+	}
 	let rawValue;
 	try {
 		rawValue = JSON.parse(verification.value);
 	} catch {
-		throw new APIError("UNAUTHORIZED", {
+		throw new APIError("BAD_REQUEST", {
 			error_description: "malformed verification value",
 			error: "invalid_grant"
 		});
 	}
 	const parsed = verificationValueSchema.safeParse(rawValue);
-	if (!parsed.success) throw new APIError("UNAUTHORIZED", {
+	if (!parsed.success) throw new APIError("BAD_REQUEST", {
 		error_description: "malformed verification value",
 		error: "invalid_grant"
 	});
 	const verificationValue = parsed.data;
-	if (verificationValue.query.client_id !== client_id) throw new APIError("UNAUTHORIZED", {
+	if (verificationValue.query.client_id !== client_id) throw new APIError("BAD_REQUEST", {
 		error_description: "invalid client_id",
-		error: "invalid_client"
+		error: "invalid_grant"
 	});
-	if (verificationValue.query?.redirect_uri && verificationValue.query?.redirect_uri !== redirect_uri) throw new APIError("BAD_REQUEST", {
+	const boundRedirectUri = verificationValue.query.redirect_uri;
+	if (boundRedirectUri) {
+		if (!redirect_uri) throw new APIError("BAD_REQUEST", {
+			error_description: "redirect_uri is required",
+			error: "invalid_request"
+		});
+		if (boundRedirectUri !== redirect_uri) throw new APIError("BAD_REQUEST", {
+			error_description: "redirect_uri mismatch",
+			error: "invalid_grant"
+		});
+	} else if (redirect_uri) throw new APIError("BAD_REQUEST", {
 		error_description: "redirect_uri mismatch",
-		error: "invalid_request"
+		error: "invalid_grant"
 	});
 	const storedResources = toResourceList(verificationValue.resource) ?? toResourceList(verificationValue.query.resource);
 	const effectiveResources = resource ?? storedResources;
@@ -1565,7 +1901,8 @@ async function checkVerificationValue(ctx, opts, code, client_id, redirect_uri,
 	return {
 		verificationValue,
 		effectiveResources,
-		authorizedResources: storedResources
+		authorizedResources: storedResources,
+		authorizationCodeId
 	};
 }
 /**
@@ -1583,10 +1920,6 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		error_description: "code is required",
 		error: "invalid_request"
 	});
-	if (!redirect_uri) throw new APIError("BAD_REQUEST", {
-		error_description: "redirect_uri is required",
-		error: "invalid_request"
-	});
 	const isAuthCodeWithSecret = client_id && client_secret;
 	const isAuthCodeWithPkce = client_id && code && code_verifier;
 	if (!isAuthCodeWithSecret && !isAuthCodeWithPkce && !preVerified) throw new APIError("BAD_REQUEST", {
@@ -1594,7 +1927,7 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		error: "invalid_request"
 	});
 	/** Get and check Verification Value */
-	const { verificationValue, effectiveResources, authorizedResources } = await checkVerificationValue(ctx, opts, code, client_id, redirect_uri, resources);
+	const { verificationValue, effectiveResources, authorizedResources, authorizationCodeId } = await checkVerificationValue(ctx, opts, code, client_id, redirect_uri, resources);
 	const scopes = verificationValue.query.scope?.split(" ");
 	if (!scopes) throw new APIError("INTERNAL_SERVER_ERROR", {
 		error_description: "verification scope unset",
@@ -1602,7 +1935,10 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 	});
 	/** Verify Client */
 	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, scopes, preVerified, "authorization_code", authMethod);
-	if (isPKCERequired(client, (verificationValue.query?.scope)?.split(" ") || [])) {
+	if (isPKCERequired(client, {
+		scopes: (verificationValue.query?.scope)?.split(" ") || [],
+		nonce: verificationValue.query?.nonce
+	})) {
 		if (!isAuthCodeWithPkce) throw new APIError("BAD_REQUEST", {
 			error_description: "PKCE is required for this client",
 			error: "invalid_request"
@@ -1650,6 +1986,7 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		error: "invalid_request"
 	});
 	const authTime = verificationValue.authTime != null ? normalizeTimestampValue(verificationValue.authTime) : resolveSessionAuthTime(session);
+	const requestedUserInfoClaims = getRequestedUserInfoClaims(verificationValue.query.claims, getSupportedClaims(opts));
 	return createUserTokens(ctx, opts, {
 		client,
 		scopes: verificationValue.query.scope?.split(" ") ?? [],
@@ -1660,6 +1997,8 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		nonce: verificationValue.query?.nonce,
 		authTime,
 		verificationValue,
+		authorizationCodeId,
+		requestedUserInfoClaims,
 		resources: effectiveResources,
 		originalResources: authorizedResources
 	});
@@ -1739,20 +2078,13 @@ async function handleRefreshTokenGrant(ctx, opts) {
 		error: "invalid_grant"
 	});
 	if (refreshToken.clientId !== client_id) throw new APIError("BAD_REQUEST", {
-		error_description: "invalid client_id",
-		error: "invalid_client"
+		error_description: "invalid refresh token",
+		error: "invalid_grant"
 	});
 	if (refreshToken.expiresAt < /* @__PURE__ */ new Date()) throw new APIError("BAD_REQUEST", {
 		error_description: "invalid refresh token",
 		error: "invalid_grant"
 	});
-	if (refreshToken.revoked) {
-		await invalidateRefreshFamily(ctx, client_id, refreshToken.userId);
-		throw new APIError("BAD_REQUEST", {
-			error_description: "invalid refresh token",
-			error: "invalid_grant"
-		});
-	}
 	if (resources && refreshToken.resources && !resources.every((v) => refreshToken.resources?.includes(v))) throw new APIError("BAD_REQUEST", {
 		error_description: "requested resource invalid",
 		error: "invalid_target"
@@ -1767,6 +2099,26 @@ async function handleRefreshTokenGrant(ctx, opts) {
 		});
 	}
 	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, requestedScopes ?? scopes, preVerified, "refresh_token", authMethod);
+	if (refreshToken.revoked) {
+		if (isWithinRefreshTokenReuseInterval(refreshToken)) {
+			const replay = await getRefreshTokenRotationReplay(ctx, refreshToken, await resolveRefreshTokenRotationReplayRequest(ctx, opts, {
+				client,
+				refreshToken,
+				scopes: requestedScopes ?? scopes,
+				resources: resources ?? refreshToken.resources
+			}));
+			if (replay) return replayRefreshTokenRotationResponse(ctx, replay);
+			throw new APIError("BAD_REQUEST", {
+				error_description: "invalid refresh token",
+				error: "invalid_grant"
+			});
+		}
+		await invalidateRefreshFamily(ctx, client_id, refreshToken.userId);
+		throw new APIError("BAD_REQUEST", {
+			error_description: "invalid refresh token",
+			error: "invalid_grant"
+		});
+	}
 	const user = await ctx.context.internalAdapter.findUserById(refreshToken.userId);
 	if (!user) throw new APIError("BAD_REQUEST", {
 		error_description: "user not found",
@@ -1779,10 +2131,12 @@ async function handleRefreshTokenGrant(ctx, opts) {
 		user,
 		grantType: "refresh_token",
 		referenceId: refreshToken.referenceId,
+		authorizationCodeId: refreshToken.authorizationCodeId,
 		sessionId: refreshToken.sessionId,
 		refreshToken,
 		resources: resources ?? refreshToken.resources,
-		authTime
+		authTime,
+		requestedUserInfoClaims: refreshToken.requestedUserInfoClaims
 	});
 }
 //#endregion
@@ -1790,10 +2144,17 @@ async function handleRefreshTokenGrant(ctx, opts) {
 var introspect_exports = /* @__PURE__ */ __exportAll({
 	introspectEndpoint: () => introspectEndpoint,
 	requireActiveAccessToken: () => requireActiveAccessToken,
+	requireActiveAccessTokenWithClaims: () => requireActiveAccessTokenWithClaims,
 	validateAccessToken: () => validateAccessToken
 });
 const INVALID_ACCESS_TOKEN_ERROR_DESCRIPTION = "Invalid access token";
 const INVALID_ACCESS_TOKEN_WWW_AUTHENTICATE = `Bearer error="invalid_token", error_description="${INVALID_ACCESS_TOKEN_ERROR_DESCRIPTION}"`;
+function inactiveAccessToken() {
+	return {
+		payload: { active: false },
+		requestedUserInfoClaims: []
+	};
+}
 /**
 * IMPORTANT NOTES:
 * Introspection follows RFC7662
@@ -1903,18 +2264,18 @@ async function validateOpaqueAccessToken(ctx, opts, token, clientId) {
 		error_description: "opaque access token not found",
 		error: "invalid_token"
 	});
-	if (!accessToken.expiresAt || accessToken.expiresAt < /* @__PURE__ */ new Date()) return { active: false };
-	if (accessToken.revoked) return { active: false };
+	if (!accessToken.expiresAt || accessToken.expiresAt < /* @__PURE__ */ new Date()) return inactiveAccessToken();
+	if (accessToken.revoked) return inactiveAccessToken();
 	const resources = Array.isArray(accessToken.resources) ? accessToken.resources : void 0;
 	let client;
 	if (accessToken.clientId) {
 		client = await getClient(ctx, opts, accessToken.clientId);
-		if (!client || client?.disabled) return { active: false };
+		if (!client || client?.disabled) return inactiveAccessToken();
 		if (!await isIntrospectionAuthorized(ctx, opts, {
 			introspectingClientId: clientId,
 			issuerClientId: accessToken.clientId,
 			audienceResources: resources ?? []
-		})) return { active: false };
+		})) return inactiveAccessToken();
 	}
 	const sessionId = accessToken.sessionId ?? void 0;
 	if (sessionId) {
@@ -1925,12 +2286,12 @@ async function validateOpaqueAccessToken(ctx, opts, token, clientId) {
 				value: sessionId
 			}]
 		});
-		if (!session || session.expiresAt < /* @__PURE__ */ new Date()) return { active: false };
+		if (!session || session.expiresAt < /* @__PURE__ */ new Date()) return inactiveAccessToken();
 	}
 	let user;
 	if (accessToken.userId) user = await ctx.context.internalAdapter.findUserById(accessToken?.userId);
 	const userInfoEndpoint = `${ctx.context.baseURL}/oauth2/userinfo`;
-	if (resources?.length && !await isAudienceClaimAllowed(ctx, opts, resources, [userInfoEndpoint])) return { active: false };
+	if (resources?.length && !await isAudienceClaimAllowed(ctx, opts, resources, [userInfoEndpoint])) return inactiveAccessToken();
 	const audienceClaim = resources ? [...resources] : void 0;
 	if (audienceClaim?.length && accessToken.scopes?.includes("openid")) {
 		if (!audienceClaim.includes(userInfoEndpoint)) audienceClaim.push(userInfoEndpoint);
@@ -1952,19 +2313,22 @@ async function validateOpaqueAccessToken(ctx, opts, token, clientId) {
 	}) : {};
 	const jwtPluginOptions = (opts.disableJwtPlugin ? void 0 : getJwtPlugin(ctx.context))?.options;
 	return {
-		...accessTokenClaims,
-		active: true,
-		iss: jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL,
-		aud: toAudienceClaim(audienceClaim),
-		client_id: accessToken.clientId,
-		azp: accessToken.clientId,
-		sub: user?.id,
-		sid: sessionId,
-		exp: Math.floor(new Date(accessToken.expiresAt).getTime() / 1e3),
-		iat: Math.floor(new Date(accessToken.createdAt).getTime() / 1e3),
-		scope: accessToken.scopes?.join(" "),
-		token_type: confirmationTokenType(accessToken.confirmation),
-		...accessToken.confirmation ? { cnf: accessToken.confirmation } : {}
+		payload: {
+			...accessTokenClaims,
+			active: true,
+			iss: jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL,
+			aud: toAudienceClaim(audienceClaim),
+			client_id: accessToken.clientId,
+			azp: accessToken.clientId,
+			sub: user?.id,
+			sid: sessionId,
+			exp: Math.floor(new Date(accessToken.expiresAt).getTime() / 1e3),
+			iat: Math.floor(new Date(accessToken.createdAt).getTime() / 1e3),
+			scope: accessToken.scopes?.join(" "),
+			token_type: confirmationTokenType(accessToken.confirmation),
+			...accessToken.confirmation ? { cnf: accessToken.confirmation } : {}
+		},
+		requestedUserInfoClaims: accessToken.requestedUserInfoClaims ?? []
 	};
 }
 /**
@@ -2023,16 +2387,17 @@ function isInactiveTokenError(error) {
 	return error.status === "BAD_REQUEST" || error.body?.error === "invalid_token";
 }
 /**
-* We don't know the access token format so we try to validate it
-* as a JWT first, then as an opaque token.
-*
-* @returns RFC7662 introspection format
-*
-* @internal
+* We don't know the access token format so we try to validate it as a JWT
+* first, then as an opaque token. Returns the RFC 7662 introspection payload
+* alongside the per-issuance UserInfo claims the opaque row persisted (empty for
+* a JWT access token, which resolves UserInfo claims by scope).
 */
-async function validateAccessToken(ctx, opts, token, clientId) {
+async function resolveAccessTokenValidation(ctx, opts, token, clientId) {
 	try {
-		return await validateJwtAccessToken(ctx, opts, token, clientId);
+		return {
+			payload: await validateJwtAccessToken(ctx, opts, token, clientId),
+			requestedUserInfoClaims: []
+		};
 	} catch (err) {
 		if (err instanceof APIError$1) {} else if (err instanceof Error) throw err;
 		else throw new Error(err);
@@ -2045,12 +2410,35 @@ async function validateAccessToken(ctx, opts, token, clientId) {
 	}
 	throw createInvalidAccessTokenError();
 }
+/**
+* Validates an access token (JWT or opaque) and returns its RFC 7662
+* introspection-format payload.
+*
+* @internal
+*/
+async function validateAccessToken(ctx, opts, token, clientId) {
+	return (await resolveAccessTokenValidation(ctx, opts, token, clientId)).payload;
+}
 async function requireActiveAccessToken(ctx, opts, token, clientId) {
 	const payload = await validateAccessToken(ctx, opts, token, clientId);
 	if (payload.active) return payload;
 	throw createInvalidAccessTokenError();
 }
 /**
+* UserInfo entry point: validates the access token, requires it active, and
+* returns the introspection payload together with the OIDC `claims.userinfo`
+* names persisted for the token. Opaque tokens carry the names on their row;
+* JWT access tokens return an empty list and resolve UserInfo claims by scope.
+*/
+async function requireActiveAccessTokenWithClaims(ctx, opts, token, clientId) {
+	const { payload, requestedUserInfoClaims } = await resolveAccessTokenValidation(ctx, opts, token, clientId);
+	if (payload.active) return {
+		payload,
+		requestedUserInfoClaims
+	};
+	throw createInvalidAccessTokenError();
+}
+/**
 * Resolves pairwise sub on an introspection payload.
 * Applied at the presentation layer so internal validation functions
 * keep real user.id (needed for user lookup in /userinfo).
@@ -2116,4 +2504,4 @@ async function introspectEndpoint(ctx, opts) {
 	}
 }
 //#endregion
-export { invalidateResourceCache as _, invalidateRefreshFamily as a, resolveResourcePolicy as b, ResourceUriSchema as c, clientRegistrationRequestSchema as d, JWS_ALGORITHMS as f, getResource as g, extractRepeatedResourceFromForm as h, getOAuthProviderApi as i, SafeUrlSchema as l, buildClientResourceLinkId as m, introspect_exports as n, tokenEndpoint as o, assertIdentifierValid as p, decodeRefreshToken as r, userInfoEndpoint as s, introspectEndpoint as t, authorizationQuerySchema as u, isAudienceClaimAllowed as v, seedResources as x, logEnforcePerClientResourcesResolution as y };
+export { STANDARD_CLAIM_NAMES as C, getRequestedUserInfoClaims as D, filterClaimsRequestUserInfoClaims as E, STANDARD_CLAIMS as S, claimsRequestParameterSchema as T, invalidateResourceCache as _, invalidateRefreshFamily as a, resolveResourcePolicy as b, ResourceUriSchema as c, clientRegistrationRequestSchema as d, JWS_ALGORITHMS as f, getResource as g, extractRepeatedResourceFromForm as h, getOAuthProviderApi as i, SafeUrlSchema as l, buildClientResourceLinkId as m, introspect_exports as n, tokenEndpoint as o, assertIdentifierValid as p, decodeRefreshToken as r, userInfoEndpoint as s, introspectEndpoint as t, authorizationQuerySchema as u, isAudienceClaimAllowed as v, getSupportedClaims as w, seedResources as x, logEnforcePerClientResourcesResolution as y };