sillybos 0.1.0__py3-none-any.whl

sillybos/__init__.py

@@ -0,0 +1,49 @@
+"""sillybos: decide before decoding.
+
+A σίλλυβος (*sillybos*, Latin *sittybus*) was the little parchment tag that
+hung from a rolled scroll in an ancient library, giving its title and author
+so that a reader could tell what a scroll was without unrolling it. This
+library is that tag for the files a scanning or OCR pipeline is handed. It
+answers one narrow question before any image library or PDF renderer opens a
+file: *is this one of the formats I mean to read, within the limits I
+expect, and if not, why?*
+
+It reads the first bytes to learn what the file really is, whatever its name
+says; reads the header of a JPEG, PNG or TIFF with code of its own, never a
+decoder's; asks poppler's ``pdfinfo``, in a separate process, how many pages
+a PDF has and how large they are; and refuses, with a reason in plain words,
+anything outside a :class:`Policy`.
+
+>>> from sillybos import check
+>>> verdict = check("scan.png")          # doctest: +SKIP
+>>> verdict.ok, verdict.reasons          # doctest: +SKIP
+(False, ('says PNG, is PostScript',))
+
+The whole surface is :func:`check`, which returns a :class:`Verdict`;
+:func:`require`, which raises :class:`Refused` instead; :class:`Policy`,
+with the presets :data:`DEFAULT` and :data:`STRICT`; and, with the
+``[pillow]`` extra, :func:`sillybos.pillow.open_checked`.
+"""
+
+from __future__ import annotations
+
+from sillybos.check import Facts, Refused, Verdict, check, require
+from sillybos.policy import DEFAULT, FORMATS, STRICT, Policy
+
+try:
+    from sillybos._version import __version__
+except ImportError:  # pragma: no cover - only in a checkout that has not been built
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DEFAULT",
+    "FORMATS",
+    "STRICT",
+    "Facts",
+    "Policy",
+    "Refused",
+    "Verdict",
+    "__version__",
+    "check",
+    "require",
+]

sillybos/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

sillybos/check.py

