Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
5.25% covered (danger)
5.25%
23 / 438
3.03% covered (danger)
3.03%
1 / 33
CRAP
0.00% covered (danger)
0.00%
0 / 1
Sanitizer
5.25% covered (danger)
5.25%
23 / 438
3.03% covered (danger)
3.03%
1 / 33
19288.35
0.00% covered (danger)
0.00%
0 / 1
 attributesAllowedInternal
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
2
 setupAttributesAllowedInternal
0.00% covered (danger)
0.00%
0 / 126
0.00% covered (danger)
0.00%
0 / 1
6
 normalizeCharReferences
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
2
 normalizeCharReferencesCallback
0.00% covered (danger)
0.00%
0 / 10
0.00% covered (danger)
0.00%
0 / 1
30
 normalizeEntity
0.00% covered (danger)
0.00%
0 / 9
0.00% covered (danger)
0.00%
0 / 1
20
 decCharReference
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
6
 hexCharReference
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
12
 validateCodepoint
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
110
 codepointToUtf8
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
2
 utf8ToCodepoint
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
2
 stripIDNs
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 cleanUrl
0.00% covered (danger)
0.00%
0 / 20
0.00% covered (danger)
0.00%
0 / 1
42
 decodeEntity
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
6
 decodeChar
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
6
 decodeCharReferences
100.00% covered (success)
100.00%
15 / 15
100.00% covered (success)
100.00%
1 / 1
5
 normalizeCss
0.00% covered (danger)
0.00%
0 / 18
0.00% covered (danger)
0.00%
0 / 1
20
 delimiterReplaceCallback
0.00% covered (danger)
0.00%
0 / 45
0.00% covered (danger)
0.00%
0 / 1
182
 delimiterReplace
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
2
 isParsoidAttr
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 1
42
 isReservedDataAttribute
66.67% covered (warning)
66.67%
2 / 3
0.00% covered (danger)
0.00%
0 / 1
2.15
 sanitizeTagAttrs
0.00% covered (danger)
0.00%
0 / 72
0.00% covered (danger)
0.00%
0 / 1
2070
 applySanitizedArgs
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 1
12
 checkCss
85.71% covered (warning)
85.71%
6 / 7
0.00% covered (danger)
0.00%
0 / 1
4.05
 cssDecodeCallback
0.00% covered (danger)
0.00%
0 / 10
0.00% covered (danger)
0.00%
0 / 1
72
 sanitizeTitleURI
0.00% covered (danger)
0.00%
0 / 14
0.00% covered (danger)
0.00%
0 / 1
20
 armorFrenchSpaces
0.00% covered (danger)
0.00%
0 / 8
0.00% covered (danger)
0.00%
0 / 1
2
 escapeIdForAttribute
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
6
 escapeIdForLink
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 escapeIdForExternalInterwiki
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 escapeIdInternalUrl
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
6
 escapeIdInternal
