"""check_redaction.py: can the strings you redacted still be read out of the PDF?

Give it the redacted file and the exact values you meant to remove. It looks in
every place our tests found text surviving a redaction and prints a checklist.

    pip install pdfplumber "pikepdf>=10.9" pypdfium2  # required
    pip install pytesseract                            # optional, for --ocr (needs Tesseract)

    python check_redaction.py redacted.pdf "Jane Ray" "987-65-4322" "(312) 555-0138"
    python check_redaction.py redacted.pdf --ocr "Jane Ray" ...

Exit code 0: none of the values was found in the places checked, and each of them
was read (not checked: page thumbnails, XFA data, application private data). Exit code
1: at least one was found (each hit is listed). Exit code 2: none was found, but
something was not read: images without --ocr, an image it could not decode
(JBIG2 needs jbig2dec), a content stream it could not parse, an earlier
revision it could not open, or an attachment that is neither a PDF nor UTF-8 or
UTF-16 text (a .docx, a zip or a picture, for example). Bad arguments exit with
64. Matching ignores case; all checks except the viewer search also ignore
spaces, line breaks and dashes, so "987-65-4322" matches "987 65 4322".

Images are found wherever a page can draw them: in its resources, inside form
XObjects, patterns, Type 3 fonts and annotation appearances, at any
depth, and inline in a content stream. An attached PDF gets every check, and so
does each earlier revision (except OCR of the rendered page).

What it cannot do: find values you did not list, read text drawn as vector
paths, read inside attachments that are not PDFs or plain text, or prove that
no other copy of the document exists. Without --ocr it does not read pixels, so
a file with images never passes (exit 2).

From "Can a Redacted PDF Be Unredacted? What We Recovered" (HyperAPI blog,
November 2026). SPDX-License-Identifier: MIT
"""
import hashlib
import io
import re
import sys

import pdfplumber
import pikepdf
import pypdfium2 as pdfium

SEP = re.compile(r"[\s\-‐-―­]")
MAX_NEST = 5  # attached PDFs inside attached PDFs


def norm(s):
    return SEP.sub("", s).lower()


class Report:
    def __init__(self, secrets):
        self.secrets = secrets
        self.rows = []  # (place, [values found] or None for "not checked", note)

    def check(self, place, text, note=""):
        t = norm(text)
        self.rows.append((place, [s for s in self.secrets if norm(s) and norm(s) in t], note))

    def skip(self, place, note):
        self.rows.append((place, None, note))

    def merge(self, place, sub, note=""):
        """Fold the rows of another report (an attached PDF, an earlier revision) into one."""
        self.rows.append((place, sorted({s for _, h, _ in sub.rows if h for s in h}), note))
        for p, h, n in sub.rows:
            if h is None:
                self.skip(place, f"{p}: {n}")


def page_text(raw):
    with pdfplumber.open(io.BytesIO(raw)) as pdf:
        return [p.extract_text() or "" for p in pdf.pages]


def viewer_search(raw, secrets):
    """PDFium's find, the engine behind Chrome's built-in PDF viewer."""
    doc = pdfium.PdfDocument(raw)
    hits = []
    for i in range(len(doc)):
        tp = doc[i].get_textpage()
        for s in secrets:
            searcher = tp.search(s, match_case=False)
            if searcher.get_next() is not None:
                hits.append(f"{s} (page {i + 1})")
            searcher.close()
        tp.close()
    doc.close()
    return hits


