security(rescan): Notbremse vor dem harten Löschen

internal/rescan ist das einzige Stück Aether, das hart löscht: DELETE FROM
files, kein Papierkorb. Entfernt wird, was beim Durchgang über die Platte nicht
gesehen wurde.

Der Ernstfall ist nicht ausgedacht. LocalFS.Walk gibt für ein nicht vorhandenes
Verzeichnis nil zurück – kein Fehler, keine Einträge. Genau der Fingerabdruck
eines Bind-Mounts, der nach einem Neustart nicht hochkam, oder eines
Tippfehlers in DATA_PATH. Dann gilt jede Datei als verwaist, und ein einziger
Aufruf mit ?anwenden=true löscht den gesamten Bestand aus der Datenbank. Die
Bytes lägen noch da, aber niemand wüsste mehr, dass es sie gibt – und der GC
räumte sie 24 Stunden später ab.

Der GC hat diese Bremse seit dem 12.09. Beide gleichen Platte und Datenbank ab,
nur aus entgegengesetzter Richtung, und beide haben denselben Fehlerfall: Eine
Seite antwortet fälschlich mit „leer". Der GC löscht dann Blobs – die Datenbank
weiss hinterher noch, was fehlt. Hier fällt die Zeile selbst. Die gefährlichere
Seite war die ungesicherte.

Zwei Bremsen: Die Notbremse (nichts gefunden, Datenbank kennt Dateien) lässt
sich nicht übersteuern. Die Mengenbremse (mehr als die Hälfte) verlangt
&bestaetigt=true. Die leere Installation ist ausgenommen.

Dazu umgebaut: erst sammeln, dann entscheiden, dann löschen. Vorher wurde
mitten in der Schleife gelöscht; die Gesamtzahl kennt man dort erst, wenn die
Hälfte schon weg ist.

Der Bericht nennt den Grund und ob er bestätigbar ist – die Oberfläche soll
keinen Knopf anbieten, der nichts bewirkt. Ein abgebrochener Lauf steht rot in
der Karte und im Audit-Log; gerade der, denn er ist der Hinweis darauf, dass
mit dem Datenordner etwas nicht stimmt.

Fünf Tests, unter Mutation nachgewiesen. Der Ernstfall läuft am echten Gerät:
fünf Zeilen in der Datenbank, ein Wurzelverzeichnis ohne users/ – nach Apply
stehen alle fünf noch, auch mit Bestätigung.

audit und thumbnails bekommen bewusst keine Go-Tests; die Begründung steht in
BEFUNDE.md statt als ewig offener Punkt.

Nebenbefund behoben: kalender-teilen-selbsttest.py leckte je Lauf ein
App-Passwort des Besitzers. Nach achtzehn Läufen war maxAppPasswords = 20
erreicht, und zwei Suiten scheiterten mit 409, ohne dass am Code etwas kaputt
war.

Geprüft: go build/vet sauber, alle Go-Pakete grün, 243 Prüfungen der sieben
Selbsttest-Suiten grün, 48 Vitest-Tests, tsc sauber.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/internal/admin/audit_handler.go

@@ -142,12 +142,16 @@ func (h *Handler) Rescan(w http.ResponseWriter, r *http.Request) {
 	}
 
 	anwenden := r.URL.Query().Get("anwenden") == "true"
+	// Zweiter Schlüssel für den Fall, dass wirklich mehr als die Hälfte fallen
+	// soll. Bewusst ein eigener Parameter: Wer „anwenden" tippt, meint
+	// aufräumen; wer „bestaetigt" dazutippt, hat den Bericht gelesen.
+	bestaetigt := r.URL.Query().Get("bestaetigt") == "true"
 	var (
 		bef *rescan.Report
 		err error
 	)
 	if anwenden {
-		bef, err = h.rescan.Apply(r.Context())
+		bef, err = h.rescan.Apply(r.Context(), bestaetigt)
 	} else {
 		bef, err = h.rescan.Check(r.Context())
 	}
