← Files Codex SecurityARCHIVED FILE

scripts/windows_scan_local_files.py

59.3 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

"""Secure scan-local file operations for Windows.

Windows does not implement Python's descriptor-relative ``dir_fd`` APIs or
``O_NOFOLLOW``.  This module provides the three operations needed by the scan
finalizer without falling back to check-then-use path validation.

Scan-local reads, writes, and deletes open every directory with
``FILE_FLAG_OPEN_REPARSE_POINT`` and reject all reparse points, including junctions.
Directory handles remain open without ``FILE_SHARE_DELETE`` for the full
operation, which prevents an
already-validated ancestor from being renamed or replaced during a read,
write, or delete.  Writes rename the exact temporary-file handle into place so
an attacker cannot substitute another file at the temporary name.

The snapshot helper copies junction metadata without opening the link target.

Importing this module and comparing streams work on every platform. Filesystem
operations raise ``WindowsScanLocalFileError`` outside Windows.
"""

from __future__ import annotations

import argparse
import contextlib
import ctypes
import ctypes.wintypes as wintypes
import errno
import functools
import importlib
import ntpath
import os
import secrets
import struct
from collections.abc import Callable, Iterator
from pathlib import Path, PurePosixPath
from typing import BinaryIO

_msvcrt = importlib.import_module("msvcrt") if os.name == "nt" else None


class WindowsScanLocalFileError(OSError):
    """Raised when a scan-local operation cannot be completed securely."""


class WindowsScanLocalPathError(WindowsScanLocalFileError):
    """Raised when a scan-local path fails an integrity check."""


# CreateFile access and sharing flags.
_DRIVE_FIXED = 3
_DELETE = 0x00010000
_FILE_ADD_SUBDIRECTORY = 0x00000004
_FILE_DELETE_CHILD = 0x00000040
_CHANGE_ACL = 0x000C0000  # WRITE_DAC | WRITE_OWNER
_SET_REPARSE_POINT = 0x00000102  # FILE_WRITE_ATTRIBUTES | FILE_WRITE_DATA
_OUTPUT_RIGHTS = (
    _DELETE | _FILE_ADD_SUBDIRECTORY | _FILE_DELETE_CHILD | _CHANGE_ACL | _SET_REPARSE_POINT
)
_FILE_TRAVERSE = 0x00000020
_FILE_READ_ATTRIBUTES = 0x00000080
_READ_CONTROL = 0x00020000
_GENERIC_READ = 0x80000000
_GENERIC_WRITE = 0x40000000
_FILE_SHARE_READ = 0x00000001
_FILE_SHARE_WRITE = 0x00000002
_FILE_SHARE_DELETE = 0x00000004

# CreateFile dispositions, attributes, and flags.
_CREATE_NEW = 1
_OPEN_EXISTING = 3
_FILE_ATTRIBUTE_DIRECTORY = 0x00000010
_FILE_ATTRIBUTE_NORMAL = 0x00000080
_FILE_ATTRIBUTE_REPARSE_POINT = 0x00000400
_REPARSE_TAG_NAME_SURROGATE = 0x20000000
_FILE_FLAG_BACKUP_SEMANTICS = 0x02000000
_FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000

# GetFileInformationByHandleEx / SetFileInformationByHandle classes.
_FILE_RENAME_INFO_CLASS = 3
_FILE_DISPOSITION_INFO_CLASS = 4
_FILE_ATTRIBUTE_TAG_INFO_CLASS = 9
_FILE_ID_INFO_CLASS = 18

_FILE_TYPE_DISK = 0x0001
_FILE_NAME_OPENED = 0x00000008
_ERROR_FILE_NOT_FOUND = 2
_ERROR_PATH_NOT_FOUND = 3
_ERROR_ACCESS_DENIED = 5
_ERROR_SHARING_VIOLATION = 32
_ERROR_LOCK_VIOLATION = 33
_ERROR_FILE_EXISTS = 80
_ERROR_INSUFFICIENT_BUFFER = 122
_ERROR_ALREADY_EXISTS = 183
_ERROR_DIRECTORY = 267
_OWNER_SECURITY_INFORMATION = 0x00000001
_DACL_SECURITY_INFORMATION = 0x00000004
_MISSING_ERRORS = {_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND}
_COLLISION_ERRORS = {_ERROR_FILE_EXISTS, _ERROR_ALREADY_EXISTS}
_INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
_MAX_COMPARE_CHUNK = 64 * 1024
_MAX_WRITE_CHUNK = 1024 * 1024

_INVALID_COMPONENT_CHARACTERS = frozenset('<>:"|?*')
_RESERVED_DEVICE_NAMES = {
    "AUX",
    "CON",
    "CONIN$",
    "CONOUT$",
    "NUL",
    "PRN",
    *(f"COM{number}" for number in range(1, 10)),
    *(f"LPT{number}" for number in range(1, 10)),
    *(f"COM{number}" for number in "¹²³"),
    *(f"LPT{number}" for number in "¹²³"),
}


class _FileBasicInfo(ctypes.Structure):
    _fields_ = [
        ("CreationTime", ctypes.c_int64),
        ("LastAccessTime", ctypes.c_int64),
        ("LastWriteTime", ctypes.c_int64),
        ("ChangeTime", ctypes.c_int64),
        ("FileAttributes", wintypes.DWORD),
    ]


class _FileAttributeTagInfo(ctypes.Structure):
    _fields_ = [
        ("FileAttributes", wintypes.DWORD),
        ("ReparseTag", wintypes.DWORD),
    ]


class _FileIdInfo(ctypes.Structure):
    _fields_ = [("VolumeSerialNumber", ctypes.c_uint64), ("FileId", ctypes.c_ubyte * 16)]


class _ByHandleFileInformation(ctypes.Structure):
    _fields_ = [
        ("dwFileAttributes", wintypes.DWORD),
        ("ftCreationTime", wintypes.FILETIME),
        ("ftLastAccessTime", wintypes.FILETIME),
        ("ftLastWriteTime", wintypes.FILETIME),
        ("dwVolumeSerialNumber", wintypes.DWORD),
        ("nFileSizeHigh", wintypes.DWORD),
        ("nFileSizeLow", wintypes.DWORD),
        ("nNumberOfLinks", wintypes.DWORD),
        ("nFileIndexHigh", wintypes.DWORD),
        ("nFileIndexLow", wintypes.DWORD),
    ]


class _SecurityAttributes(ctypes.Structure):
    _fields_ = [
        ("length", wintypes.DWORD),
        ("descriptor", wintypes.LPVOID),
        ("inherit", wintypes.BOOL),
    ]


class _FileDispositionInfo(ctypes.Structure):
    _fields_ = [("DeleteFile", wintypes.BOOLEAN)]


class _FileRenameInfo(ctypes.Structure):
    # The first field is a union.  FileRenameInfo interprets its low byte as
    # ReplaceIfExists; representing the union as DWORD also provides the
    # correct alignment for RootDirectory on 32-bit and 64-bit Windows.
    _fields_ = [
        ("FlagsOrReplaceIfExists", wintypes.DWORD),
        ("RootDirectory", wintypes.HANDLE),
        ("FileNameLength", wintypes.DWORD),
        ("FileName", wintypes.WCHAR * 1),
    ]


