onbot 0.1.0.dev0__py3-none-any.whl

onbot/events.py

@@ -0,0 +1,51 @@
+"""Tiny async signal bus (AD-4).
+
+Explicit, in-process coupling between the bounded domains: the reconciler emits signals (e.g. a
+user was synced) and onboarding (Phase 4) subscribes. Kept deliberately minimal — no broker, no
+persistence — but designed so a domain could later move to its own process behind the same API.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from onbot.logging import get_logger
+
+log = get_logger(__name__)
+
+
+class Signal(StrEnum):
+    user_synced = "user_synced"
+    drift_detected = "drift_detected"
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    signal: Signal
+    payload: dict[str, Any]
+
+
+Handler = Callable[[Event], Awaitable[None]]
+
+
+class EventBus:
+    def __init__(self) -> None:
+        self._handlers: dict[Signal, list[Handler]] = defaultdict(list)
+
+    def subscribe(self, signal: Signal, handler: Handler) -> None:
+        self._handlers[signal].append(handler)
+
+    async def emit(self, signal: Signal, **payload: Any) -> None:
+        handlers = self._handlers.get(signal, [])
+        if not handlers:
+            return
+        event = Event(signal=signal, payload=payload)
+        results = await asyncio.gather(*(h(event) for h in handlers), return_exceptions=True)
+        for result in results:
+            if isinstance(result, Exception):
+                log.exception("event handler for %s failed", signal, exc_info=result)

onbot/healthcheck.py

@@ -0,0 +1,134 @@
+"""Dependency health probe for ``onbot healthcheck`` (BATTLE_PLAN §5 Phase 8).
+
+Probes the services the bot actually talks to — the Matrix CS API, the Synapse admin API, the
+Authentik API, and (when configured) the MAS admin API — using the *real* configured credentials, so
+the check verifies connectivity **and** authorization, not just that a port is open. Each probe is a
+single lightweight authenticated request.
+
+Exit code contract (suitable for a container ``HEALTHCHECK`` / orchestrator readiness probe):
+
+* ``0`` — every required dependency answered successfully.
+* ``1`` — at least one probe failed (unreachable, auth rejected, or unexpected response).
+
+The bot user id from ``/whoami`` is compared against ``synapse_server.bot_user_id``; a mismatch is a
+warning (the token authenticates as a different user than configured) but not a hard failure, since
+the bot can still operate as whoever the token belongs to.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from onbot.app import build_matrix_token_provider
+from onbot.auth.token_provider import OAuth2ClientCredentialsTokenProvider
+from onbot.clients.authentik import ApiClientAuthentik
+from onbot.clients.mas_admin import ApiClientMasAdmin, mxid_localpart
+from onbot.clients.matrix import ApiClientMatrix
+from onbot.clients.synapse_admin import ApiClientSynapseAdmin
+from onbot.config import OnbotConfig
+from onbot.logging import get_logger
+
+log = get_logger(__name__)
+
+
+@dataclass(slots=True)
+class ProbeResult:
+    """Outcome of a single dependency probe."""
+
+    name: str
+    ok: bool
+    detail: str
+
+
+async def _probe_matrix(matrix: ApiClientMatrix, expected_user_id: str) -> ProbeResult:
+    """Reach the CS API and confirm the bot token authenticates (``/whoami``)."""
+    whoami = await matrix.get_json("v3/account/whoami")
+    user_id = whoami.get("user_id", "")
+    if user_id != expected_user_id:
+        return ProbeResult(
+            "matrix-cs",
+            True,
+            f"reachable, but token is @{user_id} (config expects {expected_user_id})",
+        )
+    return ProbeResult("matrix-cs", True, f"authenticated as {user_id}")
+
+
+async def _probe_synapse_admin(admin: ApiClientSynapseAdmin) -> ProbeResult:
+    """Confirm the admin token is authorized against the Synapse admin API."""
+    # A minimal authenticated read; ``guests=false`` is required under MSC3861/MAS (synapse_admin.py).
+    await admin.get_json("v2/users", params={"limit": 1, "guests": "false"})
+    return ProbeResult("synapse-admin", True, "admin API authorized")
+
+
+async def _probe_authentik(authentik: ApiClientAuthentik) -> ProbeResult:
+    """Confirm the Authentik API token works."""
+    await authentik.get_json("core/users/", params={"page_size": 1})
+    return ProbeResult("authentik", True, "API token accepted")
+
+
+async def _probe_mas_admin(mas: ApiClientMasAdmin, bot_user_id: str) -> ProbeResult:
+    """Confirm the MAS admin client-credentials token works (lifecycle enforcement path, §7 Q1)."""
+    # ``by-username`` returns the user or 404 (both prove auth); the lookup itself never mutates.
+    await mas.get_user_id_by_username(mxid_localpart(bot_user_id))
+    return ProbeResult("mas-admin", True, "admin API authorized")
+
+
+async def run_healthcheck(config: OnbotConfig) -> int:
+    """Probe every configured dependency, log a line per result, and return an exit code."""
+    token_provider = build_matrix_token_provider(config.synapse_server)
+    authentik = ApiClientAuthentik(url=config.authentik_server.url, api_key=config.authentik_server.api_key)
+    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,
+    )
+    mas: ApiClientMasAdmin | None = None
+    if config.mas_admin is not None:
+        mas = 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",
+            ),
+        )
+
+    probes = [
+        _probe_matrix(matrix, config.synapse_server.bot_user_id),
+        _probe_synapse_admin(admin),
+        _probe_authentik(authentik),
+    ]
+    names = ["matrix-cs", "synapse-admin", "authentik"]
+    if mas is not None:
+        probes.append(_probe_mas_admin(mas, config.synapse_server.bot_user_id))
+        names.append("mas-admin")
+
+    try:
+        results = await asyncio.gather(*probes, return_exceptions=True)
+    finally:
+        await authentik.aclose()
+        await admin.aclose()
+        await matrix.aclose()
+        if mas is not None:
+            await mas.aclose()
+
+    failed = False
+    for name, result in zip(names, results, strict=True):
+        if isinstance(result, ProbeResult):
+            log.info("healthcheck %-14s OK   — %s", result.name, result.detail)
+        else:
+            failed = True
+            log.error("healthcheck %-14s FAIL — %r", name, result)
+
+    if failed:
+        log.error("healthcheck: one or more dependencies are unhealthy")
+        return 1
+    log.info("healthcheck: all dependencies healthy")
+    return 0

