@better-auth/oauth-provider 1.7.9 → 1.8.0-beta.0

package/dist/{introspect-7WCMPe5Z.mjs → introspect-CEo9Q06v.mjs}

@@ -1,56 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-wcPFST8Q.mjs";
-import { A as collectExtensionAccessTokenClaims, C as storeToken, E as validateClientCredentials, F as getExtensionGrantHandler, L as getSupportedGrantTypes, M as collectExtensionUserInfoClaims, R as hasUserInfoClaimExtension, T as toResourceList, a as getClient, b as resolveSubjectIdentifier, c as getStoredToken, h as parseClientMetadata, i as extractClientCredentials, j as collectExtensionIdTokenClaims, l as isPKCERequired, n as decryptStoredClientSecret, o as getJwtPlugin, p as normalizeTimestampValue, r as destructureCredentials, t as clientAllowsGrant, w as toAudienceClaim, y as resolveSessionAuthTime } from "./utils-DKU5wblX.mjs";
+import { B as collectExtensionIdTokenClaims, D as resolveSessionAuthTime, F as validateClientCredentials, G as getExtensionGrantHandler, I as validateClientScopes, J as getSupportedGrantTypes, M as toAudienceClaim, N as toResourceList, O as resolveSubjectIdentifier, V as collectExtensionUserInfoClaims, X as hasUserInfoClaimExtension, a as decryptStoredClientSecret, c as extractClientCredentials, f as getJwtPlugin, h as isPKCERequired, j as storeToken, m as getStoredToken, r as clientAllowsGrant, s as destructureCredentials, u as getClient, x as parseClientMetadata, y as normalizeTimestampValue, z as collectExtensionAccessTokenClaims } from "./utils-BMNe8Sg2.mjs";
 import { APIError } from "better-auth/api";
 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";
 import { createDpopReplayStore, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, isDpopBindingError, isDpopProofError, parseAccessTokenAuthorization, stripAccessTokenAuthorizationScheme, verifyDpopProof } from "better-auth/oauth2";
