ipx 4.0.0-alpha.2 → 4.0.0-beta.1

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import { createIPX, ipxFSStorage, ipxHttpStorage, serveIPX } from "./_chunks/node-fs.mjs";
 import { parseArgs } from "node:util";
 var name = "ipx";
-var version = "4.0.0-alpha.1";
+var version = "4.0.0-beta.0";
 const { positionals, values } = parseArgs({
 	allowPositionals: true,
 	options: {

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { ImageMeta } from "./_chunks/libs/image-meta.mjs";
+import { HTTPError } from "./_chunks/libs/h3.mjs";
 import { NodeHttpHandler, Server, ServerOptions } from "srvx";
 import { Color, KernelEnum, Sharp, SharpOptions } from "sharp";
 import { Config } from "svgo";
@@ -34,6 +35,30 @@ interface HandlerContext {
    * @optional
    */
   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;
+  /**
+   * Dimensions the image is expected to have once the resize modifiers
+   * (`resize`, `width`, `height`) have been applied, recorded by those
+   * handlers after their own clamping.
+   *
+   * libvips resizes before it extends, whatever order the modifiers appear in
+   * the URL, so `extend` budgets its edges against these rather than against
+   * {@link meta}: budgeting against the source lets the two clamps stack and
+   * the canvas end up at twice `maxOutputDimension` on each axis.
+   *
+   * Undefined when no resize modifier was applied (or when nothing could be
+   * projected from it), in which case `extend` falls back to {@link meta}.
+   * @optional
+   */
+  outputDimensions?: {
+    width?: number;
+    height?: number;
+  };
   /**
    * Metadata about the image being processed.
    */
@@ -106,6 +131,7 @@ type IPXSourceMeta = {
    */
   maxAge?: number;
 };
+type FlagModifier = true | "true" | "";
 type FormatModifier = "jpeg" | "jpg" | "png" | "webp" | "avif" | "gif" | "heif" | "tiff" | "auto" | (string & {});
 interface IPXModifiers {
   format: FormatModifier;
@@ -119,28 +145,39 @@ interface IPXModifiers {
   b: string;
   position: string;
   pos: string;
-  enlarge: true | "true";
+  enlarge: FlagModifier;
   kernel: "nearest" | "cubic" | "mitchell" | "lanczos2" | "lanczos3" | (string & {});
   trim: number | string;
   extend: string;
   extract: string;
   crop: string;
   rotate: number | string;
-  flip: true | "true";
-  flop: true | "true";
+  autoorient: FlagModifier;
+  flip: FlagModifier;
+  flop: FlagModifier;
   sharpen: number | string;
   median: number | string;
   blur: number | string;
-  flatten: true | "true";
+  dilate: number | string;
+  erode: number | string;
+  clahe: number | string;
+  flatten: FlagModifier;
+  unflatten: FlagModifier;
   gamma: string;
-  negate: true | "true";
-  normalize: true | "true";
+  negate: FlagModifier | string;
+  normalize: FlagModifier | string;
   threshold: number | string;
+  linear: string;
   modulate: string;
+  brightness: number | string;
+  saturation: number | string;
+  hue: number | string;
+  lightness: number | string;
+  opacity: number | string;
   tint: number | string;
-  grayscale: true | "true";
-  animated: true | "true";
-  a: true | "true";
+  grayscale: FlagModifier;
+  animated: FlagModifier;
+  a: FlagModifier;
   width: string | number;
   w: string | number;
   height: string | number;
@@ -177,6 +214,26 @@ type IPXOptions = {
    * @optional
    */
   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
@@ -197,10 +254,28 @@ type IPXOptions = {
    */
   httpStorage?: IPXStorage;
   /**
-   * Configuration for the SVGO library used when processing SVG images.
+   * Options for SVG images, which are processed by SVGO instead of Sharp.
    * @optional
    */
-  svgo?: false | Config;
+  svg?: {
+    /**
+     * Configuration for the SVGO library used to optimize SVG images.
+     *
+     * SVGO's `preset-default` is applied unless custom `plugins` are configured.
+     * Set to `false` to disable optimization. Sanitization is applied either way.
+     * @optional
+     */
+    optimize?: false | Config;
+    /**
+     * Disable SVG sanitization.
+     *
+     * Sanitized SVG images cannot execute scripts. Only disable this if all sources
+     * are fully trusted, as it allows serving SVG images with XSS payloads.
+     * @default false
+     * @optional
+     */
+    unsafeSkipSanitize?: boolean;
+  };
 };
 /**
  * Creates an IPX image processing instance with the specified options.
@@ -210,12 +285,62 @@ type IPXOptions = {
  */
 declare function createIPX(userOptions: IPXOptions): IPX;
 type FetchHandler = (request: Request | string | URL) => Response | Promise<Response>;
-declare function createIPXFetchHandler(ipx: IPX): FetchHandler;
-declare function createIPXNodeHandler(ipx: IPX): NodeHttpHandler;
-declare function serveIPX(ipx: IPX, opts?: Omit<ServerOptions, "fetch">): Server;
+interface IPXHandlerOptions {
+  /**
+   * Custom URL parser to extract the resource id and modifiers from the request URL.
+   * Can be async.
+   *
+   * Receives the raw (absolute, still percent-encoded) request URL, so parsers can
+   * decode it themselves without going through h3's normalization.
+   *
+   * Defaults to {@link parseIPXURL} which handles URLs in the form `/<modifiers>/<id>`.
+   *
+   * Returned values are escaped (control characters) by the handler, so custom parsers
+   * do not need to escape them. This is not an access check: exactly as with the default
+   * parser, what the resulting `id` is allowed to resolve to is enforced by the storage
+   * layer. Throw an `HTTPError` to reject a request with a specific status code.
+   *
+   * @optional
+   */
+  parseURL?: IPXURLParser;
+}
+declare function createIPXFetchHandler(ipx: IPX, opts?: IPXHandlerOptions): FetchHandler;
+declare function createIPXNodeHandler(ipx: IPX, opts?: IPXHandlerOptions): NodeHttpHandler;
+declare function serveIPX(ipx: IPX, opts?: Omit<ServerOptions, "fetch"> & IPXHandlerOptions): Server;
+interface IPXParsedURL {
+  /**
+   * The identifier of the source image (path or URL, depending on the storage).
+   */
+  id: string;
+  /**
+   * Modifiers to apply, keyed by modifier name. See {@link IPXModifiers}.
+   *
+   * Values are coerced to strings. Use `""` (or `undefined`) for valueless
+   * modifiers such as `grayscale`.
+   */
+  modifiers: Record<string, string | number | boolean | undefined>;
+}
+type IPXURLParser = (url: string) => IPXParsedURL | Promise<IPXParsedURL>;
+/**
+ * Default IPX URL parser, handling URLs in the form `/<modifiers>/<id>`.
+ *
+ * Use `_` as the modifiers segment to apply none (`/_/image.png`).
+ *
+ * @param {string} url - The raw (absolute) request URL.
+ * @returns {IPXParsedURL} The parsed resource id and modifiers. See {@link IPXParsedURL}.
+ * @throws {HTTPError} If the modifiers segment is missing.
+ */
+declare function parseIPXURL(url: string): IPXParsedURL;
 type HTTPStorageOptions = {
   /**
    * Custom options for fetch operations, such as headers or method overrides.
+   *
+   * Redirects are followed manually (one hop at a time) so that each redirect target
+   * can be re-validated against the {@link HTTPStorageOptions.domains} allowlist
+   * (and {@link HTTPStorageOptions.blockPrivateIPs} when enabled).
+   * Explicitly setting `redirect` here opts out of this protection: the value is passed
+   * to `fetch` as-is and redirect targets are **not** validated (a redirect to an
+   * internal address is then possible: SSRF).
    * @optional
    */
   fetchOptions?: RequestInit;
@@ -226,6 +351,11 @@ type HTTPStorageOptions = {
   maxAge?: number;
   /**
    * Whitelist of domains from which resource fetching is allowed. Can be a single string or an array of strings.
+   *
+   * Only `http:` and `https:` URLs are allowed. Redirects are followed only within this
+   * allowlist (up to 3 hops): a redirect to a host that is not listed is rejected with
+   * `403 IPX_FORBIDDEN_HOST`, so an allowlisted host cannot bounce IPX to an internal
+   * address. Hosts that redirect to a CDN must have the CDN hostname listed here too.
    * @optional
    */
   domains?: string | string[];
@@ -239,6 +369,22 @@ type HTTPStorageOptions = {
    * @optional
    */
   ignoreCacheControl?: boolean;
+  /**
+   * If set to true, reject URLs whose host is (or resolves to) a non-public IP address
+   * with `403 IPX_FORBIDDEN_IP`. Checked for the requested URL and for every redirect hop.
+   *
+   * This is **defense in depth**, not the primary access control: the
+   * {@link HTTPStorageOptions.domains} allowlist is. It only helps when an allowlisted
+   * (or, with `allowAllDomains`, arbitrary) hostname points at loopback, link-local
+   * (`169.254.169.254`, the cloud metadata service), RFC1918, CGNAT, unique-local or
+   * otherwise non-public space.
+   *
+   * Disabled by default because many legitimate deployments fetch from in-cluster origins
+   * (internal object storage, sidecars, `localhost` during development), which this blocks.
+   * @optional
+   * @default false
+   */
+  blockPrivateIPs?: boolean;
 };
 /**
  * Creates an HTTP storage handler for IPX that fetches image data from external URLs.
@@ -256,10 +402,32 @@ type NodeFSSOptions = {
    */
   dir?: string | string[];
   /**
-   * The directory or list of directories from which to serve files. If not specified, the current directory is used by default.
+   * `max-age`, in seconds, reported for files served from this storage. Used for the
+   * `cache-control` header. Falls back to the IPX-wide `maxAge` (default 60) when unset.
+   *
+   * `0` is meaningful and is passed through as-is — it disables caching rather than
+   * falling back to the default.
    * @optional
    */
   maxAge?: number;
+  /**
+   * If set to true, a symlink inside {@link NodeFSSOptions.dir} may resolve to a file outside
+   * of it. By default such files are rejected with `403 IPX_FORBIDDEN_SYMLINK`, since the
+   * lexical `../` check alone says nothing about where a path physically ends up.
+   *
+   * Symlinks that stay inside `dir` are always followed, whatever this is set to.
+   *
+   * This is **defense in depth**, not a fix for a remotely reachable hole: planting a symlink
+   * in the served directory already requires a symlink-create or arbitrary-write primitive
+   * there, and the served filesystem is assumed to be trusted. Comparable static file servers
+   * (`express.static`, nginx with `disable_symlinks off`) follow symlinks by default too.
+   *
+   * Enable it for the deployments where symlinking assets into the served directory is
+   * deliberate — monorepo `public/` layouts, CI artifact linking, Docker layer tricks.
+   * @optional
+   * @default false
+   */
+  allowSymlinksOutsideDir?: boolean;
 };
 /**
  * Creates a file system storage handler for IPX that allows images to be served from local directories specified in the options.
@@ -287,4 +455,4 @@ type UnstorageIPXStorageOptions = {
  * @throws {H3Error} If there is a problem retrieving or converting the storage data, detailed error information is thrown. See {@link H3Error}.
  */
 declare function unstorageToIPXStorage(storage: Storage | Driver, _options?: UnstorageIPXStorageOptions | string): IPXStorage;
-export { type HTTPStorageOptions, type Handler, type HandlerContext, type IPX, type IPXModifiers, type IPXOptions, type IPXStorage, type IPXStorageMeta, type IPXStorageOptions, type NodeFSSOptions, type UnstorageIPXStorageOptions, createIPX, createIPXFetchHandler, createIPXNodeHandler, ipxFSStorage, ipxHttpStorage, serveIPX, unstorageToIPXStorage };
+export { HTTPError, type HTTPStorageOptions, type Handler, type HandlerContext, type IPX, type IPXHandlerOptions, type IPXModifiers, type IPXOptions, type IPXParsedURL, type IPXStorage, type IPXStorageMeta, type IPXStorageOptions, type IPXURLParser, type NodeFSSOptions, type UnstorageIPXStorageOptions, createIPX, createIPXFetchHandler, createIPXNodeHandler, ipxFSStorage, ipxHttpStorage, parseIPXURL, serveIPX, unstorageToIPXStorage };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { HTTPError } from "./_chunks/libs/h3.mjs";
-import { createIPX, createIPXFetchHandler, createIPXNodeHandler, ipxFSStorage, ipxHttpStorage, serveIPX } from "./_chunks/node-fs.mjs";
+import { createIPX, createIPXFetchHandler, createIPXNodeHandler, ipxFSStorage, ipxHttpStorage, parseIPXURL, serveIPX } from "./_chunks/node-fs.mjs";
 function unstorageToIPXStorage(storage, _options = {}) {
 	const options = typeof _options === "string" ? { prefix: _options } : _options;
 	const resolveKey = (id) => options.prefix ? `${options.prefix}:${id}` : id;
@@ -29,4 +29,4 @@ function unstorageToIPXStorage(storage, _options = {}) {
 		}
 	};
 }
-export { createIPX, createIPXFetchHandler, createIPXNodeHandler, ipxFSStorage, ipxHttpStorage, serveIPX, unstorageToIPXStorage };
+export { HTTPError, createIPX, createIPXFetchHandler, createIPXNodeHandler, ipxFSStorage, ipxHttpStorage, parseIPXURL, serveIPX, unstorageToIPXStorage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ipx",
-  "version": "4.0.0-alpha.2",
+  "version": "4.0.0-beta.1",
   "description": "High performance, secure and easy-to-use image optimizer.",
   "repository": "unjs/ipx",
   "license": "MIT",
@@ -19,40 +19,40 @@
   ],
   "scripts": {
     "build": "obuild",
+    "gen:operations": "node ./scripts/gen-operations.ts",
     "ipx": "node ./src/cli.ts",
-    "lint": "eslint . && prettier -c src test",
-    "lint:fix": "automd && eslint . --fix && prettier -w src test",
+    "lint": "eslint . && prettier -c src test scripts automd.config.ts",
+    "lint:fix": "automd && eslint . --fix && prettier -w src test scripts automd.config.ts",
     "prepack": "pnpm build",
-    "release": "pnpm test && pnpm build && changelogen --release --prerelease --publish --publishTag alpha --push",
+    "release": "pnpm test && pnpm build && changelogen --release --prerelease --push && npm publish --tag latest",
     "start": "node bin/ipx.js",
     "test": "pnpm lint && pnpm test:types && vitest run --coverage",
     "test:types": "tsc --noEmit"
   },
   "dependencies": {
-    "pathe": "^2.0.3",
-    "sharp": "^0.35.2",
-    "srvx": "^0.11.17"
+    "sharp": "^0.35.3",
+    "srvx": "^0.12.4"
   },
   "devDependencies": {
     "@fastify/accept-negotiator": "^2.0.1",
     "@types/etag": "^1.8.4",
     "@types/is-valid-path": "^0.1.2",
-    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/coverage-v8": "^4.1.10",
     "automd": "^0.4.3",
     "changelogen": "^0.6.2",
-    "eslint": "^10.5.0",
+    "eslint": "^10.8.0",
     "eslint-config-unjs": "^0.6.2",
     "etag": "^1.8.1",
-    "h3": "2.0.1-rc.22",
+    "h3": "2.0.1-rc.26",
     "image-meta": "^0.2.2",
-    "obuild": "^0.4.37",
-    "oxc-minify": "^0.137.0",
-    "prettier": "^3.8.4",
-    "svgo": "^4.0.1",
-    "typescript": "^6.0.3",
+    "obuild": "^0.4.38",
+    "oxc-minify": ">=0.141.0",
+    "prettier": "^3.9.6",
+    "svgo": "^4.0.2",
+    "typescript": "^6",
     "ufo": "^1.6.4",
     "unstorage": "^1.17.5",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "unstorage": "*"
@@ -62,5 +62,8 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@11.9.0"
+  "engines": {
+    "node": "^20.16.0 || >=22.3.0"
+  },
+  "packageManager": "pnpm@11.17.0"
 }