🛡️ Supabase Auth 邮件网关

为 Supabase Auth 邮件添加 发送前网关检查

检查地址格式并查询收件人域名 MX。离线 MIT 许可静态一次性域名列表(明确加入 tempmail.com)中的完整/子域名匹配、受限域名,以及与现有收件人域名威胁特征的匹配会被硬拦截。MX 查询失败和垃圾邮件陷阱/信誉启发式 HIGH 警告仅提示并放行;不进行实时陷阱查询。

邮箱验证 · 每月 100 次免费请求(验证与发送共用)· 无需信用卡

delivery-path.trace发送前检查已启用

身份验证邮件 / 受控发送

01
Supabase Auth注册 · OTP · 账户恢复
02
SentriSend 发送前网关收件人验证 · 限制等待时间 · 故障时继续发送
03
已配置的邮件服务商已验证签名的钩子通过你自己的服务商发送
✓Supabase Auth → SentriSend 发送前网关 → 已配置的邮件服务商

01 / 故障情形

格式正确的地址仍可能无法投递。

Supabase Auth 会触发邮件发送。SentriSend 检查地址格式并查询收件人域名 MX。MX 缺失、无效或暂时无法查询时仅提示并放行,不验证邮箱是否存在。离线 MIT 许可静态一次性域名列表(明确加入 tempmail.com)中的完整/子域名匹配、受限域名,以及与现有收件人域名威胁特征的匹配会被硬拦截。垃圾邮件陷阱/信誉启发式 HIGH 警告仅提示并放行;不进行实时陷阱查询,也不探测 SMTP 收件人。实际投递情况请在服务商处查看。

  • 检查地址格式并查询收件人域名 MX(不验证邮箱)。
  • 硬拦截离线一次性域名列表(明确加入 tempmail.com)中的完整/子域名匹配、受限域名及与现有收件人域名威胁特征的匹配。
  • 垃圾邮件陷阱/信誉启发式 HIGH 警告会放行;不进行实时陷阱查询或 SMTP 收件人探测。

02 / 集成

验证钩子签名,检查收件人,只发送一次。

这个 Next.js 邮件发送钩子先用 standardwebhooks 验证 Supabase 原始请求的签名,再调用 POST /api/v1/validate。AbortSignal 限制验证等待时间,但不保证响应时间。验证 API 区分一次性域名、不存在的域名,以及既无 MX 又无可用 A 记录的域名。A 记录回退仅检查 DNS;Null MX(明确声明不接收邮件)会被拒绝,而暂时性 DNS 故障以 DNS_INCONCLUSIVE 和 MEDIUM 风险放行。钩子仅在明确的验证响应中 allowed === false 时拒绝;输入错误、配额耗尽、服务器错误、无效 JSON 和超时均继续交给邮件服务商发送。服务商发送包含 token_hash 链接、token 验证码或两者的邮件,不进行 SMTP 服务器或邮箱探测。

安装 standardwebhooks,并将此路由配置为 Supabase Send Email Hook。在服务器端设置 SEND_EMAIL_HOOK_SECRET、SENTRISEND_API_KEY 和 RESEND_API_KEY,设置链接所需的 NEXT_PUBLIC_SUPABASE_URL 与 NEXT_PUBLIC_SITE_URL。将示例发件人替换为已验证的域名。秘密信息切勿使用 NEXT_PUBLIC_ 前缀。启用 Supabase 原生速率限制和 Cloudflare Turnstile。自动化测试使用模拟的 Hook 请求。此示例尚未在真实的 Supabase 项目中进行端到端验证。
pages/api/auth/supabase-hook.ts
// pages/api/auth/supabase-hook.ts
import type { NextApiRequest, NextApiResponse } from "next";
import { Webhook } from "standardwebhooks";

// Preserve the raw body for signature verification.
// App Router equivalent: await req.text().
export const config = { api: { bodyParser: false } };

