lighthouse-cli 0.16.0__py3-none-any.whl

lighthouse/device.py

@@ -0,0 +1,124 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Signing in through the browser with a device code, as `stripe login` does.
+
+    $ lighthouse login --host t7m2kqx9vbn.atlanticagenticlabs.com
+
+    Your pairing code is: WXKM-7T4P
+    Press Enter to open the browser, or visit
+    https://t7m2kqx9vbn.atlanticagenticlabs.com/device
+    Waiting for approval…
+    Signed in as ops@example.test (viewer). Scopes: telemetry:read agents:read
+
+The person approves in their own portal, behind their own identity provider and
+their own second factor. Nothing is typed into this terminal: no password, no
+token, no copy and paste. The CLI then holds a short-lived delegated token in
+the OS keychain (credentials.py).
+
+**The code is shown before the browser opens**, and the browser is opened only
+on a keypress unless `--yes` is given. A command that silently launches a
+browser is a command nobody can run over SSH, and a code the person has already
+seen is a code they can compare with the one on the page — which is the whole
+protection against being walked through approving somebody else's sign-in.
+
+`--no-browser` prints the URL and nothing else, for a remote shell.
+
+Polling obeys the interval the service asks for, and backs off further when it
+answers `slow_down` (RFC 8628 §3.5). It stops at `expires_in` with a message
+that says to run the command again, rather than looping.
+"""
+from __future__ import annotations
+
+import time
+import webbrowser
+from dataclasses import dataclass
+from typing import Any
+
+from lighthouse.exits import NEEDS_A_PERSON, CliError
+from lighthouse.http import Client, Refused
+from lighthouse.i18n import t
+from lighthouse.out import Out
+
+DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+PENDING = ("authorization_pending", "slow_down")
+
+
+@dataclass
+class Started:
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    device_code: str
+    interval: int
+    expires_in: int
+    scope: str
+
+    @classmethod
+    def of(cls, body: dict[str, Any]) -> Started:
+        return cls(str(body["user_code"]), str(body["verification_uri"]),
+                   str(body.get("verification_uri_complete") or body["verification_uri"]),
+                   str(body["device_code"]), int(body.get("interval") or 5),
+                   int(body.get("expires_in") or 600), str(body.get("scope") or ""))
+
+
+def start(client: Client, *, scope: str | None, client_name: str) -> Started:
+    body = client.post("/api/v1/oauth/device/code",
+                       {"scope": scope, "client_name": client_name})
+    return Started.of(body)
+
+
+def open_browser(url: str, *, opener: Any = None) -> bool:
+    """True if a browser was opened. Never raises: a machine with no browser is
+    a normal thing, and the URL has already been printed."""
+    try:
+        return bool((opener or webbrowser.open)(url))
+    except Exception:                               # pragma: no cover - platform dependent
+        return False
+
+
+def poll(client: Client, started: Started, *, out: Out, sleep: Any = None,
+         now: Any = None) -> dict[str, Any]:
+    """Wait for the person, then return the token the service issued."""
+    rest = sleep or time.sleep
+    clock = now or time.monotonic
+    deadline = clock() + started.expires_in
+    interval = float(started.interval)
+    while True:
+        if clock() >= deadline:
+            raise CliError(t("err.pairing_expired"), error="expired", hint=t("hint.login_again"))
+        rest(interval)
+        try:
+            return dict(client.post("/api/v1/oauth/token", {
+                "grant_type": DEVICE_GRANT, "device_code": started.device_code}))
+        except Refused as e:
+            if e.error == "slow_down":
+                interval += 5
+                continue
+            if e.error == "authorization_pending":
+                continue
+            if e.error == "access_denied":
+                raise CliError(t("err.sign_in_declined"), error="declined") from None
+            raise
+
+
+def sign_in(client: Client, *, out: Out, scope: str | None, client_name: str,
+            no_browser: bool = False, assume_yes: bool = False, no_input: bool = False,
+            opener: Any = None, sleep: Any = None, reader: Any = None) -> dict[str, Any]:
+    """The whole flow. Returns the token document; the caller stores it."""
+    started = start(client, scope=scope, client_name=client_name)
+    out.say(t("login.pairing_code", code=out.paint(started.user_code, "bold")))
+    out.say(t("login.approve_at", url=started.verification_uri))
+    if started.scope:
+        out.note(t("login.asking_for", scope=started.scope))
+    if not no_browser:
+        if assume_yes or no_input:
+            open_browser(started.verification_uri_complete, opener=opener)
+        else:
+            try:
+                (reader or input)(t("prompt.open_browser") + " ")
+            except EOFError:
+                raise CliError(t("err.no_terminal"), code=NEEDS_A_PERSON,
+                               error="needs_a_person", hint=t("hint.no_terminal")) from None
+            open_browser(started.verification_uri_complete, opener=opener)
+    out.note(t("note.waiting_for_approval"))
+    return poll(client, started, out=out, sleep=sleep)

lighthouse/exits.py

@@ -0,0 +1,78 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Exit codes, and the one error type that carries them.
+
+A script in someone's CI has to be able to tell the four cases apart without
+reading English, so the codes are few, fixed and documented:
+
+| Code | Meaning | What a pipeline should do |
+|---|---|---|
+| 0 | it worked | carry on |
+| 1 | the command failed | stop; the message says why |
+| 2 | the command line was wrong | stop; a human must fix the invocation |
+| 3 | not signed in, or the credential has expired | run `lighthouse login` |
+| 4 | signed in, but the role or scope does not reach this | ask an administrator |
+| 5 | the service refused for now: rate limit, or a retryable 5xx | retry later |
+| 7 | the command needed a person and none is there (`--no-input`, or no tty) | stop |
+
+Nothing exits on a signal with a code of its own: SIGINT leaves 130 as the
+shell expects.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from lighthouse.i18n import t
+
+OK = 0
+FAILED = 1
+USAGE = 2
+UNAUTHENTICATED = 3
+FORBIDDEN = 4
+RETRY = 5
+NEEDS_A_PERSON = 7
+
+CODES = {
+    OK: "ok",
+    FAILED: "failed",
+    USAGE: "usage",
+    UNAUTHENTICATED: "unauthenticated",
+    FORBIDDEN: "forbidden",
+    RETRY: "retry",
+    NEEDS_A_PERSON: "needs_a_person",
+}
+
+
+class CliError(Exception):
+    """A failure to report and exit with. `error` is a stable short code, so
+    `--json` output can be matched on and the English can be improved without
+    breaking anyone's script."""
+
+    def __init__(self, message: str, *, code: int = FAILED, error: str = "failed",
+                 hint: str | None = None, **extra: Any) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.error = error
+        self.hint = hint
+        self.extra = extra
+
+    def body(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"ok": False, "error": self.error, "message": self.message}
+        if self.hint:
+            out["hint"] = self.hint
+        out.update(self.extra)
+        return out
+
+
+class NotSignedIn(CliError):
+    def __init__(self, host: str | None = None) -> None:
+        message = t("err.not_signed_in_for", host=host) if host else t("err.not_signed_in")
+        super().__init__(message, code=UNAUTHENTICATED, error="unauthenticated",
+                         hint=t("hint.login"))
+
+
+class NeedsAPerson(CliError):
+    def __init__(self, what: str) -> None:
+        super().__init__(t("err.needs_a_person", what=what), code=NEEDS_A_PERSON,
+                         error="needs_a_person", hint=t("hint.needs_a_person"))

