@autional-cn/shared 0.1.0-rc

package/src/components/OAuthCallbackPage.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useState } from 'react';
+import { handleOAuthCallback } from '../auth/oauth-login';
+
+// 这个组件在 9 个站点各存一份，三处用户可见文案此前**三种写法并存**：
+//   admin「正在登录…」 / platform「登录中…」 / 其余 7 站是英文「Signing in...」
+// 也就是说 7 个中文门户在 OAuth 回调时会显示英文文案。
+//
+// 采用与权威 shared/ui/ErrorBoundary.tsx 完全相同的约定：用 <html lang> 判定文案语言，
+// 默认中文——各 portal 的 I18nProvider 都会在 languageChanged 时同步它。
+// （ErrorBoundary 当初就是因为各 portal 的 t() 约定不一致，才改用这个零依赖信号。）
+const TEXT = {
+	zh: { signingIn: '正在登录…', failed: '登录失败', retry: '重试' },
+	en: { signingIn: 'Signing in...', failed: 'Login failed', retry: 'Try again' },
+};
+
+function text(): typeof TEXT.zh {
+	if (typeof document === 'undefined') return TEXT.zh;
+	const lang = (document.documentElement.getAttribute('lang') || '').toLowerCase();
+	return lang.startsWith('zh') ? TEXT.zh : TEXT.en;
+}
+
+export function OAuthCallbackPage() {
+	const [error, setError] = useState('');
+	const [loading, setLoading] = useState(true);
+	const t = text();
+
+	useEffect(() => {
+		handleOAuthCallback().catch((e) => {
+			setError(e.message);
+			setLoading(false);
+		});
+	}, []);
+
+	if (loading) {
+		return (
+			<div className="flex h-screen items-center justify-center bg-neutral-50">
+				<div className="flex flex-col items-center gap-3">
+					<div className="h-8 w-8 animate-spin rounded-full border-4 border-blue-600 border-t-transparent" />
+					<p className="text-sm text-neutral-500">{t.signingIn}</p>
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex h-screen items-center justify-center bg-neutral-50">
+			<div className="max-w-sm rounded-lg border border-red-200 bg-red-50 p-6 text-center">
+				<p className="text-sm font-medium text-red-700">{t.failed}</p>
+				<p className="mt-1 text-xs text-red-600">{error}</p>
+				<a href="/" className="mt-4 inline-block text-sm text-blue-600 underline">
+					{t.retry}
+				</a>
+			</div>
+		</div>
+	);
+}

package/src/components/PortalGuard.tsx

@@ -0,0 +1,105 @@
+/**
+ * PortalGuard — Portal 级 Guard 组件
+ *
+ * 基于 portal-config.ts 中的角色定义，派生出命名 Guard 组件。
+ * 替代在每个路由中重复传入 allowedRoles 的模式。
+ *
+ * 用法:
+ *   import { AdminGuard, PlatformGuard, SecurityGuard } from '@autional-cn/shared';
+ *
+ *   // admin-console 路由:
+ *   <AdminGuard><DashboardPage /></AdminGuard>
+ *   <AdminGuard allowedRoles={['user_mgmt']}><UsersPage /></AdminGuard>  // 覆盖默认角色
+ *
+ * @see portal-config.ts
+ */
+
+'use client';
+
+import React from 'react';
+import { RequireAuth } from './RequireAuth';
+import { ADMIN_GUARDS, PLATFORM_GUARDS, SECURITY_GUARDS } from '../auth/portal-config';
+
+interface PortalGuardProps {
+	children: React.ReactNode;
+	allowedRoles?: readonly string[];
+	fallback?: React.ReactNode;
+	loadingFallback?: React.ReactNode;
+	/** 确定性未知 slug（by-slug HTTP 404）时渲染的 404 页（透传 RequireAuth） */
+	notFound?: React.ReactNode;
+}
+
+/**
+ * Admin Console Guard — 默认 roles: ['super_admin', 'admin']
+ */
+export function AdminGuard({ children, allowedRoles, ...rest }: PortalGuardProps) {
+	return (
+		<RequireAuth allowedRoles={allowedRoles || ADMIN_GUARDS.admin.roles} {...rest}>
+			{children}
+		</RequireAuth>
+	);
+}
+
+/**
+ * 用户管理 Guard — roles: ['super_admin', 'admin', 'user_manager']
+ */
+export function UserMgmtGuard({ children, allowedRoles, ...rest }: PortalGuardProps) {
+	return (
+		<RequireAuth allowedRoles={allowedRoles || ADMIN_GUARDS.userMgmt.roles} {...rest}>
+			{children}
+		</RequireAuth>
+	);
+}
+
+/**
+ * 安全只读 Guard — roles: ['super_admin', 'admin', 'security_admin']
+ */
+export function SecurityGuard({ children, allowedRoles, ...rest }: PortalGuardProps) {
+	return (
+		<RequireAuth allowedRoles={allowedRoles || SECURITY_GUARDS.security.roles} {...rest}>
+			{children}
+		</RequireAuth>
+	);
+}
+
+/**
+ * Platform Console Guard — roles: ['super_admin', 'admin']
+ */
+export function PlatformGuard({ children, allowedRoles, ...rest }: PortalGuardProps) {
+	return (
+		<RequireAuth allowedRoles={allowedRoles || PLATFORM_GUARDS.superAdmin.roles} {...rest}>
+			{children}
+		</RequireAuth>
+	);
+}
+
+/**
+ * Security Admin Guard — roles: ['super_admin', 'security_admin']
+ * 用于 security-dashboard 中仅 security_admin 可访问的平台级页面
+ */
+export function SecurityAdminGuard({ children, allowedRoles, ...rest }: PortalGuardProps) {
+	return (
+		<RequireAuth allowedRoles={allowedRoles || SECURITY_GUARDS.securityAdmin.roles} {...rest}>
+			{children}
+		</RequireAuth>
+	);
+}
+
+/**
+ * Auditor Guard — roles: ['auditor']
+ * 仅 auditor 可访问的纯审计页面（只读）
+ */
+export function AuditorGuard({ children, allowedRoles, ...rest }: PortalGuardProps) {
+	return (
+		<RequireAuth allowedRoles={allowedRoles || SECURITY_GUARDS.auditor.roles} {...rest}>
+			{children}
+		</RequireAuth>
+	);
+}
+
+/**
+ * Token-only Guard — 仅需登录，无角色限制
+ */
+export function AuthGuard({ children, ...rest }: PortalGuardProps) {
+	return <RequireAuth {...rest}>{children}</RequireAuth>;
+}

package/src/components/RequireAuth.tsx

@@ -0,0 +1,142 @@
+import { useEffect } from 'react';
+import { AuthService, setBootstrapLock } from '../auth/service';
+import { buildLoginUrl } from '../auth/roles';
+import { initiateOAuthLogin } from '../auth/oauth-login';
+import {
+	useTenantRoute,
+	resolveEffectiveClientId,
+	isSameDomainOAuth,
+} from '../auth/tenant-route-middleware';
+import { useAuthMachine } from '../auth/auth-machine';
+
+interface RequireAuthProps {
+	children: React.ReactNode;
+	allowedRoles?: readonly string[];
+	fallback?: React.ReactNode;
+	loadingFallback?: React.ReactNode;
+	/** 确定性未知 slug（by-slug HTTP 404）时渲染的 404 页；缺省用内置极简 404 兜底 */
+	notFound?: React.ReactNode;
+}
+
+/**
+ * 内置极简 404（零依赖，供未注入 notFound 的站点兜底 —— shared 不能 import 各
+ * app 的 not-found/page）。样式用 CSS 变量 var(--color-*)，.dark 下自动反转。
+ */
+function DefaultTenantNotFound() {
+	const zh =
+		typeof document !== 'undefined' &&
+		(document.documentElement.lang || '').toLowerCase().startsWith('zh');
+	return (
+		<div
+			role="alert"
+			style={{
+				display: 'flex',
+				flexDirection: 'column',
+				alignItems: 'center',
+				justifyContent: 'center',
+				minHeight: '40vh',
+				gap: '0.5rem',
+				width: '100%',
+			}}
+		>
+			<h1 style={{ fontSize: '3rem', fontWeight: 700, color: 'var(--color-text-muted)' }}>404</h1>
+			<p style={{ color: 'var(--color-text-secondary)' }}>
+				{zh ? '页面不存在或已被移除' : 'Page not found'}
+			</p>
+		</div>
+	);
+}
+
+export function RequireAuth({
+	children,
+	allowedRoles,
+	fallback,
+	loadingFallback,
+	notFound,
+}: RequireAuthProps) {
+	const machine = useAuthMachine();
+	const tenantRoute = useTenantRoute();
+
+	// F-W6 闸门：URL slug 确定性不存在（by-slug HTTP 404）且本站未配 env 固定
+	// client（admin-console 等单租户旁路不适用）→ 本地 404，不发弹跳。
+	// 不然：门户 → buildLoginUrl → auth 侧有会话走「回跳 redirect」→ 回到本页
+	// → 再弹跳，构成无限整页往返（verification-W5-patch §6）。
+	// 网络错误/5xx 不置 unknownSlug（fail-open 仍走登录漏斗）；仅 unauthenticated 终态生效。
+	const envClientId =
+		typeof window !== 'undefined' ? (window as any).__APP_CONFIG__?.VITE_OAUTH_CLIENT_ID || '' : '';
+	const unknownSlugGate =
+		machine.status === 'unauthenticated' && tenantRoute.unknownSlug && !envClientId;
+
+	// 挂载时抑制 401 抢跑：若当前域配置了 OAuth client 且本页无有效 token
+	// （跨域 admin 场景），任何无 token API 请求的 401 都会触发 onUnauthorized →
+	// buildLoginUrl 302 到 auth 登录页，抢跑下方 OAuth PKCE 决策，形成时序竞争。
+	// 上锁后未登录跳转的唯一出口是下方 effect 的 OAuth/buildLoginUrl 决策。
+	useEffect(() => {
+		if (typeof window === 'undefined') return;
+		const cfg = (window as any).__APP_CONFIG__;
+		const envClientId = cfg?.VITE_OAUTH_CLIENT_ID || '';
+		if (!envClientId) return;
+		const rawToken = AuthService.getAccessToken();
+		const hasToken = !!rawToken && rawToken !== 'undefined' && rawToken !== 'null';
+		if (!hasToken) setBootstrapLock(true);
+	}, []);
+
+	// Redirect logic: only runs when machine says unauthenticated
+	useEffect(() => {
+		if (machine.status !== 'unauthenticated') return;
+		if (typeof window === 'undefined') return;
+		if (tenantRoute.loading) return; // wait for OAuth config
+
+		const cfg = (window as any).__APP_CONFIG__;
+		const envClientId = cfg?.VITE_OAUTH_CLIENT_ID || '';
+
+		// F-W6 闸门：确定性未知 slug → 不发起任何弹跳，由渲染分支给本地 404
+		if (tenantRoute.unknownSlug && !envClientId) return;
+
+		const effectiveClientId = resolveEffectiveClientId(tenantRoute, envClientId);
+
+		if (effectiveClientId && (isSameDomainOAuth(tenantRoute) || envClientId)) {
+			initiateOAuthLogin(effectiveClientId);
+			return;
+		}
+
+		// Cross-domain or no client: redirect to auth-pages login
+		// from_requireauth=1 与 service.ts 的 onUnauthorized 同口径：auth 侧据此先做会话复检
+		// （有会话直接回跳，避免「已登录还被要求再登一次」）
+		setTimeout(() => {
+			window.location.replace(buildLoginUrl(window.location.href, true));
+		}, 0);
+	}, [machine.status, tenantRoute]);
+
+	if (machine.status === 'checking' || machine.status === 'bootstrap') {
+		return loadingFallback ? <>{loadingFallback}</> : null;
+	}
+
+	if (unknownSlugGate) {
+		return notFound ? <>{notFound}</> : <DefaultTenantNotFound />;
+	}
+
+	if (machine.status === 'unauthenticated' || machine.status === 'redirecting') {
+		return null;
+	}
+
+	// status === 'ready' or 'authenticated'
+	if (allowedRoles && allowedRoles.length > 0) {
+		const role = AuthService.getCurrentRole();
+		if (role && !allowedRoles.includes(role)) {
+			const permissions = AuthService.getPermissions();
+			if (!permissions || permissions.length === 0) {
+				return loadingFallback ? <>{loadingFallback}</> : <>{children}</>;
+			}
+			const hasAdminPermission = permissions.some(
+				(p: string) => p === '*' || allowedRoles.some((r) => p.includes(r)),
+			);
+			if (!hasAdminPermission) {
+				if (fallback) return <>{fallback}</>;
+				return null;
+			}
+		}
+	}
+
+	return <>{children}</>;
+}

package/src/components/TenantIndexGuard.tsx

@@ -0,0 +1,131 @@
+/**
+ * TenantIndexGuard — 租户 slug 白名单守卫（TASK-425，AC-010）
+ *
+ * 从 end-user-portal App.tsx L65-111 抽取泛化，供 4 个租户门户复用
+ * （不复制 4 份，违反 DRY）。
+ *
+ * - usePublicTenantSlugs: 调公开 tenants API（无认证端点），staleTime 5m 缓存，
+ *   retry 1，任何失败返回空数组（放行语义由 TenantIndexGuard 处理）。
+ * - TenantIndexGuard: index 路由守卫（P0-2），防止未知路径被贪婪渲染为
+ *   Dashboard/首页。404 页由各 portal 通过 notFound prop 注入
+ *   （shared 组件不能 import 具体 app 的 not-found/page）。
+ *
+ * ⚠️ 依赖约束: shared 包 dependencies 无 @autional-cn/ui，禁止 import @autional-cn/ui
+ * （会引入未声明依赖/循环依赖）。loading 默认值用内联 div 骨架，
+ * 样式用 CSS 变量 var(--color-*)，在 .dark 下自动反转（AGENTS.md 设计规范）。
+ * ⚠️ useTenantSlugFromUrl 内部相对导入（'../auth/slug-from-url'），
+ * 不要从包名 '@autional-cn/shared' 导入自身。
+ */
+
+'use client';
+
+import { type ReactNode } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useTenantSlugFromUrl } from '../auth/slug-from-url';
+
+/** 公开租户信息（public tenants API 返回项） */
+export interface PublicTenantInfo {
+	name?: string;
+	slug?: string;
+	id?: string;
+}
+
+/**
+ * 公开租户列表（无认证端点，用于校验 URL slug 有效性）。
+ * 从 end-user-portal App.tsx 原样抽取。
+ * - staleTime 5m（plan §5 资源列：public tenants API 有缓存）
+ * - retry 1；失败返回 []（白名单空数组放行，避免 API 挂掉时全站 404）
+ *
+ * ⚠️ 响应契约：tenant-service ListPublicTenants 返回 dto_base.ListResponse
+ * （`{code, message, items, total, pagination, timestamp}`，items 才是数组）。
+ * 解析顺序：items → data（旧兼容）→ 原始对象，均非数组则返回 []。
+ */
+export function usePublicTenantSlugs() {
+	return useQuery<Array<PublicTenantInfo>>({
+		queryKey: ['public-tenants'],
+		queryFn: async () => {
+			try {
+				const res = await fetch('/bff/tenant/api/v1/tenant/public/tenants');
+				if (!res.ok) return [];
+				const json = await res.json();
+				const list = json?.items ?? json?.data ?? json ?? [];
+				return Array.isArray(list) ? list : [];
+			} catch {
+				return [];
+			}
+		},
+		staleTime: 5 * 60 * 1000,
+		retry: 1,
+	});
+}
+
+export interface TenantIndexGuardProps {
+	/** 白名单校验通过后渲染的 index 内容（各 portal 的 Dashboard/首页） */
+	children?: ReactNode;
+	/** 白名单校验失败渲染的 404 页（各 portal 注入自己的 NotFoundPage） */
+	notFound?: ReactNode;
+	/** loading 占位（缺省渲染内联简单骨架，不依赖 @autional-cn/ui） */
+	loading?: ReactNode;
+}
+
+/**
+ * 默认 loading 占位 — 内联骨架（零依赖）。
+ * 不使用 @autional-cn/ui（shared 包无该依赖，避免未声明依赖/循环依赖）；
+ * 样式用 CSS 变量 var(--color-*)，在 .dark 下自动反转。
+ */
+function DefaultLoadingSkeleton() {
+	return (
+		<>
+			<style>{`@keyframes authms-guard-spin { to { transform: rotate(360deg); } }`}</style>
+			<div
+				role="status"
+				aria-live="polite"
+				aria-label={typeof document !== 'undefined' && (document.documentElement.lang || '').toLowerCase().startsWith('zh') ? '加载中' : 'Loading'}
+				style={{
+					display: 'flex',
+					alignItems: 'center',
+					justifyContent: 'center',
+					minHeight: '40vh',
+					width: '100%',
+				}}
+			>
+				<div
+					style={{
+						width: '2rem',
+						height: '2rem',
+						borderRadius: '9999px',
+						border: '3px solid var(--color-border-subtle)',
+						borderTopColor: 'var(--color-brand)',
+						animation: 'authms-guard-spin 0.8s linear infinite',
+					}}
+				/>
+			</div>
+		</>
+	);
+}
+
+/**
+ * index 路由守卫（P0-2）：防止未知路径被贪婪渲染为 Dashboard/首页。
+ * 逻辑与 end-user-portal 现状一致（L94-111）：
+ * - URL 多段（如 /acme-corp/xyz）：basename 已剥离 slug，内部单段必为未知路由段 → notFound
+ * - URL 单段（如 /not-found）：校验 slug 是否在公开租户列表 → 无效 → notFound
+ * - URL 单段且 slug 有效（如 /acme-corp）→ children
+ * - 白名单为空数组时放行（public tenants API 挂掉时退化为不拦截，与 end-user 现状一致）
+ */
+export function TenantIndexGuard({ children, notFound, loading }: TenantIndexGuardProps) {
+	const { data: tenants, isLoading } = usePublicTenantSlugs();
+	const slug = useTenantSlugFromUrl();
+
+	if (typeof window !== 'undefined') {
+		const fullSegs = window.location.pathname.split('/').filter(Boolean);
+		if (fullSegs.length > 1) return <>{notFound}</>;
+	}
+
+	if (isLoading && !tenants) return <>{loading ?? <DefaultLoadingSkeleton />}</>;
+
+	if (slug && tenants && tenants.length > 0 && !tenants.some((t) => (t.name || t.slug) === slug)) {
+		return <>{notFound}</>;
+	}
+
+	return <>{children}</>;
+}

