---
kind: epic
slug: tenant-lifecycle
title: Tenant lifecycle — invites, roles, soft-delete, audit, rate-limits
plan_slug: multitenant-saas-hardening
status: ready
priority: P1
tenant_id: global
cursor_epic_id: null
updated_at: "2026-06-02"
---

# Epic objective

Cover the operational edges of running a multitenant app: who's in the workspace, what they did, can we recover from a mistake, and can we cap abuse.

## In scope / out of scope

**In scope**

- **Multi-email identity** on user profile (foundation — one user can own multiple verified emails).
- Invite + role management (`workspace_members` already exists; add invite flow on top).
- Smart invite-recipient autocomplete (members / pending / known users / new email).
- Append-only `audit_log` table with write hooks.
- Soft-delete on workspaces and core tenant-scoped tables.
- Rate-limiting middleware on auth + mutation routes.

**Out of scope**

- SSO group sync (later).
- Per-tenant billing (separate plan).

## Related tasks

| Task | Link |
|------|------|
| Multi-email identity on user profile | `./Task-multi-email-identity.md` |
| Workspace invites and roles | `./Task-workspace-invites-and-roles.md` |
| Invite recipient autocomplete | `./Task-invite-recipient-autocomplete.md` |
| Workspace soft-delete and audit | `./Task-workspace-soft-delete-and-audit.md` |
| Rate limit and abuse guardrails | `./Task-rate-limit-and-abuse-guardrails.md` |

### Follow-ups (filed, not in this convoy)

| Task | Link | Why deferred |
|------|------|--------------|
| Manual email verification | `./Task-manual-email-verification.md` | Add an email outside an OAuth provider; needs verification token + send + entry UI. |
| Disconnect linked email | `./Task-disconnect-linked-email.md` | Has destructive edge cases (last verified email, primary swap). |
| Account merge | `./Task-account-merge.md` | Merge two existing users who turn out to share an email — security-sensitive, not v1. |

## Dependencies

- Depends on: `Plan-daily-driver-finish` (don't harden surfaces that are still stubs).
- Blocks: charging real money, onboarding non-trusted tenants.

## Acceptance criteria

- [ ] An owner can invite an email; the recipient lands in the workspace after sign-in.
- [ ] Every tenant-scoped mutation produces an `audit_log` row.
- [ ] An archived workspace stops serving its data through tRPC but is restorable for at least 30 days.
- [ ] Credentials sign-in is rate-limited at the route handler level.

## Proposed timeline

| Phase | Window | Notes |
|-------|--------|-------|
| Identity foundation | Week 1 (first half) | `Task-multi-email-identity` lands before any invite work touches the sign-in path. |
| Invites | Week 1 (second half) | `Task-workspace-invites-and-roles` end-to-end with copy-paste URL. |
| Invite polish | Week 2 (first half) | `Task-invite-recipient-autocomplete`. Can parallelize with audit/soft-delete. |
| Audit + soft-delete | Week 2 (second half) | Schema + middleware. |
| Guardrails | Week 3 | Rate limits + abuse signals. |