@masheev/better-auth 0.0.0-stage → 1.7.5

package/dist/plugins/username/index.d.mts

@@ -0,0 +1,326 @@
+import { InferOptionSchema } from "../../types/plugins.mjs";
+import { UsernameSchema } from "./schema.mjs";
+import { USERNAME_ERROR_CODES } from "./error-codes.mjs";
+import * as _$_better_auth_core0 from "@better-auth/core";
+import * as _$_better_auth_core_db0 from "@better-auth/core/db";
+import * as _$_better_auth_core_utils_error_codes0 from "@better-auth/core/utils/error-codes";
+import * as _$better_call0 from "better-call";
+import * as z from "zod";
+
+//#region src/plugins/username/index.d.ts
+declare module "@better-auth/core" {
+  interface BetterAuthPluginRegistry<AuthOptions, Options> {
+    username: {
+      creator: typeof username;
+    };
+  }
+}
+type UsernameOptions = {
+  schema?: InferOptionSchema<UsernameSchema> | undefined;
+  /**
+   * The minimum length of the username
+   *
+   * @default 3
+   */
+  minUsernameLength?: number | undefined;
+  /**
+   * The maximum length of the username
+   *
+   * @default 30
+   */
+  maxUsernameLength?: number | undefined;
+  /**
+   * A function to validate the username
+   *
+   * By default, the username should only contain alphanumeric characters and underscores
+   */
+  usernameValidator?: ((username: string) => boolean | Promise<boolean>) | undefined;
+  /**
+   * A function to validate the display username
+   *
+   * By default, no validation is applied to display username
+   */
+  displayUsernameValidator?: ((displayUsername: string) => boolean | Promise<boolean>) | undefined;
+  /**
+   * A function to normalize the username
+   *
+   * @default (username) => username.toLowerCase()
+   */
+  usernameNormalization?: (((username: string) => string) | false) | undefined;
+  /**
+   * A function to normalize the display username
+   *
+   * @default false
+   */
+  displayUsernameNormalization?: (((displayUsername: string) => string) | false) | undefined;
+  /**
+   * The order of validation
+   *
+   * @default { username: "pre-normalization", displayUsername: "pre-normalization" }
+   */
+  validationOrder?: {
+    /**
+     * The order of username validation
+     *
+     * @default "pre-normalization"
+     */
+    username?: "pre-normalization" | "post-normalization";
+    /**
+     * The order of display username validation
+     *
+     * @default "pre-normalization"
+     */
+    displayUsername?: "pre-normalization" | "post-normalization";
+  } | undefined;
+  /**
+   * Whether the username should be immutable
+   * When enabled, users cannot update their username after it has been set
+   *
+   * @default false
+   */
+  immutableUsername?: boolean | undefined;
+  /**
+   * Whether to add and maintain a separate `displayUsername` field.
+   *
+   * When set to `false`, the `displayUsername` field is not added to the user
+   * schema, is never written during sign-up/update, and is excluded from the
+   * inferred user/session types. Username normalization continues to work.
+   *
+   * @default true
+   */
+  displayUsername?: boolean | undefined;
+};
+declare const usernameImpl: <IncludeDisplayUsername extends boolean>(options: UsernameOptions | undefined, includeDisplayUsername: IncludeDisplayUsername) => {
+  id: "username";
+  version: string;
+  init(ctx: _$_better_auth_core0.AuthContext): {
+    options: {
+      databaseHooks: {
+        user: {
+          create: {
+            before(user: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              email: string;
+              emailVerified: boolean;
+              name: string;
+              image?: string | null | undefined;
+            } & Record<string, unknown>, context: _$_better_auth_core0.GenericEndpointContext | null): Promise<{
+              data: {
+                displayUsername?: string | undefined;
+                username: string;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              };
+            } | {
+              data: {
+                displayUsername?: string | undefined;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              };
+            }>;
+          };
+          update: {
+            before(user: Partial<{
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              email: string;
+              emailVerified: boolean;
+              name: string;
+              image?: string | null | undefined;
+            }> & Record<string, unknown>, context: _$_better_auth_core0.GenericEndpointContext | null): Promise<{
+              data: {
+                displayUsername?: string | undefined;
+                username: string;
+                id?: string | undefined;
+                createdAt?: Date | undefined;
+                updatedAt?: Date | undefined;
+                email?: string | undefined;
+                emailVerified?: boolean | undefined;
+                name?: string | undefined;
+                image?: string | null | undefined;
+              };
+            } | {
+              data: {
+                displayUsername?: string | undefined;
+                id?: string | undefined;
+                createdAt?: Date | undefined;
+                updatedAt?: Date | undefined;
+                email?: string | undefined;
+                emailVerified?: boolean | undefined;
+                name?: string | undefined;
+                image?: string | null | undefined;
+              };
+            }>;
+          };
+        };
+      };
+    };
+  };
+  endpoints: {
+    signInUsername: _$better_call0.StrictEndpoint<"/sign-in/username", {
+      method: "POST";
+      body: z.ZodObject<{
+        username: z.ZodString;
+        password: z.ZodString;
+        rememberMe: z.ZodOptional<z.ZodBoolean>;
+        callbackURL: z.ZodOptional<z.ZodString>;
+      }, z.core.$strip>;
+      metadata: {
+        openapi: {
+          summary: string;
+          description: string;
+          responses: {
+            200: {
+              description: string;
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object";
+                    properties: {
+                      redirect: {
+                        type: string;
+                        description: string;
+                      };
+                      token: {
+                        type: string;
+                        description: string;
+                      };
+                      url: {
+                        type: string;
+                        nullable: boolean;
+                        description: string;
+                      };
+                      user: {
+                        $ref: string;
+                      };
+                    };
+                    required: string[];
+                  };
+                };
+              };
+            };
+            422: {
+              description: string;
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object";
+                    properties: {
+                      message: {
+                        type: string;
+                      };
+                    };
+                  };
+                };
+              };
+            };
+          };
+        };
+      };
+    }, {
+      redirect: boolean;
+      token: string;
+      url: string | undefined;
+      user: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+      } & {
+        username: string;
+        displayUsername: string;
+      };
+    }>;
+    isUsernameAvailable: _$better_call0.StrictEndpoint<"/is-username-available", {
+      method: "POST";
+      body: z.ZodObject<{
+        username: z.ZodString;
+      }, z.core.$strip>;
+    }, {
+      available: boolean;
+    }>;
+  };
+  schema: {
+    user: {
+      fields: IncludeDisplayUsername extends false ? Pick<{
+        username: {
+          type: "string";
+          required: false;
+          sortable: true;
+          unique: true;
+          returned: true;
+          transform: {
+            input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+          };
+        };
+        displayUsername: {
+          type: "string";
+          required: false;
+          transform: {
+            input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+          };
+        };
+      }, "username"> : {
+        username: {
+          type: "string";
+          required: false;
+          sortable: true;
+          unique: true;
+          returned: true;
+          transform: {
+            input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+          };
+        };
+        displayUsername: {
+          type: "string";
+          required: false;
+          transform: {
+            input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+          };
+        };
+      };
+    };
+  };
+  hooks: {
+    before: {
+      matcher(context: _$_better_auth_core0.HookEndpointContext): boolean;
+      handler: _$better_call0.Middleware<_$better_call0.MiddlewareOptions, (inputContext: _$better_call0.MiddlewareInputContext<_$better_call0.MiddlewareOptions>) => Promise<void>>;
+    }[];
+  };
+  options: UsernameOptions | undefined;
+  $ERROR_CODES: {
+    EMAIL_NOT_VERIFIED: _$_better_auth_core_utils_error_codes0.RawError<"EMAIL_NOT_VERIFIED">;
+    UNEXPECTED_ERROR: _$_better_auth_core_utils_error_codes0.RawError<"UNEXPECTED_ERROR">;
+    INVALID_USERNAME_OR_PASSWORD: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_USERNAME_OR_PASSWORD">;
+    USERNAME_IS_ALREADY_TAKEN: _$_better_auth_core_utils_error_codes0.RawError<"USERNAME_IS_ALREADY_TAKEN">;
+    USERNAME_TOO_SHORT: _$_better_auth_core_utils_error_codes0.RawError<"USERNAME_TOO_SHORT">;
+    USERNAME_TOO_LONG: _$_better_auth_core_utils_error_codes0.RawError<"USERNAME_TOO_LONG">;
+    INVALID_USERNAME: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_USERNAME">;
+    INVALID_DISPLAY_USERNAME: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_DISPLAY_USERNAME">;
+    USERNAME_IS_IMMUTABLE: _$_better_auth_core_utils_error_codes0.RawError<"USERNAME_IS_IMMUTABLE">;
+  };
+};
+type UsernamePlugin = ReturnType<typeof usernameImpl<true>>;
+type UsernamePluginWithoutDisplayUsername = ReturnType<typeof usernameImpl<false>>;
+declare function username(options: UsernameOptions & {
+  displayUsername: false;
+}): UsernamePluginWithoutDisplayUsername;
+declare function username(options?: UsernameOptions): UsernamePlugin;
+//#endregion
+export { USERNAME_ERROR_CODES, UsernameOptions, UsernamePlugin, UsernamePluginWithoutDisplayUsername, username };

