maf-sandbox-document 0.2.0__py3-none-any.whl

maf_sandbox_document/__init__.py

@@ -0,0 +1,33 @@
+"""Guarded document extraction in disposable sandboxes."""
+
+import warnings as _warnings
+
+from ._tool import (
+    DOCUMENT_KIND,
+    DOCUMENT_READ_TOOL_NAME,
+    document_sandbox_spec,
+    make_document_tools,
+)
+
+__all__ = [
+    "DOCUMENT_KIND",
+    "DOCUMENT_READ_TOOL_NAME",
+    "MafSandboxDocumentExperimentalWarning",
+    "document_sandbox_spec",
+    "make_document_tools",
+]
+
+
+class MafSandboxDocumentExperimentalWarning(UserWarning):
+    """Warning category for the experimental document kind."""
+
+
+try:
+    _warnings.warn(
+        "maf_sandbox_document is experimental and may change or be removed without notice.",
+        category=MafSandboxDocumentExperimentalWarning,
+        stacklevel=2,
+    )
+except MafSandboxDocumentExperimentalWarning:
+    # The pre-1.0 notice must not prevent imports under -W error.
+    pass

maf_sandbox_document/_guest.py

@@ -0,0 +1,393 @@
+"""Fixed document converter, executed only in a disposable POSIX guest."""
+
+from __future__ import annotations
+
+import importlib
+import io
+import json
+import math
+import re
+import struct
+import sys
+import xml.etree.ElementTree as ET
+import xml.parsers.expat
+import zipfile
+import zlib
+from contextlib import closing
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+MAX_INPUT_BYTES = 16 * 1024 * 1024
+MAX_MEMBER_BYTES = 16 * 1024 * 1024
+MAX_TOTAL_BYTES = 64 * 1024 * 1024
+MAX_MEMBERS = 2048
+MAX_RATIO = 200
+MAX_PAGE_CHARS = 100_000
+MAX_OUTPUT_BYTES = 32 * 1024 * 1024
+MAX_OUTPUT_TOTAL = 64 * 1024 * 1024
+MAX_METADATA_BYTES = 64 * 1024
+MAX_DIAGNOSTIC = 2000
+MEDIA_TYPES = {
+    "pdf": "application/pdf",
+    "docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "rtf": "application/rtf",
+}
+
+
+class Refused(ValueError):
+    """A named document guard refused the input."""
+
+
+def selected_pages(total: int, pages: list[int] | None) -> list[int]:
+    """Clamp a 1-based inclusive range to the available pages."""
+    start, stop = pages or [1, total]
+    return list(range(min(start, total), min(stop, total) + 1)) if total else []
+
+
+def _xml_guard(data: bytes) -> None:
+    def refuse(*args: Any) -> Any:
+        raise Refused("XML DTDs and entities are refused")
+
+    parser = xml.parsers.expat.ParserCreate(namespace_separator="}")
+    parser.StartDoctypeDeclHandler = refuse
+    parser.EntityDeclHandler = refuse
+    parser.ExternalEntityRefHandler = refuse
+    parser.SetParamEntityParsing(xml.parsers.expat.XML_PARAM_ENTITY_PARSING_NEVER)
+    parser.Parse(data, True)
+
+
+def guarded_zip(data: bytes, kind: str) -> io.BytesIO:
+    """Verify metadata and actual expanded bytes, then rebuild a stored-only archive."""
+    rebuilt = io.BytesIO()
+    with zipfile.ZipFile(io.BytesIO(data)) as archive, zipfile.ZipFile(rebuilt, "w") as output:
+        members = archive.infolist()
+        if len(members) > MAX_MEMBERS:
+            raise Refused("max_zip_members exceeded")
+        total = 0
+        names: set[str] = set()
+        for member in members:
+            name = member.filename
+            path = PurePosixPath(name)
+            if (
+                name in names
+                or not name
+                or path.is_absolute()
+                or ".." in path.parts
+                or "\\" in name
+                or ":" in name
+                or "\x00" in name
+                or member.orig_filename != name
+                or (member.external_attr >> 16) & 0o170000 == 0o120000
+            ):
+                raise Refused("unsafe ZIP member name")
+            names.add(name)
+            if member.file_size > MAX_MEMBER_BYTES:
+                raise Refused("max_zip_member_bytes exceeded")
+            total += member.file_size
+            if total > MAX_TOTAL_BYTES:
+                raise Refused("max_zip_total_bytes exceeded")
+            if member.file_size > max(1, member.compress_size) * MAX_RATIO:
+                raise Refused("max_zip_ratio exceeded")
+            if member.flag_bits & 1 or member.compress_type not in (0, 8):
+                raise Refused("unsupported ZIP compression or encryption")
+            if path.suffix.lower() in {".zip", ".docx", ".pptx", ".xlsx", ".jar", ".7z", ".gz"}:
+                raise Refused("nested archive members are refused")
+        actual_total = 0
+        for member in members:
+            value = _zip_member(data, archive, member)
+            actual_total += len(value)
+            if actual_total > MAX_TOTAL_BYTES:
+                raise Refused("max_zip_total_bytes exceeded")
+            if value.startswith((b"PK\x03\x04", b"PK\x05\x06", b"7z\xbc\xaf", b"\x1f\x8b")):
+                raise Refused("nested archive members are refused")
+            image = value.startswith((b"\x89PNG\r\n", b"\xff\xd8\xff", b"GIF8", b"BM"))
+            if value and not image and not member.is_dir():
+                try:
+                    _xml_guard(value)
+                except xml.parsers.expat.ExpatError:
+                    if member.filename.endswith((".xml", ".rels")):
+                        raise
+            output.writestr(member.filename, value)
+        expected = "word/document.xml" if kind == "docx" else "ppt/presentation.xml"
+        if expected not in names or "[Content_Types].xml" not in names:
+            raise Refused("document type does not match OOXML content")
+        if ("ppt/presentation.xml" if kind == "docx" else "word/document.xml") in names:
+            raise Refused("ambiguous OOXML content")
+        # Both XML members above passed the DTD/entity guard before these structural reads.
+        document = ET.fromstring(archive.read(expected))  # nosec B314
+        namespace, local_name = (
+            ("wordprocessingml/2006/main", "document")
+            if kind == "docx"
+            else ("presentationml/2006/main", "presentation")
+        )
+        if document.tag != f"{{http://schemas.openxmlformats.org/{namespace}}}{local_name}":
+            raise Refused("document type does not match OOXML root")
+        types = ET.fromstring(archive.read("[Content_Types].xml"))  # nosec B314
+        expected_type = MEDIA_TYPES[kind].removesuffix(
+            ".document" if kind == "docx" else ".presentation"
+        )
+        expected_type += ".document.main+xml" if kind == "docx" else ".presentation.main+xml"
+        declared_types = [
+            item.get("ContentType") for item in types if item.get("PartName") == "/" + expected
+        ]
+        if declared_types != [expected_type]:
+            raise Refused("document type does not match OOXML content type")
+    rebuilt.seek(0)
+    return rebuilt
+
+
+def _zip_member(data: bytes, archive: zipfile.ZipFile, member: zipfile.ZipInfo) -> bytes:
+    """Bound expansion independently of the ZIP member's declared uncompressed size."""
+    # ZipFile validates local headers and overlap; ZipExtFile truncates to the declared size.
+    with archive.open(member):
+        offset = member.header_offset
+        name_size, extra_size = struct.unpack_from("<HH", data, offset + 26)
+        start = offset + 30 + name_size + extra_size
+        stop = start + member.compress_size
+        if not 0 <= start <= stop <= len(data):
+            raise Refused("invalid ZIP member bounds")
+        value = data[start:stop]
+        if member.compress_type == zipfile.ZIP_DEFLATED:
+            decoder = zlib.decompressobj(-zlib.MAX_WBITS)
+            value = decoder.decompress(value, MAX_MEMBER_BYTES + 1)
+            if len(value) > MAX_MEMBER_BYTES or decoder.unconsumed_tail:
+                raise Refused("max_zip_member_bytes exceeded")
+            if not decoder.eof or decoder.unused_data:
+                raise Refused("invalid ZIP compressed stream")
+        if len(value) > MAX_MEMBER_BYTES:
+            raise Refused("max_zip_member_bytes exceeded")
+        if len(value) != member.file_size:
+            raise Refused("ZIP member size mismatch")
+        if zlib.crc32(value) != member.CRC:
+            raise Refused("ZIP member CRC mismatch")
+        return value
+
+
+def _bounded_text(text: str, maximum: int, *, page: bool = False) -> str:
+    if page and len(text) > MAX_PAGE_CHARS:
+        raise Refused("max_page_chars exceeded")
+    if len(text) > maximum:
+        raise Refused("max_chars exceeded")
+    return text
+
+
+def _pdf(data: bytes, config: dict[str, Any]) -> tuple[int, list[int], str]:
+    # -I excludes the call directory; load only the separately staged fixed guard.
+    import runpy
+
+    guard = runpy.run_path(str(Path(__file__).with_name("_pdf_guard.py")))
+    try:
+        guard["check_pdf"](data)
+    except ValueError as exc:
+        raise Refused(str(exc)) from exc
+    pdfium = importlib.import_module("pypdfium2")
+    with pdfium.PdfDocument(data) as document:
+        count = len(document)
+        if count > config["max_pages"]:
+            raise Refused("max_pages exceeded")
+        chosen = selected_pages(count, config["pages"])
+        if not chosen:
+            raise Refused("document has no pages")
+        if config["format"] == "images" and len(chosen) > config["max_image_pages"]:
+            raise Refused("max_image_pages exceeded")
+        chunks: list[str] = []
+        total = 0
+        image_bytes = 0
+        for number in chosen:
+            with closing(document[number - 1]) as page:
+                with closing(page.get_textpage()) as textpage:
+                    if textpage.count_chars() > MAX_PAGE_CHARS:
+                        raise Refused("max_page_chars exceeded")
+                    if total + textpage.count_chars() > config["max_chars"]:
+                        raise Refused("max_chars exceeded")
+                    text = textpage.get_text_range()
+                    total += len(text)
+                    _bounded_text(text, config["max_chars"], page=True)
+                    chunks.append(text)
+                if config["format"] == "images":
+                    width, height = page.get_size()
+                    scale = config["image_dpi"] / 72
+                    if (
+                        not all(math.isfinite(v) and v > 0 for v in (width, height))
+                        or math.ceil(width * scale) * math.ceil(height * scale)
+                        > config["max_image_pixels"]
+                    ):
+                        raise Refused("max_image_pixels exceeded")
+                    with closing(page.render(scale=scale)) as bitmap:
+                        picture = bitmap.to_pil()
+                        try:
+                            picture.save(f"page-{number}.png", format="PNG")
+                        finally:
+                            picture.close()
+                    size = Path(f"page-{number}.png").stat().st_size
+                    if size > MAX_OUTPUT_BYTES:
+                        raise Refused("max_output_file_bytes exceeded")
+                    image_bytes += size
+                    if image_bytes > MAX_OUTPUT_TOTAL - MAX_METADATA_BYTES:
+                        raise Refused("max_output_total_bytes exceeded")
+        return count, chosen, _bounded_text("\n\n".join(chunks), config["max_chars"])
+
+
+def _pptx(archive: io.BytesIO, config: dict[str, Any]) -> tuple[int, list[int], str]:
+    pptx = importlib.import_module("pptx")
+    oxml = importlib.import_module("pptx.oxml")
+    etree = importlib.import_module("lxml.etree")
+    parser = etree.XMLParser(
+        remove_blank_text=True, resolve_entities=False, load_dtd=False, no_network=True
+    )
+    parser.set_element_class_lookup(oxml.element_class_lookup)
+    setattr(oxml, "oxml_parser", parser)
+    presentation = pptx.Presentation(archive)
+    count = len(presentation.slides)
+    if count > config["max_pages"]:
+        raise Refused("max_pages exceeded")
+    chosen = selected_pages(count, config["pages"])
+    if not chosen:
+        raise Refused("document has no slides")
+    chunks: list[str] = []
+    for number in chosen:
+        slide = presentation.slides[number - 1]
+        parts: list[str] = []
+        pending = list(reversed(slide.shapes))
+        while pending:
+            shape = pending.pop()
+            if hasattr(shape, "shapes"):
+                pending.extend(reversed(shape.shapes))
+            if shape.has_text_frame:
+                parts.append(shape.text)
+            if shape.has_table:
+                for row in shape.table.rows:
+                    parts.append("\t".join(cell.text for cell in row.cells))
+        if slide.has_notes_slide:
+            notes = slide.notes_slide.notes_text_frame
+            if notes is not None:
+                parts.append(notes.text)
+        text = _bounded_text("\n".join(parts), config["max_chars"], page=True)
+        chunks.append(f"## Slide {number}\n\n{text}" if config["format"] == "markdown" else text)
+        _bounded_text("\n\n".join(chunks), config["max_chars"])
+    return count, chosen, "\n\n".join(chunks)
+
+
+def _omit_image(image: Any) -> list[Any]:
+    return []
+
+
+def convert(data: bytes, config: dict[str, Any]) -> dict[str, Any]:
+    """Write every requested output or refuse without reporting extraction success."""
+    if len(data) > MAX_INPUT_BYTES:
+        raise Refused("max_input_bytes exceeded")
+    kind = config["kind"]
+    if kind not in MEDIA_TYPES:
+        raise Refused("unsupported document format")
+    supported = ["text", "markdown"] + (["images"] if kind == "pdf" else [])
+    metadata: dict[str, Any] = {
+        "schema_version": 1,
+        "media_type": MEDIA_TYPES[kind],
+        "format": config["format"],
+        "supported_formats": supported,
+        "pages": None,
+        "selected_pages": [],
+        "characters": 0,
+        "truncated": False,
+        "range_clamped": False,
+        "verdict": "refused",
+        "reason": None,
+        "files": [],
+    }
+    try:
+        if config["format"] not in supported:
+            raise Refused("requested format is not supported for this document")
+        count, chosen = None, []
+        if kind == "pdf":
+            count, chosen, text = _pdf(data, config)
+        elif kind in ("docx", "pptx"):
+            archive = guarded_zip(data, kind)
+            if kind == "pptx":
+                count, chosen, text = _pptx(archive, config)
+            else:
+                if config["pages"] is not None:
+                    raise Refused("DOCX page ranges require a pagination engine")
+                mammoth = importlib.import_module("mammoth")
+                if config["format"] == "markdown":
+                    result = mammoth.convert_to_markdown(
+                        archive,
+                        external_file_access=False,
+                        include_embedded_style_map=False,
+                        convert_image=_omit_image,
+                    )
+                else:
+                    result = mammoth.extract_raw_text(archive)
+                text = _bounded_text(result.value, config["max_chars"])
+        else:
+            if not re.match(rb"\{\\rtf[1-9]", data):
+                raise Refused("document type does not match RTF content")
+            rtf = importlib.import_module("striprtf.striprtf")
+            text = _bounded_text(rtf.rtf_to_text(data.decode("latin-1")), config["max_chars"])
+        names = [f"page-{number}.png" for number in chosen]
+        if config["format"] != "images":
+            names = ["document.md" if config["format"] == "markdown" else "document.txt"]
+            Path(names[0]).write_text(text, encoding="utf-8")
+        sizes = [Path(name).stat().st_size for name in names]
+        if any(size > MAX_OUTPUT_BYTES for size in sizes):
+            raise Refused("max_output_file_bytes exceeded")
+        if sum(sizes) > MAX_OUTPUT_TOTAL - MAX_METADATA_BYTES:
+            raise Refused("max_output_total_bytes exceeded")
+        metadata.update(
+            pages=count,
+            selected_pages=chosen,
+            characters=len(text),
+            verdict="extracted",
+            range_clamped=bool(
+                count is not None and config["pages"] and config["pages"][1] > count
+            ),
+            files=names,
+        )
+    except Refused as exc:
+        metadata["reason"] = str(exc)[:MAX_DIAGNOSTIC]
+    return metadata
+
+
+def main() -> int:
+    """Keep parser errors guest-derived and reserve exit 2 for a definitive refusal."""
+    config = json.loads(Path("request.json").read_text("utf-8"))
+    metadata: dict[str, Any]
+    try:
+        data = Path("input.bin").read_bytes()
+        metadata = convert(data, config)
+    except ImportError:
+        print("document converter dependencies are unavailable", file=sys.stderr)
+        return 3
+    except (
+        ValueError,
+        RuntimeError,
+        KeyError,
+        IndexError,
+        zipfile.BadZipFile,
+        zlib.error,
+        ET.ParseError,
+        xml.parsers.expat.ExpatError,
+    ) as exc:
+        metadata = {
+            "schema_version": 1,
+            "verdict": "refused",
+            "reason": f"invalid document: {exc}"[:2000],
+            "pages": None,
+            "selected_pages": [],
+            "characters": 0,
+            "truncated": False,
+            "range_clamped": False,
+            "supported_formats": [],
+            "format": config["format"],
+            "media_type": MEDIA_TYPES.get(config["kind"]),
+            "files": [],
+        }
+    Path("document.json").write_text(json.dumps(metadata, ensure_ascii=True), encoding="utf-8")
+    if metadata["verdict"] == "refused":
+        print(metadata["reason"], file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maf_sandbox_document/_pdf_guard.py

@@ -0,0 +1,362 @@
+"""Bound supported PDF streams before PDFium sees the document.
+
+Only a single classic cross-reference table and losslessly encoded streams are admitted.
+Unsupported structures are refused rather than passed to a second, less bounded parser.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import zlib
+from typing import Any, cast
+
+MAX_STREAM_BYTES = 32 * 1024 * 1024
+MAX_STREAM_TOTAL = 64 * 1024 * 1024
+MAX_OBJECTS = 100_000
+_SPACE = b"\x00\t\n\f\r "
+_DELIMITERS = _SPACE + b"()<>[]{}/%"
+_LINE_END = re.compile(rb"[\r\n]")
+
+
+class Refused(ValueError):
+    """The document exceeds a guard or uses an unsupported structure."""
+
+
+class _Tokens:
+    def __init__(self, data: bytes) -> None:
+        self.data = data
+        self.pos = 0
+        self.count = 0
+
+    def space(self) -> None:
+        while self.pos < len(self.data):
+            if self.data[self.pos] in _SPACE:
+                self.pos += 1
+            elif self.data[self.pos] == 37:
+                end = _LINE_END.search(self.data, self.pos)
+                self.pos = end.end() if end else len(self.data)
+            else:
+                break
+
+    def word(self) -> bytes:
+        self.space()
+        start = self.pos
+        while self.pos < len(self.data) and self.data[self.pos] not in _DELIMITERS:
+            self.pos += 1
+        if start == self.pos:
+            raise Refused("unsupported PDF syntax")
+        return self.data[start : self.pos]
+
+    def value(self, depth: int = 0) -> Any:
+        self.count += 1
+        if depth > 32 or self.count > 1_000_000:
+            raise Refused("max_pdf_structure exceeded")
+        self.space()
+        data, start = self.data, self.pos
+        if data[start : start + 2] == b"<<":
+            self.pos += 2
+            result: dict[bytes, Any] = {}
+            while True:
+                self.space()
+                if data[self.pos : self.pos + 2] == b">>":
+                    self.pos += 2
+                    return result
+                key = self.value(depth + 1)
+                if not isinstance(key, bytes) or not key.startswith(b"/") or key in result:
+                    raise Refused("unsupported PDF dictionary")
+                result[key] = self.value(depth + 1)
+        if data[start : start + 1] == b"[":
+            self.pos += 1
+            values: list[Any] = []
+            while True:
+                self.space()
+                if data[self.pos : self.pos + 1] == b"]":
+                    self.pos += 1
+                    return values
+                values.append(self.value(depth + 1))
+        if data[start : start + 1] == b"/":
+            self.pos += 1
+            name_start = self.pos
+            while self.pos < len(data) and data[self.pos] not in _DELIMITERS:
+                self.pos += 1
+            name = data[name_start : self.pos]
+            if re.search(rb"#(?![0-9a-fA-F]{2})", name):
+                raise Refused("unsupported PDF name")
+            return b"/" + re.sub(rb"#([0-9a-fA-F]{2})", lambda m: bytes([int(m[1], 16)]), name)
+        if data[start : start + 1] == b"(":
+            self.pos += 1
+            nesting = 1
+            while self.pos < len(data) and nesting:
+                char = data[self.pos]
+                self.pos += 1
+                if char == 92:
+                    self.pos += 1
+                elif char == 40:
+                    nesting += 1
+                elif char == 41:
+                    nesting -= 1
+            if nesting or self.pos > len(data):
+                raise Refused("invalid PDF string")
+            return None
+        if data[start : start + 1] == b"<":
+            end = data.find(b">", start + 1)
+            if end < 0 or re.search(
+                rb"[^0-9a-fA-F]", data[start + 1 : end].translate(None, _SPACE)
+            ):
+                raise Refused("invalid PDF hex string")
+            self.pos = end + 1
+            return None
+        word = self.word()
+        if re.fullmatch(rb"[+-]?\d+", word):
+            number = int(word)
+            saved = self.pos
+            try:
+                generation = self.word()
+                if generation.isdigit() and self.word() == b"R":
+                    return (number, int(generation))
+            except Refused:
+                # Failed lookahead leaves a plain integer, not an indirect reference.
+                pass
+            self.pos = saved
+            return number
+        if word in (b"true", b"false", b"null") or re.fullmatch(rb"[+-]?(?:\d+\.\d*|\.\d+)", word):
+            return None
+        raise Refused("unsupported PDF value")
+
+
+def _decode(data: bytes, filters: Any) -> bytes:
+    if filters is None:
+        filters = []
+    elif isinstance(filters, bytes):
+        filters = [filters]
+    if not isinstance(filters, list) or len(cast(list[Any], filters)) > 4:
+        raise Refused("unsupported PDF stream filter")
+    for filter_name in cast(list[Any], filters):
+        if filter_name in (b"/FlateDecode", b"/Fl"):
+            decoder = zlib.decompressobj()
+            data = decoder.decompress(data, MAX_STREAM_BYTES + 1)
+            if len(data) > MAX_STREAM_BYTES or decoder.unconsumed_tail:
+                raise Refused("max_pdf_stream_bytes exceeded")
+            if not decoder.eof or decoder.unused_data:
+                raise Refused("invalid PDF compressed stream")
+        elif filter_name in (b"/ASCII85Decode", b"/A85"):
+            # PDFium stops decoding at these otherwise legal PDF whitespace bytes.
+            if b"\x00" in data or b"\f" in data:
+                raise Refused("unsupported PDF ASCII85 whitespace")
+            raw = data.translate(None, _SPACE).removesuffix(b"~>")
+            zeros = raw.count(b"z")
+            groups, remainder = divmod(len(raw) - zeros, 5)
+            if 4 * (zeros + groups) + max(0, remainder - 1) > MAX_STREAM_BYTES:
+                raise Refused("max_pdf_stream_bytes exceeded")
+            data = base64.a85decode(raw, adobe=False, ignorechars=_SPACE)
+        elif filter_name in (b"/ASCIIHexDecode", b"/AHx"):
+            raw = data.translate(None, _SPACE)
+            if not raw.endswith(b">"):
+                raise Refused("invalid PDF hex stream")
+            raw = raw[:-1]
+            data = bytes.fromhex((raw + (b"0" if len(raw) % 2 else b"")).decode("ascii"))
+        else:
+            raise Refused("unsupported PDF stream filter")
+        if len(data) > MAX_STREAM_BYTES:
+            raise Refused("max_pdf_stream_bytes exceeded")
+    return data
+
+
+def _has_inline_image(data: bytes) -> bool:
+    tokens = _Tokens(data)
+    while tokens.pos < len(data):
+        tokens.space()
+        start = tokens.pos
+        if data[start : start + 1] in (b"(", b"/", b"<", b"["):
+            tokens.value()
+        elif start < len(data) and data[start] not in _DELIMITERS:
+            word = tokens.word()
+            if re.fullmatch(rb"[+\-0-9.]*BI", word):
+                return True
+        else:
+            tokens.pos += 1
+    return False
+
+
+def check_pdf(data: bytes) -> None:
+    """Refuse unbounded, encrypted, incremental or ambiguous PDF input before native parsing."""
+    if not re.match(rb"%PDF-1\.[0-7][\r\n]", data):
+        raise Refused("unsupported PDF header")
+    end = re.search(rb"startxref\s+(\d+)\s+%%EOF\s*$", data)
+    if end is None:
+        raise Refused("invalid PDF cross-reference")
+    offset = int(end[1])
+    table = _Tokens(data[offset : end.start()])
+    if table.word() != b"xref":
+        raise Refused("unsupported PDF cross-reference stream")
+    entries: dict[int, tuple[int, int]] = {}
+    declared: set[int] = set()
+    while True:
+        first = table.word()
+        if first == b"trailer":
+            break
+        count = table.word()
+        if not first.isdigit() or not count.isdigit():
+            raise Refused("invalid PDF cross-reference")
+        start, size = int(first), int(count)
+        if size > MAX_OBJECTS or len(declared) + size > MAX_OBJECTS:
+            raise Refused("max_pdf_objects exceeded")
+        for number in range(start, start + size):
+            position, generation, state = table.word(), table.word(), table.word()
+            if number in declared or not position.isdigit() or not generation.isdigit():
+                raise Refused("invalid PDF cross-reference")
+            declared.add(number)
+            if state == b"n":
+                entries[number] = (int(position), int(generation))
+            elif state != b"f":
+                raise Refused("invalid PDF cross-reference")
+    trailer = table.value()
+    table.space()
+    if (
+        not isinstance(trailer, dict)
+        or any(key in trailer for key in (b"/Prev", b"/XRefStm", b"/Encrypt"))
+        or table.pos != len(table.data)
+    ):
+        raise Refused("unsupported PDF trailer")
+    positions = sorted((pos, number, gen) for number, (pos, gen) in entries.items())
+    prefix = _Tokens(data[: positions[0][0]] if positions else data[:offset])
+    prefix.space()
+    if prefix.pos != len(prefix.data):
+        raise Refused("unindexed PDF object")
+    objects: dict[tuple[int, int], Any] = {}
+    streams: dict[tuple[int, int], tuple[dict[bytes, Any], bytes]] = {}
+    for index, (pos, number, generation) in enumerate(positions):
+        stop = positions[index + 1][0] if index + 1 < len(positions) else offset
+        if not 0 < pos < stop <= offset:
+            raise Refused("invalid PDF object offset")
+        tokens = _Tokens(data[pos:stop])
+        if tokens.word() != str(number).encode() or tokens.word() != str(generation).encode():
+            raise Refused("invalid PDF object identity")
+        if tokens.word() != b"obj":
+            raise Refused("invalid PDF object")
+        value = tokens.value()
+        objects[(number, generation)] = value
+        following = tokens.word()
+        if following == b"stream" and isinstance(value, dict):
+            value = cast(dict[bytes, Any], value)
+            if value.get(b"/Type") in (b"/ObjStm", b"/XRef"):
+                raise Refused("unsupported PDF object stream")
+            tail = tokens.data[tokens.pos :]
+            if not tail.startswith((b"\r\n", b"\n")):
+                raise Refused("invalid PDF stream delimiter")
+            tail = tail[2:] if tail.startswith(b"\r\n") else tail[1:]
+            streams[(number, generation)] = (value, tail)
+        else:
+            tokens.space()
+            if following != b"endobj" or tokens.pos != len(tokens.data):
+                raise Refused("invalid PDF object ending")
+
+    def check_references(value: Any) -> None:
+        if isinstance(value, tuple):
+            if cast(tuple[int, int], value) not in objects:
+                raise Refused("unresolved PDF reference")
+        elif isinstance(value, dict):
+            for nested in cast(dict[bytes, Any], value).values():
+                check_references(nested)
+        elif isinstance(value, list):
+            for nested in cast(list[Any], value):
+                check_references(nested)
+
+    for value in objects.values():
+        check_references(value)
+    check_references(trailer)
+    root_reference = cast(dict[bytes, Any], trailer).get(b"/Root")
+    if not isinstance(root_reference, tuple):
+        raise Refused("invalid PDF catalog reference")
+    root = objects.get(cast(tuple[int, int], root_reference))
+    if not isinstance(root, dict) or cast(dict[bytes, Any], root).get(b"/Type") != b"/Catalog":
+        raise Refused("invalid PDF catalog")
+    total = 0
+    decoded_streams: dict[tuple[int, int], bytes] = {}
+    for identity, (info, tail) in streams.items():
+        length = info.get(b"/Length")
+        if isinstance(length, tuple):
+            length = objects.get(cast(tuple[int, int], length))
+        if type(length) is not int or not 0 <= length <= MAX_STREAM_BYTES:
+            raise Refused("max_pdf_stream_bytes exceeded")
+        rest = _Tokens(tail[length:])
+        if rest.word() != b"endstream" or rest.word() != b"endobj":
+            raise Refused("invalid PDF stream length")
+        rest.space()
+        if rest.pos != len(rest.data) or info.get(b"/DecodeParms") is not None:
+            raise Refused("unsupported PDF stream parameters")
+        if any(key in info for key in (b"/F", b"/FFilter", b"/FDecodeParms")):
+            raise Refused("external PDF streams are refused")
+        decoded = _decode(tail[:length], info.get(b"/Filter"))
+        total += len(decoded)
+        if total > MAX_STREAM_TOTAL:
+            raise Refused("max_pdf_stream_total exceeded")
+        decoded_streams[identity] = decoded
+
+    lookups = 0
+
+    def resolve(value: Any, depth: int = 0) -> Any:
+        nonlocal lookups
+        lookups += 1
+        if depth > 32 or lookups > MAX_OBJECTS * 10:
+            raise Refused("max_pdf_structure exceeded")
+        if isinstance(value, tuple):
+            return resolve(objects[cast(tuple[int, int], value)], depth + 1)
+        return value
+
+    def content(value: Any, depth: int = 0) -> list[bytes]:
+        nonlocal lookups
+        lookups += 1
+        if depth > 32 or lookups > MAX_OBJECTS * 10:
+            raise Refused("max_pdf_structure exceeded")
+        if isinstance(value, tuple):
+            reference = cast(tuple[int, int], value)
+            if reference in decoded_streams:
+                return [decoded_streams[reference]]
+            return content(objects[reference], depth + 1)
+        if isinstance(value, list):
+            return [chunk for item in cast(list[Any], value) for chunk in content(item, depth + 1)]
+        if value is None:
+            return []
+        raise Refused("invalid PDF content reference")
+
+    groups: list[list[bytes]] = []
+    for identity, (info, _) in streams.items():
+        if resolve(info.get(b"/Subtype")) == b"/Form" or resolve(info.get(b"/PatternType")) == 1:
+            groups.append([decoded_streams[identity]])
+    pending = list(objects.values())
+    while pending:
+        value = pending.pop()
+        if isinstance(value, list):
+            pending.extend(cast(list[Any], value))
+        if not isinstance(value, dict):
+            continue
+        info = cast(dict[bytes, Any], value)
+        pending.extend(info.values())
+        if resolve(info.get(b"/Type")) == b"/Page":
+            groups.append(content(info.get(b"/Contents")))
+        procedures = resolve(info.get(b"/CharProcs"))
+        if isinstance(procedures, dict):
+            groups.extend(content(item) for item in cast(dict[bytes, Any], procedures).values())
+        appearances = resolve(info.get(b"/AP"))
+        if isinstance(appearances, dict):
+            for key in (b"/N", b"/R", b"/D"):
+                appearance = cast(dict[bytes, Any], appearances).get(key)
+                if isinstance(appearance, tuple) and appearance in decoded_streams:
+                    groups.append(content(appearance))
+                else:
+                    states = resolve(appearance)
+                    if isinstance(states, dict):
+                        groups.extend(
+                            content(item) for item in cast(dict[bytes, Any], states).values()
+                        )
+                    elif states is not None:
+                        raise Refused("invalid PDF appearance reference")
+    scanned = 0
+    for chunks in groups:
+        scanned += sum(map(len, chunks))
+        if scanned > MAX_STREAM_TOTAL:
+            raise Refused("max_pdf_content_total exceeded")
+        if _has_inline_image(b"".join(chunks)):
+            raise Refused("inline PDF images are refused")

maf_sandbox_document/_tool.py

@@ -0,0 +1,344 @@
+"""Document reads through core's labelled store, call isolation and bounded output delivery."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import math
+import re
+from collections.abc import Awaitable, Callable
+from importlib.resources import files
+from pathlib import PurePosixPath
+from typing import Any, cast
+
+from maf_sandbox import (
+    CallerContext,
+    Capability,
+    Cleanup,
+    DeclaredOutput,
+    Egress,
+    FileStoreProvenance,
+    Isolation,
+    IsolationScope,
+    OsFamily,
+    OutputSink,
+    SandboxRouter,
+    SandboxSpec,
+    SourceIntegrity,
+    TransferLimits,
+    collect_outputs,
+)
+from maf_sandbox.maf import SandboxResult, SandboxToolSession, sandboxed_tool
+
+from ._guest import (
+    MAX_DIAGNOSTIC,
+    MAX_INPUT_BYTES,
+    MAX_METADATA_BYTES,
+    MAX_OUTPUT_BYTES,
+    MAX_OUTPUT_TOTAL,
+    selected_pages,
+)
+
+DOCUMENT_KIND = "document"
+DOCUMENT_READ_TOOL_NAME = "document_read"
+_LOGGER = logging.getLogger(__name__)
+
+
+def document_sandbox_spec(image: str | None = None) -> SandboxSpec:
+    """Require a disposable, isolated POSIX guest with closed egress for every document."""
+    return SandboxSpec(
+        kind=DOCUMENT_KIND,
+        image=image,
+        work_dir="/maf-sandbox/work",
+        requires=frozenset({Capability.EXEC, Capability.FILES_IN, Capability.FILES_OUT}),
+        requires_os_family=OsFamily.POSIX,
+        egress=Egress.CLOSED,
+        min_isolation=Isolation.CONTAINER,
+        isolation_scope=IsolationScope.CALL,
+        min_cleanup=Cleanup.DISPOSE,
+        confined_to_guest_call_path=False,
+        outputs_named_at_call_time=True,
+        files_in=TransferLimits(
+            max_bytes_per_file=MAX_INPUT_BYTES,
+            max_total_bytes=MAX_INPUT_BYTES + 256 * 1024,
+            max_files=4,
+        ),
+        files_out=TransferLimits(
+            max_bytes_per_file=MAX_OUTPUT_BYTES,
+            max_total_bytes=MAX_OUTPUT_TOTAL,
+            max_files=101,
+        ),
+    )
+
+
+def make_document_tools(
+    router: SandboxRouter | None,
+    file_store: Any,
+    agent_id: str,
+    context: CallerContext,
+    sink: OutputSink,
+    *,
+    image: str | None = None,
+    exec_timeout_seconds: float = 60,
+    max_pages: int = 200,
+    max_chars: int = 1_000_000,
+    image_dpi: int = 96,
+    max_image_pixels: int = 16_000_000,
+    max_image_pages: int = 20,
+    formats: tuple[str, ...] = ("text", "markdown", "images"),
+    file_store_provenance: FileStoreProvenance | None = None,
+    requires_file_integrity: SourceIntegrity | None = None,
+) -> list[Any]:
+    """Attach document_read(file, format, pages) to a store whose read returns bytes.
+
+    The context supplies the authorized listing. The host selects all limits and the output
+    sink; the model selects one listed document and a 1-based inclusive page/slide range.
+    """
+    if (
+        type(exec_timeout_seconds) not in (int, float)
+        or not math.isfinite(exec_timeout_seconds)
+        or not 0 < exec_timeout_seconds <= 300
+    ):
+        raise ValueError("exec_timeout_seconds must be finite and in (0, 300]")
+    settings = {
+        "max_pages": max_pages,
+        "max_chars": max_chars,
+        "image_dpi": image_dpi,
+        "max_image_pixels": max_image_pixels,
+        "max_image_pages": max_image_pages,
+    }
+    ceilings = {
+        "max_pages": 10_000,
+        "max_chars": 8_000_000,
+        "image_dpi": 600,
+        "max_image_pixels": 32_000_000,
+        "max_image_pages": 100,
+    }
+    for name, value in settings.items():
+        if type(value) is not int or not 1 <= value <= ceilings[name]:
+            raise ValueError(f"{name} must be an integer in [1, {ceilings[name]}]")
+    if (
+        not isinstance(cast(object, formats), tuple)
+        or not formats
+        or any(value not in ("text", "markdown", "images") for value in formats)
+        or len(set(formats)) != len(formats)
+    ):
+        raise ValueError("formats must be a nonempty tuple of distinct text, markdown or images")
+    return sandboxed_tool(
+        lambda session: _build_tool(
+            session, file_store, sink, settings, formats, exec_timeout_seconds
+        ),
+        router=router,
+        agent_id=agent_id,
+        context=context,
+        spec=document_sandbox_spec(image),
+        name=DOCUMENT_READ_TOOL_NAME,
+        approval_mode="never_require",
+        source_integrity=SourceIntegrity.UNTRUSTED,
+        result_contract=True,
+        verdicts=("extracted", "refused"),
+        output_sink=sink,
+        file_store_provenance=file_store_provenance,
+        requires_file_integrity=requires_file_integrity,
+        admission_timeout=max(30, exec_timeout_seconds),
+        logger=_LOGGER,
+    )
+
+
+def _stopped(sentence: str) -> SandboxResult:
+    return SandboxResult(completed=False, trusted_output=(sentence,))
+
+
+def _outputs(
+    data: bytes, request: dict[str, Any], call_id: str, refused: bool
+) -> tuple[DeclaredOutput, ...]:
+    manifest = json.loads(data)
+    if not isinstance(manifest, dict):
+        raise ValueError("invalid document metadata")
+    manifest = cast(dict[str, Any], manifest)
+    if (
+        set(manifest)
+        != {
+            "schema_version",
+            "media_type",
+            "format",
+            "supported_formats",
+            "pages",
+            "selected_pages",
+            "characters",
+            "truncated",
+            "range_clamped",
+            "verdict",
+            "reason",
+            "files",
+        }
+        or type(manifest.get("schema_version")) is not int
+        or manifest.get("schema_version") != 1
+        or manifest.get("verdict") != ("refused" if refused else "extracted")
+        or manifest.get("truncated") is not False
+        or manifest.get("format") != request["format"]
+        or type(manifest.get("characters")) is not int
+        or not 0 <= manifest["characters"] <= request["max_chars"]
+        or type(manifest.get("range_clamped")) is not bool
+        or (not refused and manifest.get("reason") is not None)
+        or (refused and not isinstance(manifest.get("reason"), str))
+    ):
+        raise ValueError("invalid document metadata")
+    names: list[str] = []
+    if not refused:
+        count = manifest.get("pages")
+        if request["kind"] in ("pdf", "pptx"):
+            if type(count) is not int or not 1 <= count <= request["max_pages"]:
+                raise ValueError("invalid page count")
+            chosen = selected_pages(count, request["pages"])
+        else:
+            if count is not None:
+                raise ValueError("invalid pagination")
+            chosen = []
+        if manifest.get("selected_pages") != chosen:
+            raise ValueError("invalid selected pages")
+        if request["format"] == "images":
+            if request["kind"] != "pdf" or len(chosen) > request["max_image_pages"]:
+                raise ValueError("invalid image output")
+            names = [f"page-{number}.png" for number in chosen]
+        else:
+            names = ["document.md" if request["format"] == "markdown" else "document.txt"]
+    if manifest.get("files") != names:
+        raise ValueError("invalid output manifest")
+    media = {
+        ".png": "image/png",
+        ".txt": "text/plain",
+        ".md": "text/markdown",
+        ".json": "application/json",
+    }
+    return tuple(
+        DeclaredOutput(
+            path=f"{call_id}/{name}", name=name, media_type=media[PurePosixPath(name).suffix]
+        )
+        for name in [*names, "document.json"]
+    )
+
+
+def _build_tool(
+    session: SandboxToolSession,
+    store: Any,
+    sink: OutputSink,
+    settings: dict[str, int],
+    formats: tuple[str, ...],
+    timeout: float,
+) -> Callable[..., Awaitable[SandboxResult]]:
+    programs = {
+        name: files("maf_sandbox_document").joinpath(name).read_text("utf-8")
+        for name in ("_guest.py", "_pdf_guard.py")
+    }
+
+    async def document_read(
+        file: str, format: str = "text", pages: str | None = None
+    ) -> SandboxResult:
+        """Read one listed PDF, DOCX, PPTX or RTF as text, Markdown or PDF page PNGs.
+
+        pages is a 1-based inclusive range such as "2-5" or "3", clamped to the available
+        pages or slides. DOCX ranges are refused; RTF ignores pages. Unsupported formats
+        and documents exceeding a cap are refused. Output includes document.json metadata.
+        """
+        if not isinstance(cast(object, file), str) or not file or format not in formats:
+            return _stopped("Error: choose one listed file and an enabled output format")
+        page_range = None
+        if pages is not None:
+            if not isinstance(cast(object, pages), str) or not re.fullmatch(
+                r"[1-9][0-9]{0,8}(-[1-9][0-9]{0,8})?", pages
+            ):
+                return _stopped("Error: pages must be a positive 1-based inclusive range")
+            ends = [int(part) for part in pages.split("-")]
+            page_range = [ends[0], ends[-1]]
+            if page_range[0] > page_range[1]:
+                return _stopped("Error: pages must be an ascending range")
+        listing = await session.list_files(store)
+        if isinstance(listing, str):
+            return _stopped(listing)
+        matches = [item for item in listing if item.name == file]
+        if len(matches) != 1:
+            return _stopped("Error: file must name exactly one visible stored document")
+        item = await session.read_file(store, matches[0], at="file", hidden=True)
+        if isinstance(item, str):
+            return _stopped(item)
+        if item is None or item.uri is None or not item.uri.startswith("data:"):
+            return _stopped("Error: the document store must return binary bytes")
+        try:
+            encoded = item.uri.split(",", 1)[1]
+            if len(encoded) > (MAX_INPUT_BYTES + 2) // 3 * 4:
+                return _stopped("Error: max_input_bytes exceeded")
+            data = base64.b64decode(encoded, validate=True)
+        except (ValueError, IndexError):
+            return _stopped("Error: the document store returned invalid binary content")
+        if len(data) > MAX_INPUT_BYTES:
+            return _stopped("Error: max_input_bytes exceeded")
+        key = session.key()
+        if isinstance(key, str):
+            return _stopped(key)
+        sandbox = await session.acquire(key)
+        if isinstance(sandbox, str):
+            return _stopped(sandbox)
+        guest_directory = session.guest_call_path()
+        call_id = guest_directory.rsplit("/", 1)[-1]
+        request = dict(
+            settings,
+            kind=PurePosixPath(file).suffix.lower().removeprefix("."),
+            format=format,
+            pages=page_range,
+        )
+        try:
+            await sandbox.write_file("input.bin", data, working_directory=guest_directory)
+            await sandbox.write_file(
+                "request.json", json.dumps(request), working_directory=guest_directory
+            )
+            for name, program in programs.items():
+                await sandbox.write_file(name, program, working_directory=guest_directory)
+            result = await sandbox.exec(
+                ["python3", "-I", "_guest.py"], working_directory=guest_directory, timeout=timeout
+            )
+        except TimeoutError:
+            return _stopped(f"Error: document conversion timed out after {timeout:g}s")
+        except Exception:
+            _LOGGER.warning("document_read: staging or execution failed", exc_info=True)
+            return _stopped("Error: could not run the document converter")
+        if result.exit_code not in (0, 2):
+            diagnostic = result.stdout if result.producer_owns_stderr else result.stderr
+            return SandboxResult(
+                completed=False,
+                trusted_output=("Error: document conversion did not complete",),
+                output=(diagnostic[:MAX_DIAGNOSTIC],),
+            )
+        refused = result.exit_code == 2
+        try:
+            metadata = await sandbox.read_file(
+                "document.json", working_directory=guest_directory, max_bytes=MAX_METADATA_BYTES
+            )
+            outputs = _outputs(metadata, request, call_id, refused)
+            landed = await collect_outputs(
+                sandbox,
+                session.spec,
+                sink=sink,
+                outputs=outputs,
+                call_id=call_id,
+                observer=session.observer,
+                key=key,
+            )
+            if len(landed) != len(outputs):
+                return _stopped("Error: not every document output was delivered")
+        except Exception:
+            _LOGGER.warning("document_read: output delivery failed", exc_info=True)
+            return _stopped("Error: document output verification or delivery failed")
+        diagnostic = result.stdout if result.producer_owns_stderr else result.stderr
+        return SandboxResult(
+            completed=True,
+            verdict="refused" if refused else "extracted",
+            output=tuple(item.display for item in landed)
+            + ((diagnostic[:MAX_DIAGNOSTIC],) if refused else ()),
+        )
+
+    document_read.__doc__ = (
+        f"{document_read.__doc__}\nEnabled output formats: {', '.join(formats)}."
+    )
+    return document_read

maf_sandbox_document/py.typed

@@ -0,0 +1 @@
+

maf_sandbox_document-0.2.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: maf-sandbox-document
+Version: 0.2.0
+Summary: Guarded PDF, DOCX, PPTX and RTF extraction in disposable sandboxes.
+Keywords: document,pdf,sandbox,agent-framework
+Author: SOKOLAI BV
+Author-email: SOKOLAI BV <info@sokolai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Dist: maf-sandbox>=0.52.0,<0.53
+Requires-Dist: agent-framework-core>=1.23.0,<1.24
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://www.sokol.ai
+Project-URL: Source, https://github.com/sokolaidev/maf-extensions
+Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
+Description-Content-Type: text/markdown
+
+# maf-sandbox-document
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-document)](https://pypi.org/project/maf-sandbox-document/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-document)](https://pypi.org/project/maf-sandbox-document/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-document/LICENSE)
+
+> **Experimental.** Releases before 1.0 may change or remove APIs. Importing this package emits `MafSandboxDocumentExperimentalWarning`.
+
+Read PDF, DOCX, PPTX and RTF files through a fixed converter in a disposable sandbox. The model chooses a listed file, output format and optional page range; it supplies no converter code. Parsers and archive/XML guards run in the guest.
+
+This package is experimental and not yet published. Its first release requires the core release containing binary file-store reads; release core before this package. The image must also have a completed, currently eligible `document` release before the kind publishes.
+
+## Attach the tool
+
+```python
+from maf_sandbox_document import make_document_tools
+
+[document_read] = make_document_tools(
+    router,
+    file_store,
+    "document-reader",
+    context,
+    sink,
+    image=verified_document_image,
+    formats=("text", "markdown"),  # Enable images only for a host that can consume them.
+)
+```
+
+The host supplies a store with `async read(name) -> bytes | None`, and `context.list_files(store)` returns authorized `ListedFile` entries. Text-only AgentFileStore implementations need a binary adapter. Names are matched exactly, never interpreted as host paths, guest paths or URLs. The host must bound ingress bytes before the store returns them; the kind independently checks its 16 MiB input limit.
+
+Use `file_store_provenance` for stores that may change during a call and `requires_file_integrity` when admission requires an established source label. Completion and the `extracted`/`refused` verdict are trusted. Document text, metadata, images, delivery references and converter diagnostics are guest-derived output. Core derives their effective label from the file read, model arguments and conversation.
+
+The router must allow at least container isolation and supply POSIX `EXEC`, `FILES_IN` and `FILES_OUT` with closed egress. Every call requires its own sandbox and disposal, including refusal, failure and cancellation.
+
+## Tool contract
+
+`document_read(file, format="text", pages=None)` accepts `text`, `markdown` or `images`. `pages` is a positive, 1-based inclusive range such as `"2-5"` or `"3"`. PDF ranges select pages; PPTX ranges select slides. Both endpoints clamp to the available last page. DOCX has no reliable pagination without a layout engine, so an explicit range is refused. RTF ignores ranges.
+
+| Input | Text / Markdown | Images | Limits |
+|---|---|---|---|
+| PDF | PDFium text in reading order; Markdown retains that text | PNG pages at the host's fixed DPI | Supported PDF subset below; no OCR |
+| DOCX | Mammoth text or Markdown conversion | Refused | No pagination or faithful layout |
+| PPTX | Slide text, table cells and notes; Markdown slide headings | Refused | No office renderer |
+| RTF (`application/rtf`, `text/rtf`) | striprtf text, also usable as plain Markdown | Refused | Page range ignored |
+
+Outputs are `document.txt` (`text/plain`), `document.md` (`text/markdown`) or `page-N.png` (`image/png`), plus `document.json` (`application/json`). Image names preserve original page numbers. An extracted verdict requires delivery of every requested output. Guard refusals deliver only the metadata and diagnostic. Invalid arguments, missing files, acquisition failures, timeouts, operational exits and incomplete delivery return `completed=False` with no verdict.
+
+Metadata schema version 1 contains `media_type`, `format`, `supported_formats`, `pages` (a page/slide count, or null), `selected_pages`, `characters`, `truncated` (always false), `range_clamped`, `verdict`, `reason` and `files`. A refusal never represents capped content as a successful extraction.
+
+## Host options and guards
+
+| Option | Default | Allowed |
+|---|---|---|
+| `exec_timeout_seconds` | 60 | Finite number greater than 0, at most 300 |
+| `max_pages` | 200 | 1–10,000 |
+| `max_chars` | 1,000,000 | 1–8,000,000 |
+| `image_dpi` | 96 | 1–600 |
+| `max_image_pixels` | 16,000,000 | 1–32,000,000 per page |
+| `max_image_pages` | 20 | 1–100 per call |
+| `formats` | text, markdown, images | Nonempty tuple of distinct enabled formats |
+
+OOXML is checked before Mammoth or python-pptx opens it: at most 2,048 ZIP entries, 16 MiB per expanded member, 64 MiB total, and a declared expansion ratio at most 200. Absolute/traversing/duplicate names, symlinks, encryption, unsupported compression and nested archives are refused. Bounded decompression verifies stream completion, actual lengths and CRCs independently of declared member sizes; converters receive a rebuilt, stored-only ZIP. XML preflight refuses DTDs and entity declarations, including UTF-16 declarations and XML in nonstandard member names. python-pptx uses a parser with entity resolution, DTD loading and network access disabled. Mammoth's pinned minidom path receives only the preflighted XML; external file access and embedded style maps are disabled.
+
+PDF preflight admits a single classic cross-reference table, bounded objects and streams with no compression, Flate, ASCII85 or ASCIIHex. Each decoded stream is at most 32 MiB, with 64 MiB total. Drawing syntax is checked in page content, forms, annotation appearances, tiling patterns and Type 3 glyph programs, with at most 64 MiB of content including repeated uses; binary image and font bytes are not interpreted as drawing commands. Object/cross-reference streams, incremental or encrypted PDFs, external streams, inline images, other filters (including JPEG/JPEG2000) and decoding parameters are refused. ASCII85 streams containing NUL or form-feed whitespace are also refused because the pinned PDFium decoder stops at those bytes. This deliberately restricts compatibility: PDFium has no public per-stream allocation limit, so unsupported structures are not passed to it. A host can prepare an accepted PDF before ingress; this kind never silently falls back to an unbounded parser. Text is capped at 100,000 characters per PDF page or PPTX slide as well as the configured total.
+
+Outputs are capped at 32 MiB per file and 64 MiB total including metadata, independently of backend transfer limits. The execution deadline covers preflight and conversion together. Backend resource limits remain necessary for native parser allocations, CPU and temporary storage; these guards do not establish immunity to parser exploits.
+
+See the [document contract](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/kinds/document.md) and [image guide](https://github.com/sokolaidev/maf-extensions/blob/main/images/document-sandbox/README.md) for verification and release evidence.

maf_sandbox_document-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+maf_sandbox_document/__init__.py,sha256=WZf0ySMb3Oa4dk-xBs7_FWUUWbISJ-phvLOosiJtREc,829
+maf_sandbox_document/_guest.py,sha256=LjEEns9fprgSLsSWQCIEKO2-Gm_hNXjcut3kYdGT3hc,16626
+maf_sandbox_document/_pdf_guard.py,sha256=EQ7eptdB82_eLVeycU02i-vvLNbqFGKrmdth-TNNbqs,15447
+maf_sandbox_document/_tool.py,sha256=TVAusS3F6mNgCMi66ZurwsEJbWwsUAQvWSLuSVNq-Yw,13190
+maf_sandbox_document/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+maf_sandbox_document-0.2.0.dist-info/licenses/LICENSE,sha256=CuJYlGnKM4A7I0_kdsEipKMk2vPYG1YyyZZMUDqYbOI,1067
+maf_sandbox_document-0.2.0.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
+maf_sandbox_document-0.2.0.dist-info/METADATA,sha256=j7bCYijY0aQYXtYfeL2oZJRelSm0os2kq5miRTOwAJc,8027
+maf_sandbox_document-0.2.0.dist-info/RECORD,,

maf_sandbox_document-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.6
+Root-Is-Purelib: true
+Tag: py3-none-any

maf_sandbox_document-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOKOLAI BV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.