proxcli 0.1.0__py3-none-any.whl

proxmox/client/auth.py

@@ -0,0 +1,113 @@
+"""Authentication manager for Proxmox VE API."""
+
+from __future__ import annotations
+
+import base64
+from enum import Enum
+from typing import Any
+
+import httpx
+
+from proxmox.client.exceptions import AuthError
+
+
+class AuthMethod(str, Enum):
+    PASSWORD = "password"
+    API_TOKEN = "api_token"
+
+
+class AuthManager:
+    """Handles Proxmox authentication (password-based ticket or API token).
+
+    For password auth: acquires a ticket and CSRF token via
+    POST /api2/json/access/ticket, then injects Cookie + CSRFPreventionToken headers.
+    For API token auth: base64-encodes the token and sets an Authorization header.
+
+    Caches credentials in memory for the process lifetime.
+    """
+
+    def __init__(self):
+        self._method: AuthMethod | None = None
+        self._ticket: str | None = None
+        self._csrf_token: str | None = None
+        self._auth_header: str | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def authenticate_password(
+        self, base_url: str, username: str, password: str, *, verify: bool = True
+    ) -> None:
+        """Acquire a ticket from Proxmox using username + password."""
+        url = f"{base_url}/api2/json/access/ticket"
+        try:
+            resp = httpx.post(
+                url,
+                data={"username": username, "password": password},
+                verify=verify,
+                timeout=30,
+            )
+        except httpx.RequestError as exc:
+            raise AuthError(f"Failed to reach Proxmox at {base_url}: {exc}") from exc
+
+        if resp.status_code != 200:
+            msg = resp.json().get("message", resp.text)
+            raise AuthError(f"Authentication failed: {msg}")
+
+        data = resp.json()["data"]
+        self._ticket = data["ticket"]
+        self._csrf_token = data["CSRFPreventionToken"]
+        self._method = AuthMethod.PASSWORD
+        self._auth_header = None
+
+    def set_api_token(self, user: str, token_id: str, secret: str) -> None:
+        """Use a Proxmox API token for authentication."""
+        raw = f"{user}!{token_id}={secret}"
+        encoded = base64.b64encode(raw.encode()).decode()
+        self._auth_header = f"PVEAPIToken {encoded}"
+        self._method = AuthMethod.API_TOKEN
+        self._ticket = None
+        self._csrf_token = None
+
+    def get_headers(self) -> dict[str, str]:
+        """Return the HTTP auth headers needed for the current auth method."""
+        if self._method == AuthMethod.API_TOKEN:
+            return {"Authorization": self._auth_header or ""}
+
+        if self._method == AuthMethod.PASSWORD:
+            headers: dict[str, str] = {}
+            if self._ticket:
+                headers["Cookie"] = f"PVEAuthCookie={self._ticket}"
+            if self._csrf_token:
+                headers["CSRFPreventionToken"] = self._csrf_token
+            return headers
+
+        return {}
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._method is not None
+
+    @property
+    def method(self) -> AuthMethod | None:
+        return self._method
+
+    def clear(self) -> None:
+        """Wipe cached credentials."""
+        self._method = None
+        self._ticket = None
+        self._csrf_token = None
+        self._auth_header = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for debugging (never exposes secrets)."""
+        return {
+            "method": self._method.value if self._method else None,
+            "has_ticket": self._ticket is not None,
+            "has_csrf": self._csrf_token is not None,
+        }

proxmox/client/client.py

@@ -0,0 +1,217 @@
+"""HTTP client for the Proxmox VE REST API."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from proxmox.client.auth import AuthManager
+from proxmox.client.exceptions import AuthError, ProxmoxAPIError
+
+
+class ProxmoxClient:
+    """Wraps httpx to talk to the Proxmox VE JSON API.
+
+    Handles:
+    - Base URL construction (prefixes /api2/json)
+    - Auth header injection
+    - Timeout control
+    - TLS verification toggle
+    - Retry on 5xx with exponential backoff
+    - Dry-run mode
+    - CSRF ticket auto-refresh on 401
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_manager: AuthManager,
+        *,
+        timeout: int = 30,
+        verify_tls: bool = True,
+        dry_run: bool = False,
+        retries: int = 3,
+        verbose: bool = False,
+    ):
+        # Normalise trailing slash
+        self._base_url = base_url.rstrip("/")
+        self._auth = auth_manager
+        self._timeout = timeout
+        self._verify_tls = verify_tls
+        self._dry_run = dry_run
+        self._max_retries = retries
+        self._verbose = verbose
+        self._username: str | None = None
+        self._password: str | None = None
+
+    # ------------------------------------------------------------------
+    # Public HTTP methods
+    # ------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """Send an HTTP request and unwrap the Proxmox JSON envelope.
+
+        Returns ``response.json()["data"]`` on success.
+        """
+        path = self._normalise_path(path)
+        full_url = f"{self._base_url}/api2/json{path}"
+
+        self._debug(f"{method} {full_url}")
+        if data:
+            self._debug(f"  body: {data}")
+
+        if self._dry_run:
+            self._print_dry_run(method, full_url, data)
+            return {}
+
+        return self._send_with_retry(method, full_url, params, data)
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any] | list[Any]:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self, path: str, *, data: dict[str, Any] | None = None
+    ) -> dict[str, Any] | list[Any]:
+        return self.request("POST", path, data=data)
+
+    def put(
+        self, path: str, *, data: dict[str, Any] | None = None
+    ) -> dict[str, Any] | list[Any]:
+        return self.request("PUT", path, data=data)
+
+    def delete(
+        self, path: str, *, params: dict[str, Any] | None = None
+    ) -> dict[str, Any] | list[Any]:
+        return self.request("DELETE", path, params=params)
+
+    def set_credentials(self, username: str, password: str) -> None:
+        """Store credentials for lazy / auto-refresh authentication."""
+        self._username = username
+        self._password = password
+
+    def authenticate(self) -> None:
+        """Explicitly authenticate the client (password method)."""
+        if self._username and self._password:
+            self._auth.authenticate_password(
+                self._base_url, self._username, self._password, verify=self._verify_tls
+            )
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _normalise_path(path: str) -> str:
+        if not path.startswith("/"):
+            path = "/" + path
+        return path
+
+    def _send_with_retry(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any] | None,
+        data: dict[str, Any] | None,
+    ) -> dict[str, Any] | list[Any]:
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                return self._send_one(method, url, params, data)
+            except AuthError:
+                raise  # don't retry auth errors
+            except ProxmoxAPIError as exc:
+                if exc.status_code < 500:
+                    raise
+                last_exc = exc
+                if attempt < self._max_retries:
+                    delay = 2**attempt
+                    self._debug(f"  ⏳ retry {attempt + 1}/{self._max_retries} in {delay}s ...")
+                    time.sleep(delay)
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    delay = 2**attempt
+                    self._debug(f"  ⏳ timeout, retry {attempt + 1}/{self._max_retries} in {delay}s ...")
+                    time.sleep(delay)
+
+        if isinstance(last_exc, ProxmoxAPIError):
+            raise last_exc
+        raise ProxmoxAPIError(0, {"message": str(last_exc)}, url)
+
+    def _send_one(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any] | None,
+        data: dict[str, Any] | None,
+    ) -> dict[str, Any] | list[Any]:
+        headers = self._auth.get_headers()
+
+        try:
+            resp = httpx.request(
+                method=method,
+                url=url,
+                params=params,
+                data=data,
+                headers=headers,
+                timeout=self._timeout,
+                verify=self._verify_tls,
+            )
+        except httpx.TimeoutException:
+            raise
+        except httpx.RequestError as exc:
+            # Wrap connection / TLS errors
+            msg = str(exc)
+            if "SSL" in msg or "certificate" in msg.lower():
+                msg += "\nHint: use --insecure to skip TLS verification"
+            raise ProxmoxAPIError(0, {"message": msg}, url) from exc
+
+        self._debug(f"  ← {resp.status_code}")
+
+        if resp.status_code == 401 and self._username and self._password:
+            # Auto-refresh ticket once
+            self._debug("  🔄 re-authenticating ...")
+            self.authenticate()
+            headers = self._auth.get_headers()
+            resp = httpx.request(
+                method=method,
+                url=url,
+                params=params,
+                data=data,
+                headers=headers,
+                timeout=self._timeout,
+                verify=self._verify_tls,
+            )
+
+        if not (200 <= resp.status_code < 300):
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"message": resp.text}
+            raise ProxmoxAPIError(resp.status_code, body, url)
+
+        # Unwrap Proxmox JSON envelope
+        envelope = resp.json()
+        return envelope.get("data", envelope)
+
+    def _print_dry_run(self, method: str, url: str, data: dict[str, Any] | None) -> None:
+        print(f"{method} {url}")
+        print(f"Headers: {self._auth.get_headers()}")
+        if data:
+            print(f"Body: {data}")
+
+    def _debug(self, message: str) -> None:
+        if self._verbose:
+            import sys
+
+            print(f"[proxmox] {message}", file=sys.stderr)

proxmox/client/exceptions.py

@@ -0,0 +1,43 @@
+"""Proxmox CLI exceptions."""
+
+
+class ProxmoxError(Exception):
+    """Base exception for proxmox CLI errors."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
+class ProxmoxAPIError(ProxmoxError):
+    """Raised when the Proxmox API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, body: dict | None = None, url: str = ""):
+        self.status_code = status_code
+        self.body = body or {}
+        self.url = url
+
+        # Try to extract a meaningful error message from Proxmox response
+        msg = body.get("message", "") if body else ""
+        if not msg and isinstance(body, dict) and "errors" in body:
+            msg = str(body["errors"])
+
+        message = f"HTTP {status_code}"
+        if url:
+            message += f" on {url}"
+        if msg:
+            message += f": {msg}"
+
+        super().__init__(message)
+
+
+class AuthError(ProxmoxError):
+    """Raised when authentication fails."""
+
+
+class ConfigError(ProxmoxError):
+    """Raised when configuration is missing or invalid."""
+
+
+class NotFoundError(ProxmoxAPIError):
+    """Raised when a resource is not found (404)."""

proxmox/config/config.py

@@ -0,0 +1,98 @@
+"""Config file loader — reads / writes credentials.json."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+from proxmox.client.exceptions import ConfigError
+from proxmox.config.models import (
+    CREDENTIALS_FILE,
+    SYSTEM_CONFIG_DIR,
+    USER_CONFIG_DIR,
+    Credentials,
+)
+
+
+class ConfigLoader:
+    """Loads and persists credentials to a JSON config file.
+
+    Priority:
+    1. ~/.config/proxmox-cli/credentials.json  (user)
+    2. /etc/proxmox-cli/credentials.json        (system)
+    """
+
+    def __init__(self, user_dir: Path | None = None, system_dir: Path | None = None):
+        self._user_dir = user_dir or USER_CONFIG_DIR
+        self._system_dir = system_dir or SYSTEM_CONFIG_DIR
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def load(self) -> Credentials:
+        """Load credentials from disk. Raises ConfigError if not found."""
+        path = self._find_file()
+        if path is None:
+            raise ConfigError(
+                "No credentials found. Run 'proxmox auth login' first, "
+                f"or place a {CREDENTIALS_FILE} in {self._user_dir} or {self._system_dir}."
+            )
+        return self._read(path)
+
+    def load_or_none(self) -> Credentials | None:
+        """Load credentials, returning None if not found."""
+        try:
+            return self.load()
+        except ConfigError:
+            return None
+
+    def save(self, credentials: Credentials) -> Path:
+        """Persist credentials to the user config directory.
+
+        Creates parent directories and sets restrictive permissions (0o600).
+        """
+        self._user_dir.mkdir(parents=True, exist_ok=True)
+        path = self._user_dir / CREDENTIALS_FILE
+
+        data = credentials.model_dump(mode="json", exclude_none=True)
+        payload = json.dumps(data, indent=2)
+        path.write_text(payload)
+
+        # Restrict permissions: owner-read/write only
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+        return path
+
+    def clear(self) -> None:
+        """Delete the user-level credentials file."""
+        path = self._user_dir / CREDENTIALS_FILE
+        if path.exists():
+            path.unlink()
+
+    def exists(self) -> bool:
+        """Return True if a credentials file can be found."""
+        return self._find_file() is not None
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _find_file(self) -> Path | None:
+        for base in (self._user_dir, self._system_dir):
+            p = base / CREDENTIALS_FILE
+            if p.exists():
+                return p
+        return None
+
+    def _read(self, path: Path) -> Credentials:
+        try:
+            raw = json.loads(path.read_text())
+        except json.JSONDecodeError as exc:
+            raise ConfigError(f"Invalid JSON in {path}: {exc}") from exc
+
+        try:
+            return Credentials(**raw)
+        except Exception as exc:
+            raise ConfigError(f"Invalid credentials in {path}: {exc}") from exc

