312 lines
25 KiB
Markdown
312 lines
25 KiB
Markdown
# Tenant-Snapshot mit PII-Anonymisierung + Restore
|
|
|
|
**Status:** completed
|
|
**Task-ID:** #44
|
|
**Phase:** 03
|
|
**Estimated Effort:** 1 Woche
|
|
**Owner:** unassigned
|
|
|
|
## Problem
|
|
|
|
Dev/QA/Sales-Teams brauchen regelmäßig „Production-ähnliche" Test-Datasets, aber:
|
|
|
|
- **Direkter Prod-DB-Dump in Dev = DSGVO-Verstoß** (PII, Stripe-IDs, Emails, IPs).
|
|
- **Manuelle Anonymisierung ist fehleranfällig** (vergessene Felder, inkonsistente Replacement-Patterns, kein Tracking welche Snapshots welches Anonymisierungs-Profile haben).
|
|
- **Bug-Reproduction von einem spezifischen Tenant-State ist heute unmöglich** — Operator müsste komplette DB ziehen, was wegen DSGVO blockiert.
|
|
- **Sales-Demos brauchen realistische Tenants** mit Workflows, Subscriptions, Audit-Trail — Synthetic-Data hat nie die Komplexität.
|
|
- **QA-Test-Datasets sind hand-kuratierte Fakten-Sammlungen** → veralten, decken Edge-Cases nicht ab.
|
|
|
|
Use-Cases die wir freischalten:
|
|
1. **Bug-Repro:** „Customer X meldet Bug in Workflow Y" → Snapshot ziehen, in Dev-Env restore, debuggen.
|
|
2. **QA-Datasets:** monatlich pro Plan-Tier (Free/Pro/Enterprise) ein Snapshot eines repräsentativen Tenants → CI-Test-Fixture.
|
|
3. **Sales-Demos:** Snapshot eines „idealen" Production-Tenants → in Demo-Env restore → realistisches Show-and-Tell.
|
|
4. **Tenant-Migration:** Tenant zu separater Instance umziehen (z.B. Enterprise-Tenant auf dediziertem Server).
|
|
|
|
Betroffene Codestellen:
|
|
- Prisma-Schema: alle Models mit `tenantId`-Spalte (User, Row, Entity, Workflow, Subscription, AuditLog, etc.) — Subagent enumeriert alle in Research-Phase.
|
|
- Storage-Layout: `tenants/<tenantId>/...` Convention.
|
|
|
|
## Depends on
|
|
|
|
- `03-scaling-infrastructure/backup-cli.md` — Tenant-Snapshot baut auf der gleichen CLI-Infrastruktur (Citty-Commands, Encryption-Layer, S3-Sink, Manifest-Schema-Pattern). Reuse statt Parallelentwicklung.
|
|
- `01-tech-debt-foundation/supabase-removal.md` — Saubere einheitliche Storage-Abstraktion damit Tenant-Files konsistent iterierbar sind.
|
|
- `03-scaling-infrastructure/shared-store-package.md` — Tenant-Plan-Info-Lookup im Anonymisierungs-Profile (verschiedene Anonymisierungs-Strenge je Plan möglich, z.B. Enterprise-Tenants wollen vielleicht „weniger" anonymisiert für Sales-Repros).
|
|
|
|
## Blocks
|
|
|
|
- `08-mobile-cli-storybook-sdk/cli-ops.md` — CLI-Ops-Package bündelt Tenant-Snapshot als weiteres Sub-Tool.
|
|
- `10-compliance-polish/dsgvo-bulk-ops.md` — DSGVO-Datenexport pro User profitiert vom gleichen Selector-Pattern (tenantId + userId-Filter).
|
|
|
|
## Approach
|
|
|
|
**CLI-Command `tenant:snapshot` und `tenant:restore` im selben `packages/cli/`-Package wie Backup, separater Command-Tree.**
|
|
|
|
**Anonymisierungs-Profile (deklarativ):**
|
|
- `profile=full-anonymized` (Default für Snapshots) — alle PII ersetzt, deterministisch (gleicher Input → gleicher Output für Foreign-Key-Konsistenz).
|
|
- `profile=minimal-anonymized` — nur Felder die DSGVO-strikt sind (Email, Phone, Address, IP, Stripe-IDs); FirstName/LastName bleiben.
|
|
- `profile=none` — KEINE Anonymisierung. Nur durch Operator mit Super-Admin-Recht erlaubt, hard-gated, separater Audit-Eintrag.
|
|
|
|
**Anonymisierungs-Mapping (`profile=full-anonymized`):**
|
|
|
|
| Feld-Typ | Mapping |
|
|
|---|---|
|
|
| Email | `user{seq}@anonymized.test` — deterministisch via SHA256(originalEmail)[:8] |
|
|
| FirstName | `faker.person.firstName(seed=hashedId)` |
|
|
| LastName | `faker.person.lastName(seed=hashedId)` |
|
|
| Phone | `null` |
|
|
| Address (Street/City/Country) | `faker.location.*(seed=hashedId)` |
|
|
| ZipCode | erste 2 Ziffern behalten + Rest random (Postleitzahl-Bereich) |
|
|
| IPAddress | `127.0.0.{seq % 255}` |
|
|
| Stripe-CustomerID | `cus_anon{seq}` |
|
|
| Stripe-SubscriptionID | `sub_anon{seq}` |
|
|
| Stripe-PaymentMethodID | `pm_anon{seq}` |
|
|
| API-Keys / Secrets (in Settings-JSON) | `[REDACTED]` |
|
|
| Webhook-URLs (custom) | `https://anonymized.test/webhook/{seq}` |
|
|
| User-Avatar-URLs | `https://anonymized.test/avatar/{seq}.png` (Storage-Objects werden trotzdem mitexportiert aber Public-Hosts darin rewritten) |
|
|
|
|
**Konsistenz-Hash:** Pro Snapshot wird ein Salt generiert, alle Anonymisierungen nutzen `hash(salt + originalValue)` als Seed. → Innerhalb eines Snapshots ist Anonymisierung deterministisch (User Alice referenziert in Workflow X = User Alice referenziert in Workflow Y), aber zwischen Snapshots verschieden (kein Cross-Snapshot-Reverse-Engineering).
|
|
|
|
**Snapshot-Format:** Gleiche Struktur wie Backup, aber tenant-scoped.
|
|
```
|
|
toolctrl-snapshot-<tenant-slug>-<iso8601>-<short-uuid>.tar.gz
|
|
├── manifest.json # Tenant-ID, Source-Slug, Schema-Version, Anonymization-Profile, Anonymization-Salt-Hash, ExportDate, CreatedBy
|
|
├── prisma/
|
|
│ └── data.jsonl # NDJSON: { model: 'User', data: {...} } — pro Row eine Zeile
|
|
├── storage/
|
|
│ ├── manifest.jsonl # { originalKey, newKey, size, etag }
|
|
│ └── objects.tar
|
|
└── audit/
|
|
└── snapshot-event.json # Audit-Trail-Entry für diesen Snapshot (im Source-System)
|
|
```
|
|
|
|
**Restore-Logik:**
|
|
- `tenant:restore <snapshot> --target-tenant-slug=<new-slug>` legt neuen Tenant in Target-DB an (oder failt wenn slug existiert ohne `--force`).
|
|
- Rewrited alle FK-Beziehungen (Snapshot-Tenant-ID → Neu-Tenant-ID), generiert neue IDs für alle Rows (UUID-Remapping-Table im Memory).
|
|
- Storage-Objects landen unter `tenants/<new-tenant-id>/...` in der lokal-konfigurierten Storage.
|
|
- Sanity-Check am Ende: alle FKs valid, keine dangling references.
|
|
|
|
**Permission-Model:**
|
|
- Source-System (Snapshot-Export): **nur Super-Admin** (Plattform-Owner). Tenant-Admin darf NICHT seinen eigenen Tenant snapshotten — könnte Daten anderer User des Tenants exfiltrieren in unverschlüsselter Form. Mitigation: User-DSGVO-Export ist separater Pfad (Task `10-compliance/dsgvo-bulk-ops.md`).
|
|
- Target-System (Restore): jeder Operator des Ziel-Systems (Dev-Box etc.). Kein hardes Gate, weil Snapshot-File ist die Berechtigung.
|
|
- Audit-Log-Eintrag pro Snapshot im Source-System (Actor, TenantID, Profile, Timestamp).
|
|
|
|
**Begründung gegen Alternativen:**
|
|
- *Anonymisierung in einem separaten Post-Processing-Step (Snapshot raw, dann anonymize):* doppelter Speicher, Risiko dass raw Snapshot „vergessen" wird. Lieber inline.
|
|
- *DB-Trigger-basierte Anonymisierung in einer separaten Anonymized-Replica:* zu viel Infra-Aufwand für Toolctrl-Boilerplate-Größe.
|
|
- *Library wie pg_anonymize:* nicht TS-nativ, kein Storage-Backup, kein Foreign-Key-Awareness wie wir es brauchen.
|
|
|
|
## Implementation Steps
|
|
|
|
1. **Tenant-Model-Enumeration** — alle Tenant-scoped Models entdecken
|
|
- Files: `packages/cli/src/commands/tenant/models.ts` (neu) — exportiert `TENANT_SCOPED_MODELS: Array<{ model: string; tenantField: string }>`. Enthält explizite Liste (User, Row, Entity, Workflow, Subscription, AuditLog, ApiKey, EmailMarketingCampaign, etc.). Subagent recherchiert Prisma-Schema und liefert vollständige Liste.
|
|
- Tests: `models.test.ts` — assert dass jede Prisma-Model-Klasse mit `tenantId`-Spalte in der Liste ist (introspection via `Prisma._dmmf`).
|
|
- Commit: `03-scaling/tenant-snapshot: enumerate tenant-scoped models`
|
|
|
|
2. **Anonymizer-Engine** — Profile-basierte Field-Transformations
|
|
- Files:
|
|
- `packages/cli/src/commands/tenant/anonymizer.ts` — Klasse `Anonymizer({ profile, salt })`. Methode `transform(model, row)` returnt anonymisiertes Row-Object. Lookup-Table pro Model: welche Felder welche Transform-Funktion (Email-Anonymizer, Faker-Person-Name, IP-Mask, etc.).
|
|
- `packages/cli/src/commands/tenant/profiles.ts` — die 3 Profile als Konfiguration.
|
|
- Faker-Seed-Mechanismus: `faker.seed(parseInt(hash(salt + rowId), 16) % MAX_INT)`.
|
|
- Tests: `anonymizer.test.ts` — pro Profile pro Feld-Typ ein Test; Determinismus-Test (gleicher salt + input → gleicher output).
|
|
- Commit: `03-scaling/tenant-snapshot: anonymizer engine with 3 profiles`
|
|
|
|
3. **Data-Extractor** — Prisma-Query pro Model filtered by tenantId
|
|
- Files: `packages/cli/src/commands/tenant/extractor.ts` — `extractTenantData(prisma, tenantId, anonymizer)` async iterator yieldet `{ model, data }` Objects. Nutzt Cursor-basiertes Paging (1000er-Chunks) damit large Tenants nicht den Speicher sprengen. Foreign-Key-Order-aware: User vor Row, Row vor RowSetting, etc. (Topological-Sort der Models).
|
|
- Tests: `extractor.test.ts` — Test-Tenant in testcontainers-Postgres, assert dass alle Models extrahiert werden, anonymisiert, in richtiger FK-Order.
|
|
- Commit: `03-scaling/tenant-snapshot: cursor-based data extractor`
|
|
|
|
4. **Storage-Extractor** — Tenant-Files aus S3 holen, ggf. anonymized rewrites
|
|
- Files: `packages/cli/src/commands/tenant/storage-extractor.ts` — listet alle Objects mit Prefix `tenants/<tenantId>/`, download streamt in tar, schreibt `manifest.jsonl` mit `{ originalKey, newKey, size, etag }`. `newKey` ist `tenants/SNAPSHOT_TENANT_ID/...` mit Platzhalter, der beim Restore ersetzt wird.
|
|
- Tests: `storage-extractor.test.ts` — gegen MinIO mit 50 Test-Files unter `tenants/abc/...`, assert alle drin.
|
|
- Commit: `03-scaling/tenant-snapshot: storage extractor for tenant files`
|
|
|
|
5. **`tenant:snapshot`-Command** — Glue
|
|
- Files: `packages/cli/src/commands/tenant/snapshot.ts` — Citty-Command.
|
|
- Args: `<tenantId>`, `--target=<output-file>` (default `./toolctrl-snapshot-<tenant-slug>-<ts>.tar.gz`), `--profile=full-anonymized|minimal-anonymized|none`, `--include-storage` (default true), `--encrypt=age|none`
|
|
- Flow:
|
|
1. Permission-Check: SUPER_ADMIN_API_KEY env-set, prompt for confirmation if `profile=none`.
|
|
2. Generate Salt.
|
|
3. Iterate `extractTenantData` → schreibe `prisma/data.jsonl` (im tempdir).
|
|
4. Storage-Extract → `storage/`.
|
|
5. Manifest erzeugen (inkl. Salt-Hash, nicht Salt selbst).
|
|
6. tar.gz.
|
|
7. Encrypt (optional).
|
|
8. AuditLog-Entry im Source-System (separater Prisma-Write).
|
|
- Tests: `snapshot.integration.test.ts` — gegen testcontainers, assert Output-Datei existiert + parsbar + Anonymisierung wirksam (Sample-Check: kein Email-Pattern `*@*.com` außer `*@anonymized.test`).
|
|
- Commit: `03-scaling/tenant-snapshot: tenant:snapshot command`
|
|
|
|
6. **Restorer + FK-Remapper** — Snapshot in Target-DB einspielen
|
|
- Files: `packages/cli/src/commands/tenant/restorer.ts` — `restoreTenantSnapshot(prisma, snapshotPath, { targetSlug })`. Flow:
|
|
1. Untar.
|
|
2. Neuer Tenant-Row erstellen (slug aus `--target-tenant-slug`).
|
|
3. ID-Mapping-Table: `Map<oldId, newId>` pro Model (alle Primary-Keys neu generieren).
|
|
4. Iterate NDJSON, FK-Felder via Mapping ersetzen, Insert.
|
|
5. Storage-Objects: Tar entpacken, jeden Key `tenants/SNAPSHOT_TENANT_ID/...` → `tenants/<new-tenant-id>/...` umbenennen, upload.
|
|
6. Sanity-Check: Foreign-Key-Integrity (`SELECT COUNT(*) FROM Row WHERE tenantId NOT IN (SELECT id FROM Tenant)` muss 0 sein, etc. pro Model).
|
|
- Tests: `restorer.test.ts` — Full-Cycle: snapshot eines Tenants → restore in zweiter DB → assert Row-Counts matchen + Sample-File downloadbar.
|
|
- Commit: `03-scaling/tenant-snapshot: restorer with fk remapping`
|
|
|
|
7. **`tenant:restore`-Command** — CLI-Wrapper für Restorer
|
|
- Files: `packages/cli/src/commands/tenant/restore.ts` — Citty-Command. Args: `<snapshot-file>`, `--target-tenant-slug=<slug>`, `--target-db=<connStr>` (default aus Env), `--force` (existing slug erlaubt).
|
|
- Confirmation-Prompt (außer `--yes`).
|
|
- Commit: `03-scaling/tenant-snapshot: tenant:restore command`
|
|
|
|
8. **Audit-Log-Hook** — Im Source-System loggen
|
|
- Files: `packages/cli/src/commands/tenant/audit.ts` — `logSnapshotEvent(prisma, { tenantId, actorUserId, profile, snapshotKey })` schreibt AuditLog-Entry mit Event `TENANT_SNAPSHOT_CREATED`. Permission-Check: nur Super-Admin-API-Key darf Snapshot triggern.
|
|
- Tests: `audit.test.ts` — assert Entry geschrieben.
|
|
- Commit: `03-scaling/tenant-snapshot: audit log entry for snapshot ops`
|
|
|
|
9. **Doku** — `docs/operations/tenant-snapshot.md`
|
|
- Files: neu. Inhalt:
|
|
- Use-Cases (Bug-Repro, QA, Sales-Demos, Migration)
|
|
- Anonymisierungs-Profile + Mapping-Tabelle
|
|
- Permission-Model (Source vs Target)
|
|
- CLI-Beispiele für alle 3 Use-Cases
|
|
- Restore-in-Dev-Workflow (mit lokal Setup)
|
|
- Sicherheitswarnung für `profile=none`
|
|
- Troubleshooting (FK-Errors beim Restore, Storage-Bucket-Mismatch)
|
|
- Commit: `03-scaling/tenant-snapshot: operations doc`
|
|
|
|
10. **Lint-Rule für PII-Fields** — Optional aber empfohlen
|
|
- Files: `packages/cli/src/commands/tenant/lint.ts` (oder als Test) — ESLint-Custom-Rule oder Vitest-Test der das Prisma-Schema scant und sicherstellt, dass alle Felder mit `@map("email")`, `@map("phone")`, etc. im Anonymizer-Mapping abgedeckt sind. Verhindert vergessene PII-Felder bei Schema-Erweiterungen.
|
|
- Tests: `lint.test.ts` — synthetisches Schema mit „vergessenem" PII-Feld → Lint failed.
|
|
- Commit: `03-scaling/tenant-snapshot: schema lint for pii field coverage`
|
|
|
|
## Test Requirements
|
|
|
|
- **Unit-Tests:**
|
|
- `anonymizer.test.ts` — pro Profile pro Feld-Typ; Determinismus-Test.
|
|
- `models.test.ts` — vollständige Tenant-Model-Coverage gegen Prisma-DMMF.
|
|
- `extractor.test.ts` — Cursor-Paging, FK-Order.
|
|
- `restorer.test.ts` — FK-Remapping, Sanity-Checks.
|
|
- `audit.test.ts` — Permission-Gate funktioniert.
|
|
- **Integration-Tests:**
|
|
- `packages/cli/test/integration/tenant-snapshot-cycle.test.ts` — End-to-End: 2-Tenant-Test-DB → snapshot Tenant A → restore in zweite DB als Slug `tenant-a-clone` → assert:
|
|
- alle Tenant-A-Rows da (Counts identisch)
|
|
- alle Anonymisierungen angewendet (Sample-Emails matchen `*@anonymized.test`)
|
|
- alle FKs valid
|
|
- Storage-Objects unter neuem Tenant-Prefix
|
|
- Audit-Eintrag im Source-System
|
|
- **E2E:** kein UI → kein Playwright.
|
|
- **Coverage-Target:** ≥ 85% für `packages/cli/src/commands/tenant/`.
|
|
- **Test-Files:** wie aufgelistet.
|
|
|
|
**NICHT als completed markieren bevor alle Tests grün sind.** Daten-Anonymisierungs-Bugs sind DSGVO-Risiken.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `tenant:snapshot` und `tenant:restore` CLI-Commands implementiert
|
|
- [ ] 3 Anonymisierungs-Profile (full/minimal/none) wählbar
|
|
- [ ] Anonymisierung deterministisch (Salt-basiert) → FK-Konsistenz innerhalb Snapshot
|
|
- [ ] Snapshot enthält Manifest mit Anonymisierungs-Profile-Hinweis
|
|
- [ ] Storage-Objects mitexportiert und beim Restore unter neuem Tenant-Prefix landen
|
|
- [ ] FK-Remapping beim Restore funktioniert (Sanity-Check grün)
|
|
- [ ] Permission: Snapshot nur mit Super-Admin-API-Key
|
|
- [ ] Audit-Log-Entry pro Snapshot im Source-System
|
|
- [ ] PII-Coverage-Lint sichert alle bekannten PII-Felder
|
|
- [ ] `docs/operations/tenant-snapshot.md` enthält alle 4 Use-Cases
|
|
- [ ] Tests grün (lint, typecheck, unit, integration)
|
|
- [ ] Staging-Verifikation: snapshot real-Tenant → restore in Dev-Box → manueller Smoke-Test in Dev-UI
|
|
- [ ] Detail-MD Progress Log aktualisiert
|
|
- [ ] PROGRESS.md Status auf `completed`
|
|
|
|
## Rollback Strategy
|
|
|
|
- **Code-Rollback:** Eigenes CLI-Package, kein Production-Impact. Commits revertieren.
|
|
- **Existierende Snapshots:** bleiben gültig (versioniert via Manifest-Schema-Version). Restore-Pfad muss alte Schema-Versionen weiterhin lesen können → Migration-Logic in `restorer.ts` falls Schema sich ändert.
|
|
- **Audit-Log-Entries:** bleiben bestehen (read-only by design).
|
|
|
|
## Security Notes
|
|
|
|
- **PII-Vollständigkeit:** Höchstes Risiko. Wenn ein PII-Feld in der Anonymizer-Map vergessen wird, leakt es im Snapshot. Mitigation:
|
|
- PII-Coverage-Lint (Step 10).
|
|
- Code-Review mit Security-Track-Subagent.
|
|
- Stichproben-Test: Snapshot eines Test-Tenants generieren, `grep -E "[\\w.]+@[\\w.]+\\.[a-z]+" snapshot.tar.gz` (nach Decompression) sollte nur `@anonymized.test`-Matches finden.
|
|
- **`profile=none` Missbrauch:** Hard-gated via Confirmation-Prompt + Audit-Log + Super-Admin-Permission. Doku enthält explizite Warnung dass das DSGVO-Verletzung sein kann wenn unverschlüsselt geteilt.
|
|
- **Salt-Speicherung:** Nur Salt-Hash im Manifest (für Reproduzierbarkeits-Check), nicht Salt selbst. Salt wird verworfen nach Snapshot-Erstellung — keine Reverse-Engineerable.
|
|
- **Snapshot-File-Distribution:** Snapshots sind selbst sensitiv (auch anonymisiert: Geschäftsdaten, Workflows). Encryption-by-Default (age) empfohlen. Doku weist darauf hin.
|
|
- **Restore-in-Production-Schutz:** `tenant:restore` checkt `process.env.NODE_ENV !== 'production'` ODER explizites `--allow-production-restore`-Flag (gefährliche Operation). Standard: Production-Restore failed mit klarer Error-Message.
|
|
- **Stripe-IDs:** Müssen ersetzt werden, sonst könnte ein Dev-Tenant-Restore versehentlich gegen die echte Stripe-API operieren. Im Mapping abgedeckt.
|
|
- **Webhook-URLs:** Wenn ein Tenant einen Custom-Webhook bei Drittsystem registriert hat (`https://customer-x.com/webhook`), und der Restore-Tenant feuert das ab → Drittsystem bekommt Test-Daten. Mapping ersetzt durch `anonymized.test`-URL → kein Outgoing.
|
|
|
|
## Subagent Recommendations
|
|
|
|
- **Planning:** `Plan`-Subagent mit Detail-MD; recherchiert ob `packages/cli/` schon existiert (aus `backup-cli.md`-Task) für Code-Reuse.
|
|
- **Research:** `Explore`-Subagent enumeriert vollständig alle Tenant-scoped Models aus Prisma-Schema und alle PII-Felder. Output → `models.ts` und `anonymizer.ts` Profile-Definition.
|
|
- **Implementation:** `general-purpose`-Subagent pro Step. Step 2 (Anonymizer) und Step 6 (Restorer) sind die kritischsten — eigene Subagents mit besonderer Sorgfalt.
|
|
- **Tests:** separater `general-purpose`-Subagent, Schwerpunkt auf Determinismus-Tests und FK-Sanity-Checks.
|
|
- **Verification:** `gsd-verifier`-Subagent + zusätzlich `gsd-security-reviewer` (falls existent) auf den Anonymizer für PII-Coverage.
|
|
- **Code-Review:** `gsd-code-reviewer` mit Fokus auf Daten-Leak-Pfade.
|
|
|
|
## Staging-Deployment-Steps
|
|
|
|
1. Branch `agent/03-tenant-snapshot` pushen.
|
|
2. Coolify-Auto-Deploy auf Staging.
|
|
3. Setup: Staging-Tenant mit realistischem Test-Dataset (mind. 100 Users, 500 Rows, 10 Workflows, 50 Storage-Files).
|
|
4. Smoke-Tests:
|
|
```bash
|
|
# Snapshot
|
|
ssh staging-host "docker compose run --rm cli toolctrl-cli tenant:snapshot \
|
|
<tenant-id> \
|
|
--target=/snapshots/tenant-acme-test.tar.gz \
|
|
--profile=full-anonymized \
|
|
--include-storage \
|
|
--encrypt=age"
|
|
|
|
# Download lokal
|
|
scp staging-host:/snapshots/tenant-acme-test.tar.gz ~/
|
|
|
|
# PII-Stichprobe
|
|
age -d -i ~/.age-key.txt ~/tenant-acme-test.tar.gz | tar -xzO prisma/data.jsonl | grep -E "@" | head
|
|
# → erwartet: nur @anonymized.test, keine echten Emails
|
|
|
|
# Restore in lokale Dev-DB
|
|
pnpm tsx packages/cli/bin/toolctrl-cli tenant:restore \
|
|
~/tenant-acme-test.tar.gz \
|
|
--target-tenant-slug=acme-restored \
|
|
--target-db=postgres://dev:dev@localhost:5432/devdb
|
|
```
|
|
5. Manueller Smoke-Test in lokaler Dev-UI: Login als restorierte User, Workflows ansehen, Subscription-State plausibel.
|
|
6. Permission-Test: ohne `SUPER_ADMIN_API_KEY` → Command failed mit klarer Message.
|
|
7. Audit-Eintrag in Source-DB prüfen.
|
|
|
|
## Deviations from Plan
|
|
|
|
- **No external faker dep.** Spec mentioned `@faker-js/faker`. Implementation uses a small curated word-pool seeded by `sha256(salt + value)` to keep the CLI free of an additional 500 KB dependency and to make every anonymizer output 100% deterministic. The mapping in the runbook lists every field-type and its strategy.
|
|
- **Audit log is file/stdout, not a Prisma write.** The CLI deliberately does not depend on `@prisma/client` (mirroring the backup-cli approach). The audit module emits a structured JSON line that operators redirect into their audit pipeline. Future work can replace this with a DB write when the CLI adopts a runtime Prisma adapter.
|
|
- **Prisma is dependency-injected.** Snapshot and restore expose a `PrismaRunner` / `PrismaRestoreRunner` interface; production consumers wire up the real client in `bin/toolctrl-cli.mjs`. This avoids a hard Prisma dep in the CLI package and makes unit tests trivial.
|
|
- **FK remapping is `tenantId`-only.** None of the tenant-scoped models reference other tenant-scoped rows by id in a way that would survive a snapshot — everything roots at `tenantId`. Row primary keys are kept as the source emitted them.
|
|
|
|
## Progress Log
|
|
|
|
- **2026-05-25 (Task G — globaler-Row-Extractor, schließt B7-Design-Limit):**
|
|
- Commit 1 (`e9fe18fc`) — `models.ts::GLOBAL_REFERENCED_MODELS` + `PLATFORM_CATALOG_GLOBALS` enumerieren jede `User`-Referenz aus tenant-scoped Models (38 FK-Spalten in 31 Source-Models) und kategorisieren die übrigen Schema-Globals (Entity/EntityGroup/Formula/Onboarding/PromptFlow/RowComment/WorkflowBlock) als deployment-baseline. `models.test.ts` parsed jedes `prisma/schema/*.prisma` und scheitert wenn eine neue FK-Relation eingebaut wird die in keiner der beiden Listen steht — verhindert stille Regressionen.
|
|
- Commit 2 (`6e0aafa3`) — `globals-runner.ts::collectAndWriteGlobals()`: streamed jede tenant-JSONL, sammelt FK-IDs pro Global, chunked `findManyByIds` (default 500), Anonymizer (gleicher Salt wie tenant-Slice), schreibt `globals/<Model>.jsonl`. Manifest-Schema um optionales `globals: TenantManifestGlobalsEntry[]` erweitert (backward-compat: alte Snapshots haben kein `globals` und werden weiter akzeptiert). `PrismaRunner` extends `Partial<GlobalsPrismaRunner>` mit `findManyByIds(model, ids)`; `createPrismaSnapshotRunner` implementiert es. CLI-Flag `--include-globals=true|false` (default true). Anonymizer-Coverage für `User`: email/firstName/lastName/phone/avatar scrubbed; passwordHash, verifyToken, githubId, googleId, totpSecretEncrypted, totpPendingSecretEncrypted, mfaRecoveryCodeHashes, deletionRequestId nullified. 6 globals-runner-Tests + 3 snapshot-Tests + 2 manifest-Tests + 4 anonymize-Tests.
|
|
- Commit 3 (`a4cdf6ef`) — Restore replayed globals VOR tenant-scoped slice. Drei Modi:
|
|
- `upsert` (default): findUnique + create-loop, idempotent, gibt `{created, updated}` zurück
|
|
- `skip`: createMany({skipDuplicates:true}), legacy-runner-kompatibel
|
|
- `error`: aborts wenn `updated > 0` (sensitiver Restore in known-empty DB)
|
|
`PrismaRestoreRunner.upsertManyById?` optional; legacy-fakes fallen automatisch auf `skip`-Semantik zurück mit warn. CLI-Flag `--globals=upsert|skip|error`. `RunRestoreResult.globals[]` mit per-model created/existed/expected counters. 5 restore-Tests + 4 prisma-runner-Tests.
|
|
- Commit 4 (`27cad89d`) — `round-trip.integration.test.ts` neuer dritter Case: seedet je 1 Row in den 6 zuvor-broken Models (TenantUser, TenantIpAddress, UserRole, Event, Log, SupportTicket) + 2 referenzierte User auf Source. Target hat den Target-Tenant aber KEINE referenzierten User (verified via `target.user.count() === 0` pre-check). Round-Trip führt Globals-Replay zuerst aus, dann tenant-scoped Models — alle 6 reportet `written === expected > 0`, jeder restored TenantUser-FK resolved gegen `target.user.findUnique`. **Live verifiziert** gegen zwei frische `pgvector/pgvector:pg16` Container (Ports 55801/55802) mit allen 138 Migrationen: **365/365 Tests grün**.
|
|
- Commit 5 (`<docs>`) — Runbook entschärft: `## Restore prerequisites: global rows are NOT in the snapshot` → `## How globals are handled in restore` mit 3-Modi-Tabelle, platform-catalog-Erklärung, Backward-Compat-Note, Anonymization-Block. Troubleshooting um 2 neue Symptome erweitert.
|
|
- **Coverage**: Nur `User` ist heute in `GLOBAL_REFERENCED_MODELS`. Andere FK-Targets (Entity/Formula/EntityGroup/Onboarding/PromptFlow/RowComment/WorkflowBlock) sind als platform-catalog markiert und bleiben deployment-baseline; per-tenant-Kopie wäre semantisch falsch. Der Test scheitert wenn jemand eine neue tenant-scoped FK in irgendeine andere globale Tabelle einbaut → forciert bewusste Entscheidung.
|
|
- **Live-Verifikation**: durchgeführt via `TENANT_TEST_DATABASE_URL` + `TENANT_TEST_TARGET_DATABASE_URL` gegen Docker-pgvector-DBs. Alle 365 Tests inkl. der 3 round-trip-Cases grün. Container nach Lauf gestoppt.
|
|
|
|
- **2026-05-17 (agent/03-tenant-snapshot):**
|
|
- Commit 1 — scaffolded `tenant` command group under `packages/cli` (registered in `src/index.ts`).
|
|
- Commit 2 — enumerated **54 tenant-scoped Prisma models** (`models.ts`); Vitest parses every `prisma/schema/*.prisma` to enforce coverage.
|
|
- Commit 3 — 3 anonymization profiles (`full-anonymized` / `minimal-anonymized` / `none`) plus deterministic salt-seeded engine (`anonymize.ts`); 21 unit tests cover all strategies + determinism + FK consistency.
|
|
- Commit 4 — zod manifest schema (`manifest.ts`); 10 tests.
|
|
- Commit 5 — `tenant:snapshot` (`runTenantSnapshot()` in `snapshot.ts`) — Prisma streaming + inline anonymization + storage object download + tar.gz + optional age/gpg encryption + multipart S3 upload. Reuses `backup/encryption.ts` and `backup/s3-upload.ts`. 9 tests with mocked Prisma + aws-sdk-client-mock.
|
|
- Commit 6 — `tenant:restore` (`runTenantRestore()` in `restore.ts`) — download/decrypt/untar/replay-with-new-tenantId/storage-reupload, NODE_ENV=production guardrail, `--yes` skip-prompt. 3 tests including full round-trip.
|
|
- Commit 7 — `tenant:list-snapshots` (`list-snapshots.ts`); 7 tests.
|
|
- Commit 8 — super-admin guardrail (`audit.ts`); hard-rejects `--profile=none` without `--i-am-the-super-admin`; emits structured `TENANT_SNAPSHOT_CREATED` audit record. 7 tests.
|
|
- Commit 9 — operator runbook (`docs/ops/tenant-snapshot.md`); 4 use cases, profile-selection table, DSGVO notes, restore drill, troubleshooting.
|
|
- Commit 10 — this entry + PROGRESS.md row #44 → `completed`.
|
|
- Final gates: `pnpm typecheck` ✅, `pnpm test src` ✅ (107 cli tests after commit 10), `pnpm lint --max-warnings=0` ✅ on the root.
|
|
- **Staging-Verifikation pending operator** per the `## Staging-Deployment-Steps` recipe (snapshot real tenant → restore in dev → smoke).
|
|
|
|
## Lessons Learned
|
|
|
|
(Optional am Task-Ende.)
|