@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/security/AuthSessionContext.js

@@ -3,8 +3,10 @@ import { createContext, useState, useMemo, useEffect, useCallback, useRef } from
 import { startAuthentication } from '@simplewebauthn/browser';
 import { AuthMethod, AuthFactorLevel, AuthSessionPurpose, SessionType, isWildoBackendError, } from '@wildo-ai/saas-models';
 import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
+import { isAuthoritativeRefreshRejection, isRefreshDevLenient } from '../../core/requests/auth-refresh-resilience.frontend.js';
 import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
 import { useI18n } from '../../core/i18n/useI18n.js';
+import { resolveComponentLabel } from '../../core/i18n/component-label-resolution.utils.js';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
 import { useError } from '../../core/errors/useError.js';
 import { useApplication } from '../../core/runtime/useApplication.js';
@@ -16,6 +18,22 @@ import { FrontendComponentType, MfaChallengeLabel, UserAuthLabel } from '@wildo-
 const logger = LoggerFrontendService.getLogger();
 const logDebug = logger.debugByType('AuthSessionContext');
 logger.setDebugTypeLogging('AuthSessionContext', false);
+function extractAuthErrorMessage(error, fallback) {
+    const guidanceExplanation = error?.wildoError?.userGuidance?.explanation
+        || error?.response?.data?.error?.userGuidance?.explanation;
+    if (typeof guidanceExplanation === 'string' && guidanceExplanation.length > 0) {
+        return guidanceExplanation;
+    }
+    const detailsMessage = error?.response?.data?.error?.details?.message;
+    if (typeof detailsMessage === 'string' && detailsMessage.length > 0) {
+        return detailsMessage;
+    }
+    const contextMessage = error?.context?.message;
+    if (typeof contextMessage === 'string' && contextMessage.length > 0) {
+        return contextMessage;
+    }
+    return error?.message || fallback;
+}
 /**
  * AuthSession Context
  * @internal - Use useAuthSession() hook instead of accessing this directly
@@ -27,18 +45,39 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
     const { handleError } = useError();
     const { tComponent, isReady } = useI18n({ component: [FrontendComponentType.PUBLIC_LAYOUTS_USER_AUTH, FrontendComponentType.PUBLIC_LAYOUTS_MFA_CHALLENGE] });
     const { appConfig } = useApplication();
-    const { connect, disconnect, switchOrganization: wsSwitchOrganization } = useWebSocket();
+    const { connect, disconnect, refreshAuth: refreshWebSocketAuth, switchOrganization: wsSwitchOrganization } = useWebSocket();
     const { clearAnonymousSession } = useAnonymousSession();
     const hasInitializedRef = useRef(false);
     const broadcastChannelRef = useRef(null);
     const refreshInFlightRef = useRef(null);
+    // Holds the latest `tokenRenewalHandler` so `connectWebSocket` (defined far
+    // earlier in this component) can hand the WebSocket layer a stable
+    // `onAuthenticationError` callback without a definition-order / stale-closure
+    // dependency on the handler. Kept current by the registration effect below.
+    const tokenRenewalHandlerRef = useRef(null);
     const [auth, setAuth] = useState({
         ...EMPTY_AUTH_STATE,
         accessToken: tokenStorage.getAccessToken(),
-        refreshToken: tokenStorage.getRefreshToken(),
+        // Auth-hardening Slice A Step 6 (2026-04-13) — `AuthState` no
+        // longer carries a `refreshToken` field. The refresh token lives
+        // exclusively in the `__wildo_refresh` `HttpOnly` cookie (set by
+        // the backend, scoped `Path=/api/v1/auth`). `EphemeralSessionTokenStorage`
+        // may still hold a value for one-off / test contexts via its own
+        // in-memory slot but `AuthSessionContext` deliberately never
+        // mirrors it into React state — the cookie is the sole source of
+        // truth for the rotation channel.
     });
-    const storeAuthTokens = (accessToken, refreshToken) => {
-        tokenStorage.storeTokens(accessToken, refreshToken);
+    /**
+     * Auth-hardening Slice A Step 3 (2026-04-13) — `storeAuthTokens` now only
+     * carries the access token. The refresh token travels via the
+     * `__wildo_refresh` `HttpOnly` cookie (set by the backend on every issuance
+     * / rotation, scoped `Path=/api/v1/auth`). We pass `null` to
+     * `tokenStorage.storeTokens` so any stale localStorage refresh token from a
+     * pre-migration session is wiped on the next call (and `EphemeralSessionTokenStorage`
+     * stops accumulating an in-memory value that nothing reads).
+     */
+    const storeAuthTokens = (accessToken) => {
+        tokenStorage.storeTokens(accessToken, null);
         if (accessToken) {
             clearAnonymousSession();
         }
@@ -93,8 +132,22 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 organizationId: organizationId || undefined,
                 consumableToken: consumableToken || undefined,
                 autoReconnect: true,
-                reconnectInterval: 5000,
-                maxReconnectAttempts: 5,
+                // Base retry delay only — the transport grows it exponentially toward its
+                // 30s cap (see WebSocketContext.performActualConnect). A large budget plus
+                // the connectivity supervisor (online / visibility / watchdog re-arm) means
+                // the socket recovers indefinitely instead of dying after a handful of
+                // attempts, so these are resilient defaults rather than a hard ceiling.
+                reconnectInterval: 1000,
+                maxReconnectAttempts: 15,
+                // Self-heal an expired access token WITHOUT depending on HTTP traffic or
+                // window focus. When the handshake is rejected for auth, the WS layer
+                // calls this; `tokenRenewalHandler` performs the resilient refresh and,
+                // on success, seeds the fresh token back into the socket via
+                // `refreshWebSocketAuth`, so the next reconnect handshake succeeds. This
+                // keeps a backgrounded/unfocused tab's real-time background jobs flowing
+                // across token expiry. Read via ref because the handler is defined after
+                // this callback (see `tokenRenewalHandlerRef`).
+                onAuthenticationError: () => tokenRenewalHandlerRef.current?.(),
             });
             logDebug('WebSocket connection initiated', { wsUrl });
         }
