feat: Implement authentication flow

- Added AuthService and related services
- Implemented email/anon sign-in routes
- Added auth middleware
- Added token service

Author: fulleni

lib/src/middlewares/authentication_middleware.dart

@@ -0,0 +1,83 @@
+import 'package:dart_frog/dart_frog.dart';
+import 'package:ht_api/src/services/auth_token_service.dart';
+import 'package:ht_shared/ht_shared.dart';
+
+/// Middleware to handle authentication by verifying Bearer tokens.
+///
+/// It extracts the token from the 'Authorization' header, validates it using
+/// the [AuthTokenService], and provides the resulting [User] object (or null)
+/// into the request context via `context.read<User?>()`.
+///
+/// If a route requires authentication (determined by where this middleware is
+/// applied) and the token is missing or invalid, it should ideally throw an
+/// [UnauthorizedException] to be caught by the [errorHandler].
+///
+/// **Usage:** Apply this middleware to routes or groups of routes that require
+/// access to the authenticated user's identity or need protection.
+Middleware authenticationProvider() {
+  return (handler) {
+    return (context) async {
+      // Read the AuthTokenService provided by earlier middleware
+      final tokenService = context.read<AuthTokenService>();
+      User? user; // Initialize user as null
+
+      // Extract the Authorization header
+      final authHeader = context.request.headers['Authorization'];
+
+      if (authHeader != null && authHeader.startsWith('Bearer ')) {
+        // Extract the token string
+        final token = authHeader.substring(7); // Length of 'Bearer '
+        try {
+          // Validate the token using the service
+          user = await tokenService.validateToken(token);
+          if (user != null) {
+            print('Authentication successful for user: ${user.id}');
+          } else {
+            print('Invalid token provided.');
+            // Optional: Could throw UnauthorizedException here if *all* routes
+            // using this middleware strictly require a valid token.
+            // However, providing null allows routes to handle optional auth.
+          }
+        } on HtHttpException catch (e) {
+          // Log token validation errors from the service
+          print('Token validation failed: $e');
+          // Let the error propagate if needed, or handle specific cases.
+          // For now, we treat validation errors as resulting in no user.
+          user = null;
+        } catch (e) {
+          // Catch unexpected errors during validation
+          print('Unexpected error during token validation: $e');
+          user = null;
+        }
+      } else {
+        print('No valid Authorization header found.');
+      }
+
+      // Provide the User object (or null) into the context
+      // This makes `context.read<User?>()` available downstream.
+      return handler(context.provide<User?>(() => user));
+    };
+  };
+}
+
+/// Middleware factory that ensures a valid authenticated user exists.
+///
+/// Use this for routes that *strictly require* a logged-in user.
+/// It reads the `User?` provided by `authenticationProvider` and throws
+/// [UnauthorizedException] if the user is null.
+Middleware requireAuthentication() {
+  return (handler) {
+    return (context) {
+      final user = context.read<User?>();
+      if (user == null) {
+        print(
+            'Authentication required but no valid user found. Denying access.',);
+        // Throwing allows the central errorHandler to create the 401 response.
+        throw const UnauthorizedException('Authentication required.');
+      }
+      // If user exists, proceed to the handler
+      print('Authentication check passed for user: ${user.id}');
+      return handler(context);
+    };
+  };
+}

lib/src/services/auth_service.dart

