installgate 0.1.0__py3-none-any.whl

engine/clients/__init__.py

@@ -0,0 +1,64 @@
+"""Read-only metadata clients. Allowlisted hosts, timeouts, no code execution."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+ALLOWED_HOSTS = frozenset(
+    {
+        "pypi.org",
+        "registry.npmjs.org",
+        "api.osv.dev",
+        "huggingface.co",
+    }
+)
+
+TIMEOUT = httpx.Timeout(connect=3.0, read=5.0, write=3.0, pool=3.0)
+HEADERS = {"User-Agent": "InstallGate/0.1 (metadata-only pre-install check)"}
+
+
+class UpstreamError(RuntimeError):
+    """A registry call failed. The caller must fail closed to REVIEW."""
+
+
+def _assert_allowed(url: str) -> None:
+    host = httpx.URL(url).host
+    if host not in ALLOWED_HOSTS:
+        raise UpstreamError(f"host not allowlisted: {host}")
+
+
+async def get_json(
+    client: httpx.AsyncClient, url: str, *, allow_404: bool = False
+) -> dict[str, Any] | None:
+    """GET and parse JSON. Returns None on 404 when allow_404 (used for existence checks)."""
+    _assert_allowed(url)
+    try:
+        response = await client.get(url, timeout=TIMEOUT, headers=HEADERS)
+    except httpx.HTTPError as exc:
+        raise UpstreamError(f"GET {url} failed: {exc}") from exc
+    if response.status_code == 404 and allow_404:
+        return None
+    if response.status_code >= 400:
+        raise UpstreamError(f"GET {url} returned {response.status_code}")
+    try:
+        body: dict[str, Any] = response.json()
+    except ValueError as exc:
+        raise UpstreamError(f"GET {url} returned non-JSON") from exc
+    return body
+
+
+async def post_json(client: httpx.AsyncClient, url: str, payload: dict[str, Any]) -> dict[str, Any]:
+    _assert_allowed(url)
+    try:
+        response = await client.post(url, json=payload, timeout=TIMEOUT, headers=HEADERS)
+    except httpx.HTTPError as exc:
+        raise UpstreamError(f"POST {url} failed: {exc}") from exc
+    if response.status_code >= 400:
+        raise UpstreamError(f"POST {url} returned {response.status_code}")
+    try:
+        body: dict[str, Any] = response.json()
+    except ValueError as exc:
+        raise UpstreamError(f"POST {url} returned non-JSON") from exc
+    return body

engine/clients/huggingface.py

@@ -0,0 +1,69 @@
+"""Hugging Face Hub model metadata. We read the file list; we never load weights."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+from contracts.contracts import TargetRef
+
+from engine.cache import Cache
+from engine.clients import get_json
+
+BASE = "https://huggingface.co/api/models"
+
+PICKLE_SUFFIXES = (".bin", ".pt", ".pth", ".pkl", ".ckpt")
+SAFE_SUFFIXES = (".safetensors",)
+
+
+def model_url(repo_id: str) -> str:
+    return f"{BASE}/{repo_id}"
+
+
+def summarise(body: dict[str, Any] | None) -> dict[str, Any]:
+    if body is None:
+        return {"exists": False}
+
+    filenames = [
+        str(s.get("rfilename"))
+        for s in (body.get("siblings") or [])
+        if isinstance(s, dict) and s.get("rfilename")
+    ]
+    pickle_files = [f for f in filenames if f.lower().endswith(PICKLE_SUFFIXES)]
+    safetensors_files = [f for f in filenames if f.lower().endswith(SAFE_SUFFIXES)]
+
+    created_raw = str(body.get("createdAt") or "")
+    modified_raw = str(body.get("lastModified") or "")
+
+    def _parse(raw: str) -> str | None:
+        try:
+            return datetime.fromisoformat(raw.replace("Z", "+00:00")).astimezone(UTC).isoformat()
+        except ValueError:
+            return None
+
+    return {
+        "exists": True,
+        "files": filenames,
+        "pickle_files": pickle_files,
+        "safetensors_files": safetensors_files,
+        "has_pickle": bool(pickle_files),
+        "has_safetensors": bool(safetensors_files),
+        "first_upload": _parse(created_raw),
+        "latest_upload": _parse(modified_raw),
+        "sha": body.get("sha"),
+    }
+
+
+async def fetch(
+    client: httpx.AsyncClient, target: TargetRef, cache: Cache | None = None
+) -> dict[str, Any]:
+    if cache is not None:
+        cached = cache.get("huggingface", target.name)
+        if cached is not None:
+            return dict(cached)
+    body = await get_json(client, model_url(target.name), allow_404=True)
+    facts = summarise(body)
+    if cache is not None:
+        cache.set("huggingface", target.name, facts)
+    return facts

