A [better-auth](https://github.com/better-auth/better-auth) plugin for email & phone normalization
and additional validation, blocking over 55,000 temporary email domains.
**Email normalization:** `foo+temp@gmail.com` -> `foo@gmail.com`
**Phone normalization:** `+1 (555) 123-1234` -> `+15551231234`
**Validation:** `throwaway@mailinator.com` -> Blocked
- [Email](#email)
- [Getting Started](#getting-started)
- [Options](#options)
- [Schema](#schema)
- [Troubleshooting ESM](#troubleshooting-esm)
- [Phone number](#phone-number)
- [Getting Started](#getting-started-1)
- [Options](#options-1)
# Email
## Getting Started
### 1. Install the plugin
```shell
npm i better-auth-harmony
```
### 2. Add the plugin to your auth config
```typescript
// auth.ts
import { betterAuth } from 'better-auth';
import { emailHarmony } from 'better-auth-harmony';
export const auth = betterAuth({
// ... other config options
plugins: [emailHarmony()]
});
```
### 3. Migrate the database
```shell
npx @better-auth/cli migrate
```
or
```shell
npx @better-auth/cli generate
```
See the [Schema](#schema) section to add the fields manually.
## Troubleshooting ESM
The [validator.js](https://github.com/validatorjs/validator.js) package lacks proper ESM support.
Please open an issue in this repo if the following workarounds don't help.
Error Error [ERR_MODULE_NOT_FOUND]: Cannot find module
### Next.js
Add `better-auth-harmony` to `transpilePackages` in
[next.config](https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages)
### Vite
Add `better-auth-harmony` to `ssr.noExternal` in
[vite.config](https://vite.dev/config/ssr-options#ssr-noexternal)
Error Cannot use import statement outside a module
### Workarounds
- Use NodeJs 22 or higher
- Or use `NODE_OPTIONS=--experimental-detect-module` for Node >= 20.10
Either as an environment variable, or via:
```shell
npx --node-options=--experimental-detect-module @better-auth/cli generate
```
or as a local script in package.json:
```json
{
"scripts": {
"auth-generate": "NODE_OPTIONS=--experimental-detect-module cli generate"
}
}
```
If none of the above works, consider [yarn patch](https://yarnpkg.com/cli/patch) or
[npm patch-package](https://www.npmjs.com/package/patch-package) to add `"type": "module"` to
_validator_'s package.json.
## Options
- `allowNormalizedSignin` (default=**false**) - Allow logging in with any version of the
unnormalized email address. For example, a user who signed up with the email
`johndoe@googlemail.com` may also log in with `john.doe@gmail.com`. Makes 1 extra database query
for every login attempt.
- `validator` - Custom function to validate email. By default uses
[validator.js](https://github.com/validatorjs/validator.js#validators) and
[Mailchecker](https://github.com/FGRibreau/mailchecker).
- `normalizer` - Custom function to normalize the email address. By default uses
[`validator.js/normalizeEmail()`](https://github.com/validatorjs/validator.js#sanitizers).
- `matchers` - Customize when to run input `email` validation and normalization. Normalization
always runs on user creation and update regardless of this setting.
## Schema
The `emailHarmony` plugin requires an additional field in the user table:
| Field Name | Type | Optional | Unique | Description |
| --------------- | ------ | -------- | ------ | ---------------------------------------- |
| normalizedEmail | string | True | True | User's email address after normalization |
The `normalizedEmail` field being unique prevents users from signing up with throwaway variations of
the same email address.
---
# Phone number
> [!NOTE]
> Unlike `emailHarmony`, phone number normalization intercepts and modifies the user's
`phoneNumber`, permitting only normalized numbers in the backend.
## Getting Started
### 1. Install the plugin
```shell
npm i better-auth-harmony
```
#### 2. Add the plugin to your auth config
```typescript
// auth.ts
import { betterAuth } from 'better-auth';
import { phoneNumber } from 'better-auth/plugins';
import { phoneHarmony } from 'better-auth-harmony';
export const auth = betterAuth({
// ... other config options
plugins: [phoneNumber(), phoneHarmony()]
});
```
See the better-auth
[`phoneNumber` plugin documentation](https://www.better-auth.com/docs/plugins/phone-number) for
information on configuring the `phoneNumber()`, including **validation**.
## Options
- `defaultCountry` - Default [country](https://www.npmjs.com/package/libphonenumber-js#country-code)
for numbers written in non-international form (without a `+` sign).
- `defaultCallingCode` - Default calling code for numbers written in non-international form (without
a `+` sign). Useful for parsing non-geographic codes such as
[`+800` numbers](https://en.wikipedia.org/wiki/Toll-free_telephone_number).
- `extract` (default=**true**) - Defines the
["strictness"](https://www.npmjs.com/package/libphonenumber-js#strictness) of parsing a phone
number. By default, it will attempt to extract the phone number from any input string, such as
`"My phone number is (213) 373-4253"`.
- `acceptRawInputOnError` (default=**false**) - If the normalizer throws, for example because it is
unable to parse the phone number, use the original input. For example, the phone number `"+12"`
will be saved as-is to the database.
- `normalizer` - Custom function to normalize phone number. Default uses
[`parsePhoneNumberWithError`](https://www.npmjs.com/package/libphonenumber-js#user-content-parse-phone-number)
from `libphonenumber-js/max`. Can be used to infer the country through the Request object, for
example using IP address geolocation.
- `matchers` - Customize when to run input `phoneNumber` validation.
