homecloud-sdk 0.3.2__tar.gz

homecloud_sdk-0.3.2/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: homecloud-sdk
+Version: 0.3.2
+Summary: HomeCloud Python SDK and core client library
+Author: HomeCloud
+License: MIT
+Project-URL: Homepage, https://github.com/HomeCloudLab/homecloud-sdk
+Project-URL: Documentation, https://docs.holab.abrdns.com/sdk/
+Keywords: homecloud,sdk,object-storage,mq
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+
+# HomeCloud SDK
+
+Python SDK for HomeCloud (`pip install homecloud-sdk`).
+
+## Auth model (cloud-style)
+
+| Who | How | MFA |
+|-----|-----|-----|
+| **SDK / automation** | Access Key ID + Secret (SigV1 data plane) | Never on requests |
+| **CLI / humans** | `homecloud login` → console JWT | At login / step-up only |
+
+Access Keys are created once in the Console (human + MFA there). Runtime SDK calls do **not** re-prompt MFA.
+
+```python
+from homecloud_sdk import HomeCloud
+
+# Recommended — explicit credentials (CI / servers)
+client = HomeCloud(
+    access_key="HCAK...",
+    secret_key="...",
+)
+
+# Or environment (HOMECLOUD_* / HC_*)
+client = HomeCloud.from_env()
+
+# Or ~/.homecloud/credentials (+ optional HC_PROFILE)
+client = HomeCloud()
+
+# Data plane — Access Key only, no login
+client.so.upload("docs", "./file.txt", key="a.txt")
+client.mq.send("orders", {"id": 1})
+
+# Interactive helpers only (CLI/tools) — may involve MFA
+# client.login("alice", "…")
+# client.login_browser()
+```
+
+## Architecture
+
+```text
+homecloud_core/     ← auth, routing, signing, sessions, MFA helpers
+homecloud_sdk/      ← public API (HomeCloud / HomeCloudClient)
+```
+
+CLI (`homecloud-cli`) is a Typer/Rich wrapper; it opts into `interactive_mfa=True`.
+
+## Install
+
+```bash
+pip install homecloud-sdk
+```
+
+Until PyPI is configured, use a Git checkout or sibling editable install:
+
+```bash
+pip install -e "../homecloud-sdk"
+```
+
+PyPI publish is wired via `.github/workflows/publish-pypi.yml` (tag `v*` + `PYPI_API_TOKEN` or Trusted Publishing).
+
+## Operations by plane
+
+| API | Auth | Notes |
+|-----|------|-------|
+| `so.upload` / `download` / `sync_*` / `list_objects` / `delete` | Access Key | Primary SDK path |
+| `so.head_object` (`object_metadata`) | Access Key | Metadata only — no object body (AWS HeadObject) |
+| `mq.send` / `receive` | Access Key | Primary SDK path |
+| `account_id()` | Access Key whoami | No JWT |
+| `so.list_buckets` / `create_bucket` | Console JWT | Management helper |
+| `queues.list` / `apps.list` / `accounts.*` | Console JWT | Management helper |
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `~/.homecloud/credentials` | Access Keys (multi-profile JSON) |
+| `~/.homecloud/session` | Console JWT (interactive only) |
+
+### Profile / env
+
+1. Constructor `profile=` / `access_key_id=` …
+2. `HOMECLOUD_PROFILE` / `HC_PROFILE`
+3. credentials `default_profile`
+4. `default`
+
+| Variable | Short | Effect |
+|----------|-------|--------|
+| `HOMECLOUD_PROFILE` | `HC_PROFILE` | Active profile |
+| `HOMECLOUD_ACCESS_KEY_ID` | `HC_ACCESS_KEY_ID` | Access key |
+| `HOMECLOUD_SECRET_ACCESS_KEY` | `HC_SECRET_ACCESS_KEY` | Secret |
+| `HOMECLOUD_ACCOUNT_ID` | `HC_ACCOUNT_ID` | Optional account |
+| `HOMECLOUD_APEX` | `HC_APEX` | Platform domain |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+pytest tests/test_live_integration.py -q   # needs Access Keys in ~/.homecloud
+```
+
+### Service-account verification (pre-PyPI)
+
+Mints a dedicated Access Key named `homecloud-sdk-test` (requires a one-time
+`homecloud login` to create the key), then runs a **clean subprocess** with
+`HomeCloud.from_env()` — no JWT session, no MFA, no browser:
+
+```bash
+python scripts/verify_service_account_flow.py
+```
+
+Expected: `PASS: service-account flow works without login/JWT/MFA/browser`.

homecloud_sdk-0.3.2/README.md

@@ -0,0 +1,112 @@
+# HomeCloud SDK
+
+Python SDK for HomeCloud (`pip install homecloud-sdk`).
+
+## Auth model (cloud-style)
+
+| Who | How | MFA |
+|-----|-----|-----|
+| **SDK / automation** | Access Key ID + Secret (SigV1 data plane) | Never on requests |
+| **CLI / humans** | `homecloud login` → console JWT | At login / step-up only |
+
+Access Keys are created once in the Console (human + MFA there). Runtime SDK calls do **not** re-prompt MFA.
+
+```python
+from homecloud_sdk import HomeCloud
+
+# Recommended — explicit credentials (CI / servers)
+client = HomeCloud(
+    access_key="HCAK...",
+    secret_key="...",
+)
+
+# Or environment (HOMECLOUD_* / HC_*)
+client = HomeCloud.from_env()
+
+# Or ~/.homecloud/credentials (+ optional HC_PROFILE)
+client = HomeCloud()
+
+# Data plane — Access Key only, no login
+client.so.upload("docs", "./file.txt", key="a.txt")
+client.mq.send("orders", {"id": 1})
+
+# Interactive helpers only (CLI/tools) — may involve MFA
+# client.login("alice", "…")
+# client.login_browser()
+```
+
+## Architecture
+
+```text
+homecloud_core/     ← auth, routing, signing, sessions, MFA helpers
+homecloud_sdk/      ← public API (HomeCloud / HomeCloudClient)
+```
+
+CLI (`homecloud-cli`) is a Typer/Rich wrapper; it opts into `interactive_mfa=True`.
+
+## Install
+
+```bash
+pip install homecloud-sdk
+```
+
+Until PyPI is configured, use a Git checkout or sibling editable install:
+
+```bash
+pip install -e "../homecloud-sdk"
+```
+
+PyPI publish is wired via `.github/workflows/publish-pypi.yml` (tag `v*` + `PYPI_API_TOKEN` or Trusted Publishing).
+
+## Operations by plane
+
+| API | Auth | Notes |
+|-----|------|-------|
+| `so.upload` / `download` / `sync_*` / `list_objects` / `delete` | Access Key | Primary SDK path |
+| `so.head_object` (`object_metadata`) | Access Key | Metadata only — no object body (AWS HeadObject) |
+| `mq.send` / `receive` | Access Key | Primary SDK path |
+| `account_id()` | Access Key whoami | No JWT |
+| `so.list_buckets` / `create_bucket` | Console JWT | Management helper |
+| `queues.list` / `apps.list` / `accounts.*` | Console JWT | Management helper |
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `~/.homecloud/credentials` | Access Keys (multi-profile JSON) |
+| `~/.homecloud/session` | Console JWT (interactive only) |
+
+### Profile / env
+
+1. Constructor `profile=` / `access_key_id=` …
+2. `HOMECLOUD_PROFILE` / `HC_PROFILE`
+3. credentials `default_profile`
+4. `default`
+
+| Variable | Short | Effect |
+|----------|-------|--------|
+| `HOMECLOUD_PROFILE` | `HC_PROFILE` | Active profile |
+| `HOMECLOUD_ACCESS_KEY_ID` | `HC_ACCESS_KEY_ID` | Access key |
+| `HOMECLOUD_SECRET_ACCESS_KEY` | `HC_SECRET_ACCESS_KEY` | Secret |
+| `HOMECLOUD_ACCOUNT_ID` | `HC_ACCOUNT_ID` | Optional account |
+| `HOMECLOUD_APEX` | `HC_APEX` | Platform domain |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+pytest tests/test_live_integration.py -q   # needs Access Keys in ~/.homecloud
+```
+
+### Service-account verification (pre-PyPI)
+
+Mints a dedicated Access Key named `homecloud-sdk-test` (requires a one-time
+`homecloud login` to create the key), then runs a **clean subprocess** with
+`HomeCloud.from_env()` — no JWT session, no MFA, no browser:
+
+```bash
+python scripts/verify_service_account_flow.py
+```
+
+Expected: `PASS: service-account flow works without login/JWT/MFA/browser`.

homecloud_sdk-0.3.2/homecloud_core/__init__.py

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

homecloud_sdk-0.3.2/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_sdk-0.3.2/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:]}"