PSA/ee/docs/plans/2026-06-01-tenant-reactivation-winback/PRD.md

# PRD: Tenant Reactivation / Win-Back

- **Status:** Draft (for review)
- **Owner:** Natallia Bukhtsik
- **Created:** 2026-06-01
- **Repos:** `alga-psa` (app/auth/billing/temporal) + `nm-store` (order/checkout site)
- **Related:** 2026-06-01 duplicate-tenant idempotency fix (reactivation must reuse its
  "one tenant per customer" guarantee — see §9)

## 1. Problem statement & user value

When a customer cancels their subscription, their tenant is **not deleted immediately**.
The `tenantDeletionWorkflow` deactivates users and schedules deletion up to **90 days** out,
keeping all data intact and the workflow alive and reversible (it already has a
`rollbackDeletion` signal). Today we do nothing with that window:

- A cancelled user who tries to **log back in** just gets "invalid credentials" — no nudge,
  no path back, and we don't even know they tried.
- A cancelled user who returns to the **order page** to sign up again is hard-blocked with
  "A tenant already exists for this email," with no way forward — and if they somehow push
  through, they'd get a brand-new empty tenant instead of their real one.

This effort turns that 90-day reversible window into a **win-back funnel**: detect returning
cancelled customers and route them to *reactivate their existing tenant* (with all their data)
via a paid re-subscribe, rather than losing them or duplicating their account.

## 2. Goals

- Detect that an email/tenant is **mid-deletion and still reactivatable** (within the window,
  before `status='deleting'`).
- **Reactivation funnel:** paid new subscription at **full price (no first-month/intro
  discount, no trial)** → `rollbackDeletion` (reactivate users + data) → link the new
  subscription to the **existing** tenant → password reset so they can log in.
- **Checkout interception (nm-store):** when a returning cancelled customer enters their email
  on the order form, divert from normal checkout to the reactivation funnel (start by emailing
  them a reactivation link).
- **Login win-back (alga, email-only):** when a *login attempt* (password NOT verified — see §8)
  hits an inactive + mid-deletion account, silently send a throttled "come back" email; keep the
  generic invalid-credentials response unchanged.
- **No duplicate tenants:** reactivation reattaches to the existing tenant and never runs the
  new-tenant provisioning path.

## 3. Non-goals

- **No data restore after the point of no return.** Once `status` is `deleting`/`deleted`,
  reactivation is refused and the user is treated as a brand-new signup. Restoring from the S3
  export is explicitly out of scope.
- **No change to who/when triggers deletion** (Stripe/IAP/manual triggers are untouched).
- **No distinguishable login screen / new login error state** (decision: email-only).
- **No free reactivation / win-back coupon** (decision: full price, no intro discount).
- No new monitoring/dashboards/analytics beyond what the flows need to function.
- **No reactivation for Apple IAP tenants** (decided) — they have no Stripe subscription to
  re-create, so there is no path back; IAP cancellations proceed to deletion as today.
- **No _auto_-refund machinery** (decided) — but the refuse path is NOT silent: if a payment was
  captured and reactivation is then refused (status crossed to `deleting` in the
  checkout→completion gap, which can be minutes — e.g. an `immediate` confirm or the 90-day
  auto-delete landing in that gap; not "negligible"), we **fire an ops alert flagging the payment
  for manual refund** (§10, F034). Manual refund, but visible — not an invisible financial liability.

## 4. Personas & primary flows

**Persona — Returning cancelled admin** (their tenant is mid-deletion, within 90 days).

**Flow A — Returns to the order page (nm-store):**
1. Enters email on the order form.
2. `check-tenant` reports `pendingDeletion: true, reactivatable: true`.
3. Order form does NOT proceed to normal checkout. Shows "Welcome back — we found your
   account" and triggers a reactivation email to the tenant's admin email.
4. Email → reactivation checkout (full price, no intro coupon/trial), metadata marks it a
   reactivation for `tenantId`.
5. On payment success: `rollbackDeletion` signal reactivates the tenant + users (data intact),
   the new subscription is linked to the existing tenant, and a **force password-reset**
   (set-password) email is sent — which also verifies the admin's email ownership after a
   payment that did not otherwise prove identity.
