Express middleware that blocks fake signups

1. 1. Add the guard helper

   One file, no dependencies, never throws. It blocks only what the table above says to block and lets every unfinished check through.

   // signup-guard.ts: server code only. Needs fetch and AbortSignal.timeout (Node 18+, Deno, Workers, Bun).
   export type Decision = "block" | "warn" | "allow";
   
   export interface Verdict {
     decision: Decision;
     /** Stable SimpleVerifier reason_code, or null when the check didn't finish. */
     reasonCode: string | null;
     /** Message to show the person when decision is "block". */
     message: string | null;
   }
   
   interface Options {
     apiKey?: string;
     /** Keep it under your platform's hook limit. A timeout lets the signup through. */
     timeoutMs?: number;
     /** Log what would be blocked, block nothing. Run this way for a few days first. */
     dryRun?: boolean;
   }
   
   const API_URL = "https://simpleverifier.com/api/v1/verify";
   const WARN_CODES = new Set(["role", "catch_all"]);
   const ALLOW: Verdict = { decision: "allow", reasonCode: null, message: null };
   
   function blockMessage(reasonCode: string, reason: string): string {
     if (reasonCode === "disposable") return "Please use a permanent email address, not a temporary inbox.";
     const hint = reason.match(/did you mean ([^?\s]+)\??/i)?.[1];
     if (hint) return `Check the spelling of your email address. Did you mean ${hint}?`;
     return "This email address can't receive mail. Please check it.";
   }
   
   export async function checkSignupEmail(email: string, options: Options = {}): Promise<Verdict> {
     const { apiKey = process.env.SIMPLEVERIFIER_KEY, timeoutMs = 8000, dryRun = false } = options;
     if (!apiKey) return ALLOW;
   
     let result: { action?: string; reason?: string; reason_code?: string; likely_invented?: boolean };
     try {
       const res = await fetch(API_URL, {
         method: "POST",
         headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
         body: JSON.stringify({ email: email.trim() }),
         signal: AbortSignal.timeout(timeoutMs),
       });
       if (!res.ok) return ALLOW; // 401, 402, 429, 503: fail open
       result = await res.json();
     } catch {
       return ALLOW; // timeout or network error: fail open
     }
   
     const reasonCode = result.reason_code ?? null;
     if (result.action === "do_not_send") {
       const verdict: Verdict = { decision: "block", reasonCode, message: blockMessage(reasonCode ?? "", result.reason ?? "") };
       if (!dryRun) return verdict;
       console.info("[signup-guard] dry run, would block", { reasonCode });
       return { ...verdict, decision: "warn" };
     }
     if (result.likely_invented || (reasonCode && WARN_CODES.has(reasonCode))) {
       return { decision: "warn", reasonCode, message: null };
     }
     return { decision: "allow", reasonCode, message: null };
   }

2. 2. Add the middleware

   Mount it only on routes that create accounts or hand out credits, after the body parser.

   import type { NextFunction, Request, Response } from "express";
   import { checkSignupEmail } from "../signup-guard";
   
   export async function blockFakeSignups(req: Request, res: Response, next: NextFunction) {
     const email = typeof req.body?.email === "string" ? req.body.email : "";
     if (!email) return next(); // let your own validation answer
   
     const verdict = await checkSignupEmail(email, { dryRun: process.env.SIGNUP_GUARD_DRY_RUN === "1" });
     if (verdict.decision === "block") {
       return res.status(422).json({ error: verdict.message, field: "email" });
     }
     res.locals.emailCheck = verdict; // { decision: "warn" | "allow", reasonCode }
     return next();
   }

3. 3. Use it on the sign-up route

   The handler can read res.locals.emailCheck to hold free credits for warn accounts.

   import express from "express";
   import { blockFakeSignups } from "./middleware/blockFakeSignups";
   
   const app = express();
   app.use(express.json());
   app.use(express.urlencoded({ extended: false }));
   
   app.post("/signup", blockFakeSignups, async (req, res) => {
     const { decision, reasonCode } = res.locals.emailCheck ?? { decision: "allow", reasonCode: null };
     // await createUser({ email: req.body.email, emailCheck: decision, emailReason: reasonCode });
     res.status(201).json({ ok: true });
   });
   
   app.listen(3000);

More on calling the API from this stack (retries, status handling, tests): API guide. Every field is described in the API docs.