private-files 1.0.0__py3-none-any.whl

private_files/__init__.py

@@ -0,0 +1,514 @@
+"""
+Support for management of semnsitiive user-wide application files such as authentication tokens and profile data.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from functools import cache
+from pathlib import Path
+from typing import IO, Any, BinaryIO, Final, Literal, TextIO, TypeAlias, overload
+
+from platformdirs import user_data_dir
+
+__all__ =  [
+    "OpenTextMode",
+    "OpenBinaryMode",
+    "get_shared_private_dir",
+    "create_shared_private_dir",
+    "PrivateFilesManager",
+    "get_private_files_manager",
+    "get_private_app_dir",
+    "create_private_app_dir",
+    "get_private_dir",
+    "create_private_dir",
+    "delete_private_dir",
+    "verify_private_dir",
+    "get_private_app_file",
+    "open_private_app_file",
+]
+
+UNIX_PRIVATE_DIR_ROOT_PATH: Final[Path] = Path("~/.private")
+
+OpenTextMode: TypeAlias = Literal[
+    "r", "rt", "r+", "r+t", "rt+",
+    "w", "wt", "w+", "w+t", "wt+",
+    "a", "at", "a+", "a+t", "at+",
+    "x", "xt", "x+", "x+t", "xt+",
+]
+"""Mode strings for open() calls that produce a TextIO."""
+
+OpenBinaryMode: TypeAlias = Literal[
+    "rb", "r+b", "rb+",
+    "wb", "w+b", "wb+",
+    "ab", "a+b", "ab+",
+    "xb", "x+b", "xb+",
+]
+"""Mode strings for open() calls that produce a BinaryIO."""
+
+@cache
+def get_shared_private_dir() -> Path:
+    """Get the name of the shared user-wide private root directory for storing sensitive data like authentication tokens.
+    On linux and macos, this will be ~/.private, which the user can choose to encrypt or protect as needed.
+    On Windows, this will be the non-roaming app data directory.
+    
+    Does not create the directory or guarantee any particular permissions, so the returned directory
+    may not be safe for storing sensitive data until create_private_dir has been called.
+    """
+    if sys.platform == "win32":
+        # On Windows, use a well-known subdir of the non-roaming app data directory,
+        # which is not backed up to the cloud and is not shared across devices.
+        return Path(user_data_dir("private_files", roaming=False)).resolve()
+    else:
+        # On Linux and MacOS, use ~/.private, which the user can choose to encrypt or protect as needed
+        return UNIX_PRIVATE_DIR_ROOT_PATH.expanduser().resolve()
+
+@cache
+def create_shared_private_dir() -> Path:
+    """Create and return the shared user-wide private root directory for storing sensitive data like authentication tokens,
+    if it does not already exist. On linux and macos, this will be ~/.private, which the user can choose to encrypt or protect as needed.
+    On Windows, this will be the non-roaming app data directory.
+    
+    If the directory cannot be created or cannot be set to the correct permissions, an exception will be raised.
+    """
+    private_dir = get_shared_private_dir()
+
+    # create the ~/.private parent directory (or equivalent windows dir) with mode 0700 if necessary, and ensure permissions are correct.
+    old_umask = os.umask(0o077)
+    try:
+        os.makedirs(private_dir, mode=0o700, exist_ok=True)
+    finally:
+        os.umask(old_umask)
+    if not private_dir.is_dir():
+        raise NotADirectoryError(f"Expected {str(private_dir)!r} to be a directory, but it is not.")
+    if sys.platform != "win32":
+        current_mode = private_dir.stat().st_mode & 0o777
+        if current_mode != 0o700:
+            # For the shared ~/.private directory, we do not automatically fix the permissions, since it may be shared with
+            # other applications.
+            # But we do require that it is locked down.
+            raise PermissionError(
+                f"Expected {str(private_dir)!r} to have permissions 0700, but it has permissions {current_mode:04o}. "
+                "Please set the permissions to 0700 to protect your sensitive data."
+            )
+    return private_dir
+
+class PrivateFilesManager:
+    """A class for managing private files and directories for an application."""
+    
+    app_name: str | None
+    """The application name used to create the application-specific private directory.
+       If None, a shared private parent directory not specific to an application is used.."""
+       
+    _shared_root_dir: Path | None = None
+    """The cached shared private directory root path, if it has been computed."""
+    
+    _shared_root_dir_created: bool = False
+    """Whether the shared private directory root path has been created."""
+       
+    _root_dir: Path | None = None
+    """The cached application-specific private directory root path, if it has been computed."""
+    
+    _root_dir_created: bool = False
+    """Whether the application-specific private directory root path has been created."""
+
+    def __init__(self, app_name: str | None = None):
+        self.app_name = app_name
+    
+    def get_shared_root_dir(self) -> Path:
+        """Get the name of the shared user-wide private root directory for storing sensitive data like authentication tokens.
+        On linux and macos, this will be ~/.private, which the user can choose to encrypt or protect as needed.
+        On Windows, this will be the non-roaming app data directory.
+        
+        Does not create the directory or guarantee any particular permissions, so the returned directory
+        may not be safe for storing sensitive data until create_private_dir has been called.
+        """
+        if self._shared_root_dir is None:
+            self._shared_root_dir = get_shared_private_dir()
+        return self._shared_root_dir
+    
+    def create_shared_root_dir(self) -> Path:
+        """Create and return the shared user-wide private root directory for storing sensitive data
+        like authentication tokens, if it does not already exist. On linux and macos, this will be
+        ~/.private, which the user can choose to encrypt or protect as needed.
+        On Windows, this will be the non-roaming app data directory.
+        
+        If the directory cannot be created or cannot be set to the correct permissions, an exception will be raised.
+        """
+        shared_root_dir = self.get_shared_root_dir()
+        if not self._shared_root_dir_created:
+            create_shared_private_dir()
+            self._shared_root_dir_created = True
+        return shared_root_dir
+        
+    def get_root_dir(self) -> Path:
+        """Get the name of the application-specific user-wide private root directory for storing sensitive data like authentication tokens.
+        On linux and macos, this will be a directory under ~/.private, which the user can choose to encrypt or protect as needed.
+        On Windows, this will be the non-roaming app data directory.
+        
+        Does not create the directory or guarantee any particular permissions, so the returned directory
+        may not be safe for storing sensitive data until create_private_dir has been called.
+        """
+        app_name = self.app_name
+        if self._root_dir is None:
+            shared_root_dir = self.get_shared_root_dir()
+            root_dir = (shared_root_dir / (app_name if app_name else ".")).resolve()
+            if not root_dir.is_relative_to(shared_root_dir):
+                raise ValueError(
+                        f"Expected application-specific private directory {str(app_name)!r} to resolve to a path "
+                        f"within the shared private directory {str(self.get_shared_root_dir())!r}, but it does not."
+                    )
+            self._root_dir = root_dir
+        return self._root_dir
+    
+    def create_root_dir(self) -> Path:
+        """Create and return the application-specific user-wide private root directory for storing sensitive data
+        like authentication tokens, if it does not already exist. On Linux and MacOS, this will be a directory
+        under ~/.private with mode 0700. On Windows, this will be the non-roaming app data directory.
+        
+        If the directory cannot be created or cannot be set to the correct permissions, an exception will be raised.
+        """
+        root_dir = self.get_root_dir()
+        if not self._root_dir_created:
+            shared_root_dir = self.create_shared_root_dir()
+            if not root_dir.is_relative_to(shared_root_dir):
+                raise ValueError(
+                        f"Expected application-specific private directory {str(root_dir)!r} to resolve to a path "
+                        f"within the shared private directory {str(shared_root_dir)!r}, but it does not."
+                    )
+            rel_dir = root_dir.relative_to(shared_root_dir)
+            partial_dir = shared_root_dir
+            for component in rel_dir.parts:
+                partial_dir = partial_dir / component
+                old_umask = os.umask(0o077)
+                try:
+                    os.makedirs(partial_dir, mode=0o700, exist_ok=True)
+                finally:
+                    os.umask(old_umask)
+                if sys.platform != "win32":
+                    if not partial_dir.is_dir():
+                        raise NotADirectoryError(f"Expected {str(partial_dir)!r} to be a directory, but it is not.")
+                    current_mode = partial_dir.stat().st_mode & 0o777
+                    if current_mode != 0o700:
+                        # For our private app-specific subdir, we go ahead and fix the permissions if they are not correct,
+                        partial_dir.chmod(0o700)
+            self._root_dir_created = True
+                
+        return root_dir
+
+    def get_private_dir(self, subdir: str | Path) -> Path:
+        """Return the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+        like authentication tokens. On Linux and MacOS, this will be a directory
+        under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+        
+        Verifies that the resolved path is within the app-specific private directory, but does not
+            create the directory or guarantee any particular permissions.
+        """
+        app_dir = self.get_root_dir()
+        subdir_fullpath = (app_dir / subdir).resolve()
+        if not subdir_fullpath.is_relative_to(app_dir):
+            raise ValueError(
+                    f"Expected private subdir {str(subdir)!r} to resolve to a path "
+                    f"within the app-specific private directory {str(app_dir)!r}, but it does not."
+                )
+        return subdir_fullpath
+
+    def create_private_dir(self, subdir: str | Path) -> Path:
+        """Create and return the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+        like authentication tokens, if it does not already exist. On Linux and MacOS, this will be a directory
+        under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+        
+        If the directory cannot be created or cannot be set to the correct permissions, an exception will be raised.
+        
+        If subdir is a relative path, it is resolved relative to the the app-specific private root directory.
+        Regardless, it must resolve to the app-specific root directory or a subdirectory of it.
+        For example, "." can be used to refer to the app-specific private root directory itself.
+        """
+        app_dir_path = self.create_root_dir()
+        subdir_fullpath = self.get_private_dir(subdir)
+        subdir_path = subdir_fullpath.relative_to(app_dir_path)
+        subdir_partial_path = app_dir_path
+        for component in subdir_path.parts:
+            subdir_partial_path = subdir_partial_path / component
+            old_umask = os.umask(0o077)
+            try:
+                os.makedirs(subdir_partial_path, mode=0o700, exist_ok=True)
+            finally:
+                os.umask(old_umask)
+            if sys.platform != "win32":
+                if not subdir_partial_path.is_dir():
+                    raise NotADirectoryError(f"Expected {str(subdir_partial_path)!r} to be a directory, but it is not.")
+                current_mode = subdir_partial_path.stat().st_mode & 0o777
+                if current_mode != 0o700:
+                    subdir_partial_path.chmod(0o700)
+        return subdir_fullpath
+
+    def delete_private_dir(self, subdir: str | Path) -> None:
+        """Delete the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+        like authentication tokens, if it exists. On Linux and MacOS, this will be a directory
+        under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+        
+        If the directory does not exist, nothing happens. If the directory cannot be deleted, an exception will be raised.
+        
+        If subdir_name is a relative path, it is resolved relative to the the app-specific private root directory.
+        Regardless, it must resolve to the app-specific root directory or a subdirectory of it.
+        For example, "." can be used to refer to the app-specific private root directory itself.
+        
+        Deletion of the shared root directory itself is not allowed.
+        """
+        subdir_fullpath = self.get_private_dir(subdir)
+        if subdir_fullpath == self.get_shared_root_dir():
+            raise ValueError(
+                    f"Deletion of the shared private root directory {str(subdir_fullpath)!r} is not allowed. "
+                    "Please delete application-specific ubdirectories instead."
+                )
+        if not subdir_fullpath.is_dir():
+            raise NotADirectoryError(f"Expected {str(subdir_fullpath)!r} to be a directory, but it is not.")
+        shutil.rmtree(subdir_fullpath)
+        
+    def verify_private_dir(self, subdir: str | Path) -> Path:
+        """Verify that the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+        like authentication tokens exists and has permissions 0700. On Linux and MacOS, this will be a directory
+        under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+        
+        If the directory does not exist or does not have permissions 0700, an exception will be raised.
+        
+        If subdir_name is a relative path, it is resolved relative to the the app-specific private root directory.
+        Regardless, it must resolve to the app-specific root directory or a subdirectory of it.
+        For example, "." can be used to refer to the app-specific private root directory itself.
+        """
+        app_dir = self.get_root_dir()
+        app_dir_parent = app_dir.parent
+        subdir_full = self.get_private_dir(subdir)
+        subdir_relpath = subdir_full.relative_to(app_dir_parent)
+        subdir_partial_path = app_dir_parent
+        for component in subdir_relpath.parts:
+            subdir_partial_path = subdir_partial_path / component
+            if not subdir_partial_path.is_dir():
+                raise NotADirectoryError(f"Expected {str(subdir_partial_path)!r} to be a directory, but it is not.")
+            if sys.platform != "win32":
+                current_mode = subdir_partial_path.stat().st_mode & 0o777
+                if current_mode != 0o700:
+                    raise PermissionError(
+                            f"Expected {str(subdir_partial_path)!r} to have permissions 0700, but it has permissions {current_mode:04o}. "
+                            "Please set the permissions to 0700 to protect your sensitive data."
+                        )
+        return subdir_full
+    
+    def get_private_file(
+                self,
+                filename: str | Path,
+                create_parent: bool = False,
+                subdir: str | Path = ".",
+            ) -> Path:
+        """Get the fully qualified path to a file with the given name in the application-specific
+        user-wide private directory for storing sensitive data like authentication tokens.
+        
+        subdir_name is resolved relative to the app-specific private root directory,
+        and filename is resolved relative to subdir_name. The file must resolve
+        to a file within the specified subdirectory, or a ValueError will be raised.
+        
+        If create_parent is True, the parent directory/directories, up to and including the application-specific root
+        directory, will be created if they do not already exist, and their permissions will be adjusted to 0700.
+        
+        If create_parent is False, the directory is not created but the existence and permissions of
+        all parent directories are verified.
+        
+        The file itself is not created, and no guarantees are made about its existence or permissions."""
+        subdir_path = self.get_private_dir(subdir)
+        file_path = (subdir_path / filename).resolve()
+        if not file_path.is_relative_to(subdir_path):
+            raise ValueError(
+                    f"Expected private file {str(filename)!r} to resolve to a path "
+                    f"within the app-specific private directory {str(subdir_path)!r}, but it does not."
+                )
+        parent_dir = file_path.parent
+        if create_parent:
+            self.create_private_dir(parent_dir)
+        else:
+            self.verify_private_dir(parent_dir)
+        return file_path
+
+    @overload
+    def open(
+            self, filename: str | Path, mode: OpenTextMode, *, subdir: str | Path = ".", create_parent: bool = False, **kwargs: Any
+        ) -> TextIO: ...
+
+    @overload
+    def open(
+            self, filename: str | Path, mode: OpenBinaryMode, *, subdir: str | Path = ".", create_parent: bool = False, **kwargs: Any
+        ) -> BinaryIO: ...
+
+    @overload
+    def open(
+            self, filename: str | Path, mode: str, *, subdir: str | Path = ".", create_parent: bool = False, **kwargs: Any
+        ) -> IO[Any]: ...
+
+    def open(
+                self,
+                filename: str | Path,
+                mode: str = "r", *,
+                subdir: str | Path = ".",
+                create_parent: bool = False,
+                **kwargs: Any
+            ) -> IO[Any]:
+        """Open a file with the given name in the application-specific user-wide private directory and subdirectory,
+        creating the directory if necessary. If writing to the file, ensure that it has permissions 0600
+        (readable and writable only by the user)."""
+        
+        allows_create = any(m in mode for m in "wax")
+        is_write_mode = any(m in mode for m in "wax+")
+        file_path = self.get_private_file(filename, create_parent=allows_create or create_parent, subdir=subdir)
+        f = open(file_path, mode, **kwargs)  # noqa: SIM115
+        try:
+            if is_write_mode and sys.platform != "win32":
+                # On Linux and MacOS, ensure the file has mode 400 (readable only by the user).
+                fd = f.fileno()
+                st = os.fstat(fd)
+                mode_bits = st.st_mode & 0o777
+                if mode_bits != 0o600:
+                    os.fchmod(fd, 0o600)
+        except Exception:
+            f.close()
+            raise
+        return f
+
+@cache
+def get_private_files_manager(app_name: str | None = None) -> PrivateFilesManager:
+    """Get a cached PrivateFilesManager instance for the given application name."""
+    return PrivateFilesManager(app_name=app_name)
+
+def get_private_app_dir(app_name: str | None = None) -> Path:
+    """Return the application-specific user-wide private directory for storing sensitive data
+       like authentication tokens. On Linux and MacOS, this will be a directory
+       under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+    """
+    return get_private_files_manager(app_name).get_root_dir()
+
+def create_private_app_dir(app_name: str | None = None) -> Path:
+    """Create and return the application-specific user-wide private root directory for storing sensitive data
+    like authentication tokens, if it does not already exist. On Linux and MacOS, this will be a directory
+    under ~/.private with mode 0700. On Windows, this will be the non-roaming app data directory.
+    
+    If the directory cannot be created or cannot be set to the correct permissions, an exception will be raised.
+    """
+    return get_private_files_manager(app_name).create_root_dir()
+
+def get_private_dir(subdir: str | Path, app_name: str | None = None) -> Path:
+    """Return the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+       like authentication tokens. On Linux and MacOS, this will be a directory
+       under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+       
+       Verifies that the resolved path is within the app-specific private directory, but does not
+         create the directory or guarantee any particular permissions.
+    """
+    return get_private_files_manager(app_name).get_private_dir(subdir)
+
+def create_private_dir(subdir: str | Path, app_name: str | None = None) -> Path:
+    """Create and return the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+       like authentication tokens, if it does not already exist. On Linux and MacOS, this will be a directory
+       under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+       
+       If the directory cannot be created or cannot be set to the correct permissions, an exception will be raised.
+       
+       If subdir_name is a relative path, it is resolved relative to the the app-specific private root directory.
+       Regardless, it must resolve to the app-specific root directory or a subdirectory of it.
+       For example, "." can be used to refer to the app-specific private root directory itself.
+    """
+    return get_private_files_manager(app_name).create_private_dir(subdir)
+
+def delete_private_dir(subdir_name: str | Path, app_name: str) -> None:
+    """Delete the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+       like authentication tokens, if it exists. On Linux and MacOS, this will be a directory
+       under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+       
+       If the directory does not exist, nothing happens. If the directory cannot be deleted, an exception will be raised.
+       
+       If subdir_name is a relative path, it is resolved relative to the the app-specific private root directory.
+       Regardless, it must resolve to the app-specific root directory or a subdirectory of it.
+       For example, "." can be used to refer to the app-specific private root directory itself.
+       
+       Deletion of the shared root directory itself is not allowed.
+    """
+    subdir_fullpath = get_private_dir(subdir_name, app_name=app_name)
+    if subdir_fullpath.is_dir():
+        shutil.rmtree(subdir_fullpath)
+
+def verify_private_dir(subdir_name: str | Path, app_name: str | None = None) -> Path:
+    """Verify that the application-specific user-wide private directory or a subdirectory thereof for storing sensitive data
+       like authentication tokens exists and has permissions 0700. On Linux and MacOS, this will be a directory
+       under ~/.private/{app_name} with mode 0700. On Windows, this will be under the non-roaming app data directory.
+       
+       If the directory does not exist or does not have permissions 0700, an exception will be raised.
+       
+       If subdir_name is a relative path, it is resolved relative to the the app-specific private root directory.
+       Regardless, it must resolve to the app-specific root directory or a subdirectory of it.
+       For example, "." can be used to refer to the app-specific private root directory itself.
+    """
+    return get_private_files_manager(app_name).verify_private_dir(subdir_name)
+
+def get_private_app_file(
+            filename: str | Path,
+            *,
+            create_parent: bool = False,
+            subdir: str | Path = ".",
+            app_name: str | None = None,
+        ) -> Path:
+    """Get the fully qualified path to a file with the given name in the application-specific
+       user-wide private directory for storing sensitive data like authentication tokens.
+       
+       subdir_name is resolved relative to the app-specific private root directory,
+       and filename is resolved relative to subdir_name. The file must resolve to a file within the
+       specified subdirectory, or a ValueError will be raised.
+       
+       If create_parent is True, the parent directory/directories, up to and including the application-specific root
+       directory, will be created if they do not already exist, and their permissions will be adjusted to 0700.
+       
+       If create_parent is False, the directory is not created but the existence and permissions of
+       all parent directories are verified.
+       
+       The file itself is not created, and no guarantees are made about its existence or permissions."""
+    return get_private_files_manager(app_name).get_private_file(
+            filename=filename,
+            create_parent=create_parent,
+            subdir=subdir,
+        )
+
+@overload
+def open_private_app_file(
+        filename: str | Path, mode: OpenTextMode, *, subdir: str | Path = ".",
+        create_parent: bool = False, app_name: str | None = None, **kwargs: Any
+    ) -> TextIO: ...
+
+@overload
+def open_private_app_file(
+        filename: str | Path, mode: OpenBinaryMode, *, subdir: str | Path = ".",
+        create_parent: bool = False, app_name: str | None = None, **kwargs: Any
+    ) -> BinaryIO: ...
+
+@overload
+def open_private_app_file(
+        filename: str | Path, mode: str, *, subdir: str | Path = ".",
+        create_parent: bool = False, app_name: str | None = None, **kwargs: Any
+    ) -> IO[Any]: ...
+
+def open_private_app_file(
+            filename: str | Path,
+            mode: str = "r",
+            *,
+            subdir: str | Path = ".",
+            create_parent: bool = False,
+            app_name: str | None = None,
+            **kwargs: Any
+        ) -> IO[Any]:
+    """Open a file with the given name in the application-specific user-wide private directory and subdirectory,
+       creating the directory if necessary. This is a convenience wrapper around get_private_app_file and open."""
+    return get_private_files_manager(app_name).open(
+            filename=filename,
+            mode=mode,
+            subdir=subdir,
+            create_parent=create_parent,
+            **kwargs
+        )

private_files-1.0.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.1
+Name: private-files
+Version: 1.0.0
+Summary: Manage secret/private files in an os-independent way
+Keywords: private,secrets,credentials,security,permissions,config,cross-platform,filesystem,dotfiles,application-data
+Author-Email: Sam McKelvie <dev@mckelvie.org>
+License: MIT License
+         
+         Copyright (c) 2026 Samuel J. McKelvie
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/mckelvie-org/private-files
+Project-URL: Source, https://github.com/mckelvie-org/private-files/tree/v1.0.0
+Project-URL: Bug Tracker, https://github.com/mckelvie-org/private-files/issues
+Project-URL: Changelog, https://github.com/mckelvie-org/private-files/releases
+Requires-Python: >=3.10
+Requires-Dist: platformdirs>=4.0.0
+Description-Content-Type: text/markdown
+
+# private-files
+
+[![CI](https://img.shields.io/badge/CI-passing-brightgreen.svg)](https://github.com/mckelvie-org/private-files/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/private-files/1.0.0/)
+[![Python versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue.svg)](https://pypi.org/project/private-files/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+`private-files`: Manage secret/private files in an os-independent way.
+
+Applications that need to persist sensitive data on a user's machine &mdash; API tokens, session cookies,
+credentials, profile data &mdash; need somewhere to put it that isn't the world-readable home directory
+clutter of `~/.config` or `~/.myapp`. `private-files` gives every application its own subdirectory of a
+single, locked-down, user-wide private root, and enforces `0700`/`0600` permissions on directories and
+files it creates so secrets are never accidentally left group- or world-readable.
+
+## Highlights
+
+- **One shared private root per user.** On Linux and macOS this is `~/.private`; on Windows it's the
+  non-roaming application-data directory (via [`platformdirs`](https://pypi.org/project/platformdirs/)),
+  which is not synced to the cloud or shared across devices.
+- **Per-application subdirectories.** Each app gets its own subdirectory of the shared root, named after
+  an `app_name` you choose, so multiple applications can share the same machine without stepping on each
+  other's secrets.
+- **Permissions are enforced, not assumed.** Directories created by this package are `chmod 0700`; files
+  opened for writing are `chmod 0600`. Existing app-specific directories with the wrong permissions are
+  fixed automatically; the shared root itself is only ever checked, never silently "fixed," since it may
+  be shared with other applications.
+- **Path-traversal safe.** Subdirectory and filename arguments are resolved and checked to ensure they
+  stay within the intended app directory &mdash; a `subdir` or `filename` of `"../../etc/passwd"` raises
+  `ValueError` instead of silently escaping the sandbox.
+- **Two equivalent APIs.** A `PrivateFilesManager` class for when you're working with one application
+  repeatedly (it caches the resolved paths), and a set of flat module-level functions for one-off calls,
+  both backed by the same cached manager instances.
+- **Drop-in `open()` replacement.** `open_private_app_file()` / `PrivateFilesManager.open()` behave like
+  the builtin `open()` &mdash; including `@overload`-based mode-based return-type inference (`TextIO` vs
+  `BinaryIO`) &mdash; but resolve the path into the private directory and create parent directories and
+  fix file permissions automatically.
+- **Fully typed**, `mypy --strict` clean, zero required dependencies beyond `platformdirs`.
+
+## Installation
+
+```bash
+pip install private-files
+```
+
+## Quick Start
+
+```python
+from private_files import open_private_app_file, get_private_app_dir
+
+# Write a secret. Parent directories are created automatically (mode 0700),
+# and the file itself ends up with mode 0600.
+with open_private_app_file("api-token.txt", "w", app_name="myapp") as f:
+    f.write("super-secret-token")
+
+# Read it back later.
+with open_private_app_file("api-token.txt", "r", app_name="myapp") as f:
+    token = f.read()
+
+# Find out where it lives on disk, without opening it.
+print(get_private_app_dir(app_name="myapp"))
+# -> /home/alice/.private/myapp   (Linux/macOS)
+# -> C:\Users\alice\AppData\Local\myapp\myapp   (Windows)
+```
+
+If your application makes several calls, prefer a `PrivateFilesManager`, which resolves and caches its
+paths once instead of on every call:
+
+```python
+from private_files import PrivateFilesManager
+
+files = PrivateFilesManager(app_name="myapp")
+
+with files.open("api-token.txt", "w") as f:
+    f.write("super-secret-token")
+
+with files.open("session/cookies.json", "w", create_parent=True) as f:
+    f.write("{}")
+
+files.delete_private_dir("session")
+```
+
+`get_private_files_manager(app_name)` returns a process-wide cached `PrivateFilesManager` for a given
+`app_name`, which is what all of the flat module-level functions use internally &mdash; so mixing the two
+styles for the same `app_name` shares the same cached, verified paths.
+
+## Concepts
+
+### Shared root vs. app-specific directory
+
+There are two levels of directory:
+
+- The **shared private root** is one directory per user, shared by every application using this package:
+  `~/.private` on Linux/macOS, or the non-roaming app-data directory on Windows. It must already have
+  (or be given) permissions `0700`. This package will create it if missing but will **not** silently fix
+  its permissions if it already exists with the wrong mode, since it may be shared with other
+  applications you don't control &mdash; instead it raises `PermissionError` so you can decide what to do.
+- The **application-specific directory** is a subdirectory of the shared root named after your `app_name`
+  (e.g. `~/.private/myapp`). Unlike the shared root, this package **does** own it, so it actively enforces
+  and repairs `0700` permissions on it and any subdirectories you create within it.
+
+Passing `app_name=None` (the default) targets the shared root itself rather than a per-application
+subdirectory.
+
+### Subdirectories and files
+
+Within an application's directory you can create arbitrarily nested subdirectories (`subdir="cache/v2"`)
+and files within them. Every directory component created by `create_private_dir()` (or implicitly by
+`create_parent=True`) gets its permissions verified and, if necessary, corrected to `0700`. Every
+directory checked by `verify_private_dir()` must already be `0700`, or a `PermissionError` is raised.
+
+All `subdir` and `filename` arguments are resolved and checked against the directory they're supposed to
+be contained within; anything that would resolve outside of it (via `..`, absolute paths outside the
+tree, symlinks, etc.) raises `ValueError` rather than being silently permitted.
+
+## API Reference
+
+### `PrivateFilesManager`
+
+```python
+class PrivateFilesManager:
+    def __init__(self, app_name: str | None = None): ...
+```
+
+An object bound to a single `app_name` (or `None` for the shared root) that resolves and caches its
+directory paths across calls.
+
+| Method | Description |
+| --- | --- |
+| `get_shared_root_dir() -> Path` | The shared private root (e.g. `~/.private`). Computed, not created. |
+| `create_shared_root_dir() -> Path` | Create the shared root if missing (mode `0700`); raise `PermissionError` if it exists with the wrong mode. |
+| `get_root_dir() -> Path` | This manager's app-specific directory. Computed, not created. |
+| `create_root_dir() -> Path` | Create the app-specific directory (and the shared root, if needed), fixing permissions at every level. |
+| `get_private_dir(subdir) -> Path` | Resolve `subdir` under the app directory. Does not create anything. |
+| `create_private_dir(subdir) -> Path` | Create `subdir` (and every intermediate component) under the app directory, mode `0700`. |
+| `delete_private_dir(subdir) -> None` | Recursively delete `subdir`. No-op if it doesn't exist. Raises `ValueError` if `subdir` resolves to the shared root itself. |
+| `verify_private_dir(subdir) -> Path` | Raise `NotADirectoryError`/`PermissionError` unless `subdir` (and everything above it, up to the shared root) exists with mode `0700`. |
+| `get_private_file(filename, *, create_parent=False, subdir=".") -> Path` | Resolve the full path to a file. Verifies (or creates, if `create_parent=True`) its parent directory. The file itself is never created. |
+| `open(filename, mode="r", *, subdir=".", create_parent=False, **kwargs) -> IO` | Like builtin `open()`, but resolved into the app directory. Parent directories are auto-created for write/append/exclusive-create modes (or when `create_parent=True`); files opened for writing get mode `0600`. |
+
+`subdir="."` refers to the app directory itself. All `subdir`/`filename` parameters accept `str | Path`.
+
+### Module-level functions
+
+Thin wrappers around a cached `PrivateFilesManager` per `app_name`, for callers that don't want to hold
+onto a manager instance themselves:
+
+| Function | Equivalent to |
+| --- | --- |
+| `get_shared_private_dir() -> Path` | `PrivateFilesManager().get_shared_root_dir()` |
+| `create_shared_private_dir() -> Path` | `PrivateFilesManager().create_shared_root_dir()` |
+| `get_private_files_manager(app_name=None) -> PrivateFilesManager` | Returns the cached manager for `app_name`. |
+| `get_private_app_dir(app_name=None) -> Path` | `manager.get_root_dir()` |
+| `create_private_app_dir(app_name=None) -> Path` | `manager.create_root_dir()` |
+| `get_private_dir(subdir, app_name=None) -> Path` | `manager.get_private_dir(subdir)` |
+| `create_private_dir(subdir, app_name=None) -> Path` | `manager.create_private_dir(subdir)` |
+| `delete_private_dir(subdir_name, app_name) -> None` | `manager.delete_private_dir(subdir_name)` |
+| `verify_private_dir(subdir_name, app_name=None) -> Path` | `manager.verify_private_dir(subdir_name)` |
+| `get_private_app_file(filename, *, create_parent=False, subdir=".", app_name=None) -> Path` | `manager.get_private_file(...)` |
+| `open_private_app_file(filename, mode="r", *, subdir=".", create_parent=False, app_name=None, **kwargs) -> IO` | `manager.open(...)` |
+
+`get_private_files_manager(app_name)` is `@functools.cache`d, so repeated calls with the same `app_name`
+(directly, or indirectly via any of the flat functions above) return the same manager instance and reuse
+its already-resolved, already-verified paths. This means the *first* successful resolution of a given
+`app_name`'s directory sticks for the lifetime of the process, even if the underlying shared root were to
+change (e.g. `$HOME` changing at runtime) &mdash; construct a fresh `PrivateFilesManager` directly if you
+need to bypass the cache.
+
+## Examples
+
+### Reading and writing binary data
+
+```python
+from private_files import open_private_app_file
+
+with open_private_app_file("cache.bin", "wb", app_name="myapp") as f:
+    f.write(b"\x00\x01\x02")
+
+with open_private_app_file("cache.bin", "rb", app_name="myapp") as f:
+    data = f.read()
+```
+
+### Nested subdirectories
+
+```python
+from private_files import PrivateFilesManager
+
+files = PrivateFilesManager(app_name="myapp")
+files.create_private_dir("sessions/2024")  # creates both levels, each mode 0700
+path = files.get_private_dir("sessions/2024")
+```
+
+### Checking a directory without creating it
+
+```python
+from private_files import verify_private_dir
+
+try:
+    verify_private_dir("sessions", app_name="myapp")
+except (NotADirectoryError, PermissionError) as e:
+    print(f"not ready: {e}")
+```
+
+### Cleaning up
+
+```python
+from private_files import delete_private_dir
+
+# Removes the directory and everything under it. No error if it doesn't exist.
+delete_private_dir("sessions", app_name="myapp")
+```
+
+## Supported Python Versions
+
+Python 3.10 through 3.14.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+For development and release workflow documentation, see [CONTRIBUTING.md](CONTRIBUTING.md).

private_files-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+private_files-1.0.0.dist-info/METADATA,sha256=15ubh_YiOclNIPZuHFOv--s3dcJF5lVm7WOR7twL0Z0,13820
+private_files-1.0.0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+private_files-1.0.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+private_files-1.0.0.dist-info/licenses/LICENSE,sha256=EiZGhGF2LQUXbByZTzYnYzbwZ-ATrF2MLPUxHKfPnHA,1075
+private_files/__init__.py,sha256=hTYJoyI5AJP2nAAMWt3VqD8ZbUG9t6B1dbQTUSfXv0A,26703
+private_files/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+private_files-1.0.0.dist-info/RECORD,,

private_files-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.9)
+Root-Is-Purelib: true
+Tag: py3-none-any

private_files-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+

private_files-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel J. McKelvie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.