@iloveagents/foundry-agent 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @iloveagents/foundry-agent
 
+## 0.1.4
+
+### Patch Changes
+
+- 07ace7e: fix(agent): canonical MSAL.js recovery — acquireTokenRedirect-first, orphaned-state cleanup, dedup
+
+  Closes the production "stuck on 401 forever" bug observed on andritz-dev after the 0.1.2 / 0.1.3 fixes. Diagnostic on the live tab showed `getAllAccounts() === []` despite localStorage holding 3 access tokens + 1 refresh token — the orphaned-state signature.
+
+  **Root cause:** The previous recovery code did `setActiveAccount(null) + clearCache({account}) + loginRedirect()`. When `loginRedirect()` silently failed to navigate (caught by our try/catch — popup blocker, browser policy, async race), the account record was already gone but the tokens lingered. Every subsequent API call hit `getAllAccounts() === []` and silently returned `null` — no Bearer header, endless 401s, only manual `localStorage.clear()` recovered.
+
+  **Canonical 2026 fix per Microsoft Learn `entra/msal/javascript/browser/errors`** + linked GitHub issues + msal-react samples:
+  1. **`acquireTokenRedirect` first, not `loginRedirect`.** It's the documented primitive for refreshing a known account's tokens — preserves the account record across the navigation. `loginRedirect` is only the fallback when `acquireTokenRedirect` itself fails to navigate.
+  2. **Never `clearCache` before redirect.** The redirect navigation IS the recovery signal; if it succeeds, MSAL handles state cleanup; if it fails, leave state intact for the next attempt rather than orphaning the cache.
+  3. **Detect + repair orphaned state.** When `getAllAccounts() === []` but localStorage has MSAL token entries, nuke ALL `msal.*` keys (localStorage + sessionStorage) and force a fresh `loginRedirect`. Without this, the SPA renders authenticated UI but every API call goes anonymous.
+  4. **Module-level recovery deduplication.** Multiple parallel API calls all hitting the recovery path simultaneously now share a single in-flight redirect promise instead of each issuing their own (which would cascade `interaction_in_progress` errors).
+
+  The previous `recoverFromHardAuthFailure` callback now uses the same primitive — single recovery path for both "MSAL silent failed" and "API rejected refreshed token".
+
+  68/68 agent tests pass (was 65) — the new tests assert the no-clearCache invariant, the acquireTokenRedirect-first ordering, the loginRedirect fallback path, and the orphaned-state nuke + redirect. Pair: lastspace bump to ^0.1.4.
+
+## 0.1.3
+
+### Patch Changes
+
+- d9b0460: fix(agent): escalate to loginRedirect after second 401
+
+  Follow-up to the auth-stale-token-401-retry fix in 0.1.2. The first version retried with `forceRefresh: true` and bounced to `loginRedirect` only when MSAL itself reported `InteractionRequiredAuthError`. But there's a more common production failure mode the silent path can't recover: the resource server rejects the **freshly-refreshed** token too — server-side policy drift, audience mismatch, conditional-access re-evaluation, claims challenge, tenant-policy change. MSAL has no way to know about any of this; it produces a clean refreshed token and calls it a day. The user is left in an endless silent 401 loop because nothing kicks them to `loginRedirect`.
+
+  Adds `recoverFromHardAuthFailure(reason)` on `authStore`. The fetch interceptor calls it when a SECOND consecutive 401 fires (i.e. even the force-refresh retry didn't help). It clears the MSAL cache and starts `loginRedirect` so a brand-new session mints a token bound to current server policy.
+
+  `createServiceFetch` now accepts an optional `recoverFromHardAuthFailure` callback. The default consumer (`@iloveagents/foundry-web-shell`) wires it to the new method on `authStore`. Same pattern in `tokenFetch`.
+
+  Pair: `lastspace#TBD` (forwards the new option through `spacesFetch`).
+
 ## 0.1.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-agent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "types": "./src/index.ts",

package/src/__tests__/auth-store.test.ts

@@ -125,6 +125,27 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     );
   });
 
+  it("recoverFromHardAuthFailure starts acquireTokenRedirect (preserves account)", async () => {
+    // When the fetch interceptor's force-refresh retry STILL gets 401,
+    // server-side drift (audience / claims / conditional-access) means
+    // we need a fresh interactive auth. Same recovery primitive as the
+    // silent-failure path: ``acquireTokenRedirect`` first (preserves
+    // the account record), ``loginRedirect`` only as fallback. Cache
+    // is NOT cleared before redirect.
+    const msal = mockMsal();
+    const reason = new Error("API returned 401 after force-refresh retry");
+    await expectInteractiveRecoveryError(
+      store().recoverFromHardAuthFailure(reason),
+      {
+        code: undefined,
+        cause: reason,
+        messageIncludes: ["interaction required"],
+      },
+    );
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
+  });
+
   it("returns null without redirecting when no account is cached", async () => {
     // AuthGuard calls loginRedirect when accounts.length === 0; double-
     // redirecting from getAccessToken would race with AuthGuard.
@@ -135,7 +156,12 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 
-  it("clears stale cache and redirects on InteractionRequiredAuthError", async () => {
+  it("uses acquireTokenRedirect on InteractionRequiredAuthError (preserves account)", async () => {
+    // Canonical 2026 MSAL.js pattern: ``acquireTokenRedirect`` is the
+    // documented primitive for refreshing a known account's tokens
+    // without a full ``loginRedirect``. Critically, the cache is NOT
+    // cleared before the redirect — that was the orphaned-state bug
+    // (account record gone + tokens lingering when redirect fails).
     const err = Object.assign(new Error("MFA required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "interaction_required",
@@ -151,17 +177,41 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
         "MFA required",
       ],
     });
-    expect(msal.clearCache).toHaveBeenCalledWith({
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith({
+      scopes: [config.apiScope],
       account: { username: "alice@example.com", localAccountId: "alice-oid" },
     });
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledWith({
-      scopes: [config.apiScope],
+    // Cache MUST NOT be cleared before redirect — see
+    // AzureAD/microsoft-authentication-library-for-js#7551 and the
+    // orphaned-state production bug this fix exists to address.
+    expect(msal.clearCache).not.toHaveBeenCalled();
+    expect(msal.setActiveAccount).not.toHaveBeenCalled();
+  });
+
+  it("falls back to loginRedirect when acquireTokenRedirect returns without navigating", async () => {
+    // ``acquireTokenRedirect`` resolves before navigation in some
+    // environments (test runners, blocked redirects). When it settles
+    // without throwing AND without navigating, fall through to a full
+    // ``loginRedirect`` so the user still gets through the auth flow.
+    const err = Object.assign(new Error("interaction"), {
+      name: "InteractionRequiredAuthError",
+      errorCode: "interaction_required",
     });
-    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    const msal = mockMsal({
+      acquireTokenSilent: vi.fn().mockRejectedValue(err),
+      acquireTokenRedirect: vi.fn().mockResolvedValue(undefined),
+    });
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "interaction_required",
+      cause: err,
+      messageIncludes: ["Authentication interaction required"],
+    });
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
 
-  it("clears stale cache and redirects on consent_required", async () => {
+  it("recovers on consent_required without clearing cache before redirect", async () => {
     const err = Object.assign(new Error("consent required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "consent_required",
@@ -172,11 +222,11 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "consent_required"],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
-  it("clears stale cache and redirects on monitor_window_timeout", async () => {
+  it("recovers on monitor_window_timeout without clearing cache before redirect", async () => {
     // Microsoft Learn → "Common errors in MSAL JS" → monitor_window_timeout
     // → documented remedy includes "Invoke an interactive API".
     const err = Object.assign(new Error("monitor_window_timeout"), {
@@ -189,8 +239,8 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "monitor_window_timeout"],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
   it("does NOT redirect on interaction_in_progress (would race with another flow)", async () => {
@@ -231,36 +281,148 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "InteractionRequiredAuthError"],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
-  it("preserves redirect failure details when interactive recovery cannot start", async () => {
+  it("preserves redirect failure details when both redirect attempts fail", async () => {
     const tokenErr = Object.assign(new Error("MFA required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "interaction_required",
     });
-    const redirectErr = Object.assign(new Error("redirect blocked"), {
+    const acquireErr = Object.assign(new Error("acquireToken redirect blocked"), {
       name: "BrowserAuthError",
       errorCode: "redirect_failed",
     });
+    const loginErr = Object.assign(new Error("login redirect blocked"), {
+      name: "BrowserAuthError",
+      errorCode: "redirect_failed_login",
+    });
     const msal = mockMsal({
       acquireTokenSilent: vi.fn().mockRejectedValue(tokenErr),
-      loginRedirect: vi.fn().mockRejectedValue(redirectErr),
+      acquireTokenRedirect: vi.fn().mockRejectedValue(acquireErr),
+      loginRedirect: vi.fn().mockRejectedValue(loginErr),
     });
 
     await expectInteractiveRecoveryError(store().getAccessToken(), {
-      code: "redirect_failed",
-      cause: redirectErr,
+      code: "redirect_failed_login",
+      cause: loginErr,
       messageIncludes: [
         "Authentication interaction required",
-        "login redirect failed",
-        "redirect_failed",
+        "redirect failed",
+        "redirect_failed_login",
         "Original token error",
         "interaction_required",
       ],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    // Even on full failure, cache is NOT touched — leaves state intact
+    // for the next attempt rather than creating an orphaned cache.
+    expect(msal.clearCache).not.toHaveBeenCalled();
+  });
+});
+
+describe("authStore — orphaned-state recovery", () => {
+  // Production bug: a previous recovery cleared the account record but
+  // its redirect didn't navigate (browser policy, popup blocker, etc.).
+  // localStorage is left with token entries but ``getAllAccounts()``
+  // returns []. Every subsequent API call gets null token + 401 forever
+  // until manual ``localStorage.clear()``.
+
+  const config = {
+    clientId: "test-client",
+    authority: "https://login.microsoftonline.com/test-tenant",
+    redirectUri: "http://localhost:8010",
+    apiScope: "api://test-api/access_as_user",
+  };
+
+  beforeEach(() => {
+    if (typeof localStorage !== "undefined") {
+      localStorage.clear();
+    }
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (typeof localStorage !== "undefined") {
+      localStorage.clear();
+    }
+  });
+
+  it("detects orphaned state, nukes localStorage, and triggers fresh login", async () => {
+    // Seed the orphan: token-shaped MSAL keys but no account record.
+    localStorage.setItem(
+      "msal.3|home-id.tenant|login.windows.net|accesstoken|client|tenant|scope|",
+      JSON.stringify({ id: "x", nonce: "n", data: "encrypted-blob", lastUpdatedAt: "0" }),
+    );
+    localStorage.setItem(
+      "msal.3|home-id.tenant|login.windows.net|refreshtoken|client|||",
+      JSON.stringify({ id: "x", nonce: "n", data: "encrypted-blob", lastUpdatedAt: "0" }),
+    );
+    localStorage.setItem(
+      "msal.client.active-account-filters",
+      JSON.stringify({ homeAccountId: "home-id.tenant" }),
+    );
+
+    const msal = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
+      // CRITICAL: the orphaned-state — empty accounts despite localStorage entries.
+      getAllAccounts: vi.fn().mockReturnValue([]),
+      loginRedirect: vi.fn().mockResolvedValue(undefined),
+      logoutRedirect: vi.fn().mockResolvedValue(undefined),
+      setActiveAccount: vi.fn(),
+      acquireTokenSilent: vi.fn(),
+      acquireTokenRedirect: vi.fn().mockResolvedValue(undefined),
+      acquireTokenPopup: vi.fn(),
+    };
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(msal);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(config);
+
+    let thrown: unknown;
+    try {
+      await authStore.getState().getAccessToken();
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(AuthInteractionRequiredError);
+    expect((thrown as AuthInteractionRequiredError).message).toMatch(/orphaned/i);
+
+    // localStorage should have been nuked of all msal.* keys.
+    const remainingMsalKeys = Object.keys(localStorage).filter((k) =>
+      k.startsWith("msal."),
+    );
+    expect(remainingMsalKeys).toEqual([]);
+
+    // No account → recovery skips acquireTokenRedirect and goes
+    // straight to loginRedirect.
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
     expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
+
+  it("returns null on truly clean no-account state (no orphan)", async () => {
+    // No MSAL keys in localStorage and no accounts — user genuinely
+    // hasn't logged in yet. AuthGuard handles ``loginRedirect`` on
+    // its render; we don't double-redirect from here.
+    const msal = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
+      getAllAccounts: vi.fn().mockReturnValue([]),
+      loginRedirect: vi.fn().mockResolvedValue(undefined),
+      logoutRedirect: vi.fn().mockResolvedValue(undefined),
+      setActiveAccount: vi.fn(),
+      acquireTokenSilent: vi.fn(),
+      acquireTokenRedirect: vi.fn(),
+      acquireTokenPopup: vi.fn(),
+    };
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(msal);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(config);
+
+    expect(await authStore.getState().getAccessToken()).toBeNull();
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    expect(msal.loginRedirect).not.toHaveBeenCalled();
+  });
 });

package/src/__tests__/service-fetch.test.ts

@@ -284,9 +284,10 @@ describe("createServiceFetch", () => {
     });
 
     it("only retries once even if the second attempt also returns 401", async () => {
-      // Hard auth failure (refresh token expired). The second 401 propagates
-      // to the caller; the auth layer's interaction-required path is what
-      // kicks the user to loginRedirect, not an infinite retry loop here.
+      // Hard auth failure (refresh token expired). With no
+      // ``recoverFromHardAuthFailure`` configured, the second 401
+      // propagates to the caller. (Tests cover the recovery path
+      // separately below.)
       fetchSpy.mockReset();
       fetchSpy
         .mockResolvedValueOnce(new Response(null, { status: 401 }))
@@ -300,5 +301,78 @@ describe("createServiceFetch", () => {
       expect(fetchSpy).toHaveBeenCalledTimes(2);
       expect(acquireToken).toHaveBeenCalledTimes(2);
     });
+
+    it("kicks off interactive recovery after a second 401", async () => {
+      // Server-policy drift: even the force-refreshed token is rejected.
+      // The fetch interceptor must escalate to loginRedirect via the
+      // recoverFromHardAuthFailure callback — without it the user is
+      // stuck in a silent 401 loop forever (the bug this fix exists for).
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockResolvedValueOnce("force-refreshed-but-still-bad-token");
+      const recoverFromHardAuthFailure = vi
+        .fn()
+        .mockRejectedValue(new Error("loginRedirect in flight"));
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      await expect(serviceFetch("/api/spaces/entities")).rejects.toThrow(
+        "loginRedirect in flight",
+      );
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+      expect(recoverFromHardAuthFailure).toHaveBeenCalledTimes(1);
+      // Reason carries enough context to log/alert without leaking tokens.
+      const reason = recoverFromHardAuthFailure.mock.calls[0]![0];
+      expect(reason).toBeInstanceOf(Error);
+      expect((reason as Error).message).toMatch(/401/);
+    });
+
+    it("does NOT call recoverFromHardAuthFailure on first-attempt success", async () => {
+      // Sanity: when the first request succeeds, recovery callback must
+      // never fire.
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi.fn().mockResolvedValue("good-token");
+      const recoverFromHardAuthFailure = vi.fn();
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      const res = await serviceFetch("/api/spaces/entities");
+      expect(res.status).toBe(200);
+      expect(recoverFromHardAuthFailure).not.toHaveBeenCalled();
+    });
+
+    it("does NOT call recoverFromHardAuthFailure when the retry recovers", async () => {
+      // Standard recovery — first 401, retry with forceRefresh succeeds.
+      // Recovery callback must not fire (would needlessly bounce the user
+      // through loginRedirect).
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale")
+        .mockResolvedValueOnce("fresh");
+      const recoverFromHardAuthFailure = vi.fn();
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      const res = await serviceFetch("/api/spaces/entities");
+      expect(res.status).toBe(200);
+      expect(recoverFromHardAuthFailure).not.toHaveBeenCalled();
+    });
   });
 });

package/src/__tests__/token-fetch.test.ts

@@ -1,11 +1,13 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const getAccessToken = vi.fn();
+const recoverFromHardAuthFailure = vi.fn();
 
 vi.mock("../msal/auth-store.ts", () => ({
   authStore: {
     getState: () => ({
       getAccessToken,
+      recoverFromHardAuthFailure,
     }),
   },
 }));
@@ -15,6 +17,7 @@ import { tokenFetch } from "../msal/token-fetch.ts";
 describe("tokenFetch", () => {
   beforeEach(() => {
     getAccessToken.mockReset();
+    recoverFromHardAuthFailure.mockReset();
     vi.restoreAllMocks();
   });
 
@@ -105,17 +108,27 @@ describe("tokenFetch", () => {
     expect(getAccessToken).toHaveBeenCalledTimes(1);
   });
 
-  it("only retries once on a hard 401-then-401 path", async () => {
+  it("escalates to interactive recovery on a hard 401-then-401 path", async () => {
+    // Server-policy drift: even the force-refreshed token is rejected.
+    // The fetch interceptor must call ``recoverFromHardAuthFailure`` so
+    // the auth layer can kick off ``loginRedirect``. The recovery
+    // throws once the redirect is in flight; the throw stops the
+    // calling pipeline.
     getAccessToken.mockResolvedValue("token");
+    recoverFromHardAuthFailure.mockRejectedValue(
+      new Error("loginRedirect in flight"),
+    );
     const fetchSpy = vi
       .spyOn(globalThis, "fetch")
       .mockResolvedValueOnce(new Response(null, { status: 401 }))
       .mockResolvedValueOnce(new Response(null, { status: 401 }));
 
-    const res = await tokenFetch("https://example.com/api/items");
+    await expect(tokenFetch("https://example.com/api/items")).rejects.toThrow(
+      "loginRedirect in flight",
+    );
 
-    expect(res.status).toBe(401);
     expect(fetchSpy).toHaveBeenCalledTimes(2);
     expect(getAccessToken).toHaveBeenCalledTimes(2);
+    expect(recoverFromHardAuthFailure).toHaveBeenCalledTimes(1);
   });
 });

package/src/client/service-fetch.ts

@@ -26,6 +26,27 @@ export interface ServiceFetchOptions {
    */
   acquireToken: (options?: { forceRefresh?: boolean }) => Promise<string | null>;
 
+  /**
+   * Force interactive recovery (e.g. ``loginRedirect``) when even a
+   * force-refreshed access token gets rejected by the resource server.
+   * The fetch interceptor calls this after a SECOND consecutive 401 —
+   * at that point we know the silent refresh produced a token the
+   * server still won't accept (audience drift, conditional-access
+   * re-eval, tenant-policy change), and the only correct UX is to
+   * mint a fresh session.
+   *
+   * Implementations should clear cached auth state and start a redirect
+   * to the IdP. They MUST throw rather than return so the fetch caller
+   * can stop processing the in-flight request — when this resolves
+   * normally the redirect is in flight and the page is about to
+   * navigate away.
+   *
+   * Optional: when omitted, the fetch interceptor lets the second 401
+   * propagate as-is. Hosts without an interactive recovery path (e.g.
+   * tests, embedded apps) should leave it unset.
+   */
+  recoverFromHardAuthFailure?: (reason: unknown) => Promise<never>;
+
   /**
    * Router FQDN for production (e.g. `https://lastspace-prod.eastus2.example.com`).
    * Empty / undefined leaves the URL untouched (Vite proxy handles routing
@@ -152,6 +173,25 @@ export function createServiceFetch(options: ServiceFetchOptions): ServiceFetch {
     // Drain the failed response body — letting it sit unread keeps the
     // underlying connection occupied on some runtimes.
     response.body?.cancel().catch(() => undefined);
-    return dispatch(true);
+    const retried = await dispatch(true);
+
+    // Hard auth failure: even the force-refreshed token got rejected.
+    // The silent path can't recover this — a token minted from the
+    // cached refresh token carries the same identity claims as the
+    // original, so it'll keep getting rejected for the same reason
+    // (audience drift, conditional-access re-eval, claims challenge,
+    // tenant-policy change). Only a brand-new ``loginRedirect`` produces
+    // a token bound to the current server policy. Without this branch
+    // the user sees an endless 401 loop until they manually log out.
+    if (retried.status === 401 && options.recoverFromHardAuthFailure) {
+      retried.body?.cancel().catch(() => undefined);
+      // ``recoverFromHardAuthFailure`` throws once the redirect is in
+      // flight; the throw stops the calling pipeline so we don't
+      // return a stale 401 the caller might handle as a real failure.
+      await options.recoverFromHardAuthFailure(
+        new Error("API returned 401 after force-refresh retry"),
+      );
+    }
+    return retried;
   };
 }

package/src/msal/auth-store.ts

@@ -38,42 +38,50 @@ interface AuthState {
    * Recovery semantics — follows the canonical MSAL.js pattern documented
    * at https://learn.microsoft.com/entra/msal/javascript/browser/errors:
    *
-   *   Try acquireTokenSilent first, then use an interactive redirect when
-   *   MSAL reports that user interaction is required.
+   * 1. ``acquireTokenSilent`` first. Pass-through on success.
+   * 2. On a recoverable error (``InteractionRequiredAuthError``,
+   *    ``monitor_window_timeout`` from blocked silent-SSO iframes,
+   *    ``login_required`` / ``consent_required``), call
+   *    :func:`startInteractiveRecovery` to navigate the user through a
+   *    fresh interactive auth.
    *
-   * Plus one extra recoverable case explicitly called out in those docs:
-   * `BrowserAuthError: monitor_window_timeout`. Microsoft's recommendation
-   * is to either backoff, fix the redirectUri page, or "invoke an
-   * interactive API such as acquireTokenPopup or acquireTokenRedirect" —
-   * we take the last option, which matches third-party-iframe storage
-   * blocking on Chrome 120+ / Edge / Safari (the silent iframe times
-   * out because the cross-site cookie is partitioned).
+   * Recovery uses ``acquireTokenRedirect`` (NOT ``loginRedirect``) as
+   * the first step — that's the documented primitive for refreshing a
+   * known account's tokens without forcing a full re-login. Falls back
+   * to ``loginRedirect`` only when ``acquireTokenRedirect`` itself
+   * fails to navigate (browser policy, popup blocker, etc.).
    *
-   * Before starting that redirect, clear the stale local account/token
-   * cache. This avoids the broken half-authenticated state where the SPA
-   * still renders an account but every API call goes out without a bearer
-   * token after MSAL returned `interaction_required`.
+   * Critically: cache is NEVER cleared before the redirect. The
+   * previous version cleared the account record before calling
+   * ``loginRedirect``; when the redirect failed silently (browser
+   * blocking the navigation), the account record was gone but the
+   * tokens lingered, leaving every subsequent API call to find
+   * ``getAllAccounts() === []``, return null, and ship anonymously
+   * to the API — endless 401s, only manual ``localStorage.clear()``
+   * recovers. This bug is documented in
+   * AzureAD/microsoft-authentication-library-for-js#7551.
    *
-   * Recoverable auth failures reject with `AuthInteractionRequiredError`
-   * after recovery has been started. The error exposes `code` and `cause`
-   * so callers can distinguish a normal interaction-required redirect from
-   * a blocked/failed redirect attempt.
+   * Recoverable auth failures reject with ``AuthInteractionRequiredError``
+   * after recovery has been started. The error exposes ``code`` and
+   * ``cause`` so callers can distinguish a normal interaction-required
+   * redirect from a blocked/failed redirect attempt.
    *
-   * Other `BrowserAuthError` codes (`interaction_in_progress`,
-   * `hash_empty_error`, `hash_does_not_contain_known_properties`,
-   * `block_iframe_reload`) are config / race-condition bugs that another
-   * redirect won't fix — propagate them as null without navigating.
+   * Other ``BrowserAuthError`` codes (``hash_empty_error``,
+   * ``hash_does_not_contain_known_properties``, ``block_iframe_reload``)
+   * are config / race-condition bugs that another redirect won't fix —
+   * propagate them as null without navigating.
    *
-   * The "no account in cache" case is handled at boot by `AuthGuard`,
-   * which calls `loginRedirect` when `accounts.length === 0`. If we
-   * still reach this method without an account, it's an unusual state;
-   * return null and let the next AuthGuard render recover.
+   * The "no account in cache" case is handled by detecting ORPHANED
+   * STATE (no accounts but localStorage has MSAL token entries) and
+   * cleaning the half-corrupted cache before redirecting. Without this,
+   * the page renders authenticated UI but every API call goes anonymous.
    *
-   * Errors are matched by `name` / `errorCode` rather than `instanceof`
-   * because `@azure/msal-browser` is loaded via dynamic import; the
-   * error class identity isn't shared across module boundaries.
+   * Errors are matched by ``name`` / ``errorCode`` rather than
+   * ``instanceof`` because ``@azure/msal-browser`` is loaded via
+   * dynamic import; the error class identity isn't shared across
+   * module boundaries.
    *
-   * `forceRefresh: true` skips MSAL's local cache and goes back to the
+   * ``forceRefresh: true`` skips MSAL's local cache and goes back to the
    * token endpoint with the cached refresh token. Use it from the
    * fetch interceptor when a protected API returns 401 — the first
    * attempt may have used a stale cached access token (claims
@@ -84,6 +92,18 @@ interface AuthState {
     audience?: "api" | "spaces",
     options?: { forceRefresh?: boolean },
   ) => Promise<string | null>;
+
+  /**
+   * Force interactive recovery: start an ``acquireTokenRedirect`` (or
+   * ``loginRedirect`` fallback). Use this from the fetch interceptor
+   * when even a force-refreshed access token still gets rejected by
+   * the resource server (the silent path can't tell us "this is
+   * fundamentally the wrong token" — it has to come from the protected
+   * API saying 401 after we already retried). Throws
+   * ``AuthInteractionRequiredError`` once the redirect has been kicked
+   * off so the caller can stop processing.
+   */
+  recoverFromHardAuthFailure: (reason: unknown) => Promise<never>;
 }
 
 /** Recoverable error codes per MSAL.js docs — every one of these has the
@@ -105,7 +125,14 @@ const RECOVERABLE_ERROR_CODES = new Set([
  * class name as a fallback when the error code isn't set. */
 const INTERACTION_REQUIRED_NAME = "InteractionRequiredAuthError";
 
-let interactiveRecoveryStarted = false;
+/** Module-level deduplication: when N parallel API calls all trip the
+ * recovery path simultaneously, the second-onwards must reuse the first
+ * one's promise rather than each issuing their own redirect. Without
+ * this, MSAL throws ``interaction_in_progress`` on N-1 of them and the
+ * cascading errors mask the actual recovery state. Mirrors the pattern
+ * in the msal-react ``useMsalAuthentication`` hook + the production
+ * patterns linked from Microsoft Learn's "Common errors" guide. */
+let activeRecoveryPromise: Promise<never> | null = null;
 
 function isRecoverableAuthError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
@@ -145,7 +172,7 @@ function createInteractionRequiredError(
 
   if (redirectError) {
     return new AuthInteractionRequiredError(
-      `Authentication interaction required, but login redirect failed (${redirectDetail}). Original token error: ${tokenDetail}.`,
+      `Authentication interaction required, but redirect failed (${redirectDetail}). Original token error: ${tokenDetail}.`,
       {
         code: authErrorCode(redirectError) ?? authErrorCode(tokenError),
         cause: redirectError,
@@ -162,31 +189,98 @@ function createInteractionRequiredError(
   );
 }
 
+/** Storage probe: does the browser have orphaned MSAL token entries with
+ * no matching account record? That state is the "stuck on 401 forever"
+ * signature — getAllAccounts() returns [] but the SPA still has tokens
+ * lingering from a previous session that recovery half-cleaned. Returns
+ * the list of MSAL keys to nuke; empty array means cache is coherent. */
+function findOrphanedMsalKeys(): string[] {
+  if (typeof window === "undefined" || !window.localStorage) return [];
+  const allKeys: string[] = [];
+  for (let i = 0; i < window.localStorage.length; i++) {
+    const k = window.localStorage.key(i);
+    if (k && k.startsWith("msal.")) allKeys.push(k);
+  }
+  const tokenKeys = allKeys.filter((k) =>
+    /\|(?:access|refresh|id)token\|/.test(k),
+  );
+  // No tokens = clean (or never logged in). Tokens AND empty
+  // getAllAccounts means orphaned — caller is the only one who knows
+  // the accounts state, so caller decides whether to nuke.
+  return tokenKeys.length > 0 ? allKeys : [];
+}
+
+function nukeMsalLocalStorage(): void {
+  if (typeof window === "undefined") return;
+  for (const store of [window.localStorage, window.sessionStorage]) {
+    if (!store) continue;
+    const toRemove: string[] = [];
+    for (let i = 0; i < store.length; i++) {
+      const k = store.key(i);
+      if (k && k.startsWith("msal.")) toRemove.push(k);
+    }
+    toRemove.forEach((k) => store.removeItem(k));
+  }
+}
+
 async function startInteractiveRecovery(
   msal: MsalClientApplication,
-  account: MsalAccountInfo,
+  account: MsalAccountInfo | null,
   scope: string,
   reason: unknown,
 ): Promise<never> {
-  let redirectError: unknown;
-  if (!interactiveRecoveryStarted) {
-    interactiveRecoveryStarted = true;
+  // Deduplicate concurrent recovery attempts. Multiple in-flight API
+  // calls can simultaneously detect a stale token and trip recovery;
+  // without this, MSAL throws ``interaction_in_progress`` on every
+  // call after the first.
+  if (activeRecoveryPromise) {
+    return activeRecoveryPromise;
+  }
+
+  activeRecoveryPromise = (async () => {
+    let redirectError: unknown;
     authStore.setState({ user: null, isAuthenticated: false });
-    msal.setActiveAccount(null);
-    await msal.clearCache({ account }).catch(() => undefined);
+
+    // Step 1: ``acquireTokenRedirect`` — the documented primitive for
+    // refreshing a known account's tokens without forcing full
+    // re-auth. Preserves the account record across the navigation,
+    // which is critical: ``loginRedirect`` + pre-redirect
+    // ``clearCache`` (the previous design) caused the orphaned-state
+    // bug we just hit in production (account record gone, tokens
+    // linger, every API call returns null token + 401 forever).
+    if (account) {
+      try {
+        await msal.acquireTokenRedirect({ scopes: [scope], account });
+        // If we reach here without navigating, MSAL settled the promise
+        // before the browser navigation kicked in (test environments,
+        // blocked redirects, etc.). Fall through to loginRedirect.
+      } catch (err) {
+        redirectError = err;
+      }
+    }
+
+    // Step 2: full ``loginRedirect`` fallback. Used when:
+    //   * No account was passed (orphaned-state caller)
+    //   * acquireTokenRedirect threw a non-navigation error
+    //   * acquireTokenRedirect settled without navigating
+    // Still NO ``clearCache`` before this — let MSAL handle its own
+    // state across the navigation. Only nuke localStorage if BOTH
+    // redirect attempts fail (the orphaned-state caller does this
+    // up-front because their state is already corrupt).
     try {
       await msal.loginRedirect({ scopes: [scope] });
     } catch (err) {
-      // The redirect is expected to navigate away; if it settles by throwing,
-      // keep that failure attached so logs/UI can show what blocked recovery.
       redirectError = err;
-    } finally {
-      // In tests or blocked-popup environments the promise can settle without
-      // navigation. Allow a later user action/retry to start recovery again.
-      interactiveRecoveryStarted = false;
     }
+
+    throw createInteractionRequiredError(reason, redirectError);
+  })();
+
+  try {
+    return await activeRecoveryPromise;
+  } finally {
+    activeRecoveryPromise = null;
   }
-  throw createInteractionRequiredError(reason, redirectError);
 }
 
 export const authStore = createStore<AuthState>((set) => ({
@@ -209,14 +303,33 @@ export const authStore = createStore<AuthState>((set) => ({
     if (!msal || !config) return null;
 
     const accounts = msal.getAllAccounts();
+    const scope = config.apiScope;
+
+    // Orphaned-state recovery: ``getAllAccounts()`` returns [] BUT
+    // localStorage still holds MSAL token entries. That happens when a
+    // previous recovery attempt cleared the account record but its
+    // redirect didn't navigate (browser policy, popup blocker, async
+    // race). The SPA renders "logged in" but every API call goes
+    // anonymous. Nuke the orphans + force a fresh redirect so the
+    // user gets unstuck without manually clearing browser storage.
     if (accounts.length === 0) {
-      // No cached account — `AuthGuard` will call `loginRedirect` on
+      const orphans = findOrphanedMsalKeys();
+      if (orphans.length > 0) {
+        nukeMsalLocalStorage();
+        return startInteractiveRecovery(
+          msal,
+          null,
+          scope,
+          new Error(
+            `Detected orphaned MSAL state (${orphans.length} cache entries with no account record); cleaned up + redirecting`,
+          ),
+        );
+      }
+      // Truly logged out — ``AuthGuard`` will call ``loginRedirect`` on
       // its next render. Don't double-redirect from here.
       return null;
     }
 
-    // Single API-scoped token — Spaces accepts both audiences (multi-audience JWT).
-    const scope = config.apiScope;
     const forceRefresh = options?.forceRefresh === true;
 
     try {
@@ -233,4 +346,28 @@ export const authStore = createStore<AuthState>((set) => ({
       return null;
     }
   },
+
+  recoverFromHardAuthFailure: async (reason) => {
+    // Fetch interceptor's escape hatch: silent path produced a token
+    // but the resource server rejected it (audience drift, conditional-
+    // access re-eval, claims challenge, tenant-policy change, etc.).
+    // Same recovery primitive as the silent-failure path —
+    // acquireTokenRedirect → loginRedirect — invoked from the
+    // resource-server signal rather than an MSAL exception.
+    const msal = getMsalInstance();
+    const config = getMsalConfig();
+    if (!msal || !config) {
+      throw new AuthInteractionRequiredError(
+        "Authentication interaction required (no MSAL instance configured).",
+        { cause: reason },
+      );
+    }
+    const accounts = msal.getAllAccounts();
+    return startInteractiveRecovery(
+      msal,
+      accounts[0] ?? null,
+      config.apiScope,
+      reason,
+    );
+  },
 }));

package/src/msal/token-fetch.ts

@@ -48,5 +48,21 @@ export async function tokenFetch(
     return response;
   }
   response.body?.cancel().catch(() => undefined);
-  return dispatch(true);
+  const retried = await dispatch(true);
+  if (retried.status === 401) {
+    // Second 401 after a force-refresh retry — the silent token path
+    // can't recover this (refresh-token grant produces the same
+    // identity claims that just got rejected). Kick off interactive
+    // recovery so a fresh ``loginRedirect`` mints a token bound to
+    // current server policy. ``recoverFromHardAuthFailure`` throws
+    // once the redirect is in flight so we don't return a stale 401
+    // the caller might handle as a real failure.
+    retried.body?.cancel().catch(() => undefined);
+    await authStore
+      .getState()
+      .recoverFromHardAuthFailure(
+        new Error("API returned 401 after force-refresh retry"),
+      );
+  }
+  return retried;
 }