@@ -124,7 +177,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             return resp;
         }
         catch (e) {
-            const msg = e?.message || 'Identification failed';
+            const msg = extractAuthErrorMessage(e, 'Identification failed');
             handleError(e, 'Identification failed', { email, message: msg });
             setAuth(a => ({ ...a, isLoading: false, error: msg }));
             throw e;
@@ -164,8 +217,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 return resp;
             }
             const accessToken = resp.accessToken || null;
-            const refreshToken = resp.refreshToken || null;
-            storeAuthTokens(accessToken, refreshToken);
+            storeAuthTokens(accessToken);
             if (accessToken) {
                 getManualCallsHttpClient().setAuthToken(accessToken);
                 setResourcesAuthToken(accessToken);
@@ -176,7 +228,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken,
-                    refreshToken,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -188,14 +239,13 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken,
-                    refreshToken,
                     sessionId: resp.success ? null : sessionId,
                 }));
             }
             return resp;
         }
         catch (e) {
-            const msg = e?.message || 'Authentication failed';
+            const msg = extractAuthErrorMessage(e, 'Authentication failed');
             handleError(e, 'Authentication failed', { email, message: msg });
             setAuth(a => ({ ...a, isLoading: false, error: msg }));
             throw e;
@@ -227,8 +277,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 return resp;
             }
             const accessToken = resp.accessToken || null;
-            const refreshToken = resp.refreshToken || null;
-            storeAuthTokens(accessToken, refreshToken);
+            storeAuthTokens(accessToken);
             if (accessToken) {
                 getManualCallsHttpClient().setAuthToken(accessToken);
                 setResourcesAuthToken(accessToken);
@@ -239,7 +288,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken,
-                    refreshToken,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -251,15 +299,15 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken,
-                    refreshToken,
                     sessionId: resp.success ? null : sessionId,
                 }));
             }
             return resp;
         }
         catch (e) {
-            handleError(e, 'Authentication failed', { method: request.method });
-            setAuth(a => ({ ...a, isLoading: false, error: e?.message || 'Authentication failed' }));
+            const msg = extractAuthErrorMessage(e, 'Authentication failed');
+            handleError(e, 'Authentication failed', { method: request.method, message: msg });
+            setAuth(a => ({ ...a, isLoading: false, error: msg }));
             throw e;
         }
     };
@@ -284,18 +332,10 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
      * Calls GET /auth/oauth2/authorize/:providerRef to get the authorization URL,
      * then performs a full-page redirect to that URL.
      *
