jelban.js

jelBAN.js

A library for filtering fake, disposable and duplicated email addresses.

TLDR; See Usage And Wiki.

Features

• Filters and checks for disposable email addresses from temporary email services (like 10minutemail and Mohmal), see the full list of domains at lib/validators/temporary-email-domains.
• Filters and checks for aliases that lead to the same email box from providers like Gmail.
• Filters for emails within an allowed domain list, or that are not in an excluded domain list.

Supported Providers

Gmail

Jelban's Gmail provider normalizes Gmail addresses to lowercase, non dotted and non aliased @gmail.com email addresses, since:

1. Gmail addresses are not case sensitive, [e-mail] is equivalent to [e-mail].

2. Gmail offers an aliases feature where you can create multiple aliases for your address, example:

   For example, messages sent to the following aliases will all go to [e-mail]:

   [e-mail] [e-mail] [e-mail]

3. Also, @gmail.com addresses, can be reached by using @googlemail.com, source http://techcrunch.com/2010/05/03/gmail-uk/. So [e-mail] is exactly equivalent to [e-mail].

4. Dots don't matter in Gmail addressees (source), so [e-mail], and [e-mail], and [e-mail] and [e-mail] are all similar.

Outlook/Hotmail

Similarly to the previous provider, Jelban's Outlook provider normalizers Outlook (aka. Hotmail) email addresses as it has also the option to create aliases (src), example:

Emails to [e-mail] and [e-mail] will land at [e-mail]'s mailbox

Security and privacy concerns

Issue #1

If you rely on the email normalization feature of this library you might be making account enumeration and brute force attacks easier. As attackers will have to guess for only a small subset of strings that does not have dots, upper/lowercase characters or aliases.

Also, users may choose to use the aliases when registering to your applications, and that a choice that must be respected as they may route that kind of emails to certain folders in their mailboxes.

Possible solution

Store email addresses in both formats, the user input and your normalized format, and when checking if an address is used you can rely on the normalized one, this may cause another issue if a user wants to change from their address [e-mail] to [e-mail] in their profile settings, then you know best what to do :)

Usage

npm i jelban.js

import { Jelban } from 'jelban.js';


// Instantiate the library
const jelban = new Jelban();

console.log(jelban.isValid('[e-mail]')); // prints "true"

console.log(jelban.isValid('[e-mail]')); // throws: "Invalid email address "[e-mail]", rules: ["IsExcludedDomainValidator"]" because "@boxmail.live" is a temporary domain from mohamal.com service

// If you don't want to throw on failed validations and return "false" instead:
console.log(jelban.isValid('[e-mail]', false)); // prints "false"

Parameters

Param	Description	Required	Default
noGmailAliases	When set to true, this will exclude Gmail aliases as described in providers/gmail	false	true
noOutlookAliases	When set to true, this will exclude Outlook aliases as described in providers/Outlook	false	true
noDisposableEmailAddresses	When set to true, this will exclude temporary email addresses from services like mohmal.com	false	true
excludeDomains	A list of email address domains that you may want to exclude	false	[]
allowDomains	A list of restricted domains you want to include, default is [] which will skip this validation rule	false	[]

Development

To run the project locally

# Use recommended Node version
nvm install
nvm use

# install dependencies
npm i

# run tests
npm test

# run mutation tests
npm run mutate

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

This project is licensed under the MIT License - see the LICENSE file for details