@michaelthielemann/kestrel 5.0.2 → 5.0.3

package/dist/boot.js

@@ -237,6 +237,8 @@ export async function boot(input) {
                     server = createHttpServer(routes, run, logger, {
                         maxBodyBytes: http.maxBodyBytes,
                         trustProxy: http.trustProxy,
+                        proxyHops: http.proxyHops,
+                        ...(http.trustedHeader === undefined ? {} : { trustedHeader: http.trustedHeader }),
                         allow: http.allow,
                         healthPath: http.healthPath,
                         inlineTypes: http.inlineTypes,

package/dist/defineConfig.d.ts

@@ -44,6 +44,8 @@ export declare const configSchema: z.ZodObject<{
         corsOrigin: z.ZodOptional<z.ZodString>;
         maxBodyBytes: z.ZodDefault<z.ZodNumber>;
         trustProxy: z.ZodDefault<z.ZodBoolean>;
+        proxyHops: z.ZodDefault<z.ZodNumber>;
+        trustedHeader: z.ZodOptional<z.ZodString>;
         allow: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         healthPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         inlineTypes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -61,11 +63,8 @@ export declare const configSchema: z.ZodObject<{
             keepAliveMs?: number | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
-        port: number;
-        host: string;
-        maxBodyBytes: number;
-        trustProxy: boolean;
         allow: string[];
+        maxBodyBytes: number;
         healthPath: string | null;
         inlineTypes: string[];
         timeouts: {
@@ -73,14 +72,16 @@ export declare const configSchema: z.ZodObject<{
             headersMs: number;
             keepAliveMs: number;
         };
+        trustProxy: boolean;
+        proxyHops: number;
+        port: number;
+        host: string;
         corsOrigin?: string | undefined;
+        trustedHeader?: string | undefined;
     }, {
-        port?: number | undefined;
-        host?: string | undefined;
+        allow?: string[] | undefined;
         corsOrigin?: string | undefined;
         maxBodyBytes?: number | undefined;
-        trustProxy?: boolean | undefined;
-        allow?: string[] | undefined;
         healthPath?: string | null | undefined;
         inlineTypes?: string[] | undefined;
         timeouts?: {
@@ -88,16 +89,18 @@ export declare const configSchema: z.ZodObject<{
             headersMs?: number | undefined;
             keepAliveMs?: number | undefined;
         } | undefined;
+        trustProxy?: boolean | undefined;
+        proxyHops?: number | undefined;
+        trustedHeader?: string | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
     }>]>>;
     pipelinesDir: z.ZodDefault<z.ZodString>;
     shutdownTimeoutMs: z.ZodDefault<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     http: {
-        port: number;
-        host: string;
-        maxBodyBytes: number;
-        trustProxy: boolean;
         allow: string[];
+        maxBodyBytes: number;
         healthPath: string | null;
         inlineTypes: string[];
         timeouts: {
@@ -105,7 +108,12 @@ export declare const configSchema: z.ZodObject<{
             headersMs: number;
             keepAliveMs: number;
         };
+        trustProxy: boolean;
+        proxyHops: number;
+        port: number;
+        host: string;
         corsOrigin?: string | undefined;
+        trustedHeader?: string | undefined;
     } | null;
     modules: {
         use: string;
@@ -139,12 +147,9 @@ export declare const configSchema: z.ZodObject<{
         pipeline: string;
     })[];
     http?: {
-        port?: number | undefined;
-        host?: string | undefined;
+        allow?: string[] | undefined;
         corsOrigin?: string | undefined;
         maxBodyBytes?: number | undefined;
-        trustProxy?: boolean | undefined;
-        allow?: string[] | undefined;
         healthPath?: string | null | undefined;
         inlineTypes?: string[] | undefined;
         timeouts?: {
@@ -152,6 +157,11 @@ export declare const configSchema: z.ZodObject<{
             headersMs?: number | undefined;
             keepAliveMs?: number | undefined;
         } | undefined;
+        trustProxy?: boolean | undefined;
+        proxyHops?: number | undefined;
+        trustedHeader?: string | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
     } | null | undefined;
     pipelinesDir?: string | undefined;
     shutdownTimeoutMs?: number | undefined;

package/dist/defineConfig.js

@@ -18,6 +18,8 @@ export const configSchema = z
             corsOrigin: z.string().min(1).optional(),
             maxBodyBytes: z.number().int().positive().default(10 * 1024 * 1024),
             trustProxy: z.boolean().default(false),
+            proxyHops: z.number().int().positive().default(1),
+            trustedHeader: z.string().min(1).optional(),
             allow: z.array(z.string().min(1)).default([]),
             healthPath: z.string().regex(/^\/\S*$/).nullable().default("/health"),
             inlineTypes: z.array(z.string().min(1)).default([]),

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { boot, type Kestrel, type BootInput, type Triggers } from "./boot.ts";
-export { matchRoute, routePattern, parseRequestBody, parseQuery, buildResponse, responseForRun, errorResponse, clientIp, BodyTooLarge, type Route, type ParsedBody, type HttpResponse, type HttpTimeouts, type ResponseMeta } from "./triggers/http.ts";
+export { matchRoute, routePattern, parseRequestBody, parseQuery, buildResponse, responseForRun, errorResponse, clientIp, BodyTooLarge, type Route, type ParsedBody, type HttpResponse, type HttpTimeouts, type ClientIpOptions, type ResponseMeta } from "./triggers/http.ts";
 export { defineConfig, type KestrelConfig, type KestrelConfigInput } from "./defineConfig.ts";
 export { defineContract, type Contract } from "./defineContract.ts";
 export { defineModule, type ModuleDefinition, type ModuleInput, type ModuleTriggers, type Deps, type EventEntry, type ContextPath, type JsonSchema, type StepDescription, type StepDescriptions } from "./defineModule.ts";

package/dist/triggers/http.d.ts

@@ -45,15 +45,19 @@ export interface HttpTimeouts {
     headersMs?: number;
     keepAliveMs?: number;
 }
-export interface HttpOptions {
+export interface ClientIpOptions {
+    trustProxy?: boolean;
+    proxyHops?: number;
+    trustedHeader?: string;
+}
+export interface HttpOptions extends ClientIpOptions {
     allow?: readonly string[];
     corsOrigin?: string;
     maxBodyBytes?: number;
-    trustProxy?: boolean;
     healthPath?: string | null;
     inlineTypes?: readonly string[];
     timeouts?: HttpTimeouts;
 }
-export declare function clientIp(req: IncomingMessage, trustProxy: boolean): string | undefined;
+export declare function clientIp(req: IncomingMessage, options?: boolean | ClientIpOptions): string | undefined;
 export declare function createHttpServer(routes: readonly Route[], run: Runner, logger: Logger, options?: HttpOptions): Server;
 export declare function listen(server: Server, port: number, host: string): Promise<AddressInfo>;

package/dist/triggers/http.js

@@ -215,12 +215,21 @@ function write(res, response) {
     res.writeHead(response.status, response.headers);
     res.end(typeof response.body === "string" ? response.body : Buffer.from(response.body));
 }
-export function clientIp(req, trustProxy) {
+function headerValues(value) {
+    return (Array.isArray(value) ? value : value === undefined ? [] : [value])
+        .flatMap((v) => v.split(","))
+        .map((v) => v.trim())
+        .filter((v) => v !== "");
+}
+// A proxy appends the peer it saw to X-Forwarded-For, so only the entries counted from the right are
+// trustworthy; the left end is whatever the client sent. A trusted header names the client outright.
+export function clientIp(req, options = {}) {
+    const { trustProxy = false, proxyHops = 1, trustedHeader } = typeof options === "boolean" ? { trustProxy: options } : options;
+    if (trustedHeader !== undefined)
+        return headerValues(req.headers[trustedHeader.toLowerCase()])[0];
     if (trustProxy) {
-        const forwarded = req.headers["x-forwarded-for"];
-        const first = (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(",")[0]?.trim();
-        if (first)
-            return first;
+        const chain = headerValues(req.headers["x-forwarded-for"]);
+        return chain.length >= proxyHops ? chain[chain.length - proxyHops] : undefined;
     }
     return req.socket.remoteAddress ?? undefined;
 }
@@ -228,9 +237,9 @@ export function createHttpServer(routes, run, logger, options = {}) {
     const started = Date.now();
     const healthPath = options.healthPath === undefined ? "/health" : options.healthPath;
     const allowlist = createAllowlist(options.allow ?? []);
-    const trustProxy = options.trustProxy ?? false;
+    const peer = { trustProxy: options.trustProxy ?? false, proxyHops: options.proxyHops ?? 1, ...(options.trustedHeader === undefined ? {} : { trustedHeader: options.trustedHeader }) };
     const server = createServer((req, res) => {
-        if (allowlist !== null && !allowlist.check(clientIp(req, trustProxy))) {
+        if (allowlist !== null && !allowlist.check(clientIp(req, peer))) {
             sendError(res, 403, "forbidden", requestIdOf(req.headers["x-request-id"]));
             return;
         }
@@ -281,7 +290,7 @@ export function createHttpServer(routes, run, logger, options = {}) {
             if (typeof v === "string")
                 headers[k] = v;
         const input = { trigger: { kind: "http", name: `${req.method} ${url.pathname}` }, payload, params: match.params, headers, files: body.files };
-        const ip = clientIp(req, trustProxy);
+        const ip = clientIp(req, peer);
         if (ip !== undefined)
             input.ip = ip;
         const result = await run(match.route.pipeline, input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "description": "Kestrel core: contract registry, boot check and pipeline runner. Ships no contracts and no modules.",
   "type": "module",
   "license": "Apache-2.0",