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

package/dist/types/init-options.d.mts

@@ -27,6 +27,73 @@ type GenerateIdFn = (options: {
   model: ModelNames;
   size?: number | undefined;
 }) => string | false;
+/**
+ * What Better Auth is about to do with an incoming identity when
+ * {@link BetterAuthOptions.user}'s `validateUserInfo` runs.
+ *
+ * - `create-user`: a brand-new user record is about to be created.
+ * - `link-account`: a new provider account is about to be linked to an
+ *   already-existing user.
+ * - `sign-in`: an existing OAuth or SSO user is signing in again. This is the
+ *   one case where the provider can assert *changed* data, so the hook receives
+ *   the fresh provider email and profile (not the stored row), letting a domain
+ *   or org policy reject a user whose provider identity moved out of bounds.
+ *
+ * Non-provider returning sign-ins are not re-validated: they carry only the
+ * stored row, which has not changed since `create-user` gated it. Use the admin
+ * plugin's ban controls or a `databaseHooks.session.create.before` hook to
+ * block those.
+ */
+type ValidateUserInfoAction = "create-user" | "link-account" | "sign-in";
+/**
+ * The authentication method that produced the incoming user info. The named
+ * methods cover Better Auth's built-ins; the open `string` keeps it extensible
+ * for plugins (for example `"scim"`).
+ */
+type ValidateUserInfoMethod = "oauth" | "sso-oidc" | "sso-saml" | "email-password" | "magic-link" | "email-otp" | "anonymous" | "siwe" | "phone-number" | "admin" | (string & {});
+/** OAuth-specific provisioning context; present only when `method` is `"oauth"`. */
+type ValidateUserInfoOAuthInfo = {
+  /** The social or generic OAuth provider id (e.g. `"google"`). */providerId: string; /** The raw provider profile (userinfo or id-token claims), unmapped. */
+  profile?: Record<string, unknown> | undefined;
+};
+/** SSO-specific provisioning context; present for OIDC and SAML SSO methods. */
+type ValidateUserInfoSSOInfo = {
+  /** The configured SSO provider id. */providerId: string; /** The raw OIDC claims or SAML assertion attributes, unmapped. */
+  profile?: Record<string, unknown> | undefined;
+};
+/** Provisioning origin passed to `createUser`; the creation seam adds `action: "create-user"` to build {@link ValidateUserInfoSource}. */
+type UserProvisioningSource = {
+  method: ValidateUserInfoMethod; /** Provider id and raw profile; present iff `method` is `"oauth"`. */
+  oauth?: ValidateUserInfoOAuthInfo | undefined; /** Provider id and raw profile; present iff `method` is `"sso-oidc"` or `"sso-saml"`. */
+  sso?: ValidateUserInfoSSOInfo | undefined;
+};
+/**
+ * The context passed to `validateUserInfo`: the lifecycle
+ * {@link ValidateUserInfoAction}, the {@link ValidateUserInfoMethod}, and (for
+ * OAuth/SSO provider methods) protocol-specific provider metadata.
+ *
+ * ```ts
+ * // Scope to one OAuth provider:
+ * if (source.oauth?.providerId !== "google") return;
+ * // Branch on the method:
+ * if (source.method === "anonymous") return { error: "no_anonymous" };
+ * // Inspect SSO claims:
+ * if (source.method === "sso-saml" && source.sso?.profile?.department !== "eng") {
+ *   return { error: "invalid_department" };
+ * }
+ * ```
+ */
+type ValidateUserInfoSource = UserProvisioningSource & {
+  action: ValidateUserInfoAction;
+};
+type ValidateUserInfoResult = {
+  /** A short, machine-readable rejection code, surfaced to the client. */error: string;
+  /**
+   * A human-readable reason, surfaced to the client. Do not put sensitive
+   * details here.
+   */
+  errorDescription?: string | undefined;
+};
 /**
  * Configuration for dynamic base URL resolution.
  * Allows Better Auth to work with multiple domains (e.g., Vercel preview deployments).
@@ -157,12 +224,13 @@ type BetterAuthAdvancedOptions = {
      */
     disableIpTracking?: boolean;
     /**
-     * IPv6 subnet prefix length for rate limiting.
-     * IPv6 addresses will be normalized to this subnet.
+     * IPv6 prefix length used to collapse addresses before rate-limit keying.
+     * Any integer from 0 to 128 is accepted; common values are 32, 48, 56, 64, 128.
+     * Out-of-range values fall back to safe behavior (negative -> mask all, > 128 -> no mask).
      *
      * @default 64
      */
