pillarz 0.1.0.dev1__py3-none-any.whl

pillarz/__init__.py

@@ -0,0 +1,309 @@
+"""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 .i18n import lazy
+
+__version__ = "0.1.0.dev1"
+
+__all__ = ["Pillarz", "NavItem", "AdminTab", "AccountSection", "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.
+    - `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). TODO(Paket E): label, order, icon, template, module."""
+    key: str
+
+
+@dataclass(frozen=True)
+class AccountSection:
+    """Eigener Abschnitt der Kontoseite (Architektur §3.3). TODO(Paket E): label, order, template, module."""
+    key: str
+
+
+@dataclass(frozen=True)
+class DeleteInput:
+    """Zusatzangabe im Löschdialog (Architektur §3.4, ADR 0006). TODO(Paket E): kind, label, default …"""
+    key: str
+
+
+@dataclass(frozen=True)
+class Setting:
+    """Registrierte App-Einstellung (Architektur §3.8). TODO(Paket E): default, kind, validate, label, ui."""
+    key: str
+
+
+@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)
+
+
+# ------------------------------------------------------------------ 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.
+    - `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=(), environ=None):
+        # TODO(Pakete D–F, 0.2): changelog, self_delete 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._registry = _runtime.Registry()
+        self._app = None
+        self._web = None            # _web.app.WebState, ab create_app()
+        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)."""
+        self._registry.add("boot", fn)
+        return fn
+
+    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)
+
+    @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._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
+        if not urls:
+            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."))
+        # TODO(Paket D): Admin aus ADMIN_USERNAME/ADMIN_PASSWORD anlegen, Startwarnung Einrichtung offen
+        self._check_admin_reachable()
+        for fn in self._registry.items("startup"):
+            fn()
+
+    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 _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()

pillarz/__main__.py

@@ -0,0 +1,176 @@
+"""Kommandozeile: `python -m pillarz <befehl> <modul:objekt>`.
+
+    python -m pillarz migrate examples.minimal.app:pz            # offene Migrationen ausführen
+    python -m pillarz migrate --dry-run examples.minimal.app:pz  # nur anzeigen (Rollback am Ende)
+    python -m pillarz migrate --status examples.minimal.app:pz   # Stand je Schritt
+    python -m pillarz create-admin examples.minimal.app:pz       # erstes Admin-Konto (nur leere DB)
+
+`<modul:objekt>` zeigt auf die `Pillarz`-Instanz der App (oder die FastAPI-App, die `create_app()`
+geliefert hat). Exit-Code 0 = gut, 1 = Fehler, 2 = Aufruf falsch.
+"""
+# TODO(0.5): worker, TODO(Paket B/H): check
+import argparse
+import getpass
+import importlib
+import sys
+
+from .i18n import _
+
+
+def _load(target: str):
+    from . import Pillarz, _runtime
+    module_name, _sep, attr = target.partition(":")
+    if not module_name:
+        raise SystemExit(_("Ziel muss wie 'paket.modul:pz' aussehen, nicht %(t)r.") % {"t": target})
+    module = importlib.import_module(module_name)
+    obj = getattr(module, attr or "pz", None)
+    if isinstance(obj, Pillarz):
+        return obj
+    try:
+        pz = _runtime.current()
+    except _runtime.NoInstanceError:
+        pz = None
+    if obj is not None and pz is not None and obj is pz._app:     # Ziel ist die FastAPI-App
+        return pz
+    raise SystemExit(_("%(t)s ist keine Pillarz-Instanz (und keine App aus create_app()).") % {"t": target})
+
+
+def _db_label(pz) -> str:
+    cfg = pz.config
+    return f"PostgreSQL {cfg.postgres_db}" if cfg.postgres else f"SQLite {cfg.db_path}"
+
+
+def cmd_migrate(args) -> int:
+    from ._db.migrations import MigrationError, _plan, _sqlite_missing, status
+    pz = _load(args.target)
+    if (args.status or args.dry_run) and _sqlite_missing(pz):
+        # Nur lesen heißt: keine leere SQLite-Datei anlegen (C-L5)
+        steps = [f"{component}/{name}" for component, name, _fn in _plan(pz)]
+        if args.status:
+            print(_("Die SQLite-Datenbank %(path)s gibt es noch nicht – alle Migrationen sind offen:")
+                  % {"path": pz.config.db_path})
+            for step in steps:
+                print(f"  {step}: " + _("offen"))
+        else:
+            print(_("Trockenlauf – die SQLite-Datenbank %(path)s gibt es noch nicht (nichts angelegt, nichts "
+                    "ausprobiert):") % {"path": pz.config.db_path})
+            for step in steps:
+                print(_("  würde ausführen: %(s)s") % {"s": step})
+        return 0
+    try:
+        if args.status:
+            rows = status(pz)
+            print(_("Migrationen von %(app)s (%(db)s):") % {"app": pz.name, "db": _db_label(pz)})
+            for row in rows:
+                state = (row["applied_at"] if row["known"] else _("unbekannt (neuere Version?) – %(at)s")
+                         % {"at": row["applied_at"]}) if row["applied_at"] else _("offen")
+                print(f"  {row['component']}/{row['name']}: {state}")
+            return 1 if any(not r["known"] for r in rows) else 0
+        done = pz.migrate(dry_run=args.dry_run)
+    except MigrationError as exc:
+        print(_("Fehler: %(e)s") % {"e": exc}, file=sys.stderr)
+        return 1
+    if args.dry_run:
+        print(_("Trockenlauf – nichts geändert (%(db)s):") % {"db": _db_label(pz)})
+        lines = [_("  würde ausführen: %(s)s") % {"s": step} for step in done]
+    else:
+        print(_("Ausgeführt (%(db)s):") % {"db": _db_label(pz)})
+        lines = [_("  angewendet: %(s)s") % {"s": step} for step in done]
+    for line in lines or [_("  keine offenen Migrationen")]:
+        print(line)
+    return 0
+
+
+def _ask(prompt: str) -> str:
+    print(prompt, end="", flush=True)
+    line = sys.stdin.readline()
+    if not line:
+        raise SystemExit(_("Abgebrochen."))
+    return line.rstrip("\n")
+
+
+def _ask_secret(prompt: str) -> str:
+    if sys.stdin.isatty():
+        return getpass.getpass(prompt)
+    return _ask(prompt)                 # Eingabe aus einer Pipe (Skripte, Tests)
+
+
+def cmd_create_admin(args) -> int:
+    from ._auth.passwords import hash_password, password_problem
+    from ._auth.setup import EMAIL_RE, NAME_MAX, USERNAME_RE, SetupClosed, create_first_admin, setup_open
+    from .db import connect
+    pz = _load(args.target)
+    if "password" not in pz.config.auth_methods:
+        print(_("Die Anmeldemethode password ist abgeschaltet – ein Konto mit Passwort ergibt keinen Sinn. "
+                "Admin-Rechte kommen dann aus OIDC_ADMIN_GROUPS."), file=sys.stderr)
+        return 1
+    from ._db.migrations import MigrationError
+    try:
+        pz.migrate()
+    except MigrationError as exc:
+        print(_("Fehler: %(e)s") % {"e": exc}, file=sys.stderr)
+        return 1
+    with connect() as conn:
+        is_open = setup_open(conn)
+    if not is_open:
+        print(_("Es gibt schon Konten – create-admin geht nur bei leerer Datenbank. Weitere Konten legt "
+                "ein Admin in der Weboberfläche an."), file=sys.stderr)
+        return 1
+    print(_("Erstes Admin-Konto für %(app)s (%(db)s) anlegen.") % {"app": pz.title, "db": _db_label(pz)})
+    while True:
+        username = _ask(_("Benutzername: ")).strip()
+        if USERNAME_RE.fullmatch(username):
+            break
+        print(_("2–40 Zeichen: Buchstaben, Ziffern, Punkt, Bindestrich, Unterstrich; zuerst ein Buchstabe "
+                "oder eine Ziffer."))
+    while True:
+        name = _ask(_("Anzeigename [%(u)s]: ") % {"u": username}).strip() or username
+        if len(name) <= NAME_MAX:
+            break
+        print(_("Höchstens %(n)d Zeichen.") % {"n": NAME_MAX})
+    while True:
+        email = _ask(_("E-Mail (optional): ")).strip().lower()
+        if not email or EMAIL_RE.fullmatch(email):
+            break
+        print(_("Das ist keine E-Mail-Adresse."))
+    while True:
+        password = _ask_secret(_("Passwort: "))
+        problem = password_problem(password, username, pz.weak_passwords)
+        if problem:
+            print(problem)
+            continue
+        if _ask_secret(_("Passwort wiederholen: ")) != password:
+            print(_("Die Passwörter stimmen nicht überein."))
+            continue
+        break
+    try:
+        create_first_admin(username, name, hash_password(password), email=email or None, source="cli")
+    except SetupClosed as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(_("Admin-Konto %(u)s angelegt.") % {"u": username})
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m pillarz", description=_("Werkzeuge für pillarz-Apps."))
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("migrate", help=_("Migrationen ausführen, anzeigen oder Stand abfragen"))
+    mode = p.add_mutually_exclusive_group()
+    mode.add_argument("--dry-run", action="store_true",
+                      help=_("nur anzeigen, was liefe – alles in einer Transaktion, am Ende Rollback"))
+    mode.add_argument("--status", action="store_true", help=_("Stand je Migration anzeigen"))
+    p.add_argument("target", help=_("Pillarz-Instanz der App als modul:objekt, z. B. app.main:pz"))
+    p.set_defaults(func=cmd_migrate)
+
+    p = sub.add_parser("create-admin", help=_("erstes Admin-Konto anlegen (nur bei leerer Datenbank)"))
+    p.add_argument("target", help=_("Pillarz-Instanz der App als modul:objekt, z. B. app.main:pz"))
+    p.set_defaults(func=cmd_create_admin)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pillarz/_auth/__init__.py

@@ -0,0 +1,2 @@
+"""Interna der Anmeldung (privat). Paket A liefert nur, was `create-admin` braucht; Sitzungen,
+Bremse, Ersteinrichtung im Browser usw. kommen mit Paket D."""

pillarz/_auth/passwords.py

@@ -0,0 +1,74 @@
+"""Passwörter: scrypt-Hash und Pflichtregeln (K-4). Portiert aus labelz `app/security.py`
+(`hash_password`, `verify_password`, `needs_rehash`, `PLACEHOLDERS`).
+
+Abweichungen von labelz (Entscheidung K-4 der technischen Leitung): Pflicht 10–200 Zeichen (labelz
+8–200 bzw. 12 für den Env-Admin), nicht gleich dem Benutzernamen, nicht aus der Platzhalterliste
+(inkl. `weak_passwords` der App). Die labelz-eigenen Wörter („labelz“, „etiketten“) stehen nicht mehr
+in der allgemeinen Liste – die App ergänzt sie über `Pillarz(weak_passwords=…)`.
+"""
+# TODO(Paket D): Dummy-Hash gegen Zeitmessung, Rehash bei der Anmeldung, Hinweise über die
+# Pflichtregeln hinaus (Architektur §10.1)
+import hashlib
+import hmac
+import secrets
+
+from ..i18n import _
+
+# N=2**16 braucht 64 MiB je Hash – mehr als hashlib standardmäßig erlaubt (32 MiB), daher maxmem
+_N, _R, _P, _DKLEN = 2 ** 16, 8, 1, 32
+_MAXMEM = 256 * 1024 * 1024
+
+PASSWORD_MIN, PASSWORD_MAX = 10, 200
+
+# Platzhalter aus Anleitungen und Beispielkonfigurationen – damit wird kein Konto angelegt
+PLACEHOLDERS = frozenset({
+    "bitte-aendern", "bitte-ändern", "bitte_aendern", "bitteaendern", "admin", "administrator",
+    "changeme", "change-me", "change_me", "password", "passwort", "geheim", "secret", "test",
+    "test123", "12345678", "123456789", "1234567890", "qwertz", "qwerty", "admin123", "adminadmin",
+    "dev-passwort", "pillarz", "password123", "passwort123", "0123456789", "qwertzuiop", "qwertyuiop",
+})
+
+
+def hash_password(password: str) -> str:
+    salt = secrets.token_bytes(16)
+    digest = hashlib.scrypt(password.encode(), salt=salt, n=_N, r=_R, p=_P, dklen=_DKLEN, maxmem=_MAXMEM)
+    return f"scrypt${_N}${_R}${_P}${salt.hex()}${digest.hex()}"
+
+
+def needs_rehash(stored: str | None) -> bool:
+    """Gespeicherter Hash mit schwächeren Parametern als heute (z. B. N=2**14 aus labelz v0.1.0)?"""
+    try:
+        kind, n, r, p, _salt, _digest = (stored or "").split("$")
+        return kind != "scrypt" or int(n) < _N or int(r) < _R or int(p) < _P
+    except ValueError:
+        return False
+
+
+def verify_password(password: str, stored: str | None) -> bool:
+    try:
+        kind, n, r, p, salt, digest = (stored or "").split("$")
+        if kind != "scrypt":
+            return False
+        given = hashlib.scrypt(password.encode(), salt=bytes.fromhex(salt), n=int(n), r=int(r), p=int(p),
+                               dklen=len(digest) // 2, maxmem=_MAXMEM)
+    except (ValueError, TypeError):
+        return False
+    return hmac.compare_digest(given.hex(), digest)
+
+
+def password_problem(password: str | None, username: str = "", extra_weak=frozenset()) -> str | None:
+    """Verstoß gegen die Pflichtregeln (K-4) als Satz für die Anzeige, sonst `None`."""
+    if not isinstance(password, str) or not PASSWORD_MIN <= len(password) <= PASSWORD_MAX:
+        return _("Das Passwort muss %(min)d bis %(max)d Zeichen lang sein.") % {"min": PASSWORD_MIN,
+                                                                               "max": PASSWORD_MAX}
+    try:
+        password.encode("utf-8")
+    except UnicodeEncodeError:
+        # einzelne UTF-16-Surrogate (z. B. "\ud800" aus JSON) – nicht hashbar, nicht speicherbar
+        return _("Das Passwort enthält ungültige Zeichen.")
+    pw = password.strip().lower()
+    if username and pw == username.strip().lower():
+        return _("Das Passwort darf nicht gleich dem Benutzernamen sein.")
+    if pw in PLACEHOLDERS or pw in {w.strip().lower() for w in extra_weak}:
+        return _("Dieses Passwort steht auf der Liste bekannter Platzhalter – bitte ein anderes wählen.")
+    return None

pillarz/_auth/setup.py

@@ -0,0 +1,57 @@
+"""Erstes Admin-Konto anlegen – atomar nach ADR 0015 §5. Paket A nutzt es für
+`python -m pillarz create-admin` (Konsole); Paket D baut darauf die Einrichtungsseite `/setup` und die
+Anlage aus `ADMIN_USERNAME`/`ADMIN_PASSWORD`.
+"""
+import logging
+import re
+import sqlite3
+
+from ..db import IntegrityError, connect, now
+from ..i18n import _, lazy
+
+log = logging.getLogger("pillarz.auth")
+
+# labelz app/security.py
+USERNAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{1,39}$")
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+NAME_MAX = 100
+
+
+class SetupClosed(RuntimeError):
+    """Es gibt schon ein Konto bzw. die Einrichtung ist abgeschlossen."""
+
+
+def setup_open(conn) -> bool:
+    """Offen genau dann, wenn `users` leer ist und `pz_meta.setup_done` fehlt (ADR 0015 §1, ohne die
+    Konfigurationsbedingungen – die prüft der Aufrufer)."""
+    if conn.scalar("SELECT COUNT(*) FROM users"):
+        return False
+    return not conn.scalar("SELECT COUNT(*) FROM pz_meta WHERE key = 'setup_done'")
+
+
+def create_first_admin(username: str, name: str, password_hash: str, *, email: str | None = None,
+                       source: str = "cli") -> int:
+    """In **einer** Transaktion: `setup_done` eintragen (der Primärschlüssel serialisiert gleichzeitige
+    Versuche auf SQLite und PostgreSQL), prüfen, dass `users` leer ist, Admin anlegen. Wirft
+    `SetupClosed`, wenn schon jemand schneller war oder Konten existieren."""
+    email = (email or "").strip().lower() or None
+    try:
+        with connect() as conn:
+            conn.execute("INSERT INTO pz_meta (key, value) VALUES ('setup_done', ?)", (now(),))
+            if conn.scalar("SELECT COUNT(*) FROM users"):
+                raise SetupClosed(_("Es gibt schon Konten – die Einrichtung ist abgeschlossen."))
+            at = now()
+            user_id = conn.insert("users", username=username, name=name, email=email,
+                                  email_confirmed=1 if email else 0, password_hash=password_hash,
+                                  role="admin", created_at=at, updated_at=at)
+            # TODO(Paket E): Event user.created mit source=<source> (Veto → Rollback)
+    except IntegrityError as exc:
+        raise SetupClosed(_("Die Einrichtung ist bereits abgeschlossen.")) from exc
+    except sqlite3.OperationalError as exc:
+        # SQLite, mehrere Prozesse: ein anderer hält die Schreibsperre länger als busy_timeout – dann
+        # richtet gerade jemand anderes ein (S-N7). Andere OperationalErrors bleiben Fehler.
+        if "locked" not in str(exc).lower() and "busy" not in str(exc).lower():
+            raise
+        raise SetupClosed(_("Die Einrichtung läuft gerade an anderer Stelle – bitte gleich neu laden.")) from exc
+    log.info(lazy("Erstes Admin-Konto %(username)s angelegt (%(source)s)."), {"username": username, "source": source})
+    return user_id

pillarz/_db/__init__.py

@@ -0,0 +1 @@
+"""Interna der Datenbankschicht (privat): Verbindung/Pool, Uhr, Migrations-Runner, pillarz-Migrationen."""