pkgwhy 1.0.0__py3-none-any.whl

pkgwhy/registry/local.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from pkgwhy.core.models import RegistryConfig, RegistryEntry, RegistryIndex
+
+CONFIG_ENV_VAR = "PKGWHY_CONFIG_HOME"
+CONFIG_FILENAME = "registries.json"
+REGISTRY_INDEX_FILENAME = "pkgwhy-registry.json"
+DEFAULT_REGISTRY_NAME = "local"
+
+
+def config_dir() -> Path:
+    override = os.environ.get(CONFIG_ENV_VAR)
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / "pkgwhy"
+    elif sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "pkgwhy"
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config_home:
+        return Path(xdg_config_home) / "pkgwhy"
+    return Path.home() / ".config" / "pkgwhy"
+
+
+def config_path() -> Path:
+    return config_dir() / CONFIG_FILENAME
+
+
+def registry_index_path(path: Path) -> Path:
+    return path / REGISTRY_INDEX_FILENAME
+
+
+def load_registry_index(path: Path, *, strict: bool = False) -> RegistryIndex:
+    target = registry_index_path(path)
+    if not target.exists():
+        if strict:
+            raise ValueError(f"Registry index not found: {target}")
+        return RegistryIndex()
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+        return RegistryIndex.model_validate(data)
+    except (OSError, json.JSONDecodeError, ValidationError) as exc:
+        if strict:
+            raise ValueError(f"Could not read registry index: {target}") from exc
+        return RegistryIndex()
+
+
+def save_registry_index(path: Path, index: RegistryIndex) -> None:
+    target = registry_index_path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    content = json.dumps(index.model_dump(mode="json"), indent=2, sort_keys=True) + "\n"
+    _atomic_write_text(target, content)
+
+
+def load_registry_config(path: Path | None = None) -> RegistryConfig:
+    target = path or config_path()
+    if not target.exists():
+        return RegistryConfig()
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+        return RegistryConfig.model_validate(data)
+    except (OSError, json.JSONDecodeError, ValidationError):
+        return RegistryConfig()
+
+
+def save_registry_config(config: RegistryConfig, path: Path | None = None) -> None:
+    target = path or config_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    content = json.dumps(config.model_dump(mode="json"), indent=2, sort_keys=True) + "\n"
+    _atomic_write_text(target, content)
+
+
+def _atomic_write_text(target: Path, content: str) -> None:
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=target.parent, delete=False) as handle:
+            handle.write(content)
+            temp_path = Path(handle.name)
+        temp_path.replace(target)
+    except Exception:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+        raise
+
+
+def init_local_registry(path: Path, name: str = DEFAULT_REGISTRY_NAME) -> RegistryEntry:
+    registry_path = path.expanduser().resolve()
+    registry_path.mkdir(parents=True, exist_ok=True)
+    index_path = registry_index_path(registry_path)
+    if not index_path.exists():
+        save_registry_index(registry_path, RegistryIndex())
+
+    config = load_registry_config()
+    if name in config.registries and config.registries[name] != str(registry_path):
+        raise ValueError(f"A registry with this name already exists at a different path: {name}")
+    config.registries[name] = str(registry_path)
+    config.current_registry = name
+    save_registry_config(config)
+    return RegistryEntry(name=name, path=registry_path, is_current=True, index_exists=True)
+
+
+def add_registry(name: str, path: Path) -> RegistryEntry:
+    registry_path = path.expanduser().resolve()
+    if not registry_path.is_dir():
+        raise ValueError(f"Registry path does not exist or is not a directory: {registry_path}")
+
+    index_exists = registry_index_path(registry_path).exists()
+    config = load_registry_config()
+    if name in config.registries:
+        raise ValueError(f"A registry with this name already exists: {name}")
+    config.registries[name] = str(registry_path)
+    if config.current_registry is None:
+        config.current_registry = name
+    save_registry_config(config)
+    return RegistryEntry(
+        name=name,
+        path=registry_path,
+        is_current=config.current_registry == name,
+        index_exists=index_exists,
+    )
+
+
+def use_registry(name: str) -> RegistryEntry:
+    config = load_registry_config()
+    registry_path_text = config.registries.get(name)
+    if registry_path_text is None:
+        raise ValueError(f"Registry is not configured: {name}")
+
+    config.current_registry = name
+    save_registry_config(config)
+    registry_path = Path(registry_path_text)
+    return RegistryEntry(
+        name=name,
+        path=registry_path,
+        is_current=True,
+        index_exists=registry_index_path(registry_path).exists(),
+    )
+
+
+def current_registry() -> RegistryEntry:
+    config = load_registry_config()
+    if config.current_registry is None:
+        raise ValueError("No current registry is configured. Run 'pkgwhy registry init <path>' first.")
+    if config.current_registry not in config.registries:
+        raise ValueError(f"Current registry is not configured: {config.current_registry}")
+    registry_path = Path(config.registries[config.current_registry])
+    return RegistryEntry(
+        name=config.current_registry,
+        path=registry_path,
+        is_current=True,
+        index_exists=registry_index_path(registry_path).exists(),
+    )
+
+
+def list_registries() -> list[RegistryEntry]:
+    config = load_registry_config()
+    entries: list[RegistryEntry] = []
+    for name, path_text in sorted(config.registries.items()):
+        registry_path = Path(path_text)
+        entries.append(
+            RegistryEntry(
+                name=name,
+                path=registry_path,
+                is_current=config.current_registry == name,
+                index_exists=registry_index_path(registry_path).exists(),
+            )
+        )
+    return entries

