120 lines
17 KiB
Markdown
120 lines
17 KiB
Markdown
# 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.
|