safe_image 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e078245fa2e4fb0707b0d477ad0c4b41f31423905ed0dc84f964cd648a5a032f
-  data.tar.gz: 9155876c2761ac9c6afb2b4da4a97af8b6b7e035ffee553c72dacda6166c1048
+  metadata.gz: ce9a76b504fa826aef4164c5748c800a95828ef7fda6bda3a00e7e85f0134f38
+  data.tar.gz: 61c5ebac14806e8e3445c3e7aa73bb1ab5191cc414e1af311b752ad0be492bc7
 SHA512:
-  metadata.gz: 2f98d64d3b9665a156c27cbcef898cd148e6b559c73c03ba757b1147d2e47f1733d5a6e0ebc7d5c038cb989f874d67747175cd1d094cdf9677f98550cfe635be
-  data.tar.gz: ae1008885bf83da844145369cd929edd12c0af238fd0d975e2c078ef95b4d7cc301f1fed2da5cdd815d520591938acc144a2bd79d4bd2573336a2c9eb1078e5b
+  metadata.gz: 5d15f34ca4de05f1ca4618695bc3993a000ce38a7de54afde86ac87497c0288ad0ed37493ca31431669341be10991bbcdb5192796ea6bdb3af016943adfac2bc
+  data.tar.gz: e71a59800452d4d396741e4e28134c47403490100233e803644a90a0ca967abd74fb5572a936a7af247411cb2055378982bccad89085085184aa92c66ca94d0d

data/CHANGELOG.md

