refactor(@angular/ssr): enforce explicit opt-in for proxy headers

This commit introduces a secure-by-default model for trusting proxy
headers (`X-Forwarded-*`) in the `@angular/ssr` package. Previously, the
engine relied on complex lazy header patching and regex filters to guard
against spoofed headers. However, implicit decoding behaviors by URL
constructors can render naive regex filtering ineffective against certain
percent-encoded payloads.

To harden the engine against Server-Side Request Forgery (SSRF) and
header-spoofing attacks:
- Introduced the `allowedProxyHeaders` configuration option to
  `AngularAppEngineOptions` and `AngularNodeAppEngineOptions`.
- By default (`false`), all incoming `X-Forwarded-*` headers are aggressively
  scrubbed unless explicitly whitelisted via `allowedProxyHeaders`.
- Replaced the lazy `cloneRequestAndPatchHeaders` utility with a simplified,
  eager `sanitizeRequestHeaders` that centralizes the header scrubbing logic.
- Hardened `verifyHostAllowed` to definitively reject parsed hosts that successfully
  carry path, search, hash, or auth components, replacing previously fallible
  regex filters for stringently checked hosts.

BREAKING CHANGE:

The `@angular/ssr` package now ignores all `X-Forwarded-*` proxy headers by default. If your application relies on these headers (e.g., for resolving absolute URLs, trust proxy, or custom proxy-related logic), you must explicitly allow them using the new `allowedProxyHeaders` option in the application server configuration.

Example:
```ts
const engine = new AngularAppEngine({
  // Allow all proxy headers
  allowedProxyHeaders: true,
});

// Or explicitly allow specific headers:
const engine = new AngularAppEngine({
  allowedProxyHeaders: ['x-forwarded-host', 'x-forwarded-prefix'],
});
```

Author: alan-agius4

goldens/public-api/angular/ssr/index.api.md

