loofah-activerecord 1.0.0.beta.1

data/README.rdoc

@@ -0,0 +1,110 @@
+= loofah-activerecord
+
+* http://github.com/flavorjones/loofah-activerecord
+* http://loofah.rubyforge.org
+* http://rubyforge.org/projects/loofah
+
+== Description
+
+loofah-activerecord extends loofah's HTML sanitization into Rails
+ActiveRecord models.
+
+== Features
+
+* Two ActiveRecord extensions:
+  * Loofah::XssFoliate, an XssTerminate[http://github.com/look/xss_terminate/tree/master] drop-in replacement, is an *opt-out* sanitizer. By default all models and attributes are sanitized.
+  * Loofah::ActiveRecordExtension is an *opt-in* sanitizer. You must explicitly declare attributes to be sanitized.
+
+=== ActiveRecord Extension \#1: Opt-In
+
+See Loofah::ActiveRecordExtension for full documentation. The methods
+mixed into ActiveRecord are:
+
+* Loofah::ActiveRecordExtension.html_document
+* Loofah::ActiveRecordExtension.html_fragment
+
+which are used to declare how specific string and text attributes
+should be scrubbed at +before_validation+.
+
+  # app/model/post.rb
+  class Post < ActiveRecord::Base
+    html_fragment :body, :scrub => :prune  # scrubs 'body' at before_validation
+  end
+
+=== ActiveRecord Extension \#2: Opt-Out
+
+See Loofah::XssFoliate::ClassMethods for more documentation. The methods mixed into ActiveRecord are:
+
+* Loofah::XssFoliate::ClassMethods.xss_foliate
+* Loofah::XssFoliate::ClassMethods.xss_foliated?
+
+which are used to declare how specific string and text attributes
+should be scrubbed at +before_validation+.
+
+Attributes are stripped by default, unless another scrubber is
+specified or the attribute is present in an +:except+ clause.
+
+== Requirements
+
+* Nokogiri >= 1.3.3
+* Rails 2.3, 2.2, 2.1, 2.0 or 1.2 (if you're using the ActiveRecord extensions)
+
+== Installation
+
+Unsurprisingly:
+
+* gem install loofah-activerecord
+
+== Support
+
+The bug tracker is available here (the Loofah project):
+
+* http://github.com/flavorjones/loofah/issues
+
+And the mailing list is on librelist (also the Loofah mailing list):
+
+* loofah@librelist.com / http://librelist.com
+
+And the IRC channel is \#loofah on freenode.
+
+== Related Links
+
+* Loofah: http://github.com/flavorjones/loofah
+* XssTerminate: http://github.com/look/xss_terminate/tree/master
+
+== Authors
+
+* {Mike Dalessio}[http://mike.daless.io] (@flavorjones[http://twitter.com/flavorjones])
+
+Featuring code contributed by:
+
+* Josh Nichols
+* Damon P. Cortesi
+
+== Historical Note
+
+This library was split out of the Loofah project for version 1.0.0.
+
+== License
+
+The MIT License
+
+Copyright (c) 2009, 2010 by Mike Dalessio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+gem 'hoe', '>= 2.3.0'
+require 'hoe'
+
+Hoe.plugin :git
+Hoe.plugin :bundler
+
+Hoe.spec "loofah-activerecord" do
+  developer "Mike Dalessio", "mike.dalessio@gmail.com"
+
+  self.extra_rdoc_files = FileList["*.rdoc"]
+  self.history_file     = "CHANGELOG.rdoc"
+  self.readme_file      = "README.rdoc"
+
+  extra_deps << ["loofah", ">= 1.0.0.beta.1"]
+  extra_dev_deps << ["mocha", ">=0.9"]
+  extra_dev_deps << ["shoulda", ">=2.10"]
+  extra_dev_deps << ["acts_as_fu", ">=0.0.5"]
+  extra_dev_deps << ["sqlite3-ruby", ">=1.2"] # acts_as_fu dependency
+end
+
+load "rails_test/Rakefile"
+
+task :gemspec do
+  system %q(rake debug_gem | grep -v "^\(in " > loofah-activerecord.gemspec)
+end
+task "test:rails" => :gemspec
+
+task :redocs => :fix_css
+task :docs => :fix_css
+task :fix_css do
+  better_css = <<-EOT
+    .method-description pre {
+      margin                    : 1em 0 ;
+    }
+
+    .method-description ul {
+      padding                   : .5em 0 .5em 2em ;
+    }
+
+    .method-description p {
+      margin-top                : .5em ;
+    }
+
+    #main ul, div#documentation ul {
+      list-style-type           : disc ! IMPORTANT ;
+      list-style-position       : inside ! IMPORTANT ;
+    }
+
+    h2 + ul {
+      margin-top                : 1em;
+    }
+  EOT
+  puts "* fixing css"
+  File.open("doc/rdoc.css", "a") { |f| f.write better_css }
+end

data/lib/loofah-activerecord.rb

@@ -0,0 +1,19 @@
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__))) unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'loofah'
+
+module Loofah::ActiveRecord
+  VERSION = "1.0.0.beta.1"
+end
+
+if defined?(Rails) && Rails::VERSION::MAJOR == 3
+  require 'loofah-activerecord/railtie'
+elsif defined? Rails.configuration and Rails.configuration.frameworks.include?([:active_record]) # >= 2.1
+  Rails.configuration.after_initialize do
+    require 'loofah-activerecord/active_record'
+    require 'loofah-activerecord/xss_foliate'
+  end
+elsif defined? ActiveRecord::Base # <= 2.0
+  require 'loofah-activerecord/active_record'
+  require 'loofah-activerecord/xss_foliate'
+end

