Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M21-audit-log.md
T

17 KiB
Raw Blame History

Boilerplate-Abgleich — Modul 21: Audit-Log (Anzeige)

  • Modul-ID: M21 (Detail-Spec _bmad-output/specs/M21-audit-log.md)
  • Name: Audit-Log — tenant-weiter Trail aller schreibenden Aktionen mit Vorher/Nachher-Diff
  • Milestones: M151 (Anzeige + Filter + Volltext-Suche), M152 (Compliance-Export + Aufbewahrung + Legal Hold); baut auf M001 (Audit-Default) auf
  • Pflichtenheft-Block: Block 7, Abschnitte 21.1–21.8
  • Reuse-Level: medium

Die Boilerplate liefert ein produktionsreifes Audit-Fundament (Tamper-evidente AuditEvent-Tabelle mit Hash-Chain, Write-Path, Retention-Worker, Compliance-Export inkl. PDF/CSV, Permission-gegatete Admin- + Tenant-Routen). Aber: Das Boilerplate-Audit-Modell ist auf Compliance-Evidence (SOC2/HIPAA/GDPR) ausgelegt, nicht auf den HiveGrid-Detail-Spec mit Vorher/Nachher-Diff, Klartext-summary_text, Subject-/Actor-Snapshot-Labels, Saved Views, tenant-Admin-konfigurierbarer Retention in Monaten und Legal Hold. Diese fachlichen Kern-Features fehlen komplett. Die Listen-/Detail-Anzeige-UI für Endnutzer (Tabelle, Diff-View, Per-Subject-Drawer) ist ebenfalls neu zu bauen — Boilerplate hat nur Export-Forms und eine Admin-Log-Tabelle.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/core.prisma:55 (model AuditEvent) Audit-Tabelle: tenantId, actorId/Type/Email/Ip/UserAgent, action, targetType/Id, requestId, sourceModule, outcome, dataSensitivity, regulatoryScope[], metadata (JSON), previousHash/eventHash. Indizes auf (tenantId,createdAt), (actorId,createdAt), (action,createdAt), requestId, (tenantId,action,createdAt) anpassen — Felder weitgehend deckungsgleich mit Spec Block A; ABER es fehlen before_diff/after_diff/summary_text/actor_label/subject_label. Spec-subject_type/subject_id = boilerplate targetType/targetId. actor_kind-Werte (ki_agent, automation, platform_admin) müssen ergänzt werden. Append-Only-DB-Trigger (Spec) fehlt.
packages/db/src/audit-events.server.ts Single-Write-Path createAuditEvent() / publishAuditEventViaOutbox() (Transaction-aware via Outbox), Metadata-Sanitizing (Secret-Redaction), Per-Tenant-Hash-Chain-Link, buildAuditEventCreateData(), toAuditHashPayloadFromRow() 1:1 für M001-Fundament; anpassen für M21 (neue Diff-/Summary-Felder ins Write-Schema aufnehmen)
packages/db/src/audit-hash.ts Tamper-Evidenz: computeAuditHash() (HMAC-SHA256 via AUDIT_CHAIN_SECRET, Fallback SHA-256), canonicalizeAuditPayload(), verifyAuditChain() mit Break-Reporting 1:1 — deckt Spec Block I (Hash-Chain Phase 2) bereits vor; Verifikations-Tool-Backend ist da, nur UI fehlt
packages/foundation/src/audit.ts DB-agnostische auditEvent(input, client), withAuditMiddleware(handler, buildEvent, client), Typen AuditEventInput/AuditEventClient als-vorlage für M001-Querschnitt-Aufruf; M21 selbst liest nur
packages/db/src/logs.server.ts Admin-/Tenant-Audit-Listen-Query: getAdminAuditLogList(), getTenantAuditLogList(tenantId, …), buildAuditLogWhereFromFilters() (Filter q/action/url/userId/createdAtFrom/To, Volltext-OR), serializeAdminAuditLogsCsv(), Pagination (take/skip, max 500) — operiert allerdings auf dem Log-Modell, nicht AuditEvent als-vorlage — Filter-/Pagination-/Where-Builder-Muster direkt übertragbar; muss auf AuditEvent-Modell + Spec-Filter (Actor-Kind, Subject-Type, Bulk-Op-ID, IP) umgeschrieben werden
packages/db/src/export-jobs.server.ts + prisma/schema/queue.prisma:27 (model ExportJob) Async-Export-Job-Lifecycle: ExportJobCreateInput, RUNNING/SUCCEEDED/FAILED/PAUSED-Transitions, artifactBucket/Key, rowCount, expiresAt/deletedAt/hardDeletedAt (TTL + Cleanup), requestId, Retention-Records anpassen — exakt das Job-Modell für M152-Compliance-Export. Es fehlt im Modell filter_criteria/format-Enum-Detaillierung + purpose/reason-Pflichtfeld (Spec Block G) + Self-Audit audit.exported
packages/exports/src/audit-pdf.ts (./audit-pdf) serializeAuditEventsToPdf / …Stream, AuditPdfEvent, Cover-Page (Tenant/Range/Filter/Integrity) + tabellarischer Event-Log, Row-Cap PDF_STREAM_HARD_ROW_LIMIT=5000 1:1 für M152-PDF-Export (Spec Block G PDF-Format); HiveGrid muss DE-Labels + Zweck-Begründung in Header ergänzen
packages/exports/src/{csv,json} + src/sinks/s3-multipart.ts + src/limits.ts CSV/JSON-Serializer (streaming), S3-Multipart-Sink (8 MB Parts), Plan-Row-Caps, Spreadsheet-Injection-Safety 1:1 für M152-Export CSV/JSON nach Scaleway-S3
apps/web/app/routes/admin/audit-export.helpers.server.ts parseAuditExportFilters(), buildAuditExportWhere() (tenantId/actorType/outcome/regulatoryScope/Date-Range), computeAuditIntegritySummary(), renderAuditExportCsv(), AUDIT_EXPORT_MAX_ROWS=50000, csvCell() (injection-safe) als-vorlage — Filter-→-Where-Übersetzung + Integritäts-Summary direkt adaptierbar; Filter-Set muss auf Spec Block F erweitert werden
apps/web/app/routes/app.$tenant/settings/audit-export.tsx Tenant-scoped Export-Route (Permission app.settings.auditTrails.view, tenantId-locked gegen Query-Smuggling), CSV+PDF-Download-Form mit Filtern, i18n-Keys als-vorlage — zeigt das korrekte Tenant-Scope-Pattern; ist aber synchroner Direkt-Download, kein Async-Job-mit-Notification (Spec verlangt Job + Vorschau-Count + Begründung)
apps/web/app/routes/admin/audit-trails.tsx + apps/web/app/components/audit/AdminAuditLogToolbar.tsx Admin-Listen-View: IndexPageLayout + LogsTable + Filter-Toolbar + CSV-Export-Button + Pagination, verifyUserHasPermission("admin.auditTrails.view") als-vorlage — Layout-/Toolbar-/Tabellen-Muster; läuft auf Log-Modell + Plattform-Admin (M041), nicht auf der Tenant-AuditEvent-Anzeige aus M151
apps/web/app/utils/audit/pdfRender.ts (renderAuditExportPdfResponse, buildAuditPdfLabels) + apps/web/app/utils/audit/withAuditContext.ts PDF-Response-Wrapper + Audit-Kontext-Middleware (Request-ID, Actor-Resolution) anpassen — DE-Labels für HiveGrid
apps/worker/src/jobs/audit-retention.ts Täglicher Retention-Cron: runAuditRetentionJob() mit Seams (tenantLister/eventDeleter/auditWriter), resolveAuditRetentionPolicy(), Meta-Audit der Löschung selbst anpassen — Mechanik passt (Spec Block H: täglicher Lösch-Job mit Self-Audit). ABER: Boilerplate-Policy ist regulatory-scope-basiert in Tagen (365/6y/7y), Spec verlangt tenant-Admin-konfigurierbar 6–120 Monate + Legal-Hold-Pause — beide fehlen und sind nachzurüsten
apps/worker/src/jobs/audit-event-persist.ts (+ -bootstrap) Outbox-Consumer der Audit-Inserts (outbox.audit-Queue), führt prevHash-Lookup + Chain-Link in kurzer Transaktion aus 1:1 für M001-Async-Audit-Schreibpfad
apps/worker/src/jobs/export.ts + dsgvo-export.ts Generischer Export-Job + DSGVO-Export-Muster (Aggregation, S3-Stream, Signed-URL, Self-Audit EXPORT_PERSONAL_DATA) als-vorlage für M152-Audit-Export-Worker (gleiches Muster: Filter → Stream → S3 → Signed-URL → audit.exported)
packages/db/src/permissions-seed.server.ts:102/177/202/237 Permissions admin.auditTrails.view (SuperAdmin) + app.settings.auditTrails.view (SuperUser/Admin) bereits geseedet + Rollen-Mapping anpassen — entspricht grob Spec audit.read; Spec verlangt zusätzlich getrenntes audit.admin (Export/Retention/Legal-Hold) und audit.read als atomares Bundle (M27)
prisma/schema/featureFlags.prisma + packages/feature-flags Feature-Flag-Querschnitt (FeatureFlag, append-only FeatureFlagAudit) 1:1 für DoD-Punkt „Feature-Flag-fähig"
packages/i18n + apps/web/.../audit-export-i18n.test.ts i18n-Querschnitt + bestehende Audit-Export-i18n-Keys anpassen — Keys-Schema nutzen, HiveGrid-Audit-Action-Labels + Klartext-Hinweise (Block L) neu
packages/view-models View-Model-Layer-Paket (M013-Konvention) als-vorlage — pure VM-Builder für Audit-Listen-/Detail-VM neu darin anlegen
apps/api/.../middleware/audit-context.ts + request-id.ts Request-ID + Audit-Kontext-Middleware in der API 1:1 — liefert requestId/Actor-Kontext für Audit-Einträge