@@ -5,6 +5,199 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0 - 2026-06-12]
+
+### Changed (breaking)
+
+- **`sanitize_svg!` now requires `id_namespace:`.** The argument forces a
+  deliberate choice of where the output may be used, removing the footgun of a
+  silently-wrong default. Pass `:standalone` for output served only as an
+  external `<img>`/CSS-url/file, or a stable per-document String to make it safe
+  to inline (see below). Omitting it (or passing `nil`/`""`) raises
+  `ArgumentError`. Callers must update: `sanitize_svg!(path)` →
+  `sanitize_svg!(path, id_namespace: :standalone)`.
+
+### Added
+
+- **`sanitize_svg!` can produce output safe to inline into an HTML DOM.** Pass
+  `id_namespace:` a stable per-document value (e.g. the upload sha) and the
+  sanitizer prefixes every `id` and every reference to it (`href`/`xlink:href`
+  fragments, `url(#…)` in attributes and CSS, ARIA IDREF attributes like
+  `aria-labelledby`/`aria-controls`, and every `class` token plus the matching
+  `.class` selectors) with the namespace, and scopes every `<style>` selector
+  under a `<ns>-scope` class added to the root `<svg>`. Namespacing classes stops
+  an inlined SVG from invoking the host page's framework CSS (a bare
+  `class="modal fixed"` overlay vector). `var()`/`env()`/`attr()` in presentation
+  attributes are rejected outright — they resolve against the host page.
+  Inlined into a page, the preserved `<style>` can no longer reach the host
+  cascade (`*{visibility:hidden}`, `#header{display:none}`) and ids cannot
+  clobber host ids — including references written `URL(#x)`, `url('#x')`, or
+  `url("#x")`, which are namespaced like the unquoted form. In this mode the root
+  `<svg>`'s `overflow` is also dropped so it clips to its declared viewport (a
+  tiny viewport with `overflow:visible` and oversized content would otherwise
+  paint a full-page overlay). With `id_namespace: :standalone` the output is the
+  document-safe form (no namespacing). The namespace must be a valid ident (a
+  letter followed by letters/digits/`_`/`-`); malformed tokens are rejected
+  rather than coerced, so two distinct values can never collapse to one. The
+  transform is idempotent per namespace. `style=""` attributes are
+  element-scoped and inline-safe either way.
+- **`<style>` elements now fail closed on any at-rule.** Previously an at-rule
+  block followed by a valid rule (`@font-face{…}.ok{…}`) could keep the trailing
+  rule; a stylesheet containing `@` anywhere is now rejected whole, matching the
+  documented guarantee.
+- **The SVG sanitizer keeps a safe CSS subset instead of stripping all CSS.**
+  `style` attributes (as written by Inkscape) and `<style>` elements (as
+  written by Illustrator) now survive sanitisation when they parse against a
+  constructed allowlist grammar: properties mirroring the allowed
+  presentation attributes, type/class/id selectors, numeric/keyword/color
+  values, and `url(#fragment)` references only. Output is reassembled from
+  validated tokens — CSS escapes, quotes/strings, at-rules, comments, and
+  unknown properties, functions, or selectors drop the declaration, rule, or
+  whole stylesheet rather than being interpreted. A single at-rule or nested
+  block fails the whole `<style>` element closed. `!important` and modern
+  `rgb()/hsl()` slash-alpha (`rgb(R G B / A)`) are preserved; both are parsed
+  structurally and re-emitted, and admitting `/` for the alpha keeps CSS
+  comments impossible because `*` remains excluded from the value charset.
+- **The presentation-attribute allowlist covers common editor output.** Added
+  the safe, widely-emitted SVG presentation properties (and their CSS twins):
+  `stroke-dasharray`/`stroke-dashoffset`, `vector-effect`, `marker`/`marker-*`
+  (with the `<marker>` element and its geometry attributes), `color`,
+  `display`/`visibility`/`overflow`, `paint-order`/`mix-blend-mode`/`isolation`,
+  the `*-rendering` hints, and the longhand text properties (`font-style`,
+  `font-variant`, `font-stretch`, `text-decoration`, `letter-spacing`,
+  `word-spacing`, `dominant-baseline`, `baseline-shift`, `writing-mode`,
+  `direction`). The only additions carrying a URL — `marker*` — are constrained
+  to `url(#fragment)` like the existing paint and clip/mask references. Filters
+  remain out of scope.
+
+### Changed
+
+- **Sandboxed operations are served by a pool of resident zygote workers —
+  warm Landlock overhead drops from ~100ms to ~3–8ms per operation, with
+  near-linear concurrency.** Previously every sandboxed call exec'd a fresh
+  Ruby that re-paid interpreter boot, rubygems, the gem's requires, and
+  libvips init. A zygote boots that once, then forks a child per operation;
+  the child applies rlimits, its per-operation Landlock policy (filesystem
+  allowlist, all TCP denied on 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
+  (blocking sockets of every family, closing the UDP gap the in-process
+  Landlock policy alone leaves open), *before* touching untrusted input, and
+  exits after the operation. Workers are pooled so N threads run N sandboxed
+  operations at once (the single zygote would serialise them): the pool grows
+  on demand to `SAFE_IMAGE_ZYGOTE_WORKERS` (default 8) and offered concurrency
+  past the cap blocks until a worker frees, bounding concurrent libvips
+  memory. An idle worker exits after `Zygote::IDLE_SECONDS` (300, overridable
+  via `SAFE_IMAGE_ZYGOTE_IDLE_SECONDS`; idling holds ~16MB private memory and
+  no CPU), exits immediately when its parent process does, and `configure!`
+  always retires the pool, so no stale process outlives its parent or a
+  reconfigure. Forking is sound because the zygote never runs operations
+  itself: libvips is initialised but quiescent (zero native threads) at every
+  fork — verified empirically. Outputs are byte-identical to both the exec
+  worker and unsandboxed operation. `SAFE_IMAGE_ZYGOTE=0` falls back to the
+  exec-per-operation worker. Pool correctness under concurrent reconfigure,
+  worker death, and fork is enforced by a per-worker generation token (a
+  worker checked out when `configure!` lands is retired on return, never
+  reused under stale config), channel-health (not process-liveness) reuse
+  decisions (a worker whose pipe broke is discarded, never re-pooled), a
+  `PR_SET_PDEATHSIG` so an operation child dies with its zygote, and
+  parent-side tmp-root cleanup that survives a SIGKILLed worker — all
+  exercised by a multithreaded chaos stress test (reconfigure + worker kills)
+  asserting no wrong output, no process/fd/tmpdir leak, and no deadlock.
+
+- **External tools run with `MALLOC_ARENA_MAX=2`.** Multithreaded optimizer
+  tools (oxipng's rayon pool, ImageMagick's OpenMP) otherwise have glibc
+  reserve a 64MB malloc arena per thread; combined with the sandbox's
+  `RLIMIT_AS` memory cap, that *address-space* reservation spuriously fails
+  the tool under concurrency even though real memory use is tiny. Bounding the
+  arena count is the standard mitigation and is free for these compute-bound
+  tools. Found by stress-testing concurrent sandboxed `convert`.
+
+- **rexml loads on first SVG use instead of at `require "safe_image"`.**
+  rexml costs ~27ms to parse and only the SVG paths need it, so every boot of
+  the gem — and in particular every Landlock sandbox worker, which is a fresh
+  Ruby process per operation — was paying it on operations that never touch
+  SVG. Measured per-op sandbox cost drops from ~102ms to ~85ms on the vips
+  backend and ~75ms to ~58ms on the imagemagick backend.
+
+- **Remote fetches reject bad responses from the headers alone.** The
+  `Content-Type` allowlist and content-type/extension agreement checks now run
+  before any body bytes are read (previously the body was downloaded first and
+  rejected afterwards), and the first bytes of the body must be compatible
+  with the claimed format's magic bytes — an obviously mislabeled body is
+  dropped after the first chunk instead of being downloaded to `max_bytes`.
+- **Remote metadata helpers download only what the answer needs.**
+  `remote_size`, `remote_type`, `remote_info` and `remote_animated?` now probe
+  the partially-downloaded file at growing thresholds (64KB, 256KB, ...) and
+  abort the transfer once the answer is final, instead of always downloading
+  up to `max_bytes`. Early answers are only trusted when more data cannot
+  change them: "not animated" still requires the complete file (truncated
+  animations undercount frames), SVG metadata still downloads the whole
+  document so the SVG size cap keeps its meaning, and any prefix probe
+  failure falls back to the full download with unchanged validation and
+  error behaviour. `fetch_remote` and `remote_dominant_color` still download
+  the complete body.
+
+### Fixed
+
+- **Lossy PNG optimisation no longer fails when pngquant declines to
+  quantise.** pngquant signals "quantised result not used" through exit
+  status 98 (`--skip-if-larger`) and 99 (`--quality` not met) — for example
+  on low-bit-depth grayscale PNGs its RGBA-palette output cannot beat —
+  and `optimize(mode: :lossy)` raised `CommandError` instead of keeping the
+  original and continuing to oxipng. Found by running 10 random Wikimedia
+  Commons images through the optimizer.
+
+- **`optimize` no longer ships sideways JPEGs.** With `strip_metadata: true`
+  (the default), stripping deleted the EXIF orientation tag without applying
+  the rotation, so an oriented camera photo came out rendered 90/180° wrong.
+  `optimize` now bakes the rotation into the pixels first via jpegtran's
+  lossless transforms: `-perfect` when the dimensions are MCU-aligned, else
+  `-trim`, which drops the partial edge blocks (under one MCU, at most 15px)
+  instead of hiding a lossy re-encode. The result hash gains `rotated_from:`
+  and `trimmed:` so the trim is reported, never silent — image_optim's jhead
+  worker (Discourse's `FileHelper.optimize_image!`) does the same transform
+  but trims silently. Without jpegtran an oriented JPEG raises in strict mode
+  and is left untouched otherwise; reading the tag goes through the configured
+  backend, so `optimize` now also enforces the pixel cap before touching an
+  oriented JPEG. Internal callers optimising output the gem just encoded skip
+  the check (`assume_upright:`).
+
+- **JPEGs with an EXIF orientation no longer fail on the libvips path once
+  they outgrow the sequential readahead window (~512px — every real camera
+  photo).** `resize`, `crop`, `convert`/`convert_to_jpeg` and the
+  `fix_orientation` re-encode tier loaded input with `access: sequential` and
+  then autorotated, and the rotation's out-of-order row reads raised
+  `VipsJpeg: out of order read`. Oriented images are now reloaded with random
+  access before autorotation; upright images keep the streaming sequential
+  load, and the pixel cap still runs before any decode.
+
+### Security
+
+- **Presentation-attribute `url()` references fail closed unless they are a
+  canonical same-document fragment.** A single validation/rewrite grammar now
+  governs both the keep decision and the namespace rewrite, so external URLs,
+  mismatched quotes, and unterminated forms (`url(#id`, `url(http://evil`) are
+  dropped rather than kept on browser parse-error leniency — and no bare,
+  un-namespaced reference can survive in inline (`id_namespace:` String) output.
+- **Attribute values containing CSS escapes are rejected outright.**
+  Browsers feed SVG presentation attributes through their CSS value parsers,
+  where an escape can re-form a token after the sanitizer's pattern checks
+  (`ur\6c(...)` is `url(...)`). No allowlisted attribute legitimately
+  contains a backslash, so any attribute value with one is now dropped.
+- **SVG parsing rejects encodings the byte-level guards cannot see through.**
+  The DOCTYPE/processing-instruction guards are ASCII byte scans; a UTF-16
+  document interleaves NUL bytes between the ASCII characters, so a
+  `<!DOCTYPE` (and an entity payload behind it) could slip past them while
+  REXML still decoded and honoured it. SVG documents must now be UTF-8 (BOM
+  allowed) or declare a single-byte ASCII-transparent charset (US-ASCII,
+  ISO-8859-*, Windows-125x): UTF-16/32 BOMs, embedded NUL bytes, and declared
+  multi-byte or transforming encodings (Shift_JIS, GBK, EUC-*, ISO-2022-*,
+  UTF-7) raise `InvalidImageError`. Declared names that fit the allowed shape
+  but resolve to no real encoding (e.g. `utf8`, `windows-1259`) also fail
+  closed as `InvalidImageError` instead of surfacing REXML's bare
+  `ArgumentError`.
+
 ## [0.2.0] - 2026-06-10
 
 The host's whole image-processing posture is now decided in one place, once,

data/README.md

@@ -142,7 +142,7 @@ sudo pacman -S --needed libvips \
 | `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 (left untouched otherwise) |
 | `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 |
@@ -228,7 +228,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)
 }
 ```
 
@@ -367,8 +369,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 +412,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;
@@ -668,6 +693,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 is left
+  untouched otherwise — never stripped sideways.
 
 PNG path:
 
@@ -680,19 +713,56 @@ optimizer tools are tolerated.
 
 ### SVG sanitising
 
-#### `SafeImage.sanitize_svg!(path)`
+#### `SafeImage.sanitize_svg!(path, id_namespace:)`
 
-Sanitises an SVG in place using a small REXML allowlist.
+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
-result = SafeImage.sanitize_svg!("icon.svg")
+# 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
 restrictive `Content-Security-Policy`, `X-Content-Type-Options: nosniff`, and/or
@@ -700,6 +770,63 @@ 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:
@@ -834,11 +961,39 @@ 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
+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.
+
 ## Development
 
 ```bash