package/dist/plugins/username/index.mjs

@@ -0,0 +1,312 @@
+import { mergeSchema, parseUserOutput } from "../../db/schema.mjs";
+import { setSessionCookie } from "../../cookies/index.mjs";
+import { getSessionFromCtx } from "../../api/routes/session.mjs";
+import { createEmailVerificationToken } from "../../api/routes/email-verification.mjs";
+import { PACKAGE_VERSION } from "../../version.mjs";
+import { USERNAME_ERROR_CODES } from "./error-codes.mjs";
+import { getSchema } from "./schema.mjs";
+import { APIError, BASE_ERROR_CODES } from "@better-auth/core/error";
+import { createAuthEndpoint, createAuthMiddleware } from "@better-auth/core/api";
+import * as z from "zod";
+//#region src/plugins/username/index.ts
+function defaultUsernameValidator(username) {
+	return /^[a-zA-Z0-9_.]+$/.test(username);
+}
+const signInUsernameBodySchema = z.object({
+	username: z.string().meta({ description: "The username of the user" }),
+	password: z.string().meta({ description: "The password of the user" }),
+	rememberMe: z.boolean().meta({ description: "Remember the user session" }).optional(),
+	callbackURL: z.string().meta({ description: "URL to redirect to after sign in (also used as the redirect target for email verification when required)" }).optional()
+});
+const isUsernameAvailableBodySchema = z.object({ username: z.string().meta({ description: "The username to check" }) });
+const usernameImpl = (options, includeDisplayUsername) => {
+	const normalizer = (username) => {
+		if (options?.usernameNormalization === false) return username;
+		if (options?.usernameNormalization) return options.usernameNormalization(username);
+		return username.toLowerCase();
+	};
+	const displayUsernameNormalizer = (displayUsername) => {
+		return options?.displayUsernameNormalization ? options.displayUsernameNormalization(displayUsername) : displayUsername;
+	};
+	const minUsernameLength = options?.minUsernameLength || 3;
+	const maxUsernameLength = options?.maxUsernameLength || 30;
+	const validator = options?.usernameValidator || defaultUsernameValidator;
+	const pathsWithHttpHookValidation = ["/sign-up/email", "/update-user"];
+	const getUsernameToValidate = (username) => options?.validationOrder?.username === "post-normalization" ? normalizer(username) : username;
+	async function validateUsernameValue(username) {
+		const usernameToValidate = getUsernameToValidate(username);
+		if (usernameToValidate.length < minUsernameLength) return USERNAME_ERROR_CODES.USERNAME_TOO_SHORT;
+		if (usernameToValidate.length > maxUsernameLength) return USERNAME_ERROR_CODES.USERNAME_TOO_LONG;
+		if (!await validator(usernameToValidate)) return USERNAME_ERROR_CODES.INVALID_USERNAME;
+		return null;
+	}
+	async function validateUsername(username, displayUsername, adapter, currentUserId) {
+		const validationError = await validateUsernameValue(username);
+		if (validationError) throw APIError.from("BAD_REQUEST", validationError);
+		const normalizedUsername = normalizer(username);
+		const existingUser = await adapter.findOne({
+			model: "user",
+			where: [{
+				field: "username",
+				value: normalizedUsername
+			}]
+		});
+		if (existingUser) {
+			if (!currentUserId || existingUser.id !== currentUserId) throw APIError.from("BAD_REQUEST", USERNAME_ERROR_CODES.USERNAME_IS_ALREADY_TAKEN);
+		}
+		if (displayUsername && options?.displayUsernameValidator) {
+			const displayUsernameToValidate = options?.validationOrder?.displayUsername === "post-normalization" ? displayUsernameNormalizer(displayUsername) : displayUsername;
+			if (!await options.displayUsernameValidator(displayUsernameToValidate)) throw APIError.from("BAD_REQUEST", USERNAME_ERROR_CODES.INVALID_DISPLAY_USERNAME);
+		}
+	}
+	return {
+		id: "username",
+		version: PACKAGE_VERSION,
+		init(ctx) {
+			return { options: { databaseHooks: { user: {
+				create: { async before(user, context) {
+					const username = "username" in user ? user.username : null;
+					const displayUsername = "displayUsername" in user ? user.displayUsername : null;
+					const currentPath = context?.path;
+					const skipValidation = currentPath && pathsWithHttpHookValidation.includes(currentPath);
+					if (username) {
+						if (!skipValidation) await validateUsername(username, displayUsername, ctx.adapter);
+						return { data: {
+							...user,
+							username: normalizer(username),
+							...includeDisplayUsername ? { displayUsername: displayUsername ? displayUsernameNormalizer(displayUsername) : username } : {}
+						} };
+					}
+					return { data: {
+						...user,
+						...includeDisplayUsername && displayUsername ? { displayUsername: displayUsernameNormalizer(displayUsername) } : {}
+					} };
+				} },
+				update: { async before(user, context) {
+					const username = "username" in user ? user.username : null;
+					const displayUsername = "displayUsername" in user ? user.displayUsername : null;
+					const currentPath = context?.path;
+					const skipValidation = currentPath && pathsWithHttpHookValidation.includes(currentPath);
+					if (username) {
+						if (!skipValidation) {
+							const currentUserId = context?.context?.session?.user?.id || ("id" in user ? user.id : null);
+							await validateUsername(username, displayUsername, ctx.adapter, currentUserId);
+						}
+						return { data: {
+							...user,
+							username: normalizer(username),
+							...includeDisplayUsername && displayUsername ? { displayUsername: displayUsernameNormalizer(displayUsername) } : {}
+						} };
+					}
+					return { data: {
+						...user,
+						...includeDisplayUsername && displayUsername ? { displayUsername: displayUsernameNormalizer(displayUsername) } : {}
+					} };
+				} }
+			} } } };
+		},
+		endpoints: {
+			signInUsername: createAuthEndpoint("/sign-in/username", {
+				method: "POST",
+				body: signInUsernameBodySchema,
+				metadata: { openapi: {
+					summary: "Sign in with username",
+					description: "Sign in with username",
+					responses: {
+						200: {
+							description: "Success",
+							content: { "application/json": { schema: {
+								type: "object",
+								properties: {
+									redirect: {
+										type: "boolean",
+										description: "Whether the client should follow the Location header. True when callbackURL was provided."
+									},
+									token: {
+										type: "string",
+										description: "Session token for the authenticated session"
+									},
+									url: {
+										type: "string",
+										nullable: true,
+										description: "The callbackURL echoed back so the client can redirect."
+									},
+									user: { $ref: "#/components/schemas/User" }
+								},
+								required: [
+									"redirect",
+									"token",
+									"user"
+								]
+							} } }
+						},
+						422: {
+							description: "Unprocessable Entity. Validation error",
+							content: { "application/json": { schema: {
+								type: "object",
+								properties: { message: { type: "string" } }
+							} } }
+						}
+					}
+				} }
+			}, async (ctx) => {
+				if (!ctx.body.username || !ctx.body.password) {
+					ctx.context.logger.warn("Username or password not found");
+					throw APIError.from("UNAUTHORIZED", USERNAME_ERROR_CODES.INVALID_USERNAME_OR_PASSWORD);
+				}
+				const username = options?.validationOrder?.username === "pre-normalization" ? normalizer(ctx.body.username) : ctx.body.username;
+				const minUsernameLength = options?.minUsernameLength || 3;
+				const maxUsernameLength = options?.maxUsernameLength || 30;
+				if (username.length < minUsernameLength) {
+					ctx.context.logger.warn("Username too short");
+					throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.USERNAME_TOO_SHORT);
+				}
+				if (username.length > maxUsernameLength) {
+					ctx.context.logger.warn("Username too long");
+					throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.USERNAME_TOO_LONG);
+				}
+				if (!await (options?.usernameValidator || defaultUsernameValidator)(username)) throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.INVALID_USERNAME);
+				const user = await ctx.context.adapter.findOne({
+					model: "user",
+					where: [{
+						field: "username",
+						value: normalizer(username)
+					}]
+				});
+				if (!user) {
+					await ctx.context.password.hash(ctx.body.password);
+					ctx.context.logger.warn("User not found");
+					throw APIError.from("UNAUTHORIZED", USERNAME_ERROR_CODES.INVALID_USERNAME_OR_PASSWORD);
+				}
+				const account = await ctx.context.internalAdapter.findCredentialAccount(user.id);
+				if (!account) throw APIError.from("UNAUTHORIZED", USERNAME_ERROR_CODES.INVALID_USERNAME_OR_PASSWORD);
+				const currentPassword = account?.password;
+				if (!currentPassword) {
+					ctx.context.logger.warn("Password not found");
+					throw APIError.from("UNAUTHORIZED", USERNAME_ERROR_CODES.INVALID_USERNAME_OR_PASSWORD);
+				}
+				if (!await ctx.context.password.verify({
+					hash: currentPassword,
+					password: ctx.body.password
+				})) {
+					ctx.context.logger.warn("Invalid password");
+					throw APIError.from("UNAUTHORIZED", USERNAME_ERROR_CODES.INVALID_USERNAME_OR_PASSWORD);
+				}
+				if (ctx.context.options?.emailAndPassword?.requireEmailVerification && !user.emailVerified) {
+					if (!ctx.context.options?.emailVerification?.sendVerificationEmail) throw APIError.from("FORBIDDEN", USERNAME_ERROR_CODES.EMAIL_NOT_VERIFIED);
+					if (ctx.context.options?.emailVerification?.sendOnSignIn) {
+						const token = await createEmailVerificationToken(ctx.context.secret, user.email, void 0, ctx.context.options.emailVerification?.expiresIn);
+						const url = `${ctx.context.baseURL}/verify-email?token=${token}&callbackURL=${encodeURIComponent(ctx.body.callbackURL || "/")}`;
+						await ctx.context.runInBackgroundOrAwait(ctx.context.options.emailVerification.sendVerificationEmail({
+							user,
+							url,
+							token
+						}, ctx.request));
+					}
+					throw APIError.from("FORBIDDEN", USERNAME_ERROR_CODES.EMAIL_NOT_VERIFIED);
+				}
+				const session = await ctx.context.internalAdapter.createSession(user.id, ctx.body.rememberMe === false);
+				if (!session) throw APIError.from("INTERNAL_SERVER_ERROR", BASE_ERROR_CODES.FAILED_TO_CREATE_SESSION);
+				await setSessionCookie(ctx, {
+					session,
+					user
+				}, ctx.body.rememberMe === false);
+				if (ctx.body.callbackURL) ctx.setHeader("Location", ctx.body.callbackURL);
+				return ctx.json({
+					redirect: !!ctx.body.callbackURL,
+					token: session.token,
+					url: ctx.body.callbackURL,
+					user: parseUserOutput(ctx.context.options, user)
+				});
+			}),
+			isUsernameAvailable: createAuthEndpoint("/is-username-available", {
+				method: "POST",
+				body: isUsernameAvailableBodySchema
+			}, async (ctx) => {
+				const username = ctx.body.username;
+				if (!username) throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.INVALID_USERNAME);
+				const minUsernameLength = options?.minUsernameLength || 3;
+				const maxUsernameLength = options?.maxUsernameLength || 30;
+				if (username.length < minUsernameLength) throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.USERNAME_TOO_SHORT);
+				if (username.length > maxUsernameLength) throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.USERNAME_TOO_LONG);
+				if (!await (options?.usernameValidator || defaultUsernameValidator)(username)) throw APIError.from("UNPROCESSABLE_ENTITY", USERNAME_ERROR_CODES.INVALID_USERNAME);
+				if (await ctx.context.adapter.findOne({
+					model: "user",
+					where: [{
+						field: "username",
+						value: normalizer(username)
+					}]
+				})) return ctx.json({ available: false });
+				return ctx.json({ available: true });
+			})
+		},
+		schema: mergeSchema(getSchema({
+			username: normalizer,
+			displayUsername: displayUsernameNormalizer
+		}, includeDisplayUsername), options?.schema),
+		hooks: { before: [
+			{
+				matcher(context) {
+					return context.path === "/sign-up/email";
+				},
+				handler: createAuthMiddleware(async (ctx) => {
+					if (typeof ctx.body.displayUsername !== "string" || ctx.body.username !== void 0) return;
+					if (!await validateUsernameValue(ctx.body.displayUsername)) ctx.body.username = ctx.body.displayUsername;
+				})
+			},
+			{
+				matcher(context) {
+					return context.path === "/sign-up/email" || context.path === "/update-user";
+				},
+				handler: createAuthMiddleware(async (ctx) => {
+					const username = ctx.body.username;
+					if (username !== void 0 && typeof username === "string") {
+						const validationError = await validateUsernameValue(username);
+						if (validationError) throw APIError.from("BAD_REQUEST", validationError);
+						const normalizedUsername = normalizer(username);
+						const session = ctx.path === "/update-user" ? await getSessionFromCtx(ctx) : null;
+						if (ctx.path === "/update-user" && options?.immutableUsername) {
+							const hasUsername = !!session?.user.username;
+							const usernamesDiffer = session?.user.username !== normalizedUsername;
+							if (hasUsername && usernamesDiffer) throw APIError.from("BAD_REQUEST", USERNAME_ERROR_CODES.USERNAME_IS_IMMUTABLE);
+						}
+						const existingUser = await ctx.context.adapter.findOne({
+							model: "user",
+							where: [{
+								field: "username",
+								value: normalizedUsername
+							}]
+						});
+						if (ctx.path === "/sign-up/email" && existingUser) throw APIError.from("BAD_REQUEST", USERNAME_ERROR_CODES.USERNAME_IS_ALREADY_TAKEN);
+						if (ctx.path === "/update-user" && existingUser) {
+							if (!session || existingUser.id !== session.user.id) throw APIError.from("BAD_REQUEST", USERNAME_ERROR_CODES.USERNAME_IS_ALREADY_TAKEN);
+						}
+					}
+					if (!includeDisplayUsername) return;
+					const displayUsername = typeof ctx.body.displayUsername === "string" && options?.validationOrder?.displayUsername === "post-normalization" ? displayUsernameNormalizer(ctx.body.displayUsername) : ctx.body.displayUsername;
+					if (displayUsername !== void 0 && typeof displayUsername === "string") {
+						if (options?.displayUsernameValidator) {
+							if (!await options.displayUsernameValidator(displayUsername)) throw APIError.from("BAD_REQUEST", USERNAME_ERROR_CODES.INVALID_DISPLAY_USERNAME);
+						}
+					}
+				})
+			},
+			{
+				matcher(context) {
+					return context.path === "/sign-up/email";
+				},
+				handler: createAuthMiddleware(async (ctx) => {
+					if (!includeDisplayUsername) return;
+					if (ctx.body.username && !ctx.body.displayUsername) ctx.body.displayUsername = ctx.body.username;
+				})
+			}
+		] },
+		options,
+		$ERROR_CODES: USERNAME_ERROR_CODES
+	};
+};
+function username(options) {
+	return usernameImpl(options, options?.displayUsername !== false);
+}
+//#endregion
+export { USERNAME_ERROR_CODES, username };

