Skip to content

jmcore.secure_files

jmcore.secure_files

Private directory and atomic secret-file utilities.

Attributes

logger = logging.getLogger(__name__) module-attribute

Functions:

atomic_write_private(path: Path, data: bytes) -> None

Atomically replace private bytes, syncing the file and supported parent directory.

A directory-sync failure propagates after replacement: new bytes may already be present, but their crash durability has not been confirmed.

Source code in jmcore/src/jmcore/secure_files.py
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def atomic_write_private(path: Path, data: bytes) -> None:
    """Atomically replace private bytes, syncing the file and supported parent directory.

    A directory-sync failure propagates after replacement: new bytes may already
    be present, but their crash durability has not been confirmed.
    """
    _reject_parent_traversal(path)
    parent = path.parent
    if parent.is_symlink():
        raise OSError(f"refusing to use symlink as private directory: {parent}")
    if not parent.exists():
        ensure_private_directory(parent)

    fd, temp_name = tempfile.mkstemp(
        dir=parent,
        prefix=f".{path.name}.",
        suffix=".tmp",
    )
    temp_path = Path(temp_name)
    try:
        os.fchmod(fd, 0o600)
        with os.fdopen(fd, "wb") as temp_file:
            fd = -1
            temp_file.write(data)
            temp_file.flush()
            os.fsync(temp_file.fileno())
        os.replace(temp_path, path)
        _sync_directory(parent)
    finally:
        if fd >= 0:
            os.close(fd)
        with suppress(FileNotFoundError):
            temp_path.unlink()

atomic_write_sensitive_file(path: Path, data: bytes) -> None

Atomically update a sensitive file while preserving configured aliases.

Source code in jmcore/src/jmcore/secure_files.py
192
193
194
def atomic_write_sensitive_file(path: Path, data: bytes) -> None:
    """Atomically update a sensitive file while preserving configured aliases."""
    atomic_write_private(path.resolve(strict=False), data)

create_private_file_exclusive(path: Path, data: bytes) -> None

Create and sync a missing private file without replacing any existing path.

Failed initialization leaves its bytes in place for explicit recovery rather than allowing another attempt to mistake partial state for a missing file.

Source code in jmcore/src/jmcore/secure_files.py
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def create_private_file_exclusive(path: Path, data: bytes) -> None:
    """Create and sync a missing private file without replacing any existing path.

    Failed initialization leaves its bytes in place for explicit recovery rather
    than allowing another attempt to mistake partial state for a missing file.
    """
    _reject_parent_traversal(path)
    parent = path.parent
    if parent.is_symlink():
        raise OSError(f"refusing to use symlink as private directory: {parent}")
    if not parent.exists():
        ensure_private_directory(parent)
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0), 0o600)
    try:
        os.fchmod(fd, 0o600)
        with os.fdopen(fd, "wb") as new_file:
            fd = -1
            new_file.write(data)
            new_file.flush()
            os.fsync(new_file.fileno())
        _sync_directory(parent)
    finally:
        if fd >= 0:
            os.close(fd)

ensure_private_directory(path: Path) -> None

Create or tighten a secret-bearing directory to owner-only access.

Source code in jmcore/src/jmcore/secure_files.py
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def ensure_private_directory(path: Path) -> None:
    """Create or tighten a secret-bearing directory to owner-only access."""
    _reject_parent_traversal(path)
    if path.is_symlink():
        raise OSError(f"refusing to use symlink as private directory: {path}")

    missing_parents: list[Path] = []
    parent = path.parent
    while not parent.exists():
        missing_parents.append(parent)
        if parent == parent.parent:
            break
        parent = parent.parent

    for parent in reversed(missing_parents):
        parent.mkdir(mode=0o700, exist_ok=True)
        _tighten_private_directory(parent)

    path.mkdir(mode=0o700, exist_ok=True)
    _tighten_private_directory(path)

ensure_private_file(path: Path) -> None

Tighten an existing regular secret file to owner-only access.

Source code in jmcore/src/jmcore/secure_files.py
 99
100
101
102
def ensure_private_file(path: Path) -> None:
    """Tighten an existing regular secret file to owner-only access."""
    fd = _open_private_regular_file(path)
    os.close(fd)

ensure_sensitive_directory(path: Path) -> None

Create a missing application directory privately without changing an existing one.

Source code in jmcore/src/jmcore/secure_files.py
112
113
114
115
116
def ensure_sensitive_directory(path: Path) -> None:
    """Create a missing application directory privately without changing an existing one."""
    resolved_path = path.resolve(strict=False)
    if not resolved_path.exists():
        ensure_private_directory(resolved_path)

ensure_sensitive_file(path: Path) -> None

Best-effort tighten a regular config or metadata file, following aliases.

Source code in jmcore/src/jmcore/secure_files.py
119
120
121
122
123
124
125
126
def ensure_sensitive_file(path: Path) -> None:
    """Best-effort tighten a regular config or metadata file, following aliases."""
    fd = _open_regular_file(
        path,
        follow_final_symlink=True,
        allow_unchanged_mode=True,
    )
    os.close(fd)

read_private_file(path: Path) -> bytes

Read and tighten a regular secret file through one no-follow descriptor.

Source code in jmcore/src/jmcore/secure_files.py
105
106
107
108
109
def read_private_file(path: Path) -> bytes:
    """Read and tighten a regular secret file through one no-follow descriptor."""
    fd = _open_private_regular_file(path)
    with os.fdopen(fd, "rb") as private_file:
        return private_file.read()

read_sensitive_file(path: Path) -> bytes

Read a regular config or metadata file, following aliases when configured.

Source code in jmcore/src/jmcore/secure_files.py
129
130
131
132
133
134
135
136
137
def read_sensitive_file(path: Path) -> bytes:
    """Read a regular config or metadata file, following aliases when configured."""
    fd = _open_regular_file(
        path,
        follow_final_symlink=True,
        allow_unchanged_mode=True,
    )
    with os.fdopen(fd, "rb") as sensitive_file:
        return sensitive_file.read()