Architektur¶

Haben ist eine einzelne Anwendung auf Basis von TanStack Start, die unter Bun läuft, mit PostgreSQL als einziger Datenbank und einem Verzeichnis für Belegdateien. Diese Seite beschreibt Aufbau, Datenmodell, Abläufe und die wichtigsten Entwurfsentscheidungen. Für die Entwicklungsumgebung siehe Entwicklung, für den Betrieb Installation.

Überblick¶

flowchart LR
  Browser["Browser<br/>React-API mit TanStack Redact, PWA"] -->|HTTPS| Caddy["Caddy<br/>Reverse Proxy"]
  Caddy --> Web

  subgraph Web["apps/web · TanStack Start auf Bun"]
    Routes["routes/<br/>Seiten und Loader"] --> Functions["server/functions/<br/>Server Functions + authMiddleware"]
    Api["routes/api/<br/>Downloads, Export, Auth"]
    Functions --> Services["server/modules/<br/>Dienste je Fachbereich"]
    Api --> Services
    Services --> Packages["packages/<br/>core · einvoice · import · elster"]
  end

  Services --> Postgres[("PostgreSQL<br/>Daten, Trigger, Audit-Log")]
  Services --> Files[("DOCUMENTS_DIR<br/>Dateien unter SHA-256")]
  Packages --> Worker["ERiC-Worker<br/>Kindprozess je Aufruf"] --> Elster["ELSTER"]
  Services -.->|optional| Anthropic["Anthropic API<br/>Belegauslesung"]
  Services -.->|oder| Local["OpenAI-kompatibler Dienst<br/>z. B. Ollama, OpenRouter"]
  Packages -.->|Umzug| Lexware["Lexware Office, sevDesk<br/>Public API"]
  Packages -.->|optional| Banking["Enable Banking<br/>Kontoabruf (PSD2)"]

Der Browser spricht nur mit der eigenen Anwendung. Seiten laden ihre Daten über Server Functions; Dateien (Rechnungs-PDFs, Belege, Protokolle, CSV, ZIP) kommen über eigene API-Routen. Nach außen verbindet sich der Server nur mit ELSTER (über ERiC, dazu download.elster.de für das ERiC-Paket), optional mit der Anthropic-API oder einem OpenAI-kompatiblen KI-Dienst (selbst betrieben oder in der Cloud), mit Enable Banking für den Kontoabruf, dem Datenportal des BMF für die Umrechnungskurse, dem eigenen Mailserver (SMTP, IMAP) und während des Umzugs mit Lexware Office oder sevDesk.

Module¶

Pakete¶

apps/elster-helfer¶

Die Browser-Erweiterung „Haben für Mein ELSTER“ (Manifest V3, TypeScript, gebaut mit Vite und @crxjs/vite-plugin nach dist/): src/fill.ts findet die Felder von Mein ELSTER über ihre amtliche Kennung (reine Logik ohne Chrome-APIs, getestet in apps/web/e2e/elster-helfer.spec.ts), src/content.ts trägt auf jeder Formularseite ein und zeigt die Leiste, src/popup.ts nimmt die Werte aus Haben entgegen und legt sie im Sitzungsspeicher des Browsers ab. Das Format der Werte ist der Typ MeinElsterWerte aus packages/elster/src/felder.ts, denselben, mit dem Haben sie erzeugt. Das Inhaltsskript ist ein Bündel ohne Nachladen, die Erweiterung gibt Mein ELSTER also keine Dateien frei (web_accessible_resources), an denen die Seite sie erkennen könnte. Für jedes Release baut und packt scripts/elster-helfer/paket.ts sie mit der Version aus dem Tag als haben-fuer-mein-elster-chrome-<Version>.zip (Format des Chrome Web Store). Sie läuft nur auf www.elster.de/eportal/interpreter/eingabe/… und verbindet sich nicht mit Haben (Mein ELSTER mit Erweiterung).

apps/web¶

Module im Server¶

Die Dienste liegen in apps/web/src/server/modules/, ein Ordner je Fachbereich. Ein Modul besitzt seine Tabellen und bietet nach außen nur an, was in seiner index.ts steht.

Die Prüfung der Modulgrenzen (scripts/modulgrenzen/) läuft mit bun run lint in der CI und prüft jeden relativen Import, auch export … from, import() und Typen wie import("…").T. Sie löst den Pfad auf, statt nur den Text des Imports zu vergleichen; das kann Biome nicht, deshalb ist es ein eigenes Skript:

• Aus einem anderen Modul nur über dessen index.ts. Braucht ein Modul, eine Server Function oder eine Route etwas, das dort fehlt, wird es in der index.ts ergänzt. Die Datei enthält nur export { … } from "./…", keine Logik.
• Infrastruktur importiert keine Module. server/*.ts und server/db/ bleiben unabhängig von der Fachlogik. Ausgenommen sind die Stellen, die Module zusammensetzen: server/functions/, server/plugins/ und scheduler.ts.
• Module importieren weder Server Functions noch Oberfläche (server/functions/, server/plugins/, routes/, components/). Gemeinsames ohne Serverbezug liegt in src/lib/.

Tests sind ausgenommen und dürfen auch Dateien hinter der index.ts anderer Module importieren. modulgrenzen.test.ts prüft die Regel selbst und die Struktur: Jedes Modul hat eine index.ts, und direkt unter server/ liegt nur Infrastruktur.

Zwischen Modulen gibt es Abhängigkeiten in beide Richtungen, etwa rechnungen ↔ bank (Zahlungen einer Rechnung, Zuordnung zu einer Rechnung) oder stammdaten → rechnungen (die Sperre der Firmendaten zählt offene Rechnungen). Die Regel verbietet sie nicht, macht sie aber an der index.ts sichtbar.

Datenmodell¶

Alle Tabellen stehen in apps/web/src/server/db/schema.ts. Beträge sind ganze Cent, Steuersätze Basispunkte. Die Spalte „Schutz“ fasst die Trigger aus apps/web/drizzle/ zusammen; Einzelheiten in Buchhaltung in Haben.

Stammdaten¶

Rechnungen und Belege¶

Buchhaltung, Bank und Umsatzsteuer¶

Lohn¶

Archiv und Umzug¶

Protokoll und Anmeldung¶

Anmeldung¶

Im Standardmodus hat Haben genau einen Inhaber und auf Wunsch Zugänge mit der Rolle Steuerberatung, die nur lesen (Zugang für die Steuerberatung). Früher hatte Haben genau einen Nutzer; diese Entscheidung ist mit dem Zugang für die Steuerberatung aufgegeben, im SSO-Modus sind mehrere Inhaber möglich.

Haben hat zwei strikt getrennte Betriebsarten, umgeschaltet nur über OIDC_ONLY: den Standardmodus mit lokaler Anmeldung (dieser Abschnitt) und den SSO-Modus mit Rollen aus OIDC-Gruppen (SSO-Modus). Im Standardmodus legt die Ersteinrichtung (/setup) den Inhaber mit E-Mail und Passwort an (mindestens 12 Zeichen). Dafür braucht es den Einrichtungscode, den der Server beim Start ins Log schreibt (server/setup-code.ts, oder fest aus HABEN_SETUP_CODE); ein Hook vor /sign-up/email prüft ihn. So kann niemand, der eine neue Instanz zuerst erreicht, das Konto an sich reißen. Jedes weitere Konto entsteht nur mit einer Einladung (server/anmeldung.ts):

• Der Inhaber erzeugt unter Einstellungen › Sicherheit einen Link /einladung/<token>. Das Token sind 32 zufällige Bytes; gespeichert ist nur sein SHA-256 in invitations, mit Rolle und Frist (72 Stunden).
• Die Seite schickt das Token beim Anlegen im Header x-haben-einladung mit. Der Hook vor /sign-up/email prüft, dass die Einladung noch gilt, sonst verlangt er wie bisher den Einrichtungscode. Der Datenbank-Hook user.create.before löst die Einladung atomar ein (UPDATE … WHERE nicht eingelöst, nicht zurückgezogen, nicht abgelaufen) und setzt die Rolle aus ihr; ohne Einladung entsteht ein Konto nur, solange es noch keines gibt, dann als Inhaber. Zwei gleichzeitige Anmeldungen mit demselben Link: nur eine bekommt die Zeile.
• Rolle und Sperre sind additionalFields von Better Auth mit input: false; die Anfrage kann sie nicht setzen. Die Spalte role ist die lokale Rolle; sie hat weiterhin die Vorgabe steuerberatung und bleibt bei Konten leer, die nur per SSO entstanden sind. Der partielle eindeutige Index user_inhaber_single (er ersetzt user_single) hält genau einen lokalen Inhaber auch bei zwei gleichzeitigen Einrichtungen, ein CHECK auf invitations lässt nur Einladungen für die Steuerberatung zu, und ein Trigger lehnt gewöhnliche Rollenänderungen ab; die ausdrückliche Offline-Vorbereitung des lokalen Inhabers ist der eng begrenzte, auditierte Ausnahmeweg. Den Endpunkt update-user von Better Auth lehnt der before-Hook für alle ab: Name und Bild änderten sich dort ohne Audit-Akteur und an der Rollenprüfung vorbei.
• Der Hook session.create.before gibt einem gesperrten Konto keine Sitzung, auch nicht per Passkey; Sperren löscht zusätzlich die laufenden Sitzungen. session.create.after schreibt jede Anmeldung mit Rolle und Art nach user_logins.

Im Standardmodus meldet man sich per Passkey an, das Passwort bleibt Rückfallebene. Better Auth begrenzt Anmeldeversuche (20 je Minute) und liest die Client-Adresse hinter Caddy aus X-Forwarded-For.

Geschützt wird an vier Stellen:

• Die Layout-Route _app leitet ohne Sitzung auf /login bzw. vor der Einrichtung auf /setup um, die Steuerberatung von jeder Seite außer ihren eigenen (steuerberatungSieht in src/lib/rollen.ts) auf /steuerberatung. Die Navigation zeigt ihr nur diese Seiten, Knöpfe zum Ändern fehlen. Das ist Bequemlichkeit, kein Schutz.
• Jede Server Function mit Daten hängt genau eine von zwei Middlewares an (apps/web/src/server/middleware.ts): authMiddleware lässt nur den Inhaber durch und ist die Vorgabe; readMiddleware lässt auch die Steuerberatung durch und steht nur an lesenden GET-Funktionen. Beide lesen die Sitzung über sessionUser (server/rollen.ts), das gesperrte Konten und unbekannte Rollen als nicht angemeldet behandelt, und legen das Konto mit Rolle in den Kontext. Abgelehnt wird mit 403. Eine neue Server Function ist also ohne Zutun nur für den Inhaber.
• Für die Steuerberatung läuft der Handler zusätzlich in runReadOnly (server/db/actor.ts, AsyncLocalStorage): withActor lehnt dort jede Transaktion ab. Rutscht in eine lesende Funktion doch ein Schreibvorgang mit Audit-Eintrag, schreibt er für die Steuerberatung nichts. Aufräumen beim Lesen (ein nach einem Neustart hängender Beleg auf „läuft“) lässt getDocument dann aus.
• Jede API-Route mit Sitzung ruft requireUser(request, "inhaber" | "lesen") (server/rollen.ts) und antwortet sonst mit 401 bzw. 403. Ausnahmen mit eigenem Token statt Sitzung sind das Kalender-Abo, /api/mcp und die REST-API unter /api/v1; deren Tokens legt nur der Inhaber an.

rollen.test.ts liest alle Server Functions und API-Routen aus dem Quelltext und bricht ab, wenn eine POST-Funktion nicht authMiddleware nimmt, eine Funktion mit readMiddleware nicht GET ist oder nicht in der geprüften Liste steht, eine Route die Sitzung an requireUser vorbei liest oder die Liste der Routen für die Steuerberatung sich ändert. Wer der Steuerberatung etwas Neues zeigen will, ergänzt die Liste dort bewusst. zugang.test.ts prüft gegen Postgres Einladung, Rollen, Middleware beider Rollen, Sperren und Audit.

Dazu kommt ein Schutz vor Anfragen fremder Seiten (CSRF): Das Sitzungscookie ist SameSite=Lax, und createCsrfMiddleware in start.ts lehnt jede schreibende Anfrage (alles außer GET, HEAD, OPTIONS) ab, deren Sec-Fetch-Site nicht same-origin ist oder deren Origin bzw. Referer nicht zu BETTER_AUTH_URL passt (server/csrf.ts). Das hält auch Seiten auf Nachbar-Subdomains derselben Domain ab. /api/mcp und das Teilen-Ziel /api/belege/teilen prüfen selbst. /api/v1/… ist ausgenommen, weil die REST-API das Sitzungscookie gar nicht liest, nur das Token im Header; eine fremde Seite erbt dort also keine Rechte.

KI-Assistenten melden sich an /api/mcp nicht mit der Sitzung an, sondern mit einem API-Token als Bearer-Header (siehe KI-Assistenten). routes/api/mcp.ts reicht jede Anfrage an handleMcpRequest (server/modules/mcp/) weiter. Der Endpunkt ist zustandslos (Streamable HTTP mit JSON-Antworten, nur POST): authenticateMcp prüft das Token gegen den SHA-256 in mcp_tokens und ob der Zugang eingeschaltet ist, dann beantwortet ein frischer McpServer die Anfrage mit den Werkzeugen, die die Rechte des Tokens erlauben. Die Werkzeuge (tools.ts) rufen nur die index.ts der Module auf und lesen nur. Jeder Aufruf landet ohne Inhalte in mcp_calls. Alles hinter authenticateMcp kennt nur den Zugang mit seinen Rechten; OAuth für die Connectors aus claude.ai kommt dort später dazu.

Die REST-API unter /api/v1 (REST-API) nimmt dieselben Tokens. routes/api/v1/$.ts reicht jede Anfrage an handleApiRequest (server/modules/api/). Welche Endpunkte es gibt, steht in einer Tabelle (routes.ts): Methode, Pfad, nötiges Recht, Handler und was die Beschreibung über sie sagt. Der Router ordnet den Pfad zu, prüft Token (authenticateMcp), Rate (dasselbe Fenster wie MCP) und Recht (hasScope, schreiben schließt lesen ein), liest den JSON-Body und ruft den Handler; jeder Aufruf landet ohne Inhalte in mcp_calls, Änderungen stehen mit dem Akteur api:<Name des Tokens> im Audit-Log. Die Handler prüfen die Eingabe zuerst mit einem strengen Schema der API (unbekannte Felder sind ein Fehler), dann mit dem Schema der Oberfläche (contactSchema, draftSchema) samt deren Vorgaben, und rufen die index.ts von stammdaten und rechnungen. Festschreiben, Buchen und Versand bietet die API nicht an. Die OpenAPI-3.1-Beschreibung unter /api/v1/openapi.json entsteht beim ersten Abruf aus der Tabelle und den Zod-Schemas (z.toJSONSchema, JSON Schema 2020-12); die Tests prüfen die Antworten gegen dieselben Schemas.

Die externe Referenz eines Entwurfs (invoices.external_source, external_id) macht das Anlegen idempotent: createDraftForReference liefert eine vorhandene Rechnung mit derselben Referenz, und kommen zwei Anfragen gleichzeitig, fängt der eindeutige Index invoices_external_ref die zweite ab, die dann die erste liefert. Die beiden Spalten sind gewöhnliche Spalten der versiegelten Tabelle: Das Siegel einer ab jetzt festgeschriebenen Rechnung schließt sie ein (es nimmt beim Festschreiben alle Spalten), ältere Siegel behalten ihre Spaltenliste und bleiben gültig.

Belege aus der API (POST /api/v1/belege, multipart/form-data mit eigener Grenze je Endpunkt statt der 1 MB für JSON) gehen durch uploadDocument wie ein Upload in Haben: dieselbe Prüfung der Datei (documentFileProblem), Ablage unter dem SHA-256, E-Rechnung lesen oder KI-Auslesung im Hintergrund, Status neu. Die Referenz (documents.external_source, external_id) wird nur beim Anlegen gesetzt. uploadDocument sucht zuerst nach ihr, dann nach dem Hash; fängt der eindeutige Index documents_external_ref eine gleichzeitige Anfrage ab, gilt der Beleg der anderen. Ob ein vorhandener Beleg zur Anfrage passt (gleiche oder keine Referenz: 200, sonst 409), entscheidet der Handler. Wie bei Rechnungen sind die Spalten gewöhnliche Spalten der versiegelten Tabelle: Ein ab jetzt gebuchter Beleg schließt sie in sein Siegel ein, der Trigger documents_locked sperrt sie mit dem Beleg; Siegel älterer Belege bleiben gültig.

Ablauf einer Anfrage¶

Rechnung festschreiben¶

1. Die Seite ruft die Server Function finalizeInvoiceDraft auf. authMiddleware prüft die Sitzung.
2. finalizeInvoice in server/modules/rechnungen/invoices.ts öffnet eine Transaktion mit withActor.
3. In dieser Transaktion:
4. Entwurf mit SELECT … FOR UPDATE sperren,
5. Firmendaten, Kunde, Positionen, Beträge, die umsatzsteuerliche Behandlung und die Pflichtfelder des gewählten E-Rechnungsformats prüfen (finalizeIssues, dieselbe Prüfung wie in der Oberfläche, hier mit der Transaktion),
6. den Nummernkreis sperren und die nächste Nummer nur lesen (peekNumber in server/modules/rechnungen/number-counter.ts, Advisory Lock je Kreis); ein Kreis ist das Jahr des Rechnungsdatums oder, bei durchlaufendem Zähler, 0 (counterCircle), so steht er auch in den Zählertabellen und in number_year,
7. PDF und XML aus Positionen und den gespeicherten Steuerzeilen (invoice_taxes) erzeugen (siehe unten); bis hierhin hat die Transaktion nichts mit Audit-Eintrag geschrieben, die Hash-Kette ist also frei,
8. den Zähler auf diese Nummer setzen (takeNumber; ab hier ist die Kette gesperrt),
9. Rechnung auf final setzen, mit Verkäufer- und Käuferdaten, Summen, PDF, XML, SHA-256 und locked_at,
10. über ledger.post buchen und festschreiben; der Trigger prüft Soll = Haben.
11. Schlägt ein Schritt fehl, wird alles zurückgerollt. Die Nummer ist dann nicht verbraucht; der Nummernkreis bleibt lückenlos.

Ein Storno läuft genauso, nur mit dem Entwurf in derselben Transaktion (cancelInvoice): erst das Original sperren (FOR UPDATE), dann den Nummernkreis, dann den Storno-Entwurf anlegen und festschreiben. Schlägt etwas fehl oder bricht der Server ab, bleibt kein Entwurf zurück. Weil der Entwurf schon einen Audit-Eintrag schreibt, entsteht das PDF des Stornos bei gesperrter Kette; Stornos sind selten, der eine Entwurf in derselben Transaktion wiegt mehr.

Angebote nummeriert finalizeQuote nach demselben Muster (eigener Kreis). Die Reihenfolge der Sperren ist immer Rechnungszeilen, dann Nummernkreis, dann Kette: Das Festschreiben einer Korrektur sperrt das Original, bevor es eine Nummer zieht, also muss auch das Storno das Original vor dem Kreis sperren, sonst verklemmen sich beide. Wer in einer Transaktion schon etwas mit Audit-Eintrag geschrieben hat und danach eine Nummer braucht, sperrt den Kreis vorher (lockNumbering). Auch „Nächste Nummer festlegen“ nimmt die Sperre des Kreises und wartet so auf ein laufendes Festschreiben.

Hauptbuch und Transaktionen¶

• Ein Schreiber. Ins Journal schreibt nur post(tx, books, posting) in server/modules/buchhaltung/ledger.ts: Buchung anlegen, Zeilen anlegen, sperren. Die Stellen, die buchen (Rechnungen, Belege, Bank, Kasse, Pauschalen, Anlagen, offene Posten aus Lexoffice, Ausschüttungen, Lohnabrechnungen, manuelle Buchungen und Eröffnungen), rufen nur noch post auf. Ein Test (hauptbuch.test.ts) schlägt fehl, sobald eine andere Datei journal_entries oder journal_lines beschreibt.
• Firmendaten in der Transaktion. openBooks(tx) liest Kontenrahmen, Versteuerung und Kleinunternehmer in der buchenden Transaktion, die Buchungszeilen werden danach berechnet. Nach dem Einfügen hält die Transaktion die Sperre der Hash-Kette; post liest die Firmendaten dann noch einmal und lehnt ab, wenn sie sich dazwischen geändert haben. Die Datenbank prüft zusätzlich den Kontenrahmen jeder Buchung und lehnt Buchungen ab, die beim Commit nicht festgeschrieben sind (0065_hauptbuch_sperren.sql).
• Ein Kontenrahmen je Jahr. post lehnt eine Buchung ab, wenn im Jahr ihres Datums schon in einem anderen Kontenrahmen gebucht ist. Umstellen geht nur zum Jahreswechsel; danach würde eine Buchung ins Vorjahr (Aufheben einer Zuordnung, rückdatierte Rechnung) sonst Kontonummern des neuen Rahmens zwischen die des alten stellen. Die Datenbank kann das nicht prüfen, sie kennt nur den Kontenrahmen der Firmendaten.
• Transaktion ausdrücklich weitergeben. Lesefunktionen nehmen eine Verbindung an (q: Db | Tx = db, etwa loadCompany(tx), getInvoice(id, tx), finalizeIssues(id, tx)), Schreibfunktionen gibt es auch ohne eigene Transaktion (insertDraft(tx, …)). withActor öffnet immer eine neue Transaktion und tritt keiner offenen bei. Ein stilles Beitreten hätte die ELSTER-Sendesperre geändert: underSendLock im ELSTER-Gateway hält eine Transaktion nur für die Sperre, protokolliert wird bewusst auf anderen Verbindungen, damit ein späterer Fehler das Protokoll einer Echtübermittlung nicht zurückrollt.
• Ein Anwendungsfall, eine Transaktion. Storno (Entwurf und Festschreiben) und Angebot zu Rechnung (Entwurf und Verknüpfung) laufen in einer Transaktion. Die Abschlagsrechnungen einer Schlussrechnung prüft Haben in der Transaktion, die den Entwurf speichert. Firmendaten speichert saveCompany in settings-guard.ts mit Prüfung der Sperren in derselben Transaktion; die Server Function ruft nur noch das auf.
• Reihenfolge der Sperren. Zeilen sperren (FOR UPDATE), dann schreiben; die Sperre der Hash-Kette kommt mit dem ersten Audit-Eintrag. Die Trigger aus 0065 nehmen sie in derselben Anweisung wie der Audit-Eintrag, die Reihenfolge bleibt also gleich. Wer Zeilen mit einem Fremdschlüssel auf eine Zeile anlegt, die er danach sperrt, sperrt sie vorher (siehe cancelInvoice), sonst verklemmen sich zwei gleichzeitige Aufrufe.

Bankumsatz zuordnen¶

1. allocateTransaction → allocate in server/modules/bank/bank.ts, in einer Transaktion mit withActor.
2. Der Umsatz wird mit FOR UPDATE gesperrt; Vorzeichen und offener Betrag werden geprüft, ebenso der offene Betrag der Rechnung bzw. des Belegs.
3. Haben liest die Firmendaten in der Transaktion (openBooks), bildet den Buchungssatz mit @haben/core (invoicePaymentPosting, documentPaymentPosting oder directPosting), legt die Zuordnung an und bucht über ledger.post auf den Buchungstag des Umsatzes.
4. Der Trigger auf allocations prüft noch einmal, dass die Summe der Zuordnungen den Umsatz nicht übersteigt. Bei einem Zahlungseingang merkt sich Haben die IBAN des Kunden, falls noch keine hinterlegt ist.

Aufheben legt eine Gegenzeile und eine Gegenbuchung an, statt etwas zu löschen. Die Gegenbuchung spiegelt die Zeilen der ursprünglichen Buchung; ist das Jahr des Buchungstags in einem anderen Kontenrahmen gebucht, lehnt post sie ab (siehe oben).

Dateiablage¶

Belegdateien, Verträge der Dauerbelege, Lexoffice-Dateien, Archivexporte, Bescheide aus dem Postfach, zusätzliche Anhänge von Rechnungen und Angeboten samt Standardanhängen, Übermittlungsprotokolle vermerkter Voranmeldungen und Protokolle aus dem SV-Meldeportal liegen im Dateisystem unter DOCUMENTS_DIR (Standard data/belege, im Container ein Volume), adressiert über ihren SHA-256: <DOCUMENTS_DIR>/ab/abcdef…. Daraus folgt:

• Dieselbe Datei wird nur einmal abgelegt; ein zweites Hochladen findet den vorhandenen Beleg.
• Gelöscht wird eine Datei erst, wenn kein Datensatz sie mehr nutzt (fileInUse in server/db/file-in-use.ts), etwa beim Löschen eines ungebuchten Belegs oder eines Anhangs im Rechnungsentwurf.
• Geschrieben wird atomar über eine temporäre Datei und rename, mit Dateirechten 0640.
• Beim Lesen prüft Haben den Hash. Eine veränderte Datei fällt sofort auf („beschädigt“).
• Den Dateityp erkennt Haben am Inhalt (PDF, JPEG, PNG, WebP, HEIC, XML), nicht an Endung oder Browserangabe.

Rechnungs-PDFs und -XML sowie ERiC-Protokolle liegen dagegen direkt in der Datenbank (bytea bzw. text). Datenbank und Belegverzeichnis gehören beide ins Backup (Backup-Container aus deploy/backup).

ERiC-Worker¶

ERiC, die native Bibliothek der Finanzverwaltung, läuft nie im Anwendungsprozess. EricProcessClient in packages/elster startet für jeden Aufruf einen kurzlebigen Kindprozess (worker.ts), der ERiC per koffi lädt (über die Node-API, die Bun nachbildet), genau eine Anfrage über IPC ausführt und sich beendet. Stürzt ERiC ab oder hängt, bekommt die Anwendung nur eine Fehlermeldung; nach 120 Sekunden wird der Kindprozess beendet. Der Kindprozess startet ohne Core-Dump (ulimit -c 0): Unter Bun wäre der Dump eines Absturzes mehrere GB groß, und wo ihn ein Dienst wie systemd-coredump annimmt, käme die Fehlermeldung erst nach Sekunden bis Minuten. Beim Postfachabruf sendet derselbe Kindprozess die PostfachAnfrage und lädt danach die Anhänge über Otto (libotto.so aus dem ERiC-Paket); die Dateien reisen base64-kodiert über IPC zurück, bestätigt wird erst, wenn die Anwendung sie gespeichert hat.

Für eine Übermittlung entschlüsselt Haben das Zertifikat und schreibt es in ein temporäres Verzeichnis (Rechte 0700, Datei 0600), das nach dem Aufruf gelöscht wird. Die PIN wird je Übermittlung abgefragt; gespeichert wird sie nur, wenn du den automatischen Postfachabruf einschaltest (verschlüsselt, für Postfach, Belegabruf und Berechtigungen). Vor dem Senden prüft der Client, dass der Testmerker im XML zur gewünschten Art passt (Test- oder Echtübermittlung). Ohne ERiC verwendet Haben einen simulierten Client und zeigt das in der Oberfläche an.

ERiC selbst liefert Haben nicht mit. packages/elster/src/install.ts lädt das Paket auf Wunsch von download.elster.de (Einstellungen, ERIC_AUTO_INSTALL im Entrypoint oder install-cli.ts), entpackt per Stream nur die Einträge unter Linux-x86_64/ in einen Unterordner von ERIC_DIR und schaltet über die Datei AKTUELL um, wenn Bibliothek und Plugins vollständig sind; so lässt sich auch ein Volume als Ziel nutzen. ERIC_HOME hat Vorrang. Der ELSTER-Client wird neu erzeugt, sobald sich das ERiC-Verzeichnis ändert. Auf Rechnern ohne Linux x86_64 startet ERIC_WORKER_COMMAND den Worker als x86_64-Prozess unter QEMU (deploy/eric-x86_64/einrichten.sh), die App selbst bleibt nativ; mit dem Befehl lassen auch Installation und Oberfläche ERiC zu (ericPlatformSupported).

ELSTER-Gateway¶

Jede Übermittlung an die Finanzverwaltung läuft über server/modules/elster/elster-gateway.ts: Voranmeldung, Dauerfristverlängerung, Zusammenfassende Meldung, Jahreserklärungen, E-Bilanz, Kapitalertragsteuer-Anmeldung, Lohnsteuer-Anmeldung und -bescheinigung, Nachrichten an das Finanzamt, Änderung der Bankverbindung, Postfach, Belegabruf (VaSt) und Berechtigungen. Das Gateway übernimmt, was jede davon braucht, damit eine neue Übermittlungsart nichts vergessen kann:

Die Bestätigung der Datenschutzhinweise prüft der Client selbst vor jedem Aufruf (elster.ts). Ein Test (elster-gateway.test.ts) schlägt fehl, sobald eine andere Datei Test-Hersteller-ID, simulierten Client, Zertifikat oder PIN selbst behandelt.

E-Rechnung¶

Beim Festschreiben entsteht die Rechnung in zwei Stufen:

1. Sichtbares PDF: Typst setzt die Vorlage rechnung.typ mit IBM Plex Sans als PDF/A-3b. Der Compiler läuft im Prozess (@myriaddreamin/typst-ts-node-compiler).
2. E-Rechnung: @e-invoice-eu/core erzeugt aus denselben Daten
3. bei ZUGFeRD (Profil EN 16931) ein PDF/A-3 mit eingebettetem factur-x.xml; Haben liest das XML danach wieder aus und speichert es zusätzlich,
4. bei XRechnung (CII oder UBL) das XML; das Typst-PDF bleibt als Sichtfassung dabei. Was die Bibliothek im CII auslässt, ergänzt der Post-Processor in packages/einvoice/src/cii.ts an der Stelle laut Schema: das leere ApplicableHeaderTradeDelivery, die Bestellnummer (BT-13) im ZUGFeRD und die Lieferscheinnummer (BT-16) in jedem CII (gflohr/e-invoice-eu#685). Die Tests in referenzen.test.ts suchen jede gesetzte Referenz im erzeugten XML, weil der KoSIT-Validator ein fehlendes optionales Feld nicht meldet.

Eingehende E-Rechnungen liest packages/einvoice direkt: das eingebettete XML aus ZUGFeRD-PDFs oder reines XML (CII, UBL). Die Felder des Belegs werden daraus vorbefüllt, ohne KI.

Hintergrundarbeit¶

Haben hat keine Job-Queue. Länger laufende Arbeit läuft als Promise im Serverprozess weiter, nachdem die Anfrage beantwortet ist:

• KI-Auslesung von Belegen: Nach dem Hochladen eines PDFs oder Fotos ohne E-Rechnung setzt Haben den Status „läuft“ und schickt die Datei an genau einen Anbieter. extractionConfig (extraction-config.ts) wählt ihn aus der Umgebung: einen OpenAI-kompatiblen Dienst, sobald EXTRACTION_BASE_URL gesetzt ist (oder EXTRACTION_PROVIDER=openai-compatible), sonst Anthropic mit ANTHROPIC_API_KEY. Schlägt der Anbieter fehl, gibt es keinen zweiten Versuch bei einem anderen; der Fehler steht am Beleg. Beide Anbieter liefern dasselbe Zod-Schema (extraction-schema.ts), Beträge als Dezimaltext, damit nichts gerundet wird; toFields prüft Beträge, Daten und Summen für beide gleich. Anthropic bekommt PDFs direkt und antwortet über output_config.format. Der OpenAI-kompatible Dienst bekommt Bilder als image_url mit data:-URL; PDFs wandelt pdf-pages.ts vorher mit pdftoppm (poppler-utils, im Image) als Kindprozess in PNG-Seiten um, in einem temporären Verzeichnis, das danach gelöscht wird. Die Anfrage verlangt response_format mit json_schema (aus dem Zod-Schema); lehnt der Dienst das mit 400/422 ab, fragt Haben denselben Dienst ohne und liest das JSON aus dem Text (Denkblock und Code-Zaun werden entfernt, Zahlen als Dezimaltext angenommen), geprüft gegen dasselbe Schema. Fehler tragen einen kurzen Code (ExtractionError.reason); nur er steht mit Anbieter und Modell im Log, nie Beleginhalt, Antwort oder Schlüssel. Ohne Anbieter verlässt keine Datei den Server.
• Wiederkehrende Rechnungen: Ein Nitro-Plugin (server/plugins/scheduler.ts) startet beim Serverstart einen Timer: 30 Sekunden nach dem Start und danach stündlich legt runDueRecurring die fälligen Rechnungen an (server/modules/rechnungen/recurring.ts). Verpasste Termine holt der Lauf mit ihrem Datum nach; ein eindeutiger Index auf (recurring_id, recurring_date) verhindert Doppelte. Im Audit-Log steht als Akteur system:wiederkehrend. HABEN_SCHEDULER=off schaltet den Timer ab.
• Dauerbelege: Derselbe Timer ruft runDueDauerbelege auf (server/modules/belege/dauerbelege-lauf.ts). Je Termin eine Transaktion: Vorlage mit FOR UPDATE sperren, Beleg „Zu prüfen“ anlegen, nächsten Termin weiterrücken; ein gleichzeitiger Lauf wartet auf die Sperre und sieht danach den neuen Termin, der eindeutige Index auf (recurring_document_id, recurring_period) fängt den Rest ab. Verpasste Termine holt der Lauf nach. Gebucht wird nichts. Akteur im Audit-Log ist system:dauerbelege.
• Kontoabruf: Derselbe Timer ruft runDueBankSyncs auf (server/modules/bank/bank-sync.ts). Jede aktive Verbindung wird höchstens alle 20 Stunden abgerufen, auch nach einem Fehler, weil PSD2 Banken nur wenige Zugriffe ohne den Nutzer am Tag erlaubt. Der Abruf baut aus der API-Antwort einen ParsedStatement und speichert ihn über denselben Weg wie eine Datei (storeStatement), also mit Hash-Dubletten und Kontosperre. Akteur im Audit-Log ist system:bankabruf.
• Weitere Läufe desselben Timers (runScheduledJobs in server/scheduler.ts): automatischer Abruf des ELSTER-Postfachs (nur mit ERiC), Umrechnungskurse des BMF samt Umrechnung offener Belege und Rechnungsentwürfe (Akteur system:kurse), Belege per E-Mail (IMAP), Erinnerungen an Fristen und die wöchentliche Mail mit dem Prüfwert des Audit-Logs.
• Basiszinssatz: Derselbe Timer ruft runDueBaseRate auf (server/modules/rechnungen/base-rate-job.ts), nur mit dem Haken „Basiszinssatz automatisch abrufen“ (company.dunning.autoBaseRate). dunning.baseRateSince hält das Halbjahr (JJJJ-01, JJJJ-07), für das die Bundesbank den Satz bestätigt hat; liegt es vor dem laufenden, fragt der Lauf höchstens einmal am Tag die Zeitreihe BBIN1.M.DE.BBK.BBKBAS2.EUR.ME ab, bis sie einen Monat des neuen Halbjahrs meldet. Ein von Hand geänderter Satz setzt baseRateSince zurück. Akteur im Audit-Log ist system:basiszins.
• Lexoffice-Abruf: läuft mit einem AbortController im Prozess und schreibt seinen Fortschritt höchstens einmal je Sekunde in lexoffice_imports. Nach einem Neustart erkennt Haben einen hängengebliebenen Lauf an drei Minuten ohne Fortschritt; ein neuer Lauf setzt fort, weil vorhandene Belege übersprungen werden.

Laufende Auslesungen merkt sich der Prozess. Steht ein Beleg auf „läuft“, ohne dass der Prozess ihn ausliest (Neustart während der Auslesung), setzt Haben ihn beim nächsten Öffnen auf „Fehler“, damit er wieder bearbeitet werden kann.

Sicherheit¶

• Verschlüsselung: ELSTER-Zertifikat und gespeicherte PIN, Lexware-API-Schlüssel, sevDesk-Token, der private Schlüssel für Enable Banking, SMTP- und IMAP-Passwort und die Sitzungskennung des Kontoabrufs liegen mit AES-256-GCM verschlüsselt in der Datenbank (server/crypto.ts, Format IV | Tag | Chiffrat). Der Schlüssel HABEN_ENCRYPTION_KEY (32 Byte, base64) steht nur in der Umgebung.
• Dateiauslieferung: Gespeicherte Dateien gehen mit X-Content-Type-Options: nosniff, Cache-Control: private, no-store und einer Content-Security-Policy hinaus: für PDFs default-src 'none'; object-src 'self', sonst sandbox. Nur PDFs und Bilder werden im Browser angezeigt; XML und JSON kommen als Text, alles andere als Download.
• Manipulationserkennung: Das Audit-Log ist eine Hash-Kette, festgeschriebene Datensätze tragen ein Siegel (siehe Buchhaltung in Haben). Berechnet und geprüft wird beides in Postgres, damit der Hash nicht von einer Nachbildung des JSON in TypeScript abhängt. Ab dem ersten Eintrag ins Audit-Log hält eine Transaktion die Sperre der Kette bis zum Commit (Advisory Lock); Transaktionen mit Audit-Einträgen laufen also nacheinander. Wer in einer Transaktion weitere Sperren nimmt (etwa die der Kasse), nimmt sie vor der ersten Änderung mit Audit-Eintrag, sonst können sich zwei Transaktionen gegenseitig blockieren. Lange Arbeit nach dem ersten Audit-Eintrag hält andere Schreibvorgänge so lange auf; teure Arbeit gehört deshalb davor. Rechnungen und Angebote erzeugen PDF und XML vor dem ersten Schreiben (siehe Rechnung festschreiben), Mahnungen ebenso. Migrationen, die eine Spalte einer versiegelten Tabelle (journal_entries, journal_lines, invoices, invoice_lines, invoice_taxes, documents, document_amounts, document_splits, vat_returns, cash_entries, allocations, pauschalen, asset_depreciations, document_cancellations, invoice_attachments, vat_return_filings, payslips, payslip_cancellations) umbenennen, löschen oder deren Werte umrechnen, lassen die Siegel nicht mehr passen; die Prüfung meldet das zu Recht als Änderung festgeschriebener Daten. Neue Spalten sind unkritisch.
• Eigene Seiten: Der Rahmen hat sandbox ohne allow-top-navigation und referrerpolicy="no-referrer"; die fremde Seite bekommt weder Sitzung noch Token und kann Haben nicht wegnavigieren. Weil allow-scripts mit allow-same-origin auf derselben Herkunft die Sandbox aufheben würde, lehnt checkPageUrl die Herkunft von BETTER_AUTH_URL ab, ebenso andere Protokolle als http und https und Zugangsdaten in der Adresse. Haben setzt kein frame-src; ob die Seite sich einbetten lässt, entscheidet sie selbst mit frame-ancestors.
• Rollen: Die Steuerberatung erreicht nur lesende Funktionen; Zertifikat, PIN, Zugangsdaten für Bank, E-Mail und Lexware Office, API-Tokens und Einstellungen liefert keine davon aus. Jede schreibende Server Function und jede API-Route mit Schreibzugriff verlangt den Inhaber, für die Steuerberatung lehnt zusätzlich withActor jede Transaktion ab (siehe Anmeldung). Einladungslinks gelten einmal und 72 Stunden und liegen nur als Hash in der Datenbank. Sperren beendet Sitzungen sofort, jede Anmeldung steht im Audit-Log.
• Kein Geheimnis im Export: Das Jahresarchiv enthält weder Zertifikat noch API-Schlüssel. Das Audit-Log speichert Chiffrate gar nicht erst, der Export filtert sie zusätzlich heraus.
• Kontoabruf: Die Rückleitung der Bank (/api/bank/callback) verlangt eine angemeldete Sitzung und einen state, den Haben beim Start zufällig erzeugt und nur einmal annimmt. Der Zugriff ist lesend; Zahlungen kann Haben nicht auslösen. Der private Schlüssel der Enable-Banking-Anwendung liegt in der Umgebung bzw. als Datei oder, unter Einstellungen eingetragen, verschlüsselt in enable_banking_settings.
• Proxy: Caddy terminiert TLS und setzt HSTS, X-Frame-Options: SAMEORIGIN und Referrer-Policy: same-origin. SAMEORIGIN statt DENY, weil die Vorschauen von Belegen, Rechnungen und Angeboten iframes auf derselben Origin sind. Die App setzt zusätzlich selbst Content-Security-Policy: frame-ancestors 'self' auf alle HTML-Antworten (src/start.ts, server/security-headers.ts); Dateien aus file-response.ts behalten ihre eigene CSP.

Entwurfsentscheidungen¶

SSO-Modus¶

Token-Verantwortung ist von der interaktiven Sitzungsfrist getrennt. Eine geprüfte Herabstufung oder ein Gruppenentzug deaktiviert API-/MCP- und Kalender-Tokens des Verantwortlichen in derselben Transaktion wie die negative Rollenentscheidung. Ohne erneuten OIDC-Durchlauf gilt ein Token höchstens 30 Tage nach der letzten Bestätigung des Verantwortlichen (currentTokenOwners in server/token-responsibility.ts); dieselbe Prüfung lässt nach einem Moduswechsel keine Tokens eines Kontos ohne Identität in der neuen Betriebsart gelten. Deaktivierung erhält das Geheimnis; nur ein anderer berechtigter Inhaber (bei eigenen Tokens auch der einzige Inhaber) kann ausdrücklich übernehmen. Ein gemeinsamer Advisory-Lock je Konto serialisiert Entzug, Anlage und Übernahme. Ältere Rollenentscheidungen dürfen neuere Nachweise nicht überschreiben.

Der Offline-Rückweg verwendet den exklusiven Anwendungs-Lock und einen eng begrenzten Datenbankpfad für die lokale Inhaberrolle. Gewöhnliche Rollenänderungen bleiben gesperrt. Konto-ID und SSO-Zuordnungen bleiben erhalten; fehlende lokale Credentials entstehen ausschließlich durch ausdrückliche Betreiberaktion. Token-Verwaltung wird ohne Geheimnisse in token_events, die lokale Vorbereitung in local_owner_recoveries auditiert.

Mit OIDC_ONLY=true meldet man sich ausschließlich über einen OIDC-Anbieter an (Better Auth genericOAuth, Provider-ID oidc, Referenz Authelia); ohne diesen Schalter ist OIDC vollständig aus, auch wenn Anbieterwerte gesetzt sind. Der gemeinsame before-Hook (server/sso-policy.ts, enforceMode) sperrt in jeder Betriebsart die Endpunkte der anderen, auch bei internen auth.api-Aufrufen; im SSO-Modus sind E-Mail/Passwort abgeschaltet und das Passkey-Plugin nicht geladen, im Standardmodus ist der Anbieter nicht registriert. Verknüpfen und Entfernen von Identitäten gibt es in keiner Betriebsart, ebenso keine Token-Endpunkte.

Callback. Authorization Code Flow mit PKCE S256, browsergebundenem state (in der Datenbank), Nonce und ID-Token-Prüfung gegen die JWKS der Discovery; deren Issuer muss exakt OIDC_ISSUER sein. Der beim Start gesetzte serverseitige OAuth-State nennt den Issuer; ein vor einem Moduswechsel oder für einen anderen Issuer begonnener Vorgang wird verworfen. Nach dem geprüften ID-Token fragt server/oidc.ts UserInfo ab, wenn der Anbieter diesen Endpunkt nennt; das Subject muss exakt übereinstimmen (OIDC Core 5.3.2). Ein fehlender Gruppenclaim darf aus dem geprüften ID-Token ergänzt werden, ein vorhandener ungültiger Claim niemals. server/sso-groups.ts entscheidet die Rolle: Der Claim aus OIDC_GROUPS_CLAIM muss ein Array aus Zeichenketten sein, verglichen wird exakt; genau eine der beiden Haben-Gruppen gibt die Rolle, keine, beide, ein fehlender oder ungültiger Claim verweigern. Identitäten sind [issuer, sub] in account.account_id (partieller eindeutiger Index); Konten werden nie über gleiche E-Mail zusammengeführt (account_not_linked → Hinweis auf die Übernahme), Profilclaims ändern weder Namen noch Rechte bestehender Konten.

Atomar. server/auth-transaction.ts führt den Schreibteil des Callbacks in einer PostgreSQL-Transaktion aus. Sie beginnt erst nach dem geprüften UserInfo (beginCallbackWrites), sodass Code-Tausch und UserInfo keine Datenbankverbindung belegen; das Löschen des States liegt davor und bleibt auch nach einem Rollback bestehen. Ein AsyncLocalStorage bindet Drizzle-Adapter und Hooks an die Verbindung, auch Fehler-Redirects rollen zurück. In ihr entstehen Einrichtung (sso_issuers, beim ersten Callback eines Inhabers je Issuer), Konto (ohne lokale Rolle), Identität, bestätigte Rolle (sso_roles) und Sitzung gemeinsam oder gar nicht (server/sso-callback.ts). Vor der Einrichtung lehnt Haben die Steuerberatung ab. Ändert sich die Rolle, löscht dieselbe Transaktion alle bisherigen Sitzungen des Kontos. Wird eine bekannte Identität nach vollständig geprüftem ID-Token und UserInfo wegen ihrer Gruppen abgewiesen, widerruft eine eigene Transaktion nach dem Rollback ihre SSO-Sitzungen und setzt die Rolle in sso_roles auf leer; der Fehler-Redirect nimmt das nicht zurück. Ungeprüfte Antworten (Signatur, Nonce, State, Subject) ändern nichts.

Wirksame Rolle. Die Sitzung trägt oidc_issuer, sso_role, sso_checked_at und sso_expires_at, gesetzt nur im Callback (input: false). sso_expires_at liegt 15 Minuten nach der Prüfung, unabhängig von der Laufzeit der nach dem Callback verworfenen Tokens; der Sitzungsrefresh von Better Auth ändert nur expires_at. effectiveRole in server/sso-policy.ts liefert im Standardmodus die lokale Rolle einer lokalen Sitzung eines ungesperrten Kontos, im SSO-Modus nur sso_role einer Sitzung dieses Issuers vor Fristablauf; lokale Rolle und Sperre zählen dort nicht. sessionUser (server/rollen.ts) nimmt sie für Navigation, Server Functions, API-Routen und Audit; native Better-Auth-Endpunkte löschen eine Sitzung, die nicht gilt. Nach Fristablauf führt die Oberfläche zur Anmeldeseite, ohne automatischen Neustart des Flusses. Tokens speichert Haben nicht (Account-Create und -Update entfernen sie), einen Hintergrundrefresh gibt es nicht.

Moduswechsel. Beim Start (server/sso-mode.ts, Plugin setup-code.ts) löscht Haben die Sitzungen der anderen Betriebsart und bricht den Standardmodus ab, wenn es Konten, aber keinen ungesperrten lokalen Inhaber mit Passwort oder Passkey gibt. Gespeicherte lokale Zugangsdaten und Einladungen bleiben erhalten. Bestehende Konten ordnet nur der Betreiber zu: src/server/db/sso-uebernahme.ts (eigenständig, auch im Betriebs-Image) prüft oder übernimmt bei gestoppter Anwendung, erkennbar am Advisory Lock, den die laufende App geteilt hält; nur zum konfigurierten Issuer, nur für ein freies Subject, mit Eintrag in sso_takeovers, ohne Rolle. Mit --ersetzen tritt ein neues Subject an die Stelle der bisherigen Identität dieses Issuers; Sitzungen und bestätigte Rolle enden, replaced_subject hält das alte fest.

Tabellen. sso_issuers und sso_takeovers sind nur anhängbar, sso_roles hält je Konto und Issuer die zuletzt bestätigte Rolle; alle drei haben Audit-Trigger. Anmeldungen stehen mit wirksamer Rolle und Art sso in user_logins. Konfiguration und Authelia-Beispiel: Single Sign-on mit OpenID Connect.

Letztes Update: 9. November 2026