proxmox/config/models.py

@@ -0,0 +1,51 @@
+"""Pydantic models for configuration and credentials."""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class AuthMethod(str, Enum):
+    PASSWORD = "password"
+    API_TOKEN = "api_token"
+
+
+class Credentials(BaseModel):
+    """Persisted credentials for a single Proxmox endpoint."""
+
+    url: str = Field(..., description="Proxmox API URL, e.g. https://192.168.1.10:8006")
+    username: str = Field(..., description="Username, e.g. root@pam")
+    auth_method: AuthMethod = Field(..., description="Authentication method")
+    password: str | None = Field(None, description="Password (for password auth)")
+    api_token_id: str | None = Field(None, description="Token ID (for token auth)")
+    api_token_secret: str | None = Field(None, description="Token secret (for token auth)")
+    verify_tls: bool = Field(True, description="Whether to verify TLS certificates")
+
+    @field_validator("url")
+    @classmethod
+    def url_must_have_scheme(cls, v: str) -> str:
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("URL must start with http:// or https://")
+        return v.rstrip("/")
+
+    @model_validator(mode="after")
+    def validate_auth_fields(self):
+        if self.auth_method == AuthMethod.PASSWORD and not self.password:
+            raise ValueError("Password is required for password authentication")
+        if self.auth_method == AuthMethod.API_TOKEN:
+            if not self.api_token_id:
+                raise ValueError("API token ID is required for token authentication")
+            if not self.api_token_secret:
+                raise ValueError("API token secret is required for token authentication")
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Config file paths (XDG-compliant)
+# ---------------------------------------------------------------------------
+USER_CONFIG_DIR = Path.home() / ".config" / "proxmox-cli"
+SYSTEM_CONFIG_DIR = Path("/etc/proxmox-cli")
+CREDENTIALS_FILE = "credentials.json"

