Skip to content

Email for professionals and teams

9.3 KB
Raw Blame
import type { ProviderVerdicts } from "@/lib/spam/types";
import type { MessageAuthentication, MessageAuthenticationMethod } from "@/lib/email/authentication-types";
import { isSameOrSubdomain } from "@/lib/email/domain-match";
import { extractSenderIp } from "@/lib/spam/domain-utils";

export type ProviderTrace = { verdicts?: ProviderVerdicts; senderIp?: string };

const HEADER_SCAN_BYTES = 64 * 1024;
/** Headers SES prepends when it accepts a message; the trace ends at the first header it did not write. */
const SES_HEADERS = new Set(["return-path", "received", "received-spf", "authentication-results", "x-ses-receipt", "x-ses-dkim-signature", "x-ses-spam-verdict", "x-ses-virus-verdict"]);

function readHeaderLines(raw: ArrayBuffer): { name: string; value: string }[] {
	const text = new TextDecoder().decode(raw.slice(0, Math.min(raw.byteLength, HEADER_SCAN_BYTES)));
	const end = text.search(/\r?\n\r?\n/);
	const block = end === -1 ? text : text.slice(0, end);
	const headers: { name: string; value: string }[] = [];
	for (const line of block.split(/\r?\n/)) {
		if (/^[ \t]/.test(line) && headers.length) headers[headers.length - 1].value += ` ${line.trim()}`;
		else {
			const colon = line.indexOf(":");
			if (colon > 0) headers.push({ name: line.slice(0, colon).trim().toLowerCase(), value: line.slice(colon + 1).trim() });
		}
	}
	return headers;
}

/**
 * The leading run of headers SES wrote, or null when the message did not come
 * through SES. Reading stops at the first header SES did not add, so a sender
 * cannot forge an authentication result further down the message.
 */
function readSesHeaders(raw: ArrayBuffer): { name: string; value: string }[] | null {
	const leading: { name: string; value: string }[] = [];
	for (const header of readHeaderLines(raw)) {
		if (!SES_HEADERS.has(header.name)) break;
		leading.push(header);
	}
	return leading.some((header) => header.name === "x-ses-receipt") ? leading : null;
}

function headerValue(headers: { name: string; value: string }[], name: string): string | undefined {
	return headers.find((header) => header.name === name)?.value;
}

/**
 * The verdicts and connecting IP SES recorded in the headers it prepended (Resend receives through SES too).
 * Without an `X-SES-Receipt` in that leading run nothing is trusted.
 */
export function readSesTrace(raw: ArrayBuffer): ProviderTrace {
	const leading = readSesHeaders(raw);
	if (!leading) return {};
	const verdicts: ProviderVerdicts = {};
	const results = headerValue(leading, "authentication-results");
	if (results && /^amazonses\.com\s*;/i.test(results)) {
		for (const method of ["spf", "dkim", "dmarc"] as const) {
			const value = results.match(new RegExp(`(?:^|[;\\s])${method}=([a-z]+)`, "i"))?.[1];
			if (value) verdicts[method] = value.toUpperCase();
		}
	}
	const spam = headerValue(leading, "x-ses-spam-verdict");
	const virus = headerValue(leading, "x-ses-virus-verdict");
	if (spam) verdicts.spam = spam.toUpperCase();
	if (virus) verdicts.virus = virus.toUpperCase();
	const received = headerValue(leading, "received");
	const senderIp = received ? extractSenderIp({ received }) ?? undefined : undefined;
	return { verdicts: Object.keys(verdicts).length ? verdicts : undefined, senderIp };
}

/** Split an Authentication-Results value on semicolons outside comment parentheses. */
function splitResults(value: string): string[] {
	const sections: string[] = [];
	let current = "";
	let depth = 0;
	for (const char of value) {
		if (char === "(") depth += 1;
		else if (char === ")") depth = Math.max(0, depth - 1);
		if (char === ";" && depth === 0) {
			if (current.trim()) sections.push(current.trim());
			current = "";
			continue;
		}
		current += char;
	}
	if (current.trim()) sections.push(current.trim());
	return sections;
}

function methodSections(sections: string[], method: "spf" | "dkim" | "dmarc"): string[] {
	return sections.filter((section) => new RegExp(`^${method}\\s*=`, "i").test(section));
}

/** Prefer a passing signature when a message carries more than one of the same method. */
function methodSection(sections: string[], method: "spf" | "dkim" | "dmarc"): string | null {
	const matches = methodSections(sections, method);
	return matches.find((section) => new RegExp(`^${method}\\s*=\\s*pass\\b`, "i").test(section)) ?? matches[0] ?? null;
}

function methodStatus(section: string | null, method: "spf" | "dkim" | "dmarc"): string | null {
	return section?.match(new RegExp(`^${method}\\s*=\\s*([a-z]+)`, "i"))?.[1]?.toUpperCase() ?? null;
}

/** A domain from either `d=`/`smtp.mailfrom=` (a domain) or `i=` (a mailbox). */
function domainFromIdentity(value: string | null): string | null {
	if (!value) return null;
	const cleaned = value.replace(/^@/, "").replace(/^<|>$/g, "").trim().toLowerCase();
	const at = cleaned.lastIndexOf("@");
	const domain = at >= 0 ? cleaned.slice(at + 1) : cleaned;
	return domain || null;
}

