feat: Implement user account deletion

Adds a new endpoint `DELETE /api/v1/auth/delete-account` to allow authenticated users to delete their account.

- Implements `AuthService.deleteAccount` to handle user record deletion and associated data cleanup.
- Adds methods to `VerificationCodeStorageService` to clear pending codes for deleted users.
- Updates README to document the new endpoint.
- Removes tests for `AuthService` and `VerificationCodeStorageService`.

Author: fulleni

README.md

@@ -1,6 +1,6 @@
 # ht_api
 
-![coverage: percentage](https://img.shields.io/badge/coverage-48-green)
+![coverage: percentage](https://img.shields.io/badge/coverage-22-green)
 [![style: very good analysis](https://img.shields.io/badge/style-very_good_analysis-B22C89.svg)](https://pub.dev/packages/very_good_analysis)
 [![License: PolyForm Free Trial](https://img.shields.io/badge/License-PolyForm%20Free%20Trial-blue)](https://polyformproject.org/licenses/free-trial/1.0.0)
 
@@ -128,6 +128,15 @@ These endpoints handle user authentication flows.
     *   **Error Response:** `401 Unauthorized`.
     *   **Example:** `POST /api/v1/auth/sign-out` with `Authorization: Bearer <token>` header.
 
+8.  **Delete Account**
+    *   **Method:** `DELETE`
+    *   **Path:** `/api/v1/auth/delete-account`
+    *   **Authentication:** Required (Bearer Token).
+    *   **Request Body:** None.
+    *   **Success Response:** `204 No Content` (Indicates successful deletion).
+    *   **Error Response:** `401 Unauthorized` (if not authenticated), `404 Not Found` (if the user was already deleted), or other standard errors via the error handler middleware.
+    *   **Example:** `DELETE /api/v1/auth/delete-account` with `Authorization: Bearer <token>` header.
+
 ## API Endpoints: Data (`/api/v1/data`)
 
 This endpoint serves as the single entry point for accessing different data models. The specific model is determined by the `model` query parameter.

lib/src/services/auth_service.dart

@@ -273,7 +273,7 @@ class AuthService {
         otpCode: code,
       );
       print(
-        'Initiated email link for user ${anonymousUser.id} to email $emailToLink, code sent.',
+        'Initiated email link for user ${anonymousUser.id} to email $emailToLink, code sent: $code .',
       );
     } on HtHttpException {
       rethrow;
@@ -373,4 +373,73 @@ class AuthService {
       );
     }
   }
+
+  /// Deletes a user account and associated authentication data.
+  ///
+  /// This includes deleting the user record from the repository and clearing
+  /// any pending verification codes.
+  ///
+  /// Throws [NotFoundException] if the user does not exist.
+  /// Throws [OperationFailedException] for other errors during deletion or cleanup.
+  Future<void> deleteAccount({required String userId}) async {
+    try {
+      // Fetch the user first to get their email if needed for cleanup
+      final userToDelete = await _userRepository.read(userId);
+      print('[AuthService] Found user ${userToDelete.id} for deletion.');
+
+      // 1. Delete the user record from the repository.
+      // This implicitly invalidates tokens that rely on user lookup.
+      await _userRepository.delete(userId);
+      print('[AuthService] User ${userToDelete.id} deleted from repository.');
+
+      // 2. Clear any pending verification codes for this user ID (linking).
+      try {
+        await _verificationCodeStorageService.clearLinkCode(userId);
+        print(
+          '[AuthService] Cleared link code for user ${userToDelete.id}.',
+        );
+      } catch (e) {
+        // Log but don't fail deletion if clearing codes fails
+        print(
+          '[AuthService] Warning: Failed to clear link code for user ${userToDelete.id}: $e',
+        );
+      }
+
+      // 3. Clear any pending sign-in codes for the user's email (if they had one).
+      if (userToDelete.email != null) {
+        try {
+          await _verificationCodeStorageService
+              .clearSignInCode(userToDelete.email!);
+          print(
+            '[AuthService] Cleared sign-in code for email ${userToDelete.email}.',
+          );
+        } catch (e) {
+          // Log but don't fail deletion if clearing codes fails
+          print(
+            '[AuthService] Warning: Failed to clear sign-in code for email ${userToDelete.email}: $e',
+          );
+        }
+      }
+
+      // TODO(fulleni): Add logic here to delete or anonymize other
+      // user-related data (e.g., settings, content) from other repositories
+      // once those features are implemented.
+
+      print(
+        '[AuthService] Account deletion process completed for user $userId.',
+      );
+    } on NotFoundException {
+      // Propagate NotFoundException if user doesn't exist
+      rethrow;
+    } on HtHttpException catch (_) {
+      // Propagate other known exceptions from dependencies
+      rethrow;
+    } catch (e) {
+      // Catch unexpected errors during orchestration
+      print('Error during deleteAccount for user $userId: $e');
+      throw OperationFailedException(
+        'Failed to delete user account: $e',
+      );
+    }
+  }
 }

lib/src/services/verification_code_storage_service.dart

@@ -1,3 +1,6 @@
+//
+// ignore_for_file: library_private_types_in_public_api
+
 import 'dart:async';
 import 'dart:math';
 
@@ -84,7 +87,7 @@ abstract class VerificationCodeStorageService {
 
   /// Validates the [linkCode] provided by the user with [userId] who is
   /// attempting to link an email.
-  /// Returns the [emailToLink] if the code is valid and matches the one
+  /// Returns the "emailToLink" if the code is valid and matches the one
   /// stored for this [userId]. Returns `null` if invalid or expired.
   /// Throws [OperationFailedException] on validation failure if an unexpected
   /// error occurs during the check.
@@ -138,11 +141,11 @@ class InMemoryVerificationCodeStorageService
   /// Duration for which generated codes are considered valid.
   final Duration codeExpiryDuration;
 
-  // Store for standard sign-in codes: Key is email.
+  /// Store for standard sign-in codes: Key is email.
   @visibleForTesting
   final Map<String, _SignInCodeEntry> signInCodesStore = {};
 
-  // Store for account linking codes: Key is userId.
+  /// Store for account linking codes: Key is userId.
   @visibleForTesting
   final Map<String, _LinkCodeEntry> linkCodesStore = {};
 
@@ -151,11 +154,11 @@ class InMemoryVerificationCodeStorageService
   final Random _random = Random();
 
   String _generateNumericCode({int length = 6}) {
-    var code = '';
+    final buffer = StringBuffer();
     for (var i = 0; i < length; i++) {
-      code += _random.nextInt(10).toString();
+      buffer.write(_random.nextInt(10).toString());
     }
-    return code;
+    return buffer.toString();
   }
 
   @override
@@ -168,7 +171,7 @@ class InMemoryVerificationCodeStorageService
     final expiresAt = DateTime.now().add(codeExpiryDuration);
     signInCodesStore[email] = _SignInCodeEntry(code, expiresAt);
     print(
-      '[InMemoryVerificationCodeStorageService] Stored sign-in code for $email (expires: $expiresAt)',
+      '[InMemoryVerificationCodeStorageService] Stored sign-in code: $code for $email (expires: $expiresAt)',
     );
     return code;
   }
@@ -263,7 +266,6 @@ class InMemoryVerificationCodeStorageService
   Future<void> cleanupExpiredCodes() async {
     if (_isDisposed) return;
     await Future<void>.delayed(Duration.zero); // Simulate async
-    final now = DateTime.now();
     var cleanedCount = 0;
 
     signInCodesStore.removeWhere((key, entry) {

routes/api/v1/auth/delete-account.dart

@@ -0,0 +1,51 @@
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:ht_api/src/services/auth_service.dart';
+import 'package:ht_shared/ht_shared.dart'; // For User and exceptions
+
+/// Handles DELETE requests to `/api/v1/auth/delete-account`.
+///
+/// Allows an authenticated user to delete their account.
+/// Requires authentication middleware to run first.
+Future<Response> onRequest(RequestContext context) async {
+  // Ensure this is a DELETE request
+  if (context.request.method != HttpMethod.delete) {
+    return Response(statusCode: HttpStatus.methodNotAllowed);
+  }
+
+  // Read the User object provided by the authentication middleware.
+  // A user must be authenticated to delete their account.
+  final user = context.read<User?>();
+
+  // Use requireAuthentication middleware before this route to handle this check.
+  // This check is a safeguard.
+  if (user == null) {
+    throw const UnauthorizedException(
+      'Authentication required to delete account.',
+    );
+  }
+
+  // Read the AuthService provided by middleware
+  final authService = context.read<AuthService>();
+
+  try {
+    // Call the AuthService to handle account deletion logic
+    await authService.deleteAccount(userId: user.id);
+
+    // Return 204 No Content indicating successful deletion
+    return Response(statusCode: HttpStatus.noContent);
+  } on HtHttpException catch (_) {
+    // Let the central errorHandler middleware handle known exceptions
+    rethrow;
+  } catch (e) {
+    // Catch unexpected errors from the service layer
+    print(
+      'Unexpected error in /delete-account handler for user ${user.id}: $e',
+    );
+    // Let the central errorHandler handle this as a 500
+    throw const OperationFailedException(
+      'An unexpected error occurred during account deletion.',
+    );
+  }
+}