PyGeoFetch 2.6.2.1__py3-none-any.whl → 2.6.2.2__py3-none-any.whl

pygeofetch/__init__.py

@@ -30,7 +30,7 @@ CLI::
     pygeofetch doctor
 """
 
-__version__ = "2.6.2.1"
+__version__ = "2.6.2.2"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

pygeofetch/cli/download_commands.py

@@ -114,6 +114,36 @@ def download() -> None:
     help='Comma-separated band names to download e.g. "B02,B03,B04" (default: all data assets).',
 )
 @click.option("--json", "as_json", is_flag=True, help="Output results summary as JSON.")
+@click.option(
+    "--validate-optical",
+    is_flag=True,
+    default=False,
+    help=(
+        "Run optical preflight validation as a final gate before "
+        "downloading (AOI coverage, cloud cover, required bands, "
+        "processing level, temporal bounds). Items that fail are "
+        "never attempted -- a failed result explaining why is "
+        "returned in their place, same position, so output length "
+        "always matches input."
+    ),
+)
+@click.option(
+    "--optical-max-cloud-cover",
+    default=None,
+    type=float,
+    help="Override the max cloud cover threshold used by --validate-optical (default 20.0).",
+)
+@click.option(
+    "--optical-min-coverage",
+    default=None,
+    type=float,
+    help="Override the min AOI coverage ratio used by --validate-optical, 0-1 (default 0.8).",
+)
+@click.option(
+    "--optical-required-bands",
+    default=None,
+    help="Comma-separated required bands for --validate-optical (default B02,B03,B04,B08,SCL).",
+)
 def download_run(
     from_search,
     scene_ids,
@@ -132,6 +162,10 @@ def download_run(
     overwrite,
     bands,
     as_json,
+    validate_optical,
+    optical_max_cloud_cover,
+    optical_min_coverage,
+    optical_required_bands,
 ) -> None:
     """
     Download satellite data products from a search results file or scene IDs.
