UmbrelApps/CLAUDE.md

# 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. Sinds 0.1.0 met een eigen image en dus een bouwstap: zie **Electrum Gate** hieronder |
| **Evolu Relay** | `whatsnext-evolu-relay/` | draait op de Umbrel sinds 28-08-2026 en wordt gebruikt. Let op de bouwstap: zie **Evolu Relay** hieronder |

**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](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 (daar is `$$` te ontsnappen), of in een
eigen image, waar geen envsubst aan te pas komt. Beide apps doen sinds september 2026 het tweede; er
staat geen `*.template` meer in deze repo, maar de regel blijft gelden voor wie er een bij zet.

**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, in een `*.template` of in een eigen
image, en nooit in een los bestand of in een submap van de app-map.

**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 `tools/electrum-gate/` en 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 tests van Evolu Relay hieronder bij "de suite" en draaien voor een commit; de uitvoer
eindigt bij elk met een regel "N goed, M fout". Er is geen watch-modus; de suite kost minder dan een
seconde. Noem hier geen aantal: dat klopte tot 30-08-2026 al niet meer.

Er is ook een test over de **pagina's** van beide apps, en die is geen Python:

```
node tests/test_paginas_parsen.mjs
```

Hij toetst dat de JavaScript in elke statuspagina parseert. Een pagina kan op twee plekken staan: als
`index.html.template` in de app-map (dan toetst hij ook dat het script heel blijft ná de invulling door
umbreld) of als `index.html` in `tools/<app>/` (dan toetst hij dat er geen accolade-variabele meer in
staat). Sinds september 2026 staan beide pagina's op de tweede plek. Dat is de enige klasse paginafouten
die niet op het apparaat gevonden hoeft te worden; alles wat de pagina *toont* blijft handwerk in een
browser.

**Wil je een pagina bekijken, gebruik `tools/voorbeeldpagina.mjs`.** Een statuspagina is niet zomaar te
openen: de gegevens komen van een agent die alleen in de app bestaat, en in een `*.template` staan
bovendien accolade-variabelen. Dat script vindt de pagina op een van de twee plekken, vult in wat er in te
vullen is en zet het resultaat in `voorbeeld/` (gitignored). Geen bewijs, wel het gereedschap dat op
30-08-2026 twee echte opmaakfouten vond voordat ze uitgerold waren.

`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 volledig, en een suite die altijd rood staat wordt niet gelezen. Hij
drukt de pinstatus wel af. Wat hij wél toetst: dat de tag van een eigen image gelijk is aan `VERSION` in
het bijbehorende `tools/<app>/build.sh`.

Twee dingen om te weten voordat je een groene uitslag vertrouwt:

- **sommige toetsen slaan zichzelf over en melden dat.** De vergelijking met `ssl` heeft de
  certificaatwinkel van het besturingssysteem nodig, en de subjectAltName-toets heeft netwerk nodig. Staat
  er `OVERGESLAGEN` in 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` is handwerk in een browser.

### Architectuurregels

**De app-code zit in een eigen image, gebouwd uit `tools/electrum-gate/`** (sinds 0.1.0, 07-09-2026). De
agent, de nginx-configuratie, het stream-blok, de pagina en het startscript staan daar; in de app-map
staan alleen nog de compose, het manifest, het icoon en `data/`. Eén image voor beide containers: de
compose start hem als `server` met het standaardcommando en als `agent` met `python3 /app/agent.py`.
Gevolg dat je moet kennen voordat je iets belooft: **een wijziging in `tools/electrum-gate/` is pas
uitgerold als de image gebouwd, geduwd en met zijn digest in de compose gezet is**, en dat kan alleen de
gebruiker, op de Umbrel. Verhoog je `VERSION` in `build.sh`, dan verhoog je ook `version` in het manifest
en de tag in de compose (twee keer); `test_appstore_vorm.py` houdt tag en `VERSION` gelijk.

**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` maar
in `stream.conf`, en `entrypoint.sh` 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.

**Het backend-adres komt uit de omgeving, in beide containers.** nginx kan in een `proxy_pass` van het
stream-blok geen omgevingsvariabele lezen, dus `stream.conf` heeft twee plaatshouders zonder dollarteken
die `entrypoint.sh` bij het starten invult. De pagina haalt de versie en het adres uit `status.json`; tot
0.0.29 vulde umbreld die rechtstreeks in de pagina in.

**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`; image `sc.kamenier-hamer.nl/sysop/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
```

```
python tests/test_relay_agent.py
```

De eerste 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. 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. Twee toetsen erin bewaken dat de leerstand niet terugsluipt: een onbekende eigenaar wordt
geweigerd ook met `learning: true` in het bestand, en `set-learning` is een onbekende actie.

De tweede toetst de agent: de labels. Dat is het enige dat hij zélf uitrekent in plaats van doorgeeft, en
daarmee de enige plek in dat bestand waar hij eigen logica heeft. De HTTP-laag zit er niet in: die handlers
zijn zonder socket niet aan te roepen.

### 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 poorten staan omgekeerd ten opzichte van wat je verwacht, en dat is de kern van de compose.** De
**pagina** hangt achter `app_proxy` mét de inlog van umbrelOS; de **relay** publiceert zijn eigen
host-poort 3852. Tot 0.0.2 stond het andersom en moest `PROXY_AUTH_ADD` op `"false"`, want een sync-cliënt
is geen browser met een sessiecookie en zou een inlogpagina krijgen in plaats van de relay. Daardoor was
een statuspagina op diezelfde poort net zo onbeschermd als de relay zelf. Zet het niet terug zonder het plan
**Umbrelapp**, `PLAN.md` §4h te lezen.

**Eén schrijver per bestand onder `data/relay/`, en dat is geen stijlkwestie.** Twee processen die in
dezelfde allowlist schrijven is een wedloop die je een keer per jaar treft en dan niet kunt reproduceren.
De verdeling:

| Bestand | Schrijver | Waarom daar |
|-|-|-|
| `owners.json` | het relay-proces | daar staat wie er binnen mag, en dat beslist het proces dat de verbindingen aanneemt |
| `command.json` | de agent | de postbus. De agent legt erin, het relay-proces past toe en ruimt op |
| `labels.json` | de agent | een label zegt niets over toegang, dus de relay hoeft het niet te weten. Dat het hier staat en niet in `owners.json` is wat labelen meteen laat werken, ook als de relay omgevallen is |

**Er is één weg naar binnen: de wachtlijst.** Een onbekende eigenaar wordt geweigerd en onthouden; op de
statuspagina laat je hem toe. De getimede leerstand die daarnaast bestond is er in 0.7.0 (09-09-2026) uit,
op voorstel van de gebruiker: allebei de wegen vragen iemand die bij de app kan, dus het was dubbelop, en
het venster was de zwakste omdat het iederéén toeliet die er toevallig in verbond. Zet hem niet terug zonder
het plan **Umbrelapp** te lezen.

De velden `learning` en `learningUntil` worden nog wél gelézen en dan genegeerd. Dat is geen slordigheid:
`STATE_VERSION` verhogen zou `normalizeState` een bestaand `owners.json` laten afwijzen, en dan schuift
`store.js` de allowlist van een werkende installatie opzij en gaat de deur dicht voor eigenaars die er al in
stonden. Het veld op schijf heet nog `rejected`; op de pagina heet het de wachtlijst.

**Het beleid is de enige plek waar staat wie er binnen mag, en `isOwnerAllowed` wordt alleen bij de
WebSocket-upgrade gesteld.** Gevolg om te kennen voordat je iets belooft op de pagina: **blokkeren werkt pas
bij de volgende verbinding.** Zie `Docs/Referenties/Upstream-evolu-relay.md` §10 en het plan **Umbrelapp**,
`OPEN.md` punt 10.

**Zet geen ontcijfering in deze app.** Het kan technisch, maar niet met een xpub: er is de SLIP-21-node van
het apparaat voor nodig, en die geeft volledige zeggenschap over de gegevens. De hele grond waarop je een
relay ergens kunt neerzetten is dat hij de sleutel niet heeft, en het manifest belooft dat letterlijk.
Onderhoudsfuncties die de inhoud kennen horen in de tool in `HomeGit/Trezor`. Zie §11 van hetzelfde
naslagdocument en `OPEN.md` punt 11.

**Alles zit in één image, sinds 0.6.0 (08-09-2026): de relay, de agent en de pagina.** `tools/evolu-relay/`
heeft naast `src/` ook `agent.py`, `nginx.conf` en `index.html`; in de app-map staan alleen nog compose,
manifest, icoon en `data/`. Basis is `node:24-slim` (om `better-sqlite3`, dat geen musl-binaries heeft)
met nginx en python3 uit apt. Twee gevolgen die je moet kennen: nginx draait als `www-data`, want Debian
heeft geen gebruiker `nginx`; en de image heeft geen `USER`, dus de compose zet `user: node` op de
relay-service en de andere twee draaien als root. De versie in de kop van de pagina komt uit `api/status`
via `RELAY_APP_VERSION`. Verhoog je `VERSION` in `build.sh`, dan ook het manifest en de tag in de compose,
**drie keer**.

**Deze app draait en wordt gebruikt sinds 28-08-2026**, maar dat geldt niet voor elke wijziging: er zit een
bouwstap tussen de repo en het apparaat. Een wijziging in `tools/evolu-relay/` is pas uitgerold als de
image gebouwd, geduwd en met zijn digest in de compose gezet is, en dat kan alleen de gebruiker. Meld dus
per wijziging wat er wél geverifieerd is; "de app werkt" is geen uitspraak over de code van vandaag.

## 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 `whatsnext`** in `umbrel-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.md` punt 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.