msdoc2docx 0.7.0__py3-none-any.whl

doc2docx/__init__.py

@@ -0,0 +1,6 @@
+"""Public API for doc2docx."""
+
+from .converter import ConversionResult, convert, inspect_doc
+
+__all__ = ["ConversionResult", "convert", "inspect_doc"]
+__version__ = "0.7.0"

doc2docx/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+raise SystemExit(main())
+

doc2docx/binary/__init__.py

@@ -0,0 +1,4 @@
+from .reader import BinaryReader
+
+__all__ = ["BinaryReader"]
+

doc2docx/binary/reader.py

@@ -0,0 +1,87 @@
+"""Small, bounded little-endian binary reader."""
+
+from __future__ import annotations
+
+import struct
+
+from ..errors import BinaryBoundsError
+
+
+class BinaryReader:
+    def __init__(
+        self,
+        data: bytes | bytearray | memoryview,
+        *,
+        label: str = "binary data",
+        base_offset: int = 0,
+    ) -> None:
+        self._data = memoryview(data).cast("B")
+        self._position = 0
+        self.label = label
+        self.base_offset = base_offset
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    @property
+    def position(self) -> int:
+        return self._position
+
+    @property
+    def remaining(self) -> int:
+        return len(self._data) - self._position
+
+    def _check(self, offset: int, size: int) -> None:
+        if offset < 0 or size < 0 or offset > len(self._data) - size:
+            absolute = self.base_offset + max(offset, 0)
+            raise BinaryBoundsError(
+                f"{self.label}: read of {size} bytes at offset 0x{absolute:X} "
+                f"exceeds {len(self._data)}-byte structure"
+            )
+
+    def seek(self, offset: int) -> None:
+        self._check(offset, 0)
+        self._position = offset
+
+    def skip(self, size: int) -> None:
+        self.seek(self._position + size)
+
+    def read(self, size: int) -> bytes:
+        self._check(self._position, size)
+        start = self._position
+        self._position += size
+        return self._data[start : start + size].tobytes()
+
+    def read_at(self, offset: int, size: int) -> bytes:
+        self._check(offset, size)
+        return self._data[offset : offset + size].tobytes()
+
+    def subreader(self, offset: int, size: int, *, label: str | None = None) -> "BinaryReader":
+        self._check(offset, size)
+        return BinaryReader(
+            self._data[offset : offset + size],
+            label=label or self.label,
+            base_offset=self.base_offset + offset,
+        )
+
+    def _unpack(self, fmt: str, size: int) -> int:
+        self._check(self._position, size)
+        value = struct.unpack_from(fmt, self._data, self._position)[0]
+        self._position += size
+        return int(value)
+
+    def u8(self) -> int:
+        return self._unpack("<B", 1)
+
+    def u16(self) -> int:
+        return self._unpack("<H", 2)
+
+    def u32(self) -> int:
+        return self._unpack("<I", 4)
+
+    def i32(self) -> int:
+        return self._unpack("<i", 4)
+
+    def u64(self) -> int:
+        return self._unpack("<Q", 8)
+

doc2docx/cfb/__init__.py

@@ -0,0 +1,5 @@
+from .container import CompoundFile, CompoundFileLimits
+from .directory import DirectoryEntry, ObjectType
+
+__all__ = ["CompoundFile", "CompoundFileLimits", "DirectoryEntry", "ObjectType"]
+

doc2docx/cfb/constants.py

@@ -0,0 +1,9 @@
+CFB_SIGNATURE = bytes.fromhex("D0CF11E0A1B11AE1")
+
+MAXREGSECT = 0xFFFFFFFA
+DIFSECT = 0xFFFFFFFC
+FATSECT = 0xFFFFFFFD
+ENDOFCHAIN = 0xFFFFFFFE
+FREESECT = 0xFFFFFFFF
+NOSTREAM = 0xFFFFFFFF
+

doc2docx/cfb/container.py

