onbot 0.0.1__tar.gz

onbot-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Deutsche Zentrum für Diabetesforschung e.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

onbot-0.0.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.1
+Name: onbot
+Version: 0.0.1
+Summary: Keep a Matrix (Synapse) homeserver in sync with Authentik and onboard new users.
+Keywords: matrix,synapse,authentik,mas,bot,onboarding
+Author: DZD
+License: MIT
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Project-URL: Homepage, https://github.com/DZD-eV-Diabetes-Research/matrix-synapse-authentik-onbaording-bot
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: tenacity>=9.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# Onbot
+
+Onbot keeps a **Matrix (Synapse)** homeserver in sync with an
+**[Authentik](https://goauthentik.io/)** identity provider and gives every new user a friendly
+welcome into the right rooms.
+
+Authentik is the source of truth. Onbot mirrors it into Matrix: each Authentik group becomes a room,
+group membership becomes room membership, and roles become power levels. When a new user shows up,
+they get a guided 1:1 welcome message.
+
+Onbot is built for **Matrix 2.0**. It assumes a
+[**Matrix Authentication Service (MAS)**](https://element-hq.github.io/matrix-authentication-service/)
+deployment with Authentik as the upstream identity provider.
+
+## What Onbot does and does not do
+
+Onbot **does not create accounts**. MAS provisions a Matrix account the first time a user logs in
+through Authentik. Onbot's job is projection: turn Authentik groups into rooms, group membership
+into room membership, attributes into power levels, and drive the offboarding lifecycle when a user
+is disabled.
+
+## Quick start with Docker
+
+The published image is [`dzdde/onbot`](https://hub.docker.com/r/dzdde/onbot) on Docker Hub. It runs
+as a non-root user and needs one thing from you: a config file.
+
+1. Create a `config.yml` (see [Minimal config](#minimal-config) below).
+
+2. Run it:
+
+```bash
+docker run --rm \
+  -v "$PWD/config.yml:/config/config.yml:ro" \
+  dzdde/onbot:latest
+```
+
+The image defaults to reading `/config/config.yml` and running the long-lived `onbot run` service.
+It also ships a built-in `HEALTHCHECK`.
+
+### docker-compose
+
+```yaml
+services:
+  onbot:
+    image: dzdde/onbot:latest
+    restart: unless-stopped
+    volumes:
+      - ./config.yml:/config/config.yml:ro
+```
+
+More deployment detail (env-only config, CLI commands, healthcheck) lives in
+[docs/deployment.md](docs/deployment.md).
+
+## Minimal config
+
+Configuration is a single YAML file. Copy this, fill in the values, save it as `config.yml`:
+
+```yaml
+synapse_server:
+  server_name: company.org                  # your Matrix domain (the part after the ':')
+  server_url: https://internal.matrix       # how the bot reaches Synapse (an internal URL is fine)
+  bot_user_id: "@welcome-bot:company.org"
+  bot_access_token: syt_REPLACE_ME          # or an `oauth2:` block instead
+
+authentik_server:
+  url: https://authentik.company.org/
+  api_key: REPLACE_ME                        # an Authentik API token
+
+# Required to enforce offboarding under MAS (omit on non-MAS deployments):
+mas_admin:
+  url: https://auth.company.org              # the MAS base URL
+  client_id: REPLACE_ME                      # a MAS admin client (in policy.data.admin_clients)
+  client_secret: REPLACE_ME
+
+sync_authentik_users_with_matrix_rooms:
+  authentik_username_mapping_attribute: username   # MUST agree with MAS's localpart template
+```
+
+Two settings above are easy to get wrong and worth calling out:
+
+- **`authentik_username_mapping_attribute` must match the localpart template MAS uses.** Onbot
+  computes each user's MXID from this Authentik attribute. If it disagrees with MAS, the computed
+  MXIDs will not match the real accounts and nobody gets added to rooms.
+- **`mas_admin` is required to actually offboard disabled users.** The Synapse admin API cannot
+  revoke a MAS-issued session, only MAS can. Without this block, offboarding silently does nothing
+  to live sessions.
+
+Every setting can also be supplied via an environment variable (prefix `ONBOT_`, nest with `__`),
+for example `ONBOT_SYNAPSE_SERVER__BOT_ACCESS_TOKEN=syt_…`.
+
+> Never commit a real config. `config*.yml` is gitignored (only `config.example.yml` is tracked) and
+> the image carries no secrets. Provide config at runtime.
+
+For the full picture (bot credential options, the MAS auth topology, and every field), see the docs
+below.
+
+## Documentation
+
+- [docs/configuration.md](docs/configuration.md) walks through every config block, the bot
+  credential choices, and how to generate the reference.
+- [docs/CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md) lists every field, its type, default,
+  description, and `ONBOT_*` env-var name (generated from the model).
+- [docs/deployment.md](docs/deployment.md) covers running with Docker and compose, env-only config,
+  the CLI commands, and the healthcheck.
+- [docs/architecture.md](docs/architecture.md) explains the Matrix client to MAS to Authentik auth
+  topology and links the architecture decision records.
+- [docs/development.md](docs/development.md) is the setup, build, and release guide for contributors.
+- [docs/testing.md](docs/testing.md) describes the unit, contract, and integration suites.
+- [docs/troubleshooting.md](docs/troubleshooting.md) is a symptom to cause table for common issues.
+- [docs/project/GOALS.md](docs/project/GOALS.md) captures project intent and [docs/project/BATTLE_PLAN.md](docs/project/BATTLE_PLAN.md) the build plan.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

onbot-0.0.1/README.md

@@ -0,0 +1,114 @@
+# Onbot
+
+Onbot keeps a **Matrix (Synapse)** homeserver in sync with an
+**[Authentik](https://goauthentik.io/)** identity provider and gives every new user a friendly
+welcome into the right rooms.
+
+Authentik is the source of truth. Onbot mirrors it into Matrix: each Authentik group becomes a room,
+group membership becomes room membership, and roles become power levels. When a new user shows up,
+they get a guided 1:1 welcome message.
+
+Onbot is built for **Matrix 2.0**. It assumes a
+[**Matrix Authentication Service (MAS)**](https://element-hq.github.io/matrix-authentication-service/)
+deployment with Authentik as the upstream identity provider.
+
+## What Onbot does and does not do
+
+Onbot **does not create accounts**. MAS provisions a Matrix account the first time a user logs in
+through Authentik. Onbot's job is projection: turn Authentik groups into rooms, group membership
+into room membership, attributes into power levels, and drive the offboarding lifecycle when a user
+is disabled.
+
+## Quick start with Docker
+
+The published image is [`dzdde/onbot`](https://hub.docker.com/r/dzdde/onbot) on Docker Hub. It runs
+as a non-root user and needs one thing from you: a config file.
+
+1. Create a `config.yml` (see [Minimal config](#minimal-config) below).
+
+2. Run it:
+
+```bash
+docker run --rm \
+  -v "$PWD/config.yml:/config/config.yml:ro" \
+  dzdde/onbot:latest
+```
+
+The image defaults to reading `/config/config.yml` and running the long-lived `onbot run` service.
+It also ships a built-in `HEALTHCHECK`.
+
+### docker-compose
+
+```yaml
+services:
+  onbot:
+    image: dzdde/onbot:latest
+    restart: unless-stopped
+    volumes:
+      - ./config.yml:/config/config.yml:ro
+```
+
+More deployment detail (env-only config, CLI commands, healthcheck) lives in
+[docs/deployment.md](docs/deployment.md).
+
+## Minimal config
+
+Configuration is a single YAML file. Copy this, fill in the values, save it as `config.yml`:
+
+```yaml
+synapse_server:
+  server_name: company.org                  # your Matrix domain (the part after the ':')
+  server_url: https://internal.matrix       # how the bot reaches Synapse (an internal URL is fine)
+  bot_user_id: "@welcome-bot:company.org"
+  bot_access_token: syt_REPLACE_ME          # or an `oauth2:` block instead
+
+authentik_server:
+  url: https://authentik.company.org/
+  api_key: REPLACE_ME                        # an Authentik API token
+
+# Required to enforce offboarding under MAS (omit on non-MAS deployments):
+mas_admin:
+  url: https://auth.company.org              # the MAS base URL
+  client_id: REPLACE_ME                      # a MAS admin client (in policy.data.admin_clients)
+  client_secret: REPLACE_ME
+
+sync_authentik_users_with_matrix_rooms:
+  authentik_username_mapping_attribute: username   # MUST agree with MAS's localpart template
+```
+
+Two settings above are easy to get wrong and worth calling out:
+
+- **`authentik_username_mapping_attribute` must match the localpart template MAS uses.** Onbot
+  computes each user's MXID from this Authentik attribute. If it disagrees with MAS, the computed
+  MXIDs will not match the real accounts and nobody gets added to rooms.
+- **`mas_admin` is required to actually offboard disabled users.** The Synapse admin API cannot
+  revoke a MAS-issued session, only MAS can. Without this block, offboarding silently does nothing
+  to live sessions.
+
+Every setting can also be supplied via an environment variable (prefix `ONBOT_`, nest with `__`),
+for example `ONBOT_SYNAPSE_SERVER__BOT_ACCESS_TOKEN=syt_…`.
+
+> Never commit a real config. `config*.yml` is gitignored (only `config.example.yml` is tracked) and
+> the image carries no secrets. Provide config at runtime.
+
+For the full picture (bot credential options, the MAS auth topology, and every field), see the docs
+below.
+
+## Documentation
+
+- [docs/configuration.md](docs/configuration.md) walks through every config block, the bot
+  credential choices, and how to generate the reference.
+- [docs/CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md) lists every field, its type, default,
+  description, and `ONBOT_*` env-var name (generated from the model).
+- [docs/deployment.md](docs/deployment.md) covers running with Docker and compose, env-only config,
+  the CLI commands, and the healthcheck.
+- [docs/architecture.md](docs/architecture.md) explains the Matrix client to MAS to Authentik auth
+  topology and links the architecture decision records.
+- [docs/development.md](docs/development.md) is the setup, build, and release guide for contributors.
+- [docs/testing.md](docs/testing.md) describes the unit, contract, and integration suites.
+- [docs/troubleshooting.md](docs/troubleshooting.md) is a symptom to cause table for common issues.
+- [docs/project/GOALS.md](docs/project/GOALS.md) captures project intent and [docs/project/BATTLE_PLAN.md](docs/project/BATTLE_PLAN.md) the build plan.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

onbot-0.0.1/onbot/__init__.py

@@ -0,0 +1,12 @@
+"""Onbot — keep a Matrix homeserver in sync with Authentik and onboard new users.
+
+Clean-slate rebuild targeting modern Matrix (MAS / next-gen auth, authenticated media,
+sliding sync). See ``BATTLE_PLAN.md`` for the architecture and ``GOALS.md`` for intent.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("onbot")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"

onbot-0.0.1/onbot/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m onbot``."""
+
+from onbot.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

onbot-0.0.1/onbot/app.py

@@ -0,0 +1,173 @@
+"""Composition root: build clients, wire the reconciler + onboarding, manage lifecycle.
+
+Keeps construction in one place (AD-4) so the CLI stays thin. The reconciler converges
+Authentik→Matrix state; onboarding reacts (event-driven) to the reconciler's "user provisioned"
+signal and to Matrix join events. They share the async API clients and an in-process event bus.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from onbot.auth.token_provider import (
+    OAuth2ClientCredentialsTokenProvider,
+    StaticTokenProvider,
+    TokenProvider,
+)
+from onbot.clients.authentik import ApiClientAuthentik
+from onbot.clients.mas_admin import ApiClientMasAdmin
+from onbot.clients.matrix import ApiClientMatrix, CSApiEffectors
+from onbot.clients.synapse_admin import ApiClientSynapseAdmin
+from onbot.config import OnbotConfig, SynapseServer
+from onbot.events import EventBus
+from onbot.lifecycle.accounts import (
+    AccountLifecycleManager,
+    AdminApiLifecycleEffectors,
+    LifecycleEffectors,
+    MasLifecycleEffectors,
+    MatrixAccountDataLedgerStore,
+)
+from onbot.logging import get_logger
+from onbot.media import MediaUploader
+from onbot.onboarding.listener import OnboardingListener
+from onbot.onboarding.welcome import WelcomeService
+from onbot.reconciler.engine import ReconcilerEngine
+
+log = get_logger(__name__)
+
+
+def build_matrix_token_provider(synapse: SynapseServer) -> TokenProvider:
+    """Pick the bot's auth strategy (AD-6): OAuth2 client-credentials if configured, else a static
+    compatibility/legacy token. Raises if neither is provided."""
+    if synapse.oauth2 is not None:
+        return OAuth2ClientCredentialsTokenProvider(
+            token_endpoint=synapse.oauth2.token_endpoint,
+            client_id=synapse.oauth2.client_id,
+            client_secret=synapse.oauth2.client_secret,
+            scope=synapse.oauth2.scope,
+        )
+    if synapse.bot_access_token:
+        return StaticTokenProvider(synapse.bot_access_token)
+    raise ValueError("synapse_server needs either bot_access_token or an oauth2 block")
+
+
+async def _apply_bot_avatar(matrix: ApiClientMatrix, config: OnbotConfig) -> None:
+    """Set the bot's own avatar from the configured URL on startup (G6.8), best-effort."""
+    url = config.synapse_server.bot_avatar_url
+    if not url:
+        return
+    uploader = MediaUploader(matrix)
+    try:
+        mxc = await uploader.upload_from_url(url)
+        await matrix.set_user_avatar(config.synapse_server.bot_user_id, mxc)
+        log.info("set bot avatar from %s", url)
+    except Exception:
+        log.exception("failed to set bot avatar from %s", url)
+    finally:
+        await uploader.aclose()
+
+
+@dataclass(slots=True)
+class App:
+    """Wired application: the reconciler engine and the onboarding listener over a shared bus."""
+
+    engine: ReconcilerEngine
+    listener: OnboardingListener
+
+
+@asynccontextmanager
+async def build_app(config: OnbotConfig) -> AsyncIterator[App]:
+    """Construct the reconciler + onboarding with their clients, closing them on exit."""
+    authentik = ApiClientAuthentik(
+        url=config.authentik_server.url,
+        api_key=config.authentik_server.api_key,
+    )
+    # One MAS-aware token provider shared by the admin + CS clients (same bot identity, AD-6).
+    token_provider = build_matrix_token_provider(config.synapse_server)
+    admin = ApiClientSynapseAdmin(
+        server_url=config.synapse_server.server_url,
+        token_provider=token_provider,
+        admin_api_path=config.synapse_server.admin_api_path,
+    )
+    matrix = ApiClientMatrix(
+        server_url=config.synapse_server.server_url,
+        token_provider=token_provider,
+        server_name=config.synapse_server.server_name,
+    )
+    # Negotiate CS-API capabilities up front (sliding sync / authenticated media); best-effort so a
+    # transient failure does not block startup — the listener re-checks and falls back if needed.
+    try:
+        await matrix.negotiate_versions()
+    except Exception:
+        log.exception("CS-API version negotiation failed; continuing with defaults")
+    # Register the bot's device so welcome DM sends work under MAS (compat-token devices are
+    # otherwise absent from Synapse's devices table; ADR-0006/0009).
+    await matrix.ensure_device_registered()
+    await _apply_bot_avatar(matrix, config)
+    events = EventBus()
+    # Lifecycle enforcement: under MAS only the MAS admin API can revoke a live session (§7 Q1), so
+    # prefer it when configured; otherwise fall back to the Synapse-admin effectors.
+    mas_admin: ApiClientMasAdmin | None = None
+    lifecycle_effectors: LifecycleEffectors
+    if config.mas_admin is not None:
+        mas_admin = ApiClientMasAdmin(
+            mas_url=config.mas_admin.url,
+            token_provider=OAuth2ClientCredentialsTokenProvider(
+                token_endpoint=f"{config.mas_admin.url.rstrip('/')}/oauth2/token",
+                client_id=config.mas_admin.client_id,
+                client_secret=config.mas_admin.client_secret,
+                scope="urn:mas:admin",
+            ),
+        )
+        lifecycle_effectors = MasLifecycleEffectors(mas_admin, synapse_admin=admin)
+    else:
+        lifecycle_effectors = AdminApiLifecycleEffectors(admin)
+    lifecycle = AccountLifecycleManager(
+        config,
+        store=MatrixAccountDataLedgerStore(
+            matrix, config.synapse_server.bot_user_id, config.synapse_server.server_name
+        ),
+        effectors=lifecycle_effectors,
+    )
+    effectors = CSApiEffectors(matrix)
+    engine = ReconcilerEngine(
+        config, authentik, admin, effectors=effectors, events=events, lifecycle=lifecycle
+    )
+    welcome = WelcomeService(matrix, config)
+    listener = OnboardingListener(matrix, welcome, config, events)
+    listener.start()  # subscribe onboarding to the reconciler's user-provisioned signal (AD-4)
+    try:
+        yield App(engine=engine, listener=listener)
+    finally:
+        await effectors.aclose()
+        await authentik.aclose()
+        await admin.aclose()
+        await matrix.aclose()
+        if mas_admin is not None:
+            await mas_admin.aclose()
+
+
+async def run_service(config: OnbotConfig) -> None:
+    """Run the reconcile loop and the onboarding listener concurrently until stopped."""
+    async with build_app(config) as app:
+        # The engine owns the signal handlers; when it stops, stop the listener too.
+        async def _reconcile() -> None:
+            try:
+                await app.engine.run()
+            finally:
+                app.listener.request_stop()
+
+        await asyncio.gather(_reconcile(), app.listener.run())
+
+
+async def run_reconcile_once(config: OnbotConfig) -> None:
+    """Run a single reconcile pass and exit (``onbot reconcile-once``).
+
+    Onboarding still fires for users discovered this pass — the listener is subscribed to the bus —
+    but the long-running sync stream is not started.
+    """
+    async with build_app(config) as app:
+        await app.engine.reconcile_once()

onbot-0.0.1/onbot/auth/__init__.py

@@ -0,0 +1,19 @@
+"""MAS-aware authentication (AD-6).
+
+Token providers (:mod:`onbot.auth.token_provider`): a static/compat token or OAuth2
+client-credentials with transparent refresh, behind one :class:`TokenProvider` protocol.
+"""
+
+from onbot.auth.token_provider import (
+    OAuth2ClientCredentialsTokenProvider,
+    OAuth2TokenError,
+    StaticTokenProvider,
+    TokenProvider,
+)
+
+__all__ = [
+    "OAuth2ClientCredentialsTokenProvider",
+    "OAuth2TokenError",
+    "StaticTokenProvider",
+    "TokenProvider",
+]

onbot-0.0.1/onbot/auth/token_provider.py

@@ -0,0 +1,153 @@
+"""MAS-aware access-token providers (AD-6, Phase 6).
+
+The bot authenticates to the Synapse CS + admin APIs with a bearer token. Under the
+MAS topology two ways of obtaining that token coexist, and the rest of the code must
+not care which is in use:
+
+* :class:`StaticTokenProvider` — a fixed token. This is the near-term path: a
+  *compatibility token* issued by ``mas-cli manage issue-compatibility-token`` (or a
+  legacy Synapse access token when not running MAS). Nothing expires; the token is
+  returned verbatim.
+* :class:`OAuth2ClientCredentialsTokenProvider` — the forward-looking path: the bot is
+  a confidential OAuth2 client of MAS and mints short-lived access tokens via the
+  ``client_credentials`` grant, transparently refreshing them before they expire
+  (using the ``refresh_token`` grant when MAS returns a refresh token, otherwise a
+  fresh ``client_credentials`` exchange).
+
+Both satisfy the :class:`TokenProvider` protocol — a single ``async get_token()`` —
+which :class:`~onbot.clients.base.BaseApiClient` calls per request, so a token can
+rotate underneath a long-lived client without reconstructing it.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol, runtime_checkable
+
+import httpx
+
+from onbot.logging import get_logger
+
+log = get_logger(__name__)
+
+# Refresh a little before the server-stated expiry so an in-flight request never races
+# the cutoff (clock skew + network latency margin).
+_EXPIRY_MARGIN_SEC = 30.0
+
+
+@runtime_checkable
+class TokenProvider(Protocol):
+    """Supplies a bearer token for the Authorization header; may refresh under the hood."""
+
+    async def get_token(self) -> str: ...
+
+    async def aclose(self) -> None: ...
+
+
+class StaticTokenProvider:
+    """A fixed bearer token (compat token or legacy Synapse token). Never expires."""
+
+    def __init__(self, token: str) -> None:
+        if not token:
+            raise ValueError("StaticTokenProvider requires a non-empty token")
+        self._token = token
+
+    async def get_token(self) -> str:
+        return self._token
+
+    async def aclose(self) -> None:  # symmetry with the OAuth2 provider; nothing to close
+        return None
+
+
+class OAuth2ClientCredentialsTokenProvider:
+    """Mints + refreshes MAS access tokens via the OAuth2 ``client_credentials`` grant.
+
+    The first :meth:`get_token` performs a ``client_credentials`` exchange and caches the
+    access token together with its expiry. Subsequent calls return the cached token until
+    it is within :data:`_EXPIRY_MARGIN_SEC` of expiring, then refresh it — via the
+    ``refresh_token`` grant when one was issued, else a fresh ``client_credentials``
+    exchange. Client authentication uses HTTP Basic per RFC 6749 §2.3.1.
+    """
+
+    def __init__(
+        self,
+        *,
+        token_endpoint: str,
+        client_id: str,
+        client_secret: str,
+        scope: str | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._token_endpoint = token_endpoint
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope
+        self._http = client or httpx.AsyncClient(timeout=30.0)
+        self._owns_http = client is None
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at: float = 0.0
+
+    async def get_token(self) -> str:
+        if self._access_token is not None and time.monotonic() < self._expires_at - _EXPIRY_MARGIN_SEC:
+            return self._access_token
+        return await self._refresh()
+
+    async def _refresh(self) -> str:
+        if self._refresh_token is not None:
+            data = {"grant_type": "refresh_token", "refresh_token": self._refresh_token}
+        else:
+            data = {"grant_type": "client_credentials"}
+            if self._scope:
+                data["scope"] = self._scope
+        payload = await self._token_request(data)
+        self._store(payload)
+        assert self._access_token is not None  # _store guarantees it or raised
+        return self._access_token
+
+    async def _token_request(self, data: dict[str, str]) -> dict[str, object]:
+        response = await self._http.post(
+            self._token_endpoint,
+            data=data,
+            auth=(self._client_id, self._client_secret),
+            headers={"Accept": "application/json"},
+        )
+        if response.status_code >= 400:
+            # A failed refresh may mean the refresh token was revoked; drop it so the next
+            # attempt falls back to a fresh client_credentials exchange.
+            self._refresh_token = None
+            raise OAuth2TokenError(response.status_code, _safe_json(response))
+        result: dict[str, object] = response.json()
+        return result
+
+    def _store(self, payload: dict[str, object]) -> None:
+        token = payload.get("access_token")
+        if not isinstance(token, str):
+            raise OAuth2TokenError(200, payload)
+        self._access_token = token
+        refresh = payload.get("refresh_token")
+        self._refresh_token = refresh if isinstance(refresh, str) else None
+        expires_in = payload.get("expires_in")
+        # Default to a conservative lifetime if the server omits expires_in.
+        seconds = float(expires_in) if isinstance(expires_in, int | float) else 300.0
+        self._expires_at = time.monotonic() + seconds
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+
+class OAuth2TokenError(Exception):
+    """The MAS token endpoint rejected a token request."""
+
+    def __init__(self, status_code: int, payload: object) -> None:
+        self.status_code = status_code
+        self.payload = payload
+        super().__init__(f"OAuth2 token request failed (HTTP {status_code}): {payload!r}")
+
+
+def _safe_json(response: httpx.Response) -> object:
+    try:
+        return response.json()
+    except ValueError:
+        return response.text