emdash 0.6.0 → 0.7.0

package/src/import/ssrf.ts

@@ -29,6 +29,13 @@ 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.
  *
@@ -54,13 +61,35 @@ const BLOCKED_PATTERNS: Array<{ start: number; end: number }> = [
 	{ 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]",
+	"::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:"]);
 
@@ -115,22 +144,34 @@ export function normalizeIPv6MappedToIPv4(ip: string): string | 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 (ip === "::1" || ip === "::ffff:127.0.0.1") return true;
+	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(ip);
+	const hexIpv4 = normalizeIPv6MappedToIPv4(normalized);
 	if (hexIpv4) return isPrivateIp(hexIpv4);
 
 	// Handle IPv4-mapped IPv6 in dotted-decimal form
-	const v4Match = ip.match(IPV4_MAPPED_IPV6_DOTTED_PATTERN);
-	const ipv4 = v4Match ? v4Match[1] : ip;
+	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
-		return ip.startsWith("fe80:") || ip.startsWith("fc") || ip.startsWith("fd");
+		// 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);
@@ -182,19 +223,215 @@ export function validateExternalUrl(url: string): URL {
 	// 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(hostname.toLowerCase())) {
+	if (BLOCKED_HOSTNAMES.has(normalizedHost)) {
 		throw new SsrfError("URLs targeting internal hosts are not allowed");
 	}
 
-	// Check if hostname is an IP address in a private range
-	if (isPrivateIp(hostname)) {
+	// 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.
  *
@@ -208,12 +445,16 @@ export function validateExternalUrl(url: string): URL {
 /** 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): Promise<Response> {
+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++) {
-		validateExternalUrl(currentUrl);
+		await resolveAndValidateExternalUrl(currentUrl, options);
 
 		const response = await globalThis.fetch(currentUrl, {
 			...currentInit,

package/src/mcp/server.ts

@@ -84,6 +84,15 @@ interface EmDashExtra {
 	tokenScopes?: string[];
 }
 
+function isPublished(t: unknown): boolean {
+	return (
+		typeof t === "object" &&
+		t !== null &&
+		"status" in t &&
+		(t as Record<string, unknown>).status === "published"
+	);
+}
+
 function getExtra(extra: { authInfo?: { extra?: Record<string, unknown> } }): EmDashExtra {
 	const payload = extra.authInfo?.extra as EmDashExtra | undefined;
 	if (!payload?.emdash) {
@@ -130,6 +139,26 @@ function requireRole(
 	}
 }
 
+/**
+ * Whether the current user may read non-published content (drafts, scheduled,
+ * trashed, revisions, compare). SUBSCRIBER may hold content:read for
+ * member-only published content but must not see drafts.
+ */
+function canReadDrafts(extra: { authInfo?: { extra?: Record<string, unknown> } }): boolean {
+	const payload = getExtra(extra);
+	return hasPermission({ role: payload.userRole }, "content:read_drafts");
+}
+
+/**
+ * Throw if the current user cannot read non-published content. Used by
+ * editor-only views (revisions, compare, trash, preview-url).
+ */
+function requireDraftAccess(extra: { authInfo?: { extra?: Record<string, unknown> } }): void {
+	if (!canReadDrafts(extra)) {
+		throw new McpError(ErrorCode.InvalidRequest, "Insufficient permissions for this operation");
+	}
+}
+
 /**
  * Enforce ownership-based permission checks, mirroring the REST API's
  * requireOwnerPerm() pattern.
@@ -240,9 +269,12 @@ export function createMcpServer(): McpServer {
 		async (args, extra) => {
 			requireScope(extra, "content:read");
 			const ec = getEmDash(extra);
+			// Subscribers must only see published content; force the status
+			// filter regardless of caller-supplied value.
+			const status = canReadDrafts(extra) ? args.status : "published";
 			return unwrap(
 				await ec.handleContentList(args.collection, {
-					status: args.status,
+					status,
 					limit: args.limit,
 					cursor: args.cursor,
 					orderBy: args.orderBy,
@@ -276,7 +308,29 @@ export function createMcpServer(): McpServer {
 		async (args, extra) => {
 			requireScope(extra, "content:read");
 			const ec = getEmDash(extra);
-			return unwrap(await ec.handleContentGet(args.collection, args.id, args.locale));
+			const result = await ec.handleContentGet(args.collection, args.id, args.locale);
+			// Hide non-published items from users without draft access. Return a
+			// not-found error so subscribers can't enumerate draft IDs by status.
+			if (result.success && !canReadDrafts(extra)) {
+				const data =
+					result.data && typeof result.data === "object"
+						? // eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- handler returns unknown data; narrowed by typeof check
+							(result.data as Record<string, unknown>)
+						: undefined;
+				const item =
+					data?.item && typeof data.item === "object"
+						? // eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- narrowed by typeof check
+							(data.item as Record<string, unknown>)
+						: undefined;
+				const status = typeof item?.status === "string" ? item.status : null;
+				if (status !== "published") {
+					return unwrap({
+						success: false,
+						error: { code: "NOT_FOUND", message: `Content item not found: ${args.id}` },
+					});
+				}
+			}
+			return unwrap(result);
 		},
 	);
 
@@ -676,6 +730,7 @@ export function createMcpServer(): McpServer {
 		},
 		async (args, extra) => {
 			requireScope(extra, "content:read");
+			requireDraftAccess(extra);
 			const ec = getEmDash(extra);
 			return unwrap(await ec.handleContentCompare(args.collection, args.id));
 		},
@@ -733,6 +788,7 @@ export function createMcpServer(): McpServer {
 		},
 		async (args, extra) => {
 			requireScope(extra, "content:read");
+			requireDraftAccess(extra);
 			const ec = getEmDash(extra);
 			return unwrap(
 				await ec.handleContentListTrashed(args.collection, {
@@ -780,7 +836,23 @@ export function createMcpServer(): McpServer {
 		async (args, extra) => {
 			requireScope(extra, "content:read");
 			const ec = getEmDash(extra);
-			return unwrap(await ec.handleContentTranslations(args.collection, args.id));
+			const result = await ec.handleContentTranslations(args.collection, args.id);
+			// Filter out non-published translations for users without draft
+			// access so a subscriber can't enumerate locales that aren't yet live.
+			if (result.success && !canReadDrafts(extra)) {
+				const data =
+					result.data && typeof result.data === "object"
+						? // eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- handler returns unknown data; narrowed by typeof check
+							(result.data as Record<string, unknown>)
+						: undefined;
+				const translations = Array.isArray(data?.translations) ? data.translations : [];
+				const filtered = translations.filter(isPublished);
+				return unwrap({
+					success: true,
+					data: { ...data, translations: filtered },
+				});
+			}
+			return unwrap(result);
 		},
 	);
 
@@ -1460,6 +1532,7 @@ export function createMcpServer(): McpServer {
 		},
 		async (args, extra) => {
 			requireScope(extra, "content:read");
+			requireDraftAccess(extra);
 			const ec = getEmDash(extra);
 			return unwrap(
 				await ec.handleRevisionList(args.collection, args.id, {

package/src/plugins/context.ts

@@ -16,7 +16,11 @@ import { SeoRepository } from "../database/repositories/seo.js";
 import { UserRepository } from "../database/repositories/user.js";
 import { withTransaction } from "../database/transaction.js";
 import type { Database } from "../database/types.js";
-import { validateExternalUrl, SsrfError, stripCredentialHeaders } from "../import/ssrf.js";
+import {
+	resolveAndValidateExternalUrl,
+	SsrfError,
+	stripCredentialHeaders,
+} from "../import/ssrf.js";
 import type { Storage } from "../storage/types.js";
 import { CronAccessImpl } from "./cron.js";
 import type { EmailPipeline } from "./email.js";
@@ -599,9 +603,10 @@ export function createUnrestrictedHttpAccess(pluginId: string): HttpAccess {
 			let currentInit = init;
 
 			for (let i = 0; i <= MAX_PLUGIN_REDIRECTS; i++) {
-				// Validate each URL against SSRF rules (private IPs, metadata endpoints)
+				// Validate each URL against SSRF rules (private IPs, metadata
+				// endpoints, wildcard DNS, resolved-IP private ranges).
 				try {
-					validateExternalUrl(currentUrl);
+					await resolveAndValidateExternalUrl(currentUrl);
 				} catch (e) {
 					const msg = e instanceof SsrfError ? e.message : "SSRF validation failed";
 					throw new Error(
@@ -849,6 +854,13 @@ export interface PluginContextFactoryOptions {
 	 * If not provided (or no provider configured), ctx.email will be undefined.
 	 */
 	emailPipeline?: EmailPipeline;
+	/**
+	 * Pre-resolved list of trusted proxy header names (from the runtime
+	 * `EmDashConfig.trustedProxyHeaders` or the env var). Plugin route
+	 * handlers pass this to `extractRequestMeta` so plugins see the same
+	 * client IP the core auth path does.
+	 */
+	trustedProxyHeaders?: string[];
 }
 
 /**

package/src/plugins/manager.ts

@@ -62,6 +62,11 @@ export interface PluginManagerOptions {
 		filename: string,
 		contentType: string,
 	) => Promise<{ uploadUrl: string; mediaId: string }>;
+	/**
+	 * Pre-resolved list of trusted proxy header names for client-IP
+	 * resolution in plugin route handlers. Thread through from the runtime.
+	 */
+	trustedProxyHeaders?: string[];
 }
 
 /**
@@ -81,6 +86,7 @@ export class PluginManager {
 			db: options.db,
 			storage: options.storage,
 			getUploadUrl: options.getUploadUrl,
+			trustedProxyHeaders: options.trustedProxyHeaders,
 		};
 	}
 

package/src/plugins/request-meta.ts

@@ -7,6 +7,8 @@
  *
  */
 
+import type { EmDashConfig } from "../astro/integration/runtime.js";
+import { getTrustedProxyHeaders, normalizeTrustedHeaders } from "../auth/trusted-proxy.js";
 import type { GeoInfo, RequestMeta } from "./types.js";
 
 /**
@@ -40,6 +42,23 @@ function parseFirstForwardedIp(header: string): string | null {
 	return IP_PATTERN.test(trimmed) ? trimmed : null;
 }
 
+/**
+ * Read an IP from an operator-declared trusted header. XFF-style headers
+ * (any name ending in `forwarded-for`) are parsed as comma-separated lists
+ * and the first entry is used; everything else is treated as a single
+ * trimmed value.
+ */
+function readIpFromHeader(headers: Headers, name: string): string | null {
+	const value = headers.get(name);
+	if (!value) return null;
+	if (name.endsWith("forwarded-for")) {
+		return parseFirstForwardedIp(value);
+	}
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	return IP_PATTERN.test(trimmed) ? trimmed : null;
+}
+
 /**
  * Get the Cloudflare `cf` object from the request, if present.
  * Returns undefined when not running on Cloudflare Workers.
@@ -69,32 +88,52 @@ function extractGeo(cf: CfProperties | undefined): GeoInfo | null {
  * Extract normalized request metadata from a Request object.
  *
  * IP resolution order:
- * 1. `CF-Connecting-IP` header — only trusted when a `cf` object is
- *    present on the request (proving the request came through Cloudflare's
- *    edge, which strips/overwrites client-supplied values).
- * 2. `X-Forwarded-For` header (first entry) — best-effort, spoofable
- *    when there is no trusted reverse proxy.
- * 3. `null`
+ * 1. `CF-Connecting-IP` — trusted only when a `cf` object is present on the
+ *    request. CF edge overwrites any client-supplied value, so this is the
+ *    cryptographically trustworthy path on Workers. Operator-declared
+ *    trusted headers cannot override it.
+ * 2. `X-Forwarded-For` first entry — trusted only with a `cf` object.
+ * 3. Operator-declared trusted proxy headers (from `config.trustedProxyHeaders`
+ *    or the `EMDASH_TRUSTED_PROXY_HEADERS` env var), tried in order. Used as
+ *    the primary source off-CF and as a fill-in on CF.
+ * 4. `null`
+ *
+ * The second argument accepts either the EmDash config or a pre-resolved
+ * list of trusted headers, so callers that already have the list don't have
+ * to round-trip through the config every request.
  */
-export function extractRequestMeta(request: Request): RequestMeta {
+export function extractRequestMeta(
+	request: Request,
+	configOrTrustedHeaders?: EmDashConfig | null | { trustedProxyHeaders?: string[] } | string[],
+): RequestMeta {
 	const headers = request.headers;
 	const cf = getCfObject(request);
+	const trusted = resolveTrustedHeaders(configOrTrustedHeaders);
 
-	// IP: only trust headers when the cf object confirms we're on Cloudflare.
-	// Without a trusted reverse proxy, X-Forwarded-For is trivially spoofable.
 	let ip: string | null = null;
+
+	// On Cloudflare, prefer the cryptographically trustworthy headers first.
 	if (cf) {
 		const cfIp = headers.get("cf-connecting-ip")?.trim();
 		if (cfIp && IP_PATTERN.test(cfIp)) {
 			ip = cfIp;
 		}
+		if (!ip) {
+			const xff = headers.get("x-forwarded-for");
+			ip = xff ? parseFirstForwardedIp(xff) : null;
+		}
 	}
-	if (!ip && cf) {
-		// Only trust X-Forwarded-For when we're behind Cloudflare (which
-		// overwrites the header). In standalone deployments without a trusted
-		// proxy, XFF is trivially spoofable.
-		const xff = headers.get("x-forwarded-for");
-		ip = xff ? parseFirstForwardedIp(xff) : null;
+
+	// Fall through to operator-declared trusted headers. On CF this fills
+	// in when the CF headers are absent; off-CF it's the primary source.
+	if (!ip) {
+		for (const name of trusted) {
+			const value = readIpFromHeader(headers, name);
+			if (value) {
+				ip = value;
+				break;
+			}
+		}
 	}
 
 	const userAgent = headers.get("user-agent")?.trim() || null;
@@ -104,6 +143,18 @@ export function extractRequestMeta(request: Request): RequestMeta {
 	return { ip, userAgent, referer, geo };
 }
 
+function resolveTrustedHeaders(
+	value: EmDashConfig | null | { trustedProxyHeaders?: string[] } | string[] | undefined,
+): string[] {
+	if (Array.isArray(value)) {
+		// Apply the same RFC 7230 validation the config/env path does so a
+		// caller passing a pre-resolved list with bad entries can't crash
+		// `Headers.get()` downstream.
+		return normalizeTrustedHeaders(value);
+	}
+	return getTrustedProxyHeaders(value);
+}
+
 // =============================================================================
 // Header Sanitization for Sandbox
 // =============================================================================

package/src/plugins/routes.ts

@@ -50,10 +50,12 @@ export interface InvokeRouteOptions {
 export class PluginRouteHandler {
 	private contextFactory: PluginContextFactory;
 	private plugin: ResolvedPlugin;
+	private trustedProxyHeaders: string[];
 
 	constructor(plugin: ResolvedPlugin, factoryOptions: PluginContextFactoryOptions) {
 		this.plugin = plugin;
 		this.contextFactory = new PluginContextFactory(factoryOptions);
+		this.trustedProxyHeaders = factoryOptions.trustedProxyHeaders ?? [];
 	}
 
 	/**
@@ -99,7 +101,7 @@ export class PluginRouteHandler {
 			...baseContext,
 			input: validatedInput,
 			request: options.request,
-			requestMeta: extractRequestMeta(options.request),
+			requestMeta: extractRequestMeta(options.request, this.trustedProxyHeaders),
 		};
 
 		// Execute handler