DetoXSS.Whitelist

Whitelist configuration for controlled HTML sanitization.

A whitelist defines which tags, attributes, URL attributes, and URL schemes may be preserved by DetoXSS.Sanitize.sanitizeWithWhitelist.

The whitelist is intended for allowing a small, explicit set of safe formatting features. It is not meant to allow arbitrary active HTML content. Some dangerous tags, attributes, and schemes are blocked regardless of the custom whitelist.

type alias State =

{ active : Bool

, config : Whitelist

}

Runtime state of whitelist sanitization.

The active field controls whether whitelist mode is enabled. When whitelist mode is disabled, sanitization treats the whole input as text instead of preserving HTML tags.

type alias Whitelist =

{ tags : List String

, attributes : List String

, urlAttributes : List String

, allowedSchemes : List String

}

Whitelist configuration used by sanitizeWithWhitelist.

The configuration contains four lists:

tags are HTML tag names that may be preserved.
attributes are attribute names that may be preserved.
urlAttributes are attributes whose values should be treated as URLs.
allowedSchemes are URL schemes accepted in URL-like attributes.

The configuration is normalized when it is created through helper functions such as fromLists, fromAll, or fromAllFull.

defaultConfig : Whitelist

Default whitelist configuration.

It allows a small set of common formatting tags, link and image attributes, and common URL schemes such as http:, https:, mailto:, and tel:.

initialState : State

Initial whitelist state.

The default configuration is loaded, but whitelist mode is disabled.

Use enable to activate whitelist-based sanitization.

enable : State -> State

Enable whitelist-based sanitization.

When enabled, sanitizeWithWhitelist may preserve allowed tags and attributes.

disable : State -> State

Disable whitelist-based sanitization.

When disabled, sanitizeWithWhitelist treats the whole input as text.

isEnabled : State -> Bool

Check whether whitelist mode is enabled.

set : Whitelist -> State -> State

Replace the current whitelist configuration.

The configuration is normalized before being stored. Blocked tags, blocked attributes, and blocked schemes are removed during normalization.

get :

State

-> { tags : List String

, attributes : List String

}

Get allowed tags and attributes from the current state.

fromLists : List String -> List String -> Whitelist

Create a whitelist from allowed tags and attributes.

The URL-like attributes default to href and src. The allowed URL schemes default to defaultConfig.allowedSchemes.

fromLists [ "p", "strong", "a" ] [ "href", "title" ]

fromAll : List String -> List String -> List String -> Whitelist

Create a whitelist from allowed tags, attributes, and URL schemes.

The URL-like attributes default to href and src.

fromAll
    [ "p", "a" ]
    [ "href" ]
    [ "http:", "https:" ]

fromAllFull : List String -> List String -> List String -> List String -> Whitelist

Create a full whitelist configuration.

This variant allows configuring allowed tags, allowed attributes, URL-like attributes, and allowed URL schemes explicitly.

fromAllFull
    [ "p", "a", "img" ]
    [ "href", "src", "alt" ]
    [ "href", "src" ]
    [ "http:", "https:" ]

isAllowedTag : State -> String -> Bool

Check whether a tag is allowed by the current whitelist configuration.

isAllowedAttribute : State -> String -> Bool

Check whether an attribute is allowed by the current whitelist configuration.

isUrlAttribute : State -> String -> Bool

Check whether an attribute should be treated as URL-like.

URL-like attributes are validated against the allowed URL schemes during sanitization.

getAll :

State

-> { tags : List String

, attributes : List String

, schemes : List String

}

Get allowed tags, attributes, and URL schemes from the current state.

getAllFull :

State

-> { tags : List String

, attributes : List String

, urlAttributes : List String

, schemes : List String

}

Get the full whitelist configuration from the current state.

This includes allowed tags, allowed attributes, URL-like attributes, and allowed URL schemes.

getAllowedSchemes : State -> List String

Get allowed URL schemes.

If whitelist mode is disabled, the default scheme list is returned.

setAttributes : List String -> State -> State

Replace the allowed attributes in the current whitelist state.

setUrlAttributes : List String -> State -> State

Replace the URL-like attributes in the current whitelist state.

URL-like attributes are checked against allowed URL schemes during sanitization.

setSchemes : List String -> State -> State

Replace the allowed URL schemes in the current whitelist state.

Schemes are normalized to lowercase and always end with :.

blockedTags : List String

Tags that are blocked regardless of whitelist configuration.

These tags are considered too risky to preserve in sanitized HTML.

blockedAttributes : List String

Attributes that are blocked regardless of whitelist configuration.

This includes style-related and document-embedding attributes. Inline event handler attributes such as onclick and onerror are also blocked by isBlockedAttribute.

blockedSchemes : List String

URL schemes that are blocked regardless of whitelist configuration.

isBlockedTag : String -> Bool

Check whether a tag is hard-blocked.

isBlockedAttribute : String -> Bool

Check whether an attribute is hard-blocked.

This returns True for inline event handlers such as onclick, for attributes listed in blockedAttributes, and for namespace declarations starting with xmlns.

isBlockedScheme : String -> Bool

Check whether a URL scheme is hard-blocked.

dominikmifkovic/detoxss/1.0.0

DetoXSS.Whitelist

Modules