skip-trace 0.1.0__py3-none-any.whl

skip_trace/reporting/md_reporter.py

@@ -0,0 +1,115 @@
+# skip_trace/reporting/md_reporter.py
+from __future__ import annotations
+
+import sys
+from typing import IO
+
+from rich.console import Console
+from rich.table import Table
+
+from ..schemas import PackageResult
+
+
+def render(result: PackageResult, file: IO[str] = sys.stdout):
+    """
+    Renders the PackageResult as a rich report to the console.
+
+    Args:
+        result: The PackageResult object to render.
+        file: The file object to write to (defaults to stdout).
+    """
+    import shutil
+
+    width, _ = shutil.get_terminal_size((80, 175))
+    console = Console(file=file, width=width)
+    version_str = f" v{result.version}" if result.version else ""
+    console.print(
+        f"\n[bold]📦 skip-trace: Ownership Report for {result.package}{version_str}[/bold]"
+    )
+    console.print("-" * 80)
+
+    # --- OWNERS TABLE ---
+    if not result.owners:
+        console.print("\n[bold]## 🕵️ Owner Candidates[/bold]")
+        console.print("\nNo owner candidates found.\n")
+    else:
+        console.print("\n[bold]## 🕵️ Owner Candidates[/bold]")
+        # Create a lookup map for evidence for fast access
+        evidence_map = {ev.id: ev for ev in result.evidence}
+
+        owner_table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title="Top Owner Candidates",
+            title_style="bold",
+        )
+        owner_table.add_column("Owner", style="cyan", width=30, no_wrap=True)
+        owner_table.add_column("Kind", width=10)
+        owner_table.add_column("Score", justify="right", style="bold")
+        owner_table.add_column("Contacts", width=65)
+        owner_table.add_column("Key Evidence Notes", no_wrap=False)
+
+        for owner in result.owners:
+            score_str = f"{owner.score:.2f}"
+            score_style = (
+                "green"
+                if owner.score >= 0.7
+                else "yellow" if owner.score >= 0.5 else "red"
+            )
+
+            contact_parts = []
+            for contact in owner.contacts:
+                value = contact.value
+                if contact.type.value in ("url", "repo") and len(value) > 60:
+                    value = value[:60] + "..."
+                contact_parts.append(f"[bold dim]{contact.type.value}[/]: {value}")
+            contacts_str = (
+                "\n".join(contact_parts)
+                if contact_parts
+                else "[italic]None found[/italic]"
+            )
+
+            # Look up the notes from the evidence IDs
+            evidence_notes = []
+            for ev_id in owner.evidence:
+                evidence_record = evidence_map.get(ev_id)
+                if evidence_record and evidence_record.notes:
+                    evidence_notes.append(f"• {evidence_record.notes}")
+            key_evidence_str = (
+                "\n".join(evidence_notes)
+                if evidence_notes
+                else "[italic]No notes.[/italic]"
+            )
+
+            owner_table.add_row(
+                owner.name,
+                owner.kind.value,
+                f"[{score_style}]{score_str}[/]",
+                contacts_str,
+                key_evidence_str,
+            )
+        console.print(owner_table)
+
+    # --- MAINTAINERS TABLE ---
+    if result.maintainers:
+        console.print("\n[bold]## 🧑‍💻 PyPI Maintainers[/bold]")
+        maintainer_table = Table(
+            show_header=True,
+            header_style="bold cyan",
+            title="Directly Listed Maintainers",
+            title_style="bold",
+        )
+        maintainer_table.add_column("Name", style="cyan")
+        maintainer_table.add_column("Email")
+        maintainer_table.add_column("Confidence", justify="right")
+
+        for maintainer in sorted(
+            result.maintainers, key=lambda m: m.confidence, reverse=True
+        ):
+            email_str = maintainer.email or "[italic]Not provided[/italic]"
+            confidence_str = f"{maintainer.confidence:.2f}"
+            maintainer_table.add_row(maintainer.name, email_str, confidence_str)
+
+        console.print(maintainer_table)
+
+    console.print("-" * 80)

skip_trace/schemas.py

