emdash 0.12.0 → 0.13.0

package/src/search/fts-manager.ts

@@ -81,8 +81,13 @@ export class FTSManager {
 		// id and locale are UNINDEXED (used for joining/filtering, not searched)
 		const columns = ["id UNINDEXED", "locale UNINDEXED", ...searchableFields].join(", ");
 
-		// Create the FTS5 virtual table
-		// Using content= to make it a contentless FTS table (we manage sync ourselves)
+		// Create the FTS5 virtual table.
+		// `content='<table>'` makes this an *external content* FTS5 table:
+		// the inverted index lives in the FTS shadow tables, but the actual
+		// row data lives in the backing content table. The triggers in
+		// `createTriggers` keep the index in sync; they MUST use the
+		// external-content-safe `'delete'` command (see notes there) to
+		// avoid `SQLITE_CORRUPT_VTAB` on UPDATE/DELETE.
 		// tokenize='porter unicode61' enables stemming (run matches running, ran, etc.)
 		await sql
 			.raw(`
@@ -106,13 +111,51 @@ export class FTSManager {
 	 * `deleted_at IS NULL`. This keeps soft-deleted content out of the
 	 * search index and ensures the FTS row count matches the non-deleted
 	 * content count (which `verifyAndRepairIndex` relies on).
+	 *
+	 * IMPORTANT: The FTS5 virtual table is created with `content='ec_<slug>'`
+	 * which makes it an *external content* FTS5 table. For external-content
+	 * tables, removing a row must use the documented `'delete'` command and
+	 * supply the OLD column values explicitly, e.g.:
+	 *
+	 *     INSERT INTO fts(fts, rowid, col1, col2)
+	 *     VALUES('delete', OLD.rowid, OLD.col1, OLD.col2);
+	 *
+	 * Using `DELETE FROM fts WHERE rowid = OLD.rowid` is the correct form
+	 * for *contentless* tables but is unsafe for external-content tables:
+	 * FTS5 then reads column values from the backing content table, which
+	 * in an AFTER UPDATE trigger already holds the NEW values. The wrong
+	 * tokens get removed and the inverted index drifts out of sync until
+	 * SQLite raises `SQLITE_CORRUPT_VTAB` on the next mutation. See
+	 * https://www.sqlite.org/fts5.html#external_content_tables.
+	 *
+	 * The UPDATE and DELETE triggers gate the `'delete'` on
+	 * `OLD.deleted_at IS NULL` because the INSERT trigger never indexed
+	 * rows that were already soft-deleted. Issuing `'delete'` for a rowid
+	 * that was never inserted into the FTS index is itself a corruption
+	 * trigger -- FTS5's `'delete'` is not a no-op on missing rowids and
+	 * raises `SQLITE_CORRUPT_VTAB`. Affected paths include restore-from-
+	 * trash (UPDATE where `OLD.deleted_at IS NOT NULL`), permanent-delete
+	 * from trash (DELETE on a soft-deleted row), and any edit on a row
+	 * that's currently in the trash.
 	 */
 	private async createTriggers(collectionSlug: string, searchableFields: string[]): Promise<void> {
 		this.validateInputs(collectionSlug, searchableFields);
+		if (searchableFields.length === 0) {
+			throw new Error(
+				`Cannot create FTS triggers for collection "${collectionSlug}": no searchable fields. ` +
+					`Mark at least one field as searchable before enabling search.`,
+			);
+		}
 		const ftsTable = this.getFtsTableName(collectionSlug);
 		const contentTable = this.getContentTableName(collectionSlug);
 		const fieldList = searchableFields.join(", ");
 		const newFieldList = searchableFields.map((f) => `NEW.${f}`).join(", ");
+		// `'delete'` takes the FTS5 virtual table name as the first column,
+		// then the rowid being removed, then the OLD value of every column
+		// declared on the FTS5 table (in declaration order: id, locale,
+		// then each searchable field).
+		const oldFieldList = searchableFields.map((f) => `OLD.${f}`).join(", ");
+
 		// Insert trigger - only index non-deleted content
 		await sql
 			.raw(`
@@ -126,15 +169,24 @@ export class FTSManager {
 		`)
 			.execute(this.db);
 
-		// Update trigger - always remove the old FTS row, only re-insert
-		// if the row is not soft-deleted. This handles both content edits
-		// and soft-delete operations (UPDATE SET deleted_at = ...).
+		// Update trigger - remove the old row from the FTS index using the
+		// external-content-safe `'delete'` command (which uses OLD column
+		// values, captured before the row was modified), then re-insert
+		// the new values when the row is still visible.
+		//
+		// `'delete'` is gated on `OLD.deleted_at IS NULL` because rows that
+		// were soft-deleted are not in the FTS index (the INSERT trigger
+		// skips them). Issuing `'delete'` for a missing rowid raises
+		// `SQLITE_CORRUPT_VTAB`, which would break restore-from-trash and
+		// edits to soft-deleted rows.
 		await sql
 			.raw(`
 			CREATE TRIGGER IF NOT EXISTS "${ftsTable}_update" 
 			AFTER UPDATE ON "${contentTable}" 
 			BEGIN
-				DELETE FROM "${ftsTable}" WHERE rowid = OLD.rowid;
+				INSERT INTO "${ftsTable}"("${ftsTable}", rowid, id, locale, ${fieldList})
+				SELECT 'delete', OLD.rowid, OLD.id, OLD.locale, ${oldFieldList}
+				WHERE OLD.deleted_at IS NULL;
 				INSERT INTO "${ftsTable}"(rowid, id, locale, ${fieldList})
 				SELECT NEW.rowid, NEW.id, NEW.locale, ${newFieldList}
 				WHERE NEW.deleted_at IS NULL;
@@ -142,13 +194,18 @@ export class FTSManager {
 		`)
 			.execute(this.db);
 
-		// Delete trigger
+		// Delete trigger - same external-content-safe `'delete'` form,
+		// gated on `OLD.deleted_at IS NULL` for the same reason as the
+		// UPDATE trigger: permanent-delete from trash hits a row whose
+		// `deleted_at` is already set and which was never indexed.
 		await sql
 			.raw(`
 			CREATE TRIGGER IF NOT EXISTS "${ftsTable}_delete" 
 			AFTER DELETE ON "${contentTable}" 
 			BEGIN
-				DELETE FROM "${ftsTable}" WHERE rowid = OLD.rowid;
+				INSERT INTO "${ftsTable}"("${ftsTable}", rowid, id, locale, ${fieldList})
+				SELECT 'delete', OLD.rowid, OLD.id, OLD.locale, ${oldFieldList}
+				WHERE OLD.deleted_at IS NULL;
 			END
 		`)
 			.execute(this.db);
@@ -372,9 +429,15 @@ export class FTSManager {
 	}
 
 	/**
-	 * Verify FTS index integrity and rebuild if corrupted.
+	 * Verify FTS index integrity and rebuild if drift is detected.
+	 *
+	 * Cheap belt-and-braces check, run lazily on the first search request
+	 * per isolate. The expensive cases (corrupted indexes from pre-fix
+	 * EmDash versions, broken legacy triggers) are handled at boot time by
+	 * migration `039_fix_fts5_triggers`, not here. This routine sticks to:
 	 *
-	 * Checks for row count mismatch between content table and FTS table.
+	 *   1. FTS table missing while config says search is enabled -> rebuild.
+	 *   2. Row count mismatch between content table and FTS docsize -> rebuild.
 	 *
 	 * Returns true if the index was rebuilt, false if it was healthy.
 	 */
@@ -397,16 +460,15 @@ export class FTSManager {
 			return true;
 		}
 
-		// Check 1: Row count mismatch
+		// Row count parity check. For external-content FTS tables, COUNT(*)
+		// on the virtual table is answered from the backing content table
+		// (including soft-deleted rows), so we use the docsize shadow table
+		// which tracks rows actually present in the full-text index.
 		const contentCount = await sql<{ count: number }>`
 			SELECT COUNT(*) as count FROM ${sql.ref(contentTable)}
 			WHERE deleted_at IS NULL
 		`.execute(this.db);
 
-		// For external-content FTS tables, COUNT(*) on the virtual table is
-		// answered from the backing content table, including soft-deleted rows.
-		// The docsize shadow table tracks the rows actually present in the
-		// full-text index, which is what we need for repair decisions.
 		const ftsCount = await sql<{ count: number }>`
 			SELECT COUNT(*) as count FROM "${sql.raw(ftsDocsizeTable)}"
 		`.execute(this.db);

package/src/security/ssrf.ts

@@ -0,0 +1,501 @@
+/**
+ * SSRF protection for import URLs.
+ *
+ * Validates that URLs don't target internal/private network addresses.
+ * Applied before any fetch() call in the import pipeline.
+ */
+
+const IPV4_MAPPED_IPV6_DOTTED_PATTERN = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i;
+const IPV4_MAPPED_IPV6_HEX_PATTERN = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i;
+const IPV4_TRANSLATED_HEX_PATTERN = /^::ffff:0:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i;
+const IPV6_EXPANDED_MAPPED_PATTERN =
+	/^0{0,4}:0{0,4}:0{0,4}:0{0,4}:0{0,4}:ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i;
+
+/**
+ * IPv4-compatible (deprecated) addresses: ::XXXX:XXXX
+ *
+ * The WHATWG URL parser normalizes [::127.0.0.1] to [::7f00:1] (no ffff prefix).
+ * These are deprecated but still parsed, and bypass the ffff-based checks.
+ */
+const IPV4_COMPATIBLE_HEX_PATTERN = /^::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i;
+
+/**
+ * NAT64 prefix (RFC 6052): 64:ff9b::XXXX:XXXX
+ *
+ * Used by NAT64 gateways to embed IPv4 addresses in IPv6.
+ * [64:ff9b::127.0.0.1] normalizes to [64:ff9b::7f00:1].
+ */
+const NAT64_HEX_PATTERN = /^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i;
+
+const IPV6_BRACKET_PATTERN = /^\[|\]$/g;
+
+/** Match fc00::/7 ULA — first byte 0xfc or 0xfd followed by any byte. */
+const IPV6_ULA_FC_PATTERN = /^fc[0-9a-f]{2}:/;
+const IPV6_ULA_FD_PATTERN = /^fd[0-9a-f]{2}:/;
+
+/** Strip trailing dots from an FQDN-form hostname ("localhost." -> "localhost"). */
+const TRAILING_DOT_PATTERN = /\.+$/;
+
+/**
+ * Private and reserved IP ranges that should never be fetched.
+ *
+ * Includes:
+ * - Loopback (127.0.0.0/8)
+ * - Private (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ * - Link-local (169.254.0.0/16)
+ * - Cloud metadata (169.254.169.254 — AWS/GCP/Azure)
+ * - IPv6 loopback and link-local
+ */
+const BLOCKED_PATTERNS: Array<{ start: number; end: number }> = [
+	// 127.0.0.0/8 — loopback
+	{ start: ip4ToNum(127, 0, 0, 0), end: ip4ToNum(127, 255, 255, 255) },
+	// 10.0.0.0/8 — private
+	{ start: ip4ToNum(10, 0, 0, 0), end: ip4ToNum(10, 255, 255, 255) },
+	// 172.16.0.0/12 — private
+	{ start: ip4ToNum(172, 16, 0, 0), end: ip4ToNum(172, 31, 255, 255) },
+	// 192.168.0.0/16 — private
+	{ start: ip4ToNum(192, 168, 0, 0), end: ip4ToNum(192, 168, 255, 255) },
+	// 169.254.0.0/16 — link-local (includes cloud metadata endpoint)
+	{ start: ip4ToNum(169, 254, 0, 0), end: ip4ToNum(169, 254, 255, 255) },
+	// 0.0.0.0/8 — current network
+	{ start: ip4ToNum(0, 0, 0, 0), end: ip4ToNum(0, 255, 255, 255) },
+];
+
+// Bracket-stripped form is used for lookups (validateExternalUrl strips
+// brackets from parsed.hostname before checking), so "::1" appears here
+// without brackets. The "::1" case is already covered by isPrivateIp, but
+// keeping it here makes the intent explicit and gives a clearer error
+// message for the common `http://[::1]/` form.
+const BLOCKED_HOSTNAMES = new Set([
+	"localhost",
+	"metadata.google.internal",
+	"metadata.google",
+	"::1",
+]);
+
+/**
+ * Wildcard DNS services that publicly resolve arbitrary IPs embedded in the
+ * hostname. Commonly used in local dev and by SSRF exploit tooling to bypass
+ * hostname-only blocklists (e.g. 127.0.0.1.nip.io -> 127.0.0.1).
+ *
+ * Matched case-insensitively as a suffix, so both the apex and any subdomain
+ * are blocked.
+ */
+const BLOCKED_HOSTNAME_SUFFIXES = [
+	"nip.io",
+	"sslip.io",
+	"xip.io",
+	"traefik.me",
+	"lvh.me",
+	"localtest.me",
+];
+
+/** Blocked URL schemes */
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+
+function ip4ToNum(a: number, b: number, c: number, d: number): number {
+	return ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+}
+
+function parseIpv4(ip: string): number | null {
+	const parts = ip.split(".");
+	if (parts.length !== 4) return null;
+
+	const nums = parts.map(Number);
+	if (nums.some((n) => isNaN(n) || n < 0 || n > 255)) return null;
+
+	return ip4ToNum(nums[0], nums[1], nums[2], nums[3]);
+}
+
+/**
+ * Convert IPv4-mapped/translated IPv6 addresses from hex form back to IPv4.
+ *
+ * The WHATWG URL parser normalizes dotted-decimal to hex:
+ *   [::ffff:127.0.0.1] -> [::ffff:7f00:1]
+ *   [::ffff:169.254.169.254] -> [::ffff:a9fe:a9fe]
+ *
+ * Without this conversion, the hex forms bypass isPrivateIp() regex checks.
+ */
+export function normalizeIPv6MappedToIPv4(ip: string): string | null {
+	// Match hex-form IPv4-mapped IPv6: ::ffff:XXXX:XXXX
+	let match = ip.match(IPV4_MAPPED_IPV6_HEX_PATTERN);
+	if (!match) {
+		// Match IPv4-translated (RFC 6052): ::ffff:0:XXXX:XXXX
+		match = ip.match(IPV4_TRANSLATED_HEX_PATTERN);
+	}
+	if (!match) {
+		// Match fully expanded form: 0000:0000:0000:0000:0000:ffff:XXXX:XXXX
+		match = ip.match(IPV6_EXPANDED_MAPPED_PATTERN);
+	}
+	if (!match) {
+		// Match IPv4-compatible (deprecated) form: ::XXXX:XXXX (no ffff prefix)
+		match = ip.match(IPV4_COMPATIBLE_HEX_PATTERN);
+	}
+	if (!match) {
+		// Match NAT64 prefix (RFC 6052): 64:ff9b::XXXX:XXXX
+		match = ip.match(NAT64_HEX_PATTERN);
+	}
+	if (match) {
+		const high = parseInt(match[1] ?? "", 16);
+		const low = parseInt(match[2] ?? "", 16);
+		return `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+	}
+	return null;
+}
+
+function isPrivateIp(ip: string): boolean {
+	// Normalize IPv6 strings to lowercase. `new URL().hostname` already
+	// lowercases, but resolver output (from DoH or an injected resolver) may
+	// not. Without this, "FE80::1" bypasses the link-local check.
+	const normalized = ip.toLowerCase();
+
+	// Handle IPv6 loopback
+	if (normalized === "::1" || normalized === "::ffff:127.0.0.1") return true;
+
+	// Handle IPv4-mapped IPv6 in hex form (WHATWG URL parser normalizes to this)
+	// e.g. ::ffff:7f00:1 -> 127.0.0.1, ::ffff:a9fe:a9fe -> 169.254.169.254
+	const hexIpv4 = normalizeIPv6MappedToIPv4(normalized);
+	if (hexIpv4) return isPrivateIp(hexIpv4);
+
+	// Handle IPv4-mapped IPv6 in dotted-decimal form
+	const v4Match = normalized.match(IPV4_MAPPED_IPV6_DOTTED_PATTERN);
+	const ipv4 = v4Match ? v4Match[1] : normalized;
+
+	const num = parseIpv4(ipv4);
+	if (num === null) {
+		// If we can't parse it, block IPv6 addresses that look internal.
+		// fc00::/7 is Unique Local (first byte 0xfc or 0xfd), fe80::/10 is
+		// link-local. Only match when followed by hex digit + colon to avoid
+		// collisions with hypothetical non-address strings.
+		return (
+			normalized.startsWith("fe80:") ||
+			IPV6_ULA_FC_PATTERN.test(normalized) ||
+			IPV6_ULA_FD_PATTERN.test(normalized)
+		);
+	}
+
+	return BLOCKED_PATTERNS.some((range) => num >= range.start && num <= range.end);
+}
+
+/**
+ * Error thrown when SSRF protection blocks a URL.
+ */
+export class SsrfError extends Error {
+	code = "SSRF_BLOCKED" as const;
+
+	constructor(message: string) {
+		super(message);
+		this.name = "SsrfError";
+	}
+}
+
+/**
+ * Validate that a URL is safe to fetch (not targeting internal networks).
+ *
+ * Checks:
+ * 1. URL is well-formed with http/https scheme
+ * 2. Hostname is not a known internal name (localhost, metadata endpoints)
+ * 3. If hostname is an IP literal, it's not in a private range
+ *
+ * Note: DNS rebinding attacks are not fully mitigated (hostname could resolve
+ * to a private IP). Full protection requires resolving DNS and checking the IP
+ * before connecting, which needs a custom fetch implementation. This covers
+ * the most common SSRF vectors.
+ *
+ * @throws SsrfError if the URL targets an internal address
+ */
+/** Maximum number of redirects to follow in ssrfSafeFetch */
+const MAX_REDIRECTS = 5;
+
+export function validateExternalUrl(url: string): URL {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new SsrfError("Invalid URL");
+	}
+
+	// Only allow http/https
+	if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+		throw new SsrfError(`Scheme '${parsed.protocol}' is not allowed`);
+	}
+
+	// Strip brackets from IPv6 hostname
+	const hostname = parsed.hostname.replace(IPV6_BRACKET_PATTERN, "");
+
+	// Normalize the hostname for blocklist matching: lowercase + strip any
+	// trailing dots. WHATWG preserves trailing dots on .hostname, so without
+	// this normalization "localhost." and "nip.io." bypass the checks.
+	const normalizedHost = hostname.toLowerCase().replace(TRAILING_DOT_PATTERN, "");
+
+	// Check against known internal hostnames
+	if (BLOCKED_HOSTNAMES.has(normalizedHost)) {
+		throw new SsrfError("URLs targeting internal hosts are not allowed");
+	}
+
+	// Check against wildcard DNS services used by SSRF tooling to bypass
+	// hostname-only checks. Match the apex and any subdomain.
+	for (const suffix of BLOCKED_HOSTNAME_SUFFIXES) {
+		if (normalizedHost === suffix || normalizedHost.endsWith(`.${suffix}`)) {
+			throw new SsrfError("URLs targeting wildcard DNS services are not allowed");
+		}
+	}
+
+	// Check if hostname is an IP address in a private range. Use the
+	// normalized form so "127.0.0.1.." and friends don't bypass parseIpv4
+	// (which rejects extra trailing dots).
+	if (isPrivateIp(normalizedHost)) {
+		throw new SsrfError("URLs targeting private IP addresses are not allowed");
+	}
+
+	return parsed;
+}
+
+// ---------------------------------------------------------------------------
+// DNS-aware validation
+// ---------------------------------------------------------------------------
+
+/**
+ * A resolver that maps a hostname to a list of IPv4/IPv6 addresses.
+ * Injectable so callers can swap in OS-level DNS on Node, stub it in tests,
+ * or point to a different DoH endpoint.
+ */
+export type DnsResolver = (hostname: string) => Promise<string[]>;
+
+/**
+ * Module-level default resolver. Tests can swap this with a stub so fetch
+ * mocks don't see unexpected DoH round-trips. Production code should leave
+ * it alone.
+ */
+let defaultResolver: DnsResolver | null = null;
+
+/** Override the default DNS resolver. Returns the previous value. */
+export function setDefaultDnsResolver(resolver: DnsResolver | null): DnsResolver | null {
+	const previous = defaultResolver;
+	defaultResolver = resolver;
+	return previous;
+}
+
+/** Timeout for a single DoH request, in milliseconds. */
+const DOH_TIMEOUT_MS = 3000;
+
+/** Default DoH endpoint — Cloudflare's public resolver. */
+const DEFAULT_DOH_URL = "https://cloudflare-dns.com/dns-query";
+
+interface DohAnswer {
+	data: string;
+}
+
+interface DohResponse {
+	Status: number;
+	Answer: DohAnswer[];
+}
+
+function hasProperty<K extends string>(obj: unknown, key: K): obj is Record<K, unknown> {
+	return typeof obj === "object" && obj !== null && key in obj;
+}
+
+/**
+ * Narrow an unknown JSON body to a DohResponse shape we can read safely.
+ * Throws if the body doesn't look like a DoH response — a malformed body is
+ * indistinguishable from a failure and must not be silently treated as empty.
+ */
+function parseDohResponse(raw: unknown): DohResponse {
+	if (!hasProperty(raw, "Status") || typeof raw.Status !== "number") {
+		throw new Error("DoH response missing Status field");
+	}
+	const answers: DohAnswer[] = [];
+	if (hasProperty(raw, "Answer") && Array.isArray(raw.Answer)) {
+		for (const entry of raw.Answer) {
+			if (hasProperty(entry, "data") && typeof entry.data === "string") {
+				answers.push({ data: entry.data });
+			}
+		}
+	}
+	return { Status: raw.Status, Answer: answers };
+}
+
+/**
+ * Resolve a hostname via DNS over HTTPS (Cloudflare). Returns all A and AAAA
+ * records. Works in both Workers and Node without requiring node:dns.
+ *
+ * Fails closed: any network error, non-2xx response, or DNS rcode != 0
+ * causes a rejected promise so the calling validator treats it as a block.
+ */
+export const cloudflareDohResolver: DnsResolver = async (hostname) => {
+	async function query(type: "A" | "AAAA"): Promise<string[]> {
+		const params = new URLSearchParams({ name: hostname, type });
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), DOH_TIMEOUT_MS);
+		try {
+			const response = await globalThis.fetch(`${DEFAULT_DOH_URL}?${params.toString()}`, {
+				headers: { Accept: "application/dns-json" },
+				signal: controller.signal,
+			});
+			if (!response.ok) {
+				throw new Error(`DoH lookup failed: ${response.status}`);
+			}
+			const raw = await response.json();
+			const body = parseDohResponse(raw);
+			// NXDOMAIN (3) is a legitimate "does not exist" — treat as empty.
+			// Any other non-zero status (SERVFAIL=2, REFUSED=5, etc.) is
+			// ambiguous and could be a split-view attacker hiding records
+			// from our resolver. Fail closed.
+			if (body.Status === 3) return [];
+			if (body.Status !== 0) {
+				throw new Error(`DoH ${type} lookup failed: rcode=${body.Status}`);
+			}
+			// DoH Answer arrays often include CNAME records alongside A/AAAA
+			// records. Their `data` is a hostname, not an IP. Filter to just
+			// IP literals so isPrivateIp sees real addresses.
+			return body.Answer.map((a) => a.data).filter(isIpLiteral);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+
+	const [a, aaaa] = await Promise.all([query("A"), query("AAAA")]);
+	return [...a, ...aaaa];
+};
+
+/**
+ * Validate a URL and resolve its hostname to check the actual IPs against
+ * the private-range blocklist. This catches DNS rebinding attacks using
+ * attacker-controlled domains that publicly resolve to private addresses,
+ * and wildcard DNS services like nip.io used by exploit tooling.
+ *
+ * Runs `validateExternalUrl` first for cheap pre-flight checks (scheme,
+ * literal IP, known-bad hostnames). Then resolves the hostname and rejects
+ * if ANY returned address is private.
+ *
+ * Fails closed: if resolution fails or returns no records, throws SsrfError.
+ *
+ * **Caveats.** This does NOT fully close the TOCTOU between check and
+ * connect. Attacks that still work against this layer include:
+ *
+ * - TTL=0 rebind: authoritative server returns public IP to the check, then
+ *   private IP to the subsequent fetch() a few milliseconds later.
+ * - Split-view via EDNS Client Subnet or source-IP inspection: the
+ *   authoritative server returns public IP to Cloudflare's DoH resolver and
+ *   private IP to the victim's own resolver (used by fetch()).
+ * - Host-file overrides or split-horizon corporate DNS on self-hosted Node.
+ * - Attacker-controlled rebinding services the caller has allowlisted.
+ *
+ * The only complete defense is a network-layer egress firewall. On
+ * Cloudflare Workers, the platform fetch pipeline provides most of that.
+ * On self-hosted Node, operators must restrict egress themselves.
+ */
+export async function resolveAndValidateExternalUrl(
+	url: string,
+	options?: { resolver?: DnsResolver },
+): Promise<URL> {
+	const parsed = validateExternalUrl(url);
+
+	// Strip brackets from IPv6 hostnames
+	const hostname = parsed.hostname.replace(IPV6_BRACKET_PATTERN, "");
+
+	// If the hostname is already an IP literal, validateExternalUrl has
+	// already checked it against the private-range list. Skip DNS.
+	if (isIpLiteral(hostname)) {
+		return parsed;
+	}
+
+	const resolver = options?.resolver ?? defaultResolver ?? cloudflareDohResolver;
+
+	let addresses: string[];
+	try {
+		addresses = await resolver(hostname);
+	} catch (error) {
+		throw new SsrfError(
+			`Could not resolve hostname: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	if (addresses.length === 0) {
+		throw new SsrfError("Hostname resolved to no addresses");
+	}
+
+	for (const ip of addresses) {
+		if (isPrivateIp(ip)) {
+			throw new SsrfError("Hostname resolves to a private IP address");
+		}
+	}
+
+	return parsed;
+}
+
+/** True when a string looks like an IPv4 or IPv6 literal. */
+function isIpLiteral(host: string): boolean {
+	if (parseIpv4(host) !== null) return true;
+	// Very loose IPv6 heuristic — matches anything with a colon, which is
+	// never valid in DNS hostnames, so this is safe.
+	return host.includes(":");
+}
+
+/**
+ * Fetch a URL with SSRF protection on redirects.
+ *
+ * Uses `redirect: "manual"` to intercept redirects and re-validate each
+ * redirect target against SSRF rules before following it. This prevents
+ * an attacker from setting up an allowed external URL that redirects to
+ * an internal IP (e.g. 169.254.169.254 for cloud metadata).
+ *
+ * @throws SsrfError if the initial URL or any redirect target is internal
+ */
+/** Headers that must be stripped when a redirect crosses origins */
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+
+export async function ssrfSafeFetch(
+	url: string,
+	init?: RequestInit,
+	options?: { resolver?: DnsResolver },
+): Promise<Response> {
+	let currentUrl = url;
+	let currentInit = init;
+
+	for (let i = 0; i <= MAX_REDIRECTS; i++) {
+		await resolveAndValidateExternalUrl(currentUrl, options);
+
+		const response = await globalThis.fetch(currentUrl, {
+			...currentInit,
+			redirect: "manual",
+		});
+
+		// Not a redirect -- return directly
+		if (response.status < 300 || response.status >= 400) {
+			return response;
+		}
+
+		// Extract redirect target
+		const location = response.headers.get("Location");
+		if (!location) {
+			return response;
+		}
+
+		// Resolve relative redirects against the current URL
+		const previousOrigin = new URL(currentUrl).origin;
+		currentUrl = new URL(location, currentUrl).href;
+		const nextOrigin = new URL(currentUrl).origin;
+
+		// Strip credential headers on cross-origin redirects
+		if (previousOrigin !== nextOrigin && currentInit) {
+			currentInit = stripCredentialHeaders(currentInit);
+		}
+	}
+
+	throw new SsrfError(`Too many redirects (max ${MAX_REDIRECTS})`);
+}
+
+/**
+ * Return a copy of init with credential headers removed.
+ */
+export function stripCredentialHeaders(init: RequestInit): RequestInit {
+	if (!init.headers) return init;
+
+	const headers = new Headers(init.headers);
+	for (const name of CREDENTIAL_HEADERS) {
+		headers.delete(name);
+	}
+
+	return { ...init, headers };
+}