data/lib/safe_image/discourse_compat.rb

@@ -182,7 +182,7 @@ module SafeImage
       format = File.extname(output).delete_prefix(".").downcase
       format = "jpg" if format == "jpeg"
       return unless Processor::OPTIMIZABLE_OUTPUTS.include?(format)
-      Optimizer.optimize(output, mode: :lossless, strip_metadata: true, quality: quality)
+      Optimizer.optimize(output, mode: :lossless, strip_metadata: true, quality: quality, assume_upright: true)
     end
 
     # JPEG default when the caller passes no quality: matches what ImageMagick
@@ -264,17 +264,6 @@ module SafeImage
       convert(from, to, format: "jpg", quality: quality, optimize: optimize, max_pixels: max_pixels, chroma_subsampling: chroma_subsampling)
     end
 
-    # EXIF orientation values mapped onto jpegtran's lossless transforms.
-    JPEGTRAN_OPERATIONS = {
-      2 => ["-flip", "horizontal"],
-      3 => ["-rotate", "180"],
-      4 => ["-flip", "vertical"],
-      5 => ["-transpose"],
-      6 => ["-rotate", "90"],
-      7 => ["-transverse"],
-      8 => ["-rotate", "270"]
-    }.freeze
-
     def fix_orientation(from, to = from, max_pixels: nil, quality: nil)
       max_pixels = SafeImage.resolved_max_pixels(max_pixels)
       output = PathSafety.ensure_safe_output_path!(to).to_s
