Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P26a.md
T

481 lines
44 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.
# VA-P26a · P26 Customer-Portal: Auth/Magic-Link + Projekt-Sicht + Status-Mails ⭐
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Phase** | P26 — Customer-Portal · v2-P6 *(ex-P18)* |
| **Cycle/Fenster** | retimiert: 2026-07-16 bis 2026-08-05 |
| **Status** | technisch vollständig · Plane Done · **8/8 DoD = 100 % done** |
**🎨 design-nachzug: offen** (seit 2026-07-16) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `VD-P26` ausstehend.
## Abhängigkeiten & Parallelität
- **Erfüllte Grundlagen:** `AK-P4a` (FileEntityLink — Doc-Freigabe + Portal-Uploads), `R-P6`
(CRM) und `R-P9a` (Projekt — Project-Stages/Stage-Trigger) wurden vollständig konsumiert; daraus
besteht kein offener Block mehr.
- **CI-Proof freigegeben durch:** `CI-05`; der ref-übergreifend parallel-sichere Docker-Smoke mit echten
SHA-Tags, wirksamen Timeouts und verwertbarer Fehlerdiagnostik ist in Gitea-Lauf `10574`, Job
`44135`, vollständig grün. Die fachlichen Staging-/UAT-Gates dieses Tickets bleiben davon
getrennt.
- **Erfüllte Handoffs:** `VA-P26b` (Upload/Reklamation/Skalierung) und `VA-P26c`
(Paket-Gates/Custom-Domain) bauen auf der am 2026-07-21 vollständig abgenommenen Portal-Auth-,
Host- und Projekt-Schicht auf; daraus besteht kein offener technischer Block mehr.
- **Läuft parallel zu:** anfangs Raffaels disjunktem KWP-Strang und danach weiterer disjunkter Carry-over-Arbeit. Das bestehende Modul-Schema `prisma/schema/portals.prisma` wird bewusst auf das Customer-Portal recuttet (AD-21); **kein zweites `Portal`-/`PortalUser`-Modell**. `crm.prisma`/`project.prisma`/`files.prisma` nur über minimale FK-Nachzüge.
- **Konflikt-Risiko:** hoch — **eigene Auth-Schicht** parallel zum TenantUser-Auth (NICHT geteilt) plus neuer Runtime-/DB-Trust-Boundary. Der zusätzliche Security-/Deploy-Slice ist deshalb auf den 16.07.–05.08.2026 retimiert; lokale P26b-Vorarbeit ist isoliert zulässig, formaler Handoff und Aktivierung beginnen erst nach diesem Gate.
## Übernahme- und Start-Notiz
2026-07-15 · Raffael: Die Umsetzung startet nach ausdrücklicher Freigabe im isolierten Worktree
`HiveGrid-Cloud-va-p26-customer-portal` auf Branch `feat/va-p26a-customer-portal`. Die Plane-Zuweisung an
Akeshan bleibt unverändert; der operative Branch wird von Raffael geführt. `AK-P4a`, `R-P6` und `R-P9a`
sind abgeschlossen. `VA-P26b` und `VA-P26c` wurden in beide Abhängigkeitsrichtungen geprüft. Ihre lokale
Vorarbeit läuft auf demselben Branch, der formale Handoff bleibt jedoch bis zum stabilen
Auth-/Runtime-/RLS-Vertrag blockiert.
**Reterminierung:** 16.07.2026 bis 05.08.2026. Der bisherige Zwei-Tage-Slot wurde wegen des durch AD-30
hinzugekommenen Runtime-, Deploy- und Live-RLS-Security-Slices ersetzt.
**Preflight:** Workspace-Struktur und EU-Import-Check grün; Node 24.18.0; `pnpm typecheck` grün;
`pnpm test` grün (803 Testdateien bestanden, 9 übersprungen; 5.444 Tests bestanden, 53 übersprungen).
**Startstand:** VA-P26a: 0/7 DoD = 0 % done · 7 Punkte selbst machbar; Live-Coolify-/Postgres-Proof ist
für den Abschluss extern auszuführen, aber kein lokaler Implementierungsblocker.
## Umsetzungs-Notiz
2026-07-15 · Raffael: Die lokale Implementierung liegt in Commit `82c41df34`
(`feat(customer-portal): add isolated portal runtime`). Umgesetzt sind die physisch getrennten
Core-/Portal-Builds aus demselben Web-Image, der fail-closed Host-/Surface-Dispatch vor Assets und
React Router, die eigene Portal-Identitäts-, Session-, Token- und RLS-Welt, Magic-Link/optionales
Passwort, Projekt-/Stage-/Dokumentsicht, der Status-Mail-Worker, der Admin-Template-Editor sowie die
AD-28-Interim-UI mit VM-, Hot-Swap-, Smoke- und Visual-Proof. Der fachfremde Legacy-Portal-Commerce-
Pfad wurde nach Konsumenten-Audit recuttet; auf dem Feature-Branch wurde gemäß AD-21 keine Migration
angelegt.
**Proof:** `pnpm typecheck`, DB-/Worker-Typecheck und `pnpm lint` grün. `pnpm test`: 829 Testdateien
bestanden, 9 übersprungen; 5.632 Tests bestanden, 53 übersprungen. Alle Package-Suiten grün; Worker:
98 Testdateien und 1.111 Tests bestanden, 5 übersprungen. Prisma valide; Tenant-Policy-Vertrag
266/266. Live-RLS: 39 Core-/App-Worker-, 14 Portal- und 7 Bootstrap-Tests grün. Dual-Build und
Surface-Verifier: 354 Core-Routen, exakt 11 Portal-Routen und keine gegenseitigen Route-, Server-,
Client- oder Public-Asset-Leaks; Runtime-Closure: 89 Imports/92 Dependencies. UI-Visual-Vertrag:
86 Prüfungen grün; Hot-Swap 1/1 und Playwright-Component-Pixeltest 1/1 grün. Gitea-CI-Vertrag
154/154, Deploy-Vertrag 189/189, Docker-Baseline 291/291, Non-Root 3/3, CI-Baseline 35/35,
Source-Health 17/17, Permission-Matrix 22/22 und Route-Inventar 5/5 grün. EU-Provider-Importcheck und
`git diff --check` grün. `verify:migrations-parity` endet erwartungsgemäß ausschließlich wegen der
nach AD-21 noch fehlenden Merge-Migration mit Exit 2.
**Stand:** VA-P26a: **5/7 DoD = ~71 % done**. Offen sind 2 Gates, beide außerhalb des jetzt lokal
abschließbaren Feature-Branch-Slices: (1) die realen Coolify-Ressourcen `hivegrid-web` und
`hivegrid-portal` samt identischem SHA/Digest, DNS/Ingress und Live-Health-Proof; (2) die einmalige
forward-only Merge-Migration samt grünem Parity-/Staging-RLS-Proof. Es wurde weder live deployt noch
DNS oder eine externe Ressource verändert. `VA-P26b` und `VA-P26c` bleiben bis zu diesen Gates
blockiert.
### Hardening- und Rollout-Nachzug
2026-07-15 · Raffael: Der lokale Rollout-Vertrag ist mit Hardening-Commit `a62945596` bis zur
Operator-Grenze fertiggestellt. Der
Deploy führt jetzt vor jeder Staging-/Production-Migration einen ausschließlich lesenden Preflight
über Core-Web, Portal-Web, API, MCP, Hocuspocus und alle fünf Worker aus. Geprüft werden unter
anderem Runtime-Rolle/RLS, verbotene Migrations-/Seed-Variablen, exakte Revision, explizite
DB-Pool-Limits, PgBouncer-Port, getrennte Sessions, kanonische HTTPS-Hosts, Web-Push sowie harte
CPU-/RAM-Grenzen beider Web-Ressourcen. Mutationen und Worker-Reconciliation bleiben hinter der
Migration. Veraltete Fly-Domain-Module und `PORTAL_SERVER_*`-Secrets wurden entfernt; Status-Mails
verwenden ausschließlich den kanonischen HTTPS-Portalhost. `/readyz` beweist Service, Surface und
Revision, ohne die DB-Rolle öffentlich auszugeben.
Der neue strikte Migration-Chain-Prüfer vergleicht für den damaligen P26a-Portal-Vertragsstand den
vollständigen App-/Worker-Zielzustand mit 29 Policies und 64 DML-Grants, inklusive ENABLE/FORCE RLS,
Policy-Ausdrücken, Rollen, PUBLIC-/vererbten Rechten und Column-ACLs. Im normalen lokalen
Feature-Branch-Modus sind der exakte Prüfer und alle 60 Live-RLS-Tests grün. Der migration-only
Strict-Modus stoppt erwartungsgemäß ausschließlich vor dem Overlay an der noch fehlenden
forward-only Merge-Migration.
**Hardening-Proof:** Node 24.18.0; Typecheck, Worker-Typecheck und Lint grün; Core-Suite 830
Testdateien bestanden, 9 übersprungen, 5.670 Tests bestanden, 53 übersprungen; Worker-Suite 98
Testdateien bestanden, 1 übersprungen, 1.114 Tests bestanden, 5 übersprungen. Core-/Portal-Build,
Web-/Worker-Runtime-Closures, Prisma-Validierung, Tenant-Policy-Vertrag 266/266, Gitea-CI-Vertrag
155/155, Deploy-Vertrag 195/195, Health 30/30, Docker-Baseline 291/291, Non-Root 3/3,
Production-/Release-Docs-Baselines, Env-Drift, Doku-Links, Secret-Scan und Removed-Module-Scan sind
grün. Das finale lokale Docker-Image lief erfolgreich gleichzeitig als getrennte Core- und
Portal-Runtime gegen den finalen gemeinsamen Policy-Zustand. `verify:migrations-parity` endet wie
vorgesehen mit Exit 2 und `verify:rls-release-readiness` ausschließlich wegen des noch nicht in einer
aktiven Merge-Migration enthaltenen Portal-Deltas. Der erweiterte P26b/P26c-Vertragsstand und sein
neuer Probe-Lauf sind im Nachweis vom 2026-07-16 unten getrennt dokumentiert.
**Stand nach Hardening:** VA-P26a: **5/7 DoD = ~71 % done**. Es wurde kein Coolify-, DNS-, TLS- oder
sonstiger Live-Zustand verändert. Offen bleiben exakt die bereits dokumentierten zwei Operator-Gates:
Merge-Migration plus strikter Staging-RLS-Proof sowie reale gleichartige Core-/Portal-Ressourcen mit
identischem SHA/Digest und Live-UAT.
### Produkt-/Betriebsentscheidungs-Nachtrag
2026-07-16 · Raffael: Die Betreiber-Startwerte sind bestätigt: Produktion startet für `hivegrid-web`
mit 2 vCPU/2 GB und `DATABASE_POOL_MAX=10`, für `hivegrid-portal` mit 1 vCPU/1 GB und
`DATABASE_POOL_MAX=5`, jeweils pro Prozess/Instanz. Die Werte bleiben anpassbare Betriebsbudgets, aber
explizite Hard-Caps sind Pflicht. VA-P26a darf die Runtime-/Auth-/RLS-Grundlage auf Staging bringen; die
öffentliche Buchung/Freischaltung wartet auf den vollständigen `VA-P26b`-Admin-/Interaktions-Slice.
Der DoD-Stand bleibt **5/7 = ~71 % done**, da weder Merge-Migration noch Live-Proof dadurch ersetzt werden.
**Rollback:** Vor der DB-Migration wird auf den vorherigen immutable Web-Digest zurückgerollt und die
Portal-Resource beziehungsweise ihr DNS-Eintrag deaktiviert. Nach der Merge-Migration gilt der im
Migration-File zu dokumentierende Inverse-SQL-Pfad parent-first für Struktur, Indizes, FKs und
Policies; gelöschte Legacy-Commerce-Zeilendaten sind nicht per DDL rückholbar und benötigen bei einem
echten Daten-Rollback das Datenbank-Backup.
### Lokaler Merge-Kandidaten-Proof
2026-07-16 · Raffael · **Bewusst ungetrackter lokaler Merge-Kandidaten-Proof.** Der reproduzierbare
Repository-Vertrag liegt in `18dfd4825`, die Main-Reconciliation in `1f8d9a04c`; der temporäre
Merge-Kandidat selbst wurde absichtlich nicht committed. Er wurde ohne Migrationsfile gegen zwei wegwerfbare
PostgreSQL-16-Datenbanken geprüft: einmal ab leerer Datenbank
über die vollständige bestehende Migration-Chain und einmal gegen einen Legacy-Datenklon. Beide Läufe
verwendeten den eingeschränkten `hivegrid_migrator`; der resultierende Zustand ist schema-paritätisch
zum aktuellen Prisma-Schema. Der Legacy-Klon belegt das freigegebene Mapping zu `active` beziehungsweise
`invited`, byte-identisch erhaltene Passwort-Hashes, zurückgesetzte nicht belastbar belegte
Verifikation/Tokens und den FK-sicheren child-first-Recut. Eine bewusst erzeugte normalisierte
E-Mail-Kollision bricht fail-closed vor der ersten Mutation ab.
Die nachgelagerten lokalen Policy-Proofs validieren vier Actor-Constraints für `File`, `FileUpload`,
`FileEntityLink` und `FormSubmission`. Der P26a-Anteil bleibt **14/14**; im aktuellen gemeinsamen
Vertragsstand sind **22/22** Portal- und zusammen mit App/Worker sowie Bootstrap **68/68** lokale
Feature-Overlay-Tests grün. Dieser Probe-Lauf ist Vorbereitung für die eine Merge-Migration, kein
Ersatz dafür: Es wurde kein Migrationsfile angelegt, kein Staging-System verwendet und keine Coolify-,
DNS-, TLS- oder
Produktionsressource verändert.
Finaler lokaler Gate-Proof: `pnpm typecheck`, `pnpm lint` und `pnpm test` grün (927 Testdateien
bestanden, 10 übersprungen; 6.166 Tests bestanden, 54 übersprungen), vollständiger Core-/Portal-Build,
Runtime-Closures, Controller-Container-Smoke, Prisma-Validierung und der reale Feature-Overlay-RLS-Lauf
mit eingeschränkten App-/Portal-Rollen grün. `verify:rls-release-readiness` bleibt ausschließlich wegen
der 19 noch nicht migrationsgebundenen P26-Definitionen erwartungsgemäß offen.
**Stand 2026-07-16:** VA-P26a bleibt **5/7 DoD = ~71 % done**. Offen sind weiterhin ausschließlich
die echte forward-only Merge-Migration samt migration-only Parity-/Staging-RLS-Proof und der reale
Core-/Portal-Ressourcen-, Digest-, Health- und UAT-Nachweis.
### Live-Deploy-Proof
2026-07-16 · Raffael: PR `#125` wurde nach grünem PR-Lauf per Squash gemergt. Die beiden aus dem
ersten Rollout sichtbar gewordenen Deploy-Vertragsfehler wurden in PR `#130` und PR `#132` jeweils
mit Regressionstests behoben. Der abschließende Deploy-Lauf
[`#10300`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300) hat die exakte
Revision `f54b04162b2823b1d2f6db0318baf1a7431c5b66` erfolgreich nach Staging und Produktion
promotet.
Die forward-only Migration
`prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql` lief im einmaligen,
eingeschränkten Migrator-Container durch. Migration-Chain-Parität, exakter Tenant-Policy-Vertrag,
RLS-Release-Readiness und der Live-RLS-Isolationslauf waren grün. Core und Portal verwenden getrennte
App-/Portal-Rollen über PgBouncer; die Portal-Ressource läuft mit `hivegrid_portal`, erzwungenem RLS,
eigenem Pool-Limit und den vereinbarten Hard-Caps. Beide Web-Surfaces wurden aus demselben gepinnten
Image/Digest ausgerollt und bestanden `/healthz` sowie `/readyz` mit der erwarteten Revision.
Damit ist der Portal-RLS-Punkt erfüllt. Der Runtime-/Trust-Boundary-Punkt bleibt bis zum echten
Staging-UAT mit Tenant-Fixture, Host-/Surface-404-Pfaden und Endkunden-Klickpfad offen. **Aktueller
Stand: 6/7 DoD = ~86 % done · 1 Punkt offen, davon 1 UAT-/Sign-off-abhängig und 0 weitere
Repository-Gates.** Billing, Custom-Domain-Controller und Custom-Domain-TLS/Ingress sind Scope von
`VA-P26c` und werden durch diesen Deploy nicht als erledigt gewertet.
### Globales M006-Fail-Closed-Gate
2026-07-18 · Raffael · Commit `6d96b7928` · **Lokaler Repository-Proof, noch nicht deployt.** Die
forward-only Migration `20260717200000_va_p26_customer_portal_feature_gate` provisioniert genau die
kanonische globale Flag `customer-portal` (`feature_flag_customer_portal_global`) samt Create-Audit.
Die erstmalige Migration erhält die bestehende Verfügbarkeit mit `enabled=true`; danach entscheidet
ausschließlich der auditierte Feature-Flag-Engine-Toggle. Fehlende, doppelte, ersetzte, gescopte,
gefilterte, varianten-/regel-/parent-gebundene oder außerhalb ihres Zeitfensters liegende Zeilen
schließen das Portal fail-closed.
Der ungecachte Gate-Read greift auf Standardhost, Framework-/Asset-Requests, Standard-/Custom-Host-
Tenantauflösung, Workspace-Admin-Navigation und direkte Admin-Routes. Portal-Automation prüft am
Job-Einstieg, transaktionslokal vor Rule-Writes, vor jedem Action-Step und direkt vor Auto-Release.
Status- und Auth-Mails werden unmittelbar vor der finalen Provider-Zustellung erneut geprüft, sodass
auch bereits eingereihte Jobs nach einem Disable nicht versendet werden. Operative Health-Pfade,
insbesondere der schmale Custom-Host-`/healthz`-Controller-Probe, bleiben für Diagnose und sicheres
Re-enable erreichbar. Der globale Betriebsschalter ist orthogonal zu den `VA-P26c`-Entitlements und
zum hostbezogenen Domain-Kill-Switch.
**Proof:** Fokussierter Gate-Lauf 19/19 Testdateien und 429/429 Tests grün; vollständiger Root-Lauf
957 Testdateien bestanden, 10 übersprungen, 6.516 Tests bestanden, 55 übersprungen. Root-/Worker-
Typecheck, Lint, Prisma-Validate, Migration-Parität, i18n, Tenant-Policy-Vertrag 292/292,
CI-Baseline, Source-Health, Coverage und `git diff --check` sind grün. Der strikte lokale
Migration-Chain-/Live-RLS-Lauf gegen frisches PostgreSQL 16 ist grün. Es wurde weder deployt noch
Staging oder eine externe Ressource verändert.
**Rollback ab diesem M006-Nachzug:** Der normale sofortige Laufzeit-Rollback ist der auditierte
Toggle von `customer-portal` auf aus; die strukturelle Inverse-SQL ist kein normaler Kill-Switch. Ein
Image-Rollback auf eine Revision vor diesem Gate ist unvereinbar mit einem deaktivierten Portal:
gate-fähige Images müssen weiterlaufen oder alle älteren Portal-/Mail-/Automation-Consumer vorher
gestoppt und gedraint werden. Vor der strukturellen Inverse-SQL sind zusätzlich Portal-Runtime,
Ingress/DNS und Portal-Mail-Consumer zu stoppen/drainen, weil die wiederhergestellten Resolver
absichtlich ungegated sind. Nicht per DDL rückholbare Legacy-Commerce-Zeilendaten benötigen weiterhin
ein DB-Backup.
**Stand:** `VA-P26a` bleibt **6/7 DoD = ~86 % done**. Offen bleibt derselbe externe Runtime-/UAT-/
User-Sign-off-Punkt. Der UAT muss nach Deploy dieses Gate-Slices Enable, Disable→404/keine
Provider-Mail und Re-enable beweisen. Es wird kein zusätzlicher DoD-Punkt gezählt.
### Scope-Präzisierung: vollständiger Einladungs-Lifecycle
2026-07-18 · Raffael: Der Produktvertrags-Abgleich hat eine Lücke in
der bisherigen Ticket-DoD sichtbar gemacht. Die bestehende Portalverwaltung legt bei einer direkten
Einladung nur einen `PortalUser` an, stellt aber keinen einlösbaren 7-Tage-Setup-Token aus und
verschickt keine Setup-Mail. Der Automation-Pfad erzeugt zwar Token und Mail, sein systemseitig
ausgestellter Token erfüllt den aktuellen IP-Bindungsvertrag jedoch nicht. Datenschutzannahme,
erneutes Senden und die Einstiege aus Kontakt-, Projekt- und Sales-Projekt-Sicht sind ebenfalls nicht
als vollständige Produktkette nachgewiesen.
Nach ausdrücklicher Produktfreigabe wird deshalb ein achter DoD-Punkt ergänzt. Der Deal-Einstieg wird
gemäß AD-20 nicht als alte separate Deal-Entität wiederbelebt, sondern über dieselbe Projektdetail-
Einladung für Projekte in einer Sales-Pipeline erfüllt. `VA-P26b` und `VA-P26c` bleiben bis zu diesem
Auth-/Projekt-Handoff blockiert. **Aktueller Stand: 6/8 DoD = 75 % done · 2 Checkboxen offen.** Der
Einladungs-Punkt hat einen lokal selbst machbaren Repository-Anteil, verlangt in derselben Checkbox
aber zusätzlich Live-RLS- und Browser-E2E-Proof; er kann deshalb erst zusammen mit dem externen
Staging-UAT gezählt werden. Der zweite offene Punkt ist der Runtime-/Trust-Boundary-UAT samt
User-Sign-off. Plane steht noch auf dem älteren Nenner und wird erst nach lokal grünem Proof
nachgezogen.
### Einladungs-Lifecycle: lokaler Repository-Proof
2026-07-18 · Raffael · Commits `9a2c3403e`, `3d303bc43`, `41724c91f` und
`fb7072e63` · **Lokal vollständig umgesetzt, noch nicht deployt.** Portalverwaltung,
Kontakt-Detail und Projekt-Detail verwenden jetzt denselben permission-gegateten Invite-/Resend-
Service; die Projektaktion vergibt den Projektzugang in derselben Transaktion. Der Erstzugang nutzt
einen einmaligen gehashten 7-Tage-Setup-Token. Die eigentliche Capability bleibt bis zur finalen
Provider-Grenze tenantgebunden verschlüsselt, wird vor dem Provider-Aufruf aus dem Queue-Payload
redigiert und bei unsicherem Delivery-Ausgang terminalisiert. `worker-mail` startet und meldet sich
ohne denselben `CRYPTO_SECRET` wie `hivegrid-web` fail-closed.
Der Setup-Flow aktiviert den PortalUser erst nach expliziter Datenschutzannahme, unterstützt den
weiterhin optionalen Passwortweg und erstellt erst anschließend die Portal-Session. Re-Invite,
Resend, fremde Kontakt-/Projekt-IDs, Frozen-/Permission-Denial, Gate-Disable und konkurrierende
Replays sind getestet. Der Lifecycle-/Anonymisierungsweg entfernt die neue Datenschutzmetadaten und
erhält für Token-/IP-Hashfelder die Datenbankform `64hex`.
**Lokaler Proof:** Root-Testlauf 963 Testdateien bestanden, 10 übersprungen; 6.561 Tests bestanden,
55 übersprungen. Der fokussierte Setup-/Mail-Security-Lauf ist 13/13 Dateien und 365/365 Tests grün;
Config-/Health 70/70, Coolify-Provisionierung 139/139 und Customer-Portal-UAT-Vertrag 121/121 sind
grün. Root-, Worker-, DB-, View-Model- und CLI-Typecheck, vollständiger Lint, Produktionsbuild beider
Web-Surfaces, Web-/Worker-Runtime-Closures, Bundle-Budget, Coverage, i18n, Hot-Swap, Visual-Baseline,
Docs-Links, Secret-Scan, Source-Health, Env-Drift und CI-/Deploy-Verträge sind grün. Migration-Parität,
Tenant-Policy-Vertrag und der frische eingeschränkte Live-RLS-Lauf mit allen acht Phasen sind grün;
RLS-Release-Readiness klassifiziert 290/290 Modelle und deckt 245/245 erzwungene Modelle ab. Der
registrierte Browser-Smoke und der externe Delivered-Mail-Adapter wurden lokal verifiziert, aber
nicht als echter Staging-/Provider-Lauf ausgegeben.
**Rollback:** Portal-Mail-/Outbox-Consumer stoppen und drainen sowie noch lebende Setup-Tokens
widerrufen. Ein Image-Rollback verwendet den vorherigen immutable Digest; der Mail-Worker darf nur
mit dem zum Web-Image passenden Envelope-Key wieder starten. Ein struktureller DB-Rollback erfolgt ausschließlich
koordiniert über die im Migration-File dokumentierte Inverse-SQL, nachdem Portal-Runtime und Worker
gestoppt wurden.
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen sind genau zwei Checkboxen: der echte
Runtime-/Trust-Boundary-UAT samt User-Sign-off sowie der Staging-Anteil des Einladungs-Lifecycle-
Punkts. Dafür fehlen noch Deploy der geprüften Revision, reale Mailjet-Zustellung, no-skip Browser-
Reise Einladung → Mail-Link → Datenschutz → Session → Projekt → Replay-Denial und die externe
Log-/Trust-Boundary-Prüfung. Im Repository ist für diese beiden Nachweise kein weiterer Codepunkt
offen.
### CI-Korrektur: RLS-Overlay-Drift
2026-07-18 · Raffael: Gitea-Run
[`#10519`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10519) hat nach einem
erfolgreichen 20:48-Minuten-Docker-Build den Web-Runtime-Smoke beim erneuten Einspielen des
Standalone-RLS-Overlays abgebrochen. Der Overlay-Resolver
`hivegrid_portal_resolve_user_email` referenzierte durch eine fehlerhafte Predicate-Übernahme den
nicht vorhandenen Alias `token`; die kanonische Merge-Migration enthielt weiterhin den korrekten
Statusvertrag für `invited` und `active`.
Der Overlay-Resolver ist wieder bytegleich an die migrationsgebundene Funktion gekoppelt. Ein
Regressionstest vergleicht den vollständigen Funktionsblock und verbietet Token-Aliase in diesem
E-Mail-Resolver. Das ändert keinen Auth-, Token- oder RLS-Vertrag, sondern stellt den bereits
gemergten Zustand wieder her. `VA-P26b` und `VA-P26c` konsumieren denselben Pre-Auth-Resolver und
bleiben dadurch kompatibel; ihre DoD-Stände ändern sich nicht.
**Proof:** Der gezielte Policy-Contract-Test ist mit 37/37 Tests grün; die vollständige DB-Suite mit
91 bestandenen und 6 übersprungenen Testdateien (800 bestanden, 116 übersprungen). Eine frische
PostgreSQL-16-Instanz hat die komplette Migrationskette und danach das Standalone-Portal-RLS-Overlay
unter dem eingeschränkten Migrator erfolgreich angewendet. `verify:migrations-parity`,
`verify:tenant-policy-contract` (292/292) und `verify:rls-release-readiness` (290/290 klassifiziert,
245/245 RLS-Policies) sind grün. Der abschließende Pre-Push-Lauf aus Typecheck, Lint und Gesamttest
ist grün (964 bestandene und 10 übersprungene Testdateien; 6.597 bestanden, 55 übersprungen).
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen bleiben dieselben zwei externen
Staging-/UAT-Punkte; die Korrektur zählt keinen neuen DoD-Punkt.
### CI-Korrektur: Mail-Worker-Runtime-Smoke
2026-07-19 · Raffael: Gitea-Run
[`#10605`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10605) hat den neuen
fail-closed `CRYPTO_SECRET`-Vertrag des Mail-Workers korrekt erkannt. Der produktive
Coolify-/Worker-Vertrag war bereits vollständig nachgezogen; ausschließlich die isolierte
`worker:health-mail`-Probe startete noch ohne den nicht-produktiven Envelope-Key-Fixture und meldete
deshalb deterministisch `misconfigured`. Der Smoke setzt den klar erkennbaren Fixture jetzt nur für
die Mail-Probe. Disabled-, General- und Runtime-General-Worker erhalten ihn weiterhin nicht; ein
Regressionstest erzwingt genau ein mail-spezifisches Vorkommen. Der Outbox-Vertrag wird nicht
abgeschaltet oder aufgeweicht.
**Proof:** Der reproduzierte Worker-Docker-Smoke ist inklusive frischer 191-Migrations-Datenbank,
eingeschränkten RLS-Rollen, Mail-/General-Health und negativen Deploy-Health-Gates grün; der zuvor
fehlgeschlagene `worker:health-mail`-Schritt lief in 1,28 Sekunden, der Runtime-Teil in 20,5 Sekunden.
Der fokussierte Config-/Health-/Docker-Vertrag ist 128/128 Tests grün. Der abschließende Root-Lauf
ist mit 966 bestandenen und 10 übersprungenen Testdateien beziehungsweise 6.693 bestandenen und 55
übersprungenen Tests grün; Typecheck, Lint, Docker-Baseline 309/309, Non-Root 4/4,
Deploy-Readiness, CI-/Deploy-Verträge, Secret-Scan, Source-Health und `git diff --check` sind grün.
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen bleiben ausschließlich die zwei
externen Staging-/UAT-Punkte; diese Smoke-Korrektur zählt keinen neuen DoD-Punkt.
### CI-Performance-Nachzug
2026-07-19 · Raffael: `CI-05` ersetzt die nachträglich eingeführte fünffache Docker-Serialisierung
durch einen einzigen gesperrten Production-Bundle-Schritt auf dem bereits warmen v2-Store. Fünf
parallele Offline-Deploys liegen in derselben atomaren RUN-Grenze; ein frozen Fetch mit vollständigem
Retry läuft nur nach einer fehlgeschlagenen Offline-Welle. Pruning und SBOM laufen danach targetweise ohne
Store-Mount. Getrennte parallele Build- und Runtime-Wellen bleiben erhalten. Die ungenutzte Buildx-
Setup-Action entfällt; erhöhte Docker-Kommando-Caps tolerieren Lastspitzen auf dem geteilten Runner,
ohne gesunde Pfade künstlich warten zu lassen.
Die für dieses Ticket relevanten Web-/Portal-/Worker-Images, Migrationen, RLS-Rollen, Health-Probes
und negativen Runtime-Gates bleiben unverändert vollständig enthalten. Run-spezifische Tags,
Container, Netze und Volumes verhindern weiterhin ref-übergreifende Kollisionen. Dieser reine
CI-Orchestrierungsnachzug ändert keinen Customer-Portal-Vertrag und keinen DoD-Zähler.
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen bleiben ausschließlich die zwei externen
Staging-/UAT-Punkte.
### Technischer Staging-Abschluss
2026-07-21 · Raffael: PR `#201` wurde als normaler Merge-Commit
`a747e9c655b2be4bd9ba52e59f56d5f0e9d145b0` übernommen. Deploy `#10909` blieb auf Staging: Der
erste Versuch scheiterte vor dem Start eines Kandidaten-Containers an einem transienten Registry-
Layer-Commit; der bis dahin laufende Core-/Portal-Stand blieb gesund und der Controller-Recovery-
Pfad stellte die alte Revision sicher. Genau ein Wiederholungslauf rollte anschließend Core und
Portal aus demselben SHA und Registry-Digest aus. Health, Readiness, DB-Rollen und der
revisionsgebundene Controller-Proof waren grün; der Recovery-Schritt erkannte den gesunden
Kandidaten und führte keinen Rollback aus. Alle Produktionspfade blieben übersprungen.
Der Staging-UAT bewies die Core↔Portal-/Host-Matrix, interne und unbekannte Pfade sowie fremde
Sessions mit fail-closed 404. Der globale M006-Schalter lief Enable → Disable → Re-enable; während
Disable blieb auch die externe Mailzustellung aus. Katalog und Portal-Fixture liefen jeweils über
Plan, Apply und Verify.
Die vollständige Einladungsreise ist für genau drei fachliche Einstiege grün: direkte
Portalverwaltung, Kontakt-Detail und Projekt-Detail. Jede frische Reise belegte Provider-Zustellung,
Datenschutzannahme, Session, erlaubten Projektzugriff und Replay-Denial. Vor der Projektreise wurden
genau drei fehlende `projects.read_own`-Rollenbindungen gezielt ergänzt, transaktional verifiziert
und erst nach dem Cache-Fenster weiterverwendet; andere Benutzer-, Passwort-, Checkout-, Provider-
oder Portalzustände blieben unverändert.
Der temporäre Test-Mailadapter war ausschließlich an `127.0.0.1` gebunden. Logs und diese
Dokumentation enthalten weder Tokens noch Empfänger, Mailinhalte oder private Proof-Hashes. Es wurden
keine Schlüssel oder Passwörter rotiert; die vorhandenen Zugangsdaten blieben unverändert.
**Abschlussstand:** `VA-P26a`: **8/8 DoD = 100 % done**. Der technische Handoff an `VA-P26b` und
`VA-P26c` ist erfüllt. `VD-P26` bleibt als separater Design-Nachzug offen; Produktion wurde nicht
freigegeben.
### UI-/Branding-Nachtrag
2026-07-22 · Raffael: PR `#212` hat die Endkunden-Shell und die täglichen Portalreisen auf den
bestehenden HiveGrid-UI-Baukasten angeglichen: klickbare, einklappbare Navigation, Sidebar-Inset,
Breadcrumbs, konsistente Seitenköpfe sowie eine reduzierte Übersicht und Projektansicht. Einstellungen
liegen getrennt unten in der Sidebar. Ein Tenant-Logo wird über einen privaten, gescannten Upload
konfiguriert und auf Standard- sowie Custom-Host angezeigt; ohne Logo greift die HiveGrid-Wortmarke als
Fallback. Die lokale Vorschau bleibt aus Production-Builds ausgeschlossen.
Main-Revision `090e2558a6965e1c5804eb24d3eab5da8c8611a8` bestand 13/13 PR-CI-Jobs und den
Staging-Deploy `#11018`. Core und Portal meldeten auf Health und Readiness dieselbe Revision aus demselben
Web-Digest; der Controller akzeptierte den Release ohne Rollback. Der vollständige aktuelle Produktstand
steht in [`docs/features/customer-portal.md`](../../docs/features/customer-portal.md).
Der Nachtrag ändert weder Auth-/RLS-Vertrag noch DoD-Zähler: **VA-P26a bleibt 8/8 = 100 % done**.
`VD-P26` bleibt als finaler Subframe-/Design-Nachzug offen.
## Was wir bauen
Die **eigene Runtime- und Auth-Schicht** des Customer-Portals (⭐ einzige extern sichtbare Endkunden-Oberfläche, höchster Polish): ein separater Coolify-Service/Container `hivegrid-portal` aus demselben immutable Web-Image, aber mit fail-closed Portal-Surface, eigenem minimal berechtigtem DB-Login und einer strikt von `TenantUser` getrennten **`PortalUser`-Klasse**. Eigene Cookies, öffentliche Standard-Routes unter `https://portal.hivegrid.de/<tenant>/…`, **keine Permission-Vermischung**, **Magic-Link primär**. Endkunden sehen nur **eigene Projekte / konfigurierte Stages / freigegebene Dokumente**; fehlender Zugang → **404** (keine Existenz-Offenlegung). Bei `project.stage_changed` gehen **Auto-Status-Mails** raus (debounced, bedingungsgesteuert). Workspace-Admin-Screens bleiben in `hivegrid-web`. `VA-P26c` ergänzt darauf Paket-Gates und Custom-Hosts; diese gehören nicht in dieses Ticket.
## Benötigte Screens (Backend bedient — Design liefert `VD-P26`, externer Polish)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Endkunde · Login [`portal.hivegrid.de/{tenant}/login` · `/login/magic-sent`] | Magic-Link primär, Passwort sekundär, „Magic-Link gesendet"-Bestätigung, **kein User-Enumeration** |
| Endkunde · Setup/Verify/Reset [`portal.hivegrid.de/{tenant}/setup/{token}` · `/verify-email/{token}` · `/forgot-password` · `/reset-password/{token}`] | Erstzugang-Setup, E-Mail-Verifizierung, Passwort-Vergessen/-Reset |
| Endkunde · Portal-Dashboard [`portal.hivegrid.de/{tenant}`] | Übersicht eigene Projekte + Status, freigegebene Dokumente, Schnellaktionen |
| Endkunde · Projekte-Liste [`portal.hivegrid.de/{tenant}/projects`] | Liste eigener Projekte (Name, Stage/Fortschritt, letztes Update) |
| Endkunde · Project-Detail [`portal.hivegrid.de/{tenant}/projects/:id`] | Fortschritt (**nur sichtbare Stages**), freigegebene Dokumente (Download) |
| Workspace-Admin · Mail-Template-Editor [`app.hivegrid.de/{tenant}/settings/customer-portal/email-templates`] | Auto-Status-Mail-Vorlagen je Stage-Event, Variablen, Vorschau |
## Definition of Done
- [x] **Runtime-/Trust-Boundary:** Pro Environment existieren genau zwei Web-Surface-Coolify-Ressourcen `hivegrid-web` und `hivegrid-portal` neben den übrigen API-/Worker-/Runtime-Ressourcen, beide aus demselben immutable `hivegrid/web:<sha>` und Registry-Digest. Der verpflichtende Production-Modus `WEB_RUNTIME_SURFACE=core|portal` bricht bei fehlendem, ungültigem oder zur Resource unpassendem Wert den Boot ab. Das fail-closed Gate läuft vor Static-Asset-Serving und React Router: Portal-Mode lässt nur konfigurierten Standardhost, Health, benötigte Assets/Data-Requests und Portal-Routes zu, löst den Tenant vor Auth auf und rewritet nur intern auf einen reservierten Portal-Namespace. App/Admin/API/Root/intern, unbekannte Hosts, direkte öffentliche Requests auf den internen Namespace sowie bis `VA-P26c` alle Custom-Hosts liefern 404. Core-Mode weist Standard-/Custom-Portalhosts und Portalpfade ebenfalls ab.
- [x] Eigene **`PortalUser`-/`PortalSession`-Welt strikt getrennt** von `User`/`TenantUser` und deren Sessions; Standardhost `portal.hivegrid.de/<tenant>`, **Magic-Link primär**. Das Portal verwendet ausschließlich `__Host-hivegrid_portal_session` und einen eigenen `PORTAL_SESSION_SECRET`; App-/Admin-Cookies werden nie gelesen oder akzeptiert und `SESSION_SECRET` ist in der Portal-Resource verboten. Serverseitige Session enthält unveränderlich `tenantId` + `portalUserId`; Pfad-, Session- und später Host-Tenant müssen exakt übereinstimmen.
- [x] Endkunde sieht **nur eigene Projekte / konfigurierte Stages / freigegebene Dokumente**; fehlender Zugang → **404** (keine Existenz-Offenlegung)
- [x] **Auto-Status-Mails** bei `project.stage_changed` (Debounce; Bedingungen: sichtbare Stage / aktiver Access / Pref / nicht frozen)
- [x] **Härtung:** Rate-Limits, Captcha, **kein User-Enumeration**, wasserdichte Cookie-Trennung
- [x] Wiederverwendung v1: Auth-Pattern (**parallel, NICHT geteilt**), Sende-Domain (Auto-Mails), `notify()`, Tenant-Lifecycle (`frozen`→read-only)
- [x] **Portal-RLS:** `hivegrid-portal` verbindet ausschließlich als `hivegrid_portal` (`LOGIN`, `NOINHERIT`, `NOBYPASSRLS`, keine Rollenmitgliedschaften) mit `RLS_RUNTIME_MODE=required`. Portalidentität wird über `app.portal_user_id` plus `app.tenant_id` gebunden, nie über `app.user_id`. Der Login erhält nur explizit geprüfte Portal-/ProjectAccess-/Stage-/Dokumentfreigabe-Policies und schmale Pre-Auth-`SECURITY DEFINER`-Resolver; keine Rechte auf `User`, `TenantUser`, `AdminUser`, Rollen/Permissions, Billing oder sonstige Tenantdaten. Live-Postgres-Tests beweisen PortalUser A/B, Tenant A/B, nicht freigegebene Projekte/Dokumente und Cross-Role-Denial. Der Punkt wird erst nach der reviewten forward-only P26-Merge-Migration, grüner migration-only Parität und dem eingeschränkten Staging-RLS-Proof abgehakt; Feature-Overlay, Recut-Helper und `prisma db push` zählen ausdrücklich nicht als Abschluss.
- [x] **Vollständiger Einladungs-Lifecycle:** Ein Workspace-Admin mit `portal.manage_users` kann Endkunden direkt aus der PortalUser-Verwaltung, vorausgefüllt aus dem Kontakt-Detail sowie aus dem Projekt-Detail einladen; die Projektdetail-Aktion vergibt den Projektzugang atomar und deckt nach AD-20 auch Sales-/Deal-Projekte ab. Jede neue oder erneut versendete Einladung erzeugt genau einen gehashten, einmaligen 7-Tage-Setup-Token, verschickt die Setup-Mail über den tenantgebundenen Mail-/Outbox-Vertrag und bleibt trotz systemseitiger Ausstellung sicher IP-gebunden. Der Setup-Flow aktiviert den User erst nach ausdrücklicher Datenschutzannahme, erlaubt weiterhin ein optionales Passwort und erzeugt erst danach die Portal-Session. Doppelte E-Mails, Re-Invite/Resend, fremde Kontakt-/Projekt-IDs, Frozen/Permission-Denial und Concurrent-Replays sind fail-closed, auditiert und RLS-geprüft. Unit-, Route-, Worker-, Live-RLS- und Browser-E2E-Proof decken Einladung → Mail-Link → Setup → Session → erlaubtes Projekt sowie Token-Replay ab.
## Technische Bausteine
- **Runtime-/Deploy-Slice:** kein neues `apps/portal` und kein neues Portal-Image im ersten Schnitt. `packages/config/src/types.ts`/`routing.ts`, `server/host-routing-runtime.ts` und `server/server.ts` erhalten einen fail-closed Portal-Runtime-Modus **vor Static-Asset-Serving und React Router**. Die Standard-URL wird nach sicherer Tenant-Auflösung intern auf einen reservierten Namespace (Arbeitsvertrag `/__portal/<tenant>/...`) rewritet; dieser Namespace ist von außen auf allen Hosts gesperrt, damit keine bestehende TenantUser-/Admin-Route matchen kann. `VA-P26a` liefert nur die sichere Erweiterungsnaht; Custom-Host-Auflösung und deren Rewrite gehören vollständig zu `VA-P26c`. Vom Client gelieferte interne Kontext-Header werden entfernt/überschrieben. `Dockerfile` bleibt beim Web-Target, bekommt aber einen surface-aware Healthcheck. Tenant-/Workspace-Admin-Routes bleiben ausschließlich im normalen Web-Service.
- **Root-/Loader-Grenze:** Portalrequests dürfen nicht durch Core-Root-Auth oder Core-Root-Data laufen. `apps/web/app/root.tsx` dispatcht anhand der vertrauenswürdigen Runtime-Surface auf getrennte Root-Middleware/-Loader/-Actions; im Portalpfad sind `getUserInfo`, `loadRootData`, Core-Session-Storage sowie `User`-/`TenantUser`-Queries verboten. Auch Locale-/CSRF-nahe Cookies verwenden die Portal-Konfiguration und nicht das Core-Session-Secret.
- **DB-/RLS-Grenze:** neuer Runtime-Login `hivegrid_portal` (`LOGIN`, `NOINHERIT`, `NOBYPASSRLS`, keine Rollenmitgliedschaften) mit minimalen Grants, `app.portal_user_id` + `app.tenant_id` und eigener tabellenweiser Portal-Policy-Matrix. Er wird nicht in den breiten App-/Worker-Tenant-Policy-Vertrag aufgenommen. Pre-Auth-Host-/Token-Auflösung erfolgt nur über eng begrenzte `SECURITY DEFINER`-Funktionen mit fixiertem `search_path`, entzogenem `PUBLIC EXECUTE` und exklusivem Execute-Recht für `hivegrid_portal`. Der bestehende `hivegrid_app`-Login oder nur tenantweite RLS zählt nicht als Proof.
- **Deploy-Identität:** `.gitea/workflows/deploy.yml`, Deploy-Verifier und Coolify-Helper adressieren Web und Portal über explizite Resource-Identitäten statt über das erste Image-Match, setzen denselben SHA/Digest, triggern beide separat und warten auf beide Deployments. `/healthz` unterscheidet Service/Surface und gebackene Revision; `/readyz` prüft die jeweilige DB-Rolle ohne sie öffentlich auszugeben. Bestehende Fly-/`PORTAL_SERVER_*`-Konsumenten werden auditiert und entfernt; keine Ingress-Credentials wandern in Web oder Portal.
- **Runtime-Secrets/Observability:** eigener Portal-Session-/Signing-Key, getrennte Rate-Limit-/Redis-Keys, CPU/RAM/PgBouncer-Limits und `service=hivegrid-portal`. Produktionsstartwerte: Core 2 vCPU/2 GB mit `DATABASE_POOL_MAX=10`, Portal 1 vCPU/1 GB mit `DATABASE_POOL_MAX=5` je Prozess/Instanz. Keine Authentik-JIT-, OAuth-, Billing-, Migrator-, Coolify-, SSH-, Traefik- oder Domain-Controller-Credentials. Dasselbe Sentry-Web-Projekt kann mit getrenntem Service-Tag verwendet werden.
- **Legacy-Recut vor neuen Entities:** `prisma/schema/portals.prisma` enthält bereits Boilerplate-Modelle `Portal`/`PortalUser` plus eine fachlich falsche Per-PortalUser-Commercewelt. Diese Modelle werden als einzige Portal-Domäne migriert: sichere/optionale Passwort-Identität, gehashte Auth-Tokens und Customer-Portal-Beziehungen ergänzen; nicht mehr benötigte `PortalSubscription*`-/Checkout-Modelle samt toten DB-Modulen nach Konsumenten-Audit entfernen. Kein paralleles zweites `PortalUser` anlegen.
- **Legacy-Recut DB-Push-/Merge-Vertrag:** Die historische RLS-Cutover-Migration bleibt unverändert. Vor einem ausschließlich lokalen/CI-seitigen Feature-Branch-`db push` läuft explizit `HIVEGRID_ALLOW_PORTAL_LEGACY_RECUT_DB_PUSH=1 pnpm run db:prepare:portal-legacy-commerce-recut`; der Helper ist auf Loopback-Datenbanken und die sieben geprüften `hg_Portal{Subscription*,UserSubscription*,CheckoutSessionStatus}_all`-Policies begrenzt, läuft atomar und bricht bei jeder weiteren Policy auf diesen Tabellen ab. Er ist **kein Migrationsersatz**: Beim Merge muss die eine forward-only P26-Migration für den ausgewählten gemeinsamen Portal-Vertragsstand nach einem fail-closed Bestandsdaten-Preflight die sieben Commerce-Policies sowie die Policy von `PortalUserRegistration` entfernen und insgesamt acht Tabellen FK-sicher child-first droppen (`PortalUserSubscriptionProductPrice` → `PortalUserSubscriptionProduct` → `PortalSubscriptionFeature`/`PortalSubscriptionPrice` → `PortalUserSubscription` → `PortalSubscriptionProduct` sowie `PortalCheckoutSessionStatus` und `PortalUserRegistration`). Vor `NOT NULL`/Unique/FK müssen `Portal.tenantId`, `PortalUser.tenantId`, `emailNormalized`, Tenant-Owner-Mismatches und normalisierte E-Mail-Kollisionen bewusst bereinigt werden. Alte `verifyToken`-/Registrierungs-Tokens werden nicht zu gültigen neuen Tokens umgedeutet; Status-/Verifikations-Mapping und Re-Invite sind eine dokumentierte Cutover-Entscheidung. Die Migration bettet App-/Worker-Tenant-Policies und die schmalen Portal-Policies unter genau einer äußeren Transaktion ein. Ihr Inverse-SQL-Kommentar beschreibt die strukturelle Wiederanlage parent-first inklusive Indizes, FKs, Grants und Policies und weist ausdrücklich darauf hin, dass gelöschte Zeilendaten nicht per DDL wiederherstellbar sind. `verify:migrations-parity` bleibt bis zu dieser Merge-Migration absichtlich rot; danach müssen `verify:migrations-parity` und der strikte, migration-only `HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live` beide grün sein. Operator-Ablauf: [`docs/deploy/customer-portal.md`](../../docs/deploy/customer-portal.md).
- **Entities** (in `prisma/schema/portals.prisma`, AD-21): `PortalUser` (eigene Identitäts-Klasse, **NICHT** `TenantUser`), Portal-Session/-Cookie-Modell (SameSite, getrennt), Magic-Link-Token + Setup/Verify/Reset-Token, `PortalProjectAccess` (welcher PortalUser sieht welches Projekt), `PortalStageVisibility`-Konfig, `PortalEmailTemplate` je Stage-Event. `project.prisma`/`crm.prisma`/`files.prisma` nur über FK (AD-21).
- **Auth-Trennung:** eigene hostgebundene Cookies, eigene Host-/Middleware-Kette für `portal.hivegrid.de/<tenant>/…`; Auth-Pattern aus v1 **kopiert, nicht geteilt** (kein Cross-Routing, keine Permission-Vermischung). Tenant-Auflösung erfolgt vor Auth; fehlender/ungültiger Zugang → 404 statt 403 (keine Enumeration).
- **Auto-Status-Mails:** Listener auf `project.stage_changed` (v1-Project-Stage-Trigger) → debounced Job; Bedingungs-Resolver (sichtbare Stage / aktiver Access / Pref / nicht frozen); Versand über v1-Sende-Domain; Templates aus `PortalEmailTemplate`.
- **Härtung:** Rate-Limits + Captcha auf allen Auth-Routes; die eigene tabellenweise PortalUser-/Access-Policy-Matrix aus der DB-/RLS-Grenze gilt verbindlich statt eines breiten tenantweiten RLS-Vertrags; `is_demo_data` auf seedbaren Portal-Demos.
## Quellen (granular)
- `ROADMAP-V2.md` → **§v2-P6 Customer-Portal** (Auth-Trennung/Magic-Link/Status-Mails = Hauptquelle; Depends-on/Success-Criteria/Recut)
- `ENTITY-MODEL.md` → **Domäne 5** (Project-Stages) + **Domäne 4** Files/FileEntityLink (Doc-Freigabe in P4 vorbereitet); PortalUser = parallele Auth-Klasse (kein geteiltes Auth-Modell)
- `ROADMAP.md` → Phase 26 · Milestones: (M141 Auth/Magic-Link, M142 Projekt-Sicht + Status-Mails)
- `designer-briefs/P26-customer-portal.md` (⭐ externer Polish, Auth-Trennung, 404-State, Mail-Template-Editor)
- `REQUIREMENTS.md` → `REQ-portal-runtime-isolation`
- `docs/ARCHITECTURE-DECISIONS.md` → AD-30 · `docs/INTEGRATION-CONTRACTS.md` §3/§14 · `docs/CHANGE-REQUESTS.md` CR-001
## Runtime-Slice: Fertig / Proof / zählt nicht
- **Fertigkeitskriterium:** Beide Coolify-Ressourcen laufen aus demselben SHA/Digest, booten nur mit passendem Surface-Modus, weisen die jeweils fremde Surface vor Assets und React Router mit 404 ab, benutzen getrennte Secrets und `hivegrid-portal` besteht Live-RLS mit minimalen Grants.
- **Proof:** Docker-/Deploy-Verifier, surface-aware Health-/Revision-Proof, Host-/Route-/Data-Request-Matrix und Live-Postgres-Test für PortalUser-/Tenant-/Cross-Role-Isolation auf Staging.
- **Zählt NICHT als fertig:** nur eine zusätzliche Domain am bestehenden Web-Container, ein zweiter Container mit `hivegrid_app`, ein Runtime-Flag erst innerhalb eines Route-Loaders oder ausschließlich gemockte RLS-Tests.
## Dev-Nachzug (nach Davids `VD-P26`-Delta)
**Interim-UI (Vorschau, Stand 2026-07-16):** Portal-Screens aus `~/ui` in
`apps/web/app/components/screens/customer-portal/CustomerPortalInterimPages.tsx`; die markierte
Interim-Baseline liegt unter
`packages/ui-mock/visual-baseline/va-p26a-customer-portal-interim.snapshot.json`. VM-, Hot-Swap-,
Visual- und Component-Proof sind lokal vorhanden; der Browser-Smoke ist registriert und wird nicht als
Staging-/Live-Lauf ausgegeben. Refactor-Nachzug: finale Subframe-Optik aus `VD-P26` und Re-Baseline.
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [x] Plane-Ticket `VA-P26a` mit 5/7-Stand und den zwei offenen externen Gates aktualisiert
(`c823b532-fd6f-46a5-aa19-0a331077f623`, 2026-07-16); Status bleibt In Progress
- [x] Plane-Ticket nach grünem Deploy auf 6/7-Stand und offenen Staging-UAT/User-Sign-off nachgezogen
(`8d1ab822-b8ee-4d2a-993c-e18c041bf745`, 2026-07-16); Status bleibt In Progress
## Abhängigkeitsnachzug · CR-007 · 2026-07-27
Das globale `customer-portal`-Rollout-Flag entfällt. Portal-Identität, Runtime-Trennung,
Tenant-/Subscription-Zustand, Veröffentlichung und RLS bleiben die fail-closed Grenzen.
## Pilot-Readiness-Nachzug · 2026-07-29
Der öffentliche Projekt-Upload begrenzt Multipart-Requests jetzt anhand der tatsächlich vom Parser
gelesenen Bytes. Fehlende oder absichtlich zu kleine `Content-Length`-Header umgehen das absolute
101-MB-Request-Limit nicht mehr; übergroße Streams enden stabil mit dem vorhandenen 413-/M002-Key,
bevor Dateien oder Storage-Zustand verarbeitet werden. Proof: fokussierte Helper- und Route-Tests,
ESLint und Web-Typecheck grün. **VA-P26a bleibt 8/8 DoD = 100 % done.**
Der Storage-Pfad übernimmt Portal-Dateien außerdem direkt als `Uint8Array`. Die bisherige
Base64-/Data-URI-Konvertierung mit anschließender erneuter Dekodierung und Blob-Kopie entfällt; Magic-
Bytes-Prüfung, fail-closed ClamAV-Scan und Provider-Fallback bleiben unverändert aktiv. Damit sinkt
der transiente Heap-Bedarf großer Uploads deutlich, ohne den Portal-/Storage-Vertrag zu erweitern.
Proof: 18 fokussierte Portal-/Storage-Tests, ESLint, Web-Typecheck und `git diff --check` grün.
**VA-P26a bleibt 8/8 DoD = 100 % done.**