homecloud-sdk 0.3.2__py3-none-any.whl

homecloud_core/mfa.py

@@ -0,0 +1,120 @@
+"""Central MFA challenge handling for console API calls."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from homecloud_core.errors import HomeCloudError
+
+PromptFn = Callable[[str], str]
+MfaMethodChooser = Callable[[list[str], list[dict] | None], str]
+
+
+class PreferBrowserLogin(Exception):
+    """User chose passkey/browser to finish authentication."""
+
+
+def is_mfa_required(exc: HomeCloudError) -> bool:
+    return exc.status_code == 403 and exc.error_code == "MFA_REQUIRED"
+
+
+def prompt_verification_code(prompt: PromptFn | None = None) -> str:
+    """Prompt for TOTP or backup code. Never cache the result."""
+    ask = prompt or (lambda msg: input(f"{msg}: ").strip())
+    code = ask("Verification code")
+    if not code:
+        raise HomeCloudError("Verification code is required")
+    return code.strip()
+
+
+class MfaResolver:
+    """
+    Completes MFA_REQUIRED challenges for console requests.
+
+    - Login challenge (``mfa_token`` in details): POST auth/login with mfa_token + mfa_code
+    - Step-up (no mfa_token): retry original JSON body with mfa_code injected
+
+    Passkeys raise PreferBrowserLogin so the CLI can open browser login.
+    """
+
+    def __init__(
+        self,
+        *,
+        mfa_code: str | None = None,
+        prompt: PromptFn | None = None,
+        interactive: bool = True,
+        choose_method: MfaMethodChooser | None = None,
+    ) -> None:
+        self._mfa_code = mfa_code
+        self._prompt = prompt
+        self._interactive = interactive
+        self._choose_method = choose_method
+
+    def obtain_code(
+        self,
+        *,
+        methods: list[str] | None = None,
+        passkeys: list[dict] | None = None,
+        allow_browser_switch: bool = True,
+    ) -> str:
+        if self._mfa_code:
+            code = self._mfa_code
+            self._mfa_code = None  # one-shot — never reuse across challenges
+            return code
+        if not self._interactive:
+            raise HomeCloudError(
+                "MFA required. Re-run with --mfa-code, or use: homecloud login --browser"
+            )
+
+        methods = methods or []
+        choice = "totp"
+        if self._choose_method and methods:
+            choice = self._choose_method(methods, passkeys)
+        elif methods and "totp" not in methods and "passkey" in methods:
+            choice = "browser"
+
+        if choice == "browser":
+            if not allow_browser_switch:
+                raise HomeCloudError(
+                    "Passkey confirmation is only available in the Console UI for this action."
+                )
+            raise PreferBrowserLogin()
+
+        return prompt_verification_code(self._prompt)
+
+    def resolve(
+        self,
+        exc: HomeCloudError,
+        *,
+        method: str,
+        path: str,
+        json_body: Any | None,
+        retry: Callable[..., Any],
+    ) -> Any:
+        details = exc.error_details
+        mfa_token = details.get("mfa_token")
+        methods_raw = details.get("methods") if isinstance(details.get("methods"), list) else None
+        methods = [str(m) for m in methods_raw] if methods_raw else None
+        passkeys_raw = details.get("passkeys")
+        passkeys = passkeys_raw if isinstance(passkeys_raw, list) else None
+        # Login challenge can switch to browser; step-up cannot.
+        allow_browser = bool(mfa_token) or path.rstrip("/").endswith("auth/login")
+        code = self.obtain_code(
+            methods=methods,
+            passkeys=[p for p in passkeys if isinstance(p, dict)] if passkeys else None,
+            allow_browser_switch=allow_browser,
+        )
+
+        if mfa_token:
+            return retry(
+                "POST",
+                "auth/login",
+                json={"mfa_token": mfa_token, "mfa_code": code},
+                require_auth=False,
+                _skip_mfa=True,
+            )
+
+        body = dict(json_body) if isinstance(json_body, dict) else {}
+        body["mfa_code"] = code
+        return retry(method, path, json=body, _skip_mfa=True)

homecloud_core/progress_reader.py

@@ -0,0 +1,27 @@
+"""File-like wrapper that reports bytes read for upload progress."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class ProgressReader:
+    """Wrap a binary file handle; call on_bytes with each read() length."""
+
+    def __init__(
+        self,
+        wrapped: Any,
+        on_bytes: Callable[[int], None] | None,
+    ) -> None:
+        self._wrapped = wrapped
+        self._on_bytes = on_bytes
+
+    def read(self, size: int = -1) -> bytes:
+        data = self._wrapped.read(size)
+        if data and self._on_bytes is not None:
+            self._on_bytes(len(data))
+        return data
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._wrapped, name)