-import { SignJWT, base64url, createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 import { SafeUrlSchema } from "@better-auth/core/utils/redirect-uri";
 import { resolveSigningKey, signJWT, toExpJWT } from "better-auth/plugins";
-//#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
+import { SignJWT, base64url, createLocalJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 //#region src/claims-request.ts
 const claimRequestMemberSchema = z.record(z.string(), z.unknown()).nullable();
 const acrClaimRequestMemberSchema = z.looseObject({
@@ -99,6 +57,18 @@ function canSatisfyEssentialAcrRequest(value, currentAcr) {
 	const valuesMatch = acrRequest.values === void 0 || acrRequest.values.includes(currentAcr);
 	return valueMatches && valuesMatch;
 }
+/**
+* Lists the ACR values requested through `claims.id_token.acr` and the
+* space-separated `acr_values` parameter, without duplicates.
+*/
+function getRequestedAcrValues(claims, acrValues) {
+	const acrRequest = parseOidcClaimsRequestObject(claims)?.id_token?.acr;
+	return Array.from(new Set([
+		...acrRequest?.value !== void 0 ? [acrRequest.value] : [],
+		...acrRequest?.values ?? [],
+		...acrValues?.split(" ").filter(Boolean) ?? []
+	]));
+}
 function filterClaimsRequestUserInfoClaims(value, allowedUserInfoClaims) {
 	const claimsRequest = parseOidcClaimsRequestObject(value);
 	if (!claimsRequest) return void 0;
@@ -110,6 +80,81 @@ function filterClaimsRequestUserInfoClaims(value, allowedUserInfoClaims) {
 	} : Object.fromEntries(Object.entries(claimsRequest).filter(([key]) => key !== "userinfo"));
 	return Object.keys(filteredClaimsRequest).length ? filteredClaimsRequest : void 0;
 }
+/** The ACR values the provider may assert, advertised in discovery. */
+function getAcrValuesSupported(opts) {
+	return opts.authenticationContext?.acrValuesSupported ?? ["0"];
+}
+function invalidAuthenticationContext(description) {
+	throw new APIError$1("INTERNAL_SERVER_ERROR", {
+		error: "server_error",
+		error_description: `authenticationContext.resolve ${description}`
+	});
+}
+/**
+* Runs the configured `authenticationContext.resolve` for an approval and
+* validates its result. Returns an empty context, which ID tokens report as
+* `acr: "0"`, when no resolver is configured or no ID token can be issued.
+* Invalid results throw an `APIError` with `server_error`.
+*/
+async function resolveAuthenticationContext(opts, info) {
+	const resolve = opts.authenticationContext?.resolve;
+	if (!resolve || !info.scopes.includes("openid")) return {};
+	const { query, ...resolveInfo } = info;
+	const resolved = await resolve({
+		...resolveInfo,
+		requestedAcrValues: getRequestedAcrValues(query.claims, query.acr_values)
+	});
+	if (resolved !== void 0 && (typeof resolved !== "object" || resolved === null)) invalidAuthenticationContext("returned a value that is not an object");
+	const { acr = "0", amr } = resolved ?? {};
+	if (typeof acr !== "string") invalidAuthenticationContext("returned a non-string acr");
+	if (!getAcrValuesSupported(opts).includes(acr)) invalidAuthenticationContext(`returned acr "${acr}", which is not in acrValuesSupported`);
+	if (amr === void 0) return { acr };
+	if (!Array.isArray(amr) || !Array.from(amr).every((value) => typeof value === "string")) invalidAuthenticationContext("returned an amr that is not a string array");
+	return {
+		acr,
+		amr: amr.length ? amr : void 0
+	};
+}
+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/standard-claims.ts
 function splitDisplayName(name) {
@@ -198,7 +243,8 @@ const RESERVED_ACCESS_TOKEN_CLAIMS = new Set([
 	"auth_time",
 	"acr",
 	"amr",
-	"cnf"
+	"cnf",
+	"reference_id"
 ]);
 /**
 * Returns a copy of `claims` with reserved AS-owned names removed. Emits a
@@ -388,6 +434,8 @@ const verificationValueSchema = z.object({
 	userId: z.string(),
 	referenceId: z.string().optional(),
 	authTime: z.number().optional(),
+	acr: z.string().optional(),
+	amr: z.array(z.string()).optional(),
 	resource: z.array(z.string()).optional()
 }).passthrough();
 /**
@@ -418,6 +466,8 @@ const clientRegistrationRequestSchema = z.object({
 	post_logout_redirect_uris: z.array(SafeUrlSchema).min(1).optional(),
 	backchannel_logout_uri: SafeUrlSchema.optional(),
 	backchannel_logout_session_required: z.boolean().optional(),
+	frontchannel_logout_uri: SafeUrlSchema.optional(),
+	frontchannel_logout_session_required: z.boolean().optional(),
 	token_endpoint_auth_method: z.string().trim().min(1).optional(),
 	jwks: clientJwksSchema.optional(),
 	jwks_uri: z.string().optional(),
@@ -525,40 +575,6 @@ async function assertIdentifierValid(opts, identifier) {
 */
 const userInfoResource = (baseURL) => `${baseURL}/oauth2/userinfo`;
 /**
-* Re-parses a request's raw `application/x-www-form-urlencoded` body to
-* recover every value of the repeated `resource` parameter (RFC 8707 §2).
-*
-* Workaround for better-call's form-body parser (better-call ≤1.3.5), which
-* collapses repeated form keys with last-write-wins. A client sending
-* `resource=https://a&resource=https://b` would otherwise arrive in the
-* handler as `{ resource: "https://b" }`, silently narrowing the issued
-* token's `aud` to a single resource.
-*
-* Returns the full ordered list when the body is form-encoded and contains
-* any `resource` entries; `undefined` otherwise. Caller MUST enable
-* `cloneRequest: true` on the endpoint — the body stream is read here a
-* second time, and that only works when better-call cloned the request
-* before its own parse.
-*
-* Note: the URL-encoded body path is the only one affected. The query-string
-* path (e.g. `/oauth2/authorize?resource=…&resource=…`) is parsed by the
-* router itself, which DOES array-promote duplicate keys correctly.
-*
-* @internal
-*/
-async function extractRepeatedResourceFromForm(request) {
-	if (!(request.headers.get("content-type")?.toLowerCase() ?? "").includes("application/x-www-form-urlencoded")) return;
-	let text;
-	try {
-		text = await request.clone().text();
-	} catch {
-		return;
-	}
-	if (!text) return void 0;
-	const values = new URLSearchParams(text).getAll("resource").filter((value) => value.length > 0);
-	return values.length > 0 ? values : void 0;
-}
-/**
 * Normalizes a `resource` parameter into an array. Accepts the RFC 8707
 * forms: a single string, a string[], or undefined.
 *
@@ -1084,14 +1100,21 @@ function getDpopProofJwt(ctx) {
 	return ctx.headers?.get("dpop") ?? void 0;
 }
 /**
-* The endpoint's public URL, built from `baseURL`, which clients use as the
-* DPoP `htu`. Not `request.url`: proxies and dev servers can rewrite its host.
+* The endpoint's public URL, which clients use as the DPoP `htu`: the origin
+* and base path of `baseURL` (not `request.url`, whose host proxies and dev
+* servers can rewrite) plus the request's own path below the base path, so
+* route params and a trailing slash match what the client called. `path` is
+* used when there is no HTTP request, such as an `auth.api` call.
 */
 function getEndpointUrl(ctx, path) {
 	const { baseURL } = ctx.context;
 	let end = baseURL.length;
 	while (end > 0 && baseURL[end - 1] === "/") end--;
-	return `${baseURL.slice(0, end)}${path}`;
+	const base = baseURL.slice(0, end);
+	if (!ctx.request || !base) return `${base}${path}`;
+	const basePath = new URL(base).pathname.replace(/\/$/, "");
+	const requestPath = new URL(ctx.request.url).pathname;
+	return `${base}${requestPath.startsWith(`${basePath}/`) ? requestPath.slice(basePath.length) : path}`;
 }
 //#endregion
 //#region src/oauthClient/client-credentials.ts
@@ -1125,6 +1148,129 @@ function validateClientCredentialsScopes(scopes, grantTypes, tokenEndpointAuthMe
 	});
 }
 //#endregion
+//#region src/token-lookup.ts
+const jwksInfrastructureErrorCodes = new Set([
+	errors.JWKSTimeout.code,
+	errors.JWKSInvalid.code,
+	errors.JWKSMultipleMatchingKeys.code
+]);
+/**
+* Verifies a JWT access token issued by this server. Returns `"inactive"` for
+* one that is expired or fails claim validation, so the lookup can stop: it
+* cannot be another token type. Returns `null` for anything else (an opaque
+* token, a malformed or forged JWT, a JWT that is not an access token) so the
+* lookup can continue. Key-set failures still throw.
+*/
+async function verifyJwtAccessToken(ctx, opts, token) {
+	if (opts.disableJwtPlugin) return null;
+	if (token.split(".").length !== 3) return null;
+	try {
+		decodeProtectedHeader(token);
+	} catch {
+		return null;
+	}
+	const jwtPlugin = getJwtPlugin(ctx.context);
+	const jwtPluginOptions = jwtPlugin.options;
+	const jwks = await getJwks(token, {
+		jwksFetch: jwtPluginOptions?.jwks?.remoteUrl ? jwtPluginOptions.jwks.remoteUrl : async () => {
+			return (await jwtPlugin.endpoints.getJwks(ctx))?.response;
+		},
+		jwksCacheKey: jwtPlugin
+	});
+	let payload;
+	try {
+		({payload} = await jwtVerify(token, createLocalJWKSet(jwks), { issuer: jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL }));
+	} catch (error) {
+		if (error instanceof errors.JWTExpired || error instanceof errors.JWTClaimValidationFailed) return isAccessTokenPayload(error.payload) ? "inactive" : null;
+		if (error instanceof errors.JOSEError && !jwksInfrastructureErrorCodes.has(error.code)) return null;
+		throw error;
+	}
+	return isAccessTokenPayload(payload) ? payload : null;
+}
+/**
+* The OAuth token endpoint stamps `azp` (the client) on every JWT access token.
+* The JWT plugin signs other JWTs with the same issuer and keys, such as its
+* `/token` session JWT, so one without `azp` is not an access token.
+*/
+function isAccessTokenPayload(payload) {
+	return typeof payload.azp === "string" && payload.azp.length > 0;
+}
+async function findOpaqueAccessToken(ctx, opts, token) {
+	const prefix = opts.prefix?.opaqueAccessToken;
+	if (prefix && !token.startsWith(prefix)) return null;
+	return ctx.context.adapter.findOne({
+		model: "oauthAccessToken",
+		where: [{
+			field: "token",
+			value: await getStoredToken(opts.storeTokens, prefix ? token.slice(prefix.length) : token, "access_token")
+		}]
+	});
+}
+/**
+* Looks up a refresh token by its presented value, after removing the
+* configured prefix and applying `formatRefreshToken.decrypt`. Returns `null`
+* when the value is not a refresh token this server stored.
+*/
+async function findRefreshToken(ctx, opts, token) {
+	const prefix = opts.prefix?.refreshToken;
+	if (prefix && !token.startsWith(prefix)) return null;
+	const value = prefix ? token.slice(prefix.length) : token;
+	let decoded;
+	try {
+		decoded = opts.formatRefreshToken?.decrypt ? await opts.formatRefreshToken.decrypt(value) : { token: value };
+	} catch (error) {
+		if (error instanceof APIError$1 && error.statusCode === 400 || error instanceof errors.JOSEError) return null;
+		throw error;
+	}
+	return ctx.context.adapter.findOne({
+		model: "oauthRefreshToken",
+		where: [{
+			field: "token",
+			value: await getStoredToken(opts.storeTokens, decoded.token, "refresh_token")
+		}]
+	});
+}
+async function identifyAccessToken(ctx, opts, token) {
+	const payload = await verifyJwtAccessToken(ctx, opts, token);
+	if (payload === "inactive") return payload;
+	if (payload) return {
+		type: "jwt",
+		payload
+	};
+	const record = await findOpaqueAccessToken(ctx, opts, token);
+	return record ? {
+		type: "opaque",
+		record
+	} : null;
+}
+/**
+* Identifies an access token as a JWT or an opaque token issued by this
+* server. Returns `null` when it is neither, including an expired JWT.
+*/
+async function findAccessToken(ctx, opts, token) {
+	const found = await identifyAccessToken(ctx, opts, token);
+	return found === "inactive" ? null : found;
+}
+/**
+* Identifies a token presented to revocation or introspection. Every token
+* type is searched; `token_type_hint` only decides which one is tried first
+* (RFC 7009 §2.1, RFC 7662 §2.1). Returns `null` when no type matches. Only
+* infrastructure failures (key set, database, refresh-token decryption) throw.
+*/
+async function findToken(ctx, opts, token, tokenTypeHint) {
+	const asRefreshToken = async () => {
+		const record = await findRefreshToken(ctx, opts, token);
+		return record ? {
+			type: "refresh",
+			record
+		} : null;
+	};
+	if (tokenTypeHint === "refresh_token") return await asRefreshToken() ?? findAccessToken(ctx, opts, token);
+	const found = await identifyAccessToken(ctx, opts, token);
+	if (found === "inactive") return null;
+	return found ?? asRefreshToken();
+}
+//#endregion
 //#region src/userinfo.ts
 /**
 * Builds the standard OIDC claims (OIDC Core §5.1) for the UserInfo response.
@@ -1335,6 +1481,18 @@ function getOAuthProviderApi(ctx, opts, grantType) {
 				grantType
 			});
 		},
+		resolveConfirmation: async (params) => {
+			if (params.confirmation) return params.confirmation;
+			const policy = await resolveResourcePolicy(ctx, opts, {
+				resource: params.resources,
+				clientId: params.client.clientId,
+				requestedScopes: params.scopes
+			});
+			return resolveDpopTokenBinding(ctx, opts, {
+				client: params.client,
+				grantIssuance: { dpopBoundAccessTokensRequired: policy.dpopBoundAccessTokensRequired }
+			});
+		},
 		hashToken: (token, type) => storeToken(opts.storeTokens, token, type),
 		validateAccessToken: async (token, clientId) => {
 			const { validateAccessToken } = await Promise.resolve().then(() => introspect_exports);
@@ -1364,6 +1522,7 @@ async function createJwtAccessToken(ctx, opts, user, client, audienceClaim, scop
 			azp: client.clientId,
 			scope: scopes.join(" "),
 			sid: overrides?.sid,
+			reference_id: overrides?.referenceId,
 			iss: jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL,
 			iat,
 			exp,
@@ -1389,7 +1548,7 @@ async function computeOidcHash(token, signingAlg) {
 * Creates a user id token in code_authorization with scope of 'openid'
 * and hybrid/implicit (not yet implemented) flows
 */
-async function createIdToken(ctx, opts, user, client, scopes, nonce, sessionId, authTime, accessToken, extraClaims) {
+async function createIdToken(ctx, opts, user, client, scopes, nonce, sessionId, authTime, accessToken, extraClaims, authenticationContext) {
 	const iat = Math.floor(Date.now() / 1e3);
 	const exp = iat + (opts.idTokenExpiresIn ?? 36e3);
 	const resolvedSub = await resolveSubjectIdentifier(user.id, client, opts);
@@ -1403,11 +1562,12 @@ async function createIdToken(ctx, opts, user, client, scopes, nonce, sessionId,
 	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 emitSid = Boolean(client.enableEndSession || client.backchannelLogoutUri || client.frontchannelLogoutUri);
 	const payload = {
 		...ID_TOKEN_SCOPE_CLAIM_GUARDS,
 		auth_time: authTimeSec,
-		acr: "0",
+		acr: authenticationContext?.acr ?? "0",
+		amr: authenticationContext?.amr,
 		...customClaims,
 		at_hash: atHash,
 		iss: jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL,
@@ -1439,20 +1599,7 @@ async function createIdToken(ctx, opts, user, client, scopes, nonce, sessionId,
 * Encodes a refresh token for a client
 */
 async function encodeRefreshToken(opts, token, sessionId) {
-	return (opts.prefix?.refreshToken ?? "") + (opts.formatRefreshToken?.encrypt ? opts.formatRefreshToken.encrypt(token, sessionId) : token);
-}
-/**
-* Decodes a refresh token for a client
-*
-* @internal
-*/
-async function decodeRefreshToken(opts, token) {
-	if (opts.prefix?.refreshToken) if (token.startsWith(opts.prefix.refreshToken)) token = token.replace(opts.prefix.refreshToken, "");
-	else throw new APIError("BAD_REQUEST", {
-		error_description: "refresh token not found",
-		error: "invalid_token"
-	});
-	return opts.formatRefreshToken?.decrypt ? opts.formatRefreshToken?.decrypt(token) : { token };
+	return (opts.prefix?.refreshToken ?? "") + (opts.formatRefreshToken?.encrypt ? await opts.formatRefreshToken.encrypt(token, sessionId) : token);
 }
 async function createOpaqueAccessToken(ctx, opts, user, client, scopes, payload, resources, referenceId, authorizationCodeId, refreshId, confirmation, requestedUserInfoClaims) {
 	const iat = payload.iat ?? Math.floor(Date.now() / 1e3);
@@ -1542,7 +1689,7 @@ async function revokeTokensIssuedForAuthorizationCode(ctx, authorizationCodeId)
 	await deleteIssuedTokens("oauthAccessToken");
 	await deleteIssuedTokens("oauthRefreshToken");
 }
-async function createRefreshToken(ctx, opts, user, referenceId, authorizationCodeId, client, scopes, payload, originalRefresh, authTime, resources, confirmation, requestedUserInfoClaims) {
+async function createRefreshToken(ctx, opts, user, referenceId, authorizationCodeId, client, scopes, payload, originalRefresh, authTime, resources, confirmation, requestedUserInfoClaims, authenticationContext) {
 	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");
@@ -1555,6 +1702,8 @@ async function createRefreshToken(ctx, opts, user, referenceId, authorizationCod
 		referenceId,
 		authorizationCodeId,
 		authTime,
+		acr: authenticationContext?.acr,
+		amr: authenticationContext?.amr,
 		confirmation,
 		requestedUserInfoClaims: requestedUserInfoClaims?.length ? requestedUserInfoClaims : void 0,
 		scopes,
@@ -1777,9 +1926,18 @@ function replayRefreshTokenRotationResponse(ctx, response) {
 	});
 }
 async function createUserTokens(ctx, opts, params) {
-	const { client, scopes, user, grantType, referenceId, sessionId, nonce, refreshToken: existingRefreshToken, authTime, verificationValue } = params;
+	const { client, scopes, user, grantType, referenceId, sessionId, nonce, refreshToken: existingRefreshToken, authTime, acr, amr, verificationValue } = params;
+	const authenticationContext = {
+		acr,
+		amr
+	};
 	const iat = Math.floor(Date.now() / 1e3);
-	const defaultExp = iat + (user ? opts.accessTokenExpiresIn ?? 3600 : opts.m2mAccessTokenExpiresIn ?? 3600);
+	const baseExpiry = user ? opts.accessTokenExpiresIn ?? 3600 : opts.m2mAccessTokenExpiresIn ?? 3600;
+	const defaultExp = Math.min(iat + baseExpiry, params.maxExpiresAt ? Math.floor(params.maxExpiresAt.getTime() / 1e3) : Number.POSITIVE_INFINITY);
+	if (defaultExp <= iat) throw new APIError("BAD_REQUEST", {
+		error: "invalid_request",
+		error_description: "the token this grant derives from has expired"
+	});
 	const scopeExp = opts.scopeExpirations ? scopes.map((sc) => opts.scopeExpirations?.[sc] ? toExpJWT(opts.scopeExpirations[sc], iat) : defaultExp).reduce((prev, curr) => {
 		return prev < curr ? prev : curr;
 	}, defaultExp) : defaultExp;
@@ -1834,7 +1992,7 @@ async function createUserTokens(ctx, opts, params) {
 		iat,
 		exp: refreshTokenExp,
 		sid: sessionId
-	}, existingRefreshToken, authTime, refreshResources, confirmation, requestedUserInfoClaims) : void 0;
+	}, existingRefreshToken, authTime, refreshResources, confirmation, requestedUserInfoClaims, authenticationContext) : void 0;
 	const accessTokenClaims = isJwtAccessToken ? await resolveAccessTokenClaims({
 		ctx,
 		opts,
@@ -1853,6 +2011,7 @@ async function createUserTokens(ctx, opts, params) {
 		iat,
 		exp,
 		sid: sessionId,
+		referenceId,
 		signingAlgorithm: grantIssuance.signingAlgorithm,
 		signingKeyId: grantIssuance.signingKeyId,
 		accessTokenClaims,
@@ -1865,8 +2024,8 @@ async function createUserTokens(ctx, opts, params) {
 		iat,
 		exp: refreshTokenExp,
 		sid: sessionId
-	}, existingRefreshToken, authTime, refreshResources, confirmation, requestedUserInfoClaims) : void 0]);
-	const idToken = isIdToken ? await createIdToken(ctx, opts, user, client, effectiveScopes, nonce, sessionId, authTime, accessToken, additionalIdTokenClaims) : void 0;
+	}, existingRefreshToken, authTime, refreshResources, confirmation, requestedUserInfoClaims, authenticationContext) : void 0]);
+	const idToken = isIdToken ? await createIdToken(ctx, opts, user, client, effectiveScopes, nonce, sessionId, authTime, accessToken, additionalIdTokenClaims, authenticationContext) : void 0;
 	const responseBody = {
 		...customFields,
 		...params.tokenResponse ?? {},
@@ -1971,6 +2130,10 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		error_description: "Either code_verifier or client_secret is required",
 		error: "invalid_request"
 	});
+	/** Verify Client (RFC 6749 §5.2: an unknown or unauthenticated client is
+	* `invalid_client`, so resolve it before the code lookup can report
+	* `invalid_grant` and before a one-time code is consumed). */
+	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, void 0, preVerified, "authorization_code", authMethod);
 	/** Get and check Verification Value */
 	const { verificationValue, effectiveResources, authorizedResources, authorizationCodeId } = await checkVerificationValue(ctx, opts, code, client_id, redirect_uri, resources);
 	const scopes = verificationValue.query.scope?.split(" ");
@@ -1978,8 +2141,7 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		error_description: "verification scope unset",
 		error: "invalid_scope"
 	});
