Backoffice: Add localize.htmlString() helper to prevent XSS in HTML-rendered translations

[iOvergaard]

Summary

Adds a new htmlString() method on UmbLocalizationController that escapes interpolated args and wraps the result in a Lit unsafeHTML directive — the safe drop-in for the manual unsafeHTML(this.localize.string(...)) pattern. Converts all direct call sites across the codebase, including a previously-unfixed XSS in trash.action.ts. Adds an ESLint rule so this regression class is caught at lint time going forward.

Also pulls in two sanitizeHTML defenses from @liamlaverty's #22425 (cherry-picked with authorship preserved) for telemetry / installer-consent — different threat model from the localize work, but related enough to land together. That PR is now closed in favour of this one.

Background

PR #18960 (v15) moved escapeHTML out of UmbLocalizationController.#processTerm and into <umb-localize> because the central escape was double-encoding apostrophes / angle brackets when callers rendered via plain Lit templates (issues #18885, #18166, #18692). The fix was correct, but it left every manual unsafeHTML(this.localize.string(...)) site unsafe-by-default — interpolated user-controlled args were no longer escaped anywhere.

This PR closes that gap by providing a single safe helper:

• localize.string(text, ...args) — plain string output. Use for non-HTML contexts (attribute bindings — Lit auto-escapes attrs, notification messages, button labels, log strings).
• localize.htmlString(text, ...args) — Lit unsafeHTML directive with args escaped. Use whenever the localized value contains HTML markup that must be rendered.

Changes

New API: UmbLocalizationController.htmlString(text, ...args) + unit tests verifying both string and toString()-bypass XSS payloads are escaped.

Actual XSS fixes — these sites interpolated user-controlled content (item / entity names) into unsafeHTML:

