fix(handlers): clamp output dimensions with maxOutputDimension option

Requested resize/width/height dimensions and extend edges are now capped
to a configurable maximum output dimension (default 8192) to prevent
memory exhaustion via requests like /enlarge,s_20000x20000/img.jpg.
Set maxOutputDimension: false to disable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: pi0

README.md

@@ -193,6 +193,9 @@ You can universally customize IPX configuration using `IPX_*` environment variab
 
 - `IPX_ALIAS`
   - Default: `{}`
+- `IPX_MAX_OUTPUT_DIMENSION`
+  - Default: `8192`
+  - Maximum width and height (in pixels) of the output image (option: `maxOutputDimension`). Requested `width`, `height` and `resize` dimensions are clamped to it, preserving the requested aspect ratio, and `extend` edges are clamped so the extended canvas stays within it. This bounds how much memory a single request can allocate: sharp only limits the _input_ size, so without it `/enlarge,s_20000x20000/image.jpg` (or `/extend_10000_10000_10000_10000/image.jpg`) allocates gigabytes from a small source image. Set to `false` to disable, which is only safe when modifiers come from a trusted source.
 
 ### Filesystem Source Options
 

src/handlers/handlers.ts

@@ -7,6 +7,8 @@ import {
   VRequired,
   VSize,
   clampDimensionsPreservingAspectRatio,
+  clampExtendEdges,
+  clampToMaxDimension,
 } from "./utils.ts";
 
 // Ranges below mirror the ones sharp enforces, so that invalid modifier
@@ -111,10 +113,19 @@ export const kernel: Handler = {
   },
 };
 