lighthouse/flags.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""The global options, declared once and attached everywhere.
+
+`--host`, `--json`, `--quiet`, `--no-input`, `--yes` and `--timeout` must work
+at every depth: `lighthouse --json runs tail`, `lighthouse runs --json tail` and
+`lighthouse runs tail --json` all mean the same thing, because people type all
+three and a tool that accepts only one of them is a tool people swear at.
+
+That is done by declaring them on the root parser with real defaults, and on a
+shared parent — `inherited()` — with `default=SUPPRESS` for every subparser at
+every level. Without `SUPPRESS`, parsing a subcommand would write the flag's
+default over whatever an outer parser had already read, which is the single
+commonest bug in nested `argparse` command lines.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+HELP = {
+    "host": "the tenant's hostname or id",
+    "json": "one JSON document on standard output, nothing else",
+    "quiet": "no prose",
+    "no_input": "never ask a person anything; exit 7 instead",
+    "yes": "answer yes to every confirmation",
+    "timeout": "seconds for one request",
+    "lang": "the language to speak: en, fr, de, es, it, pt, nl, ga, ja, zh-Hans, zh-Hant or ar (default: your setting, then LANG)",
+}
+
+
+def add(target: argparse.ArgumentParser, *, suppress: bool) -> None:
+    """Attach the global options. `suppress` for anything but the root."""
+    def opts(default: Any) -> dict[str, Any]:
+        return {"default": argparse.SUPPRESS} if suppress else {"default": default}
+
+    hide = argparse.SUPPRESS
+    target.add_argument("--host", help=hide if suppress else HELP["host"], **opts(None))
+    target.add_argument("--json", action="store_true", dest="as_json",
+                        help=hide if suppress else HELP["json"], **opts(False))
+    target.add_argument("--quiet", action="store_true",
+                        help=hide if suppress else HELP["quiet"], **opts(False))
+    target.add_argument("--no-input", action="store_true", dest="no_input",
+                        help=hide if suppress else HELP["no_input"], **opts(False))
+    target.add_argument("--yes", action="store_true",
+                        help=hide if suppress else HELP["yes"], **opts(False))
+    target.add_argument("--timeout", type=float,
+                        help=hide if suppress else HELP["timeout"], **opts(None))
+    target.add_argument("--lang", metavar="TAG",
+                        help=hide if suppress else HELP["lang"], **opts(None))
+
+
+def inherited() -> argparse.ArgumentParser:
+    """A parent parser carrying the global options, for `parents=[...]`.
+
+    A fresh one each time: `argparse` refuses to share a parent between two
+    parsers that both add the same option, and a sub-subcommand needs its own.
+    """
+    parent = argparse.ArgumentParser(add_help=False)
+    add(parent, suppress=True)
+    return parent

