onbot 0.1.0.dev0__py3-none-any.whl

onbot/reconciler/state.py

@@ -0,0 +1,77 @@
+"""Versioned onbot room-state schemas.
+
+The bot has no database; it persists its own bookkeeping as **custom Matrix room-state events**
+(AD-1 keeps this idea). Event types are namespaced with the reversed server name, e.g.
+``org.company.onbot.group_room``. Legacy stored these as bare, unversioned dicts; we give them
+explicit, validated pydantic schemas carrying a ``schema_version`` so future migrations are possible.
+
+This module is pure (no I/O): the reconciler reads/writes these via the Matrix client (Phase 4).
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+SCHEMA_VERSION = 1
+
+
+class OnbotRoomType(StrEnum):
+    space = "space"
+    group_room = "group_room"
+    direct_room = "direct_room"
+
+
+def event_type_name(server_name: str, room_type: OnbotRoomType | str) -> str:
+    """Fully-qualified custom state event type, e.g. ``org.company.onbot.group_room``.
+
+    Mirrors the legacy reversed-domain scheme so existing rooms keep matching.
+    """
+    rt = room_type.value if isinstance(room_type, OnbotRoomType) else room_type
+    reversed_domain = ".".join(reversed(server_name.split(".")))
+    return f"{reversed_domain}.onbot.{rt}"
+
+
+class _OnbotRoomState(BaseModel):
+    schema_version: int = SCHEMA_VERSION
+    authentik_server: str | None = None
+    avatar_source_url: str | None = None
+
+
+class SpaceRoomState(_OnbotRoomState):
+    room_type: Literal[OnbotRoomType.space] = OnbotRoomType.space
+
+
+class GroupRoomState(_OnbotRoomState):
+    room_type: Literal[OnbotRoomType.group_room] = OnbotRoomType.group_room
+    group_id: str
+
+
+class DirectRoomState(_OnbotRoomState):
+    room_type: Literal[OnbotRoomType.direct_room] = OnbotRoomType.direct_room
+    user_id: str
+    marked_for_disabling_timestamp: float | None = None
+    disabled_user_timestamp: float | None = None
+    welcome_messages_sent: dict[str, str] = Field(default_factory=dict)
+
+
+AnyRoomState = SpaceRoomState | GroupRoomState | DirectRoomState
+
+_STATE_MODEL_BY_TYPE: dict[OnbotRoomType, type[AnyRoomState]] = {
+    OnbotRoomType.space: SpaceRoomState,
+    OnbotRoomType.group_room: GroupRoomState,
+    OnbotRoomType.direct_room: DirectRoomState,
+}
+
+
+def parse_room_state(room_type: OnbotRoomType, content: dict[str, Any]) -> AnyRoomState:
+    """Validate raw state-event content into the matching schema for ``room_type``."""
+    model = _STATE_MODEL_BY_TYPE[room_type]
+    return model.model_validate(content)
+
+
+def dump_room_state(state: AnyRoomState) -> dict[str, Any]:
+    """Serialise a room-state model to JSON-able content for a Matrix state event."""
+    return state.model_dump(mode="json")

onbot/utils.py

@@ -0,0 +1,61 @@
+"""Small, dependency-free helpers.
+
+Ported from legacy ``onbot/utils.py`` — we keep the nested-dict helpers (used pervasively to read
+dotted attribute paths out of Authentik objects) and drop the legacy ``synchronize_async_helper``
+sync/async bridge (AD-7: async everything) and the ``requests``-based media download (Phase 6,
+authenticated media). The ``Any``-as-sentinel hack is replaced with an explicit ``_MISSING`` marker.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Final
+
+
+class _Missing:
+    """Sentinel distinguishing 'no fallback given' from a ``None`` fallback."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return "<MISSING>"
+
+
+_MISSING: Final = _Missing()
+
+
+def get_nested_dict_val_by_path(
+    data: dict[str, Any],
+    key_path: Sequence[str],
+    fallback_val: Any = _MISSING,
+) -> Any:
+    """Read a nested value via a key path (e.g. ``["attributes", "matrix_name"]``).
+
+    Raises ``KeyError`` if the path is absent and no ``fallback_val`` was provided.
+    """
+    current: Any = data
+    for key in key_path:
+        try:
+            current = current[key]
+        except KeyError, TypeError:
+            if fallback_val is _MISSING:
+                raise KeyError(key) from None
+            return fallback_val
+    return current
+
+
+def dict_has_nested_attr(
+    data: dict[str, Any],
+    key_path: Sequence[str],
+    *,
+    must_have_val: bool = False,
+) -> bool:
+    """Return whether ``data`` has the nested ``key_path`` (and a truthy value if ``must_have_val``)."""
+    current: Any = data
+    for key in key_path:
+        if not isinstance(current, dict) or key not in current:
+            return False
+        current = current[key]
+    if must_have_val:
+        return bool(current)
+    return True

onbot-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.1
+Name: onbot
+Version: 0.1.0.dev0
+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
+
+A bot that keeps a **Matrix (Synapse)** homeserver continuously in sync with an
+**[Authentik](https://goauthentik.io/)** identity provider and onboards every new user into the
+right rooms with a friendly welcome. Authentik is the source of truth; Matrix mirrors it
+(group → room, group membership → room membership, power levels), and new users get guided in with a
+1:1 welcome DM.
+
+Onbot targets **Matrix 2.0**: it assumes a [**Matrix Authentication Service
+(MAS)**](https://element-hq.github.io/matrix-authentication-service/) deployment with Authentik as
+an *upstream identity provider*, uses authenticated media, and drives the Client-Server and admin
+APIs over a single async HTTP client (no `matrix-nio`).
+
+See [`GOALS.md`](GOALS.md) for intent, [`BATTLE_PLAN.md`](BATTLE_PLAN.md) for the build plan, and
+[`docs/adr/`](docs/adr/) for the architecture decisions.
+
+> ⚠️ **Release blocker (maintainer):** the Phase 1 security items are **not done** — leaked
+> credentials in git history still need rotating and the history scrubbing
+> ([`BATTLE_PLAN.md`](BATTLE_PLAN.md) §5 Phase 1). **Do not publish an image or tag a release until
+> those are complete.** The packaging below is ready; the security hand-off is the gate.
+
+---
+
+## How it works — the MAS auth topology
+
+The auth chain is **Matrix client → MAS → Authentik** (ADR-[0006](docs/adr/0006-auth-topology-mas-authentik.md)):
+
+```
+                   logs in via                      upstream IdP
+   Matrix client ───────────────▶  MAS  ◀───────────────────────  Authentik
+        ▲                           │  (provisions Matrix accounts   (source of truth:
+        │                           │   on first login)               users & groups)
+        │ welcome DM,               │
+        │ room membership      ┌────┴─────┐
+        └──────────────────────│  Onbot   │── reads users/groups ──▶ Authentik API
+                               └────┬─────┘
+                                    └── Synapse Admin API + CS API ──▶ Synapse  ◀─ MAS
+```
+
+Consequences that shape how you configure Onbot:
+
+- **Onbot does not create accounts.** MAS auto-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, and group/role attributes into power levels — plus the
+  quarantined offboarding lifecycle.
+- **The MXID localpart contract is critical.** Onbot computes a user's MXID
+  (`@<localpart>:server_name`) from an Authentik attribute, and it **must match the localpart
+  template MAS uses** when it provisions accounts from the same Authentik claim. Set
+  [`sync_authentik_users_with_matrix_rooms.authentik_username_mapping_attribute`](docs/CONFIG_REFERENCE.md)
+  to agree with MAS — get it wrong and Onbot's computed MXIDs won't match the real accounts, so
+  nobody gets added to rooms. (Verified by the integration suite's localpart-contract test.)
+- **Lifecycle enforcement requires MAS.** When Authentik disables a user, MAS blocks *new* logins
+  but **existing Matrix sessions keep working**, and the *Synapse* admin API cannot revoke a
+  MAS-issued session — only MAS can (ADR-[0005](docs/adr/0005-quarantine-lifecycle.md), §7 Q1, proven
+  empirically). So to actually offboard a disabled user you must configure the
+  [`mas_admin`](docs/CONFIG_REFERENCE.md) block. Without it, offboarding is a **no-op against live
+  sessions** (it silently fails to revoke).
+
+---
+
+## Configuration
+
+Configuration is a single YAML file validated by a [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
+model ([`onbot/config.py`](onbot/config.py)). Every setting can also be supplied (or overridden) via
+an environment variable: prefix `ONBOT_`, nest with `__`. E.g.
+`ONBOT_SYNAPSE_SERVER__BOT_ACCESS_TOKEN=syt_…`.
+
+- **Full reference:** [`docs/CONFIG_REFERENCE.md`](docs/CONFIG_REFERENCE.md) — every field, its type,
+  default, description and `ONBOT_*` env-var name.
+- **Annotated template:** [`config.example.yml`](config.example.yml) — a commented, fillable YAML
+  template. Copy it to `config.yml` and fill in the required values.
+
+Both are **generated from the model** (with [psyplus](https://pypi.org/project/psyplus/)) and kept in
+sync by CI — regenerate after editing `onbot/config.py`:
+
+```bash
+pdm run gen-config-docs      # rewrite docs/CONFIG_REFERENCE.md + config.example.yml
+pdm run check-config-docs    # fail if they drift from the model (runs in CI)
+```
+
+> 🔐 **Never commit a real config.** `config*.yml` is gitignored (only `config.example.yml` is
+> tracked) and the Docker image carries no secrets — provide config at runtime.
+
+### Bot credentials (pick one)
+
+Onbot authenticates to Synapse as a bot user. Under MAS, choose one of:
+
+| Option | Field | When |
+|---|---|---|
+| **Compatibility token** | `synapse_server.bot_access_token` | Near-term. Issue with `mas-cli manage issue-compatibility-token`. Provide the bare token. |
+| **OAuth2 client-credentials** | `synapse_server.oauth2` | Forward-looking. The bot is a confidential MAS client and refreshes tokens automatically. |
+
+Provide **exactly one**. The same identity drives both the Synapse Admin API and the Client-Server
+API.
+
+### Minimal `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 (internal URL is fine)
+  bot_user_id: "@welcome-bot:company.org"
+  bot_access_token: syt_REPLACE_ME          # or use an `oauth2:` block instead
+
+authentik_server:
+  url: https://authentik.company.org/
+  api_key: REPLACE_ME                        # 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
+```
+
+See [`config.example.yml`](config.example.yml) for everything else (room mapping rules, power
+levels, welcome messages, the dry-run lifecycle defaults, ignore lists, …).
+
+---
+
+## Run with Docker
+
+The published image runs as a non-root user and ships only runtime dependencies (no crypto stack —
+the bot operates outside encrypted rooms, ADR-[0009](docs/adr/0009-e2ee-stance.md)).
+
+```bash
+docker run --rm \
+  -v "$PWD/config.yml:/config/config.yml:ro" \
+  ghcr.io/dzd-ev-diabetes-research/matrix-synapse-authentik-onbaording-bot:latest
+```
+
+The image defaults to `ONBOT_CONFIG_FILE_PATH=/config/config.yml` and the `run` command. It has a
+built-in `HEALTHCHECK` that calls `onbot healthcheck` (see below).
+
+### docker-compose
+
+```yaml
+services:
+  onbot:
+    image: ghcr.io/dzd-ev-diabetes-research/matrix-synapse-authentik-onbaording-bot:latest
+    restart: unless-stopped
+    volumes:
+      - ./config.yml:/config/config.yml:ro
+    # Or skip the file and supply everything via env (no secrets on disk):
+    # environment:
+    #   ONBOT_SYNAPSE_SERVER__SERVER_NAME: company.org
+    #   ONBOT_SYNAPSE_SERVER__BOT_ACCESS_TOKEN: ${ONBOT_BOT_TOKEN}
+```
+
+### CLI commands
+
+```
+onbot run               # long-running service: reconcile loop + event-driven onboarding (default)
+onbot reconcile-once    # one idempotent reconcile pass, then exit
+onbot generate-config   # print a minimal config template (use config.example.yml for the rich one)
+onbot healthcheck       # probe Synapse/Authentik/MAS with the real credentials; exit 0 healthy, 1 not
+```
+
+`onbot healthcheck` is what the container's `HEALTHCHECK` runs: it issues one authenticated request
+to the Matrix CS API (`/whoami`), the Synapse admin API, the Authentik API, and — when `mas_admin`
+is configured — the MAS admin API, and exits non-zero if any is unreachable or rejects the
+credentials.
+
+---
+
+## Develop
+
+Requires **Python 3.14** and **[PDM](https://pdm-project.org/)**.
+
+```bash
+pdm install                 # create the venv and install deps (incl. dev + docs)
+pdm run pre-commit install  # enable lint + secret-scan hooks
+```
+
+### Run & test
+
+```bash
+pdm run onbot --help
+pdm run onbot reconcile-once
+
+pdm run pytest -m "not integration"     # fast unit + contract suite
+pdm run pytest                          # full suite incl. live Synapse+MAS+Authentik (needs Docker)
+pdm run ruff check .                     # lint
+pdm run ruff format --check .            # formatting
+pdm run mypy onbot                       # type check
+```
+
+The `run_*.sh` helper scripts at the repo root wrap the same PDM commands.
+
+### Build the image locally
+
+```bash
+docker build -t onbot:dev .
+docker run --rm onbot:dev --help
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Users never get added to rooms | The MXID localpart contract is broken — `authentik_username_mapping_attribute` doesn't match MAS's localpart template, so computed MXIDs don't exist. |
+| Disabled users keep their Matrix access | `mas_admin` is not configured (the Synapse admin API can't revoke a MAS session), or lifecycle `dry_run` is still `true` (the default). |
+| Nothing destructive ever happens | Expected by default — the lifecycle is quarantined (`dry_run: true`); it only logs to the `onbot.lifecycle.audit` channel until you opt in. |
+| Welcome DM send fails with a 500 | The bot device isn't registered yet — Onbot registers it on startup (`ensure_device_registered`); check startup logs. |
+| `healthcheck` reports a dependency FAIL | Read the per-dependency log line; it distinguishes unreachable from auth-rejected. The `matrix-cs` line also flags a token/`bot_user_id` mismatch. |
+| Sliding sync unavailable | The homeserver doesn't advertise MSC4186; Onbot falls back to the reconciler signal path automatically. |
+
+---
+
+## Releasing
+
+Versioned images are published to GHCR by the [release workflow](.github/workflows/release.yml) when
+a `v*` tag is pushed. See [`CHANGELOG.md`](CHANGELOG.md) and the workflow's header comment for the
+tag/version flow. **(Blocked on the Phase 1 security hand-off — see the note at the top.)**
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

onbot-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,38 @@
+onbot-0.1.0.dev0.dist-info/METADATA,sha256=pI9PGj7lF4Gt2wmN_TRK6wA9KHew7B_AqeHRNyiwLJ4,11164
+onbot-0.1.0.dev0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+onbot-0.1.0.dev0.dist-info/entry_points.txt,sha256=DGrxm-JKvVp239mGhGJC9xY-IvC-2AjjrdUg0L6yQXs,57
+onbot-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=TuZlsZ-MBR0SxDZR0I8eTSMK2oI-UPKSs8Du8cSpxU0,1101
+onbot/__init__.py,sha256=PCI_AaMaoMIOSBLYD-84-oi2NaJ4vv5gKcOQr89b8w0,292
+onbot/__main__.py,sha256=GO4R6IprVZwwwH3glDpQrNz2_MU0BrnN75lKDIDfaPc,119
+onbot/app.py,sha256=_x-hJdEUQww4rHNLPTdL7XqKAP89nx3vlWqvmBsJRak,7046
+onbot/auth/__init__.py,sha256=ur6qmM7E1fNUpxw2OaVr7vIxQK_EgurweB1knp9Afj8,496
+onbot/auth/token_provider.py,sha256=1RjflnWDT2zubQH-wdvb9v251jbfDnm8mJ7PHmhOPdo,5958
+onbot/cli.py,sha256=iiZ5Vk0ZQYH7o0BtTGmyn7mLFTSrD3LwIpSCrpBnvsE,3048
+onbot/clients/__init__.py,sha256=2bZ_RF_0vjzaLj-Q8g8HWKJaS3fjZBBQT2ni7_vE3fQ,263
+onbot/clients/authentik.py,sha256=DvBVgdKX6oxe0reXJ7_FmUNfd0_op-tnW-JfGenSbM8,4812
+onbot/clients/base.py,sha256=8WSzLBuYXSWJJYnN5ZAyPY-k4_H7Nex5LQr3II41vq0,9302
+onbot/clients/mas_admin.py,sha256=Snc76PcnIqT4PwUs4nH4OzK6Mv4x_T1ennHI8wwiLhI,2594
+onbot/clients/matrix.py,sha256=WEwwnm3q9fmbc0vPfCGFHxbgfS_84OG6HWes-jlNJ3c,19693
+onbot/clients/synapse_admin.py,sha256=kfrQtfy5M5Qq-sir1U4wRWFAiszMBsw9nJWTff-V56w,7467
+onbot/clients/versions.py,sha256=RzM6BilIJLwCzjT7kuo-wrzF4o00DU4nqKQruETd5iU,2668
+onbot/config.py,sha256=zq5Tk9kn7n6nz5WZTGkwO0U5kO86U7XgtFX07cVRw3o,26634
+onbot/events.py,sha256=MTBBZ1bcWVukZzVwI4suqgzXluQy9PTLfwyHdEX2CnM,1563
+onbot/healthcheck.py,sha256=loZWenxjg4H0nR9DcxDEdPFfHKinQ0zTQQzEvNwMlXk,5530
+onbot/identity.py,sha256=ggK4pqmxvjMhPwFXRSAqJIectz8P0McU2DHDMLQ9M2I,1809
+onbot/lifecycle/__init__.py,sha256=E8vfTN8AOjQO6c0wb1lKK26PaYG78-Phcidn5_AkbLk,148
+onbot/lifecycle/accounts.py,sha256=6gIZOMZhfpnTa8471fW-jjF735i2x7gtw8lfLSty_uY,13269
+onbot/logging.py,sha256=qASVDwcQLj4xowUL3lnETp7gkMWjdtAiAQ28k5amqG4,899
+onbot/media.py,sha256=Uh53B_-HePoIXxCKVLcOBfJldDVHRDTiX_Ea-3XJ4Mo,1981
+onbot/models.py,sha256=GyJelGYy2_5nZLMkKNnlA_dsIIyga720bF0kootlIfk,2092
+onbot/onboarding/__init__.py,sha256=y4lt5sP_HhC7nfAKFTJLEoDWTfH1AUT_PY5R_SSzniI,267
+onbot/onboarding/listener.py,sha256=fEh5wNfxABth8JpSpM3DTAuStN6ef_d3hRqVGh38tiY,4024
+onbot/onboarding/welcome.py,sha256=Nzo9q29m7Lhq2AUAJjzlsa5ZaDmWps6KQFcq5zjgYnE,5001
+onbot/reconciler/__init__.py,sha256=3X9zZTz6v6y1CgX6LSuBs_R4JOy2g6BEJdOR2CvQfs4,179
+onbot/reconciler/effectors.py,sha256=9Ys6FaPMhDQIU71FayOcog0K2U7WpgQXp4kMdWRkIN8,3499
+onbot/reconciler/engine.py,sha256=05T27P_ccxmIf-dkkYWulPYFW-J8IK-TAP1-v4N4T1U,15905
+onbot/reconciler/membership.py,sha256=gLuH7pIYFpCWYqG8y6xHQucyGRmfav643sCe5GV473M,1938
+onbot/reconciler/power_levels.py,sha256=HKlPLNNcxnc5e_2JS0SLC13GNgYEHQ6pYWKsfXhgkks,3524
+onbot/reconciler/rooms.py,sha256=kjNnul402Nwg11DCe29Ypo5c_V2oIbmE-9zq8AINS1g,5262
+onbot/reconciler/state.py,sha256=vqzy6JKCm45fe7CwpNGGYjsx7Hsg91uIHgcyQjvJQ1Q,2669
+onbot/utils.py,sha256=xFHB-7MfFzxj_NJ5AYx4BRf-wAbhUaSp7PlhHG0p7Rs,1839
+onbot-0.1.0.dev0.dist-info/RECORD,,

onbot-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.9)
+Root-Is-Purelib: true
+Tag: py3-none-any

onbot-0.1.0.dev0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+onbot = onbot.cli:main
+
+[gui_scripts]
+

onbot-0.1.0.dev0.dist-info/licenses/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.