@@ -157,9 +161,17 @@ func (h *Handler) Rescan(w http.ResponseWriter, r *http.Request) {
 	}
 
 	if anwenden {
-		h.logAdmin(r, audit.ActionGarbageCollect, "storage", "", "",
-			fmt.Sprintf("rescan applied: %d adopted, %d corrected, %d rows removed, %d errors",
-				bef.Adopted, bef.Corrected, bef.Removed, bef.Errors))
+		// Ein abgebrochener Lauf gehört genauso ins Protokoll wie ein
+		// ausgeführter – **gerade der**: Er ist der Hinweis darauf, dass mit
+		// dem Datenordner etwas nicht stimmt.
+		if bef.Aborted {
+			h.logAdmin(r, audit.ActionGarbageCollect, "storage", "", "",
+				"rescan aborted, nothing removed: "+bef.AbortReason)
+		} else {
+			h.logAdmin(r, audit.ActionGarbageCollect, "storage", "", "",
+				fmt.Sprintf("rescan applied: %d adopted, %d corrected, %d rows removed, %d errors",
+					bef.Adopted, bef.Corrected, bef.Removed, bef.Errors))
+		}
 	}
 	response.JSON(w, http.StatusOK, bef)
 }

backend/internal/rescan/bremse_test.go

@@ -0,0 +1,164 @@
+package rescan
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"aether/internal/files"
+	"aether/internal/storage"
+)
+
+// Der Abgleich ist das einzige Stück Aether, das **hart** löscht:
+// `DELETE FROM files`, kein Papierkorb. Entfernt wird, was beim Durchgang über
+// die Platte nicht gesehen wurde.
+//
+// Der Ernstfall ist nicht ausgedacht: `LocalFS.Walk` gibt für ein nicht
+// vorhandenes Verzeichnis `nil` zurück – kein Fehler, keine Einträge. Genau
+// der Fingerabdruck eines Bind-Mounts, der nach einem Neustart nicht hochkam.
+// Ohne Bremse gälte dann jede Datei als verwaist, und ein einziger Aufruf mit
+// `?anwenden=true` löschte den ganzen Bestand aus der Datenbank.
+//
+// Der GC hat diese Bremse seit dem 12.09.2026. Hier fehlte sie – an der
+// gefährlicheren von beiden Stellen.
+
+func TestNotbremseBeiLeeremSpeicher(t *testing.T) {
+	// Nichts gesehen, obwohl die Datenbank Dateien kennt: nicht verhandelbar.
+	grund, uebersteuerbar := pruefeBremse(0, 1200, 1200, false)
+	if grund == "" {
+		t.Fatal("leerer Durchgang bei gefuellter Datenbank muss bremsen")
+	}
+	if uebersteuerbar {
+		t.Fatal("die Notbremse darf sich nicht bestaetigen lassen")
+	}
+	// Auch mit ausdruecklicher Bestaetigung nicht.
+	if grund, _ := pruefeBremse(0, 1200, 1200, true); grund == "" {
+		t.Fatal("auch mit Bestaetigung muss die Notbremse halten")
+	}
+}
+
+func TestLeereInstallationDarfDurch(t *testing.T) {
+	// Nichts auf der Platte, nichts in der Datenbank – da gibt es nichts zu
+	// verwechseln. Würde hier gebremst, liesse sich eine frische Anlage nie
+	// abgleichen.
+	if grund, _ := pruefeBremse(0, 0, 0, false); grund != "" {
+		t.Fatalf("leere Installation darf nicht bremsen: %s", grund)
+	}
+}
+
+func TestMengenbremseLaesstSichBestaetigen(t *testing.T) {
+	// Mehr als die Hälfte auf einmal: erst nachfragen.
+	grund, uebersteuerbar := pruefeBremse(500, 1000, 501, false)
+	if grund == "" {
+		t.Fatal("mehr als die Haelfte muss nachfragen")
+	}
+	if !uebersteuerbar {
+		t.Fatal("die Mengenbremse muss sich bestaetigen lassen")
+	}
+	if grund, _ := pruefeBremse(500, 1000, 501, true); grund != "" {
+		t.Fatalf("mit Bestaetigung muss es durchgehen: %s", grund)
+	}
+}
+
+func TestGewoehnlichesAufraeumenGehtDurch(t *testing.T) {
+	// Der Normalfall: ein paar Leichen unter vielen. Bremste es hier, wäre die
+	// Funktion unbrauchbar – und jemand baute die Bremse wieder aus.
+	for _, f := range []struct {
+		gescannt, lebende, fallen int
+	}{
+		{1000, 1000, 1},
+		{1000, 1000, 17},
+		{1000, 1000, 500}, // genau die Hälfte: noch erlaubt
+		{1, 1, 0},
+	} {
+		if grund, _ := pruefeBremse(f.gescannt, f.lebende, f.fallen, false); grund != "" {
+			t.Fatalf("%d von %d duerfen fallen, wurde gebremst: %s", f.fallen, f.lebende, grund)
+		}
+	}
+}
+
+// Und jetzt der Ernstfall am echten Gerät: Dateien in der Datenbank, ein
+// Datenordner, den es nicht gibt. Nach dem Anwenden muss **jede** Zeile noch
+// da sein.
+//
+// Läuft nur mit TEST_DSN: ./scripts/db-tests.sh ./internal/rescan/
+func TestAnwendenLoeschtNichtsWennDerOrdnerFehlt(t *testing.T) {
+	dsn := os.Getenv("TEST_DSN")
+	if dsn == "" {
+		t.Skip("TEST_DSN nicht gesetzt")
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("verbinden: %v", err)
+	}
+	defer pool.Close()
+
+	var nutzer uuid.UUID
+	if err := pool.QueryRow(ctx,
+		`INSERT INTO users (username, display_name, password, is_admin)
+		 VALUES ($1, $1, 'x', false) RETURNING id`, "rescan-"+uuid.NewString()[:8],
+	).Scan(&nutzer); err != nil {
+		t.Fatalf("konto: %v", err)
+	}
+	defer pool.Exec(ctx, `DELETE FROM users WHERE id = $1`, nutzer)
+
+	for i := 0; i < 5; i++ {
+		if _, err := pool.Exec(ctx,
+			`INSERT INTO files (owner_id, folder_id, name, mime_type, size, checksum, storage_key)
+			 VALUES ($1, NULL, $2, 'application/pdf', 3, 'x', $3)`,
+			nutzer, "Rechnung.pdf", "users/wer/home/"+uuid.NewString(),
+		); err != nil {
+			t.Fatalf("datei: %v", err)
+		}
+	}
+
+	// Ein Wurzelverzeichnis, das es gibt – aber ohne "users/" darin. Genau das
+	// sieht der Server, wenn der Bind-Mount nicht hochkam.
+	wurzel := t.TempDir()
+	st, err := storage.NewLocalFS(wurzel, filepath.Join(wurzel, "tmp"))
+	if err != nil {
+		t.Fatalf("speicher: %v", err)
+	}
+
+	scanner := New(pool, files.NewStore(pool), st)
+	bericht, err := scanner.Apply(ctx, false)
+	if err != nil {
+		t.Fatalf("anwenden: %v", err)
+	}
+
+	if !bericht.Aborted {
+		t.Fatal("der Lauf haette abbrechen muessen")
+	}
+	if bericht.Removed != 0 {
+		t.Fatalf("es durfte nichts entfernt werden, entfernt wurden %d", bericht.Removed)
+	}
+	if bericht.Overridable {
+		t.Fatal("die Notbremse darf sich nicht bestaetigen lassen")
+	}
+
+	var uebrig int
+	if err := pool.QueryRow(ctx,
+		`SELECT count(*) FROM files WHERE owner_id = $1`, nutzer).Scan(&uebrig); err != nil {
+		t.Fatalf("zaehlen: %v", err)
+	}
+	if uebrig != 5 {
+		t.Fatalf("alle fuenf Zeilen muessen stehen bleiben, es sind %d", uebrig)
+	}
+
+	// Gegenprobe mit Bestaetigung: Auch dann bleibt alles stehen.
+	if _, err := scanner.Apply(ctx, true); err != nil {
+		t.Fatalf("anwenden mit Bestaetigung: %v", err)
+	}
+	if err := pool.QueryRow(ctx,
+		`SELECT count(*) FROM files WHERE owner_id = $1`, nutzer).Scan(&uebrig); err != nil {
+		t.Fatalf("zaehlen: %v", err)
+	}
+	if uebrig != 5 {
+		t.Fatalf("auch mit Bestaetigung muessen alle fuenf stehen, es sind %d", uebrig)
+	}
+}