data/lib/loofah-activerecord/active_record.rb

@@ -0,0 +1,60 @@
+module Loofah
+  #
+  # Loofah can scrub ActiveRecord attributes in a before_validation callback:
+  #
+  #   # config/initializers/loofah.rb
+  #   require 'loofah'
+  #
+  #   # db/schema.rb
+  #   create_table "posts" do |t|
+  #     t.string  "title"
+  #     t.string  "body"
+  #   end
+  #
+  #   # app/model/post.rb
+  #   class Post < ActiveRecord::Base
+  #     html_fragment :body, :scrub => :prune  # scrubs 'body' in a before_validation
+  #   end
+  #
+  module ActiveRecordExtension
+    #
+    #  :call-seq:
+    #    html_fragment(attribute, :scrub => scrubber_specification)
+    #
+    #  Scrub an ActiveRecord attribute +attribute+ as an HTML *fragment*
+    #  using the method specified by +scrubber_specification+.
+    #
+    #  +scrubber_specification+ must be an argument acceptable to Loofah::ScrubBehavior.scrub!, namely:
+    #
+    #  * a symbol for one of the built-in scrubbers (see Loofah::Scrubbers for a full list)
+    #  * or a Scrubber instance. (see Loofah::Scrubber for help on implementing a custom scrubber)
+    #
+    def html_fragment(attr, options={})
+      raise ArgumentError, "html_fragment requires :scrub option" unless method = options[:scrub]
+      before_validation do |record|
+        record[attr] = Loofah.scrub_fragment(record[attr], method).to_s
+      end
+    end
+
+    #
+    #  :call-seq:
+    #    model.html_document(attribute, :scrub => scrubber_specification)
+    #
+    #  Scrub an ActiveRecord attribute +attribute+ as an HTML *document*
+    #  using the method specified by +scrubber_specification+.
+    #
+    #  +scrubber_specification+ must be an argument acceptable to Loofah::ScrubBehavior.scrub!, namely:
+    #
+    #  * a symbol for one of the built-in scrubbers (see Loofah::Scrubbers for a full list)
+    #  * or a Scrubber instance.
+    #
+    def html_document(attr, options={})
+      raise ArgumentError, "html_document requires :scrub option" unless method = options[:scrub]
+      before_validation do |record|
+        record[attr] = Loofah.scrub_document(record[attr], method).to_s
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.extend(Loofah::ActiveRecordExtension)

data/lib/loofah-activerecord/railtie.rb

