hippius 0.2.18__py3-none-any.whl → 0.2.20__py3-none-any.whl

{hippius-0.2.18.dist-info → hippius-0.2.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hippius
-Version: 0.2.18
+Version: 0.2.20
 Summary: Python SDK and CLI for Hippius blockchain storage
 Home-page: https://github.com/thenervelab/hippius-sdk
 Author: Dubs

{hippius-0.2.18.dist-info → hippius-0.2.20.dist-info}/RECORD

@@ -1,10 +1,10 @@
-hippius_sdk/__init__.py,sha256=y1hFaAKG77GAKjps2c3Og69ZCn1anXFIa65PlYYj9Lg,1392
+hippius_sdk/__init__.py,sha256=9rPlh9Ob5xHhR9owW4IxihHaanA0vxuMrDidpW5l0Fw,1474
 hippius_sdk/cli.py,sha256=aqKOYSBSWt7UhcpFt7wf9yIPJ3bznpsJ6ehOnuZ4usI,18235
 hippius_sdk/cli_assets.py,sha256=V3MX63QTiex6mCp0VDXQJ7cagm5v1s4xtsu8c1O4G_k,371
 hippius_sdk/cli_handlers.py,sha256=TQNE9os87gRzRKLEO-SIwhFnBtEFMiaSESv-Bu7omfo,128909
 hippius_sdk/cli_parser.py,sha256=z7UvgWvvy04ey-R56qZiCqYc_9RaNq1rVDkQyXoK3JU,21100
 hippius_sdk/cli_rich.py,sha256=_jTBYMdHi2--fIVwoeNi-EtkdOb6Zy_O2TUiGvU3O7s,7324
-hippius_sdk/client.py,sha256=W1aVyvgMXRXVqjwSmRl03kZKB96PHMPcpq3cj1equ-8,20179
+hippius_sdk/client.py,sha256=k8K3__zDtWJhCbHPAPYu9FopSNXsrw1HpVAX6fV7pnI,21462
 hippius_sdk/config.py,sha256=Hf_aUYzG9ylzqauA_ABUSSB5mBTYbp-VtB36VQt2XDw,21981
 hippius_sdk/db/README.md,sha256=okDeI1qgkaZqXSlJ8L0xIE4UpuxO-qEGPIbXUvSHQjU,2030
 hippius_sdk/db/env.db.template,sha256=_6hEC3IvkzCDOAzG1_yJUKRUfCTMciNaJUicZpMCat4,217
@@ -12,12 +12,12 @@ hippius_sdk/db/migrations/20241201000001_create_key_storage_tables.sql,sha256=mi
 hippius_sdk/db/setup_database.sh,sha256=bDeIiTnMuX0AYCdefAfEI1CyXho6A6kLzufsDZFSXpE,3118
 hippius_sdk/db_utils.py,sha256=-x0rbN0as7Tn3PJPZBYCgreZe52FLH40ppA1TLxsg90,1851
 hippius_sdk/errors.py,sha256=LScJJmawVAx7aRzqqQguYSkf9iazSjEQEBNlD_GXZ6Y,1589
-hippius_sdk/ipfs.py,sha256=by45dH1c2IxzkfU7B9-ZRkI5gwEAxE0bUB9KUhszlL8,84460
+hippius_sdk/ipfs.py,sha256=Bp-f4QjrPeLKy61SxNsmB_YWvVjcYVBJlTt4NN6mGWo,90907
 hippius_sdk/ipfs_core.py,sha256=eOOgLoyP9mvwndnCjldnTc7z94ImYCXY3nm7JU3e_Mo,12676
-hippius_sdk/key_storage.py,sha256=7q5SL3Ls6Ho0xEwYSBpdci7e-bBMJnUMz2j7ROEBSVc,8947
+hippius_sdk/key_storage.py,sha256=-f4pEUvkczY_yw3lYJ_kM2iDDOAtKOgrexWxVgIo78w,9486
 hippius_sdk/substrate.py,sha256=AqfQNl5Qv_s6roOESSdwleX0-VGyu5sh3m5-dYZp5ek,49079
 hippius_sdk/utils.py,sha256=rJ611yvwKSyiBpYU3w-SuyQxoghMGU-ePuslrPv5H5g,7388
-hippius-0.2.18.dist-info/METADATA,sha256=bR-7aqi5G5o34ajG969VMj_VL-vWPYQIznyrBEfKcBM,30088
-hippius-0.2.18.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-hippius-0.2.18.dist-info/entry_points.txt,sha256=bFAZjW3vndretf9-8s587jA2ebMVI7puhn_lVs8jPc8,149
-hippius-0.2.18.dist-info/RECORD,,
+hippius-0.2.20.dist-info/METADATA,sha256=-mfl3cVtxZhaYbQvq-yt2aR96T1szZxnCb_R3Xbhx5I,30088
+hippius-0.2.20.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+hippius-0.2.20.dist-info/entry_points.txt,sha256=bFAZjW3vndretf9-8s587jA2ebMVI7puhn_lVs8jPc8,149
+hippius-0.2.20.dist-info/RECORD,,

hippius_sdk/__init__.py

@@ -23,13 +23,15 @@ from hippius_sdk.config import (
     set_encryption_key,
     set_seed_phrase,
 )
-from hippius_sdk.ipfs import IPFSClient
+from hippius_sdk.ipfs import IPFSClient, S3PublishResult, S3DownloadResult
 from hippius_sdk.utils import format_cid, format_size, hex_to_ipfs_cid
 
-__version__ = "0.2.18"
+__version__ = "0.2.20"
 __all__ = [
     "HippiusClient",
     "IPFSClient",
+    "S3PublishResult",
+    "S3DownloadResult",
     "get_config_value",
     "set_config_value",
     "get_encryption_key",

hippius_sdk/client.py

@@ -9,7 +9,7 @@ import nacl.secret
 import nacl.utils
 
 from hippius_sdk.config import get_config_value, get_encryption_key
-from hippius_sdk.ipfs import IPFSClient, S3PublishResult
+from hippius_sdk.ipfs import IPFSClient, S3PublishResult, S3DownloadResult
 from hippius_sdk.substrate import SubstrateClient
 
 
@@ -532,3 +532,31 @@ class HippiusClient:
             ValueError: If encryption is requested but not available
         """
         return await self.ipfs_client.s3_publish(file_path, encrypt, seed_phrase)
+
+    async def s3_download(
+        self, cid: str, output_path: str, seed_phrase: str, auto_decrypt: bool = True
+    ) -> S3DownloadResult:
+        """
+        Download a file from IPFS with automatic decryption.
+
+        This method automatically manages decryption keys per seed phrase:
+        - Downloads the file from IPFS
+        - If auto_decrypt=True, attempts to decrypt using stored keys for the seed phrase
+        - Falls back to client encryption key if key storage is not available
+        - Returns the file in decrypted form if decryption succeeds
+
+        Args:
+            cid: Content Identifier (CID) of the file to download
+            output_path: Path where the downloaded file will be saved
+            seed_phrase: Seed phrase to use for retrieving decryption keys
+            auto_decrypt: Whether to attempt automatic decryption (default: True)
+
+        Returns:
+            S3DownloadResult: Object containing download info and decryption status
+
+        Raises:
+            HippiusIPFSError: If IPFS download fails
+            FileNotFoundError: If the output directory doesn't exist
+            ValueError: If decryption fails
+        """
+        return await self.ipfs_client.s3_download(cid, output_path, seed_phrase, auto_decrypt)

hippius_sdk/ipfs.py

@@ -13,7 +13,11 @@ import tempfile
 import time
 import uuid
 from typing import Any, Callable, Dict, List, Optional
-
+from hippius_sdk.key_storage import (
+    generate_and_store_key_for_seed,
+    get_key_for_seed,
+    is_key_storage_enabled,
+)
 import httpx
 from pydantic import BaseModel
 
@@ -57,6 +61,18 @@ class S3PublishResult(BaseModel):
     tx_hash: str
 
 
+class S3DownloadResult(BaseModel):
+    """Result model for s3_download method."""
+
+    cid: str
+    output_path: str
+    size_bytes: int
+    size_formatted: str
+    elapsed_seconds: float
+    decrypted: bool
+    encryption_key: Optional[str]
+
+
 # Set up logger for this module
 logger = logging.getLogger(__name__)
 
@@ -1949,14 +1965,7 @@ class IPFSClient:
         encryption_key_used = None
         if encrypt:
             # Check if key storage is enabled and available
-            key_storage_available = False
             try:
-                from hippius_sdk.key_storage import (
-                    generate_and_store_key_for_seed,
-                    get_key_for_seed,
-                    is_key_storage_enabled,
-                )
-
                 key_storage_available = is_key_storage_enabled()
                 logger.debug(f"Key storage enabled: {key_storage_available}")
             except ImportError:
@@ -1964,9 +1973,6 @@ class IPFSClient:
                 key_storage_available = False
 
             if key_storage_available:
-                # Use PostgreSQL-backed key storage
-                logger.info(f"Using PostgreSQL key storage for seed phrase")
-
                 # Try to get existing key for this seed phrase
                 existing_key_b64 = await get_key_for_seed(seed_phrase)
 
@@ -2079,3 +2085,153 @@ class IPFSClient:
             encryption_key=encryption_key_used,
             tx_hash=tx_hash,
         )
+
+    async def s3_download(
+        self, cid: str, output_path: str, seed_phrase: str, auto_decrypt: bool = True
+    ) -> S3DownloadResult:
+        """
+        Download a file from IPFS with automatic decryption.
+
+        This method automatically manages decryption keys per seed phrase:
+        - Downloads the file from IPFS
+        - If auto_decrypt=True, attempts to decrypt using stored keys for the seed phrase
+        - Falls back to client encryption key if key storage is not available
+        - Returns the file in decrypted form if decryption succeeds
+
+        Args:
+            cid: Content Identifier (CID) of the file to download
+            output_path: Path where the downloaded file will be saved
+            seed_phrase: Seed phrase to use for retrieving decryption keys
+            auto_decrypt: Whether to attempt automatic decryption (default: True)
+
+        Returns:
+            S3DownloadResult: Object containing download info and decryption status
+
+        Raises:
+            HippiusIPFSError: If IPFS download fails
+            FileNotFoundError: If the output directory doesn't exist
+            ValueError: If decryption fails
+        """
+        start_time = time.time()
+
+        # Download the file first using the existing download_file method
+        try:
+            # Create parent directories if they don't exist
+            os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+
+            # Download without decryption first
+            download_result = await self.download_file(
+                cid=cid,
+                output_path=output_path,
+                skip_directory_check=False,
+                seed_phrase=seed_phrase,
+            )
+
+            if not download_result.get("success", False):
+                raise HippiusIPFSError("Download failed")
+
+        except Exception as e:
+            raise HippiusIPFSError(f"Failed to download file from IPFS: {str(e)}")
+
+        # Get file info after download
+        size_bytes = os.path.getsize(output_path)
+        elapsed_time = time.time() - start_time
+
+        # Attempt automatic decryption if requested
+        decrypted = False
+        encryption_key_used = None
+
+        if auto_decrypt:
+            # Check if key storage is enabled and available
+            try:
+                key_storage_available = is_key_storage_enabled()
+                logger.debug(f"Key storage enabled: {key_storage_available}")
+            except ImportError:
+                logger.debug("Key storage module not available")
+                key_storage_available = False
+
+            # Read the downloaded file content
+            with open(output_path, "rb") as f:
+                file_data = f.read()
+
+            decryption_attempted = False
+            decryption_successful = False
+
+            if key_storage_available:
+                # Try to get the encryption key for this seed phrase
+                try:
+                    existing_key_b64 = await get_key_for_seed(seed_phrase)
+
+                    if existing_key_b64:
+                        logger.debug("Found encryption key for seed phrase, attempting decryption")
+                        decryption_attempted = True
+                        encryption_key_used = existing_key_b64
+
+                        # Attempt decryption with the stored key
+                        try:
+                            import nacl.secret
+
+                            encryption_key_bytes = base64.b64decode(existing_key_b64)
+                            box = nacl.secret.SecretBox(encryption_key_bytes)
+                            decrypted_data = box.decrypt(file_data)
+
+                            # Write the decrypted data back to the file
+                            with open(output_path, "wb") as f:
+                                f.write(decrypted_data)
+
+                            decryption_successful = True
+                            decrypted = True
+                            size_bytes = len(decrypted_data)  # Update size to decrypted size
+                            logger.info("Successfully decrypted file using stored key")
+
+                        except Exception as decrypt_error:
+                            logger.debug(f"Decryption failed with stored key: {decrypt_error}")
+                            # Continue to try fallback decryption
+                    else:
+                        logger.debug("No encryption key found for seed phrase")
+
+                except Exception as e:
+                    logger.debug(f"Error retrieving key from storage: {e}")
+
+            # If key storage decryption failed or wasn't available, try client encryption key
+            if not decryption_successful and self.encryption_available:
+                logger.debug("Attempting decryption with client encryption key")
+                decryption_attempted = True
+
+                try:
+                    decrypted_data = self.decrypt_data(file_data)
+
+                    # Write the decrypted data back to the file
+                    with open(output_path, "wb") as f:
+                        f.write(decrypted_data)
+
+                    decryption_successful = True
+                    decrypted = True
+                    size_bytes = len(decrypted_data)  # Update size to decrypted size
+                    
+                    # Store the encryption key for the result
+                    encryption_key_used = (
+                        base64.b64encode(self.encryption_key).decode("utf-8")
+                        if self.encryption_key
+                        else None
+                    )
+                    logger.info("Successfully decrypted file using client encryption key")
+
+                except Exception as decrypt_error:
+                    logger.debug(f"Decryption failed with client key: {decrypt_error}")
+
+            # Log final decryption status
+            if decryption_attempted and not decryption_successful:
+                logger.info("File may not be encrypted or decryption keys don't match")
+            elif not decryption_attempted:
+                logger.debug("No decryption attempted - no keys available")
+
+        return S3DownloadResult(
+            cid=cid,
+            output_path=output_path,
+            size_bytes=size_bytes,
+            size_formatted=self.format_size(size_bytes),
+            elapsed_seconds=round(elapsed_time, 2),
+            decrypted=decrypted,
+            encryption_key=encryption_key_used,
+        )

hippius_sdk/key_storage.py

@@ -232,8 +232,25 @@ _default_storage = None
 
 
 def is_key_storage_enabled() -> bool:
-    """Check if key storage is enabled in configuration."""
-    return get_config_value("key_storage", "enabled", False)
+    """
+    Check if key storage is enabled and available.
+    
+    Returns True if:
+    1. Explicitly enabled in config, OR
+    2. asyncpg is available (key_storage extra installed) AND not explicitly disabled
+    """
+    # Check if explicitly disabled
+    config_value = get_config_value("key_storage", "enabled", None)
+    if config_value is False:
+        return False
+    
+    # If explicitly enabled, return True
+    if config_value is True:
+        return True
+    
+    # If not set in config, auto-detect based on asyncpg availability
+    # This allows users who install [key_storage] extra to use it without manual config
+    return ASYNCPG_AVAILABLE
 
 
 def get_default_storage() -> KeyStorage: