Skip to content
This repository has been archived by the owner on Jul 15, 2019. It is now read-only.

Commit

Permalink
update README on tag balancing
Browse files Browse the repository at this point in the history
  • Loading branch information
adon committed Aug 30, 2015
1 parent 45dd4c0 commit 4f3f134
Showing 1 changed file with 30 additions and 0 deletions.
30 changes: 30 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,36 @@ var input = '...';
var result = purifier.purify(input);
```

## Advanced Usage

The following outlines the configuration that is secure by default. You should perform due dilligence to confirm your use cases are safe before disabling or altering the configurations.

```js
// The default configuration
new Purifier({
whitelistTags: ['a', '...'],
whitelistAttributes: ['href', '...'],
enableCanonicalization: true,
tagBalance: {
enabled: true,
stackSize: 100
}
});
```

<!--
#### whitelistTags
#### whitelistAttributes
#### enableCanonicalization
-->

#### tagBalance
The untrusted data must be self-contained. Therefore, it cannot close any tags prior to its inclusion, nor leave any of its own tags unclosed. An efficient and simple tag balancing algorithm is applied by default to enforce this goal only, and may not produce perfectly balanced output. You can implement your own tag balancing before invoking purify. But the default one should be still enabled, unless you're sure your algorithm can meet the self-contained requirement.

The ``stackSize`` is a limit on the maximum number of unclosed tags (or the max levels of nested tags). When an untrusted data attempts to open tags that are so nested to exceed the allowed limit, the algorithm will cease further processing the data but simply close all of those tags.

## Development

### How to build
Expand Down

0 comments on commit 4f3f134

Please sign in to comment.