feat(api): rootless Podman OS sandbox for untrusted compiles

[frederikbeimgraben]

Summary

Stacked on #19. Implements the rootless Podman option from the sandbox proposal: non-trusted (UNTRUSTED/SANDBOXED) tectonic compiles run inside an ephemeral, network-less, read-only container. render_blob stays sandbox-agnostic — the wrapper is chosen by the TrustPolicy in compile_to_pdf, and TRUSTED builds run un-containerised as before.

Base = feat/pytex-api-module (PR #19), not main. Review/merge #19 first.

What's implemented

New module pytex_api._sandbox:

• build_podman_cmd — pure, unit-tested argv builder. Hardening flags:
  • --network none (no network at all; untrusted tectonic also runs --only-cached)
  • --read-only rootfs + size-capped /tmp tmpfs for scratch
  • --cap-drop ALL, --security-opt no-new-privileges, Podman's default seccomp profile (never weakened to unconfined)
  • --memory / --pids-limit / --cpus — cgroups v2 resource caps
  • Mounts: pre-warmed bundle cache as an ephemeral overlay (:O — writable view, host cache never mutated), the per-request workdir as the only read-write mount (SELinux-relabelled :Z), host font dirs read-only.
• SandboxConfig — image, cache dir, font dirs, caps, seccomp profile, tectonic_in_image.
• build_sandbox_image / sandbox_image_present — the privileged warm-up. Builds a Fedora image carrying tectonic (installed via its official binary + the libs it dynamically links — graphite2, openssl — since Fedora has no tectonic package) plus fontconfig. tectonic runs from the image, so no dynamically-linked host binary is smuggled into a minimal base. The image is never pulled/built at request time.

compile_to_pdf wiring:

• Sandbox is used only when podman is present and the image already exists locally (never pulls on the request path). Otherwise it falls back to the in-process setrlimit/timeout floor with an explicit console.warn — the weaker confinement is never silent.
• cgroup flags replace the in-process rlimits on the Podman path (an rlimit on the podman client would not reach the build inside).
• On the wall-clock kill, the named container is force-removed (podman rm -f) so the build cannot outlive the request.

Podman test proof (rootless, no sudo)

Podman 5.8.1 was already installed — the sudo exception was not needed (nothing installed via sudo, no system paths touched). All container work ran rootless as the user.

$ podman info  -> Rootless: true
# image built rootless from the in-code Containerfile (microdnf + official tectonic installer)
$ podman run --rm --network none localhost/pytex-tectonic:latest tectonic --version
Tectonic 0.16.9

# live untrusted build through the sandbox (render_blob, TrustLevel.UNTRUSTED, PDF):
should_sandbox(UNTRUSTED): True
SANDBOX PDF: b'%PDF-1.5' bytes: 7776 dur: 3.7s

# confinement spot-checks with the production flags:
no network        -> network blocked (good)   # curl in container fails
--read-only       -> touch /pwned -> Read-only file system (good)
--tmpfs /tmp      -> touch /tmp/ok -> writable (good)

The opt-in integration test (PYTEX_TEST_PODMAN=1) runs the same end-to-end: warm-up (download tectonic + bundle), then compile untrusted input fully offline through the sandbox — 15 passed.

Quality gates

• Tests: 15 new in tests/pytex_api/test_sandbox.py (14 pure flag/mount asserts + 1 opt-in live build). Full suite 811 passed, 2 skipped (skips = the real-tectonic PDF build from feat(api): blob-in/blob-out render module with trust levels #19 and the opt-in Podman build; both gated on env/availability).
• basedpyright src: 0 errors, 0 warnings (the CI gate).
• ruff: ruff format --check and ruff check on src tests both clean.

Notes / limitations

• The sandbox image is a privileged warm-up (build_sandbox_image, needs network for dnf + the tectonic installer). Production must build it out of band; an untrusted request never triggers a build or pull.
• Bundle cache is mounted overlay (:O) so it must be pre-warmed too (a TRUSTED build, or any prior compile, populates ~/.cache/Tectonic).
• setrlimit+timeout remain the fallback floor when podman/image are absent; the warning makes the downgrade visible.
• No new docs/ dir added.

🤖 Generated with Claude Code