@vertesia/ui 1.5.0-dev.20260910.052912Z → 1.6.0-dev.20260912.110338Z

package/src/session/auth/composable.ts

@@ -10,11 +10,86 @@ import {
 import { Env } from '@vertesia/ui/env';
 import { jwtDecode } from 'jwt-decode';
 import { LastSelectedAccountId_KEY, LastSelectedProjectId_KEY } from '../constants';
+import { generateAuthState } from './authState';
+import {
+    authReturnUrl,
+    buildCentralAuthRedirectUrl,
+    centralAuthUrl,
+    shouldRedirectToCentralAuth,
+} from './domainRouting';
 import { getFirebaseAuth, getFirebaseAuthToken } from './firebase';
 
 let AUTH_TOKEN_RAW: string | undefined;
 let AUTH_TOKEN: AuthTokenPayload | undefined;
 
+/**
+ * Whether this tab ever held a token.
+ *
+ * Separates "the session expired" from "there is no session yet". Only the first is renewed from
+ * here; the first load is UserSessionProvider's, and it has the account/project selection that
+ * this layer does not.
+ */
+let HAD_SESSION = false;
+
+/** Session-storage stamp of the last renewal redirect, so the cooldown survives the navigation. */
+const RENEWAL_ATTEMPT_KEY = 'vt.centralAuthRenewalAt';
+const RENEWAL_COOLDOWN_MS = 60_000;
+
+/**
+ * Renew an expired Central Auth session by bouncing through the broker.
+ *
+ * A Central Auth session holds exactly one credential -- the STS JWT, in memory -- and STS refuses
+ * it once it has expired. There is no Firebase user in this browser to mint a replacement from and
+ * no refresh token, so the only way back is the broker, which still has the user's own session and
+ * returns a fresh identity token without prompting. That is precisely what a manual reload does
+ * today; doing it here turns a page that dead-ends on "Cannot acquire a composable token" into a
+ * redirect the user usually does not notice.
+ *
+ * The cooldown is the important part. If the broker returns a credential STS also rejects, an
+ * unguarded redirect bounces the browser between the two forever -- and a redirect loop is a worse
+ * failure than the error page it replaced, because it never comes to rest anywhere the user can
+ * read. One attempt per minute, recorded in sessionStorage because the module state does not
+ * survive the navigation this function starts.
+ *
+ * Returns whether a redirect was started.
+ */
+function renewExpiredCentralAuthSession(): boolean {
+    if (!HAD_SESSION || !shouldRedirectToCentralAuth()) {
+        return false;
+    }
+
+    let lastAttempt = 0;
+    try {
+        lastAttempt = Number(sessionStorage.getItem(RENEWAL_ATTEMPT_KEY) ?? '0');
+    } catch {
+        // sessionStorage unavailable -- treated as "no previous attempt", so the redirect is
+        // allowed once and the failure surfaces normally if it does not stick.
+    }
+    if (Number.isFinite(lastAttempt) && lastAttempt > 0 && Date.now() - lastAttempt < RENEWAL_COOLDOWN_MS) {
+        Env.logger.warn('Central Auth session renewal already attempted; surfacing the failure instead', {
+            vertesia: { last_attempt_ms_ago: Date.now() - lastAttempt },
+        });
+        return false;
+    }
+
+    try {
+        sessionStorage.setItem(RENEWAL_ATTEMPT_KEY, String(Date.now()));
+    } catch {
+        // Without the stamp the cooldown cannot be enforced across the navigation. Still worth
+        // redirecting once: the alternative is a page the user can only fix by reloading manually.
+    }
+
+    Env.logger.info('Renewing an expired Central Auth session through the broker');
+    const url = buildCentralAuthRedirectUrl(
+        centralAuthUrl(),
+        Env.endpoints.sts ?? 'https://sts.vertesia.io',
+        authReturnUrl(),
+        generateAuthState(),
+    );
+    location.replace(url.toString());
+    return true;
+}
+
 function clearRejectedPersistedScope(accountId?: string, projectId?: string) {
     if (!accountId) return;
 
@@ -62,8 +137,11 @@ function identityFromAcceptedToken(token: string): AuthenticatedIdentity | undef
 }
 
 export function resolveAuthSelection(currentUrl: URL): { accountId?: string; projectId?: string } {
-    const urlAccount = currentUrl.searchParams.get('a') ?? undefined;
-    const urlProject = currentUrl.searchParams.get('p') ?? undefined;
+    // A URL selection owns the whole pair: never attach an unrelated configured account/project.
+    const hasUrlScope = currentUrl.searchParams.has('a') || currentUrl.searchParams.has('p');
+    const defaults = hasUrlScope ? undefined : Env.defaultAuthSelection;
+    const urlAccount = currentUrl.searchParams.get('a') ?? defaults?.accountId;
+    const urlProject = currentUrl.searchParams.get('p') ?? defaults?.projectId;
     const accountId =
         urlAccount ??
         (urlProject === undefined ? (localStorage.getItem(LastSelectedAccountId_KEY) ?? undefined) : undefined);
@@ -434,6 +512,7 @@ export async function getComposableToken(
         cachedTokenMatchesScope &&
         AUTH_TOKEN.exp > Date.now() / 1000 + 300
     ) {
+        HAD_SESSION = true;
         return { rawToken: AUTH_TOKEN_RAW, token: AUTH_TOKEN, error: false };
     }
 
@@ -447,6 +526,7 @@ export async function getComposableToken(
         if (!AUTH_TOKEN.exp) {
             throw new Error('Invalid composable token');
         }
+        HAD_SESSION = true;
         return { rawToken: AUTH_TOKEN_RAW, token: AUTH_TOKEN, error: false };
     }
 
@@ -458,7 +538,14 @@ export async function getComposableToken(
         } else if (!devAuthToken) {
             // Embedded apps can reacquire a fresh credential from their host after their cached token expires.
             const refreshCredential = (await Env.authTokenProvider?.()) ?? initToken ?? AUTH_TOKEN_RAW;
+            // `forceRefresh` has to defeat this shortcut, not just the cache above it. A caller
+            // asking for a forced refresh wants claims recomputed -- `refreshAuthToken()` exists so
+            // a stale `apps` claim can be re-read after an ACE change, and STS recomputes it on
+            // every issuance. Adopting the credential we already hold satisfies the check and
+            // returns the very token whose claims were suspect, silently making the call a no-op
+            // for exactly the sessions that have no other credential to fall back on.
             if (
+                !forceRefresh &&
                 refreshCredential &&
                 isVertesiaIssuedToken(refreshCredential) &&
                 canUseVertesiaTokenDirectly(refreshCredential, selectedAccount, selectedProject)
@@ -488,6 +575,13 @@ export async function getComposableToken(
                 clearRejectedPersistedScope(selectedAccount, selectedProject);
             }
         }
+        // An expired Central Auth session presents as a rejected credential: the JWT we sent STS to
+        // renew from is the one that timed out. The broker can still vouch for the user. Only this
+        // error -- a scope or account failure is about who the user is, and the broker would hand
+        // back the same identity and the same refusal.
+        if (error instanceof CredentialError) {
+            renewExpiredCentralAuthSession();
+        }
         throw error;
     }
 
@@ -498,6 +592,10 @@ export async function getComposableToken(
                 project_id: selectedProject,
             },
         });
