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

package/src/components/PortalGuard.tsx

@@ -0,0 +1,105 @@
+/**
+ * PortalGuard — Portal 级 Guard 组件
+ *
+ * 基于 portal-config.ts 中的角色定义，派生出命名 Guard 组件。
+ * 替代在每个路由中重复传入 allowedRoles 的模式。
+ *
+ * 用法:
+ *   import { AdminGuard, PlatformGuard, SecurityGuard } from '@autional/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,220 @@
+import { useCallback, useEffect, useState } from 'react';
+import { AuthService, setBootstrapLock } from '../auth/service';
+import { buildLoginUrl } from '../auth/roles';
+import { traceRedirect } from '../auth/auth-trace';
+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>
+	);
+}
+
+/**
+ * AUTH-03：未认证态下用户选择「停留」（取消被动登录跳转）后的可恢复 UI——
+ * 原实现停留后仍渲染 null（正文空白无任何出口），现替换为提示 + 「前往登录」出口。
+ * 零依赖、CSS 变量主题（同 DefaultTenantNotFound）；按钮用固定 #2563eb（白字
+ * 5.17:1 过 AA），不引品牌色（品牌色可能对比度不足，见 AUTH-05）。
+ */
+function DefaultSignInRequired({ onSignIn }: { onSignIn: () => void }) {
+	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.75rem',
+				width: '100%',
+			}}
+		>
+			<h1 style={{ fontSize: '1.25rem', fontWeight: 600, color: 'var(--color-text-primary)' }}>
+				{zh ? '需要登录' : 'Sign-in required'}
+			</h1>
+			<p style={{ color: 'var(--color-text-secondary)', fontSize: '0.875rem', margin: 0 }}>
+				{zh ? '此页面需登录后访问' : 'This page requires sign-in'}
+			</p>
+			<button
+				type="button"
+				onClick={onSignIn}
+				style={{
+					border: 0,
+					borderRadius: 6,
+					padding: '8px 18px',
+					fontSize: '0.875rem',
+					cursor: 'pointer',
+					background: '#2563eb',
+					color: '#fff',
+				}}
+			>
+				{zh ? '前往登录' : 'Go to sign-in'}
+			</button>
+		</div>
+	);
+}
+
+export function RequireAuth({
+	children,
+	allowedRoles,
+	fallback,
+	loadingFallback,
+	notFound,
+}: RequireAuthProps) {
+	const machine = useAuthMachine();
+	const tenantRoute = useTenantRoute();
+	// 「停留」已选（被动登录跳转被用户取消）——渲染恢复态而非空白（AUTH-03）
+	const [stayed, setStayed] = useState(false);
+
+	// 登录跳转的单一出口：effect（进入未认证态）与恢复态「前往登录」按钮共用。
+	// force=true 跳过 OAuth 10s 防重入窗口（用户显式重试）。
+	const triggerLogin = useCallback(
+		(force = false) => {
+			if (typeof window === 'undefined') return;
+			const cfg = (window as any).__APP_CONFIG__;
+			const envClientId = cfg?.VITE_OAUTH_CLIENT_ID || '';
+			const effectiveClientId = resolveEffectiveClientId(tenantRoute, envClientId);
+
+			if (effectiveClientId && (isSameDomainOAuth(tenantRoute) || envClientId)) {
+				void initiateOAuthLogin(effectiveClientId, undefined, {
+					onStay: () => setStayed(true),
+					force,
+				});
+				return;
+			}
+
+			// Cross-domain or no client: redirect to auth-pages login
+			// from_requireauth=1 与 service.ts 的 onUnauthorized 同口径：auth 侧据此先做会话复检
+			// （有会话直接回跳，避免「已登录还被要求再登一次」）
+			// interstitial：未认证深链被动弹登录 → authTrace 提示（可停留）；重入抑制在其内。
+			setTimeout(() => {
+				traceRedirect(buildLoginUrl(window.location.href, true), {
+					reason: 'unauthenticated',
+					kind: 'interstitial',
+					onStay: () => setStayed(true),
+				});
+			}, 0);
+		},
+		[tenantRoute],
+	);
+
+	// 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;
+
+		triggerLogin(false);
+	}, [machine.status, tenantRoute, triggerLogin]);
+
+	if (machine.status === 'checking' || machine.status === 'bootstrap') {
+		return loadingFallback ? <>{loadingFallback}</> : null;
+	}
+
+	if (unknownSlugGate) {
+		return notFound ? <>{notFound}</> : <DefaultTenantNotFound />;
+	}
+
+	if (machine.status === 'unauthenticated' || machine.status === 'redirecting') {
+		// AUTH-03：「停留」后原实现恒 null（空白死路）→ 给恢复态与再发起出口
+		if (stayed) return <DefaultSignInRequired onSignIn={() => triggerLogin(true)} />;
+		return null;
+	}
+
+	// status === 'ready' or 'authenticated'
+	// 守卫三原则（ADR-AB1-01 / A-445 修复口径）：
+	//   ① 精确角色相等：allowedRoles.includes(role) 直通——禁止任何子串/前缀判定
+	//      （历史缺陷：权限码对角色白名单做子串包含判定，security_admin 借 14 条
+	//      `*:admin` 权限码穿透一切含 'admin' 的白名单路由 = A-445）；
+	//   ② '*' 单豁免：持全量通配 '*' 的非白名单角色放行（唯一豁免通道）；
+	//   ③ 空权限 fail-closed：非白名单角色且无 '*' ⇒ 拒绝（fallback / null），
+	//      空权限数组不再构成放行旁路。
+	// role === null 保持穿透为锁定现语义（叠加语义）：更严闸门（AuthGuard /
+	// PortalGuard）在更外层裁决未知角色，本组件不把 null 判为拒绝
+	// （对抗用例④为防误改回归锁，改前先改裁定）。
+	if (allowedRoles && allowedRoles.length > 0) {
+		const role = AuthService.getCurrentRole();
+		if (role && !allowedRoles.includes(role)) {
+			const permissions = AuthService.getPermissions();
+			const hasWildcard = !!permissions && permissions.some((p: string) => p === '*');
+			if (!hasWildcard) {
+				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/ui，禁止 import @autional/ui
+ * （会引入未声明依赖/循环依赖）。loading 默认值用内联 div 骨架，
+ * 样式用 CSS 变量 var(--color-*)，在 .dark 下自动反转（AGENTS.md 设计规范）。
+ * ⚠️ useTenantSlugFromUrl 内部相对导入（'../auth/slug-from-url'），
+ * 不要从包名 '@autional/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/ui） */
+	loading?: ReactNode;
+}
+
+/**
+ * 默认 loading 占位 — 内联骨架（零依赖）。
+ * 不使用 @autional/ui（shared 包无该依赖，避免未声明依赖/循环依赖）；
+ * 样式用 CSS 变量 var(--color-*)，在 .dark 下自动反转。
+ */
+function DefaultLoadingSkeleton() {
+	return (
+		<>
+			<style>{`@keyframes autional-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: 'autional-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/TenantRootRedirect.tsx

@@ -0,0 +1,49 @@
+import { useEffect, useMemo } from 'react';
+import { useCurrentTenantId } from '../hooks/useAuth';
+import { getPortalUrl } from '../config';
+import { traceRedirect } from '../auth/auth-trace';
+import { usePublicTenantSlugs } from './TenantIndexGuard';
+
+/**
+ * 裸根 `/` 漏斗：门户入口必须带租户段（/:tenantSlug）。
+ * - 已有会话且能解析出 slug → 整页跳 /<slug>/（不经过 brand）
+ * - 否则整页跳 brand 选品牌（brand → auth 登录 → 回本门户 /<slug>/）
+ *
+ * slug 解析**唯一权威 = 公开租户名单**（id → name，name 即 slug）。
+ * 不得用会话 store 的 tenants[].name —— 那是 identity `/auth/me/tenants` 的
+ * **展示名**（如 "Demo Tenant"），拼进 URL 会落 /Demo%20Tenant/ → 404（回归修复；
+ * 与 auth 站 8859e4d 的 pickSessionSlug 同口径）。
+ *
+ * 注：本包刻意不依赖 react-router（它只属于各 app），故不走 <Navigate>。
+ */
+export function TenantRootRedirect() {
+	const currentTenantId = useCurrentTenantId();
+	const { data: knownTenants, isSuccess: tenantsLoaded } = usePublicTenantSlugs();
+
+	const slug = useMemo(() => {
+		if (!currentTenantId || !tenantsLoaded) return undefined;
+		const match = (knownTenants ?? []).find((t) => t.id === currentTenantId);
+		return match?.name || match?.slug || undefined;
+	}, [currentTenantId, knownTenants, tenantsLoaded]);
+
+	useEffect(() => {
+		if (typeof window === 'undefined') return;
+		if (slug) {
+			const base = window.location.pathname.replace(/\/+$/, '');
+			traceRedirect(`${base}/${slug}/`, { reason: 'funnel-slug' });
+			return;
+		}
+		// 有会话但公开名单尚未返回：等待（名单是 slug 唯一权威，不得抢跑漏斗 brand）。
+		// 无会话（currentTenantId 空）不受此闸，立即漏斗。
+		if (currentTenantId && !tenantsLoaded) return;
+		const brand = getPortalUrl('brand');
+		// 门户不可派生（如经 IP 主机访问）：保持当前页，不导航（与 EntryRouter 同约定）
+		if (!brand) return;
+		const target = `${brand}/?redirect=${encodeURIComponent(
+			window.location.origin + window.location.pathname,
+		)}`;
+		traceRedirect(target, { reason: 'funnel-brand' });
+	}, [slug, currentTenantId, tenantsLoaded]);
+
+	return null;
+}

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

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+// ============================================================
+// TASK-AB1-29 · RequireAuth 对抗测试 6 类（RC-4 / A-445）
+// 修复前基线（2026-10-04）：本文件对未修复代码运行，组①③必须红（fail-open 实证）；
+// 修复（TASK-AB1-01）后 6 类全绿，即 A-445 子串穿透永久钉死。
+// 14 条 `*:admin` 弹药清单以 findings §1.1 实扫枚举为准（防清单漂移）。
+// ============================================================
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+
+const { mockState } = vi.hoisted(() => ({
+	mockState: {
+		machineStatus: 'ready' as string,
+		role: 'admin' as string | null,
+		permissions: [] as string[],
+	},
+}));
+
+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: () => ({
+		slug: null,
+		tenantId: null,
+		oauthClientId: null,
+		loading: false,
+		notFound: false,
+		unknownSlug: false,
+	}),
+}));
+
+vi.mock('../../auth/oauth-login', () => ({
+	initiateOAuthLogin: vi.fn(),
+}));
+
+vi.mock('../../auth/service', () => ({
+	AuthService: {
+		getAccessToken: () => null,
+		getCurrentRole: () => mockState.role,
+		getPermissions: () => mockState.permissions,
+	},
+	setBootstrapLock: vi.fn(),
+}));
+
+import { RequireAuth } from '../RequireAuth';
+
+/** findings §1.1：security_admin 存量持有的 14 条 `*:admin` 弹药（实扫自 platform_rbac.go catalog） */
+const AMMO_14 = [
+	'tenant:admin',
+	'saml:admin',
+	'mfa:admin',
+	'billing:admin',
+	'notification:admin',
+	'pay:admin',
+	'compliance:admin',
+	'wallet:admin',
+	'point:admin',
+	'oauth:admin',
+	'secret:admin',
+	'status:admin',
+	'identity:admin',
+	'storage:admin',
+];
+
+const ADMIN_ONLY = ['super_admin', 'admin'] as const;
+const SECURITY_READ = ['super_admin', 'admin', 'security_admin'] as const;
+
+function renderGuard(checkpoint: string, props: Record<string, unknown>) {
+	return render(
+		<RequireAuth
+			fallback={<div data-testid={`forbidden-${checkpoint}`}>forbidden</div>}
+			{...props}
+		>
+			<div data-testid={`protected-${checkpoint}`}>protected</div>
+		</RequireAuth>,
+	);
+}
+
+beforeEach(() => {
+	mockState.machineStatus = 'ready';
+	mockState.role = 'admin';
+	mockState.permissions = [];
+	delete (window as any).__APP_CONFIG__;
+});
+
+afterEach(() => {
+	cleanup();
+});
+
+describe('RequireAuth 对抗 6 类（A-445 / RC-4）', () => {
+	it('① security_admin + 14 条 *:admin 弹药 + Admin 白名单 ⇒ 拦截（子串穿透不得成立）', () => {
+		mockState.role = 'security_admin';
+		mockState.permissions = [...AMMO_14];
+
+		renderGuard('c1', { allowedRoles: ADMIN_ONLY });
+
+		expect(screen.getByTestId('forbidden-c1')).toBeInTheDocument();
+		expect(screen.queryByTestId('protected-c1')).toBeNull();
+	});
+
+	it('② admin / super_admin ⇒ 放行', () => {
+		mockState.role = 'admin';
+		const r1 = renderGuard('c2a', { allowedRoles: ADMIN_ONLY });
+		expect(screen.getByTestId('protected-c2a')).toBeInTheDocument();
+		r1.unmount();
+
+		mockState.role = 'super_admin';
+		renderGuard('c2b', { allowedRoles: ADMIN_ONLY });
+		expect(screen.getByTestId('protected-c2b')).toBeInTheDocument();
+	});
+
+	it('③ user_manager / 空权限 ⇒ fail-closed 拦截', () => {
+		mockState.role = 'user_manager';
+		mockState.permissions = [];
+
+		renderGuard('c3', { allowedRoles: ADMIN_ONLY });
+
+		expect(screen.getByTestId('forbidden-c3')).toBeInTheDocument();
+		expect(screen.queryByTestId('protected-c3')).toBeNull();
+	});
+
+	it('④ role=null ⇒ 穿透（现语义锁定，防误改）', () => {
+		mockState.role = null;
+		mockState.permissions = [];
+
+		renderGuard('c4', { allowedRoles: ADMIN_ONLY });
+
+		expect(screen.getByTestId('protected-c4')).toBeInTheDocument();
+	});
+
+	it('⑤ 持 \"*\" 的非白名单角色 ⇒ 放行（豁免对照组）', () => {
+		mockState.role = 'operator';
+		mockState.permissions = ['*'];
+
+		renderGuard('c5', { allowedRoles: ADMIN_ONLY });
+
+		expect(screen.getByTestId('protected-c5')).toBeInTheDocument();
+	});
+
+	it('⑥ security_admin + SecurityRead（含 security_admin）白名单 ⇒ 放行（对照组）', () => {
+		mockState.role = 'security_admin';
+		mockState.permissions = ['audit:read', 'compliance:read'];
+
+		renderGuard('c6', { allowedRoles: SECURITY_READ });
+
+		expect(screen.getByTestId('protected-c6')).toBeInTheDocument();
+	});
+
+	it('⑦ allowedRoles 未配置 ⇒ 直通 children（AC-AB1-04 回归锁）', () => {
+		mockState.role = 'member';
+		mockState.permissions = ['user:read'];
+
+		render(
+			<RequireAuth>
+				<div data-testid="protected-c7">protected</div>
+			</RequireAuth>,
+		);
+
+		expect(screen.getByTestId('protected-c7')).toBeInTheDocument();
+	});
+});