certora-prover-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: certora-prover-cli
-Version: 0.2.1
+Version: 0.2.3
 Summary: A Python API and CLI for parsing outputs from the Certora Prover
 Project-URL: Homepage, https://github.com/Certora/ProverCLI
 Project-URL: Repository, https://github.com/Certora/ProverCLI

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.2.3'
+__version_tuple__ = version_tuple = (0, 2, 3)
 
 __commit_id__ = commit_id = None

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/api/aws_data_fetcher.py

@@ -206,6 +206,13 @@ class AWSDataFetcher(BaseDataFetcher):
         except json.JSONDecodeError as e:
             raise ProverAPIError(f"Failed to parse statsdata.json for {job_identifier}: {e}")
 
+    def fetch_prover_version(self, job_identifier: str) -> Dict[str, Any]:
+        """Fetch a job's cvt_version.json (the prover version / commit it ran on)."""
+        try:
+            return cast(Dict[str, Any], json.loads(self.fetch_output_file(job_identifier, "cvt_version.json")))
+        except json.JSONDecodeError as e:
+            raise ProverAPIError(f"Failed to parse cvt_version.json for {job_identifier}: {e}")
+
     def fetch_output_file(self, job_identifier: str, rel_path: str) -> str:
         """Fetch the raw text of a Reports/-relative output file (e.g. unsat_core_map.json).
 

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/api/data_fetcher.py

@@ -263,6 +263,13 @@ class DataFetcher(BaseDataFetcher):
         except json.JSONDecodeError as e:
             raise ProverAPIError(f"Failed to parse statsdata.json for {job_identifier}: {e}")
 
+    def fetch_prover_version(self, job_identifier: str) -> Dict[str, Any]:
+        """Fetch a job's cvt_version.json (the prover version / commit it ran on)."""
+        try:
+            return cast(Dict[str, Any], json.loads(self.fetch_output_file(job_identifier, "cvt_version.json")))
+        except json.JSONDecodeError as e:
+            raise ProverAPIError(f"Failed to parse cvt_version.json for {job_identifier}: {e}")
+
     @handle_token_expiration
     def fetch_output_file(self, job_identifier: str, rel_path: str) -> str:
         """Fetch the raw text of a Reports/-relative output file (e.g. unsat_core_map.json).

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/api/local_data_fetcher.py

@@ -206,6 +206,20 @@ class LocalDataFetcher(BaseDataFetcher):
         except json.JSONDecodeError as e:
             raise ProverAPIError(f"Failed to parse statsdata.json: {e}")
 
+    def fetch_prover_version(self, job_identifier: str) -> Dict[str, Any]:
+        """Read cvt_version.json from a local emv-* folder's inputs/ directory."""
+        emv_path = os.path.abspath(job_identifier)
+        if not os.path.exists(emv_path):
+            raise JobNotFoundError(f"Local prover output path not found: {job_identifier}")
+        cvt_version_path = os.path.join(emv_path, "inputs", "cvt_version.json")
+        if not os.path.exists(cvt_version_path):
+            raise JobNotFoundError(f"cvt_version.json not found: {cvt_version_path}")
+        try:
+            with open(cvt_version_path, "r") as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise ProverAPIError(f"Failed to parse cvt_version.json: {e}")
+
     def fetch_outputs(self, job_identifier: str) -> bytes:
         """
         Fetch outputs archive for local job - not applicable for local files.

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/api/main.py

@@ -18,8 +18,10 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
 
-from ..auth import ProverAuth
+from ..auth import ProverAuth, organization_api_key
 from ..aws_auth import AWSAuth
 from ..breadcrumb import BreadcrumbParser
 from ..exceptions import JobNotFoundError, ProverAPIError
@@ -45,6 +47,49 @@ from .tree_parser import TreeParser
 from .url_utils import extract_job_id, extract_job_identifier
 
 
+#: Seconds a request may go without progress before it is abandoned. requests measures this per
+#: socket read rather than over the whole call, so a large download that keeps streaming is
+#: unaffected; it fires when the peer goes quiet. The headroom over the SigV4 fetcher's 30 is for
+#: the outputs archive, where the server has a lot to assemble before the first byte arrives.
+_REQUEST_TIMEOUT_S = 60
+
+#: A silent peer that resets or 5xx's mid-transfer is transient — the same request usually succeeds
+#: moments later. Retry it with exponential backoff (``backoff_factor`` doubles the wait each attempt:
+#: ~0.5s, 1s, 2s), capped at a few attempts so an unrecoverable endpoint still fails promptly rather
+#: than looping. Only the default idempotent methods are retried (urllib3 excludes POST), so a retry
+#: never re-runs a non-idempotent call.
+_MAX_RETRIES = 3
+_BACKOFF_FACTOR = 0.5
+
+
+class _TimedSession(requests.Session):
+    """A session whose requests give up on a silent peer and retry a transient failure.
+
+    requests applies no timeout of its own, so an unresponsive endpoint holds its caller for as
+    long as the socket stays open, and a caller that handed the call to a thread cannot get that
+    thread back. Every ``get``/``post`` on a session goes through ``request``, so the timeout default
+    belongs here rather than at each call site. A caller that passes its own timeout keeps it. The
+    mounted adapter additionally retries transient connection/read failures and 502/503/504 with
+    exponential backoff.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        retry = Retry(
+            total=_MAX_RETRIES,
+            backoff_factor=_BACKOFF_FACTOR,
+            status_forcelist=(502, 503, 504),
+            raise_on_status=False,  # leave status-code handling to the callers
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self.mount("https://", adapter)
+        self.mount("http://", adapter)
+
+    def request(self, *args, **kwargs) -> requests.Response:
+        kwargs.setdefault("timeout", _REQUEST_TIMEOUT_S)
+        return super().request(*args, **kwargs)
+
+
 # Per-job locks for thread-safe fetch operations
 _fetch_locks: dict[str, threading.Lock] = {}
 _fetch_locks_lock = threading.Lock()
@@ -143,8 +188,11 @@ class ProverOutputAPI:
         # Initialize appropriate data fetcher
         if use_local:
             self.data_fetcher = LocalDataFetcher()
-        elif os.getenv("CI") and self._is_aws_available():
-            # In CI with AWS credentials, use AWS Lambda authentication
+        elif organization_api_key() is None and os.getenv("CI") and self._is_aws_available():
+            # In CI with AWS credentials, use AWS Lambda authentication. The
+            # path exists for automation that has AWS credentials and no
+            # Certora login, so a key the caller supplied on purpose takes
+            # precedence over it.
             self.logger.info("Using AWS Lambda authentication in CI")
             aws_auth = AWSAuth()
             aws_session = aws_auth.get_session()
@@ -152,15 +200,19 @@ class ProverOutputAPI:
             # No session needed for AWS auth
             self.session = None
         else:
-            # Regular cookie-based authentication
+            # Key or cookie authentication; ProverAuth resolves which applies
             self.auth = ProverAuth()
             self._setup_session()
 
     def _setup_session(self, force_relogin: bool = False):
-        """Setup session with authentication cookies."""
-        self.session = requests.Session()
+        """Setup session with whichever credential ProverAuth resolves: an
+        organization API key on the Authorization header, or login cookies."""
+        self.session = _TimedSession()
         # Set up authentication
         self.session.cookies = self.auth.get_auth_cookies(force_relogin=force_relogin)
+        # An organization API key travels on every request of the session;
+        # with cookie authentication this adds nothing.
+        self.session.headers.update(self.auth.get_auth_headers())
         self.data_fetcher = DataFetcher(self.session, api_instance=self, api_base_url=self.api_base_url)
 
     def _is_aws_available(self) -> bool:
@@ -753,6 +805,26 @@ class ProverOutputAPI:
         except Exception as e:
             raise ProverAPIError(f"Failed to get statsdata for job {job_identifier}: {e}")
 
+    def get_prover_version(self, job_input: str) -> Dict[str, Any]:
+        """
+        Get a job's cvt_version.json — the prover version / commit it ran on.
+
+        Args:
+            job_input: Job URL, job ID, or local emv-* path
+
+        Returns:
+            Parsed cvt_version.json contents (e.g. a "version" field and commit hashes)
+
+        Raises:
+            ProverAPIError: If fetching fails
+        """
+        job_identifier = self._extract_job_identifier(job_input)
+
+        try:
+            return self.data_fetcher.fetch_prover_version(job_identifier)
+        except Exception as e:
+            raise ProverAPIError(f"Failed to get prover version for job {job_identifier}: {e}")
+
     def get_console_logs(self, job_input: str) -> str:
         """
         Get console logs for a job. This contains the full console output 

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/auth.py

@@ -83,6 +83,30 @@ except ImportError:
     SERVERS = None
 
 
+# Environment variables holding an organization API key, in the order they are
+# consulted. The env-scoped name comes first so a machine configured for one
+# environment cannot be pointed at another by a stray generic value.
+_API_KEY_ENV_VARS: Dict[LoginEnv, tuple[str, ...]] = {
+    "prod": ("CERTORA_API_KEY_PROD", "CERTORA_API_KEY"),
+    "stg": ("CERTORA_API_KEY_STG", "CERTORA_API_KEY"),
+    "dev": ("CERTORA_API_KEY_DEV", "CERTORA_API_KEY"),
+}
+
+
+def organization_api_key() -> str | None:
+    """The organization API key for the current login env, if one is set.
+
+    This is the key issued on the organization's API page, not ``CERTORAKEY``.
+    The API accepts it on the ``Authorization`` header and exchanges it for a
+    short-lived token itself, so a caller that has one needs no browser login.
+    """
+    for name in _API_KEY_ENV_VARS[resolve_login_env()]:
+        value = (os.environ.get(name) or "").strip()
+        if value:
+            return value
+    return None
+
+
 class ProverAuth:
     """
     Handles authentication with Certora Prover API using certora_login.
@@ -129,6 +153,11 @@ class ProverAuth:
         """
         cookies = requests.cookies.RequestsCookieJar()
 
+        # An organization API key authenticates on the header instead, so
+        # there is nothing to log in for and no cookie to carry.
+        if organization_api_key() is not None:
+            return cookies
+
         # Skip authentication in CI environment - return empty cookies
         if os.getenv("CI"):
             return cookies
@@ -163,10 +192,17 @@ class ProverAuth:
         """
         Get authentication headers for API requests.
 
-        Note: Headers are typically not needed when using cookies from certora_login.
-        This method returns an empty dict as headers are handled via cookies.
+        An organization API key authenticates on the ``Authorization``
+        header: the API classifies the credential by shape and exchanges an
+        opaque key for a short-lived token on the caller's behalf, so no
+        browser login and no cookie are involved. Without a key the cookies
+        from certora_login carry the identity and there is no header to add.
 
         Returns:
-            Empty dictionary (authentication is via cookies)
+            The bearer header for the organization API key, or an empty
+            dictionary when authentication is via cookies.
         """
-        return {}
+        key = organization_api_key()
+        if key is None:
+            return {}
+        return {"Authorization": f"Bearer {key}"}

{certora_prover_cli-0.2.1 → certora_prover_cli-0.2.3}/src/prover_output_utility/prover_cli.py

@@ -193,6 +193,11 @@ Environment Variables:
     parser.add_argument("--calltrace", help="Get calltrace for specific output file path")
     parser.add_argument("--breadcrumbs", help="Get breadcrumb trace from DAP file")
     parser.add_argument("--statsdata", action="store_true", help="Get statsdata.json for the job")
+    parser.add_argument(
+        "--prover-version",
+        action="store_true",
+        help="Get cvt_version.json for the job (the prover version / commit it ran on)",
+    )
     parser.add_argument(
         "--all-checks",
         action="store_true",
@@ -458,6 +463,11 @@ Environment Variables:
             statsdata = api.get_statsdata(job_input)
             result = {"job_id": job_input, "statsdata": statsdata}
 
+        elif args.prover_version:
+            # Get cvt_version.json (prover version / commit the job ran on)
+            prover_version = api.get_prover_version(job_input)
+            result = {"job_id": job_input, "prover_version": prover_version}
+
         elif args.all_checks:
             # Get all checks (both successful and failed)
             all_checks = api.get_all_checks(job_input)
@@ -534,6 +544,8 @@ Environment Variables:
                 )
             elif args.statsdata:
                 print(f"✅ Statsdata retrieved. Results written to {args.output}")
+            elif args.prover_version:
+                print(f"✅ prover_version retrieved. Results written to {args.output}")
             elif args.all_checks:
                 count = result.get("checks_count", 0)
                 print(f"Found {count} checks (all tree nodes). Results written to {args.output}")
@@ -611,6 +623,12 @@ Environment Variables:
                         print(f"  ... and {len(result['statsdata']) - 5} more keys")
                     print("Use --format json to see full data")
 
+            elif args.prover_version:
+                print(f"Job ID: {job_input}")
+                print("✅ Retrieved cvt_version.json")
+                for key, value in result["prover_version"].items():
+                    print(f"  {key}: {value}")
+
             elif args.all_checks:
                 # Show all checks (both successful and failed)
                 print(f"Job ID: {job_input}")