@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

package/dist/templates/frontend/application/src/@aurora/modules/authentication/shared/session-recovery-coordinator.service.spec.ts

@@ -0,0 +1,759 @@
+/**
+ * Tests for `SessionRecoveryCoordinatorService` (design.md Decision 1/2, redesign-session-expiry-recovery).
+ *
+ * Task 2.1 is the change's ACCEPTANCE test: it drives the REAL entry points — the route guard's
+ * `check()` (via `AuthenticationAuroraAdapterService`) AND the real Apollo `ErrorLink` chain — against
+ * a SHARED injector (so both resolve the SAME coordinator singleton) and a REAL `TokenStore`. It
+ * deliberately does NOT import the coordinator class: it exercises the public surface only, so it
+ * stays meaningful (and RED) against the pre-redesign code, where `check()` and the error link each
+ * independently call `signInUsingRefreshToken()`.
+ *
+ * Tasks 2.2-2.4 unit-test the coordinator directly (single flight, per-kind separation, one owner for
+ * terminal sign-out).
+ */
+import '@angular/compiler';
+import { Injector, runInInjectionContext } from '@angular/core';
+import { Router } from '@angular/router';
+import { TranslocoService } from '@jsverse/transloco';
+import { toast } from '@spartan-ng/brain/sonner';
+import { Apollo } from 'apollo-angular';
+import { Observable } from 'rxjs';
+import { AuthenticationAuroraAdapterService } from './adapters/authentication-aurora-adapter.service';
+import { CurrentAccountService } from './current-account.service';
+import { LandingResolverService } from './landing-resolver.service';
+import { SessionRecoveryCoordinatorService } from './session-recovery-coordinator.service';
+import { TokenStore } from './token-store.service';
+
+let toastInfo: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  localStorage.clear();
+  toastInfo = vi.spyOn(toast, 'info').mockImplementation(() => undefined as never);
+});
+
+afterEach(() => {
+  toastInfo.mockRestore();
+  localStorage.clear();
+});
+
+/** Structurally valid JWT with a controllable `exp`. */
+function jwt(payload: Record<string, unknown>, expOffsetSeconds: number): string {
+  const exp = Math.floor(Date.now() / 1000) + expOffsetSeconds;
+  return `${btoa(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))}.${btoa(
+    JSON.stringify({ exp, ...payload }),
+  )}.fake-signature`;
+}
+
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+/** A gated mutate() — resolves only when `release()` is called, so tests can assert call counts
+ * while a grant is still pending. */
+function gatedMutate(result: unknown): { mutate: ReturnType<typeof vi.fn>; release: () => void } {
+  let observer: { next: (v: unknown) => void; complete: () => void } | undefined;
+  const mutate = vi.fn().mockImplementation(
+    () =>
+      new Observable((obs) => {
+        observer = obs;
+      }),
+  );
+  return {
+    mutate,
+    release: () => {
+      observer?.next(result);
+      observer?.complete();
+    },
+  };
+}
+
+describe('SessionRecoveryCoordinatorService — task 2.1 acceptance: one grant across the guard and the error link', () => {
+  it('sends exactly ONE refresh grant when the route guard and an unrelated failed operation both need recovery against the same (both-expired) credential, and neither clears the session nor bounces to sign-in', async () => {
+    const OPERATOR_EXPIRED = jwt({ aci: 'actor-1' }, -60);
+    const IMPERSONATION_EXPIRED = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, -60);
+    const OPERATOR_REFRESHED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+
+    const store = new TokenStore();
+    // Fixture rule: BOTH tokens expired. Operator has a refresh token; the impersonation credential
+    // does NOT (production never issues one for it — design D4).
+    store.setCredentials({ accessToken: OPERATOR_EXPIRED, refreshToken: 'operator-refresh' });
+    store.beginImpersonation({ accessToken: IMPERSONATION_EXPIRED });
+
+    const { mutate, release } = gatedMutate({
+      data: {
+        oAuthCreateToken: { accessToken: OPERATOR_REFRESHED, refreshToken: 'operator-refresh-2' },
+      },
+    });
+    const navigate = vi.fn().mockResolvedValue(true);
+    const load = vi.fn();
+
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load } },
+        // check() never triggers reMaterializeSession (it never navigates — see design.md), so
+        // this is DI plumbing only: AuthenticationAuroraAdapterService's constructor now injects
+        // LandingResolverService unconditionally.
+        { provide: LandingResolverService, useValue: { apply: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+
+    // Entry point 1: the route guard's check(), via the real adapter.
+    const adapter = runInInjectionContext(injector, () => new AuthenticationAuroraAdapterService());
+    const guardResult$ = adapter.check();
+    let guardAuthenticated: boolean | undefined;
+    guardResult$.subscribe((v) => (guardAuthenticated = v));
+
+    // Let the guard's synchronous unwind + recursive refresh call reach the transport.
+    await flush();
+    expect(mutate).toHaveBeenCalledTimes(1);
+
+    // Entry point 2: an unrelated operation fails via the coordinator against the SAME (now-restored
+    // operator, still-expired) credential — it must JOIN the pending grant, not start a second one.
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+    let secondOutcome: string | undefined;
+    coordinator
+      .recoverForOperation(store.identityGeneration())
+      .subscribe((r) => (secondOutcome = r));
+
+    await flush();
+    // Still exactly ONE grant reached the transport.
+    expect(mutate).toHaveBeenCalledTimes(1);
+
+    release();
+    await flush();
+    await flush();
+
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(guardAuthenticated).toBe(true);
+    expect(secondOutcome).toBe('retry');
+    // Session not cleared.
+    expect(store.authenticated()).toBe(true);
+    expect(store.accessToken()).toBe(OPERATOR_REFRESHED);
+    // Operator not sent to sign-in.
+    expect(navigate).not.toHaveBeenCalledWith(['/auth/sign-in']);
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — task 2.2: a recovery requested while a grant is pending joins it', () => {
+  function makeCoordinator(store: TokenStore, mutate: ReturnType<typeof vi.fn>) {
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    return injector.get(SessionRecoveryCoordinatorService);
+  }
+
+  it('two concurrent recoverForOperation calls under the same generation send only ONE grant', async () => {
+    const ACCESS = jwt({ aci: 'actor-1' }, -60);
+    const ROTATED = jwt({ aci: 'actor-1', jti: 'r' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: ACCESS, refreshToken: 'refresh' });
+
+    const { mutate, release } = gatedMutate({
+      data: { oAuthCreateToken: { accessToken: ROTATED, refreshToken: 'refresh-2' } },
+    });
+    const coordinator = makeCoordinator(store, mutate);
+    const gen = store.identityGeneration();
+
+    let a: string | undefined;
+    let b: string | undefined;
+    coordinator.recoverForOperation(gen).subscribe((r) => (a = r));
+    coordinator.recoverForOperation(gen).subscribe((r) => (b = r));
+
+    await flush();
+    expect(mutate).toHaveBeenCalledTimes(1);
+
+    release();
+    await flush();
+    await flush();
+
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(a).toBe('retry');
+    expect(b).toBe('retry');
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — task 2.3: unwind and refresh proceed under separate flights', () => {
+  it('an unwind completes without waiting for a still-pending, unrelated refresh grant', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, -60);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+
+    const { mutate, release } = gatedMutate({
+      data: { oAuthCreateToken: { accessToken: 'unused', refreshToken: 'unused' } },
+    });
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    // Operation A: issued as the operator, access expired, refresh needed — starts the refresh
+    // flight and leaves it PENDING (gated).
+    const genBeforeImpersonation = store.identityGeneration();
+    let refreshOutcome: string | undefined;
+    coordinator.recoverForOperation(genBeforeImpersonation).subscribe((r) => (refreshOutcome = r));
+    await flush();
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(refreshOutcome).toBeUndefined(); // still pending
+
+    // A brand-new impersonation starts and IMMEDIATELY expires; operation B was issued under it.
+    const IMPERSONATION_EXPIRED = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, -60);
+    store.beginImpersonation({ accessToken: IMPERSONATION_EXPIRED });
+    const genImpersonation = store.identityGeneration();
+
+    let unwindOutcome: string | undefined;
+    coordinator.recoverForOperation(genImpersonation).subscribe((r) => (unwindOutcome = r));
+    await flush();
+
+    // The unwind (no network call) completed WITHOUT waiting for the still-gated refresh grant.
+    expect(unwindOutcome).toBe('terminate');
+    expect(store.isImpersonating()).toBe(false);
+    expect(refreshOutcome).toBeUndefined(); // the refresh flight is still pending
+
+    release();
+    await flush();
+    await flush();
+    // The refresh flight eventually settles too (independent of the unwind).
+    expect(['retry', 'terminate']).toContain(refreshOutcome);
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — task 2.4: a terminal sign-out has one owner', () => {
+  it('several operations failing in a session-ending way produce exactly one sign-out and one notice', async () => {
+    const ACCESS = jwt({ aci: 'actor-1' }, -60);
+    const store = new TokenStore();
+    // No refresh token at all — the refresh grant cannot even be attempted, so every caller
+    // reaches the terminal sign-out path.
+    store.setCredentials({ accessToken: ACCESS });
+
+    const mutate = vi.fn();
+    const clearSpy = vi.spyOn(store, 'clear');
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+    const gen = store.identityGeneration();
+
+    const outcomes: string[] = [];
+    coordinator.recoverForOperation(gen).subscribe((r) => outcomes.push(r));
+    coordinator.recoverForOperation(gen).subscribe((r) => outcomes.push(r));
+    coordinator.recoverForOperation(gen).subscribe((r) => outcomes.push(r));
+
+    await flush();
+    await flush();
+
+    expect(mutate).not.toHaveBeenCalled();
+    expect(clearSpy).toHaveBeenCalledTimes(1);
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+    expect(outcomes).toEqual(['terminate', 'terminate', 'terminate']);
+    clearSpy.mockRestore();
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — the terminal sign-out revokes the refresh token server-side', () => {
+  /**
+   * Regression guard. Before the redesign the terminal path ran through
+   * `AuthenticationService.signOut()`, whose own comment promised a "best-effort server revoke".
+   * The coordinator cannot call that method (the adapter delegates `check()` to the coordinator, so
+   * coordinator -> adapter would close a DI cycle inside `authentication`), so the coordinator must
+   * issue the revocation ITSELF. Without it the client ends the session locally while the refresh
+   * token stays usable server-side until its own expiry.
+   *
+   * Fixture rule: the refresh token must be PRESENT and still plausibly valid — that is the only
+   * state where the revocation has anything to revoke. A fixture without a refresh token (as in
+   * task 2.4) can never fail for this defect.
+   */
+  function terminalSetup(revokeResult: 'ok' | 'fail') {
+    const store = new TokenStore();
+    store.setCredentials({
+      accessToken: jwt({ aci: 'actor-1' }, -60),
+      refreshToken: 'live-refresh',
+    });
+
+    const mutate = vi.fn().mockImplementation(
+      () =>
+        new Observable((obs) => {
+          if (revokeResult === 'ok') {
+            obs.next({ data: { oAuthRevokeToken: true } });
+            obs.complete();
+          } else {
+            obs.error(new Error('network down'));
+          }
+        }),
+    );
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    return { store, mutate, coordinator: injector.get(SessionRecoveryCoordinatorService) };
+  }
+
+  it('sends oAuthRevokeToken carrying the refresh token, and clears locally', async () => {
+    const { store, mutate, coordinator } = terminalSetup('ok');
+
+    const outcomes: string[] = [];
+    coordinator.terminate().subscribe((r) => outcomes.push(r));
+    await flush();
+    await flush();
+
+    const revokeCalls = mutate.mock.calls.filter(
+      ([options]) => options.variables?.payload?.token === 'live-refresh',
+    );
+    expect(revokeCalls).toHaveLength(1);
+    expect(store.accessToken()).toBe('');
+    expect(outcomes).toEqual(['terminate']);
+  });
+
+  it('clears locally even when the revocation fails, so a network error never strands a signed-in client', async () => {
+    const { store, mutate, coordinator } = terminalSetup('fail');
+
+    const outcomes: string[] = [];
+    coordinator.terminate().subscribe((r) => outcomes.push(r));
+    await flush();
+    await flush();
+
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(store.accessToken()).toBe('');
+    expect(store.refreshToken()).toBe('');
+    expect(outcomes).toEqual(['terminate']);
+  });
+
+  it('does not attempt a revocation when there is no refresh token to revoke', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, -60) });
+
+    const mutate = vi.fn();
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+
+    injector.get(SessionRecoveryCoordinatorService).terminate().subscribe();
+    await flush();
+    await flush();
+
+    expect(mutate).not.toHaveBeenCalled();
+    expect(store.accessToken()).toBe('');
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — finding 1: the terminal sign-out revokes the OPERATOR token during an impersonated session', () => {
+  /**
+   * Fixture rule: the ACTIVE credential is the impersonation JWT, built WITHOUT a refreshToken
+   * (production never issues one for it — design D4). The STASH holds the operator's own
+   * credentials, which DO carry one. A fixture that gives the impersonation credential a
+   * refreshToken, or that has no stash at all, cannot fail for this defect.
+   */
+  it('unwinds the impersonation before reading the refresh token, so the revocation targets the OPERATOR token and both slots end empty', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, 3600);
+    const IMPERSONATION_ACCESS = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+    store.beginImpersonation({ accessToken: IMPERSONATION_ACCESS }); // no refreshToken
+
+    const mutate = vi.fn().mockImplementation(
+      () =>
+        new Observable((obs) => {
+          obs.next({ data: { oAuthRevokeToken: true } });
+          obs.complete();
+        }),
+    );
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    const outcomes: string[] = [];
+    coordinator.terminate().subscribe((r) => outcomes.push(r));
+    await flush();
+    await flush();
+
+    const revokeCalls = mutate.mock.calls.filter(
+      ([options]) =>
+        (options as { variables?: { payload?: { token?: string } } }).variables?.payload?.token ===
+        'operator-refresh',
+    );
+    expect(revokeCalls).toHaveLength(1);
+    expect(store.hasStashedSession()).toBe(false);
+    expect(store.accessToken()).toBe('');
+    expect(store.refreshToken()).toBe('');
+    expect(outcomes).toEqual(['terminate']);
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — finding 4: the local sign-out does not await the revocation network call', () => {
+  it('clears the store and fires the single notice even when the revocation never settles', async () => {
+    const store = new TokenStore();
+    store.setCredentials({
+      accessToken: jwt({ aci: 'actor-1' }, 3600),
+      refreshToken: 'live-refresh',
+    });
+
+    const { mutate } = gatedMutate({ data: { oAuthRevokeToken: true } }); // release() is never called
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    const outcomes: string[] = [];
+    coordinator.terminate().subscribe((r) => outcomes.push(r));
+    await flush();
+    await flush();
+
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(store.accessToken()).toBe('');
+    expect(store.refreshToken()).toBe('');
+    expect(outcomes).toEqual(['terminate']);
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — finding 3: a grant dropped as stale must revoke its NEW refresh token', () => {
+  /**
+   * The grant already COMPLETED server-side: the backend revoked the OLD pair and issued a NEW
+   * one. `issueRefreshGrant()` correctly refuses to INSTALL a grant whose launch generation no
+   * longer matches, but discarding it silently leaves a valid, unrevoked refresh token with a
+   * 30-day TTL that no client will ever present.
+   *
+   * Fixture rule: the identity must change DURING the round trip — via a real `beginImpersonation`
+   * between the request leaving and its response arriving — so `issueRefreshGrant()` actually
+   * reaches the stale branch instead of the happy path.
+   */
+  it('fires a best-effort revocation of the NEW token when the identity changed mid-flight, and does not install it', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, -60);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+
+    const { mutate, release } = gatedMutate({
+      data: { oAuthCreateToken: { accessToken: 'new-access', refreshToken: 'new-refresh' } },
+    });
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+    const gen = store.identityGeneration();
+
+    let outcome: string | undefined;
+    coordinator.recoverForOperation(gen).subscribe((r) => (outcome = r));
+    await flush();
+    expect(mutate).toHaveBeenCalledTimes(1); // the grant request itself
+
+    // The identity changes WHILE the grant is in flight — a real impersonation swap.
+    const IMPERSONATION_ACCESS = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600);
+    store.beginImpersonation({ accessToken: IMPERSONATION_ACCESS });
+
+    release();
+    await flush();
+    await flush();
+
+    const revokeCalls = mutate.mock.calls.filter(
+      ([options]) =>
+        (options as { variables?: { payload?: { token?: string } } }).variables?.payload?.token ===
+        'new-refresh',
+    );
+    expect(revokeCalls).toHaveLength(1);
+    // The dropped grant's credentials were never installed — the mid-flight impersonation stands.
+    expect(store.accessToken()).toBe(IMPERSONATION_ACCESS);
+    expect(store.isImpersonating()).toBe(true);
+    expect(outcome).toBe('terminate');
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — JD-1: concurrent operations under one stale identity share one notice', () => {
+  /**
+   * Ledger JD-1. Before the fix, `notifyOperationNotCompleted()` fired unconditionally from each of
+   * its three call sites, so N operations invalidated by the SAME identity change each produced their
+   * own toast. Drives the real entry point (`recoverForOperation`) against a real `TokenStore` after
+   * a real identity transition, so all three operations independently take the generation-mismatch
+   * branch (spec.md: "Concurrent failures produce one notice, not one per operation").
+   */
+  it('three operations stamped with a generation invalidated by the same identity change produce exactly ONE OperationNotCompletedNotice, and all three terminate', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'actor-1' }, 3600), refreshToken: 'refresh' });
+    const staleGeneration = store.identityGeneration();
+
+    // A real identity transition invalidates `staleGeneration` for every operation stamped with it.
+    store.beginImpersonation({
+      accessToken: jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600),
+    });
+
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate: vi.fn() } },
+        { provide: Router, useValue: { navigate: vi.fn().mockResolvedValue(true) } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    const outcomes: string[] = [];
+    coordinator.recoverForOperation(staleGeneration).subscribe((r) => outcomes.push(r));
+    coordinator.recoverForOperation(staleGeneration).subscribe((r) => outcomes.push(r));
+    coordinator.recoverForOperation(staleGeneration).subscribe((r) => outcomes.push(r));
+
+    await flush();
+
+    expect(outcomes).toEqual(['terminate', 'terminate', 'terminate']);
+    const staleNoticeCalls = toastInfo.mock.calls.filter(
+      (call: unknown[]) => call[0] === 'navigation.Session.OperationNotCompletedNotice',
+    );
+    expect(staleNoticeCalls).toHaveLength(1);
+    // Total count, not just the filtered one — an unexpected extra notice on a different key
+    // must not be able to hide behind the filter.
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — finding 2: terminate() must not destroy a session the stamped operation was never issued under', () => {
+  /**
+   * Sequence: the operator is impersonating; operation X is sent stamped generation N; the
+   * operator stops the impersonation (a synchronous swap — their OWN valid session becomes active
+   * under generation N+1); X's late response arrives on the `alreadyRetried` branch, which calls
+   * `terminate(N)`. A stale N must NOT be allowed to sign out the now-current, unrelated,
+   * perfectly valid session.
+   *
+   * `alreadyRetried` is now the ONLY caller that passes a generation. The `isRefreshInvalid`
+   * branch that used to be the second one was removed: it classified a 404 `OAuthRefreshToken`
+   * as an unrecoverable auth failure, but the only producers of that shape are the o-auth
+   * refresh-token ADMIN CRUD handlers, so it fired solely as a false positive. The Basic-operation
+   * call site still passes NO generation, deliberately, so the optional parameter still earns its
+   * keep — see the regression test that pins that asymmetry.
+   *
+   * Caveat worth knowing before anyone "simplifies" the optional parameter away: a security review
+   * observed that `alreadyRetried` may be effectively UNREACHABLE in production, because Apollo v4's
+   * `forward()` re-emission does not re-enter the error link, so a retried operation's second
+   * failure never arrives there. If that holds, this test is the only thing exercising the
+   * generation guard at all. That makes it MORE load-bearing, not less — do not delete it on the
+   * grounds that its production caller looks dead.
+   */
+  it('leaves the store untouched, sends no revocation, and does not navigate when the stamped generation is stale', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+
+    const IMPERSONATION_ACCESS = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600);
+    store.beginImpersonation({ accessToken: IMPERSONATION_ACCESS });
+    const staleGeneration = store.identityGeneration(); // generation N — stamped when X was sent
+
+    // The operator stops impersonating SYNCHRONOUSLY — their own valid session is active again.
+    store.endImpersonation();
+
+    const mutate = vi.fn();
+    const navigate = vi.fn().mockResolvedValue(true);
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    const outcome = await new Promise((resolve) =>
+      coordinator.terminate(staleGeneration).subscribe(resolve),
+    );
+
+    expect(outcome).toBe('terminate');
+    expect(mutate).not.toHaveBeenCalled();
+    expect(store.accessToken()).toBe(OPERATOR_ACCESS); // the operator's valid session survives
+    expect(navigate).not.toHaveBeenCalled();
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+  });
+
+  it('still terminates when the stamped generation matches the current one (no regression on the real defect)', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'actor-1' }, 3600), refreshToken: 'refresh' });
+    const gen = store.identityGeneration();
+
+    const mutate = vi.fn().mockImplementation(
+      () =>
+        new Observable((obs) => {
+          obs.next({ data: { oAuthRevokeToken: true } });
+          obs.complete();
+        }),
+    );
+    const navigate = vi.fn().mockResolvedValue(true);
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load: vi.fn() } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    const outcome = await new Promise((resolve) => coordinator.terminate(gen).subscribe(resolve));
+
+    expect(outcome).toBe('terminate');
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(store.accessToken()).toBe('');
+    expect(navigate).toHaveBeenCalledWith(['/auth/sign-in']);
+  });
+});
+
+describe('SessionRecoveryCoordinatorService — an impersonation with no session to restore ends as a normal sign-out', () => {
+  /**
+   * Spec scenario "An impersonation with no session to restore ends as a normal sign-out".
+   * Fixture rule: an ACTIVE, EXPIRED impersonation credential built with `setCredentials` DIRECTLY
+   * (never `beginImpersonation`, which would create the stash this scenario must NOT have).
+   * `isImpersonating()` stays true — it derives from the actor claim, not from validity or the
+   * stash — which is exactly what makes this branch reachable.
+   */
+  function noStashFixture() {
+    const IMPERSONATION_EXPIRED_NO_STASH = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, -60);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: IMPERSONATION_EXPIRED_NO_STASH });
+    expect(store.isImpersonating()).toBe(true);
+    expect(store.hasStashedSession()).toBe(false);
+
+    const mutate = vi.fn();
+    const navigate = vi.fn().mockResolvedValue(true);
+    const load = vi.fn();
+    const injector = Injector.create({
+      providers: [
+        { provide: TokenStore, useValue: store },
+        { provide: Apollo, useValue: { mutate } },
+        { provide: Router, useValue: { navigate } },
+        { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+        { provide: CurrentAccountService, useValue: { load } },
+        SessionRecoveryCoordinatorService,
+      ],
+    });
+    return {
+      store,
+      mutate,
+      navigate,
+      load,
+      coordinator: injector.get(SessionRecoveryCoordinatorService),
+    };
+  }
+
+  it('recoverForOperation (error-link path) signs out with the NoStashedSession notice, navigates to sign-in, and does not repeat the rollback on a later operation stamped with the same doomed generation', async () => {
+    const { store, mutate, navigate, load, coordinator } = noStashFixture();
+    const generation = store.identityGeneration();
+
+    const outcome = await new Promise((resolve) =>
+      coordinator.recoverForOperation(generation).subscribe(resolve),
+    );
+
+    expect(outcome).toBe('terminate');
+    // Both slots end cleared.
+    expect(store.authenticated()).toBe(false);
+    expect(store.hasStashedSession()).toBe(false);
+    // The dead-end unwind never restored anything, so session-scoped state was never reloaded.
+    expect(load).not.toHaveBeenCalled();
+    // No refresh grant, no revocation attempt — there is no refresh token to act on.
+    expect(mutate).not.toHaveBeenCalled();
+    // Error-link path DOES navigate on a terminal sign-out.
+    expect(navigate).toHaveBeenCalledWith(['/auth/sign-in']);
+    // Exactly ONE notice, and it is the NoStashedSession key — never the ExpiredNotice one.
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+    expect(toastInfo).toHaveBeenCalledWith('navigation.Impersonation.NoStashedSessionNotice');
+    expect(toastInfo).not.toHaveBeenCalledWith('navigation.Session.ExpiredNotice');
+
+    // Second half of the scenario: a LATER operation, stamped with the SAME (now-doomed)
+    // generation the first one carried, must not re-attempt the rollback nor fire a second
+    // NoStashedSession notice — the generation guard alone stops it from reaching that branch.
+    navigate.mockClear();
+    const secondOutcome = await new Promise((resolve) =>
+      coordinator.recoverForOperation(generation).subscribe(resolve),
+    );
+
+    expect(secondOutcome).toBe('terminate');
+    const noStashedCalls = toastInfo.mock.calls.filter(
+      (call: unknown[]) => call[0] === 'navigation.Impersonation.NoStashedSessionNotice',
+    );
+    expect(noStashedCalls).toHaveLength(1); // still exactly one — no repeat
+    expect(navigate).not.toHaveBeenCalled(); // no second sign-in redirect
+    expect(mutate).not.toHaveBeenCalled(); // still no network activity
+    // TOTAL count, not just the filtered one: the first call's sign-out clears the store, which
+    // itself advances identityGeneration (the `(account, actor)` tuple goes from impersonated to
+    // null). The second call's `generation` is therefore ALSO stale by the time it runs, so it
+    // correctly takes the mismatch branch and fires its OWN, DIFFERENT notice
+    // (OperationNotCompletedNotice) — a legitimate second event, not a repeat of the first. This is
+    // a distinct guarantee from "does not repeat the rollback": that one is about the NoStashedSession
+    // branch/notice not firing twice, not about zero notices on the second call.
+    expect(toastInfo).toHaveBeenCalledTimes(2);
+  });
+
+  it('recoverForGuard (guard path) signs out with the NoStashedSession notice, returns false, and never navigates — check() runs inside canActivate', async () => {
+    const { store, mutate, navigate, load, coordinator } = noStashFixture();
+
+    const result = await new Promise((resolve) => coordinator.recoverForGuard().subscribe(resolve));
+
+    expect(result).toBe(false);
+    expect(store.authenticated()).toBe(false);
+    expect(store.hasStashedSession()).toBe(false);
+    expect(load).not.toHaveBeenCalled();
+    expect(mutate).not.toHaveBeenCalled();
+    // Guard path MUST stay navigation-free — the router resolves the redirect on a `false`.
+    expect(navigate).not.toHaveBeenCalled();
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+    expect(toastInfo).toHaveBeenCalledWith('navigation.Impersonation.NoStashedSessionNotice');
+    expect(toastInfo).not.toHaveBeenCalledWith('navigation.Session.ExpiredNotice');
+  });
+});