moonetix / signup-guard
Explainable sign-up risk checks: email normalization, disposable domains, datacenter and Tor IPs, velocity limits.
Package info
github.com/moonetix/signup-guard
Language:JavaScript
pkg:composer/moonetix/signup-guard
Requires
- php: >=8.1
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Explainable sign-up risk checks for any product: normalized emails, disposable domains, datacenter and Tor addresses, velocity limits, and a score where every point has a written reason.
Maintained by Moonetix.
Open the live demo: type an email and an IP address and get allow, review or block with every reason, its points and its hint. The library runs in your browser on the bundled data, and nothing is sent anywhere.
Fake accounts are cheap to make, and the cheap ones look alike: a throwaway inbox, a rented server, ten attempts in a minute. signup-guard checks for exactly those traits with public data you can read yourself, and returns a decision together with the reasons behind it. A support agent can read the reasons, a user can be told what to fix, and nothing is decided by a model you cannot inspect.
- JavaScript: ESM, Node 20+, zero dependencies, TypeScript declarations.
- PHP: 8.1+, zero dependencies, standard extensions only.
- One spec: both suites run the same test vectors, so the two ports give the same answer to the same input.
- Data you can audit: the disposable-email-domains list (CC0) and moonetix/datacenter-ip-ranges, vendored in
data/and refreshed every week.
The checks
flowchart TD
A["Sign-up attempt<br/>email, IP, your own fields"] --> V["VelocityLimiter.check()<br/>one counter per rule: IP, /24 or /64, email"]
A --> S["assessSignup({ email, ip, velocity })"]
V -->|velocity result| S
S --> E["Email<br/>syntax, provider rules, disposable list,<br/>typos, role and free mail"]
S --> I["IP<br/>special-use, cloud, services,<br/>CDN, Tor, privacy relay"]
S --> VR["Velocity<br/>rules over their limit"]
E --> R["reasons: code, points, message, hint<br/>score = sum of points"]
I --> R
VR --> R
R -->|below 30| OK[allow]
R -->|30 to 69| RV["review<br/>challenge, verify, hold"]
R -->|70 and up| B["block<br/>show the hints"]
Loading
| Function | What it does |
|---|---|
assessSignup(input, options) |
Runs every check and returns score, decision, reasons and the raw results |
normalizeEmail(email, options) |
Validates an address and returns the form to check duplicates against |
suggestEmail(email, options) |
The corrected address when the domain looks like a typo of a common mailbox (gmial.com, hotmail.con), else null |
isRoleAddress(email) |
Whether the address is a shared mailbox such as admin@, info@ or no-reply@ |
isFreeMail(emailOrDomain, options) |
Whether the domain belongs to a free consumer mailbox service |
checkDisposable(emailOrDomain, options) |
Disposable list lookup on the domain and every parent domain, with allow and block lists |
lookupIp(ip, options) |
Public or special-use, plus every listed range that contains the address |
normalizeIp(ip), ipNetwork(ip) |
Canonical address text, and the /24 or /64 it belongs to |
new VelocityLimiter({ store, rules }) |
Fixed-window attempt counters per IP, network, normalized email or your own field |
MemoryStore |
In-process counters for tests and single-process apps |
createData, loadData, dataInfo |
Use your own lists, load a snapshot folder, read snapshot dates and counts |
PROVIDERS, FREE_MAIL_PROVIDERS, MAILBOX_DOMAINS, ROLE_LOCAL_PARTS, DEFAULT_WEIGHTS, DEFAULT_THRESHOLDS, DEFAULT_VELOCITY_RULES |
The defaults, as data |
parseIp, formatIp, parseCidr, specialRange, SPECIAL_RANGES, IP_CATEGORIES, EMAIL_PROBLEMS |
Lower-level IP parsing, the special-use table, and the problem codes normalizeEmail can return (empty, non-ascii, missing-at, multiple-at, too-long, local-too-long, local-invalid, domain-literal, domain-invalid) |
SignupGuardError |
Thrown for bad arguments, options, rules or data. code is one of invalid_argument, invalid_option, invalid_rule, data_error |
In PHP the same functions are static methods of Moonetix\SignupGuard\SignupGuard, and the limiter is Moonetix\SignupGuard\VelocityLimiter. Options use the same names in both languages. PHP throws SignupGuardException (an InvalidArgumentException) with the same codes in $e->errorCode, and adds exportData, loadExported and cachedData for PHP-FPM. The defaults are SignupGuard::DEFAULT_WEIGHTS, SignupGuard::DEFAULT_THRESHOLDS and VelocityLimiter::DEFAULT_RULES; the lower-level helpers live in Ip (parse, format, parseCidr, special, SPECIAL) and Email (PROVIDERS, PROBLEMS, FREE_MAIL_PROVIDERS, MAILBOX_DOMAINS, ROLE_LOCAL_PARTS).
Install
The JavaScript package is on npm and the PHP package is on Packagist:
npm install @moonetix/signup-guard composer require moonetix/signup-guard
Both packages bundle the data as of their release. The data/ folder on GitHub is refreshed every week; to follow it between releases, point loadData(dir) at a current copy of that folder or install from Git.
Without Composer, require 'php/autoload.php'; from a copy of the repository.
Quick start
JavaScript (examples/quickstart.mjs)
import { assessSignup, VelocityLimiter } from '@moonetix/signup-guard'; const limiter = new VelocityLimiter(); // in-memory: fine for one process, see "Velocity stores" otherwise async function screenSignup({ email, ip }) { const now = Math.floor(Date.now() / 1000); const velocity = await limiter.check({ now, ip, email }); // count the attempt before you judge it return assessSignup({ email, ip, velocity }); } const result = await screenSignup({ email: 'Jane.Doe+promo@googlemail.com', ip: '3.5.140.2' }); console.log(result.decision, result.score); for (const r of result.reasons) console.log(`${r.code} +${r.points}: ${r.message}`); console.log(result.email.normalized);
review 40
email_normalized +0: Normalized to janedoe@gmail.com (lowercased, domain alias replaced, plus tag removed, dots removed). Check duplicates against this form.
ip_datacenter +40: 3.5.140.2 is in a datacenter range: Amazon Web Services (cloud, 3.5.128.0/19).
janedoe@gmail.com
PHP (examples/quickstart.php)
require 'vendor/autoload.php'; use Moonetix\SignupGuard\SignupGuard; use Moonetix\SignupGuard\VelocityLimiter; $limiter = new VelocityLimiter(); // in-memory: PHP-FPM needs a shared store, see "Velocity stores" $email = 'Jane.Doe+promo@googlemail.com'; $ip = '3.5.140.2'; $velocity = $limiter->check(['now' => time(), 'ip' => $ip, 'email' => $email]); $result = SignupGuard::assessSignup(['email' => $email, 'ip' => $ip, 'velocity' => $velocity]); echo $result['decision'], ' ', $result['score'], "\n"; foreach ($result['reasons'] as $r) { echo "{$r['code']} +{$r['points']}: {$r['message']}\n"; } echo $result['email']['normalized'], "\n";
The output is the same as above. Store email.normalized in a column with a unique index and keep sending mail to the address the user typed.
Acting on the decision
Each reason carries a hint that is safe to show the person signing up. It never names a limit or a list, so an attacker learns nothing they can tune against.
import { assessSignup } from '@moonetix/signup-guard'; const result = assessSignup({ email: 'temp123@mailinator.com', ip: '81.2.69.142' }); if (result.decision === 'allow') { console.log('create the account'); } else if (result.decision === 'review') { console.log('create it, but require a challenge and a verified email before it can do anything valuable'); } else { const hints = [...new Set(result.reasons.map((r) => r.hint).filter(Boolean))]; console.log('ask the user to fix:', hints); } console.log(result.reasons.map((r) => r.code)); // ask the user to fix: [ 'Please use a permanent email address.' ] // [ 'email_disposable' ]
| Decision | Suggested action |
|---|---|
allow |
Create the account. Still verify the email before anything of value. |
review |
Prefer soft steps: a bot challenge such as Turnstile, email verification, a hold on rewards or credits until the account has aged, a manual look before the first payout. |
block |
Refuse with the hints. Log the reasons, and give people a way to reach a human. |
Whatever the decision, check result.suggestion first. When it is not null, the domain looks like a typo of a common mailbox, and the email_typo reason carries a hint such as Did you mean jane@gmail.com?. Ask the person before you create the account, and keep what they typed if they say it is right.
Building blocks
(examples/building-blocks.mjs, examples/building-blocks.php)
import { normalizeEmail, suggestEmail, isRoleAddress, isFreeMail, checkDisposable, lookupIp, ipNetwork } from '@moonetix/signup-guard'; normalizeEmail('J.Smith+news@GoogleMail.com').normalized; // 'jsmith@gmail.com' normalizeEmail('shop@carol.fastmail.com').normalized; // 'carol@fastmail.com' normalizeEmail('erin+tag@outlook.com').normalized; // 'erin+tag@outlook.com' normalizeEmail('erin+tag@outlook.com', { plusTagDomains: ['outlook.com'] }).normalized; // 'erin@outlook.com' normalizeEmail('kim@@example.org').problem; // 'multiple-at' suggestEmail('jane@gmial.com'); // 'jane@gmail.com' suggestEmail('jane@hotmail.con'); // 'jane@hotmail.com' suggestEmail('jane@example.org'); // null isRoleAddress('No-Reply@example.org'); // true isFreeMail('jane@yahoo.co.uk'); // true checkDisposable('x@inbox.mailinator.com'); // { domain: 'inbox.mailinator.com', disposable: true, matchedDomain: 'mailinator.com', source: 'list', allowedBy: null } const ip = lookupIp('::ffff:3.219.87.128'); [ip.ip, ip.categories, ip.matches.map((m) => m.provider)]; // [ '3.219.87.128', [ 'cloud', 'services' ], [ 'github', 'aws' ] ] lookupIp('100.64.12.7').special; // { cidr: '100.64.0.0/10', kind: 'cgnat', description: 'a carrier-grade NAT address' } ipNetwork('2001:db8:abcd:12:ff::1'); // '2001:db8:abcd:12::/64'
use Moonetix\SignupGuard\SignupGuard as Guard; Guard::normalizeEmail('J.Smith+news@GoogleMail.com')['normalized']; // 'jsmith@gmail.com' Guard::suggestEmail('jane@gmial.com'); // 'jane@gmail.com' Guard::isRoleAddress('No-Reply@example.org'); // true Guard::isFreeMail('jane@yahoo.co.uk'); // true Guard::checkDisposable('x@inbox.mailinator.com')['matchedDomain']; // 'mailinator.com' Guard::lookupIp('::ffff:3.219.87.128')['categories']; // ['cloud', 'services'] Guard::ipNetwork('2001:db8:abcd:12:ff::1'); // '2001:db8:abcd:12::/64'
Configuration
Reasons and default weights
The score is the sum of the points of the reasons. Nothing else goes into it. A reason with 0 points still appears, as information for your logs.
| Code | Points | Added when | Hint shown to the user |
|---|---|---|---|
email_invalid |
100 | The address fails the syntax check (one @, dot-atom local part up to 64 characters, host name with at least two labels, ASCII) |
Check the email address for typos. |
email_disposable |
70 | The domain or a parent domain is on the disposable list or your blockDomains |
Please use a permanent email address. |
email_typo |
0 | suggestEmail finds a likely typo of a common mailbox domain; suggestion holds the corrected address |
Did you mean (the corrected address)? |
email_role |
10 | The part before @ is a shared mailbox such as admin, info, support or no-reply |
Please use an email address of your own, not a shared team address. |
email_free_mail |
30 | Only with freeMail: true: the domain belongs to a free consumer mailbox service, or is on your freeMailDomains |
Please use your work email address. |
email_normalized |
0 | Normalization removed a tag or dots or replaced a domain alias | none |
ip_datacenter |
40 | The address is in a cloud or services range |
Turn off your VPN or proxy, or switch to your home or mobile connection, and try again. |
ip_tor |
40 | The address is a Tor exit | Please sign up without Tor. |
ip_cdn |
15 | The address is in a CDN edge range | If you use a VPN or a privacy service, turn it off and try again. |
ip_privacy_relay |
0 | The address is an iCloud Private Relay egress | none |
ip_not_public |
0 | Private, CGNAT, loopback, link-local, documentation or other special-use address | none |
ip_invalid |
0 | The IP string does not parse | none |
velocity_ip |
30 | An ip rule is over its limit |
Too many attempts. Please try again later. |
velocity_network |
30 | A network rule (/24 or /64) is over its limit |
same |
velocity_email |
40 | An email rule is over its limit |
same |
velocity_<key> |
30 | A rule on your own field is over its limit (velocity_other sets the default) |
same |
Several tripped rules on the same key add one reason, not one per rule. An address that is both a Tor exit and inside a cloud range gets both reasons.
Why these points for the three mailbox reasons:
email_typo, 0. A typo is a slip by a real person, not a sign of fraud, so it adds nothing to the score. The reason is there to carry the hint. Some typo domains are registered and receive mail, and a few (gmial.com,hotmial.com) are on the disposable list, so a typo can come together withemail_disposable; the typo hint then tells the person what to fix.email_role, 10. A shared mailbox is a common way to open accounts with someone else's work address, and the confirmation email is read by whoever runs that inbox. Ten points never reachreviewalone, but they add up with a CDN hit or a velocity reason.email_free_mail, 30. The check is off unless you passfreeMail: true, for products that want a work address. Then a consumer address alone lands inreview, where you can ask for a work address or look at the account. Set the weight lower to keep it as a label, or 0 for information only.
assessSignup options
| Option | Default | Meaning |
|---|---|---|
weights |
DEFAULT_WEIGHTS |
Points per code, integers from 0 to 1000. Merged over the defaults. velocity_<yourkey> and velocity_other are accepted. |
thresholds |
{ review: 30, block: 70 } |
score >= block is block, score >= review is review. Integers, 1 <= review <= block. |
allowDomains |
[] |
Domains never treated as disposable, with their subdomains. Wins over both lists. |
blockDomains |
[] |
Extra disposable domains, with their subdomains. |
plusTagDomains |
[] |
Extra domains where +tag is removed during normalization. |
lowercaseLocal |
true |
Lowercase the part before @ for every domain. |
mailboxDomains |
[] |
Extra domains for typo suggestions. They are suggested, and never changed themselves. |
freeMail |
false |
Add email_free_mail for addresses at free consumer mailbox services. |
freeMailDomains |
[] |
Extra domains treated as free mail when freeMail is on. Exact domains, no subdomains. |
data |
bundled snapshot | A data set from createData(), loadData() or, in PHP, cachedData(). |
Input: { email, ip, velocity }, all optional. velocity is the result of VelocityLimiter.check(). The result also contains email (the normalizeEmail result), suggestion (the suggestEmail result), disposable and ip (the lookupIp result), so you can log one object per attempt.
Velocity rules
| Rule | Key | Limit | Window |
|---|---|---|---|
ip-hour |
ip |
5 | 1 hour |
ip-day |
ip |
20 | 24 hours |
network-day |
network |
50 | 24 hours |
email-day |
email |
5 | 24 hours |
new VelocityLimiter({ store, rules, keyPrefix }): store defaults to a MemoryStore, rules to the table above, keyPrefix to "sg:". A rule is { name, key, limit, windowSeconds }. key is ip, network (IPv4 /24, IPv6 /64), email (the normalized address), or the name of any field you pass to check(), such as an app install ID or a phone number. Rules whose value is missing or invalid are skipped, not counted.
check({ now, ip, email, ...yourFields }) records one attempt for every rule and returns { limited, exceeded, results }, where each result has rule, key, value, count, limit, windowSeconds, resetAt and exceeded. Call it on every attempt, including the ones that fail validation later, and before you decide.
Email normalization by provider
A rule is applied only where the provider documents it. Checked on 2026-11-11.
| Provider | Domains | +tag removed |
Dots removed | Other | Source |
|---|---|---|---|---|---|
| Gmail | gmail.com, googlemail.com | yes | yes | googlemail.com becomes gmail.com | dots, +aliases, googlemail |
| Proton Mail | proton.me, protonmail.com, protonmail.ch, pm.me | yes | no | Domains are not merged | Proton |
| Fastmail | fastmail.com, fastmail.fm | yes | no | tag@user.fastmail.com becomes user@fastmail.com |
Fastmail |
| Yandex Mail | yandex.com, yandex.ru | yes | no | yandex.com, yandex.ru | |
| Outlook.com | outlook.com, hotmail.com, live.com, msn.com | no | no | Microsoft documents plus addressing for Exchange Online organizations, not for consumer accounts. Opt in with plusTagDomains. |
Microsoft Learn |
| iCloud Mail | icloud.com, me.com, mac.com | no | no | Apple documents neither plus addressing nor that name@me.com and name@icloud.com are always one account |
Apple |
| Yahoo Mail | yahoo.com, ymail.com, rocketmail.com | no | no | Disposable addresses are basename-keyword, and the base name is chosen apart from the account name, so cutting the keyword does not recover the account |
Yahoo |
Zoho Mail, GMX, AOL and Tuta are not in the table: we found no provider documentation either way, so their addresses are only lowercased. Google Workspace and every other custom domain get no provider rules; for Workspace, Google states that dots do change the address. The table is exported as PROVIDERS, and a test fails if the two ports drift apart.
Typos, role addresses and free mail
Typo suggestions. suggestEmail works offline, on the domain only, and keeps the part before @ as typed. It returns the first of these that applies, or null:
- The domain is on
MAILBOX_DOMAINSor yourmailboxDomains: nothing to fix. - The top-level domain is a misspelling that is not a real one (
con,cmo,ocm,vom,xom,cpm,comm,coom,nte,ner,nett,ogr,orgg): it is fixed on any domain, sojane@acme.conbecomesjane@acme.com. A near miss of a listed domain is then fixed as in step 4, sogmial.conbecomesgmail.com. - The top-level domain is a real one that is easy to hit by mistake (
co,cm,om,ne): it is fixed only when the result is on the list, soicloud.cobecomesicloud.comandacme.costays as it is. - Otherwise the first label is compared with the listed domains that have the same rest (
gmial.comonly with*.comentries) and the same first letter. The distance is Damerau-Levenshtein (optimal string alignment): a missing, extra or swapped letter counts 1, a wrong letter counts 1 when the two keys sit next to each other on a QWERTY keyboard and 2 otherwise. Names of up to 4 letters are never matched, names of 5 to 7 letters allow 1, longer names 2. When two domains are equally near, there is no suggestion. - A domain without a dot gets
.comor its missing dot back only when that gives a listed domain:jane@gmailandjane@gmailcombecomejane@gmail.com.
These rules keep real domains that look like mailbox names alone: wahoo.com, email.com, cloud.com and libera.it get no suggestion. Add the domains your own users have, such as a company domain, to mailboxDomains: they are suggested for near misses and never changed.
Role addresses. isRoleAddress and email_role look at the part before @ after normalization, ignore case and a +tag, and remove dots, hyphens and underscores, so No-Reply+alerts@example.org matches noreply. ROLE_LOCAL_PARTS holds the mailbox names of RFC 2142 (info, marketing, sales, support, abuse, noc, security, postmaster, hostmaster, usenet, news, webmaster, www, uucp, ftp) and other common shared mailboxes: accounting, accounts, admin, administrator, billing, careers, contact, customerservice, donotreply, enquiries, feedback, finance, hello, help, helpdesk, hr, inquiries, jobs, legal, mailerdaemon, media, newsletter, noreply, office, orders, press, privacy, root, service, team.
Free mail. FREE_MAIL_PROVIDERS lists consumer webmail services where anyone can open a personal address at no cost, without owning a domain. The check matches exact domains only; mail.gmail.com does not match.
| Provider | Domains | Why it is consumer mail |
|---|---|---|
| Gmail | gmail.com, googlemail.com | Free personal Google accounts |
| Outlook.com | outlook.com, hotmail.com, live.com, msn.com, hotmail.co.uk, hotmail.fr, hotmail.de, hotmail.it, hotmail.es, live.co.uk, live.fr, outlook.fr, outlook.de | Microsoft's free personal mail; the country domains belong to personal accounts opened in those countries |
| Yahoo Mail | yahoo.com, ymail.com, rocketmail.com, yahoo.co.uk, yahoo.fr, yahoo.de, yahoo.it, yahoo.es, yahoo.ca, yahoo.co.in, yahoo.com.br | Free personal mail; ymail.com and rocketmail.com are older Yahoo domains |
| iCloud Mail | icloud.com, me.com, mac.com | Comes free with every Apple Account; me.com and mac.com are older addresses of the same service |
| AOL Mail | aol.com | Free personal mail |
| Proton Mail | proton.me, protonmail.com, protonmail.ch, pm.me | Free plan for personal accounts |
| Tuta | tuta.com, tutanota.com, tutanota.de, tutamail.com, tuta.io | Free plan for personal accounts |
| Zoho Mail | zohomail.com, zoho.com | Free personal accounts; business accounts use their own domain |
| GMX | gmx.com, gmx.net, gmx.de, gmx.at, gmx.ch | Free personal mail |
| mail.com | mail.com | Free personal mail |
| WEB.DE | web.de | Free personal mail in Germany |
| Yandex Mail | yandex.com, yandex.ru, ya.ru | Free personal mail of Yandex accounts |
| Mail.ru | mail.ru, bk.ru, list.ru, inbox.ru | Free personal mail; the four domains are offered at sign-up |
| QQ Mail | qq.com | Free mail of Tencent QQ accounts |
| NetEase Mail | 163.com, 126.com | Free personal mail |
| Naver Mail | naver.com | Free mail of Naver accounts |
| Daum Mail | daum.net, hanmail.net | Free mail of Daum accounts; hanmail.net is the older domain |
| Libero Mail | libero.it | Free personal mail in Italy |
| La Poste Mail | laposte.net | Free personal mail of the French postal service |
| Rediffmail | rediffmail.com | Free personal mail in India |
| Seznam Email | seznam.cz | Free personal mail in the Czech Republic |
| Poczta WP | wp.pl | Free personal mail of Wirtualna Polska |
Left out on purpose: Fastmail, which has no free plan; mailboxes that come with an internet or phone subscription, such as comcast.net or orange.fr; and disposable services, which email_disposable covers. Add others with freeMailDomains. MAILBOX_DOMAINS holds every domain above, the PROVIDERS domains and the mailboxes of large internet providers. The three lists are exported, and the shared vectors fail if the two ports drift apart.
The data
| Folder | Source | License | Used for |
|---|---|---|---|
data/disposable/ |
disposable-email-domains, disposable_email_blocklist.conf |
CC0 1.0 (copy) | checkDisposable, email_disposable |
data/ip/ |
moonetix/datacenter-ip-ranges, data/providers/*.txt |
MIT repository; each feed's terms in providers.json |
lookupIp, the ip_* reasons |
data/SOURCES.md and data/manifest.json record the upstream commit, the update time and the counts. dataInfo() returns the same at runtime.
| IP category | Providers | Reason |
|---|---|---|
cloud |
AWS, Google Cloud, Oracle Cloud, DigitalOcean, Akamai Cloud (Linode), Vultr | ip_datacenter |
services |
Google services, GitHub (including Actions runners) | ip_datacenter |
cdn |
Cloudflare, Fastly | ip_cdn |
tor |
Tor exit nodes | ip_tor |
privacy-relay |
iCloud Private Relay egress | ip_privacy_relay |
Weekly update. update-data.yml runs every Monday and on demand (workflow_dispatch). It runs scripts/update-data.mjs, which pins each upstream to its current commit, downloads the files from that commit, parses every line with the library itself, and compares the result with the snapshot. It refuses to write anything when a download fails, a line does not parse, a provider disappears or a list shrinks by more than half. Then both test suites run, and the workflow commits only when data/ changed. Run it yourself with npm run update-data.
Your own lists. createData({ disposableDomains, ipRanges }) builds a data set from arrays (ipRanges entries are { cidr, provider, providerName, category }), and loadData(dir) reads a folder with the same layout as data/. Pass the result as data.
Velocity stores
MemoryStore lives in one process. With several Node processes, or with PHP-FPM, use a shared store. A store has one method, hit(key, ttlSeconds, now), that increments a counter, sets its expiry when it is created, and returns the new count. Keys already contain the window start, so the store needs no clock of its own. Both stores below write the same keys, so a Node service and a PHP app can share counters.
Redis, Node.js with the official redis client (examples/redis-store.mjs):
import { createClient } from 'redis'; import { VelocityLimiter } from '@moonetix/signup-guard'; // INCR and EXPIRE in one script, so a counter can never be left without an expiry. const HIT = `local c = redis.call('INCR', KEYS[1]) if c == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end return c`; const redis = await createClient({ url: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379' }).connect(); const limiter = new VelocityLimiter({ store: { hit: (key, ttlSeconds) => redis.eval(HIT, { keys: [key], arguments: [String(ttlSeconds)] }) }, });
Redis, PHP with phpredis (examples/redis-store.php):
use Moonetix\SignupGuard\VelocityLimiter; use Moonetix\SignupGuard\VelocityStore; final class RedisVelocityStore implements VelocityStore { // INCR and EXPIRE in one script, so a counter can never be left without an expiry. private const HIT = "local c = redis.call('INCR', KEYS[1])\nif c == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end\nreturn c"; public function __construct(private Redis $redis) { } public function hit(string $key, int $ttlSeconds, int $now): int { return (int)$this->redis->eval(self::HIT, [$key, $ttlSeconds], 1); } } $redis = new Redis(); $redis->connect(getenv('REDIS_HOST') ?: '127.0.0.1', (int)(getenv('REDIS_PORT') ?: 6379)); $limiter = new VelocityLimiter(store: new RedisVelocityStore($redis));
A SQL table works too: a primary key on key, an upsert that increments count, and a periodic delete of expired rows.
Framework examples
Each example names in its first lines what to install; none of it is a dependency of the package.
| Example | What it shows |
|---|---|
| examples/express-middleware.mjs | Express 5 middleware on a sign-up route: block answers 422 with the hints, a likely typo answers 409 with the suggestion, review creates the account on hold (202), allow creates it (201). trust proxy is set to the number of proxies in front of the app, so req.ip is the client address. |
| examples/nextjs-route.mjs | A Next.js App Router route handler with the same mapping. It runs on the Node.js runtime, because the library reads its data from disk, and takes the client address from the X-Forwarded-For entry your own proxy added. |
| examples/laravel/ | A validation rule for the email field of a FormRequest, velocity counters in the Laravel cache, and a README with the request and controller code. |
All three count the attempt before they judge it, and all three depend on reading the right client address: see False positives and other pitfalls. An in-memory VelocityLimiter is per process; on serverless platforms or with several servers, give it a shared store.
PHP-FPM: load the data once
Parsing the snapshot takes about 190 ms and 32 MB in PHP. That is fine for a CLI job and wasteful on every web request. cachedData() writes the parsed tables as a PHP file that holds only literals, which OPcache keeps in shared memory, and rebuilds it when the snapshot changes (examples/fpm-cache.php):
use Moonetix\SignupGuard\SignupGuard; // First call builds a literal-only PHP file; after that OPcache serves it from shared memory. $data = SignupGuard::cachedData(sys_get_temp_dir() . '/signup-guard-data.php'); $result = SignupGuard::assessSignup(['email' => 'temp123@mailinator.com', 'ip' => '81.2.69.142'], ['data' => $data]); echo $result['decision'], ' ', $result['score'], "\n"; // block 70
With OPcache enabled, a full assessSignup including the data load measured about 0.4 ms per request on PHP 8.4. Point the cache file at a directory the PHP user can write and nobody else can. In Node.js the data loads once per process (about 200 ms) and lookups take a few microseconds.
How it works
VelocityLimiter.check()derives the values for each rule (canonical IP, /24 or /64, normalized email, your fields) and increments one counter per rule in the current fixed window. The window start is part of the key, so counters expire on their own.normalizeEmailtrims ASCII whitespace, rejects anything that is not a plain ASCII address, lowercases, then applies the documented provider rules: subdomain tags, domain aliases,+tags, dots.checkDisposabletakes the domain and tests it and each parent domain (never the bare TLD) against your allow list, your block list, then the snapshot.lookupIpparses IPv4 and IPv6 strictly (no octal-looking parts, no zone IDs), turns IPv4-mapped IPv6 into IPv4, and checks the special-use ranges first. A private or CGNAT address is reported as not public and never matched against provider ranges.- Public addresses go through a binary search over ranges sorted by start, followed by a short walk back for ranges that nest across providers, such as a GitHub block inside an AWS block. Every containing range is returned, most specific first.
assessSignupturns each finding into a reason with a code, points, a message for you and a hint for the user. The score is the sum of the points, compared with two thresholds.- Both ports keep addresses as exact integers or fixed-width bytes, so there is no floating point anywhere, and the shared vectors pin every message string.
False positives and other pitfalls
Every signal here also fires for honest people sometimes. The defaults are set so that no network signal blocks on its own; a block needs either a bad email or several signals together.
- Read the right client IP. Behind a load balancer or CDN, the socket address is the proxy. Take the client address from the header your own proxy sets (for example
CF-Connecting-IPbehind Cloudflare), and never trustX-Forwarded-Forfrom the open internet. If many users show up withip_not_public, this is why. - Carrier-grade NAT and mobile networks. Mobile carriers put thousands of subscribers behind a few public IPv4 addresses. Keep per-IP limits generous and count attempts, not accounts.
- Universities, offices, hotels. One /24 can be a whole campus. The default
network-daylimit is 50 for that reason; raise it if your audience is students. - IPv6. One home usually gets a whole /64, and rotating within it is free. Per-IP limits on IPv6 are weak, which is why the
networkkey groups by /64. - iCloud Private Relay. Safari users on iCloud+ browse through Apple's relay addresses. They are real people, so the reason carries 0 points by default. Private Relay is one of the most common causes of a false VPN warning; see VPN or proxy detected.
- CDN ranges. People rarely browse from Cloudflare or Fastly edge addresses, so a hit usually means a proxy or worker in front of the browser. Cloudflare WARP users are not matched: WARP exits from addresses outside Cloudflare's published ranges. The default weight is low (15); check your own logs before raising it.
- Corporate and school networks. Company VPN gateways and secure web proxies often run in cloud regions, and Google's service ranges cover some Google-operated proxies and fetchers. A datacenter match alone lands in
review, notblock, for that reason. - Residential proxies are invisible here. They route through home connections and are in no provider list. Range checks stop the cheapest automation; slow attacks spread over residential addresses need behavior signals and checks at payout. See What is a residential proxy?.
- The disposable list is not perfect. The maintainers say they cannot guarantee every entry is still disposable. Keep
allowDomainsfor the ones your users prove wrong, andblockDomainsfor new ones you find. - Role addresses belong to people too. Some people really do use
info@of their one-person business, and old Gmail accounts namedadminexist. That is whyemail_rolehas 10 points and no block. - Typo suggestions are guesses.
suggestEmailonly knows the domains on its list and yourmailboxDomains. Offer the suggestion and let the person keep what they typed. - Free mail is not a fraud signal. Most honest people sign up with a consumer address. Turn on
freeMailonly when your product needs a work address. - Normalize for duplicates, not for mail. Send to the address the user typed. Gmail rules apply only to gmail.com and googlemail.com; a Workspace domain on Google's servers keeps its dots.
- Fixed windows allow bursts at the edge. A client can use a full limit at 00:59 and another at 01:00. Pair a short window with a longer one, as the defaults do.
- Tell people what to fix. Show the
hint, not the score or the rule. Keep an appeal path to a person, and look at what appeals overturn: a rule that keeps losing appeals needs a lower weight. - Mind what you store. Velocity keys contain IPs and emails for at most the window length. If that is too much for your privacy policy, pass a keyed hash as a custom field and use it as the rule key instead of
email.
What is IP reputation? covers shared addresses and fair handling in more depth.
What signup-guard does not do
- No device fingerprinting. It reads an email address and an IP address, and anything else only if you pass it as a velocity field.
- No network calls at runtime. Every check is local. Downloads happen only in the update script, on your schedule.
- No MX or SMTP checks. They are slow, they fail during DNS outages, and a working inbox proves little. Send a verification email instead.
- No bot challenge. Use Turnstile, hCaptcha or reCAPTCHA, verified on your server, for the
reviewband. - No machine learning. Weights are integers in a table you can read and change.
Common errors
| You see | Cause and fix |
|---|---|
velocity must be the result of VelocityLimiter.check() |
In Node, check() is async and you passed the Promise. await it first. |
now must be a non-negative integer (Unix seconds) |
now is missing or not an integer. Use Math.floor(Date.now() / 1000) or time(). |
| Velocity limits never trip, and no error | now is in milliseconds (Date.now()). It passes the integer check, but every window becomes 1,000 times shorter, so a one-hour rule resets every 3.6 seconds. Divide by 1000. |
Unknown reason code "..." |
weights accepts only the codes in the table above, plus velocity_<yourkey> and velocity_other. |
thresholds must be integers with 1 <= review <= block |
A threshold is not an integer, review is below 1, or review ends up above block. A single key is merged over the defaults, so { review: 80 } alone fails against the default block: 70. |
store.hit must return the new count as a positive integer |
Your store returned a string, nothing, or 0. Cast the Redis reply to an integer, as the PHP store above does. |
Cannot write /path/to/cache.php (PHP) |
cachedData() could not write next to the cache file. Use a directory the PHP-FPM user owns. |
Cannot read <dir>/ip/providers.json (PHP), ENOENT ... ip/providers.json (Node) |
loadData(dir) points at a folder without the data/ layout. Copy the whole data/ folder, not only the lists. |
Errors thrown by the library are SignupGuardError in Node and SignupGuardException in PHP, with the same code in both. Bad input from users never throws: an unparsable email or IP becomes an email_invalid or ip_invalid reason.
Tests
npm test # node --test: shared vectors, API tests, checks on the bundled snapshot php php/tests/run.php # shared vectors, PHP-specific checks, the same snapshot checks
test-vectors/vectors.json holds 294 cases: email syntax and provider rules, typo suggestions, role addresses and free mail with the exported lists, IPv4 and IPv6 parsing and RFC 5952 formatting, CIDR edges, nested ranges, special-use ranges, disposable matching with allow and block lists, velocity windows and their boundaries, and full assessments with every message string. They run against a small fixture data set inside the file, never the snapshot, so a weekly data update cannot break them. CI runs both suites on Node 20 and 22 and PHP 8.1 and 8.4, runs every example, and runs the Redis examples against a Redis service.
npm run site builds the demo page into _site/: the files of src/ for the browser and the snapshot as two static files. The examples on the page are test vectors, and the build stops with an error when one of them no longer returns its decision, score and reasons on the current snapshot.
Further reading
- Moonetix Academy: How to stop fake signups, Stop multi-accounting and VPN abuse, What is IP reputation?, What is a residential proxy?, VPN or proxy detected, How to prevent referral fraud
- Data: moonetix/datacenter-ip-ranges, disposable-email-domains
About Moonetix
Moonetix is an affiliate network. Publishers add its offerwall to an app, game, website, bot or community, and users earn the publisher's own currency by completing offers.
Other open source from Moonetix: reward-economy-kit, country-tiers, datacenter-ip-ranges, offerwall-fraud-playbook, referral-engine, gamification-kit, awesome-offerwalls, offerwall-postback-handlers.
License
MIT. See LICENSE. The vendored data keeps its own terms, listed in data/SOURCES.md.