def all_images(pdf):
    """Every image the pages can draw: {fingerprint: decoder}, plus a count of
    content streams that could not be parsed (they may hold inline images)."""
    found, seen, bad = {}, set(), 0

    def add(data, decoder):
        found.setdefault(hashlib.sha256(data).hexdigest(), decoder)

    def drawing(obj, res, depth):
        """A content stream (page, form, pattern, glyph, appearance) and its resources."""
        nonlocal bad
        if depth > 50 or (obj.is_indirect and obj.objgen in seen):
            return
        if obj.is_indirect:
            seen.add(obj.objgen)
        if isinstance(obj, pikepdf.Stream):
            res = obj.get("/Resources", res)
        try:
            for ins in pikepdf.parse_content_stream(obj):
                if isinstance(ins, pikepdf.ContentStreamInlineImage):
                    add(ins.iimage.unparse(), ins.iimage.as_pil_image)
        except Exception:  # noqa: counted, never passed
            bad += 1
        if not isinstance(res, pikepdf.Dictionary):
            return
        for xo in res.get("/XObject", pikepdf.Dictionary()).values():
            if xo.get("/Subtype") == "/Image":
                add(xo.read_raw_bytes() + f"{xo.get('/Width')}x{xo.get('/Height')}".encode(),
                    lambda xo=xo: pikepdf.PdfImage(xo).as_pil_image())
            elif xo.get("/Subtype") == "/Form":
                drawing(xo, res, depth + 1)
        for pat in res.get("/Pattern", pikepdf.Dictionary()).values():
            if isinstance(pat, pikepdf.Stream):  # PatternType 1: a pattern with its own drawing
                drawing(pat, res, depth + 1)
        for font in res.get("/Font", pikepdf.Dictionary()).values():
            if font.get("/Subtype") == "/Type3":
                for glyph in font.get("/CharProcs", pikepdf.Dictionary()).values():
                    drawing(glyph, font.get("/Resources", res), depth + 1)

    for page in pdf.pages:
        node, res = page.obj, None
        for _ in range(50):  # /Resources can be inherited from the page tree
            if "/Resources" in node or "/Parent" not in node:
                res = node.get("/Resources")
                break
            node = node.Parent
        drawing(page.obj, res, 0)
        for a in page.obj.get("/Annots", pikepdf.Array()):
            for ap in a.get("/AP", pikepdf.Dictionary()).values():  # /N, /R, /D
                for s in [ap] if isinstance(ap, pikepdf.Stream) else ap.values():
                    if isinstance(s, pikepdf.Stream):
                        drawing(s, res, 1)
    return found, bad


def attachments(pdf):
    """(name, bytes or the error) for embedded files and file-attachment annotations."""
    out = []
    for name, spec in pdf.attachments.items():
        try:
            out.append((name, spec.get_file().read_bytes()))
        except Exception as e:  # noqa: keep going, but say so
            out.append((name, e))
    for page in pdf.pages:
        for a in page.obj.get("/Annots", pikepdf.Array()):
            fs = a.get("/FS") if a.get("/Subtype") == "/FileAttachment" else None
            if isinstance(fs, pikepdf.Dictionary) and "/EF" in fs:
                f = fs.EF.get("/UF", fs.EF.get("/F"))
                name = str(fs.get("/UF", fs.get("/F", "file annotation")))
                out.append((name, f.read_bytes() if isinstance(f, pikepdf.Stream) else ValueError("no stream")))
    return out


def verify(path, secrets, ocr=False):
    return verify_bytes(open(path, "rb").read(), secrets, ocr)


