liquid-autoescape 0.2.1

data/lib/liquid/autoescape/filters.rb

@@ -0,0 +1,26 @@
+require "liquid"
+
+module Liquid
+  module Autoescape
+
+    # Liquid filters used to support the autoescape tag
+    module Filters
+
+      # Flag an input as exempt from autoescaping
+      #
+      # This is a non-transformative filter that works by registering itself
+      # in a variable's filter chain.  If a variable detects this in its
+      # filters, no escaping will be performed on it.
+      #
+      # @param [String] input A variable's content
+      # @return [String] The unmodified content
+      def skip_escape(input)
+        input
+      end
+
+    end
+
+    Template.register_filter(Filters)
+
+  end
+end

data/lib/liquid/autoescape/liquid_ext/variable.rb

@@ -0,0 +1,38 @@
+require "liquid"
+require "liquid/autoescape"
+require "liquid/autoescape/template_variable"
+
+module Liquid
+  class Variable
+
+    # @private
+    alias_method :non_escaping_render, :render
+
+    # Possibly render the variable with HTML escaping applied
+    #
+    # If the autoescaping context variable has been set by the +autoescape+ tag
+    # or Liquid autoescaping is globally enabled, this will run the variable
+    # through the global exemption list to determine if it is exempt from
+    # autoescaping.  If it is not, its contents will be rendered as a string
+    # with all unsafe HTML characters escaped.  In all other cases, the
+    # original, unescaped value of the variable will be rendered.
+    #
+    # @param [Liquid::Context] context The variable's rendering context
+    # @return [String] The potentially escaped contents of the variable
+    def render(context)
+      if !Autoescape.configuration.global? && !context[Autoescape::ENABLED_FLAG]
+        return non_escaping_render(context)
+      end
+
+      variable = Autoescape::TemplateVariable.from_liquid_variable(self)
+      is_exempt = Autoescape.configuration.exemptions.apply?(variable)
+
+      @filters << [:escape, []] unless is_exempt
+      output = non_escaping_render(context)
+      @filters.pop unless is_exempt
+
+      output
+    end
+
+  end
+end

data/lib/liquid/autoescape/tags/autoescape.rb

@@ -0,0 +1,45 @@
+require "liquid"
+require "liquid/autoescape/liquid_ext/variable"
+
+module Liquid
+  module Autoescape
+    module Tags
+
+      # A block tag that automatically escapes all variables contained within it
+      #
+      # All contained variables will have dangerous HTML characters escaped.
+      # Any variables that should be exempt from escaping should have the
+      # +skip_escape+ filter applied to them.
+      #
+      # @example
+      #   {% assign untrusted = "<script>window.reload();</script>" %}
+      #   {% assign trusted = "<strong>Text</strong>" %}
+      #
+      #   {% autoescape %}
+      #     {{ untrusted }}
+      #     {{ trusted | skip_escape }}
+      #   {% endautoescape %}
+      class Autoescape < Block
+
+        def initialize(tag_name, markup, tokens)
+          unless markup.empty?
+            raise SyntaxError, "Syntax Error in 'autoescape' - Valid syntax: {% autoescape %}"
+          end
+
+          super
+        end
+
+        def render(context)
+          context.stack do
+            context[ENABLED_FLAG] = true
+            super
+          end
+        end
+
+      end
+
+      Template.register_tag("autoescape", Autoescape)
+
+    end
+  end
+end

data/lib/liquid/autoescape/template_variable.rb

@@ -0,0 +1,74 @@
+module Liquid
+  module Autoescape
+
+    # A wrapper around a Liquid variable used in a template
+    #
+    # This provides a consistent interface to a Liquid variable, accounting
+    # for structural differences in variables between different Liquid versions
+    # and exposing a simple list of applied filters.  All exemptions are
+    # determined by examining instances of this object.
+    class TemplateVariable
+
+      # The name of the variable
+      #
+      # @return [String]
+      attr_reader :name
+
+      # The names of the filters applied to the variable
+      #
+      # @return [Array<Symbol>]
+      attr_reader :filters
+
+      class << self
+
+        # Create a wrapper around a Liquid variable instance
+        #
+        # This normalizes the variable's information, since Liquid handles
+        # variable names differently across versions.
+        #
+        # @param [Liquid::Variable] variable A Liquid variable as used in a template
+        # @return [Liquid::Autoescape::TemplateVariable]
+        def from_liquid_variable(variable)
+          name = normalize_variable_name(variable)
+          filters = variable.filters.map { |f| f.first.to_sym }
+
+          new(:name => name, :filters => filters)
+        end
+
+      private
+
+        # Normalize the name of a Liquid variable
+        #
+        # Liquid 2 exposes the full variable name directly on the
+        # +Liquid::Variable+ instance, while Liquid 3 manages it via a
+        # +Liquid::VariableLookup+ instance that tracks both the base name and
+        # any lookup paths involved.
+        #
+        # @param [Liquid::Variable] variable A Liquid variable as used in a template
+        # @return [String] The name of the Liquid variable
+        def normalize_variable_name(variable)
+          lookup_name = variable.name.instance_variable_get("@name")
+          return variable.name unless lookup_name
+
+          parts = [lookup_name]
+          variable.name.instance_variable_get("@lookups").each do |lookup|
+            parts << lookup
+          end
+          parts.join(".")
+        end
+
+      end
+
+      # Create a wrapper around a Liquid variable used in a template
+      #
+      # @options options [String] :name The name of the variable
+      # @options options [Array<Symbol>] :filters The filters applied to the variable
+      def initialize(options={})
+        @name = options.fetch(:name)
+        @filters = options[:filters] || []
+      end
+
+    end
+
+  end
+end

