HarmenandClaude Opus 5
89aa06639b
tools/evolu-relay/src/ bevat nu een eigen programma dat createRelay uit @evolu/nodejs aanroept met de twee terugroepfuncties die het bedoelde uitbreidpunt vormen. De relay zelf komt uit npm en wordt niet nagebouwd of aangepast; de opstartvolgorde is overgenomen uit apps/relay/src/index.ts van Evolu zelf. De opzet is drie bestanden met een harde scheiding, en die scheiding is de reden dat hier iets te testen valt. policy.js bevat het beleid als pure functies: geen bestanden, geen netwerk, geen klok. store.js is de enige plek met schijf erin. index.js doet niets anders dan lezen, doorgeven en opslaan. Het beleid: de eerste eigenaar die zich meldt wordt geleerd, een schakelaar bepaalt of er nog nieuwe bij mogen, en een eigenaar is te blokkeren, alsnog toe te laten of te vergeten. Geweigerde pogingen worden onthouden voor de pagina, afgekapt op twintig, want elke poging is een id dat de ander zelf verzint. Een onleesbaar owners.json wordt opzij geschoven en de app gaat dan dicht in plaats van open: we weten dan niet wie er toegelaten was, en met de leerstand aan zou de eerstvolgende die verbindt de nieuwe eigenaar worden. Met test: node tests/test_limiter.mjs, 60 toetsen, en de toetsen gaan over de guards en niet over het gelukkige pad. De beslissende regel is muteertest gedaan en de juiste toets viel om: een geblokkeerde eigenaar mag er niet alsnog in doordat de leerstand aanstaat. Het bestand is .mjs omdat de repo-root geen package.json heeft en een .js daar als CommonJS gelezen zou worden. build.sh bouwt niet langer de repo van Trezor maar onze eigen Dockerfile, dus git is er niet meer voor nodig en de pin zit nu in package.json. De image is node:24-slim en niet alpine, want better-sqlite3 heeft binaries voor glibc en niet voor musl. Er is nog geen package-lock.json; het script waarschuwt daarvoor en het staat als taak. Onderweg bleek een aanname van vanmiddag fout: de 1 MB uit de gepubliceerde image geldt per schrijfactie en niet per eigenaar. Er valt dus geen labelgeschiedenis tegenaan te lopen. Dat is rechtgezet in het plan en in de naslag, en het getal is overgenomen als bewuste keuze met RELAY_MAX_WRITE_BYTES ernaast. Wat er niet in zit en ook niet gegokt is: data per eigenaar wissen. Het beleid kan een eigenaar vergeten, maar zijn berichten staan in de SQLite van de relay, en dat is andermans schema. Tests: alle vier groen (32, 54, 39 en 60 goed, 0 fout). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
9.9 KiB
UmbrelApps - projectspecifieke afspraken
De algemene werkafspraken staan in HomeGit/CLAUDE.md en worden hier niet herhaald. Hieronder alleen wat
eigen is aan dit project.
Deze repo is één community app store met twee apps erin. umbrelOS leest per store één repo, en dat is de reden dat ze samen in één repo zitten in plaats van elk in een eigen. Eerst de regels die voor allebei gelden, dan per app wat alleen daar geldt.
| App | Map | Toestand |
|---|---|---|
| Electrum Gate | whatsnext-electrum-gate/ |
draait op de Umbrel, wordt gebruikt |
| Evolu Relay | whatsnext-evolu-relay/ |
gepakketteerd, nog nooit geïnstalleerd; zie het plan Umbrelapp |
Zet geen CLAUDE.md of andere werkbestanden in een app-map. umbreld kopieert bij installatie de héle
app-map naar ~/umbrel/app-data/<app-id>/ met rsync --archive, dus alles wat daar staat belandt op het
apparaat en in de back-up. Documentatie hoort in Docs/, tests in tests/, allebei in de repo-root.
Umbrel-regels die je niet mag omzeilen
Deze gelden voor élke app hier, want het zijn eigenschappen van umbrelOS. Met bron in Docs/Referenties/Umbrel-appstore-spec.md.
Geen accolade-variabelen in een *.template die er niet horen. umbreld haalt bij elke start elk
${...} in zo'n bestand door envsubst, ook een variabele die niet bestaat, en die wordt dan leeg. Dat
sloopt Python-code, en in een nginx-config betekent het geen $host, geen log_format en geen
access_log met variabelen. Moet er tóch een dollarteken in een nginx-directive, dan hoort die directive
in een bestand dat het command-blok van de compose wegschrijft, want daar is $$ te ontsnappen.
Wat bij een update meekomt is een whitelist: docker-compose.yml, *.template, exports.sh, torrc,
hooks en umbrel-app.yml. Al het andere bereikt een bestaande installatie nooit, zonder foutmelding.
Zet logica die later nog moet kunnen wijzigen dus in de compose of in een *.template, en nooit in een
los bestand of in een submap.
Een wijziging zonder verhoging van version in umbrel-app.yml wordt niet uitgerold. Geen melding,
geen fout; umbrelOS ziet hetzelfde nummer en doet niets. Dat heeft hier een keer een dag gekost. De
versies staan per app los van elkaar.
Alle gebruikersstaat onder ${APP_DATA_DIR}/data/..., en nooit erbuiten schrijven. Elke map die bij
de eerste start moet bestaan, heeft een .gitkeep in de repo.
Geen wachtwoord of ander geheim in de repo. umbrelOS levert ${APP_PASSWORD} en ${APP_SEED} aan,
per installatie afgeleid. Deze repo is publiek, dus een literal is een gepubliceerd wachtwoord. Dat wordt
pas echt scherp bij Evolu Relay, want daar hoort een Postgres bij.
Mapnaam gelijk aan het id in het manifest, en allebei met het store-id whatsnext ervoor.
Electrum Gate
De tests draaien
python tests/test_agent_certificates.py
python tests/test_server_start_zonder_certificaat.py
Deze twee gaan over Electrum Gate en noemen die app-map bij naam. Er is een derde die over de store gaat en zijn apps zelf vindt, dus over beide:
python tests/test_appstore_vorm.py
Geen testrunner en geen afhankelijkheden: het zijn losse scripts die 0 teruggeven als alles goed is. Ze horen samen met de test van Evolu Relay hieronder bij "de suite" en draaien voor een commit; de uitvoer eindigt bij alle vier met een regel "N goed, M fout". Er is geen watch-modus; de suite kost minder dan een seconde.
test_appstore_vorm.py toetst expres niet dat images op een digest gepind zijn. Dat is wél de regel,
maar geen van de twee apps haalt hem vandaag, en een suite die altijd rood staat wordt niet gelezen. Hij
drukt de pinstatus wel af.
Twee dingen om te weten voordat je een groene uitslag vertrouwt:
- sommige toetsen slaan zichzelf over en melden dat. De vergelijking met
sslheeft de certificaatwinkel van het besturingssysteem nodig, en de subjectAltName-toets heeft netwerk nodig. Staat erOVERGESLAGENin de uitvoer, dan is dat deel níet bewezen. Lees de uitvoer dus, tel niet alleen de exitcode; - de suite dekt de agent, niet de pagina. Alles in
index.html.templateis handwerk in een browser.
Architectuurregels
Geen Docker-socket. De agent kan nginx daarom niet zelf herladen; hij zet een vlagbestand neer en de nginx-container herlaadt zichzelf. Als je denkt de socket nodig te hebben, is er bijna zeker een vlagbestand-oplossing.
De pagina start altijd, ook zonder certificaat. Het TLS-blok staat daarom niet in
nginx.conf.template maar in stream.conf.template, en het command-blok van de compose zet dat pas in
/var/lib/gate/tls/ als de agent een cert.conf geschreven heeft; nginx.conf haalt die map met een
jokerteken op. Zet het blok niet terug in nginx.conf, hoe netjes dat ook staat: nginx weigert te starten
als een listen ssl geen certificaat heeft, en dan komt de pagina waarop je dat certificaat kiest ook niet
omhoog. Dat was de fout in 0.0.3. tests/test_server_start_zonder_certificaat.py houdt het dicht.
Bij twijfel over een certificaat weigert de app. Meerdere kandidaten zonder keuze van de gebruiker levert géén automatische keuze op, ook niet "de nieuwste". Een verkeerd certificaat geeft een verbinding die het lijkt te doen en pas bij de wallet stukloopt op naamverificatie, en dat is veel lastiger te vinden dan een app die weigert en zegt waarom.
Feiten
- App-id en mapnaam
whatsnext-electrum-gate. - De TLS-poort is 50022, niet de conventionele 50002: die bezet Fulcrum op de host.
- De app leest de certificaatmap van Zoraxy alleen-lezen. Dat is het meest ongebruikelijke aan dit pakket; zie het masterplan Publicatie-Gate §4.
Evolu Relay
De tests draaien
node tests/test_limiter.mjs
Dit is de vierde test van de suite en de enige die geen Python is. Hij toetst het toegangsbeleid uit
tools/evolu-relay/src/policy.js: wie er op de relay mag schrijven, wat er met een onbekende eigenaar
gebeurt, en of een geblokkeerde eigenaar er niet alsnog in komt doordat de leerstand aanstaat. Node 24 of
hoger, geen afhankelijkheden, en het bestand is met opzet .mjs: in de repo-root is er geen package.json,
dus een .js zou als CommonJS gelezen worden en de import falen.
Het beleid staat los van de relay en dat is de reden dat dit te testen is. policy.js bevat alleen
pure functies: geen bestanden, geen netwerk, geen klok. Wat wél schijf raakt staat in store.js, en de
relay zelf wordt in index.js alleen aangeroepen. Houd die scheiding aan; anders is er van deze test niets
meer over.
Architectuurregels
De relay-code is niet van ons. Dit gebruikt @evolu/nodejs uit npm; er worden geen wijzigingen aan die
software gedaan en er wordt niet bovenstrooms bijgedragen. Wat wij toevoegen zijn de twee terugroepfuncties
isOwnerAllowed en isOwnerWithinQuota, en dat is het bedoelde uitbreidpunt. Bouw de relay niet na.
Het programma en het bouwrecept staan in tools/evolu-relay/, nooit in de app-map. Een Dockerfile
staat niet in de update-whitelist, dus bouwen-in-de-app kost bij elke nieuwe versie een deïnstallatie plus
herinstallatie, en het zou de installatie minuten laten hangen.
Verhoog je VERSION in build.sh, dan verhoog je ook version in het manifest. Anders is er een
nieuwe image en een oude installatie, zonder dat iets dat meldt. Houd die twee gelijk.
De app-map loopt achter op
tools/. Het programma hierboven is nieuw sinds 28-08-2026; de compose en het manifest inwhatsnext-evolu-relay/beschrijven nog het oude pakket met de relay van Trezor, een Postgres en een quota-manager. Dat wordt vervangen in fase 5 van het plan Umbrelapp. De drie alinea's hieronder over de app-proxy en de quota-manager gelden dus voor wat er staat, niet voor wat er komt.
De app-proxy staat op PROXY_AUTH_ADD: "false" en dat is met opzet. Trezor Suite is geen browser met
een sessiecookie. Zet het niet "voor de veiligheid" terug: dan krijgt Suite een inlogpagina in plaats van
de relay en werkt de app niet meer. De keerzijde hoort erbij en staat in de compose: wie de poort bereikt,
bereikt de relay. Voeg dus geen pagina toe achter diezelfde poort zonder daar apart over na te denken; zie
het plan Umbrelapp, OPEN.md punt 2.
De quota-manager hoort erbij en is geen restje. De relay weigert elke eigenaar zonder rij in de limietentabel, en dit is wat die rijen maakt. Haal hem er niet uit omdat hij bij Trezor bij betaalde hosting hoort.
"Gebouwd" is hier nog verder van "werkend" dan bij Electrum Gate: er is nog nooit iets van deze app op een Umbrel gedraaid. Meld dat expliciet in plaats van het te laten meelezen als werkend.
Repo-feiten
- Remote:
https://sc.kamenier-hamer.nl/sysop/UmbrelApps.git, SHA-1 en publiek. Alle drie zijn eisen en geen voorkeuren: umbreld kloont met isomorphic-git, en die spreekt alleen smart-HTTP, kan alleen SHA-1, en krijgt geen inloggegevens mee. - Store-id
whatsnextinumbrel-app-store.yml. Elk app-id moet daarmee beginnen en gelijk zijn aan de mapnaam. - Aangemaakt op 25-08-2026 zonder historie, toen Evolu Relay erbij kwam. De voorganger was de repo
ElectrumTLS; die bevatte één app en zijn naam werd onhoudbaar bij een tweede. De historie is bewust niet meegenomen. Zolang die oude repo op de Git-server staat, staat het domein van de gebruiker daar nog in; zie het plan Appstore,OPEN.mdpunt 3. - De URL is de identiteit van de store. Verandert hij, dan is het voor umbrelOS een andere store en moet de gebruiker hem opnieuw toevoegen.
Taal
Codecommentaar en documentatie zijn Nederlands. Zichtbare tekst is Engels: de pagina, umbrel-app.yml,
de meldingen die de agent naar de pagina stuurt, en de root-README.md, want dat is wat een bezoeker van
een publieke app store als eerste ziet. Die grens loopt precies langs "ziet de gebruiker dit": een reden
uit choose() belandt op het dashboard en is dus Engels, een commentaarregel erboven niet.