Vorhandene Daten-Modelle (konkret, mit Pfad)

Modell Pfad Bezug zu M21
AuditEvent prisma/schema/core.prisma:55 Kern-Modell. Deckt Spec Block A zu ~70% (Actor-Felder, Action, Target, requestId, metadata, IP/UA, Hash-Chain, Indizes). Fehlend: before_diff, after_diff, summary_text, actor_label, subject_label
Log prisma/schema/core.prisma:36 Älteres, schlankeres Aktivitäts-Log (url/action/details, Tenant/User/ApiKey/Row/Comment-Relationen). Wird von logs.server.ts-Listen-Query genutzt — NICHT das Spec-Audit-Modell, eher Aktivitäts-/Row-Log
ExportJob + Enum ExportJobStatus prisma/schema/queue.prisma:20/27 Direkt für M152-Export-Job. Hat TTL (expiresAt/deletedAt/hardDeletedAt), artifactBucket/Key, rowCount, Status-Lifecycle. Fehlend: filterCriteria, purpose/reason
ImpersonationAudit prisma/schema/accounts.prisma:266 Spezial-Audit für Admin-Impersonation (SetNull-Tombstone) — Referenz-Muster, nicht direkt M21
FeatureFlagAudit prisma/schema/featureFlags.prisma:44 Append-only Flag-Audit — Beispiel für append-only-Pattern; Spec feature_flag.changed-Marker
PluginCapabilityUse / PluginInvocation prisma/schema/plugins.prisma Per-Capability-Audit mit eigener Hash-Chain (prevHash/rowHash) — Referenz-Muster für Tamper-Evidenz
QueueFailedJob prisma/schema/queue.prisma:1 Export-Job-Failure-Tracking

