safe_image 0.1.0 → 0.2.0

data/SECURITY.md

@@ -4,7 +4,7 @@ Safe Image is a hardened image-processing boundary for untrusted uploads, not a
 
 ## Supported versions
 
-Security fixes are expected to land on `main` until the gem has tagged releases. Once releases exist, report against the latest released version unless you can reproduce on `main` as well.
+Only the latest released gem version is supported; security fixes land on `main` and ship as the next release. Report against the latest released version unless you can reproduce on `main` as well.
 
 ## Threat model
 
@@ -13,24 +13,44 @@ Safe Image assumes image input may be attacker-controlled. The library is design
 - shell-free external command execution using argv arrays
 - allowlisted command environment
 - bounded command output and process-group timeout cleanup
-- explicit libvips loader selection for supported raster formats
-- no silent fallback from libvips to generic ImageMagick decoding
+- explicit libvips loader selection for supported raster formats, with
+  libvips' untrusted-operation block enabled and the ImageMagick loader
+  classes blocked by name
+- a runtime libvips binding (Fiddle) that exposes only the specific
+  operations the gem invokes — there is no generic operation access
+- no silent fallback from libvips to generic ImageMagick decoding; the
+  backend is a single explicit `SafeImage.configure!` decision and formats it
+  cannot decode fail closed
+- decompression-bomb ceilings enforced from container/header metadata before
+  any pixel decode (128MP default, plus dedicated SVG and ICO caps)
 - restrictive ImageMagick policy disabling delegates, filters, `@file`, remote URL coders, Ghostscript-backed formats, and dangerous pseudo-formats
+- risky container formats parsed in memory-safe Ruby rather than C: SVG
+  (bounded REXML metadata and allowlist sanitising) and ICO (bounds-checked
+  directory/DIB parsing); extracted pixels are re-encoded through libvips and
+  embedded payload bytes are never copied through verbatim
+- letter avatar text rendering escapes the user-derived glyph before Pango
+  markup parsing, and fonts come from an allowlist (the default font is
+  bundled with the gem)
 - symlink rejection for untrusted local input/output paths
 - remote fetch SSRF hardening: scheme/port restrictions, special-use IP blocking, DNS pinning, redirect limits, HTTPS-to-HTTP rejection, header allowlists, content-type/extension agreement, and probe-before-yield
-- bounded SVG metadata parsing and conservative SVG sanitising without handing SVG to ImageMagick for probing
 - optional Linux Landlock/seccomp subprocess sandboxing
 
+One deliberate exception to libvips' untrusted-operation block: the libjxl
+loader and saver are re-enabled because JPEG XL is part of the supported
+input surface. JXL inputs still pass extension routing, the pixel cap, and
+(optionally) the Landlock sandbox, but libjxl does parse attacker-controlled
+bytes in-process like the other raster decoders below.
+
 ## Non-goals
 
-Safe Image does not claim that parsing hostile images in-process is memory-safe. Raster decoders such as libjpeg, libpng, libwebp, libheif, libvips loaders, and ImageMagick coders still parse attacker-controlled bytes. A decoder memory-corruption bug or pathological resource-consumption bug is still possible.
+Safe Image does not claim that parsing hostile images in-process is memory-safe. Raster decoders such as libjpeg, libpng, libwebp, libheif, libjxl, libnsgif, libvips loaders, and ImageMagick coders still parse attacker-controlled bytes. A decoder memory-corruption bug or pathological resource-consumption bug is still possible.
 
 The honest claim is defense-in-depth:
 
 - without Landlock: centralized and hardened image processing with major delegate/protocol/policy foot-guns removed
 - with Landlock: the same hardening plus a kernel containment boundary around subprocess-based public operations
 
-If your deployment needs a hard isolation boundary, enable sandbox execution and run image processing away from your main web worker process.
+If your deployment needs a hard isolation boundary, configure `landlock: true` and run image processing away from your main web worker process.
 
 ## Reporting vulnerabilities
 
@@ -40,7 +60,7 @@ Include:
 
 - affected version or commit
 - input file or minimized reproducer, if shareable