data/lib/liquid/autoescape/version.rb

@@ -0,0 +1,5 @@
+module Liquid
+  module Autoescape
+    VERSION = "0.2.1"
+  end
+end

data/spec/functional/autoescape_tag_spec.rb

@@ -0,0 +1,200 @@
+require "liquid/autoescape"
+
+describe "{% autoescape %}" do
+
+  def verify_template_output(template, expected, context={})
+    rendered = Liquid::Template.parse(template).render!(context)
+    expect(rendered).to eq(expected)
+  end
+
+  it "handles empty content" do
+    verify_template_output(
+      "{% autoescape %}{% endautoescape %}",
+      ""
+    )
+  end
+
+  it "handles non-variable content" do
+    verify_template_output(
+      "{% autoescape %}Static{% endautoescape %}",
+      "Static"
+    )
+  end
+
+  it "escapes all dangerous HTML characters" do
+    verify_template_output(
+      "{% autoescape %}{{ variable }}{% endautoescape %}",
+      "<tag> & "quote"",
+      "variable" => '<tag> & "quote"'
+    )
+  end
+
+  it "applies HTML escaping to all variables inside the block tag" do
+    verify_template_output(
+      "{% autoescape %}{{ one }} {{ two }} {{ three }}{% endautoescape %}",
+      "&lt;tag&gt; &amp; &quot;quote&quot;",
+      "one" => "<tag>", "two" => "&", "three" => '"quote"'
+    )
+  end
+
+  it "applies HTML escaping to a filtered variable" do
+    verify_template_output(
+      "{% autoescape %}{{ filtered | downcase | capitalize }}{% endautoescape %}",
+      "A &lt;strong&gt; tag",
+      "filtered" => "A <STRONG> Tag"
+    )
+  end
+
+  it "does not double-escape variables" do
+    verify_template_output(
+      "{% autoescape %}{{ escaped | escape }}{% endautoescape %}",
+      "HTML &amp; CSS",
+      "escaped" => "HTML & CSS"
+    )
+  end
+
+  it "does not escape variables outside the block tag" do
+    verify_template_output(
+      "{{ variable }} {% autoescape %}{{ variable }}{% endautoescape %} {{ variable }}",
+      "& &amp; &",
+      "variable" => "&"
+    )
+  end
+
+  it "can be called multiple times" do
+    verify_template_output(
+      "{% autoescape %}{{ var }}{% endautoescape %} {{ var }} {% autoescape %}{{ var }}{% endautoescape %}",
+      "&amp; & &amp;",
+      "var" => "&"
+    )
+  end
+
+  it "does not escape variables with the skip_escape filter applied" do
+    verify_template_output(
+      "{% autoescape %}{{ variable | skip_escape }}{% endautoescape %}",
+      "<strong>&amp;</strong>",
+      "variable" => "<strong>&amp;</strong>"
+    )
+  end
+
+  it "raises an error when called with arguments" do
+    invalid = "{% autoescape on %}{% endautoescape %}"
+    expect { Liquid::Template.parse(invalid) }.to raise_error(Liquid::SyntaxError)
+  end
+
+  describe "configuration options" do
+
+    after(:each) { Liquid::Autoescape.reconfigure }
+
+    context "with global mode enabled" do
+
+      before(:each) do
+        Liquid::Autoescape.configure do |config|
+          config.global = true
+        end
+      end
+
+      it "escapes variables outside of an autoescape block" do
+        verify_template_output(
+          "{{ variable }}",
+          "&amp;",
+          "variable" => "&"
+        )
+      end
+
+      it "escapes variables in an autoescape block" do
+        verify_template_output(
+          "{% autoescape %}{{ variable }}{% endautoescape %}",
+          "&amp;",
+          "variable" => "&"
+        )
+      end
+
+      it "respects escaping filters" do
+        verify_template_output(
+          "{{ variable | skip_escape }}{% autoescape %}{{ variable | skip_escape }}{% endautoescape %}",
+          "&&",
+          "variable" => "&"
+        )
+      end
+
+    end
+
+    context "with custom exemptions" do
+
+      let(:exemptions) do
+        Module.new do
+          def exemption(variable)
+            variable.name == "module"
+          end
+        end
+      end
+
+      before(:each) do
+        Liquid::Autoescape.configure do |config|
+          config.exemptions.add { |variable| variable.name == "filter" }
+          config.exemptions.import(exemptions)
+        end
+      end
+
+      it "does not escape exempt variables" do
+        verify_template_output(
+          "{% autoescape %}{{ filter }} {{ module }} {{ other }}{% endautoescape %}",
+          "<a> <b> &lt;i&gt;",
+          "filter" => "<a>", "module" => "<b>", "other" => "<i>"
+        )
+      end
+
+      it "can handle exemptions with lookup-style variable names" do
+        Liquid::Autoescape.configure do |config|
+          config.exemptions.add { |variable| variable.name == "root.one" }
+          config.exemptions.add { |variable| variable.name == "trunk.branch.leaf" }
+        end
+
+        verify_template_output(
+          "{% autoescape %}{{ root.one }} {{ root.two }} {{ trunk.branch.leaf }}{% endautoescape %}",
+          "<a> &lt;b&gt; <i>",
+          "root" => {"one" => "<a>", "two" => "<b>"},
+          "trunk" => {"branch" => {"leaf" => "<i>"}}
+        )
+      end
+
+      it "respects the default exemptions" do
+        verify_template_output(
+          "{% autoescape %}{{ filter | skip_escape }} {{ other }}{% endautoescape %}",
+          "<a> &lt;b&gt;",
+          "filter" => "<a>", "other" => "<b>"
+        )
+      end
+
+    end
+
+    context "with trusted filters" do
+
+      before(:each) do
+        Liquid::Autoescape.configure do |config|
+          config.trusted_filters << :downcase
+        end
+      end
+
+      it "does not forget the default escaping filters" do
+        verify_template_output(
+          "{% autoescape %}{{ one | skip_escape }} {{ two | escape }}{% endautoescape %}",
+          "<a> &lt;b&gt;",
+          "one" => "<a>", "two" => "<b>"
+        )
+      end
+
+      it "exempts variables that use one of the trusted filters" do
+        verify_template_output(
+          "{% autoescape %}{{ variable | downcase }} {{ variable | capitalize }}{% endautoescape %}",
+          "r&d R&amp;d",
+          "variable" => "R&D"
+        )
+      end
+
+    end
+
+  end
+
+end

