safe_image 0.3.0 → 0.5.0

data/README.md

@@ -3,7 +3,7 @@
 Safe Image is a small Ruby image-processing boundary for untrusted uploads.
 
 It gives an application one narrow API for probing, thumbnailing, resizing,
-cropping, converting, optimising, SVG sanitising, animation checks, dominant
+cropping, converting, optimising, SVG metadata probing, animation checks, dominant
 colour extraction, favicon conversion, and letter-avatar generation.
 Everything that varies by host is decided once, at boot, with a single
 mandatory call:
@@ -12,27 +12,27 @@ mandatory call:
 SafeImage.configure!(backend: :vips, landlock: true)
 ```
 
-The `:vips` backend uses a tiny Fiddle binding that drives `libvips` directly
-— pure Ruby, nothing compiles at install time. The `:imagemagick` backend
-runs ImageMagick with shell-free command execution and a restrictive bundled
-policy. There are no per-call backend choices and no silent fallback from one
-backend to the other: you pick the decoder for untrusted bytes in one place
-and every operation uses it.
+The `:vips` backend uses a tiny compiled helper for all libvips work; the Ruby
+process never loads libvips. The `:imagemagick` backend runs ImageMagick with
+shell-free command execution and a restrictive bundled policy. There are no
+per-call backend choices and no silent fallback from one backend to the other:
+you pick the decoder for untrusted bytes in one place and every operation uses
+it.
 
 The premise is that hostile image bytes are a lousy thing to spread across
 model callbacks, upload helpers, optimizer wrappers, and hand-built command
 strings. Safe Image puts the risky operations behind one small, hardened
-choke point instead.
+choke point instead. See [`docs/architecture.md`](docs/architecture.md) for the
+security model and the invariants future changes must preserve.
 
 ## Install
 
-Nothing compiles at install time: libvips is bound at runtime through Fiddle
-(`libvips.so.42` is dlopened when `configure!(backend: :vips)` runs;
-`SAFE_IMAGE_LIBVIPS` overrides the library name authoritatively). libvips'
-GLib warnings about rejected input (e.g. "Not a PNG file") are silenced —
-failures surface as exceptions instead; set `SAFE_IMAGE_VIPS_WARNINGS=1` to
-restore them for debugging. Install the runtime
-[dependencies](#dependencies) below.
+A small native helper is compiled at gem install time and linked against
+libvips; install the libvips development package (`pkg-config vips` must work)
+in the build environment. At runtime, `configure!(backend: :vips)` verifies that
+this helper can start and initialize libvips; all subsequent libvips operations
+run in helper subprocesses whose stderr is captured and reported only on
+structured failures. Install the runtime [dependencies](#dependencies) below.
 
 ```bash
 gem build safe_image.gemspec
