@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/meta/meta-spec.js

@@ -0,0 +1,197 @@
+/**
+ * metaSpec: the generate-time policy that turns route meta and route schemas into OpenAPI
+ * operation fields. Never consulted at request time; what it finds goes to the diagnostics,
+ * which the caller throws or reports.
+ */
+import { resolvedStrictness, } from "./meta-spec-merge.js";
+import { checkTargetKey } from "./meta-spec-validate.js";
+export const DEFAULT_PROFILE = "default";
+const isName = (value) => typeof value === "string" && value !== "";
+const isGroup = (value) => Array.isArray(value) && value.every(isName);
+/** `{ scheme: scopes[] }`: scheme names mapped to lists of scope names. */
+function isRequirement(entry) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+        return false;
+    return Object.entries(entry).every(([scheme, scopes]) => scheme !== "" && Array.isArray(scopes) && scopes.every((scope) => typeof scope === "string"));
+}
+/**
+ * Security shorthand → OpenAPI requirements: a name, alternative names, groups of names, or
+ * requirement objects; `[]` is explicitly public. Anything else throws: a guess would document
+ * a protected route as public.
+ */
+export function normalizeSecurity(raw) {
+    if (typeof raw === "string") {
+        if (raw === "")
+            throw new TypeError("security: a scheme name cannot be empty");
+        return [{ [raw]: [] }];
+    }
+    if (!Array.isArray(raw))
+        throw new TypeError(`security: expected a scheme name or an array, got ${raw === null ? "null" : typeof raw}`);
+    if (raw.every(isName))
+        return raw.map((scheme) => ({ [scheme]: [] }));
+    if (raw.every(isGroup))
+        return raw.map((group) => Object.fromEntries(group.map((scheme) => [scheme, []])));
+    if (raw.every(isRequirement))
+        return raw;
+    throw new TypeError("security: entries must all be scheme names, all groups of scheme names, or all { scheme: scopes[] } requirement objects — mixed or malformed entries are refused");
+}
+/** The scheme names a security list refers to, once each. */
+export function securitySchemeNames(security) {
+    if (!Array.isArray(security))
+        return [];
+    return [
+        ...new Set(security.flatMap((requirement) => (requirement instanceof Object ? Object.keys(requirement) : []))),
+    ];
+}
+/** Where a schema entry without `from` looks, in order. */
+const SOURCES = [
+    "output",
+    "input.json",
+    "input.search",
+    "input.form",
+    "input.headers",
+    "input.cookies",
+];
+/** Meta keys that never reach a document, policy or none. */
+const HIDDEN = ["internal", "extensions"];
+const UNREAD = { from: SOURCES, match: null, profiles: null, schema: null, search: "root", version: null };
+const truthy = (key) => (value) => value ? { [key]: value } : undefined;
+function builtin(key, target, produce, ws) {
+    return { ...UNREAD, http: true, keys: [target], produce, rank: 2, read: key, sourceKey: key, ws };
+}
+const invalidate = (value) => Array.isArray(value) && value.length > 0 ? { "x-invalidate": [...new Set(value)] } : undefined;
+/** The eight mappings every app has, in their emit order. */
+function builtins() {
+    return [
+        builtin("summary", "summary", truthy("summary"), true),
+        builtin("description", "description", truthy("description"), true),
+        builtin("tags", "tags", (value) => (value ? { tags: typeof value === "string" ? [value] : value } : undefined), true),
+        builtin("deprecated", "deprecated", truthy("deprecated"), false),
+        builtin("operationId", "operationId", truthy("operationId"), true),
+        builtin("security", "security", (value) => (value ? { security: normalizeSecurity(value) } : undefined), false),
+        builtin("invalidate", "x-invalidate", invalidate, false),
+        builtin("mcp", "x-mcp", (value) => (value === true ? { "x-mcp": true } : undefined), false),
+    ];
+}
+function compileEntry(key, entry, rank, diagnostics) {
+    const where = `${rank === 1 ? "schema" : "meta"}."${key}"`;
+    if (entry === false)
+        return null;
+    if (typeof entry === "string") {
+        if (!checkTargetKey(entry, where, diagnostics))
+            return null;
+        const produce = (value) => (value === undefined ? undefined : { [entry]: value });
+        return { ...UNREAD, http: true, keys: [entry], produce, rank, read: key, sourceKey: key, ws: true };
+    }
+    const read = entry;
+    const base = {
+        from: read.from ?? SOURCES,
+        http: entry.on !== "ws",
+        match: read.match ?? null,
+        profiles: entry.profiles ?? null,
+        rank,
+        read: read.read ?? key,
+        schema: entry.schema ?? null,
+        search: read.search ?? "root",
+        sourceKey: key,
+        version: read.version ?? null,
+        ws: entry.on !== "http",
+    };
+    if ("expand" in entry) {
+        const expand = entry.expand;
+        const produce = (value, ctx) => {
+            const out = expand(value, ctx);
+            if (out === undefined)
+                return undefined;
+            const kept = Object.entries(out).filter(([target, produced]) => produced !== undefined && checkTargetKey(target, `${where} (expand)`, diagnostics));
+            return kept.length > 0 ? Object.fromEntries(kept) : undefined;
+        };
+        return { ...base, keys: [], produce };
+    }
+    if (!checkTargetKey(entry.key, where, diagnostics))
+        return null;
+    const { key: target } = entry;
+    const map = entry.map;
+    const produce = (value, ctx) => {
+        const mapped = map === undefined ? value : map(value, ctx);
+        return mapped === undefined ? undefined : { [target]: mapped };
+    };
+    return { ...base, keys: [target], produce };
+}
+/** Whether two entries ever write to one operation: their targets and profiles overlap. */
+function overlap(a, b) {
+    if (!((a.http && b.http) || (a.ws && b.ws)))
+        return false;
+    return a.profiles === null || b.profiles === null || a.profiles.some((name) => b.profiles?.includes(name));
+}
+function detectDuplicates(entries, diagnostics) {
+    const byKey = new Map();
+    for (const entry of entries) {
+        for (const key of entry.keys) {
+            const prior = byKey.get(`${entry.rank} ${key}`) ?? [];
+            const clash = prior.find((other) => other.sourceKey !== entry.sourceKey && overlap(other, entry));
+            if (clash === undefined)
+                byKey.set(`${entry.rank} ${key}`, [...prior, entry]);
+            else {
+                const both = `"${clash.sourceKey}" and "${entry.sourceKey}"`;
+                diagnostics.add("DUPLICATE_TARGET", "error", `${both} both write operation key "${key}" at the same precedence`);
+            }
+        }
+    }
+}
+const CONFLICT = {
+    hidden: "a mounted sub-app hides this key, so it is hidden here too — hiding wins over a parent entry, because a leak is worse than a missing tag",
+    parent: "a mounted sub-app declares a different entry; this app's entry wins for this document. The sub-app's own document still uses its own entry",
+};
+/** `config` ready to apply: built-ins (an app entry takes its slot), app entries, then schema entries. */
+export function compileMetaSpec(config, diagnostics) {
+    const overrides = config?.meta ?? {};
+    const known = new Set(HIDDEN);
+    const compile = (key, entry, rank) => compileEntry(key, entry, rank, diagnostics);
+    const meta = [
+        ...builtins().map((entry) => Object.hasOwn(overrides, entry.sourceKey) ? compile(entry.sourceKey, overrides[entry.sourceKey], 2) : entry),
+        ...Object.entries(overrides)
+            .filter(([key]) => !builtins().some((entry) => entry.sourceKey === key))
+            .map(([key, entry]) => compile(key, entry, 2)),
+    ];
+    for (const key of [...builtins().map(({ sourceKey }) => sourceKey), ...Object.keys(overrides)])
+        known.add(key);
+    const schema = Object.entries(config?.schema ?? {}).map(([key, entry]) => compile(key, entry, 1));
+    const entries = [...meta, ...schema].filter((entry) => entry !== null);
+    detectDuplicates(entries, diagnostics);
+    for (const { key, resolution, section } of config?.conflicts ?? []) {
+        diagnostics.add("SUBAPP_ENTRY_CONFLICT", "warn", `${section}."${key}": ${CONFLICT[resolution]}`);
+    }
+    return {
+        entries,
+        known,
+        needsSchemas: schema.length > 0,
+        profiles: config?.profiles ?? {},
+        strict: resolvedStrictness(config),
+    };
+}
+/** The meta keys a published manifest may carry: built-ins and keys with an entry, never a hidden one. */
+export function publishableMetaKeys(config) {
+    const allowed = new Set(builtins().map(({ sourceKey }) => sourceKey));
+    for (const [key, entry] of Object.entries(config?.meta ?? {})) {
+        if (entry === false)
+            allowed.delete(key);
+        else
+            allowed.add(key);
+    }
+    return (key) => allowed.has(key) && !HIDDEN.includes(key);
+}
+/** The filter of the document's profile: `exclude` drops keys, `include` allowlists `x-` keys. */
+export function resolveProfile(spec, profile, diagnostics) {
+    const name = profile ?? DEFAULT_PROFILE;
+    const declared = Object.hasOwn(spec.profiles, name) ? spec.profiles[name] : undefined;
+    if (declared === undefined) {
+        if (name !== DEFAULT_PROFILE) {
+            diagnostics.add("UNKNOWN_PROFILE", "error", `document requests profile "${name}", which is not declared in metaSpec.profiles`);
+        }
+        return { filter: () => true, name };
+    }
+    const { exclude = [], include } = declared;
+    const filter = (key) => !exclude.includes(key) && (include === undefined || !key.startsWith("x-") || include.includes(key));
+    return { filter, name };
+}

