mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/login.py

@@ -0,0 +1,691 @@
+"""``mr-data login`` -- RFC 8628 device authorization against the Mostly Right cloud.
+
+Three calls, in order, against the cloud's better-auth device-authorization plugin and its device
+key mint route:
+
+1. ``POST {cloud}/api/auth/device/code`` starts the flow and returns a ``user_code`` to show the
+   operator and a ``device_code`` this machine polls with.
+2. ``POST {cloud}/api/auth/device/token`` is polled on the interval the cloud names, until the
+   operator approves in their browser (``authorization_pending`` keeps polling, ``slow_down`` widens
+   the interval by RFC 8628's required five seconds, ``access_denied``/``expired_token`` stop the
+   flow) or it returns a Better Auth session token.
+3. ``POST {cloud}/api/device/keys``, immediately, with that session token as a bearer credential,
+   mints the durable ``mr_cli_`` device key this command stores. The cloud revokes the bearer
+   session right after this mint, so nothing else may call the cloud between steps 2 and 3.
+
+The transport is stdlib ``urllib`` in the shape :mod:`mostlyright.data_harness.key_seam` and
+:mod:`mostlyright.data_harness.hosted_bootstrap` already use -- proxies and redirects disabled, a
+byte cap and a bounded timeout on every response -- rather than a new dependency. ``login`` has to
+work on the same plain install ``mr-data inventory`` does.
+
+The raw key this mints is handed to :mod:`mostlyright.data_harness.ux.credentials` the moment it
+exists and is never returned from here, logged, or put in a payload; only :class:`DeviceKey`'s
+``prefix`` and ``last_four`` are.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import socket
+import ssl
+import sys
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.error import HTTPError
+from urllib.parse import urlsplit
+from urllib.request import (
+    HTTPRedirectHandler,
+    HTTPSHandler,
+    ProxyHandler,
+    Request,
+    build_opener,
+)
+
+from mostlyright.data_harness.canonical import CanonicalJSONError, parse_foreign_json
+from mostlyright.data_harness.key_seam import LEGACY_API_KEY_ENV
+from mostlyright.data_harness.ux.cloud_auth import CloudAuthClient, CloudAuthError
+from mostlyright.data_harness.ux.credential_store import (
+    CredentialEnvelope,
+    CredentialStoreError,
+    ProtectedCredential,
+    credential_lock,
+)
+from mostlyright.data_harness.ux.credentials import (
+    CLOUD_URL_ENV,
+    DEFAULT_CLOUD_URL,
+    LoginError,
+    StoredCredentials,
+    credential_transaction_store,
+    install_credential_manifest,
+    refuse_existing_credentials,
+)
+
+#: The OAuth client identity every device-flow request carries. Fixed, because this command is the
+#: only issuer of it.
+CLIENT_ID = "mostlyright-cli"
+
+DEVICE_CODE_PATH = "/api/auth/device/code"
+DEVICE_TOKEN_PATH = "/api/auth/device/token"
+DEVICE_KEYS_PATH = "/api/device/keys"
+
+#: RFC 8628's grant type string for the token endpoint, verbatim.
+DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+#: A verdict is a small object; anything larger than this is not one. Mirrors
+#: ``key_seam.MAX_VERIFY_RESPONSE_BYTES`` and ``hosted_bootstrap.MAX_BOOTSTRAP_RESPONSE_BYTES``: a
+#: cap sized for what the endpoint is documented to return, not for what it could be made to send.
+MAX_RESPONSE_BYTES = 16 * 1024
+
+#: A bounded wait on each individual request. A poll that hangs is a login that never returns.
+REQUEST_TIMEOUT_SECONDS = 10.0
+
+#: A floor under whatever interval the cloud names, so a misconfigured or hostile ``interval`` of
+#: zero cannot turn polling into a busy loop.
+MIN_POLL_INTERVAL_SECONDS = 1.0
+
+#: RFC 8628 section 3.5: on ``slow_down`` the client MUST widen the polling interval by at least
+#: five seconds for the rest of the session.
+SLOW_DOWN_INCREMENT_SECONDS = 5.0
+
+MIN_DEVICE_NAME_LENGTH = 1
+MAX_DEVICE_NAME_LENGTH = 100
+
+LOGIN_SCHEMA_VERSION = "mr-data-login.v1"
+
+
+def _with_environment_authority(payload: dict[str, Any]) -> dict[str, Any]:
+    """State the surviving parent-process authority without ever reading its value."""
+
+    if LEGACY_API_KEY_ENV in os.environ:
+        payload["environment_authority"] = "remains_effective"
+    return payload
+
+
+@dataclass(frozen=True)
+class DeviceAuthorization:
+    """The device flow's starting grant: what to show the operator, and what to poll with."""
+
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: float
+
+
+@dataclass(frozen=True)
+class DeviceSession:
+    """A Better Auth session token, good for exactly one thing: minting the device key."""
+
+    access_token: str
+
+    def __repr__(self) -> str:
+        return "DeviceSession(access_token='<redacted>')"
+
+
+@dataclass(frozen=True)
+class DeviceKey:
+    """The durable ``mr_cli_`` credential the mint route hands back."""
+
+    key_id: str
+    raw_key: str
+    prefix: str
+    last_four: str
+
+    def __repr__(self) -> str:
+        return (
+            f"DeviceKey(key_id={self.key_id!r}, prefix={self.prefix!r}, "
+            f"last_four={self.last_four!r}, raw_key='<redacted>')"
+        )
+
+
+class DeviceFlowTransport(Protocol):
+    """Minimal redirect-free, proxy-free transport -- the same shape ``key_seam`` and
+    ``hosted_bootstrap`` already define, so a stub written for one reads as a stub for any."""
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes]: ...
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    """Refuse every redirect; a followed one would re-send the bearer token to another host."""
+
+    def redirect_request(
+        self,
+        request: Request,
+        file_pointer: Any,
+        code: int,
+        message: str,
+        headers: Any,
+        new_url: str,
+    ) -> None:
+        return None
+
+
+class UrlLibDeviceFlowTransport:
+    """Small stdlib transport with ambient proxies and redirects disabled."""
+
+    def __init__(self) -> None:
+        self._opener = build_opener(
+            ProxyHandler({}),
+            HTTPSHandler(context=ssl.create_default_context()),
+            _NoRedirect(),
+        )
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes]:
+        request = Request(url, data=body, headers=dict(headers), method=method)
+        try:
+            response = self._opener.open(request, timeout=REQUEST_TIMEOUT_SECONDS)
+        except HTTPError as error:
+            response = error
+        with response:
+            status = int(response.status)
+            content_length = response.headers.get("Content-Length")
+            if content_length is not None:
+                try:
+                    declared = int(content_length)
+                except ValueError as error:
+                    raise LoginError(
+                        "LOGIN_TRANSPORT_FAILED",
+                        "the cloud sent an invalid content length",
+                    ) from error
+                if declared < 0 or declared > maximum:
+                    raise LoginError(
+                        "LOGIN_TRANSPORT_FAILED",
+                        "the cloud's response exceeds its byte limit",
+                    )
+            raw = response.read(maximum + 1)
+        if len(raw) > maximum:
+            raise LoginError(
+                "LOGIN_TRANSPORT_FAILED", "the cloud's response exceeds its byte limit"
+            )
+        return status, raw
+
+
+def _https_url(value: str, label: str) -> str:
+    """Return ``value`` when it is a plain absolute https URL, otherwise refuse it.
+
+    Copied rather than imported, the way ``key_seam._https_url`` and
+    ``hosted_bootstrap._https_url`` are each their own copy of the same policy: importing across
+    those modules would pull in code this command does not otherwise touch, for a validation that
+    has to stay identical without needing to be the same function.
+    """
+
+    if not isinstance(value, str) or not 1 <= len(value) <= 2048:
+        raise LoginError("LOGIN_CONFIG_INVALID", f"{label} is not a usable URL")
+    if value.endswith("/"):
+        raise LoginError("LOGIN_CONFIG_INVALID", f"{label} must not end with a slash")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+    ):
+        raise LoginError(
+            "LOGIN_CONFIG_INVALID",
+            f"{label} must be an absolute https URL without user information or fragment",
+        )
+    return value
+
+
+def _device_name(value: str | None) -> str:
+    name = value if value is not None else socket.gethostname()
+    if not isinstance(name, str):
+        raise LoginError("LOGIN_CONFIG_INVALID", "a device name must be text")
+    if not MIN_DEVICE_NAME_LENGTH <= len(name) <= MAX_DEVICE_NAME_LENGTH:
+        raise LoginError(
+            "LOGIN_CONFIG_INVALID",
+            f"a device name must be {MIN_DEVICE_NAME_LENGTH}-{MAX_DEVICE_NAME_LENGTH} characters",
+        )
+    return name
+
+
+def _post_json(
+    transport: DeviceFlowTransport,
+    url: str,
+    payload: Mapping[str, Any],
+    *,
+    headers: Mapping[str, str] | None = None,
+) -> tuple[int, Any]:
+    """POST one JSON body and return ``(status, parsed_body_or_None)``.
+
+    Never raises for a non-2xx status or a body that fails to parse: the three device-flow callers
+    each read those differently (a poll's ``authorization_pending`` is not a failure; a mint
+    failure means something else again), so only what none of them can do anything useful with --
+    the request never reaching the cloud at all, or the byte cap being exceeded -- is collapsed
+    into one typed failure here.
+    """
+
+    body = json.dumps(dict(payload), sort_keys=True).encode("utf-8")
+    request_headers = {"Content-Type": "application/json", "Accept": "application/json"}
+    request_headers.update(headers or {})
+    try:
+        status, raw = transport.request("POST", url, request_headers, body, MAX_RESPONSE_BYTES)
+    except LoginError:
+        raise
+    except Exception as error:
+        raise LoginError(
+            "LOGIN_TRANSPORT_FAILED", f"the cloud could not be reached: {error}"
+        ) from error
+    if not raw:
+        return status, None
+    try:
+        # `parse_foreign_json`, not `parse_json`: this body is authored by a separate cloud
+        # codebase, not by this harness, and the Harness's own integer-only canonical form is not a
+        # contract that document ever signed up to.
+        return status, parse_foreign_json(raw)
+    except CanonicalJSONError:
+        return status, None
+
+
+def _required_str(payload: Mapping[str, Any], field: str) -> str:
+    value = payload.get(field)
+    if not isinstance(value, str) or not value:
+        raise LoginError(
+            "LOGIN_TRANSPORT_FAILED", f"the cloud's response is missing a usable {field!r}"
+        )
+    return value
+
+
+def _required_positive_int(payload: Mapping[str, Any], field: str) -> int:
+    value = payload.get(field)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise LoginError(
+            "LOGIN_TRANSPORT_FAILED", f"the cloud's response is missing a usable {field!r}"
+        )
+    return value
+
+
+def _positive_number(payload: Mapping[str, Any], field: str, *, default: float) -> float:
+    value = payload.get(field, default)
+    if isinstance(value, bool) or not isinstance(value, int | float) or value <= 0:
+        raise LoginError(
+            "LOGIN_TRANSPORT_FAILED", f"the cloud's response is missing a usable {field!r}"
+        )
+    return float(value)
+
+
+def request_device_code(cloud_url: str, *, transport: DeviceFlowTransport) -> DeviceAuthorization:
+    """Start the device flow: ``POST {cloud}/api/auth/device/code``."""
+
+    url = f"{cloud_url}{DEVICE_CODE_PATH}"
+    status, parsed = _post_json(transport, url, {"client_id": CLIENT_ID})
+    if status != 200 or not isinstance(parsed, dict):
+        raise LoginError(
+            "LOGIN_TRANSPORT_FAILED",
+            f"the cloud could not start a device sign-in (HTTP {status})",
+        )
+    return DeviceAuthorization(
+        device_code=_required_str(parsed, "device_code"),
+        user_code=_required_str(parsed, "user_code"),
+        verification_uri=_required_str(parsed, "verification_uri"),
+        verification_uri_complete=_required_str(parsed, "verification_uri_complete"),
+        expires_in=_required_positive_int(parsed, "expires_in"),
+        interval=_positive_number(parsed, "interval", default=MIN_POLL_INTERVAL_SECONDS * 5),
+    )
+
+
+def poll_for_token(
+    cloud_url: str,
+    authorization: DeviceAuthorization,
+    *,
+    transport: DeviceFlowTransport,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+) -> DeviceSession:
+    """Poll ``POST {cloud}/api/auth/device/token`` until approval, denial, or expiry.
+
+    Waits ``interval`` seconds before every poll, including the first -- the operator cannot have
+    approved before they have seen the code -- and widens ``interval`` by
+    :data:`SLOW_DOWN_INCREMENT_SECONDS` on every ``slow_down`` for the rest of this call, per
+    RFC 8628 section 3.5.
+    """
+
+    deadline = clock() + authorization.expires_in
+    interval = max(authorization.interval, MIN_POLL_INTERVAL_SECONDS)
+    url = f"{cloud_url}{DEVICE_TOKEN_PATH}"
+    payload = {
+        "grant_type": DEVICE_CODE_GRANT_TYPE,
+        "device_code": authorization.device_code,
+        "client_id": CLIENT_ID,
+    }
+    while True:
+        if clock() >= deadline:
+            raise LoginError(
+                "LOGIN_EXPIRED",
+                "the sign-in code expired before it was approved; run mr-data login again",
+            )
+        sleep(interval)
+        status, parsed = _post_json(transport, url, payload)
+        if not isinstance(parsed, dict):
+            raise LoginError(
+                "LOGIN_TRANSPORT_FAILED",
+                f"the cloud's sign-in response could not be read (HTTP {status})",
+            )
+        error = parsed.get("error")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += SLOW_DOWN_INCREMENT_SECONDS
+            continue
+        if error == "access_denied":
+            raise LoginError(
+                "LOGIN_ACCESS_DENIED",
+                "sign-in was denied in the browser; run mr-data login again to retry",
+            )
+        if error == "expired_token":
+            raise LoginError(
+                "LOGIN_EXPIRED",
+                "the sign-in code expired before it was approved; run mr-data login again",
+            )
+        if isinstance(error, str) and error:
+            raise LoginError("LOGIN_TRANSPORT_FAILED", f"the cloud refused the sign-in: {error}")
+        if status == 200:
+            return DeviceSession(access_token=_required_str(parsed, "access_token"))
+        raise LoginError(
+            "LOGIN_TRANSPORT_FAILED",
+            f"the cloud's sign-in response was not understood (HTTP {status})",
+        )
+
+
+def mint_device_key(
+    cloud_url: str,
+    session: DeviceSession,
+    *,
+    device_name: str,
+    transport: DeviceFlowTransport,
+) -> DeviceKey:
+    """``POST {cloud}/api/device/keys``, the one call this session's bearer token is good for.
+
+    Must run immediately after :func:`poll_for_token` returns: the cloud revokes the bearer session
+    right after this mint, so no other network call may sit between the two.
+    """
+
+    status, parsed = _post_json(
+        transport,
+        f"{cloud_url}{DEVICE_KEYS_PATH}",
+        {"deviceName": device_name},
+        headers={"Authorization": f"Bearer {session.access_token}"},
+    )
+    if status != 201 or not isinstance(parsed, dict):
+        raise LoginError(
+            "LOGIN_MINT_FAILED",
+            f"signed in, but the cloud could not issue a device key (HTTP {status}); "
+            "run mr-data login again",
+        )
+    try:
+        return DeviceKey(
+            key_id=_required_str(parsed, "id"),
+            raw_key=_required_str(parsed, "rawKey"),
+            prefix=_required_str(parsed, "prefix"),
+            last_four=_required_str(parsed, "lastFour"),
+        )
+    except LoginError as error:
+        raise LoginError(
+            "LOGIN_MINT_FAILED",
+            "signed in, but the cloud's device key response is missing fields it must have; "
+            "run mr-data login again",
+        ) from error
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def announce_device_code(authorization: DeviceAuthorization) -> None:
+    """Print the code and address prominently, on stderr, so it survives a piped stdout.
+
+    Plain text only, and only wired up from plain-mode command dispatch: ``--json`` mode calls
+    :func:`run_login` without an announcer, because a caller asking for one machine-readable object
+    should get exactly one, on stdout, when this finishes -- not an interstitial line ahead of it.
+    """
+
+    print(file=sys.stderr)
+    print(f"    {authorization.user_code}", file=sys.stderr)
+    print(file=sys.stderr)
+    print(
+        f"Open {authorization.verification_uri_complete} to approve this device.",
+        file=sys.stderr,
+    )
+    print("Waiting for approval...", file=sys.stderr, flush=True)
+
+
+def run_login(
+    *,
+    cloud_url: str | None = None,
+    device_name: str | None = None,
+    force: bool = False,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+    transport: DeviceFlowTransport | None = None,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+    open_browser: Callable[[str], bool] | None = None,
+    announce: Callable[[DeviceAuthorization], None] | None = None,
+    cloud_client_factory: Callable[[str, str], Any] | None = None,
+) -> dict[str, Any]:
+    """Run the whole device flow and store the resulting credential.
+
+    ``open_browser`` defaults to :func:`webbrowser.open`, resolved lazily so importing this module
+    never imports ``webbrowser``'s platform-probing machinery for callers -- ``whoami`` among them
+    -- that never open a browser at all.
+    """
+
+    if open_browser is None:
+        import webbrowser
+
+        open_browser = webbrowser.open
+
+    resolved_cloud_url = _https_url(
+        cloud_url if cloud_url is not None else _configured_cloud_url(), "the cloud address"
+    )
+    resolved_device_name = _device_name(device_name)
+    if not force:
+        # Preserve the compatibility preflight for every occupied control path, including a
+        # dangling link.  The durable lease below remains the authoritative concurrent gate.
+        refuse_existing_credentials(config_dir=config_dir)
+    try:
+        opened = credential_transaction_store(
+            config_dir=config_dir, credential_store=credential_store
+        )
+    except LoginError:
+        raise
+    if opened is None:  # Defensive: the helper returns a selected empty store for first login.
+        raise LoginError(
+            "LOGIN_CREDENTIAL_STORE_UNAVAILABLE", "the credential store is unavailable"
+        )
+    store, manifest_path = opened
+    try:
+        current = store.load()
+        if current is not None and current.state == "active" and not force:
+            refuse_existing_credentials(config_dir=config_dir)
+        operation = "rotate" if force else "login"
+        pending = store.acquire_login_lease(
+            operation=operation,
+            requested_device_name=resolved_device_name,
+            created_at=_now_iso(),
+        )
+        if not manifest_path.exists():
+            install_credential_manifest(manifest_path, store.backend.name)
+    except CredentialStoreError as error:
+        raise LoginError("LOGIN_CREDENTIAL_RECOVERY_REQUIRED", error.detail) from None
+    live_transport = transport or UrlLibDeviceFlowTransport()
+
+    authorization = request_device_code(resolved_cloud_url, transport=live_transport)
+    if announce is not None:
+        announce(authorization)
+    with contextlib.suppress(Exception):
+        # Best-effort: a headless box or a browser that fails to launch must not stop a flow whose
+        # answer is printed either way.
+        open_browser(authorization.verification_uri_complete)
+
+    session = poll_for_token(
+        resolved_cloud_url, authorization, transport=live_transport, clock=clock, sleep=sleep
+    )
+    # No network call of any kind may sit between the line above and the one below -- see
+    # `mint_device_key`'s docstring: the cloud revokes this bearer session immediately after mint.
+    key = mint_device_key(
+        resolved_cloud_url, session, device_name=resolved_device_name, transport=live_transport
+    )
+
+    credentials = StoredCredentials(
+        cloud_url=resolved_cloud_url,
+        key_id=key.key_id,
+        prefix=key.prefix,
+        last_four=key.last_four,
+        device_name=resolved_device_name,
+        created_at=_now_iso(),
+        raw_key=key.raw_key,
+    )
+    minted = credentials._protected()
+    try:
+        installed = store.complete_login_lease(nonce=pending.login_pending.nonce, minted=minted)
+    except CredentialStoreError as error:
+        cleanup = _self_revoke_after_mint(minted, cloud_client_factory=cloud_client_factory)
+        raise LoginError(
+            "LOGIN_MINT_CLEANUP_REQUIRED",
+            "the minted device key could not be stored; remote cleanup is " + cleanup,
+        ) from error
+
+    if installed.state == "active":
+        if force:
+            return _with_environment_authority(
+                {
+                    "schema_version": "mr-data-auth-rotate.v1",
+                    "status": "rotated",
+                    "remote_revocation": "proved",
+                    "local_state": "active",
+                    **credentials.to_receipt(),
+                }
+            )
+        return _with_environment_authority(
+            {
+                "schema_version": LOGIN_SCHEMA_VERSION,
+                "status": "device_authenticated",
+                **credentials.to_receipt(),
+                "credentials_path": str(manifest_path),
+            }
+        )
+
+    assert installed.active is not None and installed.prior is not None
+    try:
+        _revoke_exact(
+            installed.prior,
+            cloud_client_factory=cloud_client_factory,
+        )
+    except CloudAuthError as error:
+        return _with_environment_authority(
+            {
+                "schema_version": "mr-data-auth-rotate.v1",
+                "status": "recovery_required",
+                "remote_revocation": "unproved",
+                "local_state": "revoke_pending",
+                "error_code": error.code,
+            }
+        )
+    try:
+        with credential_lock(store.config_dir):
+            cleanup_pending = CredentialEnvelope.pending_cleanup(
+                generation=installed.generation + 1,
+                active=installed.active,
+                prior=installed.prior,
+            )
+            store.replace_under_held_lock(
+                cleanup_pending,
+                expected_generation=installed.generation,
+                expected_states=frozenset({"revoke_pending"}),
+            )
+            active = CredentialEnvelope.active_envelope(
+                generation=cleanup_pending.generation + 1,
+                active=cleanup_pending.active,
+            )
+            store.replace_under_held_lock(
+                active,
+                expected_generation=cleanup_pending.generation,
+                expected_states=frozenset({"cleanup_pending"}),
+            )
+    except CredentialStoreError as error:
+        return _with_environment_authority(
+            {
+                "schema_version": "mr-data-auth-rotate.v1",
+                "status": "recovery_required",
+                "remote_revocation": "proved",
+                "local_state": "cleanup_pending",
+                "error_code": error.code,
+            }
+        )
+    return _with_environment_authority(
+        {
+            "schema_version": "mr-data-auth-rotate.v1",
+            "status": "rotated",
+            "remote_revocation": "proved",
+            "local_state": "active",
+            **credentials.to_receipt(),
+        }
+    )
+
+
+def _revoke_exact(
+    credential: ProtectedCredential,
+    *,
+    cloud_client_factory: Callable[[str, str], Any] | None,
+) -> None:
+    client = (CloudAuthClient if cloud_client_factory is None else cloud_client_factory)(
+        credential.cloud_url, credential.raw_key
+    )
+    client.revoke(credential.key_id, exact_secret_same_key_replay=True)
+
+
+def _self_revoke_after_mint(
+    credential: ProtectedCredential,
+    *,
+    cloud_client_factory: Callable[[str, str], Any] | None,
+) -> str:
+    try:
+        _revoke_exact(credential, cloud_client_factory=cloud_client_factory)
+    except CloudAuthError:
+        return "unproved"
+    return "proved"
+
+
+def _configured_cloud_url() -> str:
+    return os.environ.get(CLOUD_URL_ENV) or DEFAULT_CLOUD_URL
+
+
+__all__ = [
+    "CLIENT_ID",
+    "CLOUD_URL_ENV",
+    "DEFAULT_CLOUD_URL",
+    "LOGIN_SCHEMA_VERSION",
+    "DeviceAuthorization",
+    "DeviceFlowTransport",
+    "DeviceKey",
+    "DeviceSession",
+    "UrlLibDeviceFlowTransport",
+    "announce_device_code",
+    "mint_device_key",
+    "poll_for_token",
+    "request_device_code",
+    "run_login",
+]