@redacto.io/consent-sdk-react 9.4.0-beta.0 → 9.5.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redacto.io/consent-sdk-react",
-  "version": "9.4.0-beta.0",
+  "version": "9.5.0-beta.0",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/RedactoPrivacyCenter/PrivacyCenterLayout.tsx

@@ -5,6 +5,7 @@ import type { OrganizationDetail } from './lib/types';
 import {
   checkAndRefreshAuth,
   decodeJwtToken,
+  resolveContactFromJwt,
 } from './lib/utils';
 import { useBaseUrl } from './context/BaseUrlContext';
 import { useAuth } from './context/AuthContext';
@@ -56,10 +57,11 @@ export function PrivacyCenterLayout({ children, slug, onBack }: PrivacyCenterLay
         if (workspaceId) sessionStorage.setItem('pc_workspace_id', workspaceId);
         if (orgSlug) sessionStorage.setItem('pc_org_slug', orgSlug);
 
-        // Extract and set email from JWT for sidebar and consent manager
-        const email = decoded.contact || decoded.primary_email;
-        if (email && typeof email === 'string') {
-          sessionStorage.setItem('email', email);
+        // Resolve the contact identifier (email, or mobile/org_user_id for
+        // mobile-only logins) for the sidebar and consent manager.
+        const contact = resolveContactFromJwt(decoded);
+        if (contact) {
+          sessionStorage.setItem('email', contact);
         }
       }
     }

package/src/RedactoPrivacyCenter/components/AppShell/AppShell.tsx

@@ -22,6 +22,7 @@ import { PageHeader } from './PageHeader';
 import { PCLoader } from '../../ui';
 import { useDataAvailability } from '../../context/DataAvailabilityContext';
 import { PrivacyCenterEmptyState } from '../PrivacyCenterEmptyState';
