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

package/src/social-providers/slack.ts

@@ -1,6 +1,10 @@
 import { betterFetch } from "@better-fetch/fetch";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
-import { refreshAccessToken, validateAuthorizationCode } from "../oauth2";
+import {
+	createAuthorizationURL,
+	refreshAccessToken,
+	validateAuthorizationCode,
+} from "../oauth2";
 
 export interface SlackProfile extends Record<string, any> {
 	ok: boolean;
@@ -42,19 +46,21 @@ export const slack = (options: SlackOptions) => {
 	return {
 		id: "slack",
 		name: "Slack",
-		createAuthorizationURL({ state, scopes, redirectURI }) {
+		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope
 				? []
 				: ["openid", "profile", "email"];
 			if (scopes) _scopes.push(...scopes);
 			if (options.scope) _scopes.push(...options.scope);
-			const url = new URL("https://slack.com/openid/connect/authorize");
-			url.searchParams.set("scope", _scopes.join(" "));
-			url.searchParams.set("response_type", "code");
-			url.searchParams.set("client_id", options.clientId);
-			url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
-			url.searchParams.set("state", state);
-			return url;
+			return createAuthorizationURL({
+				id: "slack",
+				options,
+				authorizationEndpoint: "https://slack.com/openid/connect/authorize",
+				scopes: _scopes,
+				state,
+				redirectURI,
+				additionalParams,
+			});
 		},
 		validateAuthorizationCode: async ({ code, redirectURI }) => {
 			return validateAuthorizationCode({

package/src/social-providers/spotify.ts

@@ -24,7 +24,13 @@ export const spotify = (options: SpotifyOptions) => {
 	return {
 		id: "spotify",
 		name: "Spotify",
-		createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
 			const _scopes = options.disableDefaultScope ? [] : ["user-read-email"];
 			if (options.scope) _scopes.push(...options.scope);
 			if (scopes) _scopes.push(...scopes);
@@ -36,6 +42,7 @@ export const spotify = (options: SpotifyOptions) => {
 				state,
 				codeVerifier,
 				redirectURI,
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {

package/src/social-providers/tiktok.ts

@@ -1,6 +1,10 @@
 import { betterFetch } from "@better-fetch/fetch";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
-import { refreshAccessToken, validateAuthorizationCode } from "../oauth2";
+import {
+	RESERVED_AUTHORIZATION_PARAMS_SET,
+	refreshAccessToken,
+	validateAuthorizationCode,
+} from "../oauth2";
 
 /**
  * [More info](https://developers.tiktok.com/doc/tiktok-api-v2-get-user-info/)
@@ -131,17 +135,26 @@ export const tiktok = (options: TiktokOptions) => {
 	return {
 		id: "tiktok",
 		name: "TikTok",
-		createAuthorizationURL({ state, scopes, redirectURI }) {
+		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["user.info.profile"];
 			if (options.scope) _scopes.push(...options.scope);
 			if (scopes) _scopes.push(...scopes);
-			return new URL(
-				`https://www.tiktok.com/v2/auth/authorize?scope=${_scopes.join(
-					",",
-				)}&response_type=code&client_key=${options.clientKey}&redirect_uri=${encodeURIComponent(
-					options.redirectURI || redirectURI,
-				)}&state=${state}`,
-			);
+			// TikTok uses `client_key` instead of the standard `client_id`, so the
+			// shared createAuthorizationURL helper cannot be used directly.
+			const url = new URL("https://www.tiktok.com/v2/auth/authorize");
+			url.searchParams.set("scope", _scopes.join(","));
+			url.searchParams.set("response_type", "code");
+			url.searchParams.set("client_key", options.clientKey);
+			url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
+			url.searchParams.set("state", state);
+			if (additionalParams) {
+				for (const [key, value] of Object.entries(additionalParams)) {
+					if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
+					if (key === "client_key") continue;
+					url.searchParams.set(key, value);
+				}
+			}
+			return url;
 		},
 
 		validateAuthorizationCode: async ({ code, redirectURI }) => {

package/src/social-providers/twitch.ts

@@ -42,7 +42,7 @@ export const twitch = (options: TwitchOptions) => {
 	return {
 		id: "twitch",
 		name: "Twitch",
-		createAuthorizationURL({ state, scopes, redirectURI }) {
+		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope
 				? []
 				: ["user:read:email", "openid"];
@@ -61,6 +61,7 @@ export const twitch = (options: TwitchOptions) => {
 					"preferred_username",
 					"picture",
 				],
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, redirectURI }) => {

package/src/social-providers/twitter.ts

@@ -122,6 +122,7 @@ export const twitter = (options: TwitterOption) => {
 				state: data.state,
 				codeVerifier: data.codeVerifier,
 				redirectURI: data.redirectURI,
+				additionalParams: data.additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {

package/src/social-providers/vercel.ts

@@ -20,7 +20,13 @@ export const vercel = (options: VercelOptions) => {
 	return {
 		id: "vercel",
 		name: "Vercel",
-		createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
 			if (!codeVerifier) {
 				throw new BetterAuthError("codeVerifier is required for Vercel");
 			}
@@ -40,6 +46,7 @@ export const vercel = (options: VercelOptions) => {
 				state,
 				codeVerifier,
 				redirectURI,
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {

package/src/social-providers/vk.ts

@@ -30,7 +30,13 @@ export const vk = (options: VkOption) => {
 	return {
 		id: "vk",
 		name: "VK",
-		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		async createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
 			const _scopes = options.disableDefaultScope ? [] : ["email", "phone"];
 			if (options.scope) _scopes.push(...options.scope);
 			if (scopes) _scopes.push(...scopes);
@@ -44,6 +50,7 @@ export const vk = (options: VkOption) => {
 				state,
 				redirectURI,
 				codeVerifier,
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({

package/src/social-providers/wechat.ts

@@ -1,5 +1,6 @@
 import { betterFetch } from "@better-fetch/fetch";
 import type { OAuth2Tokens, OAuthProvider, ProviderOptions } from "../oauth2";
+import { RESERVED_AUTHORIZATION_PARAMS_SET } from "../oauth2";
 
 /**
  * WeChat user profile information
@@ -58,7 +59,7 @@ export const wechat = (options: WeChatOptions) => {
 	return {
 		id: "wechat",
 		name: "WeChat",
-		createAuthorizationURL({ state, scopes, redirectURI }) {
+		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["snsapi_login"];
 			options.scope && _scopes.push(...options.scope);
 			scopes && _scopes.push(...scopes);
@@ -72,6 +73,13 @@ export const wechat = (options: WeChatOptions) => {
 			url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
 			url.searchParams.set("state", state);
 			url.searchParams.set("lang", options.lang || "cn");
+			if (additionalParams) {
+				for (const [key, value] of Object.entries(additionalParams)) {
+					if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
+					if (key === "appid") continue;
+					url.searchParams.set(key, value);
+				}
+			}
 			url.hash = "wechat_redirect";
 
 			return url;

package/src/social-providers/zoom.ts

@@ -1,7 +1,7 @@
 import { betterFetch } from "@better-fetch/fetch";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
 import {
-	generateCodeChallenge,
+	createAuthorizationURL,
 	refreshAccessToken,
 	validateAuthorizationCode,
 } from "../oauth2";
@@ -152,25 +152,21 @@ export const zoom = (userOptions: ZoomOptions) => {
 	return {
 		id: "zoom",
 		name: "Zoom",
-		createAuthorizationURL: async ({ state, redirectURI, codeVerifier }) => {
-			const params = new URLSearchParams({
-				response_type: "code",
-				redirect_uri: options.redirectURI ? options.redirectURI : redirectURI,
-				client_id: options.clientId,
+		createAuthorizationURL: async ({
+			state,
+			redirectURI,
+			codeVerifier,
+			additionalParams,
+		}) =>
+			createAuthorizationURL({
+				id: "zoom",
+				options,
+				authorizationEndpoint: "https://zoom.us/oauth/authorize",
 				state,
-			});
-
-			if (options.pkce) {
-				const codeChallenge = await generateCodeChallenge(codeVerifier);
-				params.set("code_challenge_method", "S256");
-				params.set("code_challenge", codeChallenge);
-			}
-
-			const url = new URL("https://zoom.us/oauth/authorize");
-			url.search = params.toString();
-
-			return url;
-		},
+				redirectURI,
+				codeVerifier: options.pkce ? codeVerifier : undefined,
+				additionalParams,
+			}),
 		validateAuthorizationCode: async ({ code, redirectURI, codeVerifier }) => {
 			return validateAuthorizationCode({
 				code,

package/src/types/context.ts

@@ -158,7 +158,15 @@ export interface InternalAdapter<
 	 */
 	deleteAccount(id: string): Promise<void>;
 
-	deleteSessions(userIdOrSessionTokens: string | string[]): Promise<void>;
+	/**
+	 * Delete every session belonging to a user.
+	 */
+	deleteUserSessions(userId: string): Promise<void>;
+
+	/**
+	 * Delete sessions by their session tokens.
+	 */
+	deleteSessions(sessionTokens: string[]): Promise<void>;
 
 	findOAuthUser(
 		email: string,
@@ -196,8 +204,6 @@ export interface InternalAdapter<
 
 	findAccounts(userId: string): Promise<Account[]>;
 
-	findAccount(accountId: string): Promise<Account | null>;
-
 	findAccountByProviderId(
 		accountId: string,
 		providerId: string,
@@ -216,6 +222,21 @@ export interface InternalAdapter<
 
 	deleteVerificationByIdentifier(identifier: string): Promise<void>;
 
+	/**
+	 * Atomically consume a single-use verification row by `identifier` and
+	 * return it. Only the first concurrent caller receives the latest row;
+	 * subsequent callers receive `null`. Consuming one row invalidates the
+	 * whole identifier so stale rows cannot be replayed. Rows past their
+	 * `expiresAt` are treated as already invalid: the row is deleted but
+	 * `null` is returned, so callers do not need to gate on `expiresAt`
+	 * themselves. Callers MUST gate any state change (issue session, mint
+	 * token, change password) on a non-null result.
+	 *
+	 * Replaces the racy `findVerificationValue` + `deleteVerificationByIdentifier`
+	 * pair at single-use credential consumption sites.
+	 */
+	consumeVerificationValue(identifier: string): Promise<Verification | null>;
+
 	updateVerificationByIdentifier(
 		identifier: string,
 		data: Partial<Verification>,
@@ -306,7 +327,7 @@ export type AuthContext<Options extends BetterAuthOptions = 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";
 			};

package/src/types/init-options.ts

@@ -207,12 +207,13 @@ export 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;
 	/**
@@ -1020,6 +1021,25 @@ export 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
@@ -1073,7 +1093,11 @@ export 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
 					 */
@@ -1106,7 +1130,7 @@ export 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";
 				/**

package/src/utils/ip.ts

@@ -12,12 +12,13 @@ import * as z from "zod";
 
 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;
 }
 
 /**
@@ -117,15 +118,13 @@ function expandIPv6(ipv6: string): string[] {
  * Normalizes an IPv6 address to canonical form
  * e.g., "2001:DB8::1" -> "2001:0db8:0000:0000:0000:0000:0000:0001"
  */
-function normalizeIPv6(
-	ipv6: string,
-	subnetPrefix?: 128 | 32 | 48 | 64,
-): string {
+function normalizeIPv6(ipv6: string, subnetPrefix?: number): string {
 	const groups = expandIPv6(ipv6);
 
-	if (subnetPrefix && subnetPrefix < 128) {
-		// Apply subnet mask
-		const prefix = subnetPrefix;
+	if (subnetPrefix !== undefined && subnetPrefix < 128) {
+		// Clamp to a valid bit range so out-of-spec inputs degrade safely:
+		// negative or fractional values would otherwise produce malformed masks.
+		const prefix = Math.max(0, Math.floor(subnetPrefix));
 		let bitsRemaining: number = prefix;
 
 		const maskedGroups = groups.map((group) => {
@@ -191,8 +190,8 @@ export function normalizeIP(
 		return ipv4.toLowerCase();
 	}
 
-	// Normalize IPv6
-	const subnetPrefix = options.ipv6Subnet || 64;
+	// Normalize IPv6. Use ?? so an explicit 0 (mask-all) is honoured.
+	const subnetPrefix = options.ipv6Subnet ?? 64;
 	return normalizeIPv6(ip, subnetPrefix);
 }
 

package/src/utils/redirect-uri.ts

@@ -0,0 +1,54 @@
+import * as z from "zod";
+import { isLoopbackHost } from "./host";
+import { DANGEROUS_URL_SCHEMES } from "./url";
+
+/**
+ * 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.
+ */
+export const SafeUrlSchema = z.url().superRefine((val, ctx) => {
+	let u: URL;
+	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)",
+		});
+	}
+});

package/src/utils/string.ts

@@ -1,3 +1,40 @@
 export function capitalizeFirstLetter(str: string) {
 	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: string): string[] {
+	return input.replace(APOSTROPHE_PATTERN, "").match(WORD_PATTERN) ?? [];
+}
+
+export function toSnakeCase(input: string): string {
+	return splitWords(input)
+		.map((word) => word.toLowerCase())
+		.join("_");
+}
+
+export function toKebabCase(input: string): string {
+	return splitWords(input)
+		.map((word) => word.toLowerCase())
+		.join("-");
+}
+
+export function toCamelCase(input: string): string {
+	return splitWords(input).reduce((acc, word, i) => {
+		return (
+			acc +
+			(i === 0
+				? word.toLowerCase()
+				: `${word[0]!.toUpperCase()}${word.slice(1)}`)
+		);
+	}, "");
+}
+
+export function toPascalCase(input: string): string {
+	return splitWords(input)
+		.map((word) => `${word[0]!.toUpperCase()}${word.slice(1).toLowerCase()}`)
+		.join("");
+}

package/src/utils/url.ts

@@ -41,3 +41,31 @@ export function normalizePathname(
 
 	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`, ...).
+ */
+export 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.
+ */
+export function isSafeUrlScheme(value: string): boolean {
+	let parsed: URL;
+	try {
+		parsed = new URL(value);
+	} catch {
+		// Relative URLs carry no scheme to abuse.
+		return true;
+	}
+	return !DANGEROUS_URL_SCHEMES.includes(parsed.protocol);
+}