fix(@angular/ssr): introduce trustProxyHeaders option to safely validate and sanitize proxy headers

This commit adds the `trustProxyHeaders` option to `AngularAppEngineOptions` and `AngularNodeAppEngineOptions` to configure, validate, and sanitize `X-Forwarded-*` headers.
- When `trustProxyHeaders` is `undefined` (default):
  - Allows `X-Forwarded-Host` and `X-Forwarded-Proto`.
  - Intercepts `X-Forwarded-Prefix` and triggers a dynamic CSR deoptimization to skip SSR if present.
  - Logs an informative message when receiving any other `X-Forwarded-*` headers.
- When `false`:
  - Ignores and strips all proxy headers from the request.
- When `true`:
  - Trusts all proxy headers.
- When a string array:
  - Allows only the proxy headers provided inside the array.

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

// Or explicitly allow specific headers:
const engine = new AngularAppEngine({
  trustProxyHeaders: ['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[];
+    trustProxyHeaders?: 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, trustProxyHeaders?: 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 trustProxyHeaders?: 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.trustProxyHeaders = options?.trustProxyHeaders;
 
     attachNodeGlobalErrorHandlers();
   }
@@ -76,7 +78,9 @@ export class AngularNodeAppEngine {
     requestContext?: unknown,
   ): Promise<Response | null> {
     const webRequest =
-      request instanceof Request ? request : createWebRequestFromNodeRequest(request);
+      request instanceof Request
+        ? request
+        : createWebRequestFromNodeRequest(request, this.trustProxyHeaders);
 
     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 trustProxyHeaders - A boolean or an array of allowed proxy headers.
+ *
+ * @remarks
+ * When `trustProxyHeaders` 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,
+  trustProxyHeaders?: boolean | readonly string[],
 ): Request {
+  const trustProxyHeadersNormalized =
+    trustProxyHeaders && typeof trustProxyHeaders !== 'boolean'
+      ? new Set(trustProxyHeaders.map((h) => h.toLowerCase()))
+      : trustProxyHeaders;
+
   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, trustProxyHeadersNormalized), {
     method,
-    headers: createRequestHeaders(headers),
+    headers: createRequestHeaders(headers, trustProxyHeadersNormalized),
     body: withBody ? nodeRequest : undefined,
     duplex: withBody ? 'half' : undefined,
     referrer,
@@ -49,16 +68,27 @@ export function createWebRequestFromNodeRequest(
  * Creates a `Headers` object from Node.js `IncomingHttpHeaders`.
  *
  * @param nodeHeaders - The Node.js `IncomingHttpHeaders` object to convert.
+ * @param trustProxyHeaders - 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,
+  trustProxyHeaders: 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.toLowerCase().startsWith('x-forwarded-') &&
+      !isProxyHeaderAllowed(name.toLowerCase(), trustProxyHeaders)
+    ) {
+      continue;
+    }
+
     if (typeof value === 'string') {
       headers.append(name, value);
     } else if (Array.isArray(value)) {
@@ -75,32 +105,92 @@ 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 trustProxyHeaders - A boolean or a set of allowed proxy headers.
+ *
+ * @remarks
+ * When `trustProxyHeaders` 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,
+  trustProxyHeaders?: boolean | ReadonlySet<string>,
+): URL {
   const {
     headers,
     socket,
     url = '',
     originalUrl,
   } = nodeRequest as IncomingMessage & { originalUrl?: string };
+
   const protocol =
-    getFirstHeaderValue(headers['x-forwarded-proto']) ??
+    getAllowedProxyHeaderValue(headers, 'x-forwarded-proto', trustProxyHeaders) ??
     ('encrypted' in socket && socket.encrypted ? 'https' : 'http');
+
   const hostname =
-    getFirstHeaderValue(headers['x-forwarded-host']) ?? headers.host ?? headers[':authority'];
+    getAllowedProxyHeaderValue(headers, 'x-forwarded-host', trustProxyHeaders) ??
+    headers.host ??
+    headers[':authority'];
 
   if (Array.isArray(hostname)) {
     throw new Error('host value cannot be an array.');
   }
 
   let hostnameWithPort = hostname;
   if (!hostname?.includes(':')) {
-    const port = getFirstHeaderValue(headers['x-forwarded-port']);
+    const port = getAllowedProxyHeaderValue(headers, 'x-forwarded-port', trustProxyHeaders);
     if (port) {
       hostnameWithPort += `:${port}`;
     }
   }
 
   return new URL(`${protocol}://${hostnameWithPort}${originalUrl ?? url}`);
 }
+
+/**
+ * Gets the first value of an allowed proxy header.
+ *
+ * @param headers - The Node.js incoming HTTP headers.
+ * @param headerName - The name of the proxy header to retrieve.
+ * @param trustProxyHeaders - A boolean or a set of allowed proxy headers.
+ * @returns The value of the allowed proxy header, or `undefined` if not allowed or not present.
+ */
+function getAllowedProxyHeaderValue(
+  headers: IncomingHttpHeaders,
+  headerName: string,
+  trustProxyHeaders: boolean | ReadonlySet<string> | undefined,
+): string | undefined {
+  return isProxyHeaderAllowed(headerName, trustProxyHeaders)
+    ? getFirstHeaderValue(headers[headerName])
+    : undefined;
+}
+
+/**
+ * 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,
+  trustProxyHeaders: boolean | ReadonlySet<string> | undefined,
+): boolean {
+  if (trustProxyHeaders === undefined) {
+    const lower = headerName.toLowerCase();
+
+    return lower === 'x-forwarded-host' || lower === 'x-forwarded-proto';
+  }
+
+  if (trustProxyHeaders === false) {
+    return false;
+  }
+
+  if (trustProxyHeaders === true) {
+    return true;
+  }
+
+  return trustProxyHeaders.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 `trustProxyHeaders` 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`, proxy headers are ignored.
+   *
+   * @default undefined
+   */
+  trustProxyHeaders?: boolean | readonly string[];
 }
 
 /**
@@ -78,6 +94,11 @@ export class AngularAppEngine {
     this.manifest.supportedLocales,
   );
 
+  /**
+   * The normalized allowed proxy headers.
+   */
+  private readonly trustProxyHeaders: ReadonlySet<string> | boolean | undefined;
+
   /**
    * A cache that holds entry points, keyed by their potential locale string.
    */
@@ -89,6 +110,14 @@ export class AngularAppEngine {
    */
   constructor(options?: AngularAppEngineOptions) {
     this.allowedHosts = this.getAllowedHosts(options);
+
+    const trustProxyHeaders = options?.trustProxyHeaders;
+    this.trustProxyHeaders =
+      trustProxyHeaders === undefined
+        ? undefined
+        : typeof trustProxyHeaders === 'boolean'
+          ? trustProxyHeaders
+          : new Set(trustProxyHeaders.map((h) => h.toLowerCase()));
   }
 
   private getAllowedHosts(options: AngularAppEngineOptions | undefined): ReadonlySet<string> {
@@ -131,33 +160,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.trustProxyHeaders);
 
     try {
-      validateRequest(request, allowedHost, disableAllowedHostsCheck);
+      validateRequest(securedRequest, allowedHost, AngularAppEngine.ɵdisableAllowedHostsCheck);
     } catch (error) {
-      return this.handleValidationError(error as Error, request);
+      return this.handleValidationError(error as Error, securedRequest);
     }
 
-    // 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(error, securedRequest),
-          ),
-        );
-      }
-
-      promises.push(serverApp.handle(securedRequest, requestContext));
-
-      return Promise.race(promises);
+      return serverApp.handle(securedRequest, requestContext);
     }
 
     if (this.supportedLocales.length > 1) {

packages/angular/ssr/src/app.ts

@@ -190,7 +190,20 @@ export class AngularServerApp {
       return null;
     }
 
-    const { redirectTo, status, renderMode, headers } = matchedRoute;
+    const { redirectTo, status, renderMode, headers, preload } = matchedRoute;
+
+    if (request.headers.get('x-angular-deopt-csr') === 'true') {
+      let html = await this.assets.getServerAsset('index.csr.html').text();
+      html = await this.runTransformsOnHtml(html, url, preload);
+
+      return new Response(html, {
+        status: 200,
+        headers: new Headers({
+          'Content-Type': 'text/html;charset=UTF-8',
+          ...headers,
+        }),
+      });
+    }
 
     if (redirectTo !== undefined) {
       return createRedirectResponse(