@iloveagents/foundry-agent 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # @iloveagents/foundry-agent
 
+## 0.1.5
+
 ## 0.1.4
 
 ### Patch Changes

package/package.json

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

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

@@ -125,13 +125,20 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     );
   });
 
-  it("recoverFromHardAuthFailure starts acquireTokenRedirect (preserves account)", async () => {
+  it("recoverFromHardAuthFailure evicts bad account + redirects with prompt:'login'", 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.
+    // we need a fresh interactive auth. Two non-negotiable behaviours
+    // that prevent the "silent redirect loop":
+    //   1. ``clearCache({ account })`` BEFORE redirect — evicts the
+    //      bad refresh-token / claims so MSAL doesn't reuse the same
+    //      poisoned material after the redirect lands.
+    //   2. ``prompt: "login"`` on BOTH redirect primitives — forces
+    //      Entra to re-prompt for credentials instead of silently
+    //      returning the SAME stale token from its server-side SSO
+    //      session.
+    // See GitHub #6840 and the Microsoft Identity Platform "claims
+    // challenge" guidance.
     const msal = mockMsal();
     const reason = new Error("API returned 401 after force-refresh retry");
     await expectInteractiveRecoveryError(
@@ -142,8 +149,41 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
         messageIncludes: ["interaction required"],
       },
     );
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.clearCache).toHaveBeenCalledWith({
+      account: { username: "alice@example.com", localAccountId: "alice-oid" },
+    });
     expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
-    expect(msal.clearCache).not.toHaveBeenCalled();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: "login" }),
+    );
+  });
+
+  it("forwards a claims-challenge payload from the failure reason to MSAL", async () => {
+    // Continuous Access Evaluation / Conditional-Access challenge:
+    // the fetch interceptor extracted ``claims`` from the resource
+    // server's ``WWW-Authenticate`` header and stamped it onto the
+    // recovery reason. The redirect must carry it through so Entra
+    // mints a token that explicitly satisfies the challenge.
+    const msal = mockMsal();
+    const reason = Object.assign(
+      new Error("API returned 401 after force-refresh retry"),
+      { claims: "eyJjbGFpbXMiOiIuLi4ifQ" },
+    );
+    await expectInteractiveRecoveryError(
+      store().recoverFromHardAuthFailure(reason),
+      {
+        code: undefined,
+        cause: reason,
+        messageIncludes: ["interaction required"],
+      },
+    );
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        claims: "eyJjbGFpbXMiOiIuLi4ifQ",
+        prompt: "login",
+      }),
+    );
   });
 
   it("returns null without redirecting when no account is cached", async () => {
@@ -156,12 +196,17 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 
-  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).
+  it("uses acquireTokenRedirect on InteractionRequiredAuthError, evicting the bad account first", async () => {
+    // Canonical 2026 MSAL.js recovery pattern (per Microsoft Identity
+    // Platform docs + GitHub #6840):
+    //   1. ``clearCache({ account })`` — surgical eviction of the bad
+    //      token + claims, BEFORE redirect. The earlier
+    //      "no-clearCache-before-redirect" rule was about the broad
+    //      ``clearCache()`` form (which produces the orphaned-state
+    //      bug); the per-account form is the documented fix.
+    //   2. ``acquireTokenRedirect`` with ``prompt: "login"`` — forces
+    //      re-prompt instead of letting Entra silently reuse the SSO
+    //      session.
     const err = Object.assign(new Error("MFA required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "interaction_required",
@@ -177,15 +222,16 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
         "MFA required",
       ],
     });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.clearCache).toHaveBeenCalledWith({
+      account: { username: "alice@example.com", localAccountId: "alice-oid" },
+    });
     expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
     expect(msal.acquireTokenRedirect).toHaveBeenCalledWith({
       scopes: [config.apiScope],
       account: { username: "alice@example.com", localAccountId: "alice-oid" },
+      prompt: "login",
     });
-    // 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();
   });
 
@@ -211,7 +257,7 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
 
-  it("recovers on consent_required without clearing cache before redirect", async () => {
+  it("recovers on consent_required by evicting bad account + acquireTokenRedirect", async () => {
     const err = Object.assign(new Error("consent required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "consent_required",
@@ -222,11 +268,15 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "consent_required"],
     });
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
-    expect(msal.clearCache).not.toHaveBeenCalled();
+    expect(msal.clearCache).toHaveBeenCalledWith(
+      expect.objectContaining({ account: expect.objectContaining({ localAccountId: "alice-oid" }) }),
+    );
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: "login" }),
+    );
   });
 
