Files

T

HarmenandClaude Opus 5 de955b607d Testclient fase 1: er is geen Evolu-client voor Node, dus die stellen we samen

Het plan is gepromoveerd naar Actief/003-Testclient en tier A, en fase 1 is af.

De uitkomst die het plan als eerste wilde weten: @evolu/nodejs 3.1.0 bevat geen
client. Het pakket levert de relay plus losse bouwstenen, maar er is geen
createEvoluDeps voor Node zoals @evolu/web die voor de browser heeft. De
afhankelijkheden voor createEvolu worden nu samengesteld in
tools/relay-client/src/evolu-node.js, uit de in-memory workers van
@evolu/common; src/client.js is de publieke kant met eigenaars en blobs.

Vier dingen zaten in de weg en alle vier faalden ze stil, met een instantie die
het lijkt te doen tot de eerste schrijfactie: de ontbrekende installPolyfills
(Node 24 mist Map.getOrInsertComputed), createEvoluDeps overslaan, de
AsyncDisposableStack van initSharedWorker laten vallen, en workers zonder eigen
reportDefect. Dat laatste is waarom de andere drie te vinden waren. Uitgeschreven
in PLAN.md 4e.

tests/test_client_lokaal.mjs schrijft daarom een blob weg en leest hem terug in
plaats van alleen een instantie te maken, en heeft een wachthond: bij een defect
in een worker blijft de suite anders hangen in plaats van rood te worden, en dat
gebeurde bij de mutatietoets letterlijk. Beide mutaties lieten de juiste toets
omvallen.

Nog niet geprobeerd: praten met de relay. Daarvoor is het adres van de Umbrel
nodig en dat komt van de gebruiker; het gaat niet in deze publieke repo.

Suite: 405 goed, 0 fout over alle acht de toetsen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-09 12:59:55 +02:00

9.3 KiB

Raw Permalink Blame History

Testclient - masterplan

App: Evolu Relay. Status: nog niet actief. Dit is één bestand en dat is bewust: er wordt nog niet aan gewerkt. Bij promotie naar Plannen/Actief/NNN-Testclient/ worden de paragrafen hieronder over de vier bestanden verdeeld; zie HomeGit/Docs/Werkproces.md §1b.

Afhankelijk van: niets. De relay draait sinds 28-08-2026 en de haken die dit plan beproeft bestaan al.

1. Doel

Een eigen cliënt waarmee je meerdere eigenaars kunt aanmaken, ze op de relay kunt laten verbinden en er gegevens doorheen kunt duwen, om het toegangsbeleid en de opslag te beproeven zonder Trezor Suite en zonder hardware.

Aanleiding: Suite is vandaag de enige cliënt, en die vraagt een apparaat dat aan het toestel kan (zie Upstream-evolu-relay.md §9). Daardoor rust een deel van wat we over deze app opschrijven op redenering in plaats van op een proef. Het scherpste voorbeeld staat in §10 van datzelfde document: blokkeren werkt pas bij de volgende verbinding. Dat is uit de broncode afgeleid en nooit gezien.

2. Afbakening

Een programma dat buiten de Umbrel draait, op de laptop, en dat via de gepubliceerde relay-poort verbindt. Meerdere eigenaars naast elkaar, elk met een eigen sleutelmateriaal en een eigen lokale database. Eén bedieningsvlak waarin je die eigenaars ziet en aanstuurt.

3. Niet-doelen

Geen tweede relay en geen wijziging aan de app. Als dit plan een aanpassing in tools/evolu-relay/ nodig lijkt te hebben, is dat een aanwijzing dat er iets misgaat in de opzet, niet een taak. De relay wordt beproefd zoals hij draait.
Geen ontcijfering van gegevens van Trezor Suite. De cliënt maakt eigen sleutels en leest zijn eigen gegevens. Wat Suite op de relay zet blijft onleesbaar, en dat is de belofte in het manifest. Zie CLAUDE.md, "Zet geen ontcijfering in deze app", en §11 van het naslagdocument.
Geen onderdeel van de app store. Dit is gereedschap in tools/ en het gaat nooit in een image of in een app-map mee.
Geen nabouw van het protocol. Net als bij de relay geldt: @evolu/common doet het werk, wij roepen het aan.

