@redacto.io/consent-sdk-react 9.3.0 → 9.4.0

package/src/RedactoPrivacyCenter/components/PrivacyCenterSessionExpired.tsx

@@ -0,0 +1,97 @@
+import { useTranslation } from 'react-i18next';
+import { Clock } from 'lucide-react';
+import { PCButton, PCText, PCTitle } from '../ui';
+import { pcStyles } from '../styles/pcStyles';
+import { getVar } from '../lib/utils';
+import { usePrivacyCenterExitAction } from './AppShell/usePrivacyCenterExitAction';
+
+type PrivacyCenterSessionExpiredProps = {
+  onBack?: 'back' | 'signout';
+};
+
+/**
+ * Terminal screen shown when the session has expired (the refresh token is
+ * dead). Purely presentational — no data fetching happens behind it. Mirrors
+ * PrivacyCenterEmptyState's layout. The exit is MANUAL: an inline CTA (and the
+ * top-bar UserMenu item) reuse the consumer's existing `onBack` prop; nothing
+ * navigates automatically. When `onBack` is absent, only the message shows.
+ */
+export function PrivacyCenterSessionExpired({
+  onBack,
+}: PrivacyCenterSessionExpiredProps) {
+  const { t } = useTranslation();
+  const { enabled, handleAction, label, Icon } = usePrivacyCenterExitAction(onBack);
+
+  return (
+    <div
+      style={{
+        ...pcStyles.flex,
+        ...pcStyles.flexCol,
+        ...pcStyles.itemsCenter,
+        ...pcStyles.justifyCenter,
+        ...pcStyles.textCenter,
+        width: '100%',
+        maxWidth: 460,
+        margin: '0 auto',
+        minHeight: 'min(62vh, 540px)',
+        paddingTop: getVar('--pc-spacing-2xl'),
+        paddingBottom: getVar('--pc-spacing-2xl'),
+        gap: getVar('--pc-spacing-xl'),
+      }}
+    >
+      <div
+        aria-hidden="true"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          width: 168,
+          height: 168,
+          borderRadius: '50%',
+          background:
+            'color-mix(in srgb, var(--pc-primary) 8%, var(--pc-bg-shell))',
+          flexShrink: 0,
+        }}
+      >
+        <Clock size={72} strokeWidth={1.5} color={getVar('--pc-primary')} />
+      </div>
+
+      <div
+        style={{
+          ...pcStyles.flex,
+          ...pcStyles.flexCol,
+          ...pcStyles.itemsCenter,
+          gap: getVar('--pc-spacing-sm'),
+        }}
+      >
+        <PCTitle as="h2" style={{ margin: 0 }}>
+          {t('sessionExpiredTitle')}
+        </PCTitle>
+        <PCText
+          as="p"
+          size="base"
+          color="secondary"
+          align="center"
+          style={{ margin: 0, maxWidth: 400 }}
+        >
+          {t('sessionExpiredDescription')}
+        </PCText>
+      </div>
+
+      {enabled && (
+        <PCButton
+          variant="primary"
+          onClick={handleAction}
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 8,
+          }}
+        >
+          <Icon size={16} strokeWidth={2} />
+          <span>{label}</span>
+        </PCButton>
+      )}
+    </div>
+  );
+}

package/src/RedactoPrivacyCenter/components/constant.ts

