@autional/shared 0.0.0-stage → 0.1.0-rc.33

package/src/auth/roles.ts

@@ -0,0 +1,120 @@
+/**
+ * Autional 共享登录 URL 构建工具（仅 buildLoginUrl）
+ *
+ * 职责划分（AC-008）：
+ * - 前端角色仅用于 UI 呈现（UX-only）；安全判断由后端 rbac-backed 授权强制。
+ * - 角色获取统一走 userinfo-first：`getCurrentRole()`（store 派生，见 ./store）
+ *   与 `useCurrentRole()`（响应式 hook，见 hooks/useCurrentRole）。
+ */
+
+import { getPortalUrl } from '../config';
+
+/** auth-pages 的静态/受保护路由 — 首段不会是租户 slug */
+const AUTH_ROUTE_RESERVED = new Set([
+	'oauth',
+	'login',
+	'register',
+	'forgot-password',
+	'reset-password',
+	'terms',
+	'privacy',
+	'error',
+	'logout',
+	'passkey',
+	'reapply',
+	'mfa',
+	'account',
+	'dashboard',
+	'magic-link',
+	'verify-email',
+	'verify-phone',
+	'mfa-challenge',
+	'mfa-setup',
+	'change-password',
+	'recover-account',
+	'account-deletion',
+	'verify-identity',
+]);
+
+/**
+ * 登出回程 URL：auth 域**裸根**入口 + `logout=1` 显式登出意图标记。
+ *
+ * 刻意不复用 buildLoginUrl：其租户 slug 保留会把 auth 域页面的登出落到
+ * `/<slug>/login`（登录页路由，不经入口路由），`logout=1` 在那里被静默忽略；
+ * 带会话回程甚至会被登录页 checkAndRedirect 直接放行成静默重登（F-W5c）。
+ * 裸根 = EntryRouter 唯一登出闸门：先终结 auth 域会话，再决定落点——
+ * 回程能解析出真实租户 → 裸 `/<slug>/login`（不带回程参数：登出即"重新开始"，
+ * 登录后走默认去向，去向选择权交还用户）；否则落 brand 裸根。
+ */
+export function buildLogoutUrl(returnUrl?: string): string {
+	const base = getPortalUrl('auth');
+	if (!base) return '/';
+	const redirect = returnUrl ? `redirect=${encodeURIComponent(returnUrl)}&` : '';
+	return `${base}/?${redirect}logout=1`;
+}
+
+/**
+ * 当前页是否已是 auth 的「登录承接面」——裸根入口（`/`、`/login`，由入口路由承接）、
+ * `/<slug>/login` 登录页、`/error` 错误页。
+ *
+ * 会话终结（onUnauthorized）时若已停在承接面，整页 replace 不但无益（目标就是本页），
+ * 还会因 buildLoginUrl 的防嵌套截断返回不带 redirect 的本页 —— 把 URL 中的回程目标
+ * 一并丢掉，且构成一次整页闪烁（F-W8b 修复②：存量过期 token 在登录页「静默弹走」）。
+ */
+export function isAuthLoginSurface(): boolean {
+	if (typeof window === 'undefined') return false;
+	const segs = window.location.pathname.split('/').filter(Boolean);
+	if (segs.length === 0) return true; // 裸根 `/`
+	if (segs[0] === 'login' || segs[0] === 'error') return true; // `/login`、`/error`
+	return segs.length === 2 && segs[1] === 'login'; // `/<slug>/login`
+}
+
+export function buildLoginUrl(returnUrl?: string, fromRequireAuth?: boolean): string {
+	const base = getPortalUrl('auth');
+	if (!base) return '/';
+
+	// 保留租户 slug：如果 returnUrl 落在 auth 域且首段是租户 slug，
+	// 跳转到 {base}/{slug}/login 而不是根路径（根路径是租户选择页）
+	let loginBase = base;
+	if (returnUrl) {
+		try {
+			const clean = new URL(returnUrl, typeof window !== 'undefined' ? window.location.origin : '');
+			const baseOrigin = new URL(base).origin;
+			const firstSeg = clean.pathname.split('/').filter(Boolean)[0];
+			if (
+				clean.origin === baseOrigin &&
+				firstSeg &&
+				!AUTH_ROUTE_RESERVED.has(firstSeg.toLowerCase())
+			) {
+				loginBase = `${base}/${firstSeg}/login`;
+			}
+		} catch {
+			/* invalid URL — fall through */
+		}
+	}
+
+	if (returnUrl) {
+		// 防止嵌套 redirect：仅当 returnUrl 落在 auth 域且本身已是登录页时才截断
+		try {
+			const clean = new URL(returnUrl, typeof window !== 'undefined' ? window.location.origin : '');
+			const baseOrigin = new URL(base).origin;
+			if (
+				clean.origin === baseOrigin &&
+				(clean.pathname === '/' || clean.pathname.endsWith('/login') || clean.href === base)
+			) {
+				return fromRequireAuth ? `${loginBase}?from_requireauth=1` : loginBase;
+			}
+		} catch {
+			/* invalid URL — fall through */
+		}
+		const qs = `?redirect=${encodeURIComponent(returnUrl)}`;
+		if (fromRequireAuth) {
+			return `${loginBase}${qs}&from_requireauth=1`;
+		}
+		return `${loginBase}${qs}`;
+	}
+	if (fromRequireAuth) {
+		return `${loginBase}?from_requireauth=1`;
+	}
+	return loginBase;
+}

