@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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

@@ -0,0 +1,310 @@
+import { inject, Injectable } 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 { firstValueFrom, from, Observable } from 'rxjs';
+import { oAuthCreateToken, oAuthRevokeToken } from '../data-access/authentication.graphql';
+import { isTokenExpired } from './authentication';
+import { ClientGrantType, type OAuthTokens } from './authentication.types';
+import { CurrentAccountService } from './current-account.service';
+import { TokenStore } from './token-store.service';
+
+/** What the coordinator tells a caller about an operation it reported a failure for. */
+export type RecoveryOutcome = 'retry' | 'terminate';
+
+/**
+ * The single owner of "a credential is no longer usable" (design.md Decision 1/2,
+ * redesign-session-expiry-recovery). It owns exactly three things:
+ *
+ * (a) THE SINGLE FLIGHT — one pending operation per recovery KIND (refresh grant, impersonation
+ *     unwind, terminal sign-out), shared by every caller. The latch is the PENDING PROMISE a later
+ *     caller awaits, never a boolean reset on completion.
+ * (b) THE DECISION — is the credential impersonated; is it expired; is a stash present; is a
+ *     refresh token present; does the operation's identity generation still match.
+ * (c) THE USER-FACING OUTCOME — exactly one notice per recovery event, on the coordinator's single
+ *     exit (inside the flight body), never on a branch — so adding a branch cannot remove it.
+ *
+ * MAY inject `TokenStore` and `Apollo` eagerly (design.md constraint 2): it lives on the
+ * `authentication` side of the `graphql → authentication` edge, so this does not create the
+ * `Apollo ↔ AuthenticationService ↔ Apollo` cycle the `graphql` side must avoid. The `graphql` side
+ * (the Apollo `ErrorLink`) MUST resolve this service LAZILY through a captured `Injector` instead.
+ */
+@Injectable()
+export class SessionRecoveryCoordinatorService {
+  private readonly tokenStore = inject(TokenStore);
+  private readonly apollo = inject(Apollo);
+  private readonly router = inject(Router);
+  private readonly transloco = inject(TranslocoService);
+  private readonly currentAccount = inject(CurrentAccountService);
+
+  private refreshFlight: Promise<boolean> | null = null;
+  private unwindFlight: Promise<boolean> | null = null;
+  private signOutFlight: Promise<void> | null = null;
+  /**
+   * The identity generation the last "operation not completed" notice was issued for. This outcome
+   * has no shared flight of its own (unlike the other three), so the dedup has to live here instead:
+   * `identityGeneration` is monotonic, so ONE number is enough to remember "already notified for the
+   * CURRENT identity" — no unbounded set needed. Operations stamped with several DIFFERENT stale
+   * generations that all surface after the SAME identity change read the SAME current generation,
+   * which is why the key is the CURRENT value, not the generation each operation was stamped with.
+   */
+  private staleNoticeGeneration: number | null = null;
+
+  /**
+   * Delegation point for the route guard's `check()`. Reads `TokenStore` live and decides:
+   * retry as-is, refresh, unwind, or terminate. NEVER navigates — `check()` runs inside
+   * `canActivate`, so the router (not this method) resolves the redirect on a `false`.
+   */
+  recoverForGuard(): Observable<boolean> {
+    return from(this.recoverForGuardAsync());
+  }
+
+  private async recoverForGuardAsync(): Promise<boolean> {
+    const access = this.tokenStore.accessToken();
+
+    if (!access) {
+      // Never authenticated (or already cleared) — not a recovery event, no notice.
+      this.tokenStore.clear();
+      return false;
+    }
+
+    if (this.tokenStore.isImpersonating()) {
+      if (!isTokenExpired(access)) return true;
+
+      const restored = await this.runUnwindFlight();
+      if (!restored) {
+        await this.runSignOutFlight('navigation.Impersonation.NoStashedSessionNotice');
+        return false;
+      }
+      // The restored operator session may ALSO be expired (the common case). Re-entrant by
+      // design and provably bounded: `endImpersonation` consumes the single stash slot, so the
+      // recursive pass either evaluates a normal session or finds no stash and stops. It joins
+      // the SAME shared refresh flight below rather than starting a second one.
+      return this.recoverForGuardAsync();
+    }
+
+    const refresh = this.tokenStore.refreshToken();
+    if (!refresh) {
+      this.tokenStore.clear();
+      return false;
+    }
+
+    if (!isTokenExpired(access)) return true;
+
+    const refreshed = await this.runRefreshFlight();
+    if (refreshed) return true;
+
+    await this.runSignOutFlight('navigation.Session.ExpiredNotice');
+    return false;
+  }
+
+  /**
+   * Delegation point for the Apollo `ErrorLink` on an access-expiry 401. `stampedGeneration` is
+   * the identity generation `headersLink` stamped on the operation when it was SENT. ALWAYS
+   * navigates to `/auth/sign-in` on a terminal sign-out (constraint 4's ErrorLink-side behavior);
+   * an impersonation unwind never navigates (the operator stays in the app under their own
+   * session).
+   */
+  recoverForOperation(stampedGeneration: number): Observable<RecoveryOutcome> {
+    return from(this.recoverForOperationAsync(stampedGeneration));
+  }
+
+  private async recoverForOperationAsync(stampedGeneration: number): Promise<RecoveryOutcome> {
+    if (stampedGeneration !== this.tokenStore.identityGeneration()) {
+      // The identity this operation was issued under is already gone. Never retry, never unwind
+      // the CURRENT (different) identity — that is the mirror-case and the late-failure case
+      // (frontend-account-impersonation spec: "not re-sent under a new impersonation" /
+      // "a late failure does not unwind a different impersonation").
+      this.notifyOperationNotCompleted();
+      return 'terminate';
+    }
+
+    if (this.tokenStore.isImpersonating()) {
+      // Generation matches, so a live read of isImpersonating() is authoritative (Decision 3).
+      // This SPECIFIC operation is never retried — it was authored inside the target's session;
+      // replaying it under the operator's identity would carry no actor claim and no audit trail.
+      const restored = await this.runUnwindFlight();
+      if (!restored) {
+        await this.runSignOutFlight('navigation.Impersonation.NoStashedSessionNotice');
+        void this.router.navigate(['/auth/sign-in']);
+      }
+      return 'terminate';
+    }
+
+    const refreshed = await this.runRefreshFlight();
+
+    // Re-check the generation IMMEDIATELY BEFORE authorizing the re-send: the refresh was a
+    // network round trip, and an impersonation can have become active while it was in flight
+    // (the re-send window this task closes). This also protects the case where the grant
+    // succeeded but was dropped as stale by runRefreshFlight() — either way, this operation
+    // must not be retried under an identity it was never issued for.
+    if (stampedGeneration !== this.tokenStore.identityGeneration()) {
+      this.notifyOperationNotCompleted();
+      return 'terminate';
+    }
+
+    if (refreshed) return 'retry';
+
+    await this.runSignOutFlight('navigation.Session.ExpiredNotice');
+    void this.router.navigate(['/auth/sign-in']);
+    return 'terminate';
+  }
+
+  /**
+   * Direct terminal sign-out — for operations the `ErrorLink` never attempts recovery for at all
+   * (a Basic-credentials operation, or one already retried once / a stale refresh token).
+   *
+   * `stampedGeneration` is OPTIONAL and, when given, is compared against the CURRENT identity
+   * generation before touching anything: a user/Bearer operation carries its own identity, and a
+   * late failure from an identity that no longer exists must not sign out whatever DIFFERENT,
+   * currently valid session is active now (the mirror-case at this call's own boundary). A
+   * Basic-credentials operation (`oAuthCreateToken` / `oAuthRevokeToken`) carries no user
+   * identity — its call site passes nothing, so it keeps terminating unconditionally.
+   */
+  terminate(stampedGeneration?: number): Observable<RecoveryOutcome> {
+    if (
+      stampedGeneration !== undefined &&
+      stampedGeneration !== this.tokenStore.identityGeneration()
+    ) {
+      this.notifyOperationNotCompleted();
+      return from(Promise.resolve<RecoveryOutcome>('terminate'));
+    }
+
+    return from(
+      this.runSignOutFlight('navigation.Session.ExpiredNotice').then(() => {
+        void this.router.navigate(['/auth/sign-in']);
+        return 'terminate' as const;
+      }),
+    );
+  }
+
+  private notifyOperationNotCompleted(): void {
+    const current = this.tokenStore.identityGeneration();
+    if (this.staleNoticeGeneration === current) return;
+    this.staleNoticeGeneration = current;
+    toast.info(this.transloco.translate('navigation.Session.OperationNotCompletedNotice'));
+  }
+
+  /** Single-flight refresh grant — the ONLY place in the client that can issue one (Decision 1). */
+  private runRefreshFlight(): Promise<boolean> {
+    this.refreshFlight ??= this.issueRefreshGrant().finally(() => {
+      this.refreshFlight = null;
+    });
+    return this.refreshFlight;
+  }
+
+  private issueRefreshGrant(): Promise<boolean> {
+    const refreshToken = this.tokenStore.refreshToken();
+    if (!refreshToken) return Promise.resolve(false);
+
+    const launchGeneration = this.tokenStore.identityGeneration();
+
+    return firstValueFrom(
+      this.apollo.mutate<{ oAuthCreateToken: OAuthTokens }>({
+        mutation: oAuthCreateToken,
+        variables: { payload: { refreshToken, grantType: ClientGrantType.REFRESH_TOKEN } },
+        // Suppress the global toast for invalid_grant on refresh failures — this call runs
+        // transparently mid-session; the terminal sign-out notice covers the operator instead.
+        context: { skipGlobalErrors: ['invalid_grant'] },
+      }),
+    ).then(
+      (response) => {
+        const next = response.data?.oAuthCreateToken;
+        if (!next) return false;
+        // The identity may have changed WHILE this round trip was in flight (a new impersonation
+        // started). Installing a rotated credential for an identity that is no longer current
+        // would silently overwrite it — never apply a stale grant. The grant already COMPLETED
+        // server-side, though: the backend revoked the OLD pair and issued `next`, so discarding it
+        // silently would leave a valid, unrevoked refresh token nobody will ever present again —
+        // revoke it best-effort instead of just dropping it on the floor.
+        if (this.tokenStore.identityGeneration() !== launchGeneration) {
+          if (next.refreshToken) this.revokeRefreshToken(next.refreshToken);
+          return false;
+        }
+        this.tokenStore.setCredentials(next);
+        return true;
+      },
+      () => false, // refresh token rejected by backend (invalid_grant) or network failure
+    );
+  }
+
+  /** Single-flight impersonation unwind. Restores the stash if present; notifies exactly once. */
+  private runUnwindFlight(): Promise<boolean> {
+    this.unwindFlight ??= Promise.resolve()
+      .then(() => {
+        if (!this.tokenStore.hasStashedSession()) return false;
+        this.tokenStore.endImpersonation();
+        // Re-materialize session-scoped state via an EXPLICIT reload: a same-tick clear-then-set
+        // produces no observable edge for CurrentAccountService's consumers to react to.
+        this.currentAccount.load();
+        toast.info(this.transloco.translate('navigation.Impersonation.ExpiredNotice'));
+        return true;
+      })
+      .finally(() => {
+        this.unwindFlight = null;
+      });
+    return this.unwindFlight;
+  }
+
+  /** Single-flight terminal sign-out. Revokes server-side, clears credentials and shows ONE notice;
+   * never navigates itself — navigation is each caller's own decision (constraint 4). */
+  private runSignOutFlight(noticeKey: string): Promise<void> {
+    // The body is DEFERRED onto a microtask so the latch is installed before any of it runs.
+    // Calling an async method directly would execute its body synchronously up to the first
+    // `await` — and with no refresh token to revoke there is no await at all, so the notice would
+    // fire while the assignment was still being evaluated and every later caller would run its own.
+    this.signOutFlight ??= Promise.resolve()
+      .then(() => this.revokeThenClear(noticeKey))
+      .finally(() => {
+        this.signOutFlight = null;
+      });
+    return this.signOutFlight;
+  }
+
+  /**
+   * Local end of the session, followed by a best-effort server-side revocation (RFC 7009) that is
+   * FIRED, never awaited.
+   *
+   * Unwinds an impersonation stack FIRST, mirroring the adapter's `signOut()` (its comment explains
+   * the hazard): during an impersonated session the ACTIVE credential is the impersonation JWT,
+   * which has NO refresh token by design, so reading `refreshToken()` off it would silently skip
+   * the revocation — and the operator's own token is reachable only through the stash `clear()` is
+   * about to delete.
+   *
+   * `clear()` and the notice run UNCONDITIONALLY, before any network work: making the local end of
+   * the session independent of the network is what keeps this method safe to await from the single
+   * sign-out flight even if the revocation itself never settles (`oAuthRevokeToken` is
+   * client-Basic-authenticated, so it succeeds with no user session — clearing first is safe). The
+   * coordinator issues the revocation ITSELF rather than through `AuthenticationService`: the
+   * adapter delegates `check()` to this service, so a call back into the adapter would close a DI
+   * cycle inside `authentication`.
+   */
+  private revokeThenClear(noticeKey: string): void {
+    if (this.tokenStore.isImpersonating() && this.tokenStore.hasStashedSession()) {
+      this.tokenStore.endImpersonation();
+    }
+
+    const refreshToken = this.tokenStore.refreshToken();
+
+    this.tokenStore.clear();
+    toast.info(this.transloco.translate(noticeKey));
+
+    if (refreshToken) {
+      this.revokeRefreshToken(refreshToken);
+    }
+  }
+
+  /** Fires a best-effort RFC 7009 revocation WITHOUT awaiting it, swallowing its failure so it can
+   * never surface as an unhandled rejection. Shared by the terminal sign-out (finding 4) and a
+   * refresh grant dropped as stale (finding 3) — both need the local flow to proceed independently
+   * of this network call. */
+  private revokeRefreshToken(refreshToken: string): void {
+    firstValueFrom(
+      this.apollo.mutate<{ oAuthRevokeToken: boolean }>({
+        mutation: oAuthRevokeToken,
+        variables: { payload: { token: refreshToken } },
+      }),
+    ).catch(() => undefined);
+  }
+}

