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/copying.py
ADDED
|
@@ -0,0 +1,533 @@
|
|
|
1
|
+
"""`phiward copy SRC... DST`: copy protected data without printing it.
|
|
2
|
+
|
|
3
|
+
The destination must be inside a protected root of the user's own config, or under a configured
|
|
4
|
+
remote (`[copy] remotes = ["host:/abs/prefix"]`). Like `run`, the command the agent types is a
|
|
5
|
+
client of the broker; the broker calls `execute`. The copy runs with rsync (or
|
|
6
|
+
`cp -R` when rsync is missing and every path is local) in the gateway profile of
|
|
7
|
+
`phiward run`: it can write only at its destination (a folder inside a protected path of the
|
|
8
|
+
user's config, reached with no link), and it gets the network only when a remote is involved. Every line
|
|
9
|
+
it prints goes through the sanitizer, which also masks every entry name under the roots. The
|
|
10
|
+
wrapper's own messages never name a path.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import os
|
|
14
|
+
import re
|
|
15
|
+
import subprocess
|
|
16
|
+
import sys
|
|
17
|
+
from typing import Callable, Dict, List, Optional, Sequence, TextIO, Tuple
|
|
18
|
+
|
|
19
|
+
from phiward import config, paths, pathid, safeio
|
|
20
|
+
from phiward.sanitize import Sanitizer, SanitizerError
|
|
21
|
+
|
|
22
|
+
USAGE = "usage: phiward copy [--dry-run] SRC... DST\n"
|
|
23
|
+
HELP = USAGE + """
|
|
24
|
+
Options:
|
|
25
|
+
--dry-run check the request and copy nothing
|
|
26
|
+
-h, --help show this help
|
|
27
|
+
|
|
28
|
+
Copy protected data without printing it. DST must be inside a protected root of your user
|
|
29
|
+
config, or under a configured remote (`[copy] remotes = ["host:/abs/prefix"]`). A source or
|
|
30
|
+
destination on a remote is written HOST:/PATH.
|
|
31
|
+
|
|
32
|
+
The command is only a client. The broker runs the copy outside the agent's sandbox, so a
|
|
33
|
+
broker must be running (`phiward broker`). The copy writes only at its destination, which
|
|
34
|
+
must be inside a protected path of your config and reached with no link. It gets the network
|
|
35
|
+
only when a remote is involved. Every line it prints is masked,
|
|
36
|
+
and its own messages never name a path.
|
|
37
|
+
"""
|
|
38
|
+
_REMOTE = re.compile(r"([A-Za-z0-9_.@-]+):(/.*)", re.S)
|
|
39
|
+
# openrsync passes a remote path to the remote shell as it is, so a remote path may hold only
|
|
40
|
+
# characters no shell treats as special
|
|
41
|
+
_SAFE_PATH = re.compile(r"/[A-Za-z0-9._+/-]*")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
_HOME_WORD = re.compile(r"(home\d*|homes|users)", re.I)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def remote_prefix_problem(path: str) -> str:
|
|
48
|
+
"""Why a copy remote's folder is too broad, or "": a push there could reach files your
|
|
49
|
+
login on the cluster runs (your home folder's startup files, `~/.ssh`)."""
|
|
50
|
+
parts = [p for p in os.path.normpath(path).split("/") if p]
|
|
51
|
+
if len(parts) < 2:
|
|
52
|
+
return "it is / or a folder just below it; name your work folder on the cluster"
|
|
53
|
+
if any(p.startswith(".") for p in parts):
|
|
54
|
+
return "it is in a dot-folder (`.ssh`, `.config`): files there run or configure later"
|
|
55
|
+
if _HOME_WORD.fullmatch(parts[-2]) or _HOME_WORD.fullmatch(parts[-1]):
|
|
56
|
+
return "it looks like a home folder; name a work folder inside it"
|
|
57
|
+
return ""
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _remote_ok(spec: str, remotes: Sequence[str]) -> bool:
|
|
61
|
+
m = _REMOTE.fullmatch(spec)
|
|
62
|
+
if not m or not _SAFE_PATH.fullmatch(m.group(2)) or ".." in m.group(2).split("/"):
|
|
63
|
+
return False
|
|
64
|
+
host, path = m.group(1), os.path.normpath(m.group(2))
|
|
65
|
+
if any(p.startswith(".") for p in path.split("/") if p):
|
|
66
|
+
return False # never into a dot-folder (`.ssh`, `.git/hooks`): files there run later
|
|
67
|
+
for r in remotes:
|
|
68
|
+
rm = _REMOTE.fullmatch(r)
|
|
69
|
+
if not rm:
|
|
70
|
+
continue
|
|
71
|
+
prefix = os.path.normpath(rm.group(2))
|
|
72
|
+
if remote_prefix_problem(prefix):
|
|
73
|
+
continue # too broad: never a place a copy may go
|
|
74
|
+
if rm.group(1) == host and (path == prefix or path.startswith(prefix.rstrip("/") + "/")):
|
|
75
|
+
return True
|
|
76
|
+
return False
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def dest_place(dst: str, cwd: str, cfg: config.Config) -> "Tuple[str, str]":
|
|
80
|
+
"""(the one place a local copy or a pull may write: the nearest existing folder of its
|
|
81
|
+
destination; why it may not, or ""). The place must be inside one of the user's roots by
|
|
82
|
+
its real path, with no link on the way (a link the agent made inside a root would lead the
|
|
83
|
+
copy out of it), and not where your tools load code later or that holds a names, pack or
|
|
84
|
+
phiward file."""
|
|
85
|
+
d = os.path.normpath(os.path.join(cwd, os.path.expanduser(dst)))
|
|
86
|
+
if any(pathid.fold(c) == ".claude" or c.lower() == ".claude" for c in d.split("/")):
|
|
87
|
+
return d, "the destination is in a .claude folder (Claude Code loads settings from there)"
|
|
88
|
+
while not os.path.isdir(d) or os.path.islink(d):
|
|
89
|
+
if os.path.islink(d):
|
|
90
|
+
return d, "the destination is reached through a link; name the real folder"
|
|
91
|
+
up = os.path.dirname(d)
|
|
92
|
+
if up == d:
|
|
93
|
+
break
|
|
94
|
+
d = up
|
|
95
|
+
real = os.path.realpath(d)
|
|
96
|
+
canon = pathid.canon(real) # the file system's own spelling (/System/Volumes/Data undone)
|
|
97
|
+
same = any(((x == d) if pathid.case_sensitive(real) else pathid.fold(x) == pathid.fold(d))
|
|
98
|
+
for x in (real, "/System/Volumes/Data" + canon if canon.startswith("/") else ""))
|
|
99
|
+
if not same:
|
|
100
|
+
return real, "the destination is reached through a link; name the real folder"
|
|
101
|
+
real = canon
|
|
102
|
+
# inside a protected root (not a pattern match: in Mode A the agent's own sandbox cannot
|
|
103
|
+
# cover a pattern match it makes, so it could read back what lands there)
|
|
104
|
+
if not any(config._deny_inside(real, r) or _within(real, r) for r in cfg.user_roots):
|
|
105
|
+
return real, "the destination is not inside a protected root of the user config"
|
|
106
|
+
why = config.runs_later_problem(real)
|
|
107
|
+
if why:
|
|
108
|
+
return real, f"the destination is where your own tools load code later: {why}"
|
|
109
|
+
# by name (folded where the system folds) and by identity (device and inode), so a volume
|
|
110
|
+
# that ignores letter case on Linux cannot hide a match
|
|
111
|
+
for r in cfg.derived_roots:
|
|
112
|
+
if _related(real, r):
|
|
113
|
+
return real, "the destination is in or above a derived protected folder (a .git)"
|
|
114
|
+
for f in list(cfg.names_from) + [p for p in cfg.packs if "/" in p]:
|
|
115
|
+
f = os.path.realpath(os.path.expanduser(f))
|
|
116
|
+
if config._deny_inside(f, real) or _holds(real, f):
|
|
117
|
+
return real, "the destination holds a names or pack file of the config"
|
|
118
|
+
for g in config.guard_files() + [config.spool_dir()]:
|
|
119
|
+
if _related(real, g):
|
|
120
|
+
return real, "the destination holds, or is inside, a phiward file or folder"
|
|
121
|
+
return real, ""
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def holds_claude(srcs: Sequence[str], cwd: str, limit: int = 200000) -> str:
|
|
125
|
+
"""Why a copy source cannot be copied as it is, or "": it is or holds a `.claude` folder in
|
|
126
|
+
any letter case (rsync's exclude matches one spelling only), or it cannot be checked (a
|
|
127
|
+
folder that cannot be read, or one with more entries than `limit`)."""
|
|
128
|
+
seen = 0
|
|
129
|
+
for src in srcs:
|
|
130
|
+
stack = [os.path.join(cwd, os.path.expanduser(src))]
|
|
131
|
+
while stack:
|
|
132
|
+
a = stack.pop()
|
|
133
|
+
seen += 1
|
|
134
|
+
if seen > limit:
|
|
135
|
+
return (f"a source holds more than {limit} entries, so it cannot be checked for "
|
|
136
|
+
".claude folders; copy smaller parts")
|
|
137
|
+
if os.path.basename(a.rstrip("/")).casefold() == ".claude":
|
|
138
|
+
return ("a source is or holds a .claude folder (Claude Code loads settings from "
|
|
139
|
+
"it); copy without it")
|
|
140
|
+
if os.path.isdir(a) and not os.path.islink(a):
|
|
141
|
+
try:
|
|
142
|
+
stack += [os.path.join(a, n) for n in os.listdir(a)]
|
|
143
|
+
except OSError:
|
|
144
|
+
return ("a source folder cannot be read, so it cannot be checked for "
|
|
145
|
+
".claude folders")
|
|
146
|
+
return ""
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _holds_links(srcs: Sequence[str], cwd: str, limit: int = 200000) -> bool:
|
|
150
|
+
seen = 0
|
|
151
|
+
for src in srcs:
|
|
152
|
+
stack = [os.path.join(cwd, os.path.expanduser(src))]
|
|
153
|
+
while stack and seen < limit:
|
|
154
|
+
a = stack.pop()
|
|
155
|
+
seen += 1
|
|
156
|
+
if os.path.isdir(a) and not os.path.islink(a):
|
|
157
|
+
try:
|
|
158
|
+
for n in os.listdir(a):
|
|
159
|
+
p = os.path.join(a, n)
|
|
160
|
+
if os.path.islink(p):
|
|
161
|
+
return True
|
|
162
|
+
stack.append(p)
|
|
163
|
+
except OSError:
|
|
164
|
+
pass
|
|
165
|
+
return False
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def type_clash(srcs: Sequence[str], dst: str, cwd: str, limit: int = 200000) -> bool:
|
|
169
|
+
"""Whether a local copy would meet something at the destination of another type (a folder
|
|
170
|
+
where a file exists, a file where a folder or a link exists). rsync on macOS would replace
|
|
171
|
+
it; phiward refuses the whole copy instead."""
|
|
172
|
+
base = os.path.join(cwd, os.path.expanduser(dst))
|
|
173
|
+
many = len(srcs) > 1 or dst.endswith("/")
|
|
174
|
+
seen = 0
|
|
175
|
+
for src in srcs:
|
|
176
|
+
s = os.path.join(cwd, os.path.expanduser(src))
|
|
177
|
+
top = base if not (many or os.path.isdir(base)) else (
|
|
178
|
+
base if src.endswith("/") else os.path.join(base, os.path.basename(s.rstrip("/"))))
|
|
179
|
+
stack = [(s, top)]
|
|
180
|
+
while stack:
|
|
181
|
+
a, b = stack.pop()
|
|
182
|
+
seen += 1
|
|
183
|
+
if seen > limit:
|
|
184
|
+
return True # too large to check: refused, not guessed
|
|
185
|
+
if not os.path.lexists(b):
|
|
186
|
+
continue
|
|
187
|
+
if os.path.islink(b) or os.path.isdir(a) != os.path.isdir(b):
|
|
188
|
+
return True
|
|
189
|
+
if os.path.isdir(a) and not os.path.islink(a):
|
|
190
|
+
try:
|
|
191
|
+
stack += [(os.path.join(a, n), os.path.join(b, n)) for n in os.listdir(a)]
|
|
192
|
+
except OSError:
|
|
193
|
+
return True
|
|
194
|
+
return False
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _within(a: str, b: str) -> bool:
|
|
198
|
+
"""Whether `a` is `b` or inside it, by identity: a folder on `a`'s way up is `b`."""
|
|
199
|
+
target = pathid.identity(b)
|
|
200
|
+
if target is None:
|
|
201
|
+
return False
|
|
202
|
+
d = os.path.realpath(a)
|
|
203
|
+
while True:
|
|
204
|
+
if pathid.identity(d) == target:
|
|
205
|
+
return True
|
|
206
|
+
up = os.path.dirname(d)
|
|
207
|
+
if up == d:
|
|
208
|
+
return False
|
|
209
|
+
d = up
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _holds(place: str, path: str) -> bool:
|
|
213
|
+
"""Whether the folder `place` holds `path` (or is it), by identity."""
|
|
214
|
+
return _within(path, place)
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def _related(a: str, b: str) -> bool:
|
|
218
|
+
"""Whether `a` is inside `b` or holds it, by name or by identity."""
|
|
219
|
+
return (config._deny_inside(a, b) or config._deny_inside(b, a)
|
|
220
|
+
or _within(a, b) or _within(b, a))
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def _local_inside(path: str, cwd: str, pset: paths.ProtectedSet) -> bool:
|
|
224
|
+
full = os.path.normpath(os.path.join(cwd, os.path.expanduser(path)))
|
|
225
|
+
return pset.relation(full) == paths.INSIDE
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def _is_remote(arg: str) -> bool:
|
|
229
|
+
"""An argument rsync reads as remote (a `:` before the first `/`) is remote. A local name
|
|
230
|
+
with a `:` is written `./name` (an exception for a name that exists
|
|
231
|
+
in the request's folder made rsync and this check disagree)."""
|
|
232
|
+
return ":" in arg.split("/", 1)[0]
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def plan(args: Sequence[str], cwd: str, cfg: config.Config) -> Optional[str]:
|
|
236
|
+
"""Why the copy is refused, or None when it may run."""
|
|
237
|
+
if len(args) < 2:
|
|
238
|
+
return "a copy needs at least one source and a destination"
|
|
239
|
+
if any(a.startswith("-") for a in args):
|
|
240
|
+
return "options are not accepted (the wrapper picks them)"
|
|
241
|
+
dst = args[-1]
|
|
242
|
+
# only the user's own roots: a root that a repo config adds is in the agent's reach
|
|
243
|
+
pset = paths.ProtectedSet(cfg.user_roots, cfg.user_patterns)
|
|
244
|
+
if _is_remote(dst):
|
|
245
|
+
if not _remote_ok(dst, cfg.remotes):
|
|
246
|
+
return "the destination is not under a configured remote ([copy] remotes)"
|
|
247
|
+
elif not _local_inside(dst, cwd, pset):
|
|
248
|
+
return "the destination is not inside a protected path of the user config"
|
|
249
|
+
from phiward import run
|
|
250
|
+
hidden = paths.ProtectedSet(run.gateway_hidden(cfg), [])
|
|
251
|
+
for src in args[:-1]:
|
|
252
|
+
if _is_remote(src) and not _remote_ok(src, cfg.remotes):
|
|
253
|
+
return "a remote source is not under a configured remote ([copy] remotes)"
|
|
254
|
+
if not _is_remote(src):
|
|
255
|
+
full = os.path.realpath(os.path.join(cwd, os.path.expanduser(src)))
|
|
256
|
+
if hidden.relation(full) in (paths.INSIDE, paths.ABOVE):
|
|
257
|
+
# rsync and ssh read credentials for a remote copy, so the profile cannot hide
|
|
258
|
+
# them: a source that is or holds one is refused here
|
|
259
|
+
return "a source is or holds a credential or a trace that no copy may read"
|
|
260
|
+
return None
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
# Programs a copy runs come from system folders only, never from a PATH folder the agent may
|
|
264
|
+
# write (~/.local/bin, Homebrew), and ssh reads only the operator's chosen config.
|
|
265
|
+
SYSTEM_DIRS = ("/usr/bin", "/bin", "/usr/sbin", "/sbin")
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def system_program(name: str) -> Optional[str]:
|
|
269
|
+
for d in SYSTEM_DIRS:
|
|
270
|
+
p = os.path.join(d, name)
|
|
271
|
+
if os.path.isfile(p) and os.access(p, os.X_OK):
|
|
272
|
+
return p
|
|
273
|
+
return None
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def rsync_command(args: Sequence[str], dry_run: bool) -> Optional[List[str]]:
|
|
277
|
+
"""The rsync argv of a local copy, or None when there is no system rsync. Remote copies do
|
|
278
|
+
not use rsync (only the system ssh touches the shared connection)."""
|
|
279
|
+
rsync = system_program("rsync")
|
|
280
|
+
if rsync is None:
|
|
281
|
+
return None
|
|
282
|
+
# a `.claude` folder is never copied: Claude Code loads settings and hooks from it
|
|
283
|
+
# existing files are kept, never replaced (an agent could replace a script the operator runs)
|
|
284
|
+
# files, folders and times only: no modes (an existing folder's mode stays), no links
|
|
285
|
+
return [rsync, "-rt", "--ignore-existing", "--exclude=.claude/"] + \
|
|
286
|
+
(["--dry-run"] if dry_run else []) + ["--"] + list(args)
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def _never() -> bool:
|
|
290
|
+
return False
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def execute(argv: Sequence[str], cwd: str, env: Dict[str, str], out: TextIO,
|
|
294
|
+
cancelled: Callable[[], bool] = _never) -> int:
|
|
295
|
+
"""Run a copy request (in the broker), with `cwd` as the working folder."""
|
|
296
|
+
dry_run = False
|
|
297
|
+
args = list(argv)
|
|
298
|
+
if args[:1] == ["--dry-run"]:
|
|
299
|
+
dry_run, args = True, args[1:]
|
|
300
|
+
if args[:1] in (["-h"], ["--help"]):
|
|
301
|
+
out.write(USAGE)
|
|
302
|
+
return 0
|
|
303
|
+
cfg = config.load(cwd)
|
|
304
|
+
if cfg.problem:
|
|
305
|
+
out.write("copy refused: the phiward config cannot be used (run phiward doctor)\n")
|
|
306
|
+
return 3
|
|
307
|
+
why = plan(args, cwd, cfg)
|
|
308
|
+
if why:
|
|
309
|
+
out.write(f"copy refused: {why}\n")
|
|
310
|
+
return 2
|
|
311
|
+
srcs, dst = args[:-1], args[-1]
|
|
312
|
+
remote_srcs = [s for s in srcs if _is_remote(s)]
|
|
313
|
+
if _is_remote(dst) and remote_srcs:
|
|
314
|
+
out.write("copy refused: a copy between two remotes is not supported\n")
|
|
315
|
+
return 2
|
|
316
|
+
try:
|
|
317
|
+
san = Sanitizer.from_config(cfg, entries=True)
|
|
318
|
+
except SanitizerError:
|
|
319
|
+
out.write("copy refused: the sanitizer cannot start (run phiward doctor)\n")
|
|
320
|
+
return 3
|
|
321
|
+
from phiward import confine, run
|
|
322
|
+
try:
|
|
323
|
+
if _is_remote(dst):
|
|
324
|
+
return _push(srcs, dst, cwd, cfg, san, dry_run, env, out, cancelled)
|
|
325
|
+
if remote_srcs:
|
|
326
|
+
hosts = {_REMOTE.fullmatch(s).group(1) for s in remote_srcs} # type: ignore[union-attr]
|
|
327
|
+
if len(hosts) != 1 or len(remote_srcs) != len(srcs):
|
|
328
|
+
out.write("copy refused: a pull takes sources from one remote only\n")
|
|
329
|
+
return 2
|
|
330
|
+
return _pull(hosts.pop(), remote_srcs, dst, cwd, cfg, san, dry_run, env, out,
|
|
331
|
+
cancelled)
|
|
332
|
+
cmd = rsync_command(args, dry_run)
|
|
333
|
+
if cmd is None:
|
|
334
|
+
if any(os.path.isdir(os.path.join(cwd, os.path.expanduser(a))) for a in srcs):
|
|
335
|
+
# only rsync leaves `.claude` folders out
|
|
336
|
+
out.write("copy refused: rsync is not installed; a folder is copied only with "
|
|
337
|
+
"rsync (install it, or copy single files)\n")
|
|
338
|
+
return 2
|
|
339
|
+
cp = system_program("cp") or "/bin/cp"
|
|
340
|
+
cmd = [sys.executable, "-c", "pass"] if dry_run else [cp, "-R", "-n", "--"] + list(args)
|
|
341
|
+
if not dry_run:
|
|
342
|
+
# make the destination folder first (Linux rsync has no --mkpath), inside the same
|
|
343
|
+
# profile and write place as the copy
|
|
344
|
+
folder = dst if (dst.endswith("/") or len(srcs) > 1) else (os.path.dirname(dst) or ".")
|
|
345
|
+
cmd = ["/bin/sh", "-c", 'mkdir -p -- "$1" && shift && exec "$@"', "sh", folder] + cmd
|
|
346
|
+
# a local copy writes only at its destination (inside a protected root), with no
|
|
347
|
+
# network, and reads no credential
|
|
348
|
+
place, why = dest_place(dst, cwd, cfg)
|
|
349
|
+
if why:
|
|
350
|
+
out.write(f"copy refused: {why}\n")
|
|
351
|
+
return 2
|
|
352
|
+
why = holds_claude(srcs, cwd)
|
|
353
|
+
if why:
|
|
354
|
+
out.write(f"copy refused: {why}\n")
|
|
355
|
+
return 2
|
|
356
|
+
if any(os.path.islink(os.path.join(cwd, os.path.expanduser(a.rstrip("/")))) for a in srcs) \
|
|
357
|
+
or _holds_links(srcs, cwd):
|
|
358
|
+
out.write("copy: links in the sources are not copied (only files and folders)\n")
|
|
359
|
+
if type_clash(srcs, dst, cwd):
|
|
360
|
+
out.write("copy refused: something at the destination has another type than what "
|
|
361
|
+
"would be copied there (a folder over a file, or a link); nothing was "
|
|
362
|
+
"copied\n")
|
|
363
|
+
return 2
|
|
364
|
+
return run.run_confined(cmd, cfg, san, [place], False, out,
|
|
365
|
+
label="copy (dry run, nothing copied)" if dry_run else "copy",
|
|
366
|
+
env=env, cwd=cwd, cancelled=cancelled,
|
|
367
|
+
deny_read=run.gateway_hidden(cfg))
|
|
368
|
+
except confine.ConfineError as exc:
|
|
369
|
+
out.write(f"copy refused: {exc}\n")
|
|
370
|
+
return 3
|
|
371
|
+
except Exception as exc: # noqa: BLE001 - never print a traceback (it can name paths)
|
|
372
|
+
out.write(f"copy failed ({type(exc).__name__})\n")
|
|
373
|
+
return 3
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
def _push(srcs: Sequence[str], dst: str, cwd: str, cfg: config.Config, san: Sanitizer,
|
|
377
|
+
dry_run: bool, env: Dict[str, str], out: TextIO,
|
|
378
|
+
cancelled: Callable[[], bool]) -> int:
|
|
379
|
+
"""A push: the broker reads the checked sources itself (no link followed) and streams them
|
|
380
|
+
into `tar -x` on the remote."""
|
|
381
|
+
from phiward import run, remote as rmt
|
|
382
|
+
m = _REMOTE.fullmatch(dst)
|
|
383
|
+
assert m is not None # plan() checked it
|
|
384
|
+
host, path = m.group(1), os.path.normpath(m.group(2))
|
|
385
|
+
limit = cfg.push_limit_gib << 30
|
|
386
|
+
# resolved once, here, and checked here: plan()'s check came earlier, and a link put on a
|
|
387
|
+
# path since then must not change what is sent
|
|
388
|
+
sources = rmt.resolve(srcs, cwd)
|
|
389
|
+
hidden = paths.ProtectedSet(run.gateway_hidden(cfg), [])
|
|
390
|
+
if any(hidden.relation(s.path) in (paths.INSIDE, paths.ABOVE) for s in sources):
|
|
391
|
+
out.write("copy refused: a source is or holds a credential or a trace that no copy may "
|
|
392
|
+
"read\n")
|
|
393
|
+
return 2
|
|
394
|
+
if any(s.path == "/" or any(s.path == n or s.path.startswith(n + "/") for n in rmt.NOT_FILES)
|
|
395
|
+
for s in sources):
|
|
396
|
+
out.write("copy refused: a source is in /dev, /proc or /sys (or is /)\n")
|
|
397
|
+
return 2
|
|
398
|
+
try:
|
|
399
|
+
counts = rmt.survey(sources, limit)
|
|
400
|
+
except rmt.PushError as exc:
|
|
401
|
+
out.write(f"copy refused: {exc}\n")
|
|
402
|
+
return 2
|
|
403
|
+
except OSError:
|
|
404
|
+
out.write("copy refused: a source is not a plain file or folder reached without a link\n")
|
|
405
|
+
return 2
|
|
406
|
+
if dry_run:
|
|
407
|
+
out.write(f"copy (dry run): would send files={counts.files} folders={counts.folders} "
|
|
408
|
+
f"skipped={counts.skipped} (links, special files and files with a second "
|
|
409
|
+
"name are not sent)\n")
|
|
410
|
+
return 0
|
|
411
|
+
rt, why = rmt.route(cfg, host)
|
|
412
|
+
if rt is None:
|
|
413
|
+
out.write(f"copy refused: {why}\n")
|
|
414
|
+
return 2
|
|
415
|
+
run.add_remote_roots(san, cfg)
|
|
416
|
+
sent = rmt.Counts()
|
|
417
|
+
cmd = rt.ssh + [host, "--", rmt.receive_script(path)]
|
|
418
|
+
code = run.run_confined(cmd, cfg, san, [], rt.net, out, label="copy", env=env, cwd=cwd,
|
|
419
|
+
cancelled=cancelled, deny_read=rt.deny_read, socket=rt.socket,
|
|
420
|
+
allow_read=rt.allow_read,
|
|
421
|
+
stdin_feed=rmt.feeder(sources, limit, sent))
|
|
422
|
+
if code == 0:
|
|
423
|
+
out.write(f"copy sent: files={sent.files} folders={sent.folders} "
|
|
424
|
+
f"skipped={sent.skipped}\n")
|
|
425
|
+
else:
|
|
426
|
+
out.write("copy failed: nothing is known to have arrived (see the line above)\n")
|
|
427
|
+
return code
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
def _pull(host: str, remote_srcs: Sequence[str], dst: str, cwd: str, cfg: config.Config,
|
|
431
|
+
san: Sanitizer, dry_run: bool, env: Dict[str, str], out: TextIO,
|
|
432
|
+
cancelled: Callable[[], bool]) -> int:
|
|
433
|
+
"""A pull: `ssh HOST tar -c` (through the shared connection, no credential, no network but
|
|
434
|
+
its socket) streams into a local `tar -x` that runs in the gateway profile: it writes only
|
|
435
|
+
at its destination inside a protected path, reads no credential, and has no network at
|
|
436
|
+
all. Only the system
|
|
437
|
+
ssh touches the socket."""
|
|
438
|
+
import shutil
|
|
439
|
+
import tempfile
|
|
440
|
+
from phiward import confine, run, remote as rmt
|
|
441
|
+
dest = os.path.normpath(os.path.join(cwd, os.path.expanduser(dst)))
|
|
442
|
+
place, why = dest_place(dst, cwd, cfg)
|
|
443
|
+
if why:
|
|
444
|
+
out.write(f"copy refused: {why}\n")
|
|
445
|
+
return 2
|
|
446
|
+
if dry_run:
|
|
447
|
+
out.write(f"copy (dry run): would pull {len(remote_srcs)} source(s) from the remote\n")
|
|
448
|
+
return 0
|
|
449
|
+
mkdir, tar = system_program("mkdir"), system_program("tar")
|
|
450
|
+
if mkdir is None or tar is None:
|
|
451
|
+
out.write("copy refused: a pull needs mkdir and tar in a system folder\n")
|
|
452
|
+
return 2
|
|
453
|
+
rt, why = rmt.route(cfg, host)
|
|
454
|
+
if rt is None:
|
|
455
|
+
out.write(f"copy refused: {why}\n")
|
|
456
|
+
return 2
|
|
457
|
+
run.add_remote_roots(san, cfg)
|
|
458
|
+
os.makedirs(cfg.cache_dir, mode=0o700, exist_ok=True)
|
|
459
|
+
code = 0
|
|
460
|
+
for spec in remote_srcs:
|
|
461
|
+
m = _REMOTE.fullmatch(spec)
|
|
462
|
+
assert m is not None
|
|
463
|
+
scratch = tempfile.mkdtemp(prefix="pull-", dir=cfg.cache_dir)
|
|
464
|
+
try:
|
|
465
|
+
argv, fds = confine.gateway_command(
|
|
466
|
+
rt.ssh + [host, "--", rmt.send_script(m.group(2))], [os.path.realpath(scratch)],
|
|
467
|
+
[], rt.net, deny_read=rt.deny_read, socket=rt.socket, allow_read=rt.allow_read)
|
|
468
|
+
errs: List[str] = []
|
|
469
|
+
try:
|
|
470
|
+
ssh = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
|
|
471
|
+
stderr=subprocess.PIPE, env=dict(env, TMPDIR=scratch),
|
|
472
|
+
cwd="/", start_new_session=True, close_fds=True,
|
|
473
|
+
pass_fds=fds)
|
|
474
|
+
finally:
|
|
475
|
+
for fd in fds:
|
|
476
|
+
os.close(fd)
|
|
477
|
+
|
|
478
|
+
def read_errors() -> None:
|
|
479
|
+
assert ssh.stderr is not None
|
|
480
|
+
for raw in iter(lambda: ssh.stderr.readline(65536), b""):
|
|
481
|
+
if len(errs) < 50:
|
|
482
|
+
errs.append(raw.decode("utf-8", "replace").rstrip("\r\n"))
|
|
483
|
+
|
|
484
|
+
import threading
|
|
485
|
+
t = threading.Thread(target=read_errors, daemon=True)
|
|
486
|
+
t.start()
|
|
487
|
+
|
|
488
|
+
def relay(stdin) -> None: # the stream, from ssh's output into the local tar
|
|
489
|
+
assert ssh.stdout is not None
|
|
490
|
+
shutil.copyfileobj(ssh.stdout, stdin, 1 << 20)
|
|
491
|
+
|
|
492
|
+
extract = [sys.executable, "-I", "-c", rmt.EXTRACT_PY, dest]
|
|
493
|
+
try:
|
|
494
|
+
c = run.run_confined(extract, cfg, san, [place], False, out, label="copy",
|
|
495
|
+
env=dict(env, PATH="/usr/bin:/bin"), cwd=cwd,
|
|
496
|
+
cancelled=cancelled, deny_read=run.gateway_hidden(cfg),
|
|
497
|
+
stdin_feed=relay, quiet=True)
|
|
498
|
+
finally:
|
|
499
|
+
# the extraction ended (done, refused a write, cancelled): ssh must not wait on
|
|
500
|
+
# a pipe nobody reads. It is our own child, in its own
|
|
501
|
+
# session: its process group is ours to end
|
|
502
|
+
try:
|
|
503
|
+
ssh.stdout.close() # type: ignore[union-attr]
|
|
504
|
+
except OSError:
|
|
505
|
+
pass
|
|
506
|
+
try:
|
|
507
|
+
r = ssh.wait(timeout=5)
|
|
508
|
+
except subprocess.TimeoutExpired:
|
|
509
|
+
import signal
|
|
510
|
+
try:
|
|
511
|
+
os.killpg(ssh.pid, signal.SIGKILL)
|
|
512
|
+
except OSError:
|
|
513
|
+
pass
|
|
514
|
+
r = ssh.wait()
|
|
515
|
+
t.join(timeout=10)
|
|
516
|
+
if errs:
|
|
517
|
+
# the remote tar names members relative to the pulled folder; no count either
|
|
518
|
+
out.write("copy: message lines from the remote withheld (they can name files)\n")
|
|
519
|
+
raw = code or c or r
|
|
520
|
+
run._log(f"pull: exit {raw}")
|
|
521
|
+
code = 0 if raw == 0 else 1 # the agent sees success or failure only
|
|
522
|
+
finally:
|
|
523
|
+
safeio.remove_tree(scratch)
|
|
524
|
+
return code
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
def main(argv: List[str], out: TextIO = sys.stdout) -> int:
|
|
528
|
+
"""The client: the request goes to the broker, which runs it outside the agent's sandbox."""
|
|
529
|
+
if argv[:1] in (["-h"], ["--help"]):
|
|
530
|
+
out.write(HELP)
|
|
531
|
+
return 0
|
|
532
|
+
from phiward import broker
|
|
533
|
+
return broker.client("copy", list(argv), out)
|
phiward/core.py
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
"""The normalized action, the decision, and the dispatcher that runs every enabled guard."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Callable, Dict, List, Optional, Tuple
|
|
5
|
+
|
|
6
|
+
# Kinds of action an adapter can report.
|
|
7
|
+
SHELL = "shell"
|
|
8
|
+
FILE_READ = "file_read"
|
|
9
|
+
FILE_SEARCH = "file_search"
|
|
10
|
+
FILE_WRITE = "file_write"
|
|
11
|
+
OTHER = "other" # any other tool (MCP and the like): only its text is checked
|
|
12
|
+
|
|
13
|
+
ALLOW, ASK, DENY = "allow", "ask", "deny"
|
|
14
|
+
_RANK = {ALLOW: 0, ASK: 1, DENY: 2}
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass(frozen=True)
|
|
18
|
+
class Action:
|
|
19
|
+
"""What an agent tool is about to do, in a form every guard understands.
|
|
20
|
+
|
|
21
|
+
`paths` are the paths a file tool names, as given (the guard resolves them against `cwd`).
|
|
22
|
+
`text` is every other string in the tool's input, for tools the core does not know.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
kind: str
|
|
26
|
+
cwd: str
|
|
27
|
+
command: str = ""
|
|
28
|
+
paths: Tuple[str, ...] = ()
|
|
29
|
+
text: Tuple[str, ...] = ()
|
|
30
|
+
tool: str = ""
|
|
31
|
+
# Whether the tool can show an "ask" prompt to the operator for this action. An adapter
|
|
32
|
+
# sets it False when the tool has no ask reply or runs in a mode that skips prompts.
|
|
33
|
+
can_ask: bool = True
|
|
34
|
+
# Whether the tool's shell commands run with the protected roots denied by the kernel
|
|
35
|
+
# (Claude Code's sandbox). The shell text guard then refuses less: the kernel is the
|
|
36
|
+
# boundary. File tools are never covered by a shell sandbox.
|
|
37
|
+
confined: bool = False
|
|
38
|
+
# why the shell is not confined, as the confinement check says it (the refusal names it)
|
|
39
|
+
unconfined_why: str = ""
|
|
40
|
+
unconfined_step: str = ""
|
|
41
|
+
# For a shell tool other than Bash and Monitor: why its input is not the one exact form of
|
|
42
|
+
# a command (adapters/claude.exact_command), or "" when it is
|
|
43
|
+
shape: str = ""
|
|
44
|
+
# an MCP tool of a remote server (it runs nothing on this machine): only its text is checked
|
|
45
|
+
remote: bool = False
|
|
46
|
+
# an app tool that starts the project's own code outside the sandbox (the preview server, a
|
|
47
|
+
# build): what it starts, for the prompt or the refusal; "" for any other tool
|
|
48
|
+
starts: str = ""
|
|
49
|
+
# paths a tool names by its path fields (`adapters/claude._named_paths`): judged as a
|
|
50
|
+
# search, in addition to every other check of the action (it can only add a refusal)
|
|
51
|
+
searches: Tuple[str, ...] = ()
|
|
52
|
+
# For such a tool: what the refusal tells the agent to do instead (it depends on the server)
|
|
53
|
+
advice: str = ""
|
|
54
|
+
# Claude Code's own payload (not Copilot's): its file tools' writes are held to the folders
|
|
55
|
+
# its sandbox lets the shell write
|
|
56
|
+
claude_code: bool = False
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class Decision:
|
|
61
|
+
verdict: str
|
|
62
|
+
reason: str = ""
|
|
63
|
+
guard: str = ""
|
|
64
|
+
|
|
65
|
+
@property
|
|
66
|
+
def allowed(self) -> bool:
|
|
67
|
+
return self.verdict == ALLOW
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
ALLOWED = Decision(ALLOW)
|
|
71
|
+
|
|
72
|
+
Guard = Callable[[Action, "object"], Decision]
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def strictest(decisions: List[Decision]) -> Decision:
|
|
76
|
+
"""The strictest of several decisions: deny over ask over allow. The first one wins a tie."""
|
|
77
|
+
best: Optional[Decision] = None
|
|
78
|
+
for d in decisions:
|
|
79
|
+
if best is None or _RANK[d.verdict] > _RANK[best.verdict]:
|
|
80
|
+
best = d
|
|
81
|
+
return best or ALLOWED
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def settle(decision: Decision, action: Action) -> Decision:
|
|
85
|
+
"""An ask the tool cannot show becomes a deny, so it never turns into a silent allow."""
|
|
86
|
+
if decision.verdict == ASK and not action.can_ask:
|
|
87
|
+
return Decision(DENY, decision.reason + " (This tool cannot ask here, so it is refused.)",
|
|
88
|
+
decision.guard)
|
|
89
|
+
return decision
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def dispatch(action: Action, config, guards: Dict[str, Guard]) -> Decision:
|
|
93
|
+
"""Run every guard on the action and return the strictest decision.
|
|
94
|
+
|
|
95
|
+
A guard that raises denies the action (fail closed): a bug must not open a hole.
|
|
96
|
+
"""
|
|
97
|
+
results = []
|
|
98
|
+
for name, guard in guards.items():
|
|
99
|
+
try:
|
|
100
|
+
d = guard(action, config)
|
|
101
|
+
except Exception as exc: # noqa: BLE001 - fail closed on any fault
|
|
102
|
+
d = Decision(DENY, f"The guard '{name}' failed ({type(exc).__name__}), so the action "
|
|
103
|
+
"is refused. Report this as a bug.", name)
|
|
104
|
+
results.append(d)
|
|
105
|
+
return settle(strictest(results), action)
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
## Protected data (phiward)
|
|
2
|
+
|
|
3
|
+
This repository uses phiward. Some folders hold protected data, for example patient data.
|
|
4
|
+
Your tool output goes to a model provider. Protected data must not reach it.
|
|
5
|
+
|
|
6
|
+
Rules:
|
|
7
|
+
|
|
8
|
+
1. Never read a protected path directly. Do not use `cat`, `ls`, `grep`, `find`, `head`, `git`
|
|
9
|
+
or your file tools (Read, Grep, Glob) on a protected path or on a folder above one.
|
|
10
|
+
2. To work with protected data, run `phiward run -- CMD [ARG]...`. Write it as the whole
|
|
11
|
+
command, with the bare name `phiward`. Put nothing before or after it: no `cd`, no
|
|
12
|
+
pipe, no redirect, no `$(...)`. The operator's broker runs the command. If `run` says no
|
|
13
|
+
broker is running, stop and ask the operator to start the broker. The broker
|
|
14
|
+
runs the program from the operator's PATH with its own environment, not yours.
|
|
15
|
+
3. Write analysis scripts that print aggregates: counts, summaries, tables. Do not print raw
|
|
16
|
+
records, sample names or identifiers. The sanitizer masks identifiers. It does not mask
|
|
17
|
+
other content. Draft a script in the project, then ask the operator to read it and move it
|
|
18
|
+
into their scripts folder; after that, run it by its full path:
|
|
19
|
+
`phiward run -- /full/path/NAME.py ARGS`.
|
|
20
|
+
4. To copy protected data, use `phiward copy SRC... DST`. The destination must be
|
|
21
|
+
inside a protected folder or a configured remote.
|
|
22
|
+
5. `run` allows read access and no network. It writes only where the operator granted it:
|
|
23
|
+
`--write-to DIR` and `--net` work only where the operator granted them in the user config
|
|
24
|
+
(`[broker] write_to`, `[broker] net`). Nothing asks the operator at run time: a grant that is
|
|
25
|
+
not in the config is refused. If you need one, stop and ask the operator. Once a config
|
|
26
|
+
exists, never run `phiward setup`, `broker`, `pin` or `carryover`: they are for the operator,
|
|
27
|
+
in their own terminal. The only exception is the guided first setup (`/phiward:setup`),
|
|
28
|
+
before any config exists.
|
|
29
|
+
6. Use `phiward check -- CMD` to see if a command is allowed, before you run it.
|
|
30
|
+
7. For an HPC cluster, do not use `ssh` yourself: your session cannot use the operator's ticket,
|
|
31
|
+
key or connection. Run `phiward run --remote HOST -- CMD [ARG]...`, and move files with
|
|
32
|
+
`phiward copy` to or from the approved remotes. The gateway is the intended route, not a way
|
|
33
|
+
around the guards. Only the hosts
|
|
34
|
+
and programs the operator listed in the user config are allowed, and the output is masked.
|
|
35
|
+
The command is not confined on the cluster: keep it to counts and states.
|
|
36
|
+
|
|
37
|
+
A refusal is a decision, not a fault. Read the reason. Do what it says. Do not try another
|
|
38
|
+
spelling, a link, a nested shell, an encoded command or another tool to read the same data.
|
|
39
|
+
Do not edit settings files, hooks or `.phiward.toml` to remove a guard. Do not use
|
|
40
|
+
`--no-verify`. If the work cannot continue, stop and tell the operator what you need.
|
|
41
|
+
Do not ask the operator to show you protected data either: no `! cat`, no paste, no copy into
|
|
42
|
+
the project, and no change that removes a guard. Offer a gateway command that prints a count or
|
|
43
|
+
a summary instead.
|