Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/10-compliance-polish/VERIFICATION.md
T

18 KiB

Phase 10 — Verification Report

Scope: Compliance + Polish (10 files) Verifier: Read-only structural + content audit Status: PASS with minor follow-ups (no blocking issues)


1. Template-Konformität

Alle 9 Task-Detail-MDs befolgen das DETAIL-MD-Template aus ../DETAIL-MD-TEMPLATE.md mit verbindlicher Section-Reihenfolge:

File Frontmatter Problem Depends on Blocks Approach Impl-Steps Tests AC Rollback Security Subagents Staging Dev/Progress/LL
react-email.md OK OK OK OK OK OK OK OK OK OK OK OK OK
compliance-audit-export.md OK OK OK OK OK OK OK OK OK OK OK OK OK
dsgvo-bulk-ops.md OK OK OK OK OK OK OK OK OK OK OK OK OK
security-docs.md OK OK OK OK OK OK OK OK OK OK OK OK OK
lighthouse.md OK OK OK OK OK OK OK OK OK OK OK OK OK
bundle-budget.md OK OK OK OK OK OK OK OK OK OK OK OK OK
i18n-foundation.md OK OK OK OK OK OK OK OK OK OK OK OK OK
wcag-internal.md OK OK OK OK OK OK OK OK OK OK OK OK OK
test-coverage.md OK OK OK OK OK OK OK OK OK OK OK OK OK

Alle 15 Sections in korrekter Reihenfolge present. README.md ist Phase-Overview (kein Detail-MD), entspricht aber den anderen Phase-README-Conventions (Done-Definition, Task-Reihenfolge-Table, Dependency-Graph).


2. Dependencies Konsistenz