@@ -151,6 +185,11 @@ def download_run(
           --notify webhook:https://hooks.slack.com/T01/B01/XYZ \\
           --notify email:user@example.com \\
           --on-failure skip
+
+      # With optical preflight validation as a final gate before downloading
+      pygeofetch download run \\
+          --from-search results.geojson --output ./data/ \\
+          --validate-optical --optical-max-cloud-cover 10
     """
     from pygeofetch.core.engine import PyGeoFetch
     from pygeofetch.core.searcher import FederatedSearcher
@@ -218,6 +257,24 @@ def download_run(
 
     sb = PyGeoFetch()
 
+    if validate_optical and (
+        optical_max_cloud_cover,
+        optical_min_coverage,
+        optical_required_bands,
+    ) != (None, None, None):
+        from pygeofetch.validation import OpticalValidationConfig
+
+        overrides = {}
+        if optical_max_cloud_cover is not None:
+            overrides["max_cloud_cover_pct"] = optical_max_cloud_cover
+        if optical_min_coverage is not None:
+            overrides["min_coverage_ratio"] = optical_min_coverage
+        if optical_required_bands is not None:
+            overrides["required_bands"] = [
+                b.strip() for b in optical_required_bands.split(",")
+            ]
+        sb.optical_validation_config = OpticalValidationConfig(**overrides)
+
     # Load data
     if from_search:
         data_list = FederatedSearcher.load_results(Path(from_search))
@@ -273,7 +330,11 @@ def download_run(
 
         # Use sb.download() with the already-sliced data_list (respects --max-items)
         results = sb.download(
-            data_list, Path(output), options, item_done_callback=on_item_done
+            data_list,
+            Path(output),
+            options,
+            item_done_callback=on_item_done,
+            validate_optical=validate_optical,
         )
 
     succeeded = [r for r in results if r.success]

pygeofetch/cli/search_commands.py

@@ -104,6 +104,34 @@ def search() -> None:
     "--timeout", default=60, show_default=True, help="Per-provider timeout in seconds."
 )
 @click.option("--no-cache", is_flag=True, default=False, help="Bypass result cache.")
+@click.option(
+    "--validate-optical",
+    is_flag=True,
+    default=False,
+    help=(
+        "Run optical preflight validation (AOI coverage, cloud cover, "
+        "required bands, processing level, temporal bounds) on results "
+        "before returning them. Not appropriate for SAR/InSAR searches "
+        "-- the default required bands are optical band names."
+    ),
+)
+@click.option(
+    "--optical-max-cloud-cover",
+    default=None,
+    type=float,
+    help="Override the max cloud cover threshold used by --validate-optical (default 20.0).",
+)
+@click.option(
+    "--optical-min-coverage",
+    default=None,
+    type=float,
+    help="Override the min AOI coverage ratio used by --validate-optical, 0-1 (default 0.8).",
+)
+@click.option(
+    "--optical-required-bands",
+    default=None,
+    help="Comma-separated required bands for --validate-optical (default B02,B03,B04,B08,SCL).",
+)
 def search_run(
     bbox,
     geometry_file,
@@ -125,6 +153,10 @@ def search_run(
     on_provider_failure,
     timeout,
     no_cache,
+    validate_optical,
+    optical_max_cloud_cover,
+    optical_min_coverage,
+    optical_required_bands,
 ) -> None:
     """
     Search for satellite imagery across one or more providers.
@@ -146,6 +178,11 @@ def search_run(
           --geometry-file area.geojson \\
           --cql2 "eo:cloud_cover < 5 AND platform = 'sentinel-2b'" \\
           --format geoparquet --output results.parquet
+
+      # With optical preflight validation (skip cloudy/off-target/wrong-level scenes)
+      pygeofetch search run \\
+          --bbox "-74,40,-73,41" --cloud-cover 0-100 \\
+          --validate-optical --optical-max-cloud-cover 10 --optical-min-coverage 0.9
     """
     from pygeofetch.core.engine import PyGeoFetch
     from pygeofetch.models.search_query import BoundingBox, SearchQuery
@@ -245,10 +282,33 @@ def search_run(
 
     sb = PyGeoFetch()
 
+    if validate_optical and (
+        optical_max_cloud_cover,
+        optical_min_coverage,
+        optical_required_bands,
+    ) != (None, None, None):
+        from pygeofetch.validation import OpticalValidationConfig
+
+        overrides = {}
+        if optical_max_cloud_cover is not None:
+            overrides["max_cloud_cover_pct"] = optical_max_cloud_cover
+        if optical_min_coverage is not None:
+            overrides["min_coverage_ratio"] = optical_min_coverage
+        if optical_required_bands is not None:
+            overrides["required_bands"] = [
+                b.strip() for b in optical_required_bands.split(",")
+            ]
+        sb.optical_validation_config = OpticalValidationConfig(**overrides)
+
     with console.status(
         f"[cyan]Searching {len(provider_list or [])} provider(s)...[/]"
     ):
-        results = sb.search(query, providers=provider_list, use_cache=not no_cache)
+        results = sb.search(
+            query,
+            providers=provider_list,
+            use_cache=not no_cache,
+            validate_optical=validate_optical,
+        )
 
     if not results:
         console.print("[yellow]No results found.[/]")

pygeofetch/core/authenticator.py

@@ -30,6 +30,8 @@ from pygeofetch.models.user_auth import AuthSession, AuthType, Credentials
 if TYPE_CHECKING:
     import builtins
 
+    from cryptography.fernet import Fernet
+
 logger = get_logger(__name__)
 
 
@@ -45,8 +47,12 @@ class CredentialStore:
     def __init__(self, storage_backend: str = "keyring") -> None:
         self.storage_backend = storage_backend
         self._config_dir = Path.home() / ".pygeofetch"
-        self._cred_file = self._config_dir / "credentials.json"
+        self._cred_file = self._config_dir / "credentials.enc"
+        self._legacy_cred_file = self._config_dir / "credentials.json"
+        self._key_file = self._config_dir / "credentials.key"
         self._in_memory: dict[str, dict[str, Any]] = {}
+        self._fernet: Fernet | None = None  # lazily initialized — see _get_fernet()
+        self._migrating = False  # re-entrancy guard for _migrate_legacy_file_if_needed
 
     def save(self, provider: str, credentials: dict[str, Any]) -> None:
         """Persist credentials for a provider."""
@@ -126,7 +132,88 @@ class CredentialStore:
         except Exception:
             return self._delete_file(provider)
 
+    _SENSITIVE_FIELDS = ("password", "api_key", "token", "secret_key", "client_secret")
+
+    def _get_fernet(self) -> Fernet:
+        """
+        Return a cached Fernet instance, generating and persisting a new
+        local encryption key on first use.
+
+        REAL BUG FIXED: this file backend previously used
+        ``base64.b64encode`` on sensitive fields with a comment stating
+        outright "Basic obfuscation (not encryption)" -- base64 is
+        trivially reversible by anyone who can read the file, with no
+        key required, and the docs previously (and inaccurately) claimed
+        this path used Fernet AES-128-CBC. It now genuinely does.
+        """
+        if self._fernet is not None:
+            return self._fernet
+        from cryptography.fernet import Fernet
+
+        self._config_dir.mkdir(parents=True, exist_ok=True)
+        if self._key_file.exists():
+            key = self._key_file.read_bytes()
+        else:
+            key = Fernet.generate_key()
+            self._key_file.write_bytes(key)
+            self._key_file.chmod(0o600)
+        self._fernet = Fernet(key)
+        return self._fernet
+
+    def _migrate_legacy_file_if_needed(self) -> None:
+        """
+        One-time transparent migration from the old base64-"obfuscated"
+        ``credentials.json`` to the new Fernet-encrypted
+        ``credentials.enc``, so existing users don't lose stored
+        credentials when upgrading. Runs at most once: after migration,
+        the legacy file is left in place but unused (never read again
+        once ``credentials.enc`` exists) rather than deleted, in case a
+        user needs to roll back.
+        """
+        if (
+            self._cred_file.exists()
+            or not self._legacy_cred_file.exists()
+            or self._migrating
+        ):
+            return
+        self._migrating = True
+        try:
+            try:
+                legacy_data = json.loads(self._legacy_cred_file.read_text())
+            except Exception as exc:
+                logger.warning(
+                    f"Could not read legacy credentials file for migration: {exc}"
+                )
+                return
+
+            migrated = 0
+            for provider, creds in legacy_data.items():
+                if not isinstance(creds, dict):
+                    continue
+                plain = dict(creds)
+                if plain.pop("__obfuscated", False):
+                    for k in self._SENSITIVE_FIELDS:
+                        if k in plain:
+                            try:
+                                plain[k] = base64.b64decode(
+                                    str(plain[k]).encode()
+                                ).decode()
+                            except Exception:
+                                pass
+                self._save_file(provider, plain)
+                migrated += 1
+            if migrated:
+                logger.info(
+                    f"Migrated {migrated} provider credential(s) from the old "
+                    f"{self._legacy_cred_file.name} (base64) to the new "
+                    f"{self._cred_file.name} (Fernet-encrypted). The old file "
+                    "was left in place, unused, and can be deleted manually."
+                )
+        finally:
+            self._migrating = False
+
     def _save_file(self, provider: str, credentials: dict[str, Any]) -> None:
+        self._migrate_legacy_file_if_needed()
         self._config_dir.mkdir(parents=True, exist_ok=True)
         existing: dict[str, Any] = {}
         if self._cred_file.exists():
@@ -134,19 +221,23 @@ class CredentialStore:
                 existing = json.loads(self._cred_file.read_text())
             except Exception:
                 pass
-        # Basic obfuscation (not encryption) - passwords stored as b64
-        obfuscated = {}
+
+        fernet = self._get_fernet()
+        encrypted = {}
         for k, v in credentials.items():
-            if k in ("password", "api_key", "token", "secret_key", "client_secret"):
-                obfuscated[k] = base64.b64encode(str(v).encode()).decode()
+            if k in self._SENSITIVE_FIELDS:
+                encrypted[k] = fernet.encrypt(str(v).encode()).decode()
             else:
-                obfuscated[k] = v
-        existing[provider] = {"__obfuscated": True, **obfuscated}
+                encrypted[k] = v
+        existing[provider] = {"__encrypted": True, **encrypted}
         self._cred_file.write_text(json.dumps(existing, indent=2))
         self._cred_file.chmod(0o600)
-        logger.debug(f"Credentials for {provider!r} saved to {self._cred_file}")
+        logger.debug(
+            f"Credentials for {provider!r} saved to {self._cred_file} (encrypted)"
+        )
 
     def _load_file(self, provider: str) -> dict[str, Any] | None:
+        self._migrate_legacy_file_if_needed()
         if not self._cred_file.exists():
             return None
         try:
@@ -154,19 +245,29 @@ class CredentialStore:
             creds = data.get(provider)
             if not creds:
                 return None
+            if creds.get("__encrypted"):
+                creds = {k: v for k, v in creds.items() if k != "__encrypted"}
+                fernet = self._get_fernet()
+                decoded = {}
+                for k, v in creds.items():
+                    if k in self._SENSITIVE_FIELDS:
+                        try:
+                            decoded[k] = fernet.decrypt(str(v).encode()).decode()
+                        except Exception:
+                            decoded[k] = v
+                    else:
+                        decoded[k] = v
+                return decoded
+            # Legacy plain/base64 entries encountered directly in
+            # credentials.enc (shouldn't normally happen, but handled
+            # rather than silently failing).
             if creds.get("__obfuscated"):
                 creds = {k: v for k, v in creds.items() if k != "__obfuscated"}
                 decoded = {}
                 for k, v in creds.items():
-                    if k in (
-                        "password",
-                        "api_key",
-                        "token",
-                        "secret_key",
-                        "client_secret",
-                    ):
+                    if k in self._SENSITIVE_FIELDS:
                         try:
-                            decoded[k] = base64.b64decode(v.encode()).decode()
+                            decoded[k] = base64.b64decode(str(v).encode()).decode()
                         except Exception:
                             decoded[k] = v
                     else: