SonicFrame v1.3.2

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 the sonic- tags with their attributes and nothing named on….
  • Your own code never writes SonicFrame's results into the page as HTML: a track.title or a feed's title holds the text as it came, markup included. Use textContent.

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 through esc_url() (which drops javascript:).
  • A list or options as JSON through wp_json_encode(), then esc_attr().
  • Names read from a sound file (its ID3 title and artist) are outside text too: through esc_attr() into an attribute, or esc_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.