-     * [Capacitor] [OAuth2] [SAML]
-     * When running inside Ionic Capacitor, `window.location.href` must NOT be used
-     * because it navigates the WebView away from the app (losing state). Instead:
-     * - Use `@capacitor/browser` → `Browser.open({ url: authorizationUrl })` which opens
-     *   ASWebAuthenticationSession (iOS) / Chrome Custom Tabs (Android) per RFC 8252.
-     * - The return path uses deep links (Universal Links / App Links) instead of route navigation.
-     * - For Apple/Google on mobile, prefer initiateNativeSignIn() which uses the native SDK
-     *   and exchanges the identity token via POST /auth/native-token/exchange (F2).
-     *   This provides a seamless system sign-in UI and handles both consumer and enterprise accounts.
-     * - For other providers (GitHub, Microsoft), use Browser.open() + deep-link return.
-     * - This method should be refactored behind a platform abstraction: web → window.location.href,
-     *   Capacitor → Browser.open() or initiateNativeSignIn() depending on the provider.
+     * Browser-only flow. The framework targets web stacks exclusively (the engine's
+     * value prop is sharing TypeScript across browser-rendered surfaces — SAAS_APP,
+     * STATIC_WEBSITE, TECH_DOC), so no native-SDK / Capacitor / Electron variants
+     * exist for this method.
      */
     const initiateOAuth2Login = useCallback(async (providerRef, returnUrl) => {
         logDebug('Initiating OAuth2 login', { providerRef, returnUrl });
@@ -303,8 +343,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         try {
             const { authorizationUrl } = await getManualCallsHttpClient().getOAuth2AuthorizationUrl(providerRef, returnUrl);
             logDebug('Redirecting to OAuth2 provider', { providerRef, authorizationUrl });
-            // Full-page redirect to the OAuth2 provider
-            // [Capacitor] Replace with Browser.open({ url: authorizationUrl }) when Capacitor is introduced
             window.location.href = authorizationUrl;
         }
         catch (e) {
@@ -315,36 +353,91 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         }
     }, [handleError]);
     /**
-     * Handle the OAuth2 callback by exchanging the one-time code for tokens.
-     * Called from the /auth/callback page after the backend redirects back.
-     * Flow: Backend callback → consumable token → redirect to /auth/callback?code=xxx → this method
+     * Exchange a single-use AUTH_CODE_EXCHANGE consumable token for a JWT pair
+     * via `POST /auth/token/exchange`.
+     *
+     * Renamed from `handleOAuth2Callback` in cross-app-jwt-propagation
+     * Step 5's deferred refactor pass — the method handles BOTH issuance
+     * flows that mint AUTH_CODE_EXCHANGE codes, so the OAuth2-specific
+     * naming was misleading:
      *
-     * [Capacitor] [OAuth2] [SAML]
-     * This method is intentionally decoupled from React Router navigation — it accepts
-     * a `code` string and handles the exchange. On web, AuthPage_AuthCallback extracts
-     * the code from URL params and calls this. On Capacitor, the same method will be called
-     * from the App.addListener('appUrlOpen') deep link handler, parsing the code from the
-     * incoming URL. No changes needed to this method for Capacitor — the caller changes.
+     *   - **OAuth2 callback** (`AuthPage_AuthCallback` route): the backend
+     *     OAuth2 callback handler mints a code AFTER the user returns from
+     *     the IdP. The exchange response carries `{accessToken, expiresIn}`
+     *     only — the rotated refresh token lives in the `Set-Cookie:
+     *     __wildo_refresh=…` header (Auth-hardening A-Step 6 cookie-only
+     *     contract; pre-A-Step-6 the body also carried `refreshToken`).
+     *   - **Cross-frontend handoff** (`AuthPage_AuthExchange` route, mounted
+     *     at `CommonRoutePaths.authExchange = '/auth/exchange'`): the backend
+     *     `crossFrontendHandoff()` handler mints a code via the same
+     *     AUTH_CODE_EXCHANGE primitive. The exchange response ALSO carries
+     *     `{returnPath, sourceFrontendServiceName, targetServiceKey}` (see
+     *     `TokenExchangeResponseSchema`), surfaced into
+     *     `auth.crossFrontendHandoffContext` for the receiving component
+     *     (`Auth_OneOffSession` in `cross-frontend-handoff` mode) to drive
+     *     post-exchange navigation.
+     *
+     * Discrimination ("did this code come from a handoff?") is purely by
+     * presence of `returnPath` in the response — see `TokenExchangeResponseSchema`
+     * JSDoc for the load-bearing `typeof returnPath === 'string'` invariant.
+     *
+     * Browser-only flow. The method is intentionally decoupled from React
+     * Router navigation — it accepts a `code` string and performs the
+     * exchange; the page-level component extracts the code from URL params
+     * and calls this. The framework targets web stacks exclusively, so no
+     * native deep-link variant exists.
      */