package/dist/templates/frontend/application/src/@aurora/modules/authentication/shared/token-store.service.spec.ts

@@ -0,0 +1,293 @@
+/**
+ * Tests for TokenStore's credential-stacking surface (design D8 / `authentication` delta spec):
+ * `beginImpersonation`, `endImpersonation`, `isImpersonating`, and the `clear()` extension to wipe
+ * BOTH slots. Every scenario below is lifted directly from
+ * `openspec/changes/add-account-impersonation/specs/authentication/spec.md`.
+ */
+import '@angular/compiler';
+import { CREDENTIALS_KEY } from './authentication';
+import type { OAuthTokens } from './authentication.types';
+import { TokenStore } from './token-store.service';
+
+/** localStorage key for the stashed original session (mirrors CREDENTIALS_KEY's encoding). */
+const ORIGIN_CREDENTIALS_KEY = 'originCredentials';
+
+/** Builds a syntactically valid JWT (header.payload.signature) carrying the given claims. */
+function makeJwt(payload: Record<string, unknown>): string {
+  const header = btoa(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+  const body = btoa(JSON.stringify(payload));
+  return `${header}.${body}.fake-signature`;
+}
+
+function futureExp(): number {
+  return Math.floor(Date.now() / 1000) + 3600;
+}
+
+/** A normal (non-impersonation) access token: no `act` claim. */
+function normalToken(aci = 'account-1'): string {
+  return makeJwt({ aci, iss: 'aurora', iat: Math.floor(Date.now() / 1000), exp: futureExp() });
+}
+
+/** An impersonation access token: carries `act.aci` for the real actor. */
+function impersonationToken(targetAci: string, actorAci: string): string {
+  return makeJwt({
+    aci: targetAci,
+    act: { aci: actorAci },
+    iss: 'aurora',
+    iat: Math.floor(Date.now() / 1000),
+    exp: futureExp(),
+  });
+}
+
+/** A normal session credential: access + refresh token, the shape the password grant returns. */
+function credentials(accessToken: string, refreshToken = 'refresh'): OAuthTokens {
+  return { accessToken, refreshToken };
+}
+
+/**
+ * An impersonation credential as PRODUCTION creates it: access token only, no refresh token
+ * (design D4 — the impersonation grant issues a short-lived, non-renewable credential). Load
+ * bearing for these tests: a fixture that invented a refresh token here would hide every bug that
+ * only appears when `refreshToken()` is `''` while impersonating.
+ */
+function impersonationCredentials(accessToken: string): OAuthTokens {
+  return { accessToken };
+}
+
+describe('TokenStore — credential stacking', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  describe('beginImpersonation', () => {
+    it('stashes the currently active credentials, installs the impersonation credentials as active, and reports success', () => {
+      const store = new TokenStore();
+      const original = credentials(normalToken('actor-1'), 'original-refresh');
+      store.setCredentials(original);
+
+      const impersonated = impersonationCredentials(impersonationToken('target-1', 'actor-1'));
+      const started = store.beginImpersonation(impersonated);
+
+      expect(started).toBe(true);
+      expect(store.accessToken()).toBe(impersonated.accessToken);
+      expect(localStorage.getItem(ORIGIN_CREDENTIALS_KEY)).toBe(btoa(JSON.stringify(original)));
+      // The active impersonation credential carries NO refresh token — this is the state every
+      // consumer of `refreshToken()` must tolerate while impersonating.
+      expect(store.refreshToken()).toBe('');
+    });
+
+    it('refuses to nest: a second beginImpersonation leaves both slots untouched AND reports refusal', () => {
+      const store = new TokenStore();
+      const original = credentials(normalToken('actor-1'), 'original-refresh');
+      store.setCredentials(original);
+
+      const firstImpersonation = impersonationCredentials(
+        impersonationToken('target-1', 'actor-1'),
+      );
+      const firstStarted = store.beginImpersonation(firstImpersonation);
+
+      const secondImpersonation = impersonationCredentials(
+        impersonationToken('target-2', 'actor-1'),
+      );
+      const secondStarted = store.beginImpersonation(secondImpersonation);
+
+      expect(firstStarted).toBe(true);
+      // Load-bearing (security finding F7): the caller MUST be able to tell the second attempt
+      // was refused, not silently treated as a successful swap.
+      expect(secondStarted).toBe(false);
+      // Active credentials are still the FIRST impersonation, not the second.
+      expect(store.accessToken()).toBe(firstImpersonation.accessToken);
+      // The origin slot still holds the ORIGINAL operator credentials, untouched.
+      expect(localStorage.getItem(ORIGIN_CREDENTIALS_KEY)).toBe(btoa(JSON.stringify(original)));
+    });
+  });
+
+  describe('endImpersonation', () => {
+    it('restores the stashed credentials as active and empties the origin slot', () => {
+      const store = new TokenStore();
+      const original = credentials(normalToken('actor-1'), 'original-refresh');
+      store.setCredentials(original);
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+
+      store.endImpersonation();
+
+      expect(store.accessToken()).toBe(original.accessToken);
+      expect(store.refreshToken()).toBe(original.refreshToken);
+      expect(localStorage.getItem(ORIGIN_CREDENTIALS_KEY)).toBeNull();
+    });
+
+    it('is a no-op when no stash exists — does not throw and leaves the active session unchanged', () => {
+      const store = new TokenStore();
+      const original = credentials(normalToken('actor-1'), 'original-refresh');
+      store.setCredentials(original);
+
+      expect(() => store.endImpersonation()).not.toThrow();
+      expect(store.accessToken()).toBe(original.accessToken);
+    });
+  });
+
+  describe('clear()', () => {
+    it('empties BOTH the active and origin slots', () => {
+      const store = new TokenStore();
+      store.setCredentials(credentials(normalToken('actor-1')));
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+
+      store.clear();
+
+      expect(localStorage.getItem(CREDENTIALS_KEY)).toBeNull();
+      expect(localStorage.getItem(ORIGIN_CREDENTIALS_KEY)).toBeNull();
+      expect(store.accessToken()).toBe('');
+      expect(store.authenticated()).toBe(false);
+
+      // A subsequent endImpersonation must be harmless — the stash is genuinely gone.
+      expect(() => store.endImpersonation()).not.toThrow();
+    });
+  });
+
+  describe('hasStashedSession', () => {
+    it('reports whether the origin slot holds a session to roll back to', () => {
+      const store = new TokenStore();
+      store.setCredentials(credentials(normalToken('actor-1'), 'original-refresh'));
+
+      expect(store.hasStashedSession()).toBe(false);
+
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+      expect(store.hasStashedSession()).toBe(true);
+
+      store.endImpersonation();
+      expect(store.hasStashedSession()).toBe(false);
+    });
+
+    it('is false after clear(), so a caller can tell there is nothing left to restore', () => {
+      const store = new TokenStore();
+      store.setCredentials(credentials(normalToken('actor-1'), 'original-refresh'));
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+
+      store.clear();
+
+      expect(store.hasStashedSession()).toBe(false);
+    });
+  });
+
+  describe('isImpersonating', () => {
+    it('is true when the ACTIVE token carries an actor claim', () => {
+      const store = new TokenStore();
+      store.setCredentials(credentials(normalToken('actor-1')));
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+
+      expect(store.isImpersonating()).toBe(true);
+    });
+
+    it('is false when the active token carries no actor claim, regardless of what the stash contains', () => {
+      const store = new TokenStore();
+      store.setCredentials(credentials(normalToken('actor-1')));
+
+      expect(store.isImpersonating()).toBe(false);
+    });
+
+    // Non-tautological guard: proves the signal reads the TOKEN, not the presence of the stash.
+    // A stale/hand-edited stash with no matching active impersonation token must NOT flip it true.
+    it('ignores a stale stash: false even when the origin slot is (artificially) occupied', () => {
+      const store = new TokenStore();
+      const original = credentials(normalToken('actor-1'));
+      store.setCredentials(original);
+
+      // Hand-edit localStorage to simulate a stale stash without an active impersonation token.
+      localStorage.setItem(ORIGIN_CREDENTIALS_KEY, btoa(JSON.stringify(original)));
+      const staleStore = new TokenStore();
+
+      expect(staleStore.isImpersonating()).toBe(false);
+    });
+  });
+
+  describe('a stacked session survives re-construction from localStorage', () => {
+    it('reloads the impersonation access token and the origin stash after a fresh construction', () => {
+      const store = new TokenStore();
+      const original = credentials(normalToken('actor-1'), 'original-refresh');
+      store.setCredentials(original);
+      const impersonated = impersonationCredentials(impersonationToken('target-1', 'actor-1'));
+      store.beginImpersonation(impersonated);
+
+      // Simulate a page reload: a brand-new TokenStore instance hydrates from localStorage.
+      const reloaded = new TokenStore();
+
+      expect(reloaded.accessToken()).toBe(impersonated.accessToken);
+      expect(reloaded.isImpersonating()).toBe(true);
+      // The stash must still be recoverable — endImpersonation on the reloaded instance restores it.
+      reloaded.endImpersonation();
+      expect(reloaded.accessToken()).toBe(original.accessToken);
+    });
+  });
+
+  /**
+   * `identityGeneration` (design.md Decision 3): a monotonic counter over the `(account, actor)`
+   * tuple derived from the ACTIVE access token — NOT over which method was called. Task 1.1: a
+   * refresh rotation that keeps the tuple unchanged must NOT advance it, while sign-in,
+   * `beginImpersonation`, `endImpersonation` and `clear` each DO, because each of those changes the
+   * tuple. Reproduces the worked table in design.md Decision 3 verbatim.
+   */
+  describe('identityGeneration', () => {
+    it('advances on sign-in, beginImpersonation, endImpersonation and clear, but NOT on a refresh rotation that keeps the same account and actor', () => {
+      const store = new TokenStore();
+
+      // sign-in: (op, -) -> generation 1
+      store.setCredentials(credentials(normalToken('actor-1'), 'original-refresh'));
+      const afterSignIn = store.identityGeneration();
+      expect(afterSignIn).toBe(1);
+
+      // begin impersonation: (op, target) -> generation 2. Fixture rule: NO refreshToken field —
+      // production never issues one for the impersonation credential.
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+      const afterBegin = store.identityGeneration();
+      expect(afterBegin).toBeGreaterThan(afterSignIn);
+
+      // refresh rotation: a NEW impersonation access token, SAME account (target-1) and SAME actor
+      // (actor-1) as the one it replaces -> generation UNCHANGED. This is a direct setCredentials
+      // call, exactly how a transparent refresh installs the rotated credential.
+      store.setCredentials(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+      expect(store.identityGeneration()).toBe(afterBegin);
+
+      // end impersonation: (op, -) -> generation advances again
+      store.endImpersonation();
+      const afterEnd = store.identityGeneration();
+      expect(afterEnd).toBeGreaterThan(afterBegin);
+
+      // clear: identity tuple collapses to empty -> generation advances again
+      store.clear();
+      expect(store.identityGeneration()).toBeGreaterThan(afterEnd);
+    });
+
+    /**
+     * Task 1.2: two successive impersonations of the SAME target must carry DIFFERENT generations,
+     * so a stamp recorded during the first is not mistaken as belonging to the second, even though
+     * the (account, actor) tuple is IDENTICAL in both impersonation windows — the sequence
+     * sign-in / begin / end / begin must yield 1 / 2 / 3 / 4, per design.md Decision 3.
+     */
+    it('gives two successive impersonations of the SAME target different generations', () => {
+      const store = new TokenStore();
+
+      store.setCredentials(credentials(normalToken('actor-1'), 'original-refresh'));
+      expect(store.identityGeneration()).toBe(1);
+
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+      const firstImpersonationGeneration = store.identityGeneration();
+      expect(firstImpersonationGeneration).toBe(2);
+
+      store.endImpersonation();
+      expect(store.identityGeneration()).toBe(3);
+
+      store.beginImpersonation(impersonationCredentials(impersonationToken('target-1', 'actor-1')));
+      const secondImpersonationGeneration = store.identityGeneration();
+      expect(secondImpersonationGeneration).toBe(4);
+
+      // Load-bearing: same target, same actor, IDENTICAL (account, actor) tuple in both windows —
+      // yet the generations must differ, so a stamp from the first is not accepted as belonging to
+      // the second.
+      expect(secondImpersonationGeneration).not.toBe(firstImpersonationGeneration);
+    });
+  });
+});