pkgwhy/registry/manifest.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pkgwhy.core.models import ToolAgentPolicy, ToolManifest, ToolSecurityPolicy
+
+MANIFEST_FILENAME = "pkgwhy.toml"
+
+
+def read_tool_manifest(path: Path) -> ToolManifest:
+    manifest_path = path / MANIFEST_FILENAME if path.is_dir() else path
+    try:
+        data = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ValueError(f"Tool manifest not found: {manifest_path}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"Tool manifest is not valid TOML: {manifest_path}") from exc
+    except OSError as exc:
+        raise ValueError(f"Could not read tool manifest: {manifest_path}") from exc
+
+    return parse_tool_manifest_data(data)
+
+
+def parse_tool_manifest_data(data: dict[str, Any]) -> ToolManifest:
+    tool = _required_table(data, "tool")
+    security = _optional_table(data, "security")
+    agent = _optional_table(data, "agent")
+
+    return ToolManifest(
+        name=_required_text(tool, "name"),
+        owner=_required_text(tool, "owner"),
+        version=_required_text(tool, "version"),
+        description=_required_text(tool, "description"),
+        artifact_type=_required_text(tool, "artifact_type"),
+        entrypoint=_required_text(tool, "entrypoint"),
+        python_requires=_optional_text(tool, "python_requires", ">=3.11"),
+        dependencies=_optional_text_list(tool, "dependencies"),
+        declared_permissions=_optional_text_list(tool, "declared_permissions"),
+        security=ToolSecurityPolicy.model_validate(security),
+        agent=ToolAgentPolicy.model_validate(agent),
+    )
+
+
+def _required_table(data: dict[str, Any], key: str) -> dict[str, Any]:
+    table = data.get(key)
+    if not isinstance(table, dict):
+        raise ValueError(f"Tool manifest must include a [{key}] table")
+    return table
+
+
+def _optional_table(data: dict[str, Any], key: str) -> dict[str, Any]:
+    table = data.get(key, {})
+    if not isinstance(table, dict):
+        raise ValueError(f"Tool manifest [{key}] value must be a table")
+    return table
+
+
+def _required_text(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"Tool manifest field is required and must be text: {key}")
+    return value
+
+
+def _optional_text(data: dict[str, Any], key: str, default: str) -> str:
+    value = data.get(key, default)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"Tool manifest field must be text when present: {key}")
+    return value
+
+
+def _optional_text_list(data: dict[str, Any], key: str) -> list[str]:
+    values = data.get(key, [])
+    if not isinstance(values, list) or not all(isinstance(value, str) and value.strip() for value in values):
+        raise ValueError(f"Tool manifest field must be a list of non-empty strings when present: {key}")
+    return values

