actor-ts 0.9.1 → 0.11.0

package/dist/http/middleware/IpAllowlist.js

@@ -0,0 +1,148 @@
+/**
+ * CIDR-based IP allowlist middleware (#312).
+ *
+ * Restricts a route subtree to clients whose IP falls inside one of
+ * the configured CIDRs.  Defence-in-depth on top of bearer-token auth
+ * (`BearerTokenAuth`): even if a token leaks, the attacker also needs
+ * to be on an allowlisted network to use it.
+ *
+ * Supports both IPv4 and IPv6 CIDRs in standard notation:
+ *   - `'10.0.0.0/8'` — RFC 1918 private space
+ *   - `'127.0.0.1/32'` — single host
+ *   - `'::1/128'` — IPv6 loopback
+ *   - `'fd00::/8'` — IPv6 ULA range
+ *
+ * IPv4-mapped IPv6 addresses (`::ffff:a.b.c.d`) are normalised so an
+ * IPv4 CIDR matches a request coming over a dual-stack socket.
+ *
+ * **Source of truth for the client IP** is the underlying socket
+ * (`req.remoteAddress`).  Operators behind a trusted reverse proxy
+ * (Cloudflare, AWS ALB, NGINX) that strip + set
+ * `x-forwarded-for` must pass a custom `getClientIp` that reads the
+ * header — the default DOES NOT trust `x-forwarded-for` because that
+ * header is client-spoofable when there's no proxy in front.
+ */
+import { HttpError, Status } from '../types.js';
+export function IpAllowlist(opts) {
+    if (opts.allow.length === 0) {
+        throw new Error('IpAllowlist: `allow` must be a non-empty list of CIDRs');
+    }
+    const parsed = opts.allow.map(parseCidr);
+    const getClientIp = opts.getClientIp ?? ((req) => req.remoteAddress);
+    return async (req, next) => {
+        const rawIp = getClientIp(req);
+        if (!rawIp) {
+            throw new HttpError(Status.Forbidden, 'IP not allowed (no client address)');
+        }
+        const matched = parsed.some((cidr) => ipMatches(rawIp, cidr));
+        if (!matched) {
+            throw new HttpError(Status.Forbidden, `IP not allowed: ${rawIp}`);
+        }
+        return next();
+    };
+}
+/* ------------------------------- internals ------------------------------- */
+/** Parse a `<address>/<prefix>` CIDR.  Throws on syntactically-invalid input. */
+function parseCidr(cidr) {
+    const slash = cidr.lastIndexOf('/');
+    if (slash < 0) {
+        throw new Error(`IpAllowlist: missing prefix length in CIDR "${cidr}"`);
+    }
+    const addr = cidr.slice(0, slash);
+    const prefixStr = cidr.slice(slash + 1);
+    const prefixBits = Number(prefixStr);
+    if (!Number.isInteger(prefixBits) || prefixBits < 0) {
+        throw new Error(`IpAllowlist: invalid prefix length in CIDR "${cidr}"`);
+    }
+    const ipv6 = addr.includes(':');
+    const totalBits = ipv6 ? 128 : 32;
+    if (prefixBits > totalBits) {
+        throw new Error(`IpAllowlist: prefix /${prefixBits} exceeds ${totalBits} bits in CIDR "${cidr}"`);
+    }
+    const fullMask = (BigInt(1) << BigInt(totalBits)) - BigInt(1);
+    const hostMask = fullMask >> BigInt(prefixBits);
+    const ipBn = ipToBigInt(addr, ipv6);
+    const network = ipBn & ~hostMask & fullMask;
+    return { ipv6, network, prefixBits, totalBits };
+}
+/** True if `ip` falls inside `cidr`.  Handles v4-in-v6 normalisation. */
+function ipMatches(ip, cidr) {
+    // IPv4-mapped IPv6 (`::ffff:a.b.c.d`) — strip the prefix so a plain
+    // IPv4 CIDR can match a dual-stack socket peer.
+    const stripped = stripV4Mapped(ip);
+    const requestIpv6 = stripped.includes(':');
+    if (requestIpv6 !== cidr.ipv6)
+        return false;
+    let candidate;
+    try {
+        candidate = ipToBigInt(stripped, requestIpv6);
+    }
+    catch {
+        return false; // unparseable address can't match any CIDR
+    }
+    const fullMask = (BigInt(1) << BigInt(cidr.totalBits)) - BigInt(1);
+    const hostMask = fullMask >> BigInt(cidr.prefixBits);
+    return (candidate & ~hostMask & fullMask) === cidr.network;
+}
+function stripV4Mapped(ip) {
+    // `::ffff:1.2.3.4` (RFC 4291 v4-mapped) or `::1.2.3.4` (deprecated v4-compat).
+    if (ip.toLowerCase().startsWith('::ffff:') && ip.includes('.')) {
+        return ip.slice('::ffff:'.length);
+    }
+    if (ip.startsWith('::') && ip.length > 2 && ip.includes('.') && !ip.toLowerCase().includes('ffff')) {
+        return ip.slice(2);
+    }
+    return ip;
+}
+function ipToBigInt(ip, isV6) {
+    if (!isV6)
+        return ipv4ToBigInt(ip);
+    return ipv6ToBigInt(ip);
+}
+function ipv4ToBigInt(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        throw new Error(`IpAllowlist: invalid IPv4 "${ip}"`);
+    let value = BigInt(0);
+    for (const part of parts) {
+        const octet = Number(part);
+        if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
+            throw new Error(`IpAllowlist: invalid IPv4 octet in "${ip}"`);
+        }
+        value = (value << BigInt(8)) | BigInt(octet);
+    }
+    return value;
+}
+function ipv6ToBigInt(ip) {
+    // Expand `::` to the full 8-group form.  Standard library doesn't
+    // expose a parser; this implementation handles all RFC 5952 forms
+    // we care about (with one `::` shorthand at most).
+    const halves = ip.split('::');
+    if (halves.length > 2)
+        throw new Error(`IpAllowlist: invalid IPv6 (multiple "::") in "${ip}"`);
+    const left = halves[0] === '' ? [] : halves[0].split(':');
+    const right = halves[1] === undefined ? [] : (halves[1] === '' ? [] : halves[1].split(':'));
+    // Fill the middle with zeros so total length is 8 groups.
+    const missing = 8 - (left.length + right.length);
+    if (missing < 0 && halves.length === 1) {
+        // No `::` shorthand — must already be 8 groups.
+    }
+    else if (missing < 0) {
+        throw new Error(`IpAllowlist: IPv6 "${ip}" has too many groups`);
+    }
+    const groups = halves.length === 1
+        ? ip.split(':')
+        : [...left, ...new Array(missing).fill('0'), ...right];
+    if (groups.length !== 8) {
+        throw new Error(`IpAllowlist: IPv6 "${ip}" did not expand to 8 groups (got ${groups.length})`);
+    }
+    let value = BigInt(0);
+    for (const group of groups) {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(group)) {
+            throw new Error(`IpAllowlist: invalid IPv6 group "${group}" in "${ip}"`);
+        }
+        value = (value << BigInt(16)) | BigInt(parseInt(group, 16));
+    }
+    return value;
+}
+//# sourceMappingURL=IpAllowlist.js.map

