added guardian login with views for their assigned childs

2026-09-20 11:11:58 +02:00
parent e4e2b1a4fb
commit 67c935c05b
117 changed files with 4784 additions and 1514 deletions
@@ -0,0 +1,58 @@
+import 'package:dio/dio.dart';
+
+import '../../../../auth_link/pending_guardian_request.dart';
+import '../../marianumconnect_api.dart';
+import '../../marianumconnect_query.dart';
+import 'guardian_login_exception.dart';
+
+class AuthGuardianRequestResponse {
+  final String requestId;
+  final DateTime expiresAt;
+  final DateTime resendAvailableAt;
+  final int codeLength;
+
+  const AuthGuardianRequestResponse({
+    required this.requestId,
+    required this.expiresAt,
+    required this.resendAvailableAt,
+    required this.codeLength,
+  });
+
+  factory AuthGuardianRequestResponse.fromJson(Map<String, dynamic> json) =>
+      AuthGuardianRequestResponse(
+        requestId: json['requestId'] as String,
+        expiresAt: DateTime.parse(json['expiresAt'] as String),
+        resendAvailableAt: DateTime.parse(json['resendAvailableAt'] as String),
+        codeLength:
+            json['codeLength'] as int? ??
+            PendingGuardianRequest.defaultCodeLength,
+      );
+}
+
+/// Starts a passwordless guardian login: the server mails a code and a link.
+/// The answer is identical for unknown addresses, so it reveals nothing about
+/// which e-mails are registered.
+class AuthGuardianRequest extends MarianumConnectQuery {
+  AuthGuardianRequest({Dio? dio})
+    : super(dio: dio ?? MarianumConnectApi.plainDio());
+
+  Future<AuthGuardianRequestResponse> run({
+    required String email,
+    required String deviceChallenge,
+    required String tokenName,
+  }) async {
+    try {
+      final response = await dio.post<Map<String, dynamic>>(
+        endpoint('auth/guardian/request'),
+        data: {
+          'email': email,
+          'deviceChallenge': deviceChallenge,
+          'tokenName': tokenName,
+        },
+      );
+      return AuthGuardianRequestResponse.fromJson(response.data!);
+    } on DioException catch (e) {
+      throw GuardianLoginException.fromDio(e);
+    }
+  }
+}
@@ -0,0 +1,51 @@
+import 'package:dio/dio.dart';
+
+import '../../auth/token_storage.dart';
+import '../../marianumconnect_api.dart';
+import '../../marianumconnect_query.dart';
+import '../auth_login/auth_login_response.dart';
+import 'guardian_login_exception.dart';
+
+/// Completes a guardian login with the mailed code or link token and stores
+/// the issued bearer token.
+class AuthGuardianVerify extends MarianumConnectQuery {
+  final MarianumConnectTokenStorage _tokenStorage;
+
+  AuthGuardianVerify({
+    MarianumConnectTokenStorage tokenStorage =
+        const MarianumConnectTokenStorage(),
+    Dio? dio,
+  }) : _tokenStorage = tokenStorage,
+       super(dio: dio ?? MarianumConnectApi.plainDio());
+
+  Future<AuthLoginResponse> run({
+    required String requestId,
+    required String deviceVerifier,
+    required String tokenName,
+    String? code,
+    String? linkToken,
+  }) async {
+    assert((code == null) != (linkToken == null));
+    try {
+      final response = await dio.post<Map<String, dynamic>>(
+        endpoint('auth/guardian/verify'),
+        data: {
+          'requestId': requestId,
+          'deviceVerifier': deviceVerifier,
+          'tokenName': tokenName,
+          'code': ?code,
+          'linkToken': ?linkToken,
+        },
+      );
+      final payload = AuthLoginResponse.fromJson(response.data!);
+      await _tokenStorage.write(
+        token: payload.token,
+        tokenId: payload.tokenId,
+        expiresAt: payload.expiresAt,
+      );
+      return payload;
+    } on DioException catch (e) {
+      throw GuardianLoginException.fromDio(e);
+    }
+  }
+}
@@ -0,0 +1,126 @@
+import 'package:dio/dio.dart';
+
+import '../../../errors/app_exception.dart';
+import '../../errors/marianumconnect_error.dart';
+
+enum GuardianLoginError {
+  invalidRequest,
+  emailNotRegistered,
+  accountDisabled,
+  invalidCode,
+  deviceMismatch,
+  requestConsumed,
+  requestExpired,
+  tooManyAttempts,
+  rateLimited,
+  unsupportedServer,
+}
+
+/// A rejected guardian login step with the reason the server reported.
+class GuardianLoginException extends AppException {
+  final GuardianLoginError error;
+  final int? attemptsLeft;
+
+  const GuardianLoginException(
+    this.error, {
+    required super.userMessage,
+    this.attemptsLeft,
+    super.technicalDetails,
+  }) : super(allowRetry: false);
+
+  /// Maps a failed guardian auth call. Only 4xx answers that carry a guardian
+  /// login reason become [GuardianLoginException]; everything else keeps the
+  /// generic MarianumConnect mapping (network, 5xx, …).
+  static AppException fromDio(DioException e) {
+    final response = e.response;
+    final status = response?.statusCode;
+    if (status == null || status < 400 || status >= 500) {
+      return mapMarianumConnectError(e);
+    }
+    final (code, attemptsLeft) = _parseBody(response!.data);
+    final error = _errorFor(code, status);
+    if (error == null) return mapMarianumConnectError(e);
+    return GuardianLoginException(
+      error,
+      attemptsLeft: attemptsLeft,
+      userMessage: messageFor(error, attemptsLeft: attemptsLeft),
+      technicalDetails: 'MC $status: ${response.data}',
+    );
+  }
+
+  static String messageFor(
+    GuardianLoginError error, {
+    int? attemptsLeft,
+  }) => switch (error) {
+    GuardianLoginError.invalidRequest =>
+      'Bitte gib eine gültige E-Mail-Adresse ein.',
+    GuardianLoginError.emailNotRegistered =>
+      'Unter dieser E-Mail-Adresse ist kein Eltern-Zugang hinterlegt. '
+          'Bitte prüfe, ob die korrekte Adresse verwendet wurde. Bitte wende dich an das Sekretariat, '
+          'wenn du nicht weißt, welche Adresse für dich registriert ist.',
+    GuardianLoginError.accountDisabled =>
+      'Dieser Eltern-Zugang ist derzeit deaktiviert. Bitte wende dich an '
+          'das Sekretariat.',
+    GuardianLoginError.invalidCode =>
+      attemptsLeft == null
+          ? 'Der Code ist falsch.'
+          : 'Der Code ist falsch. Noch $attemptsLeft '
+                '${attemptsLeft == 1 ? 'Versuch' : 'Versuche'}.',
+    GuardianLoginError.deviceMismatch =>
+      'Dieser Anmeldelink wurde auf einem anderen Gerät angefordert. '
+          'Bitte gib stattdessen den Code aus der E-Mail ein.',
+    GuardianLoginError.requestConsumed =>
+      'Diese Anmeldung wurde bereits verwendet. Bitte fordere einen neuen '
+          'Code an.',
+    GuardianLoginError.requestExpired =>
+      'Der Code ist abgelaufen. Bitte fordere einen neuen an.',
+    GuardianLoginError.tooManyAttempts =>
+      'Zu viele Fehlversuche. Bitte fordere einen neuen Code an.',
+    GuardianLoginError.rateLimited =>
+      'Zu viele Anfragen. Bitte warte einige Stunden und versuche es '
+          'erneut.',
+    GuardianLoginError.unsupportedServer =>
+      'Die Eltern-Anmeldung ist auf diesem Server noch nicht verfügbar. '
+          'Bitte versuche es später erneut.',
+  };
+
+  /// Accepts the documented JSON body (`{"error": …, "attemptsLeft": …}`) as
+  /// well as the plain-text `Fehler: <code>` the server's generic error
+  /// handler produces.
+  static (String?, int?) _parseBody(Object? data) {
+    if (data is Map) {
+      final attempts = data['attemptsLeft'];
+      return (data['error'] as String?, attempts is int ? attempts : null);
+    }
+    if (data is String) {
+      final code = data.startsWith('Fehler: ')
+          ? data.substring('Fehler: '.length)
+          : data;
+      return (code.trim(), null);
+    }
+    return (null, null);
+  }
+
+  static GuardianLoginError? _errorFor(String? code, int status) =>
+      switch (code) {
+        'invalid_request' => GuardianLoginError.invalidRequest,
+        'email_not_registered' => GuardianLoginError.emailNotRegistered,
+        'account_disabled' => GuardianLoginError.accountDisabled,
+        'invalid_code' => GuardianLoginError.invalidCode,
+        'device_mismatch' => GuardianLoginError.deviceMismatch,
+        'request_consumed' => GuardianLoginError.requestConsumed,
+        'request_expired' => GuardianLoginError.requestExpired,
+        'too_many_attempts' => GuardianLoginError.tooManyAttempts,
+        _ => switch (status) {
+          401 => GuardianLoginError.invalidCode,
+          // The server names an unknown address explicitly
+          // (`email_not_registered`); a bare 404/405 means the endpoint itself
+          // is missing, i.e. a server version without guardian login.
+          404 || 405 => GuardianLoginError.unsupportedServer,
+          409 => GuardianLoginError.requestConsumed,
+          410 => GuardianLoginError.requestExpired,
+          429 => GuardianLoginError.rateLimited,
+          _ => null,
+        },
+      };
+}