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

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

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+// ============================================================
+// AUTH-03：未认证 + 用户点「停留」不得留空白死路——
+//  ① 无 OAuth client（buildLoginUrl 链）：停留 → 恢复态（需要登录/前往登录）；点击再发起
+//  ② 有 OAuth client（PKCE 链）：停留 → 恢复态；点击以 force 跳过 10s 防重入再发起
+// ============================================================
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act, fireEvent, render, screen, cleanup, waitFor } from '@testing-library/react';
+
+const { mockState, mockInitiate, mockTrace } = vi.hoisted(() => ({
+	mockState: {
+		machineStatus: 'ready' as string,
+		tenantRoute: {
+			slug: null as string | null,
+			tenantId: null as string | null,
+			oauthClientId: null as string | null,
+			loading: false,
+			notFound: false,
+			unknownSlug: false,
+		},
+	},
+	mockInitiate: vi.fn(),
+	mockTrace: 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[]) => mockInitiate(...args),
+}));
+
+vi.mock('../../auth/auth-trace', () => ({
+	traceRedirect: (...args: any[]) => mockTrace(...args),
+}));
+
+vi.mock('../../auth/service', () => ({
+	AuthService: {
+		getAccessToken: () => null,
+		getCurrentRole: () => 'admin',
+		getPermissions: () => [],
+	},
+	setBootstrapLock: vi.fn(),
+}));
+
+import { RequireAuth } from '../RequireAuth';
+
+function renderGuard() {
+	return render(
+		<RequireAuth>
+			<div data-testid="protected">protected</div>
+		</RequireAuth>,
+	);
+}
+
+beforeEach(() => {
+	mockState.machineStatus = 'ready';
+	mockState.tenantRoute = {
+		slug: null,
+		tenantId: null,
+		oauthClientId: null,
+		loading: false,
+		notFound: false,
+		unknownSlug: false,
+	};
+	delete (window as any).__APP_CONFIG__;
+	document.documentElement.lang = 'zh-CN';
+});
+
+afterEach(() => {
+	cleanup();
+	vi.clearAllMocks();
+});
+
+describe('RequireAuth「停留」恢复态（AUTH-03）', () => {
+	it('无 OAuth client：停留 → 恢复态渲染，「前往登录」再发起（interstitial 重弹）', async () => {
+		mockState.machineStatus = 'unauthenticated';
+		renderGuard();
+
+		// effect → setTimeout(0) → traceRedirect(interstitial)；未停留时仍是空白
+		await waitFor(() => expect(mockTrace).toHaveBeenCalledTimes(1));
+		expect(screen.queryByTestId('protected')).toBeNull();
+		expect(screen.queryByText('需要登录')).toBeNull();
+
+		const opts = mockTrace.mock.calls[0][1];
+		expect(opts.kind).toBe('interstitial');
+		expect(typeof opts.onStay).toBe('function');
+
+		// 用户点「停留」→ onStay → 恢复态（不再空白）
+		act(() => opts.onStay());
+		expect(await screen.findByText('需要登录')).toBeInTheDocument();
+
+		act(() => fireEvent.click(screen.getByRole('button', { name: '前往登录' })));
+		await waitFor(() => expect(mockTrace).toHaveBeenCalledTimes(2));
+	});
+
+	it('有 OAuth client：停留 → 恢复态；「前往登录」以 force 跳过防重入重发起', async () => {
+		(window as any).__APP_CONFIG__ = { VITE_OAUTH_CLIENT_ID: 'portal-cid' };
+		mockState.machineStatus = 'unauthenticated';
+		renderGuard();
+
+		await waitFor(() => expect(mockInitiate).toHaveBeenCalledTimes(1));
+		const [cidArg, , opts] = mockInitiate.mock.calls[0];
+		expect(cidArg).toBe('portal-cid');
+		expect(opts.force).toBe(false);
+		expect(typeof opts.onStay).toBe('function');
+
+		act(() => opts.onStay());
+		expect(await screen.findByText('需要登录')).toBeInTheDocument();
+
+		act(() => fireEvent.click(screen.getByRole('button', { name: '前往登录' })));
+		await waitFor(() => expect(mockInitiate).toHaveBeenCalledTimes(2));
+		expect(mockInitiate.mock.calls[1][2]).toMatchObject({ force: true });
+	});
+
+	it('未停留时保持原语义：unauthenticated 渲染 null（无恢复态）', async () => {
+		mockState.machineStatus = 'unauthenticated';
+		renderGuard();
+
+		await waitFor(() => expect(mockTrace).toHaveBeenCalledTimes(1));
+		expect(screen.queryByText('需要登录')).toBeNull();
+		expect(screen.queryByTestId('protected')).toBeNull();
+	});
+});

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