def verify_bytes(raw, secrets, ocr=False, done=None, nest=0, revisions=True, render=True):
    """Run every check on one PDF. `done` holds the fingerprints of images
    already read (or already reported as not read), so an image shared by
    several revisions or attachments is counted once."""
    done = set() if done is None else done
    r = Report(secrets)
    pdf = pikepdf.open(io.BytesIO(raw))

    # 1. The text layer: what copy-paste and any text extractor read.
    r.check("page text (pdfplumber)", "\n".join(page_text(raw)))

    # 2. What a viewer's Find box finds.
    found = viewer_search(raw, secrets)
    r.rows.append(("viewer search (PDFium)", [h.split(" (page")[0] for h in found], ", ".join(found)))

    # 3. Document metadata: the Info dictionary and the XMP packet.
    info = " ".join(str(v) for v in pdf.docinfo.values()) if "/Info" in pdf.trailer else ""
    xmp = pdf.Root.Metadata.read_bytes().decode("utf-8", "replace") if "/Metadata" in pdf.Root else ""
    r.check("metadata (Info + XMP)", info + "\n" + xmp)

    # 4. Annotations (comments, sticky notes) and 5. form-field values.
    ann, fields = [], []
    for page in pdf.pages:
        for a in page.obj.get("/Annots", []):
            if a.get("/Subtype") == "/Widget":
                fields.append(str(a.get("/V", "")))
            else:
                ann.extend(str(a.get(k, "")) for k in ("/Contents", "/T", "/Subj", "/RC"))

    def walk(items, depth=0):
        for f in items:
            fields.append(str(f.get("/V", "")))
            if depth < 50:
                walk(f.get("/Kids", []), depth + 1)

    if "/AcroForm" in pdf.Root:
        walk(pdf.Root.AcroForm.get("/Fields", []))
    r.check("annotations / comments", "\n".join(ann))
    r.check("form-field values", "\n".join(fields))

    # 6. Bookmarks (the outline).
    titles = []
    with pdf.open_outline() as outline:
        stack = list(outline.root)
        while stack:
            item = stack.pop()
            titles.append(item.title or "")
            stack.extend(item.children)
    r.check("bookmarks", "\n".join(titles))

    # 9 (run first, reported last). Pixels: a box drawn over a scan does not
    #    change the stored image. Read before the attachments and revisions so
    #    the hits on this file's own images are reported on this file.
    pix = Report(secrets)
    images, bad = all_images(pdf)
    if bad:
        pix.skip("stored images", f"{bad} content stream(s) could not be parsed")
    new = {k: v for k, v in images.items() if k not in done}
    done.update(new)
    if ocr:
        import pytesseract  # optional dependency
        stored, failed = [], 0
        for decode in new.values():
            try:
                stored.append(pytesseract.image_to_string(decode()))
            except Exception:  # e.g. JBIG2 without jbig2dec: counted, never passed
                failed += 1
        pix.check("stored images (OCR)", "\n".join(stored), f"{len(images)} image(s)")
        if failed:
            pix.skip("stored images", f"{failed} image(s) could not be decoded")
        if render:
            doc = pdfium.PdfDocument(raw)
            seen = [pytesseract.image_to_string(doc[i].render(scale=200 / 72).to_pil()) for i in range(len(doc))]
            doc.close()
            pix.check("rendered page (OCR)", "\n".join(seen), "what a reader sees")
    elif new:
        pix.skip("stored images", f"{len(new)} image(s) not read: run again with --ocr")

    # 7. Embedded files. An attached PDF gets every check; text is searched;
    #    anything else (a .docx, a zip, a picture) is reported as not read.
    files = attachments(pdf)
    text, sub = [], Report(secrets)
    for name, data in files:
        text.append(name)
        if isinstance(data, Exception):
            sub.skip("attachment", f"{name}: could not be read ({data})")
        elif b"%PDF-" in data[:1024]:
            if nest >= MAX_NEST:
                sub.skip("attached PDF", f"{name}: nested too deep")
                continue
            try:
                sub.merge("attached PDF", verify_bytes(data, secrets, ocr, done, nest + 1))
            except Exception as e:  # noqa: keep going, but say so
                sub.skip("attached PDF", f"{name}: could not be opened ({e})")
        else:
            try:
                if data[:2] == b"PK":
                    raise UnicodeError("zip container")
                bom16 = data[:2] in (b"\xff\xfe", b"\xfe\xff")
                text.append(data.decode("utf-16" if bom16 else "utf-8-sig"))
            except UnicodeError:
                sub.skip("attachment", f"{name}: not a PDF or text file, not read")
    sub.check("names and text", "\n".join(text))
    r.merge("attachments", sub, f"{len(files)} file(s)")

    # 8. Earlier revisions: an incremental save appends changes and keeps the
    #    old objects. Cut the file at each earlier %%EOF and give that version
    #    the same checks: page text, viewer search, metadata, comments, form
    #    fields, bookmarks, attachments and stored images.
    if revisions:
        ends = [m.end() for m in re.finditer(rb"%%EOF", raw)]
        old, unreadable = Report(secrets), 0
        for k, end in enumerate(ends[:-1]):
            try:
                rev = verify_bytes(raw[:end], secrets, ocr, done, nest, revisions=False, render=False)
                old.merge("revision", rev)
            except Exception:  # a linearised file's first section is not a full PDF
                if not (k == 0 and pdf.is_linearized):
                    unreadable += 1
        r.merge("earlier revisions", old, f"{len(ends)} %%EOF marker(s)")
        if unreadable:
            r.skip("earlier revisions", f"{unreadable} could not be opened")

    r.rows.extend(pix.rows)
    return r


def verdict(rows):
    """Exit code and RESULT line: 1 found, 2 something not read, 0 clean."""
    if any(hits for _, hits, _ in rows):
        return 1, "values recoverable, not safe to share"
    notes = [note for _, hits, note in rows if hits is None]
    if notes and all(n.endswith("run again with --ocr") for n in notes):
        return 2, "images not checked: rerun with --ocr"
    if notes:
        return 2, "not everything was read: see NOT CHECKED"
    return 0, "none of the listed values found"


def main(argv):
    ocr = "--ocr" in argv
    args = [a for a in argv if a != "--ocr"]
    if len(args) < 2:
        print(__doc__)
        return 64
    r = verify(args[0], args[1:], ocr=ocr)
    for place, hits, note in r.rows:
        status = "NOT CHECKED" if hits is None else "FOUND" if hits else "clean"
        line = f"[{status:^11}] {place}"
        if hits:
            line += ": " + ", ".join(sorted(set(hits)))
        if note and not hits:
            line += f"  ({note})"
        print(line)
    code, result = verdict(r.rows)
    print("\nRESULT:", result)
    return code


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
