On a CMS or WordPress
When other people write a site's pages, they can place players with SonicFrame's tags. Nothing they write in a tag's text or attributes runs as code; your site's HTML filter decides which tags they may write at all.
Who does what
- SonicFrame shows every title, label and attribute as text, never as HTML, checks every address (only http, https or relative), and a tag can never loosen what your code set (see Security).
-
Your HTML filter (WordPress's KSES,
DOMPurify, your server's own) decides what an author
may write. A
<sonic-player onclick="…">or a<a href="javascript:…">would be run by the browser before SonicFrame ever sees it, so the filter allows thesonic-tags with their attributes and nothing namedon…. -
Your own code never writes
SonicFrame's results into the page as HTML: a
track.titleor a feed'stitleholds the text as it came, markup included. UsetextContent.
The tags to allow
SONIC_TAGS (in sonicframe and
sonicframe/analysis) lists each tag with
the attributes it reads, the children that count (a
playlist's links) and the starts of names it reads too
(the recorder's icon-). None starts with
on. The few marked
trustedOnly send what a visitor does to an
address the author picks: upload-url sends
a visitor's recording there. Allow those only to authors
you trust.
With DOMPurify, on a server or in the page:
import DOMPurify from 'dompurify';
import { SONIC_TAGS } from 'sonicframe/analysis';
const tags = new Set(SONIC_TAGS.map((tag) => tag.tag));
const names = new Set(
SONIC_TAGS.flatMap((tag) =>
tag.attributes.filter((name) => !tag.trustedOnly.includes(name)),
),
);
const prefixes = SONIC_TAGS.flatMap((tag) => tag.prefixes);
const clean = DOMPurify.sanitize(html, {
CUSTOM_ELEMENT_HANDLING: {
tagNameCheck: (name) => tags.has(name),
attributeNameCheck: (name) =>
names.has(name) || prefixes.some((start) => name.startsWith(start)),
allowCustomizedBuiltInElements: false,
},
});
WordPress: the filter
WordPress lets authors and contributors write only the
HTML its KSES filter allows. This adds SonicFrame's tags
to what a post may hold, with
upload-url left out; add it to the
recorder's list only if every author can be trusted with
your visitors' recordings. For the recorder's own
buttons, add icon- and the name of each
action your site uses.
add_filter( 'wp_kses_allowed_html', 'sonicframe_allowed_html', 10, 2 );
function sonicframe_allowed_html( $allowed, $context ) {
if ( 'post' !== $context ) {
return $allowed;
}
$tags = array(
'sonic-player' => array(
'src', 'preload', 'peaks', 'peaks-channel', 'peaks-max', 'peaks-normalize', 'theme',
'palette', 'wave', 'font', 'font-src', 'font-stylesheet', 'label', 'artist', 'line',
'meta', 'volume', 'spectrogram', 'zoom', 'zoom-max', 'minimap', 'chapters', 'chapters-options',
'chapter-options', 'media-session', 'media-title', 'media-artist', 'media-album',
'media-artwork', 'keys', 'remember', 'remember-key', 'a11y-lang', 'a11y-label',
'a11y-chapters', 'a11y-description', 'a11y-zoom', 'a11y-minimap', 'a11y-keys',
'a11y-remember', 'load-error', 'a11y-load-error', 'a11y-slider-name', 'decode-stream',
'decode-stream-max-bytes', 'decode-stream-max-seconds', 'background-color',
'background-gradient',
'background-image',
'background-options', 'background-angle', 'background-blur', 'background-opacity',
'background-effects', 'background-animation', 'background-duration', 'time-precision',
'time-fps', 'time-hours', 'time-decimal', 'time-format',
),
'sonic-playlist' => array(
'src', 'feed', 'feed-order', 'feed-limit', 'feed-max-size', 'feed-max-depth',
'feed-max-elements', 'feed-max-attributes', 'feed-max-name-length', 'start', 'layout',
'advance', 'repeat', 'shuffle', 'gap', 'previous-restarts', 'play-on-select', 'list',
'list-place', 'list-placement', 'list-side', 'list-width', 'list-max-height',
'list-header', 'list-stay-open', 'list-backdrop', 'list-animation', 'list-palette',
'buttons', 'remember-key', 'now-playing', 'fetch-credentials', 'a11y-label',
'a11y-announce', 'a11y-lang', 'peaks-channel', 'peaks-max', 'peaks-normalize', 'theme',
'palette', 'wave', 'font', 'font-src', 'font-stylesheet', 'line', 'meta', 'volume',
'spectrogram', 'zoom', 'zoom-max', 'minimap', 'chapters-options', 'chapter-options', 'media-session',
'media-title', 'media-artist', 'media-album', 'media-artwork', 'keys', 'remember',
'a11y-chapters', 'a11y-description', 'a11y-zoom', 'a11y-minimap', 'a11y-keys',
'a11y-remember', 'load-error', 'a11y-load-error', 'a11y-slider-name', 'decode-stream',
'decode-stream-max-bytes', 'decode-stream-max-seconds', 'background-color',
'background-gradient',
'background-image',
'background-options', 'background-angle', 'background-blur', 'background-opacity',
'background-effects', 'background-animation', 'background-duration', 'time-precision',
'time-fps', 'time-hours', 'time-decimal', 'time-format',
),
'sonic-now-playing' => array(
'when', 'place', 'align', 'offset', 'width', 'z-index', 'parts', 'palette', 'font',
'font-src', 'font-stylesheet', 'close', 'animation', 'animation-type', 'a11y-label',
'a11y-announce', 'a11y-lang',
),
'sonic-recorder' => array(
'max-seconds', 'max', 'live', 'live-seconds', 'window', 'theme', 'palette', 'wave',
'font', 'font-src', 'font-stylesheet', 'hold', 'after-send', 'keep', 'idle-parts',
'recording-parts', 'review-parts', 'actions', 'after-stop', 'align', 'icon-record',
'icon-stop', 'icon-pause', 'icon-resume', 'icon-discard', 'icon-send', 'icon-cancel',
'upload-method', 'upload-field', 'cancel-send', 'record-style', 'record-color',
'rec-place', 'rec-blink', 'record-blink', 'mic-style', 'mic-color', 'a11y-lang',
'a11y-announce-every',
),
);
foreach ( $tags as $tag => $names ) {
$allowed[ $tag ] = array_fill_keys( $names, true );
}
// The playlist's links: the address and the data- attributes it reads.
$allowed['a'] = array_merge(
$allowed['a'] ?? array(),
array_fill_keys(
array(
'href', 'data-artist', 'data-album', 'data-artwork', 'data-peaks', 'data-duration',
'data-chapters', 'data-id',
),
true
)
);
return $allowed;
}
WordPress: a shortcode or a block
A plugin that writes the tags for its authors escapes every value on the server, whoever the author is, even one allowed to post unfiltered HTML. The audio-player plugins whose shortcodes let a contributor run a script all skipped this step for one attribute.
-
Every attribute through
esc_attr(); every address first throughesc_url()(which dropsjavascript:). -
A list or options as JSON through
wp_json_encode(), thenesc_attr(). -
Names read from a sound file (its ID3 title and
artist) are outside text too: through
esc_attr()into an attribute, oresc_html()into a link's text. - Never a value written into the page as it came, and never a tag built by joining strings without escaping each piece.
add_shortcode( 'sonic_player', 'sonicframe_player_shortcode' );
function sonicframe_player_shortcode( $atts ) {
$atts = shortcode_atts(
array( 'src' => '', 'label' => '', 'theme' => '' ),
$atts,
'sonic_player'
);
return sprintf(
'<sonic-player src="%s" label="%s" theme="%s"></sonic-player>',
esc_url( $atts['src'] ),
esc_attr( $atts['label'] ),
esc_attr( $atts['theme'] )
);
}
The page also loads SonicFrame and registers the tags
once (defineSonicPlayer(), and the others
it uses); see
Tag attributes.