@beignet/core 0.0.45 → 0.0.47

package/src/server/server.ts

@@ -73,6 +73,12 @@ import {
 } from "./route-matching.js";
 import type { RuntimeIntegrityCheck } from "./runtime-integrity.js";
 import { runRuntimeIntegrityCheck } from "./runtime-integrity.js";
+import {
+  resolveTrustedRequest,
+  type TrustedProxyConfig,
+  type TrustedRequestInfo,
+} from "./trusted-proxy.js";
+import { assertValidTrustedProxyConfig } from "./trusted-proxy-internal.js";
 import {
   createUseCaseRouteHandler,
   isUseCaseRouteDef,
@@ -107,6 +113,15 @@ type AnyServiceProvider = ServiceProvider<
   any
 >;
 
+function copyTrustedRequestInfo(
+  requestInfo: TrustedRequestInfo,
+): TrustedRequestInfo {
+  return {
+    ...requestInfo,
+    url: new URL(requestInfo.url),
+  };
+}
+
 /**
  * Options for creating a Beignet server instance.
  */
@@ -155,6 +170,14 @@ export type CreateServerOptions<
     Ports & InferProviderPorts<Providers>,
     ServiceInput
   >;
+  /**
+   * Explicit policy for trusting proxy- or edge-provided request metadata.
+   *
+   * Forwarding headers are ignored by default. Configure this only when every
+   * request reaches the app through a trusted platform or reverse proxy that
+   * strips or normalizes those headers.
+   */
+  trustedProxy?: TrustedProxyConfig;
   /**
    * Server hooks that wrap every registered route.
    */
@@ -387,10 +410,12 @@ export async function createServer<
     ...((options.hooks ?? []) as ServerHook<Ctx, FinalPorts>[]),
   ];
   const contracts = options.routes ? contractsFromRoutes(options.routes) : [];
+  const trustedProxy = options.trustedProxy ?? false;
+  assertValidTrustedProxyConfig(trustedProxy);
 
   // Fail startup on hook misconfiguration before provider setup runs.
   for (const hook of hooks) {
-    hook.validate?.({ contracts });
+    hook.validate?.({ contracts, trustedProxy });
   }
 
   const resolvedContext = resolveServerContext<Ctx, FinalPorts, ServiceInput>(
@@ -403,11 +428,13 @@ export async function createServer<
   const createRequestContext = async (
     req: HttpRequestLike,
     contract?: HttpContractConfig,
+    requestInfo: TrustedRequestInfo = resolveTrustedRequest(req, trustedProxy),
   ): Promise<Ctx> => {
     const { requestId, trace } = instrumentation.prepareRequest(req);
     return finalizeContext(
       await resolvedContext.request({
         req,
+        requestInfo: copyTrustedRequestInfo(requestInfo),
         ports: finalPorts,
         contract,
         requestId,
@@ -502,6 +529,8 @@ export async function createServer<
   const contextRuntime = {
     createRequestContext,
     finalizeContext,
+    resolveRequestInfo: (req: HttpRequestLike) =>
+      resolveTrustedRequest(req, trustedProxy),
   };
 
   let serviceContextsAvailable = false;

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,
   };
 }