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

package/src/types/init-options.ts

@@ -47,6 +47,98 @@ export type GenerateIdFn = (options: {
 	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.
+ */
+export 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"`).
+ */
+export 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"`. */
+export 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. */
+export 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}. */
+export 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" };
+ * }
+ * ```
+ */
+export type ValidateUserInfoSource = UserProvisioningSource & {
+	action: ValidateUserInfoAction;
+};
+
+export 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).
@@ -207,12 +299,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;
 	/**
@@ -776,6 +869,33 @@ export type BetterAuthOptions = {
 	 */
 	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
 				 */
@@ -1020,6 +1140,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 +1212,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 +1249,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);
+}