= Sanitize

Sanitize is a whitelist-based HTML sanitizer. Given a list of acceptable
elements and attributes, Sanitize will remove all unacceptable HTML from a
string.

Using a simple configuration syntax, you can tell Sanitize to allow certain
elements, certain attributes within those elements, and even certain URL
protocols within attributes that contain URLs. Any HTML elements or attributes
that you don't explicitly allow will be removed.

Because it's based on Nokogiri, a full-fledged HTML parser, rather than a bunch
of fragile regular expressions, Sanitize has no trouble dealing with malformed
or maliciously-formed HTML, and will always output valid HTML or XHTML.

*Author*::    Ryan Grove (mailto:ryan@wonko.com)
*Version*::   2.0.0 (git)
*Copyright*:: Copyright (c) 2011 Ryan Grove. All rights reserved.
*License*::   MIT License (http://opensource.org/licenses/mit-license.php)
*Website*::   http://github.com/rgrove/sanitize

== Requires

* Nokogiri ~> 1.4.4
* libxml2 >= 2.7.2

== Installation

Latest stable release:

  gem install sanitize

Latest development version:

  gem install sanitize --pre

== Usage

If you don't specify any configuration options, Sanitize will use its strictest
settings by default, which means it will strip all HTML and leave only text
behind.

  require 'rubygems'
  require 'sanitize'

  html = '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg">'

  Sanitize.clean(html) # => 'foo'

== Configuration

In addition to the ultra-safe default settings, Sanitize comes with three other
built-in modes.

=== Sanitize::Config::RESTRICTED

Allows only very simple inline formatting markup. No links, images, or block
elements.

  Sanitize.clean(html, Sanitize::Config::RESTRICTED) # => '<b>foo</b>'

=== Sanitize::Config::BASIC

Allows a variety of markup including formatting tags, links, and lists. Images
and tables are not allowed, links are limited to FTP, HTTP, HTTPS, and mailto
protocols, and a <code>rel="nofollow"</code> attribute is added to all links to
mitigate SEO spam.

  Sanitize.clean(html, Sanitize::Config::BASIC)
  # => '<b><a href="http://foo.com/" rel="nofollow">foo</a></b>'

=== Sanitize::Config::RELAXED

Allows an even wider variety of markup than BASIC, including images and tables.
Links are still limited to FTP, HTTP, HTTPS, and mailto protocols, while images
are limited to HTTP and HTTPS. In this mode, <code>rel="nofollow"</code> is not
added to links.

  Sanitize.clean(html, Sanitize::Config::RELAXED)
  # => '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg">'

=== Custom Configuration

If the built-in modes don't meet your needs, you can easily specify a custom
configuration:

  Sanitize.clean(html, :elements => ['a', 'span'],
      :attributes => {'a' => ['href', 'title'], 'span' => ['class']},
      :protocols => {'a' => {'href' => ['http', 'https', 'mailto']}})

==== :add_attributes (Hash)

Attributes to add to specific elements. If the attribute already exists, it will
be replaced with the value specified here. Specify all element names and
attributes in lowercase.

  :add_attributes => {
    'a' => {'rel' => 'nofollow'}
  }

==== :attributes (Hash)

Attributes to allow for specific elements. Specify all element names and
attributes in lowercase.

  :attributes => {
    'a'          => ['href', 'title'],
    'blockquote' => ['cite'],
    'img'        => ['alt', 'src', 'title']
  }

If you'd like to allow certain attributes on all elements, use the symbol
<code>:all</code> instead of an element name.

  :attributes => {
    :all => ['class'],
    'a'  => ['href', 'title']
  }

==== :allow_comments (boolean)

Whether or not to allow HTML comments. Allowing comments is strongly
discouraged, since IE allows script execution within conditional comments. The
default value is <code>false</code>.

==== :elements (Array)

Array of element names to allow. Specify all names in lowercase.

  :elements => %w[
    a abbr b blockquote br cite code dd dfn dl dt em i kbd li mark ol p pre
    q s samp small strike strong sub sup time u ul var
  ]

==== :output (Symbol)

Output format. Supported formats are <code>:html</code> and <code>:xhtml</code>,
defaulting to <code>:html</code>.

==== :output_encoding (String)

Character encoding to use for HTML output. Default is <code>utf-8</code>.

==== :protocols (Hash)

URL protocols to allow in specific attributes. If an attribute is listed here
and contains a protocol other than those specified (or if it contains no
protocol at all), it will be removed.

  :protocols => {
    'a'   => {'href' => ['ftp', 'http', 'https', 'mailto']},
    'img' => {'src'  => ['http', 'https']}
  }

If you'd like to allow the use of relative URLs which don't have a protocol,
include the symbol <code>:relative</code> in the protocol array:

  :protocols => {
    'a' => {'href' => ['http', 'https', :relative]}
  }

==== :remove_contents (boolean or Array)

If set to +true+, Sanitize will remove the contents of any non-whitelisted
elements in addition to the elements themselves. By default, Sanitize leaves the
safe parts of an element's contents behind when the element is removed.

If set to an array of element names, then only the contents of the specified
elements (when filtered) will be removed, and the contents of all other filtered
elements will be left behind.

The default value is <code>false</code>.

==== :transformers

Custom transformer or array of custom transformers to run using depth-first
traversal. See the Transformers section below for details.

=== :transformers_breadth

Custom transformer or array of custom transformers to run using breadth-first
traversal. See the Transformers section below for details.

==== :whitespace_elements (Array)

Array of lowercase element names that should be replaced with whitespace when
removed in order to preserve readability. For example,
<code>foo<div>bar</div>baz</code> will become
<code>foo bar baz</code> when the <code><div></code> is removed.

By default, the following elements are included in the
<code>:whitespace_elements</code> array:

  address article aside blockquote br dd div dl dt footer h1 h2 h3 h4 h5
  h6 header hgroup hr li nav ol p pre section ul

=== Transformers

Transformers allow you to filter and modify nodes using your own custom logic,
on top of (or instead of) Sanitize's core filter. A transformer is any object
that responds to <code>call()</code> (such as a lambda or proc).

To use one or more transformers, pass them to the <code>:transformers</code>
config setting. You may pass a single transformer or an array of transformers.

  Sanitize.clean(html, :transformers => [transformer_one, transformer_two])

==== Input

Each registered transformer's <code>call()</code> method will be called once for
each node in the HTML (including elements, text nodes, comments, etc.), and will
receive as an argument an environment Hash that contains the following items:

[<code>:config</code>]
  The current Sanitize configuration Hash.

[<code>:is_whitelisted</code>]
  <code>true</code> if the current node has been whitelisted by a previous
  transformer, <code>false</code> otherwise. It's generally bad form to remove a
  node that a previous transformer has whitelisted.

[<code>:node</code>]
  A Nokogiri::XML::Node object representing an HTML node. The node may be an
  element, a text node, a comment, a CDATA node, or a document fragment. Use
  Nokogiri's inspection methods (<code>element?</code>, <code>text?</code>,
  etc.) to selectively ignore node types you aren't interested in.