0.00% covered (danger)
0.00%
0 / 13
0.00% covered (danger)
0.00%
0 / 1
20
 escapeIdReferenceList
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 1
6
 normalizeSectionNameWhiteSpace
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
1<?php
2declare( strict_types = 1 );
3
4/**
5 * General token sanitizer. Strips out (or encapsulates) unsafe and disallowed
6 * tag types and attributes. Should run last in the third, synchronous
7 * expansion stage.
8 *
9 * FIXME: This code was originally ported from PHP to JS in 2012
10 * and periodically updated before being back to PHP. This code should be
11 * (a) resynced with core sanitizer changes (b) updated to use HTML5 spec
12 */
13
14namespace Wikimedia\Parsoid\Core;
15
16use InvalidArgumentException;
17use Wikimedia\Assert\Assert;
18use Wikimedia\Parsoid\Config\SiteConfig;
19use Wikimedia\Parsoid\DOM\Element;
20use Wikimedia\Parsoid\Tokens\KV;
21use Wikimedia\Parsoid\Tokens\Token;
22use Wikimedia\Parsoid\Utils\DOMCompat;
23use Wikimedia\Parsoid\Utils\DOMUtils;
24use Wikimedia\Parsoid\Utils\PHPUtils;
25use Wikimedia\Parsoid\Utils\TokenUtils;
26use Wikimedia\RemexHtml\HTMLData;
27
28class Sanitizer {
29    /**
30     * RDFa and microdata properties allow URLs, URIs and/or CURIs.
31     */
32    private const MICRODATA = [
33        'rel' => true,
34        'rev' => true,
35        'about' => true,
36        'property' => true,
37        'resource' => true,
38        'datatype' => true,
39        'typeof' => true, // RDFa
40        'itemid' => true,
41        'itemprop' => true,
42        'itemref' => true,
43        'itemscope' => true,
44        'itemtype' => true,
45    ];
46
47    private const UTF8_REPLACEMENT = "\u{FFFD}";
48
49    /**
50     * Regular expression to match various types of character references in
51     * Sanitizer::normalizeCharReferences and Sanitizer::decodeCharReferences
52     */
53    private const CHAR_REFS_REGEX =
54        '/&([A-Za-z0-9\x80-\xff]+;)
55        |&\#([0-9]+);
56        |&\#[xX]([0-9A-Fa-f]+);
57        |(&)/x';
58
59    private const INSECURE_RE = '! expression
60        | filter\s*:
61        | accelerator\s*:
62        | -o-link\s*:
63        | -o-link-source\s*:
64        | -o-replace\s*:
65        | url\s*\(
66        | image\s*\(
67        | image-set\s*\(
68        | attr\s*\([^)]+[\s,]+url
69    !ix';
70
71    /**
72     * Pattern matching evil uris like javascript:
73     * WARNING: DO NOT use this in any place that actually requires denying
74     * certain URIs for security reasons. There are NUMEROUS[1] ways to bypass
75     * pattern-based deny lists; the only way to be secure from javascript:
76     * uri based xss vectors is to allow only things that you know are safe
77     * and deny everything else.
78     * [1]: http://ha.ckers.org/xss.html
79     */
80    private const EVIL_URI_PATTERN = '!(^|\s|\*/\s*)(javascript|vbscript)([^\w]|$)!iD';
81    private const XMLNS_ATTRIBUTE_PATTERN = "/^xmlns:[:A-Z_a-z-.0-9]+$/D";
82
83    /**
84     * Tells escapeUrlForHtml() to encode the ID using the wiki's primary encoding.
85     *
86     * @since 1.30
87     */
88    public const ID_PRIMARY = 0;
89
90    /**
91     * Tells escapeUrlForHtml() to encode the ID using the fallback encoding, or return false
92     * if no fallback is configured.
93     *
94     * @since 1.30
95     */
96    public const ID_FALLBACK = 1; // public because it is accessed in Headings handler
97
98    /** Characters that will be ignored in IDNs.
99     * https://datatracker.ietf.org/doc/html/rfc8264#section-9.13
100     * https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
101     * Strip them before further processing so deny lists and such work.
102     * Part of Sanitizer::cleanUrl in core.
103     */
104    private const IDN_RE_G = "/
105                \\s|      # general whitespace
106                \u{00AD}|               # SOFT HYPHEN
107                \u{034F}|               # COMBINING GRAPHEME JOINER
108                \u{061C}|               # ARABIC LETTER MARK
109                [\u{115F}-\u{1160}]|    # HANGUL CHOSEONG FILLER..
110                            # HANGUL JUNGSEONG FILLER
111                [\u{17B4}-\u{17B5}]|    # KHMER VOWEL INHERENT AQ..
112                            # KHMER VOWEL INHERENT AA
113                [\u{180B}-\u{180D}]|    # MONGOLIAN FREE VARIATION SELECTOR ONE..
114                            # MONGOLIAN FREE VARIATION SELECTOR THREE
115                \u{180E}|               # MONGOLIAN VOWEL SEPARATOR
116                [\u{200B}-\u{200F}]|    # ZERO WIDTH SPACE..
117                            # RIGHT-TO-LEFT MARK
118                [\u{202A}-\u{202E}]|    # LEFT-TO-RIGHT EMBEDDING..
119                            # RIGHT-TO-LEFT OVERRIDE
120                [\u{2060}-\u{2064}]|    # WORD JOINER..
121                            # INVISIBLE PLUS
122                \u{2065}|               # <reserved-2065>
123                [\u{2066}-\u{206F}]|    # LEFT-TO-RIGHT ISOLATE..
124                            # NOMINAL DIGIT SHAPES
125                \u{3164}|               # HANGUL FILLER
126                [\u{FE00}-\u{FE0F}]|    # VARIATION SELECTOR-1..
127                            # VARIATION SELECTOR-16
128                \u{FEFF}|               # ZERO WIDTH NO-BREAK SPACE
129                \u{FFA0}|               # HALFWIDTH HANGUL FILLER
130                [\u{FFF0}-\u{FFF8}]|    # <reserved-FFF0>..
131                            # <reserved-FFF8>
132                [\u{1BCA0}-\u{1BCA3}]|  # SHORTHAND FORMAT LETTER OVERLAP..
133                            # SHORTHAND FORMAT UP STEP
134                [\u{1D173}-\u{1D17A}]|  # MUSICAL SYMBOL BEGIN BEAM..
135                            # MUSICAL SYMBOL END PHRASE
136                \u{E0000}|              # <reserved-E0000>
137                \u{E0001}|              # LANGUAGE TAG
138                [\u{E0002}-\u{E001F}]|  # <reserved-E0002>..
139                            # <reserved-E001F>
140                [\u{E0020}-\u{E007F}]|  # TAG SPACE..
141                            # CANCEL TAG
142                [\u{E0080}-\u{E00FF}]|  # <reserved-E0080>..
143                            # <reserved-E00FF>
144                [\u{E0100}-\u{E01EF}]|  # VARIATION SELECTOR-17..
145                            # VARIATION SELECTOR-256
146                [\u{E01F0}-\u{E0FFF}]|  # <reserved-E01F0>..
147                            # <reserved-E0FFF>
148                /xuD";
149
150    private const GET_ATTRIBS_RE = '/^[:_\p{L}\p{N}][:_\.\-\p{L}\p{N}]*$/uD';
151
152    /**
153     * Character entity aliases accepted by MediaWiki in wikitext.
154     * These are not part of the HTML standard.
155     */
156    private const MW_ENTITY_ALIASES = [
157        'רלמ;' => 'rlm;',
158        'رلم;' => 'rlm;',
159    ];
160
161    /**
162     * Fetch the list of acceptable attributes for a given element name.
163     *
164     * @param string $element
165     * @return array
166     */
167    public static function attributesAllowedInternal( string $element ): array {
168        // PORT-FIXME: this method is private in core, but used by Gallery
169        $lists = self::setupAttributesAllowedInternal();
170        $list = $lists[$element] ?? [];
171        return array_flip( $list );
172    }
173
174    /**
175     * Foreach array key (an allowed HTML element), return an array
176     * of allowed attributes
177     * @return array
178     */
179    private static function setupAttributesAllowedInternal(): array {
180        static $allowed;
181
182        if ( $allowed !== null ) {
183            return $allowed;
184        }
185
186        $common = [
187            # HTML
188            'id',
189            'class',
190            'style',
191            'lang',
192            'dir',
193            'title',
194            'tabindex',
195
196            # WAI-ARIA
197            'aria-describedby',
198            'aria-flowto',
199            'aria-hidden',
200            'aria-label',
201            'aria-labelledby',
202            'aria-owns',
203            'role',
204
205            # RDFa
206            # These attributes are specified in section 9 of
207            # https://www.w3.org/TR/2008/REC-rdfa-syntax-20081014
208            'about',
209            'property',
210            'resource',
211            'datatype',
212            'typeof',
213
214            # Microdata. These are specified by
215            # https://html.spec.whatwg.org/multipage/microdata.html#the-microdata-model
216            'itemid',
217            'itemprop',
218            'itemref',
219            'itemscope',
220            'itemtype',
221        ];
222
223        $block = array_merge( $common, [ 'align' ] );
224        $tablealign = [ 'align', 'valign' ];
225        $tablecell = [
226            'abbr',
227            'axis',
228            'headers',
229            'scope',
230            'rowspan',
231            'colspan',
232            'nowrap', # deprecated
233            'width', # deprecated
234            'height', # deprecated
235            'bgcolor', # deprecated
236        ];
237
238        # Numbers refer to sections in HTML 4.01 standard describing the element.
239        # See: https://www.w3.org/TR/html4/
240        $allowed = [
241            # 7.5.4
242            'div'        => $block,
243            'center'     => $common, # deprecated
244            'span'       => $common,
245
246            # 7.5.5
247            'h1'         => $block,
248            'h2'         => $block,
249            'h3'         => $block,
250            'h4'         => $block,
251            'h5'         => $block,
252            'h6'         => $block,
253
254            # 7.5.6
255            # address
256
257            # 8.2.4
258            'bdo'        => $common,
259
260            # 9.2.1
261            'em'         => $common,
262            'strong'     => $common,
263            'cite'       => $common,
264            'dfn'        => $common,
265            'code'       => $common,
266            'samp'       => $common,
267            'kbd'        => $common,
268            'var'        => $common,
269            'abbr'       => $common,
270            # acronym
271
272            # 9.2.2
273            'blockquote' => array_merge( $common, [ 'cite' ] ),
274            'q'          => array_merge( $common, [ 'cite' ] ),
275
276            # 9.2.3
277            'sub'        => $common,
278            'sup'        => $common,
279
280            # 9.3.1
281            'p'          => $block,
282
283            # 9.3.2
284            'br'         => array_merge( $common, [ 'clear' ] ),
285
286            # https://www.w3.org/TR/html5/text-level-semantics.html#the-wbr-element
287            'wbr'        => $common,
288
289            # 9.3.4
290            'pre'        => array_merge( $common, [ 'width' ] ),
291
292            # 9.4
293            'ins'        => array_merge( $common, [ 'cite', 'datetime' ] ),
294            'del'        => array_merge( $common, [ 'cite', 'datetime' ] ),
295
296            # 10.2
297            'ul'         => array_merge( $common, [ 'type' ] ),
298            'ol'         => array_merge( $common, [ 'type', 'start', 'reversed' ] ),
299            'li'         => array_merge( $common, [ 'type', 'value' ] ),
300
301            # 10.3
302            'dl'         => $common,
303            'dd'         => $common,
304            'dt'         => $common,
305
306            # 11.2.1
307            'table'      => array_merge( $common,
308                                [ 'summary', 'width', 'border', 'frame',
309                                        'rules', 'cellspacing', 'cellpadding',
310                                        'align', 'bgcolor',
311                                ] ),
312
313            # 11.2.2
314            'caption'    => $block,
315
316            # 11.2.3
317            'thead'      => $common,
318            'tfoot'      => $common,
319            'tbody'      => $common,
320
321            # 11.2.4
322            'colgroup'   => array_merge( $common, [ 'span' ] ),
323            'col'        => array_merge( $common, [ 'span' ] ),
324
325            # 11.2.5
326            'tr'         => array_merge( $common, [ 'bgcolor' ], $tablealign ),
327
328            # 11.2.6
329            'td'         => array_merge( $common, $tablecell, $tablealign ),
330            'th'         => array_merge( $common, $tablecell, $tablealign ),
331
332            # 12.2
333            # NOTE: <a> is not allowed directly, but this list of allowed
334            # attributes is used from the Parser object
335            'a'          => array_merge( $common, [ 'href', 'rel', 'rev' ] ), # rel/rev esp. for RDFa
336
337            # 13.2
338            # Not usually allowed, but may be used for extension-style hooks
339            # such as <math> when it is rasterized, or if $wgAllowImageTag is
340            # true
341            'img'        => array_merge( $common, [ 'alt', 'src', 'width', 'height', 'srcset' ] ),
342            # Attributes for A/V tags added in T163583 / T133673
343            'audio'      => array_merge( $common, [ 'controls', 'preload', 'width', 'height' ] ),
344            'video'      => array_merge( $common, [ 'poster', 'controls', 'preload', 'width', 'height' ] ),
345            'source'     => array_merge( $common, [ 'type', 'src' ] ),
346            'track'      => array_merge( $common, [ 'type', 'src', 'srclang', 'kind', 'label' ] ),
347
348            # 15.2.1
349            'tt'         => $common,
350            'b'          => $common,
351            'i'          => $common,
352            'big'        => $common,
353            'small'      => $common,
354            'strike'     => $common,
355            's'          => $common,
356            'u'          => $common,
357
358            # 15.2.2
359            'font'       => array_merge( $common, [ 'size', 'color', 'face' ] ),
360            # basefont
361
362            # 15.3
363            'hr'         => array_merge( $common, [ 'width' ] ),
364
365            # HTML Ruby annotation text module, simple ruby only.
366            # https://www.w3.org/TR/html5/text-level-semantics.html#the-ruby-element
367            'ruby'       => $common,
368            # rbc
369            'rb'         => $common,
370            'rp'         => $common,
371            'rt'         => $common, # array_merge( $common, array( 'rbspan' ) ),
372            'rtc'        => $common,
373
374            # MathML root element, where used for extensions
375            # 'title' may not be 100% valid here; it's XHTML
376            # https://www.w3.org/TR/REC-MathML/
377            'math'       => [ 'class', 'style', 'id', 'title' ],
378
379            // HTML 5 section 4.5
380            'figure'     => $common,
381            'figcaption' => $common,
382
383            # HTML 5 section 4.6
384            'bdi' => $common,
385
386            # HTML5 elements, defined by:
387            # https://html.spec.whatwg.org/multipage/semantics.html#the-data-element
388            'data' => array_merge( $common, [ 'value' ] ),
389            'time' => array_merge( $common, [ 'datetime' ] ),
390            'mark' => $common,
391
392            // meta and link are only permitted by removeHTMLtags when Microdata
393            // is enabled so we don't bother adding a conditional to hide these
394            // Also meta and link are only valid in WikiText as Microdata elements
395            // (ie: validateTag rejects tags missing the attributes needed for Microdata)
396            // So we don't bother including $common attributes that have no purpose.
397            'meta' => [ 'itemprop', 'content' ],
398            'link' => [ 'itemprop', 'href', 'title' ],
399
400            // HTML 5 section 4.3.5
401            'aside' => $common,
402        ];
403
404        return $allowed;
405    }
406
407    /**
408     * Ensure that any entities and character references are legal
409     * for XML and XHTML specifically. Any stray bits will be
410     * &amp;-escaped to result in a valid text fragment.
411     *
412     * a. named char refs can only be &lt; &gt; &amp; &quot;, others are
413     *   numericized (this way we're well-formed even without a DTD)
414     * b. any numeric char refs must be legal chars, not invalid or forbidden
415     * c. use lower cased "&#x", not "&#X"
416     * d. fix or reject non-valid attributes
417     *
418     * @param string $text
419     * @return string
420     * @internal
421     */
422    public static function normalizeCharReferences( $text ) {
423        return preg_replace_callback(
424            self::CHAR_REFS_REGEX,
425            [ self::class, 'normalizeCharReferencesCallback' ],
426            $text );
427    }
428
429    /**
430     * @param string $matches
431     * @return string
432     */
433    private static function normalizeCharReferencesCallback( $matches ) {
434        $ret = null;
435        if ( $matches[1] != '' ) {
436            $ret = self::normalizeEntity( $matches[1] );
437        } elseif ( $matches[2] != '' ) {
438            $ret = self::decCharReference( $matches[2] );
439        } elseif ( $matches[3] != '' ) {
440            $ret = self::hexCharReference( $matches[3] );
441        }
442        if ( $ret === null ) {
443            return htmlspecialchars( $matches[0] );
444        } else {
445            return $ret;
446        }
447    }
448
449    /**
450     * If the named entity is defined in HTML5
451     * return the equivalent numeric entity reference (except for the core &lt;
452     * &gt; &amp; &quot;). If the entity is a MediaWiki-specific alias, returns
453     * the HTML equivalent. Otherwise, returns HTML-escaped text of
454     * pseudo-entity source (eg &amp;foo;)
455     *
456     * @param string $name Semicolon-terminated name
457     * @return string
458     */
459    private static function normalizeEntity( $name ) {
460        if ( isset( self::MW_ENTITY_ALIASES[$name] ) ) {
461            // Non-standard MediaWiki-specific entities
462            return '&' . self::MW_ENTITY_ALIASES[$name];
463        } elseif ( in_array( $name, [ 'lt;', 'gt;', 'amp;', 'quot;' ], true ) ) {
464            // Keep these in word form
465            return "&$name";
466        } elseif ( isset( HTMLData::$namedEntityTranslations[$name] ) ) {
467            // Beware: some entities expand to more than 1 codepoint
468            return preg_replace_callback( '/./Ssu', function ( $m ) {
469                return '&#' . self::utf8ToCodepoint( $m[0] ) . ';';
470            }, HTMLData::$namedEntityTranslations[$name] );
471        } else {
472            return "&amp;$name";
473        }
474    }
475
476    /**
477     * @param string $codepoint
478     * @return null|string
479     */
480    private static function decCharReference( string $codepoint ): ?string {
481        # intval() will (safely) saturate at the maximum signed integer
482        # value if $codepoint is too many digits
483        $point = intval( $codepoint );
484        if ( self::validateCodepoint( $point ) ) {
485            return sprintf( '&#%d;', $point );
486        } else {
487            return null;
488        }
489    }
490
491    /**
492     * @param string $codepoint
493     * @return null|string
494     */
495    private static function hexCharReference( string $codepoint ): ?string {
496        # hexdec() will return a float (not an int) if $codepoint is too
497        # long, so protect against that.  The largest valid codepoint is
498        # 0x10FFFF.
499        if ( strlen( ltrim( $codepoint, '0' ) ) > 6 ) {
500            return null;
501        }
502        $point = hexdec( $codepoint );
503        if ( self::validateCodepoint( $point ) ) {
504            return sprintf( '&#x%x;', $point );
505        } else {
506            return null;
507        }
508    }
509
510    /**
511     * Returns true if a given Unicode codepoint is a valid character in
512     * both HTML5 and XML.
513     * @param int $codepoint
514     * @return bool
515     */
516    private static function validateCodepoint( int $codepoint ): bool {
517        # U+000C is valid in HTML5 but not allowed in XML.
518        # U+000D is valid in XML but not allowed in HTML5.
519        # U+007F - U+009F are disallowed in HTML5 (control characters).
520        return $codepoint == 0x09
521            || $codepoint == 0x0a
522            || ( $codepoint >= 0x20 && $codepoint <= 0x7e )
523            || ( $codepoint >= 0xa0 && $codepoint <= 0xd7ff )
524            || ( $codepoint >= 0xe000 && $codepoint <= 0xfffd )
525            || ( $codepoint >= 0x10000 && $codepoint <= 0x10ffff );
526    }
527
528    /**
529     * Returns a string from the provided code point.
530     *
531     * @param int $cp
532     * @return string
533     */
534    private static function codepointToUtf8( int $cp ) {
535        $chr = mb_chr( $cp, 'UTF-8' );
536        Assert::invariant( $chr !== false, "Getting char failed!" );
537        return $chr;
538    }
539
540    /**
541     * Returns the code point at the first position of the string.
542     *
543     * @param string $str
544     * @return int
545     */
546    private static function utf8ToCodepoint( string $str ) {
547        $ord = mb_ord( $str );
548        Assert::invariant( $ord !== false, "Getting code point failed!" );
549        return $ord;
550    }
551
552    /**
553     * @param string $host
554     * @return string
555     */
556    private static function stripIDNs( string $host ) {
557        // This code is part of Sanitizer::cleanUrl in core
558        return preg_replace( self::IDN_RE_G, '', $host );
559    }
560
561    /**
562     * @param SiteConfig $siteConfig
563     * @param string $href
564     * @param string $mode
565     * @return string|null
566     */
567    public static function cleanUrl( SiteConfig $siteConfig, string $href, string $mode ): ?string {
568        if ( $mode !== 'wikilink' ) {
569            $href = preg_replace_callback(
570                '/([\][<>"\x00-\x20\x7F\|])/', static function ( $matches ) {
571                    return urlencode( $matches[0] );
572                }, $href
573            );
574        }
575
576        $matched = preg_match( '#^((?:[a-zA-Z][^:/]*:)?(?://)?)([^/]+)(/?.*)#', $href, $bits );
577        if ( $matched === 1 ) {
578            $proto = $bits[1];
579            if ( $proto && !$siteConfig->hasValidProtocol( $proto ) ) {
580                // invalid proto, disallow URL
581                return null;
582            }
583            $host = self::stripIDNs( $bits[2] );
584            preg_match( '/^%5B([0-9A-Fa-f:.]+)%5D((:\d+)?)$/D', $host, $match );
585            if ( $match ) {
586                // IPv6 host names
587                $host = '[' . $match[1] . ']' . $match[2];
588            }
589            $path = $bits[3];
590        } else {
591            $proto = '';
592            $host = '';
593            $path = $href;
594        }
595        return $proto . $host . $path;
596    }
597
598    /**
599     * If the named entity is defined in HTML5
600     * return the UTF-8 encoding of that character. Otherwise, returns
601     * pseudo-entity source (eg "&foo;")
602     *
603     * @param string $name Semicolon-terminated entity name
604     * @return string
605     */
606    private static function decodeEntity( $name ) {
607        // These are MediaWiki-specific entities, not in the HTML standard
608        if ( isset( self::MW_ENTITY_ALIASES[$name] ) ) {
609            $name = self::MW_ENTITY_ALIASES[$name];
610        }
611        $trans = HTMLData::$namedEntityTranslations[$name] ?? null;
612        return $trans ?? "&$name";
613    }
614
615    /**
616     * Return UTF-8 string for a codepoint if that is a valid
617     * character reference, otherwise U+FFFD REPLACEMENT CHARACTER.
618     * @param int $codepoint
619     * @return string
620     */
621    private static function decodeChar( int $codepoint ): string {
622        if ( self::validateCodepoint( $codepoint ) ) {
623            return self::codepointToUtf8( $codepoint );
624        } else {
625            return self::UTF8_REPLACEMENT;
626        }
627    }
628
629    /**
630     * Decode any character references, numeric or named entities,
631     * in the text and return a UTF-8 string.
632     * @param string $text
633     * @return string
634     */
635    public static function decodeCharReferences( string $text ): string {
636        return preg_replace_callback(
637            self::CHAR_REFS_REGEX,
638            function ( $matches ) {
639                if ( $matches[1] !== '' ) {
640                    return self::decodeEntity( $matches[1] );
641                } elseif ( $matches[2] !== '' ) {
642                    return self::decodeChar( intval( $matches[2] ) );
643                } elseif ( $matches[3] !== '' ) {
644                    # hexdec will return a float if the string is too long (!) so
645                    # check the length of the string first.
646                    if ( strlen( ltrim( $matches[3], '0' ) ) > 6 ) {
647                        // Invalid character reference.
648                        return self::UTF8_REPLACEMENT;
649                    }
650                    return self::decodeChar( hexdec( $matches[3] ) );
651                }
652                # Last case should be an ampersand by itself
653                return $matches[4];
654            },
655            $text
656        );
657    }
658
659    /**
660     * Normalize CSS into a format we can easily search for hostile input
661     *  - decode character references
662     *  - decode escape sequences
663     *  - convert characters that IE6 interprets into ascii
664     *  - remove comments, unless the entire value is one single comment
665     * @param string $value the css string
666     * @return string normalized css
667     */
668    public static function normalizeCss( string $value ): string {
669        // Decode character references like &#123;
670        $value = self::decodeCharReferences( $value );
671
672        // Decode escape sequences and line continuation
673        // See the grammar in the CSS 2 spec, appendix D.
674        // This has to be done AFTER decoding character references.
675        // This means it isn't possible for this function to return
676        // unsanitized escape sequences. It is possible to manufacture
677        // input that contains character references that decode to
678        // escape sequences that decode to character references, but
679        // it's OK for the return value to contain character references
680        // because the caller is supposed to escape those anyway.
681        static $decodeRegex;
682        if ( !$decodeRegex ) {
683            $space = '[\\x20\\t\\r\\n\\f]';
684            $nl = '(?:\\n|\\r\\n|\\r|\\f)';
685            $backslash = '\\\\';
686            $decodeRegex = "$backslash
687                (?:
688                    ($nl) |  # 1. Line continuation
689                    ([0-9A-Fa-f]{1,6})$space? |  # 2. character number
690                    (.) | # 3. backslash cancelling special meaning
691                    () | # 4. backslash at end of string
692                )/xu";
693        }
694        $value = preg_replace_callback( $decodeRegex,
695            [ self::class, 'cssDecodeCallback' ], $value );
696
697        // Let the value through if it's nothing but a single comment, to
698        // allow other functions which may reject it to pass some error
699        // message through.
700        if ( !preg_match( '! ^ \s* /\* [^*\\/]* \*/ \s* $ !xD', $value ) ) {
701            // Remove any comments; IE gets token splitting wrong
702            // This must be done AFTER decoding character references and
703            // escape sequences, because those steps can introduce comments
704            // This step cannot introduce character references or escape
705            // sequences, because it replaces comments with spaces rather
706            // than removing them completely.
707            $value = self::delimiterReplace( '/*', '*/', ' ', $value );
708
709            // Remove anything after a comment-start token, to guard against
710            // incorrect client implementations.
711            $commentPos = strpos( $value, '/*' );
712            if ( $commentPos !== false ) {
713                $value = substr( $value, 0, $commentPos );
714            }
715        }
716
717        return $value;
718    }
719
720    // PORT_FIXME - The delimiterReplace code below is from StringUtils in core
721
722    /**
723     * Perform an operation equivalent to `preg_replace_callback()`
724     *
725     * Matches this code:
726     *
727     *     preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject );
728     *
729     * If the start delimiter ends with an initial substring of the end delimiter,
730     * e.g. in the case of C-style comments, the behavior differs from the model
731     * regex. In this implementation, the end must share no characters with the
732     * start, so e.g. `/*\/` is not considered to be both the start and end of a
733     * comment. `/*\/xy/*\/` is considered to be a single comment with contents `/xy/`.
734     *
735     * The implementation of delimiterReplaceCallback() is slower than hungryDelimiterReplace()
736     * but uses far less memory. The delimiters are literal strings, not regular expressions.
737     *
738     * @param string $startDelim Start delimiter
739     * @param string $endDelim End delimiter
740     * @param callable $callback Function to call on each match
741     * @param string $subject
742     * @param string $flags Regular expression flags
743     * @throws InvalidArgumentException
744     * @return string
745     */
746    private static function delimiterReplaceCallback(
747        string $startDelim, string $endDelim, callable $callback, string $subject, string $flags = ''
748    ): string {
749        $inputPos = 0;
750        $outputPos = 0;
751        $contentPos = 0;
752        $output = '';
753        $foundStart = false;
754        $encStart = preg_quote( $startDelim, '!' );
755        $encEnd = preg_quote( $endDelim, '!' );
756        $strcmp = strpos( $flags, 'i' ) === false ? 'strcmp' : 'strcasecmp';
757        $endLength = strlen( $endDelim );
758        $m = [];
759        while ( $inputPos < strlen( $subject ) &&
760            preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE, $inputPos )
761        ) {
762            $tokenOffset = $m[0][1];
763            if ( $m[1][0] !== '' ) {
764                if ( $foundStart &&
765                    $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) === 0
766                ) {
767                    # An end match is present at the same location
768                    $tokenType = 'end';
769                    $tokenLength = $endLength;
770                } else {
771                    $tokenType = 'start';
772                    $tokenLength = strlen( $m[0][0] );
773                }
774            } elseif ( $m[2][0] !== '' ) {
775                $tokenType = 'end';
776                $tokenLength = strlen( $m[0][0] );
777            } else {
778                throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__ );
779            }
780            if ( $tokenType === 'start' ) {
781                # Only move the start position if we haven't already found a start
782                # This means that START START END matches outer pair
783                if ( !$foundStart ) {
784                    # Found start
785                    $inputPos = $tokenOffset + $tokenLength;
786                    # Write out the non-matching section
787                    $output .= substr( $subject, $outputPos, $tokenOffset - $outputPos );
788                    $outputPos = $tokenOffset;
789                    $contentPos = $inputPos;
790                    $foundStart = true;
791                } else {
792                    # Move the input position past the *first character* of START,
793                    # to protect against missing END when it overlaps with START
794                    $inputPos = $tokenOffset + 1;
795                }
796            } elseif ( $tokenType === 'end' ) {
797                if ( $foundStart ) {
798                    # Found match
799                    $output .= $callback( [
800                        substr( $subject, $outputPos, $tokenOffset + $tokenLength - $outputPos ),
801                        substr( $subject, $contentPos, $tokenOffset - $contentPos )
802                    ] );
803                    $foundStart = false;
804                } else {
805                    # Non-matching end, write it out
806                    $output .= substr( $subject, $inputPos, $tokenOffset + $tokenLength - $outputPos );
807                }
808                $inputPos = $outputPos = $tokenOffset + $tokenLength;
809            } else {
810                throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__ );
811            }
812        }
813        if ( $outputPos < strlen( $subject ) ) {
814            $output .= substr( $subject, $outputPos );
815        }
816        return $output;
817    }
818
819    /**
820     * Perform an operation equivalent to `preg_replace()` with flags.
821     *
822     * Matches this code:
823     *
824     *     preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject );
825     *
826     * @param string $startDelim Start delimiter regular expression
827     * @param string $endDelim End delimiter regular expression
828     * @param string $replace Replacement string. May contain $1, which will be
829     *  replaced by the text between the delimiters
830     * @param string $subject String to search
831     * @param string $flags Regular expression flags
832     * @return string The string with the matches replaced
833     */
834    private static function delimiterReplace(
835        string $startDelim, string $endDelim, string $replace, string $subject, string $flags = ''
836    ): string {
837        return self::delimiterReplaceCallback(
838            $startDelim, $endDelim,
839            static function ( array $matches ) use ( $replace ) {
840                return strtr( $replace, [ '$0' => $matches[0], '$1' => $matches[1] ] );
841            },
842            $subject, $flags
843        );
844    }
845
846    /**
847     * SSS FIXME: There is a test in mediawiki.environment.js that doles out
848     * and tests about ids. There are probably some tests in Util.php as well.
849     * We should move all these kind of tests somewhere else.
850     * @param string $k
851     * @param string $v
852     * @param KV[] $attrs
853     * @return bool
854     */
855    private static function isParsoidAttr( string $k, string $v, array $attrs ): bool {
856        // NOTES:
857        // 1. Currently the tokenizer unconditionally escapes typeof and about
858        // attributes from wikitxt to data-x-typeof and data-x-about. So,
859        // this check will only pass through Parsoid inserted attrs.
860        // 2. But, if we fix the over-aggressive escaping in the tokenizer to
861        // not escape non-Parsoid typeof and about, then this will return
862        // true for something like typeof='mw:Foo evilScriptHere'. But, that
863        // is safe since this check is only used to see if we should
864        // unconditionally discard the entire attribute or process it further.
865        // That further processing will catch and discard any dangerous
866        // strings in the rest of the attribute
867        return ( in_array( $k, [ 'typeof', 'property', 'rel' ], true )
868                && preg_match( '/(?:^|\s)mw:.+?(?=$|\s)/D', $v ) )
869            || ( $k === 'about' && preg_match( '/^#mwt\d+$/D', $v ) )
870            || ( $k === 'content'
871                && preg_match( '/(?:^|\s)mw:.+?(?=$|\s)/D', KV::lookup( $attrs, 'property' ) ?? '' ) );
872    }
873
874    /**
875     * Given an attribute name, checks whether it is a reserved data attribute
876     * (such as data-mw-foo) which is unavailable to user-generated HTML so MediaWiki
877     * core and extension code can safely use it to communicate with frontend code.
878     * @param string $attr Attribute name.
879     * @return bool
880     */
881    public static function isReservedDataAttribute( string $attr ): bool {
882        // data-ooui is reserved for ooui.
883        // data-mw and data-parsoid are reserved for parsoid.
884        // data-mw-<name here> is reserved for extensions (or core) if
885        // they need to communicate some data to the client and want to be
886        // sure that it isn't coming from an untrusted user.
887        // We ignore the possibility of namespaces since user-generated HTML
888        // can't use them anymore.
889        if ( preg_match( '/^data-(mw|parsoid)/', $attr ) ) {
890            return false; // PARSOID SPECIFIC
891        }
892        return (bool)preg_match( '/^data-(ooui|mw|parsoid)/i', $attr );
893    }
894
895    /**
896     * @param SiteConfig $siteConfig
897     * @param ?string $tagName
898     * @param ?Token $token
899     * @param array $attrs
900     * @return array
901     */
902    public static function sanitizeTagAttrs(
903        SiteConfig $siteConfig, ?string $tagName, ?Token $token, array $attrs
904    ): array {
905        $tag = $tagName ?: $token->getName();
906
907        $list = self::attributesAllowedInternal( $tag );
908        $newAttrs = [];
909        $n = count( $attrs );
910        for ( $i = 0;  $i < $n;  $i++ ) {
911            $a = $attrs[$i];
912            if ( !isset( $a->v ) ) {
913                $a->v = '';
914            }
915
916            // Convert attributes to string, if necessary.
917            $a->k = TokenUtils::tokensToString( $a->k );
918
919            if ( is_array( $a->v ) ) {
920                // Use the expanded attr instead of trying to unpackDOMFragments
921                // since the fragment will have been released when expanding to DOM
922                $expandedVal = $token ? $token->fetchExpandedAttrValue( $a->k ) : null;
923                if ( $expandedVal === null ) {
924                    $a->v = TokenUtils::tokensToString( $a->v );
925                } else {
926                    // See the comment in TokenUtils::tokensToString about
927                    // unpackDOMFragments for why we're just using the textContent
928                    $dom = DOMUtils::parseHTML( $expandedVal );
929                    $a->v = DOMCompat::getBody( $dom )->textContent;
930                }
931            }
932
933            $origK = $a->ksrc ?? $a->k;
934            // $a->k can be uppercase
935            $k = mb_strtolower( $a->k );
936            $v = $a->v;
937            $origV = $a->vsrc ?? $v;
938            $psdAttr = self::isParsoidAttr( $k, $v, $attrs );
939
940            // Bypass RDFa/allowed attribute checks for Parsoid-inserted attrs
941            // Safe to do since the tokenizer renames about/typeof attrs.
942            // unconditionally. FIXME: The escaping solution in the tokenizer
943            // may be aggressive. There is no need to escape typeof strings
944            // that or about ids that don't resemble Parsoid tokens/about ids.
945            if ( !$psdAttr ) {
946                if ( !preg_match( self::GET_ATTRIBS_RE, $k ) ) {
947                    $newAttrs[$k] = [ null, $origV, $origK ];
948                    continue;
949                }
950
951                # Allow XML namespace declaration to allow RDFa
952                if ( preg_match( self::XMLNS_ATTRIBUTE_PATTERN, $k ) ) {
953                    if ( !preg_match( self::EVIL_URI_PATTERN, $v ) ) {
954                        $newAttrs[$k] = [ $v, $origV, $origK ];
955                    } else {
956                        $newAttrs[$k] = [ null, $origV, $origK ];
957                    }
958                    continue;
959                }
960
961                # Allow any attribute beginning with "data-"
962                # However:
963                # * Disallow data attributes used by MediaWiki code
964                # * Ensure that the attribute is not namespaced by banning
965                #   colons.
966                if ( ( !preg_match( '/^data-[^:]*$/iD', $k ) && !isset( $list[$k] ) )
967                     || self::isReservedDataAttribute( $k )
968                ) {
969                    $newAttrs[$k] = [ null, $origV, $origK ];
970                    continue;
971                }
972            }
973
974            # Strip javascript "expression" from stylesheets.
975            # http://msdn.microsoft.com/workshop/author/dhtml/overview/recalc.asp
976            if ( $k === 'style' ) {
977                $v = self::checkCss( $v );
978            }
979
980            # Escape HTML id attributes
981            if ( $k === 'id' ) {
982                $v = self::escapeIdForAttribute( $v, self::ID_PRIMARY );
983            }
984
985            # Escape HTML id reference lists
986            if ( $k === 'aria-describedby'
987                || $k === 'aria-flowto'
988                || $k === 'aria-labelledby'
989                || $k === 'aria-owns'
990            ) {
991                $v = self::escapeIdReferenceList( $v );
992            }
993
994            // RDFa and microdata properties allow URLs, URIs and/or CURIs.
995            // Check them for validity.
996            if ( $k === 'rel' || $k === 'rev'
997                # RDFa
998                || $k === 'about' || $k === 'property'
999                || $k === 'resource' || $k === 'datatype'
1000                || $k === 'typeof'
1001                # HTML5 microdata
1002                || $k === 'itemid' || $k === 'itemprop'
1003                || $k === 'itemref' || $k === 'itemscope'
1004                || $k === 'itemtype'
1005            ) {
1006                // Paranoia. Allow "simple" values but suppress javascript
1007                if ( preg_match( self::EVIL_URI_PATTERN, $v ) ) {
1008                    // Retain the Parsoid typeofs for Parsoid attrs
1009                    $newV = $psdAttr ? trim( preg_replace( '/(?:^|\s)(?!mw:\w)[^\s]*/', '', $origV ) ) : null;
1010                    $newAttrs[$k] = [ $newV, $origV, $origK ];
1011                    continue;
1012                }
1013            }
1014
1015            # NOTE: even though elements using href/src are not allowed directly, supply
1016            #       validation code that can be used by tag hook handlers, etc
1017            if ( $token && ( $k === 'href' || $k === 'src' || $k === 'poster' ) ) { // T163583
1018                // `origV` will always be `v`, because `a.vsrc` isn't set, since
1019                // this attribute didn't come from source.  However, in the
1020                // LinkHandler, we may have already shadowed this value so use
1021                // that instead.
1022                $rel = $token->getAttributeShadowInfo( 'rel' );
1023                $mode = ( $k === 'href' &&
1024                    isset( $rel['value'] ) &&
1025                    preg_match( '#^mw:WikiLink(/Interwiki)?$#', $rel['value'] )
1026                ) ? 'wikilink' : 'external';
1027                $origHref = $token->getAttributeShadowInfo( $k )['value'];
1028                $newHref = self::cleanUrl( $siteConfig, $v, $mode );
1029                if ( $newHref !== $v ) {
1030                    $newAttrs[$k] = [ $newHref, $origHref, $origK ];
1031                    continue;
1032                }
1033            }
1034
1035            if ( $k === 'tabindex' && $v !== '0' ) {
1036                // Only allow tabindex of 0, which is useful for accessibility.
1037                continue;
1038            }
1039
1040            // SSS FIXME: This logic is not RT-friendly.
1041            // If this attribute was previously set, override it.
1042            // Output should only have one attribute of each name.
1043            $newAttrs[$k] = [ $v, $origV, $origK ];
1044        }
1045
1046        # itemtype, itemid, itemref don't make sense without itemscope
1047        if ( !array_key_exists( 'itemscope', $newAttrs ) ) {
1048            // SSS FIXME: This logic is not RT-friendly.
1049            unset( $newAttrs['itemtype'] );
1050            unset( $newAttrs['itemid'] );
1051            unset( $newAttrs['itemref'] );
1052        }
1053        # TODO: Strip itemprop if we aren't descendants of an itemscope or pointed to by an itemref.
1054
1055        return $newAttrs;
1056    }
1057
1058    /**
1059     * Sanitize and apply attributes to a wrapper element.
1060     *
1061     * Used primarily when we're applying tokenized attributes directly to
1062     * dom elements, which wouldn't have had a chance to be sanitized before
1063     * tree building.
1064     * @param SiteConfig $siteConfig
1065     * @param Element $wrapper wrapper
1066     * @param array $attrs attributes
1067     */
1068    public static function applySanitizedArgs(
1069        SiteConfig $siteConfig, Element $wrapper, array $attrs
1070    ): void {
1071        $nodeName = DOMCompat::nodeName( $wrapper );
1072        $sanitizedAttrs = self::sanitizeTagAttrs( $siteConfig, $nodeName, null, $attrs );
1073        foreach ( $sanitizedAttrs as $k => $v ) {
1074            if ( isset( $v[0] ) ) {
1075                $wrapper->setAttribute( $k, $v[0] );
1076            }
1077        }
1078    }
1079
1080    /**
1081     * @param string $text
1082     * @return string
1083     */
1084    public static function checkCss( string $text ): string {
1085        $text = self::normalizeCss( $text );
1086        // \000-\010\013\016-\037\177 are the octal escape sequences
1087        if ( preg_match( '/[\000-\010\013\016-\037\177]/', $text )
1088            || strpos( $text, self::UTF8_REPLACEMENT ) !== false
1089        ) {
1090            return '/* invalid control char */';
1091        } elseif ( preg_match( self::INSECURE_RE, $text ) ) {
1092            return '/* insecure input */';
1093        } else {
1094            return $text;
1095        }
1096    }
1097
1098    /**
1099     * @param array $matches
1100     * @return string
1101     */
1102    public static function cssDecodeCallback( $matches ) {
1103        if ( $matches[1] !== '' ) {
1104            // Line continuation
1105            return '';
1106        } elseif ( $matches[2] !== '' ) {
1107            # hexdec could return a float if the match is too long, but the
1108            # regexp in question limits the string length to 6.
1109            $char = self::codepointToUtf8( hexdec( $matches[2] ) );
1110        } elseif ( $matches[3] !== '' ) {
1111            $char = $matches[3];
1112        } else {
1113            $char = '\\';
1114        }
1115        if ( $char == "\n" || $char == '"' || $char == "'" || $char == '\\' ) {
1116            // These characters need to be escaped in strings
1117            // Clean up the escape sequence to avoid parsing errors by clients
1118            return '\\' . dechex( ord( $char ) ) . ' ';
1119        } else {
1120            // Decode unnecessary escape
1121            return $char;
1122        }
1123    }
1124
1125    /**
1126     * Sanitize a title to be used in a URI?
1127     * @param string $title
1128     * @param bool $isInterwiki
1129     * @return string
1130     */
1131    public static function sanitizeTitleURI( string $title, bool $isInterwiki = false ): string {
1132        $idx = strpos( $title, '#' );
1133        $anchor = null;
1134        if ( $idx !== false ) { // split at first '#'
1135            $anchor = substr( $title, $idx + 1 );
1136            $title = substr( $title, 0, $idx );
1137        }
1138        $title = preg_replace_callback(
1139            '/[%? \[\]#|<>]/', static function ( $matches ) {
1140                return PHPUtils::encodeURIComponent( $matches[0] );
1141            }, $title );
1142        if ( $anchor !== null ) {
1143            $title .= '#' . ( $isInterwiki
1144                    ? self::escapeIdForExternalInterwiki( $anchor )
1145                    : self::escapeIdForLink( $anchor ) );
1146        }
1147        return $title;
1148    }
1149
1150    public const FIXTAGS = [
1151        # French spaces, last one Guillemet-left
1152        # only if it isn't followed by a word character.
1153        '/ (?=[?:;!%»›](?!\w))/u' => "%s",
1154        # French spaces, Guillemet-right
1155        '/([«‹]) /u' => "\\1%s",
1156    ];
1157
1158    /**
1159     * Armor French spaces with a replacement character
1160     *
1161     * @since 1.32
1162     * @param string $text Text to armor
1163     * @param string $space Space character for the French spaces, defaults to '&#160;'
1164     * @return string Armored text
1165     */
1166    public static function armorFrenchSpaces( $text, $space = '&#160;' ) {
1167        // Replace $ with \$ and \ with \\
1168        $space = preg_replace( '#(?<!\\\\)(\\$|\\\\)#', '\\\\$1', $space );
1169        return preg_replace(
1170            array_keys( self::FIXTAGS ),
1171            array_map( static function ( string $replacement ) use ( $space ) {
1172                // @phan-suppress-next-line PhanPluginPrintfVariableFormatString
1173                return sprintf( $replacement, $space );
1174            }, array_values( self::FIXTAGS ) ),
1175            $text
1176        );
1177    }
1178
1179    /**
1180     * Given a section name or other user-generated or otherwise unsafe string, escapes it to be
1181     * a valid HTML id attribute.
1182     *
1183     * WARNING: unlike escapeId(), the output of this function is not guaranteed to be HTML safe,
1184     * be sure to use proper escaping.
1185     *
1186     * In Parsoid, proper escaping is usually handled for us by the HTML
1187     * serialization algorithm, but be careful of corner cases (such as
1188     * emitting attributes in wikitext).
1189     *
1190     * @param string $id String to escape
1191     * @param int $mode One of ID_* constants, specifying whether the primary or fallback encoding
1192     *     should be used.
1193     * @return string Escaped ID
1194     *
1195     * @since 1.30
1196     */
1197    public static function escapeIdForAttribute( string $id, $mode = self::ID_PRIMARY ): string {
1198        // For consistency with PHP's API, we accept "primary" or "fallback" as
1199        // the mode in 'options'.  This (slightly) abstracts the actual details
1200        // of the id encoding from the Parsoid code which handles ids; we could
1201        // swap primary and fallback here, or even transition to a new HTML6
1202        // encoding (!), without touching all the call sites.
1203        $internalMode = $mode === self::ID_FALLBACK ? 'legacy' : 'html5';
1204        return self::escapeIdInternal( $id, $internalMode );
1205    }
1206
1207    /**
1208     * Given a section name or other user-generated or otherwise unsafe string, escapes it to be
1209     * a valid URL fragment.
1210     *
1211     * WARNING: unlike escapeId(), the output of this function is not guaranteed to be HTML safe,
1212     * be sure to use proper escaping.
1213     *
1214     * @param string $id String to escape
1215     * @return string Escaped ID
1216     *
1217     * @since 1.30
1218     */
1219    public static function escapeIdForLink( string $id ): string {
1220        return self::escapeIdInternalUrl( $id, 'html5' );
1221    }
1222
1223    /**
1224     * Given a section name or other user-generated or otherwise unsafe string, escapes it to be
1225     * a valid URL fragment for external interwikis.
1226     *
1227     * @param string $id String to escape
1228     * @return string Escaped ID
1229     *
1230     * @since 1.30
1231     */
1232    private static function escapeIdForExternalInterwiki( string $id ): string {
1233        // Assume $wgExternalInterwikiFragmentMode = 'legacy'
1234        return self::escapeIdInternalUrl( $id, 'legacy' );
1235    }
1236
1237    /**
1238     * Do percent encoding of percent signs for href (but not id) attributes
1239     *
1240     * @see https://phabricator.wikimedia.org/T238385
1241     * @param string $id String to escape
1242     * @param string $mode One of modes from $wgFragmentMode
1243     * @return string
1244     */
1245    private static function escapeIdInternalUrl( $id, $mode ) {
1246        $id = self::escapeIdInternal( $id, $mode );
1247        if ( $mode === 'html5' ) {
1248            $id = preg_replace( '/%([a-fA-F0-9]{2})/', '%25$1', $id );
1249        }
1250        return $id;
1251    }
1252
1253    /**
1254     * Helper for escapeIdFor*() functions. Performs most of the actual escaping.
1255     *
1256     * @param string $id String to escape
1257     * @param string $mode One of modes from $wgFragmentMode ('html5' or 'legacy')
1258     * @return string
1259     */
1260    private static function escapeIdInternal( string $id, string $mode ): string {
1261        switch ( $mode ) {
1262            case 'html5':
1263                // html5 spec says ids must not have any of the following:
1264                // U+0009 TAB, U+000A LF, U+000C FF, U+000D CR, or U+0020 SPACE
1265                // In practice, in wikitext, only tab, LF, CR (and SPACE) are
1266                // possible using either Lua or html entities.
1267                $id = str_replace( [ "\t", "\n", "\f", "\r", " " ], '_', $id );
1268                break;
1269
1270            case 'legacy':
1271                // This corresponds to 'noninitial' mode of the old escapeId
1272                static $replace = [
1273                    '%3A' => ':',
1274                    '%' => '.'
1275                ];
1276
1277                $id = urlencode( str_replace( ' ', '_', $id ) );
1278                $id = strtr( $id, $replace );
1279                break;
1280
1281            default:
1282                throw new InvalidArgumentException( "Invalid mode '$mode' passed to '" . __METHOD__ );
1283        }
1284
1285        return $id;
1286    }
1287
1288    /**
1289     * Given a string containing a space delimited list of ids, escape each id
1290     * to match ids escaped by the escapeIdForAttribute() function.
1291     *
1292     * @since 1.27
1293     *
1294     * @param string $referenceString Space delimited list of ids
1295     * @return string
1296     */
1297    public static function escapeIdReferenceList( string $referenceString ): string {
1298        # Explode the space delimited list string into an array of tokens
1299        $references = preg_split( '/\s+/', "{$referenceString}", -1, PREG_SPLIT_NO_EMPTY );
1300
1301        # Escape each token as an id
1302        foreach ( $references as &$ref ) {
1303            $ref = self::escapeIdForAttribute( $ref );
1304        }
1305
1306        # Merge the array back to a space delimited list string
1307        # If the array is empty, the result will be an empty string ('')
1308        $referenceString = implode( ' ', $references );
1309
1310        return $referenceString;
1311    }
1312
1313    /**
1314     * Normalizes whitespace in a section name, such as might be returned
1315     * by Parser::stripSectionName(), for use in the ids that are used for
1316     * section links.
1317     *
1318     * @param string $section
1319     * @return string
1320     */
1321    public static function normalizeSectionNameWhiteSpace( string $section ): string {
1322        return trim( preg_replace( '/[ _]+/', ' ', $section ) );
1323    }
1324}