xmemcli 0.0.1__py3-none-any.whl

xmemcli/_login.py

@@ -0,0 +1,593 @@
+"""The browser handoff behind ``xmem auth login`` (PKCE + loopback callback).
+
+The CLI mints a PKCE ``verifier`` / ``challenge`` and opens ``/xmemcli/<challenge>``.
+It listens on ``127.0.0.1:9636`` while the human creates a key and clicks **Use this key
+in the CLI**. The Console POSTs the key to ``/cli/handoff``, receives a signed short-lived
+``code``, then redirects the browser to the local callback with ``code`` + ``state``.
+The CLI redeems with ``verifier`` + ``code`` over TLS; only it holds the verifier.
+
+This loopback callback is a conscious multi-node design choice: the API remains stateless
+for sign-in, because any node can mint/verify the signed code and no shared relay table,
+cache, sticky session, or cross-node pub/sub is required.
+Standard-library only, like the rest of the CLI.
+"""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import select
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import IO, Any, Callable, NamedTuple, cast, override
+from urllib.parse import parse_qs, quote, urlparse
+
+try:
+    import termios
+    import tty
+
+    _TERMIOS_AVAILABLE = True
+except ImportError:
+    termios = None  # type: ignore[assignment]
+    tty = None  # type: ignore[assignment]
+    _TERMIOS_AVAILABLE = False
+
+from ._envelope import batch_envelope_error
+from ._version import CLI_NAME
+
+# Must match ``xmem.ENV_CONSOLE_URL`` / ``xmem.ENV_API_URL``.
+# Duplicated here so ``_login`` stays importable without loading ``xmem``.
+_ENV_CONSOLE_URL = "XMEM_CONSOLE_URL"
+_ENV_API_URL = "XMEM_API_URL"
+DEFAULT_CONSOLE_URL = "https://console.xmemory.ai"
+
+CALLBACK_PORT = 9636
+CALLBACK_PATH = "/callback"
+CLI_LOGIN_PATH = "/xmemcli"
+CLI_TOKEN_PROXY_PATH = "/api/cli/token"
+CLI_WHOAMI_PROXY_PATH = "/api/cli/whoami"
+
+API_KEY_PREFIX = "xmem_"
+
+_DONE_PAGE = (
+    f"<!doctype html><html><head><meta charset='utf-8'><title>{CLI_NAME}</title></head>"
+    "<body style='font-family:system-ui;margin:3rem'>"
+    "<h2>You're all set.</h2><p>You can close this tab and return to your terminal.</p>"
+    "</body></html>"
+).encode("utf-8")
+
+
+class LoginError(Exception):
+    """A login flow failed (bind error, missing code, bad ``state``)."""
+
+
+class LoginTimeout(LoginError):
+    """The human did not complete the browser step before the deadline."""
+
+
+class LoginAborted(Exception):
+    """The user cancelled login (e.g. Ctrl+C)."""
+
+
+class HandoffResult(NamedTuple):
+    """Outcome of a successful PKCE login — carries the secret and validated account email."""
+
+    api_key: str
+    key_prefix: str
+    name: str
+    email: str
+
+
+def redirect_uri_for_port(port: int) -> str:
+    return f"http://127.0.0.1:{port}{CALLBACK_PATH}"
+
+
+def redirect_uri() -> str:
+    return redirect_uri_for_port(CALLBACK_PORT)
+
+
+def new_verifier() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def challenge_for(verifier: str) -> str:
+    digest = hashlib.sha256(verifier.encode("utf-8")).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def _console_url_from_api_url(api_url: str) -> str | None:
+    """Local dev convention: API on :8000, Console on :8002 (same host)."""
+    parsed = urlparse(api_url.rstrip("/"))
+    if parsed.hostname not in ("localhost", "127.0.0.1"):
+        return None
+    if parsed.port == 8000:
+        return f"{parsed.scheme}://{parsed.hostname}:8002"
+    return None
+
+
+def console_url_for_api(*, console_url: str | None = None) -> str:
+    """Resolve the Console origin for PKCE login and token/whoami proxies."""
+    if console_url:
+        return console_url.rstrip("/")
+    from_env = os.environ.get(_ENV_CONSOLE_URL, "").strip()
+    if from_env:
+        return from_env.rstrip("/")
+    api_from_env = os.environ.get(_ENV_API_URL, "").strip()
+    if api_from_env:
+        inferred = _console_url_from_api_url(api_from_env)
+        if inferred:
+            return inferred
+    return DEFAULT_CONSOLE_URL
+
+
+def build_login_page_url(console_url: str, *, challenge: str, callback_url: str | None = None) -> str:
+    """Console CLI login URL: ``/xmemcli/<challenge>`` (PKCE S256, also the callback state)."""
+    segment = quote(challenge, safe="-_")
+    url = f"{console_url.rstrip('/')}{CLI_LOGIN_PATH}/{segment}"
+    if callback_url and callback_url != redirect_uri_for_port(CALLBACK_PORT):
+        url += "?callback_url=" + quote(callback_url, safe=":/?&=-_.")
+    return url
+
+
+def _login_prompt_line(label: str, body: str) -> str:
+    return f"  {label:<10}{body}"
+
+
+def write_login_handoff_prompt(
+    login_url: str,
+    *,
+    offer_paste: bool,
+    stream: IO[str] | None = None,
+) -> None:
+    """Human-facing instructions while ``auth login`` waits for a credential."""
+    out = stream or sys.stderr
+    body_indent = "            "
+    lines = [
+        "",
+        f"Authorize {CLI_NAME} on this machine.",
+        "",
+        _login_prompt_line("Browser", "Open this URL and click \"Use this key in the CLI\":"),
+        f"{body_indent}{login_url}",
+    ]
+    if offer_paste:
+        lines.extend(
+            [
+                "",
+                _login_prompt_line(
+                    "Paste",
+                    "Paste your API key below (input hidden), then press Enter.",
+                ),
+            ]
+        )
+    lines.extend(
+        [
+            "",
+            _login_prompt_line("Manual", "Set $XMEM_API_KEY or `.xmemrc.json`"),
+            f"{body_indent}See AUTH-FLOW.md.",
+            "",
+        ]
+    )
+    out.write("\n".join(lines))
+    out.flush()
+
+
+def token_redeem_urls(*, api_url: str, console_url: str | None) -> list[str]:
+    """Candidate ``POST /cli/token`` URLs, most likely first."""
+    console = console_url_for_api(console_url=console_url)
+    if console_url or os.environ.get(_ENV_CONSOLE_URL, "").strip():
+        return [f"{console.rstrip('/')}{CLI_TOKEN_PROXY_PATH}"]
+    base = api_url.rstrip("/")
+    return [f"{base}/cli/token", f"{base}/api/cli/token"]
+
+
+def whoami_urls(*, api_url: str, console_url: str | None) -> list[str]:
+    """Candidate ``GET /whoami`` URLs for bearer API-key lookup, most likely first."""
+    console = console_url_for_api(console_url=console_url)
+    if console_url or os.environ.get(_ENV_CONSOLE_URL, "").strip():
+        return [f"{console.rstrip('/')}{CLI_WHOAMI_PROXY_PATH}"]
+    base = api_url.rstrip("/")
+    return [f"{base}/whoami", f"{base}/api/whoami"]
+
+
+class _LoopbackServer(HTTPServer):
+    captured: dict[str, str] | None = None
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path != CALLBACK_PATH:
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = {k: v[0] for k, v in parse_qs(parsed.query).items() if v}
+        cast(_LoopbackServer, self.server).captured = params
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(_DONE_PAGE)
+
+    @override
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+        return
+
+
+def wait_for_callback(
+    state: str,
+    build_url: Callable[[str], str],
+    on_url: Callable[[str], None],
+    timeout_s: float,
+    *,
+    callback_port: int = CALLBACK_PORT,
+    stop: threading.Event | None = None,
+) -> dict[str, str]:
+    """Listen for the browser's local callback carrying the signed code.
+
+    This is intentionally the production transport. It keeps CLI sign-in friendly to multi-node API deployments:
+    the server only mints/verifies stateless JWT codes, while the browser delivers the code directly to the waiting CLI.
+    """
+    try:
+        server = _LoopbackServer(("127.0.0.1", callback_port), _CallbackHandler)
+    except OSError as e:
+        label = callback_port if callback_port != 0 else CALLBACK_PORT
+        raise LoginError(
+            f"could not bind 127.0.0.1:{label} — is another `{CLI_NAME} auth login` in progress? ({e})"
+        ) from None
+    bound_port = server.server_address[1]
+    server.timeout = 0.5
+    try:
+        on_url(build_url(redirect_uri_for_port(bound_port)))
+        deadline = time.monotonic() + timeout_s
+        while server.captured is None and not (stop and stop.is_set()):
+            if time.monotonic() >= deadline:
+                raise LoginTimeout(
+                    f"timed out after {timeout_s:g}s waiting for the browser callback on port {bound_port}"
+                )
+            server.handle_request()
+    finally:
+        server.server_close()
+    params = server.captured
+    if params is None:  # pragma: no cover
+        raise LoginError("callback listener stopped")
+    if params.get("state") != state:
+        raise LoginError("callback `state` did not match — rejecting (possible CSRF / stale tab)")
+    return params
+
+
+def _response_looks_like_html(raw: str) -> bool:
+    head = raw.lstrip()[:256].lower()
+    return head.startswith("<!doctype") or head.startswith("<html")
+
+
+def _parse_token_envelope(raw: str, *, url: str) -> HandoffResult:
+    if _response_looks_like_html(raw):
+        raise LoginError(f"token redeem got a web page instead of JSON from {url}")
+    try:
+        envelope = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise LoginError(f"token redeem returned non-JSON from {url}: {raw[:200]}") from e
+    err = batch_envelope_error(envelope)
+    if err:
+        raise LoginError(f"token redeem failed: {err}")
+    items = envelope.get("items") if isinstance(envelope, dict) else None
+    if not isinstance(items, list) or not items or not isinstance(items[0], dict):
+        raise LoginError("token redeem response missing items[0]")
+    item = items[0]
+    key = item.get("key")
+    if not isinstance(key, str) or not key:
+        raise LoginError("token redeem response missing key")
+    key_prefix_raw = item.get("key_prefix")
+    key_prefix = key_prefix_raw if isinstance(key_prefix_raw, str) and key_prefix_raw else key[:8]
+    name_raw = item.get("name")
+    name = name_raw if isinstance(name_raw, str) and name_raw else "cli"
+    email_raw = item.get("email")
+    if not isinstance(email_raw, str) or not email_raw.strip() or "@" not in email_raw:
+        raise LoginError("token redeem response missing validated email")
+    email = email_raw.strip().lower()
+    return HandoffResult(api_key=key, key_prefix=key_prefix, name=name, email=email)
+
+
+def redeem_token(
+    api_url: str,
+    *,
+    code: str,
+    verifier: str,
+    console_url: str | None = None,
+    timeout_s: float = 30.0,
+) -> HandoffResult:
+    """Exchange ``verifier`` + signed ``code`` for the issued key."""
+    payload: dict[str, str] = {"verifier": verifier}
+    if not code:
+        raise LoginError("internal error: redeem requires code")
+    payload["code"] = code
+    body = json.dumps(payload).encode("utf-8")
+    headers = {"Content-Type": "application/json", "Accept": "application/json"}
+    errors: list[str] = []
+    for url in token_redeem_urls(api_url=api_url, console_url=console_url):
+        req = urllib.request.Request(url, data=body, method="POST", headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            if e.code == 401:
+                raise LoginError(
+                    f"The login code expired or is invalid — run `{CLI_NAME} auth login` again."
+                ) from None
+            detail = e.read().decode("utf-8", errors="replace")[:200]
+            errors.append(f"{url}: HTTP {e.code} ({detail})")
+            continue
+        except urllib.error.URLError as e:
+            errors.append(f"{url}: network error ({e.reason})")
+            continue
+        try:
+            return _parse_token_envelope(raw, url=url)
+        except LoginError as e:
+            errors.append(str(e))
+            continue
+    hint = (
+        "Could not reach the accounts API token endpoint. "
+        "Set $XMEM_CONSOLE_URL to your Console (e.g. dk-web…) and ensure it can reach the API "
+        "(ACCOUNTS_API_URL on the Console server)."
+    )
+    detail = "; ".join(errors[-3:]) if errors else "no endpoints tried"
+    raise LoginError(f"token redeem failed: {detail}. {hint}")
+
+
+def stdin_is_interactive() -> bool:
+    """True when stdin is a TTY (interactive paste is meaningful)."""
+    try:
+        return sys.stdin.isatty()
+    except (AttributeError, ValueError, OSError):
+        return False
+
+
+def paste_from_stdin_supported() -> bool:
+    """True when hidden stdin paste can be offered (Unix TTY with termios)."""
+    return stdin_is_interactive() and _TERMIOS_AVAILABLE
+
+
+def _read_pasted_api_key_no_echo(*, stop: threading.Event) -> str | None:
+    """Read one line from stdin without echo. Returns None if *stop* is set first."""
+    if not _TERMIOS_AVAILABLE or termios is None or tty is None:
+        return None
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    chars: list[str] = []
+    try:
+        tty.setraw(fd)
+        while not stop.is_set():
+            ready, _, _ = select.select([sys.stdin], [], [], 0.15)
+            if not ready:
+                continue
+            ch = sys.stdin.read(1)
+            if ch in ("\n", "\r"):
+                return "".join(chars).strip()
+            if ch == "\x03":
+                raise LoginAborted()
+            if ch in ("\x7f", "\b"):
+                if chars:
+                    chars.pop()
+                continue
+            if ch == "\x04":
+                return "".join(chars).strip()
+            chars.append(ch)
+        return None
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+        # DELIBERATELY print: newline after raw-mode paste must not touch stdout (machine JSON).
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+
+
+def fetch_whoami_email(
+    api_url: str,
+    api_key: str,
+    *,
+    console_url: str | None = None,
+    timeout_s: float = 10.0,
+) -> str:
+    """Resolve an ``xmem_`` API key to its owner email via ``GET /whoami``."""
+    headers = {"Accept": "application/json", "Authorization": f"Bearer {api_key}"}
+    errors: list[str] = []
+    for url in whoami_urls(api_url=api_url, console_url=console_url):
+        req = urllib.request.Request(url, method="GET", headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", errors="replace")[:200]
+            errors.append(f"{url}: HTTP {e.code} ({detail})")
+            continue
+        except urllib.error.URLError as e:
+            raise LoginError(f"whoami network error at {url}: {e.reason}") from None
+        try:
+            body = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise LoginError(f"whoami returned non-JSON from {url}") from e
+        auth = body.get("AuthApiKey") if isinstance(body, dict) else None
+        if isinstance(auth, dict):
+            email_raw = auth.get("email")
+            if isinstance(email_raw, str) and email_raw.strip() and "@" in email_raw:
+                return email_raw.strip().lower()
+        errors.append(f"{url}: key did not resolve to an active account")
+    detail = "; ".join(errors[-2:]) if errors else "no whoami endpoints tried"
+    raise LoginError(f"pasted key is not valid or not active ({detail})")
+
+
+def handoff_from_pasted_key(
+    api_url: str,
+    api_key: str,
+    *,
+    console_url: str | None = None,
+    timeout_s: float = 10.0,
+) -> HandoffResult:
+    """Build a handoff result from a human-pasted plaintext key."""
+    key = api_key.strip()
+    if not key.startswith(API_KEY_PREFIX):
+        raise LoginError(f"pasted key must start with {API_KEY_PREFIX}")
+    if len(key) < len(API_KEY_PREFIX) + 8:
+        raise LoginError("pasted key looks too short")
+    email = fetch_whoami_email(api_url, key, console_url=console_url, timeout_s=timeout_s)
+    return HandoffResult(api_key=key, key_prefix=key[:8], name="pasted", email=email)
+
+
+def wait_for_handoff(
+    api_url: str,
+    *,
+    console_url: str | None,
+    challenge: str,
+    verifier: str,
+    build_url: Callable[[str], str],
+    on_url: Callable[[str], None],
+    timeout_s: float,
+    callback_port: int = CALLBACK_PORT,
+    interactive: bool = False,
+    notify: Callable[[str], None] | None = None,
+) -> HandoffResult:
+    """Wait for a key via loopback callback and, when interactive, hidden stdin paste in parallel."""
+    notify = notify or (lambda _msg: None)
+    stop = threading.Event()
+    abort_requested = threading.Event()
+    result_box: list[HandoffResult] = []
+    errors: list[Exception] = []
+    offer_paste = interactive and paste_from_stdin_supported()
+    prompt_ready = threading.Event()
+
+    def request_abort() -> None:
+        abort_requested.set()
+        stop.set()
+
+    def callback_worker() -> None:
+        def opened(url: str) -> None:
+            on_url(url)
+            prompt_ready.set()
+
+        try:
+            params = wait_for_callback(
+                challenge,
+                build_url,
+                opened,
+                timeout_s,
+                callback_port=callback_port,
+                stop=stop,
+            )
+            code = params.get("code")
+            if not code:
+                raise LoginError("callback missing code")
+            result = redeem_token(
+                api_url,
+                code=code,
+                console_url=console_url,
+                verifier=verifier,
+                timeout_s=min(10.0, timeout_s),
+            )
+            if not result_box:
+                result_box.append(result)
+                notify("Key received from the browser callback; paste prompt closed.")
+                stop.set()
+        except LoginTimeout as e:
+            if not stop.is_set():
+                errors.append(e)
+        except LoginError as e:
+            if not stop.is_set():
+                errors.append(e)
+                stop.set()
+
+    def paste_worker() -> None:
+        while not stop.is_set() and not prompt_ready.wait(timeout=0.1):
+            pass
+        if stop.is_set():
+            return
+        try:
+            while not stop.is_set():
+                try:
+                    pasted = _read_pasted_api_key_no_echo(stop=stop)
+                except LoginAborted:
+                    errors.append(LoginAborted())
+                    request_abort()
+                    return
+                if stop.is_set():
+                    return
+                if not pasted:
+                    continue
+                try:
+                    result = handoff_from_pasted_key(
+                        api_url, pasted, console_url=console_url, timeout_s=min(10.0, timeout_s)
+                    )
+                except LoginError as e:
+                    notify(f"Could not use pasted key: {e}")
+                    continue
+                if not result_box:
+                    result_box.append(result)
+                    notify("Using pasted key; stopped waiting for browser callback.")
+                    stop.set()
+                return
+        except LoginAborted:
+            errors.append(LoginAborted())
+            request_abort()
+
+    threads = [threading.Thread(target=callback_worker, daemon=True)]
+    if offer_paste:
+        threads.append(threading.Thread(target=paste_worker, daemon=True))
+    for thread in threads:
+        thread.start()
+
+    deadline = time.monotonic() + timeout_s
+    try:
+        while time.monotonic() < deadline and not result_box:
+            if abort_requested.is_set():
+                raise LoginAborted()
+            if stop.is_set() and errors:
+                break
+            time.sleep(0.05)
+    except KeyboardInterrupt:
+        request_abort()
+        raise LoginAborted() from None
+    finally:
+        stop.set()
+        for thread in threads:
+            thread.join(timeout=1.0)
+
+    if result_box:
+        return result_box[0]
+    if any(isinstance(e, LoginAborted) for e in errors):
+        raise LoginAborted()
+    if errors:
+        raise errors[0]
+    raise LoginTimeout(
+        f"timed out after {timeout_s:g}s waiting for a key from the browser callback or stdin"
+    )
+
+
+def run_pkce_login(
+    api_url: str,
+    *,
+    console_url: str | None,
+    verifier: str,
+    on_url: Callable[[str], None],
+    timeout_s: float,
+    callback_port: int = CALLBACK_PORT,
+    interactive: bool = False,
+    notify: Callable[[str], None] | None = None,
+) -> HandoffResult:
+    """Open the Console login page and wait for loopback callback and/or hidden stdin paste."""
+    console = console_url_for_api(console_url=console_url)
+    challenge = challenge_for(verifier)
+    return wait_for_handoff(
+        api_url,
+        console_url=console_url,
+        challenge=challenge,
+        verifier=verifier,
+        build_url=lambda redirect_uri: build_login_page_url(console, challenge=challenge, callback_url=redirect_uri),
+        on_url=on_url,
+        timeout_s=timeout_s,
+        callback_port=callback_port,
+        interactive=interactive,
+        notify=notify,
+    )

xmemcli/_org_cluster.py

@@ -0,0 +1,70 @@
+"""Org-scoped inventory commands for ``xmemcli``."""
+
+import argparse
+from typing import Any
+
+from ._envelope import batch_envelope_error
+from ._output import CliOutput, OutputKind, make_error
+from ._xmem_bridge import curate_instance, http_to_exit, xmem_module
+
+_CLUSTER_FIELDS = ("id", "name", "description")
+
+
+def _curate_cluster(item: dict[str, Any], verbose: bool) -> dict[str, Any]:
+    m = xmem_module()
+    curated = {k: item[k] for k in _CLUSTER_FIELDS if k in item}
+    return m._add_verbose_extras(curated, item, verbose)
+
+
+def cmd_org_list_clusters(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``org list clusters`` — clusters visible to this credential."""
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    try:
+        envelope = m._get(f"{base}/clusters?verbose=true", api_key)
+    except m.ApiError as e:
+        return (make_error(f"/clusters failed: {e}", status=e.status), http_to_exit(e.status))
+    err = batch_envelope_error(envelope)
+    if err:
+        return (make_error(f"/clusters failed: {err}", stage="request"), m.EXIT_HTTP_ERROR)
+    items = [i for i in (envelope.get("items") or []) if isinstance(i, dict)]
+    curated = [_curate_cluster(i, args.verbose) for i in items]
+    return (CliOutput(OutputKind.CLUSTER_LIST, curated), m.EXIT_OK)
+
+
+def cmd_org_list_instances(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``org list instances`` — instances visible to this credential (``GET /instances``)."""
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    cluster_filter = getattr(args, "cluster", None)
+    try:
+        envelope = m._get(f"{base}/instances?verbose=true", api_key)
+    except m.ApiError as e:
+        return (make_error(f"/instances failed: {e}", status=e.status), http_to_exit(e.status))
+    err = batch_envelope_error(envelope)
+    if err:
+        return (make_error(f"/instances failed: {err}", stage="request"), m.EXIT_HTTP_ERROR)
+    items = [i for i in (envelope.get("items") or []) if isinstance(i, dict)]
+    if cluster_filter:
+        items = [i for i in items if i.get("cluster_id") == cluster_filter]
+    curated = [curate_instance(i, args.verbose) for i in items]
+    return (CliOutput(OutputKind.INSTANCE_LIST, curated), m.EXIT_OK)
+
+
+def cmd_org_list_keys(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``org list keys`` — API keys visible to this credential."""
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    try:
+        envelope = m._get(f"{base}/api-keys?verbose=true", api_key)
+    except m.ApiError as e:
+        return (make_error(f"/api-keys failed: {e}", status=e.status), http_to_exit(e.status))
+    err = batch_envelope_error(envelope)
+    if err:
+        return (make_error(f"/api-keys failed: {err}", stage="request"), m.EXIT_HTTP_ERROR)
+    keys = envelope.get("items") or []
+    curated = [m._curate_key(k, args.verbose) for k in keys if isinstance(k, dict)]
+    return (CliOutput(OutputKind.KEY_LIST, curated), m.EXIT_OK)