package/dist/http/middleware/IpAllowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IpAllowlist.js","sourceRoot":"","sources":["../../../src/http/middleware/IpAllowlist.ts"],"names":[],"mappings":"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"}

package/dist/http/middleware/RequestId.d.ts

@@ -0,0 +1,5 @@
+import type { Middleware } from '../Route.js';
+import type { RequestIdOptions } from './RequestIdOptions.js';
+/** Build a middleware that assigns/propagates a request id. */
+export declare function requestId(options?: RequestIdOptions): Middleware;
+//# sourceMappingURL=RequestId.d.ts.map

package/dist/http/middleware/RequestId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestId.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/RequestId.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAwB,MAAM,uBAAuB,CAAC;AAKpF,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,UAAU,CAYpE"}

package/dist/http/middleware/RequestId.js

@@ -0,0 +1,24 @@
+/**
+ * Request-id middleware.  Adds a stable id to the request (so handlers and
+ * downstream calls can correlate) and echoes it on the response.  An
+ * incoming id is accepted only if it is well-formed — never echo raw
+ * client bytes back into a header.
+ */
+import { randomUUID } from 'node:crypto';
+import { applyHeaders } from './headers.js';
+/** Conservative id shape — enough for UUIDs, ULIDs, and trace ids; caps length. */
+const VALID_ID = /^[A-Za-z0-9._-]{1,64}$/;
+/** Build a middleware that assigns/propagates a request id. */
+export function requestId(options = {}) {
+    const resolvedOptions = options;
+    const headerName = (resolvedOptions.headerName ?? 'x-request-id').toLowerCase();
+    const trustIncoming = resolvedOptions.trustIncoming ?? true;
+    const generate = resolvedOptions.generate ?? (() => randomUUID());
+    return async (req, next) => {
+        const incoming = trustIncoming ? req.headers[headerName] : undefined;
+        const id = incoming && VALID_ID.test(incoming) ? incoming : generate();
+        const res = await next({ ...req, headers: { ...req.headers, [headerName]: id } });
+        return applyHeaders(res, { [headerName]: id });
+    };
+}
+//# sourceMappingURL=RequestId.js.map

