Account Deletion System

TinyKit Pro includes a comprehensive and secure account deletion system with multiple safety checks, complete data cleanup, and a user-friendly "Danger Zone"...

TinyKit Pro includes a comprehensive and secure account deletion system with multiple safety checks, complete data cleanup, and a user-friendly "Danger Zone" interface that guides users through the deletion process while preventing accidental data loss.

Overview

The account deletion system is designed with security and data integrity as top priorities. It implements multiple validation layers, provides clear user guidance, and ensures complete cleanup of all user-related data across the entire system.

Key Features

🛡️ Security Safeguards

Admin Protection: Administrators cannot delete their accounts for security reasons
Organization Ownership Checks: Users must transfer or delete owned organizations before account deletion
Subscription Requirements: Active subscriptions must be cancelled via Stripe Customer Portal
Email Confirmation: Users must type their email address to confirm deletion intent
Comprehensive Validation: Multi-layer checks prevent accidental or unauthorized deletions

🗑️ Complete Data Cleanup

User Profile: Complete removal of profile, settings, and personal data
Authentication Data: Cleanup of all auth sessions, accounts, refresh tokens, verification codes, and verifiers
Organization Memberships: Removal from all organization memberships
Invitations: Deletion of all invitations sent TO the user (both org and user invitations)
Notifications: Removal of all user notifications and delivery tracking
Billing Records: Anonymization of payment records for tax/legal compliance
Profile Pictures: Deletion from Convex storage
Rate Limiting: Cleanup of authentication rate limit entries

🎨 Intuitive User Interface

Danger Zone Tab: Dedicated account settings tab for dangerous operations
Contextual Guidance: Different UI states based on blocking conditions
Clear Warnings: Detailed information about what will be deleted
Action Links: Direct links to resolve blocking conditions (org settings, billing portal)
Progressive Disclosure: Shows relevant information based on user's current state

Implementation Architecture

Three-Tier Deletion Process

Frontend Validation (DeleteAccountSection.tsx)
- Real-time status checks
- User guidance and warnings
- Email confirmation input
Backend Validation (deleteUser mutation)
- Permission and role verification
- Organization ownership checks
- Subscription status validation
Scheduled Cleanup (processUserDeletion internal function)
- Background data cleanup process
- Complete auth table cleanup
- Cross-table reference updates

Database Cleanup Strategy

// Auth & Session Cleanup
- authSessions (user sessions)
- authAccounts (OAuth connections)
- authRefreshTokens (JWT refresh tokens)
- authVerificationCodes (email verification)
- authVerifiers (OAuth verifiers)
- authRateLimits (login attempt tracking)

// Organization & Social Cleanup
- orgMembers (organization memberships)
- orgInvitations (invitations TO user by email)
- userInvitations (user platform invitations TO user)
- notifications (all user notifications)

// Content & Settings Cleanup
- mailingList (newsletter subscriptions)
- Profile pictures (Convex storage cleanup)

// Billing Compliance (Anonymization)
- payments (anonymize but retain for tax records)
- invoices (anonymize but retain for legal compliance)
- subscriptions (mark as cancelled)

User Flow Examples

Scenario 1: Admin Attempt

User: Admin
Status: ❌ Blocked
Message: "Account Deletion Blocked - Administrators cannot delete their account for security reasons."
Action: None available

Scenario 2: Organization Owner

User: Organization Owner
Status: ⚠️ Blocked
Message: "Organizations Owned - You must transfer ownership or delete these organizations first:"
Action: Links to organization settings with "?tab=advanced" parameter

Scenario 3: Active Subscription

User: Has active subscription
Status: ⚠️ Blocked
Message: "Active Subscription - You have an active Pro subscription. You must cancel your subscription before deleting your account."
Action: "Go to Billing & Cancel Subscription" link

Scenario 4: Scheduled Cancellation