class _OwnedHandle:
    """Own a Win32 HANDLE and close it exactly once."""

    def __init__(self, value: int) -> None:
        self.value: int | None = value

    def close(self) -> None:
        if self.value is not None:
            _close_handle(self.value)
            self.value = None

    def detach(self) -> int:
        if self.value is None:
            raise RuntimeError("handle is already closed")
        value = self.value
        self.value = None
        return value

    def __enter__(self) -> _OwnedHandle:
        return self

    def __exit__(self, *_: object) -> None:
        self.close()


if os.name == "nt":
    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
    _advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
    _ntdll = ctypes.WinDLL("ntdll")

    _GetFileSecurityW = _advapi32.GetFileSecurityW
    _GetFileSecurityW.argtypes = [
        wintypes.LPCWSTR,
        wintypes.DWORD,
        wintypes.LPVOID,
        wintypes.DWORD,
        ctypes.POINTER(wintypes.DWORD),
    ]
    _GetFileSecurityW.restype = wintypes.BOOL

    _GetDriveTypeW = _kernel32.GetDriveTypeW
    _GetDriveTypeW.argtypes = [wintypes.LPCWSTR]
    _GetDriveTypeW.restype = wintypes.UINT

    _CreateFileW = _kernel32.CreateFileW
    _CreateFileW.argtypes = [
        wintypes.LPCWSTR,
        wintypes.DWORD,
        wintypes.DWORD,
        wintypes.LPVOID,
        wintypes.DWORD,
        wintypes.DWORD,
        wintypes.HANDLE,
    ]
    _CreateFileW.restype = wintypes.HANDLE

    _ReOpenFile = _kernel32.ReOpenFile
    _ReOpenFile.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD]
    _ReOpenFile.restype = wintypes.HANDLE

    _CreateDirectoryW = _kernel32.CreateDirectoryW
    _CreateDirectoryW.argtypes = [wintypes.LPCWSTR, wintypes.LPVOID]
    _CreateDirectoryW.restype = wintypes.BOOL

    _CloseHandle = _kernel32.CloseHandle
    _CloseHandle.argtypes = [wintypes.HANDLE]
    _CloseHandle.restype = wintypes.BOOL

    _GetFileInformationByHandleEx = _kernel32.GetFileInformationByHandleEx
    _GetFileInformationByHandleEx.argtypes = [
        wintypes.HANDLE,
        ctypes.c_int,
        wintypes.LPVOID,
        wintypes.DWORD,
    ]
    _GetFileInformationByHandleEx.restype = wintypes.BOOL
    _GetFileInformationByHandle = _kernel32.GetFileInformationByHandle
    _GetFileInformationByHandle.argtypes = [
        wintypes.HANDLE,
        ctypes.POINTER(_ByHandleFileInformation),
    ]
    _GetFileInformationByHandle.restype = wintypes.BOOL

    _GetFileType = _kernel32.GetFileType
    _GetFileType.argtypes = [wintypes.HANDLE]
    _GetFileType.restype = wintypes.DWORD

    _GetFinalPathNameByHandleW = _kernel32.GetFinalPathNameByHandleW
    _GetFinalPathNameByHandleW.argtypes = [
        wintypes.HANDLE,
        wintypes.LPWSTR,
        wintypes.DWORD,
        wintypes.DWORD,
    ]
    _GetFinalPathNameByHandleW.restype = wintypes.DWORD

    _SetFileInformationByHandle = _kernel32.SetFileInformationByHandle
    _SetFileInformationByHandle.argtypes = [
        wintypes.HANDLE,
        ctypes.c_int,
        wintypes.LPVOID,
        wintypes.DWORD,
    ]
    _SetFileInformationByHandle.restype = wintypes.BOOL

    _WriteFile = _kernel32.WriteFile
    _WriteFile.argtypes = [
        wintypes.HANDLE,
        wintypes.LPCVOID,
        wintypes.DWORD,
        ctypes.POINTER(wintypes.DWORD),
        wintypes.LPVOID,
    ]
    _WriteFile.restype = wintypes.BOOL

    _DeviceIoControl = _kernel32.DeviceIoControl
    _DeviceIoControl.argtypes = [
        wintypes.HANDLE,
        wintypes.DWORD,
        wintypes.LPVOID,
        wintypes.DWORD,
        wintypes.LPVOID,
        wintypes.DWORD,
        ctypes.POINTER(wintypes.DWORD),
        wintypes.LPVOID,
    ]
    _DeviceIoControl.restype = wintypes.BOOL

    _FlushFileBuffers = _kernel32.FlushFileBuffers
    _FlushFileBuffers.argtypes = [wintypes.HANDLE]
    _FlushFileBuffers.restype = wintypes.BOOL
else:
    _kernel32 = None


def _require_windows() -> None:
    if _kernel32 is None:
        raise WindowsScanLocalFileError(
            errno.ENOSYS,
            "secure Windows scan-local file operations require Windows",
        )


def _raise_last_error(operation: str, path: Path | None = None) -> None:
    error = ctypes.get_last_error()
    detail = ctypes.FormatError(error).strip()
    target = f" for {path}" if path is not None else ""
    raise WindowsScanLocalFileError(error, f"{operation}{target}: {detail}", str(path or ""))


def _invalid_path(path: Path | str, reason: str) -> WindowsScanLocalPathError:
    return WindowsScanLocalPathError(errno.EINVAL, reason, str(path))


def _validated_parts(relative_path: str) -> tuple[str, ...]:
    """Validate a POSIX contract path against Windows filesystem aliases."""

    path = PurePosixPath(relative_path)
    normalized = path.as_posix()
    if (
        not relative_path
        or normalized == "."
        or path.is_absolute()
        or ".." in path.parts
        or "\\" in relative_path
        or "\0" in relative_path
    ):
        raise _invalid_path(relative_path, "expected a safe scan-relative POSIX path")

    for component in path.parts:
        if (
            any(character in _INVALID_COMPONENT_CHARACTERS for character in component)
            or any(ord(character) < 32 for character in component)
            or component.endswith((" ", "."))
        ):
            raise _invalid_path(relative_path, "path contains a Windows-unsafe component")
        device_name = component.split(".", 1)[0].upper()
        if device_name in _RESERVED_DEVICE_NAMES:
            raise _invalid_path(relative_path, "path contains a reserved Windows device name")
    return path.parts


def _extended_path(path: Path) -> str:
    """Return a Win32 extended-length path so long scan paths remain usable."""

    value = str(path)
    if value.startswith("\\\\?\\"):
        return value
    if value.startswith("\\\\"):
        return "\\\\?\\UNC\\" + value[2:]
    return "\\\\?\\" + value


def _normalized_windows_path(path: Path | str) -> str:
    value = str(path)
    if value.startswith("\\\\?\\UNC\\"):
        value = "\\\\" + value[8:]
    elif value.startswith("\\\\?\\"):
        value = value[4:]
    return ntpath.normcase(ntpath.normpath(value))


def _close_handle(handle: int) -> None:
    _require_windows()
    if not _CloseHandle(handle):
        _raise_last_error("CloseHandle")


