~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""Contracts for report export generation (LaTeX / Quarto-zip / ODT / PDF).
Threat model these tests encode
------------------------------
The bytes an exporter converts are the *assembled report*: LLM-generated
prose that was synthesised from pages the search engines fetched. A page
the researcher's own crawl retrieved can therefore steer what the model
writes, and whatever the model writes is handed verbatim to the format
converters behind ``/api/v1/research/{id}/export/{format}``. So report
text is attacker-influenceable input, and every exporter is a place where
inert prose can be promoted into something a downstream tool *executes*:
* ``.tex`` -> ``pdflatex`` runs control sequences. ``\\input`` reads a
local file into the rendered PDF with default settings; ``\\write18``
runs a shell command when ``-shell-escape`` is on.
* ``.qmd`` -> ``quarto render`` executes fenced cells tagged with a
language in braces, and honours front-matter keys that name scripts.
LDR itself never invokes a TeX or Quarto binary (verified: no
``pdflatex`` / ``xelatex`` / ``quarto`` subprocess exists anywhere in
``src/``), so nothing executes on the server. The exported file is the
payload carrier, and it detonates on the researcher's machine at the
moment they do the one thing the export exists for: compile it.
The tests below assert the two halves that together prove correctness for
an escaping boundary -- the payload's *text* arrives in the document
(so the test is not passing merely because the content was dropped), and
its *control sequence* does not.
Sections
--------
1. LaTeX body escaping (body and heading text are escaped through
``_escape_latex_text``, the bibliography through ``_escape_latex`` --
section 2 pins that both regions meet the same bar).
2. Bibliography path, as a positive control.
3. Quarto ``.qmd`` promotion and front matter.
4. Archive entry names (zip-slip) and download-filename sanitising.
5. Size guard, asserted without allocating.
6. Filesystem posture: exports are in-memory, so a failed export cannot
leave a partial file.
7. The pandoc subprocess boundary for ODT.
8. Route-level owner scoping and failure handling.
"""
import re
import zipfile
from contextlib import contextmanager
from contextlib import nullcontext as _nullcontext
from io import BytesIO
from unittest.mock import MagicMock, Mock, patch
import pytest
from local_deep_research.exporters.base import BaseExporter, ExportOptions
from local_deep_research.exporters.latex_exporter import LaTeXExporter
from local_deep_research.exporters.odt_exporter import ODTExporter
from local_deep_research.exporters.quarto_exporter import QuartoExporter
RESEARCH_ROUTER = "local_deep_research.web.routers.research"
ASSEMBLY = (
"local_deep_research.web.services.report_assembly_service"
".assemble_full_report"
)
# --------------------------------------------------------------------------
# Attack payloads, kept in named constants so they never appear inline in
# prose or in a docstring.
# --------------------------------------------------------------------------
# Reads an arbitrary local file into the compiled PDF. Needs no special
# pdflatex flag -- this is the default-settings exfiltration primitive.
TEX_FILE_READ = "\\input{/etc/passwd}"
# Shell escape. Requires pdflatex -shell-escape (or a shell_escape=t
# texmf.cnf), which several editor "build" integrations enable.
TEX_SHELL_ESCAPE = "\\immediate\\write18{touch /tmp/ldr-export-probe}"
# Loads a package the document never declared, e.g. one that turns shell
# escape on for the rest of the run.
TEX_PACKAGE_LOAD = "\\usepackage{shellesc}"
TEX_PAYLOADS = pytest.mark.parametrize(
("payload", "control_sequence", "surviving_text"),
[
(TEX_FILE_READ, "\\input", "passwd"),
(TEX_SHELL_ESCAPE, "\\write18", "ldr-export-probe"),
(TEX_PACKAGE_LOAD, "\\usepackage{shellesc}", "shellesc"),
],
ids=["file-read", "shell-escape", "package-load"],
)
# A Quarto cell whose language is in braces is *executed* by
# ``quarto render``; the same fence without braces is inert display code.
QUARTO_EXECUTABLE_CELL = "```{python}\nprint(open('/etc/passwd').read())\n```"
# A double quote closes the YAML scalar the title is interpolated into;
# the following newlines then start real top-level front-matter keys.
# ``project.pre-render`` names a script ``quarto render`` runs.
QUARTO_YAML_BREAKOUT = (
'Quarterly Report"\nproject:\n pre-render: attacker-script.sh\ntrailing: "'
)
# CRLF plus a header name: what a filename must never carry into a
# response header.
FILENAME_HEADER_BREAKOUT = "Report\r\nX-Injected: yes"
FILENAME_TRAVERSAL = "../../../etc/cron.d/ldr"
# --------------------------------------------------------------------------
# helpers
# --------------------------------------------------------------------------
def _export_latex(markdown: str, title: str = "Report") -> str:
"""Run the real registry exporter, returning the .tex source."""
result = LaTeXExporter().export(markdown, ExportOptions(title=title))
assert result.mimetype == "text/plain"
return result.content.decode("utf-8")
def _tex_body(tex: str) -> str:
"""The document body only.
The preamble legitimately contains ``\\usepackage`` and other control
sequences, so assertions about *report-derived* TeX must not see it.
"""
start = tex.index("\\maketitle") + len("\\maketitle")
end = tex.index("\\end{document}")
body = tex[start:end]
# Bibliography is a separately-escaped region (section 2).
if "\\begin{thebibliography}" in body:
body = body[: body.index("\\begin{thebibliography}")]
return body
def _quarto_parts(markdown: str, title: str | None = None):
"""Return (front_matter, qmd_body, zip_entry_names)."""
result = QuartoExporter().export(markdown, ExportOptions(title=title))
with zipfile.ZipFile(BytesIO(result.content)) as archive:
names = archive.namelist()
qmd_name = next(n for n in names if n.endswith(".qmd"))
qmd = archive.read(qmd_name).decode("utf-8")
# Front matter is the first fenced --- block.
_, front_matter, body = qmd.split("---", 2)
return front_matter, body, names
def _quarto_front_matter_keys(title: str) -> set:
"""Front-matter keys the exporter emits for a benign title."""
yaml = pytest.importorskip("yaml")
front, _body, _names = _quarto_parts("# Doc\n\nBody.\n", title=title)
return set(yaml.safe_load(front))
class _PretendHuge(str):
"""A short string that reports an oversized length.
Lets the size guard be exercised at its real threshold without
allocating 50 MB -- the guard only consults ``len()``.
"""
def __len__(self):
return BaseExporter.MAX_CONTENT_SIZE + 1
class _WriteWatchingOpen:
"""Delegating ``open`` that records every write-mode call."""
def __init__(self, real_open):
self._real_open = real_open
self.writes = []
def __call__(self, file, mode="r", *args, **kwargs):
if any(flag in str(mode) for flag in "wxa+"):
self.writes.append((str(file), str(mode)))
return self._real_open(file, mode, *args, **kwargs)
# --------------------------------------------------------------------------
# 1. LaTeX body escaping
# --------------------------------------------------------------------------
class TestLaTeXBodyEscaping:
"""Report prose must reach the .tex file as text, not as TeX code."""
@TEX_PAYLOADS
def test_report_prose_must_not_carry_live_control_sequences(
self, payload, control_sequence, surviving_text
):
"""A control sequence in LLM prose must not become live TeX.
The exporter escapes the backslash along with ``&``, ``%`` and
``_`` in body text, so none of these payloads survive into the
``.tex`` file as something the first ``pdflatex`` run would
execute.
"""
report = (
"## Findings\n\n"
f"The reviewed literature states {payload} in section two.\n"
)
body = _tex_body(_export_latex(report))
# Arrival: the payload's text is in the document, so a pass below
# cannot come from the content having been silently dropped.
assert surviving_text in body
# Neutralisation: but not as something TeX will act on.
assert control_sequence not in body
assert payload not in body
def test_markdown_headings_are_escaped_like_body_text(self):
"""A heading line is escaped, then rewritten into a section.
``export_to_latex`` matches the leading ``#`` markers with
``_HEADING_PREFIX_RE``, escapes the heading text the same way it
escapes a body line, and only then rewrites the line into
``\\section{...}``. So a control sequence -- or the ``&``/``%``/
``_`` that would otherwise break compilation -- lands inside the
section argument neutralised, same as it would one line lower.
"""
report = f"# Results for R&D spend {TEX_FILE_READ}\n\nBody text.\n"
body = _tex_body(_export_latex(report))
assert "\\section{" in body # heading did become a section
assert "passwd" in body # arrival
assert "\\input" not in body
assert "R\\&D" in body
def test_one_dollar_sign_does_not_switch_escaping_off_for_the_rest(self):
"""A lone ``$`` must not disable body escaping anywhere.
``export_to_latex`` used to split the whole document on ``$``
and escape only even-indexed parts, so a single unpaired ``$``
-- a price, which LLM research prose produces constantly --
inverted the parity and every character after it was treated as
math mode and escaped not at all. That was a plain correctness
break as much as a security one: an unescaped ``_`` outside
math mode is a hard pdflatex error, so the exported document
stopped compiling. Math spans are now paired by a scanner that
treats an unpairable ``$`` as prose; this contract pins that
the escaping after such a dollar stays on.
"""
report = (
"Licences cost $5 per seat.\n\n"
"R&D spend rose 40% for the file_name metric.\n"
)
body = _tex_body(_export_latex(report))
assert "R" in body and "spend rose" in body # arrival
assert "\\&" in body
assert "\\%" in body
assert "\\_" in body
def test_a_control_sequence_inside_display_math_is_literal_text(
self,
):
"""An unsupported command in ``$$...$$`` must be inert text.
``test_citation_exporter_edge_cases.py`` still pins that ordinary
display math such as ``$$E = mc^2$$`` survives unescaped.
"""
report = "Benign report with no stray dollars.\n\n$$\\relax$$\n"
body = _tex_body(_export_latex(report))
assert "relax" in body # arrival
assert "\\relax" not in body
def test_escaper_that_would_fix_this_already_exists_in_the_module(self):
"""Positive control: the neutralising routine is present and works.
``LaTeXExporter._escape_latex`` handles the backslash correctly,
and the body path applies the same escaping through
``_escape_latex_text`` -- this pins that the shared helper's own
output is correct, independent of where it is called from.
"""
from local_deep_research.text_optimization.citation_formatter import (
LaTeXExporter as LegacyLaTeXExporter,
)
escaped = LegacyLaTeXExporter()._escape_latex(TEX_FILE_READ)
assert "passwd" in escaped # arrival
assert "\\input" not in escaped
assert "\\textbackslash" in escaped
# --------------------------------------------------------------------------
# 2. Bibliography path -- positive control for section 1
# --------------------------------------------------------------------------
class TestLaTeXBibliographyIsAlreadyHardened:
"""Same payload, same document, two regions -- one escaped by each."""
def test_body_must_meet_the_same_bar_as_the_bibliography(self):
"""One document, one payload, two regions -- one bar.
The bibliography and the body are escaped by different helpers
(``_escape_latex`` for the bibliography, ``_escape_latex_text``
for the body), so this test pins that both regions meet the same
bar rather than trusting that they happen to agree.
"""
report = (
f"The claim {TEX_FILE_READ} appears in the survey.\n\n"
"## Sources\n\n"
f"[1] A paper about {TEX_FILE_READ} and caches\n"
" URL: https://example.com/paper\n"
)
tex = _export_latex(report)
bibliography = tex[tex.index("\\begin{thebibliography}") :]
body = _tex_body(tex)
# Bibliography: arrival + neutralisation. Passes today.
assert "passwd" in bibliography
assert "\\input" not in bibliography
assert "\\textbackslash" in bibliography
# Body: the same payload, and so the same requirement.
assert "passwd" in body
assert "\\input" not in body
def test_a_url_carrying_a_brace_or_backslash_is_dropped_not_emitted(self):
"""Positive control on ``_safe_bibtex_url``: a source URL that
could break out of ``\\url{...}`` is omitted rather than repaired.
"""
breakout_url = "https://example.com/a}\\input{/etc/passwd"
report = (
f"Body.\n\n## Sources\n\n[1] Some source\n URL: {breakout_url}\n"
)
tex = _export_latex(report)
bibliography = tex[tex.index("\\begin{thebibliography}") :]
assert "\\bibitem[1]{1}" in bibliography # entry still emitted
assert "\\url{" not in bibliography # but with no link
assert "\\input" not in bibliography
# --------------------------------------------------------------------------
# 3. Quarto
# --------------------------------------------------------------------------
class TestQuartoDocumentPromotion:
def test_a_fenced_cell_in_prose_must_not_become_an_executable_cell(self):
"""``.qmd`` is not an inert rendering of the markdown.
The exporter copies the report body into the ``.qmd`` verbatim
apart from citation rewriting. A brace-tagged fence in LLM prose
is therefore an executable Quarto cell, and ``quarto render`` --
the only reason to request this format -- runs it. A plain
```` ```python ```` fence (no braces) is display-only and must
keep working; only the executable form needs neutralising.
"""
report = f"## Method\n\n{QUARTO_EXECUTABLE_CELL}\n\nDiscussion.\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(open(" in body # arrival: the text is still there
assert "```{python}" not in body # but not as a runnable cell
def test_a_defused_cell_keeps_its_language(self):
"""Defusing is a demotion, not a deletion: the cell becomes the
display fence it would have been in the markdown it came from, so the
reader still gets highlighted Python. A bare ```` ``` ```` would be
just as inert and would lose that, which no security assertion here
can see."""
report = f"## Method\n\n{QUARTO_EXECUTABLE_CELL}\n\nDiscussion.\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "```python\n" in body
def test_a_display_fence_survives_untouched(self):
"""Accept control on the defuser, and the reason it is not a blanket
strip: a plain fence was never executable, so a rule that neutralised
it would cost every code block in every report to close nothing."""
report = (
"## Method\n\n```python\nprint(open('/etc/passwd').read())\n```\n"
)
_front, body, _names = _quarto_parts(report, title="Report")
assert "```python\n" in body
assert "```{" not in body
def test_a_pandoc_attribute_fence_is_not_a_cell(self):
"""``{.python}`` is Pandoc's attribute syntax — a class on a display
block — and Quarto does not run it. The two forms differ by one
character, so the rule is graded on that character rather than on a
language name."""
report = "## Method\n\n```{.python}\nprint(1)\n```\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "```{.python}" in body
def test_a_cell_tag_inside_an_open_fence_is_demoted_too(self):
"""A report that QUOTES the executable syntax inside a longer fence
is still demoted. Quarto picks the engine with a regex that does not
track fences, knitr's chunk regex does not either, and the Jupyter
engine's reader opens a cell inside a display fence. So the quoted
example renders as ```` ```python ````: the accepted cost of failing
closed."""
report = "## Method\n\n````\n```{python}\nprint(1)\n```\n````\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python}" not in body
assert "````\n```python\n" in body
def test_the_exporters_own_note_and_bibtex_fence_survive(self):
"""The defuser runs on the report body only. The bibliography note the
exporter appends is its own markup: a bold heading (the reader
format turns fenced divs off, so a callout would show as text) and
a ```` ```bibtex ```` display fence."""
report = (
"Body.\n\n## Sources\n\n[1] A paper\n"
" URL: https://example.com/paper\n"
)
_front, body, _names = _quarto_parts(report, title="Report")
assert "**Bibliography File Required**" in body
assert ":::" not in body
assert "```bibtex" in body
class TestQuartoCellGrammarFollowsQuarto:
"""The defuser is graded against Quarto's readers, not CommonMark.
One of the regexes ``quarto render`` decides what runs with is
``startCodeCellRegEx`` in ``src/core/lib/break-quarto-md.ts``:
^\\s*(```+)\\s*\\{([=A-Za-z][=A-Za-z0-9._]*)( *[ ,].*)?\\}\\s*$
Each case below is a fence that Quarto reads as an executable cell while
a CommonMark reading does not — a defuser written to the wrong grammar
passes its own tests and still ships the cell.
"""
def test_a_space_between_the_fence_and_the_brace_still_opens_a_cell(self):
"""``\\s*`` sits between the fence and the brace in Quarto's regex."""
report = (
"## M\n\n``` {python}\nprint(open('/etc/passwd').read())\n```\n"
)
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(open(" in body
assert "{python}" not in body
def test_an_option_value_may_contain_a_backtick(self):
"""Quarto's option group is ``.*``. Excluding backticks from it lets a
cell carry one and slip past."""
report = '## M\n\n```{python, comment="`"}\nprint(1)\n```\n'
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python" not in body
def test_an_option_value_may_contain_a_closing_brace(self):
"""``fig.cap="a}b"`` is an ordinary caption. Quarto's ``.*`` is greedy
up to the last brace, so the cell opens."""
report = '## M\n\n```{r, fig.cap="a}b"}\nsessionInfo()\n```\n'
_front, body, _names = _quarto_parts(report, title="Report")
assert "sessionInfo()" in body
assert "{r," not in body
def test_a_cell_may_be_indented_past_the_commonmark_limit(self):
"""CommonMark stops a fence at three spaces; Quarto's cell open is
``^\\s*``, so four spaces — or a tab — is still a cell."""
for indent in (" ", "\t"):
report = f"## M\n\n{indent}```{{python}}\n{indent}print(1)\n{indent}```\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python}" not in body
def test_an_indented_closer_ends_the_block_for_quarto(self):
"""``endCodeRegEx`` is ``^\\s*``: an indented ``` closes a block opened
at column 0. A defuser that misses the close holds state and hands the
next cell through as if it were content."""
report = (
"## M\n\n```python\nx = 1\n ```\n```{python}\nprint(1)\n```\n"
)
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python}" not in body
def test_an_indented_display_fence_never_opens_a_block(self):
"""The mirror image: ``startCodeRegEx`` is ``^```` with no leading
whitespace, so an indented display fence is prose and does not shield
what follows it."""
report = "## M\n\n ```python\nx = 1\n```{python}\nprint(1)\n```\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python}" not in body
def test_a_tilde_fence_is_not_a_fence_to_quarto(self):
"""Quarto's splitter has no tilde branch. A ``~~~`` block is prose, so
a cell inside one runs — while a CommonMark reader treats the same
lines as an opaque code block."""
report = "## M\n\n~~~\n```{python}\nprint(1)\n```\n~~~\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python}" not in body
def test_a_longer_fence_inside_a_block_does_not_close_it(self):
"""Quarto closes on an EXACT tick match. Closing on ``>=`` ends the
block early, and everything after it is then read in the wrong state —
here that returns a later cell to plain text."""
report = (
"## M\n\n```{python}\n````\nprint(1)\n```\n"
"```{python}\nprint(2)\n```\n"
)
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "print(2)" in body
assert "{python}" not in body
def test_defusing_an_indented_cell_cannot_expose_a_new_one(self):
"""Demoting an indented cell leaves a line Quarto does not read as a
fence at all, which returns the lines after it to plain text — where
a tag that was content a moment ago is a cell of its own. A defuser
that tracked fences in a single reading would demote the first and
leave the second live."""
report = "## M\n\n ```{python}\n```{python}\nprint(1)\n ```\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "print(1)" in body
assert "{python}" not in body
def test_a_pandoc_attribute_fence_is_still_left_alone(self):
"""Accept control for the whole class: the first character of the tag
is what separates a cell from Pandoc's attribute syntax, and widening
the grammar must not start rewriting display blocks."""
report = "## M\n\n```{.python}\nprint(1)\n```\n"
_front, body, _names = _quarto_parts(report, title="Report")
assert "```{.python}" in body
def test_a_title_cannot_inject_front_matter_keys(self):
"""The title used to be interpolated into ``title: "{title}"``
unquoted.
A ``"`` in the title would close the scalar and the newlines
after it would open real top-level keys, so the exported
document could carry a front matter the exporter never wrote.
``project.pre-render`` would have been the interesting one:
``quarto render`` runs it as a script before rendering anything.
Reachability note: the title is ``research.title or
research.query``, i.e. the requesting user's own text, so today
this is self-directed. It is pinned because it was the same
missing-quoting root cause as the LaTeX body, at a key that
executes rather than merely displays.
"""
expected_keys = _quarto_front_matter_keys(title="Plain Title")
front, _body, _names = _quarto_parts(
"# Doc\n\nBody.\n", title=QUARTO_YAML_BREAKOUT
)
yaml = pytest.importorskip("yaml")
parsed = yaml.safe_load(front)
# Arrival: the title text is in the document...
assert "Quarterly Report" in front
# ...but it must not have become structure.
assert set(parsed) == expected_keys
assert "project" not in parsed
assert "attacker-script.sh" not in str(parsed.get("format", ""))
def test_the_whole_hostile_title_stays_inside_the_title_scalar(self):
"""Complementary framing of the same invariant: whatever the
title contains, round-tripping the front matter must give the
title back as one scalar rather than as new keys.
"""
yaml = pytest.importorskip("yaml")
front, _body, _names = _quarto_parts(
"# Doc\n\nBody.\n", title=QUARTO_YAML_BREAKOUT
)
parsed = yaml.safe_load(front)
# The title is Markdown with every ASCII punctuation character
# backslash-escaped, so Pandoc reads it as plain text.
title_text = re.sub(r"\\(.)", r"\1", str(parsed["title"]))
assert "attacker-script.sh" in title_text
# --------------------------------------------------------------------------
# 4. Archive entry names and download filenames
# --------------------------------------------------------------------------
class TestArchiveAndFilenameSafety:
def test_a_traversing_title_cannot_escape_the_zip(self):
"""Positive control -- zip-slip on write is closed.
``_generate_safe_filename`` strips everything outside
``[\\w\\s-]``, which removes both ``.`` and ``/``, so a traversing
title cannot produce a traversing archive member. Pinned because
the quarto exporter is the only writer of archive entry names and
the sanitiser it depends on lives in a different module.
"""
_front, _body, names = _quarto_parts(
"# Doc\n\nBody.\n", title=FILENAME_TRAVERSAL
)
assert len(names) == 2
for name in names:
assert not name.startswith("/")
assert ".." not in name
assert "/" not in name
assert "\\" not in name
# Arrival: the title's word characters did reach the entry name,
# so the assertions above are not passing on an empty string.
assert any("cron" in name for name in names)
def test_quarto_entry_names_strip_control_characters(self):
"""The shared helper keeps CR, LF and TAB -- by design.
``re.sub(r"[^\\w\\s-]", "", title)`` treats them as ``\\s`` and
keeps them; the export route is saved by ``quote(filename,
safe="")`` percent-encoding them (pinned in the route test
below and in the hostile-input matrix, which locks ``%0D%0A``
in the disposition). Stripping them in the shared helper would
break that locked contract, so the raw consumer -- the Quarto
export's zip entry names -- strips them at the sink instead:
no archive entry may carry CR, LF or TAB.
"""
_front, _body, names = _quarto_parts(
"# Doc\n\nBody.\n", title=FILENAME_HEADER_BREAKOUT
)
assert names
for name in names:
assert not any(ch in name for ch in "\r\n\t"), names
# Arrival: the title's word characters did reach the entry
# name, so the assertion above is not passing on an empty
# string.
assert any("Report" in name for name in names)
def test_a_title_of_only_punctuation_still_yields_a_named_file(self):
"""An all-punctuation title sanitises to the empty string, which
would otherwise download as ``.tex`` -- a dotfile with no stem,
hidden on Unix and rejected outright by some browsers. The
``None`` branch and the empty-after-sanitising branch now share
the same fallback (``base.py``'s empty-stem check).
"""
exporter = LaTeXExporter()
assert exporter._generate_safe_filename(None) == "research_report.tex"
filename = exporter._generate_safe_filename("...")
assert filename.removesuffix(".tex") != ""
# --------------------------------------------------------------------------
# 5. Size guard -- asserted, never allocated
# --------------------------------------------------------------------------
class TestContentSizeGuard:
def test_oversized_report_is_rejected_before_the_converter_runs(self):
"""The guard must short-circuit ahead of conversion, not after.
Exercised with a short string that misreports its length, so the
50 MB threshold is tested at its real value without the test
itself allocating 50 MB on a single-worker box.
"""
exporter = LaTeXExporter()
exporter._legacy = Mock()
with pytest.raises(ValueError, match="maximum size"):
exporter.export(_PretendHuge("short"), ExportOptions(title="t"))
exporter._legacy.export_to_latex.assert_not_called()
def test_guard_boundary_is_inclusive(self):
"""Exactly MAX_CONTENT_SIZE is accepted; one byte more is not."""
class _AtLimit(str):
def __len__(self):
return BaseExporter.MAX_CONTENT_SIZE
exporter = LaTeXExporter()
exporter._validate_content_size(_AtLimit("short")) # must not raise
with pytest.raises(ValueError):
exporter._validate_content_size(_PretendHuge("short"))
def test_every_registered_exporter_enforces_the_same_ceiling(self):
"""A new exporter that forgets ``_validate_content_size`` reopens
the OOM hole for its own format. Assert the guard is reachable
through each registered exporter's public ``export``.
"""
from local_deep_research.exporters import ExporterRegistry
# Import side effects register the exporters.
import local_deep_research.exporters # noqa: F401
formats = ExporterRegistry.get_available_formats()
assert {"latex", "quarto", "odt", "pdf"} <= set(formats)
unguarded = []
for name in formats:
exporter = ExporterRegistry.get_exporter(name)
# ODT checks for pypandoc before it checks the size, so stub
# that boundary rather than skipping the format when the
# optional dependency is absent.
guard = _stubbed_pandoc() if name == "odt" else _nullcontext()
try:
with guard:
exporter.export(
_PretendHuge("short"), ExportOptions(title="t")
)
except ValueError as exc:
if "maximum size" in str(exc):
continue
unguarded.append((name, repr(exc)))
except Exception as exc: # noqa: BLE001 - classified here
unguarded.append((name, repr(exc)))
else:
unguarded.append((name, "no error raised"))
assert unguarded == []
# --------------------------------------------------------------------------
# 6. Filesystem posture
# --------------------------------------------------------------------------
class TestExportsTouchNoFiles:
"""Every exporter is documented as in-memory. If that holds, a failed
export cannot leave a partial file behind -- there is no file. These
assert the property rather than the docstring.
"""
def test_a_successful_latex_export_opens_nothing_for_writing(self):
import builtins
watcher = _WriteWatchingOpen(builtins.open)
exporter = LaTeXExporter() # construct outside the patch
with patch.object(builtins, "open", watcher):
result = exporter.export(
"# Doc\n\nBody.\n", ExportOptions(title="Report")
)
assert result.content.startswith(b"\\documentclass")
assert watcher.writes == []
def test_a_failing_export_leaves_no_partial_file(self):
import builtins
exporter = LaTeXExporter()
exporter._legacy = Mock()
exporter._legacy.export_to_latex.side_effect = RuntimeError(
"converter blew up midway"
)
watcher = _WriteWatchingOpen(builtins.open)
with patch.object(builtins, "open", watcher):
with pytest.raises(RuntimeError, match="blew up"):
exporter.export("# Doc\n", ExportOptions(title="Report"))
assert watcher.writes == []
def test_quarto_builds_its_archive_in_memory(self):
import builtins
watcher = _WriteWatchingOpen(builtins.open)
exporter = QuartoExporter()
with patch.object(builtins, "open", watcher):
result = exporter.export(
"# Doc\n\nBody.\n", ExportOptions(title="Report")
)
assert result.content[:2] == b"PK"
assert watcher.writes == []
# --------------------------------------------------------------------------
# 7. The pandoc subprocess boundary (ODT)
# --------------------------------------------------------------------------
@contextmanager
def _stubbed_pandoc(stdout=b"PK\x03\x04odt-bytes"):
"""Stub the pandoc boundary.
The real binary is never run: the whole point of this test is the
argv and stdin handed to it, and pandoc would render the payload
rather than report it.
"""
from local_deep_research.exporters import odt_exporter as module
fake_pypandoc = Mock()
fake_pypandoc.get_pandoc_path.return_value = "/usr/bin/pandoc"
completed = Mock(stdout=stdout, stderr=b"", returncode=0)
with (
patch.object(module, "PYPANDOC_AVAILABLE", True),
patch.object(module, "pypandoc", fake_pypandoc),
patch.object(
ODTExporter, "_pandoc_supports_sandbox", return_value=True
),
patch.object(
module.subprocess, "run", return_value=completed
) as run_mock,
):
yield run_mock
class TestODTPandocInvocation:
def test_report_text_is_piped_on_stdin_never_placed_in_argv(self):
"""Report content must not be able to become a pandoc argument.
If it could, a report opening with ``--`` would be read as a flag
(``--lua-filter`` executes a script). Piping on stdin makes that
structurally impossible; this pins the structure.
"""
marker = "--lua-filter=/tmp/ldr-export-probe.lua"
report = f"## Findings\n\nThe study noted {marker} in passing.\n"
with _stubbed_pandoc() as run_mock:
ODTExporter().export(report, ExportOptions(title="Report"))
cmd = run_mock.call_args.args[0]
kwargs = run_mock.call_args.kwargs
assert marker.encode() in kwargs["input"] # arrival, via stdin
assert not any(marker in str(arg) for arg in cmd)
assert kwargs.get("shell") is not True
def test_output_goes_to_stdout_so_no_temp_file_can_be_left(self):
with _stubbed_pandoc() as run_mock:
result = ODTExporter().export(
"# Doc\n\nBody.\n", ExportOptions(title="Report")
)
cmd = run_mock.call_args.args[0]
assert cmd[0] == "/usr/bin/pandoc"
assert cmd[cmd.index("-o") + 1] == "-"
# Raw passthrough, native divs and spans, body metadata and
# multiline tables off: report text reaches the ODT as text.
assert cmd[cmd.index("-f") + 1] == (
"markdown-raw_attribute-raw_html-raw_tex"
"-native_divs-native_spans-yaml_metadata_block-multiline_tables"
)
assert cmd[cmd.index("-t") + 1] == "odt"
assert result.content == b"PK\x03\x04odt-bytes"
def test_title_metadata_stays_one_argv_token(self):
"""``--metadata=title:<value>`` is a single token, so a title that
looks like a flag cannot become one. Positive control on the
sanitiser's actual guarantee.
"""
hostile_title = "--lua-filter /tmp/x.lua"
with _stubbed_pandoc() as run_mock:
ODTExporter().export("# Doc\n", ExportOptions(title=hostile_title))
cmd = run_mock.call_args.args[0]
metadata_args = [
arg for arg in cmd if str(arg).startswith("--metadata=")
]
assert len(metadata_args) == 1
assert metadata_args[0].startswith("--metadata=title:")
# "--" stripped by _sanitize_metadata, and nothing split out.
assert not any(str(arg).startswith("--lua") for arg in cmd)
def test_pandoc_failure_surfaces_as_runtime_error_not_partial_output(self):
"""An empty stdout must raise rather than return a zero-byte ODT
that the browser would happily download as a corrupt document.
"""
with _stubbed_pandoc(stdout=b""):
with pytest.raises(RuntimeError, match="no output"):
ODTExporter().export("# Doc\n", ExportOptions(title="R"))
# --------------------------------------------------------------------------
# 8. Route-level contracts
# --------------------------------------------------------------------------
def _call_export_route(
*,
username="alice",
research_row=None,
export_return=(b"content", "report.tex", "text/plain"),
export_side_effect=None,
seen_usernames=None,
):
from local_deep_research.web.routers.research import (
export_research_report,
)
query = MagicMock()
query.filter_by.return_value.first.return_value = research_row
session = MagicMock()
session.query.return_value = query
@contextmanager
def fake_db_session(user, *args, **kwargs):
if seen_usernames is not None:
seen_usernames.append(user)
yield session
export_patch = {}
if export_side_effect is not None:
export_patch["side_effect"] = export_side_effect
else:
export_patch["return_value"] = export_return
with (
patch(
f"{RESEARCH_ROUTER}.get_user_db_session",
side_effect=fake_db_session,
),
patch(ASSEMBLY, return_value="# report\n\nbody\n"),
patch(
f"{RESEARCH_ROUTER}.export_report_to_memory", **export_patch
) as export_mock,
):
response = export_research_report(
Mock(), "rid-1", "latex", username=username
)
return response, query, export_mock
class TestExportRouteContracts:
def test_export_reads_only_the_authenticated_users_database(self):
"""Scoping here is by database, not by a WHERE clause: the query
is ``filter_by(id=research_id)`` with no owner predicate, so the
session must come from the authenticated user's own encrypted DB
and from no other name the request can influence.
"""
row = Mock(title="Report", query="q")
seen = []
response, query, _export = _call_export_route(
username="alice", research_row=row, seen_usernames=seen
)
assert response.status_code == 200
assert seen == ["alice"]
filter_kwargs = query.filter_by.call_args.kwargs
assert filter_kwargs == {"id": "rid-1"}
def test_another_users_research_id_is_a_404_not_a_download(self):
response, _query, export_mock = _call_export_route(research_row=None)
assert response.status_code == 404
export_mock.assert_not_called()
def test_a_failed_export_returns_an_error_body_with_no_content(self):
"""No partial payload, and no exporter internals in the message."""
response, _query, _export = _call_export_route(
research_row=Mock(title="Report", query="q"),
export_side_effect=RuntimeError(
"pandoc: /home/ldr/secret/path not found"
),
)
assert response.status_code == 500
assert b"secret/path" not in response.body
assert b"content-disposition" not in response.body.lower()
def test_disposition_header_carries_no_raw_control_characters(self):
"""Positive control: whatever ``_generate_safe_filename`` leaves
in the filename, the route's percent-encoding must keep CR/LF out
of the header value.
"""
# Route-level control: hand the route a hostile filename
# directly, bypassing the sanitizer, so the percent-encoding
# defence is pinned independently of it. CRLF in a title
# reaches the route, is percent-encoded rather than stripped,
# and never appears raw.
raw_filename = f"{FILENAME_HEADER_BREAKOUT}.tex"
response, _query, _export = _call_export_route(
research_row=Mock(title="Report", query="q"),
export_return=(b"content", raw_filename, "text/plain"),
)
disposition = response.headers["content-disposition"]
assert response.status_code == 200
assert "Report" in disposition # arrival
# The CRLF arrives raw at the route and leaves percent-encoded --
# which is exactly what keeps it inert in the header value.
assert not re.search(r"[\r\n]", disposition)
assert "%0D%0A" in disposition
# Only the two filename parameters may introduce separators.
assert disposition.count(";") == 2
assert 'filename="' in disposition
assert "filename*=UTF-8''" in disposition
def test_unknown_format_is_rejected_before_any_db_read(self):
from local_deep_research.web.routers.research import (
export_research_report,
)
with patch(f"{RESEARCH_ROUTER}.get_user_db_session") as session_factory:
response = export_research_report(
Mock(), "rid-1", "../../etc/passwd", username="alice"
)
assert response.status_code == 400
session_factory.assert_not_called()