nextcloud/,

# Bad-Signature-Toolkit

Werkzeuge zum Aufspüren und Beheben von **"Bad Signature"-Fehlern** der
Nextcloud Server-Side-Encryption (Dateien, die sich wegen einer
fehlerhaften Verschlüsselungs-Signatur nicht mehr öffnen lassen).

Alle Scripte laufen als **root** auf dem jeweiligen Nextcloud-Server und
fragen die Website interaktiv ab, falls `-s <website>` nicht angegeben
wird (Voraussetzung: eine passende `.conf`-Datei liegt im `conf/`-
Verzeichnis neben den Scripten).

## Der Ablauf auf einen Blick

```
1. scan_bad_signature.sh      Betroffene Dateien FINDEN          (read-only)
2. recover_bad_signature.sh   Dateien probeweise ENTSCHLÜSSELN    (read-only,
                               schreibt nur außerhalb von Nextcloud)
3. restore_bad_signature.sh   Geprüfte Dateien ZURÜCKSCHREIBEN    (live-Schreibzugriff)
4. recreate_bad_signature.sh  Fallback für die Fälle, die (3)     (live-Schreibzugriff,
                               nicht reparieren kann                bricht Freigaben!)
   delete_files.sh            Explizite Dateiliste LÖSCHEN        (live-Schreibzugriff,
                               (unabhängig vom obigen Ablauf)        -> Papierkorb)
```

Jeder Schritt liest den Report des vorherigen Schritts. Reports landen
alle unter `reports/` (Dateiname verrät den Schritt: `bad_signature_…`,
`recovery_…`, `restore_…`, `recreate_…`, `delete_…`).

---

## 1. `scan_bad_signature.sh` – Betroffene Dateien finden

Liest einmal jede verschlüsselte Datei eines/mehrerer/aller Accounts und
protokolliert, welche dabei mit einem Signaturfehler scheitert. **Rein
lesend** – verändert, verschiebt oder löscht nichts.

```bash
./scan_bad_signature.sh -s <website>
```

→ Ergebnis: `reports/bad_signature_<website>_<datum>.tsv`

---

## 2. `recover_bad_signature.sh` – Versuchsweise entschlüsseln

Schaltet die Signaturprüfung *instanzweit, nur für die Laufzeit des
Scripts* ab (`encryption_skip_signature_check`) und versucht, die
betroffenen Dateien trotzdem zu entschlüsseln. Funktioniert nur, wenn
die Signaturprüfung selbst das Problem ist – nicht bei tatsächlich
beschädigtem Chiffretext. Jede gewonnene Datei wird automatisch geprüft
(Dateityp-Signatur, PDF-/ZIP-Integrität, Plausibilität der Dateigröße
o. Ä.) und als `VALID`, `UNVERIFIED` ("Nicht prüfbar") oder `INVALID`
("Datenmüll") eingestuft.

**Wichtig:** Original-Dateien in Nextcloud werden nie angefasst. Alles
landet in einem separaten Verzeichnis außerhalb von Nextclouds eigener
Ablage (`/var/nc-recovery/<website>/…`) – dort liegen danach
**unverschlüsselte** Daten, also nach Gebrauch aufräumen.

```bash
./recover_bad_signature.sh -s <website>

# Nur erneut validieren (z. B. nach einem Script-Update mit neuen
# Prüfregeln), ohne nochmal zu entschlüsseln:
./recover_bad_signature.sh -V -s <website>
```

→ Ergebnis: `reports/recovery_<website>_<datum>.tsv`

---

## 3. `restore_bad_signature.sh` – Zurückschreiben (Regelfall)

Schreibt die in Schritt 2 gewonnenen Dateien über die **normale
Nextcloud-Files-API** an ihren ursprünglichen Pfad zurück – der einzige
Weg, der Datei-ID und bestehende Freigaben erhält. Danach ist die Datei
wieder ganz normal verschlüsselt, mit frischer, korrekter Signatur.

