htcli 1.1.0__py3-none-any.whl

src/htcli/client/offchain/backup.py

@@ -0,0 +1,385 @@
+"""
+Off-chain backup management operations.
+Handles backup and restoration of wallets, configurations, and local state.
+"""
+
+import json
+import shutil
+import tarfile
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from ...utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class BackupManager:
+    """Manager for off-chain backup operations."""
+
+    def __init__(self, backup_dir: Optional[str] = None):
+        self.backup_dir = (
+            Path(backup_dir) if backup_dir else Path.home() / ".htcli" / "backups"
+        )
+        self.backup_dir.mkdir(parents=True, exist_ok=True)
+        self.htcli_dir = Path.home() / ".htcli"
+
+    def _validate_member_path(self, destination: Path, member_name: str) -> Path:
+        """Resolve a tar member path and ensure it stays under destination."""
+        target_path = (destination / member_name).resolve()
+        try:
+            target_path.relative_to(destination)
+        except ValueError as exc:
+            raise ValueError(f"Unsafe backup member path: {member_name}") from exc
+        return target_path
+
+    def _safe_extract_tar(self, tar: tarfile.TarFile, destination: Path) -> None:
+        """Extract regular files and directories without trusting archive paths."""
+        destination = destination.resolve()
+        destination.mkdir(parents=True, exist_ok=True)
+
+        for member in tar.getmembers():
+            target_path = self._validate_member_path(destination, member.name)
+
+            if member.isdir():
+                target_path.mkdir(parents=True, exist_ok=True)
+                continue
+
+            if not member.isfile():
+                raise ValueError(f"Unsupported backup member type: {member.name}")
+
+            source = tar.extractfile(member)
+            if source is None:
+                raise ValueError(f"Unable to read backup member: {member.name}")
+
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            with source, open(target_path, "wb") as target:
+                shutil.copyfileobj(source, target)
+
+    def create_full_backup(self, backup_name: Optional[str] = None) -> dict:
+        """Create a full backup of all HTCLI data."""
+        try:
+            if backup_name is None:
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                backup_name = f"htcli_backup_{timestamp}"
+
+            backup_file = self.backup_dir / f"{backup_name}.tar.gz"
+
+            # Create backup archive
+            with tarfile.open(backup_file, "w:gz") as tar:
+                if self.htcli_dir.exists():
+                    # Add all files except existing backups to avoid recursion
+                    for item in self.htcli_dir.iterdir():
+                        if item.name != "backups":
+                            tar.add(item, arcname=item.name)
+
+            # Create backup manifest
+            manifest = self._create_backup_manifest(backup_name)
+            manifest_file = self.backup_dir / f"{backup_name}_manifest.json"
+
+            with open(manifest_file, "w") as f:
+                json.dump(manifest, f, indent=2)
+
+            return {
+                "success": True,
+                "message": "Full backup created successfully",
+                "data": {
+                    "backup_name": backup_name,
+                    "backup_file": str(backup_file),
+                    "manifest_file": str(manifest_file),
+                    "size": backup_file.stat().st_size,
+                    "manifest": manifest,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to create full backup: {str(e)}")
+            raise
+
+    def restore_full_backup(self, backup_name: str, confirm: bool = False) -> dict:
+        """Restore a full backup (replaces current data)."""
+        try:
+            if not confirm:
+                raise ValueError("Full restore requires explicit confirmation")
+
+            backup_file = self.backup_dir / f"{backup_name}.tar.gz"
+            manifest_file = self.backup_dir / f"{backup_name}_manifest.json"
+
+            if not backup_file.exists():
+                raise ValueError(f"Backup file '{backup_name}.tar.gz' not found")
+
+            # Load manifest
+            manifest = {}
+            if manifest_file.exists():
+                with open(manifest_file) as f:
+                    manifest = json.load(f)
+
+            # Create backup of current state before restore
+            current_backup_result = self.create_full_backup(
+                f"pre_restore_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+            )
+
+            # Clear current HTCLI directory (except backups)
+            if self.htcli_dir.exists():
+                for item in self.htcli_dir.iterdir():
+                    if item.name != "backups":
+                        if item.is_dir():
+                            shutil.rmtree(item)
+                        else:
+                            item.unlink()
+
+            # Extract backup
+            with tarfile.open(backup_file, "r:gz") as tar:
+                self._safe_extract_tar(tar, self.htcli_dir)
+
+            return {
+                "success": True,
+                "message": f"Full backup '{backup_name}' restored successfully",
+                "data": {
+                    "backup_name": backup_name,
+                    "manifest": manifest,
+                    "pre_restore_backup": current_backup_result["data"]["backup_name"],
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to restore full backup: {str(e)}")
+            raise
+
+    def backup_wallets(self, backup_name: Optional[str] = None) -> dict:
+        """Create a backup of all wallets."""
+        try:
+            if backup_name is None:
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                backup_name = f"wallets_backup_{timestamp}"
+
+            wallets_dir = self.htcli_dir / "wallets"
+            backup_file = self.backup_dir / f"{backup_name}.tar.gz"
+
+            if not wallets_dir.exists():
+                return {
+                    "success": False,
+                    "message": "No wallets directory found",
+                    "data": None,
+                }
+
+            # Create wallets backup
+            with tarfile.open(backup_file, "w:gz") as tar:
+                tar.add(wallets_dir, arcname="wallets")
+
+            # Count wallet files
+            wallet_count = len(list(wallets_dir.glob("*.json")))
+
+            return {
+                "success": True,
+                "message": "Wallets backup created successfully",
+                "data": {
+                    "backup_name": backup_name,
+                    "backup_file": str(backup_file),
+                    "wallet_count": wallet_count,
+                    "size": backup_file.stat().st_size,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to backup wallets: {str(e)}")
+            raise
+
+    def restore_wallets(self, backup_name: str, confirm: bool = False) -> dict:
+        """Restore wallets from backup."""
+        try:
+            if not confirm:
+                raise ValueError("Wallet restore requires explicit confirmation")
+
+            backup_file = self.backup_dir / f"{backup_name}.tar.gz"
+
+            if not backup_file.exists():
+                raise ValueError(f"Backup file '{backup_name}.tar.gz' not found")
+
+            wallets_dir = self.htcli_dir / "wallets"
+
+            # Create backup of current wallets if they exist
+            current_backup = None
+            if wallets_dir.exists() and any(wallets_dir.glob("*.json")):
+                current_backup_result = self.backup_wallets(
+                    f"pre_restore_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+                )
+                current_backup = current_backup_result["data"]["backup_name"]
+
+            # Clear current wallets
+            if wallets_dir.exists():
+                shutil.rmtree(wallets_dir)
+
+            # Extract backup
+            with tarfile.open(backup_file, "r:gz") as tar:
+                self._safe_extract_tar(tar, self.htcli_dir)
+
+            # Count restored wallets
+            wallet_count = (
+                len(list(wallets_dir.glob("*.json"))) if wallets_dir.exists() else 0
+            )
+
+            return {
+                "success": True,
+                "message": f"Wallets restored from backup '{backup_name}' successfully",
+                "data": {
+                    "backup_name": backup_name,
+                    "wallet_count": wallet_count,
+                    "pre_restore_backup": current_backup,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to restore wallets: {str(e)}")
+            raise
+
+    def list_backups(self) -> dict:
+        """List all available backups."""
+        try:
+            backup_files = list(self.backup_dir.glob("*.tar.gz"))
+            backups = []
+
+            for backup_file in backup_files:
+                try:
+                    backup_name = backup_file.stem
+                    manifest_file = self.backup_dir / f"{backup_name}_manifest.json"
+
+                    backup_info = {
+                        "name": backup_name,
+                        "file": str(backup_file),
+                        "size": backup_file.stat().st_size,
+                        "created_at": datetime.fromtimestamp(
+                            backup_file.stat().st_ctime
+                        ).isoformat(),
+                        "manifest": None,
+                    }
+
+                    # Load manifest if exists
+                    if manifest_file.exists():
+                        with open(manifest_file) as f:
+                            backup_info["manifest"] = json.load(f)
+
+                    backups.append(backup_info)
+                except Exception as e:
+                    logger.warning(f"Failed to read backup info for {backup_file}: {e}")
+                    continue
+
+            # Sort by creation time (newest first)
+            backups.sort(key=lambda x: x["created_at"], reverse=True)
+
+            return {
+                "success": True,
+                "message": f"Found {len(backups)} backup(s)",
+                "data": backups,
+            }
+        except Exception as e:
+            logger.error(f"Failed to list backups: {str(e)}")
+            raise
+
+    def delete_backup(self, backup_name: str, confirm: bool = False) -> dict:
+        """Delete a backup."""
+        try:
+            if not confirm:
+                raise ValueError("Backup deletion requires explicit confirmation")
+
+            backup_file = self.backup_dir / f"{backup_name}.tar.gz"
+            manifest_file = self.backup_dir / f"{backup_name}_manifest.json"
+
+            if not backup_file.exists():
+                raise ValueError(f"Backup '{backup_name}' not found")
+
+            # Delete files
+            backup_file.unlink()
+            if manifest_file.exists():
+                manifest_file.unlink()
+
+            return {
+                "success": True,
+                "message": f"Backup '{backup_name}' deleted successfully",
+                "data": {"backup_name": backup_name},
+            }
+        except Exception as e:
+            logger.error(f"Failed to delete backup: {str(e)}")
+            raise
+
+    def cleanup_old_backups(self, keep_count: int = 10, confirm: bool = False) -> dict:
+        """Clean up old backups, keeping only the most recent ones."""
+        try:
+            if not confirm:
+                raise ValueError("Backup cleanup requires explicit confirmation")
+
+            backups_result = self.list_backups()
+            backups = backups_result["data"]
+
+            if len(backups) <= keep_count:
+                return {
+                    "success": True,
+                    "message": f"No cleanup needed. Current backup count: {len(backups)}",
+                    "data": {
+                        "deleted_count": 0,
+                        "remaining_count": len(backups),
+                    },
+                }
+
+            # Delete oldest backups
+            backups_to_delete = backups[keep_count:]
+            deleted_count = 0
+
+            for backup in backups_to_delete:
+                try:
+                    self.delete_backup(backup["name"], confirm=True)
+                    deleted_count += 1
+                except Exception as e:
+                    logger.warning(f"Failed to delete backup {backup['name']}: {e}")
+
+            return {
+                "success": True,
+                "message": f"Cleanup completed. Deleted {deleted_count} old backup(s)",
+                "data": {
+                    "deleted_count": deleted_count,
+                    "remaining_count": len(backups) - deleted_count,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to cleanup backups: {str(e)}")
+            raise
+
+    def _create_backup_manifest(self, backup_name: str) -> dict:
+        """Create a manifest describing the backup contents."""
+        try:
+            manifest = {
+                "backup_name": backup_name,
+                "created_at": datetime.now().isoformat(),
+                "version": "1.0",
+                "contents": {"wallets": [], "config": None, "other_files": []},
+            }
+
+            # List wallets
+            wallets_dir = self.htcli_dir / "wallets"
+            if wallets_dir.exists():
+                for wallet_file in wallets_dir.glob("*.json"):
+                    try:
+                        with open(wallet_file) as f:
+                            wallet_data = json.load(f)
+                        manifest["contents"]["wallets"].append(
+                            {
+                                "name": wallet_data.get("name", wallet_file.stem),
+                                "address": wallet_data.get("address"),
+                                "file": wallet_file.name,
+                            }
+                        )
+                    except Exception as e:
+                        logger.warning(f"Failed to read wallet {wallet_file}: {e}")
+
+            # Check config
+            config_file = self.htcli_dir / "config.yaml"
+            if config_file.exists():
+                manifest["contents"]["config"] = "config.yaml"
+
+            # List other files
+            if self.htcli_dir.exists():
+                for item in self.htcli_dir.iterdir():
+                    if item.name not in ["wallets", "config.yaml", "backups"]:
+                        manifest["contents"]["other_files"].append(item.name)
+
+            return manifest
+        except Exception as e:
+            logger.error(f"Failed to create backup manifest: {str(e)}")
+            return {"error": str(e)}