@zudojs/http 1.1.0 → 1.2.0

package/dist/httpAdapter/node/httpNode.type.d.ts

@@ -6,7 +6,8 @@
 import type { Server } from "node:http";
 import type { HttpAdapterOptions } from "../http.adapter.js";
 import type { TrustProxy } from "../../httpTrustProxy/httpTrustProxy.core.js";
-export interface NodeAdapterOptions extends HttpAdapterOptions {
+import type { NodeAdapterSecurityOptions } from "../../httpSecurity/httpSecurity.nodeGuard.js";
+export interface NodeAdapterOptions extends HttpAdapterOptions, NodeAdapterSecurityOptions {
     readonly host?: string;
     readonly port?: number;
     readonly server?: Server;

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

@@ -57,7 +57,14 @@ export declare const MAX_COOKIE_HEADER_LENGTH: number;
  * @returns The parsed cookie jar.
  */
 export declare function parseCookies(header: string | undefined): CookieCollection;
-export declare function serializeCookie(name: string, value: CookieValue, options?: CookieOptions): string;
+/**
+ * Serializes a `Set-Cookie` header value.
+ *
+ * Unset attributes take the secure defaults (`Path=/; HttpOnly; Secure;
+ * SameSite=Lax`, see `DEFAULT_COOKIE_ATTRIBUTES`); pass `httpOnly: false`,
+ * `secure: false`, another `sameSite` or `path` to override them.
+ */
+export declare function serializeCookie(name: string, value: CookieValue, cookieOptions?: CookieOptions): string;
 export interface CookieManager {
     get(name: string): string | undefined;
     has(name: string): boolean;
@@ -78,11 +85,31 @@ export interface SignedCookie {
     readonly value: string;
     readonly signature: string;
 }
+/**
+ * Serializes a signed cookie. The MAC covers the cookie **name** as well as
+ * the value, so a signature minted for one cookie is not accepted for
+ * another; read it back with `parseSignedCookie(value, secret, name)`.
+ */
 export declare function serializeSignedCookie(name: string, value: string, options: SignedCookieOptions): string;
-export declare function parseSignedCookie(value: string | undefined, secret: string): string | undefined;
+/**
+ * Verifies a signed cookie value and returns the original value, or
+ * `undefined` when the signature does not match.
+ *
+ * Pass the cookie's `name`: the signature produced by
+ * `serializeSignedCookie` is bound to it, so a value lifted from another
+ * signed cookie (for example a user-chosen display name replayed as
+ * `session_user`) is rejected. Without `name` only a legacy, value-only
+ * signature (from `signCookieValue(value, secret)`) verifies, and
+ * name-bound signatures never do.
+ */
+export declare function parseSignedCookie(value: string | undefined, secret: string, name?: string): string | undefined;
 /**
  * Signs a cookie value with HMAC-SHA256.
  *
+ * Synchronous by contract, so the MAC is computed with `node:crypto`: every
+ * `@zudojs/crypto` HMAC helper is asynchronous. Verification compares with
+ * `@zudojs/crypto`'s constant-time `timingSafeEqualString`.
+ *
  * @param value - The value to authenticate.
  * @param secret - The signing key.
  * @returns The base64url signature.

package/dist/httpCookies/http.cookies.js

@@ -1,4 +1,6 @@
-import { createHmac, timingSafeEqual as cryptoTimingSafeEqual, } from "node:crypto";
+import { createHmac } from "node:crypto";
+import { timingSafeEqualString } from "@zudojs/crypto";
+import { withSecureCookieDefaults } from "./httpCookies.defaults.js";
 /* -------------------------------------------------------------------------- */
 /* Cookie Collection                                                          */
 /* -------------------------------------------------------------------------- */
@@ -123,7 +125,15 @@ export function parseCookies(header) {
 /* -------------------------------------------------------------------------- */
 /* Serialize Cookie                                                           */
 /* -------------------------------------------------------------------------- */
-export function serializeCookie(name, value, options = {}) {
+/**
+ * Serializes a `Set-Cookie` header value.
+ *
+ * Unset attributes take the secure defaults (`Path=/; HttpOnly; Secure;
+ * SameSite=Lax`, see `DEFAULT_COOKIE_ATTRIBUTES`); pass `httpOnly: false`,
+ * `secure: false`, another `sameSite` or `path` to override them.
+ */
+export function serializeCookie(name, value, cookieOptions = {}) {
+    const options = withSecureCookieDefaults(cookieOptions, "lax");
     validateCookieName(name);
     validateCookiePrefix(name, options);
     const encodedName = name;
@@ -229,11 +239,27 @@ export function createCookieManager(request, response) {
         },
     };
 }
+/**
+ * Serializes a signed cookie. The MAC covers the cookie **name** as well as
+ * the value, so a signature minted for one cookie is not accepted for
+ * another; read it back with `parseSignedCookie(value, secret, name)`.
+ */
 export function serializeSignedCookie(name, value, options) {
-    const signature = signCookieValue(value, options.secret);
+    const signature = signCookieValue(bindCookieName(name, value), options.secret);
     return serializeCookie(name, `${value}.${signature}`, options);
 }
-export function parseSignedCookie(value, secret) {
+/**
+ * Verifies a signed cookie value and returns the original value, or
+ * `undefined` when the signature does not match.
+ *
+ * Pass the cookie's `name`: the signature produced by
+ * `serializeSignedCookie` is bound to it, so a value lifted from another
+ * signed cookie (for example a user-chosen display name replayed as
+ * `session_user`) is rejected. Without `name` only a legacy, value-only
+ * signature (from `signCookieValue(value, secret)`) verifies, and
+ * name-bound signatures never do.
+ */
+export function parseSignedCookie(value, secret, name) {
     if (!value) {
         return undefined;
     }
@@ -243,15 +269,27 @@ export function parseSignedCookie(value, secret) {
     }
     const originalValue = value.slice(0, separator);
     const signature = value.slice(separator + 1);
-    const expected = signCookieValue(originalValue, secret);
-    if (!timingSafeEqual(signature, expected)) {
+    const expected = signCookieValue(name === undefined ? originalValue : bindCookieName(name, originalValue), secret);
+    if (!timingSafeEqualString(signature, expected)) {
         return undefined;
     }
     return originalValue;
 }
+/**
+ * The MAC input for a name-bound signature. A cookie name is an RFC 6265
+ * token and cannot contain `=`, so the encoding is unambiguous.
+ */
+function bindCookieName(name, value) {
+    validateCookieName(name);
+    return `${name}=${value}`;
+}
 /**
  * Signs a cookie value with HMAC-SHA256.
  *
+ * Synchronous by contract, so the MAC is computed with `node:crypto`: every
+ * `@zudojs/crypto` HMAC helper is asynchronous. Verification compares with
+ * `@zudojs/crypto`'s constant-time `timingSafeEqualString`.
+ *
  * @param value - The value to authenticate.
  * @param secret - The signing key.
  * @returns The base64url signature.
@@ -396,22 +434,4 @@ function normalizePriority(value) {
             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/httpCookies/httpCookies.defaults.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Secure cookie defaults.
+ *
+ * Both cookie serializers (`serializeCookie` in this module and the
+ * `serializeResponseCookie` the adapters use for `response.cookie()`) start
+ * from these defaults, so a cookie set "the obvious way" is `HttpOnly`,
+ * `Secure`, `SameSite=Lax` and `Path=/`, matching the defaults of
+ * `@zudojs/security`'s `serializeCookie` and the AGENTS.md secure-defaults
+ * rule. Every default can be overridden explicitly (`httpOnly: false`,
+ * `secure: false`, `sameSite: "none"`, `path: "/app"`); an option left
+ * `undefined` keeps the default.
+ *
+ * @module httpCookies/defaults
+ */
+/**
+ * The attributes every cookie gets unless the caller overrides them.
+ */
+export declare const DEFAULT_COOKIE_ATTRIBUTES: Readonly<{
+    readonly path: "/";
+    readonly httpOnly: true;
+    readonly secure: true;
+    readonly sameSite: "lax";
+}>;
+interface DefaultableCookieOptions<S extends string> {
+    readonly path?: string;
+    readonly httpOnly?: boolean;
+    readonly secure?: boolean;
+    readonly sameSite?: S;
+}
+/**
+ * Returns `options` with the secure defaults filled in for every attribute
+ * the caller left `undefined`.
+ *
+ * @param options - The caller's cookie options.
+ * @param sameSite - The default `SameSite` value in the option type's own
+ *   spelling (`"lax"` or `"Lax"`).
+ */
+export declare function withSecureCookieDefaults<S extends string, T extends DefaultableCookieOptions<S>>(options: T | undefined, sameSite: S): T;
+export {};
+//# sourceMappingURL=httpCookies.defaults.d.ts.map

package/dist/httpCookies/httpCookies.defaults.js

@@ -0,0 +1,42 @@
+/**
+ * Secure cookie defaults.
+ *
+ * Both cookie serializers (`serializeCookie` in this module and the
+ * `serializeResponseCookie` the adapters use for `response.cookie()`) start
+ * from these defaults, so a cookie set "the obvious way" is `HttpOnly`,
+ * `Secure`, `SameSite=Lax` and `Path=/`, matching the defaults of
+ * `@zudojs/security`'s `serializeCookie` and the AGENTS.md secure-defaults
+ * rule. Every default can be overridden explicitly (`httpOnly: false`,
+ * `secure: false`, `sameSite: "none"`, `path: "/app"`); an option left
+ * `undefined` keeps the default.
+ *
+ * @module httpCookies/defaults
+ */
+/**
+ * The attributes every cookie gets unless the caller overrides them.
+ */
+export const DEFAULT_COOKIE_ATTRIBUTES = Object.freeze({
+    path: "/",
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+});
+/**
+ * Returns `options` with the secure defaults filled in for every attribute
+ * the caller left `undefined`.
+ *
+ * @param options - The caller's cookie options.
+ * @param sameSite - The default `SameSite` value in the option type's own
+ *   spelling (`"lax"` or `"Lax"`).
+ */
+export function withSecureCookieDefaults(options, sameSite) {
+    const source = (options ?? {});
+    return {
+        ...source,
+        path: source.path ?? DEFAULT_COOKIE_ATTRIBUTES.path,
+        httpOnly: source.httpOnly ?? DEFAULT_COOKIE_ATTRIBUTES.httpOnly,
+        secure: source.secure ?? DEFAULT_COOKIE_ATTRIBUTES.secure,
+        sameSite: source.sameSite ?? sameSite,
+    };
+}
+//# sourceMappingURL=httpCookies.defaults.js.map

package/dist/httpCookies/index.d.ts

@@ -4,4 +4,5 @@
  * HTTP httpCookies module.
  */
 export * from "./http.cookies.js";
+export * from "./httpCookies.defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpCookies/index.js

@@ -4,4 +4,5 @@
  * HTTP httpCookies module.
  */
 export * from "./http.cookies.js";
+export * from "./httpCookies.defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/httpMiddleware/builtin/conditional/httpMiddleware.conditional.d.ts

@@ -7,7 +7,28 @@ import type { HttpMiddleware, HttpMiddlewareContext } from "../../httpMiddleware
 import type { HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
 export declare function createAsyncMiddleware(factory: (context: HttpMiddlewareContext) => Promise<HttpMiddleware>): HttpMiddleware;
 export declare function createConditionalMiddleware(predicate: (context: HttpMiddlewareContext) => boolean | Promise<boolean>, middleware: HttpMiddleware): HttpMiddleware;
-export declare function createPathMiddleware(path: string, middleware: HttpMiddleware): HttpMiddleware;
+/**
+ * Options for {@link createPathMiddleware}.
+ */
+export interface PathMiddlewareOptions {
+    /**
+     * Match the path case-sensitively. Defaults to `false`, the router's
+     * default, so a guard scoped to `/admin` also covers `/Admin`, which the
+     * router would dispatch to the same route.
+     */
+    readonly caseSensitive?: boolean;
+}
+/**
+ * Runs `middleware` only for requests addressed to `path`.
+ *
+ * The request path is normalised exactly as the router normalises it before
+ * matching: it is read with the canonical request-target parser, repeated
+ * slashes are collapsed, a trailing slash is ignored and (by default) case is
+ * ignored. An exact, case-sensitive comparison let `/Admin`, `/admin/` and
+ * `/admin//` skip a guard on `/admin` while the router still served the
+ * protected route.
+ */
+export declare function createPathMiddleware(path: string, middleware: HttpMiddleware, options?: PathMiddlewareOptions): HttpMiddleware;
 export declare function createMethodMiddleware(method: string, middleware: HttpMiddleware): HttpMiddleware;
 export declare function createResponseMiddleware(response: Response | ResponseContext): HttpMiddleware;
 export declare function createShortCircuitMiddleware(predicate: (context: HttpMiddlewareContext) => boolean | Promise<boolean>, response: Response | ResponseContext): HttpMiddleware;

package/dist/httpMiddleware/builtin/conditional/httpMiddleware.conditional.js

@@ -4,6 +4,7 @@
  * @module httpMiddleware/builtin/conditional
  */
 import { getRequestMethod, getRequestUrl, extractPathname, } from "../helpers/index.js";
+import { normalizePath } from "../../../httpRouter/core/util/httpRoute.util.js";
 import { isWebResponse, bufferWebResponse, } from "../../../httpResponse/httpResponse.fromWeb.js";
 export function createAsyncMiddleware(factory) {
     return async (context, next) => {
@@ -19,12 +20,26 @@ export function createConditionalMiddleware(predicate, middleware) {
         return next();
     };
 }
-export function createPathMiddleware(path, middleware) {
-    const targetPath = extractPathname(path);
+/**
+ * Runs `middleware` only for requests addressed to `path`.
+ *
+ * The request path is normalised exactly as the router normalises it before
+ * matching: it is read with the canonical request-target parser, repeated
+ * slashes are collapsed, a trailing slash is ignored and (by default) case is
+ * ignored. An exact, case-sensitive comparison let `/Admin`, `/admin/` and
+ * `/admin//` skip a guard on `/admin` while the router still served the
+ * protected route.
+ */
+export function createPathMiddleware(path, middleware, options = {}) {
+    const caseSensitive = options.caseSensitive === true;
+    const canonical = (value) => {
+        const normalized = normalizePath(value);
+        return caseSensitive ? normalized : normalized.toLowerCase();
+    };
+    const targetPath = canonical(extractPathname(path));
     return createConditionalMiddleware((context) => {
         const url = getRequestUrl(context.request);
-        const pathname = extractPathname(url);
-        return pathname === targetPath;
+        return canonical(extractPathname(url)) === targetPath;
     }, middleware);
 }
 export function createMethodMiddleware(method, middleware) {

package/dist/httpMiddleware/builtin/conditional/index.d.ts

@@ -4,4 +4,5 @@
  * @module httpMiddleware/builtin/conditional
  */
 export { createAsyncMiddleware, createConditionalMiddleware, createPathMiddleware, createMethodMiddleware, createResponseMiddleware, createShortCircuitMiddleware, } from "./httpMiddleware.conditional.js";
+export type { PathMiddlewareOptions } from "./httpMiddleware.conditional.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/cors/httpMiddleware.cors.d.ts

@@ -24,5 +24,13 @@ export interface CorsMiddlewareOptions {
      */
     readonly optionsSuccessStatus?: number;
 }
+/**
+ * Creates the CORS middleware.
+ *
+ * @throws {ConfigurationError} At construction when a wildcard origin
+ *   (including the default `"*"`) is combined with `credentials: true`.
+ *   This used to be accepted and then fail every cross-origin request with a
+ *   500, which tests that send no `Origin` never noticed.
+ */
 export declare function createCorsMiddleware(options?: CorsMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.cors.d.ts.map

package/dist/httpMiddleware/builtin/cors/httpMiddleware.cors.js

@@ -3,6 +3,7 @@
  *
  * @module httpMiddleware/builtin/cors
  */
+import { isOriginAllowed } from "@zudojs/security";
 import { applyHeadersToResponse } from "../helpers/index.js";
 function getRequestHeader(context, name) {
     const headers = context.request.headers;
@@ -13,30 +14,23 @@ function getRequestMethod(context) {
     return (context.request.method ?? "GET").toUpperCase();
 }
 /**
- * Decides whether an origin is allowed.
- *
- * The previous implementation ignored the request origin entirely and wrote
- * `Access-Control-Allow-Origin: *` on every response, so the documented
- * "reflect the origin" pattern allowed every origin on the internet.
+ * The `@zudojs/security` CORS configuration for this middleware's origin
+ * policy. `allowOrigin` defaults to `"*"`; a predicate is bound to the
+ * request context because `@zudojs/security` predicates take the origin only.
  */
-function resolveAllowedOrigin(origin, context, options) {
+function toSecurityCorsConfig(options, context) {
     const configured = options.allowOrigin ?? "*";
-    if (typeof configured === "function") {
-        return configured(origin, context) ? origin : undefined;
-    }
-    const list = typeof configured === "string" ? [configured] : configured;
-    if (list.includes("*")) {
-        if (options.credentials) {
-            /*
-             * A wildcard origin with credentials is forbidden by the spec, and
-             * reflecting the request origin instead would authorise every origin
-             * to read authenticated responses.
-             */
-            throw new TypeError("CORS: a wildcard allowOrigin cannot be combined with credentials.");
-        }
-        return "*";
-    }
-    return list.includes(origin) ? origin : undefined;
+    const origin = typeof configured === "function"
+        ? (value) => context !== undefined && configured(value, context)
+        : configured;
+    return { origin, credentials: options.credentials === true };
+}
+/**
+ * Decides whether an origin is allowed, delegating to `@zudojs/security`'s
+ * `isOriginAllowed` so origin matching has one implementation.
+ */
+function resolveAllowedOrigin(origin, context, options) {
+    return isOriginAllowed(origin, toSecurityCorsConfig(options, context));
 }
 function appendVary(headers, value) {
     const existing = headers.get("vary");
@@ -51,7 +45,16 @@ function appendVary(headers, value) {
         headers.set("vary", `${existing}, ${value}`);
     }
 }
+/**
+ * Creates the CORS middleware.
+ *
+ * @throws {ConfigurationError} At construction when a wildcard origin
+ *   (including the default `"*"`) is combined with `credentials: true`.
+ *   This used to be accepted and then fail every cross-origin request with a
+ *   500, which tests that send no `Origin` never noticed.
+ */
 export function createCorsMiddleware(options = {}) {
+    isOriginAllowed(undefined, toSecurityCorsConfig(options));
     return async (context, next) => {
         const origin = getRequestHeader(context, "origin");
         /*

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.accessor.js

@@ -3,6 +3,7 @@
  *
  * @module httpMiddleware/builtin/helpers/accessors
  */
+import { getCanonicalPath } from "../../../httpRequest/target/httpRequest.target.js";
 export function getRequestMethod(request) {
     const value = request.method;
     return value ?? "GET";
@@ -32,12 +33,7 @@ export function getContextSignal(request) {
     return value;
 }
 export function extractPathname(value) {
-    try {
-        return new URL(value, "http://zudojs.local").pathname;
-    }
-    catch {
-        return value.split("?")[0] ?? value;
-    }
+    return getCanonicalPath(value);
 }
 export function performanceNow() {
     if (typeof performance !== "undefined" &&

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.media.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared helpers for the media (image / video) compression middleware.
+ *
+ * Both middleware used to read the stale `context.response` instead of the
+ * response `next()` returned, so a handler that returned a fresh response
+ * context (the documented style) was never compressed. These helpers read
+ * everything from the returned response.
+ *
+ * @module httpMiddleware/builtin/helpers/media
+ */
+import type { HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
+/**
+ * Reports a compression failure. The uncompressed response is still served.
+ */
+export type MediaCompressionErrorHandler = (error: unknown, response: ResponseContext) => void;
+/**
+ * The media type of a response (`image/png; q=1` → `image/png`), lowercased.
+ */
+export declare function getResponseMediaType(response: ResponseContext): string | undefined;
+/**
+ * The response body as a Buffer, or `undefined` for a body that is not held
+ * in memory (streams, JSON values).
+ */
+export declare function getResponseBytes(response: ResponseContext): Buffer | undefined;
+/**
+ * Loads an optional peer module's callable default export.
+ */
+export declare function loadOptionalModule<T>(specifier: string, install: string): Promise<T>;
+/**
+ * Replaces the body and content type of a compressed response.
+ */
+export declare function applyCompressedBody(response: ResponseContext, body: Buffer, contentType: string): ResponseContext;
+//# sourceMappingURL=httpMiddleware.media.d.ts.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.media.js

@@ -0,0 +1,59 @@
+/**
+ * Shared helpers for the media (image / video) compression middleware.
+ *
+ * Both middleware used to read the stale `context.response` instead of the
+ * response `next()` returned, so a handler that returned a fresh response
+ * context (the documented style) was never compressed. These helpers read
+ * everything from the returned response.
+ *
+ * @module httpMiddleware/builtin/helpers/media
+ */
+/**
+ * The media type of a response (`image/png; q=1` → `image/png`), lowercased.
+ */
+export function getResponseMediaType(response) {
+    const raw = response.headers["content-type"];
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const mediaType = raw.split(";", 1)[0]?.trim().toLowerCase();
+    return mediaType ? mediaType : undefined;
+}
+/**
+ * The response body as a Buffer, or `undefined` for a body that is not held
+ * in memory (streams, JSON values).
+ */
+export function getResponseBytes(response) {
+    const body = response.body;
+    if (Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof Uint8Array) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    return undefined;
+}
+/**
+ * Loads an optional peer module's callable default export.
+ */
+export async function loadOptionalModule(specifier, install) {
+    try {
+        const mod = (await import(specifier));
+        return (mod.default ?? mod);
+    }
+    catch {
+        throw new Error(`${specifier} is not installed. Run: ${install}`);
+    }
+}
+/**
+ * Replaces the body and content type of a compressed response.
+ */
+export function applyCompressedBody(response, body, contentType) {
+    response.setHeader("content-type", contentType);
+    if (response.headers["cache-control"] === undefined) {
+        response.setHeader("cache-control", "public, max-age=86400");
+    }
+    response.removeHeader("content-length");
+    return response.setBody(body);
+}
+//# sourceMappingURL=httpMiddleware.media.js.map

package/dist/httpMiddleware/builtin/helpers/index.d.ts

@@ -6,4 +6,5 @@
 export * from "./httpMiddleware.contextHelper.js";
 export * from "./httpMiddleware.accessor.js";
 export * from "./httpMiddleware.response.js";
+export * from "./httpMiddleware.media.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/helpers/index.js

@@ -6,4 +6,5 @@
 export * from "./httpMiddleware.contextHelper.js";
 export * from "./httpMiddleware.accessor.js";
 export * from "./httpMiddleware.response.js";
+export * from "./httpMiddleware.media.js";
 //# sourceMappingURL=index.js.map

package/dist/httpMiddleware/builtin/image/httpMiddleware.image.d.ts

@@ -6,6 +6,7 @@
  * Requires: npm install sharp
  */
 import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+import { type MediaCompressionErrorHandler } from "../helpers/index.js";
 export interface ImageCompressionOptions {
     readonly quality?: number;
     readonly format?: "jpeg" | "png" | "webp" | "avif";
@@ -17,10 +18,22 @@ export interface ImageCompressionMiddlewareOptions {
     readonly enabled?: boolean;
     readonly defaultQuality?: number;
     readonly defaultFormat?: "jpeg" | "png" | "webp" | "avif";
+    /** Upper bound on the output width; applied to every image. */
     readonly maxWidth?: number;
+    /** Upper bound on the output height; applied to every image. */
     readonly maxHeight?: number;
     readonly contentTypeMap?: Record<string, ImageCompressionOptions>;
+    /**
+     * Called when compression fails. The original response is still served.
+     * Defaults to a no-op.
+     */
+    readonly onError?: MediaCompressionErrorHandler;
 }
 export declare function compressImage(buffer: Buffer, options?: ImageCompressionOptions): Promise<Buffer>;
+/**
+ * Compresses `image/*` responses. Status, headers and body are read from the
+ * response returned by `next()`, and `maxWidth` / `maxHeight` cap every
+ * output.
+ */
 export declare function createImageCompressionMiddleware(options?: ImageCompressionMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.image.d.ts.map