pillarz 0.1.0__py3-none-any.whl

pillarz/__init__.py

@@ -0,0 +1,618 @@
+"""pillarz – gemeinsames Fundament für FastAPI-Webservices (ADR 0001).
+
+Eine App erzeugt **genau ein** `Pillarz`-Objekt je Prozess, meldet daran ihre Erweiterungen an und baut
+zum Schluss mit `create_app()` die FastAPI-Instanz::
+
+    from pathlib import Path
+    from pillarz import Pillarz
+    from . import __version__, migrations
+
+    pz = Pillarz(name="labelz", title="Labelz", version=__version__,
+                 package_dir=Path(__file__).resolve().parent, migrations=migrations.STEPS)
+    app = pz.create_app()
+
+Der Import von pillarz hat keine Nebenwirkungen: Konfiguration, Datenverzeichnis und Schlüssel
+entstehen erst beim Erzeugen von `Pillarz(...)` (`Config.from_env()`), die Datenbank erst im
+Lifespan bzw. bei `python -m pillarz migrate`.
+"""
+import logging
+import re
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import _runtime
+from .config import Config
+from .events import DeleteInput
+from .i18n import lazy
+
+__version__ = "0.1.0"
+
+__all__ = ["Pillarz", "NavItem", "AdminTab", "AccountSection", "SettingsSection", "DeleteInput", "Setting", "Theme"]
+
+log = logging.getLogger("pillarz.system")
+
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]{0,31}$")
+_KEY_RE = re.compile(r"^[a-z][a-z0-9_-]{0,39}$")
+DEFAULT_AUTH_METHODS = ("password", "oidc")
+
+
+# ------------------------------------------------------------------ Datenklassen der Registrierungen
+# Vorerst nur die Hüllen (Meilensteinplan 0.1, Paket A): der Schlüssel steht fest, die übrigen Felder
+# kommen mit den Paketen, die sie nutzen (Architektur §3.3–§3.8).
+@dataclass(frozen=True)
+class NavItem:
+    """Navigationseintrag der App (Architektur §3.3), nur für Angemeldete sichtbar::
+
+        pz.nav(NavItem("library", "/", _l("Bibliothek"), icon="library", order=10))
+
+    - `icon`: Name eines Symbols `i-<icon>` im Sprite (pillarz' `icons.svg` oder `pz.icons()`).
+    - `visible(request, user) -> bool`: Eintrag nur zeigen, wenn wahr. `user` ist der angemeldete
+      `pillarz.accounts.User` (z. B. `lambda request, user: not user.is_guest`).
+    - `badge(request, user) -> int`: Zahl am Eintrag (nur auf Seiten mit Navigation berechnet; 0 = keine),
+      `badge_href` Ziel des Badges (Standard `href`), `badge_label(n) -> str` zugänglicher Name.
+    """
+    key: str
+    href: str = "/"
+    label: object = ""
+    icon: str | None = None
+    order: int = 100
+    visible: Callable | None = None
+    badge: Callable | None = None
+    badge_href: str | None = None
+    badge_label: Callable | None = None
+
+
+@dataclass(frozen=True)
+class AdminTab:
+    """Eigener Admin-Reiter (Architektur §3.3, §14.10)::
+
+        pz.admin_tab(AdminTab("sheets", _l("Bogenformate"), order=30, icon="ruler",
+                              template="admin/sheets.html", module="/static/js/admin-sheets.js"))
+
+    `template` (App-Template, wird in den Reiter gerendert) und `module` (ES-Modul unter `/static/…`) sind
+    optional; das Modul exportiert `init(panel, ctx)` und wird beim ersten Öffnen per `import()` geladen.
+    Adresse `/admin#<key>` bzw. `/admin#<key>-<id>`. pillarz-Reiter: Konten (10), Geräte (20),
+    authentik-Links (30, nur mit aktivem authentik), Themes (50), Einstellungen (80), Protokoll (90); App-Reiter
+    stehen nach `order` dazwischen oder danach. Nur für Admins (`require_admin` inkl. befristeter
+    authentik-Admins); `visible(request, user)` blendet aus."""
+    key: str
+    label: object = ""
+    order: int = 100
+    icon: str | None = None
+    template: str | None = None
+    module: str | None = None
+    visible: Callable | None = None
+
+
+@dataclass(frozen=True)
+class AccountSection:
+    """Eigener Abschnitt der Kontoseite `/account` (Architektur §3.3, §12)::
+
+        pz.account_section(AccountSection("printing", _l("Druck"), order=50,
+                                          template="account/printing.html", module="/static/js/account-printing.js"))
+
+    pillarz-Abschnitte (Profil 10, Darstellung 20, Sprache 30, Anmeldung 40, Geräte 60, Konto löschen 90)
+    stehen fest; App-Abschnitte nach `order`. Das Modul exportiert `init(section, ctx)`. `visible(request,
+    user)` blendet aus (z. B. nicht für Gäste)."""
+    key: str
+    label: object = ""
+    order: int = 100
+    template: str | None = None
+    module: str | None = None
+    visible: Callable | None = None
+
+
+@dataclass(frozen=True)
+class SettingsSection:
+    """App-Abschnitt im Admin-Reiter „Einstellungen“ (Architektur §3.8, P-102)::
+
+        pz.settings_section(SettingsSection("printing", _l("Druck"), order=50,
+                            keys=("default_font", "default_printer_id"),
+                            template="admin/settings-printing.html", module="/static/js/settings-printing.js"))
+
+    `keys` sind registrierte `Setting`s, die der Abschnitt bearbeitet (je Schlüssel höchstens ein Abschnitt,
+    sonst Startabbruch). Das Modul exportiert `init(section, ctx)`; gespeichert wird über
+    `ctx.save({schlüssel: wert})` (`PATCH /api/pz/admin/settings`, 422 mit `field`)."""
+    key: str
+    label: object = ""
+    order: int = 100
+    keys: tuple = ()
+    template: str | None = None
+    module: str | None = None
+
+
+@dataclass(frozen=True)
+class Setting:
+    """Registrierte App-Einstellung (Architektur §3.8)::
+
+        pz.setting(Setting("show_names", default=False, kind="bool", label=_l("Namen zeigen"), ui=True))
+        pz.setting(Setting("default_sheet_id", default=None, kind="custom", validate=sheets.check_default))
+
+    - `kind`: `text` (einzeilig, `max_length`, `required`), `int` (`min`/`max`), `bool`, `choice`
+      (`options` = `[(wert, beschriftung), …]` oder Funktion, die das liefert; Werte dürfen auch Zahlen
+      sein), `custom` (beliebiges JSON, **`validate` Pflicht**).
+    - `validate(value) -> value`: zusätzlicher Prüfer; `ValueError(text)` lehnt mit `text` am Feld ab. Lehnt
+      er einen schon gespeicherten Wert ab, gilt der Standard (labelz `effective()`).
+    - `ui=True`: erscheint mit `label`/`help` im Reiter „Einstellungen“ (nicht bei `custom` – dafür
+      `SettingsSection`)."""
+    key: str
+    default: object = None
+    kind: str = "text"
+    label: object = ""
+    help: object = None
+    ui: bool = False
+    validate: Callable | None = None
+    options: object = ()
+    required: bool = False
+    max_length: int = 200
+    min: int | None = None
+    max: int | None = None
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Weiteres eingebautes Theme (Architektur §14.5): vier Grundfarben je Modus als `#rrggbb`::
+
+        pz.theme(Theme("etikett", _l("Etikett"),
+                       light={"bg": "#…", "surface": "#…", "ink": "#…", "accent": "#…"}, dark={…}))
+    """
+    id: str
+    name: object = ""
+    light: dict = field(default_factory=dict)
+    dark: dict = field(default_factory=dict)
+
+
+_ADMIN_TABS = ("users", "links", "sessions", "themes", "settings", "log")
+_ACCOUNT_SECTIONS = ("profile", "look", "language", "login", "devices", "delete")
+
+
+def _check_extension(where: str, item, existing, reserved) -> None:
+    """Schlüssel, Template und Modul von Admin-Reitern, Konto- und Einstellungsabschnitten prüfen."""
+    if not isinstance(item.key, str) or not _KEY_RE.fullmatch(item.key) or item.key in reserved \
+            or any(e.key == item.key for e in existing):
+        raise ValueError(f"{where}(): Schlüssel {item.key!r} ist ungültig, von pillarz belegt oder schon vergeben")
+    if not isinstance(item.order, int) or isinstance(item.order, bool):
+        raise ValueError(f"{where}({item.key!r}): order muss eine ganze Zahl sein")
+    module = item.module
+    if module is not None and (not isinstance(module, str) or not module.startswith("/static/")
+                               or module.startswith("/static/pillarz/") or ".." in module
+                               or not module.endswith(".js")):
+        raise ValueError(f"{where}({item.key!r}): module muss ein ES-Modul der App unter /static/…/*.js sein")
+    template = item.template
+    if template is not None and (not isinstance(template, str) or template.startswith(("/", "pillarz/"))
+                                 or ".." in template):
+        raise ValueError(f"{where}({item.key!r}): template muss ein Template der App sein (relativ, nicht pillarz/…)")
+
+
+# ------------------------------------------------------------------ das App-Objekt
+class Pillarz:
+    """Das eine pillarz-Objekt einer App.
+
+    - `name`: Kennung (Cookie, Logger, Standard-Dateiname der SQLite-Datenbank `DATA_DIR/<name>.db`),
+      klein, `[a-z][a-z0-9_-]*`, höchstens 32 Zeichen; `pillarz` ist reserviert.
+    - `title`: Standard-Seitenname, `version`: Version der App.
+    - `package_dir`: Verzeichnis der App mit `templates/`, `static/`, `locale/` (je optional).
+    - `migrations`: geordnete App-Migrationen `[("0001_initial", step), …]`, `step(conn)` (ADR 0003).
+    - `auth_methods`: Vorgabe für die Anmeldemethoden; `AUTH_METHODS` in der Umgebung überschreibt.
+    - `weak_passwords`: ergänzt pillarz' Liste verbotener Platzhalter-Passwörter.
+    - `self_delete`: Nutzer dürfen ihr eigenes Konto löschen (Kontoseite, ADR 0006; Standard an). `False`
+      blendet den Abschnitt aus, `GET/DELETE /api/pz/me/delete` bzw. `/api/pz/me` antworten 404.
+    - `environ`: nur für Tests – statt `os.environ`.
+    """
+
+    def __init__(self, *, name: str, title: str | None = None, version: str = "0", package_dir=None,
+                 migrations=(), auth_methods=DEFAULT_AUTH_METHODS, weak_passwords=(), self_delete: bool = True,
+                 environ=None):
+        # TODO(0.2): changelog und weitere Parameter aus Architektur §3.1
+        from ._db.migrations import validate
+        _runtime.check_free()
+        if not isinstance(name, str) or not _NAME_RE.fullmatch(name) or name == "pillarz":
+            raise ValueError(f"Pillarz(name=…): {name!r} ist keine gültige Kennung "
+                             "(klein, [a-z][a-z0-9_-]*, höchstens 32 Zeichen, nicht 'pillarz')")
+        self.name = name
+        self.title = title or name
+        self.version = str(version)
+        self.package_dir = Path(package_dir).resolve() if package_dir is not None else None
+        self.migrations = validate(migrations, "app")
+        self.weak_passwords = frozenset(w.strip().lower() for w in weak_passwords if w and w.strip())
+        self.self_delete = bool(self_delete)
+        self._registry = _runtime.Registry()
+        self._app = None
+        self._web = None            # _web.app.WebState, ab create_app()
+        self._setup_closed = False  # Einrichtung (ADR 0015) als „zu“ erkannt – wird nie wieder offen
+        self.config: Config = Config.from_env(environ, name=name, auth_methods=tuple(auth_methods))
+        _runtime.install(self)
+
+    def __repr__(self) -> str:
+        return f"<Pillarz {self.name!r} {self.version}>"
+
+    # -------------------------------------------------------------- Registrierungen
+    def on_startup(self, fn: Callable[[], None]) -> Callable[[], None]:
+        """Funktion nach den Migrationen und vor dem ersten Request aufrufen (als Dekorator nutzbar)."""
+        self._registry.add("startup", fn)
+        return fn
+
+    def on_shutdown(self, fn: Callable[[], None]) -> Callable[[], None]:
+        """Funktion beim Herunterfahren aufrufen (umgekehrte Reihenfolge der Anmeldung)."""
+        self._registry.add("shutdown", fn)
+        return fn
+
+    def nav(self, item: NavItem) -> NavItem:
+        """Navigationseintrag anmelden (Architektur §3.3). pillarz hängt rechts Konto, Admin und Abmelden an."""
+        if not isinstance(item, NavItem):
+            raise TypeError("pz.nav() erwartet ein NavItem")
+        if not _KEY_RE.fullmatch(item.key) or any(i.key == item.key for i in self._registry.items("nav")):
+            raise ValueError(f"pz.nav(): Schlüssel {item.key!r} ist ungültig oder schon vergeben")
+        if not isinstance(item.href, str) or not item.href.startswith("/") or item.href.startswith("//"):
+            raise ValueError(f"pz.nav({item.key!r}): href muss ein Pfad dieser Seite sein (/…)")
+        self._registry.add("nav", item)
+        return item
+
+    def csp(self, **directives) -> None:
+        """CSP der App ergänzen, z. B. `pz.csp(img_src=["blob:"], worker_src=["'self'"])`. Lockern ist
+        unmöglich: `'unsafe-*'` (außer `'wasm-unsafe-eval'`), `*`, reine Schemata in `script-src`, `javascript:`,
+        in `worker-src`/`child-src` mehr als `'self'`/`blob:`, Hashes in `style-src`, bei reinem HTTPS
+        `http://`/`ws://`-Hosts und jede Änderung an `object-src`/`base-uri`/`frame-ancestors` →
+        `ValueError` (Startabbruch, ADR 0004 §5)."""
+        from ._web.csp import check
+        self._registry.add("csp", check(directives, https_only=self.config.https_only))
+
+    def upload_limit(self, path, size: int) -> None:
+        """Größere Body-Grenze für einen Upload-Pfad (nur POST, `Content-Length` Pflicht): exakter Pfad,
+        Präfix mit `/` am Ende oder `re.compile(…)` (ganzer Pfad). Sonst gilt 1 MiB."""
+        from ._web.headers import PathRule
+        if not isinstance(size, int) or size <= 0:
+            raise ValueError("pz.upload_limit(): Größe in Bytes > 0 erwartet")
+        PathRule(path)
+        self._registry.add("upload_limit", (path, size))
+
+    def no_store(self, path) -> None:
+        """Antworten auf diesen Pfad (Präfix mit `/` am Ende, exakter Pfad oder `re.compile`) nie
+        zwischenspeichern, nie als Referer weitergeben, nicht indexieren – für Link-/Token-Seiten."""
+        from ._web.headers import PathRule
+        PathRule(path)
+        self._registry.add("no_store", path)
+
+    def public_mount(self, path: str) -> None:
+        """Eine eingehängte Unter-App (`app.mount(path, …)`) ohne Anmeldung erreichbar machen.
+
+        Mounts, Starlette-Routen (`app.add_route`) und `Host`-Routen laufen am Gate vorbei (sie kennen
+        keine FastAPI-Dependencies). pillarz behandelt sie deshalb als **geschützt**: der Guard weist
+        anonyme Anfragen an sie ab (401 bzw. 303 auf `/login`), `testing.route_audit()` meldet sie.
+        Nur so freigegebene Mount-Pfade (genau der Pfad aus `app.mount`, z. B. `"/docs-static"`) und
+        pillarz' eigene Static-Mounts sind öffentlich (ADR 0004 §2)."""
+        if not isinstance(path, str) or not path.startswith("/") or path.startswith("//"):
+            raise ValueError(f"pz.public_mount(): {path!r} ist kein Pfad (/…)")
+        self._registry.add("public_mount", path.rstrip("/") or "/")
+
+    def boot(self, fn: Callable) -> Callable:
+        """`fn(request, user) -> dict` ergänzt `boot.app` im `#boot`-Block (nur für Angemeldete; `user` ist
+        ein `pillarz.accounts.User`)."""
+        self._registry.add("boot", fn)
+        return fn
+
+    def context(self, fn: Callable) -> Callable:
+        """Anfrage-Kontext der App (P-9): `fn(request, user) -> dict` liefert Werte für den Template-Kontext
+        jeder Seite und für die Routen (`pillarz.web.request_context(request)`), z. B. Navigations-Badges::
+
+            @pz.context
+            def badges(request, user):
+                return {"nav_answers": prints.needing_answer(user.id)}
+
+        - Nur für Angemeldete (Sitzung oder App-Authenticator); `user` ist ein `pillarz.accounts.User`. Ohne
+          Anmeldung wird der Haken nie aufgerufen, der Kontext ist `{}`.
+        - **Höchstens einmal je Request und erst bei Bedarf**: beim ersten `render()` bzw.
+          `request_context()`; API-Routen, die beides nicht nutzen, zahlen nichts. Das Ergebnis liegt danach
+          auch in `request.state.app_context`.
+        - Mehrere Haken werden in Anmeldereihenfolge zusammengeführt (spätere überschreiben frühere).
+          Schlüssel, die pillarz im Template-Kontext selbst setzt (`user`, `nav`, `boot` …), sind verboten
+          (`RuntimeError`); Schlüssel aus `render(**ctx)` haben Vorrang vor dem Haken.
+        - Eine Ausnahme im Haken ist ein Fehler der Anfrage: 500 mit pillarz-Fehlerseite und Eintrag im
+          Protokoll (nichts wird still verschluckt). Das `User`-Objekt bleibt unverändert."""
+        if not callable(fn):
+            raise TypeError("pz.context(): erwartet eine Funktion fn(request, user) -> dict")
+        self._registry.add("context", fn)
+        return fn
+
+    def secret_user_column(self, name: str) -> None:
+        """Eine (app-eigene oder übernommene) Spalte von `users` als **geheim** markieren (S-N6): sie landet
+        nie in pillarz' privater Kontozeile der Anfrage, in Templates oder JSON-Antworten. `password_hash`
+        trägt pillarz selbst ein (ab 0.4 auch die TOTP-Spalten). `current_user()` liefert ohnehin nur die
+        öffentlichen Spalten (`User`)::
+
+            pz.secret_user_column("api_token_hash")
+        """
+        from ._db.connection import ident
+        ident(name)
+        if name in self._registry.items("secret_user_column"):
+            raise ValueError(f"pz.secret_user_column(): {name!r} ist schon eingetragen")
+        self._registry.add("secret_user_column", name)
+
+    def log_source(self, logger: str, source: str, label) -> None:
+        """Logger der App einem Protokoll-Bereich zuordnen, z. B.
+        `pz.log_source("labelz.direct", "direct", _l("Direktdruck"))`. Nur Logger unter `<name>`."""
+        if not (logger == self.name or logger.startswith(self.name + ".")):
+            raise ValueError(f"pz.log_source(): Logger {logger!r} gehört nicht zur App {self.name!r}")
+        if not _KEY_RE.fullmatch(source):
+            raise ValueError(f"pz.log_source(): Bereich {source!r} ist ungültig ([a-z][a-z0-9_-]*)")
+        self._registry.add("log_source", (logger, source, label))
+
+    def theme(self, theme: Theme) -> Theme:
+        """Weiteres eingebautes Theme anmelden (nach pillarz' fünf, in Anmeldereihenfolge)."""
+        from ._themes import check_registration
+        if not isinstance(theme, Theme):
+            raise TypeError("pz.theme() erwartet ein Theme")
+        check_registration(theme)
+        if any(t.id == theme.id for t in self._registry.items("theme")):
+            raise ValueError(f"pz.theme(): {theme.id!r} ist schon angemeldet")
+        self._registry.add("theme", theme)
+        return theme
+
+    def icons(self, path) -> None:
+        """Weitere `<symbol id="i-…">` aus einer SVG-Datei ins Sprite jeder Seite aufnehmen."""
+        path = Path(path)
+        if not path.is_file():
+            raise ValueError(f"pz.icons(): {path} gibt es nicht")
+        self._registry.add("icons", path)
+
+    # -------------------------------------------------------------- Konten, Events, Verwaltung (Paket E)
+    def on(self, event: str, fn: Callable | None = None, *, order: int = 100):
+        """Event-Handler anmelden (ADR 0006, `pillarz.events`), als Dekorator::
+
+            @pz.on("user.deleting", order=10)
+            def transfer(ev): …
+
+        tx-Events (`user.created`, `user.updated`, `user.deactivating`, `user.reactivated`, `user.deleting`)
+        laufen in der pillarz-Transaktion: `ev.conn` bzw. jeder `pillarz.db.connect()` auf diesem Thread ist
+        dieselbe Verbindung; **keine Threads starten** (`pillarz.db.TxThreadError`); Datei-Arbeit gehört in
+        die Nach-Commit-Events `user.deleted`, `user.signed_in`, `user.signed_out`, deren Fehler nur
+        protokolliert werden. Reihenfolge: `order`, dann Anmeldung."""
+        from ._events import check_name
+        check_name(event)
+        if not isinstance(order, int) or isinstance(order, bool):
+            raise ValueError("pz.on(): order muss eine ganze Zahl sein")
+
+        def register(handler: Callable) -> Callable:
+            from ._events import handler_name
+            if not callable(handler):
+                raise TypeError("pz.on() erwartet eine Funktion")
+            name = handler_name(handler)
+            if any(e == event and handler_name(fn) == name for e, fn, _o in self._registry.items("event")):
+                # Rückgaben landen unter diesem Namen in user.deleted.result – doppelt hieße überschrieben (C-L7)
+                raise ValueError(f"pz.on({event!r}): Handler {name} ist für dieses Event schon angemeldet")
+            self._registry.add("event", (event, handler, order))
+            return handler
+
+        return register(fn) if fn is not None else register
+
+    def delete_input(self, item: DeleteInput) -> DeleteInput:
+        """Zusatzangabe für den Löschdialog anmelden (ADR 0006, `pillarz.events.DeleteInput`)."""
+        if not isinstance(item, DeleteInput):
+            raise TypeError("pz.delete_input() erwartet ein DeleteInput")
+        if not _KEY_RE.fullmatch(item.key) or any(i.key == item.key for i in self._registry.items("delete_input")):
+            raise ValueError(f"pz.delete_input(): Schlüssel {item.key!r} ist ungültig oder schon vergeben")
+        if item.kind not in ("user", "choice", "bool", "text"):
+            raise ValueError(f"pz.delete_input({item.key!r}): kind muss user, choice, bool oder text sein")
+        if item.on_self not in (None, "ask", "default"):
+            raise ValueError(f"pz.delete_input({item.key!r}): on_self muss 'ask' oder 'default' sein")
+        if item.kind == "user" and item.on_self == "ask":
+            raise ValueError(f"pz.delete_input({item.key!r}): kind='user' wird bei Selbstlöschung nie abgefragt "
+                             "(on_self='default' mit self_default)")
+        if item.self_default == "actor":
+            raise ValueError(f"pz.delete_input({item.key!r}): self_default='actor' wäre das gelöschte Konto")
+        if item.kind == "choice" and not item.options:
+            raise ValueError(f"pz.delete_input({item.key!r}): kind='choice' braucht options")
+        if item.visible is not None and not callable(item.visible):
+            raise ValueError(f"pz.delete_input({item.key!r}): visible muss eine Funktion (user, conn) sein")
+        if not isinstance(item.max_length, int) or not 1 <= item.max_length <= 1000:
+            raise ValueError(f"pz.delete_input({item.key!r}): max_length 1–1000")
+        self._registry.add("delete_input", item)
+        return item
+
+    def request_authenticator(self, name: str, *, max_role: str = "user", methods=("GET", "HEAD")):
+        """Eigenen Anmeldeweg für Spezialfälle anmelden (labelz-Render-Ticket, Architektur §3.6, ADR 0004 §6)::
+
+            @pz.request_authenticator(name="direct", max_role="user")
+            def ticket(request) -> AuthResult | int | None: …
+
+        Läuft im Guard **vor dem Gate**, nur ohne gültige Sitzung und nur für `methods` (Standard GET/HEAD),
+        in Anmeldereihenfolge (erster Treffer gewinnt); sieht Methode, Pfad, Query und Header. Rückgabe
+        `None`, Konto-ID oder `pillarz.web.AuthResult(user_id, context)` (`auth_context(request)`). Gesperrte
+        Konten gelten nie; die Rolle ist auf `max_role` gedeckelt; pillarz-Seiten und `/api/pz/*` antworten
+        403. Keine Nebenwirkungen (keine Sitzung, kein Cookie, kein `last_seen`, kein `user.signed_in`).
+        Eine Ausnahme im Authenticator ergibt 500 (nie still anonym)."""
+        if not isinstance(name, str) or not _KEY_RE.fullmatch(name) or name == "session":
+            raise ValueError(f"pz.request_authenticator(): Name {name!r} ist ungültig")
+        if any(a[0] == name for a in self._registry.items("authenticator")):
+            raise ValueError(f"pz.request_authenticator(): {name!r} ist schon angemeldet")
+        if max_role not in ("admin", "user", "guest"):
+            raise ValueError("pz.request_authenticator(): max_role muss admin, user oder guest sein")
+        allowed = {"GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"}
+        methods = tuple(m.upper() for m in methods)
+        if not methods or any(m not in allowed for m in methods):
+            raise ValueError(f"pz.request_authenticator(): methods {methods!r} ungültig")
+
+        def register(fn: Callable) -> Callable:
+            self._registry.add("authenticator", (name, fn, max_role, frozenset(methods)))
+            return fn
+
+        return register
+
+    def admin_tab(self, tab: AdminTab) -> AdminTab:
+        """Eigenen Admin-Reiter anmelden (siehe `AdminTab`)."""
+        if not isinstance(tab, AdminTab):
+            raise TypeError("pz.admin_tab() erwartet ein AdminTab")
+        _check_extension("pz.admin_tab", tab, self._registry.items("admin_tab"), _ADMIN_TABS)
+        self._registry.add("admin_tab", tab)
+        return tab
+
+    def account_section(self, section: AccountSection) -> AccountSection:
+        """Eigenen Abschnitt der Kontoseite anmelden (siehe `AccountSection`)."""
+        if not isinstance(section, AccountSection):
+            raise TypeError("pz.account_section() erwartet eine AccountSection")
+        _check_extension("pz.account_section", section, self._registry.items("account_section"), _ACCOUNT_SECTIONS)
+        self._registry.add("account_section", section)
+        return section
+
+    def settings_section(self, section: SettingsSection) -> SettingsSection:
+        """App-Abschnitt im Reiter „Einstellungen“ anmelden (siehe `SettingsSection`)."""
+        if not isinstance(section, SettingsSection):
+            raise TypeError("pz.settings_section() erwartet eine SettingsSection")
+        _check_extension("pz.settings_section", section, self._registry.items("settings_section"), ())
+        if not section.keys or not all(isinstance(k, str) for k in section.keys):
+            raise ValueError(f"pz.settings_section({section.key!r}): keys fehlt")
+        self._registry.add("settings_section", section)
+        return section
+
+    def setting(self, setting: Setting) -> Setting:
+        """App-Einstellung anmelden (siehe `Setting`, `pillarz.settings`)."""
+        from ._settings import KINDS, PILLARZ_KEYS
+        if not isinstance(setting, Setting):
+            raise TypeError("pz.setting() erwartet ein Setting")
+        if not _KEY_RE.fullmatch(setting.key) or setting.key in PILLARZ_KEYS or \
+                any(s.key == setting.key for s in self._registry.items("setting")):
+            raise ValueError(f"pz.setting(): Schlüssel {setting.key!r} ist ungültig oder schon vergeben")
+        if setting.kind not in KINDS:
+            raise ValueError(f"pz.setting({setting.key!r}): kind muss {', '.join(KINDS)} sein")
+        if setting.kind == "choice" and not setting.options:
+            raise ValueError(f"pz.setting({setting.key!r}): kind='choice' braucht options")
+        if setting.kind == "custom" and setting.validate is None:
+            # Ohne Prüfer nähme PATCH /api/pz/admin/settings beliebiges JSON an (S-N4)
+            raise ValueError(f"pz.setting({setting.key!r}): kind='custom' braucht validate")
+        if setting.ui and setting.kind == "custom":
+            raise ValueError(f"pz.setting({setting.key!r}): kind='custom' hat keine eingebaute Oberfläche – "
+                             "SettingsSection nutzen")
+        self._registry.add("setting", setting)
+        return setting
+
+    def _check_registrations(self) -> None:
+        """Beim `create_app()`: Kombinationen prüfen, die erst mit allen Registrierungen feststehen."""
+        if self.self_delete:
+            for item in self._registry.items("delete_input"):
+                asks = item.asks_self
+                if not asks and item.required and item.self_default is None:
+                    raise ValueError(
+                        f"pz.delete_input({item.key!r}): Pflichtangabe ohne self_default – bei Selbstlöschung "
+                        f"wird {'kind=user' if item.kind == 'user' else 'on_self=default'} nicht abgefragt. "
+                        "self_default setzen, die Selbstlöschung im user.deleting-Handler ablehnen oder "
+                        "Pillarz(self_delete=False).")
+        settings = {s.key for s in self._registry.items("setting")}
+        owner: dict[str, str] = {}
+        for section in self._registry.items("settings_section"):
+            for key in section.keys:
+                if key not in settings:
+                    raise ValueError(f"pz.settings_section({section.key!r}): Einstellung {key!r} ist nicht "
+                                     "mit pz.setting() angemeldet")
+                if key in owner:
+                    raise ValueError(f"pz.settings_section(): Einstellung {key!r} gehört schon zum Abschnitt "
+                                     f"{owner[key]!r}")
+                owner[key] = section.key
+
+    @property
+    def frozen(self) -> bool:
+        return self._registry.frozen
+
+    # -------------------------------------------------------------- Start
+    def migrate(self, *, dry_run: bool = False) -> list[str]:
+        """Offene Migrationen (pillarz, dann App) ausführen – wie beim Start. Rückgabe: angewendete
+        Schritte als `"komponente/name"`."""
+        from ._db.migrations import run
+        return run(self, dry_run=dry_run)
+
+    def create_app(self):
+        """FastAPI-Instanz bauen: Guard, Gate „default deny“, Fehler-Handler, Static, Templates,
+        `/healthz`, `/themes.css` (Paket B). Danach sind alle Registrierungen eingefroren."""
+        from ._web.app import build
+
+        if self._app is not None:
+            return self._app
+        self._check_registrations()
+        self._registry.freeze()
+        pz = self
+
+        @asynccontextmanager
+        async def lifespan(_app):
+            from starlette.concurrency import run_in_threadpool
+            for warning in pz.config.warnings:
+                log.warning(warning)
+            await run_in_threadpool(pz._startup)
+            try:
+                yield
+            finally:
+                await run_in_threadpool(pz._shutdown)
+
+        self._app = build(self, lifespan)
+        return self._app
+
+    def _startup(self) -> None:
+        from . import _protocol
+        from ._i18n import catalogs
+        catalogs.load(self)         # kaputte .po stoppen den Start (statt still deutsch anzuzeigen)
+        self.migrate()
+        _protocol.install(self)     # nach den Migrationen (Tabelle pz_log), vor allem anderen
+        urls = self.config.public_urls
+        # S-N1: Secure/__Host- hängen an PUBLIC_URLS. Leer ist in Tests normal (keine Warnung), gemischt nie.
+        if not urls and not _runtime.testing:
+            log.warning(lazy("PUBLIC_URLS ist nicht gesetzt – kein HSTS, Anmelde-Cookie ohne Secure-Flag und keine "
+                             "Links nach außen. Für den Betrieb die öffentliche https://-Adresse setzen."))
+        elif not self.config.https_only and any(u.startswith("https://") for u in urls):
+            log.warning(lazy("PUBLIC_URLS mischt http:// und https:// – deshalb kein HSTS und das Anmelde-Cookie "
+                             "wird auch über unverschlüsseltes HTTP gesendet."))
+        if "oidc" in self.config.auth_methods and not urls:
+            log.warning(lazy("Anmeldung über authentik ist aktiv, aber PUBLIC_URLS ist nicht gesetzt – ohne öffentliche "
+                             "Adresse gibt es keine Rückleitung von authentik und keine Verknüpfungslinks."))
+        self._prune()
+        from ._auth.setup import seed_admin
+        seed_admin(self)            # ADMIN_* bei leerer DB (K-15: schwaches Passwort bricht ab), Warnung /setup
+        self._check_admin_reachable()
+        self._check_oidc()
+        for fn in self._registry.items("startup"):
+            fn()
+
+    def _prune(self) -> None:
+        """Aufräumen beim Start (P-43): abgelaufene/im Leerlauf ungültige Sitzungen, abgelaufene Flows, alte
+        Bremsen-Einträge, verbrauchte/zurückgezogene/abgelaufene Einmal-Tokens nach 30 Tagen. Ab 0.5
+        zusätzlich regelmäßig im System-Job `pillarz.prune`."""
+        from ._auth import flows, sessions, throttle, tokens
+        counts = {"sessions": sessions.prune(), "flows": flows.prune(), "throttle": throttle.prune(),
+                  "tokens": tokens.prune()}
+        if any(counts.values()):
+            log.info(lazy("Aufgeräumt: %(sessions)d Sitzungen, %(flows)d Anmelde-Zwischenstände, "
+                          "%(throttle)d Bremsen-Einträge, %(tokens)d Einmal-Tokens"), counts)
+
+    def _check_admin_reachable(self) -> None:
+        """C-L4: Konten, aber kein aktives Admin-Konto und keine `OIDC_ADMIN_GROUPS` – niemand kommt in
+        die Verwaltung (typisch nach der Übernahme einer Datenbank ohne Umbau `is_admin` → `role`).
+        Kein Startabbruch, aber ein Fehler im Protokoll. Leere Datenbank = Einrichtung, kein Fehler."""
+        from .db import connect
+        if self.config.oidc_admin_groups:
+            return
+        with connect() as conn:
+            users = conn.scalar("SELECT COUNT(*) FROM users")
+            admins = conn.scalar("SELECT COUNT(*) FROM users WHERE role = 'admin' AND active = 1")
+        if users and not admins:
+            log.error(lazy("Kein aktives Admin-Konto (Konten insgesamt: %(users)d) und OIDC_ADMIN_GROUPS ist leer "
+                           "– niemand kann die Verwaltung öffnen. Ein Konto zum Admin machen (role = 'admin') "
+                           "oder OIDC_ADMIN_GROUPS setzen."), {"users": users})
+
+    def _check_oidc(self) -> None:
+        """P-6: Discovery im Hintergrund prüfen – ein falscher `OIDC_ISSUER` steht so schon nach dem Start im Protokoll
+        und im Admin-Bereich, nicht erst nach der ersten fehlgeschlagenen Anmeldung. Nicht im Testmodus."""
+        from ._auth import oidc
+        if oidc.enabled() and not _runtime.testing:
+            oidc.check_in_background()
+
+    def _shutdown(self) -> None:
+        from ._db.connection import close_pool
+        try:
+            for fn in reversed(self._registry.items("shutdown")):
+                try:
+                    fn()
+                except Exception:   # noqa: BLE001 – weitere Handler und das Schließen des Pools laufen trotzdem
+                    log.exception(lazy("on_shutdown-Handler %r ist fehlgeschlagen"), fn)
+        finally:
+            from . import _protocol
+            _protocol.uninstall()
+            close_pool()