-  it("recovers on monitor_window_timeout without clearing cache before redirect", async () => {
+  it("recovers on monitor_window_timeout by evicting bad account + acquireTokenRedirect", 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"), {
@@ -239,8 +289,12 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "monitor_window_timeout"],
     });
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
-    expect(msal.clearCache).not.toHaveBeenCalled();
+    expect(msal.clearCache).toHaveBeenCalledWith(
+      expect.objectContaining({ account: expect.objectContaining({ localAccountId: "alice-oid" }) }),
+    );
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: "login" }),
+    );
   });
 
   it("does NOT redirect on interaction_in_progress (would race with another flow)", async () => {
@@ -281,8 +335,10 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "InteractionRequiredAuthError"],
     });
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
-    expect(msal.clearCache).not.toHaveBeenCalled();
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: "login" }),
+    );
   });
 
   it("preserves redirect failure details when both redirect attempts fail", async () => {
@@ -315,11 +371,17 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
         "interaction_required",
       ],
     });
-    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();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: "login" }),
+    );
+    expect(msal.loginRedirect).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: "login" }),
+    );
+    // Per-account cache eviction DID happen as the canonical pre-
+    // redirect step (see GitHub #6840). The "no clearCache" rule
+    // applies only to the broad ``clearCache()`` form, not the
+    // ``clearCache({ account })`` variant we use here.
+    expect(msal.clearCache).toHaveBeenCalledOnce();
   });
 });
 
@@ -426,3 +488,109 @@ describe("authStore — orphaned-state recovery", () => {
     expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 });
+
+describe("authStore — block_iframe_reload defuse", () => {
+  // MSAL.js refuses to redirect when the current URL fragment still
+  // carries a prior silent-auth failure (``#error=…``). In production
+  // we shipped clearCache + prompt:'login' but users were STILL stuck
+  // because the redirect itself was aborting with
+  // ``BrowserAuthError: block_iframe_reload``. The fix:
+  // ``startInteractiveRecovery`` must strip the error fragment from
+  // the URL with ``history.replaceState`` BEFORE calling
+  // ``acquireTokenRedirect`` / ``loginRedirect``.
+
+  const config = {
+    clientId: "test-client",
+    authority: "https://login.microsoftonline.com/test-tenant",
+    redirectUri: "http://localhost:8010",
+    apiScope: "api://test-api/access_as_user",
+  };
+
+  function mockMsal(overrides: Record<string, unknown> = {}) {
+    const account = { username: "alice@example.com", localAccountId: "alice-oid" };
+    const mock = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
+      getAllAccounts: vi.fn().mockReturnValue([account]),
+      loginRedirect: vi.fn().mockResolvedValue(undefined),
+      logoutRedirect: vi.fn().mockResolvedValue(undefined),
+      setActiveAccount: vi.fn(),
+      acquireTokenSilent: vi.fn().mockResolvedValue({ accessToken: "fresh" }),
+      acquireTokenRedirect: vi.fn().mockResolvedValue(undefined),
+      acquireTokenPopup: vi.fn().mockResolvedValue({ accessToken: "popup" }),
+      ...overrides,
+    };
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(mock);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(config);
+    return mock;
+  }
+
+  beforeEach(() => {
+    // Reset URL fragment between tests.
+    window.history.replaceState(null, "", "/");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    window.history.replaceState(null, "", "/");
+  });
+
+  it("strips a stale MSAL error fragment before calling acquireTokenRedirect", async () => {
+    window.history.replaceState(
+      null,
+      "",
+      "/spaces/some-entity?foo=bar" +
+        "#error=interaction_required" +
+        "&error_description=AADSTS160021%3a+Application+requested+a+user+session+which+does+not+exist" +
+        "&state=eyJpZCI6IngifQ%3D%3D",
+    );
+    expect(window.location.hash).toContain("error=interaction_required");
+
+    const msal = mockMsal();
+    const reason = new Error("API returned 401 after force-refresh retry");
+    let acquireRedirectHash: string | null = null;
+    msal.acquireTokenRedirect = vi.fn(async () => {
+      acquireRedirectHash = window.location.hash;
+    });
+
+    await expect(authStore.getState().recoverFromHardAuthFailure(reason)).rejects.toBeInstanceOf(AuthInteractionRequiredError);
+
+    // By the time MSAL's redirect API is called, the page fragment
+    // has been wiped. MSAL won't see the stale ``error=`` and won't
+    // trip its ``block_iframe_reload`` guard.
+    expect(acquireRedirectHash).toBe("");
+    // Path + query string are preserved so the post-redirect landing
+    // page is the SAME page the user was on when their session went
+    // bad.
+    expect(window.location.pathname).toBe("/spaces/some-entity");
+    expect(window.location.search).toBe("?foo=bar");
+  });
+
+  it("leaves a clean URL alone (no spurious history mutation)", async () => {
+    window.history.replaceState(null, "", "/spaces?clean=1");
+    const original = window.location.href;
+    const msal = mockMsal();
+    await expect(authStore
+        .getState()
+        .recoverFromHardAuthFailure(new Error("policy drift"))).rejects.toBeInstanceOf(AuthInteractionRequiredError);
+    // Path + query stay identical (no replaceState invocation).
+    expect(window.location.href).toBe(original);
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+  });
+
+  it("strips error_code / error_uri fragments too (not just error_description)", async () => {
+    window.history.replaceState(
+      null,
+      "",
+      "/spaces#error_code=AADSTS160021&error_uri=https%3a%2f%2flogin.example",
+    );
+    const msal = mockMsal();
+    let hashAtRedirect: string | null = null;
+    msal.acquireTokenRedirect = vi.fn(async () => {
+      hashAtRedirect = window.location.hash;
+    });
+    await expect(authStore.getState().recoverFromHardAuthFailure(new Error("x"))).rejects.toBeInstanceOf(AuthInteractionRequiredError);
+    expect(hashAtRedirect).toBe("");
+  });
+});

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

