Fix safeLinkHref scheme check running before entity decoding

[jonathanKingston]

Summary

safeLinkHref validated the link destination's scheme before HTML character references were decoded, so an entity-encoded dangerous scheme slipped past the check and only decoded to a live URL afterwards (during encodeHrefForOutput).

The javascript|data|vbscript denylist tested the raw string; encodeHrefForOutput then called decodeHTMLStrict. So javascript:alert(1) passed the check and decoded to a working javascript: URL in the emitted href.

• Reproduced: renderMarkdown('[click][r]\n\n[r]: javascript:alert(1)') → <a href="javascript:alert(1)"> (also data: via data:…, and the double-encoded j…).
• The inline [x](dest) path was safe only by accident (entities are pre-decoded to inert PUA before safeLinkHref runs). The reference-definition path — whose destination is stored raw — was exploitable.
• autolinkHref has the same shape but is not vulnerable: the autolink grammar requires a literal scheme: (letters + literal colon), so entities can't disguise the scheme there. Left unchanged.

Fix

• Decode before validating. safeLinkHref now fully resolves the href (undo source HTML-escaping → decode PUA punctuation → decode HTML character references), then validates, then percent-encodes the already-decoded string directly — no second decode pass that could re-hide a scheme behind double-encoded entities.
• Split percentEncodeHref out of encodeHrefForOutput so validation and encoding share one decode.
• Allowlist instead of denylist. Scheme-less destinations (relative paths, fragments, queries) are always allowed; a scheme is permitted only if it's in the allowlist, so unknown/future dangerous schemes fail closed.
• A control-char bypass (java	script:) is neutralized too — the percent-encoder turns the tab into %09, breaking the scheme.

Configurable allowlist

• DEFAULT_SAFE_HREF_SCHEMES — http, https, mailto, tel, sms, ftp, ftps.
• setSafeHrefSchemes(schemes | null) — override the active set (case-insensitive) or restore the default; mirrors the existing setLinkDecorator injection pattern.
• getSafeHrefSchemes() — read the active set.

Relative destinations stay allowed regardless of the set, and resolution still decodes entities before the scheme check, so a custom allowlist can't be bypassed with entity-encoded schemes. Documented in the README (narrowing is always safe; widening must avoid script-executing schemes).

Tests

• npm run typecheck clean; 435/435 tests pass, including the CommonMark conformance baseline (unchanged — the spec's non-http schemes are all autolinks).
• Added regression tests: entity-encoded, double-encoded, dangerous, unknown, and control-char schemes; the reference-definition end-to-end path; and the setSafeHrefSchemes narrow/restore, case-insensitivity, and no-bypass-on-widen behavior.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B88dLwh4TdWDbsDwuqxQUs

---

Generated by Claude Code