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/pin.py ADDED
@@ -0,0 +1,214 @@
1
+ """`phiward pin`: approve the listed programs, and record the derived protected folders, as the
2
+ operator sees them now.
3
+
4
+ Derived roots (the git folders around a root, snapshot folders, other mounts of the same data)
5
+ are worked out from paths the agent may be able to write: a `.git` file planted closer to a root
6
+ would otherwise make the real git folder stop being protected on the next load. `pin` writes the
7
+ derived roots found from the operator's view to `pinned.toml` next to the user config (a guard
8
+ file: the agent cannot write it). Every later load uses the pinned folders and the folders it
9
+ finds, so a planted file can add protection but never remove a pinned folder. `doctor` warns
10
+ when the two differ.
11
+
12
+ It also approves the programs of `[broker] commands`: it lists each one with its path and a mark
13
+ (new, changed, not installed, a link that never runs, cannot be read), and after a yes records
14
+ the content of each. The broker runs only programs whose content is approved, and refuses every
15
+ request while one differs.
16
+
17
+ It runs only on a terminal (the operator's), shows the list, and writes after a yes. `setup`
18
+ pins after it writes the config.
19
+ """
20
+
21
+ import os
22
+ import sys
23
+ from typing import List, Optional, Sequence, TextIO
24
+
25
+ from phiward import config
26
+
27
+ USAGE = ("Approve the programs of [broker] commands as they are now (the broker runs only "
28
+ "approved ones),\nand pin the folders phiward found that hold copies of protected data; "
29
+ "then restart the broker.\nRun it in your own terminal after you change a listed "
30
+ "program or add a script to your scripts folder.\nusage: phiward pin\n")
31
+
32
+
33
+ def pins_path(env: Optional[dict] = None) -> str:
34
+ return os.path.join(os.path.dirname(config.user_config_path(env)), "pinned.toml")
35
+
36
+
37
+ def pinnable(cfg: config.Config) -> List[str]:
38
+ """The derived roots worth pinning: all but the cache folder (always derived)."""
39
+ return [d for d in (cfg.found_derived or cfg.derived_roots) if d != cfg.cache_dir]
40
+
41
+
42
+ def read_pins(env: Optional[dict] = None) -> List[str]:
43
+ from phiward import _toml
44
+ path = pins_path(env)
45
+ if not os.path.isfile(path):
46
+ return []
47
+ try:
48
+ raw, _ = _toml.load_file(path)
49
+ except Exception: # noqa: BLE001 - a bad file pins nothing; doctor reports it
50
+ return []
51
+ v = raw.get("pinned", {}).get("derived", []) if isinstance(raw, dict) else []
52
+ return [x for x in v if isinstance(x, str) and x.startswith("/")]
53
+
54
+
55
+ def program_record(cfg: config.Config, path: Optional[str] = None) -> List[str]:
56
+ """The programs `[broker] commands` allows, as the broker finds them now, each as
57
+ "sha256 path" (content, not just the name): what the operator approves with `pin`. `path`:
58
+ the PATH to find bare names on (the broker passes its own); else the running broker's."""
59
+ import hashlib
60
+ from phiward import broker
61
+ out: List[str] = []
62
+ for prog in broker.listed_programs(cfg, broker.program_path() if path is None else path):
63
+ if prog.startswith(("too-many:", "missing:", "linked:")):
64
+ out.append(f"{prog.split(':', 1)[0]} {prog.split(':', 1)[1]}")
65
+ continue
66
+ try:
67
+ with open(prog, "rb") as fh:
68
+ h = hashlib.sha256()
69
+ for chunk in iter(lambda: fh.read(1 << 20), b""):
70
+ h.update(chunk)
71
+ out.append(f"{h.hexdigest()} {prog}")
72
+ except OSError:
73
+ # there but not readable (mode 0111): its content cannot be approved, so it never
74
+ # is (a "missing" line would equal itself whatever the file holds)
75
+ out.append(f"{'unreadable' if os.path.lexists(prog) else 'missing'} {prog}")
76
+ return sorted(set(out))
77
+
78
+
79
+ def read_approved(env: Optional[dict] = None) -> List[str]:
80
+ from phiward import _toml
81
+ try:
82
+ raw, _ = _toml.load_file(pins_path(env))
83
+ except Exception: # noqa: BLE001 - nothing approved
84
+ return []
85
+ v = raw.get("programs", {}).get("approved", []) if isinstance(raw, dict) else []
86
+ return [x for x in v if isinstance(x, str)]
87
+
88
+
89
+ def unapproved(cfg: config.Config, env: Optional[dict] = None,
90
+ path: Optional[str] = None) -> List[str]:
91
+ """The listed programs that differ from what the operator approved (empty without a list).
92
+ A program too large to check, or one that cannot be read, is never approved."""
93
+ if not cfg.command_lists:
94
+ return []
95
+ have = set(read_approved(env))
96
+ return [r.split(" ", 1)[1] for r in program_record(cfg, path)
97
+ if r not in have or r.startswith(("too-many ", "unreadable ", "linked "))]
98
+
99
+
100
+ def describe(cfg: config.Config, env: Optional[dict] = None) -> List[str]:
101
+ """The listed programs as `pin` and `doctor` show them: each marked (new), (changed),
102
+ (not installed) or (folder too large to check)."""
103
+ have = read_approved(env)
104
+ by_path = {r.split(" ", 1)[1]: r for r in have}
105
+ out = []
106
+ for r in program_record(cfg):
107
+ kind, path = r.split(" ", 1)
108
+ if kind == "too-many":
109
+ mark = " (folder too large to check: list fewer files)"
110
+ elif kind == "missing":
111
+ mark = " (not installed)"
112
+ elif kind == "linked":
113
+ mark = " (a link: never runs; list it by its name, or list its folder)"
114
+ elif kind == "unreadable":
115
+ mark = " (cannot be read: never approved)"
116
+ elif r in have:
117
+ mark = ""
118
+ elif path in by_path:
119
+ mark = " (changed)"
120
+ else:
121
+ mark = " (new)"
122
+ out.append(_shown_path(path) + mark)
123
+ return out
124
+
125
+
126
+ def _shown_path(path: str) -> str:
127
+ """A path as `pin`, `setup` and `doctor` print it: control characters written as `\\xNN`, so
128
+ a file name cannot steer the terminal or look like another path."""
129
+ import re
130
+ return re.sub(r"[\x00-\x1f\x7f-\x9f]", lambda m: "\\x%02x" % ord(m.group()), path)
131
+
132
+
133
+ def pins_readable(env: Optional[dict] = None) -> bool:
134
+ from phiward import _toml
135
+ try:
136
+ _toml.load_file(pins_path(env))
137
+ return True
138
+ except Exception: # noqa: BLE001
139
+ return False
140
+
141
+
142
+ def write_pins(cfg: config.Config, env: Optional[dict] = None, add: Sequence[str] = (),
143
+ drop: Sequence[str] = (), approve: bool = True) -> int:
144
+ """Pin what is found now, keep what was pinned, plus `add`, minus `drop`."""
145
+ from phiward.setup_cmd import _value
146
+ path = pins_path(env)
147
+ items = sorted((set(pinnable(cfg)) | set(read_pins(env)) | set(add)) - set(drop))
148
+ text = ("# Derived protected folders pinned by `phiward pin` (the agent cannot write\n"
149
+ "# this file). Every load protects these, as well as what it finds itself.\n\n"
150
+ f"[pinned]\nderived = {_value(items)}\n")
151
+ # the listed programs as they are now, or (approve=False) the approvals made before
152
+ progs = program_record(cfg) if approve else read_approved(env)
153
+ if progs:
154
+ text += ("\n# The programs [broker] commands allows, as approved: the broker runs no "
155
+ "listed\n# program whose content differs.\n"
156
+ f"[programs]\napproved = {_value(progs)}\n")
157
+ os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
158
+ from phiward import safeio
159
+ safeio.write_new(path, text)
160
+ return 0
161
+
162
+
163
+ def main(argv: List[str], fin: Optional[TextIO] = None, fout: Optional[TextIO] = None) -> int:
164
+ fin = sys.stdin if fin is None else fin
165
+ fout = sys.stdout if fout is None else fout
166
+ if argv[:1] in (["-h"], ["--help"]):
167
+ fout.write(USAGE + "\n" + (__doc__ or ""))
168
+ return 0
169
+ if argv:
170
+ sys.stderr.write(USAGE)
171
+ return 2
172
+ try:
173
+ tty = fin.isatty() and fout.isatty()
174
+ except (AttributeError, ValueError):
175
+ tty = False
176
+ if not tty:
177
+ sys.stderr.write("phiward pin asks for a yes: run it in your own terminal, not "
178
+ "through an agent tool. Nothing was written.\n")
179
+ return 2
180
+ cfg = config.load(os.getcwd())
181
+ if cfg.problem:
182
+ fout.write(f"pin refused: the config cannot be used: {cfg.problem}\n")
183
+ return 3
184
+ found = set(pinnable(cfg))
185
+ items = sorted(found | set(read_pins()))
186
+ fout.write(f"Derived protected folders to pin ({len(items)}):\n")
187
+ for k, d in enumerate(items, 1):
188
+ mark = "" if d in found else " (pinned before, not found now)"
189
+ fout.write(f" {k}. {d}{mark}\n")
190
+ fout.write("Numbers to drop (for example 2 5), or an empty line to keep all: ")
191
+ fout.flush()
192
+ drop: List[str] = []
193
+ for w in fin.readline().split():
194
+ if w.isdigit() and 1 <= int(w) <= len(items):
195
+ drop.append(items[int(w) - 1])
196
+ progs = program_record(cfg)
197
+ if progs:
198
+ lines = describe(cfg)
199
+ missing = sum(1 for x in lines if x.endswith("(not installed)"))
200
+ fout.write("Programs of [broker] commands to approve as they are now "
201
+ f"({len(lines) - missing} found, {missing} not installed here):\n")
202
+ for line in lines:
203
+ if not line.endswith("(not installed)"):
204
+ fout.write(f" {line}\n")
205
+ fout.write(f"Write {len(items) - len(drop)} pin(s)" + (" and the programs" if progs else "")
206
+ + f" to {pins_path()}? [y/N] ")
207
+ fout.flush()
208
+ if fin.readline().strip().lower() not in ("y", "yes"):
209
+ fout.write("Nothing was written.\n")
210
+ return 1
211
+ write_pins(cfg, drop=drop)
212
+ from phiward import broker
213
+ fout.write(f"Pinned. Restart the broker so it uses them: {broker.restart_hint()}.\n")
214
+ return 0
phiward/procinfo.py ADDED
@@ -0,0 +1,73 @@
1
+ """A process's parent and start time, without starting a program: Linux reads `/proc/<pid>/stat`,
2
+ macOS asks the kernel (`proc_pidinfo`, the call `ps` makes). The start time tells a live process
3
+ from a later one that got the same number. None when it cannot tell: callers then trust
4
+ nothing."""
5
+
6
+ import os
7
+ import sys
8
+ from typing import List, Optional, Tuple
9
+
10
+ # (parent pid, start time in the system's own unit)
11
+ Info = Tuple[int, int]
12
+
13
+
14
+ def _linux(pid: int) -> Optional[Info]:
15
+ try:
16
+ with open(f"/proc/{pid}/stat", "rb") as fh:
17
+ data = fh.read().decode("ascii", "replace")
18
+ except OSError:
19
+ return None
20
+ # the name (field 2) may hold spaces and parentheses: the fields after it follow the last ')'
21
+ rest = data[data.rfind(")") + 2:].split()
22
+ try:
23
+ return int(rest[1]), int(rest[19]) # field 4 ppid, field 22 starttime
24
+ except (IndexError, ValueError):
25
+ return None
26
+
27
+
28
+ _PROC_PIDTBSDINFO = 3
29
+ _BSDINFO_SIZE = 136 # struct proc_bsdinfo
30
+
31
+
32
+ def _darwin(pid: int) -> Optional[Info]:
33
+ import ctypes
34
+ import struct
35
+ try:
36
+ lib = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
37
+ except OSError:
38
+ return None
39
+ buf = ctypes.create_string_buffer(_BSDINFO_SIZE)
40
+ n = lib.proc_pidinfo(ctypes.c_int(pid), ctypes.c_int(_PROC_PIDTBSDINFO), ctypes.c_uint64(0),
41
+ buf, ctypes.c_int(_BSDINFO_SIZE))
42
+ if n != _BSDINFO_SIZE:
43
+ return None
44
+ got_pid, ppid = struct.unpack_from("=II", buf.raw, 12)
45
+ sec, usec = struct.unpack_from("=QQ", buf.raw, 120)
46
+ if got_pid != pid:
47
+ return None
48
+ return int(ppid), int(sec) * 1_000_000 + int(usec)
49
+
50
+
51
+ def info(pid: int) -> Optional[Info]:
52
+ """(parent pid, start time) of a live process, or None."""
53
+ if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
54
+ return None
55
+ if sys.platform.startswith("linux"):
56
+ return _linux(pid)
57
+ if sys.platform == "darwin":
58
+ return _darwin(pid)
59
+ return None
60
+
61
+
62
+ def ancestors(pid: Optional[int] = None, depth: int = 4) -> List[int]:
63
+ """The parent, grandparent, ... of `pid` (this process by default), nearest first, at most
64
+ `depth`, never pid 1 (every orphan's parent) or 0."""
65
+ out: List[int] = []
66
+ cur = os.getpid() if pid is None else pid
67
+ for _ in range(depth):
68
+ got = info(cur)
69
+ if got is None or got[0] <= 1:
70
+ break
71
+ cur = got[0]
72
+ out.append(cur)
73
+ return out