@@ -22,6 +22,7 @@ export class AngularAppEngine {
 // @public
 export interface AngularAppEngineOptions {
     allowedHosts?: readonly string[];
+    allowedProxyHeaders?: boolean | readonly string[];
 }
 
 // @public

goldens/public-api/angular/ssr/node/index.api.md

@@ -55,7 +55,7 @@ export interface CommonEngineRenderOptions {
 export function createNodeRequestHandler<T extends NodeRequestHandlerFunction>(handler: T): T;
 
 // @public
-export function createWebRequestFromNodeRequest(nodeRequest: IncomingMessage | Http2ServerRequest): Request;
+export function createWebRequestFromNodeRequest(nodeRequest: IncomingMessage | Http2ServerRequest, allowedProxyHeaders?: boolean | readonly string[]): Request;
 
 // @public
 export function isMainModule(url: string): boolean;

packages/angular/ssr/node/src/app-engine.ts

@@ -29,6 +29,7 @@ export interface AngularNodeAppEngineOptions extends AngularAppEngineOptions {}
  */
 export class AngularNodeAppEngine {
   private readonly angularAppEngine: AngularAppEngine;
+  private readonly allowedProxyHeaders?: boolean | readonly string[];
 
   /**
    * Creates a new instance of the Angular Node.js server application engine.
@@ -39,6 +40,7 @@ export class AngularNodeAppEngine {
       ...options,
       allowedHosts: [...getAllowedHostsFromEnv(), ...(options?.allowedHosts ?? [])],
     });
+    this.allowedProxyHeaders = options?.allowedProxyHeaders;
 
     attachNodeGlobalErrorHandlers();
   }
@@ -75,7 +77,9 @@ export class AngularNodeAppEngine {
     requestContext?: unknown,
   ): Promise<Response | null> {
     const webRequest =
-      request instanceof Request ? request : createWebRequestFromNodeRequest(request);
+      request instanceof Request
+        ? request
+        : createWebRequestFromNodeRequest(request, this.allowedProxyHeaders);
 
     return this.angularAppEngine.handle(webRequest, requestContext);
   }

packages/angular/ssr/node/src/request.ts

@@ -17,7 +17,13 @@ import { getFirstHeaderValue } from '../../src/utils/validation';
  * as they are not allowed to be set directly using the `Node.js` Undici API or
  * the web `Headers` API.
  */
-const HTTP2_PSEUDO_HEADERS = new Set([':method', ':scheme', ':authority', ':path', ':status']);
+const HTTP2_PSEUDO_HEADERS: ReadonlySet<string> = new Set([
+  ':method',
+  ':scheme',
+  ':authority',
+  ':path',
+  ':status',
+]);
 
 /**
  * Converts a Node.js `IncomingMessage` or `Http2ServerRequest` into a
@@ -27,18 +33,31 @@ const HTTP2_PSEUDO_HEADERS = new Set([':method', ':scheme', ':authority', ':path
  * be used by web platform APIs.
  *
  * @param nodeRequest - The Node.js request object (`IncomingMessage` or `Http2ServerRequest`) to convert.
+ * @param allowedProxyHeaders - A boolean or an array of allowed proxy headers.
+ *
+ * @remarks
+ * When `allowedProxyHeaders` is enabled, headers such as `X-Forwarded-Host` and
+ * `X-Forwarded-Prefix` should ideally be strictly validated at a higher infrastructure
+ * level (e.g., at the reverse proxy or API gateway) before reaching the application.
+ *
  * @returns A Web Standard `Request` object.
  */
 export function createWebRequestFromNodeRequest(
   nodeRequest: IncomingMessage | Http2ServerRequest,
+  allowedProxyHeaders?: boolean | readonly string[],
 ): Request {
+  const allowedProxyHeadersNormalized =
+    allowedProxyHeaders && typeof allowedProxyHeaders !== 'boolean'
+      ? new Set(allowedProxyHeaders.map((h) => h.toLowerCase()))
+      : allowedProxyHeaders;
+
   const { headers, method = 'GET' } = nodeRequest;
   const withBody = method !== 'GET' && method !== 'HEAD';
   const referrer = headers.referer && URL.canParse(headers.referer) ? headers.referer : undefined;
 
-  return new Request(createRequestUrl(nodeRequest), {
+  return new Request(createRequestUrl(nodeRequest, allowedProxyHeadersNormalized), {
     method,
-    headers: createRequestHeaders(headers),
+    headers: createRequestHeaders(headers, allowedProxyHeadersNormalized),
     body: withBody ? nodeRequest : undefined,
     duplex: withBody ? 'half' : undefined,
     referrer,
@@ -49,16 +68,24 @@ export function createWebRequestFromNodeRequest(
  * Creates a `Headers` object from Node.js `IncomingHttpHeaders`.
  *
  * @param nodeHeaders - The Node.js `IncomingHttpHeaders` object to convert.
+ * @param allowedProxyHeaders - A boolean or a set of allowed proxy headers.
  * @returns A `Headers` object containing the converted headers.
  */
-function createRequestHeaders(nodeHeaders: IncomingHttpHeaders): Headers {
+function createRequestHeaders(
+  nodeHeaders: IncomingHttpHeaders,
+  allowedProxyHeaders: boolean | ReadonlySet<string> | undefined,
+): Headers {
   const headers = new Headers();
 
   for (const [name, value] of Object.entries(nodeHeaders)) {
     if (HTTP2_PSEUDO_HEADERS.has(name)) {
       continue;
     }
 
+    if (name.startsWith('x-forwarded-') && !isProxyHeaderAllowed(name, allowedProxyHeaders)) {
+      continue;
+    }
+
     if (typeof value === 'string') {
       headers.append(name, value);
     } else if (Array.isArray(value)) {
@@ -75,27 +102,43 @@ function createRequestHeaders(nodeHeaders: IncomingHttpHeaders): Headers {
  * Creates a `URL` object from a Node.js `IncomingMessage`, taking into account the protocol, host, and port.
  *
  * @param nodeRequest - The Node.js `IncomingMessage` or `Http2ServerRequest` object to extract URL information from.
+ * @param allowedProxyHeaders - A boolean or a set of allowed proxy headers.
+ *
+ * @remarks
+ * When `allowedProxyHeaders` is enabled, headers such as `X-Forwarded-Host` and
+ * `X-Forwarded-Prefix` should ideally be strictly validated at a higher infrastructure
+ * level (e.g., at the reverse proxy or API gateway) before reaching the application.
+ *
  * @returns A `URL` object representing the request URL.
  */
-export function createRequestUrl(nodeRequest: IncomingMessage | Http2ServerRequest): URL {
+export function createRequestUrl(
+  nodeRequest: IncomingMessage | Http2ServerRequest,
+  allowedProxyHeaders?: boolean | ReadonlySet<string>,
+): URL {
   const {
     headers,
     socket,
     url = '',
     originalUrl,
   } = nodeRequest as IncomingMessage & { originalUrl?: string };
+
   const protocol =
-    getFirstHeaderValue(headers['x-forwarded-proto']) ??
-    ('encrypted' in socket && socket.encrypted ? 'https' : 'http');
+    (isProxyHeaderAllowed('x-forwarded-proto', allowedProxyHeaders)
+      ? getFirstHeaderValue(headers['x-forwarded-proto'])
+      : undefined) ?? ('encrypted' in socket && socket.encrypted ? 'https' : 'http');
   const hostname =
-    getFirstHeaderValue(headers['x-forwarded-host']) ?? headers.host ?? headers[':authority'];
+    (isProxyHeaderAllowed('x-forwarded-host', allowedProxyHeaders)
+      ? getFirstHeaderValue(headers['x-forwarded-host'])
+      : undefined) ??
+    headers.host ??
+    headers[':authority'];
 
   if (Array.isArray(hostname)) {
     throw new Error('host value cannot be an array.');
   }
 
   let hostnameWithPort = hostname;
-  if (!hostname?.includes(':')) {
+  if (!hostname?.includes(':') && isProxyHeaderAllowed('x-forwarded-port', allowedProxyHeaders)) {
     const port = getFirstHeaderValue(headers['x-forwarded-port']);
     if (port) {
       hostnameWithPort += `:${port}`;
@@ -104,3 +147,25 @@ export function createRequestUrl(nodeRequest: IncomingMessage | Http2ServerReque
 
   return new URL(`${protocol}://${hostnameWithPort}${originalUrl ?? url}`);
 }
+
+/**
+ * Checks if a specific proxy header is allowed.
+ *
+ * @param headerName - The name of the proxy header to check.
+ * @param allowedProxyHeaders - A boolean or a set of allowed proxy headers.
+ * @returns `true` if the header is allowed, `false` otherwise.
+ */
+function isProxyHeaderAllowed(
+  headerName: string,
+  allowedProxyHeaders?: boolean | ReadonlySet<string>,
+): boolean {
+  if (!allowedProxyHeaders) {
+    return false;
+  }
+
+  if (allowedProxyHeaders === true) {
+    return true;
+  }
+
+  return allowedProxyHeaders.has(headerName.toLowerCase());
+}

packages/angular/ssr/node/test/request_spec.ts

@@ -137,6 +137,7 @@ describe('createRequestUrl', () => {
         },
         url: '/test',
       }),
+      true,
     );
     expect(url.href).toBe('https://example.com/test');
   });
@@ -152,6 +153,7 @@ describe('createRequestUrl', () => {
         },
         url: '/test',
       }),
+      true,
     );
     expect(url.href).toBe('https://example.com:8443/test');
   });

packages/angular/ssr/src/app-engine.ts

@@ -12,7 +12,7 @@ import { getPotentialLocaleIdFromUrl, getPreferredLocale } from './i18n';
 import { EntryPointExports, getAngularAppEngineManifest } from './manifest';
 import { createRedirectResponse } from './utils/redirect';
 import { joinUrlParts } from './utils/url';
-import { cloneRequestAndPatchHeaders, validateRequest } from './utils/validation';
+import { sanitizeRequestHeaders, validateRequest } from './utils/validation';
 
 /**
  * Options for the Angular server application engine.
@@ -22,6 +22,22 @@ export interface AngularAppEngineOptions {
    * A set of allowed hostnames for the server application.
    */
   allowedHosts?: readonly string[];
+
+  /**
+   * Extends the scope of trusted proxy headers (`X-Forwarded-*`).
+   *
+   * @remarks
+   * When `allowedProxyHeaders` is enabled, headers such as `X-Forwarded-Host` and
+   * `X-Forwarded-Prefix` should ideally be strictly validated at a higher infrastructure
+   * level (e.g., at the reverse proxy or API gateway) before reaching the application.
+   *
+   * If a `string[]` is provided, only those proxy headers are allowed.
+   * If `true`, all proxy headers are allowed.
+   * If `false` or not provided, proxy headers are ignored.
+   *
+   * @default false
+   */
+  allowedProxyHeaders?: boolean | readonly string[];
 }
 
 /**
@@ -78,6 +94,11 @@ export class AngularAppEngine {
     this.manifest.supportedLocales,
   );
 
+  /**
+   * The resolved allowed proxy headers.
+   */
+  private readonly allowedProxyHeaders: ReadonlySet<string> | boolean;
+
   /**
    * A cache that holds entry points, keyed by their potential locale string.
    */
@@ -89,6 +110,12 @@ export class AngularAppEngine {
    */
   constructor(options?: AngularAppEngineOptions) {
     this.allowedHosts = this.getAllowedHosts(options);
+
+    const allowedProxyHeaders = options?.allowedProxyHeaders ?? false;
+    this.allowedProxyHeaders =
+      typeof allowedProxyHeaders === 'boolean'
+        ? allowedProxyHeaders
+        : new Set(allowedProxyHeaders.map((h) => h.toLowerCase()));
   }
 
   private getAllowedHosts(options: AngularAppEngineOptions | undefined): ReadonlySet<string> {
@@ -132,32 +159,17 @@ export class AngularAppEngine {
   async handle(request: Request, requestContext?: unknown): Promise<Response | null> {
     const allowedHost = this.allowedHosts;
     const disableAllowedHostsCheck = AngularAppEngine.ɵdisableAllowedHostsCheck;
+    const securedRequest = sanitizeRequestHeaders(request, this.allowedProxyHeaders);
 
     try {
-      validateRequest(request, allowedHost, disableAllowedHostsCheck);
+      validateRequest(securedRequest, allowedHost, disableAllowedHostsCheck);
     } catch (error) {
-      return this.handleValidationError(request.url, error as Error);
+      return this.handleValidationError(securedRequest.url, error as Error);
     }
 
-    // Clone request with patched headers to prevent unallowed host header access.
-    const { request: securedRequest, onError: onHeaderValidationError } = disableAllowedHostsCheck
-      ? { request, onError: null }
-      : cloneRequestAndPatchHeaders(request, allowedHost);
-
     const serverApp = await this.getAngularServerAppForRequest(securedRequest);
     if (serverApp) {
-      const promises: Promise<Response | null>[] = [];
-      if (onHeaderValidationError) {
-        promises.push(
-          onHeaderValidationError.then((error) =>
-            this.handleValidationError(securedRequest.url, error),
-          ),
-        );
-      }
-
-      promises.push(serverApp.handle(securedRequest, requestContext));
-
-      return Promise.race(promises);
+      return serverApp.handle(securedRequest, requestContext);
     }
 
     if (this.supportedLocales.length > 1) {