# Authentication, Billing, and Lifecycle

This document describes planned account, subscription, trial, retention, and deletion flows. It is planning-only and does not implement application code, Stripe configuration, or database migrations.

## Status labels

- **Approved foundation** — already established by the repository documentation.
- **Recommended direction** — the preferred approach, subject to product-owner approval.
- **Deferred decision** — intentionally decided later.
- **Open question** — requires product-owner input.

## Global users and organization memberships

- **Approved foundation** — Users are global accounts and may belong to multiple organizations through membership records.
- **Approved foundation** — A user may have a different organization role in each organization.
- **Approved foundation** — Authorization must always use trusted active-organization context and verify membership and permission server-side. Client-provided organization identifiers are not sufficient by themselves.
- **Recommended direction** — Switching organizations should establish a new trusted active-organization context only after the server confirms the authenticated user's membership in the target organization.

## Password signup and email-verification lifecycle

1. **Approved foundation** — Signup is submitted with an email address, password, and initial organization information.
2. **Approved foundation** — An unverified global user account or secure pending-registration record is created. Passwords must use secure one-way hashing and must never be reversibly encrypted.
3. **Approved foundation** — A time-limited, single-use email-verification token is generated and stored only as a hash.
4. **Approved foundation** — The verification email is sent.
5. **Approved foundation** — The user verifies control of the email address.
6. **Approved foundation** — The organization is created.
7. **Approved foundation** — The initiating user receives the organization-owner membership.
8. **Approved foundation** — The seven-day trial begins.

- **Approved foundation** — Organization creation, owner-membership creation, and trial activation must be idempotent. Retried verification requests, background jobs, or repeated user actions must not create duplicate organizations, memberships, or trial periods for the same signup intent.
- **Approved foundation** — The organization and trial must not become active before email ownership is verified, except when an appropriately validated external-identity flow provides a verified email claim.
- **Recommended direction** — Password resets use time-limited, single-use tokens stored only as hashes.
- **Recommended direction** — Password login uses secure sessions, login rate limiting, account lockout and recovery considerations, and logout from all devices.
- **Recommended direction** — MFA-ready architecture should support stronger authentication for owners, editors, and platform administrators.

## Google OAuth/OpenID Connect signup and linking

- **Approved foundation** — Google login uses OAuth/OpenID Connect with provider, issuer, audience, nonce, state, and other validation appropriate to the selected implementation.
- **Approved foundation** — A verified email claim from an appropriately validated provider may satisfy email verification for signup.
- **Approved foundation** — External identities must be linked only after verifying ownership and preventing account-linking conflicts.
- **Approved foundation** — Accounts must not be automatically merged based only on an untrusted or unverified email value.
- **Recommended direction** — When an external identity email matches an existing global account, the linking flow should require proof that the authenticated person controls both the existing account and the external identity.
- **Recommended direction** — OAuth callbacks should remain centralized where practical. Authentication on customer-owned domains requires the deferred handoff decision documented in [Architecture](ARCHITECTURE.md), [Deployment and scaling](DEPLOYMENT_AND_SCALING.md), [Data model](DATA_MODEL.md), and [Security and tenancy](SECURITY_AND_TENANCY.md).

## Organization and trial lifecycle

1. **Approved foundation** — A verified password-signup intent or appropriately validated external-identity signup is accepted for activation.
2. **Approved foundation** — The organization is created once, or the existing organization created for the same signup intent is reused.
3. **Approved foundation** — The initiating user receives the organization-owner membership once.
4. **Approved foundation** — The seven-day trial is activated once.
5. **Recommended direction** — Trial-ending reminders are sent by idempotent scheduled jobs.
6. **Recommended direction** — Trial expires without payment.
7. **Recommended direction** — Workspace is suspended or made read-only, depending on product-owner policy.
8. **Recommended direction** — Thirty-day post-trial retention period begins only after the seven-day trial expires.
9. **Recommended direction** — Subscription during retention reactivates the workspace.
10. **Recommended direction** — Final deletion warning is sent before deletion.
11. **Recommended direction** — Automated production-data deletion removes eligible active customer data after retention and after holds/extensions are cleared.
12. **Recommended direction** — Deleted data ages out of encrypted backups according to the backup-retention policy; active data deletion and backup expiration are separate processes.
13. **Recommended direction** — A minimal deletion audit receipt is retained without unnecessary customer content.

## Stripe billing lifecycle

- **Recommended direction** — Stripe Checkout starts subscription purchase or reactivation through a Stripe-hosted page.
- **Recommended direction** — The Stripe customer billing portal handles payment method updates, plan changes where allowed, and customer-managed billing actions.
- **Recommended direction** — Subscription records store Stripe customer identifiers, subscription identifiers, price identifiers, and non-secret subscription state.
- **Recommended direction** — UAT uses Stripe test mode and production uses Stripe live mode; modes, webhook secrets, customers, and subscriptions must never be shared.
- **Recommended direction** — Signed webhook verification is required before processing Stripe events.
- **Recommended direction** — Webhook-event storage or deduplication must make processing idempotent and safe for retries.
- **Recommended direction** — Successful payments activate or continue service and clear relevant grace or suspension states.
- **Recommended direction** — Failed payments can start a grace period, trigger notices, and eventually suspend or make the workspace read-only according to product-owner policy.
- **Recommended direction** — Subscription plan changes update entitlement state only after verified Stripe confirmation.
- **Recommended direction** — Cancellations move the organization to a canceled or ending state based on the paid-through period and configured grace rules.
- **Recommended direction** — Reactivation during retention should restore access when payment succeeds and no legal/support hold prevents reactivation.
- **Recommended direction** — Full card numbers and CVV information must never be stored by Cloutal Workspace.

## Failure handling expectations

- **Recommended direction** — Scheduled jobs and webhook handlers must be idempotent and safe to retry.
- **Recommended direction** — Billing webhooks should store processing state so duplicate delivery does not duplicate payments, state changes, emails, or audit events.
- **Recommended direction** — Trial reminders, deletion warnings, retention transitions, exports, email jobs, billing events, and maintenance jobs should retry safely and alert after repeated failure.
- **Recommended direction** — Administrative retention holds, administrative extensions, and legal or support holds can pause deletion when justified and audited.
- **Recommended direction** — Automation can retry and alert, but security incidents, unusual failures, restoration decisions, and customer disputes may require human intervention.

## Open questions

- **Open question** — Are payment details required before a trial starts?
- **Open question** — Should expired or failed-payment workspaces be suspended, read-only, or both in sequence?
- **Open question** — What exact plans, prices, billing intervals, grace periods, and cancellation policies are required?