feat: use soft delete by default

Author: rrd108

docs/user-guide/configuration.md

@@ -77,7 +77,10 @@ export default defineNuxtConfig({
       requireNumbers: true,
       requireSpecialChars: true,
       preventCommonPasswords: true
-    }
+    },
+    
+    // User deletion behavior
+    hardDelete: false // true = permanent deletion, false = soft delete (default)
   }
 })
 ```
@@ -341,6 +344,88 @@ nuxtUsers: {
 | `requireSpecialChars` | Require special characters (!@#$%^&*) | `true` |
 | `preventCommonPasswords` | Block common weak passwords | `true` |
 
+## User Deletion Behavior
+
+The module supports two types of user deletion: **soft delete** (default) and **hard delete**.
+
+### Soft Delete (Default - Recommended)
+
+By default, when a user is "deleted", they are actually **soft deleted**:
+
+```ts
+nuxtUsers: {
+  hardDelete: false // Default behavior
+}
+```
+
+**What happens during soft delete:**
+- User's `active` field is set to `false`
+- User record remains in the database
+- All user tokens are revoked (user is logged out)
+- User cannot log in anymore
+- User data is preserved for compliance/audit purposes
+
+**Benefits of soft delete:**
+- **Data preservation** - Important for compliance and audit trails
+- **Reversible** - Can reactivate users by setting `active: true`
+- **Reference integrity** - Foreign keys to user records remain valid
+- **Analytics** - Historical data remains available
+
+### Hard Delete (Permanent)
+
+For applications that require permanent user removal:
+
+```ts
+nuxtUsers: {
+  hardDelete: true // Enable permanent deletion
+}
+```
+
+**What happens during hard delete:**
+- All user tokens are revoked first
+- User record is permanently removed from database
+- Action cannot be undone
+- Any foreign key references will break
+
+**Use cases for hard delete:**
+- **GDPR "right to be forgotten"** compliance
+- **Data minimization** requirements
+- **Storage optimization** for high-volume applications
+- **Security-sensitive** applications
+
+### Important Considerations
+
+⚠️ **Before enabling hard delete:**
+
+1. **Check foreign keys** - Ensure your app handles missing user references
+2. **Backup strategy** - Have proper backups before permanent deletion
+3. **Compliance** - Verify hard delete meets your legal requirements
+4. **Audit trail** - Consider logging deletion events separately
+
+### Database Behavior Notes
+
+**SQLite Boolean Handling:**
+When using soft delete with SQLite, the `active` field is stored as integers (1 for `true`, 0 for `false`). This is normal SQLite behavior and doesn't affect functionality.
+
+**Cross-database compatibility:**
+The module handles boolean values consistently across SQLite, MySQL, and PostgreSQL, but the underlying storage may differ.
+
+### Example Usage
+
+```ts
+// Soft delete configuration (default)
+nuxtUsers: {
+  hardDelete: false,
+  // User deletion sets active: false, preserves data
+}
+
+// Hard delete configuration 
+nuxtUsers: {
+  hardDelete: true,
+  // User deletion permanently removes record
+}
+```
+
 ## Custom Table Names
 
 If you need to customize database table names:

src/module.ts

@@ -42,6 +42,7 @@ export const defaultOptions: ModuleOptions = {
     requireSpecialChars: true,
     preventCommonPasswords: true,
   },
+  hardDelete: false,
 }
 
 export default defineNuxtModule<RuntimeModuleOptions>({
@@ -73,6 +74,7 @@ export default defineNuxtModule<RuntimeModuleOptions>({
         tokenExpiration: options.auth?.tokenExpiration || defaultOptions.auth.tokenExpiration,
         permissions: options.auth?.permissions || defaultOptions.auth.permissions
       },
+      hardDelete: options.hardDelete ?? defaultOptions.hardDelete,
     }
 
     // Add public runtime config for client-side access

src/runtime/server/api/nuxt-users/me.patch.ts

@@ -24,6 +24,11 @@ export default defineEventHandler(async (event) => {
     delete body.role
   }
 
+  // Users should not be able to change their active status via this endpoint.
+  if (body.active) {
+    delete body.active
+  }
+
   try {
     const updatedUser = await updateUser(user.id, body, options)
     return { user: updatedUser }

src/runtime/server/utils/user.ts

@@ -160,16 +160,32 @@ export const updateUser = async (id: number, userData: Partial<User>, options: M
 
 /**
  * Deletes a user by their ID.
+ * By default performs soft delete (sets active to false).
+ * If hardDelete option is true, performs hard delete (removes from database).
+ * In both cases, user tokens are revoked.
  */
 export const deleteUser = async (id: number, options: ModuleOptions): Promise<void> => {
   const db = await useDb(options)
   const usersTable = options.tables.users
 
-  const result = await db.sql`DELETE FROM {${usersTable}} WHERE id = ${id}`
+  // Check if user exists first
+  const userExists = await db.sql`SELECT id FROM {${usersTable}} WHERE id = ${id}` as { rows: Array<{ id: number }> }
 
-  if (result.rows?.length === 0) {
-    throw new Error('User not found or could not be deleted.')
+  if (userExists.rows.length === 0) {
+    throw new Error('User not found.')
   }
+
+  // Always revoke user tokens first
+  await revokeUserTokens(id, options)
+
+  if (options.hardDelete) {
+    // Hard delete - permanently remove from database
+    await db.sql`DELETE FROM {${usersTable}} WHERE id = ${id}`
+    return
+  }
+
+  // Soft delete - set active to false
+  await db.sql`UPDATE {${usersTable}} SET active = false, updated_at = CURRENT_TIMESTAMP WHERE id = ${id}`
 }
 
 /**

src/types.ts

@@ -104,6 +104,13 @@ export interface RuntimeModuleOptions {
      */
     preventCommonPasswords?: boolean
   }
+  /**
+   * Enable hard delete for user deletion
+   * When false (default), users are soft deleted (active set to false)
+   * When true, users are permanently deleted from database
+   * @default false
+   */
+  hardDelete?: boolean
 }
 
 // Runtime config type with all properties required (after merging with defaults)
@@ -134,6 +141,7 @@ export interface ModuleOptions {
     requireSpecialChars: boolean
     preventCommonPasswords: boolean
   }
+  hardDelete: boolean
 }
 
 export interface MailerOptions {

test/test-setup.ts

@@ -71,7 +71,8 @@ export const getTestOptions = (dbType: DatabaseType, dbConfig: DatabaseConfig) =
     requireNumbers: false,
     requireSpecialChars: false,
     preventCommonPasswords: false,
-  }
+  },
+  hardDelete: false
 })
 
 export const cleanupTestSetup = async (dbType: DatabaseType, db: Database, cleanupFiles: string[], tableName: string) => {

test/unit/api.users-list.test.ts

@@ -44,8 +44,8 @@ const testOptions: ModuleOptions = {
   connector: {
     name: 'sqlite',
     options: {
-      path: './test.sqlite'
-    }
+      path: './_test-users-list',
+    },
   },
   tables: {
     migrations: 'migrations',
@@ -56,17 +56,18 @@ const testOptions: ModuleOptions = {
   passwordResetUrl: '/reset-password',
   auth: {
     whitelist: [],
-    permissions: {},
-    tokenExpiration: 1440
+    tokenExpiration: 1440,
+    permissions: {}
   },
   passwordValidation: {
     minLength: 8,
-    requireUppercase: true,
-    requireLowercase: true,
-    requireNumbers: true,
-    requireSpecialChars: true,
-    preventCommonPasswords: true
-  }
+    requireUppercase: false,
+    requireLowercase: false,
+    requireNumbers: false,
+    requireSpecialChars: false,
+    preventCommonPasswords: false,
+  },
+  hardDelete: false
 }
 
 describe('Users List API Route', () => {

test/unit/usePublicPaths.test.ts

@@ -54,7 +54,8 @@ describe('usePublicPaths', () => {
         requireNumbers: true,
         requireSpecialChars: true,
         preventCommonPasswords: true
-      }
+      },
+      hardDelete: false
     }
 
     mockUseRuntimeConfig.mockReturnValue({

test/utils.user.test.ts

@@ -4,7 +4,7 @@ import type { DatabaseType, DatabaseConfig, ModuleOptions } from '../src/types'
 import { cleanupTestSetup, createTestSetup } from './test-setup'
 import { createUsersTable } from '../src/runtime/server/utils/create-users-table'
 import { createPersonalAccessTokensTable } from '../src/runtime/server/utils/create-personal-access-tokens-table'
-import { createUser, findUserByEmail, updateUser, updateUserPassword, getLastLoginTime, getCurrentUserFromToken } from '../src/runtime/server/utils/user'
+import { createUser, findUserByEmail, findUserById, deleteUser, updateUser, updateUserPassword, getLastLoginTime, getCurrentUserFromToken } from '../src/runtime/server/utils/user'
 import { addActiveToUsers } from '../src/runtime/server/utils/add-active-to-users'
 
 describe('User Utilities (src/utils/user.ts)', () => {
@@ -181,6 +181,74 @@ describe('User Utilities (src/utils/user.ts)', () => {
     })
   })
 
+  describe('deleteUser', () => {
+    it('should soft delete user by default (set active to false)', async () => {
+      const userData = { email: 'softdelete@example.com', name: 'Soft Delete User', password: 'password123' }
+      const user = await createUser(userData, testOptions)
+
+      // Verify user is active initially (SQLite may return 1 instead of true)
+      expect(user.active).toBeTruthy()
+
+      // Delete user (should be soft delete by default)
+      await deleteUser(user.id, testOptions)
+
+      // Verify user still exists but is inactive
+      const deletedUser = await findUserById(user.id, testOptions)
+      expect(deletedUser).not.toBeNull()
+      expect(deletedUser?.active).toBeFalsy()
+
+      // Verify user still exists in database
+      const result = await db.sql`SELECT * FROM {${testOptions.tables.users}} WHERE id = ${user.id}`
+      expect(result.rows?.length).toBe(1)
+    })
+
+    it('should hard delete user when hardDelete option is true', async () => {
+      const userData = { email: 'harddelete@example.com', name: 'Hard Delete User', password: 'password123' }
+      const user = await createUser(userData, testOptions)
+
+      // Set hardDelete option
+      const hardDeleteOptions = { ...testOptions, hardDelete: true }
+
+      // Delete user with hard delete
+      await deleteUser(user.id, hardDeleteOptions)
+
+      // Verify user no longer exists
+      const deletedUser = await findUserById(user.id, testOptions)
+      expect(deletedUser).toBeNull()
+
+      // Verify user is removed from database
+      const result = await db.sql`SELECT * FROM {${testOptions.tables.users}} WHERE id = ${user.id}`
+      expect(result.rows?.length).toBe(0)
+    })
+
+    it('should throw error when trying to delete non-existent user', async () => {
+      await expect(deleteUser(999, testOptions)).rejects.toThrow('User not found.')
+    })
+
+    it('should revoke user tokens on both soft and hard delete', async () => {
+      const userData = { email: 'tokenrevoke@example.com', name: 'Token Revoke User', password: 'password123' }
+      const user = await createUser(userData, testOptions)
+
+      // Create a token for the user
+      await db.sql`
+        INSERT INTO {${testOptions.tables.personalAccessTokens}} 
+        (tokenable_type, tokenable_id, name, token, created_at, updated_at) 
+        VALUES ('user', ${user.id}, 'test-token', 'abc123', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+      `
+
+      // Verify token exists
+      let tokenResult = await db.sql`SELECT * FROM {${testOptions.tables.personalAccessTokens}} WHERE tokenable_id = ${user.id}`
+      expect(tokenResult.rows?.length).toBe(1)
+
+      // Soft delete user
+      await deleteUser(user.id, testOptions)
+
+      // Verify tokens are revoked
+      tokenResult = await db.sql`SELECT * FROM {${testOptions.tables.personalAccessTokens}} WHERE tokenable_id = ${user.id}`
+      expect(tokenResult.rows?.length).toBe(0)
+    })
+  })
+
   describe('Integration tests', () => {
     it('should work together: create user, find user, update password', async () => {
       const userData = { email: 'integration@webmania.cc', name: 'Integration User', password: 'initialpassword' }