feat(cli): trust gating with --untrusted / --trust-level

[frederikbeimgraben]

Why

Red-Team finding #9: the pytex CLI has no trust gating. By default it executes .py inputs, evaluates .tex pytex(...) replacements and Markdown eval comments, and runs tectonic with shell-escape on. That is RCE-by-design — fine for your own documents, dangerous on foreign/untrusted source. The trust model previously lived only in the pytex_api layer.

What

• CLI = TRUSTED context, stated explicitly in the module docstring, the argparse description/help, the README, and the wiki.
• --untrusted (shorthand for --trust-level untrusted) and --trust-level {trusted,sandboxed,untrusted} (mutually exclusive group). Default stays trusted → fully backwards-compatible.
• Non-trusted levels route the build through the existing pytex_api trust policy via render_blob, not duplicated logic:
  • .py / .tex.py refused (no exec),
  • .tex pytex(...) markers + Markdown eval comments stay inert,
  • shell-escape forced off, package allowlist enforced (dangerous packages like minted rejected),
  • resource limits; sandboxed additionally requires the Podman sandbox for PDFs.

How it docks onto pytex_api

_run dispatches on cfg.trust: TRUSTED keeps the in-process pipeline unchanged; any other level calls _run_untrusted, which reads the source bytes, maps the suffix to an InputKind (.py→TEX_PY, .tex→TEX, .md→MARKDOWN), builds a BuildRequest with the chosen TrustLevel, and calls render_blob. ApiError is mapped to BuildError so main reports it like any other failure. TrustLevel is imported from pytex_api._models (not the package root) to avoid a circular import — pytex_api/__init__ imports pytex_builder.console.

Tested vectors

• --untrusted on a .py that writes a file on import → blocked at the trust gate (exit 1, output absent, side effect never runs, error names TRUSTED).
• --untrusted on .tex requesting minted (the shell-escape package) → rejected.
• --untrusted on benign .tex → renders, but the pytex(...) marker survives verbatim (inert).
• Trusted default still executes .py (regression guard).
• Flag parsing: default trusted, --untrusted, --trust-level sandboxed, and mutual exclusion.

Status

• Full suite: 903 passed, 3 skipped.
• basedpyright src (configured root): 0 errors, 0 warnings.
• ruff format --check + ruff check: green.
• Wiki "CLI and Input Modes" page updated with a trust section (pushed).
• CHANGELOG entry added.

🤖 Generated with Claude Code