def _create_file(
    path: Path,
    *,
    access: int,
    share: int,
    disposition: int,
    flags: int,
    missing_ok: bool = False,
) -> _OwnedHandle | None:
    _require_windows()
    handle = _CreateFileW(
        _extended_path(path),
        access,
        share,
        None,
        disposition,
        flags,
        None,
    )
    if handle == _INVALID_HANDLE_VALUE:
        error = ctypes.get_last_error()
        if missing_ok and error in _MISSING_ERRORS:
            return None
        _raise_last_error("CreateFileW", path)
    return _OwnedHandle(int(handle))


def copy_directory_junction(source: Path, destination: Path) -> None:
    """Copy raw junction data to an empty directory without opening the link target."""
    # MAXIMUM_REPARSE_DATA_BUFFER_SIZE, including the reparse data header.
    data = ctypes.create_string_buffer(16 * 1024)
    size = wintypes.DWORD()
    for path, write in ((source, False), (destination, True)):
        handle = _create_file(
            path,
            access=_GENERIC_WRITE if write else _FILE_READ_ATTRIBUTES,
            share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
            disposition=_OPEN_EXISTING,
            flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
        )
        assert handle is not None
        with handle:
            if not _DeviceIoControl(
                handle.value,
                0x000900A4 if write else 0x000900A8,  # FSCTL_SET/GET_REPARSE_POINT.
                data if write else None,
                size.value if write else 0,
                None if write else data,
                0 if write else len(data),
                ctypes.byref(size),
                None,
            ):
                _raise_last_error("Copy directory junction", path)


def _attributes(handle: int) -> _FileAttributeTagInfo:
    info = _FileAttributeTagInfo()
    if not _GetFileInformationByHandleEx(
        handle,
        _FILE_ATTRIBUTE_TAG_INFO_CLASS,
        ctypes.byref(info),
        ctypes.sizeof(info),
    ):
        _raise_last_error("GetFileInformationByHandleEx")
    return info


def _final_path(handle: int, *, opened_name: bool = False) -> str:
    flags = _FILE_NAME_OPENED if opened_name else 0
    size = _GetFinalPathNameByHandleW(handle, None, 0, flags)
    if size == 0:
        _raise_last_error("GetFinalPathNameByHandleW")
    buffer = ctypes.create_unicode_buffer(size + 1)
    written = _GetFinalPathNameByHandleW(handle, buffer, len(buffer), flags)
    if written == 0 or written >= len(buffer):
        _raise_last_error("GetFinalPathNameByHandleW")
    return buffer.value


def _verify_handle_path(handle: int, expected_path: Path, *, opened_name: bool = False) -> None:
    actual = _normalized_windows_path(_final_path(handle, opened_name=opened_name))
    expected = _normalized_windows_path(expected_path)
    if actual != expected:
        raise _invalid_path(expected_path, "opened file resolved outside its verified scan path")


def _verify_directory(handle: int, expected_path: Path, checkout: bool = False) -> None:
    info = _attributes(handle)
    if info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT and (
        not checkout or not info.ReparseTag or info.ReparseTag & _REPARSE_TAG_NAME_SURROGATE
    ):
        raise _invalid_path(expected_path, "scan-local directories must not be reparse points")
    if not info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY:
        raise _invalid_path(expected_path, "expected a scan-local directory")
    _verify_handle_path(handle, expected_path)


def _verify_regular_file(handle: int, expected_path: Path) -> None:
    info = _attributes(handle)
    if info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
        raise _invalid_path(expected_path, "scan-local files must not be reparse points")
    if info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY or _GetFileType(handle) != _FILE_TYPE_DISK:
        raise _invalid_path(expected_path, "expected a regular scan-local file")
    _verify_handle_path(handle, expected_path)


