simulo 0.26.0__py3-none-any.whl

simulo/_client/_secure_downloads.py

@@ -0,0 +1,1181 @@
+"""Race-resistant destination-directory handling for CLI downloads.
+
+THE RACE THIS CLOSES. The bulk download path validates its assembled
+filename and the selected destination directory as PATH STRINGS
+(``_contained_bulk_download_destination`` in ``cli.py``: resolve, then
+``relative_to``) before any bytes are fetched. The actual write — inside
+this client's ``download_model``/``download_output``/``download_recording``
+— re-derives the SAME destination from its path string again, after a
+network fetch: an ``exist_ok=True`` ``mkdir`` (which silently ACCEPTS a
+symlink planted at a previously-missing path, so long as it resolves to a
+directory), a SEPARATE ``tempfile.mkstemp(dir=...)`` call, then a SEPARATE
+``os.replace`` call. A local attacker who can create files in whatever
+directory CONTAINS the selected destination — or in any ANCESTOR of it a
+nested ``-o a/b/c`` would create — can replace a previously-missing
+directory with a symlink at any point before the eventual write and
+redirect the downloaded bytes outside the approved destination. This was
+named, and explicitly deferred, by the security review of the change that
+landed the response-ID, filename, normalization, and existing-symlink-escape
+containment this module extends.
+
+THE FIX is two-phase, and the split matters: **observe, then open.**
+
+:func:`observe_destination` runs FIRST — before any network I/O for the
+download begins — and walks the ENTIRE destination path, component by
+component, from a trusted anchor (filesystem root for an absolute path, the
+process's current working directory for a relative one) down to the leaf.
+For the PREFIX of components that already exist, it does not merely record
+their (device, inode) VALUES — an inode number is a value a filesystem
+allocator can and does reuse (measured on ext4: a directory removed with
+``rmdir`` frees its inode for the very next ``mkdir`` in the same parent, on
+the first attempt), so a value comparison taken later can be fooled by an
+attacker who deletes the observed directory and lets a NEW directory they
+control claim the same number before the eventual check runs. Instead, the
+DEEPEST existing component's file descriptor is kept OPEN — held inside the
+returned :class:`DestinationObservation` — which pins its inode: the kernel
+will not hand that inode number to a new allocation while any process holds
+it open, so the value-reuse attack has no purchase on it. Every component
+AFTER that point does not exist yet; only its NAME is recorded, nothing
+about its contents is trusted. This call is read-only for anything it does
+not already hold open, so a subsequent digest mismatch or failed fetch
+still leaves zero NEW filesystem footprint, exactly as before.
+
+:func:`open_destination_directory` runs SECOND — immediately before the
+atomic write, once bytes are ready to land — and takes that observation as
+a REQUIRED argument. On POSIX it does NOT re-walk the existing prefix at
+all: it takes OVER the held file descriptor directly (ownership transfers
+to the returned handle) and continues the walk, ``dir_fd``-chained, only
+for the components the observation recorded as absent — creating each with
+a bare ``os.mkdir`` (which fails outright, symlink or not, if anything
+already occupies the name) and then opening it ``O_NOFOLLOW``, so anything
+other than the plain directory just created is provably a race (nothing was
+there when the operation began) and is refused rather than followed.
+
+Because the existing prefix is never re-derived from a path string —
+``open_destination_directory`` continues from the SAME open descriptor
+``observe_destination`` acquired, never a fresh lookup of the same name —
+and every absent component is only ever created under ``O_NOFOLLOW``,
+nothing that happens during the network fetch can redirect the eventual
+write, for EVERY component of the destination this module creates or
+holds, not only the final one.
+
+MEASURED RESIDUAL. The gap between ``observe_destination`` and
+``open_destination_directory`` is NOT small: callers call the first before
+even resolving a presigned URL and the second only after the network fetch
+(and any digest verification) completes — the gap IS the fetch's entire,
+possibly long, duration, deliberately, because a digest mismatch or a
+failed fetch must still leave zero new filesystem footprint. The invariant
+this module provides does not depend on that gap's width. On POSIX, the
+existing prefix is bound to a held file descriptor from the moment it is
+observed, so nothing that happens to its NAME during the gap — deletion,
+inode reuse at the freed number, a symlink planted at the freed name — can
+change what the returned handle operates on, because the handle never
+looks that name up again; and every component recorded absent is only ever
+created under ``O_NOFOLLOW`` at open time, so a plant during the gap is
+refused there instead. What is genuinely out of scope: the trusted anchor
+itself (filesystem root, or the process's own current working directory),
+already outside this module's and the CLI's threat model, and the CALLER's
+own responsibility to pass ``observe_destination`` and
+``open_destination_directory`` the intended destination in the first place
+(a caller bug there is not an attacker capability this module can guard).
+
+WINDOWS. CPython's ``os`` module does not expose ``dir_fd``-relative
+operations on Windows for any primitive this module needs — ``os.open``,
+``os.mkdir``, and ``os.replace`` are all documented "Availability: Unix" for
+their ``dir_fd``/``*_dir_fd`` parameters, and ``os.supports_dir_fd`` is
+empty there — so neither the held-descriptor technique nor the
+``dir_fd``-chained walk is available.
+``_PathIdentityDestinationDirectory`` still applies a per-component
+create-or-verify treatment to every component, ancestors included, but each
+check is its own separate ``os.stat``/``os.mkdir`` call against an
+ACCUMULATED path string, never a held handle — so a swap of any EARLIER
+component, at any point after that component's own check already ran,
+redirects every SUBSEQUENT component's ``mkdir``/``stat`` for the
+REMAINDER of that walk, not merely "the next syscall on that same
+component". This is a real, disclosed, non-zero-width gap the POSIX path
+does not have. Windows also has a primitive Linux/macOS do not: DIRECTORY
+JUNCTIONS, created via ``mklink /J`` with NO elevated privilege (unlike a
+true Windows symlink, which needs ``SeCreateSymbolicLinkPrivilege``) and
+NOT detected by ``stat.S_ISLNK``. This module checks ``st_reparse_tag``
+explicitly wherever it checks for a symlink on the fallback path, so the
+unprivileged primitive an attacker can actually use is the one being
+guarded, not only the privileged one they usually cannot. One user-visible
+consequence: a PRE-EXISTING junction as the selected destination is now
+refused outright, the same as a freshly-planted one, rather than silently
+followed — junctions are the ordinary UNPRIVILEGED way Windows users link
+directories day to day, so a ``-o`` target that is a junction, which
+worked before this module existed, now gets a hard error where it did not
+before.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import errno
+import os
+import secrets
+import stat as stat_module
+import sys
+import unicodedata
+from pathlib import Path
+from typing import Optional
+
+__all__ = [
+    "DestinationDirectory",
+    "DestinationDirectoryError",
+    "DestinationObservation",
+    "SUPPORTS_DIR_FD",
+    "observe_destination",
+    "open_destination_directory",
+]
+
+
+class DestinationDirectoryError(OSError):
+    """A download destination could not be safely opened, created, or
+    written to — including a fail-closed refusal of a symlink/junction race.
+
+    An ``OSError`` subclass so every existing ``except (OSError, ValueError)``
+    around a download write (``_download_and_report`` and its Model/Output
+    counterparts in ``cli.py``) already reports it as one clean CLI line;
+    no caller needs a new except clause to handle this module's refusals.
+    """
+
+
+def _retained_temp_error(
+    destination_display_path: Path, temp_name: str, exc: Exception, *, existing_final_preserved: bool = False
+) -> DestinationDirectoryError:
+    """Describe a possible temporary residue without trusting its current path."""
+    preservation = "Existing final entry was preserved. " if existing_final_preserved else ""
+    return DestinationDirectoryError(
+        f"{preservation}Download created private temporary entry {temp_name!r} in the originally selected "
+        f"destination directory {destination_display_path} before the failure. That directory and name may now "
+        "resolve elsewhere; locate and verify the original entry before cleanup. Do not delete a same-named "
+        "current path unless its identity is independently confirmed. "
+        f"Could not complete the download write: {exc}."
+    )
+
+
+def _close_fd_quietly(fd: int) -> None:
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+
+
+#: ``True`` when this interpreter can perform openat-style,
+#: directory-file-descriptor-relative operations for every primitive this
+#: module needs. A platform property, checked once at import time — used by
+#: :func:`open_destination_directory` to pick
+#: :class:`_DirFdDestinationDirectory` (POSIX, race-free) or
+#: :class:`_PathIdentityDestinationDirectory` (the documented Windows
+#: fallback, race-narrowing) — see the module docstring's WINDOWS section.
+SUPPORTS_DIR_FD = (
+    hasattr(os, "O_DIRECTORY")
+    and hasattr(os, "O_NOFOLLOW")
+    and os.open in os.supports_dir_fd
+    and os.mkdir in os.supports_dir_fd
+    # `os.replace` itself is never listed in `os.supports_dir_fd` — CPython
+    # only advertises its sibling `os.rename` there, even though (measured:
+    # both share the same underlying `posixmodule.c` rename implementation,
+    # differing only in overwrite behavior) `os.replace(src, dst,
+    # src_dir_fd=..., dst_dir_fd=...)` works everywhere `os.rename` with
+    # those same arguments does. Check the one CPython actually documents.
+    and os.rename in os.supports_dir_fd
+    and os.unlink in os.supports_dir_fd
+)
+
+#: Bounded retries for picking an unused random temp-file name directly
+#: inside the destination directory — mirrors ``tempfile``'s own retry
+#: count for the same collision-on-``O_EXCL`` situation.
+_TEMP_NAME_ATTEMPTS = 64
+
+# Linux ``renameat2(..., RENAME_NOREPLACE)`` is one syscall: either the
+# temporary entry becomes the final entry and the temporary name disappears,
+# or an existing final entry is left untouched.  ``link`` followed by
+# ``unlink`` cannot offer that postcondition because a process death between
+# those calls leaves both names behind.  Keep the optional libc binding at
+# module scope so unsupported libc/platform combinations are explicitly
+# refused rather than silently falling back to replacement.
+_AT_FDCWD = -100
+_RENAME_NOREPLACE = 1
+_RENAME_EXCL = 0x00000004
+_renameat2 = None
+_renameatx_np = None
+if sys.platform.startswith("linux"):
+    _libc = ctypes.CDLL(None, use_errno=True)
+    _renameat2 = getattr(_libc, "renameat2", None)
+    if _renameat2 is not None:
+        _renameat2.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+        _renameat2.restype = ctypes.c_int
+elif sys.platform == "darwin":
+    _libc = ctypes.CDLL(None, use_errno=True)
+    _renameatx_np = getattr(_libc, "renameatx_np", None)
+    if _renameatx_np is not None:
+        _renameatx_np.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+        _renameatx_np.restype = ctypes.c_int
+
+
+def _rename_noreplace(
+    source: str,
+    destination: str,
+    *,
+    src_dir_fd: Optional[int] = None,
+    dst_dir_fd: Optional[int] = None,
+) -> None:
+    """Atomically publish *source* at absent *destination*, or fail closed.
+
+    Linux uses ``renameat2(RENAME_NOREPLACE)`` and macOS uses
+    ``renameatx_np(RENAME_EXCL)``.  Windows' native ``os.rename`` refuses an
+    existing destination. Other platforms deliberately refuse the
+    server-derived no-clobber path instead of using a two-name link/unlink
+    sequence or replacing an existing file. Explicit user file targets keep
+    using ``os.replace`` through ``replace_existing=True``.
+    """
+    if os.name == "nt":
+        if src_dir_fd is not None or dst_dir_fd is not None:
+            raise DestinationDirectoryError(
+                "This platform cannot atomically publish a server-named download through directory descriptors."
+            )
+        os.rename(source, destination)
+        return
+    if sys.platform.startswith("linux"):
+        rename_function = _renameat2
+        flag = _RENAME_NOREPLACE
+    elif sys.platform == "darwin":
+        rename_function = _renameatx_np
+        flag = _RENAME_EXCL
+    else:
+        rename_function = None
+        flag = 0
+    if rename_function is None:
+        raise DestinationDirectoryError(
+            "This platform cannot atomically publish a server-named download without replacing an existing file."
+        )
+    old_dir_fd = _AT_FDCWD if src_dir_fd is None else src_dir_fd
+    new_dir_fd = _AT_FDCWD if dst_dir_fd is None else dst_dir_fd
+    ctypes.set_errno(0)
+    result = rename_function(
+        old_dir_fd,
+        os.fsencode(source),
+        new_dir_fd,
+        os.fsencode(destination),
+        flag,
+    )
+    if result == 0:
+        return
+    error_number = ctypes.get_errno()
+    if error_number == errno.EEXIST:
+        raise FileExistsError(error_number, os.strerror(error_number), destination)
+    if error_number in (errno.EINVAL, errno.ENOSYS, errno.EOPNOTSUPP):
+        raise DestinationDirectoryError(
+            "This filesystem cannot atomically publish a server-named download without replacing an existing file."
+        )
+    raise OSError(error_number, os.strerror(error_number), destination)
+
+
+def _random_temp_name(final_name: str) -> str:
+    """One candidate temp-file name for ``final_name``, unpredictable
+    enough that an attacker cannot pre-plant a symlink at it — the
+    surrounding directory's OWN identity is what this module protects;
+    the temp name's job is only to avoid colliding with anything already
+    there, exactly like ``tempfile.mkstemp``."""
+    return f".{final_name}.{secrets.token_hex(8)}.part"
+
+
+def _portable_name_key(name: str) -> str:
+    return unicodedata.normalize("NFKC", name).casefold()
+
+
+def _validate_leaf_name(final_name: str) -> None:
+    """Refuse anything that is not a bare basename.
+
+    Every documented caller already gets a bare basename from
+    ``_safe_download_filename`` before it ever reaches here, but the
+    containment this module sells ("cannot land outside the directory the
+    handle identifies, by construction") is only true if this precondition
+    actually holds — checked explicitly rather than left as an unenforced
+    assumption a future caller could violate silently.
+    """
+    if not final_name or final_name in (".", "..") or "/" in final_name:
+        raise DestinationDirectoryError(f"Refusing to write {final_name!r}: not a safe bare filename.")
+    if os.sep != "/" and os.sep in final_name:
+        raise DestinationDirectoryError(f"Refusing to write {final_name!r}: not a safe bare filename.")
+    if os.altsep and os.altsep in final_name:
+        raise DestinationDirectoryError(f"Refusing to write {final_name!r}: not a safe bare filename.")
+
+
+def _is_reparse_point(info: os.stat_result) -> bool:
+    """``True`` for a Windows reparse point — a directory JUNCTION
+    (``mklink /J``, no elevated privilege required) among them.
+
+    ``stat.S_ISLNK`` does not cover a junction (it is not the "symlink"
+    reparse type NTFS uses), so a check that only calls ``S_ISLNK`` misses
+    the one unprivileged local-filesystem redirection primitive an
+    unprivileged Windows attacker can actually create — a true Windows
+    symlink needs ``SeCreateSymbolicLinkPrivilege``, which an ordinary local
+    account does not have by default. ``st_reparse_tag`` is populated only
+    on Windows and is ``0``/absent everywhere else, so ``getattr(..., 0)``
+    is a portable, no-op check on POSIX. ``os.path.isjunction`` would be the
+    stdlib spelling of this, but it is 3.12+ and this package's floor is
+    3.11.
+    """
+    return getattr(info, "st_reparse_tag", 0) != 0
+
+
+def _refuse_degenerate_identity(identity: tuple[int, int], expanded: Path) -> None:
+    """Refuse a ``(0, 0)`` device/inode pair rather than silently trusting
+    it as a real identity.
+
+    Some filesystems — certain Windows network shares among them — report
+    ``st_dev``/``st_ino`` as ``0`` for every entry. An identity check built
+    on that value would compare ``(0, 0) == (0, 0)`` for two UNRELATED
+    directories and pass every time, making the whole re-verification an
+    inert no-op precisely where a UNC ``-o \\\\server\\share\\dl`` style
+    destination would otherwise rely on it most.
+    """
+    if identity == (0, 0):
+        raise DestinationDirectoryError(
+            f"Refusing to use {expanded} as a download destination: the filesystem reports a "
+            "degenerate (0, 0) device/inode identity for it (seen on some network shares), which "
+            "cannot detect a swap. Choose a destination on a filesystem that reports real identities."
+        )
+
+
+class DestinationDirectory:
+    """A stable handle to one download destination directory.
+
+    Acquired once, immediately before the write, by
+    :func:`open_destination_directory`; the write for that download must go
+    through :meth:`write_atomic` on this SAME instance, never through a
+    fresh path-string lookup. Use as a context manager, or call
+    :meth:`close` explicitly once the write (success or failure) is
+    complete.
+    """
+
+    #: The path this handle was opened for — display/error text only, never
+    #: re-resolved for a filesystem operation once the handle exists.
+    display_path: Path
+
+    def write_atomic(self, final_name: str, data: bytes, *, replace_existing: bool = True) -> None:
+        """Write *data* into ``final_name`` directly inside this directory.
+
+        A same-directory temporary file is written, flushed, and ``fsync``'d,
+        then published atomically. With ``replace_existing=True`` it replaces
+        a prior complete entry; otherwise publication fails if *any* final
+        entry already exists. Any failure after temporary-file creation may
+        leave that mode-0600 ``.part`` entry behind. No backend deletes it
+        automatically because a pathname can be replaced before cleanup.
+        Ordinary write and publication errors name the temporary entry and ask
+        the operator to locate and verify it before manual cleanup.
+        ``KeyboardInterrupt`` and
+        ``SystemExit`` are re-raised unchanged; their possible residue is
+        documented here rather than reported while interrupting the caller.
+        ``final_name`` must be a bare basename (no path separators); see
+        :func:`_validate_leaf_name`.
+        """
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+    def __enter__(self) -> "DestinationDirectory":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class _DirFdDestinationDirectory(DestinationDirectory):
+    """POSIX ``openat()``-style handle: race-free by construction.
+
+    ``fd`` is an open, ``O_DIRECTORY`` file descriptor bound to the
+    destination's inode. Every operation below passes it as ``dir_fd=``
+    with a bare basename, so none of them ever re-walks ``display_path`` as
+    a string again — and, because a bare basename cannot contain a path
+    separator, none of them can ever land outside the directory ``fd``
+    identifies, by construction rather than by re-checking.
+    """
+
+    def __init__(self, fd: int, display_path: Path) -> None:
+        self.display_path = display_path
+        self._fd = fd
+        self._closed = False
+
+    def _mkstemp(self, final_name: str) -> tuple[int, str]:
+        last_exc: Optional[OSError] = None
+        for _ in range(_TEMP_NAME_ATTEMPTS):
+            candidate = _random_temp_name(final_name)
+            try:
+                fd = os.open(candidate, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=self._fd)
+            except FileExistsError as exc:
+                last_exc = exc
+                continue
+            except FileNotFoundError as exc:
+                # The held directory was removed out from under this
+                # handle (e.g. an attacker who deleted a genuinely
+                # pre-existing directory after it was validated) — the
+                # kernel refuses to add new entries to an unlinked
+                # directory even though this fd still refers to it, which
+                # is itself a correct refusal. Give it a clear message
+                # rather than surfacing the bare temp filename.
+                raise DestinationDirectoryError(
+                    f"Refusing to write into {self.display_path}: the destination directory no longer "
+                    "exists. It may have been removed after it was validated."
+                ) from exc
+            return fd, candidate
+        raise DestinationDirectoryError(
+            f"Could not create a unique temporary file for {final_name!r} in {self.display_path} "
+            "after repeated attempts."
+        ) from last_exc
+
+    def _refuse_portable_alias(self, final_name: str, *, published_identity: Optional[tuple[int, int]] = None) -> None:
+        aliases = [
+            name
+            for name in os.listdir(self._fd)
+            if name != final_name and _portable_name_key(name) == _portable_name_key(final_name)
+        ]
+        if not aliases:
+            return
+        if published_identity is not None:
+            current = os.stat(final_name, dir_fd=self._fd, follow_symlinks=False)
+            if (current.st_dev, current.st_ino) != published_identity:
+                raise DestinationDirectoryError(
+                    f"A portable-equivalent alias appeared after the complete download was published at "
+                    f"{final_name!r}, and another process replaced that entry before identity verification. "
+                    "Manual resolution is required; the client did not delete either entry."
+                )
+            # Python exposes no conditional unlink-by-inode primitive. Leave
+            # the proven self-published entry in place rather than reopening a
+            # stat-to-unlink race that could delete a replacement.
+            raise DestinationDirectoryError(
+                f"The complete download was published at {final_name!r}, but portable-equivalent alias "
+                f"{aliases[0]!r} appeared. Manual resolution is required; the client did not delete either entry."
+            )
+        raise DestinationDirectoryError(
+            f"Refusing to publish {final_name!r}: portable-equivalent alias {aliases[0]!r} exists."
+        )
+
+    def write_atomic(self, final_name: str, data: bytes, *, replace_existing: bool = True) -> None:
+        _validate_leaf_name(final_name)
+        if not replace_existing:
+            self._refuse_portable_alias(final_name)
+        fd, temp_name = self._mkstemp(final_name)
+        try:
+            published_identity = os.fstat(fd)
+        except (KeyboardInterrupt, SystemExit):
+            _close_fd_quietly(fd)
+            raise
+        except Exception as exc:
+            _close_fd_quietly(fd)
+            raise _retained_temp_error(self.display_path, temp_name, exc) from exc
+        try:
+            handle = os.fdopen(fd, "wb")
+        except (KeyboardInterrupt, SystemExit):
+            _close_fd_quietly(fd)
+            raise
+        except Exception as exc:
+            _close_fd_quietly(fd)
+            raise _retained_temp_error(self.display_path, temp_name, exc) from exc
+        published = False
+        existing_final_preserved = False
+        try:
+            with handle:
+                handle.write(data)
+                handle.flush()
+                os.fsync(handle.fileno())
+            if replace_existing:
+                os.replace(temp_name, final_name, src_dir_fd=self._fd, dst_dir_fd=self._fd)
+                published = True
+            else:
+                try:
+                    _rename_noreplace(temp_name, final_name, src_dir_fd=self._fd, dst_dir_fd=self._fd)
+                except FileExistsError as exc:
+                    existing_final_preserved = True
+                    raise DestinationDirectoryError(
+                        f"Refusing to replace existing download destination {final_name!r} in {self.display_path}. "
+                        "The existing final entry was preserved."
+                    ) from exc
+                published = True
+                self._refuse_portable_alias(
+                    final_name, published_identity=(published_identity.st_dev, published_identity.st_ino)
+                )
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as exc:
+            if published:
+                raise
+            raise _retained_temp_error(
+                self.display_path, temp_name, exc, existing_final_preserved=existing_final_preserved
+            ) from exc
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            os.close(self._fd)
+
+
+class _PathIdentityDestinationDirectory(DestinationDirectory):
+    """Windows (no ``dir_fd``) fallback: narrows, but cannot eliminate, the
+    ancestor-component race. See the module docstring's WINDOWS section for
+    exactly what this class does and does not guarantee."""
+
+    def __init__(self, display_path: Path, identity: tuple[int, int], *, originally_symlink: bool) -> None:
+        self.display_path = display_path
+        #: ``(st_dev, st_ino)`` captured when this handle was opened —
+        #: re-verified before every filesystem operation below.
+        self._identity = identity
+        #: Whether *display_path* was ALREADY a symlink (to a real
+        #: directory) the first time this handle looked — an established
+        #: policy allows that, so every later check must keep following it
+        #: (and compare the TARGET's identity) rather than refusing outright
+        #: merely because the path is, as it always was, a symlink. A path
+        #: that started as a plain directory must never become one.
+        self._originally_symlink = originally_symlink
+        self._closed = False
+
+    def _verify_unchanged(self) -> None:
+        path_str = os.fspath(self.display_path)
+        follow = self._originally_symlink
+        try:
+            info = os.stat(path_str, follow_symlinks=follow)
+        except OSError as exc:
+            raise DestinationDirectoryError(
+                f"Download destination {self.display_path} became unreachable during the download: {exc}"
+            ) from exc
+        if not follow and (stat_module.S_ISLNK(info.st_mode) or _is_reparse_point(info)):
+            raise DestinationDirectoryError(
+                f"Refusing to write into {self.display_path}: it became a symlink or junction during " "the download."
+            )
+        if not stat_module.S_ISDIR(info.st_mode):
+            raise DestinationDirectoryError(f"Refusing to write into {self.display_path}: it is no longer a directory.")
+        if (info.st_dev, info.st_ino) != self._identity:
+            raise DestinationDirectoryError(
+                f"Refusing to write into {self.display_path}: it was replaced with a different "
+                "directory during the download."
+            )
+
+    def _mkstemp(self, final_name: str) -> tuple[int, Path]:
+        """Bounded retry on an ``O_EXCL`` temp-name collision — mirrors
+        :meth:`_DirFdDestinationDirectory._mkstemp`'s 64-attempt loop (and
+        the pre-fix ``tempfile.mkstemp``, which retried on every platform).
+        Without this, an uncaught ``FileExistsError`` on the ~1/2**64-odds
+        collision would simply fail the download outright instead of
+        retrying, on the one platform where this path is load-bearing.
+        """
+        last_exc: Optional[OSError] = None
+        for _ in range(_TEMP_NAME_ATTEMPTS):
+            temp_path = self.display_path / _random_temp_name(final_name)
+            try:
+                fd = os.open(os.fspath(temp_path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            except FileExistsError as exc:
+                last_exc = exc
+                continue
+            return fd, temp_path
+        raise DestinationDirectoryError(
+            f"Could not create a unique temporary file for {final_name!r} in {self.display_path} "
+            "after repeated attempts."
+        ) from last_exc
+
+    def _refuse_portable_alias(self, final_name: str, *, published_identity: Optional[tuple[int, int]] = None) -> None:
+        aliases = [
+            path
+            for path in self.display_path.iterdir()
+            if path.name != final_name and _portable_name_key(path.name) == _portable_name_key(final_name)
+        ]
+        if not aliases:
+            return
+        if published_identity is not None:
+            final_path = self.display_path / final_name
+            info = final_path.stat(follow_symlinks=False)
+            if (info.st_dev, info.st_ino) != published_identity:
+                raise DestinationDirectoryError(
+                    f"A portable-equivalent alias appeared after the complete download was published at "
+                    f"{final_name!r}, and another process replaced that entry before identity verification. "
+                    "Manual resolution is required; the client did not delete either entry."
+                )
+            raise DestinationDirectoryError(
+                f"The complete download was published at {final_name!r}, but portable-equivalent alias "
+                f"{aliases[0].name!r} appeared. Manual resolution is required; the client did not delete either entry."
+            )
+        raise DestinationDirectoryError(f"Refusing to publish {final_name!r}: portable-equivalent alias exists.")
+
+    def write_atomic(self, final_name: str, data: bytes, *, replace_existing: bool = True) -> None:
+        _validate_leaf_name(final_name)
+        self._verify_unchanged()
+        if not replace_existing:
+            self._refuse_portable_alias(final_name)
+        fd, temp_path = self._mkstemp(final_name)
+        try:
+            published_identity = os.fstat(fd)
+        except (KeyboardInterrupt, SystemExit):
+            _close_fd_quietly(fd)
+            raise
+        except Exception as exc:
+            _close_fd_quietly(fd)
+            raise _retained_temp_error(self.display_path, temp_path.name, exc) from exc
+        final_path = self.display_path / final_name
+        try:
+            handle = os.fdopen(fd, "wb")
+        except (KeyboardInterrupt, SystemExit):
+            _close_fd_quietly(fd)
+            raise
+        except Exception as exc:
+            _close_fd_quietly(fd)
+            raise _retained_temp_error(self.display_path, temp_path.name, exc) from exc
+        published = False
+        existing_final_preserved = False
+        try:
+            with handle:
+                handle.write(data)
+                handle.flush()
+                os.fsync(handle.fileno())
+            self._verify_unchanged()
+            if replace_existing:
+                os.replace(os.fspath(temp_path), os.fspath(final_path))
+                published = True
+            else:
+                try:
+                    _rename_noreplace(os.fspath(temp_path), os.fspath(final_path))
+                except FileExistsError as exc:
+                    existing_final_preserved = True
+                    raise DestinationDirectoryError(
+                        f"Refusing to replace existing download destination {final_name!r} in {self.display_path}. "
+                        "The existing final entry was preserved."
+                    ) from exc
+                published = True
+                self._refuse_portable_alias(
+                    final_name, published_identity=(published_identity.st_dev, published_identity.st_ino)
+                )
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as exc:
+            if published:
+                raise
+            raise _retained_temp_error(
+                self.display_path, temp_path.name, exc, existing_final_preserved=existing_final_preserved
+            ) from exc
+
+    def close(self) -> None:
+        self._closed = True
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: observe (read-only, before any network I/O)
+# ---------------------------------------------------------------------------
+
+
+class _ComponentObservation:
+    """One path component's state as observed, before the fetch: its name,
+    and either the resolved (device, inode) identity it had (existed), or
+    ``None`` (did not exist — and, transitively, neither did anything below
+    it)."""
+
+    __slots__ = ("name", "identity")
+
+    def __init__(self, name: str, identity: Optional[tuple[int, int]]) -> None:
+        self.name = name
+        self.identity = identity
+
+
+class DestinationObservation:
+    """Opaque snapshot of a destination directory's pre-fetch state.
+
+    Produced by :func:`observe_destination`, consumed by
+    :func:`open_destination_directory`. Never constructed directly, and
+    never partially reused across two different destinations — call
+    :func:`observe_destination` again for a different path.
+
+    On POSIX, this may hold an OPEN file descriptor for the deepest
+    existing path component (``held_fd``) for the entire gap between
+    observation and open — see the module docstring for why a held
+    descriptor, not a recorded identity value, is what closes the race for
+    that prefix. Callers MUST call :meth:`close` (or use this as a context
+    manager) on every path, including a digest mismatch or a failed fetch,
+    so that descriptor is never leaked. :func:`open_destination_directory`
+    takes ownership of it on success — a redundant :meth:`close` afterward
+    is always safe.
+    """
+
+    def __init__(
+        self,
+        expanded: Path,
+        *,
+        is_absolute: bool,
+        held_fd: Optional[int] = None,
+        absent_names: Optional[list[str]] = None,
+        components: Optional[list[_ComponentObservation]] = None,
+        existed: bool = True,
+        identity: Optional[tuple[int, int]] = None,
+        was_symlink: bool = False,
+    ) -> None:
+        self.expanded = expanded
+        self.is_absolute = is_absolute
+        #: POSIX only: an open fd for the deepest EXISTING component, or
+        #: ``None`` if nothing below the anchor existed (a relative
+        #: destination with no existing prefix at all — the anchor is then
+        #: the process's own current working directory, itself immune to a
+        #: path-string race; see :func:`_open_posix`). Ownership transfers
+        #: to the :class:`DestinationDirectory` :func:`open_destination_directory`
+        #: returns on success.
+        self.held_fd = held_fd
+        #: POSIX only: the ordered suffix of component names that did NOT
+        #: exist at observation time and must be created (each guarded by
+        #: ``O_NOFOLLOW`` at open time).
+        self.absent_names = absent_names
+        #: The full per-component chain, Windows-fallback only (``None`` on
+        #: POSIX, which uses ``held_fd``/``absent_names`` instead — see the
+        #: module docstring's WINDOWS section for why the fallback cannot
+        #: use a held handle the same way).
+        self.components = components
+        #: Convenience mirror of the FINAL component's own state — fallback only.
+        self.existed = existed
+        self.identity = identity
+        self.was_symlink = was_symlink
+        self._closed = False
+        self._consumed = False
+
+    def _take_for_open(self) -> None:
+        """Claim this observation for exactly one
+        :func:`open_destination_directory` call, refusing reuse.
+
+        A containment primitive whose misuse mode is "silently create and
+        write in a DIFFERENT directory" is the wrong direction to fail.
+        Without this guard, a second open on an already-spent observation
+        (``held_fd`` already handed off, ``None``) falls through to an
+        unqualified, ``dir_fd=None`` — i.e. CWD-relative — walk on POSIX,
+        landing bytes wherever the process happens to be running rather
+        than the validated destination; opening after :meth:`close` raises
+        a raw, non-``OSError`` exception (an ``AssertionError``, or under
+        ``python -O`` a ``TypeError`` from operating on a ``None`` fd) that
+        the CLI's ``except (OSError, ValueError)`` does not catch. Refusing
+        outright, the same way for both misuse shapes, is strictly safer
+        than either.
+        """
+        if self._consumed:
+            raise DestinationDirectoryError(
+                f"Refusing to open {self.expanded}: this observation was already used for a previous "
+                "open_destination_directory() call, or was closed first. Call observe_destination() "
+                "again to snapshot the destination and attempt a new open."
+            )
+        self._consumed = True
+
+    def is_existing_directory(self) -> bool:
+        """Whether the selected directory existed when this observation began."""
+        if self.absent_names is not None:
+            return not self.absent_names
+        return self.existed
+
+    def matches_directory(self, directory: Path) -> bool:
+        """Whether *directory* is exactly the path this observation owns."""
+        return self.expanded == Path(os.path.expanduser(os.fspath(directory)))
+
+    def contained_destination(self, final_name: str) -> Path:
+        """Return a final path that passed this observation's containment check.
+
+        The later open consumes this same observation, so a selected directory
+        swapped after this check cannot redirect the write. A swap visible to
+        the path-resolution check instead causes a refusal.
+        """
+        _validate_leaf_name(final_name)
+        destination = self.expanded / final_name
+        try:
+            resolved_root = self.expanded.resolve(strict=False)
+            resolved_destination = destination.resolve(strict=False)
+            resolved_destination.relative_to(resolved_root)
+        except (OSError, RuntimeError, ValueError) as exc:
+            raise DestinationDirectoryError(
+                f"Could not validate {destination} beneath selected directory {self.expanded}: {exc}"
+            ) from exc
+        if resolved_destination == resolved_root:
+            raise DestinationDirectoryError(
+                f"Refusing to write {final_name!r}: it resolves to the selected directory itself."
+            )
+        return destination
+
+    def close(self) -> None:
+        """Release the held descriptor, if any, and mark this observation
+        spent — a later :func:`open_destination_directory` call on it must
+        refuse outright (see :meth:`_take_for_open`) rather than silently
+        falling through to an unqualified, CWD-relative walk. Idempotent
+        and safe to call after ownership has already transferred to a
+        :class:`DestinationDirectory` (``held_fd`` is ``None`` by then)."""
+        if not self._closed:
+            self._closed = True
+            self._consumed = True
+            if self.held_fd is not None:
+                os.close(self.held_fd)
+                self.held_fd = None
+
+    def __enter__(self) -> "DestinationObservation":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+def _observe_posix(directory: Path) -> DestinationObservation:
+    expanded = Path(os.path.expanduser(os.fspath(directory)))
+    is_absolute = expanded.is_absolute()
+    parts = expanded.parts
+    remaining = parts[1:] if is_absolute else parts
+    absent_names: list[str] = []
+    #: The deepest component confirmed to exist so far — ``None`` means
+    #: "relative to the process's own current working directory" (either
+    #: because *expanded* is relative and nothing in it exists yet, or
+    #: because the walk has not opened anything below the anchor at all).
+    current_fd: Optional[int] = None
+    stop = False
+    try:
+        if is_absolute:
+            try:
+                current_fd = os.open(parts[0], os.O_DIRECTORY | os.O_RDONLY)
+            except OSError as exc:
+                raise DestinationDirectoryError(f"Could not observe download destination {expanded}: {exc}") from exc
+        for name in remaining:
+            if stop:
+                absent_names.append(name)
+                continue
+            try:
+                next_fd = os.open(name, os.O_DIRECTORY | os.O_RDONLY, dir_fd=current_fd)
+            except FileNotFoundError:
+                absent_names.append(name)
+                stop = True
+                continue
+            except NotADirectoryError as exc:
+                raise DestinationDirectoryError(f"{expanded}: {name!r} exists and is not a directory.") from exc
+            except OSError as exc:
+                raise DestinationDirectoryError(f"Could not observe download destination {expanded}: {exc}") from exc
+            # `next_fd` becomes the new deepest-known-existing component —
+            # release the fd it superseded (never the one we are about to
+            # return) BEFORE advancing, so a later exception in this loop
+            # closes at most one live fd via the `except` below, never two.
+            if current_fd is not None:
+                os.close(current_fd)
+            current_fd = next_fd
+    except BaseException:
+        if current_fd is not None:
+            os.close(current_fd)
+        raise
+    # `current_fd` is now the deepest EXISTING component's fd (or the
+    # anchor's, or None for "nothing exists, relative to cwd") — HELD open,
+    # deliberately, not closed: this is what pins its inode against reuse
+    # for the entire gap until `open_destination_directory` runs. See the
+    # module docstring.
+    was_symlink = False
+    if not absent_names:
+        try:
+            was_symlink = stat_module.S_ISLNK(os.lstat(os.fspath(expanded)).st_mode)
+        except OSError as exc:
+            if current_fd is not None:
+                os.close(current_fd)
+            raise DestinationDirectoryError(f"Could not observe download destination {expanded}: {exc}") from exc
+    return DestinationObservation(
+        expanded,
+        is_absolute=is_absolute,
+        held_fd=current_fd,
+        absent_names=absent_names,
+        was_symlink=was_symlink,
+    )
+
+
+def _observe_fallback(directory: Path) -> DestinationObservation:
+    """The Windows-fallback observation: no ``dir_fd`` to hold or chain, so
+    each component is checked by ``os.stat``ing the ACCUMULATED path
+    string built up so far, and its (device, inode) VALUE is recorded —
+    weaker than the POSIX walk (which holds the deepest existing
+    component's descriptor open instead of trusting a recorded value; see
+    the module docstring for why a value can be fooled by inode reuse) but
+    still a real per-component snapshot, closing the same ancestor gap the
+    POSIX walk closes, just not to zero width — see the module docstring's
+    WINDOWS section for exactly what residual window this leaves.
+    """
+    expanded = Path(os.path.expanduser(os.fspath(directory)))
+    is_absolute = expanded.is_absolute()
+    parts = expanded.parts
+    remaining = parts[1:] if is_absolute else parts
+    components: list[_ComponentObservation] = []
+    accumulated = Path(parts[0]) if is_absolute else Path(".")
+    stop = False
+    for name in remaining:
+        accumulated = accumulated / name
+        if stop:
+            components.append(_ComponentObservation(name, None))
+            continue
+        try:
+            info = os.stat(os.fspath(accumulated), follow_symlinks=True)
+        except FileNotFoundError:
+            components.append(_ComponentObservation(name, None))
+            stop = True
+            continue
+        except OSError as exc:
+            raise DestinationDirectoryError(f"Could not observe download destination {expanded}: {exc}") from exc
+        if not stat_module.S_ISDIR(info.st_mode):
+            raise DestinationDirectoryError(f"{expanded}: {name!r} exists and is not a directory.")
+        identity = (info.st_dev, info.st_ino)
+        _refuse_degenerate_identity(identity, expanded)
+        components.append(_ComponentObservation(name, identity))
+
+    leaf = components[-1] if components else None
+    existed = leaf.identity is not None if leaf is not None else True
+    leaf_identity = leaf.identity if leaf is not None else None
+    was_symlink = False
+    if existed:
+        try:
+            leaf_lstat = os.lstat(os.fspath(expanded))
+        except OSError as exc:
+            raise DestinationDirectoryError(f"Could not observe download destination {expanded}: {exc}") from exc
+        if _is_reparse_point(leaf_lstat):
+            raise DestinationDirectoryError(
+                f"Refusing to use {expanded} as a download destination: it is a directory junction, "
+                "which this module does not treat as a followable selected-directory symlink."
+            )
+        was_symlink = stat_module.S_ISLNK(leaf_lstat.st_mode)
+    return DestinationObservation(
+        expanded,
+        is_absolute=is_absolute,
+        components=components,
+        existed=existed,
+        identity=leaf_identity,
+        was_symlink=was_symlink,
+    )
+
+
+def observe_destination(directory: Path) -> DestinationObservation:
+    """Snapshot *directory*'s current state for a download about to begin.
+
+    Call this FIRST — before any network I/O for the download, including
+    resolving a presigned URL — and hold the result until bytes are ready
+    to write, then pass it to :func:`open_destination_directory`. This call
+    is read-only: it CREATES nothing, so it adds no new filesystem footprint
+    to a fetch that ultimately fails (a digest mismatch, a network error) —
+    that guarantee is unchanged from before this module existed. On POSIX
+    it may hold an open file descriptor for the deepest existing path
+    component until the returned :class:`DestinationObservation` is closed
+    (see its docstring) — a process-local resource, not a footprint on
+    disk, but the caller MUST close it on every path, success or failure.
+
+    Relative paths and ``~`` expansion are both honored, matching every
+    existing ``-o PATH``/implicit-cwd download destination.
+    """
+    if SUPPORTS_DIR_FD:
+        return _observe_posix(directory)
+    return _observe_fallback(directory)
+
+
+# ---------------------------------------------------------------------------
+# Phase 2: open (immediately before the write, using the observation)
+# ---------------------------------------------------------------------------
+
+
+def _create_absent_component(parent_fd: Optional[int], name: str, expanded: Path) -> int:
+    """Create ``name`` directly inside ``parent_fd`` (``None`` means
+    "relative to the process's own current working directory", itself
+    immune to a path-string race), never following anything already there.
+
+    A bare ``os.mkdir`` is attempted first (fails outright — symlink or
+    not — if anything already occupies the name); whatever is then opened
+    is opened ``O_NOFOLLOW``. Since the observation already proved nothing
+    was here when the operation began, anything other than a plain
+    directory now is provably a race and is refused rather than followed.
+
+    There is no "observed PRESENT" counterpart to this function on the
+    ``dir_fd`` path: a component that existed at observation time is never
+    re-walked here at all — :func:`_open_posix` continues directly from the
+    file descriptor :func:`observe_destination` kept open for it. See the
+    module docstring for why a held descriptor, not a re-checked identity
+    value, is what closes the race for that prefix.
+    """
+    try:
+        os.mkdir(name, dir_fd=parent_fd)
+    except FileExistsError:
+        pass  # benign concurrent create OR an attacker's plant -- the NOFOLLOW open below decides
+    except OSError as exc:
+        raise DestinationDirectoryError(f"Could not create download destination {expanded}: {exc}") from exc
+    try:
+        return os.open(name, os.O_DIRECTORY | os.O_RDONLY | os.O_NOFOLLOW, dir_fd=parent_fd)
+    except OSError as exc:
+        raise DestinationDirectoryError(
+            f"Refusing to use {expanded} as a download destination: {name!r} was replaced with a "
+            "symlink (or another non-directory) after it was validated as missing. This can happen "
+            "when another process races the same path — pick a different -o PATH, or remove the "
+            "conflicting entry and retry."
+        ) from exc
+
+
+def _open_posix(observation: DestinationObservation) -> _DirFdDestinationDirectory:
+    expanded = observation.expanded
+    assert observation.absent_names is not None  # POSIX observations always populate this
+
+    # Take ownership of the held descriptor immediately: from this point,
+    # `observation.close()` must not touch it (it is about to become either
+    # this walk's own `current_fd`, closed on failure right here, or the
+    # returned handle's fd) — a caller that calls `observation.close()`
+    # again afterward, in an outer `finally`, must see a safe no-op.
+    current_fd = observation.held_fd
+    observation.held_fd = None
+    try:
+        if current_fd is not None and not observation.absent_names:
+            try:
+                leaf_lstat = os.lstat(os.fspath(expanded))
+                leaf_stat = os.stat(os.fspath(expanded), follow_symlinks=True)
+            except OSError as exc:
+                raise DestinationDirectoryError(
+                    f"Download destination {expanded} became unreachable during the download: {exc}"
+                ) from exc
+            if not observation.was_symlink and stat_module.S_ISLNK(leaf_lstat.st_mode):
+                raise DestinationDirectoryError(
+                    f"Refusing to write into {expanded}: it became a symlink during the download."
+                )
+            held_stat = os.fstat(current_fd)
+            if (leaf_stat.st_dev, leaf_stat.st_ino) != (held_stat.st_dev, held_stat.st_ino):
+                raise DestinationDirectoryError(
+                    f"Refusing to write into {expanded}: it was replaced with a different directory during the download."
+                )
+        if current_fd is None and not observation.is_absolute:
+            # Nothing existed below the anchor, and the anchor itself is
+            # the process's own current working directory (an absolute
+            # destination always has at least the root's own fd held —
+            # see `_observe_posix`). `dir_fd=None` below already means
+            # "resolve relative to cwd" to the kernel, which is bound to
+            # this process's `chdir()` state, not a re-walked path string
+            # — so this needs no fd of its own to stay race-free; opening
+            # one explicitly is just for a uniform, always-holds-an-fd
+            # `_DirFdDestinationDirectory` instead of a special `None` case
+            # threaded through every one of its methods.
+            current_fd = os.open(".", os.O_DIRECTORY | os.O_RDONLY)
+        for name in observation.absent_names:
+            next_fd = _create_absent_component(current_fd, name, expanded)
+            if current_fd is not None:
+                os.close(current_fd)
+            current_fd = next_fd
+    except BaseException:
+        if current_fd is not None:
+            os.close(current_fd)
+        raise
+    assert current_fd is not None
+    return _DirFdDestinationDirectory(current_fd, expanded)
+
+
+def _open_fallback_component(accumulated: Path, comp: _ComponentObservation, expanded: Path) -> None:
+    """Verify or create ONE component of the fallback's path-string walk,
+    at *accumulated* (the full path up to and including this component).
+
+    Unlike the POSIX path (:func:`_open_posix`, :func:`_create_absent_component`),
+    there is no ``dir_fd`` to hold: each check here is its own separate
+    ``os.stat``/``os.mkdir`` pair against an ACCUMULATED path string. A
+    swap of THIS component after ITS OWN check has already run redirects
+    every SUBSEQUENT component's ``mkdir``/``stat`` for the REMAINDER of
+    the walk — not merely "the next syscall on this same component" — since
+    every later component's accumulated path is built by extending this
+    one's string. See the module docstring's WINDOWS section.
+    """
+    name = comp.name
+    if comp.identity is None:
+        try:
+            os.mkdir(os.fspath(accumulated))
+        except FileExistsError:
+            pass  # benign concurrent create OR an attacker's plant -- the check below decides
+        except OSError as exc:
+            raise DestinationDirectoryError(f"Could not create download destination {expanded}: {exc}") from exc
+        try:
+            info = os.stat(os.fspath(accumulated), follow_symlinks=False)
+        except OSError as exc:
+            raise DestinationDirectoryError(f"Could not open download destination {expanded}: {exc}") from exc
+        # Observed ABSENT: anything other than a plain, non-reparse
+        # directory here now is provably a race, since the observation
+        # already proved nothing was here when the operation began.
+        if stat_module.S_ISLNK(info.st_mode) or _is_reparse_point(info):
+            raise DestinationDirectoryError(
+                f"Refusing to use {expanded} as a download destination: {name!r} was replaced with a "
+                "symlink or junction after it was validated as missing."
+            )
+        if not stat_module.S_ISDIR(info.st_mode):
+            raise DestinationDirectoryError(f"{expanded}: {name!r} exists and is not a directory.")
+        return
+
+    try:
+        info = os.stat(os.fspath(accumulated), follow_symlinks=True)
+    except OSError as exc:
+        raise DestinationDirectoryError(
+            f"Refusing to use {expanded} as a download destination: {name!r} changed since it was "
+            f"validated ({exc})."
+        ) from exc
+    if not stat_module.S_ISDIR(info.st_mode):
+        raise DestinationDirectoryError(
+            f"Refusing to use {expanded} as a download destination: {name!r} is not a directory."
+        )
+    identity = (info.st_dev, info.st_ino)
+    if identity != comp.identity:
+        raise DestinationDirectoryError(
+            f"Refusing to use {expanded} as a download destination: {name!r} was replaced with a "
+            "different directory after it was validated."
+        )
+
+
+def _open_fallback(observation: DestinationObservation) -> _PathIdentityDestinationDirectory:
+    expanded = observation.expanded
+    assert observation.components is not None
+    accumulated = Path(expanded.parts[0]) if observation.is_absolute else Path(".")
+    for comp in observation.components:
+        accumulated = accumulated / comp.name
+        _open_fallback_component(accumulated, comp, expanded)
+
+    # Every component, ancestors included, is now verified/created and
+    # matches the pre-fetch observation. Capture the FINAL entry's current
+    # identity (and whether it is itself a symlink, which decides how
+    # `_PathIdentityDestinationDirectory`'s ONGOING re-checks behave) to
+    # bind the returned handle to — this is the earliest point after the
+    # fetch this call can check it, mirroring what the POSIX fd already
+    # identifies at this same point in the walk.
+    try:
+        leaf_lstat = os.stat(os.fspath(expanded), follow_symlinks=False)
+    except OSError as exc:
+        raise DestinationDirectoryError(f"Could not open download destination {expanded}: {exc}") from exc
+    originally_symlink = stat_module.S_ISLNK(leaf_lstat.st_mode)
+    try:
+        info = os.stat(os.fspath(expanded), follow_symlinks=True)
+    except OSError as exc:
+        raise DestinationDirectoryError(f"Could not open download destination {expanded}: {exc}") from exc
+    if not stat_module.S_ISDIR(info.st_mode):
+        raise DestinationDirectoryError(f"Refusing to use {expanded} as a download destination: it is not a directory.")
+    identity = (info.st_dev, info.st_ino)
+    _refuse_degenerate_identity(identity, expanded)
+    return _PathIdentityDestinationDirectory(expanded, identity, originally_symlink=originally_symlink)
+
+
+def open_destination_directory(observation: DestinationObservation) -> DestinationDirectory:
+    """Open the destination :func:`observe_destination` snapshotted,
+    honoring exactly what it recorded — there is no separate ``directory``
+    argument to (mis)match against ``observation`` here: the observation
+    already carries the expanded path (``observation.expanded``), and a
+    second, independently-suppliable path parameter would only create a
+    caller-bug opportunity for the two to diverge with no attacker
+    involved. Call this immediately before the write it will hold — once
+    bytes are ready to land, with no further network I/O between this call
+    and :meth:`DestinationDirectory.write_atomic`.
+
+    A pre-existing, empty (or non-existing) real directory opens exactly as
+    before; a missing one — including every missing ancestor a nested
+    ``-o a/b/c`` needs — is created; see the module docstring for exactly
+    which race this closes on each platform.
+
+    Raises :class:`DestinationDirectoryError` outright if ``observation``
+    was already used for a prior call, or was already closed — this
+    function may be called AT MOST ONCE per :func:`observe_destination`
+    result; see :meth:`DestinationObservation._take_for_open`.
+
+    Ownership of any descriptor ``observation`` was holding transfers to
+    the returned handle on SUCCESS. On a RAISED exception, this call (via
+    ``_open_posix``/``_open_fallback``) has already closed whatever it was
+    holding at the point of failure — it does not leak. Callers must still
+    call ``observation.close()`` afterward in a ``finally`` regardless,
+    because a failure can also occur BEFORE this function is ever called
+    (a digest mismatch, a failed fetch) — that is the path this function
+    cannot clean up after, since it never ran; ``observation.close()`` is
+    what covers it, and is always a safe no-op once ownership has already
+    transferred here.
+    """
+    observation._take_for_open()
+    if SUPPORTS_DIR_FD:
+        return _open_posix(observation)
+    return _open_fallback(observation)