Plugin API / Hooks for custom filters and sanitation about dompurify

[mozfreddyb]

If I were to write a customization on top of DOMPurify, I'd like to register call backs (the JS name for hooks :P) for events before and after the filtering of each (attribute, tag, entity).

This kinda matches what your proposal says, if I understand you correctly.

[arbixy]

It would be good that the current sanitize configuration is provided as parameter, closure or some getter to these event callbacks so that the user could modify it during the process in order to achieve better results before the next hooked stage or any api helping tools what so ever.

[cure53]

@mozfreddyb True, that's what I meant.

@arbixy Yes, that would allow you to flatten, re-configure per node, enforce tag-attribute white-lists etc.

[arbixy]

Perhaps some query tools would be a great addition, too.
Or api for the ones used in the library itself.
I mean on a lower level than current.

[cure53]

@arbixy What do you mean by query tools?

@ALL Now, let's do a quick dry run as to how it could look like. Let's assume we want to install a hook/callback in _initDocument():

Without

            /* Exit directly if we have nothing to do */
            if (typeof dirty === 'string' && dirty.indexOf('<') === -1) { 
                return dirty; 
            }

            /* Create documents to map markup to */
            var dom = document.implementation.createHTMLDocument('');
                dom.body.parentNode.removeChild(dom.body.parentNode.firstElementChild);
                dom.body.outerHTML = dirty;

            /* Cover IE9's buggy outerHTML behavior */
            if(dom.body === null) {
                dom = document.implementation.createHTMLDocument('');
                dom.body.innerHTML = dirty;
                if(dom.body.firstChild && dom.body.firstChild.nodeName
                    && !WHOLE_DOCUMENT
                    && dom.body.firstChild.nodeName === 'STYLE'){
                    dom.body.removeChild(dom.body.firstChild);
                }
            }

With Callback

            /* Exit directly if we have nothing to do */
            if (typeof dirty === 'string' && dirty.indexOf('<') === -1) { 
                return dirty; 
            }

            /* Create documents to map markup to */
            var dom = document.implementation.createHTMLDocument('');
                dom.body.parentNode.removeChild(dom.body.parentNode.firstElementChild);
                dom.body.outerHTML = dirty;

            /* NEWNEWNEW Basic Callback NEWNEWNEW */
            if(cfg.CALLBACKS['beforeFillDocument']){
                [dirty, dom, cfg] = cfg.CALLBACKS['beforeFillDocument'](dirty, dom, cfg)
            }  

            /* Cover IE9's buggy outerHTML behavior */
            if(dom.body === null) {
                dom = document.implementation.createHTMLDocument('');
                dom.body.innerHTML = dirty;
                if(dom.body.firstChild && dom.body.firstChild.nodeName
                    && !WHOLE_DOCUMENT
                    && dom.body.firstChild.nodeName === 'STYLE'){
                    dom.body.removeChild(dom.body.firstChild);
                }
            }

Of course we should have a dedicated callback loader that verifies if it's a function, has proper length (number of arguments) and what not. And for compatibility sake maybe no destructuring assignment etc. But the basic mechanism looks okay? Function objects stored in the config array and a direct call inside the DOMPurify methods?

[fhemberger]

Just a rough idea how do handle/execute those hooks. Just open the console (on this page for example) and execute this:

var DOMPurify = (function() {
    /* browser:true, devel:true */
    'use strict';

    var DOMPurify = {};
    var hooks = {};


    DOMPurify.sanitize = function(dirty, cfg) {

        var _sanitizeElements = function(currentNode) {
            currentNode = _executeHook('beforeSantitizeElements', currentNode);

            // do the magic
            console.log('_sanitizeElements', currentNode);

            currentNode = _executeHook('afterSantitizeElements', currentNode);
        };


        var _executeHook = function(entryPoint, currentNode) {
            var modifiedNode;

            console.log('_executeHook:%s', entryPoint);
            hooks[entryPoint].forEach(function(hook) {
                modifiedNode = hook.call(DOMPurify, currentNode, cfg);

                if (!modifiedNode) { return console.error('Hook for "' + entryPoint + '" didn\'t returned a node. Skipping.'); }
                currentNode = modifiedNode;
            });

            return currentNode;
        };

        // Dummy execution
        _sanitizeElements( document.getElementsByTagName('body')[0] );
    };


    DOMPurify.addHook = function(entryPoint, hookFunction) {

        hooks[entryPoint] = hooks[entryPoint] || [];
        hooks[entryPoint].push(hookFunction);
    };

    return DOMPurify;
})();


// --- Test code ---
DOMPurify.addHook('beforeSantitizeElements', function(currentNode, config) {
    console.log('before:function 1');
    return currentNode;
});

DOMPurify.addHook('beforeSantitizeElements', function(currentNode, config) {
    console.log('before:function 2');
});

DOMPurify.addHook('afterSantitizeElements', function(currentNode, config) {
    console.log('after:function 1');
    return currentNode;
});

DOMPurify.sanitize();

Additionally, you could add a validation step in addHook to check if the argument passed is in an array of valid entry points and throw an error if not. We should also try to have a consistent signature for the hook function if possible (some hooks might execute on the raw string, some on the current node).

[cure53]

Makes perfect sense, yes! Shall I add a branch for that? I think the earlier we have something to hack on the better. And the general idea seems to be robust enough to start playing.

[fhemberger]

Sure, go ahead. ;)

[cure53]

Created the HOOK_API branch.

[fhemberger]

I just added my basic hook handling to it.

[cure53]

See fbe0fa46c6cd042e3807de2661410e6d517036b0

Nice, thanks! I did some changes and added a bunch of demo cases to see how it could work. I also decided to rename the demo folder as the name was misleading.

Feedback very welcome. There's also a first hook - doing nothing but capitalizing text node content for demo purposes.

[cure53]

I am mostly done with the rest of the hook implementation. I also added support for two new config flags and I think we are pretty much ready for a new release. What do you think?

1246610ec2431b8febc80f0096140acbef27eefd

[fhemberger]

Cool, LGTM! 👍