feat(username): add custom username normalization option (#3412)

* feat(username): add custom username normalization option

* add transformer

* handle nullish values

---------

Co-authored-by: Bereket Engida <Bekacru@gmail.com>

Author: bortoz

docs/content/docs/plugins/username.mdx

@@ -190,3 +190,27 @@ const auth = betterAuth({
     ]
 })
 ```
+
+### Username Normalization
+
+A function that normalizes the username, or `false` if you want to disable normalization.
+
+By default, usernames are case-insensitive, so "TestUser" and "testuser", for example, are considered the same username. The `username` field will contain the normalized (lower case) username, while `displayUsername` will contain the original `username`.
+
+```ts title="auth.ts"
+import { betterAuth } from "better-auth"
+import { username } from "better-auth/plugins"
+
+const auth = betterAuth({
+    plugins: [
+        username({
+            usernameNormalization: (username) => {
+                return username.toLowerCase()
+                    .replaceAll("0", "o")
+                    .replaceAll("3", "e")
+                    .replaceAll("4", "a");
+            }
+        })
+    ]
+})
+```

packages/better-auth/src/plugins/username/index.ts

@@ -6,12 +6,12 @@ import type { Account, InferOptionSchema, User } from "../../types";
 import { setSessionCookie } from "../../cookies";
 import { sendVerificationEmailFn } from "../../api";
 import { BASE_ERROR_CODES } from "../../error/codes";
-import { schema } from "./schema";
+import { getSchema, type UsernameSchema } from "./schema";
 import { mergeSchema } from "../../db/schema";
 import { USERNAME_ERROR_CODES as ERROR_CODES } from "./error-codes";
 export * from "./error-codes";
 export type UsernameOptions = {
-	schema?: InferOptionSchema<typeof schema>;
+	schema?: InferOptionSchema<UsernameSchema>;
 	/**
 	 * The minimum length of the username
 	 *
@@ -30,13 +30,29 @@ export type UsernameOptions = {
 	 * By default, the username should only contain alphanumeric characters and underscores
 	 */
 	usernameValidator?: (username: string) => boolean | Promise<boolean>;
+	/**
+	 * A function to normalize the username
+	 *
+	 * @default (username) => username.toLowerCase()
+	 */
+	usernameNormalization?: ((username: string) => string) | false;
 };
 
 function defaultUsernameValidator(username: string) {
 	return /^[a-zA-Z0-9_.]+$/.test(username);
 }
 
 export const username = (options?: UsernameOptions) => {
+	const normalizer = (username: string) => {
+		if (options?.usernameNormalization === false) {
+			return username;
+		}
+		if (options?.usernameNormalization) {
+			return options.usernameNormalization(username);
+		}
+		return username.toLowerCase();
+	};
+
 	return {
 		id: "username",
 		endpoints: {
@@ -139,7 +155,7 @@ export const username = (options?: UsernameOptions) => {
 						where: [
 							{
 								field: "username",
-								value: ctx.body.username.toLowerCase(),
+								value: normalizer(ctx.body.username),
 							},
 						],
 					});
@@ -272,7 +288,7 @@ export const username = (options?: UsernameOptions) => {
 				},
 			),
 		},
-		schema: mergeSchema(schema, options?.schema),
+		schema: mergeSchema(getSchema(normalizer), options?.schema),
 		hooks: {
 			before: [
 				{
@@ -313,7 +329,7 @@ export const username = (options?: UsernameOptions) => {
 								where: [
 									{
 										field: "username",
-										value: username.toLowerCase(),
+										value: normalizer(username),
 									},
 								],
 							});
@@ -340,8 +356,9 @@ export const username = (options?: UsernameOptions) => {
 						);
 					},
 					handler: createAuthMiddleware(async (ctx) => {
-						if (!ctx.body.displayUsername && ctx.body.username) {
-							ctx.body.displayUsername = ctx.body.username;
+						if (ctx.body.username) {
+							ctx.body.displayUsername ||= ctx.body.username;
+							ctx.body.username = normalizer(ctx.body.username);
 						}
 					}),
 				},

packages/better-auth/src/plugins/username/schema.ts

@@ -1,24 +1,28 @@
 import type { AuthPluginSchema } from "../../types";
 
-export const schema = {
-	user: {
-		fields: {
-			username: {
-				type: "string",
-				required: false,
-				sortable: true,
-				unique: true,
-				returned: true,
-				transform: {
-					input(value) {
-						return value?.toString().toLowerCase();
+export const getSchema = (normalizer: (username: string) => string) => {
+	return {
+		user: {
+			fields: {
+				username: {
+					type: "string",
+					required: false,
+					sortable: true,
+					unique: true,
+					returned: true,
+				},
+				displayUsername: {
+					type: "string",
+					required: false,
+					transform: {
+						input(value) {
+							return value == null ? value : normalizer(value as string);
+						},
 					},
 				},
 			},
-			displayUsername: {
-				type: "string",
-				required: false,
-			},
 		},
-	},
-} satisfies AuthPluginSchema;
+	} satisfies AuthPluginSchema;
+};
+
+export type UsernameSchema = ReturnType<typeof getSchema>;

packages/better-auth/src/plugins/username/username.test.ts

@@ -165,3 +165,42 @@ describe("username", async (it) => {
 		expect(res.data?.available).toEqual(true);
 	});
 });
+
+describe("username custom normalization", async (it) => {
+	const { client } = await getTestInstance(
+		{
+			plugins: [
+				username({
+					minUsernameLength: 4,
+					usernameNormalization: (username) =>
+						username.replaceAll("0", "o").replaceAll("4", "a").toLowerCase(),
+				}),
+			],
+		},
+		{
+			clientOptions: {
+				plugins: [usernameClient()],
+			},
+		},
+	);
+
+	it("should sign up with username", async () => {
+		const res = await client.signUp.email({
+			email: "new-email@gamil.com",
+			username: "H4XX0R",
+			password: "new-password",
+			name: "new-name",
+		});
+		expect(res.error).toBeNull();
+	});
+
+	it("should fail on duplicate username", async () => {
+		const res = await client.signUp.email({
+			email: "new-email-2@gamil.com",
+			username: "haxxor",
+			password: "new-password",
+			name: "new-name",
+		});
+		expect(res.error?.status).toBe(422);
+	});
+});