From b892259f69aaa85820c0bc8157c22af937658e6e Mon Sep 17 00:00:00 2001 From: "matthias.lotz" Date: Tue, 11 Nov 2025 21:29:19 +0100 Subject: [PATCH] docs(phase2): Update documentation for Phase 2 Backend (Task 19) - Updated FEATURE_PLAN-social-media.md: * Phase 2 Backend status: 100% complete (Tasks 2-11) * Added Phase 2 backend implementation results * 4 new commits documented (c18c258, 2d49f0b, 0dce5fd, 0f77db6) * New files: management.js, rateLimiter.js, auditLog.js, ManagementAuditLogRepository.js, Migration 007 * All 8 Management Portal APIs documented with test results * Security features: Rate-limiting, brute-force protection, audit logging * Frontend status: Tasks 12-18 pending - Updated README.md: * Added Phase 2 Backend features to 'Latest Features' section * Documented all Management Portal API endpoints * Documented Management Audit-Log API endpoints * Added security features documentation * Extended database schema with management_audit_log table Phase 2 Backend: 11/20 tasks complete, ready for frontend implementation --- README.md | 64 +++++++++- docs/FEATURE_PLAN-social-media.md | 199 ++++++++++++++++++++++++++---- 2 files changed, 234 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 3ee09b7..27c4419 100644 --- a/README.md +++ b/README.md @@ -21,14 +21,23 @@ A self-hosted image uploader with multi-image upload capabilities and automatic This project extends the original [Image-Uploader by vallezw](https://github.com/vallezw/Image-Uploader) with enhanced multi-upload and slideshow capabilities. ### 🆕 Latest Features (November 2025) -- **� Social Media Consent Management** (Phase 1 Complete - Nov 9-10): +- **🔐 Social Media Consent Management** (Phase 1 Complete - Nov 9-10): - GDPR-compliant consent system for image usage - Mandatory workshop display consent (no upload without approval) - Optional per-platform consents (Facebook, Instagram, TikTok) - Consent badges and filtering in moderation panel - CSV/JSON export for legal documentation - Group ID tracking for consent withdrawal requests -- **�🚀 Slideshow Optimization**: Intelligent image preloading eliminates loading delays and duplicate images +- **🔑 Self-Service Management Portal** (Phase 2 Backend Complete - Nov 11): + - Secure UUID-based management tokens for user self-service + - Token-based API for consent revocation and metadata editing + - Add/delete images after upload (with moderation re-approval) + - Complete group deletion with audit trail + - IP-based rate limiting (10 requests/hour) + - Brute-force protection (20 failed attempts → 24h ban) + - Management audit log for security tracking + - Frontend portal coming soon (Tasks 12-18) +- **� Slideshow Optimization**: Intelligent image preloading eliminates loading delays and duplicate images - **📅 Chronological Display**: Slideshows now play in chronological order (year → upload date) - **Automatic Cleanup**: Unapproved groups are automatically deleted after 7 days - **Deletion Log**: Complete audit trail with statistics (groups, images, storage freed) @@ -298,6 +307,35 @@ CREATE TABLE group_social_media_consents ( consented BOOLEAN NOT NULL DEFAULT 0, consent_timestamp DATETIME NOT NULL, revoked BOOLEAN DEFAULT 0, -- For Phase 2: Consent revocation + revoked_timestamp DATETIME, -- When consent was revoked + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (group_id) REFERENCES groups(group_id) ON DELETE CASCADE, + FOREIGN KEY (platform_id) REFERENCES social_media_platforms(id) ON DELETE CASCADE, + UNIQUE(group_id, platform_id) +); + +-- Management audit log (Phase 2) +CREATE TABLE management_audit_log ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + group_id TEXT, + management_token TEXT, -- First 8 characters only (masked) + action TEXT NOT NULL, -- validate_token, revoke_consent, edit_metadata, add_images, delete_image, delete_group + success BOOLEAN NOT NULL, + error_message TEXT, + ip_address TEXT, + user_agent TEXT, + request_data TEXT, -- JSON of request body + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (group_id) REFERENCES groups(group_id) ON DELETE SET NULL +); + +-- Indexes for performance +CREATE INDEX IF NOT EXISTS idx_audit_group_id ON management_audit_log(group_id); +CREATE INDEX IF NOT EXISTS idx_audit_action ON management_audit_log(action); +CREATE INDEX IF NOT EXISTS idx_audit_success ON management_audit_log(success); +CREATE INDEX IF NOT EXISTS idx_audit_created_at ON management_audit_log(created_at); +CREATE INDEX IF NOT EXISTS idx_audit_ip_address ON management_audit_log(ip_address); revoked_timestamp DATETIME, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, @@ -417,6 +455,28 @@ src - `GET /api/admin/groups/by-consent` - Filter groups by consent status (query params: `?workshopConsent=true&platform=facebook`) - `GET /api/admin/consents/export` - Export all consent data as CSV/JSON +### User Self-Service Management Portal (Phase 2 - Backend Complete) + +**Management Portal APIs** (Token-based authentication): +- `GET /api/manage/:token` - Validate management token and retrieve group data +- `PUT /api/manage/:token/consents` - Revoke or restore consents (workshop & social media) +- `PUT /api/manage/:token/metadata` - Edit group title and description (resets approval status) +- `POST /api/manage/:token/images` - Add new images to existing group (max 50 total, resets approval) +- `DELETE /api/manage/:token/images/:imageId` - Delete individual image (prevents deleting last image) +- `DELETE /api/manage/:token` - Delete entire group with all images and data + +**Management Audit Log APIs** (Admin access only): +- `GET /api/admin/management-audit?limit=N` - Retrieve recent management actions (default: 10) +- `GET /api/admin/management-audit/stats` - Get statistics (total actions, success rate, unique IPs) +- `GET /api/admin/management-audit/group/:groupId` - Get audit log for specific group + +**Security Features**: +- IP-based rate limiting: 10 requests per hour per IP +- Brute-force protection: 20 failed token validations → 24-hour IP ban +- Complete audit trail: All management actions logged with IP, User-Agent, timestamp +- Token masking: Only first 8 characters stored in audit log for privacy +- Automatic file cleanup: Physical deletion of images when removed via API + ### Moderation Operations (Protected) - `GET /moderation/groups` - Get all groups pending moderation (includes consent info) diff --git a/docs/FEATURE_PLAN-social-media.md b/docs/FEATURE_PLAN-social-media.md index 6738be3..a45e3d9 100644 --- a/docs/FEATURE_PLAN-social-media.md +++ b/docs/FEATURE_PLAN-social-media.md @@ -5,9 +5,30 @@ **Feature**: Einwilligungsverwaltung für Bildveröffentlichung in Werkstatt und Social Media **Ziel**: Rechtskonforme Einholung und Verwaltung von Nutzerzustimmungen für die Anzeige von Bildern in der Werkstatt und Veröffentlichung auf Social Media Plattformen **Priorität**: High (Rechtliche Anforderung) -**Status**: ✅ Phase 1 komplett implementiert (9-10. November 2025) -**Branch**: `feature/SocialMedia` (11 Commits) -**Implementierungszeit**: 2 Tage (Backend, Frontend, Moderation komplett) +**Status**: ✅ Phase 1 komplett (9-10. Nov 2025) | ✅ Phase 2 Backend komplett (11. Nov 2025) +**API-Endpoints**: +- ✅ `GET /api/social-media/platforms` - Liste aktiver Social Media Plattformen +- ✅ `POST /api/groups/:groupId/consents` - Consents speichern +- ✅ `GET /api/groups/:groupId/consents` - Consents abrufen +- ✅ `GET /api/admin/groups/by-consent` - Gruppen nach Consent filtern +- ✅ `GET /api/admin/consents/export` - Consent-Daten exportieren (CSV/JSON) + +**Test-Ergebnisse (10. Nov 2025)**: +- ✅ Upload mit Consent: Funktioniert +- ✅ Upload ohne Werkstatt-Consent: Blockiert (400 Error) +- ✅ Filter "Alle Gruppen": 76 Gruppen +- ✅ Filter "Nur Werkstatt": 74 Gruppen +- ✅ Filter "Facebook": 2 Gruppen +- ✅ Export-Button: CSV-Download funktioniert +- ✅ ConsentBadges: Icons und Tooltips werden korrekt angezeigt +- ✅ Automatische Migration: Migration 005 & 006 beim Backend-Start angewendet +- ✅ GDPR-Konformität: 72 alte Gruppen mit display_in_workshop = 0 +- ✅ Social Media Plattformen: 3 Plattformen (Facebook, Instagram, TikTok) + +--- + +### Phase 2 Backend (11. Nov 2025) +**Implementierungszeit**: Phase 1: 2 Tage | Phase 2 Backend: 1 Tag ## 🎯 Funktionale Anforderungen @@ -22,11 +43,20 @@ - [x] **Gruppen-ID Anzeige**: Nach Upload wird Gruppen-ID als Referenz angezeigt - [x] **Widerrufs-Information**: Hinweis auf Kontaktmöglichkeit für Widerruf der Zustimmung -### Nice-to-Have (Phase 2) -- [ ] **Verwaltungslink**: Kryptischer UUID-basierter Link für Nutzer zur Selbstverwaltung -- [ ] **Self-Service Portal**: Nutzer kann über Link Beschreibungen ändern, Bilder löschen, Consents widerrufen -- [ ] **E-Mail-Benachrichtigung**: Optional E-Mail mit Verwaltungslink nach Upload -- [ ] **Consent-Historie**: Vollständige Audit-Trail aller Consent-Änderungen +### Nice-to-Have (Phase 2) - ✅ Backend 100% KOMPLETT (11. Nov 2025) +- [x] **Management-Token-System**: UUID v4 Token-Generation bei Upload +- [x] **Token-Validierung API**: GET /api/manage/:token (200 mit Gruppendaten oder 404) +- [x] **Consent-Widerruf API**: PUT /api/manage/:token/consents (Workshop & Social Media) +- [x] **Metadata-Edit API**: PUT /api/manage/:token/metadata (Titel & Beschreibung editieren) +- [x] **Bilder hinzufügen API**: POST /api/manage/:token/images (max 50 Bilder pro Gruppe) +- [x] **Bild löschen API**: DELETE /api/manage/:token/images/:imageId (verhindert letztes Bild) +- [x] **Gruppe löschen API**: DELETE /api/manage/:token (komplette Gruppe inkl. Dateien) +- [x] **Rate-Limiting**: IP-basiert 10 req/h, Brute-Force-Schutz 20 Versuche → 24h Block +- [x] **Management Audit-Log**: Migration 007, vollständige Historie aller Management-Aktionen +- [x] **Widerruf-Verhalten**: Workshop setzt display_in_workshop=0, Social Media setzt revoked=1 +- [ ] **Frontend Management-Portal**: React-Komponente /manage/:token (Tasks 12-17) ⏳ +- [ ] **E-Mail-Benachrichtigung**: Optional E-Mail mit Verwaltungslink nach Upload ⏳ +- [ ] **Consent-Historie**: Vollständige Audit-Trail aller Consent-Änderungen ⏳ ## 🔒 Rechtliche Überlegungen @@ -981,13 +1011,33 @@ MANAGEMENT_TOKEN_EXPIRY=90 - [ ] Code-Review durchgeführt (TODO: später) - [ ] Deployment auf Production (bereit nach Code-Review) -### Phase 2 - ⏳ NOCH NICHT GESTARTET -- [ ] Management-Token-System implementiert -- [ ] Management-Portal funktionsfähig -- [ ] Consent-Widerruf funktioniert -- [ ] Alle Phase-2-Tests grün -- [ ] Sicherheits-Review durchgeführt -- [ ] Production-Deployment erfolgreich +### Phase 2 - ✅ Backend 100% KOMPLETT (11. Nov 2025) | ⏳ Frontend ausstehend +**Backend (Tasks 2-11)**: +- [x] Management-Token-System implementiert (UUID v4) +- [x] Token-Validierung API (GET /api/manage/:token) +- [x] Consent-Widerruf API (PUT /api/manage/:token/consents) +- [x] Metadata-Edit API (PUT /api/manage/:token/metadata) +- [x] Bilder hinzufügen API (POST /api/manage/:token/images) +- [x] Bild löschen API (DELETE /api/manage/:token/images/:imageId) +- [x] Gruppe löschen API (DELETE /api/manage/:token) +- [x] Rate-Limiting & Brute-Force-Schutz (IP-basiert, in-memory) +- [x] Management Audit-Log (Migration 007, vollständige Historie) +- [x] Widerruf-Verhalten korrekt implementiert +- [x] Alle Backend-Tests erfolgreich + +**Frontend (Tasks 12-18)**: +- [ ] Management-Portal UI (/manage/:token) ⏳ +- [ ] Consent-Management UI ⏳ +- [ ] Metadata-Edit UI ⏳ +- [ ] Bilder-Management UI ⏳ +- [ ] Gruppe löschen UI ⏳ +- [ ] Upload-Erfolgsseite mit Management-Link ⏳ +- [ ] E2E Testing ⏳ + +**Deployment (Tasks 19-20)**: +- [ ] Dokumentation aktualisiert ⏳ +- [ ] nginx Konfiguration ⏳ +- [ ] Production-Deployment ⏳ ## 📅 Zeitplan @@ -1003,10 +1053,36 @@ MANAGEMENT_TOKEN_EXPIRY=90 **Finale Commits**: 12 Commits, Branch: feature/SocialMedia **Status**: Production-ready nach Code-Review -### Phase 2 (Nice-to-Have): ⏳ Geplant für später -- Tag 6-7: Backend Management-System (Tasks 2.1, 2.2, 2.3) -- Tag 8-9: Frontend Management-Portal (Tasks 2.4, 2.5) -- Tag 10 (optional): E-Mail-Integration (Task 2.6) +### Phase 2 (Nice-to-Have): ✅ Backend 100% komplett (11. Nov 2025) | ⏳ Frontend ausstehend +**Backend (Tasks 2-11) - ✅ KOMPLETT**: +- ✅ Task 2: Token-Generation (UUID v4 bei Upload, bereits in Phase 1) +- ✅ Task 3: Token-Validierung API (GET /api/manage/:token) +- ✅ Task 4: Consent-Widerruf API (PUT /api/manage/:token/consents) +- ✅ Task 5: Metadata-Edit API (PUT /api/manage/:token/metadata) +- ✅ Task 6: Bilder hinzufügen API (POST /api/manage/:token/images) +- ✅ Task 7: Bild löschen API (DELETE /api/manage/:token/images/:imageId) +- ✅ Task 8: Gruppe löschen API (DELETE /api/manage/:token) +- ✅ Task 9: Rate-Limiting & Brute-Force-Schutz (10 req/h, 20 Versuche → 24h Block) +- ✅ Task 10: Management Audit-Log (Migration 007, Repository, Admin-Endpoints) +- ✅ Task 11: Widerruf-Verhalten validiert (Workshop: display_in_workshop=0, Social Media: revoked=1) + +**Frontend (Tasks 12-18) - ⏳ AUSSTEHEND**: +- ⏳ Task 12: Management Portal Grundgerüst (/manage/:token Route) +- ⏳ Task 13: Consent-Management UI (Widerruf/Wiederherstellen) +- ⏳ Task 14: Metadata-Edit UI (Titel/Beschreibung ändern) +- ⏳ Task 15: Bilder-Management UI (Hinzufügen/Löschen) +- ⏳ Task 16: Gruppe löschen UI (mit Bestätigung) +- ⏳ Task 17: Upload-Erfolgsseite (Management-Link prominent anzeigen) +- ⏳ Task 18: E2E Testing (alle Flows testen) + +**Dokumentation & Deployment (Tasks 19-20) - ⏳ AUSSTEHEND**: +- ⏳ Task 19: Dokumentation aktualisieren +- ⏳ Task 20: nginx Konfiguration (/api/manage/* Routing) + +**Zeitaufwand Phase 2**: +- Backend: 1 Tag (11. Nov 2025) - ✅ komplett +- Frontend: Geplant ~2 Tage +- Testing & Deployment: Geplant ~1 Tag ## � Bekannte Issues & Fixes @@ -1035,12 +1111,21 @@ MANAGEMENT_TOKEN_EXPIRY=90 ## 📊 Implementierungsergebnis -### Git-Historie (Branch: feature/SocialMedia) -- **12 Commits** vom 9-10. November 2025 -- Letzter Commit: `8e62475` - "fix: DatabaseManager removes inline comments correctly in migrations" -- Status: **Phase 1 zu 100% komplett** - Bereit für Code-Review und Production-Deployment +### Phase 1 (9-10. Nov 2025) -### Test-Ergebnisse (10. Nov 2025) +**Git-Historie (Branch: feature/SocialMedia)**: +- **11 Commits** vom 9-10. November 2025 +- Letzter Commit: `8e62475` - "fix: DatabaseManager removes inline comments correctly in migrations" +- Status: **100% komplett** - Production-ready + +**API-Endpoints**: +- ✅ `GET /api/social-media/platforms` - Liste aktiver Social Media Plattformen +- ✅ `POST /api/groups/:groupId/consents` - Consents speichern +- ✅ `GET /api/groups/:groupId/consents` - Consents abrufen +- ✅ `GET /api/admin/groups/by-consent` - Gruppen nach Consent filtern +- ✅ `GET /api/admin/consents/export` - Consent-Daten exportieren (CSV/JSON) + +**Test-Ergebnisse (10. Nov 2025)**: - ✅ Upload mit Consent: Funktioniert - ✅ Upload ohne Werkstatt-Consent: Blockiert (400 Error) - ✅ Filter "Alle Gruppen": 76 Gruppen @@ -1049,6 +1134,66 @@ MANAGEMENT_TOKEN_EXPIRY=90 - ✅ Export-Button: CSV-Download funktioniert - ✅ ConsentBadges: Icons und Tooltips werden korrekt angezeigt - ✅ Automatische Migration: Migration 005 & 006 beim Backend-Start angewendet +- ✅ GDPR-Konformität: 72 alte Gruppen mit display_in_workshop = 0 +- ✅ Social Media Plattformen: 3 Plattformen (Facebook, Instagram, TikTok) + +--- + +### Phase 2 Backend (11. Nov 2025) + +**Git-Historie**: +- **4 neue Commits** am 11. November 2025 + - `c18c258` - "feat(phase2): Implement Management Portal API routes (Tasks 3-7)" + - `2d49f0b` - "fix(phase2): Fix DELETE /api/manage/:token - use correct DeletionLogRepository method" + - `0dce5fd` - "feat(phase2): Implement Rate-Limiting & Brute-Force Protection (Task 9)" + - `0f77db6` - "feat(phase2): Implement Management Audit-Log (Task 10)" +- Gesamtstand: **15 Commits** (11 Phase 1 + 4 Phase 2) +- Status: **Backend 100% komplett** - Bereit für Frontend-Integration + +**Neue Dateien erstellt**: +- `backend/src/routes/management.js` (651 Zeilen) - 8 Management-API-Routes +- `backend/src/middlewares/rateLimiter.js` (~180 Zeilen) - Rate-Limiting & Brute-Force-Schutz +- `backend/src/middlewares/auditLog.js` (~45 Zeilen) - Audit-Logging-Middleware +- `backend/src/repositories/ManagementAuditLogRepository.js` (~180 Zeilen) - Audit-Log CRUD +- `backend/src/database/migrations/007_create_management_audit_log.sql` - Audit-Log-Tabelle + +**Erweiterte Dateien**: +- `backend/src/repositories/GroupRepository.js` - `getGroupByManagementToken()` Methode +- `backend/src/routes/admin.js` - 3 neue Audit-Log-Endpoints +- `backend/src/routes/index.js` - Management-Router registriert +- `backend/package.json` - `uuid` Dependency hinzugefügt + +**Management Portal APIs** (alle getestet): +- ✅ `GET /api/manage/:token` - Token validieren & Gruppendaten laden +- ✅ `PUT /api/manage/:token/consents` - Consents widerrufen/wiederherstellen +- ✅ `PUT /api/manage/:token/metadata` - Titel & Beschreibung editieren (setzt approved=0) +- ✅ `POST /api/manage/:token/images` - Bilder hinzufügen (max 50, setzt approved=0) +- ✅ `DELETE /api/manage/:token/images/:imageId` - Einzelnes Bild löschen +- ✅ `DELETE /api/manage/:token` - Komplette Gruppe löschen + +**Management Audit-Log APIs** (alle getestet): +- ✅ `GET /api/admin/management-audit?limit=N` - Letzte N Audit-Log-Einträge +- ✅ `GET /api/admin/management-audit/stats` - Statistiken (Aktionen, IPs, Erfolgsrate) +- ✅ `GET /api/admin/management-audit/group/:groupId` - Audit-Log für spezifische Gruppe + +**Sicherheitsfeatures**: +- ✅ Rate-Limiting: IP-basiert, 10 Anfragen/Stunde +- ✅ Brute-Force-Schutz: 20 fehlgeschlagene Versuche → 24h IP-Block +- ✅ Audit-Logging: Alle Management-Aktionen werden protokolliert +- ✅ Token-Maskierung: Nur erste 8 Zeichen im Audit-Log gespeichert +- ✅ File-Cleanup: Gelöschte Bilder werden physisch von Festplatte entfernt +- ✅ Validation: UUID-Format-Check, Image-Count-Limits, Duplicate-Prevention + +**Test-Ergebnisse (11. Nov 2025)**: +- ✅ Token-Validierung: GET /api/manage/:token funktioniert (200 mit Daten, 404 bei invalid) +- ✅ Consent-Widerruf: Workshop setzt display_in_workshop=0, Social Media setzt revoked=1 +- ✅ Metadata-Edit: Titel/Beschreibung ändern, setzt approved=0 +- ✅ Bilder hinzufügen: POST /api/manage/:token/images (max 50 Bilder-Limit) +- ✅ Bild löschen: DELETE .../:imageId funktioniert, verhindert letztes Bild löschen +- ✅ Gruppe löschen: DELETE /api/manage/:token mit Deletion-Log +- ✅ Rate-Limiting: Blockiert nach 10 Requests/Stunde (429 Error) +- ✅ Audit-Log: 2 Einträge geschrieben, Admin-API funktioniert +- ✅ Migration 007: Erfolgreich angewendet nach DB-Reset - ✅ GDPR-Konformität: 72 alte Gruppen mit display_in_workshop = 0, 0 mit automatischem Consent - ✅ Social Media Plattformen: 3 Plattformen (Facebook, Instagram, TikTok) erfolgreich angelegt @@ -1073,6 +1218,6 @@ MANAGEMENT_TOKEN_EXPIRY=90 --- **Erstellt am**: 9. November 2025 -**Letzte Aktualisierung**: 10. November 2025, 17:45 Uhr -**Status**: ✅ Phase 1 zu 100% komplett - Alle Features implementiert, getestet und GDPR-konform validiert -**Production-Ready**: Ja - Bereit für Code-Review und Deployment +**Letzte Aktualisierung**: 11. November 2025, 20:30 Uhr +**Status**: ✅ Phase 1: 100% komplett | ✅ Phase 2 Backend: 100% komplett | ⏳ Phase 2 Frontend: ausstehend +**Production-Ready**: Phase 1: Ja (deployed) | Phase 2 Backend: Ja (bereit für Frontend-Integration)