6. User sets a new password and logs into their restored tenant.

**Flow B — Tries to log in (alga):**
1. Submits any credentials to an account that is `is_inactive` and mid-deletion.
2. Auth returns the generic invalid-credentials response (no UX change) — **the password is NOT
   verified** (the `is_inactive` gate short-circuits before `verifyPassword`; see §8).
3. Behind the scenes, a throttled win-back email is sent: "We noticed a sign-in attempt — your
   account is scheduled for deletion on `<date>`. Reactivate now" → links into the same
   reactivation funnel (Flow A, steps 4–6). Intent is confirmed downstream by **payment**, not by
   the login attempt; the email is just an invitation.

**Persona — Past-the-window customer:** `status='deleting'`/`deleted` → not reactivatable →
checkout proceeds as a normal new signup; login win-back email is not sent.

## 5. Scope

### In scope
- Mid-deletion detection helper + `check-tenant` response extension (alga).
- HMAC service-to-service "request reactivation email" endpoint (alga) callable by nm-store.
- Extend the Temporal deletion workflow's `rollbackDeletion` signal + rollback handler to perform
  reactivation (subscription→existing-tenant link + password-reset) via new activities, plus a
  thin server trigger that fires the enriched signal on reactivation-checkout success.
- Reactivation checkout (nm-store): no intro coupon, no trial, reactivation metadata.
- Order-form divert (nm-store).
- Login win-back email trigger + throttle (alga auth path).
- Two email templates: reactivation invite + login win-back.

### Reactivation eligibility
Reactivatable iff an active `pending_tenant_deletions` row exists with
`status NOT IN ('deleting','deleted','rolled_back','failed')` (i.e. `pending`,
`awaiting_confirmation`, or `confirmed` but not yet executing).

**Confirmed deletions are reactivatable** (verified against
`tenant-deletion-workflow.ts:347-367`): after a `confirmDeletion` signal the workflow sets status
`confirmed` and waits `deletionDelay` (30 or 90 days) while **still listening for the rollback
signal**, so rollback succeeds throughout that window. The window simply shrinks to the confirmed
delay; status flips to `deleting` (point of no return) only when the delay elapses with no
rollback. Edge: an **`immediate`** confirmation has `deletionDelay = 0`, so the wait is skipped and
`confirmed → deleting` happens back-to-back — effectively **no reactivation window**.

The reactivation/win-back emails must display the **effective** deletion date =
`COALESCE(deletion_scheduled_for, scheduled_deletion_date)`. There are TWO columns (verified in
migration `20260113120000` + `updateDeletionStatus`): `scheduled_deletion_date` is the auto-delete
deadline (`canceled_at + 90d`, NOT NULL, never updated); on confirmation the actual date is written
to a **separate** column `deletion_scheduled_for` (e.g. `now + 30d`), NULL until confirmed.
`updateDeletionStatus` does NOT touch `scheduled_deletion_date`.

## 6. UX / UI notes

- **Order form:** replace the dead-end "A tenant already exists for this email." with a
  reactivation branch only when `reactivatable`. If `exists` but NOT reactivatable (active,
  healthy tenant), keep the existing block. If past the window, allow normal signup.
- **Reactivation email:** clear "Welcome back", what reactivation does (restores data,
  requires re-subscribe at standard price), scheduled deletion date, single CTA → reactivation
  checkout. From `info@nineminds.com`.
- **Win-back email:** "We noticed a sign-in attempt", scheduled deletion date, reactivate CTA.
  Throttled to at most once per 14 days per tenant.
- **Reactivation checkout success page:** "Your account is being restored — check your email to
  set a new password." (Mirrors the thank-you page but for reactivation.)

## 7. Data model / API integration notes

- **Detection:** `pending_tenant_deletions` (one row per tenant via `unique(['tenant'])`).
  Read `status`, `workflow_id`, `subscription_external_id`, and both date columns
  (`scheduled_deletion_date` = 90d auto deadline, `deletion_scheduled_for` = confirmed date, NULL
  until confirmed). `reactivatable` = status ∈ {`pending`,`awaiting_confirmation`,`confirmed`}.
