@robosystems/core 0.11.1 → 0.11.3

package/auth-core/client.js

@@ -1,7 +1,8 @@
 var _a;
 import { checkPasswordStrength, client, completeSsoAuth, createUserApiKey, deleteUserPasskey, forgotPassword, generateSsoToken, getAuthProviders, getCurrentAuthUser, getInvitationPreview, getMfaOptions, getMfaStatus, getPasskeyLoginOptions, getPasskeyReauthOptions, getPasskeyRegistrationOptions, getPasswordPolicy, listUserApiKeys, listUserPasskeys, loginUser, logoutUser, refreshAuthSession, regenerateMfaRecoveryCodes, registerUser, resendVerificationEmail, resetPassword, revokeUserApiKey, ssoTokenExchange, validateResetToken, verifyEmail, verifyMfa, verifyPasskeyLogin, verifyPasskeyRegistration, } from '@robosystems/client';
 import * as sdkClientsModule from '@robosystems/client/clients';
-import { getToken, getValidToken } from './token-storage';
+import { ApiError, isSessionRejection, isTransientError, unwrapSdk, } from '../lib/sdk-errors';
+import { getRefreshToken, getToken, getValidToken } from './token-storage';
 // Global config hook for the clients package's lazy default singleton
 // (`import { clients } from '@robosystems/client/clients'`). We must
 // set this BEFORE the singleton is first accessed — the singleton reads the
@@ -26,7 +27,45 @@ const ERROR_CACHE_TTL_MS = 5 * 1000; // 5 seconds - allow reasonable retry delay
  * instead.
  */
 const APP_SOURCE_HEADER = 'X-App-Source';
+/**
+ * Marks the shared SDK client as already wrapped. Every auth client instance
+ * configures the *global* SDK client; wrapping its methods once per instance
+ * would stack a layer per construction (per render in a careless caller).
+ */
+const AUTH_WRAPPED = Symbol.for('@robosystems/core:auth-wrapped');
+export { isSessionRejection, isTransientError };
 const appSourceHeaders = (appSource) => appSource ? { [APP_SOURCE_HEADER]: appSource } : undefined;