package/src/auth/service.ts

@@ -0,0 +1,433 @@
+/**
+ * Autional AuthService — 认证系统的唯一入口
+ *
+ * 职责:
+ *  - 统一管理认证状态的读写（取代分散在各文件的直接 store/LS 操作）
+ *  - 提供 token 刷新、登出、401 处理等标准流程
+ *  - 提供事件订阅机制用于可观测性
+ *
+ * 使用原则:
+ *  - 所有组件必须通过 AuthService 访问认证状态，不得直接 import useAuthStore
+ *  - 所有组件必须通过 AuthService 变更认证状态，不得直接调 store action
+ *  - apiClient 必须通过 AuthService.refreshToken() 处理 token 刷新
+ *  - logout 只有 AuthService.logout() 一个实现
+ *
+ * @see docs/architecture/auth-service-migration-plan.md
+ */
+
+import {
+	useAuthStore,
+	getAccessToken,
+	getRefreshToken,
+	getCurrentRole,
+	isTokenExpired as checkExpired,
+} from './store';
+import { loginWithTokens } from './store';
+import { buildLoginUrl, isAuthLoginSurface } from './roles';
+import { traceClear, traceEvent, traceRedirect } from './auth-trace';
+import { resolveClientIdForSession } from './oauth-client-id-store';
+import { extractItem } from '../utils/response';
+import type { User } from '../types';
+
+// ============ Internal State ============
+
+let refreshPromise: Promise<string | null> | null = null;
+
+// ============ OAuth PKCE Bootstrap Lock ============
+
+let _bootstrapLocked = false;
+
+/** Suppress onUnauthorized redirects during OAuth PKCE initialization */
+export function setBootstrapLock(locked: boolean): void {
+	_bootstrapLocked = locked;
+	if (typeof window !== 'undefined') (window as any).__bootstrapLocked = locked;
+}
+
+export function isBootstrapLocked(): boolean {
+	return _bootstrapLocked;
+}
+const listeners = new Map<string, Set<(data?: unknown) => void>>();
+
+function emit(event: string, data?: unknown) {
+	listeners.get(event)?.forEach((fn) => {
+		try {
+			fn(data);
+		} catch {
+			/* ignore */
+		}
+	});
+}
+
+// ============ Cross-tab Sync (BroadcastChannel) ============
+
+const BC_CHANNEL = 'autional-auth';
+let bc: BroadcastChannel | null = null;
+
+function initBroadcastChannel(): void {
+	if (typeof BroadcastChannel === 'undefined') return;
+	if (bc) return;
+	try {
+		bc = new BroadcastChannel(BC_CHANNEL);
+		bc.onmessage = (event) => {
+			const msg = event.data;
+			if (!msg || !msg.type) return;
+
+			switch (msg.type) {
+				case 'auth:logout':
+					// 另一个 tab 触发了登出 → 同步清除本 tab 状态
+					useAuthStore.getState().clearAuth();
+					if (typeof window !== 'undefined') {
+						localStorage.removeItem('autional-auth-v1');
+						localStorage.removeItem('access_token');
+						localStorage.removeItem('refresh_token');
+					}
+					emit('auth:logout', { source: 'broadcast' });
+					break;
+
+				case 'auth:login':
+					// 另一个 tab 登录成功 → 刷新本 tab 状态（可选）
+					// 可由消费方决定是否同步
+					emit('auth:login-broadcast', msg.data);
+					break;
+			}
+		};
+	} catch (e) {
+		console.warn('[AuthService] BroadcastChannel not available', (e as Error)?.message || '');
+	}
+}
+
+function broadcast(event: string, data?: unknown): void {
+	if (!bc) return;
+	try {
+		bc.postMessage({ type: event, data });
+	} catch {
+		/* ignore */
+	}
+}
+
+// ============ AuthService ============
+
+// Initialize cross-tab sync channel
+initBroadcastChannel();
+
+export const AuthService = {
+	// ==================== 读取（纯函数，无副作用） ====================
+
+	/** 获取 access token：Zustand store 优先，localStorage fallback */
+	getAccessToken: (): string | null => getAccessToken(),
+
+	/** 获取 refresh token */
+	getRefreshToken: (): string | null => getRefreshToken(),
+
+	/** 获取当前用户信息 */
+	getUser: (): User | null => useAuthStore.getState().user,
+
+	/** 是否已认证 */
+	isAuthenticated: (): boolean => useAuthStore.getState().isAuthenticated,
+
+	/** token 是否已过期 */
+	isTokenExpired: (token?: string): boolean => checkExpired(token || getAccessToken() || ''),
+
+	/** 获取当前租户 ID */
+	getCurrentTenantId: (): string | null => useAuthStore.getState().currentTenantId,
+
+	/** 获取当前租户列表 */
+	getTenants: (): Array<{ id: string; name: string; role: string }> =>
+		useAuthStore.getState().tenants,
+
+	/** 获取当前权限列表 */
+	getPermissions: (): string[] => useAuthStore.getState().permissions,
+
+	/** 获取当前角色（userinfo-first，委托 store 派生） */
+	getCurrentRole: (): string | null => getCurrentRole(),
+
+	// ==================== 写入（唯一变更入口） ====================
+
+	/** 登录成功后设置完整认证状态 */
+	setAuth: (accessToken: string, refreshToken: string, user: User): void => {
+		loginWithTokens(accessToken, refreshToken, user);
+		emit('auth:login', { userId: user.id, username: user.username });
+		broadcast('auth:login', { userId: user.id });
+	},
+
+	/** token 刷新后更新令牌 */
+	updateTokens: (accessToken: string, refreshToken: string): void => {
+		useAuthStore.getState().setTokens(accessToken, refreshToken);
+		emit('auth:tokens-refreshed');
+	},
+
+	/** 更新用户信息（来自 /auth/me） */
+	updateUser: (user: Partial<User>): void => {
+		const current = useAuthStore.getState().user;
+		// 防止跨用户覆盖：如果 store 中有用户但 ID 不匹配，忽略
+		if (current && user.id && current.id !== user.id) return;
+		useAuthStore.setState({ user: user as User });
+		emit('auth:user-updated', { userId: user.id });
+	},
+
+	/** 设置租户列表 */
+	updateTenants: (tenants: Array<{ id: string; name: string; role: string }>): void => {
+		useAuthStore.getState().setTenants(tenants);
+		emit('auth:tenants-updated');
+	},
+
+	/** 设置权限列表 */
+	updatePermissions: (permissions: string[]): void => {
+		useAuthStore.getState().setPermissions(permissions);
+		emit('auth:permissions-updated');
+	},
+
+	/** 切换当前租户 */
+	updateCurrentTenant: (tenantId: string): void => {
+		useAuthStore.getState().setCurrentTenant(tenantId);
+		emit('auth:tenant-changed', { tenantId });
+	},
+
+	// ==================== 登出（唯一实现） ====================
+
+	/**
+	 * 统一登出：
+	 * 1. 清除内存状态（立即生效）
+	 * 2. 清除所有持久化数据
+	 * 3. 服务端 token 吊销（best-effort，不阻塞）
+	 */
+	logout: async (): Promise<void> => {
+		const at = AuthService.getAccessToken();
+		const rt = AuthService.getRefreshToken();
+
+		// 1. 清除内存状态（立即生效，阻止后续操作使用过期 token）
+		useAuthStore.getState().clearAuth();
+
+		// 2. 清除所有持久化数据
+		if (typeof window !== 'undefined') {
+			localStorage.removeItem('autional-auth-v1');
+			localStorage.removeItem('access_token');
+			localStorage.removeItem('refresh_token');
+			localStorage.removeItem('__oauth_bridge_token');
+		}
+
+		// 2b. AUTH-08 会话卫生：清本 tab 的 OAuth 发起预置物（含明文 verifier）与
+		// trace 缓冲——sessionStorage 跨整页导航天然保留，不清则跨登出残留。
+		try {
+			const { discardPendingOAuthLogin } = await import('./oauth-login');
+			discardPendingOAuthLogin();
+		} catch {
+			/* best-effort */
+		}
+		traceClear();
+
+		// 3. 服务端 token 吊销（best-effort，不阻塞登出流程）。按与 refreshToken
+		//    相同的链判据分流（JWT 三段式 rt = identity 链）：
+		//    - OAuth（PKCE）链（不透明 rt + 已解析 client_id）：oauth revoke 端点
+		//      要求客户端认证（S9-A），公开客户端凭注册 client_id；access/refresh
+		//      各自成行、须逐条撤销；
+		//    - identity 链（rt 为 JWT / 无 client_id）：identity /auth/logout 携 AT
+		//      是权威撤销——单 token 黑名单（jwt:bl:）+ 会话级撤销（jwt:bls:，覆盖
+		//      该会话全部已签发 token）。修复前固定打 oauth revoke 且（会话无
+		//      client_id 时）不带凭据 → 必 401 静默（AUTH-15），identity 会话从未
+		//      被服务端终结。
+		try {
+			if (at || rt) {
+				const { default: axios } = await import('axios');
+				const { getApiBaseUrl } = await import('../config');
+				const baseUrl = getApiBaseUrl();
+				const clientId = resolveClientIdForSession();
+				const rtIsJwt = !!rt && rt.split('.').length === 3;
+
+				const record = (ev: string, chain: string, err?: unknown) => {
+					traceEvent(ev, {
+						reason: chain,
+						to: err ? String((err as any)?.response?.status ?? 'network-error') : 'ok',
+					});
+				};
+
+				if (rt && !rtIsJwt && clientId) {
+					const revokeParams = (token: string, hint: string) => {
+						const params = new URLSearchParams({ token, token_type_hint: hint });
+						params.set('client_id', clientId);
+						return params.toString();
+					};
+					if (at) {
+						await axios
+							.post(`${baseUrl}/oauth/api/v1/oauth/revoke`, revokeParams(at, 'access_token'), {
+								headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+							})
+							.then(() => record('logout-revoke', 'oauth-access_token'))
+							.catch((e) => record('logout-revoke-failed', 'oauth-access_token', e));
+					}
+					await axios
+						.post(`${baseUrl}/oauth/api/v1/oauth/revoke`, revokeParams(rt, 'refresh_token'), {
+							headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+						})
+						.then(() => record('logout-revoke', 'oauth-refresh_token'))
+						.catch((e) => record('logout-revoke-failed', 'oauth-refresh_token', e));
+				} else if (at) {
+					await axios
+						.post(`${baseUrl}/identity/api/v1/auth/logout`, null, {
+							headers: { Authorization: `Bearer ${at}` },
+						})
+						.then(() => record('logout-revoke', 'identity'))
+						.catch((e) => record('logout-revoke-failed', 'identity', e));
+				} else {
+					// 仅剩无法凭 client_id 走 oauth 的 rt（identity 签发的 JWT rt）：
+					// identity logout 需携 AT → 无凭据可吊销，记 trace 明示跳过
+					record('logout-revoke-skipped', 'no-credential');
+				}
+			}
+		} catch {
+			/* best-effort */
+		}
+
+		// 4. BFF 会话吊销（best-effort，httpOnly cookie 清理）
+		try {
+			const { bffLogout } = await import('../api/bff-client');
+			await bffLogout();
+		} catch {
+			/* best-effort */
+		}
+
+		broadcast('auth:logout');
+		emit('auth:logout');
+	},
+
+	// ==================== Token 刷新（统一超时防重入） ====================
+
+	/**
+	 * 刷新 access token。
+	 * 防重入：同一时间只会有一个刷新请求进行中。
+	 *
+	 * 失败处置（onFailure，缺省 'redirect'）：
+	 * - 'redirect'：onUnauthorized —— 清理 + 引导登录（常规路径）；
+	 * - 'clear'   ：clearSession —— 只清理不导航（调用方自控唯一导航出口，
+	 *               如会话过期横幅 → error 页，避免与整页跳转双跳竞争）；
+	 * - 'none'    ：零副作用静默（尽力续期场景：如过期前 5 分钟的自动续期尝试，
+	 *               失败不清理不打断——会话此刻仍有效，等真正过期再统一处置）。
+	 */
+	refreshToken: async (opts?: {
+		onFailure?: 'redirect' | 'clear' | 'none';
+	}): Promise<string | null> => {
+		if (refreshPromise) return refreshPromise;
+		const onFailure = opts?.onFailure ?? 'redirect';
+		const handleFailure = () => {
+			if (onFailure === 'redirect') AuthService.onUnauthorized();
+			else if (onFailure === 'clear') AuthService.clearSession();
+		};
+
+		refreshPromise = (async () => {
+			const rt = AuthService.getRefreshToken();
+			if (!rt) {
+				// During OAuth PKCE bootstrap (no token yet), suppress redirect.
+				// RequireAuth will handle OAuth PKCE vs BFF fallback once tenantRoute resolves.
+				if (!_bootstrapLocked) handleFailure();
+				return null;
+			}
+
+			try {
+				const { default: axios } = await import('axios');
+				const { getApiBaseUrl } = await import('../config');
+				const baseUrl = getApiBaseUrl();
+
+				// 按 refresh token 格式分流：
+				// - JWT（三段式，identity 链签发）→ identity /auth/refresh（现状逻辑）
+				// - opaque（rt- 前缀，OAuth PKCE 链签发）→ oauth /oauth/refresh（扁平 JSON，轮换式）
+				const isJwtRefreshToken = rt.split('.').length === 3;
+				// OAuth 链分流判据：会话内已解析值（持久化）→ env（TASK-09 / D8）
+				const clientId = resolveClientIdForSession();
+
+				let data: {
+					access_token?: string;
+					accessToken?: string;
+					refresh_token?: string;
+					refreshToken?: string;
+				};
+				if (isJwtRefreshToken || !clientId) {
+					// identity 链：标准信封响应 { code, message, data: { access_token, refresh_token } }
+					// 必须解包（2026-10-03 线上缺陷：未解包 ⇒ 200 被当失败 ⇒ 预警点横幅 +
+					// 到期旧 RT 重放 ⇒ 服务端反重放 revoke-all 全量吊销）
+					const resp = await axios.post(`${baseUrl}/identity/api/v1/auth/refresh`, {
+						refresh_token: rt,
+					});
+					data = extractItem(resp.data) ?? resp.data;
+				} else {
+					// OAuth 链：扁平 JSON 响应 { access_token, refresh_token, token_type, expires_in, scope }
+					const resp = await axios.post(`${baseUrl}/oauth/api/v1/oauth/refresh`, {
+						refresh_token: rt,
+						client_id: clientId,
+					});
+					data = resp.data;
+				}
+				const newAT = data.access_token || data.accessToken;
+				const newRT = data.refresh_token || data.refreshToken;
+				if (newAT) {
+					AuthService.updateTokens(newAT, newRT || rt);
+				}
+				return newAT || null;
+			} catch (err) {
+				console.warn('[AuthService] Token refresh failed', (err as Error)?.message || '');
+				handleFailure();
+				return null;
+			} finally {
+				refreshPromise = null;
+			}
+		})();
+
+		return refreshPromise;
+	},
+
+	// ==================== 401/未授权处理 ====================
+
+	/**
+	 * 仅清除会话状态（store + localStorage），不做任何导航。
+	 * 供 silent 刷新失败、以及需要自控导航出口的调用方使用。
+	 */
+	clearSession: (): void => {
+		useAuthStore.getState().clearAuth();
+		if (typeof window !== 'undefined') {
+			// 清除 localStorage（同步，立即生效）
+			localStorage.removeItem('autional-auth-v1');
+			localStorage.removeItem('access_token');
+			localStorage.removeItem('refresh_token');
+		}
+	},
+
+	/**
+	 * 处理 401 未授权响应：
+	 * 1. 清除所有状态（clearSession）
+	 * 2. 经 authTrace 提示（会话已过期 → 即将前往登录，可停留）后整页弹登录页
+	 *
+	 * 例外：已在 auth 登录承接面（裸根入口 / `/<slug>/login` / `/error`）时只清理不导航 ——
+	 * 目标就是当前页，整页 replace 反而会丢掉 URL 里的 redirect 回程目标并造成闪烁
+	 * （F-W8b 修复②）；承接面页面对 401 有自己的收口（登录页落表单、error 页走倒计时）。
+	 *
+	 * 重入抑制在 authTrace 内（pending 单例；并发 401 只提示一次、只跳一次）。
+	 */
+	onUnauthorized: (): void => {
+		// Suppress redirect during OAuth PKCE bootstrap — RequireAuth handles it
+		if (_bootstrapLocked) return;
+		// 先清除状态，不等待 logout 的异步吊销
+		AuthService.clearSession();
+
+		if (isAuthLoginSurface()) return;
+
+		if (typeof window !== 'undefined') {
+			traceRedirect(buildLoginUrl(window.location.href, true), {
+				reason: 'session-expired',
+				kind: 'interstitial',
+			});
+		}
+	},
+
+	// ==================== 事件订阅（可观测性） ====================
+
+	/**
+	 * 订阅认证事件。
+	 * @returns 取消订阅函数
+	 */
+	subscribe: (event: string, handler: (data?: unknown) => void): (() => void) => {
+		if (!listeners.has(event)) listeners.set(event, new Set());
+		listeners.get(event)!.add(handler);
+		return () => {
+			listeners.get(event)?.delete(handler);
+		};
+	},
+};

