multicloud-cli 0.1.0__py3-none-any.whl

multicloud_cli/auth.py

@@ -0,0 +1,547 @@
+"""``mctl auth``: keep the API key or the SSO session in the OS keyring, or in a 0600 file when no keyring works.
+
+No function here prints a key or a token. They leave this module only as return values
+(get_key, fresh_access_token)."""
+import contextlib
+import json
+import os
+import re
+import stat
+import sys
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+from urllib.parse import quote, urlparse
+
+import click
+import requests
+
+from . import config, exitcodes, sso
+
+try:
+    import fcntl
+except ImportError:  # Windows
+    fcntl = None
+try:
+    import msvcrt
+except ImportError:
+    msvcrt = None
+
+SERVICE = "multicloud-api-key"
+SSO_SERVICE = "multicloud-sso"
+TIMEOUT_S = 30
+REFRESH_SKEW_S = 60
+
+
+class AuthError(Exception):
+    pass
+
+
+def account(org: str) -> str:
+    return f"{org}/infra"
+
+
+def credentials_file() -> Path:
+    return config.config_dir() / "credentials"
+
+
+def _keyring():
+    """The keyring module, or None when it has no usable backend."""
+    try:
+        import keyring
+        from keyring.backends import fail
+        backend = keyring.get_keyring()
+        # keyrings.alt holds plaintext or weakly encrypted files: the 0600 file is no worse and is visible.
+        if isinstance(backend, fail.Keyring) or type(backend).__module__.startswith("keyrings.alt"):
+            return None
+        return keyring
+    except Exception:
+        return None
+
+
+def _read_file(path: Path, acct: str) -> Optional[str]:
+    if not path.exists():
+        return None
+    mode = stat.S_IMODE(path.stat().st_mode)
+    # Windows has no POSIX modes (chmod only sets read-only): the profile folder ACL protects the file there.
+    if os.name != "nt" and mode & 0o077:
+        raise AuthError(f"{path} can be read by other users (mode {mode:o}). Run: chmod 600 {path}")
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        raise AuthError(f"Could not read {path}.")
+    key = data.get(acct) if isinstance(data, dict) else None
+    return key or None
+
+
+def _load_secret(service: str, acct: str) -> Tuple[Optional[str], Optional[str]]:
+    """(value, source): the OS keyring first, then the credentials file."""
+    ring = _keyring()
+    if ring is not None:
+        try:
+            value = ring.get_password(service, acct)
+        except Exception:
+            value = None
+        if value:
+            return value, "OS keyring"
+    path = credentials_file()
+    value = _read_file(path, acct)
+    if value:
+        return value, f"file {path}"
+    return None, None
+
+
+def get_key(org: str) -> Tuple[Optional[str], Optional[str]]:
+    """(key, source). Order: environment, OS keyring, credentials file."""
+    key = os.environ.get("MULTICLOUD_API_KEY")
+    if key:
+        return key, "environment"
+    return _load_secret(SERVICE, account(org))
+
+
+def _write_file(acct: str, key: Optional[str]) -> bool:
+    """Set (or remove, when key is None) one entry. Returns whether an entry was present or written."""
+    path = credentials_file()
+    data = {}
+    if path.exists():
+        _read_file(path, acct)  # refuses a loose mode
+        try:
+            data = json.loads(path.read_text())
+        except (OSError, ValueError):
+            data = {}
+    had = acct in data
+    if key is None:
+        if not had:
+            return False
+        del data[acct]
+    else:
+        data[acct] = key
+    config.ensure_private_dir(strict=True)
+    # A temp file and a rename: a crash or a second login never leaves a cut-off file.
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(json.dumps(data))
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+    os.chmod(path, 0o600)
+    return True
+
+
+def _store_secret(service: str, acct: str, value: str) -> str:
+    """Store one secret. Returns where: 'OS keyring' or 'file <path>'."""
+    ring = _keyring()
+    if ring is not None:
+        try:
+            ring.set_password(service, acct, value)
+            return "OS keyring"
+        except Exception:
+            # The keyring is read first: an old entry there would hide the value in the file.
+            try:
+                ring.delete_password(service, acct)
+            except Exception:
+                pass
+    _write_file(acct, value)
+    return f"file {credentials_file()}"
+
+
+def _delete_secret(service: str, acct: str) -> list:
+    """Remove one secret from both places. Returns where it was removed from."""
+    removed = []
+    ring = _keyring()
+    if ring is not None:
+        try:
+            if ring.get_password(service, acct):
+                ring.delete_password(service, acct)
+                removed.append("OS keyring")
+        except Exception:
+            pass
+    if _write_file(acct, None):
+        removed.append(f"file {credentials_file()}")
+    return removed
+
+
+def store_key(org: str, key: str) -> str:
+    """Store the key. Returns where: 'OS keyring' or 'file <path>'."""
+    return _store_secret(SERVICE, account(org), key)
+
+
+def delete_key(org: str) -> list:
+    """Remove the key from both places. Returns where it was removed from."""
+    return _delete_secret(SERVICE, account(org))
+
+
+def sso_account(issuer: str, part: str) -> str:
+    return f"{issuer}#{part}"
+
+
+def store_sso(issuer: str, tokens: sso.Tokens) -> str:
+    """Store the refresh token, then the access token. Two entries: one keyring entry is small on some systems."""
+    where = _store_secret(SSO_SERVICE, sso_account(issuer, "refresh"), tokens.refresh)
+    _store_secret(SSO_SERVICE, sso_account(issuer, "access"), tokens.access)
+    return where
+
+
+def load_sso(issuer: str) -> Optional[sso.Tokens]:
+    refresh, _ = _load_secret(SSO_SERVICE, sso_account(issuer, "refresh"))
+    if not refresh:
+        return None
+    access, _ = _load_secret(SSO_SERVICE, sso_account(issuer, "access"))
+    return sso.Tokens(access=access or "", refresh=refresh)
+
+
+def sso_source(issuer: str) -> Optional[str]:
+    return _load_secret(SSO_SERVICE, sso_account(issuer, "refresh"))[1]
+
+
+def delete_sso(issuer: str) -> list:
+    removed = _delete_secret(SSO_SERVICE, sso_account(issuer, "refresh"))
+    for where in _delete_secret(SSO_SERVICE, sso_account(issuer, "access")):
+        if where not in removed:
+            removed.append(where)
+    return removed
+
+
+class SessionEnded(AuthError):
+    pass
+
+
+@contextlib.contextmanager
+def _refresh_lock():
+    """One refresh at a time across mctl processes. Keycloak may rotate the refresh token, and a refresh token
+    used twice ends the whole session, so two processes must not refresh from the same stored token."""
+    directory = config.ensure_private_dir()
+    fd = os.open(directory / ".refresh.lock", os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0), 0o600)
+    with os.fdopen(fd, "a+") as f:
+        if hasattr(os, "fchmod"):  # not on Windows
+            try:
+                os.fchmod(f.fileno(), 0o600)
+            except OSError as ex:  # another account's lock file: it holds no secret, so lock anyway
+                config.warn_once(f"cannot set {directory / '.refresh.lock'} to 0600 ({type(ex).__name__}).")
+        if fcntl is not None:
+            fcntl.flock(f, fcntl.LOCK_EX)
+        elif msvcrt is not None:  # pragma: no cover (Windows)
+            f.seek(0)
+            for attempt in range(6):  # LK_LOCK itself gives up after about 10 s
+                try:
+                    msvcrt.locking(f.fileno(), msvcrt.LK_LOCK, 1)
+                    break
+                except OSError:
+                    if attempt == 5:
+                        raise AuthError("Another mctl is refreshing the sign-in. Try again in a minute.")
+        try:
+            yield
+        finally:
+            if fcntl is not None:
+                fcntl.flock(f, fcntl.LOCK_UN)
+            elif msvcrt is not None:  # pragma: no cover (Windows)
+                f.seek(0)
+                msvcrt.locking(f.fileno(), msvcrt.LK_UNLCK, 1)
+
+
+def _valid(access: str) -> bool:
+    return bool(access) and sso.expires_at(access) - time.time() > REFRESH_SKEW_S
+
+
+def fresh_access_token(issuer: str, rejected: Optional[str] = None) -> str:
+    """The access token of the stored SSO session; refreshed when it expires within a minute, or when it is
+    the ``rejected`` one (the API answered 401). The refresh response may hold a new refresh token
+    (rotation): it replaces the old one, and is written before the access token."""
+    tokens = load_sso(issuer)
+    if tokens is None:
+        raise SessionEnded("You are not signed in. Run: mctl auth login")
+    if _valid(tokens.access) and tokens.access != rejected:
+        return tokens.access
+    with _refresh_lock():
+        # Another process may have refreshed while this one waited for the lock.
+        tokens = load_sso(issuer)
+        if tokens is None:
+            raise SessionEnded("You are not signed in. Run: mctl auth login")
+        if _valid(tokens.access) and tokens.access != rejected:
+            return tokens.access
+        try:
+            new = sso.refresh(issuer, tokens.refresh)
+        except sso.SsoError as ex:
+            if ex.code == "invalid_grant":
+                raise SessionEnded("Your session ended. Run: mctl auth login (or mctl auth logout --sso to use a stored API key)")
+            raise AuthError(str(ex))
+        try:
+            store_sso(issuer, new)
+        except AuthError as ex:
+            # The old refresh token may be dead already (rotation): say that the session was not saved.
+            raise AuthError(f"{ex} The refreshed sign-in could not be saved. Run: mctl auth login")
+        return new.access
+
+
+def check_key(org: str, api_url: str, key: str) -> Tuple[bool, str]:
+    """GET the list of cloud accounts with this key. Returns (ok, error text)."""
+    url = f"{api_url}/api/v1/orgs/{quote(org, safe='')}/cloud-accounts"
+    try:
+        r = requests.request("GET", url, timeout=TIMEOUT_S, headers={"X-API-Key": key},
+                             allow_redirects=False)
+    except requests.RequestException as ex:
+        return False, f"Could not reach the API: {type(ex).__name__}"
+    if r.status_code == 200:
+        return True, ""
+    return False, f"The API refused the key (HTTP {r.status_code})."
+
+
+def need_org(option: Optional[str]) -> str:
+    org = config.get_org(option)
+    if not org:
+        click.echo("Error: name the organization with --org or MULTICLOUD_ORG.", err=True)
+        sys.exit(1)
+    return org
+
+
+def _check_hosts(url: str, issuer: str) -> None:
+    for what, u in (("API", url), ("sign-in", issuer)):
+        host = urlparse(u).hostname or ""
+        if host not in ("localhost", "127.0.0.1", "::1") and host != "multicloud.io" \
+                and not host.endswith(".multicloud.io"):
+            click.echo(f"Warning: {u} is not a multicloud.io address. Your credentials go to that {what} host.", err=True)
+
+
+@click.group()
+def auth():
+    """Sign in with your browser, or store an API key, and check the result."""
+
+
+@auth.command()
+@click.option("--org", default=None, help="Organization slug (default: MULTICLOUD_ORG, saved, or the one in your sign-in)")
+@click.option("--api-url", default=None, help="API URL (default: MULTICLOUD_API_URL or saved)")
+@click.option("--issuer-url", default=None, help="Keycloak realm URL (default: MULTICLOUD_ISSUER_URL, saved, or auth.multicloud.io)")
+@click.option("--no-browser", is_flag=True, help="Sign in with a code on another device (for SSH and containers)")
+@click.option("--api-key", "use_key", is_flag=True, help="Store an API key instead of signing in with SSO")
+@click.option("--key-stdin", is_flag=True, help="Read the API key from one line of standard input (implies --api-key)")
+def login(org, api_url, issuer_url, no_browser, use_key, key_stdin):
+    """Sign in with SSO (browser), or with --api-key store a checked API key. Nothing secret is shown."""
+    try:
+        url = config.check_api_url(api_url) if api_url else config.get_api_url()
+        issuer = config.check_api_url(issuer_url, "issuer URL") if issuer_url else config.get_issuer()
+    except config.ConfigError as ex:
+        click.echo(f"Error: {ex} Nothing stored.", err=True)
+        sys.exit(1)
+    if use_key or key_stdin:
+        _login_key(org, url, key_stdin)
+        return
+    _check_hosts(url, issuer)
+    try:
+        tokens = (sso.login_device if no_browser else sso.login_browser)(
+            issuer, lambda text: click.echo(text, err=True))  # the URL and code are for the user, not for a pipe
+    except sso.SsoError as ex:
+        click.echo(f"Error: {ex}", err=True)
+        sys.exit(1)
+    orgs = sso.orgs_in_token(tokens.access)
+    org = config.get_org(org) if org else None
+    if org and org not in orgs:
+        listed = ", ".join(orgs) or "none"
+        click.echo(f"Error: you are not a member of '{org}' (your organizations: {listed}). Nothing stored.", err=True)
+        sys.exit(1)
+    probe = _probe(url, tokens.access, org or (orgs[0] if orgs else None))
+    if probe == 401:
+        click.echo("Error: the API did not accept this sign-in (HTTP 401). Nothing stored. "
+                   "Ask Multicloud support whether the API accepts the 'multicloud-cli' client.", err=True)
+        sys.exit(exitcodes.AUTH)
+    if probe is not None and probe != 200:
+        click.echo(f"Warning: the API answered HTTP {probe} to a test call. Check with: mctl auth status", err=True)
+    try:
+        where = store_sso(issuer, tokens)
+    except AuthError as ex:
+        click.echo(f"Error: {ex} Nothing stored.", err=True)
+        sys.exit(1)
+    config.save(org=org, api_url=api_url and url, issuer=issuer_url and issuer)
+    claims = sso.decode_claims(tokens.access)
+    who = claims.get("email") or claims.get("preferred_username") or "your account"
+    click.echo(f"Signed in as {who}. Session stored in {where}.")
+    if not orgs:
+        click.echo("Warning: your sign-in holds no organization. Ask an owner to add you.", err=True)
+    else:
+        click.echo(f"Organizations: {', '.join(orgs)}." + ("" if len(orgs) == 1 else " Name one with --org."))
+
+
+def _probe(url: str, access: str, org: Optional[str]) -> Optional[int]:
+    """One read with the new token, before it is stored. The HTTP status, or None when there is no answer or no
+    organization to ask about (a network problem must not block a sign-in)."""
+    if not org:
+        return None
+    try:
+        r = requests.request("GET", f"{url}/api/v1/orgs/{quote(org, safe='')}/pool-classes", timeout=TIMEOUT_S,
+                             headers={"Authorization": f"Bearer {access}"}, allow_redirects=False)
+    except requests.RequestException:
+        return None
+    return r.status_code
+
+
+def _key_exit_code(error: str) -> int:
+    """3 when the API refused the key (HTTP 401 or 403), else 1."""
+    m = re.search(r"refused the key \(HTTP (\d+)\)", error)
+    return exitcodes.for_status(int(m.group(1))) if m else exitcodes.ERROR
+
+
+def _login_key(org, url, key_stdin):
+    org = need_org(org)
+    host = urlparse(url).hostname or ""
+    if host not in ("localhost", "127.0.0.1", "::1") and host != "multicloud.io" \
+            and not host.endswith(".multicloud.io"):
+        click.echo(f"Warning: {url} is not a multicloud.io address. The key goes to that host.", err=True)
+    if key_stdin:
+        key = sys.stdin.readline()
+    else:
+        key = click.prompt("API key", hide_input=True)
+    key = key.strip()
+    if not key:
+        click.echo("Error: no API key given. Nothing stored.", err=True)
+        sys.exit(1)
+    ok, error = check_key(org, url, key)
+    if not ok:
+        click.echo(f"{error} Nothing stored.", err=True)
+        sys.exit(_key_exit_code(error))
+    try:
+        where = store_key(org, key)
+    except AuthError as ex:
+        click.echo(f"Error: {ex} Nothing stored.", err=True)
+        sys.exit(1)
+    config.save(org=org, api_url=url)
+    click.echo(f"Stored the API key for {org} in {where}. It can read the cloud accounts of {org}.")
+
+
+def _expiry_text(access: str) -> str:
+    exp = sso.expires_at(access)
+    if not exp:
+        return "unknown"
+    left = int(exp - time.time())
+    stamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(exp))
+    return f"{stamp} (in {left // 60} min)" if left > 0 else f"{stamp} (expired; refreshed on the next call)"
+
+
+@auth.command()
+@click.option("--org", default=None)
+@click.option("--json", "as_json", is_flag=True, help="Print method, api_url, org, orgs, expires and works as JSON")
+def status(org, as_json):
+    """Show how you are signed in and check that it works."""
+    say = lambda text: click.echo(text, err=as_json)  # noqa: E731
+    info = {"method": None, "api_url": None, "org": None, "orgs": [], "expires": None, "works": None}
+
+    def emit(works=None):
+        info["works"] = works
+        if as_json:
+            click.echo(json.dumps(info, indent=2, sort_keys=True))
+    try:
+        url = config.get_api_url()
+        issuer = config.get_issuer()
+    except config.ConfigError as ex:
+        click.echo(f"Error: {ex}", err=True)
+        sys.exit(1)
+    say(f"API URL: {url}")
+    info["api_url"] = url
+    slug = config.get_org(org)
+    info["org"] = slug
+    env_key = bool(os.environ.get("MULTICLOUD_API_KEY"))
+    try:
+        tokens = load_sso(issuer)
+        stored, source = get_key(slug) if slug and not env_key else (None, None)
+    except AuthError as ex:
+        click.echo(f"Error: {ex}", err=True)
+        sys.exit(1)
+    if env_key:
+        say("Method: API key from MULTICLOUD_API_KEY (wins over a stored sign-in)")
+        info["method"] = "api-key-env"
+    elif tokens:
+        say("Method: SSO")
+        info["method"] = "sso"
+    elif stored:
+        say(f"Method: API key from {source}")
+        info["method"] = "api-key"
+    else:
+        say("Method: none. Run: mctl auth login")
+        emit(False)
+        sys.exit(exitcodes.AUTH)
+    if tokens:
+        claims = sso.decode_claims(tokens.access)
+        say(f"SSO user: {claims.get('email') or claims.get('preferred_username') or 'unknown'}"
+            f" (stored in {sso_source(issuer)}; the refresh token is kept)")
+        say(f"Access token expires: {_expiry_text(tokens.access)}")
+        say(f"Organizations: {', '.join(sso.orgs_in_token(tokens.access)) or 'none'}")
+        info["orgs"] = sso.orgs_in_token(tokens.access)
+        exp = sso.expires_at(tokens.access)
+        info["expires"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(exp)) if exp else None
+    if tokens and not env_key:
+        if stored:
+            say(f"Stored API key for {slug}: {source} (not used while an SSO sign-in exists)")
+        orgs = sso.orgs_in_token(tokens.access)
+        explicit = config.org_is_explicit(org)
+        if len(orgs) > 1 and not explicit and slug not in orgs:
+            say("You are signed in, but no organization is chosen. To check an API call, name one: "
+                "mctl auth status --org <team-id> (save one with: mctl auth login --org <team-id>)")
+            info["org"] = None
+            emit()
+            return
+        from . import api  # api imports this module
+        try:
+            api.call("GET", org, "/pool-classes")
+        except api.ApiError as ex:
+            click.echo(f"The sign-in does not work: {ex}", err=True)
+            emit(False)
+            sys.exit(ex.exit_code)
+        say("The sign-in works.")
+        emit(True)
+        return
+    key = os.environ.get("MULTICLOUD_API_KEY") or stored
+    if not slug:
+        click.echo("Name the organization with --org or MULTICLOUD_ORG to check the key.", err=True)
+        emit()
+        sys.exit(1)
+    ok, error = check_key(slug, url, key)
+    if not ok:
+        click.echo(error, err=True)
+        emit(False)
+        sys.exit(_key_exit_code(error))
+    say("The key works.")
+    emit(True)
+
+
+@auth.command()
+@click.option("--org", default=None)
+@click.option("--sso", "only_sso", is_flag=True, help="Remove only the SSO sign-in")
+@click.option("--api-key", "only_key", is_flag=True, help="Remove only the stored API key")
+def logout(org, only_sso, only_key):
+    """End the SSO session at Keycloak and remove it, and remove the stored key.
+
+    The CLI shares the Keycloak browser session, so this signs you out of Keycloak in your browser too."""
+    do_sso, do_key = (only_sso or not only_key), (only_key or not only_sso)
+    try:
+        if do_sso:
+            try:
+                issuer = config.get_issuer()
+            except config.ConfigError as ex:
+                click.echo(f"Error: {ex}", err=True)
+                sys.exit(1)
+            tokens = load_sso(issuer)
+            if tokens:
+                try:
+                    sso.revoke(issuer, tokens.refresh)
+                    click.echo("Ended the session at the sign-in server.")
+                except sso.SsoError as ex:
+                    click.echo(f"Warning: could not end the session at the sign-in server ({ex}). "
+                               "It stays valid until it expires.", err=True)
+                click.echo(f"Removed the SSO sign-in from {', '.join(delete_sso(issuer)) or 'nowhere'}.")
+            elif only_sso:
+                click.echo("No SSO sign-in stored.")
+        if do_key:
+            slug = config.get_org(org)
+            if slug:
+                removed = delete_key(slug)
+                if removed:
+                    click.echo(f"Removed the API key for {slug} from {', '.join(removed)}.")
+                elif only_key:
+                    click.echo(f"No stored API key for {slug}.")
+            elif only_key:
+                click.echo("Error: name the organization with --org or MULTICLOUD_ORG.", err=True)
+                sys.exit(1)
+    except AuthError as ex:
+        click.echo(f"Error: {ex}", err=True)
+        sys.exit(1)