peterbamuhigire/skills-web-dev/saas-tenant-data-portability-and-erasure

SaaS Tenant Data Portability and Erasure

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Required Inputs

Skill-specific inputs:

• Tenant lifecycle states (saas-architecture-strategy).
• Map of every data store the SaaS uses (primary DBs, search, object storage, warehouse, CRM, ESP, analytics, third-party processors).
• Regulatory profile (GDPR? POPIA? Uganda DPPA? CCPA? sector-specific HIPAA?).
• Retention obligations (audit log 7 years; financial 10 years in most jurisdictions; backups 30 days).

Capability and permission contract

Default to read-only analysis. Change configuration, billing, identity, tenant data, infrastructure, or customer communications only with explicit authority, least-privilege credentials, tenant scope, rollback, and auditable approval. Never expose secrets or cross tenant boundaries.

Degraded mode

If production access, policy, telemetry, or authoritative records are unavailable, produce a labelled design or dry-run plan. Do not claim deployment, reconciliation, deletion, delivery, or measured outcomes; list missing evidence and verification.

Decision rules

Domain Anti-Patterns

• Applying one tenant's policy or data to another. Fix: enforce tenant scope at every boundary.
• Mutating production from an advisory request. Fix: remain read-only until authority is explicit.
• Inventing limits, prices, metrics, or compliance claims. Fix: use authoritative records or mark them unresolved.
• Shipping without rollback and audit evidence. Fix: stage and retain before/after proof.
• Treating a missing dependency as successful. Fix: name the blocked verification.

<!-- dual-compat-start -->

Use When

• Implementing the data-portability (export) and erasure (delete) workflows mandated by GDPR Article 20 / 17, POPIA, CCPA, Uganda DPPA, Kenya DPA.
• Designing the cascade that purges a tenant's data through every store the SaaS uses — primary DB, search index, file storage, warehouse, caches, backups, ESP suppression list, CRM, analytics, third-party processors.
• Handling user-level vs tenant-level erasure (a user leaving a tenant vs a tenant leaving the platform).
• Designing requester verification so an attacker can't erase a competitor's tenant.
• Designing the retention policy and the documented backup window (what survives erasure and for how long).

Do Not Use When

• The task is general data classification — use compliance audit work in vibe-security-skill / web-app-security-audit.
• The task is tenant lifecycle state machine — use saas-architecture-strategy.
• The task is region-specific compliance content — use dpia-generator for Ugandan specifics.

Workflow

1. Read this SKILL.md.
2. Inventory every data store (§2).
3. Map every store to user-level + tenant-level erasure capability (§3).
4. Design the export workflow (§4).
5. Design the erasure workflow (§5).
6. Design requester verification (§6) — protect against malicious erasure.
7. Document retention exceptions (§7) — what survives, why, for how long.
8. Wire into the back-office (§8).
9. Apply anti-patterns (§9).

Quality Standards

• Export delivered within 30 days (GDPR ceiling); aim for hours-to-days.
• Erasure cascades through every store; documented retention exceptions only.
• Backups handled honestly — document the retention window after which erased data is also purged from backups; don't claim instant deletion of backups when it's not true.
• Every export and erasure logged in the audit log with actor, target, verification trail.
• Requester verification appropriate to risk — primary-admin email confirmation + MFA for tenant-level erasure.

Anti-Patterns

• "Delete" implemented as SET deleted_at = NOW() (soft delete) — fails the regulatory test.
• Forgetting the warehouse — analytics data still contains PII years later.
• Forgetting the ESP suppression list — email still goes out to "deleted" addresses.
• Forgetting backups — claim "deleted" while the customer's PII sits in S3 for 90 days.
• One-click tenant erasure with no verification — competitor / disgruntled user destroys the tenant.
• No audit trail of the erasure itself — cannot prove compliance.

Outputs

• Data store inventory + erasure capability matrix.
• Export workflow + format spec.
• Erasure workflow + cascade order.
• Requester verification policy.
• Retention exceptions document.
• Customer-facing data-processing addendum (DPA) annex.

Evidence Produced

References

• references/erasure-cascade.md — the per-store cascade including backups + warehouse.
• references/export-format-spec.md — JSON-LD / CSV export package contents.
• references/requester-verification.md — verification strength per request type.
• Companion: saas-architecture-strategy, saas-admin-backoffice-tooling, multi-tenant-saas-architecture, dpia-generator, vibe-security-skill.

<!-- dual-compat-end -->

§1 The Two Request Types

A user-level request inside a tenant context (a tenant admin asks for a specific user's data) is a third variant: scope is one user within one tenant.

§2 Data Store Inventory

For every SaaS, enumerate stores:

Every store gets a column: "Per-user delete?" "Per-tenant delete?" "Retention window after request?"

§3 The Erasure Capability Matrix

Example:

§4 Export Workflow

Trigger: Customer initiates via in-product "Export my data" or tenant admin's "Export tenant data".

Steps:

1. Verify requester (§6).
2. Create export job (exports table; status queued).
3. Worker dumps data:

• Primary DB tables relevant to the user/tenant → CSV or JSON-Lines.
• Object storage files → keep folder structure.
• Settings / preferences → JSON.
• Audit log subset (the customer's own actions) → JSON.

1. Package as ZIP / TAR.GZ.
2. Upload to a private bucket; generate a signed URL with 7-day expiry.
3. Email the requester (to the verified email on file) with the link.
4. Update job status = ready; audit-log the event.

Format guidance:

• Use JSON-LD or plain JSON with schemas; CSV for tabular tables; manifest file at the root listing contents.
• Document field meanings in a README.md inside the bundle.
• Include a manifest of what is not included and why (retained for legal reasons, etc.).

Time: GDPR allows 30 days. Aim for hours-to-days; queue for big tenants.

§5 Erasure Workflow

Trigger: customer-initiated OR admin-initiated GDPR erasure request.

Pre-conditions:

• Outstanding obligations resolved (paid up, no pending refund, no legal hold).
• Final export offered to the customer (last chance to retrieve data).
• Cool-down window (e.g., 7 days) to prevent rage-deletion regret.

Cascade order (top to bottom; failures retried):

1. Mark tenant `pending_erasure` — no new data accepted; UI blocks; sessions invalidated.
2. External processors first (irreversible, slowest): Stripe Customer marked deleted (PII redacted, financial retained); Twilio/SendGrid/Customer.io contacts deleted; analytics vendor delete API.
3. Search indexes — delete-by-tenant.
4. Caches — flush per-tenant namespace.
5. Object storage — delete per-tenant prefix.
6. Primary OLTP — per-tenant DELETE cascade or schema drop.
7. Warehouse — DELETE / pseudonymise; rebuild materialised views.
8. Audit log — pseudonymise PII fields (email → hash); keep the records for regulatory retention; document this in the retention exceptions.
9. Backups — flag for redaction at the next rotation; do not delete the running backup retention window (operational risk).
10. Tenant record — status = deleted, deleted_at = NOW(), identifiers retained as opaque hashes only.
11. Audit log entry — TENANT_ERASURE_COMPLETED with the cascade outcome JSON.
12. Email requester confirming completion + summary of retention exceptions.

Failure handling:

• Each step is idempotent and retriable.
• Per-step status persisted (erasure_runs.step_status).
• On unrecoverable failure (e.g., Stripe API down), pause; alert ops; resume.

§6 Requester Verification