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

120 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
7. **Cursor-Pagination** (Spec: cursor-basiert, 100/Page, „Mehr laden") — Boilerplate `logs.server.ts` ist **offset-basiert** (take/skip).
8. **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.
9. **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).
10. **Bulk-Op-Aggregat + Aufklapp-Logik** (Geschwister-Entries derselben `bulk_op_id`) — **neu**.
11. **Vorschau-Count vor Export-Submit** + **Pflicht-Zweck-Begründung** + **Async-Job statt Direkt-Download** (Block G) — Boilerplate-Tenant-Export ist synchroner Direkt-Stream.
12. **Legal-Hold-Logik** im Retention-Worker (Pause für Tenant bei `legal_hold_active`) + Retention-Reduzierungs-Vorschau („ca. X Einträge betroffen") — **neu**.
13. **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)
14. **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.
15. **Detail-View mit Diff-Visualisierung** (Block E) — Skalar nebeneinander, JSON-Struktur-Diff, Sensible-Marker, Copy-`request_id`, „Ähnliche/Verlauf"-Links. **Komplett neu.**
16. **Per-Subject-Audit-Drawer** in Detail-Views (Kontakt/Deal/Projekt) + **Per-User-Audit-Drawer** in Admin/users/:id (Block C) — **neu**, gegated `audit.read`.
17. **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.**
18. **Export-Job-Übersicht + Anlage + Status/Download-Routen** (`/admin/audit/exports*`) — **neu** (Boilerplate hat Form, keine Job-Übersicht).
19. **Klartext-Hinweise** (Block L: leerer Trail, Subject gelöscht, Bulk-Op, Automation/KI-Bezug, Legal-Hold-Banner) — i18n-Keys neu.
20. **Sidebar-Eintrag** (Gruppe EINSTELLUNGEN → Audit-Log, INTEGRATION-CONTRACTS §1) + Breadcrumbs — in HiveGrid-App-Shell neu zu registrieren.
### Querschnitt
21. **Activity-Stream-Brücke** (Block K: `audit_event`-Activity-Typ) — abhängig von M045; **neu**.
22. **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.