loofah 2.20.0 → 2.21.0.rc1

data/lib/loofah.rb

@@ -1,8 +1,24 @@
 # frozen_string_literal: true
-$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__))) unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
 
 require "nokogiri"
 
+module Loofah
+  class << self
+    def html5_support?
+      # Note that Loofah can only support HTML5 in Nokogiri >= 1.14.0 because it requires the
+      # subclassing fix from https://github.com/sparklemotion/nokogiri/pull/2534
+      unless @html5_support_set
+        @html5_support = (
+          Gem::Version.new(Nokogiri::VERSION) > Gem::Version.new("1.14.0") &&
+          Nokogiri.uses_gumbo?
+        )
+        @html5_support_set = true
+      end
+      @html5_support
+    end
+  end
+end
+
 require_relative "loofah/version"
 require_relative "loofah/metahelpers"
 require_relative "loofah/elements"
@@ -14,51 +30,129 @@ require_relative "loofah/html5/scrub"
 require_relative "loofah/scrubber"
 require_relative "loofah/scrubbers"
 
-require_relative "loofah/instance_methods"
+require_relative "loofah/concerns"
 require_relative "loofah/xml/document"
 require_relative "loofah/xml/document_fragment"
-require_relative "loofah/html/document"
-require_relative "loofah/html/document_fragment"
+require_relative "loofah/html4/document"
+require_relative "loofah/html4/document_fragment"
+
+if Nokogiri.respond_to?(:uses_gumbo?) && Nokogiri.uses_gumbo?
+  require_relative "loofah/html5/document"
+  require_relative "loofah/html5/document_fragment"
+end
 
 # == Strings and IO Objects as Input
 #
-# Loofah.document and Loofah.fragment accept any IO object in addition
-# to accepting a string. That IO object could be a file, or a socket,
-# or a StringIO, or anything that responds to +read+ and
-# +close+. Which makes it particularly easy to sanitize mass
-# quantities of docs.
+# The following methods accept any IO object in addition to accepting a string:
+#
+# - Loofah.html4_document
+# - Loofah.html4_fragment
+# - Loofah.scrub_html4_document
+# - Loofah.scrub_html4_fragment
+#
+# - Loofah.html5_document
+# - Loofah.html5_fragment
+# - Loofah.scrub_html5_document
+# - Loofah.scrub_html5_fragment
+#
+# - Loofah.xml_document
+# - Loofah.xml_fragment
+# - Loofah.scrub_xml_document
+# - Loofah.scrub_xml_fragment
+#
+# - Loofah.document
+# - Loofah.fragment
+# - Loofah.scrub_document
+# - Loofah.scrub_fragment
+#
+# That IO object could be a file, or a socket, or a StringIO, or anything that responds to +read+
+# and +close+.
 #
 module Loofah
+  # Alias for Loofah::HTML4
+  HTML = HTML4
+
   class << self
-    # Shortcut for Loofah::HTML::Document.parse
-    # This method accepts the same parameters as Nokogiri::HTML::Document.parse
-    def document(*args, &block)
-      remove_comments_before_html_element Loofah::HTML::Document.parse(*args, &block)
+    # Shortcut for Loofah::HTML4::Document.parse(*args, &block)
+    #
+    # This method accepts the same parameters as Nokogiri::HTML4::Document.parse
+    def html4_document(*args, &block)
+      Loofah::HTML4::Document.parse(*args, &block)
     end
 
-    # Shortcut for Loofah::HTML::DocumentFragment.parse
-    # This method accepts the same parameters as Nokogiri::HTML::DocumentFragment.parse
-    def fragment(*args, &block)
-      Loofah::HTML::DocumentFragment.parse(*args, &block)
+    # Shortcut for Loofah::HTML4::DocumentFragment.parse(*args, &block)
+    #
+    # This method accepts the same parameters as Nokogiri::HTML4::DocumentFragment.parse
+    def html4_fragment(*args, &block)
+      Loofah::HTML4::DocumentFragment.parse(*args, &block)
     end
 
