camaleon_cms 2.9.2 → 2.9.4

data/lib/camaleon_cms/unsafe_markup.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'loofah'
+require 'rails-html-sanitizer'
+
+module CamaleonCms
+  # Scan-and-reject gate for authored rich text (audit findings M17 and the post-content policy).
+  #
+  # The security model is rejection, not transformation: an untrusted author's content is either
+  # stored exactly as written or refused with an error naming the problem — it is never silently
+  # rewritten. Stored content therefore always equals authored content, and the frontend may render
+  # it verbatim, which is what the templates do (`raw` post content, `raw` editor field values).
+  #
+  # The detector mirrors the gate cama_contact_form's admin controller applies to its authored
+  # markup positions (keep the two in parity): parse once, compare what the safe-list scrubber
+  # would remove against the parse's own reserialization, so only a genuine removal registers —
+  # never a spelling difference (`Tom & Jerry`, `<br/>`, quote style, tag case). Three structural
+  # guards cover what that comparison cannot see: markup the parser drops instead of scrubbing,
+  # a tag left open at the end of the value, and a translation marker sitting inside a tag (the
+  # renderer deletes markers, so one inside a tag splices markup the gate never saw).
+  module UnsafeMarkup
+    # Every gated value costs a parse, and both the number of values and their size are chosen by
+    # the caller — bound the size so a pathological multi-megabyte value cannot drive a giant Loofah
+    # parse. The ceiling is generous (an ordinary long article is well under it); callers surface an
+    # over-size refusal with its own message via `too_large?`, and `unsafe_html?` keeps the check as a
+    # fail-closed backstop for callers that do not pre-check.
+    MAX_GATED_VALUE_BYTES = 2 * 1024 * 1024
+
+    # Nothing below can find anything in a string holding none of these: the scrubber and the
+    # serializer are both the identity function on it. `&` counts because entity decoding is a
+    # rewrite, the private-use sentinels count because the translation-marker shield deletes any
+    # supplied raw, and the control characters count because the HTML parser rewrites them.
+    SANITIZER_SIGNIFICANT = /[<>&\u{E000}\u{E001}\u0000-\u0008\u000B\u000C\u000E-\u001F\u{FFFE}\u{FFFF}]/
+
+    # A well-formed translation marker (`<!--:-->`, `<!--:en-->`). Any other `<!--` is refused:
+    # the sanitizer strips comments, so a stray comment would register as a removal anyway, but an
+    # unterminated one additionally swallows everything to the next `-->` when emitted.
+    TRANSLATION_MARKER = /<!--:[\w|-]{0,5}-->/
+
+    # `<` only opens a tag when a name, a solidus or a markup declaration follows it — this is what
+    # keeps `Age < 18` and `5 > 3` out of the tag scanners below.
+    TAG_OPEN = %r{<[a-zA-Z/!?]}
+    START_TAG_NAME = %r{<([a-zA-Z][a-zA-Z0-9]*)(?=[\s/>]|\z)}
+    # One whole tag, quoted attribute values included, so a `>` inside an attribute does not look
+    # like the end of the tag; an unterminated quote runs to the end of the value.
+    TAG_SPAN = %r{<[a-zA-Z/!?][^"'>]*(?:(?:"[^"]*"?|'[^']*'?)[^"'>]*)*>?}
+
+    # `data-*`/`aria-*` are admitted by shape: the set is open, they carry no behaviour of their
+    # own (a data- attribute is inert without script; an aria- attribute only annotates), and
+    # without them ordinary pasted Bootstrap-style markup would be refused for attributes no
+    # rejection message names.
+    OPEN_ATTR_NAME = /\A(?:data|aria)-[a-zA-Z][-a-zA-Z0-9_.]*\z/
+
+    # rails-html-sanitizer >= 1.6 exposes the scrubber under Rails::HTML (all caps); older releases
+    # (valid with Rails 6.1/7.0, which this gem supports) expose only Rails::Html. Resolve whichever
+    # the host bundled so the engine loads across the whole supported range.
+    PERMIT_SCRUBBER_BASE = defined?(Rails::HTML::PermitScrubber) ? Rails::HTML::PermitScrubber : Rails::Html::PermitScrubber
+
+    class PermissiveDataAttrScrubber < PERMIT_SCRUBBER_BASE
+      private
+
+      def scrub_attribute?(name)
+        return false if name.to_s.match?(OPEN_ATTR_NAME)
+
+        super
+      end
+    end
+
+    class << self
+      # True when `value` contains markup outside the given allowlist (or one of the structural
+      # shapes above). Callers reject the save when this is true for an untrusted author.
+      def unsafe_html?(value, tags:, attributes:)
+        string = scannable_string(value)
+        return false unless string.match?(SANITIZER_SIGNIFICANT)
+        return true if string.bytesize > MAX_GATED_VALUE_BYTES
+        return true if disallowed_comment?(string)
+        return true if marker_inside_tag?(string)
+        return true if unterminated_tag?(string)
+
+        shielded = string.gsub(CamaleonRecord::TRANSLATION_TAG_HIDE_REGEX, CamaleonRecord::TRANSLATION_TAG_HIDE_MAP)
+        fragment = parse(shielded)
+        # The css scrubber reformats whitespace while it scrubs, so a benign `text-align: center`
+        # would register as a removal in the comparison below. Check style values separately
+        # (whitespace-insensitively) and normalize them on the tree first, so the comparison sees
+        # identical css on both sides and only element/attribute removals register.
+        return true if dangerous_or_normalized_css!(fragment)
+        return true if attribute_holds_markup?(fragment)
+
+        baseline = fragment.to_s
+        return true if markup_dropped?(shielded, fragment)
+
+        # One parse, not two: scrub the fragment already built, so both sides of the comparison
+        # share the same parser and serializer and only a genuine removal differs.
+        fragment.scrub!(scrubber_for(tags, attributes)).to_s != baseline
+      end
+
+      # True when the value exceeds the parse-cost ceiling. Callers refuse it with a size-specific
+      # message rather than the markup message — an over-size value may be perfectly clean.
+      def too_large?(value)
+        value.to_s.bytesize > MAX_GATED_VALUE_BYTES
+      end
+
+      # True when `value` carries a script-capable URI scheme (javascript:, vbscript:, or a
+      # non-raster data: URI), tolerant of the gap characters and entity encodings a browser
+      # strips. For values a renderer emits into a URL position (href/src).
+      def dangerous_uri?(value)
+        CamaleonCms::ContentSecurity.blocked_scheme?(value.to_s)
+      end
+
+      private
+
+      # Prefer the HTML5 parser (browser-parity) only when it is actually available: the method
+      # arrived in loofah 2.21, so guard on the method itself, not on `Nokogiri::HTML5` (present
+      # since nokogiri 1.11) -- an older loofah with a newer nokogiri would otherwise NoMethodError.
+      def parse(string)
+        if Loofah.respond_to?(:html5_fragment) && defined?(Nokogiri::HTML5)
+          Loofah.html5_fragment(string)
+        else
+          Loofah.fragment(string)
+        end
+      end
+
+      # The gate only reads, never stores. A legacy value with invalid (or non-UTF-8) encoding would
+      # make the `match?` below raise ArgumentError -- a 500 on save and an abort of the scan task --
+      # so scan a scrubbed UTF-8 copy instead. The stored bytes are never touched (reject, don't
+      # transform), and invalid byte sequences cannot spell markup anyway.
+      def scannable_string(value)
+        string = value.to_s
+        return string if string.encoding == Encoding::UTF_8 && string.valid_encoding?
+
+        string.b.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def scrubber_for(tags, attributes)
+        PermissiveDataAttrScrubber.new.tap do |scrubber|
+          scrubber.tags = tags
+          scrubber.attributes = attributes
+        end
+      end
+
+      # Scrub every style attribute with the same css scrubber the safe-list scrub uses, compare
+      # declaration-by-declaration ignoring the scrubber's benign rewrites (whitespace, a trailing
+      # semicolon), and write the scrubbed form back so the later serialization comparison cannot
+      # re-register it. A surviving difference means the scrubber refused part of the css
+      # (expression(), url(javascript:), a disallowed property) — dangerous, report it.
+      def dangerous_or_normalized_css!(fragment)
+        fragment.css('[style]').any? do |node|
+          original = node['style'].to_s
+          scrubbed = Loofah::HTML5::Scrub.scrub_css(original)
+          node['style'] = scrubbed
+          css_declarations(original) != css_declarations(scrubbed)
+        end
+      end
+
+      def css_declarations(css)
+        css.gsub(/\s+/, '').split(';').reject(&:empty?)
+      end
+
+      # Any `<!--` that is not a well-formed translation marker. A bare `-->` is ordinary text.
+      def disallowed_comment?(string)
+        string.gsub(TRANSLATION_MARKER, '').include?('<!--')
+      end
+
+      # A tag opened after the last `>` is never completed inside this value.
+      def unterminated_tag?(string)
+        string.rpartition('>').last.match?(TAG_OPEN)
+      end
+
+      # Every tag the author wrote has to appear in the parse. Compared by name rather than by
+      # count, because the parser *inserts* elements too — an implied `<tbody>` would otherwise
+      # cancel out a dropped `<td>` and let the pair through.
+      def markup_dropped?(shielded, fragment)
+        written = shielded.scan(START_TAG_NAME).flatten.map(&:downcase).tally
+        return false if written.empty?
+
+        parsed = fragment.css('*').map { |node| node.name.downcase }.tally
+        written.any? { |name, count| parsed.fetch(name, 0) < count }
+      end
+
+      # An attribute value that decodes to a tag-open is markup smuggled through an attribute the
+      # scrubber keeps -- a data-*/aria-* attribute admitted by shape, or an allowed one like `title`.
+      # A client-side `data-html` sink (Bootstrap tooltip/popover, and similar) injects such a value
+      # as HTML at render. Entity-encoded markup (`&lt;img ...&gt;`) leaves no literal `<` in the
+      # stored bytes, so `markup_dropped?` never sees it; but the parser has already entity-decoded
+      # the value on the node, so a tag-open here is real markup the renderer would emit. Reject it
+      # (never rewrite). A legitimate `<` in an attribute value (rare) must be entity-escaped by hand.
+      def attribute_holds_markup?(fragment)
+        fragment.css('*').any? do |node|
+          node.attribute_nodes.any? { |attr| attr.value.to_s.match?(TAG_OPEN) }
+        end
+      end
+
+      # A translation marker separates whole translated blocks; it never belongs *inside* a tag.
+      # The renderer deletes markers, so one inside a tag splices the halves into markup the
+      # author never wrote and this gate never saw.
+      def marker_inside_tag?(string)
+        return false unless string.include?('<!--')
+
+        tags = +''
+        string.scan(/#{TRANSLATION_MARKER}|#{TAG_SPAN}/) do |match|
+          tags << match unless match.match?(/\A#{TRANSLATION_MARKER}\z/)
+        end
+        tags.match?(TRANSLATION_MARKER)
+      end
+    end
+  end
+end

data/lib/camaleon_cms/uploader_content_security.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require 'stringio'
+
+module CamaleonCms
+  module UploaderContentSecurity
+    # Extensions a browser parses as markup. These select the parse-based checker; everything else
+    # keeps the generic pattern ruleset.
+    #
+    # The routing key is *how the stored file will be rendered*, not a literal `.svg` comparison.
+    # The two are not the same thing, and the difference was the bug: identical bytes carrying an
+    # `onpointerdown` attribute were refused as `x.svg` and stored as `x.html`, because only the
+    # first name reached the checker that rejects handlers by shape.
+    #
+    # Deliberately narrow. Everything listed here is served as markup and therefore parsed as markup
+    # by the browser; nothing else is added "just in case". Running a markup parser over content
+    # that is not markup invents attributes that were never written -- `if a<b and on=1 then x` in a
+    # .txt parses to a `b` element with an `on` attribute -- so a wider list would refuse ordinary
+    # text files.
+    MARKUP_EXTENSIONS = %w[svg svgz svg.gz html htm xhtml xht shtml xml xsl xslt].freeze
+
+    # Of those, the ones that are not well-formed XML and need the HTML parser (see
+    # SvgContentChecker: the two modes differ in whether a parse failure means anything).
+    HTML_MODE_EXTENSIONS = %w[html htm shtml].freeze
+
+    # Gzip-compressed markup. Compressed bytes are high-entropy: no pattern matches them and no
+    # parser reads them, so scanning them as they arrive is not weak scanning, it is no scanning.
+    COMPRESSED_MARKUP_EXTENSIONS = %w[svgz svg.gz].freeze
+
+    # Executable script. Refused for untrusted uploaders rather than scanned, because no scan can
+    # reach a verdict on JavaScript: it has no safe subset, every dangerous capability is reachable
+    # through dynamic construction (`window['fet'+'ch']`), and legitimate uploaded script is
+    # arbitrary script -- indistinguishable from a payload by any static rule. A scanner that cannot
+    # decide has to fail closed, and a fail-closed scanner for these types is a permission gate.
+    #
+    # The gate is the existing `media_unfiltered_upload`, not a new permission. Its holders skip
+    # scanning entirely, so they could already store these files; reusing it grants nothing new and
+    # changes nothing for an install that has already granted it, whereas a new permission would
+    # revoke the capability from those installs until they granted the second one too.
+    SCRIPT_EXTENSIONS = %w[js mjs cjs wasm swf].freeze
+
+    # Ceiling on decompressed markup. Compression is the one case where the upload size limit stops
+    # bounding the work: a few-KB upload can expand to gigabytes, so the input limit says nothing
+    # about the memory the scan will use. Generous for a real compressed image and far below
+    # anything a bomb aims for; an upload that exceeds it is refused rather than expanded further.
+    MAX_DECOMPRESSED_MARKUP_BYTES = 10 * 1024 * 1024
+
+    # Leading bytes of a gzip member. Used to decide whether trailing bytes after one member begin
+    # another, so every member is decompressed rather than only the first.
+    GZIP_MAGIC = "\x1f\x8b".b.freeze
+    # Whether the current uploader may skip the malicious-content scan. Mirrors
+    # Post#trusted_for_unfiltered_html?: read the request context, fail closed (scan) when
+    # either half is missing -- background jobs, rake tasks and the console have no request
+    # user, and an upload from there must be scanned rather than exempted.
+    #
+    # Deliberately not memoized. The crop flow evaluates this twice, which costs two role-meta
+    # lookups on an operation already doing file I/O; an ivar memo would have to be invalidated
+    # whenever CurrentRequest changes, and the object it would hang on is sometimes a long-lived
+    # plugin helper rather than a per-request controller.
+    def cama_trusted_for_unfiltered_upload?
+      user = CurrentRequest.user
+      site = CurrentRequest.site
+      return false if user.blank? || site.blank?
+
+      CamaleonCms::Ability.new(user, site).can?(:manage, :media_unfiltered_upload)
+    rescue StandardError
+      # Ability#initialize dereferences the site and reads role metas for non-admin users;
+      # malformed meta must fail closed instead of aborting the upload with a 500.
+      false
+    end
+
+    def svg_upload?(uploaded_io)
+      file_path = if uploaded_io.is_a?(ActionDispatch::Http::UploadedFile)
+                    uploaded_io.original_filename
+                  else
+                    uploaded_io.path
+                  end
+      cama_upload_extension(file_path) == 'svg'
+    end
+
+    # Scans in-memory content. Callers holding decoded bytes (e.g. a base64 data:
+    # payload) use this to check *before* writing to a web-served staging path, so
+    # rejected content never reaches a servable location.
+    #
+    # Returns a truthy value (the matched pattern, or true for SVG) when unsafe,
+    # nil when safe -- matching file_content_unsafe?'s contract.
+    def content_unsafe?(content, filename: nil)
+      extension = cama_upload_extension(filename)
+
+      # No permission check here. Every caller reaches this method only after
+      # `cama_trusted_for_unfiltered_upload?` already answered false, so the uploader is known to be
+      # untrusted; asking again would cost a second role-meta lookup and could disagree with the
+      # check that already ran. It also means the fail-closed behaviour is inherited exactly --
+      # no request user or no site means the scan runs, and the scan refuses these.
+      if SCRIPT_EXTENSIONS.include?(extension)
+        Rails.logger.info { 'Potentially malicious content found: executable script upload' }
+        return 'script_upload'
+      end
+
+      if MARKUP_EXTENSIONS.include?(extension)
+        return true if markup_unsafe?(content, extension)
+
+        return nil
+      end
+
+      normalized = CamaleonCms::ContentSecurity.normalize(content)
+      if CamaleonCms::ContentSecurity.blocked_scheme_in?(normalized)
+        Rails.logger.info { 'Potentially malicious content found: blocked URI scheme' }
+        return 'blocked_scheme'
+      end
+      CamaleonCms::ContentSecurity::SUSPICIOUS_PATTERNS.each do |pattern|
+        next unless normalized&.match?(pattern)
+
+        Rails.logger.info { "Potentially malicious content found: #{pattern.inspect}" }
+        return pattern.inspect
+      end
+      nil
+    end
+
+    # IO-based entry point: reads the handle, rewinds it so downstream consumers
+    # still see the full content, and delegates to content_unsafe?.
+    def file_content_unsafe?(uploaded_io)
+      file = uploaded_io.is_a?(ActionDispatch::Http::UploadedFile) ? uploaded_io.tempfile : uploaded_io
+      filename = if uploaded_io.is_a?(ActionDispatch::Http::UploadedFile)
+                   uploaded_io.original_filename
+                 else
+                   uploaded_io.path
+                 end
+      # `.svg` is read as-is; every other extension is forced to BINARY (svgz needs the raw gzip
+      # bytes, and the markup parser reads the encoding from the content, not the String tag). Reuse
+      # the filename already computed rather than re-deriving the path through svg_upload?.
+      if cama_upload_extension(filename) != 'svg' && file.respond_to?(:binmode) && file.respond_to?(:set_encoding)
+        file.set_encoding(Encoding::BINARY)
+      end
+      content = file.read
+      file.rewind if file.respond_to?(:rewind)
+
+      content_unsafe?(content, filename: filename)
+    end
+
+    private
+
+    # The extension that selects the ruleset, lowercased. Handles three shapes a naive
+    # `File.extname` gets wrong, each of which was or would be a routing bypass:
+    #   - a compound `.svg.gz`, which File.extname reports as `.gz`
+    #   - a dotfile (`.svg`), which File.extname reports as having no extension at all
+    #   - any case (`evil.SVG`), since the stored name keeps whatever case the client sent
+    # A name with no extension yields '' and takes the generic ruleset.
+    def cama_upload_extension(name)
+      base = File.basename(name.to_s).downcase
+      # Trailing dots and spaces do not survive the way the file is served: some servers and
+      # filesystems strip them (IIS-style), turning `evil.svg.` back into `evil.svg` and serving it
+      # as SVG, so `File.extname` reporting no extension would route it to the weaker generic ruleset
+      # while the browser parses it as markup. Strip them so routing matches how the file is served.
+      base = base.sub(/[.\s]+\z/, '')
+      compound = COMPRESSED_MARKUP_EXTENSIONS.find { |ext| ext.include?('.') && base.end_with?(".#{ext}") }
+      return compound if compound
+
+      extension = File.extname(base).delete_prefix('.')
+      return extension if extension.present?
+
+      # A basename that is entirely an extension (`.svg`) routes on that name rather than falling
+      # through to the generic ruleset -- fail closed, preserving the behaviour of the suffix check
+      # this replaced.
+      base.start_with?('.') ? base.delete_prefix('.') : ''
+    end
+
+    # Markup verdict: the byte-level scheme check, then the parser the browser would use.
+    #
+    # The scheme check is not redundant with the parse, and dropping it would have lost detection.
+    # `normalize` strips the NUL and C0 bytes a URL parser ignores inside a scheme, so
+    # `java\0script:` matches on the raw bytes; the HTML parser instead *truncates* the attribute at
+    # the NUL, leaving `java` and nothing for a parse-based check to find. Bytes and tree disagree,
+    # so both are consulted.
+    #
+    # The element and handler patterns still run here, as a byte-level backstop the parse cannot
+    # provide. A markup parser autodetects its encoding from in-band signals (a BOM, an XML
+    # declaration, a `<meta charset>`); a browser can resolve the same signals differently, so a
+    # document declaring `utf-16` while carrying ASCII fires its handlers in the browser but reaches
+    # the parser as garbled utf-16 with no handlers seen. `suspicious_markup_bytes?` strips the
+    # NUL/C0 padding and matches the element/handler tokens on the collapsed bytes, catching the
+    # payload whatever encoding the parser chose. It does not entity-decode, so the parse still owns
+    # the documented false positive it removes: a document that merely *shows* escaped markup
+    # (`&lt;script&gt;`) renders as literal text in a browser and is not refused for it.
+    def markup_unsafe?(content, extension)
+      scannable = cama_markup_scannable(content, extension)
+      return true if scannable == :too_large
+
+      return true if CamaleonCms::ContentSecurity.blocked_scheme?(scannable)
+      return true if CamaleonCms::ContentSecurity.suspicious_markup_bytes?(scannable)
+
+      CamaleonCms::SvgContentChecker.unsafe?(scannable, mode: cama_markup_parse_mode(extension))
+    end
+
+    # The bytes a browser will actually parse: the decompressed payload for a compressed markup
+    # extension, the content itself otherwise.
+    #
+    # Bytes under a compressed extension that are not valid gzip fall back to being scanned as raw
+    # markup rather than skipped. nginx's default mime map serves `.svgz` as `image/svg+xml`, so an
+    # ungzipped file under that name still renders as SVG; skipping it would be the same
+    # scanned-in-name-only hole the compression created.
+    def cama_markup_scannable(content, extension)
+      return content unless COMPRESSED_MARKUP_EXTENSIONS.include?(extension)
+
+      cama_gunzip_bounded(content) || content
+    end
+
+    # Decompresses every gzip member, at most MAX_DECOMPRESSED_MARKUP_BYTES in total. Returns the
+    # payload, `:too_large` when it exceeds the ceiling, or nil when the bytes are not gzip at all.
+    #
+    # A gzip stream may hold several concatenated members, and a compliant decoder returns their
+    # concatenation -- the browser serving `.svgz` with `Content-Encoding: gzip`, the gzip CLI, and
+    # zlib all do. `GzipReader#read` stops at the first member, so reading once would scan a clean
+    # decoy member while a hostile second member is served unexamined. Loop over `unused` (the bytes
+    # left after a member's footer) so every member is decompressed and scanned.
+    #
+    # Reads one byte past the remaining ceiling per member and checks after each, rather than reading
+    # to EOF and measuring afterwards: a GzipReader decompresses lazily, so a bomb is detected having
+    # materialized only the bound, not the gigabytes behind it.
+    def cama_gunzip_bounded(content)
+      remaining = content.to_s.b
+      return nil unless remaining.start_with?(GZIP_MAGIC)
+
+      decompressed = +''.b
+      while remaining.start_with?(GZIP_MAGIC)
+        reader = Zlib::GzipReader.new(StringIO.new(remaining))
+        begin
+          decompressed << reader.read(MAX_DECOMPRESSED_MARKUP_BYTES + 1 - decompressed.bytesize).to_s
+          remaining = reader.unused.to_s.b
+        ensure
+          reader.close
+        end
+        return :too_large if decompressed.bytesize > MAX_DECOMPRESSED_MARKUP_BYTES
+      end
+      decompressed
+    rescue Zlib::Error, EOFError
+      # A member whose footer will not verify (truncated or corrupt). Scan whatever earlier members
+      # already decoded -- the prefix a compliant decoder would emit before erroring -- or, if none
+      # did, fall back to the raw bytes, which fail closed for anything that is not clean markup.
+      decompressed.empty? ? nil : decompressed
+    end
+
+    def cama_markup_parse_mode(extension)
+      HTML_MODE_EXTENSIONS.include?(extension) ? :html : :xml
+    end
+  end
+end

data/lib/camaleon_cms/uploader_image_processing.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# rubocop:disable Naming/MethodParameterName
+module CamaleonCms
+  # Image transformation shared by the two uploader entry points,
+  # CamaleonCms::RuntimeUploaderConcern and CamaleonCms::UploaderHelper, so cropping
+  # and resizing behave identically whichever one a caller included.
+  module UploaderImageProcessing
+    # Terminal `.svg` extension, any case. The upload pipeline preserves the client's extension
+    # case (`logo.SVG` is stored verbatim), so every site renaming an SVG-derived artifact to
+    # `.jpg` must match case-insensitively or uppercase uploads keep their SVG name and format.
+    # Anchored so the rename never touches an `.svg` occurring mid-path.
+    SVG_EXT_PATTERN = /\.svg\z/i
+
+    # generate thumbnail of a existent image
+    # key: key of the current file
+    # the thumbnail will be saved in my_images/my_img.png => my_images/thumb/my_img.png
+    def cama_uploader_generate_thumbnail(uploaded_io, key, thumb_size = nil, remove_source = false)
+      w = thumb_size.present? ? thumb_size.split('x')[0] : cama_uploader.thumb[:w]
+      h = thumb_size.present? ? thumb_size.split('x')[1] : cama_uploader.thumb[:h]
+      uploaded_io = File.open(uploaded_io) if uploaded_io.is_a?(String)
+      path_thumb = cama_resize_and_crop(uploaded_io.path, w, h)
+      thumb = cama_uploader.add_file(path_thumb, cama_uploader.version_path(key).sub(SVG_EXT_PATTERN, '.jpg'),
+                                     is_thumb: true, same_name: true)
+      FileUtils.rm_f(path_thumb) if remove_source
+      thumb
+    end
+
+    # crop and image and saved as imagename_crop.ext
+    # file: file path
+    # w:  new width
+    # h: new height
+    # w_offset: left offset
+    # w_offset: top offset
+    # resize: true/false
+    #   (true => resize the image to this dimension)
+    #   (false => crop the image with this dimension)
+    # replace: Boolean (replace current image or create another file)
+    def cama_crop_image(file_path, w = nil, h = nil, w_offset = 0, h_offset = 0, resize = false, replace = true)
+      force = w.present? && h.present? && !w.include?('?') && !h.include?('?') ? '!' : ''
+      img = MiniMagick::Image.open(file_path)
+      w = clamp_to_image_dimension(w, img[:width])
+      h = clamp_to_image_dimension(h, img[:height])
+      data = { img: img, w: w, h: h, w_offset: w_offset, h_offset: h_offset, resize: resize, replace: replace }
+      hooks_run('before_crop_image', data)
+      data[:img].combine_options do |i|
+        i.resize("#{w.presence}x#{h.presence}#{force}") if data[:resize]
+        i.crop "#{w.presence}x#{h.presence}+#{w_offset}+#{h_offset}#{force}" unless data[:resize]
+      end
+
+      ext = File.extname(file_path)
+      res = data[:replace] ? file_path : file_path.gsub(ext, "_crop#{ext}")
+      data[:img].write res
+      res
+    end
+
+    # resize and crop a file
+    # SVGs are converted to JPEGs for editing
+    # Params:
+    #   file: (String) File path
+    #   w: (Integer) width
+    #   h: (Integer) height
+    #   settings:
+    #     gravity: (Sym, default :north_east)
+    #       Crop position: :north_west, :north, :north_east, :east, :south_east, :south, :south_west, :west, :center
+    #     overwrite: (Boolean, default true) true for overwrite current image with resized resolutions,
+    #       false: create other file called with prefix "crop_"
+    #     output_name: (String, default prefixd name with crop_), permit to define the output name of the
+    #       thumbnail if overwrite = true
+    # Return: (String) file path where saved this cropped
+    # sample: cama_resize_and_crop(my_file, 200, 200, {gravity: :north_east, overwrite: false})
+    def cama_resize_and_crop(file, w, h, settings = {})
+      settings = { gravity: :north_east, overwrite: true, output_name: +'' }.merge!(settings)
+      img = MiniMagick::Image.open(file)
+      if file.match?(SVG_EXT_PATTERN)
+        img.format 'jpg'
+        file.sub!(SVG_EXT_PATTERN, '.jpg')
+        settings[:output_name]&.sub!(SVG_EXT_PATTERN, '.jpg')
+      end
+      w = clamp_to_image_dimension(w, img[:width])
+      h = clamp_to_image_dimension(h, img[:height])
+      w_original = img[:width].to_f
+      h_original = img[:height].to_f
+      w = w.to_i if w.present?
+      h = h.to_i if h.present?
+
+      # check proportions
+      if w_original * h < h_original * w
+        op_resize = "#{w.to_i}x"
+        w_result = w
+        h_result = (h_original * w / w_original)
+      else
+        op_resize = "x#{h.to_i}"
+        w_result = (w_original * h / h_original)
+        h_result = h
+      end
+
+      w_offset, h_offset = cama_crop_offsets_by_gravity(settings[:gravity], [w_result, h_result], [w, h])
+      data = { img: img, w: w, h: h, w_offset: w_offset, h_offset: h_offset, op_resize: op_resize, settings: settings }
+      hooks_run('before_resize_crop', data)
+      data[:img].combine_options do |i|
+        i.resize(data[:op_resize])
+        i.gravity(settings[:gravity])
+        i.crop "#{data[:w].to_i}x#{data[:h].to_i}+#{data[:w_offset]}+#{data[:h_offset]}!"
+      end
+
+      if settings[:overwrite]
+        data[:img].write(file.sub(SVG_EXT_PATTERN, '.jpg'))
+      elsif settings[:output_name].present?
+        data[:img].write(file = File.join(File.dirname(file), settings[:output_name]).to_s)
+      else
+        data[:img].write(file = uploader_verify_name(
+          File.join(File.dirname(file), "crop_#{File.basename(file.sub(SVG_EXT_PATTERN, '.jpg'))}")
+        ))
+      end
+      file
+    end
+
+    # resize image if the format is correct
+    # return resized file path
+    def cama_resize_upload(image_path, dimension, args = {})
+      if cama_uploader.class.validate_file_format(image_path, 'image') && dimension.present?
+        dim_parts = dimension.split('x')
+        r = { file: image_path, w: dim_parts[0], h: dim_parts[1], w_offset: 0, h_offset: 0,
+              resize: !dim_parts[2] || dim_parts[2] == 'resize',
+              replace: true, gravity: :north_east }.merge!(args)
+        hooks_run('on_uploader_resize', r)
+        image_path = if r[:w].present? && r[:h].present?
+                       cama_resize_and_crop(r[:file], r[:w], r[:h], { overwrite: r[:replace], gravity: r[:gravity] })
+                     else
+                       cama_crop_image(r[:file], r[:w], r[:h], r[:w_offset], r[:h_offset], r[:resize], r[:replace])
+                     end
+      end
+      image_path
+    end
+
+    private
+
+    # helper for resize and crop method
+    def cama_crop_offsets_by_gravity(gravity, original_dimensions, cropped_dimensions)
+      original_width, original_height = original_dimensions
+      cropped_width, cropped_height = cropped_dimensions
+
+      vertical_offset = case gravity
+                        when :north_west, :north, :north_east then 0
+                        when :center, :east, :west then [((original_height - cropped_height) / 2.0).to_i, 0].max
+                        when :south_west, :south, :south_east then (original_height - cropped_height).to_i
+                        end
+
+      horizontal_offset = case gravity
+                          when :north_west, :west, :south_west then 0
+                          when :center, :north, :south then [((original_width - cropped_width) / 2.0).to_i, 0].max
+                          when :north_east, :east, :south_east then (original_width - cropped_width).to_i
+                          end
+
+      [horizontal_offset, vertical_offset]
+    end
+
+    def clamp_to_image_dimension(value, img_size)
+      return value unless value.present? && value.to_s.include?('?')
+
+      img_size.to_f > value.sub('?', '').to_i ? value.sub('?', '') : img_size
+    end
+  end
+end
+# rubocop:enable Naming/MethodParameterName