-- operation/API called
+- operation/API called and the backend in use (libvips, ImageMagick, cjpegli)
 - expected vs actual result
 - whether Landlock sandboxing was enabled
 - host OS, kernel, libvips, ImageMagick, and optimizer tool versions

data/lib/safe_image/discourse_compat.rb

@@ -6,27 +6,37 @@ require "tempfile"
 
 module SafeImage
   # Compatibility-shaped API for the operations Discourse currently performs in
-  # OptimizedImage, UploadCreator, ShrinkUploadedImage and FileHelper.
+  # OptimizedImage, UploadCreator, ShrinkUploadedImage and FileHelper. The
+  # backend is decided once by SafeImage.configure!; these methods only
+  # dispatch to it.
   module DiscourseCompat
     module_function
 
-    def resize(from, to, width, height, quality: nil, backend: :imagemagick, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)
-      if backend.to_sym == :vips
-        return SafeImage.thumbnail(
-          input: from,
-          output: to,
-          width: width,
-          height: height,
-          quality: quality || 85,
-          backend: backend,
-          optimize: optimize,
-          max_pixels: max_pixels,
-          encoder: encoder,
-          chroma_subsampling: chroma_subsampling
-        )
+    def resize(from, to, width, height, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)
+      max_pixels = SafeImage.resolved_max_pixels(max_pixels)
+      case SafeImage.config.backend
+      when :vips
+        vips_resize(from, to, width, height, quality: quality, optimize: optimize, max_pixels: max_pixels, chroma_subsampling: chroma_subsampling)
+      when :imagemagick
+        imagemagick_resize(from, to, width, height, quality: quality, optimize: optimize, max_pixels: max_pixels)
       end
+    end
 
-      probe = compat_probe(from, backend: :imagemagick, max_pixels: max_pixels)
+    def vips_resize(from, to, width, height, quality:, optimize:, max_pixels:, chroma_subsampling:)
+      SafeImage.thumbnail(
+        input: from,
+        output: to,
+        width: width,
+        height: height,
+        quality: quality || 85,
+        optimize: optimize,
+        max_pixels: max_pixels,
+        chroma_subsampling: chroma_subsampling
+      )
+    end
+
+    def imagemagick_resize(from, to, width, height, quality:, optimize:, max_pixels:)
+      probe = compat_probe(from, max_pixels: max_pixels)
       output = PathSafety.ensure_safe_output_path!(to).to_s
       info = ImageMagickBackend.thumbnail(
         input: probe.input,
@@ -36,17 +46,27 @@ module SafeImage
         format: File.extname(output).delete_prefix(".").downcase,
         quality: quality
       )
-      Optimizer.optimize(output, mode: :lossless, strip_metadata: true, quality: quality) if optimize
+      optimize_output(output, quality) if optimize
       result_from_info(probe.input, output, info, "imagemagick")
     end
 
-    def crop(from, to, width, height, quality: nil, backend: :imagemagick, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)
-      probe = compat_probe(from, backend: backend, max_pixels: max_pixels)
+    def crop(from, to, width, height, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)
+      max_pixels = SafeImage.resolved_max_pixels(max_pixels)
+      case SafeImage.config.backend
+      when :vips
+        vips_crop(from, to, width, height, quality: quality, optimize: optimize, max_pixels: max_pixels, chroma_subsampling: chroma_subsampling)
+      when :imagemagick
+        imagemagick_crop(from, to, width, height, quality: quality, optimize: optimize, max_pixels: max_pixels)
+      end
+    end
+
+    def vips_crop(from, to, width, height, quality:, optimize:, max_pixels:, chroma_subsampling:)
+      probe = compat_probe(from, max_pixels: max_pixels)
       output = PathSafety.ensure_safe_output_path!(to).to_s
       format = File.extname(output).delete_prefix(".").downcase
 
       info =
-        if backend.to_sym == :vips && use_jpegli_for_generated_jpeg?(format, backend, encoder)
+        if use_jpegli_for_generated_jpeg?(format)
           with_temp_png(output) do |tmp_path|
             VipsBackend.crop_north(
               input: probe.input,
@@ -65,7 +85,7 @@ module SafeImage
               input_format: probe.input_format
             )
           end
