You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP

better-auth-harmony

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install
b

better-auth-harmony

Validation and normalization for better-auth

1.2.5
latest
100

Supply Chain Security

100

Vulnerability

100

Quality

76

Maintenance

100

License

Version published
Weekly downloads
3K
4.19%
Maintainers
1
Weekly downloads
 
Created
Issues
2
Better Auth Logo

Better Auth Harmony

100% coverage with Vitest NPM Version NPM License

A 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

Getting Started

1. Install the plugin

npm i better-auth-harmony

2. Add the plugin to your auth config

// 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

npx @better-auth/cli migrate

or

npx @better-auth/cli generate

See the Schema section to add the fields manually.

Troubleshooting ESM

The 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

Vite

Add better-auth-harmony to ssr.noExternal in vite.config

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:

npx --node-options=--experimental-detect-module @better-auth/cli generate

or as a local script in package.json:

{
  "scripts": {
    "auth-generate": "NODE_OPTIONS=--experimental-detect-module cli generate"
  }
}

If none of the above works, consider yarn patch or npm 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 and Mailchecker.
  • normalizer - Custom function to normalize the email address. By default uses validator.js/normalizeEmail().
  • 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 NameTypeOptionalUniqueDescription
normalizedEmailstringTrueTrueUser'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

npm i better-auth-harmony

2. Add the plugin to your auth config

// 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 for information on configuring the phoneNumber(), including validation.

Options

  • defaultCountry - Default country 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.
  • extract (default=true) - Defines the "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 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.

FAQs

Package last updated on 29 May 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts