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

package/src/auth/__tests__/auth-trace.test.ts

@@ -0,0 +1,321 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ============================================================
+// authTrace 三层回归锁（#48）
+//  ① interstitial：被动跳转 → 提示条（可停留），延迟后 replace
+//  ② debug=auth → 确认页（不自动跳，手动继续/留）
+//  ③ 结构化日志：环形缓冲 / 凭据剥离 / ?rt= 跨站面包屑 / dump()
+// ============================================================
+
+const replaceSpy = vi.fn();
+let assignCalls: string[] = [];
+let currentHref = '';
+const originalLocationDescriptor = Object.getOwnPropertyDescriptor(window, 'location');
+
+// 只替换 window.location（不动 window 本体 —— stubGlobal 会连 localStorage/sessionStorage
+// 一起遮蔽）。字段给纯值 + href getter/setter，绕开 jsdom Location brand check。
+function mockWindowLocation(pathname: string, search = ''): void {
+	currentHref = `https://user.autional.local${pathname}${search}`;
+	Object.defineProperty(window, 'location', {
+		configurable: true,
+		value: {
+			pathname,
+			search,
+			origin: 'https://user.autional.local',
+			hostname: 'user.autional.local',
+			protocol: 'https:',
+			replace: replaceSpy,
+			get href() {
+				return currentHref;
+			},
+			set href(v: string) {
+				assignCalls.push(v);
+			},
+		},
+	});
+}
+
+/** 每例取全新模块实例：清 initialized / pending / buffer 模块态。 */
+async function freshTrace() {
+	vi.resetModules();
+	return await import('../auth-trace');
+}
+
+function notice(): HTMLElement | null {
+	return document.getElementById('auth-trace-notice');
+}
+function confirm(): HTMLElement | null {
+	return document.getElementById('auth-trace-confirm');
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	assignCalls = [];
+	sessionStorage.clear();
+	document.body.innerHTML = '';
+	document.documentElement.lang = 'zh-CN';
+});
+
+afterEach(() => {
+	if (originalLocationDescriptor) {
+		Object.defineProperty(window, 'location', originalLocationDescriptor);
+	}
+	document.body.innerHTML = '';
+	vi.useRealTimers();
+});
+
+describe('层 ③ 结构化日志与缓冲', () => {
+	it('traceEvent 写入环形缓冲，50 条封顶（丢最旧）', async () => {
+		mockWindowLocation('/demo/');
+		const { traceEvent, traceDump } = await freshTrace();
+		for (let i = 0; i < 55; i++) traceEvent('evt', { reason: `r${i}` });
+		const entries = (window as any).__authTrace.entries() as any[];
+		expect(entries).toHaveLength(50);
+		expect(entries[0].reason).toBe('r5');
+		expect(entries[49].reason).toBe('r54');
+		expect(traceDump()).toContain('r54');
+	});
+
+	it('缓冲中的 URL 剥除凭据类 query（token/code/state 不入 trace）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect(
+			'https://auth.autional.local/demo/login?redirect=x&access_token=SECRET&code=ABC123&state=st&ok=1',
+			{ reason: 'unauthenticated', kind: 'funnel' },
+		);
+		const entries = (window as any).__authTrace.entries() as any[];
+		const to = entries[entries.length - 1].to as string;
+		expect(to).not.toContain('SECRET');
+		expect(to).not.toContain('ABC123');
+		expect(to).not.toContain('state=');
+		expect(to).toContain('ok=1');
+	});
+
+	it('dump() 含环境摘要与条目', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceEvent, traceDump } = await freshTrace();
+		traceEvent('error-exit', { reason: 'session_expired' });
+		const dump = traceDump();
+		expect(dump).toContain('authTrace v1 @user');
+		expect(dump).toContain('error-exit');
+	});
+
+	it('?rt= 跨站面包屑：读取接续为 handoff 条目', async () => {
+		mockWindowLocation('/demo/login', '?rt=auth.unauthenticated.abc123&redirect=x');
+		const { traceDump } = await freshTrace();
+		const dump = traceDump();
+		expect(dump).toContain('handoff');
+		expect(dump).toContain('auth@');
+	});
+});
+
+describe('层 ① interstitial 提示与停留', () => {
+	it('被动跳转：先出提示条，延迟后 replace（URL 带 rt= 面包屑）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'session-expired',
+			kind: 'interstitial',
+		});
+
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(notice()).not.toBeNull();
+		expect(notice()!.textContent).toContain('会话已过期');
+
+		vi.advanceTimersByTime(1600);
+		expect(notice()).toBeNull();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('rt=user.session-expired.');
+	});
+
+	it('点「停留」：取消跳转 + pending 复位（后续 funnel 照常执行）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'session-expired',
+			kind: 'interstitial',
+		});
+		const stayBtn = Array.from(notice()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('停留'),
+		)!;
+		stayBtn.click();
+
+		expect(notice()).toBeNull();
+		vi.advanceTimersByTime(5000);
+		expect(replaceSpy).not.toHaveBeenCalled();
+
+		// pending 已复位：funnel 直跳不受阻
+		traceRedirect('https://brand.autional.local/?redirect=x', { reason: 'funnel-slug', kind: 'funnel' });
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('AUTH-03 点「停留」：onStay 回调触发（调用方据此恢复 UI）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+		const onStay = vi.fn();
+
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'unauthenticated',
+			kind: 'interstitial',
+			onStay,
+		});
+		const stayBtn = Array.from(notice()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('停留'),
+		)!;
+		stayBtn.click();
+
+		expect(onStay).toHaveBeenCalledTimes(1);
+	});
+
+	it('AUTH-03 onStay 回调抛错：不冒泡打断停留处理（pending 仍复位）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'unauthenticated',
+			kind: 'interstitial',
+			onStay: () => {
+				throw new Error('boom');
+			},
+		});
+		const stayBtn = Array.from(notice()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('停留'),
+		)!;
+		expect(() => stayBtn.click()).not.toThrow();
+
+		vi.advanceTimersByTime(5000);
+		expect(replaceSpy).not.toHaveBeenCalled();
+		// pending 已复位：funnel 直跳不受阻
+		traceRedirect('https://brand.autional.local/?redirect=x', { reason: 'funnel-slug', kind: 'funnel' });
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('pending 抑制：提示条未决时再来一次 interstitial 被记为 suppressed', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login', { reason: 'unauthenticated', kind: 'interstitial' });
+		traceRedirect('https://auth.autional.local/other/login', { reason: 'unauthenticated', kind: 'interstitial' });
+
+		const entries = (window as any).__authTrace.entries() as any[];
+		expect(entries.filter((e) => e.ev === 'suppressed')).toHaveLength(1);
+		vi.advanceTimersByTime(1600);
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('/demo/login');
+	});
+
+	it('funnel（缺省 kind）：静默直跳，不出现提示条', async () => {
+		mockWindowLocation('/');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://brand.autional.local/?redirect=x', { reason: 'funnel-brand' });
+		expect(notice()).toBeNull();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe('层 ② debug 确认页', () => {
+	it('?debug=auth：不自动跳，确认页出现；点「继续前往」才 replace', async () => {
+		mockWindowLocation('/demo/dashboard', '?debug=auth');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'session-expired',
+			kind: 'interstitial',
+		});
+
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(confirm()).not.toBeNull();
+		expect(confirm()!.textContent).toContain('整页跳转确认');
+
+		const goBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('继续前往'),
+		)!;
+		goBtn.click();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('debug=auth');
+	});
+
+	it('确认页点「留在本页」：不跳 + pending 复位 + onStay 回调触发', async () => {
+		mockWindowLocation('/demo/dashboard', '?debug=auth');
+		const { traceRedirect } = await freshTrace();
+		const onStay = vi.fn();
+		traceRedirect('https://auth.autional.local/demo/login', {
+			reason: 'unauthenticated',
+			kind: 'funnel',
+			onStay,
+		});
+
+		const stayBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('留在本页'),
+		)!;
+		stayBtn.click();
+		expect(confirm()).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(onStay).toHaveBeenCalledTimes(1);
+	});
+
+	it('debug 标志经 sessionStorage 保持并随跳转透传（无需每次带 ?debug=auth）', async () => {
+		mockWindowLocation('/demo/');
+		const { traceRedirect } = await freshTrace();
+		(window as any).__authTrace.on();
+
+		traceRedirect('https://auth.autional.local/demo/login', { reason: 'unauthenticated' });
+		expect(confirm()).not.toBeNull();
+		const goBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('继续前往'),
+		)!;
+		goBtn.click();
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('debug=auth');
+	});
+
+	it('assign 语义：opts.assign=true 走 location.href（登录/登出链保持新增历史）', async () => {
+		mockWindowLocation('/demo/');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://auth.autional.local/?logout=1', { reason: 'logout', assign: true });
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(assignCalls).toHaveLength(1);
+		expect(assignCalls[0]).toContain('logout=1');
+	});
+});
+
+describe('跳转执行防御（非法目标不炸页）', () => {
+	it('replace 抛 SyntaxError（IP 主机派生的 brand.127.0.0.1）→ 不冒泡，记 error-exit', async () => {
+		mockWindowLocation('/demo/');
+		const { traceRedirect } = await freshTrace();
+		replaceSpy.mockImplementationOnce(() => {
+			throw new SyntaxError(
+				"Failed to execute 'replace' on 'Location': 'http://brand.127.0.0.1/' is not a valid URL.",
+			);
+		});
+
+		expect(() =>
+			traceRedirect('http://brand.127.0.0.1/?redirect=x', { reason: 'funnel-brand' }),
+		).not.toThrow();
+
+		const entries = (window as any).__authTrace.entries() as any[];
+		const errEntry = entries.find((e) => e.ev === 'error-exit');
+		expect(errEntry).toBeTruthy();
+		expect(errEntry.reason).toBe('invalid-target');
+	});
+
+	it('防御后 pending 复位：随后合法跳转照常执行', async () => {
+		mockWindowLocation('/demo/');
+		const { traceRedirect } = await freshTrace();
+		replaceSpy.mockImplementationOnce(() => {
+			throw new SyntaxError('bad url');
+		});
+
+		traceRedirect('http://brand.127.0.0.1/?redirect=x', { reason: 'funnel-brand' });
+		traceRedirect('https://brand.autional.local/?redirect=y', { reason: 'funnel-brand' });
+
+		expect(replaceSpy).toHaveBeenCalledTimes(2);
+		expect(String(replaceSpy.mock.calls[1][0])).toContain('brand.autional.local');
+	});
+});

package/src/auth/__tests__/build-login-url.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { buildLoginUrl, buildLogoutUrl, isAuthLoginSurface } from '../roles';
+
+const MOCK_CONFIG = {
+	VITE_PORTAL_CONFIG: {
+		auth: { host: 'auth', base: '' },
+	},
+};
+
+function mockWindow(
+	hostname: string,
+	protocol: string,
+	origin: string,
+	config: any = MOCK_CONFIG,
+): void {
+	vi.stubGlobal('window', {
+		location: { hostname, protocol, origin },
+		__APP_CONFIG__: config,
+	});
+}
+
+describe('buildLoginUrl', () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe('basic URL construction', () => {
+		it('builds base login URL pointing to auth domain', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl();
+			expect(url).toBe('https://auth.iam.tianv.local');
+		});
+
+		it('includes redirect param when returnUrl provided', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl('https://app.iam.tianv.com/admin');
+			expect(url).toContain('redirect=');
+			expect(url).toContain(encodeURIComponent('https://app.iam.tianv.com/admin'));
+		});
+	});
+
+	describe('fromRequireAuth parameter', () => {
+		it('appends from_requireauth=1 when fromRequireAuth is true', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl(undefined, true);
+			expect(url).toContain('from_requireauth=1');
+		});
+
+		it('appends from_requireauth=1 with redirect param', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl('https://app.iam.tianv.com/admin', true);
+			expect(url).toContain('redirect=');
+			expect(url).toContain('from_requireauth=1');
+			expect(url).toContain('&from_requireauth=1');
+		});
+
+		it('does not include from_requireauth when fromRequireAuth is false', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl('https://app.iam.tianv.com/admin', false);
+			expect(url).not.toContain('from_requireauth');
+		});
+
+		it('does not include from_requireauth when fromRequireAuth is undefined', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl('https://app.iam.tianv.com/admin');
+			expect(url).not.toContain('from_requireauth');
+		});
+
+		it('returns only from_requireauth=1 when no returnUrl but fromRequireAuth is true', () => {
+			mockWindow('app.iam.tianv.local', 'https:', 'https://app.iam.tianv.local');
+			const url = buildLoginUrl(undefined, true);
+			expect(url).toContain('?from_requireauth=1');
+			expect(url).not.toContain('redirect=');
+		});
+	});
+
+	describe('domain-agnostic', () => {
+		it('works with .com domain', () => {
+			mockWindow('app.iam.tianv.com', 'https:', 'https://app.iam.tianv.com');
+			const url = buildLoginUrl();
+			expect(url).toBe('https://auth.iam.tianv.com');
+		});
+
+		it('works with autional.com domain', () => {
+			mockWindow('app.autional.com', 'https:', 'https://app.autional.com');
+			const url = buildLoginUrl();
+			expect(url).toBe('https://auth.autional.com');
+		});
+	});
+
+	describe('tenant-slug preservation', () => {
+		const AUTH_CONFIG = {
+			VITE_PORTAL_CONFIG: {
+				auth: { host: 'auth', base: '' },
+			},
+		};
+
+		it('redirects to {slug}/login when returnUrl is tenant-scoped on auth domain', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://auth.autional.local/acme-corp/dashboard');
+			expect(url).toBe(
+				'https://auth.autional.local/acme-corp/login?redirect=' +
+					encodeURIComponent('https://auth.autional.local/acme-corp/dashboard'),
+			);
+		});
+
+		it('keeps from_requireauth on tenant-scoped login url', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://auth.autional.local/acme-corp/dashboard', true);
+			expect(url).toBe(
+				'https://auth.autional.local/acme-corp/login?redirect=' +
+					encodeURIComponent('https://auth.autional.local/acme-corp/dashboard') +
+					'&from_requireauth=1',
+			);
+		});
+
+		it('does not treat reserved auth routes as tenant slug', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://auth.autional.local/reset-password');
+			expect(url).toBe(
+				'https://auth.autional.local?redirect=' +
+					encodeURIComponent('https://auth.autional.local/reset-password'),
+			);
+		});
+
+		it('preserves cross-domain returnUrl behavior (app domain)', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://app.autional.com/admin');
+			expect(url).toBe(
+				'https://auth.autional.local?redirect=' +
+					encodeURIComponent('https://app.autional.com/admin'),
+			);
+		});
+
+		it('does not truncate cross-domain returnUrl containing /login substring (regression P1-2)', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://app.autional.com/admin/login');
+			expect(url).toBe(
+				'https://auth.autional.local?redirect=' +
+					encodeURIComponent('https://app.autional.com/admin/login'),
+			);
+		});
+
+		it('truncates auth-domain login page itself (no nested redirect)', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://auth.autional.local/acme-corp/login');
+			expect(url).toBe('https://auth.autional.local/acme-corp/login');
+		});
+	});
+
+	describe('useLogout unification (logout → login redirect)', () => {
+		const AUTH_CONFIG = {
+			VITE_PORTAL_CONFIG: {
+				auth: { host: 'auth', base: '' },
+			},
+		};
+
+		it('logout from auth-domain tenant page keeps tenant slug (bug scenario)', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://auth.autional.local/acme-corp/dashboard');
+			expect(url).toBe(
+				'https://auth.autional.local/acme-corp/login?redirect=' +
+					encodeURIComponent('https://auth.autional.local/acme-corp/dashboard'),
+			);
+		});
+
+		it('logout from auth root (tenant select page) does not add redirect', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLoginUrl('https://auth.autional.local/');
+			expect(url).toBe('https://auth.autional.local');
+		});
+
+		it('logout from portal domain falls back to generic auth login (no slug misjudge)', () => {
+			// useLogout 在 portal app 中跨域调用：returnUrl origin ≠ auth origin，
+			// 首段 /admin 不会被误判为租户 slug，跳转 {base}?redirect=<portal-url>
+			mockWindow('app.autional.com', 'https:', 'https://app.autional.com', AUTH_CONFIG);
+			const url = buildLoginUrl('https://app.autional.com/admin');
+			expect(url).toBe(
+				'https://auth.autional.com?redirect=' +
+					encodeURIComponent('https://app.autional.com/admin'),
+			);
+		});
+	});
+
+	describe('buildLogoutUrl（F-W5c 登出意图标记）', () => {
+		const AUTH_CONFIG = {
+			VITE_PORTAL_CONFIG: {
+				auth: { host: 'auth', base: '' },
+			},
+		};
+
+		it('门户域登出：auth 裸根 + redirect 回程 + logout=1', () => {
+			mockWindow('app.autional.com', 'https:', 'https://app.autional.com', AUTH_CONFIG);
+			const url = buildLogoutUrl('https://app.autional.com/demo/');
+			expect(url).toBe(
+				'https://auth.autional.com/?redirect=' +
+					encodeURIComponent('https://app.autional.com/demo/') +
+					'&logout=1',
+			);
+		});
+
+		it('auth 域租户页登出也走裸根：不经 /<slug>/login（那里 logout=1 被静默忽略）', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLogoutUrl('https://auth.autional.local/acme-corp/dashboard');
+			expect(url).toBe(
+				'https://auth.autional.local/?redirect=' +
+					encodeURIComponent('https://auth.autional.local/acme-corp/dashboard') +
+					'&logout=1',
+			);
+			expect(url).not.toContain('/acme-corp/login');
+		});
+
+		it('无回程：auth 裸根 + logout=1', () => {
+			mockWindow('auth.autional.local', 'https:', 'https://auth.autional.local', AUTH_CONFIG);
+			const url = buildLogoutUrl();
+			expect(url).toBe('https://auth.autional.local/?logout=1');
+		});
+	});
+});
+
+// ============================================================
+// F-W8b 修复②：登录承接面判定（onUnauthorized 抑制整页弹走的判据）
+//  承接面（只清理不导航）：`/`、`/login`、`/<slug>/login`、`/error`
+//  非承接面（照常弹登录页）：应用页、PKCE 发起页、其它静态路由
+// ============================================================
+function mockPathname(pathname: string): void {
+	vi.stubGlobal('window', {
+		location: { pathname, hostname: 'auth.autional.local', protocol: 'https:' },
+		__APP_CONFIG__: MOCK_CONFIG,
+	});
+}
+
+describe('isAuthLoginSurface', () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it.each([
+		['裸根入口', '/', true],
+		['/login 入口', '/login', true],
+		['错误页', '/error', true],
+		['租户登录页', '/demo/login', true],
+		['带尾斜杠的租户登录页', '/demo/login/', true],
+		['应用页 dashboard', '/demo/dashboard', false],
+		['租户 index（守卫跳转页）', '/demo', false],
+		['裸 dashboard', '/dashboard', false],
+		['PKCE 发起页', '/oauth/api/v1/oauth/authorize', false],
+		['重置密码页', '/reset-password', false],
+		['注册页', '/demo/register', false],
+	])('%s（%s）→ %s', (_name, pathname, expected) => {
+		mockPathname(pathname as string);
+		expect(isAuthLoginSurface()).toBe(expected);
+	});
+
+	it('服务端渲染（无 window）→ false，不抑制', () => {
+		vi.stubGlobal('window', undefined);
+		expect(isAuthLoginSurface()).toBe(false);
+	});
+});

