Registry / auth-security / better-auth-harmony

better-auth-harmony

library1.3.2jsnpmunverified

Better Auth Harmony is a plugin for the `better-auth` framework, designed to enhance user input handling by providing robust validation and normalization functionalities. It specifically targets email addresses, detecting and blocking disposable domains, as well as standardizing phone numbers. The library aims to improve data quality and security within applications leveraging `better-auth` for user authentication. The current stable version is `1.3.2`, with a release cadence that includes regular patch and minor updates to address bugs and introduce new features. Its primary differentiator lies in its deep integration with the `better-auth` ecosystem, offering specialized validation and normalization that aligns with `better-auth`'s architecture, thereby providing a comprehensive solution for managing user identity data.

auth-security web-framework llm-agents

npm install better-auth-harmony

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-HARMON

better-auth-harmony

auth-securityjavascriptv1.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

emailHarmony

✓ import { emailHarmony } from 'better-auth-harmony';

✗ const { emailHarmony } = require('better-auth-harmony');

`better-auth-harmony` is primarily designed for ESM environments. While CJS might work in some setups, named ESM imports are the recommended and most compatible approach.

phoneHarmony

✓ import { phoneHarmony } from 'better-auth-harmony';

✗ import phoneHarmony from 'better-auth-harmony/phoneHarmony';

Both `emailHarmony` and `phoneHarmony` are named exports from the main package entry point.

betterAuth

✓ import { betterAuth } from 'better-auth';

While `betterAuth` is not from `better-auth-harmony`, it's crucial for integrating the harmony plugins. It's often imported alongside `emailHarmony` or `phoneHarmony` into your `auth` configuration file.

This code demonstrates how to integrate `emailHarmony` and `phoneHarmony` plugins into a `better-auth` instance. It showcases the plugin-based configuration and highlights automatic normalization and validation features.

import { betterAuth } from 'better-auth'; import { emailHarmony, phoneHarmony } from 'better-auth-harmony'; import { phoneNumber } from 'better-auth/plugins'; // Assuming this is needed for phone number handling in better-auth // Configure your Better Auth instance with the Harmony plugins export const auth = betterAuth({ // ... other better-auth configuration options emailAndPassword: { enabled: true, }, plugins: [ emailHarmony({ allowNormalizedSignin: true, // Example option: Allow users to sign in with normalized or unnormalized emails }), phoneNumber(), // better-auth's core phone number plugin phoneHarmony({ matchers: { // Example matcher, customize as needed create: true, update: true, delete: false, }, }), ], // Define a database adapter (e.g., Prisma, Drizzle) // database: prismaAdapter(prisma, { provider: 'postgresql' }), }); console.log('Better Auth instance configured with Harmony plugins.'); console.log('Harmony automatically normalizes and validates emails/phone numbers.'); console.log('For example, "foo+temp@gmail.com" becomes "foo@gmail.com" and checks for disposable domains.');

Debug

Known issues

breakingVersion 1.3.0 introduced changes to 'Match new API paths' and 'Fix compatibility with better-auth 1.5.0'. This may require updates to how `better-auth-harmony` interacts with the core `better-auth` library if you are upgrading either package across major or significant minor versions.

fix

Review the `better-auth` changelog for API changes in version 1.5.0 and ensure your `better-auth-harmony` configuration and usage align with the updated `better-auth` API. Consult the `better-auth-harmony` documentation for any specific migration steps related to API paths.

affects: >=1.3.0

gotchaPrior to version 1.3.2, a bug caused 'normalized email login failure', meaning users might have been unable to log in if their email was normalized differently than what was stored or expected.

fix

Upgrade to `better-auth-harmony@1.3.2` or later to resolve the normalized email login issue.

affects: <1.3.2

gotchaVersions prior to 1.3.1 had compatibility issues with `validator.js` in unbundled ESM environments, potentially leading to module resolution errors.

fix

Upgrade to `better-auth-harmony@1.3.1` or later. If issues persist in complex ESM setups, consider workarounds mentioned in the `better-auth-harmony` documentation such as using Node.js 22+, `NODE_OPTIONS=--experimental-detect-module` for Node >= 20.10, or patching `validator.js` to include `"type": "module"` in its `package.json`.

affects: <1.3.1

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'validator' from '.../node_modules/better-auth-harmony/dist/esm/index.js'

`better-auth-harmony` relies on `validator.js`, which historically had inconsistent ESM support, leading to module resolution failures in certain environments.

fix

Upgrade to `better-auth-harmony@1.3.1` or newer. If using Next.js, add `better-auth-harmony` to `transpilePackages` in `next.config.js`. For Vite, add it to `ssr.noExternal` in `vite.config.js`. Alternatively, ensure Node.js 22+ is used, or pass `NODE_OPTIONS=--experimental-detect-module` for Node >= 20.10.

TypeError: Cannot read properties of undefined (reading 'emailHarmony')

Attempting to `require` or use incorrect named import syntax for `emailHarmony` or `phoneHarmony` in a CommonJS module, or when the bundler/runtime expects ESM.

fix

Ensure you are using `import { emailHarmony } from 'better-auth-harmony';` for ESM environments. Verify your `package.json` `type` field and module resolution settings if using a mixed environment.

A user's email might have been normalized by `better-auth-harmony` (e.g., removing `+` aliases or changing domain casing), but the login attempt used the original unnormalized email, and `allowNormalizedSignin` option was not enabled.

fix

To allow users to sign in with either their normalized or unnormalized email, configure `emailHarmony` with `allowNormalizedSignin: true`. This will perform an additional database lookup for the normalized version of the email.

Upgrade

Version history

1.3.2latest on npm

Audit

Dependencies

better-authrequiredThis package is a plugin for `better-auth` and requires it as a peer dependency for core authentication functionalities.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/GeKorm/better-auth-harmony ↗

packagehttps://www.npmjs.com/package/better-auth-harmony ↗