fix(security, core): Auth-Pflicht für Ingest-APIs, 500er-Ursachen beheben, Agenten-Workflow

Sicherheit - install_db.php war ohne Authentifizierung erreichbar und setzte bei jedem Aufruf das Admin-Passwort auf einen fest im Code stehenden Wert zurück. Jetzt Auth-Pflicht; ein Konto wird nur bei leerer Benutzertabelle angelegt. - Stored XSS im Bugtracker-Detail-Modal: Titel, Beschreibung, Fehlermeldung, Stacktrace und Kommentare gingen ungefiltert durch innerHTML. - report.php, projects.php und das Veröffentlichen von Releases verlangen jetzt zwingend ein Token. Publish war zuvor völlig ungeschützt. - CSRF-Token in allen Formularen, Session-Regenerierung nach Login, Drosselung fehlgeschlagener Anmeldeversuche. - Zugangsdaten aus der Versionskontrolle entfernt (Serverdaten.txt, config.php, .htpasswd, deploy_config.json). Historie enthält sie weiterhin, Rotation erforderlich (siehe docs/UPGRADE.md). - Token-Validierung nur noch über SHA-256-Hash; expires_at wird ausgewertet. Behobene 500er - Audit::log() war in index.php weder eingebunden noch importiert. Jeder Klick auf "Aktivierung freigeben" endete in einem Fatal Error. - Derselbe benannte PDO-Platzhalter mehrfach je Statement (:id in revokeToken/deleteToken, :q siebenfach in der Volltextsuche). Bei EMULATE_PREPARES=false ist das nicht zulässig und warf HY093. - Migration 005 nutzte dynamisches SQL, dessen Semikolons in String-Literalen vom alten explode(';')-Installer als Statement-Ende gelesen wurden. Sie schlug still fehl, wodurch push_id/target_agent/tags dauerhaft fehlten. - Monitor-Umbenennung ohne Transaktion, verschachtelte Transaktionen im RateLimiter. Funktionale Korrekturen - Der Watchdog-Evaluator fehlte vollständig: Monitor-Zustände änderten sich nur beim Eintreffen eines Heartbeats, ein ausgefallenes System blieb dauerhaft "up". Erster Lauf auf dem Produktivsystem: 7 von 10 Monitoren waren tatsächlich seit über einem Tag nicht erreichbar. - Das Feld "os" fehlte im Monitor-Dialog, wurde aber gespeichert und löschte damit bei jedem Speichern das Betriebssystem. - Der Resolve-Dialog existierte im HTML nicht; der Button war funktionslos. - Versionsvergleich erfolgte lexikografisch, wodurch 1.9.0 als neuer galt als 1.10.0. - Schreiboperationen meldeten Erfolg auch für nicht existierende IDs. - Post/Redirect/Get gegen doppelte Einträge beim Neuladen. Neue Struktur - src/bootstrap.php mit PSR-4-Autoloader ersetzt die require-Ketten. - Core: Config, Http, Csrf, ApiAuth, Logger, Migrator, ErrorReporter. - Migrator mit zeichenweisem SQL-Parser, dc_migrations und Baseline-Verfahren, damit bestehende Installationen keine Beispieldaten zurückbekommen. Agenten-Workflow - Claim/Lease: Items werden exklusiv übernommen, damit nicht zwei Agenten am selben Problem arbeiten. action=next holt und reserviert in einem Zug. - Idempotenz über client_ref, Deduplizierung auch für Feature Requests, Erkennung von Regressionen, automatische Eskalation des Schweregrads. - Strukturierter Code-Kontext (repo_url, commit_sha, file_path, line_no). - Delta-Abfragen über updated_since, Pagination, Bulk-Update. - Beim Veröffentlichen eines Releases schließen sich Items mit passendem resolved_in_build selbst. - Ausgehende Webhooks mit HMAC-Signatur, /api/health, /api/openapi.json. - Unbehandelte Fehler meldet die Plattform in ihren eigenen Bugtracker. WebUI - Serverseitige Filterung mit Pagination statt Rendern aller Datensätze. - Migrations-Schranke, Evaluator-Warnung, Übersicht aktiver Agenten. Zeitstempel liegen in der Datenbank durchgängig in UTC und werden für die Anzeige in die App-Zeitzone umgerechnet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-07 16:17:36 +02:00
parent a21536f495
commit e7fbc85db4
59 changed files with 8506 additions and 2410 deletions
@@ -1,42 +1,117 @@
-# 📋 Minimal Agent Prompt Template (For CLAUDE.md / AGENTS.md / CursorRules)
+# Agent-Prompt-Vorlage

-Copy & paste the following snippet into your agent system prompts or repository `CLAUDE.md` / `.cursorrules`:
+Diesen Abschnitt in `CLAUDE.md`, `AGENTS.md` oder `.cursorrules` des jeweiligen
+Projekts einfügen.
+
+---

 ```markdown
-## 🐛 Central Bugtracker & Feature Logging Directive
+## Zentraler Bugtracker — Deployment Center

-As an AI developer agent, you MUST track all unhandled errors, stack traces, planned features, and refactoring ideas in the central **Deployment Center Bugtracker**.
+Erfasse unbehandelte Fehler, geplante Verbesserungen und Ideen im zentralen
+Deployment Center. Basis-URL: `https://dc.mhdf.de`

-### 1. Monitored Projects & Discovery
-Before reporting, check monitored projects via API or use the known project slug:
- **Projects Discovery API**: `GET https://dc.mhdf.de/api/bugtracker/v1/projects.php`
- **Known Slugs**: `deploymentcenter`, `myapp`, `polytrader`, `predictalytics`.
-*Note: If you discover a bug or issue in the Deployment Center code itself while working elsewhere, report it under `project_slug: "deploymentcenter"`.*
+### Zugang
+Token steht in der Umgebungsvariable `DC_TOKEN`.
+Header: `Authorization: Bearer $DC_TOKEN`

-### 2. Reporting Bugs & Ideas
-Submit reports via HTTP POST to: `https://dc.mhdf.de/api/bugtracker/v1/report.php`
-Header: `Authorization: Bearer <YOUR_AGENT_TOKEN>` (or `X-Agent-Token: <YOUR_AGENT_TOKEN>`)
+Die vollständige Schnittstellenbeschreibung liegt maschinenlesbar unter
+`GET /api/openapi.json`, das Handbuch unter `/docs/`.
+
+### Projekt bestimmen
+`GET /api/bugtracker/v1/projects` liefert alle Slugs.
+Bekannt: `deploymentcenter`, `myapp`, `polytrader`, `predictalytics`.
+Fällt dir ein Fehler im Deployment Center selbst auf, melde ihn unter
+`deploymentcenter`.
+
+### Etwas melden
+`POST /api/bugtracker/v1/report`

 ```json
 {
-  "project_slug": "deploymentcenter",
+  "project_slug": "myapp",
  "type": "bug",
-  "title": "Short descriptive title of the error or feature",
-  "description": "Condition or context under which it occurred",
-  "error_message": "Exact exception message",
-  "stack_trace": "Complete stack trace snippet",
+  "title": "Kurze, aussagekräftige Zusammenfassung",
+  "description": "Unter welchen Bedingungen tritt es auf?",
+  "error_message": "Exakte Fehlermeldung",
+  "stack_trace": "Vollständiger Stacktrace",
  "severity": "high",
-  "push_id": "push_wf_8912",
-  "created_by": "agent:your-name"
+  "environment": "production",
+  "build_version": "v1.4.2",
+  "repo_url": "https://git.example.com/me/myapp.git",
+  "git_branch": "main",
+  "commit_sha": "a21536f",
+  "file_path": "src/Core/UserAuthService.cs",
+  "line_no": 42,
+  "client_ref": "eindeutige-id-dieses-laufs"
 }
 ```

- **Severities**:
-  - `idea`: 💡 Quick reminder / thought for later
-  - `wishlist`: ⭐ Backlog feature request
-  - `low` / `medium` / `high` / `critical`: Standard bug severities
+**Setze immer `client_ref`** — ein wiederholter Aufruf mit demselben Wert legt
+kein Duplikat an. Gib nach Möglichkeit `file_path` und `line_no` an; das spart
+dem nächsten Agenten das Parsen des Stacktrace.
+
+Schweregrade: `idea` (Gedanke für später), `wishlist` (Backlog),
+`low`, `medium`, `high`, `critical`.
+
+### Arbeit übernehmen
+Bevor du an einem Item arbeitest, übernimm es — sonst arbeiten zwei Agenten
+parallel am selben Problem:

-### 3. Full API Documentation On-Demand
-If you need complete API details, token provisioning instructions, or cURL/Python examples, read:
-📄 **Documentation URL**: `https://dc.mhdf.de/docs/bugtracker.md`
+```
+POST /api/bugtracker/v1/manage?action=next
+Body: {"project_slug": "myapp", "limit": 1}
+```
+
+Antwortet der Server mit `409 already_claimed`, nimm das nächste Item.
+
+### Fortschritt festhalten
+```
+POST /api/bugtracker/v1/manage?action=comment&id=<ID>
+Body: {"comment": "Was du herausgefunden hast", "action_taken": "investigated"}
+```
+
+`action_taken`: `investigated`, `fix_proposed`, `pr_opened`, `needs_human`,
+`blocked`.
+
+### Abschließen
+```
+POST /api/bugtracker/v1/manage?action=resolve&id=<ID>
+Body: {"resolved_in_build": "v1.4.3", "resolution_notes": "Was geändert wurde"}
+```
+
+Kommst du nicht weiter, gib das Item zurück statt es blockieren zu lassen:
+```
+POST /api/bugtracker/v1/manage?action=release&id=<ID>
+Body: {"note": "Grund"}
+```
+
+### Release melden
+Nach einem Release schließen sich Items mit passendem `resolved_in_build`
+automatisch:
+```
+POST /api/updateservice/v1/publish
+Body: {"product_slug": "myapp", "version": "1.4.3",
+       "download_url": "...", "sha256_hash": "...", "git_commit": "..."}
+```
+
+### Fehlerbehandlung
+Antworten haben die Form `{"status":"error","error":{"code":"…"}}`.
+Reagiere auf `code`, nicht auf den Text:
+- `401 unauthorized` — Token prüfen, nicht wiederholen
+- `409 already_claimed` — nächstes Item nehmen
+- `429 rate_limited` — Intervall verdoppeln, später erneut
+```
+
+---
+
+## Kurzfassung für knappe Prompt-Budgets
+
+```markdown
+Melde Fehler und Ideen an https://dc.mhdf.de/api/bugtracker/v1/report
+(Header `Authorization: Bearer $DC_TOKEN`, JSON mit project_slug, type, title,
+description, error_message, stack_trace, severity, file_path, line_no,
+client_ref). Vor der Arbeit an einem Item: POST .../manage?action=next zum
+Übernehmen. Danach ?action=resolve mit resolved_in_build.
+Vollständige Beschreibung: https://dc.mhdf.de/api/openapi.json
 ```
@@ -1,5 +1,13 @@
 # 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API

+> **⚠️ Geändert in Version 2.0** — `POST /api/bugtracker/v1/report` und
+> `GET /api/bugtracker/v1/projects` verlangen jetzt zwingend ein Token mit dem
+> passenden Scope; Aufrufe ohne Token liefern `401 unauthorized`. Das
+> Antwortformat wurde vereinheitlicht. Die aktuelle, vollständige Beschreibung
+> steht im **[Agenten-Handbuch](../public/docs/bugtracker.md)** und unter
+> `/api/openapi.json`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
+
+
 This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.

 ---
@@ -1,5 +1,13 @@
 # Deploymentcenter — Lizenzsystem Integration für KI-Agenten

+> **⚠️ Geändert in Version 2.0** — `/api/license/v1/validate` bleibt unverändert
+> und ohne Token erreichbar. `/api/license/v1/deactivate` verlangt weiterhin
+> Authentifizierung, allerdings mit dem **neu erzeugten** `shared_key`: der alte
+> Wert lag im Repository und wurde ersetzt. Die Signatur der Offline-Lizenzdateien
+> ist jetzt ein ehrlich benanntes HMAC-SHA256 statt der irreführenden Bezeichnung
+> `ED25519_SIG_`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
+
+
 > **Zielgruppe**: KI-Agenten & Softwareentwickler  
 > **Gültig ab**: Hardware-ID v2 Specification (August 2026)  
 > **Plattformen**: Windows, Linux (inkl. systemd Services & Docker-Container), macOS
@@ -1,18 +1,90 @@
-# Deploymentcenter — AI Agent Integration Guides
+# Deploymentcenter — Entwickler- und Agenten-Dokumentation

-Willkommen in der Entwickler- und Agenten-Dokumentation von **Deploymentcenter**. 
+Zentrale Plattform für Lizenzverwaltung, Software-Updates, Infrastruktur-
+Monitoring und einen Bugtracker, den Coding-Agenten selbständig bedienen.

-Diese Anleitungen sind speziell dafür strukturiert, KI-Agenten und Entwicklern klare, praxiserprobte Vorgaben zur Integration unserer zentralen Dienste bereitzustellen:
+---

- **[Lizenzsystem-Integration (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)**: Hardware-Anbindung, Lizenzschlüssel-Validierung, verschlüsselter Offline-Cache (`LLS2`), CLI-Befehle und Multi-Plattform-Betrieb (Windows & Linux / Docker).
- **[Watchdog-Integration (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)**: Überwachung von Anwendungen, Diensten und Infrastruktur-Knoten via Ping-API, Agent-Tokens und automatisiertem Heartbeat.
+## Zuerst lesen
+
+| Dokument | Wofür |
+|---|---|
+| **[UPGRADE.md](./UPGRADE.md)** | **Ablaufplan für die Umstellung auf 2.0.** Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron. |
+| [Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md) | Textbaustein für `CLAUDE.md` / `AGENTS.md` eines Projekts |
+| [Agenten-Handbuch](../public/docs/bugtracker.md) | Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter `/docs/` |
+
+## Modul-Handbücher
+
+- **[Lizenzsystem (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)** — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
+- **[Watchdog (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)** — Überwachung von Anwendungen, Diensten und Infrastruktur
+- **[UpdateService](./UPDATESERVICE_INTEGRATION_GUIDE.md)** — Release-Verteilung und Update-Prüfung
+- **[Bugtracker](./BUGTRACKER_INTEGRATION_GUIDE.md)** — Anbindung aus Anwendungen heraus

 ---

 ## Modulübersicht

-| Modul | Hauptaufgabe | Endpunkte | .NET Client SDK |
-| :--- | :--- | :--- | :--- |
-| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache | `/api/license/v1/validate`<br>`/api/license/v1/deactivate` | `Deploymentcenter.Client` (`LicenseClient`, `HardwareId`) |
-| **Watchdog** | Heartbeat-Monitoring, Status & Alerting | `/api/watchdog/v1/ping` | `HttpClient` + Header `X-Agent-Token` |
-| **UpdateService** | Automatic Software Release Checks | `/api/updateservice/v1/check` | `HttpClient` GET Request |
+| Modul | Aufgabe | Endpunkte | Authentifizierung |
+|---|---|---|---|
+| **Bugtracker** | Fehler, Feature Requests und Ideen; Agenten-Workflow mit Claim/Lease | `/api/bugtracker/v1/report`<br>`/api/bugtracker/v1/projects`<br>`/api/bugtracker/v1/manage` | Token mit `bugtracker:*` |
+| **UpdateService** | Release-Verteilung, semantischer Versionsvergleich | `/api/updateservice/v1/check`<br>`/api/updateservice/v1/publish` | Lesen offen, Publish braucht `updateservice:publish` |
+| **Watchdog** | Heartbeat-Monitoring, Zustandsbewertung, Alarmierung | `/api/watchdog/v1/ping`<br>`/api/watchdog/v1/evaluate` | Token mit `watchdog:ping` |
+| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache | `/api/license/v1/validate`<br>`/api/license/v1/deactivate` | Validierung offen, Deaktivierung authentifiziert |
+| **Tokens** | Selbst-Provisionierung von Sub-Tokens | `/api/tokens/v1/provision` | Master-Token |
+| **System** | Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung | `/api/health`<br>`/api/openapi.json` | Health optional, OpenAPI offen |
+
+---
+
+## Schnittstelle maschinenlesbar
+
+```
+GET https://dc.mhdf.de/api/openapi.json
+```
+
+Ein Agent kann sich daran selbst orientieren — der früher fest im WebUI
+hinterlegte Textblock entfällt damit.
+
+---
+
+## Antwortformat
+
+Alle JSON-Endpunkte antworten einheitlich:
+
+```json
+{ "status": "success", "…": "…" }
+```
+
+```json
+{ "status": "error", "error": { "code": "already_claimed", "message": "…" } }
+```
+
+Der `code` ist stabil und für Programme gedacht; die `message` richtet sich an
+Menschen und kann sich ändern.
+
+---
+
+## Betrieb
+
+| Aufgabe | Befehl |
+|---|---|
+| Deployment | `python scripts/deploy.py` |
+| Migration | `php public/install_db.php` oder WebUI → System → DB-Migration |
+| Evaluator (Cron, minütlich) | `curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate` |
+| Zustand prüfen | `curl https://dc.mhdf.de/api/health` |
+| Logs | `var/log/dc-<datum>.log` auf dem Server |
+
+## Aufbau
+
+```
+config/    Zugangsdaten (nicht versioniert), Vorlage in config.example.php
+src/       Anwendungscode, PSR-4 unter dem Namensraum Deploymentcenter\
+  Core/      Bootstrap, Konfiguration, DB, Auth, CSRF, HTTP, Tokens, Migrator
+  Modules/   Bugtracker, License, UpdateService, Watchdog, Notify
+public/    Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation
+sql/       Schema und Migrationen (fortlaufend nummeriert)
+var/log/   Laufzeitprotokolle
+scripts/   Deployment
+```
+
+Neue Klassen werden automatisch geladen, sobald sie dem Namensraum-Pfad
+entsprechen — eine `require`-Zeile ist nicht mehr nötig.
@@ -1,5 +1,12 @@
 # Deploymentcenter — UpdateService Integration & Deployment Guide