**Seit dem letzten Update werden standardmäßig zwei Kategorien
zurückgeschrieben**, klar unterscheidbar im Report (Spalte `origin`):

| validation im Recovery-Report | Bedeutung | wird restauriert |
|---|---|---|
| `VALID` | dedizierte Strukturprüfung hat den Inhalt bestätigt | ja |
| `UNVERIFIED`, Größe plausibel | kein dedizierter Check, aber nichts sieht falsch aus | ja |
| `UNVERIFIED`, Größe "LOOKS OFF" | Größenverhältnis auffällig – echtes Warnsignal | **nein** |
| `INVALID` ("Datenmüll") | Strukturprüfung fehlgeschlagen | **nein** |

```bash
./restore_bad_signature.sh -s <website>
# nur Dry-Run (nichts wird geschrieben):
./restore_bad_signature.sh -n -s <website>
```

Fragt danach interaktiv: welcher Recovery-Report, welche(r) Account(s).

**Sicherheit:** Neuvalidierung direkt vor jedem Schreiben · aktueller
(noch kaputter) Chiffretext wird vorher byte-genau gesichert
(`/var/nc-restore-backup/<website>`) · jede Datei wird nach dem
Schreiben normal zurückgelesen und per SHA-256 verglichen · Dry-Run ist
Default, echter Lauf braucht eine ausdrückliche `YES`-Bestätigung.

⚠️ **Ein erneuter Lauf wählt wieder *alle* passenden Einträge des
gewählten Accounts aus dem Report** – auch bereits erfolgreich
restaurierte, nicht nur neue. Für ein gezieltes Nachziehen einzelner,
noch offener Dateien lieber einen auf diese Dateien reduzierten
Mini-Report verwenden, statt den ganzen Account-Bestand erneut zu
überschreiben.

→ Ergebnis: `reports/restore_<website>_<datum>.tsv`

---

## 4. `recreate_bad_signature.sh` – Fallback für Schlüsselmaterial-Fehler

Nur nötig, wenn `restore_bad_signature.sh` bei einer Datei mit einem
**Schlüsselmaterial-Fehler** scheitert (`MultiKeyDecryptException` /
"probably this is a shared file…") statt mit "Bad Signature". Löscht
die kaputte Datei auf reiner Dateisystem-Ebene (inkl. altem
Schlüssel-Verzeichnis) und legt sie komplett neu an, mit frischem
Schlüssel.

⚠️ **Invasiver als restore:** Die Datei bekommt eine **neue Datei-ID**
– bestehende Freigaben, Kommentare, Tags und Versionshistorie dieser
Datei gehen dabei verloren und müssten danach manuell neu eingerichtet
werden. Nur verwenden, wenn Schritt 3 tatsächlich mit diesem
spezifischen Fehler gescheitert ist.

```bash
./recreate_bad_signature.sh -s <website>
# Dateien mit aktiven Freigaben standardmäßig übersprungen,
# nur mit Bedacht einschließen:
./recreate_bad_signature.sh -f -s <website>
```

**Sicherheit:** Nur Dateien mit passendem Fehler aus dem
restore-Report werden angefasst · Chiffretext UND Schlüssel-Verzeichnis
werden vorher gesichert und die Sicherung vor dem Löschen verifiziert
(`/var/nc-recreate-backup/<website>`) · Dateien mit aktiven Freigaben
werden standardmäßig übersprungen · Verifikation nach dem Schreiben wie
bei restore.

→ Ergebnis: `reports/recreate_<website>_<datum>.tsv`

---

## `delete_files.sh` – Gezielt nicht benötigte Dateien löschen

Generisches, von Account und Site unabhängiges Script für den zweiten
Teil des Aufräum-Workflows: eine **von Hand geprüfte** Liste an
Dateien entfernen, die nicht erhaltenswert sind (z. B. macOS-Spotlight-
Indexdateien, Fragmente aus "Webseite speichern"). Kein Scannen, kein
automatisches Erraten – jede Zeile in der Liste ist eine bewusste
Entscheidung.