-	/** Verify Client */
-	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, scopes, preVerified, "authorization_code", authMethod);
+	validateClientScopes(client, scopes);
 	if (isPKCERequired(client, {
 		scopes: (verificationValue.query?.scope)?.split(" ") || [],
 		nonce: verificationValue.query?.nonce
@@ -1996,17 +2158,17 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 	const pkceUsedInAuth = !!verificationValue.query?.code_challenge;
 	const pkceUsedInToken = !!code_verifier;
 	if (pkceUsedInAuth || pkceUsedInToken) {
-		if (pkceUsedInAuth && !pkceUsedInToken) throw new APIError("UNAUTHORIZED", {
+		if (pkceUsedInAuth && !pkceUsedInToken) throw new APIError("BAD_REQUEST", {
 			error_description: "code_verifier required because PKCE was used in authorization",
 			error: "invalid_request"
 		});
-		if (!pkceUsedInAuth && pkceUsedInToken) throw new APIError("UNAUTHORIZED", {
+		if (!pkceUsedInAuth && pkceUsedInToken) throw new APIError("BAD_REQUEST", {
 			error_description: "code_verifier provided but PKCE was not used in authorization",
 			error: "invalid_request"
 		});
-		if ((verificationValue.query?.code_challenge_method === "S256" ? await generateCodeChallenge(code_verifier) : void 0) !== verificationValue.query?.code_challenge) throw new APIError("UNAUTHORIZED", {
+		if ((verificationValue.query?.code_challenge_method === "S256" ? await generateCodeChallenge(code_verifier) : void 0) !== verificationValue.query?.code_challenge) throw new APIError("BAD_REQUEST", {
 			error_description: "code verification failed",
-			error: "invalid_request"
+			error: "invalid_grant"
 		});
 	}
 	/** Get user */
@@ -2041,6 +2203,8 @@ async function handleAuthorizationCodeGrant(ctx, opts) {
 		sessionId: session.id,
 		nonce: verificationValue.query?.nonce,
 		authTime,
+		acr: verificationValue.acr,
+		amr: verificationValue.amr,
 		verificationValue,
 		authorizationCodeId,
 		requestedUserInfoClaims,
@@ -2109,14 +2273,11 @@ async function handleRefreshTokenGrant(ctx, opts) {
 		error_description: "Missing a required refresh_token for refresh_token grant",
 		error: "invalid_request"
 	});
-	const decodedRefresh = await decodeRefreshToken(opts, refresh_token);
-	const refreshToken = await ctx.context.adapter.findOne({
-		model: "oauthRefreshToken",
-		where: [{
-			field: "token",
-			value: await getStoredToken(opts.storeTokens, decodedRefresh.token, "refresh_token")
-		}]
-	});
+	/** Verify Client (RFC 6749 §5.2: an unknown or unauthenticated client is
+	* `invalid_client`, so resolve it before the refresh token lookup can
+	* report `invalid_grant`). */
+	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, void 0, preVerified, "refresh_token", authMethod);
+	const refreshToken = await findRefreshToken(ctx, opts, refresh_token);
 	if (!refreshToken) throw new APIError("BAD_REQUEST", {
 		error_description: "session not found",
 		error: "invalid_grant"
@@ -2142,7 +2303,7 @@ async function handleRefreshTokenGrant(ctx, opts) {
 			error: "invalid_scope"
 		});
 	}
-	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, requestedScopes ?? scopes, preVerified, "refresh_token", authMethod);
+	validateClientScopes(client, requestedScopes ?? scopes);
 	if (refreshToken.revoked) {
 		if (isWithinRefreshTokenReuseInterval(refreshToken)) {
 			const replay = await getRefreshTokenRotationReplay(ctx, refreshToken, await resolveRefreshTokenRotationReplayRequest(ctx, opts, {
@@ -2180,6 +2341,8 @@ async function handleRefreshTokenGrant(ctx, opts) {
 		refreshToken,
 		resources: resources ?? refreshToken.resources,
 		authTime,
+		acr: refreshToken.acr ?? void 0,
+		amr: refreshToken.amr ?? void 0,
 		requestedUserInfoClaims: refreshToken.requestedUserInfoClaims
 	});
 }
@@ -2200,11 +2363,11 @@ function inactiveAccessToken() {
 	};
 }
 /**
-* IMPORTANT NOTES:
-* Introspection follows RFC7662
+* Introspection follows RFC 7662
 * https://datatracker.ietf.org/doc/html/rfc7662
-* - APIError: Continue catches (returnable to client)
-* - Error: Should immediately stop catches (internal error)
+*
+* A token this server cannot find, or one the caller may not see, resolves as
+* `{ active: false }` (§2.2, §4). Only protocol errors surface.
 */
 /**
 * Resource identifiers in a token's audience, excluding the implicit
@@ -2230,38 +2393,14 @@ async function isIntrospectionAuthorized(ctx, opts, params) {
 	return isClientLinkedToAnyResource(ctx, opts, introspectingClientId, audienceResources);
 }
 /**
-* Validates a JWT access token against the configured JWKs.
+* Validates a JWT access token whose signature and issuer are verified.
 *
 * @returns RFC7662 introspection format
 */
-async function validateJwtAccessToken(ctx, opts, token, clientId) {
-	const jwtPlugin = opts.disableJwtPlugin ? void 0 : getJwtPlugin(ctx.context);
-	const jwtPluginOptions = jwtPlugin?.options;
-	const userInfoAud = `${ctx.context.baseURL ?? ""}/oauth2/userinfo`;
-	const expectedIssuer = jwtPluginOptions?.jwt?.issuer ?? ctx.context.baseURL;
-	let jwtPayload;
-	try {
-		jwtPayload = (await jwtVerify(token, createLocalJWKSet(await getJwks(token, {
-			jwksFetch: jwtPluginOptions?.jwks?.remoteUrl ? jwtPluginOptions.jwks.remoteUrl : async () => {
-				return (await jwtPlugin?.endpoints.getJwks(ctx))?.response;
-			},
-			jwksCacheKey: jwtPlugin
-		})), { issuer: expectedIssuer })).payload;
-	} catch (error) {
-		if (error instanceof Error) {
-			if (error.name === "TypeError" || error.name === "JWSInvalid") throw new APIError$1("BAD_REQUEST", {
-				error_description: "invalid JWT signature",
-				error: "invalid_request"
-			});
-			else if (error.name === "JWTExpired") return { active: false };
-			else if (error.name === "JWTInvalid") return { active: false };
-			throw error;
-		}
-		throw new Error(error);
-	}
+async function validateJwtAccessToken(ctx, opts, jwtPayload, clientId) {
+	const userInfoAud = userInfoResource(ctx.context.baseURL ?? "");
 	const rawAud = jwtPayload.aud;
 	if (!await isAudienceClaimAllowed(ctx, opts, rawAud, [userInfoAud])) return { active: false };
-	if (!jwtPayload.azp) return { active: false };
 	const client = await getClient(ctx, opts, jwtPayload.azp);
 	if (!client || client?.disabled) return { active: false };
 	if (!await isIntrospectionAuthorized(ctx, opts, {
@@ -2286,28 +2425,11 @@ async function validateJwtAccessToken(ctx, opts, token, clientId) {
 	return jwtPayload;
 }
 /**
-* Searches for an opaque access token in the database and validates it
+* Validates an opaque access token record.
 *
 * @returns RFC7662 introspection format
 */
-async function validateOpaqueAccessToken(ctx, opts, token, clientId) {
-	let tokenValue = token;
-	if (opts.prefix?.opaqueAccessToken) if (tokenValue.startsWith(opts.prefix.opaqueAccessToken)) tokenValue = tokenValue.replace(opts.prefix.opaqueAccessToken, "");
-	else throw new APIError$1("BAD_REQUEST", {
-		error_description: "opaque access token not found",
-		error: "invalid_request"
-	});
-	const accessToken = await ctx.context.adapter.findOne({
-		model: "oauthAccessToken",
-		where: [{
-			field: "token",
-			value: await getStoredToken(opts.storeTokens, tokenValue, "access_token")
-		}]
-	});
-	if (!accessToken) throw new APIError$1("BAD_REQUEST", {
-		error_description: "opaque access token not found",
-		error: "invalid_token"
-	});
+async function validateOpaqueAccessToken(ctx, opts, accessToken, clientId) {
 	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;
@@ -2366,6 +2488,7 @@ async function validateOpaqueAccessToken(ctx, opts, token, clientId) {
 			azp: accessToken.clientId,
 			sub: user?.id,
 			sid: sessionId,
+			reference_id: accessToken.referenceId ?? void 0,
 			exp: Math.floor(new Date(accessToken.expiresAt).getTime() / 1e3),
 			iat: Math.floor(new Date(accessToken.createdAt).getTime() / 1e3),
 			scope: accessToken.scopes?.join(" "),
@@ -2376,22 +2499,11 @@ async function validateOpaqueAccessToken(ctx, opts, token, clientId) {
 	};
 }
 /**
-* Validates a refresh token in the session store.
+* Validates a refresh token record.
 *
 * @returns payload in RFC7662 introspection format
 */
-async function validateRefreshToken(ctx, opts, token, clientId) {
-	const refreshToken = await ctx.context.adapter.findOne({
-		model: "oauthRefreshToken",
-		where: [{
-			field: "token",
-			value: await getStoredToken(opts.storeTokens, token, "refresh_token")
-		}]
-	});
-	if (!refreshToken) throw new APIError$1("BAD_REQUEST", {
-		error_description: "token not found",
-		error: "invalid_token"
-	});
+async function validateRefreshToken(ctx, opts, refreshToken, clientId) {
 	if (!refreshToken.clientId || refreshToken.clientId !== clientId) return { active: false };
 	if (!refreshToken.expiresAt || refreshToken.expiresAt < /* @__PURE__ */ new Date()) return { active: false };
 	if (refreshToken.revoked) return { active: false };
@@ -2414,6 +2526,7 @@ async function validateRefreshToken(ctx, opts, token, clientId) {
 		iss: ((opts.disableJwtPlugin ? void 0 : getJwtPlugin(ctx.context))?.options)?.jwt?.issuer ?? ctx.context.baseURL,
 		sub: user?.id,
 		sid: sessionId,
+		reference_id: refreshToken.referenceId ?? void 0,
 		exp: Math.floor(new Date(refreshToken.expiresAt).getTime() / 1e3),
 		iat: Math.floor(new Date(refreshToken.createdAt).getTime() / 1e3),
 		scope: refreshToken.scopes?.join(" "),
@@ -2427,32 +2540,23 @@ function createInvalidAccessTokenError() {
 		error: "invalid_token"
 	}, { "WWW-Authenticate": INVALID_ACCESS_TOKEN_WWW_AUTHENTICATE });
 }
-function isInactiveTokenError(error) {
-	return error.status === "BAD_REQUEST" || error.body?.error === "invalid_token";
+async function validateFoundAccessToken(ctx, opts, found, clientId) {
+	if (found.type === "opaque") return validateOpaqueAccessToken(ctx, opts, found.record, clientId);
+	return {
+		payload: await validateJwtAccessToken(ctx, opts, found.payload, clientId),
+		requestedUserInfoClaims: []
+	};
 }
 /**
-* 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).
+* Validates an access token (JWT or opaque). Returns the RFC 7662
+* introspection payload, inactive for an unknown token, alongside the
+* per-issuance UserInfo claims the opaque row persisted (empty for a JWT access
+* token, which resolves UserInfo claims by scope).
 */
 async function resolveAccessTokenValidation(ctx, opts, token, clientId) {
-	try {
-		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);
-	}
-	try {
-		return await validateOpaqueAccessToken(ctx, opts, token, clientId);
-	} catch (err) {
-		if (err instanceof APIError$1) {} else if (err instanceof Error) throw err;
-		else throw new Error("Unknown error validating access token");
-	}
-	throw createInvalidAccessTokenError();
+	const found = await findAccessToken(ctx, opts, token);
+	if (!found) return inactiveAccessToken();
+	return validateFoundAccessToken(ctx, opts, found, clientId);
 }
 /**
 * Validates an access token (JWT or opaque) and returns its RFC 7662
@@ -2501,7 +2605,6 @@ async function resolveIntrospectionSub(ctx, opts, payload, introspectingClient)
 }
 async function introspectEndpoint(ctx, opts) {
 	let { token, token_type_hint } = ctx.body;
-	if (token_type_hint !== "access_token" && token_type_hint !== "refresh_token") token_type_hint = void 0;
 	const { clientId: client_id, clientSecret: client_secret, preVerified, authMethod } = destructureCredentials(await extractClientCredentials(ctx, opts, `${ctx.context.baseURL}/oauth2/introspect`));
 	if (!client_id || !client_secret && !preVerified) throw new APIError$1("UNAUTHORIZED", {
 		error_description: "missing required credentials",
@@ -2514,38 +2617,16 @@ async function introspectEndpoint(ctx, opts) {
 	});
 	const client = await validateClientCredentials(ctx, opts, client_id, client_secret, void 0, preVerified, void 0, authMethod);
 	try {
-		if (token_type_hint === void 0 || token_type_hint === "access_token") try {
-			return resolveIntrospectionSub(ctx, opts, await validateAccessToken(ctx, opts, token, client.clientId), client);
-		} catch (error) {
-			if (error instanceof APIError$1) {
-				if (token_type_hint === "access_token") throw error;
-			} else if (error instanceof Error) throw error;
-			else throw new Error(error);
-		}
-		if (token_type_hint === void 0 || token_type_hint === "refresh_token") try {
-			return resolveIntrospectionSub(ctx, opts, await validateRefreshToken(ctx, opts, (await decodeRefreshToken(opts, token)).token, client.clientId), client);
-		} catch (error) {
-			if (error instanceof APIError$1) {
-				if (token_type_hint === "refresh_token") throw error;
-			} else if (error instanceof Error) throw error;
-			else throw new Error(error);
-		}
-		throw new APIError$1("BAD_REQUEST", {
-			error_description: "token not found",
-			error: "invalid_request"
-		});
+		const found = await findToken(ctx, opts, token, token_type_hint);
+		if (!found) return { active: false };
+		if (found.type === "refresh") return resolveIntrospectionSub(ctx, opts, await validateRefreshToken(ctx, opts, found.record, client.clientId), client);
+		const { payload } = await validateFoundAccessToken(ctx, opts, found, client.clientId);
+		return resolveIntrospectionSub(ctx, opts, payload, client);
 	} catch (error) {
-		if (error instanceof APIError$1) {
-			if (isInactiveTokenError(error)) return { active: false };
-			throw error;
-		} else if (error instanceof Error) {
-			logger.error("Introspection error:", error.message, error.stack);
-			throw new APIError$1("INTERNAL_SERVER_ERROR");
-		} else {
-			logger.error("Introspection error:", error);
-			throw new APIError$1("INTERNAL_SERVER_ERROR");
-		}
+		if (error instanceof APIError$1) throw error;
+		logger.error("Introspection error:", error);
+		throw new APIError$1("INTERNAL_SERVER_ERROR");
 	}
 }
 //#endregion
-export { claimsRequestParameterSchema as A, clientJwksSchema as C, STANDARD_CLAIM_NAMES as D, STANDARD_CLAIMS as E, getRequestedUserInfoClaims as M, isValidOidcClaimsRequest as N, getSupportedClaims as O, authorizationQuerySchema as S, oauthClientMetadataSchema as T, logStartupSeedFailure as _, invalidateRefreshFamily as a, ResourceUriSchema as b, normalizeClientCredentialsScopes as c, assertIdentifierValid as d, extractRepeatedResourceFromForm as f, logEnforcePerClientResourcesResolution as g, isAudienceClaimAllowed as h, getOAuthProviderApi as i, filterClaimsRequestUserInfoClaims as j, canSatisfyEssentialAcrRequest as k, validateClientCredentialsScopes as l, invalidateResourceCache as m, introspect_exports as n, tokenEndpoint as o, getResource as p, decodeRefreshToken as r, userInfoEndpoint as s, introspectEndpoint as t, JWS_ALGORITHMS as u, resolveResourcePolicy as v, clientRegistrationRequestSchema as w, SafeUrlSchema as x, seedResourcesOnce as y };
+export { getAcrValuesSupported as A, authorizationQuerySchema as C, STANDARD_CLAIMS as D, oauthClientMetadataSchema as E, getRequestedUserInfoClaims as F, isValidOidcClaimsRequest as I, canSatisfyEssentialAcrRequest as M, claimsRequestParameterSchema as N, STANDARD_CLAIM_NAMES as O, filterClaimsRequestUserInfoClaims as P, SafeUrlSchema as S, clientRegistrationRequestSchema as T, logStartupSeedFailure as _, tokenEndpoint as a, userInfoResource as b, normalizeClientCredentialsScopes as c, JWS_ALGORITHMS as d, assertIdentifierValid as f, logEnforcePerClientResourcesResolution as g, isAudienceClaimAllowed as h, invalidateRefreshFamily as i, resolveAuthenticationContext as j, getSupportedClaims as k, validateClientCredentialsScopes as l, invalidateResourceCache as m, introspect_exports as n, userInfoEndpoint as o, getResource as p, getOAuthProviderApi as r, findToken as s, introspectEndpoint as t, getEndpointUrl as u, resolveResourcePolicy as v, clientJwksSchema as w, ResourceUriSchema as x, seedResourcesOnce as y };