# Customer-Portal: Erst-Rollout und Betrieb Dieses Runbook beschreibt den sicheren Erst-Rollout von VA-P26a sowie die vorbereiteten VA-P26b-/VA-P26c-Verträge. Es enthält nur Schlüsselnamen und Platzhalter. Ressourcen-IDs, URLs mit Zugangsdaten, Passwörter, Tokens und Live-Konfiguration gehören ausschließlich in die freigegebenen Secret- und Betriebswerkzeuge. **Stand 2026-07-22:** `VA-P26a`, `VA-P26b` und `VA-P26c` sind technisch vollständig. Der aktuelle Produkt- und UX-Vertrag einschließlich Tenant-Logo, Endkundenreisen und Designgrenzen steht in [`docs/features/customer-portal.md`](../features/customer-portal.md). PR `#212` wurde als Main-Revision `090e2558a6965e1c5804eb24d3eab5da8c8611a8` erfolgreich nach Staging ausgerollt. Core und Portal verwenden denselben Web-Digest; Health, Readiness, alle abhängigen Dienste und der revisionsgebundene Domain-Controller sind grün. Produktion wurde durch diesen UI-/Branding-Release nicht verändert. | Ticket | Aktueller Stand | Formales Abschluss-Gate | | --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `VA-P26a` | 8/8 DoD = 100 % | technischer Handoff abgeschlossen; finaler Design-Polish bleibt `VD-P26` | | `VA-P26b` | 6/6 DoD = 100 % | technischer Handoff abgeschlossen; finaler Design-Polish bleibt `VD-P26` | | `VA-P26c` | 8/8 DoD = 100 % | technischer Handoff abgeschlossen; Produktion bleibt eine separate Freigabe | ## Abschlussnachweis des Basis-Deploys - Feature-Merge: PR `#125`; Deploy-Hotfixes: PR `#130` und `#132`. - Finaler Lauf: [`#10300`](https://git.hg-int.dev/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300), exakte Revision `f54b04162b2823b1d2f6db0318baf1a7431c5b66`, vollständig grün für Staging und Produktion. - Forward-only Migration: `prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql`, ausgeführt im einmaligen eingeschränkten Migrator-Container. - Migration-Chain-Parität, exakter Tenant-Policy-Vertrag, RLS-Release-Readiness und Live-RLS- Isolation waren grün. App, Worker und Portal verwenden getrennte Runtime-Rollen über PgBouncer. - `hivegrid-web` und `hivegrid-portal` liefen aus demselben gepinnten Image/Digest; beide bestanden `/healthz` und `/readyz` mit der erwarteten Revision. Hard-Caps und getrennte Pool-Limits waren Bestandteil des Deploy-Preflights. Dieser Nachweis erfüllt das Merge-/RLS-Gate von VA-P26a/b. Er ersetzt nicht den UAT-Tenant, Browser-Klickpfade, Billing-Provider-Proof oder die VA-P26c-Controller-/Custom-Domain-/TLS-Gates. ## Zielbild `hivegrid-web` und `hivegrid-portal` sind zwei getrennte Coolify-Ressourcen aus demselben unveränderlichen `hivegrid/web:`-Image und demselben Registry-Digest. Die Core-Ressource läuft als `hivegrid_app`; die Portal-Ressource ausschließlich als `hivegrid_portal`. Der Deploy-Workflow provisioniert weder die Portal-Ressource noch einen DNS-Eintrag; die bereits bestehende Worker-Reconciliation bleibt davon unberührt. Für den Portal-Rollout akzeptiert er nur vorab angelegte, eindeutig allowlistete Ressourcen und bricht bei Abweichungen vor dem Rollout ab. Standardhosts: - Staging: `staging-portal.hivegrid.de` - Produktion: `portal.hivegrid.de` - Kundeneigene Hosts wie `portal.geerkens.de` gehören zu VA-P26c. Claim, sichere Host-/Session- Auflösung und Admin-Self-Service sind lokal vorbereitet; eine Annahme im Live-Ingress erfolgt erst nach den unten beschriebenen Controller-, TLS-, Merge- und Staging-Gates. ## Harte Vorbedingungen vor dem Main-Merge Der Main-Workflow prüft das Coolify-Inventar und die Runtime-Grenzen vor der Migration und bricht bei Abweichungen ohne Schemaänderung ab. Trotzdem müssen alle folgenden Punkte bereits vor dem Merge erfüllt sein: 1. Ein aktueller Backup-/Restore-Punkt ist bestätigt. Für Produktion ist zusätzlich ein dokumentierter Restore-Drill gemäß Estate-Standard erforderlich. 2. `pnpm run db:roles:provision` wurde mit den fünf getrennten Passwort-Keys aus dem Secret-Store ausgeführt. `hivegrid_portal` ist danach `LOGIN`, `NOINHERIT`, `NOBYPASSRLS`, kein Superuser und hat keine Rollenmitgliedschaft. 3. PgBouncer enthält einen eigenen SCRAM-Eintrag für `hivegrid_portal`, wurde neu geladen und akzeptiert den Portal-Login. Details stehen in [`docs/ops/pgbouncer.md`](../ops/pgbouncer.md). 4. `hivegrid-portal` ist in Staging gestoppt beziehungsweise noch nicht öffentlich erreichbar angelegt, verwendet dasselbe Web-Image wie `hivegrid-web` und steht in der Staging-Ressourcen-Allowlist. Vor einer Produktion-Promotion gilt dasselbe für Produktion. 5. Bestehende Runtime-Ressourcen enthalten weder `DIRECT_URL`, `MIGRATE_ON_BOOT`, `SEED_ON_BOOT`, `SEED_*` noch `MIGRATOR_*`. Diese Schlüssel gehören nur in den kurzlebigen Migrationsschritt. 6. Core-Web und Portal haben in Coolify jeweils positive, explizite Hard-Caps in `limits_cpus` und `limits_memory`; Portal und Core haben getrennte PgBouncer-Zugangsdaten und bewusst gesetzte Pool-Limits. `0`/`unlimited`, nur `limits_cpu_shares` oder nur eine Memory-Reservation zählen nicht als Hard-Cap. Für den ersten Produktionsrollout sind Core mit 2 vCPU/2 GB und `DATABASE_POOL_MAX=10` sowie Portal mit 1 vCPU/1 GB und `DATABASE_POOL_MAX=5` je Prozess/Instanz festgelegt. Spätere Anpassungen erfolgen nur anhand gemessener Last und bleiben als explizite Hard-Caps dokumentiert. 7. `worker-mail` erhält denselben `PORTAL_APP_HOST` wie die Portal-Ressource, damit Status-Mails keine aus `APP_BASE_DOMAIN` abgeleitete falsche URL erzeugen. 8. `worker-mail` erhält exakt denselben `CRYPTO_SECRET` wie `hivegrid-web`. Ohne diesen gemeinsamen Envelope-Key müssen Worker-Start, Healthcheck und Deploy-Preflight fail-closed abbrechen; der Wert darf nie geloggt werden. 9. `worker-general` erhält `LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_TIMEOUT_MS`, `MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID` und `MOLLIE_TIMEOUT_MS` aus dem freigegebenen Coolify-Secret-/Env-Source. Fehlende Provider-Keys oder ungültige gesetzte Timeouts müssen im Deploy-Preflight beziehungsweise beim Required-RLS-Start fail-closed abbrechen. `MOLLIE_PROFILE_ID` bleibt optional. 10. `hivegrid-web`, `hivegrid-portal`, `worker-import` und `worker-general` verwenden denselben privaten Bucket sowie dieselben normalisierten Werte für `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET` und `STORAGE_FORCE_PATH_STYLE`. Ein vorhandenes gemeinsames `STORAGE_ACCESS_KEY_ID`-/`STORAGE_SECRET_ACCESS_KEY`-Paar ist für alle vier Ressourcen zulässig und kein Rollout-Blocker; getrennte Credentials bleiben optional. Nur Core, Portal und Import-Worker erhalten exakt denselben `GDPR_EXPORT_SSE_C_KEY_BASE64`; der reine Lösch-Worker benötigt und erhält diesen Customer-Key nicht. `STORAGE_SESSION_TOKEN` wird nur gesetzt, wenn das jeweilige Credential ihn tatsächlich benötigt. Fehlende Pflichtwerte, ein nicht-HTTPS-Endpoint oder ein nicht kanonisch Base64-kodierter 32-Byte-Key brechen den Produktionsstart fail-closed ab. Die lokale Staging-Compose-Referenz bildet dieselbe Konfiguration über die host-seitigen Quellen `WEB_STORAGE_*`, `WORKER_IMPORT_STORAGE_*` und `WORKER_GENERAL_STORAGE_*`; diese Quellen dürfen auf dasselbe Credential zeigen. Die Portal-Ressource bleibt eine separate Coolify-Resource mit vollständig gesetzten `STORAGE_*`-Werten. Der Deploy-Preflight prüft Vollständigkeit und gemeinsame Storage-Zielwerte, vergleicht oder protokolliert die Credential-Werte jedoch nicht. `worker-import` und `worker-general` müssen für die gemeinsame Tenant-Export-Barriere außerdem denselben normalisierten Redis-Endpunkt und dieselbe Redis-Datenbank verwenden. Dafür gilt effektiv ein nichtleeres `REDIS_URL`, sonst `BULLMQ_REDIS_URL`; Zugangsdaten dürfen getrennt sein. Fehlende, ungültige oder abweichende Ziele brechen den Deploy-Preflight ab, ohne Redis-URLs auszugeben. 11. `worker-general` erhält zusätzlich `MEILI_URL` und den HiveGrid-scoped `MEILI_API_KEY`. In Production, required-RLS sowie Staging-/Production-Sentry muss der Worker vor Queue-Ownership abbrechen, wenn Wert oder Search-Client fehlen; ein Tenant-Hard-Delete darf sonst nicht erfolgreich abschließen. ## Runtime-Matrix | Bereich | `hivegrid-web` | `hivegrid-portal` | `worker-mail` | | --------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Surface | `WEB_RUNTIME_SURFACE=core` | `WEB_RUNTIME_SURFACE=portal` | nicht setzen | | DB-Rolle | `DATABASE_RUNTIME_ROLE=hivegrid_app` | `DATABASE_RUNTIME_ROLE=hivegrid_portal` | `DATABASE_RUNTIME_ROLE=hivegrid_worker` | | DB-Modus | `RLS_RUNTIME_MODE=required` | `RLS_RUNTIME_MODE=required` | `RLS_RUNTIME_MODE=required` | | Produktions-Pool je Instanz | `DATABASE_POOL_MAX=10` | `DATABASE_POOL_MAX=5` | nach Worker-Vertrag | | Produktions-Hard-Cap | 2 vCPU / 2 GB RAM | 1 vCPU / 1 GB RAM | nach Worker-Vertrag | | Session | `SESSION_SECRET` | `PORTAL_SESSION_SECRET` | keine Web-Session | | Tenant-Envelope-Key | `CRYPTO_SECRET` | nicht erforderlich | exakt derselbe `CRYPTO_SECRET` wie `hivegrid-web` | | Portalhost | `PORTAL_APP_HOST` | `PORTAL_APP_HOST` | `PORTAL_APP_HOST` | | Custom-Domain-Runtime | in Staging exakt `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED=true`; Produktion bis zum freigegebenen Controller unset/false | identischer expliziter Staging-Opt-in; Produktion bis zur Freigabe unset/false | nicht setzen | | Redis | nach Core-Funktion | gültiges `REDIS_URL`; optional gültiges `BULLMQ_REDIS_URL` | Queue-Verbindung nach Worker-Vertrag | | GDPR-Export-Storage | gemeinsamer Endpoint/Region/Bucket, vollständiges Storage-Credential; gemeinsames Paar zulässig | gemeinsamer Endpoint/Region/Bucket, vollständiges Storage-Credential; gemeinsames Paar zulässig | nicht setzen | | GDPR-Export-SSE-C | `GDPR_EXPORT_SSE_C_KEY_BASE64`, exakt wie im Import-Worker | exakt derselbe Wert wie `hivegrid-web` und Import-Worker | nicht setzen | | CAPTCHA | Core-Konfiguration | `CAPTCHA_PROVIDER=cap` oder `mcaptcha` plus passende Login-Keys und Instanz-URL | nicht erforderlich | | Auth-Mail | Core-Mailkonfiguration | nur Queue-Verbindung; keine Mailjet-Provider-Credentials | Mailjet-Absender-/Provider-Keys für Auth- und Status-Mails plus Queue-Verbindung | | Admin SSO/OAuth/Billing | nur dort, wo der Core-Vertrag es erlaubt | verboten | nach eigenem Worker-Vertrag, nie Portal-Credentials | Auf `hivegrid-portal` sind zusätzlich alle Core-Session-, Authentik-, OAuth-, Billing-, Coolify-, SSH-, Traefik-, Ingress-, Cloudflare-, Domain-Controller- und veralteten `PORTAL_SERVER_*`-Keys verboten. `APP_REVISION` wird aus dem Image gelesen und darf nicht als Coolify-Override existieren. ### GDPR-Export-Storage: Schlüssel und effektive Rechte Der dedizierte Import-Worker schreibt Portal- und Privacy-Exporte mit SSE-C. Beide Web-Surfaces lesen sie ausschließlich serverseitig mit demselben Customer-Key; es gibt keinen Presigned-URL- oder Klartext-Fallback. Die S3-Zugangsdaten dürfen von den vier Runtimes geteilt werden; getrennte Principals sind optional und werden nicht vom Deploy-Preflight erzwungen. Für die Anwendungspfade gilt diese Funktionsmatrix: | Runtime | Erlaubte Object-Actions | Erlaubte Object-ARNs/Key-Prefixe | Explizit nicht benötigt | | ------- | ----------------------- | -------------------------------- | ----------------------- | | `hivegrid-web` | `s3:GetObject` | `arn:aws:s3:::/gdpr-exports/privacy/tenants/*/*/*` | Portal-GDPR-Prefix, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` | | `hivegrid-portal` | `s3:GetObject` | `arn:aws:s3:::/gdpr-exports/portal/tenants/*/*/*` | Core-GDPR-Prefix, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` | | `worker-import` | `s3:PutObject`; zusätzlich `s3:DeleteObject` nur nach einem eindeutig fehlgeschlagenen Attempt, niemals bei unklarem Commit-Ausgang oder Owner-CAS-Verlust | beide oben genannten Object-Prefixe | `s3:GetObject`, `s3:ListBucket` | | `worker-general` | `s3:DeleteObject`; bucket-level `s3:ListBucket` nur mit `s3:prefix`-Condition auf `tenants/*`, `gdpr-exports/privacy/tenants/*` und `gdpr-exports/portal/tenants/*` | beide oben genannten Object-Prefixe sowie der bestehende Hard-Delete-Prefix `arn:aws:s3:::/tenants/*` | Customer-Key, `s3:GetObject`, `s3:PutObject`, unbeschränktes `s3:ListBucket` | Bei einem gemeinsamen Credential benötigt dessen Bucket-Policy die Vereinigungsmenge der in der Tabelle aufgeführten Actions und Prefixe. Die Trennung der App-Pfade bleibt im Code erhalten, ist dann aber keine Principal-Isolation des Providers. `worker-general` erhält unabhängig davon nie den SSE-C-Customer-Key und kann die Exportinhalte deshalb nicht entschlüsseln. Falls das Credential weitere, bereits freigegebene Storage-Funktionen bedient, erhalten diese eigene, explizite Statements auf deren Prefixe; daraus darf kein `s3:*` auf dem gesamten Bucket entstehen. Alle Artefakte liegen im gemeinsamen, export-first Keyspace `gdpr-exports/`; jeder Versuch erhält einen eigenen `attemptId`, sodass ein später oder parallel verlorener Versuch nicht das veröffentlichte Artefakt überschreibt. Der private Export-Bucket verwendet für diese Objekte weder Versioning noch Object Lock, weil der aktuelle `DeleteObject`-Pfad sonst nur einen Delete-Marker setzen beziehungsweise an einer Retention scheitern könnte. Die Bucket-Policy ist default-deny für andere Principals, Actions und Prefixe. Als Defense-in-depth liegt auf exakt dem Prefix `gdpr-exports/` zusätzlich eine Provider-Lifecycle-Regel mit `Expiration.Days=3`. Sie schützt auch dann vor dauerhaft liegen gebliebenen Attempts, wenn App-Kompensation und beide Sweeper ausfallen. Sie ist kein Ersatz für den 15-Minuten-Sweep und keine Zusage einer minutengenauen Löschung: Hetzner verarbeitet Lifecycle-Expiration asynchron. Die Regel darf weder den übrigen Bucket noch andere Prefixe erfassen. Hetzner dokumentiert action-spezifische Bucket-Policies, SSE-C und Lifecycle-Regeln; das Repository kann ihre tatsächlich angewandte Provider-Konfiguration jedoch nicht allein beweisen ([S3-Credentials](https://docs.hetzner.com/storage/object-storage/faq/s3-credentials/), [SSE-C](https://docs.hetzner.com/storage/object-storage/howto-protect-objects/encrypt-with-sse-c/), [Lifecycle](https://docs.hetzner.com/storage/object-storage/howto-protect-objects/manage-lifecycle/), [unterstützte Actions](https://docs.hetzner.com/storage/object-storage/supported-actions/)). Privacy-Exporte sind nach `resultExpiresAt` höchstens 72 Stunden, Portal-Exporte höchstens 24 Stunden über die authentifizierte App-Route abrufbar. Die Route sperrt den Zugriff ab diesem Zeitpunkt sofort. Der erforderliche Lösch-Scheduler läuft im 15-Minuten-Takt; physisch gelöscht wird im ersten erfolgreichen Sweep nach Ablauf. Die planmäßige Löschlatenz beträgt damit bis zu 15 Minuten zuzüglich Laufzeit, ist bei Provider-/Queue-Störung aber ausdrücklich nicht garantiert. Fehler müssen den Job fehlschlagen lassen, erneut versucht werden und bis zur erfolgreichen Löschung als Alarm offen bleiben. Eindeutig fehlgeschlagene Attempts werden unmittelbar kompensiert. Bei unklarem PUT- oder Ready-CAS-Ausgang bleiben Claim und Pointer erhalten, damit der Retry denselben Key übernimmt; der Sweep erfasst zusätzlich deterministisch adressierbare verwaiste Artefakte. Bei einer Rotation werden Import-Worker, Core und Portal gemeinsam umgestellt, nachdem alle mit dem alten Customer-Key verschlüsselten Exportobjekte erfolgreich gelöscht wurden. Im Dedicated-Modus setzt der Import-Worker `PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` und hält `IMPORT_QUEUE_ENABLED=false` sowie `IMPORT_QUEUE_RUNTIME_READY=false`; eine Mischkonfiguration bricht Runtime- und Deploy-Preflight fail-closed ab. Der alternative Full-Modus setzt beide `IMPORT_QUEUE_*`-Gates auf `true` und hält `PORTAL_GDPR_EXPORT_QUEUE_ENABLED` unset oder `false`. Auch dann bleiben der Storage-/SSE-C-Vertrag sowie Portal-, Privacy- und generische Import-/Export-Service-Wirings verpflichtend. Im Idle-Modus bleiben alle drei Gates unset oder `false`; dann darf der Import-Worker seinen Storage-/SSE-C-Vertrag weglassen und konsumiert keine Import-/Export-Queue. Core und Portal behalten ihren verschlüsselten Downloadvertrag unabhängig davon. `worker-general` setzt in jedem Staging-/Produktions-Rollout `EXPORT_RETENTION_QUEUE_ENABLED=true` und startet nicht bereit, wenn Scheduler, Redis oder sein Delete-only-Storage-Vertrag fehlen. Ein gesetzter `GDPR_EXPORT_SSE_C_KEY_BASE64` ist auf diesem Lösch-Worker ausdrücklich verboten und wird von Runtime- und Deploy-Preflight zurückgewiesen. ### Operator-Checkpoint: Provider-Vertrag Unit-Tests und der Coolify-Preflight beweisen nur Key-Format, Env-Vollständigkeit, gemeinsamen Bucket/Endpoint und die Runtime-Verdrahtung. Sie beweisen weder die aktive Hetzner-Bucket-Policy noch SSE-C- oder Hard-Delete-Semantik. Vor jedem neuen Environment und nach jeder Policy-/Credential-Rotation führt ein Operator deshalb mit ausschließlich wegwerfbaren Testobjekten den folgenden redigierten Check aus: 1. Privaten Bucket, default-deny Policy sowie deaktiviertes Versioning/Object Lock bestätigen. Die aktive Lifecycle-Konfiguration muss genau ein `Expiration.Days=3`-Statement für `gdpr-exports/` enthalten und darf keinen breiteren Prefix erfassen. Policy-/Lifecycle-Hash und Prüfzeitpunkt dokumentieren, nie Schlüsselwerte. Vor dem ersten SSE-C-Rollout zusätzlich die Legacy-Keyspaces `tenants/*/gdpr/*.zip` und `tenants/*/portal-gdpr/*/*.json` mit einem separat verwahrten Operator-Credential inventarisieren, vollständig löschen und die dazugehörigen DB-Jobs auf `expired` setzen beziehungsweise ihre alte Objektadresse entfernen. Nur redigierte Counts, Policy-Hash und Prüfzeitpunkt dokumentieren. Der neue Reader darf diese Klartextobjekte nie als Fallback akzeptieren. 2. Mit dem konfigurierten Storage-Credential je ein Lese- und ein Kompensations-Testobjekt mit SSE-C in beide GDPR-Prefixe schreiben und die Kompensationsobjekte wieder löschen. Für den GDPR-Keyspace müssen Actions und Prefixe außerhalb der oben beschriebenen Export-/Hard-Delete-Matrix scheitern; außerhalb dieses Keyspaces gilt die vollständig inventarisierte Vereinigungsmenge aller für das gemeinsame Credential explizit freigegebenen Actions und Prefixe. 3. Über die authentifizierten App-Routen bestätigen, dass Core nur das Privacy-Objekt und Portal nur das Portal-Objekt mit Customer-Key ausliefert. Kreuz-Prefix sowie Abruf ohne oder mit falschem Customer-Key müssen scheitern. Ein gemeinsamer Provider-Principal wird hierbei bewusst nicht als Runtime-Isolation gewertet. 4. `worker-general` muss die drei für Tenant-Hard-Delete benötigten Prefixe (`tenants/{tenantId}/`, Privacy-Export, Portal-Export) listen und darin löschen können. Der Worker darf keinen `GDPR_EXPORT_SSE_C_KEY_BASE64` erhalten und bietet ausschließlich den Delete-/Retention-Pfad an. Bei einem gemeinsamen Storage-Credential ist eine providerseitige Get-/Put-Sperre für diesen einzelnen Prozess nicht nachweisbar; verpflichtend bleiben die Prefix-Grenzen der Bucket-Policy. Danach wird bestätigt, dass die Objekte fehlen. 5. Je ein isoliertes, kurz vor Ablauf datiertes UAT-Fixture für Privacy und Portal beobachten: App-Download ab Expiry abgewiesen, Artefakt im ersten erfolgreichen 15-Minuten-Sweep gelöscht, Alarmweg bei einem absichtlich fehlgeschlagenen Delete anschließend wieder resolved. Das Fenster im Produktvertrag bleibt 72 beziehungsweise 24 Stunden; nur dieser Live- Checkpoint zählt als Provider-Proof. 6. Ein ausschließlich für den Backstop erzeugtes Attempt unter `gdpr-exports/` liegen lassen und nach Ablauf der dreitägigen Provider-Regel mit dem separaten Operator-Credential seine Entfernung bestätigen. Das Ergebnis ist ein zeitversetzter Provider-Nachweis und blockiert nicht den primären App-Sweep- Checkpoint; bis zur Bestätigung bleibt es als offener Betriebsnachweis markiert. ## VA-P26c: privater Domain-Controller-Vertrag Die vorbereitete private Ressource heißt `hivegrid-portal-domain-controller` und verwendet das gleichnamige immutable Image/Target mit derselben expliziten Revision wie der freigegebene Portal-Release. Sie ist nicht öffentlich erreichbar und besitzt ausdrücklich **keine** Datenbank-, Coolify-, SSH-, Root-, Cloudflare-, allgemeine Traefik-/Ingress- oder Docker-Socket-Credentials. Benötigt werden ausschließlich: - eine eigene Redis-Verbindung für die dedizierten signierten Command-/Result-Queues; - ein getrenntes Command-Secret sowie ein getrenntes Bearer-Token für `/metrics`; - DNS-/HTTPS-Outbound für Ownership-, CNAME-, SNI- und Health-Prüfungen; - Schreibrecht ausschließlich auf `/data/coolify/proxy/dynamic/hivegrid-portal-domains/`, nicht auf das übergeordnete Dynamic-Config-Verzeichnis; - das environment-spezifische, provider-qualifizierte Coolify-Ziel `https-0-@docker`; ein frei wählbares oder provider-loses Backend ist verboten. Commands tragen `claimId`, `tenantId`, `generation`, `hostname` und `action` sowie Signatur und Content-Hash. Der Controller verwirft falsche Signaturen, alte Generationen und nicht exakte Hosts. Traefik-Dateien werden über Temp-Datei, `fsync` und atomaren Rename geschrieben; jede Regel matcht exakt `Host()` und verwendet kein offenes On-Demand-Wildcard-TLS. `active` darf erst nach realem SNI-/Portal-Health-Ack gesetzt werden. Dafür läuft ausschließlich der schmale `hivegrid_portal_resolve_custom_hostname_health`-Resolver vor dem normalen Host-Dispatch: Er akzeptiert nur DNS-verifizierte Claims mit aktivem Entitlement/Payment, persistiertem Controller-Command und Domainstatus `provisioning`, `active` oder `degraded`; pending, disabled, Kill-Switch und Deprovisioning liefern 404. Das ist ein Controller-Probe, keine Freigabe für pre-active Portalinhalte. `/healthz` bleibt ohne Secrets nutzbar, `/metrics` ist Bearer-geschützt. Das Repository enthält Image-, CI-/SBOM-, Health-, Queue- und Renderer-Verträge. Das ist kein Beleg, dass die Ressource in Coolify angelegt, gestartet oder mit dem Estate-Traefik verbunden wurde. Bis dieser Beleg je Environment vorliegt, bleibt `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED` dort unset oder `false`. Nur Staging setzt den Wert aktuell auf exakt `true`, und zwar auf `hivegrid-web` sowie `hivegrid-portal`; der Coolify-Helper prüft beide Werte vor jeder Controller-Mutation. Das Gate blendet den Tenant-Admin-Link aus und liefert für Domain-Admin-Route sowie Custom-Host-Routing 404, ohne den Standardhost des Kundenportals abzuschalten. ## Merge-Migration Auf dem Feature-Branch blieb `verify:migrations-parity` gemäß AD-21 absichtlich rot. Für den Merge wurde daraus genau eine reviewte forward-only P26-Migration für den ausgewählten gemeinsamen Portal-Vertragsstand aus VA-P26a/b/c erzeugt: `prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql`. Der rohe Prisma-Diff wurde nicht ungeprüft übernommen; auf dem Feature-Branch gab es ausdrücklich keine eigene Migration. ### Bestandsdaten-Preflight Die Migration muss vor jeder destruktiven Änderung fail-closed prüfen: - `Portal.tenantId` ist lückenlos und verweist auf den richtigen Tenant. - Pro Tenant existiert höchstens ein Portal, bevor der neue Unique-Index entsteht. - `PortalUser.tenantId` ist lückenlos und entspricht immer dem Tenant seines Portals. - Portal-E-Mails sind nach `lower(trim(email))` weder leer noch innerhalb eines Portals doppelt. - Die später benötigten zusammengesetzten IDs/FKs zwischen Portal, PortalUser, Projekt, Stage und File sind tenant-konsistent. - Das freigegebene Legacy-Mapping ist anwendbar: tenant-konsistente PortalUser mit einem nichtleeren, vom aktuellen Passwort-Hasher akzeptierten `passwordHash` werden `active`; alle übrigen übernahmefähigen PortalUser werden `invited`. Bestehende Hashes werden byte-identisch erhalten und niemals neu gehasht oder durch ein Default-Passwort ersetzt. `emailVerifiedAt` wird nur aus einem vor dem Cutover dokumentierten, belastbaren Verifikationsbeleg übernommen. Ein fehlender Legacy-`verifyToken` allein zählt nicht als Beleg und führt deshalb zu `NULL`. Fehlerhafte oder mehrdeutige Zeilen werden nicht geraten, automatisch gelöscht oder unter einem beliebigen Tenant einsortiert. Sie müssen vor dem Cutover bewusst bereinigt beziehungsweise zugeordnet werden. ### Token- und Re-Invite-Entscheidung Die alten Felder `PortalUser.verifyToken` und `PortalUserRegistration.token` enthalten keinen mit dem neuen `PortalToken`-Vertrag kompatiblen Hash. Sie werden nicht in gültige neue Login-Fähigkeiten umgewandelt. Offene Registrierungen beziehungsweise alte Verify-Tokens werden invalidiert; betroffene Personen erhalten nach dem Cutover einen neuen Setup-/Magic-Link über den geprüften Flow. Dieser Re-Invite muss vor dem Drop fachlich freigegeben und kommuniziert sein. Die Migration bricht vor jeder Mutation ab, sobald Tenant-/Portal-Zuordnung, normalisierte E-Mail oder Portal-Owner nicht eindeutig sind. Sie archiviert oder verschiebt keine Konfliktzeile automatisch. Legacy-Registrierungen und Tokens werden vollständig invalidiert; weder Klartext- noch Legacy-Tokenwerte dürfen in die neuen `PortalToken`-Zeilen gelangen. ### DDL- und Policy-Reihenfolge Die Migration führt Preflight, Backfill, Constraints, Tabellenänderungen und RLS in einer atomaren Migration aus: 1. Fehlende `tenantId`-/`emailNormalized`-/Locale-Werte nach dem freigegebenen Mapping backfillen und die Preflight-Prüfungen erneut ausführen. 2. Die sieben geprüften Legacy-Commerce-Policies sowie die Policy von `PortalUserRegistration` explizit entfernen. 3. Acht Legacy-Tabellen FK-sicher child-first entfernen: `PortalUserSubscriptionProductPrice`, `PortalUserSubscriptionProduct`, `PortalSubscriptionFeature`, `PortalSubscriptionPrice`, `PortalUserSubscription`, `PortalSubscriptionProduct`, `PortalCheckoutSessionStatus` und `PortalUserRegistration`. 4. Den vollständigen aktuellen Portal-Vertragsstand anlegen: Auth/Session/Token, ProjectAccess/Stage-/Dokumentfreigabe/Status-Mail, Upload/Reklamation, Subunternehmerzugang, Tenant-Konfiguration/Auto-Release/Notification-Präferenzen, Service-Inbox/Routing, DSGVO-Export/Löschung/Lifecycle sowie Domain-Claim und aktuelle Custom-Domain-State-Machine. Dazu gehören alle Enums, Indizes, zusammengesetzten Tenant-FKs und die sicheren Änderungen an `Portal`/`PortalUser`; eine fest verdrahtete Annahme von nur „sechs Portal-Tabellen" ist veraltet. 5. Nur den noch nicht migrierten Portal-Delta für die normalen `hivegrid_app`-/ `hivegrid_worker`-Tenant-Policies einbetten. Bereits migrierte Telephony-Objekte dürfen nicht aus einem breiten Generator-Delta dupliziert werden. 6. Die schmalen `hivegrid_portal`-Policies, Spalten-Grants und `SECURITY DEFINER`-Resolver einbetten. Die Actor-Invarianten erzwingen für `File`, `FileUpload`, `FileEntityLink` und `portal_form`-`FormSubmission` genau den zulässigen internen oder Portal-Aktor. Die schmalen Domain-Controller-Capabilities bleiben vom Portal-Login getrennt. SQL-Dateien mit eigenem `BEGIN`/`COMMIT` werden nicht blind verkettet; beim Einbetten bleibt genau eine äußere Transaktion. Der Inverse-SQL-Kommentar rekonstruiert Struktur, Indizes, FKs, Grants und Policies parent-first. Er weist ausdrücklich darauf hin, dass gelöschte Registrierungs- und Commerce-Zeilen nur aus dem Backup, nicht durch Inverse-DDL, wiederhergestellt werden. ### Pflicht-Proof der Migration Vor dem Merge beziehungsweise Rollout müssen grün sein: ```sh pnpm exec prisma validate pnpm run verify:migrations-parity HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live pnpm run verify:tenant-policy-contract pnpm run verify:rls-release-readiness ``` Der strikte RLS-Lauf muss eine frische leere Datenbank ausschließlich mit `prisma migrate deploy` aufbauen. `prisma db push`, der Feature-Branch-Recut-Helper und manuell nachgeladene Policy-Dateien sind in diesem Proof verboten. ### Lokaler Merge-Kandidaten-Proof vom 2026-07-16 Ein **bewusst ungetrackter lokaler Merge-Kandidaten-Proof** wurde gegen zwei wegwerfbare PostgreSQL-16-Datenbanken ausgeführt. Die zugehörigen Repository-Verträge liegen in `18dfd4825`; der temporäre Migrationskandidat selbst wurde gemäß AD-21 nicht in der Feature-Branch committed: 1. leere Datenbank nach vollständigem `prisma migrate deploy` der bestehenden Chain; 2. Datenklon mit den acht Legacy-Commerce-/Registrierungstabellen und repräsentativen PortalUsern. Beide Läufe verwendeten den eingeschränkten `hivegrid_migrator` und endeten schema-paritätisch zum aktuellen Prisma-Schema. Der Legacy-Klon bestätigt `active` für akzeptierte Hashes, `invited` für nicht akzeptierte/fehlende Hashes, byte-identische Hash-Erhaltung, `emailNormalized`-/Tenant-/Locale- Backfill und Reset nicht belastbar belegter Verifikation sowie alter Registrierung/Token-Fähigkeiten. Eine normalisierte Duplicate-E-Mail-Kollision bricht fail-closed vor Mutation ab. Vier Actor-Checks sind validiert; **22/22** eingeschränkte Portal-Live-Tests (P26a 14/14 + P26b 7/7 + schmaler Custom-Host-Resolver 1/1) belegen Customer/Subunternehmer, PortalUser/Tenant A/B, active/revoked, Frozen read/write und fail-closed Host-Auflösung. Zusammen mit App-/Worker- und Tenant-Bootstrap- Proofs ist der frische Feature-Overlay-Lauf **68/68** grün. Dieser Probe-Lauf erlaubt weder `verify:migrations-parity` noch den migration-only Strict-Lauf grün zu markieren: Der Kandidat liegt bewusst nur außerhalb des Repositories. Vor Merge muss daraus die eine reviewte forward-only Migration mit Inverse-SQL entstehen; danach folgen frische Chain und Staging-RLS-Proof. ### Ausgeführter Merge-/RLS-Proof vom 2026-07-16 Die reviewte Migration wurde mit PR `#125` in `main` übernommen und im Deploy-Lauf [`#10300`](https://git.hg-int.dev/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300) als einmaliger Migrationsschritt ausgeführt. Der Lauf prüfte die exakte Revision `f54b04162b2823b1d2f6db0318baf1a7431c5b66`, Migration-Chain-Parität, Tenant-Policy-Vertrag, RLS-Release-Readiness und Live-RLS-Isolation. App, Worker und Portal liefen mit getrennten Rollen über PgBouncer; Core und Portal verwendeten denselben gepinnten Web-Digest und bestanden `/healthz`/`/readyz`. Damit sind die oben beschriebenen Merge-/RLS-Gates erfüllt. ## Staging-Rollout 1. Portal-Ressource und Core-Web zunächst ohne öffentlichen Portal-DNS vollständig nach der Runtime-Matrix konfigurieren. Alle Ressourcen-Allowlisten aktualisieren. 2. Merge erst freigeben, wenn Migration, Rollen, PgBouncer und Coolify-Inventar vorbereitet sind. 3. Der Main-Workflow migriert einmalig, pinnt Web und Portal auf denselben SHA/Digest, deployt beide getrennt und prüft `/healthz` sowie `/readyz` auf Service, Surface, Revision und echte DB-Rolle/RLS-Bereitschaft. 4. Erst nach grüner interner Bereitschaft den DNS-Eintrag anlegen. Nach Estate- Standard bleibt Cloudflare zunächst `proxied=false`, bis das LE-Zertifikat gültig ist; anschließend kann `proxied=true` gesetzt werden. 5. Die schreibenden Portal-RLS-Integrationstests laufen nur gegen eine wegwerfbare PostgreSQL-Instanz. Shared Staging erhält einen nicht destruktiven Rollen-/Policy-/ Grant-/`readyz`-Proof und bewusst angelegte UAT-Fixtures. ## Staging-UAT VA-P26b besitzt den vollständigen Admin-/Interaktionsflow; Merge-Migration und eingeschränkter Staging-RLS-Proof sind mit Lauf `#10300` grün. Für den formalen Handoff fehlt jetzt ein bewusst angelegter isolierter UAT-Tenant mit PortalUser, ProjectAccess, sichtbarer Stage, freigegebenem Testdokument sowie begrenztem Customer- und Subunternehmerzugang. Es werden keine `SEED_*`-Runtime-Schalter verwendet. Zu prüfen sind mindestens: - Magic-Link, optionales Passwort, Setup, Verifikation, Reset und Logout; - keine User-Enumeration bei unbekannter E-Mail; - PortalUser A/B, Tenant A/B und nicht freigegebene Projekte/Dokumente liefern 404; - Core-Host weist Portalpfade ab und Portalhost weist Core-/Admin-/API-/Rootpfade ab; - Frozen-Tenant verhält sich read-only; - Status-Mail enthält den richtigen Portalhost, respektiert Sichtbarkeit/Präferenz, wird debounced und tatsächlich zugestellt; - Multi-Upload/Reklamation schreibt erst nach AV-/Storage-Erfolg File-/Link-/Activity-/Inbox- Datensätze und benachrichtigt über `notify()`; Subunternehmer sehen weder Endkunden noch fremde Projekt-/Dokumentdaten; - Admin-Konfiguration, Rechtslink-Aktivierungsgate, Inbox-Routing, Export, 24-Stunden-Lösch-Widerruf und Lifecycle-Jobs verhalten sich unter Frozen read-only; - `/healthz` und `/readyz` melden den erwarteten Service, die erwartete Surface und die gebackene Revision, ohne DB-Rolle oder Secrets öffentlich auszugeben. VA-P26c-UAT folgt separat erst nach echtem Billing-Provider-Proof und angelegter Controller-Ressource: TXT/CNAME-Verifikation, exakte Host-Auflösung, SNI/TLS-/Health-Ack, Retry/Revalidation, Remove/Switch, Kill-Switch und Standardhost-Fallback. Localhost-, Mock- oder manuell eingespielte Traefik-Dateien ersetzen diesen Proof nicht. ## Produktion und Rollback Die VA-P26a-Grundlage darf vorab auf Staging verifiziert werden. Eine öffentliche Buchung beziehungsweise Produktfreischaltung erfolgt jedoch erst nach VA-P26b, wenn Workspace-Admin-Verwaltung, Upload/Reklamation und DSGVO-Flows vollständig verfügbar sind. VA-P26c schaltet danach Paket-Gates und Custom-Domains frei. Produktion wird nur über den bestehenden `promote`-Workflow mit der exakt in Staging geprüften Live-Staging-SHA und einem erst nach Backup-Bereitschaft manuell gestarteten, input-freien Promote ausgerollt. Ressourcen-, Rollen-, PgBouncer-, Env-, DNS- und Zertifikatsvorbereitung werden vorher nochmals geprüft. Vor der DB-Migration kann auf den vorherigen Web-Digest zurückgerollt und die Portal- Ressource beziehungsweise ihr DNS deaktiviert werden. Nach der Migration gilt der im Migration-File dokumentierte Inverse-SQL-Pfad; gelöschte Legacy-Zeilen benötigen das Backup. Core und Portal werden immer als Digest-Paar zurückgerollt, damit keine zwei unterschiedlichen Surface-Verträge gleichzeitig laufen. Für VA-P26c bleibt der Standardhost der verpflichtende Fallback. Bei Controller-, DNS-, TLS- oder Entitlement-Störung wird zuerst der Domain-Kill-Switch gesetzt, die aktuelle Generation deprovisioniert und ausschließlich die exakt zu diesem Claim gehörende generierte Traefik-Datei entfernt. Danach wird die Controller-Ressource auf den zuvor geprüften immutable Digest zurückgesetzt oder gestoppt; Core-/Portal-Digests und fremde Host-Dateien bleiben unberührt. Die 30-Tage-Reclaim- Sperre wird durch einen Rollback nicht umgangen. Ohne erfolgreiches Deprovisioning-/Fallback-UAT wird kein Custom-Host öffentlich aktiviert. ## Folge-Tickets - VA-P26b ergänzt Admin-Einladungen, Access-Matrix, Stage-/Dokumentfreigaben, Upload/Reklamation und DSGVO-Flows. - VA-P26c ergänzt Paket-Gates und den Self-Service-Custom-Domain-Flow inklusive DNS-Verifikation, Zertifikatsstatus und Deaktivierung.