Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M27-auth-multi-tenancy.md
T

143 lines
24 KiB
Markdown

# Boilerplate-Mapping — M27 Auth / Multi-Tenancy / Rollen / Permissions
**Modul-ID:** M27 (HiveGrid-Modul 27)
**Name:** Anmeldung, Mandanten, Rollen & Permissions
**Milestones:** M018-M027 (M018 Mandanten-Anlage, M019 Mandanten-Trennung-Hardening, M020 Email/PW-Auth, M021 Magic-Link/Sessions, M022 TOTP-2FA, M023 Rollen-Engine/SHK-Rollen/Gruppen, M024 Mitarbeiter-Einladung/Deaktivierung, M025 Konto-Löschung, M026 Mandanten-Lebenszyklus, M027 API-Keys/Tarif-Gates)
**Block:** Block 1 — Plattform-Fundament (Pflichtenheft v1.1, §27)
**Reuse-Level:** **HIGH** — Die Boilerplate liefert ein nahezu vollständiges Auth/Tenancy/RBAC-Fundament inkl. Daten-Modelle, Service-Layer, fertige Settings-UI-Routen und Querschnitt-Helper. HiveGrid muss primär: (1) HiveGrid-spezifische Inhalte (SHK-Rollen-Template, Permission-IDs) einfüllen, (2) drei echte Architektur-Lücken schließen (Server-Side-Sessions in Postgres, Tenant-Lifecycle-Statusmaschine, Reassign-Workflow vor Deaktivierung), (3) das App-Level-Tenant-Scoping ggf. um Postgres-RLS härten (Spec A.4 — bauliche Vorgabe, in BP NICHT vorhanden).
> Verifiziert per direktem Read/Grep in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` (nicht nur Inventur). Stand der Vorphase-Inventur bestätigt; Abweichungen unten markiert.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/accounts.prisma` | `User`, `Tenant`, `TenantUser`, `TenantUserInvitation`, `MagicLinkToken`, `AdminUser`, `Registration`, `Blacklist`, `ImpersonationAudit`, `TenantIpAddress`, `WorkspaceAuthProvider`, `TenantType` | **anpassen** — Identity/Tenancy-Kern. User hat bereits `passwordHash`, `totpSecretEncrypted`/`totpPendingSecretEncrypted`/`totpEnabledAt`, `mfaRecoveryCodeHashes`, DSGVO-Flags (`pendingDeletion`/`scheduledDeletionAt`/`pseudonymized`/`deletionRequestId`), `defaultTenantId`. Felder zu ergänzen siehe Lücken. |
| `prisma/schema/permissions.prisma` | `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | **1:1** als RBAC-Fundament. `Role` ist tenant-scoped (`tenantId?`), hat `type`/`isDefault`/`assignToNewUsers`/`order`. `UserRole.tenantId?` (Multi-Rolle pro User + tenant-Scope). `Group`/`GroupUser` = exakt die orthogonalen Gruppen aus Spec C.4. Permission `name @unique` (global, atomar) + optional `entityId` (Entity-gebundene Rechte). Deckt C.1 (atomar gespeichert), C.3 (Multi-Rolle additiv), C.4 1:1 ab. |
| `prisma/schema/core.prisma` → `ApiKey`, `ApiKeyLog` | API-Key-Modell mit `keyHash`/`keyPrefix`/`keyLastFour`/`keyVersion` (gehashte Keys, einmalig sichtbar), `alias`, `expires`, `active`, `@@unique([tenantId, alias])`; `ApiKeyLog` für Request-Logging (ip/endpoint/method/status/duration) | **anpassen** — deckt Block E fast komplett (Anlage, Hash, Rotation, Logs). Lücke: Scopes (`read_only`/`webhook_inbound`/`read_full`/`automation_trigger`) + per-Tenant-Rate-Limit-Override + 365-Tage-Default fehlen als Felder. |
| `prisma/schema/core.prisma` → `AuditEvent` | Tamper-evidente Audit-Hash-Kette (`previousHash`/`eventHash`), `actorType`/`actorId`/`actorEmail`/`actorIp`, `dataSensitivity`, `regulatoryScope[]`, `outcome`, reichlich Indizes | **1:1** — Audit-Trail für C.5 (Rollen-/Permission-Änderungen geloggt), D-Lifecycle, E (API-Key-Anlage/Widerruf). Querschnitt M001. |
| `prisma/schema/subscriptions.prisma` (14 Modelle) + `packages/entitlements` | `SubscriptionProduct`/`SubscriptionPrice`/`SubscriptionFeature`/`TenantSubscription`/`TenantFeatureOverride` + Feature-Gate-Engine (`evaluateEntitlement`, `featureGateRegistry`, `featureKeys`, `evaluateProductAccess`, `productBlueprints` mit `crm-saas`) | **anpassen** — deckt Block F.1 (Subscription-Feature-Gates) als Engine ab; Datenmodell SubscriptionProduct→Features→TenantSubscription exakt wie Spec F.1. HiveGrid-Plan-Definitionen (Cloud/Cloud+/Enterprise) sind geparkt (Spec), daher nur Engine übernehmen, `featureKeys` mit HiveGrid-Keys erweitern. |
| `prisma/schema/featureFlags.prisma` | `FeatureFlag` (scope global/tenant/user, v2-Targeting `rules`/`variants`, `enabledFrom/Until`, Flag-Dependencies), `FeatureFlagFilter`, `FeatureFlagAudit` (append-only) | **1:1** — deckt Block F.2 (Feature-Flags, Modul 32) inkl. Filter-Regeln + Audit. |
| `apps/web/app/services/auth/totp.server.ts` (+ `utils/auth/mfa/recovery-codes.server.ts`, `enforcement.server.ts`, `step-up.server.ts`, `challenge-rate-limit.server.ts`) | TOTP-Enrollment (otpauth, SHA1/6-stellig/30s), QR/otpauth-URI, verschlüsseltes Secret (CryptoApi), 10 Recovery-Codes, Pending→Activate-Flow, MFA-Enforcement-Gate, Step-Up, Challenge-Rate-Limit (5/5min konfigurierbar) | **1:1 / anpassen** — deckt Block B.4 (TOTP, Backup-Codes, Setup-Flow) nahezu vollständig. Anpassen: Trust-Device-Cookie + Pflicht-2FA-Toggle pro Tenant (siehe Lücken). |
| `apps/web/app/services/auth/password-policy.server.ts` (+ `password-policy-banner.server.ts`, `password-reset-token.server.ts`) | Zentrale Passwort-Validierung, env-getrieben, HIBP-k-Anonymity-Check (`api.pwnedpasswords.com/range/`, Timeout 3s), Min-Length, bounded i18n-Error-Codes, Soft-Banner bei veraltetem PW, Reset-Token | **1:1** — deckt B.1 (≥12 Zeichen via Config, HIBP-Block mit Klartext, keine erzwungenen Sonderzeichen). Cost-Faktor: siehe `passwordHasher.server.ts`. |
| `apps/web/app/utils/auth/passwordHasher.server.ts` | Passwort-Hashing | **anpassen** — Spec B.1 verlangt bcrypt Cost 12; verifizieren/setzen. |
| `apps/web/app/services/auth/magic-link.server.ts` | Magic-Link: signierte Tokens, `MAGIC_LINK_TOKEN_TTL_MINUTES=15`, einmalig nutzbar (`consumeMagicLinkToken`), Purpose-gebunden, `MagicLinkToken`-Tabelle mit `tokenHash`/`consumedAt`/`expiresAt` | **1:1** — deckt B.2 (15-Min-TTL, einmalig) exakt. Rate-Limit 3/15min via auth-rate-limit ergänzen. |
| `apps/web/app/services/auth/auth-rate-limit.server.ts` | Rate-Limit für `login`/`forgot-password`/`reset-password`/`mfa`, IP+Identifier-gehasht, Window+Limit konfigurierbar, retryAfter | **1:1** — deckt B.1 (5/15min pro Email, IP-Limit) + B.2 + B.4. Captcha (hCaptcha) ab 3. Versuch fehlt (siehe Lücken). |
| `apps/web/app/utils/session.server.ts` | Cookie-Session-Storage (`createCookieSessionStorage`), `setLoggedUser` (löst defaultTenant → Fallback erster Tenant), Impersonation-Session-State + Validierung (TTL, Actor-Check), CSRF | **als-vorlage** — Login-Flow + Tenant-Resolution + Impersonation übernehmbar. ABER: Sessions sind **cookie-basiert, NICHT server-side in Postgres** — Spec B.5 verlangt explizit Postgres-Sessions (siehe Lücken). |
| `apps/web/app/utils/services/tenantService.ts` (+ `utils/app/UrlUtils.ts`, `app/PublicRouteSegments.ts`) | `normalizeTenantSlug`, `UrlUtils.slugify`, `isReservedTenantSlug`, `getAvailableTenantSlug` (Auto-Suffix `-2` bei Konflikt), Reserved-Slug-Set | **1:1 / anpassen** — deckt A.2 (Auto-Generierung, Eindeutigkeit, Reserved-Words, Vorschlag mit Nummer). Reserved-Word-Liste + Umlaut-Mapping (ae/oe/ue) + GmbH/AG-Suffix-Erhalt an HiveGrid-Regeln angleichen. |
| `apps/web/app/utils/services/rolesAndPermissionsService.ts` (+ `@toolctrl/db/permissions-seed.server`) | `seedRolesAndPermissions`, `defaultAppRoleSeeds`/`defaultAdminRoleSeeds`, `defaultPermissionSeedDescriptors`, `syncDefaultRolesAndPermissions`, Seed-Diagnostics | **als-vorlage** — Seeding-Mechanik 1:1 nutzbar. ABER Default-Rollen sind **generisch** (`SuperAdmin`/`SuperUser`/`Admin`/`Billing Admin`/`User`), NICHT die SHK-Rollen. SHK-Branchen-Template (C.2/27.7, 7-10 Rollen) ist als deklaratives Seed neu zu definieren. |
| `apps/web/app/components/layouts/selectors/TenantSelector.tsx` + `NewTenantSelector.tsx` (eingebunden in `routes/app.tsx`) | Tenant-Switcher-Komponente in der App-Shell | **anpassen** — deckt A.3/D.4 (Tenant-Switcher überall verfügbar). Suchfeld bei 5+ Tenants + `last_accessed_at`-Sortierung ergänzen (Feld fehlt, siehe Lücken). |
| `apps/web/app/routes/app.$tenant/settings/members.tsx` (+ `members/groups`) | Mitarbeiter-Verwaltung + Einladungs-Flow (nutzt `TenantUserInvitation`) | **anpassen** — Basis für D.1 (Einladung mit Rolle/Groups/Nachricht, 7-Tage-Token, 3 Pfade). Reassign-Workflow vor Deaktivierung fehlt. |
| `apps/web/app/routes/app.$tenant/settings/roles-and-permissions.tsx` (+ `roles-and-permissions/roles`, `components/core/roles`) | Rollen-Editor-UI (Liste, Anlegen, Permissions, Matrix-Test vorhanden) | **anpassen** — Basis für C.3 (Editor, neue Rolle, „Basieren auf", Duplizieren, Löschen mit Reassign). Bundle/Advanced-Mode-Toggle (C.1) und Permission-Preview-Tool (C.5) ergänzen. |
| `apps/web/app/routes/app.$tenant/settings/groups.tsx` | Gruppen-Editor | **1:1 / anpassen** — deckt C.4 (Anlegen/Umbenennen/Löschen, Mitglieder, Description). |
| `apps/web/app/routes/app.$tenant/settings/api/keys/` (`keys.tsx`, `new.tsx`, `$id.tsx`) + `api/logs.tsx`, `api/docs.tsx` | API-Key-Settings-UI inkl. Anlage, Detail, Logs | **anpassen** — deckt Block E-UI (Liste, einmalig sichtbarer Key, Logs der Anfragen). Scope-Auswahl + Rate-Limit-Override ergänzen. |
| `apps/web/app/routes/app.$tenant/settings/account.tsx` + `privacy.tsx` + `privacy.delete.confirm.$token.tsx` + `privacy.delete-mail` | Account-Löschung (Multi-Step), DSGVO-Privacy, Token-Bestätigung | **anpassen** — deckt D.3 (Multi-Step-Löschung, PII-Überschreibung, 24h-Reverse via Email-Token). Last-Tenant-Admin-Block + 3-Sek-Countdown ergänzen. Cascade-Karte in `packages/db/src/dsgvo/user-fk-map.ts` ist Pflicht-Referenz. |
| `apps/web/app/routes/app.$tenant/settings/profile.tsx` (+ `profile.mfa`, `profile.session`, `profile.locale-picker`, `theme.tsx`) | Persönliche Settings: 2FA-Setup, Session-Übersicht, Sprache, Theme | **anpassen** — deckt B.5-UI (Session-Liste/Revoke) + B.4-UI (2FA-Setup) + Persönliche `/settings/`. Trust-Device-Liste mit Revoke ergänzen. |
| `apps/web/app/routes/app.$tenant/settings/audit-export.tsx` + `logs/` | Audit-Log-UI + Export | **1:1** — Audit-Log-Anzeige für C.5. |
| `packages/foundation/src/permissions.ts` | `requirePermission`, `withTenantScope`, `withPermission`, `withOwnerCheck` | **1:1** — Querschnitt-Helper (Spec AV #5 Permissions-aware-Default, AGENTS.md DoD C.17). Exakt die in INTEGRATION-CONTRACTS §10 referenzierte API. |
| `packages/foundation/src/{audit,notifications,flags,concurrency,idempotency,errors}.ts` | Audit-Helper, Notify, Feature-Flag-Eval, Concurrency (Last-Write-Wins), Idempotenz, Catalog-Errors | **1:1** — Querschnitt für C.5 (Concurrent-Update Last-Write-Wins), D.3-Notify, F.2, Klartext-Errors (M002). |
| `packages/db/src/{client.server,transactions.server,outbox,audit-hash}.ts` + `dsgvo/user-fk-map.ts`, `dsgvo/pseudonymize.ts` | Prisma-Client-Grenze, Transaktionen, Outbox, Audit-Hash, DSGVO-FK-Karte + Pseudonymisierung | **1:1** — Fundament für jede schreibende Aktion (Audit/Outbox), D.3-Pseudonymisierung. |
| `packages/db/src/{users,accounts,api-keys,auth-boundary,auth-providers,device-tokens,impersonation-audit,workspace-invites,permissions-seed,entitlements-seed,subscriptions,settings}.server.ts` | Repository-Befehlsfläche für alle Auth/Tenancy-Domänen | **1:1 / anpassen** — DB-Layer-APIs direkt nutzbar; je Repo-Methode neue HiveGrid-Felder durchreichen. |
| `apps/web/app/utils/services/admin*` + `services/auth/admin-mfa-gate.server.ts`, `admin-fallback.server.ts` | Admin-Panel-Auth (Pflicht-2FA, Fallback-Admin) | **als-vorlage** — relevant für Plattform-Admin (Modul 37, außerhalb M27-Kern, aber `AdminUser`-Modell + Pflicht-2FA-Gate direkt nutzbar). |
| `packages/shared-store` | Redis-KV: `createFixedWindowRateLimiter`, `createSlidingWindowRateLimiter`, `createSessionStore`, `createIdempotencyStore`, Cache mit Tenant-Präfix | **1:1** — Cross-Replica-Rate-Limit (B.1/B.2/B.4, Spec verlangt mehr als der In-Memory-`cache` in auth-rate-limit), Cache-Isolation `tenant:{id}:` (A.4), Session-Store falls hybrid. |
---
## Vorhandene Daten-Modelle (konkret, mit Pfad)
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
**accounts.prisma:**
- `User` — `email @unique`, `passwordHash?`, `firstName`/`lastName`/`avatar`/`phone`, `defaultTenantId?`, `verifyToken`, TOTP (`totpSecretEncrypted`, `totpPendingSecretEncrypted`, `totpEnabledAt`, `totpPendingCreatedAt`), `mfaRecoveryCodeHashes Json`, `mfaRecoveryCodesGeneratedAt`, `active`, DSGVO (`pendingDeletion`, `scheduledDeletionAt`, `deletionRequestedAt`, `pseudonymized`, `pseudonymizedAt`, `deletionRequestId @unique`), `locale`, `lightOrDarkMode`. **Hat noch `githubId`/`googleId @unique` (Boilerplate-OAuth — EU-Sterilisation pending, für M27-Scope irrelevant/zu entfernen).**
- `Tenant` — `slug @unique`, `name`, `icon`/`logo`, `subscriptionId?`, `active`, `deactivatedReason?`, `theme`/`themeConfig`. **Kein Lifecycle-Status-Enum, kein `lastAccessedAt`.**
- `TenantUser` — Membership (`tenantId`, `userId`, `type Int`, `joined Int`, `status Int` — Int-codiert, kein Enum).
- `TenantUserInvitation` — `email`, `firstName`/`lastName`, `type Int`, `pending`, `status @default("pending")`, `tokenHash?`/`tokenPrefix?`, `expiresAt?`, `acceptedAt?`/`revokedAt?`, `createdUserId?`/`fromUserId?`/`acceptedByUserId?`/`revokedByUserId?`. Indizes auf `(tenantId,status,expiresAt)`, `(tenantId,email,status)`, `(tenantId,tokenPrefix)`.
- `MagicLinkToken` — `tokenHash @unique`, `expiresAt`, `consumedAt?`, FK User Cascade.
- `AdminUser` — Plattform-Admin-Panel-Zugang (+ OIDC-SSO-Felder `ssoProvider`/`ssoSubjectId`/`ssoGroups`/`lastSsoLoginAt`).
- `Registration` — Self-Service-Signup-Staging (`email @unique`, `slug?`, `token @unique`, `company?`, `selectedSubscriptionPriceId?`, Lead-Conversion-Felder, `createdTenantId?`).
- `Blacklist` (email/domain/ip), `TenantIpAddress`, `ImpersonationAudit` (Actor/Target/Tenant SetNull), `WorkspaceAuthProvider` (SSO/SAML/OIDC pro Tenant), `TenantType`.
**permissions.prisma:**
- `Role` (`tenantId?`, `name`, `description`, `type`, `assignToNewUsers`, `isDefault`, `order`, `@@unique([tenantId, name])`), `Permission` (`name @unique` global atomar, `type`, `isDefault`, `order`, `entityId?`), `RolePermission`, `UserRole` (`tenantId?`, partielle Eindeutigkeit via Migration-SQL), `Group` (`tenantId?`, `name`, `description`, `color`), `GroupUser`.
**core.prisma:** `ApiKey` (gehasht), `ApiKeyLog`, `AuditEvent` (Hash-Kette), `IdempotencyKey`, `Credential` (Secret-Store), `Event`/`EventWebhookAttempt`, `Log`, `IpAddress`/`IpAddressLog` (Geolocation für Session-Standort B.5).
**subscriptions.prisma:** `SubscriptionProduct`, `SubscriptionPrice`, `SubscriptionFeature`, `TenantSubscription`, `TenantFeatureOverride` (`@@unique([tenantId, featureKey])`), `TenantProductConfiguration` (`blueprintId` default `crm-saas`) — Block-F.1-Fundament.
**featureFlags.prisma:** `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` — Block-F.2-Fundament.
**notifications.prisma:** `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` — für D.3-Lösch-Notification + B.5-Push-Token-Cleanup.
---
## Lücken / komplett neu zu bauen
Verifiziert per Grep — folgendes existiert in der Boilerplate **NICHT** und ist neu zu bauen:
1. **Server-Side-Sessions in Postgres (B.5) — ARCHITEKTUR-LÜCKE.** Boilerplate nutzt `createCookieSessionStorage` (Cookie-only, `apps/web/app/utils/session.server.ts:124`). Es gibt **kein** `Session`/`UserSession`/`AuthSession`-Prisma-Modell (Grep leer). Spec B.5 verlangt explizit Postgres-Sessions wegen Logout/Revoke, Session-Liste mit Gerät/Browser/IP/Standort/Letzte-Aktivität, globalem „Von allen Geräten abmelden", 4h-Inaktivitäts-Timeout, 30-Tage-Sliding-Window, Auto-Logout bei PW/2FA/Email-Änderung. → **Neues `Session`-Modell + Session-Service neu bauen.** (`profile.session.tsx`-UI existiert als Hülle, Backend fehlt.)
2. **Postgres Row-Level-Security (A.4) — ARCHITEKTUR-LÜCKE.** Kein `current_setting('app.tenant_id')`, kein `SET LOCAL`, keine RLS-Policy-Migrations (Grep nur Doku/Tests, keine `ENABLE ROW LEVEL SECURITY`). Boilerplate-Tenant-Isolation ist **App-Level** (`withTenantScope`, repo-Filter, `tenant-scoped.ts`-Wrapper). Spec A.4 schreibt RLS als bauliche Vorgabe vor (Policy USING/WITH CHECK, App-Role ohne BYPASSRLS, Middleware `SET LOCAL app.tenant_id`). → **RLS-Layer neu (Migration + Request-Middleware + Worker-Job-Context)** — M019.
3. **Tenant-Lifecycle-Statusmaschine (A.5 / 27.11) — FEHLT.** `Tenant` hat nur `active: Boolean` + `deactivatedReason?`, **kein** Status-Enum. Status-Werte `trial/active/past_due/frozen/suspended/deletion_pending/deleted`, Übergänge, Frozen-Read-Only-Rechte-Matrix, Statusabhängige UI-Banner, 30-Tage-Grace-Cron — alles neu. → **Tenant-Status-Feld/Enum + State-Machine + Banner + Cron** — M026.
4. **Reassign-Workflow vor Deaktivierung/Entfernen (D.2 / 27.9.5) — FEHLT.** Kein `reassign`/`handover`/`orphan`-Code in `apps`. Anzeige offener Verknüpfungen pro Typ (Deals/Projekte/Tasks/Termine), Bulk-Reassign, Einzel-Reassign, „verwaist lassen"-Override mit Bestätigung. → Neu (querschnittlich, braucht spätere Modul-Entitäten). — M024.
5. **SHK-Branchen-Rollen-Template (C.2 / 27.7) — FEHLT (generische Seeds vorhanden).** `defaultAppRoleSeeds` = `SuperUser/Admin/Billing Admin/User` (generisch). Die 7-10 SHK-Rollen (GF, Vertriebsleiter, Vertriebler, Projektleiter, Büro, Buchhaltung, Personal, Lagerist, Marketing, Monteur) inkl. Default-UI-Modus (Büro/Baustelle) und Permission-Bundles sind als **deklaratives Branchen-Template** neu zu schreiben (Seeding-Mechanik selbst ist wiederverwendbar). — M023.
6. **Permission-Bundle/Advanced-Mode + Permission-IDs (C.1) — FEHLT.** Permissions sind atomar gespeichert (vorhanden), aber die Variante-2-Bundle-Stufen (`crm.none/read_own/read_all/write/admin`), der Advanced-Mode-Toggle und „Benutzerdefiniert"-Erkennung sind neu. Konkrete HiveGrid-Permission-IDs entstehen modulweise (Spec offen). — M023.
7. **`Tenant.lastAccessedAt` pro Membership (A.3 / D.4) — FEHLT.** Kein Feld für Default-Sortierung des Switchers / „letzter genutzter Tenant". → Feld auf `TenantUser` ergänzen + im Switcher (Suchfeld bei 5+) verdrahten. — M019/M018.
8. **Trust-Device / „30 Tage merken" (B.4) — FEHLT.** Kein `trustedDevice`/`rememberDevice`-Code (Grep leer). Signed-Cookie umgeht 2FA 30 Tage + Trust-Device-Liste mit Revoke neu. — M022.
9. **Pflicht-2FA-Toggle pro Tenant (B.4 / 27.4.3) — FEHLT.** MFA-Enforcement existiert für Admin-Panel (`admin-mfa-gate.server.ts`), aber nicht der Tenant-weite „2FA für alle Pflicht"-Toggle (zwingt User ohne 2FA beim nächsten Login). → Tenant-Setting + Enforcement-Erweiterung. — M022.
10. **Captcha ab 3. Fehlversuch (B.1 / 27.3.5) — FEHLT.** `AppConfiguration.authRecaptchaSiteKey` existiert als Feld, aber keine hCaptcha-Integration/Trigger-Logik. Spec verlangt hCaptcha (DSGVO). — M020.
11. **API-Key-Scopes + Rate-Limit-Override + 365-Tage-Default (Block E) — TEILWEISE.** `ApiKey`-Modell hat keine Scope-Spalte; Scopes (`read_only`/`webhook_inbound`/`read_full`/`automation_trigger`), per-Tenant-Rate-Limit-Override (1000/h Default, erhöhbar) und 365-Tage-Zwangs-Ablauf neu. — M027.
12. **Signup-Formular-Felder (A.1 / 27.1.2-3) — TEILWEISE.** `Registration` hat `company`/`slug`, aber nicht: Branche (SHK-preselect, andere „Coming soon"), Firmengröße-Dropdown, AGB/DSGVO/AVV-Akzeptanz-Checkboxen (AVV elektronisch unterschrieben), USt-Id, Telefon. → Felder + Formular-Validierung ergänzen. — M018.
13. **Slug-Live-Validierung beim Tippen (A.2, debounced 500ms) — TEILWEISE.** Server-Funktionen (`getAvailableTenantSlug`, `isReservedTenantSlug`) vorhanden; debounced Live-Check-Endpoint + Umlaut-Mapping (ae/oe/ue) + Suffix-Erhalt (GmbH) ergänzen. — M018.
14. **HiveGrid-UI-Layer (`packages/ui-hivegrid`, Subframe-Adapter, View-Models, sidebar.config) — NEU.** Boilerplate-UI liegt in `apps/web/app/routes` + `components/core` (klassisch, kein VM/Adapter-Pattern). HiveGrid-DoD verlangt VM-Layer (`packages/view-models`), `ui-hivegrid`-Adapter, `sidebar.config.ts`-Eintrag „Mitarbeiter & Rollen" (Gruppe Einstellungen), i18n-Keys. Boilerplate-Routen sind **als-vorlage** (Logik/Felder), nicht 1:1 (Layer-Disziplin AGENTS.md §A). — alle Milestones.
15. **Domain-/Pseudonymisierungs-Erweiterung der `user-fk-map.ts` — PFLICHT bei neuen User-FKs.** Jedes neue M27-Modell mit User-FK muss in `packages/db/src/dsgvo/user-fk-map.ts` eingetragen werden (CI-Test bricht sonst).
---
## Empfohlenes Vorgehen
**Phase 1 — Fundament 1:1 aktivieren (geringes Risiko, größter Hebel):**
1. Prisma-Modelle `accounts.prisma` + `permissions.prisma` + `core.prisma`(ApiKey/AuditEvent) + `featureFlags.prisma` + `subscriptions.prisma` als HiveGrid-Schema übernehmen (in `prisma/schema/` — sind bereits Teil der Codebase). `githubId`/`googleId` im Zuge der EU-Sterilisation entfernen.
2. Querschnitt-Helper aus `packages/foundation` (`permissions.ts`, `audit`, `notifications`, `flags`, `concurrency`, `errors`) + `packages/db`-Repos + `packages/entitlements` + `packages/shared-store` aktivieren — sie sind die in INTEGRATION-CONTRACTS/AGENTS referenzierten APIs.
3. Auth-Services 1:1 verdrahten: `totp.server.ts` (+ mfa/*), `password-policy.server.ts`, `magic-link.server.ts`, `auth-rate-limit.server.ts` (auf `shared-store`-Rate-Limiter umstellen statt In-Memory-cache).
**Phase 2 — Architektur-Lücken schließen (M019/M021/M026 — die drei echten Neubauten):**
4. **Server-Side-Sessions** (B.5): neues `Session`-Prisma-Modell + Session-Service (Erstellen/Laden/Revoke/Liste, Sliding-Window, Inaktivitäts-Timeout, Auto-Logout-Trigger). Cookie hält nur Session-ID-Referenz. — M021.
5. **RLS-Härtung** (A.4): RLS-Policies als Forward-Migration (Inverse-SQL als Kommentar, AGENTS §F.28), Request-Middleware `SET LOCAL app.tenant_id`, App-Role ohne BYPASSRLS, Worker-Job-Tenant-Context-Wrapper, Cache-Präfix `tenant:{id}:`, S3-Pfad `tenants/{id}/`. Sonderfälle ohne RLS: `users`/`subscription_plans`/`feature_flags`/`branchen_templates`. — M019.
6. **Tenant-Lifecycle** (A.5): `Tenant.status`-Enum + State-Machine + Frozen-Read-Only-Gate (write-blockierend) + Status-Banner + 30-Tage-Grace-Cron. — M026.
**Phase 3 — HiveGrid-Inhalte einfüllen (auf Fundament):**
7. **SHK-Rollen-Template** (C.2): deklaratives Branchen-Seed (10 Rollen + UI-Modus + Bundle-Permissions) über die vorhandene `seedRolesAndPermissions`-Mechanik; bei Tenant-Anlage mit Branche=SHK seeden. — M023.
8. **Permission-Bundles + Advanced-Mode** (C.1) + konkrete HiveGrid-Permission-IDs (modulweise) + `featureKeys`-Erweiterung in entitlements. — M023.
9. **Signup-Formular** (A.1) + Slug-Live-Validierung (A.2) + `lastAccessedAt` + Tenant-Switcher-Suchfeld. — M018.
10. **Mitarbeiter-Lifecycle**: Einladung (D.1, drei Pfade) auf vorhandenem `TenantUserInvitation` + **Reassign-Workflow** (D.2, neu) + Deaktivieren/Entfernen + Last-Admin-Schutz. — M024.
11. **Konto-Löschung** (D.3) auf vorhandener `privacy.delete.*`-Hülle + `user-fk-map.ts`-Pseudonymisierung + Multi-Step/3-Sek-Countdown/Last-Admin-Block. — M025.
12. **2FA-Ergänzungen**: Trust-Device-Cookie + Pflicht-2FA-Tenant-Toggle. — M022. **Captcha** (hCaptcha) bei Login. — M020.
13. **API-Keys** (Block E): Scopes + Rate-Limit-Override + 365-Tage-Ablauf auf vorhandenem `ApiKey`-Modell/UI. — M027.
14. **Feature-Gating** (Block F): entitlements-Engine + `featureFlags`-Modell verdrahten, `requireTenantFeatureAccess`-Loader-Convention + Klartext-Boundary mit Marketing-Link. — M027.
**Querschnitt durchgängig:** Alle UI als VM + `ui-hivegrid`-Adapter (nicht Boilerplate-Routen direkt), `sidebar.config.ts`-Eintrag „Mitarbeiter & Rollen" (Gruppe Einstellungen) mit Permission-Gate, i18n-Keys, Audit auto via Middleware, Smoke-Tests + Hot-Swap-Drill (AGENTS.md DoD).
---
## Notizen / Realitäts-Check
- **EU-Sterilisation:** `apps/web/app/routes/oauth/github` + `User.githubId`/`googleId` sind noch vorhanden (Boilerplate-OAuth). Für M27 (Spec: nur Email+PW+Magic-Link+TOTP, kein Google/GitHub/MS) im Zuge des Pre-Flight-Checks (AGENTS.md) zu entfernen. `WorkspaceAuthProvider` (SAML/OIDC) ist Enterprise-SSO-Vorrat, in Phase 1 nicht beauftragt.
- **Admin-Panel-Auth** (`AdminUser`, `admin-mfa-gate.server.ts`) gehört strenggenommen zu Modul 37 (Plattform-Admin), ist aber als Fundament für `admin.hivegrid.de` direkt vorhanden.
- **Sessions cookie-basiert** ist der wichtigste Befund: Spec B.5 ist hier inkompatibel mit dem Boilerplate-Default und erzwingt einen echten Neubau (Postgres-Session-Tabelle), nicht nur Anpassung.
- **RLS fehlt komplett** — die Boilerplate setzt vollständig auf App-Level-Scoping. Spec A.4 macht RLS zur baulichen Vorgabe; das ist eine substanzielle, separat zu testende (Pen-Test-Suite, M019-Erfolgskriterium) Erweiterung.