phiward 0.2.0b1__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.
Files changed (53) hide show
  1. phiward/__init__.py +8 -0
  2. phiward/__main__.py +5 -0
  3. phiward/_toml.py +211 -0
  4. phiward/adapters/__init__.py +105 -0
  5. phiward/adapters/claude.py +429 -0
  6. phiward/broker.py +831 -0
  7. phiward/carryover.py +1613 -0
  8. phiward/claude_settings.py +1307 -0
  9. phiward/cli.py +110 -0
  10. phiward/config.py +936 -0
  11. phiward/confine.py +476 -0
  12. phiward/copying.py +533 -0
  13. phiward/core.py +105 -0
  14. phiward/data/agents-section.md +43 -0
  15. phiward/doctor.py +1132 -0
  16. phiward/fasthook.py +70 -0
  17. phiward/fsinfo.py +241 -0
  18. phiward/gateway.py +159 -0
  19. phiward/githooks.py +248 -0
  20. phiward/guards/__init__.py +0 -0
  21. phiward/guards/protected_paths.py +1138 -0
  22. phiward/hidden.py +281 -0
  23. phiward/init.py +155 -0
  24. phiward/install.py +828 -0
  25. phiward/inventory.py +173 -0
  26. phiward/mcp.py +186 -0
  27. phiward/mcp_config.py +1736 -0
  28. phiward/names.py +5 -0
  29. phiward/packs/dates.toml +17 -0
  30. phiward/packs/genomics.toml +51 -0
  31. phiward/packs/msk.toml +32 -0
  32. phiward/pathid.py +403 -0
  33. phiward/pathmatch.py +98 -0
  34. phiward/paths.py +942 -0
  35. phiward/pin.py +214 -0
  36. phiward/procinfo.py +73 -0
  37. phiward/remote.py +448 -0
  38. phiward/run.py +788 -0
  39. phiward/safeio.py +84 -0
  40. phiward/sanitize.py +691 -0
  41. phiward/selfcheck.py +1506 -0
  42. phiward/service.py +321 -0
  43. phiward/session_note.py +86 -0
  44. phiward/setup_cmd.py +886 -0
  45. phiward/shell.py +504 -0
  46. phiward/wholetool.py +1463 -0
  47. phiward-0.2.0b1.dist-info/METADATA +147 -0
  48. phiward-0.2.0b1.dist-info/RECORD +53 -0
  49. phiward-0.2.0b1.dist-info/WHEEL +5 -0
  50. phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
  51. phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
  52. phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
  53. phiward-0.2.0b1.dist-info/top_level.txt +1 -0
