validateForwardedHeaders() — astro Function Reference

Architecture documentation for the validateForwardedHeaders() function in validate-forwarded-headers.ts from the astro codebase.

Function typescript CoreAstro RenderingEngine calls 1

Entity Profile

CoreAstro→ RenderingEngine→ validateForwardedHeaders() — astro Function Reference

Dependency Diagram

graph TD
  f0b817ef_eb04_6a82_be87_88371a15d57a["validateForwardedHeaders()"]
  99ec8f02_16e0_8238_9009_e576f7a7689a["validate-forwarded-headers.ts"]
  f0b817ef_eb04_6a82_be87_88371a15d57a -->|defined in| 99ec8f02_16e0_8238_9009_e576f7a7689a
  2db711c0_6a20_c7ba_2a00_0a735185abd4["sanitizeHost()"]
  f0b817ef_eb04_6a82_be87_88371a15d57a -->|calls| 2db711c0_6a20_c7ba_2a00_0a735185abd4
  style f0b817ef_eb04_6a82_be87_88371a15d57a fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/astro/src/core/app/validate-forwarded-headers.ts lines 19–93

export function validateForwardedHeaders(
	forwardedProtocol?: string,
	forwardedHost?: string,
	forwardedPort?: string,
	allowedDomains?: Partial<RemotePattern>[],
): { protocol?: string; host?: string; port?: string } {
	const result: { protocol?: string; host?: string; port?: string } = {};

	// Validate protocol
	if (forwardedProtocol) {
		if (allowedDomains && allowedDomains.length > 0) {
			const hasProtocolPatterns = allowedDomains.some((pattern) => pattern.protocol !== undefined);
			if (hasProtocolPatterns) {
				// Validate against allowedDomains patterns
				try {
					const testUrl = new URL(`${forwardedProtocol}://example.com`);
					const isAllowed = allowedDomains.some((pattern) => matchPattern(testUrl, pattern));
					if (isAllowed) {
						result.protocol = forwardedProtocol;
					}
				} catch {
					// Invalid protocol, omit from result
				}
			} else if (/^https?$/.test(forwardedProtocol)) {
				// allowedDomains exist but no protocol patterns, allow http/https
				result.protocol = forwardedProtocol;
			}
		} else if (/^https?$/.test(forwardedProtocol)) {
			// No allowedDomains, only allow http/https
			result.protocol = forwardedProtocol;
		}
	}

	// Validate port first
	if (forwardedPort && allowedDomains && allowedDomains.length > 0) {
		const hasPortPatterns = allowedDomains.some((pattern) => pattern.port !== undefined);
		if (hasPortPatterns) {
			// Validate against allowedDomains patterns
			const isAllowed = allowedDomains.some((pattern) => pattern.port === forwardedPort);
			if (isAllowed) {
				result.port = forwardedPort;
			}
		}
		// If no port patterns, reject the header (strict security default)
	}

	// Validate host (extract port from hostname for validation)
	// Reject empty strings and sanitize to prevent path injection
	if (forwardedHost && forwardedHost.length > 0 && allowedDomains && allowedDomains.length > 0) {
		const protoForValidation = result.protocol || 'https';
		const sanitized = sanitizeHost(forwardedHost);
		if (sanitized) {
			try {
				// Extract hostname without port for validation
				const hostnameOnly = sanitized.split(':')[0];
				// Use full hostname:port for validation so patterns with ports match correctly
				// Include validated port if available, otherwise use port from forwardedHost if present
				const portFromHost = sanitized.includes(':') ? sanitized.split(':')[1] : undefined;
				const portForValidation = result.port || portFromHost;
				const hostWithPort = portForValidation
					? `${hostnameOnly}:${portForValidation}`
					: hostnameOnly;
				const testUrl = new URL(`${protoForValidation}://${hostWithPort}`);
				const isAllowed = allowedDomains.some((pattern) => matchPattern(testUrl, pattern));
				if (isAllowed) {
					result.host = sanitized;
				}
			} catch {
				// Invalid host, omit from result
			}
		}
	}

	return result;
}