@better-auth/core 1.6.15 → 1.6.17

package/dist/api/index.d.mts

@@ -272,6 +272,9 @@ declare const createAuthMiddleware: {
 type EndpointHandler<Path extends string, Options extends EndpointOptions, R> = (context: EndpointContext<Path, Options, AuthContext>) => Promise<R>;
 declare function createAuthEndpoint<Path extends string, Options extends EndpointOptions, R>(path: Path, options: Options, handler: EndpointHandler<Path, Options, R>): StrictEndpoint<Path, Options, R>;
 declare function createAuthEndpoint<Path extends string, Options extends EndpointOptions, R>(options: Options, handler: EndpointHandler<Path, Options, R>): StrictEndpoint<Path, Options, R>;
+declare namespace createAuthEndpoint {
+  var serverOnly: <Path extends string, Options extends EndpointOptions, R>(options: Options, handler: EndpointHandler<Path, Options, R>) => StrictEndpoint<Path, Options, R>;
+}
 type AuthEndpoint<Path extends string, Opts extends EndpointOptions, R> = ReturnType<typeof createAuthEndpoint<Path, Opts, R>>;
 type AuthMiddleware = ReturnType<typeof createAuthMiddleware>;
 //#endregion

package/dist/api/index.mjs

@@ -52,5 +52,41 @@ function createAuthEndpoint(pathOrOptions, handlerOrOptions, handlerOrNever) {
 		use: [...options?.use || [], ...use]
 	}, wrapped);
 }
+/**
+* Set `metadata.SERVER_ONLY` while preserving any existing metadata
+* (`$Infer`, `openapi`, ...).
+*/
+function withServerOnly(options) {
+	return {
+		...options,
+		metadata: {
+			...options.metadata,
+			SERVER_ONLY: true
+		}
+	};
+}
+/**
+* Declare a **server-only** endpoint.
+*
+* The endpoint is callable through `auth.api.*` from trusted server code but is
+* never registered on the HTTP router and never emitted into the OpenAPI
+* schema. It takes no path because it has no URL to be reached at.
+*
+* Prefer this over the path-less `createAuthEndpoint({ ... }, handler)` form.
+* Setting `metadata.SERVER_ONLY` makes the intent explicit at the call site and
+* keeps the endpoint off the HTTP surface even if a path is later added by
+* mistake: better-call's router skips an endpoint when its path is missing *or*
+* when `SERVER_ONLY` is set, so the two together are defense in depth. Relying
+* on path omission alone is invisible and one keystroke away from exposure.
+*
+* @example
+* ```ts
+* viewBackupCodes: createAuthEndpoint.serverOnly(
+* 	{ method: "POST", body: schema },
+* 	async (ctx) => { ... },
+* )
+* ```
+*/
+createAuthEndpoint.serverOnly = (options, handler) => createAuthEndpoint(withServerOnly(options), handler);
 //#endregion
 export { createAuthEndpoint, createAuthMiddleware, optionsMiddleware };

package/dist/context/global.mjs

@@ -2,7 +2,7 @@
 const symbol = Symbol.for("better-auth:global");
 let bind = null;
 const __context = {};
