onbot 0.1.0.dev0__py3-none-any.whl

onbot/config.py

@@ -0,0 +1,653 @@
+"""Configuration model (pydantic-settings).
+
+Ported and refined from the legacy ``onbot/config.py`` (AD-1, reuse-the-config decision).
+Changes from legacy:
+
+* pydantic v2 / ``pydantic-settings`` v2 (``SettingsConfigDict``) and modern ``X | None`` typing.
+* Removed the duplicated top-level ``DeactivateDisabledAuthentikUsersInMatrix`` block — the
+  lifecycle settings live solely under :class:`SyncAuthentikUsersWithMatrix` where they are read.
+* Fixed legacy type/default bugs (``sync_only_users_of_groups_with_id`` defaulted to ``None`` on a
+  non-optional ``list``; ``only_groups_with_attributes`` / ``only_for_groupnames_starting_with``
+  carried list defaults on non-list fields).
+* No ``matrix-nio`` references — the Matrix client library is a Phase 6 decision (AD, BATTLE_PLAN §5).
+* Phase 8: dropped the vestigial ``storage_dir`` / ``storage_encryption_key`` fields — they backed
+  the libolm key store, which ADR-0009 removed (the bot operates outside encrypted rooms and keeps
+  no on-disk crypto state). They were unused everywhere in the codebase; the lifecycle ledger lives
+  in Matrix account data (ADR-0001, no DB). Every field carries a description + example so the
+  psyplus-generated config reference and YAML template are self-documenting (BATTLE_PLAN §5 Phase 8).
+
+Loading: :func:`load_config` reads the YAML at ``ONBOT_CONFIG_FILE_PATH`` (env overrides still apply
+via the ``ONBOT_`` prefix and ``__`` nesting delimiter); :func:`generate_example_config` dumps the
+default model to YAML (G11.2).
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import yaml
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+CONFIG_FILE_ENV_VAR = "ONBOT_CONFIG_FILE_PATH"
+
+
+class MatrixOAuth2(BaseModel):
+    """OAuth2 client-credentials auth against MAS (AD-6, Phase 6).
+
+    The forward-looking alternative to a static compatibility token: the bot is a confidential
+    OAuth2 client of MAS and mints short-lived access tokens that refresh transparently. When this
+    block is set it takes precedence over ``bot_access_token``.
+    """
+
+    token_endpoint: Annotated[
+        str,
+        Field(
+            description="MAS OAuth2 token endpoint (the ``token_endpoint`` from MAS discovery).",
+            examples=["https://auth.company.org/oauth2/token"],
+        ),
+    ]
+    client_id: Annotated[
+        str,
+        Field(description="OAuth2 client id registered for the bot in MAS."),
+    ]
+    client_secret: Annotated[
+        str,
+        Field(description="OAuth2 client secret for the bot client. Provide the bare secret."),
+    ]
+    scope: Annotated[
+        str | None,
+        Field(
+            description="Optional space-separated scopes to request (e.g. the Synapse admin scope).",
+            examples=["urn:matrix:org.matrix.msc2967.client:api:* urn:synapse:admin:*"],
+        ),
+    ] = None
+
+
+class MasAdmin(BaseModel):
+    """MAS admin API credentials for lifecycle enforcement (ADR-0005/0006, §7 Q1).
+
+    Under MAS the Matrix token is owned by MAS, so the Synapse admin API cannot revoke a live
+    session — only MAS can (lock/deactivate). When this block is set, the lifecycle module enforces
+    lockout through the MAS admin API using an OAuth2 ``client_credentials`` token with the
+    ``urn:mas:admin`` scope (the client must be listed in MAS ``policy.data.admin_clients``). Leave
+    unset to fall back to the Synapse-admin effectors (which do NOT revoke MAS sessions).
+    """
+
+    url: Annotated[
+        str,
+        Field(
+            description="Base URL of the Matrix Authentication Service.",
+            examples=["https://auth.company.org"],
+        ),
+    ]
+    client_id: Annotated[
+        str,
+        Field(description="OAuth2 client id of the bot's MAS admin client (client_credentials)."),
+    ]
+    client_secret: Annotated[
+        str,
+        Field(description="OAuth2 client secret of the bot's MAS admin client."),
+    ]
+
+
+class SynapseServer(BaseModel):
+    server_name: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """Synapse's public facing domain
+                https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#server_name
+                This is not necessarily the domain under which the Synapse server is reachable."""
+            ),
+            examples=["company.org"],
+        ),
+    ]
+    server_url: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """URL to reach the Synapse server. This can (and should) be an internal URL, so the
+                Synapse admin API need not be public. The bot works with a public URL too."""
+            ),
+            examples=["https://internal.matrix"],
+        ),
+    ]
+    bot_user_id: Annotated[
+        str,
+        Field(
+            description="Full Matrix user ID of an existing account; the bot acts as this user.",
+            examples=["@welcome-bot:company.org"],
+        ),
+    ]
+    bot_access_token: Annotated[
+        str | None,
+        Field(
+            description=inspect.cleandoc(
+                """Access token authorising the bot against the Synapse APIs. Under MAS this is a
+                compatibility token issued via ``mas-cli manage issue-compatibility-token`` (AD-6).
+                Provide the bare token; do not prefix it with ``Bearer`` (the client adds that).
+                Leave unset (``null``) when using ``oauth2`` instead."""
+            ),
+            examples=["syt_ONLY_AN_EXAMPLE_TOKEN_sadaw4"],
+        ),
+    ] = None
+    oauth2: Annotated[
+        MatrixOAuth2 | None,
+        Field(
+            description=inspect.cleandoc(
+                """Optional OAuth2 client-credentials auth against MAS (AD-6). When set, it is used
+                instead of ``bot_access_token`` and tokens refresh automatically. Provide exactly one
+                of ``bot_access_token`` or ``oauth2``."""
+            ),
+        ),
+    ] = None
+    bot_avatar_url: Annotated[
+        str | None,
+        Field(
+            description="HTTP URL to a picture; the bot sets it as its own avatar on start.",
+            examples=["https://sillyimages.com/face.png"],
+        ),
+    ] = None
+    admin_api_path: Annotated[
+        str,
+        Field(
+            description="Sub-path the Synapse admin API is served under. Keep the default if unsure.",
+            examples=["_synapse/admin/"],
+        ),
+    ] = "_synapse/admin/"
+
+
+class AuthentikServer(BaseModel):
+    url: Annotated[
+        str,
+        Field(
+            description="URL to reach your Authentik server.",
+            examples=["https://authentik.company.org/"],
+        ),
+    ]
+    api_key: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """API token for your Authentik server. Generate one at
+                ``https://<authentik>/if/admin/#/core/tokens``. Provide the bare token; the client
+                adds the ``Bearer`` prefix."""
+            ),
+            examples=["yEl4tFqeIBQwoHAd9hajmkm2PBjSAirY_THIS_IS_JUST_AN_EXAMPLE_i57e"],
+        ),
+    ]
+
+
+class DeactivateDisabledAuthentikUsersInMatrix(BaseModel):
+    """Lifecycle settings (Phase 5 — quarantined, dry-run/audit default; AD-5)."""
+
+    enabled: Annotated[
+        bool,
+        Field(
+            description="Lock out Matrix accounts whose Authentik account was disabled/deleted.",
+        ),
+    ] = True
+    dry_run: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """Quarantine switch (AD-5): while ``true`` the bot only records bookkeeping and logs
+                what it *would* do to the ``onbot.lifecycle.audit`` channel — no session is revoked
+                and no account is deactivated. Set ``false`` to actually perform destructive
+                lifecycle actions. Defaults to ``true`` so destructive offboarding is opt-in."""
+            ),
+        ),
+    ] = True
+    deactivate_after_n_sec: Annotated[
+        int,
+        Field(
+            description="Cooldown before deactivation, to absorb accidental upstream disables.",
+        ),
+    ] = 60 * 60 * 24
+    delete_after_n_sec: Annotated[
+        int | None,
+        Field(
+            description="Further cooldown before erase/delete. ``null`` disables deletion.",
+        ),
+    ] = 60 * 60 * 24 * 365
+    include_user_media_on_delete: Annotated[
+        bool,
+        Field(
+            description="Also delete media uploaded by the user on account deletion (data protection).",
+        ),
+    ] = False
+
+
+class SyncAuthentikUsersWithMatrix(BaseModel):
+    """How Authentik users/groups are projected into Matrix room membership (the core sync)."""
+
+    enabled: Annotated[
+        bool,
+        Field(description="Master switch for projecting Authentik group membership into Matrix rooms."),
+    ] = True
+    authentik_username_mapping_attribute: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """Source of the localpart of the Matrix ID (``@<localpart>:server``). A dotted path
+                into the Authentik user object (e.g. ``username`` or ``attributes.matrix_name``).
+                Under MAS this MUST agree with the localpart template MAS derives from the upstream
+                claim, or provisioned users will not match (AD-6)."""
+            ),
+        ),
+    ] = "username"
+    kick_matrix_room_members_not_in_mapped_authentik_group_anymore: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """When a user leaves an Authentik group, kick them from the corresponding Matrix
+                room so membership stays a faithful mirror. Disable to let the bot only ever *add*
+                members (never remove)."""
+            ),
+        ),
+    ] = True
+    sync_only_users_in_authentik_pathes: Annotated[
+        list[str] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Restrict syncing to users under these Authentik directory paths. ``null`` syncs
+                users regardless of path."""
+            ),
+            examples=[["users", "users/staff"]],
+        ),
+    ] = None
+    sync_only_users_with_authentik_attributes: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Only sync users carrying all of these Authentik attributes (exact match).
+                ``null`` syncs every user."""
+            ),
+            examples=[{"is_chat_user": True}],
+        ),
+    ] = None
+    sync_only_users_of_groups_with_id: Annotated[
+        list[str] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Only sync users who belong to at least one of these Authentik groups (by pk).
+                ``null`` applies no group filter."""
+            ),
+            examples=[["1120a6e1124f309bbe96c8be5fb09eab"]],
+        ),
+    ] = None
+    deactivate_disabled_authentik_users_in_matrix: Annotated[
+        DeactivateDisabledAuthentikUsersInMatrix,
+        Field(
+            description="Quarantined lifecycle settings: lock out Matrix accounts disabled upstream.",
+        ),
+    ] = Field(default_factory=DeactivateDisabledAuthentikUsersInMatrix)
+
+
+class CreateMatrixSpaceIfNotExists(BaseModel):
+    enabled: bool = Field(
+        default=True,
+        description="Create the parent space if it does not exist.",
+    )
+    name: str = Field(default="OnBotSpace", description="Display name of the space.")
+    topic: str = Field(
+        default="Space for authentik group rooms",
+        description="Matrix topic (tagline) for the space.",
+    )
+    avatar_url: str | None = Field(
+        default=None,
+        description="HTTP(S) URL to a picture used as the space avatar.",
+    )
+    space_params: dict[str, Any] = Field(
+        default_factory=lambda: {"preset": "private_chat", "visibility": "private"},
+        description="Extra parameters passed to the space-creation call.",
+    )
+
+
+class CreateMatrixRoomsInAMatrixSpace(BaseModel):
+    enabled: bool = Field(
+        default=True,
+        description="Gather all Authentik-group rooms under a dedicated parent space.",
+    )
+    alias: str = Field(
+        default="OnBotSpace",
+        description='Localpart of the space canonical alias (e.g. "#<alias>:server").',
+        examples=["myspace", "companyspace"],
+    )
+    create_matrix_space_if_not_exists: CreateMatrixSpaceIfNotExists = Field(
+        default_factory=CreateMatrixSpaceIfNotExists,
+        description="Whether/how the parent space is created.",
+    )
+
+
+class SyncMatrixRoomsBasedOnAuthentikGroups(BaseModel):
+    """Which Authentik groups become Matrix rooms, and how their power levels are derived."""
+
+    enabled: Annotated[
+        bool,
+        Field(description="Master switch for creating/maintaining one Matrix room per Authentik group."),
+    ] = True
+    only_for_children_of_groups_with_uid: Annotated[
+        list[str] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Only mirror Authentik groups that are children of one of these parent groups (by
+                uid/pk). ``null`` considers all groups."""
+            ),
+            examples=[["a1b2c3d4parentgroupuid"]],
+        ),
+    ] = None
+    only_groups_with_attributes: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Only mirror Authentik groups carrying these custom attributes. If unset, all
+                groups become rooms. https://goauthentik.io/docs/user-group/group#attributes"""
+            ),
+            examples=[{"is_chatroom": True}],
+        ),
+    ] = None
+    room_avatar_url_attribute: Annotated[
+        str | None,
+        Field(
+            description="Authentik group attribute holding a URL used as the room avatar.",
+            examples=["chatroom_avatar_url"],
+        ),
+    ] = "chatroom_avatar_url"
+    only_for_groupnames_starting_with: Annotated[
+        str | None,
+        Field(
+            description=inspect.cleandoc(
+                """Only mirror Authentik groups whose name starts with this prefix — a lightweight way
+                to opt specific groups into chat without custom attributes. ``null`` disables the
+                filter."""
+            ),
+            examples=["chat-", "matrix_"],
+        ),
+    ] = None
+    disable_rooms_when_mapped_authentik_group_disappears: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """If a mapped Authentik group disappears (deleted or lost its matching attribute),
+                kick all members and block the room."""
+            ),
+        ),
+    ] = False
+    delete_disabled_rooms: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """When a room is disabled (its Authentik group disappeared, see
+                ``disable_rooms_when_mapped_authentik_group_disappears``), also delete it via the
+                Synapse admin API rather than only blocking it. Irreversible — leave ``false`` unless
+                you are sure."""
+            ),
+        ),
+    ] = False
+    make_authentik_superusers_matrix_room_admin: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """Grant Authentik superusers the Matrix admin power level (100) in the rooms they are
+                members of. Takes precedence over ``authentik_group_attr_for_matrix_power_level``."""
+            ),
+        ),
+    ] = True
+    authentik_group_attr_for_matrix_power_level: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """Authentik group attribute (dotted path) holding an integer 0-100. Members of the
+                group get that Matrix power level in their onbot rooms. Superusers made admin (see
+                ``make_authentik_superusers_matrix_room_admin``) ignore this. On conflicting values
+                across multiple group memberships the highest wins."""
+            ),
+            examples=["matrix-userpowerlevel", "synapse-options.chat-powerlevel"],
+        ),
+    ] = "chat-systemwide-powerlevel"
+
+
+class MatrixDynamicRoomSettings(BaseModel):
+    """Template for how a Matrix room's identity (alias/name/topic/encryption/create params) is
+    derived from its Authentik group. Used as the default for all rooms and overridable per group
+    via ``per_authentik_group_pk_matrix_room_settings``."""
+
+    alias_prefix: Annotated[
+        str | None,
+        Field(
+            description="Prefix prepended to the room's canonical alias localpart. ``null`` for none.",
+            examples=["authentik-", "grp-"],
+        ),
+    ] = None
+    matrix_alias_from_authentik_attribute: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """Authentik group attribute (dotted path) used as the room alias localpart. The
+                default ``pk`` is the most stable choice (it never changes when a group is renamed)."""
+            ),
+            examples=["pk", "attributes.chatroom_alias"],
+        ),
+    ] = "pk"
+    name_prefix: Annotated[
+        str | None,
+        Field(
+            description="Prefix prepended to the room's display name. ``null`` for none.",
+            examples=["[Chat] "],
+        ),
+    ] = None
+    matrix_name_from_authentik_attribute: Annotated[
+        str,
+        Field(
+            description="Authentik group attribute (dotted path) used as the room display name.",
+            examples=["name", "attributes.chatroom_name"],
+        ),
+    ] = "name"
+    topic_prefix: Annotated[
+        str | None,
+        Field(description="Prefix prepended to the room topic. ``null`` for none."),
+    ] = None
+    matrix_topic_from_authentik_attribute: Annotated[
+        str | None,
+        Field(
+            description=inspect.cleandoc(
+                """Authentik group attribute (dotted path) used as the room topic. ``null`` leaves the
+                topic unset."""
+            ),
+            examples=["attributes.chatroom_topic"],
+        ),
+    ] = "attributes.chatroom_topic"
+    end2end_encryption_enabled: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """Enable end-to-end encryption in the group-mapped Matrix rooms. The bot itself stays
+                outside encryption (ADR-0009): it writes room *state* (membership, power levels) but
+                does not read/post message content in encrypted rooms — welcome DMs are plaintext."""
+            ),
+        ),
+    ] = True
+    default_room_create_params: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Parameters merged into the Matrix ``createRoom`` call for group rooms (preset,
+                visibility, federation, …). See the Client-Server API ``POST /createRoom``."""
+            ),
+            examples=[{"preset": "private_chat", "visibility": "private"}],
+        ),
+    ] = Field(default_factory=lambda: {"preset": "private_chat", "visibility": "private"})
+    matrix_room_create_params_from_authentik_attribute: Annotated[
+        str | None,
+        Field(
+            description=inspect.cleandoc(
+                """Authentik group attribute (dotted path) holding a dict of extra ``createRoom``
+                params, merged over ``default_room_create_params`` for that group. ``null`` to
+                disable per-group overrides."""
+            ),
+            examples=["attributes.chatroom_params"],
+        ),
+    ] = "attributes.chatroom_params"
+    keep_updating_matrix_attributes_from_authentik: Annotated[
+        bool,
+        Field(
+            description="Keep room name/topic in sync with Authentik, overwriting drift.",
+        ),
+    ] = True
+
+
+class OnbotConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="ONBOT_", env_nested_delimiter="__")
+
+    log_level: Annotated[
+        Literal["INFO", "DEBUG"],
+        Field(
+            description="Logging verbosity. ``DEBUG`` is noisy but useful while wiring up the bot.",
+            examples=["INFO", "DEBUG"],
+        ),
+    ] = "INFO"
+    server_tick_rate_sec: Annotated[
+        int,
+        Field(
+            description=inspect.cleandoc(
+                """How often (seconds) the reconciler re-converges Authentik→Matrix state, in
+                addition to on-demand triggers. The reconcile is idempotent (AD-2), so this is a
+                safety net for drift, not the only path — onboarding still reacts to live events."""
+            ),
+            examples=[20, 300],
+        ),
+    ] = 20
+
+    synapse_server: Annotated[
+        SynapseServer,
+        Field(
+            title="Synapse Server Configuration",
+            description="Authorization/connection data for the Matrix CS and Synapse admin APIs.",
+        ),
+    ]
+    authentik_server: Annotated[
+        AuthentikServer,
+        Field(description="Connection data and API token for the upstream Authentik IdP (source of truth)."),
+    ]
+
+    mas_admin: Annotated[
+        MasAdmin | None,
+        Field(
+            description=inspect.cleandoc(
+                """Optional MAS admin API credentials. Required for the lifecycle module to actually
+                revoke sessions / deactivate accounts under MAS — the Synapse admin API cannot
+                (ADR-0005, BATTLE_PLAN §7 Q1). Leave unset on non-MAS deployments."""
+            ),
+        ),
+    ] = None
+
+    welcome_new_users_messages: Annotated[
+        list[str] | None,
+        Field(
+            description=inspect.cleandoc(
+                """Messages the bot sends, in order, in the 1:1 welcome DM to each newly onboarded
+                user. Each message is sent once (content-hashed, idempotent). ``null`` or an empty
+                list disables the welcome DM entirely."""
+            ),
+        ),
+    ] = Field(
+        default_factory=lambda: [
+            "Welcome to the company chat. I am the company bot. I will invite you to the groups you "
+            "are assigned to. If you have any technical questions write a message to "
+            "@admin-person:matrix.company.org.",
+            "If you need guidance on how to use this chat have a look at the official documentation: "
+            "https://matrix.org/docs/chat_basics/matrix-for-im/ and https://element.io/user-guide",
+            "🛑 🔐 The chat software will ask you to set up a 'Security Key Backup'. This is very "
+            "important. Save the file in a secure location, otherwise you could lose access to older "
+            "encrypted messages later. Please follow the request.",
+        ]
+    )
+
+    place_onboarding_rooms_in_space: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """Gather the 1:1 onboarding/welcome rooms under the managed parent space (G4.5).
+                Off by default — whether direct rooms belong in a space is a matter of taste. Only
+                applies when the parent space is enabled."""
+            ),
+        ),
+    ] = False
+
+    sync_authentik_users_with_matrix_rooms: Annotated[
+        SyncAuthentikUsersWithMatrix,
+        Field(description="User→room-membership projection (the core Authentik→Matrix sync)."),
+    ] = Field(default_factory=SyncAuthentikUsersWithMatrix)
+    create_matrix_rooms_in_a_matrix_space: Annotated[
+        CreateMatrixRoomsInAMatrixSpace,
+        Field(description="Configure the designated parent space for Authentik-group rooms."),
+    ] = Field(default_factory=CreateMatrixRoomsInAMatrixSpace)
+    sync_matrix_rooms_based_on_authentik_groups: Annotated[
+        SyncMatrixRoomsBasedOnAuthentikGroups,
+        Field(description="Group→room projection rules (which groups become rooms, power levels)."),
+    ] = Field(default_factory=SyncMatrixRoomsBasedOnAuthentikGroups)
+    matrix_room_default_settings: Annotated[
+        MatrixDynamicRoomSettings,
+        Field(description="Default room identity template applied to every group room."),
+    ] = Field(default_factory=MatrixDynamicRoomSettings)
+    per_authentik_group_pk_matrix_room_settings: Annotated[
+        dict[str, MatrixDynamicRoomSettings],
+        Field(
+            description="Per-group room-setting overrides, keyed by Authentik group primary key (pk).",
+        ),
+    ] = Field(default_factory=dict)
+
+    matrix_user_ignore_list: Annotated[
+        list[str],
+        Field(examples=[["@admin:company.org", "@root:company.org"]]),
+    ] = Field(default_factory=list)
+    authentik_user_ignore_list: Annotated[
+        list[str],
+        Field(examples=[["admin", "internal_account_alex"]]),
+    ] = Field(default_factory=list)
+    authentik_group_id_ignore_list: Annotated[
+        list[str],
+        Field(examples=[["1120a6e1124f309bbe96c8be5fb09eab"]]),
+    ] = Field(default_factory=list)
+
+
+def get_config_file_path(*, not_exists_ok: bool = False) -> Path | None:
+    """Return the YAML config path from ``ONBOT_CONFIG_FILE_PATH`` (default ``config.yml``)."""
+    yaml_file = Path(os.environ.get(CONFIG_FILE_ENV_VAR, "config.yml"))
+    if yaml_file.is_file() or not_exists_ok:
+        return yaml_file
+    return None
+
+
+def load_config() -> OnbotConfig:
+    """Load config from YAML if present; env vars (``ONBOT_*``) override either way."""
+    yaml_file = get_config_file_path()
+    if yaml_file is not None:
+        with yaml_file.open() as reader:
+            data = yaml.safe_load(reader) or {}
+        return OnbotConfig.model_validate(data)
+    # No file: required fields are supplied from the environment by pydantic-settings.
+    return OnbotConfig()  # type: ignore[call-arg]
+
+
+def generate_example_config() -> str:
+    """Render a YAML document of the default config model (G11.2).
+
+    Required fields that have no default are emitted as ``null`` placeholders so the result is a
+    fillable template rather than a validation error.
+    """
+    model = OnbotConfig(
+        synapse_server=SynapseServer(server_name="", server_url="", bot_user_id="", bot_access_token=""),
+        authentik_server=AuthentikServer(url="", api_key=""),
+    )
+    data = model.model_dump(mode="json")
+    for key in ("server_name", "server_url", "bot_user_id", "bot_access_token"):
+        data["synapse_server"][key] = None
+    data["authentik_server"]["url"] = None
+    data["authentik_server"]["api_key"] = None
+    return yaml.safe_dump(data, sort_keys=False, allow_unicode=True)