- **Edition placement (F042):** `pending_tenant_deletions` is an **EE-only** table (created only by
  `ee/server/migrations/20260113120000`). Every reader must therefore live in EE. The HMAC endpoints
  below (and the F035 password-reset endpoint) move to `ee/server/src/app/api/...` (mirroring the
  existing EE-only routes `internal/`, `provisioning/`, `v1/tenant-management/`), keeping the same URL
  paths nm-store signs against. Any pending-deletion read reachable in CE must fail-soft (table absent
  ⇒ "no pending deletion"), never throw.
- **`GET /api/billing/check-tenant`** (alga, HMAC; relocate to EE per F042): extend response with
  `pendingDeletion: boolean`, `reactivatable: boolean`, `deletionStatus?: string`, and
  `effectiveDeletionDate?: string` (= `COALESCE(deletion_scheduled_for, scheduled_deletion_date)`).
  Backward compatible (additive fields).
- **`POST /api/billing/request-reactivation`** (new, alga, HMAC same scheme; in EE per F042): body
  `{ email }`; looks up active pending deletion → sends reactivation email to tenant admin.
  Anti-enumeration: return 200 regardless; only email if reactivatable.
- **Reactivation checkout** (nm-store): Stripe Checkout for the plan's standard recurring price,
  `discounts` omitted (no `introCouponId`), no `trial_period_days`; `metadata` includes
  `reactivation: "true"`, `tenant_id`, `deletion_workflow_id`. **Created with the tenant's EXISTING
  Stripe customer** (`customer: cus_…`) — Stripe retains the customer after
  `customer.subscription.deleted`, so the new subscription attaches to the same customer rather than
  spawning a divergent one. nm-store does NOT set `customer` today (verified: `utils/stripe.ts` passes
  none → Stripe auto-creates one); it obtains the `cus_…` via F044 — a **non-PII** Stripe id returned
  by alga's token-exchange (the prior `subscription_external_id` and/or `cus_…`), or derived from
  Stripe with nm-store's own `STRIPE_SECRET_KEY`. The admin **email** is never sent to nm-store (F038).
- **Stripe customer reconciliation:** the existing tenant already has a `stripe_customers` row from
  the original subscription. Reactivation **reuses** it (F037 checkout + F019 link) — it must NOT
  create a second/divergent customer row, since the billing portal and future subscription webhooks
  key off the customer. Only a new `stripe_subscriptions` row is inserted.
- **Charged-but-refused ledger:** `pending_reactivation_refunds` table (F036) backs F034 — durable
  work queue of payments captured but not reactivated, for manual refund + an ops-inbox email.
- **Reactivation token ledger:** `tenant_reactivation_tokens` table (F040) backs F039 — durable
  single-use state for email links. Store `token_hash`, `tenant`, `deletion_id`, `expires_at`,
  `reserved_at`, `consumed_at`, `checkout_session_id`, and timestamps. The checkout route validates
  the signed token against this row and atomically reserves it before creating Stripe Checkout, so a
  replay cannot mint multiple sessions; completion consumes it on successful reactivation.
- **Stripe webhook branching:** `checkout.session.completed` handling must branch on
  `session.metadata.reactivation === "true"` **before** the normal subscription import/update path.
  Reactivation sessions run only the reactivation trigger/guard path (F041/F016); normal sessions
  continue through existing checkout handling. This prevents the webhook from importing the new
  subscription before the Temporal rollback handler owns the reactivation flow.
