feat(encodeEmail): add option to enable/disable mail obfuscation

Prior to version 1.6.1, emails would always be obfuscated through dec and hex encoding.
This option makes it possible to disable this.

README.md

@@ -294,6 +294,9 @@ var defaultOptions = showdown.getDefaultOptions();
  
  * **ghMentions**: (boolean) [default false] Enables github @mentions, which link to the username mentioned (since v1.6.0) 
  
+ * **encodeEmails**: (boolean) [default true] Enables e-mail addresses encoding through the use of Character Entities, transforming ASCII e-mail addresses into its equivalent decimal entities. (since v1.6.1)
+
+   NOTE: Prior to version 1.6.1, emails would always be obfuscated through dec and hex encoding.
 
 **NOTE**: Please note that until version 1.6.0, all of these options are ***DISABLED*** by default in the cli tool.
  

src/helpers.js

@@ -251,6 +251,46 @@ showdown.helper.replaceRecursiveRegExp = function (str, replacement, left, right
   return finalStr;
 };
 
+/**
+ * Obfuscate an e-mail address through the use of Character Entities,
+ * transforming ASCII characters into their equivalent decimal or hex entities.
+ *
+ * Since it has a random component, subsequent calls to this function produce different results
+ *
+ * @param {string} mail
+ * @returns {string}
+ */
+showdown.helper.encodeEmailAddress = function (mail) {
+  'use strict';
+  var encode = [
+    function (ch) {
+      return '&#' + ch.charCodeAt(0) + ';';
+    },
+    function (ch) {
+      return '&#x' + ch.charCodeAt(0).toString(16) + ';';
+    },
+    function (ch) {
+      return ch;
+    }
+  ];
+
+  mail = mail.replace(/./g, function (ch) {
+    if (ch === '@') {
+      // this *must* be encoded. I insist.
+      ch = encode[Math.floor(Math.random() * 2)](ch);
+    } else {
+      var r = Math.random();
+      // roughly 10% raw, 45% hex, 45% dec
+      ch = (
+        r > 0.9 ? encode[2](ch) : r > 0.45 ? encode[1](ch) : encode[0](ch)
+      );
+    }
+    return ch;
+  });
+
+  return mail;
+};
+
 /**
  * POLYFILLS
  */

src/options.js

@@ -105,6 +105,11 @@ function getDefaultOpts(simple) {
       defaultValue: false,
       description: 'Enables github @mentions',
       type: 'boolean'
+    },
+    encodeEmails: {
+      defaultValue: true,
+      description: 'Encode e-mail addresses through the use of Character Entities, transforming ASCII e-mail addresses into its equivalent decimal entities',
+      type: 'boolean'
     }
   };
   if (simple === false) {

src/subParsers/autoLinks.js

@@ -36,8 +36,15 @@ showdown.subParser('autoLinks', function (text, options, globals) {
   }
 
   function replaceMail(wholeMatch, mail) {
-    var unescapedStr = showdown.subParser('unescapeSpecialChars')(mail);
-    return showdown.subParser('encodeEmailAddress')(unescapedStr);
+    var href = 'mailto:';
+    mail = showdown.subParser('unescapeSpecialChars')(mail);
+    if (options.encodeEmails) {
+      mail = showdown.helper.encodeEmailAddress(mail);
+      href = showdown.helper.encodeEmailAddress(href + mail);
+    } else {
+      href = href + mail;
+    }
+    return '<a href="' + href + '">' + mail + '</a>';
   }
 
   text = globals.converter._dispatch('autoLinks.after', text, options, globals);

test/features/disable-email-encoding.html

@@ -0,0 +1 @@
+<p>this email <a href="mailto:foobar@example.com">foobar@example.com</a> should not be encoded</p>

test/features/disable-email-encoding.md

@@ -0,0 +1 @@
+this email <foobar@example.com> should not be encoded

test/node/showdown.helpers.js

@@ -0,0 +1,30 @@
+/**
+ * Created by Estevao on 27/01/2017.
+ */
+
+var bootstrap = require('../bootstrap.js'),
+  showdown = bootstrap.showdown,
+  encoder = showdown.helper.encodeEmailAddress;
+
+describe('encodeEmailAddress', function () {
+  'use strict';
+  var email = 'foobar@example.com',
+      encodedEmail = encoder(email);
+
+  it('should encode email', function () {
+    encodedEmail.should.not.equal(email);
+  });
+
+  it('should decode to original email', function () {
+    var decodedEmail = encodedEmail.replace(/&#(.+?);/g, function (wm, cc) {
+      if (cc.charAt(0) === 'x') {
+        //hex
+        return String.fromCharCode('0' + cc);
+      } else {
+        //dec
+        return String.fromCharCode(cc);
+      }
+    });
+    decodedEmail.should.equal(email);
+  });
+});

test/node/testsuite.features.js

@@ -53,6 +53,8 @@ describe('makeHtml() features testsuite', function () {
       converter = new showdown.Converter({ghCompatibleHeaderId: true});
     } else if (testsuite[i].name === 'ghMentions') {
       converter = new showdown.Converter({ghMentions: true});
+    } else if (testsuite[i].name === 'disable-email-encoding') {
+      converter = new showdown.Converter({encodeEmails: false});
     } else {
       converter = new showdown.Converter();
     }