add a binding for hoedown_escape_html()

We need an escape function to implement XSS protection.

build_ffi.py

@@ -55,6 +55,7 @@ ffi.set_source(
     """\
 #include "hoedown/buffer.h"
 #include "hoedown/document.h"
+#include "hoedown/escape.h"
 #include "hoedown/html.h"
 #include "extra.h"
 """,
@@ -255,6 +256,12 @@ hoedown_document *hoedown_document_new(
 void hoedown_document_render(hoedown_document *doc, hoedown_buffer *ob, const uint8_t *data, size_t size);
 void hoedown_document_free(hoedown_document *doc);
 
+// ------------------------
+// --- hoedown/escape.h ---
+// ------------------------
+
+void hoedown_escape_html(hoedown_buffer *ob, const uint8_t *data, size_t size, int secure);
+
 // ----------------------
 // --- hoedown/html.h ---
 // ----------------------

docs/index.rst

@@ -214,6 +214,9 @@ Functions
 .. autofunction:: smartypants
 
 
+.. autofunction:: escape_html
+
+
 Classes
 ^^^^^^^
 

misaka/api.py

@@ -8,6 +8,7 @@ from .utils import extension_map, html_flag_map, args_to_int, \
 
 
 __all__ = [
+    'escape_html',
     'html',
     'smartypants',
     'Markdown',
@@ -58,6 +59,32 @@ OUNIT = 64
 MAX_NESTING = 16
 
 
+def escape_html(text, escape_slash=False):
+    """
+    Binding for Hoedown's HTML escaping function.
+
+    The implementation is inspired by the OWASP XSS Prevention recommendations:
+
+    .. code-block:: none
+
+        & --> &
+        < --> &lt;
+        > --> &gt;
+        " --> &quot;
+        ' --> &#x27;
+        / --> &#x2F;  when escape_slash is set to True
+
+    """
+    byte_str = text.encode('utf-8')
+    ob = lib.hoedown_buffer_new(OUNIT)
+    lib.hoedown_escape_html(ob, byte_str, len(byte_str), int(escape_slash))
+
+    try:
+        return to_string(ob)
+    finally:
+        lib.hoedown_buffer_free(ob)
+
+
 def html(text, extensions=0, render_flags=0):
     """
     Convert markdown text to HTML.

tests/test_xss_protection.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+from chibitest import TestCase, ok
+from misaka import escape_html
+
+
+class EscapeHtmlTest(TestCase):
+    def test_escape_html(self):
+        ok(escape_html('a&<>"\'/')) == 'a&amp;&lt;&gt;&quot;&#39;/'
+
+    def test_escape_html_slash(self):
+        ok(escape_html('a&<>"\'/', True)) == 'a&amp;&lt;&gt;&quot;&#39;&#47;'