package/dist/http/middleware/RequestId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestId.js","sourceRoot":"","sources":["../../../src/http/middleware/RequestId.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,mFAAmF;AACnF,MAAM,QAAQ,GAAG,wBAAwB,CAAC;AAE1C,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,UAA4B,EAAE;IACtD,MAAM,eAAe,GAAG,OAAwC,CAAC;IACjE,MAAM,UAAU,GAAG,CAAC,eAAe,CAAC,UAAU,IAAI,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC;IAChF,MAAM,aAAa,GAAG,eAAe,CAAC,aAAa,IAAI,IAAI,CAAC;IAC5D,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,IAAI,CAAC,GAAW,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC;IAE1E,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACrE,MAAM,EAAE,GAAG,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACvE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QAClF,OAAO,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC,CAAC;AACJ,CAAC"}

package/dist/http/middleware/RequestIdOptions.d.ts

@@ -0,0 +1,22 @@
+/** Options for the {@link requestId} middleware.  Options-only. */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/** Plain settings shape for request-id. */
+export interface RequestIdOptionsType {
+    /** Header carrying the id, in + out.  Default `'x-request-id'`. */
+    readonly headerName?: string;
+    /** Accept a well-formed incoming id instead of always generating.  Default true. */
+    readonly trustIncoming?: boolean;
+    /** Id generator.  Default `crypto.randomUUID()`. */
+    readonly generate?: () => string;
+}
+/** Fluent builder for {@link RequestIdOptionsType}. */
+export declare class RequestIdOptionsBuilder extends OptionsBuilder<RequestIdOptionsType> {
+    static create(): RequestIdOptionsBuilder;
+    withHeaderName(name: string): this;
+    withTrustIncoming(flag?: boolean): this;
+    withGenerate(fn: () => string): this;
+}
+/** Accepted input: the builder or a plain object. */
+export type RequestIdOptions = RequestIdOptionsBuilder | Partial<RequestIdOptionsType>;
+export declare const RequestIdOptions: typeof RequestIdOptionsBuilder;
+//# sourceMappingURL=RequestIdOptions.d.ts.map

package/dist/http/middleware/RequestIdOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestIdOptions.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/RequestIdOptions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;CAClC;AAED,uDAAuD;AACvD,qBAAa,uBAAwB,SAAQ,cAAc,CAAC,oBAAoB,CAAC;IAC/E,MAAM,CAAC,MAAM,IAAI,uBAAuB;IAGxC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAGlC,iBAAiB,CAAC,IAAI,UAAO,GAAG,IAAI;IAGpC,YAAY,CAAC,EAAE,EAAE,MAAM,MAAM,GAAG,IAAI;CAGrC;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACvF,eAAO,MAAM,gBAAgB,gCAA0B,CAAC"}

package/dist/http/middleware/RequestIdOptions.js

@@ -0,0 +1,19 @@
+/** Options for the {@link requestId} middleware.  Options-only. */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/** Fluent builder for {@link RequestIdOptionsType}. */
+export class RequestIdOptionsBuilder extends OptionsBuilder {
+    static create() {
+        return new RequestIdOptionsBuilder();
+    }
+    withHeaderName(name) {
+        return this.set('headerName', name);
+    }
+    withTrustIncoming(flag = true) {
+        return this.set('trustIncoming', flag);
+    }
+    withGenerate(fn) {
+        return this.set('generate', fn);
+    }
+}
+export const RequestIdOptions = RequestIdOptionsBuilder;
+//# sourceMappingURL=RequestIdOptions.js.map

package/dist/http/middleware/RequestIdOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestIdOptions.js","sourceRoot":"","sources":["../../../src/http/middleware/RequestIdOptions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAY9D,uDAAuD;AACvD,MAAM,OAAO,uBAAwB,SAAQ,cAAoC;IAC/E,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,uBAAuB,EAAE,CAAC;IACvC,CAAC;IACD,cAAc,CAAC,IAAY;QACzB,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,iBAAiB,CAAC,IAAI,GAAG,IAAI;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,YAAY,CAAC,EAAgB;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;CACF;AAID,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC"}

package/dist/http/middleware/SecurityHeaders.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A small, typed, helmet-style bundle of sensible security response
+ * headers.  Every header is overridable and disable-able (`false`), the
+ * handler's own header always wins, and CSP is deliberately excluded (too
+ * app-specific — see {@link contentSecurityPolicy}).
+ */
+import type { Middleware } from '../Route.js';
+import type { SecurityHeadersOptions } from './SecurityHeadersOptions.js';
+/** Build a middleware that adds the configured security headers to every response. */
+export declare function securityHeaders(options?: SecurityHeadersOptions): Middleware;
+//# sourceMappingURL=SecurityHeaders.d.ts.map

