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

Commit

Permalink
updated 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 fa24fa2 commit bcd6047
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 may implement another tag balancing algorithm before invoking purify. But the default one should still be enabled, unless you're sure the self-contained requirement is met.

The ``stackSize`` (default: 100) is a limit imposed 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 and has exceeded the allowed limit, the algorithm will terminate and cease processing any data further but simply close all of those tags.

## Development

### How to build
Expand Down

0 comments on commit bcd6047

Please sign in to comment.