engine/clients/npm.py

@@ -0,0 +1,91 @@
+"""npm registry. Existence, `time` map, maintainers, dist integrity."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from contracts.contracts import TargetRef
+
+from engine.cache import Cache
+from engine.clients import get_json
+
+BASE = "https://registry.npmjs.org"
+
+
+def project_url(name: str) -> str:
+    # A scoped name (@scope/pkg) must have its slash encoded.
+    return f"{BASE}/{quote(name, safe='@')}"
+
+
+def _parse(raw: str) -> datetime | None:
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).astimezone(UTC)
+    except ValueError:
+        return None
+
+
+def _pin_digest(integrity: object, shasum: object, name: str, version: str) -> str:
+    """Stable 64-hex pin from registry metadata. Not the tarball bytes (we never fetch them)."""
+    raw = str(integrity or shasum or f"{name}@{version}")
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def summarise(body: dict[str, Any] | None, *, version: str | None = None) -> dict[str, Any]:
+    if body is None:
+        return {"exists": False}
+
+    times: dict[str, Any] = body.get("time") or {}
+    created = _parse(str(times.get("created") or ""))
+    modified = _parse(str(times.get("modified") or ""))
+
+    latest_version = ((body.get("dist-tags") or {}).get("latest")) or None
+    versions: dict[str, Any] = body.get("versions") or {}
+    pin_version = version if version and str(version) in versions else latest_version
+    pin_meta = versions.get(str(pin_version)) or {}
+    dist = pin_meta.get("dist") or {}
+    integrity = dist.get("integrity")
+    shasum = dist.get("shasum")
+    name = str(body.get("name") or pin_meta.get("name") or "")
+
+    maintainers = sorted(
+        {
+            str(m.get("name") or m.get("email"))
+            for m in (body.get("maintainers") or [])
+            if isinstance(m, dict) and (m.get("name") or m.get("email"))
+        }
+    )
+
+    pin_sha = _pin_digest(integrity, shasum, name, str(pin_version)) if pin_version else None
+
+    return {
+        "exists": True,
+        "latest_version": latest_version,
+        "first_upload": created.isoformat() if created else None,
+        "latest_upload": modified.isoformat() if modified else None,
+        "maintainers": maintainers,
+        "dist_integrity": integrity,
+        "dist_shasum": shasum,
+        "pin_version": pin_version,
+        "pin_sha256": pin_sha,
+        "latest_sha256": pin_sha,
+        "release_count": len(versions),
+    }
+
+
+async def fetch(
+    client: httpx.AsyncClient, target: TargetRef, cache: Cache | None = None
+) -> dict[str, Any]:
+    key = f"{target.name}@{target.version or 'latest'}"
+    if cache is not None:
+        cached = cache.get("npm", key)
+        if cached is not None:
+            return dict(cached)
+    body = await get_json(client, project_url(target.name), allow_404=True)
+    facts = summarise(body, version=target.version)
+    if cache is not None:
+        cache.set("npm", key, facts)
+    return facts

engine/clients/osv.py

@@ -0,0 +1,91 @@
+"""OSV.dev query. Only MAL- records make a package malicious."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from contracts.contracts import Ecosystem, TargetRef
+
+from engine.cache import Cache
+from engine.clients import post_json
+
+QUERY_URL = "https://api.osv.dev/v1/query"
+
+OSV_ECOSYSTEM = {
+    Ecosystem.PYPI: "PyPI",
+    Ecosystem.NPM: "npm",
+}
+
+
+def affected_spec(record: dict[str, Any], name: str | None = None) -> dict[str, Any]:
+    """What an advisory says about *which versions* it covers.
+
+    A MAL- record usually lists exact versions. Some cover the whole project and
+    name none. The difference decides whether a clean release of a package that
+    was once compromised may still be installed, so it has to survive into the
+    evidence rather than collapsing to a boolean.
+    """
+    versions: list[str] = []
+    ranges: list[dict[str, Any]] = []
+    for affected in record.get("affected") or []:
+        package = (affected or {}).get("package") or {}
+        if name and package.get("name") and str(package["name"]).lower() != name.lower():
+            continue
+        versions.extend(str(v) for v in (affected.get("versions") or []))
+        ranges.extend(r for r in (affected.get("ranges") or []) if isinstance(r, dict))
+
+    return {
+        "id": str(record.get("id", "")),
+        "versions": sorted(set(versions)),
+        "ranges": ranges,
+        # No version information at all means the project as a whole is the
+        # finding: every release is covered.
+        "whole_package": not versions and not ranges,
+    }
+
+
+def summarise(body: dict[str, Any], name: str | None = None) -> dict[str, Any]:
+    vulns = [v for v in (body.get("vulns") or []) if isinstance(v, dict)]
+    mal = [v for v in vulns if str(v.get("id", "")).startswith("MAL-")]
+    other_ids = sorted({str(v["id"]) for v in vulns if not str(v.get("id", "")).startswith("MAL-")})
+    records = [affected_spec(v, name) for v in mal]
+    return {
+        # True when a MAL- record exists for the *name*. Whether it covers the
+        # version in hand is a separate question, answered by `mal_records`.
+        "malicious": bool(mal),
+        "mal_ids": sorted({r["id"] for r in records}),
+        "mal_records": records,
+        "other_ids": other_ids,
+    }
+
+
+async def fetch(
+    client: httpx.AsyncClient, target: TargetRef, cache: Cache | None = None
+) -> dict[str, Any]:
+    ecosystem = OSV_ECOSYSTEM.get(target.ecosystem)
+    if ecosystem is None:
+        return {
+            "malicious": False,
+            "mal_ids": [],
+            "mal_records": [],
+            "other_ids": [],
+            "queried": False,
+        }
+
+    # Always query by name, never by version. Asking OSV to filter would hide
+    # which versions a record covers, and the check needs that to tell a
+    # compromised release from a clean one of the same project.
+    key = f"{ecosystem}:{target.name}"
+    if cache is not None:
+        cached = cache.get("osv", key)
+        if cached is not None:
+            return dict(cached)
+
+    payload: dict[str, Any] = {"package": {"name": target.name, "ecosystem": ecosystem}}
+
+    facts = summarise(await post_json(client, QUERY_URL, payload), name=target.name)
+    facts["queried"] = True
+    if cache is not None:
+        cache.set("osv", key, facts)
+    return facts

