@beignet/core 0.0.46 → 0.0.48

package/src/server/hooks/logging.ts

@@ -3,6 +3,10 @@
  */
 
 import type { HttpContractConfig } from "../../contracts/index.js";
+import {
+  resolveTrustedRequest,
+  type TrustedRequestInfo,
+} from "../trusted-proxy.js";
 import type { HttpRequestLike, ServerHook } from "../types.js";
 import { getRequestIdFromContext } from "./utils.js";
 
@@ -46,6 +50,7 @@ export interface LoggingConfig<Ctx> {
   onRequestStart?: (args: {
     ctx?: Ctx;
     req: HttpRequestLike;
+    requestInfo: TrustedRequestInfo;
     contract?: HttpContractConfig;
   }) => void;
   /**
@@ -54,6 +59,7 @@ export interface LoggingConfig<Ctx> {
   onRequestEnd?: (args: {
     ctx?: Ctx;
     req: HttpRequestLike;
+    requestInfo: TrustedRequestInfo;
     res: { status: number; headers: Record<string, string> };
     durationMs: number;
     contract?: HttpContractConfig;
@@ -61,6 +67,13 @@ export interface LoggingConfig<Ctx> {
   }) => void;
 }
 
+function loggingRequestInfo(
+  req: HttpRequestLike,
+  requestInfo: TrustedRequestInfo | undefined,
+): TrustedRequestInfo {
+  return requestInfo ?? resolveTrustedRequest(req);
+}
+
 /**
  * Create request logging hooks.
  *
@@ -74,10 +87,15 @@ export function createLoggingHooks<Ctx>(
 
   return {
     name: "logging",
-    onRequest: ({ req, contract }) => {
+    onRequest: ({ req, requestInfo, contract }) => {
       if (config.onRequestStart) {
         try {
-          config.onRequestStart({ req, contract, ctx: undefined });
+          config.onRequestStart({
+            req,
+            requestInfo: loggingRequestInfo(req, requestInfo),
+            contract,
+            ctx: undefined,
+          });
         } catch {
           // Ignore logging errors
         }
@@ -86,9 +104,11 @@ export function createLoggingHooks<Ctx>(
 
       if (!config.logger) return undefined;
       try {
-        const url = new URL(req.url);
         config.logger.info(
-          { method: req.method, url: url.pathname },
+          {
+            method: req.method,
+            url: loggingRequestInfo(req, requestInfo).url.pathname,
+          },
           "Request start",
         );
       } catch {
@@ -114,13 +134,22 @@ export function createLoggingHooks<Ctx>(
           },
         }
       : {}),
-    afterSend: ({ ctx, req, response, durationMs, contract, error }) => {
+    afterSend: ({
+      ctx,
+      req,
+      requestInfo,
+      response,
+      durationMs,
+      contract,
+      error,
+    }) => {
       const headers = response.headers ?? {};
       if (config.onRequestEnd) {
         try {
           config.onRequestEnd({
             ctx,
             req,
+            requestInfo: loggingRequestInfo(req, requestInfo),
             res: { status: response.status, headers },
             durationMs,
             contract,
@@ -134,11 +163,10 @@ export function createLoggingHooks<Ctx>(
 
       if (!config.logger) return;
       try {
-        const url = new URL(req.url);
         const requestId = getRequestIdFromContext(ctx);
         const payload = {
           method: req.method,
-          url: url.pathname,
+          url: loggingRequestInfo(req, requestInfo).url.pathname,
           status: response.status,
           durationMs: Math.round(durationMs),
           ...(requestId !== undefined ? { requestId } : {}),

package/src/server/hooks/rate-limit.ts

@@ -13,6 +13,7 @@ import {
   resolveTrustedClientIp,
   type TrustedProxyClientIpSource,
   type TrustedProxyConfig,
+  type TrustedRequestInfo,
 } from "../trusted-proxy.js";
 import type { HttpRequestLike, ServerHook } from "../types.js";
 
@@ -78,16 +79,16 @@ export interface RateLimitOptions<Ctx> {
    * Resolve the client IP for `ip`-scoped limits.
    *
    * There is no default: when any contract declares an `ip`-scoped rate limit
-   * and neither `trustedProxy.clientIp`, `ipSource`, nor a custom `earlyKey`
-   * is configured, the hook fails at startup. Prefer `trustedProxy.clientIp`
-   * for production proxy headers; keep `ipSource` for custom keying or
-   * compatibility, or pass `"none"` to explicitly accept one shared
-   * `ip:unknown` bucket for all clients.
+   * and neither the server-level `trustedProxy.clientIp`,
+   * this hook's `trustedProxy.clientIp`, `ipSource`, nor a custom `earlyKey`
+   * is configured, the hook fails at startup. Prefer the server-level policy
+   * for production proxy headers; keep these hook-local options for an
+   * intentional override or custom keying.
    */
   ipSource?: RateLimitIpSource;
   /**
-   * Shared trusted-proxy policy used to resolve client IPs when `ipSource` is
-   * not set.
+   * Hook-local trusted-proxy policy used to resolve client IPs when
+   * `ipSource` is not set. This overrides the server-level policy.
    *
    * Configure this only when the app is always behind a platform or reverse
    * proxy that strips or normalizes forwarding headers. For `ip`-scoped rate
@@ -257,23 +258,32 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
   const { ipSource, trustedProxy } = options;
   const getClientIp = (
     req: HttpRequestLike,
+    requestInfo: TrustedRequestInfo | undefined,
     contractName: string,
   ): string | undefined => {
     if (ipSource !== undefined) {
       return resolveClientIp(req, ipSource);
     }
-    if (hasTrustedProxyClientIp(trustedProxy) && trustedProxy) {
-      return resolveTrustedClientIp(req, trustedProxy.clientIp);
+    if (trustedProxy !== undefined) {
+      if (hasTrustedProxyClientIp(trustedProxy) && trustedProxy) {
+        return resolveTrustedClientIp(req, trustedProxy.clientIp);
+      }
+      throw ipSourceConfigurationError(formatContractNames([contractName]));
+    }
+    if (requestInfo?.clientIpTrusted) {
+      return requestInfo.clientIp;
     }
     throw ipSourceConfigurationError(formatContractNames([contractName]));
   };
 
   return {
     name: "rate-limit",
-    validate: ({ contracts }) => {
+    validate: ({ contracts, trustedProxy: serverTrustedProxy }) => {
       if (
         ipSource !== undefined ||
-        hasTrustedProxyClientIp(trustedProxy) ||
+        hasTrustedProxyClientIp(
+          trustedProxy !== undefined ? trustedProxy : serverTrustedProxy,
+        ) ||
         options.earlyKey
       ) {
         return;
@@ -286,7 +296,7 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
       }
       throw ipSourceConfigurationError(formatContractNames(ipScoped));
     },
-    onRequest: async ({ contract, ports, req }) => {
+    onRequest: async ({ contract, ports, req, requestInfo }) => {
       const rlMeta = contract.metadata?.rateLimit;
       if (!rlMeta) {
         return undefined;
@@ -300,7 +310,7 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
       const key =
         options.earlyKey?.({ req, scope }) ??
         defaultEarlyRateLimitKey({ req, scope }, (r) =>
-          getClientIp(r, contract.name),
+          getClientIp(r, requestInfo, contract.name),
         );
 
       await enforceRateLimit(ports, {
@@ -312,7 +322,7 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
 
       return undefined;
     },
-    beforeHandle: async ({ ctx, contract, req }) => {
+    beforeHandle: async ({ ctx, contract, req, requestInfo }) => {
       const rlMeta = contract.metadata?.rateLimit;
       if (!rlMeta) {
         return undefined;
@@ -326,7 +336,7 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
       const key =
         options.key?.({ ctx, req, scope }) ??
         defaultRateLimitKey({ ctx, req, scope }, (r) =>
-          getClientIp(r, contract.name),
+          getClientIp(r, requestInfo, contract.name),
         );
 
       await enforceRateLimit(ctx.ports, {

package/src/server/hooks/security.ts

@@ -154,12 +154,13 @@ export interface CsrfHooksOptions {
    */
   token?: false | CsrfTokenOptions;
   /**
-   * Shared trusted-proxy policy used when comparing the request's external
-   * origin against `Origin` or `Referer`.
+   * Hook-local trusted-proxy policy used when comparing the request's external
+   * origin against `Origin` or `Referer`. This overrides the server-level
+   * policy.
    *
    * Configure this only when the app is always behind a platform or reverse
    * proxy that strips or normalizes forwarding headers. Without this option,
-   * CSRF uses `req.url` exactly as the adapter provided it.
+   * CSRF uses the `requestInfo` resolved by `createServer(...)`.
    */
   trustedProxy?: TrustedProxyConfig;
   /**
@@ -410,7 +411,7 @@ function enforceOrigin(args: {
   contract: HttpContractConfig;
   allowMissingOrigin: boolean;
   trustedOrigins: CsrfHooksOptions["trustedOrigins"];
-  trustedProxy: TrustedProxyConfig | undefined;
+  requestOrigin: string;
 }): void {
   const origin = originFromRequestHeaders(args.req);
   if (!origin) {
@@ -426,7 +427,7 @@ function enforceOrigin(args: {
       origin,
       req: args.req,
       contract: args.contract,
-      requestOrigin: requestOrigin(args.req, args.trustedProxy),
+      requestOrigin: args.requestOrigin,
       trustedOrigins: args.trustedOrigins,
     })
   ) {
@@ -485,7 +486,7 @@ export function createCsrfHooks<Ctx>(
 
   return {
     name: "csrf",
-    onRequest: async ({ req, contract, params }) => {
+    onRequest: async ({ req, requestInfo, contract, params }) => {
       if (!protectedMethods.has(req.method.toUpperCase())) return undefined;
       if (await options.skip?.({ req, contract, params })) return undefined;
 
@@ -494,7 +495,10 @@ export function createCsrfHooks<Ctx>(
         contract,
         allowMissingOrigin,
         trustedOrigins,
-        trustedProxy: options.trustedProxy,
+        requestOrigin:
+          options.trustedProxy !== undefined
+            ? requestOrigin(req, options.trustedProxy)
+            : (requestInfo?.origin ?? requestOrigin(req, false)),
       });
       enforceToken(req, token);
       return undefined;

package/src/server/http.ts

@@ -5,6 +5,10 @@ import type {
   StandardSchema,
 } from "../contracts/index.js";
 import type { AnyPorts } from "../ports/index.js";
+import type {
+  TrustedProxyConfig,
+  TrustedRequestInfo,
+} from "./trusted-proxy.js";
 
 /**
  * Framework-neutral request shape consumed by Beignet server adapters.
@@ -276,6 +280,7 @@ export type OnRequestHook<
   C extends HttpContractConfig = HttpContractConfig,
 > = (args: {
   req: HttpRequestLike;
+  requestInfo: TrustedRequestInfo;
   ports: Ports;
   contract: C;
   params: Record<string, string>;
@@ -303,6 +308,7 @@ export type BeforeHandleHook<
   C extends HttpContractConfig = HttpContractConfig,
 > = (args: {
   req: HttpRequestLike;
+  requestInfo: TrustedRequestInfo;
   ctx: Ctx;
   contract: C;
   path: InferPath<C>;
@@ -323,6 +329,7 @@ export type BeforeSendHook<
   C extends HttpContractConfig = HttpContractConfig,
 > = (args: {
   req: HttpRequestLike;
+  requestInfo: TrustedRequestInfo;
   ctx?: Ctx;
   contract: C;
   path?: InferPath<C>;
@@ -371,6 +378,7 @@ export type AfterSendHook<
   C extends HttpContractConfig = HttpContractConfig,
 > = (args: {
   req: HttpRequestLike;
+  requestInfo: TrustedRequestInfo;
   ctx?: Ctx;
   contract: C;
   path?: InferPath<C>;
@@ -395,6 +403,7 @@ export type ServerCaughtErrorHook<
 > = (args: {
   err: unknown;
   req: HttpRequestLike;
+  requestInfo?: TrustedRequestInfo;
   ctx?: Ctx;
   contract: C;
   path?: InferPath<C>;
@@ -415,6 +424,7 @@ export type ServerUnhandledErrorMapper<
 > = (args: {
   err: unknown;
   req: HttpRequestLike;
+  requestInfo?: TrustedRequestInfo;
   ctx?: Ctx;
   contract: C;
   path?: InferPath<C>;
@@ -447,7 +457,14 @@ export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
    * registered later through `server.route(...)` are not seen here, so hooks
    * that need full coverage should keep a runtime check as a backstop.
    */
-  validate?: (args: { contracts: readonly HttpContractConfig[] }) => void;
+  validate?: (args: {
+    contracts: readonly HttpContractConfig[];
+    /**
+     * Server-level trusted-proxy policy. Request phases receive its resolved
+     * value as `requestInfo`.
+     */
+    trustedProxy?: TrustedProxyConfig;
+  }) => void;
   /**
    * Runs after route matching and before body/query/header parsing.
    */

package/src/server/request-executor.ts

@@ -81,6 +81,7 @@ import {
   decodeMatchedParams,
   PathDecodeError,
 } from "./route-matching.js";
+import type { TrustedRequestInfo } from "./trusted-proxy.js";
 
 function withoutHeadResponseBody(
   response: HttpResponse,
@@ -133,6 +134,23 @@ type ExecutionTarget<Ctx, C extends HttpContractConfig> = {
   responseValidationExemptStatus?: number;
 };
 
+function copyTrustedRequestInfo(
+  requestInfo: TrustedRequestInfo,
+): TrustedRequestInfo;
+function copyTrustedRequestInfo(requestInfo: undefined): undefined;
+function copyTrustedRequestInfo(
+  requestInfo: TrustedRequestInfo | undefined,
+): TrustedRequestInfo | undefined;
+function copyTrustedRequestInfo(
+  requestInfo: TrustedRequestInfo | undefined,
+): TrustedRequestInfo | undefined {
+  if (!requestInfo) return undefined;
+  return {
+    ...requestInfo,
+    url: new URL(requestInfo.url),
+  };
+}
+
 /**
  * Build the per-request execution pipeline once.
  *
@@ -151,8 +169,10 @@ export function createRequestExecutor<
     createRequestContext: (
       req: HttpRequestLike,
       contract: HttpContractConfig,
+      requestInfo: TrustedRequestInfo,
     ) => Promise<Ctx>;
     finalizeContext: (seed: ContextSeed<Ctx> | Ctx) => Ctx;
+    resolveRequestInfo: (req: HttpRequestLike) => TrustedRequestInfo;
   },
   hooks: ServerHook<Ctx, FinalPorts>[],
   routeHooks: readonly RouteHook<unknown, object>[] = [],
@@ -179,6 +199,7 @@ export function createRequestExecutor<
     preMatchedParams?: Record<string, string>,
   ) => {
     const { contract, handler: userHandler } = target;
+    let requestInfo: TrustedRequestInfo | undefined;
     let baseCtx: Ctx | undefined;
     let pathValue: HandlerArgs<Ctx, C>["path"] | undefined;
     let queryValue: HandlerArgs<Ctx, C>["query"] | undefined;
@@ -224,6 +245,7 @@ export function createRequestExecutor<
         const args = {
           err: caught,
           req,
+          requestInfo: copyTrustedRequestInfo(requestInfo),
           ctx,
           contract,
           path,
@@ -364,6 +386,7 @@ export function createRequestExecutor<
           const handled = await hook.mapUnhandledError({
             err: currentError,
             req,
+            requestInfo: copyTrustedRequestInfo(requestInfo),
             ctx,
             contract,
             path,
@@ -391,6 +414,7 @@ export function createRequestExecutor<
           const handled = await options.mapUnhandledError({
             err: currentError,
             req,
+            requestInfo: copyTrustedRequestInfo(requestInfo),
             ctx,
             contract,
             path,
@@ -422,6 +446,8 @@ export function createRequestExecutor<
     };
 
     try {
+      const resolvedRequestInfo = contextRuntime.resolveRequestInfo(req);
+      requestInfo = resolvedRequestInfo;
       const url = new URL(req.url);
 
       let matchedParams: Record<string, string>;
@@ -460,6 +486,7 @@ export function createRequestExecutor<
           if (!hook.beforeSend) continue;
           const nextResponse = await hook.beforeSend({
             req,
+            requestInfo: copyTrustedRequestInfo(resolvedRequestInfo),
             ctx: initialResult.ctx,
             contract,
             path: pathValue,
@@ -515,6 +542,7 @@ export function createRequestExecutor<
             if (!hook.beforeSend) continue;
             const nextResponse = await hook.beforeSend({
               req,
+              requestInfo: copyTrustedRequestInfo(resolvedRequestInfo),
               ctx: initialResult.ctx,
               contract,
               path: pathValue,
@@ -612,6 +640,7 @@ export function createRequestExecutor<
         try {
           const hookResult = await hook.onRequest({
             req,
+            requestInfo: copyTrustedRequestInfo(resolvedRequestInfo),
             ports: finalPorts,
             contract,
             params: matchedParams,
@@ -644,7 +673,11 @@ export function createRequestExecutor<
           let createdCtx!: Ctx;
           try {
             createdCtx = await timeStage("contextMs", () =>
-              contextRuntime.createRequestContext(req, contract),
+              contextRuntime.createRequestContext(
+                req,
+                contract,
+                resolvedRequestInfo,
+              ),
             );
             baseCtx = createdCtx;
           } catch (error) {
@@ -727,7 +760,11 @@ export function createRequestExecutor<
             let createdCtx!: Ctx;
             try {
               createdCtx = await timeStage("contextMs", () =>
-                contextRuntime.createRequestContext(req, contract),
+                contextRuntime.createRequestContext(
+                  req,
+                  contract,
+                  resolvedRequestInfo,
+                ),
               );
               baseCtx = createdCtx;
             } catch (error) {
@@ -792,6 +829,7 @@ export function createRequestExecutor<
                   try {
                     const hookResult = await hook.beforeHandle({
                       req,
+                      requestInfo: copyTrustedRequestInfo(resolvedRequestInfo),
                       ctx: currentCtx,
                       contract,
                       path,
@@ -951,6 +989,7 @@ export function createRequestExecutor<
         try {
           await hook.afterSend({
             req,
+            requestInfo: copyTrustedRequestInfo(resolvedRequestInfo),
             ctx: result.ctx,
             contract,
             path: pathValue,
@@ -1110,8 +1149,10 @@ export function buildHandler<
     createRequestContext: (
       req: HttpRequestLike,
       contract: HttpContractConfig,
+      requestInfo: TrustedRequestInfo,
     ) => Promise<Ctx>;
     finalizeContext: (seed: ContextSeed<Ctx> | Ctx) => Ctx;
+    resolveRequestInfo: (req: HttpRequestLike) => TrustedRequestInfo;
   },
   contract: C,
   userHandler: Handler<Ctx, C>,

package/src/server/server-context.ts

@@ -16,10 +16,11 @@ import type { ServerContextConfig } from "./context.js";
  * // server/context.ts
  * export const appContext = defineServerContext<AppContext, AppPorts>()({
  *   gate: (ports) => ports.gate,
- *   request: async ({ req, ports, requestId, trace }) => ({
+ *   request: async ({ req, ports, requestId, requestInfo, trace }) => ({
  *     actor: await resolveActor(req),
  *     auth: null,
  *     requestId,
+ *     requestInfo,
  *     ...trace,
  *     ports,
  *   }),

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",
+    );
+  }
+}