WEB-956: preserve deep-link after login redirect

Currently when an unauthenticated user opens a deep link (e.g. /clients/1
from a bookmark, a shared URL or an email), AuthenticationGuard logs the
user out and navigates to /login with replaceUrl:true. Because the guard
does not propagate the originally requested URL and LoginComponent
unconditionally navigates to "/" after a successful authentication, the
user always lands on the home dashboard instead of the page they were
trying to reach.

This change:

- AuthenticationGuard.canActivate now accepts RouterStateSnapshot and
  forwards state.url as a returnUrl query parameter when the target is a
  meaningful route (i.e. not "/" nor "/login", which would otherwise
  cause noise or redirect loops).

- LoginComponent reads queryParamMap.get('returnUrl') from the
  ActivatedRoute when the authentication success alert fires, and
  navigates there via navigateByUrl. Falls back to "/" when no
  returnUrl is present, preserving the previous behavior for the
  ordinary login flow.

- Adds unit tests covering: authenticated pass-through, deep-link
  capture, "/" and "/login" being skipped to avoid loops/noise, and
  complex URLs with query params and fragments.

Verified end to end against an isolated docker-compose stack
(postgres + fineract + web-app):

  before: /#/clients -> /#/login -> /#/home              (bug)
  after:  /#/clients -> /#/login?returnUrl=/clients -> /#/clients

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Jonattan Infante

src/app/core/authentication/authentication.guard.spec.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright since 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+import { TestBed } from '@angular/core/testing';
+import { ActivatedRouteSnapshot, Router, RouterStateSnapshot } from '@angular/router';
+
+import { AuthenticationGuard } from './authentication.guard';
+import { AuthenticationService } from './authentication.service';
+
+describe('AuthenticationGuard', () => {
+  let guard: AuthenticationGuard;
+  let authServiceMock: jest.Mocked<Pick<AuthenticationService, 'isAuthenticated' | 'logout'>>;
+  let routerMock: jest.Mocked<Pick<Router, 'navigate'>>;
+
+  const buildState = (url: string): RouterStateSnapshot => ({ url }) as RouterStateSnapshot;
+  const emptyRoute = {} as ActivatedRouteSnapshot;
+
+  beforeEach(() => {
+    authServiceMock = {
+      isAuthenticated: jest.fn(),
+      logout: jest.fn()
+    };
+    routerMock = { navigate: jest.fn() };
+
+    TestBed.configureTestingModule({
+      providers: [
+        AuthenticationGuard,
+        { provide: AuthenticationService, useValue: authServiceMock },
+        { provide: Router, useValue: routerMock }]
+    });
+
+    guard = TestBed.inject(AuthenticationGuard);
+  });
+
+  it('allows the route when user is authenticated', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(true);
+    const result = guard.canActivate(emptyRoute, buildState('/clients'));
+    expect(result).toBe(true);
+    expect(routerMock.navigate).not.toHaveBeenCalled();
+    expect(authServiceMock.logout).not.toHaveBeenCalled();
+  });
+
+  it('redirects to /login with returnUrl when target is a deep link', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    const result = guard.canActivate(emptyRoute, buildState('/clients/1/general'));
+    expect(result).toBe(false);
+    expect(authServiceMock.logout).toHaveBeenCalledTimes(1);
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], {
+      queryParams: { returnUrl: '/clients/1/general' },
+      replaceUrl: true
+    });
+  });
+
+  it('redirects to /login WITHOUT returnUrl when target is "/" (default landing)', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    guard.canActivate(emptyRoute, buildState('/'));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], { queryParams: {}, replaceUrl: true });
+  });
+
+  it('redirects to /login WITHOUT returnUrl when target is already /login (avoids loops)', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    guard.canActivate(emptyRoute, buildState('/login'));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], { queryParams: {}, replaceUrl: true });
+  });
+
+  it('redirects to /login WITHOUT returnUrl when target is /login with stale params', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    guard.canActivate(emptyRoute, buildState('/login?returnUrl=/foo'));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], { queryParams: {}, replaceUrl: true });
+  });
+
+  it('preserves complex URLs with query params and fragments', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    const target = '/loans/42?tab=schedule#repayment';
+    guard.canActivate(emptyRoute, buildState(target));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], {
+      queryParams: { returnUrl: target },
+      replaceUrl: true
+    });
+  });
+});