proxmox/output/formatter.py

@@ -0,0 +1,26 @@
+"""Output formatter dispatcher."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from proxmox.output.json_fmt import format_json
+from proxmox.output.table_fmt import format_table
+from proxmox.output.yaml_fmt import format_yaml
+
+
+def format_output(data: Any, fmt: str, *, columns: list[str] | None = None) -> str:
+    """Dispatch to the appropriate formatter.
+
+    Args:
+        data: The data to format (dict, list, etc.)
+        fmt: One of 'json', 'table', 'yaml'
+        columns: Optional column name override for table mode.
+    """
+    if fmt == "json":
+        return format_json(data)
+    if fmt == "table":
+        return format_table(data, columns)
+    if fmt == "yaml":
+        return format_yaml(data)
+    return format_json(data)

proxmox/output/json_fmt.py

@@ -0,0 +1,11 @@
+"""JSON output formatter."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def format_json(data: Any, indent: int = 2) -> str:
+    """Render data as pretty-printed JSON."""
+    return json.dumps(data, indent=indent, ensure_ascii=False, default=str)

proxmox/output/table_fmt.py

@@ -0,0 +1,64 @@
+"""Table output formatter using rich."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+
+def format_table(data: Any, columns: list[str] | None = None) -> str:
+    """Render data as a rich-powered ASCII table.
+
+    - list[dict]  → columnar table
+    - dict        → key-value table
+    - other       → plain string
+    """
+    console = Console(force_terminal=True, color_system=None, width=120)
+    table = _build_table(data, columns)
+    with console.capture() as capture:
+        console.print(table)
+    return capture.get().rstrip()
+
+
+def _build_table(data: Any, columns: list[str] | None) -> Table:
+    if isinstance(data, list):
+        return _list_table(data, columns)
+    if isinstance(data, dict):
+        return _kv_table(data)
+    return _plain_table(data)
+
+
+def _list_table(items: list[dict], columns: list[str] | None) -> Table:
+    if not items:
+        return Table(title="No results")
+
+    # Auto-detect columns from first item keys if not specified
+    cols = columns or list(items[0].keys())
+    table = Table(show_header=True, header_style="bold")
+    for col in cols:
+        table.add_column(col, overflow="fold")
+    for item in items:
+        table.add_row(*[str(item.get(col, "")) for col in cols])
+    return table
+
+
+def _kv_table(data: dict) -> Table:
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Key", style="dim")
+    table.add_column("Value")
+    for key, value in data.items():
+        if isinstance(value, (dict, list)):
+            import json
+
+            value = json.dumps(value, default=str)
+        table.add_row(str(key), str(value))
+    return table
+
+
+def _plain_table(data: Any) -> Table:
+    table = Table()
+    table.add_column("Result")
+    table.add_row(str(data))
+    return table

proxmox/output/yaml_fmt.py

@@ -0,0 +1,12 @@
+"""YAML output formatter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+
+def format_yaml(data: Any) -> str:
+    """Render data as YAML."""
+    return yaml.dump(data, default_flow_style=False, sort_keys=False, allow_unicode=True)

proxmox/utils/helpers.py

@@ -0,0 +1,14 @@
+"""Shared helpers."""
+
+from __future__ import annotations
+
+
+def vmid_type(value: str) -> int:
+    """Argparse type for validating VMID (positive integer)."""
+    try:
+        v = int(value)
+    except ValueError:
+        raise ValueError(f"Invalid VMID '{value}': must be an integer")
+    if v <= 0:
+        raise ValueError(f"Invalid VMID '{value}': must be positive")
+    return v

proxmox/utils/logging.py

@@ -0,0 +1,15 @@
+"""Structured stderr logging."""
+
+from __future__ import annotations
+
+import sys
+
+
+def log_error(message: str) -> None:
+    """Print an error message to stderr."""
+    print(f"Error: {message}", file=sys.stderr)
+
+
+def log_info(message: str) -> None:
+    """Print an info message to stderr."""
+    print(message, file=sys.stderr)