# Paperless-ngx für Thunderbird / Betterbird

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.