pkgwhy/registry/publish.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import tarfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pkgwhy.core.models import PublishResult, RegistryToolEntry, ToolArtifactType, ToolManifest
+from pkgwhy.registry.local import current_registry, load_registry_index, save_registry_index
+from pkgwhy.registry.manifest import read_tool_manifest
+
+EXCLUDED_DIRS = {".git", ".hg", ".svn", ".venv", "venv", "__pycache__"}
+
+
+def publish_local_tool(path: Path) -> PublishResult:
+    requested_source = path.expanduser()
+    if requested_source.is_symlink():
+        raise ValueError(f"Publish path must not be a symlink: {requested_source}")
+    source = requested_source.resolve()
+    if not source.exists():
+        raise ValueError(f"Publish path does not exist: {source}")
+
+    registry = current_registry()
+    manifest = _manifest_for_source(source)
+    _ensure_version_is_new(registry.path, manifest)
+    bundle_path = _bundle_path(registry.path, manifest)
+    manifest_path = _manifest_path(registry.path, manifest)
+    bundle_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    _write_bundle(source, bundle_path)
+    sha256 = _sha256_file(bundle_path)
+    manifest_path.write_text(
+        json.dumps(manifest.model_dump(mode="json"), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    _update_index(registry.path, manifest, bundle_path, manifest_path, sha256)
+
+    return PublishResult(
+        manifest=manifest,
+        registry_name=registry.name,
+        registry_path=registry.path,
+        bundle_path=bundle_path,
+        manifest_path=manifest_path,
+        sha256=sha256,
+    )
+
+
+def _manifest_for_source(source: Path) -> ToolManifest:
+    if source.is_file() and source.suffix == ".py":
+        return ToolManifest(
+            name=source.stem,
+            owner="local",
+            version="0.1.0",
+            description="Local Python script published with pkgwhy.",
+            artifact_type=ToolArtifactType.SCRIPT,
+            entrypoint=source.name,
+            declared_permissions=[],
+        )
+    if source.is_dir():
+        return read_tool_manifest(source)
+    raise ValueError("Publish path must be a Python script or a folder with pkgwhy.toml")
+
+
+def _bundle_path(registry_path: Path, manifest: ToolManifest) -> Path:
+    return (
+        registry_path
+        / "bundles"
+        / manifest.owner
+        / manifest.name
+        / manifest.version
+        / f"{manifest.name}-{manifest.version}.tar.gz"
+    )
+
+
+def _manifest_path(registry_path: Path, manifest: ToolManifest) -> Path:
+    return registry_path / "manifests" / manifest.owner / manifest.name / manifest.version / "manifest.json"
+
+
+def _write_bundle(source: Path, bundle_path: Path) -> None:
+    with tarfile.open(bundle_path, "w:gz", dereference=False) as archive:
+        if source.is_file():
+            archive.add(source, arcname=source.name)
+            return
+        for child in sorted(source.rglob("*")):
+            if _should_skip(child):
+                continue
+            if child.is_symlink():
+                raise ValueError(
+                    f"Symlinks are not supported in tool bundles: {child.relative_to(source)}"
+                )
+            archive.add(child, arcname=child.relative_to(source))
+
+
+def _should_skip(path: Path) -> bool:
+    return any(part in EXCLUDED_DIRS for part in path.parts)
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _update_index(
+    registry_path: Path,
+    manifest: ToolManifest,
+    bundle_path: Path,
+    manifest_path: Path,
+    sha256: str,
+) -> None:
+    index = load_registry_index(registry_path, strict=True)
+    published_at = datetime.now(tz=UTC).isoformat()
+    entry = RegistryToolEntry(
+        name=manifest.name,
+        owner=manifest.owner,
+        version=manifest.version,
+        artifact_type=manifest.artifact_type,
+        entrypoint=manifest.entrypoint,
+        bundle_path=str(bundle_path.relative_to(registry_path)),
+        sha256=sha256,
+        manifest_path=str(manifest_path.relative_to(registry_path)),
+        published_at=published_at,
+    )
+    index.tools.append(entry)
+    save_registry_index(registry_path, index)
+
+
+def _ensure_version_is_new(registry_path: Path, manifest: ToolManifest) -> None:
+    index = load_registry_index(registry_path, strict=True)
+    for existing in index.tools:
+        if (
+            existing.owner == manifest.owner
+            and existing.name == manifest.name
+            and existing.version == manifest.version
+        ):
+            raise ValueError(
+                f"Tool version is already published: {manifest.owner}/{manifest.name} {manifest.version}"
+            )

pkgwhy/registry/run.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import tarfile
+import venv
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pkgwhy.core.models import (
+    ToolArtifactType,
+    ToolRunResult,
+    ToolRunStatus,
+)
+from pkgwhy.policy.tool_execution import evaluate_tool_execution_policy
+from pkgwhy.registry.local import current_registry
+from pkgwhy.registry.tools import judge_tool, resolve_tool_entry
+
+RUNNER_ISOLATION_WARNING = (
+    "This run uses a Python virtual environment for dependency isolation. "
+    "It does not fully sandbox operating-system permissions."
+)
+DEFAULT_RUN_TIMEOUT_SECONDS = 300
+
+
+def run_local_tool(reference: str, *, non_interactive: bool = False) -> ToolRunResult:
+    registry = current_registry()
+    entry = resolve_tool_entry(reference, registry)
+    judgement = judge_tool(reference)
+    policy_result = evaluate_tool_execution_policy(judgement, non_interactive=non_interactive)
+    if not policy_result.allowed:
+        raise ValueError(f"Tool policy blocks execution: {' '.join(policy_result.reasons)}")
+    manifest = judgement.manifest
+    if manifest.artifact_type not in {ToolArtifactType.SCRIPT, ToolArtifactType.FOLDER}:
+        raise ValueError(f"Unsupported tool artifact type for runner MVP: {manifest.artifact_type.value}")
+    if manifest.dependencies:
+        raise ValueError("Dependency installation is not implemented for pkgwhy run MVP.")
+    entrypoint = Path(manifest.entrypoint)
+    if entrypoint.is_absolute() or ".." in entrypoint.parts or entrypoint.suffix != ".py":
+        raise ValueError(f"Unsupported entrypoint for runner MVP: {manifest.entrypoint}")
+
+    tool_root = registry.path / "run-workspaces" / entry.owner / entry.name / entry.version
+    venv_path = registry.path / "venvs" / entry.owner / entry.name / entry.version
+    log_dir = registry.path / "execution-logs" / entry.owner / entry.name / entry.version
+    bundle_path = registry.path / entry.bundle_path
+
+    _prepare_workspace(bundle_path, tool_root)
+    entrypoint_path = (tool_root / entrypoint).resolve()
+    if not entrypoint_path.is_file() or tool_root.resolve() not in entrypoint_path.parents:
+        raise ValueError(f"Entrypoint not found in tool bundle: {manifest.entrypoint}")
+    python_path = _ensure_venv_python(venv_path)
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    started_at_dt = datetime.now(tz=UTC)
+    command = [str(python_path), str(entrypoint_path)]
+    try:
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=tool_root,
+            timeout=DEFAULT_RUN_TIMEOUT_SECONDS,
+        )
+        exit_code = completed.returncode
+        stdout = completed.stdout
+        stderr = completed.stderr
+    except subprocess.TimeoutExpired as exc:
+        exit_code = 124
+        stdout = _output_text(exc.stdout)
+        stderr = _output_text(exc.stderr)
+        timeout_message = f"Tool execution timed out after {DEFAULT_RUN_TIMEOUT_SECONDS} seconds."
+        stderr = f"{stderr.rstrip()}\n{timeout_message}\n" if stderr else f"{timeout_message}\n"
+    finished_at_dt = datetime.now(tz=UTC)
+    status = ToolRunStatus.COMPLETED if exit_code == 0 else ToolRunStatus.FAILED
+    result = ToolRunResult(
+        tool=f"{entry.owner}/{entry.name}",
+        owner=entry.owner,
+        name=entry.name,
+        version=entry.version,
+        registry_name=registry.name,
+        registry_path=registry.path,
+        command=command,
+        entrypoint=manifest.entrypoint,
+        started_at=started_at_dt.isoformat(),
+        finished_at=finished_at_dt.isoformat(),
+        exit_code=exit_code,
+        status=status,
+        stdout=stdout,
+        stderr=stderr,
+        log_path=log_dir / f"{started_at_dt.strftime('%Y%m%dT%H%M%S%fZ')}.json",
+        warning=RUNNER_ISOLATION_WARNING,
+        policy_decision=policy_result.decision,
+        policy_reasons=policy_result.reasons,
+        policy_warnings=policy_result.warnings,
+    )
+    _write_execution_log(result)
+    return result
+
+
+def _prepare_workspace(bundle_path: Path, tool_root: Path) -> None:
+    if tool_root.exists():
+        shutil.rmtree(tool_root)
+    tool_root.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(bundle_path, "r:gz") as archive:
+        members = archive.getmembers()
+        _validate_archive_members(members)
+        try:
+            archive.extractall(tool_root, members=members, filter="data")
+        except TypeError:
+            archive.extractall(tool_root, members=members)
+
+
+def _validate_archive_members(members: list[tarfile.TarInfo]) -> None:
+    for member in members:
+        path = Path(member.name)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"Unsafe path in tool bundle: {member.name}")
+        if member.issym() or member.islnk():
+            raise ValueError(f"Links are not supported in runner bundles: {member.name}")
+
+
+def _ensure_venv_python(venv_path: Path) -> Path:
+    python_path = venv_path / ("Scripts/python.exe" if _is_windows_venv() else "bin/python")
+    if not python_path.exists():
+        venv.EnvBuilder(with_pip=False, clear=False).create(venv_path)
+    if not python_path.exists():
+        raise ValueError(f"Could not create runner virtual environment at {venv_path}")
+    return python_path
+
+
+def _is_windows_venv() -> bool:
+    return sys.platform == "win32"
+
+
+def _output_text(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    return value
+
+
+def _write_execution_log(result: ToolRunResult) -> None:
+    result.log_path.parent.mkdir(parents=True, exist_ok=True)
+    result.log_path.write_text(json.dumps(result.model_dump(mode="json"), indent=2, sort_keys=True) + "\n", encoding="utf-8")

pkgwhy/registry/tools.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from pkgwhy.core.models import (
+    AgentDecision,
+    Confidence,
+    HashStatus,
+    RegistryEntry,
+    RegistryToolEntry,
+    RiskLevel,
+    ToolJudgement,
+    ToolManifest,
+)
+from pkgwhy.registry.local import current_registry, load_registry_index
+
+
+def judge_tool(reference: str) -> ToolJudgement:
+    registry = current_registry()
+    entry = resolve_tool_entry(reference, registry)
+    manifest = _load_manifest(registry.path, entry)
+    hash_status = _verify_hash(registry.path, entry)
+    warnings: list[str] = ["Signature verification is not implemented yet."]
+    detected_capabilities: list[str] = []
+
+    if hash_status == HashStatus.VERIFIED:
+        risk = RiskLevel.MEDIUM
+        decision = AgentDecision.REVIEW_MANUALLY if manifest.security.requires_human_approval else AgentDecision.ALLOW_WITH_CAUTION
+        reason = "Tool bundle hash matches the local registry index."
+        recommendation = "Review declared permissions and manifest metadata before running this private tool."
+    elif hash_status == HashStatus.MISSING:
+        risk = RiskLevel.UNKNOWN
+        decision = AgentDecision.REVIEW_MANUALLY
+        reason = "Tool bundle is missing from the local registry."
+        recommendation = "Restore or republish the bundle before running this tool."
+        warnings.append("Bundle file is missing.")
+    else:
+        risk = RiskLevel.HIGH
+        decision = AgentDecision.BLOCK
+        reason = "Tool bundle hash does not match the local registry index."
+        recommendation = "Block use until a human verifies or republishes the tool."
+        warnings.append("Bundle hash mismatch.")
+
+    if not detected_capabilities:
+        warnings.append("Static capability detection for tool bundles is not implemented yet.")
+
+    return ToolJudgement(
+        tool=f"{entry.owner}/{entry.name}",
+        owner=entry.owner,
+        name=entry.name,
+        version=entry.version,
+        decision=decision,
+        risk_level=risk,
+        confidence=Confidence.MEDIUM if hash_status == HashStatus.VERIFIED else Confidence.LOW,
+        reason=reason,
+        requires_human_approval=manifest.security.requires_human_approval,
+        manifest=manifest,
+        declared_permissions=manifest.declared_permissions,
+        detected_capabilities=detected_capabilities,
+        hash_status=hash_status,
+        warnings=warnings,
+        recommendation=recommendation,
+    )
+
+
+def resolve_tool_entry(reference: str, registry: RegistryEntry | None = None) -> RegistryToolEntry:
+    active_registry = registry or current_registry()
+    index = load_registry_index(active_registry.path, strict=True)
+    owner, name = _parse_reference(reference)
+    matches = [
+        entry
+        for entry in index.tools
+        if entry.name == name and (owner is None or entry.owner == owner)
+    ]
+    if not matches:
+        raise ValueError(f"Tool is not published in the current registry: {reference}")
+    if owner is None and len({entry.owner for entry in matches}) > 1:
+        raise ValueError(f"Tool reference is ambiguous; include owner: {reference}")
+    return sorted(matches, key=lambda entry: entry.published_at, reverse=True)[0]
+
+
+def _parse_reference(reference: str) -> tuple[str | None, str]:
+    parts = reference.split("/", maxsplit=1)
+    if len(parts) == 2:
+        return parts[0], parts[1]
+    return None, reference
+
+
+def _load_manifest(registry_path: Path, entry: RegistryToolEntry) -> ToolManifest:
+    manifest_path = _validate_registry_path(registry_path, entry.manifest_path, entry)
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        return ToolManifest.model_validate(data)
+    except (OSError, json.JSONDecodeError, ValidationError) as exc:
+        raise ValueError(f"Could not read stored tool manifest for {entry.owner}/{entry.name}") from exc
+
+
+def _verify_hash(registry_path: Path, entry: RegistryToolEntry) -> HashStatus:
+    bundle_path = _validate_registry_path(registry_path, entry.bundle_path, entry)
+    digest = hashlib.sha256()
+    try:
+        with bundle_path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+    except FileNotFoundError:
+        return HashStatus.MISSING
+    if digest.hexdigest() != entry.sha256:
+        return HashStatus.MISMATCH
+    return HashStatus.VERIFIED
+
+
+def _validate_registry_path(registry_path: Path, entry_path: str, entry: RegistryToolEntry) -> Path:
+    registry_root = registry_path.resolve()
+    candidate = (registry_root / entry_path).resolve()
+    if not candidate.is_relative_to(registry_root):
+        raise ValueError(f"Registry entry path escapes registry root for {entry.owner}/{entry.name}: {entry_path}")
+    return candidate

pkgwhy/reports/__init__.py

@@ -0,0 +1,2 @@
+"""Human and machine-readable package inspection reports."""
+