- **Reactivation completion** runs **inside the Temporal deletion workflow's rollback handler**
  (not a server orchestrator). The `rollbackDeletion` signal payload is extended with an optional
  `reactivation` block `{ stripeCustomerId, stripeSubscriptionId, stripeSubscriptionItemId,
  stripePriceId, sendPasswordReset }`. On checkout success a thin server trigger fires this
  enriched signal; the (already durable, retried) rollback handler then, in order:
  1. Reactivates users (`is_inactive=false`), removes Canceled tag, reactivates master client
     and contacts in the master tenant (existing rollback behavior).
  2. If a `reactivation` block is present: links the new Stripe subscription to the **existing**
     tenant by **reusing `createTenantInDB`'s exact stripe_customers/stripe_subscriptions insert
     path** (shared helper) so Citus shard routing is identical (`tenant` set explicitly), **without
     creating a tenant**, and stamps `subscription.metadata.tenant_id`. **Idempotency is keyed on
     the tenant, not the sub id:** if the tenant already has an active linked subscription, do not
     insert a second (two genuine payments → two distinct `sub_…` ids); the duplicate routes to the
     charged-but-refused/duplicate-payment alert (§10, F034).
  3. If `sendPasswordReset` (default for reactivation): force a **password-reset (set-password)**
     email — necessarily **after** step 1 (`requestPasswordReset` skips `is_inactive` users). The
     worker does **not** mint the link itself (it lacks `NEXT_PUBLIC_BASE_URL`/`NEXTAUTH_URL` and
     uses a different sender); it calls an **app-side HMAC endpoint** (F035) that runs the existing
     `requestPasswordReset` in app context (correct `baseUrl` + branded auth email). This also
     verifies email ownership after a payment that didn't prove identity. (Alternative if chosen:
     keep-old-password — omit `sendPasswordReset`; preserved hash lets the owner log in.)
  - The trigger must handle a **closed workflow**: once status is `rolled_back` the deletion
    workflow has returned, so signaling it throws — detect and route to the duplicate-payment alert
    instead of signaling.
  - The **admin** rollback endpoint passes **no** `reactivation` block → unchanged behavior
    (back-compat).
- **Win-back throttle:** add `last_winback_email_at timestamptz` to `pending_tenant_deletions`.

## 8. Login win-back integration

**Important (corrected):** `authenticateUser` (`packages/auth/src/actions/auth.tsx`) returns
`null` at the `is_inactive` gate (`:87`) **before** `verifyPassword` (`:97`). So the password is
NOT verified for inactive users, and the win-back hook **cannot and does not** confirm identity at
login. We do not attempt to authenticate the user — intent is confirmed downstream by **payment**.

Behavior: at the `is_inactive` gate, if an active `pending_tenant_deletions` row exists for
`user.tenant`, fire the throttled win-back email (respecting `last_winback_email_at`, ≤ once / 14
days per tenant) as a fire-and-forget side effect, then `return null` exactly as today. We do NOT
reorder the gate, do NOT call `verifyPassword`, and make no other behavior change for active users
or non-deletion inactive users. The email is sent on the login *attempt* regardless of password
correctness; it is merely an invitation to the (paid) reactivation funnel.

**Consequence — abuse surface:** because there is no password check, anyone who submits a known
mid-deletion email triggers (at most one per 14 days per tenant) a "your account is scheduled for
deletion — reactivate" email to the tenant admin. This is a mild spam/enumeration vector, bounded
by the per-tenant 14-day throttle, and the email contains no information the owner doesn't already
know. The 14-day throttle therefore exists for **anti-spam**, not as an intent signal (the login
attempt is an unverified signal; real intent = payment).

**Recipient:** detection keys on `user.tenant`, but the email is sent to the tenant's
**billing/admin email** (the party who can re-subscribe), not necessarily the user who attempted —
so a non-admin internal user's attempt emails the admin. The throttle is intentionally per-tenant,
so one user's attempt can consume the window for another's. This is by design (the admin owns
billing); just noted explicitly.

## 9. Idempotency / duplicate-tenant guard (critical)

Reactivation creates a **new** Stripe subscription (`sub_…`) for an **existing** tenant. It must
NOT go through the nm-store provisioning entry — `ensureOrderInstallWorkflowForCheckoutSession`
(`orderInstallFromCheckoutSession.ts`) → `startOrderInstallWorkflow` (`orderInstallTrigger.ts`) →
the tenant-creation workflow — because that path provisions a *new* tenant. The new subscription id
has no `tenant_id` metadata, so neither the metadata pre-check (Layer 3) nor the DB guard (Layer 2)
from the duplicate-tenant fix would stop it. Reactivation is a distinct, explicit "attach to
existing tenant" path; the reactivation checkout metadata (`reactivation:"true"`, `tenant_id`) is
the discriminator that keeps it off the provisioning path. (Related real symbols in that module:
`buildOrderInstallWorkflowInputFromCheckoutSession`, `isCheckoutSessionReadyForProvisioning`,
`buildOrderInstallWorkflowId`.)

## 10. Risks, rollout, open questions