+// `withoutEnlargement` is disabled by the `enlarge` modifier, so the requested
+// dimensions are additionally capped to `maxOutputDimension` (see
+// `clampToMaxDimension`) to bound how much memory the output can take.
+
 export const width: Handler = {
   args: [VNumber("width", { min: 1, integer: true })],
   apply: (context, pipe, width) => {
-    return pipe.resize(width, undefined, {
+    const clamped = clampToMaxDimension(
+      context.maxOutputDimension,
+      { width },
+      context.meta,
+    );
+    return pipe.resize(clamped.width, undefined, {
       withoutEnlargement: !context.enlarge,
     });
   },
@@ -123,7 +134,12 @@ export const width: Handler = {
 export const height: Handler = {
   args: [VNumber("height", { min: 1, integer: true })],
   apply: (context, pipe, height) => {
-    return pipe.resize(undefined, height, {
+    const clamped = clampToMaxDimension(
+      context.maxOutputDimension,
+      { height },
+      context.meta,
+    );
+    return pipe.resize(undefined, clamped.height, {
       withoutEnlargement: !context.enlarge,
     });
   },
@@ -145,7 +161,12 @@ export const resize: Handler = {
       width = clamped.width;
       height = clamped.height;
     }
-    return pipe.resize(width, height, {
+    // Applies with `enlarge` too, where nothing else bounds the output size.
+    const capped = clampToMaxDimension(context.maxOutputDimension, {
+      width,
+      height,
+    });
+    return pipe.resize(capped.width, capped.height, {
       fit: context.fit,
       position: context.position,
       background: context.background,
@@ -177,11 +198,18 @@ export const extend: Handler = {
   // `background` is set by the `background` / `b` modifier and only used when
   // extending with `background` (the sharp default).
   apply: (context, pipe, top, right, bottom, left, extendWith) => {
+    // Edges grow the canvas without any input-size relation, so they are capped
+    // to keep the extended canvas within `maxOutputDimension`.
+    const edges = clampExtendEdges(
+      context.maxOutputDimension,
+      { top, right, bottom, left },
+      context.meta,
+    );
     return pipe.extend({
-      top,
-      left,
-      bottom,
-      right,
+      top: edges.top,
+      left: edges.left,
+      bottom: edges.bottom,
+      right: edges.right,
       background: context.background,
       extendWith,
     });

src/handlers/utils.ts

@@ -252,6 +252,106 @@ export function applyHandler(
   }
 }
 
+/**
+ * Clamps requested output dimensions to `max`, preserving the requested aspect
+ * ratio.
+ *
+ * Sharp's `limitInputPixels` only bounds the *input*, so without this cap a
+ * request such as `/enlarge,s_20000x20000/img.jpg` makes sharp allocate a
+ * ~1.6GB output buffer from an arbitrarily small source image.
+ *
+ * A side that was not requested stays omitted (sharp then derives it from the
+ * source aspect ratio), but `source` is used to make sure that derived side
+ * cannot exceed the limit either.
+ *
+ * @param max The limit, or `false`/`undefined` to leave the dimensions as-is.
+ * @param desired The requested dimensions.
+ * @param source The source dimensions, used to derive an omitted side.
+ */
+export function clampToMaxDimension(
+  max: number | false | undefined,
+  desired: { width?: number; height?: number },
+  source?: { width?: number; height?: number },
+): { width?: number; height?: number } {
+  const { width, height } = desired;
+  if (!max || (width === undefined && height === undefined)) {
+    return desired;
+  }
+
+  // Sharp preserves the source aspect ratio when only one side is requested.
+  const ratio =
+    source?.width && source?.height ? source.width / source.height : undefined;
+  const effectiveWidth =
+    width ?? (ratio && height ? height * ratio : undefined);
+  const effectiveHeight =
+    height ?? (ratio && width ? width / ratio : undefined);
+
+  const scale = Math.min(
+    effectiveWidth ? max / effectiveWidth : 1,
+    effectiveHeight ? max / effectiveHeight : 1,
+  );
+  if (scale >= 1) {
+    return desired;
+  }
+
+  // Both sides are scaled by the same factor, so the requested aspect ratio is
+  // preserved. `Math.min` guards against floating point rounding above `max`.
+  const clamp = (value?: number) =>
+    value === undefined
+      ? undefined
+      : Math.max(1, Math.min(max, Math.round(value * scale)));
+  return { width: clamp(width), height: clamp(height) };
+}
+
+/**
+ * Clamps `extend` edges so that the extended canvas cannot exceed `max` in
+ * either dimension.
+ *
+ * Both edges of an axis are scaled down by the same factor rather than the
+ * request being rejected, for consistency with how resize dimensions are
+ * clamped. Omitted edges stay omitted so sharp applies its own default (`0`).
+ *
+ * @param max The limit, or `false`/`undefined` to leave the edges as-is.
+ * @param edges The requested per-side extend values.
+ * @param source The dimensions of the image being extended.
+ */
+export function clampExtendEdges(
+  max: number | false | undefined,
+  edges: { top?: number; right?: number; bottom?: number; left?: number },
+  source?: { width?: number; height?: number },
+) {
+  if (!max) {
+    return edges;
+  }
+  const [top, bottom] = clampEdges(
+    max - (source?.height || 0),
+    edges.top,
+    edges.bottom,
+  );
+  const [left, right] = clampEdges(
+    max - (source?.width || 0),
+    edges.left,
+    edges.right,
+  );
+  return { top, right, bottom, left };
+}
+
+/** Clamps the two edges of one axis to the space left within the limit. */
+function clampEdges(
+  available: number,
+  a: number | undefined,
+  b: number | undefined,
+): [number | undefined, number | undefined] {
+  const total = (a || 0) + (b || 0);
+  if (total === 0 || total <= available) {
+    return [a, b];
+  }
+  const scale = Math.max(0, available) / total;
+  const clamp = (value?: number) =>
+    value === undefined ? undefined : Math.floor(value * scale);
+  return [clamp(a), clamp(b)];
+}
+
 export function clampDimensionsPreservingAspectRatio(
   sourceDimensions: ImageMeta,
   desiredDimensions: { width: number; height: number },

src/ipx.ts

@@ -128,6 +128,27 @@ export type IPXOptions = {
    */
   maxAge?: number;
 
+  /**
+   * Maximum width and height (in pixels) of the output image.
+   *
+   * Modifiers are user input and sharp's `limitInputPixels` only bounds the
+   * *input*, so without this limit a request such as
+   * `/enlarge,s_20000x20000/img.jpg` or `/extend_10000_10000_10000_10000/img.jpg`
+   * makes sharp allocate a multi-gigabyte output buffer from a tiny source
+   * image, which is an easy way to exhaust the server memory.
+   *
+   * Requested `width`, `height`, `resize` dimensions are clamped to this value
+   * (preserving the requested aspect ratio) and `extend` edges are clamped so
+   * that the extended canvas stays within it.
+   *
+   * Set to `false` to disable the limit (only safe when modifiers come from a
+   * trusted source).
+   *
+   * @default 8192
+   * @optional
+   */
+  maxOutputDimension?: number | false;
+
   /**
    * A mapping of URL aliases to their corresponding URLs, used to simplify resource identifiers.
    * @optional
@@ -177,6 +198,10 @@ export type IPXOptions = {
   };
 };
 
+// A common CDN limit. `8192 x 8192 x 4B` is ~268MB of uncompressed pixels,
+// which bounds what a single request can allocate.
+const DEFAULT_MAX_OUTPUT_DIMENSION = 8192;
+
 // https://sharp.pixelplumbing.com/#formats
 // (gif and svg are not supported as output)
 const SUPPORTED_FORMATS = new Set([
@@ -203,6 +228,10 @@ export function createIPX(userOptions: IPXOptions): IPX {
       userOptions.alias || getEnv<Record<string, string>>("IPX_ALIAS") || {},
     maxAge:
       userOptions.maxAge ?? getEnv<number>("IPX_MAX_AGE") ?? 60 /* 1 minute */,
+    maxOutputDimension:
+      userOptions.maxOutputDimension ??
+      getEnv<number | false>("IPX_MAX_OUTPUT_DIMENSION") ??
+      DEFAULT_MAX_OUTPUT_DIMENSION,
     sharpOptions: {
       jpegProgressive: true,
       ...userOptions.sharpOptions,
@@ -400,7 +429,10 @@ export function createIPX(userOptions: IPXOptions): IPX {
         });
 
       // Apply handlers
-      const handlerContext: any = { meta: imageMeta };
+      const handlerContext: any = {
+        meta: imageMeta,
+        maxOutputDimension: options.maxOutputDimension,
+      };
       for (const h of handlers) {
         sharp =
           applyHandler(handlerContext, sharp, h.handler, h.args.toString()) ||

src/types.ts

@@ -40,6 +40,13 @@ export interface HandlerContext {
    */
   kernel?: keyof KernelEnum;
 
+  /**
+   * The maximum width and height of the output image, or `false` when
+   * unlimited. Set from the `maxOutputDimension` IPX option.
+   * @optional
+   */
+  maxOutputDimension?: number | false;
+
   /**
    * Metadata about the image being processed.
    */

test/handlers/handlers.test.ts

@@ -404,6 +404,103 @@ describe("handlers", () => {
   });
 });
 
+// Modifiers are user input and sharp only limits the *input* size, so handlers
+// growing the output are capped by `context.maxOutputDimension`.
+describe("maxOutputDimension", () => {
+  const context = (maxOutputDimension: number | false | undefined) =>
+    ({
+      // `enlarge` disables every other bound on the output size
+      enlarge: true,
+      maxOutputDimension,
+      meta: { width: 400, height: 200 },
+    }) as any;
+
+  it("resize is clamped, preserving the requested aspect ratio", () => {
+    const pipe = { resize: vi.fn() };
+
+    applyHandler(context(1000), pipe as any, resize, "8000x4000");
+
+    expect(pipe.resize).toHaveBeenCalledWith(1000, 500, expect.anything());
+  });
+
+  it("width is clamped", () => {
+    const pipe = { resize: vi.fn() };
+
+    applyHandler(context(1000), pipe as any, width, "8000");
+
+    expect(pipe.resize).toHaveBeenCalledWith(1000, undefined, {
+      withoutEnlargement: false,
+    });
+  });
+
+  it("height is clamped", () => {
+    const pipe = { resize: vi.fn() };
+
+    applyHandler(context(1000), pipe as any, height, "8000");
+
+    // 500, not 1000: the source is twice as wide as it is tall, so a height of
+    // 1000 would give a derived width of 2000.
+    expect(pipe.resize).toHaveBeenCalledWith(undefined, 500, {
+      withoutEnlargement: false,
+    });
+  });
+
+  // Sharp derives the omitted side from the source aspect ratio, so a single
+  // dimension within the limit can still blow up the other one.
+  it("width is clamped for the derived height", () => {
+    const pipe = { resize: vi.fn() };
+    const tall = { ...context(1000), meta: { width: 200, height: 4000 } };
+
+    applyHandler(tall, pipe as any, width, "1000");
+
+    expect(pipe.resize).toHaveBeenCalledWith(50, undefined, {
+      withoutEnlargement: false,
+    });
+  });
+
+  it("extend edges are clamped to fit the canvas within the limit", () => {
+    const pipe = { extend: vi.fn() };
+
+    applyHandler(context(1000), pipe as any, extend, "5000_5000_5000_5000");
+
+    expect(pipe.extend).toHaveBeenCalledWith({
+      top: 400,
+      bottom: 400,
+      left: 300,
+      right: 300,
+      background: undefined,
+      extendWith: undefined,
+    });
+  });
+
+  it.each<false | undefined>([false, undefined])(
+    "is disabled with `%s`",
+    (max) => {
+      const pipe = { resize: vi.fn(), extend: vi.fn() };
+
+      applyHandler(context(max), pipe as any, resize, "8000x4000");
+      applyHandler(context(max), pipe as any, extend, "5000");
+
+      expect(pipe.resize).toHaveBeenCalledWith(8000, 4000, expect.anything());
+      expect(pipe.extend).toHaveBeenCalledWith(
+        expect.objectContaining({ top: 5000 }),
+      );
+    },
+  );
+
+  it("does not affect requests within the limit", () => {
+    const pipe = { resize: vi.fn(), extend: vi.fn() };
+
+    applyHandler(context(1000), pipe as any, resize, "300x150");
+    applyHandler(context(1000), pipe as any, extend, "10_20_30_40");
+
+    expect(pipe.resize).toHaveBeenCalledWith(300, 150, expect.anything());
+    expect(pipe.extend).toHaveBeenCalledWith(
+      expect.objectContaining({ top: 10, right: 20, bottom: 30, left: 40 }),
+    );
+  });
+});
+
 // Every modifier argument is validated up front so that bad input is a 400
 // instead of an unhandled sharp error (a 500) further down the pipeline.
 describe("handler args", () => {