onbot 0.1.0.dev0__py3-none-any.whl

onbot/__init__.py

@@ -0,0 +1,7 @@
+"""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.
+"""
+
+__version__ = "0.1.0.dev0"

onbot/__main__.py

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

onbot/app.py

@@ -0,0 +1,171 @@
+"""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,
+    )
+    engine = ReconcilerEngine(
+        config, authentik, admin, effectors=CSApiEffectors(matrix), 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 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/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/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

onbot/cli.py

@@ -0,0 +1,80 @@
+"""Command-line entry point: ``python -m onbot`` / ``onbot``.
+
+Sub-commands mirror the operational surface from ``BATTLE_PLAN.md`` §4:
+
+* ``run``             — long-running service: scheduled reconcile + (Phase 4) onboarding
+* ``reconcile-once``  — run a single idempotent reconcile and exit
+* ``generate-config`` — emit a documented example config (G11.2)
+* ``healthcheck``     — probe dependencies for container/orchestrator health (Phase 8)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from collections.abc import Sequence
+
+from onbot import __version__
+from onbot.config import generate_example_config, get_config_file_path, load_config
+from onbot.logging import configure_logging, get_logger
+
+log = get_logger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="onbot", description="Authentik → Matrix sync & onboarding bot.")
+    parser.add_argument("--version", action="version", version=f"onbot {__version__}")
+    parser.add_argument("--log-level", default=None, help="Override log level (e.g. DEBUG, INFO).")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("run", help="Run the bot service (reconcile loop + onboarding).")
+    sub.add_parser("reconcile-once", help="Run a single reconcile pass and exit.")
+    gen = sub.add_parser("generate-config", help="Write a documented example configuration file.")
+    gen.add_argument("-o", "--output", default=None, help="Write to this path instead of stdout.")
+    sub.add_parser("healthcheck", help="Check connectivity to required services.")
+    return parser
+
+
+def _cmd_generate_config(output: str | None) -> int:
+    text = generate_example_config()
+    if output:
+        with open(output, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        log.info("wrote example config to %s", output)
+    else:
+        print(text, end="")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    configure_logging(args.log_level)
+    log.info("onbot %s — command %r", __version__, args.command)
+
+    if args.command == "generate-config":
+        return _cmd_generate_config(args.output)
+
+    # Commands that need live configuration + the async runtime.
+    if get_config_file_path() is None:
+        log.warning("no config file found; relying on ONBOT_* environment variables")
+    config = load_config()
+
+    if args.command == "healthcheck":
+        from onbot.healthcheck import run_healthcheck
+
+        return asyncio.run(run_healthcheck(config))
+
+    from onbot import app  # local import keeps `generate-config` usable without a config file
+
+    if args.command == "run":
+        asyncio.run(app.run_service(config))
+        return 0
+    if args.command == "reconcile-once":
+        asyncio.run(app.run_reconcile_once(config))
+        return 0
+
+    raise SystemExit(f"unknown command {args.command!r}")  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

onbot/clients/__init__.py

@@ -0,0 +1,5 @@
+"""Async HTTP clients on a shared pooled base (AD-7): Authentik, Synapse-Admin, Matrix CS.
+
+Base client + Authentik/Admin clients land in Phase 3; the Matrix CS client (+ Simplified Sliding
+Sync stream and the concrete reconciler effectors) lands in Phase 4.
+"""

onbot/clients/authentik.py

@@ -0,0 +1,123 @@
+"""Authentik API client (async, paginated).
+
+Ported from legacy ``onbot/api_client_authentik.py`` onto the async :class:`BaseApiClient`.
+Fixes carried over from BATTLE_PLAN §3: full pagination (legacy read only page 1), no stray
+``print`` debugging, and typed errors via the base client.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Any
+
+from onbot.clients.base import BaseApiClient
+from onbot.logging import get_logger
+from onbot.utils import dict_has_nested_attr
+
+log = get_logger(__name__)
+
+_DEFAULT_PAGE_SIZE = 100
+
+
+def _next_page_params(page: Any, current: dict[str, Any]) -> dict[str, Any] | None:
+    """Authentik paginates with ``pagination.next`` holding the next page number (0 = end)."""
+    pagination = (page or {}).get("pagination", {})
+    next_page = pagination.get("next")
+    if not next_page:
+        return None
+    return {**current, "page": next_page}
+
+
+class ApiClientAuthentik(BaseApiClient):
+    def __init__(self, url: str, api_key: str, **kwargs: Any) -> None:
+        super().__init__(base_url=f"{url.rstrip('/')}/api/v3", auth_token=api_key, **kwargs)
+
+    async def list_users(
+        self,
+        *,
+        filter_groups_by_name: str | Sequence[str] | None = None,
+        filter_groups_by_pk: str | Sequence[str] | None = None,
+        filter_by_path: str | None = None,
+        filter_by_attribute: str | dict[str, Any] | None = None,
+        filter_is_superuser: bool | None = None,
+        filter_is_active: bool | None = True,
+    ) -> list[dict[str, Any]]:
+        """List users (https://<authentik>/api/v3/#get-/core/users/), following all pages."""
+        if isinstance(filter_by_attribute, dict):
+            filter_by_attribute = json.dumps(filter_by_attribute)
+        params = {
+            "groups_by_name": filter_groups_by_name,
+            "groups_by_pk": filter_groups_by_pk,
+            "attributes": filter_by_attribute,
+            "is_superuser": filter_is_superuser,
+            "is_active": filter_is_active,
+            "path": filter_by_path,
+            "page_size": _DEFAULT_PAGE_SIZE,
+        }
+        return await self.paginate_collect(
+            "core/users/",
+            params=params,
+            extract_items=lambda page: page["results"],
+            next_params=_next_page_params,
+        )
+
+    async def list_groups(
+        self,
+        *,
+        filter_members_by_username: str | Sequence[str] | None = None,
+        filter_members_by_pk: str | Sequence[str] | None = None,
+        filter_by_attribute: dict[str, Any] | None = None,
+        filter_is_superuser: bool | None = None,
+        filter_has_attributes: Sequence[str] | None = None,
+        filter_has_non_empty_attributes: Sequence[str] | None = None,
+        include_inactive_users_obj: bool = False,
+    ) -> list[dict[str, Any]]:
+        """List groups (https://<authentik>/api/v3/#get-/core/groups/), following all pages.
+
+        ``filter_has_attributes`` / ``filter_has_non_empty_attributes`` are client-side filters on
+        dotted attribute paths (Authentik's query API can't express them). Inactive users are
+        stripped from each group's ``users_obj`` unless ``include_inactive_users_obj``.
+        """
+        params = {
+            "members_by_username": filter_members_by_username,
+            "members_by_pk": filter_members_by_pk,
+            "attributes": (json.dumps(filter_by_attribute) if filter_by_attribute else None),
+            "is_superuser": filter_is_superuser,
+            "page_size": _DEFAULT_PAGE_SIZE,
+        }
+        groups: list[dict[str, Any]] = await self.paginate_collect(
+            "core/groups/",
+            params=params,
+            extract_items=lambda page: page["results"],
+            next_params=_next_page_params,
+        )
+
+        if not include_inactive_users_obj:
+            for group in groups:
+                self._remove_inactive_users_from_group(group)
+
+        if filter_has_attributes:
+            groups = [
+                g
+                for g in groups
+                if any(
+                    dict_has_nested_attr(g.get("attributes", {}), attr.split("."))
+                    for attr in filter_has_attributes
+                )
+            ]
+        if filter_has_non_empty_attributes:
+            groups = [
+                g
+                for g in groups
+                if any(
+                    dict_has_nested_attr(g.get("attributes", {}), attr.split("."), must_have_val=True)
+                    for attr in filter_has_non_empty_attributes
+                )
+            ]
+        return groups
+
+    @staticmethod
+    def _remove_inactive_users_from_group(group: dict[str, Any]) -> None:
+        if "users_obj" in group:
+            group["users_obj"] = [u for u in group["users_obj"] if u.get("is_active") is True]