Appcatalogus en downloadtokens

FAQ › Profielserver › Apps en downloads · English

Wat is het?

De appcatalogus op de profielserver vertelt EUZOS-pc's welke apps er zijn (eerst Chromium, ook Server Admin srvadmin), welke versie, en waar het ondertekende pakket staat. De pakketten zelf staan op de pakketserver download.euzos.eu, die sandbox en productie delen. Alleen een pc die een downloadtoken van een profielserver heeft gekregen, mag downloaden, en alleen een ingelogde pc krijgt er een. De beveiliging zit in de handtekening van het pakket, niet in de server of de URL: een server of CDN die liegt, kan een installatie laten mislukken, maar de pc nooit iets anders laten installeren dan een ondertekend pakket van die app.

Hoe doe ik…?

Hoe vindt en installeert een pc een app?

GET /api/apps/<naam> (openbaar, zonder token): beschikbaar + naam, versie, grootte, SHA-256, URL's van de beschrijving en van het pakket; of niet_beschikbaar. Als de server tokens uitgeeft, volgt een regel downloadbasis=https://download.euzos.eu/.
POST /api/apps/token?token=<pc-token> met app= en versie= → een downloadtoken (2 uur).
GET https://download.euzos.eu/<app>/<versie>/<BESTAND> met Authorization: Bearer <token>; met Range gaat een onderbroken download verder.
De pc controleert de beschrijving met SIGNPUB.TXT, de versie tegen HAAL.TXT, dat de beschrijving precies klopt met de catalogus, en de SHA-256 en de blokhash van het pakket.

Op de pc: apps catalog chromium toont wat de server zegt; apps install chromium installeert via de catalogus.

Hoe zet ik een app in de catalogus?

Op de profielserver (alleen via de CLI; er is geen API om de catalogus te wijzigen, en elke wijziging komt in het beheerlogboek):

