@zudojs/http 0.1.0 → 1.1.0

package/dist/httpCookies/http.cookies.d.ts

@@ -0,0 +1,92 @@
+import type { HTTPRequest, HTTPResponse } from "../httpTypes/http.types.js";
+export interface CookieOptions {
+    readonly maxAge?: number;
+    readonly expires?: Date;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly secure?: boolean;
+    readonly httpOnly?: boolean;
+    readonly sameSite?: CookieSameSite;
+    readonly partitioned?: boolean;
+    readonly priority?: CookiePriority;
+}
+export type CookieSameSite = "strict" | "lax" | "none";
+export type CookiePriority = "low" | "medium" | "high";
+export type CookieValue = string | number | boolean;
+export declare class CookieCollection {
+    private readonly values;
+    constructor(cookies?: Record<string, string> | Map<string, string>);
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    set(name: string, value: string): this;
+    delete(name: string): boolean;
+    clear(): void;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    valuesIterator(): IterableIterator<string>;
+    /**
+     * Materialises the jar as a plain record.
+     *
+     * The record has a `null` prototype so that a cookie named `__proto__`,
+     * `constructor` or `toString` can neither reach `Object.prototype` nor be
+     * confused with an inherited member on lookup.
+     *
+     * @returns A null-prototype record of cookie name to value.
+     */
+    toObject(): Record<string, string>;
+    get size(): number;
+}
+/**
+ * Maximum number of cookies parsed from one `Cookie` header.
+ */
+export declare const MAX_COOKIE_COUNT = 128;
+/**
+ * Maximum `Cookie` header length accepted, in characters.
+ */
+export declare const MAX_COOKIE_HEADER_LENGTH: number;
+/**
+ * Parses a `Cookie` request header.
+ *
+ * This function never throws: the header is fully attacker-controlled, so a
+ * malformed entry is skipped rather than allowed to abort the request. When
+ * a name occurs more than once the **first** occurrence wins, matching
+ * RFC 6265 section 5.4 ordering (most specific path first) and every browser
+ * and mainstream server library.
+ *
+ * @param header - The raw `Cookie` header value.
+ * @returns The parsed cookie jar.
+ */
+export declare function parseCookies(header: string | undefined): CookieCollection;
+export declare function serializeCookie(name: string, value: CookieValue, options?: CookieOptions): string;
+export interface CookieManager {
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    set(name: string, value: CookieValue, options?: CookieOptions): void;
+    delete(name: string, options?: CookieOptions): void;
+    parse(): CookieCollection;
+}
+export declare function getRequestCookies(request: HTTPRequest): CookieCollection;
+export declare function getRequestCookie(request: HTTPRequest, name: string): string | undefined;
+export declare function setResponseCookie(response: HTTPResponse, name: string, value: CookieValue, options?: CookieOptions): void;
+export declare function deleteResponseCookie(response: HTTPResponse, name: string, options?: CookieOptions): void;
+export declare function appendSetCookieHeader(response: HTTPResponse, cookie: string): void;
+export declare function createCookieManager(request: HTTPRequest, response: HTTPResponse): CookieManager;
+export interface SignedCookieOptions extends CookieOptions {
+    readonly secret: string;
+}
+export interface SignedCookie {
+    readonly value: string;
+    readonly signature: string;
+}
+export declare function serializeSignedCookie(name: string, value: string, options: SignedCookieOptions): string;
+export declare function parseSignedCookie(value: string | undefined, secret: string): string | undefined;
+/**
+ * Signs a cookie value with HMAC-SHA256.
+ *
+ * @param value - The value to authenticate.
+ * @param secret - The signing key.
+ * @returns The base64url signature.
+ * @throws {TypeError} If the secret is empty.
+ */
+export declare function signCookieValue(value: string, secret: string): string;
+//# sourceMappingURL=http.cookies.d.ts.map

package/dist/httpCookies/http.cookies.js

@@ -0,0 +1,417 @@
+import { createHmac, timingSafeEqual as cryptoTimingSafeEqual, } from "node:crypto";
+/* -------------------------------------------------------------------------- */
+/* Cookie Collection                                                          */
+/* -------------------------------------------------------------------------- */
+export class CookieCollection {
+    values = new Map();
+    constructor(cookies = {}) {
+        if (cookies instanceof Map) {
+            for (const [name, value] of cookies) {
+                this.values.set(name, value);
+            }
+            return;
+        }
+        for (const [name, value] of Object.entries(cookies)) {
+            this.values.set(name, value);
+        }
+    }
+    get(name) {
+        return this.values.get(name);
+    }
+    has(name) {
+        return this.values.has(name);
+    }
+    set(name, value) {
+        validateCookieName(name);
+        this.values.set(name, value);
+        return this;
+    }
+    delete(name) {
+        return this.values.delete(name);
+    }
+    clear() {
+        this.values.clear();
+    }
+    entries() {
+        return this.values.entries();
+    }
+    keys() {
+        return this.values.keys();
+    }
+    valuesIterator() {
+        return this.values.values();
+    }
+    /**
+     * Materialises the jar as a plain record.
+     *
+     * The record has a `null` prototype so that a cookie named `__proto__`,
+     * `constructor` or `toString` can neither reach `Object.prototype` nor be
+     * confused with an inherited member on lookup.
+     *
+     * @returns A null-prototype record of cookie name to value.
+     */
+    toObject() {
+        const result = Object.create(null);
+        for (const [name, value] of this.values) {
+            result[name] = value;
+        }
+        return result;
+    }
+    get size() {
+        return this.values.size;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Parse Cookie Header                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Maximum number of cookies parsed from one `Cookie` header.
+ */
+export const MAX_COOKIE_COUNT = 128;
+/**
+ * Maximum `Cookie` header length accepted, in characters.
+ */
+export const MAX_COOKIE_HEADER_LENGTH = 32 * 1024;
+/**
+ * RFC 6265 `cookie-name`, which is an RFC 9110 `token`.
+ */
+const COOKIE_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * Parses a `Cookie` request header.
+ *
+ * This function never throws: the header is fully attacker-controlled, so a
+ * malformed entry is skipped rather than allowed to abort the request. When
+ * a name occurs more than once the **first** occurrence wins, matching
+ * RFC 6265 section 5.4 ordering (most specific path first) and every browser
+ * and mainstream server library.
+ *
+ * @param header - The raw `Cookie` header value.
+ * @returns The parsed cookie jar.
+ */
+export function parseCookies(header) {
+    const values = new Map();
+    if (!header) {
+        return new CookieCollection(values);
+    }
+    const bounded = header.slice(0, MAX_COOKIE_HEADER_LENGTH);
+    for (const part of splitCookieHeader(bounded)) {
+        if (values.size >= MAX_COOKIE_COUNT) {
+            break;
+        }
+        const separator = part.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const name = part.slice(0, separator).trim();
+        const rawValue = part.slice(separator + 1).trim();
+        if (!COOKIE_NAME_TOKEN.test(name)) {
+            continue;
+        }
+        /*
+         * First occurrence wins. Taking the last would let an attacker who can
+         * set a cookie on a parent domain or a less specific path override the
+         * legitimate one, while the browser still considers the first
+         * authoritative.
+         */
+        if (values.has(name)) {
+            continue;
+        }
+        values.set(name, decodeCookieValue(rawValue));
+    }
+    return new CookieCollection(values);
+}
+/* -------------------------------------------------------------------------- */
+/* Serialize Cookie                                                           */
+/* -------------------------------------------------------------------------- */
+export function serializeCookie(name, value, options = {}) {
+    validateCookieName(name);
+    validateCookiePrefix(name, options);
+    const encodedName = name;
+    const encodedValue = encodeCookieValue(String(value));
+    const parts = [`${encodedName}=${encodedValue}`];
+    if (options.maxAge !== undefined) {
+        if (!Number.isFinite(options.maxAge)) {
+            throw new TypeError("Cookie maxAge must be a finite number.");
+        }
+        parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+    }
+    if (options.expires) {
+        if (Number.isNaN(options.expires.getTime())) {
+            throw new TypeError("Cookie expires must be a valid Date.");
+        }
+        parts.push(`Expires=${options.expires.toUTCString()}`);
+    }
+    if (options.domain) {
+        validateCookieAttribute("domain", options.domain);
+        parts.push(`Domain=${options.domain}`);
+    }
+    if (options.path) {
+        validateCookieAttribute("path", options.path);
+        parts.push(`Path=${options.path}`);
+    }
+    if (options.httpOnly) {
+        parts.push("HttpOnly");
+    }
+    if (options.secure) {
+        parts.push("Secure");
+    }
+    if (options.sameSite) {
+        const sameSite = normalizeSameSite(options.sameSite);
+        parts.push(`SameSite=${sameSite}`);
+    }
+    if (options.partitioned) {
+        parts.push("Partitioned");
+    }
+    if (options.priority) {
+        parts.push(`Priority=${normalizePriority(options.priority)}`);
+    }
+    return parts.join("; ");
+}
+/* -------------------------------------------------------------------------- */
+/* Request Cookies                                                            */
+/* -------------------------------------------------------------------------- */
+export function getRequestCookies(request) {
+    const header = request.getHeader("cookie");
+    return parseCookies(header);
+}
+export function getRequestCookie(request, name) {
+    return getRequestCookies(request).get(name);
+}
+/* -------------------------------------------------------------------------- */
+/* Response Cookies                                                           */
+/* -------------------------------------------------------------------------- */
+export function setResponseCookie(response, name, value, options = {}) {
+    const serialized = serializeCookie(name, value, options);
+    appendSetCookieHeader(response, serialized);
+}
+export function deleteResponseCookie(response, name, options = {}) {
+    setResponseCookie(response, name, "", {
+        ...options,
+        maxAge: 0,
+        expires: new Date(0),
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Response Header Helpers                                                    */
+/* -------------------------------------------------------------------------- */
+export function appendSetCookieHeader(response, cookie) {
+    const existing = response.getHeader("Set-Cookie");
+    if (existing === undefined) {
+        response.setHeader("Set-Cookie", [cookie]);
+        return;
+    }
+    const values = Array.isArray(existing)
+        ? existing.map(String)
+        : [String(existing)];
+    values.push(cookie);
+    response.setHeader("Set-Cookie", values);
+}
+/* -------------------------------------------------------------------------- */
+/* Cookie Manager Factory                                                     */
+/* -------------------------------------------------------------------------- */
+export function createCookieManager(request, response) {
+    const parsed = getRequestCookies(request);
+    return {
+        get(name) {
+            return parsed.get(name);
+        },
+        has(name) {
+            return parsed.has(name);
+        },
+        set(name, value, options) {
+            setResponseCookie(response, name, value, options);
+        },
+        delete(name, options) {
+            deleteResponseCookie(response, name, options);
+        },
+        parse() {
+            return parsed;
+        },
+    };
+}
+export function serializeSignedCookie(name, value, options) {
+    const signature = signCookieValue(value, options.secret);
+    return serializeCookie(name, `${value}.${signature}`, options);
+}
+export function parseSignedCookie(value, secret) {
+    if (!value) {
+        return undefined;
+    }
+    const separator = value.lastIndexOf(".");
+    if (separator <= 0) {
+        return undefined;
+    }
+    const originalValue = value.slice(0, separator);
+    const signature = value.slice(separator + 1);
+    const expected = signCookieValue(originalValue, secret);
+    if (!timingSafeEqual(signature, expected)) {
+        return undefined;
+    }
+    return originalValue;
+}
+/**
+ * Signs a cookie value with HMAC-SHA256.
+ *
+ * @param value - The value to authenticate.
+ * @param secret - The signing key.
+ * @returns The base64url signature.
+ * @throws {TypeError} If the secret is empty.
+ */
+export function signCookieValue(value, secret) {
+    if (!secret) {
+        throw new TypeError("Cookie signing secret cannot be empty.");
+    }
+    return createHmac("sha256", secret).update(value, "utf8").digest("base64url");
+}
+/* -------------------------------------------------------------------------- */
+/* Cookie Encoding                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Percent-encodes a cookie value.
+ *
+ * SP is deliberately left encoded: RFC 6265 `cookie-octet` excludes it, and
+ * emitting a raw space breaks strict parsers and some proxies.
+ *
+ * @param value - The raw cookie value.
+ * @returns The encoded value.
+ */
+function encodeCookieValue(value) {
+    return encodeURIComponent(value);
+}
+/**
+ * Percent-decodes a cookie value.
+ *
+ * DQUOTE is not stripped: it is an ordinary `cookie-octet`, and unwrapping it
+ * makes the parse disagree with the browser about the value.
+ *
+ * @param value - The raw cookie value.
+ * @returns The decoded value, or the raw value when decoding fails.
+ */
+function decodeCookieValue(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Header Parsing                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * Splits a `Cookie` header into its `name=value` pairs.
+ *
+ * The split is unconditional on `;` per RFC 6265 section 5.4. DQUOTE is an
+ * ordinary `cookie-octet` there with no delimiting meaning, so tracking
+ * quotes would let a single unbalanced `"` in one attacker-set cookie swallow
+ * every cookie after it — a cookie-shadowing primitive.
+ *
+ * @param header - The raw header value.
+ * @returns The unparsed pairs.
+ */
+function splitCookieHeader(header) {
+    return header.split(";");
+}
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Validates a cookie name against the RFC 6265 `cookie-name` production.
+ *
+ * @param name - The cookie name.
+ * @throws {TypeError} If the name is empty or contains a non-token character
+ *   — which includes NUL and DEL, whose acceptance would let an intermediary
+ *   truncate the name and set a different cookie than the one requested.
+ */
+function validateCookieName(name) {
+    if (!name) {
+        throw new TypeError("Cookie name cannot be empty.");
+    }
+    if (!COOKIE_NAME_TOKEN.test(name)) {
+        throw new TypeError(`Invalid cookie name: ${JSON.stringify(name)}`);
+    }
+}
+/**
+ * Enforces the RFC 6265bis section 4.1.3 cookie name prefixes.
+ *
+ * A browser silently drops a `__Host-` or `__Secure-` cookie whose
+ * attributes violate the prefix, and the failure is invisible server-side —
+ * a login that quietly does nothing. Failing loudly here is the only way the
+ * caller learns.
+ *
+ * @param name - The cookie name.
+ * @param options - The cookie attributes.
+ * @throws {TypeError} If a prefix constraint is violated.
+ */
+function validateCookiePrefix(name, options) {
+    if (name.startsWith("__Host-")) {
+        if (!options.secure) {
+            throw new TypeError("A __Host- cookie requires the Secure attribute.");
+        }
+        if (options.domain) {
+            throw new TypeError("A __Host- cookie must not set a Domain attribute.");
+        }
+        if ((options.path ?? "/") !== "/") {
+            throw new TypeError("A __Host- cookie requires Path=/.");
+        }
+        return;
+    }
+    if (name.startsWith("__Secure-") && !options.secure) {
+        throw new TypeError("A __Secure- cookie requires the Secure attribute.");
+    }
+}
+/**
+ * Validates a cookie attribute value.
+ *
+ * @param attribute - The attribute name, for the error message.
+ * @param value - The attribute value.
+ * @throws {TypeError} If the value contains `;` or any control character.
+ */
+function validateCookieAttribute(attribute, value) {
+    if (/[;\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError(`Invalid cookie ${attribute}.`);
+    }
+}
+function normalizeSameSite(value) {
+    switch (value) {
+        case "strict":
+            return "Strict";
+        case "lax":
+            return "Lax";
+        case "none":
+            return "None";
+        default:
+            throw new TypeError(`Invalid SameSite value: ${String(value)}`);
+    }
+}
+function normalizePriority(value) {
+    switch (value) {
+        case "low":
+            return "Low";
+        case "medium":
+            return "Medium";
+        case "high":
+            return "High";
+        default:
+            throw new TypeError(`Invalid cookie priority: ${String(value)}`);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Hash Helpers                                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * Compares two signatures in constant time.
+ *
+ * @param left - The candidate signature.
+ * @param right - The expected signature.
+ * @returns `true` if the two are byte-identical.
+ */
+function timingSafeEqual(left, right) {
+    const leftBuffer = Buffer.from(left, "utf8");
+    const rightBuffer = Buffer.from(right, "utf8");
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return cryptoTimingSafeEqual(leftBuffer, rightBuffer);
+}
+//# sourceMappingURL=http.cookies.js.map

package/dist/httpCors/http.cors.d.ts

@@ -0,0 +1,152 @@
+/**
+ * HTTP CORS utilities.
+ *
+ * Provides parsing, validation, policy evaluation, and response-header
+ * generation for Cross-Origin Resource Sharing.
+ */
+export type CorsOrigin = string | readonly string[] | ((origin: string) => boolean | Promise<boolean>);
+export type CorsMethods = string | readonly string[];
+export type CorsHeaders = string | readonly string[];
+export interface CorsOptions {
+    readonly origin?: CorsOrigin;
+    readonly methods?: CorsMethods;
+    readonly allowedHeaders?: CorsHeaders;
+    readonly exposedHeaders?: CorsHeaders;
+    readonly credentials?: boolean;
+    readonly maxAge?: number;
+    readonly preflightContinue?: boolean;
+    readonly optionsSuccessStatus?: number;
+}
+export interface CorsRequest {
+    readonly origin?: string;
+    readonly method?: string;
+    readonly requestMethod?: string;
+    readonly requestHeaders?: string;
+}
+export interface CorsResult {
+    readonly allowed: boolean;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly preflight: boolean;
+    readonly vary: readonly string[];
+}
+export interface CorsPolicy {
+    readonly origin: CorsOrigin;
+    readonly methods: readonly string[];
+    readonly allowedHeaders: readonly string[];
+    readonly exposedHeaders: readonly string[];
+    readonly credentials: boolean;
+    readonly maxAge?: number;
+    /**
+     * True when the configured origin allows every origin — whether written as
+     * the string `"*"` or as a `"*"` element inside an array. Credentials can
+     * never be combined with it.
+     */
+    readonly wildcard: boolean;
+    readonly preflightContinue: boolean;
+    readonly optionsSuccessStatus: number;
+}
+/**
+ * The decision a CORS-aware middleware needs in order to act.
+ */
+export interface CorsDecision {
+    /** True when the request carried an `Origin` header at all. */
+    readonly isCorsRequest: boolean;
+    readonly preflight: boolean;
+    /** True when the origin (and, for a preflight, the method/headers) passed. */
+    readonly allowed: boolean;
+    /**
+     * True when the middleware should answer the request itself rather than
+     * calling `next()`. Only ever true for a preflight with
+     * `preflightContinue: false`.
+     */
+    readonly terminate: boolean;
+    /** Status to answer a terminated preflight with. */
+    readonly status: number;
+    /**
+     * Headers to apply to the response, `Vary` already merged in. Always
+     * contains `Vary: Origin` for any origin-dependent response, including a
+     * rejected one, so a shared cache cannot serve one origin's CORS grant to
+     * another.
+     */
+    readonly headers: Readonly<Record<string, string>>;
+}
+export declare const CORS_ORIGIN_HEADER = "Access-Control-Allow-Origin";
+export declare const CORS_METHODS_HEADER = "Access-Control-Allow-Methods";
+export declare const CORS_HEADERS_HEADER = "Access-Control-Allow-Headers";
+export declare const CORS_EXPOSE_HEADERS_HEADER = "Access-Control-Expose-Headers";
+export declare const CORS_CREDENTIALS_HEADER = "Access-Control-Allow-Credentials";
+export declare const CORS_MAX_AGE_HEADER = "Access-Control-Max-Age";
+export declare const CORS_REQUEST_METHOD_HEADER = "Access-Control-Request-Method";
+export declare const CORS_REQUEST_HEADERS_HEADER = "Access-Control-Request-Headers";
+export declare const CORS_VARY_HEADER = "Vary";
+export declare const DEFAULT_CORS_METHODS: readonly string[];
+export declare const DEFAULT_OPTIONS_SUCCESS_STATUS = 204;
+export declare function normalizeOrigin(origin: string | undefined | null): string | undefined;
+export declare function isWildcardOrigin(origin: string | undefined | null): boolean;
+/**
+ * Canonicalises an origin for comparison.
+ *
+ * An origin is scheme + host + port. Scheme and host are case-insensitive, the
+ * default port is implicit, and there is no path — so `HTTPS://App.Example.com`
+ * and `https://app.example.com:443/` are the same origin and must compare
+ * equal, while anything that is not a parseable http(s) origin falls back to a
+ * trimmed, lower-cased literal so that `"null"` still compares by value.
+ */
+export declare function canonicalizeOrigin(origin: string | undefined | null): string | undefined;
+/**
+ * True when the configured origin permits every origin.
+ */
+export declare function hasWildcardOrigin(configured: CorsOrigin | undefined): boolean;
+export declare function isNullOrigin(origin: string | undefined | null): boolean;
+export declare function isValidOrigin(origin: string | undefined | null): boolean;
+export declare function normalizeMethods(methods: CorsMethods | undefined): readonly string[];
+export declare function isMethodAllowed(method: string | undefined | null, allowedMethods: CorsMethods): boolean;
+export declare function normalizeHeaderNames(headers: CorsHeaders | undefined): readonly string[];
+export declare function areHeadersAllowed(requestedHeaders: CorsHeaders | undefined, allowedHeaders: CorsHeaders): boolean;
+export declare function parseRequestedHeaders(value: string | undefined | null): readonly string[];
+/**
+ * Decides whether a request origin is permitted by the configured origin.
+ *
+ * Matching is **exact on the canonical origin**. It is deliberately not
+ * `startsWith`, `endsWith`, `includes` or an unescaped regex built from the
+ * configured value: against `https://example.com`, all of those admit
+ * `https://evil-example.com.attacker.com`, `https://example.com.evil.tld` or
+ * `https://example.como`. A caller that needs subdomain matching must supply a
+ * predicate function and take responsibility for anchoring it.
+ *
+ * The opaque origin `null` (sandboxed iframes, `file://`, some redirects) is
+ * only allowed when `"null"` is configured explicitly. It is never covered by
+ * `"*"`, because reflecting it grants access to content any page can produce.
+ */
+export declare function matchesOrigin(configured: CorsOrigin | undefined, requestOrigin: string | undefined): Promise<boolean>;
+export declare function createCorsPolicy(options?: CorsOptions | undefined): CorsPolicy;
+export declare function isCorsRequest(request: CorsRequest): boolean;
+export declare function isPreflightRequest(request: CorsRequest): boolean;
+export declare function isSimpleCorsRequest(request: CorsRequest): boolean;
+export declare function validatePreflight(request: CorsRequest, policy: CorsPolicy): boolean;
+export declare function createCorsHeaders(request: CorsRequest, policy: CorsPolicy): Promise<Readonly<Record<string, string>>>;
+export declare function evaluateCors(request: CorsRequest, options: CorsOptions | CorsPolicy): Promise<CorsResult>;
+export declare function getCorsVaryHeaders(request: CorsRequest, policy: CorsPolicy): readonly string[];
+export declare function formatVaryHeader(values: readonly string[]): string;
+export declare function shouldHandlePreflight(request: CorsRequest): boolean;
+export declare function getPreflightStatus(options?: CorsOptions | undefined): number;
+export declare function serializeCorsHeaders(headers: Readonly<Record<string, string>>, vary: readonly string[] | undefined): Readonly<Record<string, string>>;
+/**
+ * Evaluates a request against a CORS policy and returns everything a
+ * middleware needs: whether to answer the request itself, with what status,
+ * and which headers to set.
+ *
+ * This is the function a CORS middleware should be built on. It differs from
+ * the naive "always set `Access-Control-Allow-Origin: *`" approach in four
+ * ways that each matter:
+ *
+ * 1. A request with no `Origin` gets no CORS headers at all.
+ * 2. A disallowed origin gets no `Access-Control-Allow-Origin`, so the browser
+ *    blocks the read — rather than the server advertising a grant it did not
+ *    intend.
+ * 3. `Vary: Origin` is emitted on every origin-dependent response, allowed or
+ *    not, so a CDN cannot serve one origin's grant to another.
+ * 4. A preflight is answered here, before the router can 404/405 it.
+ */
+export declare function evaluateCorsDecision(request: CorsRequest, options: CorsOptions | CorsPolicy): Promise<CorsDecision>;
+//# sourceMappingURL=http.cors.d.ts.map