@beignet/core 0.0.46 → 0.0.47

package/src/server/trusted-proxy-internal.ts

@@ -0,0 +1,41 @@
+import type { TrustedProxyConfig } from "./trusted-proxy.js";
+
+export function requireTrustedProxyHeaderName(
+  name: string,
+  optionName: string,
+): string {
+  const header = name.trim();
+  if (!header) {
+    throw new Error(`${optionName} must be a non-empty header name.`);
+  }
+
+  try {
+    new Headers().get(header);
+  } catch {
+    throw new Error(`${optionName} must be a valid HTTP header name.`);
+  }
+
+  return header;
+}
+
+export function assertValidTrustedProxyConfig(
+  config: TrustedProxyConfig,
+): void {
+  if (!config) return;
+
+  if (config.hostHeader !== undefined && config.hostHeader !== false) {
+    requireTrustedProxyHeaderName(config.hostHeader, "trustedProxy.hostHeader");
+  }
+  if (config.protocolHeader !== undefined && config.protocolHeader !== false) {
+    requireTrustedProxyHeaderName(
+      config.protocolHeader,
+      "trustedProxy.protocolHeader",
+    );
+  }
+  if (typeof config.clientIp === "object") {
+    requireTrustedProxyHeaderName(
+      config.clientIp.header,
+      "trustedProxy.clientIp.header",
+    );
+  }
+}

package/src/server/trusted-proxy.ts

@@ -1,4 +1,5 @@
 import type { HttpRequestLike } from "./http.js";
+import { requireTrustedProxyHeaderName } from "./trusted-proxy-internal.js";
 
 /**
  * Header source used to resolve a client IP after an app has explicitly opted
@@ -51,27 +52,32 @@ export interface TrustedRequestInfo {
   /**
    * URL as seen by the app or reconstructed from trusted proxy headers.
    */
-  url: URL;
+  readonly url: Readonly<URL>;
   /**
    * External request origin.
    */
-  origin: string;
+  readonly origin: string;
   /**
    * External request protocol without a trailing colon.
    */
-  protocol: "http" | "https";
+  readonly protocol: "http" | "https";
   /**
    * External request host, including port when present.
    */
-  host: string;
+  readonly host: string;
   /**
    * Resolved client IP when a trusted client-IP source is configured.
    */
-  clientIp?: string;
+  readonly clientIp?: string;
+  /**
+   * Whether the server policy configured a trusted client-IP source. This can
+   * be true while `clientIp` is absent when the expected header is missing.
+   */
+  readonly clientIpTrusted: boolean;
   /**
    * Whether forwarding headers were eligible to affect this result.
    */
-  trustedProxy: boolean;
+  readonly trustedProxy: boolean;
 }
 
 const DEFAULT_PROTOCOL_HEADER = "x-forwarded-proto";
@@ -92,14 +98,6 @@ function firstHeaderValue(
   return splitForwardedHeader(req.headers.get(header))[0];
 }
 
-function requireHeaderName(name: string, optionName: string): string {
-  const header = name.trim();
-  if (!header) {
-    throw new Error(`${optionName} must be a non-empty header name.`);
-  }
-  return header;
-}
-
 function normalizeProtocol(
   value: string | undefined,
 ): "http" | "https" | undefined {
@@ -172,7 +170,10 @@ export function resolveTrustedClientIp(
   if (typeof source === "object") {
     return firstHeaderValue(
       req,
-      requireHeaderName(source.header, "trustedProxy.clientIp.header"),
+      requireTrustedProxyHeaderName(
+        source.header,
+        "trustedProxy.clientIp.header",
+      ),
     );
   }
 
@@ -205,6 +206,7 @@ export function resolveTrustedRequest(
       origin: baseUrl.origin,
       protocol: baseProtocol,
       host: baseHost,
+      clientIpTrusted: false,
       trustedProxy: false,
     };
   }
@@ -212,14 +214,14 @@ export function resolveTrustedRequest(
   const protocolHeader =
     config.protocolHeader === false
       ? undefined
-      : requireHeaderName(
+      : requireTrustedProxyHeaderName(
           config.protocolHeader ?? DEFAULT_PROTOCOL_HEADER,
           "trustedProxy.protocolHeader",
         );
   const hostHeader =
     config.hostHeader === false
       ? undefined
-      : requireHeaderName(
+      : requireTrustedProxyHeaderName(
           config.hostHeader ?? DEFAULT_HOST_HEADER,
           "trustedProxy.hostHeader",
         );
@@ -244,6 +246,7 @@ export function resolveTrustedRequest(
     protocol,
     host,
     ...(clientIp !== undefined ? { clientIp } : {}),
+    clientIpTrusted: Boolean(config.clientIp),
     trustedProxy: true,
   };
 }