@better-auth/core 1.7.0-beta.5 → 1.7.0-beta.7

package/src/oauth2/refresh-access-token.ts

@@ -29,6 +29,21 @@ interface RefreshAccessTokenInput extends RefreshAccessTokenRequestInput {
 	tokenEndpoint: string;
 }
 
+/**
+ * Body keys owned by the refresh-token flow or unsafe to copy from caller input.
+ */
+const BLOCKED_REFRESH_TOKEN_PARAMS = [
+	"grant_type",
+	"refresh_token",
+	"__proto__",
+	"constructor",
+	"prototype",
+] as const;
+
+const BLOCKED_REFRESH_TOKEN_PARAMS_SET: ReadonlySet<string> = new Set(
+	BLOCKED_REFRESH_TOKEN_PARAMS,
+);
+
 export async function refreshAccessTokenRequest({
 	refreshToken,
 	options,
@@ -59,6 +74,17 @@ export async function refreshAccessTokenRequest({
 	return request;
 }
 
+function applyRefreshExtraParams(
+	body: URLSearchParams,
+	extraParams: Record<string, string> | undefined,
+) {
+	if (!extraParams) return;
+	for (const [key, value] of Object.entries(extraParams)) {
+		if (BLOCKED_REFRESH_TOKEN_PARAMS_SET.has(key)) continue;
+		body.set(key, value);
+	}
+}
+
 function buildRefreshAccessTokenRequest({
 	refreshToken,
 	options,
@@ -83,9 +109,7 @@ function buildRefreshAccessTokenRequest({
 		}
 	}
 	if (extraParams) {
-		for (const [key, value] of Object.entries(extraParams)) {
-			body.set(key, value);
-		}
+		applyRefreshExtraParams(body, extraParams);
 	}
 
 	return {

package/src/oauth2/verify-id-token.ts

@@ -79,6 +79,8 @@ export async function verifyProviderIdToken(
 		// Opaque (non-JWS) tokens carry no signature to check. They are accepted only when the
 		// provider opts in, in which case getUserInfo resolves identity from the access token via
 		// the provider's userinfo endpoint, which validates it (e.g. Facebook Graph access tokens).
+		// An expected `nonce` is not enforced here: an opaque token carries no `nonce` claim, and the
+		// access-token-backed userinfo exchange (not the token itself) is the identity source.
 		if (token.split(".").length !== 3) {
 			return config.allowOpaqueToken === true;
 		}

package/src/oauth2/verify.ts

@@ -4,6 +4,7 @@ import type {
 	JSONWebKeySet,
 	JWTPayload,
 	JWTVerifyOptions,
+	JWTVerifyResult,
 	ProtectedHeaderParameters,
 } from "jose";
 import {
@@ -14,6 +15,14 @@ import {
 	UnsecuredJWT,
 } from "jose";
 import { logger } from "../env";
+import type { DpopReplayStore } from "./dpop";
+import {
+	createInMemoryDpopReplayStore,
+	enforceDpopBinding,
+	getDpopJktFromPayload,
+	isDpopBindingError,
+	parseAccessTokenAuthorization,
+} from "./dpop";
 
 const joseInfrastructureErrorCodes = new Set([
 	joseErrors.JWKSTimeout.code,
@@ -28,12 +37,37 @@ function isJoseInfrastructureError(error: joseErrors.JOSEError) {
 interface JwksCacheEntry {
 	jwks: JSONWebKeySet;
 	fetchedAt: number;
+	noKidRefetchedAt?: number | undefined;
 }
 
-const jwksCache = new Map<
-	string | (() => Promise<JSONWebKeySet | undefined>),
-	JwksCacheEntry
->();
+type JwksFetchOptions = {
+	/** Jwks url or promise of a Jwks */
+	jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
+	/**
+	 * Stable object to cache the result of a function `jwksFetch` under,
+	 * with the same TTL and kid-miss refetch rules as string sources.
+	 * Without it, a function source is fetched on every verification.
+	 */
+	jwksCacheKey?: object;
+};
+
+type ResolvedJwks = {
+	jwks: JSONWebKeySet;
+	fromCache: boolean;
+	kid: string | undefined;
+	noKidRefetchedAt?: number | undefined;
+};
+
+/**
+ * @internal
+ */
+export const jwksCache = new Map<string, JwksCacheEntry>();
+
+/**
+ * Cache for function jwks sources, keyed by a caller-provided stable object.
+ * Entries are released with their key, so per-request keys cannot accumulate.
+ */
+const functionJwksCache = new WeakMap<object, JwksCacheEntry>();
 
 /**
  * How long a cached JWKS is trusted before it is refetched
@@ -41,6 +75,61 @@ const jwksCache = new Map<
  * @internal
  */
 const JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
+const JWKS_NO_KID_REFETCH_COOLDOWN_MS = 30 * 1000;
+
+/**
+ * Returns the cached key set when it is within the TTL. When the token carries
+ * `kid`, the cached set must contain that key id; without `kid`, key selection
+ * is deferred to JOSE because RFC 7515 makes the header parameter optional.
+ */
+function getFreshJwksWithKid(
+	cached: JwksCacheEntry | undefined,
+	kid: string | undefined,
+): JSONWebKeySet | undefined {
+	if (!cached) return undefined;
+	if (Date.now() - cached.fetchedAt >= JWKS_CACHE_TTL_MS) return undefined;
+	if (kid && !cached.jwks.keys.some((jwk) => jwk.kid === kid)) {
+		return undefined;
+	}
+	return cached.jwks;
+}
+
+function shouldRefetchCachedJwksWithoutKid(
+	error: unknown,
+	resolved: ResolvedJwks,
+) {
+	const isRetryableNoKidFailure =
+		resolved.fromCache &&
+		!resolved.kid &&
+		(error instanceof joseErrors.JWKSNoMatchingKey ||
+			error instanceof joseErrors.JWSSignatureVerificationFailed);
+	if (!isRetryableNoKidFailure) return false;
+	if (!resolved.noKidRefetchedAt) return true;
+	return (
+		Date.now() - resolved.noKidRefetchedAt >= JWKS_NO_KID_REFETCH_COOLDOWN_MS
+	);
+}
+
+async function fetchJwks(
+	jwksFetch: JwksFetchOptions["jwksFetch"],
+): Promise<JSONWebKeySet> {
+	const jwks =
+		typeof jwksFetch === "string"
+			? await betterFetch<JSONWebKeySet>(jwksFetch, {
+					headers: {
+						Accept: "application/json",
+					},
+				}).then(async (res) => {
+					if (res.error)
+						throw new Error(
+							`Jwks failed: ${res.error.message ?? res.error.statusText}`,
+						);
+					return res.data;
+				})
+			: await jwksFetch();
+	if (!jwks) throw new Error("No jwks found");
+	return jwks;
+}
 
 export interface VerifyAccessTokenRemote {
 	/** Full url of the introspect endpoint. Should end with `/oauth2/introspect` */
@@ -71,6 +160,65 @@ export interface VerifyAccessTokenRemote {
 	allowMissingAudience?: boolean;
 }
 
+export interface VerifyAccessTokenOptions {
+	/** Verify options */
+	verifyOptions: JWTVerifyOptions &
+		Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
+	/** Scopes to additionally verify. Token must include all but not exact. */
+	scopes?: string[];
+	/** Required to verify access token locally */
+	jwksUrl?: string;
+	/** If provided, can verify a token remotely */
+	remoteVerify?: VerifyAccessTokenRemote;
+}
+
+export interface VerifyAccessTokenRequestOptions
+	extends VerifyAccessTokenOptions {
+	dpop?: {
+		proofMaxAgeSeconds?: number;
+		/**
+		 * Store used to reject replayed DPoP proof `jti` values.
+		 *
+		 * Defaults to a process-local in-memory store, which is only safe for a
+		 * single-instance deployment: it shares no state across instances and
+		 * resets on cold start, so a captured proof can be replayed against
+		 * another instance within the proof's lifetime. Supply a shared,
+		 * persistent store (for example one backed by your database) for any
+		 * multi-instance or serverless resource server.
+		 */
+		replayStore?: DpopReplayStore;
+		signingAlgorithms?: readonly string[];
+	};
+}
+
+export interface ResourceRequestInput {
+	authorizationHeader: string | null | undefined;
+	dpopProofJwt?: string | null | undefined;
+	method: string;
+	url: string;
+}
+
+/**
+ * Builds a {@link ResourceRequestInput} from a standard `Request`, reading the
+ * `Authorization` and `DPoP` headers and the request method and URL. Resource
+ * servers share this so every entry point maps the wire request the same way.
+ */
+export function requestToResourceInput(request: Request): ResourceRequestInput {
+	return {
+		authorizationHeader: request.headers.get("authorization"),
+		dpopProofJwt: request.headers.get("dpop"),
+		method: request.method,
+		url: request.url,
+	};
+}
+
+/**
+ * Process-local, single-instance replay store. See the warning on
+ * {@link VerifyAccessTokenRequestOptions.dpop.replayStore}; multi-instance
+ * resource servers must pass their own shared store.
+ */
+const defaultDpopReplayStore = createInMemoryDpopReplayStore();
+
 /**
  * Performs local verification of an access token for your APIs.
  *
@@ -78,21 +226,36 @@ export interface VerifyAccessTokenRemote {
  */
 export async function verifyJwsAccessToken(
 	token: string,
-	opts: {
-		/** Jwks url or promise of a Jwks */
-		jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
+	opts: JwksFetchOptions & {
 		/** Verify options */
 		verifyOptions: JWTVerifyOptions &
 			Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
 	},
 ) {
 	try {
-		const jwks = await getJwks(token, opts);
-		const jwt = await jwtVerify<JWTPayload>(
-			token,
-			createLocalJWKSet(jwks),
-			opts.verifyOptions,
-		);
+		const resolved = await getJwksForVerification(token, opts);
+		let jwt: JWTVerifyResult<JWTPayload>;
+		try {
+			jwt = await jwtVerify<JWTPayload>(
+				token,
+				createLocalJWKSet(resolved.jwks),
+				opts.verifyOptions,
+			);
+		} catch (error) {
+			if (shouldRefetchCachedJwksWithoutKid(error, resolved)) {
+				const refreshed = await getJwksForVerification(token, {
+					...opts,
+					forceRefresh: true,
+				});
+				jwt = await jwtVerify<JWTPayload>(
+					token,
+					createLocalJWKSet(refreshed.jwks),
+					opts.verifyOptions,
+				);
+			} else {
+				throw error;
+			}
+		}
 		// Return the JWT payload in introspection format
 		// https://datatracker.ietf.org/doc/html/rfc7662#section-2.2
 		if (jwt.payload.azp) {
@@ -105,12 +268,13 @@ export async function verifyJwsAccessToken(
 	}
 }
 
-export async function getJwks(
+export async function getJwks(token: string, opts: JwksFetchOptions) {
+	return (await getJwksForVerification(token, opts)).jwks;
+}
+
+async function getJwksForVerification(
 	token: string,
-	opts: {
-		/** Jwks url or promise of a Jwks */
-		jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
-	},
+	opts: JwksFetchOptions & { forceRefresh?: boolean },
 ) {
 	// Attempt to decode the token and find a matching kid in jwks
 	let jwtHeaders: ProtectedHeaderParameters | undefined;
@@ -121,63 +285,70 @@ export async function getJwks(
 		throw new Error(error as unknown as string);
 	}
 
-	if (!jwtHeaders.kid) {
-		throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
-	}
 	const kid = jwtHeaders.kid;
 
+	// Function sources have no usable identity of their own (callers pass
+	// fresh closures per request), so they are cached only under a stable
+	// caller-provided key object.
+	if (typeof opts.jwksFetch !== "string") {
+		const cacheKey = opts.jwksCacheKey;
+		if (!cacheKey) {
+			const jwks = await opts.jwksFetch();
+			if (!jwks) throw new Error("No jwks found");
+			return { jwks, fromCache: false, kid };
+		}
+		const cached = functionJwksCache.get(cacheKey);
+		const cachedJwks = opts.forceRefresh
+			? undefined
+			: getFreshJwksWithKid(cached, kid);
+		if (cachedJwks) {
+			return {
+				jwks: cachedJwks,
+				fromCache: true,
+				kid,
+				noKidRefetchedAt: cached?.noKidRefetchedAt,
+			};
+		}
+		const jwks = await opts.jwksFetch();
+		if (!jwks) throw new Error("No jwks found");
+		const fetchedAt = Date.now();
+		functionJwksCache.set(cacheKey, {
+			jwks,
+			fetchedAt,
+			...(opts.forceRefresh && !kid ? { noKidRefetchedAt: fetchedAt } : {}),
+		});
+		return { jwks, fromCache: false, kid };
+	}
+
+	// The cache is scoped to `cacheKey`, so a token is only ever matched
+	// against the key set published by its own source.
 	const cacheKey = opts.jwksFetch;
 	const cached = jwksCache.get(cacheKey);
-	const isFresh = cached
-		? Date.now() - cached.fetchedAt < JWKS_CACHE_TTL_MS
-		: false;
-	const hasKid = cached?.jwks.keys.some((jwk) => jwk.kid === kid) ?? false;
-
-	// Refetch when this source has no cached set, the cached set has expired, or
-	// it does not contain the token's kid (e.g. a newly rotated-in key). The
-	// cache is scoped to `cacheKey`, so a token is only ever matched against the
-	// key set published by its own source.
-	if (!cached || !isFresh || !hasKid) {
-		const jwks =
-			typeof opts.jwksFetch === "string"
-				? await betterFetch<JSONWebKeySet>(opts.jwksFetch, {
-						headers: {
-							Accept: "application/json",
-						},
-					}).then(async (res) => {
-						if (res.error)
-							throw new Error(
-								`Jwks failed: ${res.error.message ?? res.error.statusText}`,
-							);
-						return res.data;
-					})
-				: await opts.jwksFetch();
-		if (!jwks) throw new Error("No jwks found");
-		jwksCache.set(cacheKey, { jwks, fetchedAt: Date.now() });
-		return jwks;
+	const cachedJwks = opts.forceRefresh
+		? undefined
+		: getFreshJwksWithKid(cached, kid);
+	if (!cachedJwks) {
+		const jwks = await fetchJwks(opts.jwksFetch);
+		const fetchedAt = Date.now();
+		jwksCache.set(cacheKey, {
+			jwks,
+			fetchedAt,
+			...(opts.forceRefresh && !kid ? { noKidRefetchedAt: fetchedAt } : {}),
+		});
+		return { jwks, fromCache: false, kid };
 	}
 
-	return cached.jwks;
+	return {
+		jwks: cachedJwks,
+		fromCache: true,
+		kid,
+		noKidRefetchedAt: cached?.noKidRefetchedAt,
+	};
 }
 
-/**
- * Performs local verification of an access token for your API.
- *
- * Can also be configured for remote verification.
- */
-export async function verifyAccessToken(
+async function verifyAccessTokenPayload(
 	token: string,
-	opts: {
-		/** Verify options */
-		verifyOptions: JWTVerifyOptions &
-			Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
-		/** Scopes to additionally verify. Token must include all but not exact. */
-		scopes?: string[];
-		/** Required to verify access token locally */
-		jwksUrl?: string;
-		/** If provided, can verify a token remotely */
-		remoteVerify?: VerifyAccessTokenRemote;
-	},
+	opts: VerifyAccessTokenOptions,
 ) {
 	let payload: JWTPayload | undefined;
 	// Locally verify
@@ -286,3 +457,95 @@ export async function verifyAccessToken(
 
 	return payload;
 }
+
+function throwDpopUnauthorized(
+	message: string,
+	error?: "invalid_dpop_proof" | "invalid_token",
+): never {
+	throw new APIError(
+		"UNAUTHORIZED",
+		error
+			? {
+					message,
+					error,
+					error_description: message,
+				}
+			: { message },
+	);
+}
+
+/**
+ * Performs local verification of a bearer access token for your API.
+ *
+ * Can also be configured for remote verification. DPoP-bound access tokens
+ * require {@link verifyAccessTokenRequest}, because sender-constraining cannot
+ * be verified without the HTTP method, URL, Authorization scheme, DPoP proof,
+ * and access-token hash. This function rejects DPoP-bound tokens; reach for it
+ * only when you hold a raw token string and intentionally accept bearer tokens
+ * alone.
+ */
+export async function verifyBearerToken(
+	token: string,
+	opts: VerifyAccessTokenOptions,
+) {
+	const payload = await verifyAccessTokenPayload(token, opts);
+	if (getDpopJktFromPayload(payload)) {
+		throwDpopUnauthorized(
+			"DPoP-bound access token requires verifyAccessTokenRequest",
+			"invalid_token",
+		);
+	}
+	return payload;
+}
+
+/**
+ * Verifies an HTTP resource request carrying an OAuth access token. This is the
+ * recommended resource-server entry point: it handles both bearer and
+ * DPoP-bound tokens, the bearer case being the request with no DPoP proof.
+ *
+ * It performs the same token validation as {@link verifyBearerToken}, then adds
+ * the RFC 9449 sender-constraint checks that need request context: authorization
+ * scheme, method, URL, DPoP proof, `ath`, and `cnf.jkt` binding.
+ */
+export async function verifyAccessTokenRequest(
+	request: ResourceRequestInput,
+	opts: VerifyAccessTokenRequestOptions,
+) {
+	const authorization = parseAccessTokenAuthorization(
+		request.authorizationHeader,
+	);
+	if (!authorization?.token) {
+		throwDpopUnauthorized("missing authorization header");
+	}
+	// RFC 6750 §2.1 / RFC 9449 §7.1: an access token is presented with the
+	// `Bearer` or `DPoP` scheme. Reject a scheme-less or unknown-scheme value
+	// rather than accept a bare token.
+	if (authorization.scheme === "Unknown") {
+		throwDpopUnauthorized(
+			"authorization scheme must be Bearer or DPoP",
+			"invalid_token",
+		);
+	}
+
+	const payload = await verifyAccessTokenPayload(authorization.token, opts);
+
+	try {
+		await enforceDpopBinding({
+			payload,
+			authorization,
+			proofJwt: request.dpopProofJwt,
+			method: request.method,
+			url: request.url,
+			replayStore: opts.dpop?.replayStore ?? defaultDpopReplayStore,
+			proofMaxAgeSeconds: opts.dpop?.proofMaxAgeSeconds,
+			signingAlgorithms: opts.dpop?.signingAlgorithms,
+		});
+	} catch (error) {
+		if (isDpopBindingError(error)) {
+			throwDpopUnauthorized(error.message, error.code);
+		}
+		throw error;
+	}
+
+	return payload;
+}

package/src/social-providers/microsoft-entra-id.ts

@@ -17,6 +17,14 @@ import {
 	validateAuthorizationCode,
 } from "../oauth2";
 
+/**
+ * Microsoft's fixed tenant id for personal (consumer) Microsoft accounts. Every
+ * personal-account token carries it as the `tid` claim, so it distinguishes the
+ * consumer account class from work/school tenants.
+ * @see https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference
+ */
+const MICROSOFT_CONSUMER_TENANT_ID = "9188040d-6c67-4c5b-b112-36a304b66dad";
+
 /**
  * @see [Microsoft Identity Platform - Optional claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference)
  */
@@ -163,7 +171,14 @@ const MICROSOFT_ENTRA_ID_DEFAULT_SCOPES = [
 
 export const microsoft = (options: MicrosoftOptions) => {
 	const tenant = options.tenantId || "common";
-	const authority = options.authority || "https://login.microsoftonline.com";
+	// Trim any trailing slash so endpoint URLs and the issuer comparison below
+	// never produce a double slash (e.g. a configured `https://host/` would make
+	// the expected issuer `https://host//<tid>/v2.0` and reject every token). A
+	// loop avoids a trailing-slash regex, which is a polynomial-ReDoS shape.
+	let authority = options.authority || "https://login.microsoftonline.com";
+	while (authority.endsWith("/")) {
+		authority = authority.slice(0, -1);
+	}
 	const authorizationEndpoint = `${authority}/${tenant}/oauth2/v2.0/authorize`;
 	const tokenEndpoint = `${authority}/${tenant}/oauth2/v2.0/token`;
 	if (options.clientSecret && options.clientAssertion) {
@@ -235,6 +250,34 @@ export const microsoft = (options: MicrosoftOptions) => {
 				tenant !== "consumers"
 					? `${authority}/${tenant}/v2.0`
 					: undefined,
+			/**
+			 * The multi-tenant endpoints (common/organizations/consumers) skip the
+			 * issuer check above because the issuer varies per tenant, and the
+			 * organizations and consumers JWKS sets overlap. Enforce the tenant
+			 * binding explicitly so a token from a disallowed account class cannot
+			 * pass: the issuer must name the token's own tenant, and the account
+			 * class must match the configured restriction.
+			 * @see https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference
+			 */
+			verifyClaims: (claims) => {
+				const tid = claims.tid;
+				if (
+					typeof tid !== "string" ||
+					claims.iss !== `${authority}/${tid}/v2.0`
+				) {
+					return false;
+				}
+				if (
+					tenant === "organizations" &&
+					tid === MICROSOFT_CONSUMER_TENANT_ID
+				) {
+					return false;
+				}
+				if (tenant === "consumers" && tid !== MICROSOFT_CONSUMER_TENANT_ID) {
+					return false;
+				}
+				return true;
+			},
 		},
 		async getUserInfo(token) {
 			if (options.getUserInfo) {

package/src/social-providers/reddit.ts

@@ -116,7 +116,11 @@ export const reddit = (options: RedditOptions) => {
 			}
 
 			const userMap = await options.mapProfileToUser?.(profile);
-			const email = userMap?.email || `${profile.id}@reddit.com`;
+			// Reddit's identity scope does not return an email. Synthesize a stable,
+			// non-routable placeholder (RFC 2606 `.invalid`) keyed to the user's
+			// Reddit id rather than the routable `reddit.com`, which could collide
+			// with a real address. Left unverified; `mapProfileToUser` can override.
+			const email = userMap?.email || `${profile.id}@reddit.invalid`;
 			return {
 				user: {
 					id: profile.id,

package/src/social-providers/wechat.ts

@@ -220,7 +220,14 @@ export const wechat = (options: WeChatOptions) => {
 				user: {
 					id: profile.unionid || profile.openid || openid,
 					name: profile.nickname,
-					email: profile.email || null,
+					// WeChat does not return an email, and the OAuth callback rejects a
+					// missing one, so the default sign-in would always fail. Synthesize a
+					// stable, non-routable placeholder (RFC 2606 `.invalid`) keyed to the
+					// user's WeChat id, left unverified. Applications that collect a real
+					// email override it via `mapProfileToUser`.
+					email:
+						profile.email ||
+						`${profile.unionid || profile.openid || openid}@wechat.invalid`,
 					image: profile.headimgurl,
 					emailVerified: false,
 					...userMap,

package/src/types/context.ts

@@ -237,6 +237,24 @@ export interface InternalAdapter<
 	 */
 	consumeVerificationValue(identifier: string): Promise<Verification | null>;
 
+	/**
+	 * First-writer-wins create keyed by a deterministic primary key derived from
+	 * `identifier`. Returns `true` when this caller created the row and `false`
+	 * when a row for the same identifier already existed.
+	 *
+	 * The dual of `consumeVerificationValue`: reserve races to create a marker
+	 * exactly once, where consume races to delete one exactly once. Use it for
+	 * replay tombstones (a SAML assertion id, a JWT `jti`) where the first caller
+	 * wins. The database path is atomic via the primary key. Secondary-storage-only
+	 * verification is not supported for reservation and runtime implementations
+	 * should fail closed unless verification is backed by the database.
+	 */
+	reserveVerificationValue(data: {
+		identifier: string;
+		value: string;
+		expiresAt: Date;
+	}): Promise<boolean>;
+
 	updateVerificationByIdentifier(
 		identifier: string,
 		data: Partial<Verification>,