camaleon_cms 2.9.2 → 2.9.4

data/lib/camaleon_cms/content_security.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module CamaleonCms
+  # SVG content security is now handled by CamaleonCms::SvgContentChecker
+  # (Nokogiri XML parse-based detection). These patterns are retained for non-SVG file
+  # scanning as a defense-in-depth layer.
+  module ContentSecurity
+    # Bounded like UserUrlValidator#validate_path_traversal, so multiply-encoded
+    # payloads are caught without a decoding bomb looping forever.
+    DECODE_PASSES = 5
+
+    # NUL and C0 controls are stripped before matching: browsers ignore them inside
+    # a URI scheme, so "java\0script:" is live markup while the raw bytes match
+    # nothing. TAB/LF/CR are deliberately kept -- they are legitimate in text, and
+    # the scheme patterns below tolerate them explicitly instead. The C1 range
+    # (\x80-\x9f) is deliberately NOT stripped: those bytes are UTF-8 continuation
+    # bytes, and removing them would mangle legitimate multibyte text.
+    CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/
+
+    # Event-handler attribute stems. Each is matched as `<stem>\w*\s*=`, so a stem covers its
+    # whole family (`onmouse` → onmousedown/onmouseover/...).
+    UNSAFE_EVENT_HANDLERS = %w[
+      onabort onafter onbefore onbegin onblur oncanplay onchange onclick oncontextmenu oncopy oncuechange oncut
+      ondblclick ondrag ondrop ondurationchange onend onended onerror onfocus onhashchange oninvalid oninput onkey
+      onload onmessage onmouse ononline onoffline onpagehide onpageshow onpage onpaste onpause onplay onpopstate
+      onprogress onpropertychange onratechange onreadystatechange onrepeat onreset onresize onscroll onsearch onseek
+      onselect onshow onstalled onstorage onsubmit onsuspend ontimeupdate ontoggle onunload onvolumechange onwaiting
+      onwheel
+    ].freeze
+
+    # One alternation over all stems instead of 58 separate scans of the full buffer — the same
+    # `<stem>\w*\s*=` match, folded into a single pass.
+    UNSAFE_EVENT_PATTERN = /(?:#{Regexp.union(UNSAFE_EVENT_HANDLERS).source})\w*\s*=/i
+
+    # Elements able to navigate, exfiltrate, or load remote active content.
+    # Longest-first so "frameset" is preferred over "frame".
+    BLOCKED_ELEMENTS = %w[
+      script iframe object embed base meta style form applet frameset frame link template portal marquee math
+    ].freeze
+
+    # "/" counts as a tag delimiter, so <script/src="..."> cannot evade the check.
+    BLOCKED_ELEMENT_PATTERN = %r{</?(#{Regexp.union(BLOCKED_ELEMENTS).source})[\s/>]}i
+
+    # Script schemes are dangerous in any URI position.
+    SCRIPT_SCHEMES = %w[javascript vbscript].freeze
+
+    # A browser interprets a data: URI by its media type, so data:image/png;base64,... is an inert
+    # bitmap (Inkscape/Figma embed rasters this way and such files must upload), while data:text/html
+    # and data:image/svg+xml carry active content. These raster media types are therefore allowed;
+    # every other data: URI is blocked.
+    DATA_URI_SAFE_MEDIA = %w[
+      image/png image/gif image/jpeg image/jpg image/webp image/bmp image/avif
+      image/x-icon image/vnd.microsoft.icon
+    ].freeze
+
+    # Characters the URL parser strips from inside a scheme ("jav<TAB>ascript:" executes as
+    # javascript:). blocked_scheme_in? deletes these before matching, so the pattern itself stays a
+    # cheap contiguous alternation instead of an `[\t\n\r]*` between every character -- the latter
+    # backtracked into seconds of CPU on adversarial near-miss input. Deliberately not all of \s: a
+    # space is not stripped, so "Sample data : 42" stays prose, never a working URI.
+    SCHEME_GAP_CHARS = "\t\n\r"
+
+    # An allowlisted raster media type ending at a data-URI delimiter (;/,), a markup boundary
+    # (whitespace/quote/>/)), or end of input -- so "image/pngx" is not mistaken for "image/png".
+    DATA_URI_SAFE_MEDIA_PATTERN = /(?:#{Regexp.union(DATA_URI_SAFE_MEDIA).source})(?=[;,\s"'>)]|\z)/i
+
+    # javascript:/vbscript: are always blocked. data: is blocked only when it is a functional data URI
+    # -- a media type, or a bare ;/, delimiter -- that is NOT an allowlisted raster image; prose that
+    # merely contains "...data:" has no such continuation and is left alone. Gaps are deleted by
+    # blocked_scheme_in? before this matches, so the scheme and media type are written contiguously.
+    BLOCKED_SCHEME_PATTERN = Regexp.new(
+      "(?:#{Regexp.union(SCRIPT_SCHEMES).source}):" \
+      "|data:(?!#{DATA_URI_SAFE_MEDIA_PATTERN.source})(?:[a-z0-9.+-]+/[a-z0-9.+-]+|[;,])",
+      Regexp::IGNORECASE
+    )
+
+    SUSPICIOUS_PATTERNS = [
+      UNSAFE_EVENT_PATTERN,
+      BLOCKED_ELEMENT_PATTERN
+    ].freeze
+
+    # True if `content` carries a blocked URI scheme. Normalizes (entity/control-char decoding)
+    # first -- use this when you hold raw bytes (the SVG scanner). The non-SVG ruleset normalizes
+    # once for all its patterns and calls blocked_scheme_in? directly to avoid a second full copy.
+    def self.blocked_scheme?(content)
+      return false if content.nil?
+
+      blocked_scheme_in?(normalize(content))
+    end
+
+    # Same test against already-normalized content. The gap bytes a browser strips inside a scheme
+    # are removed here so BLOCKED_SCHEME_PATTERN can stay a cheap contiguous match rather than
+    # backtracking through an `[\t\n\r]*` between every character.
+    def self.blocked_scheme_in?(normalized)
+      return false if normalized.nil?
+
+      normalized.delete(SCHEME_GAP_CHARS).match?(BLOCKED_SCHEME_PATTERN)
+    end
+
+    # Byte-level backstop for markup, immune to the encoding a parser autodetects. A markup parser
+    # picks its encoding from in-band signals (a BOM, an XML declaration, a `<meta charset>`) that a
+    # browser can resolve differently -- WHATWG maps a `utf-16`/`utf-32` `<meta charset>` back to
+    # UTF-8, so a pure-ASCII document declaring utf-16 fires its handlers in the browser while the
+    # parser re-decodes the bytes as utf-16 and sees none. Stripping the NUL/C0 padding collapses a
+    # UTF-16/UTF-32 (or spoofed-declaration) handler down to the ASCII bytes the browser will run,
+    # so the element and handler patterns match it regardless of the declared encoding.
+    #
+    # Deliberately does NOT entity-decode, unlike `normalize`: character references in a tag or
+    # attribute NAME are never decoded by a browser (`on&#99;lick` is an inert attribute, not
+    # `onclick`), so decoding would buy no coverage while turning escaped markup (`&lt;script&gt;`,
+    # which a browser renders as text) into a false positive. The scheme check keeps using
+    # `blocked_scheme?`, which does normalize, because a scheme in an attribute VALUE is decoded.
+    def self.suspicious_markup_bytes?(content)
+      return false if content.nil?
+
+      stripped = content.dup.force_encoding(Encoding::BINARY).gsub(CONTROL_CHARS, '')
+      UNSAFE_EVENT_PATTERN.match?(stripped) || BLOCKED_ELEMENT_PATTERN.match?(stripped)
+    end
+
+    # Canonicalizes content so encoded variants of a blocked pattern are detected.
+    # Returns a normalized copy; the stored file is never modified.
+    #
+    # Deliberately entity-decoding only, NOT percent-decoding -- unlike
+    # UserUrlValidator, which percent-decodes because its input is a URL that gets
+    # parsed and resolved, where "%252e%252e" really does become "..". Here the input
+    # is file content a browser parses as markup: "&#x61;" really does become "a" in
+    # an attribute, but a percent-escape does not. Per the URL spec the scheme is
+    # matched literally, so "%6Aavascript:" and "javascript%3Aalert(1)" are not
+    # schemes at all and never execute. Percent-decoding here would buy no coverage
+    # and would reject legitimate files that merely contain encoded URLs (JSON
+    # exports, CSVs of links, access logs).
+    def self.normalize(content)
+      return content if content.nil?
+
+      normalized = content.dup.force_encoding(Encoding::BINARY)
+      normalized = decode_entities(normalized) if normalized.include?('&')
+      normalized = normalized.gsub(CONTROL_CHARS, '') if CONTROL_CHARS.match?(normalized)
+      normalized
+    end
+
+    # Repeatedly decodes HTML entities until stable, capped at DECODE_PASSES so a
+    # deliberately deep chain cannot spin. Falls back to the last good value if a
+    # decode produces bytes that cannot be handled.
+    def self.decode_entities(content)
+      DECODE_PASSES.times do
+        decoded = CGI.unescapeHTML(content).force_encoding(Encoding::BINARY)
+        break if decoded == content
+
+        content = decoded
+      end
+      content
+    rescue ArgumentError, Encoding::CompatibilityError
+      content
+    end
+  end
+end

data/lib/camaleon_cms/engine.rb

@@ -14,17 +14,9 @@ require 'dartsass-sprockets'
 require 'cama_contact_form'
 require 'cama_meta_tag'
 
-# `factory_bot_rails` gem can be added to test, development and/or other environments in the main app, containing the
-# `camaleon_cms` gem.
-# So, being unknown, whether it is defined or not, we're trying requiring the gem, using `rescue` in case of failures.
-begin
-  require 'factory_bot_rails'
-rescue LoadError
-  # do nothing
-end
-
 $camaleon_engine_dir = File.expand_path('../..', __dir__)
 require File.join($camaleon_engine_dir, 'lib', 'plugin_routes').to_s
+require File.join($camaleon_engine_dir, 'lib', 'camaleon_cms', 'setup_token').to_s
 Dir[File.join($camaleon_engine_dir, 'lib', 'ext', '**', '*.rb')].sort.each { |f| require f }
 require 'draper'
 
@@ -43,6 +35,16 @@ module CamaleonCms
       end
     end
 
+    # Security (audit 2026-08-11 M9): redact credential-bearing parameters from the Rails logs. The site
+    # settings form submits the SMTP password and S3 keys in the clear (options[email_pass],
+    # options[filesystem_s3_access_key], options[filesystem_s3_secret_key]), as do user passwords, the
+    # installer gate token (setup_token, matched by :token) and the stored password of a
+    # password-protected post (post[visibility_value]), and the engine set no filter. Appended (+=) so
+    # a host app's own filters are preserved.
+    initializer 'camaleon_cms.filter_parameters' do |app|
+      app.config.filter_parameters += %i[passw email_pass secret access_key token visibility_value]
+    end
+
     initializer :append_migrations do |app|
       engine_dir = File.expand_path('../..', __dir__)
       translation_files = Dir[File.join($camaleon_engine_dir, 'config', 'locales', '**', '*.{rb,yml}')]
@@ -53,14 +55,15 @@ module CamaleonCms
       app.config.i18n.load_path.unshift(*translation_files)
 
       # assets
-      app.config.assets.paths << Rails.root.join('app', 'apps')
-      app.config.assets.paths << Rails.root.join('app', 'assets', 'fonts')
+      app.config.assets.paths << Rails.root.join('app/apps')
+      app.config.assets.paths << Rails.root.join('app/assets/fonts')
       app.config.assets.paths << File.join($camaleon_engine_dir, 'app', 'apps')
       app.config.assets.paths << File.join($camaleon_engine_dir, 'app', 'assets', 'fonts')
       app.config.encoding = 'utf-8'
 
       # add prefix url, like: https://localhost.com/blog/
-      # config.action_controller.relative_url_root = PluginRoutes.system_info["relative_url_root"] if PluginRoutes.system_info["relative_url_root"].present?
+      # config.action_controller.relative_url_root =
+      # PluginRoutes.system_info["relative_url_root"] if PluginRoutes.system_info["relative_url_root"].present?
 
       # multiple route files
       app.routes_reloader.paths.push(File.join(engine_dir, 'config', 'routes', 'admin.rb'))
@@ -71,15 +74,25 @@ module CamaleonCms
       app.config.eager_load_paths += %W[#{app.config.root}/app/apps/]
       if PluginRoutes.static_system_info['auto_include_migrations']
         PluginRoutes.all_plugins.each do |plugin|
-          app.config.paths['db/migrate'] << File.join(plugin['path'], 'migrate') if Dir.exist?(File.join(
-                                                                                                 plugin['path'], 'migrate'
-                                                                                               ))
-          app.config.paths['db/migrate'] << File.join(plugin['path'], 'db', 'migrate') if Dir.exist?(File.join(
-                                                                                                       plugin['path'], 'db', 'migrate'
-                                                                                                     ))
+          if Dir.exist?(File.join(plugin['path'], 'migrate'))
+            app.config.paths['db/migrate'] << File.join(plugin['path'], 'migrate')
+          end
+
+          if Dir.exist?(File.join(plugin['path'], 'db', 'migrate'))
+            app.config.paths['db/migrate'] << File.join(plugin['path'], 'db', 'migrate')
+          end
         end
       end
 
+      # Security headers for SVG media files. ActionDispatch::Static is only in the host
+      # stack when public_file_server is enabled; anchoring on it unconditionally aborts
+      # boot on hosts that serve public/ from nginx/Apache.
+      if app.config.public_file_server.enabled
+        app.middleware.insert_before ::ActionDispatch::Static, CamaleonCms::MediaSecurityHeaders
+      else
+        app.middleware.use CamaleonCms::MediaSecurityHeaders
+      end
+
       # Static files
       app.middleware.use ::ActionDispatch::Static, "#{root}/public"
 
@@ -91,9 +104,20 @@ module CamaleonCms
       end
     end
 
-    if defined?(FactoryBotRails)
-      config.factory_bot.definition_file_paths +=
-        [File.expand_path('../../spec/factories', __dir__)]
+    # Draw the route table at boot so the first request is never served against a half-built set
+    # of routes (see PluginRoutes.draw_routes_eagerly). Closes the development-mode window where
+    # the first request after a restart races the multi-site route draw; a no-op once drawn.
+    #
+    # Runs as a config.after_initialize callback, NOT as a named `initializer ... after:
+    # :set_routes_reloader_hook`. Anchoring a CamaleonCms::Engine initializer to that late Finisher
+    # hook adds a cross-cutting edge to Rails' initializer tsort that reorders the `append_assets_path`
+    # initializers and drops engine/host asset load paths from config.assets.paths -- gem-packaged
+    # plugin assets and core camaleon_cms images then raise AssetNotPrecompiledError and 500 the site
+    # (regression fixed here). after_initialize runs once the whole boot -- routes reloader, internal
+    # routes and every engine's asset path -- is assembled, so the draw still reflects the final route
+    # set without perturbing initializer ordering.
+    config.after_initialize do
+      PluginRoutes.draw_routes_eagerly
     end
   end
 end

data/lib/camaleon_cms/media_security_headers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CamaleonCms
+  class MediaSecurityHeaders
+    # Case-insensitive: an `evil.SVG` is stored and served verbatim (get_file_format downcases
+    # the extension), so a case-sensitive match left uppercase-extension SVGs served inline
+    # without the protective headers.
+    SVG_PATH_PATTERN = %r{\A/media/.*\.svg\z}i
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      if env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO']&.match?(SVG_PATH_PATTERN)
+        # Lowercase header keys: the Rack 3 SPEC requires them and Falcon/Rack::Lint reject
+        # mixed case (Puma tolerated it, which hid this).
+        headers['x-content-type-options'] = 'nosniff'
+        headers['content-security-policy'] = "script-src 'none'"
+      end
+
+      [status, headers, body]
+    end
+  end
+end

data/lib/camaleon_cms/setup_token.rb

@@ -0,0 +1,69 @@
+require 'securerandom'
+require 'fileutils'
+
+module CamaleonCms
+  # Gates the first-run installer so setup can be completed only by someone with access to the
+  # server's environment or filesystem — not by any anonymous visitor who reaches the app on a fresh
+  # deploy (audit finding C1, vector 2). The expected token comes from ENV['CAMALEON_SETUP_TOKEN']
+  # when set, otherwise from a generated 0600 file under tmp/; generating it logs its location once so
+  # the operator can read it. It is required only while no site exists, and is cleared once one does.
+  # See openspec/specs/installer-access-control/spec.md.
+  module SetupToken
+    ENV_KEY = 'CAMALEON_SETUP_TOKEN'.freeze
+
+    module_function
+
+    # The installer is gated only until the first site exists; afterwards it is closed anyway.
+    def required?
+      CamaleonCms::Site.count == 0
+    rescue StandardError
+      false
+    end
+
+    # The expected token: an explicit ENV override wins; otherwise a generated file (created on first
+    # read). Returns nil only if no ENV value is set and the file cannot be created.
+    def value
+      env = ENV[ENV_KEY].to_s
+      return env if env.present?
+
+      read_or_generate_file
+    end
+
+    # Constant-time comparison; false for a blank candidate or when no expected token is available.
+    def valid?(candidate)
+      candidate = candidate.to_s
+      expected = value.to_s
+      return false if candidate.empty? || expected.empty?
+
+      ActiveSupport::SecurityUtils.secure_compare(candidate, expected)
+    end
+
+    # Invalidate the generated token once setup has completed (the ENV override, if any, is untouched).
+    def clear!
+      File.delete(file_path) if File.exist?(file_path)
+    rescue StandardError
+      nil
+    end
+
+    def file_path
+      Rails.root.join('tmp/camaleon_setup_token').to_s
+    end
+
+    def read_or_generate_file
+      return File.read(file_path).strip if File.exist?(file_path)
+
+      token = SecureRandom.hex(32)
+      FileUtils.mkdir_p(File.dirname(file_path))
+      # 0600 from the first byte (write-then-chmod would leave a world-readable window at default
+      # umask), EXCL so a concurrent generator cannot clobber a token already handed to an operator.
+      File.open(file_path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |f| f.write(token) }
+      Rails.logger.info("Camaleon CMS: setup token written to #{file_path} — required to run the installer.")
+      token
+    rescue Errno::EEXIST
+      # Lost the creation race between the exist? check and the open: adopt the winner's token.
+      read_or_generate_file
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/camaleon_cms/shortcode_registry.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module CamaleonCms
+  # Process-wide, boot-time registry of shortcode NAMES. It exists so that save-time code can detect
+  # shortcodes without a frontend request: the per-request `CurrentRequest.shortcodes` list is
+  # populated by the active frontend theme's `front_before_load` hook and is therefore empty in the
+  # admin save path, so the save-time gate consults this canonical set instead.
+  #
+  # Providers declare their shortcode names through the `register` DSL at boot. Declarations run with
+  # NO request/site context, so a declaration MUST NOT touch `current_site`/`request` -- only the
+  # names move here; the render-time handler stays in `shortcode_add`. Core declares its own bundled
+  # names (see CORE_SHORTCODES); a theme/plugin gem declares its names from its own boot (an
+  # initializer or engine), e.g. `CamaleonCms::ShortcodeRegistry.register('redirect')`.
+  #
+  # Detection mirrors the engine's `ShortCodeHelper#cama_reg_shortcode` regex shape, sourced from
+  # this registry rather than `CurrentRequest`, so a name is a match only when followed by a space +
+  # attributes or an immediate "]" -- bracketed prose that is not a registered name is never treated
+  # as a shortcode.
+  #
+  # Fail-closed (design D4): an "unavailable" registry -- boot never completed registration -- treats
+  # any non-blank content as gated, so a non-administrator is refused rather than let through on an
+  # empty set. A legitimately empty registry (available, but no provider declared any name) is a
+  # distinct, non-error state that gates nothing.
+  class ShortcodeRegistry
+    # Core-bundled shortcode names, declared through the DSL at boot. Mirrors the shortcodes that
+    # `ShortCodeHelper#shortcodes_init` adds per request; the two are kept in sync by hand (unifying
+    # the boot DSL with the render-time `shortcode_add` registration is a deliberate non-goal -- see
+    # the gate-content-shortcodes design).
+    CORE_SHORTCODES = %w[widget load_libraries asset data].freeze
+
+    class << self
+      # Boot-time DSL: declare one or more shortcode names. Request-independent, idempotent, and
+      # order-independent. Blank names are ignored.
+      def register(*names)
+        names.flatten.each do |name|
+          name = name.to_s.strip
+          registered_names << name unless name.empty?
+        end
+        @regexp = nil
+        self
+      end
+
+      # Mark the registry as successfully built at boot. Called once registration has completed; if
+      # boot raises before this point the registry stays unavailable and detection fails closed.
+      def mark_available!
+        @available = true
+        self
+      end
+
+      def available?
+        @available == true
+      end
+
+      # Frozen snapshot of the registered names.
+      def names
+        registered_names.dup.freeze
+      end
+
+      # Whether `content` contains a registered shortcode. Fails closed when the registry is
+      # unavailable (any non-blank content is treated as gated); a legitimately empty registry
+      # matches nothing.
+      def content_has_shortcode?(content)
+        content = content.to_s
+        return false if content.empty?
+        return true unless available?
+
+        matcher = regexp
+        return false if matcher.nil?
+
+        matcher.match?(content)
+      end
+
+      # Test-only: reset to the unavailable/empty baseline.
+      def reset!
+        @registered_names = nil
+        @regexp = nil
+        @available = false
+        self
+      end
+
+      private
+
+      def registered_names
+        @registered_names ||= Set.new
+      end
+
+      # Mirrors ShortCodeHelper#cama_reg_shortcode: "(\\[(a|b)((\s)((?!\\]).)*|)\\])". In that source
+      # the "\s" is a literal space (a double-quoted-string escape, not the regex whitespace class),
+      # so a code matches only when followed by a literal space + attributes, or an immediate "]".
+      # Names are regex-escaped and ordered longest-first so a name that is a prefix of another
+      # (e.g. media / media_gallery) still matches its own token.
+      def regexp
+        return nil if registered_names.empty?
+
+        @regexp ||= begin
+          codes = registered_names.sort_by { |name| -name.length }.map { |name| Regexp.escape(name) }.join('|')
+          Regexp.new("(\\[(#{codes})((\s)((?!\\]).)*|)\\])")
+        end
+      end
+    end
+  end
+end

data/lib/camaleon_cms/svg_content_checker.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module CamaleonCms
+  # Parse-based rejection for uploads a browser parses as markup.
+  #
+  # Named for SVG because that is where it started; it now serves every markup extension the
+  # scanner routes here (see UploaderContentSecurity::MARKUP_EXTENSIONS). The reason is the reason
+  # it replaced the regex denylist for SVG: event handlers are rejected *by shape* — any attribute
+  # whose name begins with `on` — so no handler name is ever enumerated, and a handler the web
+  # platform ships next year is refused without a code change. A name list cannot make that promise;
+  # the one in ContentSecurity is missing `onpointer*`, `ontouch*` and `onauxclick` today.
+  module SvgContentChecker
+    # `animate` and `set` are intentionally absent: SMIL animation elements carry no
+    # script by themselves, and their scripting vector is the onbegin/onend/onrepeat
+    # attribute, which the element-agnostic on* check below rejects wherever it appears.
+    # foreignObject and handler stay banned — they embed foreign markup or handlers.
+    #
+    # form/meta/base/style/link are valid in SVG and none executes script on its own, but an
+    # uploaded SVG is served inline from the site origin and these five are what turn a passive
+    # image into markup that can navigate (meta http-equiv=refresh, base href), collect input
+    # (form), or pull in remote styling (link, style). This list only ever runs for uploads that are
+    # being scanned at all, i.e. from uploaders without `media_unfiltered_upload`, so it needs no
+    # trust argument.
+    SVG_BANNED_TAGS = %w[
+      script foreignObject iframe object embed handler form meta base style link
+    ].freeze
+
+    # What the checker actually refuses: the SVG list above unioned with the generic ruleset's
+    # element denylist. The union is load-bearing, not tidiness. ContentSecurity::BLOCKED_ELEMENTS
+    # refuses `applet frameset frame template portal marquee math`, which SVG_BANNED_TAGS does not;
+    # routing `.html` here while checking only the SVG list would have *narrowed* what an HTML
+    # upload is refused for. Unioning means every extension routed here is refused for at least
+    # everything the ruleset it came from refused.
+    BANNED_TAGS = (SVG_BANNED_TAGS | ContentSecurity::BLOCKED_ELEMENTS).freeze
+
+    # Extensions parsed as HTML rather than XML. Kept here rather than inferred, because the two
+    # modes differ in what a parse failure means (see `parse_document`).
+    HTML_MODE = :html
+    XML_MODE = :xml
+
+    # Lowercasing tables for XPath translate(). The tag check folds case so a name an HTML parser
+    # lowercases is matched the same as its source form: `Nokogiri::HTML` reports `<foreignObject>`
+    # as `foreignobject`, and an SVG inlined into an HTML document fires `<SCRIPT>` exactly as
+    # `<script>`. Without folding, `foreignObject` -- the only mixed-case entry in BANNED_TAGS --
+    # would be refused as `.svg` (XML, case-sensitive) yet accepted as `.html`.
+    ASCII_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    ASCII_LOWER = 'abcdefghijklmnopqrstuvwxyz'
+
+    # The banned-element XPath, built once from the frozen BANNED_TAGS rather than reassembled on
+    # every scan: `//*[translate(local-name(),UPPER,LOWER)='tag' or ...]`, each tag folded to
+    # lowercase so an HTML-lowercased element name still matches.
+    BANNED_TAGS_XPATH = "//*[#{BANNED_TAGS.map do |tag|
+      "translate(local-name(), '#{ASCII_UPPER}', '#{ASCII_LOWER}') = '#{tag.downcase}'"
+    end.join(' or ')}]".freeze
+
+    module_function
+
+    # `mode:` defaults to :xml so the pre-existing single-argument call (`unsafe?(content)`) keeps
+    # its exact behaviour for any downstream caller.
+    def unsafe?(content, mode: XML_MODE)
+      return true if content.nil? || content.empty? # rubocop:disable Rails/Blank
+
+      doc = parse_document(content, mode)
+      return true if doc.nil? # XML syntax error -- fail closed
+
+      # XML mode only. A document that parses to nothing is not a valid document of its format, so
+      # refusing it fails closed. HTML has no such signal — Nokogiri::HTML never raises and reports
+      # a nil root for input as ordinary as a whitespace-only or comment-only file, which must be
+      # accepted. See design.md D3: the guarantee does not exist in HTML mode and is not faked.
+      return true if mode != HTML_MODE && doc.root.nil?
+
+      dangerous_document?(doc, mode)
+    end
+
+    def dangerous_document?(doc, mode)
+      return true if doc.xpath(BANNED_TAGS_XPATH).any?
+
+      # Case-insensitive: XML attribute names are case-sensitive, but an SVG inlined into an HTML
+      # document fires ONCLICK/OnClick exactly as onclick, and the non-SVG ruleset already matches
+      # handlers case-insensitively. translate() lowercases the "on" prefix so every case variant is
+      # caught (no standard attribute name in either format begins with "on" except an event
+      # handler). This is the shape match that makes the handler *name* irrelevant.
+      return true if doc.xpath('//@*[starts-with(translate(local-name(), "ON", "on"), "on")]').any?
+
+      # Blocked URI schemes via the shared ContentSecurity.blocked_scheme?, so the markup and generic
+      # rulesets cannot drift apart about the same bytes (audit 2026-08-11 NEW-1). Nokogiri decodes
+      # char-refs into attr.value but re-emits them in serialization, so the href is matched decoded
+      # while the serialized document is entity-decoded (normalized) inside the helper before the
+      # scheme match.
+      return true if doc.xpath('//@*[local-name() = "href"]').any? do |attr|
+        ContentSecurity.blocked_scheme?(attr.value)
+      end
+
+      dangerous_serialization?(doc, mode)
+    end
+
+    # Serialization echoes the document's declared encoding, so a UTF-16/UTF-32 document yields an
+    # ASCII-incompatible String. Matching an ASCII regex against it raises
+    # Encoding::CompatibilityError, which the rescue below does not catch -- surfacing as a 500
+    # on upload instead of a verdict. Force BINARY first: the byte scan stays correct (BANNED_TAGS
+    # already caught any <script> element, and normalize strips the interleaved NUL bytes of a
+    # non-UTF-8 encoding before the scheme match). Catches DTD entity declarations and CDATA
+    # sections, whose expansion is only visible after the parse.
+    def dangerous_serialization?(doc, mode)
+      serialized = (mode == HTML_MODE ? doc.to_html : doc.to_xml).b
+      return true if serialized.match?(/<script[\s>]/i)
+
+      ContentSecurity.blocked_scheme?(serialized)
+    end
+
+    # The rescue is confined to XML mode on purpose: Nokogiri::HTML never raises, so a shared rescue
+    # would be dead code implying a fail-closed guarantee that HTML mode cannot provide.
+    def parse_document(content, mode)
+      return Nokogiri::HTML(content) if mode == HTML_MODE
+
+      Nokogiri::XML(content, &:nonet)
+    rescue Nokogiri::XML::SyntaxError
+      nil
+    end
+
+    private_class_method :dangerous_document?, :dangerous_serialization?, :parse_document
+  end
+end

data/lib/camaleon_cms/task_reporter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CamaleonCms
+  # Output seam for operator-run repair tasks: logs for the record AND prints to
+  # stdout, because an operator runs these from a terminal, where Rails.logger
+  # writes to a file they are not watching — a logger-only task looks like a
+  # no-op. Shared so the reporting rule cannot drift between the repair tasks.
+  module TaskReporter
+    def self.call(msg)
+      Rails.logger.info(msg)
+      puts msg # rubocop:disable Rails/Output -- terminal output for the operator is the point
+    end
+  end
+end