phiward/names.py ADDED
@@ -0,0 +1,5 @@
1
+ """The program's names. phiward was called agent-guards before v0.2.0b1: the old program name is
2
+ kept as an alias for the beta, so every check that looks for the program looks for both."""
3
+
4
+ PROGRAMS = ("phiward", "agent-guards")
5
+ MODULES = ("phiward", "agent_guards")
@@ -0,0 +1,17 @@
1
+ # Built-in sanitizer pack: dates and times (HIPAA treats dates tied to a person as identifiers).
2
+ # Off by default; turn it on with `[sanitize] packs = ["genomics", "dates"]`. Format: see
3
+ # packs/genomics.toml. Times are masked with their dates; a bare year is kept.
4
+ [pack]
5
+ name = "dates"
6
+
7
+ identifiers = [
8
+ # ISO 8601: 2024-03-05, 2024-03-05T14:22:01Z, 2024-03-05 14:22, 20240305T1422
9
+ '\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)? => <DATE>',
10
+ '\b\d{8}T\d{4,6}Z?\b => <DATE>',
11
+ # 03/05/2024, 3/5/24, 05.03.2024, 05-03-2024
12
+ '\b\d{1,2}[/.\-]\d{1,2}[/.\-](?:\d{4}|\d{2})\b => <DATE>',
13
+ # Mar 5 2024, 5 Mar 2024, March 5, 2024, and ls -l style "Mar 5 14:22" or "Mar 5 2024"
14
+ # (day first runs first, so "5 March 2024" is one date)
15
+ '(?i)\b\d{1,2}\s+(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?,?\s+\d{4} => <DATE>',
16
+ '(?i)\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?\s+\d{1,2}(?:,?\s+\d{4}|\s+\d{1,2}:\d{2})?(?!\d) => <DATE>',
17
+ ]
@@ -0,0 +1,51 @@
1
+ # Built-in sanitizer pack: generic genomics masks. Format of a pack file (also for packs you
2
+ # write yourself and name by path in `[sanitize] packs = ["path/to/pack.toml"]`):
3
+ #
4
+ # [pack]
5
+ # name = "..." optional, for humans
6
+ # paths = [ RULE, ... ] applied first, over all packs, before the identifier rules
7
+ # identifiers = [ RULE, ... ] applied in text mode AND table mode
8
+ # positions = [ RULE, ... ] text mode only (numbers and positions)
9
+ # keep_files = [ REGEX, ... ] whole file names that a <BAMFILE> rule leaves alone
10
+ #
11
+ # A RULE is 'REGEX => <PLACEHOLDER>': a Python regular expression, then " => ", then a
12
+ # placeholder in capitals between angle brackets. Write the regex as a TOML literal string
13
+ # ('...') so that backslashes stay as they are; for a quote character use \x27 or \x22.
14
+ # A rule that matches the empty string is refused. Rules run in file order. After all rules a
15
+ # second pass must change nothing, else the line is withheld.
16
+ [pack]
17
+ name = "genomics"
18
+
19
+ identifiers = [
20
+ # sequence and alignment file names (a path token ending in one), unless in keep_files;
21
+ # a match starts only where a token starts, so a long line stays linear
22
+ '(?i)(?<![^\s\x27\x22=,;()\[\]])[^\s\x27\x22=,;()\[\]]+\.(?:bam|cram|bai|crai|csi|sam|fastq|fq|bcf|vcf)(?:\.gz|\.bgz)?\b => <BAMFILE>',
23
+ # read names: Illumina and Casava colon forms (5 or more fields), with /1, #0, _UMI, +UMI tails;
24
+ # a match starts only where a word starts (leading `_ . -` are taken too), so a long word
25
+ # stays linear
26
+ '(?<![A-Za-z0-9_.\-])[_.\-]*[A-Za-z0-9](?:[A-Za-z0-9_\-]+(?:\.[A-Za-z0-9_\-]+)*)?(?::[A-Za-z0-9_\-]+(?:\.[A-Za-z0-9_\-]+)*){4,}(?:[/#+][A-Za-z0-9+\-]*)* => <READ>',
27
+ # PacBio movie names
28
+ '\bm\d{5}[A-Za-z]?_\d{6}_\d{6}/\d+(?:/\w+)? => <READ>',
29
+ ]
30
+
31
+ positions = [
32
+ # chr1:123, 12:123456, chr2:1,234,567-1,300,000
33
+ '\b(?:[Cc]hr(?:\d{1,2}|[XYM]|MT)|\d{1,2}|X|Y|MT)\s*:\s*\d[\d,]*(?:\s*-\s*\d[\d,]*)? => <LOCUS>',
34
+ # chrX 12345
35
+ '\b(?:[Cc]hr(?:\d{1,2}|[XYM]|MT)|X|Y|MT)[\t ]+\d{3,} => <LOCUS>',
36
+ # 1_1234_A_C and chr7-55249071-C-T style variant IDs
37
+ '\b(?:[Cc]hr)?(?:\d{1,2}|X|Y|MT)[_.\-]\d{3,}(?:[_\-][ACGTN]+)+ => <LOCUS>',
38
+ # VCF-like rows: a chromosome cell, a tab, a position cell
39
+ '(?:^|(?<=\t))\d{1,2}\t\d{3,} => <LOCUS>',
40
+ # comma-grouped numbers of a million or more, then bare runs of five or more digits
41
+ '(?<![\d,])\d{1,3}(?:,\d{3}){2,}(?![\d,]) => <NUM>',
42
+ '(?<!\d)(?<!\d[.,])\d{5,}(?!\d)(?![.,]\d) => <NUM>',
43
+ ]
44
+
45
+ # neutral work names: they carry no identity
46
+ keep_files = [
47
+ 'slice\.bam(?:\.bai)?',
48
+ 'rows(?:_b37)?\.vcf',
49
+ 'b\d\d\.(?:bam|cram)(?:\.bai|\.crai|\.csi)?',
50
+ 'b\d\d\.(?:bai|crai|csi)',
51
+ ]
phiward/packs/msk.toml ADDED
@@ -0,0 +1,32 @@
1
+ # EXAMPLE sanitizer pack: the identifier forms of one institution (MSK) and an example path
2
+ # layout. It is not a default; name it in the config to use it:
3
+ # [sanitize]
4
+ # packs = ["genomics", "msk"]
5
+ # Copy it and change the rules for another institution. The format is described at the top of
6
+ # genomics.toml.
7
+ #
8
+ # Two rules are examples of a project's folder layout, not facts about any institution:
9
+ # <PATIENTPATH> any path token holding inputs/patient
10
+ # <CLINICALPATH> any path token under /clinical/ (a made-up share of clinical data; change
11
+ # the prefix to your own)
12
+ # They run first (the `paths` list), so a clinical path is masked as a whole before a file-name
13
+ # rule sees it.
14
+ [pack]
15
+ name = "msk"
16
+
17
+ paths = [
18
+ '[^\s\x27\x22=,;()\[\]]*inputs/patient[^\s\x27\x22=,;()\[\]]* => <PATIENTPATH>',
19
+ '[^\s\x27\x22=,;()\[\]]*/clinical/[^\s\x27\x22=,;()\[\]]* => <CLINICALPATH>',
20
+ ]
21
+
22
+ identifiers = [
23
+ # sample and patient IDs: P-0000000-T01-IM6 and forms like it
24
+ '\bP-\d{4,}(?:-[A-Za-z]\d{1,3})?(?:[-_][A-Za-z0-9]+)* => <SAMPLEID>',
25
+ # CMO IDs: C-ABC123-L001-d, s_C_ABC123_P001_d
26
+ '\bC-\w{6}(?:[-_]\w+)* => <CMOID>',
27
+ '\bs_C_\w+ => <CMOID>',
28
+ # anonymized BAM stems: AB123456-T
29
+ '\b[A-Z]{2}\d{6}-[A-Z]\b => <BAMID>',
30
+ # donor names
31
+ '\bDonor[\w\-]+|\bDONOR[\w\-]+ => <DONOR>',
32
+ ]
phiward/pathid.py ADDED
@@ -0,0 +1,403 @@
1
+ """The canonical spelling and the identity of a path, from the file system itself.
2
+
3
+ A path can be written many ways that name the same file: through links, with `..`, in another
4
+ letter case or Unicode form (macOS), through the `/System/Volumes/Data` firmlink or as
5
+ `/.vol/<device>/<inode>` (macOS), through a bind mount (Linux). A check that computes the answer
6
+ from the written string misses some of them.
7
+
8
+ `walk(path)` asks the file system instead: it resolves the path part by part from folder
9
+ descriptors, as the kernel does, and returns the canonical spelling (macOS `F_GETPATH`, the form
10
+ Seatbelt matches; Linux `/proc/self/fd`) and the (device, inode) of every folder on the way.
11
+ `canon()` is its spelling; `fold()` is the key for deny comparisons (on macOS NFD and
12
+ case-folded; on Linux the path itself). A walk that blocks on a stale network mount blocks the
13
+ caller (a known limit: docs/threat-model.md).
14
+ """
15
+
16
+ import os
17
+ import stat
18
+ import sys
19
+ import unicodedata
20
+ from typing import List, NamedTuple, Optional, Tuple
21
+
22
+ _F_GETPATH = 50 # <sys/fcntl.h>
23
+ _O_EVTONLY = 0x8000 # macOS: open for event notification only (no read access needed)
24
+ MACOS = sys.platform == "darwin"
25
+ LINUX = sys.platform.startswith("linux")
26
+
27
+
28
+ def inside(path: str, folder: str, strict: bool = False) -> bool:
29
+ """Whether `path` is `folder` or below it, as text (both absolute, in the same spelling);
30
+ `strict`: below it only. The one lexical rule for "inside": an empty or relative `folder` is
31
+ a caller's mistake (as text, "" would hold every absolute path), so it raises ValueError and
32
+ each caller says what a missing folder means for it."""
33
+ if not folder or not folder.startswith("/"):
34
+ raise ValueError(f"not an absolute folder: {folder!r}")
35
+ if path == folder:
36
+ return not strict
37
+ return path.startswith(folder.rstrip("/") + "/") or folder == "/" and path.startswith("/")
38
+
39
+
40
+ def fold(path: str) -> str:
41
+ if MACOS:
42
+ return unicodedata.normalize("NFD", path).casefold()
43
+ return path
44
+
45
+
46
+ def _from_fd(fd: int) -> Optional[str]:
47
+ if MACOS:
48
+ import fcntl
49
+ try:
50
+ raw = fcntl.fcntl(fd, _F_GETPATH, b"\0" * 1024)
51
+ except OSError:
52
+ return None
53
+ return raw.split(b"\0", 1)[0].decode("utf-8", "surrogateescape") or None
54
+ if LINUX:
55
+ try:
56
+ return os.readlink(f"/proc/self/fd/{fd}")
57
+ except OSError:
58
+ return None
59
+ return None
60
+
61
+
62
+ def _dir_flags() -> int:
63
+ f = os.O_DIRECTORY | os.O_CLOEXEC | os.O_NOCTTY | os.O_NONBLOCK
64
+ if MACOS:
65
+ f |= _O_EVTONLY
66
+ elif LINUX:
67
+ f |= os.O_PATH # type: ignore[attr-defined]
68
+ return f
69
+
70
+
71
+ MAX_LINKS = 40
72
+
73
+
74
+ class Walk(NamedTuple):
75
+ canon: str
76
+ ids: List[Tuple[int, int]] # (dev, ino) of every folder on the way, and of the last part
77
+ complete: bool # False: some part could not be resolved (callers fail closed)
78
+
79
+
80
+ def _file_flags() -> int:
81
+ f = os.O_CLOEXEC | os.O_NOCTTY | os.O_NONBLOCK | os.O_NOFOLLOW
82
+ if MACOS:
83
+ f |= _O_EVTONLY
84
+ elif LINUX:
85
+ f |= os.O_PATH # type: ignore[attr-defined]
86
+ return f
87
+
88
+
89
+ def walk_full(path: str) -> Walk:
90
+ """Resolve an absolute path the way the kernel does, part by part:
91
+ each folder is opened from its parent's descriptor (`..` from the folder itself, links read
92
+ and followed in place), the last part is only looked up, never opened as a device. A part
93
+ that does not exist ends the walk normally: the rest is kept as text (with `.` and `..`
94
+ applied), and the walk is complete. Anything else that stops the walk (no permission, a
95
+ `/.vol` name that does not resolve, a magic link under `/proc`, too many links) makes it
96
+ incomplete: callers then treat the path as protected."""
97
+ if not (MACOS or LINUX):
98
+ return Walk(os.path.realpath(path), [], True)
99
+ flags = _dir_flags()
100
+ ids: List[Tuple[int, int]] = []
101
+ todo = [p for p in path.split("/") if p and p != "."]
102
+ fd = os.open("/", flags)
103
+ st = os.fstat(fd)
104
+ ids.append((st.st_dev, st.st_ino))
105
+ links = 0
106
+ tail: List[str] = []
107
+ last_name = ""
108
+ base_override = ""
109
+ complete = True
110
+ try:
111
+ while todo:
112
+ part = todo.pop(0)
113
+ if part == "..":
114
+ try:
115
+ nxt = os.open("..", flags, dir_fd=fd)
116
+ except OSError:
117
+ complete = False
118
+ break
119
+ os.close(fd)
120
+ fd = nxt
121
+ st = os.fstat(fd)
122
+ ids.append((st.st_dev, st.st_ino))
123
+ continue
124
+ try:
125
+ st = os.stat(part, dir_fd=fd, follow_symlinks=False)
126
+ except FileNotFoundError:
127
+ st = None
128
+ except OSError:
129
+ complete = False
130
+ break
131
+ if st is None:
132
+ # some folders resolve a name only by full path (macOS /.vol/<dev>/<inode>):
133
+ # try longer prefixes of the rest, as a folder, then as anything else
134
+ here = _from_fd(fd)
135
+ opened = -1
136
+ if here and (here == "/.vol" or here.startswith("/.vol/")):
137
+ for k in range(0, min(len(todo), 3) + 1):
138
+ if any(x == ".." for x in todo[:k]):
139
+ break
140
+ full = os.path.join(here, part, *todo[:k])
141
+ for fl in (flags, _file_flags()):
142
+ try:
143
+ opened = os.open(full, fl)
144
+ break
145
+ except OSError:
146
+ opened = -1
147
+ if opened >= 0:
148
+ del todo[:k]
149
+ break
150
+ if opened < 0:
151
+ complete = False # an inode name we cannot follow: fail closed
152
+ break
153
+ os.close(fd)
154
+ fd = opened
155
+ st = os.fstat(fd)
156
+ ids.append((st.st_dev, st.st_ino))
157
+ if not stat.S_ISDIR(st.st_mode):
158
+ base_override = _from_fd(fd) or ""
159
+ if not base_override:
160
+ complete = False
161
+ tail = todo
162
+ todo = []
163
+ break
164
+ continue
165
+ # the generic rule: a name the walk cannot find, but
166
+ # that the kernel resolves as part of the whole path (macOS /.nofollow,
167
+ # /.resolve/N, ...), is not a missing tail: fail closed
168
+ here = _from_fd(fd) or "/"
169
+ try:
170
+ os.lstat(os.path.join(here, part, *todo))
171
+ complete = False
172
+ break
173
+ except OSError:
174
+ pass
175
+ tail = [part] + todo
176
+ todo = []
177
+ break
178
+ if stat.S_ISLNK(st.st_mode):
179
+ links += 1
180
+ if links > MAX_LINKS:
181
+ complete = False # a loop: fail closed
182
+ break
183
+ target = os.readlink(part, dir_fd=fd)
184
+ if _on_procfs(fd):
185
+ kind = _proc_link_kind(_from_fd(fd) or "", part, target)
186
+ if kind == "magic":
187
+ # its text is not where it leads: let the kernel follow it, ask the
188
+ # kernel where it really is, and walk that; use the answer only if the
189
+ # identities agree, else fail closed
190
+ resolved = _follow_magic(fd, part, todo)
191
+ if resolved is None:
192
+ complete = False
193
+ break
194
+ os.close(fd)
195
+ fd = os.open("/", flags)
196
+ return resolved
197
+ if kind == "not-a-path": # pipe:, socket:, anon_inode:
198
+ last_name = part
199
+ tail = []
200
+ todo = []
201
+ break
202
+ more = [p for p in target.split("/") if p and p != "."]
203
+ if target.startswith("/"):
204
+ os.close(fd)
205
+ fd = os.open("/", flags)
206
+ todo = more + todo
207
+ continue
208
+ if stat.S_ISDIR(st.st_mode):
209
+ try:
210
+ nxt = os.open(part, flags | os.O_NOFOLLOW, dir_fd=fd)
211
+ except OSError:
212
+ complete = False
213
+ break
214
+ os.close(fd)
215
+ fd = nxt
216
+ st = os.fstat(fd)
217
+ ids.append((st.st_dev, st.st_ino))
218
+ continue
219
+ # a file, device, FIFO or socket: looked up only
220
+ ids.append((st.st_dev, st.st_ino))
221
+ last_name = part
222
+ tail = todo
223
+ todo = []
224
+ base = base_override or _from_fd(fd) or "/"
225
+ finally:
226
+ os.close(fd)
227
+ out: List[str] = []
228
+ for p in ([last_name] if last_name else []) + tail:
229
+ if p == "..":
230
+ if out:
231
+ out.pop()
232
+ elif p and p != ".":
233
+ out.append(p)
234
+ return Walk(os.path.join(base, *out) if out else base, ids, complete)
235
+
236
+
237
+ _PROC_SUPER_MAGIC = 0x9FA0
238
+
239
+
240
+ def _on_procfs(fd: int) -> bool:
241
+ """Linux: whether the folder `fd` is on procfs, asked of the file system (fstatfs), not
242
+ guessed from its path (procfs can be mounted at a second path)."""
243
+ if not LINUX:
244
+ return False
245
+ import ctypes
246
+ import ctypes.util
247
+
248
+ class _StatFs(ctypes.Structure):
249
+ _fields_ = [("f_type", ctypes.c_long), ("_rest", ctypes.c_byte * 120)]
250
+
251
+ libc = ctypes.CDLL(ctypes.util.find_library("c") or None, use_errno=True)
252
+ buf = _StatFs()
253
+ if libc.fstatfs(fd, ctypes.byref(buf)) != 0:
254
+ return True # unknown: treat as procfs (fail closed on its links)
255
+ return (buf.f_type & 0xFFFFFFFF) == _PROC_SUPER_MAGIC
256
+
257
+
258
+ def _follow_magic(fd: int, part: str, rest: List[str]) -> Optional["Walk"]:
259
+ """A magic link of another process, followed by the kernel and checked by identity; None
260
+ (fail closed) for this process's own links: /proc/self in the hook is the hook, not the
261
+ agent tool whose path this is."""
262
+ if not LINUX:
263
+ return None
264
+ here = _from_fd(fd)
265
+ if not here:
266
+ return None
267
+ mine = {str(os.getpid()), str(getattr(os, "gettid", os.getpid)())}
268
+ if any(c in mine for c in here.split("/")):
269
+ return None
270
+ full = os.path.join(here, part, *rest)
271
+ try:
272
+ tfd = os.open(full, os.O_PATH | os.O_CLOEXEC) # type: ignore[attr-defined]
273
+ except OSError:
274
+ return None
275
+ try:
276
+ real = os.readlink(f"/proc/self/fd/{tfd}")
277
+ st = os.fstat(tfd)
278
+ except OSError:
279
+ return None
280
+ finally:
281
+ os.close(tfd)
282
+ if not real.startswith("/") or real.startswith("/proc/"):
283
+ return None
284
+ try:
285
+ w = walk_full(real)
286
+ except OSError:
287
+ return None
288
+ if w.complete and w.ids and w.ids[-1] == (st.st_dev, st.st_ino):
289
+ return w
290
+ return None
291
+
292
+
293
+ _MAGIC_NAMES = ("root", "cwd", "exe")
294
+
295
+
296
+ def _proc_link_kind(folder: str, name: str, target: str) -> str:
297
+ """'plain' (follow it as text: /proc/self, /proc/thread-self, /proc/mounts), 'not-a-path'
298
+ (an fd link to a pipe, socket or anon inode), or 'magic' (root, cwd, exe, fd/*, map_files/*,
299
+ also under task/*: their text is not where they lead)."""
300
+ if re_not_a_path(target):
301
+ return "not-a-path"
302
+ last = os.path.basename(folder)
303
+ if name in _MAGIC_NAMES or last in ("fd", "map_files"):
304
+ return "magic" # also a tty-named one: checked by identity
305
+ return "plain"
306
+
307
+
308
+ def re_not_a_path(target: str) -> bool:
309
+ return any(target.startswith(p) for p in ("pipe:", "socket:", "anon_inode:", "net:", "mnt:"))
310
+
311
+
312
+ def walk(path: str) -> Tuple[str, List[Tuple[int, int]]]:
313
+ w = walk_full(path)
314
+ return w.canon, w.ids
315
+
316
+
317
+ def canon(path: str) -> str:
318
+ """The canonical spelling of an absolute path (see `walk`). When the walk cannot finish,
319
+ the spelling it reached is a prefix of the path, not the path: use `realpath` then."""
320
+ try:
321
+ w = walk_full(path)
322
+ except (OSError, ValueError):
323
+ return os.path.realpath(path)
324
+ return w.canon if w.complete else os.path.realpath(path)
325
+
326
+
327
+
328
+ def canon_new(path: str) -> str:
329
+ """The canonical spelling of a path that may not exist yet: its nearest existing folder in
330
+ the file system's own spelling (macOS firmlinks such as /System/Volumes/Data undone), with
331
+ the rest of the path after it."""
332
+ head, rest = path, ""
333
+ while not os.path.exists(head):
334
+ up = os.path.dirname(head)
335
+ if up == head:
336
+ return path
337
+ rest = os.path.join(os.path.basename(head), rest) if rest else os.path.basename(head)
338
+ head = up
339
+ c = canon(head)
340
+ return os.path.join(c, rest) if rest else c
341
+
342
+ def spellings(path: str) -> List[str]:
343
+ """The path as written (normalized), resolved, and canonical, without duplicates."""
344
+ out: List[str] = []
345
+ for v in (os.path.normpath(path), os.path.realpath(path), canon(path)):
346
+ if v not in out:
347
+ out.append(v)
348
+ return out
349
+
350
+
351
+ def home(env=None) -> str:
352
+ """The home folder: `HOME` of `env` (os.environ by default), else the account's. The one
353
+ lookup (selfcheck, a standalone child, keeps its own; the user config's base uses the real
354
+ home on purpose: config.user_config_path)."""
355
+ env = os.environ if env is None else env
356
+ return env.get("HOME") or os.path.expanduser("~")
357
+
358
+
359
+ def identity(path: str) -> Optional[Tuple[int, int]]:
360
+ try:
361
+ st = os.stat(path)
362
+ except OSError:
363
+ return None
364
+ return st.st_dev, st.st_ino
365
+
366
+
367
+ def case_sensitive(path: str) -> bool:
368
+ """Whether the volume that holds `path` tells letter case apart (macOS asks the volume;
369
+ Linux: yes, except in a casefold folder, see `casefold_folder`)."""
370
+ if MACOS:
371
+ here = path
372
+ while here and not os.path.exists(here):
373
+ here = os.path.dirname(here)
374
+ try:
375
+ return bool(os.pathconf(here or "/", 11)) # _PC_CASE_SENSITIVE
376
+ except (OSError, ValueError):
377
+ return False # unknown: fold (stricter for deny decisions)
378
+ return not casefold_folder(path)
379
+
380
+
381
+ def casefold_folder(path: str) -> bool:
382
+ """Linux: whether a folder on the way has the casefold attribute (ext4, f2fs)."""
383
+ if not LINUX:
384
+ return False
385
+ import fcntl
386
+ import struct
387
+ here = path
388
+ while here and here != "/":
389
+ try:
390
+ fd = os.open(here, os.O_RDONLY | os.O_DIRECTORY | os.O_NONBLOCK | os.O_CLOEXEC)
391
+ except OSError:
392
+ here = os.path.dirname(here)
393
+ continue
394
+ try:
395
+ buf = fcntl.ioctl(fd, 0x80086601, struct.pack("l", 0)) # FS_IOC_GETFLAGS
396
+ if struct.unpack("l", buf)[0] & 0x40000000: # FS_CASEFOLD_FL
397
+ return True
398
+ except OSError:
399
+ pass
400
+ finally:
401
+ os.close(fd)
402
+ here = os.path.dirname(here)
403
+ return False
phiward/pathmatch.py ADDED
@@ -0,0 +1,98 @@
1
+ """One meaning for a protected pattern, used by every part.
2
+
3
+ A pattern is an absolute path whose parts may hold `*`: any run of characters inside one path
4
+ part (never `/`), matching a name that starts with a dot too. Nothing else is a wildcard: `?` and
5
+ `[...]` are refused, and so is any character outside printable ASCII (Seatbelt matches
6
+ case-folded NFD bytes, Python matches code points, and the two disagree on classes, `?` and
7
+ non-ASCII names). With only `*` and ASCII literals, every back-end agrees by construction.
8
+ On macOS, letter case is folded (its volumes ignore case by default).
9
+
10
+ - `problem(pattern)`: why a pattern cannot be used, with a suggested rewrite, or None;
11
+ - `match_path(pattern, path)`: whether `path` is a match (not below one);
12
+ - `matches(pattern)`: the paths on disk that match, dot-names included, never through a link;
13
+ - `regex(pattern)`: an anchored-at-start regular expression for the same set, in the syntax that
14
+ both Python `re` and Seatbelt accept.
15
+ """
16
+
17
+ import os
18
+ import re
19
+ import sys
20
+ from fnmatch import fnmatchcase
21
+ from typing import List, Optional
22
+
23
+ FOLD_CASE = sys.platform == "darwin"
24
+ WILD = re.compile(r"[*?\[]")
25
+
26
+
27
+ def fold(p: str) -> str:
28
+ return p.casefold() if FOLD_CASE else p
29
+
30
+
31
+ def parts(path: str) -> List[str]:
32
+ return [c for c in path.split("/") if c]
33
+
34
+
35
+ def match_part(pattern_part: str, name: str) -> bool:
36
+ return fnmatchcase(fold(name), fold(pattern_part))
37
+
38
+
39
+ def match_path(pattern: str, path: str) -> bool:
40
+ pp, xp = parts(pattern), parts(path)
41
+ return len(pp) == len(xp) and all(match_part(a, b) for a, b in zip(pp, xp))
42
+
43
+
44
+ _LITERAL = re.compile(r"[ -~]") # printable ASCII, space included
45
+
46
+
47
+ def problem(pattern: str) -> Optional[str]:
48
+ """Why a pattern cannot be used (with a suggested rewrite), or None."""
49
+ if any(p in ("", ".", "..") for p in pattern.split("/")[1:]):
50
+ # the matcher and the kernel would read such a part differently
51
+ return "a pattern may not hold empty, `.` or `..` parts; write the folder as it is"
52
+ for ch in pattern:
53
+ if ch in "?[]":
54
+ return ("only `*` is a wildcard (`?` and `[...]` are not accepted, so that every part "
55
+ "of phiward reads the pattern the same way); use `*` there, or list the "
56
+ "folders as roots")
57
+ if ch == "\\":
58
+ return "a backslash is not accepted in a pattern"
59
+ if not _LITERAL.fullmatch(ch):
60
+ return ("a pattern may hold only printable ASCII; give a folder with other characters "
61
+ "in its name as a root")
62
+ return None
63
+
64
+
65
+ def _part_regex(part: str) -> str:
66
+ return "".join("[^/]*" if ch == "*" else ("\\" + ch if ch in ".^$+(){}|\\" else ch)
67
+ for ch in part)
68
+
69
+
70
+ def regex(pattern: str) -> str:
71
+ """`^` and the pattern, as a regex for whole paths (add your own end)."""
72
+ return "^/" + "/".join(_part_regex(p) for p in parts(pattern))
73
+
74
+
75
+ def matches(pattern: str) -> List[str]:
76
+ """Paths on disk that match, dot-names included. A folder on the way is entered only when it
77
+ is a real folder (not a link), so a match is never reached through a link the agent put
78
+ there. The literal leading part is taken as written."""
79
+ pp = parts(pattern)
80
+ out = ["/"]
81
+ for k, part in enumerate(pp):
82
+ nxt: List[str] = []
83
+ for base in out:
84
+ if not WILD.search(part):
85
+ cand = os.path.join(base, part)
86
+ if os.path.lexists(cand):
87
+ nxt.append(cand)
88
+ continue
89
+ try:
90
+ names = os.listdir(base)
91
+ except OSError:
92
+ continue
93
+ nxt += [os.path.join(base, n) for n in names if match_part(part, n)]
94
+ if k < len(pp) - 1: # enter only real folders, except along the literal prefix
95
+ literal = not any(WILD.search(p) for p in pp[:k + 1])
96
+ nxt = [p for p in nxt if os.path.isdir(p) and (literal or not os.path.islink(p))]
97
+ out = nxt
98
+ return sorted(out)