@@ -55,8 +55,8 @@ result = SafeImage.thumbnail(
 puts "#{result.backend}: #{result.width}x#{result.height} #{result.filesize} bytes"
 
 SafeImage.convert(
-  "upload.png",
-  "upload.jpg",
+  input: "upload.png",
+  output: "upload.jpg",
   format: "jpg",
   quality: 85,
   max_pixels: 40_000_000
@@ -66,13 +66,13 @@ SafeImage.convert(
 ## Configuration
 
 `SafeImage.configure!` must be called before any operation — typically from a
-boot-time initializer. Any operation before it (including the pure-Ruby SVG
-and remote helpers) raises `SafeImage::NotConfiguredError`.
+boot-time initializer. Any operation before it (including SVG metadata and remote
+helpers) raises `SafeImage::NotConfiguredError`.
 
 ```ruby
 SafeImage.configure!(
   backend: :vips,    # required: :vips or :imagemagick — decodes all untrusted bytes
-  landlock: true,    # required: route every operation through the Landlock sandbox
+  landlock: true,    # required: Landlock child helpers/tools when they run
   max_pixels: SafeImage::DEFAULT_MAX_PIXELS # optional: default decompression-bomb ceiling (128MP)
 )
 ```
@@ -80,7 +80,7 @@ SafeImage.configure!(
 Validation is eager, so a misconfigured host fails at boot rather than on the
 first request:
 
-- `backend: :vips` dlopens libvips and raises if it is unavailable
+- `backend: :vips` verifies that the compiled helper can initialize libvips and raises if it is unavailable
 - `backend: :imagemagick` raises if no `magick`/`convert` executable is found
 - `landlock: true` raises if the Landlock sandbox is unavailable
   (`SafeImage.sandbox_available?` works before `configure!`, so a host can
@@ -98,8 +98,8 @@ is decided here and only here.
 
 Choosing a backend:
 
-- `:vips` — the recommended fast path: explicit native loaders, in-process
-  hardening, no subprocess per operation
+- `:vips` — the recommended fast path: explicit native loaders in the compiled
+  helper process, with no libvips loaded into Ruby
 - `:imagemagick` — matches classic ImageMagick `convert` pipelines; also the
   option for hosts without libvips. Formats are decoded by ImageMagick under
   the bundled restrictive policy.
@@ -116,7 +116,7 @@ Debian / Ubuntu:
 
 ```bash
 sudo apt-get install --no-install-recommends \
-  libvips42 imagemagick jpegoptim pngquant oxipng libjpeg-turbo-progs
+  build-essential pkg-config libvips-dev imagemagick jpegoptim pngquant oxipng libjpeg-turbo-progs
 ```
 
 `oxipng` is packaged from Debian 13 / Ubuntu 24.04; on older releases install
@@ -127,7 +127,7 @@ detected at runtime.
 Arch:
 
 ```bash
-sudo pacman -S --needed libvips \
+sudo pacman -S --needed base-devel pkgconf libvips \
   imagemagick jpegoptim pngquant oxipng libjpeg-turbo libjxl
 ```
 
@@ -137,18 +137,19 @@ sudo pacman -S --needed libvips \
 
 | Dependency | Kind | Needed for | Without it |
 | --- | --- | --- | --- |
-| `libvips` runtime library (`libvips.so.42`; Debian: `libvips42` ≥ 8.13) | required for `backend: :vips` | the fast path for every operation, bound via Fiddle | `configure!(backend: :vips)` raises at boot; configure `backend: :imagemagick` instead |
+| `libvips` runtime library (`libvips.so.42`; Debian: `libvips42` ≥ 8.13) plus development headers/pkg-config at gem build time | required for `backend: :vips` | the fast path for every operation and the compiled helper | gem install fails without headers; `configure!(backend: :vips)` raises at boot if the runtime library is unavailable |
 | ImageMagick (`magick`/`convert`, `identify`) | required for `backend: :imagemagick` | every operation on the `:imagemagick` backend | `configure!(backend: :imagemagick)` raises at boot |
 | `jpegoptim` | required for JPEG `optimize` | lossless JPEG optimisation and metadata stripping | JPEG `optimize` raises in strict mode |
 | `oxipng` | required for PNG `optimize` | lossless PNG optimisation | PNG `optimize` raises in strict mode |
 | `pngquant` | optional | lossy PNG quantisation (`optimize_mode: :lossy`, files < 500KB) | lossy mode silently skips the quantisation pass |
-| `jpegtran` (libjpeg-turbo) | optional | lossless tier of `fix_orientation`; uprighting EXIF-oriented JPEGs in `optimize` | `fix_orientation` falls back to the libvips re-encode tier; `optimize` of an oriented JPEG raises in strict mode (left untouched otherwise) |
+| `jpegtran` (libjpeg-turbo) | optional | lossless tier of `fix_orientation`; uprighting EXIF-oriented JPEGs in `optimize` | `fix_orientation` falls back to the libvips re-encode tier; `optimize` of an oriented JPEG raises in strict mode (or copies source to output with `strict: false`) |
 | `cjpegli` (libjxl) | optional | higher-quality encoding of generated JPEGs on the `:vips` backend — used automatically when installed | generated JPEGs use the backend's own encoder |
-| `landlock` gem (Linux kernel ≥ 5.13) | required for `landlock: true` | the atomic sandbox around every operation | `configure!(landlock: true)` raises at boot; `sandbox_available?` is false |
-| `rexml` gem | automatic | SVG sanitising and SVG metadata | installed as a gem dependency |
+| `landlock` gem ≥ 0.3 (Linux kernel ≥ 5.13) | required for `landlock: true` | optional sandboxing for child helpers/tools (`safe_image_vips_helper`, ImageMagick, optimizers, jpegtran/cjpegli) | `configure!(landlock: true)` raises at boot; `sandbox_available?` is false |
+| `nokogiri` gem | automatic | bounded SVG metadata parser (not Landlock-contained) | installed as a gem dependency |
 
-The `landlock` gem is intentionally **not** a gem dependency; add it to the
-host application's Gemfile if you want sandboxing.
+The `landlock` gem is intentionally **not** a runtime gem dependency; add
+`gem "landlock", ">= 0.3"` to the host application's Gemfile if you want
+sandboxing.
 
 ### libvips build capabilities
 
@@ -190,7 +191,7 @@ require "safe_image"
 %w[magick identify jpegoptim oxipng pngquant jpegtran cjpegli].each do |tool|
   puts format("%-10s %s", tool, SafeImage::Runner.available?(tool) ? "ok" : "missing")
 end
-puts format("%-10s %s", "libvips", SafeImage::VipsGlue.available? ? "ok" : "unavailable")
+puts format("%-10s %s", "vips-helper", SafeImage::Native.available? ? "ok" : "unavailable")
 puts format("%-10s %s", "sandbox", SafeImage.sandbox_available? ? "ok" : "unavailable")
 ```
 
@@ -213,8 +214,8 @@ SafeImage::Result[
   width:,
   height:,
   filesize:,
-  backend:,        # e.g. "libvips-direct", "imagemagick", "cjpegli",
-                   #      "libvips-direct+cjpegli"
+  backend:,        # e.g. "libvips-helper", "imagemagick", "cjpegli",
+                   #      "libvips-helper+cjpegli"
   duration_ms:,
   optimizer:       # optimizer tool list for thumbnail path, otherwise nil
 ]
@@ -291,7 +292,9 @@ SafeImage.size("icon.svg")         # => [120, 80]
 SVG metadata is handled by a dedicated parser, not ImageMagick or libvips. It is
 limited to local `.svg` files, caps input size/tree depth/element/attribute
 counts, rejects `DOCTYPE` and non-XML processing instructions, requires an `<svg>`
-root, and derives dimensions from numeric `width`/`height` or `viewBox`.
+root, and derives dimensions from numeric `width`/`height` or `viewBox`. This
+bounded Nokogiri/libxml2 parse happens in the Ruby process; `landlock: true`
+contains child image helpers/tools, not SVG metadata parsing itself.
 
 #### `SafeImage.orientation(path, max_pixels: nil)`
 
@@ -486,15 +489,20 @@ SafeImage.fetch_remote("https://example.com/image.jpg", max_bytes: 10.megabytes)
 end
 ```
 
-With `landlock: true` configured, the network fetch itself is not put inside
-the Landlock worker because the worker denies network access. The downloaded
-tempfile is then passed through the normal Safe Image local image APIs, so
-decoding still uses the same sandboxed image-processing path.
+With `landlock: true` configured, the network fetch itself is not sandboxed: it
+needs network access, while the image-processing child helpers/tools deliberately
+do not get it. The downloaded tempfile is then passed through the normal Safe
+Image local APIs, so raster decoding and transform subprocesses still use the
+configured Landlock containment.
 
 ### Generating images
 
 Operations that write a new image. All of them run on the configured backend
-and return [`SafeImage::Result`](#return-values).
+and return [`SafeImage::Result`](#return-values). Every operation that reads an
+existing image and writes a file requires explicit `input:` and `output:` paths;
+they must be distinct. Safe Image does not expose in-place mutating APIs — if a
+caller wants to replace a file, write to a separate destination and perform the
+rename in application code.
 
 #### `SafeImage.thumbnail(...)`
 
@@ -524,46 +532,46 @@ Supported outputs on the `:vips` backend:
 - `avif`
 - `jxl` (requires a libvips build with libjxl support)
 
-#### `SafeImage.resize(from, to, width, height, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
+#### `SafeImage.resize(input:, output:, width:, height:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
 
 Creates a resized thumbnail-style output.
 
 ```ruby
-SafeImage.resize("upload.jpg", "thumb.jpg", 600, 400)
-SafeImage.resize("upload.jpg", "thumb.jpg", 600, 400, quality: 85)
+SafeImage.resize(input: "upload.jpg", output: "thumb.jpg", width: 600, height: 400)
+SafeImage.resize(input: "upload.jpg", output: "thumb.jpg", width: 600, height: 400, quality: 85)
 ```
 
 `resize`, `crop` and `downsize` run on the configured backend:
 
-- `:vips` — the direct libvips path; formats outside the native loader
+- `:vips` — the helper-backed libvips path; formats outside the native loader
   allowlist (ICO input) fail closed
 - `:imagemagick` — matches classic `convert` thumbnail pipelines
   (`-thumbnail`, catrom interpolation, unsharp, sRGB profile); configure this
   if byte-similar output with previously generated thumbnails matters
 
-#### `SafeImage.crop(from, to, width, height, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
+#### `SafeImage.crop(input:, output:, width:, height:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
 
 Creates a north-cropped image — the shape typically used for square avatar
 crops.
 
 ```ruby
-SafeImage.crop("upload.jpg", "avatar.jpg", 240, 240)
+SafeImage.crop(input: "upload.jpg", output: "avatar.jpg", width: 240, height: 240)
 ```
 
-#### `SafeImage.downsize(from, to, dimensions, optimize: true, max_pixels: nil, quality: 85, chroma_subsampling: :auto)`
+#### `SafeImage.downsize(input:, output:, dimensions:, optimize: true, max_pixels: nil, quality: 85, chroma_subsampling: :auto)`
 
 Downsizes an image using ImageMagick-style geometry strings.
 
 ```ruby
-SafeImage.downsize("large.png", "small.png", "50%")
-SafeImage.downsize("large.png", "small.png", "100x100>")
-SafeImage.downsize("large.png", "small.png", "400000@")
+SafeImage.downsize(input: "large.png", output: "small.png", dimensions: "50%")
+SafeImage.downsize(input: "large.png", output: "small.png", dimensions: "100x100>")
+SafeImage.downsize(input: "large.png", output: "small.png", dimensions: "400000@")
 ```
 
 The vips backend supports the geometry forms covered by the test suite:
 percentage, bounding box with `>`, and pixel-area cap with `@`.
 
-#### `SafeImage.convert(from, to, format:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
+#### `SafeImage.convert(input:, output:, format:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
 
 Converts an input image to an explicit output `format:`. Unsupported formats
 raise `SafeImage::UnsupportedFormatError`.
@@ -580,12 +588,12 @@ For PNG-to-JPEG on the `:vips` backend, `cjpegli` is used automatically when
 installed (see [JPEG encoding of generated images](#jpeg-encoding-of-generated-images)).
 
 ```ruby
-SafeImage.convert("upload.png", "upload.jpg", format: "jpg", quality: 85)
-SafeImage.convert("upload.heic", "upload.jpg", format: "jpg", quality: 85)
-SafeImage.convert("upload.jpg", "upload.webp", format: "webp", quality: 85)
+SafeImage.convert(input: "upload.png", output: "upload.jpg", format: "jpg", quality: 85)
+SafeImage.convert(input: "upload.heic", output: "upload.jpg", format: "jpg", quality: 85)
+SafeImage.convert(input: "upload.jpg", output: "upload.webp", format: "webp", quality: 85)
 ```
 
-#### `SafeImage.fix_orientation(from, to = from, max_pixels: nil, quality: nil)`
+#### `SafeImage.fix_orientation(input:, output:, max_pixels: nil, quality: nil)`
 
 Bakes the EXIF orientation into the pixels and clears the tag. The `:vips`
 backend tries tiers in order:
@@ -599,26 +607,23 @@ backend tries tiers in order:
 The `:imagemagick` backend uses the previous `-auto-orient` behaviour and
 re-encodes at the input's estimated quality.
 
-If `to` is omitted, the file is rewritten in place.
-
 ```ruby
-SafeImage.fix_orientation("upload.jpg")
-SafeImage.fix_orientation("upload.jpg", "oriented.jpg")
+SafeImage.fix_orientation(input: "upload.jpg", output: "oriented.jpg")
 ```
 
-#### `SafeImage.convert_favicon_to_png(from, to, optimize: true, max_pixels: nil)`
+#### `SafeImage.convert_favicon_to_png(input:, output:, optimize: true, max_pixels: nil)`
 
 Extracts the largest ICO entry and writes PNG. On the `:vips` backend no
 ImageMagick is involved: the container and legacy DIB payloads (1/4/8/24/32bpp
 BI_RGB plus the AND mask) are parsed in pure Ruby with explicit bounds checks,
-and pixels are encoded through the hardened native libvips path. Embedded PNG
+and pixels are encoded through the hardened libvips helper. Embedded PNG
 payloads are re-encoded — never copied through verbatim — and their pixel cap
 is enforced from the IHDR before any decoder runs. On the `:imagemagick`
 backend the conversion runs through ImageMagick's ico decoder under the
 bundled policy.
 
 ```ruby
-SafeImage.convert_favicon_to_png("favicon.ico", "favicon.png")
+SafeImage.convert_favicon_to_png(input: "favicon.ico", output: "favicon.png")
 ```
 
 #### `SafeImage.letter_avatar(output:, size:, background_rgb:, letter:, pointsize: 280, font: "DejaVu-Sans")`
@@ -658,17 +663,18 @@ JPEGs**. This avoids hiding a lossy re-encode behind a method named `optimize`.
 
 Like the optimizer tools, the optional `cjpegli` encoder is availability
 driven: installed means used, absent means the configured backend encodes.
-There is no encoder knob — cjpegli only ever encodes pixels Safe Image has
-already decoded, so it is not part of the untrusted-input surface the backend
-choice controls.
+There is no encoder knob. Even when cjpegli is used, untrusted inputs are first
+decoded by the configured Safe Image backend with the normal pixel cap; cjpegli
+only receives a PNG generated by Safe Image, so it is not an additional
+untrusted-input decoder.
 
 | Operation | Behavior |
 | --- | --- |
-| `thumbnail` / `resize` / `crop` / `downsize` to JPEG on the `:vips` backend | use `cjpegli` when installed; otherwise normal libvips JPEG output |
-| `convert("input.png", "output.jpg", format: "jpg")` on the `:vips` backend | use `cjpegli` when installed (PNG is the one input Jpegli encodes directly); otherwise libvips |
-| `convert` from HEIC/WebP/AVIF/GIF/JPEG to JPEG | decode through the native libvips loaders and encode with libvips; `cjpegli` is not treated as a universal decoder |
+| `thumbnail` / `resize` / `crop` / `downsize` to JPEG on the `:vips` backend | decode through libvips first, then use `cjpegli` when installed; otherwise normal libvips JPEG output |
+| `convert(input: "input.png", output: "output.jpg", format: "jpg")` on the `:vips` backend | decode the PNG through libvips into a generated PNG first, then use `cjpegli` when installed; otherwise libvips |
+| `convert` from HEIC/WebP/AVIF/GIF/JPEG/JXL to JPEG | decode through the native libvips loaders and encode with libvips; `cjpegli` is not treated as a universal decoder |
 | any operation on the `:imagemagick` backend | ImageMagick encodes; `cjpegli` is never used |
-| `optimize("existing.jpg")` | use `jpegoptim`; never `cjpegli` |
+| `optimize(input: "existing.jpg", output: "optimized.jpg")` | use `jpegoptim`; never `cjpegli` |
 
 `cjpegli` output is ordinary browser-compatible JPEG. It is optional because it
 is a system binary, not a Ruby dependency. Safe Image detects it at runtime.
@@ -676,16 +682,17 @@ is a system binary, not a Ruby dependency. Safe Image detects it at runtime.
 `chroma_subsampling: :auto` uses `4:4:4` for PNG-sourced JPEG conversion and
 `4:2:0` otherwise. Pass `"420"`, `"422"`, or `"444"` to force a value.
 
-### Optimising in place
+### Optimising to a destination
 
-#### `SafeImage.optimize(path, mode: :lossless, strip_metadata: true, quality: nil, strict: true)`
+#### `SafeImage.optimize(input:, output:, mode: :lossless, strip_metadata: true, quality: nil, strict: true)`
 
-Optimises an existing JPEG or PNG in place.
+Optimises an existing JPEG or PNG into a separate output path. The source file is
+never modified, and `input:`/`output:` must not refer to the same file.
 
 ```ruby
-SafeImage.optimize("image.jpg", quality: 85)
-SafeImage.optimize("image.png")
-SafeImage.optimize("image.png", mode: :lossy, quality: "65-90")
+SafeImage.optimize(input: "image.jpg", output: "image.optimized.jpg", quality: 85)
+SafeImage.optimize(input: "image.png", output: "image.optimized.png")
+SafeImage.optimize(input: "image.png", output: "image.lossy.png", mode: :lossy, quality: "65-90")
 ```
 
 JPEG path:
@@ -699,8 +706,8 @@ JPEG path:
   images rotate exactly (`-perfect`); others drop the partial edge blocks
   (`-trim`, under one MCU — at most 15px), reported as `trimmed: true` in
   the result rather than re-encoding behind a method named `optimize`.
-  Without `jpegtran`, an oriented JPEG raises in strict mode and is left
-  untouched otherwise — never stripped sideways.
+  Without `jpegtran`, an oriented JPEG raises in strict mode and the output is
+  not written; with `strict: false`, the original bytes are copied to `output:`.
 
 PNG path:
 
@@ -709,138 +716,18 @@ PNG path:
   then `oxipng`
 
 When `strict: true`, missing optimizer tools raise. When `strict: false`, missing
-optimizer tools are tolerated.
-
-### SVG sanitising
+optimizer tools are tolerated and the output is still written from the source
+copy when possible.
 
-#### `SafeImage.sanitize_svg!(path, id_namespace:)`
+### SVG handling
 
-Sanitises an SVG in place using a small REXML allowlist. `id_namespace:` is
-**required** — it forces a deliberate choice of where the output may be used,
-so there is no silently-wrong default (see "Inlining" below):
-
-```ruby
-# served as an <img src>/CSS-url/file and never spliced into a page's DOM:
-result = SafeImage.sanitize_svg!("icon.svg", id_namespace: :standalone)
-
-# spliced inline into an HTML DOM (pass a stable, per-document token):
-result = SafeImage.sanitize_svg!("icon.svg", id_namespace: "u#{upload.sha1}")
-
-puts result[:sanitized]
-```
-
-Omitting `id_namespace:` (or passing `nil`/`""`) raises `ArgumentError`.
-
-The sanitizer removes unsafe elements/attributes such as scripts and event
-handlers. It is intentionally conservative rather than a full browser-grade SVG
-implementation.
-
-CSS is reduced to a constructed allowlist subset rather than stripped: `style`
-attributes (as written by Inkscape) and `<style>` elements (as written by
-Illustrator) survive when they parse against a small grammar — allowlisted
-properties, type/class/id selectors, numeric/keyword/color values, and
-`url(#fragment)` references only. The output is reassembled from validated
-tokens, never echoed from the input; escapes, quotes, at-rules (`@import`,
-`@font-face`, `@media`), comments, strings, and unknown
-properties/functions/selectors drop the declaration, rule, or whole stylesheet
-rather than being interpreted.
-
-Two behaviours are worth knowing before relying on this:
-
-- **The CSS property allowlist mirrors the presentation attributes that have
-  CSS-property twins** — `SvgCss::ALLOWED_PROPERTIES` is a subset of
-  `SvgSanitizer::ALLOWED_ATTRIBUTES` (asserted by a test), so a `fill:`
-  declaration and a `fill=""` attribute are treated identically and a property
-  the sanitizer would strip as an attribute is also dropped in CSS. (The
-  reverse does not hold: geometry/XML attributes like `width`, `href`, and
-  `xmlns` are not CSS properties.) The set covers the common paint, stroke
-  (including `stroke-dasharray` and `vector-effect`), marker, text, and
-  visibility properties that Inkscape and Illustrator emit; it is deliberately
-  narrower than a browser. Filters (`filter`, `fe*`) are not yet included.
-- **A `<style>` element fails closed as a whole** on anything outside a flat
-  list of `selector { declarations }` rules. Any at-rule (e.g. one stray
-  `@import`), a nested block, or an unbalanced brace discards every rule in that
-  element, not just the offending one. Within a well-formed stylesheet,
-  individual selectors and declarations still drop independently.
-
-SVG sanitising is defense-in-depth for stored bytes. Applications that serve
-user-supplied SVGs directly should still use response-level controls such as a
+Safe Image no longer sanitises or rewrites SVG files. It only supports bounded
+metadata probing for local and remote `.svg` inputs (`type`, `size`, `info`, and
+the corresponding remote helpers). Applications that accept user-supplied SVG
+content for display should run a dedicated SVG sanitizer in their own upload or
+rendering pipeline, and should still use response-level controls such as a
 restrictive `Content-Security-Policy`, `X-Content-Type-Options: nosniff`, and/or
-attachment/sandbox handling for direct-open routes. Browsers restrict script
-execution when an SVG is embedded as `<img>`, but a top-level SVG document is a
-different sink.
-
-#### Inlining sanitized SVG into an HTML page
-
-The `id_namespace:` argument forces this decision at every call site — there is
-no default to get wrong.
-
-Pass `:standalone` when the output is only ever served as an external resource —
-`<img src>`, `background-image`, an `<object>`/`<iframe>`, or its own file. This
-is the document-safe form. It is **not** safe to splice directly into an HTML
-DOM: a preserved `<style>` rule like `*{visibility:hidden}` or
-`#header{display:none}` would join the host document's cascade, and the SVG's
-`id`s could clobber host ids — both CSS-injection / UI-redress vectors.
-
-Pass a **stable, per-document** String (e.g. the upload's sha) to make the output
-safe to inline:
-
-```ruby
-SafeImage.sanitize_svg!("icon.svg", id_namespace: "u#{upload.sha1}")
-```
-
-With a namespace, the sanitizer:
-
-- prefixes every `id` and every reference to it — `href`/`xlink:href` fragments,
-  `url(#…)` in attributes and CSS, and ARIA IDREF attributes (`aria-labelledby`,
-  `aria-describedby`, `aria-controls`, …) — so internal references stay intact
-  but cannot collide with host ids; and
-- prefixes every `class` token (and the `.class` selectors that match them), so
-  an attacker can't invoke the host page's framework CSS — a bare
-  `class="modal fixed"` would otherwise pick up Bootstrap/Tailwind/app styles and
-  become an overlay. Internal class styling still matches because attribute and
-  selector are prefixed together; and
-- scopes every `<style>` selector under a `<ns>-scope` class it adds to the root
-  `<svg>`, so `*` and type selectors only match that document's own content and
-  can never reach the host page; and
-- rejects `var()`, `env()`, and `attr()` in presentation attributes — they
-  resolve against the host page (custom properties, environment) and could pull
-  in values, including a `url()`, the sanitizer never saw; and
-- drops `overflow` from the root `<svg>` so it clips to its declared viewport — a
-  tiny `width`/`height` with `overflow:visible` and oversized content would
-  otherwise paint a full-page overlay. Inner elements keep `overflow` (markers
-  need it); the root clip bounds them.
-
-Because every `<style>` selector is anchored *under* the scope class, a rule
-targeting the root itself — `svg { … }`, `* { … }` intended to include the root,
-or a class on the root such as `.icon { … }` for `<svg class="icon">` — matches
-the root's descendants but not the root element. Root-level styling from a
-`<style>` block therefore does not survive; style the root via attributes if you
-need it. (This is rare in editor exports, which style the root with attributes
-and inner elements with classes.)
-
-`style=""` attributes never need selector scoping — a declaration list only
-styles its own element — so they are not a cascade risk in either mode. They can
-still carry `url(#…)` references, though, which are only namespaced when you pass
-a String; so `:standalone` output (bare ids and references) is still not for
-inline use. The transform is idempotent for a given namespace, so re-sanitising
-is a no-op. Use a per-document value so two inlined SVGs on one page don't share
-a namespace.
-
-### Compatibility aliases
-
-Two thin wrappers kept for callers migrating from existing upload pipelines:
-
-```ruby
-SafeImage.optimize_image!("image.jpg")
-SafeImage.optimize_image!("image.png", allow_lossy_png: true)
-SafeImage.convert_to_jpeg("upload.heic", "upload.jpg", quality: 85)
-```
-
-`optimize_image!(path, allow_lossy_png: false, strip_metadata: true, quality: nil, strict: true)`
-forwards to `optimize`, with `allow_lossy_png:` mapping to `mode:`.
-`convert_to_jpeg(from, to, ...)` forwards to `convert` with `format: "jpg"`
-and accepts the same keywords.
+attachment/sandbox handling for direct-open routes.
 
 ## Security
 
@@ -857,12 +744,12 @@ What it does:
 - starts external commands with an allowlisted environment, private temp/home/cache
   directories, bounded stdout/stderr, and process-group timeout cleanup
 - uses explicit libvips loaders selected from allowlisted extensions
-- enables libvips' untrusted-operation block in-process (deliberately
+- enables libvips' untrusted-operation block inside the helper (deliberately
   re-enabling only the libjxl loader/saver, which libvips tags untrusted,
   because JPEG XL is part of the supported input surface)
-- blocks libvips ImageMagick loader classes in the libvips binding, which
-  itself exposes only the operations the gem invokes
-- disables libvips cache by default in-process
+- blocks libvips ImageMagick loader classes in the helper, which exposes only
+  the operations the gem invokes
+- disables libvips cache inside the helper
 - strips metadata on generated images where applicable
 - rejects symlinked local input/output paths and symlinked path components for
   untrusted file-processing paths
@@ -879,12 +766,8 @@ What it does:
   blocking, DNS pinning, redirect limits, HTTPS-to-HTTP rejection, proxy-env
   bypass prevention, request-header allowlists, content-type/extension
   agreement, and probe-before-yield (details under [Remote URLs](#remote-urls))
-- parses SVG metadata with a bounded pure-Ruby parser; SVG is never handed to
+- parses SVG metadata with a bounded Nokogiri SAX parser; SVG is never handed to
   ImageMagick for probing
-- sanitises SVG conservatively, allowlist based: rejects `DOCTYPE` and XML
-  processing instructions, removes comments and disallowed elements, converts
-  CDATA to escaped text, and blocks event handlers, external URLs, and
-  `javascript:` / `data:` URL values
 - supports optional Landlock subprocess sandboxing on Linux
 
 The backend is a configuration decision, not a per-call option. Safe Image
@@ -907,23 +790,23 @@ ImageMagick path runs with:
 
 That does **not** make hostile files benign. Raster decoders still parse attacker
 controlled bytes: libjpeg, libpng, libwebp, libheif/HEIC/AVIF, ImageMagick's
-raster decoders, and libvips loaders. If one of those decoders has a memory
-corruption bug or pathological resource-consumption bug, policy alone is not a
-sandbox.
+raster decoders, and libvips loaders; Nokogiri/libxml2 also parses SVG metadata.
+If one of those parsers or decoders has a memory corruption bug or pathological
+resource-consumption bug, policy alone is not a sandbox.
 
 So the intended posture is:
 
 - without Landlock: hardened, centralized image processing with the major
   ImageMagick delegate/pseudo-protocol foot-guns removed
-- with Landlock: the same hardening plus a real containment boundary around all
-  public operations
+- with Landlock: the same hardening plus a containment boundary around child
+  helpers/tools that parse or transform raster bytes
 
 Do not describe non-sandboxed operation as making hostile images safe. The honest
 claim is defense-in-depth, not immunity.
 
-### Atomic Landlock sandboxing
+### Optional Landlock containment
 
-Landlock support is optional, but atomic once configured.
+Landlock support is optional, but fail-closed once configured.
 
 ```ruby
 SafeImage.sandbox_available?                       # => true/false, works before configure!
@@ -931,74 +814,44 @@ SafeImage.configure!(backend: :vips, landlock: true) # raises if unavailable
 SafeImage.config.landlock                          # => true
 ```
 
-With `landlock: true`, every public operation routes through the sandbox
-worker:
-
-- `probe`
-- `type`
-- `size`
-- `dimensions`
-- `info`
-- `orientation`
-- `dominant_color`
-- `thumbnail`
-- `optimize`
-- `resize`
-- `crop`
-- `downsize`
-- `convert`
-- `convert_to_jpeg` compatibility alias
-- `fix_orientation`
-- `convert_favicon_to_png`
-- `frame_count`
-- `animated?`
-- `letter_avatar`
-- `optimize_image!`
-- `sanitize_svg!`
-
-There is no silent fallback once landlock is configured. If sandbox setup or
-a sandboxed command fails, the operation fails.
-
-The sandbox grants read/write access only to the paths inferred from the
-operation arguments, plus runtime/library paths and temporary directories needed
-by Ruby, libvips, ImageMagick, and optimizer tools. Worker processes inherit the
-parent's backend and pixel-ceiling configuration; landlock is forced off
-inside the worker so sandboxed operations never nest.
-
-Operations are served by a pool of resident **zygote** workers: each is a
-fresh Ruby process that boots the gem once and then forks a child per
-operation, so the ~85ms boot cost (Ruby + requires + libvips init) is paid
-once per burst instead of per call — a warm sandboxed operation costs ~3–8ms
-over the unsandboxed one. The pool grows on demand to
-`SAFE_IMAGE_ZYGOTE_WORKERS` (default 8), so N threads run N sandboxed
-operations concurrently (throughput scales near-linearly with cores until the
-work itself saturates the CPU); offered concurrency past the cap blocks until
-a worker frees, which also bounds how many libvips decodes run at once.
-Idling is cheap (~16MB private memory per worker, zero CPU), so a worker
-lingers for `Zygote::IDLE_SECONDS` (300) without work before exiting on its
-own; the next operation boots a new one. Workers also exit immediately when
-their parent process does, and `configure!` always retires the pool.
-
-A zygote itself never touches untrusted bytes: each forked child first
-applies rlimits, its per-operation Landlock policy (filesystem allowlist, all
-TCP denied on Landlock ABI ≥ 4, abstract-unix-socket/signal scopes on
-ABI ≥ 6), and — when the installed `landlock` gem exposes
-`seccomp_deny_network!` — the helper's deny-all-network seccomp filter (which
-blocks sockets of every family, closing the non-TCP/UDP gap the in-process
-Landlock policy alone leaves open), and only then runs the operation. Forking
-is sound because the zygote never runs operations itself — libvips is
-initialised but quiescent (no native threads) at every fork.
-
-`SAFE_IMAGE_ZYGOTE=0` falls back to the exec-per-operation worker (a fresh
-sandboxed Ruby per call through the Landlock helper binary, whose seccomp
-filter denies sockets of every family, no pool); `SAFE_IMAGE_ZYGOTE_WORKERS`
-and `SAFE_IMAGE_ZYGOTE_IDLE_SECONDS` tune the pool cap and idle window.
+With `landlock: true`, Safe Image does **not** proxy public operations through a
+sandboxed Ruby worker. Ruby remains the orchestrator: it validates paths, stages
+outputs, applies format/pixel policy, parses bounded SVG/ICO metadata where
+needed, and launches the actual image-processing helpers/tools.
+
+The Landlock boundary is applied to child processes that do risky native image
+work:
+
+- `safe_image_vips_helper` for every libvips operation
+- ImageMagick `magick`/`convert`/`identify` commands on the `:imagemagick` backend
+- optimizer tools such as `jpegoptim`, `oxipng`, and `pngquant`
+- `jpegtran` and `cjpegli` when those optional paths are used
+
+There is no silent fallback once Landlock is configured. If sandbox setup or a
+sandboxed helper/tool fails, the operation fails.
+
+Each child process receives only the explicit read/write grants for that call,
+plus runtime/library/font/temp paths needed by the helper or tool. The network is
+denied for those children; remote fetching happens in Ruby before the downloaded
+tempfile is handed back to the local image APIs.
+
+For the `:vips` backend, raster operations are executed by the compiled
+`safe_image_vips_helper` executable. The Ruby process performs path validation and
+orchestration, then the helper initializes libvips in its own process, applies the
+loader/operation allowlist and pixel cap, writes a structured JSON response, and
+exits. With Landlock enabled, the helper process itself is launched inside the
+per-call filesystem policy.
+
+SVG metadata is the deliberate exception: it is bounded and non-rendering, but it
+is parsed by Nokogiri/libxml2 in the Ruby process and is not Landlock-contained by
+Safe Image. If your deployment needs a hard kernel boundary around SVG parsing as
+well, run Safe Image in a separate application process/container.
 
 ## Development
 
 ```bash
 bundle install
-bundle exec rake          # run the tests (nothing compiles)
+bundle exec rake          # run the tests (builds/uses the native vips helper)
 docker/run.sh             # run the suite on Debian bookworm's packaged libvips 8.14
 bundle exec rubocop       # lint
 ```
@@ -1010,8 +863,8 @@ explanation when that support is missing.
 
 The suite includes golden-output checks, cross-backend parity checks (the
 claim is operation parity, not byte-for-byte output identity across
-ImageMagick/libvips versions), policy-denial checks, and a real-image atomic
-sandbox sweep over the full public operation list.
+ImageMagick/libvips versions), policy-denial checks, and Landlock sweeps over
+helper/tool execution paths.
 
 Gem packaging uses the standard Bundler tasks (`rake build`, `rake install`).
 Releases: bump `SafeImage::VERSION`, merge to `main`, and CI publishes the