src/app/core/authentication/authentication.guard.ts

@@ -8,7 +8,7 @@
 
 /** Angular Imports */
 import { Injectable, inject } from '@angular/core';
-import { Router } from '@angular/router';
+import { ActivatedRouteSnapshot, Router, RouterStateSnapshot } from '@angular/router';
 
 /** Custom Services */
 import { Logger } from '../logger/logger.service';
@@ -26,18 +26,34 @@ export class AuthenticationGuard {
   private authenticationService = inject(AuthenticationService);
 
   /**
-   * Ensures route access is authorized only when user is authenticated, otherwise redirects to login.
+   * Ensures route access is authorized only when user is authenticated.
    *
+   * If unauthenticated, redirects to /login while preserving the originally
+   * requested URL in the `returnUrl` query param so the LoginComponent can
+   * restore it after a successful authentication.
+   *
+   * @param _route Activated route snapshot (unused, kept for guard signature).
+   * @param state  Router state — provides the URL the user was trying to reach.
    * @returns {boolean} True if user is authenticated.
    */
-  canActivate(): boolean {
+  canActivate(_route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {
     if (this.authenticationService.isAuthenticated()) {
       return true;
     }
 
-    log.debug('User not authenticated, redirecting to login...');
+    log.debug(`User not authenticated, redirecting to login (target was: ${state.url})...`);
     this.authenticationService.logout();
-    this.router.navigate(['/login'], { replaceUrl: true });
+
+    // Preserve the originally requested URL so the user can be sent back
+    // there after authenticating. We only forward non-trivial targets
+    // (avoid carrying "/" or "/login" as the returnUrl).
+    const targetUrl = state.url;
+    const isMeaningfulTarget = targetUrl && targetUrl !== '/' && !targetUrl.startsWith('/login');
+
+    this.router.navigate(['/login'], {
+      queryParams: isMeaningfulTarget ? { returnUrl: targetUrl } : {},
+      replaceUrl: true
+    });
     return false;
   }
 }

src/app/login/login.component.ts

@@ -8,7 +8,7 @@
 
 /** Angular Imports */
 import { ChangeDetectionStrategy, Component, OnInit, OnDestroy, inject } from '@angular/core';
-import { Router } from '@angular/router';
+import { ActivatedRoute, Router } from '@angular/router';
 
 /** rxjs Imports */
 
@@ -86,6 +86,7 @@ export class LoginComponent implements OnInit, OnDestroy {
   private settingsService = inject(SettingsService);
   private themingService = inject(ThemingService);
   private router = inject(Router);
+  private activatedRoute = inject(ActivatedRoute);
 
   private versionService = inject(VersionService);
   private translateService = inject(TranslateService);
@@ -143,7 +144,10 @@ export class LoginComponent implements OnInit, OnDestroy {
       } else if (alertType === this.translateService.instant('errors.auth.success.type')) {
         this.resetPassword = false;
         this.twoFactorAuthenticationRequired = false;
-        this.router.navigate(['/'], { replaceUrl: true });
+        const returnUrl = this.activatedRoute.snapshot.queryParamMap.get('returnUrl');
+        // Restore the originally requested deep link if the AuthenticationGuard captured one.
+        // Falls back to root (default landing) when no returnUrl is present.
+        this.router.navigateByUrl(returnUrl || '/', { replaceUrl: true });
       } else if (alertType === this.translateService.instant('errors.tenant.changed.type')) {
         this.updateLogo();
       }