@autional-cn/shared 0.1.0-rc

package/src/auth/oauth-client-id-store.ts

@@ -0,0 +1,41 @@
+/**
+ * OAuth client_id 持久化（TASK-09 / D8）。
+ *
+ * 门户的 client_id 平时由 slug 实时解析（`oauth-client-from-slug.ts`）或 env 固定；
+ * 但刷新（`AuthService.refreshToken`）与登出吊销（`AuthService.logout`）不在 React
+ * 上下文里，拿不到 slug 解析结果 —— 故 OAuth 交棒时把已解析的 client_id 落 localStorage，
+ * 两处按「会话值（持久化）→ env → 空」顺序读取（`resolveClientIdForSession`）。
+ *
+ * 该值属于「本部署用哪个 OAuth 客户端」，非用户私有数据 ⇒ 登出不清除。
+ */
+
+const STORAGE_KEY = 'oauth_client_id';
+
+/** OAuth 交棒（PKCE 发起 / 回调兑换成功）时落库 */
+export function persistOAuthClientId(clientId: string): void {
+	if (typeof window === 'undefined' || !clientId) return;
+	try {
+		localStorage.setItem(STORAGE_KEY, clientId);
+	} catch {
+		/* 存储不可用（隐私模式）时静默：刷新回落 env，行为与接线前一致 */
+	}
+}
+
+export function getPersistedOAuthClientId(): string {
+	if (typeof window === 'undefined') return '';
+	try {
+		return localStorage.getItem(STORAGE_KEY) || '';
+	} catch {
+		return '';
+	}
+}
+
+/** 刷新/登出用：会话内已解析值优先，env 兜底 */
+export function resolveClientIdForSession(): string {
+	const persisted = getPersistedOAuthClientId();
+	if (persisted) return persisted;
+	if (typeof window !== 'undefined') {
+		return (window as any).__APP_CONFIG__?.VITE_OAUTH_CLIENT_ID || '';
+	}
+	return '';
+}

package/src/auth/oauth-login.ts

