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

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.4",
   "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,7 +152,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@better-auth/utils": "0.4.0",
+    "@better-auth/utils": "0.4.1",
     "@better-fetch/fetch": "1.1.21",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
@@ -159,18 +160,18 @@
     "better-call": "1.3.5",
     "@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-auth/utils": "0.4.1",
     "@better-fetch/fetch": "1.1.21",
     "@opentelemetry/api": "^1.9.0",
     "better-call": "1.3.5",
     "@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,118 @@ 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",
+										},
+									],
+								});
+								// A non-numeric count coerces to a false miss, so fail loud.
+								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 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;

package/src/db/type.ts

@@ -311,6 +311,18 @@ export interface SecondaryStorage {
 	 * @returns - Value of the key
 	 */
 	get: (key: string) => Awaitable<unknown>;
+	/**
+	 * Atomically get a value and delete it from storage.
+	 *
+	 * This is optional for backwards compatibility with existing secondary
+	 * storage implementations. Single-use credential consumers use it when
+	 * present to avoid a read-then-delete race.
+	 *
+	 * TODO(secondary-storage-atomic-consume): make this required in the next
+	 * breaking release, or require database-backed verification storage for
+	 * security-sensitive consume paths.
+	 */
+	getAndDelete?: (key: string) => Awaitable<unknown>;
 	set: (
 		/**
 		 * Key to store

package/src/error/codes.ts

@@ -37,6 +37,7 @@ export const BASE_ERROR_CODES = defineErrorCodes({
 	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL:
 		"User already exists. Use another email.",
 	EMAIL_CAN_NOT_BE_UPDATED: "Email can not be updated",
+	CHANGE_EMAIL_DISABLED: "Change email is disabled",
 	CREDENTIAL_ACCOUNT_NOT_FOUND: "Credential account not found",
 	SESSION_EXPIRED: "Session expired. Re-authenticate to perform this action.",
 	FAILED_TO_UNLINK_LAST_ACCOUNT: "You can't unlink your last account",

package/src/oauth2/authorization-params.ts

@@ -0,0 +1,28 @@
+import * as z from "zod";
+import {
+	RESERVED_AUTHORIZATION_PARAMS,
+	RESERVED_AUTHORIZATION_PARAMS_SET,
+} from "./create-authorization-url";
+
+/**
+ * Zod schema for the `additionalParams` field on social sign-in and
+ * account-linking request bodies. Rejects any key reserved by the
+ * authorization-URL builder (see `RESERVED_AUTHORIZATION_PARAMS`), so
+ * a caller cannot overwrite `state`, PKCE, `redirect_uri`, etc.
+ */
+export const additionalAuthorizationParamsSchema = z
+	.record(z.string(), z.string())
+	.refine(
+		(value) =>
+			!Object.keys(value).some((key) =>
+				RESERVED_AUTHORIZATION_PARAMS_SET.has(key),
+			),
+		{
+			message: `additionalParams cannot include reserved OAuth parameters: ${RESERVED_AUTHORIZATION_PARAMS.join(", ")}`,
+		},
+	)
+	.meta({
+		description:
+			"Extra query parameters to append to the provider authorization URL (e.g. Cognito identity_provider, Google hd).",
+	})
+	.optional();

package/src/oauth2/basic-credentials.ts

@@ -0,0 +1,87 @@
+import { base64 } from "@better-auth/utils/base64";
+
+// RFC 7235 §2.1: auth scheme is case-insensitive and is followed by one or
+// more SP before the credentials. The trailing capture is everything after
+// the whitespace (may be empty, which downstream checks reject).
+const BASIC_AUTHORIZATION_PATTERN = /^Basic +(.*)$/i;
+
+/**
+ * Encodes a value using `application/x-www-form-urlencoded` per the URL
+ * Living Standard. Differs from `encodeURIComponent` in two ways: it escapes
+ * `!`, `'`, `(`, and `)`, and it represents space as `+` rather than `%20`.
+ * `*` is left unescaped, matching the URL Standard's percent-encode set.
+ */
+function formUrlEncode(value: string): string {
+	return new URLSearchParams({ v: value }).toString().slice("v=".length);
+}
+
+/**
+ * Inverse of `formUrlEncode`: decodes a single `application/x-www-form-urlencoded`
+ * value, handling both `+` and `%20` as space.
+ */
+function formUrlDecode(value: string): string {
+	const decoded = new URLSearchParams(`v=${value}`).get("v");
+	if (decoded === null) {
+		throw new Error("form-url-encoded value could not be decoded");
+	}
+	return decoded;
+}
+
+/**
+ * Encodes an OAuth client id and secret as an HTTP Basic credential string.
+ *
+ * Follows RFC 6749 §2.3.1: both values are `application/x-www-form-urlencoded`
+ * prior to base64 encoding. The returned string is the full value of the
+ * `Authorization` header, including the `Basic ` prefix.
+ */
+export function encodeBasicCredentials(
+	clientId: string,
+	clientSecret: string,
+): string {
+	const payload = `${formUrlEncode(clientId)}:${formUrlEncode(clientSecret)}`;
+	return `Basic ${base64.encode(payload)}`;
+}
+
+/**
+ * Decodes an `Authorization: Basic …` header value into its OAuth client id
+ * and secret.
+ *
+ * Scheme matching is case-insensitive and tolerates one or more spaces
+ * between the scheme and credentials per RFC 7235 §2.1. The base64 payload
+ * is split on the first `:` only, so secrets containing colons round-trip
+ * correctly. Each half is form-url-decoded per RFC 6749 §2.3.1, accepting
+ * both `+` and `%20` as space. Per the URL Living Standard, invalid
+ * percent-escapes pass through as-is; downstream client lookup will fail
+ * with `invalid_client` for malformed credentials.
+ *
+ * Throws when the header is not a Basic credential, when the base64 payload
+ * contains no `:`, or when either half is empty.
+ */
+export function decodeBasicCredentials(authorization: string): {
+	clientId: string;
+	clientSecret: string;
+} {
+	const match = authorization.match(BASIC_AUTHORIZATION_PATTERN);
+	if (!match) {
+		throw new Error("Authorization header is not a Basic credential");
+	}
+	const encoded = match[1] ?? "";
+	const decoded = new TextDecoder().decode(base64.decode(encoded));
+	const separatorIndex = decoded.indexOf(":");
+	if (separatorIndex === -1) {
+		throw new Error(
+			"Basic credential is missing the client id/secret separator",
+		);
+	}
+	const rawClientId = decoded.slice(0, separatorIndex);
+	const rawClientSecret = decoded.slice(separatorIndex + 1);
+	if (!rawClientId || !rawClientSecret) {
+		throw new Error(
+			"Basic credential client id and secret must both be non-empty",
+		);
+	}
+	return {
+		clientId: formUrlDecode(rawClientId),
+		clientSecret: formUrlDecode(rawClientSecret),
+	};
+}