def _canonical_scan_directory(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
    absolute = Path(scan_dir).absolute()
    try:
        expected = absolute.lstat()
        canonical = absolute.resolve(strict=True)
    except OSError as exc:
        if exc.errno not in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
            raise
        raise _invalid_path(scan_dir, "expected an existing scan directory") from exc
    if _normalized_windows_path(absolute) != _normalized_windows_path(canonical):
        raise _invalid_path(scan_dir, "scan directory must be canonical and non-reparse")
    return canonical, (expected.st_dev, expected.st_ino)


def _open_directory(
    path: Path,
    *,
    missing_ok: bool = False,
    missing_is_path_error: bool = True,
    movable: bool = False,
    checkout: bool = False,
) -> _OwnedHandle | None:
    try:
        handle = _create_file(
            path,
            # Attribute-only handles do not participate in Win32 sharing checks.
            access=_FILE_READ_ATTRIBUTES | (0 if movable else _FILE_TRAVERSE),
            share=_FILE_SHARE_READ | _FILE_SHARE_WRITE | (_FILE_SHARE_DELETE if movable else 0),
            disposition=_OPEN_EXISTING,
            flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
            missing_ok=missing_ok,
        )
    except WindowsScanLocalFileError as exc:
        if exc.errno != _ERROR_DIRECTORY and not (
            missing_is_path_error and exc.errno in _MISSING_ERRORS
        ):
            raise
        raise _invalid_path(path, f"could not open scan-local directory: {exc}") from exc
    if handle is not None:
        try:
            assert handle.value is not None
            _verify_directory(handle.value, path, checkout)
        except BaseException:
            handle.close()
            raise
    return handle


def _create_directory(path: Path) -> None:
    if _CreateDirectoryW(_extended_path(path), None):
        return
    error = ctypes.get_last_error()
    if error not in _COLLISION_ERRORS:
        _raise_last_error("CreateDirectoryW", path)


def _directory_security_descriptor(source: Path, information: int) -> ctypes.Array:
    source_path = _extended_path(source)
    size = wintypes.DWORD()
    _GetFileSecurityW(source_path, information, None, 0, ctypes.byref(size))
    if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
        _raise_last_error("GetFileSecurityW", source)
    descriptor = ctypes.create_string_buffer(size.value)
    if not _GetFileSecurityW(source_path, information, descriptor, size.value, ctypes.byref(size)):
        _raise_last_error("GetFileSecurityW", source)
    return descriptor


def _sid_text(sid: wintypes.LPVOID) -> str:
    value = wintypes.LPWSTR()
    if not _advapi32.ConvertSidToStringSidW(sid, ctypes.byref(value)):
        _raise_last_error("ConvertSidToStringSidW")
    try:
        return value.value
    finally:
        _kernel32.LocalFree(value)


@functools.cache
def _current_user_sid() -> str:
    token = wintypes.HANDLE(-4)  # GetCurrentProcessToken pseudo-handle.
    size = wintypes.DWORD()
    _advapi32.GetTokenInformation(token, 1, None, 0, ctypes.byref(size))
    if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
        _raise_last_error("GetTokenInformation")
    user = ctypes.create_string_buffer(size.value)
    if not _advapi32.GetTokenInformation(token, 1, user, size, ctypes.byref(size)):
        _raise_last_error("GetTokenInformation")
    return _sid_text(wintypes.LPVOID.from_buffer(user))


def _output_directory_grants(handle: int, path: Path, *, expected_descriptor=None) -> int:
    """Inspect the descriptor of the opened directory, even if its pathname changes."""
    owner, acl, descriptor = wintypes.LPVOID(), wintypes.LPVOID(), wintypes.LPVOID()
    status = _advapi32.GetSecurityInfo(
        wintypes.HANDLE(handle),
        1,
        _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION,
        ctypes.byref(owner),
        None,
        ctypes.byref(acl),
        None,
        ctypes.byref(descriptor),
    )
    if status:
        raise ctypes.WinError(status)
    try:
        if expected_descriptor is not None and _generated_directory_policy(
            descriptor
        ) != _generated_directory_policy(expected_descriptor):
            raise _invalid_path(path, "new scan directory lacks its private owner or DACL")
        trusted = {
            _current_user_sid(),
            "S-1-5-18",
            "S-1-5-32-544",  # Current user, SYSTEM, Administrators.
            "S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464",  # TrustedInstaller.
        }
        if _sid_text(owner) not in trusted:
            raise _invalid_path(path, "Scan output directory must have a trusted owner.")
        return _output_dacl_grants(acl, trusted, path)
    finally:
        _kernel32.LocalFree(descriptor)


def _authenticated_account(sid: wintypes.LPVOID, trustee: str) -> bool:
    # The Guest account can have its own SID without Authenticated Users membership.
    if not trustee.startswith("S-1-5-21-") or trustee.endswith("-501"):
        return False
    name_size, domain_size, sid_type = (ctypes.pointer(wintypes.DWORD()) for _ in range(3))
    lookup = _advapi32.LookupAccountSidW
    lookup(None, sid, None, name_size, None, domain_size, sid_type)
    if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
        return False
    name = ctypes.create_unicode_buffer(name_size.contents.value)
    domain = ctypes.create_unicode_buffer(domain_size.contents.value)
    found = lookup(None, sid, name, name_size, domain, domain_size, sid_type)
    return bool(found) and sid_type.contents.value == 1  # SidTypeUser


def _output_dacl_grants(acl: wintypes.LPVOID, trusted: set[str], path: Path) -> int:
    if not acl.value:  # A NULL DACL grants full access.
        return _OUTPUT_RIGHTS
    # Read ACEs in DACL order. A deny masks future grants for its trustee.
    denied: dict[str, int] = {}
    granted = 0
    for index in range(wintypes.WORD.from_address(acl.value + 4).value):  # ACL.AceCount
        ace = wintypes.LPVOID()
        if not _advapi32.GetAce(acl, index, ctypes.byref(ace)):
            _raise_last_error("GetAce", path)
        kind, flags, size = struct.unpack("<BBH", ctypes.string_at(ace, 4))
        if flags & 8 or kind in {10, 12}:  # INHERIT_ONLY or conditional deny.
            continue
        entry = ctypes.string_at(ace, size)
        mask = struct.unpack_from("<I", entry, 4)[0]
        if mask & 0x10000000:  # GENERIC_ALL
            mask |= _OUTPUT_RIGHTS
        if mask & _GENERIC_WRITE:
            mask |= _FILE_ADD_SUBDIRECTORY | _SET_REPARSE_POINT
        mask &= _OUTPUT_RIGHTS
        if not mask:
            continue
        offset = 8  # ACE_HEADER and ACCESS_MASK precede the trustee SID.
        if kind in {5, 6, 11}:
            object_flags = struct.unpack_from("<I", entry, offset)[0]
            offset += 4 + 16 * (object_flags & 3).bit_count()
            if kind == 6 and object_flags & 1:
                continue  # This deny is scoped to a particular object type.
        elif kind not in {0, 1, 9}:
            raise _invalid_path(path, "Unable to evaluate scan output directory permissions.")
        if len(entry) < offset + 8 or len(entry) < offset + 8 + 4 * entry[offset + 1]:
            raise _invalid_path(path, "Invalid scan output directory trustee.")
        sid = wintypes.LPVOID(ace.value + offset)
        trustee = _sid_text(sid)
        if trustee in trusted or trustee == "S-1-3-4":  # OWNER RIGHTS applies to the checked owner.
            continue
        if kind in {1, 6}:
            denied[trustee] = denied.get(trustee, 0) | mask
        else:
            blocked = denied.get(trustee, 0) | denied.get("S-1-1-0", 0)
            authenticated = denied.get("S-1-5-11", 0)
            if mask & authenticated and _authenticated_account(sid, trustee):
                blocked |= authenticated
            granted |= mask & ~blocked
    if granted & _CHANGE_ACL:
        granted |= _OUTPUT_RIGHTS
    return granted


def _require_stable_output(path: Path, parent_grants: int, child_grants: int = 0) -> None:
    can_remove = parent_grants & _FILE_DELETE_CHILD or child_grants & _DELETE
    can_replace = parent_grants & (_FILE_ADD_SUBDIRECTORY | _SET_REPARSE_POINT)
    if can_remove and can_replace:
        raise _invalid_path(path, "Scan output directory can be replaced by another user.")


@contextlib.contextmanager
def _checked_output_directory(path: Path) -> Iterator[tuple[int | None, int, int]]:
    """Hold the checked chain and expose its parent, final directory handle and grants."""
    parent_grants = 0
    parent = None
    with contextlib.ExitStack() as pins:
        for directory in (*reversed(path.parents), path):
            if parent is None:
                handle = _create_file(
                    directory,
                    access=_FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _READ_CONTROL,
                    share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
                    disposition=_OPEN_EXISTING,
                    flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
                )
                assert handle is not None
            else:
                error, child = _relative_output_directory(parent, directory.name)
                if error:
                    raise WindowsScanLocalPathError(
                        error, ctypes.FormatError(error), str(directory)
                    )
                handle = _OwnedHandle(child)
            pins.enter_context(handle)
            assert handle.value is not None
            _verify_directory(handle.value, directory)
            grants = _output_directory_grants(handle.value, directory)
            _require_stable_output(directory, parent_grants, grants)
            containing, parent, parent_grants = parent, handle.value, grants
        yield containing, parent, parent_grants


def require_windows_output_path(path: Path, *, writable_output: bool = False) -> None:
    with _checked_output_directory(path) as (_, _, grants):
        if writable_output and grants & _SET_REPARSE_POINT:
            raise _invalid_path(
                path, "Another user can turn the output directory into a reparse point when empty."
            )


DEEP_RESUME_DIRECTORY = ".codex-security-resume"


def deep_resume_output_identity(scan_dir: Path) -> list[int]:
    """Bind the output and its protected child while every directory is pinned."""
    retained = scan_dir / DEEP_RESUME_DIRECTORY
    with _checked_output_directory(retained) as (parent, child, grants):
        assert parent is not None
        return _pinned_resume_identity(parent, child, retained, grants)


def _full_directory_id(handle: int, path: Path) -> tuple[int, int] | None:
    info = _FileIdInfo()
    if not _GetFileInformationByHandleEx(
        handle, _FILE_ID_INFO_CLASS, ctypes.byref(info), ctypes.sizeof(info)
    ):
        if ctypes.get_last_error() in {50, 87}:  # ERROR_NOT_SUPPORTED or ERROR_INVALID_PARAMETER.
            return None
        _raise_last_error("GetFileInformationByHandleEx(FileIdInfo)", path)
    file_id = int.from_bytes(info.FileId, "little")
    if not file_id:
        raise _invalid_path(path, "The resume directory has no stable file identity.")
    return info.VolumeSerialNumber, file_id


def _resume_directory_id(handle: int, path: Path) -> tuple[int, int]:
    if (identity := _full_directory_id(handle, path)) is not None:
        return identity
    # Some filesystems expose only the legacy 64-bit file index.
    legacy = _ByHandleFileInformation()
    if not _GetFileInformationByHandle(handle, ctypes.byref(legacy)):
        _raise_last_error("GetFileInformationByHandle", path)
    file_id = (legacy.nFileIndexHigh << 32) | legacy.nFileIndexLow
    if not file_id:
        raise _invalid_path(path, "The resume directory has no stable file identity.")
    return legacy.dwVolumeSerialNumber, file_id


@contextlib.contextmanager
def pinned_resume_checkout(target: Path) -> Iterator[tuple[int, int] | None]:
    """Keep the canonical checkout fixed while reading its full native identity and snapshot."""
    with contextlib.ExitStack() as pins:
        for directory in (*reversed(target.parents), target):
            # A source provider directory may carry a reparse tag without redirecting its name.
            handle = _open_directory(directory, checkout=True)
            assert handle is not None
            pins.enter_context(handle)
        assert handle.value is not None
        yield _full_directory_id(handle.value, target)


def _pinned_resume_identity(parent: int, child: int, retained: Path, grants: int) -> list[int]:
    # A nonreplaceable, protected child keeps the scan root nonempty after
    # the sandbox receives Modify there. The caller holds both directories.
    if grants:
        raise _invalid_path(retained, "The retained resume directory must be protected.")
    return [*_resume_directory_id(parent, retained.parent), *_resume_directory_id(child, retained)]


class _UnicodeString(ctypes.Structure):
    _fields_ = [
        ("length", wintypes.USHORT),
        ("capacity", wintypes.USHORT),
        ("text", wintypes.LPWSTR),
    ]


class _ObjectAttributes(ctypes.Structure):
    _fields_ = [
        ("length", wintypes.ULONG),
        ("root", wintypes.HANDLE),
        ("name", ctypes.POINTER(_UnicodeString)),
        ("attributes", wintypes.ULONG),
        ("security", wintypes.LPVOID),
        ("qos", wintypes.LPVOID),
    ]


def _relative_output_directory(
    parent: int, basename: str, descriptor=None, *, rollback_handle: bool = False
) -> tuple[int, int | None]:
    """Open or create one component relative to its checked parent without reparsing it."""
    size = len(basename.encode("utf-16-le", errors="surrogatepass"))
    if size >= 1 << 16:  # UNICODE_STRING.Length is a byte count in a USHORT.
        return 206, None
    name = _UnicodeString(size, size, basename)
    attributes = _ObjectAttributes(
        ctypes.sizeof(_ObjectAttributes),
        parent,
        ctypes.pointer(name),
        0x40 | 0x1000,  # OBJ_CASE_INSENSITIVE | OBJ_DONT_REPARSE
        descriptor,
        None,
    )
    handle = wintypes.HANDLE()
    io_status = (ctypes.c_void_p * 2)()  # IO_STATUS_BLOCK
    status = _ntdll.NtCreateFile(
        ctypes.byref(handle),
        _FILE_TRAVERSE
        | _FILE_READ_ATTRIBUTES
        | _READ_CONTROL
        | 0x100000
        | (_DELETE if rollback_handle else 0),
        ctypes.byref(attributes),
        ctypes.byref(io_status),
        None,
        _FILE_ATTRIBUTE_NORMAL,
        0 if rollback_handle else _FILE_SHARE_READ | _FILE_SHARE_WRITE,
        1 if descriptor is None else 2,  # FILE_OPEN or FILE_CREATE
        0x200021,  # FILE_OPEN_REPARSE_POINT | FILE_SYNCHRONOUS_IO_NONALERT | FILE_DIRECTORY_FILE
        None,
        0,
    )
    return (_ntdll.RtlNtStatusToDosError(status), None) if status < 0 else (0, handle.value)


def create_windows_output_directory(path: Path, descriptor: wintypes.LPVOID) -> int:
    with _checked_output_directory(path.parent) as (_, parent, grants):
        _require_stable_output(path, grants)
        error, handle = _relative_output_directory(parent, path.name, descriptor)
        if not error:
            _close_handle(handle)
        return error


@contextlib.contextmanager
def _private_directory_descriptor(path: Path, *, explicit_owner: bool) -> Iterator[wintypes.LPVOID]:
    _require_windows()
    # Older supported Python releases ignore mkdir's 0700 mode on Windows.
    # Apply the same owner/SYSTEM/Administrators policy at creation so a
    # writable parent never becomes an inheritance window.
    volume = ctypes.create_unicode_buffer(32768)
    flags = wintypes.DWORD()
    if not _kernel32.GetVolumePathNameW(str(path.parent.resolve()), volume, len(volume)):
        raise ctypes.WinError(ctypes.get_last_error())
    if not _kernel32.GetVolumeInformationW(
        volume, None, 0, None, None, ctypes.byref(flags), None, 0
    ):
        raise ctypes.WinError(ctypes.get_last_error())
    if not flags.value & 0x8:  # FILE_PERSISTENT_ACLS
        raise ValueError("Select a directory on a Windows volume that supports ACLs.")

    sid = _current_user_sid()
    owner = f"O:{sid}" if explicit_owner else ""
    dacl = f"{owner}D:P(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;FA;;;{sid})"

    descriptor = wintypes.LPVOID()
    if not _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
        dacl, 1, ctypes.byref(descriptor), None
    ):
        raise ctypes.WinError(ctypes.get_last_error())
    try:
        yield descriptor
    finally:
        _kernel32.LocalFree(descriptor)