User: Subscription ending soon
Status: ℹ️ Available
Message: "Subscription Ending - Your Pro subscription is scheduled to end on [date]. Account deletion is now available."
Action: Delete account dialog available

Scenario 5: Ready for Deletion

User: No blocking conditions
Status: ✅ Available
Action: Full delete account confirmation dialog

Technical Implementation

Frontend Query Optimization

The system uses Convex's conditional query pattern to prevent errors during the deletion flow:

const deletionStatus = useQuery(
  api.users.private.queries.getUserAccountDeletionStatus,
  currentUser ? {} : "skip",
);

This prevents "User not found" errors when the component tries to query deletion status after the user has been deleted and signed out.

Scheduled Background Processing

Large-scale data cleanup is handled via Convex's scheduled mutations to avoid timeout issues:

await ctx.scheduler.runAfter(
  0,
  internal.users.internal.scheduled.processUserDeletion,
  {
    userId,
    deletedBy: userId,
    deletedAt: Date.now(),
  },
);

Error Handling and Recovery

Validation Failures: Clear error messages guide users to resolve blocking conditions
Cleanup Failures: Comprehensive error logging and graceful degradation
UI State Management: Proper loading states and conditional rendering
Network Issues: Toast notifications and retry mechanisms

Requires authentication system to be enabled
Integrates with organization system when enableOrganizations is enabled in site settings
Works with any combination of enabled authentication providers

Security Considerations

Data Retention Compliance

Complete Deletion: All personal data is permanently removed
Legal Compliance: Billing records are anonymized but retained for tax/legal requirements
No Recovery: Deletion is truly permanent and cannot be undone

Protection Mechanisms

Admin Protection: Prevents deletion of critical system administrators
Email Verification: Requires exact email match to confirm intent
Multi-Layer Validation: Both frontend and backend validation prevents bypassing
Organization Safety: Prevents accidental deletion of organization owners
Subscription Safety: Ensures billing is properly handled before deletion

Development Patterns

Component Structure

/home/account/
├── page.tsx (Account settings with tabs)
└── _components/
    └── DeleteAccountSection.tsx (Danger Zone UI)

Backend Functions

convex/users/
├── private/
│   ├── mutations.ts (deleteUser validation)
│   └── queries.ts (getUserAccountDeletionStatus)
└── internal/
    └── scheduled.ts (processUserDeletion cleanup)

Testing Strategy

The account deletion system includes comprehensive testing coverage:

Permission Testing: Verify admin deletion is blocked
Organization Testing: Confirm ownership transfer requirements
Subscription Testing: Validate billing portal integration
UI Testing: Ensure proper state transitions and error handling
Data Integrity: Verify complete cleanup after deletion

Best Practices

For Developers

Always check deletion status before showing delete UI
Use scheduled functions for large cleanup operations
Implement proper error handling for all deletion steps
Test deletion flow thoroughly across different user states
Follow data retention policies for compliance requirements

For Users

Backup important data before initiating deletion
Transfer organization ownership to other members first
Cancel active subscriptions via billing portal
Understand deletion is permanent and cannot be undone
Contact support if experiencing issues with deletion process

Troubleshooting

Common Issues

"Account Deletion Blocked" for Admin

Solution: Super admins cannot delete accounts for security. Contact other admins to change role first.

"Organizations Owned" blocking deletion

Solution: Transfer ownership or delete organizations via organization settings "Advanced" tab.

"Active Subscription" preventing deletion

Solution: Cancel subscription via billing portal, wait for end of billing period.

"Email doesn't match" error

Solution: Ensure email address is typed exactly as registered, including case sensitivity.

Debug Information

Check browser console for detailed error messages
Verify user permissions and roles in admin panel
Review organization memberships and ownership
Confirm subscription status in billing section
Monitor Convex logs during deletion process

This account deletion system provides a secure, comprehensive, and user-friendly approach to permanent account removal while maintaining data integrity and legal compliance.