feat(authentication): refactor account linking and route protection

- Create new top-level route for account linking
- Implement modal presentation for account linking flow
- Simplify authentication page by removing linking context parameters
- Enhance route protection logic for better clarity and security
- Update routing structure for improved maintainability

Author: fulleni

lib/router/router.dart

@@ -18,6 +18,7 @@ import 'package:flutter_news_app_mobile_client_full_source_code/ads/models/ad_th
 import 'package:flutter_news_app_mobile_client_full_source_code/app/bloc/app_bloc.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/app/view/app_shell.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/authentication/bloc/authentication_bloc.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/authentication/view/account_linking_page.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/authentication/view/authentication_page.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/authentication/view/email_code_verification_page.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/authentication/view/request_code_page.dart';
@@ -86,6 +87,8 @@ GoRouter createRouter({
       // Add any other necessary observers here. If none, this can be an empty list.
     ],
     // --- Redirect Logic ---
+    // This function is the single source of truth for route protection.
+    // It's driven by the AppBloc's AppLifeCycleStatus.
     redirect: (BuildContext context, GoRouterState state) {
       final appStatus = context.read<AppBloc>().state.status;
       final currentLocation = state.matchedLocation;
@@ -98,141 +101,86 @@ GoRouter createRouter({
 
       const rootPath = '/';
       const authenticationPath = Routes.authentication;
+      const accountLinkingPath = Routes.accountLinking;
       const feedPath = Routes.feed;
       final isGoingToAuth = currentLocation.startsWith(authenticationPath);
-
-      // With the current App startup architecture, the router is only active when
-      // the app is in a stable, running state. The `redirect` function's
-      // only responsibility is to handle auth-based route protection.
-      // States like `configFetching`, `underMaintenance`, etc., are now
-      // handled by the root App widget *before* this router is ever built.
+      final isGoingToLinking = currentLocation.startsWith(accountLinkingPath);
 
       // --- Case 1: Unauthenticated User ---
-      // If the user is unauthenticated, they should be on an auth path.
-      // If they are trying to access any other part of the app, redirect them.
+      // If the user is unauthenticated, they must be on an auth path.
+      // If they try to go anywhere else, they are redirected to the sign-in page.
       if (appStatus == AppLifeCycleStatus.unauthenticated) {
         print('  Redirect: User is unauthenticated.');
-        // If they are already on an auth path, allow it. Otherwise, redirect.
         return isGoingToAuth ? null : authenticationPath;
       }
 
-      // --- Case 2: Anonymous or Authenticated User ---
-      // If a user is anonymous or authenticated, they should not be able to
-      // access the main authentication flows, with an exception for account
-      // linking for anonymous users.
-      if (appStatus == AppLifeCycleStatus.anonymous ||
-          appStatus == AppLifeCycleStatus.authenticated) {
-        print('  Redirect: User is $appStatus.');
-
-        // If the user is trying to access an authentication path:
+      // --- Case 2: Anonymous User ---
+      // An anonymous user is partially authenticated. They can browse the app.
+      if (appStatus == AppLifeCycleStatus.anonymous) {
+        print('  Redirect: User is anonymous.');
+        // Block anonymous users from the main sign-in page.
         if (isGoingToAuth) {
-          // A fully authenticated user should never see auth pages.
-          if (appStatus == AppLifeCycleStatus.authenticated) {
-            print(
-              '    Action: Authenticated user on auth path. Redirecting to feed.',
-            );
-            return feedPath;
-          }
-
-          // An anonymous user is only allowed on auth paths for account linking.
-          final isLinking =
-              state.uri.queryParameters['context'] == 'linking' ||
-              currentLocation.contains('/linking/');
-
-          if (isLinking) {
-            print('    Action: Anonymous user on linking path. Allowing.');
-            return null;
-          } else {
-            print(
-              '    Action: Anonymous user on non-linking auth path. Redirecting to feed.',
-            );
-            return feedPath;
-          }
+          print(
+            '    Action: Anonymous user on auth path. Redirecting to feed.',
+          );
+          return feedPath;
         }
+        // If at the root, send them to the feed.
+        if (currentLocation == rootPath) {
+          print('    Action: User at root. Redirecting to feed.');
+          return feedPath;
+        }
+        // Allow navigation to other pages, including the new linking page.
+        return null;
+      }
 
-        // If the user is at the root path, they should be sent to the feed.
+      // --- Case 3: Authenticated User ---
+      // A fully authenticated user should be blocked from all auth/linking pages.
+      if (appStatus == AppLifeCycleStatus.authenticated) {
+        print('  Redirect: User is authenticated.');
+        if (isGoingToAuth || isGoingToLinking) {
+          print(
+            '    Action: Authenticated user on auth/linking path. Redirecting to feed.',
+          );
+          return feedPath;
+        }
+        // If at the root, send them to the feed.
         if (currentLocation == rootPath) {
           print('    Action: User at root. Redirecting to feed.');
           return feedPath;
         }
       }
 
       // --- Fallback ---
-      // For any other case, allow navigation.
+      // For any other case (or if no conditions are met), allow navigation.
       print('  Redirect: No condition met. Allowing navigation.');
       return null;
     },
     // --- Authentication Routes ---
     routes: [
       // A neutral root route that the app starts on. The redirect logic will
-      // immediately move the user to the correct location. This route's
-      // builder will never be called in practice.
+      // immediately move the user to the correct location.
       GoRoute(path: '/', builder: (context, state) => const SizedBox.shrink()),
+      // --- Simplified Authentication Route for New Users ---
       GoRoute(
         path: Routes.authentication,
         name: Routes.authenticationName,
         builder: (BuildContext context, GoRouterState state) {
-          final l10n = context.l10n;
-          // Determine context from query parameter
-          final isLinkingContext =
-              state.uri.queryParameters['context'] == 'linking';
-
-          // Define content based on context
-          final String headline;
-          final String subHeadline;
-          final bool showAnonymousButton;
-
-          if (isLinkingContext) {
-            headline = l10n.authenticationLinkingHeadline;
-            subHeadline = l10n.authenticationLinkingSubheadline;
-            showAnonymousButton = false;
-          } else {
-            headline = l10n.authenticationSignInHeadline;
-            subHeadline = l10n.authenticationSignInSubheadline;
-            showAnonymousButton = true;
-          }
-
+          // This page is now self-contained and doesn't need parameters.
+          // It's only for truly unauthenticated users.
           return BlocProvider(
             create: (context) => AuthenticationBloc(
               authenticationRepository: context.read<AuthRepository>(),
             ),
-            child: AuthenticationPage(
-              headline: headline,
-              subHeadline: subHeadline,
-              showAnonymousButton: showAnonymousButton,
-              isLinkingContext: isLinkingContext,
-            ),
+            child: const AuthenticationPage(),
           );
         },
         routes: [
-          // Nested route for account linking flow (defined first for priority)
-          GoRoute(
-            path: Routes.accountLinking,
-            name: Routes.accountLinkingName,
-            builder: (context, state) => const SizedBox.shrink(),
-            routes: [
-              GoRoute(
-                path: Routes.requestCode,
-                name: Routes.linkingRequestCodeName,
-                builder: (context, state) =>
-                    const RequestCodePage(isLinkingContext: true),
-              ),
-              GoRoute(
-                path: '${Routes.verifyCode}/:email',
-                name: Routes.linkingVerifyCodeName,
-                builder: (context, state) {
-                  final email = state.pathParameters['email']!;
-                  return EmailCodeVerificationPage(email: email);
-                },
-              ),
-            ],
-          ),
-          // Non-linking authentication routes (defined after linking routes)
+          // Sub-routes for the standard sign-in flow.
           GoRoute(
             path: Routes.requestCode,
             name: Routes.requestCodeName,
-            builder: (context, state) =>
-                const RequestCodePage(isLinkingContext: false),
+            builder: (context, state) => const RequestCodePage(),
           ),
           GoRoute(
             path: '${Routes.verifyCode}/:email',
@@ -244,9 +192,40 @@ GoRouter createRouter({
           ),
         ],
       ),
+      // --- New Top-Level Modal Route for Account Linking ---
+      GoRoute(
+        path: Routes.accountLinking,
+        name: Routes.accountLinkingName,
+        // Use pageBuilder to create a modal (fullscreen dialog) presentation.
+        pageBuilder: (context, state) {
+          return MaterialPage(
+            fullscreenDialog: true,
+            child: BlocProvider(
+              create: (context) => AuthenticationBloc(
+                authenticationRepository: context.read<AuthRepository>(),
+              ),
+              child: const AccountLinkingPage(),
+            ),
+          );
+        },
+        routes: [
+          // Nested routes for the account linking email/code flow.
+          GoRoute(
+            path: Routes.requestCode,
+            name: Routes.accountLinkingRequestCodeName,
+            builder: (context, state) => const RequestCodePage(),
+          ),
+          GoRoute(
+            path: '${Routes.verifyCode}/:email',
+            name: Routes.accountLinkingVerifyCodeName,
+            builder: (context, state) {
+              final email = state.pathParameters['email']!;
+              return EmailCodeVerificationPage(email: email);
+            },
+          ),
+        ],
+      ),
       // --- Entity Details Route (Top Level) ---
-      // This route handles displaying details for various content entities
-      // (Topic, Source, Country) based on path parameters.
       GoRoute(
         path: Routes.entityDetails,
         name: Routes.entityDetailsName,
@@ -300,29 +279,6 @@ GoRouter createRouter({
         },
       ),
       // --- Global Article Details Route (Top Level) ---
-      // This GoRoute provides a top-level, globally accessible way to view the
-      // HeadlineDetailsPage.
-      //
-      // Purpose:
-      // It is specifically designed for navigating to article details from contexts
-      // that are *outside* the main StatefulShellRoute's branches (e.g., from
-      // EntityDetailsPage, which is itself a top-level route, or potentially
-      // from other future top-level pages or deep links).
-      //
-      // Why it's necessary:
-      // Attempting to push a route that is deeply nested within a specific shell
-      // branch (like '/feed/article/:id') from a BuildContext outside of that
-      // shell can lead to navigator context issues and assertion failures.
-      // This global route avoids such problems by providing a clean, direct path
-      // to the HeadlineDetailsPage.
-      //
-      // How it differs:
-      // This route is distinct from the article detail routes nested within the
-      // StatefulShellRoute branches (e.g., Routes.articleDetailsName under /feed,
-      // Routes.searchArticleDetailsName under /search). Those nested routes are
-      // intended for navigation *within* their respective shell branches,
-      // preserving the shell's UI (like the bottom navigation bar).
-      // This global route, being top-level, will typically cover the entire screen.
       GoRoute(
         path: Routes.globalArticleDetails,
         name: Routes.globalArticleDetailsName,

lib/router/routes.dart

@@ -50,7 +50,9 @@ abstract final class Routes {
   static const resetPasswordName = 'resetPassword';
   static const confirmEmail = 'confirm-email';
   static const confirmEmailName = 'confirmEmail';
-  static const accountLinking = 'linking';
+
+  // Top-level account linking route
+  static const accountLinking = '/account-linking';
   static const accountLinkingName = 'accountLinking';
 
   // routes for email code verification flow
@@ -59,11 +61,9 @@ abstract final class Routes {
   static const verifyCode = 'verify-code';
   static const verifyCodeName = 'verifyCode';
 
-  // Linking-specific authentication routes
-  static const linkingRequestCode = 'linking/request-code';
-  static const linkingRequestCodeName = 'linkingRequestCode';
-  static const linkingVerifyCode = 'linking/verify-code';
-  static const linkingVerifyCodeName = 'linkingVerifyCode';
+  // Linking-specific authentication routes (now nested under accountLinking)
+  static const accountLinkingRequestCodeName = 'accountLinkingRequestCode';
+  static const accountLinkingVerifyCodeName = 'accountLinkingVerifyCode';
 
   // --- Settings Sub-Routes (relative to /account/settings) ---
   static const settingsAppearance = 'appearance';
@@ -86,10 +86,6 @@ abstract final class Routes {
   static const settingsLanguage = 'language';
   static const settingsLanguageName = 'settingsLanguage';
 
-  // Add names for notification sub-selection routes if needed later
-  // static const settingsNotificationCategories = 'categories';
-  // static const settingsNotificationCategoriesName = 'settingsNotificationCategories';
-
   // --- Account Sub-Routes (relative to /account) ---
   static const manageFollowedItems = 'manage-followed-items';
   static const manageFollowedItemsName = 'manageFollowedItems';