How to Prevent XSS Vulnerabilities Using Client-side HTML Entity Encoding

Your encoder is not the hard part. The hard part is the two functions that sit next to it and quietly corrupt your data.

Everyone writes an HTML entity encoder in an afternoon. Five characters, five replace calls, done. I did it too. Then I spent a week debugging why a code sample on my own site rendered as a real, live tag instead of showing the source, and the bug was not in the encoder at all. It was in the decode direction, and in a list of entities that my encoder supposedly supported but actually did not.

This is a walk through what client-side HTML entity encoding really requires if you want it to be correct, using the exact behaviors a production encoder needs to get right. Two of them are the ones almost every hand-rolled version gets wrong.

Start with the minimum character set, and understand why five is the floor

The five characters that must be encoded to stop XSS are the classic set: less-than, greater-than, ampersand, double quote, and single quote. Encoding those five alone is enough to break out of any HTML tag or attribute an attacker tries to inject, which is why every security checklist stops there.

But "minimum" and "sufficient for a code-sharing tool" are different bars. If you are building anything that displays source code — a snippet box, a developer blog, a teaching tool — you have a second job: the encoded output has to actually round-trip. A user pastes <div class="box"> and you must be able to show it back to them exactly. That means your entity table has to know the difference between characters that have a named entity and characters that only have a numeric one.

// The four named entities everyone writes:
38: '&'   // &
60: '&lt;'    // <
62: '&gt;'    // >
34: '&quot;'  // "

// And the one that has no named form:
39: '&#39;'    // single quote

Single quote is the trap. There is no ' in the HTML4 named entity set, so a correct encoder emits the numeric form ' and never invents a name for it. If your table maps single quote to something like ' and your decoder trusts that name, the round trip breaks on the first apostrophe in any line of text.

Why your decode must strip exactly one layer, not all of them

Here is the bug that cost me the week, and it is subtle enough that most encoders ship with it. Encoding is idempotent-ish: you escape once, you are safe. Decoding is the dangerous direction, because a decoder that loops until the output stops changing will happily double-decode data it should have left alone.

Consider the string A. A single pass of correct decoding turns only the first entity, &, into an ampersand, giving A. That is the right answer: one encoded character in, one decoded character out, and the rest is left as literal text for the next layer to see. That is exactly what stops a stored double-encoded payload from becoming live in a decoder.

A naive chained decoder — hex pass, then decimal pass, then named pass, each overwriting the last — takes the same input and produces a capital A. It decoded & to &, which immediately glued itself to the following #65; and formed a fresh entity that the very next pass decoded. Two rounds of decoding from one call. A single-pass decoder with one combined regular expression is not a micro-optimization, it is the security property.

The hex you emit has to be uppercase, and it has to round-trip

When a character has no named entity, you emit a numeric one, and you have two bases to choose from:

if (style === 'dec') return '&#' + cp + ';';              // decimal: A
return '&#x' + cp.toString(16).toUpperCase() + ';';     // hex: A

The hex form uses uppercase digits, so the letter A is A, not a. This is not a cosmetic choice. Hex entities are case-insensitive on the digit side for A through F, but code that compares or displays its own output needs one canonical spelling, and uppercase is the convention the major encoders settled on. Decode is different: it must accept both cases, because browsers and other tools emit lowercase hex. Encode in one canonical case, decode in both.

Auto-direction detection will bite the moment your input mixes text and entities

A convenient feature is a direction detector that looks at the input and decides "this is already encoded, so decode it" versus "this is raw, so encode it." The heuristic: count special characters versus entity-looking sequences, and go with whichever is more prevalent.

That heuristic is fine until the input is genuinely mixed. Paste a sentence that contains one real < and one literal < and the detector has to pick a direction for the whole string, so it will be wrong for half the input. The fix is not a cleverer detector, it is a manual escape hatch. Give the user an explicit "encode" and "decode" control, and let auto be a convenience default they can override in one click. Any tool that only offers auto-direction will eventually mangle a real payload, and the user will blame the tool, not the heuristic.

The encoder is five lines. These four rules are the whole job

1. Encode the five critical characters, and map single quote to the numeric '. Never invent a named entity for it.
2. Decode in a single pass with one combined regex. Chaining passes lets a double-encoded payload become live again.
3. Emit uppercase hex, accept both cases on decode. One canonical output spelling, tolerant input.
4. Expose a manual encode / decode switch. Auto-detection is a default, not the only mode.

None of these are about the five-character escape itself, and that is the point. The escape everyone writes is already correct. What separates an encoder that survives contact with real developer input from one that embeds live tags into your own page is the decode discipline and the entity table around it. Get those four rules right and the five-liner stays a five-liner.