-    const handleOAuth2Callback = useCallback(async (code) => {
-        logDebug('Handling OAuth2 callback', { codeLength: code.length });
+    const handleAuthCodeExchange = useCallback(async (code) => {
+        logDebug('Handling AUTH_CODE_EXCHANGE token (OAuth2 callback or cross-frontend handoff)', { codeLength: code.length });
         setAuth(a => ({ ...a, isLoading: true, error: null }));
         try {
-            const { accessToken, refreshToken } = await getManualCallsHttpClient().exchangeOAuth2Code(code);
-            storeAuthTokens(accessToken, refreshToken);
+            const response = await getManualCallsHttpClient().exchangeAuthCode(code);
+            const { accessToken, returnPath, sourceFrontendServiceName, targetServiceKey } = response;
+            storeAuthTokens(accessToken);
             getManualCallsHttpClient().setAuthToken(accessToken);
             setResourcesAuthToken(accessToken);
-            logDebug('OAuth2 callback successful, tokens stored');
+            // Cross-frontend-handoff signal: the issuer (cross-app-jwt-propagation
+            // Step 2) puts `returnPath` into the consumable-token metadata; the
+            // exchange handler (Step 5) round-trips it back here. OAuth2-callback
+            // codes do NOT carry it, so a missing field correctly leaves the
+            // context undefined for the OAuth2 path. The receiving component
+            // (`Auth_OneOffSession` mounted at `/auth/exchange` in
+            // cross-frontend-handoff mode) reads `crossFrontendHandoffContext`
+            // and navigates accordingly.
+            //
+            // Discriminator invariant: `typeof returnPath === 'string'` is the
+            // ONLY signal that distinguishes a handoff-issued exchange from an
+            // OAuth2-callback exchange (no `kind` discriminator field is sent
+            // over the wire — see `TokenExchangeResponseSchema` rationale in
+            // `cross-frontend-handoff.shared.dto.schemas.ts`). The backend
+            // controller is contractually required to use omit-when-absent (NOT
+            // emit `null` or `''`) for OAuth2 codes; the
+            // `TokenExchangeResponseSchema.parse()` call in `tokenExchange()`
+            // and the integration test in
+            // `cross-frontend-handoff-token-exchange.integration.test.ts`
+            // jointly enforce this. If both safety nets ever regress, this
+            // discriminator silently flips to false-positives and OAuth2 users
+            // would land with a stale handoff context.
+            const crossFrontendHandoffContext = typeof returnPath === 'string'
+                ? {
+                    returnPath,
+                    ...(sourceFrontendServiceName !== undefined && { sourceFrontendServiceName }),
+                    ...(targetServiceKey !== undefined && { targetServiceKey }),
+                }
+                : undefined;
+            logDebug('OAuth2 callback successful, tokens stored', {
+                isCrossFrontendHandoff: crossFrontendHandoffContext !== undefined,
+            });
             // Update auth state — mark as restoring so UserOrgsContext picks up and loads user data
             setAuth(a => ({
                 ...a,
                 isLoading: false,
                 accessToken,
-                refreshToken,
                 isRestoringSession: true,
                 sessionRestored: false,
                 // Clear any previous session (OAuth2 bypasses identify/authenticate flow)
                 sessionId: null,
+                crossFrontendHandoffContext,
             }));
             hasInitializedRef.current = true;
         }
@@ -355,67 +448,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             throw e;
         }
     }, [setResourcesAuthToken, handleError]);
-    /**
-     * Exchange a native identity token (from Apple/Google SDK) for Wildo JWT tokens.
-     * Called after the Capacitor native SDK returns an identity token.
-     *
-     * This method is platform-agnostic — it sends the raw identity token to the backend.
-     * The caller (initiateNativeSignIn or a Capacitor plugin callback) provides the token.
-     *
-     * [Capacitor] The backend POST /auth/native-token/exchange endpoint validates the
-     * identity token via JWKS, provisions/links the user, and returns Wildo JWTs.
-     */
-    const handleNativeTokenExchange = useCallback(async (provider, identityToken, nonce) => {
-        logDebug('Handling native token exchange', { provider });
-        setAuth(a => ({ ...a, isLoading: true, error: null }));
-        try {
-            const result = await getManualCallsHttpClient().exchangeNativeToken({
-                provider,
-                identityToken,
-                nonce,
-            });
-            const accessToken = result.accessToken;
-            const refreshToken = result.refreshToken ?? null;
-            storeAuthTokens(accessToken, refreshToken);
-            getManualCallsHttpClient().setAuthToken(accessToken);
-            setResourcesAuthToken(accessToken);
-            logDebug('Native token exchange successful, tokens stored', { provider, isNewUser: result.isNewUser });
-            setAuth(a => ({
-                ...a,
-                isLoading: false,
-                accessToken,
-                refreshToken,
-                isRestoringSession: true,
-                sessionRestored: false,
-                sessionId: null,
-            }));
-            hasInitializedRef.current = true;
-        }
-        catch (e) {
-            const msg = e?.message || 'Native token exchange failed';
-            handleError(e, 'Native token exchange failed', { provider, message: msg });
-            setAuth(a => ({ ...a, isLoading: false, error: msg }));
-            throw e;
-        }
-    }, [setResourcesAuthToken, handleError]);
-    /**
-     * Trigger native Sign-In SDK flow for the given provider, then exchange the token.
-     *
-     * [Capacitor] NOT YET IMPLEMENTED — requires @capacitor-community/apple-sign-in
-     * (Apple) or @codetrix-studio/capacitor-google-auth (Google) to be installed and
-     * configured. Once implemented, this method will:
-     *   1. Call the native SDK to present the system sign-in UI
-     *   2. Receive the identity token + optional nonce
-     *   3. Call handleNativeTokenExchange() with the token
-     *
-     * For enterprise Google SSO on Capacitor, this same flow applies — the native
-     * Google SDK handles both consumer and Workspace accounts transparently.
-     */
-    const initiateNativeSignIn = useCallback(async (_provider) => {
-        throw new Error('Not yet implemented: Capacitor native SDK sign-in. ' +
-            'Install @capacitor-community/apple-sign-in or @codetrix-studio/capacitor-google-auth ' +
-            'and implement the native SDK call here.');
-    }, []);
     /**
      * Handle email verification by exchanging the verification token for JWT tokens.
      * Called from the /confirm-email page after the user clicks the verification link.
@@ -429,7 +461,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         try {
             const response = await getManualCallsHttpClient().verifyEmail(token, email);
             if (response.accessToken) {
-                storeAuthTokens(response.accessToken, response.refreshToken ?? null);
+                storeAuthTokens(response.accessToken);
                 getManualCallsHttpClient().setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Email verification successful, tokens stored');
@@ -437,7 +469,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken: response.accessToken,
-                    refreshToken: response.refreshToken ?? null,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -471,12 +502,12 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         }
     }, [setResourcesAuthToken, handleError]);
     const acceptInvitation = useCallback(async (params) => {
-        logDebug('Handling invitation acceptance', { hasPassword: !!params.password });
+        logDebug('Handling invitation acceptance', { hasPassword: !!params.password, credentialMethod: params.credentialMethod });
         setAuth(a => ({ ...a, isLoading: true, error: null }));
         try {
             const response = await getManualCallsHttpClient().acceptInvitation(params);
             if (response.accessToken) {
-                storeAuthTokens(response.accessToken, response.refreshToken ?? null);
+                storeAuthTokens(response.accessToken);
                 getManualCallsHttpClient().setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Invitation acceptance successful, tokens stored');
@@ -484,7 +515,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken: response.accessToken,
-                    refreshToken: response.refreshToken ?? null,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -516,6 +546,11 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     error: null,
                 }));
             }
+            // PASSKEY-enroll-at-accept: hand the pre-generated WebAuthn registration challenge back to
+            // the caller so it can run the browser ceremony and complete it against the authenticated
+            // `/auth/passkey/register/verify` route (the access token was just set on the HTTP client
+            // above). Present only on the passkey path's session-issued branch; undefined otherwise.
+            return { passkeyRegistrationOptions: response.passkeyRegistrationOptions };
         }
         catch (e) {
             const msg = e?.message || 'Invitation acceptance failed';
@@ -547,8 +582,13 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 }));
                 return response;
             }
-            if (response.success && response.accessToken && response.refreshToken) {
-                storeAuthTokens(response.accessToken, response.refreshToken);
+            // Auth-hardening Slice A Step 6 (2026-04-13): the cookie-only
+            // contract means `response.refreshToken` no longer exists on the
+            // wire — the rotated value lives in the `Set-Cookie:
+            // __wildo_refresh=…` response header (HttpOnly, JS-invisible).
+            // Gate on `success && accessToken` only.
+            if (response.success && response.accessToken) {
+                storeAuthTokens(response.accessToken);
                 getManualCallsHttpClient().setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Magic link verification successful, tokens stored');
@@ -556,7 +596,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken: response.accessToken,
-                    refreshToken: response.refreshToken,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -593,8 +632,10 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 rememberMe: false,
                 requestedIntegrations: [],
             });
-            if (response.success && response.accessToken && response.refreshToken) {
-                storeAuthTokens(response.accessToken, response.refreshToken);
+            // Auth-hardening Slice A Step 6 (2026-04-13): cookie-only contract
+            // — see the magic-link gate above for the full rationale.
+            if (response.success && response.accessToken) {
+                storeAuthTokens(response.accessToken);
                 client.setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('MFA verification successful, tokens stored');
@@ -602,7 +643,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken: response.accessToken,
-                    refreshToken: response.refreshToken,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -630,7 +670,11 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         logDebug('Handling passkey authentication', { sessionId, factorLevel });
         setAuth(a => ({ ...a, isLoading: true, error: null }));
         const componentType = factorLevel === 'first' ? FrontendComponentType.PUBLIC_LAYOUTS_USER_AUTH : FrontendComponentType.PUBLIC_LAYOUTS_MFA_CHALLENGE;
-        const t = (key) => tComponent(componentType, key);
+        const t = (key) => resolveComponentLabel({
+            tComponent,
+            componentType,
+            key,
+        });
         const passkeyErrorLabel = factorLevel === 'first' ? UserAuthLabel.PASSKEY_ERROR : MfaChallengeLabel.PASSKEY_ERROR;
         const passkeyCancelledLabel = factorLevel === 'first' ? UserAuthLabel.PASSKEY_CANCELLED : MfaChallengeLabel.PASSKEY_CANCELLED;
         try {
@@ -652,8 +696,10 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 }));
                 return response;
             }
-            if (response.success && response.accessToken && response.refreshToken) {
-                storeAuthTokens(response.accessToken, response.refreshToken);
+            // Auth-hardening Slice A Step 6 (2026-04-13): cookie-only contract
+            // — see the magic-link gate above for the full rationale.
+            if (response.success && response.accessToken) {
+                storeAuthTokens(response.accessToken);
                 client.setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Passkey authentication successful, tokens stored');
@@ -661,7 +707,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                     ...a,
                     isLoading: false,
                     accessToken: response.accessToken,
-                    refreshToken: response.refreshToken,
                     isRestoringSession: true,
                     sessionRestored: false,
                     sessionId: null,
@@ -708,8 +753,8 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         try {
             const client = getManualCallsHttpClient();
             const response = await client.exchangeOneOffToken(token);
-            const { accessToken, refreshToken, consumableTokenValue, tokenExpiresAt, context } = response;
-            storeAuthTokens(accessToken, refreshToken);
+            const { accessToken, consumableTokenValue, tokenExpiresAt, context } = response;
+            storeAuthTokens(accessToken);
             client.setAuthToken(accessToken);
             setResourcesAuthToken(accessToken);
             if (consumableTokenValue) {
@@ -723,7 +768,6 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             setAuth({
                 ...EMPTY_AUTH_STATE,
                 accessToken,
-                refreshToken,
                 sessionType: SessionType.ONE_OFF,
                 oneOffContext: {
                     originTokenId: context.tokenId,
@@ -747,16 +791,20 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
     }, [tokenStorage, setResourcesAuthToken, setResourcesConsumableToken, connectWebSocket, handleError]);
     const logout = useCallback(() => {
         logDebug('Logging out user');
-        // Attempt to revoke refresh token on the backend (fire-and-forget).
-        // We read the token BEFORE clearing storage so we have the value.
-        const storedRefreshToken = tokenStorage.getRefreshToken();
-        if (storedRefreshToken) {
-            getManualCallsHttpClient()
-                .logoutFromBackend(storedRefreshToken)
-                .catch((e) => {
-                logger.warn('Backend logout call failed (token revocation)', { error: e });
-            });
-        }
+        // Auth-hardening Slice A Step 3 (2026-04-13) — refresh token now travels
+        // via the `__wildo_refresh` `HttpOnly` cookie. JS can't read it (and
+        // doesn't need to): the cookie auto-attaches via `withCredentials: true`
+        // on `/auth/*` because of the `authCookiesInterceptor`. Backend
+        // `logout()` handler dual-reads (cookie-first, body-fallback per A-K-5)
+        // and ALWAYS clears the cookie, so this fire-and-forget call works even
+        // when the JS access token was lost (e.g., post tab crash). We keep
+        // this unconditional now — there's no JS-visible "is there a session
+        // to revoke?" signal anymore.
+        getManualCallsHttpClient()
+            .logoutFromBackend()
+            .catch((e) => {
+            logger.warn('Backend logout call failed (token revocation)', { error: e });
+        });
         broadcastChannelRef.current?.postMessage({ type: 'LOGOUT' });
         disconnect();
         // Clear consumable token from HTTP client singletons (prevents stale header leakage)
@@ -769,6 +817,20 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         hasInitializedRef.current = false;
         logger.info('User logged out successfully');
     }, [disconnect, tokenStorage, setResourcesAuthToken, setResourcesConsumableToken]);
+    /**
+     * Single-use clear for the cross-frontend-handoff context.
+     *
+     * Called by `Auth_OneOffSession` on unmount in cross-frontend-handoff
+     * mode (which happens AFTER the post-exchange `<Navigate to>` resolves
+     * and React unmounts the receiver). Unmount-cleanup timing is critical:
+     * clearing earlier would race the `useMemo(targetUrl, [auth.crossFrontendHandoffContext, …])`
+     * recomputation and could navigate the user to home instead of `returnPath`.
+     */
+    const clearCrossFrontendHandoffContext = useCallback(() => {
+        setAuth(a => (a.crossFrontendHandoffContext === undefined
+            ? a
+            : { ...a, crossFrontendHandoffContext: undefined }));
+    }, []);
     /**
      * Mark session as restored (called by UserOrgsContext when it finishes loading user data)
      */
@@ -799,40 +861,89 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
      * call is made and all callers share the same promise.
      */
     const tokenRenewalHandler = useCallback(async () => {
-        // If a refresh is already in flight, piggyback on it
+        // If a refresh is already in flight IN THIS TAB, piggyback on it.
         if (refreshInFlightRef.current) {
-            logDebug('Token refresh already in flight, waiting for result');
+            logger.debug('Auth token renewal already in flight; waiting for shared result');
             return refreshInFlightRef.current;
         }
-        const doRefresh = async () => {
-            const storedRefreshToken = tokenStorage.getRefreshToken();
-            if (!storedRefreshToken) {
-                throw new Error('No refresh token available');
-            }
-            logDebug('Refreshing access token');
-            const result = await getManualCallsHttpClient().refreshTokens(storedRefreshToken);
-            // Store the new tokens
-            storeAuthTokens(result.accessToken, result.refreshToken ?? null);
-            // Update HTTP clients with new access token
+        // The access token that just failed verification. Captured before we take
+        // the cross-tab lock so that, once we hold it, we can detect whether
+        // another tab already rotated a fresh token into shared storage while we
+        // were waiting (see `adoptCrossTabRefreshedToken`).
+        const staleAccessToken = tokenStorage.getAccessToken();
+        // Adopt — WITHOUT a network call — an access token that another tab already
+        // rotated into the shared store while we were queued on the cross-tab lock.
+        // Returns the adopted token, or `null` if storage still holds the stale
+        // token (meaning THIS tab must perform the network rotation).
+        const adoptCrossTabRefreshedToken = () => {
+            const current = tokenStorage.getAccessToken();
+            if (current && current !== staleAccessToken) {
+                getManualCallsHttpClient().setAuthToken(current);
+                setResourcesAuthToken(current);
+                setAuth(a => (a.accessToken === current ? a : { ...a, accessToken: current }));
+                refreshWebSocketAuth(current);
+                logger.debug('Auth token renewal short-circuited; adopted token rotated by another tab');
+                return current;
+            }
+            return null;
+        };
+        // The actual network rotation + local propagation. Assumes the caller holds
+        // the cross-tab refresh lock (or that no lock primitive is available).
+        const performNetworkRefresh = async () => {
+            // Auth-hardening Slice A Step 3 (2026-04-13) — refresh token travels via
+            // the `__wildo_refresh` `HttpOnly` cookie. JS can't see the cookie
+            // (`HttpOnly` blocks DOM reads), so we can't pre-check whether a refresh
+            // is even possible; we just attempt the call.
+            logger.debug('Auth token renewal started');
+            const result = await getManualCallsHttpClient().refreshTokens();
+            // Persist the rotated access token. The rotated refresh token landed in
+            // the `__wildo_refresh` cookie via `Set-Cookie` on the same response —
+            // the browser cookie store updated automatically; no JS plumbing needed.
+            storeAuthTokens(result.accessToken);
             getManualCallsHttpClient().setAuthToken(result.accessToken);
             setResourcesAuthToken(result.accessToken);
-            // Update React state
+            // Update React state — only the access token surfaces here.
             setAuth(a => ({
                 ...a,
                 accessToken: result.accessToken,
-                refreshToken: result.refreshToken ?? a.refreshToken,
             }));
-            // Broadcast refreshed tokens to other tabs to prevent concurrent refresh
-            // race conditions that trigger rotation detection and force-logout all tabs
+            // Broadcast the rotated ACCESS token so other tabs adopt it instead of
+            // independently refreshing. The rotated refresh token is NOT broadcast —
+            // it already landed in the shared same-origin `__wildo_refresh` cookie.
             broadcastChannelRef.current?.postMessage({
                 type: 'TOKEN_REFRESHED',
                 accessToken: result.accessToken,
-                refreshToken: result.refreshToken ?? null,
             });
-            logDebug('Token refresh successful');
+            logger.debug('Auth token renewal succeeded; frontend clients updated');
+            refreshWebSocketAuth(result.accessToken);
             return result.accessToken;
         };
-        // Store the promise so concurrent callers share it
+        // RC1 — CROSS-TAB SERIALIZATION via the Web Locks API.
+        //
+        // `refreshInFlightRef` only dedupes refreshes WITHIN a tab. Across tabs,
+        // a mass-expiry event (e.g. a dev backend recompile expiring every tab's
+        // access token at the same instant) makes every tab fire `/auth/token/
+        // refresh` with the SAME current cookie. One wins and rotates the token;
+        // the others present the now-rotated token a beat later, the backend's
+        // reuse-detection treats that as theft and `invalidateAllTokensForUser`
+        // NUKES every session. The `wildo-auth-refresh` lock ensures only ONE tab
+        // performs the network rotation; the rest wait, then adopt the winner's
+        // already-rotated token with no second network call. Falls back to a plain
+        // refresh where Web Locks is unavailable (non-secure context / old browser;
+        // localhost dev IS a secure context, so the lock is active there).
+        const doRefresh = async () => {
+            const locks = typeof navigator !== 'undefined' ? navigator.locks : undefined;
+            if (!locks?.request) {
+                return performNetworkRefresh();
+            }
+            return locks.request('wildo-auth-refresh', async () => {
+                const adopted = adoptCrossTabRefreshedToken();
+                if (adopted)
+                    return adopted;
+                return performNetworkRefresh();
+            });
+        };
+        // Store the promise so concurrent callers in this tab share it.
         refreshInFlightRef.current = doRefresh().finally(() => {
             refreshInFlightRef.current = null;
         });
@@ -840,14 +951,41 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             return await refreshInFlightRef.current;
         }
         catch (error) {
-            // Refresh failed — trigger logout
-            logger.warn('Token refresh failed, logging out', { error });
-            logout();
+            // RC2/RC3 — classify the failure. `logout()` clears the SHARED
+            // `__wildo_refresh` cookie, so destroying the session on a transient
+            // failure (backend restarting / 5xx / timeout) permanently logs out
+            // every tab and breaks recovery. Only an AUTHORITATIVE rejection (the
+            // backend explicitly refused this refresh token) warrants logout — and
+            // in DEVELOPMENT not even that, because dev recompiles routinely produce
+            // authoritative-looking 400/401s while the session is in fact fine once
+            // the backend settles. See `auth-refresh-resilience.frontend.ts`.
+            const authoritative = isAuthoritativeRefreshRejection(error);
+            const devLenient = isRefreshDevLenient();
+            if (authoritative && !devLenient) {
+                logger.warn('Auth token renewal failed; refresh token was rejected and logout will follow', {
+                    error: isWildoBackendError(error)
+                        ? error.customMessageReference
+                        : (error instanceof Error ? error.message : 'Unknown error'),
+                });
+                logout();
+            }
+            else {
+                logger.warn('Auth token renewal failed but session is preserved (will retry on the next request)', {
+                    authoritative,
+                    devLenient,
+                    reason: authoritative
+                        ? 'development leniency active — not logging out on an authoritative rejection'
+                        : 'transient failure (backend unreachable / 5xx / timeout) — not an authoritative rejection',
+                });
+            }
             throw error;
         }
-    }, [setResourcesAuthToken, logout, tokenStorage]);
-    // Register the token renewal handler on both HTTP clients
+    }, [setResourcesAuthToken, logout, refreshWebSocketAuth, tokenStorage]);
+    // Register the token renewal handler on both HTTP clients + expose it via ref
+    // so the WebSocket `onAuthenticationError` callback (wired in `connectWebSocket`
+    // above) always invokes the current handler.
     useEffect(() => {
+        tokenRenewalHandlerRef.current = tokenRenewalHandler;
         getManualCallsHttpClient().setTokenRenewalHandler(tokenRenewalHandler);
         setResourcesTokenRenewalHandler(tokenRenewalHandler);
     }, [tokenRenewalHandler, setResourcesTokenRenewalHandler]);