-        elsif backend.to_sym == :vips
+        else
           VipsBackend.crop_north(
             input: probe.input,
             output: output,
@@ -75,27 +95,43 @@ module SafeImage
             quality: quality || 85,
             max_pixels: max_pixels
           )
-        else
-          ImageMagickBackend.resize_like(
-            input: probe.input,
-            output: output,
-            width: width,
-            height: height,
-            format: format,
-            quality: quality,
-            crop: :north
-          )
         end
-      Optimizer.optimize(output, mode: :lossless, strip_metadata: true, quality: quality) if optimize
-      result_from_info(probe.input, output, info, compat_backend_name(backend, info))
+      optimize_output(output, quality) if optimize
+      result_from_info(probe.input, output, info, compat_backend_name(:vips, info))
+    end
+
+    def imagemagick_crop(from, to, width, height, quality:, optimize:, max_pixels:)
+      probe = compat_probe(from, max_pixels: max_pixels)
+      output = PathSafety.ensure_safe_output_path!(to).to_s
+      info = ImageMagickBackend.resize_like(
+        input: probe.input,
+        output: output,
+        width: width,
+        height: height,
+        format: File.extname(output).delete_prefix(".").downcase,
+        quality: quality,
+        crop: :north
+      )
+      optimize_output(output, quality) if optimize
+      result_from_info(probe.input, output, info, "imagemagick")
     end
 
-    def downsize(from, to, dimensions, backend: :imagemagick, optimize: true, max_pixels: nil, quality: 85, encoder: :auto, chroma_subsampling: :auto)
-      probe = compat_probe(from, backend: backend, max_pixels: max_pixels)
+    def downsize(from, to, dimensions, optimize: true, max_pixels: nil, quality: 85, chroma_subsampling: :auto)
+      max_pixels = SafeImage.resolved_max_pixels(max_pixels)
+      case SafeImage.config.backend
+      when :vips
+        vips_downsize(from, to, dimensions, quality: quality, optimize: optimize, max_pixels: max_pixels, chroma_subsampling: chroma_subsampling)
+      when :imagemagick
+        imagemagick_downsize(from, to, dimensions, optimize: optimize, max_pixels: max_pixels)
+      end
+    end
+
+    def vips_downsize(from, to, dimensions, quality:, optimize:, max_pixels:, chroma_subsampling:)
+      probe = compat_probe(from, max_pixels: max_pixels)
       output = PathSafety.ensure_safe_output_path!(to).to_s
       format = File.extname(output).delete_prefix(".").downcase
       info =
-        if backend.to_sym == :vips && use_jpegli_for_generated_jpeg?(format, backend, encoder)
+        if use_jpegli_for_generated_jpeg?(format)
           with_temp_png(output) do |tmp_path|
             VipsBackend.downsize(
               input: probe.input,
@@ -113,7 +149,7 @@ module SafeImage
               input_format: probe.input_format
             )
           end
-        elsif backend.to_sym == :vips
+        else
           VipsBackend.downsize(
             input: probe.input,
             output: output,
@@ -122,59 +158,89 @@ module SafeImage
             quality: quality,
             max_pixels: max_pixels
           )
-        else
-          ImageMagickBackend.downsize(
-            input: probe.input,
-            output: output,
-            dimensions: dimensions,
-            format: format
-          )
         end
-      Optimizer.optimize(output, mode: :lossless, strip_metadata: true) if optimize
-      result_from_info(probe.input, output, info, compat_backend_name(backend, info))
+      optimize_output(output, nil) if optimize
+      result_from_info(probe.input, output, info, compat_backend_name(:vips, info))
+    end
+
+    def imagemagick_downsize(from, to, dimensions, optimize:, max_pixels:)
+      probe = compat_probe(from, max_pixels: max_pixels)
+      output = PathSafety.ensure_safe_output_path!(to).to_s
+      info = ImageMagickBackend.downsize(
+        input: probe.input,
+        output: output,
+        dimensions: dimensions,
+        format: File.extname(output).delete_prefix(".").downcase
+      )
+      optimize_output(output, nil) if optimize
+      result_from_info(probe.input, output, info, "imagemagick")
+    end
+
+    # Post-processing applies only to the formats the optimizer tools
+    # understand; other outputs (gif, jxl, ...) skip the pass.
+    def optimize_output(output, quality)
+      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)
     end
 
