safe_image 0.2.0 → 0.4.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` for MCU-aligned JPEGs | falls back to the libvips re-encode tier |
+| `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
 ]
@@ -228,7 +229,9 @@ Optimizer operations return a hash:
   before_bytes: 123_456,
   after_bytes: 120_000,
   saved_bytes: 3_456,
-  tools: ["jpegoptim"]
+  tools: ["jpegoptim"],
+  rotated_from: nil,  # the EXIF orientation baked into the pixels, when one was set
+  trimmed: false      # true when uprighting dropped partial edge blocks (see optimize)
 }
 ```
 
@@ -289,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)`
 
@@ -367,8 +372,26 @@ SafeImage.dominant_color("upload.png") # => "6F745E"
 
 These helpers are intended to cover `FastImage.size(url)` / `FastImage.type(url)`
 style use cases without another Ruby dependency. They use only Ruby stdlib
-`Net::HTTP`, download to a tempfile with a byte cap, then run the normal Safe
-Image local metadata path on that tempfile.
+`Net::HTTP` and stream to a tempfile with a byte cap.
+
+Like FastImage, the metadata helpers (`remote_size`, `remote_type`,
+`remote_info`, `remote_animated?`) download as little as possible: the normal
+Safe Image local metadata path probes the partially-downloaded tempfile as
+bytes arrive (first at 64KB, then at growing thresholds) and the transfer is
+aborted as soon as the answer is final — typically after the first 64KB.
+Early answers are only trusted when more data cannot change them:
+
+- "not animated" is reported only from the complete file, because a truncated
+  animation undercounts frames; "animated" is final as soon as a second frame
+  is seen
+- SVG metadata always downloads the whole document, so the SVG parser's total
+  size cap keeps its meaning
+- a probe failure on a prefix just means the download continues; a file that
+  never yields an early answer is downloaded and validated exactly like a
+  `fetch_remote` download
+
+`fetch_remote` and `remote_dominant_color` need the complete body and always
+download it (up to `max_bytes`).
 
 Remote fetching is deliberately conservative:
 
@@ -392,9 +415,14 @@ Remote fetching is deliberately conservative:
 - private, loopback, link-local, multicast, documentation, benchmarking,
   carrier-grade NAT, IPv4-mapped IPv6, NAT64, 6to4/Teredo, and other
   special-use resolved addresses are rejected by default
-- no image decoding happens directly from the socket
+- no image decoding happens directly from the socket; probes only ever see the
+  on-disk tempfile
 - the final response `Content-Type` must be an allowed image type and must agree
-  with an image-looking URL extension when one is present
+  with an image-looking URL extension when one is present — both are enforced
+  from the response headers, before any body bytes are downloaded
+- the first bytes of the body must be compatible with the claimed format's
+  magic bytes (SVG, which has no signature, is exempt); an obviously mislabeled
+  body is dropped after the first chunk instead of being downloaded to the cap
 - downloaded content is probed before `fetch_remote` yields the tempfile, so the
   raw downloader cannot be used as a blind extension-based file saver
 - SVG remote metadata uses the same bounded SVG metadata parser after download;
@@ -461,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(...)`
 
@@ -499,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`.
@@ -555,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:
@@ -574,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")`
@@ -633,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.
@@ -651,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:
@@ -668,6 +700,14 @@ JPEG path:
 - uses `jpegoptim`
 - `quality:` maps to `jpegoptim --max`
 - metadata is stripped unless `strip_metadata: false`
+- an EXIF-oriented JPEG is uprighted first with jpegtran's lossless
+  transforms, because stripping would otherwise delete the orientation tag
+  without applying the rotation and ship the image sideways. MCU-aligned
+  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 the output is
+  not written; with `strict: false`, the original bytes are copied to `output:`.
 
 PNG path:
 
@@ -676,44 +716,18 @@ PNG path:
   then `oxipng`
 
 When `strict: true`, missing optimizer tools raise. When `strict: false`, missing
-optimizer tools are tolerated.
-
-### SVG sanitising
-
-#### `SafeImage.sanitize_svg!(path)`
-
-Sanitises an SVG in place using a small REXML allowlist.
-
-```ruby
-result = SafeImage.sanitize_svg!("icon.svg")
-puts result[:sanitized]
-```
+optimizer tools are tolerated and the output is still written from the source
+copy when possible.
 
-The sanitizer removes unsafe elements/attributes such as scripts and event
-handlers. It is intentionally conservative rather than a full browser-grade SVG
-implementation.
+### SVG handling
 
-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.
-
-### 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
 
@@ -730,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
@@ -752,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
@@ -780,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!
@@ -804,46 +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. Network syscalls are denied
-through the Landlock helper's seccomp layer. Worker processes inherit the
-parent's backend and pixel-ceiling configuration; landlock is forced off
-inside the worker so sandboxed operations never nest.
+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
 ```
@@ -855,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