Komplett fehlende Modelle (Spec Block A Sub-Entitäten):

  • AuditRetentionPolicy (tenant-Admin Retention in Monaten + legal_hold_active/legal_hold_reason/legal_hold_set_by/at) — existiert NICHT
  • Saved-View / SavedAuditView (max 5/User, Spec Block F / 21.3.4) — existiert NICHT
  • AuditExportJob als dedizierte Audit-Variante mit filter_criteria + Zweck-Begründung — existiert NICHT (nur generisches ExportJob)

Lücken / komplett neu zu bauen

Daten-Layer

  1. Diff-Felder am AuditEvent — before_diff (JSONB), after_diff (JSONB), summary_text (DE-Klartext, Pflicht), actor_label, subject_label (Snapshot-Namen für Hard-Delete-Resistenz). Spec-zentral (Block D/E), in Boilerplate nicht vorhanden.
  2. actor_kind-Erweiterung — Boilerplate kennt user/admin/api_key/system/plugin; Spec braucht zusätzlich automation, ki_agent, platform_admin.
  3. AuditRetentionPolicy-Modell + tenant-Admin-Konfig 6–120 Monate (Default 24) + Legal-Hold-Felder (Block H) — neu.
  4. Saved-Views-Modell (max 5/User, geseedete Default-Ansichten) (Block F) — neu.
  5. GIN-Index auf metadata + Trigram-Index auf summary_text (Volltext) — Spec Block A; Boilerplate hat weder summary_text noch diese Indizes.
  6. Append-Only-DB-Trigger (UPDATE/DELETE-Block auf App-Role) — Spec verlangt DB-Trigger; Boilerplate setzt Append-Only nur auf App-Ebene (kein DELETE/UPDATE-Pfad im Code), kein DB-Trigger.