@@ -0,0 +1,296 @@
+// @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;
+
+/**
+ * 每例取全新模块实例：auth-trace 的模块级重入抑制（pending）与「停留」复位
+ * 是同页语义，跨用例泄漏会让后续 interstitial 被静默抑制（假红/假绿）。
+ */
+async function freshRequireAuth() {
+	vi.resetModules();
+	const mod = await import('../RequireAuth');
+	return mod.RequireAuth;
+}
+
+/** authTrace 的提示条/确认页挂在 document.body（非 React 树），手动清理防跨用例残留。 */
+function cleanupAuthTraceNodes() {
+	document.getElementById('auth-trace-notice')?.remove();
+	document.getElementById('auth-trace-confirm')?.remove();
+}
+
+function clickGoNow(): void {
+	const btn = Array.from(document.querySelectorAll<HTMLButtonElement>('#auth-trace-notice button')).find(
+		(b) => b.textContent === '立即前往',
+	);
+	expect(btn).toBeTruthy();
+	btn!.click();
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	document.documentElement.lang = 'zh-CN';
+	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();
+	cleanupAuthTraceNodes();
+});
+
+describe('RequireAuth 未登录出口', () => {
+	it('无可用 client_id → 提示条（可停留）后跳 auth 登录页并带 from_requireauth=1', async () => {
+		const RequireAuthFresh = await freshRequireAuth();
+
+		render(
+			<RequireAuthFresh>
+				<div>protected</div>
+			</RequireAuthFresh>,
+		);
+
+		// 层①：被动弹登录先出提示条（不再静默整页弹走）
+		await waitFor(() => expect(document.getElementById('auth-trace-notice')).toBeTruthy());
+		clickGoNow();
+
+		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).toContain('rt=localhost.unauthenticated.');
+		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(() => {
+			// AUTH-03：第三参携「停留」恢复回调；effect 路径 force=false
+			expect(mockState.initiate).toHaveBeenCalledWith(
+				'cid-from-slug',
+				undefined,
+				expect.objectContaining({ force: false, onStay: expect.any(Function) }),
+			);
+		});
+		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',
+				undefined,
+				expect.objectContaining({ force: false, onStay: expect.any(Function) }),
+			);
+		});
+		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',
+				undefined,
+				expect.objectContaining({ force: false, onStay: expect.any(Function) }),
+			),
+		);
+		expect(screen.queryByTestId('tenant-404')).toBeNull();
+		expect(mockState.replace).not.toHaveBeenCalled();
+	});
+
+	it('非 unknownSlug（网络错误 fail-open）→ 维持原漏斗（回归锁）', async () => {
+		// 默认 tenantRoute: notFound=true, unknownSlug=false —— 即 by-slug 网络错误场景
+		const RequireAuthFresh = await freshRequireAuth();
+
+		render(
+			<RequireAuthFresh notFound={<div data-testid="tenant-404">no such tenant</div>}>
+				<div>protected</div>
+			</RequireAuthFresh>,
+		);
+
+		await waitFor(() => expect(document.getElementById('auth-trace-notice')).toBeTruthy());
+		clickGoNow();
+		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();
+	});
+});

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