@@ -0,0 +1,183 @@
+import 'package:ht_data_repository/ht_data_repository.dart';
+import 'package:ht_email_repository/ht_email_repository.dart';
+import 'package:ht_shared/ht_shared.dart';
+import 'package:uuid/uuid.dart';
+
+import 'package:ht_api/src/services/auth_token_service.dart';
+import 'package:ht_api/src/services/verification_code_storage_service.dart';
+
+/// {@template auth_service}
+/// Service responsible for orchestrating authentication logic on the backend.
+///
+/// It coordinates interactions between user data storage, token generation,
+/// verification code management, and email sending.
+/// {@endtemplate}
+class AuthService {
+  /// {@macro auth_service}
+  const AuthService({
+    required HtDataRepository<User> userRepository,
+    required AuthTokenService authTokenService,
+    required VerificationCodeStorageService verificationCodeStorageService,
+    required HtEmailRepository emailRepository,
+    required Uuid uuidGenerator,
+  })  : _userRepository = userRepository,
+        _authTokenService = authTokenService,
+        _verificationCodeStorageService = verificationCodeStorageService,
+        _emailRepository = emailRepository,
+        _uuid = uuidGenerator;
+
+  final HtDataRepository<User> _userRepository;
+  final AuthTokenService _authTokenService;
+  final VerificationCodeStorageService _verificationCodeStorageService;
+  final HtEmailRepository _emailRepository;
+  final Uuid _uuid;
+
+  /// Initiates the email sign-in process.
+  ///
+  /// Generates a verification code, stores it, and sends it via email.
+  /// Throws [InvalidInputException] for invalid email format (via email client).
+  /// Throws [OperationFailedException] if code generation/storage/email fails.
+  Future<void> initiateEmailSignIn(String email) async {
+    try {
+      // Generate and store the code
+      final code = await _verificationCodeStorageService.generateAndStoreCode(
+        email,
+      );
+
+      // Send the code via email
+      await _emailRepository.sendOtpEmail(
+        recipientEmail: email,
+        otpCode: code,
+      );
+      print('Initiated email sign-in for $email, code sent.');
+    } on HtHttpException {
+      // Propagate known exceptions from dependencies
+      rethrow;
+    } catch (e) {
+      // Catch unexpected errors during orchestration
+      print('Error during initiateEmailSignIn for $email: $e');
+      throw const OperationFailedException(
+        'Failed to initiate email sign-in process.',
+      );
+    }
+  }
+
+  /// Completes the email sign-in process by verifying the code.
+  ///
+  /// If the code is valid, finds or creates the user, generates an auth token.
+  /// Returns the authenticated User and the generated token.
+  /// Throws [InvalidInputException] if the code is invalid or expired.
+  /// Throws [AuthenticationException] for specific code mismatch.
+  /// Throws [OperationFailedException] for user lookup/creation or token errors.
+  Future<({User user, String token})> completeEmailSignIn(
+    String email,
+    String code,
+  ) async {
+    // 1. Validate the code
+    final isValidCode = await _verificationCodeStorageService.validateCode(
+      email,
+      code,
+    );
+    if (!isValidCode) {
+      // Consider distinguishing between expired and simply incorrect codes
+      // For now, treat both as invalid input.
+      throw const InvalidInputException(
+          'Invalid or expired verification code.',);
+    }
+
+    // 2. Find or create the user
+    User user;
+    try {
+      // Attempt to find user by email (assuming a query method exists)
+      // NOTE: HtDataRepository<User> currently lacks findByEmail.
+      // We'll simulate this by querying all and filtering for now.
+      // Replace with a proper query when available.
+      final query = {'email': email}; // Hypothetical query
+      final paginatedResponse = await _userRepository.readAllByQuery(query);
+
+      if (paginatedResponse.items.isNotEmpty) {
+        user = paginatedResponse.items.first;
+        print('Found existing user: ${user.id} for email $email');
+      } else {
+        // User not found, create a new one
+        print('User not found for $email, creating new user.');
+        user = User(
+          id: _uuid.v4(), // Generate new ID
+          email: email,
+          isAnonymous: false, // Email verified user is not anonymous
+        );
+        user = await _userRepository.create(user); // Save the new user
+        print('Created new user: ${user.id}');
+      }
+    } on HtHttpException catch (e) {
+      print('Error finding/creating user for $email: $e');
+      throw const OperationFailedException(
+          'Failed to find or create user account.',);
+    } catch (e) {
+      print('Unexpected error during user lookup/creation for $email: $e');
+      throw const OperationFailedException('Failed to process user account.');
+    }
+
+    // 3. Generate authentication token
+    try {
+      final token = await _authTokenService.generateToken(user);
+      print('Generated token for user ${user.id}');
+      return (user: user, token: token);
+    } catch (e) {
+      print('Error generating token for user ${user.id}: $e');
+      throw const OperationFailedException(
+          'Failed to generate authentication token.',);
+    }
+  }
+
+  /// Performs anonymous sign-in.
+  ///
+  /// Creates a new anonymous user record and generates an auth token.
+  /// Returns the anonymous User and the generated token.
+  /// Throws [OperationFailedException] if user creation or token generation fails.
+  Future<({User user, String token})> performAnonymousSignIn() async {
+    // 1. Create anonymous user
+    User user;
+    try {
+      user = User(
+        id: _uuid.v4(), // Generate new ID
+        isAnonymous: true,
+        email: null, // Anonymous users don't have an email initially
+      );
+      user = await _userRepository.create(user);
+      print('Created anonymous user: ${user.id}');
+    } on HtHttpException catch (e) {
+      print('Error creating anonymous user: $e');
+      throw const OperationFailedException('Failed to create anonymous user.');
+    } catch (e) {
+      print('Unexpected error during anonymous user creation: $e');
+      throw const OperationFailedException(
+          'Failed to process anonymous sign-in.',);
+    }
+
+    // 2. Generate token
+    try {
+      final token = await _authTokenService.generateToken(user);
+      print('Generated token for anonymous user ${user.id}');
+      return (user: user, token: token);
+    } catch (e) {
+      print('Error generating token for anonymous user ${user.id}: $e');
+      throw const OperationFailedException(
+          'Failed to generate authentication token.',);
+    }
+  }
+
+  /// Performs sign-out actions (currently placeholder).
+  ///
+  /// In a real implementation, this might involve invalidating the token
+  /// on the server-side (e.g., adding to a blacklist if using JWTs).
+  /// The primary sign-out action (clearing local token) happens client-side.
+  Future<void> performSignOut({required String userId}) async {
+    // Placeholder: Server-side token invalidation logic would go here.
+    // For the current SimpleAuthTokenService, there's nothing server-side
+    // to invalidate easily. A real JWT implementation might use a blacklist.
+    print('Performing server-side sign-out actions for user $userId (if any).');
+    await Future<void>.delayed(Duration.zero); // Simulate async
+    // No exceptions thrown here unless invalidation fails.
+  }
+}

