libre-devops-helpers 0.4.1__py3-none-any.whl

libre_devops_helpers/core/auth.py

@@ -0,0 +1,103 @@
+"""Access tokens and token providers.
+
+A token provider is anything with ``get_token(resource, tenant_id)``. Each vendor layer
+supplies its own credentials (``microsoft.auth`` for Entra ID), and its service modules
+accept any provider, so none of them depends on where a token comes from.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Protocol
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True)
+class AccessToken:
+    """A bearer token. ``token`` is left out of repr so it cannot leak into logs."""
+
+    token: str = field(repr=False)
+    expires_on: datetime
+    tenant_id: str
+    resource: str
+
+    def expires_within(self, window: timedelta, *, now: datetime | None = None) -> bool:
+        """True when the token expires within ``window`` of ``now``."""
+        return self.expires_on - (now or utc_now()) <= window
+
+
+class TokenProvider(Protocol):
+    """Anything that can produce an access token for a resource in a tenant."""
+
+    def get_token(self, resource: str, tenant_id: str) -> AccessToken:
+        """An access token for ``resource`` in ``tenant_id``."""
+
+
+class CachingTokenProvider:
+    """Wraps a provider and reuses each token until it is close to expiry.
+
+    The cache is in memory only; tokens are never written to disk. It is safe to share
+    between threads, and a token is fetched once even when several threads ask at once.
+    """
+
+    def __init__(
+        self,
+        inner: TokenProvider,
+        *,
+        refresh_before: timedelta = timedelta(minutes=5),
+        clock: Callable[[], datetime] = utc_now,
+    ) -> None:
+        self._inner = inner
+        self._refresh_before = refresh_before
+        self._clock = clock
+        self._cache: dict[tuple[str, str], AccessToken] = {}
+        self._lock = threading.Lock()
+
+    def get_token(self, resource: str, tenant_id: str) -> AccessToken:
+        key = (resource, tenant_id.lower())
+        with self._lock:
+            cached = self._cache.get(key)
+            if cached is None or cached.expires_within(self._refresh_before, now=self._clock()):
+                cached = self._inner.get_token(resource, tenant_id)
+                self._cache[key] = cached
+            return cached
+
+    def invalidate(self, resource: str, tenant_id: str) -> None:
+        """Forget the cached token, so the next request fetches a new one."""
+        with self._lock:
+            self._cache.pop((resource, tenant_id.lower()), None)
+
+
+class BearerToken:
+    """A current bearer token each time it is called, as ApiClient expects.
+
+    ``refresh`` drops the provider's cached token (when it caches), so the next call
+    fetches a new one. ApiClient calls it once when an API answers 401.
+    """
+
+    def __init__(self, provider: TokenProvider, resource: str, tenant_id: str) -> None:
+        self._provider = provider
+        self._resource = resource
+        self._tenant_id = tenant_id
+
+    def __repr__(self) -> str:
+        return f"BearerToken(resource={self._resource!r}, tenant_id={self._tenant_id!r})"
+
+    def __call__(self) -> str:
+        return self._provider.get_token(self._resource, self._tenant_id).token
+
+    def refresh(self) -> None:
+        invalidate = getattr(self._provider, "invalidate", None)
+        if callable(invalidate):
+            invalidate(self._resource, self._tenant_id)
+
+
+def token_source(provider: TokenProvider, resource: str, tenant_id: str) -> BearerToken:
+    """A zero-argument callable returning a current bearer token, as ApiClient expects."""
+    return BearerToken(provider, resource, tenant_id)

libre_devops_helpers/core/brand.py

@@ -0,0 +1,67 @@
+"""Who this tool is, in one place.
+
+Every name the running tool shows or reads comes from here: its command, the prefix of
+its environment variables, its config directory, and how it introduces itself. To ship it
+under another name, run ``just rebrand``. That rewrites these values together with the
+names no module can hold, such as the Python package name in every import; see
+``scripts/rebrand.py`` and ``brand.toml``.
+"""
+
+DISPLAY_NAME = "Libre DevOps Helpers"
+COMMAND = "ldo"
+# The name to install, from PyPI or a git URL.
+DISTRIBUTION = "libre-devops-helpers"
+ENV_PREFIX = "LDO"
+CONFIG_DIR = "ldo"
+REPOSITORY = "https://github.com/libre-devops/python-helpers"
+
+# The welcome banner, drawn after the Libre DevOps unicorn. Plain ASCII, so it renders in
+# any terminal and font. 'just rebrand --banner FILE' swaps it; --no-banner empties it.
+# banner-start
+BANNER = r"""
+     `.
+      `.`.
+        `. `.           |`.
+          `.  `.        |  `.
+           `.   `.      |  /
+             `.    `.   |   `.
+              `.    .'        `.
+                `..'        \    `.
+               .'             \    `.
+             .'   __           \     `.
+            .'     /           /       `.
+          .'                  /          `.
+        .'                    /            `.
+      .'  -                .-                `.
+      `.              .--''
+        `.       .--''    |
+          `._.-''         |
+                           |
+
+ _    ___ ___ ___ ___   ___  _____   _____  ___  ___
+| |  |_ _| _ ) _ \ __| |   \| __\ \ / / _ \| _ \/ __|
+| |__ | || _ \   / _|  | |) | _| \ V / (_) |  _/\__ \
+|____|___|___/_|_\___| |___/|___| \_/ \___/|_|  |___/
+"""
+# banner-end
+
+
+def env_var(name: str) -> str:
+    """The environment variable ``name`` under this tool's prefix, e.g. ``LDO_CONFIG``."""
+    return f"{ENV_PREFIX}_{name}"
+
+
+def command(text: str) -> str:
+    """A command line to suggest to the person, e.g. ``'ldo config init'``, quoted."""
+    return f"'{COMMAND} {text}'"
+
+
+def docs(page: str) -> str:
+    """The web address of a page in docs/, for a hint, e.g. ``docs("servicenow")``."""
+    return f"{REPOSITORY}/blob/main/docs/{page}.md"
+
+
+CONFIG_ENV = env_var("CONFIG")
+PROFILE_ENV = env_var("PROFILE")
+LOG_FORMAT_ENV = env_var("LOG_FORMAT")
+LOG_LEVEL_ENV = env_var("LOG_LEVEL")

libre_devops_helpers/core/browser.py

@@ -0,0 +1,21 @@
+"""Whether a browser can be opened here, decided as the Azure CLI decides it."""
+
+from __future__ import annotations
+
+import sys
+import webbrowser
+
+
+def can_launch_browser() -> bool:
+    """False on a Linux machine with no browser to open (a headless server, say).
+
+    Windows and macOS always have one. On Linux, a browser registered with Python's
+    webbrowser module (a desktop session, or BROWSER set) counts.
+    """
+    if not sys.platform.startswith("linux"):
+        return True
+    try:
+        webbrowser.get()
+    except webbrowser.Error:
+        return False
+    return True

libre_devops_helpers/core/config.py

@@ -0,0 +1,159 @@
+"""The config file: one TOML file, with a section per vendor.
+
+Its path is, in order: an explicit path, the ``LDO_CONFIG`` environment variable, then the
+platform config directory (``~/.config/ldo/config.toml`` on Linux and macOS, under
+``%APPDATA%`` on Windows). It lives outside any repository because it describes
+environments, not code, and it never holds a secret.
+
+The top level holds what every vendor shares (``ca_bundle``). Each vendor layer reads and
+validates its own section (``[microsoft]``, ...) with the field readers here, so every
+section rejects unknown keys and bad values the same way.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tomllib
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from libre_devops_helpers.core import brand
+from libre_devops_helpers.core.errors import ConfigError, ConfigNotFoundError
+from libre_devops_helpers.core.util import is_guid
+
+CONFIG_HEADER = f"""\
+# {brand.DISPLAY_NAME} ({brand.COMMAND}) configuration. Each vendor has its own section;
+# every key is described in {brand.docs("configuration")}
+#
+# Optional PEM bundle for a TLS-inspecting proxy, used for every HTTPS call. Without it,
+# SSL_CERT_FILE or the bundled CA list is used.
+# ca_bundle = "~/certs/proxy-ca.pem"
+"""
+
+_NAME = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+
+
+@dataclass(frozen=True)
+class ConfigFile:
+    """The parsed file: shared settings, plus each vendor's raw section."""
+
+    path: Path
+    data: Mapping[str, Any] = field(default_factory=dict)
+    ca_bundle: Path | None = None
+
+    def section(self, name: str) -> Mapping[str, Any] | None:
+        """A vendor's section, or None when the file has none."""
+        value = self.data.get(name)
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            raise ConfigError(f"{self.path}: [{name}] must be a table")
+        return value
+
+
+def default_config_path() -> Path:
+    """Where the config file lives when no explicit path is given."""
+    override = os.environ.get(brand.CONFIG_ENV)
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == "win32":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / brand.CONFIG_DIR / "config.toml"
+
+
+def load_config_file(
+    path: Path | None = None, *, sections: Iterable[str] | None = None
+) -> ConfigFile:
+    """Read and parse the config file. Raises ConfigNotFoundError when it is absent.
+
+    ``sections`` names the vendor sections that may appear; anything else at the top
+    level is then an error, so a typo fails loudly. None skips that check, for a library
+    caller that only knows its own vendor.
+    """
+    path = path or default_config_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise ConfigNotFoundError(
+            f"config file not found: {path}",
+            hint=f"create one with {brand.command('config init')}",
+        ) from None
+    except OSError as exc:
+        raise ConfigError(f"cannot read {path}: {exc}") from None
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path} is not valid TOML: {exc}") from None
+    return parse_config_file(data, path, sections=sections)
+
+
+def parse_config_file(
+    data: Mapping[str, Any], path: Path, *, sections: Iterable[str] | None = None
+) -> ConfigFile:
+    """Validate already-parsed TOML's shared settings."""
+    where = str(path)
+    if sections is not None:
+        reject_unknown(data, frozenset({"ca_bundle", *sections}), where)
+    ca_bundle = data.get("ca_bundle")
+    if ca_bundle is not None and not isinstance(ca_bundle, str):
+        raise ConfigError(f"{where}: ca_bundle must be a path string")
+    return ConfigFile(
+        path=path,
+        data=dict(data),
+        ca_bundle=Path(ca_bundle).expanduser() if ca_bundle else None,
+    )
+
+
+# Field readers for vendor sections --------------------------------------------------
+
+
+def check_name(name: str, where: str) -> None:
+    """Profile and instance names are lowercase, so they are easy to type and complete."""
+    if not _NAME.match(name):
+        raise ConfigError(f"{where}: use lowercase letters, digits, '-' and '_' in names")
+
+
+def table(value: object, where: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{where}: expected a table")
+    return value
+
+
+def guid(data: Mapping[str, Any], key: str, where: str) -> str | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not is_guid(value):
+        raise ConfigError(f"{where}: {key} must be a GUID, got {value!r}")
+    return value.strip().lower()
+
+
+def text(data: Mapping[str, Any], key: str, where: str) -> str | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(f"{where}: {key} must be a string")
+    return value.strip()
+
+
+def https_url(data: Mapping[str, Any], key: str, where: str) -> str | None:
+    # Tokens are attached to every request, so plain http is never acceptable.
+    value = text(data, key, where)
+    if value is not None and not value.startswith("https://"):
+        raise ConfigError(f"{where}: {key} must be an https:// URL")
+    return value.rstrip("/") if value else None
+
+
+def reject_unknown(data: Mapping[str, Any], allowed: frozenset[str], where: str) -> None:
+    unknown = sorted(set(data) - allowed)
+    if unknown:
+        raise ConfigError(
+            f"{where}: unknown key(s) {', '.join(unknown)} (allowed: {', '.join(sorted(allowed))})"
+        )

libre_devops_helpers/core/dpapi.py

@@ -0,0 +1,60 @@
+"""Encrypt bytes for the signed-in Windows account with DPAPI, through ctypes.
+
+``CryptProtectData`` ties the result to the Windows account (and this machine), so only
+that account can decrypt it; the brand name is mixed in as extra entropy, so another
+program running as the same account cannot decrypt it by asking DPAPI alone. Windows
+only: the Windows CI job tests it.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from collections.abc import Callable
+from typing import Any
+
+from libre_devops_helpers.core import brand
+
+_ENTROPY = f"{brand.COMMAND} refresh tokens".encode()
+_UI_FORBIDDEN = 0x01  # never show a prompt
+
+
+class _Blob(ctypes.Structure):
+    _fields_ = [("size", ctypes.c_uint32), ("data", ctypes.POINTER(ctypes.c_char))]
+
+
+def protect(data: bytes) -> bytes:  # pragma: no cover - Windows only
+    """``data`` encrypted for the current Windows account."""
+    return _crypt(_library("crypt32").CryptProtectData, data)
+
+
+def unprotect(data: bytes) -> bytes:  # pragma: no cover - Windows only
+    """``data`` decrypted; OSError when it was encrypted for another account."""
+    return _crypt(_library("crypt32").CryptUnprotectData, data)
+
+
+def _library(name: str) -> Any:  # pragma: no cover - Windows only
+    # use_last_error keeps the call's error code, which a later call could overwrite.
+    return ctypes.WinDLL(name, use_last_error=True)  # type: ignore[attr-defined]
+
+
+def _crypt(function: Callable[..., Any], data: bytes) -> bytes:  # pragma: no cover - Windows
+    source = ctypes.create_string_buffer(data, len(data))
+    entropy = ctypes.create_string_buffer(_ENTROPY, len(_ENTROPY))
+    blob_in = _Blob(len(data), ctypes.cast(source, ctypes.POINTER(ctypes.c_char)))
+    blob_entropy = _Blob(len(_ENTROPY), ctypes.cast(entropy, ctypes.POINTER(ctypes.c_char)))
+    blob_out = _Blob()
+    # Both functions take (in, description, entropy, reserved, prompt, flags, out).
+    if not function(
+        ctypes.byref(blob_in),
+        None,
+        ctypes.byref(blob_entropy),
+        None,
+        None,
+        _UI_FORBIDDEN,
+        ctypes.byref(blob_out),
+    ):
+        raise ctypes.WinError(ctypes.get_last_error())  # type: ignore[attr-defined]
+    try:
+        return ctypes.string_at(blob_out.data, blob_out.size)
+    finally:
+        _library("kernel32").LocalFree(blob_out.data)

libre_devops_helpers/core/errors.py

@@ -0,0 +1,90 @@
+"""Exception types raised by this package.
+
+Library code raises these and never exits the process. Only the ``cli`` subpackage
+turns them into messages and exit codes, so importing code keeps control of its flow.
+"""
+
+from __future__ import annotations
+
+
+class LdoError(Exception):
+    """Base class for every error this package raises.
+
+    ``hint`` is an optional next step for the person running the command.
+    """
+
+    exit_code = 1
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.hint = hint
+
+
+class ConfigError(LdoError):
+    """The config file is invalid, or a profile cannot be used."""
+
+
+class ConfigNotFoundError(ConfigError):
+    """The config file does not exist."""
+
+
+class InputError(LdoError):
+    """A list of names, a file of names, or a duration could not be read."""
+
+
+class CommandError(LdoError):
+    """An external command line tool is missing, or a command it ran failed."""
+
+
+class AuthError(LdoError):
+    """A credential could not produce an access token."""
+
+
+class ReauthRequired(AuthError):
+    """A sign-in has lapsed, and only a person signing in again can renew it.
+
+    Retrying does not help: the refresh token behind the session has expired or been
+    revoked, or a policy wants a fresh sign-in. ``reason`` says which, in plain words.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        tenant_id: str | None = None,
+        reason: str | None = None,
+    ) -> None:
+        super().__init__(message, hint=hint)
+        self.tenant_id = tenant_id
+        self.reason = reason
+
+
+class TokenError(LdoError):
+    """A token could not be decoded."""
+
+
+class NotFoundError(LdoError):
+    """A named object does not exist."""
+
+
+class AmbiguousError(LdoError):
+    """A name matched more than one object where exactly one was needed."""
+
+
+class ApiError(LdoError):
+    """An HTTP API call failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        hint: str | None = None,
+    ) -> None:
+        super().__init__(message, hint=hint)
+        self.status = status
+        self.code = code
+        self.request_id = request_id