engine/clients/pypi.py

@@ -0,0 +1,197 @@
+"""PyPI JSON API. Existence, release dates, maintainers, file hashes."""
+
+from __future__ import annotations
+
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+from contracts.contracts import TargetRef
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.tags import Tag, sys_tags
+from packaging.utils import InvalidWheelFilename, parse_wheel_filename
+from packaging.version import InvalidVersion, Version
+
+from engine.cache import Cache
+from engine.clients import get_json
+
+BASE = "https://pypi.org/pypi"
+
+
+def project_url(name: str) -> str:
+    return f"{BASE}/{name}/json"
+
+
+def cache_key(name: str, python: tuple[int, int] | None = None) -> str:
+    major, minor = python or sys.version_info[:2]
+    return f"{name}:cp{major}{minor}"
+
+
+def _parse_upload_time(raw: str) -> datetime | None:
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).astimezone(UTC)
+    except ValueError:
+        return None
+
+
+def _python_ok(spec: object, python: str) -> bool:
+    if not spec:
+        return True
+    try:
+        return python in SpecifierSet(str(spec))
+    except InvalidSpecifier:
+        return False
+
+
+def _usable_files(
+    files: list[dict[str, Any]], python: str, tags: list[Tag]
+) -> list[dict[str, Any]]:
+    usable: list[dict[str, Any]] = []
+    for item in files:
+        if item.get("yanked"):
+            continue
+        if not _python_ok(item.get("requires_python"), python):
+            continue
+        usable.append(item)
+    if not usable:
+        return []
+    if _file_sha(usable, tags) is None:
+        return []
+    return usable
+
+
+def _file_sha(files: list[dict[str, Any]], tags: list[Tag]) -> str | None:
+    wheels: list[tuple[frozenset[Tag], str]] = []
+    sdist: str | None = None
+    for item in files:
+        digest = (item.get("digests") or {}).get("sha256")
+        if not digest:
+            continue
+        name = str(item.get("filename") or "")
+        if name.endswith(".whl"):
+            try:
+                _, _, _, wheel_tags = parse_wheel_filename(name)
+            except InvalidWheelFilename:
+                continue
+            wheels.append((wheel_tags, str(digest)))
+            continue
+        if sdist is None:
+            sdist = str(digest)
+    for tag in tags:
+        for wheel_tags, digest in wheels:
+            if tag in wheel_tags:
+                return digest
+    return sdist
+
+
+def _newest_installable(
+    releases: dict[str, list[dict[str, Any]]], python: str, tags: list[Tag]
+) -> tuple[str | None, list[dict[str, Any]]]:
+    ranked: list[tuple[Version, str]] = []
+    for version in releases:
+        try:
+            ranked.append((Version(version), version))
+        except InvalidVersion:
+            continue
+    ranked.sort(reverse=True)
+    for _, version in ranked:
+        files = _usable_files(releases.get(version) or [], python, tags)
+        if files:
+            return version, files
+    return None, []
+
+
+def summarise(
+    body: dict[str, Any] | None,
+    *,
+    python: tuple[int, int] | None = None,
+    tags: list[Tag] | None = None,
+) -> dict[str, Any]:
+    """Flatten the PyPI payload into the facts the checks need.
+
+    `latest_version` is what PyPI reports. `pin_version` is the newest release
+    this interpreter can actually install (requires_python + a matching wheel
+    or sdist). Unpinned checks pin `pin_version`, not a 3.12-only latest on 3.11.
+    """
+    if body is None:
+        return {"exists": False}
+
+    info = body.get("info") or {}
+    releases: dict[str, list[dict[str, Any]]] = body.get("releases") or {}
+    if not releases and body.get("urls"):
+        # A release document (/pypi/{name}/{version}/json) has no `releases` map;
+        # its files are under `urls` and describe that one version. Without this
+        # the summary comes back with no dates and no hash, which reads as a
+        # package nobody ever uploaded.
+        releases = {str(info.get("version")): list(body["urls"])}
+
+    upload_times: list[datetime] = []
+    for files in releases.values():
+        for item in files:
+            parsed = _parse_upload_time(str(item.get("upload_time_iso_8601") or ""))
+            if parsed:
+                upload_times.append(parsed)
+
+    major, minor = python or sys.version_info[:2]
+    python_s = f"{major}.{minor}"
+    tag_list = tags if tags is not None else list(sys_tags())
+
+    latest_version = info.get("version")
+    latest_files = releases.get(str(latest_version), []) if latest_version else []
+    latest_upload = max(
+        (
+            t
+            for t in (
+                _parse_upload_time(str(f.get("upload_time_iso_8601") or "")) for f in latest_files
+            )
+            if t
+        ),
+        default=None,
+    )
+    latest_sha = _file_sha(latest_files, tag_list) or next(
+        (
+            str((f.get("digests") or {}).get("sha256"))
+            for f in latest_files
+            if (f.get("digests") or {}).get("sha256")
+        ),
+        None,
+    )
+
+    pin_version, pin_files = _newest_installable(releases, python_s, tag_list)
+    pin_sha = _file_sha(pin_files, tag_list) if pin_files else None
+
+    maintainers = sorted(
+        {
+            str(value)
+            for key in ("author", "maintainer", "author_email", "maintainer_email")
+            if (value := info.get(key))
+        }
+    )
+
+    return {
+        "exists": True,
+        "latest_version": latest_version,
+        "first_upload": min(upload_times).isoformat() if upload_times else None,
+        "latest_upload": latest_upload.isoformat() if latest_upload else None,
+        "maintainers": maintainers,
+        "latest_sha256": latest_sha,
+        "pin_version": pin_version,
+        "pin_sha256": pin_sha,
+        "release_count": len(releases),
+    }
+
+
+async def fetch(
+    client: httpx.AsyncClient, target: TargetRef, cache: Cache | None = None
+) -> dict[str, Any]:
+    key = cache_key(target.name)
+    if cache is not None:
+        cached = cache.get("pypi", key)
+        if cached is not None:
+            return dict(cached)
+    body = await get_json(client, project_url(target.name), allow_404=True)
+    facts = summarise(body)
+    if cache is not None:
+        cache.set("pypi", key, facts)
+    return facts