@michaelthielemann/kestrel 5.0.0 → 5.0.2

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,7 @@ export async function boot(input) {
                     server = createHttpServer(routes, run, logger, {
                         maxBodyBytes: http.maxBodyBytes,
                         trustProxy: http.trustProxy,
+                        allow: http.allow,
                         healthPath: http.healthPath,
                         inlineTypes: http.inlineTypes,
                         timeouts: http.timeouts,

package/dist/defineConfig.d.ts

@@ -44,6 +44,7 @@ export declare const configSchema: z.ZodObject<{
         corsOrigin: z.ZodOptional<z.ZodString>;
         maxBodyBytes: z.ZodDefault<z.ZodNumber>;
         trustProxy: z.ZodDefault<z.ZodBoolean>;
+        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<{
@@ -64,6 +65,7 @@ export declare const configSchema: z.ZodObject<{
         host: string;
         maxBodyBytes: number;
         trustProxy: boolean;
+        allow: string[];
         healthPath: string | null;
         inlineTypes: string[];
         timeouts: {
@@ -78,6 +80,7 @@ export declare const configSchema: z.ZodObject<{
         corsOrigin?: string | undefined;
         maxBodyBytes?: number | undefined;
         trustProxy?: boolean | undefined;
+        allow?: string[] | undefined;
         healthPath?: string | null | undefined;
         inlineTypes?: string[] | undefined;
         timeouts?: {
@@ -94,6 +97,7 @@ export declare const configSchema: z.ZodObject<{
         host: string;
         maxBodyBytes: number;
         trustProxy: boolean;
+        allow: string[];
         healthPath: string | null;
         inlineTypes: string[];
         timeouts: {
@@ -140,6 +144,7 @@ export declare const configSchema: z.ZodObject<{
         corsOrigin?: string | undefined;
         maxBodyBytes?: number | undefined;
         trustProxy?: boolean | undefined;
+        allow?: string[] | undefined;
         healthPath?: string | null | undefined;
         inlineTypes?: string[] | undefined;
         timeouts?: {

package/dist/defineConfig.js

@@ -18,6 +18,7 @@ export const configSchema = z
             corsOrigin: z.string().min(1).optional(),
             maxBodyBytes: z.number().int().positive().default(10 * 1024 * 1024),
             trustProxy: z.boolean().default(false),
+            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/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

@@ -46,6 +46,7 @@ export interface HttpTimeouts {
     keepAliveMs?: number;
 }
 export interface HttpOptions {
+    allow?: readonly string[];
     corsOrigin?: string;
     maxBodyBytes?: number;
     trustProxy?: boolean;

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",
@@ -225,7 +227,13 @@ export function clientIp(req, trustProxy) {
 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 server = createServer((req, res) => {
+        if (allowlist !== null && !allowlist.check(clientIp(req, trustProxy))) {
+            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 +281,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, trustProxy);
         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.2",
   "description": "Kestrel core: contract registry, boot check and pipeline runner. Ships no contracts and no modules.",
   "type": "module",
   "license": "Apache-2.0",