@@ -0,0 +1,131 @@
+# skip_trace/schemas.py
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, List, Optional
+
+# --- Enums for controlled vocabularies ---
+
+
+class OwnerKind(str, Enum):
+    INDIVIDUAL = "individual"
+    COMPANY = "company"
+    FOUNDATION = "foundation"
+    PROJECT = "project"
+
+
+class ContactType(str, Enum):
+    EMAIL = "email"
+    URL = "url"
+    SECURITY = "security"
+    REPO = "repo"
+    MATRIX = "matrix"
+    SLACK = "slack"
+    TWITTER = "twitter"
+    MASTODON = "mastodon"
+    LINKEDIN = "linkedin"
+    # Add more common social platforms
+    FACEBOOK = "facebook"
+    INSTAGRAM = "instagram"
+    YOUTUBE = "youtube"
+    TIKTOK = "tiktok"
+    OTHER = "other"
+
+
+class EvidenceSource(str, Enum):
+    PYPI = "pypi"
+    REPO = "repo"
+    WHEEL = "wheel"
+    LOCAL = "local"
+    DOCS = "docs"
+    SIGSTORE = "sigstore"
+    WHOIS = "whois"
+    VENV_SCAN = "venv-scan"
+    LLM_NER = "llm-ner"
+
+
+class EvidenceKind(str, Enum):
+    PERSON = "person"
+    EMAIL = "email"
+    MAINTAINER = "maintainer"
+    ORGANIZATION = "org"
+    DOMAIN = "domain"
+    GOVERNANCE = "governance"
+    SIGNATURE = "signature"
+    COPYRIGHT = "copyright"
+    AUTHOR_TAG = "author-tag"
+    CODEOWNERS = "codeowners"
+    CONTACT = "contact"
+    PROJECT_URL = "project-url"
+    PYPI_USER = "pypi-user"
+    # GitHub-specific evidence kinds
+    REPO_OWNER = "repo-owner"
+    COMMIT_AUTHOR = "commit-author"
+    # GitHub profile-specific evidence kinds
+    USER_PROFILE = "user-profile"
+    USER_COMPANY = "user-company"
+
+
+# --- Core Data Schemas ---
+
+
+@dataclass
+class Contact:
+    """Represents a method of contacting an entity."""
+
+    type: ContactType
+    value: str
+    verified: bool = False
+
+
+@dataclass
+class EvidenceRecord:
+    """A single piece of evidence supporting an ownership claim."""
+
+    id: str
+    source: EvidenceSource
+    locator: str  # URL, file path, or PURL
+    kind: EvidenceKind
+    value: Any
+    observed_at: datetime.datetime
+    linkage: List[str] = field(default_factory=list)
+    confidence: float = 0.0
+    notes: str = ""
+
+
+@dataclass
+class OwnerCandidate:
+    """Represents a potential owner with an aggregated score."""
+
+    name: str
+    kind: OwnerKind
+    score: float = 0.0
+    contacts: List[Contact] = field(default_factory=list)
+    evidence: List[str] = field(default_factory=list)  # List of EvidenceRecord IDs
+    rationale: str = ""
+
+
+@dataclass
+class Maintainer:
+    """A simplified maintainer record, distinct from a scored owner."""
+
+    name: str
+    email: Optional[str] = None
+    confidence: float = 0.0
+
+
+@dataclass
+class PackageResult:
+    """The final JSON output for a single package."""
+
+    package: str
+    version: Optional[str] = None
+    owners: List[OwnerCandidate] = field(default_factory=list)
+    maintainers: List[Maintainer] = field(default_factory=list)
+    evidence: List[EvidenceRecord] = field(default_factory=list)
+    timestamp: str = field(
+        default_factory=lambda: datetime.datetime.now(datetime.timezone.utc).isoformat()
+    )
+    schema_version: str = "1.0"

skip_trace/utils/__init__.py

@@ -0,0 +1,4 @@
+# skip_trace/utils/__init__.py
+from . import cache, http_client, validation
+
+__all__ = ["cache", "http_client", "validation"]

skip_trace/utils/cache.py

