lr-fleet 0.1.0__py3-none-any.whl

lr_fleet/__init__.py

@@ -0,0 +1,12 @@
+"""lr-fleet: CLI client for the LumenRadio fleet management REST API."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lr-fleet")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

lr_fleet/cli.py

@@ -0,0 +1,70 @@
+"""Typer-powered CLI entry point for lr-fleet."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import __version__
+from .client import DEFAULT_BASE_URL
+from .commands import CliContext
+from .commands.articles import articles
+from .commands import device as device_commands
+from .commands.devices import list_devices, replace_key, revoke, show_device
+from .commands.login import login, logout, status
+from .commands.pending import approve, pending, reject
+from .commands.provision import provision
+from .config import DEFAULT_CONFIG_PATH
+
+app = typer.Typer(help="Manage the LumenRadio fleet from the command line.")
+
+app.command("list")(list_devices)
+app.command("show")(show_device)
+app.command("revoke")(revoke)
+app.command("replace-key")(replace_key)
+app.command("pending")(pending)
+app.command("approve")(approve)
+app.command("reject")(reject)
+app.command("provision")(provision)
+app.command("articles")(articles)
+app.command("login")(login)
+app.command("logout")(logout)
+app.command("status")(status)
+app.add_typer(device_commands.app, name="device")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    base_url: str = typer.Option(
+        DEFAULT_BASE_URL,
+        "--base-url",
+        envvar="FLEET_URL",
+        help="Fleet management API base URL.",
+    ),
+    config_path: Optional[Path] = typer.Option(
+        None,
+        "--config-path",
+        help="Override the location of ~/.config/lr-fleet/token.json.",
+    ),
+    version: bool = typer.Option(False, "--version", help="Print the lr-fleet version and exit."),
+) -> None:
+    """Top-level callback: resolves --base-url/--config-path for every
+    sub-command, and handles --version."""
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+    ctx.obj = CliContext(
+        base_url=base_url.rstrip("/"),
+        config_path=config_path.expanduser() if config_path else DEFAULT_CONFIG_PATH,
+    )
+
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+__all__ = ["app"]

lr_fleet/client.py