**Risks**
- **Point-of-no-return race (with money on the line):** the checkout→completion gap can be
  minutes; if `status` flips to `deleting` in it, Stripe has already captured payment. Re-check
  status at the trigger; if refused after capture → surface "too late, sign up fresh" to the user
  AND fire the F034 ops alert flagging the payment for manual refund. (No auto-refund — see §3.)
- **Double payment / duplicate linking:** two genuine payments produce two distinct `sub_…` ids; a
  sub-id-keyed guard would link both → double billing. Idempotency is keyed on "tenant already has
  an active linked subscription" (F022); the second payment is refused-and-alerted (F034). The
  trigger must also not signal an already-closed (`rolled_back`) workflow (F016).
- **Email correctness ordering:** password reset before rollback would silently no-op
  (`is_inactive` filter). Enforce ordering (test).
- **Double trigger:** repeated reactivation-email requests or checkout reloads — make the
  email idempotent (throttle) and the completion idempotent (rollback is safe to call once;
  guard re-entry by checking status).
- **workflowClient.ts duplication** (`ee/server` + `packages/ee`) must stay in sync.

**Rollout**
- Additive endpoints + additive `check-tenant` fields → safe to deploy alga first; nm-store
  divert is gated on the new fields.
- Migration: add `last_winback_email_at` to `pending_tenant_deletions` (nullable).

**Resolved decisions (2026-06-01)**
1. **IAP-only tenants:** not supported — no path back (see §3).
2. **Refund/abort on the point-of-no-return race:** no refund machinery; refuse + message (see §3).
3. **Reactivation orchestration:** lives **inside the Temporal deletion workflow's rollback
   handler** via an enriched `rollbackDeletion` signal — NOT a server-side orchestrator (see §7).
4. **Win-back throttle:** at most **once per 14 days** per tenant. (Corrected rationale: the login
   attempt is NOT identity-verified — the password is never checked at the gate — so the throttle
   is an **anti-spam/anti-enumeration** cap, not an intent signal. Real intent = payment. See §8.)
5. **Login win-back does NOT verify the password** (decided): the `is_inactive` gate short-circuits
   before `verifyPassword`; we just send the reactivate invite on the attempt and confirm intent via
   payment downstream. No reordering of the auth flow.
6. **Reactivation password handling: force password-reset** (set-password email) by default — also
   verifies email ownership after a payment that didn't prove identity. Keep-old-password is a
   documented, lower-friction alternative (the hash is preserved through deactivation).

**Open questions:** none — plan is review-complete.

## 11. Acceptance criteria / definition of done

- A mid-deletion, in-window email entered on the order form does NOT start a normal checkout;
  it triggers a reactivation email to the tenant admin.
- Completing the reactivation checkout (a) reactivates the existing tenant and its users with
  all prior data intact, (b) links the new subscription to the existing tenant with NO new
  tenant created, (c) applies NO first-month/intro discount or trial, and (d) sends a
  password-reset email; the user can set a password and log into their restored tenant.