-    ipv6Subnet?: 128 | 64 | 48 | 32;
+    ipv6Subnet?: number;
   } | undefined;
   /**
    * Force cookies to always use the `Secure` attribute. By default,
@@ -683,6 +751,30 @@ type BetterAuthOptions = {
    * User configuration
    */
   user?: (BetterAuthDBOptions<"user", keyof BaseUser> & {
+    /**
+     * Gate which identities Better Auth admits. Called just before
+     * `create-user`, `link-account`, and (for OAuth) `sign-in`, across
+     * every authentication method, including stateless setups with no
+     * persistent database. On `sign-in` the hook receives the *fresh*
+     * provider email and profile, so a domain policy can reject a user
+     * whose provider identity moved out of bounds.
+     *
+     * Non-provider returning sign-ins are not re-validated; use the admin
+     * plugin's ban controls or a `databaseHooks.session.create.before`
+     * hook for those.
+     *
+     * Return nothing to allow; return `{ error }` to reject. Browser flows
+     * redirect to the configured error URL; programmatic flows surface a
+     * `403`.
+     *
+     * TODO: rename to `validateUser` (and the `ValidateUserInfo*` types).
+     * "UserInfo" is the OIDC term and misleads for the email/password,
+     * SIWE, phone, and admin methods.
+     */
+    validateUserInfo?: (data: {
+      user: Partial<User> & Record<string, unknown>;
+      source: ValidateUserInfoSource;
+    }, context: GenericEndpointContext) => Awaitable<void | ValidateUserInfoResult>;
     /**
      * Changing email configuration
      */
@@ -906,6 +998,25 @@ type BetterAuthOptions = {
        * @default false
        */
       disableImplicitLinking?: boolean;
+      /**
+       * Require the existing local user row to have
+       * `emailVerified: true` before implicit account linking
+       * uses the IdP's `email_verified` claim as ownership
+       * proof. Defaults to `true` so an attacker who
+       * pre-registers an unverified account at a victim's
+       * email cannot have the victim's OAuth identity linked
+       * into the attacker-owned row on first sign-in. Set to
+       * `false` for backward compatibility on apps whose
+       * users sign up via OAuth without verifying their email
+       * locally; understand the takeover risk before doing
+       * so.
+       *
+       * @default true
+       *
+       * @deprecated The option will be removed on the next
+       * minor; the gate will become unconditional.
+       */
+      requireLocalEmailVerified?: boolean;
       /**
        * List of trusted providers. Can be a static array or a function
        * that returns providers dynamically. The function is called
@@ -943,7 +1054,11 @@ type BetterAuthOptions = {
        */
       allowUnlinkingAll?: boolean;
       /**
-       * If enabled (true), this will update the user information based on the newly linked account
+       * When enabled, linking an account copies the provider's profile onto
+       * the local user, matching the fields persisted on sign-up (`name`,
+       * `image`, and any `mapProfileToUser` fields). The local `email` and
+       * `emailVerified` are never changed, so a link cannot rebind the
+       * account's identity.
        *
        * @default false
        */
@@ -976,7 +1091,7 @@ type BetterAuthOptions = {
      * - "cookie": Store state in an encrypted cookie (stateless)
      * - "database": Store state in the database
      *
-     * @default "cookie"
+     * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
      */
     storeStateStrategy?: "database" | "cookie";
     /**
@@ -1355,4 +1470,4 @@ type BetterAuthOptions = {
   };
 };
 //#endregion
-export { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption };
+export { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource };

package/dist/utils/ip.d.mts

@@ -10,12 +10,13 @@
  */
 interface NormalizeIPOptions {
   /**
-   * For IPv6 addresses, extract the subnet prefix instead of full address.
-   * Common values: 32, 48, 64, 128 (default: 128 = full address)
+   * Prefix length used to collapse IPv6 addresses before keying.
+   * Any integer from 0 to 128 is accepted. Common values: 32, 48, 56, 64, 128.
+   * Values outside 0-128 are clamped.
    *
-   * @default 128
+   * @default 64
    */
-  ipv6Subnet?: 128 | 64 | 48 | 32;
+  ipv6Subnet?: number;
 }
 /**
  * Checks if an IP is valid IPv4 or IPv6

package/dist/utils/ip.mjs

@@ -60,8 +60,8 @@ function expandIPv6(ipv6) {
 */
 function normalizeIPv6(ipv6, subnetPrefix) {
 	const groups = expandIPv6(ipv6);
-	if (subnetPrefix && subnetPrefix < 128) {
-		let bitsRemaining = subnetPrefix;
+	if (subnetPrefix !== void 0 && subnetPrefix < 128) {
+		let bitsRemaining = Math.max(0, Math.floor(subnetPrefix));
 		return groups.map((group) => {
 			if (bitsRemaining <= 0) return "0000";
 			if (bitsRemaining >= 16) {
@@ -99,7 +99,7 @@ function normalizeIP(ip, options = {}) {
 	if (!isIPv6(ip)) return ip.toLowerCase();
 	const ipv4 = extractIPv4FromMapped(ip);
 	if (ipv4) return ipv4.toLowerCase();
-	return normalizeIPv6(ip, options.ipv6Subnet || 64);
+	return normalizeIPv6(ip, options.ipv6Subnet ?? 64);
 }
 /**
 * Creates a rate limit key from IP and path

package/dist/utils/redirect-uri.d.mts

@@ -0,0 +1,20 @@
+import * as z from "zod";
+
+//#region src/utils/redirect-uri.d.ts
+/**
+ * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
+ * server stores and later hands back to a browser.
+ *
+ * - Rejects dangerous schemes (`javascript:`, `data:`, `vbscript:`).
+ * - Rejects URIs with a fragment component (`#...`) per RFC 6749 §3.1.2.
+ * - Requires HTTPS, except for loopback hosts (`127.0.0.0/8`, `[::1]`,
+ *   `*.localhost` per RFC 6761), where HTTP is allowed for local development.
+ * - Allows custom schemes for mobile apps (e.g. `myapp://callback`).
+ *
+ * This is the single source of truth for redirect-URI validation across the
+ * OAuth provider plugins. Consume it from `@better-auth/core/utils/redirect-uri`
+ * rather than re-implementing the scheme policy per plugin.
+ */
+declare const SafeUrlSchema: z.ZodURL;
+//#endregion
+export { SafeUrlSchema };

package/dist/utils/redirect-uri.mjs

@@ -0,0 +1,48 @@
+import { isLoopbackHost } from "./host.mjs";
+import { DANGEROUS_URL_SCHEMES } from "./url.mjs";
+import * as z from "zod";
+//#region src/utils/redirect-uri.ts
+/**
+* Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
+* server stores and later hands back to a browser.
+*
+* - Rejects dangerous schemes (`javascript:`, `data:`, `vbscript:`).
+* - Rejects URIs with a fragment component (`#...`) per RFC 6749 §3.1.2.
+* - Requires HTTPS, except for loopback hosts (`127.0.0.0/8`, `[::1]`,
+*   `*.localhost` per RFC 6761), where HTTP is allowed for local development.
+* - Allows custom schemes for mobile apps (e.g. `myapp://callback`).
+*
+* This is the single source of truth for redirect-URI validation across the
+* OAuth provider plugins. Consume it from `@better-auth/core/utils/redirect-uri`
+* rather than re-implementing the scheme policy per plugin.
+*/
+const SafeUrlSchema = z.url().superRefine((val, ctx) => {
+	let u;
+	try {
+		u = new URL(val);
+	} catch {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL must be parseable",
+			fatal: true
+		});
+		return z.NEVER;
+	}
+	if (DANGEROUS_URL_SCHEMES.includes(u.protocol)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL cannot use javascript:, data:, or vbscript: scheme"
+		});
+		return;
+	}
+	if (val.includes("#")) ctx.addIssue({
+		code: "custom",
+		message: "Redirect URI must not contain a fragment component"
+	});
+	if (u.protocol === "http:" && !isLoopbackHost(u.host)) ctx.addIssue({
+		code: "custom",
+		message: "Redirect URI must use HTTPS (HTTP allowed only for loopback hosts)"
+	});
+});
+//#endregion
+export { SafeUrlSchema };

package/dist/utils/string.d.mts

@@ -1,4 +1,8 @@
 //#region src/utils/string.d.ts
 declare function capitalizeFirstLetter(str: string): string;
+declare function toSnakeCase(input: string): string;
+declare function toKebabCase(input: string): string;
+declare function toCamelCase(input: string): string;
+declare function toPascalCase(input: string): string;
 //#endregion
-export { capitalizeFirstLetter };
+export { capitalizeFirstLetter, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/utils/string.mjs

@@ -2,5 +2,24 @@
 function capitalizeFirstLetter(str) {
 	return str.charAt(0).toUpperCase() + str.slice(1);
 }
+const WORD_PATTERN = /[\p{Ll}\d]+|\p{Lu}+(?!\p{Ll})|\p{Lu}[\p{Ll}\d]+|\p{Lo}+/gu;
+const APOSTROPHE_PATTERN = /['\u2019]/g;
+function splitWords(input) {
+	return input.replace(APOSTROPHE_PATTERN, "").match(WORD_PATTERN) ?? [];
+}
+function toSnakeCase(input) {
+	return splitWords(input).map((word) => word.toLowerCase()).join("_");
+}
+function toKebabCase(input) {
+	return splitWords(input).map((word) => word.toLowerCase()).join("-");
+}
+function toCamelCase(input) {
+	return splitWords(input).reduce((acc, word, i) => {
+		return acc + (i === 0 ? word.toLowerCase() : `${word[0].toUpperCase()}${word.slice(1)}`);
+	}, "");
+}
+function toPascalCase(input) {
+	return splitWords(input).map((word) => `${word[0].toUpperCase()}${word.slice(1).toLowerCase()}`).join("");
+}
 //#endregion
-export { capitalizeFirstLetter };
+export { capitalizeFirstLetter, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/utils/url.d.mts

@@ -16,5 +16,22 @@
  * // Returns: "/sso/saml2/callback/provider1"
  */
 declare function normalizePathname(requestUrl: string, basePath: string): string;
+/**
+ * Schemes that execute or embed code when navigated to or accepted as a
+ * redirect target. These are never safe as an OAuth `redirect_uri` or as a
+ * client-side navigation target (`window.location.href`, `location.assign`, ...).
+ */
+declare const DANGEROUS_URL_SCHEMES: string[];
+/**
+ * Returns `false` only when `value` is an absolute URL using a dangerous scheme
+ * (`javascript:`, `data:`, `vbscript:`). Relative URLs (e.g. `/dashboard`) and
+ * safe absolute schemes (`http`, `https`, custom app schemes such as
+ * `myapp://`) return `true`.
+ *
+ * Use this to guard browser navigation sinks and any redirect target that may
+ * originate from untrusted input. It is intentionally narrow: it blocks code
+ * execution schemes without rejecting relative paths or mobile deep links.
+ */
+declare function isSafeUrlScheme(value: string): boolean;
 //#endregion
-export { normalizePathname };
+export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };

package/dist/utils/url.mjs

@@ -27,5 +27,34 @@ function normalizePathname(requestUrl, basePath) {
 	if (pathname.startsWith(basePath + "/")) return pathname.slice(basePath.length).replace(/\/+$/, "") || "/";
 	return pathname;
 }
+/**
+* Schemes that execute or embed code when navigated to or accepted as a
+* redirect target. These are never safe as an OAuth `redirect_uri` or as a
+* client-side navigation target (`window.location.href`, `location.assign`, ...).
+*/
+const DANGEROUS_URL_SCHEMES = [
+	"javascript:",
+	"data:",
+	"vbscript:"
+];
+/**
+* Returns `false` only when `value` is an absolute URL using a dangerous scheme
+* (`javascript:`, `data:`, `vbscript:`). Relative URLs (e.g. `/dashboard`) and
+* safe absolute schemes (`http`, `https`, custom app schemes such as
+* `myapp://`) return `true`.
+*
+* Use this to guard browser navigation sinks and any redirect target that may
+* originate from untrusted input. It is intentionally narrow: it blocks code
+* execution schemes without rejecting relative paths or mobile deep links.
+*/
+function isSafeUrlScheme(value) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return true;
+	}
+	return !DANGEROUS_URL_SCHEMES.includes(parsed.protocol);
+}
 //#endregion
-export { normalizePathname };
+export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.0-beta.3",
+  "version": "1.7.0-beta.5",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -93,12 +93,13 @@
     "./instrumentation": {
       "dev-source": "./src/instrumentation/index.ts",
       "types": "./dist/instrumentation/index.d.mts",
+      "workerd": "./dist/instrumentation/pure.index.mjs",
+      "edge": "./dist/instrumentation/pure.index.mjs",
+      "browser": "./dist/instrumentation/pure.index.mjs",
       "node": "./dist/instrumentation/index.mjs",
       "deno": "./dist/instrumentation/index.mjs",
       "bun": "./dist/instrumentation/index.mjs",
-      "edge": "./dist/instrumentation/pure.index.mjs",
-      "workerd": "./dist/instrumentation/pure.index.mjs",
-      "browser": "./dist/instrumentation/pure.index.mjs",
+      "import": "./dist/instrumentation/index.mjs",
       "default": "./dist/instrumentation/index.mjs"
     }
   },
@@ -151,26 +152,26 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@better-auth/utils": "0.4.0",
-    "@better-fetch/fetch": "1.1.21",
+    "@better-auth/utils": "0.4.1",
+    "@better-fetch/fetch": "1.2.2",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "better-call": "1.3.5",
+    "better-call": "1.3.6",
     "@cloudflare/workers-types": "^4.20250121.0",
     "jose": "^6.1.3",
-    "kysely": "^0.28.14",
+    "kysely": "^0.28.17 || ^0.29.0",
     "nanostores": "^1.1.1",
     "tsdown": "0.21.1"
   },
   "peerDependencies": {
-    "@better-auth/utils": "0.4.0",
-    "@better-fetch/fetch": "1.1.21",
+    "@better-auth/utils": "0.4.1",
+    "@better-fetch/fetch": "1.2.2",
     "@opentelemetry/api": "^1.9.0",
-    "better-call": "1.3.5",
+    "better-call": "1.3.6",
     "@cloudflare/workers-types": ">=4",
     "jose": "^6.1.0",
-    "kysely": "^0.28.5",
+    "kysely": "^0.28.5 || ^0.29.0",
     "nanostores": "^1.0.1"
   },
   "peerDependenciesMeta": {

package/src/db/adapter/factory.ts

@@ -133,6 +133,11 @@ export const createAdapterFactory =
 							!config.debugLogs.deleteMany
 						) {
 							return;
+						} else if (
+							method === "consumeOne" &&
+							!config.debugLogs.consumeOne
+						) {
+							return;
 						} else if (method === "count" && !config.debugLogs.count) {
 							return;
 						}
@@ -485,6 +490,7 @@ export const createAdapterFactory =
 				| "updateMany"
 				| "delete"
 				| "deleteMany"
+				| "consumeOne"
 				| "count";
 		}): W extends undefined ? undefined : CleanedWhere[] => {
 			if (!where) return undefined as any;
@@ -1312,6 +1318,126 @@ export const createAdapterFactory =
 				);
 				return res;
 			},
+			consumeOne: async <T>({
+				model: unsafeModel,
+				where: unsafeWhere,
+			}: {
+				model: string;
+				where: Where[];
+			}): Promise<T | null> => {
+				transactionId++;
+				const thisTransactionId = transactionId;
+				const model = getModelName(unsafeModel);
+				const where = transformWhereClause({
+					model: unsafeModel,
+					where: unsafeWhere,
+					action: "consumeOne",
+				});
+				unsafeModel = getDefaultModelName(unsafeModel);
+				debugLog(
+					{ method: "consumeOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(1, 3)}`,
+					`${formatMethod("consumeOne")} ${formatAction("ConsumeOne")}:`,
+					{ model, where },
+				);
+
+				let res: T | null;
+				let resultNeedsOutputTransform = true;
+				if (adapterInstance.consumeOne) {
+					res = await withSpan(
+						`db consumeOne ${model}`,
+						{
+							[ATTR_DB_OPERATION_NAME]: "consumeOne",
+							[ATTR_DB_COLLECTION_NAME]: model,
+						},
+						() => adapterInstance.consumeOne!<T>({ model, where }),
+					);
+				} else {
+					// TODO(consume-one-required): adapters without native `consumeOne`
+					// fall back to `transaction(findMany + deleteMany)`. Race-safe on
+					// engines with real transaction isolation; race window narrows
+					// (does not close) on adapters that fall through to sequential
+					// execution. Remove this branch when consumeOne becomes required.
+					// FIXME(consume-one-nested-transaction): custom adapters without a
+					// native consumeOne have no portable signal for "already inside a
+					// transaction". First-party adapters mark transaction-scoped
+					// adapters as as-is; make that capability explicit in the next
+					// breaking adapter contract.
+					res = await withSpan(
+						`db consumeOne ${model}`,
+						{
+							[ATTR_DB_OPERATION_NAME]: "consumeOne",
+							[ATTR_DB_COLLECTION_NAME]: model,
+						},
+						() =>
+							adapter.transaction(async (trx) => {
+								const rows = await trx.findMany<Record<string, any>>({
+									model: unsafeModel,
+									where: unsafeWhere,
+									limit: 1,
+								});
+								const target = rows[0];
+								if (!target) return null;
+								const deleted = await trx.deleteMany({
+									model: unsafeModel,
+									where: [
+										...unsafeWhere,
+										{
+											field: "id",
+											value: target.id,
+											operator: "eq",
+											connector: "AND",
+											mode: "sensitive",
+										},
+									],
+								});
+								// `deleteMany` is typed `Promise<number>`. A non-number breaks
+								// the contract, so fail loud. A finite-number check then closes
+								// the NaN/Infinity hole: `NaN > 0` is false and `Infinity > 0`
+								// is true, so a bare `deleted > 0` would misclassify both. Only
+								// a finite positive count proves we won the delete race; any
+								// other value fails closed (returns null) so a single-use row
+								// is never reported consumed without proof.
+								if (typeof deleted !== "number") {
+									throw new BetterAuthError(
+										`Adapter "${config.adapterId}" returned a non-numeric value from deleteMany during the consumeOne fallback. Return the number of deleted rows, or implement a native consumeOne for atomic single-use consumption.`,
+									);
+								}
+								return Number.isFinite(deleted) && deleted > 0
+									? (target as T)
+									: null;
+							}),
+					);
+					resultNeedsOutputTransform = false;
+				}
+
+				debugLog(
+					{ method: "consumeOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`,
+					`${formatMethod("consumeOne")} ${formatAction("DB Result")}:`,
+					{ model, data: res },
+				);
+				let transformed: any = res;
+				if (
+					!config.disableTransformOutput &&
+					resultNeedsOutputTransform &&
+					res
+				) {
+					transformed = await transformOutput(
+						res as Record<string, any>,
+						unsafeModel,
+						undefined,
+						undefined,
+					);
+				}
+				debugLog(
+					{ method: "consumeOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 3)}`,
+					`${formatMethod("consumeOne")} ${formatAction("Parsed Result")}:`,
+					{ model, data: transformed },
+				);
+				return transformed as T | null;
+			},
 			count: async ({
 				model: unsafeModel,
 				where: unsafeWhere,

package/src/db/adapter/index.ts

@@ -15,6 +15,7 @@ export type DBAdapterDebugLogOption =
 			findMany?: boolean | undefined;
 			delete?: boolean | undefined;
 			deleteMany?: boolean | undefined;
+			consumeOne?: boolean | undefined;
 			count?: boolean | undefined;
 	  }
 	| {
@@ -211,6 +212,7 @@ export interface DBAdapterFactoryConfig<
 					| "updateMany"
 					| "delete"
 					| "deleteMany"
+					| "consumeOne"
 					| "count";
 				/**
 				 * The model name.
@@ -445,6 +447,23 @@ export type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
 	}) => Promise<number>;
 	delete: <_T>(data: { model: string; where: Where[] }) => Promise<void>;
 	deleteMany: (data: { model: string; where: Where[] }) => Promise<number>;
+	/**
+	 * Atomically consume a single row matching the where clause: delete it and
+	 * return the deleted row, or return `null` if no row matched.
+	 * Implementations MUST NOT delete any additional rows that also match a
+	 * non-unique predicate.
+	 *
+	 * Under concurrent invocation against the same row, exactly one caller
+	 * receives the row; subsequent racers receive `null`. This is the
+	 * race-safe primitive for consuming single-use credentials
+	 * (verification tokens, authorization codes, one-time tokens).
+	 *
+	 * Always defined on the factory-wrapped adapter. When the underlying
+	 * `CustomAdapter` does not implement `consumeOne`, the factory provides
+	 * a fallback that wraps `findMany + deleteMany` in `transaction(...)`
+	 * and returns the row only when the delete reports an affected row.
+	 */
+	consumeOne: <T>(data: { model: string; where: Where[] }) => Promise<T | null>;
 	/**
 	 * Execute multiple operations in a transaction.
 	 * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -531,6 +550,19 @@ export interface CustomAdapter {
 		model: string;
 		where: CleanedWhere[];
 	}) => Promise<number>;
+	/**
+	 * Optional native atomic single-row consume. When omitted, the adapter
+	 * factory falls back to `transaction(findMany + deleteMany)`.
+	 * Implementing this method natively (e.g. `DELETE ... RETURNING *`,
+	 * `findOneAndDelete`, `OUTPUT deleted.*`) gives one round trip and the
+	 * strongest race-safety guarantee. Implementations must delete at most
+	 * one matching row. TODO(consume-one-required): tighten to required in the
+	 * next minor on `next`.
+	 */
+	consumeOne?: <T>(data: {
+		model: string;
+		where: CleanedWhere[];
+	}) => Promise<T | null>;
 	count: ({
 		model,
 		where,

package/src/db/adapter/types.ts

@@ -122,6 +122,7 @@ export type AdapterFactoryCustomizeAdapterCreator = (config: {
 			| "updateMany"
 			| "delete"
 			| "deleteMany"
+			| "consumeOne"
 			| "count";
 	}) => W extends undefined ? undefined : CleanedWhere[];
 }) => CustomAdapter;