@@ -0,0 +1,12 @@
+require 'rails'
+module Loofah::ActiveRecord
+  class Railtie < Rails::Railtie
+    initializer "loofah-activerecord.initialize" do |app|
+      activerecord_railtie = app.railties.all.select {|railtie| railtie.class.to_s == "ActiveRecord::Railtie" }
+      if activerecord_railtie
+        require 'loofah-activerecord/active_record'
+        require 'loofah-activerecord/xss_foliate'
+      end
+    end
+  end
+end

data/lib/loofah-activerecord/xss_foliate.rb

@@ -0,0 +1,207 @@
+module Loofah
+  #
+  #  A replacement for
+  #  XssTerminate[http://github.com/look/xss_terminate/tree/master],
+  #  XssFoliate will strip all tags from your ActiveRecord models'
+  #  string and text attributes.
+  #
+  #  Please read the Loofah documentation for an explanation of the
+  #  different scrubbing methods, and
+  #  Loofah::XssFoliate::ClassMethods for more information on the
+  #  methods.
+  #
+  #  If you'd like to scrub all fields in all your models (and perhaps *opt-out* in specific models):
+  #
+  #    # config/initializers/loofah.rb
+  #    require 'loofah'
+  #    Loofah::XssFoliate.xss_foliate_all_models
+  #
+  #    # db/schema.rb
+  #    create_table "posts" do |t|
+  #      t.string  "title"
+  #      t.text    "body"
+  #      t.string  "author"
+  #    end
+  #
+  #    # app/model/post.rb
+  #    class Post < ActiveRecord::Base
+  #      #  by default, title, body and author will all be scrubbed down to their inner text
+  #    end
+  #
+  #  OR
+  #
+  #    # app/model/post.rb
+  #    class Post < ActiveRecord::Base
+  #      xss_foliate :except => :author  # opt-out of sanitizing author
+  #    end
+  #
+  #  OR
+  #
+  #      xss_foliate :strip => [:title, body]  # strip unsafe tags from both title and body
+  #
+  #  OR
+  #
+  #      xss_foliate :except => :title         # scrub body and author but not title
+  #
+  #  OR
+  #
+  #      # remove all tags from title, remove unsafe tags from body
+  #      xss_foliate :sanitize => :title, :scrub => :body
+  #
+  #  OR
+  #
+  #      # old xss_terminate code will work if you s/_terminate/_foliate/
+  #      # was: xss_terminate :except => [:title], :sanitize => [:body]
+  #      xss_foliate :except => [:title], :sanitize => [:body]
+  #
+  #  Alternatively, if you would like to *opt-in* to the models and attributes that are sanitized:
+  #
+  #    # config/initializers/loofah.rb
+  #    require 'loofah'
+  #    ## note omission of call to Loofah::XssFoliate.xss_foliate_all_models
+  #
+  #    # db/schema.rb
+  #    create_table "posts" do |t|
+  #      t.string  "title"
+  #      t.text    "body"
+  #      t.string  "author"
+  #    end
+  #
+  #    # app/model/post.rb
+  #    class Post < ActiveRecord::Base
+  #      xss_foliate  # scrub title, body and author down to their inner text
+  #    end
+  #
+  module XssFoliate
+    #
+    #  A replacement for
+    #  XssTerminate[http://github.com/look/xss_terminate/tree/master],
+    #  XssFoliate will strip all tags from your ActiveRecord models'
+    #  string and text attributes.
+    #
+    #  See Loofah::XssFoliate for more example usage.
+    #
+    module ClassMethods
+      # :stopdoc:
+      VALID_OPTIONS = [:except, :html5lib_sanitize, :sanitize] + Loofah::Scrubbers.scrubber_symbols
+      ALIASED_OPTIONS = {:html5lib_sanitize => :escape, :sanitize => :strip}
+      REAL_OPTIONS = VALID_OPTIONS - ALIASED_OPTIONS.keys
+      # :startdoc:
+
+      #
+      #  Annotate your model with this method to specify which fields
+      #  you want scrubbed, and how you want them scrubbed. XssFoliate
+      #  assumes all character fields are HTML fragments (as opposed to
+      #  full documents, see the Loofah[http://loofah.rubyforge.org/]
+      #  documentation for a full explanation of the difference).
+      #
+      #  Example call:
+      #
+      #   xss_foliate :except => :author, :strip => :body, :prune => [:title, :description]
+      #
+      #  *Note* that the values in the options hash can be either an
+      #  array of attributes or a single attribute.
+      #
+      #  Options:
+      #
+      #   :except => [fields] # don't scrub these fields
+      #   :strip  => [fields] # strip unsafe tags from these fields
+      #   :escape => [fields] # escape unsafe tags from these fields
+      #   :prune  => [fields] # prune unsafe tags and subtrees from these fields
+      #   :text   => [fields] # remove everything except the inner text from these fields
+      #
+      #  XssTerminate compatibility options (note that the default
+      #  behavior in XssTerminate corresponds to :text)
+      #
+      #   :html5lib_sanitize => [fields] # same as :escape
+      #   :sanitize          => [fields] # same as :strip
+      #
+      #  The default is :text for all fields unless otherwise specified.
+      #
+      def xss_foliate(options = {})
+        callback_already_declared = \
+        if respond_to?(:before_validation_callback_chain)
+          # Rails 2.1 and later
+          before_validation_callback_chain.any? {|cb| cb.method == :xss_foliate_fields}
+        else
+          # Rails 2.0
+          cbs = read_inheritable_attribute(:before_validation)
+          (! cbs.nil?) && cbs.any? {|cb| cb == :xss_foliate_fields}
+        end
+
+        unless callback_already_declared
+          before_validation        :xss_foliate_fields
+          class_inheritable_reader :xss_foliate_options
+          include XssFoliate::InstanceMethods
+        end
+
+        options.keys.each do |option|
+          raise ArgumentError, "unknown xss_foliate option #{option}" unless VALID_OPTIONS.include?(option)
+        end
+
+        REAL_OPTIONS.each do |option|
+          options[option] = Array(options[option]).collect { |val| val.to_sym }
+        end
+
+        ALIASED_OPTIONS.each do |option, real|
+          options[real] += Array(options.delete(option)).collect { |val| val.to_sym } if options[option]
+        end
+
+        write_inheritable_attribute(:xss_foliate_options, options)
+      end
+
+      #
+      #  Class method to determine whether or not this model is applying
+      #  xss_foliation to its attributes. Could be useful in test suites.
+      #
+      def xss_foliated?
+        options = read_inheritable_attribute(:xss_foliate_options)
+        ! (options.nil? || options.empty?)
+      end
+    end
+
+    module InstanceMethods
+      def xss_foliate_fields # :nodoc:
+        # fix a bug with Rails internal AR::Base models that get loaded before
+        # the plugin, like CGI::Sessions::ActiveRecordStore::Session
+        return if xss_foliate_options.nil?
+
+        self.class.columns.each do |column|
+          next unless (column.type == :string || column.type == :text)
+
+          field = column.name.to_sym
+          value = self[field]
+
+          next if value.nil? || !value.is_a?(String)
+
+          next if xss_foliate_options[:except].include?(field)
+
+          next if xss_foliated_with_standard_scrubber(field)
+
+          # :text if we're here
+          fragment = Loofah.scrub_fragment(value, :strip)
+          self[field] = fragment.nil? ? "" : fragment.text
+        end
+      end
+
+      private
+
+      def xss_foliated_with_standard_scrubber(field)
+        Loofah::Scrubbers.scrubber_symbols.each do |method|
+          if xss_foliate_options[method].include?(field)
+            fragment = Loofah.scrub_fragment(self[field], method)
+            self[field] = fragment.nil? ? "" : fragment.to_s
+            return true
+          end
+        end
+        false
+      end
+    end
+
+    def self.xss_foliate_all_models
+      ::ActiveRecord::Base.xss_foliate
+    end
+  end
+end
+
+::ActiveRecord::Base.extend(Loofah::XssFoliate::ClassMethods)