@@ -860,13 +998,22 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         const channel = new BroadcastChannel('wildo-auth-tokens');
         broadcastChannelRef.current = channel;
         channel.onmessage = (event) => {
-            const { type, accessToken, refreshToken } = event.data ?? {};
+            const { type, accessToken } = event.data ?? {};
             if (type === 'TOKEN_REFRESHED' && accessToken) {
-                logDebug('Received refreshed tokens from another tab');
-                storeAuthTokens(accessToken, refreshToken);
+                // Auth-hardening Slice A Step 6 (2026-04-13) — payload only
+                // carries the rotated access token. The rotated refresh token
+                // landed in the shared `__wildo_refresh` cookie via the issuing
+                // tab's `Set-Cookie` response, and same-origin tabs see the
+                // new cookie automatically; nothing for this receiver to do.
+                // Pre-Slice-A tabs that broadcast a `refreshToken` field have
+                // long since aged out (A-Step 6 ships well after the dual-read
+                // window closed); the destructuring above doesn't pick it up.
+                logger.debug('Auth token renewal received from another tab; frontend clients updated');
+                storeAuthTokens(accessToken);
                 getManualCallsHttpClient().setAuthToken(accessToken);
                 setResourcesAuthToken(accessToken);
-                setAuth(a => ({ ...a, accessToken, refreshToken: refreshToken ?? a.refreshToken }));
+                setAuth(a => ({ ...a, accessToken }));
+                refreshWebSocketAuth(accessToken);
             }
             if (type === 'LOGOUT') {
                 logDebug('Received logout signal from another tab');
@@ -874,7 +1021,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 tokenStorage.clear();
                 getManualCallsHttpClient().setConsumableToken(null);
                 setResourcesConsumableToken(null);
-                storeAuthTokens(null, null);
+                storeAuthTokens(null);
                 getManualCallsHttpClient().setAuthToken(null);
                 setResourcesAuthToken(null);
                 setAuth(EMPTY_AUTH_STATE);
@@ -884,35 +1031,34 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             channel.close();
             broadcastChannelRef.current = null;
         };
-    }, [setResourcesAuthToken, setResourcesConsumableToken, disconnect, tokenStorage]);
+    }, [setResourcesAuthToken, setResourcesConsumableToken, disconnect, refreshWebSocketAuth, tokenStorage]);
     // Initialize auth tokens on mount (from storage)
     useEffect(() => {
         // Prevent multiple initializations
         if (hasInitializedRef.current) {
             return;
         }
+        // Auth-hardening Slice A Step 3 (2026-04-13) — only the access token
+        // is stored client-side. The refresh token lives in the
+        // `__wildo_refresh` `HttpOnly` cookie which JS can't read; it's
+        // implicitly available as soon as the browser includes it on the
+        // first `/auth/token/refresh` round-trip. No "do we have a refresh
+        // token?" check needed at mount.
         const storedAccessToken = tokenStorage.getAccessToken();
-        const storedRefreshToken = tokenStorage.getRefreshToken();
-        // If no tokens in storage, nothing to do
-        if (!storedAccessToken && !storedRefreshToken) {
-            logDebug('No stored tokens found');
+        if (!storedAccessToken) {
+            logDebug('No stored access token found');
             hasInitializedRef.current = true;
             return;
         }
-        logDebug('Found stored tokens, initializing auth state');
+        logDebug('Found stored access token, initializing auth state');
         hasInitializedRef.current = true;
-        // Set tokens in state and HTTP clients
         setAuth(a => ({
             ...a,
             accessToken: storedAccessToken,
-            refreshToken: storedRefreshToken,
             isRestoringSession: true,
         }));
-        // Set token in HTTP clients
-        if (storedAccessToken) {
-            getManualCallsHttpClient().setAuthToken(storedAccessToken);
-            setResourcesAuthToken(storedAccessToken);
-        }
+        getManualCallsHttpClient().setAuthToken(storedAccessToken);
+        setResourcesAuthToken(storedAccessToken);
         // UserOrgsContext will handle fetching user data and marking session as restored
     }, [setResourcesAuthToken, tokenStorage]);
     const value = useMemo(() => ({
@@ -925,12 +1071,9 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         getSessionState,
         isAuthenticated,
         logout,
-        // OAuth2 methods
+        // OAuth2 + cross-frontend-handoff (shared AUTH_CODE_EXCHANGE primitive)
         initiateOAuth2Login,
-        handleOAuth2Callback,
-        // Native SDK token exchange (Capacitor mobile)
-        handleNativeTokenExchange,
-        initiateNativeSignIn,
+        handleAuthCodeExchange,
         // Email verification
         handleEmailVerification,
         acceptInvitation,
@@ -941,6 +1084,8 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         handlePasskeyAuth,
         // One-off session exchange (W7.3b)
         handleOneOffTokenExchange,
+        // Cross-frontend handoff context (cross-app-jwt-propagation Step 5)
+        clearCrossFrontendHandoffContext,
         // Session management
         markSessionRestored,
         setSessionRestoring,
@@ -952,15 +1097,14 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         tokenStorage,
         logout,
         initiateOAuth2Login,
-        handleOAuth2Callback,
-        handleNativeTokenExchange,
-        initiateNativeSignIn,
+        handleAuthCodeExchange,
         handleEmailVerification,
         acceptInvitation,
         handleMagicLinkVerify,
         handleMfaVerify,
         handlePasskeyAuth,
         handleOneOffTokenExchange,
+        clearCrossFrontendHandoffContext,
         markSessionRestored,
         setSessionRestoring,
         connectWebSocket,
@@ -968,4 +1112,4 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
     ]);
     return _jsx(AuthSessionContext.Provider, { value: value, children: children });
 };
-//# sourceMappingURL=AuthSessionContext.js.map
+//# sourceMappingURL=AuthSessionContext.js.map