safe_image 0.1.0

data/lib/safe_image/runner.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require "timeout"
+
+module SafeImage
+  class CommandError < Error
+    attr_reader :command, :status, :stdout, :stderr
+
+    def initialize(message, command:, status: nil, stdout: "", stderr: "")
+      super(message)
+      @command = command
+      @status = status
+      @stdout = stdout
+      @stderr = stderr
+    end
+  end
+
+  module Runner
+    module_function
+
+    DEFAULT_TIMEOUT = 20
+    MAX_OUTPUT_BYTES = 512 * 1024
+    TRUSTED_PATH = "/usr/bin:/bin:/usr/local/bin".freeze
+    ALLOWED_ENV_KEYS = %w[LANG LC_ALL LC_CTYPE TZ].freeze
+    IMAGEMAGICK_POLICY_PATH = File.expand_path("imagemagick_policy", __dir__)
+    IMAGEMAGICK_POLICY_FILE = File.join(IMAGEMAGICK_POLICY_PATH, "policy.xml").freeze
+    BASE_ENV = {
+      "PATH" => TRUSTED_PATH,
+      "VIPS_BLOCK_UNTRUSTED" => "1"
+    }.freeze
+
+    def run!(argv, timeout: DEFAULT_TIMEOUT, env: {}, sandbox: false, read: [], write: [])
+      raise ArgumentError, "empty command" if argv.nil? || argv.empty?
+      argv = argv.map(&:to_s)
+      argv[0] = resolve_executable!(argv[0])
+      ensure_imagemagick_policy! if imagemagick_command?(File.basename(argv[0]))
+
+      Dir.mktmpdir("safe-image-command-") do |tmpdir|
+        child_env = command_env(tmpdir, env)
+
+        if sandbox || SafeImage.sandbox_enabled?
+          return Sandbox.capture_command!(argv, read: read, write: [*write, tmpdir], timeout: timeout, env: child_env)
+        end
+
+        return run_process!(argv, child_env, timeout: timeout)
+      end
+    end
+
+    def run_process!(argv, child_env, timeout:)
+      stdout = +"".b
+      stderr = +"".b
+      status = nil
+
+      Open3.popen3(child_env, *argv, unsetenv_others: true, pgroup: true) do |stdin, out, err, wait_thr|
+        stdin.close
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        streams = { out => stdout, err => stderr }
+
+        until streams.empty?
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0
+            kill_process_group(wait_thr.pid)
+            raise CommandError.new("command timed out after #{timeout}s", command: argv, stdout: stdout, stderr: stderr)
+          end
+
+          readable, = IO.select(streams.keys, nil, nil, remaining)
+          next unless readable
+
+          readable.each do |io|
+            begin
+              chunk = io.read_nonblock(16 * 1024)
+              buffer = streams.fetch(io)
+              buffer << chunk
+              if buffer.bytesize > MAX_OUTPUT_BYTES
+                kill_process_group(wait_thr.pid)
+                raise CommandError.new("command output exceeded #{MAX_OUTPUT_BYTES} bytes", command: argv, stdout: stdout, stderr: stderr)
+              end
+            rescue IO::WaitReadable
+              next
+            rescue EOFError
+              streams.delete(io)
+              io.close
+            end
+          end
+        end
+
+        # The read loop above exits as soon as both pipes hit EOF, which can
+        # happen while the child is still alive (it closed/redirected its
+        # standard streams but keeps running, possibly via a grandchild).
+        # Bound the final wait against the same deadline so the timeout is a
+        # hard ceiling rather than something a child can close its way out of.
+        until status
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0
+            kill_process_group(wait_thr.pid)
+            raise CommandError.new("command timed out after #{timeout}s", command: argv, stdout: stdout, stderr: stderr)
+          end
+          status = wait_thr.join(remaining)&.value
+        end
+      rescue CommandError
+        raise
+      rescue Exception
+        kill_process_group(wait_thr.pid) if wait_thr
+        raise
+      end
+
+      return [stdout, stderr] if status&.success?
+
+      raise CommandError.new(
+        "command failed: #{argv.first} exited #{status&.exitstatus}",
+        command: argv,
+        status: status&.exitstatus,
+        stdout: stdout,
+        stderr: stderr
+      )
+    end
+
+    def kill_process_group(pid)
+      Process.kill("TERM", -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+    ensure
+      begin
+        sleep 0.2
+        Process.kill("KILL", -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+      end
+    end
+
+    def command_env(tmpdir, env = {})
+      allowed = env.each_with_object({}) do |(key, value), hash|
+        key = key.to_s
+        hash[key] = value.to_s if ALLOWED_ENV_KEYS.include?(key)
+      end
+
+      BASE_ENV.merge(
+        "MAGICK_CONFIGURE_PATH" => IMAGEMAGICK_POLICY_PATH,
+        "MAGICK_TEMPORARY_PATH" => tmpdir,
+        "HOME" => tmpdir,
+        "XDG_CACHE_HOME" => tmpdir,
+        "TMPDIR" => tmpdir
+      ).merge(allowed)
+    end
+
+    def ensure_imagemagick_policy!
+      raise Error, "missing ImageMagick policy: #{IMAGEMAGICK_POLICY_FILE}" unless File.file?(IMAGEMAGICK_POLICY_FILE)
+    end
+
+    def imagemagick_command?(name)
+      %w[magick convert identify compare].include?(name.to_s)
+    end
+
+    def available?(name)
+      !!resolve_executable(name)
+    end
+
+    def resolve_executable!(name)
+      resolve_executable(name) || raise(UnsupportedFormatError, "missing executable: #{name}")
+    end
+
+    def resolve_executable(name)
+      name = name.to_s
+      return name if name.include?(File::SEPARATOR) && File.file?(name) && File.executable?(name)
+
+      TRUSTED_PATH.split(File::PATH_SEPARATOR).each do |dir|
+        path = File.join(dir, name)
+        return path if File.file?(path) && File.executable?(path)
+      end
+
+      nil
+    end
+  end
+end

data/lib/safe_image/sandbox.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+require "tmpdir"
+
+module SafeImage
+  module Sandbox
+    module_function
+
+    DEFAULT_RLIMITS = {
+      cpu_seconds: 30,
+      memory_bytes: 2 * 1024 * 1024 * 1024,
+      file_size_bytes: 1024 * 1024 * 1024,
+      open_files: 256
+    }.freeze
+
+    OPERATIONS = %w[
+      probe thumbnail type size dimensions info orientation optimize resize crop downsize convert convert_to_jpeg fix_orientation
+      convert_favicon_to_png frame_count animated? letter_avatar optimize_image!
+      sanitize_svg!
+    ].freeze
+
+    def available?
+      require "landlock"
+      Landlock::SafeExec.supported?
+    rescue LoadError
+      false
+    end
+
+    def capture_command!(argv, read:, write:, timeout: Runner::DEFAULT_TIMEOUT, env: nil, rlimits: DEFAULT_RLIMITS)
+      require "landlock"
+      env ||= Runner.command_env(Dir.tmpdir)
+
+      result = Landlock::SafeExec.capture!(
+        *argv.map(&:to_s),
+        read: existing_paths([*Landlock::SafeExec.default_read_paths, *runtime_read_paths, *read]),
+        write: existing_paths(write),
+        execute: existing_paths([*Landlock::SafeExec.default_execute_paths, File.dirname(RbConfig.ruby)]),
+        env: env.merge("SAFE_IMAGE_SANDBOX_CHILD" => "1"),
+        inherit_env: false,
+        timeout: timeout,
+        rlimits: rlimits,
+        seccomp_deny_network: true,
+        max_output_bytes: 512 * 1024,
+        truncate_output: false
+      )
+      [result.stdout, result.stderr]
+    rescue LoadError
+      raise Error, "landlock sandbox requested but the landlock gem is unavailable"
+    rescue Landlock::SafeExec::CommandError => e
+      raise CommandError.new(
+        "sandboxed command failed",
+        command: argv,
+        status: e.status&.exitstatus,
+        stdout: e.stdout,
+        stderr: e.stderr
+      )
+    end
+
+    def public_call!(operation, args:, kwargs:)
+      operation = operation.to_s
+      raise ArgumentError, "unsupported sandbox operation: #{operation}" unless OPERATIONS.include?(operation)
+      result = run_worker!(operation, { args: args, kwargs: kwargs })
+      operation == "type" && result ? result.to_sym : result
+    end
+
+    def thumbnail(request)
+      public_call!(
+        :thumbnail,
+        args: [],
+        kwargs: request.merge(execution: :inline)
+      )
+    end
+
+    def run_worker!(operation, request)
+      operation = operation.to_s
+      raise ArgumentError, "unsupported sandbox operation: #{operation}" unless OPERATIONS.include?(operation)
+
+      require "landlock"
+      payload = JSON.dump({ operation: operation, request: request })
+      code = <<~'RUBY'
+        require "json"
+        require "safe_image"
+
+        def deep_symbolize(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+          when Array
+            value.map { |v| deep_symbolize(v) }
+          else
+            value
+          end
+        end
+
+        payload = JSON.parse(ARGV.fetch(0), symbolize_names: true)
+        operation = payload.fetch(:operation).to_s
+        allowed_operations = %w[
+          probe thumbnail type size dimensions info orientation optimize resize crop downsize convert convert_to_jpeg fix_orientation
+          convert_favicon_to_png frame_count animated? letter_avatar optimize_image! sanitize_svg!
+        ]
+        raise ArgumentError, "unsupported sandbox operation: #{operation}" unless allowed_operations.include?(operation)
+
+        request = payload.fetch(:request)
+        args = request[:args] || []
+        kwargs = deep_symbolize(request[:kwargs] || {})
+
+        result = SafeImage.with_sandbox_disabled do
+          SafeImage.__send__(operation, *args, **kwargs)
+        end
+
+        if defined?(SafeImage::Result) && result.is_a?(SafeImage::Result)
+          puts JSON.dump({ __type: "Result", data: result.to_h })
+        elsif defined?(SafeImage::Info) && result.is_a?(SafeImage::Info)
+          puts JSON.dump({ __type: "Info", data: result.to_h })
+        else
+          puts JSON.dump({ __type: "Value", data: result })
+        end
+      RUBY
+
+      paths = sandbox_paths(request, operation)
+      Dir.mktmpdir("safe-image-worker-") do |tmpdir|
+        worker_env = Runner.command_env(tmpdir).merge(
+          "SAFE_IMAGE_SANDBOX_CHILD" => "1",
+          "GEM_HOME" => ENV["GEM_HOME"].to_s,
+          "GEM_PATH" => ENV["GEM_PATH"].to_s,
+          "RUBYLIB" => $LOAD_PATH.select { |p| p && File.directory?(p) }.join(File::PATH_SEPARATOR)
+        )
+
+        stdout, = Landlock::SafeExec.capture!(
+          RbConfig.ruby,
+          "-I#{File.expand_path("../../", __dir__)}",
+          "-rjson",
+          "-e",
+          code,
+          payload,
+          read: existing_paths([*Landlock::SafeExec.default_read_paths, *runtime_read_paths, *paths.fetch(:read), tmpdir]),
+          write: existing_paths([*paths.fetch(:write), tmpdir]),
+          execute: existing_paths([*Landlock::SafeExec.default_execute_paths, File.dirname(RbConfig.ruby)]),
+          env: worker_env,
+          inherit_env: false,
+          timeout: Runner::DEFAULT_TIMEOUT,
+          rlimits: DEFAULT_RLIMITS,
+          seccomp_deny_network: true,
+          max_output_bytes: 512 * 1024,
+          truncate_output: false
+        )
+        response = JSON.parse(stdout, symbolize_names: true)
+        if response[:__type] == "Result"
+          data = response.fetch(:data)
+          Result.new(**data)
+        elsif response[:__type] == "Info"
+          data = response.fetch(:data)
+          Info.new(**data)
+        else
+          response[:data]
+        end
+      end
+    rescue LoadError
+      raise Error, "landlock sandbox requested but the landlock gem is unavailable"
+    rescue Landlock::SafeExec::CommandError => e
+      raise CommandError.new(
+        "sandboxed worker failed",
+        command: [RbConfig.ruby, "-e", "..."],
+        status: e.status&.exitstatus,
+        stdout: e.stdout,
+        stderr: e.stderr
+      )
+    end
+
+    def sandbox_paths(request, operation)
+      read = []
+      write = []
+
+      values = []
+      values.concat(Array(request[:args]))
+      values.concat(Array(request.dig(:kwargs)&.values))
+      values.flatten.compact.each do |value|
+        next unless value.is_a?(String)
+        next if value.empty? || value.include?("\0")
+
+        expanded = File.expand_path(value) rescue next
+        if File.exist?(expanded)
+          read << expanded
+        elsif looks_like_path?(value)
+          write << File.dirname(expanded)
+        end
+      end
+
+      # Common keyword names for generated outputs. Include the containing dir
+      # even when a stale file already exists, because operations may replace it.
+      kwargs = request[:kwargs] || {}
+      %i[output to path].each do |key|
+        next unless kwargs[key].is_a?(String)
+        write << File.dirname(File.expand_path(kwargs[key]))
+      end
+
+      # In-place mutators need write permission for an existing input path too.
+      if %w[optimize optimize_image! sanitize_svg! fix_orientation].include?(operation.to_s)
+        first = Array(request[:args]).first
+        if first.is_a?(String) && File.exist?(first)
+          expanded = File.expand_path(first)
+          write << expanded
+          write << File.dirname(expanded)
+        end
+      end
+
+      { read: read.uniq, write: write.uniq }
+    end
+
+    def looks_like_path?(value)
+      value.start_with?("/", "./", "../") || File.extname(value) != ""
+    end
+
+    def runtime_read_paths
+      paths = []
+      paths.concat(Gem.path) if defined?(Gem)
+      paths.concat($LOAD_PATH.select { |path| path && path != "." })
+      paths << RbConfig::CONFIG["rubylibdir"]
+      paths << RbConfig::CONFIG["rubyarchdir"]
+      paths << RbConfig::CONFIG["sitearchdir"]
+      paths << RbConfig::CONFIG["vendorarchdir"]
+      paths << File.dirname(RbConfig.ruby)
+      paths
+    end
+
+    def existing_paths(paths)
+      paths.flatten.compact.map(&:to_s).reject(&:empty?).select { |path| File.exist?(path) }.uniq
+    end
+
+    def symbolize(hash)
+      hash.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/safe_image/svg_metadata.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rexml/document"
+
+module SafeImage
+  module SvgMetadata
+    module_function
+
+    MAX_SVG_BYTES = 1 * 1024 * 1024
+    MAX_SVG_DEPTH = 64
+    MAX_SVG_ELEMENTS = 10_000
+    MAX_SVG_ATTRIBUTES = 50_000
+    MAX_SVG_DIMENSION = 100_000
+    MAX_SVG_PIXELS = 100_000_000
+
+    LENGTH_PATTERN = /\A\s*([+]?(?:\d+(?:\.\d+)?|\.\d+))(?:px)?\s*\z/i.freeze
+    VIEWBOX_SPLIT = /[\s,]+/.freeze
+
+    def probe(path, max_pixels: nil, max_bytes: MAX_SVG_BYTES)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      path = safe_svg_path(path)
+      width, height = dimensions(path, max_pixels: max_pixels, max_bytes: max_bytes)
+      {
+        input_format: "svg",
+        width: width,
+        height: height,
+        frames: 1,
+        duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+      }
+    end
+
+    def dimensions(path, max_pixels: nil, max_bytes: MAX_SVG_BYTES)
+      path = safe_svg_path(path)
+      doc = parse(path, max_bytes: max_bytes)
+      root = doc.root
+      width = parse_length(root.attributes["width"])
+      height = parse_length(root.attributes["height"])
+
+      unless width && height
+        view_box = parse_view_box(root.attributes["viewBox"])
+        width ||= view_box&.fetch(2)
+        height ||= view_box&.fetch(3)
+      end
+
+      validate_dimensions!(width, height, max_pixels: max_pixels)
+    end
+
+    def parse(path, max_bytes: MAX_SVG_BYTES)
+      path = safe_svg_path(path)
+      size = File.size(path)
+      raise LimitError, "SVG exceeds #{max_bytes} bytes" if size > max_bytes
+
+      xml = File.binread(path, max_bytes + 1)
+      raise LimitError, "SVG exceeds #{max_bytes} bytes" if xml.bytesize > max_bytes
+      reject_unsafe_xml!(xml)
+      doc = REXML::Document.new(xml)
+      raise InvalidImageError, "SVG root required" unless doc.root&.name == "svg"
+
+      validate_tree!(doc.root)
+      doc
+    rescue REXML::ParseException => e
+      raise InvalidImageError, "invalid SVG: #{e.message}"
+    end
+
+    def safe_svg_path(path)
+      path = PathSafety.ensure_regular_file!(path)
+      raise UnsupportedFormatError, "not an SVG file: #{path}" unless File.extname(path.to_s).downcase == ".svg"
+      path.to_s
+    end
+
+    def reject_unsafe_xml!(xml)
+      raise InvalidImageError, "doctype is not allowed in SVG" if xml.match?(/<!DOCTYPE/i)
+      raise InvalidImageError, "XML processing instructions are not allowed in SVG" if xml.match?(/<\?(?!xml\s)/i)
+    end
+
+    def parse_length(value)
+      value = value.to_s
+      match = LENGTH_PATTERN.match(value)
+      return nil unless match
+
+      number = Float(match[1])
+      return nil unless number.finite? && number.positive?
+
+      number
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_view_box(value)
+      parts = value.to_s.strip.split(VIEWBOX_SPLIT)
+      return nil unless parts.length == 4
+
+      numbers = parts.map { |part| Float(part) }
+      return nil unless numbers.all?(&:finite?) && numbers[2].positive? && numbers[3].positive?
+
+      numbers
+    rescue ArgumentError
+      nil
+    end
+
+    def validate_dimensions!(width, height, max_pixels: nil)
+      raise InvalidImageError, "SVG dimensions are missing or invalid" unless width&.positive? && height&.positive?
+      raise LimitError, "SVG dimensions exceed #{MAX_SVG_DIMENSION}px" if width > MAX_SVG_DIMENSION || height > MAX_SVG_DIMENSION
+
+      pixels = width * height
+      limit = max_pixels || MAX_SVG_PIXELS
+      raise LimitError, "SVG has #{pixels.to_i} pixels, exceeds #{limit}" if pixels > limit
+
+      [width.ceil, height.ceil]
+    end
+
+    def validate_tree!(root)
+      counters = { elements: 0, attributes: 0 }
+      validate_element!(root, depth: 0, counters: counters)
+    end
+
+    def validate_element!(element, depth:, counters:)
+      raise LimitError, "SVG nesting exceeds #{MAX_SVG_DEPTH}" if depth > MAX_SVG_DEPTH
+
+      counters[:elements] += 1
+      raise LimitError, "SVG has too many elements" if counters[:elements] > MAX_SVG_ELEMENTS
+
+      counters[:attributes] += element.attributes.length
+      raise LimitError, "SVG has too many attributes" if counters[:attributes] > MAX_SVG_ATTRIBUTES
+
+      element.elements.each do |child|
+        validate_element!(child, depth: depth + 1, counters: counters)
+      end
+    end
+  end
+end

data/lib/safe_image/svg_sanitizer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require "rexml/formatters/default"
+require "pathname"
+require "tempfile"
+
+module SafeImage
+  module SvgSanitizer
+    ALLOWED_ELEMENTS = %w[
+      svg g defs title desc path rect circle ellipse line polyline polygon text tspan
+      linearGradient radialGradient stop clipPath mask pattern use symbol
+    ].freeze
+
+    ALLOWED_ATTRIBUTES = %w[
+      id class x y x1 y1 x2 y2 cx cy r rx ry d points width height viewBox
+      fill stroke stroke-width stroke-linecap stroke-linejoin stroke-miterlimit
+      fill-rule clip-rule opacity fill-opacity stroke-opacity transform
+      gradientUnits gradientTransform offset stop-color stop-opacity clip-path
+      mask href xlink:href xmlns xmlns:xlink version preserveAspectRatio
+      font-family font-size font-weight text-anchor
+    ].freeze
+
+    module_function
+
+    def sanitize!(path, max_pixels: nil)
+      path = Pathname.new(SvgMetadata.safe_svg_path(path))
+      begin
+        SvgMetadata.dimensions(path.to_s, max_pixels: max_pixels)
+      rescue InvalidImageError => e
+        raise unless e.message.include?("dimensions are missing")
+      end
+      doc = SvgMetadata.parse(path.to_s)
+
+      clean = REXML::Document.new
+      clean.add_element(sanitize_element!(doc.root.deep_clone))
+
+      out = +""
+      formatter = REXML::Formatters::Default.new
+      formatter.write(clean, out)
+      atomic_write(path, out)
+      { format: "svg", sanitized: true, filesize: File.size(path.to_s) }
+    rescue REXML::ParseException => e
+      raise InvalidImageError, "invalid SVG: #{e.message}"
+    end
+
+    def sanitize_element!(element)
+      element.children.to_a.each do |child|
+        case child
+        when REXML::Element
+          if ALLOWED_ELEMENTS.include?(child.name)
+            sanitize_element!(child)
+          else
+            child.remove
+          end
+        when REXML::CData
+          child.replace_with(REXML::Text.new(child.value.to_s))
+        when REXML::Text
+          # Text is serialized escaped by REXML::Formatters::Default.
+        else
+          child.remove
+        end
+      end
+
+      attributes_to_delete = []
+      element.attributes.each_attribute do |attr|
+        name = attr.name.to_s
+        value = attr.value.to_s
+        allowed = ALLOWED_ATTRIBUTES.include?(name) || name.start_with?("aria-")
+        if !allowed || name.downcase.start_with?("on") || dangerous_value?(value)
+          attributes_to_delete << name
+        end
+      end
+      attributes_to_delete.each { |name| element.delete_attribute(name) }
+
+      %w[href xlink:href].each do |href|
+        next unless element.attributes[href]
+        element.delete_attribute(href) unless element.attributes[href].to_s.start_with?("#")
+      end
+      element
+    end
+
+    def dangerous_value?(value)
+      normalized = value.to_s.gsub(/[\u0000-\u0020\u007f]+/, "")
+      return true if normalized.match?(/(?:javascript|data):/i)
+
+      normalized.scan(/url\(([^)]*)\)/i).any? do |match|
+        inner = match.first.to_s.delete(%q{'"})
+        !inner.match?(/\A#[A-Za-z][\w.-]*\z/)
+      end
+    end
+
+    def atomic_write(path, content)
+      Tempfile.create([path.basename.to_s, ".tmp"], path.dirname.to_s, binmode: false) do |tmp|
+        tmp.write(content)
+        tmp.flush
+        tmp.fsync
+        File.rename(tmp.path, path.to_s)
+      end
+    end
+  end
+end

data/lib/safe_image/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SafeImage
+  VERSION = "0.1.0"
+end

data/lib/safe_image/vips_backend.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SafeImage
+  module VipsBackend
+    module_function
+
+    DIMENSIONS_RE = /\A(?:(?<percent>\d+(?:\.\d+)?)%|(?<w>\d*)x(?<h>\d*)(?<only_down>>)?|(?<pixels>\d+)@)\z/
+
+    def crop_north(input:, output:, width:, height:, format:, quality: 85, max_pixels: nil)
+      Native.crop_north(input.to_s, output.to_s, Integer(width), Integer(height), format.to_s, Integer(quality), max_pixels)
+    end
+
+    def downsize(input:, output:, dimensions:, format:, quality: 85, max_pixels: nil)
+      probe = SafeImage.probe(input, max_pixels: max_pixels)
+      scale = scale_for(probe.width, probe.height, dimensions)
+      # Never upscale, but always re-encode through the native saver — even on a
+      # no-op scale of 1.0 — so the output is metadata-stripped rather than a
+      # verbatim copy of the untrusted input bytes.
+      scale = [scale, 1.0].min
+      Native.resize(input.to_s, output.to_s, scale, normalized_format(format), Integer(quality), max_pixels)
+    end
+
+    def normalized_format(format)
+      format = format.to_s.downcase
+      format == "jpeg" ? "jpg" : format
+    end
+
+    def scale_for(width, height, dimensions)
+      dimensions = dimensions.to_s
+      match = DIMENSIONS_RE.match(dimensions) or raise ArgumentError, "unsupported dimensions: #{dimensions.inspect}"
+
+      if match[:percent]
+        return Float(match[:percent]) / 100.0
+      end
+
+      if match[:pixels]
+        target_pixels = Float(match[:pixels])
+        return Math.sqrt(target_pixels / (Integer(width) * Integer(height)))
+      end
+
+      target_w = match[:w].to_s.empty? ? nil : Float(match[:w])
+      target_h = match[:h].to_s.empty? ? nil : Float(match[:h])
+      scales = []
+      scales << target_w / width if target_w
+      scales << target_h / height if target_h
+      raise ArgumentError, "missing width/height in dimensions: #{dimensions.inspect}" if scales.empty?
+      scales.min
+    end
+  end
+end