@@ -0,0 +1,370 @@
+"""Safe, read-only CFB/OLE compound-file reader."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+import struct
+
+from .constants import (
+    DIFSECT,
+    ENDOFCHAIN,
+    FATSECT,
+    FREESECT,
+    MAXREGSECT,
+    NOSTREAM,
+)
+from .directory import DirectoryEntry, ObjectType
+from .header import CompoundFileHeader
+from ..errors import InvalidCompoundFile, StreamNotFound
+
+
+@dataclass(slots=True, frozen=True)
+class CompoundFileLimits:
+    max_input_bytes: int = 512 * 1024 * 1024
+    max_stream_bytes: int = 256 * 1024 * 1024
+    max_directory_entries: int = 1_000_000
+
+
+class CompoundFile:
+    def __init__(
+        self,
+        data: bytes | bytearray | memoryview,
+        *,
+        limits: CompoundFileLimits | None = None,
+    ) -> None:
+        self.limits = limits or CompoundFileLimits()
+        if len(data) > self.limits.max_input_bytes:
+            raise InvalidCompoundFile(
+                f"input is {len(data)} bytes, exceeding the configured "
+                f"{self.limits.max_input_bytes}-byte limit"
+            )
+        self._data = memoryview(data).cast("B")
+        self.header = CompoundFileHeader.parse(self._data)
+        if len(self._data) < self.header.sector_size:
+            raise InvalidCompoundFile("CFB file is shorter than one header sector")
+        payload_size = len(self._data) - self.header.sector_size
+        if payload_size % self.header.sector_size:
+            raise InvalidCompoundFile(
+                "CFB file length is not aligned to its declared sector size"
+            )
+        self._sector_count = payload_size // self.header.sector_size
+        if self._sector_count == 0:
+            raise InvalidCompoundFile("CFB file contains no sectors")
+        if self.header.number_of_fat_sectors > self._sector_count:
+            raise InvalidCompoundFile("declared FAT sector count exceeds file size")
+        if self.header.number_of_difat_sectors > self._sector_count:
+            raise InvalidCompoundFile("declared DIFAT sector count exceeds file size")
+
+        self._fat_sector_ids = self._load_difat()
+        self._fat = self._load_fat()
+        self._directory_entries = self._load_directory()
+        self._entries_by_path = self._index_directory_tree()
+        self._mini_fat = self._load_mini_fat()
+        self._mini_stream: bytes | None = None
+
+    @classmethod
+    def from_path(
+        cls,
+        path: str | Path,
+        *,
+        limits: CompoundFileLimits | None = None,
+    ) -> "CompoundFile":
+        file_path = Path(path)
+        actual_limits = limits or CompoundFileLimits()
+        size = file_path.stat().st_size
+        if size > actual_limits.max_input_bytes:
+            raise InvalidCompoundFile(
+                f"input is {size} bytes, exceeding the configured "
+                f"{actual_limits.max_input_bytes}-byte limit"
+            )
+        return cls(file_path.read_bytes(), limits=actual_limits)
+
+    @property
+    def sector_count(self) -> int:
+        return self._sector_count
+
+    @property
+    def entries(self) -> tuple[DirectoryEntry, ...]:
+        return tuple(self._entries_by_path.values())
+
+    def _sector(self, sector_id: int) -> memoryview:
+        if sector_id > MAXREGSECT or sector_id >= self._sector_count:
+            raise InvalidCompoundFile(f"sector {sector_id} is outside the CFB file")
+        start = (sector_id + 1) * self.header.sector_size
+        return self._data[start : start + self.header.sector_size]
+
+    def _load_difat(self) -> list[int]:
+        fat_sector_ids = [sid for sid in self.header.difat if sid != FREESECT]
+        next_sector = self.header.first_difat_sector
+        seen: set[int] = set()
+        entries_per_sector = self.header.sector_size // 4 - 1
+
+        for _ in range(self.header.number_of_difat_sectors):
+            if next_sector in seen:
+                raise InvalidCompoundFile("cycle detected in DIFAT sector chain")
+            seen.add(next_sector)
+            sector = self._sector(next_sector)
+            values = struct.unpack_from(
+                f"<{entries_per_sector + 1}I", sector, 0
+            )
+            fat_sector_ids.extend(
+                sid for sid in values[:entries_per_sector] if sid != FREESECT
+            )
+            next_sector = values[-1]
+
+        if self.header.number_of_difat_sectors and next_sector != ENDOFCHAIN:
+            raise InvalidCompoundFile("DIFAT chain does not end with ENDOFCHAIN")
+        if len(fat_sector_ids) < self.header.number_of_fat_sectors:
+            raise InvalidCompoundFile(
+                "DIFAT does not contain the declared number of FAT sectors"
+            )
+        fat_sector_ids = fat_sector_ids[: self.header.number_of_fat_sectors]
+        if len(set(fat_sector_ids)) != len(fat_sector_ids):
+            raise InvalidCompoundFile("DIFAT contains duplicate FAT sector IDs")
+        for sector_id in fat_sector_ids:
+            self._sector(sector_id)
+        return fat_sector_ids
+
+    def _load_fat(self) -> tuple[int, ...]:
+        values: list[int] = []
+        entries_per_sector = self.header.sector_size // 4
+        for sector_id in self._fat_sector_ids:
+            sector = self._sector(sector_id)
+            values.extend(struct.unpack_from(f"<{entries_per_sector}I", sector, 0))
+        if len(values) < self._sector_count:
+            raise InvalidCompoundFile("FAT does not cover every sector in the file")
+        for sector_id in self._fat_sector_ids:
+            if values[sector_id] != FATSECT:
+                raise InvalidCompoundFile(
+                    f"FAT sector {sector_id} is not marked FATSECT in the FAT"
+                )
+        return tuple(values)
+
+    def _chain(
+        self,
+        start_sector: int,
+        allocation_table: tuple[int, ...],
+        *,
+        label: str,
+        expected_sectors: int | None = None,
+    ) -> list[int]:
+        if start_sector == ENDOFCHAIN:
+            if expected_sectors in (None, 0):
+                return []
+            raise InvalidCompoundFile(f"{label} is empty but data was expected")
+        if start_sector in (FREESECT, FATSECT, DIFSECT) or start_sector > MAXREGSECT:
+            raise InvalidCompoundFile(
+                f"{label} starts at invalid sector marker 0x{start_sector:08X}"
+            )
+
+        result: list[int] = []
+        seen: set[int] = set()
+        current = start_sector
+        hard_limit = len(allocation_table) + 1
+        while current != ENDOFCHAIN:
+            if current in seen:
+                raise InvalidCompoundFile(f"cycle detected in {label} sector chain")
+            if current >= len(allocation_table) or current > MAXREGSECT:
+                raise InvalidCompoundFile(
+                    f"{label} references sector {current} outside its allocation table"
+                )
+            seen.add(current)
+            result.append(current)
+            if len(result) > hard_limit:
+                raise InvalidCompoundFile(f"{label} sector chain is unbounded")
+            current = allocation_table[current]
+            if current in (FREESECT, FATSECT, DIFSECT):
+                raise InvalidCompoundFile(
+                    f"{label} chain terminates with invalid marker 0x{current:08X}"
+                )
+
+        if expected_sectors is not None and len(result) < expected_sectors:
+            raise InvalidCompoundFile(
+                f"{label} has {len(result)} sectors but needs {expected_sectors}"
+            )
+        return result
+
+    def _read_regular_stream(
+        self, start_sector: int, size: int, *, label: str
+    ) -> bytes:
+        if size < 0 or size > self.limits.max_stream_bytes:
+            raise InvalidCompoundFile(
+                f"{label} size {size} exceeds the configured stream limit"
+            )
+        if size == 0:
+            return b""
+        required = (size + self.header.sector_size - 1) // self.header.sector_size
+        chain = self._chain(
+            start_sector,
+            self._fat,
+            label=label,
+            expected_sectors=required,
+        )
+        return b"".join(self._sector(sid) for sid in chain[:required])[:size]
+
+    def _load_directory(self) -> list[DirectoryEntry]:
+        expected = (
+            self.header.number_of_directory_sectors
+            if self.header.major_version == 4
+            else None
+        )
+        chain = self._chain(
+            self.header.first_directory_sector,
+            self._fat,
+            label="directory",
+            expected_sectors=expected,
+        )
+        if expected is not None:
+            chain = chain[:expected]
+        raw = b"".join(self._sector(sid) for sid in chain)
+        count = len(raw) // 128
+        if count > self.limits.max_directory_entries:
+            raise InvalidCompoundFile(
+                f"directory contains {count} entries, exceeding configured limit"
+            )
+        entries = [
+            DirectoryEntry.parse(
+                raw[index * 128 : (index + 1) * 128],
+                index,
+                major_version=self.header.major_version,
+            )
+            for index in range(count)
+        ]
+        if not entries or entries[0].object_type is not ObjectType.ROOT_STORAGE:
+            raise InvalidCompoundFile("directory entry 0 is not the root storage")
+        return entries
+
+    def _index_directory_tree(self) -> dict[str, DirectoryEntry]:
+        entries = self._directory_entries
+        indexed: dict[str, DirectoryEntry] = {}
+        visited: set[int] = set()
+
+        def validate_id(entry_id: int, relation: str) -> None:
+            if entry_id == NOSTREAM:
+                return
+            if entry_id >= len(entries):
+                raise InvalidCompoundFile(
+                    f"directory {relation} ID {entry_id} is out of range"
+                )
+
+        def walk_sibling_tree(entry_id: int, parent: str, depth: int = 0) -> None:
+            if entry_id == NOSTREAM:
+                return
+            if depth > 128:
+                raise InvalidCompoundFile("directory tree exceeds safe nesting depth")
+            validate_id(entry_id, "entry")
+            if entry_id in visited:
+                raise InvalidCompoundFile("cycle or duplicate detected in directory tree")
+            visited.add(entry_id)
+            entry = entries[entry_id]
+            if entry.object_type is ObjectType.UNALLOCATED:
+                raise InvalidCompoundFile(
+                    "directory tree references an unallocated entry"
+                )
+            validate_id(entry.left_sibling_id, "left sibling")
+            validate_id(entry.right_sibling_id, "right sibling")
+            validate_id(entry.child_id, "child")
+
+            walk_sibling_tree(entry.left_sibling_id, parent, depth + 1)
+            path = f"{parent}/{entry.name}" if parent else entry.name
+            if path in indexed:
+                raise InvalidCompoundFile(f"duplicate directory path {path!r}")
+            indexed[path] = replace(entry, path=path)
+            if entry.object_type is ObjectType.STORAGE:
+                walk_sibling_tree(entry.child_id, path, depth + 1)
+            elif entry.child_id != NOSTREAM:
+                raise InvalidCompoundFile(
+                    f"non-storage directory entry {path!r} has a child"
+                )
+            walk_sibling_tree(entry.right_sibling_id, parent, depth + 1)
+
+        root = entries[0]
+        validate_id(root.child_id, "root child")
+        indexed[""] = replace(root, path="")
+        visited.add(0)
+        walk_sibling_tree(root.child_id, "")
+        return indexed
+
+    def _load_mini_fat(self) -> tuple[int, ...]:
+        count = self.header.number_of_mini_fat_sectors
+        if count == 0:
+            return ()
+        chain = self._chain(
+            self.header.first_mini_fat_sector,
+            self._fat,
+            label="mini FAT",
+            expected_sectors=count,
+        )[:count]
+        entries_per_sector = self.header.sector_size // 4
+        values: list[int] = []
+        for sector_id in chain:
+            values.extend(
+                struct.unpack_from(
+                    f"<{entries_per_sector}I", self._sector(sector_id), 0
+                )
+            )
+        return tuple(values)
+
+    def _root_mini_stream(self) -> bytes:
+        if self._mini_stream is None:
+            root = self._directory_entries[0]
+            self._mini_stream = self._read_regular_stream(
+                root.starting_sector,
+                root.stream_size,
+                label="root mini stream",
+            )
+        return self._mini_stream
+
+    def _read_mini_stream(
+        self, start_sector: int, size: int, *, label: str
+    ) -> bytes:
+        if not self._mini_fat:
+            raise InvalidCompoundFile(f"{label} requires a mini FAT, but none exists")
+        if size > self.limits.max_stream_bytes:
+            raise InvalidCompoundFile(
+                f"{label} size {size} exceeds the configured stream limit"
+            )
+        required = (size + self.header.mini_sector_size - 1) // self.header.mini_sector_size
+        chain = self._chain(
+            start_sector,
+            self._mini_fat,
+            label=f"{label} mini",
+            expected_sectors=required,
+        )[:required]
+        mini_stream = self._root_mini_stream()
+        chunks: list[bytes] = []
+        for mini_sector in chain:
+            start = mini_sector * self.header.mini_sector_size
+            end = start + self.header.mini_sector_size
+            if end > len(mini_stream):
+                raise InvalidCompoundFile(
+                    f"{label} mini sector {mini_sector} exceeds the root mini stream"
+                )
+            chunks.append(mini_stream[start:end])
+        return b"".join(chunks)[:size]
+
+    def get_entry(self, path: str) -> DirectoryEntry:
+        normalized = path.strip("/")
+        try:
+            return self._entries_by_path[normalized]
+        except KeyError as exc:
+            raise StreamNotFound(f"compound-file entry {path!r} was not found") from exc
+
+    def open_stream(self, path: str) -> bytes:
+        entry = self.get_entry(path)
+        if entry.object_type is not ObjectType.STREAM:
+            raise StreamNotFound(f"compound-file entry {path!r} is not a stream")
+        if entry.stream_size == 0:
+            return b""
+        if entry.stream_size < self.header.mini_stream_cutoff:
+            return self._read_mini_stream(
+                entry.starting_sector,
+                entry.stream_size,
+                label=f"stream {entry.path!r}",
+            )
+        return self._read_regular_stream(
+            entry.starting_sector,
+            entry.stream_size,
+            label=f"stream {entry.path!r}",
+        )

doc2docx/cfb/directory.py

@@ -0,0 +1,135 @@
+"""CFB directory entry structures."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+import struct
+
+from .constants import NOSTREAM
+from ..errors import InvalidCompoundFile
+
+
+class ObjectType(IntEnum):
+    UNALLOCATED = 0
+    STORAGE = 1
+    STREAM = 2
+    ROOT_STORAGE = 5
+
+
+@dataclass(slots=True, frozen=True)
+class DirectoryEntry:
+    entry_id: int
+    name: str
+    object_type: ObjectType
+    color_flag: int
+    left_sibling_id: int
+    right_sibling_id: int
+    child_id: int
+    clsid: bytes
+    state_bits: int
+    creation_time: int
+    modified_time: int
+    starting_sector: int
+    stream_size: int
+    path: str = ""
+    name_was_repaired: bool = False
+
+    @classmethod
+    def parse(
+        cls, data: bytes | memoryview, entry_id: int, *, major_version: int
+    ) -> "DirectoryEntry":
+        view = memoryview(data)
+        if len(view) != 128:
+            raise InvalidCompoundFile("CFB directory entries must be 128 bytes")
+
+        name_length = struct.unpack_from("<H", view, 64)[0]
+        raw_type = view[66]
+        try:
+            object_type = ObjectType(raw_type)
+        except ValueError as exc:
+            raise InvalidCompoundFile(
+                f"directory entry {entry_id} has invalid object type {raw_type}"
+            ) from exc
+
+        name_was_repaired = False
+        if object_type is ObjectType.UNALLOCATED:
+            name = ""
+        else:
+            valid_length = 2 <= name_length <= 64 and name_length % 2 == 0
+            is_terminated = valid_length and (
+                view[name_length - 2 : name_length].tobytes() == b"\x00\x00"
+            )
+            if not valid_length or not is_terminated:
+                # Some Word-produced temporary documents contain a malformed root
+                # storage name/length. The root name is not used to resolve child
+                # streams, so normalizing only this entry is safe and improves real
+                # world compatibility without weakening child-stream validation.
+                if entry_id == 0 and object_type is ObjectType.ROOT_STORAGE:
+                    name = "Root Entry"
+                    name_was_repaired = True
+                elif not valid_length:
+                    raise InvalidCompoundFile(
+                        f"directory entry {entry_id} has invalid UTF-16 name length "
+                        f"{name_length}"
+                    )
+                else:
+                    raise InvalidCompoundFile(
+                        f"directory entry {entry_id} name is not null terminated"
+                    )
+            else:
+                raw_name = view[: name_length - 2].tobytes()
+                try:
+                    name = raw_name.decode("utf-16le")
+                except UnicodeDecodeError as exc:
+                    if entry_id == 0 and object_type is ObjectType.ROOT_STORAGE:
+                        name = "Root Entry"
+                        name_was_repaired = True
+                    else:
+                        raise InvalidCompoundFile(
+                            f"directory entry {entry_id} has an invalid UTF-16 name"
+                        ) from exc
+                if (
+                    entry_id == 0
+                    and object_type is ObjectType.ROOT_STORAGE
+                    and name != "Root Entry"
+                ):
+                    name = "Root Entry"
+                    name_was_repaired = True
+
+        left, right, child = struct.unpack_from("<III", view, 68)
+        state_bits = struct.unpack_from("<I", view, 96)[0]
+        creation_time, modified_time = struct.unpack_from("<QQ", view, 100)
+        starting_sector = struct.unpack_from("<I", view, 116)[0]
+        stream_size = struct.unpack_from("<Q", view, 120)[0]
+        if major_version == 3:
+            stream_size &= 0xFFFFFFFF
+
+        return cls(
+            entry_id=entry_id,
+            name=name,
+            object_type=object_type,
+            color_flag=int(view[67]),
+            left_sibling_id=left,
+            right_sibling_id=right,
+            child_id=child,
+            clsid=view[80:96].tobytes(),
+            state_bits=state_bits,
+            creation_time=creation_time,
+            modified_time=modified_time,
+            starting_sector=starting_sector,
+            stream_size=stream_size,
+            name_was_repaired=name_was_repaired,
+        )
+
+    @property
+    def has_left(self) -> bool:
+        return self.left_sibling_id != NOSTREAM
+
+    @property
+    def has_right(self) -> bool:
+        return self.right_sibling_id != NOSTREAM
+
+    @property
+    def has_child(self) -> bool:
+        return self.child_id != NOSTREAM