Anti-abuse
What blocks fake signups, and how to tune it.
What you need to do
Most protection is on by default. Your part:
- Rate limits apply automatically (10 joins per IP per minute; see
errors and rate limits). Make sure
TRUSTED_IP_HEADERnames a header your host sets (production checklist). - Captcha is opt-in per waitlist: set
settings.captcha_required: true, configureTURNSTILE_SECRET_KEY, render the Turnstile widget and pass its token ascaptchaToken(captcha_tokenin the raw API). - Double opt-in (default) stops other people's addresses and keeps referral credit honest: only confirmed referrals count.
- Allowed origins on the project keep other websites from using your key in their visitors' browsers.
- Review blocked and flagged attempts on the project page in the dashboard (counts by reason, never addresses).
Blocked joins always look the same to the caller (422 abuse_blocked) so
attackers learn nothing about which rule fired. A legitimate visitor who is
blocked should be told to try another address or solve the captcha.
How it works
Join requests pass through ordered guards before anything is stored. Each
guard returns allow, deny(reason) or flag(reason). The first deny
stops the join; every deny and flag writes one abuse_events row
(outcome = block / flag).
Order
- Rate limit (route level, step 1.3)
captchadisposable_email- Alias normalization (
ALIAS_EMAIL_POLICY) mx(sees the alias-collapsed address)
Client-visible behavior
A deny is always 422 abuse_blocked with the generic message
"Request blocked by abuse protection". The rule that fired is never
returned; it is only in abuse_events.check / detail.reason, and is
surfaced to the project owner in 3.4. Guards run before the
existing-signup lookup, so a repeat join is checked like a first one.
Audit rows contain no raw PII
detail holds reason, email_hash (sha256 of waitlist id + normalized
email, truncated to 32 hex chars), email_domain, and guard extras (e.g.
matched_domain, captcha error_codes). Never the address, IP or token.
The hash is unkeyed: pseudonymous, not anonymous, and a guessed address can
be confirmed by someone with database access.
Audit-write failures are logged and never block a join.
Checks and failure modes
| Check | Denies when | Dependency fails | Reasons |
|---|---|---|---|
captcha | captcha_required and token missing/invalid | Fail closed: deny | captcha_missing, captcha_invalid, captcha_timeout, captcha_unavailable, captcha_not_configured |
disposable_email | domain or any parent is in the list | none (offline list) | disposable_domain |
mx | no MX and no A/AAAA, or null MX (RFC 7505) | Fail open: allow + flag | no_mail_server; flags dns_timeout, dns_error |
Captcha (captcha_token in the join body, max 2048 chars). Skipped
entirely when the waitlist does not require it. Turnstile siteverify is a
fixed URL, 3s timeout, no redirects. It fails closed because failing open
would let a bot bypass the captcha by waiting for an outage. If
TURNSTILE_SECRET_KEY is unset, waitlists requiring captcha deny all joins.
Tokens are single use; Cloudflare rejects replays.
Disposable list: packages/shared/src/disposable-email/ (CC0, vendored,
never fetched at runtime; update procedure in its README). Matching is on
label boundaries, so x.mailinator.com matches but notmailinator.com
does not. IDN domains are matched in punycode.
MX: 2s timeout per lookup via node:dns/promises. Only definitive
verdicts (deliverable / undeliverable) are cached for 5 minutes, in a
bounded per-process cache behind TtlCache (swap for a shared one later).
Resolver errors are never cached.
Alias normalization (email_normalized): Gmail/Googlemail lose dots and
case and googlemail.com becomes gmail.com; every provider loses +tag
(configurable via EmailPolicy: stripPlusTag, keepPlusTagDomains,
dotInsensitiveDomains). A +tag that would empty the local part or leave a
trailing dot is kept. email_original is stored as typed.
Known gaps
- Rows created before 1.4 keep their old
email_normalized, so an alias of an old signup can join once more. - Denied attempts each write an event row; they are pruned after 90 days
(see
docs/privacy.md). - The MX cache is per instance.