[<code>:node_name</code>]
  The name of the current HTML node, always lowercase (e.g. "div" or "span").
  For non-element nodes, the name will be something like "text", "comment",
  "#cdata-section", "#document-fragment", etc.

[<code>:node_whitelist</code>]
  Set of Nokogiri::XML::Node objects in the current document that have been
  whitelisted by previous transformers, if any. It's generally bad form to
  remove a node that a previous transformer has whitelisted.

[<code>:traversal_mode</code>]
  Current node traversal mode, either <code>:depth</code> for depth-first (the
  default mode) or <code>:breadth</code> for breadth-first.

==== Output

A transformer doesn't have to return anything, but may optionally return a Hash,
which may contain the following items:

[<code>:node_whitelist</code>]
  Array or Set of specific Nokogiri::XML::Node objects to add to the document's
  whitelist, bypassing the current Sanitize config. These specific nodes and all
  their attributes will be whitelisted, but their children will not be.

If a transformer returns anything other than a Hash, the return value will be
ignored.

==== Processing

Each transformer has full access to the Nokogiri::XML::Node that's passed into
it and to the rest of the document via the node's <code>document()</code>
method. Any changes made to the current node or to the document will be
reflected instantly in the document and passed on to subsequently-called
transformers and to Sanitize itself. A transformer may even call Sanitize
internally to perform custom sanitization if needed.

