Vendoo 1.41.2 – Git Ignore Boundary & Module Tracking Hotfix (#18)

* docs: prepare Vendoo 1.41.2 git-ignore boundary hotfix * fix: track native source modules with root-anchored runtime ignores
2026-07-09 17:09:00 +02:00
parent f4923437ca
commit 6f48827f4d
556 changed files with 77265 additions and 210 deletions
@@ -0,0 +1,27 @@
+# Catalog & Media Architecture 1.39.0
+
+## Ziel
+
+Listings, Inventory und Media sind eigenständige native Module innerhalb des modularen Monolithen. Die Migration folgt dem Strangler-Prinzip: öffentliche CRUD-Routen und Sicherheitsverträge gehören den Modulen; bestehende Tabellen und kompatible Datenzugriffe für AI, Publishing, Quality und Dashboard bleiben zunächst erhalten.
+
+## Modulgrenzen
+
+### `vendoo.listings`
+
+Besitzt Artikelkatalog und Papierkorb. Das Modul validiert alle schreibenden Payloads über eine Allowlist, bereinigt Rich-HTML, erzwingt Bearbeitungssperren und trennt Soft-Delete von endgültigem Löschen.
+
+### `vendoo.inventory`
+
+Besitzt Lagerorte und Bestandszuordnung. Lesende Übersichten benötigen Artikel-Leserechte; Änderungen benötigen `inventory.edit`. Bulk-Aktionen sind dedupliziert und auf 500 IDs begrenzt.
+
+### `vendoo.media`
+
+Besitzt Medienbibliothek und Upload-Dateien. Pfade werden normalisiert und innerhalb des Upload-Roots aufgelöst. Aktive Artikelreferenzen schützen Bilder vor Löschung.
+
+## Dependency Injection
+
+Die Modulindizes importieren keine Datenbankadapter. Der Server injiziert Repositories nach Initialisierung der Laufzeitpfade. Dadurch bleiben Modulgraph und Policy-Verträge ohne native SQLite-Bindings prüfbar.
+
+## Kompatibilität
+
+Die Endpunkte `/api/listings`, `/api/trash`, `/api/inventory/*` und `/api/media-library*` bleiben unverändert. `lib/db.mjs` bleibt vorübergehend als Kompatibilitätsschicht für noch nicht migrierte Module. Es findet keine Tabellenmigration und kein Datenreset statt.
@@ -0,0 +1,39 @@
+# Vendoo 1.35.0 – Design-System- und Theme-Vertrag
+
+## Quelle der Wahrheit
+
+Die editierbare Tokenquelle liegt unter:
+
+`public/design-system/tokens/source.json`
+
+Aus ihr erzeugt `tools/generate-design-tokens.mjs` deterministisch:
+
+- `public/design-system/tokens.css`
+- `public/design-system/theme-contract.json`
+
+Direkte Änderungen an `tokens.css` sind nicht zulässig.
+
+## Ebenen
+
+- Primitive/semantische Farb-, Radius-, Schatten-, Dichte-, Layout- und Bewegungswerte
+- CSS-Variablen mit Präfix `--vd-*`
+- Kompatibilitätsbrücke für bestehende Variablen wie `--bg`, `--accent` und `--radius`
+
+## Themes
+
+1. `light`
+2. `dark`
+3. `contrast`
+4. Browserpräferenz `system` über die Theme Runtime
+
+## Sicherheit
+
+Der zukünftige Theme Manager darf ausschließlich Tokens mit `customizable: true` verändern. Freies CSS, HTML, URLs, JavaScript, Schattenausdrücke und beliebige Variablennamen sind nicht erlaubt. Farben und Dimensionen werden typ- und bereichsgeprüft. Ein Theme wird nie ungeprüft als Stylesheet gespeichert.
+
+## Nächster Ausbau
+
+- persistente Themes pro Benutzer und systemweit
+- Live-Vorschau in isoliertem Vorschaucontainer
+- automatische Kontrastprüfung
+- Import/Export eines versionierten Theme-JSON
+- Versionsverlauf und Zurücksetzen
@@ -0,0 +1,39 @@
+# Identity & Settings Architecture 1.38.0
+
+## Schichten
+
+```text
+HTTP Route
+  -> Platform Route Registry
+  -> Policy Engine
+  -> Input Schema
+  -> Module Service
+  -> Identity Core / Settings Repository
+  -> bestehende SQLite-Tabellen
+```
+
+## Verantwortlichkeiten
+
+### `vendoo.auth`
+
+Besitzt Authentifizierungsabläufe und Token-Lebenszyklen. Das Modul kennt Setup, Login, Einladungen, Invite-Annahme und Logout. Es liefert keine Passwort-Hashes aus.
+
+### `vendoo.users`
+
+Besitzt Benutzerprofile, Rollenänderungen, Passwort-Reset und Login-Historie. Der letzte aktive Administrator ist als Invariante geschützt.
+
+### `vendoo.sessions`
+
+Besitzt Sitzungslisten, Widerruf und Cleanup. Selbstbedienungsrouten erzwingen `user_id` als Teil der Löschbedingung; eine erratene fremde Session-ID genügt daher nicht.
+
+### `vendoo.settings`
+
+Besitzt die Allowlist veränderbarer Einstellungen. Secret-Felder werden an den verschlüsselten Secret Store delegiert, Runtime-Felder an den persistenten Konfigurationsspeicher und fachliche Einstellungen an das Settings Repository.
+
+## Datenbankstrategie
+
+Die bestehenden Tabellen bleiben die Quelle der Wahrheit. 1.38.0 verschiebt Eigentümerschaft und Zugriffsschichten, nicht die Daten. Neue Module greifen über klar benannte Services und Repositories zu. Spätere Releases können Tabellen modulweise weiter kapseln.
+
+## Übergangsregel
+
+`lib/auth.mjs` darf ausschließlich als Exportfassade dienen. Neue Fachlogik darf dort nicht mehr ergänzt werden. Neue Identitätsrouten müssen über die nativen Module und den Platform Kernel registriert werden.
@@ -0,0 +1,25 @@
+# Vendoo Modularisierungs-Roadmap ab 1.35.0
+
+## 1.35.0 – Foundation
+
+Kernel, Manifeste, Lifecycle, Event Bus, Feature Flags, Policy-/Routenverträge, Design Tokens und Architekturtests.
+
+## 1.36.0 – Theme Manager
+
+Persistente sichere Themeverwaltung, Vorschau, Import/Export, Kontrast- und Accessibility-Gates.
+
+## 1.37.0 – Security & Secrets
+
+Secret Provider, Schema Registry, strukturierte Logs, sichere Fehlergrenzen und CSP-Migrationsgrundlage.
+
+## 1.38.0 – Auth, Users & Settings
+
+Erster vollständig migrierter Backend-/Frontend-Modulverbund einschließlich Vertragstests.
+
+## 1.39.0 – Listings, Inventory & Media
+
+Fachmodule, Repository-Schicht, UI-Komponenten und Datenzugriffsgrenzen.
+
+## 1.40.0 – Publishing, AI & FLUX
+
+Adapterverträge, Job-Schnittstellen, FLUX-Modul und Vorbereitung des isolierten Extension-Hosts.
@@ -0,0 +1,52 @@
+# Vendoo Module Manager 1.40.0
+
+## Zielarchitektur
+
+Vendoo bleibt ein modularer Monolith. Eingebaute Module laufen über den Plattformkernel; Fremdmodule werden als `.vmod`-Pakete verwaltet. Drittanbieter-Code wird nicht ungeprüft im Hauptprozess ausgeführt.
+
+## Modulklassen
+
+### Geschützte Kernmodule
+
+Systemrelevante Module wie Security, Auth, Benutzer, Sitzungen, Einstellungen, Themes, Listings, Inventory, Media, Operations und der Modulmanager selbst können weder deaktiviert noch gelöscht werden.
+
+### Optionale Vendoo-Module
+
+Publishing, AI, FLUX Studio und Quality Center können kontrolliert aktiviert oder deaktiviert werden. Der Registry-Graph prüft Abhängigkeiten. Beim Aktivieren werden notwendige Abhängigkeiten automatisch gestartet; beim Deaktivieren ist eine bewusste Kaskadenentscheidung erforderlich.
+
+### Installierte Fremdmodule
+
+- `declarative`: ausschließlich Daten, Manifest und freigegebene UI-/Metadaten; kein ausführbarer Code.
+- `isolated`: ausführbarer Code, nur mit vertrauenswürdiger Ed25519-Signatur und isoliertem Extension-Host.
+- `builtin-reference`: Exportformat eingebauter Module, nicht als Fremdmodul installierbar.
+
+Der isolierte Extension-Host ist in 1.40.0 noch nicht für die Ausführung freigegeben. Solche Pakete können geprüft und quarantänisiert, aber nicht aktiviert werden.
+
+## Paketvertrag
+
+Ein `.vmod`-Paket enthält:
+
+- Format und Schemaversion
+- validiertes Modulmanifest
+- Runtime-Modus und optionalen Einstiegspunkt
+- Dateien als Base64 mit Größe und SHA-256
+- kanonische Gesamtintegrität
+- optionale Ed25519-Signatur
+
+Pfade mit Traversal, absoluten Pfaden, Laufwerkspräfix oder Nullbytes werden abgewiesen. Paket- und Dateigrößen sind begrenzt.
+
+## Persistenz
+
+- Pakete: `modules/<module-id>/package.vmod`
+- Aktivierungszustand: `config/modules-state.json`
+- Docker/NAS/VPS: eigener persistenter Mount `/app/data/modules`
+
+Backups und Rollbacks behandeln `config/` und `modules/` als zusammengehörige Laufzeitdaten.
+
+## API und UI
+
+Administration erfolgt ausschließlich über `/api/admin/modules` und die Oberfläche **Administration → Module**. Alle Routen benötigen `modules.manage`, CSRF-Schutz bei Änderungen und Audit-Einträge.
+
+## Sicherheitsgrenze
+
+Deaktivierte Module blockieren ihre eigenen Kernel-Routen und die kompatiblen Legacy-API-Namensräume mit HTTP 503 `MODULE_DISABLED`. Installation bedeutet niemals automatische Aktivierung.
@@ -0,0 +1,31 @@
+# Vendoo 1.35.0 – Modulsystem
+
+## Ziel
+
+Vendoo wird schrittweise als modularer Monolith organisiert. Der bestehende Code bleibt in 1.35.0 funktional unverändert und wird über `legacy-bridge`-Manifeste erfasst. Neue Funktionen müssen die Kernelverträge verwenden; bestehende Bereiche werden in späteren Releases einzeln migriert.
+
+## Verbindliche Regeln
+
+1. Jedes Modul besitzt eine eindeutige ID `vendoo.<name>` und ein validiertes `module.json`.
+2. Abhängigkeiten müssen explizit und frei von Zyklen sein.
+3. Neue Routen benötigen Besitzer, Policy, Auditklasse, Rate-Limit-Klasse und Stabilitätsstatus.
+4. Unbekannte Policies verweigern den Zugriff. Es gibt keinen Allow-by-default-Fallback.
+5. Module kommunizieren künftig über öffentliche Services, Capabilities und Events, nicht über interne Querimporte.
+6. Ein Modul darf langfristig nur seine eigenen Tabellen beziehungsweise Repository-Schnittstellen verändern.
+7. Externe Erweiterungen werden nicht im Vendoo-Hauptprozess ausgeführt. Ein isolierter Extension-Host bleibt bis zur sicheren Umsetzung deaktiviert.
+8. Modulaktivierung durch bloßes Kopieren einer Datei ist unzulässig.
+
+## Status 1.35.0
+
+Die Bereiche System, Security, Auth, Benutzer, Themes, Medien, Artikel, AI, FLUX Studio, Quality Center, Publishing und Operations sind registriert. Ihr Status `legacy-bridge` bedeutet: Der Vertrag existiert, die bestehende Implementierung liegt aber noch überwiegend in `server.mjs`, `lib/`, `public/app.js` und `public/style.css`.
+
+## Migrationsmethode
+
+Vendoo verwendet das Strangler-Verfahren:
+
+- neue Architektur neben dem Bestand aufbauen,
+- einen fachlichen Bereich vollständig migrieren,
+- Verhalten und Datenbestand prüfen,
+- erst danach den alten Pfad entfernen.
+
+Kein Big-Bang-Refactoring, keine Framework-Migration und kein Datenbankreset.
@@ -0,0 +1,29 @@
+# Vendoo 1.35.0 – Sicherheitsarchitektur
+
+## Neue Grundlage
+
+- Deny-by-default Policy Engine für neue Kernel-Routen
+- explizite Routenverträge
+- standardisierte interne Fehler mit Request-ID
+- validierte Modulmanifeste und Abhängigkeiten
+- Owner-basierter Event-Bus mit sauberem Listener-Abbau
+- Feature Flags mit fester Registrierung und sicherem Environment-Override
+- sichere Theme-Werte statt frei eingebbarem CSS
+- geordneter Kernelstart und Kernelshutdown
+
+## Bestehender Schutz bleibt aktiv
+
+Sitzungen, CSRF, Rollen, Berechtigungen, Rate Limits, Origin-/Hostprüfung, Uploadschutz, Audit und Ressourcenlocks werden nicht ersetzt oder umgangen.
+
+## Offene Produktiv-Gates
+
+Diese Punkte werden bewusst nicht als bereits gelöst ausgegeben:
+
+- vollständige CSP ohne `unsafe-inline`
+- zentral validierte Request-/Response-Schemas für alle Bestandsrouten
+- verschlüsselter Secret Provider je Plattform
+- isolierter Extension-Host
+- vollständige Repository-Trennung aller Datenbankzugriffe
+- automatisierte Browser-, Accessibility- und Penetrationstests
+
+Bis zu ihrer Umsetzung bleiben die entsprechenden Feature Flags deaktiviert oder die Altpfade unter bestehenden Schutzmechanismen aktiv.
@@ -0,0 +1,21 @@
+# Security Foundation 1.37.0
+
+## Secret Provider
+
+Der aktuelle Provider verschlüsselt jeden Wert einzeln mit AES-256-GCM und zufälliger 96-Bit-IV. Authentifizierungstag, IV und Ciphertext werden gespeichert; der Master-Key liegt getrennt. Schreibvorgänge erfolgen atomar über eine temporäre Datei und restriktive Dateirechte.
+
+## Vertrauensgrenzen
+
+- Browser erhält nur `configured`, `masked`, `provider` und Zeitstempel.
+- Klarwerte werden nur im Serverprozess entschlüsselt.
+- Nur bekannte Secret-Namen sind zulässig.
+- Nicht editierbare OAuth-Tokens können nicht über die generische Secret-API geändert werden.
+- Policy `security.secrets.manage` schützt alle Secret-Routen.
+
+## CSP
+
+`script-src` erlaubt ausschließlich Same-Origin und den bestehenden jsDelivr-Abhängigkeitspfad. `script-src-attr 'none'` blockiert Inline-Eventhandler. Inline-Stile bleiben vorübergehend erlaubt, bis die Legacy-Oberfläche vollständig tokenisiert und modularisiert ist.
+
+## Observability
+
+Request- und Correlation-IDs werden in Response-Headern zurückgegeben. Die In-Memory-Telemetrie speichert keine Request-Bodies, Querywerte, Cookies oder Authorization-Header. Die letzten Einträge enthalten nur Methode, Pfad, Status, Dauer und Benutzer-ID.
@@ -0,0 +1,41 @@
+# Vendoo Theme Manager 1.36.0
+
+## Ziel
+
+Der Theme Manager verwaltet Darstellung ausschließlich über einen versionierten Design-Token-Vertrag. Freies CSS, JavaScript, URLs, Dateipfade und nicht freigegebene Tokens werden nicht akzeptiert.
+
+## Modulgrenze
+
+`vendoo.themes` ist ab 1.36.0 ein natives Modul. Es besitzt:
+
+- `theme_profiles`
+- `user_theme_preferences`
+- Systemstandard in der bestehenden Settings-Ablage
+- Tokenvertrag und Accessibility-Prüfung
+- Theme-APIs mit Deny-by-default-Policies
+
+Andere Module greifen nicht direkt auf diese Tabellen zu.
+
+## Berechtigungen
+
+- Jeder angemeldete Benutzer darf seine eigene Darstellung speichern.
+- Eigene Theme-Profile, Import, Export, Löschen und Systemstandard benötigen `settings.manage`.
+- Alle Änderungen an Profilen und Systemstandard werden auditiert.
+
+## Sichere Werte
+
+Anpassbar sind nur freigegebene Farb- und Pixel-Dimensionstokens. Farben werden auf Hex/RGB-Kanäle geprüft. Dimensionen besitzen Mindest- und Höchstwerte. Nicht anpassbare Schatten-, Bewegungs- und Layoutverträge können nicht über die Oberfläche überschrieben werden.
+
+## Accessibility
+
+Die Validierung prüft zentrale Text-, Flächen-, Marken-, Gefahren- und Linienkontraste. Zusätzlich unterstützt die Runtime:
+
+- High Contrast
+- System-Farbschema
+- reduzierte Bewegung
+- kompakte, ausgewogene und großzügige UI-Dichte
+- tokenisierte Fokus-Ringe und Mindest-Zielgrößen
+
+## Migration
+
+Bestehende `vendoo-theme`-LocalStorage-Werte werden von der Runtime als Fallback übernommen. Nach Anmeldung lädt die Oberfläche die serverseitige Benutzerpräferenz. Datenbanktabellen werden additiv angelegt; vorhandene Benutzer und Einstellungen bleiben erhalten.