@bitclaw/disposable-email 1.1.0 → 1.2.1
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 +62 -8
- package/dist/domains.d.ts +0 -5
- package/dist/domains.d.ts.map +1 -1
- package/dist/domains.js +7575 -71
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/mx-hosts.d.ts +14 -0
- package/dist/mx-hosts.d.ts.map +1 -0
- package/dist/mx-hosts.js +26 -0
- package/dist/mx-validator.d.ts.map +1 -1
- package/dist/mx-validator.js +14 -2
- package/package.json +23 -9
package/README.md
CHANGED
|
@@ -4,10 +4,34 @@ Email validation against disposable/temporary email providers with optional DNS
|
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
- **Disposable domain blocklist**
|
|
8
|
-
|
|
9
|
-
- **
|
|
10
|
-
|
|
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
|
|
12
|
+
- **MX record validation** - Optional DNS lookup to verify the domain can receive mail
|
|
13
|
+
- **Fail-open DNS** - Transient DNS errors allow the request through (only blocks definitive failures)
|
|
14
|
+
- **Zero dependencies** - Uses Node.js built-in `dns/promises`
|
|
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.
|
|
11
35
|
|
|
12
36
|
## Installation
|
|
13
37
|
|
|
@@ -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
CHANGED
|
@@ -1,7 +1,2 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Curated set of disposable/temporary email domains.
|
|
3
|
-
* Sources: disposable-email-domains (GitHub), community contributions.
|
|
4
|
-
* Community can add more domains via PRs.
|
|
5
|
-
*/
|
|
6
1
|
export declare const DISPOSABLE_DOMAINS: ReadonlySet<string>;
|
|
7
2
|
//# sourceMappingURL=domains.d.ts.map
|
package/dist/domains.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAu/PjD,CAAC"}
|