Version 2.3.0

Author: CoinK0in

README.md

@@ -31,15 +31,16 @@ The content is encrypted with AES-256 in Python using PyCryptodome, and decrypte
   * [Usage](#usage)
     * [Global password protection](#global-password-protection)
     * [Secret from environment](#secret-from-environment)
-    * [Customization](#extra-vars-customization)
+    * [Customization](#default-vars-customization)
   * [Features](#features)
     * [HighlightJS support](#highlightjs-support) *(default)*
     * [Arithmatex support](#arithmatex-support) *(default)*
     * [Mermaid2 support](#mermaid-support) *(default)*
     * [Tag encrypted page](#tag-encrypted-page) *(default)*
-    * [Rebember password](#rebember-password)
+    * [Remember password](#remember-password)
     * [Encrypt something](#encrypt-something)
     * [Search index encryption](#search-index-encryption)
+    * [Override default templates](#override-default-templates)
     * [Add button](#add-button)
     * [Reload scripts](#reload-scripts)
   * [Contributing](#contributing)
@@ -58,7 +59,7 @@ Install the package from source with pip:
 ```bash
 cd mkdocs-encryptcontent-plugin/
 python3 setup.py sdist bdist_wheel
-pip3 install dist/mkdocs_encryptcontent_plugin-2.2.1-py3-none-any.whl
+pip3 install dist/mkdocs_encryptcontent_plugin-2.3.0-py3-none-any.whl
 ```
 
 Enable the plugin in your `mkdocs.yml`:
@@ -111,7 +112,7 @@ plugins:
 > **NOTE** Keep in mind that if the `use_secret:` configuration is set, it will always be used even if you have also set a global password with the `global_password` variable.
 
 
-### Extra vars customization
+### Default vars customization
 
 Optionally you can use some extra variables in plugin configuration to customize default messages.
 
@@ -218,7 +219,7 @@ For example, in your theme template, you can use conditional check to add custom
 <a {% if nav_item.encrypted %}class="mkdocs-encrypted-class"{% endif %}href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
 ```
 
-### Rebember password
+### Remember password
 
 Related to [issue #6](https://github.com/CoinK0in/mkdocs-encryptcontent-plugin/issues/6)
 
@@ -240,14 +241,14 @@ If your password is a [global password](#global-password-protection), you can fi
 The key that will be created with a generic name to making it accessible, by default, on all the pages of your site.
 
 The form of decryption remains visible as long as the content has not been successfully decrypted, which allows in case of error to retry. 
-All keys created with this feature on localstorage have an default expire time daly set to 24 hours, just cause ...
+All keys created with this feature on sessionStorage/localStorage have an default expire time daly set to 24 hours, just cause ...
 
-However *(optionally)*, its possible to change the default expire time by setting options `default_expire_dalay: <number>` in your `mkdocs.yml`. Your configuration should look like this when you enabled this feature :
+However *(optionally)*, its possible to change the default expire time by setting options `default_expire_delay: <number>` in your `mkdocs.yml`. Your configuration should look like this when you enabled this feature :
 ```yaml
 plugins:
     - encryptcontent:
         remember_password: True
-        default_expire_dalay: 24   # <-- Default expire delay in hours (optional)
+        default_expire_delay: 24   # <-- Default expire delay in hours (optional)
 ```
 
 > **NOTE** The expired elements of the localStorage are only deleted by the execution of the decrypt-content.js scripts and therefore by the navigation on the site. Secret items can therefore remain visible in local storage after their expiration dates. 
@@ -371,6 +372,42 @@ When the configuration mode is set to "**dynamically**", the [javascripts contri
 
 > **NOTE** The mode 'dynamically' is currently **not compatible with Material Theme** !
 
+### Override default templates
+
+Related to [issue #32](https://github.com/CoinK0in/mkdocs-encryptcontent-plugin/issues/32)
+
+You can override the default templates with your own templates by providing an actual replacement path in the `html_template_path` *(HTML)* and `js_template_path` *(JS)* directives. Overridden templates **completely** replace the default templates. You **must** therefore copy the default templates to keep this module working.
+
+```yaml
+plugins:
+    - encryptcontent:
+        html_template_path: "/root/real/path/mkdocs_poc/my_html_template.html"
+        js_template_path: "/root/real/path/mkdocs_poc/my_js_template.js"
+```
+
+When you overriding the default templates, you can add and use your own Jinja variables to condition and enrich your template, by defining `html_extra_vars` and `js_extra_vars` directives in key/value format. Added values can be used in your Jinja templates via the variable `extra`.
+
+```yaml
+plugins:
+    - encryptcontent:
+        html_extra_vars:
+            my_extra: "extra value"
+            <key>: <value>
+        js_extra_vars:
+            my_extra: "extra value"
+            <key>: <value>
+```
+
+For example, you can modify your HTML template, to add a new title with your own text variable.
+
+```jinja
+[ ... ] 
+<h2>{{ extra.my_extra }}</h2>
+[ ... ]
+```
+
+> **NOTE** You must avoid replacing/overwriting the variables used by default by this module. The limitations are the same as those of the jinja models. Issues related to template override will not be addressed.
+
 ### Add button
 
 Add `password_button: True` in plugin configuration variable, to add button to the right of the password field.

encryptcontent/decrypt-contents.tpl.js

@@ -32,27 +32,43 @@ function decrypt_content(password, iv_b64, ciphertext_b64, padding_char) {
 };
 
 {% if remember_password -%}
-/* Set key:value with expire time in localStorage */
+/* Set key:value with expire time in sessionStorage/localStorage */
 function setItemExpiry(key, value, ttl) {
     const now = new Date()
     const item = {
         value: encodeURIComponent(value),
         expiry: now.getTime() + ttl,
     }
+    {% if session_storage -%}
+    sessionStorage.setItem('encryptcontent_' + encodeURIComponent(key), JSON.stringify(item))
+    {%- else %}
     localStorage.setItem('encryptcontent_' + encodeURIComponent(key), JSON.stringify(item))
+    {%- endif %}
 };
 
-/* Delete key with specific name in localStorage */
+/* Delete key with specific name in sessionStorage/localStorage */
 function delItemName(key) {
+    {% if session_storage -%}
+    sessionStorage.removeItem('encryptcontent_' + encodeURIComponent(key));
+    {%- else %}
     localStorage.removeItem('encryptcontent_' + encodeURIComponent(key));
+    {%- endif %}
 };
 
-/* Get key:value from localStorage */
+/* Get key:value from sessionStorage/localStorage */
 function getItemExpiry(key) {
+    {% if session_storage -%}
+    var remember_password = sessionStorage.getItem('encryptcontent_' + encodeURIComponent(key));
+    {%- else %}
     var remember_password = localStorage.getItem('encryptcontent_' + encodeURIComponent(key));
+    {%- endif %}
     if (!remember_password) {
         // fallback to search default password defined by path
+        {% if session_storage -%}
+        var remember_password = sessionStorage.getItem('encryptcontent_' + encodeURIComponent("/"));
+        {%- else %}
         var remember_password = localStorage.getItem('encryptcontent_' + encodeURIComponent("/"));
+        {%- endif %}
         if (!remember_password) {
             return null
         }
@@ -61,7 +77,7 @@ function getItemExpiry(key) {
     const now = new Date()
     if (now.getTime() > item.expiry) {
         // if the item is expired, delete the item from storage and return null
-        localStorage.removeItem('encryptcontent_' + encodeURIComponent(key))
+        delItemName(key)
         return null
     }
     return decodeURIComponent(item.value)
@@ -202,7 +218,7 @@ function init_decryptor() {
     {%- endif %}
 
     {% if remember_password -%}
-    /* If remember_password is set, try to use localstorage item to decrypt content when page is loaded */
+    /* If remember_password is set, try to use sessionStorage/localstorage item to decrypt content when page is loaded */
     var password_cookie = getItemExpiry(window.location.pathname);
     if (password_cookie) {
         password_input.value = password_cookie;
@@ -218,7 +234,7 @@ function init_decryptor() {
             var something_decrypted = decrypt_somethings(password_input, encrypted_something);
             {%- endif %}
         } else {
-            // remove item on localStorage if decryption process fail (Invalid item)
+            // remove item on sessionStorage/localStorage if decryption process fail (Invalid item)
             delItemName(window.location.pathname)
         }
     };
@@ -234,8 +250,8 @@ function init_decryptor() {
             );
             if (content_decrypted) {
                 {% if remember_password -%}
-                // keep password value on localStorage with specific path (relative)
-                setItemExpiry(document.location.pathname, password_input.value, 1000*3600*{{ default_expire_dalay | int }});
+                // keep password value on sessionStorage/localStorage with specific path (relative)
+                setItemExpiry(document.location.pathname, password_input.value, 1000*3600*{{ default_expire_delay | int }});
                 {%- endif %}
                 // continue to decrypt others parts
                 {% if experimental -%}
@@ -266,8 +282,8 @@ function init_decryptor() {
             );
             if (content_decrypted) {
                 {% if remember_password -%}
-                // keep password value on localStorage with specific path (relative)
-                setItemExpiry(location_path, password_input.value, 1000*3600*{{ default_expire_dalay | int }});
+                // keep password value on sessionStorage/localStorage with specific path (relative)
+                setItemExpiry(location_path, password_input.value, 1000*3600*{{ default_expire_delay | int }});
                 {%- endif %}
                 // continue to decrypt others parts
                 {% if experimental -%}

encryptcontent/plugin.py

@@ -27,19 +27,11 @@
 ]
 
 PLUGIN_DIR = os.path.dirname(os.path.realpath(__file__))
-DECRYPT_FORM_TPL_PATH = os.path.join(PLUGIN_DIR, 'decrypt-form.tpl.html')
-DECRYPT_JS_TPL_PATH = os.path.join(PLUGIN_DIR, 'decrypt-contents.tpl.js')
-
-with open(DECRYPT_FORM_TPL_PATH, 'r') as template_html:
-    DECRYPT_FORM_TPL = template_html.read()
-
-with open(DECRYPT_JS_TPL_PATH, 'r') as template_js:
-    DECRYPT_JS_TPL = template_js.read()
 
 SETTINGS = {
     'title_prefix': '[Protected] ',
     'summary': 'This content is protected with AES encryption. ',
-    'placeholder': 'Provide password and press ENTER',
+    'placeholder': 'Use CTRL+ENTER to provide global password',
     'password_button_text': 'Decrypt',
     'decryption_failure_message': 'Invalid password.',
     'encryption_info_message': 'Contact your administrator for access to this page.'
@@ -53,22 +45,32 @@ class encryptContentPlugin(BasePlugin):
     """ Plugin that encrypt markdown content with AES and inject decrypt form. """
 
     config_scheme = (
-        ('use_secret', config_options.Type(string_types, default=None)),
+        # default customization
         ('title_prefix', config_options.Type(string_types, default=str(SETTINGS['title_prefix']))),
         ('summary', config_options.Type(string_types, default=str(SETTINGS['summary']))),
         ('placeholder', config_options.Type(string_types, default=str(SETTINGS['placeholder']))),
         ('decryption_failure_message', config_options.Type(string_types, default=str(SETTINGS['decryption_failure_message']))),
         ('encryption_info_message', config_options.Type(string_types, default=str(SETTINGS['encryption_info_message']))),
         ('password_button_text', config_options.Type(string_types, default=str(SETTINGS['password_button_text']))),
+        ('password_button', config_options.Type(bool, default=False)),
+        # password feature
         ('global_password', config_options.Type(string_types, default=None)),
+        ('use_secret', config_options.Type(string_types, default=None)),
         ('password', config_options.Type(string_types, default=None)),
+        ('remember_password', config_options.Type(bool, default=False)),
+        ('session_storage', config_options.Type(bool, default=True)),
+        ('default_expire_delay', config_options.Type(int, default=int(24))),
+        # default features enabled
         ('arithmatex', config_options.Type(bool, default=True)),
         ('hljs', config_options.Type(bool, default=True)),
         ('mermaid2', config_options.Type(bool, default=True)),
-        ('remember_password', config_options.Type(bool, default=False)),
-        ('default_expire_dalay', config_options.Type(int, default=int(24))),
         ('tag_encrypted_page', config_options.Type(bool, default=True)),
-        ('password_button', config_options.Type(bool, default=False)),
+        # override feature
+        ('html_template_path', config_options.Type(string_types, default=str(os.path.join(PLUGIN_DIR, 'decrypt-form.tpl.html')))),
+        ('html_extra_vars', config_options.Type(dict, default={})),
+        ('js_template_path', config_options.Type(string_types, default=str(os.path.join(PLUGIN_DIR, 'decrypt-contents.tpl.js')))),
+        ('js_extra_vars', config_options.Type(dict, default={})),
+        # others features
         ('encrypted_something', config_options.Type(dict, default={})),
         ('search_index', config_options.Choice(('clear', 'dynamically', 'encrypted'), default='encrypted')),
         ('reload_scripts', config_options.Type(list, default=[])),
@@ -104,7 +106,7 @@ def __encrypt_text_aes__(self, text, password):
     def __encrypt_content__(self, content, base_path):
         """ Replaces page or article content with decrypt form. """
         ciphertext_bundle = self.__encrypt_text_aes__(content, str(self.config['password']))
-        decrypt_form = Template(DECRYPT_FORM_TPL).render({
+        decrypt_form = Template(self.config['html_template']).render({
             # custom message and template rendering
             'summary': self.config['summary'],
             'placeholder': self.config['placeholder'],
@@ -115,13 +117,15 @@ def __encrypt_content__(self, content, base_path):
             # otherwise the output string will be wrapped with b''
             'ciphertext_bundle': b';'.join(ciphertext_bundle).decode('ascii'),
             'js_libraries': JS_LIBRARIES,
-            'base_path': base_path
+            'base_path': base_path,
+            # add extra vars
+            'extra': self.config['html_extra_vars']
         })
         return decrypt_form
 
     def __generate_decrypt_js__(self):
         """ Generate JS file with enable feature. """
-        decrypt_js = Template(DECRYPT_JS_TPL).render({
+        decrypt_js = Template(self.config['js_template']).render({
             # custom message and template rendering
             'password_button': self.config['password_button'],
             'decryption_failure_message': self.config['decryption_failure_message'],
@@ -130,10 +134,13 @@ def __generate_decrypt_js__(self):
             'hljs': self.config['hljs'],
             'mermaid2': self.config['mermaid2'],
             'remember_password': self.config['remember_password'],
-            'default_expire_dalay': int(self.config['default_expire_dalay']),
+            'session_storage': self.config['session_storage'],
+            'default_expire_delay': int(self.config['default_expire_delay']),
             'encrypted_something': self.config['encrypted_something'],
             'reload_scripts': self.config['reload_scripts'],
-            'experimental': self.config['experimental']
+            'experimental': self.config['experimental'],
+            # add extra vars
+            'extra': self.config['js_extra_vars']
         })
         return decrypt_js
 
@@ -148,6 +155,13 @@ def on_config(self, config, **kwargs):
         :param config: global configuration object (mkdocs.yml)
         :return: global configuration object modified to include templates files
         """
+        # Override default template
+        logger.debug('Load HTML template from file: "{file}".'.format(file=str(self.config['html_template_path'])))
+        with open(self.config['html_template_path'], 'r') as template_html:
+            self.config['html_template'] = template_html.read()
+        logger.debug('Load JS template from file: "{file}".'.format(file=str(self.config['js_template_path'])))
+        with open(self.config['js_template_path'], 'r') as template_js:
+            self.config['js_template'] = template_js.read()
         # Optionnaly use Github secret
         if self.config.get('use_secret'):
             if os.environ.get(str(self.config['use_secret'])):
@@ -156,7 +170,7 @@ def on_config(self, config, **kwargs):
                 logger.error('Cannot get global password from environment variable: {var}. Abort !'.format(
                     var=str(self.config['use_secret']))
                 )
-                os._exit(1)
+                os._exit(1)                                 # prevent build without password to avoid leak
         # Set global password as default password for each page
         self.config['password'] = self.config['global_password']
         # Check if hljs feature need to be enabled, based on theme configuration

setup.py

@@ -11,7 +11,7 @@ def read(fname):
 
 setup(
     name='mkdocs-encryptcontent-plugin',
-    version='2.2.1',
+    version='2.3.0',
     author='CoinK0in',
     author_email='[email protected]',
     description='A MkDocs plugin that encrypt/decrypt markdown content with AES',