Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- jtl-shop:altcha-spamschutz:start [2026/09/21 16:34] – Installation praezisiert, Pflicht-Test gekuerzt, Gedankenstriche entfernt jf
+++ jtl-shop:altcha-spamschutz:start [2026/09/22 09:43] (aktuell) – Revert auf vorherige Fassung (letzte Ergänzung zurückgenommen) jf
@@ Zeile 1: / Zeile 1: @@
+====== JTL-Shop: falk_plus ALTCHA Spam- und Botschutz ======
-====== JTL-Shop: ALTCHA Spamschutz (Registrierung & Newsletter) ======
+Selbst gehostetes, quelloffenes Spam- und Botschutz-Plugin für JTL-Shop 5 auf Basis von [[https://altcha.org|ALTCHA]], einem quelloffenen Proof-of-Work-Verfahren (MIT-Lizenz). Schützt Registrierung, Newsletter-Anmeldung und Kontaktformular vor Spam-Bots und automatisierten Fake-Anmeldungen ohne Daten an Dritte weiterzugeben. Bewusst ohne Google reCAPTCHA und ohne Umleitung über Cloudflare oder ähnliche Dienste.
-Selbst gehostetes, quelloffenes Spamschutz-Plugin für JTL-Shop 5 auf Basis des ALTCHA Proof-of-Work-Verfahrens (MIT-Lizenz). Schützt Registrierung und Newsletter-Anmeldung vor automatisierten Fake-Anmeldungen, ohne Daten an Dritte weiterzugeben. Ziel ist dabei bewusst der Verzicht auf Google reCAPTCHA und ähnliche externe Dienste sowie auf eine Umleitung des Datenverkehrs über Cloudflare oder vergleichbare Drittanbieter. Die Prüfung läuft vollständig auf dem eigenen Server, ohne Cookies.
+===== 1. Was macht das Plugin =====
-Der Plugin-Quellcode wird direkt aus unserem Gitea-Repository synchronisiert (Repo: **JTL-Shop-ALTCHA-Spamschutz**), sodass Änderungen dort immer sofort auch hier im Guide aktuell sind.
+Das Plugin blendet in den drei genannten Formularen unauffällig eine kleine Sicherheitsprüfung ein. Der Browser des Besuchers löst dabei im Hintergrund eine kurze Rechenaufgabe (Proof-of-Work), bevor das Formular abgeschickt werden kann. Für Menschen ist das kaum spürbar (in der Regel deutlich unter einer Sekunde), für automatisierte Bot-Skripte, die kein JavaScript ausführen oder einfach nur Formularfelder befüllen, stellt es dagegen eine wirksame Hürde dar.
-===== 1. Hintergrund =====
+Da die gesamte Prüfung selbst gehostet läuft, verlassen keine Besucherdaten den eigenen Server, es gibt keine Weiterleitung an Google oder Cloudflare und keine Cookie- oder Datenschutz-Implikationen durch Drittanbieter-Dienste.
-Anlass war ein Bot-Problem bei einem Kunden: Über Wochen liefen massenhaft Fake-Registrierungen und Newsletter-Anmeldungen mit immer demselben Muster auf: "Test"/"Test User"/"Test Test" in Vorname, Nachname, Straße und Ort, aber echte, unterschiedliche Fremd-E-Mail-Adressen. Rate-Limiting und andere getestete Plugins konnten das Problem nicht zuverlässig lösen, da deren Prüfungen an anderer Stelle ansetzen (z. B. an Kommentar-/Nachrichtenfeldern, die weder das Registrierungs- noch das Newsletter-Formular besitzen). Dieses Plugin prüft stattdessen direkt beim Absenden von Registrierung und Newsletter-Anmeldung selbst, unabhängig davon, welche Felder das Formular sonst enthält, und kann bestehende Lösungen vollständig ersetzen.
+===== 2. Hintergrund =====
-===== 2. Funktionsweise =====
+Anlass war ein Bot-Problem: über einen längeren Zeitraum liefen massenhaft Fake-Registrierungen und Newsletter-Anmeldungen mit immer demselben Muster auf ("Test"/"Test User" in Vorname/Nachname/Ort/Straße, aber echte, unterschiedliche Fremd-E-Mail-Adressen). Andere getestete Maßnahmen wie Rate-Limiting konnten das Problem nicht zuverlässig lösen, da deren Prüfungen an anderer Stelle ansetzen (z. B. an Kommentar- oder Nachrichtenfeldern, die weder das Registrierungs- noch das Newsletter-Formular besitzen).
-Registrierung (''/Registrieren'') und Newsletter-Anmeldung (''/Newsletter'') erhalten eine unsichtbare Sicherheitsprüfung nach dem ALTCHA-Prinzip: Proof-of-Work, selbst gehostet, MIT-Lizenz. Der Browser des Besuchers muss vor dem Absenden eine kleine Rechenaufgabe lösen (meist unter 1 Sekunde, läuft im Hintergrund, kein Klicken/Kästchen nötig). Ein Skript, das das Formular direkt per HTTP-POST anspringt, wie bei den ursprünglichen Fake-Registrierungen offenbar geschehen, hat diese Lösung nicht und wird serverseitig abgelehnt.
+Dieses Plugin prüft stattdessen direkt beim Absenden von Registrierung, Newsletter-Anmeldung und Kontaktformular selbst, unabhängig davon, welche Felder das jeweilige Formular sonst enthält. Mittlerweile schützt es alle drei Formulare nach demselben Prinzip.
-Kann ergänzend zu einem bestehenden Rate-Limit eingesetzt werden oder andere Spamschutz-Plugins vollständig ersetzen.
+===== 3. Funktionsweise (ALTCHA) =====
-===== 3. Installation =====
+[[https://altcha.org|ALTCHA]] ist ein quelloffenes, selbst hostbares Proof-of-Work-Verfahren als datenschutzfreundliche Alternative zu klassischen Captchas. Der Ablauf:
-  - Im Adminbereich unter *Plugins → Plugin-Verwaltung* gibt es den Bereich "Plugin hochladen": Plugin-ZIP dort direkt hochladen und installieren.
+  - Der Server erzeugt beim Laden der Seite eine zufällige Rechenaufgabe (Challenge) und signiert sie.
-  - Oder per FTP hochladen: ZIP entpacken, Ordner ''fp_altcha_spamschutz'' per FTP/Dateimanager in das Plugin-Verzeichnis des Shops legen (''.../plugins/fp_altcha_spamschutz/''), danach in *Plugins → Plugin-Verwaltung* auf "Neue Plugins suchen" klicken.
+  - Der Browser des Besuchers löst diese Aufgabe im Hintergrund per JavaScript, bevor das Formular abgeschickt werden kann.
-  - Plugin öffnen → Einstellungen → Feld **HMAC-Geheimschlüssel** mit einem zufälligen, einmaligen Wert füllen (z. B. per ''openssl rand -hex 32'' erzeugt) und danach nicht mehr ändern, solange das Plugin aktiv genutzt wird.
+  - Beim Absenden prüft der Server die eingereichte Lösung anhand der Signatur. Passt sie nicht oder fehlt sie, wird die Anfrage abgelehnt.
-  - Übrige Einstellungen können auf den Standardwerten bleiben (Sicherheitsstufe "Mittel", beide Formulare aktiv, Debug-Logging aus).
-  - Speichern.
-===== 4. Einstellungen =====
+Die Bibliothek und das Verfahren stehen unter der MIT-Lizenz und werden unverändert vom offiziellen Projekt übernommen (siehe [[https://github.com/altcha-org/altcha-lib-php|altcha-org/altcha-lib-php]] auf GitHub). Es findet keine Kommunikation mit externen Diensten statt, die gesamte Prüfung läuft auf dem eigenen Server.
-^ Einstellung ^ Bedeutung ^
+===== 4. Geschützte Formulare =====
-| HMAC-Geheimschlüssel | Signiert die Sicherheitsprüfung. Pro Shop-Installation einmalig erzeugen, danach nicht mehr ändern. |
-| Sicherheitsstufe (Rechenaufwand) | Niedrig/Mittel/Hoch: wie viel Rechenarbeit der Browser leisten muss, i. d. R. unter 1 Sekunde. |
-| Gültigkeit der Prüfung | Wie lange eine erzeugte Prüfung gültig bleibt (Standard 600 Sekunden). |
-| Kundenregistrierung / Newsletter-Anmeldung schützen | Formulare einzeln aktivierbar. |
-| Debug-Logging | Schreibt Diagnoseinformationen ins Shop-Errorlog, nur temporär zum Testen aktivieren. |
-===== 5. Pflicht-Test vor Produktivbetrieb =====
+  * Kundenregistrierung (''/Registrieren'')
+  * Newsletter-Anmeldung (''/Newsletter'')
+  * Kontaktformular (''/Kontakt'')
-Dieses Plugin greift aktiv in Registrierung und Newsletter-Anmeldung ein. Die Kern-Sicherheitsprüfung (Challenge erzeugen → lösen → verifizieren) wurde isoliert erfolgreich getestet, die Einbindung in JTL-Shop selbst basiert auf der offiziellen Hook-Dokumentation. Bitte vor jedem Produktiveinsatz auf einem Testsystem prüfen:
+Jedes der drei Formulare lässt sich in den Plugin-Einstellungen einzeln aktivieren oder deaktivieren.
-  - **Normale Registrierung:** Formular ausfüllen und absenden, muss wie gewohnt funktionieren (kurzes "Sicherheitsprüfung wird vorbereitet …" / "… bestätigt").
+===== 5. Installation / Download =====
-  - **Normale Newsletter-Anmeldung:** muss wie gewohnt funktionieren.
-  - **Bypass-Versuch (wichtigster Test):** In der Entwicklerkonsole ''document.querySelector('input[name=altcha]').remove()'' ausführen und absenden. Das muss mit Fehlermeldung abgelehnt werden.
-  - **Direkter POST ohne JavaScript** (z. B. curl/Postman) ohne gültiges ''altcha''-Feld. Das muss ebenfalls abgelehnt werden.
-  - Einige Tage laufen lassen und die echten Fake-Registrierungszahlen beobachten, bevor produktiv übernommen wird.
-  - Danach kurz Debug-Logging aktivieren, ein paar Testanmeldungen durchführen, im Shop-Fehlerprotokoll auf ''[fp_altcha_spamschutz]''-Einträge prüfen, anschließend wieder deaktivieren.
-===== 6. Technischer Hintergrund =====
+Das Plugin wird als ZIP-Datei über das JTL-Shop-Backend installiert (*Plugins → Plugin hochladen*).
-==== 6.1 Warum ALTCHA V1 statt des aktuellen Widgets (v3)? ====
+Nach dem Hochladen wird das Plugin wie gewohnt im JTL-Shop-Backend aktiviert. Ein HMAC-Geheimschlüssel muss nicht manuell hinterlegt werden, das Plugin erzeugt beim ersten Aufruf automatisch einen zufälligen Schlüssel und speichert ihn im Plugin-Verzeichnis.
-Das offizielle ALTCHA-JS-Widget v3 nutzt ein neueres, komplexeres Protokoll (PBKDF2/Argon2id/Scrypt mit Key-Prefix-Matching), für das es keine robust dokumentierte "Challenge direkt einbetten"-Variante ohne zusätzlichen Netzwerk-Endpunkt gibt. Das klassische V1-Protokoll (SHA-256 Hashcash: Client sucht per Brute-Force eine Zahl n, für die SHA256(salt+n) == challenge gilt) ist dagegen vollständig dokumentiert, einfach zu prüfen und wird hier zusammen mit einem kleinen eigenen JS-Löser eingesetzt. Serverseitig kommt der offizielle, unveränderte [[https://github.com/altcha-org/altcha-lib-php|altcha-org/altcha-lib-php]]-Code zum Einsatz (MIT-Lizenz).
+Repository: [[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz|vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz]]
-Die Kryptografie wurde Cross-Language getestet: Der echte, unveränderte ''fp-altcha.js'' wurde unter Node.js gegen eine von der echten PHP-Bibliothek erzeugte Challenge gelöst und das Ergebnis erfolgreich mit derselben PHP-Bibliothek verifiziert.
+===== 6. Einstellungen =====
-==== 6.2 Verwendete JTL-Shop-Hooks ====
+In den Plugin-Einstellungen im JTL-Shop-Backend lassen sich konfigurieren:
-^ Hook ^ Zweck ^
+  * **HMAC-Geheimschlüssel** -- optional, wird sonst automatisch erzeugt.
-| HOOK_SMARTY_OUTPUTFILTER | Fügt Widget-Container und Skript in das gerenderte HTML von Registrierungs- und Newsletter-Formular ein (phpQuery-DOM-Filter). |
+  * **Sicherheitsstufe (Rechenaufwand)** -- wie viel Rechenarbeit der Browser vor dem Absenden leisten muss (niedrig/mittel/hoch).
-| HOOK_REGISTRIEREN_PAGE_REGISTRIEREN_PLAUSI | Plausibilitätsprüfung nach Absenden des Registrierungsformulars. |
+  * **Gültigkeit der Prüfung** -- wie lange eine erzeugte Prüfung gültig bleibt, bevor sie abläuft.
-| HOOK_NEWSLETTER_PAGE_EMPFAENGEREINTRAGEN | Zusätzliche Absicherung kurz vor dem Speichern des Newsletter-Empfängers (defense in depth). |
+  * **Formulare** -- Registrierung, Newsletter-Anmeldung und Kontaktformular einzeln aktivierbar.
+  * **Debug-Logging** -- schreibt zusätzliche Diagnoseinformationen ins Error-Log.
-Registriert per EventDispatcher in ''Bootstrap.php'' (moderner Mechanismus), nicht über die veraltete XML-''<Hooks>''-Datei.
+===== 7. Test nach der Installation =====
-==== 6.3 Defensives Design (fail-open) ====
+Nach der Installation sollte einmal geprüft werden, dass:
-Jede Stelle, an der sich das Plugin in den Shop einklinkt, ist mit try/catch abgesichert. Bewusste Entscheidung: Schlägt eine Prüfung aus unerwartetem Grund fehl (z. B. Plugin nicht vollständig konfiguriert), wird die Aktion durchgelassen statt den gesamten Shop lahmzulegen. Ein Bot mehr ist besser als ein Shop, bei dem sich niemand mehr registrieren kann. Die eigentliche Sicherheitsprüfung (''AltchaService::verifyPost()'') lehnt dagegen bei fehlender Konfiguration sicherheitshalber ab (fail-closed). Die beiden Ebenen ergänzen sich.
+  * in Registrierung, Newsletter-Anmeldung und Kontaktformular die Sicherheitsprüfung sichtbar erscheint und nach kurzer Zeit "Sicherheitsprüfung bestanden" anzeigt,
+  * eine normale, korrekt ausgefüllte Anfrage in allen drei Formularen anstandslos durchgeht,
+  * ein Absenden ohne JavaScript bzw. ohne gelöste Prüfung zuverlässig abgelehnt wird.
-===== 7. Bekannte Einschränkung =====
+===== 8. Bekannte Einschränkungen =====
-Falls das Registrierungs- oder Newsletterformular im verwendeten Template abweichende CSS-Klassen/Feldnamen hat als im Template "NOVA" ermittelt (''form.register-form'' bzw. ein Formular mit ''input[name="abonnieren"]''), erscheint das Widget dort nicht. Der Shop bleibt aber unverändert nutzbar (kein Fehler, das Plugin erkennt das Formular einfach nicht). In dem Fall bitte über den Issue-Tracker melden (siehe unten), dann werden die Selektoren angepasst.
+Das Widget wird über das umgebende Formular-Element eingebunden. Bei stark individualisierten Theme-Anpassungen, die die Formularstruktur wesentlich verändern, kann es in seltenen Fällen nötig sein, die verwendeten CSS-Selektoren im Plugin anzupassen.
-==== 8. Fehlerbehebung ====
+===== 9. Weiterführende Links =====
-^ Problem ^ Ursache ^ Lösung ^
+  * Gitea-Repository (Quellcode, Releases, Issues): [[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz]]
-| Widget erscheint nicht | Formular-Selektoren passen nicht zum Template | Siehe Abschnitt 7, Issue öffnen |
+  * ALTCHA-Projekt: [[https://altcha.org]]
-| Registrierung/Newsletter immer abgelehnt | Kein oder falscher HMAC-Geheimschlüssel hinterlegt | Einstellungen prüfen, Schlüssel neu setzen |
+  * ALTCHA PHP-Bibliothek (MIT-Lizenz): [[https://github.com/altcha-org/altcha-lib-php]]
-| Keine Fehlermeldung, Formular tut einfach nichts | JavaScript blockiert/sehr alter Browser ohne Web Crypto API | Erwartetes, sicheres Verhalten: Prüfung kann dann nicht bestätigt werden |
-===== 9. Quellcode =====
-Wird als reguläre Plugin-Dateien im Shop-Plugin-Verzeichnis abgelegt (siehe Installation). Die vendorierte ALTCHA-PHP-Bibliothek (''src/Vendor/AltchaOrg/Altcha/V1/'', MIT-Lizenz) ist Teil der Plugin-ZIP, wird hier aber nicht dupliziert. Siehe [[https://github.com/altcha-org/altcha-lib-php|altcha-org/altcha-lib-php]].
-==== 9.1 info.xml (Plugin-Manifest & Einstellungen) ====
-{{page>gitea_code:JTL-Shop-ALTCHA-Spamschutz:info_xml}}
-=== 💬 Fragen & Feedback ===
-Haben Sie Fehler gefunden, Verbesserungsvorschläge oder Fragen zu dieser Datei?
-[[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz/issues/new?labels=info.xml|Hier ein neues Gitea-Issue öffnen]]
-==== 9.2 Bootstrap.php (Hook-Registrierung) ====
-{{page>gitea_code:JTL-Shop-ALTCHA-Spamschutz:bootstrap_php}}
-=== 💬 Fragen & Feedback ===
-Haben Sie Fehler gefunden, Verbesserungsvorschläge oder Fragen zu dieser Datei?
-[[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz/issues/new?labels=Bootstrap.php|Hier ein neues Gitea-Issue öffnen]]
-==== 9.3 AltchaService.php (Challenge & Verifikation) ====
-{{page>gitea_code:JTL-Shop-ALTCHA-Spamschutz:altchaservice_php}}
-=== 💬 Fragen & Feedback ===
-Haben Sie Fehler gefunden, Verbesserungsvorschläge oder Fragen zu dieser Datei?
-[[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz/issues/new?labels=AltchaService.php|Hier ein neues Gitea-Issue öffnen]]
-==== 9.4 TemplateHandler.php (Widget-Einbindung) ====
-{{page>gitea_code:JTL-Shop-ALTCHA-Spamschutz:templatehandler_php}}
-=== 💬 Fragen & Feedback ===
-Haben Sie Fehler gefunden, Verbesserungsvorschläge oder Fragen zu dieser Datei?
-[[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz/issues/new?labels=TemplateHandler.php|Hier ein neues Gitea-Issue öffnen]]
-==== 9.5 ValidationHandler.php (Prüfung bei Absenden) ====
-{{page>gitea_code:JTL-Shop-ALTCHA-Spamschutz:validationhandler_php}}
-=== 💬 Fragen & Feedback ===
-Haben Sie Fehler gefunden, Verbesserungsvorschläge oder Fragen zu dieser Datei?
-[[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz/issues/new?labels=ValidationHandler.php|Hier ein neues Gitea-Issue öffnen]]
-==== 9.6 fp-altcha.js (Client-seitiger Löser) ====
-{{page>gitea_code:JTL-Shop-ALTCHA-Spamschutz:fp-altcha_js}}
-=== 💬 Fragen & Feedback ===
-Haben Sie Fehler gefunden, Verbesserungsvorschläge oder Fragen zu dieser Datei?
-[[https://vw.falk.plus/JensFalk/JTL-Shop-ALTCHA-Spamschutz/issues/new?labels=fp-altcha.js|Hier ein neues Gitea-Issue öffnen]]
-----
-//Anleitung erstellt auf Basis einer echten Kundenumsetzung. Plugin-Quellcode wird live aus Gitea (Repo: JTL-Shop-ALTCHA-Spamschutz) synchronisiert//

Impressum | Datenschutz