cli-login 0.1.0__py3-none-any.whl

cli_login/remote.py

@@ -0,0 +1,208 @@
+"""Remote sign-in: a CLI with no browser gets a session that a person approves from another device.
+
+The CLI keeps two secrets and sends only their hashes: the PKCE verifier V (the broker sees ``S256(V)``) and the
+poll secret P (the broker sees ``sha256(P)``). The person opens the approval URL, checks the matching code and
+signs in; the broker then holds an authorization code that is useless without V, and hands it only to a poll that
+knows P. The CLI exchanges the code itself and passes the token response to the session store.
+
+See docs/protocol.md.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import math
+import secrets
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from . import PROTOCOL_VERSION, __version__
+from .errors import AuthError, OAuthError
+
+
+class RemoteLoginError(OAuthError):
+    """A remote sign-in that did not finish. ``transient`` says whether trying again later may work."""
+
+    def __init__(self, code: str, message: str, *, transient: bool = False):
+        self.code = code
+        self.transient = transient
+        AuthError.__init__(self, message)
+
+
+def default_http(method: str, url: str, *, json_body=None, form=None, timeout: float = 30) -> tuple[int, dict[str, Any], dict[str, str]]:
+    """One HTTPS request; answers (status, JSON body, headers). Network failures raise OSError."""
+    if json_body is not None:
+        data, content_type = json.dumps(json_body).encode(), "application/json"
+    else:
+        data, content_type = urllib.parse.urlencode(form or {}).encode(), "application/x-www-form-urlencoded"
+    request = urllib.request.Request(url, data=data, method=method, headers={"content-type": content_type, "accept": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            status, raw, headers = response.status, response.read(), dict(response.headers)
+    except urllib.error.HTTPError as error:
+        status, raw, headers = error.code, error.read(), dict(error.headers or {})
+    try:
+        body = json.loads(raw or b"{}")
+    except ValueError:
+        body = {}
+    return status, body if isinstance(body, dict) else {}, {key.lower(): value for key, value in headers.items()}
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def _https(value: Any, what: str) -> str:
+    parts = urllib.parse.urlsplit(value if isinstance(value, str) else "")
+    if parts.scheme != "https" or not parts.hostname or parts.username or parts.password:
+        raise RemoteLoginError("invalid_broker_answer", f"The broker answered an unusable {what}.")
+    return value
+
+
+MAX_INTERVAL = 60   # seconds between polls, whatever the broker says
+MAX_WAIT = 900      # seconds a CLI waits for an approval, whatever the broker says
+
+
+def _clamp(value: Any, default: float, low: float, high: float | None) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        number = default
+    if math.isnan(number):
+        number = default
+    number = max(number, low)
+    return min(number, high) if high is not None else number
+
+
+def _claims(token: Any) -> dict[str, Any]:
+    """The payload of a JWT the CLI received straight from the token endpoint over TLS (no signature check here)."""
+    try:
+        payload = token.split(".")[1]
+        return json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+    except (AttributeError, IndexError, ValueError):
+        raise RemoteLoginError("invalid_token", "The sign-in provider answered an unreadable token.") from None
+
+
+def remote_login(
+    target,
+    store_token_set: Callable[[Mapping[str, Any]], Any],
+    *,
+    http=default_http,
+    out: Callable[[str], None] = print,
+    clock: Callable[[], float] = time.time,
+    sleep: Callable[[float], None] = time.sleep,
+    host: str | None = None,
+    note: str | None = None,
+    expected_email: str | None = None,
+    token=secrets.token_urlsafe,
+):
+    """Sign in through the target's broker and return what ``store_token_set`` returns.
+
+    ``target`` supplies ``client_id``, ``broker_endpoint``, ``remote_callback_uri``, ``token_endpoint`` and
+    ``api_endpoint``, which names the binding to the broker and on the approval page. The broker's ``redirect_uri``
+    must equal ``remote_callback_uri``, and its approval URL must be on that origin. Nothing secret is printed: only the approval URL and the
+    matching code.
+
+    Whoever approves first owns the session, and the approval URL and code are often relayed through chat. Pass
+    ``expected_email`` to refuse, and store nothing, when the person who approved is someone else. The signed-in
+    identity is always printed.
+    """
+    broker = getattr(target, "broker_endpoint", None)
+    if not broker:
+        raise RemoteLoginError("remote_unavailable", "This target has no remote sign-in broker; sign in on a machine with a browser.")
+    broker = _https(broker, "broker endpoint").rstrip("/")
+    remote_callback = getattr(target, "remote_callback_uri", None)
+    if not remote_callback:
+        raise RemoteLoginError("remote_unavailable", "This target names no remote callback; sign in on a machine with a browser.")
+    remote_callback = _https(remote_callback, "remote callback URI")
+    expected_origin = urllib.parse.urlsplit(remote_callback)
+    verifier, poll_secret, nonce = token(64), token(32), token(24)
+    requester = {"host": host or socket.gethostname(), "version": __version__}
+    if note:
+        requester["note"] = note
+    try:
+        status, started, _ = http("POST", broker + "/start", json_body={
+            "protocol": PROTOCOL_VERSION,
+            "client_id": target.client_id,
+            "target": target.api_endpoint,
+            "code_challenge": _b64url(hashlib.sha256(verifier.encode()).digest()),
+            "code_challenge_method": "S256",
+            "poll_secret_hash": hashlib.sha256(poll_secret.encode()).hexdigest(),
+            "nonce": nonce,
+            "requester": requester,
+        })
+    except OSError:
+        raise RemoteLoginError("broker_unreachable", "The sign-in broker could not be reached; try again.", transient=True) from None
+    if status == 429:
+        raise RemoteLoginError("too_many_requests", "Too many sign-in attempts from this machine; wait a minute and try again.", transient=True)
+    if status != 200 or started.get("protocol") != PROTOCOL_VERSION:
+        raise RemoteLoginError(started.get("error") or "start_refused", "The sign-in broker refused to start a sign-in.")
+    url = _https(started.get("approval_url"), "approval URL")
+    transaction, code = started.get("transaction"), started.get("matching_code")
+    if not isinstance(transaction, str) or not isinstance(code, str):
+        raise RemoteLoginError("invalid_broker_answer", "The broker answered an unusable transaction.")
+    url_origin = urllib.parse.urlsplit(url)
+    if (url_origin.scheme, url_origin.netloc) != (expected_origin.scheme, expected_origin.netloc):
+        raise RemoteLoginError("invalid_broker_answer", "The broker pointed at an approval page on another site.")
+    interval = _clamp(started.get("interval"), 5, 1, MAX_INTERVAL)
+    expires_at = min(_clamp(started.get("expires_at"), clock() + 600, 0, None), clock() + MAX_WAIT)
+    out(f"To approve this sign-in, open {url}\nand check that the page shows the code {code}.")
+
+    while True:
+        if clock() >= expires_at:
+            raise RemoteLoginError("expired_token", "The approval link expired; start the sign-in again.")
+        sleep(interval)
+        try:
+            status, answer, headers = http("POST", broker + "/poll", json_body={"transaction": transaction, "poll_secret": poll_secret})
+        except OSError:
+            continue  # polling is safe to repeat; the code is handed over only once, to a poll that knows P
+        if status == 200:
+            break
+        error = answer.get("error")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval = min(max(_clamp(answer.get("interval"), interval + 5, 1, MAX_INTERVAL), interval + 1), MAX_INTERVAL)
+        elif status == 429:
+            sleep(_clamp(headers.get("retry-after") or answer.get("retry_after"), 60, 1, MAX_INTERVAL))
+        elif error == "access_denied":
+            raise RemoteLoginError("access_denied", "The sign-in was denied on the approval page.")
+        elif error == "expired_token":
+            raise RemoteLoginError("expired_token", "The approval link expired or was already used; start the sign-in again.")
+        elif status < 500:
+            raise RemoteLoginError(error or "poll_refused", "The sign-in broker refused the sign-in.")
+
+    authorization_code, redirect_uri = answer.get("code"), _https(answer.get("redirect_uri"), "redirect URI")
+    if redirect_uri != remote_callback:
+        raise RemoteLoginError("invalid_broker_answer", "The broker answered a callback this target does not use.")
+    if not isinstance(authorization_code, str) or not authorization_code:
+        raise RemoteLoginError("invalid_broker_answer", "The broker answered without a code.")
+    try:
+        status, tokens, _ = http("POST", _https(target.token_endpoint, "token endpoint"), form={
+            "grant_type": "authorization_code",
+            "client_id": target.client_id,
+            "code": authorization_code,
+            "redirect_uri": redirect_uri,
+            "code_verifier": verifier,
+        })
+    except OSError:
+        # The code is single use and may already be spent; a retry cannot be known to be safe, so start again.
+        raise RemoteLoginError("exchange_uncertain", "The sign-in provider did not answer; start the sign-in again.") from None
+    if status != 200:
+        raise RemoteLoginError(str(tokens.get("error") or "exchange_refused"), "The sign-in provider refused the code; start the sign-in again.")
+    claims = _claims(tokens.get("id_token"))
+    if claims.get("nonce") != nonce:
+        raise RemoteLoginError("nonce_mismatch", "The sign-in answered tokens for a different request; nothing was saved.")
+    email = claims.get("email") if isinstance(claims.get("email"), str) else None
+    if expected_email is not None and (email or "").casefold() != expected_email.casefold():
+        raise RemoteLoginError("unexpected_identity", "Someone other than the expected person approved this sign-in; nothing was saved.")
+    record = store_token_set(tokens)
+    out(f"Signed in as {email or claims.get('sub', 'an unknown identity')}.")
+    return record

cli_login/session.py

@@ -0,0 +1,213 @@
+"""A renewable session: login, renewal, status and logout with honest revocation."""
+
+from __future__ import annotations
+
+import base64
+import json
+import math
+import secrets
+import threading
+import time
+from contextlib import contextmanager
+
+from .errors import AuthError, OAuthError
+from .locks import default_state_dir, key_lock
+from .oauth import HTTPProvider, authorization_url, pkce_pair, receive_code
+from .stores import open_store
+from .target import Target
+
+
+class Session:
+    def __init__(
+        self,
+        target: Target,
+        *,
+        store=None,
+        provider=None,
+        clock=time.time,
+        receive=receive_code,
+        state_dir=None,
+        login_command: str = "login",
+        identity_provider: str | None = None,
+    ):
+        self.target = target
+        self.store = store if store is not None else open_store(target)
+        self.provider = provider if provider is not None else HTTPProvider()
+        self.clock = clock
+        self.receive = receive
+        self.state_dir = state_dir if state_dir is not None else default_state_dir(target.namespace)
+        self.login_command = login_command
+        self.identity_provider = identity_provider
+        self._token = None
+        self._expires = 0.0
+        self._subject = None
+        self._guard = threading.RLock()
+        self._depth = 0
+
+    @contextmanager
+    def _hold(self):
+        """The key's lock, re-entrant within this session so locked callers can store a token set."""
+        with self._guard:
+            if self._depth:
+                self._depth += 1
+                try:
+                    yield
+                finally:
+                    self._depth -= 1
+                return
+            with key_lock(self.state_dir, self.target.key):
+                self._depth = 1
+                try:
+                    yield
+                finally:
+                    self._depth = 0
+
+    def _record(self):
+        raw = self.store.get(self.target.key)
+        if raw is None:
+            raise AuthError(f"No session; run `{self.login_command}`.")
+        try:
+            record = json.loads(raw)
+            if (
+                not isinstance(record.get("refresh_token"), str)
+                or not record["refresh_token"]
+                or not isinstance(record.get("subject"), str)
+                or not record["subject"]
+                or not isinstance(record.get("label"), str)
+            ):
+                raise ValueError()
+            record["created_at"] = float(record["created_at"])
+            if not math.isfinite(record["created_at"]):
+                raise ValueError()
+            return record
+        except (KeyError, ValueError, AttributeError, TypeError):
+            raise AuthError(f"Stored session is invalid; run `{self.login_command}` to replace it.") from None
+
+    def store_token_set(self, response, *, previous=None) -> dict:
+        """Check a token response against the target and save the session under the key's lock.
+
+        Returns {subject, label, created_at}. Raises AuthError, saving nothing, on any mismatch.
+        """
+        try:
+            value = response["id_token"]
+            claims = json.loads(base64.urlsafe_b64decode(value.split(".")[1] + "==="))
+            expected = self.target
+            if (
+                claims["iss"] != expected.issuer
+                or claims["aud"] != expected.client_id
+                or claims["token_use"] != "id"
+                or not claims["sub"]
+                or (previous and claims["sub"] != previous["subject"])
+                or float(claims["exp"]) <= self.clock()
+            ):
+                raise ValueError()
+            expires = min(float(claims["exp"]), self.clock() + float(response["expires_in"]))
+            if (
+                not math.isfinite(expires)
+                or not math.isfinite(float(response["expires_in"]))
+                or expires <= self.clock()
+            ):
+                raise ValueError()
+            refresh = response.get("refresh_token") or (previous or {}).get("refresh_token")
+            if not isinstance(refresh, str) or not refresh:
+                raise ValueError()
+        except (KeyError, ValueError, TypeError, IndexError, AttributeError):
+            raise AuthError(
+                "Provider token does not match the configured identity or client. No new session was saved."
+            ) from None
+        # Tokens arrive only from the configured TLS token endpoint; the API verifies signature and
+        # permissions. Local decoded claims are display and binding only.
+        record = {
+            "subject": claims["sub"],
+            "label": str(claims.get("email") or claims["sub"]),
+            "refresh_token": refresh,
+            "created_at": (previous or {}).get("created_at", self.clock()),
+        }
+        with self._hold():
+            self.store.set(self.target.key, json.dumps(record))
+        self._token, self._expires, self._subject = value, expires, record["subject"]
+        return {"subject": record["subject"], "label": record["label"], "created_at": record["created_at"]}
+
+    def login(self) -> dict:
+        """Local browser sign-in on the target's loopback callback."""
+        if not self.target.has_loopback_callback:
+            raise AuthError("Local sign-in needs a loopback callback; this target's callback is not one.")
+        state = secrets.token_urlsafe(32)
+        verifier, challenge = pkce_pair()
+        url = authorization_url(self.target, state=state, challenge=challenge, identity_provider=self.identity_provider)
+        code = self.receive(self.target.callback_uri, url, state, 180.0)
+        with self._hold():
+            response = self.provider.post(
+                self.target.token_endpoint,
+                {
+                    "grant_type": "authorization_code",
+                    "client_id": self.target.client_id,
+                    "code": code,
+                    "redirect_uri": self.target.callback_uri,
+                    "code_verifier": verifier,
+                },
+            )
+            return self.store_token_set(response)
+
+    def headers(self, endpoint):
+        if endpoint != self.target.api_endpoint:
+            raise AuthError("Endpoint does not match the signed-in target; sign in to the target that owns it.")
+        with self._hold():
+            record = self._record()  # Check even with a cached access token: local logout must win.
+            if self._subject is not None and self._subject != record["subject"]:
+                self._token = None  # Another process explicitly signed in as a different person.
+            if not self._token or self._expires <= self.clock() + 60:
+                try:
+                    response = self.provider.post(
+                        self.target.token_endpoint,
+                        {
+                            "grant_type": "refresh_token",
+                            "client_id": self.target.client_id,
+                            "refresh_token": record["refresh_token"],
+                        },
+                    )
+                except OAuthError as error:
+                    if error.code == "invalid_grant":
+                        self.store.delete(self.target.key)
+                        self._token = None
+                    raise OAuthError(error.code, transient=error.transient, login_command=self.login_command) from None
+                self.store_token_set(response, previous=record)
+            return {"content-type": "application/json", "Authorization": self._token}
+
+    def status(self) -> dict:
+        try:
+            record = self._record()
+        except AuthError:
+            # Locked or unavailable stores stay errors, never a fabricated signed-out state.
+            if self.store.get(self.target.key) is not None:
+                raise
+            return {"signed_in": False}
+        return {
+            "signed_in": True,
+            "subject": record["subject"],
+            "label": record["label"],
+            "access_expires_at": self._expires or None,
+            "elapsed_session_seconds": max(0, self.clock() - record["created_at"]),
+        }
+
+    def logout(self) -> dict:
+        remote = "not_needed"
+        with self._hold():
+            raw = self.store.get(self.target.key)
+            try:
+                if raw:
+                    remote = "unconfirmed"
+                    record = self._record()
+                    self.provider.post(
+                        self.target.revoke_endpoint,
+                        {"client_id": self.target.client_id, "token": record["refresh_token"]},
+                    )
+                    remote = "confirmed"
+            except AuthError:
+                pass
+            finally:
+                self.store.delete(self.target.key)
+                self._token = None
+                self._expires = 0.0
+        # An access token the API already accepted stays valid until it expires.
+        return {"local_session_removed": True, "remote_revocation": remote}

