cli-login 0.1.0__py3-none-any.whl

cli_login/broker/transactions.py

@@ -0,0 +1,201 @@
+"""Remote sign-in transactions: create once, change state conditionally, hand the code over exactly once.
+
+Two stores share one interface: ``MemoryTransactions`` for specs and local runs, and ``DynamoTransactions`` for the
+deployed broker, whose table expires items through TTL on ``expires_at``. Every change is conditional on the state
+it expects, so two callers racing for the same transition cannot both win.
+"""
+
+from __future__ import annotations
+
+import copy
+import threading
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+PENDING, BOUND, APPROVED, DENIED = "pending", "bound", "approved", "denied"
+STATES = (PENDING, BOUND, APPROVED, DENIED)
+
+
+class MemoryTransactions:
+    """In-process store with the same conditional semantics as the DynamoDB one."""
+
+    def __init__(self):
+        self._items: dict[str, dict[str, Any]] = {}
+        self._lock = threading.Lock()
+
+    def create(self, item: Mapping[str, Any]) -> bool:
+        with self._lock:
+            if item["id"] in self._items:
+                return False
+            self._items[item["id"]] = dict(item)
+            return True
+
+    def get(self, transaction_id: str) -> dict[str, Any] | None:
+        with self._lock:
+            item = self._items.get(transaction_id)
+            return copy.deepcopy(item) if item else None
+
+    def transition(
+        self,
+        transaction_id: str,
+        from_states: Iterable[str],
+        changes: Mapping[str, Any],
+        *,
+        expect: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """Apply ``changes`` only when the state is one of ``from_states`` and every ``expect`` field matches."""
+        with self._lock:
+            item = self._items.get(transaction_id)
+            if item is None or item["state"] not in tuple(from_states):
+                return None
+            if any(item.get(key) != value for key, value in (expect or {}).items()):
+                return None
+            item.update(changes)
+            return copy.deepcopy(item)
+
+    def take(self, transaction_id: str) -> dict[str, Any] | None:
+        """Delete an approved transaction and return it; None when it is not approved or another caller took it."""
+        with self._lock:
+            item = self._items.get(transaction_id)
+            if item is None or item["state"] != APPROVED or not item.get("code"):
+                return None
+            return self._items.pop(transaction_id)
+
+    def count(self, key: str, now: int, window_seconds: int) -> int:
+        """Count one call against ``key`` in the current window and return the window's total."""
+        window = now // window_seconds
+        with self._lock:
+            counter = self._items.setdefault(f"rate#{key}#{window}", {"count": 0})
+            counter["count"] += 1
+            return counter["count"]
+
+
+def _failed_condition(error: Exception) -> bool:
+    # The client's ConditionalCheckFailedException, recognised by its code so no AWS import is needed.
+    response = getattr(error, "response", None) or {}
+    return (response.get("Error") or {}).get("Code") == "ConditionalCheckFailedException"
+
+
+def _encode(value: Any) -> dict[str, Any]:
+    if isinstance(value, bool):
+        return {"BOOL": value}
+    if isinstance(value, int):
+        return {"N": str(value)}
+    if isinstance(value, str):
+        return {"S": value}
+    if value is None:
+        return {"NULL": True}
+    if isinstance(value, Mapping):
+        return {"M": {key: _encode(item) for key, item in value.items()}}
+    raise TypeError(f"unsupported attribute type {type(value).__name__}")
+
+
+def _decode(attribute: Mapping[str, Any]) -> Any:
+    (kind, value), = attribute.items()
+    if kind == "N":
+        return int(value)
+    if kind == "M":
+        return {key: _decode(item) for key, item in value.items()}
+    if kind == "NULL":
+        return None
+    return value
+
+
+def _item(raw: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    return {key: _decode(value) for key, value in raw.items() if key != "pk"}
+
+
+class DynamoTransactions:
+    """The deployed store: one table keyed by ``pk``, with TTL on ``expires_at``.
+
+    ``client`` is a low-level DynamoDB client (``boto3.client("dynamodb")``); specs pass a recording fake.
+    """
+
+    def __init__(self, client, table: str):
+        self.client = client
+        self.table = table
+
+    @staticmethod
+    def _key(transaction_id: str) -> dict[str, Any]:
+        return {"pk": {"S": "tx#" + transaction_id}}
+
+    def create(self, item: Mapping[str, Any]) -> bool:
+        try:
+            self.client.put_item(
+                TableName=self.table,
+                Item={**self._key(item["id"]), **{key: _encode(value) for key, value in item.items()}},
+                ConditionExpression="attribute_not_exists(pk)",
+            )
+            return True
+        except Exception as error:
+            if _failed_condition(error):
+                return False
+            raise
+
+    def get(self, transaction_id: str) -> dict[str, Any] | None:
+        result = self.client.get_item(TableName=self.table, Key=self._key(transaction_id), ConsistentRead=True)
+        return _item(result.get("Item"))
+
+    def transition(self, transaction_id, from_states, changes, *, expect=None):
+        names, values, sets = {"#state": "state"}, {}, []
+        for index, (key, value) in enumerate(changes.items()):
+            names[f"#c{index}"] = key
+            values[f":c{index}"] = _encode(value)
+            sets.append(f"#c{index} = :c{index}")
+        allowed = []
+        for index, state in enumerate(from_states):
+            values[f":s{index}"] = _encode(state)
+            allowed.append(f":s{index}")
+        conditions = [f"#state IN ({', '.join(allowed)})"]
+        for index, (key, value) in enumerate((expect or {}).items()):
+            names[f"#e{index}"] = key
+            if value is None:
+                conditions.append(f"attribute_not_exists(#e{index})")
+            else:
+                values[f":e{index}"] = _encode(value)
+                conditions.append(f"#e{index} = :e{index}")
+        try:
+            result = self.client.update_item(
+                TableName=self.table,
+                Key=self._key(transaction_id),
+                UpdateExpression="SET " + ", ".join(sets),
+                ConditionExpression="attribute_exists(pk) AND " + " AND ".join(conditions),
+                ExpressionAttributeNames=names,
+                ExpressionAttributeValues=values,
+                ReturnValues="ALL_NEW",
+            )
+        except Exception as error:
+            if _failed_condition(error):
+                return None
+            raise
+        return _item(result.get("Attributes"))
+
+    def take(self, transaction_id: str) -> dict[str, Any] | None:
+        try:
+            result = self.client.delete_item(
+                TableName=self.table,
+                Key=self._key(transaction_id),
+                ConditionExpression="#state = :approved AND attribute_exists(code)",
+                ExpressionAttributeNames={"#state": "state"},
+                ExpressionAttributeValues={":approved": _encode(APPROVED)},
+                ReturnValues="ALL_OLD",
+            )
+        except Exception as error:
+            if _failed_condition(error):
+                return None
+            raise
+        return _item(result.get("Attributes"))
+
+    def count(self, key: str, now: int, window_seconds: int) -> int:
+        window = now // window_seconds
+        result = self.client.update_item(
+            TableName=self.table,
+            Key={"pk": {"S": f"rate#{key}#{window}"}},
+            UpdateExpression="ADD #count :one SET expires_at = if_not_exists(expires_at, :expires)",
+            ExpressionAttributeNames={"#count": "count"},
+            ExpressionAttributeValues={":one": {"N": "1"}, ":expires": {"N": str((window + 2) * window_seconds)}},
+            ReturnValues="UPDATED_NEW",
+        )
+        return int(result["Attributes"]["count"]["N"])

cli_login/errors.py

@@ -0,0 +1,29 @@
+"""Error types. Messages never carry token values or provider payloads."""
+
+from __future__ import annotations
+
+
+class AuthError(ValueError):
+    """A safe, operator-facing message; never include provider payloads or secrets."""
+
+
+class StoreUnavailable(AuthError):
+    """A secure store cannot be used here (absent, locked or blocked).
+
+    Choosing a store moves on to the next candidate; the message is the recovery guidance and never carries a
+    secret or a backend's raw text.
+    """
+
+
+class OAuthError(AuthError):
+    """The provider refused or could not serve a token request."""
+
+    def __init__(self, code: str, *, transient: bool = False, login_command: str | None = None):
+        self.code = code
+        self.transient = transient
+        login = login_command or "login"
+        super().__init__(
+            "Sign-in provider temporarily unavailable; retry later."
+            if transient
+            else f"Session expired or was revoked; run `{login}`."
+        )

cli_login/locks.py

@@ -0,0 +1,111 @@
+"""Per-key process locks, on POSIX (``flock``) and on Windows (``msvcrt.locking``).
+
+One lock file per stored key, ``session-<key>.lock`` in the private state directory. There is no global lock:
+different keys never block each other.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import re
+import sys
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+from .errors import AuthError
+
+_SAFE = re.compile(r"[A-Za-z0-9._-]{1,200}")
+
+
+def default_state_dir(namespace: str) -> Path:
+    return Path.home() / ".config" / "cli-login" / namespace
+
+
+def ensure_state_dir(path: Path) -> Path:
+    """Create the private (0700) metadata directory, refusing a symlink."""
+    path = Path(path)
+    if path.is_symlink():
+        raise AuthError("CLI session metadata directory must not be a symlink.")
+    try:
+        path.mkdir(mode=0o700, parents=True, exist_ok=True)
+        path.chmod(0o700)
+    except OSError:
+        raise AuthError("Unable to access private CLI session metadata; check directory permissions.") from None
+    return path
+
+
+def _lock_posix(fd: int) -> None:
+    import fcntl
+
+    fcntl.flock(fd, fcntl.LOCK_EX)
+
+
+def _unlock_posix(fd: int) -> None:
+    import fcntl
+
+    fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+def _lock_windows(fd: int) -> None:
+    """Lock byte 0 of the file, waiting without a deadline.
+
+    ``LK_LOCK`` gives up after ten seconds, so poll the non-blocking form with a short, growing sleep.
+    """
+    import msvcrt
+
+    delay = 0.005
+    while True:
+        os.lseek(fd, 0, os.SEEK_SET)
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            return
+        except OSError as error:
+            if error.errno not in (errno.EACCES, errno.EDEADLK):
+                raise
+        time.sleep(delay)
+        delay = min(delay * 2, 0.1)
+
+
+def _unlock_windows(fd: int) -> None:
+    import msvcrt
+
+    os.lseek(fd, 0, os.SEEK_SET)
+    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+
+
+if sys.platform == "win32":
+    _lock, _unlock = _lock_windows, _unlock_windows
+else:
+    _lock, _unlock = _lock_posix, _unlock_posix
+
+
+@contextmanager
+def key_lock(state_dir: Path, key: str):
+    """Hold an exclusive lock for one stored key, never a global lock."""
+    if not _SAFE.fullmatch(key or ""):
+        raise AuthError("Invalid lock key.")
+    path = ensure_state_dir(state_dir) / ("session-" + key + ".lock")
+    if path.is_symlink():
+        raise AuthError("The CLI session lock must not be a symlink.")
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    except OSError:
+        raise AuthError("Unable to open the private CLI session lock; check directory permissions.") from None
+    try:
+        try:
+            _lock(fd)
+        except OSError:
+            raise AuthError(
+                "Unable to lock the CLI session safely; retry after checking directory permissions."
+            ) from None
+        try:
+            yield
+        finally:
+            try:
+                _unlock(fd)
+            except OSError:
+                pass  # closing the descriptor releases the lock
+    finally:
+        os.close(fd)

cli_login/oauth.py

@@ -0,0 +1,143 @@
+"""PKCE, the authorization URL, the loopback callback receiver and the HTTP provider."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+from .errors import AuthError, OAuthError
+from .target import Target, https_url
+
+
+def pkce_pair() -> tuple[str, str]:
+    """A fresh (verifier, S256 challenge) pair."""
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=")
+    return verifier, challenge
+
+
+def authorization_url(
+    target: Target,
+    *,
+    state: str,
+    challenge: str,
+    identity_provider: str | None = None,
+    scope: str = "openid email profile",
+) -> str:
+    fields = {
+        "response_type": "code",
+        "client_id": target.client_id,
+        "redirect_uri": target.callback_uri,
+        "scope": scope,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    if identity_provider:
+        fields["identity_provider"] = identity_provider
+    return target.authorize_endpoint + "?" + urllib.parse.urlencode(fields)
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+class HTTPProvider:
+    """Posts form fields to the configured provider. Redirects are refused: secrets go nowhere else."""
+
+    def post(self, url: str, fields: dict[str, str]) -> dict[str, Any]:
+        https_url(url, "OAuth endpoint")
+        request = urllib.request.Request(
+            url,
+            data=urllib.parse.urlencode(fields).encode(),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            method="POST",
+        )
+        try:
+            opener = urllib.request.build_opener(_NoRedirect())
+            with opener.open(request, timeout=20) as response:
+                raw = response.read(1024 * 1024)
+            return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as error:
+            try:
+                code = json.loads(error.read(4096)).get("error")
+            except (ValueError, AttributeError):
+                code = None
+            if code == "invalid_grant":
+                raise OAuthError("invalid_grant") from None
+            if error.code == 429 or error.code >= 500:
+                raise OAuthError("temporarily_unavailable", transient=True) from None
+            raise AuthError(
+                "OAuth request rejected. Check the registered client and callback configuration; no provider payload was logged."
+            ) from None
+        except (OSError, urllib.error.URLError):
+            raise OAuthError("temporarily_unavailable", transient=True) from None
+        except (ValueError, TypeError):
+            raise AuthError(
+                "Sign-in provider returned an invalid response; retry without discarding your session."
+            ) from None
+
+
+def receive_code(callback_uri: str, authorization_url: str, state: str, timeout: float) -> str:
+    """Open the browser and wait for the one authorization code on the loopback callback."""
+    callback = urllib.parse.urlsplit(callback_uri)
+    outcome: dict[str, str] = {}
+
+    class Callback(BaseHTTPRequestHandler):
+        def log_message(self, *args):
+            pass  # The request URL contains the authorization code.
+
+        def do_GET(self):
+            parsed = urllib.parse.urlsplit(self.path)
+            query = urllib.parse.parse_qs(parsed.query)
+            valid = (
+                parsed.path == (callback.path or "/")
+                and query.get("state") == [state]
+                and ((len(query.get("code", [])) == 1 and bool(query["code"][0])) or len(query.get("error", [])) == 1)
+            )
+            self.send_response(200 if valid else 400)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(
+                b"Sign-in response received. You may close this page." if valid else b"Invalid sign-in response."
+            )
+            if valid:
+                outcome.update(code=query.get("code", [""])[0], error="denied" if query.get("error") else "")
+
+    class CallbackServer(HTTPServer):
+        def get_request(self):
+            connection, address = super().get_request()
+            connection.settimeout(min(5, timeout))
+            return connection, address
+
+    try:
+        # Never resolve the registered host to pick an interface, and never bind a wildcard.
+        server = CallbackServer(("127.0.0.1", callback.port), Callback)
+    except OSError:
+        raise AuthError(
+            f"Sign-in needs local port {callback.port} for its callback, but it is already in use. "
+            "Stop whatever is using it and run the login again."
+        ) from None
+    with server:
+        server.timeout = min(0.25, timeout)
+        if not webbrowser.open(authorization_url):
+            raise AuthError("Could not open the system browser. Run the login in an interactive desktop session.")
+        deadline = time.monotonic() + timeout
+        while not outcome and time.monotonic() < deadline:
+            server.handle_request()
+    if not outcome:
+        raise AuthError("Sign-in timed out. Run the login again.")
+    if outcome.get("error") or not outcome.get("code"):
+        raise AuthError("Sign-in was declined. No session was saved.")
+    return outcome["code"]