4. Ontwerp

4a. Een eigenaar is een mnemonic plus een eigen map

Evolu leidt een AppOwner af uit een mnemonic. Een tweede eigenaar is dus niets anders dan een tweede mnemonic met een eigen SQLite-bestand ernaast; er is geen accountbegrip dat gedeeld moet worden. De cliënt bewaart per eigenaar een map met de mnemonic en de database, onder een pad dat in .gitignore staat.

Dat sleutelmateriaal is van deze proefopstelling en heeft geen waarde buiten de relay, maar het blijft sleutelmateriaal: het staat niet in de repo en het wordt niet in een logregel afgedrukt. Het OwnerId wel, want dat is publiek en je hebt het nodig om de eigenaar op de statuspagina terug te vinden (§1b van het naslagdocument).

4b. Eén bedieningsvlak voor de cliënt

Alles wat de cliënt doet, gebeurt vanuit één scherm. Geen losse opdrachten per eigenaar en geen tweede terminal ernaast: je ziet de eigenaars in een lijst en bedient ze daar. Wat dat scherm kan:

Onderdeel	Wat je ziet of doet
De lijst	per eigenaar zijn naam, zijn `OwnerId`, of hij verbonden is, wanneer er voor het laatst iets over de lijn ging, en hoeveel er geschreven is
Per eigenaar	aanmaken, verbinden, verbreken, een blob schrijven met een instelbare omvang, teruglezen, en weggooien
Het log	wat er per verbinding gebeurt, met tijdstip. Dit is waar de proeven uit §4c af te lezen zijn
De relay	het adres waarmee verbonden wordt, en of hij een verbinding aanneemt

Vorm: een kleine HTTP-server in hetzelfde proces met één pagina ervoor, in de stijl van de statuspagina's van beide apps. Geen bouwstap en geen framework; die pagina's laten zien dat dat hier genoeg is. De opdrachtregel blijft eronder bestaan, want stap 2 van §5 heeft hem toch nodig en het is prettig om een proef te kunnen scripten.

Aan de server-app wordt niets gedaan. Bevestigd door de gebruiker op 09-09-2026: die draait en synchroniseert met Trezor Suite op de Mac. Dit plan raakt tools/evolu-relay/ dus niet, en een bevinding uit §4c is materiaal voor Umbrelapp, geen taak hier.

Eén grens om te kennen voordat iemand er knoppen bij wil zetten: de leerstand openzetten, blokkeren en labelen kán deze UI niet, en dat is de poortindeling van de app en geen tekortkoming van het gereedschap. De relay publiceert hostpoort 3852 en daar praat de cliënt mee, maar de agent-API (GET /api/status, POST /api/command, POST /api/label) hangt achter app_proxy met de inlog van umbrelOS, en poort 8000 staat niet op de host. Dat blijft dus op de statuspagina van de app, in een tweede tabblad. Het omzeilen daarvan zou een onbeschermde poort vragen, en dat haalt precies de bescherming weg waarvoor de poorten in 0.0.2 omgedraaid zijn (CLAUDE.md, "De poorten staan omgekeerd ten opzichte van wat je verwacht").

4c. Wat er dan te beproeven valt

Dit is de eigenlijke opbrengst, en elk punt is vandaag niet te proberen:

Proef	Wat er hoort te gebeuren	Waar het vandaan komt
Onbekende eigenaar, venster dicht	HTTP 401, socket dicht, niets in de database van de relay, wel een regel in de weigerlijst	§10 van het naslagdocument, afgeleid uit de broncode
Diezelfde eigenaar toelaten en opnieuw verbinden	de hele geschiedenis komt alsnog binnen, want de cliënt was niets kwijt	§10, punt 3
Blokkeren tijdens een lopende verbinding	de eigenaar blijft schrijven tot hij opnieuw verbindt	§10, punt 4. Open punt 10 van Umbrelapp
Venster van twee minuten, met de pagina dicht	de teller loopt in het relay-proces en sluit vanzelf	`CLAUDE.md`, "Het tijdvenster loopt in het relay-proces"
Eén blob boven `RELAY_MAX_WRITE_BYTES` (1 MB)	geweigerd; meerdere kleinere samen niet, want de grens is per schrijfactie	§8 van het naslagdocument
Twee eigenaars die tegelijk verbinden	onafhankelijk, en elk ziet alleen zijn eigen gegevens	§1b