package/dist/http/middleware/SecurityHeaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityHeaders.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/SecurityHeaders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,KAAK,EAAE,sBAAsB,EAA8B,MAAM,6BAA6B,CAAC;AAoBtG,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU,CA8BhF"}

package/dist/http/middleware/SecurityHeaders.js

@@ -0,0 +1,50 @@
+import { applyHeaders } from './headers.js';
+import { hstsHeaderValue, resolveHsts } from './Hsts.js';
+const FEATURE_RE = /^[a-z][a-z-]*$/;
+function serializePermissionsPolicy(policy) {
+    const parts = [];
+    for (const [feature, allow] of Object.entries(policy)) {
+        if (!FEATURE_RE.test(feature)) {
+            throw new Error(`securityHeaders: invalid Permissions-Policy feature "${feature}"`);
+        }
+        for (const item of allow) {
+            if (/[,()]/.test(item)) {
+                throw new Error(`securityHeaders: invalid Permissions-Policy allowlist item "${item}" for "${feature}"`);
+            }
+        }
+        parts.push(`${feature}=(${allow.join(' ')})`);
+    }
+    return parts.join(', ');
+}
+/** Build a middleware that adds the configured security headers to every response. */
+export function securityHeaders(options = {}) {
+    const resolvedOptions = options;
+    const headers = {};
+    if (resolvedOptions.contentTypeOptions ?? true)
+        headers['x-content-type-options'] = 'nosniff';
+    const frame = resolvedOptions.frameOptions ?? 'DENY';
+    if (frame !== false)
+        headers['x-frame-options'] = frame;
+    const referrer = resolvedOptions.referrerPolicy ?? 'no-referrer';
+    if (referrer !== false)
+        headers['referrer-policy'] = referrer;
+    const coop = resolvedOptions.crossOriginOpenerPolicy ?? 'same-origin';
+    if (coop !== false)
+        headers['cross-origin-opener-policy'] = coop;
+    const corp = resolvedOptions.crossOriginResourcePolicy ?? 'same-origin';
+    if (corp !== false)
+        headers['cross-origin-resource-policy'] = corp;
+    const coep = resolvedOptions.crossOriginEmbedderPolicy ?? false;
+    if (coep !== false)
+        headers['cross-origin-embedder-policy'] = coep;
+    if (resolvedOptions.xssProtection ?? true)
+        headers['x-xss-protection'] = '0';
+    const pp = resolvedOptions.permissionsPolicy ?? false;
+    if (pp !== false)
+        headers['permissions-policy'] = serializePermissionsPolicy(pp);
+    const hstsOpt = resolvedOptions.hsts ?? false;
+    if (hstsOpt !== false)
+        headers['strict-transport-security'] = hstsHeaderValue(resolveHsts(hstsOpt));
+    return async (_req, next) => applyHeaders(await next(), headers);
+}
+//# sourceMappingURL=SecurityHeaders.js.map

package/dist/http/middleware/SecurityHeaders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityHeaders.js","sourceRoot":"","sources":["../../../src/http/middleware/SecurityHeaders.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGzD,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAEpC,SAAS,0BAA0B,CAAC,MAAmD;IACrF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,wDAAwD,OAAO,GAAG,CAAC,CAAC;QACtF,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,+DAA+D,IAAI,UAAU,OAAO,GAAG,CAAC,CAAC;YAC3G,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,eAAe,GAAG,OAA8C,CAAC;IACvE,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,IAAI,eAAe,CAAC,kBAAkB,IAAI,IAAI;QAAE,OAAO,CAAC,wBAAwB,CAAC,GAAG,SAAS,CAAC;IAE9F,MAAM,KAAK,GAAG,eAAe,CAAC,YAAY,IAAI,MAAM,CAAC;IACrD,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC;IAExD,MAAM,QAAQ,GAAG,eAAe,CAAC,cAAc,IAAI,aAAa,CAAC;IACjE,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,QAAQ,CAAC;IAE9D,MAAM,IAAI,GAAG,eAAe,CAAC,uBAAuB,IAAI,aAAa,CAAC;IACtE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,4BAA4B,CAAC,GAAG,IAAI,CAAC;IAEjE,MAAM,IAAI,GAAG,eAAe,CAAC,yBAAyB,IAAI,aAAa,CAAC;IACxE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,8BAA8B,CAAC,GAAG,IAAI,CAAC;IAEnE,MAAM,IAAI,GAAG,eAAe,CAAC,yBAAyB,IAAI,KAAK,CAAC;IAChE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,8BAA8B,CAAC,GAAG,IAAI,CAAC;IAEnE,IAAI,eAAe,CAAC,aAAa,IAAI,IAAI;QAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,GAAG,CAAC;IAE7E,MAAM,EAAE,GAAG,eAAe,CAAC,iBAAiB,IAAI,KAAK,CAAC;IACtD,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,0BAA0B,CAAC,EAAE,CAAC,CAAC;IAEjF,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,IAAI,KAAK,CAAC;IAC9C,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,CAAC,2BAA2B,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IAEpG,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC"}