+        // Reached once the credential has already been discarded -- typically the call after the
+        // one that saw STS reject it. Same remedy, and the cooldown keeps this from redirecting a
+        // second time for the same expiry.
+        renewExpiredCentralAuthSession();
         throw new Error('Cannot acquire a composable token');
     }
 
@@ -514,6 +612,7 @@ export async function getComposableToken(
         throw new Error('Invalid composable token');
     }
 
+    HAD_SESSION = true;
     return { rawToken: AUTH_TOKEN_RAW, token: AUTH_TOKEN, error: false };
 }
 

package/src/session/auth/domainRouting.test.ts

@@ -1,12 +1,12 @@
 import { Env } from '@vertesia/ui/env';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 import {
-    centralAuthRedirectUrl,
+    centralAuthUrl,
     clearCentralAuthRoundTripMarker,
+    DEFAULT_CENTRAL_AUTH_URL,
     isCentralAuthRedirectPending,
     markCentralAuthRoundTripStarted,
     mountRootUrl,
-    redirectToCentralAuth,
     shouldRedirectToCentralAuth,
     shouldUseFirebaseAuth,
 } from './domainRouting';
@@ -40,24 +40,6 @@ describe('domainRouting', () => {
         expect(shouldRedirectToCentralAuth()).toBe(true);
     });
 
