onbot 0.1.0.dev0__py3-none-any.whl

onbot/models.py

@@ -0,0 +1,74 @@
+"""Domain models shared across the reconciler.
+
+These are lightweight typed views over the raw Authentik / Synapse-admin API dicts (which stay as
+``dict`` since their shapes are owned upstream). Replaces the legacy ``UserMap`` / ``Group2RoomMap``
+god-objects with plain, side-effect-free dataclasses.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RoomCreateAttributes:
+    """Desired Matrix room attributes computed from an Authentik group."""
+
+    alias: str
+    canonical_alias: str
+    name: str | None = None
+    topic: str | None = None
+    room_params: dict[str, Any] = field(default_factory=dict)
+    encrypted: bool = True
+
+
+@dataclass(slots=True)
+class MatrixRoom:
+    """Actual room as seen via the Synapse admin API."""
+
+    room_id: str
+    canonical_alias: str | None = None
+    name: str | None = None
+    topic: str | None = None
+    is_space: bool = False
+
+    @classmethod
+    def from_admin_api(cls, obj: dict[str, Any], *, is_space: bool = False) -> MatrixRoom:
+        return cls(
+            room_id=obj["room_id"],
+            canonical_alias=obj.get("canonical_alias"),
+            name=obj.get("name"),
+            topic=obj.get("topic"),
+            is_space=is_space,
+        )
+
+
+@dataclass(slots=True)
+class MappedUser:
+    """An Authentik user resolved to its (MAS-provisioned) Matrix account."""
+
+    authentik_obj: dict[str, Any]
+    mxid: str
+    matrix_obj: dict[str, Any] | None = None
+
+    @property
+    def is_superuser(self) -> bool:
+        return bool(self.authentik_obj.get("is_superuser"))
+
+    @property
+    def group_pks(self) -> set[str]:
+        return {g["pk"] for g in self.authentik_obj.get("groups_obj", [])}
+
+
+@dataclass(slots=True)
+class GroupRoomMap:
+    """A desired group→room projection, paired with the actual room if one exists."""
+
+    authentik_group: dict[str, Any]
+    desired: RoomCreateAttributes
+    room: MatrixRoom | None = None
+
+    @property
+    def group_pk(self) -> str:
+        return str(self.authentik_group["pk"])

onbot/onboarding/__init__.py

@@ -0,0 +1,5 @@
+"""Event-driven welcome/onboarding via the sync stream (AD-3): listener + idempotent welcome flow.
+
+Phase 4. MXID identity mapping consistent with the MAS localpart template lives in the shared
+``onbot.identity`` module (AD-6), reused here and by the reconciler.
+"""

onbot/onboarding/listener.py

@@ -0,0 +1,103 @@
+"""Onboarding listener (AD-3): event-driven welcome via the sync stream + the reconciler signal.
+
+Two trigger paths converge here (AD-4 explicit coupling):
+
+* **Reconciler signal** — the reconciler emits :attr:`Signal.user_synced` for every provisioned user
+  it sees; the listener subscribes and welcomes them. This is the dependable path and works without
+  any sync support.
+* **Sync stream** — :meth:`run` consumes Simplified Sliding Sync and welcomes users on ``join``
+  membership events, for instant onboarding with no tick latency.
+
+Both funnel through :meth:`_maybe_welcome`, which filters out the bot and ignored users and defers to
+the idempotent :class:`~onbot.onboarding.welcome.WelcomeService` (so duplicate triggers are safe).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+
+from onbot.clients.matrix import ApiClientMatrix, SyncNotSupportedError, SyncResult
+from onbot.config import OnbotConfig
+from onbot.events import Event, EventBus, Signal
+from onbot.logging import get_logger
+from onbot.onboarding.welcome import WelcomeService
+
+log = get_logger(__name__)
+
+_ERROR_BACKOFF_SEC = 5.0
+
+
+def extract_joined_users(result: SyncResult) -> set[str]:
+    """MXIDs with a ``join`` membership event in this sync slice."""
+    joined: set[str] = set()
+    for room in result.rooms:
+        for ev in room.member_events():
+            if (ev.get("content") or {}).get("membership") != "join":
+                continue
+            mxid = ev.get("state_key") or ev.get("sender")
+            if mxid:
+                joined.add(mxid)
+    return joined
+
+
+class OnboardingListener:
+    def __init__(
+        self,
+        client: ApiClientMatrix,
+        welcome: WelcomeService,
+        config: OnbotConfig,
+        events: EventBus,
+    ) -> None:
+        self.client = client
+        self.welcome = welcome
+        self.config = config
+        self.events = events
+        self.bot_id = config.synapse_server.bot_user_id
+        self._pos: str | None = None
+        self._stop = asyncio.Event()
+
+    def start(self) -> None:
+        """Subscribe to the reconciler's user-provisioned signal (call once, before running)."""
+        self.events.subscribe(Signal.user_synced, self._on_user_synced)
+
+    def request_stop(self) -> None:
+        self._stop.set()
+
+    async def _on_user_synced(self, event: Event) -> None:
+        await self._maybe_welcome(event.payload["mxid"])
+
+    async def _maybe_welcome(self, mxid: str) -> None:
+        if mxid == self.bot_id or mxid in self.config.matrix_user_ignore_list:
+            return
+        try:
+            await self.welcome.welcome_user(mxid)
+        except Exception:
+            log.exception("welcome flow failed for %s", mxid)
+
+    async def run(self) -> None:
+        """Consume the sync stream and welcome joining users until stopped."""
+        log.info("onboarding listener started (sliding sync)")
+        while not self._stop.is_set():
+            try:
+                result = await self.client.sliding_sync(self._pos)
+            except SyncNotSupportedError:
+                # The homeserver does not support Simplified Sliding Sync; rely on the reconciler
+                # signal path for onboarding (the listener stays subscribed via start()).
+                log.warning("sliding sync unsupported; onboarding via reconciler signal only")
+                break
+            except Exception:
+                log.exception("sync failed; backing off %.0fs", _ERROR_BACKOFF_SEC)
+                await self._sleep(_ERROR_BACKOFF_SEC)
+                continue
+            self._pos = result.pos
+            for mxid in extract_joined_users(result):
+                if self._stop.is_set():
+                    break
+                await self._maybe_welcome(mxid)
+        log.info("onboarding listener stopped")
+
+    async def _sleep(self, seconds: float) -> None:
+        # Sleep, but wake immediately on stop.
+        with contextlib.suppress(TimeoutError):
+            await asyncio.wait_for(self._stop.wait(), timeout=seconds)