data/spec/unit/autoescape_spec.rb

@@ -0,0 +1,49 @@
+require "liquid/autoescape"
+require "liquid/autoescape/configuration"
+
+module Liquid
+  describe Autoescape do
+
+    after(:each) { Autoescape.reconfigure }
+
+    describe ".configure" do
+
+      it "allows autoescape settings to be customized" do
+        Autoescape.configure do |config|
+          expect(config).to be_an_instance_of(Autoescape::Configuration)
+        end
+      end
+
+    end
+
+    describe ".reconfigure" do
+
+      it "undoes any user configuration" do
+        Autoescape.configure do |config|
+          config.trusted_filters << :my_custom_filter
+        end
+
+        expect(Autoescape.configuration.trusted_filters).to include(:my_custom_filter)
+
+        Autoescape.reconfigure
+        expect(Autoescape.configuration.trusted_filters).to_not include(:my_custom_filter)
+      end
+
+    end
+
+    describe ".configuration" do
+
+      it "exposes the current configuration object" do
+        Autoescape.configure do |config|
+          config.global = true
+        end
+
+        config = Autoescape.configuration
+        expect(config).to be_an_instance_of(Autoescape::Configuration)
+        expect(config.global?).to be(true)
+      end
+
+    end
+
+  end
+end

data/spec/unit/configuration_spec.rb

@@ -0,0 +1,72 @@
+require "liquid/autoescape/configuration"
+
+module Liquid
+  module Autoescape
+    describe Configuration do
+
+      let(:config) { Configuration.new }
+
+      describe "global mode" do
+
+        it "is off by default" do
+          expect(config.global?).to be(false)
+        end
+
+        it "can be turned on" do
+          config.global = true
+          expect(config.global?).to be(true)
+        end
+
+      end
+
+      describe "the list of custom exemptions" do
+
+        it "has default exemptions" do
+          expect(config.exemptions.populated?).to be(true)
+        end
+
+        it "can accept custom exemption filters" do
+          expect { config.exemptions.add { true } }.to change { config.exemptions.size }.by(1)
+        end
+
+        it "cannot directly exemption filters" do
+          exemption = lambda { true }
+          expect { config.exemptions << exemption }.to raise_error
+        end
+
+      end
+
+      describe "the list of trusted filters" do
+
+        it "is empty by default" do
+          expect(config.trusted_filters).to be_empty
+        end
+
+        it "can receive additional filters" do
+          config.trusted_filters << :downcase
+          expect(config.trusted_filters).to match_array([:downcase])
+        end
+
+      end
+
+      describe "#reset" do
+
+        it "restores the default configuration values" do
+          config.global = true
+          config.exemptions.add { true }
+          config.trusted_filters << :downcase
+
+          expect(config.global?).to be(true)
+          expect(config.trusted_filters.size).to be(1)
+
+          expect { config.reset }.to change { config.exemptions.size }.by(-1)
+
+          expect(config.global?).to be(false)
+          expect(config.trusted_filters).to be_empty
+        end
+
+      end
+
+    end
+  end
+end