+/**
+ * For the email endpoints (forgot password, resend verification): the
+ * failures worth telling the user about. Null for a refusal the caller
+ * reports as "sent".
+ *
+ * Forgot password is unauthenticated and must not reveal whether the address
+ * has an account, so it surfaces only what says nothing about the account:
+ * rate limiting and a request that never arrived. A 5xx is not surfaced —
+ * only the existing-account path does work that can fail. Resend requires a
+ * session, so it can also report an outage and an expired session.
+ */
+const deliveryFailure = (error, { authenticated }) => {
+    if (!(error instanceof ApiError)) {
+        return authenticated ? 'Failed to send email. Please try again.' : null;
+    }
+    if (error.status === 429) {
+        return 'Too many requests. Please wait a few minutes and try again.';
+    }
+    if (error.isNetworkError) {
+        return 'Unable to reach the server. Check your connection and try again.';
+    }
+    if (!authenticated)
+        return null;
+    if (error.status === 401) {
+        return 'Your session has expired. Please sign in again.';
+    }
+    if (error.status >= 500) {
+        return 'The server ran into a problem. Please try again in a moment.';
+    }
+    return null;
+};
 // Custom error class for token expiry
 export class TokenExpiredError extends Error {
     constructor(message = 'Token expired') {
@@ -108,54 +147,32 @@ export class RoboSystemsAuthClient {
                 console.warn('[AuthClient] Failed to seed SDK extensions config:', err);
             }
         }
-        // Wrap the client methods to add JWT token to requests
-        const originalPost = (_b = this.client.post) === null || _b === void 0 ? void 0 : _b.bind(this.client);
-        const originalPut = (_c = this.client.put) === null || _c === void 0 ? void 0 : _c.bind(this.client);
-        const originalPatch = (_d = this.client.patch) === null || _d === void 0 ? void 0 : _d.bind(this.client);
-        const originalDelete = (_e = this.client.delete) === null || _e === void 0 ? void 0 : _e.bind(this.client);
-        // Helper to add JWT token to headers and handle 401 responses
-        const wrapWithAuthAndErrorHandling = (originalMethod, _methodName) => {
+        // Wrap the client methods to add the JWT to every request — once per
+        // SDK client, however many auth clients are constructed.
+        const sdkClient = this.client;
+        if (sdkClient[AUTH_WRAPPED])
+            return;
+        sdkClient[AUTH_WRAPPED] = true;
+        // Errors are not handled here: the SDK resolves `{ error }` on HTTP
+        // failures rather than throwing, so each caller unwraps its own result
+        // (`unwrapSdk`) and decides what a given status means.
+        const withAuthHeader = (originalMethod) => {
             if (!originalMethod)
                 return undefined;
             return async (options) => {
-                var _a, _b, _c;
-                try {
-                    const authToken = await getAuthToken();
-                    const headers = Object.assign({}, options.headers);
-                    if (authToken) {
-                        headers['Authorization'] = `Bearer ${authToken}`;
-                    }
-                    const enhancedOptions = Object.assign(Object.assign({}, options), { headers });
-                    const result = await originalMethod(enhancedOptions);
-                    return result;
-                }
-                catch (error) {
-                    // Check for 401 Unauthorized errors
-                    if ((error === null || error === void 0 ? void 0 : error.status) === 401 ||
-                        ((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.status) === 401 ||
-                        ((_b = error === null || error === void 0 ? void 0 : error.message) === null || _b === void 0 ? void 0 : _b.toLowerCase().includes('unauthorized')) ||
-                        ((_c = error === null || error === void 0 ? void 0 : error.message) === null || _c === void 0 ? void 0 : _c.toLowerCase().includes('401'))) {
-                        // Clear cached auth data
-                        this.clearAuthCache();
-                        // Clear token from storage
-                        const { clearToken } = await import('./token-storage');
-                        clearToken();
-                        // Throw custom error that can be caught by UI
-                        throw new TokenExpiredError('Your session has expired. Please log in again.');
-                    }
-                    // Re-throw other errors
-                    throw error;
+                const authToken = await getAuthToken();
+                const headers = Object.assign({}, options.headers);
+                if (authToken) {
+                    headers['Authorization'] = `Bearer ${authToken}`;
                 }
+                return originalMethod(Object.assign(Object.assign({}, options), { headers }));
             };
         };
-        // Also wrap GET requests to add JWT token
-        const originalGet = (_f = this.client.get) === null || _f === void 0 ? void 0 : _f.bind(this.client);
-        // Override all methods with auth headers and error handling
-        this.client.get = wrapWithAuthAndErrorHandling(originalGet, 'GET');
-        this.client.post = wrapWithAuthAndErrorHandling(originalPost, 'POST');
-        this.client.put = wrapWithAuthAndErrorHandling(originalPut, 'PUT');
-        this.client.patch = wrapWithAuthAndErrorHandling(originalPatch, 'PATCH');
-        this.client.delete = wrapWithAuthAndErrorHandling(originalDelete, 'DELETE');
+        this.client.get = withAuthHeader((_b = this.client.get) === null || _b === void 0 ? void 0 : _b.bind(this.client));
+        this.client.post = withAuthHeader((_c = this.client.post) === null || _c === void 0 ? void 0 : _c.bind(this.client));
+        this.client.put = withAuthHeader((_d = this.client.put) === null || _d === void 0 ? void 0 : _d.bind(this.client));
+        this.client.patch = withAuthHeader((_e = this.client.patch) === null || _e === void 0 ? void 0 : _e.bind(this.client));
+        this.client.delete = withAuthHeader((_f = this.client.delete) === null || _f === void 0 ? void 0 : _f.bind(this.client));
     }
     /**
      * Push the latest auth token into the SDK extensions global config.
@@ -188,7 +205,7 @@ export class RoboSystemsAuthClient {
             client: this.client,
             body: { email, password },
         });
-        return this.finalizeAuthResponse(response.data);
+        return this.finalizeAuthResponse(unwrapSdk(response));
     }
     /**
      * Validate an auth-shaped SDK response, store the session token when one
@@ -240,12 +257,7 @@ export class RoboSystemsAuthClient {
             },
             headers: appSourceHeaders(options === null || options === void 0 ? void 0 : options.appSource),
         });
-        // Check for error responses (4xx/5xx)
-        if (response.error) {
-            const errorData = response.error;
-            throw new Error((errorData === null || errorData === void 0 ? void 0 : errorData.detail) || 'Registration failed');
-        }
-        const sdkResponse = this.validateSDKAuthResponse(response.data);
+        const sdkResponse = this.validateSDKAuthResponse(unwrapSdk(response));
         // Store JWT token with expiry information if present in response
         if (sdkResponse.token) {
             const { storeToken } = await import('./token-storage');
@@ -346,7 +358,7 @@ export class RoboSystemsAuthClient {
             const response = await getCurrentAuthUser({
                 client: this.client,
             });
-            const data = this.validateSDKCurrentUserResponse(response.data);
+            const data = this.validateSDKCurrentUserResponse(unwrapSdk(response));
             const user = data.user;
             this.lastAuthCheck = { timestamp: Date.now(), result: user };
             return user;
@@ -358,9 +370,25 @@ export class RoboSystemsAuthClient {
         }
     }
     async refreshSession() {
-        const response = await this.refreshSessionWithRetry();
-        // Check if response has data property or if it IS the data
-        const responseData = (response === null || response === void 0 ? void 0 : response.data) !== undefined ? response.data : response;
+        const sentToken = getRefreshToken();
+        let responseData;
+        try {
+            responseData = await this.refreshSessionWithRetry();
+        }
+        catch (error) {
+            // Tabs of one app share the stored token. When another tab renewed it
+            // first, this refusal is for the token it replaced: adopt the renewed
+            // one instead of ending the session.
+            const currentToken = getRefreshToken();
+            if (!isTransientError(error) &&
+                currentToken !== null &&
+                currentToken !== sentToken) {
+                this.clearAuthCache();
+                const user = await this.getCurrentUser();
+                return { user, success: true, token: currentToken };
+            }
+            throw error;
+        }
         const sdkResponse = this.validateSDKAuthResponse(responseData);
         // Store new JWT token with expiry information if present in response
         if (sdkResponse.token) {
@@ -385,21 +413,31 @@ export class RoboSystemsAuthClient {
         };
     }
     /**
-     * Refresh session with exponential backoff retry logic
+     * Refresh session with exponential backoff retry logic.
+     *
+     * The request presents the stored token even when it has just expired:
+     * the API renews a recently-expired token within its grace window, and
+     * the data-call path deliberately stops sending it at expiry. A refusal
+     * (401/403) is final; only network errors, 429 and 5xx are retried.
      */
     async refreshSessionWithRetry() {
         let lastError = null;
         for (let attempt = 0; attempt <= this.MAX_REFRESH_RETRIES; attempt++) {
             try {
-                // Attempt to refresh the session
+                const refreshToken = getRefreshToken();
                 const response = await refreshAuthSession({
                     client: this.client,
+                    headers: refreshToken
+                        ? { Authorization: `Bearer ${refreshToken}` }
+                        : undefined,
                 });
-                // Success - return the response
-                return response;
+                return unwrapSdk(response);
             }
             catch (error) {
                 lastError = error;
+                if (!isTransientError(error)) {
+                    break;
+                }
                 // If this is the last attempt, throw the error
                 if (attempt === this.MAX_REFRESH_RETRIES) {
                     break;
@@ -425,7 +463,7 @@ export class RoboSystemsAuthClient {
                 description: request.permissions.join(', '), // Map permissions to description for now
             },
         });
-        const sdkResponse = response.data;
+        const sdkResponse = unwrapSdk(response);
         return {
             id: sdkResponse.api_key.id,
             name: sdkResponse.api_key.name,
@@ -442,7 +480,7 @@ export class RoboSystemsAuthClient {
         const response = await listUserApiKeys({
             client: this.client,
         });
-        const sdkResponse = response.data;
+        const sdkResponse = unwrapSdk(response);
         return sdkResponse.api_keys.map((apiKey) => ({
             id: apiKey.id,
             name: apiKey.name,
@@ -454,24 +492,23 @@ export class RoboSystemsAuthClient {
         }));
     }
     async revokeAPIKey(keyId) {
-        await revokeUserApiKey({
+        unwrapSdk(await revokeUserApiKey({
             client: this.client,
             path: { api_key_id: keyId },
-        });
+        }));
     }
     async generateSSOToken() {
         const response = await generateSsoToken({
             client: this.client,
         });
-        const data = response.data;
-        return data;
+        return unwrapSdk(response);
     }
     async ssoExchange(token, targetApp) {
         const response = await ssoTokenExchange({
             client: this.client,
             body: { token, target_app: targetApp },
         });
-        const data = response.data;
+        const data = unwrapSdk(response);
         return {
             session_id: data.session_id,
         };
@@ -481,7 +518,7 @@ export class RoboSystemsAuthClient {
             client: this.client,
             body: { session_id: sessionId },
         });
-        const sdkResponse = this.validateSDKAuthResponse(response.data);
+        const sdkResponse = this.validateSDKAuthResponse(unwrapSdk(response));
         // Store JWT token with expiry information if present in response
         if (sdkResponse.token) {
             const { storeToken } = await import('./token-storage');
@@ -542,7 +579,7 @@ export class RoboSystemsAuthClient {
             client: this.client,
             body: { mfa_token: mfaToken },
         });
-        return response.data.options;
+        return unwrapSdk(response).options;
     }
     /** Second-factor step: complete with an assertion or a recovery code. */
     async verifyMfa(mfaToken, input) {
@@ -554,12 +591,12 @@ export class RoboSystemsAuthClient {
                 recovery_code: input.recoveryCode,
             },
         });
-        return this.finalizeAuthResponse(response.data);
+        return this.finalizeAuthResponse(unwrapSdk(response));
     }
     /** Passwordless login: usernameless assertion options. */
     async getPasskeyLoginOptions() {
         const response = await getPasskeyLoginOptions({ client: this.client });
-        return response.data.options;
+        return unwrapSdk(response).options;
     }
     /** Passwordless login: assertion → session. */
     async completePasskeyLogin(assertion) {
@@ -567,7 +604,7 @@ export class RoboSystemsAuthClient {
             client: this.client,
             body: { assertion },
         });
-        return this.finalizeAuthResponse(response.data);
+        return this.finalizeAuthResponse(unwrapSdk(response));
     }
     /**
      * Begin enrollment. The settings lane must carry a fresh re-auth proof —
@@ -585,7 +622,7 @@ export class RoboSystemsAuthClient {
                 assertion: proof === null || proof === void 0 ? void 0 : proof.assertion,
             },
         });
-        return response.data.options;
+        return unwrapSdk(response).options;
     }
     /**
      * Finish enrollment. First passkey returns recovery codes (once); in the
@@ -602,7 +639,7 @@ export class RoboSystemsAuthClient {
                 mfa_token: options === null || options === void 0 ? void 0 : options.mfaToken,
             },
         });
-        const data = response.data;
+        const data = unwrapSdk(response);
         let auth;
         if (data.auth) {
             auth = await this.finalizeAuthResponse(data.auth);
@@ -617,20 +654,20 @@ export class RoboSystemsAuthClient {
     async listPasskeys() {
         var _a, _b;
         const response = await listUserPasskeys({ client: this.client });
-        return ((_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.passkeys) !== null && _b !== void 0 ? _b : []);
+        return ((_b = (_a = unwrapSdk(response)) === null || _a === void 0 ? void 0 : _a.passkeys) !== null && _b !== void 0 ? _b : []);
     }
     /** Fresh-assertion options for destructive lifecycle actions. */
     async getPasskeyReauthOptions() {
         const response = await getPasskeyReauthOptions({ client: this.client });
-        return response.data.options;
+        return unwrapSdk(response).options;
     }
     /** Remove a passkey; exactly one re-auth proof must be supplied. */
     async deletePasskey(passkeyId, proof) {
-        await deleteUserPasskey({
+        unwrapSdk(await deleteUserPasskey({
             client: this.client,
             path: { passkey_id: passkeyId },
             body: { password: proof.password, assertion: proof.assertion },
-        });
+        }));
     }
     /** MFA posture for the settings surface; null on any failure. */
     async getMfaStatus() {
@@ -656,7 +693,7 @@ export class RoboSystemsAuthClient {
             client: this.client,
             body: { password: proof.password, assertion: proof.assertion },
         });
-        return response.data.codes;
+        return unwrapSdk(response).codes;
     }
     // Clear request deduplication cache (useful after login/logout)
     clearAuthCache() {
@@ -669,23 +706,26 @@ export class RoboSystemsAuthClient {
      */
     async forgotPassword(email, options) {
         try {
-            await forgotPassword({
+            const response = await forgotPassword({
                 client: this.client,
                 body: { email },
                 headers: appSourceHeaders(options === null || options === void 0 ? void 0 : options.appSource),
             });
-            return {
-                success: true,
-                message: 'Password reset email sent if the account exists',
-            };
+            unwrapSdk(response);
         }
         catch (error) {
-            console.error('Forgot password error:', error);
-            return {
-                success: false,
-                message: 'Failed to send password reset email',
-            };
+            const failure = deliveryFailure(error, { authenticated: false });
+            if (failure) {
+                console.error('Forgot password error:', error);
+                return { success: false, message: failure };
+            }
         }
+        // Any other outcome reads as sent: whether the address has an account
+        // must not be observable from this form.
+        return {
+            success: true,
+            message: 'Password reset email sent if the account exists',
+        };
     }
     /**
      * Reset password using token
@@ -737,7 +777,7 @@ export class RoboSystemsAuthClient {
                 client: this.client,
                 query: { token },
             });
-            const data = response.data;
+            const data = unwrapSdk(response);
             return {
                 valid: (data === null || data === void 0 ? void 0 : data.valid) === true,
                 email: data === null || data === void 0 ? void 0 : data.email,
@@ -796,23 +836,25 @@ export class RoboSystemsAuthClient {
      */
     async resendVerificationEmail(email, options) {
         try {
-            await resendVerificationEmail({
+            const response = await resendVerificationEmail({
                 client: this.client,
                 body: { email },
                 headers: appSourceHeaders(options === null || options === void 0 ? void 0 : options.appSource),
             });
-            return {
-                success: true,
-                message: 'Verification email sent if the account exists',
-            };
+            unwrapSdk(response);
         }
         catch (error) {
-            console.error('Resend verification email error:', error);
-            return {
-                success: false,
-                message: 'Failed to send verification email',
-            };
+            const failure = deliveryFailure(error, { authenticated: true });
+            if (failure) {
+                console.error('Resend verification email error:', error);
+                return { success: false, message: failure };
+            }
         }
+        // Any other refusal (e.g. already verified) reads as sent.
+        return {
+            success: true,
+            message: 'Verification email sent if the account exists',
+        };
     }
     /**
      * Get password policy requirements
@@ -822,7 +864,7 @@ export class RoboSystemsAuthClient {
             const response = await getPasswordPolicy({
                 client: this.client,
             });
-            const data = response.data;
+            const data = unwrapSdk(response);
             return {
                 minLength: (data === null || data === void 0 ? void 0 : data.min_length) || 8,
                 requireUppercase: (data === null || data === void 0 ? void 0 : data.require_uppercase) || false,
@@ -878,7 +920,7 @@ export class RoboSystemsAuthClient {
                 client: this.client,
                 body: { password, email },
             });
-            const data = response.data;
+            const data = unwrapSdk(response);
             return {
                 score: (data === null || data === void 0 ? void 0 : data.score) || 0,
                 strength: (data === null || data === void 0 ? void 0 : data.strength) || 'very-weak',

package/auth-core/sso.d.ts

@@ -1,14 +1,9 @@
 import type { AppConfig, AuthUser } from './types';
 export interface SSORedirectUrlOptions {
     /**
-     * Mirror the target app / return URL into this tab's sessionStorage as a
-     * same-domain fallback for `handleSSOLogin`. Default true.
-     *
-     * Pass false when the URL is being handed to a *different* tab: the hints
-     * are unreadable there (separate tab, separate origin) and would linger in
-     * this tab, where a later same-tab SSO completion with no `returnUrl`
-     * param would pick up the stale path and redirect somewhere the user
-     * never asked to go.
+     * @deprecated No effect. The return path travels only in the handoff URL;
+     * a sessionStorage copy was never readable by the target app (every app is
+     * its own origin) and misrouted later handoffs into the *source* app.
      */
     persistSessionHints?: boolean;
 }
@@ -26,7 +21,7 @@ export declare class SSOManager {
     /**
      * Get SSO redirect URL using secure POST-based flow
      */
-    getSSORedirectUrl(targetApp: string, returnUrl?: string, options?: SSORedirectUrlOptions): Promise<string>;
+    getSSORedirectUrl(targetApp: string, returnUrl?: string, _options?: SSORedirectUrlOptions): Promise<string>;
     /**
      * Handle SSO login using secure POST-based flow
      */

package/auth-core/sso.js

@@ -31,6 +31,18 @@ const sanitizeReturnUrl = (returnUrl) => {
         return null;
     return returnUrl;
 };
+/** Keys an older version wrote; cleared on every handoff completion. */
+const LEGACY_SSO_HINT_KEYS = ['sso_target_app', 'sso_return_url'];
+const clearLegacySsoHints = () => {
+    try {
+        for (const key of LEGACY_SSO_HINT_KEYS)
+            sessionStorage.removeItem(key);
+    }
+    catch (error) {
+        // Storage access error - continue silently
+        debugLog('sessionStorage cleanup failed', error);
+    }
+};
 export class SSOManager {
     constructor(apiUrl) {
         this.authClient = new RoboSystemsAuthClient(apiUrl);
@@ -55,8 +67,7 @@ export class SSOManager {
     /**
      * Get SSO redirect URL using secure POST-based flow
      */
-    async getSSORedirectUrl(targetApp, returnUrl, options = {}) {
-        const { persistSessionHints = true } = options;
+    async getSSORedirectUrl(targetApp, returnUrl, _options = {}) {
         const ssoData = await this.generateSSOToken();
         const appConfig = APP_CONFIGS[targetApp];
         if (!appConfig) {
@@ -71,20 +82,6 @@ export class SSOManager {
         if (returnUrl) {
             url.searchParams.set('returnUrl', returnUrl);
         }
-        // Store only non-sensitive metadata in sessionStorage as backup for same-domain cases
-        // Note: We avoid storing the session_id in sessionStorage for security
-        if (persistSessionHints) {
-            try {
-                sessionStorage.setItem('sso_target_app', targetApp);
-                if (returnUrl) {
-                    sessionStorage.setItem('sso_return_url', returnUrl);
-                }
-            }
-            catch (error) {
-                // Storage error - continue without backup storage
-                debugLog('sessionStorage write failed during SSO URL generation', error);
-            }
-        }
         return url.toString();
     }
     /**
@@ -94,19 +91,11 @@ export class SSOManager {
         // Check for session ID from URL parameters (cross-domain compatible)
         const urlParams = new URLSearchParams(window.location.search);
         const sessionId = urlParams.get('session_id');
+        // The return path comes only from the handoff URL. With none, the
+        // caller's own default landing applies.
         const returnUrl = urlParams.get('returnUrl');
-        // Check sessionStorage for return URL fallback (same-domain case)
-        // Note: We don't store session_id in sessionStorage for security
-        let sessionStorageReturn = null;
-        try {
-            sessionStorageReturn = sessionStorage.getItem('sso_return_url');
-        }
-        catch (error) {
-            // Storage access error - continue without fallback
-            debugLog('sessionStorage read failed during SSO login', error);
-        }
         const finalSessionId = sessionId; // Only use URL parameter for session ID
-        const finalReturnUrl = sanitizeReturnUrl(returnUrl || sessionStorageReturn);
+        const finalReturnUrl = sanitizeReturnUrl(returnUrl);
         if (!finalSessionId) {
             return null;
         }
@@ -121,15 +110,7 @@ export class SSOManager {
                 newUrl.searchParams.delete('returnUrl');
                 window.history.replaceState({}, '', newUrl.toString());
             }
-            // Clean up session storage
-            try {
-                sessionStorage.removeItem('sso_target_app');
-                sessionStorage.removeItem('sso_return_url');
-            }
-            catch (error) {
-                // Storage access error - continue silently
-                debugLog('sessionStorage cleanup failed during SSO success', error);
-            }
+            clearLegacySsoHints();
             // Handle return URL if provided
             if (finalReturnUrl && finalReturnUrl !== window.location.pathname) {
                 // Delay navigation to allow authentication to complete
@@ -147,14 +128,7 @@ export class SSOManager {
                 newUrl.searchParams.delete('returnUrl');
                 window.history.replaceState({}, '', newUrl.toString());
             }
-            try {
-                sessionStorage.removeItem('sso_target_app');
-                sessionStorage.removeItem('sso_return_url');
-            }
-            catch (error) {
-                // Storage access error - continue silently
-                debugLog('sessionStorage cleanup failed during SSO error', error);
-            }
+            clearLegacySsoHints();
             // Log errors for monitoring in production (sanitized)
             if (process.env.NODE_ENV === 'development') {
                 console.error('SSO login failed:', this.sanitizeErrorForLogging(error));
@@ -249,20 +223,6 @@ export class SSOManager {
             if (returnUrl) {
                 targetUrl.searchParams.set('returnUrl', returnUrl);
             }
-            // Store only non-sensitive metadata in sessionStorage as backup for same-domain cases
-            // Note: We avoid storing the session_id in sessionStorage for security
-            if (typeof window !== 'undefined') {
-                try {
-                    sessionStorage.setItem('sso_target_app', targetApp);
-                    if (returnUrl) {
-                        sessionStorage.setItem('sso_return_url', returnUrl);
-                    }
-                }
-                catch (error) {
-                    // Storage error - continue without backup storage
-                    debugLog('sessionStorage write failed during SSO navigation', error);
-                }
-            }
             // Navigate to target app
             window.location.href = targetUrl.toString();
         }

package/auth-core/token-storage.d.ts

@@ -10,6 +10,13 @@ export interface TokenData {
     refreshThreshold?: number;
 }
 export type TokenStatus = 'valid' | 'warning' | 'expired';
+/**
+ * How long past its local expiry a token is kept. The API renews a
+ * recently-expired token at `/v1/auth/refresh` within this window, so the
+ * token must survive locally until then — for the refresh call only. Data
+ * calls stop sending it at expiry.
+ */
+export declare const TOKEN_REFRESH_GRACE_MS: number;
 /**
  * Store JWT token in localStorage
  * @param token - The JWT token from login response
@@ -56,3 +63,8 @@ export declare function handleAuthResponse(response: any): void;
  * @returns Valid token or null if expired
  */
 export declare function getValidToken(): Promise<string | null>;
+/**
+ * The token to present to `/v1/auth/refresh`: the stored token while it is
+ * unexpired or within the server's refresh grace after expiry, else null.
+ */
+export declare function getRefreshToken(): string | null;