-    # Shortcut for Loofah.fragment(string_or_io).scrub!(method)
-    def scrub_fragment(string_or_io, method)
-      Loofah.fragment(string_or_io).scrub!(method)
+    # Shortcut for Loofah::HTML4::Document.parse(string_or_io).scrub!(method)
+    def scrub_html4_document(string_or_io, method)
+      Loofah::HTML4::Document.parse(string_or_io).scrub!(method)
     end
 
-    # Shortcut for Loofah.document(string_or_io).scrub!(method)
-    def scrub_document(string_or_io, method)
-      Loofah.document(string_or_io).scrub!(method)
+    # Shortcut for Loofah::HTML4::DocumentFragment.parse(string_or_io).scrub!(method)
+    def scrub_html4_fragment(string_or_io, method)
+      Loofah::HTML4::DocumentFragment.parse(string_or_io).scrub!(method)
     end
 
-    # Shortcut for Loofah::XML::Document.parse
+    if Loofah.html5_support?
+      # Shortcut for Loofah::HTML5::Document.parse(*args, &block)
+      #
+      # This method accepts the same parameters as Nokogiri::HTML5::Document.parse
+      def html5_document(*args, &block)
+        Loofah::HTML5::Document.parse(*args, &block)
+      end
+
+      # Shortcut for Loofah::HTML5::DocumentFragment.parse(*args, &block)
+      #
+      # This method accepts the same parameters as Nokogiri::HTML5::DocumentFragment.parse
+      def html5_fragment(*args, &block)
+        Loofah::HTML5::DocumentFragment.parse(*args, &block)
+      end
+
+      # Shortcut for Loofah::HTML5::Document.parse(string_or_io).scrub!(method)
+      def scrub_html5_document(string_or_io, method)
+        Loofah::HTML5::Document.parse(string_or_io).scrub!(method)
+      end
+
+      # Shortcut for Loofah::HTML5::DocumentFragment.parse(string_or_io).scrub!(method)
+      def scrub_html5_fragment(string_or_io, method)
+        Loofah::HTML5::DocumentFragment.parse(string_or_io).scrub!(method)
+      end
+    else
+      def html5_document(*args, &block)
+        raise NotImplementedError, "HTML5 is not supported by your version of Nokogiri"
+      end
+
+      def html5_fragment(*args, &block)
+        raise NotImplementedError, "HTML5 is not supported by your version of Nokogiri"
+      end
+
+      def scrub_html5_document(string_or_io, method)
+        raise NotImplementedError, "HTML5 is not supported by your version of Nokogiri"
+      end
+
+      def scrub_html5_fragment(string_or_io, method)
+        raise NotImplementedError, "HTML5 is not supported by your version of Nokogiri"
+      end
+    end
+
+    alias_method :document, :html4_document
+    alias_method :fragment, :html4_fragment
+    alias_method :scrub_document, :scrub_html4_document
+    alias_method :scrub_fragment, :scrub_html4_fragment
+
+    # Shortcut for Loofah::XML::Document.parse(*args, &block)
+    #
     # This method accepts the same parameters as Nokogiri::XML::Document.parse
     def xml_document(*args, &block)
       Loofah::XML::Document.parse(*args, &block)
     end
 
-    # Shortcut for Loofah::XML::DocumentFragment.parse
+    # Shortcut for Loofah::XML::DocumentFragment.parse(*args, &block)
+    #
     # This method accepts the same parameters as Nokogiri::XML::DocumentFragment.parse
     def xml_fragment(*args, &block)
       Loofah::XML::DocumentFragment.parse(*args, &block)
@@ -78,23 +172,5 @@ module Loofah
     def remove_extraneous_whitespace(string)
       string.gsub(/\n\s*\n\s*\n/, "\n\n")
     end
-
-    private
-
-    # remove comments that exist outside of the HTML element.
-    #
-    # these comments are allowed by the HTML spec:
-    #
-    #    https://www.w3.org/TR/html401/struct/global.html#h-7.1
-    #
-    # but are not scrubbed by Loofah because these nodes don't meet
-    # the contract that scrubbers expect of a node (e.g., it can be
-    # replaced, sibling and children nodes can be created).
-    def remove_comments_before_html_element(doc)
-      doc.children.each do |child|
-        child.unlink if child.comment?
-      end
-      doc
-    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: loofah
 version: !ruby/object:Gem::Version
