# Blattlauspost für CrossPoint – 0.6.0

**Stand:** 09.10.2026 · Feldtest auf X4Ente erforderlich.

## Installation

Das Archiv enthält `plugins/blattlauspost/`. ZIP im Stammverzeichnis der SD-Karte entpacken. Bereits vorhandene `plugins/blattlauspost/config.json` **nicht** überschreiben! Das Archiv liefert daher nur `config.example.json`, keine `config.json`.

CrossPoint benötigt eine Firmware mit SD-Plugins, `device.json` und `book.downloaded`-Events.

## Einmalige Einrichtung im Web-Dateimanager

1. X4Ente: File Transfer einschalten, Web-Dateimanager im vertrauten Netzwerk öffnen.
2. Auf der Webseite das Plugin **Blattlauspost · Briefe** auswählen (`mount: files`).
3. **Kontaktwort**, **gesalzenes Referenzdatum** und **vollständige Headless-Slitter-URL** eingeben (z. B. `https://SERVER/v1/unpack`).
4. **Konfiguration speichern**. Die Seite schreibt und prüft `plugins/blattlauspost/config.json` über `api.writeFile`, analog zum WebDAV-Plugin. Keine Browser-Speicherung.
5. Reader: **Einstellungen → System → Plugins → Blattlauspost**. Briefe im paginierten Katalog wählen und EPUB herunterladen.

Bestehende `config.json` wird eingelesen; zusätzliche benutzerdefinierte Felder bleiben beim Speichern erhalten. Das Salzdatum steht auf SD **im Klartext**. Zugriff nur in einem vertrauenswürdigen Netz.

## Funktionskette

- **Katalog:** `GET https://posthalter.blattlauspost.de/post/{kontaktwort}/all?page={page}&limit={limit}` (8 Einträge pro Reader-Seite, älteste zuerst).
- **Feldzuordnung:** `title=ts`, `author=r`, `id=ts`, `url=p` (hier verschlüsselte Nutzlast, **keine** URL).
- **Download:** `POST {cfg.slitter_url}` mit `ts,r,p,salzdatum`; JSON-Antwort `{"download_url":"https://…/brief.epub"}`; dann EPUB-GET und Speichern nach `/briefe/{ts}.epub`.
- **ACK:** Nach `book.downloaded` `POST https://posthalter.blattlauspost.de/post/{kontaktwort}/at/{event.title}/ack`; bei Erfolg Toast. Erfolgreiches **Ablegen**, nicht Lesen. Event-Queue ggf. verzögert; siehe Sicherheits-/Event-Grenzen.
- **Browser-Slitter:** Der frühere Slitter 0.3.2 mit Route86, SHA-256, AES-256-CTR, gzip und EPUB-3-Erzeugung bleibt im Datei-Manager unter „Alternativer Browser-Slitter“ verfügbar, einschließlich Offline-Markdown-Weg. Er benötigt JSZip aus dem CrossPoint-Dateimanager sowie `codec.js` und `pako.min.js` dieses Pakets.

**Voraussetzungen:** Posthalter muss `/all` paginiert und `/at/{ts}/ack` unterstützen; ein erreichbarer Headless-Slitter muss die oben genannte API implementieren. Das Archiv installiert diese Server nicht.

## Bibliotheksaktualisierung und Metadaten

Im Browser-Plugin gibt es **„EPUBs auf SD prüfen“**: Es liest das Verzeichnis `/briefe/`, zählt die Dateien und zeigt, soweit technisch möglich, EPUB-Titel und Autoren aus den OPF-Metadaten an (erste 12 Dateien, höchstens 2 MiB je Datei). So ist kontrollierbar, dass die EPUB-Metadaten bereits stimmen, ohne das Werk im Reader öffnen zu müssen.

**Einschränkung:** Dies aktualisiert **nur die Browser-Vorschau**, **nicht** den nativen CrossPoint-Bibliotheksindex. CrossPoint stellt derzeit keinen dokumentierten Plugin-/Web-Endpunkt für „Rebuild library index“ bereit; `sidecar` und `book.downloaded` können das nicht selbst auslösen. Auf dem Gerät ggf. **Einstellungen → System → Rebuild library index** wählen und **Use book metadata** aktivieren. Automatische native Index-Aktualisierung nach einem Geräte-Katalog-Download benötigt eine zusätzliche Firmware-Funktion. Wir täuschen keinen solchen API-Aufruf vor.

## Sicherheit und Grenzen

- Bei zentralem Headless-Slitter werden `salzdatum` und die verschlüsselte Nutzlast an einen entschlüsselnden Dienst übergeben: **keine Ende-zu-Ende-Vertraulichkeit bis zum Reader**.
- Das Legacy-AES-CTR-Profil ist **nicht authentifiziert** und nicht mit der künftigen X25519-Buchverschlüsselung gleichzusetzen.
- CrossPoint-Dokumentation warnt, dass bei Firmware-Relay/TLS der Peer nicht kryptografisch geprüft wird. TLS-Vertrauensgrenze eigenständig bewerten.
- `book.downloaded`-Events sind in bestimmten Firmwareständen nicht plugin-spezifisch gefiltert: Fremddownloads könnten unpassende ACK-Versuche auslösen. Vor produktiver Nutzung Event-Scoping beachten.
- `ts` in Sekunden kann theoretisch kollidieren; der Posthalter muss mehrdeutige `ACK-at`-Treffer zurückweisen.
- Bibliotheksindex-Rebuild wird nicht automatisch ausgeführt; auf dem Reader manuell.
- Der Browser-Slitter unterstützt weiterhin das Legacy-Verfahren, nicht X25519/`bpbox.key`.

## Enthaltene Dateien

- `device.json`: funktionierender Reader-Katalog 0.5 mit ACK und Seiten.
- `plugin.js`: frühere Browser-Slitter-Funktionen plus Einstellungsmaske und EPUB-Kontrolle.
- `manifest.json`: Plugin-Metadaten, Mount für Web-Dateimanager.
- `codec.js`: Originalcodec aus Slitter 0.3.2.
- `pako.min.js`, `PAKO-LICENSE.txt`: gzip-Bibliothek und Drittlizenz.
- `config.example.json`: Vorlage, **kein** Wirkkonfigurationsfile.
- `README.md`: diese Datei.

**Upstream:** [CrossPoint SD plugins](https://github.com/crosspoint-reader/crosspoint-reader/blob/develop/docs/sd-plugins.md), [Webserver endpoints](https://github.com/crosspoint-reader/crosspoint-reader/blob/develop/docs/webserver-endpoints.md).