@michaelthielemann/kestrel 5.0.0 → 5.0.3

package/dist/boot.js

@@ -8,6 +8,7 @@ import { StepRegistry } from "./registry.js";
 import { createRunTracker, runPipeline } from "./runner.js";
 import { sortModules } from "./sort.js";
 import { createCronEntry, startCron } from "./triggers/cron.js";
+import { createAllowlist } from "./triggers/allowlist.js";
 import { createHttpServer, listen, parseRoute, routePattern } from "./triggers/http.js";
 const CORE = "kestrel";
 const SVG = "image/svg+xml";
@@ -151,6 +152,14 @@ export async function boot(input) {
         if (config.http?.inlineTypes.includes(SVG) && !steps.has(SANITIZE_SVG)) {
             throw new KestrelBootError(CORE, `http.inlineTypes contains "${SVG}" but no module registers the step "${SANITIZE_SVG}"`);
         }
+        if (config.http !== null) {
+            try {
+                createAllowlist(config.http.allow);
+            }
+            catch (err) {
+                throw new KestrelBootError(CORE, `http.allow: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         const definitions = new Map();
         for (const p of input.pipelines) {
             if (definitions.has(p.name))
@@ -228,6 +237,9 @@ 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,
                         timeouts: http.timeouts,

package/dist/defineConfig.d.ts

@@ -44,6 +44,9 @@ 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">>;
         timeouts: z.ZodDefault<z.ZodObject<{
@@ -60,10 +63,8 @@ export declare const configSchema: z.ZodObject<{
             keepAliveMs?: number | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
-        port: number;
-        host: string;
+        allow: string[];
         maxBodyBytes: number;
-        trustProxy: boolean;
         healthPath: string | null;
         inlineTypes: string[];
         timeouts: {
@@ -71,13 +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;
         healthPath?: string | null | undefined;
         inlineTypes?: string[] | undefined;
         timeouts?: {
@@ -85,15 +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;
+        allow: string[];
         maxBodyBytes: number;
-        trustProxy: boolean;
         healthPath: string | null;
         inlineTypes: string[];
         timeouts: {
@@ -101,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;
@@ -135,11 +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;
         healthPath?: string | null | undefined;
         inlineTypes?: string[] | undefined;
         timeouts?: {
@@ -147,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,9 @@ 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([]),
             timeouts: z

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/allowlist.d.ts

@@ -0,0 +1,9 @@
+export interface Allowlist {
+    check(ip: string | undefined): boolean;
+}
+export declare function normalizeIp(ip: string): {
+    address: string;
+    family: "ipv4" | "ipv6";
+} | null;
+/** `null` for an empty list: nothing to enforce. Throws on an entry that is neither an address nor a CIDR. */
+export declare function createAllowlist(entries: readonly string[]): Allowlist | null;

package/dist/triggers/allowlist.js

@@ -0,0 +1,49 @@
+import { BlockList, isIP } from "node:net";
+const MAPPED_IPV4 = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i;
+function invalid(entry, reason) {
+    return new Error(`ip allowlist: invalid entry ${JSON.stringify(entry)} (${reason})`);
+}
+// Strips an IPv6 zone id and unwraps an IPv4-mapped IPv6 address so both sides of the check use
+// the same family the operator wrote into the list.
+export function normalizeIp(ip) {
+    const bare = ip.includes("%") ? (ip.split("%")[0] ?? "") : ip;
+    const mapped = MAPPED_IPV4.exec(bare);
+    const address = mapped ? (mapped[1] ?? bare) : bare;
+    const version = isIP(address);
+    if (version === 4)
+        return { address, family: "ipv4" };
+    if (version === 6)
+        return { address, family: "ipv6" };
+    return null;
+}
+/** `null` for an empty list: nothing to enforce. Throws on an entry that is neither an address nor a CIDR. */
+export function createAllowlist(entries) {
+    if (entries.length === 0)
+        return null;
+    const list = new BlockList();
+    for (const entry of entries) {
+        const [raw, prefixText, ...rest] = entry.trim().split("/");
+        if (raw === undefined || raw === "" || rest.length > 0)
+            throw invalid(entry, "expected an IP address or a CIDR range");
+        const ip = normalizeIp(raw);
+        if (ip === null)
+            throw invalid(entry, "not an IPv4 or IPv6 address");
+        if (prefixText === undefined) {
+            list.addAddress(ip.address, ip.family);
+            continue;
+        }
+        const bits = ip.family === "ipv4" ? 32 : 128;
+        const prefix = /^\d{1,3}$/.test(prefixText) ? Number(prefixText) : Number.NaN;
+        if (!Number.isInteger(prefix) || prefix < 0 || prefix > bits)
+            throw invalid(entry, `prefix must be 0-${bits}`);
+        list.addSubnet(ip.address, prefix, ip.family);
+    }
+    return {
+        check(ip) {
+            if (ip === undefined)
+                return false;
+            const normalized = normalizeIp(ip);
+            return normalized !== null && list.check(normalized.address, normalized.family);
+        },
+    };
+}

package/dist/triggers/http.d.ts

@@ -45,14 +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

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { isBinaryResult, requestIdOf } from "../context.js";
+import { createAllowlist } from "./allowlist.js";
 export function parseRoute(http, pipeline) {
     const [method, path] = http.split(" ");
     if (method === undefined || path === undefined || !path.startsWith("/"))
@@ -182,6 +183,7 @@ export function responseForRun(result, extraInline = []) {
 /** Fixed code for errors raised before a pipeline runs, where there is no KestrelError to read one from. */
 const EDGE_CODE_BY_STATUS = {
     400: "VALIDATION",
+    403: "FORBIDDEN",
     404: "NOT_FOUND",
     413: "PAYLOAD_TOO_LARGE",
     500: "INTERNAL",
@@ -213,19 +215,34 @@ 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;
 }
 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 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, peer))) {
+            sendError(res, 403, "forbidden", requestIdOf(req.headers["x-request-id"]));
+            return;
+        }
         if (options.corsOrigin !== undefined) {
             res.setHeader("access-control-allow-origin", options.corsOrigin);
             res.setHeader("access-control-allow-headers", "content-type, authorization");
@@ -273,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, options.trustProxy ?? false);
+        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.0",
+  "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",