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

libre_devops_helpers/core/token_store.py

@@ -0,0 +1,266 @@
+"""Where a sign-in's refresh token is kept between commands: a profile's token_cache.
+
+Three choices, from safest to least guarded (profiles use ``file`` unless they say
+otherwise, since it works on a headless machine):
+
+- ``memory``: nowhere. The sign-in lasts one command and is gone after.
+- ``keychain``: the operating system's own store, locked to your account. Keychain on
+  macOS and the Secret Service (GNOME Keyring, KWallet) on Linux, through the optional
+  ``keyring`` package; on Windows, a file encrypted with DPAPI for your Windows account,
+  since Credential Manager's size limit is too small for a refresh token.
+- ``file`` (the default for profiles): a plaintext JSON file that only your account may
+  read (mode 0600), as the Azure CLI keeps its own tokens on Linux. Anyone who can act as
+  you, or as root, or who gets a copy of the file (a backup, say), can use what is in it.
+
+A refresh token is as good as a sign-in until it expires or is revoked, so a file that
+other accounts can read is refused rather than used, as ssh refuses a readable key.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import threading
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Protocol
+
+from libre_devops_helpers.core import brand
+from libre_devops_helpers.core.errors import AuthError, ConfigError
+
+log = logging.getLogger(__name__)
+
+TOKEN_CACHES = ("memory", "keychain", "file")
+# Where a profile keeps its sign-in unless it says otherwise: a private file, which works
+# on a headless machine as well as a desktop.
+DEFAULT_TOKEN_CACHE = "file"
+FILE_ENV = brand.env_var("TOKEN_CACHE")
+KEYCHAIN_SERVICE = f"{brand.COMMAND} sign-in"
+_KEYCHAIN_HINT = f"install the keychain extra: uv tool install '{brand.DISTRIBUTION}[keychain]'"
+
+
+class TokenStore(Protocol):
+    """Named secrets that outlast one command (or, for MemoryStore, do not)."""
+
+    def load(self, key: str) -> str | None:
+        """The value kept under ``key``, or None when there is none."""
+
+    def save(self, key: str, value: str) -> None:
+        """Keep ``value`` under ``key``, replacing what was there."""
+
+    def delete(self, key: str) -> bool:
+        """Forget ``key``. True when there was something to forget."""
+
+
+class MemoryStore:
+    """Kept in this process only: the default, and what every other store falls back to."""
+
+    def __init__(self) -> None:
+        self._values: dict[str, str] = {}
+        self._lock = threading.Lock()
+
+    def load(self, key: str) -> str | None:
+        with self._lock:
+            return self._values.get(key)
+
+    def save(self, key: str, value: str) -> None:
+        with self._lock:
+            self._values[key] = value
+
+    def delete(self, key: str) -> bool:
+        with self._lock:
+            return self._values.pop(key, None) is not None
+
+
+class FileStore:
+    """Values in one JSON file, private to your account, replaced whole on every write.
+
+    The directory is created 0700 and the file 0600, through a temporary file renamed
+    into place, so a crash never leaves half a file. With ``protect`` and ``unprotect``
+    (DPAPI on Windows) the file holds their encrypted bytes rather than plain JSON.
+    """
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        protect: Callable[[bytes], bytes] | None = None,
+        unprotect: Callable[[bytes], bytes] | None = None,
+    ) -> None:
+        self.path = path
+        self._protect = protect
+        self._unprotect = unprotect
+        self._lock = threading.Lock()
+
+    def load(self, key: str) -> str | None:
+        with self._lock:
+            entry = self._read().get(key)
+        value = entry.get("value") if isinstance(entry, dict) else None
+        return value if isinstance(value, str) and value else None
+
+    def save(self, key: str, value: str) -> None:
+        with self._lock:
+            data = self._read(refuse_exposed=False)
+            data[key] = {"value": value, "saved": datetime.now(UTC).isoformat(timespec="seconds")}
+            self._write(data)
+
+    def delete(self, key: str) -> bool:
+        with self._lock:
+            data = self._read(refuse_exposed=False)
+            if key not in data:
+                return False
+            del data[key]
+            if data:
+                self._write(data)
+            else:
+                self.path.unlink(missing_ok=True)
+            return True
+
+    def _read(self, *, refuse_exposed: bool = True) -> dict[str, Any]:
+        try:
+            raw = self.path.read_bytes()
+        except FileNotFoundError:
+            return {}
+        except OSError as exc:
+            raise AuthError(f"cannot read the token cache {self.path}: {exc}") from None
+        if refuse_exposed and _exposed(self.path):
+            raise AuthError(
+                f"the token cache {self.path} can be read by other accounts, so it is not used",
+                hint=(
+                    f"delete it (a new one is private): what it held may have been seen, so "
+                    f"also run {brand.command('entra sign-out')} and sign out everywhere if "
+                    "that matters"
+                ),
+            )
+        try:
+            if self._unprotect is not None:
+                raw = self._unprotect(raw)
+            data = json.loads(raw.decode("utf-8"))
+        except (OSError, ValueError) as exc:
+            # A damaged cache, or one encrypted for another account: start again.
+            log.warning("ignoring the token cache %s, which cannot be read: %s", self.path, exc)
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _write(self, data: Mapping[str, Any]) -> None:
+        payload = json.dumps(data, indent=2, sort_keys=True).encode("utf-8")
+        if self._protect is not None:
+            payload = self._protect(payload)
+        folder = self.path.parent
+        try:
+            if not folder.exists():
+                folder.mkdir(parents=True, mode=0o700)
+                os.chmod(folder, 0o700)  # mkdir's mode is narrowed by the umask, not widened
+            temporary = folder / f".{self.path.name}.{os.getpid()}.tmp"
+            descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            try:
+                with os.fdopen(descriptor, "wb") as handle:
+                    handle.write(payload)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                os.replace(temporary, self.path)
+            finally:
+                temporary.unlink(missing_ok=True)
+        except OSError as exc:
+            raise AuthError(f"cannot write the token cache {self.path}: {exc}") from None
+
+
+class KeyringStore:
+    """Values in the operating system's keychain, through the ``keyring`` package."""
+
+    def __init__(self, service: str = KEYCHAIN_SERVICE, *, backend: ModuleType | None = None):
+        if backend is None:
+            try:
+                # Optional (the keychain extra), so imported only when asked for.
+                import keyring as backend
+            except ImportError:
+                raise ConfigError(
+                    'token_cache = "keychain" needs the keyring package', hint=_KEYCHAIN_HINT
+                ) from None
+        self.service = service
+        self._backend = backend
+        errors = getattr(backend, "errors", None)
+        self._error: type[Exception] = getattr(errors, "KeyringError", Exception)
+
+    def load(self, key: str) -> str | None:
+        try:
+            return self._backend.get_password(self.service, key) or None
+        except self._error as exc:
+            raise self._failure("read", exc) from None
+
+    def save(self, key: str, value: str) -> None:
+        try:
+            self._backend.set_password(self.service, key, value)
+        except self._error as exc:
+            raise self._failure("write to", exc) from None
+
+    def delete(self, key: str) -> bool:
+        try:
+            if self._backend.get_password(self.service, key) is None:
+                return False
+            self._backend.delete_password(self.service, key)
+        except self._error as exc:
+            raise self._failure("write to", exc) from None
+        return True
+
+    def _failure(self, action: str, exc: Exception) -> AuthError:
+        return AuthError(
+            f"cannot {action} the keychain: {exc}",
+            hint=(
+                "on Linux this needs a Secret Service (GNOME Keyring or KWallet) running; "
+                'without one, use token_cache = "file" or "memory"'
+            ),
+        )
+
+
+def default_path(
+    *, encrypted: bool = False, environ: Mapping[str, str] = os.environ, platform: str = ""
+) -> Path:
+    """Where the file stores live: per user, never beside a config file in a repository.
+
+    The brand's ``TOKEN_CACHE`` variable names a file instead. Otherwise it is
+    ``%LOCALAPPDATA%\\<tool>`` on Windows and ``$XDG_STATE_HOME/<tool>`` (by default
+    ``~/.local/state/<tool>``) elsewhere.
+    """
+    name = "refresh-tokens.dpapi" if encrypted else "refresh-tokens.json"
+    override = environ.get(FILE_ENV)
+    if override:
+        path = Path(override).expanduser()
+        return path.with_suffix(".dpapi") if encrypted else path
+    if (platform or sys.platform) == "win32":
+        base = Path(environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    else:
+        base = Path(environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
+    return base / brand.CONFIG_DIR / name
+
+
+def open_store(
+    kind: str, *, environ: Mapping[str, str] = os.environ, platform: str = ""
+) -> TokenStore:
+    """The store a profile's ``token_cache`` names."""
+    if kind == "memory":
+        return MemoryStore()
+    if kind == "file":
+        return FileStore(default_path(environ=environ, platform=platform))
+    if kind == "keychain":
+        if (platform or sys.platform) == "win32":
+            from libre_devops_helpers.core import dpapi  # Windows only
+
+            return FileStore(
+                default_path(encrypted=True, environ=environ, platform=platform),
+                protect=dpapi.protect,
+                unprotect=dpapi.unprotect,
+            )
+        return KeyringStore()
+    raise ConfigError(f"token_cache must be one of {', '.join(TOKEN_CACHES)}, not {kind!r}")
+
+
+def _exposed(path: Path) -> bool:
+    """True when accounts other than the owner may read ``path`` (POSIX permissions)."""
+    if os.name != "posix":
+        return False  # Windows: the per-user profile folder's ACL keeps others out
+    return bool(path.stat().st_mode & 0o077)

libre_devops_helpers/core/util.py

@@ -0,0 +1,120 @@
+"""Small helpers shared across the subpackages: names, OData literals, timestamps."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from datetime import UTC, datetime, timedelta
+
+from libre_devops_helpers.core.errors import InputError
+
+_GUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+# Some Microsoft APIs return seven fractional digits; datetime accepts six.
+_LONG_FRACTION = re.compile(r"\.(\d{6})\d+")
+
+
+def is_guid(value: str) -> bool:
+    """True when ``value`` is a GUID in the 8-4-4-4-12 form."""
+    return bool(_GUID.match(value.strip()))
+
+
+def short_name(name: str) -> str:
+    """The host part of a name: ``web01.corp.example.com`` -> ``web01``."""
+    return name.strip().rstrip(".").split(".", 1)[0]
+
+
+def candidate_names(name: str) -> list[str]:
+    """Names to try for one device, most specific first: the FQDN, then the short hostname.
+
+    Entra and Defender do not record Linux host names consistently, so a lookup
+    that misses on the FQDN retries on the short name.
+    """
+    full = name.strip().rstrip(".")
+    short = short_name(full)
+    return [full] if short.casefold() == full.casefold() else [full, short]
+
+
+def split_names(values: Iterable[str]) -> list[str]:
+    """Split comma- or whitespace-separated names, dropping blanks and repeats.
+
+    ``["a,b", "c  d", "A"]`` -> ``["a", "b", "c", "d"]``: a command can take
+    ``"X,Y,Z"`` as one argument, as several arguments, or as lines from a file.
+    Repeats are matched case-insensitively and the first spelling is kept.
+    """
+    seen: set[str] = set()
+    names: list[str] = []
+    for value in values:
+        for name in re.split(r"[,\s]+", value):
+            if name and name.casefold() not in seen:
+                seen.add(name.casefold())
+                names.append(name)
+    return names
+
+
+def odata_string(value: str) -> str:
+    """Quote ``value`` as an OData string literal, doubling embedded single quotes."""
+    return "'" + value.replace("'", "''") + "'"
+
+
+def odata_datetime(value: datetime) -> str:
+    """A UTC OData datetime literal, ``2026-09-24T10:11:12Z``, which is never quoted."""
+    return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_datetime(value: object) -> datetime | None:
+    """Parse an ISO 8601 timestamp from an API into an aware UTC datetime.
+
+    Returns None for empty or unparseable values rather than raising, because one
+    odd record should not fail a whole listing.
+    """
+    if not isinstance(value, str) or not value.strip():
+        return None
+    text = _LONG_FRACTION.sub(r".\1", value.strip())
+    if text[-1] in "Zz":
+        text = text[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+_DURATION = re.compile(r"(\d+)\s*([dhms])", re.IGNORECASE)
+_UNIT_SECONDS = {"d": 86400, "h": 3600, "m": 60, "s": 1}
+
+
+def parse_duration(text: str) -> timedelta:
+    """Read ``90``, ``90s``, ``15m``, ``2h``, ``1h30m`` or ``7d`` as a duration.
+
+    A bare number is seconds. Raises InputError for anything else, including zero.
+    """
+    value = text.strip().lower().replace(" ", "")
+    if value.isdigit():
+        seconds = int(value)
+    else:
+        parts = _DURATION.findall(value)
+        if not parts or "".join(number + unit for number, unit in parts) != value:
+            raise InputError(
+                f"cannot read the duration {text!r}", hint="use e.g. 90, 90s, 15m, 2h, 1h30m or 7d"
+            )
+        seconds = sum(int(number) * _UNIT_SECONDS[unit] for number, unit in parts)
+    if seconds <= 0:
+        raise InputError(f"the duration {text!r} must be more than zero")
+    return timedelta(seconds=seconds)
+
+
+def format_duration(delta: timedelta) -> str:
+    """Render a duration compactly: ``45s``, ``12m 05s``, ``3h 07m``, ``2d 04h``."""
+    seconds = int(abs(delta.total_seconds()))
+    days, seconds = divmod(seconds, 86400)
+    hours, seconds = divmod(seconds, 3600)
+    minutes, seconds = divmod(seconds, 60)
+    if days:
+        return f"{days}d {hours:02d}h"
+    if hours:
+        return f"{hours}h {minutes:02d}m"
+    if minutes:
+        return f"{minutes}m {seconds:02d}s"
+    return f"{seconds}s"

libre_devops_helpers/core/yaml_text.py

@@ -0,0 +1,142 @@
+"""JSON-shaped data as YAML, with the standard library alone.
+
+Only what JSON can hold is written (objects, arrays, strings, numbers, booleans, null),
+in block style. A string is left plain only when no YAML reader could take it for
+anything else: ``yes``, ``no``, ``null``, ``1.0``, ``2026-09-24``, ``@odata.context`` and
+``a: b`` are all quoted, as JSON strings, which YAML reads the same way. A multi-line
+string becomes a ``|`` block. There is no parser: reading YAML is not needed here.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from typing import Any
+
+# kind ("key", "string", "number", "bool", "null", "punct") and text -> text to write.
+Paint = Callable[[str, str], str]
+
+# Plain only when it starts with a letter or underscore and holds nothing YAML reads
+# specially; single spaces between words are fine.
+_PLAIN = re.compile(r"[A-Za-z_][\w.\-/+@]*(?: [\w.\-/+@]+)*")
+# Words YAML 1.1 or 1.2 readers take for booleans or null, in any case.
+_WORDS = frozenset(
+    {"true", "false", "yes", "no", "on", "off", "y", "n", "null", "none", "nan", "inf"}
+)
+# Characters YAML will not take as they are inside a quoted string: C1 controls (U+0085
+# is a line break to YAML), the Unicode line and paragraph separators, and non-characters.
+_UNPRINTABLE = re.compile(r"[\x7f-\x9f\u2028\u2029\ufeff\ufffe\uffff\ud800-\udfff]")
+# Characters that make a string unsafe for a literal block: controls other than tab.
+_CONTROL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f\u0085\u2028\u2029\ufeff]")
+
+
+def dumps(data: Any, *, indent: int = 2, paint: Paint | None = None) -> str:
+    """``data`` (as ``json.loads`` gives it) as a YAML document, ending in a newline.
+
+    The newline matters: a ``|`` block last in the document keeps its own final line
+    break only when the document ends with one.
+    """
+    painter = paint or (lambda _kind, text: text)
+    return "\n".join(_node(data, 0, max(indent, 1), painter)) + "\n"
+
+
+def _node(value: Any, level: int, indent: int, paint: Paint) -> list[str]:
+    """The lines for ``value`` standing alone, at ``level`` spaces."""
+    pad = " " * level
+    if isinstance(value, dict) and value:
+        lines = []
+        for key, item in value.items():
+            head = f"{pad}{paint('key', _string(str(key)))}{paint('punct', ':')}"
+            lines.extend(_entry(head, item, level, indent, paint))
+        return lines
+    if isinstance(value, list) and value:
+        lines = []
+        for item in value:
+            lines.extend(_item(item, level, indent, paint))
+        return lines
+    first, *rest = _scalar(value, level, indent, paint)
+    return [pad + first, *_indented(rest, level + indent)]
+
+
+def _entry(head: str, value: Any, level: int, indent: int, paint: Paint) -> list[str]:
+    """``key:`` followed by its value: on the same line, or nested below it."""
+    if _nests(value):
+        return [head, *_node(value, level + indent, indent, paint)]
+    first, *rest = _scalar(value, level + indent, indent, paint)
+    return [f"{head} {first}", *_indented(rest, level + indent)]
+
+
+def _item(value: Any, level: int, indent: int, paint: Paint) -> list[str]:
+    """``- `` followed by an array item; a nested object or array starts on the same line."""
+    dash = " " * level + paint("punct", "-")
+    if _nests(value):
+        inner = _node(value, level + 2, indent, paint)
+        return [dash + " " + inner[0].lstrip(), *inner[1:]]
+    first, *rest = _scalar(value, level + 2, indent, paint)
+    return [f"{dash} {first}", *_indented(rest, level + 2)]
+
+
+def _indented(lines: list[str], level: int) -> list[str]:
+    """A block's lines at ``level``; blank ones stay empty, with no trailing spaces."""
+    return [" " * level + line if line else "" for line in lines]
+
+
+def _nests(value: Any) -> bool:
+    return isinstance(value, dict | list) and bool(value)
+
+
+def _scalar(value: Any, level: int, indent: int, paint: Paint) -> list[str]:
+    """A scalar's lines: one, or a ``|`` header and a block, each without the indent."""
+    if value is None:
+        return [paint("null", "null")]
+    if isinstance(value, bool):
+        return [paint("bool", "true" if value else "false")]
+    if isinstance(value, float):
+        return [paint("number", _float(value))]
+    if isinstance(value, int):
+        return [paint("number", json.dumps(value))]
+    if isinstance(value, dict):
+        return [paint("punct", "{}")]
+    if isinstance(value, list):
+        return [paint("punct", "[]")]
+    text = str(value)
+    block = _block(text)
+    if block is not None:
+        return [paint("punct", block[0]), *(paint("string", line) for line in block[1:])]
+    return [paint("string", _string(text))]
+
+
+def _float(value: float) -> str:
+    """A float every YAML reader takes as one: YAML 1.1 wants a point, so 1e-07 is 1.0e-07."""
+    text = json.dumps(value)
+    mantissa, marker, exponent = text.partition("e")
+    if marker and "." not in mantissa:
+        return f"{mantissa}.0e{exponent}"
+    return text
+
+
+def _string(text: str) -> str:
+    """``text`` plain when that reads back as the same string, else JSON-quoted."""
+    # fullmatch, not match with $: in Python, $ also matches before a final newline.
+    if _PLAIN.fullmatch(text) and text.casefold() not in _WORDS:
+        return text
+    quoted = json.dumps(text, ensure_ascii=False)
+    return _UNPRINTABLE.sub(lambda found: f"\\u{ord(found.group()):04x}", quoted)
+
+
+def _block(text: str) -> list[str] | None:
+    """A multi-line string as a literal block (``|``), or None when it cannot be one.
+
+    The lines come back unindented; the caller indents them. A block must not start with
+    a space (the reader would take that as the indent), and holds no control characters.
+    """
+    if "\n" not in text or _CONTROL.search(text) or text.startswith((" ", "\n")):
+        return None
+    body = text.rstrip("\n")
+    trailing = len(text) - len(body)
+    chomp = {0: "|-", 1: "|"}.get(trailing, "|+")
+    lines = body.split("\n") + [""] * (trailing - 1 if trailing > 1 else 0)
+    if any(line.endswith((" ", "\t")) for line in lines):
+        return None  # trailing spaces would be invisible, so quote it instead
+    return [chomp, *lines]

libre_devops_helpers/microsoft/__init__.py

@@ -0,0 +1,94 @@
+"""Microsoft: Azure, Entra ID, Defender, Intune, Key Vault and Log Analytics.
+
+This package is the Microsoft vendor layer. Its top-level modules are shared by every
+Microsoft feature: clouds and their endpoints, the APIs as tokens see them, token checks,
+credentials, the Azure CLI runner and the ``[microsoft]`` profiles. The feature modules
+(``azcli``, ``entra``, ``xdr``, ``intune``, ``azure``, ``keyvault``, ``loganalytics``)
+depend on those and on ``core`` only; ``devices`` combines ``entra``, ``xdr`` and
+``intune``.
+
+Public API::
+
+    from libre_devops_helpers.core import CachingTokenProvider
+    from libre_devops_helpers.microsoft import credential_for, load_config
+    from libre_devops_helpers.microsoft.entra import EntraClient
+
+    profile = load_config().get("prod-tenant")
+    tokens = CachingTokenProvider(credential_for(profile))
+"""
+
+from libre_devops_helpers.microsoft.auth import (
+    AzureCliCredential,
+    ClientSecretCredential,
+    ManagedIdentityCredential,
+    WorkloadIdentityCredential,
+    credential_for,
+)
+from libre_devops_helpers.microsoft.clouds import CHINA, CLOUDS, PUBLIC, USGOV, Cloud, get_cloud
+from libre_devops_helpers.microsoft.config import (
+    AUTH_METHODS,
+    CONFIG_TEMPLATE,
+    PLACEHOLDER_ID,
+    MicrosoftConfig,
+    Profile,
+    load_config,
+    parse_config,
+)
+from libre_devops_helpers.microsoft.process import AzCliError, AzureCliRunner
+from libre_devops_helpers.microsoft.resources import (
+    ARM,
+    GRAPH,
+    KEY_VAULT,
+    LOG_ANALYTICS,
+    MDE,
+    RESOURCES,
+    Requirement,
+    Resource,
+    resolve_resource,
+    resources_for,
+)
+from libre_devops_helpers.microsoft.tokens import (
+    Check,
+    DecodedToken,
+    decode_token,
+    passed,
+    validate_token,
+)
+
+__all__ = [
+    "ARM",
+    "AUTH_METHODS",
+    "CHINA",
+    "CLOUDS",
+    "CONFIG_TEMPLATE",
+    "GRAPH",
+    "KEY_VAULT",
+    "LOG_ANALYTICS",
+    "MDE",
+    "PLACEHOLDER_ID",
+    "PUBLIC",
+    "RESOURCES",
+    "USGOV",
+    "AzCliError",
+    "AzureCliCredential",
+    "AzureCliRunner",
+    "Check",
+    "ClientSecretCredential",
+    "Cloud",
+    "DecodedToken",
+    "ManagedIdentityCredential",
+    "MicrosoftConfig",
+    "Profile",
+    "Requirement",
+    "Resource",
+    "WorkloadIdentityCredential",
+    "credential_for",
+    "decode_token",
+    "get_cloud",
+    "load_config",
+    "parse_config",
+    "passed",
+    "resolve_resource",
+    "resources_for",
+    "validate_token",
+]

libre_devops_helpers/microsoft/auth/__init__.py

@@ -0,0 +1,43 @@
+"""Microsoft credentials: the Azure CLI, app registrations and managed identities.
+
+Every credential satisfies ``core.auth.TokenProvider``; the service modules take any
+provider, and ``credential_for`` builds the one a profile's ``auth`` setting names.
+
+Public API::
+
+    from libre_devops_helpers.core.auth import CachingTokenProvider
+    from libre_devops_helpers.microsoft.auth import credential_for
+
+    tokens = CachingTokenProvider(credential_for(profile))
+"""
+
+from libre_devops_helpers.microsoft.auth.azure_cli import AzureCliCredential, Reauthenticate
+from libre_devops_helpers.microsoft.auth.delegated import (
+    DeviceCodeCredential,
+    InteractiveCredential,
+    LoopbackReceiver,
+)
+from libre_devops_helpers.microsoft.auth.entra import (
+    ClientSecretCredential,
+    WorkloadIdentityCredential,
+    federated_token_file,
+    github_actions_assertion,
+)
+from libre_devops_helpers.microsoft.auth.factory import credential_for
+from libre_devops_helpers.microsoft.auth.lapse import lapse_reason
+from libre_devops_helpers.microsoft.auth.managed_identity import ManagedIdentityCredential
+
+__all__ = [
+    "AzureCliCredential",
+    "ClientSecretCredential",
+    "DeviceCodeCredential",
+    "InteractiveCredential",
+    "LoopbackReceiver",
+    "ManagedIdentityCredential",
+    "Reauthenticate",
+    "WorkloadIdentityCredential",
+    "credential_for",
+    "federated_token_file",
+    "github_actions_assertion",
+    "lapse_reason",
+]