Domänen-Logik

  1. Cursor-Pagination (Spec: cursor-basiert, 100/Page, „Mehr laden") — Boilerplate logs.server.ts ist offset-basiert (take/skip).
  2. Erweiterte Filter — Actor-Kind, Subject-Type-Multi-Select, Subject-ID-Autocomplete, Bulk-Op-ID, IP-Filter (Forensik). Boilerplate-Where-Builder kennt nur action/url/userId/tenantId/Date.
  3. Sensible-Diff-Maskierung (HR/Portal/Secrets → nur „Wert geändert", permission-abhängig hr.read_all/audit.admin) — neu (Boilerplate redacted nur metadata-Keys generisch, kein permission-abhängiges Diff-Gating).
  4. Bulk-Op-Aggregat + Aufklapp-Logik (Geschwister-Entries derselben bulk_op_id) — neu.
  5. Vorschau-Count vor Export-Submit + Pflicht-Zweck-Begründung + Async-Job statt Direkt-Download (Block G) — Boilerplate-Tenant-Export ist synchroner Direkt-Stream.
  6. Legal-Hold-Logik im Retention-Worker (Pause für Tenant bei legal_hold_active) + Retention-Reduzierungs-Vorschau („ca. X Einträge betroffen") — neu.
  7. Permissions-Split — separates audit.admin (Export/Retention/Legal-Hold) vs. audit.read; Boilerplate hat nur ein …auditTrails.view. Legal Hold braucht zusätzlich tenant.admin UND audit.admin.

UI (größte Lücke)

  1. Tenant-Audit-Listen-View für Endnutzer (M151) — Tabelle/Stream mit Actor-Avatar, Action-Label (i18n), Subject klickbar, Summary-Text, relative/absolute Zeit, Quick-Filter, Date-Range, Saved-Views-UI. Boilerplate hat nur Admin-Log-Tabelle + Export-Form, keine Tenant-AuditEvent-Anzeige.
  2. Detail-View mit Diff-Visualisierung (Block E) — Skalar nebeneinander, JSON-Struktur-Diff, Sensible-Marker, Copy-request_id, „Ähnliche/Verlauf"-Links. Komplett neu.
  3. Per-Subject-Audit-Drawer in Detail-Views (Kontakt/Deal/Projekt) + Per-User-Audit-Drawer in Admin/users/:id (Block C) — neu, gegated audit.read.
  4. Settings-View (/admin/audit/settings) — Retention-Slider, Legal-Hold-Toggle mit Pflicht-Begründung, Hash-Integritäts-Prüf-Button (Phase 2-Backend existiert via verifyAuditChain). Neu.
  5. Export-Job-Übersicht + Anlage + Status/Download-Routen (/admin/audit/exports*) — neu (Boilerplate hat Form, keine Job-Übersicht).
  6. Klartext-Hinweise (Block L: leerer Trail, Subject gelöscht, Bulk-Op, Automation/KI-Bezug, Legal-Hold-Banner) — i18n-Keys neu.
  7. Sidebar-Eintrag (Gruppe EINSTELLUNGEN → Audit-Log, INTEGRATION-CONTRACTS §1) + Breadcrumbs — in HiveGrid-App-Shell neu zu registrieren.

Querschnitt

  1. Activity-Stream-Brücke (Block K: audit_event-Activity-Typ) — abhängig von M045; neu.
  2. Notifications bei Export-Fertigstellung (notify(), M011) — Wiring neu.

Empfohlenes Vorgehen

Phase 0 — M001-Fundament prüfen/erweitern (Voraussetzung):

  1. AuditEvent-Modell (core.prisma:55) übernehmen und um Spec-Felder erweitern: before_diff, after_diff, summary_text, actor_label, subject_label; actor_kind-Werte ergänzen. Forward-only Migration mit GIN-(metadata)- + Trigram-(summary_text)-Index. Append-Only-DB-Trigger ergänzen.
  2. Write-Path createAuditEvent()/publishAuditEventViaOutbox() (packages/db/src/audit-events.server.ts) + audit-hash.ts + Outbox-Consumer (audit-event-persist.ts) 1:1 übernehmen, Diff-/Summary-Felder ins Schema einziehen.

Phase 1 — M151 Anzeige (Wiederverwendung mittel, UI neu): 3. Listen-Query: logs.server.ts-Filter-/Where-/Pagination-Muster als Vorlage, neu gegen AuditEvent schreiben (Cursor-Pagination, erweiterte Filter Block F, withTenantScope()+withPermission() aus M004). 4. View-Model-Builder in packages/view-models (M013) — Listen-VM + Detail-VM (Diff-Strukturierung, Sensible-Maskierung, Snapshot-Labels) — neu, pure Functions + Zod. 5. UI komplett neu via Subframe-Adapter (M015): Listen-View, Detail-/Diff-View, Per-Subject/-User-Drawer. Sidebar + Breadcrumbs + i18n-Keys. 6. Saved-Views-Modell + Default-Ansichten-Seed — neu.

Phase 2 — M152 Export + Retention + Legal Hold: 7. Export: ExportJob-Modell (queue.prisma:27) + export-jobs.server.ts + dsgvo-export.ts-Muster übernehmen/anpassen (filter_criteria + Zweck-Begründung + Vorschau-Count). Serializer audit-pdf.ts/csv/json + S3-Multipart-Sink 1:1. Self-Audit audit.exported + notify() bei Fertigstellung. 8. Retention: audit-retention.ts-Worker anpassen — Policy von regulatory-scope-Tagen auf AuditRetentionPolicy (Monate, tenant-konfigurierbar) + Legal-Hold-Pause umstellen. Reduzierungs-Vorschau-Count. 9. Settings-UI (Retention/Legal-Hold/Integritäts-Prüfung) — neu; Hash-Verifikations-Backend (verifyAuditChain) ist bereits da.

Permissions (parallel, M27-abhängig): audit.read / audit.admin als atomare Bundle-Permissions definieren; Boilerplate-…auditTrails.view als Ausgangspunkt, aber splitten.


Notizen / Realitäts-Check

  • Das Boilerplate-Audit ist Compliance-Evidence-orientiert (SOC2/HIPAA/GDPR, Hash-Chain, regulatory-scope-Retention), nicht operativ-nachvollziehbar (Diff/Summary/Snapshot). Das ist die fundamentale Differenz: Tamper-Evidenz + Schreibpfad + Export-Pipeline sind vorbildlich vorhanden, aber der für HiveGrid-Endnutzer zentrale Diff-/Klartext-/Anzeige-Layer ist neu.
  • Der Boilerplate hat zwei Audit-artige Tabellen: AuditEvent (Compliance, core.prisma:55) und Log (Aktivitäts-/Row-Log, core.prisma:36). Die bestehende Listen-UI (audit-trails.tsx + logs.server.ts) läuft auf Log, nicht auf AuditEvent. Für M21 ist AuditEvent das richtige Modell — die Listen-Query muss umgehängt werden.
  • Phase-2-Features der Spec (Hash-Chain Block I) sind im Backend bereits implementiert (audit-hash.ts, verifyAuditChain) — nur das Verifikations-Tool-UI in den Settings fehlt. Das ist ein unerwarteter Vorsprung.
  • Kein before/after-Snapshot in M001-Prisma-Middleware-Default: AGENTS.md/INTEGRATION-CONTRACTS §6 sagen „Audit ist automatisch via Prisma-Middleware" — diese Middleware ist im Boilerplate nicht vorhanden (es gibt withAuditMiddleware für Service-Handler + createAuditEvent, aber keine generische Prisma-$extends-Middleware, die before/after automatisch erfasst). Das ist eine M001-Lücke, die M21 voraussetzt.