pkgwhy 1.0.0__py3-none-any.whl

pkgwhy/metadata/installed.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from importlib import metadata
+from importlib.metadata import Distribution
+
+from packaging.utils import canonicalize_name
+
+from pkgwhy.core.models import PackageIdentity, PackageMetadata, ProjectUrls
+
+
+def normalize_package_name(name: str) -> str:
+    return canonicalize_name(name)
+
+
+def list_installed_packages() -> list[PackageMetadata]:
+    packages = [metadata_from_distribution(dist) for dist in metadata.distributions()]
+    return sorted(packages, key=lambda package: package.identity.normalized_name)
+
+
+def get_installed_package(name: str) -> PackageMetadata | None:
+    dist = find_distribution(name)
+    return metadata_from_distribution(dist) if dist is not None else None
+
+
+def get_distribution(name: str) -> Distribution | None:
+    """Return the installed distribution for callers that need file-level inspection."""
+    return find_distribution(name)
+
+
+def find_distribution(name: str) -> Distribution | None:
+    wanted = normalize_package_name(name)
+    for dist in metadata.distributions():
+        dist_name = dist.metadata.get("Name")
+        if dist_name and normalize_package_name(dist_name) == wanted:
+            return dist
+    return None
+
+
+def metadata_from_distribution(dist: Distribution) -> PackageMetadata:
+    meta = dist.metadata
+    name = meta.get("Name") or "unknown"
+    project_urls = parse_project_urls(meta.get_all("Project-URL") or [])
+    entry_points = [
+        f"{entry_point.group}:{entry_point.name}={entry_point.value}"
+        for entry_point in dist.entry_points
+    ]
+    return PackageMetadata(
+        identity=PackageIdentity(
+            name=name,
+            normalized_name=normalize_package_name(name),
+            version=meta.get("Version"),
+        ),
+        summary=meta.get("Summary"),
+        author=meta.get("Author"),
+        maintainer=meta.get("Maintainer"),
+        license=meta.get("License"),
+        requires=list(meta.get_all("Requires-Dist") or []),
+        project_urls=project_urls,
+        entry_points=entry_points,
+        metadata_available=True,
+    )
+
+
+def parse_project_urls(values: list[str]) -> ProjectUrls:
+    raw: dict[str, str] = {}
+    homepage: str | None = None
+    repository: str | None = None
+    documentation: str | None = None
+    for value in values:
+        if "," not in value:
+            continue
+        label, url = value.split(",", 1)
+        label = label.strip()
+        url = url.strip()
+        raw[label] = url
+        key = label.lower()
+        if homepage is None and key in {"homepage", "home-page"}:
+            homepage = url
+        if repository is None and any(token in key for token in ("source", "repository", "github", "code")):
+            repository = url
+        if documentation is None and any(token in key for token in ("doc", "documentation")):
+            documentation = url
+    return ProjectUrls(homepage=homepage, repository=repository, documentation=documentation, raw=raw)