function tlsVersion(received: string | undefined): string | null {
	const version = received?.match(/\bversion\s*=\s*(TLS(?:v|_)?[\d.]+)/i)?.[1];
	if (!version) return null;
	return version.replace(/^TLSv?/i, "TLS ").replace(/_/g, ".");
}

function senderDomainMatches(fromAddress: string, domains: string[]): boolean | null {
	const fromDomain = fromAddress.slice(fromAddress.lastIndexOf("@") + 1).trim().toLowerCase();
	if (!fromDomain || domains.length === 0) return null;
	return domains.some((domain) => isSameOrSubdomain(domain, fromDomain));
}

/**
 * Authentication results for a message that arrived through SES. Returns null
 * when the message has no trusted provider trace, so callers can say results
 * are unavailable instead of trusting headers the sender could have written.
 */
export function readSesAuthentication(raw: ArrayBuffer, fromAddress: string): MessageAuthentication | null {
	const leading = readSesHeaders(raw);
	if (!leading) return null;
	const results = headerValue(leading, "authentication-results");
	if (!results || !/^amazonses\.com\s*;/i.test(results)) return null;

	const sections = splitResults(results);
	const spfSections = methodSections(sections, "spf");
	const dkimSections = methodSections(sections, "dkim");
	const spfSection = methodSection(sections, "spf");
	const dkimSection = methodSection(sections, "dkim");
	const dmarcSection = methodSection(sections, "dmarc");

	const spfStatus = methodStatus(spfSection, "spf");
	const dkimStatus = methodStatus(dkimSection, "dkim");
	const dmarcStatus = methodStatus(dmarcSection, "dmarc");
	if (!spfStatus && !dkimStatus && !dmarcStatus) return null;

	const spfIp = spfSection?.match(/\bclient-ip\s*=\s*([^\s;)]+)/i)?.[1]
		?? spfSection?.match(/\(sender IP is ([^\s;)]+)\)/i)?.[1]
		?? null;
	const mailedBy = spfSection
		? domainFromIdentity(
			spfSection.match(/\bsmtp\.mailfrom\s*=\s*([^\s;)]+)/i)?.[1]
				?? spfSection.match(/\benvelope-from\s*=\s*([^\s;)]+)/i)?.[1]
				?? null,
		)
		: null;
	const signedBy = dkimSection
		? domainFromIdentity(
			dkimSection.match(/\bheader\.d\s*=\s*([^\s;)]+)/i)?.[1]
				?? dkimSection.match(/\bheader\.i\s*=\s*@?([^\s;)]+)/i)?.[1]
				?? null,
		)
		: null;
	const dmarcDomain = dmarcSection?.match(/\bheader\.from\s*=\s*([^\s;)]+)/i)?.[1]?.toLowerCase() ?? null;
	// Only passing signatures say anything about alignment; a failing one must
	// not make an unrelated sender look aligned.
	const alignedDomains = [...spfSections, ...dkimSections]
		.filter((section) => /^(?:spf|dkim)\s*=\s*pass\b/i.test(section))
		.map((section) => /^spf\s*=/i.test(section)
			? domainFromIdentity(
				section.match(/\bsmtp\.mailfrom\s*=\s*([^\s;)]+)/i)?.[1]
					?? section.match(/\benvelope-from\s*=\s*([^\s;)]+)/i)?.[1]
					?? null,
			)
			: domainFromIdentity(
				section.match(/\bheader\.d\s*=\s*([^\s;)]+)/i)?.[1]
					?? section.match(/\bheader\.i\s*=\s*@?([^\s;)]+)/i)?.[1]
					?? null,
			))
		.filter((domain): domain is string => !!domain);

	const method = (status: string | null, detail: string | null): MessageAuthenticationMethod | null =>
		status ? { status, detail } : null;
	const received = headerValue(leading, "received");
	const senderIp = spfIp ?? (received ? extractSenderIp({ received }) : null);

	return {
		spf: method(spfStatus, spfIp ? `IP ${spfIp}` : mailedBy ? `mailed by ${mailedBy}` : null),
		dkim: method(dkimStatus, signedBy ? `d=${signedBy}` : null),
		dmarc: method(dmarcStatus, dmarcDomain ? `header.from=${dmarcDomain}` : null),
		signedBy,
		mailedBy,
		senderIp,
		encryption: tlsVersion(received),
		aligned: senderDomainMatches(fromAddress, alignedDomains),
	};
}

/** Headers a provider has not vouched for: nothing the sender wrote here may count as authentication. */
const UNTRUSTED_PROVIDER_HEADERS = new Set(["authentication-results", "received-spf", "arc-authentication-results", "received", "return-path", "x-ses-receipt", "x-ses-spam-verdict", "x-ses-virus-verdict", "x-ses-dkim-signature"]);
const MAX_HEADER_ENTRIES = 200;
const MAX_HEADER_VALUE = 2000;

/**
 * A bounded header map (lower-case names, first value wins) for providers that do not hand one over,
 * so auto-reply suppression and spam analysis can see Auto-Submitted, Precedence, List-Id and similar.
 */
export function readHeaderMap(raw: ArrayBuffer): Record<string, string> {
	const map: Record<string, string> = {};
	let count = 0;
	for (const header of readHeaderLines(raw)) {
		if (UNTRUSTED_PROVIDER_HEADERS.has(header.name) || header.name in map) continue;
		map[header.name] = header.value.slice(0, MAX_HEADER_VALUE);
		if (++count >= MAX_HEADER_ENTRIES) break;
	}
	return map;
}