def create_private_directory(path: Path, *, exist_ok: bool, scan_output: bool) -> Path:
    """Create one Windows directory with a protected inheritable DACL."""
    with _private_directory_descriptor(path, explicit_owner=not exist_ok) as descriptor:
        if scan_output:
            error = create_windows_output_directory(path, descriptor)
        else:
            attributes = _SecurityAttributes(ctypes.sizeof(_SecurityAttributes), descriptor, False)
            error = (
                0
                if _CreateDirectoryW(str(path), ctypes.byref(attributes))
                else ctypes.get_last_error()
            )
        if not error:
            return path if exist_ok else verify_private_scan_root(path, descriptor)
        if exist_ok and error == 183 and path.is_dir():  # ERROR_ALREADY_EXISTS
            if scan_output:
                require_windows_output_path(path)
            return path
        raise ctypes.WinError(error)


@contextlib.contextmanager
def create_deep_resume_output(scan_dir: Path, committed: Callable[[], bool]) -> Iterator[list[int]]:
    """Retain the exact creation handle through verification and database commit."""
    retained = scan_dir / DEEP_RESUME_DIRECTORY
    with (
        _private_directory_descriptor(retained, explicit_owner=True) as descriptor,
        _checked_output_directory(scan_dir) as (_, parent, grants),
    ):
        _require_stable_output(retained, grants)
        error, child = _relative_output_directory(
            parent, retained.name, descriptor, rollback_handle=True
        )
        if error:
            raise ctypes.WinError(error)
        assert child is not None
        with _OwnedHandle(child):
            try:
                _verify_directory(child, retained)
                child_grants = _output_directory_grants(
                    child, retained, expected_descriptor=descriptor
                )
                yield _pinned_resume_identity(parent, child, retained, child_grants)
            except BaseException:
                if not committed():
                    _mark_handle_for_deletion(child)
                raise