-const __betterAuthVersion = "1.6.15";
+const __betterAuthVersion = "1.6.17";
 /**
 * We store context instance in the globalThis.
 *

package/dist/db/adapter/factory.mjs

@@ -58,6 +58,7 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 					else if (method === "delete" && !config.debugLogs.delete) return;
 					else if (method === "deleteMany" && !config.debugLogs.deleteMany) return;
 					else if (method === "consumeOne" && !config.debugLogs.consumeOne) return;
+					else if (method === "incrementOne" && !config.debugLogs.incrementOne) return;
 					else if (method === "count" && !config.debugLogs.count) return;
 				}
 				logger.info(`[${config.adapterName}]`, ...args);
@@ -738,6 +739,87 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 			});
 			return transformed;
 		},
+		incrementOne: async ({ model: unsafeModel, where: unsafeWhere, increment: unsafeIncrement, set: unsafeSet }) => {
+			transactionId++;
+			const thisTransactionId = transactionId;
+			const model = getModelName(unsafeModel);
+			const where = transformWhereClause({
+				model: unsafeModel,
+				where: unsafeWhere,
+				action: "incrementOne"
+			});
+			unsafeModel = getDefaultModelName(unsafeModel);
+			debugLog({ method: "incrementOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(1, 3)}`, `${formatMethod("incrementOne")} ${formatAction("IncrementOne")}:`, {
+				model,
+				where,
+				increment: unsafeIncrement,
+				set: unsafeSet
+			});
+			let res;
+			let resultNeedsOutputTransform = true;
+			if (adapterInstance.incrementOne) {
+				const mappedKeys = config.mapKeysTransformInput ?? {};
+				const increment = {};
+				for (const [field, delta] of Object.entries(unsafeIncrement)) increment[mappedKeys[field] || getFieldName({
+					model: unsafeModel,
+					field
+				})] = delta;
+				let set;
+				if (unsafeSet && !config.disableTransformInput) set = await transformInput(unsafeSet, unsafeModel, "update");
+				else set = unsafeSet;
+				res = await withSpan(`db incrementOne ${model}`, {
+					[ATTR_DB_OPERATION_NAME]: "incrementOne",
+					[ATTR_DB_COLLECTION_NAME]: model
+				}, () => adapterInstance.incrementOne({
+					model,
+					where,
+					increment,
+					set
+				}));
+			} else {
+				res = await withSpan(`db incrementOne ${model}`, {
+					[ATTR_DB_OPERATION_NAME]: "incrementOne",
+					[ATTR_DB_COLLECTION_NAME]: model
+				}, () => adapter.transaction(async (trx) => {
+					const target = (await trx.findMany({
+						model: unsafeModel,
+						where: unsafeWhere,
+						limit: 1
+					}))[0];
+					if (!target) return null;
+					const nextValues = { ...unsafeSet ?? {} };
+					for (const [field, delta] of Object.entries(unsafeIncrement)) nextValues[field] = (typeof target[field] === "number" ? target[field] : 0) + delta;
+					const updated = await trx.updateMany({
+						model: unsafeModel,
+						where: [...unsafeWhere, {
+							field: "id",
+							value: target.id,
+							operator: "eq",
+							connector: "AND",
+							mode: "sensitive"
+						}],
+						update: nextValues
+					});
+					if (typeof updated !== "number") throw new BetterAuthError(`Adapter "${config.adapterId}" returned a non-numeric value from updateMany during the incrementOne fallback. Return the number of updated rows, or implement a native incrementOne for atomic guarded counter updates.`);
+					return updated > 0 ? {
+						...target,
+						...nextValues
+					} : null;
+				}));
+				resultNeedsOutputTransform = false;
+			}
+			debugLog({ method: "incrementOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`, `${formatMethod("incrementOne")} ${formatAction("DB Result")}:`, {
+				model,
+				data: res
+			});
+			let transformed = res;
+			if (!config.disableTransformOutput && resultNeedsOutputTransform && res) transformed = await transformOutput(res, unsafeModel, void 0, void 0);
+			debugLog({ method: "incrementOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(3, 3)}`, `${formatMethod("incrementOne")} ${formatAction("Parsed Result")}:`, {
+				model,
+				data: transformed
+			});
+			return transformed;
+		},
 		count: async ({ model: unsafeModel, where: unsafeWhere }) => {
 			transactionId++;
 			const thisTransactionId = transactionId;

package/dist/db/adapter/index.d.mts

@@ -23,6 +23,7 @@ type DBAdapterDebugLogOption = boolean | {
   delete?: boolean | undefined;
   deleteMany?: boolean | undefined;
   consumeOne?: boolean | undefined;
+  incrementOne?: boolean | undefined;
   count?: boolean | undefined;
 } | {
   /**
@@ -198,7 +199,7 @@ interface DBAdapterFactoryConfig<Options extends BetterAuthOptions = BetterAuthO
     /**
      * The action which was called from the adapter.
      */
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "incrementOne" | "count";
     /**
      * The model name.
      */
@@ -436,6 +437,36 @@ type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
     model: string;
     where: Where[];
   }) => Promise<T | null>;