Wat er als bijvangst uit kan komen, en dat is de reden om de proeven echt te dóen: owners.json groeit hier voor het eerst voorbij één of twee regels, en de statuspagina is nog nooit met een handvol eigenaars en een volle weigerlijst gezien.

4d. Waar het staat, en wat het niet raakt

tools/relay-client/, met een eigen package.json. Niet in een app-map, want alles daar wordt bij installatie naar het apparaat gekopieerd (CLAUDE.md, "Zet geen CLAUDE.md of andere werkbestanden in een app-map"). Geen VERSION, geen image, geen manifest: er is niets uit te rollen, dus de versieregels van de twee apps gelden hier niet.

5. Het werk in grote lijnen

De cliënt-API van @evolu/common 8.7.0 verifiëren. Een eigenaar uit een mnemonic, een schema met een kolom waar een blob in past, en verbinden met een syncUrl. Dit staat expres eerst: van de relaykant is alles nagetrokken, van de cliëntkant niets. Valt die API tegen, dan verandert de rest van dit plan.
Een kale opdrachtregel die één eigenaar maakt, verbindt en schrijft. Dat is het moment waarop bekend is of het werkt.
Meerdere eigenaars naast elkaar, elk in een eigen map, met een register erbij.
De UI eromheen: de lijst, de knoppen per eigenaar, en de meldingen uit de verbinding.
De proeven uit §4c lopen, en de uitkomsten terugschrijven naar de plek waar de bewering nu staat: §10 van het naslagdocument en open punt 10 van Umbrelapp.

6. Open punten

Hoe zichtbaar is een 401 in de cliënt? Evolu probeert opnieuw en is ontworpen om een relay te overleven die er niet is. Als een weigering en een relay die plat ligt in de cliënt hetzelfde signaal geven, is de eerste proef uit §4c niet af te lezen. De uitweg blijft binnen dit gereedschap: een eigen WebSocket-poging naast Evolu, met dezelfde OwnerId in de URL, die de statuscode wel te zien krijgt. Dat is een handeling van een paar regels, want de OwnerId staat in de URL van de verbinding (§10 van het naslagdocument).
Wat is een zinnige blob om mee te experimenteren? Willekeurige bytes zijn genoeg voor de bytegrens, maar niet om te zien of gegevens werkelijk heen en weer gaan. Iets met leesbare inhoud en een teller is waarschijnlijk beter.
Wordt de gegevensmap van de proef opgeruimd? Twintig eigenaars die blijven staan is rommel, en het is sleutelmateriaal. Waarschijnlijk een opdracht die er één weggooit en één die alles weggooit.
Data per eigenaar wissen op de relay staat al open bij Umbrelapp. Dit gereedschap maakt dat makkelijk te beproeven maar lost het niet op; het blijft schrijven in andermans schema (§8 van het naslagdocument).

7. Verificatie

Wat automatisch kan is klein en dat is eerlijk om vooraf te zeggen. Het meeste van dit gereedschap is netwerk en UI. Wat wél in de suite hoort:

het register van eigenaars: aanmaken, teruglezen, een naam die al bestaat, een map die half is;
het afleiden van een OwnerId uit een mnemonic, met een vaste mnemonic en een vaste verwachte uitkomst. Dat is de toets die omvalt als de bibliotheek onder ons iets anders gaat doen;
het lezen van de opdrachtregel.

Alles wat een relay nodig heeft is handwerk, en dat is precies het doel van dit plan: de proeven uit §4c worden met de hand gedaan en de uitkomst wordt opgeschreven. Een groene suite zegt hier dus weinig, en de uitslag van dit plan staat in de documenten die het corrigeert.

9.3 KiB Raw Permalink Blame History