lighthouse/http.py

@@ -0,0 +1,355 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Talking to the control plane: retries, pagination, idempotency, refusals.
+
+One class, `Client`, used by every command. It holds four behaviours that would
+otherwise be written slightly differently in each of them:
+
+**Retries.** A 429 or a 5xx is retried with exponential back-off and full
+jitter, honouring `Retry-After` when the service sends one. A 4xx that is not
+429 is never retried: the request was wrong and sending it again will not make
+it right. Nor is a write retried without an idempotency key, because a POST
+that timed out may well have been applied.
+
+**Idempotency.** Every write carries `Idempotency-Key`, a fresh UUID per
+logical operation (not per attempt), so a retried deploy is the same deploy and
+not a second one.
+
+**Pagination.** The read API answers `{<rows>: [...], "next": "<cursor>"}` and
+takes that cursor back as `?cursor=`. `each()` follows it and yields rows, and
+`get_all()` does the same but returns one document with every row in it, so no
+command has a `while True` of its own.
+
+**Cloudflare Access.** Every tenant host is behind Cloudflare Access except the
+OAuth endpoints. When a credential carries the tenant's Access service token,
+`CF-Access-Client-Id` and `CF-Access-Client-Secret` go on every request (it is
+harmless on the bypassed paths). If Access answers instead of the service, with
+a redirect to `*.cloudflareaccess.com` or a login page, the CLI says the service
+token is missing or wrong and names the two variables.
+
+**Refusals.** The control plane answers `{error, message}` with a fixed code
+(`docs/CONTRACT.md`). Those codes are mapped onto the CLI's exit codes
+(exits.py) once, here: `role_required` becomes 4, an expired credential becomes
+3 after one attempt to refresh it, a rate limit becomes 5.
+
+**Refresh.** A delegated token is short-lived (eight hours). The client
+refreshes it before it lapses and once on a 401, then stores the new one in the
+keychain. A credential that came from `LIGHTHOUSE_TOKEN` is never refreshed: in
+a pipeline there is nowhere to put the new one, and silently holding one in
+memory would hide that the variable needs rotating. A machine key (`aalcp-`)
+does not expire by time, so it is the credential for a pipeline.
+"""
+from __future__ import annotations
+
+import logging
+import random
+import time
+import uuid
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from lighthouse import __version__
+from lighthouse.credentials import ENV_ACCESS_ID, ENV_ACCESS_SECRET, ENV_TOKEN, Credential, Store
+from lighthouse.exits import FORBIDDEN, RETRY, UNAUTHENTICATED, CliError, NotSignedIn
+from lighthouse.i18n import t
+
+log = logging.getLogger(__name__)
+
+TIMEOUT = httpx.Timeout(connect=10.0, read=60.0, write=60.0, pool=10.0)
+# Pages walked at most, so a service that never stops sending a cursor cannot
+# keep a pipeline busy for ever.
+MAX_PAGES = 500
+ATTEMPTS = 4
+BACKOFF = 0.5
+MAX_BACKOFF = 8.0
+WRITES = ("POST", "PUT", "PATCH", "DELETE")
+
+# A refusal code (docs/CONTRACT.md) -> the exit code it becomes. Anything not
+# here is an ordinary failure, exit 1.
+EXIT_FOR = {
+    "unauthenticated": UNAUTHENTICATED,
+    "invalid_token": UNAUTHENTICATED,
+    "mfa_required": UNAUTHENTICATED,
+    "role_required": FORBIDDEN,
+    "not_authorised": FORBIDDEN,
+    "scope_required": FORBIDDEN,
+    "rate_limited": RETRY,
+    "tier_b_unavailable": RETRY,
+    "tenant_key_missing": RETRY,
+    "records_deferred": RETRY,
+    "identity_unavailable": RETRY,
+}
+
+
+class Refused(CliError):
+    """The service refused. Carries the service's own code, so a script can
+    match on `error` and a person reads `message`."""
+
+    def __init__(self, status: int, body: dict[str, Any]) -> None:
+        code = str(body.get("error") or f"http_{status}")
+        hint = None
+        needed = body.get("required_scope")
+        if code == "scope_required" and isinstance(needed, str) and needed:
+            # The token was approved without the scope this command needs:
+            # say which, and how to get it, rather than leave a bare 403.
+            hint = t("hint.scope_required", scope=needed)
+        super().__init__(str(body.get("message") or t("err.service_answered", status=status)),
+                         code=EXIT_FOR.get(code, 1), error=code, hint=hint, status=status)
+
+
+def access_wall(reply: httpx.Response) -> bool:
+    """Whether Cloudflare Access, not the service, answered.
+
+    Access sends an unauthenticated API call to its login: a 302/303 to
+    `<team>.cloudflareaccess.com`, or a login page as HTML. The service answers
+    JSON, always, so an HTML 200, 401 or 403 is Access (or something that is not
+    LightHouse), never the control plane. A 5xx page from a proxy is left
+    alone: that is an outage, not a missing token.
+    """
+    if reply.status_code in (301, 302, 303, 307, 308):
+        return "cloudflareaccess.com" in reply.headers.get("Location", "").lower()
+    kind = reply.headers.get("Content-Type", "").lower()
+    if "json" in kind:
+        return False
+    if "html" in kind and reply.status_code in (200, 401, 403):
+        return True
+    head = reply.content[:2000].lower()
+    return b"cloudflareaccess.com" in head or b"cloudflare access" in head
+
+
+class TokenRefused(NotSignedIn):
+    """A 401 on a credential from `LIGHTHOUSE_TOKEN`, said in its own terms."""
+
+    def __init__(self, message: str, hint: str) -> None:
+        CliError.__init__(self, message, code=UNAUTHENTICATED, error="unauthenticated",
+                          hint=hint)
+
+
+class AccessRefused(CliError):
+    def __init__(self, host: str, *, configured: bool) -> None:
+        state = t("err.access_state_wrong") if configured else t("err.access_state_missing")
+        super().__init__(
+            t("err.access_stopped", state=state),
+            code=UNAUTHENTICATED, error="access_service_token", host=host,
+            hint=t("hint.access_stopped", id=ENV_ACCESS_ID, secret=ENV_ACCESS_SECRET))
+
+
+def sleep_for(attempt: int, retry_after: str | None) -> float:
+    """How long before the next attempt. `Retry-After` wins where the service
+    sent one; otherwise exponential with full jitter, so a fleet of runners
+    does not retry in step."""
+    if retry_after:
+        try:
+            return max(0.0, min(float(retry_after), 60.0))
+        except ValueError:
+            pass
+    # Full jitter, so a fleet of runners does not retry in step. Not a
+    # cryptographic choice: nothing here is a secret or a credential.
+    return random.uniform(0, min(MAX_BACKOFF, BACKOFF * (2 ** attempt)))  # noqa: S311  # nosec B311
+
+
+def retry_hint(status: int, headers: Any) -> str | None:
+    """The service's own word on when to send again: `Retry-After`, or on a
+    429 that carries none, `RateLimit-Reset` (the seconds until this minute's
+    allowance is renewed)."""
+    hint = headers.get("Retry-After")
+    if not hint and status == 429:
+        hint = headers.get("RateLimit-Reset")
+    return str(hint) if hint else None
+
+
+class Client:
+    def __init__(self, host: str, credential: Credential | None, *, store: Store | None = None,
+                 transport: Any = None, sleep: Any = None, attempts: int = ATTEMPTS,
+                 user_agent: str | None = None, timeout: float | None = None,
+                 access: tuple[str, str] | None = None, session: str | None = None) -> None:
+        self.host = host
+        self.credential = credential
+        # A person's own Cloudflare Access session for this host, from
+        # `cloudflared access token` (`connect --credential-stdin`). Sent as
+        # `cf-access-token`, the header Access itself documents for a CLI, and
+        # never beside a delegated token: the request is the person's.
+        self._session = session
+        self.store = store
+        self.attempts = attempts
+        self._access = access
+        self._sleep = sleep or time.sleep
+        # `--timeout N` is seconds for one request: connect, read, write and
+        # pool alike. Unset, the defaults above stand.
+        self.timeout = httpx.Timeout(timeout) if timeout and timeout > 0 else TIMEOUT
+        self._http = httpx.Client(
+            base_url=f"https://{host}", timeout=self.timeout, transport=transport,
+            follow_redirects=False,
+            headers={"User-Agent": user_agent or f"lighthouse/{__version__}",
+                     "Accept": "application/json"})
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # -- credentials ----------------------------------------------------------------
+
+    def _access_pair(self) -> tuple[str, str] | None:
+        if self._access:
+            return self._access
+        return self.credential.access() if self.credential else None
+
+    def _headers(self, idempotency: str | None) -> dict[str, str]:
+        out = {}
+        pair = self._access_pair()
+        if pair:
+            out["CF-Access-Client-Id"], out["CF-Access-Client-Secret"] = pair
+        if self._session:
+            out["cf-access-token"] = self._session
+        elif self.credential and self.credential.access_token:
+            out["Authorization"] = f"Bearer {self.credential.access_token}"
+        if idempotency:
+            out["Idempotency-Key"] = idempotency
+        return out
+
+    def refresh(self) -> bool:
+        """Exchange the refresh token for a new pair. False if there is nothing
+        to refresh with, which is the normal case in CI."""
+        cred = self.credential
+        if cred is None or not cred.refresh_token or cred.source != "keychain":
+            return False
+        reply = self._http.post("/api/v1/oauth/token", headers=self._headers(None), json={
+            "grant_type": "refresh_token", "refresh_token": cred.refresh_token})
+        if reply.status_code != 200:
+            return False
+        token = reply.json()
+        self.credential = self.store.save(
+            self.host, token, email=cred.email, access_client_id=cred.access_client_id,
+            access_client_secret=cred.access_client_secret) \
+            if self.store is not None else cred
+        return True
+
+    # -- requests ---------------------------------------------------------------------
+
+    def request(self, method: str, path: str, *, params: dict[str, Any] | None = None,
+                json_body: Any = None, idempotency: str | None = None) -> Any:
+        """One logical request, retried where retrying is safe."""
+        method = method.upper()
+        if idempotency is None and method in WRITES:
+            idempotency = str(uuid.uuid4())
+        if self.credential is not None and self.credential.stale():
+            self.refresh()
+        refreshed = False
+        last: CliError | None = None
+        for attempt in range(self.attempts):
+            try:
+                reply = self._http.request(
+                    method, path, params={k: v for k, v in (params or {}).items() if v is not None},
+                    json=json_body, headers=self._headers(idempotency))
+            except httpx.TimeoutException as e:
+                last = CliError(t("err.timeout", method=method, path=path), code=RETRY, error="timeout")
+                log.debug("timeout: %s", e)
+                self._sleep(sleep_for(attempt, None))
+                continue
+            except httpx.TransportError as e:
+                raise CliError(t("err.unreachable", host=self.host, error=e), code=RETRY,
+                               error="unreachable", hint=t("hint.unreachable")) from None
+            if access_wall(reply):
+                raise AccessRefused(self.host, configured=self._access_pair() is not None)
+            if reply.status_code == 401 and not refreshed and self.refresh():
+                refreshed = True
+                continue
+            if 200 <= reply.status_code < 300:
+                if not reply.content:
+                    return {}
+                try:
+                    return reply.json()
+                except ValueError:
+                    raise CliError(t("err.not_json", method=method, path=path),
+                                   error="bad_response") from None
+            body = self._body(reply)
+            if reply.status_code == 429 or reply.status_code >= 500:
+                last = Refused(reply.status_code, body)
+                if attempt + 1 < self.attempts:
+                    self._sleep(sleep_for(attempt, retry_hint(reply.status_code, reply.headers)))
+                    continue
+            if reply.status_code == 401:
+                raise self._unauthenticated()
+            raise Refused(reply.status_code, body)
+        raise last or CliError(t("err.exhausted", method=method, path=path), code=RETRY,
+                               error="exhausted")
+
+    def _unauthenticated(self) -> CliError:
+        """A 401, said in the terms of where the credential came from."""
+        cred = self.credential
+        if cred is None or cred.source != "environment":
+            return NotSignedIn(self.host)
+        if cred.kind == "machine":
+            return TokenRefused(t("err.machine_key_refused", env=ENV_TOKEN),
+                                t("hint.machine_key_refused"))
+        return TokenRefused(t("err.delegated_token_refused", env=ENV_TOKEN),
+                            t("hint.delegated_token_refused", env=ENV_TOKEN))
+
+    @staticmethod
+    def _body(reply: httpx.Response) -> dict[str, Any]:
+        try:
+            out = reply.json()
+            return out if isinstance(out, dict) else {"message": str(out)[:200]}
+        except ValueError:
+            return {"message": t("err.service_answered", status=reply.status_code)}
+
+    def get(self, path: str, **params: Any) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, body: Any = None, **params: Any) -> Any:
+        return self.request("POST", path, params=params, json_body=body)
+
+    def delete(self, path: str, **params: Any) -> Any:
+        return self.request("DELETE", path, params=params)
+
+    # -- pagination ---------------------------------------------------------------------
+
+    def each(self, path: str, key: str, *, limit: int | None = None,
+             **params: Any) -> Iterator[dict[str, Any]]:
+        """Every row of a cursor-paginated read, newest page first.
+
+        The read API answers `{<key>: [...], "next": "..."}` and takes that
+        value back as `?cursor=`; a page whose `next` is null is the last one.
+        `limit` caps the rows yielded, so `runs tail --limit 10` does not walk
+        a year of history to show ten lines.
+        """
+        seen = 0
+        cursor = None
+        visited: set[str] = set()
+        for _ in range(MAX_PAGES):
+            page = self.get(path, cursor=cursor, **params)
+            rows = page.get(key) or []
+            for row in rows:
+                yield row
+                seen += 1
+                if limit is not None and seen >= limit:
+                    return
+            cursor = page.get("next")
+            if not cursor or not rows or cursor in visited:
+                return
+            visited.add(str(cursor))
+
+    def get_all(self, path: str, key: str, **params: Any) -> dict[str, Any]:
+        """The whole of a paginated read as one document: the first page, with
+        `key` holding every page's rows and `next` null. A release gate that
+        read only page one would pass on what it never saw."""
+        first = self.get(path, **params)
+        rows = list(first.get(key) or [])
+        cursor = first.get("next")
+        visited: set[str] = set()
+        for _ in range(MAX_PAGES):
+            if not cursor or cursor in visited:
+                break
+            visited.add(str(cursor))
+            page = self.get(path, cursor=cursor, **params)
+            more = page.get(key) or []
+            rows.extend(more)
+            cursor = page.get("next") if more else None
+        return {**first, key: rows, "next": None}