pkgwhy/metadata/pypi.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+from urllib import error, request
+from urllib.parse import quote
+
+from packaging.version import InvalidVersion, Version
+
+from pkgwhy.core.models import Confidence, PackageProvenance
+from pkgwhy.metadata.installed import normalize_package_name
+
+PYPI_JSON_URL = "https://pypi.org/pypi/{package}/json"
+
+
+class PyPIMetadataError(RuntimeError):
+    """Raised when optional PyPI metadata lookup fails."""
+
+
+def fetch_pypi_project(package_name: str, *, timeout_seconds: float = 10.0) -> dict[str, Any]:
+    """Fetch PyPI JSON explicitly; callers decide when network access is allowed."""
+    url = PYPI_JSON_URL.format(package=quote(package_name, safe=""))
+    req = request.Request(url, headers={"Accept": "application/json"}, method="GET")
+    try:
+        with request.urlopen(req, timeout=timeout_seconds) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except (OSError, error.HTTPError, json.JSONDecodeError) as exc:
+        raise PyPIMetadataError(f"PyPI metadata lookup failed for {package_name}: {exc}") from exc
+
+
+def provenance_from_pypi_payload(
+    package_name: str,
+    payload: dict[str, Any],
+    *,
+    audited_version: str | None = None,
+) -> PackageProvenance:
+    """Build a conservative provenance summary from a PyPI JSON payload."""
+    info = payload.get("info")
+    info = info if isinstance(info, dict) else {}
+    reported_version = audited_version or _string_or_none(info.get("version"))
+    project_urls = info.get("project_urls")
+    project_urls = project_urls if isinstance(project_urls, dict) else {}
+    normalized_urls = {
+        str(key): value.strip()
+        for key, value in project_urls.items()
+        if isinstance(value, str) and value.strip()
+    }
+    repository_url = _find_url(normalized_urls, ("source", "repository", "github", "code"))
+    documentation_url = _find_url(normalized_urls, ("doc", "documentation"))
+    homepage_url = _string_or_none(info.get("home_page")) or _find_url(normalized_urls, ("homepage", "home-page"))
+    releases = payload.get("releases")
+    latest_release_date = _latest_release_date(releases)
+    audited_release_date = _release_date(releases, reported_version)
+    source_distribution_status = _source_distribution_status(releases, reported_version)
+    evidence = ["Read project metadata from PyPI JSON payload."]
+    warnings = [
+        "Trusted Publishing status is not inferred from PyPI project JSON.",
+        "Attestation verification is not implemented.",
+        "Source distribution versus wheel comparison is not implemented.",
+    ]
+
+    if repository_url:
+        evidence.append(f"Repository URL declared in PyPI metadata: {repository_url}")
+    else:
+        warnings.append("PyPI metadata does not declare a repository URL.")
+
+    if audited_version is not None and reported_version:
+        if audited_release_date:
+            evidence.append(f"Observed PyPI upload time for audited version {reported_version}: {audited_release_date}")
+            release_activity_status = f"audited_release_upload:{audited_release_date}"
+        else:
+            release_activity_status = "unknown"
+            warnings.append(f"PyPI metadata did not include release files for audited version {reported_version}.")
+            if latest_release_date:
+                evidence.append(f"Latest observed PyPI release upload time: {latest_release_date}")
+    elif latest_release_date:
+        evidence.append(f"Latest observed PyPI release upload time: {latest_release_date}")
+        release_activity_status = f"latest_release_upload:{latest_release_date}"
+    else:
+        release_activity_status = "unknown"
+        warnings.append("Could not determine latest release upload time from PyPI metadata.")
+
+    if source_distribution_status == "present":
+        evidence.append("PyPI metadata lists at least one source distribution for the inspected release.")
+    elif source_distribution_status == "not_found":
+        warnings.append("PyPI metadata did not list a source distribution for the inspected release.")
+    else:
+        warnings.append("Could not determine source distribution status from PyPI metadata.")
+
+    return PackageProvenance(
+        package=normalize_package_name(package_name),
+        version=reported_version,
+        repository_url=repository_url,
+        documentation_url=documentation_url,
+        homepage_url=homepage_url,
+        project_urls=normalized_urls,
+        metadata_source="pypi_json",
+        source_distribution_status=source_distribution_status,
+        trusted_publishing_status="unknown",
+        attestation_status="not_implemented",
+        release_activity_status=release_activity_status,
+        confidence=Confidence.MEDIUM if repository_url or latest_release_date else Confidence.LOW,
+        warnings=warnings,
+        evidence=evidence,
+    )
+
+
+def _find_url(values: dict[str, str], tokens: tuple[str, ...]) -> str | None:
+    for key, value in values.items():
+        lower = key.lower()
+        if any(token in lower for token in tokens):
+            return value
+    return None
+
+
+def _latest_release_date(releases: Any) -> str | None:
+    if not isinstance(releases, dict):
+        return None
+    latest: datetime | None = None
+    for files in releases.values():
+        if not isinstance(files, list):
+            continue
+        for file_info in files:
+            if not isinstance(file_info, dict):
+                continue
+            uploaded_at = _string_or_none(file_info.get("upload_time_iso_8601")) or _string_or_none(file_info.get("upload_time"))
+            if uploaded_at is None:
+                continue
+            parsed = _parse_datetime(uploaded_at)
+            if parsed is not None and (latest is None or parsed > latest):
+                latest = parsed
+    return latest.date().isoformat() if latest else None
+
+
+def _release_date(releases: Any, version: str | None) -> str | None:
+    files = _release_files(releases, version)
+    if files is None:
+        return None
+    latest: datetime | None = None
+    for file_info in files:
+        if not isinstance(file_info, dict):
+            continue
+        uploaded_at = _string_or_none(file_info.get("upload_time_iso_8601")) or _string_or_none(file_info.get("upload_time"))
+        if uploaded_at is None:
+            continue
+        parsed = _parse_datetime(uploaded_at)
+        if parsed is not None and (latest is None or parsed > latest):
+            latest = parsed
+    return latest.date().isoformat() if latest else None
+
+
+def _source_distribution_status(releases: Any, version: str | None) -> str:
+    files = _release_files(releases, version)
+    if files is None:
+        return "unknown"
+    for file_info in files:
+        if not isinstance(file_info, dict):
+            continue
+        package_type = _string_or_none(file_info.get("packagetype"))
+        filename = _string_or_none(file_info.get("filename"))
+        if package_type == "sdist" or (filename is not None and filename.endswith((".tar.gz", ".zip"))):
+            return "present"
+    return "not_found"
+
+
+def _release_files(releases: Any, version: str | None) -> list[Any] | None:
+    if not isinstance(releases, dict) or version is None:
+        return None
+    files = releases.get(version)
+    if isinstance(files, list):
+        return files
+    try:
+        target = Version(version)
+    except InvalidVersion:
+        return None
+    for release_version, release_files in releases.items():
+        if not isinstance(release_version, str) or not isinstance(release_files, list):
+            continue
+        try:
+            if Version(release_version) == target:
+                return release_files
+        except InvalidVersion:
+            continue
+    return None
+
+
+def _parse_datetime(value: str) -> datetime | None:
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _string_or_none(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped if stripped else None

pkgwhy/policy/__init__.py

@@ -0,0 +1 @@
+"""Local policy helpers for package and private-tool decisions."""

pkgwhy/policy/agent_policy.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from pkgwhy.core.models import (
+    AgentDecision,
+    AgentPackagePrecheckResult,
+    AgentPolicyConfig,
+    PackageJudgement,
+    RiskLevel,
+)
+
+NON_INTERACTIVE_PACKAGE_ALLOWED_DECISIONS = {AgentDecision.ALLOW, AgentDecision.ALLOW_WITH_CAUTION}
+
+
+def default_agent_policy() -> AgentPolicyConfig:
+    """Return conservative default policy settings for agent package decisions."""
+
+    return AgentPolicyConfig()
+
+
+def evaluate_package_policy(
+    judgement: PackageJudgement,
+    *,
+    non_interactive: bool = True,
+    policy: AgentPolicyConfig | None = None,
+) -> AgentPackagePrecheckResult:
+    """Apply policy-as-code to a package judgement without changing the judgement itself."""
+
+    active_policy = policy or default_agent_policy()
+    decision = judgement.decision
+    reasons: list[str] = []
+    warnings = list(judgement.warnings)
+    decision_source = "package_judgement"
+
+    risk_policy_decision = _decision_for_risk(judgement.risk_level, active_policy, non_interactive=non_interactive)
+    if risk_policy_decision is not None:
+        decision = _stricter_decision(decision, risk_policy_decision)
+        decision_source = "agent_policy"
+        reasons.append(_risk_policy_reason(judgement.risk_level, non_interactive=non_interactive))
+
+    if non_interactive and judgement.decision not in NON_INTERACTIVE_PACKAGE_ALLOWED_DECISIONS:
+        decision = _stricter_decision(decision, active_policy.non_interactive_default_decision)
+        decision_source = "agent_policy"
+        reasons.append(f"Non-interactive package use is not allowed for decision: {judgement.decision.value}.")
+
+    if active_policy.require_pkgwhy_judgement and not judgement.evidence:
+        decision = _stricter_decision(decision, AgentDecision.REVIEW_MANUALLY)
+        decision_source = "agent_policy"
+        reasons.append("Policy requires a pkgwhy judgement with supporting evidence.")
+
+    recommendation = _recommendation_for_decision(decision, judgement.recommendation, non_interactive=non_interactive)
+    return AgentPackagePrecheckResult(
+        package=judgement.package,
+        version=judgement.version,
+        non_interactive=non_interactive,
+        decision=decision,
+        risk_level=judgement.risk_level,
+        confidence=judgement.confidence,
+        policy_decision_source=decision_source,
+        reasons=reasons,
+        warnings=warnings,
+        recommendation=recommendation,
+        package_judgement=judgement,
+    )
+
+
+def _decision_for_risk(
+    risk_level: RiskLevel,
+    policy: AgentPolicyConfig,
+    *,
+    non_interactive: bool,
+) -> AgentDecision | None:
+    if risk_level == RiskLevel.UNKNOWN:
+        return (
+            policy.non_interactive_unknown_package_decision
+            if non_interactive
+            else policy.unknown_package_decision
+        )
+    if risk_level == RiskLevel.HIGH:
+        return policy.non_interactive_high_risk_package_decision if non_interactive else policy.high_risk_package_decision
+    if risk_level == RiskLevel.CRITICAL:
+        return (
+            policy.non_interactive_critical_risk_package_decision
+            if non_interactive
+            else policy.critical_risk_package_decision
+        )
+    return None
+
+
+def _risk_policy_reason(risk_level: RiskLevel, *, non_interactive: bool) -> str:
+    mode = "non-interactive agent use" if non_interactive else "agent use"
+    return f"Policy requires a stricter decision for {risk_level.value}-risk packages in {mode}."
+
+
+def _stricter_decision(current: AgentDecision, candidate: AgentDecision) -> AgentDecision:
+    order = {
+        AgentDecision.ALLOW: 0,
+        AgentDecision.ALLOW_WITH_CAUTION: 1,
+        AgentDecision.REVIEW_MANUALLY: 2,
+        AgentDecision.SANDBOX_ONLY: 3,
+        AgentDecision.BLOCK: 4,
+    }
+    return candidate if order[candidate] > order[current] else current
+
+
+def _recommendation_for_decision(decision: AgentDecision, fallback: str, *, non_interactive: bool) -> str:
+    if decision == AgentDecision.BLOCK:
+        if non_interactive:
+            return "Block non-interactive package use until a human reviews the judgement evidence."
+        return "Block package use until a human reviews the evidence."
+    if decision == AgentDecision.REVIEW_MANUALLY:
+        return "Manual review is required before an agent uses this package."
+    if decision == AgentDecision.SANDBOX_ONLY:
+        return "Use only in a real sandboxed environment; a Python virtual environment is not a full OS sandbox."
+    return fallback

pkgwhy/policy/audit_log.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pkgwhy.core.models import AgentPackagePrecheckResult
+from pkgwhy.registry.local import config_dir
+
+AGENT_DECISION_LOG_SCHEMA_VERSION = "pkgwhy.agent_decision_log.v1"
+
+
+def write_agent_package_decision_log(
+    result: AgentPackagePrecheckResult,
+    *,
+    log_root: Path | None = None,
+) -> Path | None:
+    """Write a compact local audit record for an agent package decision.
+
+    Audit logging is best-effort: an unwritable local config directory must not
+    prevent the policy decision itself from being returned.
+    """
+
+    created_at = datetime.now(tz=UTC)
+    root = log_root or config_dir() / "agent-decisions"
+    package_dir = root / _safe_path_segment(result.package)
+    try:
+        package_dir.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return None
+    log_path = package_dir / f"{created_at.strftime('%Y%m%dT%H%M%S%fZ')}.json"
+    payload = {
+        "schema_version": AGENT_DECISION_LOG_SCHEMA_VERSION,
+        "created_at": created_at.isoformat(),
+        "precheck_schema_version": result.schema_version,
+        "policy_schema_version": result.policy_schema_version,
+        "target_type": result.target_type,
+        "package": result.package,
+        "version": result.version,
+        "non_interactive": result.non_interactive,
+        "decision": result.decision.value,
+        "risk_level": result.risk_level.value,
+        "confidence": result.confidence.value,
+        "policy_decision_source": result.policy_decision_source,
+        "reason_count": len(result.reasons),
+        "warning_count": len(result.warnings),
+        "reasons": list(result.reasons),
+        "warnings": list(result.warnings),
+    }
+    try:
+        log_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    except OSError:
+        return None
+    return log_path
+
+
+def _safe_path_segment(value: str) -> str:
+    normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip(".-_")
+    return normalized or "unknown-package"

pkgwhy/policy/tool_execution.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pkgwhy.core.models import AgentDecision, HashStatus, ToolJudgement
+
+SIGNATURE_STATUS_VERIFIED = "verified"
+SIGNATURE_STATUS_NOT_IMPLEMENTED = "not_implemented"
+
+
+@dataclass(frozen=True)
+class ToolExecutionPolicy:
+    """Conservative local execution policy for private registry tools."""
+
+    allow_unsigned_tools: bool = False
+    allow_unpinned_dependencies: bool = False
+    require_hash_verification: bool = True
+    require_signature_verification: bool = False
+
+
+@dataclass(frozen=True)
+class ToolExecutionPolicyResult:
+    """Policy decision used before local private-tool execution."""
+
+    allowed: bool
+    decision: AgentDecision
+    reasons: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+NON_INTERACTIVE_ALLOWED_DECISIONS = {AgentDecision.ALLOW, AgentDecision.ALLOW_WITH_CAUTION}
+
+
+def evaluate_tool_execution_policy(
+    judgement: ToolJudgement,
+    *,
+    non_interactive: bool = False,
+    policy: ToolExecutionPolicy | None = None,
+) -> ToolExecutionPolicyResult:
+    active_policy = policy or ToolExecutionPolicy()
+    reasons: list[str] = []
+    warnings: list[str] = []
+
+    if active_policy.require_hash_verification and judgement.hash_status != HashStatus.VERIFIED:
+        reasons.append(f"Tool bundle hash is not verified: {judgement.hash_status.value}.")
+
+    if judgement.decision == AgentDecision.BLOCK:
+        reasons.append("Tool judgement blocks execution.")
+    elif judgement.decision == AgentDecision.SANDBOX_ONLY:
+        reasons.append("Tool requires sandbox-only execution, but the local runner is not a full OS sandbox.")
+
+    if judgement.signature_status != SIGNATURE_STATUS_VERIFIED:
+        message = "Tool signature verification is not implemented; treat this tool as unsigned."
+        if active_policy.require_signature_verification:
+            reasons.append(message)
+        elif not active_policy.allow_unsigned_tools:
+            warnings.append(message)
+
+    if judgement.manifest.dependencies:
+        if active_policy.allow_unpinned_dependencies:
+            warnings.append("Tool dependencies are declared, but dependency installation is not implemented in the runner.")
+        else:
+            reasons.append("Dependency installation is not implemented for tools with declared dependencies.")
+
+    if non_interactive:
+        if judgement.decision not in NON_INTERACTIVE_ALLOWED_DECISIONS:
+            reasons.append(f"Non-interactive execution is not allowed for judgement decision: {judgement.decision.value}.")
+        if judgement.manifest.agent.non_interactive_decision not in NON_INTERACTIVE_ALLOWED_DECISIONS:
+            reasons.append(
+                "Manifest agent policy does not allow non-interactive execution: "
+                f"{judgement.manifest.agent.non_interactive_decision.value}."
+            )
+
+    allowed = not reasons
+    decision = AgentDecision.BLOCK if reasons else (AgentDecision.REVIEW_MANUALLY if warnings else judgement.decision)
+    return ToolExecutionPolicyResult(allowed=allowed, decision=decision, reasons=reasons, warnings=warnings)

pkgwhy/provenance/__init__.py

@@ -0,0 +1,2 @@
+"""Source-trust and provenance signal helpers."""
+

pkgwhy/provenance/installed.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pkgwhy.core.models import Confidence, PackageMetadata, PackageProvenance
+
+
+def assess_installed_provenance(metadata: PackageMetadata) -> PackageProvenance:
+    """Summarize source-trust signals available from installed metadata only."""
+    urls = metadata.project_urls
+    raw_urls = dict(urls.raw)
+    evidence = ["Read project URLs from installed distribution metadata."]
+    warnings = [
+        "Trusted Publishing status is unknown from installed metadata.",
+        "Attestation verification is not implemented.",
+        "Source distribution versus wheel comparison is not implemented.",
+        "Release activity requires optional online metadata and is not available from installed metadata alone.",
+    ]
+    confidence = Confidence.LOW
+
+    if urls.repository:
+        evidence.append(f"Repository URL declared in installed metadata: {urls.repository}")
+        confidence = Confidence.MEDIUM
+    else:
+        warnings.append("No repository URL was found in installed metadata.")
+
+    if urls.documentation:
+        evidence.append(f"Documentation URL declared in installed metadata: {urls.documentation}")
+
+    if urls.homepage:
+        evidence.append(f"Homepage URL declared in installed metadata: {urls.homepage}")
+
+    if not raw_urls:
+        warnings.append("Installed metadata does not declare project URLs.")
+
+    return PackageProvenance(
+        package=metadata.identity.normalized_name,
+        version=metadata.identity.version,
+        repository_url=urls.repository,
+        documentation_url=urls.documentation,
+        homepage_url=urls.homepage,
+        project_urls=raw_urls,
+        metadata_source="installed_distribution_metadata",
+        confidence=confidence,
+        warnings=warnings,
+        evidence=evidence,
+    )

pkgwhy/registry/__init__.py

@@ -0,0 +1,2 @@
+"""Local private registry support."""
+