def create_directory_with_same_dacl(path: Path, source: Path) -> None:
    """Create an archive replacement with the original directory's DACL."""
    _require_windows()
    descriptor = _directory_security_descriptor(source, _DACL_SECURITY_INFORMATION)
    error = create_windows_output_directory(path, ctypes.cast(descriptor, wintypes.LPVOID))
    if error:
        raise WindowsScanLocalFileError(error, ctypes.FormatError(error), str(path))


@contextlib.contextmanager
def _locked_parent(
    scan_dir: Path,
    relative_path: str,
    *,
    create: bool,
    missing_is_path_error: bool = True,
    expected_root_identity: tuple[int, int] | None = None,
) -> Iterator[tuple[Path, str]]:
    """Hold non-deletable handles for every directory in the absolute target path."""

    _require_windows()
    parts = _validated_parts(relative_path)
    root_path, observed_root_identity = _canonical_scan_directory(scan_dir)
    if expected_root_identity is not None and observed_root_identity != expected_root_identity:
        raise _invalid_path(scan_dir, "scan directory changed after artifact restoration setup")
    handles: list[_OwnedHandle] = []
    try:
        # Absolute-path Win32 calls remain safe only while every ancestor is
        # fixed in place. Otherwise an attacker could rename an ancestor of the
        # scan root and substitute a different tree at the stored path.
        for directory_path in (*reversed(root_path.parents), root_path):
            directory_handle = _open_directory(directory_path)
            assert directory_handle is not None
            handles.append(directory_handle)
        try:
            current_root = root_path.lstat()
        except OSError as exc:
            if exc.errno not in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
                raise
            raise _invalid_path(
                scan_dir, f"scan directory changed while it was being opened: {exc}"
            ) from exc
        current_root_identity = (current_root.st_dev, current_root.st_ino)
        if current_root_identity != observed_root_identity or (
            expected_root_identity is not None and current_root_identity != expected_root_identity
        ):
            raise _invalid_path(scan_dir, "scan directory changed while it was being opened")
        current_path = root_path
        for component in parts[:-1]:
            current_path /= component
            child_handle = _open_directory(
                current_path, missing_ok=create, missing_is_path_error=missing_is_path_error
            )
            if child_handle is None:
                _create_directory(current_path)
                child_handle = _open_directory(current_path)
                assert child_handle is not None
            handles.append(child_handle)
        yield current_path, parts[-1]
    finally:
        for handle in reversed(handles):
            handle.close()


def _generated_directory_policy(descriptor: object) -> tuple[str, bool, frozenset[str]]:
    # Let Windows normalize SID aliases, access masks and inheritance flags in
    # both descriptors. ACE order is immaterial for our three allow grants.
    sddl = wintypes.LPWSTR()
    if not _advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW(
        descriptor,
        1,
        _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION,
        ctypes.byref(sddl),
        None,
    ):
        _raise_last_error("ConvertSecurityDescriptorToStringSecurityDescriptorW")
    try:
        owner, _, dacl = sddl.value.partition("D:")
        flags, _, entries = dacl.partition("(")
        return owner, "P" in flags, frozenset(entries.removesuffix(")").split(")("))
    finally:
        _kernel32.LocalFree(sddl)


def verify_private_scan_root(scan_dir: Path, expected_descriptor: object) -> Path:
    """Verify the new directory's owner and protected grants while the path is pinned."""
    with _locked_parent(scan_dir, ".security", create=False) as (root_path, _):
        actual = _directory_security_descriptor(
            root_path, _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION
        )
        if _generated_directory_policy(actual) != _generated_directory_policy(expected_descriptor):
            raise _invalid_path(scan_dir, "new scan directory lacks its private owner or DACL")
        return root_path


def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
    """Return a canonical scan root and its identity while holding it fixed."""

    with _locked_parent(scan_dir, ".identity", create=False) as (root_path, _):
        metadata = root_path.lstat()
        return root_path, (metadata.st_dev, metadata.st_ino)


@contextlib.contextmanager
def pinned_root_git_marker(
    cwd: Path, metadata: Path, *, work_tree: Path | None = None
) -> Iterator[Path | None]:
    """Return a short explicit worktree marker while its cwd and Git metadata are pinned."""
    if work_tree is None:
        work_tree = cwd
    if (
        not cwd.is_absolute()
        or not metadata.is_absolute()
        or len(cwd.drive) != 2
        or len(metadata.drive) != 2
        or len(work_tree.parts) < 2
        or cwd.parts[: len(work_tree.parts)] != work_tree.parts
        or len(metadata.parts) < 2
        or _GetDriveTypeW(cwd.anchor) != _DRIVE_FIXED
        or _GetDriveTypeW(metadata.anchor) != _DRIVE_FIXED
    ):
        yield None
        return
    marker = None
    with contextlib.ExitStack() as pins:
        try:
            for path in (cwd, metadata):
                _validated_parts(PurePosixPath(*path.parts[1:]).as_posix())
                # Pin each literal ancestor before opening the next component. Never resolve
                # a repository-controlled reparse point to find the directory to be pinned.
                for directory in (*reversed(path.parents), path):
                    handle = _open_directory(directory)
                    assert handle is not None
                    pins.enter_context(handle)
                assert handle.value is not None
                if _final_path(handle.value) != _extended_path(path):
                    raise ValueError("the selected Git directory spelling is not canonical")
            root_marker = work_tree / ".git"
            reference = Path(os.path.relpath(root_marker, cwd))
            if str(root_marker) != str(metadata):
                # The literal canonical root is already pinned before opening its regular file.
                fd, leaf = open_read_fd_with_path(work_tree, ".git", "Git metadata pointer")
                pointer = pins.enter_context(os.fdopen(fd, "rb"))
                if leaf != ".git":
                    raise ValueError("the root marker name does not match .git")
                expected = f"gitdir: {metadata}".encode("utf-8")
                value = pointer.read(len(expected) + 3).removesuffix(b"\n").removesuffix(b"\r")
                if value.replace(b"/", b"\\") != expected:
                    raise ValueError("the root marker does not name the selected Git directory")
                # A deep scope can make the relative spelling longer than the gitfile itself.
                if len(os.fsencode(root_marker)) < len(os.fsencode(reference)):
                    reference = root_marker
            marker = reference
        except (OSError, ValueError):
            pins.close()
        yield marker


def pin_replay_metadata(
    pins: contextlib.ExitStack, metadata: Path | None, scratch: Path
) -> Path | None:
    """Bind the selected metadata and fresh private Windows scratch before copying into it."""
    if os.name != "nt" or metadata is None:
        return None
    try:
        with contextlib.ExitStack() as checked:
            checked.enter_context(_locked_parent(metadata, "HEAD", create=False))
            checked.enter_context(_locked_parent(scratch.parent, scratch.name, create=False))
            directory = _create_file(
                scratch,
                access=_FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _READ_CONTROL,
                share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
                disposition=_OPEN_EXISTING,
                flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
            )
            assert directory is not None and directory.value is not None
            checked.enter_context(directory)
            _verify_directory(directory.value, scratch)
            if _output_directory_grants(directory.value, scratch):
                return None
            pins.enter_context(checked.pop_all())
    except (OSError, ValueError):
        return None
    return metadata