package/dist/plugins/username/schema.d.mts

@@ -0,0 +1,50 @@
+import * as _$_better_auth_core_db0 from "@better-auth/core/db";
+
+//#region src/plugins/username/schema.d.ts
+declare const getSchema: <IncludeDisplayUsername extends boolean = true>(normalizer: {
+  username: (username: string) => string;
+  displayUsername: (displayUsername: string) => string;
+}, includeDisplayUsername?: IncludeDisplayUsername) => {
+  user: {
+    fields: IncludeDisplayUsername extends false ? Pick<{
+      username: {
+        type: "string";
+        required: false;
+        sortable: true;
+        unique: true;
+        returned: true;
+        transform: {
+          input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+        };
+      };
+      displayUsername: {
+        type: "string";
+        required: false;
+        transform: {
+          input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+        };
+      };
+    }, "username"> : {
+      username: {
+        type: "string";
+        required: false;
+        sortable: true;
+        unique: true;
+        returned: true;
+        transform: {
+          input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+        };
+      };
+      displayUsername: {
+        type: "string";
+        required: false;
+        transform: {
+          input(value: _$_better_auth_core_db0.DBPrimitive): string | number | boolean | Date | unknown[] | Record<string, unknown> | null | undefined;
+        };
+      };
+    };
+  };
+};
+type UsernameSchema = ReturnType<typeof getSchema<true>>;
+//#endregion
+export { UsernameSchema };