temp-check

A lightweight toolkit for detecting disposable emails, abused usernames, and unsafe credential inputs. Zero required dependencies for core checks.

Why

Signup forms get abused in predictable ways: throwaway emails, impersonation usernames, and oversized passwords sent to hash functions as a DoS vector. temp-check bundles these checks into one small, dependency-free package so you don't have to maintain your own blocklists.

Features

• Disposable email detection — static blocklist first, optional DNS/MX fallback for domains not yet in the list.
• Role-based & catch-all email flags — admin@, support@, noreply@, and domains that accept any inbox.
• Username abuse detection — profanity filtering, impersonation patterns, leetspeak and homoglyph normalization.
• Password/credential guards — hard-reject on oversized input (DoS protection), min-length and pattern checks.
• Structured results — every check returns { flagged, reason, source }, not just a boolean, so you can log why something was blocked.
• Catch-all probing — active SMTP connection to detect catch-all domains (opt-in).
• TypeScript Support — ships with a temp-check.d.ts declaration file for out-of-the-box IDE autocompletion and type safety.
• Customizable Lists — easily extend the default dictionaries with extraBlockedWords and extraReservedWords.
• Zero required dependencies — DNS lookups and breach-check APIs are opt-in, not baked into the core path.
• Graceful invalid-input handling — non-string or malformed input never throws unexpectedly from the boolean-style helpers.

Installation

npm install temp-check

Usage

For full runnable code samples, check out the examples/ directory in this repository.

Email

const { isTempMail } = require('temp-check');

isTempMail('[email protected]');    // true
isTempMail('[email protected]');   // false
isTempMail(12345);              // false — invalid input handled gracefully

With DNS fallback for domains not in the static list:

const { isDisposableEmail } = require('temp-check');

const result = await isDisposableEmail('[email protected]', {
  dnsFallback: true,
  timeoutMs: 1500,
});
// { flagged: true, reason: 'disposable', source: 'dns' }

Username

const { isAbusedUsername } = require('temp-check');

isAbusedUsername('admin');
// { flagged: true, reason: 'impersonation', source: 'reserved-words' }

// You can extend the built-in dictionary:
isAbusedUsername('mycompany', { extraReservedWords: ['mycompany'] });
// { flagged: true, reason: 'impersonation', source: 'reserved-words' }

isAbusedUsername('regular_user_42');
// { flagged: false }

Password

const { validatePassword } = require('temp-check');

const isValid = validatePassword(oversizedInput, { maxLength: 128 });
if (!isValid) {
  // Reject before it ever reaches bcrypt/argon2
}

API Reference

| Function | Returns | Description | |---|---|---| | isTempMail(email) | boolean | Quick static-list check. Invalid input returns false. | | isDisposableEmail(email, options?) | Promise<object> | Static list + optional DNS/MX fallback. | | isAbusedUsername(username, options?) | object | Profanity, impersonation, and pattern checks. | | validatePassword(password, options?) | boolean | Promise<boolean> | Length and pattern guard. Max length blocks oversized input (DoS). |

isDisposableEmail options

| Option | Default | Description | |---|---|---| | dnsFallback | true | Fall back to MX lookup if domain isn't in the static list. | | checkCatchAll | false | Actively probe the MX server to check if it's a catch-all domain. (Use with caution, can get your IP flagged). | | timeoutMs | 1500 | DNS lookup/SMTP probe timeout. Fails open (not disposable) on timeout. |

validatePassword options

| Option | Default | Description | |---|---|---| | maxLength | 128 | Hard reject above this length (DoS guard). | | minLength | 8 | Minimum required length. |

Migration Guide (v0.1.x to v0.2.0)

If you are upgrading from v0.1.x to v0.2.0:

• isTempMail: Remains fully backwards compatible. No changes are required to your code.
• New Modules: If you want to use the new username or password features, simply import them via the top-level barrel export:

  const { isAbusedUsername, validatePassword } = require('temp-check');

• Enhanced Email Validation: We recommend migrating from isTempMail(email) to isDisposableEmail(email, options). Note that isDisposableEmail is async if dnsFallback or checkCatchAll are enabled, and returns an object { flagged, reason, source } instead of a boolean.

Design notes

• DNS failures fail open. A flaky resolver should never block a legitimate signup — network errors return disposable: false.
• Password length is hard-capped by default. Extremely long input (100,000+ characters) is a known denial-of-service vector against bcrypt/argon2, so it's rejected before hashing rather than accepted.
• No global state. Every function takes a config object, making it safe to use in serverless/edge environments.

Contributing

Issues and PRs welcome. If you're adding to the disposable-domain or blocklist data files, please include a source for the addition.

License

MIT