@@ -0,0 +1,291 @@
+/**
+ * Dev-mode OAuth PKCE login utilities
+ *
+ * Used by RequireAuth when VITE_OAUTH_CLIENT_ID is configured.
+ * Supports 3 profiles:
+ *   - dev:   API=localhost, OAuth=off (password login, no OAuth)
+ *   - oauth: API=localhost, OAuth=on  (local Docker API, tianv.local OAuth)
+ *   - prod:  API=production, OAuth=on (production API, iam.tianv.com OAuth)
+ */
+
+import { apiClient } from '../api/client';
+import { loginWithTokens } from './store';
+import { AuthService } from './service';
+import { generatePKCE } from './pkce';
+import { getPortalUrl } from '../config';
+import { persistOAuthClientId } from './oauth-client-id-store';
+import type { User } from '../types';
+
+function getAppConfig(): Record<string, string> | undefined {
+	if (typeof window !== 'undefined') {
+		return (window as any).__APP_CONFIG__;
+	}
+	return undefined;
+}
+
+const SK = {
+	PKCE: 'oauth_pkce_verifier',
+	STATE: 'oauth_state',
+	INIT: 'oauth_init',
+	INIT_TS: 'oauth_init_ts',
+	CID: 'oauth_client_id',
+};
+
+// 防重入拦截后的一次性重试 timer（避免 10 秒窗口内快速刷新导致 OAuth 跳转被吞、页面卡住）
+let retryTimer: ReturnType<typeof setTimeout> | null = null;
+
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+	try {
+		const parts = token.split('.');
+		if (parts.length !== 3) return null;
+		return JSON.parse(atob(parts[1]));
+	} catch {
+		return null;
+	}
+}
+
+function parseUserFromToken(token?: string, apiUser?: unknown): User {
+	if (token) {
+		const p = decodeJwtPayload(token);
+		if (p) {
+			return {
+				id: (p.sub || p.user_id) as string,
+				username: ((p as any).custom?.username || (p as any).username) as string,
+				email: p.email as string,
+				status: 'active',
+				avatar_url: p.picture as string,
+			} as unknown as User;
+		}
+	}
+	return apiUser as User;
+}
+
+function envVar(key: string): string {
+	const cfg = getAppConfig();
+	if (cfg && cfg[key]) return cfg[key];
+	try {
+		return (import.meta as any).env?.[key] || '';
+	} catch {
+		return '';
+	}
+}
+
+function getConfig() {
+	const base = getPortalUrl('auth');
+	const callbackPath = (window as any).__APP_CONFIG__?.BASE_PATH || '/';
+	const origin = window.location.origin;
+	return {
+		clientId: envVar('VITE_OAUTH_CLIENT_ID'),
+		authorizeUrl: `${base}/oauth/api/v1/oauth/authorize`,
+		redirectUri:
+			callbackPath === '/' ? `${origin}/oauth/callback` : `${origin}${callbackPath}/oauth/callback`,
+		scope: 'openid profile email offline_access',
+	};
+}
+
+export function isOAuthEnabled(): boolean {
+	return !!envVar('VITE_OAUTH_CLIENT_ID');
+}
+
+function randomState(): string {
+	if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+		try {
+			return crypto.randomUUID();
+		} catch {
+			/* fall through to getRandomValues */
+		}
+	}
+	// crypto.getRandomValues is available in non-secure contexts too (unlike
+	// randomUUID, which requires HTTPS/localhost). This value is used as the
+	// OAuth state CSRF token — never degrade to a state-recoverable, predictable
+	// PRNG or a timestamp (both are attackable for CSRF forgery). Fail loud.
+	if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+		const bytes = new Uint8Array(16);
+		crypto.getRandomValues(bytes);
+		return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+	}
+	throw new Error('No CSPRNG available — cannot generate secure OAuth state');
+}
+
+export async function initiateOAuthLogin(
+	clientId?: string,
+	redirectTarget?: string,
+): Promise<void> {
+	const ts = sessionStorage.getItem(SK.INIT_TS);
+	if (ts && Date.now() - parseInt(ts, 10) < 10000) {
+		// 防重入：10 秒内已有一次 OAuth 初始化（如快速刷新/重复导航）。
+		// 直接 return 会吞掉跳转导致 RequireAuth 卡在空白页（无 re-render 不会重试），
+		// 因此在窗口过期后安排一次自动重试，保证最终完成跳转。
+		const wait = 10000 - (Date.now() - parseInt(ts, 10)) + 100;
+		if (!retryTimer) {
+			retryTimer = setTimeout(() => {
+				retryTimer = null;
+				void initiateOAuthLogin(clientId, redirectTarget);
+			}, wait);
+		}
+		return;
+	}
+	sessionStorage.setItem(SK.INIT_TS, String(Date.now()));
+	sessionStorage.setItem(SK.INIT, '1');
+
+	// Determine the URL to redirect to after successful OAuth
+	const target = redirectTarget || window.location.href;
+
+	// Derive OAuth config (redirectUri computed from BASE_PATH, consistent with handleOAuthCallback)
+	const cfg = getConfig();
+	const cid = clientId || cfg.clientId;
+	if (!cid) throw new Error('OAuth client_id is not available');
+
+	// Always encode state as JSON with CSRF token + redirect target
+	const csrf = randomState();
+	const state = JSON.stringify({ csrf, redirect: target });
+
+	sessionStorage.setItem(SK.STATE, csrf);
+	sessionStorage.setItem(SK.CID, cid);
+	// 交棒时落持久层：刷新/登出在 React 上下文外，拿不到 slug 解析结果（TASK-09 / D8）
+	persistOAuthClientId(cid);
+
+	try {
+		const pkce = await generatePKCE();
+		sessionStorage.setItem(SK.PKCE, pkce.verifier);
+		const params = new URLSearchParams({
+			response_type: 'code',
+			client_id: cid,
+			redirect_uri: cfg.redirectUri,
+			scope: cfg.scope,
+			code_challenge: pkce.challenge,
+			code_challenge_method: 'S256',
+			state,
+		});
+		window.location.href = `${cfg.authorizeUrl}?${params}`;
+	} catch {
+		const params = new URLSearchParams({
+			response_type: 'code',
+			client_id: cid,
+			redirect_uri: cfg.redirectUri,
+			scope: cfg.scope,
+			state,
+		});
+		window.location.href = `${cfg.authorizeUrl}?${params}`;
+	}
+}
+
+export async function handleOAuthCallback(): Promise<void> {
+	const q = new URLSearchParams(window.location.search);
+
+	const err = q.get('error');
+	if (err) {
+		throw new Error(q.get('error_description') || `OAuth error: ${err}`);
+	}
+
+	const code = q.get('code');
+	if (!code) throw new Error('Missing authorization code');
+
+	const storedState = sessionStorage.getItem(SK.STATE) || '';
+	const verifier = sessionStorage.getItem(SK.PKCE) || '';
+	const cid = sessionStorage.getItem(SK.CID) || '';
+
+	// State is always JSON: { csrf, redirect }
+	let oauthRedirectTarget: string | null = null;
+	const rawState = q.get('state');
+	if (rawState) {
+		try {
+			const parsed = JSON.parse(rawState);
+			if (parsed.csrf && parsed.csrf === storedState) {
+				oauthRedirectTarget = parsed.redirect || null;
+			} else if (parsed.csrf) {
+				throw new Error('State mismatch — possible CSRF attack');
+			}
+		} catch {
+			// Backward compat: plain string state (should not happen after Fix 3)
+			if (rawState !== storedState) {
+				throw new Error('State mismatch — possible CSRF attack');
+			}
+		}
+	}
+
+	if (!verifier) throw new Error('Missing PKCE verifier — page reload may have cleared storage');
+
+	// Derive redirectUri from getConfig() for consistency with initiateOAuthLogin
+	const cbCfg = getConfig();
+	const redirectUri = cbCfg.redirectUri;
+
+	const res = await apiClient.post(
+		'/oauth/api/v1/oauth/token', // @generated-api-exempt
+		new URLSearchParams({
+			grant_type: 'authorization_code',
+			code,
+			client_id: cid,
+			client_secret: '',
+			redirect_uri: redirectUri,
+			code_verifier: verifier,
+		}).toString(),
+		{ headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
+	);
+
+	const t = res.data as any;
+	const accessToken = t.access_token;
+	const refreshToken = t.refresh_token || null;
+
+	// Prefer id_token for user info, fallback to /auth/me.
+	// IMPORTANT: loginWithTokens (which populates the auth store) runs AFTER this block,
+	// so the interceptor would send NO Authorization header here. Attach the freshly
+	// exchanged access_token explicitly — otherwise /auth/me 401s and the apiClient
+	// interceptor routes it through onUnauthorized (no refresh token yet) → bounce back
+	// to the login page with the now-consumed code → infinite redirect loop.
+	let user: User | null = parseUserFromToken(t.id_token);
+	if (!user && accessToken) {
+		try {
+			const me = await apiClient.get('/identity/api/v1/auth/me', {
+				// @generated-api-exempt
+				headers: { Authorization: `Bearer ${accessToken}` },
+			});
+			user = parseUserFromToken(undefined, me.data);
+		} catch {
+			// /auth/me may fail; loginWithTokens will still succeed with partial user
+		}
+	}
+	if (!user && accessToken) {
+		// id_token 缺失 + /auth/me 失败时，用 access_token JWT 兜底解析 user
+		// (access_token 由身份服务签发，payload 含 sub/custom.username/email/role)
+		user = parseUserFromToken(accessToken);
+	}
+	if (!user) {
+		user = { id: '', username: '', email: '' } as User;
+	}
+
+	// 兑换成功后落持久层（同 TASK-09 / D8；兑换前的持久值可能来自旧租户）
+	persistOAuthClientId(cid);
+
+	// Clean up temporary OAuth flow storage
+	sessionStorage.removeItem(SK.STATE);
+	sessionStorage.removeItem(SK.PKCE);
+	sessionStorage.removeItem(SK.CID);
+
+	// Persist to Zustand store (in-memory).
+	// Zustand persist subscriber will automatically write to localStorage
+	// via partialize — no manual localStorage.setItem needed.
+	loginWithTokens(accessToken, refreshToken, user);
+
+	// OAuth access_token 由身份服务签发，payload 含 tenant_id claim。
+	// 登录成功后初始化 currentTenantId，供 useTenantId()/useTenantIdOr() 等
+	// 页面使用真实租户（否则 fallback 'default-tenant' 导致 data-classification 等 404）。
+	const parsedToken = accessToken ? decodeJwtPayload(accessToken) : null;
+	const tokenTenantId = parsedToken?.tenant_id || (parsedToken as any)?.tenantId;
+	if (tokenTenantId) {
+		AuthService.updateCurrentTenant(tokenTenantId as string);
+	}
+
+	// Compute navigation target
+	let target: string;
+	if (oauthRedirectTarget) {
+		target = oauthRedirectTarget;
+	} else {
+		// Fallback to BASE_PATH from app config or root
+		const fallbackBase = (window as any).__APP_CONFIG__?.BASE_PATH || '/';
+		target = fallbackBase === '/' ? '/' : `${window.location.origin}${fallbackBase}/`;
+	}
+
+	// Full page navigation to the target (auth gateway will route to dashboard)
+	window.location.href = target;
+}

package/src/auth/pkce.ts

@@ -0,0 +1,141 @@
+/**
+ * RFC 7636 — OAuth2 PKCE (Proof Key for Code Exchange)
+ *
+ * Uses Web Crypto API (crypto.subtle) when available.
+ * Falls back to a compact, verified pure-JS SHA-256 implementation for non-secure contexts (HTTP).
+ */
+
+function base64URLEncode(buffer: ArrayBuffer): string {
+	const bytes = new Uint8Array(buffer);
+	let binary = '';
+	for (let i = 0; i < bytes.length; i++) {
+		binary += String.fromCharCode(bytes[i]);
+	}
+	return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function generateRandomString(length: number): string {
+	const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'; // 66 chars
+	if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+		// Never silently degrade to a weak, state-recoverable PRNG — the PKCE
+		// verifier is a security credential. Fail loud instead.
+		throw new Error('crypto.getRandomValues is unavailable — cannot generate PKCE verifier');
+	}
+	// Rejection sampling to remove modulo bias: 256 % 66 = 58, so a naive
+	// `byte % 66` makes chars 0-57 ~3% likelier than chars 58-65. Instead we
+	// build a 198-char lookup table (chars repeated 3×, each char exactly 3
+	// times) and only accept bytes < 198 — pool[byte] is then perfectly
+	// uniform (every char has probability 3/198 = 1/66).
+	const maxAccepted = Math.floor(256 / chars.length) * chars.length; // 198
+	const pool = chars.repeat(maxAccepted / chars.length); // 66 × 3 = 198 chars
+	let result = '';
+	while (result.length < length) {
+		const array = new Uint8Array(length - result.length);
+		crypto.getRandomValues(array);
+		for (const byte of array) {
+			if (byte < maxAccepted) {
+				result += pool[byte];
+			}
+		}
+	}
+	return result;
+}
+
+export interface PKCEPair {
+	verifier: string;
+	challenge: string;
+}
+
+export async function generatePKCE(): Promise<PKCEPair> {
+	const verifier = generateRandomString(64);
+	const challenge = await sha256Base64URL(verifier);
+	return { verifier, challenge };
+}
+
+async function sha256Base64URL(input: string): Promise<string> {
+	const encoder = new TextEncoder();
+	const data = encoder.encode(input);
+	try {
+		const hash = await crypto.subtle.digest('SHA-256', data);
+		return base64URLEncode(hash);
+	} catch {
+		return sha256PureJS(input);
+	}
+}
+
+/**
+ * Pure-JS SHA-256 — verified against NIST test vectors.
+ * Based on a minimal, audited implementation.
+ */
+function sha256PureJS(input: string): string {
+	const msg = new TextEncoder().encode(input);
+	const msgBits = msg.length * 8;
+	const buf = new Uint8Array(((msg.length + 9 + 63) >>> 6) << 6);
+	buf.set(msg);
+	buf[msg.length] = 0x80;
+	const view = new DataView(buf.buffer);
+	view.setUint32(buf.length - 4, msgBits);
+
+	const K = new Uint32Array([
+		0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+		0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+		0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+		0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+		0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+		0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+		0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+		0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+	]);
+
+	const H = new Uint32Array([
+		0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+	]);
+	const W = new Uint32Array(64);
+
+	for (let off = 0; off < buf.length; off += 64) {
+		for (let i = 0; i < 16; i++) {
+			W[i] = view.getUint32(off + i * 4);
+		}
+		for (let i = 16; i < 64; i++) {
+			const s0 = ror(W[i - 15], 7) ^ ror(W[i - 15], 18) ^ (W[i - 15] >>> 3);
+			const s1 = ror(W[i - 2], 17) ^ ror(W[i - 2], 19) ^ (W[i - 2] >>> 10);
+			W[i] = (W[i - 16] + s0 + W[i - 7] + s1) | 0;
+		}
+		let [a, b, c, d, e, f, g, h] = H;
+		for (let i = 0; i < 64; i++) {
+			const S1 = ror(e, 6) ^ ror(e, 11) ^ ror(e, 25);
+			const ch = (e & f) ^ (~e & g);
+			const t1 = (h + S1 + ch + K[i] + W[i]) | 0;
+			const S0 = ror(a, 2) ^ ror(a, 13) ^ ror(a, 22);
+			const maj = (a & b) ^ (a & c) ^ (b & c);
+			const t2 = (S0 + maj) | 0;
+			h = g;
+			g = f;
+			f = e;
+			e = (d + t1) | 0;
+			d = c;
+			c = b;
+			b = a;
+			a = (t1 + t2) | 0;
+		}
+		H[0] = (H[0] + a) | 0;
+		H[1] = (H[1] + b) | 0;
+		H[2] = (H[2] + c) | 0;
+		H[3] = (H[3] + d) | 0;
+		H[4] = (H[4] + e) | 0;
+		H[5] = (H[5] + f) | 0;
+		H[6] = (H[6] + g) | 0;
+		H[7] = (H[7] + h) | 0;
+	}
+
+	const digest = new Uint8Array(32);
+	const dv = new DataView(digest.buffer);
+	for (let i = 0; i < 8; i++) dv.setUint32(i * 4, H[i]);
+	return base64URLEncode(digest.buffer);
+}
+
+function ror(x: number, n: number): number {
+	return (x >>> n) | (x << (32 - n));
+}
+
+export { generatePKCE as generateCodeChallenge };

package/src/auth/portal-config.ts

@@ -0,0 +1,68 @@
+/**
+ * PortalAuthConfig — Portal 认证配置注册表
+ *
+ * 集中管理所有 Portal 的角色定义和 Guard 配置，
+ * 消除跨 Portal 的角色常量重复定义。
+ *
+ * 用法:
+ *   import { ADMIN_GUARDS, AdminGuard } from '@autional-cn/shared';
+ *   // 路由中: <AdminGuard><Page /></AdminGuard>
+ *   替代: <RequireAuth allowedRoles={['super_admin', 'admin']}><Page /></RequireAuth>
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+// ============ Role Sets ============
+
+/** 超级管理员（系统级） */
+export const ROLE_SUPER_ADMIN = ['super_admin', 'admin'] as const;
+/** 用户管理 */
+export const ROLE_USER_MGMT = ['super_admin', 'admin', 'user_manager'] as const;
+/** 安全只读（含 admin，用于 admin-console 路由守卫） */
+export const ROLE_SECURITY_READ = ['super_admin', 'admin', 'security_admin'] as const;
+/** security-dashboard 基础准入（不含 admin — admin 不直接登录 security-dashboard） */
+export const ROLE_SECURITY_ENTRY = ['super_admin', 'security_admin', 'auditor'] as const;
+/** 审计安全（含 auditor 只读，不含 admin — admin 审计经 admin-console + sod_mode 控制） */
+export const ROLE_AUDIT_READ = ['super_admin', 'security_admin', 'auditor'] as const;
+/** 安全操作（含配置权限，不含 auditor） */
+export const ROLE_SECURITY_FULL = ['super_admin', 'security_admin'] as const;
+
+// ============ Portal Guards ============
+
+/**
+ * Portal Guard 配置。
+ * 如需新增 Guard，在此添加 role 集即可。
+ */
+export const ADMIN_GUARDS = {
+	admin: { roles: ROLE_SUPER_ADMIN },
+	userMgmt: { roles: ROLE_USER_MGMT },
+	securityRead: { roles: ROLE_SECURITY_READ },
+	auditRead: { roles: ROLE_AUDIT_READ }, // admin-console 审计证据路由
+	securityAdmin: { roles: ROLE_SECURITY_FULL }, // admin-console 安全配置管理
+} as const;
+
+export const PLATFORM_GUARDS = {
+	superAdmin: { roles: ROLE_SUPER_ADMIN },
+} as const;
+
+export const SECURITY_GUARDS = {
+	security: { roles: ROLE_SECURITY_ENTRY }, // 基础准入（不含 admin）
+	auditRead: { roles: ROLE_AUDIT_READ }, // 审计证据页（auditor 只读）
+	securityAdmin: { roles: ROLE_SECURITY_FULL }, // 安全配置/平台级操作
+	auditor: { roles: ['auditor'] }, // 仅 auditor
+} as const;
+
+// ============ Portal Config ============
+
+/** 所有 Portal 的认证配置映射 */
+export const PORTAL_AUTH_CONFIG = {
+	'admin-console': { guards: ADMIN_GUARDS },
+	'platform-console': { guards: PLATFORM_GUARDS },
+	'security-dashboard': { guards: SECURITY_GUARDS },
+	'end-user-portal': { guards: null }, // 仅需 token，无角色限制
+	// developer-portal removed — merged into admin per ADR-006
+	'authenticator-app': { guards: null }, // 仅需 token，无角色限制
+	'auth-pages': { guards: null }, // 混合（大部分公开）
+} as const;
+
+export type PortalName = keyof typeof PORTAL_AUTH_CONFIG;

package/src/auth/roles.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 域会话，再按「无会话」落 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`;
+}
+
+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;
+}