@better-auth/infra 0.2.1 → 0.2.3

package/dist/index.d.mts

@@ -101,6 +101,9 @@ interface SecurityOptions {
     action?: SecurityAction;
     domainAllowlist?: string[];
   };
+  emailNormalization?: {
+    enabled?: boolean;
+  };
   staleUsers?: {
     enabled: boolean;
     staleDays?: number;
@@ -181,6 +184,9 @@ declare const sentinel: (options?: SentinelOptions) => {
         action?: SecurityAction;
         domainAllowlist?: string[];
       } | undefined;
+      emailNormalization: {
+        enabled?: boolean;
+      } | undefined;
       databaseHooks: {
         user: {
           create: {
@@ -723,7 +729,7 @@ interface DashIdRow {
   id: string;
 }
 //#endregion
-//#region ../../node_modules/.bun/@better-auth+scim@1.6.1+27eabf8bb9704597/node_modules/@better-auth/scim/dist/index.d.mts
+//#region ../../node_modules/.bun/@better-auth+scim@1.6.1+f10cf570321458be/node_modules/@better-auth/scim/dist/index.d.mts
 //#region src/types.d.ts
 interface SCIMProvider {
   id: string;
@@ -4586,7 +4592,7 @@ interface DashCheckUserExistsResponse {
  * - Normalize googlemail.com to gmail.com
  *
  * @param email - Raw email to normalize
- * @param context - Auth context with getPlugin (for sentinel policy)
+ * @param context - Auth context
  */
 declare function normalizeEmail(email: string, context: AuthContext): string;
 //#endregion

package/dist/index.mjs

@@ -958,8 +958,8 @@ function createIdentificationMiddleware(options) {
 			return;
 		}
 		const ipAddress = getClientIpFromRequest(ctx.request, ipConfig?.ipAddressHeaders || null);
-		const countryCode = getCountryCodeFromRequest(ctx.request);
-		if (ipAddress || countryCode) {
+		if (ipAddress) {
+			const countryCode = getCountryCodeFromRequest(ctx.request);
 			ctx.context.location = {
 				ipAddress,
 				countryCode
@@ -997,502 +997,6 @@ function getCountryCodeFromRequest(request) {
 	return cc ? cc.toUpperCase() : void 0;
 }
 //#endregion
-//#region src/validation/matchers.ts
-const paths = [
-	"/sign-up/email",
-	"/email-otp/verify-email",
-	"/sign-in/email-otp",
-	"/sign-in/magic-link",
-	"/sign-in/email",
-	"/forget-password/email-otp",
-	"/email-otp/reset-password",
-	"/email-otp/create-verification-otp",
-	"/email-otp/get-verification-otp",
-	"/email-otp/send-verification-otp",
-	"/forget-password",
-	"/request-password-reset",
-	"/send-verification-email",
-	"/change-email"
-];
-const all = new Set(paths);
-new Set(paths.slice(1, 12));
-/**
-* Path is one of `[
-*   '/sign-up/email',
-*   '/email-otp/verify-email',
-*   '/sign-in/email-otp',
-*   '/sign-in/magic-link',
-*   '/sign-in/email',
-*   '/forget-password/email-otp',
-*   '/email-otp/reset-password',
-*   '/email-otp/create-verification-otp',
-*   '/email-otp/get-verification-otp',
-*   '/email-otp/send-verification-otp',
-*   '/forget-password',
-*   '/request-password-reset',
-*   '/send-verification-email',
-*   '/change-email'
-* ]`.
-* @param context Request context
-* @param context.path Request path
-* @returns boolean
-*/
-const allEmail = ({ path }) => !!path && all.has(path);
-//#endregion
-//#region src/validation/email.ts
-/**
-* Gmail-like providers that ignore dots in the local part
-*/
-const GMAIL_LIKE_DOMAINS = new Set(["gmail.com", "googlemail.com"]);
-/**
-* Providers known to support plus addressing
-*/
-const PLUS_ADDRESSING_DOMAINS = new Set([
-	"gmail.com",
-	"googlemail.com",
-	"outlook.com",
-	"hotmail.com",
-	"live.com",
-	"yahoo.com",
-	"icloud.com",
-	"me.com",
-	"mac.com",
-	"protonmail.com",
-	"proton.me",
-	"fastmail.com",
-	"zoho.com"
-]);
-/**
-* Normalize an email address for comparison/deduplication
-* - Lowercase the entire email
-* - Remove dots from Gmail-like providers (they ignore dots)
-* - Remove plus addressing (user+tag@domain → user@domain)
-* - Normalize googlemail.com to gmail.com
-*
-* @param email - Raw email to normalize
-* @param context - Auth context with getPlugin (for sentinel policy)
-*/
-function normalizeEmail(email, context) {
-	if (!email || typeof email !== "string") return email;
-	if ((context.getPlugin?.("sentinel"))?.options?.emailValidation?.enabled === false) return email;
-	const trimmed = email.trim().toLowerCase();
-	const atIndex = trimmed.lastIndexOf("@");
-	if (atIndex === -1) return trimmed;
-	let localPart = trimmed.slice(0, atIndex);
-	let domain = trimmed.slice(atIndex + 1);
-	if (domain === "googlemail.com") domain = "gmail.com";
-	if (PLUS_ADDRESSING_DOMAINS.has(domain)) {
-		const plusIndex = localPart.indexOf("+");
-		if (plusIndex !== -1) localPart = localPart.slice(0, plusIndex);
-	}
-	if (GMAIL_LIKE_DOMAINS.has(domain)) localPart = localPart.replace(/\./g, "");
-	return `${localPart}@${domain}`;
-}
-function createEmailValidator(options = {}) {
-	const { apiKey = "", apiUrl = INFRA_API_URL, kvUrl = INFRA_KV_URL, defaultConfig = {} } = options;
-	const $api = createFetch({
-		baseURL: apiUrl,
-		headers: { "x-api-key": apiKey }
-	});
-	const $kv = createFetch({
-		baseURL: kvUrl,
-		headers: { "x-api-key": apiKey },
-		timeout: KV_TIMEOUT_MS
-	});
-	/**
-	* Fetch and resolve email validity policy from API with caching
-	* Sends client config to API which merges with user's dashboard settings
-	*/
-	async function fetchPolicy() {
-		try {
-			const { data } = await $api("/security/resolve-policy", {
-				method: "POST",
-				body: {
-					policyId: "email_validity",
-					config: { emailValidation: {
-						enabled: defaultConfig.enabled,
-						strictness: defaultConfig.strictness,
-						action: defaultConfig.action,
-						domainAllowlist: defaultConfig.domainAllowlist
-					} }
-				}
-			});
-			if (data?.policy) return data.policy;
-		} catch (error) {
-			logger.warn("[Dash] Failed to fetch email policy, using defaults:", error);
-		}
-		return null;
-	}
-	return { async validate(email, checkMx = true) {
-		const trimmed = email.trim();
-		const policy = await fetchPolicy();
-		if (!policy?.enabled) return {
-			valid: true,
-			disposable: false,
-			confidence: "high",
-			policy
-		};
-		try {
-			const { data } = await $kv("/email/validate", {
-				method: "POST",
-				body: {
-					email: trimmed,
-					checkMx,
-					strictness: policy.strictness
-				}
-			});
-			return {
-				...data || {
-					valid: false,
-					reason: "invalid_format"
-				},
-				policy
-			};
-		} catch (error) {
-			logger.warn("[Dash] Email validation API error, falling back to allow:", error);
-			return {
-				valid: true,
-				policy
-			};
-		}
-	} };
-}
-/**
-* Basic local email format validation (fallback)
-*/
-function isValidEmailFormatLocal(email) {
-	if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return false;
-	if (email.length > 254) return false;
-	const [localPart, domain] = email.split("@");
-	if (!localPart || !domain) return false;
-	if (localPart.length > 64) return false;
-	if (domain.length > 253) return false;
-	return true;
-}
-const getEmail = (ctx) => {
-	if (ctx.path === "/change-email") return {
-		email: ctx.body?.newEmail,
-		container: "body",
-		field: "newEmail"
-	};
-	const body = ctx.body;
-	const query = ctx.query;
-	return {
-		email: body?.email ?? query?.email,
-		container: body ? "body" : "query",
-		field: "email"
-	};
-};
-/**
-* Create email normalization hook (shared between all configurations)
-*/
-function createEmailNormalizationHook() {
-	return {
-		matcher: allEmail,
-		handler: createAuthMiddleware(async (ctx) => {
-			const { email, container, field } = getEmail(ctx);
-			if (typeof email !== "string") return;
-			const normalized = normalizeEmail(email, ctx.context);
-			if (normalized === email) return;
-			const data = container === "query" ? {
-				...ctx.query,
-				[field]: normalized
-			} : {
-				...ctx.body,
-				[field]: normalized
-			};
-			return { context: {
-				...ctx,
-				[container]: data
-			} };
-		})
-	};
-}
-/**
-* Create email validation hook with configurable validation strategy
-*/
-function createEmailValidationHook(validator, onDisposableEmail) {
-	return {
-		matcher: allEmail,
-		handler: createAuthMiddleware(async (ctx) => {
-			const { email } = getEmail(ctx);
-			if (typeof email !== "string") return;
-			const trimmed = email.trim();
-			if (!isValidEmailFormatLocal(trimmed)) throw new APIError$1("BAD_REQUEST", { message: "Invalid email" });
-			if (validator) {
-				const result = await validator.validate(trimmed);
-				const policy = result.policy;
-				if (!policy?.enabled) return;
-				if (policy.domainAllowlist?.length) {
-					const domain = trimmed.toLowerCase().split("@")[1];
-					if (domain && policy.domainAllowlist.includes(domain)) return;
-				}
-				const action = policy.action;
-				if (!result.valid) {
-					if ((result.disposable || result.reason === "no_mx_records" || result.reason === "blocklist" || result.reason === "known_invalid_email" || result.reason === "known_invalid_host" || result.reason === "reserved_tld" || result.reason === "provider_local_too_short") && onDisposableEmail) {
-						const ip = ctx.request?.headers?.get("x-forwarded-for")?.split(",")[0] || ctx.request?.headers?.get("cf-connecting-ip") || void 0;
-						onDisposableEmail({
-							email: trimmed,
-							reason: result.reason || "disposable",
-							confidence: result.confidence,
-							ip,
-							path: ctx.path,
-							action
-						});
-					}
-					if (action === "allow") return;
-					throw new APIError$1("BAD_REQUEST", { message: result.reason === "no_mx_records" ? "This email domain cannot receive emails" : result.disposable || result.reason === "blocklist" ? "Disposable email addresses are not allowed" : result.reason === "known_invalid_email" || result.reason === "known_invalid_host" || result.reason === "reserved_tld" || result.reason === "provider_local_too_short" ? "This email address appears to be invalid" : "Invalid email" });
-				}
-			}
-		})
-	};
-}
-/**
-* Create email validation hooks with optional API-backed validation
-*
-* @param options - Configuration options
-* @param options.enabled - Enable email validation (default: true)
-* @param options.useApi - Use API-backed validation (requires apiKey)
-* @param options.apiKey - API key for remote validation
-* @param options.apiUrl - API URL for policy fetching (defaults to INFRA_API_URL)
-* @param options.kvUrl - KV URL for email validation (defaults to INFRA_KV_URL)
-* @param options.strictness - Default strictness level: 'low', 'medium' (default), or 'high'
-* @param options.action - Default action when invalid: 'allow', 'block' (default), or 'challenge'
-*
-* @example
-* // Local validation only
-* createEmailHooks()
-*
-* @example
-* // API-backed validation
-* createEmailHooks({ useApi: true, apiKey: "your-api-key" })
-*
-* @example
-* // API-backed validation with high strictness default
-* createEmailHooks({ useApi: true, apiKey: "your-api-key", strictness: "high" })
-*/
-function createEmailHooks(options = {}) {
-	const { useApi = false, apiKey = "", apiUrl = INFRA_API_URL, kvUrl = INFRA_KV_URL, defaultConfig, onDisposableEmail } = options;
-	const emailConfig = {
-		enabled: true,
-		strictness: "medium",
-		action: "block",
-		...defaultConfig
-	};
-	if (!emailConfig.enabled) return { before: [] };
-	const validator = useApi ? createEmailValidator({
-		apiUrl,
-		kvUrl,
-		apiKey,
-		defaultConfig: emailConfig
-	}) : void 0;
-	return { before: [createEmailNormalizationHook(), createEmailValidationHook(validator, onDisposableEmail)] };
-}
-createEmailHooks();
-//#endregion
-//#region src/validation/phone.ts
-/**
-* Common fake/test phone numbers that should be blocked
-* These are numbers commonly used in testing, movies, documentation, etc.
-*/
-const INVALID_PHONE_NUMBERS = new Set([
-	"+15550000000",
-	"+15550001111",
-	"+15550001234",
-	"+15551234567",
-	"+15555555555",
-	"+15551111111",
-	"+15550000001",
-	"+15550123456",
-	"+12125551234",
-	"+13105551234",
-	"+14155551234",
-	"+12025551234",
-	"+10000000000",
-	"+11111111111",
-	"+12222222222",
-	"+13333333333",
-	"+14444444444",
-	"+15555555555",
-	"+16666666666",
-	"+17777777777",
-	"+18888888888",
-	"+19999999999",
-	"+11234567890",
-	"+10123456789",
-	"+19876543210",
-	"+441632960000",
-	"+447700900000",
-	"+447700900001",
-	"+447700900123",
-	"+447700900999",
-	"+442079460000",
-	"+442079460123",
-	"+441134960000",
-	"+0000000000",
-	"+1000000000",
-	"+123456789",
-	"+1234567890",
-	"+12345678901",
-	"+0123456789",
-	"+9876543210",
-	"+11111111111",
-	"+99999999999",
-	"+491234567890",
-	"+491111111111",
-	"+33123456789",
-	"+33111111111",
-	"+61123456789",
-	"+61111111111",
-	"+81123456789",
-	"+81111111111",
-	"+19001234567",
-	"+19761234567",
-	"+1911",
-	"+1411",
-	"+1611",
-	"+44999",
-	"+44112"
-]);
-/**
-* Patterns that indicate fake/test phone numbers
-*/
-const INVALID_PHONE_PATTERNS = [
-	/^\+\d(\d)\1{6,}$/,
-	/^\+\d*1234567890/,
-	/^\+\d*0123456789/,
-	/^\+\d*9876543210/,
-	/^\+\d*0987654321/,
-	/^\+\d*(12){4,}/,
-	/^\+\d*(21){4,}/,
-	/^\+\d*(00){4,}/,
-	/^\+1\d{3}555\d{4}$/,
-	/^\+\d{1,3}\d{1,5}$/,
-	/^\+\d+0{7,}$/,
-	/^\+\d*147258369/,
-	/^\+\d*258369147/,
-	/^\+\d*369258147/,
-	/^\+\d*789456123/,
-	/^\+\d*123456789/,
-	/^\+\d*1234512345/,
-	/^\+\d*1111122222/,
-	/^\+\d*1212121212/,
-	/^\+\d*1010101010/
-];
-/**
-* Invalid area codes / prefixes that indicate test numbers
-* Key: country code, Value: set of invalid prefixes
-*/
-const INVALID_PREFIXES_BY_COUNTRY = {
-	US: new Set([
-		"555",
-		"000",
-		"111",
-		"911",
-		"411",
-		"611"
-	]),
-	CA: new Set([
-		"555",
-		"000",
-		"911"
-	]),
-	GB: new Set([
-		"7700900",
-		"1632960",
-		"1134960"
-	]),
-	AU: new Set([
-		"0491570",
-		"0491571",
-		"0491572"
-	])
-};
-/**
-* Check if a phone number is a commonly used fake/test number
-* @param phone - The phone number to check (E.164 format preferred)
-* @param defaultCountry - Default country code if not included in phone string
-* @returns true if the phone appears to be fake/test, false if it seems legitimate
-*/
-const isFakePhoneNumber = (phone, defaultCountry) => {
-	const parsed = parsePhoneNumberFromString(phone, defaultCountry);
-	if (!parsed) return true;
-	const e164 = parsed.number;
-	const nationalNumber = parsed.nationalNumber;
-	const country = parsed.country;
-	if (INVALID_PHONE_NUMBERS.has(e164)) return true;
-	for (const pattern of INVALID_PHONE_PATTERNS) if (pattern.test(e164)) return true;
-	if (country && INVALID_PREFIXES_BY_COUNTRY[country]) {
-		const prefixes = INVALID_PREFIXES_BY_COUNTRY[country];
-		for (const prefix of prefixes) if (nationalNumber.startsWith(prefix)) return true;
-	}
-	if (/^(\d)\1+$/.test(nationalNumber)) return true;
-	const digits = nationalNumber.split("").map(Number);
-	let isSequential = digits.length >= 6;
-	for (let i = 1; i < digits.length && isSequential; i++) {
-		const current = digits[i];
-		const previous = digits[i - 1];
-		if (current === void 0 || previous === void 0 || current !== previous + 1 && current !== previous - 1) isSequential = false;
-	}
-	if (isSequential) return true;
-	return false;
-};
-/**
-* Validate a phone number format
-* @param phone - The phone number to validate
-* @param defaultCountry - Default country code if not included in phone string
-* @returns true if the phone number is valid
-*/
-const isValidPhone = (phone, defaultCountry) => {
-	return isValidPhoneNumber(phone, defaultCountry);
-};
-/**
-* Comprehensive phone number validation
-* @param phone - The phone number to validate
-* @param options - Validation options
-* @returns true if valid, false otherwise
-*/
-const validatePhone = (phone, options = {}) => {
-	const { mobileOnly = false, allowedCountries, blockedCountries, blockFakeNumbers = true, blockPremiumRate = true, blockTollFree = false, blockVoip = false, defaultCountry } = options;
-	if (!isValidPhone(phone, defaultCountry)) return false;
-	const parsed = parsePhoneNumberFromString(phone, defaultCountry);
-	if (!parsed) return false;
-	if (blockFakeNumbers && isFakePhoneNumber(phone, defaultCountry)) return false;
-	const country = parsed.country;
-	if (country) {
-		if (allowedCountries && !allowedCountries.includes(country)) return false;
-		if (blockedCountries?.includes(country)) return false;
-	}
-	const phoneType = parsed.getType();
-	if (mobileOnly) {
-		if (phoneType !== "MOBILE" && phoneType !== "FIXED_LINE_OR_MOBILE") return false;
-	}
-	if (blockPremiumRate && phoneType === "PREMIUM_RATE") return false;
-	if (blockTollFree && phoneType === "TOLL_FREE") return false;
-	if (blockVoip && phoneType === "VOIP") return false;
-	return true;
-};
-const allPhonePaths = new Set([
-	"/phone-number/send-otp",
-	"/phone-number/verify",
-	"/sign-in/phone-number",
-	"/phone-number/request-password-reset",
-	"/phone-number/reset-password"
-]);
-const getPhoneNumber = (ctx) => ctx.body?.phoneNumber ?? ctx.query?.phoneNumber;
-/**
-* Better Auth plugin for phone number validation
-* Validates phone numbers on all phone-related endpoints
-*/
-const phoneValidationHooks = { before: [{
-	matcher: (context) => !!context.path && allPhonePaths.has(context.path),
-	handler: createAuthMiddleware(async (ctx) => {
-		const phoneNumber = getPhoneNumber(ctx);
-		if (typeof phoneNumber !== "string") return;
-		if (!validatePhone(phoneNumber)) throw new APIError$1("BAD_REQUEST", { message: "Invalid phone number" });
-	})
-}] };
-//#endregion
 //#region src/sentinel/security.ts
 async function hashForFingerprint(input) {
 	const data = new TextEncoder().encode(input);
@@ -1504,6 +1008,16 @@ async function sha1Hash(input) {
 	const hashBuffer = await crypto.subtle.digest("SHA-1", data);
 	return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("").toUpperCase();
 }
+/**
+* Whether Sentinel should normalize emails for deduplication/sign-in consistency.
+* If `emailNormalization` is set, it wins; otherwise legacy behavior uses `emailValidation.enabled`.
+* @internal Not part of the package public API; used by the sentinel plugin and email helpers.
+*/
+function isEmailNormalizationEnabled(security) {
+	const explicit = security?.emailNormalization;
+	if (explicit !== void 0) return explicit.enabled !== false;
+	return security?.emailValidation?.enabled !== false;
+}
 function createSecurityClient(apiUrl, apiKey, options, onSecurityEvent) {
 	const resolvedApiUrl = apiUrl || INFRA_API_URL;
 	const $api = createFetch({
@@ -1883,6 +1397,501 @@ function createSecurityClient(apiUrl, apiKey, options, onSecurityEvent) {
 	};
 }
 //#endregion
+//#region src/validation/matchers.ts
+const paths = [
+	"/sign-up/email",
+	"/email-otp/verify-email",
+	"/sign-in/email-otp",
+	"/sign-in/magic-link",
+	"/sign-in/email",
+	"/forget-password/email-otp",
+	"/email-otp/reset-password",
+	"/email-otp/create-verification-otp",
+	"/email-otp/get-verification-otp",
+	"/email-otp/send-verification-otp",
+	"/forget-password",
+	"/request-password-reset",
+	"/send-verification-email",
+	"/change-email"
+];
+const all = new Set(paths);
+new Set(paths.slice(1, 12));
+/**
+* Path is one of `[
+*   '/sign-up/email',
+*   '/email-otp/verify-email',
+*   '/sign-in/email-otp',
+*   '/sign-in/magic-link',
+*   '/sign-in/email',
+*   '/forget-password/email-otp',
+*   '/email-otp/reset-password',
+*   '/email-otp/create-verification-otp',
+*   '/email-otp/get-verification-otp',
+*   '/email-otp/send-verification-otp',
+*   '/forget-password',
+*   '/request-password-reset',
+*   '/send-verification-email',
+*   '/change-email'
+* ]`.
+* @param context Request context
+* @param context.path Request path
+* @returns boolean
+*/
+const allEmail = ({ path }) => !!path && all.has(path);
+//#endregion
+//#region src/validation/email.ts
+/**
+* Gmail-like providers that ignore dots in the local part
+*/
+const GMAIL_LIKE_DOMAINS = new Set(["gmail.com", "googlemail.com"]);
+/**
+* Providers known to support plus addressing
+*/
+const PLUS_ADDRESSING_DOMAINS = new Set([
+	"gmail.com",
+	"googlemail.com",
+	"outlook.com",
+	"hotmail.com",
+	"live.com",
+	"yahoo.com",
+	"icloud.com",
+	"me.com",
+	"mac.com",
+	"protonmail.com",
+	"proton.me",
+	"fastmail.com",
+	"zoho.com"
+]);
+/**
+* Normalize an email address for comparison/deduplication
+* - Lowercase the entire email
+* - Remove dots from Gmail-like providers (they ignore dots)
+* - Remove plus addressing (user+tag@domain → user@domain)
+* - Normalize googlemail.com to gmail.com
+*
+* @param email - Raw email to normalize
+* @param context - Auth context
+*/
+function normalizeEmail(email, context) {
+	if (!email || typeof email !== "string") return email;
+	const mergedOpts = context.options;
+	if (!isEmailNormalizationEnabled(mergedOpts)) return email;
+	const trimmed = email.trim().toLowerCase();
+	const atIndex = trimmed.lastIndexOf("@");
+	if (atIndex === -1) return trimmed;
+	let localPart = trimmed.slice(0, atIndex);
+	let domain = trimmed.slice(atIndex + 1);
+	if (domain === "googlemail.com") domain = "gmail.com";
+	if (PLUS_ADDRESSING_DOMAINS.has(domain)) {
+		const plusIndex = localPart.indexOf("+");
+		if (plusIndex !== -1) localPart = localPart.slice(0, plusIndex);
+	}
+	if (GMAIL_LIKE_DOMAINS.has(domain)) localPart = localPart.replace(/\./g, "");
+	return `${localPart}@${domain}`;
+}
+function createEmailValidator(options = {}) {
+	const { apiKey = "", apiUrl = INFRA_API_URL, kvUrl = INFRA_KV_URL, emailValidationOptions = {} } = options;
+	const $api = createFetch({
+		baseURL: apiUrl,
+		headers: { "x-api-key": apiKey }
+	});
+	const $kv = createFetch({
+		baseURL: kvUrl,
+		headers: { "x-api-key": apiKey },
+		timeout: KV_TIMEOUT_MS
+	});
+	/**
+	* Fetch and resolve email validity policy from API with caching
+	* Sends client config to API which merges with user's dashboard settings
+	*/
+	async function fetchPolicy() {
+		try {
+			const { data } = await $api("/security/resolve-policy", {
+				method: "POST",
+				body: {
+					policyId: "email_validity",
+					config: { emailValidation: {
+						enabled: emailValidationOptions.enabled,
+						strictness: emailValidationOptions.strictness,
+						action: emailValidationOptions.action,
+						domainAllowlist: emailValidationOptions.domainAllowlist
+					} }
+				}
+			});
+			if (data?.policy) return data.policy;
+		} catch (error) {
+			logger.warn("[Dash] Failed to fetch email policy, using defaults:", error);
+		}
+		return null;
+	}
+	return { async validate(email, checkMx = true) {
+		const trimmed = email.trim();
+		const policy = await fetchPolicy();
+		if (!policy?.enabled) return {
+			valid: true,
+			disposable: false,
+			confidence: "high",
+			policy
+		};
+		try {
+			const { data } = await $kv("/email/validate", {
+				method: "POST",
+				body: {
+					email: trimmed,
+					checkMx,
+					strictness: policy.strictness
+				}
+			});
+			return {
+				...data || {
+					valid: false,
+					reason: "invalid_format"
+				},
+				policy
+			};
+		} catch (error) {
+			logger.warn("[Dash] Email validation API error, falling back to allow:", error);
+			return {
+				valid: true,
+				policy
+			};
+		}
+	} };
+}
+/**
+* Basic local email format validation (fallback)
+*/
+function isValidEmailFormatLocal(email) {
+	if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return false;
+	if (email.length > 254) return false;
+	const [localPart, domain] = email.split("@");
+	if (!localPart || !domain) return false;
+	if (localPart.length > 64) return false;
+	if (domain.length > 253) return false;
+	return true;
+}
+const getEmail = (ctx) => {
+	if (ctx.path === "/change-email") return {
+		email: ctx.body?.newEmail,
+		container: "body",
+		field: "newEmail"
+	};
+	const body = ctx.body;
+	const query = ctx.query;
+	return {
+		email: body?.email ?? query?.email,
+		container: body ? "body" : "query",
+		field: "email"
+	};
+};
+/**
+* Create email normalization hook (shared between all configurations)
+*/
+function createEmailNormalizationHook() {
+	return {
+		matcher: allEmail,
+		handler: createAuthMiddleware(async (ctx) => {
+			const { email, container, field } = getEmail(ctx);
+			if (typeof email !== "string") return;
+			const normalized = normalizeEmail(email, ctx.context);
+			if (normalized === email) return;
+			const data = container === "query" ? {
+				...ctx.query,
+				[field]: normalized
+			} : {
+				...ctx.body,
+				[field]: normalized
+			};
+			return { context: {
+				...ctx,
+				[container]: data
+			} };
+		})
+	};
+}
+/**
+* Create email validation hook with configurable validation strategy
+*/
+function createEmailValidationHook(validator, onDisposableEmail) {
+	return {
+		matcher: allEmail,
+		handler: createAuthMiddleware(async (ctx) => {
+			const { email } = getEmail(ctx);
+			if (typeof email !== "string") return;
+			const trimmed = email.trim();
+			if (!isValidEmailFormatLocal(trimmed)) throw new APIError$1("BAD_REQUEST", { message: "Invalid email" });
+			if (validator) {
+				const result = await validator.validate(trimmed);
+				const policy = result.policy;
+				if (!policy?.enabled) return;
+				if (policy.domainAllowlist?.length) {
+					const domain = trimmed.toLowerCase().split("@")[1];
+					if (domain && policy.domainAllowlist.includes(domain)) return;
+				}
+				const action = policy.action;
+				if (!result.valid) {
+					if ((result.disposable || result.reason === "no_mx_records" || result.reason === "blocklist" || result.reason === "known_invalid_email" || result.reason === "known_invalid_host" || result.reason === "reserved_tld" || result.reason === "provider_local_too_short") && onDisposableEmail) {
+						const ip = ctx.request?.headers?.get("x-forwarded-for")?.split(",")[0] || ctx.request?.headers?.get("cf-connecting-ip") || void 0;
+						onDisposableEmail({
+							email: trimmed,
+							reason: result.reason || "disposable",
+							confidence: result.confidence,
+							ip,
+							path: ctx.path,
+							action
+						});
+					}
+					if (action === "allow") return;
+					throw new APIError$1("BAD_REQUEST", { message: result.reason === "no_mx_records" ? "This email domain cannot receive emails" : result.disposable || result.reason === "blocklist" ? "Disposable email addresses are not allowed" : result.reason === "known_invalid_email" || result.reason === "known_invalid_host" || result.reason === "reserved_tld" || result.reason === "provider_local_too_short" ? "This email address appears to be invalid" : "Invalid email" });
+				}
+			}
+		})
+	};
+}
+/**
+* Create email validation hooks with optional API-backed validation.
+*
+* @param options - {@link EmailHooksOptions}
+*
+* @example
+* // Local validation only
+* createEmailHooks()
+*
+* @example
+* // API-backed validation
+* createEmailHooks({ useApi: true, apiKey: "your-api-key" })
+*
+* @example
+* // High strictness + API
+* createEmailHooks({
+*   emailValidationOptions: { strictness: "high" },
+*   useApi: true,
+*   apiKey: "your-api-key",
+* })
+*/
+function createEmailHooks(options = {}) {
+	const { emailValidationOptions, emailNormalizationOptions, useApi = false, apiKey = "", apiUrl = INFRA_API_URL, kvUrl = INFRA_KV_URL, onDisposableEmail } = options;
+	const emailConfig = {
+		enabled: true,
+		strictness: "medium",
+		action: "block",
+		...emailValidationOptions
+	};
+	return { before: [...isEmailNormalizationEnabled({
+		emailValidation: emailValidationOptions,
+		emailNormalization: emailNormalizationOptions
+	}) ? [createEmailNormalizationHook()] : [], ...emailConfig.enabled ? [createEmailValidationHook(useApi ? createEmailValidator({
+		apiUrl,
+		kvUrl,
+		apiKey,
+		emailValidationOptions: emailConfig
+	}) : void 0, onDisposableEmail)] : []] };
+}
+createEmailHooks();
+//#endregion
+//#region src/validation/phone.ts
+/**
+* Common fake/test phone numbers that should be blocked
+* These are numbers commonly used in testing, movies, documentation, etc.
+*/
+const INVALID_PHONE_NUMBERS = new Set([
+	"+15550000000",
+	"+15550001111",
+	"+15550001234",
+	"+15551234567",
+	"+15555555555",
+	"+15551111111",
+	"+15550000001",
+	"+15550123456",
+	"+12125551234",
+	"+13105551234",
+	"+14155551234",
+	"+12025551234",
+	"+10000000000",
+	"+11111111111",
+	"+12222222222",
+	"+13333333333",
+	"+14444444444",
+	"+15555555555",
+	"+16666666666",
+	"+17777777777",
+	"+18888888888",
+	"+19999999999",
+	"+11234567890",
+	"+10123456789",
+	"+19876543210",
+	"+441632960000",
+	"+447700900000",
+	"+447700900001",
+	"+447700900123",
+	"+447700900999",
+	"+442079460000",
+	"+442079460123",
+	"+441134960000",
+	"+0000000000",
+	"+1000000000",
+	"+123456789",
+	"+1234567890",
+	"+12345678901",
+	"+0123456789",
+	"+9876543210",
+	"+11111111111",
+	"+99999999999",
+	"+491234567890",
+	"+491111111111",
+	"+33123456789",
+	"+33111111111",
+	"+61123456789",
+	"+61111111111",
+	"+81123456789",
+	"+81111111111",
+	"+19001234567",
+	"+19761234567",
+	"+1911",
+	"+1411",
+	"+1611",
+	"+44999",
+	"+44112"
+]);
+/**
+* Patterns that indicate fake/test phone numbers
+*/
+const INVALID_PHONE_PATTERNS = [
+	/^\+\d(\d)\1{6,}$/,
+	/^\+\d*1234567890/,
+	/^\+\d*0123456789/,
+	/^\+\d*9876543210/,
+	/^\+\d*0987654321/,
+	/^\+\d*(12){4,}/,
+	/^\+\d*(21){4,}/,
+	/^\+\d*(00){4,}/,
+	/^\+1\d{3}555\d{4}$/,
+	/^\+\d{1,3}\d{1,5}$/,
+	/^\+\d+0{7,}$/,
+	/^\+\d*147258369/,
+	/^\+\d*258369147/,
+	/^\+\d*369258147/,
+	/^\+\d*789456123/,
+	/^\+\d*123456789/,
+	/^\+\d*1234512345/,
+	/^\+\d*1111122222/,
+	/^\+\d*1212121212/,
+	/^\+\d*1010101010/
+];
+/**
+* Invalid area codes / prefixes that indicate test numbers
+* Key: country code, Value: set of invalid prefixes
+*/
+const INVALID_PREFIXES_BY_COUNTRY = {
+	US: new Set([
+		"555",
+		"000",
+		"111",
+		"911",
+		"411",
+		"611"
+	]),
+	CA: new Set([
+		"555",
+		"000",
+		"911"
+	]),
+	GB: new Set([
+		"7700900",
+		"1632960",
+		"1134960"
+	]),
+	AU: new Set([
+		"0491570",
+		"0491571",
+		"0491572"
+	])
+};
+/**
+* Check if a phone number is a commonly used fake/test number
+* @param phone - The phone number to check (E.164 format preferred)
+* @param defaultCountry - Default country code if not included in phone string
+* @returns true if the phone appears to be fake/test, false if it seems legitimate
+*/
+const isFakePhoneNumber = (phone, defaultCountry) => {
+	const parsed = parsePhoneNumberFromString(phone, defaultCountry);
+	if (!parsed) return true;
+	const e164 = parsed.number;
+	const nationalNumber = parsed.nationalNumber;
+	const country = parsed.country;
+	if (INVALID_PHONE_NUMBERS.has(e164)) return true;
+	for (const pattern of INVALID_PHONE_PATTERNS) if (pattern.test(e164)) return true;
+	if (country && INVALID_PREFIXES_BY_COUNTRY[country]) {
+		const prefixes = INVALID_PREFIXES_BY_COUNTRY[country];
+		for (const prefix of prefixes) if (nationalNumber.startsWith(prefix)) return true;
+	}
+	if (/^(\d)\1+$/.test(nationalNumber)) return true;
+	const digits = nationalNumber.split("").map(Number);
+	let isSequential = digits.length >= 6;
+	for (let i = 1; i < digits.length && isSequential; i++) {
+		const current = digits[i];
+		const previous = digits[i - 1];
+		if (current === void 0 || previous === void 0 || current !== previous + 1 && current !== previous - 1) isSequential = false;
+	}
+	if (isSequential) return true;
+	return false;
+};
+/**
+* Validate a phone number format
+* @param phone - The phone number to validate
+* @param defaultCountry - Default country code if not included in phone string
+* @returns true if the phone number is valid
+*/
+const isValidPhone = (phone, defaultCountry) => {
+	return isValidPhoneNumber(phone, defaultCountry);
+};
+/**
+* Comprehensive phone number validation
+* @param phone - The phone number to validate
+* @param options - Validation options
+* @returns true if valid, false otherwise
+*/
+const validatePhone = (phone, options = {}) => {
+	const { mobileOnly = false, allowedCountries, blockedCountries, blockFakeNumbers = true, blockPremiumRate = true, blockTollFree = false, blockVoip = false, defaultCountry } = options;
+	if (!isValidPhone(phone, defaultCountry)) return false;
+	const parsed = parsePhoneNumberFromString(phone, defaultCountry);
+	if (!parsed) return false;
+	if (blockFakeNumbers && isFakePhoneNumber(phone, defaultCountry)) return false;
+	const country = parsed.country;
+	if (country) {
+		if (allowedCountries && !allowedCountries.includes(country)) return false;
+		if (blockedCountries?.includes(country)) return false;
+	}
+	const phoneType = parsed.getType();
+	if (mobileOnly) {
+		if (phoneType !== "MOBILE" && phoneType !== "FIXED_LINE_OR_MOBILE") return false;
+	}
+	if (blockPremiumRate && phoneType === "PREMIUM_RATE") return false;
+	if (blockTollFree && phoneType === "TOLL_FREE") return false;
+	if (blockVoip && phoneType === "VOIP") return false;
+	return true;
+};
+const allPhonePaths = new Set([
+	"/phone-number/send-otp",
+	"/phone-number/verify",
+	"/sign-in/phone-number",
+	"/phone-number/request-password-reset",
+	"/phone-number/reset-password"
+]);
+const getPhoneNumber = (ctx) => ctx.body?.phoneNumber ?? ctx.query?.phoneNumber;
+/**
+* Better Auth plugin for phone number validation
+* Validates phone numbers on all phone-related endpoints
+*/
+const phoneValidationHooks = { before: [{
+	matcher: (context) => !!context.path && allPhonePaths.has(context.path),
+	handler: createAuthMiddleware(async (ctx) => {
+		const phoneNumber = getPhoneNumber(ctx);
+		if (typeof phoneNumber !== "string") return;
+		if (!validatePhone(phoneNumber)) throw new APIError$1("BAD_REQUEST", { message: "Invalid phone number" });
+	})
+}] };
+//#endregion
 //#region src/sentinel/security-hooks.ts
 const ERROR_MESSAGES = {
 	geo_blocked: "Access from your location is not allowed.",
@@ -2024,11 +2033,12 @@ const sentinel = (options) => {
 		});
 	});
 	const emailHooks = createEmailHooks({
+		emailValidationOptions: opts.security?.emailValidation,
+		emailNormalizationOptions: opts.security?.emailNormalization,
 		useApi: !!opts.apiKey,
 		apiKey: opts.apiKey,
 		apiUrl: opts.apiUrl,
 		kvUrl: opts.kvUrl,
-		defaultConfig: opts.security?.emailValidation,
 		onDisposableEmail: (data) => {
 			const isNoMxRecord = data.reason === "no_mx_records";
 			const reason = isNoMxRecord ? "no_mx_records" : "disposable_email";
@@ -2061,6 +2071,7 @@ const sentinel = (options) => {
 			const activityTrackingEnabled = (ctx.getPlugin("dash")?.options)?.activityTracking?.enabled === true;
 			return { options: {
 				emailValidation: opts.security?.emailValidation,
+				emailNormalization: opts.security?.emailNormalization,
 				databaseHooks: {
 					user: { create: {
 						async before(user, ctx) {
@@ -2070,7 +2081,7 @@ const sentinel = (options) => {
 								const abuseCheck = await securityService.checkFreeTrialAbuse(visitorId);
 								if (abuseCheck.isAbuse && abuseCheck.action === "block") throw new APIError("FORBIDDEN", { message: "Account creation is not allowed from this device." });
 							}
-							if (user.email && typeof user.email === "string" && opts.security?.emailValidation?.enabled !== false) return { data: {
+							if (user.email && typeof user.email === "string" && isEmailNormalizationEnabled(opts.security)) return { data: {
 								...user,
 								email: normalizeEmail(user.email, ctx.context)
 							} };
@@ -2746,7 +2757,7 @@ const jwtValidateMiddleware = (options) => createAuthMiddleware(async (ctx) => {
 });
 //#endregion
 //#region src/version.ts
-const PLUGIN_VERSION = "0.2.1";
+const PLUGIN_VERSION = "0.2.3";
 //#endregion
 //#region src/routes/auth/config.ts
 const PLUGIN_OPTIONS_EXCLUDE_KEYS = { stripe: new Set(["stripeClient"]) };
@@ -2758,23 +2769,28 @@ function isPlainSerializable(value) {
 	if (constructor && constructor.name !== "Object" && constructor.name !== "Array") return false;
 	return true;
 }
-function sanitizePluginOptions(pluginId, options, seen = /* @__PURE__ */ new WeakSet()) {
+function sanitizePluginOptions(pluginId, options, visiting = /* @__PURE__ */ new WeakSet()) {
 	if (options === null || options === void 0) return options;
 	if (typeof options === "function") return void 0;
 	if (typeof options !== "object") return options;
-	if (seen.has(options)) return void 0;
-	seen.add(options);
-	const excludeKeys = PLUGIN_OPTIONS_EXCLUDE_KEYS[pluginId];
-	if (Array.isArray(options)) return options.map((item) => sanitizePluginOptions(pluginId, item, seen)).filter((item) => item !== void 0);
-	const result = {};
-	for (const [key, value] of Object.entries(options)) {
-		if (excludeKeys?.has(key)) continue;
-		if (typeof value === "function") continue;
-		if (value !== null && typeof value === "object" && !isPlainSerializable(value)) continue;
-		const sanitized = sanitizePluginOptions(pluginId, value, seen);
-		if (sanitized !== void 0) result[key] = sanitized;
+	const obj = options;
+	if (visiting.has(obj)) return void 0;
+	visiting.add(obj);
+	try {
+		const excludeKeys = PLUGIN_OPTIONS_EXCLUDE_KEYS[pluginId];
+		if (Array.isArray(options)) return options.map((item) => sanitizePluginOptions(pluginId, item, visiting)).filter((item) => item !== void 0);
+		const result = {};
+		for (const [key, value] of Object.entries(options)) {
+			if (excludeKeys?.has(key)) continue;
+			if (typeof value === "function") continue;
+			if (value !== null && typeof value === "object" && !isPlainSerializable(value)) continue;
+			const sanitized = sanitizePluginOptions(pluginId, value, visiting);
+			if (sanitized !== void 0) result[key] = sanitized;
+		}
+		return result;
+	} finally {
+		visiting.delete(obj);
 	}
-	return result;
 }
 function estimateEntropy(str) {
 	const unique = new Set(str).size;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/infra",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Dashboard and analytics plugin for Better Auth",
   "type": "module",
   "main": "dist/index.mjs",
@@ -70,7 +70,7 @@
     "expo-crypto": "^14.0.2",
     "happy-dom": "^20.8.9",
     "msw": "^2.13.0",
-    "tsdown": "^0.21.1",
+    "tsdown": "^0.21.8",
     "typescript": "catalog:",
     "zod": "catalog:"
   },