Support automatic escaping HTML

[kylef]

This pull request is the first step in implementing auto escaping.

Why?

Most users of Stencil are going to be using Stencil as a HTML templating language, and subsequently it should provide auto escaping of HTML for XSS prevention. A Stencil template author should not have to think about XSS or escaping as it will be handled automatically.

Should auto escape be enable by default?

I've been thinking a lot about this, and leaning towards auto escaping to be off by default. However any web frameworks should create an environment with auto escaping enabled for rendering templates.

It may make sense for autoescaping HTML to be enable by default because most cases users will be using Templates with HTML.

How should the auto escape setting in Environment work?

Jinja2 has an approach of allowing users to provide a function which can be used to determine if auto escape can be enabled. The value can also be set to False/True to force.

def guess_autoescape(template_name):
    if template_name is None or '.' not in template_name:
        return False

    ext = template_name.rsplit('.', 1)[1]
    return ext in ('html', 'htm', 'xml')

This seems useful, especially for web frameworks where they may want to provide this exact behaviour of escaping HTML based on a .html extension. So that if there was .txt templates for example an email template it would not be escaped.

Allowing users to escape in any format

We shouldn't limit the API to only allow HTML autoescape, users should be able to write custom escaping rules for other content types. Most of the similiar template languages to Stencil don't allow serialising custom formats.

Allowing users to mark a value as already escaped

We provide the HTMLEscaped protocol which allows you to provide a html property which will return an already escaped string. This might be useful if you need to include HTML inside a variable such as:

{{ form }}

class Form: HTMLEscaped {
  // fields
  
  var html: String {
    return "<ul><li><input type="text" name="name"></li></ul>"
  }
}

Where form returns HTML representation of a HTML form.

There is also a template filter which can be used to wrap a value in the escaped protocol.

{{ value|safe }}

Force escaping:

{{ value|escape }}

Django also provides an {% autoescape on/off %}{% endautoescape %} block so users can enable/disable auto escaping in a scope.

---

This pull request is not yet ready. The current state is to force HTML auto escaping, it should become optional with custom formats.

[ilyapuchka]

Isn't it what {{{ html }}} should do (as in mustache(5))?

[ianpartridge]

Hi @kylef are you hoping to take this forwards? We have been discussing how to handle escaping in Kitura templating and would welcome this being added to Stencil.

We have written an HTML5 compliant encoder/decoder for Swift - see https://github.com/IBM-Swift/swift-html-entities

If you would like Stencil to use it you would be very welcome!

[ianpartridge]

@kylef ping..

[gurugeek]

is there any news on it ? On another note: is it possible to escape HTML(manually) at the moment? I can't find anything on the documentation.