package/dist/middleware/compress.d.ts

@@ -0,0 +1,15 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type CompressOptions = {
+    /** Compress answers to credentialed requests and answers that set a cookie. Default `false` (BREACH). */
+    credentialed?: boolean;
+    /** The smallest body compressed, in bytes (characters, for a text body). Default 1024. */
+    threshold?: number;
+};
+/**
+ * Whether an `Accept-Encoding` value takes `coding`: by name, else through `*`, at a q-value above 0
+ * (a malformed one is 0). Shared with staticFiles' precompressed siblings.
+ */
+export declare function acceptsCoding(accept: string | null, coding: string): boolean;
+export declare function compress(options?: CompressOptions): MiddlewareFn<{
+    readonly req: Request;
+}>;

package/dist/middleware/compress.js

@@ -0,0 +1,93 @@
+/**
+ * `compress()`: gzip a buffered answer when the client's `Accept-Encoding` takes gzip (q-values
+ * honored, `*` included). The edge may already compress (Cloudflare does); this is for the origin
+ * that answers directly. No brotli here (b3): `CompressionStream` runs it at quality 11 with no
+ * knob, ~55× gzip's time for a dynamic answer; brotli is served as a precompressed static sibling.
+ *
+ * It encodes only the raw body the answer was built from, never reading or cloning its stream, so
+ * a produced stream (sse, stream, generate) or a foreign response is passed through as it is. It
+ * leaves alone: an empty, partial or 304 answer; one already encoded; `Cache-Control:
+ * no-transform`; a type that does not compress; a body under `threshold`.
+ *
+ * BREACH: compressed length leaks a secret in a body that also reflects attacker input. By default
+ * an answer to a credentialed request (a `Cookie` or `Authorization`) or one that sets a cookie is
+ * not compressed; `credentialed: true` opts in.
+ */
+import { isHoneyResponse, rawBodyOf, replaceResponse, withRawBody } from "../response/builder.js";
+import { addVary, withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+/* text, JSON, XML, JavaScript and SVG compress; images, archives and media are compressed already */
+const COMPRESSIBLE = /^(?:text\/|application\/(?:json|javascript|xml|[\w.-]+\+(?:json|xml))$|image\/svg\+xml$)/;
+const NO_TRANSFORM = /(?:^|,)\s*no-transform\s*(?:,|$)/i;
+function essenceOf(contentType) {
+    const text = contentType ?? "";
+    const semi = text.indexOf(";");
+    return (semi === -1 ? text : text.slice(0, semi)).trim().toLowerCase();
+}
+/**
+ * Whether an `Accept-Encoding` value takes `coding`: by name, else through `*`, at a q-value above 0
+ * (a malformed one is 0). Shared with staticFiles' precompressed siblings.
+ */
+export function acceptsCoding(accept, coding) {
+    if (accept === null)
+        return false;
+    let any = 0;
+    for (const item of accept.split(",")) {
+        const [name, ...params] = item.split(";");
+        const weight = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+        const value = weight === undefined ? 1 : Number(weight.slice(2));
+        const q = Number.isFinite(value) ? value : 0;
+        const listed = name.trim().toLowerCase();
+        if (listed === coding)
+            return q > 0;
+        if (listed === "*")
+            any = q;
+    }
+    return any > 0;
+}
+function compressible(response, threshold, raw) {
+    /* the size first: most answers are small JSON, and it costs no header lookup */
+    if ((typeof raw === "string" ? raw.length : raw.byteLength) < threshold)
+        return false;
+    const status = response.status;
+    if (status < 200 || status === 204 || status === 206 || status === 304)
+        return false;
+    const headers = response.headers;
+    if (headers.has("content-encoding") || headers.has("content-range"))
+        return false;
+    if (NO_TRANSFORM.test(headers.get("cache-control") ?? ""))
+        return false;
+    return COMPRESSIBLE.test(essenceOf(headers.get("content-type")));
+}
+async function gzip(raw) {
+    const stream = new Blob([raw]).stream().pipeThrough(new CompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+export function compress(options = {}) {
+    const { credentialed = false, threshold = 1024 } = options;
+    if (!(Number.isFinite(threshold) && threshold >= 0)) {
+        throw new TypeError("compress: threshold must be a finite number of bytes, 0 or more");
+    }
+    return namedMiddleware("compress", async (ctx, next) => {
+        const response = await next();
+        const raw = rawBodyOf(response);
+        /* no raw body: a produced stream or a foreign response, never buffered here */
+        if (raw === null || !compressible(response, threshold, raw))
+            return response;
+        const req = ctx.req;
+        const secret = !credentialed &&
+            (req.headers.has("cookie") || req.headers.has("authorization") || response.headers.has("set-cookie"));
+        if (secret || !acceptsCoding(req.headers.get("accept-encoding"), "gzip")) {
+            return withHeaders(response, (headers) => addVary(headers, "accept-encoding"));
+        }
+        const bytes = await gzip(raw);
+        const encoded = replaceResponse(response, { body: bytes });
+        if (!isHoneyResponse(encoded))
+            withRawBody(encoded, bytes);
+        return withHeaders(encoded, (headers) => {
+            headers.set("content-encoding", "gzip");
+            headers.delete("content-length");
+            addVary(headers, "accept-encoding");
+        });
+    });
+}

package/dist/middleware/cors.d.ts

@@ -0,0 +1,18 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type CORSOptions = {
+    /** Requires an explicit `origin`: a string, a list or a predicate. With `"*"` or none, cors() throws. */
+    credentials?: boolean;
+    /** Response headers a browser script may read. */
+    exposeHeaders?: string[];
+    /** Request headers a preflight allows; unset, the requested ones are echoed. */
+    headers?: string[];
+    /** Seconds a browser may cache a preflight. Default 86400. */
+    maxAge?: number;
+    /** Methods a preflight allows. Default GET, HEAD, PUT, PATCH, POST, DELETE. */
+    methods?: string[];
+    /** Default `"*"`. */
+    origin?: "*" | ((origin: string) => boolean) | string | readonly string[];
+};
+export declare function cors(options?: CORSOptions): MiddlewareFn<{
+    req: Request;
+}>;

package/dist/middleware/cors.js

@@ -0,0 +1,80 @@
+/**
+ * `cors(options)`: Cross-Origin Resource Sharing. A preflight from an allowed origin is answered
+ * here with 204; any other answer gets the allow-origin it earns. The opaque origin `null` is never
+ * reflected, and credentials need an explicit origin. Headers are written through `withHeaders`,
+ * so a buffered response keeps its plain header map.
+ */
+import { addVary, withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+const DEFAULT_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"];
+const DEFAULT_MAX_AGE = 86_400;
+/**
+ * The `Access-Control-Allow-Origin` value `origin` earns, or `null`. The opaque origin `null`
+ * (sandboxed frames, `file:`, some redirects) is never reflected: any page can produce it.
+ */
+function allowedOrigin(origin, policy) {
+    if (policy === undefined || policy === "*")
+        return "*";
+    if (origin === "null")
+        return null;
+    if (typeof policy === "string")
+        return policy === origin ? origin : null;
+    if (typeof policy === "function")
+        return policy(origin) ? origin : null;
+    return policy.includes(origin) ? origin : null;
+}
+const joined = (list) => list !== undefined && list.length > 0 ? list.join(", ") : null;
+export function cors(options = {}) {
+    const { credentials = false, origin } = options;
+    if (credentials && (origin === undefined || origin === "*")) {
+        throw new TypeError("cors: `credentials: true` needs an explicit `origin` (a string, a list or a predicate). A wildcard would let every site make credentialed requests and read the answer.");
+    }
+    /* the answer depends on the request's Origin unless the policy is a plain wildcard: say so to caches */
+    const varies = !(origin === undefined || origin === "*");
+    const methods = (options.methods ?? DEFAULT_METHODS).join(", ");
+    const allowHeaders = joined(options.headers);
+    const exposeHeaders = joined(options.exposeHeaders);
+    const maxAge = String(options.maxAge ?? DEFAULT_MAX_AGE);
+    const answerPreflight = (req, allowed) => {
+        const headers = new Headers({
+            "access-control-allow-methods": methods,
+            "access-control-allow-origin": allowed,
+            "access-control-max-age": maxAge,
+        });
+        if (allowHeaders !== null)
+            headers.set("access-control-allow-headers", allowHeaders);
+        else {
+            const requested = req.headers.get("access-control-request-headers");
+            if (requested)
+                headers.set("access-control-allow-headers", requested);
+            addVary(headers, "Access-Control-Request-Headers");
+        }
+        if (credentials)
+            headers.set("access-control-allow-credentials", "true");
+        if (varies)
+            addVary(headers, "Origin");
+        return new Response(null, { headers, status: 204 });
+    };
+    return namedMiddleware("cors", async (ctx, next) => {
+        const req = ctx.req;
+        const requestOrigin = req.headers.get("origin");
+        const allowed = requestOrigin === null ? null : allowedOrigin(requestOrigin, origin);
+        if (allowed !== null && req.method === "OPTIONS" && req.headers.has("access-control-request-method")) {
+            return answerPreflight(req, allowed);
+        }
+        const response = await next();
+        if (allowed === null && !varies)
+            return response;
+        return withHeaders(response, (headers) => {
+            if (varies)
+                addVary(headers, "Origin");
+            if (allowed === null)
+                return;
+            headers.set("access-control-allow-origin", allowed);
+            if (credentials)
+                headers.set("access-control-allow-credentials", "true");
+            if (exposeHeaders !== null)
+                headers.set("access-control-expose-headers", exposeHeaders);
+        });
+    });
+}

package/dist/middleware/csrf.d.ts

@@ -0,0 +1,11 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type CSRFOptions = {
+    /**
+     * Cross-origin callers allowed to make unsafe requests, matched exactly against the full `Origin`
+     * (`https://app.example.com`). Same-origin requests never need listing.
+     */
+    origin?: ((origin: string) => boolean) | string | readonly string[];
+};
+export declare function csrf(options?: CSRFOptions): MiddlewareFn<{
+    req: Request;
+}, {}, "forbidden">;

package/dist/middleware/csrf.js

@@ -0,0 +1,65 @@
+/**
+ * `csrf(options)`: refuse cross-origin unsafe requests, whatever their content type, as Go's
+ * `http.CrossOriginProtection` does.
+ *
+ * 1. `GET`, `HEAD` and `OPTIONS` pass.
+ * 2. With `Sec-Fetch-Site` (every current browser sends it): `same-origin` and `none`
+ *    (user-initiated) pass; `same-site` and `cross-site` pass only for an allow-listed `Origin`. A
+ *    sibling subdomain is same-site, not trusted.
+ * 3. Without it: no `Origin` passes (curl, a server); an `Origin` on the request's own host passes;
+ *    an allow-listed one passes; anything else, the opaque `null` included, does not.
+ *
+ * A refusal is a 403 `forbidden`, declared on the middleware.
+ */
+import { HoneyError } from "../errors/error.js";
+import { namedMiddleware } from "./middleware.js";
+function isSafe(method) {
+    return method === "GET" || method === "HEAD" || method === "OPTIONS";
+}
+function allowListed(origin, allow) {
+    if (allow === undefined)
+        return false;
+    if (typeof allow === "string")
+        return allow === origin;
+    if (typeof allow === "function")
+        return allow(origin);
+    return allow.includes(origin);
+}
+/** `origin`'s host as a URL spells it, or `null` for the opaque origin or one that is no URL. */
+function hostOf(origin) {
+    if (origin === "null")
+        return null;
+    try {
+        return new URL(origin).host;
+    }
+    catch {
+        /* not a URL: an Origin no host matches, which the caller refuses */
+        return null;
+    }
+}
+function forbidden() {
+    throw new HoneyError({ errorKey: "forbidden", status: "forbidden" });
+}
+export function csrf(options = {}) {
+    const allow = options.origin;
+    const mw = (ctx, next) => {
+        const req = ctx.req;
+        if (isSafe(req.method))
+            return next();
+        const origin = req.headers.get("origin");
+        const site = req.headers.get("sec-fetch-site");
+        if (site !== null) {
+            if (site === "same-origin" || site === "none")
+                return next();
+            return origin !== null && allowListed(origin, allow) ? next() : forbidden();
+        }
+        if (origin === null)
+            return next();
+        /* the request URL is the canonical one the adapter built: its host is the one the client addressed */
+        if (hostOf(origin) === new URL(req.url).host)
+            return next();
+        return allowListed(origin, allow) ? next() : forbidden();
+    };
+    mw.errors = ["forbidden"];
+    return namedMiddleware("csrf", mw);
+}

package/dist/middleware/ip-restrict.d.ts

@@ -0,0 +1,10 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type IpRestrictOptions = {
+    /** Addresses and CIDR ranges admitted; with it, every other peer is refused. */
+    allowList?: readonly string[];
+    /** Addresses and CIDR ranges refused, checked before `allowList`. */
+    denyList?: readonly string[];
+};
+export declare function ipRestrict(options: IpRestrictOptions): MiddlewareFn<{
+    readonly ip: string | null;
+}, {}, "forbidden">;

package/dist/middleware/ip-restrict.js

@@ -0,0 +1,82 @@
+/**
+ * `ipRestrict({ allowList, denyList })`: admit or refuse a request by `ctx.ip`, the platform peer
+ * (H23): no forwarding header can stand in for it, so behind a self-hosted proxy restrict at the
+ * proxy. Rules are addresses or CIDR ranges, IPv4 or IPv6, compared as numbers, so every spelling
+ * of one address (IPv4-mapped, zero-compressed, any case) is one address.
+ *
+ * The deny list is checked first; with an allow list, everything else is refused. Fails closed: no
+ * reported peer is 403 under either list.
+ */
+import { parseIpv4, parseIpv6 } from "../context/peer.js";
+import { HoneyError } from "../errors/error.js";
+import { namedMiddleware } from "./middleware.js";
+const PREFIX_LENGTH = /^\d{1,3}$/;
+function v4Range(n, prefix) {
+    /* a shift by 32 is a shift by 0 in JS: /0 is spelled out */
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    return { base: (n & mask) >>> 0, mask, v: 4 };
+}
+/** An address or CIDR rule, strict: no brackets, zone or port, a prefix that fits the family. */
+function parseRule(rule) {
+    const slash = rule.indexOf("/");
+    const text = slash === -1 ? rule : rule.slice(0, slash);
+    const bits = slash === -1 ? null : rule.slice(slash + 1);
+    if (bits !== null && !PREFIX_LENGTH.test(bits))
+        return null;
+    if (!text.includes(":")) {
+        const n = parseIpv4(text);
+        const prefix = bits === null ? 32 : Number(bits);
+        return n === null || prefix > 32 ? null : v4Range(n, prefix);
+    }
+    const n = parseIpv6(text);
+    const prefix = bits === null ? 128 : Number(bits);
+    if (n === null || prefix > 128)
+        return null;
+    /* `::ffff:a.b.c.d/96` or longer is the IPv4 range it maps, which is how ctx.ip spells those peers */
+    if (n >> 32n === 0xffffn && prefix >= 96)
+        return v4Range(Number(n & 0xffffffffn), prefix - 96);
+    const mask = ((1n << BigInt(prefix)) - 1n) << BigInt(128 - prefix);
+    return { base: n & mask, mask, v: 6 };
+}
+function rulesOf(list, name) {
+    return (list ?? []).map((rule) => {
+        const range = parseRule(rule);
+        if (range === null) {
+            throw new TypeError(`ipRestrict: ${name} entry ${JSON.stringify(rule)} is not an IP address or CIDR range`);
+        }
+        return range;
+    });
+}
+/** ctx.ip is canonical (dotted IPv4 or RFC 5952 IPv6), so it always parses. */
+function addressOf(ip) {
+    return ip.includes(":") ? { n: parseIpv6(ip), v: 6 } : { n: parseIpv4(ip), v: 4 };
+}
+function inRange(addr, range) {
+    if (addr.v === 4)
+        return range.v === 4 && (addr.n & range.mask) >>> 0 === range.base;
+    return range.v === 6 && (addr.n & range.mask) === range.base;
+}
+function forbidden() {
+    throw new HoneyError({ errorKey: "forbidden", status: "forbidden" });
+}
+export function ipRestrict(options) {
+    if (options.allowList?.length === 0) {
+        throw new TypeError("ipRestrict: `allowList: []` would refuse every request; remove the middleware or list addresses");
+    }
+    const deny = rulesOf(options.denyList, "denyList");
+    const allow = rulesOf(options.allowList, "allowList");
+    if (deny.length === 0 && allow.length === 0)
+        throw new TypeError("ipRestrict: pass a non-empty `allowList` or `denyList`");
+    const mw = (ctx, next) => {
+        if (ctx.ip === null)
+            return forbidden();
+        const addr = addressOf(ctx.ip);
+        if (deny.some((range) => inRange(addr, range)))
+            return forbidden();
+        if (allow.length > 0 && !allow.some((range) => inRange(addr, range)))
+            return forbidden();
+        return next();
+    };
+    mw.errors = ["forbidden"];
+    return namedMiddleware("ipRestrict", mw);
+}

package/dist/middleware/middleware.d.ts

@@ -0,0 +1,53 @@
+export type MaybePromise<T> = Promise<T> | T;
+/** A Response carrying, at the type level only, the context a middleware added. */
+export type MiddlewareResult<TAdds = {}> = Response & {
+    readonly __adds?: TAdds;
+};
+/**
+ * Run the rest of the chain, optionally adding to the context. Answers synchronously when
+ * everything downstream did: `await` it, never `.then` it.
+ */
+export type NextFn = {
+    <T>(additions: T): MaybePromise<MiddlewareResult<T>>;
+    (): MaybePromise<MiddlewareResult<{}>>;
+};
+export type MiddlewareFn<TCtx = {}, TAdds = {}, TErrors extends string = string> = ((ctx: TCtx, next: NextFn) => MaybePromise<MiddlewareResult<TAdds>>) & {
+    errors?: readonly TErrors[];
+    /** Meta this middleware contributes to every route that mounts it. */
+    meta?: Readonly<Record<string, unknown>>;
+};
+/** A stored middleware, generics erased. */
+export type RuntimeMiddleware = (ctx: Record<string, unknown>, next: (additions?: Record<string, unknown>) => MaybePromise<Response>) => MaybePromise<Response>;
+/**
+ * Stamp a stable name on a middleware closure. `Function.prototype.name` is inferred by whatever
+ * transpiled the module, and transpilers disagree about a closure returned from a factory; a
+ * shipped middleware names itself so generated artifacts are deterministic.
+ */
+export declare function namedMiddleware<T extends object>(name: string, fn: T): T;
+/** A middleware whose error keys are constrained to a factory; `.use()` accumulates them. */
+export declare function defineMiddleware<TReqs, TAdds, TFactory extends Record<string, (...args: never[]) => unknown>, TKeys extends keyof TFactory & string>(opts: {
+    errors?: [TFactory, ...TKeys[]];
+    fn: MiddlewareFn<TReqs, TAdds>;
+    meta?: Record<string, unknown>;
+}): MiddlewareFn<TReqs, TAdds, TKeys>;
+/** The additions a middleware's return type carries; distributes over unions. */
+type ExtractAdds<T> = Awaited<T> extends MiddlewareResult<infer A> ? A : never;
+/**
+ * A middleware: annotate `ctx` for what it requires; what it adds is inferred from `next({...})`.
+ *   createMiddleware((ctx: { env: { DB: D1Database } }, next) => next({ db }))
+ */
+export declare function createMiddleware<TReqs = {}, TRet extends MaybePromise<Response> = MaybePromise<MiddlewareResult<{}>>>(fn: (ctx: TReqs, next: NextFn) => TRet, opts?: {
+    meta?: Record<string, unknown>;
+}): MiddlewareFn<TReqs, ExtractAdds<TRet>>;
+/** Merge the meta a chain contributes, in run order (later wins). Resolved once at finalize. */
+export declare function collectMiddlewareMeta(groups: ReadonlyArray<ReadonlyArray<RuntimeMiddleware>>): Record<string, unknown> | null;
+/** Turns a value thrown inside a chain into the Response that stands in for it. Must not throw. */
+export type ChainErrorConverter = (thrown: unknown, ctx: object) => MaybePromise<Response>;
+export type CompiledChain = (ctx: object) => MaybePromise<Response>;
+/**
+ * Compile a middleware chain and a handler into one function, once. Whatever the handler or a
+ * middleware throws or rejects with becomes a Response at that layer, so the middleware around it
+ * always gets a Response from `next()` and its post-`next()` code runs on errors too.
+ */
+export declare function compileChain(middlewares: readonly RuntimeMiddleware[], handler: (ctx: object) => MaybePromise<Response>, convert: ChainErrorConverter): CompiledChain;
+export {};