Files
rust-discovery/docs/windows-helper-pipe-drain.md

113 lines
6.8 KiB
Markdown

# Windows Helper: begrenzte Transportbestätigung
Dieser Schnitt ist im isolierten Zweig `codex/windows-pipe-drain` implementiert.
Eine native Ausführung des neuen Framings und ein Komponentenupgrade sind noch
nicht nachgewiesen. Die bestehenden Nachweise des Agenten `89004ad3…` und Helpers
`e6aacbdd…` bleiben historische Belege ihres ursprünglichen Framings.
## Anlass und Beleggrenze
Beim tatsächlichen Agenten wurde `client_read_reply / HELPER_PIPE_IO / 233`
beobachtet; die Helperdiagnose war nicht vorhanden. Der bisherige Dienst rief
auch nach erfolgreichem Schreiben der Antwort sofort `DisconnectNamedPipe` auf.
Microsoft dokumentiert, dass dabei ungelesene Pipebytes verworfen werden. Das
ist ein konkreter möglicher Fehlerpfad, aber kein Nachweis, dass genau dieser
Pfad die beobachtete Störung verursacht hat.
[DisconnectNamedPipe](https://learn.microsoft.com/en-us/windows/win32/api/namedpipeapi/nf-namedpipeapi-disconnectnamedpipe)
Eine fehlende Diagnose beweist weder einen erfolgreichen Peercheck noch eine
bestimmte Ablehnung: strukturierte `Denied`-Antworten erzeugen keinen privaten
Pipefehlerbeleg, Connect-Leerlauf kann ohne Beleg enden, und das begrenzte
Diagnoseschreiben selbst kann fehlschlagen. Diese Pfade werden hier nicht
umgedeutet oder gelockert.
## Framing v2 und Reihenfolge
Agent und Helper verwenden ausschließlich `\\.\pipe\RustDiscovery-System-v2`.
Jeder JSON-Frame beginnt mit acht ASCIIbytes `RDPIPC02`, gefolgt von vier Bytes
Länge in Big Endian und den bisherigen, maximal 1 MiB großen JSONbytes.
V1 und V2 haben unterschiedliche Endpunkte; zusätzlich verweigert der V2-Parser
alte oder fremde Framingtags. Es gibt keinen stillen Fallback. Beide EXEs müssen
als gemeinsam qualifiziertes, gegenseitig gepinntes Paar bereitgestellt werden.
Die JSONschemas von Call/Reply, `helper.system.v1`, Systempolicy-Schema 1 und
RMM-Jobbytes ändern sich nicht.
Nach dem vollständigen Lesen der Antwort prüft der Agent weiterhin den tatsächlichen
Helperprozess, Schema, Challenge, Enrollmentbindung, Policyhash, Helperbinaryhash
und die Operation/Antwort-Zuordnung. Erst danach schreibt er genau 56 Bytes:
`RDPACK02` (8), ursprüngliche UUID-Challenge in UUID-Bytefolge (16), SHA-256 der
**exakt empfangenen JSON-Antwortbytes** (32). Es findet keine Re-Serialisierung
für diese Prüfsumme statt. Auch eine vollständig geprüfte `Denied`-Antwort wird
so transportseitig bestätigt, ohne sie in einen Erfolg umzuwandeln.
Der Helper prüft denselben bereits authentifizierten Peer vor dem Schreiben und
nach dem Lesen der Bestätigung. Schreiben, Empfang und Prüfung der Bestätigung
teilen dieselbe bisherige Antwortdeadline von fünf Sekunden; der Client behält
seine bisherige Gesamtdeadline. Erst danach trennt die Dienstschleife die Pipe.
Fehlende, falsche oder verspätete Bestätigung schließt den bestehenden Syncgate
und trennt die Verbindung über den bisherigen Fehlerpfad; statische Diagnosen
unterscheiden `server_drain_receipt` und `client_drain_receipt`. Es gibt keinen
weiteren Aufruf, Retry oder erneute Ausführung.
Diese Bestätigung bestätigt nur den Empfang der Antwortbytes. Sie ist kein
JobResult-, Journal-, SignedSync-, Grant-, Freigabe- oder Wirkungsbeleg und löscht
keinen dauerhaften Zustand. Ein bereits ausgeführter Auftrag wird durch einen
fehlenden Transport-ACK nicht zurückgenommen oder wiederholt.
`FlushFileBuffers` wird nicht verwendet: dieser synchrone Pipeaufruf wartet laut
Microsoft bis zum Lesen aller gepufferten Daten und bietet hier keine passende
begrenzte Warteoperation.
[FlushFileBuffers](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-flushfilebuffers)
## Prüfung und verbleibender nativer Nachweis
Die bestehenden IPC-Codecfälle prüfen zusätzlich fremde/alte Frameversionen,
begrenzte Längen sowie manipulierte ACK-Tags, Challenge und Prüfsumme. Eine andere
JSON-Bytefolge mit gleichem JSON-Inhalt darf den ursprünglichen Frame nicht
bestätigen. Die bestehenden Unitfallzahlen bleiben dadurch unverändert.
Lokale Qualifikation wird separat in einem geschützten `devstate/`-Beleg mit
Quellen- und Artefakthashes erfasst. Cross-Clippy und Linken sind kein nativer
Pipebeleg. Vor einem Zielupgrade sind unabhängiger Quellreview, die nativen
Windows-Units des gleichen Manifests und ein eigener erhaltender Paarupgrade mit
explizitem Backup sowie anschließendem tatsächlichen Agent/Helper-Austausch
notwendig. Alle Produktgates bleiben geschlossen.
Lokale Ausführung: Default- und `system-helper`-Clippy für alle Windows-GNU-Targets
mit `-D warnings`, Release-Build beider EXEs und Linken beider Unitprogramme waren
erfolgreich. 61 gebundene Quelldateien blieben vor/nach dem Lauf gleich. Die
bestehenden 23 Library- und 7 Binary-Unitfälle sind weiterhin die **erwartete**
native Liste; hier wurde kein Windows-Testprogramm ausgeführt. Geschützter
Beleg: `devstate/windows-pipe-drain/qualification-1e0f2b22-1e74-41af-b8ed-0a356be054ba/qualification.json`.
## Separater Build-/Unitrunner
`deploy/windows/system_pipe_acceptance.py` erstellt einen neuen Pack unter
`devstate/windows-pipe-drain-build/`. Er prüft den unveränderten lokalen
Qualifikationsbeleg samt ursprünglichen Links und verwendet die bereits
bestandenen Clippy-/Release-/Unitlinkschritte wieder. Nur die fehlenden beiden
Release-Stateprobes werden ergänzt. Alle sechs Auslieferungsdateien erhalten
eine unveränderte `.linked`-Kopie; ausschließlich die Unit-Auslieferungskopien
werden von Debuginformationen befreit. Neue Quellen einschließlich Runner,
Compilerimage, Cargo-/Protoinputs und tatsächlich verwendeter Bootstrapmodule
sind vor/nach dem Build gebunden.
`--access-root` muss der ursprüngliche Hauptcheckout sein. Nur dort werden die
vorhandenen geschützten Zugangskonfigurationen für den bereits gepinnten
Bootstraptransport und die tatsächlichen Linux-80-/Windows-58-Corebelege gelesen.
Es werden keine Zugangsdaten oder Main-`devstate`-Bäume kopiert oder verlinkt.
Neue Build-, Upload- und Unitfallbelege gehören zum isolierten Pipeworktree.
Der Native-Unitfall verwendet den neuen Namespace `native-pipe-v2`. **Beide**
vollständigen nativen Listen müssen exakt den erwarteten 23 Library- und 7
Binary-Namen entsprechen, bevor irgendein Unitfall ausgeführt wird. Intent,
Listen, Start und einzelne Testergebnisse werden create-only gespeichert.
Nach einem Antwortverlust darf ausschließlich derselbe Fall gelesen werden;
auch ein fehlender oder unvollständiger Fall löst keinen erneuten Start aus.
Die Units laufen als Bootstrapadministrator, nicht als Produkt-LocalService,
und beweisen keinen tatsächlichen Pipeaustausch. Zentral gespeicherte
Gerätezähler und geschlossene Fault-/Policyflags werden vor/nach verglichen.
Der bestehende rohe `helper_peer_controls::raw`-Probe schreibt weiterhin einen
V1-Header. Sein Ablehnungsresultat ist deshalb **kein** V2-Peernegativnachweis;
Runner und Manifest behaupten ausdrücklich keine solche Qualifikation.