@@ -1,3 +1,5 @@
+import type { BadgeVariant, MarkerTint } from './types';
+
 export const GRIEVANCE_TAB_IDS = {
   ALL: 'all',
   PROCESSING: 'processing',
@@ -14,3 +16,26 @@ export {
 
 
 export const MAX_DISPLAYED_PURPOSE_NAMES_IN_ERASURE_MODAL = 3;
+
+// ─── Activity timeline ──────────────────────────────────────────────────────
+
+export const TIMELINE_MARKER_SIZE = 30;
+export const TIMELINE_TIME_COL = '64px';
+export const TIMELINE_MARKER_COL = '34px';
+export const TIMELINE_COL_GAP = 12;
+// Rail sits at the centre of the marker column: time col + gap + half marker col.
+export const TIMELINE_RAIL_LEFT = 64 + TIMELINE_COL_GAP + 17;
+
+// Marker tint per variant — mirrors the PCBadge palette so tag + marker match.
+// Literal `var(--…)` strings (same as getVar) avoid a constants↔utils import cycle.
+export const MARKER_TINT: Record<BadgeVariant, MarkerTint> = {
+  success: { color: 'var(--pc-success)', bg: 'rgba(16, 185, 129, 0.12)' },
+  error: { color: 'var(--pc-error)', bg: 'rgba(239, 68, 68, 0.12)' },
+  warning: { color: 'var(--pc-warning)', bg: 'rgba(245, 158, 11, 0.13)' },
+  info: { color: 'var(--pc-info)', bg: 'rgba(59, 130, 246, 0.12)' },
+  secondary: { color: 'var(--pc-text-secondary)', bg: 'var(--pc-bg-tertiary)' },
+};
+
+// Internal error thrown when an activity page fails to load (surfaced to the
+// user via the i18n `failedToFetchActivityData` toast).
+export const ACTIVITY_FETCH_ERROR_MESSAGE = 'Failed to fetch activity data';

package/src/RedactoPrivacyCenter/components/types.ts

@@ -1,5 +1,7 @@
-import type { ReactNode } from 'react';
+import type { ComponentType, ReactNode } from 'react';
+import type { LucideProps } from 'lucide-react';
 import type {
+  Activity,
   CaseRequest,
   ConsentModalRecord,
 } from '../lib/types';
@@ -90,3 +92,32 @@ export type ModifyConsentModalProps = {
   ) => void;
 };
 
+// ─── Activity timeline ──────────────────────────────────────────────────────
+
+export type BadgeVariant = 'success' | 'error' | 'warning' | 'info' | 'secondary';
+
+export type ActivityCategory = {
+  variant: BadgeVariant;
+  Icon: ComponentType<LucideProps>;
+};
+
+export type MarkerTint = Readonly<{
+  color: string;
+  bg: string;
+}>;
+
+export type ActivityDateGroup = {
+  key: string;
+  label: string;
+  newest: string;
+  items: Activity[];
+};
+
+export type ActivityTimelineProps = Readonly<{
+  activities: Activity[];
+}>;
+
+export type TimelineRowProps = Readonly<{
+  activity: Activity;
+}>;
+

package/src/RedactoPrivacyCenter/context/AuthContext.tsx

@@ -1,5 +1,5 @@
 import { createContext, useContext, useState, useEffect, useCallback, useMemo, type ReactNode } from 'react';
-import { setRefreshTokenCookie, decodeJwtToken } from '../lib/utils';
+import { setRefreshTokenCookie, decodeJwtToken, setSessionExpiredListener } from '../lib/utils';
 import type { AuthContextValue } from './types';
 
 export type { AuthContextValue } from './types';
@@ -80,6 +80,21 @@ export const AuthProvider = ({
     return initialRefreshToken;
   });
 
+  // Terminal "session expired" flag. Set by utils' refresh routines (via the
+  // module listener registered below) when the refresh token is dead; reset when
+  // a new refresh token appears (re-auth) so the breaker and the screen recover
+  // together. Drives the shared session-expired screen and gates all fetching.
+  const [sessionExpired, setSessionExpired] = useState(false);
+  const markSessionExpired = useCallback(() => setSessionExpired(true), []);
+
+  // Bridge the module-level refresh routines to React state. utils calls the
+  // registered listener on terminal failure; this is the same single-instance
+  // singleton model as the OTP refresh circuit breaker.
+  useEffect(() => {
+    setSessionExpiredListener(markSessionExpired);
+    return () => setSessionExpiredListener(null);
+  }, [markSessionExpired]);
+
   // Re-sync when props change (for token refresh scenarios)
   useEffect(() => {
     if (initialAccessToken && typeof initialAccessToken === 'string' && initialAccessToken.trim() !== '') {
@@ -94,6 +109,9 @@ export const AuthProvider = ({
   useEffect(() => {
     if (initialRefreshToken && typeof initialRefreshToken === 'string' && initialRefreshToken.trim() !== '') {
       setRefreshToken(initialRefreshToken);
+      // A fresh refresh token means the user re-authenticated — clear the
+      // terminal state (the breaker auto-re-arms on the next ensureValidToken).
+      setSessionExpired(false);
       if (typeof window !== 'undefined') {
         setRefreshTokenCookie(initialRefreshToken);
       }
@@ -106,6 +124,8 @@ export const AuthProvider = ({
     if (newRefreshToken) {
       setRefreshToken(newRefreshToken);
     }
+    // A successful refresh clears any prior terminal state.
+    setSessionExpired(false);
     // Also update storage
     if (typeof window !== 'undefined') {
       sessionStorage.setItem('access_token', newAccessToken);
@@ -123,7 +143,8 @@ export const AuthProvider = ({
     refreshToken,
     onError,
     updateTokens,
-  }), [accessToken, refreshToken, onError, updateTokens]);
+    sessionExpired,
+  }), [accessToken, refreshToken, onError, updateTokens, sessionExpired]);
 
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
 };

package/src/RedactoPrivacyCenter/context/DataAvailabilityContext.session-expired.test.tsx

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor, cleanup } from '@testing-library/react';
+import {
+  DataAvailabilityProvider,
+  useDataAvailability,
+} from './DataAvailabilityContext';
+
+/**
+ * Regression: when the session is terminally expired, the DataAvailabilityProvider
+ * must NOT fire any data fetch on mount — it goes straight to the 'session-expired'
+ * status so the shell renders the terminal screen instead of (fail-open) content.
+ */
+
+// Mutable auth state shared with the hoisted mock so each test can flip it.
+const auth = vi.hoisted(() => ({
+  current: {
+    accessToken: 'stale-access-token',
+    refreshToken: 'dead-refresh-token',
+    onError: () => false,
+    updateTokens: () => {},
+    sessionExpired: true,
+  },
+}));
+
+vi.mock('../lib/api', () => ({
+  fetchUserConsents: vi.fn(() => Promise.resolve(null)),
+  fetchActivities: vi.fn(() => Promise.resolve(null)),
+  fetchCaseHistory: vi.fn(() => Promise.resolve(null)),
+}));
+
+vi.mock('./AuthContext', () => ({ useAuth: () => auth.current }));
+vi.mock('./OrganizationContext', () => ({
+  useOrganization: () => ({
+    organization: { uuid: 'org-uuid', workspaces: [{ uuid: 'ws-uuid' }] },
+  }),
+}));
+vi.mock('./BaseUrlContext', () => ({ useBaseUrl: () => ({ consentClient: {} }) }));
+vi.mock('../lib/useCurrentLanguage', () => ({
+  useCurrentLanguage: () => ({ langParam: 'en' }),
+}));
+
+import { fetchUserConsents, fetchActivities, fetchCaseHistory } from '../lib/api';
+
+function StatusProbe() {
+  const { status } = useDataAvailability();
+  return <div data-testid="status">{status}</div>;
+}
+
+describe('DataAvailabilityProvider — session-expired gate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    sessionStorage.clear();
+    sessionStorage.setItem('email', 'user@example.com');
+    auth.current = {
+      accessToken: 'stale-access-token',
+      refreshToken: 'dead-refresh-token',
+      onError: () => false,
+      updateTokens: () => {},
+      sessionExpired: true,
+    };
+  });
+
+  afterEach(() => cleanup());
+
+  it('does not fetch and reports session-expired when the session is expired', () => {
+    auth.current.sessionExpired = true;
+
+    render(
+      <DataAvailabilityProvider>
+        <StatusProbe />
+      </DataAvailabilityProvider>,
+    );
+
+    expect(screen.getByTestId('status').textContent).toBe('session-expired');
+    expect(fetchUserConsents).not.toHaveBeenCalled();
+    expect(fetchActivities).not.toHaveBeenCalled();
+    expect(fetchCaseHistory).not.toHaveBeenCalled();
+  });
+
+  it('does fetch when the session is NOT expired (gate is meaningful)', async () => {
+    auth.current.sessionExpired = false;
+
+    render(
+      <DataAvailabilityProvider>
+        <StatusProbe />
+      </DataAvailabilityProvider>,
+    );
+
+    await waitFor(() => expect(fetchUserConsents).toHaveBeenCalled());
+    expect(fetchActivities).toHaveBeenCalled();
+  });
+});

package/src/RedactoPrivacyCenter/context/DataAvailabilityContext.tsx

@@ -14,7 +14,11 @@ import { useOrganization } from './OrganizationContext';
 import { useAuth } from './AuthContext';
 import { useBaseUrl } from './BaseUrlContext';
 
-export type DataAvailabilityStatus = 'checking' | 'has-data' | 'empty';
+export type DataAvailabilityStatus =
+  | 'checking'
+  | 'has-data'
+  | 'empty'
+  | 'session-expired';
 
 type DataAvailabilityContextValue = {
   status: DataAvailabilityStatus;
@@ -36,7 +40,7 @@ const DataAvailabilityContext = createContext<DataAvailabilityContextValue | nul
  */
 export const DataAvailabilityProvider = ({ children }: { children: ReactNode }) => {
   const { organization } = useOrganization();
-  const { accessToken, refreshToken, onError, updateTokens } = useAuth();
+  const { accessToken, refreshToken, onError, updateTokens, sessionExpired } = useAuth();
   const { consentClient } = useBaseUrl();
   const { langParam } = useCurrentLanguage();
 
@@ -141,10 +145,18 @@ export const DataAvailabilityProvider = ({ children }: { children: ReactNode })
   }, [organizationId, workspaceId, authContext, consentClient, langParam]);
 
   useEffect(() => {
+    // Terminal session: never fetch. Bump the run id so any in-flight runCheck
+    // resolves into a no-op (its fail-open path would otherwise flip the status
+    // back to 'has-data' and remount the content), then show the expired screen.
+    if (sessionExpired) {
+      runIdRef.current += 1;
+      setStatus('session-expired');
+      return;
+    }
     if (organizationId && workspaceId && accessToken) {
       void runCheck();
     }
-  }, [organizationId, workspaceId, accessToken, runCheck]);
+  }, [organizationId, workspaceId, accessToken, runCheck, sessionExpired]);
 
   const value = useMemo<DataAvailabilityContextValue>(
     () => ({ status }),

package/src/RedactoPrivacyCenter/context/types.ts

@@ -6,6 +6,10 @@ export type AuthContextValue = Readonly<{
   onError: (error: Error) => boolean;
   // Internal: updates tokens after refresh
   updateTokens: (accessToken: string, refreshToken?: string) => void;
+  // Terminal: true once a refresh failed because the refresh token is
+  // expired/invalid. Consumers gate fetching/rendering on this to show the
+  // shared "session expired" screen and stop all further work.
+  sessionExpired: boolean;
 }>;
 
 export type BaseUrlContextValue = Readonly<{

package/src/RedactoPrivacyCenter/lib/consent-manager/utils.tsx

@@ -1,14 +1,19 @@
 import { useMemo } from 'react';
 import { useTranslation } from 'react-i18next';
 import { ConsentStatusEnum } from '../types';
-import type { PurposeItem } from '../types';
-
-type CsvRow = Partial<PurposeItem> & Record<string, unknown>;
 import { formatDateTime as formatDateTimeShared } from '../../utils/date';
 
 // Re-export shared date formatting
 export const formatDateTime = formatDateTimeShared;
 
+// Leading characters that spreadsheet apps (Excel/Sheets) may interpret as a
+// formula; values starting with these are prefixed with a quote to neutralize
+// CSV formula injection.
+const CSV_FORMULA_TRIGGERS = ['=', '+', '-', '@', '\t', '\r'];
+
+// Byte-order mark so Excel detects UTF-8 and renders localized labels correctly.
+const UTF8_BOM = '\uFEFF';
+
 export const useStatusOptions = () => {
   const { t } = useTranslation();
   return useMemo(
@@ -22,35 +27,32 @@ export const useStatusOptions = () => {
   );
 };
 
-export const exportTableToCSV = (rows: CsvRow[]) => {
+// Rows must be pre-formatted display strings keyed by their (already localized)
+// column header. Each cell is written verbatim so the CSV matches the on-screen
+// table exactly; null/undefined become an empty cell rather than the text "null".
+export const exportTableToCSV = (rows: Record<string, string>[]) => {
   if (!rows || rows.length === 0) {
-    console.warn('No data to export');
     return;
   }
 
-  const excludedFields = ['Action', 'data_elements'];
-  const headers = Array.from(new Set(rows.flatMap((r) => Object.keys(r))))
-    .filter((key) => !excludedFields.includes(key))
-    .map((key) => key.toUpperCase())
-    .join(',');
+  const escape = (value: string | null | undefined) => {
+    const raw = value ?? '';
+    // Defuse spreadsheet formula injection by prefixing risky leading chars.
+    const safe =
+      raw.length > 0 && CSV_FORMULA_TRIGGERS.includes(raw[0]) ? `'${raw}` : raw;
+    return `"${safe.replace(/"/g, '""')}"`;
+  };
 
-  const csvRows = rows.map((row) => {
-    return Object.entries(row)
-      .filter(([key]) => !excludedFields.includes(key))
-      .map(([key, value]) => {
-        let formattedValue = value;
-        if ((key === 'given_date' || key === 'valid_till') && value) {
-          formattedValue = formatDateTime(String(value));
-        }
-        return `"${String(formattedValue).replace(/"/g, '""')}"`;
-      })
-      .join(',');
-  });
+  const columns = Object.keys(rows[0]);
+  const headers = columns.map(escape).join(',');
+  const csvRows = rows.map((row) =>
+    columns.map((col) => escape(row[col])).join(',')
+  );
 
   const csvContent = [headers, ...csvRows].join('\n');
 
   try {
-    const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
+    const blob = new Blob([UTF8_BOM, csvContent], { type: 'text/csv;charset=utf-8;' });
     const url = URL.createObjectURL(blob);
     const link = document.createElement('a');
     link.href = url;

package/src/RedactoPrivacyCenter/lib/constants.ts

@@ -167,21 +167,34 @@ export const DOCUMENT_REQUEST_STATUS_LABEL: Record<DocumentRequestStatus, Docume
   replacement_requested: { labelKey: 'docStatusReplacementRequested', color: STATUS_COLORS.warning.color },
 };
 
-// Activity columns constants
-export const ACTIVITY_COLUMN_SIZES = {
-  TITLE: 220,
-  ACTIVITY_TYPE: 160,
-  DESCRIPTION: 320,
-  TIMESTAMP: 200,
-} as const;
-
-export const ACTIVITY_DESCRIPTION_TRUNCATE_LENGTH = 100;
-
 export const ACTIVITY_DATE_FORMATS = {
   DISPLAY: 'MMM D, YYYY [at] h:mm A',
   TOOLTIP: 'MMMM D, YYYY [at] h:mm:ss A',
+  DATE: 'MMM D, YYYY',
+  TIME: 'h:mm A',
 } as const;
 
+export const ACTIVITY_PAGE_SIZE = 10;
+
+
+// ─── Token refresh ─────────────────────────────────────────────────────────
+
+// Backoff window for *transient* OTP-refresh failures (network / 5xx). After a
+// transient failure we wait at least MIN before the next attempt and grow the
+// window exponentially up to MAX, so a flaky connection can't turn the
+// proactive-refresh path into a request storm (incident 2026-06-22). Terminal
+// failures (expired / already-used token) are handled by the circuit breaker in
+// lib/utils.ts and are not retried at all.
+export const MIN_REFRESH_BACKOFF_MS = 30_000; // 30s
+export const MAX_REFRESH_BACKOFF_MS = 300_000; // 5m
+
+// Where the privacy center persists the refresh token: localStorage (origin-
+// scoped, no path matching) under a Redacto-namespaced key, so it is readable
+// regardless of the host app's basePath and never collides with a host's own
+// `refresh_token` cookie. LEGACY_REFRESH_TOKEN_COOKIE is the cookie name older
+// SDK versions wrote (at path=/privacy-center); only that path is ever cleared.
+export const REFRESH_TOKEN_STORAGE_KEY = 'redacto_pc_refresh_token';
+export const LEGACY_REFRESH_TOKEN_COOKIE = 'refresh_token';
 
 // ─── Notification Hub ──────────────────────────────────────────────────────
 

package/src/RedactoPrivacyCenter/lib/queries.ts

@@ -9,6 +9,7 @@ import {
 } from './api';
 import { useBaseUrl } from '../context/BaseUrlContext';
 import { useCurrentLanguage } from './useCurrentLanguage';
+import { isTerminalRefreshError } from '../api/fetcher';
 import type { SendCaseMessageInput, SubmitDocumentForRequestInput } from './types';
 
 export const useCaseHistory = (
@@ -33,7 +34,10 @@ export const useCaseHistory = (
       return response?.data || [];
     },
     enabled: !!organizationId && !!workspaceId && !!contact && !!consentClient,
-    retry: 1,
+    // Don't retry terminal auth failures — retrying a dead token only adds load
+    // (incident 2026-06-22). Transient failures get a single backed-off retry.
+    retry: (failureCount, error) => !isTerminalRefreshError(error) && failureCount < 1,
+    retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000),
   });
 };
 
@@ -67,7 +71,10 @@ export const useCaseMessages = (
         return ta - tb;
       }),
     enabled: !!organizationId && !!workspaceId && !!caseUuid && !!consentClient,
-    retry: 1,
+    // Don't retry terminal auth failures — retrying a dead token only adds load
+    // (incident 2026-06-22). Transient failures get a single backed-off retry.
+    retry: (failureCount, error) => !isTerminalRefreshError(error) && failureCount < 1,
+    retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000),
   });
 };
 

