Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -15,11 +15,49 @@ Database operations are driven by key names only. Documentation, issues, CI logs
Required or relevant keys:
- `DATABASE_URL`: Prisma PostgreSQL connection setting used by migration status, migration deploy, runtime database access, and local development.
- `DIRECT_URL`: optional direct Prisma connection setting for maintenance flows when the deployment environment requires a separate direct connection.
- `DATABASE_URL`: Prisma-Verbindung der jeweiligen Runtime. Core-Web/API/MCP/Hocuspocus nutzen `hivegrid_app`, das Customer-Portal nutzt `hivegrid_portal`, Worker nutzen `hivegrid_worker`.
- `DIRECT_URL`: direkte, ungepoolte Verbindung des kurzlebigen Migrationsprozesses als `hivegrid_migrator`; sie gehört in keine Runtime.
- `AUTHENTIK_ADMIN_JIT_DATABASE_URL`: separate PgBouncer-Verbindung als `hivegrid_authentik_jit`; ausschließlich für den verifizierten Authentik-Callback im Web-Resource.
- `HIVEGRID_RLS_PROVISION_DATABASE_URL`: direkte Superuser-Verbindung ausschließlich für die einmalige oder bewusst wiederholte Rollen-Provisionierung.
- `HIVEGRID_RLS_MIGRATOR_PASSWORD`, `HIVEGRID_RLS_APP_PASSWORD`, `HIVEGRID_RLS_PORTAL_PASSWORD`, `HIVEGRID_RLS_WORKER_PASSWORD`, `HIVEGRID_RLS_AUTHENTIK_JIT_PASSWORD`: fünf unterschiedliche, mindestens 32 Zeichen lange Secrets aus dem freigegebenen Secret-Store.
Operators should confirm that the required key names exist in the target secret store, CI setting, or platform environment. Do not paste raw values into tickets, chat, docs, screenshots, or verifier output.
## PostgreSQL-Rollen und Provisionierung
HiveGrid verwendet sechs getrennte Rollen:
| Rolle | Zweck | Sicherheitsvertrag |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `hivegrid_migrator` | Eigentümer von Datenbank, `public`-Schema und den normalen Anwendungsobjekten; führt Prisma-Migrationen aus | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT` |
| `hivegrid_app` | Web-, API-, MCP- und Hocuspocus-Runtime | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT` |
| `hivegrid_portal` | Isolierte Customer-Portal-Runtime mit expliziten Portal-/Projektfreigaben | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT`, keine Mitgliedschaften |
| `hivegrid_worker` | Worker-Runtime | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT` |
| `hivegrid_authentik_jit` | Verifizierter Authentik-Callback im Web; nur JIT-Admin-Capability | `LOGIN`, keine Tabellen-/Sequenzrechte oder Mitgliedschaft |
| `hivegrid_rls_definer` | Eigentümer der explizit geprüften `SECURITY DEFINER`-Funktionen | `NOLOGIN`, `BYPASSRLS`, sonst keine administrativen Rechte |
Die einzige zulässige Mitgliedschaft ist `hivegrid_migrator` als Mitglied von `hivegrid_rls_definer`, mit `SET TRUE`, aber ohne `ADMIN` und ohne vererbte Rechte. App, Portal, Worker und Authentik-JIT dürfen weder Mitglied der Definer-Rolle noch einer anderen Rolle sein.
Die Rollen werden vor der ersten Migration und bei einer kontrollierten Passwortrotation idempotent provisioniert:
```sh
pnpm run db:roles:provision
```
Der Befehl verlangt die Provisionierungs-URL und alle fünf Passwort-Keys, gibt keine URL und kein Passwort aus und bricht ohne Superuser-Verbindung ab. Er setzt die Rollenattribute auf den exakten Vertrag zurück, entfernt unerwartete Mitgliedschaften, erzwingt SCRAM-Passwort-Hashes und prüft den Zustand vor dem Commit. Bei einem Fehler wird die Transaktion zurückgerollt.
Der Provisionierer überträgt die aktuelle Datenbank, das `public`-Schema und vorhandene, nicht zu einer Extension gehörende Anwendungsobjekte an `hivegrid_migrator`. Deshalb darf er nur gegen die dedizierte HiveGrid-Datenbank und bei bestehenden Installationen erst nach Backup und bestätigtem Restore-Pfad ausgeführt werden. Extension-Objekte behalten bewusst ihren bisherigen Eigentümer.
Sicherer Ablauf für eine neue Datenbank:
1. Datenbank anlegen und die sechs Rollen mit `pnpm run db:roles:provision` provisionieren.
2. `DIRECT_URL` ausschließlich im kurzlebigen Migrationsprozess auf `hivegrid_migrator` setzen.
3. Mit `pnpm run verify:migrator-role` den tatsächlichen Session-User, die nicht privilegierten Rollenattribute und die einzige erlaubte Definer-Mitgliedschaft prüfen.
4. Das freigegebene, unveränderliche Web-Image einmalig im `migrate`-Modus starten (`/myapp/start.sh migrate`). Dieser Pfad führt Rollenprüfung, Prisma-Migrationen und den globalen Permission-Reconcile als eine fail-closed Deploy-Kette aus.
5. Runtimes nur mit `hivegrid_app`, `hivegrid_portal` beziehungsweise `hivegrid_worker` starten. Die separate JIT-URL kommt ausschließlich in die Core-Web-Resource; Portal, API, MCP, Hocuspocus, Worker und Migrator erhalten keine Admin-SSO-Secrets.
Bei einer bestehenden Datenbank müssen vor Schritt 1 alle laufenden Schreiber angehalten oder in ein freigegebenes Cutover-Fenster gebracht werden. Nach der Migration sind Rollenattribute, Objekt-Ownership und Tenant-A/B-Isolation zu prüfen, bevor der Traffic wieder freigegeben wird.
## Local PostgreSQL and Prisma workflow
For local development, follow `docs/local-dev.md` first. Start a local PostgreSQL instance, create a disposable local database, set `DATABASE_URL` to a local placeholder value, and keep production credentials out of local files.
@@ -51,13 +89,25 @@ A passing migration-status gate means the status command completed. It does not
## Production migration deployment
Production migration deployment uses the package-level deployment command:
Production migration deployment uses the immutable web image's one-shot entrypoint:
```sh
pnpm run db:migrate:deploy
/myapp/start.sh migrate
```
Run this only in the approved deployment path for the target environment, with the environment's secret store providing `DATABASE_URL` and any required `DIRECT_URL`. The command applies already-authored Prisma migrations; it is not a schema authoring workflow and must not be mixed with local-only commands such as `pnpm exec prisma migrate dev` or `pnpm exec prisma db push`.
Run this only inside the approved one-shot container for the target environment. `DIRECT_URL` must be the unpooled connection that authenticates directly as `hivegrid_migrator` and must be scoped to that short-lived migration process. A superuser URL, a URL that reaches the role through `SET ROLE`, or any drift in the required role attributes and membership is forbidden. The bare package command `pnpm run db:migrate:deploy` is not an approved production path because it omits the mandatory post-migration permission reconcile.
The deployed web image runs `pnpm run verify:migrator-role` from `start.sh migrate` before it exposes the URL to Prisma. The probe fails closed unless both `session_user` and `current_user` are exactly `hivegrid_migrator`, the role is `LOGIN` but not superuser and cannot create databases or roles, inherit, replicate, or bypass RLS, and its only role edge is the constrained membership in `hivegrid_rls_definer`. The entrypoint then applies the migrations and reconciles the global permission catalog before it can exit successfully. None of these steps prints the connection string.
The one-shot migration path applies already-authored Prisma migrations; it is not a schema authoring workflow and must not be mixed with local-only commands such as `pnpm exec prisma migrate dev` or `pnpm exec prisma db push`.
### Globaler Permission-Reconcile nach Migrationen
Der freigegebene Containerpfad `start.sh migrate` führt erst nach einem erfolgreichen `prisma migrate deploy` den gebündelten Reconcile aus. Er gleicht ausschließlich den globalen `Permission`-Katalog, die globalen Defaultrollen (`tenantId IS NULL`) und deren katalogeigene Verknüpfungen ab. Der allein aufgerufene Package-Befehl `pnpm run db:migrate:deploy` enthält diesen Post-Migration-Schritt nicht.
Der Reconcile läuft fail-closed in einer kurzen Datenbanktransaktion. `hivegrid_rls_definer` erhält darin nur temporär die erforderlichen DML-Rechte; vor dem Commit werden sie wieder entzogen. `FORCE ROW LEVEL SECURITY` bleibt aktiv. Fehler bei Sicherheitsprüfung, Abgleich oder Daten-Postcondition rollen Daten und ACL-Änderungen dieser Transaktion zurück und stoppen den Deploy.
AD-29 schützt tenant-eigene Rollen und alle Rollen mit `isTemplateOrigin = true`: Sie werden im automatischen Deploy niemals angelegt, geändert, gelöscht oder mit Berechtigungen nachgezogen. Ist eine kanonische globale Rolle als Template-Ursprung markiert, bricht der Reconcile vor Rollen-DML fail-closed ab; Tenant-Rollen bleiben unberührt. Änderungen an Bestands-Tenants erfordern eine explizit freigegebene, auditierte Operator-Aktion. Allgemeines Seeding bleibt unter erzwungener RLS verboten; der globale Reconcile ist keine Seed-Freigabe.
Before deploying, confirm that the intended migration set has passed review and that the CI migration-status gate is healthy. After deployment, inspect the approved deployment logs and the migration-status verifier output for redacted success or failure signals. If deployment fails, do not paste connection details or table contents into the incident record; capture the command name, exit code, diagnostic phase, and sanitized Prisma excerpt only.
@@ -86,7 +136,7 @@ Generation does not connect to production data and must not be treated as a migr
Use these safe inspection surfaces for database failures:
- CI logs from `pnpm run verify:db-migrate-status` with sanitized stdout and stderr excerpts.
- Approved deployment logs for `pnpm run db:migrate:deploy` with secrets redacted.
- Approved deployment logs from the immutable web image's `/myapp/start.sh migrate` one-shot path, with secrets redacted.
- Local command output from `pnpm exec prisma migrate status` against a disposable local PostgreSQL database.
- Package script names, exit codes, diagnostic phases, and redacted Prisma error codes.
- `docs/db-ci.md` for the CI status verifier contract and `docs/local-dev.md` for local setup checks.
@@ -95,8 +145,8 @@ Common failure patterns:
- Missing `DATABASE_URL`: confirm that the key exists in the CI secret or platform environment and is scoped only to the database operation that needs it.
- Connection or authentication failure: confirm the secret store and database service health without copying the value, username, password, host, or database name into logs.
- Migration drift: run the status gate, inspect the sanitized Prisma status message, and distinguish read-only status output from deploy behavior before deciding on `pnpm run db:migrate:deploy`.
- Migration drift: run the status gate, inspect the sanitized Prisma status message, and distinguish read-only status output from deploy behavior before deciding whether to invoke the approved `/myapp/start.sh migrate` one-shot path.
- Stale Prisma client: run `pnpm run db:generate` and re-run the focused check that reported stale generated artifacts.
- Local schema mismatch: use local-only `pnpm exec prisma migrate status`, `pnpm exec prisma migrate dev`, or a deliberate disposable `pnpm exec prisma db push` according to `docs/local-dev.md`.
If any troubleshooting output reveals a connection string, credential, hostname, username, password, database name, or customer data, treat it as a secret leak. Remove the exposed material from the shared surface, rotate affected credentials, preserve only redacted evidence, and fix the logging or documentation path before continuing.
If any troubleshooting output reveals a connection string, credential, hostname, username, password, database name, or customer data, treat it as a secret leak. Remove the exposed material from the shared surface, rotate affected credentials, preserve only redacted evidence, and fix the logging or documentation path before continuing.