homecloud_core/session.py

@@ -0,0 +1,115 @@
+"""Temporary session state — JWT and active account selection."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from homecloud_core.config import homecloud_dir
+from homecloud_core.env import env_session_file
+
+
+def session_path() -> Path:
+    override = env_session_file()
+    if override:
+        return Path(override).expanduser()
+    return homecloud_dir() / "session"
+
+
+@dataclass
+class ProfileSession:
+    access_token: str | None = None
+    active_account_id: str | None = None
+    last_used_account_id: str | None = None
+
+
+@dataclass
+class SessionFile:
+    version: int
+    profiles: dict[str, ProfileSession]
+
+    def get(self, profile_name: str) -> ProfileSession:
+        return self.profiles.setdefault(profile_name, ProfileSession())
+
+
+def load_session(path: Path | None = None) -> SessionFile:
+    session_file = path or session_path()
+    if not session_file.exists():
+        return SessionFile(version=1, profiles={})
+
+    raw = json.loads(session_file.read_text(encoding="utf-8"))
+    profiles = {
+        name: ProfileSession(
+            access_token=data.get("access_token"),
+            active_account_id=data.get("active_account_id"),
+            last_used_account_id=data.get("last_used_account_id"),
+        )
+        for name, data in raw.get("profiles", {}).items()
+    }
+    return SessionFile(version=int(raw.get("version", 1)), profiles=profiles)
+
+
+def save_session(session: SessionFile, path: Path | None = None) -> Path:
+    session_file = path or session_path()
+    session_file.parent.mkdir(parents=True, exist_ok=True)
+
+    payload: dict[str, Any] = {
+        "version": session.version,
+        "profiles": {
+            name: {
+                **({"access_token": profile.access_token} if profile.access_token else {}),
+                **({"active_account_id": profile.active_account_id} if profile.active_account_id else {}),
+                **(
+                    {"last_used_account_id": profile.last_used_account_id}
+                    if profile.last_used_account_id
+                    else {}
+                ),
+            }
+            for name, profile in session.profiles.items()
+            if profile.access_token or profile.active_account_id or profile.last_used_account_id
+        },
+    }
+
+    session_file.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    try:
+        session_file.chmod(0o600)
+    except OSError:
+        pass
+    return session_file
+
+
+def set_access_token(profile_name: str, token: str) -> Path:
+    session = load_session()
+    profile_session = session.get(profile_name)
+    profile_session.access_token = token
+    session.profiles[profile_name] = profile_session
+    return save_session(session)
+
+
+def set_active_account(profile_name: str, account_id: str) -> Path:
+    session = load_session()
+    profile_session = session.get(profile_name)
+    profile_session.active_account_id = account_id
+    profile_session.last_used_account_id = account_id
+    session.profiles[profile_name] = profile_session
+    return save_session(session)
+
+
+def get_access_token(profile_name: str) -> str | None:
+    return load_session().get(profile_name).access_token
+
+
+def migrate_legacy_token_from_credentials(
+    profile_name: str,
+    access_token: str | None,
+) -> None:
+    if not access_token:
+        return
+    session = load_session()
+    profile_session = session.get(profile_name)
+    if not profile_session.access_token:
+        profile_session.access_token = access_token
+        session.profiles[profile_name] = profile_session
+        save_session(session)

homecloud_core/signing.py

@@ -0,0 +1,50 @@
+"""HomeCloud request signing (SigV1) — internal only."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from datetime import datetime, timezone
+
+
+def build_string_to_sign(
+    *,
+    method: str,
+    path: str,
+    timestamp: str,
+    account_id: str,
+) -> str:
+    return f"{method.upper()}\n{path}\n{timestamp}\n{account_id}"
+
+
+def compute_signature(*, secret: str, string_to_sign: str) -> str:
+    return hmac.new(
+        secret.encode("utf-8"),
+        string_to_sign.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def sign_request_headers(
+    *,
+    access_key_id: str,
+    secret: str,
+    method: str,
+    path: str,
+    account_id: str,
+    timestamp: datetime | None = None,
+) -> dict[str, str]:
+    ts = (timestamp or datetime.now(timezone.utc)).replace(microsecond=0)
+    ts_str = ts.isoformat().replace("+00:00", "Z")
+    string_to_sign = build_string_to_sign(
+        method=method,
+        path=path,
+        timestamp=ts_str,
+        account_id=account_id,
+    )
+    signature = compute_signature(secret=secret, string_to_sign=string_to_sign)
+    return {
+        "X-Homecloud-Access-Key-Id": access_key_id,
+        "X-Homecloud-Date": ts_str,
+        "X-Homecloud-Signature": signature,
+    }

homecloud_core/so_paths.py

@@ -0,0 +1,29 @@
+"""SO object path helpers — canonical sign path vs URL-encoded request path."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+
+def encode_object_key_path(key: str) -> str:
+    """Encode each object key segment for the HTTP path (spaces → %20, etc.)."""
+    return "/".join(quote(part, safe="") for part in key.lstrip("/").split("/"))
+
+
+def so_object_paths(account_id: str, bucket_name: str, object_key: str) -> tuple[str, str]:
+    """Return (sign_path, url_path) for object GET/DELETE."""
+    key = object_key.lstrip("/")
+    sign_path = f"/{account_id}/{bucket_name}/objects/{key}"
+    url_path = f"/{account_id}/{bucket_name}/objects/{encode_object_key_path(key)}"
+    return sign_path, url_path
+
+
+def sync_relative_local_path(key: str, prefix_clean: str) -> str:
+    """Map remote object key to a relative path under the sync destination directory."""
+    if not prefix_clean:
+        return key
+    if key == prefix_clean:
+        return key.rsplit("/", 1)[-1]
+    if key.startswith(f"{prefix_clean}/"):
+        return key[len(prefix_clean) + 1 :]
+    return key

homecloud_core/transfer_state.py

@@ -0,0 +1,65 @@
+"""Thread-safe transfer metrics for upload/download progress."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TransferSnapshot:
+    total_bytes: int
+    completed_bytes: int
+    files_total: int
+    files_completed: int
+    active_files: tuple[str, ...]
+    bytes_per_second: float
+    eta_seconds: float | None
+
+
+class TransferState:
+    """Mutable transfer counters — workers update via add_bytes / file_* only."""
+
+    def __init__(self, *, total_bytes: int, files_total: int) -> None:
+        self.total_bytes = max(total_bytes, 0)
+        self.files_total = max(files_total, 0)
+        self._completed_bytes = 0
+        self._files_completed = 0
+        self._active_files: list[str] = []
+        self._lock = threading.Lock()
+        self._started_at = time.monotonic()
+
+    def add_bytes(self, nbytes: int) -> None:
+        if nbytes <= 0:
+            return
+        with self._lock:
+            self._completed_bytes += nbytes
+
+    def file_begin(self, key: str) -> None:
+        with self._lock:
+            if key not in self._active_files:
+                self._active_files.append(key)
+
+    def file_complete(self, key: str) -> None:
+        with self._lock:
+            if key in self._active_files:
+                self._active_files.remove(key)
+            self._files_completed += 1
+
+    def snapshot(self) -> TransferSnapshot:
+        with self._lock:
+            elapsed = max(time.monotonic() - self._started_at, 0.001)
+            completed = self._completed_bytes
+            speed = completed / elapsed
+            remaining = max(self.total_bytes - completed, 0)
+            eta = remaining / speed if speed > 0 and remaining > 0 else None
+            return TransferSnapshot(
+                total_bytes=self.total_bytes,
+                completed_bytes=completed,
+                files_total=self.files_total,
+                files_completed=self._files_completed,
+                active_files=tuple(self._active_files),
+                bytes_per_second=speed,
+                eta_seconds=eta,
+            )