+  /**
+   * Atomically apply signed numeric deltas to a single row matching the where
+   * clause. For each entry in `increment`, the operation applies
+   * `field = field + delta` in one atomic step; a negative delta decrements.
+   *
+   * The `where` clause is both the selector AND the guard: comparison
+   * operators are honored, so passing `{ field: "remaining", operator: "gt",
+   * value: 0 }` only mutates the row while `remaining` is still above zero.
+   * When the guard matches no row, the operation makes no change and returns
+   * `null`.
+   *
+   * The optional `set` map assigns absolute values to fields in the same
+   * atomic operation, alongside the increments.
+   *
+   * Returns the updated row, or `null` when the guard matched no row. Under
+   * concurrent invocation against the same row, this is the race-safe
+   * primitive for guarded counter updates (e.g. decrementing a remaining-uses
+   * counter only while it is still positive).
+   *
+   * Always defined on the factory-wrapped adapter. When the underlying
+   * `CustomAdapter` does not implement `incrementOne`, the factory provides a
+   * fallback that wraps `findMany + updateMany` in `transaction(...)` and
+   * re-applies the where clause as a compare-and-swap guard on the update.
+   */
+  incrementOne: <T>(data: {
+    model: string;
+    where: Where[];
+    increment: Record<string, number>;
+    set?: Record<string, unknown> | undefined;
+  }) => Promise<T | null>;
   /**
    * Execute multiple operations in a transaction.
    * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -530,6 +561,25 @@ interface CustomAdapter {
     model: string;
     where: CleanedWhere[];
   }) => Promise<T | null>;
+  /**
+   * Optional native atomic guarded counter mutation. Applies
+   * `field = field + delta` for each entry in `increment` (negative deltas
+   * decrement), with `where` acting as both selector and guard and `set`
+   * assigning absolute values in the same operation. Returns the updated row,
+   * or `null` when the guard matched no row.
+   *
+   * Implementing this natively (e.g. `UPDATE ... SET n = n + $delta WHERE ...
+   * RETURNING *`) gives one round trip and the strongest race-safety
+   * guarantee. When omitted, the adapter factory provides a transaction-based
+   * fallback over `findMany + updateMany`. TODO(increment-one-required):
+   * tighten to required in the next minor on `next`.
+   */
+  incrementOne?: <T>(data: {
+    model: string;
+    where: CleanedWhere[];
+    increment: Record<string, number>;
+    set?: Record<string, unknown> | undefined;
+  }) => Promise<T | null>;
   count: ({
     model,
     where

package/dist/db/adapter/types.d.mts

@@ -94,7 +94,7 @@ type AdapterFactoryCustomizeAdapterCreator = (config: {
   }: {
     where: W;
     model: string;
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "incrementOne" | "count";
   }) => W extends undefined ? undefined : CleanedWhere[];
 }) => CustomAdapter;
 type AdapterTestDebugLogs = {

package/dist/db/type.d.mts

@@ -153,6 +153,21 @@ interface SecondaryStorage {
    * security-sensitive consume paths.
    */
   getAndDelete?: (key: string) => Awaitable<unknown>;
+  /**
+   * Atomically increment the counter at `key` by one, returning the
+   * post-increment value.
+   *
+   * When the key is absent, it is created with a value of `1` and the given
+   * `ttl` (in SECONDS). The TTL is applied only on creation; later increments
+   * never extend it, so the counter expires a fixed window after it was first
+   * created.
+   *
+   * This is optional for backwards compatibility with existing secondary
+   * storage implementations. TODO(secondary-storage-increment-required): make
+   * this required for secondary-storage-backed rate limiting in the next minor
+   * on `next`.
+   */
+  increment?: (key: string, ttl: number) => Awaitable<number>;
   set: (
   /**
    * Key to store

package/dist/env/env-impl.mjs

@@ -27,7 +27,7 @@ const env = new Proxy(_envShim, {
 function toBoolean(val) {
 	return val ? val !== "false" : false;
 }
-const nodeENV = typeof process !== "undefined" && process.env && process.env.NODE_ENV || "";
+const nodeENV = env.NODE_ENV ?? "";
 /** Detect if `NODE_ENV` environment variable is `production` */
 const isProduction = nodeENV === "production";
 /** Detect if `NODE_ENV` environment variable is `dev` or `development` */

package/dist/instrumentation/tracer.mjs

@@ -2,7 +2,7 @@ import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
 const INSTRUMENTATION_SCOPE = "better-auth";
-const INSTRUMENTATION_VERSION = "1.6.15";
+const INSTRUMENTATION_VERSION = "1.6.17";
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be

package/dist/oauth2/verify.d.mts

@@ -1,6 +1,18 @@
 import { JSONWebKeySet, JWTPayload, JWTVerifyOptions } from "jose";
 
 //#region src/oauth2/verify.d.ts
+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;
+};
+/**
+ * @internal
+ */
 interface VerifyAccessTokenRemote {
   /** Full url of the introspect endpoint. Should end with `/oauth2/introspect` */
   introspectUrl: string;
@@ -14,19 +26,30 @@ interface VerifyAccessTokenRemote {
    * is also still active.
    */
   force?: boolean;
+  /**
+   * Accept introspection responses that omit the `aud` claim even when a
+   * required `audience` is configured in `verifyOptions`.
+   *
+   * By default verification fails closed: if you configure an `audience` and
+   * the introspection response has no `aud` (or a mismatching one), the token
+   * is rejected. Some authorization servers legitimately omit `aud` from
+   * introspection responses (it is OPTIONAL per RFC 7662 §2.2); only enable
+   * this if you trust the issuer to bind the token to this resource through
+   * another mechanism, as it skips the audience check in that case.
+   *
+   * @default false
+   */
+  allowMissingAudience?: boolean;
 }
 /**
  * Performs local verification of an access token for your APIs.
  *
  * Can also be configured for remote verification.
  */
-declare function verifyJwsAccessToken(token: string, opts: {
-  /** Jwks url or promise of a Jwks */jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>); /** Verify options */
-  verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
+declare function verifyJwsAccessToken(token: string, opts: JwksFetchOptions & {
+  /** Verify options */verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
 }): Promise<JWTPayload>;
-declare function getJwks(token: string, opts: {
-  /** Jwks url or promise of a Jwks */jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
-}): Promise<JSONWebKeySet>;
+declare function getJwks(token: string, opts: JwksFetchOptions): Promise<JSONWebKeySet>;
 /**
  * Performs local verification of an access token for your API.
  *

package/dist/oauth2/verify.mjs

@@ -11,8 +11,46 @@ const joseInfrastructureErrorCodes = new Set([
 function isJoseInfrastructureError(error) {
 	return joseInfrastructureErrorCodes.has(error.code);
 }
-/** Last fetched jwks used locally in getJwks @internal */
-let jwks;
+/**
+* @internal
+*/
+const jwksCache = /* @__PURE__ */ new Map();
+/**
+* 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 = /* @__PURE__ */ new WeakMap();
+/**
+* How long a cached JWKS is trusted before it is refetched
+*
+* @internal
+*/
+const JWKS_CACHE_TTL_MS = 300 * 1e3;
+const JWKS_NO_KID_REFETCH_COOLDOWN_MS = 30 * 1e3;
+/**
+* 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, kid) {
+	if (!cached) return void 0;
+	if (Date.now() - cached.fetchedAt >= JWKS_CACHE_TTL_MS) return void 0;
+	if (kid && !cached.jwks.keys.some((jwk) => jwk.kid === kid)) return;
+	return cached.jwks;
+}
+function shouldRefetchCachedJwksWithoutKid(error, resolved) {
+	if (!(resolved.fromCache && !resolved.kid && (error instanceof errors.JWKSNoMatchingKey || error instanceof errors.JWSSignatureVerificationFailed))) return false;
+	if (!resolved.noKidRefetchedAt) return true;
+	return Date.now() - resolved.noKidRefetchedAt >= JWKS_NO_KID_REFETCH_COOLDOWN_MS;
+}
+async function fetchJwks(jwksFetch) {
+	const jwks = typeof jwksFetch === "string" ? await betterFetch(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;
+}
 /**
 * Performs local verification of an access token for your APIs.
 *
@@ -20,7 +58,17 @@ let jwks;
 */
 async function verifyJwsAccessToken(token, opts) {
 	try {
-		const jwt = await jwtVerify(token, createLocalJWKSet(await getJwks(token, opts)), opts.verifyOptions);
+		const resolved = await getJwksForVerification(token, opts);
+		let jwt;
+		try {
+			jwt = await jwtVerify(token, createLocalJWKSet(resolved.jwks), opts.verifyOptions);
+		} catch (error) {
+			if (shouldRefetchCachedJwksWithoutKid(error, resolved)) jwt = await jwtVerify(token, createLocalJWKSet((await getJwksForVerification(token, {
+				...opts,
+				forceRefresh: true
+			})).jwks), opts.verifyOptions);
+			else throw error;
+		}
 		if (jwt.payload.azp) jwt.payload.client_id = jwt.payload.azp;
 		return jwt.payload;
 	} catch (error) {
@@ -29,6 +77,9 @@ async function verifyJwsAccessToken(token, opts) {
 	}
 }
 async function getJwks(token, opts) {
+	return (await getJwksForVerification(token, opts)).jwks;
+}
+async function getJwksForVerification(token, opts) {
 	let jwtHeaders;
 	try {
 		jwtHeaders = decodeProtectedHeader(token);
@@ -36,15 +87,63 @@ async function getJwks(token, opts) {
 		if (error instanceof Error) throw error;
 		throw new Error(error);
 	}
-	if (!jwtHeaders.kid) throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
-	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
-		jwks = typeof opts.jwksFetch === "string" ? await betterFetch(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();
+	const kid = jwtHeaders.kid;
+	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 ? void 0 : 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
+		};
 	}
-	return jwks;
+	const cacheKey = opts.jwksFetch;
+	const cached = jwksCache.get(cacheKey);
+	const cachedJwks = opts.forceRefresh ? void 0 : 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 {
+		jwks: cachedJwks,
+		fromCache: true,
+		kid,
+		noKidRefetchedAt: cached?.noKidRefetchedAt
+	};
 }
 /**
 * Performs local verification of an access token for your API.
@@ -85,8 +184,9 @@ async function verifyAccessToken(token, opts) {
 		if (!introspect.active) throw new APIError("UNAUTHORIZED", { message: "token inactive" });
 		try {
 			const unsecuredJwt = new UnsecuredJWT(introspect).encode();
-			const { audience: _audience, ...verifyOptions } = opts.verifyOptions;
-			payload = (introspect.aud ? UnsecuredJWT.decode(unsecuredJwt, opts.verifyOptions) : UnsecuredJWT.decode(unsecuredJwt, verifyOptions)).payload;
+			const { audience: _audience, ...verifyOptionsNoAudience } = opts.verifyOptions;
+			const skipAudience = !introspect.aud && opts.remoteVerify.allowMissingAudience === true;
+			payload = UnsecuredJWT.decode(unsecuredJwt, skipAudience ? verifyOptionsNoAudience : opts.verifyOptions).payload;
 		} catch (error) {
 			throw new Error(error);
 		}

package/dist/social-providers/facebook.mjs

@@ -7,6 +7,34 @@ import { validateAuthorizationCode } from "../oauth2/validate-authorization-code
 import { betterFetch } from "@better-fetch/fetch";
 import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
 //#region src/social-providers/facebook.ts
+/**
+* Validate an opaque Facebook access token against the configured app.
+*
+* Facebook access tokens are not audience-bound at the Graph `/me` endpoint: a
+* token minted for any Facebook app returns that app's profile. Without this
+* check, a token issued to an unrelated app could be presented to this
+* app's direct sign-in path and accepted as proof of identity. We call the
+* `debug_token` endpoint and require the token to be valid, bound to one of the
+* configured client ids, and tied to a user.
+*
+* @see https://developers.facebook.com/docs/facebook-login/guides/access-tokens/debugging
+*
+* @returns the inspected token's `user_id` when the token is valid and bound to
+* the configured app, otherwise `null`.
+*/
+async function verifyFacebookAccessToken(accessToken, options) {
+	const primaryClientId = getPrimaryClientId(options.clientId);
+	if (!primaryClientId || !options.clientSecret) return null;
+	const clientIds = Array.isArray(options.clientId) ? options.clientId : [options.clientId];
+	const { data, error } = await betterFetch("https://graph.facebook.com/debug_token", { query: {
+		input_token: accessToken,
+		access_token: `${primaryClientId}|${options.clientSecret}`
+	} });
+	if (error || !data?.data) return null;
+	const { is_valid, app_id, user_id } = data.data;
+	if (is_valid !== true || !app_id || !clientIds.includes(app_id) || !user_id) return null;
+	return user_id;
+}
 const facebook = (options) => {
 	return {
 		id: "facebook",
@@ -52,7 +80,7 @@ const facebook = (options) => {
 			} catch {
 				return false;
 			}
-			return true;
+			return await verifyFacebookAccessToken(token, options) !== null;
 		},
 		refreshAccessToken: options.refreshAccessToken ? options.refreshAccessToken : async (refreshToken) => {
 			return refreshAccessToken({
@@ -93,6 +121,10 @@ const facebook = (options) => {
 					data: profile
 				};
 			}
+			const accessToken = token.accessToken;
+			if (!accessToken) return null;
+			const tokenUserId = await verifyFacebookAccessToken(accessToken, options);
+			if (!tokenUserId) return null;
 			const { data: profile, error } = await betterFetch("https://graph.facebook.com/me?fields=" + [
 				"id",
 				"name",
@@ -101,9 +133,10 @@ const facebook = (options) => {
 				...options?.fields || []
 			].join(","), { auth: {
 				type: "Bearer",
-				token: token.accessToken
+				token: accessToken
 			} });
 			if (error) return null;
+			if (profile.id !== tokenUserId) return null;
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {

package/dist/social-providers/google.d.mts

@@ -37,7 +37,12 @@ interface GoogleOptions extends ProviderOptions<GoogleProfile> {
    */
   display?: ("page" | "popup" | "touch" | "wap") | undefined;
   /**
-   * The hosted domain of the user
+   * The hosted domain (Google Workspace) the user must belong to.
+   *
+   * This is sent to Google as the `hd` authorization hint and, when set, is
+   * also enforced against the `hd` claim of the returned id token/profile.
+   * Sign-in is rejected when the claim is missing or does not match, so this
+   * can be used to restrict sign-in to a Workspace domain.
    */
   hd?: string | undefined;
 }

package/dist/social-providers/google.mjs

@@ -73,6 +73,7 @@ const google = (options) => {
 					maxTokenAge: "1h"
 				});
 				if (nonce && jwtClaims.nonce !== nonce) return false;
+				if (options.hd && jwtClaims.hd !== options.hd) return false;
 				return true;
 			} catch {
 				return false;
@@ -82,6 +83,10 @@ const google = (options) => {
 			if (options.getUserInfo) return options.getUserInfo(token);
 			if (!token.idToken) return null;
 			const user = decodeJwt(token.idToken);
+			if (options.hd && user.hd !== options.hd) {
+				logger.error(`Google sign-in rejected: id token hosted domain (hd) "${user.hd ?? "<missing>"}" does not match the configured "hd" option "${options.hd}".`);
+				return null;
+			}
 			const userMap = await options.mapProfileToUser?.(user);
 			return {
 				user: {

package/dist/social-providers/index.d.mts

@@ -28,7 +28,7 @@ import { KakaoOptions, KakaoProfile, kakao } from "./kakao.mjs";
 import { NaverOptions, NaverProfile, naver } from "./naver.mjs";
 import { LineIdTokenPayload, LineOptions, LineUserInfo, line } from "./line.mjs";
 import { PaybinOptions, PaybinProfile, paybin } from "./paybin.mjs";
-import { PayPalOptions, PayPalProfile, PayPalTokenResponse, paypal } from "./paypal.mjs";
+import { PayPalOptions, PayPalProfile, PayPalTokenResponse, getPayPalPublicKey, paypal } from "./paypal.mjs";
 import { PolarOptions, PolarProfile, polar } from "./polar.mjs";
 import { RailwayOptions, RailwayProfile, railway } from "./railway.mjs";
 import { VercelOptions, VercelProfile, vercel } from "./vercel.mjs";
@@ -1831,4 +1831,4 @@ type SocialProviders = { [K in SocialProviderList[number]]?: AwaitableFunction<P
 }> };
 type SocialProviderList = typeof socialProviderList;
 //#endregion
-export { AccountStatus, AppleNonConformUser, AppleOptions, AppleProfile, AtlassianOptions, AtlassianProfile, CognitoOptions, CognitoProfile, DiscordOptions, DiscordProfile, DropboxOptions, DropboxProfile, FacebookOptions, FacebookProfile, FigmaOptions, FigmaProfile, GithubOptions, GithubProfile, GitlabOptions, GitlabProfile, GoogleOptions, GoogleProfile, HuggingFaceOptions, HuggingFaceProfile, KakaoOptions, KakaoProfile, KickOptions, KickProfile, LineIdTokenPayload, LineOptions, LineUserInfo, LinearOptions, LinearProfile, LinearUser, LinkedInOptions, LinkedInProfile, LoginType, MicrosoftEntraIDProfile, MicrosoftOptions, NaverOptions, NaverProfile, NotionOptions, NotionProfile, PayPalOptions, PayPalProfile, PayPalTokenResponse, PaybinOptions, PaybinProfile, PhoneNumber, PolarOptions, PolarProfile, PronounOption, RailwayOptions, RailwayProfile, RedditOptions, RedditProfile, RobloxOptions, RobloxProfile, SalesforceOptions, SalesforceProfile, SlackOptions, SlackProfile, SocialProvider, SocialProviderList, SocialProviderListEnum, SocialProviders, SpotifyOptions, SpotifyProfile, TiktokOptions, TiktokProfile, TwitchOptions, TwitchProfile, TwitterOption, TwitterProfile, VercelOptions, VercelProfile, VkOption, VkProfile, WeChatOptions, WeChatProfile, ZoomOptions, ZoomProfile, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, github, gitlab, google, huggingface, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, vk, wechat, zoom };
+export { AccountStatus, AppleNonConformUser, AppleOptions, AppleProfile, AtlassianOptions, AtlassianProfile, CognitoOptions, CognitoProfile, DiscordOptions, DiscordProfile, DropboxOptions, DropboxProfile, FacebookOptions, FacebookProfile, FigmaOptions, FigmaProfile, GithubOptions, GithubProfile, GitlabOptions, GitlabProfile, GoogleOptions, GoogleProfile, HuggingFaceOptions, HuggingFaceProfile, KakaoOptions, KakaoProfile, KickOptions, KickProfile, LineIdTokenPayload, LineOptions, LineUserInfo, LinearOptions, LinearProfile, LinearUser, LinkedInOptions, LinkedInProfile, LoginType, MicrosoftEntraIDProfile, MicrosoftOptions, NaverOptions, NaverProfile, NotionOptions, NotionProfile, PayPalOptions, PayPalProfile, PayPalTokenResponse, PaybinOptions, PaybinProfile, PhoneNumber, PolarOptions, PolarProfile, PronounOption, RailwayOptions, RailwayProfile, RedditOptions, RedditProfile, RobloxOptions, RobloxProfile, SalesforceOptions, SalesforceProfile, SlackOptions, SlackProfile, SocialProvider, SocialProviderList, SocialProviderListEnum, SocialProviders, SpotifyOptions, SpotifyProfile, TiktokOptions, TiktokProfile, TwitchOptions, TwitchProfile, TwitterOption, TwitterProfile, VercelOptions, VercelProfile, VkOption, VkProfile, WeChatOptions, WeChatProfile, ZoomOptions, ZoomProfile, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, getPayPalPublicKey, github, gitlab, google, huggingface, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, vk, wechat, zoom };

package/dist/social-providers/index.mjs

@@ -18,7 +18,7 @@ import { getMicrosoftPublicKey, microsoft } from "./microsoft-entra-id.mjs";
 import { naver } from "./naver.mjs";
 import { notion } from "./notion.mjs";
 import { paybin } from "./paybin.mjs";
-import { paypal } from "./paypal.mjs";
+import { getPayPalPublicKey, paypal } from "./paypal.mjs";
 import { polar } from "./polar.mjs";
 import { railway } from "./railway.mjs";
 import { reddit } from "./reddit.mjs";
@@ -75,4 +75,4 @@ const socialProviders = {
 const socialProviderList = Object.keys(socialProviders);
 const SocialProviderListEnum = z.enum(socialProviderList).or(z.string());
 //#endregion
-export { SocialProviderListEnum, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, github, gitlab, google, huggingface, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, vk, wechat, zoom };
+export { SocialProviderListEnum, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, getPayPalPublicKey, github, gitlab, google, huggingface, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, vk, wechat, zoom };

package/dist/social-providers/microsoft-entra-id.d.mts

@@ -151,7 +151,7 @@ declare const microsoft: (options: MicrosoftOptions) => {
     user?: {
       name?: {
         firstName?: string;
-        lastName? /** The primary username that represents the user */: string;
+        lastName?: string;
       };
       email?: string;
     } | undefined;