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/inventory.py ADDED
@@ -0,0 +1,173 @@
1
+ """The names of every entry under the protected roots, so the sanitizer masks a file however a
2
+ tool spells or wraps its name (`ls` prints bare names, `ls -F` adds `*`, a diff adds `+`).
3
+
4
+ A name gives two strings to mask: the whole name and its stem (the part before the first dot).
5
+ A string is kept when it has 4 or more characters (6 or more when it is only digits) and is not a
6
+ stop word. Each one is masked **wherever it appears in a line**, without regard to letter case;
7
+ spaces inside a name are part of it. Names under 4 characters are not masked (a stated limit).
8
+
9
+ The list is built fresh for each gateway run: every folder is listed again, so a new file is
10
+ masked at once. Only pure results are kept between runs in the broker (each name's mask
11
+ strings, the compiled matcher for a set of names), so nothing stored can go stale or be
12
+ poisoned. The walk is bounded: more than `limit` entries raises
13
+ InventoryError, and the caller fails closed (a cut-off list would leave names unmasked).
14
+ """
15
+
16
+ import os
17
+ import re
18
+ import unicodedata
19
+ from typing import Dict, Iterable, List, Optional, Pattern, Sequence, Set
20
+
21
+ from phiward import pathmatch
22
+
23
+
24
+ class InventoryError(Exception):
25
+ pass
26
+
27
+
28
+ # Terminal escape sequences (CSI, OSC, other ESC forms) and the other control characters except TAB.
29
+ _ESCAPES = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b[@-_]?"
30
+ r"|\x9b[0-?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f-\x9f]")
31
+
32
+
33
+ def normalize(text: str) -> str:
34
+ """Text as masking sees it: escape sequences and control characters removed, an escaped
35
+ space (`\\ `) as a plain space, Unicode in NFKC
36
+ form (full-width and other look-alike letters become plain ones, a decomposed accent is
37
+ composed), format characters (zero-width spaces, direction marks) removed. Lines and entry
38
+ names both go through it, so they meet in the same form."""
39
+ text = _ESCAPES.sub("", text)
40
+ text = text.replace("\\ ", " ") # `ls -b`, `printf %q`: an escaped space is a space
41
+ text = unicodedata.normalize("NFKC", text)
42
+ return "".join(ch for ch in text if unicodedata.category(ch) != "Cf")
43
+
44
+
45
+ def _strings_of(name: str, stop: Set[str]) -> List[str]:
46
+ out = []
47
+ if any(0xDC80 <= ord(c) <= 0xDCFF for c in name):
48
+ # a name that is not valid UTF-8 (Linux): output is decoded with "replace", so mask it
49
+ # in that form too
50
+ name = name.encode("utf-8", "surrogateescape").decode("utf-8", "replace")
51
+ name = normalize(name)
52
+ pieces = [p for p in re.split(r"[\x00-\x1f\x7f]", name) if p]
53
+ if len(pieces) > 1:
54
+ # a name with a line break or a tab: tools print it split, escaped (`\n`) or with `?`,
55
+ # so each piece is masked too
56
+ for p in pieces:
57
+ out += _strings_of(p, stop)
58
+ for t in {name, name.split(".")[0]}:
59
+ f = t.casefold()
60
+ if len(t) < 4 or (t.isdigit() and len(t) < 6) or f in stop or not t.strip():
61
+ continue
62
+ out.append(f)
63
+ if t.lower() != f: # re.IGNORECASE folds simply (it does not turn "ß" into "ss")
64
+ out.append(t.lower())
65
+ return out
66
+
67
+
68
+ # Kept between calls in a long-lived process (the broker):
69
+ # only what cannot go stale. Every folder is listed on every call (that is how a new name is
70
+ # seen; listing is cheap); what is cached is each name's mask strings, a pure function of the
71
+ # name, and the compiled matcher for a set of names. No times, no stamps.
72
+ _NAMES: Dict[str, List[str]] = {}
73
+ _NAMES_MAX = 500_000 # names; cleared when passed
74
+
75
+
76
+ def _strings_cached(name: str, stop: Set[str], skey: int) -> List[str]:
77
+ k = f"{skey}\0{name}"
78
+ got = _NAMES.get(k)
79
+ if got is None:
80
+ if len(_NAMES) > _NAMES_MAX:
81
+ _NAMES.clear()
82
+ got = _strings_of(name, stop)
83
+ _NAMES[k] = got
84
+ return got
85
+
86
+
87
+ def build(roots: Sequence[str], patterns: Sequence[str], limit: int, stop: Set[str]) -> Set[str]:
88
+ found: Set[str] = set()
89
+ count = 0
90
+ skey = hash(frozenset(stop))
91
+ # start folders resolved: a root or pattern match written through a link is listed as the
92
+ # folder it names
93
+ starts = [os.path.realpath(r) for r in roots if os.path.isdir(r)]
94
+ for p in patterns:
95
+ # a name the pattern's last part leaves open is protected too (`phi_*` matches
96
+ # `phi_Doe Jane`); a literal last part (`runs/*/panel`) is pattern text, not a name
97
+ last = pathmatch.parts(p)[-1:]
98
+ named = bool(last and pathmatch.WILD.search(last[0]))
99
+ for m in pathmatch.matches(p):
100
+ if named:
101
+ found.update(_strings_cached(os.path.basename(m), stop, skey))
102
+ if os.path.isdir(m):
103
+ starts.append(os.path.realpath(m))
104
+ for r in roots:
105
+ if os.path.isfile(r):
106
+ found.update(_strings_cached(os.path.basename(r), stop, skey))
107
+ for start in starts:
108
+ todo = [start]
109
+ while todo:
110
+ d = todo.pop()
111
+ try:
112
+ entries = list(os.scandir(d))
113
+ except OSError:
114
+ continue
115
+ count += len(entries)
116
+ if count > limit:
117
+ raise InventoryError(
118
+ f"more than {limit} entries under the protected roots; raise "
119
+ "[sanitize] inventory_limit in the user config, or protect a narrower root")
120
+ for e in entries:
121
+ found.update(_strings_cached(e.name, stop, skey))
122
+ if e.is_dir(follow_symlinks=False):
123
+ todo.append(e.path)
124
+ return found
125
+
126
+
127
+ def _trie_regex(words: Iterable[str]) -> str:
128
+ """One regex that matches any of `words`, as a trie, so a long list stays fast."""
129
+ trie: Dict[str, dict] = {}
130
+ for w in words:
131
+ node = trie
132
+ for ch in w:
133
+ node = node.setdefault(ch, {})
134
+ node[""] = {}
135
+
136
+ def emit(node: Dict[str, dict]) -> str:
137
+ ends = "" in node
138
+ alts = [re.escape(ch) + emit(sub) for ch, sub in sorted(node.items()) if ch]
139
+ if not alts:
140
+ return ""
141
+ body = alts[0] if len(alts) == 1 else "(?:" + "|".join(alts) + ")"
142
+ if ends:
143
+ return "(?:" + body + ")?"
144
+ return body
145
+
146
+ return emit(trie)
147
+
148
+
149
+ _MATCHER: Dict[str, Optional[Pattern[str]]] = {}
150
+
151
+
152
+ def matcher(strings: Iterable[str]) -> Optional[Pattern[str]]:
153
+ words = sorted(set(strings))
154
+ if not words:
155
+ return None
156
+ # compiled once per set of names (compiling is most of the cost for a large root)
157
+ import hashlib
158
+ key = hashlib.sha256("\0".join(words).encode("utf-8", "surrogatepass")).hexdigest()
159
+ got = _MATCHER.get(key) # one look: another worker may clear it between two
160
+ if got is not None:
161
+ return got
162
+ # A trie regex prefers the longest match at each place, because every optional part is
163
+ # greedy; masking the longest name first keeps a stem from leaving the rest of a name.
164
+ rx = re.compile(_trie_regex(words), re.IGNORECASE)
165
+ _MATCHER.clear() # keep only the latest set: memory stays one matcher's worth
166
+ _MATCHER[key] = rx
167
+ return rx
168
+
169
+
170
+ def mask(line: str, rx: Optional[Pattern[str]], placeholder: str = "<ENTRY>") -> str:
171
+ if rx is None:
172
+ return line
173
+ return rx.sub(placeholder, line)
phiward/mcp.py ADDED
@@ -0,0 +1,186 @@
1
+ """`phiward mcp`: phiward's gateway as an MCP server (stdio), for Claude Code and other tools.
2
+
3
+ Tools:
4
+ - `phiward_run(command, write_to?, net?)`: `phiward run -- COMMAND...`, masked output;
5
+ - `phiward_copy(sources, destination, dry_run?)`: `phiward copy`;
6
+ - `phiward_remote(host, command)`: `phiward run --remote HOST -- COMMAND...`;
7
+ - `phiward_check(command)`: what the guard decides for a shell command;
8
+ - `phiward_doctor()`: the setup check.
9
+
10
+ It is a client of the broker, like the `phiward` command: it writes a request into the spool,
11
+ and the broker checks it against the user config, runs it outside the agent, and masks what
12
+ comes back. Nothing here reads protected data. Arguments are lists, so there is no shell and no
13
+ quoting. The working folder of a request is the server's (the project Claude Code started it in).
14
+ """
15
+ # The code uses the standard library only.
16
+
17
+ import io
18
+ import json
19
+ import sys
20
+ from typing import Any, Dict, List, Optional
21
+
22
+ PROTOCOL = "2025-06-18"
23
+
24
+ _STR_LIST = {"type": "array", "items": {"type": "string"}}
25
+ TOOLS: List[Dict[str, Any]] = [
26
+ {"name": "phiward_run",
27
+ "description": ("Run a command on protected data through phiward's gateway. The output is "
28
+ "masked (paths, names and identifiers become placeholders). Print counts "
29
+ "and summaries, never records. `command` is the program and its arguments "
30
+ "as a list (no shell)."),
31
+ "inputSchema": {"type": "object", "required": ["command"],
32
+ "properties": {"command": _STR_LIST,
33
+ "write_to": _STR_LIST,
34
+ "net": {"type": "boolean"}}}},
35
+ {"name": "phiward_copy",
36
+ "description": ("Copy files without printing names: to a protected folder, or to or from an "
37
+ "approved HPC remote (host:/path)."),
38
+ "inputSchema": {"type": "object", "required": ["sources", "destination"],
39
+ "properties": {"sources": _STR_LIST, "destination": {"type": "string"},
40
+ "dry_run": {"type": "boolean"}}}},
41
+ {"name": "phiward_remote",
42
+ "description": ("Run an approved program on an approved HPC host through the operator's "
43
+ "shared SSH connection; the output is masked."),
44
+ "inputSchema": {"type": "object", "required": ["host", "command"],
45
+ "properties": {"host": {"type": "string"}, "command": _STR_LIST}}},
46
+ {"name": "phiward_check",
47
+ "description": "Say whether phiward's guard allows a shell command (allow, ask or deny).",
48
+ "inputSchema": {"type": "object", "required": ["command"],
49
+ "properties": {"command": {"type": "string"}}}},
50
+ {"name": "phiward_doctor",
51
+ "description": "Check phiward's setup for this project: the mode, each layer, warnings.",
52
+ "inputSchema": {"type": "object", "properties": {}}},
53
+ ]
54
+
55
+
56
+ def _strs(v: Any) -> Optional[List[str]]:
57
+ return v if isinstance(v, list) and all(isinstance(x, str) for x in v) else None
58
+
59
+
60
+ def _capture(fn) -> "tuple":
61
+ buf = io.StringIO()
62
+ try:
63
+ code = fn(buf)
64
+ except SystemExit as exc: # a command's main may exit
65
+ code = exc.code if isinstance(exc.code, int) else 1
66
+ except Exception as exc: # noqa: BLE001 - a tool error, never a traceback (it can name paths)
67
+ buf.write(f"phiward failed ({type(exc).__name__})\n")
68
+ code = 3
69
+ return code or 0, buf.getvalue()
70
+
71
+
72
+ def call(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
73
+ from phiward import broker
74
+ code, text = 2, ""
75
+ if name == "phiward_run":
76
+ cmd = _strs(args.get("command"))
77
+ if not cmd:
78
+ text = "phiward_run: `command` must be a non-empty list of strings\n"
79
+ else:
80
+ argv: List[str] = []
81
+ for w in _strs(args.get("write_to")) or []:
82
+ argv += ["--write-to", w]
83
+ if args.get("net") is True:
84
+ argv.append("--net")
85
+ code, text = _capture(lambda out: broker.client("run", argv + ["--"] + cmd, out))
86
+ elif name == "phiward_copy":
87
+ srcs, dst = _strs(args.get("sources")), args.get("destination")
88
+ if not srcs or not isinstance(dst, str):
89
+ text = "phiward_copy: give `sources` (a list) and `destination`\n"
90
+ else:
91
+ argv = (["--dry-run"] if args.get("dry_run") is True else []) + srcs + [dst]
92
+ code, text = _capture(lambda out: broker.client("copy", argv, out))
93
+ elif name == "phiward_remote":
94
+ host, cmd = args.get("host"), _strs(args.get("command"))
95
+ if not isinstance(host, str) or not cmd:
96
+ text = "phiward_remote: give `host` and `command` (a list)\n"
97
+ else:
98
+ code, text = _capture(
99
+ lambda out: broker.client("run", ["--remote", host, "--"] + cmd, out))
100
+ elif name == "phiward_check":
101
+ command = args.get("command")
102
+ if not isinstance(command, str):
103
+ text = "phiward_check: give `command` (a string)\n"
104
+ else:
105
+ from phiward.adapters import run_check
106
+
107
+ def check(out):
108
+ old = sys.stdout
109
+ sys.stdout = out
110
+ try:
111
+ return run_check(["--", command])
112
+ finally:
113
+ sys.stdout = old
114
+ code, text = _capture(check)
115
+ elif name == "phiward_doctor":
116
+ from phiward import doctor
117
+
118
+ def doc(out):
119
+ old = sys.stdout
120
+ sys.stdout = out
121
+ try:
122
+ return doctor.main([])
123
+ finally:
124
+ sys.stdout = old
125
+ code, text = _capture(doc)
126
+ else:
127
+ return {"content": [{"type": "text", "text": f"unknown tool: {name}"}], "isError": True}
128
+ return {"content": [{"type": "text", "text": text or f"(exit {code})"}], "isError": code != 0}
129
+
130
+
131
+ def _reply(mid: Any, result: Any = None, error: Optional[Dict[str, Any]] = None) -> None:
132
+ msg: Dict[str, Any] = {"jsonrpc": "2.0", "id": mid}
133
+ if error is not None:
134
+ msg["error"] = error
135
+ else:
136
+ msg["result"] = result
137
+ sys.stdout.write(json.dumps(msg) + "\n")
138
+ sys.stdout.flush()
139
+
140
+
141
+ def main(argv: List[str]) -> int:
142
+ if argv[:1] in (["wrap"], ["unwrap"], ["list"]):
143
+ # the operator's command; with no arguments this is the MCP server (Claude Code starts it)
144
+ from phiward import mcp_config
145
+ return mcp_config.main(argv)
146
+ if argv[:1] in (["-h"], ["--help"]):
147
+ sys.stdout.write("usage: phiward mcp (an MCP server on stdin and stdout)\n"
148
+ " phiward mcp list|wrap|unwrap ... your own MCP servers: see "
149
+ "`phiward mcp list --help`\n\n" + (__doc__ or ""))
150
+ return 0
151
+ if not argv and sys.stdin.isatty():
152
+ # typed in a terminal: this is the server Claude Code starts, not a command for you
153
+ sys.stderr.write("phiward mcp is phiward's own MCP server, which Claude Code starts. To see "
154
+ "and wrap your MCP servers: `phiward mcp list`.\n")
155
+ return 2
156
+ for line in sys.stdin:
157
+ try:
158
+ msg = json.loads(line)
159
+ except ValueError:
160
+ continue
161
+ if not isinstance(msg, dict):
162
+ continue
163
+ method, mid = msg.get("method"), msg.get("id")
164
+ params = msg.get("params") if isinstance(msg.get("params"), dict) else {}
165
+ if method == "initialize":
166
+ _reply(mid, {"protocolVersion": params.get("protocolVersion", PROTOCOL),
167
+ "capabilities": {"tools": {}},
168
+ "serverInfo": {"name": "phiward", "version": _version()}})
169
+ elif method == "tools/list":
170
+ _reply(mid, {"tools": TOOLS})
171
+ elif method == "tools/call":
172
+ args = params.get("arguments") if isinstance(params.get("arguments"), dict) else {}
173
+ _reply(mid, call(str(params.get("name", "")), args))
174
+ elif method == "ping":
175
+ _reply(mid, {})
176
+ elif mid is not None:
177
+ _reply(mid, error={"code": -32601, "message": f"unknown method: {method}"})
178
+ return 0
179
+
180
+
181
+ def _version() -> str:
182
+ try:
183
+ from phiward import __version__
184
+ return __version__
185
+ except ImportError:
186
+ return "0"