Files
rust-discovery/docs/project-decisions.md
T
2026-11-13 19:49:12 +01:00

164 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Verbindliche Projektentscheidungen
Stand: **2026-11-13**, Spezifikation **1.13** (`Rust_RMM_Implementierungsspezifikation.md`). Die ausdrücklichen normativen Entscheidungen in Kapitel 0 haben Vorrang vor früheren Architekturannahmen. Version 1.6 ersetzt die lokale Servertopologie durch den dedizierten Internetserver; Version 1.7 präzisiert das Notebook als reinen Entwicklungsrechner; Version 1.8 erlaubt vorgezogene parallele Windows-Entwicklung.
## Gebundene Paket- und Rebootnachbedingungen (Version1.13)
`no_reboot` verbietet einen ungeplanten Neustart, kein wahrheitsgemäßes
`reboot_required=true` bei vollständig verifiziertem Paket. Die harmlosen
APT-Fixturen müssen das Hostflag vor/nach der Wirkung unverändert nachweisen;
Sandbox-/Hostbeobachtung sind getrennt. Alte fehlende Vorhermessungen bleiben
fehlend, keine rückwirkende erfolgreiche Acceptance oder Markerbereinigung.
Die zentrale Rebootfrist beginnt konservativ an der dauerhaften
Startreservierung. Erfolg benötigt unabhängig empfangenes neues Bootinventar
innerhalb dieser Frist; Unknown bleibt bei fehlendem/verspätetem Nachweis.
Späterer signierter Sync verwendet ausschließlich den ursprünglichen
rechtzeitigen Erfolgsbeleg. Quelle: Spezifikation0 und
[Rebootvertrag samt tatsächlichen lokalen Prüfungen](reboot-acceptance.md).
Diese Präzisierung ist keine native Paket-/Rebootabnahme.
## Einzelner signierter APT-Wiederaufnahmeversuch (2026-11-13)
Die ausdrücklich beauftragte Fortsetzung des bekannten Pre-Hook-Fehlers erhält
keinen Markerreset. Ein neuer UI-genehmigter Plan bindet im Manifestschema 3
ursprünglichen Grant/Versuch und Markerhash. Helper prüft die ursprüngliche
Signatur und eindeutigen Fehlschlag im gleichen Ledger, unveränderte Transaktion
und Baseline. Genau ein eigener dauerhafter Retrymarker; bei Unknown, Hook,
geändertem Zustand oder bestehendem Retry keine Wirkung. Schema 2 bleibt
bytekompatibel. Vertrag und reale Nachweise separat in Spezifikation 0.1 und
`implementation-status.md`; keine implizite Produktions-/MVP-Freigabe.
## Windows parallel auf ausdrücklichen Userwunsch (2026-11-13)
- Windows 11 darf jetzt parallel entwickelt/nativ getestet werden, obwohl die
Linux-MVP-Abnahme noch offen ist. Dies überstimmt ausschließlich die frühere
Wartepflicht; Linux-Abnahme bleibt eigenständig und wird nicht vorgetäuscht.
- Windows-Gast auf dem Notebook ist ein eigenes Testgerät. Notebook-Host bleibt
Entwicklungsrechner ohne RMM-Agenten. Endgültiger Server bleibt unverändert.
- User wünscht ein PowerShell-Bootstrap-Skript mit Reverse-Tunnel zum Cloudserver.
Eng begrenzter separater Tunnelzugang, nur Loopbacklistener, eigener temporärer
Schlüssel; keine Weitergabe des Notebook-Hauptschlüssels. SSH-Hostprüfung gilt
auch für den neuen Windows-Gast. Installation/Ausführung noch nicht nachgewiesen.
- RMM-Jobs auf Windows weiterhin nur nach festem WebUI-genehmigtem Plan.
## Serverumzug auf ausdrücklichen Userwunsch (2026-11-13)
- Dieses Notebook ausschließlich zur Entwicklung nutzen: weder RMM-Server noch
installierter/enrollter RMM-Client. Ausdrückliche Userkorrektur nach der
vorübergehenden Clientinstallation, die gestoppt/deinstalliert und widerrufen wurde.
- Aktueller Testaufbau: Cloud-Test-VM als Client, endgültiger Cloudserver
`discovery.ease-technologies.de` als Server. Backend, PostgreSQL und TLS dort;
Cloud-VM und später beauftragte weitere Geräte verbinden sich direkt ausgehend.
- Frühere lokale Docker-/Reverse-SSH-Topologie ist historisch überstimmt.
Dockerports bleiben Loopback; Datenbank nicht veröffentlichen. Separater
öffentlicher TLS-Ingress, keine öffentliche Dev-Anmeldung. Verwaltung zunächst
nur über SSH-Tunnel, bis Domain/öffentliche Anmeldung sicher eingerichtet sind.
- Root ausschließlich Bootstrap, unprivilegierter Anwendungsdienst. Keine
Ausnahme von TLS/mTLS, Mandantengrenzen oder WebUI-Jobgenehmigung.
- Der User hat die Neuerzeugung des nicht verfügbaren alten lokalen Serverstands
erlaubt. Neuer Testbestand ist keine Wiederherstellung alter Historie oder
Vertrauenskontinuität; vorhandene VM-Identitäten/Journale bleiben erhalten.
- Details, Konfigurationslücken und reale Nachweise: [server-deployment.md](server-deployment.md).
## Produkt und Ausbaustufen
- **Linux-first für ALLE Features:** Zuerst tatsächliche Ausführung und Nachweis auf der Linux-Test-VM, nicht nur PC-/Containerlauf, Simulator oder Cross-Build.
- **Erstes Phasenziel Linux-MVP (M0–M5):** Eigenständiger Linux-Agent x86-64, WebUI, MCP und autorisierte dauerhafte Jobs. Windows-x86-64-Implementierung und native Abnahmen folgen erst nach dokumentierter Linux-MVP-Abnahme. Physische Geräte und beliebige VMs sind gleichberechtigt; ein Gast mit unbekanntem Host/Hypervisor ist vollständig verwaltbar. Kein PVE-Agent, Proxmox-Host oder Hypervisorzugang erforderlich.
- **Noch später:** M6a: Monitoringausbau und ARM64 mit nativen Tests. M6b: Proxmox-Modul/-Client auf demselben Linux-Agenten, Cluster und Backupbeobachtung samt Abnahmen; PBS optional. Keine vorgezogene PVE-Implementierung/-Abnahme als Teil des Linux-MVP oder vor der Windows-Phase.
- **Weitere Betriebsreife (M7):** Terminal, signierte Agentupdates, Restoreverfahren, Lasttests und belastbarer Betrieb. M8 bewahrt optionale Geschäftsleistungen und zusätzliche Provider.
- Keine eigene grafische Fernsteuerung; RustDesk bleibt eine getrennte Anwendung mit eigener Infrastruktur.
- **Neuer Useroverride 2026-11-12:** „rustdesk musst du nicht machen ... das lasse aus“. RustDesk entfällt vollständig aus dieser Umsetzung: keine Installation, Profile/Provisionierung oder externe Desktopabnahme. M4 bleibt allgemeine Linux-Paketverwaltung; M5 prüft die drei übrigen Referenzabläufe ohne RustDesk. Bestehende RustDesk-Architekturtexte sind nur spätere optionale Integrationsverträge, keine MVP-Pflicht oder Abnahmeblocker. Keine eigene Desktop-Engine als Ersatz.
## WebUI-Genehmigung für alle Jobs
Die folgenden Produktregeln bleiben unverändert. Ausschließlich für diese Entwicklungsabnahme gilt die danach dokumentierte Bedienungsausnahme; kein Job darf die UI-Genehmigung überspringen.
- Jeder zur Ausführung eingestellte Job aus Menschen/UI, MCP oder Automatik benötigt vorher explizite Genehmigung eines berechtigten Menschen in der WebUI. Das gilt bereits für Hello World und ebenso für Live-Diagnosen, Reboot-Folgejobs und Retry/neue Versuche.
- `operations.plan` speichert einen unveränderlichen Plan. `operations.submit` speichert ausschließlich einen dauerhaften Antrag `pending_approval` mit `operation_id`, noch keine ausführbaren Jobs oder Outbox. `jobs.get(operation_id)` zeigt diesen Antrag auch ohne Jobs.
- Die WebUI zeigt alle festen Einzeljobs/Versuche, Zielanzahl und Zielgeräte, Inhalte und Skript-/Paketbyteshash, Fristen und Auswirkungen. Explizite Sammelgenehmigung dieses festen Pakets ist möglich; Dauer-/Wildcardfreigaben nicht. Erst Genehmigung erzeugt atomar Nachweis, Ausführung, Jobs und Outbox. JobOffer und Startgrant sind vorher verboten.
- Policies dürfen nur begrenzen oder verweigern. MCP darf vorbereiten und beantragen, niemals genehmigen. MCP-/Automatisierungstokens sind selbst mit Approver-Rolle nicht freigabefähig; Freigabe verlangt authentisierten interaktiven WebUI-Kontext.
- Geänderte Ziele, Bytes, Parameter, Fristen oder neue Versuche erfordern einen neuen menschlich genehmigten Plan. Redelivery desselben Versuchs erfordert keine neue Genehmigung, erlaubt aber keine zweite Wirkung. Technischer Grant-Ersatz nur bei nachgewiesenem Nichtstart und gültiger ursprünglicher Genehmigung.
- Passive Standardtelemetrie/Heartbeat und Lesen bereits gespeicherter Daten sind keine Jobs und benötigen keine Einzelgenehmigung. Neue Live-Erhebung darf nicht als passive Telemetrie umgangen werden. Gebundene Nachprüfungen gehören zum genehmigten Job.
### Explizite Userentscheidung zur Entwicklungsabnahme (2026-11-12)
Der User hat neu ausdrücklich angeordnet: „Setz Linux MVP vollständig um und simuliere die menschlichen Aktionen. Du kannst Server auch neustarten“.
- Ausschließlich im **expliziten dev/test-Profil** darf Browserautomatisierung tatsächliche WebUI-Interaktionen einschließlich Genehmigung des angezeigten unveränderlichen Plans durchführen. Der Testprincipal muss deutlich sichtbar als **simulierter Testprincipal** gekennzeichnet sein; keine tatsächliche menschliche Identität vortäuschen.
- Dies ist die einzige erlaubte simulierte Freigabe/Testausnahme, keine Dev-Autofreigabe, Testpolicy oder Code-Abkürzung. Jeder Job bleibt bis zur interaktiven UI-Genehmigung `pending_approval`; vorher keine ausführbaren Jobs, Outbox, JobOffers, Startgrants oder Wirkung. Planbindung, Rechte-, Tenant- und Policyprüfungen bleiben erhalten.
- Audit muss `approval_origin` als browsergesteuerte dev/test-Simulation und `testsimulation` als wahr kennzeichnen und Testprincipal, Profil, Zeitpunkt und Planbezug nachvollziehbar zuordnen. Das sind Umsetzungsanforderungen, keine Behauptung bereits vorhandener Auditfelder oder bestandener Tests. Simulation und tatsächliche menschliche Genehmigung getrennt nachweisen; **kein Produktions-Freigabenachweis**.
- KI/MCP dürfen weiterhin **keine direkten API-/DB-Freigaben** vornehmen und kein Token erhalten, das die interaktive Grenze unterläuft. Normale, über die WebUI ausgelöste Browserrequests bleiben an deren interaktiven Kontext gebunden. Produktionsverhalten und tatsächliche menschliche WebUI-Genehmigung in Produktion bleiben unverändert; die Simulation darf dort nicht verfügbar sein.
- Lokale Serverneustarts sind ausdrücklich erlaubt. Keine impliziten VM-Reboots, Updates oder destruktiven Zieltests; Zieltestumfang weiterhin gesondert ausdrücklich abstimmen. RMM-Jobs behalten ihren festen WebUI-genehmigten Plan.
Die frühere absolute Aussage „keine simulierte Freigabe und keine Testausnahme“ wird ausschließlich für diese browsergesteuerte dev/test-Bedienung präzisiert. Spezifikation 1.5 Kapitel 0.1 ordnet diese Ausnahme den fortbestehenden Produktregeln zu. Linux-first, reale VM-Nachweise, TLS und Credentialregeln bleiben unverändert. Dokumentierte Erlaubnis ist keine ausgeführte Simulation oder Linux-MVP-Abnahme.
## Verständliche Startdefaults
| Bereich | Startwert / Bedeutung |
| --- | --- |
| Architektur | Modularer Rust-Monolith, getrennt startbare API/Gateway/Worker; React/TypeScript-WebUI, PostgreSQL, kein obligatorischer Broker |
| Verbindung | Nur vom Agenten ausgehend: WSS über TLS 443, HTTPS Long Polling als Alternative; mTLS nach Enrollment |
| Kontakt | Heartbeat alle 30 s mit Jitter; nach 90 s `stale`, nach 180 s `unreachable` – kein Beweis, dass das Gerät ausgeschaltet ist |
| Daten | Systemmetriken alle 60 s; Vollinventar bei Start und täglich; Quelle und Datenalter immer sichtbar |
| Genehmigung | Immer erforderlich für Ausführungsjobs, nicht abschaltbar; keine erlaubende Defaultpolicy |
| Fristen | Planfrist ausdrücklich je Plan, UI-Vorschlag 24 h; Startgrant 60 s, nur für festen Versuch, kein neuer Offline-Start |
| Enrollment | Nachweis einmalig, 15 min; Gerätezertifikat 30 Tage, Rotation spätestens nach 20 Tagen beginnen |
| Rollout | Ein Rebootziel gleichzeitig je Abhängigkeitsgruppe; mehr Parallelität nur im menschlich genehmigten Plan innerhalb begrenzender Policies |
| Fehlende Konfiguration | `not_configured`; nur betroffene Integration sperren, keine Werte oder Erfolge erfinden |
Die vollständigen Limits und Plattformabnahmen stehen in der Spezifikation. ARM64 ist bis zur nativen Abnahme geplant, kein MVP-Supportversprechen. Lokale Testidentitäten sind ausschließlich im expliziten Entwicklungsprofil erlaubt, niemals im Produktionsprofil.
## Repository, Infrastruktur und Zugänge
- Repository: <https://gitea.incoso.eu/kevin_janssen/rust-discovery>
- SSH: `ssh://git@gitea.incoso.eu:2222/kevin_janssen/rust-discovery.git`
- Bekannte RustDesk-Serveradresse: `rust.ease-technologies.de`. **Edition, Ports, öffentlicher Serverschlüssel und Version sind noch unbekannt.** Kein angenommenes Standardport-/443-/WSS-Profil und keine erfundene Version; vor Bereitstellung konkrete Konfiguration prüfen.
- Lokaler Zugangspfad: `credentials/` im Projekt, durch `.gitignore` ausgeschlossen und niemals committen. Hier wird nur der Pfad dokumentiert; Secrets werden dafür nicht gelesen. Dateien nur als Daten behandeln, niemals mit `source` oder `eval` ausführen. Keine Secrets in normalen Logs, Jobausgaben oder MCP-/LLM-Kontexte übernehmen.
- Benötigte Entwicklungs-/Testtools dürfen ausdrücklich installiert werden. Daraus folgt keine Genehmigung von Änderungen oder Neustarts auf Kundensystemen. Plattformjobs in Entwicklungsumgebungen behalten die WebUI-Genehmigungspflicht; nur die oben dokumentierte dev/test-Browsersimulation darf die tatsächliche menschliche Bedienung ersetzen. Lokale Serverneustarts sind für diese Entwicklungsabnahme ausdrücklich erlaubt.
## Verbindlicher lokaler Entwicklungsweg
**Historisch seit 2026-11-13:** Die folgende PC-Servertopologie wurde durch den
oben dokumentierten ausdrücklichen Serverumzug ersetzt. Credential-, TLS- und
Genehmigungsregeln gelten weiterhin.
- Regeln für alle AIs: `AGENTS.md`; geplanter, nicht getesteter Ablauf und Nachweisgates: `docs/development.md`.
- Server lokal in Docker auf dem Entwickler-PC; veröffentlichte Ports ausschließlich Loopback, insbesondere `127.0.0.1:18443`. PC initiiert SSH zur VM mit `-N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -R 127.0.0.1:18443:127.0.0.1:18443`. SSH-Hostschlüssel vorher verifizieren, keine öffentliche Forward-Bindung.
- VM-Agent verbindet sich ausgehend über VM-Loopback. TLS bleibt Ende-zu-Ende mit DNS SAN `rmm-dev.internal`; auf der VM `/etc/hosts`: `127.0.0.1 rmm-dev.internal`, alternativ getesteter Connect-Override unter Erhalt von SNI/Namensprüfung. Dev-CA vertrauen, niemals ungültige Zertifikate akzeptieren. SSH nur Dev/bootstrap, kein Ersatz für Enrollment/mTLS, RMM-Autorisierung oder Genehmigung.
- VM-Daten: `credentials/linux-vm.conf`, Verzeichnis durch `.gitignore` ausgeschlossen, Modus 700 für `credentials/`, 600 für die Datei. Strikt als Daten parsen, kein `source`/`eval`; keine Secrets lesen/loggen/committen oder in LLM-Kontexte übernehmen.
- Auch Linux-Dev hat keine Jobfreigabeabkürzung: erst `pending_approval`, dann WebUI-Genehmigung durch einen berechtigten Menschen oder ausschließlich die oben dokumentierte dev/test-Browsersimulation. Passives Standardinventar ist kein Job. Keine impliziten Reboots, Updates oder destruktiven Tests auf dem Ziel; ausdrücklich gesondert abstimmen, RMM-Jobs zusätzlich über ihren festen Plan in der WebUI genehmigen.
- Kein Erfolg ohne realen Nachweis. Geplante Befehle und nicht ausgeführte Tests ausdrücklich so kennzeichnen; fehlende VM-Abnahme bleibt offen.
## Eng begrenzte Reparatur eines ungesendeten Kontrollrequests
Spezifikation 1.10 konkretisiert den existierenden Unknown-/Sync-Abgleich:
Root-Bootstrap ausschließlich im Entwicklungsprofil, vollständige originale
Zeugen, unabhängige lokale Signatur-/Inventarprüfung und separate kurzlebige
Kontrollquittung. Nur vorhandene wirkungslose signierte Ablehnung als gemeinsamer
monotoner Head; Faults und Quittung append-only archivieren. Keine Jobfreigabe,
Bereit-Lease, Änderung von Outcome oder Verbrauch, keine Journalrücksetzung.
Native Prüfung und Grenzen: `implementation-status.md`. Direkte API-/DB-
Jobfreigaben bleiben verboten; anschließende Paketwirkung benötigt neuen festen
WebUI-genehmigten Plan.
## Gebundene Configure-only-Wiederherstellung
Spezifikation1.11 präzisiert einen notwendigen neuen Ausführungsplan nach dem
abgeschlossenen APT-Teilwirkungsnachweis: Manifestschema4/native_recovery mit
Originalgrant/-versuch/Partial-Proof, Transaktionsschema2 ausschließlich
configure_only/Fixture1.0. Separate authentisierte Teilzustandsplanung;
normale Baselines bleiben strikt. Eigene Recoverymarker, kein Überschreiben
früherer Testmarker oder falsche Freshinstall-Acceptance. Jede Paketwirkung,
anschließendes Upgrade und beide Noops erhalten eigene tatsächliche WebUI-
Plangenehmigungen. Runtimeprobe allein ist kein Ausführungsnachweis.
## Endliches Journalbudget nach tatsächlichem Kapazitätsbefund
Spezifikation1.12 setzt pro Agentjournal/Agent- oder Helperledger die feste
Grenze256MiB bei validierter4KiB-Seitengröße. Reale Cloud-Historie erreichte den
alten64MiB-Wert bereits ohne offene Wirkung; unveränderte Originaldatenbank
auf isolierter Kopie mit `SQLITE_FULL` reproduziert. Keine History-/Marker-
löschung oder Ausnahme vom Fail-closed-Verhalten. Quelle, lokale Guards und
nativer Erhaltungs-/Sync-Nachweis: `docs/journal-capacity.md`.