fscryptography 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fscryptography/__init__.py +41 -0
- fscryptography/_directory.py +99 -0
- fscryptography/_filesystem.py +671 -0
- fscryptography/_journal.py +493 -0
- fscryptography/_master_key.py +294 -0
- fscryptography/crypto.py +89 -0
- fscryptography/errors.py +52 -0
- fscryptography/file_format.py +178 -0
- fscryptography/names/__init__.py +16 -0
- fscryptography/names/codec.py +116 -0
- fscryptography/names/tink_backend.py +28 -0
- fscryptography/names/validation.py +84 -0
- fscryptography/py.typed +0 -0
- fscryptography-0.1.0.dist-info/METADATA +168 -0
- fscryptography-0.1.0.dist-info/RECORD +18 -0
- fscryptography-0.1.0.dist-info/WHEEL +5 -0
- fscryptography-0.1.0.dist-info/licenses/LICENSE +25 -0
- fscryptography-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,493 @@
|
|
|
1
|
+
"""Persistent transaction journal and read-only recovery inspection.
|
|
2
|
+
|
|
3
|
+
The journal is diagnostic evidence, not an authorization to mutate resources.
|
|
4
|
+
"""
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import re
|
|
10
|
+
import secrets
|
|
11
|
+
import stat
|
|
12
|
+
import sys
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any
|
|
16
|
+
|
|
17
|
+
from .errors import NameConstraintError
|
|
18
|
+
from .names import NameProfile, validate_name
|
|
19
|
+
|
|
20
|
+
_PREFIX = ".fscryptography-txn-"
|
|
21
|
+
_ID = re.compile(r"^[0-9a-f]{32}$")
|
|
22
|
+
_MAX_RECORD = 16 * 1024
|
|
23
|
+
_OPERATIONS = {"file_encrypt", "file_decrypt", "dir_encrypt", "dir_decrypt"}
|
|
24
|
+
_STATES = {"prepared", "result_ready", "published", "source_retained", "source_removed", "complete"}
|
|
25
|
+
_FIELDS = {
|
|
26
|
+
"format", "transaction_id", "operation", "state", "parent_identity",
|
|
27
|
+
"source_name", "destination_name", "temporary_name", "source_identity",
|
|
28
|
+
"result_identity", "created_ns",
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True, slots=True)
|
|
33
|
+
class RecoveryRecord:
|
|
34
|
+
transaction_id: str
|
|
35
|
+
operation: str | None
|
|
36
|
+
state: str | None
|
|
37
|
+
classification: str
|
|
38
|
+
source_name: str | None = None
|
|
39
|
+
destination_name: str | None = None
|
|
40
|
+
temporary_name: str | None = None
|
|
41
|
+
detail: str | None = None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _identity(info: os.stat_result) -> dict[str, int]:
|
|
45
|
+
return {"device": int(info.st_dev), "inode": int(info.st_ino)}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _valid_identity(value: Any) -> bool:
|
|
49
|
+
return (
|
|
50
|
+
isinstance(value, dict)
|
|
51
|
+
and set(value) == {"device", "inode"}
|
|
52
|
+
and type(value["device"]) is int
|
|
53
|
+
and type(value["inode"]) is int
|
|
54
|
+
and 0 <= value["device"] <= 2**64 - 1
|
|
55
|
+
and 0 <= value["inode"] <= 2**64 - 1
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _component(value: Any) -> bool:
|
|
60
|
+
return (
|
|
61
|
+
isinstance(value, str)
|
|
62
|
+
and bool(value)
|
|
63
|
+
and value not in {".", ".."}
|
|
64
|
+
and "\x00" not in value
|
|
65
|
+
and "/" not in value
|
|
66
|
+
and "\\" not in value
|
|
67
|
+
and len(value.encode("utf-8", "strict")) <= 4096
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _pairs(pairs):
|
|
72
|
+
result = {}
|
|
73
|
+
for key, value in pairs:
|
|
74
|
+
if key in result:
|
|
75
|
+
raise ValueError("duplicate JSON object key")
|
|
76
|
+
result[key] = value
|
|
77
|
+
return result
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _encode(data: dict[str, Any]) -> bytes:
|
|
81
|
+
raw = json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8")
|
|
82
|
+
if len(raw) > _MAX_RECORD:
|
|
83
|
+
raise ValueError("journal exceeds maximum size")
|
|
84
|
+
return raw
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _decode(raw: bytes, transaction_id: str, parent_info: os.stat_result) -> dict[str, Any]:
|
|
88
|
+
if not raw or len(raw) > _MAX_RECORD or raw.startswith(b"\xef\xbb\xbf"):
|
|
89
|
+
raise ValueError("journal size or encoding is invalid")
|
|
90
|
+
text = raw.decode("utf-8", "strict")
|
|
91
|
+
data = json.loads(text, object_pairs_hook=_pairs, parse_constant=lambda _: (_ for _ in ()).throw(ValueError("invalid JSON constant")))
|
|
92
|
+
if not isinstance(data, dict) or set(data) != _FIELDS:
|
|
93
|
+
raise ValueError("journal fields do not match schema")
|
|
94
|
+
if type(data["format"]) is not int or data["format"] != 1:
|
|
95
|
+
raise ValueError("unsupported journal format")
|
|
96
|
+
if data["transaction_id"] != transaction_id or not _ID.fullmatch(transaction_id):
|
|
97
|
+
raise ValueError("transaction identifier mismatch")
|
|
98
|
+
if data["operation"] not in _OPERATIONS or data["state"] not in _STATES:
|
|
99
|
+
raise ValueError("unknown operation or state")
|
|
100
|
+
if not _valid_identity(data["parent_identity"]) or not _valid_identity(data["source_identity"]):
|
|
101
|
+
raise ValueError("invalid resource identity")
|
|
102
|
+
if not _valid_identity(data["result_identity"]) and data["result_identity"] is not None:
|
|
103
|
+
raise ValueError("invalid result identity")
|
|
104
|
+
if not _component(data["source_name"]) or not _component(data["destination_name"]):
|
|
105
|
+
raise ValueError("invalid resource basename")
|
|
106
|
+
if data["source_name"] == data["destination_name"]:
|
|
107
|
+
raise ValueError("source and destination names are equal")
|
|
108
|
+
is_file = data["operation"].startswith("file_")
|
|
109
|
+
if data["temporary_name"] != ("result" if is_file else None):
|
|
110
|
+
raise ValueError("temporary name does not match operation")
|
|
111
|
+
if type(data["created_ns"]) is not int or not 0 <= data["created_ns"] <= 2**63 - 1:
|
|
112
|
+
raise ValueError("invalid creation timestamp")
|
|
113
|
+
# Canonical representation is required; this also rejects trailing bytes/newlines.
|
|
114
|
+
if _encode(data) != raw:
|
|
115
|
+
raise ValueError("journal is not canonically encoded")
|
|
116
|
+
return data
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _sync_directory(path: Path) -> None:
|
|
120
|
+
if os.name == "nt":
|
|
121
|
+
return
|
|
122
|
+
if not sys.platform.startswith("linux"):
|
|
123
|
+
raise OSError("directory fsync is unsupported")
|
|
124
|
+
fd = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0))
|
|
125
|
+
try:
|
|
126
|
+
os.fsync(fd)
|
|
127
|
+
finally:
|
|
128
|
+
os.close(fd)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class Transaction:
|
|
132
|
+
"""Internal writer for one transaction directory."""
|
|
133
|
+
|
|
134
|
+
def __init__(self, parent: Path, directory: Path, data: dict[str, Any], *, parent_fd: int | None = None):
|
|
135
|
+
self.parent = parent
|
|
136
|
+
self.directory = directory
|
|
137
|
+
self.data = data
|
|
138
|
+
self.parent_fd = os.dup(parent_fd) if parent_fd is not None else None
|
|
139
|
+
self.directory_fd: int | None = None
|
|
140
|
+
try:
|
|
141
|
+
if self.parent_fd is not None:
|
|
142
|
+
self.directory_fd = os.open(
|
|
143
|
+
directory.name,
|
|
144
|
+
os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
|
|
145
|
+
dir_fd=self.parent_fd,
|
|
146
|
+
)
|
|
147
|
+
except BaseException:
|
|
148
|
+
if self.parent_fd is not None:
|
|
149
|
+
os.close(self.parent_fd)
|
|
150
|
+
self.parent_fd = None
|
|
151
|
+
raise
|
|
152
|
+
|
|
153
|
+
@classmethod
|
|
154
|
+
def begin(cls, parent: Path, operation: str, source_name: str, destination_name: str,
|
|
155
|
+
source_info: os.stat_result, *, parent_fd: int | None = None) -> "Transaction":
|
|
156
|
+
if operation not in _OPERATIONS or not _component(source_name) or not _component(destination_name):
|
|
157
|
+
raise ValueError("invalid transaction parameters")
|
|
158
|
+
if source_name == destination_name:
|
|
159
|
+
raise ValueError("source and destination must differ")
|
|
160
|
+
parent_info = os.fstat(parent_fd) if parent_fd is not None else parent.stat()
|
|
161
|
+
for _ in range(8):
|
|
162
|
+
transaction_id = secrets.token_hex(16)
|
|
163
|
+
directory = parent / (_PREFIX + transaction_id)
|
|
164
|
+
try:
|
|
165
|
+
if parent_fd is not None:
|
|
166
|
+
os.mkdir(directory.name, 0o700, dir_fd=parent_fd)
|
|
167
|
+
else:
|
|
168
|
+
os.mkdir(directory, 0o700 if os.name != "nt" else 0o777)
|
|
169
|
+
break
|
|
170
|
+
except FileExistsError:
|
|
171
|
+
continue
|
|
172
|
+
else:
|
|
173
|
+
raise FileExistsError("could not allocate unique transaction directory")
|
|
174
|
+
data = {
|
|
175
|
+
"format": 1,
|
|
176
|
+
"transaction_id": transaction_id,
|
|
177
|
+
"operation": operation,
|
|
178
|
+
"state": "prepared",
|
|
179
|
+
"parent_identity": _identity(parent_info),
|
|
180
|
+
"source_name": source_name,
|
|
181
|
+
"destination_name": destination_name,
|
|
182
|
+
"temporary_name": "result" if operation.startswith("file_") else None,
|
|
183
|
+
"source_identity": _identity(source_info),
|
|
184
|
+
"result_identity": None,
|
|
185
|
+
"created_ns": __import__("time").time_ns(),
|
|
186
|
+
}
|
|
187
|
+
transaction = cls(parent, directory, data, parent_fd=parent_fd)
|
|
188
|
+
try:
|
|
189
|
+
transaction._persist()
|
|
190
|
+
if parent_fd is not None:
|
|
191
|
+
os.fsync(parent_fd)
|
|
192
|
+
else:
|
|
193
|
+
_sync_directory(parent)
|
|
194
|
+
except Exception:
|
|
195
|
+
# Preserve any directory that may contain a partially durable journal.
|
|
196
|
+
transaction.close()
|
|
197
|
+
raise
|
|
198
|
+
return transaction
|
|
199
|
+
|
|
200
|
+
@property
|
|
201
|
+
def result_path(self) -> Path:
|
|
202
|
+
if self.directory_fd is not None:
|
|
203
|
+
raise RuntimeError("descriptor-anchored transactions do not expose pathname results")
|
|
204
|
+
return self.directory / "result"
|
|
205
|
+
|
|
206
|
+
@property
|
|
207
|
+
def retained_path(self) -> Path:
|
|
208
|
+
if self.directory_fd is not None:
|
|
209
|
+
raise RuntimeError("descriptor-anchored transactions do not expose pathname entries")
|
|
210
|
+
return self.directory / "source"
|
|
211
|
+
|
|
212
|
+
def open_result(self) -> int:
|
|
213
|
+
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
|
|
214
|
+
if self.directory_fd is not None:
|
|
215
|
+
return os.open("result", flags, 0o600, dir_fd=self.directory_fd)
|
|
216
|
+
return os.open(self.result_path, flags, 0o600)
|
|
217
|
+
|
|
218
|
+
def stat_result(self) -> os.stat_result:
|
|
219
|
+
if self.directory_fd is not None:
|
|
220
|
+
return os.stat("result", dir_fd=self.directory_fd, follow_symlinks=False)
|
|
221
|
+
return self.result_path.lstat()
|
|
222
|
+
|
|
223
|
+
def rename_result_to(self, parent_fd: int, destination_name: str) -> None:
|
|
224
|
+
if self.directory_fd is None:
|
|
225
|
+
raise RuntimeError("transaction is not descriptor-anchored")
|
|
226
|
+
from ._directory import _renameat2
|
|
227
|
+
_renameat2(self.directory_fd, "result", parent_fd, destination_name)
|
|
228
|
+
|
|
229
|
+
def unlink_retained(self) -> None:
|
|
230
|
+
if self.directory_fd is not None:
|
|
231
|
+
os.unlink("source", dir_fd=self.directory_fd)
|
|
232
|
+
else:
|
|
233
|
+
self.retained_path.unlink()
|
|
234
|
+
|
|
235
|
+
def close(self) -> None:
|
|
236
|
+
if self.directory_fd is not None:
|
|
237
|
+
os.close(self.directory_fd)
|
|
238
|
+
self.directory_fd = None
|
|
239
|
+
if self.parent_fd is not None:
|
|
240
|
+
os.close(self.parent_fd)
|
|
241
|
+
self.parent_fd = None
|
|
242
|
+
|
|
243
|
+
def set_result_ready(self, result_info: os.stat_result) -> None:
|
|
244
|
+
self.data["result_identity"] = _identity(result_info)
|
|
245
|
+
self.data["state"] = "result_ready"
|
|
246
|
+
self._persist()
|
|
247
|
+
|
|
248
|
+
def set_state(self, state: str) -> None:
|
|
249
|
+
if state not in _STATES:
|
|
250
|
+
raise ValueError("invalid transaction state")
|
|
251
|
+
self.data["state"] = state
|
|
252
|
+
self._persist()
|
|
253
|
+
|
|
254
|
+
def _persist(self) -> None:
|
|
255
|
+
raw = _encode(self.data)
|
|
256
|
+
temporary_name = ".journal-" + secrets.token_hex(8)
|
|
257
|
+
temporary = self.directory / temporary_name
|
|
258
|
+
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
|
|
259
|
+
if self.directory_fd is not None:
|
|
260
|
+
fd = os.open(temporary_name, flags, 0o600, dir_fd=self.directory_fd)
|
|
261
|
+
else:
|
|
262
|
+
fd = os.open(temporary, flags, 0o600)
|
|
263
|
+
try:
|
|
264
|
+
with os.fdopen(fd, "wb") as stream:
|
|
265
|
+
stream.write(raw)
|
|
266
|
+
stream.flush()
|
|
267
|
+
os.fsync(stream.fileno())
|
|
268
|
+
if self.directory_fd is not None:
|
|
269
|
+
os.replace(
|
|
270
|
+
temporary_name, "journal.json",
|
|
271
|
+
src_dir_fd=self.directory_fd, dst_dir_fd=self.directory_fd,
|
|
272
|
+
)
|
|
273
|
+
os.fsync(self.directory_fd)
|
|
274
|
+
else:
|
|
275
|
+
os.replace(temporary, self.directory / "journal.json")
|
|
276
|
+
_sync_directory(self.directory)
|
|
277
|
+
except Exception:
|
|
278
|
+
try:
|
|
279
|
+
if self.directory_fd is not None:
|
|
280
|
+
os.unlink(temporary_name, dir_fd=self.directory_fd)
|
|
281
|
+
else:
|
|
282
|
+
temporary.unlink(missing_ok=True)
|
|
283
|
+
except OSError:
|
|
284
|
+
pass
|
|
285
|
+
raise
|
|
286
|
+
|
|
287
|
+
def finish(self) -> None:
|
|
288
|
+
# Keep the completed record as durable evidence. Cleanup is intentionally
|
|
289
|
+
# deferred until a separately specified, identity-safe retention policy exists.
|
|
290
|
+
if self.data["state"] != "complete":
|
|
291
|
+
raise RuntimeError("transaction is not complete")
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
def _inspect_path_based(parent: str | os.PathLike[str]) -> tuple[RecoveryRecord, ...]:
|
|
295
|
+
"""Windows fallback; path-based inspection has weaker race guarantees."""
|
|
296
|
+
root = Path(os.path.abspath(os.fspath(parent)))
|
|
297
|
+
root_info = root.lstat()
|
|
298
|
+
if stat.S_ISLNK(root_info.st_mode) or not stat.S_ISDIR(root_info.st_mode):
|
|
299
|
+
raise NotADirectoryError("recovery inspection requires a real directory")
|
|
300
|
+
records: list[RecoveryRecord] = []
|
|
301
|
+
for entry in sorted(root.iterdir(), key=lambda item: item.name):
|
|
302
|
+
if not entry.name.startswith(_PREFIX):
|
|
303
|
+
continue
|
|
304
|
+
transaction_id = entry.name[len(_PREFIX):]
|
|
305
|
+
if not _ID.fullmatch(transaction_id):
|
|
306
|
+
records.append(RecoveryRecord(transaction_id, None, None, "corrupt", detail="invalid transaction directory name"))
|
|
307
|
+
continue
|
|
308
|
+
try:
|
|
309
|
+
entry_info = entry.lstat()
|
|
310
|
+
if not stat.S_ISDIR(entry_info.st_mode) or stat.S_ISLNK(entry_info.st_mode):
|
|
311
|
+
raise ValueError("transaction entry is not a real directory")
|
|
312
|
+
journal = entry / "journal.json"
|
|
313
|
+
journal_info = journal.lstat()
|
|
314
|
+
if not stat.S_ISREG(journal_info.st_mode) or stat.S_ISLNK(journal_info.st_mode) or journal_info.st_size > _MAX_RECORD:
|
|
315
|
+
raise ValueError("journal is not a bounded regular file")
|
|
316
|
+
fd = os.open(journal, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
|
|
317
|
+
opened_info = os.fstat(fd)
|
|
318
|
+
if not stat.S_ISREG(opened_info.st_mode) or _identity(opened_info) != _identity(journal_info):
|
|
319
|
+
os.close(fd)
|
|
320
|
+
raise ValueError("journal changed during inspection")
|
|
321
|
+
with os.fdopen(fd, "rb") as stream:
|
|
322
|
+
raw = stream.read(_MAX_RECORD + 1)
|
|
323
|
+
data = _decode(raw, transaction_id, root_info)
|
|
324
|
+
if data["parent_identity"] != _identity(root_info):
|
|
325
|
+
records.append(RecoveryRecord(transaction_id, data["operation"], data["state"], "ambiguous",
|
|
326
|
+
data["source_name"], data["destination_name"], data["temporary_name"], "parent directory identity mismatch"))
|
|
327
|
+
continue
|
|
328
|
+
source_kind, source_id = _lstat_identity(root / data["source_name"])
|
|
329
|
+
dest_kind, dest_id = _lstat_identity(root / data["destination_name"])
|
|
330
|
+
temp_kind, temp_id = ("missing", None)
|
|
331
|
+
if data["temporary_name"] is not None:
|
|
332
|
+
temp_kind, temp_id = _lstat_identity(entry / "result")
|
|
333
|
+
retained_kind, retained_id = ("missing", None)
|
|
334
|
+
if data["operation"].startswith("file_"):
|
|
335
|
+
retained_kind, retained_id = _lstat_identity(entry / "source")
|
|
336
|
+
expected_source, expected_result = data["source_identity"], data["result_identity"]
|
|
337
|
+
classification = "ambiguous"
|
|
338
|
+
if any(kind in {"symlink", "other"} for kind in (source_kind, dest_kind, temp_kind, retained_kind)):
|
|
339
|
+
classification = "ambiguous"
|
|
340
|
+
elif data["operation"].startswith("dir_"):
|
|
341
|
+
if source_kind == "directory" and source_id == expected_source and dest_kind == "missing":
|
|
342
|
+
classification = "prepared_no_output" if data["state"] == "prepared" else "ambiguous"
|
|
343
|
+
elif source_kind == "missing" and dest_kind == "directory" and dest_id == expected_source:
|
|
344
|
+
classification = "source_removed" if data["state"] in {"source_removed", "complete"} else "published_source_missing"
|
|
345
|
+
elif retained_kind != "missing":
|
|
346
|
+
if retained_kind == "regular" and retained_id == expected_source and source_kind == "missing" and dest_kind == "regular" and expected_result is not None and dest_id == expected_result:
|
|
347
|
+
classification = "source_retained"
|
|
348
|
+
elif source_kind == "regular" and source_id == expected_source and dest_kind == "missing" and temp_kind == "missing":
|
|
349
|
+
classification = "prepared_no_output" if data["state"] == "prepared" else "ambiguous"
|
|
350
|
+
elif source_kind == "regular" and source_id == expected_source and dest_kind == "missing" and temp_kind == "regular":
|
|
351
|
+
classification = "result_ready" if expected_result is not None and temp_id == expected_result else "result_incomplete_or_unverified"
|
|
352
|
+
elif dest_kind == "regular" and expected_result is not None and dest_id == expected_result and source_kind == "regular" and source_id == expected_source:
|
|
353
|
+
classification = "published_source_present"
|
|
354
|
+
elif dest_kind == "regular" and expected_result is not None and dest_id == expected_result and source_kind == "missing":
|
|
355
|
+
classification = "source_removed" if data["state"] in {"source_removed", "complete"} else "published_source_missing"
|
|
356
|
+
records.append(RecoveryRecord(transaction_id, data["operation"], data["state"], classification,
|
|
357
|
+
data["source_name"], data["destination_name"], data["temporary_name"]))
|
|
358
|
+
except Exception as exc:
|
|
359
|
+
records.append(RecoveryRecord(transaction_id, None, None, "corrupt", detail=str(exc)))
|
|
360
|
+
return tuple(records)
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _lstat_identity(path: Path):
|
|
364
|
+
try:
|
|
365
|
+
info = path.lstat()
|
|
366
|
+
except FileNotFoundError:
|
|
367
|
+
return "missing", None
|
|
368
|
+
if stat.S_ISLNK(info.st_mode):
|
|
369
|
+
return "symlink", None
|
|
370
|
+
return ("regular" if stat.S_ISREG(info.st_mode) else "directory" if stat.S_ISDIR(info.st_mode) else "other"), _identity(info)
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
def inspect(parent: str | os.PathLike[str]) -> tuple[RecoveryRecord, ...]:
|
|
374
|
+
"""Inspect journals without modifying entries; Linux uses descriptor-relative traversal."""
|
|
375
|
+
if not sys.platform.startswith("linux"):
|
|
376
|
+
return _inspect_path_based(parent)
|
|
377
|
+
root = Path(os.path.abspath(os.fspath(parent)))
|
|
378
|
+
flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
|
|
379
|
+
root_fd = os.open(root, flags)
|
|
380
|
+
try:
|
|
381
|
+
root_info = os.fstat(root_fd)
|
|
382
|
+
if not stat.S_ISDIR(root_info.st_mode):
|
|
383
|
+
raise NotADirectoryError("recovery inspection requires a real directory")
|
|
384
|
+
records: list[RecoveryRecord] = []
|
|
385
|
+
for entry_name in sorted(os.listdir(root_fd)):
|
|
386
|
+
if not entry_name.startswith(_PREFIX):
|
|
387
|
+
continue
|
|
388
|
+
transaction_id = entry_name[len(_PREFIX):]
|
|
389
|
+
if not _ID.fullmatch(transaction_id):
|
|
390
|
+
records.append(RecoveryRecord(transaction_id, None, None, "corrupt", detail="invalid transaction directory name"))
|
|
391
|
+
continue
|
|
392
|
+
entry_fd = None
|
|
393
|
+
journal_fd = None
|
|
394
|
+
try:
|
|
395
|
+
entry_fd = os.open(
|
|
396
|
+
entry_name,
|
|
397
|
+
os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
|
|
398
|
+
dir_fd=root_fd,
|
|
399
|
+
)
|
|
400
|
+
entry_info = os.fstat(entry_fd)
|
|
401
|
+
if not stat.S_ISDIR(entry_info.st_mode):
|
|
402
|
+
raise ValueError("transaction entry is not a real directory")
|
|
403
|
+
journal_info = os.stat("journal.json", dir_fd=entry_fd, follow_symlinks=False)
|
|
404
|
+
if not stat.S_ISREG(journal_info.st_mode) or journal_info.st_size > _MAX_RECORD:
|
|
405
|
+
raise ValueError("journal is not a bounded regular file")
|
|
406
|
+
journal_fd = os.open("journal.json", os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0), dir_fd=entry_fd)
|
|
407
|
+
opened_info = os.fstat(journal_fd)
|
|
408
|
+
if not stat.S_ISREG(opened_info.st_mode) or _identity(opened_info) != _identity(journal_info):
|
|
409
|
+
raise ValueError("journal changed during inspection")
|
|
410
|
+
with os.fdopen(journal_fd, "rb") as stream:
|
|
411
|
+
journal_fd = None
|
|
412
|
+
raw = stream.read(_MAX_RECORD + 1)
|
|
413
|
+
data = _decode(raw, transaction_id, root_info)
|
|
414
|
+
if data["parent_identity"] != _identity(root_info):
|
|
415
|
+
records.append(RecoveryRecord(
|
|
416
|
+
transaction_id, data["operation"], data["state"], "ambiguous",
|
|
417
|
+
data["source_name"], data["destination_name"], data["temporary_name"],
|
|
418
|
+
"parent directory identity mismatch",
|
|
419
|
+
))
|
|
420
|
+
continue
|
|
421
|
+
if data["parent_identity"]["inode"] == 0 or data["source_identity"]["inode"] == 0:
|
|
422
|
+
records.append(RecoveryRecord(
|
|
423
|
+
transaction_id, data["operation"], data["state"], "ambiguous",
|
|
424
|
+
data["source_name"], data["destination_name"], data["temporary_name"],
|
|
425
|
+
"filesystem identity is not verifiable on this platform",
|
|
426
|
+
))
|
|
427
|
+
continue
|
|
428
|
+
|
|
429
|
+
def identity_at(directory_fd: int, name: str):
|
|
430
|
+
try:
|
|
431
|
+
info = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
|
|
432
|
+
except FileNotFoundError:
|
|
433
|
+
return "missing", None
|
|
434
|
+
if stat.S_ISLNK(info.st_mode):
|
|
435
|
+
return "symlink", None
|
|
436
|
+
kind = "regular" if stat.S_ISREG(info.st_mode) else "directory" if stat.S_ISDIR(info.st_mode) else "other"
|
|
437
|
+
return kind, _identity(info)
|
|
438
|
+
|
|
439
|
+
source_kind, source_id = identity_at(root_fd, data["source_name"])
|
|
440
|
+
dest_kind, dest_id = identity_at(root_fd, data["destination_name"])
|
|
441
|
+
temp_kind, temp_id = ("missing", None)
|
|
442
|
+
if data["temporary_name"] is not None:
|
|
443
|
+
temp_kind, temp_id = identity_at(entry_fd, "result")
|
|
444
|
+
retained_kind, retained_id = ("missing", None)
|
|
445
|
+
if data["operation"].startswith("file_"):
|
|
446
|
+
retained_kind, retained_id = identity_at(entry_fd, "source")
|
|
447
|
+
expected_source = data["source_identity"]
|
|
448
|
+
expected_result = data["result_identity"]
|
|
449
|
+
classification = "ambiguous"
|
|
450
|
+
if (
|
|
451
|
+
source_kind in {"symlink", "other"}
|
|
452
|
+
or dest_kind in {"symlink", "other"}
|
|
453
|
+
or temp_kind in {"symlink", "other"}
|
|
454
|
+
or retained_kind in {"symlink", "other"}
|
|
455
|
+
):
|
|
456
|
+
classification = "ambiguous"
|
|
457
|
+
elif data["operation"].startswith("dir_"):
|
|
458
|
+
if source_kind == "directory" and source_id == expected_source and dest_kind == "missing":
|
|
459
|
+
classification = "prepared_no_output" if data["state"] == "prepared" else "ambiguous"
|
|
460
|
+
elif source_kind == "missing" and dest_kind == "directory" and dest_id == expected_source:
|
|
461
|
+
classification = "source_removed" if data["state"] in {"source_removed", "complete"} else "published_source_missing"
|
|
462
|
+
else:
|
|
463
|
+
if retained_kind != "missing":
|
|
464
|
+
if (
|
|
465
|
+
retained_kind == "regular" and retained_id == expected_source
|
|
466
|
+
and source_kind == "missing" and dest_kind == "regular"
|
|
467
|
+
and expected_result is not None and dest_id == expected_result
|
|
468
|
+
):
|
|
469
|
+
classification = "source_retained"
|
|
470
|
+
else:
|
|
471
|
+
classification = "ambiguous"
|
|
472
|
+
elif source_kind == "regular" and source_id == expected_source and dest_kind == "missing" and temp_kind == "missing":
|
|
473
|
+
classification = "prepared_no_output" if data["state"] == "prepared" else "ambiguous"
|
|
474
|
+
elif source_kind == "regular" and source_id == expected_source and dest_kind == "missing" and temp_kind == "regular":
|
|
475
|
+
classification = "result_ready" if expected_result is not None and temp_id == expected_result else "result_incomplete_or_unverified"
|
|
476
|
+
elif dest_kind == "regular" and expected_result is not None and dest_id == expected_result and source_kind == "regular" and source_id == expected_source:
|
|
477
|
+
classification = "published_source_present"
|
|
478
|
+
elif dest_kind == "regular" and expected_result is not None and dest_id == expected_result and source_kind == "missing":
|
|
479
|
+
classification = "source_removed" if data["state"] in {"source_removed", "complete"} else "published_source_missing"
|
|
480
|
+
records.append(RecoveryRecord(
|
|
481
|
+
transaction_id, data["operation"], data["state"], classification,
|
|
482
|
+
data["source_name"], data["destination_name"], data["temporary_name"],
|
|
483
|
+
))
|
|
484
|
+
except Exception as exc:
|
|
485
|
+
records.append(RecoveryRecord(transaction_id, None, None, "corrupt", detail=str(exc)))
|
|
486
|
+
finally:
|
|
487
|
+
if journal_fd is not None:
|
|
488
|
+
os.close(journal_fd)
|
|
489
|
+
if entry_fd is not None:
|
|
490
|
+
os.close(entry_fd)
|
|
491
|
+
return tuple(records)
|
|
492
|
+
finally:
|
|
493
|
+
os.close(root_fd)
|