@@ -1,5 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createServiceFetch } from "../client/service-fetch.ts";
+import {
+  createServiceFetch,
+  parseClaimsChallengeFromWwwAuthenticate,
+} from "../client/service-fetch.ts";
 
 describe("createServiceFetch", () => {
   let fetchSpy: ReturnType<typeof vi.spyOn>;
@@ -352,6 +355,65 @@ describe("createServiceFetch", () => {
       expect(recoverFromHardAuthFailure).not.toHaveBeenCalled();
     });
 
+    it("kicks off interactive recovery when acquireToken throws on retry", async () => {
+      // Hard expiry path: refresh-token window closed (24h SPA cap) or
+      // claims challenge pending. The force-refresh retry's
+      // ``acquireToken`` rejects BEFORE the second fetch leaves the
+      // browser. Without this branch the throw bubbles up to callers
+      // that have bare ``catch {}`` (e.g. useContentTreeStore.fetchSchemas)
+      // and the user is stuck in a silent 401 loop with no re-auth UI.
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const msalError = new Error("InteractionRequiredAuthError: refresh token expired");
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockRejectedValueOnce(msalError);
+      const recoverFromHardAuthFailure = vi
+        .fn()
+        .mockRejectedValue(new Error("loginRedirect in flight"));
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      // The wrapped TokenAcquisitionError propagates as the thrown
+      // error; recovery has already kicked off by then.
+      await expect(serviceFetch("/api/spaces/entities")).rejects.toThrow();
+      expect(fetchSpy).toHaveBeenCalledTimes(1); // second fetch never left
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+      expect(recoverFromHardAuthFailure).toHaveBeenCalledTimes(1);
+      // Recovery receives the ORIGINAL MSAL error, not the wrapper —
+      // telemetry / logging downstream should see the real cause.
+      expect(recoverFromHardAuthFailure.mock.calls[0]![0]).toBe(msalError);
+    });
+
+    it("does NOT call recoverFromHardAuthFailure on transport errors during retry", async () => {
+      // Regression for review feedback on PR #30: the retry-catch must
+      // distinguish auth failures (TokenAcquisitionError) from
+      // generic transport failures (network drop, AbortError, CORS
+      // preflight reject). The latter must NOT trigger loginRedirect
+      // — that would bounce users through Entra ID on any flaky-wifi
+      // moment.
+      fetchSpy.mockReset();
+      const networkErr = new TypeError("NetworkError: Failed to fetch");
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockRejectedValueOnce(networkErr);
+      const acquireToken = vi.fn().mockResolvedValue("token");
+      const recoverFromHardAuthFailure = vi.fn();
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      // Network error propagates as-is; no recovery attempted.
+      await expect(serviceFetch("/api/spaces/entities")).rejects.toBe(networkErr);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2); // both attempts got a token
+      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
@@ -376,3 +438,88 @@ describe("createServiceFetch", () => {
     });
   });
 });
