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/config.py ADDED
@@ -0,0 +1,936 @@
1
+ """Layered configuration: the user's file, then the repository's, combined tighten-only.
2
+
3
+ - User config (never committed): `$PHIWARD_CONFIG`, else
4
+ `$XDG_CONFIG_HOME/phiward/config.toml`, else `~/.config/phiward/config.toml`.
5
+ - Repo config (committed): the first `.phiward.toml` found from the working folder upward.
6
+
7
+ One source of authority: the agent can write a repo file, and it
8
+ chooses the working folder of a gateway request. So a repo file may only add protection: it can
9
+ add protected roots and patterns (never writable by the gateway), built-in packs and protected
10
+ branches, make `unresolved` stricter, and lower `inventory_limit`. Everything that widens or
11
+ changes the gateway (copy remotes, sanitize rules, names files, pack files, the grants
12
+ `[broker] write_to` and `net`) comes from the user's file only. A repo file that sets such a key
13
+ is not an error; the key is ignored, and `ignored` lists it (doctor shows it).
14
+
15
+ Grants: nothing asks the operator at run time. `[broker] write_to`
16
+ lists the only folders a `--write-to` may name; each must be a real folder (an entry reached
17
+ through a link is skipped, so whoever can change the link cannot choose the place);
18
+ `[broker] net = true` lets `--net` through. A `write_to` folder that is `/`, the home folder or
19
+ above it, a dot-folder in it, above or inside a protected path, or holds or is inside an
20
+ phiward folder is a problem; one that does not exist yet is skipped (doctor counts it).
21
+
22
+ No config, no effect. A file that is present but cannot be read, does not parse, or has an unknown
23
+ key or a bad value makes `problem` non-empty; the guards then refuse what they guard (fail closed).
24
+ """
25
+
26
+ import os
27
+ import re
28
+ import sys
29
+ from dataclasses import dataclass, field
30
+ from typing import Any, Dict, List, Mapping, Optional, Tuple
31
+
32
+ from phiward import _toml, pathid
33
+
34
+ REPO_FILE = ".phiward.toml"
35
+ # the names before the rename (v0.2.0b1): the program is kept as an alias for the beta; the old
36
+ # config files are refused, never read and never ignored without a word (a repo config may add
37
+ # protected roots, so ignoring it would drop protection)
38
+ from phiward.names import MODULES, PROGRAMS # noqa: E402,F401
39
+ LEGACY_REPO_FILE = ".agent-guards.toml"
40
+ LEGACY_STATE = ".agent-guards"
41
+ UNRESOLVED = ("allow", "ask", "deny") # weakest first
42
+
43
+ # section -> key -> kind ("list" of strings, or "choice" from UNRESOLVED)
44
+ SCHEMA: Dict[str, Dict[str, str]] = {
45
+ "protected_paths": {"roots": "list", "patterns": "list", "unresolved": "choice",
46
+ "snapshot_names": "list"},
47
+ "sanitize": {"packs": "list", "names_from": "list", "patterns": "list",
48
+ "inventory_limit": "int", "table": "bool"},
49
+ "copy": {"remotes": "list", "ssh_config": "str", "push_limit_gib": "int"},
50
+ "git": {"protected_branches": "list"},
51
+ "broker": {"write_to": "list", "net": "bool", "max_output_lines": "int", "commands": "list"},
52
+ "launch": {"pass_env": "list"},
53
+ # commands on HPC through the broker; every key is the operator's own (USER_ONLY)
54
+ "remote": {"hosts": "list", "commands": "list", "roots": "list",
55
+ "use_shared_connection": "bool"},
56
+ # the network of shell commands in Claude Code sessions (Mode A): Claude Code's own
57
+ # sandbox.network.strictAllowlist and allowedDomains in the user settings (USER_ONLY)
58
+ "network": {"limit": "bool", "allowed_domains": "list"},
59
+ # a shell that no kernel confines: best_effort keeps the hook's text check instead of
60
+ # refusing every such call (USER_ONLY). `strict` and `commands` (strict mode, removed) still
61
+ # load, and do nothing: unconfined calls are refused by default now
62
+ "shell": {"best_effort": "bool", "strict": "bool", "commands": "list"},
63
+ }
64
+ # built-in program lists for `[broker] commands` (`"@genomics"`): programs that read data and
65
+ # print results, chosen so that none runs code it is given. Each still prints what it reads:
66
+ # print summaries.
67
+ COMMAND_PRESETS = {
68
+ # not in them: `sort` (--compress-program runs a program), `bcftools` (+plugin loads a
69
+ # library from a path), interpreters, shells, `awk`, `find`, `xargs`, `make`, `git`, pagers
70
+ # also not `fastqc` (its wrapper can be told which program to start) or `multiqc` (it reads
71
+ # settings from the working folder)
72
+ "genomics": ("samtools", "bedtools", "tabix", "bgzip", "mosdepth", "seqkit", "wc", "uniq", "cut", "du", "md5sum", "sha256sum", "shasum", "ls",
73
+ "stat", "file", "head", "tail", "zcat", "gzip", "gunzip"),
74
+ "counts": ("wc", "du", "ls", "stat", "uniq", "cut", "md5sum", "sha256sum", "shasum"),
75
+ }
76
+
77
+
78
+ # programs that run other code they are given (a script, an alias in a project's .git/config,
79
+ # -exec, a compress program): in `[broker] commands` they let agent code run again
80
+ LAUNCHERS = frozenset({
81
+ "sh", "bash", "zsh", "dash", "ksh", "fish", "csh", "tcsh", "python", "python3", "perl", "ruby",
82
+ "node", "Rscript", "R", "julia", "java", "awk", "gawk", "mawk", "sed", "gsed", "git", "find",
83
+ "xargs", "parallel", "make", "env", "nice", "nohup", "timeout", "time", "sort", "tar", "rsync",
84
+ "less", "more", "vim", "vi", "emacs", "ssh", "snakemake", "nextflow", "cromwell", "conda",
85
+ "mamba", "pip", "uv", "npx", "docker", "apptainer", "singularity", "srun", "sbatch",
86
+ # data tools that can be told to start a program or load a library (not in the presets)
87
+ "fastqc", "multiqc", "bcftools",
88
+ # more interpreters and multi-call programs
89
+ "pypy", "php", "lua", "tclsh", "wish", "osascript", "busybox", "toybox", "pwsh", "deno",
90
+ "bun"})
91
+
92
+
93
+ def runs_other_code(name: str) -> bool:
94
+ """Whether a program, by its file name, runs other code it is given: LAUNCHERS, also with a
95
+ version after the name (`python3.9`, `perl5.34`, `node18`, `pypy3`)."""
96
+ import re as _re
97
+ base = os.path.basename(name)
98
+ return base in LAUNCHERS or _re.sub(r"[0-9][0-9.]*$", "", base) in LAUNCHERS
99
+
100
+
101
+ # keys of iteration 4 that are gone: a file that still sets one is a problem that says why
102
+ REMOVED = {("broker", "confirm"), ("broker", "prompt")}
103
+ # keys a repo file may not set; they are ignored there
104
+ USER_ONLY = {("copy", "remotes"), ("copy", "ssh_config"), ("sanitize", "patterns"),
105
+ ("copy", "push_limit_gib"), ("remote", "use_shared_connection"),
106
+ ("remote", "hosts"), ("remote", "commands"), ("remote", "roots"),
107
+ ("sanitize", "names_from"), ("sanitize", "table"),
108
+ ("broker", "write_to"), ("broker", "net"), ("launch", "pass_env"),
109
+ ("network", "limit"), ("network", "allowed_domains"), ("shell", "best_effort"),
110
+ ("shell", "commands")}
111
+ # an allowed_domains entry: a host name, `*.` and a host name, an IPv4 or bracketed IPv6
112
+ # address; an optional :port. Never `*` alone (that allows every host)
113
+ _LABEL = r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
114
+ DOMAIN = re.compile(r"(?:(?:\*\.)?" + _LABEL + r"(?:\." + _LABEL + r")*|\[[0-9A-Fa-f:.]+\])"
115
+ r"(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}"
116
+ r"|655[0-2][0-9]|6553[0-5]))?")
117
+
118
+
119
+ _SUFFIX_SECOND = {"co", "com", "net", "org", "gov", "edu", "ac", "or", "ne", "go", "gob", "nic",
120
+ "me", "ltd", "plc", "sch", "nhs", "police"}
121
+ # names under which anyone can get a host of their own: `*.` over one of them, or over a name
122
+ # below one (`*.s3.amazonaws.com`), is every user's site (a short list, not the whole public
123
+ # suffix list)
124
+ SHARED_HOSTING = {"github.io", "gitlab.io", "githubusercontent.com", "amazonaws.com",
125
+ "cloudfront.net", "azurewebsites.net", "windows.net", "googleapis.com", "on.aws",
126
+ "amazonaws.com.cn", "trycloudflare.com",
127
+ "googleusercontent.com", "r2.dev", "appspot.com", "web.app", "firebaseapp.com",
128
+ "herokuapp.com", "netlify.app", "vercel.app", "pages.dev", "workers.dev",
129
+ "ngrok.io", "ngrok-free.app", "ngrok.app", "onrender.com", "fly.dev",
130
+ "blogspot.com", "glitch.me", "repl.co", "uk.com", "eu.org"}
131
+
132
+
133
+ def domain_problem(d: str) -> str:
134
+ """Why `d` cannot be an allowed host, or "". A wildcard needs a name of its own below a
135
+ public suffix: `*.example.org`, never `*.org` or `*.co.uk`."""
136
+ if not DOMAIN.fullmatch(d):
137
+ return ("is not a host name (for example github.com, *.example.org or github.com:443; "
138
+ "no http://, no path, not *)")
139
+ if d.startswith("*."):
140
+ labels = d[2:].split(":")[0].lower().split(".")
141
+ name = ".".join(labels)
142
+ if len(labels) < 2 or any(name == s or name.endswith("." + s) for s in SHARED_HOSTING) or (
143
+ len(labels) == 2 and len(labels[1]) == 2 and labels[0] in _SUFFIX_SECOND):
144
+ return ("is a wildcard over a whole public or shared hosting suffix; name a "
145
+ "domain below it")
146
+ return ""
147
+
148
+
149
+ @dataclass
150
+ class Config:
151
+ roots: List[str] = field(default_factory=list) # absolute, normalized, ~ expanded
152
+ patterns: List[str] = field(default_factory=list) # absolute glob patterns
153
+ # The roots and patterns of the user's own file. Only these are writable by the gateway: the
154
+ # agent can edit a repo file, so a repo root must not become a place the gateway writes to.
155
+ user_roots: List[str] = field(default_factory=list)
156
+ user_patterns: List[str] = field(default_factory=list)
157
+ write_to: List[str] = field(default_factory=list) # resolved folders a grant may name
158
+ write_to_missing: int = 0 # write_to entries that name no folder yet
159
+ write_to_linked: int = 0 # write_to entries reached through a link (skipped)
160
+ write_to_claude: int = 0 # write_to entries that hold a .claude folder (skipped)
161
+ net: bool = False
162
+ launch_pass_env: List[str] = field(default_factory=list) # more variables for `launch`
163
+ max_output_lines: int = 2000 # gateway output lines shown; a repo file may only lower it
164
+ # the programs gateway commands may run ([broker] commands): one list per config file that
165
+ # sets one; a program must be in every list. Empty: no list, any program
166
+ command_lists: List[List[str]] = field(default_factory=list)
167
+ # the user config's own list (None when it sets none): what a listed program runs as comes
168
+ # from it only, never from a repo list, which the agent can write
169
+ user_commands: Optional[List[str]] = None
170
+ ignored: List[str] = field(default_factory=list) # "section.key" a repo file may not set
171
+ unresolved: str = "deny"
172
+ snapshot_names: List[str] = field(default_factory=list) # site snapshot folder names
173
+ packs: List[str] = field(default_factory=list)
174
+ names_from: List[str] = field(default_factory=list)
175
+ sanitize_patterns: List[str] = field(default_factory=list) # "REGEX => <PLACEHOLDER>"
176
+ # table mode lets bare numbers through (an MRN would pass): the operator's choice only
177
+ sanitize_table: bool = False
178
+ remotes: List[str] = field(default_factory=list)
179
+ remote_hosts: List[str] = field(default_factory=list) # hosts `run --remote` may use
180
+ remote_commands: List[str] = field(default_factory=list) # programs it may run there
181
+ remote_roots: List[str] = field(default_factory=list) # protected paths there, masked
182
+ ssh_config: str = "" # the ssh config file a remote copy uses (else none: -F /dev/null)
183
+ # HPC requests join the operator's shared SSH connection (no key, no ticket,
184
+ # no network but its socket); false: ssh logs in itself and must read the credentials
185
+ use_shared_connection: bool = True
186
+ # [network]: limit the network of shell commands in Claude Code sessions to allowed_domains
187
+ network_limit: bool = False
188
+ # [shell] best_effort (USER_ONLY): a shell call that no kernel confines gets the text check
189
+ # instead of a refusal
190
+ shell_best_effort: bool = False
191
+ allowed_domains: List[str] = field(default_factory=list)
192
+ push_limit_gib: int = 5 # a larger push is the operator's to do
193
+ protected_branches: List[str] = field(default_factory=list)
194
+ inventory_limit: int = 200_000 # most entries the sanitizer lists under the roots
195
+ # Protected without being configured: the cache folder (it holds the list of protected
196
+ # names) and the .git folder of a work tree that holds a root (it holds copies).
197
+ derived_roots: List[str] = field(default_factory=list)
198
+ found_derived: List[str] = field(default_factory=list) # derived roots found now, before pins
199
+ cache_dir: str = ""
200
+ files: List[str] = field(default_factory=list) # the files that were read
201
+ problem: str = "" # non-empty: fail closed
202
+ # the full text of a repo-config problem; `problem` itself quotes nothing from a repo file
203
+ # (the agent sees it, and the file may be a link into a root)
204
+ problem_detail: str = ""
205
+
206
+ @property
207
+ def has_protected_paths(self) -> bool:
208
+ return bool(self.roots or self.patterns)
209
+
210
+ @property
211
+ def all_roots(self) -> List[str]:
212
+ """The configured roots and the derived ones (empty when nothing is configured)."""
213
+ if not self.has_protected_paths:
214
+ return []
215
+ return self.roots + [r for r in self.derived_roots if r not in self.roots]
216
+
217
+ @property
218
+ def active(self) -> bool:
219
+ return bool(self.problem) or self.has_protected_paths
220
+
221
+
222
+ def xdg_config_home(home: str, env: Optional[Mapping[str, str]] = None) -> str:
223
+ """XDG_CONFIG_HOME, or `HOME/.config`: as the XDG spec says, a relative value is ignored."""
224
+ env = os.environ if env is None else env
225
+ v = env.get("XDG_CONFIG_HOME") or ""
226
+ return v if v.startswith("/") else os.path.join(home, ".config")
227
+
228
+
229
+ def user_config_path(env: Optional[Dict[str, str]] = None) -> str:
230
+ env = os.environ if env is None else env
231
+ named = env.get("PHIWARD_CONFIG", "")
232
+ if named:
233
+ if named == "~" or named.startswith("~/"):
234
+ # a `~` the shell left as it is (`env PHIWARD_CONFIG=~/...`)
235
+ named = os.path.join(pathid.home(env), named[2:])
236
+ return named
237
+ # this process's home (os.environ), not `env`'s, on purpose: the user config is the one the
238
+ # operator's process reads, whatever HOME an env built for a launched tool holds
239
+ base = xdg_config_home(os.path.expanduser("~"), env)
240
+ return os.path.join(base, "phiward", "config.toml")
241
+
242
+
243
+ def launch_settings_path(env: Optional[Dict[str, str]] = None) -> str:
244
+ """The file for `claude --settings`, which `install claude --user --write` writes: with it,
245
+ Claude Code's sandbox is admin-required, so a repository's settings cannot loosen it."""
246
+ env = os.environ if env is None else env
247
+ base = xdg_config_home(pathid.home(env), env)
248
+ return os.path.join(base, "phiward", "claude-settings.json")
249
+
250
+
251
+ def legacy_user_config_path(env: Optional[Dict[str, str]] = None) -> str:
252
+ env = os.environ if env is None else env
253
+ base = xdg_config_home(os.path.expanduser("~"), env) # as user_config_path
254
+ return os.path.join(base, "agent-guards", "config.toml")
255
+
256
+
257
+ def cache_dir(env: Optional[Dict[str, str]] = None) -> str:
258
+ env = os.environ if env is None else env
259
+ base = env.get("XDG_CACHE_HOME") or os.path.join(
260
+ pathid.home(env), ".cache")
261
+ return os.path.join(base, "phiward")
262
+
263
+
264
+ def spool_dir(env: Optional[Dict[str, str]] = None) -> str:
265
+ """The folder where agent-side clients leave requests for the broker."""
266
+ env = os.environ if env is None else env
267
+ named = env.get("PHIWARD_SPOOL", "")
268
+ if named:
269
+ return os.path.abspath(named)
270
+ return default_spool(pathid.home(env))
271
+
272
+
273
+ def default_spool(home: str) -> str:
274
+ """The spool when `$PHIWARD_SPOOL` is not set: outside `~/.phiward`, which the sandbox denies
275
+ in full (`sandbox_denied`); the spool is the one folder the agent must write."""
276
+ return os.path.join(home, ".phiward-spool")
277
+
278
+
279
+ def sandbox_denied(env: Optional[Dict[str, str]] = None) -> List[str]:
280
+ """Folders Claude Code's sandbox denies in full (not guard files: `phiward launch`'s own
281
+ profile writes in them): `~/.phiward`, phiward's own state (the launch records, wrap's
282
+ backups, the broker's status). Denied as a whole, nothing in a session can write, rename or
283
+ replace them, wherever the session was opened (`denyWrite` holds inside writable folders,
284
+ `--add-dir` and `allowWrite` ones too)."""
285
+ env = os.environ if env is None else env
286
+ return [os.path.join(pathid.home(env), ".phiward")]
287
+
288
+
289
+ def status_path(env: Optional[Dict[str, str]] = None) -> str:
290
+ """The broker's status file: next to the default spool, never inside a spool (the agent can
291
+ write a spool)."""
292
+ env = os.environ if env is None else env
293
+ return os.path.join(pathid.home(env), ".phiward", "broker.json")
294
+
295
+
296
+ def command_paths(cfg: "Config") -> List[str]:
297
+ """The files and folders that `[broker] commands` names by path: the operator's own
298
+ scripts. They are guard places: the agent may not write them, or it could change the code
299
+ that the gateway is allowed to run."""
300
+ out: List[str] = []
301
+ for lst in cfg.command_lists:
302
+ for e in lst:
303
+ if "/" in e and not e.startswith("@"):
304
+ p = os.path.realpath(os.path.expanduser(e))
305
+ if p not in out and p != "/":
306
+ out.append(p)
307
+ return out
308
+
309
+
310
+ def listed_in_home(cfg: "Config") -> List[str]:
311
+ """The programs `[broker] commands` allows that the operator owns (conda, ~/.local/bin,
312
+ Homebrew): protected from agent writes, like the operator's own scripts."""
313
+ if not cfg.command_lists:
314
+ return []
315
+ from phiward import broker
316
+ out = []
317
+ for p in broker.listed_programs(cfg, broker.program_path()):
318
+ try:
319
+ if os.stat(p).st_uid == os.getuid():
320
+ out.append(p)
321
+ except OSError:
322
+ continue
323
+ return out
324
+
325
+
326
+ def shell_prefix_path(env: Optional[Dict[str, str]] = None) -> str:
327
+ """Where an older phiward (`install claude --user --shell-prefix`, removed) wrote the
328
+ launcher that Claude Code's CLAUDE_CODE_SHELL_PREFIX named: kept guarded while it exists,
329
+ and a reinstall removes the setting that names it."""
330
+ env = os.environ if env is None else env
331
+ return os.path.join(pathid.home(env), ".phiward", "bin",
332
+ "shell-prefix")
333
+
334
+
335
+ def make_state_dirs(home: str) -> None:
336
+ """phiward's own folders that the sandbox must protect from the first session on (bubblewrap
337
+ covers only paths that exist): `~/.phiward/launched` and `~/.phiward/backups`, private."""
338
+ base = os.path.join(home, ".phiward")
339
+ for d in (base, os.path.join(base, "launched"), os.path.join(base, "backups")):
340
+ try:
341
+ os.mkdir(d, 0o700)
342
+ except FileExistsError:
343
+ pass
344
+ if d != base and os.path.isdir(d) and not os.path.islink(d):
345
+ os.chmod(d, 0o700)
346
+
347
+
348
+ def guard_files(env: Optional[Dict[str, str]] = None) -> List[str]:
349
+ """Files and folders that the agent must not change, or the guard turns itself off: the user
350
+ config (its folder too, when it is the default place), the phiward code and the
351
+ broker's status file."""
352
+ env = os.environ if env is None else env
353
+ out = []
354
+ user = user_config_path(env)
355
+ out.append(user)
356
+ if os.path.realpath(user) != os.path.normpath(user):
357
+ out.append(os.path.realpath(user)) # a linked config: its target is the config too
358
+ if not env.get("PHIWARD_CONFIG"):
359
+ out.append(os.path.dirname(user))
360
+ out.append(os.path.dirname(os.path.abspath(__file__)))
361
+ out.append(status_path(env))
362
+ # what runs phiward: its interpreter's prefix (the venv or tool folder), the launcher,
363
+ # and the user site folder, which Python reads at start
364
+ import sys
365
+ import shutil
366
+ launchers = [shutil.which(n, path=env.get("PATH")) or "" for n in PROGRAMS]
367
+ launcher = launchers[0]
368
+ for p in (sys.prefix, os.path.dirname(os.path.realpath(sys.argv[0] or "")) if
369
+ os.path.basename(sys.argv[0] or "") in PROGRAMS else "",
370
+ _user_site(env), os.path.realpath(launcher) if launcher else ""):
371
+ if p and os.path.normpath(p) != "/" and os.path.realpath(p) not in out:
372
+ out.append(os.path.realpath(p))
373
+ # the launcher as the hook and the operator call it: a link on PATH (uv tool, pipx) is
374
+ # guarded itself, so it cannot be pointed at other code
375
+ for la in launchers:
376
+ if la and os.path.abspath(la) not in out:
377
+ out.append(os.path.abspath(la))
378
+ if la and os.path.realpath(la) not in out:
379
+ out.append(os.path.realpath(la))
380
+ # the launchers phiward's install record lists: the file a wrapped MCP server's entry names
381
+ # (mcp_config.installed_launcher), wherever PATH leads
382
+ from phiward import selfcheck
383
+ try:
384
+ recorded = selfcheck.launcher_scripts() or ()
385
+ except Exception: # noqa: BLE001 - the record is read again where it is used
386
+ recorded = ()
387
+ for la in sorted(recorded):
388
+ if la not in out:
389
+ out.append(la)
390
+ from phiward import service
391
+ # the interpreter's own standard library: on uv, pyenv or Homebrew Pythons it is the user's,
392
+ # and the launcher imports from it before any check
393
+ base = os.path.realpath(sys.base_prefix)
394
+ if base != "/" and base not in out and base != os.path.realpath(sys.prefix):
395
+ out.append(base)
396
+ sf = service.service_file(pathid.home(env))
397
+ out.append(sf)
398
+ if sf.endswith(".service"):
399
+ out.append(sf + ".d") # systemd drop-ins can override ExecStart
400
+ ssh = _user_ssh_config(env)
401
+ if ssh:
402
+ out.append(ssh)
403
+ prefix = shell_prefix_path(env) # the shell prefix's launcher, once written
404
+ if os.path.lexists(prefix):
405
+ out.append(prefix)
406
+ # the folder of the `claude --settings` file, at both places it can be (the hook may see
407
+ # another XDG_CONFIG_HOME than install did): the agent must not loosen the file, nor put a
408
+ # file where its folder goes
409
+ home = pathid.home(env)
410
+ for base in (xdg_config_home(home, env), os.path.join(home, ".config")):
411
+ if base:
412
+ folder = os.path.join(base, "phiward")
413
+ for f in (folder, os.path.realpath(folder)): # a linked folder: both names
414
+ if f not in out:
415
+ out.append(f)
416
+ # the records of the running `phiward launch` processes (mcp_config.launched_dir): the hook
417
+ # trusts a wrapped MCP server by them
418
+ out.append(os.path.join(home, ".phiward", "launched"))
419
+ # the backups `phiward mcp wrap` keeps (mcp_config.backups_root): shown as the operator's
420
+ # original config, so only phiward writes them
421
+ out.append(os.path.join(home, ".phiward", "backups"))
422
+ # the pinned derived roots (phiward pin): the agent must not unpin them
423
+ out.append(os.path.join(os.path.dirname(user), "pinned.toml"))
424
+ return out
425
+
426
+
427
+ def _user_site(env: Dict[str, str]) -> str:
428
+ """The user site-packages folder for this Python and this environment's HOME (Python's own
429
+ value is fixed when it starts, so it can differ between two processes)."""
430
+ import site
431
+ import sys
432
+ if not site.ENABLE_USER_SITE:
433
+ return ""
434
+ home = pathid.home(env)
435
+ ver = f"{sys.version_info[0]}.{sys.version_info[1]}"
436
+ framework = getattr(sys, "_framework", "")
437
+ base = env.get("PYTHONUSERBASE") or (
438
+ os.path.join(home, "Library", framework, ver) if sys.platform == "darwin" and framework
439
+ else os.path.join(home, ".local"))
440
+ if sys.platform == "darwin" and framework:
441
+ return os.path.join(base, "lib", "python", "site-packages")
442
+ return os.path.join(base, "lib", f"python{ver}", "site-packages")
443
+
444
+
445
+ def _user_ssh_config(env: Dict[str, str]) -> str:
446
+ """`[copy] ssh_config` of the user file, read without the rest of the loader."""
447
+ path = user_config_path(env)
448
+ try:
449
+ raw, _ = _toml.load_file(path)
450
+ v = raw.get("copy", {}).get("ssh_config", "")
451
+ except Exception: # noqa: BLE001 - a bad file is reported by load()
452
+ return ""
453
+ if not isinstance(v, str) or not v:
454
+ return ""
455
+ home = pathid.home(env)
456
+ p = os.path.normpath(_expand_root(v, home))
457
+ return p if p.startswith("/") else ""
458
+
459
+
460
+ def git_dirs(dot_git: str) -> List[str]:
461
+ """The folders that hold the copies of a work tree's files: its `.git` folder, or for a `.git`
462
+ file (a linked worktree or a submodule) the file, the folder it names, and the main
463
+ repository's `.git`. The `.git` file is a derived root, so the agent cannot
464
+ change where it points."""
465
+ if not os.path.isfile(dot_git):
466
+ return [dot_git]
467
+ out = [dot_git]
468
+ from phiward import safeio
469
+ try:
470
+ text = safeio.read_text(dot_git, limit=4096)
471
+ except (OSError, UnicodeDecodeError, ValueError):
472
+ return out
473
+ line = text.strip().splitlines()[0] if text.strip() else ""
474
+ if not line.startswith("gitdir:"):
475
+ return out
476
+ target = os.path.normpath(os.path.join(os.path.dirname(dot_git), line[len("gitdir:"):].strip()))
477
+ out.append(target)
478
+ common = os.path.join(target, "commondir")
479
+ try:
480
+ c = safeio.read_text(common, limit=4096).strip()
481
+ out.append(os.path.normpath(os.path.join(target, c)))
482
+ except (OSError, UnicodeDecodeError, ValueError):
483
+ # a submodule (.git/modules/X) or an old worktree: the main .git is above "modules"
484
+ # or "worktrees"
485
+ parts = target.split("/")
486
+ for marker in ("modules", "worktrees"):
487
+ if marker in parts:
488
+ i = len(parts) - 1 - parts[::-1].index(marker)
489
+ out.append("/".join(parts[:i]) or "/")
490
+ break
491
+ return out
492
+
493
+
494
+ # never a derived git folder (a planted name must not block the system); /var is not here:
495
+ # temp and user data live under it (/var/folders, /var/tmp, /var/lib)
496
+ _SYSTEM_FOLDERS = ("/usr", "/bin", "/sbin", "/lib", "/lib64", "/opt", "/etc", "/System",
497
+ "/Library", "/Applications", "/private/etc", "/dev", "/proc", "/sys", "/boot",
498
+ "/nix", "/snap")
499
+
500
+
501
+ def _looks_like_git_dir(d: str) -> bool:
502
+ """A folder git itself would use: a repository (HEAD and objects/), or a worktree or
503
+ submodule entry (HEAD and commondir or gitdir)."""
504
+ if not os.path.isfile(os.path.join(d, "HEAD")):
505
+ return False
506
+ return any(os.path.lexists(os.path.join(d, x)) for x in ("objects", "commondir", "gitdir"))
507
+
508
+
509
+ def _sane_git_dir(d: str, home: str) -> bool:
510
+ """A git folder named by an agent-writable `.git` file is used only when it is a real folder
511
+ that is not `/`, the home folder or above it: a planted name cannot turn
512
+ the guard into a refusal of everything."""
513
+ if "\0" in d or not d.startswith("/") or not os.path.isdir(d):
514
+ return False
515
+ real = os.path.realpath(d)
516
+ if real == "/" or inside(os.path.realpath(home), real):
517
+ return False
518
+ if any(inside(real, s) or inside(real, os.path.realpath(s)) for s in _SYSTEM_FOLDERS):
519
+ return False
520
+ return _looks_like_git_dir(real)
521
+
522
+
523
+ def enclosing_git_dirs(path: str) -> List[str]:
524
+ """Every `.git` (folder or file) from `path` up to `/`, nearest first: a `.git` planted
525
+ closer to a root cannot hide the real one above it."""
526
+ out: List[str] = []
527
+ here = os.path.realpath(path)
528
+ while True:
529
+ candidate = os.path.join(here, ".git")
530
+ if os.path.lexists(candidate):
531
+ out.append(candidate)
532
+ parent = os.path.dirname(here)
533
+ if parent == here:
534
+ return out
535
+ here = parent
536
+
537
+
538
+ def find_repo_config(cwd: str) -> Optional[str]:
539
+ here = os.path.abspath(cwd or ".")
540
+ while True:
541
+ for name in (REPO_FILE, LEGACY_REPO_FILE):
542
+ candidate = os.path.join(here, name)
543
+ if os.path.lexists(candidate): # a link or a FIFO is found, then refused by load()
544
+ return candidate
545
+ parent = os.path.dirname(here)
546
+ if parent == here:
547
+ return None
548
+ here = parent
549
+
550
+
551
+ def _expand_root(value: str, home: str) -> str:
552
+ if value == "~" or value.startswith("~/"):
553
+ value = home + value[1:]
554
+ value = value.replace("${HOME}", home).replace("$HOME", home)
555
+ return value
556
+
557
+
558
+ def _check(data: Dict[str, Any], where: str) -> Tuple[Dict[str, Dict[str, Any]], str]:
559
+ if not isinstance(data, dict):
560
+ return {}, f"{where}: not a table"
561
+ for section, body in data.items():
562
+ if section not in SCHEMA:
563
+ return {}, f"{where}: unknown section [{section}]"
564
+ if not isinstance(body, dict):
565
+ return {}, f"{where}: [{section}] is not a table"
566
+ for key, value in body.items():
567
+ if (section, key) in REMOVED:
568
+ return {}, (f"{where}: '{section}.{key}' was removed: nothing asks at run time "
569
+ "now; grants come from [broker] write_to and net in the user config "
570
+ "(see docs/configuration.md)")
571
+ kind = SCHEMA[section].get(key)
572
+ if kind is None:
573
+ return {}, f"{where}: unknown key '{key}' in [{section}]"
574
+ if kind == "list":
575
+ if not isinstance(value, list) or not all(isinstance(v, str) and v for v in value):
576
+ return {}, f"{where}: '{section}.{key}' must be a list of non-empty strings"
577
+ elif kind == "int" and (type(value) is not int or value < 1):
578
+ return {}, f"{where}: '{section}.{key}' must be a whole number of 1 or more"
579
+ elif kind == "choice" and value not in UNRESOLVED:
580
+ return {}, f"{where}: '{section}.{key}' must be one of {', '.join(UNRESOLVED)}"
581
+ elif kind == "str" and (not isinstance(value, str) or not value):
582
+ return {}, f"{where}: '{section}.{key}' must be a non-empty string"
583
+ elif kind == "bool" and type(value) is not bool:
584
+ return {}, f"{where}: '{section}.{key}' must be true or false"
585
+ if section == "protected_paths" and key in ("roots", "patterns"):
586
+ for v in value:
587
+ if ".." in v.split("/"):
588
+ return {}, f"{where}: protected path '{v}' must have no '..'"
589
+ return data, ""
590
+
591
+
592
+ def _check_paths(cfg: Config) -> str:
593
+ for lst in cfg.command_lists:
594
+ for e in lst:
595
+ if "/" in e and not e.startswith("@") and not os.path.expanduser(e).startswith("/"):
596
+ return (f"[broker] commands entry '{e}' must be absolute (or start with ~/): "
597
+ "a relative one would be read against the broker's own folder")
598
+ for p in cfg.roots + cfg.patterns:
599
+ if not p.startswith("/"):
600
+ return f"protected path '{p}' must be absolute (or start with ~/)"
601
+ parts = p.split("/")
602
+ if ".." in parts or os.path.normpath(p) == "/":
603
+ return f"protected path '{p}' must be below / and have no '..'"
604
+ if "$" in p:
605
+ return f"protected path '{p}' may use only $HOME as a variable"
606
+ for p in cfg.roots:
607
+ if any(ch in p for ch in "*?["):
608
+ return f"root '{p}' has a wildcard; put it under 'patterns'"
609
+ for d in cfg.allowed_domains:
610
+ why = domain_problem(d)
611
+ if why:
612
+ return f"[network] allowed_domains entry '{d}' {why}"
613
+ if cfg.ssh_config and not cfg.ssh_config.startswith("/"):
614
+ return "[copy] ssh_config must be absolute (or start with ~/)" # else the agent's folder
615
+ from phiward import pathmatch
616
+ for p in cfg.patterns:
617
+ why = pathmatch.problem(p)
618
+ if why:
619
+ return f"pattern '{p}' cannot be used: {why}"
620
+ return ""
621
+
622
+
623
+ def inside(path: str, folder: str) -> bool:
624
+ return pathid.inside(path, folder)
625
+
626
+
627
+ def _folded(path: str) -> List[str]:
628
+ return list({pathid.fold(v) for v in pathid.spellings(path)})
629
+
630
+
631
+ def _deny_inside(a: str, b: str) -> bool:
632
+ """Whether `a` is `b` or inside it, in any spelling the file system treats as equal (a deny
633
+ decision folds broadly: case and Unicode form on macOS)."""
634
+ return any(inside(x, y) for x in _folded(a) for y in _folded(b))
635
+
636
+
637
+ def grant_problem(full: str, cfg: "Config", env: Optional[Dict[str, str]] = None) -> str:
638
+ """Why the resolved folder `full` may not be a write place, or ""."""
639
+ env = os.environ if env is None else env
640
+ if os.path.normpath(full) == "/":
641
+ return "it is /"
642
+ later = runs_later_problem(full, env)
643
+ if later:
644
+ return later
645
+ # a grant may sit inside a protected root (what is written there stays protected), never
646
+ # above one, and never in a derived protected folder (a `.git`) or a pattern match
647
+ for r in cfg.roots:
648
+ if _deny_inside(r, full):
649
+ return "it holds a protected path; grant a folder inside it instead"
650
+ for r in cfg.derived_roots + [_pattern_prefix(p) for p in cfg.patterns]:
651
+ if _deny_inside(full, r) or _deny_inside(r, full):
652
+ return "it is above or inside a derived protected folder or a pattern match"
653
+ # the files that decide what is masked: a gateway command must not rewrite them
654
+ for f in list(cfg.names_from) + [p for p in cfg.packs if "/" in p]:
655
+ if _deny_inside(os.path.realpath(os.path.expanduser(f)), full):
656
+ return "it holds a names or pack file of the config"
657
+ for g in guard_files(env) + [spool_dir(env)]:
658
+ if _deny_inside(full, g) or _deny_inside(g, full):
659
+ return "it holds, or is inside, a phiward file or folder"
660
+ return ""
661
+
662
+
663
+ def runs_later_problem(full: str, env: Optional[Dict[str, str]] = None) -> str:
664
+ """Why the folder `full` is a place where your own tools load code or settings later, so
665
+ the gateway may not write there, or "". A protected root here stays protected; gateway
666
+ commands just cannot write in it."""
667
+ env = os.environ if env is None else env
668
+ home = pathid.home(env)
669
+ if _deny_inside(home, full):
670
+ return "it is the home folder or above it (startup and settings files live there)"
671
+ if _deny_inside(full, home):
672
+ rel = os.path.relpath(pathid.canon(full), pathid.canon(home))
673
+ top = rel.split("/")[0]
674
+ if top.startswith("."):
675
+ return "it is in a dot-folder of the home folder (startup and settings files live there)"
676
+ if pathid.fold(top) == pathid.fold("Library"):
677
+ return "it is in ~/Library (settings and login items live there)"
678
+ for entry in (env.get("PATH") or "").split(":"):
679
+ if not entry.startswith("/"):
680
+ continue
681
+ if _deny_inside(full, entry) or _deny_inside(entry, full):
682
+ return "it is a PATH folder, or holds or is inside one (programs you run live there)"
683
+ return ""
684
+
685
+
686
+ def _pattern_prefix(pattern: str) -> str:
687
+ cut = min([i for i in (pattern.find("*"), pattern.find("?"), pattern.find("[")) if i >= 0]
688
+ or [len(pattern)])
689
+ return os.path.dirname(pattern[:cut]) if cut < len(pattern) else pattern
690
+
691
+
692
+ def _resolve_write_to(cfg: "Config", env: Dict[str, str]) -> str:
693
+ named, cfg.write_to = cfg.write_to, []
694
+ for w in named:
695
+ if not w.startswith("/"):
696
+ return f"[broker] write_to '{w}' must be absolute (or start with ~/)"
697
+ full = os.path.realpath(w)
698
+ if not os.path.isdir(full):
699
+ cfg.write_to_missing += 1
700
+ continue
701
+ written = os.path.normpath(w)
702
+ # an allow decision: exact on a case-sensitive volume, folded only where the volume
703
+ # folds
704
+ same = (full == written) if pathid.case_sensitive(full) else \
705
+ pathid.fold(full) == pathid.fold(written)
706
+ if not same:
707
+ # a link on the way: whoever can change the link would choose the place
708
+ cfg.write_to_linked += 1
709
+ continue
710
+ why = grant_problem(full, cfg, env)
711
+ if not why and os.path.isdir(os.path.join(full, ".claude")):
712
+ # skipped, not a problem: anyone who can make the folder could otherwise stop every
713
+ # guarded action; doctor counts it
714
+ cfg.write_to_claude += 1
715
+ continue
716
+ if why:
717
+ return f"[broker] write_to '{w}' may not be granted: {why}"
718
+ full = pathid.canon(full) # stored in the file system's own spelling (step 3)
719
+ if full not in cfg.write_to:
720
+ cfg.write_to.append(full)
721
+ return ""
722
+
723
+
724
+ def stricter(a: str, b: str) -> str:
725
+ return a if UNRESOLVED.index(a) >= UNRESOLVED.index(b) else b
726
+
727
+
728
+ def _merge(cfg: Config, data: Dict[str, Dict[str, Any]], home: str, repo: bool) -> None:
729
+ if repo:
730
+ data = {sec: dict(keys) for sec, keys in data.items()}
731
+ for sec, key in sorted(USER_ONLY):
732
+ if key in data.get(sec, {}):
733
+ del data[sec][key]
734
+ if f"{sec}.{key}" not in cfg.ignored:
735
+ cfg.ignored.append(f"{sec}.{key}")
736
+ packs = data.get("sanitize", {}).get("packs", [])
737
+ if any("/" in p for p in packs): # a pack file is code the agent could write
738
+ data["sanitize"]["packs"] = [p for p in packs if "/" not in p]
739
+ if "sanitize.packs (files)" not in cfg.ignored:
740
+ cfg.ignored.append("sanitize.packs (files)")
741
+ pp = data.get("protected_paths", {})
742
+ for key, target, mine in (("roots", cfg.roots, cfg.user_roots),
743
+ ("patterns", cfg.patterns, cfg.user_patterns)):
744
+ for r in pp.get(key, []):
745
+ r = os.path.normpath(_expand_root(r, home))
746
+ if r not in target:
747
+ target.append(r)
748
+ if not repo and r not in mine:
749
+ mine.append(r)
750
+ for v in pp.get("snapshot_names", []): # adds protection: allowed in a repo file too
751
+ if "/" not in v and v not in cfg.snapshot_names:
752
+ cfg.snapshot_names.append(v)
753
+ if "unresolved" in pp:
754
+ cfg.unresolved = stricter(cfg.unresolved, pp["unresolved"]) if repo else pp["unresolved"]
755
+ san = data.get("sanitize", {})
756
+ if repo and san.get("packs") and not cfg.packs:
757
+ # a repo file adds packs to the user's (or to the default), never replaces them: an
758
+ # empty list means the default, and a repo list would otherwise turn it off
759
+ from phiward.sanitize import DEFAULT_PACKS
760
+ cfg.packs.extend(DEFAULT_PACKS)
761
+ for key, target in (("packs", cfg.packs), ("names_from", cfg.names_from),
762
+ ("patterns", cfg.sanitize_patterns)):
763
+ for v in san.get(key, []):
764
+ if key == "names_from":
765
+ v = _expand_root(v, home)
766
+ if v not in target:
767
+ target.append(v)
768
+ if "table" in san: # USER_ONLY: a repo file's value is ignored (listed in cfg.ignored)
769
+ cfg.sanitize_table = bool(san["table"])
770
+ if "inventory_limit" in san:
771
+ # tighten only: a repo file can lower the limit, never raise it
772
+ lim = san["inventory_limit"]
773
+ cfg.inventory_limit = min(cfg.inventory_limit, lim) if repo else lim
774
+ rm = data.get("remote", {})
775
+ if "use_shared_connection" in rm: # USER_ONLY
776
+ cfg.use_shared_connection = bool(rm["use_shared_connection"])
777
+ if "push_limit_gib" in data.get("copy", {}): # USER_ONLY
778
+ cfg.push_limit_gib = max(0, int(data["copy"]["push_limit_gib"]))
779
+ for key, target in (("hosts", cfg.remote_hosts), ("commands", cfg.remote_commands),
780
+ ("roots", cfg.remote_roots)):
781
+ for v in rm.get(key, []):
782
+ v = os.path.normpath(v) if key == "roots" else v
783
+ if v not in target:
784
+ target.append(v)
785
+ br = data.get("broker", {})
786
+ for v in br.get("write_to", []): # only from the user file (USER_ONLY); checked in load()
787
+ v = os.path.normpath(_expand_root(v, home))
788
+ if v not in cfg.write_to:
789
+ cfg.write_to.append(v)
790
+ if "net" in br:
791
+ cfg.net = br["net"]
792
+ if "max_output_lines" in br:
793
+ m = br["max_output_lines"]
794
+ cfg.max_output_lines = min(cfg.max_output_lines, m) if repo else m
795
+ if "commands" in br:
796
+ # a repo list can only narrow: a program must be in every list that is set
797
+ cfg.command_lists.append([str(v) for v in br["commands"]])
798
+ if not repo:
799
+ cfg.user_commands = cfg.command_lists[-1]
800
+ for v in data.get("launch", {}).get("pass_env", []):
801
+ if v not in cfg.launch_pass_env:
802
+ cfg.launch_pass_env.append(v)
803
+ if "best_effort" in data.get("shell", {}): # USER_ONLY
804
+ cfg.shell_best_effort = bool(data["shell"]["best_effort"])
805
+ nw = data.get("network", {})
806
+ if "limit" in nw: # USER_ONLY
807
+ cfg.network_limit = bool(nw["limit"])
808
+ for v in nw.get("allowed_domains", []): # USER_ONLY
809
+ if v not in cfg.allowed_domains:
810
+ cfg.allowed_domains.append(v)
811
+ if "ssh_config" in data.get("copy", {}):
812
+ cfg.ssh_config = os.path.normpath(_expand_root(data["copy"]["ssh_config"], home))
813
+
814
+ for v in data.get("copy", {}).get("remotes", []):
815
+ if v not in cfg.remotes:
816
+ cfg.remotes.append(v)
817
+ for v in data.get("git", {}).get("protected_branches", []):
818
+ if v not in cfg.protected_branches:
819
+ cfg.protected_branches.append(v)
820
+
821
+
822
+ def load(cwd: str, env: Optional[Dict[str, str]] = None) -> Config:
823
+ """The combined config for a tool call whose working folder is `cwd`."""
824
+ env = os.environ if env is None else env
825
+ home = pathid.home(env)
826
+ cfg = Config()
827
+ places = []
828
+ user = user_config_path(env)
829
+ if env.get("PHIWARD_CONFIG") and not os.path.isabs(user):
830
+ cfg.problem = f"$PHIWARD_CONFIG must be an absolute path: {user}"
831
+ return cfg
832
+ if env.get("PHIWARD_CONFIG") and not os.path.isfile(user):
833
+ cfg.problem = f"$PHIWARD_CONFIG names no file: {user}"
834
+ return cfg
835
+ if not env.get("PHIWARD_CONFIG") and not os.path.lexists(user) and \
836
+ os.path.lexists(legacy_user_config_path(env)):
837
+ cfg.problem = ("the user config is still at ~/.config/agent-guards/config.toml (the name "
838
+ "before phiward); move that folder to ~/.config/phiward")
839
+ return cfg
840
+ if os.path.isfile(user):
841
+ places.append(user)
842
+ repo = find_repo_config(cwd)
843
+ if repo and os.path.basename(repo) == LEGACY_REPO_FILE:
844
+ cfg.problem = (f"a repo config has the name before phiward ({LEGACY_REPO_FILE}); rename "
845
+ f"it to {REPO_FILE}")
846
+ return cfg
847
+ if repo and repo not in places:
848
+ places.append(repo)
849
+ for place in places:
850
+ is_repo = place != user
851
+ detail = ""
852
+ try:
853
+ if is_repo:
854
+ from phiward import paths
855
+ pset = paths.ProtectedSet(cfg.roots, cfg.patterns)
856
+ if pset.relation(place) == paths.INSIDE or \
857
+ pset.relation(os.path.dirname(place)) == paths.INSIDE:
858
+ raise OSError("it is inside a protected path")
859
+ raw, _ = _toml.load_file(place, follow=not is_repo)
860
+ except (OSError, UnicodeDecodeError) as exc:
861
+ detail = f"{place} cannot be read ({type(exc).__name__}: {exc})"
862
+ except _toml.TomlError as exc:
863
+ detail = f"{place} does not parse: {exc}"
864
+ else:
865
+ data, detail = _check(raw, place)
866
+ if detail:
867
+ if is_repo:
868
+ cfg.problem = (f"{place}: the repo config cannot be used (it is not a plain "
869
+ "file, it is in a protected place, or it has an error); the "
870
+ "operator sees why with `phiward doctor --show-paths`")
871
+ cfg.problem_detail = detail
872
+ else:
873
+ cfg.problem = detail
874
+ return cfg
875
+ # The user's value (default deny) is the floor; a repo file can only make it stricter.
876
+ _merge(cfg, data, home, repo=place != user)
877
+ cfg.files.append(place)
878
+ cfg.problem = _check_paths(cfg)
879
+ cfg.cache_dir = cache_dir(env)
880
+ if cfg.has_protected_paths and not cfg.problem:
881
+ cfg.derived_roots.append(cfg.cache_dir)
882
+ spool = os.path.realpath(spool_dir(env))
883
+
884
+ def sane(d: str) -> bool:
885
+ if "\0" in d or not _sane_git_dir(d, home): # the NUL check before any path call
886
+ return False
887
+ real = os.path.realpath(d)
888
+ return (not inside(spool, real) and
889
+ not inside(real, spool) and not any(inside(r2, d) for r2 in cfg.roots))
890
+
891
+ for r in cfg.roots:
892
+ for g in enclosing_git_dirs(r):
893
+ found = git_dirs(g)
894
+ # the .git itself when it is a folder or file in place; a .git that is a link,
895
+ # and folders read out of a .git file, only when they look like git folders and
896
+ # are not system, home, spool or root folders. No
897
+ # dependence on the caller's working folder (finding 11).
898
+ first = [found[0]] if not os.path.islink(found[0]) or sane(found[0]) else []
899
+ keep = first + [d for d in found[1:] if sane(d)]
900
+ for d in keep:
901
+ if d not in cfg.derived_roots:
902
+ cfg.derived_roots.append(d)
903
+ # old copies (snapshot folders) and other mounts of the same data
904
+ from phiward import fsinfo
905
+ prefixes = [_pattern_prefix(p) for p in cfg.patterns]
906
+ linux = sys.platform.startswith("linux")
907
+ if linux:
908
+ # an overlay whose folders cannot be read may show protected data: its own mount
909
+ # point is protected, nothing else stops
910
+ for d in fsinfo.unknown_overlays():
911
+ if d not in cfg.derived_roots:
912
+ cfg.derived_roots.append(d)
913
+ # repeat until nothing new is found: an alias of an alias, a snapshot above an alias
914
+ todo = cfg.roots + prefixes + list(cfg.derived_roots)
915
+ done: List[str] = []
916
+ while todo and len(done) < 1000:
917
+ r = todo.pop(0)
918
+ if r in done:
919
+ continue
920
+ done.append(r)
921
+ extra = fsinfo.snapshot_dirs(r, cfg.snapshot_names)
922
+ if linux:
923
+ extra += [a for a in fsinfo.alias_paths(r) if os.path.lexists(a)]
924
+ for d in extra:
925
+ if d not in cfg.roots and d not in cfg.derived_roots:
926
+ cfg.derived_roots.append(d)
927
+ todo.append(d)
928
+ cfg.found_derived = list(cfg.derived_roots)
929
+ # pinned by the operator (phiward pin): never removed by what is found now
930
+ from phiward import pin
931
+ for d in pin.read_pins(env):
932
+ if d not in cfg.roots and d not in cfg.derived_roots and os.path.lexists(d):
933
+ cfg.derived_roots.append(d)
934
+ if not cfg.problem:
935
+ cfg.problem = _resolve_write_to(cfg, env)
936
+ return cfg