cli_login/stores/__init__.py

@@ -0,0 +1,122 @@
+"""Secure session stores. Choosing one fails closed; there is no plaintext fallback.
+
+Order of choice:
+- macOS: the Keychain.
+- Linux: Secret Service, then the kernel keyring, then a running memory agent.
+- Windows: Credential Manager.
+
+Set ``CLI_LOGIN_STORE`` (or pass ``backend=``) to one of ``keychain``, ``secret-service``,
+``kernel-keyring``, ``agent`` or ``credential-manager`` to choose explicitly. Any other value, a file or
+plaintext included, is refused. Backends load lazily so importing the package needs no optional dependency.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ..errors import AuthError, StoreUnavailable
+from ..target import Target
+
+ENV_STORE = "CLI_LOGIN_STORE"
+
+
+def _keychain(target, state_dir, environ):
+    from .macos import MacOSKeychainStore
+
+    return MacOSKeychainStore(target.namespace)
+
+
+def _secret_service(target, state_dir, environ):
+    from .secret_service import SecretServiceStore
+
+    return SecretServiceStore(target.namespace)
+
+
+def _kernel_keyring(target, state_dir, environ):
+    from .kernel_keyring import KernelKeyringStore
+
+    return KernelKeyringStore(target.namespace)
+
+
+def _agent(target, state_dir, environ):
+    from .agent import AgentStore
+
+    return AgentStore(target.namespace, state_dir=state_dir, environ=environ)
+
+
+def _credential_manager(target, state_dir, environ):
+    from .windows import WindowsCredentialStore
+
+    return WindowsCredentialStore(target.namespace)
+
+
+# name -> (factory, platform prefix). Tests may replace entries.
+BACKENDS = {
+    "keychain": (_keychain, "darwin"),
+    "secret-service": (_secret_service, "linux"),
+    "kernel-keyring": (_kernel_keyring, "linux"),
+    "agent": (_agent, ("linux", "darwin")),
+    "credential-manager": (_credential_manager, "win32"),
+}
+DEFAULT_ORDER = {
+    "darwin": ["keychain"],
+    "linux": ["secret-service", "kernel-keyring", "agent"],
+    "win32": ["credential-manager"],
+}
+
+
+def _supported(name: str, platform: str) -> bool:
+    return platform.startswith(BACKENDS[name][1])
+
+
+def _try(name, target, state_dir, environ):
+    store = BACKENDS[name][0](target, state_dir, environ)
+    if hasattr(store, "probe"):
+        store.probe()
+    return store
+
+
+def _guidance(target: Target, reasons: list[tuple[str, str]], state_dir) -> AuthError:
+    from .agent import agent_command
+
+    lines = ["No secure credential store is available on this machine."]
+    lines += [f"- {name}: {reason}" for name, reason in reasons]
+    lines.append(
+        f"On a cloud machine, start the memory agent: {agent_command(target.namespace, state_dir=state_dir)} "
+        "then sign in again. Elsewhere, install the Linux extra "
+        '(pip install "cli-login[linux]") and unlock your desktop keyring. '
+        "Plaintext storage is never used."
+    )
+    return AuthError("\n".join(lines))
+
+
+def open_store(target: Target, *, backend: str | None = None, state_dir=None, environ=None, platform: str | None = None):
+    """The secure store for this machine, or an AuthError that says exactly what to do."""
+    environ = os.environ if environ is None else environ
+    platform = platform or sys.platform
+    chosen = backend or environ.get(ENV_STORE) or None
+    if chosen:
+        if chosen not in BACKENDS:
+            raise AuthError(
+                f"Unknown credential store {chosen!r}; choose one of {', '.join(BACKENDS)}. "
+                "Plaintext storage is never used."
+            )
+        if not _supported(chosen, platform):
+            raise AuthError(f"The {chosen} store is not available on this platform.")
+        try:
+            return _try(chosen, target, state_dir, environ)
+        except StoreUnavailable as error:
+            raise AuthError(str(error)) from None
+    order = next((names for prefix, names in DEFAULT_ORDER.items() if platform.startswith(prefix)), None)
+    if order is None:
+        raise AuthError("No secure credential store is available on this platform; plaintext storage is never used.")
+    reasons = []
+    for name in order:
+        try:
+            return _try(name, target, state_dir, environ)
+        except StoreUnavailable as error:
+            reasons.append((name, str(error)))
+    if platform.startswith("linux"):
+        raise _guidance(target, reasons, state_dir)
+    raise AuthError("\n".join(["No secure credential store is available."] + [f"- {n}: {r}" for n, r in reasons]))