+
+describe("parseClaimsChallengeFromWwwAuthenticate", () => {
+  it("returns undefined when header is missing", () => {
+    expect(parseClaimsChallengeFromWwwAuthenticate(null)).toBeUndefined();
+    expect(parseClaimsChallengeFromWwwAuthenticate(undefined)).toBeUndefined();
+    expect(parseClaimsChallengeFromWwwAuthenticate("")).toBeUndefined();
+  });
+
+  it("returns undefined when Bearer challenge carries no claims", () => {
+    const header = 'Bearer realm="example", error="invalid_token"';
+    expect(parseClaimsChallengeFromWwwAuthenticate(header)).toBeUndefined();
+  });
+
+  it("extracts quoted claims payload", () => {
+    // Microsoft Identity Platform CAE / Conditional Access challenge
+    // shape — base64url payload inside double quotes.
+    const claims = "eyJhY2Nlc3NfdG9rZW4iOnsibmJmIjp7ImVzc2VudGlhbCI6dHJ1ZSwidmFsdWUiOiIxNjAwMDAwMDAwIn19fQ";
+    const header = `Bearer realm="example", error="insufficient_claims", claims="${claims}"`;
+    expect(parseClaimsChallengeFromWwwAuthenticate(header)).toBe(claims);
+  });
+
+  it("extracts unquoted token68 claims payload", () => {
+    const claims = "eyJhY2Nlc3NfdG9rZW4iOnsibmJmIjp7ImVzc2VudGlhbCI6dHJ1ZX19fQ";
+    const header = `Bearer claims=${claims}`;
+    expect(parseClaimsChallengeFromWwwAuthenticate(header)).toBe(claims);
+  });
+
+  it("ignores non-Bearer challenges", () => {
+    const header = 'Basic realm="x", Digest realm="y", claims="ignored"';
+    expect(parseClaimsChallengeFromWwwAuthenticate(header)).toBeUndefined();
+  });
+
+  it("picks the Bearer claims even when other challenges are present", () => {
+    const header = 'Basic realm="x", Bearer realm="api", error="insufficient_claims", claims="ABC123"';
+    expect(parseClaimsChallengeFromWwwAuthenticate(header)).toBe("ABC123");
+  });
+});
+
+describe("createServiceFetch — claims-challenge passthrough", () => {
+  let fetchSpy: ReturnType<typeof vi.fn>;
+  beforeEach(() => {
+    fetchSpy = vi.fn();
+    globalThis.fetch = fetchSpy as unknown as typeof globalThis.fetch;
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("forwards a WWW-Authenticate claims challenge through recoverFromHardAuthFailure", async () => {
+    // Resource server returned 401 with a CAE claims challenge. The
+    // retry succeeds at the token level (forceRefresh produced a
+    // fresh access token) but the server STILL rejects because the
+    // user needs a step-up. Recovery must carry the challenge to
+    // MSAL so the next token explicitly satisfies it.
+    const claims = "eyJjbGFpbXMiOiJBQkMifQ";
+    fetchSpy
+      .mockResolvedValueOnce(new Response(null, { status: 401 }))
+      .mockResolvedValueOnce(
+        new Response(null, {
+          status: 401,
+          headers: {
+            "WWW-Authenticate": `Bearer realm="api", error="insufficient_claims", claims="${claims}"`,
+          },
+        }),
+      );
+    const acquireToken = vi
+      .fn()
+      .mockResolvedValueOnce("stale")
+      .mockResolvedValueOnce("fresh");
+    const recoverFromHardAuthFailure = vi
+      .fn()
+      .mockRejectedValue(new Error("redirecting"));
+    const serviceFetch = createServiceFetch({
+      acquireToken,
+      recoverFromHardAuthFailure,
+    });
+
+    await expect(serviceFetch("/api/spaces/entities")).rejects.toThrow();
+    expect(recoverFromHardAuthFailure).toHaveBeenCalledTimes(1);
+    const reason = recoverFromHardAuthFailure.mock.calls[0]![0];
+    // Stamped onto the recovery reason so auth-store can forward it
+    // to MSAL.acquireTokenRedirect({ claims }).
+    expect((reason as { claims?: string }).claims).toBe(claims);
+  });
+});

package/src/client/service-fetch.ts

@@ -66,6 +66,26 @@ export type ServiceFetch = (
   init?: RequestInit,
 ) => Promise<Response>;
 
+/**
+ * Wrapper thrown when ``acquireToken`` rejects inside the fetch
+ * interceptor. Lets the outer 401-retry layer distinguish
+ * token-acquisition failures (which warrant interactive recovery) from
+ * generic ``fetch`` rejections like network drops, aborts, or CORS
+ * preflight failures (which do NOT — those would needlessly bounce the
+ * user through ``loginRedirect`` on a transient transport error).
+ *
+ * Exported so hosts that wrap ``serviceFetch`` further can ``instanceof``
+ * against the same class without re-declaring it.
+ */
+export class TokenAcquisitionError extends Error {
+  override readonly name = "TokenAcquisitionError";
+  readonly cause: unknown;
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.cause = cause;
+  }
+}
+
 const defaultOriginResolver = (): string =>
   typeof window !== "undefined" ? window.location.origin : "";
 
@@ -134,11 +154,15 @@ export function createServiceFetch(options: ServiceFetchOptions): ServiceFetch {
             headers.set("Authorization", `Bearer ${token}`);
           }
         } catch (error) {
-          // A thrown token acquisition error usually means the auth layer
-          // is starting an interactive recovery. Do not downgrade protected
-          // API calls to anonymous requests; that creates noisy 401s and
-          // stale UI.
-          throw error;
+          // A thrown token-acquisition error usually means the auth layer
+          // is starting an interactive recovery. Do not downgrade
+          // protected API calls to anonymous requests; that creates
+          // noisy 401s and stale UI. Wrap the error so the outer
+          // 401-retry layer can distinguish it from generic ``fetch``
+          // rejections (network drops, aborts, CORS preflight fails)
+          // and only escalate to ``recoverFromHardAuthFailure`` for
+          // genuine auth failures.
+          throw new TokenAcquisitionError(error);
         }
       }
       if (input instanceof Request) {
@@ -173,25 +197,122 @@ 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);
-    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.
+
+    // Two failure shapes for the retry:
+    //   (a) The force-refreshed token grant FAILS — refresh token gone
+    //       (24h SPA cap), interaction-required claims challenge, etc.
+    //       ``acquireToken`` throws inside ``dispatch`` BEFORE the fetch
+    //       leaves the browser. ``dispatch`` re-throws wrapped in
+    //       ``TokenAcquisitionError`` so we can distinguish this case
+    //       from network errors below.
+    //   (b) The grant succeeds but the resource server STILL rejects
+    //       the token (audience drift, server-side policy change). The
+    //       retried response status is 401.
+    // Both must funnel into ``recoverFromHardAuthFailure`` so the auth
+    // layer can kick off ``loginRedirect`` — the only correct UX for a
+    // hard expiry. We treat the two auth paths symmetrically.
+    //
+    // We deliberately do NOT trigger recovery on generic ``dispatch``
+    // throws (TypeError from network drops, AbortError from caller
+    // cancellation, CORS-preflight failures, etc.) — those are
+    // transient transport problems, not auth state corruption, and
+    // bouncing the user through ``loginRedirect`` for a flaky network
+    // would be a much worse UX than letting the error propagate.
+    let retried: Response;
+    try {
+      retried = await dispatch(true);
+    } catch (err) {
+      if (err instanceof TokenAcquisitionError && options.recoverFromHardAuthFailure) {
+        // ``recoverFromHardAuthFailure`` is expected to throw once the
+        // redirect is in flight; if it returns (e.g. test stub) we
+        // re-throw the wrapped original so the caller still sees the
+        // auth failure rather than a phantom recovery. We pass the
+        // unwrapped ``cause`` to recovery so it sees the real MSAL
+        // error (InteractionRequiredAuthError etc.) for telemetry.
+        await options.recoverFromHardAuthFailure(err.cause);
+      }
+      throw err;
+    }
+
+    // Hard auth failure path (b): even the force-refreshed token got
+    // rejected. 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. 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) {
+      // Continuous Access Evaluation / Conditional-Access claims
+      // challenge passthrough. When the resource server requires a
+      // step-up (MFA, device compliance, revocation invalidation),
+      // it returns 401 with ``WWW-Authenticate: Bearer ... claims="…"``.
+      // We forward the payload through the recovery callback so the
+      // auth layer's redirect carries it to Entra ID and the
+      // re-minted token satisfies the exact challenge. Without it,
+      // Entra re-issues the same already-rejected claims set and the
+      // user loops back into the broken state.
+      const claims = parseClaimsChallengeFromWwwAuthenticate(
+        retried.headers.get("www-authenticate"),
+      );
       retried.body?.cancel().catch(() => undefined);