package/dist/http/middleware/SecurityHeadersOptions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Options for the {@link securityHeaders} bundle.  Every header is
+ * individually overridable, and `false` disables it.  Options-only.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import type { HstsOptionsType } from './HstsOptions.js';
+/** Plain settings shape for the security-headers bundle. */
+export interface SecurityHeadersOptionsType {
+    /** `X-Content-Type-Options: nosniff`.  Default true. */
+    readonly contentTypeOptions?: boolean;
+    /** `X-Frame-Options`.  Default `'DENY'`; `false` omits it. */
+    readonly frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    /** `Referrer-Policy`.  Default `'no-referrer'`; `false` omits it. */
+    readonly referrerPolicy?: string | false;
+    /** `Permissions-Policy` as feature→allowlist.  Default `false` (omitted). */
+    readonly permissionsPolicy?: Readonly<Record<string, readonly string[]>> | false;
+    /** `Cross-Origin-Opener-Policy`.  Default `'same-origin'`; `false` omits it. */
+    readonly crossOriginOpenerPolicy?: 'same-origin' | 'same-origin-allow-popups' | 'unsafe-none' | false;
+    /** `Cross-Origin-Resource-Policy`.  Default `'same-origin'`; `false` omits it. */
+    readonly crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin' | false;
+    /** `Cross-Origin-Embedder-Policy`.  Default `false` (breaks embeds; opt-in). */
+    readonly crossOriginEmbedderPolicy?: 'require-corp' | 'credentialless' | false;
+    /** `X-XSS-Protection: 0` (disable the buggy legacy filter).  Default true. */
+    readonly xssProtection?: boolean;
+    /** Also emit HSTS with these options.  Default `false` (opt-in — see {@link strictTransportSecurity}). */
+    readonly hsts?: Partial<HstsOptionsType> | false;
+}
+/** Fluent builder for {@link SecurityHeadersOptionsType}. */
+export declare class SecurityHeadersOptionsBuilder extends OptionsBuilder<SecurityHeadersOptionsType> {
+    static create(): SecurityHeadersOptionsBuilder;
+    withContentTypeOptions(flag?: boolean): this;
+    withFrameOptions(value: 'DENY' | 'SAMEORIGIN' | false): this;
+    withReferrerPolicy(value: string | false): this;
+    withPermissionsPolicy(value: Readonly<Record<string, readonly string[]>> | false): this;
+    withCrossOriginOpenerPolicy(value: 'same-origin' | 'same-origin-allow-popups' | 'unsafe-none' | false): this;
+    withCrossOriginResourcePolicy(value: 'same-origin' | 'same-site' | 'cross-origin' | false): this;
+    withCrossOriginEmbedderPolicy(value: 'require-corp' | 'credentialless' | false): this;
+    withXssProtection(flag?: boolean): this;
+    withHsts(value?: Partial<HstsOptionsType> | false): this;
+}
+/** Accepted input: the builder or a plain object. */
+export type SecurityHeadersOptions = SecurityHeadersOptionsBuilder | Partial<SecurityHeadersOptionsType>;
+export declare const SecurityHeadersOptions: typeof SecurityHeadersOptionsBuilder;
+//# sourceMappingURL=SecurityHeadersOptions.d.ts.map