@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, cleanup, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+import { TenantIndexGuard, usePublicTenantSlugs } from '../TenantIndexGuard';
+
+function createQueryClient() {
+	return new QueryClient({
+		defaultOptions: {
+			queries: { retry: false, gcTime: Infinity },
+		},
+	});
+}
+
+function wrapper(children: ReactNode) {
+	return <QueryClientProvider client={createQueryClient()}>{children}</QueryClientProvider>;
+}
+
+/** mock fetch 返回 items 数组的 ListResponse */
+function stubFetch(items: unknown[], ok = true, status = 200) {
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok,
+			status,
+			json: async () => ({ code: 0, message: 'success', items, total: items.length }),
+		}),
+	);
+}
+
+function stubFetchData(items: unknown[]) {
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok: true,
+			status: 200,
+			json: async () => ({ code: 0, message: 'success', data: items }),
+		}),
+	);
+}
+
+function stubFetchReject() {
+	vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network down')));
+}
+
+function stubFetchNonOk() {
+	vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500 }));
+}
+
+function stubFetchBadShape() {
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok: true,
+			status: 200,
+			json: async () => ({ foo: 'bar' }),
+		}),
+	);
+}
+
+function setPath(path: string) {
+	window.history.pushState({}, '', path);
+}
+
+describe('usePublicTenantSlugs（响应契约解析）', () => {
+	beforeEach(() => {
+		setPath('/acme-corp');
+	});
+
+	afterEach(() => {
+		cleanup();
+		vi.unstubAllGlobals();
+	});
+
+	it('ListResponse 用 items 字段 → 返回租户数组（修复回归）', async () => {
+		stubFetch([
+			{ id: '1', name: 'acme-corp' },
+			{ id: '2', name: 'beta-inc' },
+		]);
+		let result: unknown[] | undefined;
+		function Harness() {
+			const q = usePublicTenantSlugs();
+			result = q.data;
+			return null;
+		}
+		render(wrapper(<Harness />));
+		await waitFor(() =>
+			expect(result).toEqual([
+				{ id: '1', name: 'acme-corp' },
+				{ id: '2', name: 'beta-inc' },
+			]),
+		);
+	});
+
+	it('旧 data 字段兼容 → 返回租户数组', async () => {
+		stubFetchData([{ id: '1', name: 'acme-corp' }]);
+		let result: unknown[] | undefined;
+		function Harness() {
+			const q = usePublicTenantSlugs();
+			result = q.data;
+			return null;
+		}
+		render(wrapper(<Harness />));
+		await waitFor(() => expect(result).toEqual([{ id: '1', name: 'acme-corp' }]));
+	});
+
+	it('API 非 200 → 返回空数组（放行语义）', async () => {
+		stubFetchNonOk();
+		let result: unknown[] | undefined;
+		function Harness() {
+			const q = usePublicTenantSlugs();
+			result = q.data;
+			return null;
+		}
+		render(wrapper(<Harness />));
+		await waitFor(() => expect(result).toEqual([]));
+	});
+
+	it('网络异常 → 返回空数组', async () => {
+		stubFetchReject();
+		let result: unknown[] | undefined;
+		function Harness() {
+			const q = usePublicTenantSlugs();
+			result = q.data;
+			return null;
+		}
+		render(wrapper(<Harness />));
+		await waitFor(() => expect(result).toEqual([]));
+	});
+
+	it('响应无 items/data 且非数组 → 返回空数组', async () => {
+		stubFetchBadShape();
+		let result: unknown[] | undefined;
+		function Harness() {
+			const q = usePublicTenantSlugs();
+			result = q.data;
+			return null;
+		}
+		render(wrapper(<Harness />));
+		await waitFor(() => expect(result).toEqual([]));
+	});
+});
+
+describe('TenantIndexGuard（P0-2 slug 白名单守卫）', () => {
+	const children = <div data-testid="children">Home</div>;
+	const notFound = <div data-testid="notfound">404</div>;
+
+	beforeEach(() => {
+		setPath('/acme-corp');
+	});
+
+	afterEach(() => {
+		cleanup();
+		vi.unstubAllGlobals();
+	});
+
+	it('slug 在白名单 → 渲染 children', async () => {
+		stubFetch([{ id: '1', name: 'acme-corp' }]);
+		render(wrapper(<TenantIndexGuard notFound={notFound}>{children}</TenantIndexGuard>));
+		await waitFor(() => expect(screen.getByTestId('children')).toBeInTheDocument());
+		expect(screen.queryByTestId('notfound')).toBeNull();
+	});
+
+	it('slug 不在白名单 → 渲染 notFound（修复回归：无效 slug 此前错误渲染首页）', async () => {
+		stubFetch([{ id: '1', name: 'acme-corp' }]);
+		setPath('/nonexistent-tenant');
+		render(wrapper(<TenantIndexGuard notFound={notFound}>{children}</TenantIndexGuard>));
+		await waitFor(() => expect(screen.getByTestId('notfound')).toBeInTheDocument());
+		expect(screen.queryByTestId('children')).toBeNull();
+	});
+
+	it('白名单为空数组 → 放行渲染 children（API 挂掉时退化为不拦截）', async () => {
+		stubFetch([]);
+		setPath('/any-slug');
+		render(wrapper(<TenantIndexGuard notFound={notFound}>{children}</TenantIndexGuard>));
+		await waitFor(() => expect(screen.getByTestId('children')).toBeInTheDocument());
+	});
+
+	it('URL 多段路径 → 直接 notFound（basename 已剥离 slug，内部必为未知段）', () => {
+		setPath('/acme-corp/xyz');
+		render(wrapper(<TenantIndexGuard notFound={notFound}>{children}</TenantIndexGuard>));
+		expect(screen.getByTestId('notfound')).toBeInTheDocument();
+		expect(screen.queryByTestId('children')).toBeNull();
+	});
+
+	it('加载中 → 渲染 loading 占位', async () => {
+		let resolveFetch: (v: unknown) => void;
+		const pending = new Promise((res) => {
+			resolveFetch = res;
+		});
+		vi.stubGlobal('fetch', vi.fn().mockReturnValue(pending));
+		setPath('/acme-corp');
+		const loading = <div data-testid="loading">Loading...</div>;
+		render(
+			wrapper(
+				<TenantIndexGuard notFound={notFound} loading={loading}>
+					{children}
+				</TenantIndexGuard>,
+			),
+		);
+		expect(screen.getByTestId('loading')).toBeInTheDocument();
+		await resolveFetch!({
+			ok: true,
+			status: 200,
+			json: async () => ({ code: 0, items: [{ id: '1', name: 'acme-corp' }] }),
+		});
+		await waitFor(() => expect(screen.getByTestId('children')).toBeInTheDocument());
+	});
+
+	it('空 slug（根路径 /）→ 渲染 children', async () => {
+		stubFetch([{ id: '1', name: 'acme-corp' }]);
+		setPath('/');
+		render(wrapper(<TenantIndexGuard notFound={notFound}>{children}</TenantIndexGuard>));
+		await waitFor(() => expect(screen.getByTestId('children')).toBeInTheDocument());
+	});
+});