package/src/components/__tests__/RequireAuth.test.tsx

@@ -0,0 +1,244 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor, cleanup } from '@testing-library/react';
+
+// ============================================================
+// L6（D9 / ADR-04）：RequireAuth 的未登录出口
+//  - 能解析出 OAuth client → 起 PKCE（initiateOAuthLogin）
+//  - 不能解析 → 跳 auth 登录页，且**必须**带 from_requireauth=1
+//    （与 service.ts onUnauthorized 同口径：auth 侧先做会话复检，避免重登一次）
+// ============================================================
+
+const { mockState } = vi.hoisted(() => ({
+	mockState: {
+		machineStatus: 'unauthenticated' as string,
+		tenantRoute: {
+			slug: null as string | null,
+			tenantId: null as string | null,
+			oauthClientId: null as string | null,
+			loading: false,
+			notFound: true,
+			unknownSlug: false,
+		},
+		token: null as string | null,
+		replace: vi.fn(),
+		initiate: vi.fn(),
+		setBootstrapLock: vi.fn(),
+	},
+}));
+
+vi.mock('../../auth/auth-machine', () => ({
+	useAuthMachine: () => ({ status: mockState.machineStatus }),
+}));
+
+vi.mock('../../auth/tenant-route-middleware', async (importOriginal) => ({
+	...(await importOriginal<typeof import('../../auth/tenant-route-middleware')>()),
+	useTenantRoute: () => mockState.tenantRoute,
+}));
+
+vi.mock('../../auth/oauth-login', () => ({
+	initiateOAuthLogin: (...args: any[]) => mockState.initiate(...args),
+}));
+
+vi.mock('../../auth/service', () => ({
+	AuthService: {
+		getAccessToken: () => mockState.token,
+		getCurrentRole: () => null,
+		getPermissions: () => [],
+	},
+	setBootstrapLock: (...args: any[]) => mockState.setBootstrapLock(...args),
+}));
+
+import { RequireAuth } from '../RequireAuth';
+import { getPortalUrl } from '../../config';
+
+const originalWindowLocation = window.location;
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mockState.machineStatus = 'unauthenticated';
+	mockState.tenantRoute = {
+		slug: null,
+		tenantId: null,
+		oauthClientId: null,
+		loading: false,
+		notFound: true,
+		unknownSlug: false,
+	};
+	mockState.token = null;
+	delete (window as any).__APP_CONFIG__;
+
+	delete (window as any).location;
+	(window as any).location = Object.defineProperties(
+		{},
+		{
+			...Object.getOwnPropertyDescriptors(originalWindowLocation),
+			replace: { get: () => mockState.replace },
+		},
+	);
+});
+
+afterEach(() => {
+	if (window.location !== originalWindowLocation) {
+		Object.defineProperty(window, 'location', { value: originalWindowLocation, writable: true });
+	}
+	// vitest globals 未开启 ⇒ RTL 不会自动 cleanup，手动清理防跨用例 DOM 污染
+	cleanup();
+});
+
+describe('RequireAuth 未登录出口', () => {
+	it('无可用 client_id → 跳 auth 登录页并带 from_requireauth=1', async () => {
+		render(
+			<RequireAuth>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => {
+			expect(mockState.replace).toHaveBeenCalled();
+		});
+		const url = String(mockState.replace.mock.calls[0][0]);
+		expect(url).toContain('from_requireauth=1');
+		expect(url).toContain('redirect=');
+		expect(url.startsWith(getPortalUrl('auth'))).toBe(true);
+		expect(mockState.initiate).not.toHaveBeenCalled();
+	});
+
+	it('slug 解析出 client_id → 发起 PKCE，不做登录页跳转', async () => {
+		mockState.tenantRoute = {
+			slug: 'demo',
+			tenantId: 't1',
+			oauthClientId: 'cid-from-slug',
+			loading: false,
+			notFound: false,
+			unknownSlug: false,
+		};
+
+		render(
+			<RequireAuth>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => {
+			expect(mockState.initiate).toHaveBeenCalledWith('cid-from-slug');
+		});
+		expect(mockState.replace).not.toHaveBeenCalled();
+	});
+
+	it('env 兜底 client_id（__APP_CONFIG__）→ 同样发起 PKCE', async () => {
+		(window as any).__APP_CONFIG__ = { VITE_OAUTH_CLIENT_ID: 'cid-from-env' };
+
+		render(
+			<RequireAuth>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => {
+			expect(mockState.initiate).toHaveBeenCalledWith('cid-from-env');
+		});
+		expect(mockState.replace).not.toHaveBeenCalled();
+	});
+
+	it('无 token + env client_id → 上 bootstrap 锁（抑制 401 抢跑）', async () => {
+		(window as any).__APP_CONFIG__ = { VITE_OAUTH_CLIENT_ID: 'cid-from-env' };
+
+		render(
+			<RequireAuth>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => {
+			expect(mockState.setBootstrapLock).toHaveBeenCalledWith(true);
+		});
+	});
+});
+
+// ============================================================
+// F-W6 闸门（verification-W5-patch §6）：未知 slug 死链 × auth 域有会话
+// 曾构成无限整页往返（门户 → buildLoginUrl → auth 回跳 redirect → 门户 → …）。
+// 修法：by-slug 确定性 404（unknownSlug）且本站未配 env client → 本地 404，不弹跳。
+// 约束：网络错误/5xx 不置 unknownSlug（fail-open 仍走漏斗）；env client 站点不触发。
+// ============================================================
+describe('RequireAuth F-W6 确定性 404 闸门', () => {
+	it('unknownSlug + 无 env client → 不发弹跳、渲染注入的 404', async () => {
+		mockState.tenantRoute = {
+			slug: null,
+			tenantId: null,
+			oauthClientId: null,
+			loading: false,
+			notFound: true,
+			unknownSlug: true,
+		};
+
+		render(
+			<RequireAuth notFound={<div data-testid="tenant-404">no such tenant</div>}>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => expect(screen.getByTestId('tenant-404')).toBeInTheDocument());
+		expect(mockState.replace).not.toHaveBeenCalled();
+		expect(mockState.initiate).not.toHaveBeenCalled();
+		expect(screen.queryByText('protected')).toBeNull();
+	});
+
+	it('unknownSlug + 无 notFound 注入 → 渲染内置极简 404（不空白）', async () => {
+		mockState.tenantRoute = {
+			slug: null,
+			tenantId: null,
+			oauthClientId: null,
+			loading: false,
+			notFound: true,
+			unknownSlug: true,
+		};
+
+		render(
+			<RequireAuth>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => expect(screen.getByText('404')).toBeInTheDocument());
+		expect(mockState.replace).not.toHaveBeenCalled();
+	});
+
+	it('unknownSlug + env client（admin-console 旁路）→ 闸门不生效，仍走 PKCE', async () => {
+		(window as any).__APP_CONFIG__ = { VITE_OAUTH_CLIENT_ID: 'cid-from-env' };
+		mockState.tenantRoute = {
+			slug: null,
+			tenantId: null,
+			oauthClientId: null,
+			loading: false,
+			notFound: true,
+			unknownSlug: true,
+		};
+
+		render(
+			<RequireAuth notFound={<div data-testid="tenant-404">no such tenant</div>}>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => expect(mockState.initiate).toHaveBeenCalledWith('cid-from-env'));
+		expect(screen.queryByTestId('tenant-404')).toBeNull();
+		expect(mockState.replace).not.toHaveBeenCalled();
+	});
+
+	it('非 unknownSlug（网络错误 fail-open）→ 维持原漏斗（回归锁）', async () => {
+		// 默认 tenantRoute: notFound=true, unknownSlug=false —— 即 by-slug 网络错误场景
+		render(
+			<RequireAuth notFound={<div data-testid="tenant-404">no such tenant</div>}>
+				<div>protected</div>
+			</RequireAuth>,
+		);
+
+		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
+		const url = String(mockState.replace.mock.calls[0][0]);
+		expect(url).toContain('from_requireauth=1');
+		expect(screen.queryByTestId('tenant-404')).toBeNull();
+	});
+});