@@ -323,7 +312,7 @@ module SafeImage
     def jpegtran_fix_orientation(input, output, orient)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       info = write_through_tempfile(output) do |tmp_path|
-        Runner.run!(["jpegtran", "-copy", "none", "-perfect", *JPEGTRAN_OPERATIONS.fetch(orient), "-outfile", tmp_path, input])
+        Runner.run!(["jpegtran", "-copy", "none", "-perfect", *Optimizer::JPEGTRAN_OPERATIONS.fetch(orient), "-outfile", tmp_path, input])
         Native.probe(tmp_path)
       end
       result_from_info(

data/lib/safe_image/ico.rb

@@ -3,7 +3,7 @@
 require "tempfile"
 
 module SafeImage
-  # Pure-Ruby ICO container support, in the spirit of the REXML SVG path:
+  # Pure-Ruby ICO container support, in the spirit of the SVG metadata path:
   # the directory and legacy DIB payloads are parsed in memory-safe Ruby with
   # explicit bounds checks, and pixel encoding is delegated to the hardened
   # native libvips helpers. ImageMagick is never involved.

data/lib/safe_image/native.rb

@@ -45,17 +45,18 @@ module SafeImage
         out_format = output_format!(format)
 
         VipsGlue.with_images do |track|
-          # Header read through the explicit loader: validates the bytes and
-          # enforces the pixel cap before any full decode.
-          header, input_format = load_image(track, input)
-          check_pixels!(header, max_pixels)
+          # Route through the explicit loader for the path's extension and keep
+          # the resulting image object for the resize. Do not call the generic
+          # filename-based `thumbnail` operation here: it re-sniffs the path and
+          # can observe different bytes if a hostile local path is replaced
+          # between the header check and the decode.
+          image, input_format = load_image(track, input, autorotate: true)
+          check_pixels!(image, max_pixels)
 
-          # Thumbnail from the file so libvips can shrink on load (e.g.
-          # libjpeg DCT downscaling); auto-rotates by default.
           thumb = track.call(
             VipsGlue.operation(
-              "thumbnail",
-              { filename: input, width: width, height: height,
+              "thumbnail_image",
+              { in: image, width: width, height: height,
                 size: "both", crop: "centre", fail_on: "error" }
             )
           )
@@ -75,7 +76,7 @@ module SafeImage
         out_format = output_format!(format)
 
         VipsGlue.with_images do |track|
-          image, input_format = load_image(track, String(input))
+          image, input_format = load_image(track, String(input), autorotate: true)
           check_pixels!(image, max_pixels)
           rotated = track.call(VipsGlue.operation("autorot", { in: image }))
           resized = track.call(VipsGlue.operation("resize", { in: rotated, scale: scale }))
@@ -94,7 +95,7 @@ module SafeImage
         out_format = output_format!(format)
 
         VipsGlue.with_images do |track|
-          image, input_format = load_image(track, String(input))
+          image, input_format = load_image(track, String(input), autorotate: true)
           check_pixels!(image, max_pixels)
           rotated = track.call(VipsGlue.operation("autorot", { in: image }))
 
@@ -116,7 +117,7 @@ module SafeImage
         out_format = output_format!(format)
 
         VipsGlue.with_images do |track|
-          image, input_format = load_image(track, String(input))
+          image, input_format = load_image(track, String(input), autorotate: true)
           check_pixels!(image, max_pixels)
           rotated = track.call(VipsGlue.operation("autorot", { in: image }))
 
@@ -306,7 +307,7 @@ module SafeImage
         raise ArgumentError, "quality must be 1..100" unless (1..100).cover?(quality)
       end
 
-      def load_image(track, path)
+      def load_image(track, path, autorotate: false)
         format = normalized_format(File.extname(path).delete_prefix("."))
         raise UnsupportedFormatError, "unsupported input format" unless format
 
@@ -319,9 +320,17 @@ module SafeImage
           raise UnsupportedFormatError, "this libvips build has no JPEG XL loader" unless VipsGlue.type_find?("jxlload")
         end
 
-        image = track.call(
-          VipsGlue.operation(LOADERS.fetch(format), { filename: path, access: "sequential", fail_on: "error" })
-        )
+        options = { filename: path, access: "sequential", fail_on: "error" }
+        image = track.call(VipsGlue.operation(LOADERS.fetch(format), options))
+
+        # autorot flips/rotates pull rows out of input order, which a
+        # sequential source can only serve while the image fits its readahead
+        # window (~512px); larger oriented images fail with "out of order
+        # read". Reload those with random access — the open itself is
+        # header-only, so the caller's pixel cap still runs before any decode.
+        if autorotate && VipsGlue.orientation(image) > 1
+          image = track.call(VipsGlue.operation(LOADERS.fetch(format), options.merge(access: "random")))
+        end
         [image, format]
       end