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/paths.py ADDED
@@ -0,0 +1,942 @@
1
+ """Which paths are protected, and how a written path resolves to real ones.
2
+
3
+ A path is in one of three relations to the protected set:
4
+ - INSIDE: it is a protected root, or below one, or it matches a pattern (or is below a match);
5
+ - ABOVE: a protected root or a pattern match sits below it (an ancestor), so a recursive tool
6
+ started there reaches protected data;
7
+ - None: neither.
8
+
9
+ Every check runs on two spellings of a path: the normalized one and the one with symlinks
10
+ resolved (`realpath`), so a link into a protected folder counts as protected.
11
+ """
12
+
13
+ import os
14
+ import re
15
+ import stat
16
+ import sys
17
+ import unicodedata
18
+ from typing import Dict, Iterable, List, NamedTuple, Optional, Sequence, Tuple
19
+
20
+ from phiward import pathid, pathmatch
21
+
22
+ INSIDE = "inside"
23
+ ABOVE = "above"
24
+
25
+ _GLOB_CHARS = re.compile(r"[*?\[]")
26
+ # macOS volumes ignore letter case by default: compare folded there (a case-sensitive volume
27
+ # only makes the check stricter).
28
+ FOLD_CASE = sys.platform == "darwin"
29
+
30
+
31
+ def _fold(p: str) -> str:
32
+ # NFD and case-folded on macOS (pathid.fold): its volumes treat both as equal
33
+ return pathid.fold(p)
34
+ _PATH_CHAR = r"[^\s'\"`<>|;&()]" # a character that can continue a path in free text
35
+
36
+
37
+ def _components(path: str) -> List[str]:
38
+ return [c for c in path.split("/") if c]
39
+
40
+
41
+ class ProtectedSet:
42
+ def __init__(self, roots: Sequence[str], patterns: Sequence[str]):
43
+ rs: List[str] = []
44
+ for r in roots:
45
+ # as written, resolved, and canonical (firmlinks, case, Unicode form: pathid)
46
+ for v in pathid.spellings(r):
47
+ if v not in rs:
48
+ rs.append(v)
49
+ self.roots = rs
50
+ ps: List[str] = []
51
+ for p in patterns:
52
+ for v in (os.path.normpath(p), _realpath_prefix(p), canon_prefix(p)):
53
+ if v not in ps:
54
+ ps.append(v)
55
+ self.patterns = ps
56
+ # the roots and patterns whose names are secret (set by the hook; None: all of these).
57
+ # A glob may be listed above a path that is only hidden (a credential), not above one
58
+ # of these
59
+ self.secret: Optional["ProtectedSet"] = None
60
+ # where the glob is decided (`glob_relation`): "confined", "shell" or "file"
61
+ self.mode = "shell"
62
+ self._roots_f = [_fold(r) for r in rs]
63
+ # for `_relation_one`: the folded roots, and every folder above one, as sets
64
+ self._roots_set = set(self._roots_f)
65
+ # a root has at most this many parts: a longer prefix of a path is never one, nor above
66
+ # one (a path of thousands of parts is checked in linear time)
67
+ self._root_depth = max((len(_components(r)) for r in self._roots_f), default=0)
68
+ self._above_set = {"/"} | {"/" + "/".join(_components(r)[:i]) for r in self._roots_f
69
+ for i in range(1, len(_components(r)))}
70
+ # the identity of every existing root: a path whose walk meets one
71
+ # of these is inside, whatever its spelling
72
+ self._root_ids = set()
73
+ for r in roots:
74
+ if not os.path.exists(r): # a dangling link or a missing root: no identity
75
+ continue # (it must not protect its parent)
76
+ try:
77
+ w = pathid.walk_full(r)
78
+ st = os.stat(r)
79
+ except OSError:
80
+ continue
81
+ if w.complete and w.ids and w.ids[-1] == (st.st_dev, st.st_ino):
82
+ self._root_ids.add(w.ids[-1])
83
+ self._patterns_f = [_fold(p) for p in ps]
84
+
85
+ def __bool__(self) -> bool:
86
+ return bool(self.roots or self.patterns)
87
+
88
+ # False for shell commands that run in the kernel profile: there the kernel decides about a
89
+ # path the walk cannot resolve, and failing closed would only over-block
90
+ fail_closed = True
91
+
92
+ def inside_by_identity(self, path: str) -> bool:
93
+ """Whether the walk of `path` meets a root's identity, or cannot finish (fail closed:
94
+ a path the walk cannot resolve all the way counts as inside)."""
95
+ if not self:
96
+ return False
97
+ try:
98
+ w = pathid.walk_full(path)
99
+ except (OSError, ValueError):
100
+ return self.fail_closed
101
+ if not w.complete:
102
+ return self.fail_closed
103
+ return any(i in self._root_ids for i in w.ids)
104
+
105
+ def relation(self, path: str) -> Optional[str]:
106
+ """INSIDE, ABOVE or None for one absolute path (checked as written and as resolved).
107
+
108
+ `realpath` runs on the path as written, so `link/..` resolves the way the kernel does;
109
+ `normpath` alone would collapse it lexically to another folder.
110
+ """
111
+ if self.inside_by_identity(path):
112
+ return INSIDE
113
+ found = None
114
+ for spelling in pathid.spellings(path): # also /.vol, firmlink and case spellings
115
+ rel = self._relation_one(_fold(spelling))
116
+ if rel == INSIDE:
117
+ return INSIDE
118
+ found = found or rel
119
+ return found
120
+
121
+ def _relation_one(self, path: str) -> Optional[str]:
122
+ """INSIDE, ABOVE or None for one folded path, as text."""
123
+ pc = _components(path)
124
+ prefix = ""
125
+ for c in pc[:self._root_depth]:
126
+ prefix += "/" + c
127
+ if prefix in self._roots_set:
128
+ return INSIDE
129
+ found = ABOVE if (self._roots_set and len(pc) <= self._root_depth and
130
+ ("/" + "/".join(pc)) in self._above_set) else None
131
+ for pat in self._patterns_f:
132
+ comps = _components(pat)
133
+ n = min(len(pc), len(comps))
134
+ if all(pathmatch.match_part(comps[i], pc[i]) for i in range(n)):
135
+ if len(pc) >= len(comps):
136
+ return INSIDE
137
+ found = ABOVE
138
+ return found
139
+
140
+ def passes_through(self, path: str) -> bool:
141
+ """Whether the path as written passes through a protected path on its way, before a
142
+ wildcard (`../phi/x/../../repo`): as text, so the answer does not depend on whether
143
+ the names on the way exist.
144
+
145
+ The names on the way are a stack, so every prefix of it was once the whole stack, and
146
+ was checked then. A stack deeper than every root and pattern is not checked again: its
147
+ prefixes of those depths were (a path of many parts is checked in linear time)."""
148
+ depth = max([self._root_depth] + [len(_components(p)) for p in self._patterns_f])
149
+ prefixes: List[str] = [] # prefixes[i]: the first i + 1 names, joined
150
+ for c in path.split("/"):
151
+ if not c or c == ".":
152
+ continue
153
+ if _GLOB_CHARS.search(c):
154
+ break
155
+ if c == "..":
156
+ if prefixes:
157
+ prefixes.pop()
158
+ continue
159
+ if len(prefixes) >= depth:
160
+ prefixes.append("") # too deep to be a root or a match, nor to start one
161
+ continue
162
+ prefixes.append((prefixes[-1] if prefixes else "") + "/" + c)
163
+ if self._relation_one(_fold(prefixes[-1])) == INSIDE:
164
+ return True
165
+ return False
166
+
167
+ def _text_finder(self) -> "_TextFinder":
168
+ finder = getattr(self, "_finder", None)
169
+ if finder is None:
170
+ finder = self._finder = _TextFinder(self.roots, self.patterns)
171
+ return finder
172
+
173
+ def text_search(self, text: str) -> Optional[Tuple[int, int]]:
174
+ """A protected path (inside, not above) written in `text`, as (start, end), or None:
175
+ the hook's form (`_TextFinder`)."""
176
+ return self._text_finder().search(text)
177
+
178
+ def text_spans(self, text: str) -> List[Tuple[int, int, bool]]:
179
+ """Every protected root or pattern match written in `text`, as (start, end, open), in
180
+ order of start: the sanitizer's form (`_TextFinder`)."""
181
+ return self._text_finder().spans(text)
182
+
183
+
184
+ # ---- protected paths written in free text ------------------------------------------------------
185
+
186
+ # The hook refuses a command that names a protected path anywhere in its text (code, heredocs,
187
+ # strings), and the sanitizer masks one anywhere in a line. A name in free text has no clear end:
188
+ # a wildcard may hold spaces, quotes and shell characters (`Zed (B)`, `O'Brien`, `R&D`). So:
189
+ # - roots (and patterns with no wildcard) are found as text, and every match counts;
190
+ # - a pattern is found by its literal start, then compared one part at a time. A part before the
191
+ # last ends at the next `/`, so it has one possible text. The last part can end at several
192
+ # places before the next `/`, tab or line end; each is tried with the pattern's own glob.
193
+ # - the hook takes a match at the first place it can end. A match whose wildcards hold `;`, `&`
194
+ # or `|` (`ls phi_a.txt; echo x_raw` is two commands, `R&D` is one folder) counts only when
195
+ # that path exists on disk; past DISK_CHECKS such checks in one text, it counts (fail closed).
196
+ # - the sanitizer takes the longest match: masking too much is the safe side. A last wildcard
197
+ # that meets a quote or a shell character makes the match "open": the name may go on there.
198
+ # Every step works inside one part of the text, so a long text is checked in linear time.
199
+
200
+ DISK_CHECKS = 256
201
+ _TEXT_STOP = re.compile(r"[/\t\n]") # where a part of a path written in free text ends
202
+ _NOT_NAME = re.compile(r"[^\w.\-]") # a character after which a name may have ended
203
+ WILDCARD_STOPS = "'\"`<>|;&()" # where a last wildcard may have ended (an "open" match)
204
+ _WILDCARD_STOP = re.compile("[" + re.escape(WILDCARD_STOPS) + "]")
205
+ _SEPARATORS = ";&|"
206
+
207
+
208
+ def _fold_full(s: str) -> str:
209
+ """A pattern's text folded where the volume ignores case, as `pathmatch` folds it."""
210
+ return s.casefold() if FOLD_CASE else s
211
+
212
+
213
+ def _fold_text(text: str) -> Tuple[str, Optional[List[int]]]:
214
+ """`text` folded as `pathmatch` folds names (`casefold`) where the volume ignores case, and,
215
+ when a letter folds to more than one character (`İ`, `ß`), the position in `text` of each
216
+ folded character (one more at the end); None when the positions are the same."""
217
+ if not FOLD_CASE:
218
+ return text, None
219
+ folded = text.casefold()
220
+ if len(folded) == len(text): # a fold never shortens a letter: each folds to one
221
+ return folded, None
222
+ pos: List[int] = []
223
+ for i, c in enumerate(text):
224
+ pos.extend([i] * len(c.casefold()))
225
+ pos.append(len(text))
226
+ return folded, pos
227
+
228
+
229
+ # other spellings of the same path, made plain in this order: a backslash-newline (bash and
230
+ # Python join the lines), a JSON-escaped slash (`\\/`), then `//`, `/./`, `/.//` (one `/` for the
231
+ # kernel)
232
+ _PLAIN_STEPS = ((re.compile(r"\\\n"), ""), (re.compile(r"\\/"), "/"),
233
+ (re.compile(r"/(?:\.?/)+"), "/"))
234
+
235
+
236
+ def plain_spelling(text: str) -> str:
237
+ """`text` with other spellings of the same path made plain (_PLAIN_STEPS)."""
238
+ for rx, repl in _PLAIN_STEPS:
239
+ text = rx.sub(repl, text)
240
+ return text
241
+
242
+
243
+ def plain_spelling_map(text: str) -> Tuple[str, List[int]]:
244
+ """plain_spelling(text), and for each of its characters the index in `text` it comes from
245
+ (a replacement's characters: where the text it replaces starts)."""
246
+ pos = list(range(len(text)))
247
+ for rx, repl in _PLAIN_STEPS:
248
+ out: List[str] = []
249
+ new: List[int] = []
250
+ last = 0
251
+ for m in rx.finditer(text):
252
+ out.append(text[last:m.start()])
253
+ new += pos[last:m.start()] + [pos[m.start()]] * len(repl)
254
+ out.append(repl)
255
+ last = m.end()
256
+ out.append(text[last:])
257
+ text, pos = "".join(out), new + pos[last:]
258
+ return text, pos
259
+
260
+
261
+ def _start_in(pos: Optional[List[int]], x: int) -> int:
262
+ return x if pos is None else pos[x]
263
+
264
+
265
+ def _end_in(pos: Optional[List[int]], x: int) -> int:
266
+ """The end in the text of the folded text up to `x` (the whole letter `x` falls in)."""
267
+ return x if pos is None or x == 0 else pos[x - 1] + 1
268
+
269
+
270
+ class _TextPattern(NamedTuple):
271
+ head: str # the folded literal start, up to the `/` before the first part with a `*`
272
+ parts: List[List[str]] # every later part, folded, split at its `*`s
273
+ seps: List[Dict[str, int]] # for each later part, how many `;`, `&`, `|` it holds itself
274
+
275
+
276
+ class _Disk:
277
+ """The disk checks of one text, at most DISK_CHECKS of them."""
278
+
279
+ def __init__(self) -> None:
280
+ self.left = DISK_CHECKS
281
+
282
+ def exists(self, path: str) -> bool:
283
+ if self.left <= 0 or "\x00" in path:
284
+ return True # fail closed
285
+ self.left -= 1
286
+ return os.path.lexists(path)
287
+
288
+
289
+ def _boundary(ft: str, e: int) -> bool:
290
+ """Whether a name may end at `e`: the text's end, a `/`, or a character no name goes on with."""
291
+ return e >= len(ft) or ft[e] == "/" or _NOT_NAME.match(ft, e) is not None
292
+
293
+
294
+ def _prefix_end(segs: List[str], ft: str, pos: int, lim: int) -> int:
295
+ """Where the part's text before its last `*` can end at the earliest, for a part written
296
+ from `pos` and ending by `lim`, or -1. The first piece must start at `pos`; each piece after
297
+ it is taken where it first occurs: no other choice ends earlier."""
298
+ q = pos + len(segs[0])
299
+ if q > lim or not ft.startswith(segs[0], pos):
300
+ return -1
301
+ for seg in segs[1:-1]:
302
+ j = ft.find(seg, q, lim)
303
+ if j < 0:
304
+ return -1
305
+ q = j + len(seg)
306
+ return q
307
+
308
+
309
+ def _matches_to(segs: List[str], ft: str, q: int, e: int) -> bool:
310
+ """Whether the part's text, with its earliest prefix end `q`, matches when it ends at `e`."""
311
+ if len(segs) == 1:
312
+ return e == q
313
+ last = segs[-1]
314
+ return e - len(last) >= q and ft.startswith(last, e - len(last))
315
+
316
+
317
+ def _end_places(segs: List[str], ft: str, q: int, lim: int) -> Iterable[int]:
318
+ """Every place, first to last, where the last part matches and a name may end."""
319
+ if len(segs) == 1:
320
+ if _boundary(ft, q):
321
+ yield q
322
+ return
323
+ last = segs[-1]
324
+ if not last: # the part ends with `*`: each place a name may end
325
+ e = q
326
+ while e <= lim:
327
+ m = _NOT_NAME.search(ft, e, lim)
328
+ e = m.start() if m else lim
329
+ yield e
330
+ e += 1
331
+ return
332
+ j = ft.find(last, q, lim)
333
+ while j >= 0:
334
+ if _boundary(ft, j + len(last)):
335
+ yield j + len(last)
336
+ j = ft.find(last, j + 1, lim)
337
+
338
+
339
+ def _longest(segs: List[str], ft: str, q: int, lim: int) -> Optional[Tuple[int, bool]]:
340
+ """The last place the last part matches and a name may end, and whether the match is open."""
341
+ if len(segs) == 1:
342
+ return (q, False) if _boundary(ft, q) else None
343
+ last = segs[-1]
344
+ if not last:
345
+ m = _WILDCARD_STOP.search(ft, q, lim)
346
+ return (m.start(), True) if m else (lim, False)
347
+ j = ft.rfind(last, q, lim)
348
+ while j >= 0:
349
+ if _boundary(ft, j + len(last)):
350
+ return j + len(last), False
351
+ j = ft.rfind(last, q, j + len(last) - 1)
352
+ return None
353
+
354
+
355
+ def _first_separator(text: str, pos: int, lim: int, own: Dict[str, int]) -> int:
356
+ """Where, from `pos`, the text holds more `;`, `&` or `|` than the part itself (so a
357
+ wildcard holds one), or `lim` when it does not before `lim`."""
358
+ first = lim
359
+ for c in _SEPARATORS:
360
+ j = pos - 1
361
+ for _ in range(own.get(c, 0) + 1):
362
+ j = text.find(c, j + 1, lim)
363
+ if j < 0:
364
+ break
365
+ if j >= 0:
366
+ first = min(first, j)
367
+ return first
368
+
369
+
370
+ class _TextFinder:
371
+ def __init__(self, roots: Sequence[str], patterns: Sequence[str]):
372
+ literals = list(roots)
373
+ self.patterns: List[_TextPattern] = []
374
+ for p in patterns:
375
+ comps = pathmatch.parts(p)
376
+ first = next((k for k, c in enumerate(comps) if "*" in c), None)
377
+ if first is None:
378
+ literals.append("/" + "/".join(comps))
379
+ continue
380
+ later = comps[first:]
381
+ self.patterns.append(_TextPattern(
382
+ _fold_full("/" + "".join(c + "/" for c in comps[:first])),
383
+ [_fold_full(c).split("*") for c in later],
384
+ [{s: c.count(s) for s in _SEPARATORS} for c in later]))
385
+ # every root also in the Unicode form the sanitizer puts lines in (NFKC), and NFC and
386
+ # NFD: a root written in another form is found all the same; longer first, so a root
387
+ # inside another one is matched whole
388
+ # (folded as names are, `ß` as `ss`, and found in the folded text)
389
+ forms: List[str] = []
390
+ for r in literals:
391
+ for f in (r, unicodedata.normalize("NFKC", r), unicodedata.normalize("NFC", r),
392
+ unicodedata.normalize("NFD", r)):
393
+ f = _fold_full(f)
394
+ if f not in forms:
395
+ forms.append(f)
396
+ forms.sort(key=len, reverse=True)
397
+ self.roots_rx = re.compile(
398
+ "|".join(re.escape(f) + r"(?=$|/|[^\w.\-])" for f in forms)) if forms else None
399
+
400
+ def search(self, text: str) -> Optional[Tuple[int, int]]:
401
+ found = self._search(text)
402
+ plain = plain_spelling(text)
403
+ if found is None and plain != text:
404
+ found = self._search(plain) # the hook needs no positions
405
+ return found
406
+
407
+ def _search(self, text: str) -> Optional[Tuple[int, int]]:
408
+ ft, at = _fold_text(text)
409
+ if self.roots_rx is not None:
410
+ m = self.roots_rx.search(ft)
411
+ if m is not None:
412
+ return _start_in(at, m.start()), _end_in(at, m.end())
413
+ if not self.patterns:
414
+ return None
415
+ disk = _Disk()
416
+ for pat in self.patterns:
417
+ a = ft.find(pat.head)
418
+ while a >= 0:
419
+ e = self._walk(pat, text, ft, at, a, disk)
420
+ if e is not None:
421
+ return _start_in(at, a), _end_in(at, e[0])
422
+ a = ft.find(pat.head, a + 1)
423
+ return None
424
+
425
+ def spans(self, text: str) -> List[Tuple[int, int, bool]]:
426
+ out: List[Tuple[int, int, bool]] = []
427
+ ft, at = _fold_text(text)
428
+ if self.roots_rx is not None:
429
+ m = self.roots_rx.search(ft)
430
+ while m is not None:
431
+ out.append((_start_in(at, m.start()), _end_in(at, m.end()), False))
432
+ m = self.roots_rx.search(ft, m.start() + 1)
433
+ if self.patterns:
434
+ for pat in self.patterns:
435
+ a = ft.find(pat.head)
436
+ while a >= 0:
437
+ e = self._walk(pat, text, ft, at, a, None)
438
+ if e is not None:
439
+ out.append((_start_in(at, a), _end_in(at, e[0]), e[1]))
440
+ a = ft.find(pat.head, a + 1)
441
+ out.sort()
442
+ return out
443
+
444
+ @staticmethod
445
+ def _walk(pat: _TextPattern, text: str, ft: str, at: Optional[List[int]], a: int,
446
+ disk: Optional[_Disk]) -> Optional[Tuple[int, bool]]:
447
+ """The end (in `ft`) of the pattern's match whose literal start is at `a` (in `ft`, the
448
+ folded text; `at` maps it back to `text`), and whether it is open: the first end that
449
+ counts for the hook (`disk` given), the longest for the sanitizer."""
450
+ pos = a + len(pat.head)
451
+ n = len(ft)
452
+ last = len(pat.parts) - 1
453
+ for k, segs in enumerate(pat.parts):
454
+ stop = _TEXT_STOP.search(ft, pos)
455
+ lim = stop.start() if stop else n
456
+ q = _prefix_end(segs, ft, pos, lim)
457
+ if q < 0:
458
+ return None
459
+ if k < last: # a part before the last ends at the next `/`
460
+ if lim == n or ft[lim] != "/" or not _matches_to(segs, ft, q, lim):
461
+ return None
462
+ if disk is not None and _first_separator(ft, pos, lim, pat.seps[k]) < lim \
463
+ and not disk.exists(text[_start_in(at, a):_end_in(at, lim)]):
464
+ return None
465
+ pos = lim + 1
466
+ continue
467
+ if disk is None:
468
+ return _longest(segs, ft, q, lim)
469
+ sep = _first_separator(ft, pos, lim, pat.seps[k])
470
+ for e in _end_places(segs, ft, q, lim):
471
+ if e <= sep or disk.exists(text[_start_in(at, a):_end_in(at, e)]):
472
+ return e, False
473
+ return None
474
+ return None
475
+
476
+
477
+ def canon_prefix(pattern: str) -> str:
478
+ """The pattern with its literal leading part in canonical spelling (pathid)."""
479
+ comps = pattern.split("/")
480
+ for i, c in enumerate(comps):
481
+ if _GLOB_CHARS.search(c):
482
+ head = "/".join(comps[:i]) or "/"
483
+ return os.path.join(pathid.canon(head), "/".join(comps[i:]))
484
+ return pathid.canon(pattern)
485
+
486
+
487
+ def _realpath_prefix(pattern: str) -> str:
488
+ """The pattern with the symlinks of its literal leading part resolved."""
489
+ comps = pattern.split("/")
490
+ for i, c in enumerate(comps):
491
+ if _GLOB_CHARS.search(c):
492
+ head = "/".join(comps[:i]) or "/"
493
+ rest = "/".join(comps[i:])
494
+ return os.path.join(os.path.realpath(head), rest)
495
+ return os.path.realpath(pattern)
496
+
497
+
498
+ def expand_braces(word: str, limit: int = 256) -> List[str]:
499
+ """Bash brace expansion of an unquoted word: `a{b,c}d`, `{1..3}`, `{a..c}`, nested.
500
+
501
+ Raises ValueError when the expansion would give more than `limit` words.
502
+ """
503
+ out = _braces(word)
504
+ if len(out) > limit:
505
+ raise ValueError("too many brace expansions")
506
+ return out
507
+
508
+
509
+ def _braces(word: str) -> List[str]:
510
+ depth = 0
511
+ start = -1
512
+ for i, ch in enumerate(word):
513
+ if ch == "\\":
514
+ continue
515
+ if ch == "{":
516
+ if depth == 0:
517
+ start = i
518
+ depth += 1
519
+ elif ch == "}" and depth:
520
+ depth -= 1
521
+ if depth == 0:
522
+ inner = word[start + 1:i]
523
+ options = _split_top(inner)
524
+ if options is None:
525
+ seq = _sequence(inner)
526
+ if seq is None:
527
+ # not a brace expression: keep "{...}" literally, expand the rest
528
+ return [word[:i + 1] + w for w in _braces(word[i + 1:])] if start == 0 \
529
+ else [word[:start] + "{" + w for w in _braces(word[start + 1:])]
530
+ options = seq
531
+ pre, post = word[:start], word[i + 1:]
532
+ result = []
533
+ for opt in options:
534
+ for o in _braces(opt):
535
+ for p in _braces(post):
536
+ result.append(pre + o + p)
537
+ return result
538
+ return [word]
539
+
540
+
541
+ def _split_top(inner: str) -> Optional[List[str]]:
542
+ parts, depth, cur = [], 0, ""
543
+ for ch in inner:
544
+ if ch == "{":
545
+ depth += 1
546
+ elif ch == "}":
547
+ depth -= 1
548
+ if ch == "," and depth == 0:
549
+ parts.append(cur)
550
+ cur = ""
551
+ else:
552
+ cur += ch
553
+ if not parts:
554
+ return None
555
+ parts.append(cur)
556
+ return parts
557
+
558
+
559
+ def _sequence(inner: str) -> Optional[List[str]]:
560
+ m = re.fullmatch(r"(-?\d+)\.\.(-?\d+)(?:\.\.(-?\d+))?", inner)
561
+ if m:
562
+ a, b = int(m.group(1)), int(m.group(2))
563
+ step = abs(int(m.group(3) or 1)) or 1
564
+ rng = range(a, b + 1, step) if a <= b else range(a, b - 1, -step)
565
+ if len(rng) > 256:
566
+ raise ValueError("too many brace expansions")
567
+ return [str(x) for x in rng]
568
+ m = re.fullmatch(r"([A-Za-z])\.\.([A-Za-z])", inner)
569
+ if m:
570
+ a, b = ord(m.group(1)), ord(m.group(2))
571
+ rng = range(a, b + 1) if a <= b else range(a, b - 1, -1)
572
+ return [chr(x) for x in rng]
573
+ return None
574
+
575
+
576
+ def candidates(word: str, bases: Iterable[str]) -> List[str]:
577
+ """The absolute paths a written path can mean: as written when absolute, else joined to
578
+ each base folder (a glob base stays a glob base). A glob is not expanded here."""
579
+ out: List[str] = []
580
+ seen = set()
581
+ for base in ([None] if word.startswith("/") else list(bases)):
582
+ full = word if base is None else os.path.join(base, word)
583
+ if isinstance(base, GlobBase):
584
+ full = GlobBase(full)
585
+ # a glob base and a plain one can spell the same text: keep both kinds
586
+ key = (type(full), str(full))
587
+ if key not in seen:
588
+ seen.add(key)
589
+ out.append(full)
590
+ return out
591
+
592
+
593
+ class GlobBase(str):
594
+ """A `cd` target that is a glob: a base folder that is a pattern, so a relative word joined
595
+ to it is judged as one longer glob."""
596
+
597
+
598
+ # the shell and the file tools' globs beyond `* ? [`: an extglob or zsh group (`@(a)`, `!(a)`,
599
+ # `(a|b)`), read as `*`
600
+ _GROUP = re.compile(r"[@!+*?]?\([^()]*\)")
601
+
602
+
603
+ _GROUP_DEPTH = 32 # groups nested deeper are refused, not read
604
+
605
+
606
+ def _ungroup(form: str) -> str:
607
+ """Every group as `*`, the innermost first, until none is left (`@(@(a)|b)`); a group
608
+ that holds `/` (zsh `(a/b|c)`) names more than one level, so it is refused."""
609
+ for _ in range(_GROUP_DEPTH):
610
+ if any("/" in m.group(0) for m in _GROUP.finditer(form)):
611
+ raise GlobUnchecked("A group here spans folders (`(a/b|c)`), which the guard "
612
+ "cannot check; write each path out.")
613
+ flat = _GROUP.sub("*", form)
614
+ if flat == form:
615
+ return flat
616
+ form = flat
617
+ raise GlobUnchecked("Groups here are nested deeper than the guard reads; write each path "
618
+ "out.")
619
+
620
+
621
+ def loose_variants(word: str) -> List[str]:
622
+ """The spellings a file tool's glob can mean, each a plain glob: braces expanded,
623
+ backslash escapes dropped, groups read as `*` (a superset of what the tool matches)."""
624
+ try:
625
+ forms = expand_braces(word)
626
+ except ValueError:
627
+ raise GlobUnchecked("A brace group here expands to more patterns than the guard "
628
+ "checks; write each path out.") from None
629
+ return [_ungroup(re.sub(r"\\(.)", r"\1", f)) for f in forms]
630
+
631
+
632
+ def word_relation(word: str, bases: Iterable[str], pset: "ProtectedSet",
633
+ glob: bool = False) -> Optional[str]:
634
+ """INSIDE, ABOVE or None for a written path (relative ones joined to each base): a path
635
+ whose written form passes through a protected path is INSIDE at once; a glob is decided by
636
+ `glob_relation`, never by expanding it."""
637
+ rel: Optional[str] = None
638
+ for full in candidates(word, bases):
639
+ if pset.passes_through(full):
640
+ return INSIDE
641
+ as_glob = (glob or isinstance(full, GlobBase)) and bool(_GLOB_CHARS.search(full))
642
+ rel = worst(rel, glob_relation(full, pset) if as_glob else pset.relation(full))
643
+ if rel == INSIDE:
644
+ break
645
+ return rel
646
+
647
+
648
+ class GlobUnchecked(Exception):
649
+ """A glob the guard cannot check (too many entries, `..` after a wildcard outside the
650
+ sandbox, a group across folders): the call is refused with this reason, never guessed or
651
+ cut short."""
652
+
653
+
654
+ GLOB_BUDGET = 200_000 # names the link scan may list for one glob, then GlobUnchecked
655
+ # a shell bracket expression, with POSIX classes inside: `[!P]`, `[^x]`, `[[:alpha:]]`, `[]a]`
656
+ _BRACKET = re.compile(r"\[[!^]?\]?(?:\[:[a-z]+:\]|[^\]])*\]")
657
+
658
+
659
+ def _loose(part: str) -> str:
660
+ """A pattern that matches at least what the shell matches, folded: a bracket expression
661
+ and `?` become `*` (fnmatch and the shell read classes differently, and one character in
662
+ one Unicode form can be two in another)."""
663
+ return _fold(_BRACKET.sub("*", part).replace("?", "*"))
664
+
665
+
666
+ def _ends(part: str) -> Tuple[str, str]:
667
+ """The literal text before the first wildcard and after the last one (loose and folded);
668
+ an unclosed `[` gives ("", ""), which meets anything."""
669
+ p = _loose(part)
670
+ first, last = p.find("*"), p.rfind("*")
671
+ if first < 0:
672
+ return "", ""
673
+ return p[:first], p[last + 1:]
674
+
675
+
676
+ def _match(pattern: str, name: str) -> bool:
677
+ """A glob part against an entry name, loose and folded on both sides."""
678
+ return pathmatch.match_part(_loose(pattern), _fold(name))
679
+
680
+
681
+ def _may_meet(a: str, b: str) -> bool:
682
+ """Whether two path parts (globs or names) can name the same entry. Errs toward yes."""
683
+ if a == "**" or b == "**":
684
+ return True
685
+ wild_a, wild_b = bool(_GLOB_CHARS.search(a)), bool(_GLOB_CHARS.search(b))
686
+ if not wild_a and not wild_b:
687
+ return _fold(a) == _fold(b)
688
+ if not wild_a:
689
+ return _match(b, a)
690
+ if not wild_b:
691
+ return _match(a, b)
692
+ (pa, sa), (pb, sb) = _ends(a), _ends(b)
693
+ return (pa.startswith(pb) or pb.startswith(pa)) and (sa.endswith(sb) or sb.endswith(sa))
694
+
695
+
696
+ def _names_into(rest: List[str], below: List[str], dots: bool) -> Optional[str]:
697
+ """Whether glob parts `rest` can name the path `below` (or something in it: INSIDE), only
698
+ a folder above it (ABOVE), or neither (None). `**` may stand for any depth. Without
699
+ `dots`, a part that does not start with `.` does not name a dot entry (the shell's rule)."""
700
+ if not below:
701
+ return INSIDE
702
+ if not rest:
703
+ return ABOVE
704
+ if rest[0] == "**":
705
+ return INSIDE
706
+ if not dots and below[0].startswith(".") and not rest[0].startswith("."):
707
+ return None
708
+ if _may_meet(rest[0], below[0]):
709
+ return _names_into(rest[1:], below[1:], dots)
710
+ return None
711
+
712
+
713
+ def _lexical(comps: List[str]) -> List[str]:
714
+ """Path parts with `.` dropped and `..` taking back the part before it, as text."""
715
+ out: List[str] = []
716
+ for c in comps:
717
+ if c == "..":
718
+ if out:
719
+ out.pop()
720
+ elif c != ".":
721
+ out.append(c)
722
+ return out
723
+
724
+
725
+ def glob_relation(pattern: str, pset: "ProtectedSet") -> Optional[str]:
726
+ """INSIDE, ABOVE or None for an absolute glob, in the place `pset.mode` names
727
+ (docs/threat-model.md, "A wildcard gets one verdict"):
728
+
729
+ - "confined", a shell in Claude Code's sandbox: from the pattern alone, against the roots
730
+ and patterns (`pset.secret`), with the shell's own dot rule; `..` is taken as text. The
731
+ disk is not listed and links are not followed: the kernel stops a read of a protected
732
+ path or credential.
733
+ - "shell" (no sandbox) and "file" (a file tool): the same against the roots, patterns and
734
+ the hidden list, `*` naming dot entries too; then `_link_scan` finds links the agent
735
+ made. `..` after a wildcard is refused (a link can take it anywhere).
736
+
737
+ The answer never depends on what a protected folder holds: no folder that is, or can lead
738
+ the glob into, a protected path is listed."""
739
+ if not pattern.startswith("/"):
740
+ raise ValueError("glob_relation takes an absolute glob")
741
+ confined = pset.mode == "confined"
742
+ comps = [c for c in pattern.split("/") if c and c != "."]
743
+ first = next((i for i, c in enumerate(comps) if _GLOB_CHARS.search(c)), len(comps))
744
+ if ".." in comps[first:]:
745
+ if not confined:
746
+ raise GlobUnchecked("A wildcard followed by `..` cannot be checked; write the path "
747
+ "without the `..`.")
748
+ # as text, over the whole path: a `..` may take back the parts before the wildcard
749
+ comps = _lexical(comps)
750
+ first = next((i for i, c in enumerate(comps) if _GLOB_CHARS.search(c)), len(comps))
751
+ if first >= len(comps) or not any(_GLOB_CHARS.search(c) for c in comps[first:]):
752
+ return pset.relation("/" + "/".join(comps))
753
+ rel_up = _as_dotdot(comps, first, pset) if pset.mode == "shell" else None
754
+ if rel_up == INSIDE:
755
+ return INSIDE
756
+ prefix, rest = "/" + "/".join(comps[:first]), comps[first:]
757
+ dots = not confined
758
+ folder = os.path.realpath(prefix)
759
+ rel = worst(rel_up, _static(folder, rest, pset, dots, pset.relation(folder)))
760
+ if rel == INSIDE or confined:
761
+ return rel
762
+ return worst(rel, _link_scan(folder, rest, pset, dots))
763
+
764
+
765
+ def _as_dotdot(comps: List[str], first: int, pset: "ProtectedSet") -> Optional[str]:
766
+ """Bash before 5.2 lets a dot glob (`.*`, `.?`) match `..`: the relation of the glob with
767
+ its first such part read as `..` (a `..` after an earlier wildcard is GlobUnchecked)."""
768
+ for i in range(first, len(comps)):
769
+ if comps[i].startswith(".") and _GLOB_CHARS.search(comps[i]) and _match(comps[i], ".."):
770
+ return glob_relation("/" + "/".join(comps[:i] + [".."] + comps[i + 1:]), pset)
771
+ return None
772
+
773
+
774
+ def _static(folder: str, rest: List[str], pset: "ProtectedSet", dots: bool,
775
+ rel: Optional[str]) -> Optional[str]:
776
+ """From the resolved folder `folder` (its relation `rel`), can the glob parts `rest` name
777
+ a protected path (INSIDE) or only a folder above one (ABOVE)? From the patterns alone. In
778
+ the sandbox only the roots and patterns count (`pset.secret`); elsewhere the hidden list
779
+ too."""
780
+ if rel == INSIDE:
781
+ return INSIDE
782
+ if rel != ABOVE:
783
+ return None
784
+ targets = pset.secret if (pset.mode == "confined" and pset.secret is not None) else pset
785
+ found: Optional[str] = None
786
+ for spelling in pathid.spellings(folder):
787
+ fc = _components(_fold(spelling))
788
+ for target in targets._roots_f + targets._patterns_f:
789
+ tc = _components(target)
790
+ if len(tc) < len(fc) or not all(_may_meet(t, f) for t, f in zip(tc, fc)):
791
+ continue
792
+ got = _names_into(rest, tc[len(fc):], dots)
793
+ if got == INSIDE:
794
+ return INSIDE
795
+ found = found or got
796
+ return found
797
+
798
+
799
+ class _Entry(NamedTuple):
800
+ """A folder entry as the link scan needs it: its path, whether it is a link or a folder,
801
+ and its identity (device, inode)."""
802
+ path: str
803
+ link: bool
804
+ folder: bool
805
+ ident: Tuple[int, int]
806
+
807
+
808
+ _Listing = Optional[Tuple[int, List["os.DirEntry[str]"]]] # (the folder's device, entries)
809
+
810
+
811
+ def _entries(folder: str, part: str, dots: bool,
812
+ listings: Dict[str, _Listing]) -> List[_Entry]:
813
+ """The entries of `folder` that the glob part `part` names. A literal part is looked up
814
+ by name (the file system's own case and Unicode rules; the folder need not be listable);
815
+ a wildcard part lists the folder, once per scan (`listings`); a folder that cannot be
816
+ listed names nothing, as in the shell."""
817
+ out: List[_Entry] = []
818
+ if part != "**" and not _GLOB_CHARS.search(part):
819
+ path = os.path.join(folder, part)
820
+ try:
821
+ st = os.lstat(path)
822
+ except OSError:
823
+ return out
824
+ out.append(_Entry(path, stat.S_ISLNK(st.st_mode), stat.S_ISDIR(st.st_mode),
825
+ (st.st_dev, st.st_ino)))
826
+ return out
827
+ if folder not in listings:
828
+ try:
829
+ dev = os.stat(folder).st_dev
830
+ with os.scandir(folder) as it:
831
+ listings[folder] = (dev, list(it))
832
+ except OSError:
833
+ listings[folder] = None
834
+ got = listings[folder]
835
+ if got is None:
836
+ return out
837
+ dev, listing = got
838
+ for e in listing:
839
+ if not dots and e.name.startswith(".") and not part.startswith("."):
840
+ continue
841
+ if part != "**" and not _match(part, e.name):
842
+ continue
843
+ try:
844
+ link, sub = e.is_symlink(), e.is_dir(follow_symlinks=False)
845
+ # a folder may be a mount (another device): stat it; a file's device is the
846
+ # folder's (a hard link stays on one device)
847
+ if sub:
848
+ st = e.stat(follow_symlinks=False)
849
+ ident = (st.st_dev, st.st_ino)
850
+ else:
851
+ ident = (dev, e.inode())
852
+ except OSError:
853
+ continue # gone since the listing: names nothing now
854
+ out.append(_Entry(e.path, link, sub, ident))
855
+ return out
856
+
857
+
858
+ def _link_scan(top: str, rest: List[str], pset: "ProtectedSet", dots: bool) -> Optional[str]:
859
+ """Outside the sandbox: walk where the glob can go, as the shell would, and check every
860
+ entry a glob part names: a link's target (`_target_relation`, then the rest of the glob
861
+ from there; a link to a folder is followed, once per real folder) and the identity of
862
+ folders and files (a root mounted or linked a second time). Each folder is listed once;
863
+ past GLOB_BUDGET names listed and entries looked at, GlobUnchecked."""
864
+ todo = [(top, rest)]
865
+ seen = {(top, len(rest))}
866
+ listings: Dict[str, _Listing] = {}
867
+ count = 0
868
+ found: Optional[str] = None
869
+ ids: Dict[str, bool] = {} # folder -> it or a folder above it is a root (identity)
870
+
871
+ while todo:
872
+ folder, parts = todo.pop()
873
+ if not parts:
874
+ continue
875
+ part, after = parts[0], parts[1:]
876
+ if part == "**":
877
+ todo.append((folder, after)) # `**` names no folder too
878
+ new = folder not in listings
879
+ entries = _entries(folder, part, dots, listings)
880
+ # the names a folder lists, the first time it is listed; on every later pass, the
881
+ # entries that pass looks at (a glob of many `**` parts passes a folder many times)
882
+ got = listings.get(folder)
883
+ count += len(got[1]) if new and got else len(entries) + 1
884
+ if count > GLOB_BUDGET:
885
+ raise GlobUnchecked("A wildcard here names more entries than the guard checks, so "
886
+ "it is refused. Name fewer files, or a folder deeper down.")
887
+ nxt = parts if part == "**" else after # `**` goes on below
888
+ for e in entries:
889
+ if e.ident in pset._root_ids:
890
+ return INSIDE # a root under another name (a mount, a hard link)
891
+ if e.link:
892
+ real = os.path.realpath(e.path)
893
+ rel = _target_relation(real, pset, ids)
894
+ if rel != INSIDE and nxt and os.path.isdir(real):
895
+ rel = _static(real, nxt, pset, dots, rel)
896
+ if rel != INSIDE and (real, len(nxt)) not in seen:
897
+ seen.add((real, len(nxt)))
898
+ todo.append((real, nxt))
899
+ if rel == INSIDE:
900
+ return INSIDE
901
+ found = found or rel
902
+ elif e.folder and nxt and (e.path, len(nxt)) not in seen:
903
+ seen.add((e.path, len(nxt)))
904
+ todo.append((e.path, nxt))
905
+ return found
906
+
907
+
908
+ def _target_relation(real: str, pset: "ProtectedSet", ids: Dict[str, bool]) -> Optional[str]:
909
+ """The relation of a resolved link target, quickly: by its text (folded, against every
910
+ spelling of the roots and patterns), then by the identity of it and each folder above it
911
+ (cached for one scan). The text check covers case, Unicode form and firmlinks; the
912
+ identity check covers a root reached by another path (a bind mount)."""
913
+ rel = pset._relation_one(_fold(real))
914
+ if rel == INSIDE:
915
+ return INSIDE
916
+ if real.startswith("/.vol/"): # macOS: a path by volume and inode id
917
+ return pset.relation(real)
918
+ path = real
919
+ chain: List[str] = []
920
+ while True:
921
+ if path in ids:
922
+ hit = ids[path]
923
+ break
924
+ try:
925
+ st = os.stat(path)
926
+ hit = (st.st_dev, st.st_ino) in pset._root_ids
927
+ except OSError:
928
+ hit = False
929
+ chain.append(path)
930
+ if hit or path == "/":
931
+ break
932
+ path = os.path.dirname(path)
933
+ for c in chain:
934
+ ids[c] = ids.get(c, False) or hit
935
+ return INSIDE if hit else rel
936
+
937
+
938
+ def worst(rel_a: Optional[str], rel_b: Optional[str]) -> Optional[str]:
939
+ order = {None: 0, ABOVE: 1, INSIDE: 2}
940
+ return rel_a if order[rel_a] >= order[rel_b] else rel_b
941
+
942
+