Pfadliste: einfache Textdatei, ein Pfad pro Zeile (`#`-Kommentare und
Leerzeilen erlaubt), Account wird automatisch aus dem Pfad erkannt:

```
/inge/files/Ordner/Datei.ext
/anderer-account/files/Anderer/Pfad/datei2.ext
```

```bash
./delete_files.sh -s <website> -f <pfadliste.txt>
# nur Dry-Run:
./delete_files.sh -n -s <website> -f <pfadliste.txt>
```

Löscht über die normale Files-API (→ **Papierkorb**, sofern
`files_trashbin` aktiv ist) und sichert den Chiffretext zusätzlich
byte-genau vorher (`/var/nc-delete-backup/<website>`). Ein bereits
nicht mehr existierender Pfad wird als `NOT_FOUND` gemeldet, nicht als
Fehler.

→ Ergebnis: `reports/delete_<website>_<datum>.tsv`

---

## Typischer Ablauf

```bash
./scan_bad_signature.sh    -s cloud-01.oopen.de   # betroffene Dateien finden
./recover_bad_signature.sh -s cloud-01.oopen.de   # entschlüsseln + prüfen
./restore_bad_signature.sh -s cloud-01.oopen.de   # VALID + plausible zurückschreiben

# nur bei einzelnen WRITE_ERROR mit Schlüsselmaterial-Fehler nötig:
./recreate_bad_signature.sh -s cloud-01.oopen.de

# optional: von Hand geprüfte, nicht erhaltenswerte Dateien entfernen
./delete_files.sh -s cloud-01.oopen.de -f nicht_benoetigt.txt

# zur Kontrolle: sollte jetzt (für erledigte Accounts) 0 melden
./scan_bad_signature.sh    -s cloud-01.oopen.de
```

## Verzeichnisse

| Zweck | Standardpfad | Override (conf-Datei) |
|---|---|---|
| Recovery-Kopien (unverschlüsselt!) | `/var/nc-recovery/<website>` | `RECOVERY_BASE_DIR` |
| Backup vor restore-Überschreiben | `/var/nc-restore-backup/<website>` | `RESTORE_BACKUP_BASE_DIR` |
| Backup vor recreate-Löschen | `/var/nc-recreate-backup/<website>` | `RECREATE_BACKUP_BASE_DIR` |
| Backup vor delete_files-Löschen | `/var/nc-delete-backup/<website>` | `DELETE_BACKUP_BASE_DIR` |
| Reports aller Scripte | `reports/` (neben den Scripten) | – |

## Sicherheitsprinzipien (gelten für alle schreibenden Scripte)

- **Dry-Run ist Standard** – ein echter Lauf braucht eine ausdrückliche `YES`-Bestätigung.
- **Immer zuerst sichern**, dann erst schreiben/löschen – byte-genaue Kopie, unabhängig von Nextcloud.
- **Immer neu validieren** unmittelbar vor dem Zugriff, nicht blind aus einem alten Report übernehmen.
- **Immer verifizieren** nach dem Schreiben (Rücklesen + SHA-256-Vergleich).
- Jedes Script kann per `Strg-C` sicher unterbrochen werden – kein halb geschriebener Report.

## Kurzreferenz aller Flags

| Script | `-s` | weitere Optionen |
|---|---|---|
| `scan_bad_signature.sh` | Website | – |
| `recover_bad_signature.sh` | Website | `-V` nur revalidieren |
| `restore_bad_signature.sh` | Website | `-n` Dry-Run erzwingen |
| `recreate_bad_signature.sh` | Website | `-n` Dry-Run erzwingen · `-f` Dateien mit aktiven Freigaben einschließen |
| `delete_files.sh` | Website | `-n` Dry-Run erzwingen · `-f <datei>` Pfadliste (**Pflicht**) |

`-h` zeigt bei jedem Script die ausführliche Hilfe.