package/src/auth/slug-from-url.ts

@@ -0,0 +1,92 @@
+'use client';
+
+/**
+ * Extract tenant slug from current URL path.
+ * Works for patterns like /{slug}/admin, /{slug}/developer, /{slug}/dashboard, etc.
+ * Returns undefined if no slug pattern detected.
+ *
+ * Portals and reserved paths are excluded from slug detection:
+ * - Reserved paths: /oauth, /bff, /api, /health, /assets, etc.
+ * - Known portal prefixes at root: /admin, /developer, /security, etc.
+ */
+
+const RESERVED_SEGMENTS = [
+	'oauth',
+	'bff',
+	'api',
+	'api-v1',
+	'health',
+	'metrics',
+	'assets',
+	'docs',
+	'scalar',
+	'fonts',
+	'env.js',
+	'sdk',
+	'static',
+];
+
+const ROOT_PORTAL_PREFIXES: string[] = []; // No longer needed — each portal is now on its own domain
+
+/**
+ * 各 portal 自己的**业务路由首段**——它们不是租户 slug。
+ *
+ * 为什么是「注册」而不是在这里写死一份名单：这是**应用知识**，不是通用知识。
+ * auth 的 /login、/mfa-challenge、/account-deletion 对其他 portal 没有意义；
+ * 反过来 admin 的 /wallets、/settings 也不该塞进通用层。写死一份大名单，
+ * 等于把某一个 app 的路由表变成所有 portal 的契约。
+ *
+ * 实测（2026-09-29）：这份名单缺席时，extractSlugFromPath 会把**一切业务路由**
+ * 判成租户——/settings → 'settings'、/users/123 → 'users'、/dashboard → 'dashboard'。
+ * auth 站正是因此自己复制了一份带 24 项白名单的实现，而不是复用这里的函数。
+ */
+const NON_TENANT_SEGMENTS = new Set<string>();
+
+/** 由各 portal 在启动时注册自己的业务路由首段（大小写不敏感）。可多次调用。 */
+export function registerNonTenantSegments(segments: readonly string[]): void {
+	for (const s of segments) {
+		const v = String(s || '').trim().toLowerCase().replace(/^\/+|\/+$/g, '');
+		if (v) NON_TENANT_SEGMENTS.add(v);
+	}
+}
+
+/** 测试与多租户切换场景用：清空已注册的业务路由。 */
+export function clearNonTenantSegments(): void {
+	NON_TENANT_SEGMENTS.clear();
+}
+
+const isNonTenant = (seg: string) => RESERVED_SEGMENTS.includes(seg) || NON_TENANT_SEGMENTS.has(seg);
+
+
+export function extractSlugFromPath(pathname: string): string | undefined {
+	const segments = pathname.split('/').filter(Boolean);
+	if (segments.length === 0) return undefined;
+
+	const first = segments[0];
+
+	// Reserved segment at root level — not a slug
+	if (isNonTenant(first.toLowerCase())) return undefined;
+
+	// If only one segment and it looks like a portal prefix — not a slug
+	if (segments.length === 1 && ROOT_PORTAL_PREFIXES.includes(first.toLowerCase())) return undefined;
+
+	// Two+ segments: first is a slug unless it's a reserved segment
+	// With independent domains, the pattern is /{slug}/route, not /{slug}/{portal}/route
+	if (segments.length >= 2) {
+		if (!isNonTenant(first.toLowerCase())) {
+			return first;
+		}
+	}
+
+	// Single segment that's not a reserved path or portal prefix — could be a slug
+	if (segments.length === 1) {
+		return first;
+	}
+
+	return undefined;
+}
+
+export function useTenantSlugFromUrl(): string | undefined {
+	if (typeof window === 'undefined') return undefined;
+	return extractSlugFromPath(window.location.pathname);
+}