🛡️ Supabase Auth 邮件网关
为 Supabase Auth 邮件添加 发送前网关检查
检查地址格式并查询收件人域名 MX。离线 MIT 许可静态一次性域名列表(明确加入 tempmail.com)中的完整/子域名匹配、受限域名,以及与现有收件人域名威胁特征的匹配会被硬拦截。MX 查询失败和垃圾邮件陷阱/信誉启发式 HIGH 警告仅提示并放行;不进行实时陷阱查询。
邮箱验证 · 每月 100 次免费请求(验证与发送共用)· 无需信用卡
身份验证邮件 / 受控发送
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
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) => ({
"&": "&", "<": "<", ">": ">",
'"': """, "'": "'",
})[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 封
- 免费密钥只能向密钥所有者本人已验证的邮箱发送。