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.
- phiward/__init__.py +8 -0
- phiward/__main__.py +5 -0
- phiward/_toml.py +211 -0
- phiward/adapters/__init__.py +105 -0
- phiward/adapters/claude.py +429 -0
- phiward/broker.py +831 -0
- phiward/carryover.py +1613 -0
- phiward/claude_settings.py +1307 -0
- phiward/cli.py +110 -0
- phiward/config.py +936 -0
- phiward/confine.py +476 -0
- phiward/copying.py +533 -0
- phiward/core.py +105 -0
- phiward/data/agents-section.md +43 -0
- phiward/doctor.py +1132 -0
- phiward/fasthook.py +70 -0
- phiward/fsinfo.py +241 -0
- phiward/gateway.py +159 -0
- phiward/githooks.py +248 -0
- phiward/guards/__init__.py +0 -0
- phiward/guards/protected_paths.py +1138 -0
- phiward/hidden.py +281 -0
- phiward/init.py +155 -0
- phiward/install.py +828 -0
- phiward/inventory.py +173 -0
- phiward/mcp.py +186 -0
- phiward/mcp_config.py +1736 -0
- phiward/names.py +5 -0
- phiward/packs/dates.toml +17 -0
- phiward/packs/genomics.toml +51 -0
- phiward/packs/msk.toml +32 -0
- phiward/pathid.py +403 -0
- phiward/pathmatch.py +98 -0
- phiward/paths.py +942 -0
- phiward/pin.py +214 -0
- phiward/procinfo.py +73 -0
- phiward/remote.py +448 -0
- phiward/run.py +788 -0
- phiward/safeio.py +84 -0
- phiward/sanitize.py +691 -0
- phiward/selfcheck.py +1506 -0
- phiward/service.py +321 -0
- phiward/session_note.py +86 -0
- phiward/setup_cmd.py +886 -0
- phiward/shell.py +504 -0
- phiward/wholetool.py +1463 -0
- phiward-0.2.0b1.dist-info/METADATA +147 -0
- phiward-0.2.0b1.dist-info/RECORD +53 -0
- phiward-0.2.0b1.dist-info/WHEEL +5 -0
- phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
- phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
- phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
- 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
|