package/dist/http/middleware/SecurityHeadersOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityHeadersOptions.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/SecurityHeadersOptions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,4DAA4D;AAC5D,MAAM,WAAW,0BAA0B;IACzC,wDAAwD;IACxD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,KAAK,CAAC;IACtD,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;IACjF,gFAAgF;IAChF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,aAAa,GAAG,0BAA0B,GAAG,aAAa,GAAG,KAAK,CAAC;IACtG,kFAAkF;IAClF,QAAQ,CAAC,yBAAyB,CAAC,EAAE,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,KAAK,CAAC;IAC1F,gFAAgF;IAChF,QAAQ,CAAC,yBAAyB,CAAC,EAAE,cAAc,GAAG,gBAAgB,GAAG,KAAK,CAAC;IAC/E,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,0GAA0G;IAC1G,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC;CAClD;AAED,6DAA6D;AAC7D,qBAAa,6BAA8B,SAAQ,cAAc,CAAC,0BAA0B,CAAC;IAC3F,MAAM,CAAC,MAAM,IAAI,6BAA6B;IAG9C,sBAAsB,CAAC,IAAI,UAAO,GAAG,IAAI;IAGzC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,KAAK,GAAG,IAAI;IAG5D,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAG/C,qBAAqB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI;IAGvF,2BAA2B,CAAC,KAAK,EAAE,aAAa,GAAG,0BAA0B,GAAG,aAAa,GAAG,KAAK,GAAG,IAAI;IAG5G,6BAA6B,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,KAAK,GAAG,IAAI;IAGhG,6BAA6B,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,GAAG,KAAK,GAAG,IAAI;IAGrF,iBAAiB,CAAC,IAAI,UAAO,GAAG,IAAI;IAGpC,QAAQ,CAAC,KAAK,GAAE,OAAO,CAAC,eAAe,CAAC,GAAG,KAAU,GAAG,IAAI;CAG7D;AAED,qDAAqD;AACrD,MAAM,MAAM,sBAAsB,GAAG,6BAA6B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;AACzG,eAAO,MAAM,sBAAsB,sCAAgC,CAAC"}

package/dist/http/middleware/SecurityHeadersOptions.js

@@ -0,0 +1,40 @@
+/**
+ * Options for the {@link securityHeaders} bundle.  Every header is
+ * individually overridable, and `false` disables it.  Options-only.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/** Fluent builder for {@link SecurityHeadersOptionsType}. */
+export class SecurityHeadersOptionsBuilder extends OptionsBuilder {
+    static create() {
+        return new SecurityHeadersOptionsBuilder();
+    }
+    withContentTypeOptions(flag = true) {
+        return this.set('contentTypeOptions', flag);
+    }
+    withFrameOptions(value) {
+        return this.set('frameOptions', value);
+    }
+    withReferrerPolicy(value) {
+        return this.set('referrerPolicy', value);
+    }
+    withPermissionsPolicy(value) {
+        return this.set('permissionsPolicy', value);
+    }
+    withCrossOriginOpenerPolicy(value) {
+        return this.set('crossOriginOpenerPolicy', value);
+    }
+    withCrossOriginResourcePolicy(value) {
+        return this.set('crossOriginResourcePolicy', value);
+    }
+    withCrossOriginEmbedderPolicy(value) {
+        return this.set('crossOriginEmbedderPolicy', value);
+    }
+    withXssProtection(flag = true) {
+        return this.set('xssProtection', flag);
+    }
+    withHsts(value = {}) {
+        return this.set('hsts', value);
+    }
+}
+export const SecurityHeadersOptions = SecurityHeadersOptionsBuilder;
+//# sourceMappingURL=SecurityHeadersOptions.js.map

package/dist/http/middleware/SecurityHeadersOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityHeadersOptions.js","sourceRoot":"","sources":["../../../src/http/middleware/SecurityHeadersOptions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAyB9D,6DAA6D;AAC7D,MAAM,OAAO,6BAA8B,SAAQ,cAA0C;IAC3F,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,6BAA6B,EAAE,CAAC;IAC7C,CAAC;IACD,sBAAsB,CAAC,IAAI,GAAG,IAAI;QAChC,OAAO,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;IACD,gBAAgB,CAAC,KAAoC;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IACD,kBAAkB,CAAC,KAAqB;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,qBAAqB,CAAC,KAA0D;QAC9E,OAAO,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,2BAA2B,CAAC,KAAyE;QACnG,OAAO,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IACD,6BAA6B,CAAC,KAA2D;QACvF,OAAO,IAAI,CAAC,GAAG,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IACD,6BAA6B,CAAC,KAAgD;QAC5E,OAAO,IAAI,CAAC,GAAG,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IACD,iBAAiB,CAAC,IAAI,GAAG,IAAI;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,QAAQ,CAAC,QAA0C,EAAE;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;CACF;AAID,MAAM,CAAC,MAAM,sBAAsB,GAAG,6BAA6B,CAAC"}

package/dist/http/middleware/Timeout.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Request-timeout middleware.  Races the handler against a deadline and
+ * returns 503 if it wins.
+ *
+ * Honest limitation: the handler is NOT cancelled — it keeps running, and
+ * its late result is discarded.  This bounds client-observed latency and
+ * how long a response is held open, nothing more.
+ */
+import type { Middleware } from '../Route.js';
+import { type TimeoutOptions } from './TimeoutOptions.js';
+/** Build a middleware that bounds handler latency.  Accepts a bare ms number or options. */
+export declare function requestTimeout(options: number | TimeoutOptions): Middleware;
+//# sourceMappingURL=Timeout.d.ts.map