backend/internal/rescan/rescan.go

@@ -22,6 +22,7 @@ import (
 
 	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/rs/zerolog/log"
 
 	"aether/internal/files"
 	"aether/internal/storage"
@@ -66,6 +67,13 @@ type Report struct {
 	Scanned  int     `json:"scanned"`
 	Samples  []Entry `json:"samples"`
 	Aborted  bool    `json:"aborted,omitempty"`
+	// AbortReason sagt, **warum** nichts geändert wurde. Ein „aborted: true"
+	// ohne Grund lässt genau die Frage offen, die man dann hat.
+	AbortReason string `json:"abort_reason,omitempty"`
+	// Overridable unterscheidet die beiden Bremsen. Die Mengenbremse lässt
+	// sich bestätigen, die Notbremse nicht – und die Oberfläche soll keinen
+	// Knopf anbieten, der nichts bewirkt.
+	Overridable bool `json:"overridable,omitempty"`
 
 	// Nur bei Apply gefüllt.
 	Adopted   int `json:"adopted,omitempty"`
@@ -137,13 +145,16 @@ func splitKey(key string) (root, owner, folderPath, name string, ok bool) {
 }
 
 // Check liest nur und ändert nichts – jederzeit gefahrlos.
-func (s *Scanner) Check(ctx context.Context) (*Report, error) { return s.run(ctx, false) }
+func (s *Scanner) Check(ctx context.Context) (*Report, error) { return s.run(ctx, false, false) }
 
 // Apply übernimmt neue Dateien, berichtigt geänderte und entfernt verwaiste
 // Einträge.
-func (s *Scanner) Apply(ctx context.Context) (*Report, error) { return s.run(ctx, true) }
+// trotzdem hebt die Mengenbremse auf – nicht die Notbremse. Siehe pruefeBremse.
+func (s *Scanner) Apply(ctx context.Context, trotzdem bool) (*Report, error) {
+	return s.run(ctx, true, trotzdem)
+}
 
-func (s *Scanner) run(ctx context.Context, apply bool) (*Report, error) {
+func (s *Scanner) run(ctx context.Context, apply, trotzdem bool) (*Report, error) {
 	ctx, cancel := context.WithTimeout(ctx, maxDuration)
 	defer cancel()
 
@@ -217,7 +228,19 @@ func (s *Scanner) run(ctx context.Context, apply bool) (*Report, error) {
 	// Einträge, deren Datei fehlt. Papierkorb und frühere Fassungen liegen
 	// außerhalb des Durchgangs – für die wird einzeln nachgesehen, statt sie
 	// pauschal für verwaist zu erklären.
+	// **Erst sammeln, dann entscheiden, dann löschen.** Vorher wurde mitten in
+	// der Schleife gelöscht – dann kennt man die Gesamtzahl erst, wenn die
+	// Hälfte schon weg ist, und eine Bremse käme zu spät.
+	type waise struct {
+		key string
+		id  uuid.UUID
+	}
+	var waisen []waise
+	var lebende int
 	for key, row := range known {
+		if !row.deleted {
+			lebende++
+		}
 		if row.seen || row.deleted {
 			continue
 		}
@@ -226,10 +249,34 @@ func (s *Scanner) run(ctx context.Context, apply bool) (*Report, error) {
 				continue
 			}
 		}
-		rep.Orphaned++
-		e := Entry{Kind: KindOrphaned, StorageKey: key, Path: key}
+		waisen = append(waisen, waise{key: key, id: row.id})
+	}
+	rep.Orphaned = len(waisen)
+
+	if apply {
+		if grund, uebersteuerbar := pruefeBremse(rep.Scanned, lebende, len(waisen), trotzdem); grund != "" {
+			rep.Aborted = true
+			rep.AbortReason = grund
+			rep.Overridable = uebersteuerbar
+			log.Ctx(ctx).Error().
+				Int("scanned", rep.Scanned).
+				Int("lebende_eintraege", lebende).
+				Int("wuerden_fallen", len(waisen)).
+				Str("grund", grund).
+				Msg("rescan: Anwenden abgebrochen - das sieht nicht nach Aufraeumen aus")
+			// Die Waisen trotzdem in die Stichprobe, damit man im Bericht
+			// sieht, worum es gegangen wäre.
+			for _, o := range waisen {
+				sample(Entry{Kind: KindOrphaned, StorageKey: o.key, Path: o.key})
+			}
+			return rep, nil
+		}
+	}
+
+	for _, o := range waisen {
+		e := Entry{Kind: KindOrphaned, StorageKey: o.key, Path: o.key}
 		if apply {
-			if err := s.remove(ctx, row.id); err != nil {
+			if err := s.remove(ctx, o.id); err != nil {
 				e.Reason = err.Error()
 				rep.Errors++
 			} else {
@@ -241,3 +288,47 @@ func (s *Scanner) run(ctx context.Context, apply bool) (*Report, error) {
 
 	return rep, nil
 }
+
+// ── Die Bremsen ──────────────────────────────────────────────────────────────
+
+// mengenAnteil: Ab welchem Anteil der lebenden Einträge ein Lauf nicht mehr
+// nach Aufräumen aussieht, sondern nach einem Unfall. Die Hälfte ist
+// großzügig – wer wirklich einmal halb Aether von Hand aus dem Datenordner
+// entfernt hat, bestätigt einmal und kommt durch.
+const mengenAnteil = 2
+
+// pruefeBremse entscheidet, ob wirklich gelöscht werden darf. Leerer Rückgabe-
+// wert heißt: ja.
+//
+// **Warum es das hier braucht, obwohl der GC es schon hat.** Beide gleichen
+// Platte und Datenbank ab, nur aus entgegengesetzter Richtung, und beide haben
+// denselben Fehlerfall: Eine Seite antwortet fälschlich mit „leer". Der GC
+// löscht dann Blobs – die Datenbank weiß hinterher noch, was fehlt. Hier fällt
+// `DELETE FROM files`, und damit das Einzige, was noch wusste, dass es die
+// Datei gab. Die gefährlichere Seite war die ungesicherte.
+//
+// Der Auslöser ist keine Theorie: `LocalFS.Walk` gibt für ein **nicht
+// vorhandenes** Verzeichnis `nil` zurück – kein Fehler, keine Einträge. Genau
+// der Fingerabdruck eines Bind-Mounts, der nach einem Neustart nicht hochkam,
+// oder eines Tippfehlers in DATA_PATH. Ohne diese Prüfung gälte dann jede
+// Datei als verwaist.
+func pruefeBremse(gescannt, lebende, wuerdenFallen int, trotzdem bool) (grund string, uebersteuerbar bool) {
+	// **Notbremse – nicht übersteuerbar.** Nichts auf der Platte gesehen,
+	// obwohl die Datenbank Dateien kennt: Das ist kein Bestand, der
+	// verschwunden ist, das ist ein Speicher, der nicht da war.
+	if gescannt == 0 && lebende > 0 {
+		return "auf der Platte wurde keine einzige Datei gefunden, " +
+			"obwohl die Datenbank welche kennt - vermutlich ist der Datenordner " +
+			"nicht eingehaengt. Es wurde nichts geloescht.", false
+	}
+
+	// **Mengenbremse – mit Bestaetigung übersteuerbar.** Dass mehr als die
+	// Hälfte auf einmal fällt, kommt bei echtem Aufräumen nicht vor.
+	if !trotzdem && wuerdenFallen > 0 && wuerdenFallen*mengenAnteil > lebende {
+		return fmt.Sprintf(
+			"%d von %d Eintraegen wuerden entfernt - das ist mehr als die Haelfte. "+
+				"Wenn das stimmt, noch einmal mit ausdruecklicher Bestaetigung aufrufen.",
+			wuerdenFallen, lebende), true
+	}
+	return "", false
+}