Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fcmam5/jelban-js
Another email addresses filter; filters out disposable and addresses' alias
https://github.com/fcmam5/jelban-js
antispam email gmail security
Last synced: 13 days ago
JSON representation
Another email addresses filter; filters out disposable and addresses' alias
- Host: GitHub
- URL: https://github.com/fcmam5/jelban-js
- Owner: Fcmam5
- License: mit
- Created: 2022-08-21T13:23:43.000Z (about 2 years ago)
- Default Branch: develop
- Last Pushed: 2024-06-21T05:28:36.000Z (5 months ago)
- Last Synced: 2024-10-10T12:02:58.885Z (about 1 month ago)
- Topics: antispam, email, gmail, security
- Language: TypeScript
- Homepage: https://github.com/Fcmam5/jelban-js/wiki
- Size: 915 KB
- Stars: 60
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# jelBAN.js
[](https://dashboard.stryker-mutator.io/reports/github.com/Fcmam5/jelban-js/develop)  [](https://codecov.io/gh/Fcmam5/jelban-js) [](https://www.npmjs.com/package/jelban.js)
A library for filtering fake, disposable and duplicated email addresses.
TLDR; See [Usage](#usage) And [Wiki](https://github.com/Fcmam5/jelban-js/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`](./src//lib/validators/temporary-email-domains.ts).
- Filters and checks for aliases that lead to the same email box from providers like [Gmail](#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:
0. Gmail addresses are not case sensitive, `[email protected]` is equivalent to `[email protected]`.
1. Gmail offers an [aliases feature](https://support.google.com/mail/answer/22370?hl=en#zippy=%2Cfilter-using-your-gmail-alias) where you can create multiple aliases for your address, example:
> For example, messages sent to the following aliases will all go to [email protected]:
>
> janedoe+school@gmail.com
> janedoe+notes@gmail.com
> janedoe+important.emails@gmail.com
2. Also, `@gmail.com` addresses, can be reached by using `@googlemail.com`, source [http://techcrunch.com/2010/05/03/gmail-uk/](http://techcrunch.com/2010/05/03/gmail-uk/). So `[email protected]` is exactly equivalent to `[email protected]`.
3. Dots don't matter in Gmail addressees ([source](https://support.google.com/mail/answer/7436150?hl=en)), so `[email protected]`, and `[email protected]`, and `[email protected]` and `[email protected]` 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](https://www.cnet.com/tech/tech-industry/hotmail-launches-accounts-you-can-throw-away/)), example:
> Emails to _jane.doe+school@hotmail.fr_ and _jane.doe+work@hotmail.fr_ will land at `[email protected]`'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 `[email protected]` to `[email protected]` in their profile settings, then you know best what to do :)
## Usage
```
npm i jelban.js
```
```typescript
import { Jelban } from 'jelban.js';
// Instantiate the library
const jelban = new Jelban();
console.log(jelban.isValid('[email protected]')); // prints "true"
console.log(jelban.isValid('[email protected]')); // throws: "Invalid email address "[email protected]", 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('[email protected]', false)); // prints "false"
```
### Parameters
| Param | Description | Required | Default |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------- |
| `noGmailAliases` | When set to `true`, this will exclude Gmail aliases as described in [providers/gmail](#gmail) | `false` | `true` |
| `noOutlookAliases` | When set to `true`, this will exclude Outlook aliases as described in [providers/Outlook](#outlookhotmail) | `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
```bash
# 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](./LICENSE) file for details