microsoft-word 0.0.0-stage → 0.1.3

package/scripts/docx_refresh.py

@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+"""Update fields and tables of contents with LibreOffice, then export PDF (default), DOCX or ODT.
+
+Usage:
+  python docx_refresh.py IN OUTFILE [--to pdf|docx|odt] [--force] [--timeout S] [--soffice PATH]
+                         [--json] [--allow-local-links TOKEN] [--sandboxed]
+  python docx_refresh.py --check      (JSON: soffice, bwrap, unshare, what can run here)
+
+Why: python-docx, docx.js and hand-edited XML write field results as stored text. PAGE and
+NUMPAGES are laid out at render time, but a TOC keeps its old entries until something updates
+it. A plain `soffice --convert-to pdf` updated PAGE and REF but kept a stale TOC in our test
+(LibreOffice 25.2). This script loads the file in a throwaway LibreOffice profile, updates
+every index (TOC, lists of figures) and refreshes text fields, and stores a new file.
+
+Fidelity: --to docx re-exports the whole package through LibreOffice. Styles, numbering,
+content controls, comments ranges and complex layout can change. Use it to get updated field
+results to compare or to ship as PDF; keep the original .docx as the master, or update fields
+in Word (F9, or Office.js / VBA) when the .docx itself must keep full fidelity.
+
+Safety:
+  - A .docx/.docm/.dotx/.dotm input first passes the same package checks as the other scripts
+    (200 MB uncompressed and 5000 member caps, duplicate or case-colliding names, DOCTYPE),
+    so a zip bomb never reaches LibreOffice.
+  - Runs on a private copy of the input with HOME, TMPDIR and cwd in a temp folder and a
+    minimal environment. The profile sets macro security to very high, disables document
+    macro execution and sets Writer Content/Update/Link to 0, which LibreOffice's code reads as
+    NEVER (sources in CHANGELOG.md, 0.1.2 note). The only macro that runs is this script's own refresh routine in
+    the throwaway profile; the document loads with MacroExecutionMode NEVER_EXECUTE.
+  - Isolation, best first:
+      bwrap (bubblewrap): no network, new PID/IPC/UTS namespaces, and a filesystem that holds
+        only /usr, the lib and bin links, fonts and a few /etc entries (read-only) and the
+        temp folder; no home, no /etc/passwd, no /opt except a LibreOffice installed there. Linked images, INCLUDETEXT
+        and INCLUDEPICTURE cannot read the user's files. Tested: a linked local image was
+        embedded in the PDF in every Link mode without bwrap, and was not with it.
+      unshare -n or -rn: no network, but every file the user can read is visible. Used only
+        when bwrap is missing; then the script refuses a document with external
+        relationships or INCLUDE/LINK fields. The refusal lists every target and prints a
+        token; --allow-local-links TOKEN runs it after the user has seen the list and agreed
+        (a different document gives a different token). It also refuses .doc and .rtf input (old parsers, long CVE
+        history: install bubblewrap).
+    Where neither works the script refuses (exit 2).
+  - --sandboxed is for a human or operator who has already isolated the network and the
+    filesystem. An agent must never pass it on its own, and never --allow-local-links without
+    the user's agreement. Even with --sandboxed, the script refuses if a test connection
+    succeeds.
+  - Never replaces OUTFILE unless --force; the result is moved into place only after success.
+Platforms: Linux only. On macOS and Windows there is no bwrap or unshare, so it always refuses;
+update fields in Word (F9, Office.js, VBA) or use Microsoft Graph for PDF instead.
+Proxy: bwrap and unshare remove the network entirely, so proxies do not matter there. The
+--sandboxed check is a direct TCP test, which a proxy-only network passes, so --sandboxed also
+refuses while HTTP_PROXY, HTTPS_PROXY or ALL_PROXY is set.
+Exit codes: 0 ok, 1 LibreOffice ran but produced no output, 2 setup error or refusal
+(no soffice, no isolation, output exists, bad input, local links without bwrap), 3 timeout or
+package safety refusal (size cap, duplicate entries, DOCTYPE).
+"""
+import argparse
+import hashlib
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+import json
+
+import wordpkg as wp
+from wordpkg import sniff
+
+FILTERS = {"pdf": "writer_pdf_Export", "docx": "MS Word 2007 XML", "odt": "writer8"}
+INPUT_EXT = {".docx", ".docm", ".dotx", ".dotm", ".doc", ".rtf", ".odt"}
+
+XCU = """<?xml version="1.0" encoding="UTF-8"?>
+<oor:items xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+<item oor:path="/org.openoffice.Office.Common/Security/Scripting"><prop oor:name="MacroSecurityLevel" oor:op="fuse"><value>3</value></prop></item>
+<item oor:path="/org.openoffice.Office.Common/Security/Scripting"><prop oor:name="DisableMacrosExecution" oor:op="fuse"><value>true</value></prop></item>
+<item oor:path="/org.openoffice.Office.Common/Security/Scripting"><prop oor:name="BlockUntrustedRefererLinks" oor:op="fuse"><value>true</value></prop></item>
+<item oor:path="/org.openoffice.Office.Writer/Content/Update"><prop oor:name="Link" oor:op="fuse"><value>0</value></prop></item>
+<item oor:path="/org.openoffice.Office.Common/Misc"><prop oor:name="FirstRun" oor:op="fuse"><value>false</value></prop></item>
+</oor:items>
+"""
+# Writer Content/Update/Link: SwMasterUsrPref::SetUpdateLinkMode stores the value as the enum in
+# sw/inc/linkenum.hxx (NEVER=0, MANUAL=1, AUTOMATIC=2), and the options dialog in
+# sw/source/ui/config/optload.cxx writes NEVER for the "never" button. So 0 is Never.
+# The labels in officecfg/.../Writer.xcs ("0 Always, 1 On Request, 2 Never") disagree with
+# the code; the code is what runs. Checked against the libreoffice-25-2 branch, Oct 13, 2026.
+
+MODULE = """<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">
+<script:module xmlns:script="http://openoffice.org/2000/script" script:name="Refresh" script:language="StarBasic">
+Sub Run
+  On Error Goto Fail
+  Dim a(1) As New com.sun.star.beans.PropertyValue
+  a(0).Name = &quot;Hidden&quot; : a(0).Value = True
+  a(1).Name = &quot;MacroExecutionMode&quot; : a(1).Value = 0
+  oDoc = StarDesktop.loadComponentFromURL(&quot;{IN}&quot;, &quot;_blank&quot;, 0, a())
+  If IsNull(oDoc) Then GoTo Fail
+  oIdx = oDoc.getDocumentIndexes()
+  For i = 0 To oIdx.getCount() - 1
+    oIdx.getByIndex(i).update()
+  Next i
+  oDoc.getTextFields().refresh()
+  oIdx = oDoc.getDocumentIndexes()
+  For i = 0 To oIdx.getCount() - 1
+    oIdx.getByIndex(i).update()
+  Next i
+  Dim o(0) As New com.sun.star.beans.PropertyValue
+  o(0).Name = &quot;FilterName&quot; : o(0).Value = &quot;{FILTER}&quot;
+  oDoc.storeToURL(&quot;{OUT}&quot;, o())
+  oDoc.close(True)
+  StarDesktop.terminate()
+  Exit Sub
+Fail:
+  On Error Resume Next
+  StarDesktop.terminate()
+End Sub
+</script:module>
+"""
+SCRIPT_XLB = """<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "library.dtd">
+<library:library xmlns:library="http://openoffice.org/2000/library" library:name="Standard" library:readonly="false" library:passwordprotected="false">
+ <library:element library:name="Refresh"/>
+</library:library>
+"""
+
+
+JSON = "--json" in sys.argv
+
+
+def die(code, msg):
+    msg = msg.rstrip()
+    if JSON:
+        print(json.dumps({"ok": False, "error": msg.removeprefix("error: "), "exit": code}))
+    else:
+        sys.stderr.write(msg + "\n")
+    sys.exit(code)
+
+
+SYSTEM_DIRS = ("/usr", "/bin", "/sbin", "/lib", "/lib32", "/lib64", "/var/cache/fontconfig")
+# Only what LibreOffice needs from /etc (fonts, linker cache, alternatives). Not passwd, hosts, ssl.
+ETC_ENTRIES = ("fonts", "ld.so.cache", "ld.so.conf", "ld.so.conf.d", "alternatives", "libreoffice",
+               "localtime")
+
+
+def bwrap_prefix(tmp, soffice):
+    """bubblewrap command that shows LibreOffice only system folders (read-only) and tmp."""
+    b = shutil.which("bwrap")
+    if not b or not sys.platform.startswith("linux"):
+        return None
+    args = [b, "--unshare-all", "--die-with-parent", "--new-session", "--proc", "/proc", "--dev", "/dev",
+            "--tmpfs", "/tmp", "--tmpfs", "/run"]
+    for d in SYSTEM_DIRS:
+        if os.path.islink(d):
+            args += ["--symlink", os.readlink(d), d]
+        elif os.path.isdir(d):
+            args += ["--ro-bind", d, d]
+    for e in ETC_ENTRIES:
+        if os.path.exists("/etc/" + e):
+            args += ["--ro-bind", "/etc/" + e, "/etc/" + e]
+    # An install outside /usr (for example /opt/libreoffice25.2) is bound alone, not all of /opt.
+    inst = os.path.dirname(os.path.dirname(os.path.realpath(soffice)))
+    if not any(inst == d or inst.startswith(d + "/") for d in SYSTEM_DIRS):
+        args += ["--ro-bind", inst, inst]
+    args += ["--bind", str(tmp), str(tmp), "--chdir", str(tmp)]
+    try:
+        if subprocess.run(args + ["true"], capture_output=True, timeout=10).returncode == 0:
+            return args
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def local_link_reasons(src):
+    """What LibreOffice could read: external relationships (not hyperlinks) and INCLUDE/LINK fields.
+
+    Returns (kinds, targets). targets are "type: target" strings for the user to review.
+    """
+    import inspect_docx
+    rep = inspect_docx.inspect(str(src), show_links=True)
+    kinds = sorted({t for t in rep["external_relationships"]["by_type"] if t != "hyperlink"})
+    targets = [f'{i["type"]}: {i["target"]}' for i in rep["external_relationships"]["items"]
+               if i["type"] != "hyperlink"]
+    for f in rep["fields"]["risky"]:
+        if f["type"] in ("INCLUDETEXT", "INCLUDEPICTURE", "INCLUDE", "IMPORT", "LINK"):
+            kinds.append(f["type"])
+            targets.append(f'{f["type"]} field: {f["instr"]}')
+    return sorted(set(kinds)), sorted(set(targets))
+
+
+def links_token(targets):
+    """Short hash of the target list; --allow-local-links must repeat it, so the list was seen."""
+    return hashlib.sha256("\n".join(targets).encode("utf-8")).hexdigest()[:12]
+
+
+def capabilities(soffice):
+    """What this machine can do, without converting anything (--check)."""
+    with tempfile.TemporaryDirectory(prefix="docx-refresh-check-") as tmp:
+        bw = bwrap_prefix(Path(tmp), soffice) is not None if soffice else False
+    un = no_network_prefix() is not None
+    iso = "bwrap" if bw else ("unshare (network only)" if un else None)
+    return {"ok": bool(soffice and iso), "platform": sys.platform, "soffice": soffice,
+            "bwrap": bw, "unshare": un, "isolation": iso,
+            "can_refresh_docx": bool(soffice and iso),
+            "can_refresh_doc_rtf": bool(soffice and bw),
+            "linked_documents": "isolated" if bw else ("refused unless --allow-local-links" if iso else "refused"),
+            "next": None if soffice and iso else
+            ("install LibreOffice Writer" if not soffice else
+             "install bubblewrap (apt install bubblewrap) or ask the user to update fields in Word")}
+
+
+def no_network_prefix():
+    unshare = shutil.which("unshare")
+    if not unshare or not sys.platform.startswith("linux"):
+        return None
+    for prefix in ([unshare, "-n"], [unshare, "-rn"]):
+        try:
+            if subprocess.run(prefix + ["true"], capture_output=True, timeout=10).returncode == 0:
+                return prefix
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    return None
+
+
+def network_reachable(timeout=1.0):
+    for host, port in (("1.1.1.1", 443), ("8.8.8.8", 53), ("9.9.9.9", 443)):
+        try:
+            with socket.create_connection((host, port), timeout=timeout):
+                return True
+        except OSError:
+            pass
+    return False
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input", nargs="?")
+    ap.add_argument("output", nargs="?", help="output file path, for example out/report.pdf")
+    ap.add_argument("--check", action="store_true",
+                    help="report soffice and isolation availability as JSON, convert nothing")
+    ap.add_argument("--to", choices=sorted(FILTERS), help="output format (default: from OUTFILE extension, else pdf)")
+    ap.add_argument("--force", action="store_true", help="replace OUTFILE if it exists (no backup is kept)")
+    ap.add_argument("--timeout", type=int, default=180, help="seconds before LibreOffice is killed (default 180)")
+    ap.add_argument("--soffice", help="path to soffice")
+    ap.add_argument("--json", action="store_true", help="print a JSON result with ok and error keys")
+    ap.add_argument("--allow-local-links", metavar="TOKEN",
+                    help="without bwrap, run even though the document links to files. TOKEN is printed "
+                         "by the refusal together with the list of targets; pass it only after the user "
+                         "has seen that list and agreed")
+    ap.add_argument("--sandboxed", action="store_true",
+                    help="OPERATOR ONLY: skip unshare because a human already isolated the network. "
+                         "Agents must never pass this flag.")
+    a = ap.parse_args()
+    if a.check:
+        print(json.dumps(capabilities(a.soffice or shutil.which("soffice") or shutil.which("libreoffice")),
+                         indent=2))
+        sys.exit(0)
+    if not a.input or not a.output:
+        ap.error("IN and OUTFILE are required (or use --check)")
+
+    src = Path(a.input)
+    if not src.is_file():
+        die(2, f"error: input not found: {src}")
+    if src.suffix.lower() not in INPUT_EXT:
+        die(2, f"error: unsupported input extension {src.suffix!r}")
+    kind = sniff(src)
+    if kind == "encrypted":
+        die(2, "error: encrypted document; decrypt a copy with msoffcrypto-tool and the user's password first")
+    if kind in ("other", "ole2"):
+        die(2, "error: input is not a Word, RTF or ODF document (bad magic bytes)")
+    links, targets = [], []
+    if kind == "zip":
+        try:
+            wp.Package(str(src)).zip.close()  # caps, duplicate names, content type: before LibreOffice
+            links, targets = local_link_reasons(src)
+        except wp.Refusal as e:
+            die(3, f"error: refused before LibreOffice: {e}")
+        except wp.Unsupported as e:
+            if src.suffix.lower() != ".odt":
+                die(2, f"error: {e}")
+            try:
+                with zipfile.ZipFile(src) as z:
+                    if len(z.infolist()) > 5000 or sum(i.file_size for i in z.infolist()) > 200 * 1024 * 1024:
+                        die(3, "error: refused before LibreOffice: ODT above 200 MB or 5000 members")
+            except zipfile.BadZipFile:
+                die(2, "error: input is not a valid zip package")
+        except (zipfile.BadZipFile, OSError) as e:
+            die(2, f"error: input is not a valid zip package (corrupt .docx?): {e}")
+    fmt = a.to or (Path(a.output).suffix.lower().lstrip(".") if Path(a.output).suffix.lower().lstrip(".") in FILTERS else "pdf")
+    out = Path(a.output).resolve()
+    if out.exists() and not a.force:
+        die(2, f"error: {out} exists; refusing to replace it (use --force to replace, no backup is kept)")
+    if out.exists() and out.samefile(src):
+        die(2, "error: output is the input file")
+    if not out.parent.is_dir():
+        die(2, f"error: output folder does not exist: {out.parent}")
+    soffice = a.soffice or shutil.which("soffice") or shutil.which("libreoffice")
+    if not soffice:
+        die(2, "error: LibreOffice (soffice) not found; install it or pass --soffice")
+
+    with tempfile.TemporaryDirectory(prefix="docx-refresh-") as tmp:
+        tmp = Path(tmp)
+        isolation = None
+        if a.sandboxed:
+            proxies = [k for k in os.environ if k.lower() in ("http_proxy", "https_proxy", "all_proxy")]
+            if proxies:
+                die(2, f"error: --sandboxed was given but {', '.join(sorted(proxies))} is set; a direct test "
+                       "connection cannot prove a proxy-only network is closed. Refusing.")
+            if network_reachable():
+                die(2, "error: --sandboxed was given but a test connection to the internet succeeded; refusing.")
+            prefix, isolation = [], "operator (--sandboxed)"
+        else:
+            prefix = bwrap_prefix(tmp, soffice)
+            if prefix is not None:
+                isolation = "bwrap"
+            else:
+                prefix = no_network_prefix()
+                if prefix is None:
+                    die(2, "error: cannot isolate LibreOffice here (no bwrap, unshare missing, not Linux, or user "
+                           "namespaces blocked, for example by AppArmor on Ubuntu 24.04+). Refusing. Agents: stop "
+                           "and tell the user; do not add --sandboxed yourself.")
+                isolation = "unshare (network only)"
+                if kind in ("doc", "rtf"):
+                    die(2, f"error: {kind} input needs bwrap (filesystem isolation); unshare hides only the "
+                           "network. Install bubblewrap, or ask the user to open and resave it in Word.")
+                if links and a.allow_local_links != links_token(targets):
+                    shown = "; ".join(targets[:20]) + (f"; and {len(targets) - 20} more" if len(targets) > 20 else "")
+                    die(2, f"error: the document links to outside content ({', '.join(links)}) and only network "
+                           "isolation is available, so LibreOffice could read these local files or paths "
+                           f"into the output: {shown}. Install bubblewrap, or show this list to the user and, "
+                           f"if they agree, rerun with --allow-local-links {links_token(targets)}"
+                           + (" (the token given does not match this document)" if a.allow_local_links else ""))
+                if links:
+                    sys.stderr.write("note: LibreOffice may read: " + "; ".join(targets) + "\n")
+        work = tmp / "work"
+        work.mkdir()
+        inp = work / ("input" + src.suffix.lower())
+        shutil.copyfile(src, inp)
+        res = work / ("result." + fmt)
+        prof = tmp / "profile"
+        env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin"), "HOME": str(tmp), "TMPDIR": str(tmp),
+               "LANG": os.environ.get("LANG", "C.UTF-8"), "SAL_USE_VCLPLUGIN": "svp"}
+        base = prefix + [soffice, f"-env:UserInstallation={prof.as_uri()}", "--headless", "--invisible",
+                         "--norestore", "--nologo", "--nodefault"]
+        # First start creates the profile; files written before it would be overwritten.
+        try:
+            subprocess.run(base + ["--terminate_after_init"], cwd=work, env=env, capture_output=True,
+                           timeout=a.timeout)
+        except (OSError, subprocess.TimeoutExpired) as e:
+            die(2, f"error: cannot initialise a LibreOffice profile: {e}")
+        basic = prof / "user" / "basic" / "Standard"
+        xcu = prof / "user" / "registrymodifications.xcu"
+        if not basic.is_dir() or not xcu.is_file():
+            die(2, "error: LibreOffice did not create its profile; is soffice working?")
+        items = XCU.split("<oor:items", 1)[1].split(">", 1)[1].replace("</oor:items>", "")
+        xcu.write_text(xcu.read_text(encoding="utf-8").replace("</oor:items>", items + "</oor:items>"),
+                       encoding="utf-8")
+        # Paths are fixed names under mkdtemp, so nothing from the caller reaches the Basic source.
+        (basic / "Refresh.xba").write_text(
+            MODULE.replace("{IN}", inp.as_uri()).replace("{OUT}", res.as_uri())
+                  .replace("{FILTER}", FILTERS[fmt]), encoding="utf-8")
+        (basic / "script.xlb").write_text(SCRIPT_XLB, encoding="utf-8")
+        cmd = base + ["macro:///Standard.Refresh.Run"]
+        try:
+            p = subprocess.Popen(cmd, cwd=work, env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                 text=True, start_new_session=True)
+        except OSError as e:
+            die(2, f"error: cannot start LibreOffice: {e}")
+        try:
+            _, err = p.communicate(timeout=a.timeout)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(p.pid, signal.SIGKILL)
+            except OSError:
+                pass
+            p.communicate()
+            die(3, f"error: LibreOffice did not finish within {a.timeout} s; killed. Nothing written.")
+        if not res.is_file() or res.stat().st_size == 0:
+            die(1, "error: LibreOffice produced no output (corrupt or unsupported input?). "
+                   + (err or "").strip()[-400:])
+        fd, staged = tempfile.mkstemp(prefix=".tmp-", dir=out.parent)
+        os.close(fd)
+        shutil.copyfile(res, staged)
+        os.replace(staged, out)
+    note = "LibreOffice rewrote the package, compare with the original before shipping" if fmt == "docx" else ""
+    if a.json:
+        print(json.dumps({"ok": True, "output": str(out), "format": fmt, "isolation": isolation,
+                          "engine": "LibreOffice", "links_in_input": links,
+                          "may_have_read": targets if isolation == "unshare (network only)" else [],
+                          "note": note}))
+    else:
+        print(f"ok: {out} ({fmt}); indexes updated and fields refreshed by LibreOffice; isolation {isolation}"
+              + (f"; {note}" if note else ""))
+
+
+if __name__ == "__main__":
+    main()