@autional-cn/shared 0.1.0-rc.3 → 0.1.0-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autional-cn/shared",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.5",
   "description": "Autional shared layer — API client, auth, types, hooks, utils",
   "license": "AGPL-3.0",
   "main": "./src/index.ts",
@@ -31,10 +31,15 @@
     "zustand": "5.0.13"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "jsdom": "29.1.1",
     "react": "19.2.5",
     "react-dom": "19.2.5",
     "typescript": "5.8.3",
-    "vitest": "3.2.0"
+    "vite": "6.4.2",
+    "vitest": "3.2.0",
+    "@autional-cn/tsconfig": "0.1.0-rc"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

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

@@ -0,0 +1,237 @@
+// @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('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 复位', async () => {
+		mockWindowLocation('/demo/dashboard', '?debug=auth');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://auth.autional.local/demo/login', { reason: 'unauthenticated', kind: 'funnel' });
+
+		const stayBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('留在本页'),
+		)!;
+		stayBtn.click();
+		expect(confirm()).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	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');
+	});
+});

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { buildLoginUrl, buildLogoutUrl } from '../roles';
+import { buildLoginUrl, buildLogoutUrl, isAuthLoginSurface } from '../roles';
 
 const MOCK_CONFIG = {
 	VITE_PORTAL_CONFIG: {
@@ -217,3 +217,43 @@ describe('buildLoginUrl', () => {
 		});
 	});
 });
+
+// ============================================================
+// 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__/session-terminal-redirect.test.ts

@@ -0,0 +1,138 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ============================================================
+// F-W8b 修复②：会话终结（onUnauthorized）与刷新失败处置的整链回归锁
+//  - 已在 auth 登录承接面（`/<slug>/login`、`/error`、裸根入口）→ 只清会话，
+//    不整页弹走（否则 buildLoginUrl 防嵌套截断会丢掉 URL 中的 redirect 回程目标，
+//    且构成一次整页闪烁 —— 存量过期 token 在登录页「静默弹走」）
+//  - 非承接面 → 照常清理 + 整页弹登录页（带 slug 与回程 redirect）
+//  - refreshToken onFailure：'clear' 只清理不导航；'none' 零副作用；缺省 'redirect'
+// ============================================================
+
+const { mockPost } = vi.hoisted(() => ({ mockPost: vi.fn() }));
+
+vi.mock('axios', () => ({ default: { post: mockPost } }));
+vi.mock('../../api/bff-client', () => ({ bffLogout: vi.fn(() => Promise.resolve()) }));
+
+const replaceSpy = vi.fn();
+const originalLocationDescriptor = Object.getOwnPropertyDescriptor(window, 'location');
+
+// 只替换 window.location（不动 window 本体 —— stubGlobal 会连 localStorage 一起遮蔽，
+// zustand persist 在 setState 时崩）。字段给纯值，绕开 jsdom Location 的 brand check。
+function mockWindowLocation(pathname: string): void {
+	Object.defineProperty(window, 'location', {
+		configurable: true,
+		value: {
+			pathname,
+			href: `https://auth.autional.local${pathname}`,
+			origin: 'https://auth.autional.local',
+			hostname: 'auth.autional.local',
+			protocol: 'https:',
+			replace: replaceSpy,
+		},
+	});
+	(window as any).__APP_CONFIG__ = { VITE_PORTAL_CONFIG: { auth: { host: 'auth', base: '' } } };
+}
+
+/** 剥除 authTrace 面包屑（rt=）后比较；rt 装饰本身由 toMatch 锁定。 */
+function withoutRt(url: string): string {
+	const u = new URL(url);
+	u.searchParams.delete('rt');
+	return u.toString();
+}
+
+/** 每例取全新模块实例：清零 service.ts 的模块级重入锁（redirectingToLogin）。 */
+async function freshService() {
+	vi.resetModules();
+	const svc = await import('../service');
+	const store = await import('../store');
+	return { AuthService: svc.AuthService, useAuthStore: store.useAuthStore };
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	localStorage.clear();
+});
+
+afterEach(() => {
+	if (originalLocationDescriptor) {
+		Object.defineProperty(window, 'location', originalLocationDescriptor);
+	}
+	delete (window as any).__APP_CONFIG__;
+	vi.useRealTimers();
+});
+
+describe('onUnauthorized 承接面抑制（F-W8b 修复②）', () => {
+	it('已在 /<slug>/login：清理会话但不整页弹走（回程 redirect 不丢）', async () => {
+		mockWindowLocation('/demo/login');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-old', isAuthenticated: true });
+
+		AuthService.onUnauthorized();
+
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(useAuthStore.getState().isAuthenticated).toBe(false);
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it('已在 /error：同样只清理不弹走（错误页有自身倒计时出口）', async () => {
+		mockWindowLocation('/error');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-old', isAuthenticated: true });
+
+		AuthService.onUnauthorized();
+
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it('非承接面 /demo/dashboard：清理 + 整页弹登录页（带 slug 与回程 redirect）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-old', isAuthenticated: true });
+
+		vi.useFakeTimers();
+		AuthService.onUnauthorized();
+		vi.runAllTimers();
+
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		const url = String(replaceSpy.mock.calls[0][0]);
+		expect(url).toMatch(/[?&]rt=auth\.session-expired\.[0-9a-z]+$/);
+		expect(withoutRt(url)).toBe(
+			'https://auth.autional.local/demo/login?redirect=' +
+				encodeURIComponent('https://auth.autional.local/demo/dashboard') +
+				'&from_requireauth=1',
+		);
+	});
+});
+
+describe('refreshToken onFailure 处置', () => {
+	it("'clear'：刷新失败只清理会话，不做任何导航（导航权交调用方）", async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-opaque-1', isAuthenticated: true });
+		mockPost.mockRejectedValue(new Error('refresh rejected'));
+
+		const at = await AuthService.refreshToken({ onFailure: 'clear' });
+
+		expect(at).toBeNull();
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it("'none'：刷新失败零副作用（会话保留、不导航）", async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-opaque-1', isAuthenticated: true });
+		mockPost.mockRejectedValue(new Error('refresh rejected'));
+
+		const at = await AuthService.refreshToken({ onFailure: 'none' });
+
+		expect(at).toBeNull();
+		expect(useAuthStore.getState().accessToken).toBe('at-old');
+		expect(useAuthStore.getState().isAuthenticated).toBe(true);
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+});