@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 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** — ~680 known disposable email providers (hardcoded, zero network calls)
8
- - **MX record validation** — Optional DNS lookup to verify the domain can receive mail
9
- - **Fail-open DNS** — Transient DNS errors allow the request through (only blocks definitive failures)
10
- - **Zero dependencies** — Uses Node.js built-in `dns/promises`
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('tempmail.com') // true
88
- DISPOSABLE_DOMAINS.size // ~680
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
- 13 tests across 2 files.
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
@@ -1 +1 @@
1
- {"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAqqB1B,CAAC"}
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"}