add script to first connection

README.md

@@ -0,0 +1,94 @@
+# eZICOM Login Helper
+
+Dieses Verzeichnis enthaelt ein kleines Python-Script, das den Login in die
+eZICOM5-Weboberflaeche automatisiert.
+
+Das Script macht keinen API-Login. Es ahmt den Browser-Login nach:
+
+1. `GET /` zum Aufbau der Session-Cookie
+2. `POST /user` mit den Formularfeldern `action=login`, `uid` und `pw0`
+
+## Dateien
+
+- `ezicom_login.py`: Login-Script
+- `plan.copilot`: kurze Untersuchungsnotizen
+- `Firefox Connection.html`: gespeicherte Firefox-Profiler-Ausgabe
+
+## Voraussetzungen
+
+- Python 3.10 oder neuer
+- Keine externen Python-Pakete erforderlich
+- Netzwerkzugriff auf `https://zm.sufw.de:31443`
+
+## Nutzung
+
+Am sichersten ist der interaktive Modus. Dabei werden keine Zugangsdaten in der
+Shell-History abgelegt:
+
+```bash
+./ezicom_login.py --insecure
+```
+
+Das Script fragt dann nach Benutzername und Passwort.
+
+Optional kann die HTML-Antwort nach dem Login gespeichert werden:
+
+```bash
+./ezicom_login.py --insecure --save-response after-login.html
+```
+
+Wenn du Zugangsdaten ueber Environment-Variablen setzen willst:
+
+```bash
+EZICOM_USERNAME='dein-user' EZICOM_PASSWORD='dein-passwort' ./ezicom_login.py --insecure
+```
+
+Oder trage sie in `.env` ein:
+
+```dotenv
+EZICOM_USERNAME=dein-user
+EZICOM_PASSWORD=dein-passwort
+```
+
+Danach reicht:
+
+```bash
+./ezicom_login.py --insecure
+```
+
+Alternativ per CLI-Argument:
+
+```bash
+./ezicom_login.py -u 'dein-user' -p 'dein-passwort' --insecure
+```
+
+Hinweis: CLI-Argumente koennen in der Shell-History und kurzzeitig in der
+Prozessliste sichtbar sein. Fuer echte Nutzung ist der interaktive Modus oder
+ein sauber geschuetzter Secret-Store besser.
+
+## TLS / Zertifikat
+
+Bei lokalen Tests konnte Python die Zertifikatskette der eZICOM-Installation
+nicht verifizieren. Deshalb gibt es die Option:
+
+```bash
+--insecure
+```
+
+Diese Option deaktiviert die TLS-Zertifikatspruefung. Sauberer waere es, die
+ausstellende CA lokal zu installieren und das Script ohne `--insecure` zu
+verwenden.
+
+## Exit-Codes
+
+- `0`: Login sieht erfolgreich aus
+- `1`: Login wurde vom Server abgelehnt, zum Beispiel HTTP 403
+- `2`: technischer Fehler, zum Beispiel Netzwerk- oder TLS-Problem
+
+## Bekannte Grenzen
+
+Das Script loggt nur ein und prueft die unmittelbare Antwort. Es bucht noch
+keine Zeiten und ruft keine eZICOM-API auf.
+
+Fuer den naechsten Schritt muessen wir nach erfolgreichem Login untersuchen,
+welche Requests beim eigentlichen Buchen von Zeiten gesendet werden.