Integrate email notifications into signup and login (#38)

frontend/packages/sxchnge_auth/lib/src/dto/backend.dart

@@ -0,0 +1,23 @@
+import 'dart:convert';
+
+class BackendDTO {
+  BackendDTO(this.data);
+  factory BackendDTO.decode(String body) => BackendDTO(
+    (jsonDecode(body) as Map<String, dynamic>)['data'] as Map<String, dynamic>,
+  );
+  final Map<String, dynamic> data;
+  String get error => data['error'] as String? ?? 'unavailable';
+  String get userId =>
+      data['userId'] as String? ??
+      (data['account'] as Map<String, dynamic>?)?['id'] as String? ??
+      '';
+  String get pendingToken =>
+      (data['pendingToken'] as Map<String, dynamic>)['token'] as String;
+  String get target => data['target'] as String;
+  DateTime get expiresAt => DateTime.parse(data['expiresAt'] as String);
+  DateTime get resendAt => DateTime.parse(data['resendAt'] as String);
+  String get accessToken =>
+      (data['accessToken'] as Map<String, dynamic>)['token'] as String;
+  String get refreshToken =>
+      (data['refreshToken'] as Map<String, dynamic>)['token'] as String;
+}

frontend/packages/sxchnge_auth/lib/src/mappers/backend.dart

@@ -0,0 +1,45 @@
+import '../dto/backend.dart';
+import '../models/auth.dart';
+import '../models/session.dart';
+import '../models/two_factor.dart';
+
+abstract final class BackendMapper {
+  static AuthResult signup(BackendDTO dto) {
+    if (dto.userId.isEmpty) throw const FormatException('Missing user');
+    return AuthResult(userId: dto.userId, isSimulated: false);
+  }
+
+  static FactorChallenge challenge(BackendDTO dto, String id) =>
+      FactorChallenge(
+        id: id,
+        purpose: FactorPurpose.login,
+        operation: id,
+        target: dto.target,
+        expiresAt: dto.expiresAt,
+        resendAt: dto.resendAt,
+      );
+  static AuthSession session(BackendDTO dto) {
+    if (dto.accessToken.isEmpty || dto.userId.isEmpty) {
+      throw const FormatException('Missing session');
+    }
+    return AuthSession(dto.userId, dto.accessToken, dto.refreshToken);
+  }
+
+  static AuthException authFailure(int status, BackendDTO dto) =>
+      AuthException(switch (dto.error) {
+        'email_in_use' => AuthError.emailInUse,
+        'account_not_verified' => AuthError.accountNotVerified,
+        _ when status == 401 => AuthError.invalidCredentials,
+        _ when status == 429 => AuthError.factorCooldown,
+        _ => AuthError.unavailable,
+      });
+  static FactorException factorFailure(int status, BackendDTO dto) =>
+      FactorException(switch (dto.error) {
+        'expired' => FactorError.expired,
+        'locked' => FactorError.locked,
+        'invalid' => FactorError.invalid,
+        _ when status == 429 => FactorError.cooldown,
+        _ when status == 401 => FactorError.expired,
+        _ => FactorError.unavailable,
+      });
+}

frontend/packages/sxchnge_auth/lib/src/models/auth.dart

@@ -39,6 +39,7 @@ class AuthResult {
 
 enum AuthError {
   invalidCredentials,
+  accountNotVerified,
   emailInUse,
   unavailable,
   unexpected,

frontend/packages/sxchnge_auth/lib/src/models/session.dart

@@ -0,0 +1,5 @@
+/// In-memory credentials. Never include these in analytics or provider state.
+class AuthSession {
+  const AuthSession(this.userId, this.accessToken, this.refreshToken);
+  final String userId, accessToken, refreshToken;
+}

frontend/packages/sxchnge_auth/lib/src/services/backend.dart

@@ -0,0 +1,250 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:math';
+
+import 'package:flutter/foundation.dart';
+
+import 'package:http/http.dart' as http;
+
+import '../dto/backend.dart';
+import '../dto/results.dart';
+import '../mappers/backend.dart';
+import '../mappers/results.dart';
+import '../models/auth.dart';
+import '../models/session.dart';
+import '../models/two_factor.dart';
+import '../models/verification.dart';
+import 'contracts.dart';
+import 'guarded_login.dart';
+import 'http/client.dart';
+import 'two_factor.dart';
+import 'verification.dart';
+
+/// Real authentication; wallet/settings operations remain separate adapters.
+class BackendAuthServices
+    implements
+        PendingLoginService,
+        SignupService,
+        VerificationService,
+        TwoFactorService,
+        SimulationInfo {
+  BackendAuthServices({
+    required this.baseUri,
+    required this.clientId,
+    http.Client? client,
+  }) : _client = client ?? createClient() {
+    if (clientId.isEmpty ||
+        !baseUri.hasAuthority ||
+        (baseUri.scheme != 'https' &&
+            !(baseUri.scheme == 'http' &&
+                ['localhost', '127.0.0.1'].contains(baseUri.host))) ||
+        baseUri.hasQuery ||
+        baseUri.hasFragment ||
+        baseUri.userInfo.isNotEmpty) {
+      throw ArgumentError('Valid API URL and client ID required');
+    }
+  }
+  final Uri baseUri;
+  final String clientId;
+  final http.Client _client;
+  final String _deviceId = _key();
+  final _pending = <String, String>{};
+  final _grants = <String, AuthSession>{};
+  final _retryKeys = <String, String>{};
+  String? _queuedSignup;
+  AuthSession? _session;
+  AuthSession? get session => _session;
+  @override
+  bool get isSimulated => false;
+  static String _key() => base64UrlEncode(
+    List<int>.generate(24, (_) => Random.secure().nextInt(256)),
+  );
+  Future<BackendDTO> _post(
+    String path,
+    Map<String, Object?> body, {
+    bool factor = false,
+  }) async {
+    try {
+      final uri = baseUri.replace(
+        path: '${baseUri.path.replaceFirst(RegExp(r'/$'), '')}/accounts/$path',
+      );
+      final res = await _client
+          .post(
+            uri,
+            headers: {
+              'Content-Type': 'application/json',
+              if (kIsWeb) 'X-Auth-Transport': 'cookie',
+              if (kIsWeb) 'X-CSRF-Protection': '1',
+            },
+            body: jsonEncode(body),
+          )
+          .timeout(const Duration(seconds: 15));
+      final dto = BackendDTO.decode(res.body);
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        throw factor
+            ? BackendMapper.factorFailure(res.statusCode, dto)
+            : BackendMapper.authFailure(res.statusCode, dto);
+      }
+      return dto;
+    } on AuthException {
+      rethrow;
+    } on FactorException {
+      rethrow;
+    } catch (_) {
+      if (factor) throw const FactorException(FactorError.unavailable);
+      throw const AuthException(AuthError.unavailable);
+    }
+  }
+
+  @override
+  Future<AuthResult> signup(SignupRequest r) async {
+    final email = r.email.trim().toLowerCase();
+    final key = _retryKeys.putIfAbsent('signup:$email', _key);
+    final dto = await _post('signup', {
+      'name': r.name,
+      'email': email,
+      'password': r.password,
+      'locale': r.locale,
+      'idempotencyKey': key,
+    });
+    final result = BackendMapper.signup(dto);
+    _retryKeys.remove('signup:$email');
+    _queuedSignup = email;
+    return result;
+  }
+
+  @override
+  Future<AuthResult> login(LoginRequest r) async {
+    _pending.clear();
+    _grants.clear();
+    _session = null;
+    final dto = await _post('login', {
+      'login': {'login': r.email, 'password': r.password},
+      'clientId': clientId,
+      'deviceId': _deviceId,
+    });
+    final id = _key();
+    final challenge = BackendMapper.challenge(dto, id);
+    _pending[id] = dto.pendingToken;
+    return AuthResult(userId: '', isSimulated: false, challenge: challenge);
+  }
+
+  @override
+  Future<VerificationResult> send({
+    required String email,
+    required String locale,
+  }) async {
+    final normalized = email.trim().toLowerCase();
+    // Signup already queued this email. The existing confirmation page requests
+    // its initial delivery on mount; consume that receipt once.
+    if (_queuedSignup == normalized) {
+      _queuedSignup = null;
+      return VerificationMapper.fromDTO(
+        const VerificationDTO(simulated: false),
+      );
+    }
+    final key = _retryKeys.putIfAbsent('activation:$normalized', _key);
+    try {
+      await _post('verification/send', {
+        'email': normalized,
+        'idempotencyKey': key,
+      }, factor: true);
+      _retryKeys.remove('activation:$normalized');
+      return VerificationMapper.fromDTO(
+        const VerificationDTO(simulated: false),
+      );
+    } on FactorException catch (e) {
+      if (e.code == FactorError.expired || e.code == FactorError.invalid) {
+        _retryKeys.remove('activation:$normalized');
+      }
+      throw const VerificationException(VerificationError.internal);
+    } catch (_) {
+      throw const VerificationException(VerificationError.internal);
+    }
+  }
+
+  @override
+  Future<VerificationResult> confirm({required String token}) async {
+    try {
+      await _post('verification/confirm', {'token': token}, factor: true);
+      return VerificationMapper.fromDTO(
+        const VerificationDTO(simulated: false),
+      );
+    } on FactorException catch (e) {
+      throw VerificationException(switch (e.code) {
+        FactorError.expired => VerificationError.expired,
+        FactorError.invalid => VerificationError.invalid,
+        _ => VerificationError.internal,
+      });
+    }
+  }
+
+  @override
+  Future<FactorChallenge> resend(String challengeId) async {
+    final pending = _pending[challengeId];
+    if (pending == null) throw const FactorException(FactorError.expired);
+    final key = _retryKeys.putIfAbsent('login:$challengeId', _key);
+    final dto = await _post('login/resend', {
+      'pendingToken': pending,
+      'idempotencyKey': key,
+    }, factor: true);
+    _retryKeys.remove('login:$challengeId');
+    return BackendMapper.challenge(dto, challengeId);
+  }
+
+  @override
+  Future<FactorGrant> verify(String challengeId, String code) async {
+    final pending = _pending[challengeId];
+    if (pending == null) throw const FactorException(FactorError.expired);
+    final dto = await _post('login/verify', {
+      'pendingToken': pending,
+      'code': code,
+    }, factor: true);
+    final session = BackendMapper.session(dto);
+    _pending.remove(challengeId);
+    _grants[challengeId] = session;
+    return FactorGrant(challengeId);
+  }
+
+  @override
+  Future<AuthResult> completeLogin(
+    FactorChallenge challenge,
+    FactorGrant grant,
+  ) async {
+    if (challenge.id != grant.token ||
+        challenge.purpose != FactorPurpose.login) {
+      throw const AuthException(AuthError.factorRequired);
+    }
+    final accepted = _grants.remove(grant.token);
+    if (accepted == null) throw const AuthException(AuthError.factorRequired);
+    _session = accepted;
+    return AuthResult(userId: accepted.userId, isSimulated: false);
+  }
+
+  // Unsupported settings and money operations fail closed until their own
+  // backend adapters exist. They cannot borrow an authentication grant.
+  @override
+  Future<FactorSettings> fetch() async =>
+      throw const FactorException(FactorError.unavailable);
+  @override
+  Future<FactorChallenge?> begin(
+    FactorPurpose purpose,
+    String operation,
+  ) async => throw const FactorException(FactorError.unavailable);
+  @override
+  Future<void> authorize(
+    FactorPurpose purpose,
+    String operation,
+    String? grant,
+  ) async => throw const FactorException(FactorError.required);
+  @override
+  Future<FactorSettings> setEnabled(bool enabled, String grant) async =>
+      throw const FactorException(FactorError.unavailable);
+  void close() {
+    _client.close();
+    _pending.clear();
+    _grants.clear();
+    _retryKeys.clear();
+    _session = null;
+  }
+}

frontend/packages/sxchnge_auth/lib/src/services/http/browser.dart

@@ -0,0 +1,4 @@
+import 'package:http/browser_client.dart';
+import 'package:http/http.dart' as http;
+
+http.Client createClient() => BrowserClient()..withCredentials = true;

frontend/packages/sxchnge_auth/lib/src/services/http/client.dart

@@ -0,0 +1 @@
+export 'native.dart' if (dart.library.js_interop) 'browser.dart';

frontend/packages/sxchnge_auth/lib/src/services/http/native.dart

@@ -0,0 +1,3 @@
+import 'package:http/http.dart' as http;
+
+http.Client createClient() => http.Client();

frontend/packages/sxchnge_auth/lib/src/services/instrumented.dart

@@ -56,6 +56,7 @@ class InstrumentedAuthServices
     } catch (error) {
       final failure = switch (error) {
         AuthException(code: final code) => switch (code) {
+          AuthError.accountNotVerified => JourneyFailure.invalid,
           AuthError.invalidCredentials => JourneyFailure.invalidCredentials,
           AuthError.emailInUse => JourneyFailure.emailInUse,
           AuthError.unavailable => JourneyFailure.unavailable,

frontend/packages/sxchnge_auth/lib/sxchnge_auth.dart

@@ -20,3 +20,6 @@ export 'src/services/two_factor.dart';
 export 'src/services/dummy_factor.dart';
 export 'src/widgets/two_factor.dart';
 export 'src/services/guarded_login.dart';
+
+export 'src/services/backend.dart';
+export 'src/models/session.dart';