+      const reason = new AuthInteractionRequiredError(
+        "API returned 401 after force-refresh retry",
+        claims ? { claims } : 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"),
-      );
+      await options.recoverFromHardAuthFailure(reason);
     }
     return retried;
   };
 }
+
+/**
+ * Error class the fetch interceptor raises (and forwards through
+ * ``recoverFromHardAuthFailure``) when a 401 needs interactive
+ * recovery. Exposed so the auth-layer recovery can pick up a
+ * ``claims`` field if one was extracted from the
+ * ``WWW-Authenticate`` header.
+ */
+export class AuthInteractionRequiredError extends Error {
+  override readonly name = "AuthInteractionRequiredError";
+  readonly claims?: string;
+  constructor(message: string, options?: { claims?: string }) {
+    super(message);
+    this.claims = options?.claims;
+  }
+}
+
+/**
+ * Extract the claims challenge string from a resource server's
+ * ``WWW-Authenticate: Bearer ... claims="…"`` header. Returns
+ * ``undefined`` when the header is missing, malformed, or carries
+ * no claims directive.
+ *
+ * The value is forwarded VERBATIM to MSAL's
+ * ``acquireTokenRedirect({ claims })``; MSAL handles the
+ * base64-url decode + JSON parse itself. We don't try to validate
+ * the inner shape — letting Entra speak for itself avoids drift if
+ * the schema evolves.
+ *
+ * Spec: RFC 6750 ``WWW-Authenticate`` + CAE claims-challenge
+ * supplement (Microsoft Identity Platform docs).
+ */
+export function parseClaimsChallengeFromWwwAuthenticate(
+  header: string | null | undefined,
+): string | undefined {
+  if (!header) return undefined;
+  // ``WWW-Authenticate`` can carry multiple challenges separated by
+  // commas (e.g. ``Basic realm="x", Bearer ...``). We only care
+  // about the Bearer challenge.
+  const bearer = header.match(/Bearer\s+([^,]+(?:,(?!\s*[A-Za-z]+\s)[^,]*)*)/i);
+  if (!bearer) return undefined;
+  // Inside the Bearer params, find ``claims="..."`` (quoted) or
+  // ``claims=token68`` (unquoted, base64url).
+  const quoted = bearer[1].match(/claims\s*=\s*"([^"]*)"/i);
+  if (quoted) return quoted[1].length > 0 ? quoted[1] : undefined;
+  const unquoted = bearer[1].match(/claims\s*=\s*([A-Za-z0-9_\-+/=]+)/i);
+  if (unquoted) return unquoted[1].length > 0 ? unquoted[1] : undefined;
+  return undefined;
+}

