feat(api): Agent-API mit Enrollment, Report und Ping (#004)

Gehashte Tokens mit Praefix, Rate-Limit je IP und Token, zod-Validierung mit
durchgaengig optionalen Feldern, idempotente Reports ueber reportId, Key- und
Server-ID-Historie sowie automatischer Laufzeit-Vorschlag. 32 Tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/issues/004-agent-api.md

@@ -1,28 +1,33 @@
 # #004 Agent-API
-**Status:** offen
+**Status:** erledigt
 **Meilenstein:** v0.1.0
 **Labels:** backend, api, sicherheit
-**Geschätzt:** 6 h   **Tatsächlich:** –
+**Geschätzt:** 6 h   **Tatsächlich:** 0 h 20 min
 
 ## Ziel
 Getrennte, abgesicherte API unter `/api/agent/v1`, über die sich Agents registrieren und Reports abliefern.
 
 ## Aufgaben
-- [ ] Token-Bibliothek: Erzeugung (Präfix `plx_e_`/`plx_h_`), SHA-256-Hash, Prüfung, Widerruf, `lastUsedAt`
-- [ ] `POST /enroll`: Enrollment-Token prüfen (Ablauf, Nutzungen), Host anlegen oder Neuinstallation erkennen, Host-Token ausgeben, optionale Kunden-/Standort-Zuordnung
-- [ ] `POST /report`: zod-Schema (alle Felder nullable), idempotent über `reportId`, Transaktion (Report, Stammdaten, Key-Historie, Server-ID-Historie, Laufzeitvorschlag)
-- [ ] `GET /ping`
-- [ ] Rate-Limiting (pro IP und Token), `429` mit `Retry-After`
-- [ ] Einheitliche Fehlerantworten (JSON), kein Stacktrace nach außen
-- [ ] Tests: Auth (fehlend/falsch/widerrufen/abgelaufen), Validierung, Idempotenz, Key-Wechsel, Server-ID-Wechsel, Laufzeitvorschlag, Rate-Limit
+- [x] Token-Bibliothek: Erzeugung (Präfix `plx_e_`/`plx_h_`), SHA-256-Hash, Prüfung, Widerruf, `lastUsedAt`
+- [x] `POST /enroll`: Enrollment-Token prüfen (Ablauf, Nutzungen), Host anlegen oder Neuinstallation erkennen, Host-Token ausgeben, optionale Kunden-/Standort-Zuordnung
+- [x] `POST /report`: zod-Schema (alle Felder nullable), idempotent über `reportId`, Transaktion (Report, Stammdaten, Key-Historie, Server-ID-Historie, Laufzeitvorschlag)
+- [x] `GET /ping`
+- [x] Rate-Limiting (pro IP und Token), `429` mit `Retry-After`
+- [x] Einheitliche Fehlerantworten (JSON), kein Stacktrace nach außen
+- [x] Tests: Auth (fehlend/falsch/widerrufen/abgelaufen), Validierung, Idempotenz, Key-Wechsel, Server-ID-Wechsel, Laufzeitvorschlag, Rate-Limit
 
 ## Akzeptanzkriterien
-- [ ] Report mit ausschließlich `null`-Feldern (außer Pflicht-Metadaten) wird angenommen
-- [ ] Tokens liegen nur gehasht in der DB
-- [ ] UI-Session-Cookies werden von der Agent-API ignoriert
-- [ ] Alle Tests grün
+- [x] Report mit ausschließlich `null`-Feldern (außer Pflicht-Metadaten) wird angenommen
+- [x] Tokens liegen nur gehasht in der DB
+- [x] UI-Session-Cookies werden von der Agent-API ignoriert
+- [x] Alle Tests grün
 
 ## Abhängigkeiten
 #003
 
 ## Notizen / Entscheidungen
+- Endpunkte: `POST /api/agent/v1/enroll`, `POST /api/agent/v1/report`, `GET /api/agent/v1/ping`.
+- Antworten enthalten `agentVersion`, damit der Agent ein Update erkennen kann (#005).
+- Nachgesendete ältere Reports werden gespeichert, überschreiben den aktuellen Hoststand aber nicht.
+- Ein Report mit neuem `nextduedate` legt automatisch eine Laufzeit im Status VORSCHLAG an.
+- Die Auslieferung von `install.sh` und `agent.sh` gehört zu #005.

docs/issues/README.md

@@ -7,8 +7,8 @@ Details und Architektur: [../architektur.md](../architektur.md). Zeiten werden a
 | [#001](001-projekt-setup.md) | Projekt-Setup | erledigt | v0.1.0 | 3 h | 0 h 08 min |
 | [#002](002-prototyp.md) | Klickbarer Prototyp | erledigt | v0.1.0 | 8 h | 0 h 20 min |
 | [#003](003-datenmodell.md) | Datenmodell und Migrationen | erledigt | v0.1.0 | 5 h | 0 h 25 min |
-| [#004](004-agent-api.md) | Agent-API | in Arbeit | v0.1.0 | 6 h | – |
-| [#005](005-agent-skript.md) | Agent-Skript | offen | v0.2.0 | 8 h | – |
+| [#004](004-agent-api.md) | Agent-API | erledigt | v0.1.0 | 6 h | 0 h 20 min |
+| [#005](005-agent-skript.md) | Agent-Skript | in Arbeit | v0.2.0 | 8 h | – |
 | [#006](006-kunden-hostzuweisung.md) | Kunden, Standorte und Hostzuweisung | offen | v0.3.0 | 6 h | – |
 | [#007](007-hosts-detailansichten.md) | Host-Tabelle, Suche und Detailansichten | offen | v0.4.0 | 8 h | – |
 | [#008](008-laufzeiten-rechnungen.md) | Laufzeiten und Rechnungen | offen | v0.5.0 | 10 h | – |
@@ -20,4 +20,4 @@ Details und Architektur: [../architektur.md](../architektur.md). Zeiten werden a
 | [#014](014-deployment.md) | Deployment und Dokumentation | offen | v0.10.0 | 8 h | – |
 | [#015](015-feinschliff-v1.md) | Feinschliff für 1.0 | offen | v1.0.0 | 6 h | – |
 | [#016](016-anleitung-screenshots.md) | Benutzerhandbuch mit Screenshots | offen | v0.10.0 | 5 h | – |
-| | **Summe** | | | **106 h** | **0 h 53 min** |
+| | **Summe** | | | **106 h** | **1 h 13 min** |