onbot/onboarding/welcome.py

@@ -0,0 +1,116 @@
+"""Welcome / onboarding flow (AD-3, G4.*).
+
+When a user is provisioned/seen, the bot opens a 1:1 direct room with them and sends the configured
+welcome messages. Two layers of idempotency keep it safe to call repeatedly (the listener may fire
+on both the reconciler signal *and* a join event):
+
+* **One DM per user** — the bot's ``m.direct`` account data maps each user to their DM room; an
+  existing room is reused rather than re-created.
+* **Each message once** — the DM's onbot ``direct_room`` state event records a content hash per sent
+  message (G4.3). Already-sent messages are skipped; only new/changed ones go out.
+
+No database: all bookkeeping lives in Matrix account data + room state (AD-1).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+
+from onbot.clients.matrix import ApiClientMatrix
+from onbot.config import OnbotConfig
+from onbot.logging import get_logger
+from onbot.reconciler.state import (
+    DirectRoomState,
+    OnbotRoomType,
+    dump_room_state,
+    event_type_name,
+    parse_room_state,
+)
+
+log = get_logger(__name__)
+
+M_DIRECT = "m.direct"
+
+
+def _message_key(message: str) -> str:
+    """Stable per-message idempotency key (content hash). Changing the text re-sends only that one."""
+    return hashlib.sha256(message.encode("utf-8")).hexdigest()[:16]
+
+
+class WelcomeService:
+    def __init__(self, client: ApiClientMatrix, config: OnbotConfig) -> None:
+        self.client = client
+        self.config = config
+        self.bot_id = config.synapse_server.bot_user_id
+        self.server_name = config.synapse_server.server_name
+        self._direct_event_type = event_type_name(self.server_name, OnbotRoomType.direct_room)
+        # G4.5: optionally gather onboarding DMs under the managed space (opt-in — 1:1 rooms in a
+        # space is a matter of taste). Resolved lazily from the configured space alias and cached.
+        space_cfg = config.create_matrix_rooms_in_a_matrix_space
+        self._place_in_space = config.place_onboarding_rooms_in_space and space_cfg.enabled
+        self._space_alias = f"#{space_cfg.alias}:{self.server_name}"
+        self._space_id: str | None = None
+
+    async def welcome_user(self, mxid: str) -> None:
+        """Ensure ``mxid`` has a DM with all configured welcome messages delivered (idempotent)."""
+        messages = self.config.welcome_new_users_messages or []
+        if not messages:
+            return
+
+        room_id, created = await self._ensure_direct_room(mxid)
+        state = (
+            await self._load_direct_state(room_id, mxid)
+            if not created
+            else DirectRoomState(user_id=mxid, authentik_server=self.config.authentik_server.url)
+        )
+
+        changed = created
+        for message in messages:
+            key = _message_key(message)
+            if key in state.welcome_messages_sent:
+                continue
+            await self.client.send_text_message(room_id, message)
+            state.welcome_messages_sent[key] = datetime.now(UTC).isoformat()
+            changed = True
+
+        if changed:
+            await self.client.put_room_state_event(room_id, self._direct_event_type, dump_room_state(state))
+            log.info(
+                "welcomed %s in %s (%d messages tracked)",
+                mxid,
+                room_id,
+                len(state.welcome_messages_sent),
+            )
+
+    async def _ensure_direct_room(self, mxid: str) -> tuple[str, bool]:
+        """Return ``(room_id, created)`` — reusing the bot's existing DM with ``mxid`` if any."""
+        direct = await self.client.get_account_data(self.bot_id, M_DIRECT)
+        existing = direct.get(mxid) or []
+        if existing:
+            return str(existing[0]), False
+
+        room_id = await self.client.create_direct_message_room(mxid)
+        direct.setdefault(mxid, []).append(room_id)
+        await self.client.set_account_data(self.bot_id, M_DIRECT, direct)
+        await self._maybe_place_in_space(room_id)
+        return room_id, True
+
+    async def _maybe_place_in_space(self, room_id: str) -> None:
+        """Add a freshly created DM to the managed space, if configured (G4.5)."""
+        if not self._place_in_space:
+            return
+        if self._space_id is None:
+            self._space_id = await self.client.resolve_room_alias(self._space_alias)
+        if self._space_id is None:
+            log.warning("cannot place DM in space: alias %s does not resolve yet", self._space_alias)
+            return
+        await self.client.link_room_to_space(self._space_id, room_id)
+
+    async def _load_direct_state(self, room_id: str, mxid: str) -> DirectRoomState:
+        content = await self.client.get_room_state_event(room_id, self._direct_event_type)
+        if content is None:
+            return DirectRoomState(user_id=mxid, authentik_server=self.config.authentik_server.url)
+        parsed = parse_room_state(OnbotRoomType.direct_room, content)
+        assert isinstance(parsed, DirectRoomState)
+        return parsed

