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

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

@@ -12,6 +12,8 @@ let browser: {
     history: { state: null; replaceState: ReturnType<typeof vi.fn> };
 };
 let requests: { url: string; init?: RequestInit }[];
+let revocationEndpoint: string | undefined;
+let tokenEndpoint: string;
 function jwt(): string {
     return `e30.${btoa(
         JSON.stringify({
@@ -24,7 +26,7 @@ function jwt(): string {
         }),
     )}.signature`;
 }
-async function setup() {
+async function setup(offlineAccess = false) {
     vi.resetModules();
     const { Env } = await import('../../env');
     Env.init({
@@ -34,12 +36,14 @@ async function setup() {
         isLocalDev: false,
         isDocker: false,
         endpoints: { studio: 'https://api.dev1.vertesia.io', zeno: 'https://api.dev1.vertesia.io', sts: issuer },
-        oauth: { clientId, redirectUri: `${origin}/app` },
+        oauth: { clientId, redirectUri: `${origin}/app`, offlineAccess },
     });
     return import('./oauth');
 }
 beforeEach(() => {
     storage.clear();
+    revocationEndpoint = undefined;
+    tokenEndpoint = `${issuer}/oauth/token`;
     requests = [];
     browser = {
         location: { href: `${origin}/app/report?a=a&p=p#chart`, origin, replace },
@@ -52,6 +56,7 @@ beforeEach(() => {
     };
     browser.parent = browser;
     vi.stubGlobal('window', browser);
+    vi.stubGlobal('document', { cookie: '' });
     vi.stubGlobal('sessionStorage', {
         getItem: (key: string) => storage.get(key) ?? null,
         setItem: (key: string, value: string) => storage.set(key, value),
@@ -66,14 +71,20 @@ beforeEach(() => {
                 return Response.json({
                     issuer,
                     authorization_endpoint: 'https://preview.cloud.dev1.vertesia.io/oauth/authorize',
-                    token_endpoint: `${issuer}/oauth/token`,
+                    token_endpoint: tokenEndpoint,
+                    revocation_endpoint: revocationEndpoint,
                 });
             if (url === clientId)
                 return Response.json({
                     redirect_uris: [`${origin}/app`],
                     scope: 'openid profile content:read offline_access',
                 });
-            if (url === `${issuer}/oauth/token`) return Response.json({ access_token: jwt(), token_type: 'Bearer' });
+            if (url === tokenEndpoint)
+                return Response.json({
+                    access_token: jwt(),
+                    token_type: 'Bearer',
+                    refresh_token: 'refresh-credential',
+                });
             throw new Error(`Unexpected request: ${url}`);
         }),
     );
@@ -90,6 +101,7 @@ it('uses CIMD and PKCE, exchanges the callback once and restores the app deep li
     await vi.waitFor(() => expect(replace).toHaveBeenCalledTimes(1));
     const authorize = new URL(replace.mock.calls[0][0]);
     expect(authorize.searchParams.get('client_id')).toBe(clientId);
+    expect(authorize.searchParams.get('resource')).toBe(`${issuer}/`);
     expect(authorize.searchParams.get('redirect_uri')).toBe(`${origin}/app`);
     expect(authorize.searchParams.get('scope')).toBe('openid profile content:read');
     expect(authorize.searchParams.get('project_id')).toBe('p');
@@ -106,6 +118,7 @@ it('uses CIMD and PKCE, exchanges the callback once and restores the app deep li
     const body = exchange.init?.body as URLSearchParams;
     expect(body.get('code_verifier')).toBe(txn.verifier);
     expect(body.get('grant_type')).toBe('authorization_code');
+    expect(body.get('resource')).toBe(authorize.searchParams.get('resource'));
     expect(body.has('client_secret')).toBe(false);
     expect(storage.has('vertesia.oauth.transaction')).toBe(false);
     expect(browser.location.href).toBe(`${origin}/app/report?a=a&p=p#chart`);
@@ -171,3 +184,107 @@ it('supports a registered client ID without fetching a CIMD', async () => {
     expect(authorize.searchParams.has('consent_required')).toBe(false);
     expect(requests).toHaveLength(1);
 });
+
+it('prefers an STS fragment token over OAuth', async () => {
+    const oauth = await setup();
+    storage.set('auth_state', 'state');
+    storage.set('auth_state_expiry', String(Date.now() + 60000));
+    Object.assign(browser.location, { hash: `#token=${jwt()}&state=state` });
+    expect(oauth.usesAppOAuth()).toBe(false);
+});
+async function loginOffline() {
+    const initial = await setup(true);
+    void initial.getAppOAuthToken();
+    await vi.waitFor(() => expect(replace).toHaveBeenCalledOnce());
+    const authorize = new URL(replace.mock.calls[0][0]);
+    browser.location.href = `${origin}/app?code=code&state=${authorize.searchParams.get('state')}`;
+    const oauth = await setup(true);
+    await oauth.getAppOAuthToken();
+    requests = [];
+    replace.mockClear();
+    return oauth;
+}
+it('keeps refresh credentials only in memory and revokes the latest one on logout', async () => {
+    const oauth = await loginOffline();
+    expect(storage.get('vertesia.oauth.access')).not.toContain('refresh-credential');
+    expect(await oauth.getAppOAuthToken(true)).toBeTruthy();
+    const exchange = requests.find((request) => request.url.endsWith('/oauth/token'));
+    if (!(exchange?.init?.body instanceof URLSearchParams)) throw new Error('Missing refresh grant');
+    expect(exchange.init.body.get('grant_type')).toBe('refresh_token');
+    expect(exchange.init.body.get('refresh_token')).toBe('refresh-credential');
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => new Response(null, { status: 200 })),
+    );
+    await oauth.revokeAppOAuthSession();
+    expect(String(vi.mocked(fetch).mock.calls[0][0])).toBe(`${issuer}/oauth/revoke`);
+    const body = vi.mocked(fetch).mock.calls[0][1]?.body as URLSearchParams;
+    expect(body.get('token')).toBe('refresh-credential');
+    expect(storage.has('vertesia.oauth.access')).toBe(false);
+});
+it('starts a fresh authorization when the refresh endpoint is unreachable', async () => {
+    const oauth = await loginOffline();
+    const original = fetch;
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+            if (String(input).endsWith('/oauth/token')) throw new TypeError('Network unavailable');
+            return original(input, init);
+        }),
+    );
+    void oauth.getAppOAuthToken(true);
+    await vi.waitFor(() => expect(replace).toHaveBeenCalledOnce());
+    expect(storage.has('vertesia.oauth.access')).toBe(false);
+});
+it('does not recover refresh credentials from browser storage after reload', async () => {
+    await loginOffline();
+    const reloaded = await setup(true);
+    void reloaded.getAppOAuthToken(true);
+    await vi.waitFor(() => expect(replace).toHaveBeenCalledOnce());
+    expect(requests.some(({ url }) => url.endsWith('/oauth/token'))).toBe(false);
+});
+it('does not let a forged fragment suppress OAuth without a matching state', async () => {
+    const oauth = await setup();
+    Object.assign(browser.location, { hash: `#token=${jwt()}&state=forged` });
+    expect(oauth.usesAppOAuth()).toBe(true);
+});
+
+it('routes a state-bound regional legacy token through branch STS without starting OAuth', async () => {
+    const oauth = await setup();
+    const { Env } = await import('../../env');
+    Env.endpoints.sts = 'https://token-server-dev-example.api.dev1.vertesia.io';
+    storage.set('auth_state', 'state');
+    storage.set('auth_state_expiry', String(Date.now() + 60000));
+    Object.assign(browser.location, { hash: `#token=${jwt()}&state=state` });
+    expect(oauth.usesAppOAuth()).toBe(false);
+    storage.delete('auth_state');
+    expect(oauth.usesAppOAuth()).toBe(true);
+});
+
+it.each([false, true])('uses the discovered revocation endpoint after refresh=%s', async (refresh) => {
+    tokenEndpoint = `${issuer}/custom/exchange`;
+    revocationEndpoint = `${issuer}/sessions/invalidate`;
+    const oauth = await loginOffline();
+    if (refresh) {
+        revocationEndpoint = `${issuer}/sessions/invalidate-v2`;
+        await oauth.getAppOAuthToken(true);
+    }
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => new Response(null, { status: 200 })),
+    );
+    await oauth.revokeAppOAuthSession();
+    expect(String(vi.mocked(fetch).mock.calls[0][0])).toBe(revocationEndpoint);
+    const body = vi.mocked(fetch).mock.calls[0][1]?.body as URLSearchParams;
+    expect(body.get('token')).toBe('refresh-credential');
+    expect(body.get('client_id')).toBe(clientId);
+    expect(storage.has('vertesia.oauth.access')).toBe(false);
+});
+
+it('rejects an insecure discovered revocation endpoint', async () => {
+    revocationEndpoint = 'http://insecure.example/revoke';
+    const oauth = await setup(true);
+    await expect(oauth.getAppOAuthToken()).rejects.toThrow();
+    expect(replace).not.toHaveBeenCalled();
+    expect(requests.some(({ url }) => url === tokenEndpoint)).toBe(false);
+});

package/src/session/auth/oauth.ts

@@ -1,15 +1,41 @@
 import type { AuthTokenPayload } from '@vertesia/common';
 import { Env } from '@vertesia/ui/env';
 import { jwtDecode } from 'jwt-decode';
+import { markCentralAuthRoundTripStarted } from './authRoundTrip';
+import { verifyAuthState } from './authState';
 import { usesGatewaySession } from './gateway';
+import { isStsTokenIssuer } from './tokenIssuer';
 
 const TRANSACTION_KEY = 'vertesia.oauth.transaction';
 const TOKEN_KEY = 'vertesia.oauth.access';
 const MAX_TRANSACTION_AGE = 10 * 60_000;
 let pending: Promise<string> | undefined;
+// Long-lived credentials never enter browser storage. A reload resumes via the broker when access expires.
+let refreshSession:
+    | { token: string; clientId: string; issuer: string; tokenEndpoint: string; revocationEndpoint?: string }
+    | undefined;
+
+export class OAuthLoginError extends Error {}
+
+function hasVertesiaFragmentToken(): boolean {
+    try {
+        const fragment = new URLSearchParams(window.location.hash.slice(1));
+        const token = fragment.get('token');
+        if (!token || verifyAuthState(fragment.get('state'))) return false;
+        return isStsTokenIssuer(jwtDecode<AuthTokenPayload>(token).iss, Env.endpoints.sts);
+    } catch {
+        return false;
+    }
+}
 
 export function usesAppOAuth(): boolean {
-    return Boolean(Env.oauth && window.parent === window && window.AUTH_MODE !== 'firebase' && !usesGatewaySession());
+    return Boolean(
+        Env.oauth &&
+            window.parent === window &&
+            window.AUTH_MODE !== 'firebase' &&
+            !usesGatewaySession() &&
+            !hasVertesiaFragmentToken(),
+    );
 }
 
 function base64url(bytes: Uint8Array): string {
@@ -38,12 +64,13 @@ interface Transaction {
 }
 
 export function clearAppOAuth(): void {
+    refreshSession = undefined;
     sessionStorage.removeItem(TOKEN_KEY);
     sessionStorage.removeItem(TRANSACTION_KEY);
 }
 
 /** Public-client PKCE for independently hosted apps. No Firebase identity token or client secret. */
-async function acquireToken(): Promise<string> {
+async function acquireToken(forceRefresh = false): Promise<string> {
     const config = Env.oauth;
     if (!config) throw new Error('Application OAuth is not configured');
     const clientId = config.clientId.trim();
@@ -65,6 +92,7 @@ async function acquireToken(): Promise<string> {
     const state = callback ? current.searchParams.get('state') : null;
     const code = callback ? current.searchParams.get('code') : null;
     const error = callback ? current.searchParams.get('error') : null;
+    let refreshCredential: string | undefined;
     let transaction: Transaction | undefined;
     if (state || code || error) {
         const raw = sessionStorage.getItem(TRANSACTION_KEY);
@@ -85,12 +113,31 @@ async function acquireToken(): Promise<string> {
     } else {
         const raw = sessionStorage.getItem(TOKEN_KEY);
         if (raw) {
-            const cached = JSON.parse(raw) as { token: string; clientId: string; issuer: string };
+            const cached = JSON.parse(raw) as {
+                token: string;
+                clientId: string;
+                issuer: string;
+                refreshToken?: string;
+            };
             const claims = jwtDecode<AuthTokenPayload>(cached.token);
+            if (
+                config.offlineAccess &&
+                cached.clientId === clientId &&
+                cached.issuer === issuer &&
+                (!current.searchParams.get('p') || claims.project?.id === current.searchParams.get('p')) &&
+                (!current.searchParams.get('a') || claims.account?.id === current.searchParams.get('a'))
+            )
+                refreshCredential =
+                    refreshSession?.clientId === clientId && refreshSession.issuer === issuer
+                        ? refreshSession.token
+                        : undefined;
+            // Discard credentials persisted by older SDK versions rather than loading them into the new session.
+            if (cached.refreshToken) sessionStorage.removeItem(TOKEN_KEY);
             if (
                 cached.clientId === clientId &&
                 cached.issuer === issuer &&
-                claims.exp > Date.now() / 1000 + 30 &&
+                !forceRefresh &&
+                claims.exp > Date.now() / 1000 + (config.offlineAccess ? 300 : 30) &&
                 (!current.searchParams.get('p') || claims.project?.id === current.searchParams.get('p')) &&
                 (!current.searchParams.get('a') || claims.account?.id === current.searchParams.get('a'))
             ) {
@@ -100,16 +147,77 @@ async function acquireToken(): Promise<string> {
     }
     const discovery = await fetch(`${issuer}/.well-known/oauth-authorization-server`);
     if (!discovery.ok) throw new Error(`OAuth discovery failed (${discovery.status})`);
-    const metadata: { issuer: string; authorization_endpoint: string; token_endpoint: string } = await discovery.json();
+    const metadata: {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        revocation_endpoint?: string;
+    } = await discovery.json();
     if (metadata.issuer.replace(/\/+$/, '') !== issuer) throw new Error('OAuth issuer mismatch');
     const authorize = httpsUrl(metadata.authorization_endpoint);
     const tokenEndpoint = httpsUrl(metadata.token_endpoint);
+    const revocationEndpoint =
+        metadata.revocation_endpoint === undefined ? undefined : httpsUrl(metadata.revocation_endpoint).toString();
+    const resource = new URL(metadata.issuer).toString();
+    if (refreshCredential) {
+        try {
+            const response = await fetch(tokenEndpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    grant_type: 'refresh_token',
+                    client_id: clientId,
+                    refresh_token: refreshCredential,
+                    resource,
+                }),
+            });
+            if (response.ok) {
+                const grant = (await response.json()) as {
+                    access_token?: string;
+                    refresh_token?: string;
+                    token_type?: string;
+                };
+                if (!grant.access_token || grant.token_type?.toLowerCase() !== 'bearer')
+                    throw new OAuthLoginError('Invalid OAuth refresh grant');
+                const claims = jwtDecode<AuthTokenPayload & { client_id?: string }>(grant.access_token);
+                if (
+                    claims.iss.replace(/\/+$/, '') !== issuer ||
+                    claims.client_id !== clientId ||
+                    claims.exp <= Date.now() / 1000 ||
+                    (!!current.searchParams.get('a') && claims.account?.id !== current.searchParams.get('a')) ||
+                    (!!current.searchParams.get('p') && claims.project?.id !== current.searchParams.get('p'))
+                )
+                    throw new OAuthLoginError('Invalid OAuth refresh identity');
+                sessionStorage.setItem(
+                    TOKEN_KEY,
+                    JSON.stringify({
+                        token: grant.access_token,
+                        clientId,
+                        issuer,
+                    }),
+                );
+                refreshSession = {
+                    token: grant.refresh_token ?? refreshCredential,
+                    clientId,
+                    issuer,
+                    tokenEndpoint: tokenEndpoint.toString(),
+                    revocationEndpoint,
+                };
+                return grant.access_token;
+            }
+        } catch {
+            // A failed or invalid refresh starts a fresh authorization transaction.
+        }
+        refreshSession = undefined;
+        sessionStorage.removeItem(TOKEN_KEY);
+    }
     if (transaction && code) {
         const response = await fetch(tokenEndpoint, {
             method: 'POST',
             headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
             body: new URLSearchParams({
                 grant_type: 'authorization_code',
+                resource,
                 code,
                 client_id: clientId,
                 redirect_uri: redirectUri,
@@ -117,7 +225,7 @@ async function acquireToken(): Promise<string> {
             }),
         });
         if (!response.ok) throw new Error(`OAuth code exchange failed (${response.status})`);
-        const grant: { access_token?: string; token_type?: string } = await response.json();
+        const grant: { access_token?: string; token_type?: string; refresh_token?: string } = await response.json();
         if (!grant.access_token || grant.token_type?.toLowerCase() !== 'bearer') throw new Error('Invalid OAuth grant');
         const claims = jwtDecode<AuthTokenPayload & { client_id?: string }>(grant.access_token);
         if (
@@ -127,9 +235,31 @@ async function acquireToken(): Promise<string> {
         ) {
             throw new Error('OAuth grant does not match this application');
         }
-        sessionStorage.setItem(TOKEN_KEY, JSON.stringify({ token: grant.access_token, clientId, issuer }));
+        sessionStorage.setItem(
+            TOKEN_KEY,
+            JSON.stringify({
+                token: grant.access_token,
+                clientId,
+                issuer,
+            }),
+        );
+        refreshSession =
+            config.offlineAccess && grant.refresh_token
+                ? {
+                      token: grant.refresh_token,
+                      clientId,
+                      issuer,
+                      tokenEndpoint: tokenEndpoint.toString(),
+                      revocationEndpoint,
+                  }
+                : undefined;
         const target = new URL(transaction.target);
         if (target.origin !== window.location.origin) throw new Error('Invalid OAuth return target');
+        if (claims.account?.id) target.searchParams.set('a', claims.account.id);
+        else target.searchParams.delete('a');
+        if (claims.project?.id) target.searchParams.set('p', claims.project.id);
+        else target.searchParams.delete('p');
+        if (target.pathname === '/auth/callback') target.pathname = '/';
         window.history.replaceState(window.history.state, '', target);
         return grant.access_token;
     }
@@ -156,21 +286,52 @@ async function acquireToken(): Promise<string> {
     authorize.searchParams.set('client_id', clientId);
     authorize.searchParams.set('redirect_uri', redirectUri);
     authorize.searchParams.set('response_type', 'code');
+    authorize.searchParams.set('resource', resource);
     authorize.searchParams.set('state', next.state);
     authorize.searchParams.set('code_challenge_method', 'S256');
     authorize.searchParams.set('code_challenge', base64url(new Uint8Array(digest)));
-    // This browser client intentionally requests no refresh token.
-    authorize.searchParams.set('scope', scopes.filter((s) => s !== 'offline_access').join(' '));
+    authorize.searchParams.set(
+        'scope',
+        (config.offlineAccess
+            ? [...new Set([...scopes, 'offline_access'])]
+            : scopes.filter((s) => s !== 'offline_access')
+        ).join(' '),
+    );
+    const account = current.searchParams.get('a');
+    if (account) authorize.searchParams.set('account_id', account);
     const project = current.searchParams.get('p');
     if (project) authorize.searchParams.set('project_id', project);
     sessionStorage.setItem(TRANSACTION_KEY, JSON.stringify(next));
+    markCentralAuthRoundTripStarted();
     window.location.replace(authorize.toString());
     return new Promise(() => {});
 }
 
-export function getAppOAuthToken(): Promise<string> {
-    pending ??= acquireToken().finally(() => {
+export function getAppOAuthToken(forceRefresh = false): Promise<string> {
+    pending ??= acquireToken(forceRefresh).finally(() => {
         pending = undefined;
     });
     return pending;
 }
+
+export function isAppOAuthLoginPending(): boolean {
+    return usesAppOAuth();
+}
+export const startAppOAuthLogin = getAppOAuthToken;
+
+export async function revokeAppOAuthSession(): Promise<void> {
+    const cached = refreshSession;
+    clearAppOAuth();
+    if (!cached) return;
+    const revoke = httpsUrl(cached.revocationEndpoint ?? cached.tokenEndpoint);
+    if (cached.revocationEndpoint === undefined) revoke.pathname = revoke.pathname.replace(/\/token$/, '/revoke');
+    await fetch(revoke, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            client_id: cached.clientId,
+            token: cached.token,
+            token_type_hint: 'refresh_token',
+        }),
+    });
+}

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { isStsTokenIssuer } from './tokenIssuer';
+
+const branch = 'https://token-server-dev-example.api.dev1.vertesia.io';
+describe('legacy STS issuer routing', () => {
+    it('recognizes the configured endpoint and regional branch issuer', () => {
+        expect(isStsTokenIssuer(`${branch}/`, branch)).toBe(true);
+        expect(isStsTokenIssuer('https://sts.dev1.vertesia.io/', branch)).toBe(true);
+    });
+    it.each([
+        'https://customer.example.com',
+        'https://token-server-dev-example.api.dev1.vertesia.io.attacker.test',
+        `${branch}:444`,
+        `${branch}/env/dev1/other`,
+        branch.replace('https:', 'http:'),
+        branch.replace('https://', 'https://user@'),
+    ])('does not infer a regional issuer for %s', (endpoint) => {
+        expect(isStsTokenIssuer('https://sts.dev1.vertesia.io', endpoint)).toBe(false);
+    });
+    it('rejects other regions and providers', () => {
+        expect(isStsTokenIssuer('https://sts.dev2.vertesia.io', branch)).toBe(false);
+        expect(isStsTokenIssuer('https://securetoken.google.com/project', branch)).toBe(false);
+        expect(isStsTokenIssuer(undefined, branch)).toBe(false);
+    });
+});

package/src/session/auth/tokenIssuer.ts

@@ -0,0 +1,25 @@
+/** Classify legacy STS credentials for routing; API servers still verify their signatures and grants. */
+export function isStsTokenIssuer(issuer: string | undefined, stsEndpoint: string): boolean {
+    if (!issuer) return false;
+    const normalized = issuer.replace(/\/+$/, '');
+    if (normalized === stsEndpoint.replace(/\/+$/, '')) return true;
+    try {
+        const endpoint = new URL(stsEndpoint);
+        // Branch STS uses a separate OAuth issuer but retains the regional issuer for legacy
+        // /token/issue and /token/sign credentials (including workload identity consumers).
+        const branch = /^token-server-dev-[a-z0-9-]+\.api\.(dev1|dev2)\.vertesia\.io$/.exec(endpoint.hostname);
+        return Boolean(
+            branch &&
+                endpoint.protocol === 'https:' &&
+                !endpoint.port &&
+                !endpoint.username &&
+                !endpoint.password &&
+                endpoint.pathname === '/' &&
+                !endpoint.search &&
+                !endpoint.hash &&
+                normalized === `https://sts.${branch[1]}.vertesia.io`,
+        );
+    } catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { isTrustedAuthBrokerUrl } from './vertesiaHosts';
+
+describe('runtime auth broker trust', () => {
+    it.each(['https://auth.vertesia.io/', 'https://auth.dev1.vertesia.io/', 'https://AUTH.US1.VERTESIA.IO./'])(
+        'accepts %s',
+        (url) => {
+            expect(isTrustedAuthBrokerUrl(url)).toBe(true);
+        },
+    );
+    it.each([
+        'https://evil.example/',
+        'https://auth.vertesia.io.evil/',
+        'https://apps.dev1.vertesia.io/',
+        'https://auth.vertesia.io@evil.example/',
+        'https://auth.vertesia.io/?redirect_uri=evil',
+        'http://auth.vertesia.io/',
+        'https://auth.vertesia.io:444/',
+    ])('rejects %s', (url) => {
+        expect(isTrustedAuthBrokerUrl(url)).toBe(false);
+    });
+    it('requires an explicit local development opt-in for loopback', () => {
+        expect(isTrustedAuthBrokerUrl('http://localhost:8080/')).toBe(false);
+        expect(isTrustedAuthBrokerUrl('http://localhost:8080/', { allowLoopback: true })).toBe(true);
+    });
+});

package/src/session/auth/vertesiaHosts.ts

@@ -0,0 +1,85 @@
+const LOOPBACK_IPV4 = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+/** A single DNS label: alphanumeric, inner hyphens allowed. */
+export const LABEL = '[a-z0-9](?:[a-z0-9-]*[a-z0-9])?';
+
+/** The region label is optional throughout, because each regional host has a global US alias. */
+export const REGION = `(?:${LABEL}\\.)?`;
+
+/**
+ * Hostnames served by the UI backend — Vertesia's own code, not merely a Vertesia-owned name:
+ *   `cloud.vertesia.io`, `cloud.us1.vertesia.io`                     — the Cloud UI
+ *   `preprod.cloud.vertesia.io`, `preview.cloud.us1.vertesia.io`     — its preview/preprod tiers
+ *   `acme.cloud.us1.vertesia.io`                                     — per-IdP-tenant branded hosts
+ *   `dev-feat-x.ui.dev1.vertesia.io`                                 — dynamic per-branch dev envs
+ *
+ * Mirrors the load-balancer host rules (region-lb/main.tf: `cloud.${var.domain}`,
+ * `*.cloud.${var.domain}`, `*.ui.${var.domain}`) rather than the DNS zone, so a name we merely own
+ * is not trusted for what serves it.
+ */
+export const FIRST_PARTY_HOST_PATTERNS: readonly RegExp[] = [
+    new RegExp(`^cloud\\.${REGION}vertesia\\.io$`),
+    new RegExp(`^${LABEL}\\.cloud\\.${REGION}vertesia\\.io$`),
+    new RegExp(`^${LABEL}\\.ui\\.${LABEL}\\.vertesia\\.io$`),
+];
+
+/**
+ * Public app-gateway origins. Stable tiers use the `apps*` browser-facing host, while development
+ * environments reach the gateway through its `*.api.*` Cloud Run route:
+ *   `apps.us1.vertesia.io`, `apps-preview.us1.vertesia.io`
+ *   `app-gateway-dev1.api.dev1.vertesia.io`, `app-gateway-us3.api.us3.vertesia.io`
+ *
+ * The second label is deliberately unconstrained. Branch environments do NOT each get a gateway —
+ * they share their region's (`detectGatewayUrl` in packages/server-common/src/env/ServerEnv.ts:444
+ * and `getAppgenServerBaseUrl` in packages/workflows/.../app_workspace/workspace-utils.ts), so the
+ * host published to browsers is region-scoped, while the per-branch `app-gateway-dev-<branch>`
+ * shape in the infrastructure README also exists. Matching `app-gateway-<anything>` covers both,
+ * and every Cloud Run service named that way *is* a gateway (region-compute/main.tf:373).
+ *
+ * These serve every tenant's published application from one shared origin, and published assets
+ * need no authentication — so this is generated, low-trust code sitting on a Vertesia-owned
+ * hostname. Owning the domain is not the test; which backend serves the origin is.
+ *
+ * Two load-balancer variables can map further hostnames onto the same backend —
+ * `appgen_host_aliases` and `appgen_preview_host_aliases` in
+ * infrastructure/terraform/modules/region-lb/variables.tf. Both are empty in every region today; if
+ * one is ever set, add the alias here too, or it silently falls through to the permissive branch of
+ * Policy L and becomes an origin that may receive a token at any path.
+ */
+export const GATEWAY_HOST_PATTERNS: readonly RegExp[] = [
+    new RegExp(`^apps(?:-preview|-preprod)?\\.${REGION}vertesia\\.io$`),
+    new RegExp(`^app-gateway-${LABEL}\\.api\\.${LABEL}\\.vertesia\\.io$`),
+];
+
+export function isLoopbackHostname(hostname: string): boolean {
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+        return true;
+    }
+    if (hostname === '::1' || hostname === '[::1]') {
+        return true;
+    }
+    return LOOPBACK_IPV4.test(hostname);
+}
+
+export function normalizeHostname(hostname: string): string {
+    return hostname.toLowerCase().replace(/\.$/, '');
+}
+
+export const AUTH_BROKER_HOST_PATTERNS: readonly RegExp[] = [new RegExp(`^auth\\.${REGION}vertesia\\.io$`)];
+
+export function isTrustedAuthBrokerUrl(value: string, options: { allowLoopback?: boolean } = {}): boolean {
+    try {
+        const url = new URL(value);
+        const hostname = normalizeHostname(url.hostname);
+        if (url.username || url.password || url.search || url.hash || url.pathname !== '/') return false;
+        if (options.allowLoopback && isLoopbackHostname(hostname)) {
+            return url.protocol === 'http:' || url.protocol === 'https:';
+        }
+        return (
+            url.protocol === 'https:' &&
+            !url.port &&
+            AUTH_BROKER_HOST_PATTERNS.some((pattern) => pattern.test(hostname))
+        );
+    } catch {
+        return false;
+    }
+}

package/src/session/index.ts

@@ -8,6 +8,7 @@ export {
     redirectToCentralAuth,
 } from './auth/domainRouting';
 export * from './auth/firebase';
+export { isAppOAuthLoginPending, startAppOAuthLogin } from './auth/oauth';
 export * from './auth/useAuthState';
 export * from './auth/useCurrentTenant';
 export * from './DevSessionProvider';

package/src/shell/AuthScreenPreview.tsx

@@ -1,7 +1,7 @@
 /** Developer-only visual fixtures. Mount outside the authenticated application tree. */
 import { I18nProvider, useUITranslation } from '@vertesia/ui/i18n';
 import type { ReactNode } from 'react';
-import type { AppBranding } from '../boot/branding.js';
+import { type AppBranding, vertesiaBranding } from '../boot/branding.js';
 import {
     AppBrandingProvider,
     BrandedAuthLoadingScreen,
@@ -215,11 +215,7 @@ export function AuthScreenPreview({
 export async function mountAuthScreenPreview(
     container: HTMLElement,
     screen: string,
-    branding: AppBranding = {
-        name: 'Vertesia',
-        logo: { light: '/logo-light.png', dark: '/logo-dark.png' },
-        loadingIcon: { light: '/icon.svg' },
-    },
+    branding: AppBranding = vertesiaBranding,
     screens: AuthScreens = {},
 ): Promise<void> {
     if (screen === 'boot') return;