+import { PrivacyCenterSessionExpired } from '../PrivacyCenterSessionExpired';
 import type { PrivacyCenterLayoutProps } from '../types';
 
 export default function AppShell({
@@ -149,6 +150,10 @@ export default function AppShell({
                   >
                     <PCLoader variant="spinner" color="info" size="lg" />
                   </div>
+                ) : status === 'session-expired' ? (
+                  <div style={{ flex: 1, minWidth: 0, width: '100%' }}>
+                    <PrivacyCenterSessionExpired onBack={onBack} />
+                  </div>
                 ) : status === 'empty' ? (
                   <div style={{ flex: 1, minWidth: 0, width: '100%' }}>
                     <PrivacyCenterEmptyState />

package/src/RedactoPrivacyCenter/components/AppShell/UserMenu.tsx

@@ -1,10 +1,10 @@
-import { useCallback, useEffect, useState, type CSSProperties } from 'react';
-import { useTranslation } from 'react-i18next';
-import { ArrowLeft, ChevronDown, LogOut } from 'lucide-react';
+import { useEffect, useState, type CSSProperties } from 'react';
+import { ChevronDown } from 'lucide-react';
 import { PCAvatar, PCPopover } from '../../ui';
 import { useBranding } from '../../context/BrandingContext';
 import { useOrganization } from '../../context/OrganizationContext';
-import { getVar, signOutPrivacyCenter } from '../../lib/utils';
+import { getVar } from '../../lib/utils';
+import { usePrivacyCenterExitAction } from './usePrivacyCenterExitAction';
 
 type UserMenuProps = {
   onBack?: 'back' | 'signout';
@@ -30,7 +30,6 @@ function initialsFromEmail(email: string): string {
 }
 
 export function UserMenu({ onBack }: UserMenuProps) {
-  const { t } = useTranslation();
   const branding = useBranding();
   const { organization } = useOrganization();
   const [email, setEmail] = useState('');
@@ -39,17 +38,8 @@ export function UserMenu({ onBack }: UserMenuProps) {
     setEmail(readEmail());
   }, []);
 
-  const handleAction = useCallback(() => {
-    if (onBack === 'back') {
-      window.history.back();
-    } else if (onBack === 'signout') {
-      signOutPrivacyCenter();
-      window.history.back();
-    }
-  }, [onBack]);
-
-  const actionLabel = onBack === 'back' ? t('back') : t('signOut');
-  const ActionIcon = onBack === 'back' ? ArrowLeft : LogOut;
+  const { handleAction, label: actionLabel, Icon: ActionIcon } =
+    usePrivacyCenterExitAction(onBack);
 
   const displayName = branding?.brand_name || organization?.name || '';
   const triggerAvatarName = email ? initialsFromEmail(email) : displayName || '?';

package/src/RedactoPrivacyCenter/components/AppShell/usePrivacyCenterExitAction.ts

@@ -0,0 +1,36 @@
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+import { ArrowLeft, LogOut, type LucideIcon } from 'lucide-react';
+import { signOutPrivacyCenter } from '../../lib/utils';
+
+/**
+ * Shared "exit the Privacy Center" action, driven by the consumer's
+ * `onBack` prop ('back' | 'signout'). Centralised so the top-bar UserMenu item
+ * and the session-expired screen's CTA stay in lockstep — same label, icon, and
+ * behaviour. `enabled` is false when the consumer passed no `onBack`, so callers
+ * render no affordance (and nothing ever fires automatically).
+ */
+export function usePrivacyCenterExitAction(onBack?: 'back' | 'signout'): {
+  enabled: boolean;
+  handleAction: () => void;
+  label: string;
+  Icon: LucideIcon;
+} {
+  const { t } = useTranslation();
+
+  const handleAction = useCallback(() => {
+    if (onBack === 'back') {
+      window.history.back();
+    } else if (onBack === 'signout') {
+      signOutPrivacyCenter();
+      window.history.back();
+    }
+  }, [onBack]);
+
+  return {
+    enabled: !!onBack,
+    handleAction,
+    label: onBack === 'back' ? t('back') : t('signOut'),
+    Icon: onBack === 'back' ? ArrowLeft : LogOut,
+  };
+}

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/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, resolveContactFromJwt, setSessionExpiredListener } from '../lib/utils';
 import type { AuthContextValue } from './types';
 
 export type { AuthContextValue } from './types';
@@ -25,12 +25,14 @@ const syncJwtDataToSessionStorage = (accessToken: string): void => {
     return;
   }
 
-  // Extract email from JWT (contact or primary_email), fall back to existing sources
-  const email = decoded.contact || decoded.primary_email
+  // Resolve the user's contact identifier (email, or mobile/org_user_id for
+  // mobile-only logins) so case + consent-management actions have a subject.
+  // Falls back to previously stored values when the token omits identifiers.
+  const contact = resolveContactFromJwt(decoded)
     || sessionStorage.getItem('email')
     || (typeof localStorage !== 'undefined' ? localStorage.getItem('userEmail') : null);
-  if (email && typeof email === 'string') {
-    sessionStorage.setItem('email', email);
+  if (contact && typeof contact === 'string') {
+    sessionStorage.setItem('email', contact);
   }
 
   // Extract organization UUID
@@ -80,6 +82,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 +111,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 +126,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 +145,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/utils.session-expired.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  ensureValidToken,
+  resetRefreshCircuit,
+  setSessionExpiredListener,
+} from './utils';
+import { ApiError } from '../api/fetcher';
+
+/**
+ * Regression tests for the terminal "session expired" signal.
+ *
+ * When the refresh token is expired/invalid, the refresh endpoint must be hit at
+ * most once (the circuit breaker) AND the React tree must be told the session is
+ * over exactly once (so it can show the terminal screen and stop all work). A
+ * transient (5xx/network) failure must NOT raise the terminal signal — those are
+ * retryable and the user is still signed in.
+ */
+
+// Minimal JWT with a chosen `exp` (only the base64 payload is read).
+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 expired, so ensureValidToken always takes the refresh path.
+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 (host handles its own navigation). The terminal signal must fire
+  // regardless of this return value — that is the behaviour under test.
+  onError: vi.fn(() => false),
+  updateTokens: vi.fn(),
+});
+
+describe('ensureValidToken — terminal session-expired signal', () => {
+  beforeEach(() => {
+    resetRefreshCircuit();
+    setSessionExpiredListener(null);
+    sessionStorage.clear();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    setSessionExpiredListener(null);
+    vi.useRealTimers();
+  });
+
+  it('fires the session-expired listener exactly once on a terminal failure', async () => {
+    const onExpired = vi.fn();
+    setSessionExpiredListener(onExpired);
+
+    const client = makeConsentClient(() =>
+      Promise.reject(new ApiError('Refresh token has expired', { status: 401 })),
+    );
+    const authContext = makeAuthContext('dead-refresh-token');
+
+    // Many triggers (pollers + API calls + effects) against the same dead token.
+    const results: Array<string | null> = [];
+    for (let i = 0; i < 10; i++) {
+      results.push(await ensureValidToken(ORG, WS, undefined, authContext, client));
+    }
+
+    expect(results.every((r) => r === null)).toBe(true);
+    // Breaker: the dead refresh token is submitted at most once.
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1);
+    // Terminal signal raised once, even though onError returned false.
+    expect(onExpired).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT fire the listener for a transient (5xx) failure', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-22T11:00:00Z'));
+
+    const onExpired = vi.fn();
+    setSessionExpiredListener(onExpired);
+
+    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);
+
+    // One attempt then backoff suppresses the rest — and the session is NOT
+    // declared terminally expired (the token may still be valid).
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1);
+    expect(onExpired).not.toHaveBeenCalled();
+  });
+
+  it('tolerates a terminal failure with no listener registered (no throw)', async () => {
+    const client = makeConsentClient(() =>
+      Promise.reject(new ApiError('Refresh token has expired', { status: 401 })),
+    );
+    const authContext = makeAuthContext('dead-refresh-token');
+
+    await expect(
+      ensureValidToken(ORG, WS, undefined, authContext, client),
+    ).resolves.toBeNull();
+    expect(client.refreshOtpToken).toHaveBeenCalledTimes(1);
+  });
+});