-    it('carries the selected account and project through central auth for a gateway-mounted app', () => {
-        const redirect = centralAuthRedirectUrl({
-            centralAuthUrl: 'https://internal-auth.vertesia.app/',
-            stsEndpoint: 'https://sts.example.test',
-            returnUrl: new URL('https://apps.example.test/tenants/t/apps/a/versions/v/app/?view=grid'),
-            state: 'state-1',
-            accountId: 'account-1',
-            projectId: 'project-1',
-        });
-        const returnUrl = new URL(redirect.searchParams.get('redirect_uri') || '');
-
-        expect(redirect.searchParams.get('sts')).toBe('https://sts.example.test');
-        expect(redirect.searchParams.get('state')).toBe('state-1');
-        expect(returnUrl.toString()).toBe(
-            'https://apps.example.test/tenants/t/apps/a/versions/v/app/?view=grid&p=project-1&a=account-1',
-        );
-    });
-
     describe('mountRootUrl', () => {
         it('returns the deep gateway mount root (dropping any deep route / query / hash)', () => {
             const mount = 'https://gw.example.com/tenants/05948c_5ed5f4/apps/furniture-catalog/versions/v1/app/';
@@ -80,6 +62,37 @@ describe('domainRouting', () => {
     });
 });
 
+describe('centralAuthUrl', () => {
+    function initEnv(auth?: string) {
+        Env.init({
+            name: 'test',
+            version: '0',
+            isLocalDev: true,
+            isDocker: false,
+            type: 'development',
+            endpoints: { studio: 'https://studio.test', zeno: 'https://zeno.test', sts: 'https://sts.test', auth },
+        });
+    }
+
+    it('falls back to the default broker when no auth endpoint is configured', () => {
+        initEnv(undefined);
+        expect(centralAuthUrl()).toBe(DEFAULT_CENTRAL_AUTH_URL);
+        expect(DEFAULT_CENTRAL_AUTH_URL).toBe('https://internal-auth.vertesia.app/');
+    });
+
+    it('uses the configured auth endpoint when one is set', () => {
+        initEnv('https://auth.vertesia.io/');
+        expect(centralAuthUrl()).toBe('https://auth.vertesia.io/');
+    });
+
+    // An empty string is what an unset VITE_* override collapses to; it must not become the broker
+    // URL, or the app would redirect to its own origin instead of a login page.
+    it('treats an empty auth endpoint as unconfigured', () => {
+        initEnv('');
+        expect(centralAuthUrl()).toBe(DEFAULT_CENTRAL_AUTH_URL);
+    });
+});
+
 // The boot-time counterpart of the redirect UserSessionProvider performs after mounting. It must
 // answer true only when that provider is certain to redirect, because an app's entry module skips
 // the whole React tree on the strength of it -- and false whenever the answer is not certain, which
@@ -116,7 +129,7 @@ describe('isCentralAuthRedirectPending', () => {
         expect(isCentralAuthRedirectPending()).toBe(true);
     });
 
-    it('is false when AUTH_MODE is firebase, which signs in without the broker', () => {
+    it('is false on a Firebase-allowlisted host, which signs in without the broker', () => {
         initEnv({});
         (globalThis as { window?: unknown }).window = { AUTH_MODE: 'firebase', location: { hash: '' } };
         expect(isCentralAuthRedirectPending()).toBe(false);
@@ -199,46 +212,3 @@ describe('central auth round-trip marker', () => {
         expect(document.cookie).toBe('vtsauth=; Path=/; Max-Age=0; SameSite=Lax; Secure');
     });
 });
-
-// The shared redirect must preserve release/1.5's gateway selection and write state that
-// the provider's hook accepts when the broker returns.
-describe('redirectToCentralAuth', () => {
-    afterEach(() => {
-        vi.unstubAllGlobals();
-        sessionStorage.clear();
-        Env.init();
-    });
-
-    it('keeps the gateway mount and selection, records state, and marks the round trip before navigating', async () => {
-        const { verifyAuthState, clearAuthState } = await import('./authState');
-        const mount = 'https://apps.test/tenants/t/apps/a/versions/v/app/';
-        const document = { baseURI: mount, cookie: '' };
-        const replace = vi.fn((target: string) => {
-            const url = new URL(target);
-            expect(document.cookie).toBe('vtsauth=1; Path=/; Max-Age=300; SameSite=Lax; Secure');
-            expect(verifyAuthState(url.searchParams.get('state'))).toBeUndefined();
-        });
-        vi.stubGlobal('window', { location: { href: 'https://apps.test/?view=grid#old', protocol: 'https:' } });
-        vi.stubGlobal('document', document);
-        vi.stubGlobal('location', { replace });
-        Env.init({
-            name: 'test',
-            version: '0',
-            isLocalDev: false,
-            isDocker: false,
-            type: 'production',
-            endpoints: { studio: 'https://studio.test', zeno: 'https://zeno.test', sts: 'https://sts.test/?x=1&y=2' },
-        });
-
-        redirectToCentralAuth({ accountId: 'account-1', projectId: 'project-1' });
-
-        expect(replace).toHaveBeenCalledOnce();
-        const url = new URL(replace.mock.calls[0][0]);
-        expect(url.origin).toBe('https://internal-auth.vertesia.app');
-        expect(url.searchParams.get('sts')).toBe('https://sts.test/?x=1&y=2');
-        expect(url.searchParams.get('redirect_uri')).toBe(`${mount}?p=project-1&a=account-1`);
-        expect(verifyAuthState('wrong')).toContain('State mismatched');
-        clearAuthState();
-        expect(verifyAuthState(url.searchParams.get('state'))).toContain('State mismatched');
-    });
-});

package/src/session/auth/domainRouting.ts

@@ -7,6 +7,20 @@ declare global {
     }
 }
 
+/**
+ * The broker this app sends users to for sign-in and logout.
+ *
+ * Hard-coded until now, which meant every consumer of this package reached the same deployment no
+ * matter what was running. It is read from the environment so a single app can be pointed at a
+ * different broker, and it keeps this default so an app that configures nothing is unaffected.
+ */
+export const DEFAULT_CENTRAL_AUTH_URL = 'https://internal-auth.vertesia.app/';
+
+export function centralAuthUrl(): string {
+    const configured = Env.endpoints.auth;
+    return configured ? configured : DEFAULT_CENTRAL_AUTH_URL;
+}
+
 export function shouldUseFirebaseAuth(_hostname?: string) {
     return window.AUTH_MODE === 'firebase';
 }
@@ -15,35 +29,11 @@ export function shouldRedirectToCentralAuth(_hostname?: string) {
     return !shouldUseFirebaseAuth();
 }
 
-interface CentralAuthRedirectOptions {
-    centralAuthUrl: string;
-    stsEndpoint: string;
-    returnUrl: URL;
-    state: string;
+interface AuthSelection {
     accountId?: string;
     projectId?: string;
 }
 
-/** Build a central-auth round trip without losing the app's requested account/project selection. */
-export function centralAuthRedirectUrl({
-    centralAuthUrl,
-    stsEndpoint,
-    returnUrl,
-    state,
-    accountId,
-    projectId,
-}: CentralAuthRedirectOptions): URL {
-    const selectedReturnUrl = new URL(returnUrl);
-    if (projectId) selectedReturnUrl.searchParams.set('p', projectId);
-    if (accountId) selectedReturnUrl.searchParams.set('a', accountId);
-
-    const url = new URL(centralAuthUrl);
-    url.searchParams.set('sts', stsEndpoint);
-    url.searchParams.set('redirect_uri', selectedReturnUrl.toString());
-    url.searchParams.set('state', state);
-    return url;
-}
-
 /**
  * The page URL to return to after a central-auth round-trip (`redirect_uri`).
  *
@@ -82,6 +72,33 @@ export function mountRootUrl(): URL {
     return url;
 }
 
+/**
+ * The broker URL a sign-in or renewal round-trip navigates to.
+ *
+ * Every parameter goes on through `searchParams`, never by concatenating a query string onto
+ * `centralAuth`. The endpoint is configurable, so it may already carry its own query or a
+ * fragment -- and appending `?sts=...` to one of those folds the parameter into the existing value
+ * or hides it in the fragment, leaving Central Auth with no `sts` at all. `searchParams` also
+ * percent-encodes the values, which the interpolated URLs did not.
+ */
+export function buildCentralAuthRedirectUrl(
+    centralAuth: string,
+    stsUrl: string,
+    returnUrl: URL,
+    state: string,
+    selection: AuthSelection = {},
+): URL {
+    const selectedReturnUrl = new URL(returnUrl);
+    if (selection.projectId) selectedReturnUrl.searchParams.set('p', selection.projectId);
+    if (selection.accountId) selectedReturnUrl.searchParams.set('a', selection.accountId);
+
+    const url = new URL(centralAuth);
+    url.searchParams.set('sts', stsUrl);
+    url.searchParams.set('redirect_uri', selectedReturnUrl.toString());
+    url.searchParams.set('state', state);
+    return url;
+}
+
 /**
  * A short-lived marker saying "a Central Auth round-trip is in flight for this browser".
  *
@@ -128,14 +145,14 @@ export function clearCentralAuthRoundTripMarker(): void {
  * and {@link isCentralAuthRedirectPending}'s counterpart inside `UserSessionProvider` cannot drift
  * into producing different `redirect_uri` / `state` / `sts` values for the same page load.
  */
-export function redirectToCentralAuth(selection: { accountId?: string; projectId?: string } = {}): void {
-    const url = centralAuthRedirectUrl({
-        centralAuthUrl: 'https://internal-auth.vertesia.app/',
-        stsEndpoint: Env.endpoints.sts ?? 'https://sts.vertesia.io',
-        returnUrl: authReturnUrl(),
-        state: generateAuthState(),
-        ...selection,
-    });
+export function redirectToCentralAuth(selection: AuthSelection = {}): void {
+    const url = buildCentralAuthRedirectUrl(
+        centralAuthUrl(),
+        Env.endpoints.sts ?? 'https://sts.vertesia.io',
+        authReturnUrl(),
+        generateAuthState(),
+        selection,
+    );
     markCentralAuthRoundTripStarted();
     location.replace(url.toString());
 }
@@ -149,7 +166,7 @@ export function redirectToCentralAuth(selection: { accountId?: string; projectId
  * that provider from redirecting is therefore knowable up front, and this predicate enumerates
  * them in the same order:
  *
- *   - Apps configured with Firebase auth sign in in place rather than at the broker;
+ *   - Firebase-allowlisted hosts sign in in place rather than at the broker;
  *   - a host app that injects a token through `Env.authTokenProvider` may not need the broker
  *     (and when its token turns out to be empty the provider still redirects — answering `false`
  *     here just lets the normal flow decide, which is the safe direction);

package/src/session/auth/useAuthState.ts

@@ -1,10 +1,17 @@
-/** React wrappers for the state record shared with boot-time Central Auth redirects. */
+/**
+ * This hook is used to generate and verify state for OAuth2 authorization requests.
+ *
+ * The implementation lives in ./authState so the token layer can start the same round-trip when it
+ * renews an expired Central Auth session, where no component is available to call a hook.
+ */
+
 import { useCallback } from 'react';
 import { clearAuthState, generateAuthState, verifyAuthState } from './authState';
 
 export function useAuthState() {
-    const generateState = useCallback(generateAuthState, []);
-    const verifyState = useCallback(verifyAuthState, []);
-    const clearState = useCallback(clearAuthState, []);
+    const generateState = useCallback(() => generateAuthState(), []);
+    const verifyState = useCallback((returnedState: string | null) => verifyAuthState(returnedState), []);
+    const clearState = useCallback(() => clearAuthState(), []);
+
     return { generateState, verifyState, clearState };
 }

package/src/session/index.ts

@@ -1,5 +1,7 @@
 export * from './auth/composable';
-// Publish the boot-time auth entry points.
+// Explicit, not `export *`: domainRouting also holds buildCentralAuthRedirectUrl, which
+// UserSessionProvider already re-exports below, and two star exports of one name resolve to
+// nothing. Only the boot-time entry points an app needs are published here.
 export {
     clearCentralAuthRoundTripMarker,
     isCentralAuthRedirectPending,

package/src/shell/AuthScreenPreview.test.tsx

@@ -0,0 +1,44 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import * as session from '@vertesia/ui/session';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AUTH_PREVIEW_SCREENS, AuthScreenPreview, mountAuthScreenPreview } from './AuthScreenPreview';
+import * as signin from './login/signInUtils';
+
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+
+describe('shared auth visual previews', () => {
+    it.each(AUTH_PREVIEW_SCREENS.filter((name) => name !== 'boot'))(
+        'renders %s without initializing or changing authentication',
+        (name) => {
+            const firebase = vi.spyOn(session, 'getFirebaseAuth');
+            const reset = vi.spyOn(signin, 'resetSignInState');
+            const { container } = render(<AuthScreenPreview screen={name} branding={{ name: 'Example' }} />);
+            expect(container.querySelector('[inert]')?.textContent?.trim()).not.toBe('');
+            expect(screen.getByText(`Auth preview: ${name}`)).toBeTruthy();
+            expect(firebase).not.toHaveBeenCalled();
+            expect(reset).not.toHaveBeenCalled();
+        },
+    );
+
+    it('retains branding and full screen overrides, with links to the shared boot URL', () => {
+        render(
+            <AuthScreenPreview
+                screen="loading"
+                branding={{ name: 'Example' }}
+                screens={{ Loading: () => <p>Custom loader fixture</p> }}
+            />,
+        );
+        expect(screen.getByText('Custom loader fixture')).toBeTruthy();
+        expect(screen.getByText('boot').getAttribute('href')).toContain('__vertesia_boot=slow');
+        expect(screen.getByText('pending').getAttribute('href')).toContain('__vertesia_auth=pending');
+    });
+
+    it('keeps the React root empty for boot previews', async () => {
+        const container = document.createElement('div');
+        await mountAuthScreenPreview(container, 'boot');
+        expect(container.childNodes).toHaveLength(0);
+    });
+});