Nodes are passed into transformers in the order in which they're traversed. By
default, depth-first traversal is used, meaning that markup is traversed from
the deepest node upward (not from the first node to the last node):

  html        = '<div><span>foo</span></div>'
  transformer = lambda{|env| puts env[:node_name] }

  # Prints "text", "span", "div", "#document-fragment".
  Sanitize.clean(html, :transformers => transformer)

You may use the <code>:transformers_breadth</code> config to specify one or more
transformers that should traverse nodes in breadth-first mode:

  html        = '<div><span>foo</span></div>'
  transformer = lambda{|env| puts env[:node_name] }

  # Prints "#document-fragment", "div", "span", "text".
  Sanitize.clean(html, :transformers_breadth => transformer)

Transformers have a tremendous amount of power, including the power to
completely bypass Sanitize's built-in filtering. Be careful! Your safety is in
your own hands.

==== Example: Transformer to whitelist YouTube video embeds

The following example demonstrates how to create a depth-first Sanitize
transformer that will safely whitelist valid YouTube video embeds without having
to blindly allow other kinds of embedded content, which would be the case if you
tried to do this by just whitelisting all <code><object></code>,
<code><embed></code>, and <code><param></code> elements:

  lambda do |env|
    node      = env[:node]
    node_name = env[:node_name]

    # Don't continue if this node is already whitelisted or is not an element.
    return if env[:is_whitelisted] || !node.element?

    parent = node.parent

    # Since the transformer receives the deepest nodes first, we look for a
    # <param> element or an <embed> element whose parent is an <object>.
    return unless (node_name == 'param' || node_name == 'embed') &&
        parent.name.to_s.downcase == 'object'

    if node_name == 'param'
      # Quick XPath search to find the <param> node that contains the video URL.
      return unless movie_node = parent.search('param[@name="movie"]')[0]
      url = movie_node['value']
    else
      # Since this is an <embed>, the video URL is in the "src" attribute. No
      # extra work needed.
      url = node['src']
    end

    # Verify that the video URL is actually a valid YouTube video URL.
    return unless url =~ /^http:\/\/(?:www\.)?youtube\.com\/v\//

    # We're now certain that this is a YouTube embed, but we still need to run
    # it through a special Sanitize step to ensure that no unwanted elements or
    # attributes that don't belong in a YouTube embed can sneak in.
    Sanitize.clean_node!(parent, {
      :elements => %w[embed object param],

      :attributes => {
        'embed'  => %w[allowfullscreen allowscriptaccess height src type width],
        'object' => %w[height width],
        'param'  => %w[name value]
      }
    })

    # Now that we're sure that this is a valid YouTube embed and that there are
    # no unwanted elements or attributes hidden inside it, we can tell Sanitize
    # to whitelist the current node (<param> or <embed>) and its parent
    # (<object>).
    {:node_whitelist => [node, parent]}
  end

== Contributors

Sanitize was created and is maintained by Ryan Grove (ryan@wonko.com).

The following lovely people have also contributed to Sanitize:

* Wilson Bilkovich (wilson@supremetyrant.com)
* Peter Cooper (git@peterc.org)
* Gabe da Silveira (gabe@websaviour.com)
* Nicholas Evans (owlmanatt@gmail.com)
* Adam Hooper (adam@adamhooper.com)
* Mutwin Kraus (mutle@blogage.de)
* Dev Purkayastha (dev.purkayastha@gmail.com)
* David Reese (work@whatcould.com)
* Ardie Saeidi (ardalan.saeidi@gmail.com)
* Rafael Souza (me@rafaelss.com)
* Ben Wanicur (bwanicur@verticalresponse.com)

== License

Copyright (c) 2011 Ryan Grove (ryan@wonko.com)

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.