File	What was unsafe
relations/.../delete-with-relation-modal.element.ts	_name flowing into unsafeHTML(localize.string(...)) (this branch's original scope; previously patched manually with escapeHTML, now via htmlString)
relations/.../trash-with-relation-modal.element.ts	Same — _name (this branch's original scope)
core/entity-action/common/delete/delete.action.ts	item.name flowing through umbConfirmModal.content → unsafeHTML (this branch's original scope)
core/recycle-bin/entity-action/trash/trash.action.ts	New XSS fix — same pattern as delete.action.ts, was not previously addressed

Cosmetic conversions — already safe (no args / numeric args), changed for consistency and to make the safe path the obvious one:

File	Args
core/modal/common/confirm/confirm-modal.element.ts	none (passthrough; safer-by-default for all future callers)
core/modal/common/info/info-modal.element.ts	none (same)
relations/.../bulk-delete-with-relation-modal.element.ts	uniques.length (number)
relations/.../bulk-trash-with-relation-modal.element.ts	uniques.length (number, ×2)
content/content/rollback/modal/content-rollback-modal.element.ts	none
documents/documents/rollback/modal/rollback-modal.element.ts	none
packages/.../installed-packages-section-view.element.ts	none
property-editors/text-box/property-editor-ui-text-box.element.ts	remaining (number)
property-editors/textarea/property-editor-ui-textarea.element.ts	remaining (number)

Sanitize defenses (cherry-picked from #22425, authored by @liamlaverty) — server-supplied / non-localize HTML:

File	What was unsafe
apps/installer/consent/installer-consent.element.ts	_selectedTelemetry.description from telemetry API rendered via unsafeHTML — now passed through sanitizeHTML first
packages/telemetry/dashboard-telemetry.element.ts	Same pattern for _selectedTelemetryDescription

The umb-news-card.element.ts change from #22425 was deliberately left out: umb-news-container.element.ts:14-17 already sanitizes i.body before passing items down, so a second sanitize would have been duplicate work per render.

ESLint rule — local-rules/no-unsafe-localize (error level) flags unsafeHTML(<x>.localize.string|term(...)) and points at htmlString() as the fix. Future regressions are caught at lint time, not in a security advisory. Lives in devops/eslint/rules/no-unsafe-localize.cjs alongside the existing local rules; verified to fire on bad fixtures and stay silent on the now-clean codebase.

Docs: docs/security.md updated with guidance on string() vs htmlString() and the modal-content wrapping pattern.

Out of scope (separate concerns, threat model differs)

• form-validation-message.element.ts renders the raw validationMessage via unsafeHTML — different threat model (raw input, no args), worth a separate look.

Test plan

• Existing 50 localization controller tests still pass.
• New unit tests confirm htmlString escapes both <script> injected via string args and via objects with a malicious toString().
• tsc --noEmit clean for changed files.
• eslint clean for changed files (only pre-existing `any` warnings).
• New no-unsafe-localize rule verified: fires on bad fixtures, zero false positives across src/.
• Manual: confirm a content node named `foo` in the delete/trash flow now shows the literal text in the confirm modal (not bold).
• Manual: verify the rollback diff help, packager empty state, and char-count text on text-box / textarea still render their HTML correctly.
• Manual: telemetry consent description on the installer + telemetry dashboard still render correctly with sanitize wrapper.

🤖 Generated with Claude Code

[claude]

Claude finished @iOvergaard's task in 4m 38s —— View job

---

PR Review

Target: origin/main · Based on commit: ea57cb63 · Skipped: 0 noise files out of 16 total

Adds UmbLocalizationController.htmlString() — a Lit unsafeHTML directive wrapper that escapes interpolated args — and converts all unsafeHTML(localize.string(...)) call sites across the backoffice to it, closing an XSS gap in the delete/trash confirmation flow.

• Modified public API: UmbLocalizationController — new htmlString() method (additive, no breaking change)
• Other changes: confirm-modal and info-modal internal rendering switched from unsafeHTML(localize.string(content)) to localize.htmlString(content) — same behavior for no-arg string content, safer for arg-interpolated content.

---

Important

• src/Umbraco.Web.UI.Client/src/libs/localization-api/localization.controller.ts:370 — escapeHTML silently returns non-string args unchanged (line 12–14 of escape-html.function.ts: return html as string). In htmlString, escapeHTML(a) is called for each arg — but for non-string types the escaping logic is entirely skipped, and String(a) in #processTerm will call the value's .toString() directly. An object with a custom toString() returning HTML would bypass escaping.

  All current call sites pass strings or numbers (safe in practice), but the JSDoc documents "Each argument is HTML-escaped" which is only partially true, and htmlString is publicly exported API that future callers will rely on with that guarantee.

  Fix is one character: pre-convert to string before escaping:

  const escapedArgs = args.map((a) => escapeHTML(String(a)));

  String("hello") is a no-op for strings, String(42) → "42" (already safe), and String({toString: () => '<script>'}) → "<script>" which then gets escaped correctly. Fix this →

Suggestions

• src/Umbraco.Web.UI.Client/src/libs/localization-api/localization.controller.test.ts:456 — The new test verifies <script> string injection is blocked, which is the core scenario. Consider adding a second case covering the object toString() path to document expected behavior and guard against regressions:

  it('should HTML-escape object toString() representation', async () => {
      const xss = { toString: () => '<script>alert("XSS")</script>' };
      const host = await fixture<HTMLElement>(html`<div>${controller.htmlString('#withInlineToken', xss, '')}</div>`);
      expect(host.innerHTML).to.not.contain('<script>');
  });

• src/Umbraco.Web.UI.Client/src/packages/content/content/rollback/modal/content-rollback-modal.element.ts:315 (same pattern in rollback-modal.element.ts:385) — Converts localize.term('rollback_diffHelp') (typed key, compile-time checked) to localize.htmlString('#rollback_diffHelp') (plain string, no key validation). This is the only available approach with the current API, but a future htmlTerm() overload with the same K extends keyof LocalizationSetType signature as term() would restore type-safety for single-key HTML rendering.

---

Approved with Suggestions for improvement

The core security fix is sound: htmlString() correctly escapes string args, all known unsafeHTML(localize.string(...)) call sites are converted, and the security docs are meaningfully improved. The Important finding (non-string bypass) is a genuine gap in the documented security contract and worth closing before this pattern spreads to more call sites, but the current call sites are all safe.

[Copilot]

Pull request overview

Adds a new UmbLocalizationController.htmlString() helper intended to make HTML-rendered localized strings safer (escape interpolated args + render via Lit unsafeHTML), and updates call sites to use it (including confirm/info modals and delete/trash flows) to close XSS gaps introduced by earlier escaping changes.

Changes:

• Adds UmbLocalizationController.htmlString() + unit test ensuring <script> injected via args is escaped.
• Replaces multiple unsafeHTML(this.localize.string/term(...)) call sites with this.localize.htmlString(...) (including relation modals, rollback help text, installed packages empty state, and textbox/textarea char count).
• Updates confirm/info modal internals and security docs with guidance for string() vs htmlString() and modal content wrapping.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Umbraco.Web.UI.Client/src/libs/localization-api/localization.controller.ts	Adds htmlString() helper wrapping localized output in unsafeHTML with escaped args.
src/Umbraco.Web.UI.Client/src/libs/localization-api/localization.controller.test.ts	Adds a unit test validating arg escaping when rendered via Lit.
src/Umbraco.Web.UI.Client/src/packages/core/modal/common/confirm/confirm-modal.element.ts	Uses localize.htmlString() when modal content is provided as a string.
src/Umbraco.Web.UI.Client/src/packages/core/modal/common/info/info-modal.element.ts	Uses localize.htmlString() when modal content is provided as a string.
src/Umbraco.Web.UI.Client/src/packages/core/entity-action/common/delete/delete.action.ts	Passes confirm modal content as a template using htmlString() for safe HTML rendering.
src/Umbraco.Web.UI.Client/src/packages/core/recycle-bin/entity-action/trash/trash.action.ts	Passes confirm modal content as a template using htmlString() for safe HTML rendering.
src/Umbraco.Web.UI.Client/src/packages/relations/relations/entity-actions/delete/modal/delete-with-relation-modal.element.ts	Replaces manual unsafeHTML(localize.string(...)) with localize.htmlString(...).
src/Umbraco.Web.UI.Client/src/packages/relations/relations/entity-actions/trash/modal/trash-with-relation-modal.element.ts	Replaces manual unsafeHTML(localize.string(...)) with localize.htmlString(...) and simplifies message selection.
src/Umbraco.Web.UI.Client/src/packages/relations/relations/entity-actions/bulk-delete/modal/bulk-delete-with-relation-modal.element.ts	Replaces manual unsafeHTML(localize.string(...)) with localize.htmlString(...).
src/Umbraco.Web.UI.Client/src/packages/relations/relations/entity-actions/bulk-trash/modal/bulk-trash-with-relation-modal.element.ts	Replaces manual unsafeHTML(localize.string(...)) with localize.htmlString(...).
src/Umbraco.Web.UI.Client/src/packages/documents/documents/rollback/modal/rollback-modal.element.ts	Uses localize.htmlString() for rollback diff help text rendered as HTML.
src/Umbraco.Web.UI.Client/src/packages/content/content/rollback/modal/content-rollback-modal.element.ts	Uses localize.htmlString() for rollback diff help text rendered as HTML.
src/Umbraco.Web.UI.Client/src/packages/packages/package-section/views/installed/installed-packages-section-view.element.ts	Uses localize.htmlString() for the “no packages” description HTML.
src/Umbraco.Web.UI.Client/src/packages/property-editors/text-box/property-editor-ui-text-box.element.ts	Uses localize.htmlString() for HTML char-count text.
src/Umbraco.Web.UI.Client/src/packages/property-editors/textarea/property-editor-ui-textarea.element.ts	Uses localize.htmlString() for HTML char-count text.
src/Umbraco.Web.UI.Client/docs/security.md	Documents string() vs htmlString() guidance and modal content usage pattern.

[AndyButland]

This tests out fine for me. E.g.:

I've also tested using Arabic script and that still renders correctly.

[Questo]

@AndyButland this is also affected the latest v16 (16.5.1), is there plants to merge this into v16 also?

[AndyButland]

It's possible if you need it @Questo, but honestly I'd look at getting onto 17 if you can. You are missing out on quite a bit of improvement and 16 goes EOL in a few weeks. Let me know what you decide.

[Questo]

Yeah I just went to your releases page and saw that v16 hits EOL very soon. I guess we'll try to get onto 17