@@ -0,0 +1,141 @@
+"""FleetClient: programmatic access to the fleet management REST API.
+
+Every method sends the bearer token given at construction; none of them
+touch a token cache, an environment variable or a terminal. Raises
+FleetError subclasses for all error conditions; never calls sys.exit().
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests as _requests
+
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    ForbiddenError,
+    NetworkError,
+    NotFoundError,
+)
+
+DEFAULT_BASE_URL = "https://fleet.cloud.lumenradio.com"
+
+
+def _error_message(resp: _requests.Response) -> str:
+    try:
+        body = resp.json()
+    except ValueError:
+        return resp.text
+    if not isinstance(body, dict):
+        return resp.text
+    detail = body.get("detail", resp.text)
+    if isinstance(detail, list):  # FastAPI validation errors
+        detail = "; ".join(str(item) for item in detail)
+    status = body.get("status")
+    return f"{status}: {detail}" if status else str(detail)
+
+
+class FleetClient:
+    """Client for the fleet management REST API under /api/v1."""
+
+    def __init__(self, access_token: str, base_url: str = DEFAULT_BASE_URL) -> None:
+        self._token = access_token
+        self._base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self._token}"
+        try:
+            resp = _requests.request(
+                method,
+                f"{self._base_url}/api/v1{path}",
+                headers=headers,
+                timeout=10,
+                **kwargs,
+            )
+        except _requests.RequestException as exc:
+            raise NetworkError(str(exc)) from exc
+
+        self._raise_for_status(resp)
+
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    @staticmethod
+    def _raise_for_status(resp: _requests.Response) -> None:
+        if resp.status_code == 401:
+            raise AuthenticationError("not signed in or token expired; run `fleet login`")
+        if resp.status_code == 403:
+            raise ForbiddenError(
+                "your account holds no Fleet access at the required tier; "
+                "ask to be added to the Entra group that carries it"
+            )
+        if not resp.ok:
+            message = _error_message(resp)
+            if resp.status_code == 404:
+                raise NotFoundError(message)
+            raise ApiError(resp.status_code, message)
+
+    # ------------------------------------------------------------------
+    # Devices
+    # ------------------------------------------------------------------
+
+    def list_devices(
+        self, *, product_id: str | None = None, online: bool | None = None
+    ) -> list[dict[str, Any]]:
+        """GET /devices."""
+        params: dict[str, Any] = {}
+        if product_id is not None:
+            params["product_id"] = product_id
+        if online is not None:
+            params["online"] = online
+        return self._request("GET", "/devices", params=params) or []
+
+    def show_device(self, uid: str) -> dict[str, Any]:
+        """GET /devices/{uid}."""
+        return self._request("GET", f"/devices/{uid}")
+
+    def revoke(self, uid: str) -> dict[str, Any]:
+        """POST /devices/{uid}/revoke."""
+        return self._request("POST", f"/devices/{uid}/revoke")
+
+    def replace_key(self, uid: str) -> dict[str, Any]:
+        """POST /devices/{uid}/replace-key."""
+        return self._request("POST", f"/devices/{uid}/replace-key")
+
+    # ------------------------------------------------------------------
+    # Pending enrolments
+    # ------------------------------------------------------------------
+
+    def list_pending(self) -> list[dict[str, Any]]:
+        """GET /pending."""
+        return self._request("GET", "/pending") or []
+
+    def approve(self, uid: str, display_name: str) -> dict[str, Any]:
+        """POST /pending/{uid}/approve."""
+        return self._request("POST", f"/pending/{uid}/approve", json={"display_name": display_name})
+
+    def reject(self, uid: str) -> dict[str, Any]:
+        """POST /pending/{uid}/reject."""
+        return self._request("POST", f"/pending/{uid}/reject")
+
+    # ------------------------------------------------------------------
+    # Hardware keys
+    # ------------------------------------------------------------------
+
+    def register_hardware_key(self, body: dict[str, Any]) -> dict[str, Any]:
+        """POST /hardware-keys."""
+        return self._request("POST", "/hardware-keys", json=body)
+
+    # ------------------------------------------------------------------
+    # Articles
+    # ------------------------------------------------------------------
+
+    def get_article(self, article: str) -> dict[str, Any]:
+        """GET /articles/{article}."""
+        return self._request("GET", f"/articles/{article}")
+
+
+__all__ = ["FleetClient", "DEFAULT_BASE_URL"]

lr_fleet/commands/__init__.py

@@ -0,0 +1,66 @@
+"""Shared helpers for fleet CLI sub-commands."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from ..client import DEFAULT_BASE_URL, FleetClient
+from ..exceptions import FleetError
+from ..session import NotLoggedIn, resolve_token
+
+# A fixed width, not the terminal's own. CliRunner and a piped `fleet list`
+# both report no real terminal size, and rich's 80-column guess truncates
+# our widest column (a 32-char uid) before the row's other fields print.
+TABLE_WIDTH = 200
+
+
+def console() -> Console:
+    """A Console at TABLE_WIDTH, for every table and detail panel."""
+    return Console(width=TABLE_WIDTH)
+
+
+@dataclass
+class CliContext:
+    """The resolved --base-url and --config-path, shared by every command."""
+
+    base_url: str
+    config_path: Path
+
+
+def print_json(data: Any) -> None:
+    """Print data as indented JSON, the --json output every read supports."""
+    typer.echo(json.dumps(data, indent=2))
+
+
+def get_client(ctx: typer.Context) -> FleetClient:
+    """Build a FleetClient for the current context, or exit with an error."""
+    cli_ctx: CliContext = ctx.obj
+    try:
+        token = resolve_token(cli_ctx.config_path)
+    except NotLoggedIn as exc:
+        typer.secho(str(exc), fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+    return FleetClient(token, cli_ctx.base_url)
+
+
+def handle_fleet_error(exc: FleetError) -> None:
+    """Print exc and exit with code 1."""
+    typer.secho(str(exc), fg=typer.colors.RED)
+    raise typer.Exit(code=1)
+
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "TABLE_WIDTH",
+    "CliContext",
+    "console",
+    "print_json",
+    "get_client",
+    "handle_fleet_error",
+]

lr_fleet/commands/articles.py

