@vertesia/ui 1.6.0-dev.20260918.061604Z → 1.6.0-dev.20260918.090710Z

package/src/env/index.ts

@@ -18,8 +18,8 @@ export interface EnvProps {
         /**
          * Central Auth broker that issues the sign-in redirect and hosts `/logout`.
          *
-         * Optional: when unset the session falls back to the long-standing broker, so an app that
-         * does not set it keeps its current behaviour exactly. Set it to move one environment at a
+         * Optional: when unset the session falls back to the first-party broker, so an app that
+         * does not set it uses auth.vertesia.io. Set it to move one environment at a
          * time onto a different broker.
          */
         auth?: string;
@@ -28,6 +28,8 @@ export interface EnvProps {
         /** Appgen app-gateway endpoint (serves live development previews and app bundles). */
         gateway?: string;
     };
+    /** Public OAuth client for independently hosted apps; ignored inside Studio or a gateway session. */
+    oauth?: { clientId: string; redirectUri: string; scopes?: string[] };
     firebase?: {
         apiKey: string;
         authDomain: string;
@@ -52,9 +54,8 @@ export interface EnvProps {
     /**
      * Optional host-provided Vertesia auth token bootstrap.
      *
-     * Published generated apps use this to ask their same-origin app gateway for
-     * the token backing the gateway session cookie, allowing UserSession to
-     * initialize without redirecting through Central Auth.
+     * Embedded apps use this to obtain a scoped token from their trusted host.
+     * Standalone generated apps use the gateway cookie session instead.
      */
     authTokenProvider?: () => Promise<string | undefined>;
     logger?: {
@@ -79,6 +80,10 @@ export type VertesiaRuntimeConfig =
       }
     | {
           authMode: 'central';
+          /** Broker selected by the serving gateway. Overrides build-time configuration. */
+          authUrl?: string;
+          /** The serving gateway owns this standalone app's OAuth session. */
+          gatewaySession?: boolean;
       };
 
 declare global {
@@ -141,6 +146,10 @@ export class VertesiaEnvironment implements Readonly<EnvProps> {
         const runtimeConfig = injectedRuntimeConfig() ?? buildRuntimeConfig(buildEnv);
         const runtimeFirebase = runtimeConfig?.authMode === 'firebase' ? runtimeConfig.firebase : undefined;
         this._props = props && runtimeFirebase && !props.firebase ? { ...props, firebase: runtimeFirebase } : props;
+        const authUrl = runtimeConfig?.authMode === 'central' ? runtimeConfig.authUrl?.trim() : undefined;
+        if (this._props && authUrl) {
+            this._props = { ...this._props, endpoints: { ...this._props.endpoints, auth: authUrl } };
+        }
         const tenantId =
             typeof buildEnv?.VITE_FIREBASE_TENANT_ID === 'string' ? buildEnv.VITE_FIREBASE_TENANT_ID.trim() : '';
         if (this._props?.firebase && tenantId && !this._props.firebase.tenantId) {
@@ -243,6 +252,10 @@ export class VertesiaEnvironment implements Readonly<EnvProps> {
         return this._props?.defaultAuthSelection;
     }
 
+    get oauth() {
+        return this._props?.oauth;
+    }
+
     get authTokenProvider() {
         return this._props?.authTokenProvider;
     }

package/src/session/UserSession.ts

@@ -7,6 +7,8 @@ import { createContext, useContext } from 'react';
 import { getComposableToken } from './auth/composable';
 import { authReturnUrl, centralAuthUrl, mountRootUrl, shouldRedirectToCentralAuth } from './auth/domainRouting';
 import { getFirebaseAuth } from './auth/firebase';
+import { gatewayFetch, loadGatewaySession, logoutGatewaySession, usesGatewaySession } from './auth/gateway';
+import { clearAppOAuth, getAppOAuthToken, usesAppOAuth } from './auth/oauth';
 
 import { LastSelectedAccountId_KEY, LastSelectedProjectId_KEY } from './constants';
 
@@ -31,9 +33,14 @@ class UserSession {
             this.client = client;
         } else {
             this.client = new VertesiaClient({
-                serverUrl: Env.endpoints.studio,
-                storeUrl: Env.endpoints.zeno,
+                serverUrl: usesGatewaySession()
+                    ? `${window.location.origin}/__appgen/session/studio`
+                    : Env.endpoints.studio,
+                storeUrl: usesGatewaySession()
+                    ? `${window.location.origin}/__appgen/session/store`
+                    : Env.endpoints.zeno,
                 tokenServerUrl: Env.endpoints.sts,
+                fetch: usesGatewaySession() ? gatewayFetch : undefined,
             });
         }
 
@@ -73,6 +80,9 @@ class UserSession {
     }
 
     get rawAuthToken() {
+        if (usesAppOAuth()) return getAppOAuthToken();
+        if (usesGatewaySession())
+            return Promise.reject(new Error('Gateway session credentials are not available to application JavaScript'));
         return getComposableToken().then((res) => {
             const token = res?.rawToken;
             if (!token) {
@@ -89,6 +99,17 @@ class UserSession {
      * stale — STS recomputes the `apps` claim from ACEs on every issuance.
      */
     async refreshAuthToken(): Promise<AuthTokenPayload> {
+        if (usesGatewaySession()) {
+            const payload = await this.loginGatewaySession();
+            this.setSession?.(this.clone());
+            return payload;
+        }
+        if (usesAppOAuth()) {
+            clearAppOAuth();
+            this.authToken = jwtDecode<AuthTokenPayload>(await getAppOAuthToken());
+            this.setSession?.(this.clone());
+            return this.authToken;
+        }
         const res = await getComposableToken(undefined, undefined, undefined, true);
         const token = res?.rawToken;
         if (!token) {
@@ -133,12 +154,47 @@ class UserSession {
         return Promise.resolve();
     }
 
+    async loginGatewaySession() {
+        this.authToken = await loadGatewaySession();
+        this.client.withAuthCallback(undefined);
+        this.authError = undefined;
+        this.isLoading = false;
+        Env.onLogin?.(this.authToken);
+        return this.authToken;
+    }
+
     isLoggedIn() {
         return !!this.authToken;
     }
 
     logout() {
         console.log('Logging out');
+        if (usesGatewaySession()) {
+            void logoutGatewaySession()
+                .then(() => {
+                    this.authToken = undefined;
+                    this.authError = undefined;
+                    this.isLoading = false;
+                    Env.onLogout?.();
+                    this.setSession?.(this.clone());
+                })
+                .catch((error: unknown) => {
+                    this.authError = error instanceof Error ? error : new Error(String(error));
+                    this.setSession?.(this.clone());
+                });
+            return;
+        }
+
+        if (usesAppOAuth()) {
+            clearAppOAuth();
+            this.client.withAuthCallback(undefined);
+            this.authToken = undefined;
+            this.authError = undefined;
+            this.isLoading = false;
+            Env.onLogout?.();
+            this.setSession?.(this.clone());
+            return;
+        }
 
         if (shouldRedirectToCentralAuth()) {
             // Redirect to central auth for logout

package/src/session/UserSessionProvider.strict-mode.test.tsx

@@ -3,6 +3,7 @@ import { Env } from '@vertesia/ui/env';
 import { StrictMode } from 'react';
 import { afterEach, expect, it, vi } from 'vitest';
 import { redirectToCentralAuth } from './auth/domainRouting';
+import { useUserSession } from './UserSession';
 import { UserSessionProvider } from './UserSessionProvider';
 
 vi.mock('./auth/useAuthState', () => ({ useAuthState: () => ({}) }));
@@ -15,6 +16,8 @@ vi.mock('./auth/domainRouting', async (importOriginal) => ({
 afterEach(() => {
     cleanup();
     vi.clearAllMocks();
+    vi.unstubAllGlobals();
+    delete window.__VERTESIA_RUNTIME_CONFIG__;
 });
 
 it('continues authentication after StrictMode cancels the first host-token attempt', async () => {
@@ -42,3 +45,36 @@ it('continues authentication after StrictMode cancels the first host-token attem
     await waitFor(() => expect(redirectToCentralAuth).toHaveBeenCalledTimes(1));
     expect(authTokenProvider).toHaveBeenCalledTimes(2);
 });
+
+it('bootstraps a gateway session from claims without starting broker authentication', async () => {
+    window.__VERTESIA_RUNTIME_CONFIG__ = { authMode: 'central', gatewaySession: true };
+    const claims = { sub: 'gateway-user', name: 'Gateway User', account: { id: 'a' }, project: { id: 'p' } };
+    const fetch = vi.fn(async (_request: Request) => Response.json(claims));
+    vi.stubGlobal('fetch', fetch);
+    Env.init({
+        name: 'gateway',
+        version: '1',
+        type: 'production',
+        isLocalDev: false,
+        isDocker: false,
+        endpoints: {
+            studio: 'https://api.example.com',
+            zeno: 'https://api.example.com',
+            sts: 'https://sts.example.com',
+        },
+    });
+    function Probe() {
+        const session = useUserSession();
+        return <span>{session.user?.name}</span>;
+    }
+    const view = render(
+        <StrictMode>
+            <UserSessionProvider>
+                <Probe />
+            </UserSessionProvider>
+        </StrictMode>,
+    );
+    await view.findByText('Gateway User');
+    expect(redirectToCentralAuth).not.toHaveBeenCalled();
+    expect(fetch.mock.calls.every(([request]) => new URL(request.url).pathname === '/__appgen/session')).toBe(true);
+});

package/src/session/UserSessionProvider.tsx

@@ -14,6 +14,8 @@ import {
 } from './auth/composable';
 import { buildCentralAuthRedirectUrl, redirectToCentralAuth, shouldRedirectToCentralAuth } from './auth/domainRouting';
 import { getFirebaseAuth } from './auth/firebase';
+import { usesGatewaySession } from './auth/gateway';
+import { getAppOAuthToken, usesAppOAuth } from './auth/oauth';
 import { useAuthState } from './auth/useAuthState';
 import { UserSession, UserSessionContext } from './UserSession';
 
@@ -130,6 +132,28 @@ export function UserSessionProvider({ children, loadOnboardingStatus = true }: U
             },
         });
 
+        if (usesGatewaySession() || usesAppOAuth()) {
+            let cancelled = false;
+            session.setSession = setSession;
+            const initialize = usesGatewaySession()
+                ? session.loginGatewaySession()
+                : getAppOAuthToken().then((token) => session.login(token, { loadOnboardingStatus: false }));
+            void initialize
+                .then(() => {
+                    if (!cancelled) setSession(session.clone());
+                })
+                .catch((error: unknown) => {
+                    if (cancelled) return;
+                    session.isLoading = false;
+                    session.authError = error instanceof Error ? error : new Error(String(error));
+                    setSession(session.clone());
+                });
+            return () => {
+                cancelled = true;
+                hasInitiatedAuthRef.current = false;
+            };
+        }
+
         if (Env.isLocalDev && Env.devAuthToken) {
             session.setSession = setSession;
             getComposableToken(selectedAccount, selectedProject, Env.devAuthToken)

package/src/session/auth/auth-flow.md

@@ -6,10 +6,22 @@ This document describes the authentication flow for the Vertesia user-facing app
 
 The authentication system uses:
 - **Firebase** for identity management and OAuth provider integration
-- **Central Auth** (internal-auth.vertesia.app) for centralized authentication flow
+- **Central Auth** (auth.vertesia.io) for centralized authentication flow
 - **STS (Security Token Service)** (sts.vertesia.io) to validate Firebase tokens and generate Vertesia JWT tokens
 - **Session state management** to validate redirects and prevent CSRF attacks
 
+### Central Auth endpoint selection
+
+`https://auth.vertesia.io/` is the default broker. Regional scaffolding can set
+`VITE_AUTH_ENDPOINT`; applications can also configure the `Env` initialization property `endpoints.auth` explicitly.
+For compatible generated app shells, a gateway-provided central runtime config
+(`window.__VERTESIA_RUNTIME_CONFIG__` with `authMode: 'central'` and `authUrl`)
+takes precedence over the build-time endpoint. A runtime config without `authUrl`
+retains the configured endpoint or default. Explicit Firebase mode uses direct
+Firebase authentication instead of the central broker.
+
+The diagrams below use the default hostname; redirects use the selected broker.
+
 ### STS Endpoints
 - Production/Preview: `https://sts.vertesia.io`
 - Staging: `https://sts.dev1.vertesia.io`
@@ -179,7 +191,7 @@ The authentication system uses:
 ┌──────────────────────┐    │ - Microsoft          │    ┌──────────────────────┐
 │ Build redirect URL:  │    └──────────┬───────────┘    │ Redirect to SSO      │
 │                      │               │                │ provider (Okta,      │
-│ internal-auth        │               ▼                │ Azure AD, etc.)      │
+│ auth.vertesia.io     │               ▼                │ Azure AD, etc.)      │
 │ .vertesia.app        │    ┌──────────────────────┐    └──────────┬───────────┘
 │ ?sts=...             │    │ Firebase OAuth       │               │
 │ &redirect_uri=...    │    │ redirect & return    │               ▼
@@ -329,7 +341,7 @@ The authentication system uses:
 
 ### Path A: Central Auth (Option 1) - Returns with JWT
 1. User clicks "Continue with Central Auth"
-2. Redirects to internal-auth.vertesia.app
+2. Redirects to auth.vertesia.io
 3. Central auth authenticates user and gets Firebase token
 4. **Central auth calls STS** (`POST sts.vertesia.io/token/issue` with Firebase token)
 5. **STS validates Firebase token and generates Vertesia JWT**
@@ -472,7 +484,7 @@ The authentication system uses:
                 │ Redirect to Central  │         │ getFirebaseAuth()    │
                 │ Auth for logout:     │         │   .signOut()         │
                 │                      │         │                      │
-                │ internal-auth        │         │ (Triggers            │
+                │ auth.vertesia.io     │         │ (Triggers            │
                 │  .vertesia.app       │         │  onAuthStateChanged  │
                 │  /logout             │         │  with anonymous user)│
                 │                      │         └──────────┬───────────┘
@@ -712,7 +724,7 @@ flowchart TB
     subgraph Option1[OPTION 1: CENTRAL AUTH]
         C1[Generate state<br/>Save to sessionStorage]
         C2[Get account/project<br/>from URL or localStorage]
-        C3[Build redirect URL:<br/>internal-auth.vertesia.app<br/>?sts=...&redirect_uri=...&state=...]
+        C3[Build redirect URL:<br/>auth.vertesia.io<br/>?sts=...&redirect_uri=...&state=...]
         C4[window.location.replace<br/>to central auth]
         C5[Central Auth Page<br/>User authenticates<br/>Gets Firebase token]
         C6[Central auth calls STS:<br/>POST sts.vertesia.io/token/issue<br/>Authorization: Bearer Firebase<br/>Body: type, account_id, project_id]
@@ -774,7 +786,7 @@ flowchart TB
 
     Check -->|YES| ShouldRedirect{shouldRedirectTo<br/>CentralAuth?}
 
-    ShouldRedirect -->|YES| RedirectLogout[Redirect to Central Auth<br/>for logout<br/><br/>internal-auth.vertesia.app<br/>/logout<br/><br/>Central auth handles<br/>Firebase logout]
+    ShouldRedirect -->|YES| RedirectLogout[Redirect to Central Auth<br/>for logout<br/><br/>auth.vertesia.io<br/>/logout<br/><br/>Central auth handles<br/>Firebase logout]
 
     ShouldRedirect -->|NO| FirebaseSignout[getFirebaseAuth.signOut<br/><br/>Triggers onAuthStateChanged<br/>with anonymous user]
 
@@ -837,7 +849,7 @@ flowchart TB
 sequenceDiagram
     actor User
     participant App as Composable UI
-    participant CentralAuth as Central Auth<br/>(internal-auth.vertesia.app)
+    participant CentralAuth as Central Auth<br/>(auth.vertesia.io)
     participant Firebase as Firebase Auth
     participant STS as STS<br/>(sts.vertesia.io)
 
@@ -1030,7 +1042,7 @@ flowchart TB
 
     Check -->|YES| ShouldRedirect{shouldRedirectTo<br/>CentralAuth?}
 
-    ShouldRedirect -->|YES| RedirectLogout[Redirect to Central Auth<br/>for logout<br/><br/>internal-auth.vertesia.app<br/>/logout<br/><br/>Central auth handles<br/>Firebase logout]
+    ShouldRedirect -->|YES| RedirectLogout[Redirect to Central Auth<br/>for logout<br/><br/>auth.vertesia.io<br/>/logout<br/><br/>Central auth handles<br/>Firebase logout]
 
     ShouldRedirect -->|NO| FirebaseSignout[getFirebaseAuth.signOut<br/><br/>Triggers onAuthStateChanged<br/>with anonymous user]
 
@@ -1078,7 +1090,7 @@ flowchart TB
         LO2[session.logout or<br/>session.signOut]
         LO3{authToken<br/>exists?}
         LO4{shouldRedirectTo<br/>CentralAuth?}
-        LO5[Redirect to Central Auth<br/>for logout<br/><br/>internal-auth.vertesia.app<br/>/logout<br/><br/>Central auth handles<br/>Firebase logout]
+        LO5[Redirect to Central Auth<br/>for logout<br/><br/>auth.vertesia.io<br/>/logout<br/><br/>Central auth handles<br/>Firebase logout]
         LO6[getFirebaseAuth.signOut<br/><br/>Triggers onAuthStateChanged<br/>with anonymous user]
         LO7[Clear session data:<br/>- authError = undefined<br/>- isLoading = false<br/>- authToken = undefined<br/>- typeRegistry = undefined]
         LO8[client.withAuthCallback<br/>undefined<br/><br/>Clear client auth]

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

@@ -77,7 +77,7 @@ describe('centralAuthUrl', () => {
     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/');
+        expect(DEFAULT_CENTRAL_AUTH_URL).toBe('https://auth.vertesia.io/');
     });
 
     it('uses the configured auth endpoint when one is set', () => {

package/src/session/auth/domainRouting.ts

@@ -1,5 +1,7 @@
 import { Env } from '@vertesia/ui/env';
 import { generateAuthState } from './authState';
+import { gatewayLoginUrl, usesGatewaySession } from './gateway';
+import { getAppOAuthToken, usesAppOAuth } from './oauth';
 
 declare global {
     interface Window {
@@ -10,11 +12,10 @@ 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.
+ * A gateway or app can select a regional broker through Env.endpoints.auth.
+ * Unconfigured apps use the first-party central broker.
  */
-export const DEFAULT_CENTRAL_AUTH_URL = 'https://internal-auth.vertesia.app/';
+export const DEFAULT_CENTRAL_AUTH_URL = 'https://auth.vertesia.io/';
 
 export function centralAuthUrl(): string {
     const configured = Env.endpoints.auth;
@@ -146,6 +147,14 @@ export function clearCentralAuthRoundTripMarker(): void {
  * into producing different `redirect_uri` / `state` / `sts` values for the same page load.
  */
 export function redirectToCentralAuth(selection: AuthSelection = {}): void {
+    if (usesAppOAuth()) {
+        void getAppOAuthToken().catch((error: unknown) => Env.logger.error('Application OAuth sign-in failed', error));
+        return;
+    }
+    if (usesGatewaySession()) {
+        window.location.replace(gatewayLoginUrl());
+        return;
+    }
     const url = buildCentralAuthRedirectUrl(
         centralAuthUrl(),
         Env.endpoints.sts ?? 'https://sts.vertesia.io',
@@ -178,6 +187,7 @@ export function redirectToCentralAuth(selection: AuthSelection = {}): void {
  * chunks that the navigation is about to discard.
  */
 export function isCentralAuthRedirectPending(): boolean {
+    if (usesGatewaySession() || usesAppOAuth()) return false;
     if (!shouldRedirectToCentralAuth()) return false;
     if (Env.authTokenProvider) return false;
     if (Env.isLocalDev && Env.devAuthToken) return false;

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

@@ -0,0 +1,82 @@
+// @vitest-environment node
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { gatewayFetch, gatewayLoginUrl, loadGatewaySession, logoutGatewaySession, usesGatewaySession } from './gateway';
+
+const replace = vi.fn();
+beforeEach(() => {
+    const browser = {
+        location: {
+            href: 'https://app.example/reports?a=account&p=project#chart',
+            origin: 'https://app.example',
+            replace,
+        },
+        __VERTESIA_RUNTIME_CONFIG__: { authMode: 'central', gatewaySession: true },
+    };
+    vi.stubGlobal('window', Object.assign(browser, { parent: browser }));
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+});
+
+it('activates only for a standalone app explicitly served with a gateway session', () => {
+    expect(usesGatewaySession()).toBe(true);
+    window.__VERTESIA_RUNTIME_CONFIG__ = { authMode: 'central' };
+    expect(usesGatewaySession()).toBe(false);
+    window.__VERTESIA_RUNTIME_CONFIG__ = { authMode: 'central', gatewaySession: true };
+    Object.defineProperty(window, 'parent', { value: {} });
+    expect(usesGatewaySession()).toBe(false);
+});
+it('preserves account, project and deep link through the existing OAuth login route', () => {
+    const url = new URL(gatewayLoginUrl());
+    expect(url.origin + url.pathname).toBe('https://app.example/__appgen/auth/login');
+    expect(url.searchParams.get('target')).toBe('/reports?a=account&p=project#chart');
+});
+it('uses same-origin cookies and never forwards browser bearer credentials', async () => {
+    const fetch = vi.fn(async (_request: Request) => new Response('{}'));
+    vi.stubGlobal('fetch', fetch);
+    await gatewayFetch('https://app.example/__appgen/session/studio/api/v1/apps', {
+        headers: { Authorization: 'Bearer browser-token' },
+    });
+    const request = fetch.mock.calls[0]?.[0] as Request | undefined;
+    expect(request?.headers.get('authorization')).toBeNull();
+    expect(request?.headers.get('x-vertesia-app-session')).toBe('1');
+    expect(request?.credentials).toBe('same-origin');
+    await expect(gatewayFetch('https://other.example/api')).rejects.toThrow('application origin');
+    expect(fetch).toHaveBeenCalledTimes(1);
+});
+it('redirects an expired session into CIMD login without invoking the direct broker', async () => {
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(
+            async () =>
+                new Response('{}', {
+                    status: 401,
+                    headers: { 'x-vertesia-session-required': '1' },
+                }),
+        ),
+    );
+    void loadGatewaySession();
+    await vi.waitFor(() => expect(replace).toHaveBeenCalledWith(gatewayLoginUrl()));
+});
+it('surfaces outages and ordinary upstream 401s instead of creating login loops', async () => {
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => new Response('{}', { status: 503 })),
+    );
+    await expect(loadGatewaySession()).rejects.toThrow('503');
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => new Response('{}', { status: 401 })),
+    );
+    expect((await gatewayFetch('https://app.example/api')).status).toBe(401);
+    expect(replace).not.toHaveBeenCalled();
+});
+it('loads claims without a JWT and signs out through a protected POST', async () => {
+    const claims = { sub: 'user', account: { id: 'account' }, project: { id: 'project' } };
+    const fetch = vi.fn(async (_request: Request) => new Response(JSON.stringify(claims)));
+    vi.stubGlobal('fetch', fetch);
+    expect(await loadGatewaySession()).toEqual(claims);
+    await logoutGatewaySession();
+    expect(fetch.mock.calls.at(-1)?.[0].method).toBe('POST');
+});

package/src/session/auth/gateway.ts

@@ -0,0 +1,49 @@
+import type { AuthTokenPayload } from '@vertesia/common';
+
+export function usesGatewaySession(): boolean {
+    if (typeof window === 'undefined' || window.parent !== window) return false;
+    const config = window.__VERTESIA_RUNTIME_CONFIG__;
+    return config?.authMode === 'central' && config.gatewaySession === true;
+}
+
+export function gatewayLoginUrl(): string {
+    const current = new URL(window.location.href);
+    const url = new URL('/__appgen/auth/login', current.origin);
+    url.searchParams.set('target', `${current.pathname}${current.search}${current.hash}`);
+    return url.toString();
+}
+
+/** Same-origin cookie transport. The gateway attaches its OAuth credential upstream. */
+export async function gatewayFetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
+    const request = new Request(input, init);
+    if (new URL(request.url).origin !== window.location.origin) {
+        throw new Error('Gateway session requests must stay on the application origin');
+    }
+    const headers = new Headers(request.headers);
+    headers.delete('authorization');
+    headers.set('x-vertesia-app-session', '1');
+    const response = await fetch(new Request(request, { headers, credentials: 'same-origin', cache: 'no-store' }));
+    if (response.status === 401 && response.headers.get('x-vertesia-session-required') === '1') {
+        window.location.replace(gatewayLoginUrl());
+        // Navigation owns recovery. Do not fall back to Firebase or the direct broker flow.
+        return new Promise(() => {});
+    }
+    return response;
+}
+
+export async function loadGatewaySession(): Promise<AuthTokenPayload> {
+    const response = await gatewayFetch(new URL('/__appgen/session', window.location.origin).toString());
+    if (!response.ok) throw new Error(`Application session could not be loaded (${response.status})`);
+    const payload: AuthTokenPayload = await response.json();
+    if (!payload.sub || !payload.account?.id || !payload.project?.id) {
+        throw new Error('Application session returned invalid user information');
+    }
+    return payload;
+}
+
+export async function logoutGatewaySession(): Promise<void> {
+    const response = await gatewayFetch(new URL('/__appgen/session/logout', window.location.origin).toString(), {
+        method: 'POST',
+    });
+    if (!response.ok) throw new Error(`Application sign-out failed (${response.status})`);
+}