Beleg — Wartungsberichte für WordPress-Agenturen

Gratis-WordPress-Plugin sammelt read-only Site-Daten, das gehostete Dashboard erzeugt daraus monatliche Wartungsberichte im Branding der Agentur. Arbeitstitel „Beleg" — vor Launch Marken-/Domain-Check machen.

Was funktioniert (getestet)

• Registrierung/Login (scrypt-Hashing, httpOnly-Session-Cookie, SameSite=Lax)
• Sites anlegen → API-Key + öffentlicher Report-Share-Token
• Ingest: Plugin pusht täglich + nach jedem Update (Bearer-Auth, 1-MB-Limit, Feld-Validierung)
• Update-Historie doppelt abgesichert: Echtzeit-Events vom Plugin-Hook + Server-Diff zwischen Tages-Snapshots als Fallback, mit Dedupe (48-h-Fenster)
• Uptime-Monitor: prüft alle Sites alle 5 Min. vom Server aus, 400 Tage Retention
• Report (/r/<token>?month=JJJJ-MM): Uptime, Update-Liste, Systemstatus, automatische Empfehlungen (PHP-Version, SSL, offene Updates) + manuell editierbarer „Empfehlung Ihres Teams"-Block, White-Label (Name, Farbe, Logo), Print-CSS → „Als PDF speichern"
• DSGVO-Basics im Code: Datenminimierung (nur technische Metadaten, keine Besucherdaten), Löschkaskaden für Site und Konto (Art. 17)

Struktur

server/                 Node.js 22+ (Express + eingebautes node:sqlite, 1 Dependency)
  src/index.js          Bootstrap
  src/app.js            Routen (Auth, Sites, Ingest, Report, Dashboard)
  src/db.js             Schema + Ingest-/Diff-Logik
  src/report.js         Report-Berechnung + HTML
  src/ui.js             Dashboard-Seiten
  src/uptime.js         Pinger
plugin/beleg-connector/ WordPress-Plugin (Opt-in, Guideline-7-konform, GPLv2)

Lokal starten

cd server && npm install && node src/index.js   # → http://localhost:3000

Konto anlegen, Site anlegen, dann das Plugin-Verzeichnis plugin/beleg-connector/ als ZIP packen, in WordPress hochladen und unter Einstellungen → Beleg verbinden.

Deploy auf EU-Server (z. B. Hetzner CX22, ~5 €/Monat)

# 1. Node 22 installieren (nodesource) und Code nach /opt/beleg kopieren
# 2. systemd-Unit /etc/systemd/system/beleg.service:
[Unit]
Description=Beleg
After=network.target
[Service]
WorkingDirectory=/opt/beleg/server
Environment=PORT=3000
Environment=BELEG_URL=https://app.deine-domain.de
Environment=BELEG_DB=/var/lib/beleg/beleg.sqlite
ExecStart=/usr/bin/node src/index.js
Restart=always
User=beleg
[Install]
WantedBy=multi-user.target

# 3. TLS-Reverse-Proxy mit Caddy (automatisches Let's-Encrypt), /etc/caddy/Caddyfile:
app.deine-domain.de {
    reverse_proxy localhost:3000
}

# 4. Backup: SQLite-Datei nächtlich per cron sichern (sqlite3 .backup oder Datei-Copy im WAL-Checkpoint)

BELEG_URL unbedingt auf die https-Domain setzen (steuert Secure-Cookie und die angezeigte Server-URL im Dashboard).

Bewusst noch offen (Reihenfolge = Empfehlung)

1. WordPress.org-Einreichung (Woche 4!): Slug sichern, „Tested up to" pflegen, Screenshots. Die readme.txt inkl. „External services"-Sektion liegt bei.
2. Stripe Billing: Checkout + Customer Portal, Plan-Feld an users, whiteLabel-Flag in app.js (Report-Route, TODO-Kommentar) an Paid koppeln.
3. Automatischer Monatsversand: Cron am 1. des Monats → Report-Link/PDF per E-Mail (EU-Anbieter, z. B. Scaleway TEM oder Brevo) mit Reply-To der Agentur. Server-PDF später via Gotenberg (Docker) — bis dahin reicht Print-to-PDF.
4. Rechtstexte: Impressum, Datenschutzerklärung, AGB, AVV-Muster für Agentur-Kunden (siehe Blueprint-Dokument; vor Launch anwaltlich prüfen lassen).
5. Härtung: Rate-Limiting auf /api/auth/* und /api/ingest, CSRF-Token für Formular-POSTs, E-Mail-Verifizierung, Passwort-Reset.

Sicherheitsmodell (Kurzfassung)

API-Key (Site → Server) und Share-Token (Report-Link) sind getrennte Geheimnisse; der Report-Link kann weitergegeben werden, ohne Schreibzugriff zu gewähren. Passwörter: scrypt mit Salt, timing-safe Vergleich. Alle SQL-Zugriffe über Prepared Statements. Plugin sendet nur nach gespeicherter Einwilligung (Opt-in, WordPress-Guideline 7 inkl. SaaS-Ausnahme).