diff --git a/index.bs b/index.bs index 77e11a3..0753287 100644 --- a/index.bs +++ b/index.bs @@ -130,14 +130,18 @@ handle additional, application-specific use cases. SecureContext ] interface Sanitizer { constructor(optional SanitizerConfig config = {}); + DocumentFragment sanitize(SanitizerInput input); DOMString sanitizeToString(SanitizerInput input); + + SanitizerConfig config(); + static SanitizerConfig defaultConfig(); }; * The new Sanitizer(config) constructor steps - are to create a new Sanitizer instance, and to retains a copy of |config| + are to create a new Sanitizer instance, and to retain a copy of |config| as its [=configuration object=]. * The sanitize(input) method steps are to return the result of running the [=sanitize=] @@ -145,11 +149,23 @@ handle additional, application-specific use cases. * The sanitizeToString(input) method steps are to return the result of running [=sanitizeToString=] algorithm on |input|. +* The config() method steps are + to return the result of running the [=query the sanitizer config=] + algorithm. It essentially returns a copy of the Sanitizer's + [=configuration object=], with some degree of normalization. +* The value of the static + defaultConfig() method steps + are to return the value of the [=default configuration=] object. Example: ```js // Replace an element's content from unsanitized input: element.replaceChildren(new Sanitizer().sanitize(userControlledInput)); + + // defaultConfig() and new Sanitizer().config should be the same. + // (For illustration purposes only. There are better ways of implementing + // object equality in JavaScript.) + JSON.stringify(Sanitizer.defaultConfig()) == JSON.stringify(new Sanitizer().config()); // true ``` ## Input Types ## {#inputs} @@ -240,6 +256,32 @@ Examples: new Sanitizer().sanitizeToString("abc def"); ``` +A sanitizer's configuration can be queried using the +[=query the sanitizer config=] method. + +Examples: +```js + // Does the default config allow script elements? + Sanitizer.defaultConfig().allowElements.includes("script") // false + + // We found a Sanitizer instance. Does it have an allow-list configured? + const a_sanitizer = ...; + !!a_sanitizer.config().allowElements // true, if an allowElements list is configured + + // If it does have an allow elements list, does it include the
element? + a_sanitizer.config().allowElements.includes("div") // true, if "div" is in allowElements. + + // Note that the config attribute might do some normaliztion. E.g., it won't + // contain key/value pairs that are not declare in the IDL. + Object.keys(new Sanitizer({madeUpDictionaryKey: "Hello"}).config()) // [] + + // As a Sanitizer's config describes its operation, a new sanitizer with + // another instance's configuration should behave identically. + // (For illustration purposes only. It would make more sense to just use a directly.) + const a = /* ... a Sanitizer we found somewhere ... */; + const b = new Sanitizer(a.config()); // b should behave the same as a. +``` + ### Attribute Match Lists ### {#attr-match-list} An attribute match list is a map of attribute names to element names, @@ -384,6 +426,18 @@ To handle funky elements on a given |element|, run these steps: 1. Remove the `formaction` attribute from |element|.
+
+To query the sanitizer config of a given sanitizer instance, +run these steps: + 1. Let |sanitizer| be the current Sanitizer. + 2. Let |config| be |sanitizer|'s [=configuration object=], or the + [=default configuration=] if no [=configuration object=] was given. + 3. Let |result| be a newly constructed SanitizerOptions dictionary. + 4. For any non-empty member of |config| whose key is declared in + SanitizerOptions, copy the value to |result|. + 5. Return |result|. +
+ ### The Effective Configuration ### {#configuration} A Sanitizer is potentially complex, so we will define a helper