homecloud-sdk 0.3.2__py3-none-any.whl

homecloud_core/__init__.py

@@ -0,0 +1 @@
+"""Internal core — not part of the public SDK surface."""

homecloud_core/account.py

@@ -0,0 +1,23 @@
+"""Automatic account resolution — users never pass account IDs."""
+
+from __future__ import annotations
+
+from homecloud_core.config import ProfileConfig
+from homecloud_core.errors import NotConfiguredError
+from homecloud_core.session import ProfileSession, set_active_account
+
+
+def resolve_account_id(profile: ProfileConfig, session: ProfileSession) -> str:
+    if session.active_account_id:
+        return session.active_account_id
+    if profile.default_account_id:
+        return profile.default_account_id
+    if session.last_used_account_id:
+        return session.last_used_account_id
+    raise NotConfiguredError(
+        "No active account for this profile. Run: homecloud configure or homecloud accounts switch"
+    )
+
+
+def remember_account(profile_name: str, account_id: str) -> None:
+    set_active_account(profile_name, account_id)

homecloud_core/config.py

@@ -0,0 +1,165 @@
+"""Persistent credentials — Access Keys only, no session tokens."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from homecloud_core.defaults import DEFAULT_PROFILE, platform_apex
+from homecloud_core.env import env_config_dir, env_credentials_file
+
+
+def homecloud_dir() -> Path:
+    override = env_config_dir()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".homecloud"
+
+
+def credentials_path() -> Path:
+    override = env_credentials_file()
+    if override:
+        return Path(override).expanduser()
+    return homecloud_dir() / "credentials"
+
+
+@dataclass
+class ProfileConfig:
+    name: str
+    apex: str = platform_apex()
+    default_account_id: str | None = None
+    access_key_id: str | None = None
+    secret_access_key: str | None = None
+
+    def require_access_key(self) -> tuple[str, str, str]:
+        if not self.default_account_id:
+            raise ValueError("No account configured for this profile. Run: homecloud configure")
+        if not self.access_key_id or not self.secret_access_key:
+            raise ValueError("Access Key not configured. Run: homecloud configure")
+        return self.default_account_id, self.access_key_id, self.secret_access_key
+
+
+@dataclass
+class CredentialsFile:
+    version: int
+    default_profile: str
+    profiles: dict[str, ProfileConfig]
+
+    def get_profile(self, name: str | None = None) -> ProfileConfig:
+        profile_name = name or self.default_profile
+        if profile_name not in self.profiles:
+            raise ValueError(f"Profile not found: {profile_name}")
+        return self.profiles[profile_name]
+
+
+def _profile_from_dict(name: str, data: dict[str, Any]) -> ProfileConfig:
+    return ProfileConfig(
+        name=name,
+        apex=data.get("apex", platform_apex()),
+        default_account_id=data.get("default_account_id"),
+        access_key_id=data.get("access_key_id"),
+        secret_access_key=data.get("secret_access_key"),
+    )
+
+
+def _strip_legacy_session_fields(data: dict[str, Any]) -> dict[str, Any]:
+    cleaned = dict(data)
+    cleaned.pop("access_token", None)
+    cleaned.pop("console_url", None)
+    cleaned.pop("mq_url", None)
+    cleaned.pop("so_url", None)
+    cleaned.pop("secrets_url", None)
+    return cleaned
+
+
+def _normalize_raw(data: dict[str, Any]) -> dict[str, Any]:
+    if "profiles" in data:
+        return {
+            "version": data.get("version", 2),
+            "default_profile": data.get("default_profile", DEFAULT_PROFILE),
+            "profiles": {
+                name: _strip_legacy_session_fields(profile_data)
+                for name, profile_data in data["profiles"].items()
+            },
+        }
+
+    profile = _strip_legacy_session_fields(data)
+    return {
+        "version": data.get("version", 2),
+        "default_profile": data.get("default_profile", DEFAULT_PROFILE),
+        "profiles": {DEFAULT_PROFILE: profile},
+    }
+
+
+def load_credentials(path: Path | None = None) -> CredentialsFile:
+    cred_path = path or credentials_path()
+    if not cred_path.exists():
+        raise FileNotFoundError(
+            f"Credentials file not found: {cred_path}. Run: homecloud configure"
+        )
+
+    raw = json.loads(cred_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError("Invalid credentials file: expected JSON object")
+
+    normalized = _normalize_raw(raw)
+    profiles = {
+        name: _profile_from_dict(name, profile_data)
+        for name, profile_data in normalized.get("profiles", {}).items()
+    }
+    if not profiles:
+        raise ValueError("No profiles found in credentials file")
+
+    return CredentialsFile(
+        version=int(normalized.get("version", 2)),
+        default_profile=normalized.get("default_profile", DEFAULT_PROFILE),
+        profiles=profiles,
+    )
+
+
+def save_credentials(credentials: CredentialsFile, path: Path | None = None) -> Path:
+    cred_path = path or credentials_path()
+    cred_path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = {
+        "version": credentials.version,
+        "default_profile": credentials.default_profile,
+        "profiles": {
+            name: {
+                "apex": profile.apex,
+                "default_account_id": profile.default_account_id,
+                "access_key_id": profile.access_key_id,
+                "secret_access_key": profile.secret_access_key,
+            }
+            for name, profile in credentials.profiles.items()
+        },
+    }
+
+    cred_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    try:
+        cred_path.chmod(0o600)
+    except OSError:
+        pass
+    return cred_path
+
+
+def upsert_profile(profile: ProfileConfig, *, make_default: bool = True) -> Path:
+    try:
+        credentials = load_credentials()
+    except FileNotFoundError:
+        credentials = CredentialsFile(version=2, default_profile=profile.name, profiles={})
+
+    credentials.profiles[profile.name] = profile
+    if make_default:
+        credentials.default_profile = profile.name
+    return save_credentials(credentials)
+
+
+def mask_secret(value: str | None) -> str:
+    if not value:
+        return ""
+    if len(value) <= 8:
+        return "****"
+    return f"{value[:4]}...{value[-4:]}"

homecloud_core/context.py

@@ -0,0 +1,323 @@
+"""Runtime context — wires credentials, session, transport, and account resolution."""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+from collections.abc import Callable
+from typing import Any
+
+from homecloud_core.account import remember_account, resolve_account_id
+from homecloud_core.config import (
+    ProfileConfig,
+    load_credentials,
+    upsert_profile,
+)
+from homecloud_core.defaults import DEFAULT_PROFILE, platform_apex
+from homecloud_core.env import (
+    env_access_key_id,
+    env_account_id,
+    env_apex,
+    env_profile,
+    env_secret_access_key,
+)
+from homecloud_core.errors import HomeCloudError, NotConfiguredError, NotLoggedInError
+from homecloud_core.mfa import MfaResolver
+from homecloud_core.session import (
+    get_access_token,
+    load_session,
+    migrate_legacy_token_from_credentials,
+    set_access_token,
+)
+from homecloud_core.transport import Transport
+
+
+class CoreContext:
+    """
+    Shared runtime for SDK and CLI.
+
+    Programmatic path (default): Access Key ID + Secret → data-plane SigV1.
+    Interactive path (CLI): optional console JWT via login / login_browser (+ MFA).
+    """
+
+    def __init__(
+        self,
+        profile_name: str | None = None,
+        *,
+        access_key_id: str | None = None,
+        secret_access_key: str | None = None,
+        account_id: str | None = None,
+        apex: str | None = None,
+        mfa_code: str | None = None,
+        mfa_prompt: Callable[[str], str] | None = None,
+        interactive_mfa: bool = False,
+        mfa_choose_method: Callable[[list[str], list[dict] | None], str] | None = None,
+    ) -> None:
+        explicit = profile_name or env_profile()
+        try:
+            credentials = load_credentials()
+            self.profile_name = explicit or credentials.default_profile or DEFAULT_PROFILE
+            try:
+                self.profile = credentials.get_profile(self.profile_name)
+            except ValueError:
+                self.profile = ProfileConfig(name=self.profile_name)
+        except FileNotFoundError:
+            self.profile_name = explicit or DEFAULT_PROFILE
+            self.profile = ProfileConfig(name=self.profile_name)
+
+        self._session = load_session().get(self.profile_name)
+        self._apply_env_overrides()
+
+        # Constructor credentials win over file + env (AWS-style).
+        if access_key_id:
+            self.profile.access_key_id = access_key_id
+        if secret_access_key:
+            self.profile.secret_access_key = secret_access_key
+        if account_id:
+            self.profile.default_account_id = account_id
+            self._account_id = account_id
+        else:
+            self._account_id = None
+        if apex:
+            self.profile.apex = apex.strip().rstrip("/")
+
+        self._mfa_prompt = mfa_prompt
+        self._interactive_mfa = interactive_mfa
+        self._mfa_choose_method = mfa_choose_method
+        self._mfa_resolver = MfaResolver(
+            mfa_code=mfa_code,
+            prompt=mfa_prompt,
+            interactive=interactive_mfa,
+            choose_method=mfa_choose_method,
+        )
+        self._transport = Transport(
+            apex=self.profile.apex,
+            access_key_id=self.profile.access_key_id,
+            secret_access_key=self.profile.secret_access_key,
+            access_token=self._session.access_token,
+            # MFA only when interactive CLI/tools opt in — never on default SDK path.
+            mfa_resolver=self._mfa_resolver if interactive_mfa or mfa_code else None,
+        )
+
+    def _apply_env_overrides(self) -> None:
+        if apex := env_apex():
+            self.profile.apex = apex
+        if account := env_account_id():
+            self.profile.default_account_id = account
+        if key_id := env_access_key_id():
+            self.profile.access_key_id = key_id
+        if secret := env_secret_access_key():
+            self.profile.secret_access_key = secret
+
+    @property
+    def transport(self) -> Transport:
+        return self._transport
+
+    @property
+    def has_access_key(self) -> bool:
+        return bool(self.profile.access_key_id and self.profile.secret_access_key)
+
+    @property
+    def has_console_session(self) -> bool:
+        return bool(self._transport.access_token)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def require_access_key(self) -> None:
+        if not self.has_access_key:
+            raise NotConfiguredError(
+                "Access Key not configured. Pass access_key_id/secret_access_key, "
+                "set HOMECLOUD_ACCESS_KEY_ID / HC_ACCESS_KEY_ID, or run: homecloud configure"
+            )
+
+    def require_console_session(self) -> None:
+        if not self.has_console_session:
+            raise NotLoggedInError(
+                "This operation needs a console JWT (human session). "
+                "For automation use Access Key data-plane APIs instead. "
+                "Interactive: client.login(...) or homecloud login"
+            )
+
+    def account_id(self) -> str:
+        if self._account_id is not None:
+            return self._account_id
+        try:
+            account_id = resolve_account_id(self.profile, self._session)
+        except NotConfiguredError:
+            self.require_access_key()
+            account_id = self._transport.resolve_access_key_account_id()
+        remember_account(self.profile_name, account_id)
+        self._account_id = account_id
+        return account_id
+
+    def _apply_access_token(self, token: str) -> None:
+        set_access_token(self.profile_name, token)
+        self._transport.access_token = token
+        self._session = load_session().get(self.profile_name)
+        self._auto_select_account()
+
+    def login(self, username: str, password: str, *, mfa_code: str | None = None) -> None:
+        """Interactive console login — not for unattended SDK/automation."""
+        if mfa_code or self._interactive_mfa:
+            self._mfa_resolver = MfaResolver(
+                mfa_code=mfa_code,
+                prompt=self._mfa_prompt,
+                interactive=self._interactive_mfa,
+                choose_method=self._mfa_choose_method,
+            )
+            self._transport.set_mfa_resolver(self._mfa_resolver)
+
+        body: dict[str, Any] = {"username": username, "password": password}
+        if mfa_code:
+            body["mfa_code"] = mfa_code
+
+        data = self._transport.console_request(
+            "POST",
+            "auth/login",
+            json=body,
+            require_auth=False,
+        )
+        token = data.get("access_token")
+        if not token:
+            raise HomeCloudError("Login failed")
+        self._apply_access_token(str(token))
+
+    def login_browser(
+        self,
+        *,
+        open_browser: bool = True,
+        on_waiting: Callable[[str], None] | None = None,
+    ) -> None:
+        """Browser/passkey console login — interactive tools only."""
+        start = self._transport.console_request(
+            "POST",
+            "auth/cli/session",
+            require_auth=False,
+        )
+        session_id = start.get("session_id")
+        verification_uri = start.get("verification_uri")
+        if not session_id or not verification_uri:
+            raise HomeCloudError("Failed to start browser login session")
+
+        expires_in = int(start.get("expires_in") or 600)
+        interval = max(1, int(start.get("interval") or 2))
+        deadline = time.monotonic() + expires_in
+
+        if open_browser:
+            webbrowser.open(str(verification_uri))
+        if on_waiting:
+            on_waiting(str(verification_uri))
+
+        while time.monotonic() < deadline:
+            poll = self._transport.console_request(
+                "GET",
+                f"auth/cli/session/{session_id}",
+                require_auth=False,
+                _skip_mfa=True,
+            )
+            status = str(poll.get("status") or "")
+            if status == "complete":
+                token = poll.get("access_token")
+                if not token:
+                    raise HomeCloudError("Browser login completed without access token")
+                self._apply_access_token(str(token))
+                return
+            if status == "expired":
+                raise HomeCloudError("Browser login session expired")
+            time.sleep(interval)
+
+        raise HomeCloudError("Browser login timed out")
+
+    def _auto_select_account(self) -> None:
+        if self._session.active_account_id or self.profile.default_account_id:
+            return
+        accounts = self.list_accounts()
+        if len(accounts) == 1:
+            remember_account(self.profile_name, str(accounts[0]["id"]))
+
+    def list_accounts(self) -> list[dict[str, Any]]:
+        self.require_console_session()
+        data = self._transport.console_request("GET", "accounts")
+        return data.get("items", data if isinstance(data, list) else [])
+
+    def switch_account(self, account_ref: str) -> None:
+        accounts = self.list_accounts()
+        match = next(
+            (
+                account
+                for account in accounts
+                if str(account.get("id")) == account_ref
+                or str(account.get("slug")) == account_ref
+                or str(account.get("name")) == account_ref
+            ),
+            None,
+        )
+        if not match:
+            raise HomeCloudError(f"Account not found: {account_ref}")
+        remember_account(self.profile_name, str(match["id"]))
+        self._account_id = str(match["id"])
+
+    @staticmethod
+    def configure_profile(
+        *,
+        profile_name: str,
+        access_key_id: str,
+        secret_access_key: str,
+        default_account_id: str | None = None,
+        apex: str | None = None,
+        make_default: bool = True,
+    ) -> None:
+        upsert_profile(
+            ProfileConfig(
+                name=profile_name,
+                apex=apex or platform_apex(),
+                access_key_id=access_key_id,
+                secret_access_key=secret_access_key,
+                default_account_id=default_account_id,
+            ),
+            make_default=make_default,
+        )
+
+    @staticmethod
+    def import_credentials_file(
+        raw: dict[str, Any],
+        *,
+        profile_name: str = DEFAULT_PROFILE,
+    ) -> None:
+        migrate_legacy_token_from_credentials(profile_name, raw.get("access_token"))
+        CoreContext.configure_profile(
+            profile_name=profile_name,
+            access_key_id=raw["access_key_id"],
+            secret_access_key=raw["secret_access_key"],
+            default_account_id=raw.get("default_account_id"),
+            apex=raw.get("apex"),
+        )
+
+    def config_summary(self) -> dict[str, Any]:
+        from homecloud_core.config import credentials_path, load_credentials, mask_secret
+        from homecloud_core.session import session_path
+
+        try:
+            load_credentials()
+            configured = True
+        except FileNotFoundError:
+            configured = False
+
+        return {
+            "profile": self.profile_name,
+            "apex": self.profile.apex,
+            "credentials_file": str(credentials_path()),
+            "session_file": str(session_path()),
+            "configured": configured,
+            "has_access_key": self.has_access_key,
+            "has_console_session": self.has_console_session,
+            "access_key_id": self.profile.access_key_id,
+            "secret_access_key": mask_secret(self.profile.secret_access_key),
+            "logged_in": bool(get_access_token(self.profile_name)),
+            "has_account": bool(
+                self._account_id
+                or self._session.active_account_id
+                or self.profile.default_account_id
+            ),
+        }

homecloud_core/defaults.py

@@ -0,0 +1,39 @@
+"""Platform endpoint defaults — hidden from end users."""
+
+from __future__ import annotations
+
+from homecloud_core.env import env_apex
+
+DEFAULT_APEX = "holab.abrdns.com"
+DEFAULT_PROFILE = "default"
+WHOAMI_PATH = "/access-key/whoami"
+WHOAMI_ACCOUNT_SENTINEL = "-"
+
+
+def platform_apex() -> str:
+    return env_apex() or DEFAULT_APEX
+
+
+def console_url(apex: str | None = None) -> str:
+    host = apex or platform_apex()
+    return f"https://console.{host}/api/v1"
+
+
+def console_web_url(apex: str | None = None) -> str:
+    host = apex or platform_apex()
+    return f"https://console.{host}"
+
+
+def mq_url(apex: str | None = None) -> str:
+    host = apex or platform_apex()
+    return f"https://mq.{host}"
+
+
+def so_url(apex: str | None = None) -> str:
+    host = apex or platform_apex()
+    return f"https://so.{host}"
+
+
+def secrets_url(apex: str | None = None) -> str:
+    host = apex or platform_apex()
+    return f"https://secrets.{host}"

homecloud_core/env.py

@@ -0,0 +1,49 @@
+"""Environment variable helpers — HOMECLOUD_* canonical, HC_* short aliases."""
+
+from __future__ import annotations
+
+import os
+
+
+def env_first(*names: str) -> str | None:
+    """Return the first non-empty env value among ``names`` (in order)."""
+    for name in names:
+        value = os.environ.get(name)
+        if value is not None and value.strip() != "":
+            return value
+    return None
+
+
+def env_profile() -> str | None:
+    return env_first("HOMECLOUD_PROFILE", "HC_PROFILE")
+
+
+def env_apex() -> str | None:
+    value = env_first("HOMECLOUD_APEX", "HC_APEX")
+    if value is None:
+        return None
+    return value.strip().rstrip("/")
+
+
+def env_account_id() -> str | None:
+    return env_first("HOMECLOUD_ACCOUNT_ID", "HC_ACCOUNT_ID")
+
+
+def env_access_key_id() -> str | None:
+    return env_first("HOMECLOUD_ACCESS_KEY_ID", "HC_ACCESS_KEY_ID")
+
+
+def env_secret_access_key() -> str | None:
+    return env_first("HOMECLOUD_SECRET_ACCESS_KEY", "HC_SECRET_ACCESS_KEY")
+
+
+def env_config_dir() -> str | None:
+    return env_first("HOMECLOUD_CONFIG_DIR", "HC_CONFIG_DIR")
+
+
+def env_credentials_file() -> str | None:
+    return env_first("HOMECLOUD_CREDENTIALS_FILE", "HC_CREDENTIALS_FILE")
+
+
+def env_session_file() -> str | None:
+    return env_first("HOMECLOUD_SESSION_FILE", "HC_SESSION_FILE")

homecloud_core/errors.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class HomeCloudError(Exception):
+    def __init__(self, message: str, *, status_code: int | None = None, detail: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+    @property
+    def error_payload(self) -> dict[str, Any] | None:
+        """Normalized `{code, message, details}` from either envelope or legacy detail dict."""
+        if not isinstance(self.detail, dict):
+            return None
+        error = self.detail.get("error")
+        if isinstance(error, dict) and error.get("code"):
+            details = error.get("details") if isinstance(error.get("details"), dict) else {}
+            return {
+                "code": str(error.get("code")),
+                "message": str(error.get("message") or error.get("code")),
+                "details": details,
+            }
+        if self.detail.get("code"):
+            details = {
+                key: value
+                for key, value in self.detail.items()
+                if key not in {"code", "message"}
+            }
+            return {
+                "code": str(self.detail.get("code")),
+                "message": str(self.detail.get("message") or self.detail.get("code")),
+                "details": details,
+            }
+        return None
+
+    @property
+    def error_code(self) -> str | None:
+        payload = self.error_payload
+        return payload["code"] if payload else None
+
+    @property
+    def error_details(self) -> dict[str, Any]:
+        payload = self.error_payload
+        if not payload:
+            return {}
+        return dict(payload.get("details") or {})
+
+
+class NotConfiguredError(HomeCloudError):
+    pass
+
+
+class NotLoggedInError(HomeCloudError):
+    pass