+> **⚠️ Geändert in Version 2.0** — Das Veröffentlichen eines Releases läuft jetzt
+> über `POST /api/updateservice/v1/publish` und verlangt ein Token mit dem Scope
+> `updateservice:publish` (zuvor völlig ungeschützt). Der Versionsvergleich folgt
+> jetzt der semantischen Versionsordnung, `1.10.0` gilt also korrekt als neuer
+> als `1.9.0`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
+
+
 Das **UpdateService-Modul** des Deploymentcenters bietet ein unternehmensweites, leichtgewichtiges Update-, Rollback- und Reparatur-Schema auf Basis eines LEMP-Stacks (Nginx Static Files + PHP API).

 ---
@@ -0,0 +1,196 @@
+# Umstellung auf Version 2.0 — Ablaufplan
+
+Diese Fassung enthält Sicherheitskorrekturen, die das Verhalten der
+Schnittstellen ändern. Bitte in dieser Reihenfolge vorgehen.
+
+---
+
+## 1. Vor dem Deployment: Zugangsdaten wechseln
+
+`Serverdaten.txt`, `config/config.php`, `config/.htpasswd` und
+`scripts/deploy_config.json` lagen im Git-Repository. Sie sind jetzt per
+`.gitignore` ausgeschlossen und aus dem Index entfernt — **die Git-Historie
+enthält sie aber weiterhin**. Alle betroffenen Zugangsdaten sind daher als
+kompromittiert zu behandeln:
+
+- [ ] MySQL-Passwort ändern, danach in `config/config.php` eintragen
+- [ ] FTP-Passwort ändern, danach in `scripts/deploy_config.json` eintragen
+- [ ] `.htpasswd`-Passwort für `deploy` neu setzen
+- [ ] Git-Token `eb429575…` widerrufen und neu ausstellen
+- [ ] Admin-Passwort im WebUI ändern (die alte Fassung setzte es bei jedem
+      Aufruf von `install_db.php` auf `Admin1337!` zurück — jeder im Internet
+      konnte das auslösen)
+
+Wenn die Historie bereinigt werden soll, geht das mit
+[`git filter-repo`](https://github.com/newren/git-filter-repo). Das schreibt
+alle Commit-Hashes um; bei einem Repository mit mehreren Nutzern vorher abstimmen.
+
+---
+
+## 2. Konfiguration ergänzen
+
+`config/config.php` braucht drei neue Schlüssel unter `security`. Die
+mitgelieferte Datei enthält bereits erzeugte Werte; für eine neue Installation:
+
+```bash
+cp config/config.example.php config/config.php
+openssl rand -hex 32   # je einmal für shared_key, webhook_key, license_key
+```
+
+| Schlüssel | Zweck |
+|---|---|
+| `security.shared_key` | Server-zu-Server-Aufrufe: Evaluator-Cron, Migration, Deaktivierung |
+| `security.webhook_key` | HMAC-Signatur ausgehender Webhooks |
+| `security.license_key` | Signatur der Offline-Lizenzdateien (`.lic`) |
+| `app.debug` | Auf Produktivsystemen `false` — steuert, ob Exception-Texte ausgeliefert werden |
+
+> Der bisherige `shared_key` (`DC_MASTER_SECURE_TOKEN_2026_x98f`) stand im
+> Repository und wurde ersetzt. Wer ihn irgendwo eingetragen hat — etwa für
+> `/api/license/v1/deactivate` — muss den neuen Wert nachziehen.
+
+---
+
+## 3. Deployment
+
+```bash
+python scripts/deploy.py
+```
+
+Das Skript überträgt unter anderem die neuen Verzeichnisse `var/` (Logs) und
+die zusätzlichen `.htaccess`-Dateien in `config/`, `src/` und `sql/`.
+
+---
+
+## 4. Migration ausführen
+
+Im WebUI anmelden, dann **System → DB-Migration → Migration jetzt ausführen**.
+
+Alternativ über die Kommandozeile:
+
+```bash
+php public/install_db.php
+```
+
+Oder mit dem Shared Key:
+
+```bash
+curl -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/install_db.php
+```
+
+Die Migration ist additiv und legt an bzw. korrigiert:
+
+- `dc_migrations` — vermerkt angewendete Versionen, damit nichts doppelt läuft
+- `dc_login_attempts` — Drosselung fehlgeschlagener Anmeldungen
+- `dc_webhooks` — ausgehende Benachrichtigungen
+- Bugtracker: Claim/Lease, `client_ref`, `dedup_key`, Code-Kontextfelder, Indizes
+- Watchdog: `last_state_change_utc`, `down_since_utc`, Zustand `unknown`
+- **Reparatur von Migration 005** — deren Spalten (`push_id`, `target_agent`,
+  `tags`) fehlten bisher auf Datenbanken, die aus Migration 004 stammen. Die
+  alte Fassung nutzte dynamisches SQL, dessen Semikolons in String-Literalen
+  vom damaligen Installer als Statement-Ende gelesen wurden; die Fehler wurden
+  stillschweigend verschluckt.
+- **Reparatur der Token-Hashes** — die Validierung vergleicht jetzt nur noch
+  den SHA-256-Hash. Die geseedeten Beispiel-Tokens trugen Hashes, die nicht zu
+  ihrem Klartext passten; sie werden korrigiert, damit bestehende Tokens
+  weiterhin funktionieren.
+
+---
+
+## 5. Cron für den Watchdog-Evaluator einrichten
+
+**Ohne diesen Schritt sind die Monitor-Zustände wertlos.** Der Evaluator fehlte
+bisher vollständig — der Zustand änderte sich nur beim Eintreffen eines
+Heartbeats, ein ausgefallener Server blieb dauerhaft grün.
+
+```bash
+* * * * * curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate > /dev/null
+```
+
+Solange der Job fehlt, zeigt das WebUI oben einen Warnhinweis mit einer
+Schaltfläche für einen einmaligen Lauf.
+
+---
+
+## 6. Agenten-Tokens ausstellen
+
+Die Ingest-Endpunkte verlangen jetzt zwingend ein Token.
+
+1. WebUI → **Token-Verwaltung → Master-Token erstellen**
+2. Scopes wählen (für einen Coding-Agenten: `bugtracker:report`,
+   `bugtracker:read`, `bugtracker:manage`)
+3. Master-Token einmalig kopieren und auf dem Agenten-Rechner als `DC_TOKEN`
+   hinterlegen — oder den Agenten per `/api/tokens/v1/provision` ein eigenes
+   Sub-Token ziehen lassen
+
+---
+
+## 7. Bestehende Integrationen anpassen
+
+| Betroffen | Was zu tun ist |
+|---|---|
+| Aufrufe von `/api/bugtracker/v1/report` ohne Token | Token-Header ergänzen |
+| Aufrufe von `/api/bugtracker/v1/projects` ohne Token | Token-Header ergänzen |
+| Skripte, die Releases veröffentlichen | Token mit `updateservice:publish` ergänzen |
+| Auswertung der Antworten | Neues Format: `{"status":"success",…}` bzw. `{"status":"error","error":{"code":…}}` |
+| Watchdog-Agenten mit `wd_live_…`-Token | Laufen unverändert weiter |
+| Clients, die `/api/updateservice/v1/check` aufrufen | Unverändert, weiterhin ohne Token |
+| Clients, die `/api/license/v1/validate` aufrufen | Unverändert, weiterhin ohne Token |
+
+---
+
+## 8. Zeitzonen
+
+Datenbankzeitstempel liegen jetzt durchgängig in **UTC**; das WebUI rechnet für
+die Anzeige in `app.timezone` (Europe/Berlin) um. Vorhandene Datensätze wurden
+in Serverzeit geschrieben und erscheinen daher einmalig um den Zeitzonenversatz
+verschoben. Für Monitoring-Daten ist das ohne Bedeutung, für den Audit-Log
+gegebenenfalls beachten.
+
+---
+
+## 9. Prüfen, ob alles läuft
+
+```bash
+curl https://dc.mhdf.de/api/health -H "Authorization: Bearer <SHARED_KEY>"
+```
+
+Erwartet wird `"healthy": true`, eine leere `schema.pending`-Liste und ein
+`checks.evaluator.ok` von `true`.
+
+Zusätzlich stichprobenartig im WebUI prüfen:
+
+- [ ] Anmeldung funktioniert
+- [ ] Projekt anlegen und wieder löschen
+- [ ] Monitor bearbeiten — das Feld **Betriebssystem** bleibt nach dem
+      Speichern erhalten (wurde zuvor bei jedem Speichern geleert)
+- [ ] Bugtracker: „🔍 Details" öffnet den Dialog, „✔" öffnet den
+      Lösen-Dialog (dessen HTML fehlte bisher komplett)
+- [ ] Token widerrufen und löschen (warf zuvor `HY093`)
+- [ ] Lizenz-Aktivierung freigeben (warf zuvor `Class "Audit" not found`)
+- [ ] Nach dem Speichern F5 drücken — es entsteht kein zweiter Eintrag mehr
+
+---
+
+## 10. Optional: Webhooks
+
+Ereignisgesteuerte Benachrichtigung statt Polling. Ziel direkt in der Datenbank
+eintragen:
+
+```sql
+INSERT INTO dc_webhooks (name, url, project_slug, events, secret, enabled)
+VALUES ('Telegram Alarm', 'https://n8n.example.com/webhook/dc',
+        NULL, 'bug.critical,monitor.down', 'geheimnis', 1);
+```
+
+Verfügbare Ereignisse: `bug.created`, `bug.critical`, `bug.resolved`,
+`feature.created`, `monitor.down`, `monitor.recovered`, `release.published`,
+oder `*` für alle.
+
+Jede Zustellung trägt eine Signatur:
+
+```
+X-DC-Timestamp: 1754563200
+X-DC-Signature: sha256=<hex(hmac_sha256(secret, timestamp + "." + body))>
+```
+
+Nach 20 Fehlversuchen in Folge deaktiviert sich ein Webhook selbst.
@@ -1,5 +1,14 @@
 # Deploymentcenter — Watchdog Integration für KI-Agenten

+> **⚠️ Geändert in Version 2.0** — Neu ist der Evaluator unter
+> `GET /api/watchdog/v1/evaluate`, der per Cron minütlich laufen muss. Ohne ihn
+> ändert sich der Zustand eines Monitors nur beim Eintreffen eines Heartbeats,
+> ein ausgefallenes System bliebe dauerhaft `up`. `expected_interval_sec`,
+> `is_muted` und `suppress_until_utc` werden jetzt ausgewertet. Neben den
+> bisherigen `wd_live_`-Tokens werden auch zentrale Tokens mit dem Scope
+> `watchdog:ping` akzeptiert. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
+
+
 > **Zielgruppe**: KI-Agenten & Softwareentwickler  
 > **Zweck**: Einbindung von Heartbeat-Monitoring, Statusmeldungen und Telemetrie in Anwendungen & Serverdienste.