-    def convert(from, to, format:, quality: nil, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)
-      probe = compat_probe(from, backend: :imagemagick, max_pixels: max_pixels)
+    # JPEG default when the caller passes no quality: matches what ImageMagick
+    # uses for sources without quality tables, rather than libvips' Q75.
+    NATIVE_CONVERT_DEFAULT_QUALITY = 92
+
+    def convert(from, to, format:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)
+      max_pixels = SafeImage.resolved_max_pixels(max_pixels)
       output = PathSafety.ensure_safe_output_path!(to).to_s
+
+      case SafeImage.config.backend
+      when :vips
+        native_convert(from, output, format: format, quality: quality, optimize: optimize, max_pixels: max_pixels, chroma_subsampling: chroma_subsampling)
+      when :imagemagick
+        imagemagick_convert(from, output, format: format, quality: quality, optimize: optimize, max_pixels: max_pixels)
+      end
+    end
+
+    def imagemagick_convert(from, output, format:, quality:, optimize:, max_pixels:)
+      probe = compat_probe(from, max_pixels: max_pixels)
       normalized_format = format.to_s.downcase == "jpeg" ? "jpg" : format.to_s.downcase
+      info = ImageMagickBackend.convert(input: probe.input, output: output, format: format, quality: quality)
+      optimize_output(output, normalized_format == "jpg" ? quality : nil) if optimize
+      result_from_info(probe.input, output, info, "imagemagick")
+    end
 
-      info =
-        if use_jpegli_for_convert?(probe.input, normalized_format, encoder)
-          JpegliBackend.convert(
-            input: probe.input,
-            output: output,
-            quality: quality || JpegliBackend::DEFAULT_QUALITY,
-            chroma_subsampling: chroma_subsampling
-          )
-        else
-          if encoder.to_sym == :cjpegli
-            raise UnsupportedFormatError, "cjpegli cannot directly encode #{File.extname(probe.input).delete_prefix(".").downcase.inspect}; use encoder: :auto or another encoder"
-          end
-          ImageMagickBackend.convert(input: probe.input, output: output, format: format, quality: quality)
-        end
+    def native_convert(from, output, format:, quality:, optimize:, max_pixels:, chroma_subsampling:)
+      input = PathSafety.ensure_regular_file!(from).to_s
+      normalized_format = format.to_s.downcase == "jpeg" ? "jpg" : format.to_s.downcase
+
+      if use_jpegli_for_convert?(input, normalized_format)
+        info = JpegliBackend.convert(
+          input: input,
+          output: output,
+          quality: quality || JpegliBackend::DEFAULT_QUALITY,
+          chroma_subsampling: chroma_subsampling
+        )
+        return result_from_info(input, output, info, "cjpegli")
+      end
 
-      Optimizer.optimize(output, mode: :lossless, strip_metadata: true, quality: normalized_format == "jpg" ? quality : nil) if optimize && info[:encoder] != "cjpegli"
-      result_from_info(probe.input, output, info, info[:encoder] == "cjpegli" ? "cjpegli" : "imagemagick")
+      info = write_through_tempfile(output) do |tmp_path|
+        Native.convert(input, tmp_path, normalized_format, quality || NATIVE_CONVERT_DEFAULT_QUALITY, max_pixels)
+      end
+      optimize_output(output, normalized_format == "jpg" ? quality : nil) if optimize
+      result_from_info(input, output, info, "libvips-direct")
     end
 
-    def use_jpegli_for_convert?(input, normalized_format, encoder)
-      encoder = encoder.to_sym
-      return false unless normalized_format == "jpg"
-      return false if encoder == :imagemagick
-      raise ArgumentError, "unknown encoder: #{encoder.inspect}" unless %i[auto cjpegli].include?(encoder)
-      return true if encoder == :cjpegli && JpegliBackend.suitable_direct_input?(input)
-      encoder == :auto && JpegliBackend.available? && JpegliBackend.suitable_direct_input?(input)
+    def use_jpegli_for_convert?(input, normalized_format)
+      normalized_format == "jpg" && JpegliBackend.available? && JpegliBackend.suitable_direct_input?(input)
     end
 