@contextlib.contextmanager
def pinned_replay_gitfile(checkout: Path, metadata: Path) -> Iterator[Path]:
    """Keep Git's short metadata pointer outside the replay and immutable while Git uses it."""
    with _locked_parent(checkout, ".git", create=False):
        # Git reads this path relative to its unchanged worktree cwd. Both volumes'
        # literal ancestors are pinned, including the temporary directory above checkout.
        marker = checkout.parent / "reviewed.git"
        handle = _create_file(
            marker,
            access=_GENERIC_WRITE | _FILE_READ_ATTRIBUTES,
            share=_FILE_SHARE_READ,
            disposition=_CREATE_NEW,
            flags=_FILE_ATTRIBUTE_NORMAL | _FILE_FLAG_OPEN_REPARSE_POINT,
        )
        assert handle is not None and handle.value is not None
        with handle:
            _verify_regular_file(handle.value, marker)
            _write_all(handle.value, f"gitdir: {metadata.as_posix()}\n".encode("utf-8"))
            yield Path("..") / marker.name


def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
    """Open a verified regular file and return an owned binary read descriptor."""

    return open_read_fd_with_path(scan_dir, relative_path, context)[0]


def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) -> tuple[int, str]:
    """Return an owned read descriptor and the scan-relative path with the file's actual leaf name.

    Verify the regular file while holding its parent directories. The caller must
    close the returned descriptor.
    """

    try:
        with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (
            parent_path,
            leaf_name,
        ):
            path = parent_path / leaf_name
            handle = _create_file(
                path,
                access=_GENERIC_READ | _FILE_READ_ATTRIBUTES,
                # Denying write/delete sharing keeps the opened contents stable.
                share=_FILE_SHARE_READ,
                disposition=_OPEN_EXISTING,
                flags=_FILE_FLAG_OPEN_REPARSE_POINT,
            )
            assert handle is not None and handle.value is not None
            with handle:
                _verify_regular_file(handle.value, path)
                filename = Path(_final_path(handle.value)).name
                resolved_path = PurePosixPath(relative_path).with_name(filename).as_posix()
                raw_handle = handle.detach()
                try:
                    assert _msvcrt is not None
                    descriptor = _msvcrt.open_osfhandle(raw_handle, os.O_RDONLY | os.O_BINARY)
                    return descriptor, resolved_path
                except BaseException:
                    _close_handle(raw_handle)
                    raise
    except WindowsScanLocalFileError as exc:
        raise WindowsScanLocalFileError(
            exc.errno,
            f"{context}: {exc.strerror}",
            exc.filename,
        ) from exc


def file_change_time(descriptor: int) -> int:
    """Return the filesystem change time. Python's Windows st_ctime is creation time."""
    assert _msvcrt is not None
    info = _FileBasicInfo()
    if not _GetFileInformationByHandleEx(
        _msvcrt.get_osfhandle(descriptor), 0, ctypes.byref(info), ctypes.sizeof(info)
    ):
        _raise_last_error("GetFileInformationByHandleEx(FileBasicInfo)")
    return info.ChangeTime


def stream_matches_payload(stream: BinaryIO, payload: bytes) -> bool:
    """Compare bytes from the current stream position to payload, requiring EOF after the final byte."""
    offset = 0
    while offset < len(payload):
        chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))
        if not chunk or chunk != payload[offset : offset + len(chunk)]:
            return False
        offset += len(chunk)
    return stream.read(1) == b""


def _write_all(handle: int, payload: bytes) -> None:
    view = memoryview(payload)
    offset = 0
    while offset < len(view):
        chunk = bytes(view[offset : offset + _MAX_WRITE_CHUNK])
        buffer = ctypes.create_string_buffer(chunk, len(chunk))
        written = wintypes.DWORD()
        if not _WriteFile(handle, buffer, len(chunk), ctypes.byref(written), None):
            _raise_last_error("WriteFile")
        if written.value == 0:
            raise WindowsScanLocalFileError(errno.EIO, "WriteFile made no progress")
        offset += written.value
    if not _FlushFileBuffers(handle):
        _raise_last_error("FlushFileBuffers")


def _rename_handle(handle: int, destination_path: Path, replace_existing: bool) -> None:
    encoded_name = _extended_path(destination_path).encode("utf-16-le")
    file_name_offset = _FileRenameInfo.FileName.offset
    buffer_size = max(
        ctypes.sizeof(_FileRenameInfo),
        file_name_offset + len(encoded_name) + ctypes.sizeof(wintypes.WCHAR),
    )
    buffer = ctypes.create_string_buffer(buffer_size)
    info = ctypes.cast(buffer, ctypes.POINTER(_FileRenameInfo)).contents
    info.FlagsOrReplaceIfExists = int(replace_existing)
    # The fully qualified destination uses a null RootDirectory. Verified
    # directory handles remain open to prevent ancestor replacement.
    info.RootDirectory = None
    info.FileNameLength = len(encoded_name)
    ctypes.memmove(ctypes.addressof(buffer) + file_name_offset, encoded_name, len(encoded_name))
    if not _SetFileInformationByHandle(
        handle,
        _FILE_RENAME_INFO_CLASS,
        buffer,
        buffer_size,
    ):
        if not replace_existing and ctypes.get_last_error() in _COLLISION_ERRORS:
            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination_path))
        _raise_last_error("SetFileInformationByHandle(FileRenameInfo)")


def _mark_handle_for_deletion(handle: int) -> None:
    info = _FileDispositionInfo(True)
    if not _SetFileInformationByHandle(
        handle,
        _FILE_DISPOSITION_INFO_CLASS,
        ctypes.byref(info),
        ctypes.sizeof(info),
    ):
        _raise_last_error("SetFileInformationByHandle(FileDispositionInfo)")


def _validate_existing_output(path: Path) -> bool:
    handle = _create_file(
        path,
        access=_FILE_READ_ATTRIBUTES,
        share=_FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
        disposition=_OPEN_EXISTING,
        flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
        missing_ok=True,
    )
    if handle is None:
        return False
    with handle:
        assert handle.value is not None
        _verify_regular_file(handle.value, path)
    return True


def _existing_output_matches(path: Path, payload: bytes) -> bool:
    try:
        handle = _create_file(
            path,
            access=_GENERIC_READ | _FILE_READ_ATTRIBUTES,
            # Deny write and delete sharing while comparing the opened contents.
            share=_FILE_SHARE_READ,
            disposition=_OPEN_EXISTING,
            flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
            missing_ok=True,
        )
    except WindowsScanLocalFileError as exc:
        if exc.errno in {
            _ERROR_ACCESS_DENIED,
            _ERROR_SHARING_VIOLATION,
            _ERROR_LOCK_VIOLATION,
        }:
            return False
        raise
    if handle is None:
        return False
    with handle:
        assert handle.value is not None
        _verify_regular_file(handle.value, path)
        raw_handle = handle.detach()
        try:
            assert _msvcrt is not None
            descriptor = _msvcrt.open_osfhandle(raw_handle, os.O_RDONLY | os.O_BINARY)
        except BaseException:
            _close_handle(raw_handle)
            raise
        try:
            with os.fdopen(descriptor, "rb") as stream:
                if os.fstat(stream.fileno()).st_size != len(payload):
                    return False
                return stream_matches_payload(stream, payload)
        except OSError:
            return False