@@ -0,0 +1,77 @@
+# skip_trace/utils/cache.py
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from typing import Any, Optional
+
+from ..config import CONFIG
+
+logger = logging.getLogger(__name__)
+
+
+def get_cache_path(cache_type: str, key: str) -> str:
+    """Constructs the full path for a given cache type and key."""
+    cache_config = CONFIG.get("cache", {})
+    base_dir = cache_config.get("dir", ".skip_trace_cache")
+    cache_dir = os.path.join(base_dir, cache_type)
+    os.makedirs(cache_dir, exist_ok=True)
+
+    # Sanitize key for filesystem compatibility
+    safe_key = "".join(c for c in key if c.isalnum() or c in ("-", "_", "."))
+    return os.path.join(cache_dir, f"{safe_key}.json")
+
+
+def get_cached_data(cache_type: str, key: str) -> Optional[Any]:
+    """
+    Retrieves data from the cache if it exists and is not expired.
+
+    Args:
+        cache_type: The category of the cache (e.g., 'whois').
+        key: The unique identifier for the cached item.
+
+    Returns:
+        The cached data, or None if not found or expired.
+    """
+    cache_config = CONFIG.get("cache", {})
+    if not cache_config.get("enabled", True):
+        return None
+
+    file_path = get_cache_path(cache_type, key)
+    ttl = cache_config.get("ttl_seconds", 604800)  # Default to 7 days
+
+    if os.path.exists(file_path):
+        mod_time = os.path.getmtime(file_path)
+        if (time.time() - mod_time) < ttl:
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except (json.JSONDecodeError, IOError) as e:
+                logger.warning(f"Could not read cache file {file_path}: {e}")
+                return None
+    return None
+
+
+def set_cached_data(cache_type: str, key: str, data: Any):
+    """
+    Writes data to the cache.
+
+    Args:
+        cache_type: The category of the cache (e.g., 'whois').
+        key: The unique identifier for the item to cache.
+        data: The JSON-serializable data to store.
+    """
+    if not data:
+        return
+    cache_config = CONFIG.get("cache", {})
+    if not cache_config.get("enabled", True):
+        return
+
+    file_path = get_cache_path(cache_type, key)
+    try:
+        with open(file_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, default=str)
+    except IOError as e:
+        logger.error(f"Could not write to cache file {file_path}: {e}")

skip_trace/utils/cli_suggestions.py