package/src/msal/auth-config.ts

@@ -27,7 +27,12 @@ export interface MsalClientApplication {
   handleRedirectPromise(): Promise<unknown>;
   clearCache(request?: { account?: MsalAccountInfo }): Promise<void>;
   getAllAccounts(): MsalAccountInfo[];
-  loginRedirect(request: { scopes: string[]; prompt?: string }): Promise<void>;
+  loginRedirect(request: {
+    scopes: string[];
+    prompt?: string;
+    /** Same claims-challenge passthrough as ``acquireTokenRedirect``. */
+    claims?: string;
+  }): Promise<void>;
   logoutRedirect(): Promise<void>;
   setActiveAccount(account: MsalAccountInfo | null): void;
   acquireTokenSilent(request: {
@@ -47,6 +52,25 @@ export interface MsalClientApplication {
   acquireTokenRedirect(request: {
     scopes: string[];
     account: MsalAccountInfo;
+    /**
+     * Force a fresh interactive login regardless of Entra SSO state.
+     * Without ``prompt: "login"``, when the user still has a live
+     * Entra session, the redirect silently round-trips and returns
+     * THE SAME stale token / claims — leaving the SPA back in the
+     * exact broken state we tried to recover from. See
+     * https://learn.microsoft.com/entra/identity-platform/msal-error-handling-js
+     * "Hard expiry / silent redirect loop" pattern.
+     */
+    prompt?: string;
+    /**
+     * Optional Continuous Access Evaluation / Conditional Access
+     * claims challenge payload, parsed from a resource-server 401
+     * response's ``WWW-Authenticate: Bearer ... claims="..."``
+     * header. When present, MSAL passes it through to Entra so the
+     * issued token explicitly satisfies the challenge (MFA step-up,
+     * device-compliance refresh, revocation invalidation, etc.).
+     */
+    claims?: string;
   }): Promise<void>;
   acquireTokenPopup(request: {
     scopes: string[];

package/src/msal/auth-store.ts

@@ -237,38 +237,113 @@ async function startInteractiveRecovery(
     return activeRecoveryPromise;
   }
 
+  // Extract a claims challenge from the failure reason (if any).
+  // Production scenarios that surface here with a payload:
+  //   * Conditional Access re-eval (MFA step-up required).
+  //   * Continuous Access Evaluation revocation.
+  //   * Device-compliance change mid-session.
+  // The service-fetch interceptor parses WWW-Authenticate when it
+  // can and stamps the payload onto the recovery reason — we pass
+  // it through to MSAL so the next token explicitly satisfies the
+  // challenge. Without this, Entra would silently re-issue the same
+  // already-rejected claims set and we'd loop right back.
+  const claims = extractClaimsChallenge(reason);
+
   activeRecoveryPromise = (async () => {
     let redirectError: unknown;
     authStore.setState({ user: null, isAuthenticated: false });
 
-    // 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).
+    // Step 0: strip a lingering MSAL error hash from the URL before
+    // attempting any redirect. MSAL.js's redirect primitives refuse
+    // to navigate with ``BrowserAuthError: block_iframe_reload`` when
+    // the current page URL still carries a previous silent-auth
+    // failure in its fragment (e.g.
+    // ``#error=interaction_required&error_description=AADSTS160021…``
+    // from an earlier ``handleRedirectPromise`` that surfaced
+    // "user session does not exist"). The SDK's own anti-loop guard
+    // sees the unconsumed error and aborts — leaving the user
+    // permanently stuck unless they manually clear browser state.
+    //
+    // We can defuse that guard cleanly by replacing the URL with a
+    // fragment-less copy via ``history.replaceState`` before the
+    // redirect call. MSAL then sees a "clean" page and proceeds.
+    // The original page state (path + search) is preserved so the
+    // user lands back where they started after re-auth.
+    //
+    // Reference:
+    //   https://aka.ms/msal.js.errors#block_iframe_reload
+    //   https://github.com/AzureAD/microsoft-authentication-library-for-js/issues/5623
+    stripStaleMsalErrorHash();
+
+    // Step 1: surgically evict the bad account record from MSAL's
+    // own token cache BEFORE redirecting. Two reasons:
+    //
+    //  (a) The bad refresh token / claims set is what's causing the
+    //      hard-auth failure. Leaving it in cache means MSAL's
+    //      acquireTokenSilent (called by every other in-flight or
+    //      post-redirect request) hands out the SAME poisoned token
+    //      until the entry naturally expires.
+    //  (b) Microsoft's "orphaned-state" anti-pattern is about
+    //      clearing AFTER initiating a redirect (i.e. clearing while
+    //      MSAL is mid-flight). Clearing the SPECIFIC account
+    //      BEFORE the redirect is the documented pattern — see
+    //      https://github.com/AzureAD/microsoft-authentication-library-for-js/issues/6840
+    //      and the SDK's own ``IPublicClientApplication.clearCache``
+    //      contract which accepts ``{ account }``.
+    //
+    // Wrapped in a try/catch so a cache-removal hiccup doesn't
+    // strand the user without ever attempting the redirect.
     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,
+        await msal.clearCache({ account });
+      } catch (err) {
+        // Telemetry only — keep flowing into the redirect path.
+        // eslint-disable-next-line no-console
+        console.warn(
+          "[msal-recovery] clearCache(account) failed; continuing with redirect",
+          err,
+        );
+      }
+    }
+
+    // Step 2: ``acquireTokenRedirect`` with ``prompt: "login"`` —
+    // forces a fresh interactive authentication even if Entra still
+    // has a live SSO session for the user. Without ``prompt: "login"``
+    // the redirect silently round-trips through Entra and returns a
+    // token built from the SAME state we just tried to escape from
+    // (this is the "silent redirect loop" users actually experience:
+    // the page bounces to login.microsoftonline.com and back, still
+    // broken). The full re-auth path produces a fresh refresh-token
+    // + fresh claims bound to current server policy.
+    if (account) {
+      try {
+        await msal.acquireTokenRedirect({
+          scopes: [scope],
+          account,
+          prompt: "login",
+          ...(claims ? { claims } : {}),
+        });
+        // If we reach here without navigating, MSAL settled the
+        // promise before browser navigation kicked in (test envs,
         // 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).
+    // Step 3: full ``loginRedirect`` fallback. Same ``prompt: "login"``
+    // contract so even this path can't loop back into broken state.
+    // Used when:
+    //   * No account was passed (orphaned-state caller already
+    //     wiped localStorage upstream).
+    //   * acquireTokenRedirect threw a non-navigation error.
+    //   * acquireTokenRedirect settled without navigating.
     try {
-      await msal.loginRedirect({ scopes: [scope] });
+      await msal.loginRedirect({
+        scopes: [scope],
+        prompt: "login",
+        ...(claims ? { claims } : {}),
+      });
     } catch (err) {
       redirectError = err;
     }
@@ -283,6 +358,75 @@ async function startInteractiveRecovery(
   }
 }
 
+/**
+ * Pull a CAE / Conditional-Access claims-challenge payload out of a
+ * recovery-trigger error. Two shapes are produced upstream:
+ *
+ *   * The fetch interceptor (``service-fetch``) parses the
+ *     ``WWW-Authenticate`` header on a 401 response and constructs
+ *     an error whose ``claims`` (or ``cause.claims``) field carries
+ *     the base64 payload it found.
+ *   * MSAL.js's own ``InteractionRequiredAuthError`` instances expose
+ *     ``claims`` directly when Azure returned one.
+ *
+ * Return ``undefined`` when none is present — callers should NOT
+ * pass an empty string to MSAL (the SDK treats that as "ignore" but
+ * older versions choke on the empty key).
+ */
+/**
+ * Replace the page's URL fragment with an empty one when it carries
+ * a leftover MSAL/Entra error response (``#error=…``,
+ * ``#error_description=…``, ``#error_code=…``, or
+ * ``#error_uri=…``). Preserves path + query string so the user
+ * lands back on the same page after the imminent recovery redirect.
+ *
+ * Why this is necessary:
+ *   MSAL.js's redirect primitives include an anti-loop guard that
+ *   refuses to navigate when the current URL fragment encodes a
+ *   prior auth error — the SDK raises ``block_iframe_reload``
+ *   instead of redirecting. In production we hit this when an
+ *   earlier ``acquireTokenSilent`` had its hidden iframe receive an
+ *   ``AADSTS160021: Application requested a user session which does
+ *   not exist`` response, MSAL surfaced it via
+ *   ``handleRedirectPromise`` but left the fragment intact.
+ *   Subsequent recovery redirects all aborted with
+ *   ``block_iframe_reload`` and the user was stuck until they
+ *   manually cleared browser storage.
+ *
+ * This helper is a no-op on non-browser environments and a no-op
+ * when no error fragment is present.
+ */
+function stripStaleMsalErrorHash(): void {
+  if (typeof window === "undefined" || typeof history === "undefined") return;
+  const hash = window.location.hash || "";
+  if (!hash) return;
+  // ``hash`` is e.g. ``#error=interaction_required&error_description=…``.
+  // We look for any of the error-shaped keys MSAL emits.
+  if (!/(?:^|[#&])error(?:_description|_code|_uri)?=/.test(hash)) return;
+  try {
+    const cleanUrl = window.location.pathname + window.location.search;
+    history.replaceState(null, "", cleanUrl);
+  } catch {
+    // Some embedded environments lock down history.replaceState
+    // (sandboxed iframes etc.). If that happens we still try the
+    // redirect — MSAL may or may not succeed; nothing we can do.
+  }
+}
+
+function extractClaimsChallenge(reason: unknown): string | undefined {
+  if (!reason || typeof reason !== "object") return undefined;
+  const direct = (reason as { claims?: unknown }).claims;
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  const cause = (reason as { cause?: unknown }).cause;
+  if (cause && typeof cause === "object") {
+    const fromCause = (cause as { claims?: unknown }).claims;
+    if (typeof fromCause === "string" && fromCause.length > 0) {
+      return fromCause;
+    }
+  }
+  return undefined;
+}
+
 export const authStore = createStore<AuthState>((set) => ({
   user: null,
   isAuthenticated: false,