hermes-agent/tests/install/e2e-assets/verify-plugin-preservation.py

320 lines
13 KiB
Python

#!/usr/bin/env python3
"""Plugin upgrade-preservation verifier (Hermes release-harness hook).
Standalone and stdlib-only. Snapshot/verify are read-only against the home;
the explicit seed command creates controlled fixtures in a disposable home.
snapshot walk every plugin tree of a HERMES_HOME (the active home's
``plugins/**`` plus each ``profiles/<name>/plugins/**`` tree,
overridable with --profiles-dir) and record, per entry —
including EMPTY DIRECTORIES and the tree roots themselves —
kind (file/dir/symlink/junction), byte size + sha256 for
regular files, link target, and a recursive fingerprint of a
symlink's external target (so an externally-owned sidecar
witness file cannot be tampered with unnoticed) -> JSON file.
verify re-walk the same home and diff against a snapshot. FAILS
(exit 1) on any deleted or modified entry. New entries are
reported but do not fail: an upgrade may add files; it may
not take yours away or alter them.
Unreadable paths are a hard error (exit 2), never a silent skip: a
scanner that cannot see a file cannot defend it. The verifier never
creates, deletes or writes anything under the scanned home.
Usage:
python verify-plugin-preservation.py snapshot --home <HERMES_HOME> --out snap.json
python verify-plugin-preservation.py verify --home <HERMES_HOME> --snapshot snap.json [--report r.json]
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import stat
import sys
from pathlib import Path
SCHEMA_VERSION = 2
PROFILES_DIR = "profiles"
PLUGIN_ROOT = "plugins"
CHUNK = 1 << 20
# Upper bound for the recursive fingerprint of a symlink's external target:
# the harness points links at small controlled fixtures, but a stray link at
# a huge tree must not explode the snapshot.
MAX_EXTERNAL_ENTRIES = 10000
class ScanError(Exception):
pass
def _sha256_file(path: str) -> str:
h = hashlib.sha256()
with open(path, "rb") as fh:
while True:
block = fh.read(CHUNK)
if not block:
break
h.update(block)
return h.hexdigest()
def _is_link(path: str) -> bool:
"""True for symlinks everywhere, and for NTFS junctions on Windows
(st.islink() is False for junctions, but readlink() works). POSIX
behavior is untouched: FILE_ATTRIBUTE_REPARSE_POINT only exists on NT."""
if os.path.islink(path):
return True
st = os.lstat(path)
reparse = getattr(st, "st_file_attributes", 0)
return bool(reparse & stat.FILE_ATTRIBUTE_REPARSE_POINT)
def _lstat_exists(path: str) -> bool:
"""Exists including dangling symlinks/junctions (os.path.exists hides
those by resolving)."""
try:
os.lstat(path)
return True
except FileNotFoundError:
return False
def plugin_roots(home: str, profiles_dir: str | None = None) -> list[str]:
"""Every plugin tree that must survive an upgrade: the active home's
plugins/ root plus each profile's plugins/ root (found under
profiles_dir, default <home>/profiles). Roots are detected with lstat so
a root that is itself a (possibly dangling) symlink is still scanned and
fingerprinted. Returns stable "<home>/..." labels for existing roots."""
roots: list[str] = []
if _lstat_exists(os.path.join(home, PLUGIN_ROOT)):
roots.append("<home>/" + PLUGIN_ROOT)
profiles = profiles_dir or os.path.join(home, PROFILES_DIR)
if os.path.isdir(profiles):
for name in sorted(os.listdir(profiles)):
p_root = os.path.join(profiles, name, PLUGIN_ROOT)
if _lstat_exists(p_root):
label = os.path.relpath(p_root, home).replace(os.sep, "/")
roots.append("<home>/" + label)
return roots
def _fingerprint_tree(root: str, budget: list[int]) -> dict:
"""Recursive content fingerprint of a directory (used for the EXTERNAL
target of a plugin-runtime symlink: the sidecar witness is owned outside
the home, so its content must be hashed here, not just listed)."""
out: dict[str, dict] = {}
def _on_walk_error(exc: OSError) -> None:
raise ScanError(f"unreadable under {root}: {exc}") from exc
for dirpath, dirnames, filenames in os.walk(root, onerror=_on_walk_error):
dirnames.sort()
for name in sorted(dirnames) + sorted(filenames):
if budget[0] <= 0:
raise ScanError(f"external target too large to fingerprint: {root}")
budget[0] -= 1
abs_path = os.path.join(dirpath, name)
rel = os.path.relpath(abs_path, root).replace(os.sep, "/")
if _is_link(abs_path):
out[rel] = {"kind": "symlink", "target": os.readlink(abs_path)}
elif os.path.isdir(abs_path):
out[rel] = {"kind": "dir"}
elif os.path.isfile(abs_path):
st = os.lstat(abs_path)
out[rel] = {"kind": "file", "size": st.st_size,
"sha256": _sha256_file(abs_path)}
else:
out[rel] = {"kind": "other"}
return out
def _entry_record(abs_path: str) -> dict:
if _is_link(abs_path):
rec: dict = {"kind": "symlink", "target": os.readlink(abs_path)}
resolved = os.path.realpath(abs_path)
rec["target_resolves"] = os.path.exists(resolved)
if rec["target_resolves"]:
if os.path.isfile(resolved):
rec["target_kind"] = "file"
rec["target_sha256"] = _sha256_file(resolved)
elif os.path.isdir(resolved):
rec["target_kind"] = "dir"
rec["target_tree"] = _fingerprint_tree(resolved, [MAX_EXTERNAL_ENTRIES])
return rec
if os.path.isdir(abs_path):
return {"kind": "dir"}
if os.path.isfile(abs_path):
st = os.lstat(abs_path)
return {"kind": "file", "size": st.st_size, "sha256": _sha256_file(abs_path)}
return {"kind": "other"}
def snapshot_home(home: str, profiles_dir: str | None = None) -> dict:
home = os.path.abspath(home)
roots = plugin_roots(home, profiles_dir)
entries: dict[str, dict] = {}
for root_label in roots:
root = os.path.join(home, root_label[len("<home>/"):].replace("/", os.sep))
# The root itself is an entry: if it is a symlink its identity and
# target are recorded; if a plain dir it anchors empty-dir coverage.
entries[root_label[len("<home>/"):]] = _entry_record(root)
if _is_link(root):
continue # walking through it would double-record its target
def _on_walk_error(exc: OSError) -> None:
raise ScanError(f"unreadable under {root}: {exc}") from exc
for dirpath, dirnames, filenames in os.walk(root, followlinks=False,
onerror=_on_walk_error):
dirnames.sort()
for name in sorted(dirnames) + sorted(filenames):
abs_path = os.path.join(dirpath, name)
rel = os.path.relpath(abs_path, home).replace(os.sep, "/")
entries[rel] = _entry_record(abs_path)
dirnames[:] = [name for name in dirnames if not _is_link(os.path.join(dirpath, name))]
return {
"schema": SCHEMA_VERSION,
"home": home,
"roots": roots,
"entries": entries,
}
def verify_home(home: str, snap: dict) -> dict:
home = os.path.abspath(home)
now = snapshot_home(home, snap.get("_profiles_dir"))["entries"]
before = snap["entries"]
deleted = sorted(set(before) - set(now))
added = sorted(set(now) - set(before))
modified = {}
for key in sorted(set(before) & set(now)):
if before[key] != now[key]:
modified[key] = {"before": before[key], "after": now[key]}
return {
"schema": SCHEMA_VERSION,
"home": home,
"snapshot_roots": snap["roots"],
"counts": {
"before": len(before),
"after": len(now),
"deleted": len(deleted),
"modified": len(modified),
"added": len(added),
},
"deleted": deleted,
"modified": modified,
"added": added,
"ok": not deleted and not modified,
}
def seed_fixtures(home: Path, external: Path) -> None:
"""Only create fresh fixtures; retries must not repair damaged witnesses."""
wrapper = home / "plugins/mnemosyne-wrapper"
profile = home / "profiles/e2e-preserve/plugins/second-plugin"
for path in (wrapper, profile, external):
if os.path.lexists(path):
raise FileExistsError(f"refusing to replace preservation fixture: {path}")
for path in (wrapper, profile, external):
path.mkdir(parents=True)
(wrapper / "mnemosyne-wrapper.json").write_text(
'{"wrapper":true,"marker":"mnemosyne-wrapper","owner":"e2e-preservation"}\n', encoding="utf-8")
(wrapper / "plugin.py").write_text('# directory wrapper fixture: no dependencies\n', encoding="utf-8")
(profile / "marker.json").write_text('{"plugin":"second-plugin"}\n', encoding="utf-8")
(profile / "data.bin").write_bytes(b"profile-plugin-bytes\n")
(external / "sidecar-witness.txt").write_text("external-sidecar-witness-v1\n", encoding="utf-8")
(external / "engine.bin").write_bytes(b"\x00\x01\x02external-engine\n")
if os.name == "nt":
import _winapi
_winapi.CreateJunction(str(external.resolve()), str(wrapper / "runtime"))
else:
(wrapper / "runtime").symlink_to(external.resolve(), target_is_directory=True)
def main(argv: list[str] | None = None) -> int:
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
sub = ap.add_subparsers(dest="mode", required=True)
p_seed = sub.add_parser("seed", help="create fresh controlled fixtures in a disposable home")
p_seed.add_argument("--home", required=True)
p_seed.add_argument("--external", required=True)
p_snap = sub.add_parser("snapshot", help="record plugin-tree state to JSON")
p_snap.add_argument("--home", required=True)
p_snap.add_argument("--out", required=True)
p_snap.add_argument("--profiles-dir",
help="override the profiles root (default <home>/profiles)")
p_ver = sub.add_parser("verify", help="compare current state to a snapshot")
p_ver.add_argument("--home", required=True)
p_ver.add_argument("--snapshot", required=True)
p_ver.add_argument("--profiles-dir")
p_ver.add_argument("--report")
args = ap.parse_args(argv)
if args.mode == "seed":
seed_fixtures(Path(args.home), Path(args.external))
return 0
if not os.path.isdir(os.path.abspath(args.home)):
print(f"error: --home is not a directory: {args.home}", file=sys.stderr)
return 2
if args.mode == "snapshot":
try:
snap = snapshot_home(args.home, args.profiles_dir)
except (OSError, ScanError) as exc:
print(f"snapshot failed: {exc}", file=sys.stderr)
return 2
if not snap["entries"]:
print("snapshot INCONCLUSIVE: ZERO entries", file=sys.stderr)
return 3
if args.profiles_dir:
snap["_profiles_dir"] = args.profiles_dir
with open(args.out, "w", encoding="utf-8") as fh:
json.dump(snap, fh, indent=2, sort_keys=True)
print(
f"snapshot: {len(snap['entries'])} entries across "
f"{len(snap['roots'])} plugin root(s) -> {args.out}"
)
return 0
with open(args.snapshot, "r", encoding="utf-8") as fh:
snap = json.load(fh)
if args.profiles_dir:
snap["_profiles_dir"] = args.profiles_dir
try:
report = verify_home(args.home, snap)
except (OSError, ScanError) as exc:
print(f"verify failed: {exc}", file=sys.stderr)
return 2
rendered = json.dumps(report, indent=2, sort_keys=True)
if args.report:
with open(args.report, "w", encoding="utf-8") as fh:
fh.write(rendered)
if not snap["entries"]:
print(
"PLUGIN PRESERVATION INCONCLUSIVE: the snapshot is empty; "
"refusing to claim preservation over zero recorded entries.",
file=sys.stderr,
)
return 3
if report["ok"]:
c = report["counts"]
print(
f"plugin preservation OK: {c['before']} entries intact "
f"({c['added']} added, 0 deleted, 0 modified)"
)
return 0
print(rendered, file=sys.stderr)
print(
"PLUGIN PRESERVATION FAILED: "
f"{report['counts']['deleted']} deleted, "
f"{report['counts']['modified']} modified",
file=sys.stderr,
)
return 1
if __name__ == "__main__":
sys.exit(main())