package/dist/http/middleware/Timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeout.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/Timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA2B,KAAK,cAAc,EAA2B,MAAM,qBAAqB,CAAC;AAE5G,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,UAAU,CAuB3E"}

package/dist/http/middleware/Timeout.js

@@ -0,0 +1,29 @@
+import { Status } from '../types.js';
+import { TimeoutOptionsValidator } from './TimeoutOptions.js';
+/** Build a middleware that bounds handler latency.  Accepts a bare ms number or options. */
+export function requestTimeout(options) {
+    const resolvedOptions = typeof options === 'number' ? { ms: options } : options;
+    new TimeoutOptionsValidator().validate(resolvedOptions);
+    const ms = resolvedOptions.ms ?? 30_000;
+    const onTimeout = resolvedOptions.onTimeout
+        ?? (() => ({ status: Status.ServiceUnavailable, body: { error: 'request timed out' } }));
+    return async (req, next) => {
+        let timer;
+        const work = Promise.resolve(next());
+        // If the timeout wins, the handler may still reject later — swallow it
+        // here so it doesn't surface as an unhandled rejection.
+        work.catch(() => { });
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(onTimeout(req)), ms);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([work, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+}
+//# sourceMappingURL=Timeout.js.map

package/dist/http/middleware/Timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeout.js","sourceRoot":"","sources":["../../../src/http/middleware/Timeout.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,MAAM,EAAuC,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAgD,MAAM,qBAAqB,CAAC;AAE5G,4FAA4F;AAC5F,MAAM,UAAU,cAAc,CAAC,OAAgC;IAC7D,MAAM,eAAe,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAE,OAAuC,CAAC;IACjH,IAAI,uBAAuB,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,IAAI,MAAM,CAAC;IACxC,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS;WACtC,CAAC,GAAiB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,kBAAkB,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC;IAEzG,OAAO,KAAK,EAAE,GAAgB,EAAE,IAAI,EAAE,EAAE;QACtC,IAAI,KAAgD,CAAC;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACrC,uEAAuE;QACvE,wDAAwD;QACxD,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAA8C,CAAC,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,EAAE;YACpD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrD,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;QAC9C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/http/middleware/TimeoutOptions.d.ts

@@ -0,0 +1,30 @@
+/** Options for the {@link requestTimeout} middleware.  Options-only. */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+import type { HttpRequest, HttpResponse } from '../types.js';
+/** Plain settings shape for the request-timeout middleware. */
+export interface TimeoutOptionsType {
+    /** Deadline in milliseconds.  Default 30000. */
+    readonly ms?: number;
+    /** Response produced on timeout.  Default 503 `{ error: 'request timed out' }`. */
+    readonly onTimeout?: (req: HttpRequest) => HttpResponse;
+}
+/** Fluent builder for {@link TimeoutOptionsType}. */
+export declare class TimeoutOptionsBuilder extends OptionsBuilder<TimeoutOptionsType> {
+    static create(): TimeoutOptionsBuilder;
+    withMs(ms: number): this;
+    withOnTimeout(fn: (req: HttpRequest) => HttpResponse): this;
+}
+/** Accepted input: the builder or a plain object. */
+export type TimeoutOptions = TimeoutOptionsBuilder | Partial<TimeoutOptionsType>;
+export declare const TimeoutOptions: typeof TimeoutOptionsBuilder;
+/**
+ * Validates resolved {@link TimeoutOptionsType} settings — a timeout
+ * deadline (`ms`) must be a positive finite number.  Runs from any input
+ * path (bare number, plain object, builder) since it checks the resolved bag.
+ */
+export declare class TimeoutOptionsValidator extends OptionsValidator<TimeoutOptionsType> {
+    constructor();
+    protected rules(_s: Partial<TimeoutOptionsType>): void;
+}
+//# sourceMappingURL=TimeoutOptions.d.ts.map

package/dist/http/middleware/TimeoutOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeoutOptions.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/TimeoutOptions.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,YAAY,CAAC;CACzD;AAED,qDAAqD;AACrD,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,kBAAkB,CAAC;IAC3E,MAAM,CAAC,MAAM,IAAI,qBAAqB;IAGtC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAGxB,aAAa,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI;CAG5D;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;AACjF,eAAO,MAAM,cAAc,8BAAwB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,gBAAgB,CAAC,kBAAkB,CAAC;;IAI/E,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI;CAGvD"}

package/dist/http/middleware/TimeoutOptions.js

@@ -0,0 +1,30 @@
+/** Options for the {@link requestTimeout} middleware.  Options-only. */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/** Fluent builder for {@link TimeoutOptionsType}. */
+export class TimeoutOptionsBuilder extends OptionsBuilder {
+    static create() {
+        return new TimeoutOptionsBuilder();
+    }
+    withMs(ms) {
+        return this.set('ms', ms);
+    }
+    withOnTimeout(fn) {
+        return this.set('onTimeout', fn);
+    }
+}
+export const TimeoutOptions = TimeoutOptionsBuilder;
+/**
+ * Validates resolved {@link TimeoutOptionsType} settings — a timeout
+ * deadline (`ms`) must be a positive finite number.  Runs from any input
+ * path (bare number, plain object, builder) since it checks the resolved bag.
+ */
+export class TimeoutOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('TimeoutOptions');
+    }
+    rules(_s) {
+        this.positiveNumber('ms');
+    }
+}
+//# sourceMappingURL=TimeoutOptions.js.map

