← Files LuciaARCHIVED FILE
scripts/legal_docx.py
12.7 KB · Nov 21, 2026 · 00:11 UTC
"""Inspect Word evidence locally. Structural facts are not semantic findings."""
from __future__ import annotations
import hashlib
import posixpath
import re
import zipfile
from pathlib import Path
from typing import Any
from lxml import etree as ET
__all__ = ["inspect_docx", "paragraph_text", "parse_xml", "story_parts"]
W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
R = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
PKG = "{http://schemas.openxmlformats.org/package/2006/relationships}"
STORY = re.compile(
r"word/(document|footnotes|endnotes|comments|header\d+|footer\d+)\.xml"
)
REVISIONS = {
"ins",
"del",
"moveFrom",
"moveTo",
"pPrChange",
"rPrChange",
"tblPrChange",
"sectPrChange",
}
def parse_xml(data: bytes) -> Any:
"""Reject entity declarations; never resolve document-controlled resources."""
if b"<!DOCTYPE" in data.upper():
raise ValueError("Document XML must not contain a DTD.")
root = ET.fromstring(
data, parser=ET.XMLParser(resolve_entities=False, no_network=True)
)
if root.getroottree().docinfo.doctype:
raise ValueError("Document XML must not contain a DTD.")
return root
def story_parts(archive: zipfile.ZipFile) -> list[str]:
"""Return ordinary Word stories, retaining stable XML paragraph anchors."""
names = archive.namelist()
# Fixed bounds prevent archive expansion attacks; oversize files fail explicitly.
if len(names) != len(set(names)):
raise ValueError("Duplicate DOCX archive entries are ambiguous.")
if sum(info.file_size for info in archive.infolist()) > 512 * 1024 * 1024:
raise ValueError("DOCX expands beyond the 512 MiB inspection limit.")
if "word/document.xml" not in names:
raise ValueError("DOCX has no main document part.")
return sorted(name for name in names if STORY.fullmatch(name))
def paragraph_text(node: Any, view: str = "final") -> str:
"""Read one paragraph's text without mixing opposing revision views.
Paragraph-mark/structural revisions still require the original artifact;
this provides text-level original/final views, not Word's layout engine.
"""
if view not in {"original", "final", "all"}:
raise ValueError("Choose original, final or all revision text.")
omit = {
W + tag
for tag in (("del", "moveFrom") if view == "final" else ("ins", "moveTo"))
}
pieces: list[str] = []
def visit(element: Any) -> None:
if element is not node and element.tag == W + "p":
return # Text-box paragraphs have their own anchors.
if view != "all" and element.tag in omit:
return
if element.tag in {W + "t", W + "delText"}:
pieces.append(element.text or "")
elif element.tag == W + "tab":
pieces.append("\t")
elif element.tag in {W + "br", W + "cr"}:
pieces.append("\n")
elif element.tag == W + "noBreakHyphen":
pieces.append("\u2011")
elif element.tag == W + "softHyphen":
pieces.append("\u00ad")
else:
for child in element:
visit(child)
visit(node)
return "".join(pieces)
def _attributes(element: Any) -> dict[str, str]:
return {ET.QName(key).localname: value for key, value in element.attrib.items()}
def _properties(parent: Any, name: str) -> list[dict[str, Any]]:
element = parent.find(W + name)
return (
[]
if element is None
else [
{
"property": ET.QName(child).localname,
"attributes": _attributes(child),
"xml": ET.tostring(child, encoding="unicode"),
}
for child in element
]
)
def _relationships(archive: zipfile.ZipFile, part: str) -> dict[str, dict[str, str]]:
directory, name = posixpath.split(part)
rels = posixpath.join(directory, "_rels", name + ".rels")
if rels not in archive.namelist():
return {}
return {
element.get("Id"): dict(element.attrib)
for element in parse_xml(archive.read(rels))
if element.tag == PKG + "Relationship"
}
def inspect_docx(path: Path) -> dict[str, Any]:
"""Expose text, revision views and hidden structure for model-led auditing."""
result: dict[str, Any] = {
"sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
"paragraphs": [],
"comments": [],
"styles": [],
"numbering": [],
"properties": {},
"warnings": [],
"text_view": "final",
}
with zipfile.ZipFile(path) as archive:
parts = story_parts(archive)
names = archive.namelist()
result["signed"] = any(name.startswith("_xmlsignatures/") for name in names)
if result["signed"]:
result["warnings"].append(
"Signed package: changes invalidate signatures; editing is disabled."
)
result["protection_enforced"] = False
if "word/settings.xml" in names:
settings = parse_xml(archive.read("word/settings.xml"))
protection = settings.find(W + "documentProtection")
if protection is not None:
result["protection_enforced"] = protection.get(
W + "enforcement", "false"
).lower() in {"1", "true", "on"}
if result["protection_enforced"]:
result["warnings"].append(
"Document protection is enforced; obtain an appropriate "
"editable source before authoring changes."
)
for part in parts:
root = parse_xml(archive.read(part))
relationships = _relationships(archive, part)
for number, paragraph in enumerate(root.iter(W + "p"), 1):
anchor = f"{part}#p{number}"
runs = []
links = []
revisions = []
fields = []
unpreserved_whitespace = []
for node in paragraph.iter():
# A nested text-box paragraph is inspected independently.
owner = next(
(p for p in node.iterancestors() if p.tag == W + "p"), None
)
if node is not paragraph and owner is not paragraph:
continue
if node.tag == W + "r":
runs.append(
{
"text": paragraph_text(node, "all"),
"properties": _properties(node, "rPr"),
"revision_ancestors": [
ET.QName(p).localname
for p in node.iterancestors()
if p.tag in {W + n for n in REVISIONS}
],
}
)
elif node.tag == W + "hyperlink":
rid = node.get(R + "id")
links.append(
{
"text": paragraph_text(node),
"relationship_id": rid,
"bookmark": node.get(W + "anchor"),
"relationship": relationships.get(rid, {}),
}
)
elif node.tag in {W + n for n in REVISIONS}:
revisions.append(
{
"type": ET.QName(node).localname,
**_attributes(node),
"text": paragraph_text(node, "all"),
}
)
elif node.tag in {W + "instrText", W + "fldSimple"}:
fields.append(
{
"type": ET.QName(node).localname,
"instruction": node.get(W + "instr", node.text or ""),
}
)
elif node.tag in {W + "t", W + "delText"}:
value = node.text or ""
space = next(
(
parent.get(
"{http://www.w3.org/XML/1998/namespace}space"
)
for parent in [node, *node.iterancestors()]
if parent.get(
"{http://www.w3.org/XML/1998/namespace}space"
)
is not None
),
None,
)
if value != value.strip(" \t\r\n") and space != "preserve":
unpreserved_whitespace.append(value)
record = {
"anchor": anchor,
"text": paragraph_text(paragraph),
"original_text": paragraph_text(paragraph, "original"),
"runs": runs,
"hyperlinks": links,
"fields": fields,
"revisions": revisions,
"unpreserved_whitespace": unpreserved_whitespace,
"properties": _properties(paragraph, "pPr"),
"bookmarks": [
_attributes(n) for n in paragraph.iter(W + "bookmarkStart")
],
"comment_ids": [
n.get(W + "id") for n in paragraph.iter(W + "commentReference")
],
"in_table": any(
n.tag == W + "tc" for n in paragraph.iterancestors()
),
}
result["paragraphs"].append(record)
for comment in root.iter(W + "comment"):
result["comments"].append(
{
**_attributes(comment),
"part": part,
"text": "\n".join(
paragraph_text(p) for p in comment.iter(W + "p")
),
}
)
if any(
n.tag in {W + "drawing", W + "pict", W + "object", W + "altChunk"}
for n in root.iter()
):
result["warnings"].append(
f"{part}: objects/images require visual inspection; their meaning is not extracted."
)
if any(
n.tag
in {
W + "pPrChange",
W + "rPrChange",
W + "sectPrChange",
W + "tblPrChange",
}
for n in root.iter()
):
result["warnings"].append(
f"{part}: structural or formatting revisions require artifact inspection."
)
if any(
n.tag in {W + "ins", W + "del"}
and any(p.tag == W + "pPr" for p in n.iterancestors())
for n in root.iter()
):
result["warnings"].append(
f"{part}: paragraph-mark revisions affect joins/numbering; text views do not simulate layout."
)
for part in ("docProps/core.xml", "docProps/app.xml", "docProps/custom.xml"):
if part in names:
result["properties"][part] = ET.tostring(
parse_xml(archive.read(part)), encoding="unicode"
)
for part, key, tag in (
("word/styles.xml", "styles", "style"),
("word/numbering.xml", "numbering", None),
):
if part in names:
root = parse_xml(archive.read(part))
nodes = list(root.iter(W + tag)) if tag else list(root)
result[key] = [
{
"attributes": _attributes(node),
"xml": ET.tostring(node, encoding="unicode"),
}
for node in nodes
]
if key == "styles":
defaults = root.find(W + "docDefaults")
result["style_defaults"] = (
ET.tostring(defaults, encoding="unicode")
if defaults is not None
else ""
)
result["warnings"].append(
"Text views and style metadata do not verify rendered layout, signature validity or legal correctness."
)
return result
SHA-256: f64755119c0d07e1630dc7718f179b6e0bb78aaa4155c1f18752bd6692f50fbf