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

@@ -135,21 +135,70 @@ Trust boundary: caller → loader (plugin manifest signature). Boundary: sandbox
```mermaid
flowchart LR
Admin["Tenant admin / DPO"]
Web["/admin/users/:id/export"]
API["API export endpoint"]
Worker["Worker exports.run"]
User["Tenant user / PortalUser"]
Web["Authenticated privacy / portal download route"]
Queue["hivegrid.exports"]
Writer["worker-import<br/>privacy + portal writers"]
Sweeper["worker-general<br/>15 min retention sweep"]
Storage[("Encrypted S3 bucket")]
Audit[("AuditEvent<br/>hash-chained")]
Admin --> Web
Web --> API
API -- "enqueue exports.run (CRITICAL priority)" -.-> Worker
Worker -- "stream user data (row-cap by plan)" --> Storage
Worker -- "append audit entry" --> Audit
Worker -- "signed URL (15 min)" --> Admin
User --> Web
Web -- "request bounded export" --> Queue
Queue -.-> Writer
Writer -- "SSE-C PUT (16/32 MiB cap)" --> Storage
Writer -- "append audit entry" --> Audit
Storage -- "SSE-C GET" --> Web
Web -- "authorized checked 200 attachment" --> User
Sweeper -- "DeleteObject after 24/72 h expiry" --> Storage
```
Trust boundary: admin → web (`admin.users.export` permission). Boundary: worker → storage (per-tenant prefix, server-side encryption). Boundary: audit chain (forensics; see `docs/security/incident-response.md`).
Trust boundary: user/PortalUser → the Core-Privacy- beziehungsweise
Customer-Portal-Route (Session, Tenant-/PortalUser-Ownership und Permission).
Boundary: Runtime → Storage. `worker-import` darf in die beiden deterministischen
GDPR-Prefixe schreiben, Core und Portal dürfen jeweils nur ihr eigenes Prefix
lesen, `worker-general` darf die beiden Export-Prefixe und den bestehenden
Tenant-Hard-Delete-Prefix nur eng begrenzt listen und löschen. Jede Runtime hat ein
eigenes Access-Key-Paar; nur Writer und Reader teilen den serverseitigen
32-Byte-SSE-C-Customer-Key. Dieser Key wird weder an den Browser noch in eine URL
gegeben. Exporte tragen keine benutzerdefinierten S3-Metadaten, weil Hetzner bei
SSE-C nur den Objektinhalt, nicht solche Metadaten verschlüsselt.
Der export-first Keyspace trennt
`gdpr-exports/privacy/tenants/{tenantId}/{exportJobId}/{attemptId}.zip` von
`gdpr-exports/portal/tenants/{tenantId}/{exportJobId}/{attemptId}.json`. Die
zufällige beziehungsweise deterministisch versuchsspezifische `attemptId`
verhindert, dass ein verlorener Retry ein bereits veröffentlichtes Artefakt
überschreibt. Die Portal-Objektadresse enthält keine PortalUser-ID.
Downloads prüfen Header, erwartete Länge und Obergrenze vor der Response; die
Byte-Obergrenze und exakte Endlänge werden während des begrenzten Streamings erneut
erzwungen. Download-Zähler und Audit dokumentieren deshalb den autorisierten
Download-Start, nicht den vollständig konsumierten Browser-Body. Es gibt keine
Presigned URL und keinen direkten Browserzugriff auf den Bucket. Privacy ist
ab 72 Stunden, Portal ab 24 Stunden nicht mehr abrufbar. Der 15-minütige Scheduler
löscht im ersten erfolgreichen Sweep nach Ablauf; Provider-/Queue-Ausfälle können
die physische Löschung verlängern und müssen deshalb bis zum erfolgreichen Retry
alarmieren. Die Zugriffssperre der App bleibt davon unabhängig sofort wirksam.
Bei deaktiviertem Versioning und Object Lock löscht eine auf `gdpr-exports/`
begrenzte dreitägige Provider-Lifecycle-Regel verwaiste Attempts als letzte
Rückfallebene. Sie darf keine anderen Bucket-Prefixe erfassen und ersetzt weder
den 15-Minuten-Sweep noch dessen Alarmierung; Provider-Lifecycle-Ausführung ist
asynchron und deshalb kein minutengenauer Retention-Nachweis.
Repository-Tests und Deploy-Preflight belegen diese Code- und Env-Grenzen, aber
nicht die tatsächlich aktive Hetzner-Bucket-Policy oder Provider-Semantik. Der
verbindliche Positiv-/Negativ-Proof ist daher der redigierte Staging-Operator-
Checkpoint in
[`docs/deploy/customer-portal.md`](../deploy/customer-portal.md#operator-checkpoint-provider-vertrag).
Der legacy Pfad `apps/worker/src/jobs/dsgvo-export.ts` und generische Presigned-URL-
Storage-Tests sind kein Nachweis für diesen GDPR-Vertrag. Boundary: Audit-Kette
(Forensik; siehe `docs/security/incident-response.md`).
Beim SSE-C-Cutover müssen die früheren Klartext-Keyspaces
`tenants/*/gdpr/*.zip` und `tenants/*/portal-gdpr/*/*.json` inventarisiert,
gelöscht und ihre DB-Referenzen abgelaufen beziehungsweise entfernt werden. Der
neue Reader bleibt für diese Legacy-Objekte fail-closed; es gibt keinen
Klartext-Fallback.
## STRIDE matrices per component
@@ -181,7 +230,7 @@ Each table follows the same shape: **Threat** (the STRIDE category and concrete
| **R** — Repudiated admin API call | Every `/v1/admin/*` request emits AuditEvent with request-id linkage | `apps/api/src/openapi.test.ts`, `verify:permission-matrix` | None known. |
| **I** — OpenAPI exposes admin route | OpenAPI guard rejects routes without explicit auth class | `apps/api/src/openapi.test.ts`, `verify:openapi-security` | None known. |
| **I** — Error envelope leak | Structured `{error: {code, messageKey}}` envelope; no raw `err.message` in mutating routes | `apps/api/src/error-envelope.test.ts` | B5 follow-up: a small number of legacy loaders still return string bodies. |
| **D** — Unauthenticated analytics flood | `ANALYTICS_TOKEN` gate + per-token rate-limit | `apps/api/src/route-access-inventory.test.ts` (`public-analytics-token`) | None known. |
| **D** — Unauthenticated analytics flood | Browser ingest capability plus per-IP and bounded anonymous-visitor rate limits; identity fields are rejected and writes run in an isolated tenantless RLS context | `apps/api/src/route-access-inventory.test.ts` (`public-analytics-token`) | The browser capability is intentionally public; infrastructure/WAF limits remain defense in depth. |
| **D** — Auth burst | Login rate-limit returns structured 429 | `apps/api/src/app.ts` rate-limit branch; `apps/api/src/auth.test.ts` | Distributed bursts handled by infra-level WAF. |
| **E** — Permission bypass via parameter tampering | Permission matrix loaded once at boot; every `/v1/*` handler asserts `assertCan(actor, action, resource)` | `verify:permission-matrix` | None known. |
@@ -195,20 +244,20 @@ Each table follows the same shape: **Threat** (the STRIDE category and concrete
| **R** — Side-effect replay without audit | Outbox is the only path to external side-effects in critical flows; receivers wrap with `withOutboxIdempotency` | `apps/worker/src/jobs/outbox-dispatcher.test.ts` | Legacy direct producers still exist; migration tracked in #42 follow-ups. |
| **I** — Job payload leak | PII-redaction at enqueue (`@hivegrid/logger` redact rules); SBOM excludes payload | `packages/logger/src/redact.test.ts` | Operator must verify Sentry breadcrumb scrubbers. |
| **D** — Queue starvation | Per-group queue separation (`general`, `mail`, `import`, `webhook`) + concurrency caps + job-priority | `apps/worker/src/queues.test.ts`, `docs/architecture/job-priority.md` | Operator must size per group; see runbook. |
| **E** — Worker → DB privilege escalation | Worker connects with role limited to required tables; no admin DDL grants | `infra/postgres/init.sql` + Coolify role provisioning | Mis-grant by operator → audited via [`docs/operations/database-rollback.md`](../operations/database-rollback.md). |
| **E** — Worker → DB privilege escalation | Worker connects as `hivegrid_worker`: `NOBYPASSRLS`, no role memberships, no DDL authority; job context may set only the trusted tenant identity | `scripts/provision-rls-roles.mjs`, `apps/worker/src/rls-context.ts`, `packages/db/src/rls-runtime-readiness.server.ts`, `verify:rls-live` | The production role/Coolify state still has to be verified during rollout; a mis-grant is a release blocker. |
### 4. Database (Postgres + PgBouncer + replicas)
| Threat | Mitigation | Evidence / Gate | Residual risk |
| --- | --- | --- | --- |
| **S** — Forged connection | mTLS to PgBouncer in production; per-app credentials in `userlist.txt` | `infra/pgbouncer/pgbouncer.ini`, `docs/ops/pgbouncer.md` | Operator must rotate per release. |
| **S** — Forged connection | PgBouncer is non-public, uses SCRAM-SHA-256, and carries separate credentials for `hivegrid_app`, `hivegrid_worker`, callback-only `hivegrid_authentik_jit`, and its admin probe | `infra/pgbouncer/pgbouncer.ini`, `docs/ops/pgbouncer.md`, `scripts/provision-rls-roles.mjs` | Transport/network controls and credential rotation remain operator-owned and must be verified in the target environment. |
| **T** — SQL injection | Prisma parameterized queries only; `$queryRaw` requires tagged template + lint rule | ESLint custom rule + grep guard in CI | `$executeRawUnsafe` banned in app code (allowed in CLI for migrations). |
| **T** — Backup tampering | Backups encrypted with age; SHA256 manifest signed at write | `docs/ops/backup-cli.md`, `packages/cli/src/backup/*.test.ts` | Encryption key custody: operator-owned. |
| **R** — Direct DB write without audit | Per-tenant write happens through Prisma + AuditEvent emission; direct `psql` writes flagged by `pg_stat_statements` review | [`docs/operations/database-rollback.md`](../operations/database-rollback.md) | Operator runbook. |
| **I** — Cross-tenant read | Every model query carries tenantId; static inventory snapshot enforced by test | `verify:tenant-isolation-report` | RLS not yet enforced; runtime integration test still pending (C3). |
| **I** — Replica leak | Read replicas configured with `hot_standby=on`, `default_transaction_read_only=on`; `DATABASE_READ_URL` user has SELECT only | `docs/architecture/rw-split.md`, `infra/postgres/replica.sql` | Operator must verify replica grants per release. |
| **I** — Cross-tenant read/write | Every Prisma model is explicitly classified; all 264 RLS definitions are generated from a reviewed policy contract, tenant tables use `ENABLE` + `FORCE RLS`, and runtime GUCs are transaction-local | `verify:tenant-policy-contract`, `verify:rls-release-readiness`, `verify:rls-live`, `prisma/migrations/20260713190000_appwide_rls_cutover/migration.sql` | Repository and ephemeral PostgreSQL proof do not prove the production cutover. Existing production data, roles, PgBouncer, replicas, and Coolify env must pass the rollout checks before traffic is enabled. |
| **I** — Replica leak | The read client is probed against the same restricted runtime-role, forced-RLS, policy, definer-allowlist, and empty-GUC contract as the write client | `packages/db/src/rls-runtime-readiness.server.ts`, `docs/architecture/rw-split.md` | Actual replica role/grant and migration lag must pass readiness in the target environment before it receives traffic. |
| **D** — Connection exhaustion | PgBouncer transaction pooling + per-app `max_client_conn` | `docs/ops/pgbouncer.md` | Long transactions block pool; mitigated by `statement_timeout`. |
| **E** — Privilege escalation in DB | Per-app role with least privilege; `pgcrypto` and `vector` extensions granted to migrator only | `infra/postgres/init.sql` | Operator must audit role grants per release. |
| **E** — Privilege escalation in DB | `hivegrid_app`, `hivegrid_worker`, and `hivegrid_authentik_jit` are `LOGIN NOBYPASSRLS` without memberships; the JIT login has no table/sequence privileges and can execute exactly one callback capability. `hivegrid_migrator` is non-superuser and may only `SET ROLE` to the `NOLOGIN BYPASSRLS` owner of an exact allow-list of narrow `SECURITY DEFINER` functions | `scripts/provision-rls-roles.mjs`, `packages/db/src/rls-runtime-readiness.server.ts`, `verify:rls-live` | The definer allow-list and grants must be reviewed whenever a new pre-tenant/platform capability is introduced; production grant drift fails readiness. |
### 5. Two-tier cache (Redis L2 + in-memory L1)
@@ -233,11 +282,11 @@ Each table follows the same shape: **Threat** (the STRIDE category and concrete
| Threat | Mitigation | Evidence / Gate | Residual risk |
| --- | --- | --- | --- |
| **S** — Spoofed presigned URL | Server-side signing with provider IAM credentials; client never holds long-lived keys | `packages/storage/src/s3.test.ts` | None known. |
| **S** — Spoofed presigned URL | Server-side signing with provider IAM credentials; client never holds long-lived keys; GDPR exports use no presigned URL | `packages/storage/src/s3-client.test.ts`, `packages/storage/src/sse-c.test.ts` | GDPR provider policy remains an operator checkpoint. |
| **T** — Upload of malicious file | AV scanner layer 1 (magic-bytes) + layer 2 (ClamAV planned) | `packages/storage/src/av-scan.test.ts`, `docs/ops/asset-cdn.md` | Layer 2 (ClamAV) container provisioning is operator step. |
| **I** — Public bucket exposure | Buckets default to private; ACL test enforces | `packages/storage/src/bucket-policy.test.ts` (operator-run) | Operator must verify per environment. |
| **D** — Egress cost burn | Per-tenant rate-limit on signed-URL issuance | `packages/storage/src/rate-limit.test.ts` | Operator-side WAF + Bunny CDN absorb large bursts. |
| **E** — Cross-tenant object read | Object key prefixed with `tenant:{tenantId}/...`; loader verifies prefix matches actor's tenant | `packages/storage/src/key-scope.test.ts` | None known. |
| **I** — Public bucket exposure | Buckets default to private; runtime keys remain action/prefix scoped | `packages/storage/src/s3-client.test.ts`, operator checkpoint in `docs/deploy/customer-portal.md` | Operator must verify per environment. |
| **D** — Egress cost burn | Distributed principal/artifact gate and bounded streaming on authenticated GDPR proxy; bounded signed-URL issuance elsewhere | `apps/web/app/utils/privacy/gdprExportDownloadGate.server.test.ts`, `packages/storage/src/sse-c.test.ts` | Operator-side WAF absorbs larger public bursts. |
| **E** — Cross-tenant object read | Tenant-bound key guards plus action/prefix-scoped runtime credentials | `packages/storage/src/access/index.test.ts`, `packages/storage/src/paths/index.test.ts`, `packages/storage/src/sse-c.test.ts` | Provider policy remains an operator checkpoint. |
### 8. Mail (`packages/mail`)
@@ -316,15 +365,16 @@ Each table follows the same shape: **Threat** (the STRIDE category and concrete
| **I** — Payload exfiltration | Outbound payload built from typed event schema; PII redacted before send | `packages/webhooks/src/payload.test.ts` | Operator must vet customer-configured destinations. |
| **D** — Slow-loris destination | Per-destination concurrency cap + timeout; circuit-breaker after consecutive failures | `apps/worker/src/jobs/webhook-delivery.test.ts` | None known. |
### 16. Form widget + lead capture
### 16. Form widget + native platform-lead intake
| Threat | Mitigation | Evidence / Gate | Residual risk |
| --- | --- | --- | --- |
| **S** — Forged embed origin | Origin allow-list per form (tenant-configured); `MARKETING_ALLOWED_ORIGINS` for global | `apps/web/app/routes/api.leads.capture.test.ts` | Operator must keep allow-list current. |
| **T** — Submission tampering | Server validates schema; honeypot field; Turnstile gate when enabled | `apps/web/app/routes/api.embed.forms.submit.test.ts` | Sophisticated bots may still pass Turnstile; rate-limit caps damage. |
| **S** — Forged platform source | Source-specific hashed Bearer credential; source identity comes only from that credential | `apps/api/src/routes/platform-lead-routes.test.ts` | Credential compromise requires immediate rotation/revoke. |
| **T** — Submission tampering/replay | Strict schema/body limit plus mandatory source-partitioned idempotency hash | `apps/api/src/routes/platform-lead-routes.test.ts`, `packages/db/src/platform-leads.rls.integration.test.ts` | A producer must reuse its submission ID until acknowledgement. |
| **T** — Embed-snippet tampering | SRI hash on `widget.js` (planned per form-widget detail-md follow-up) | `docs/features/form-widget.md` | Until SRI ships, customer must serve widget over HTTPS. |
| **I** — Lead PII exposure | Submissions stored per-tenant; admin inbox requires `marketing.leads.read` | `apps/web/app/routes/admin.marketing-leads.test.tsx` | None known. |
| **D** — Spam flood | Sliding-window rate-limit (5/min IP, 1/min email); Turnstile when enabled | `apps/web/app/routes/api.leads.capture.test.ts` | Distributed bots may evade IP limit. |
| **I** — Platform-lead PII exposure | Operator RLS + `read_own`/`read_all`; PII-free audit/outbox/queue payloads | `packages/db/src/platform-leads.rls.integration.test.ts`, `apps/worker/src/jobs/platform-notification-outbox.test.ts` | Privileged operators still require normal access review. |
| **D** — Spam/credential probing | Pre-auth IP limit plus source-specific rate limit; disabled ingress returns neutral 404 | `apps/api/src/public-ingress-rate-limit.test.ts`, `apps/api/src/routes/platform-lead-routes.test.ts` | Distributed probing remains observable via ingress metrics. |
| **R** — Stale browser writer | Legacy `/api/leads/capture` is write-free and returns 410; `marketing.js` removed | `apps/web/app/routes/api.leads.capture.test.ts` | Keep drain monitoring until all stale clients disappear. |
### 17. Feature flags + targeting
@@ -381,7 +431,8 @@ Each table follows the same shape: **Threat** (the STRIDE category and concrete
## Cross-cutting controls
- **Secret handling** — secrets never read from UI code; `@hivegrid/config` exposes typed loaders. `.env.test` allow-listed; `.env` git-ignored. See `docs/env-access-inventory.md`.
- **Branding / infra parametrization** — `BRAND_*` env vars and `scripts/infra-config.mjs` give forks override knobs without removing the verify-gate contract — see `docs/deployment-porting.md`.
- **Branding / infra parametrization** — `BRAND_*` env vars and `scripts/infra-config.mjs` keep
runtime configuration explicit; see `docs/deployment.md`.
- **Migrations** — structural Prisma diff verified via `verify:db-migrate-status`; rollback procedure documented in `docs/operations/database-rollback.md`.
- **Audit chain** — every privileged mutation emits an AuditEvent; the planned HiveGrid hash-chain verifier is the canonical forensics source referenced by [`incident-response.md`](./incident-response.md) once it lands.
- **SBOM** — generated per build; see [`sbom.md`](./sbom.md).