-    def use_jpegli_for_generated_jpeg?(format, backend, encoder)
-      encoder = encoder.to_sym
+    # cjpegli is an output-quality tool, not a configuration choice: installed
+    # means used for JPEG output on the native path. It encodes only pixels
+    # this gem already decoded, so it is not part of the untrusted-input
+    # surface the backend choice controls.
+    def use_jpegli_for_generated_jpeg?(format)
       normalized_format = format.to_s.downcase == "jpeg" ? "jpg" : format.to_s.downcase
-      return false unless normalized_format == "jpg"
-      return false if %i[vips imagemagick magick].include?(encoder)
-      raise ArgumentError, "unknown encoder: #{encoder.inspect}" unless %i[auto cjpegli].include?(encoder)
-      raise ArgumentError, "encoder: :cjpegli currently requires backend: :vips" if encoder == :cjpegli && backend.to_sym != :vips
-      encoder == :cjpegli || (backend.to_sym == :vips && JpegliBackend.available?)
+      normalized_format == "jpg" && JpegliBackend.available?
     end
 
     def with_temp_png(output)
@@ -194,44 +260,147 @@ module SafeImage
       info[:encoder] == "cjpegli" ? "#{base}+cjpegli" : base
     end
 
-    def convert_to_jpeg(from, to, quality: nil, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)
-      convert(from, to, format: "jpg", quality: quality, optimize: optimize, max_pixels: max_pixels, encoder: encoder, chroma_subsampling: chroma_subsampling)
+    def convert_to_jpeg(from, to, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)
+      convert(from, to, format: "jpg", quality: quality, optimize: optimize, max_pixels: max_pixels, chroma_subsampling: chroma_subsampling)
     end
 
-    def fix_orientation(from, to = from, max_pixels: nil)
-      probe = compat_probe(from, backend: :imagemagick, max_pixels: max_pixels)
+    # 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
+
+      case SafeImage.config.backend
+      when :vips
+        native_fix_orientation(from, output, max_pixels: max_pixels, quality: quality)
+      when :imagemagick
+        imagemagick_fix_orientation(from, output, max_pixels: max_pixels)
+      end
+    end
+
+    def imagemagick_fix_orientation(from, output, max_pixels:)
+      probe = compat_probe(from, max_pixels: max_pixels)
       info = ImageMagickBackend.fix_orientation(input: probe.input, output: output)
       result_from_info(probe.input, output, info, "imagemagick")
     end
 
+    def native_fix_orientation(from, output, max_pixels:, quality:)
+      input = PathSafety.ensure_regular_file!(from).to_s
+      format = File.extname(input).delete_prefix(".").downcase
+      format = "jpg" if format == "jpeg"
+      # Validates the format against the native loader allowlist and enforces
+      # the pixel cap before any pixel decode.
+      orient = VipsBackend.orientation(input, max_pixels: max_pixels)
+
+      # Lossless tier: jpegtran transforms JPEG DCT coefficients directly, so
+      # there is no generation loss. -perfect refuses when the dimensions are
+      # not MCU-aligned; fall through to the re-encode tier.
+      if format == "jpg" && orient > 1 && Runner.available?("jpegtran")
+        begin
+          return jpegtran_fix_orientation(input, output, orient)
+        rescue CommandError
+          nil
+        end
+      end
+
+      quality = quality.nil? ? 95 : Integer(quality)
+      raise ArgumentError, "quality must be 1..100" unless (1..100).cover?(quality)
+      info = write_through_tempfile(output) do |tmp_path|
+        Native.resize(input, tmp_path, 1.0, format, quality, max_pixels)
+      end
+      result_from_info(input, output, info, "libvips-direct")
+    end
+
+    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])
+        Native.probe(tmp_path)
+      end
+      result_from_info(
+        input,
+        output,
+        {
+          input_format: "jpg",
+          output_format: "jpg",
+          width: info.fetch(:width),
+          height: info.fetch(:height),
+          duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+        },
+        "jpegtran"
+      )
+    end
+
+    # Writes via a sibling tempfile and renames into place, so in-place calls
+    # (to == from) never feed an output path that libvips is still reading
+    # from as input.
+    def write_through_tempfile(output)
+      tmp_path = File.join(File.dirname(output), ".safe-image-#{Process.pid}-#{output.object_id}#{File.extname(output)}")
+      PathSafety.ensure_safe_output_path!(tmp_path)
+      result = yield tmp_path
+      FileUtils.mv(tmp_path, output)
+      result
+    ensure
+      FileUtils.rm_f(tmp_path)
+    end
+
     def convert_favicon_to_png(from, to, optimize: true, max_pixels: nil)
