@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/backup.py

@@ -0,0 +1,345 @@
+"""Sovereign agent backup and restore.
+
+Creates a portable, encrypted archive of the full agent state:
+identity, memories, trust, config, agent card, and coordination.
+Restores to any machine with a single command.
+
+The backup is a gzip-compressed tar archive. When a PGP key is
+available, the archive content manifest is signed for integrity.
+
+Layout inside the tarball:
+    backup-<timestamp>/
+    ├── manifest.json          # backup metadata + file checksums
+    ├── config/                # agent configuration
+    ├── identity/              # CapAuth profile + keys
+    ├── memory/                # SKMemory data
+    ├── trust/                 # Cloud 9 FEB files + seeds
+    ├── coordination/          # board state
+    └── agent-card.json        # sovereign identity card
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import tarfile
+import tempfile
+from datetime import datetime, timezone
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from . import AGENT_HOME, __version__
+
+logger = logging.getLogger("skcapstone.backup")
+
+
+class BackupManifest(BaseModel):
+    """Metadata for a sovereign agent backup.
+
+    Attributes:
+        backup_id: Unique backup identifier (timestamp-based).
+        created_at: When the backup was created.
+        agent_name: Name of the backed-up agent.
+        version: SKCapstone version that created the backup.
+        home_path: Original agent home path.
+        files: Dict of relative path -> SHA-256 hash.
+        total_size: Total uncompressed size in bytes.
+    """
+
+    backup_id: str = ""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    agent_name: str = ""
+    version: str = __version__
+    home_path: str = ""
+    files: dict[str, str] = Field(default_factory=dict)
+    total_size: int = 0
+
+
+# Directories relative to agent home to include in backup.
+# Excludes ephemeral runtime dirs: sync/, heartbeats/, coordination/tasks/
+BACKUP_DIRS = [
+    "config",
+    "identity",
+    "memory",
+    "soul",
+    "conversations",
+    "trust",
+]
+
+# Individual files relative to agent home
+BACKUP_FILES = [
+    "manifest.json",
+    "agent-card.json",
+]
+
+# Patterns to exclude from backup (security-sensitive)
+EXCLUDE_PATTERNS = [
+    "*.pyc",
+    "__pycache__",
+    ".git",
+]
+
+
+def _sha256_file(filepath: Path) -> str:
+    """Compute SHA-256 of a file.
+
+    Args:
+        filepath: Path to the file.
+
+    Returns:
+        str: Hex digest.
+    """
+    h = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _should_exclude(name: str) -> bool:
+    """Check if a tar member should be excluded.
+
+    Args:
+        name: Filename or path component.
+
+    Returns:
+        bool: True if the file should be skipped.
+    """
+    base = os.path.basename(name)
+    for pattern in EXCLUDE_PATTERNS:
+        if pattern.startswith("*"):
+            if base.endswith(pattern[1:]):
+                return True
+        elif base == pattern:
+            return True
+    return False
+
+
+def create_backup(
+    home: Optional[Path] = None,
+    output_dir: Optional[Path] = None,
+    agent_name: str = "",
+) -> dict[str, Any]:
+    """Create a compressed backup of the full agent state.
+
+    Collects all agent data directories and files into a
+    gzip-compressed tar archive with a manifest for integrity.
+
+    Args:
+        home: Agent home directory. Defaults to ~/.skcapstone.
+        output_dir: Where to write the backup file. Defaults to ~/backups.
+        agent_name: Agent name for the manifest.
+
+    Returns:
+        dict: Result with 'filepath', 'size', 'file_count', 'manifest'.
+    """
+    home_path = (home or Path(AGENT_HOME)).expanduser()
+    if not home_path.exists():
+        raise FileNotFoundError(f"Agent home not found: {home_path}")
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+    backup_id = f"backup-{timestamp}"
+
+    out_dir = (output_dir or home_path / "backups").expanduser()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    archive_path = out_dir / f"{backup_id}.tar.gz"
+
+    manifest = BackupManifest(
+        backup_id=backup_id,
+        agent_name=agent_name or _read_agent_name(home_path),
+        home_path=str(home_path),
+    )
+
+    total_size = 0
+    file_count = 0
+
+    with tarfile.open(archive_path, "w:gz") as tar:
+        for dir_name in BACKUP_DIRS:
+            dir_path = home_path / dir_name
+            if not dir_path.exists():
+                continue
+
+            for filepath in sorted(dir_path.rglob("*")):
+                if not filepath.is_file():
+                    continue
+                if _should_exclude(str(filepath)):
+                    continue
+
+                rel = filepath.relative_to(home_path)
+                arcname = f"{backup_id}/{rel}"
+
+                tar.add(filepath, arcname=arcname)
+                manifest.files[str(rel)] = _sha256_file(filepath)
+                total_size += filepath.stat().st_size
+                file_count += 1
+
+        for filename in BACKUP_FILES:
+            filepath = home_path / filename
+            if filepath.exists():
+                arcname = f"{backup_id}/{filename}"
+                tar.add(filepath, arcname=arcname)
+                manifest.files[filename] = _sha256_file(filepath)
+                total_size += filepath.stat().st_size
+                file_count += 1
+
+        manifest.total_size = total_size
+
+        manifest_json = manifest.model_dump_json(indent=2).encode("utf-8")
+        info = tarfile.TarInfo(name=f"{backup_id}/_backup_manifest.json")
+        info.size = len(manifest_json)
+        tar.addfile(info, BytesIO(manifest_json))
+
+    archive_size = archive_path.stat().st_size
+
+    logger.info(
+        "Backup created: %s (%d files, %d bytes -> %d bytes compressed)",
+        archive_path, file_count, total_size, archive_size,
+    )
+
+    return {
+        "filepath": str(archive_path),
+        "backup_id": backup_id,
+        "file_count": file_count,
+        "total_size": total_size,
+        "archive_size": archive_size,
+        "manifest": manifest.model_dump(mode="json"),
+    }
+
+
+def restore_backup(
+    archive_path: str | Path,
+    target_home: Optional[Path] = None,
+    verify: bool = True,
+) -> dict[str, Any]:
+    """Restore an agent from a backup archive.
+
+    Extracts the archive to the target home directory and
+    verifies file integrity against the manifest checksums.
+
+    Args:
+        archive_path: Path to the .tar.gz backup file.
+        target_home: Where to restore. Defaults to ~/.skcapstone.
+        verify: Whether to verify checksums after extraction.
+
+    Returns:
+        dict: Result with 'restored', 'file_count', 'verified', 'errors'.
+    """
+    archive = Path(archive_path).expanduser()
+    if not archive.exists():
+        raise FileNotFoundError(f"Backup not found: {archive}")
+
+    target = (target_home or Path(AGENT_HOME)).expanduser()
+    target.mkdir(parents=True, exist_ok=True)
+
+    manifest: Optional[BackupManifest] = None
+    backup_prefix = ""
+
+    with tarfile.open(archive, "r:gz") as tar:
+        members = tar.getmembers()
+        if not members:
+            raise ValueError("Empty backup archive")
+
+        backup_prefix = members[0].name.split("/")[0]
+
+        manifest_member = f"{backup_prefix}/_backup_manifest.json"
+        try:
+            f = tar.extractfile(manifest_member)
+            if f:
+                manifest = BackupManifest.model_validate_json(f.read())
+        except (KeyError, Exception) as exc:
+            logger.warning("No manifest in backup: %s", exc)
+
+        file_count = 0
+        for member in tar.getmembers():
+            if member.name == manifest_member:
+                continue
+            if not member.isfile():
+                continue
+            if _should_exclude(member.name):
+                continue
+
+            rel_path = member.name[len(backup_prefix) + 1:]
+            member.name = rel_path
+            tar.extract(member, path=target, filter="data")
+            file_count += 1
+
+    errors: list[str] = []
+    if verify and manifest:
+        for rel_path, expected_hash in manifest.files.items():
+            restored_file = target / rel_path
+            if not restored_file.exists():
+                errors.append(f"Missing: {rel_path}")
+                continue
+            actual = _sha256_file(restored_file)
+            if actual != expected_hash:
+                errors.append(f"Checksum mismatch: {rel_path}")
+
+    logger.info(
+        "Restored %d files to %s (%d verification errors)",
+        file_count, target, len(errors),
+    )
+
+    return {
+        "restored": file_count,
+        "file_count": file_count,
+        "target": str(target),
+        "verified": len(errors) == 0,
+        "errors": errors,
+        "backup_id": manifest.backup_id if manifest else "unknown",
+        "agent_name": manifest.agent_name if manifest else "unknown",
+    }
+
+
+def list_backups(
+    backup_dir: Optional[Path] = None,
+) -> list[dict[str, Any]]:
+    """List available backup archives.
+
+    Args:
+        backup_dir: Directory to scan. Defaults to ~/.skcapstone/backups.
+
+    Returns:
+        list[dict]: Backup metadata sorted newest first.
+    """
+    search_dir = (backup_dir or Path(AGENT_HOME).expanduser() / "backups")
+    if not search_dir.exists():
+        return []
+
+    backups = []
+    for f in sorted(search_dir.glob("backup-*.tar.gz"), reverse=True):
+        stat = f.stat()
+        backups.append({
+            "filepath": str(f),
+            "filename": f.name,
+            "size": stat.st_size,
+            "created": datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat(),
+        })
+
+    return backups
+
+
+def _read_agent_name(home: Path) -> str:
+    """Read agent name from config or manifest.
+
+    Args:
+        home: Agent home directory.
+
+    Returns:
+        str: Agent name or 'unknown'.
+    """
+    for filename in ("manifest.json", "config/config.yaml"):
+        filepath = home / filename
+        if filepath.exists():
+            try:
+                data = json.loads(filepath.read_text(encoding="utf-8"))
+                name = data.get("name") or data.get("agent_name")
+                if name:
+                    return name
+            except Exception:
+                continue
+    return "unknown"

package/src/skcapstone/blueprint_registry.py

@@ -0,0 +1,357 @@
+"""
+Blueprint Registry Client — interact with the souls.skworld.io API.
+
+This is a client library for the remote soul blueprint registry hosted at
+souls.skworld.io. The actual server is a separate service; this module
+provides a typed Python interface for listing, searching, publishing,
+and downloading blueprints.
+
+Authentication uses DID-based bearer tokens: the agent's DID key is
+sent as ``Authorization: Bearer did:key:<fingerprint>`` so the registry
+can attribute published blueprints to a sovereign identity.
+
+No external dependencies — uses only ``urllib`` from the standard library.
+
+Usage::
+
+    from skcapstone.blueprint_registry import BlueprintRegistryClient
+
+    client = BlueprintRegistryClient()
+    blueprints = client.list_blueprints()
+    result = client.search_blueprints("comedy")
+    client.publish_blueprint(soul_data)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger("skcapstone.blueprint_registry")
+
+DEFAULT_BASE_URL = "https://souls.skworld.io/api"
+
+# Timeout for HTTP requests (seconds).
+_REQUEST_TIMEOUT = 30
+
+
+class BlueprintRegistryError(Exception):
+    """Raised when a registry API call fails."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class BlueprintRegistryClient:
+    """Client for the souls.skworld.io blueprint registry API.
+
+    Args:
+        base_url: API base URL (default: ``https://souls.skworld.io/api``).
+        did_key: DID key string for authentication (e.g. ``did:key:z6Mk...``).
+            If not provided, the client will attempt to load it from the
+            agent's identity on disk at ``~/.skcapstone/did/``.
+        timeout: HTTP request timeout in seconds (default: 30).
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        did_key: Optional[str] = None,
+        timeout: int = _REQUEST_TIMEOUT,
+    ) -> None:
+        # Strip trailing slash for consistent URL joining
+        self.base_url = base_url.rstrip("/")
+        self.did_key = did_key
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Auth helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_did_key(self) -> Optional[str]:
+        """Resolve the DID key from the instance or from disk.
+
+        Returns:
+            DID key string, or None if unavailable.
+        """
+        if self.did_key:
+            return self.did_key
+
+        # Attempt to load from the agent's DID directory
+        did_dir = Path.home() / ".skcapstone" / "did"
+        key_file = did_dir / "did_key.json"
+        if key_file.exists():
+            try:
+                data = json.loads(key_file.read_text(encoding="utf-8"))
+                resolved = data.get("did") or data.get("did_key") or data.get("id")
+                if resolved:
+                    logger.debug("Resolved DID key from %s", key_file)
+                    return resolved
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.debug("Could not load DID key from %s: %s", key_file, exc)
+
+        # Fallback: check identity.json
+        identity_file = did_dir / "identity.json"
+        if identity_file.exists():
+            try:
+                data = json.loads(identity_file.read_text(encoding="utf-8"))
+                resolved = data.get("did_key") or data.get("did") or data.get("id")
+                if resolved:
+                    return resolved
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        return None
+
+    def _build_headers(self, authenticated: bool = False) -> dict[str, str]:
+        """Build HTTP headers for a request.
+
+        Args:
+            authenticated: Whether to include the Authorization header.
+
+        Returns:
+            Header dict.
+        """
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "skcapstone-blueprint-registry/1.0",
+        }
+        if authenticated:
+            did = self._resolve_did_key()
+            if did:
+                headers["Authorization"] = f"Bearer {did}"
+            else:
+                logger.warning(
+                    "No DID key available for authenticated request. "
+                    "Set did_key on the client or ensure ~/.skcapstone/did/ "
+                    "contains a valid identity."
+                )
+        return headers
+
+    # ------------------------------------------------------------------
+    # HTTP transport
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        authenticated: bool = False,
+    ) -> dict[str, Any]:
+        """Execute an HTTP request against the registry API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: URL path relative to base_url (e.g. ``/blueprints``).
+            body: JSON body for POST/PUT requests.
+            authenticated: Whether to attach DID auth header.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            BlueprintRegistryError: On HTTP or connection errors.
+        """
+        url = f"{self.base_url}{path}"
+        headers = self._build_headers(authenticated=authenticated)
+
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+
+        req = urllib.request.Request(
+            url, data=data, headers=headers, method=method
+        )
+
+        logger.debug("%s %s", method, url)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                if not raw.strip():
+                    return {}
+                return json.loads(raw)
+        except urllib.error.HTTPError as exc:
+            error_body = ""
+            try:
+                error_body = exc.read().decode("utf-8", errors="replace")
+            except Exception:
+                pass
+            msg = f"Registry API error {exc.code} for {method} {path}"
+            if error_body:
+                msg += f": {error_body[:500]}"
+            raise BlueprintRegistryError(msg, status_code=exc.code) from exc
+        except urllib.error.URLError as exc:
+            raise BlueprintRegistryError(
+                f"Cannot reach registry at {url}: {exc.reason}"
+            ) from exc
+        except json.JSONDecodeError as exc:
+            raise BlueprintRegistryError(
+                f"Invalid JSON in response from {method} {path}: {exc}"
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # Public API methods
+    # ------------------------------------------------------------------
+
+    def list_blueprints(self) -> list[dict[str, Any]]:
+        """List all published blueprints in the registry.
+
+        Calls ``GET /blueprints``.
+
+        Returns:
+            List of blueprint summary dicts, each containing at minimum
+            ``name``, ``display_name``, ``category``, and ``soul_id``.
+
+        Raises:
+            BlueprintRegistryError: On API failure.
+        """
+        result = self._request("GET", "/blueprints")
+        # API may return {"blueprints": [...]} or a bare list
+        if isinstance(result, list):
+            return result
+        return result.get("blueprints", [])
+
+    def get_blueprint(self, soul_id: str) -> dict[str, Any]:
+        """Get a single blueprint by its soul ID.
+
+        Calls ``GET /blueprints/{soul_id}``.
+
+        Args:
+            soul_id: The unique identifier (slug) of the blueprint.
+
+        Returns:
+            Full blueprint dict with all fields.
+
+        Raises:
+            BlueprintRegistryError: On API failure or 404.
+        """
+        return self._request("GET", f"/blueprints/{soul_id}")
+
+    def publish_blueprint(self, soul_data: dict[str, Any]) -> dict[str, Any]:
+        """Publish a soul blueprint to the registry.
+
+        Calls ``POST /blueprints`` with DID-based authentication.
+
+        The ``soul_data`` should conform to the SoulBlueprint schema
+        (at minimum: ``name``, ``display_name``, ``category``).
+
+        Args:
+            soul_data: Blueprint data dict to publish.
+
+        Returns:
+            API response dict (typically includes ``soul_id`` and ``status``).
+
+        Raises:
+            BlueprintRegistryError: On API failure or auth error.
+        """
+        return self._request(
+            "POST", "/blueprints", body=soul_data, authenticated=True
+        )
+
+    def search_blueprints(self, query: str) -> list[dict[str, Any]]:
+        """Search for blueprints by a text query.
+
+        Calls ``GET /blueprints/search?q=<query>``.
+
+        Args:
+            query: Search string (matched against name, category, traits, etc.).
+
+        Returns:
+            List of matching blueprint dicts.
+
+        Raises:
+            BlueprintRegistryError: On API failure.
+        """
+        # URL-encode the query parameter
+        encoded_q = urllib.request.quote(query, safe="")
+        result = self._request("GET", f"/blueprints/search?q={encoded_q}")
+        if isinstance(result, list):
+            return result
+        return result.get("blueprints", result.get("results", []))
+
+    def download_blueprint(self, soul_id: str) -> dict[str, Any]:
+        """Download a full blueprint for local installation.
+
+        Calls ``GET /blueprints/{soul_id}/download``.
+
+        The returned dict can be written directly to a JSON file and
+        loaded by the local SoulManager.
+
+        Args:
+            soul_id: The unique identifier (slug) of the blueprint.
+
+        Returns:
+            Complete blueprint data suitable for local installation.
+
+        Raises:
+            BlueprintRegistryError: On API failure or 404.
+        """
+        return self._request("GET", f"/blueprints/{soul_id}/download")
+
+    # ------------------------------------------------------------------
+    # Convenience helpers
+    # ------------------------------------------------------------------
+
+    def download_and_install(self, soul_id: str, home: Optional[Path] = None) -> Path:
+        """Download a blueprint and install it locally.
+
+        Args:
+            soul_id: Registry soul ID to download.
+            home: Agent home directory (default: ``~/.skcapstone``).
+
+        Returns:
+            Path to the installed blueprint JSON file.
+
+        Raises:
+            BlueprintRegistryError: On download failure.
+        """
+        bp_data = self.download_blueprint(soul_id)
+        home = home or Path.home() / ".skcapstone"
+        installed_dir = home / "soul" / "installed"
+        installed_dir.mkdir(parents=True, exist_ok=True)
+
+        name = bp_data.get("name", soul_id)
+        dest = installed_dir / f"{name}.json"
+        dest.write_text(json.dumps(bp_data, indent=2), encoding="utf-8")
+        logger.info("Installed blueprint '%s' from registry to %s", soul_id, dest)
+        return dest
+
+    def publish_from_file(self, path: Path) -> dict[str, Any]:
+        """Load a local blueprint file and publish it to the registry.
+
+        Args:
+            path: Path to a local blueprint JSON file.
+
+        Returns:
+            API response from publish.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            BlueprintRegistryError: On publish failure.
+        """
+        if not path.exists():
+            raise FileNotFoundError(f"Blueprint file not found: {path}")
+
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return self.publish_blueprint(data)
+
+    def is_reachable(self) -> bool:
+        """Check if the registry API is reachable.
+
+        Returns:
+            True if a basic request succeeds, False otherwise.
+        """
+        try:
+            self._request("GET", "/blueprints")
+            return True
+        except BlueprintRegistryError:
+            return False