mailwarden CLAUDE.md

mailwarden — Projektinstruktionen

Native Gmail-MCP-Server (TypeScript, Node ≥20). Veröffentlicht als npm-Paket mailwarden und in der MCP-Registry als io.github.csitte/mailwarden.

Harte Design-Regeln (nicht ohne Rücksprache ändern)

• Kein Senden — by design. Es gibt keine compose/reply/forward/send-Tools. Das ist die zentrale Sicherheitszusage gegen Prompt-Injection-Exfiltration und der wichtigste Differenzierer — siehe SECURITY.md. Auch create_filter erzeugt nie eine Forwarding-Regel. Präzise formulieren: von Google erzwungen ist das nur im read-Tier (gmail.readonly); gmail.modify ist bei Google für messages.send zulässig (13.08.2026 live bestätigt), dort trägt die Tool-Oberfläche die Zusage. Nie wieder „die Scopes können nicht senden" schreiben. Das prüft seit 26.08. ein Test (test/send-claims.test.ts + scripts/lib/send-claims.mjs): jede scope-verankerte No-Send-Aussage muss in einer Allowlist stehen — dieselbe Mechanik wie beim Egress-Guard. Eine neue Formulierung bricht npm test, bis jemand sie einträgt. Anlass: die Regel stand hier schon und wurde trotzdem zweimal verletzt (13.08. in sechs Dateien, 26.08. in 0.15.0 ausgeliefert). Seit 20.08. zusätzlich src/egress.ts: ein Checkpoint um request() des Auth-Clients, Allowlist der 15 tatsächlich genutzten Endpunkte — das sind 13 Einträge in ALLOWED, weil einer modify|trash|untrash in einem Ausdruck zusammenfasst; wer die Datei zählt, kommt auf 13, wer Endpunkte zählt, auf 15 (csitte kam bei der Verifikation auf 14, und das kam aus genau dieser Doppeldeutigkeit) — plus vorgeschaltete Denylist (send/drafts/import/insert/Hard-Delete/settings außer filters). Damit ist die Zusage im Server erzwungen — aber weiter nicht am Token: ein gestohlenes gmail.modify-Refresh-Token sendet von woanders. Wer einen Endpunkt neu benutzt, muss ihn dort eintragen, sonst fliegt der Aufruf. Die beiden Listen sind bewusst asymmetrisch (23.08.): die Denylist matcht einen normalisierten Pfad (Upload-Präfixe gestrippt, Mehrfach-Slashes gefaltet), weil googleapis bei media auf /upload/gmail/v1/... zielt — ein realer Sendeweg, den auf /gmail/v1 verankerte Regeln nie sahen. Die Allowlist matcht weiter roh und darf das nie ändern: sonst bekäme jeder erlaubte Endpunkt eine zweite, ungeprüfte Schreibweise. Merksatz: Denylist so breit wie die API wirklich ist, Allowlist so eng wie mailwarden wirklich ist.
• Kein Hard-Delete. Nur trash/untrash (wiederherstellbar).
• Live-API, kein Cache. Kein Mailbox-Spiegel, kein Suchindex. Einziger lokaler Zustand: ~/.mailwarden/ (credentials.json, token.json, ggf. token.<account>.json).
• Suchtreffer werden re-verifiziert. threads.list (nicht „der Suchindex") kann Read-State-Operatoren aus einem veralteten **Thread-**Read-State beantworten (gemessen 15.08.2026: 131 Treffer für category:updates is:unread, davon 114 ohne eine einzige ungelesene Nachricht = 87 %; in der Nacht darauf über beide Endpunkte nachgemessen 132/114 — eine Mail kam dazwischen, beide Zahlen stehen, und welche Zahl aus welcher Messung stammt, steht in docs/measurements.json (ein Test prüft, dass keine Zahl ohne Beleg im Repo steht) — im selben Durchgang ein zweites Postfach mit 0 Drift, und dieselbe Query über messages.list im selben Postfach in derselben Minute: 19 Treffer, 0 veraltet). search() geht über threads.list und prüft deshalb jeden Treffer gegen die echten Labels; der Message-Pfad (bulk_modify) ist ein anderer Fall. Drei Formulierungen sind verbrannt und nicht wiederzubeleben: der Index „verwerfe is:unread" (falsch — dieselbe Query ohne das Prädikat liefert 800+, es wirkt also), es liege an bestimmten Operator-Kombinationen (falsch — auch die simpelste Query zeigt den Effekt; „größter Effekt" nur absolut, 136 Threads, in Prozent ist sie mit 58 % die schwächste), und es betreffe is:unread allgemein (unbelegt — das zweite Postfach widerspricht). Belegt ist: postfachabhängig, und ein Server kann vorher nicht wissen, in welchem er steckt. Demo gegen eine Fake-API: node scripts/demo-reverify.mjs; Messung im eigenen Postfach: node scripts/probe-reverify.mjs.