package/src/RedactoPrivacyCenter/lib/utils.refresh-circuit.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ensureValidToken, isRefreshBlocked, resetRefreshCircuit } from './utils';
+import { ApiError } from '../api/fetcher';
+
+/**
+ * Regression tests for the OTP refresh circuit breaker.
+ *
+ * Production incident 2026-06-22: an embedded Privacy Center retry-looped a dead
+ * refresh token, sending ~9× the normal volume of `POST /otp/refresh` (all fast
+ * terminal rejections) and spiking consent-server CPU. ensureValidToken is the
+ * single chokepoint for every refresh — these tests pin the guarantee that a
+ * terminally-failed token is attempted exactly once until the user re-authenticates,
+ * and that transient failures back off instead of hammering.
+ */
+
+// Minimal JWT with a chosen `exp`. The signature is irrelevant — the SDK only
+// base64-decodes the payload to read `exp`.
+const base64url = (obj: unknown) => btoa(JSON.stringify(obj)).replace(/=+$/, '');
+const makeJwt = (expSeconds: number) =>
+  `${base64url({ alg: 'HS256', typ: 'JWT' })}.${base64url({ exp: expSeconds })}.sig`;
+
+// `exp` in 1970 — always treated as expired, so ensureValidToken always takes the
+// refresh path regardless of wall-clock / fake timers.
+const EXPIRED_ACCESS_TOKEN = makeJwt(1_000);
+const ORG = 'org-uuid';
+const WS = 'ws-uuid';
+
+const makeConsentClient = (
+  refreshOtpToken: (orgId: string, wsId: string, refreshToken: string) => Promise<unknown>
+) => ({ refreshOtpToken: vi.fn(refreshOtpToken) }) as any;
+
+const makeAuthContext = (refreshToken: string) => ({
+  accessToken: EXPIRED_ACCESS_TOKEN,
+  refreshToken,
+  // Return false so the SDK suppresses navigation (jsdom can't navigate). The
+  // circuit breaker trips before onError is consulted, which is what we assert.
+  onError: vi.fn(() => false),
+  updateTokens: vi.fn(),
+});
+
+describe('ensureValidToken — OTP refresh circuit breaker (incident 2026-06-22)', () => {
+  beforeEach(() => {
+    resetRefreshCircuit();
+    sessionStorage.clear();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('attempts a terminally-failed refresh token exactly once across many calls', async () => {
+    const client = makeConsentClient(() =>
+      Promise.reject(new ApiError('Token verification error: Refresh token has expired', { status: 401 }))
+    );
+    const authContext = makeAuthContext('dead-refresh-token');
+
+    // Simulate the 3 pollers + every API call + render-driven effects all hitting
+    // the path while the token is dead.
+    const results: Array<string | null> = [];
+    for (let i = 0; i < 25; i++) {
+      results.push(await ensureValidToken(ORG, WS, undefined, authContext, client));
+    }
+
+    expect(results.every((r) => r === null)).toBe(true);
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1);
+    expect(isRefreshBlocked(authContext)).toBe(true);
+  });
+
+  it('treats "not found / already used" (T0) as terminal, not retryable', async () => {
+    const client = makeConsentClient(() =>
+      Promise.reject(new ApiError('Refresh token not found or already used', { status: 401 }))
+    );
+    const authContext = makeAuthContext('already-used-token');
+
+    await ensureValidToken(ORG, WS, undefined, authContext, client);
+    await ensureValidToken(ORG, WS, undefined, authContext, client);
+
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1);
+  });
+
+  it('resumes refreshing once a new refresh token value appears', async () => {
+    const validAccess = makeJwt(Math.floor(Date.now() / 1000) + 3600);
+    const client = makeConsentClient((_org, _ws, token) =>
+      token === 'dead-refresh-token'
+        ? Promise.reject(new ApiError('Refresh token has expired', { status: 401 }))
+        : Promise.resolve({ access_token: validAccess, refresh_token: 'rotated' })
+    );
+
+    const deadCtx = makeAuthContext('dead-refresh-token');
+    await ensureValidToken(ORG, WS, undefined, deadCtx, client);
+    await ensureValidToken(ORG, WS, undefined, deadCtx, client);
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1); // breaker held the loop
+
+    // User re-authenticated → a *different* refresh token value re-arms the breaker.
+    const freshCtx = makeAuthContext('fresh-refresh-token');
+    const token = await ensureValidToken(ORG, WS, undefined, freshCtx, client);
+
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(2);
+    expect(token).toBe(validAccess);
+    expect(isRefreshBlocked(freshCtx)).toBe(false);
+  });
+
+  it('backs off after a transient failure instead of retrying immediately', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-22T11:00:00Z'));
+
+    const client = makeConsentClient(() =>
+      Promise.reject(new ApiError('Service Unavailable', { status: 503 }))
+    );
+    const authContext = makeAuthContext('flaky-refresh-token');
+
+    await ensureValidToken(ORG, WS, undefined, authContext, client);
+    await ensureValidToken(ORG, WS, undefined, authContext, client);
+    await ensureValidToken(ORG, WS, undefined, authContext, client);
+
+    // One attempt, then the backoff window suppresses the rest (no token-marking —
+    // a 5xx is transient, so the token is NOT permanently dead).
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1);
+    expect(isRefreshBlocked(authContext)).toBe(true);
+
+    // Once the backoff window elapses, a later call is allowed to retry.
+    vi.advanceTimersByTime(31_000); // > MIN_REFRESH_BACKOFF_MS (30s)
+    await ensureValidToken(ORG, WS, undefined, authContext, client);
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(2);
+  });
+});