@contextlib.contextmanager
def _written_temp(destination: Path, payload: bytes) -> Iterator[tuple[Path, _OwnedHandle]]:
    for _ in range(16):
        path = destination.with_name(f".{destination.name}.{secrets.token_hex(8)}.tmp")
        try:
            handle = _create_file(
                path,
                access=_GENERIC_WRITE | _DELETE | _FILE_READ_ATTRIBUTES,
                share=0,
                disposition=_CREATE_NEW,
                flags=_FILE_ATTRIBUTE_NORMAL,
            )
        except WindowsScanLocalFileError as exc:
            if exc.errno in _COLLISION_ERRORS:
                continue
            raise
        assert handle is not None and handle.value is not None
        with handle:
            try:
                _verify_regular_file(handle.value, path)
                _write_all(handle.value, payload)
                yield path, handle
            except BaseException:
                if handle.value is not None:
                    with contextlib.suppress(OSError):
                        _mark_handle_for_deletion(handle.value)
                raise
        return
    raise WindowsScanLocalFileError(errno.EEXIST, "could not allocate a unique temp file")


def _stage_metadata(
    handle: _OwnedHandle, *, close_writer: bool = False
) -> tuple[os.stat_result, int]:
    # Windows can update LastWriteTime on last writer close. Observe the same
    # file across that close, independently of whatever is now at the name.
    assert handle.value is not None and _msvcrt is not None
    raw = _ReOpenFile(
        handle.value,
        _FILE_READ_ATTRIBUTES,
        _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
        0,
    )
    if raw is None or raw == _INVALID_HANDLE_VALUE:
        _raise_last_error("ReOpenFile")
    with _OwnedHandle(raw) as observer:
        descriptor = _msvcrt.open_osfhandle(raw, os.O_RDONLY | os.O_BINARY)
        observer.detach()
        try:
            if close_writer:
                handle.close()
            try:
                return os.fstat(descriptor), file_change_time(descriptor)
            except BaseException:
                if close_writer:
                    # The observer still identifies the staged file after the writer closed.
                    cleanup = _ReOpenFile(
                        raw, _DELETE, _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE, 0
                    )
                    if cleanup and cleanup != _INVALID_HANDLE_VALUE:
                        with _OwnedHandle(cleanup), contextlib.suppress(OSError):
                            _mark_handle_for_deletion(cleanup)
                raise
        finally:
            os.close(descriptor)


@contextlib.contextmanager
def stage_write(
    scan_dir: Path,
    relative_path: str,
    payload: bytes,
    *,
    expected_root_identity: tuple[int, int] | None = None,
    replace_existing: bool = False,
) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
    """Flush a patch and keep only a movable handle to its root across admission."""
    if expected_root_identity is None:
        root = scan_dir.lstat()
        expected_root_identity = (root.st_dev, root.st_ino)
    with _locked_parent(
        scan_dir, relative_path, create=True, expected_root_identity=expected_root_identity
    ) as (parent, leaf):
        destination = parent / leaf
        if _validate_existing_output(destination) and not replace_existing:
            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination))
        root_handle = _open_directory(scan_dir, movable=True)
        assert root_handle is not None
        try:
            with _written_temp(destination, payload) as (temp, writer):
                staged, change_time = _stage_metadata(writer, close_writer=True)
        except BaseException:
            root_handle.close()
            raise

    location = scan_dir
    published = False

    @contextlib.contextmanager
    def open_stage() -> Iterator[tuple[_OwnedHandle, Path]]:
        with _locked_parent(
            location, relative_path, create=False, expected_root_identity=expected_root_identity
        ) as (parent, leaf):
            path = parent / temp.name
            handle = _create_file(
                path,
                access=_DELETE | _FILE_READ_ATTRIBUTES,
                share=0,
                disposition=_OPEN_EXISTING,
                flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
            )
            assert handle is not None and handle.value is not None
            with handle:
                _verify_regular_file(handle.value, path)
                current, changed = _stage_metadata(handle)
                if not (
                    os.path.samestat(staged, current)
                    and staged.st_size == current.st_size
                    and staged.st_mtime_ns == current.st_mtime_ns
                    and change_time == changed
                ):
                    raise _invalid_path(path, "staged patch changed before publication")
                yield handle, parent / leaf

    def publish(directory: Path | None = None) -> tuple[os.stat_result, int]:
        nonlocal location, published
        if directory is not None:
            location = directory
        with open_stage() as (handle, destination):
            assert handle.value is not None
            _rename_handle(handle.value, destination, replace_existing)
            published = True
            _verify_regular_file(handle.value, destination)
            return _stage_metadata(handle)

    with root_handle:
        try:
            yield publish
        finally:
            if not published:
                # A different workbench database may own the archive move.
                assert root_handle.value is not None
                with contextlib.suppress(OSError):
                    location = Path(_final_path(root_handle.value))
                    while True:
                        try:
                            with open_stage() as (handle, _):
                                assert handle.value is not None
                                _mark_handle_for_deletion(handle.value)
                            break
                        except OSError:
                            # A move can land between locating the root and fixing its parents.
                            moved_to = Path(_final_path(root_handle.value))
                            if moved_to == location:
                                break
                            location = moved_to


def atomic_write(
    scan_dir: Path,
    relative_path: str,
    payload: bytes,
    *,
    expected_root_identity: tuple[int, int] | None = None,
    replace_existing: bool = True,
) -> None:
    """Atomically publish ``payload`` to a scan-local regular file."""
    with _locked_parent(
        scan_dir, relative_path, create=True, expected_root_identity=expected_root_identity
    ) as (parent, leaf):
        destination = parent / leaf
        if _validate_existing_output(destination) and not replace_existing:
            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination))
        if (
            replace_existing
            and expected_root_identity is not None
            and _existing_output_matches(destination, payload)
        ):
            return
        with _written_temp(destination, payload) as (_, handle):
            assert handle.value is not None
            _rename_handle(handle.value, destination, replace_existing)
            _verify_regular_file(handle.value, destination)


def unlink_if_exists(scan_dir: Path, relative_path: str) -> None:
    """Delete a scan-local regular file or reparse-point leaf without following it."""

    with _locked_parent(scan_dir, relative_path, create=False) as (parent_path, leaf_name):
        path = parent_path / leaf_name
        handle = _create_file(
            path,
            access=_DELETE | _FILE_READ_ATTRIBUTES,
            # Deny delete sharing so an existing delete-capable handle makes
            # cleanup fail instead of moving the verified object before delete.
            share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
            disposition=_OPEN_EXISTING,
            flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
            missing_ok=True,
        )
        if handle is None:
            return
        with handle:
            assert handle.value is not None
            info = _attributes(handle.value)
            is_reparse_point = bool(info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT)
            is_directory = bool(info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY)
            if is_directory and not is_reparse_point:
                raise _invalid_path(path, "scan-local cleanup target must not be a directory")
            _verify_handle_path(handle.value, path, opened_name=is_reparse_point)
            _mark_handle_for_deletion(handle.value)


if __name__ == "__main__":
    argparse.ArgumentParser(description=__doc__).parse_args()

SHA-256: 9ab01a477f944f0ce4d3f7ef8646d477b40dc6b775b5b615b464fcf461beaee7