Email verification in Express

// middleware/verifyEmail.js
const KEY = process.env.ZAPBOUNCE_KEY;

export async function verifyEmail(req, res, next) {
  const { email } = req.body;

  try {
    const response = await fetch("https://api.zapbounce.com/v1/verify", {
      method: "POST",
      headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(2000),   // someone is waiting on a form
    });

    if (!response.ok) throw new Error(`status ${response.status}`);

    const { result, disposable } = await response.json();
    req.emailVerdict = result;

    // disposable is a boolean flag beside the result, never a value of it.
    if (result === "invalid" || disposable) {
      return res.status(422).json({ error: "That address will not receive mail." });
    }
  } catch (err) {
    // Fail open. A verifier having a slow second must not cost you a signup.
    req.log.warn({ err }, "zapbounce unreachable");
    req.emailVerdict = "unknown";
  }

  next();
}

app.post("/signup", express.json(), verifyEmail, async (req, res) => {
  const user = await db.users.create({ email: req.body.email, verdict: req.emailVerdict });
  res.status(201).json({ id: user.id });
});

app.post("/lists/:id/verify", express.json(), async (req, res) => {
  const emails = await db.contacts.pluckEmails(req.params.id);

  const response = await fetch("https://api.zapbounce.com/v1/batches", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      // Stable per list: a double-click on the button must not bill twice.
      "Idempotency-Key": `list-${req.params.id}`,
    },
    body: JSON.stringify({
      name: `list-${req.params.id}`,
      emails,
      webhook_url: `${process.env.PUBLIC_URL}/webhooks/zapbounce`,
    }),
    signal: AbortSignal.timeout(30_000),
  });

  if (!response.ok) {
    const { error } = await response.json();
    return res.status(502).json({ error: error.code, request_id: error.request_id });
  }

  const batch = await response.json();
  await db.lists.update(req.params.id, { batchId: batch.batch_id });

  // 202: accepted, not finished. The webhook will say when it is.
  res.status(202).json({ batch_id: batch.batch_id, unique: batch.unique });
});

import crypto from "node:crypto";

// express.raw() ONLY on this route. Mounting express.json() globally above it
// consumes the stream and the signature can never match again.
app.post(
  "/webhooks/zapbounce",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const header = req.get("ZapBounce-Signature") ?? "";
    const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));

    if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) {
      return res.status(401).send("stale signature");
    }

    const expected = crypto
      .createHmac("sha256", process.env.ZAPBOUNCE_WEBHOOK_SECRET)
      .update(`${parts.t}.`)
      .update(req.body)                 // a Buffer, exactly as sent
      .digest("hex");

    const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
    if (!ok) return res.status(401).send("bad signature");

    const event = JSON.parse(req.body.toString("utf8"));

    // Deliveries repeat. Insert-if-absent makes a replay harmless.
    const fresh = await db.webhookEvents.insertIfAbsent(event.id);
    if (fresh) await queue.add("import-results", { batchId: event.data.batch_id });

    res.sendStatus(204);   // acknowledge fast; import on the worker
  },
);