xdg-kit 0.1.0__py3-none-any.whl

xdg_kit/__init__.py

@@ -0,0 +1,60 @@
+"""Secure XDG-style application storage for Python: paths, credentials, permissions, and
+runtime files.
+
+The common surface -- directories and secret resolution -- is re-exported here:
+
+    from xdg_kit import config_dir, data_dir, state_dir, cache_dir, runtime_dir
+    from xdg_kit import Credentials, get_secret, require_secret
+
+Deeper pieces stay in their modules so the import says what it reaches for:
+
+    from xdg_kit.backends import FileBackend, KeyringBackend
+    from xdg_kit.scrub import scrub_secrets, scrub_exception
+    from xdg_kit.locking import FileLock, single_instance
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from xdg_kit.credentials import (
+    Credentials,
+    get_secret,
+    require_secret,
+    secret_names,
+    set_secret,
+    unset_secret,
+)
+from xdg_kit.errors import (
+    CredentialsError,
+    InsecureStorageError,
+    InvalidAppNameError,
+    XdgKitError,
+)
+from xdg_kit.paths import cache_dir, config_dir, data_dir, state_dir
+from xdg_kit.runtime import runtime_dir
+
+# Single source of truth is pyproject's version, read from the installed distribution's
+# metadata -- so a release bump lives in one place and `xdg-kit --version` can never drift
+# from what pip resolved. (An editable install reflects a bump after re-sync; importing
+# from an uninstalled source tree raises PackageNotFoundError, which is not a supported use.)
+__version__ = version("xdg-kit")
+
+__all__ = [
+    "__version__",
+    "config_dir",
+    "data_dir",
+    "state_dir",
+    "cache_dir",
+    "runtime_dir",
+    "Credentials",
+    "get_secret",
+    "require_secret",
+    "set_secret",
+    "unset_secret",
+    "secret_names",
+    "XdgKitError",
+    "CredentialsError",
+    "InsecureStorageError",
+    "InvalidAppNameError",
+]

xdg_kit/_oslock.py

@@ -0,0 +1,78 @@
+"""One cross-platform exclusive file-lock primitive, shared by the two callers that need
+it: ``locking.FileLock`` (a non-blocking single-instance guard) and ``backends`` (a
+blocking serializer around a store's read-modify-write).
+
+Built on ``fcntl.flock`` (POSIX) and ``msvcrt.locking`` (Windows) -- both released by the
+OS automatically when the process exits, even on a crash, so there is no stale lock to
+clean up. On a platform with neither, locking is a no-op that always "succeeds", leaving
+the caller's own in-process guard as the only serialization.
+
+The caller owns the lock file (where it lives, how it is opened); this module only takes
+and releases the lock on an already-open handle.
+"""
+
+from __future__ import annotations
+
+import errno
+from typing import IO
+
+try:
+    import fcntl
+except ImportError:   # non-POSIX
+    fcntl = None      # type: ignore[assignment]
+
+try:
+    import msvcrt
+except ImportError:   # non-Windows
+    msvcrt = None     # type: ignore[assignment]
+
+__all__ = [
+    "lock_exclusive",
+    "unlock",
+]
+
+
+def lock_exclusive(handle: IO[str], *, blocking: bool) -> bool:
+    """Take an exclusive lock on ``handle`` and report whether it was taken. With
+    ``blocking=False`` return ``False`` at once when another holder has it. With
+    ``blocking=True`` wait for it -- but the wait can still fail to acquire and return
+    ``False``: POSIX ``flock`` reports ``ENOLCK`` where locking is unsupported (e.g. some
+    network filesystems), so a caller must honour the result rather than assume ``True``.
+    Always ``True`` where no OS primitive exists (locking is a no-op)."""
+    if fcntl is not None:
+        flags = fcntl.LOCK_EX if blocking else fcntl.LOCK_EX | fcntl.LOCK_NB
+        try:
+            fcntl.flock(handle, flags)
+        except OSError:
+            return False
+        return True
+    if msvcrt is not None:
+        handle.seek(0)
+        if not blocking:
+            try:
+                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+            except OSError:
+                return False
+            return True
+        # LK_LOCK blocks only ~10s and then raises EDEADLOCK; re-issue it on that timeout so
+        # ``blocking=True`` genuinely waits. Any other error is real -- give up with False.
+        while True:
+            try:
+                msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+            except OSError as err:
+                if err.errno == errno.EDEADLOCK:
+                    handle.seek(0)
+                    continue
+                return False
+            return True
+    return True
+
+
+def unlock(handle: IO[str]) -> None:
+    """Release the lock taken by ``lock_exclusive`` on ``handle``; a no-op where no OS
+    primitive exists."""
+    if fcntl is not None:
+        fcntl.flock(handle, fcntl.LOCK_UN)
+    elif msvcrt is not None:
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)

xdg_kit/atomic.py

@@ -0,0 +1,67 @@
+"""Atomic file writes: write a temp file in the target directory, fsync it, then rename
+it over the target.
+
+A rename on the same filesystem is atomic, so a crash or a concurrent reader never sees
+a half-written file, and the fsync before the rename means a crash *after* the rename
+cannot leave the target pointing at unflushed bytes. The temp file is created 0600 by
+``mkstemp`` and its mode is set explicitly before the rename, so a secret is never briefly
+world-readable between create and ``chmod``. Two overlapping writers get distinct temp
+paths, so neither corrupts the other.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from xdg_kit.errors import XdgKitError
+
+__all__ = [
+    "write_bytes_atomic",
+    "write_text_atomic",
+]
+
+
+def write_bytes_atomic(path: Path, data: bytes, *, mode: int = 0o600) -> None:
+    """Write ``data`` to ``path`` atomically, leaving it mode ``mode`` (0600 by default,
+    the right mode for a secret). Creates the parent directory if needed.
+
+    Raises:
+        XdgKitError: the write failed (an I/O error); the partial temp file is removed
+            first so a failed write never leaves debris beside the target.
+    """
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+        temp_path = Path(temp_name)
+        try:
+            try:
+                handle = os.fdopen(fd, "wb")
+            except OSError:
+                os.close(fd)   # fdopen did not adopt the descriptor -- close it ourselves
+                raise
+            with handle:
+                if hasattr(os, "fchmod"):
+                    os.fchmod(handle.fileno(), mode)   # POSIX: pin the mode before any bytes land
+                handle.write(data)
+                handle.flush()
+                os.fsync(handle.fileno())   # durable before the rename
+            os.replace(temp_path, path)
+        except OSError:
+            try:
+                temp_path.unlink(missing_ok=True)
+            except OSError:
+                pass   # cleanup is best-effort; never mask the original write failure below
+            raise
+    except OSError as err:
+        raise XdgKitError(f"could not write {path}: {err}") from err
+
+
+def write_text_atomic(path: Path, text: str, *, mode: int = 0o600) -> None:
+    """Write ``text`` (UTF-8) to ``path`` atomically, leaving it mode ``mode``.
+
+    Raises:
+        XdgKitError: the write failed (propagated from ``write_bytes_atomic``).
+    """
+    write_bytes_atomic(path, text.encode("utf-8"), mode=mode)

xdg_kit/backends.py

@@ -0,0 +1,414 @@
+"""Where a secret is physically stored, behind one small interface.
+
+``SecretBackend`` is the seam: given an app and a secret name, read, write, remove, or
+list. Two implementations ship:
+
+- ``FileBackend`` (the default) -- a flat ``name -> value`` JSON map in
+  ``credentials.json`` under ``config_dir(app)``, written atomically at mode 0600 in a
+  directory tightened to 0700. It is the reliable base everywhere: no OS session, no
+  network, portable across machines, and it works the same headless as on a desktop.
+- ``KeyringBackend`` (opt-in) -- the OS secure store, via the ``keyring`` package. Because
+  a login keyring has no backend in headless contexts (cron, containers, servers), it
+  takes a ``fallback`` (normally a ``FileBackend``) and delegates the whole operation to it
+  whenever ``keyring`` is missing or non-functional -- warning once so the user learns
+  their secrets are in the file, not the keyring they asked for. When ``keyring`` *is*
+  functional it is authoritative, and a successful write/delete also clears any stale
+  plaintext copy from the fallback, so opting into the keyring does not leave (or later
+  resurrect) a file copy.
+
+The store an app reads is chosen by *name* (``config_dir(app)``), so one app can read
+another's store -- that is how a shared store lets a common key live in one place (see
+``credentials``).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import IO, Protocol
+
+from xdg_kit._oslock import lock_exclusive, unlock
+from xdg_kit.atomic import write_text_atomic
+from xdg_kit.errors import CredentialsError, XdgKitError
+from xdg_kit.paths import config_dir
+from xdg_kit.permissions import (
+    PRIVATE_FILE_MODE,
+    restrict_dir_to_owner,
+    warn_if_group_or_world_readable,
+)
+
+__all__ = [
+    "SecretBackend",
+    "FileBackend",
+    "KeyringBackend",
+    "default_backend",
+]
+
+CREDENTIALS_FILE = "credentials.json"
+
+_warned_keyring_fallback = False
+
+
+class SecretBackend(Protocol):
+    """The store interface every backend implements. ``get`` returns the stored value or
+    ``None`` when the store or key is absent; ``set`` and ``unset`` mutate it; ``names``
+    lists the stored keys (never their values). ``value`` is keyword-only so it can never
+    be swapped with ``name`` positionally -- a swap would store the secret *as a key
+    name*. Surrounding whitespace is not significant: ``get`` returns a value stripped, so a
+    whitespace-only value reads back as ``None`` (absent)."""
+
+    def get(self, app: str, name: str) -> str | None: ...
+    def set(self, app: str, name: str, *, value: str) -> None: ...
+    def unset(self, app: str, name: str) -> None: ...
+    def names(self, app: str) -> list[str]: ...
+
+
+class FileBackend:
+    """Secrets in ``credentials.json`` (a flat JSON object) under ``config_dir(app)``,
+    written atomically at mode 0600 in a directory tightened to 0700."""
+
+    def path(self, app: str) -> Path:
+        """The credentials file for ``app``: ``credentials.json`` in ``config_dir(app)``."""
+        return config_dir(app) / CREDENTIALS_FILE
+
+    def get(self, app: str, name: str) -> str | None:
+        """Return the value stored under ``name``, or ``None`` when the file or key is
+        absent (or the value is not a non-empty string). Warns once if the file is
+        readable beyond its owner.
+
+        Raises:
+            CredentialsError: the file exists but is unreadable, not JSON, or not a JSON
+                object.
+        """
+        return _normalize_secret_value(self._load(app).get(name))
+
+    def set(self, app: str, name: str, *, value: str) -> None:
+        """Store ``value`` under ``name``, creating or updating the file at mode 0600 in a
+        0700 directory. The whole read-modify-write is serialized -- always across threads of
+        this process, and across processes too wherever the OS file lock can be taken -- so
+        concurrent writers to one store do not lose each other's keys.
+
+        Raises:
+            CredentialsError: the existing file is unreadable or malformed, or the write
+                failed.
+        """
+        with _exclusive_store_lock(self.path(app)):
+            secret_value_by_name = self._load(app)
+            secret_value_by_name[name] = value
+            self._save(app, secret_value_by_name)
+
+    def unset(self, app: str, name: str) -> None:
+        """Remove ``name`` from the file if present; a no-op when the file or key is
+        absent. The read-modify-write is serialized (see ``set``).
+
+        Raises:
+            CredentialsError: the existing file is unreadable or malformed, or the write
+                failed.
+        """
+        with _exclusive_store_lock(self.path(app)):
+            secret_value_by_name = self._load(app)
+            if name in secret_value_by_name:
+                del secret_value_by_name[name]
+                self._save(app, secret_value_by_name)
+
+    def names(self, app: str) -> list[str]:
+        """The stored key names, sorted -- never the values.
+
+        Raises:
+            CredentialsError: the file exists but is unreadable or malformed.
+        """
+        return sorted(self._load(app))
+
+    def _load(self, app: str) -> dict[str, object]:
+        """Parse ``credentials.json`` into a name -> value dict, or ``{}`` when the file is
+        absent. Warns once when a present file is group/world-readable."""
+        path = self.path(app)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {}
+        except (OSError, UnicodeDecodeError) as err:
+            # UnicodeDecodeError is a ValueError, not an OSError, so name it explicitly or
+            # a non-UTF-8 file escapes this boundary as a bare traceback.
+            raise CredentialsError(f"could not read {path}: {err}") from err
+        warn_if_group_or_world_readable(path, app=app)
+        try:
+            secret_value_by_name = json.loads(text)
+        except json.JSONDecodeError as err:
+            raise CredentialsError(f"{path} is not valid JSON: {err}") from err
+        if not isinstance(secret_value_by_name, dict):
+            raise CredentialsError(f"{path} must contain a JSON object of name to value")
+        return secret_value_by_name
+
+    def _save(self, app: str, secret_value_by_name: dict[str, object]) -> None:
+        """Write the map back to ``credentials.json`` atomically at mode 0600, in a config
+        directory hardened to 0700 first. Converts the atomic layer's ``XdgKitError`` to
+        ``CredentialsError`` to honour the ``set``/``unset`` contract."""
+        path = self.path(app)
+        restrict_dir_to_owner(path.parent)
+        text = json.dumps(secret_value_by_name, indent=2, sort_keys=True) + "\n"
+        try:
+            write_text_atomic(path, text, mode=PRIVATE_FILE_MODE)
+        except XdgKitError as err:
+            raise CredentialsError(str(err)) from err
+
+
+class KeyringBackend:
+    """Secrets in the OS keyring (service = ``app``, username = ``name``), via the
+    ``keyring`` package, with a file ``fallback`` for headless machines where no keyring
+    backend exists.
+
+    When ``keyring`` is missing or reports no backend, the operation is delegated to
+    ``fallback`` in full and a one-time warning is printed so the user knows their secrets
+    are in the file, not the keyring. When ``keyring`` is present but a call fails (a locked
+    or broken store), ``get`` and ``set`` still fall back to the file, but ``unset`` fails
+    closed -- it raises ``CredentialsError`` rather than risk reporting a delete that left
+    the secret retrievable from the keyring. When ``keyring`` works it is the sole source,
+    and a successful ``set``/``unset`` also clears any file copy so opting into the keyring
+    never leaves plaintext behind. ``keyring`` provides no way to enumerate a
+    service's keys, so ``names`` reports only what the ``fallback`` holds -- keys stored
+    solely in the OS keyring are not listable.
+
+    One direction cannot be fully closed: a value written to the file fallback *while the
+    keyring is down* is not migrated into the keyring on recovery. If on recovery the keyring
+    holds *no* entry for that name, ``get`` consults the file and returns it, so the value is
+    not lost; but if the keyring still holds an *older* value for that name, that older value
+    shadows the newer file value (the keyring is authoritative on a conflict). Re-set the key
+    while the keyring is reachable so the new value lands in the keyring; do not try to fix it
+    by deleting the keyring entry -- an ``unset`` while the keyring works also clears the file
+    copy, losing the newer value.
+    """
+
+    def __init__(self, *, fallback: SecretBackend | None = None) -> None:
+        self._fallback = fallback
+
+    def __repr__(self) -> str:
+        fallback = type(self._fallback).__name__ if self._fallback is not None else None
+        return f"KeyringBackend(fallback={fallback})"
+
+    def get(self, app: str, name: str) -> str | None:
+        """Return the keyring value for ``name``, or ``None`` when it is set nowhere.
+
+        Falls back to the file store in two cases: when the keyring is unavailable (any
+        failure -- missing package, locked or broken backend), warning once; and when the
+        keyring is reachable but holds no entry, so a value written to the file while the
+        keyring was down (see the class note on one-way reconciliation) stays readable after
+        the keyring recovers instead of being silently hidden.
+
+        Raises:
+            CredentialsError: the keyring is unavailable and no fallback is configured, or a
+                consulted fallback file is present but unreadable or malformed.
+        """
+        try:
+            import keyring
+            value = keyring.get_password(app, name)
+        except Exception as err:
+            # Best-effort read: any keyring failure (missing package, locked or broken
+            # backend) falls back to the file. A third-party backend's error surface is not
+            # fully knowable, so the catch is deliberately broad -- unlike unset, which fails
+            # closed because reporting a delete that did not happen would strand a live secret.
+            return self._fallback_get(app, name, err)
+        cleaned = _normalize_secret_value(value)
+        if cleaned is not None:
+            return cleaned
+        # Keyring reachable but empty for this name: a value may have been written to the file
+        # while the keyring was down (_fallback_set), which the keyring never learned. Consult
+        # the fallback so that value is not silently hidden once the keyring is back. The
+        # keyring stays authoritative on conflicts -- a successful keyring set/unset always
+        # clears the file copy, so the file can only hold what the keyring genuinely lacks.
+        if self._fallback is not None:
+            return self._fallback.get(app, name)
+        return None
+
+    def set(self, app: str, name: str, *, value: str) -> None:
+        """Store ``value`` under ``name`` in the keyring; a successful write also clears any
+        stale plaintext copy from the fallback file. Falls back to the file store (warning
+        once) when the keyring is unavailable.
+
+        Raises:
+            CredentialsError: the keyring is unavailable and no fallback is configured; or the
+                keyring write succeeded but a stale file copy could not be cleared.
+        """
+        try:
+            import keyring
+            keyring.set_password(app, name, value)
+        except Exception as err:
+            self._fallback_set(app, name, value, err)
+            return
+        # keyring is authoritative: drop any stale plaintext copy from the fallback file. The
+        # keyring write already succeeded; if clearing the file copy fails, say so loudly (a
+        # plaintext copy may remain) without hiding that the secret IS stored.
+        if self._fallback is not None:
+            try:
+                self._fallback.unset(app, name)
+            except CredentialsError as err:
+                raise CredentialsError(
+                    f"stored {app}/{name} in the keyring, but a stale plaintext copy may "
+                    f"remain in the file store and could not be cleared: {err}"
+                ) from err
+
+    def unset(self, app: str, name: str) -> None:
+        """Remove ``name`` from the keyring and from any fallback file copy; a no-op when
+        absent. Fails closed: a keyring present but erroring on delete raises rather than
+        silently reporting a delete that may not have happened.
+
+        Raises:
+            CredentialsError: the keyring is present but the delete failed (a locked or broken
+                store); or the delete succeeded but a stale file copy could not be cleared.
+                When no keyring backend exists at all, the deletion is delegated to the
+                fallback (which raises only if its file is malformed).
+        """
+        try:
+            import keyring
+            import keyring.errors
+        except ImportError as err:
+            self._fallback_unset(app, name, err)
+            return
+        try:
+            keyring.delete_password(app, name)
+        except keyring.errors.PasswordDeleteError:
+            pass   # key already absent -- unset is idempotent
+        except keyring.errors.NoKeyringError as err:
+            self._fallback_unset(app, name, err)   # no backend at all -> the file owns it
+            return
+        except keyring.errors.KeyringError as err:
+            # keyring is present but the delete genuinely failed (a locked store, an I/O
+            # error): do NOT report success and silently fall back while the secret may
+            # still be retrievable from the keyring -- surface it.
+            raise CredentialsError(
+                f"could not delete {app}/{name} from the keyring: {err}"
+            ) from err
+        # deletion succeeded (or the key was absent): also clear any file copy so a later
+        # keyring outage cannot resurrect it. The keyring delete already succeeded; if
+        # clearing the file copy fails, say so loudly without hiding that fact.
+        if self._fallback is not None:
+            try:
+                self._fallback.unset(app, name)
+            except CredentialsError as err:
+                raise CredentialsError(
+                    f"deleted {app}/{name} from the keyring, but a stale plaintext copy may "
+                    f"remain in the file store and could not be cleared: {err}"
+                ) from err
+
+    def names(self, app: str) -> list[str]:
+        """The fallback file's stored key names, sorted -- never the values. The OS keyring
+        cannot enumerate its own keys, so a key stored solely in the keyring is not listed.
+
+        Raises:
+            CredentialsError: the fallback file is present but unreadable or malformed.
+        """
+        # keyring cannot enumerate; report only the fallback's file-stored names.
+        return self._fallback.names(app) if self._fallback is not None else []
+
+    def _fallback_get(self, app: str, name: str, err: Exception) -> str | None:
+        if self._fallback is not None:
+            _warn_keyring_fallback_once(err)
+            return self._fallback.get(app, name)
+        raise CredentialsError(f"keyring unavailable for {app}/{name}: {err}") from err
+
+    def _fallback_set(self, app: str, name: str, value: str, err: Exception) -> None:
+        if self._fallback is not None:
+            _warn_keyring_fallback_once(err)
+            self._fallback.set(app, name, value=value)
+            return
+        raise CredentialsError(f"keyring unavailable for {app}/{name}: {err}") from err
+
+    def _fallback_unset(self, app: str, name: str, err: Exception) -> None:
+        if self._fallback is not None:
+            _warn_keyring_fallback_once(err)
+            self._fallback.unset(app, name)
+            return
+        raise CredentialsError(f"keyring unavailable for {app}/{name}: {err}") from err
+
+
+def default_backend(*, use_keyring: bool = False) -> SecretBackend:
+    """The backend a plain ``Credentials(app)`` uses: a ``FileBackend`` by default, or a
+    ``KeyringBackend`` with a ``FileBackend`` fallback when ``use_keyring=True`` opts into
+    the OS keyring."""
+    if use_keyring:
+        return KeyringBackend(fallback=FileBackend())
+    return FileBackend()
+
+
+def _warn_keyring_fallback_once(err: Exception) -> None:
+    """Warn once, on stderr, that the OS keyring is unavailable and secrets are going to
+    the file backend instead -- so a user who opted into the keyring is not silently
+    downgraded to a plaintext file without knowing."""
+    global _warned_keyring_fallback
+    if _warned_keyring_fallback:
+        return
+    _warned_keyring_fallback = True
+    print(
+        f"xdg-kit: warning: OS keyring unavailable ({err}); using the file backend "
+        f"(credentials.json, mode 0600) instead",
+        file=sys.stderr,
+    )
+
+
+def _normalize_secret_value(value: object) -> str | None:
+    """A stored value normalised to a non-empty string, or ``None`` -- so a blank entry
+    reads as absent and falls through to the next resolution tier."""
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+# --- store write serialization ------------------------------------------------
+#
+# A file store's set/unset is a read-modify-write: load the JSON, change one key, write it
+# back. The atomic write guards against a *torn* file, not against a lost *update* -- two
+# writers that both read the old map each write back their own change, and the last one wins,
+# silently dropping the other's key. So the whole critical section is held under a lock that
+# serializes across both threads (a per-path threading.Lock) and processes (a blocking OS
+# lock on a sibling .lock file, which -- unlike credentials.json -- is never replaced, so an
+# atomic rename cannot orphan a holder's lock). Where the OS lock cannot be taken (no
+# primitive on the platform, or flock unsupported on a network FS), it degrades to the
+# thread lock alone -- correct for the single-process norm, best-effort across processes.
+
+# One lock per distinct store path, kept for the process lifetime. The registry is bounded
+# by the number of stores a process touches (a handful), not by call volume, so a plain dict
+# is right here -- eviction would buy nothing worth the machinery.
+_thread_lock_by_store_path: dict[str, threading.Lock] = {}
+_thread_lock_registry_guard = threading.Lock()
+
+
+def _thread_lock_for(store_path: str) -> threading.Lock:
+    """The process-wide lock for the store at ``store_path``, created on first use. Serializes
+    two threads of one process, which an OS file lock alone does not guarantee everywhere."""
+    with _thread_lock_registry_guard:
+        lock = _thread_lock_by_store_path.get(store_path)
+        if lock is None:
+            lock = threading.Lock()
+            _thread_lock_by_store_path[store_path] = lock
+        return lock
+
+
+@contextmanager
+def _exclusive_store_lock(path: Path) -> Iterator[None]:
+    """Hold an exclusive lock over a read-modify-write of the store file ``path``. Degrades
+    to thread-only serialization where no OS lock primitive exists, the lock file cannot be
+    created, or the OS lock cannot be taken (e.g. ``flock`` unsupported on a network FS) --
+    the in-process guarantee still holds, and single-process use is the norm."""
+    thread_lock = _thread_lock_for(str(path))
+    thread_lock.acquire()
+    try:
+        restrict_dir_to_owner(path.parent)
+        try:
+            handle: IO[str] | None = (path.parent / f"{path.name}.lock").open("a+")
+        except OSError:
+            handle = None   # cannot create the lock file: rely on the thread lock alone
+        locked = False
+        try:
+            locked = handle is not None and lock_exclusive(handle, blocking=True)
+            yield
+        finally:
+            if handle is not None:
+                try:
+                    if locked:
+                        unlock(handle)   # only when we actually took it -- never a no-op region
+                finally:
+                    handle.close()
+    finally:
+        thread_lock.release()   # its own finally: always runs, even if unlock/close raises