lib/src/services/auth_token_service.dart

@@ -0,0 +1,76 @@
+import 'package:ht_shared/ht_shared.dart';
+
+/// {@template auth_token_service}
+/// Service responsible for generating and validating authentication tokens.
+///
+/// Implementations will handle the specifics of token creation (e.g., JWT
+/// signing with a secret key) and validation (signature, expiry, claims).
+/// {@endtemplate}
+abstract class AuthTokenService {
+  /// {@macro auth_token_service}
+  const AuthTokenService();
+
+  /// Generates an authentication token for the given user.
+  ///
+  /// Returns the generated token string.
+  /// Throws [OperationFailedException] if token generation fails.
+  Future<String> generateToken(User user);
+
+  /// Validates the given token string.
+  ///
+  /// Returns the [User] associated with the token if valid.
+  /// Returns `null` if the token is invalid, expired, or malformed.
+  /// Throws [OperationFailedException] for unexpected validation errors.
+  Future<User?> validateToken(String token);
+
+  // Potential future methods:
+  // Future<void> invalidateToken(String token); // For token blacklisting
+}
+
+/// A basic implementation of [AuthTokenService].
+///
+/// **Note:** This is a placeholder and **not secure** for production.
+/// It does not perform real cryptographic signing or validation.
+/// Replace with a proper JWT implementation (e.g., using `dart_jsonwebtoken`).
+class SimpleAuthTokenService implements AuthTokenService {
+  /// {@macro simple_auth_token_service}
+  const SimpleAuthTokenService({
+    // In a real implementation, you'd inject a secret key here.
+    String secretKey = 'very-secret-key-replace-me',
+  }) : _secretKey = secretKey;
+
+  // ignore: unused_field
+  final String _secretKey;
+
+  // Placeholder for storing "valid" tokens in this insecure example.
+  // A real implementation validates cryptographically.
+  static final Map<String, User> _validTokens = {};
+
+  @override
+  Future<String> generateToken(User user) async {
+    // Insecure placeholder: Generate a simple token string.
+    // A real implementation would create a JWT with claims and sign it.
+    final token =
+        'token_for_${user.id}_${DateTime.now().millisecondsSinceEpoch}';
+    _validTokens[token] = user; // Store for simple validation
+    print('Generated token (INSECURE): $token for user ${user.id}');
+    await Future<void>.delayed(Duration.zero); // Simulate async
+    return token;
+  }
+
+  @override
+  Future<User?> validateToken(String token) async {
+    // Insecure placeholder: Check if the token exists in our map.
+    // A real implementation would verify JWT signature, expiry, issuer, etc.
+    print('Validating token (INSECURE): $token');
+    final user = _validTokens[token];
+    await Future<void>.delayed(Duration.zero); // Simulate async
+    if (user != null) {
+      print('Token valid for user ${user.id}');
+      return user;
+    } else {
+      print('Token invalid');
+      return null;
+    }
+  }
+}