@moonetix/signup-guard 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +415 -2
- package/data/SOURCES.md +40 -0
- package/data/disposable/LICENSE.txt +14 -0
- package/data/disposable/domains.txt +10274 -0
- package/data/ip/aws.txt +4115 -0
- package/data/ip/cloudflare.txt +22 -0
- package/data/ip/digitalocean.txt +241 -0
- package/data/ip/fastly.txt +24 -0
- package/data/ip/github.txt +6572 -0
- package/data/ip/google-cloud.txt +495 -0
- package/data/ip/google-services.txt +395 -0
- package/data/ip/icloud-private-relay.txt +13994 -0
- package/data/ip/linode.txt +279 -0
- package/data/ip/oracle-cloud.txt +809 -0
- package/data/ip/providers.json +98 -0
- package/data/ip/tor.txt +686 -0
- package/data/ip/vultr.txt +142 -0
- package/data/manifest.json +68 -0
- package/package.json +42 -4
- package/src/assess.js +153 -0
- package/src/data.js +187 -0
- package/src/email.js +208 -0
- package/src/errors.js +15 -0
- package/src/index.d.ts +268 -0
- package/src/index.js +17 -0
- package/src/ip.js +192 -0
- package/src/velocity.js +108 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Moonetix
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,416 @@
|
|
|
1
|
-
#
|
|
1
|
+
# signup-guard
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**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.**
|
|
4
|
+
|
|
5
|
+
[](https://github.com/moonetix/signup-guard/actions/workflows/ci.yml)
|
|
6
|
+
[](https://github.com/moonetix/signup-guard/actions/workflows/update-data.yml)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](package.json)
|
|
9
|
+
[](#quick-start)
|
|
10
|
+
[](#quick-start)
|
|
11
|
+
[](https://www.npmjs.com/package/@moonetix/signup-guard)
|
|
12
|
+
[](https://packagist.org/packages/moonetix/signup-guard)
|
|
13
|
+
|
|
14
|
+
Maintained by [Moonetix](https://moonetix.com).
|
|
15
|
+
|
|
16
|
+
**[Open the live demo](https://moonetix.github.io/signup-guard/)**: 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.
|
|
17
|
+
|
|
18
|
+
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.
|
|
19
|
+
|
|
20
|
+
- **JavaScript:** ESM, Node 20+, zero dependencies, TypeScript declarations.
|
|
21
|
+
- **PHP:** 8.1+, zero dependencies, standard extensions only.
|
|
22
|
+
- **One spec:** both suites run the same [test vectors](test-vectors/vectors.json), so the two ports give the same answer to the same input.
|
|
23
|
+
- **Data you can audit:** the [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains) list (CC0) and [moonetix/datacenter-ip-ranges](https://github.com/moonetix/datacenter-ip-ranges), vendored in [`data/`](data/SOURCES.md) and refreshed every week.
|
|
24
|
+
|
|
25
|
+
## The checks
|
|
26
|
+
|
|
27
|
+
```mermaid
|
|
28
|
+
flowchart TD
|
|
29
|
+
A["Sign-up attempt<br/>email, IP, your own fields"] --> V["VelocityLimiter.check()<br/>one counter per rule: IP, /24 or /64, email"]
|
|
30
|
+
A --> S["assessSignup({ email, ip, velocity })"]
|
|
31
|
+
V -->|velocity result| S
|
|
32
|
+
S --> E["Email<br/>syntax, provider rules,<br/>disposable list"]
|
|
33
|
+
S --> I["IP<br/>special-use, cloud, services,<br/>CDN, Tor, privacy relay"]
|
|
34
|
+
S --> VR["Velocity<br/>rules over their limit"]
|
|
35
|
+
E --> R["reasons: code, points, message, hint<br/>score = sum of points"]
|
|
36
|
+
I --> R
|
|
37
|
+
VR --> R
|
|
38
|
+
R -->|below 30| OK[allow]
|
|
39
|
+
R -->|30 to 69| RV["review<br/>challenge, verify, hold"]
|
|
40
|
+
R -->|70 and up| B["block<br/>show the hints"]
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
| Function | What it does |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| `assessSignup(input, options)` | Runs every check and returns `score`, `decision`, `reasons` and the raw results |
|
|
46
|
+
| `normalizeEmail(email, options)` | Validates an address and returns the form to check duplicates against |
|
|
47
|
+
| `checkDisposable(emailOrDomain, options)` | Disposable list lookup on the domain and every parent domain, with allow and block lists |
|
|
48
|
+
| `lookupIp(ip, options)` | Public or special-use, plus every listed range that contains the address |
|
|
49
|
+
| `normalizeIp(ip)`, `ipNetwork(ip)` | Canonical address text, and the /24 or /64 it belongs to |
|
|
50
|
+
| `new VelocityLimiter({ store, rules })` | Fixed-window attempt counters per IP, network, normalized email or your own field |
|
|
51
|
+
| `MemoryStore` | In-process counters for tests and single-process apps |
|
|
52
|
+
| `createData`, `loadData`, `dataInfo` | Use your own lists, load a snapshot folder, read snapshot dates and counts |
|
|
53
|
+
| `PROVIDERS`, `DEFAULT_WEIGHTS`, `DEFAULT_THRESHOLDS`, `DEFAULT_VELOCITY_RULES` | The defaults, as data |
|
|
54
|
+
| `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`) |
|
|
55
|
+
| `SignupGuardError` | Thrown for bad arguments, options, rules or data. `code` is one of `invalid_argument`, `invalid_option`, `invalid_rule`, `data_error` |
|
|
56
|
+
|
|
57
|
+
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`).
|
|
58
|
+
|
|
59
|
+
## Install
|
|
60
|
+
|
|
61
|
+
The JavaScript package is on [npm](https://www.npmjs.com/package/@moonetix/signup-guard) and the PHP package is on [Packagist](https://packagist.org/packages/moonetix/signup-guard):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm install @moonetix/signup-guard
|
|
65
|
+
composer require moonetix/signup-guard
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
Without Composer, `require 'php/autoload.php';` from a copy of the repository.
|
|
71
|
+
|
|
72
|
+
## Quick start
|
|
73
|
+
|
|
74
|
+
**JavaScript** ([examples/quickstart.mjs](examples/quickstart.mjs))
|
|
75
|
+
|
|
76
|
+
```js
|
|
77
|
+
import { assessSignup, VelocityLimiter } from '@moonetix/signup-guard';
|
|
78
|
+
|
|
79
|
+
const limiter = new VelocityLimiter(); // in-memory: fine for one process, see "Velocity stores" otherwise
|
|
80
|
+
|
|
81
|
+
async function screenSignup({ email, ip }) {
|
|
82
|
+
const now = Math.floor(Date.now() / 1000);
|
|
83
|
+
const velocity = await limiter.check({ now, ip, email }); // count the attempt before you judge it
|
|
84
|
+
return assessSignup({ email, ip, velocity });
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const result = await screenSignup({ email: 'Jane.Doe+promo@googlemail.com', ip: '3.5.140.2' });
|
|
88
|
+
|
|
89
|
+
console.log(result.decision, result.score);
|
|
90
|
+
for (const r of result.reasons) console.log(`${r.code} +${r.points}: ${r.message}`);
|
|
91
|
+
console.log(result.email.normalized);
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```text
|
|
95
|
+
review 40
|
|
96
|
+
email_normalized +0: Normalized to janedoe@gmail.com (lowercased, domain alias replaced, plus tag removed, dots removed). Check duplicates against this form.
|
|
97
|
+
ip_datacenter +40: 3.5.140.2 is in a datacenter range: Amazon Web Services (cloud, 3.5.128.0/19).
|
|
98
|
+
janedoe@gmail.com
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**PHP** ([examples/quickstart.php](examples/quickstart.php))
|
|
102
|
+
|
|
103
|
+
```php
|
|
104
|
+
require 'vendor/autoload.php';
|
|
105
|
+
|
|
106
|
+
use Moonetix\SignupGuard\SignupGuard;
|
|
107
|
+
use Moonetix\SignupGuard\VelocityLimiter;
|
|
108
|
+
|
|
109
|
+
$limiter = new VelocityLimiter(); // in-memory: PHP-FPM needs a shared store, see "Velocity stores"
|
|
110
|
+
|
|
111
|
+
$email = 'Jane.Doe+promo@googlemail.com';
|
|
112
|
+
$ip = '3.5.140.2';
|
|
113
|
+
|
|
114
|
+
$velocity = $limiter->check(['now' => time(), 'ip' => $ip, 'email' => $email]);
|
|
115
|
+
$result = SignupGuard::assessSignup(['email' => $email, 'ip' => $ip, 'velocity' => $velocity]);
|
|
116
|
+
|
|
117
|
+
echo $result['decision'], ' ', $result['score'], "\n";
|
|
118
|
+
foreach ($result['reasons'] as $r) {
|
|
119
|
+
echo "{$r['code']} +{$r['points']}: {$r['message']}\n";
|
|
120
|
+
}
|
|
121
|
+
echo $result['email']['normalized'], "\n";
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
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.
|
|
125
|
+
|
|
126
|
+
### Acting on the decision
|
|
127
|
+
|
|
128
|
+
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.
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
import { assessSignup } from '@moonetix/signup-guard';
|
|
132
|
+
|
|
133
|
+
const result = assessSignup({ email: 'temp123@mailinator.com', ip: '81.2.69.142' });
|
|
134
|
+
|
|
135
|
+
if (result.decision === 'allow') {
|
|
136
|
+
console.log('create the account');
|
|
137
|
+
} else if (result.decision === 'review') {
|
|
138
|
+
console.log('create it, but require a challenge and a verified email before it can do anything valuable');
|
|
139
|
+
} else {
|
|
140
|
+
const hints = [...new Set(result.reasons.map((r) => r.hint).filter(Boolean))];
|
|
141
|
+
console.log('ask the user to fix:', hints);
|
|
142
|
+
}
|
|
143
|
+
console.log(result.reasons.map((r) => r.code));
|
|
144
|
+
// ask the user to fix: [ 'Please use a permanent email address.' ]
|
|
145
|
+
// [ 'email_disposable' ]
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
| Decision | Suggested action |
|
|
149
|
+
| --- | --- |
|
|
150
|
+
| `allow` | Create the account. Still verify the email before anything of value. |
|
|
151
|
+
| `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. |
|
|
152
|
+
| `block` | Refuse with the hints. Log the reasons, and give people a way to reach a human. |
|
|
153
|
+
|
|
154
|
+
### Building blocks
|
|
155
|
+
|
|
156
|
+
([examples/building-blocks.mjs](examples/building-blocks.mjs), [examples/building-blocks.php](examples/building-blocks.php))
|
|
157
|
+
|
|
158
|
+
```js
|
|
159
|
+
import { normalizeEmail, checkDisposable, lookupIp, ipNetwork } from '@moonetix/signup-guard';
|
|
160
|
+
|
|
161
|
+
normalizeEmail('J.Smith+news@GoogleMail.com').normalized; // 'jsmith@gmail.com'
|
|
162
|
+
normalizeEmail('shop@carol.fastmail.com').normalized; // 'carol@fastmail.com'
|
|
163
|
+
normalizeEmail('erin+tag@outlook.com').normalized; // 'erin+tag@outlook.com'
|
|
164
|
+
normalizeEmail('erin+tag@outlook.com', { plusTagDomains: ['outlook.com'] }).normalized; // 'erin@outlook.com'
|
|
165
|
+
normalizeEmail('kim@@example.org').problem; // 'multiple-at'
|
|
166
|
+
|
|
167
|
+
checkDisposable('x@inbox.mailinator.com');
|
|
168
|
+
// { domain: 'inbox.mailinator.com', disposable: true, matchedDomain: 'mailinator.com', source: 'list', allowedBy: null }
|
|
169
|
+
|
|
170
|
+
const ip = lookupIp('::ffff:3.219.87.128');
|
|
171
|
+
[ip.ip, ip.categories, ip.matches.map((m) => m.provider)]; // [ '3.219.87.128', [ 'cloud', 'services' ], [ 'github', 'aws' ] ]
|
|
172
|
+
lookupIp('100.64.12.7').special; // { cidr: '100.64.0.0/10', kind: 'cgnat', description: 'a carrier-grade NAT address' }
|
|
173
|
+
ipNetwork('2001:db8:abcd:12:ff::1'); // '2001:db8:abcd:12::/64'
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```php
|
|
177
|
+
use Moonetix\SignupGuard\SignupGuard as Guard;
|
|
178
|
+
|
|
179
|
+
Guard::normalizeEmail('J.Smith+news@GoogleMail.com')['normalized']; // 'jsmith@gmail.com'
|
|
180
|
+
Guard::checkDisposable('x@inbox.mailinator.com')['matchedDomain']; // 'mailinator.com'
|
|
181
|
+
Guard::lookupIp('::ffff:3.219.87.128')['categories']; // ['cloud', 'services']
|
|
182
|
+
Guard::ipNetwork('2001:db8:abcd:12:ff::1'); // '2001:db8:abcd:12::/64'
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Configuration
|
|
186
|
+
|
|
187
|
+
### Reasons and default weights
|
|
188
|
+
|
|
189
|
+
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.
|
|
190
|
+
|
|
191
|
+
| Code | Points | Added when | Hint shown to the user |
|
|
192
|
+
| --- | ---: | --- | --- |
|
|
193
|
+
| `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. |
|
|
194
|
+
| `email_disposable` | 70 | The domain or a parent domain is on the disposable list or your `blockDomains` | Please use a permanent email address. |
|
|
195
|
+
| `email_normalized` | 0 | Normalization removed a tag or dots or replaced a domain alias | none |
|
|
196
|
+
| `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. |
|
|
197
|
+
| `ip_tor` | 40 | The address is a Tor exit | Please sign up without Tor. |
|
|
198
|
+
| `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. |
|
|
199
|
+
| `ip_privacy_relay` | 0 | The address is an iCloud Private Relay egress | none |
|
|
200
|
+
| `ip_not_public` | 0 | Private, CGNAT, loopback, link-local, documentation or other special-use address | none |
|
|
201
|
+
| `ip_invalid` | 0 | The IP string does not parse | none |
|
|
202
|
+
| `velocity_ip` | 30 | An `ip` rule is over its limit | Too many attempts. Please try again later. |
|
|
203
|
+
| `velocity_network` | 30 | A `network` rule (/24 or /64) is over its limit | same |
|
|
204
|
+
| `velocity_email` | 40 | An `email` rule is over its limit | same |
|
|
205
|
+
| `velocity_<key>` | 30 | A rule on your own field is over its limit (`velocity_other` sets the default) | same |
|
|
206
|
+
|
|
207
|
+
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.
|
|
208
|
+
|
|
209
|
+
### `assessSignup` options
|
|
210
|
+
|
|
211
|
+
| Option | Default | Meaning |
|
|
212
|
+
| --- | --- | --- |
|
|
213
|
+
| `weights` | `DEFAULT_WEIGHTS` | Points per code, integers from 0 to 1000. Merged over the defaults. `velocity_<yourkey>` and `velocity_other` are accepted. |
|
|
214
|
+
| `thresholds` | `{ review: 30, block: 70 }` | `score >= block` is `block`, `score >= review` is `review`. Integers, `1 <= review <= block`. |
|
|
215
|
+
| `allowDomains` | `[]` | Domains never treated as disposable, with their subdomains. Wins over both lists. |
|
|
216
|
+
| `blockDomains` | `[]` | Extra disposable domains, with their subdomains. |
|
|
217
|
+
| `plusTagDomains` | `[]` | Extra domains where `+tag` is removed during normalization. |
|
|
218
|
+
| `lowercaseLocal` | `true` | Lowercase the part before `@` for every domain. |
|
|
219
|
+
| `data` | bundled snapshot | A data set from `createData()`, `loadData()` or, in PHP, `cachedData()`. |
|
|
220
|
+
|
|
221
|
+
Input: `{ email, ip, velocity }`, all optional. `velocity` is the result of `VelocityLimiter.check()`. The result also contains `email` (the `normalizeEmail` result), `disposable` and `ip` (the `lookupIp` result), so you can log one object per attempt.
|
|
222
|
+
|
|
223
|
+
### Velocity rules
|
|
224
|
+
|
|
225
|
+
| Rule | Key | Limit | Window |
|
|
226
|
+
| --- | --- | ---: | --- |
|
|
227
|
+
| `ip-hour` | `ip` | 5 | 1 hour |
|
|
228
|
+
| `ip-day` | `ip` | 20 | 24 hours |
|
|
229
|
+
| `network-day` | `network` | 50 | 24 hours |
|
|
230
|
+
| `email-day` | `email` | 5 | 24 hours |
|
|
231
|
+
|
|
232
|
+
`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.
|
|
233
|
+
|
|
234
|
+
`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.
|
|
235
|
+
|
|
236
|
+
### Email normalization by provider
|
|
237
|
+
|
|
238
|
+
A rule is applied only where the provider documents it. Checked on 2026-11-11.
|
|
239
|
+
|
|
240
|
+
| Provider | Domains | `+tag` removed | Dots removed | Other | Source |
|
|
241
|
+
| --- | --- | --- | --- | --- | --- |
|
|
242
|
+
| Gmail | gmail.com, googlemail.com | yes | yes | googlemail.com becomes gmail.com | [dots](https://support.google.com/mail/answer/7436150), [+aliases](https://support.google.com/mail/answer/12096), [googlemail](https://support.google.com/mail/answer/10313) |
|
|
243
|
+
| Proton Mail | proton.me, protonmail.com, protonmail.ch, pm.me | yes | no | Domains are not merged | [Proton](https://proton.me/support/addresses-and-aliases) |
|
|
244
|
+
| Fastmail | fastmail.com, fastmail.fm | yes | no | `tag@user.fastmail.com` becomes `user@fastmail.com` | [Fastmail](https://www.fastmail.help/hc/en-us/articles/360060591053) |
|
|
245
|
+
| Yandex Mail | yandex.com, yandex.ru | yes | no | | [yandex.com](https://yandex.com/support/mail/reg.html), [yandex.ru](https://yandex.ru/support/mail/reg.html) |
|
|
246
|
+
| 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](https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/plus-addressing-in-exchange-online) |
|
|
247
|
+
| 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](https://support.apple.com/en-us/118230) |
|
|
248
|
+
| 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](https://help.yahoo.com/kb/SLN28815.html) |
|
|
249
|
+
|
|
250
|
+
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.
|
|
251
|
+
|
|
252
|
+
## The data
|
|
253
|
+
|
|
254
|
+
| Folder | Source | License | Used for |
|
|
255
|
+
| --- | --- | --- | --- |
|
|
256
|
+
| [`data/disposable/`](data/disposable) | [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains), `disposable_email_blocklist.conf` | CC0 1.0 ([copy](data/disposable/LICENSE.txt)) | `checkDisposable`, `email_disposable` |
|
|
257
|
+
| [`data/ip/`](data/ip) | [moonetix/datacenter-ip-ranges](https://github.com/moonetix/datacenter-ip-ranges), `data/providers/*.txt` | MIT repository; each feed's terms in [`providers.json`](data/ip/providers.json) | `lookupIp`, the `ip_*` reasons |
|
|
258
|
+
|
|
259
|
+
[`data/SOURCES.md`](data/SOURCES.md) and [`data/manifest.json`](data/manifest.json) record the upstream commit, the update time and the counts. `dataInfo()` returns the same at runtime.
|
|
260
|
+
|
|
261
|
+
| IP category | Providers | Reason |
|
|
262
|
+
| --- | --- | --- |
|
|
263
|
+
| `cloud` | AWS, Google Cloud, Oracle Cloud, DigitalOcean, Akamai Cloud (Linode), Vultr | `ip_datacenter` |
|
|
264
|
+
| `services` | Google services, GitHub (including Actions runners) | `ip_datacenter` |
|
|
265
|
+
| `cdn` | Cloudflare, Fastly | `ip_cdn` |
|
|
266
|
+
| `tor` | Tor exit nodes | `ip_tor` |
|
|
267
|
+
| `privacy-relay` | iCloud Private Relay egress | `ip_privacy_relay` |
|
|
268
|
+
|
|
269
|
+
**Weekly update.** [`update-data.yml`](.github/workflows/update-data.yml) runs every Monday and on demand (`workflow_dispatch`). It runs [`scripts/update-data.mjs`](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`.
|
|
270
|
+
|
|
271
|
+
**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`.
|
|
272
|
+
|
|
273
|
+
## Velocity stores
|
|
274
|
+
|
|
275
|
+
`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.
|
|
276
|
+
|
|
277
|
+
**Redis, Node.js** with the official `redis` client ([examples/redis-store.mjs](examples/redis-store.mjs)):
|
|
278
|
+
|
|
279
|
+
```js
|
|
280
|
+
import { createClient } from 'redis';
|
|
281
|
+
import { VelocityLimiter } from '@moonetix/signup-guard';
|
|
282
|
+
|
|
283
|
+
// INCR and EXPIRE in one script, so a counter can never be left without an expiry.
|
|
284
|
+
const HIT = `local c = redis.call('INCR', KEYS[1])
|
|
285
|
+
if c == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
|
|
286
|
+
return c`;
|
|
287
|
+
|
|
288
|
+
const redis = await createClient({ url: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379' }).connect();
|
|
289
|
+
|
|
290
|
+
const limiter = new VelocityLimiter({
|
|
291
|
+
store: { hit: (key, ttlSeconds) => redis.eval(HIT, { keys: [key], arguments: [String(ttlSeconds)] }) },
|
|
292
|
+
});
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
**Redis, PHP** with phpredis ([examples/redis-store.php](examples/redis-store.php)):
|
|
296
|
+
|
|
297
|
+
```php
|
|
298
|
+
use Moonetix\SignupGuard\VelocityLimiter;
|
|
299
|
+
use Moonetix\SignupGuard\VelocityStore;
|
|
300
|
+
|
|
301
|
+
final class RedisVelocityStore implements VelocityStore
|
|
302
|
+
{
|
|
303
|
+
// INCR and EXPIRE in one script, so a counter can never be left without an expiry.
|
|
304
|
+
private const HIT = "local c = redis.call('INCR', KEYS[1])\nif c == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end\nreturn c";
|
|
305
|
+
|
|
306
|
+
public function __construct(private Redis $redis)
|
|
307
|
+
{
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
public function hit(string $key, int $ttlSeconds, int $now): int
|
|
311
|
+
{
|
|
312
|
+
return (int)$this->redis->eval(self::HIT, [$key, $ttlSeconds], 1);
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
$redis = new Redis();
|
|
317
|
+
$redis->connect(getenv('REDIS_HOST') ?: '127.0.0.1', (int)(getenv('REDIS_PORT') ?: 6379));
|
|
318
|
+
$limiter = new VelocityLimiter(store: new RedisVelocityStore($redis));
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
A SQL table works too: a primary key on `key`, an upsert that increments `count`, and a periodic delete of expired rows.
|
|
322
|
+
|
|
323
|
+
## PHP-FPM: load the data once
|
|
324
|
+
|
|
325
|
+
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](examples/fpm-cache.php)):
|
|
326
|
+
|
|
327
|
+
```php
|
|
328
|
+
use Moonetix\SignupGuard\SignupGuard;
|
|
329
|
+
|
|
330
|
+
// First call builds a literal-only PHP file; after that OPcache serves it from shared memory.
|
|
331
|
+
$data = SignupGuard::cachedData(sys_get_temp_dir() . '/signup-guard-data.php');
|
|
332
|
+
|
|
333
|
+
$result = SignupGuard::assessSignup(['email' => 'temp123@mailinator.com', 'ip' => '81.2.69.142'], ['data' => $data]);
|
|
334
|
+
echo $result['decision'], ' ', $result['score'], "\n"; // block 70
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
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.
|
|
338
|
+
|
|
339
|
+
## How it works
|
|
340
|
+
|
|
341
|
+
1. `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.
|
|
342
|
+
2. `normalizeEmail` trims ASCII whitespace, rejects anything that is not a plain ASCII address, lowercases, then applies the documented provider rules: subdomain tags, domain aliases, `+tags`, dots.
|
|
343
|
+
3. `checkDisposable` takes the domain and tests it and each parent domain (never the bare TLD) against your allow list, your block list, then the snapshot.
|
|
344
|
+
4. `lookupIp` parses 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.
|
|
345
|
+
5. 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.
|
|
346
|
+
6. `assessSignup` turns 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.
|
|
347
|
+
7. 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.
|
|
348
|
+
|
|
349
|
+
## False positives and other pitfalls
|
|
350
|
+
|
|
351
|
+
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.
|
|
352
|
+
|
|
353
|
+
- **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-IP` behind Cloudflare), and never trust `X-Forwarded-For` from the open internet. If many users show up with `ip_not_public`, this is why.
|
|
354
|
+
- **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.
|
|
355
|
+
- **Universities, offices, hotels.** One /24 can be a whole campus. The default `network-day` limit is 50 for that reason; raise it if your audience is students.
|
|
356
|
+
- **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 `network` key groups by /64.
|
|
357
|
+
- **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](https://moonetix.com/academy/traffic-quality/vpn-proxy-detected-offerwall).
|
|
358
|
+
- **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.
|
|
359
|
+
- **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`, not `block`, for that reason.
|
|
360
|
+
- **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?](https://moonetix.com/academy/glossary/what-is-a-residential-proxy).
|
|
361
|
+
- **The disposable list is not perfect.** The maintainers say they cannot guarantee every entry is still disposable. Keep `allowDomains` for the ones your users prove wrong, and `blockDomains` for new ones you find.
|
|
362
|
+
- **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.
|
|
363
|
+
- **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.
|
|
364
|
+
- **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.
|
|
365
|
+
- **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`.
|
|
366
|
+
|
|
367
|
+
[What is IP reputation?](https://moonetix.com/academy/glossary/what-is-ip-reputation) covers shared addresses and fair handling in more depth.
|
|
368
|
+
|
|
369
|
+
## What signup-guard does not do
|
|
370
|
+
|
|
371
|
+
- **No device fingerprinting.** It reads an email address and an IP address, and anything else only if you pass it as a velocity field.
|
|
372
|
+
- **No network calls at runtime.** Every check is local. Downloads happen only in the update script, on your schedule.
|
|
373
|
+
- **No MX or SMTP checks.** They are slow, they fail during DNS outages, and a working inbox proves little. Send a verification email instead.
|
|
374
|
+
- **No bot challenge.** Use Turnstile, hCaptcha or reCAPTCHA, verified on your server, for the `review` band.
|
|
375
|
+
- **No machine learning.** Weights are integers in a table you can read and change.
|
|
376
|
+
|
|
377
|
+
## Common errors
|
|
378
|
+
|
|
379
|
+
| You see | Cause and fix |
|
|
380
|
+
| --- | --- |
|
|
381
|
+
| `velocity must be the result of VelocityLimiter.check()` | In Node, `check()` is async and you passed the Promise. `await` it first. |
|
|
382
|
+
| `now must be a non-negative integer (Unix seconds)` | `now` is missing or not an integer. Use `Math.floor(Date.now() / 1000)` or `time()`. |
|
|
383
|
+
| 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. |
|
|
384
|
+
| `Unknown reason code "..."` | `weights` accepts only the codes in the table above, plus `velocity_<yourkey>` and `velocity_other`. |
|
|
385
|
+
| `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`. |
|
|
386
|
+
| `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. |
|
|
387
|
+
| `Cannot write /path/to/cache.php` (PHP) | `cachedData()` could not write next to the cache file. Use a directory the PHP-FPM user owns. |
|
|
388
|
+
| `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. |
|
|
389
|
+
|
|
390
|
+
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.
|
|
391
|
+
|
|
392
|
+
## Tests
|
|
393
|
+
|
|
394
|
+
```bash
|
|
395
|
+
npm test # node --test: shared vectors, API tests, checks on the bundled snapshot
|
|
396
|
+
php php/tests/run.php # shared vectors, PHP-specific checks, the same snapshot checks
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
`test-vectors/vectors.json` holds 204 cases: email syntax and provider rules, 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.
|
|
400
|
+
|
|
401
|
+
`npm run site` builds the [demo page](https://moonetix.github.io/signup-guard/) 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.
|
|
402
|
+
|
|
403
|
+
## Further reading
|
|
404
|
+
|
|
405
|
+
- Moonetix Academy: [How to stop fake signups](https://moonetix.com/academy/traffic-quality/stop-fake-signups-rewards-site), [Stop multi-accounting and VPN abuse](https://moonetix.com/academy/traffic-quality/stop-multi-accounting-vpn-abuse), [What is IP reputation?](https://moonetix.com/academy/glossary/what-is-ip-reputation), [What is a residential proxy?](https://moonetix.com/academy/glossary/what-is-a-residential-proxy), [VPN or proxy detected](https://moonetix.com/academy/traffic-quality/vpn-proxy-detected-offerwall), [How to prevent referral fraud](https://moonetix.com/academy/traffic-quality/prevent-referral-fraud)
|
|
406
|
+
- Data: [moonetix/datacenter-ip-ranges](https://github.com/moonetix/datacenter-ip-ranges), [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains)
|
|
407
|
+
|
|
408
|
+
## About Moonetix
|
|
409
|
+
|
|
410
|
+
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.
|
|
411
|
+
|
|
412
|
+
Other open source from Moonetix: [reward-economy-kit](https://github.com/moonetix/reward-economy-kit), [country-tiers](https://github.com/moonetix/country-tiers), [datacenter-ip-ranges](https://github.com/moonetix/datacenter-ip-ranges), [offerwall-fraud-playbook](https://github.com/moonetix/offerwall-fraud-playbook), [referral-engine](https://github.com/moonetix/referral-engine), [gamification-kit](https://github.com/moonetix/gamification-kit), [awesome-offerwalls](https://github.com/moonetix/awesome-offerwalls), [offerwall-postback-handlers](https://github.com/moonetix/offerwall-postback-handlers).
|
|
413
|
+
|
|
414
|
+
## License
|
|
415
|
+
|
|
416
|
+
MIT. See [LICENSE](LICENSE). The vendored data keeps its own terms, listed in [data/SOURCES.md](data/SOURCES.md).
|
package/data/SOURCES.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Data sources
|
|
2
|
+
|
|
3
|
+
This folder is a snapshot of two upstream lists. `scripts/update-data.mjs` refreshes it every week and rewrites this file only when the data changes.
|
|
4
|
+
|
|
5
|
+
## Disposable email domains
|
|
6
|
+
|
|
7
|
+
| | |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| Source | [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains), `disposable_email_blocklist.conf` |
|
|
10
|
+
| License | CC0 1.0 Universal, see [disposable/LICENSE.txt](disposable/LICENSE.txt) |
|
|
11
|
+
| Commit | [`3cb930c9fdbb`](https://github.com/disposable-email-domains/disposable-email-domains/commit/3cb930c9fdbbc271d8dd84709bb6bc9364f629d8) |
|
|
12
|
+
| Updated | 2026-11-16T06:47:20Z |
|
|
13
|
+
| Domains | 10274 |
|
|
14
|
+
|
|
15
|
+
Entries are registrable domains (or the third level under a public suffix). A listed domain also matches its subdomains. Upstream notes that it cannot guarantee every entry is still disposable, so keep your own allow list.
|
|
16
|
+
|
|
17
|
+
## IP ranges
|
|
18
|
+
|
|
19
|
+
| | |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| Source | [moonetix/datacenter-ip-ranges](https://github.com/moonetix/datacenter-ip-ranges), `data/providers/*.txt` |
|
|
22
|
+
| License | MIT for the repository; feed terms per provider in ip/providers.json |
|
|
23
|
+
| Commit | [`5da0eaab3cdf`](https://github.com/moonetix/datacenter-ip-ranges/commit/5da0eaab3cdf7dba0e5b9a7eb7dd0352e221d1f4) |
|
|
24
|
+
| Updated | 2026-11-16T06:47:20Z |
|
|
25
|
+
| Ranges | 12034 IPv4, 15740 IPv6 |
|
|
26
|
+
|
|
27
|
+
| Provider | File | Category | IPv4 | IPv6 | Terms |
|
|
28
|
+
| --- | --- | --- | ---: | ---: | --- |
|
|
29
|
+
| Amazon Web Services | `aws` | cloud | 1752 | 2363 | Published by AWS for allow lists and filtering. No license is stated. |
|
|
30
|
+
| Google Cloud | `google-cloud` | cloud | 467 | 28 | Published by Google for allow lists and filtering. No license is stated. |
|
|
31
|
+
| Google services (excluding Google Cloud) | `google-services` | services | 297 | 98 | Published by Google for allow lists and filtering. No license is stated. |
|
|
32
|
+
| Oracle Cloud Infrastructure | `oracle-cloud` | cloud | 809 | 0 | Published by Oracle in its public documentation. No license is stated. |
|
|
33
|
+
| DigitalOcean | `digitalocean` | cloud | 187 | 54 | Self-published RFC 8805 geofeed, linked from the DigitalOcean docs. No license is stated. |
|
|
34
|
+
| Akamai Cloud (Linode) | `linode` | cloud | 240 | 39 | Self-published RFC 8805 geofeed, referenced in the Linode network records at ARIN. No license is stated. |
|
|
35
|
+
| Vultr | `vultr` | cloud | 121 | 21 | Self-published RFC 8805 geofeed of AS20473, referenced in the Vultr network records at ARIN. No license is stated. |
|
|
36
|
+
| Cloudflare | `cloudflare` | cdn | 15 | 7 | Published by Cloudflare for allow lists. No license is stated. |
|
|
37
|
+
| Fastly | `fastly` | cdn | 21 | 3 | Public, unauthenticated Fastly API endpoint. No license is stated. |
|
|
38
|
+
| GitHub (incl. Actions runners) | `github` | services | 4025 | 2547 | GitHub REST API, covered by the GitHub Terms of Service (API Terms). |
|
|
39
|
+
| iCloud Private Relay egress | `icloud-private-relay` | privacy-relay | 3414 | 10580 | Published by Apple for geolocation and server operators. No license is stated. |
|
|
40
|
+
| Tor exit nodes | `tor` | tor | 686 | 0 | Tor Project data, CC0 1.0 (no copyright). |
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
CC0 1.0 Universal (CC0 1.0)
|
|
2
|
+
Public Domain Dedication
|
|
3
|
+
|
|
4
|
+
No Copyright
|
|
5
|
+
|
|
6
|
+
The person who associated a work with this deed has dedicated
|
|
7
|
+
the work to the public domain by waiving all of his or her rights
|
|
8
|
+
to the work worldwide under copyright law, including all related
|
|
9
|
+
and neighboring rights, to the extent allowed by law.
|
|
10
|
+
|
|
11
|
+
You can copy, modify, distribute and perform the work, even
|
|
12
|
+
for commercial purposes, all without asking permission.
|
|
13
|
+
|
|
14
|
+
Details: https://creativecommons.org/publicdomain/zero/1.0/legalcode
|