17 KiB
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 AuditExportJobals dedizierte Audit-Variante mitfilter_criteria+ Zweck-Begründung — existiert NICHT (nur generischesExportJob)
Lücken / komplett neu zu bauen
Daten-Layer
- 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. actor_kind-Erweiterung — Boilerplate kenntuser/admin/api_key/system/plugin; Spec braucht zusätzlichautomation,ki_agent,platform_admin.AuditRetentionPolicy-Modell + tenant-Admin-Konfig 6–120 Monate (Default 24) + Legal-Hold-Felder (Block H) — neu.- Saved-Views-Modell (max 5/User, geseedete Default-Ansichten) (Block F) — neu.
- GIN-Index auf
metadata+ Trigram-Index aufsummary_text(Volltext) — Spec Block A; Boilerplate hat wedersummary_textnoch diese Indizes. - 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
- Cursor-Pagination (Spec: cursor-basiert, 100/Page, „Mehr laden") — Boilerplate
logs.server.tsist offset-basiert (take/skip). - 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.
- 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). - Bulk-Op-Aggregat + Aufklapp-Logik (Geschwister-Entries derselben
bulk_op_id) — neu. - Vorschau-Count vor Export-Submit + Pflicht-Zweck-Begründung + Async-Job statt Direkt-Download (Block G) — Boilerplate-Tenant-Export ist synchroner Direkt-Stream.
- Legal-Hold-Logik im Retention-Worker (Pause für Tenant bei
legal_hold_active) + Retention-Reduzierungs-Vorschau („ca. X Einträge betroffen") — neu. - Permissions-Split — separates
audit.admin(Export/Retention/Legal-Hold) vs.audit.read; Boilerplate hat nur ein…auditTrails.view. Legal Hold braucht zusätzlichtenant.adminUNDaudit.admin.
UI (größte Lücke)
- 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. - Detail-View mit Diff-Visualisierung (Block E) — Skalar nebeneinander, JSON-Struktur-Diff, Sensible-Marker, Copy-
request_id, „Ähnliche/Verlauf"-Links. Komplett neu. - Per-Subject-Audit-Drawer in Detail-Views (Kontakt/Deal/Projekt) + Per-User-Audit-Drawer in Admin/users/:id (Block C) — neu, gegated
audit.read. - Settings-View (
/admin/audit/settings) — Retention-Slider, Legal-Hold-Toggle mit Pflicht-Begründung, Hash-Integritäts-Prüf-Button (Phase 2-Backend existiert viaverifyAuditChain). Neu. - Export-Job-Übersicht + Anlage + Status/Download-Routen (
/admin/audit/exports*) — neu (Boilerplate hat Form, keine Job-Übersicht). - Klartext-Hinweise (Block L: leerer Trail, Subject gelöscht, Bulk-Op, Automation/KI-Bezug, Legal-Hold-Banner) — i18n-Keys neu.
- Sidebar-Eintrag (Gruppe EINSTELLUNGEN → Audit-Log, INTEGRATION-CONTRACTS §1) + Breadcrumbs — in HiveGrid-App-Shell neu zu registrieren.
Querschnitt
- Activity-Stream-Brücke (Block K:
audit_event-Activity-Typ) — abhängig von M045; neu. - Notifications bei Export-Fertigstellung (
notify(), M011) — Wiring neu.
Empfohlenes Vorgehen
Phase 0 — M001-Fundament prüfen/erweitern (Voraussetzung):
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.- 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) undLog(Aktivitäts-/Row-Log,core.prisma:36). Die bestehende Listen-UI (audit-trails.tsx+logs.server.ts) läuft aufLog, nicht aufAuditEvent. Für M21 istAuditEventdas 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 gibtwithAuditMiddlewarefür Service-Handler +createAuditEvent, aber keine generische Prisma-$extends-Middleware, die before/after automatisch erfasst). Das ist eine M001-Lücke, die M21 voraussetzt.