@@ -0,0 +1,206 @@
+"""The check itself: one function, one verdict.
+
+:func:`check` runs the steps in the order that keeps the cheapest and safest
+first, and stops handing the file to anything further once it has a reason
+to refuse it:
+
+1. The file's size, from the file system. Over the limit, nothing reads it
+   but the sniff.
+2. Its first bytes, to name the format it really is. A format the policy
+   does not allow is refused by name, and no reader of ours runs on it.
+3. Whether its name agrees with its contents.
+4. Its header, with the reader for its format (ours for JPEG, PNG and TIFF;
+   ``pdfinfo`` in a separate process for PDF): dimensions, frames, pages.
+5. The policy's ceilings against what the header said.
+
+Every reason is a sentence an operator can act on, and the verdict carries
+all of them, not just the first.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from sillybos import headers, sniff
+from sillybos.pdf import pdf as read_pdf
+from sillybos.policy import DEFAULT, FORMATS, Policy
+
+
+@dataclass(frozen=True)
+class Facts:
+    """What was read from the file before any decoder saw it.
+
+    Attributes:
+        bytes: The file's size.
+        width: Pixels across the first page or frame; for a PDF, at the
+            policy's render dpi.
+        height: Pixels down, likewise.
+        pages: Pages in a PDF, frames in a TIFF or animated PNG, 1 otherwise.
+            For a file with more than the policy allows, the walk may have
+            stopped early: the number is then "more than" the limit.
+        max_pixels: The most pixels any one page or frame would decode to,
+            or ``None`` if the page count was over the limit and the sizes
+            were not read.
+        encrypted: Whether a PDF is encrypted. Always ``False`` for an image.
+        pages_exact: ``False`` when the frame walk stopped at the limit, so
+            ``pages`` is a floor, not a count.
+    """
+
+    bytes: int
+    width: int
+    height: int
+    pages: int
+    max_pixels: int | None
+    encrypted: bool = False
+    pages_exact: bool = True
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """The answer to "may a decoder open this file?".
+
+    Attributes:
+        path: The file.
+        ok: ``True`` if nothing was found against it.
+        format: What the file really is, from its contents: a name from
+            :data:`sillybos.FORMATS`, another name the library knows only
+            to refuse (``"postscript"``), or ``None`` for an unknown format.
+        claimed: What its extension says it is, or ``None`` if the extension
+            is not one the library maps.
+        facts: What the header said, or ``None`` if it was never read.
+        reasons: Why the file was refused, one sentence each. Empty when
+            ``ok``.
+    """
+
+    path: Path
+    ok: bool
+    format: str | None
+    claimed: str | None
+    facts: Facts | None
+    reasons: tuple[str, ...]
+
+    def __str__(self) -> str:
+        if self.ok:
+            return f"{self.path.name}: ok ({self.summary()})"
+        return f"{self.path.name}: refused. " + " ".join(r + "." for r in self.reasons)
+
+    def summary(self) -> str:
+        """One line of facts: ``"JPEG, 4000x6000, 1 page, 2.1 MB"``."""
+        parts = [sniff.describe(self.format)]
+        if self.facts is not None:
+            parts.append(f"{self.facts.width}x{self.facts.height}")
+            parts.append(f"{self.facts.pages} page{'s' if self.facts.pages != 1 else ''}")
+            parts.append(f"{self.facts.bytes / 1_000_000:.1f} MB")
+        return ", ".join(parts)
+
+
+class Refused(Exception):
+    """A file did not pass. Raised by :func:`require`; carries the :class:`Verdict`."""
+
+    def __init__(self, verdict: Verdict) -> None:
+        self.verdict = verdict
+        super().__init__(str(verdict))
+
+
+def check(path: str | os.PathLike[str], policy: Policy = DEFAULT) -> Verdict:
+    """Decide whether a decoder may open ``path``, without opening it with one.
+
+    Args:
+        path: The file to check. It must exist; a missing file is the
+            caller's error, not a verdict, and raises :class:`FileNotFoundError`.
+        policy: The limits to apply. :data:`sillybos.DEFAULT` if not given.
+
+    Returns:
+        A :class:`Verdict`. Never raises for anything found *in* the file:
+        a malformed header, a lying name and a page too large are all
+        reasons, not exceptions.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        sillybos.pdf.PdfInfoMissing: If the file is a PDF and ``pdfinfo``
+            is not installed.
+    """
+    path = Path(path)
+    size = path.stat().st_size
+    reasons: list[str] = []
+    claimed = sniff.claimed_by(path.suffix)
+
+    if size > policy.max_bytes:
+        reasons.append(f"{size:,} bytes; the limit is {policy.max_bytes:,}")
+
+    with path.open("rb") as f:
+        head = f.read(sniff.HEAD_BYTES)
+        if not head:
+            return Verdict(path, False, None, claimed, None, ("the file is empty",))
+        fmt = sniff.sniff(head)
+
+        if fmt is None or not policy.allows(fmt):
+            reasons.append(_wrong_format(fmt, claimed, policy))
+            return Verdict(path, False, fmt, claimed, None, tuple(reasons))
+
+        if policy.name_must_match and claimed is not None and claimed != fmt:
+            reasons.append(f"says {sniff.describe(claimed)}, is {sniff.describe(fmt)}")
+            return Verdict(path, False, fmt, claimed, None, tuple(reasons))
+
+        if reasons:
+            # Over the byte limit: do not read on, and in particular do not
+            # start pdfinfo on it.
+            return Verdict(path, False, fmt, claimed, None, tuple(reasons))
+
+        try:
+            facts = _facts(path, fmt, f, size, policy)
+        except headers.HeaderError as exc:
+            reasons.append(f"the header could not be read: {exc}")
+            return Verdict(path, False, fmt, claimed, None, tuple(reasons))
+
+    reasons.extend(_against_limits(facts, policy))
+    return Verdict(path, not reasons, fmt, claimed, facts, tuple(reasons))
+
+
+def require(path: str | os.PathLike[str], policy: Policy = DEFAULT) -> Verdict:
+    """As :func:`check`, but raise :class:`Refused` instead of returning a refusal."""
+    verdict = check(path, policy)
+    if not verdict.ok:
+        raise Refused(verdict)
+    return verdict
+
+
+def _wrong_format(fmt: str | None, claimed: str | None, policy: Policy) -> str:
+    real = sniff.describe(fmt)
+    allowed = ", ".join(sniff.describe(name) for name in sorted(policy.formats))
+    if claimed is not None and claimed != fmt:
+        return f"says {sniff.describe(claimed)}, is {real}"
+    if fmt in FORMATS:
+        return f"is {real}, which this policy does not allow (allowed: {allowed})"
+    return f"is {real}, not one of the formats a scan can be (allowed: {allowed})"
+
+
+def _facts(path: Path, fmt: str, f: headers.Reader, size: int, policy: Policy) -> Facts:
+    if fmt == "pdf":
+        info = read_pdf(path, policy)
+        return Facts(size, info.width, info.height, info.pages, info.max_pixels, info.encrypted)
+    header = headers.READERS[fmt](f, size, policy.max_pages)
+    return Facts(
+        size,
+        header.width,
+        header.height,
+        header.pages,
+        header.max_pixels if header.complete else None,
+        pages_exact=header.complete,
+    )
+
+
+def _against_limits(facts: Facts, policy: Policy) -> list[str]:
+    reasons = []
+    if facts.pages > policy.max_pages:
+        if facts.pages_exact:
+            reasons.append(f"{facts.pages:,} pages; the limit is {policy.max_pages:,}")
+        else:
+            reasons.append(f"more than {policy.max_pages:,} pages, which is the limit")
+    if facts.max_pixels is not None and facts.max_pixels > policy.max_pixels:
+        reasons.append(f"a page of {facts.max_pixels:,} pixels; the limit is {policy.max_pixels:,}")
+    if facts.encrypted and not policy.allow_encrypted_pdf:
+        reasons.append("the PDF is encrypted")
+    return reasons

sillybos/cli.py

@@ -0,0 +1,119 @@
+"""The ``sillybos`` command: check files, print verdicts, exit non-zero on a refusal.
+
+For a shell pipeline or a Dockerfile::
+
+    sillybos scans/*.tif && run-the-ocr scans/
+
+Exit status 0 when every file passed, 1 when any was refused, 2 when the
+command could not do its job (a missing file, no ``pdfinfo`` for a PDF).
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from sillybos import __version__, check
+from sillybos.pdf import PdfInfoMissing
+from sillybos.policy import DEFAULT, STRICT, Policy
+
+
+def _policy(args: argparse.Namespace) -> Policy:
+    base = STRICT if args.strict else DEFAULT
+    changes = {
+        name: value
+        for name, value in (
+            ("max_bytes", args.max_bytes),
+            ("max_pixels", args.max_pixels),
+            ("max_pages", args.max_pages),
+        )
+        if value is not None
+    }
+    if args.formats:
+        changes["formats"] = frozenset(args.formats.split(","))
+    if args.any_name:
+        changes["name_must_match"] = False
+    return dataclasses.replace(base, **changes) if changes else base
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sillybos",
+        description=(
+            "Decide before decoding: say whether each file is one of the formats a scan "
+            "can be, within the limits, before any image library or PDF renderer opens it."
+        ),
+    )
+    parser.add_argument("files", nargs="+", type=Path, metavar="FILE")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--strict", action="store_true", help="the strict preset, for files from outside"
+    )
+    parser.add_argument(
+        "--formats",
+        metavar="LIST",
+        help="comma-separated formats to allow, from jpeg,png,tiff,pdf (default: all four)",
+    )
+    parser.add_argument("--max-bytes", type=int, metavar="N", help="largest file, in bytes")
+    parser.add_argument(
+        "--max-pixels", type=int, metavar="N", help="most pixels in any one page or frame"
+    )
+    parser.add_argument("--max-pages", type=int, metavar="N", help="most pages or frames")
+    parser.add_argument(
+        "--any-name",
+        action="store_true",
+        help="do not refuse a file whose extension disagrees with its contents",
+    )
+    parser.add_argument("--json", action="store_true", help="one JSON object per line")
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="print only the files that were refused"
+    )
+    return parser
+
+
+def _line(verdict: object, as_json: bool) -> str:
+    from sillybos.check import Verdict
+
+    if not isinstance(verdict, Verdict):  # pragma: no cover - typing guard
+        raise TypeError(type(verdict))
+    if as_json:
+        record = dataclasses.asdict(verdict)
+        record["path"] = str(verdict.path)
+        return json.dumps(record, ensure_ascii=False)
+    if verdict.ok:
+        return f"ok       {verdict.path}  ({verdict.summary()})"
+    return f"refused  {verdict.path}  {'; '.join(verdict.reasons)}"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        policy = _policy(args)
+    except ValueError as exc:
+        print(f"sillybos: {exc}", file=sys.stderr)
+        return 2
+    status = 0
+    for path in args.files:
+        try:
+            verdict = check(path, policy)
+        except FileNotFoundError:
+            print(f"sillybos: {path}: no such file", file=sys.stderr)
+            status = 2
+            continue
+        except PdfInfoMissing as exc:
+            print(f"sillybos: {exc}", file=sys.stderr)
+            return 2
+        if not verdict.ok:
+            status = max(status, 1)
+        if verdict.ok and args.quiet:
+            continue
+        print(_line(verdict, args.json))
+    return status
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

sillybos/headers.py

@@ -0,0 +1,236 @@
+"""Width, height and page count from a JPEG, PNG or TIFF header, without a decoder.
+
+Each reader here is a few dozen lines that understand just enough of its
+format to find the dimensions and count the frames. None of them decodes a
+pixel, and none of them is a decoder's own header code: the point of the
+library is that a file is judged before any of that runs. Every read is
+bounded, every offset is checked against the file's size, and a TIFF's
+chain of frames is walked with a limit and a memory of where it has been,
+so that a crafted file cannot send the reader round in a circle or off the
+end of the file.
+
+A header the reader cannot make sense of raises :class:`HeaderError` with a
+reason; the check turns that into a refusal. "Cannot make sense of" is
+deliberately broad: a file that is not shaped the way its format says is not
+one to hand to a decoder, whatever a more forgiving reader would do with it.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import IO
+
+Reader = IO[bytes]
+
+MAX_SEGMENTS = 4096
+"""How many JPEG segments or PNG chunks to walk before giving up: a bound
+on the time a crafted file can cost. A real scan has tens."""
+
+MAX_DIMENSION = 1 << 31
+"""A width or height at or above this is not a dimension; it is a bug or
+an attack, and refused before the multiplication that would overflow a C
+decoder."""
+
+
+class HeaderError(ValueError):
+    """The header is not shaped the way its format says."""
+
+
+@dataclass(frozen=True)
+class Header:
+    """What a header reader found.
+
+    Attributes:
+        width: Pixels across, for the first frame.
+        height: Pixels down, for the first frame.
+        pages: Frames in the file (1 for an ordinary image). For a TIFF with
+            more frames than ``limit``, ``limit + 1``: the walk stopped.
+        max_pixels: The most pixels in any one frame the reader looked at.
+        complete: ``False`` if the walk stopped at the limit, so ``pages``
+            and ``max_pixels`` describe only the frames it reached.
+    """
+
+    width: int
+    height: int
+    pages: int
+    max_pixels: int
+    complete: bool = True
+
+
+def _read_exactly(f: Reader, n: int, what: str) -> bytes:
+    data = f.read(n)
+    if len(data) != n:
+        raise HeaderError(f"the file ends inside its {what}")
+    return data
+
+
+def _dimensions(width: int, height: int, what: str) -> None:
+    if width < 1 or height < 1:
+        raise HeaderError(f"the {what} gives a zero width or height")
+    if width >= MAX_DIMENSION or height >= MAX_DIMENSION:
+        raise HeaderError(f"the {what} gives a width or height of {max(width, height):,}")
+
+
+# --- JPEG -------------------------------------------------------------------
+
+# Start-of-frame markers, which carry the dimensions. C4 (DHT), C8 (JPG
+# extension) and CC (DAC) share the range but are not frames.
+_SOF = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
+# Markers with no length field.
+_STANDALONE = {0x01, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8}
+
+
+def jpeg(f: Reader, size: int, limit: int) -> Header:
+    """Read a JPEG's frame header: walk the segments to the first SOF marker."""
+    del limit  # a JPEG has one frame
+    f.seek(0)
+    if _read_exactly(f, 2, "header") != b"\xff\xd8":
+        raise HeaderError("no JPEG start-of-image marker")
+    for _ in range(MAX_SEGMENTS):
+        byte = _read_exactly(f, 1, "segment marker")
+        if byte != b"\xff":
+            raise HeaderError("a segment does not start with a marker")
+        marker = _read_exactly(f, 1, "segment marker")[0]
+        while marker == 0xFF:  # fill bytes before a marker are allowed
+            marker = _read_exactly(f, 1, "segment marker")[0]
+        if marker in _STANDALONE:
+            continue
+        if marker in (0xD9, 0xDA):
+            raise HeaderError("the image data starts before any frame header")
+        (length,) = struct.unpack(">H", _read_exactly(f, 2, "segment length"))
+        if length < 2:
+            raise HeaderError("a segment claims a length shorter than its own length field")
+        if marker in _SOF:
+            if length < 7:
+                raise HeaderError("the frame header is too short to hold the dimensions")
+            _precision, height, width = struct.unpack(">BHH", _read_exactly(f, 5, "frame header"))
+            if height == 0:
+                # Legal (a DNL marker supplies it later) and never seen in a
+                # scan; refusing it keeps every decoder's rarest path closed.
+                raise HeaderError("the height is deferred to a DNL marker")
+            _dimensions(width, height, "frame header")
+            return Header(width, height, 1, width * height)
+        next_offset = f.tell() + length - 2
+        if next_offset > size:
+            raise HeaderError("a segment runs past the end of the file")
+        f.seek(next_offset)
+    raise HeaderError(f"no frame header in the first {MAX_SEGMENTS} segments")
+
+
+# --- PNG --------------------------------------------------------------------
+
+
+def png(f: Reader, size: int, limit: int) -> Header:
+    """Read a PNG's IHDR, and count the frames of an animated one (acTL)."""
+    del limit  # the frame count is one field; no walk to bound
+    f.seek(8)  # the signature was checked by sniff
+    length, kind = struct.unpack(">I4s", _read_exactly(f, 8, "first chunk"))
+    if kind != b"IHDR" or length != 13:
+        raise HeaderError("the first chunk is not a 13-byte IHDR")
+    width, height = struct.unpack(">II", _read_exactly(f, 8, "IHDR"))
+    _dimensions(width, height, "IHDR")
+    f.seek(13 - 8 + 4, 1)  # the rest of IHDR, and its CRC
+    pages = 1
+    for _ in range(MAX_SEGMENTS):
+        head = f.read(8)
+        if len(head) < 8:
+            break
+        length, kind = struct.unpack(">I4s", head)
+        if kind in (b"IDAT", b"IEND"):
+            break
+        if kind == b"acTL" and length >= 4:
+            (pages,) = struct.unpack(">I", _read_exactly(f, 4, "acTL"))
+            if pages < 1:
+                raise HeaderError("acTL gives zero frames")
+            break
+        next_offset = f.tell() + length + 4
+        if next_offset > size:
+            raise HeaderError("a chunk runs past the end of the file")
+        f.seek(next_offset)
+    return Header(width, height, pages, width * height)
+
+
+# --- TIFF -------------------------------------------------------------------
+
+_TIFF_SHORT = 3
+_TIFF_LONG = 4
+_IMAGE_WIDTH = 256
+_IMAGE_LENGTH = 257
+
+
+def tiff(f: Reader, size: int, limit: int) -> Header:
+    """Walk a classic TIFF's IFD chain: dimensions per frame, frames counted.
+
+    Stops after ``limit + 1`` frames and reports that many, so that a file
+    with a million frames costs the time of ``limit`` reads, not a million.
+    An IFD that points at itself, at an earlier one, or past the end of the
+    file is an error, not a loop.
+    """
+    f.seek(0)
+    order = _read_exactly(f, 2, "header")
+    endian = {b"II": "<", b"MM": ">"}.get(order)
+    if endian is None:
+        raise HeaderError("no TIFF byte-order mark")
+    (magic,) = struct.unpack(endian + "H", _read_exactly(f, 2, "header"))
+    if magic != 42:
+        raise HeaderError("not a classic TIFF (BigTIFF is refused by name)")
+    (offset,) = struct.unpack(endian + "I", _read_exactly(f, 4, "header"))
+    seen: set[int] = set()
+    first: tuple[int, int] | None = None
+    max_pixels = 0
+    pages = 0
+    while offset != 0:
+        if pages > limit:
+            if first is None:
+                return _no_frames()
+            return Header(first[0], first[1], pages, max_pixels, complete=False)
+        if offset in seen:
+            raise HeaderError("the frame chain loops back on itself")
+        if offset + 2 > size or offset < 8:
+            raise HeaderError("a frame directory lies outside the file")
+        seen.add(offset)
+        f.seek(offset)
+        (count,) = struct.unpack(endian + "H", _read_exactly(f, 2, "frame directory"))
+        if offset + 2 + count * 12 + 4 > size:
+            raise HeaderError("a frame directory runs past the end of the file")
+        width = height = None
+        for _ in range(count):
+            tag, kind, n, raw = struct.unpack(
+                endian + "HHI4s", _read_exactly(f, 12, "frame directory")
+            )
+            if tag not in (_IMAGE_WIDTH, _IMAGE_LENGTH):
+                continue
+            if n != 1:
+                raise HeaderError("a dimension tag holds more than one value")
+            if kind == _TIFF_SHORT:
+                # A SHORT sits in the first two bytes of the field in either
+                # byte order: the value is left-justified, not right-aligned.
+                (value,) = struct.unpack(endian + "H", raw[:2])
+            elif kind == _TIFF_LONG:
+                (value,) = struct.unpack(endian + "I", raw)
+            else:
+                raise HeaderError("a dimension tag is neither SHORT nor LONG")
+            if tag == _IMAGE_WIDTH:
+                width = value
+            else:
+                height = value
+        if width is None or height is None:
+            raise HeaderError(f"frame {pages + 1} has no width or height")
+        _dimensions(width, height, f"frame {pages + 1}")
+        pages += 1
+        max_pixels = max(max_pixels, width * height)
+        if first is None:
+            first = (width, height)
+        (offset,) = struct.unpack(endian + "I", _read_exactly(f, 4, "frame directory"))
+    if first is None:
+        return _no_frames()
+    return Header(first[0], first[1], pages, max_pixels)
+
+
+def _no_frames() -> Header:
+    raise HeaderError("the file has no frames")
+
+
+READERS = {"jpeg": jpeg, "png": png, "tiff": tiff}
+"""The header reader for each raster format in :data:`sillybos.FORMATS`."""

sillybos/pdf.py

@@ -0,0 +1,126 @@
+"""Page count and page sizes of a PDF, from poppler's ``pdfinfo``.
+
+A PDF's structure cannot be read from a fixed header the way an image's can:
+the page count lives in an object tree that may be compressed, and finding
+it means parsing. Rather than carry a PDF parser (which would be exactly the
+kind of code the library exists to keep away from untrusted files), this
+asks ``pdfinfo``, which parses the structure without rendering a page, in a
+separate process with a time limit. A hang or a crash in ``pdfinfo`` is then
+one file's refusal, not the caller's.
+
+``pdfinfo`` comes with poppler (``brew install poppler``, ``apt install
+poppler-utils``), which anything that renders PDFs in Python already needs.
+Without it, a PDF cannot be checked, and :class:`PdfInfoMissing` says so;
+that is a configuration error, not a verdict on the file.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from sillybos.headers import HeaderError
+from sillybos.policy import Policy
+
+_PAGES = re.compile(r"^Pages:\s+(\d+)\s*$", re.MULTILINE)
+_ENCRYPTED = re.compile(r"^Encrypted:\s+yes", re.MULTILINE)
+_PAGE_SIZE = re.compile(r"^Page(?:\s+(\d+))? size:\s+([\d.]+) x ([\d.]+) pts", re.MULTILINE)
+
+
+class PdfInfoMissing(RuntimeError):
+    """``pdfinfo`` is not on the PATH, so no PDF can be checked."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "pdfinfo (from poppler) is needed to check a PDF and is not on the PATH: "
+            "`brew install poppler` on macOS, `apt install poppler-utils` on Debian"
+        )
+
+
+@dataclass(frozen=True)
+class PdfHeader:
+    """What ``pdfinfo`` reported.
+
+    Attributes:
+        pages: The page count.
+        encrypted: Whether the file is encrypted.
+        width: The first page's width in pixels at the policy's render dpi.
+        height: The first page's height, likewise.
+        max_pixels: The most pixels any page would render to. ``None`` when
+            the page count was over the limit and the sizes were not asked
+            for.
+    """
+
+    pages: int
+    encrypted: bool
+    width: int
+    height: int
+    max_pixels: int | None
+
+
+def _pdfinfo(args: list[str], path: Path, timeout: float) -> str:
+    executable = shutil.which("pdfinfo")
+    if executable is None:
+        raise PdfInfoMissing
+    try:
+        # The arguments are a fixed list plus the path being checked: nothing
+        # here is a shell, and the file's contents go to pdfinfo's parser,
+        # which is the one process this library is willing to expose to them.
+        done = subprocess.run(  # noqa: S603
+            [executable, *args, str(path)],
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        raise HeaderError(f"pdfinfo did not finish within {timeout:g} seconds") from None
+    if done.returncode != 0:
+        detail = done.stderr.strip().splitlines()
+        reason = detail[-1] if detail else f"exit status {done.returncode}"
+        raise HeaderError(f"pdfinfo could not read it ({reason})")
+    return done.stdout
+
+
+def _pixels(points: str, dpi: int) -> float:
+    return float(points) / 72 * dpi
+
+
+def pdf(path: Path, policy: Policy) -> PdfHeader:
+    """Ask ``pdfinfo`` for the page count, encryption and, within the limit, every page's size.
+
+    Page sizes are only asked for when the count is within ``policy.max_pages``:
+    a listing of a hundred thousand pages is work the file should not be able
+    to cause.
+
+    Raises:
+        HeaderError: If ``pdfinfo`` refuses the file or runs out of time.
+        PdfInfoMissing: If ``pdfinfo`` is not installed.
+    """
+    summary = _pdfinfo([], path, policy.pdfinfo_timeout)
+    pages_match = _PAGES.search(summary)
+    if pages_match is None:
+        raise HeaderError("pdfinfo reported no page count")
+    pages = int(pages_match.group(1))
+    if pages < 1:
+        raise HeaderError("the PDF has no pages")
+    encrypted = _ENCRYPTED.search(summary) is not None
+    first = _PAGE_SIZE.search(summary)
+    if first is None:
+        raise HeaderError("pdfinfo reported no page size")
+    width = round(_pixels(first.group(2), policy.render_dpi))
+    height = round(_pixels(first.group(3), policy.render_dpi))
+    if pages > policy.max_pages:
+        return PdfHeader(pages, encrypted, width, height, None)
+    listing = _pdfinfo(["-f", "1", "-l", str(pages)], path, policy.pdfinfo_timeout)
+    sizes = [
+        _pixels(w, policy.render_dpi) * _pixels(h, policy.render_dpi)
+        for _page, w, h in _PAGE_SIZE.findall(listing)
+    ]
+    if not sizes:
+        raise HeaderError("pdfinfo reported no page sizes")
+    return PdfHeader(pages, encrypted, width, height, round(max(sizes)))

sillybos/pillow.py

@@ -0,0 +1,49 @@
+"""Check a file, then open it with Pillow using only the readers the policy allows.
+
+The one-line fix that October 2026's Pillow advisories made everyone want,
+packaged: ``Image.open`` takes a ``formats`` list, and a file that is not one
+of them is never handed to the other readers, whatever it claims to be.
+:func:`open_checked` runs :func:`sillybos.require` first, so a file that is
+too large, lies about its format or has a page beyond the limit is refused
+before Pillow sees it, and then opens it with ``formats`` set from the
+policy.
+
+Needs the ``[pillow]`` extra: ``pip install 'sillybos[pillow]'``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from sillybos.check import require
+from sillybos.policy import DEFAULT, Policy
+
+if TYPE_CHECKING:
+    from PIL import Image
+
+_PILLOW_NAMES = {"jpeg": "JPEG", "png": "PNG", "tiff": "TIFF"}
+
+
+def pillow_formats(policy: Policy = DEFAULT) -> list[str]:
+    """The ``formats`` argument for ``Image.open``, from a policy: ``["JPEG", "PNG", "TIFF"]``."""
+    return [_PILLOW_NAMES[name] for name in sorted(policy.formats) if name in _PILLOW_NAMES]
+
+
+def open_checked(path: str | os.PathLike[str], policy: Policy = DEFAULT) -> Image.Image:
+    """Check ``path`` against ``policy``, then open it with only the allowed Pillow readers.
+
+    A PDF passes the check but Pillow does not read PDFs; opening one raises
+    ``PIL.UnidentifiedImageError``, as it would for any file outside
+    ``formats``.
+
+    Raises:
+        sillybos.Refused: If the file does not pass the policy.
+        ImportError: If Pillow is not installed.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        raise ImportError("open_checked needs Pillow: pip install 'sillybos[pillow]'") from None
+    require(path, policy)
+    return Image.open(path, formats=pillow_formats(policy))

sillybos/policy.py

@@ -0,0 +1,91 @@
+"""What a file is allowed to be.
+
+A :class:`Policy` is a plain settings object: which formats may pass, and the
+ceilings on size, pixels and pages. Two presets cover most uses. The numbers
+in :data:`DEFAULT` come from a real corpus of archival scans (the largest
+page in it is 39 million pixels at 600 dpi; the longest book is 166 pages)
+with room to spare; :data:`STRICT` is for files from further away.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+FORMATS: tuple[str, ...] = ("jpeg", "png", "tiff", "pdf")
+"""The only formats the library will ever pass: the ones a scan can be.
+Everything else is refused by name. Adding a format is adding attack surface,
+so one is added only when someone shows a scan in it."""
+
+MIB = 1024 * 1024
+
+
+@dataclass(frozen=True)
+class Policy:
+    """The limits a file must sit inside to pass :func:`sillybos.check`.
+
+    Args:
+        formats: Which of :data:`FORMATS` may pass. A file of any other
+            format is refused whatever its name says.
+        max_bytes: The largest file, in bytes. Checked before anything is
+            read, so an enormous file is never handed to ``pdfinfo``.
+        max_pixels: The most pixels in any one page or frame once decoded.
+            For a PDF page, the pixels it would render to at ``render_dpi``.
+            The default is the threshold at which Pillow warns of a
+            decompression bomb, enforced here rather than left to a global
+            that another library may have raised.
+        max_pages: The most pages in a PDF, or frames in a multi-frame TIFF
+            or animated PNG. Bounds the time and the memory a run takes,
+            and stops the header walk itself on a file with a million
+            empty frames.
+        render_dpi: The resolution the PDF renderer will be run at, so a
+            page's size in points can be turned into pixels before the
+            renderer allocates them.
+        name_must_match: Refuse a file whose extension says one allowed
+            format and whose contents are another (a JPEG called
+            ``.png``). The readers would cope, but a file whose name lies
+            is not one to trust, and the mismatch is the first thing an
+            operator wants to know.
+        allow_encrypted_pdf: Pass a PDF that ``pdfinfo`` reports as
+            encrypted. A scanned book never is, so the default refuses.
+        pdfinfo_timeout: Seconds to give ``pdfinfo`` before giving up on a
+            PDF, which is then refused. A crafted file can make a parser
+            loop; a limit turns that into one file's failure.
+    """
+
+    formats: frozenset[str] = field(default_factory=lambda: frozenset(FORMATS))
+    max_bytes: int = 512 * MIB
+    max_pixels: int = 89_478_485
+    max_pages: int = 500
+    render_dpi: int = 200
+    name_must_match: bool = True
+    allow_encrypted_pdf: bool = False
+    pdfinfo_timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        unknown = set(self.formats) - set(FORMATS)
+        if unknown:
+            raise ValueError(
+                f"unknown format(s) {sorted(unknown)}; the formats are {', '.join(FORMATS)}"
+            )
+        if not self.formats:
+            raise ValueError("a policy must allow at least one format")
+        for name in ("max_bytes", "max_pixels", "max_pages", "render_dpi"):
+            if getattr(self, name) < 1:
+                raise ValueError(f"{name} must be at least 1")
+        if self.pdfinfo_timeout <= 0:
+            raise ValueError("pdfinfo_timeout must be positive")
+
+    def allows(self, fmt: str) -> bool:
+        """Whether ``fmt`` (a name from :data:`FORMATS`) may pass."""
+        return fmt in self.formats
+
+
+DEFAULT = Policy()
+"""For files from a trusted laptop or your own scanner."""
+
+STRICT = Policy(
+    max_bytes=128 * MIB,
+    max_pixels=50_000_000,
+    max_pages=100,
+)
+"""For files from outside: smaller, shorter, and no more lenient on format."""

sillybos/sniff.py

@@ -0,0 +1,120 @@
+"""What a file really is, from its first bytes.
+
+An image library decides a file's format from its contents and then runs the
+reader for that format, so a file's extension protects nothing: a PostScript
+file named ``page.png`` reaches the PostScript reader. This module looks at
+the same bytes first, and names the format, so that the check can refuse by
+name before any reader runs.
+
+The table names more formats than the library will ever pass. The extra
+names exist for the reason text: "says PNG, is PostScript" tells an operator
+more than "says PNG, is something else".
+"""
+
+from __future__ import annotations
+
+HEAD_BYTES = 1024
+"""How much of a file :func:`sniff` needs. The longest signature here is
+twelve bytes; the rest is slack for formats that put their mark later."""
+
+# (name, offset, signature); checked in order, first match wins.
+_SIGNATURES: tuple[tuple[str, int, bytes], ...] = (
+    ("jpeg", 0, b"\xff\xd8\xff"),
+    ("png", 0, b"\x89PNG\r\n\x1a\n"),
+    ("tiff", 0, b"II*\x00"),
+    ("tiff", 0, b"MM\x00*"),
+    ("bigtiff", 0, b"II+\x00"),
+    ("bigtiff", 0, b"MM\x00+"),
+    ("pdf", 0, b"%PDF-"),
+    ("postscript", 0, b"%!PS"),
+    ("postscript", 0, b"\xc5\xd0\xd3\xc6"),  # DOS EPS binary header
+    ("gif", 0, b"GIF87a"),
+    ("gif", 0, b"GIF89a"),
+    ("bmp", 0, b"BM"),
+    ("ole", 0, b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"),  # FlashPix, old Office
+    ("psd", 0, b"8BPS"),
+    ("jpeg2000", 0, b"\x00\x00\x00\x0cjP  \r\n\x87\n"),
+    ("jpeg2000", 0, b"\xff\x4f\xff\x51"),
+    ("zip", 0, b"PK\x03\x04"),
+    ("gzip", 0, b"\x1f\x8b"),
+    ("ico", 0, b"\x00\x00\x01\x00"),
+    ("xml", 0, b"<?xml"),
+    ("xml", 0, b"<svg"),
+    ("pcx", 0, b"\x0a"),
+)
+
+_DESCRIPTIONS: dict[str, str] = {
+    "jpeg": "JPEG",
+    "png": "PNG",
+    "tiff": "TIFF",
+    "bigtiff": "BigTIFF",
+    "pdf": "PDF",
+    "postscript": "PostScript",
+    "gif": "GIF",
+    "bmp": "BMP",
+    "ole": "an OLE compound file (FlashPix, or an old Office document)",
+    "psd": "a Photoshop document",
+    "jpeg2000": "JPEG 2000",
+    "webp": "WebP",
+    "heif": "HEIF or AVIF",
+    "zip": "a zip archive",
+    "gzip": "a gzip file",
+    "ico": "a Windows icon",
+    "xml": "XML (or SVG)",
+    "pcx": "PCX",
+}
+
+_CLAIMS: dict[str, str] = {
+    ".jpg": "jpeg",
+    ".jpeg": "jpeg",
+    ".jpe": "jpeg",
+    ".jfif": "jpeg",
+    ".png": "png",
+    ".tif": "tiff",
+    ".tiff": "tiff",
+    ".pdf": "pdf",
+}
+
+
+def sniff(head: bytes) -> str | None:
+    """Name the format of a file from its first bytes, or ``None`` if unknown.
+
+    Args:
+        head: The first :data:`HEAD_BYTES` of the file (fewer, if the file is
+            shorter).
+
+    Returns:
+        A lower-case name: one of :data:`sillybos.FORMATS`, one of the other
+        names the library knows only to refuse, or ``None``.
+    """
+    for name, offset, signature in _SIGNATURES:
+        if head[offset : offset + len(signature)] == signature:
+            return name
+    # RIFF containers and ISO base media files carry their type a few bytes in.
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "webp"
+    if head[4:8] == b"ftyp":
+        brand = head[8:12]
+        if brand in {b"heic", b"heix", b"hevc", b"hevx", b"mif1", b"msf1", b"avif", b"avis"}:
+            return "heif"
+    return None
+
+
+def describe(name: str | None) -> str:
+    """The format's name for a reason sentence: ``"PostScript"``, ``"a zip archive"``."""
+    if name is None:
+        return "an unknown format"
+    return _DESCRIPTIONS.get(name, name)
+
+
+def claimed_by(suffix: str) -> str | None:
+    """What a file's extension says it is, as a name from :data:`sillybos.FORMATS`.
+
+    ``None`` for an extension the library does not map, including no
+    extension at all: such a file makes no claim, so it cannot lie.
+    """
+    return _CLAIMS.get(suffix.lower())
+
+
+FORMATS_KNOWN = frozenset(_DESCRIPTIONS)
+"""Every name sniff() can return, for telling "not allowed" from "unknown"."""

sillybos-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: sillybos
+Version: 0.1.0
+Summary: Decide before decoding: check that a file is a JPEG, PNG, TIFF or PDF within your limits before any image library or PDF renderer opens it
+Project-URL: Homepage, https://github.com/scattercode/sillybos
+Project-URL: Source, https://github.com/scattercode/sillybos
+Project-URL: Changelog, https://github.com/scattercode/sillybos/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/scattercode/sillybos/issues
+Project-URL: Tetrak, https://tetrak.dev/
+Author: Stephen Masters, Yvette Mankerian
+License-Expression: MIT
+License-File: LICENSE
+Keywords: archives,decompression-bomb,file-validation,image,libraries,ocr,pdf,pillow,poppler,scans,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pillow>=13.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: pillow
+Requires-Dist: pillow>=13.0; extra == 'pillow'
+Description-Content-Type: text/markdown
+
+# sillybos
+
+<img src="https://raw.githubusercontent.com/scattercode/sillybos/main/docs/logo.png" alt="A rolled scroll with a small parchment tag hanging from it, reading: metadata, caps and format vetted" width="280" align="right">
+
+**Decide before decoding.** A σίλλυβος (*sillybos*; Latin *sittybus*) was
+the little parchment tag that hung from a rolled scroll in an ancient
+library, carrying its title and author, so that a reader could tell what a
+scroll was without unrolling it. Cicero had them made for his books. This
+library is that tag for the files a scanning or OCR pipeline is handed: it
+reads the tag, and says whether the scroll should be unrolled at all.
+
+It answers one narrow question, before any image library or PDF renderer
+opens a file: *is this one of the formats I mean to read, within the limits
+I expect, and if not, why?* It names the format from the file's first bytes,
+whatever the file is called; reads the header of a JPEG, PNG or TIFF with a
+few dozen lines of its own, never a decoder's; asks poppler's `pdfinfo`, in
+a separate process with a time limit, how many pages a PDF has and how large
+they are; and refuses, in a plain sentence, anything outside the policy you
+give it.
+
+> **Status: alpha.** The API is small and may still move. It is in use in
+> [Tetrak OCR](https://tetrak.dev/), which is where it came from.
+
+```bash
+pip install sillybos            # the check; no dependencies
+pip install 'sillybos[pillow]'  # plus open_checked(), which opens the file with Pillow
+```
+
+A PDF needs `pdfinfo` from poppler on the PATH (`brew install poppler`,
+`apt install poppler-utils`). Anything that renders PDFs in Python already
+has it.
+
+## Why
+
+Every program that reads scans hands each file to a decoder: Pillow for
+images, poppler for PDFs, then an OCR engine. Decoders are large, old
+programs that read complicated formats, and they have flaws. In October
+2026, Pillow 13.0.0 fixed four serious ones at once. One of them
+(CVE-2026-112900) ran commands on the computer when an EPS file was opened
+and Ghostscript was installed; and a file's extension was no protection,
+because Pillow decides what a file is from its contents, so a PostScript
+file named `page.png` went straight to the PostScript reader.
+
+The fixes to Pillow arrived; the lesson stays. A pipeline that opens files
+it did not make should decide, from the file's own bytes and a policy of
+its own, whether a decoder may have it, and should do that deciding with
+code that is not itself a decoder.
+
+## Use
+
+```python
+>>> from sillybos import check
+>>> verdict = check("scans/page-012.png")
+>>> verdict.ok
+False
+>>> verdict.reasons
+('says PNG, is PostScript',)
+```
+
+```python
+>>> verdict = check("scans/register.tif")
+>>> verdict.ok, verdict.format, verdict.facts
+(True, 'tiff', Facts(bytes=48213990, width=4960, height=7016, pages=32, max_pixels=34799360, encrypted=False))
+```
+
+`check` never raises for anything found *in* the file. A lying name, a
+malformed header, a page too large and a thousand-page PDF are all reasons,
+not exceptions, and a verdict carries every reason it found. `require` is
+the same check for callers who would rather catch one exception:
+
+```python
+from sillybos import require, Refused
+
+try:
+    require(path)
+except Refused as refusal:
+    quarantine(path, refusal.verdict.reasons)
+```
+
+### The policy
+
+```python
+from sillybos import Policy, DEFAULT, STRICT, check
+
+check(path)  # DEFAULT: a trusted laptop, your own scanner
+check(path, STRICT)  # files from outside: smaller and shorter
+check(path, Policy(formats={"tiff", "pdf"}, max_pages=50))
+```
+
+| Setting | `DEFAULT` | `STRICT` | What it bounds |
+|---|---|---|---|
+| `formats` | jpeg, png, tiff, pdf | the same | What may pass at all. Nothing else is ever allowed, whatever the policy says |
+| `max_bytes` | 512 MiB | 128 MiB | The file. Checked before anything reads it |
+| `max_pixels` | 89,478,485 | 50,000,000 | Any one page or frame, decoded. For a PDF page, at `render_dpi`. The default is Pillow's own decompression-bomb threshold, enforced here rather than left to a global |
+| `max_pages` | 500 | 100 | Pages of a PDF, frames of a TIFF or animated PNG. Also bounds the header walk itself |
+| `render_dpi` | 200 | 200 | What you will render PDF pages at, so a page's pixels are known before the renderer allocates them |
+| `name_must_match` | yes | yes | Refuse a JPEG called `.png`. The readers would cope; the lie is what you want to know about |
+| `allow_encrypted_pdf` | no | no | A scanned book is never encrypted |
+| `pdfinfo_timeout` | 30 s | 30 s | How long `pdfinfo` may take before the file is refused |
+
+The defaults were set from a real corpus of archival scans (largest page 39
+million pixels at 600 dpi; longest book 166 pages) with room to spare. Set
+yours the same way: from the largest real file you have, times two or three.
+
+### With Pillow
+
+```python
+from sillybos.pillow import open_checked
+
+with open_checked(
+    path
+) as image:  # checked first; then Image.open(path, formats=["JPEG", "PNG", "TIFF"])
+    ...
+```
+
+`Image.open` takes a `formats` list, and a file outside it is never handed
+to the other readers. `open_checked` runs the check, then opens with that
+list set from the policy. That one argument is the whole of the October fix
+for images, and it costs nothing; the check in front of it is what makes
+the limits bite before Pillow allocates a pixel.
+
+### The command
+
+```bash
+$ sillybos scans/*
+ok       scans/page-001.tif  (TIFF, 4960x7016, 1 page, 1.6 MB)
+refused  scans/page-002.png  says PNG, is PostScript
+refused  scans/poster.jpg    a page of 1,200,000,000 pixels; the limit is 89,478,485
+refused  scans/report.pdf    1,412 pages; the limit is 500
+```
+
+Exit status 0 when every file passed, 1 when any was refused, 2 when the
+command could not do its job. `--strict`, `--formats`, `--max-pages`,
+`--max-pixels`, `--max-bytes` and `--any-name` adjust the policy; `--json`
+prints one object per line for a pipeline; `-q` prints only refusals.
+
+## What it does, exactly
+
+1. **Size**, from the file system. Over the limit, nothing reads the file
+   but the next step.
+2. **Format, from the first bytes.** JPEG, PNG, TIFF and PDF are the four
+   it can pass. It also knows PostScript, GIF, BMP, WebP, HEIF, JPEG 2000,
+   BigTIFF, Photoshop, OLE (FlashPix, old Office), zip, gzip, icons and
+   XML, so that a refusal can say *what* the file is. Anything else is "an
+   unknown format". Refused by name, and no reader of ours runs on it.
+3. **Name against contents.** `says PNG, is JPEG`.
+4. **The header**, with a reader of its own for each raster format: the
+   dimensions from a JPEG's frame header, a PNG's `IHDR` (and `acTL` frame
+   count), and every directory in a TIFF's chain, which is walked with a
+   limit and a memory of where it has been, so that a chain that loops or
+   points off the end of the file is a refusal, not a hang. Every read is
+   bounded and every offset is checked against the file's size. For a PDF,
+   `pdfinfo` reports the page count, whether it is encrypted and, if the
+   count is within the limit, every page's size.
+5. **The limits**, against what the header said.
+
+## What it does not do
+
+Say this plainly, because a security library carries an implied promise.
+
+- **It does not protect against a flaw in the readers you *do* allow.** A
+  crafted JPEG that exploits a bug in your JPEG decoder passes this check,
+  because it is a JPEG of a sensible size. What this library removes is the
+  attack surface of every format you did not mean to read, and the whole
+  class of files that are too big to be safe. For the readers you keep:
+  update them, and run them in a boxed process with memory and time
+  limits (a recipe for that is planned; it is deliberately not a
+  dependency).
+- **It does not scan for malware.** ClamAV does that, for malware that has
+  been seen before.
+- **It does not repair, re-encode or "sanitise" a file.** That needs a
+  decoder, and the moment this library decoded anything it would become
+  the kind of code it exists to keep away from untrusted files.
+- **It does not look inside a PDF beyond what `pdfinfo` reports.** A PDF's
+  structure cannot be read from a fixed header; it has to be parsed, and
+  the parser this library trusts is poppler's, in its own process, with a
+  timeout. Checks for JavaScript, launch actions, embedded files and forms
+  (things a scanned book never has) are the next step.
+- **It does not validate uploads.** File names, path traversal and zip
+  bombs belong to a web framework's upload handling. This library starts
+  after the file is on disk and asks only whether a decoder may open it.
+- **It does not read formats beyond the four.** WebP, JPEG 2000, HEIC and
+  the rest are refused by name until someone shows a scan in one. Each
+  format added is attack surface added.
+
+## Development
+
+```bash
+uv venv .venv && source .venv/bin/activate
+uv pip install -e '.[dev]'
+ruff check . && ruff format --check . && mypy && pytest --cov
+```
+
+The tests build the hostile corpus by hand at test time (`tests/corpus.py`):
+renamed PostScript, a 100-byte PNG that claims ten billion pixels, a TIFF
+with ten thousand frames, a TIFF whose frame chain loops, a PDF of a
+thousand pages, a PDF with a page 200 inches wide. Nothing hostile is
+checked in. The readers are also checked against Pillow's reading of real
+files, so that they agree with the decoder they stand in front of.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and the commit style,
+and [SECURITY.md](SECURITY.md) for how to report a flaw privately.
+
+## Credits
+
+Made by [Stephen Masters](https://scattercode.dev) and Yvette Mankerian as
+part of [Tetrak](https://tetrak.dev/), an OCR and catalogue-search toolkit
+for archives, where the check sits in front of every scan. MIT licensed.

sillybos-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+sillybos/__init__.py,sha256=5ls6TUJg91yFOvJ6V5V4uxUtU4hjpFeGcu47TBQTRls,1814
+sillybos/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+sillybos/check.py,sha256=A8Qc_eU5A4ULR9Yj72jyeJ2J3mtacel5GOdlwSB_61I,7973
+sillybos/cli.py,sha256=hYfTPEtRXLMUT4xqIvUWCcWMjUqnbdDcpezLI0z79hQ,4017
+sillybos/headers.py,sha256=1rP-yePk0LCUIhq33RbHPDlwxdG8du9zwvH6TWAHE10,9733
+sillybos/pdf.py,sha256=UWXXGHHOy2i5ywTdVGsudhUzjh_ZuSSKPnypC2aL4s4,4835
+sillybos/pillow.py,sha256=mlYGHuAnY265jEYq5KjpcDSdcGJGY7vfsb_MRuQDNeY,1861
+sillybos/policy.py,sha256=D1EIcFZNutwF7efMsdhzG-d6toUGn5bStiZrRwI9uT8,3940
+sillybos/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sillybos/sniff.py,sha256=BUOAa1L9UvHC-dHKVPzi7j45wB42xNQ9n9t804C2vKg,3924
+sillybos-0.1.0.dist-info/METADATA,sha256=mMblXYIb64-9eY7-6m-Dyh75A-EH0JkETY0z0DkY0DE,11471
+sillybos-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+sillybos-0.1.0.dist-info/entry_points.txt,sha256=0IFtaDvnaSup0uBvFMwA8-f1hI3L7NPOUmEInKHdUwU,47
+sillybos-0.1.0.dist-info/licenses/LICENSE,sha256=C9aF2rOOTEyD4yzG0tzy-QZcuWfUVZySFtIN0lCBm10,1093
+sillybos-0.1.0.dist-info/RECORD,,

sillybos-0.1.0.dist-info/WHEEL

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

sillybos-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sillybos = sillybos.cli:main

sillybos-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Masters and Yvette Mankerian
+
+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.