onbot/identity.py

@@ -0,0 +1,44 @@
+"""MXID / localpart mapping (AD-6 — the critical MAS integration contract).
+
+Under MAS, accounts are auto-provisioned on first login and the MXID localpart is derived by MAS
+from an upstream Authentik claim. The bot does **not** create accounts, but it must compute the
+*same* MXID to match users to their Matrix accounts. The localpart source is configurable
+(``sync_authentik_users_with_matrix_rooms.authentik_username_mapping_attribute``) and MUST agree
+with the template MAS uses, otherwise users won't match (BATTLE_PLAN §7 Q2).
+
+Shared by the reconciler (membership, power levels) and, later, onboarding (Phase 4).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from onbot.utils import get_nested_dict_val_by_path
+
+SigilT = Literal["@", "#", "!"]
+
+
+def build_canonical(local_part: str, server_name: str, sigil: SigilT = "@") -> str:
+    """Build a fully-qualified Matrix identifier: ``<sigil><local_part>:<server_name>``.
+
+    ``@`` → user ID, ``#`` → room alias, ``!`` → room/space ID.
+    """
+    return f"{sigil}{local_part}:{server_name}"
+
+
+def compute_mxid(
+    authentik_user: dict[str, Any],
+    *,
+    username_attribute: str,
+    server_name: str,
+) -> str:
+    """Compute the deterministic MXID for an Authentik user (G1.2, AD-6).
+
+    ``username_attribute`` is a dotted path into the Authentik user object (e.g. ``username`` or
+    ``attributes.matrix_name``). Raises ``KeyError`` if the attribute is missing — a user we cannot
+    map deterministically must surface loudly, never be silently skipped.
+    """
+    local_part = get_nested_dict_val_by_path(authentik_user, username_attribute.split("."))
+    if local_part is None or local_part == "":
+        raise KeyError(username_attribute)
+    return build_canonical(str(local_part), server_name, "@")

onbot/lifecycle/__init__.py

@@ -0,0 +1,2 @@
+"""Quarantined account lifecycle (AD-5): deactivate/delete with cooldowns, dry-run + audit
+defaults, highest test rigor. Implemented in Phase 5."""

onbot/lifecycle/accounts.py

@@ -0,0 +1,309 @@
+"""Quarantined account lifecycle (AD-5, G9.*): the scariest code in the repo.
+
+When an Authentik account is disabled (or removed), the matching Matrix account must eventually be
+locked out and, optionally, erased. This is destructive and irreversible past a point, so the module
+is built around three safety principles:
+
+* **Cooldowns absorb accidents (G12.3).** Detection only *marks* a user; nothing destructive happens
+  until ``deactivate_after_n_sec`` has elapsed, and erasure waits a further ``delete_after_n_sec``.
+  A user who reappears in Authentik before erasure is silently re-enabled (G9.6).
+* **Dry-run + audit by default (Q6, AD-5).** Destructive effector calls are gated on an explicit
+  ``dry_run=False``; until an operator opts in, the manager only records bookkeeping timestamps and
+  logs an audit line describing what *would* happen.
+* **Pure decision, isolated effects.** :func:`decide_account_action` is a side-effect-free state
+  machine (exhaustively unit-tested); all I/O lives behind the :class:`LifecycleEffectors` and
+  :class:`LifecycleLedgerStore` seams.
+
+**Two-stage semantics (legacy-faithful, GOALS-aligned).** Stage one (``deactivate_after_n_sec``)
+*logs the user out* — revoking every device/session (G9.2). Under the MAS topology (AD-6) this is the
+effective lock-out: re-login flows through MAS→Authentik, which already blocks the disabled upstream
+user. It is also reversible, which keeps the G9.6 re-enable window open. Stage two
+(``delete_after_n_sec``) *erases* the account (G9.4) and optionally its uploaded media (G9.5).
+
+Whether MAS *itself* propagates the upstream disable (revoking sessions / locking the account) is an
+open question for the maintainer (BATTLE_PLAN §7 Q1); this module is the enforcement backstop either
+way.
+
+There is no database (AD-1): the per-user bookkeeping (mark/disable timestamps) is persisted as a
+single blob in the bot's Matrix *account data*, keyed by MXID — decoupled from the onboarding DM.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from enum import StrEnum
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+from onbot.config import OnbotConfig
+from onbot.logging import get_logger
+from onbot.reconciler.state import SCHEMA_VERSION, event_type_name
+
+log = get_logger(__name__)
+# Dedicated audit channel so operators can route the irreversible-action trail separately.
+audit = get_logger("onbot.lifecycle.audit")
+
+
+def lifecycle_account_data_type(server_name: str) -> str:
+    """Account-data type holding the lifecycle ledger, e.g. ``org.company.onbot.lifecycle``."""
+    return event_type_name(server_name, "lifecycle")
+
+
+class LifecycleAction(StrEnum):
+    none = "none"  # active user, no bookkeeping to do
+    reenable = "reenable"  # previously marked/disabled but active again → clear (G9.6)
+    mark = "mark"  # newly detected orphan → start the cooldown clock (no destructive action)
+    logout = "logout"  # cooldown elapsed → revoke sessions (G9.2)
+    erase = "erase"  # further cooldown elapsed → deactivate/erase account (G9.4/G9.5)
+    wait = "wait"  # in a cooldown window → do nothing yet
+
+
+def decide_account_action(
+    *,
+    is_orphaned: bool,
+    marked_ts: float | None,
+    disabled_ts: float | None,
+    now: float,
+    deactivate_after_n_sec: float,
+    delete_after_n_sec: float | None,
+) -> LifecycleAction:
+    """Pure state machine: given a user's orphan status and timestamps, decide the next action.
+
+    ``marked_ts`` is when the user was first seen orphaned; ``disabled_ts`` is when they were logged
+    out. ``delete_after_n_sec=None`` disables erasure entirely (a logged-out user simply stays so).
+    """
+    has_state = marked_ts is not None or disabled_ts is not None
+    if not is_orphaned:
+        return LifecycleAction.reenable if has_state else LifecycleAction.none
+    if marked_ts is None:
+        return LifecycleAction.mark
+    if disabled_ts is None:
+        if now - marked_ts >= deactivate_after_n_sec:
+            return LifecycleAction.logout
+        return LifecycleAction.wait
+    if delete_after_n_sec is not None and now - disabled_ts >= delete_after_n_sec:
+        return LifecycleAction.erase
+    return LifecycleAction.wait
+
+
+class LifecycleEntry(BaseModel):
+    """Per-user bookkeeping for the lifecycle state machine."""
+
+    marked_for_disabling_timestamp: float | None = None
+    disabled_user_timestamp: float | None = None
+
+
+class LifecycleLedger(BaseModel):
+    """Versioned blob of every tracked user's lifecycle state (stored in bot account data)."""
+
+    schema_version: int = SCHEMA_VERSION
+    entries: dict[str, LifecycleEntry] = Field(default_factory=dict)
+
+
+@runtime_checkable
+class LifecycleEffectors(Protocol):
+    """The destructive Matrix/Synapse operations, isolated behind a seam (separate boundary, AD-5)."""
+
+    async def logout(self, mxid: str) -> None:
+        """Revoke every session for ``mxid`` (G9.2). Reversible (see :meth:`reenable`)."""
+
+    async def reenable(self, mxid: str) -> None:
+        """Reverse a non-destructive logout when the user returns (G9.6). May be a no-op."""
+
+    async def erase(self, mxid: str, *, delete_media: bool) -> None:
+        """Deactivate/erase the account (G9.4) and optionally its uploaded media (G9.5)."""
+
+
+class AdminApiLifecycleEffectors:
+    """Concrete effectors over the Synapse Admin API.
+
+    NOTE (BATTLE_PLAN §7 Q1, verified by the Phase 7b harness): under MAS these do **not** revoke a
+    live MAS-issued session — deleting devices/deactivating in Synapse leaves the MAS token valid.
+    Use :class:`MasLifecycleEffectors` for real enforcement under the MAS topology (ADR-0006). These
+    remain correct for non-MAS Synapse deployments.
+    """
+
+    def __init__(self, admin: Any) -> None:
+        self.admin = admin
+
+    async def logout(self, mxid: str) -> None:
+        await self.admin.logout_account(mxid)
+
+    async def reenable(self, mxid: str) -> None:
+        # Synapse logout deletes devices; there is nothing to restore — the user logs in afresh.
+        return None
+
+    async def erase(self, mxid: str, *, delete_media: bool) -> None:
+        if delete_media:
+            await self.admin.delete_user_media(mxid)
+        await self.admin.deactivate_account(mxid, erase=delete_media)
+
+
+class MasLifecycleEffectors:
+    """Effectors that enforce lockout through the **MAS admin API** (ADR-0006, §7 Q1).
+
+    This is the path that actually works under MAS: ``logout`` locks the MAS user (revoking live
+    sessions, reversibly), ``reenable`` unlocks them when their upstream account returns (G9.6), and
+    ``erase`` deactivates the account irreversibly. Media deletion still goes through the Synapse
+    admin API (MAS does not own media).
+    """
+
+    def __init__(self, mas_admin: Any, synapse_admin: Any | None = None) -> None:
+        self.mas = mas_admin
+        self.synapse_admin = synapse_admin
+
+    async def _resolve(self, mxid: str) -> str | None:
+        from onbot.clients.mas_admin import mxid_localpart
+
+        uid: str | None = await self.mas.get_user_id_by_username(mxid_localpart(mxid))
+        if uid is None:
+            log.warning("no MAS user for %s; cannot enforce lifecycle action", mxid)
+        return uid
+
+    async def logout(self, mxid: str) -> None:
+        uid = await self._resolve(mxid)
+        if uid is not None:
+            await self.mas.lock_user(uid)
+
+    async def reenable(self, mxid: str) -> None:
+        uid = await self._resolve(mxid)
+        if uid is not None:
+            await self.mas.unlock_user(uid)
+
+    async def erase(self, mxid: str, *, delete_media: bool) -> None:
+        uid = await self._resolve(mxid)
+        if uid is not None:
+            await self.mas.deactivate_user(uid)
+        if delete_media and self.synapse_admin is not None:
+            await self.synapse_admin.delete_user_media(mxid)
+
+
+@runtime_checkable
+class LifecycleLedgerStore(Protocol):
+    async def load(self) -> LifecycleLedger: ...
+
+    async def save(self, ledger: LifecycleLedger) -> None: ...
+
+
+class MatrixAccountDataLedgerStore:
+    """Persists the ledger as a single account-data blob on the bot user (no database, AD-1)."""
+
+    def __init__(self, client: Any, bot_id: str, server_name: str) -> None:
+        self.client = client
+        self.bot_id = bot_id
+        self.data_type = lifecycle_account_data_type(server_name)
+
+    async def load(self) -> LifecycleLedger:
+        raw = await self.client.get_account_data(self.bot_id, self.data_type)
+        if not raw:
+            return LifecycleLedger()
+        return LifecycleLedger.model_validate(raw)
+
+    async def save(self, ledger: LifecycleLedger) -> None:
+        await self.client.set_account_data(self.bot_id, self.data_type, ledger.model_dump(mode="json"))
+
+
+class LifecycleOutcome(BaseModel):
+    """What the manager decided for one user this pass (returned for tests/observability)."""
+
+    mxid: str
+    action: LifecycleAction
+    dry_run: bool
+
+
+class AccountLifecycleManager:
+    """Orchestrates the lifecycle pass: load ledger → decide per user → act → persist.
+
+    Invoked only by the reconciler with the set of *orphaned* MXIDs (Matrix accounts whose Authentik
+    user is disabled/gone). Any MXID already in the ledger that is no longer orphaned is re-enabled.
+    """
+
+    def __init__(
+        self,
+        config: OnbotConfig,
+        store: LifecycleLedgerStore,
+        effectors: LifecycleEffectors,
+        *,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self.cfg = config.sync_authentik_users_with_matrix_rooms.deactivate_disabled_authentik_users_in_matrix
+        self.store = store
+        self.effectors = effectors
+        self.clock = clock
+
+    async def reconcile_accounts(self, orphaned_mxids: set[str]) -> list[LifecycleOutcome]:
+        if not self.cfg.enabled:
+            return []
+        ledger = await self.store.load()
+        now = self.clock()
+        outcomes: list[LifecycleOutcome] = []
+        changed = False
+
+        # Decide for every orphan and for anyone we are already tracking (so they can be re-enabled).
+        for mxid in sorted(orphaned_mxids | set(ledger.entries)):
+            entry = ledger.entries.get(mxid)
+            action = decide_account_action(
+                is_orphaned=mxid in orphaned_mxids,
+                marked_ts=entry.marked_for_disabling_timestamp if entry else None,
+                disabled_ts=entry.disabled_user_timestamp if entry else None,
+                now=now,
+                deactivate_after_n_sec=self.cfg.deactivate_after_n_sec,
+                delete_after_n_sec=self.cfg.delete_after_n_sec,
+            )
+            if action is LifecycleAction.none or action is LifecycleAction.wait:
+                continue
+            changed |= await self._apply(ledger, mxid, action, now)
+            outcomes.append(LifecycleOutcome(mxid=mxid, action=action, dry_run=self.cfg.dry_run))
+
+        if changed:
+            await self.store.save(ledger)
+        return outcomes
+
+    async def _apply(self, ledger: LifecycleLedger, mxid: str, action: LifecycleAction, now: float) -> bool:
+        """Carry out one decision; return whether the ledger changed. Destructive ops respect dry-run."""
+        if action is LifecycleAction.reenable:
+            # Restorative (only ever grants access back), so it runs even under dry-run — it undoes a
+            # prior real logout/lock. A no-op when nothing was locked.
+            await self.effectors.reenable(mxid)
+            ledger.entries.pop(mxid, None)
+            audit.info("re-enabled %s (Authentik account active again); cleared lifecycle state", mxid)
+            return True
+
+        if action is LifecycleAction.mark:
+            # Bookkeeping only — harmless to persist even in dry-run, and it starts the cooldown clock.
+            ledger.entries[mxid] = LifecycleEntry(marked_for_disabling_timestamp=now)
+            audit.info(
+                "marked %s for lifecycle action (Authentik account disabled); logout in %ss",
+                mxid,
+                self.cfg.deactivate_after_n_sec,
+            )
+            return True
+
+        if action is LifecycleAction.logout:
+            if self.cfg.dry_run:
+                audit.warning("DRY-RUN: would log out %s (revoke all sessions)", mxid)
+                return False
+            await self.effectors.logout(mxid)
+            entry = ledger.entries.setdefault(mxid, LifecycleEntry())
+            entry.disabled_user_timestamp = now
+            audit.warning(
+                "logged out %s (revoked all sessions); erase in %ss", mxid, self.cfg.delete_after_n_sec
+            )
+            return True
+
+        # action is LifecycleAction.erase
+        if self.cfg.dry_run:
+            audit.warning(
+                "DRY-RUN: would erase %s (deactivate account, delete_media=%s)",
+                mxid,
+                self.cfg.include_user_media_on_delete,
+            )
+            return False
+        await self.effectors.erase(mxid, delete_media=self.cfg.include_user_media_on_delete)
+        ledger.entries.pop(mxid, None)
+        audit.warning(
+            "erased %s (account deactivated, media=%s)", mxid, self.cfg.include_user_media_on_delete
+        )
+        return True

onbot/logging.py

@@ -0,0 +1,26 @@
+"""Structured logging setup.
+
+A thin, dependency-light wrapper over the stdlib ``logging`` module. Phase 2 keeps this
+minimal; a structured-logging backend can be slotted in later without changing call sites.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+_DEFAULT_FORMAT = "%(asctime)s %(levelname)-8s %(name)s: %(message)s"
+
+
+def configure_logging(level: str | int | None = None) -> None:
+    """Configure root logging once, honouring ``ONBOT_LOG_LEVEL`` when ``level`` is unset."""
+    if level is None:
+        level = os.environ.get("ONBOT_LOG_LEVEL", "INFO")
+    if isinstance(level, str):
+        level = logging.getLevelName(level.upper())
+    logging.basicConfig(level=level, format=_DEFAULT_FORMAT)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a module-scoped logger; prefer ``get_logger(__name__)`` at call sites."""
+    return logging.getLogger(name)

onbot/media.py

@@ -0,0 +1,46 @@
+"""Remote-URL → Matrix media upload with deduplication (G10.1, G10.2, Phase 6).
+
+Avatars (bot, rooms, the space) are configured as plain HTTP(S) URLs. To use them in Matrix they
+must be fetched and uploaded to the homeserver's media repo, which returns an ``mxc://`` URI. This
+helper does that and **deduplicates by source URL within a run**, so the same avatar URL is fetched
+and uploaded at most once (the legacy bot re-uploaded on every tick). Uploads go through the
+authenticated media endpoint on :class:`~onbot.clients.matrix.ApiClientMatrix` (MSC3916).
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from onbot.clients.matrix import ApiClientMatrix
+from onbot.logging import get_logger
+
+log = get_logger(__name__)
+
+_DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+
+class MediaUploader:
+    def __init__(self, client: ApiClientMatrix, *, http_client: httpx.AsyncClient | None = None) -> None:
+        self.client = client
+        self._http = http_client or httpx.AsyncClient(timeout=30.0, follow_redirects=True)
+        self._owns_http = http_client is None
+        # Source URL -> mxc URI, so a repeated URL uploads only once (G10.2).
+        self._cache: dict[str, str] = {}
+
+    async def upload_from_url(self, url: str) -> str:
+        """Fetch ``url`` and upload it, returning the ``mxc://`` URI (cached per source URL)."""
+        cached = self._cache.get(url)
+        if cached is not None:
+            return cached
+        response = await self._http.get(url)
+        response.raise_for_status()
+        raw_type = response.headers.get("content-type", _DEFAULT_CONTENT_TYPE).split(";")[0].strip()
+        content_type = raw_type or _DEFAULT_CONTENT_TYPE
+        mxc = await self.client.upload_media(response.content, content_type=content_type)
+        self._cache[url] = mxc
+        log.info("uploaded avatar %s -> %s", url, mxc)
+        return mxc
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()