-  version: 2.20.0
+  version: 2.21.0.rc1
 platform: ruby
 authors:
 - Mike Dalessio
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-01 00:00:00.000000000 Z
+date: 2023-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: crass
@@ -39,102 +39,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.9
-- !ruby/object:Gem::Dependency
-  name: hoe-markdown
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: json
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.2'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.14'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.14'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '7'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-description: |-
-  Loofah is a general library for manipulating and transforming HTML/XML documents and fragments, built on top of Nokogiri.
-
-  Loofah excels at HTML sanitization (XSS prevention). It includes some nice HTML sanitizers, which are based on HTML5lib's safelist, so it most likely won't make your codes less secure. (These statements have not been evaluated by Netexperts.)
+description: |
+  Loofah is a general library for manipulating and transforming HTML/XML documents and fragments,
+  built on top of Nokogiri.
 
-  ActiveRecord extensions for sanitization are available in the [`loofah-activerecord` gem](https://github.com/flavorjones/loofah-activerecord).
+  Loofah also includes some HTML sanitizers based on `html5lib`'s safelist, which are a specific
+  application of the general transformation functionality.
 email:
 - mike.dalessio@gmail.com
 - bryan@brynary.com
@@ -147,14 +57,16 @@ files:
 - README.md
 - SECURITY.md
 - lib/loofah.rb
+- lib/loofah/concerns.rb
 - lib/loofah/elements.rb
 - lib/loofah/helpers.rb
-- lib/loofah/html/document.rb
-- lib/loofah/html/document_fragment.rb
+- lib/loofah/html4/document.rb
+- lib/loofah/html4/document_fragment.rb
+- lib/loofah/html5/document.rb
+- lib/loofah/html5/document_fragment.rb
 - lib/loofah/html5/libxml2_workarounds.rb
 - lib/loofah/html5/safelist.rb
 - lib/loofah/html5/scrub.rb
-- lib/loofah/instance_methods.rb
 - lib/loofah/metahelpers.rb
 - lib/loofah/scrubber.rb
 - lib/loofah/scrubbers.rb
@@ -181,13 +93,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: Loofah is a general library for manipulating and transforming HTML/XML documents
-  and fragments, built on top of Nokogiri
+  and fragments, built on top of Nokogiri.
 test_files: []

data/lib/loofah/html/document_fragment.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-module Loofah
-  module HTML # :nodoc:
-    #
-    #  Subclass of Nokogiri::HTML::DocumentFragment.
-    #
-    #  See Loofah::ScrubBehavior and Loofah::TextBehavior for additional methods.
-    #
-    class DocumentFragment < Nokogiri::HTML::DocumentFragment
-      include Loofah::TextBehavior
-
-      class << self
-        #
-        #  Overridden Nokogiri::HTML::DocumentFragment
-        #  constructor. Applications should use Loofah.fragment to
-        #  parse a fragment.
-        #
-        def parse(tags, encoding = nil)
-          doc = Loofah::HTML::Document.new
-
-          encoding ||= tags.respond_to?(:encoding) ? tags.encoding.name : "UTF-8"
-          doc.encoding = encoding
-
-          new(doc, tags)
-        end
-      end
-
-      #
-      #  Returns the HTML markup contained by the fragment
-      #
-      def to_s
-        serialize_root.children.to_s
-      end
-
-      alias :serialize :to_s
-
-      def serialize_root
-        at_xpath("./body") || self
-      end
-    end
-  end
-end

data/lib/loofah/instance_methods.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-module Loofah
-  #
-  #  Mixes +scrub!+ into Document, DocumentFragment, Node and NodeSet.
-  #
-  #  Traverse the document or fragment, invoking the +scrubber+ on
-  #  each node.
-  #
-  #  +scrubber+ must either be one of the symbols representing the
-  #  built-in scrubbers (see Scrubbers), or a Scrubber instance.
-  #
-  #    span2div = Loofah::Scrubber.new do |node|
-  #      node.name = "div" if node.name == "span"
-  #    end
-  #    Loofah.fragment("<span>foo</span><p>bar</p>").scrub!(span2div).to_s
-  #    # => "<div>foo</div><p>bar</p>"
-  #
-  #  or
-  #
-  #    unsafe_html = "ohai! <div>div is safe</div> <script>but script is not</script>"
-  #    Loofah.fragment(unsafe_html).scrub!(:strip).to_s
-  #    # => "ohai! <div>div is safe</div> "
-  #
-  #  Note that this method is called implicitly from
-  #  Loofah.scrub_fragment and Loofah.scrub_document.
-  #
-  #  Please see Scrubber for more information on implementation and traversal, and
-  #  README.rdoc for more example usage.
-  #
-  module ScrubBehavior
-    module Node # :nodoc:
-      def scrub!(scrubber)
-        #
-        #  yes. this should be three separate methods. but nokogiri
-        #  decorates (or not) based on whether the module name has
-        #  already been included. and since documents get decorated
-        #  just like their constituent nodes, we need to jam all the
-        #  logic into a single module.
-        #
-        scrubber = ScrubBehavior.resolve_scrubber(scrubber)
-        case self
-        when Nokogiri::XML::Document
-          scrubber.traverse(root) if root
-        when Nokogiri::XML::DocumentFragment
-          children.scrub! scrubber
-        else
-          scrubber.traverse(self)
-        end
-        self
-      end
-    end
-
-    module NodeSet # :nodoc:
-      def scrub!(scrubber)
-        each { |node| node.scrub!(scrubber) }
-        self
-      end
-    end
-
-    def ScrubBehavior.resolve_scrubber(scrubber) # :nodoc:
-      scrubber = Scrubbers::MAP[scrubber].new if Scrubbers::MAP[scrubber]
-      unless scrubber.is_a?(Loofah::Scrubber)
-        raise Loofah::ScrubberNotFound, "not a Scrubber or a scrubber name: #{scrubber.inspect}"
-      end
-      scrubber
-    end
-  end
-
-  #
-  #  Overrides +text+ in HTML::Document and HTML::DocumentFragment,
-  #  and mixes in +to_text+.
-  #
-  module TextBehavior
-    #
-    #  Returns a plain-text version of the markup contained by the document,
-    #  with HTML entities encoded.
-    #
-    #  This method is significantly faster than #to_text, but isn't
-    #  clever about whitespace around block elements.
-    #
-    #    Loofah.document("<h1>Title</h1><div>Content</div>").text
-    #    # => "TitleContent"
-    #
-    #  By default, the returned text will have HTML entities
-    #  escaped. If you want unescaped entities, and you understand
-    #  that the result is unsafe to render in a browser, then you
-    #  can pass an argument as shown:
-    #
-    #    frag = Loofah.fragment("&lt;script&gt;alert('EVIL');&lt;/script&gt;")
-    #    # ok for browser:
-    #    frag.text                                 # => "&lt;script&gt;alert('EVIL');&lt;/script&gt;"
-    #    # decidedly not ok for browser:
-    #    frag.text(:encode_special_chars => false) # => "<script>alert('EVIL');</script>"
-    #
-    def text(options = {})
-      result = if serialize_root
-        serialize_root.children.reject(&:comment?).map(&:inner_text).join("")
-      else
-        ""
-      end
-      if options[:encode_special_chars] == false
-        result # possibly dangerous if rendered in a browser
-      else
-        encode_special_chars result
-      end
-    end
-
-    alias :inner_text :text
-    alias :to_str :text
-
-    #
-    #  Returns a plain-text version of the markup contained by the
-    #  fragment, with HTML entities encoded.
-    #
-    #  This method is slower than #text, but is clever about
-    #  whitespace around block elements and line break elements.
-    #
-    #    Loofah.document("<h1>Title</h1><div>Content<br>Next line</div>").to_text
-    #    # => "\nTitle\n\nContent\nNext line\n"
-    #
-    def to_text(options = {})
-      Loofah.remove_extraneous_whitespace self.dup.scrub!(:newline_block_elements).text(options)
-    end
-  end
-
-  module DocumentDecorator # :nodoc:
-    def initialize(*args, &block)
-      super
-      self.decorators(Nokogiri::XML::Node) << ScrubBehavior::Node
-      self.decorators(Nokogiri::XML::NodeSet) << ScrubBehavior::NodeSet
-    end
-  end
-end