package/src/auth/__tests__/get-current-role.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { useAuthStore, getCurrentRole } from '../store';
+
+// 注：node 测试环境下 zustand persist 中间件会打印一条无害的 storage 降级警告
+// （"Unable to update item 'autional-auth-v1'"），这是 store.ts 既有 persist 的
+// 标准降级行为，不影响被测的 getCurrentRole 派生逻辑。
+
+const TENANTS = [
+	{ id: 'tenant-a', name: 'Tenant A', role: 'admin' },
+	{ id: 'tenant-b', name: 'Tenant B', role: 'member' },
+];
+
+/** 重置 store 到初始状态，避免跨用例污染（AC-002 约定） */
+function resetAuthStore(): void {
+	useAuthStore.setState({
+		user: null,
+		accessToken: null,
+		refreshToken: null,
+		tenants: [],
+		currentTenantId: null,
+		permissions: [],
+		isAuthenticated: false,
+	});
+}
+
+describe('getCurrentRole (AC-001 四态派生，userinfo-first)', () => {
+	beforeEach(() => {
+		resetAuthStore();
+	});
+
+	it('① tenants 空 → null', () => {
+		useAuthStore.setState({ tenants: [], currentTenantId: 'tenant-a' });
+		expect(getCurrentRole()).toBeNull();
+	});
+
+	it('② currentTenantId null → null（不猜测）', () => {
+		useAuthStore.setState({ tenants: TENANTS, currentTenantId: null });
+		expect(getCurrentRole()).toBeNull();
+	});
+
+	it('③ 命中 → tenants.find(t => t.id === currentTenantId).role', () => {
+		useAuthStore.setState({ tenants: TENANTS, currentTenantId: 'tenant-a' });
+		expect(getCurrentRole()).toBe('admin');
+
+		useAuthStore.setState({ currentTenantId: 'tenant-b' });
+		expect(getCurrentRole()).toBe('member');
+	});
+
+	it('④ 租户切换后重查返回新角色（switchTenant）', () => {
+		useAuthStore.setState({ tenants: TENANTS, currentTenantId: 'tenant-a' });
+		expect(getCurrentRole()).toBe('admin');
+
+		useAuthStore.getState().switchTenant('tenant-b');
+		expect(getCurrentRole()).toBe('member');
+	});
+
+	it('currentTenantId 指向不存在的租户 → null（不猜测）', () => {
+		useAuthStore.setState({ tenants: TENANTS, currentTenantId: 'tenant-ghost' });
+		expect(getCurrentRole()).toBeNull();
+	});
+});