euzos-profielserver --config <conf> app-set chromium --version <n> --size <bytes> \
    --sha256 <hex> --url https://download.euzos.eu/chromium/<n>/CHROMIUM.APP \
    [--url <spiegel>/CHROMIUM.APP] [--package https://<…>/CHROMIUM.PAK]

tools/chromium/install.sh --create bouwt en ondertekent het pakket en toont deze opdracht met versie, grootte en SHA-256 al ingevuld. app-set controleert elk veld zoals de pc dat doet en waarschuwt bij een lagere versie. De beheerpagina kan hetzelfde (Appcatalogus).

Hoe publiceer ik een pakket op download.euzos.eu?

Vanaf de Mac: server/download/deploy/publiceer.sh <map>/<NAAM>.APP. Het neemt <NAAM>.APP, .sig en het pakket uit pakket=, leest de versie uit de .sig, controleert grootte en SHA-256, uploadt naar /srv/euzos-pakketten/<app>/<versie>/ (overschrijft nooit een bestaande versie) en toont de opdracht app-set.

Hoe haal ik een app weg?

app-delete <naam>; pc's horen dan niet_beschikbaar.

Hoe krijg ik met de hand een downloadtoken (voor tests)?

download-token <app> <versie> op de profielserver: een token van 2 uur voor het account "beheer", vastgelegd in het beheerlogboek.

Hoe trek ik een downloadtoken in?

Op de pakketserver: sudo euzos-download revoke <jti> [opmerking] (zet de jti op de zwarte lijst; oude naam intrek). De pagina Downloadtokens van de beheerpagina legt het verzoek vast en toont deze opdracht. Een token leeft sowieso hoogstens 2 uur.

Hoe voeg ik de sleutel van een nieuwe omgeving (bv. PROD) toe aan de pakketserver?

Op de profiel-VPS: download-key-create (weigert als het bestand al bestaat) en noteer de getoonde regel <kid> <publieke sleutel>; zet die in de sleutellijst van de pakketserver (/etc/euzos-download/sleutels.txt). Die regel weghalen maakt alle tokens van die kid in één keer ongeldig.

Waarom krijgt mijn pc 401 van de pakketserver?

Geen token, een verkeerde handtekening of een verlopen token (geen_token, handtekening, verlopen). 403 betekent ingetrokken (ingetrokken) of een token voor een andere app of versie (ander_pad); 404 een pad dat niet aan het patroon voldoet (pad). Een oudere pc die downloadbasis= overslaat, stuurt geen token en krijgt 401.

Details

Velden van de catalogus: versie is de versie in de handtekening (de eerste 8 bytes van <NAAM>.APP.sig); grootte en sha256 beschrijven het pakket; beschrijving is de URL van de ondertekende beschrijving (eindigt op /<NAAM>.APP); pakket de URL van het pakket (leeg: naast de beschrijving). Van elk hoogstens 4 URL's: de eerste eerst, de rest zijn spiegels. Alleen https://, hoogstens 512 tekens. App-namen: a-z, 0-9, -, hoogstens 8 tekens (apps::valid_name). Afgeremd op 30 verzoeken per minuut per netwerk.

Werkplekserver: vraagt een pc de catalogus op vanuit het netwerk van een aangemelde werkplekserver, dan volgen nog twee regels: werkplek=https://<lan-adres>:8445/ en werkplek-tls=<SHA-256 van zijn SPKI>. De pc probeert dan eerst de werkplekserver (dezelfde paden, vastgepinde TLS-sleutel, hetzelfde token) en valt bij elke fout terug op de URL's van de catalogus.

Downloadtoken (ezdl1.<kid>.<app>.<versie>.<exp>.<jti>.<account>.<sig>): kid = sbx-/prod-/lok- + 8 hex van de publieke sleutel; exp Unix-tijd (2 uur, download_token::DURATION); jti 32 willekeurige hex; account een SHA-256 met sleutel van het account-id (niet terug te rekenen); sig Ed25519 over EUZOS-downloadtoken-v1\0 + alles vóór de laatste punt. Alleen de huidige versie in de catalogus krijgt een token, nooit een oudere. Limieten: 20 per account per uur (PER_ACCOUNT), 60 per netwerk per uur (PER_NET).

Downloadsleutel: een Ed25519-sleutel per omgeving, alleen op de profiel-VPS (download_key_file, rechten 0600/0640, nooit in git). Zonder die sleutel geeft /api/apps/token 404.

Server Admin: de app srvadmin krijgt alleen een downloadtoken voor een account met beheerrechten (de rol serverbeheerder of beheerder van een organisatie; workplace_admin::may_server_admin).

De pakketserver (server/download, programma euzos-download) staat achter Caddy (forward_auth) op localhost en laat een verzoek alleen door als: de methode GET/HEAD is en het pad /<app>/<versie>/<bestand>; de kid van het token bekend is en de handtekening klopt; exp niet voorbij is en hoogstens 2 uur + 5 min vooruit ligt; de jti niet op de zwarte lijst staat; app en versie gelijk zijn aan het pad. Sleutellijst en zwarte lijst worden binnen een seconde na een wijziging opnieuw gelezen. Het journal legt IP, uitkomst, jti, accounthash, kid, pad en Range vast, nooit het token.

Naslag

CLI-opdrachten

Profielserver (euzos-profielserver):

Opdracht	Argumenten	Wat het doet
`apps`	—	de catalogus (zoals `GET /api/apps`)
`app-set`	`<naam> --version <n> --size <bytes> --sha256 <hex> --url <https://…/NAAM.APP> [--url <spiegel>]… [--package <https://…>]…`	een app toevoegen of vervangen
`app-delete`	`<naam>`	een app weghalen
`download-key-create`	—	de downloadsleutel van deze omgeving maken; toont de regel voor de sleutellijst
`download-key`	—	`kid` en publieke sleutel tonen
`download-token`	`<app> <versie>`	een token voor beheerwerk en tests

Oude namen: app-zet, app-wis, downloadsleutel-maak, downloadsleutel, downloadtoken; vlaggen --versie, --grootte, --pakket.

Pakketserver (euzos-download):

Opdracht	Argumenten	Wat het doet
`start`	`[--address <ip:poort>] [--keys <bestand>] [--blocklist <bestand>]`	de tokencontrole draaien (standaard `127.0.0.1:8091`)
`revoke`	`<jti> [opmerking]`	een token op de zwarte lijst zetten (oud `intrek`)
`keys`	—	de bekende sleutel-id's (`kid`) tonen (oud `sleutels`)

Oude vlaggen: --adres, --sleutels, --zwarte-lijst.

Functies en modules

Functie / module	Rol
`euzos_profileserver::apps::list`, `one`, `valid_name`	`GET /api/apps`, `GET /api/apps/<naam>`
`euzos_profileserver::download_token::fetch`	`POST /api/apps/token`
`euzos_profileserver::download_token::Key` (`create`, `read`, `kid`, `key_line`, `account_hash`, `token`)	de downloadsleutel en het maken van tokens
`euzos_profileserver::workplace::download_token`	tokens voor een werkplekserver (`eze_`-token)
`server/download` (`euzos-download`)	de tokencontrole achter Caddy
Kernel: `kernel/src/app_store.rs` (`catalog`, `install_catalog`, `Access`), `kernel/src/app_install.rs`; `euzos_install::apps::read_catalog`	de kant van de pc

Configuratiebestanden

Configuratie van de profielserver:

Sleutel	Betekenis
`download_key_file` (oud `download_sleutel_bestand`)	de Ed25519-downloadsleutel; zonder staan tokens uit
`download_base` (oud `download_basis`)	`https://download.euzos.eu/`; alleen samen met `download_key_file`; geeft de regel `downloadbasis=`

Pakketserver: /etc/euzos-download/sleutels.txt (per regel <kid> <publieke sleutel hex>, de sleutels van SBX en PROD; geen geheimen) en /etc/euzos-download/zwarte-lijst.txt (ingetrokken jti's). Bestanden op schijf: /srv/euzos-pakketten/<app>/<versie>/<BESTAND>.

Op de pc: \EOS\FW\HAAL.TXT (laatst geïnstalleerde versies, de ondergrens) en \EOS\FW\SIGNPUB.TXT (de publieke ondertekensleutel).

Configuratiesleutels op schijf en getypte bevestigingswoorden zijn sinds 27-10-2026 Engels (bijvoorbeeld WIS-… → WIPE-…, omgeving= → environment=; docs/ENGLISH.md); de Nederlandse namen blijven geaccepteerd. De draadformaten van de profielserver (pc-regelprotocol, ondertekend profiel, ondertekende telefoonberichten, instellingssleutels) blijven Nederlands.

API-eindpunten

Methode	Pad	Oud Nederlands pad	Doel
GET	`/api/apps`	—	de hele catalogus (openbaar)
GET	`/api/apps/<naam>`	—	één app (openbaar)
POST	`/api/apps/token?token=<pc-token>`	—	een downloadtoken
POST	`/api/workplace/v1/download-token?token=eze_…`	`/api/werkplek/v1/downloadtoken`	een downloadtoken voor een werkplekserver
GET, HEAD	`https://download.euzos.eu/<app>/<versie>/<BESTAND>`	—	de pakketserver (Bearer-token)

Protocolberichten en formaten

GET /api/apps/chromium
beschikbaar                      (of: niet_beschikbaar + naam=…)
naam=chromium
versie=<n>
grootte=<bytes>
sha256=<64 hex>
beschrijving=https://…/CHROMIUM.APP      (1 tot 4)
pakket=https://…/CHROMIUM.PAK            (0 tot 4)
downloadbasis=https://download.euzos.eu/ (als tokens aan staan)
werkplek=https://<lan>:8445/             (vanuit een werkplek-netwerk)
werkplek-tls=<64 hex>

POST /api/apps/token?token=<pc-token>
app=chromium
versie=<n>
→ ok / token=ezdl1.… / verloopt=<Unix-tijd> / duur=7200
→ 400 reden=ongeldig | 401 reden=token | 404 reden=onbekend | 404 (tokens uit)
  | 429 reden=te_vaak + wacht= | 503

Antwoorden van de pakketserver: 200/206 (bestand), 401 geen_token|handtekening|verlopen (met WWW-Authenticate: Bearer), 403 ingetrokken|ander_pad, 404 pad.

Zie ook

docs/PROFILE-PROTOCOL.md, "The app catalog", "Download tokens"
docs/DOWNLOADSERVER.md
docs/APPS.md
Organisaties (werkplekservers) · Omgevingen en uitrol · CLI