ipx

When using ipxHttpStorage, setting blockPrivateIPs: true provides a second line of defense against SSRF. It ensures that the host of the requested URL and every redirect hop resolves to a public IP address. It rejects loopback, RFC1918, CGNAT, link-local, and other reserved/private ranges.

Note: This is off by default to allow fetching from internal cluster origins (like sidecars or local object storage) in development or specific deployments.

ipxHttpStorage({ domains: ["cdn.example.com"], blockPrivateIPs: true });

To prevent XSS, IPX always sanitizes SVG documents. Sanitization is independent of optimization. IPX removes:

• <script> elements and event handler attributes (on*).
• Embedded foreign documents (<foreignObject>, <iframe>, etc.).
• SMIL animations that use unsafe URIs.
• URIs with dangerous schemes (e.g., javascript:).
• <!DOCTYPE> declarations and processing instructions.

External references like <image href="..."> or <use> are preserved.

Warning: Sanitization can be disabled with unsafeSkipSanitize: true, but this should only be done if the source is fully trusted, as it allows XSS payloads to pass through unchanged.

createIPX({
  storage,
  svg: {
    // Serve SVG images unsanitized. Only for fully trusted sources!
    unsafeSkipSanitize: false,
  },
});

IPX uses modifiers in the URL path to transform images. Modifier arguments are separated by underscores (_).

Validation and Errors

• 400 IPX_INVALID_MODIFIER_ARG: An argument was provided but is invalid.
• 400 IPX_MISSING_MODIFIER_ARG: A required argument for a modifier is missing.
• 400 IPX_INVALID_MODIFIER: The modifier could only be validated by libvips after the pipeline was set up.

Argument Syntax

• Colours: Accept hex codes (e.g., f00, ff0000, ff000080) or CSS colour names (e.g., red). Note that the leading # cannot be used in a URL path and should be omitted.
• Booleans: Accept true/false or the shorthand 1/0.
• Trailing Arguments: May be omitted to use the default value, unless the modifier requires them.

If you are using the Bun runtime, you can start the IPX server using bunx.

bunx ipx serve --dir ./

To start an IPX server for images located in your current directory, use the ipx serve command. You can run this via npx or bunx.

npx ipx serve --dir ./

To use IPX within an h3 application, use the createIPXFetchHandler function to create a handler from your IPX instance.

import { H3, serve } from "h3";
import {
  createIPX,
  ipxFSStorage,
  ipxHttpStorage,
  createIPXFetchHandler,
} from "ipx";

const ipx = createIPX({
  storage: ipxFSStorage({ dir: "./public" }),
  httpStorage: ipxHttpStorage({ domains: ["picsum.photos"] }),
  alias: { "/picsum": "https://picsum.photos" },
});

const app = new H3();
app.mount("/ipx", createIPXFetchHandler(ipx));

serve(app);

IPX processes SVG images by sanitizing them and optionally optimizing them with svgo.

Optimization: By default, SVGO's preset-default is applied. This can break SVGs that rely on specific IDs for external references (like sprite sheets) or internal CSS selectors. To sanitize without optimizing, use optimize: false. To keep optimization but prevent ID renaming or element removal, configure the plugins manually.

// Sanitize without optimizing
createIPX({
  storage,
  svg: {
    optimize: false,
  },
});

// Optimize with specific plugin overrides to preserve IDs/elements
createIPX({
  storage,
  svg: {
    optimize: {
      plugins: [
        {
          name: "preset-default",
          params: {
            overrides: { cleanupIds: false, removeHiddenElems: false },
          },
        },
      ],
    },
  },
});

To use IPX within an express application, use the createIPXNodeHandler function. Note that you may need to cast the result to a RequestHandler for TypeScript compatibility.

import Express from "express";
import {
  createIPX,
  ipxFSStorage,
  ipxHttpStorage,
  createIPXNodeHandler,
} from "ipx";
import type { RequestHandler } from "express";

const ipx = createIPX({
  storage: ipxFSStorage({ dir: "./public" }),
  httpStorage: ipxHttpStorage({ domains: ["picsum.photos"] }),
  alias: { "/picsum": "https://picsum.photos" },
});

const app = Express();
app.use("/ipx", createIPXNodeHandler(ipx) as RequestHandler);

app.listen(3000);