Korrekt modelliert:

  • react-email.md (#75) ist als „vorgezogen" markiert, blockt 05-business-features/marketing-funnel-phase-3.md — wie gewünscht
  • compliance-audit-export.md (#67) blockt dsgvo-bulk-ops.md (#68) wegen gemeinsamer AuditEvent-Schema-Updates — korrekt sequenziell
  • test-coverage.md (#76) hat explizit „Alle vorherigen Phasen" als Dependency — korrekt am Ende
  • Lighthouse/Bundle-Budget/i18n/WCAG/Security-Docs (#69-#73) sind als parallel ausgewiesen, sharen aber bewusst Vite-Config (Lighthouse↔Bundle-Budget) — Koordination dokumentiert
  • wcag-internal.md depends on lighthouse.md + i18n-foundation.md (Translation-Strings für ARIA) — semantisch konsistent

Numbering Hinweis: Task-IDs sind nicht sequenziell (#67, #68, #69, #70, #71, #72, #73, #75, #76 — #74 fehlt offenbar, vermutlich in anderer Phase aufgeteilt). Reihenfolge im README (1-9) ist trotzdem konsistent durchgängig benutzt.


3. Implementation-Steps-Qualität

react-email.md

  • Migration aller transactional templates: 8 Templates explizit benannt (Welcome, MagicLink, PasswordReset, SubscriptionSuccess, SubscriptionFailed, Invitation, InvoiceSent, TenantNotification) + 1 Marketing-Campaign-Base → vollständig.
  • ESLint-Rule für dangerouslySetInnerHTML-Verbot, actionUrl https-Validation, automatisches React-Escaping — solide Security-Posture.

compliance-audit-export.md

  • AuditEvent-Schema-Erweiterung: alle SOC2/HIPAA/GDPR-relevanten Felder vorhanden: actorType, actorId, actorEmail, actorIp, actorUserAgent, resourceType/Id, action, outcome, sourceModule, dataSensitivity, regulatoryScope, metadata, prevHash, hash, createdAt mit korrekten Indizes → vollständig.
  • Tamper-Evidence Hash-Chain: HMAC-SHA-256 über (prevHash || serializedEvent) mit AUDIT_CHAIN_SECRET. Versionsfeld für Key-Rotation erwähnt. Kryptografisch korrekt. Hinweis: Key-Rotation-Schema (Versionsfeld in hash-Spalte) sollte als Implementation-Step expliziter sein — aktuell nur in Security-Notes (Section 5).
  • 5 Pre-Built Reports + PDF-Generator mit Signature-Hash decken Standard-SOC2-Auditor-Anforderungen.

dsgvo-bulk-ops.md

  • Datasubject-Export-Worker: 12 Tabellen explizit aufgelistet (User, UserRole, TenantUser, AuditEvent, Row, CrmContact, Notification, OutboundEmail, ChatMessage, FormSubmission, EventWebhookAttempt, ImpersonationAudit). Storage-Files-ZIP für hochgeladene Files — vollständig für aktuellen Schema-Stand. Hinweis: Phase 04 (Search/RAG) und Phase 07 (Chatbot) bringen ggf. weitere PII-haltige Models (Chunk-Embeddings mit User-Content, Chatbot-Sessions) — sollte als „Update-Pflicht bei Schema-Änderungen" in der Cascade-Doku verewigt werden.
  • 30-Tage-Grace-Period: User-Schema-Erweiterung mit pendingDeletion, scheduledDeletionAt, deletionRequestedAt, pseudonymized, pseudonymizedAt. Login-Path-Erweiterung in Step 8. Grace-Cron in Step 9. Reactivation-Flow mit Reactivation-Screen und signed-Token (30-Min-Validity, AUDIT_CHAIN_SECRET-ähnlicher Key) — korrekt und robust.
  • Pseudonymisierungs-Layer mit verschlüsselter Map: Separates PseudonymizationMap-Model, verschlüsselt mit PSEUDONYMIZATION_KEY (Platform-Admin only, Vault/AWS-KMS in Production gefordert), CLI-Reveal mit Audit-Trail. Sicher, aber: Encryption-Schema (Key-Derivation, IV-Handling, Algorithmus-Wahl AES-256-GCM vs ähnlich) bleibt in Step 2 abstrakt — sollte explizit AES-256-GCM oder libsodium-secretbox spezifizieren.
  • Verification-Pass: Schema-Reflection via Prisma-DMMF iteriert ALLE Models mit User-Reference, läuft 1h nach Cascade, generiert DsgvoVerificationReport mit Hash. Robust. Hinweis: 1h-Window könnte für sehr große Tenants zu kurz sein wenn Cascade asynchron läuft; sollte konfigurierbar sein.

security-docs.md

  • STRIDE-Threat-Model: 7 Komponenten (Web, API, Worker, DB, Plugins, AI-Pipeline, Webhooks) mit allen 6 STRIDE-Achsen, plus 5 Mermaid-Datenfluss-Diagramme → vollständig.
  • IR-Runbook mit GDPR-72h-Notification: 4 Severity-Levels, 6 Phasen, separate Section für GDPR-Breach-Notification mit Aufsichtsbehörde-Template, Datasubject-Notification (Art. 34 High-Risk), Communication-Templates für Internal/External/Regulator/Press → vollständig.
  • security.txt-Pfad: apps/web/public/.well-known/security.txt → korrekt (statisches Asset, von Web-App ausgeliefert unter https://app.toolctrl.de/.well-known/security.txt). Vite serves public/ standardmäßig.
  • Expires-Renewal-Cron als zusätzliche Verteidigung gegen abgelaufene security.txt.

lighthouse.md

  • 12 Routes explizit in .lighthouserc.json-Config: 4 Public (/, /pricing, /contact, /blog), 5 Internal (dashboard, crm, crm/contacts, settings/members, settings/billing), 3 Admin (dashboard, analytics, tenants) → passt zu User-Wunsch „Lighthouse für alles, auch internal". Hinweis: settings/profile, settings/privacy, email-marketing werden in wcag-internal.md Step 9 als Routes erwähnt aber nicht in den 12 Lighthouse-URLs — Inkonsistenz, sollte angeglichen werden (entweder Lighthouse-Liste erweitern oder WCAG-Liste auf 12 reduzieren).
  • Critical-CSS-Inlining (Step 3), Font-Preload (Step 3), Code-Splitting/manualChunks (Step 4) — konfiguriert.
  • PWA als „warn"-Level (0.80) statt „error" (0.95) — pragmatisch.

bundle-budget.md

  • Per-Route-Limits als Soft-Tool: Step 2 + Test-Requirements explizit: „Size > Limit → red Output, exit code 0 (kein Block, nur Warning), aber Report-Flag setzen". PR-Comment statt PR-Block. → korrekt nach User-Wunsch „Soft-Tool ohne Hard-Gate".
  • 12 Routes + Vendor-Chunks im Config, gzip-bytes als Measurement.
  • Δ-Vergleich gegen main-Baseline via CI-Artifact.

i18n-foundation.md

  • ICU-Plurals: i18next + i18next-icu, explicit Plural-Pattern-Example, Tests für DE/EN/PL → vorhanden.
  • Intl-Helpers: 5 Helpers (Currency, Date, Number, RelativeTime, List) mit 4-Locale-Tests (de/en/ar/ja) → vollständig.
  • RTL-Foundation: Tailwind-RTL-Variants, <html dir> server-side, 2 RTL-Smoke-Tests (Sidebar, Card) → etabliert als Foundation (nicht vollständig RTL-konvertiert, aber das ist konsistent mit „B i18n DE/EN solide").
  • Locale-Picker: in /app/$tenant/settings/profile.tsx, mit User.locale Schema-Migration → vorhanden.
  • Keine 5+ Sprachen jetzt, nur Framework + DE/EN → korrekt nach User-Wunsch.

wcag-internal.md

  • axe-core ≥ 80% Coverage: explizit als Target in beiden Packages (packages/ui-app, packages/ui-subframe) → korrekt.
  • jsx-a11y strict: ESLint-Plugin-Strict-Preset + 3 zusätzliche Custom-Rules (no-autofocus, no-noninteractive-element-interactions, anchor-is-valid) → vorhanden.
  • Color-Contrast-Audit: scripts/contrast-audit.mjs mit wcag-contrast-Lib, Light + Dark Mode, WCAG-AA 4.5:1/3:1 → robust.
  • NVDA/VoiceOver Smoke-Tests: 6 Major-Flows (Login, Magic-Link, Dashboard, CRM, Settings-Members, DSGVO-Export) in Step 10 → vorhanden.

test-coverage.md

  • Per-Path-Thresholds: Critical 90 / Standard 70 / ui-subframe 50 → korrekt nach User-Wunsch.
  • 5 Golden-Path-E2E: Auth, Tenant-Create, Member-Invite, Billing-Subscribe, CRM-Workflow → vollständig.
  • Sprint-Reihenfolge: Auth → Tenant-Isolation → Billing → Permissions/Entitlements → DB-Package (Steps 5-9) — sicherheits-priorisiert.

4. Test-Requirements

Coverage-Tests:

  • DSGVO-Export-Worker: ≥ 90 % im DSGVO-Code (Test-Requirements Section), End-to-End-Integration-Test mit Test-User in jeder Tabelle → vorhanden.
  • Tamper-Evidence-Hash-Chain-Verifikation: CLI-Test mit Happy-Path und Tampering-Detection, Coverage ≥ 85 % → vorhanden.
  • WCAG-Smoke-Tests mit NVDA/VoiceOver: Step 10 dokumentiert 6 Flows, Reports werden in docs/accessibility/screen-reader-smoke-tests-<date>.md gespeichert → vorhanden.

5. Security-Notes

DSGVO-Pseudonymisierung-Map-Encryption-Key-Management

  • PSEUDONYMIZATION_KEY als Platform-Level-Secret, Vault/AWS-KMS in Production gefordert, nie pro Tenant → adressiert.
  • Lücke: Encryption-Schema (Algorithmus, IV-Generierung, Authentication-Tag) bleibt abstrakt. Empfehlung: in Step 2 Algorithmus konkret festlegen (z.B. libsodium secretbox oder AES-256-GCM mit random 96-bit IV pro Record).
  • Key-Rotation: nicht explizit erwähnt für PSEUDONYMIZATION_KEY (im Gegensatz zu AUDIT_CHAIN_SECRET mit Versionsfeld). Empfehlung: gleicher Rotation-Mechanismus.

Tamper-Evidence-HMAC-Key-Management

  • AUDIT_CHAIN_SECRET als Platform-Level-Secret, Rotation via Versionsfeld in Hash → adressiert.
  • Lücke: Rotation-Workflow-Schritte (Re-Hash der gesamten Chain bei Rotation? Oder Versions-Markierung pro Event?) bleiben abstrakt. Empfehlung: in Step 2 expliziter — vorgeschlagen wäre hash = HMAC(secret_v_N, ...) mit N als zusätzlicher Spalte, Verifier kennt alle aktiven Keys.

Audit-Event-Auto-Capture vermeidet PII-Leaks in audit-Logs selbst

  • Default dataSensitivity=internal, explizite dataSensitivity=pii für PII-Models, IP-Anonymisierung bei Pseudonymisierung (/24-Subnetz) → adressiert.
  • Lücke: metadata-Field (Json, max 8KB) kann beliebige PII enthalten wenn Auto-Capture leichtfertig konfiguriert. Empfehlung: Validation-Layer der metadata gegen eine Allowlist von erlaubten Keys pro sourceModule prüft.

6. Staging-Deployment-Steps

Lighthouse-CI-Setup auf Coolify-Preview-Deploys

  • .lighthouserc.json mit extraHeaders für Auth-Cookie, Test-Session-Token via Repo-Secret LIGHTHOUSE_STAGING_SESSION, Token-Rotation täglich via Cron — vorhanden.
  • Lücke: „Coolify-Preview-Deploys"-Integration ist nicht explizit. Aktuell läuft Lighthouse-CI gegen https://staging.toolctrl.de (Single-Staging-URL). Wenn Coolify PR-Preview-URLs pro Branch generiert, sollte die URL dynamisch sein ({{PR_PREVIEW_URL}}-Substitution im Workflow). Empfehlung: Workflow-Step ergänzen der Preview-URL aus Coolify-API zieht.

WCAG-Audit-Workflow

  • Lokaler Audit-Run pro Route (Chrome + axe-DevTools, Lighthouse-Headless), pnpm contrast:audit, manuelle Screen-Reader-Tests durch Operator, Lighthouse-CI-Run auf Staging → vorhanden und gut strukturiert.

Performance-Regression-Comments auf PRs

  • Bundle-Budget hat dedizierten PR-Comment-Workflow (.github/workflows/bundle-budget.yml) mit Upsert-Marker → vorhanden.
  • Lighthouse-CI: treosh/lighthouse-ci-action@v11 mit uploadArtifacts: true und temporaryPublicStorage: true postet Lighthouse-Report-Link, aber kein expliziter Per-Route-Performance-Comparison-Comment. Empfehlung: zusätzlich lhci-server oder Custom-Action für Δ-Comments wie bei Bundle-Budget. Aktuell wird die Verschlechterung nur via Score-Threshold-Fail sichtbar, nicht als delta-tabelle im PR.

7. Konsistenz mit User-Wünschen

User-Wunsch Status
A für Audit-Trail-Export Voll-Compliance OK — compliance-audit-export.md mit allen SOC2/HIPAA/GDPR-Feldern + Hash-Chain
A für DSGVO-Bulk-Operations OK — dsgvo-bulk-ops.md mit Self-Service + Admin + Pseudonymisierung + Verification
A für Security-Docs-Pack OK — security-docs.md mit 7 Doku-Files + security.txt + IR-Runbook
Lighthouse für alles, auch internal OK mit Inkonsistenz — 5 Internal-Routes drin, aber settings/profile, settings/privacy, email-marketing aus wcag-internal-Audit-Liste fehlen in Lighthouse-Config (siehe Section 3)
Bundle-Budget Soft-Tool ohne Hard-Gate OK — explizit exit code 0 + PR-Comment-Warning statt Block
B i18n DE/EN solide OK — DE/EN als supportedLngs, RTL nur als Foundation (2 Smoke-Tests), Framework offen für Erweiterung
B WCAG Internal-Audit erst, dann später extern OK — wcag-internal.md macht Internal; externer Audit nicht erwähnt (sollte in 11-backlog/README.md ergänzt werden — nicht in Phase 10, aber als Erwartung)
B Test-Coverage Per-Module-Gates → Per-Path-Thresholds OK — Per-Path-Thresholds mit Critical 90/Standard 70/UI 50
A React-Email Migration OK — alle 8 Templates portiert, Marketing-Base + Audit-Export-Ready-Template als zusätzliche werden in compliance-audit-export.md/dsgvo-bulk-ops.md angekoppelt

8. Fehlende Aspekte

DSGVO-Self-Service-UI-Email-Confirmation-Flow

  • Adressiert. dsgvo-bulk-ops.md Step 6 + Sub-Component (a) erwähnen Email-Verifikation mit signed-token, 30-Min-Validity, dedicated AccountDeletionConfirmationEmail.tsx-Template (Step 10). Security-Notes erklären Schutz gegen Account-Hijack-Lösch-Attacken.

Security-Docs security.txt-Path

  • Korrekt. apps/web/public/.well-known/security.txt — Vite/React-Router servt public/ als statische Assets unter Root, also URL wird https://app.toolctrl.de/.well-known/security.txt (RFC-9116-konform).

Lighthouse-CI Performance-Regression-Comments auf PRs

  • Teilweise. Score-basiertes Threshold-Fail ist da, aber kein expliziter Δ-Comment wie bei Bundle-Budget. Empfehlung: in lighthouse.md Step 9 ergänzen — Custom-Action die LHCI-Report-JSON gegen Main-Baseline vergleicht und Δ-Tabelle als PR-Comment postet (analog zu bundle-budget.md).

Weitere kleine Lücken

  • AuditEvent-Cleanup-Lock: dsgvo-bulk-ops.md erwähnt Concurrency-Schutz für Cascade (Idempotency-Key + DB-Lock auf user.id), aber compliance-audit-export.md erwähnt nicht explizit dass Retention-Cleanup nicht parallel mit Export-Job laufen darf — Empfehlung: Lock-Mechanismus oder Manual-Pause-Flag (in Security-Notes erwähnt aber nicht als Implementation-Step).
  • i18n-Audit-Output-Persistierung: Audit-Report (docs/contributing/i18n-audit-<date>.md) wird in Step 1 erzeugt; sollte als CI-Artifact persistiert werden für Trend-Tracking, nicht nur als one-shot-Doku.
  • react-email Storybook-Stories: als „sobald Phase 08 Storybook fertig" konditional — wenn Phase 08 vor Phase 10 abgeschlossen ist (laut README), sollten Stories nicht optional sein. Empfehlung: in Acceptance-Criteria als bedingtes „falls Phase 08 fertig: Stories existieren".

9. Verbesserungs-Vorschläge (nicht blockierend)

  1. Lighthouse ↔ WCAG Routen-Konsistenz: wcag-internal.md listet in Step 9 zusätzliche Routes (settings/profile, settings/privacy, email-marketing, auth/login, auth/register, auth/magic-link, auth/password-reset). Diese sollten auch in .lighthouserc.json aufgenommen werden, damit Lighthouse-Accessibility-Score-Pflicht ≥ 0.95 für genau diese Routes gilt. Aktuelles Lighthouse hat 12 URLs, WCAG impliziert 17+ Routes. Empfehlung: Routen-Liste konsolidieren in docs/performance/lighthouse-targets.md und beide Tasks referenzieren.

  2. Encryption-Algorithmus für PseudonymizationMap explizit machen: AES-256-GCM oder libsodium secretbox als konkrete Wahl, IV-Strategy, Authentication-Tag-Handling — als Implementation-Step in dsgvo-bulk-ops.md Step 2.

  3. AUDIT_CHAIN_SECRET-Rotation-Workflow als Implementation-Step: Versionsfeld pro Event oder pro Chain-Segment, Verifier-Logik für Multi-Version-Validation — als Sub-Step in compliance-audit-export.md Step 2.

  4. Lighthouse-Performance-Δ-PR-Comment analog zu Bundle-Budget — als Step 9b in lighthouse.md.

  5. Coolify-Preview-URL-Integration für Lighthouse-CI wenn Coolify PR-Preview-Deployments unterstützt — Workflow-Dynamik.

  6. Cross-Reference zu Phase 11 Backlog für extern-pen-test + externer WCAG-Audit im README.md Verweise-Section ergänzen.


10. Gesamt-Bewertung

PASS.

Die Phase ist vollständig, template-konform und mit dokumentierten User-Wünschen konsistent. Implementation-Steps sind atomar und committable, Test-Requirements sind konkret (Coverage-Targets, E2E-Flows benannt), Security-Notes adressieren die wichtigsten Risiken. Kleinere Lücken (Encryption-Algorithmus-Spezifikation, Key-Rotation-Workflow, Lighthouse-Δ-PR-Comments, Routen-Liste-Konsistenz zwischen Lighthouse und WCAG) sind nicht-blockierend und können während Implementation oder via einem kleinen Follow-up-Commit der Detail-MDs adressiert werden.

Keine kritischen Compliance-Lücken. Hash-Chain ist kryptografisch korrekt aufgesetzt, DSGVO-Cascade ist vollständig (12 Tabellen explizit), Pseudonymisierung mit verschlüsselter Map ist sicher konzipiert (mit der oben genannten Empfehlung zur Algorithmus-Konkretisierung).

Empfehlung: Phase 10 kann zur Implementation freigegeben werden. Die in Section 9 aufgeführten Verbesserungen sollten vor Start der jeweiligen Detail-MDs (insbesondere compliance-audit-export.md Step 2, dsgvo-bulk-ops.md Step 2, lighthouse.md Step 9) als kleine Detail-MD-Edits eingearbeitet werden, um Implementation-Subagents keine Architektur-Entscheidungen treffen zu lassen.