package/dist/http/middleware/TimeoutOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeoutOptions.js","sourceRoot":"","sources":["../../../src/http/middleware/TimeoutOptions.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAWlE,qDAAqD;AACrD,MAAM,OAAO,qBAAsB,SAAQ,cAAkC;IAC3E,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,qBAAqB,EAAE,CAAC;IACrC,CAAC;IACD,MAAM,CAAC,EAAU;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,aAAa,CAAC,EAAsC;QAClD,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;CACF;AAID,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,gBAAoC;IAC/E;QACE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC1B,CAAC;IACS,KAAK,CAAC,EAA+B;QAC7C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/http/middleware/headers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal header helpers shared by the response-decorating middleware
+ * (CORS, security headers, HSTS, …).  Not part of the public API.
+ */
+import type { HttpResponse } from '../types.js';
+/**
+ * Return a copy of `res` with `add` merged into its headers.  By default a
+ * key the response already carries (compared case-insensitively) is left
+ * untouched — so a handler's explicit header wins over a middleware
+ * default.  Pass `{ overwrite: true }` to force the middleware value.
+ */
+export declare function applyHeaders(res: HttpResponse, add: Readonly<Record<string, string>>, opts?: {
+    readonly overwrite?: boolean;
+}): HttpResponse;
+/**
+ * Merge `Vary` field names into an existing header value,
+ * case-insensitively de-duplicated (the first spelling is kept).  Caches
+ * must not cross-serve responses that vary by these fields.
+ */
+export declare function appendVary(existing: string | undefined, ...fields: string[]): string;
+//# sourceMappingURL=headers.d.ts.map

package/dist/http/middleware/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/headers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACrC,IAAI,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,YAAY,CASd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAcpF"}

package/dist/http/middleware/headers.js

@@ -0,0 +1,43 @@
+/**
+ * Return a copy of `res` with `add` merged into its headers.  By default a
+ * key the response already carries (compared case-insensitively) is left
+ * untouched — so a handler's explicit header wins over a middleware
+ * default.  Pass `{ overwrite: true }` to force the middleware value.
+ */
+export function applyHeaders(res, add, opts = {}) {
+    const existing = res.headers ?? {};
+    const present = new Set(Object.keys(existing).map((k) => k.toLowerCase()));
+    const merged = { ...existing };
+    for (const [k, v] of Object.entries(add)) {
+        if (!opts.overwrite && present.has(k.toLowerCase()))
+            continue;
+        merged[k] = v;
+    }
+    return { ...res, headers: merged };
+}
+/**
+ * Merge `Vary` field names into an existing header value,
+ * case-insensitively de-duplicated (the first spelling is kept).  Caches
+ * must not cross-serve responses that vary by these fields.
+ */
+export function appendVary(existing, ...fields) {
+    const seen = new Set();
+    const out = [];
+    const push = (field) => {
+        const trimmed = field.trim();
+        if (!trimmed)
+            return;
+        const lower = trimmed.toLowerCase();
+        if (seen.has(lower))
+            return;
+        seen.add(lower);
+        out.push(trimmed);
+    };
+    if (existing)
+        for (const f of existing.split(','))
+            push(f);
+    for (const f of fields)
+        push(f);
+    return out.join(', ');
+}
+//# sourceMappingURL=headers.js.map

package/dist/http/middleware/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../../src/http/middleware/headers.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAiB,EACjB,GAAqC,EACrC,OAAyC,EAAE;IAE3C,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3E,MAAM,MAAM,GAA2B,EAAE,GAAG,QAAQ,EAAE,CAAC;IACvD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;YAAE,SAAS;QAC9D,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,QAA4B,EAAE,GAAG,MAAgB;IAC1E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,CAAC,KAAa,EAAQ,EAAE;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO;QAC5B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,CAAC,CAAC;IACF,IAAI,QAAQ;QAAE,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3D,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAChC,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}