-      frame_count(from, max_pixels: max_pixels) if max_pixels
+      max_pixels = SafeImage.resolved_max_pixels(max_pixels)
       output = PathSafety.ensure_safe_output_path!(to).to_s
-      info = ImageMagickBackend.convert_ico_to_png(input: Pathname.new(from).expand_path.to_s, output: output)
+
+      case SafeImage.config.backend
+      when :vips
+        # Pure-Ruby ICO parse; libvips only encodes the extracted pixels.
+        info = Ico.convert_to_png(from, output, max_pixels: max_pixels)
+        backend_name = "ico-ruby+libvips"
+      when :imagemagick
+        info = ImageMagickBackend.convert_ico_to_png(input: Pathname.new(from).expand_path.to_s, output: output)
+        backend_name = "imagemagick"
+      end
       Optimizer.optimize(output, mode: :lossless, strip_metadata: true) if optimize
-      result_from_info(from, output, info, "imagemagick")
+      result_from_info(from, output, info, backend_name)
     end
 
     def frame_count(path, max_pixels: nil)
-      ImageMagickBackend.frame_count(path, max_pixels: max_pixels)
+      max_pixels = SafeImage.resolved_max_pixels(max_pixels)
+      # ico directories are counted by the pure-Ruby parser on either backend;
+      # everything else is a header-only count.
+      return Ico.frame_count(path, max_pixels: max_pixels) if File.extname(PathSafety.local_path(path)).downcase == ".ico"
+
+      case SafeImage.config.backend
+      when :vips
+        VipsBackend.frame_count(path, max_pixels: max_pixels)
+      when :imagemagick
+        ImageMagickBackend.frame_count(path, max_pixels: max_pixels)
+      end
     end
 
     def animated?(path, max_pixels: nil)
       frame_count(path, max_pixels: max_pixels).to_i > 1
     end
 
-    def letter_avatar(output:, size:, background_rgb:, letter:, pointsize: 280, font: "NimbusSans-Regular")
+    def letter_avatar(output:, size:, background_rgb:, letter:, pointsize: 280, font: "DejaVu-Sans")
       output = PathSafety.ensure_safe_output_path!(output).to_s
-      info = ImageMagickBackend.letter_avatar(
-        output: output,
-        size: size,
-        background_rgb: background_rgb,
-        letter: letter,
-        pointsize: pointsize,
-        font: font
-      )
-      result_from_info("generated", output, info, "imagemagick")
+      request = { output: output, size: size, background_rgb: background_rgb, letter: letter, pointsize: pointsize, font: font }
+
+      info, backend_name =
+        case SafeImage.config.backend
+        when :vips
+          [VipsBackend.letter_avatar(**request), "libvips-direct"]
+        when :imagemagick
+          [ImageMagickBackend.letter_avatar(**request), "imagemagick"]
+        end
+
+      result_from_info("generated", output, info, backend_name)
     end
 
     def optimize_image!(path, allow_lossy_png: false, strip_metadata: true, quality: nil, strict: true)
@@ -244,9 +413,9 @@ module SafeImage
       )
     end
 
-    def compat_probe(path, backend:, max_pixels: nil)
+    def compat_probe(path, max_pixels: nil)
       path = Pathname.new(path).expand_path.to_s
-      if backend.to_sym == :vips
+      if SafeImage.config.backend == :vips
         SafeImage.probe(path, max_pixels: max_pixels)
       else
         info = ImageMagickBackend.probe(path, max_pixels: max_pixels)