const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const SUBJECT_MAP: Record<string, string> = {
  signup: "Verify your account",
  recovery: "Reset your password",
  magiclink: "Your magic login link",
  reauthentication: "Confirm your identity",
};
const SUPPORTED_TYPES = new Set(Object.keys(SUBJECT_MAP));

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  if (req.method !== "POST") return res.status(405).end();

  // Authenticate Supabase before any validation or email delivery.
  let payload: any;
  try {
    const rawBody = (await getRawBody(req)).toString("utf8");
    const secret = (process.env.SEND_EMAIL_HOOK_SECRET || "")
      .replace(/^v1,whsec_/, "");
    payload = new Webhook(secret).verify(
      rawBody, req.headers as Record<string, string>,
    );
  } catch {
    return res.status(401).json({
      error: { http_code: 401, message: "Invalid webhook signature" },
    });
  }

  const { user, email_data } = payload;
  const email = user?.email;
  const token = email_data?.token;
  const tokenHash = email_data?.token_hash;
  const redirectTo = email_data?.redirect_to
    || process.env.NEXT_PUBLIC_SITE_URL || "";
  const type = email_data?.email_action_type || "signup";

  if (typeof email !== "string"
    || !EMAIL_REGEX.test(email) || email.length > 254) {
    return res.status(400).json({
      error: { http_code: 400, message: "Invalid recipient address" },
    });
  }
  if (!SUPPORTED_TYPES.has(type)) {
    return res.status(400).json({
      error: { http_code: 400, message: "Unsupported auth action type" },
    });
  }

  // Validation only: delivery stays with your upstream provider.
  // Enable Supabase native rate limits and Cloudflare Turnstile.
  try {
    const check = await fetch(
      "https://sentrisend.com/api/v1/validate",
      {
        method: "POST",
        signal: AbortSignal.timeout(600),
        headers: {
          Authorization: `Bearer ${process.env.SENTRISEND_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ email }),
      },
    );
    // 429, 5xx, malformed JSON, and timeouts fail open.
    // Only a validation response can intentionally reject the user.
    if (check.ok || check.status === 400) {
      const data = await check.json().catch(() => ({}));
      if (data.allowed === false) {
        return res.status(400).json({
          error: {
            http_code: 400,
            message: "Unsupported or high-risk email address rejected.",
          },
        });
      }
    }
    if (check.status === 401) {
      console.error("[SentriSend] Invalid SENTRISEND_API_KEY");
    }
  } catch {
    console.warn("[SentriSend] Validation unavailable; failing open");
  }

  try {
    const result = await sendEmailViaProvider({
      email, token, tokenHash, type, redirectTo,
      subject: SUBJECT_MAP[type],
    });
    if (!result.ok) {
      return res.status(502).json({
        error: { http_code: 502, message: "Upstream delivery failed" },
      });
    }
    // Supabase expects an empty JSON object on hook success.
    return res.status(200).json({});
  } catch {
    return res.status(500).json({
      error: { http_code: 500, message: "Internal delivery failure" },
    });
  }
}

function escapeHtml(value: string): string {
  return value.replace(/[&<>"']/g, (char) => ({
    "&": "&amp;", "<": "&lt;", ">": "&gt;",
    '"': "&quot;", "'": "&#39;",
  })[char]!);
}

async function sendEmailViaProvider({
  email, token, tokenHash, type, redirectTo, subject,
}: any) {
  const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL || "";
  let htmlContent = "";
  if (typeof tokenHash === "string" && tokenHash) {
    const params = new URLSearchParams({
      token: tokenHash, type, redirect_to: redirectTo,
    });
    const verifyUrl = `${supabaseUrl}/auth/v1/verify?${params}`;
    htmlContent += `<p><a href="${escapeHtml(verifyUrl)}">Click here to complete authentication</a></p>`;
  }
  if (typeof token === "string" && token) {
    htmlContent += `<p>Or enter this verification code: <strong>${escapeHtml(token)}</strong></p>`;
  }
  if (!htmlContent) return { ok: false };

  const response = await fetch("https://api.resend.com/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RESEND_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from: "Your App <auth@yourdomain.com>",
      to: email, subject, html: htmlContent,
    }),
  });
  return { ok: response.ok };
}

async function getRawBody(req: NextApiRequest): Promise<Buffer> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) {
    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
  }
  return Buffer.concat(chunks);
}

03 / 开始防护

从真实密钥开始,无需销售沟通。

验证你的邮箱,并使用自己的身份验证邮件流量测试网关。

免费密钥

生成免费的 SentriSend API 密钥

每个邮箱地址仅可领取一个免费密钥。所有域名的 + 标签都视为同一地址;只有 Gmail 和 Googlemail 的句点也视为相同。

验证邮箱后即可领取密钥。无需信用卡。

使用限额

  • 每月 100 次请求,验证与发送共用
  • 每个 UTC 日最多发送 10 封
  • 免费密钥只能向密钥所有者本人已验证的邮箱发送。

正在加载安全验证…