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.

Author: alan-agius4

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

@@ -14,12 +14,14 @@ export class AngularAppEngine {
     constructor(options?: AngularAppEngineOptions);
     handle(request: Request, requestContext?: unknown): Promise<Response | null>;
     static ɵallowStaticRouteRender: boolean;
+    static ɵdisableAllowedHostsCheck: boolean;
     static ɵhooks: Hooks;
 }
 
 // @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

@@ -30,6 +30,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.
@@ -40,6 +41,7 @@ export class AngularNodeAppEngine {
       ...options,
       allowedHosts: [...getAllowedHostsFromEnv(), ...(options?.allowedHosts ?? [])],
     });
+    this.trustProxyHeaders = options?.trustProxyHeaders;
   }
 
   /**
@@ -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.trustProxyHeaders);
 
     return this.angularAppEngine.handle(webRequest, requestContext);
   }

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

@@ -8,7 +8,11 @@
 
 import type { IncomingHttpHeaders, IncomingMessage } from 'node:http';
 import type { Http2ServerRequest } from 'node:http2';
-import { getFirstHeaderValue } from '../../src/utils/validation';
+import {
+  getFirstHeaderValue,
+  isProxyHeaderAllowed,
+  normalizeTrustProxyHeaders,
+} from '../../src/utils/validation';
 
 /**
  * A set containing all the pseudo-headers defined in the HTTP/2 specification.
@@ -17,7 +21,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,16 +37,25 @@ 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 proxy headers to trust when constructing the request URL.
+ *
+ * @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.
  * @developerPreview
  */
 export function createWebRequestFromNodeRequest(
   nodeRequest: IncomingMessage | Http2ServerRequest,
+  trustProxyHeaders?: boolean | readonly string[],
 ): Request {
+  const trustProxyHeadersNormalized = normalizeTrustProxyHeaders(trustProxyHeaders);
   const { headers, method = 'GET' } = nodeRequest;
   const withBody = method !== 'GET' && method !== 'HEAD';
 
-  return new Request(createRequestUrl(nodeRequest), {
+  return new Request(createRequestUrl(nodeRequest, trustProxyHeadersNormalized), {
     method,
     headers: createRequestHeaders(headers),
     body: withBody ? nodeRequest : undefined,
@@ -74,32 +93,64 @@ 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 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: 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 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: ReadonlySet<string>,
+): string | undefined {
+  return isProxyHeaderAllowed(headerName, trustProxyHeaders)
+    ? getFirstHeaderValue(headers[headerName])
+    : undefined;
+}

packages/angular/ssr/node/test/BUILD.bazel

@@ -7,6 +7,7 @@ ts_project(
     srcs = glob(["**/*_spec.ts"]),
     deps = [
         "//:node_modules/@types/node",
+        "//packages/angular/ssr",
         "//packages/angular/ssr/node",
     ],
 )

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

@@ -7,8 +7,8 @@
  */
 
 import { IncomingMessage } from 'node:http';
-import { Http2ServerRequest } from 'node:http2';
 import { Socket } from 'node:net';
+import { normalizeTrustProxyHeaders } from '../../src/utils/validation';
 import { createRequestUrl } from '../src/request';
 
 // Helper to create a mock request object for testing.
@@ -26,25 +26,14 @@ function createRequest(details: {
   } as unknown as IncomingMessage;
 }
 
-// Helper to create a mock Http2ServerRequest object for testing.
-function createHttp2Request(details: {
-  headers: Record<string, string | string[] | undefined>;
-  url?: string;
-}): Http2ServerRequest {
-  return {
-    headers: details.headers,
-    socket: new Socket(),
-    url: details.url,
-  } as Http2ServerRequest;
-}
-
 describe('createRequestUrl', () => {
   it('should create a http URL with hostname and port from the host header', () => {
     const url = createRequestUrl(
       createRequest({
         headers: { host: 'localhost:8080' },
         url: '/test',
       }),
+      new Set(),
     );
     expect(url.href).toBe('http://localhost:8080/test');
   });
@@ -56,6 +45,7 @@ describe('createRequestUrl', () => {
         encryptedSocket: true,
         url: '/test',
       }),
+      new Set(),
     );
     expect(url.href).toBe('https://example.com/test');
   });
@@ -67,6 +57,7 @@ describe('createRequestUrl', () => {
         encryptedSocket: true,
         url: '',
       }),
+      new Set(),
     );
     expect(url.href).toBe('https://example.com/');
   });
@@ -78,6 +69,7 @@ describe('createRequestUrl', () => {
         encryptedSocket: true,
         url: '/test?a=1',
       }),
+      new Set(),
     );
     expect(url.href).toBe('https://example.com/test?a=1');
   });
@@ -90,6 +82,7 @@ describe('createRequestUrl', () => {
         url: '/test',
         originalUrl: '/original',
       }),
+      new Set(),
     );
     expect(url.href).toBe('https://example.com/original');
   });
@@ -102,6 +95,7 @@ describe('createRequestUrl', () => {
         url: undefined,
         originalUrl: undefined,
       }),
+      new Set(),
     );
     expect(url.href).toBe('https://example.com/');
   });
@@ -112,6 +106,7 @@ describe('createRequestUrl', () => {
         headers: { host: 'localhost:8080' },
         url: '//example.com/test',
       }),
+      new Set(),
     );
     expect(url.href).toBe('http://localhost:8080//example.com/test');
   });
@@ -123,6 +118,7 @@ describe('createRequestUrl', () => {
         url: '/test',
         originalUrl: '//example.com/original',
       }),
+      new Set(),
     );
     expect(url.href).toBe('http://localhost:8080//example.com/original');
   });
@@ -137,6 +133,7 @@ describe('createRequestUrl', () => {
         },
         url: '/test',
       }),
+      normalizeTrustProxyHeaders(true),
     );
     expect(url.href).toBe('https://example.com/test');
   });
@@ -152,6 +149,7 @@ describe('createRequestUrl', () => {
         },
         url: '/test',
       }),
+      normalizeTrustProxyHeaders(true),
     );
     expect(url.href).toBe('https://example.com:8443/test');
   });