@@ -0,0 +1,62 @@
+"""`fleet articles`."""
+
+from __future__ import annotations
+
+import typer
+from rich.table import Table
+
+from ..exceptions import FleetError
+from . import console, get_client, handle_fleet_error, print_json
+
+
+def articles(
+    ctx: typer.Context,
+    article: str = typer.Argument(..., help="The article number to pivot on."),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """Show every station holding article, grouped by Build Words.
+
+    More than one group means the fleet disagrees about what that article
+    is -- the divergence this pivot exists to surface.
+    """
+    client = get_client(ctx)
+    try:
+        result = client.get_article(article)
+    except FleetError as exc:
+        handle_fleet_error(exc)
+        return
+
+    if json_output:
+        print_json(result)
+        return
+
+    groups = result.get("groups", {})
+    if not groups:
+        typer.echo(f"No devices report article {article}.")
+        return
+
+    if result.get("divergent"):
+        typer.secho(
+            f"Divergent: {len(groups)} distinct Build Words values for {article}.",
+            fg=typer.colors.YELLOW,
+        )
+
+    out = console()
+    for build_words, devices in groups.items():
+        out.print(f"[bold]Build Words: {build_words or '(none)'}[/bold]")
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("UID", style="cyan", no_wrap=True)
+        table.add_column("Name")
+        table.add_column("Revision")
+        table.add_column("Manifest SHA-256")
+        for device in devices:
+            table.add_row(
+                device.get("uid", ""),
+                device.get("display_name", ""),
+                device.get("revision", ""),
+                device.get("manifest_sha256", ""),
+            )
+        out.print(table)
+
+
+__all__ = ["articles"]

lr_fleet/commands/device.py

@@ -0,0 +1,208 @@
+"""`fleet device …`: play a fleet device from a terminal.
+
+These commands are the device library (:mod:`lr_fleet.device`) with a face on
+it — for trying the enrolment workflow by hand, from a laptop, with a software
+key, a YubiKey or the machine's TPM. They sign as the device, so they need no
+sign-in; the fleet's base URL comes from the top-level ``--base-url``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import typer
+
+from ..exceptions import FleetError
+from ..device import DeviceClient, DeviceIdentity, DeviceResponse, SoftwareKey, os_composite
+from . import CliContext, print_json
+
+DEFAULT_DEVICE_DIR = Path("~/.config/lr-fleet/device").expanduser()
+
+app = typer.Typer(help="Act as a fleet device: create an identity, enrol, report.")
+
+_DirOption = typer.Option(
+    DEFAULT_DEVICE_DIR,
+    "--dir",
+    envvar="FLEET_DEVICE_DIR",
+    help="Where the device identity lives.",
+)
+
+
+def _fail(message: str) -> None:
+    typer.secho(message, fg=typer.colors.RED)
+    raise typer.Exit(code=1)
+
+
+def _load(directory: Path) -> DeviceIdentity:
+    try:
+        return DeviceIdentity.load(directory)
+    except FleetError as exc:
+        _fail(str(exc))
+        raise
+
+
+def _holder(key: str, serial: Optional[int], slot: str, tcti: Optional[str]):
+    if key == "software":
+        return SoftwareKey.generate()
+    if key == "yubikey":
+        from ..device.yubikey import YubiKeyPivKey, attached_serial
+
+        holder = YubiKeyPivKey(serial=serial or attached_serial(), slot=slot)
+        holder.public_key()  # refuses a slot with no key before anything is saved
+        return holder
+    if key == "tpm":
+        from ..device.tpm import Tpm2Key
+
+        return Tpm2Key.create(tcti=tcti)
+    _fail(f"--key must be software, yubikey or tpm, not {key!r}.")
+
+
+@app.command("init")
+def init(
+    directory: Path = _DirOption,
+    key: str = typer.Option(
+        "software", "--key", help="Where the key lives: software, yubikey or tpm."
+    ),
+    serial: Optional[int] = typer.Option(
+        None, "--serial", help="With --key yubikey: which YubiKey, when several are attached."
+    ),
+    slot: str = typer.Option(
+        "9e", "--slot", help="With --key yubikey: the slot `fleet provision --yubikey` used."
+    ),
+    tcti: Optional[str] = typer.Option(
+        None,
+        "--tcti",
+        envvar="FLEET_TPM_TCTI",
+        help="With --key tpm: the TPM to use, e.g. swtpm:host=127.0.0.1,port=2321.",
+    ),
+    replace: bool = typer.Option(False, "--replace", help="Overwrite an existing identity."),
+) -> None:
+    """Create this device's identity."""
+    try:
+        identity = DeviceIdentity.create(
+            directory, _holder(key, serial, slot, tcti), replace=replace
+        )
+    except FleetError as exc:
+        _fail(str(exc))
+    typer.secho(f"Created device {identity.station_uid}.", fg=typer.colors.GREEN)
+    typer.echo(f"Key: {identity.holder.kind or 'software'}")
+    typer.echo(f"Pairing code: {identity.pairing_code}")
+
+
+@app.command("show")
+def show(
+    directory: Path = _DirOption,
+    json_output: bool = typer.Option(False, "--json", help="Print JSON."),
+) -> None:
+    """Show this device's uid, key and pairing code."""
+    identity = _load(directory)
+    try:
+        summary = {
+            "station_uid": identity.station_uid,
+            "key": identity.holder.kind or "software",
+            "pairing_code": identity.pairing_code,
+            "thumbprint": identity.thumbprint,
+            "request_seq": identity.request_seq,
+            "enrolled": identity.enrolled,
+        }
+    except FleetError as exc:
+        _fail(str(exc))
+    if json_output:
+        print_json(summary)
+        return
+    for label, value in summary.items():
+        typer.echo(f"{label}: {value}")
+
+
+@app.command("attest")
+def attest(directory: Path = _DirOption) -> None:
+    """Print the key's attestation, for `fleet provision --statement`."""
+    identity = _load(directory)
+    if identity.holder.kind is None:
+        _fail("A software key has no attestation.")
+    try:
+        attestation = identity.holder.attestation()
+    except FleetError as exc:
+        _fail(str(exc))
+    print_json(attestation)
+
+
+def _composites(path: Optional[Path]) -> List[Dict[str, Any]]:
+    if path is None:
+        return [os_composite()]
+    try:
+        composites = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        _fail(f"Cannot read composites from {path}: {exc}")
+    if not isinstance(composites, list):
+        _fail(f"{path} must hold a JSON list of composites.")
+    return composites
+
+
+def _report(response: DeviceResponse, identity: DeviceIdentity, json_output: bool) -> None:
+    if json_output:
+        print_json({"status_code": response.status_code, **response.body})
+        return
+    colour = typer.colors.GREEN if response.status_code < 300 else typer.colors.YELLOW
+    typer.secho(f"{response.status_code} {response.status or 'ok'}", fg=colour)
+    if response.status in ("pending", "key_mismatch"):
+        typer.echo(f"Pairing code: {identity.pairing_code}")
+    if response.status_code >= 400:
+        raise typer.Exit(code=1)
+
+
+@app.command("enrol")
+def enrol(
+    ctx: typer.Context,
+    directory: Path = _DirOption,
+    product_id: str = typer.Option("504-1007", "--product-id", help="The product to enrol as."),
+    enrol_token: Optional[str] = typer.Option(
+        None, "--enrol-token", envvar="FLEET_ENROL_TOKEN", help="The product's enrol token."
+    ),
+    composites: Optional[Path] = typer.Option(
+        None, "--composites", help="A JSON list of composites; default: this machine's os."
+    ),
+    no_attest: bool = typer.Option(
+        False, "--no-attest", help="Enrol a hardware key without its attestation."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """Enrol, or confirm this device is enrolled. 202 means it waits for approval."""
+    cli_ctx: CliContext = ctx.obj
+    identity = _load(directory)
+    client = DeviceClient(identity, cli_ctx.base_url)
+    try:
+        response = client.enroll(
+            product_id,
+            _composites(composites),
+            enrol_token=enrol_token,
+            attest=not no_attest,
+        )
+    except FleetError as exc:
+        _fail(str(exc))
+    _report(response, identity, json_output)
+
+
+@app.command("report")
+def report(
+    ctx: typer.Context,
+    directory: Path = _DirOption,
+    composites: Optional[Path] = typer.Option(
+        None, "--composites", help="A JSON list of composites; default: this machine's os."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """Send one snapshot. The device must be enrolled."""
+    cli_ctx: CliContext = ctx.obj
+    identity = _load(directory)
+    client = DeviceClient(identity, cli_ctx.base_url)
+    try:
+        response = client.snapshot(_composites(composites))
+    except FleetError as exc:
+        _fail(str(exc))
+    _report(response, identity, json_output)
+
+
+__all__ = ["app", "DEFAULT_DEVICE_DIR"]