onbot/reconciler/__init__.py

@@ -0,0 +1,2 @@
+"""Level-triggered, idempotent Authentik→Matrix reconciler (AD-2): group→room projection,
+membership, power levels, parent space, onbot room-state. Implemented in Phase 3."""

onbot/reconciler/effectors.py

@@ -0,0 +1,78 @@
+"""Matrix-side effectors — the write seam between the reconciler and the Matrix CS API.
+
+The reconciler decides *what* should change (pure logic in the sibling modules); these effectors
+perform the Matrix Client-Server operations that the Synapse admin API cannot do (room/space
+creation, kicks, power levels, room name/topic, custom state events).
+
+The concrete CS-API implementation lands in Phase 4 (clients/matrix.py) once the Matrix-library
+decision is made (AD / Phase 6). For Phase 3 we ship the :class:`MatrixEffectors` protocol plus a
+:class:`DryRunEffectors` that logs intended actions — so ``reconcile-once`` runs end-to-end against
+real read APIs without mutating anything (the dry-run-by-default safety principle, Q6).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Protocol, runtime_checkable
+
+from onbot.logging import get_logger
+from onbot.models import RoomCreateAttributes
+
+log = get_logger(__name__)
+
+
+@runtime_checkable
+class MatrixEffectors(Protocol):
+    async def create_group_room(self, attrs: RoomCreateAttributes, parent_space_id: str | None) -> str: ...
+
+    async def create_space(self, *, alias: str, name: str, topic: str, params: dict[str, Any]) -> str: ...
+
+    async def kick_user(self, room_id: str, user_id: str, reason: str | None = None) -> None: ...
+
+    async def get_room_power_levels(self, room_id: str) -> dict[str, Any]: ...
+
+    async def set_room_power_levels(self, room_id: str, power_levels: dict[str, Any]) -> None: ...
+
+    async def set_room_name(self, room_id: str, name: str) -> None: ...
+
+    async def set_room_topic(self, room_id: str, topic: str) -> None: ...
+
+    async def put_room_state(self, room_id: str, event_type: str, content: dict[str, Any]) -> None: ...
+
+
+class DryRunEffectors:
+    """Logs every intended write and mutates nothing. Default until Phase 4 wires the CS client."""
+
+    def _synthetic_room_id(self, server_name: str = "dry-run") -> str:
+        return f"!dryrun-{uuid.uuid4().hex[:12]}:{server_name}"
+
+    async def create_group_room(self, attrs: RoomCreateAttributes, parent_space_id: str | None) -> str:
+        log.info(
+            "[dry-run] would create group room alias=%s name=%r in space=%s",
+            attrs.canonical_alias,
+            attrs.name,
+            parent_space_id,
+        )
+        return self._synthetic_room_id()
+
+    async def create_space(self, *, alias: str, name: str, topic: str, params: dict[str, Any]) -> str:
+        log.info("[dry-run] would create space alias=%s name=%r", alias, name)
+        return self._synthetic_room_id()
+
+    async def kick_user(self, room_id: str, user_id: str, reason: str | None = None) -> None:
+        log.info("[dry-run] would kick %s from %s (%s)", user_id, room_id, reason)
+
+    async def get_room_power_levels(self, room_id: str) -> dict[str, Any]:
+        return {}
+
+    async def set_room_power_levels(self, room_id: str, power_levels: dict[str, Any]) -> None:
+        log.info("[dry-run] would set power levels in %s -> %s", room_id, power_levels)
+
+    async def set_room_name(self, room_id: str, name: str) -> None:
+        log.info("[dry-run] would set name of %s -> %r", room_id, name)
+
+    async def set_room_topic(self, room_id: str, topic: str) -> None:
+        log.info("[dry-run] would set topic of %s -> %r", room_id, topic)
+
+    async def put_room_state(self, room_id: str, event_type: str, content: dict[str, Any]) -> None:
+        log.info("[dry-run] would set state %s on %s", event_type, room_id)