@@ -0,0 +1,91 @@
+"""
+Smart argument parser with typo suggestions.
+
+This module provides a subclass of `argparse.ArgumentParser` that enhances
+the error reporting behavior when users supply invalid choices. If a user
+makes a typo in a choice, the parser will suggest the closest matches
+based on string similarity.
+
+Example:
+    ```python
+    import sys
+
+    parser = SmartParser(prog="myapp")
+    parser.add_argument("color", choices=["red", "green", "blue"])
+    args = parser.parse_args()
+
+    # If the user runs:
+    #   myapp gren
+    #
+    # The output will include:
+    #   error: invalid choice: 'gren' (choose from 'red', 'green', 'blue')
+    #
+    #   Did you mean: green?
+    ```
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from difflib import get_close_matches
+
+
+class SmartParser(argparse.ArgumentParser):
+    """Argument parser that suggests similar choices on invalid input.
+
+    This class extends `argparse.ArgumentParser` to provide more helpful
+    error messages when the user provides an invalid choice for an argument.
+    Instead of only showing the list of valid choices, it also suggests the
+    closest matches using fuzzy string matching.
+
+    Example:
+        ```python
+        parser = SmartParser()
+        parser.add_argument("fruit", choices=["apple", "banana", "cherry"])
+        args = parser.parse_args()
+        ```
+
+    If the user types:
+        ```
+        myprog bannna
+        ```
+
+    The error message will include:
+        ```
+        Did you mean: banana?
+        ```
+    """
+
+    def error(self, message: str):
+        """Handle parsing errors with suggestions for invalid choices.
+
+        Args:
+            message (str): The error message generated by argparse,
+                typically when parsing fails (e.g., due to invalid
+                choices or syntax errors).
+
+        Side Effects:
+            - Prints usage information to `sys.stderr`.
+            - Exits the program with status code 2.
+
+        Behavior:
+            - If the error message contains an "invalid choice" message,
+              attempts to suggest the closest valid alternatives by
+              computing string similarity.
+            - Otherwise, preserves standard argparse behavior.
+        """
+        # Detect "invalid choice: 'foo' (choose from ...)"
+        if "invalid choice" in message and "choose from" in message:
+            bad = message.split("invalid choice:")[1].split("(")[0].strip().strip("'\"")
+            choices_str = message.split("choose from")[1]
+            choices = [
+                c.strip().strip(",)'") for c in choices_str.split() if c.strip(",)")
+            ]
+
+            tips = get_close_matches(bad, choices, n=3, cutoff=0.6)
+            if tips:
+                message += f"\n\nDid you mean: {', '.join(tips)}?"
+
+        self.print_usage(sys.stderr)
+        self.exit(2, f"{self.prog}: error: {message}\n")

skip_trace/utils/http_client.py

@@ -0,0 +1,45 @@
+# skip_trace/utils/http_client.py
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ..config import CONFIG
+from ..exceptions import NetworkError
+
+_client: Optional[httpx.Client] = None
+
+
+def get_client() -> httpx.Client:
+    """Returns a shared httpx.Client instance."""
+    global _client
+    if _client is None:
+        http_config = CONFIG.get("http", {})
+        _client = httpx.Client(
+            headers={"User-Agent": http_config.get("user_agent", "skip-trace")},
+            timeout=http_config.get("timeout", 5),
+            follow_redirects=True,
+        )
+    return _client
+
+
+def make_request(url: str) -> httpx.Response:
+    """
+    Makes a GET request using the shared client and handles common errors.
+
+    :param url: The URL to fetch.
+    :raises NetworkError: If the request fails due to network issues or an error status code.
+    :return: The httpx.Response object.
+    """
+    client = get_client()
+    try:
+        response = client.get(url)
+        response.raise_for_status()
+        return response
+    except httpx.RequestError as e:
+        raise NetworkError(f"Network request to {e.request.url} failed: {e}") from e
+    except httpx.HTTPStatusError as e:
+        raise NetworkError(
+            f"Request to {e.request.url} failed with status {e.response.status_code}"
+        ) from e

skip_trace/utils/safe_targz.py

@@ -0,0 +1,161 @@
+# safe_targz.py
+from __future__ import annotations
+
+import os
+import tarfile
+from pathlib import Path, PurePosixPath
+from posixpath import normpath as posix_normpath
+from tarfile import TarFile, TarInfo
+from typing import Iterable, List, Tuple
+
+
+class TarExtractionError(Exception):
+    pass
+
+
+def _is_within(base: Path, target: Path) -> bool:
+    try:
+        base_resolved = base.resolve(strict=False)
+        target_resolved = target.resolve(strict=False)
+    except Exception:
+        # Fall back if resolve fails on not-yet-created parents
+        base_resolved = base.absolute()
+        target_resolved = target.absolute()
+    try:
+        target_resolved.relative_to(base_resolved)
+        return True
+    except Exception:
+        return False
+
+
+def _sanitize_member_name(name: str) -> str:
+    # Tar paths are POSIX; normalize and strip leading "./"
+    name = name.lstrip("./")
+    name = posix_normpath(name)
+    return name
+
+
+def _is_bad_path(name: str) -> bool:
+    # Reject absolute paths, Windows drive letters, parent traversal
+    if not name or name == ".":
+        return True
+    if name.startswith("/") or name.startswith("\\"):
+        return True
+    if ":" in name.split("/")[0]:  # e.g., "C:..." in archives created on Windows
+        return True
+    parts = PurePosixPath(name).parts
+    return any(p == ".." for p in parts)
+
+
+def _iter_safe_members(
+    tf: TarFile, dest: Path, allow_symlinks: bool
+) -> Iterable[Tuple[TarInfo, Path]]:
+    for m in tf.getmembers():
+        clean = _sanitize_member_name(m.name)
+        if _is_bad_path(clean):
+            continue
+        out_path = dest / Path(*PurePosixPath(clean).parts)
+        if not _is_within(dest, out_path):
+            continue
+
+        # Directories and regular files are allowed
+        if m.isdir():
+            yield (m, out_path)
+        elif m.isreg():
+            yield (m, out_path)
+        elif m.issym() or m.islnk():
+            if not allow_symlinks:
+                continue
+            # Only allow relative symlink targets that stay inside dest
+            link = m.linkname or ""
+            link = _sanitize_member_name(link)
+            if _is_bad_path(link):
+                continue
+            # Compute where the symlink would point to
+            # (symlink is created relative to out_path.parent)
+            target = out_path.parent / Path(*PurePosixPath(link).parts)
+            if not _is_within(dest, target):
+                continue
+            yield (m, out_path)
+        else:
+            # Block devices, fifos, sockets, etc.
+            continue
+
+
+def _extract_member(tf: TarFile, m: TarInfo, out_path: Path) -> None:
+    if m.isdir():
+        out_path.mkdir(parents=True, exist_ok=True)
+        return
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if m.isreg():
+        src = tf.extractfile(m)
+        if src is None:
+            raise TarExtractionError(f"Missing file data for {m.name!r}")
+        with src, open(out_path, "wb") as f:
+            # Stream copy without trusting metadata
+            for chunk in iter(lambda: src.read(1024 * 1024), b""):
+                f.write(chunk)
+        # Apply conservative mode for regular files (rw-r--r--)
+        try:
+            os.chmod(out_path, 0o644)
+        except Exception:
+            pass  # nosec # noqa
+        return
+
+    if m.issym() or m.islnk():
+        # Create a symlink with relative target; errors are non-fatal
+        try:
+            if out_path.exists() or out_path.is_symlink():
+                out_path.unlink()
+            os.symlink(m.linkname, out_path)
+        except Exception:
+            # If symlink creation is not permitted (e.g., Windows), skip
+            pass  # nosec # noqa
+        return
+
+
+def safe_extract_tar(
+    archive: Path, dest: Path, allow_symlinks: bool = False
+) -> List[Path]:
+    """
+    Safely extract a tar archive into 'dest'.
+    - Rejects absolute/parent-traversal paths and special members by default.
+    - Never calls TarFile.extractall() (satisfies Bandit B202).
+    - Returns list of extracted filesystem paths.
+    """
+    archive = Path(archive)
+    dest = Path(dest)
+    dest.mkdir(parents=True, exist_ok=True)
+
+    mode = "r"
+    if archive.suffixes[-2:] in [[".tar", ".gz"]] or archive.suffix == ".tgz":
+        mode = "r:gz"
+    elif archive.suffixes[-2:] == [".tar", ".bz2"]:
+        mode = "r:bz2"
+    elif archive.suffixes[-2:] == [".tar", ".xz"]:
+        mode = "r:xz"
+    elif archive.suffix == ".tar":
+        mode = "r:*"  # auto-detect compression
+    else:
+        raise TarExtractionError(f"Unsupported tar archive: {archive.name}")
+
+    extracted: List[Path] = []
+    with tarfile.open(archive, mode) as tf:  # type: ignore[call-overload]
+        for m, out_path in _iter_safe_members(tf, dest, allow_symlinks=allow_symlinks):
+            _extract_member(tf, m, out_path)
+            extracted.append(out_path)
+    return extracted
+
+
+def safe_extract_auto(
+    download_path: str, extract_dir: str, allow_symlinks: bool = False
+) -> List[Path]:
+    """
+    Backwards-compatible replacement for:
+        tarfile.open(...).extractall(extract_dir)
+    """
+    return safe_extract_tar(
+        Path(download_path), Path(extract_dir), allow_symlinks=allow_symlinks
+    )

skip_trace/utils/validation.py

@@ -0,0 +1,52 @@
+# skip_trace/utils/validation.py
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from email_validator import EmailNotValidError, validate_email
+
+logger = logging.getLogger(__name__)
+
+RESERVED_DOMAINS = {
+    "example.com",
+    "example.net",
+    "example.org",
+    "localhost",
+    "localhost.localdomain",
+}
+
+RESERVED_SUFFIXES = {".test", ".example", ".invalid", ".localhost"}
+
+
+def is_valid_email(email_string: str) -> Optional[str]:
+    """
+    Checks if a string is a valid email address using a robust library.
+
+    Args:
+        email_string: The string to validate.
+
+    Returns:
+        The normalized email address if valid, otherwise None.
+    """
+    if not isinstance(email_string, str):
+        return None
+
+    try:
+        # We only care about syntactic validity, not whether the domain's
+        # mail server is reachable, so we disable deliverability checks.
+        valid = validate_email(email_string, check_deliverability=False)
+
+        for reserved in RESERVED_DOMAINS:
+            if valid.domain.endswith(reserved):
+                return None
+
+        if valid.domain in RESERVED_DOMAINS or any(
+            valid.domain.endswith(suffix) for suffix in RESERVED_SUFFIXES
+        ):
+            return None
+
+        return valid.normalized
+    except EmailNotValidError as e:
+        logger.debug(f"String '{email_string}' is not a valid email: {e}")
+        return None