Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gekorm/better-auth-harmony
Normalize emails/phone numbers and block throwaway domains with Better Auth
https://github.com/gekorm/better-auth-harmony
authentication better-auth disposable-email email email-validation phone-number
Last synced: 25 days ago
JSON representation
Normalize emails/phone numbers and block throwaway domains with Better Auth
- Host: GitHub
- URL: https://github.com/gekorm/better-auth-harmony
- Owner: GeKorm
- License: mit
- Created: 2024-11-25T17:40:56.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-12-02T12:02:35.000Z (about 1 month ago)
- Last Synced: 2024-12-04T09:09:24.082Z (30 days ago)
- Topics: authentication, better-auth, disposable-email, email, email-validation, phone-number
- Language: TypeScript
- Homepage: https://npmjs.com/package/better-auth-harmony
- Size: 1.49 MB
- Stars: 27
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Better Auth Harmony
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:** `[email protected]` -> `[email protected]`
**Phone normalization:** `+1 (555) 123-1234` -> `+15551231234`
**Validation:** `[email protected]` -> Blocked
- [Email](#email)
- [Getting Started](#getting-started)
- [Options](#options)
- [Schema](#schema)
- [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.
## 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
`[email protected]` may also log in with `[email protected]`. 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).
## 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.