@iloveagents/foundry-agent 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @iloveagents/foundry-agent
 
+## 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.3",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "types": "./src/index.ts",

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

@@ -125,6 +125,26 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     );
   });
 
+  it("recoverFromHardAuthFailure clears cache + starts loginRedirect", async () => {
+    // When the fetch interceptor's force-refresh retry STILL gets 401,
+    // the only correct UX is a fresh ``loginRedirect`` (server policy
+    // drift, audience mismatch, etc.). Same recovery primitive used by
+    // the silent path, but invoked from the resource-server signal
+    // rather than an MSAL exception.
+    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.clearCache).toHaveBeenCalled();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
   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.

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

@@ -84,6 +84,17 @@ interface AuthState {
     audience?: "api" | "spaces",
     options?: { forceRefresh?: boolean },
   ) => Promise<string | null>;
+
+  /**
+   * Force interactive recovery: clear MSAL's cache for the active account
+   * and start a ``loginRedirect``. 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
@@ -233,4 +244,29 @@ export const authStore = createStore<AuthState>((set) => ({
       return null;
     }
   },
+
+  recoverFromHardAuthFailure: async (reason) => {
+    // The silent path produced a token but the resource server rejected
+    // it (audience drift, conditional-access re-eval, claims challenge,
+    // tenant-policy change, etc.). The cached refresh token can't help
+    // — a token minted from it would carry the same identity claims —
+    // so the only correct UX is a full ``loginRedirect`` that produces
+    // a fresh token bound to the current server policy.
+    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();
+    if (accounts.length === 0) {
+      throw new AuthInteractionRequiredError(
+        "Authentication interaction required (no cached account).",
+        { cause: reason },
+      );
+    }
+    return startInteractiveRecovery(msal, accounts[0], 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;
 }