…
` for short content, a collapsible `` with preview + full body for content exceeding `line_threshold`. |
+| `render_markdown(text)` | `(str) -> str` | You need Markdown→HTML inside a custom `format_html` (e.g. embedding a Markdown fragment in a richer HTML scaffold). Escapes raw HTML in `text` (untrusted-safe). |
+| `render_markdown_collapsible(raw_content, css_class, *, line_threshold=20, preview_line_count=5)` | `(str, str, int, int) -> str` | Long Markdown bodies (mail bodies, agent responses, multi-paragraph result text). Returns inline `
…
` for short content, a collapsible `` with preview + full body for content exceeding `line_threshold`. Escapes raw HTML. |
+| `escape_html(text)` | `(str) -> str` | Interpolating transcript-derived text into a `format_html` raw-HTML string, OR into a `title` return (which is emitted via `\| safe`). Entity-escapes `<`, `>`, `&`, quotes. |
+| `safe_markdown_inline(text)` | `(str) -> str` | Interpolating transcript-derived text into a Markdown **inline** fragment in `format_markdown` (a link label, a list item, inline prose) — the Markdown-output path emits `format_markdown` verbatim. Entity-escapes raw HTML tags while preserving Markdown formatting. |
The reference plugin's
[`tool_communicate_result.py`](../test/_plugins/clmail/src/claude_code_log_clmail_test/transformers/tool_communicate_result.py)
@@ -297,6 +314,59 @@ Add to `claude_code_log.plugins.__all__` only on concrete plugin-author
demand — every entry is an API commitment. Open an issue if a helper
you need isn't exposed.
+### 4.2 Security-conscious rendering
+
+**Every transcript-derived value is untrusted.** A transcript is not a
+trusted document: the assistant routinely echoes arbitrary user / file /
+web input verbatim ("write a test that types ``
+into the field"), and tool names, hook names, `cwd`-derived project names,
+session summaries and the like are all attacker-influenceable. There is no
+"trusted source" — if a value came from the transcript, escape it before it
+reaches a rendered position. A plugin that interpolates transcript data into
+its render methods reproduces the exact XSS sink class that issue #245 closed
+in the core.
+
+**Helper per context** — pick by *where the value lands*, covering **both**
+output paths:
+
+| Context (where the value lands) | Helper |
+|---|---|
+| `format_html` raw-HTML f-string (text or attribute) | `escape_html(value)` |
+| `format_html` embedding a Markdown body | `render_markdown(value)` / `render_markdown_collapsible(value, …)` |
+| `format_markdown` inline fragment (link label, list item, inline prose) | `safe_markdown_inline(value)` |
+| `title()` return | `escape_html(value)` — the HTML header emits it via `\| safe` (no core escaping); the Markdown heading is auto-gated by the core |
+
+Notes:
+
+- **Don't double-escape.** Pass a value through *one* helper for its context.
+ Don't `escape_html` a value and then also feed it to `render_markdown`
+ (you'd get visible `<` entities). A constant string needs no helper.
+- **`format_markdown` HTML safety is automatic; Markdown safety is not.**
+ When only `format_markdown` is defined, the HTML path runs it through
+ `render_markdown` (escapes raw HTML for you). The Markdown-output path emits
+ `format_markdown` verbatim, so inline transcript interpolation there needs
+ `safe_markdown_inline`.
+
+**Sink-class self-audit checklist** — scan your render methods for:
+
+- a raw f-string interpolating transcript data into HTML (`format_html`)
+- transcript data interpolated into a `title()` return
+- transcript data in a Markdown heading or inline link/list label
+ (`format_markdown`)
+- anything you emit into a `\| safe` / non-autoescaped context
+
+**Prefer one structural gate over per-site escaping.** The #245 class took
+several review rounds precisely because each sink was individually "known" but
+no single chokepoint enforced neutralisation, so new sinks kept slipping in.
+The core now routes every Markdown heading/label through one
+`safe_markdown_inline` gate. Apply the same principle in your plugin: if you
+build several rendered strings from transcript data, funnel them through one
+helper at one place rather than remembering to escape at each call site.
+
+For the core-renderer view of this contract (the per-field escaping the host
+renderer applies, and the title/markdown gate internals), see
+[implementing-a-tool-renderer.md](implementing-a-tool-renderer.md).
+
---
## 5. Dispatch resolution order
@@ -573,6 +643,7 @@ own plugin should follow the same shape:
| **2. Dispatch matrix** | Renderer-side vs class-side resolution; HTML vs Markdown output | Skip unless your plugin does something exotic with the dispatcher. |
| **3. Transformer integration** | End-to-end: real `MessageContent` through your `transform()` and class-side render methods | Always write this. Drive your transformer with hand-built `MessageMeta.empty()` candidates; assert the replacement is an instance of your subclass and that the render methods return the expected text. |
| **4. Text-equivalence** | If your plugin reads `UserTextMessage.items`, assert that the joined text matches what the factory's `extract_text_content` produces | Recommended for any plugin keying on user text — protects you against future core refactors that sneak normalization between extraction and the items list. |
+| **5. XSS payload** | Feed a payload (`
`) into every transcript-derived field your render methods interpolate, render BOTH paths, and assert the raw tag is escaped (not present verbatim) | Write this whenever your `format_html` / `format_markdown` / `title` interpolates transcript data ([§4.2](#42-security-conscious-rendering)). String-level: assert `" None:
assert "bold" in render_user_markdown("**bold**")
+def test_render_markdown_escapes_html() -> None:
+ """The shared (assistant/tool/web-authored) renderer must escape raw HTML.
+
+ Regression for the XSS where a transcript whose assistant text, tool
+ result, or fetched web content contained ``'
+ out = render_markdown(payload)
+ # No live markup reaches the DOM (escaped tags carry a dead
+ # ``onerror="`` but never a live ``onerror="`` on a real tag).
+ assert ")",
+ ):
+ out = render(src)
+ # The scheme is dangerous only as a live href/src attribute;
+ # appearing as visible link text is harmless.
+ assert 'href="javascript:' not in out, (render.__name__, src, out)
+ assert 'src="javascript:' not in out, (render.__name__, src, out)
+ assert 'href="data:' not in out, (render.__name__, src, out)
+ assert 'src="data:' not in out, (render.__name__, src, out)
+
+
+def test_assistant_text_does_not_inject_live_html() -> None:
+ """End-to-end: assistant text with HTML must not emit live tags."""
+ from claude_code_log.html.assistant_formatters import (
+ format_assistant_text_content,
+ )
+ from claude_code_log.models import (
+ AssistantTextMessage,
+ MessageMeta,
+ TextContent,
+ )
+
+ meta = MessageMeta(
+ session_id="test-session",
+ timestamp="2024-01-01T00:00:00Z",
+ uuid="test-uuid",
+ )
+ payload = "Sure! I'll enter into the field."
+ content = AssistantTextMessage(meta, items=[TextContent(type="text", text=payload)])
+ out = format_assistant_text_content(content)
+ assert " into the
+field"). See ``html/utils.py::_get_markdown_renderer`` for the escape policy.
+
+It is ALSO placed in a TITLE field — a generic tool_use's ``name`` (#245):
+the header title path (``{{ message_title | safe }}``) has no central
+escaping, so a tool with no specialized title method renders its raw name
+live in the header span. That channel is blind to the body-render escape and
+needs the per-field ``escape_html`` on the HTML title methods.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from playwright.sync_api import Page
+
+from claude_code_log.converter import load_transcript
+from claude_code_log.html.renderer import generate_html
+
+# Auto-firing vectors: "
+)
+
+_BASE = {
+ "cwd": "/app",
+ "isSidechain": False,
+ "sessionId": "11110000-0000-4000-8000-000000000001",
+ "userType": "external",
+ "version": "1.0.0",
+}
+_USAGE = {"input_tokens": 1, "output_tokens": 1}
+
+
+def _write_transcript(path: Path) -> None:
+ rows = [
+ {
+ **_BASE,
+ "type": "user",
+ "uuid": "u1",
+ "parentUuid": None,
+ "timestamp": "2026-06-27T10:00:00.000Z",
+ "message": {
+ "role": "user",
+ "content": f"Write an E2E test that types this: {PAYLOAD}",
+ },
+ },
+ {
+ **_BASE,
+ "type": "assistant",
+ "uuid": "a1",
+ "parentUuid": "u1",
+ "requestId": "r1",
+ "timestamp": "2026-06-27T10:00:01.000Z",
+ "message": {
+ "role": "assistant",
+ "model": "claude",
+ "id": "m1",
+ "type": "message",
+ "stop_reason": "end_turn",
+ "stop_sequence": None,
+ "usage": _USAGE,
+ "content": [
+ {"type": "text", "text": f"Sure! I'll enter {PAYLOAD} there."},
+ {
+ "type": "tool_use",
+ "id": "t1",
+ "name": "Write",
+ "input": {
+ "file_path": "/app/t.spec.ts",
+ "content": f"await page.fill('#in', '{PAYLOAD}');",
+ },
+ },
+ ],
+ },
+ },
+ {
+ **_BASE,
+ "type": "user",
+ "uuid": "u2",
+ "parentUuid": "a1",
+ "timestamp": "2026-06-27T10:00:02.000Z",
+ "message": {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "t1",
+ "content": f"Wrote file containing {PAYLOAD}",
+ }
+ ],
+ },
+ },
+ {
+ # TITLE-path vector (#245): a tool with no specialized title method
+ # falls back to its raw name in the header span. The name IS the
+ # payload — auto-firing if the title isn't escaped.
+ **_BASE,
+ "type": "assistant",
+ "uuid": "a2",
+ "parentUuid": "u2",
+ "requestId": "r2",
+ "timestamp": "2026-06-27T10:00:03.000Z",
+ "message": {
+ "role": "assistant",
+ "model": "claude",
+ "id": "m2",
+ "type": "message",
+ "stop_reason": "end_turn",
+ "stop_sequence": None,
+ "usage": _USAGE,
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "t2",
+ "name": PAYLOAD,
+ "input": {"q": "noop"},
+ }
+ ],
+ },
+ },
+ ]
+ path.write_text("\n".join(json.dumps(r) for r in rows) + "\n", encoding="utf-8")
+
+
+class TestTranscriptXss:
+ @pytest.mark.browser
+ def test_opening_transcript_fires_no_dialog(
+ self, page: Page, tmp_path: Path
+ ) -> None:
+ jsonl = tmp_path / "xss.jsonl"
+ _write_transcript(jsonl)
+ entries = load_transcript(jsonl, silent=True)
+ html_path = tmp_path / "xss.html"
+ html_path.write_text(generate_html(entries, "XSS"), encoding="utf-8")
+
+ dialogs: list[str] = []
+
+ def _on_dialog(dialog: object) -> None: # pragma: no cover - event cb
+ dialogs.append(getattr(dialog, "message", ""))
+ dialog.dismiss() # type: ignore[attr-defined]
+
+ page.on("dialog", _on_dialog)
+ page.goto(html_path.as_uri())
+ # Give any onerror/script a tick to fire.
+ page.wait_for_timeout(200)
+
+ assert dialogs == [], f"XSS executed — dialogs fired: {dialogs}"
+
+ # And the payload is still visible to the reader, as escaped text.
+ body_text = page.inner_text("body")
+ assert "script-xss" in body_text
+ assert "alert('img-xss')" in body_text
+
+ @pytest.mark.browser
+ def test_no_content_supplied_nodes_in_dom(self, page: Page, tmp_path: Path) -> None:
+ """The payload tags must not materialise as live DOM nodes."""
+ jsonl = tmp_path / "xss.jsonl"
+ _write_transcript(jsonl)
+ entries = load_transcript(jsonl, silent=True)
+ html_path = tmp_path / "xss.html"
+ html_path.write_text(generate_html(entries, "XSS"), encoding="utf-8")
+
+ page.goto(html_path.as_uri())
+
+ # No ![]()
whose src is the payload's bogus "x" was injected, and no
+ # content-supplied leaked as a live element.
+ injected = page.evaluate(
+ "() => ({"
+ " imgs: document.querySelectorAll('img[src=\"x\"]').length,"
+ " bolds: Array.from(document.querySelectorAll('b'))"
+ " .filter(b => b.textContent === 'bold').length,"
+ "})"
+ )
+ assert injected == {"imgs": 0, "bolds": 0}, injected
diff --git a/test/test_xss_markdown_surfaces.py b/test/test_xss_markdown_surfaces.py
new file mode 100644
index 00000000..7f124b0e
--- /dev/null
+++ b/test/test_xss_markdown_surfaces.py
@@ -0,0 +1,128 @@
+"""XSS: every Markdown interpolation surface routes through one gate (#245).
+
+Round-4 follow-up: the per-message + page/project/session headings were gated
+last; this generalises the gate to `safe_markdown_inline` and routes the inline
+link-label / list surfaces through it too — so "neutralise raw HTML from every
+source" is a single structural property, not a per-site convention.
+
+Surfaces (markdown/renderer.py), each driven end-to-end here:
+- WebSearch result link title → format_WebSearchOutput
+- projects-index project heading + link → generate_projects_index
+- per-project session-link label → generate_projects_index (combined off)
+- expand-paths tree label → generate_projects_index (expand_paths)
+- (TOC label + headings are pinned in test_xss_titles.py)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from claude_code_log.markdown.renderer import MarkdownRenderer, safe_markdown_inline
+from claude_code_log.models import (
+ MessageMeta,
+ SystemMessage,
+ WebSearchLink,
+ WebSearchOutput,
+)
+from claude_code_log.renderer import TemplateMessage
+
+PAYLOAD = ""
+
+
+def _no_raw_tag(md: str) -> None:
+ assert "`` marker), so there is no
+central escaping. Each ``title_*`` method that interpolates a transcript field
+must therefore escape that field on the HTML path. daaain's PR secured the
+message *body* (the shared Markdown renderer → ``escape=True``) but left four
+title sinks unescaped; these pin them.
+
+The four sinks (all on the shared base ``Renderer``; the HTML renderer escapes
+on its side only, so the Markdown renderer doesn't get HTML-entity-escaped
+titles):
+
+1. generic / mcp__* / custom tool name — ``title_ToolUseMessage`` fallback
+2. hook name — ``title_HookAttachmentMessage``
+3. workflow phase title — ``title_WorkflowPhaseMessage``
+4. workflow agent label — ``title_WorkflowAgentMessage``
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from claude_code_log.converter import load_transcript
+from claude_code_log.html.renderer import HtmlRenderer, generate_html
+from claude_code_log.markdown.renderer import MarkdownRenderer
+from claude_code_log.models import (
+ BashInput,
+ HookAttachmentMessage,
+ MessageMeta,
+ SystemMessage,
+ ToolUseMessage,
+ WorkflowAgentMessage,
+ WorkflowPhaseMessage,
+)
+from claude_code_log.renderer import TemplateMessage
+
+PAYLOAD = ""
+ESCAPED = "<img src=x onerror=alert(1)>"
+
+
+def _meta() -> MessageMeta:
+ return MessageMeta(uuid="u", session_id="s", timestamp="2025-01-01T00:00:00Z")
+
+
+def _title(content) -> str:
+ msg = TemplateMessage(content)
+ return HtmlRenderer().title_content(msg)
+
+
+class TestTitlePathEscaping:
+ def test_generic_tool_name_escaped(self, tmp_path: Path):
+ # A tool with no specialized title method (generic / mcp__* / custom)
+ # falls back to its raw name in the header. Exercise the real render
+ # path with the payload AS the tool name.
+ rows = [
+ {
+ "type": "user",
+ "uuid": "u0",
+ "parentUuid": None,
+ "isSidechain": False,
+ "userType": "external",
+ "cwd": "/x",
+ "sessionId": "s1",
+ "version": "1.0",
+ "timestamp": "2025-01-01T00:00:00Z",
+ "message": {"role": "user", "content": "go"},
+ },
+ {
+ "type": "assistant",
+ "uuid": "a1",
+ "parentUuid": "u0",
+ "isSidechain": False,
+ "userType": "external",
+ "cwd": "/x",
+ "sessionId": "s1",
+ "version": "1.0",
+ "timestamp": "2025-01-01T00:00:01Z",
+ "requestId": "r1",
+ "message": {
+ "id": "m1",
+ "type": "message",
+ "role": "assistant",
+ "model": "claude",
+ "stop_reason": "tool_use",
+ "stop_sequence": None,
+ "usage": {"input_tokens": 1, "output_tokens": 1},
+ "content": [
+ {"type": "tool_use", "id": "t1", "name": PAYLOAD, "input": {}}
+ ],
+ },
+ },
+ ]
+ f = tmp_path / "x.jsonl"
+ f.write_text("\n".join(json.dumps(r) for r in rows), encoding="utf-8")
+ html = generate_html(load_transcript(f, silent=True), "x")
+ assert PAYLOAD not in html
+ assert ESCAPED in html
+
+ def test_hook_name_escaped(self):
+ content = HookAttachmentMessage(meta=_meta(), kind="success", hook_name=PAYLOAD)
+ out = _title(content)
+ assert out.startswith("Hook · ")
+ assert PAYLOAD not in out
+ assert ESCAPED in out
+
+ def test_workflow_phase_title_escaped(self):
+ content = WorkflowPhaseMessage(meta=_meta(), title=PAYLOAD)
+ out = _title(content)
+ assert out.startswith("Phase: ")
+ assert PAYLOAD not in out
+ assert ESCAPED in out
+
+ def test_workflow_agent_label_escaped(self):
+ content = WorkflowAgentMessage(meta=_meta(), label=PAYLOAD)
+ out = _title(content)
+ assert out.startswith("Agent ")
+ assert PAYLOAD not in out
+ assert ESCAPED in out
+
+ def test_system_level_escaped(self):
+ # ``level`` is free-text from the transcript, not an enum. The title is
+ # ``System {level.title()}``; the title-casing folds the tag name's
+ # case (``![]()
``) but the tag would still fire (HTML attrs are
+ # case-insensitive), so it must be escaped AFTER ``.title()``.
+ content = SystemMessage(meta=_meta(), level=PAYLOAD, text="x")
+ out = _title(content)
+ assert out.startswith("System ")
+ # No live tag at any case; the dangerous ``<`` is entity-escaped, and
+ # ``.title()`` didn't corrupt the entity (no ``≪``).
+ assert "`` for a
+ downstream viewer to execute (#245)."""
+
+ def test_generic_tool_name_protected_in_markdown_heading(self, tmp_path: Path):
+ rows = [
+ {
+ "type": "user",
+ "uuid": "u0",
+ "parentUuid": None,
+ "isSidechain": False,
+ "userType": "external",
+ "cwd": "/x",
+ "sessionId": "s1",
+ "version": "1.0",
+ "timestamp": "2025-01-01T00:00:00Z",
+ "message": {"role": "user", "content": "go"},
+ },
+ {
+ "type": "assistant",
+ "uuid": "a1",
+ "parentUuid": "u0",
+ "isSidechain": False,
+ "userType": "external",
+ "cwd": "/x",
+ "sessionId": "s1",
+ "version": "1.0",
+ "timestamp": "2025-01-01T00:00:01Z",
+ "requestId": "r1",
+ "message": {
+ "id": "m1",
+ "type": "message",
+ "role": "assistant",
+ "model": "claude",
+ "stop_reason": "tool_use",
+ "stop_sequence": None,
+ "usage": {"input_tokens": 1, "output_tokens": 1},
+ "content": [
+ {"type": "tool_use", "id": "t1", "name": PAYLOAD, "input": {}}
+ ],
+ },
+ },
+ ]
+ f = tmp_path / "x.jsonl"
+ f.write_text("\n".join(json.dumps(r) for r in rows), encoding="utf-8")
+ md = MarkdownRenderer().generate(load_transcript(f, silent=True), "x")
+ # The raw tag must not survive into the heading…
+ assert f"# {PAYLOAD}" not in md
+ assert "