# README
Safe HTML for Go
safehtml provides immutable string-like types that wrap web types such as
HTML, JavaScript and CSS. These wrappers are safe by construction against XSS
and similar web vulnerabilities, and they can only be interpolated in safe ways.
You can read more about our approach to web security in our
whitepaper,
or this OWASP talk.
Additional subpackages provide APIs for managing exceptions to the
safety rules, and a template engine with a syntax and interface that closely
matches html/template. You can refer
to the godoc
for each (sub)package for the API documentation and code examples.
More end-to-end demos are available in example_test.go.
This is not an officially supported Google product.
# Packages
Package legacyconversions provides functions to create values of package safehtml types from plain strings.
Package template (safehtml/template) implements data-driven templates for
generating HTML output safe against code injection.
Package testconversions provides functions to to create arbitrary values of package safehtml types for use by tests only.
Package uncheckedconversions provides functions to create values of package safehtml types from plain strings.
# Functions
CSSRule constructs a StyleSheet containng a CSS rule of the form: selector{style} It returns an error if selector contains disallowed characters or unbalanced brackets.
HTMLConcat returns an HTML which contains, in order, the string representations of the given htmls.
HTMLEscaped returns an HTML whose value is text, with the characters [&<>"'] escaped.
IdentifierFromConstant constructs an Identifier with its underlying identifier set to the given string value, which must be an untyped string constant.
IdentifierFromConstantPrefix constructs an Identifier with its underlying string set to the string formed by joining prefix, which must be an untyped string constant, and value with a hyphen.
ScriptFromConstant constructs a Script with its underlying script set to the given script, which must be an untyped string constant.
ScriptFromDataAndConstant constructs a Script of the form
var name = data; script
where name is the supplied variable name, data is the supplied data value encoded as JSON using encoding/json.Marshal, and script is the supplied JavaScript statement or sequence of statements.
StyleFromConstant constructs a Style with its underlying style set to the given style, which must be an untyped string constant, and panics if the style string does not pass basic syntax checks.
StyleFromProperties constructs a Style containining properties whose values are set in properties.
StyleSheetFromConstant constructs a StyleSheet with the underlying stylesheet set to the given styleSheet, which must be an untyped string constant.
TrustedResourceURLAppend URL-escapes a string and appends it to the TrustedResourceURL.
TrustedResourceURLFormatFromConstant constructs a TrustedResourceURL from a format string, which must be an untyped string constant, and string arguments.
TrustedResourceURLFormatFromFlag is a variant of TrustedResourceURLFormatFromConstant that constructs a TrustedResourceURL from a format string, which is given as a flag.Value, and string arguments.
TrustedResourceURLFromConstant constructs a TrustedResourceURL with its underlying URL set to the given url, which must be an untyped string constant.
TrustedResourceURLFromFlag returns a TrustedResourceURL containing the string representation of the retrieved value of the flag.
TrustedResourceURLWithParams constructs a new TrustedResourceURL with the given key-value pairs added as query parameters.
URLSanitized returns a URL whose value is url, validating that the input string matches a pattern of commonly used safe URLs.
URLSetSanitized returns a safe srcset by individually vetting each substring that specifies a URL.
# Constants
InnocuousPropertyValue is an innocuous property generated by filter when its input unsafe.
InnocuousURL is an innocuous URL generated by URLSanitized when passed an unsafe URL.
# Structs
An HTML is an immutable string-like type that is safe to use in HTML contexts in DOM APIs and HTML documents.
A Identifier is an immutable string-like type that is safe to use in HTML contexts as an identifier for HTML elements.
A Script is an immutable string-like type which represents JavaScript code and guarantees that its value, as a string, will not cause execution of unconstrained attacker controlled code (cross-site scripting) when evaluated as JavaScript in a browser.
A Style is an immutable string-like type which represents a sequence of CSS declarations (property_name1: property_value1; property_name2: property_value2; ...) and guarantees that its value will not cause untrusted script execution (cross-site scripting) when evaluated as CSS in a browser.
StyleProperties contains property values for CSS properties whose names are the hyphen-separated form of the field names.
A StyleSheet is an immutable string-like type which represents a CSS style sheet and guarantees that its value, as a string, will not cause untrusted script execution (cross-site scripting) when evaluated as CSS in a browser.
A TrustedResourceURL is an immutable string-like type referencing the application’s own, trusted resources.
A URL is an immutable string-like type that is safe to use in URL contexts in DOM APIs and HTML documents.
URLSet corresponds to the value of a srcset attribute outside a TrustedResourceURL context.
# Interfaces
HTMLer is implemented by any value that has an HTML method, which defines the safe HTML format for that value.