- A login attempt (password NOT verified) to an inactive, in-window account sends one win-back
  email (subject to the per-tenant throttle, to the tenant's billing/admin email) and still returns
  the generic invalid-credentials response.
- An out-of-window (`deleting`/`deleted`) email is treated as a normal new signup; no
  reactivation email and no win-back email are sent.
- No code path in the funnel creates a duplicate tenant (regression-tested against the
  idempotency guards).
- The reactivation email is sent only to the tenant's billing/admin email; a non-admin login
  attempt or order-form email entry never receives the link, and nm-store never sees the admin
  address. The reactivation checkout cannot be created without a valid, single-use reactivation
  token.

## 12. Authorization model — who may reactivate

Reactivation spends money on the org's behalf, so it must be gated on **authority**, not just
payment. The authority anchor is **control of the tenant's billing/admin email** — the same anchor
Stripe (billing contact) and our password-reset flow already rely on. We cannot gate via login/RBAC
because all users are deactivated (`is_inactive`) during the deletion window.

- **Recipient (F038):** the reactivation/win-back email goes ONLY to the tenant's billing/admin
  email (the original owner/`adminEmail` / Stripe customer email), resolved server-side. **Never**
  to the attempter (a non-admin's login attempt nudges the admin, not themselves) and never to the
  arbitrary email typed on the order form. nm-store never receives the admin address (anti-enumeration).
- **Token (F039):** the email link carries a signed, single-use, expiring token bound to
  `tenant_id`. The reactivation checkout cannot be created without a valid token (validated
  server-side against the durable token ledger); it is atomically reserved before Checkout creation
  and consumed on success (replay rejected before or after payment). So only someone with access to
  the admin inbox can *initiate* reactivation — payment alone cannot.
- **Access (F021):** after payment, the force password-reset link also goes to the admin inbox — so
  even completing payment grants no access without inbox control.

Authority chain: **admin-inbox control → token → checkout → payment → password-reset (same inbox) →
access.** Threat notes: a random payer without the token cannot initiate (no griefing/data
resurrection of arbitrary tenants, no enumeration). An attacker who controls the admin inbox is
already effectively the admin (could reset any password regardless), so email-ownership is an
acceptable and consistent anchor. Finer-grained billing RBAC is a possible future refinement but is
out of scope for v1 (a single billing/admin email is the authority).

## 13. Review-5 (2026-06-05) — edition placement, Stripe-customer resolution, residual findings

A fifth pass after verifying the claims against both repos. The first three items were already folded
into §5/§7; the rest are new (F042–F048). All file/line claims below are code-verified.

- **Edition placement — `pending_tenant_deletions` is EE-only (F042).** It is created only by
  `ee/server/migrations/20260113120000_create_pending_tenant_deletions.cjs` (exact table name
  `pending_tenant_deletions`). check-tenant currently lives in **CE** (`server/src/app/api/billing/`)
  and the login path is **shared** (`packages/auth`); reading the table from there throws where it
  doesn't exist. Resolution: move the HMAC endpoints (check-tenant, request-reactivation F006,
  reactivation-password-reset F035) into `ee/server/src/app/api/...` at the same URL paths, and make
  any CE-reachable read fail-soft. EE routes resolve via aliases (`scripts/build-enterprise.sh`).
- **Login win-back via the EE injection pattern (F043).** Don't inline an EE-table query in shared
  `auth.tsx`. Reuse the existing `@enterprise/*` dynamic-import + `isEnterprise` pattern
  (`loadEnterpriseSsoProviderRegistryImpl` / `enterpriseSsoRegistryInitPromise` in `nextAuthOptions.ts`,
  CE-stub fallback). The shared gate (`auth.tsx:87`) invokes a hook that is a no-op in CE.
- **nm-store resolves `cus_…` from Stripe, not alga's DB (F044) — confirms the "it comes from Stripe"
  intuition.** nm-store passes no `customer` today (`utils/stripe.ts`) and holds `STRIPE_SECRET_KEY`.
  alga's token-exchange returns a **non-PII** Stripe id (prior `subscription_external_id` / `cus_…`);
  nm-store sets `customer: cus_…` or derives it via `subscriptions.retrieve(sub_…).customer`. The admin
  email never crosses the boundary — F038 holds. F037 updated to stop shipping alga's DB row.
- **Reactivated-but-unbilled partial failure (F045).** `handleRollback` flips status to `rolled_back`
  and reactivates users before linking the subscription. A permanent link failure after a captured
  payment leaves a live tenant with no subscription — a gap not covered by F034's prior reasons. Raise
  F034 with a distinct `reactivated_unbilled` reason on exhausted retries.
- **F019 is a refactor, not a literal reuse (F046).** In `tenant-operations.ts` the customer and
  subscription inserts are coupled (sub FK uses the just-inserted internal customer; rows carry
  `billing_tenant = MASTER_TENANT_ID`). Extract a shared helper taking an existing internal
  `stripe_customer_id` that inserts only the sub row (preserving `tenant` + `billing_tenant`).
- **Throttle atomicity (F047)** — conditional `UPDATE … WHERE last_winback_email_at IS NULL OR <
  now()-14d RETURNING`, email only on a returned row (read-check-update double-sends under concurrency).
- **Admin-email source of truth (F048)** — the authority model hinges on this; pin the canonical field
  + fallback order behind one resolver shared by F008 and F025.

**Status:** review-complete pending implementation; no open questions.