Initial commit
This commit is contained in:
236
README.md
236
README.md
@@ -1,3 +1,235 @@
|
||||
# thunderbird-paperless-connector
|
||||
# Paperless-ngx für Thunderbird / Betterbird
|
||||
|
||||
Addon für Thuderbird oder Betterbird zur Anbindung von Paperless-NGX
|
||||
Legt Anhänge und ganze E-Mails in einem Paperless-ngx-Archiv ab und fügt
|
||||
Dokumente aus dem Archiv als Anhang oder Freigabelink in Entwürfe ein.
|
||||
|
||||
Schwestererweiterung zur LibreOffice-Fassung; dieselben Erkenntnisse zur
|
||||
Paperless-Schnittstelle, aber vollständig eigener Code — Thunderbird kennt
|
||||
WebExtensions, LibreOffice UNO.
|
||||
|
||||
---
|
||||
|
||||
## Funktionen
|
||||
|
||||
| Ort | Befehl | Wirkung |
|
||||
|---|---|---|
|
||||
| Kontextmenü am Anhang | Anhang in Paperless ablegen | ausgewählte Anhänge als Dokument |
|
||||
| Kontextmenü in der Nachrichtenliste | E-Mail in Paperless ablegen | vollständige Nachricht als `.eml` |
|
||||
| Schaltfläche im Nachrichtenfenster | dasselbe für die angezeigte Nachricht | |
|
||||
| Schaltfläche im Verfassenfenster | Aus Paperless einfügen | als Anhang oder als Freigabelink |
|
||||
|
||||
Beim Ablegen stehen dieselben zwei Ziele zur Wahl wie in der
|
||||
LibreOffice-Fassung: ein **neues Dokument** oder eine **neue Version eines
|
||||
bestehenden**. Der zweite Fall deckt die Lücke, die Dokumentenverwaltungen
|
||||
gern offenlassen:
|
||||
|
||||
> Die Rechnung kommt als PDF im Anhang. Später entsteht die bearbeitbare
|
||||
> Fassung. Beides gehört zusammen — aber das PDF war zuerst da.
|
||||
|
||||
---
|
||||
|
||||
## Was beim Ablegen passiert
|
||||
|
||||
**Anhänge einzeln wählbar.** Kleine Bilder und Signaturen sind vorab
|
||||
abgewählt — sie gehören zur Darstellung der Nachricht, nicht zum Inhalt.
|
||||
Wer sie alle mit archiviert, hat nach einem Jahr hunderte Logos im Bestand.
|
||||
Die Schwelle liegt bei 8 KB und ist einstellbar.
|
||||
|
||||
**Die ganze Nachricht als `.eml`.** Anhänge bleiben darin enthalten;
|
||||
Paperless legt sie nicht als eigene Dokumente an, aber die Datei ist
|
||||
vollständig und lässt sich jederzeit wieder in einem Mailprogramm öffnen.
|
||||
|
||||
**Titel aus dem Betreff.** Präfixe wie `AW:` oder `Fwd:` werden entfernt —
|
||||
sie tragen im Archiv nichts bei und stören beim Sortieren.
|
||||
|
||||
**Klassifizierung direkt danach.** Sonst trägt ein neues Dokument nur den
|
||||
Titel, und nachträglich macht man es erfahrungsgemäß nicht mehr.
|
||||
|
||||
---
|
||||
|
||||
## Einfügen in Entwürfe
|
||||
|
||||
**Als Anhang.** Das Original wird geladen (`?original=true`), nicht die
|
||||
Archivfassung — bei ZUGFeRD bleibt damit die eingebettete XML erhalten.
|
||||
Die Version ist wählbar, mit Datum und Format.
|
||||
|
||||
**Als Freigabelink.** Zeitlich begrenzt, ohne Anmeldung abrufbar, auf
|
||||
Wunsch mit einem Tag am Dokument. Eingefügt werden Name (fett), Adresse
|
||||
und Gültigkeit:
|
||||
|
||||
```
|
||||
Einladung Generalversammlung
|
||||
https://dms.example.org/share/ZYGwdw…
|
||||
Link gültig bis 11.09.2026
|
||||
```
|
||||
|
||||
Die Adresse steht sichtbar, nicht nur als Verweisziel — bei einem Link,
|
||||
der ohne Anmeldung Zugriff gewährt, sollte der Empfänger sehen, wohin er
|
||||
führt.
|
||||
|
||||
**Der Tag ist abschaltbar.** Ein leeres Tag-Feld bedeutet: keine
|
||||
Kennzeichnung setzen. Wer es dauerhaft nicht will, leert das Feld in den
|
||||
Einstellungen.
|
||||
|
||||
> **Einschränkung:** Die Compose-Schnittstelle kennt kein Einfügen an der
|
||||
> Schreibmarke. Der Nachrichtentext muss vollständig gelesen und
|
||||
> zurückgeschrieben werden. Der Link landet deshalb am Ende des Textes,
|
||||
> nicht an der Cursorposition. Bei HTML-Nachrichten wird er vor dem
|
||||
> schließenden `</body>` eingesetzt.
|
||||
|
||||
Wann was: Der Anhang für alles, was auch in fünf Jahren noch lesbar sein
|
||||
muss, wenn der Link längst abgelaufen ist. Der Link für große Dateien und
|
||||
für Empfänger, die ohnehin Zugriff auf das Archiv haben sollen.
|
||||
|
||||
---
|
||||
|
||||
## Einrichten
|
||||
|
||||
1. Add-ons-Verwaltung → **Paperless-ngx** → Einstellungen
|
||||
2. Basisadresse eintragen, etwa `https://dms.example.org` — ohne
|
||||
abschließenden Schrägstrich
|
||||
3. API-Token eintragen, erzeugt im **Benutzerprofil** von Paperless
|
||||
4. Speichern — dabei wird das Zugriffsrecht für genau diese Adresse
|
||||
erbeten und die Verbindung sofort geprüft
|
||||
|
||||
Das Zugriffsrecht steht bewusst **nicht** pauschal im Manifest. Eine
|
||||
Erweiterung, die von Haus aus jede Adresse erreichen darf, ist eine
|
||||
unnötig große Angriffsfläche.
|
||||
|
||||
---
|
||||
|
||||
## Bauen und installieren
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
```
|
||||
|
||||
Zum Ausprobieren ohne Installation:
|
||||
|
||||
```
|
||||
Extras → Entwicklerwerkzeuge → Debuggen von Add-ons
|
||||
→ Temporäres Add-on laden → manifest.json wählen
|
||||
```
|
||||
|
||||
Das ist beim Entwickeln der bessere Weg: Änderungen sind nach einem Klick
|
||||
auf „Neu laden" wirksam, und die Konsole zeigt Fehler im Klartext.
|
||||
|
||||
Dauerhaft:
|
||||
|
||||
```
|
||||
Add-ons-Verwaltung → Zahnrad → Add-on aus Datei installieren
|
||||
→ paperless-thunderbird-1.0.0.xpi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bekannte Einschränkung: Zugriff über IP-Adresse
|
||||
|
||||
Der Zugang über `https://` und einen Rechnernamen funktioniert. Der
|
||||
direkte Weg über eine LAN-Adresse wie `http://192.168.1.5:8000` schlägt
|
||||
dagegen mit `NetworkError` fehl, auch wenn das Zugriffsrecht erteilt
|
||||
wurde.
|
||||
|
||||
**Die Ursache ist nicht abschließend geklärt.** Eine Vermutung: Neuere
|
||||
Gecko-Versionen schränken Anfragen aus erweiterten Kontexten in private
|
||||
Adressbereiche ein. Falls das zutrifft, lässt es sich von der Erweiterung
|
||||
aus nicht umgehen.
|
||||
|
||||
Praktisch ist das verschmerzbar — der Weg über den Reverse Proxy ist
|
||||
ohnehin der bessere, weil er verschlüsselt ist. Wer es untersuchen möchte,
|
||||
findet in `about:networking` und in der Netzwerkanalyse der
|
||||
Add-on-Debugansicht Ansatzpunkte.
|
||||
|
||||
## Manifest-Version
|
||||
|
||||
Gebaut nach **Manifest V3** mit den Thunderbird-Besonderheiten:
|
||||
|
||||
- `background.scripts` als Ereignisseite, **kein** Service Worker —
|
||||
Thunderbird unterstützt keine
|
||||
- `compose_action` und `message_display_action` neben `action`
|
||||
- `optional_host_permissions` statt fester Adressen
|
||||
|
||||
Sollte die eingesetzte Version noch MV2 verlangen, sind vier Änderungen
|
||||
nötig: `manifest_version` auf 2, `optional_host_permissions` nach
|
||||
`optional_permissions`, `host_permissions` entfällt, und
|
||||
`background.type: module` bleibt wie es ist.
|
||||
|
||||
---
|
||||
|
||||
## Sprachen
|
||||
|
||||
Deutsch, Englisch und Französisch über die eingebaute Verwaltung
|
||||
(`_locales/`). Die Sprache richtet sich nach der Oberfläche von
|
||||
Thunderbird. Eine weitere Sprache ergänzt man, indem man ein Verzeichnis
|
||||
mit `messages.json` anlegt — die Schlüssel stehen in
|
||||
`_locales/de/messages.json`.
|
||||
|
||||
---
|
||||
|
||||
## Sicherheit
|
||||
|
||||
Ausführlich in [SICHERHEIT.md](SICHERHEIT.md). Die Lage ist entspannter als
|
||||
bei der LibreOffice-Fassung, weil hier **keine fremden Dokumente geöffnet**
|
||||
werden — der heikelste Punkt entfällt. Die wichtigsten Maßnahmen:
|
||||
|
||||
- Zugriffsrecht nur für die eingetragene Adresse, zur Laufzeit erbeten
|
||||
- Nur die fünf tatsächlich benötigten Berechtigungen — `compose.send` war
|
||||
im ersten Entwurf enthalten, ohne je benutzt zu werden, und ist entfernt
|
||||
- Nur `http` und `https` als Basisadresse
|
||||
- Dateinamen aus Anhängen werden bereinigt — sie stammen vom Absender
|
||||
- Anhangdaten werden erst beim Hochladen geladen, nicht beim Öffnen des
|
||||
Dialogs
|
||||
- Freigabelinks und Dokumentnamen werden beim Einfügen HTML-maskiert
|
||||
- Aufträge zwischen Dialog und Ereignisseite werden nach 30 Minuten
|
||||
verworfen
|
||||
|
||||
---
|
||||
|
||||
## Aufbau
|
||||
|
||||
```
|
||||
manifest.json
|
||||
background.js Menüs, Schaltflächen, Vermittlung
|
||||
lib/
|
||||
client.js REST-Client (fetch, FormData)
|
||||
settings.js Einstellungen, Dateinamen, Hilfsmittel
|
||||
ui/
|
||||
store.html/.js Ablegen: Anhänge oder ganze Nachricht
|
||||
classify.html/.js Klassifizierung direkt danach
|
||||
insert.html/.js Einfügen als Anhang oder Link
|
||||
options.html/.js Verbindung einrichten
|
||||
gemeinsam.js/.css geteilte Hilfsmittel
|
||||
_locales/{de,en,fr}/
|
||||
icons/
|
||||
```
|
||||
|
||||
Die Dialoge sprechen **nicht** selbst mit Paperless, sondern lassen die
|
||||
Ereignisseite arbeiten. Dort hängt die zur Laufzeit erteilte Berechtigung;
|
||||
ein Dialogfenster müsste sie sonst erneut erbitten.
|
||||
|
||||
---
|
||||
|
||||
## Vor einer Veröffentlichung
|
||||
|
||||
| Datei | Was |
|
||||
|---|---|
|
||||
| `manifest.json` | `browser_specific_settings.gecko.id`, `author`, `homepage_url` |
|
||||
| `LICENSE` | Rechteinhaber |
|
||||
|
||||
Die Kennung sollte einer Domain folgen, die dir gehört. Aktuell steht dort
|
||||
`paperless@example.org`.
|
||||
|
||||
---
|
||||
|
||||
## Lizenz
|
||||
|
||||
MIT, siehe [LICENSE](LICENSE).
|
||||
|
||||
## Haftung
|
||||
|
||||
Die Erweiterung schreibt in ein Dokumentenarchiv. Sie wurde gegen eine
|
||||
Paperless-Instanz entwickelt, aber nicht formal getestet. Die MIT-Lizenz
|
||||
schließt jede Gewährleistung aus.
|
||||
|
||||
Vor dem ersten produktiven Einsatz: eine Testnachricht ablegen und in
|
||||
Paperless nachsehen, ob Titel, Datum und Anhänge stimmen.
|
||||
|
||||
Reference in New Issue
Block a user