@bitclaw/disposable-email 1.2.0 → 1.2.2
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/README.md +59 -5
- package/dist/domains.d.ts.map +1 -1
- package/dist/domains.js +19 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -4,11 +4,35 @@ Email validation against disposable/temporary email providers with optional DNS
|
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
- **Disposable domain blocklist** - ~
|
|
7
|
+
- **Disposable domain blocklist** - ~8,200 known disposable email providers, generated from a
|
|
8
|
+
maintained community source (zero network calls to check)
|
|
9
|
+
- **MX host detection** - Optional check that catches rotating-alias domains (services like
|
|
10
|
+
10minutemail.com that assign a fresh random domain per inbox) by matching the backend mail
|
|
11
|
+
server instead of the domain name
|
|
8
12
|
- **MX record validation** - Optional DNS lookup to verify the domain can receive mail
|
|
9
13
|
- **Fail-open DNS** - Transient DNS errors allow the request through (only blocks definitive failures)
|
|
10
14
|
- **Zero dependencies** - Uses Node.js built-in `dns/promises`
|
|
11
15
|
|
|
16
|
+
### Why two blocklists: domain names vs. MX hosts
|
|
17
|
+
|
|
18
|
+
A domain blocklist only catches services a scraper has already discovered. It can never catch a
|
|
19
|
+
*rotating-alias* service, where every signup gets a new, previously-unseen domain (e.g.
|
|
20
|
+
`10minutemail.com` handed out `vtmpj.net` for one inbox). Those domains aren't predictable, so no
|
|
21
|
+
static list, however well maintained, can enumerate them in advance.
|
|
22
|
+
|
|
23
|
+
What *is* stable is the backend infrastructure: rotating-alias services still route all that mail
|
|
24
|
+
through the same small set of MX servers, because standing up new mail infrastructure is
|
|
25
|
+
expensive while registering a new domain is nearly free. `DISPOSABLE_MX_HOSTS` in `src/mx-hosts.ts`
|
|
26
|
+
matches on that instead. It's checked only when `checkMx: true` is passed to `validateEmailDomain`,
|
|
27
|
+
since it requires a live DNS lookup.
|
|
28
|
+
|
|
29
|
+
**Every entry in `DISPOSABLE_MX_HOSTS` was verified with a live `dig MX <domain>` lookup before
|
|
30
|
+
being added, and hosts shared with real mail providers are deliberately excluded.** Some
|
|
31
|
+
temp-mail-flavored domains actually route through general-purpose providers (e.g. `mx.yandex.net`,
|
|
32
|
+
`protonmail.ch`) - blocking those would false-positive real users of that provider, not just the
|
|
33
|
+
disposable service. Don't add a speculative or unverified hostname to this list; verify it's
|
|
34
|
+
dedicated infrastructure for the disposable service first.
|
|
35
|
+
|
|
12
36
|
## Installation
|
|
13
37
|
|
|
14
38
|
```bash
|
|
@@ -84,23 +108,53 @@ The raw domain blocklist, exported for direct access if needed:
|
|
|
84
108
|
```typescript
|
|
85
109
|
import { DISPOSABLE_DOMAINS } from '@bitclaw/disposable-email'
|
|
86
110
|
|
|
87
|
-
DISPOSABLE_DOMAINS.has('
|
|
88
|
-
DISPOSABLE_DOMAINS.size
|
|
111
|
+
DISPOSABLE_DOMAINS.has('mailinator.com') // true
|
|
112
|
+
DISPOSABLE_DOMAINS.size // ~8,200
|
|
89
113
|
```
|
|
90
114
|
|
|
115
|
+
Regenerated from the [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains)
|
|
116
|
+
community CC0 blocklist via `bun run sync-domains`. It overwrites `src/domains.ts`.
|
|
117
|
+
|
|
118
|
+
A weekly GitHub Actions workflow (`.github/workflows/sync-domains.yml`) runs this automatically
|
|
119
|
+
and opens a PR if the list changed, so it doesn't drift the way the old hand-maintained list did.
|
|
120
|
+
|
|
121
|
+
### `DISPOSABLE_MX_HOSTS: ReadonlySet<string>`
|
|
122
|
+
|
|
123
|
+
Curated set of MX hostnames belonging to rotating-alias disposable-mail services, exported for
|
|
124
|
+
direct access:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
import { DISPOSABLE_MX_HOSTS } from '@bitclaw/disposable-email'
|
|
128
|
+
|
|
129
|
+
DISPOSABLE_MX_HOSTS.has('prd-smtp.10minutemail.com') // true
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
This list is hand-curated, not scraped, precisely because each entry needs to be verified as
|
|
133
|
+
dedicated infrastructure (see "Why two blocklists" above) before it's safe to block on.
|
|
134
|
+
|
|
91
135
|
## DNS Error Handling
|
|
92
136
|
|
|
93
137
|
| DNS Result | Behavior |
|
|
94
138
|
|-----------|----------|
|
|
95
|
-
| MX records found | `{ valid: true }` |
|
|
139
|
+
| MX records found, host not in `DISPOSABLE_MX_HOSTS` | `{ valid: true }` |
|
|
140
|
+
| MX records found, host in `DISPOSABLE_MX_HOSTS` | `{ valid: false, reason: 'disposable' }` |
|
|
96
141
|
| ENOTFOUND / ENODATA | `{ valid: false, reason: 'no-mx-records' }` |
|
|
97
142
|
| Timeout | `{ valid: false, reason: 'dns-error' }` |
|
|
98
143
|
| Other DNS error | `{ valid: true }` (fail-open) |
|
|
99
144
|
|
|
145
|
+
## Design note: why `isDisposableEmail` never does a DNS lookup
|
|
146
|
+
|
|
147
|
+
`isDisposableEmail` is synchronous and network-free by design, so callers can use it as an
|
|
148
|
+
unconditional gate (e.g. on every OTP send) without adding an external DNS round-trip to the
|
|
149
|
+
critical path of login/signup. The MX-host check needs a live DNS lookup, so it only lives in
|
|
150
|
+
`validateEmailDomain`'s opt-in `checkMx` path. If you need rotating-alias detection on every
|
|
151
|
+
request, call `validateEmailDomain(email, { checkMx: true })` there deliberately, understanding
|
|
152
|
+
you're accepting DNS latency and the fail-open behavior above.
|
|
153
|
+
|
|
100
154
|
## Testing
|
|
101
155
|
|
|
102
156
|
```bash
|
|
103
157
|
bun test
|
|
104
158
|
```
|
|
105
159
|
|
|
106
|
-
|
|
160
|
+
15 tests across 2 files.
|
package/dist/domains.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,
|
|
1
|
+
{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CA0gQjD,CAAC"}
|
package/dist/domains.js
CHANGED
|
@@ -514,6 +514,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
514
514
|
'aidesign.work.gd',
|
|
515
515
|
'aidesigner.2bd.net',
|
|
516
516
|
'aifmusic.top',
|
|
517
|
+
'aihubtools.space',
|
|
517
518
|
'aikunkun.com',
|
|
518
519
|
'ailicke.com',
|
|
519
520
|
'aineapi.com',
|
|
@@ -1618,6 +1619,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
1618
1619
|
'coza.ro',
|
|
1619
1620
|
'cozilla.pw',
|
|
1620
1621
|
'cpc.cx',
|
|
1622
|
+
'cqwbn.com',
|
|
1621
1623
|
'crankhole.com',
|
|
1622
1624
|
'crapmail.org',
|
|
1623
1625
|
'crastination.de',
|
|
@@ -2518,6 +2520,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
2518
2520
|
'faxzu.com',
|
|
2519
2521
|
'faybetsy.com',
|
|
2520
2522
|
'fazka.ovh',
|
|
2523
|
+
'fbfbs.lol',
|
|
2521
2524
|
'fbhotro.com',
|
|
2522
2525
|
'fbi.one',
|
|
2523
2526
|
'fbins001mail.com',
|
|
@@ -2714,6 +2717,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
2714
2717
|
'friday12.store',
|
|
2715
2718
|
'friendlymail.co.uk',
|
|
2716
2719
|
'friendsofbram.com',
|
|
2720
|
+
'frive.site',
|
|
2717
2721
|
'frm.ovh',
|
|
2718
2722
|
'front14.org',
|
|
2719
2723
|
'frostmail.fr.nf',
|
|
@@ -2770,6 +2774,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
2770
2774
|
'fviamail.work',
|
|
2771
2775
|
'fxavaj.com',
|
|
2772
2776
|
'fxnxs.com',
|
|
2777
|
+
'fxt.ink',
|
|
2773
2778
|
'fxtubes.com',
|
|
2774
2779
|
'fxxf.beer',
|
|
2775
2780
|
'fxzig.com',
|
|
@@ -3428,6 +3433,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
3428
3433
|
'http.nyc.mn',
|
|
3429
3434
|
'httpsgreenwichmeantime.in',
|
|
3430
3435
|
'huage.me',
|
|
3436
|
+
'hualabtech.com',
|
|
3431
3437
|
'huangao.xyz',
|
|
3432
3438
|
'huangniu8.com',
|
|
3433
3439
|
'hubglee.com',
|
|
@@ -3464,6 +3470,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
3464
3470
|
'hwsye.net',
|
|
3465
3471
|
'hxopi.ru',
|
|
3466
3472
|
'hxopi.store',
|
|
3473
|
+
'hygle.net',
|
|
3467
3474
|
'hyhotmail.ccwu.cc',
|
|
3468
3475
|
'hymenjj.cfd',
|
|
3469
3476
|
'hypenated-domain.com',
|
|
@@ -3521,6 +3528,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
3521
3528
|
'ikewe.com',
|
|
3522
3529
|
'ikomail.com',
|
|
3523
3530
|
'ikuromi.com',
|
|
3531
|
+
'ilcvn.cn',
|
|
3524
3532
|
'illistnoise.com',
|
|
3525
3533
|
'illnessth.com',
|
|
3526
3534
|
'illubd.com',
|
|
@@ -4684,6 +4692,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
4684
4692
|
'mgxianlu.gq',
|
|
4685
4693
|
'mhzayt.online',
|
|
4686
4694
|
'miaferrari.com',
|
|
4695
|
+
'mianfeibuluo.com',
|
|
4687
4696
|
'miauj.com',
|
|
4688
4697
|
'michaeladmin.eu',
|
|
4689
4698
|
'michaeladmin.fr',
|
|
@@ -4770,6 +4779,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
4770
4779
|
'mockata.net',
|
|
4771
4780
|
'mockmyid.com',
|
|
4772
4781
|
'modirosa.com',
|
|
4782
|
+
'modolku.store',
|
|
4773
4783
|
'moeri.org',
|
|
4774
4784
|
'mofu.be',
|
|
4775
4785
|
'mohmal.com',
|
|
@@ -5059,6 +5069,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
5059
5069
|
'naah.ru',
|
|
5060
5070
|
'naah.store',
|
|
5061
5071
|
'nabaxox.edu.pl',
|
|
5072
|
+
'nabilalo.bond',
|
|
5062
5073
|
'nabomail.com',
|
|
5063
5074
|
'nabuma.com',
|
|
5064
5075
|
'nada.email',
|
|
@@ -6107,6 +6118,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
6107
6118
|
'sackboii.com',
|
|
6108
6119
|
'sad23321adja.cn',
|
|
6109
6120
|
'sada-sd.cc',
|
|
6121
|
+
'saddope.lol',
|
|
6110
6122
|
'sadfg.indevs.in',
|
|
6111
6123
|
'sadrain.shop',
|
|
6112
6124
|
'sads-ads-awe.top',
|
|
@@ -6371,6 +6383,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
6371
6383
|
'skygazer42.cn',
|
|
6372
6384
|
'skygazerhub.com',
|
|
6373
6385
|
'skyhope666.icu',
|
|
6386
|
+
'skyhopenb.shop',
|
|
6374
6387
|
'skynet.infos.st',
|
|
6375
6388
|
'skyrt.de',
|
|
6376
6389
|
'skytopway.com',
|
|
@@ -6491,6 +6504,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
6491
6504
|
'spacebazzar.ru',
|
|
6492
6505
|
'spacehotline.com',
|
|
6493
6506
|
'spacework.top',
|
|
6507
|
+
'spacexyz.space',
|
|
6494
6508
|
'spacezin.space',
|
|
6495
6509
|
'spam-be-gone.com',
|
|
6496
6510
|
'spam.care',
|
|
@@ -7576,6 +7590,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
7576
7590
|
'vps911.net',
|
|
7577
7591
|
'vradportal.com',
|
|
7578
7592
|
'vremonte24-store.ru',
|
|
7593
|
+
'vrjxk.com',
|
|
7579
7594
|
'vrmtr.com',
|
|
7580
7595
|
'vsdsd23gsdf.shop',
|
|
7581
7596
|
'vsimcard.com',
|
|
@@ -7668,6 +7683,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
7668
7683
|
'wee.my',
|
|
7669
7684
|
'weekfly.com',
|
|
7670
7685
|
'weekzs.icu',
|
|
7686
|
+
'weeline.fun',
|
|
7671
7687
|
'wef.gr',
|
|
7672
7688
|
'weg-werf-email.de',
|
|
7673
7689
|
'wegoo.dpdns.org',
|
|
@@ -7755,6 +7771,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
7755
7771
|
'wmail.cf',
|
|
7756
7772
|
'wmail.club',
|
|
7757
7773
|
'wmct.info',
|
|
7774
|
+
'wmksuhd.cn',
|
|
7758
7775
|
'wnbaldwy.com',
|
|
7759
7776
|
'wohbc.co.uk',
|
|
7760
7777
|
'wokcy.com',
|
|
@@ -7774,6 +7791,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
7774
7791
|
'wpdork.com',
|
|
7775
7792
|
'wpg.im',
|
|
7776
7793
|
'wralawfirm.com',
|
|
7794
|
+
'wrgee.com',
|
|
7777
7795
|
'writeme.us',
|
|
7778
7796
|
'wronghead.com',
|
|
7779
7797
|
'wrqj.top',
|
|
@@ -7901,6 +7919,7 @@ export const DISPOSABLE_DOMAINS = new Set([
|
|
|
7901
7919
|
'xsnipersquad.site',
|
|
7902
7920
|
'xsnipersquad.space',
|
|
7903
7921
|
'xstyled.net',
|
|
7922
|
+
'xswl.xyz',
|
|
7904
7923
|
'xvx.us',
|
|
7905
7924
|
'xww.ro',
|
|
7906
7925
|
'xxhamsterxx.ga',
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bitclaw/disposable-email",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.2",
|
|
4
4
|
"description": "Fast disposable and free email provider detection with optional MX record validation",
|
|
5
5
|
"files": [
|
|
6
6
|
"dist",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
"lint:fix": "biome check --write",
|
|
26
26
|
"format": "biome format --write",
|
|
27
27
|
"knip": "knip",
|
|
28
|
+
"sync-domains": "bun scripts/sync-domains.ts",
|
|
28
29
|
"prepublishOnly": "npm run build && npm run test",
|
|
29
30
|
"publish:dev": "npm run build && npm publish --tag dev --access public",
|
|
30
31
|
"publish:patch": "npm whoami && npm version patch && git push --follow-tags && npm publish --access public",
|