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

package/src/auth/__tests__/jwt-payload.test.ts

@@ -0,0 +1,49 @@
+// @vitest-environment jsdom
+// PL-70 回归锁：JWT 段是 base64url（`-`/`_` 替代 `+`/`/`、无填充），裸 atob 对含 `-`/`_`
+// 的载荷抛 InvalidCharacterError → store.isTokenExpired 误判「已过期」→ 请求拦截器
+// 预判式刷新 → 无 RT 的模拟会话被清会话弹登录。旧套件用 btoa 直造「标准 base64」载荷，
+// 恰好覆盖不到此形态（preflight-refresh.test.ts 的 expiredJwt 即此盲区）。
+import { describe, it, expect } from 'vitest';
+import { decodeJwtPayload } from '../jwt-payload';
+import { isTokenExpired } from '../store';
+
+// 造 base64url 载荷段。pad 连排 9 个 '?'（0x3F）：任意连续 3 个字节位置中恰有一个
+// 全局下标 ≡2 (mod 3)，其 6bit 组 = 低 6 位 111111 → base64 字符 63 → base64url `_`
+// ——保证段内定产 `_`，用例真实覆盖 base64url 形态而非碰运气。
+function makeToken(payload: Record<string, unknown>): { token: string; segment: string } {
+	const json = JSON.stringify({ ...payload, pad: '?????????' });
+	let binary = '';
+	for (const b of Array.from(Buffer.from(json, 'utf8'))) binary += String.fromCharCode(b);
+	const segment = btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+	return { token: `eyJhbGciOiJIUzI1NiJ9.${segment}.sig`, segment };
+}
+
+describe('decodeJwtPayload（base64url 归一化）', () => {
+	it('含 -/_ 的 base64url 载荷可解，且非 ASCII 正确还原', () => {
+		const { token, segment } = makeToken({ exp: 4102444800, n: 'ÿ中文' });
+		expect(segment).toMatch(/[-_]/);
+		const payload = decodeJwtPayload(token);
+		expect(payload?.n).toBe('ÿ中文');
+		expect(payload?.exp).toBe(4102444800);
+	});
+
+	it('畸形输入 → null（不抛）', () => {
+		expect(decodeJwtPayload('not-a-jwt')).toBeNull();
+		expect(decodeJwtPayload('a.b')).toBeNull();
+		expect(decodeJwtPayload('a.!!!.c')).toBeNull();
+		expect(decodeJwtPayload('a.' + btoa('not json') + '.c')).toBeNull();
+	});
+
+	it('isTokenExpired：base64url 载荷 + 未来 exp → false（旧实现误判 true 的事故形态）', () => {
+		const exp = Math.floor(Date.now() / 1000) + 3600;
+		const { token, segment } = makeToken({ exp, n: 'ÿ' });
+		expect(segment).toMatch(/[-_]/);
+		expect(isTokenExpired(token)).toBe(false);
+	});
+
+	it('isTokenExpired：过期 exp → true；畸形 token → true', () => {
+		const { token } = makeToken({ exp: Math.floor(Date.now() / 1000) - 60, n: 'ÿ' });
+		expect(isTokenExpired(token)).toBe(true);
+		expect(isTokenExpired('not-a-jwt')).toBe(true);
+	});
+});

package/src/auth/__tests__/logout-redirect.test.ts

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+// U350 回归锁：logout(redirectTo) 接通导航语义 —— 先清会话（await AuthService.logout()），
+// 再整页前往（traceRedirect assign）；无参调用保持「仅清会话、导航交调用方」。
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { logoutSpy, traceRedirectSpy } = vi.hoisted(() => ({
+	logoutSpy: vi.fn(async () => {}),
+	traceRedirectSpy: vi.fn(),
+}));
+
+vi.mock('../service', () => ({
+	AuthService: { logout: logoutSpy },
+}));
+vi.mock('../auth-trace', () => ({
+	traceRedirect: traceRedirectSpy,
+}));
+
+import { logout } from '../store';
+
+describe('U350: shared logout(redirectTo) 导航语义', () => {
+	beforeEach(() => {
+		logoutSpy.mockClear();
+		traceRedirectSpy.mockClear();
+	});
+
+	it('带 redirectTo：先清会话，再整页前往（reason=logout, assign）', async () => {
+		await logout('/auth/acme-corp/login?account_deleted=true');
+		expect(logoutSpy).toHaveBeenCalledTimes(1);
+		expect(traceRedirectSpy).toHaveBeenCalledWith(
+			'/auth/acme-corp/login?account_deleted=true',
+			{ reason: 'logout', assign: true },
+		);
+		// 顺序锁：导航必须发生在会话清理之后（先终结会话再离开）
+		expect(logoutSpy.mock.invocationCallOrder[0]).toBeLessThan(
+			traceRedirectSpy.mock.invocationCallOrder[0],
+		);
+	});
+
+	it('无参：仅清会话、不导航（程序性调用方不受影响）', async () => {
+		await logout();
+		expect(logoutSpy).toHaveBeenCalledTimes(1);
+		expect(traceRedirectSpy).not.toHaveBeenCalled();
+	});
+});

package/src/auth/__tests__/logout-revoke.test.ts

@@ -0,0 +1,219 @@
+// @vitest-environment jsdom
+// ============================================================
+// AUTH-15：登出吊销分链（identity vs OAuth PKCE）——
+//  ① OAuth 链（不透明 rt + client_id）→ oauth revoke ×2（at/rt）带 client_id
+//  ② identity 链（JWT rt / 无 client_id）→ identity /auth/logout 携 Bearer AT
+//  ③ JWT rt + 持久 client_id 仍走 identity（镜像 refreshToken 分链判据）
+//  ④ AUTH-08 登出卫生：localStorage 四键 + OAuth 预置物 + trace 缓冲
+//  ⑤ 吊销失败 → trace 留痕 failed（HTTP status / network-error）且 logout 仍 resolve
+// ============================================================
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { mockCtx, mockClearAuth, mockTraceEvent, mockTraceClear, mockDiscard, mockBffLogout, mockPost } =
+	vi.hoisted(() => ({
+		mockCtx: {
+			accessToken: null as string | null,
+			refreshToken: null as string | null,
+			clientId: '',
+		},
+		mockClearAuth: vi.fn(),
+		mockTraceEvent: vi.fn(),
+		mockTraceClear: vi.fn(),
+		mockDiscard: vi.fn(),
+		mockBffLogout: vi.fn(),
+		mockPost: vi.fn(),
+	}));
+
+vi.mock('../store', () => ({
+	useAuthStore: {
+		getState: () => ({
+			clearAuth: mockClearAuth,
+			user: null,
+			isAuthenticated: false,
+			currentTenantId: null,
+			tenants: [],
+			permissions: [],
+			setTokens: vi.fn(),
+			setTenants: vi.fn(),
+			setPermissions: vi.fn(),
+			setCurrentTenant: vi.fn(),
+		}),
+	},
+	getAccessToken: () => mockCtx.accessToken,
+	getRefreshToken: () => mockCtx.refreshToken,
+	getCurrentRole: () => null,
+	isTokenExpired: () => false,
+	loginWithTokens: vi.fn(),
+}));
+
+vi.mock('../roles', () => ({
+	buildLoginUrl: vi.fn(() => 'https://auth.example.com/login'),
+	isAuthLoginSurface: vi.fn(() => false),
+}));
+
+vi.mock('../auth-trace', () => ({
+	traceClear: mockTraceClear,
+	traceEvent: mockTraceEvent,
+	traceRedirect: vi.fn(),
+}));
+
+vi.mock('../oauth-client-id-store', () => ({
+	resolveClientIdForSession: () => mockCtx.clientId,
+}));
+
+vi.mock('../oauth-login', () => ({
+	discardPendingOAuthLogin: mockDiscard,
+}));
+
+vi.mock('../api/bff-client', () => ({
+	bffLogout: mockBffLogout,
+}));
+
+vi.mock('../../config', () => ({
+	getApiBaseUrl: () => '/bff',
+}));
+
+vi.mock('axios', () => ({
+	default: { post: mockPost },
+}));
+
+import { AuthService } from '../service';
+
+const JWT_RT = 'eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1MSJ9.sig';
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mockCtx.accessToken = null;
+	mockCtx.refreshToken = null;
+	mockCtx.clientId = '';
+	mockPost.mockResolvedValue({ data: {} });
+	localStorage.clear();
+});
+
+describe('AuthService.logout 分链吊销（AUTH-15）', () => {
+	it('OAuth 链（不透明 rt + client_id）→ oauth revoke ×2 带 client_id，不打 identity logout', async () => {
+		mockCtx.accessToken = 'at-opaque';
+		mockCtx.refreshToken = 'rt-opaque';
+		mockCtx.clientId = 'cid-1';
+
+		await AuthService.logout();
+
+		expect(mockPost).toHaveBeenCalledTimes(2);
+		const [url0, body0, cfg0] = mockPost.mock.calls[0];
+		expect(url0).toBe('/bff/oauth/api/v1/oauth/revoke');
+		const p0 = new URLSearchParams(body0 as string);
+		expect(p0.get('token')).toBe('at-opaque');
+		expect(p0.get('token_type_hint')).toBe('access_token');
+		expect(p0.get('client_id')).toBe('cid-1');
+		expect((cfg0 as any).headers['Content-Type']).toBe('application/x-www-form-urlencoded');
+
+		const [url1, body1] = mockPost.mock.calls[1];
+		expect(url1).toBe('/bff/oauth/api/v1/oauth/revoke');
+		const p1 = new URLSearchParams(body1 as string);
+		expect(p1.get('token')).toBe('rt-opaque');
+		expect(p1.get('token_type_hint')).toBe('refresh_token');
+		expect(p1.get('client_id')).toBe('cid-1');
+
+		expect(mockPost.mock.calls.some(([u]) => String(u).includes('identity'))).toBe(false);
+		expect(mockTraceEvent).toHaveBeenCalledWith('logout-revoke', {
+			reason: 'oauth-access_token',
+			to: 'ok',
+		});
+		expect(mockTraceEvent).toHaveBeenCalledWith('logout-revoke', {
+			reason: 'oauth-refresh_token',
+			to: 'ok',
+		});
+	});
+
+	it('OAuth 链无 AT（仅 rt）→ 只 revoke refresh_token', async () => {
+		mockCtx.refreshToken = 'rt-opaque';
+		mockCtx.clientId = 'cid-1';
+
+		await AuthService.logout();
+
+		expect(mockPost).toHaveBeenCalledTimes(1);
+		const p = new URLSearchParams(mockPost.mock.calls[0][1] as string);
+		expect(p.get('token')).toBe('rt-opaque');
+		expect(p.get('token_type_hint')).toBe('refresh_token');
+	});
+
+	it('identity 链（JWT rt，无 client_id）→ identity /auth/logout 携 Bearer AT，不打 oauth revoke', async () => {
+		mockCtx.accessToken = 'at-jwt';
+		mockCtx.refreshToken = JWT_RT;
+
+		await AuthService.logout();
+
+		expect(mockPost).toHaveBeenCalledTimes(1);
+		const [url, body, cfg] = mockPost.mock.calls[0];
+		expect(url).toBe('/bff/identity/api/v1/auth/logout');
+		expect(body).toBeNull();
+		expect((cfg as any).headers.Authorization).toBe('Bearer at-jwt');
+		expect(mockTraceEvent).toHaveBeenCalledWith('logout-revoke', { reason: 'identity', to: 'ok' });
+	});
+
+	it('JWT rt + 持久 client_id 仍走 identity（镜像 refreshToken 分链判据）', async () => {
+		mockCtx.accessToken = 'at-jwt';
+		mockCtx.refreshToken = JWT_RT;
+		mockCtx.clientId = 'cid-1';
+
+		await AuthService.logout();
+
+		expect(mockPost).toHaveBeenCalledTimes(1);
+		expect(mockPost.mock.calls[0][0]).toBe('/bff/identity/api/v1/auth/logout');
+	});
+
+	it('仅剩无凭据 rt（identity JWT rt 且无 AT）→ 明示跳过并留痕', async () => {
+		mockCtx.refreshToken = JWT_RT;
+
+		await AuthService.logout();
+
+		expect(mockPost).not.toHaveBeenCalled();
+		expect(mockTraceEvent).toHaveBeenCalledWith('logout-revoke-skipped', {
+			reason: 'no-credential',
+			to: 'ok',
+		});
+	});
+
+	it('AUTH-08 登出卫生：清 localStorage 四键 + OAuth 预置物 + trace 缓冲 + 内存态', async () => {
+		mockCtx.accessToken = 'at-jwt';
+		mockCtx.refreshToken = JWT_RT;
+		localStorage.setItem('autional-auth-v1', 'x');
+		localStorage.setItem('access_token', 'x');
+		localStorage.setItem('refresh_token', 'x');
+		localStorage.setItem('__oauth_bridge_token', 'x');
+
+		await AuthService.logout();
+
+		expect(localStorage.getItem('autional-auth-v1')).toBeNull();
+		expect(localStorage.getItem('access_token')).toBeNull();
+		expect(localStorage.getItem('refresh_token')).toBeNull();
+		expect(localStorage.getItem('__oauth_bridge_token')).toBeNull();
+		expect(mockClearAuth).toHaveBeenCalledTimes(1);
+		expect(mockDiscard).toHaveBeenCalledTimes(1);
+		expect(mockTraceClear).toHaveBeenCalledTimes(1);
+	});
+
+	it('吊销失败（4xx）：trace 留痕 failed（带 HTTP status）且 logout 仍 resolve', async () => {
+		mockCtx.accessToken = 'at-jwt';
+		mockCtx.refreshToken = JWT_RT;
+		mockPost.mockRejectedValueOnce({ response: { status: 401 } });
+
+		await expect(AuthService.logout()).resolves.toBeUndefined();
+		expect(mockTraceEvent).toHaveBeenCalledWith('logout-revoke-failed', {
+			reason: 'identity',
+			to: '401',
+		});
+	});
+
+	it('吊销失败（网络异常，无 response）：to=network-error 且 logout 仍 resolve', async () => {
+		mockCtx.accessToken = 'at-jwt';
+		mockCtx.refreshToken = JWT_RT;
+		mockPost.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+
+		await expect(AuthService.logout()).resolves.toBeUndefined();
+		expect(mockTraceEvent).toHaveBeenCalledWith('logout-revoke-failed', {
+			reason: 'identity',
+			to: 'network-error',
+		});
+	});
+});

package/src/auth/__tests__/oauth-callback-error-codes.test.ts

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+// AUTH-46② 回归锁：handleOAuthCallback 失败路径以 OAuthCallbackError 携带稳定 code
+// （oauth.provider_error / oauth.missing_code / oauth.state_mismatch / oauth.pkce_cleared），
+// 供回调页按 code 映射本地化文案——此前英文裸句（"Missing authorization code" 等）直接落用户屏。
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { mockPost } = vi.hoisted(() => ({ mockPost: vi.fn() }));
+
+vi.mock('../../api/client', () => ({ apiClient: { post: mockPost, get: vi.fn() } }));
+vi.mock('../store', () => ({ loginWithTokens: vi.fn() }));
+vi.mock('../service', () => ({ AuthService: { updateCurrentTenant: vi.fn() } }));
+vi.mock('../oauth-client-id-store', () => ({ persistOAuthClientId: vi.fn() }));
+vi.mock('../auth-trace', () => ({ traceRedirect: vi.fn() }));
+vi.mock('../../config', () => ({ getPortalUrl: () => 'https://auth.example.com' }));
+
+import { handleOAuthCallback, OAuthCallbackError } from '../oauth-login';
+
+async function codeOf(promise: Promise<unknown>): Promise<string> {
+	try {
+		await promise;
+		throw new Error('expected rejection');
+	} catch (e) {
+		expect(e).toBeInstanceOf(OAuthCallbackError);
+		return (e as OAuthCallbackError).code;
+	}
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	sessionStorage.clear();
+});
+
+describe('handleOAuthCallback 错误 code（AUTH-46②）', () => {
+	it('provider error 参数 → oauth.provider_error（description 作 message 保留）', async () => {
+		window.history.replaceState({}, '', '/?error=access_denied&error_description=user+denied');
+		const code = await codeOf(handleOAuthCallback());
+		expect(code).toBe('oauth.provider_error');
+	});
+
+	it('无 code → oauth.missing_code', async () => {
+		window.history.replaceState({}, '', '/?state=%7B%22csrf%22%3A%22a%22%7D');
+		const code = await codeOf(handleOAuthCallback());
+		expect(code).toBe('oauth.missing_code');
+	});
+
+	it('state csrf 不匹配 → oauth.state_mismatch', async () => {
+		sessionStorage.setItem('oauth_state', 'csrf-A');
+		sessionStorage.setItem('oauth_pkce_verifier', 'v-1');
+		window.history.replaceState(
+			{},
+			'',
+			'/?code=c1&state=' + encodeURIComponent(JSON.stringify({ csrf: 'csrf-B' })),
+		);
+		const code = await codeOf(handleOAuthCallback());
+		expect(code).toBe('oauth.state_mismatch');
+	});
+
+	it('state 通过但 PKCE verifier 缺失（刷新清存储）→ oauth.pkce_cleared', async () => {
+		sessionStorage.setItem('oauth_state', 'csrf-A');
+		window.history.replaceState(
+			{},
+			'',
+			'/?code=c1&state=' + encodeURIComponent(JSON.stringify({ csrf: 'csrf-A' })),
+		);
+		const code = await codeOf(handleOAuthCallback());
+		expect(code).toBe('oauth.pkce_cleared');
+	});
+});

package/src/auth/__tests__/oauth-client-from-slug.test.ts

@@ -0,0 +1,132 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup, waitFor } from '@testing-library/react';
+
+// ============================================================
+// F-W6 判别依据：按 slug 拉取公开 auth-config 的三态
+//  - ok（2xx）
+//  - unknown-slug（**HTTP 404**，租户确定性不存在）→ 门户侧闸门判死
+//  - error（网络/5xx/解析失败）→ 必须 fail-open（not-found，仍走登录漏斗）
+// 契约来源：identity public_handler.go GetTenantAuthConfigBySlug ——
+//  租户不存在 → 404 ErrCodeNotFound；已知租户未配 client → 200（client 空）。
+// ============================================================
+
+import {
+	useOAuthClientIdFromUrl,
+	fetchOAuthClientIdBySlug,
+} from '../oauth-client-from-slug';
+
+function setPath(path: string) {
+	window.history.pushState({}, '', path);
+}
+
+function stubFetch(ok: boolean, status: number, body?: unknown) {
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok,
+			status,
+			json: async () => body,
+		}),
+	);
+}
+
+beforeEach(() => {
+	setPath('/acme');
+	delete (window as any).__APP_CONFIG__;
+});
+
+afterEach(() => {
+	cleanup();
+	vi.unstubAllGlobals();
+});
+
+describe('useOAuthClientIdFromUrl（三态判别）', () => {
+	it('HTTP 404 → unknown-slug（确定性不存在，带 slug）', async () => {
+		stubFetch(false, 404);
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('unknown-slug'));
+		expect(result.current).toMatchObject({ status: 'unknown-slug', slug: 'acme' });
+		expect(fetch).toHaveBeenCalledWith(expect.stringContaining('by-slug/acme'));
+	});
+
+	it('HTTP 500 → not-found（fail-open，不得判死；回归锁）', async () => {
+		stubFetch(false, 500);
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('not-found'));
+	});
+
+	it('网络异常 → not-found（fail-open）', async () => {
+		vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network down')));
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('not-found'));
+	});
+
+	it('200 + data.oauthClientId（camel）→ resolved', async () => {
+		stubFetch(true, 200, { data: { oauthClientId: 'cid-1', tenantId: 't1' } });
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('resolved'));
+		expect(result.current).toMatchObject({
+			status: 'resolved',
+			slug: 'acme',
+			clientId: 'cid-1',
+			config: { tenantId: 't1' },
+		});
+	});
+
+	it('200 + 扁平 oauth_client_id（snake）→ resolved', async () => {
+		stubFetch(true, 200, { oauth_client_id: 'cid-snake' });
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('resolved'));
+		expect(result.current).toMatchObject({ status: 'resolved', clientId: 'cid-snake' });
+	});
+
+	it('200 但无 client（已知租户未配）→ not-found（不误判 unknown-slug）', async () => {
+		stubFetch(true, 200, { data: { tenantId: 't1' } });
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('not-found'));
+	});
+
+	it('根路径无 slug → not-found 且不发请求', async () => {
+		setPath('/');
+		stubFetch(true, 200, { data: { oauthClientId: 'cid-1' } });
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('not-found'));
+		expect(fetch).not.toHaveBeenCalled();
+	});
+
+	it('env 固定 client（admin-console 旁路）→ not-found 且不发请求', async () => {
+		setPath('/users');
+		(window as any).__APP_CONFIG__ = { VITE_OAUTH_CLIENT_ID: 'cid-env' };
+		stubFetch(true, 200, { data: { oauthClientId: 'cid-1' } });
+		const { result } = renderHook(() => useOAuthClientIdFromUrl());
+
+		await waitFor(() => expect(result.current.status).toBe('not-found'));
+		expect(fetch).not.toHaveBeenCalled();
+	});
+});
+
+describe('fetchOAuthClientIdBySlug（非 hook 版本，登录页回源）', () => {
+	it('200 + client → 返回 clientId', async () => {
+		stubFetch(true, 200, { data: { oauthClientId: 'cid-1' } });
+		await expect(fetchOAuthClientIdBySlug('acme')).resolves.toBe('cid-1');
+	});
+
+	it('404 → null', async () => {
+		stubFetch(false, 404);
+		await expect(fetchOAuthClientIdBySlug('acme')).resolves.toBeNull();
+	});
+
+	it('网络异常 → null', async () => {
+		vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network down')));
+		await expect(fetchOAuthClientIdBySlug('acme')).resolves.toBeNull();
+	});
+});

package/src/auth/__tests__/oauth-initiate-stay.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ============================================================
+// AUTH-03/08：initiateOAuthLogin 的「停留」语义与防重入窗口
+//  - onStay 转发给调用方（RequireAuth 据此渲染恢复态）并清零本次预置物
+//  - 「停留」取消待重试定时器：窗口过期后不再自动把用户弹走
+//  - force=true 跳过 10s 防重入窗口（恢复态「前往登录」按钮用）
+// ============================================================
+
+const { mockTrace, mockPersistCid, mockGeneratePKCE } = vi.hoisted(() => ({
+	mockTrace: vi.fn(),
+	mockPersistCid: vi.fn(),
+	mockGeneratePKCE: vi.fn(() => Promise.resolve({ verifier: 'v-1', challenge: 'c-1' })),
+}));
+
+vi.mock('../../api/client', () => ({ apiClient: { post: vi.fn(), get: vi.fn() } }));
+vi.mock('../store', () => ({ loginWithTokens: vi.fn() }));
+vi.mock('../service', () => ({ AuthService: { updateCurrentTenant: vi.fn() } }));
+vi.mock('../oauth-client-id-store', () => ({ persistOAuthClientId: mockPersistCid }));
+vi.mock('../auth-trace', () => ({ traceRedirect: mockTrace }));
+vi.mock('../pkce', () => ({ generatePKCE: () => mockGeneratePKCE() }));
+vi.mock('../../config', () => ({ getPortalUrl: () => 'https://auth.example.com' }));
+
+import { initiateOAuthLogin, discardPendingOAuthLogin } from '../oauth-login';
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	sessionStorage.clear();
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe('initiateOAuthLogin「停留」与防重入（AUTH-03/08）', () => {
+	it('「停留」→ onStay 转发 + 本次预置物全清（state/verifier/cid/init_ts）', async () => {
+		const onStay = vi.fn();
+		await initiateOAuthLogin('cid-1', 'https://user.example.com/x', { onStay });
+
+		expect(mockTrace).toHaveBeenCalledTimes(1);
+		const opts = mockTrace.mock.calls[0][1];
+		expect(opts.kind).toBe('interstitial');
+		expect(typeof opts.onStay).toBe('function');
+		// 发起时预置物就位
+		expect(sessionStorage.getItem('oauth_state')).toBeTruthy();
+		expect(sessionStorage.getItem('oauth_pkce_verifier')).toBe('v-1');
+		expect(sessionStorage.getItem('oauth_client_id')).toBe('cid-1');
+		expect(sessionStorage.getItem('oauth_init_ts')).toBeTruthy();
+
+		opts.onStay();
+
+		expect(onStay).toHaveBeenCalledTimes(1);
+		expect(sessionStorage.getItem('oauth_state')).toBeNull();
+		expect(sessionStorage.getItem('oauth_pkce_verifier')).toBeNull();
+		expect(sessionStorage.getItem('oauth_client_id')).toBeNull();
+		expect(sessionStorage.getItem('oauth_init_ts')).toBeNull();
+	});
+
+	it('10s 防重入窗口内默认被抑制（无跳转）；force=true 直通', async () => {
+		sessionStorage.setItem('oauth_init_ts', String(Date.now()));
+
+		await initiateOAuthLogin('cid-1');
+		expect(mockTrace).not.toHaveBeenCalled();
+
+		await initiateOAuthLogin('cid-1', undefined, { force: true });
+		expect(mockTrace).toHaveBeenCalledTimes(1);
+	});
+
+	it('「停留」取消待重试定时器：窗口过期后不再自动发起', async () => {
+		vi.useFakeTimers();
+		sessionStorage.setItem('oauth_init_ts', String(Date.now()));
+
+		// 窗口内首次调用被抑制，安排窗口过期后的自动重试
+		await initiateOAuthLogin('cid-1');
+		expect(mockTrace).not.toHaveBeenCalled();
+
+		// 窗口过期 → 自动重试真正发起，拿到本轮的 onStay
+		await vi.advanceTimersByTimeAsync(10200);
+		expect(mockTrace).toHaveBeenCalledTimes(1);
+		const opts = mockTrace.mock.calls[0][1];
+		opts.onStay();
+
+		// 预置物清零 + 定时器已取消：再次调用立即发起（不被窗口吞、无遗留重试）
+		mockTrace.mockClear();
+		await initiateOAuthLogin('cid-1');
+		expect(mockTrace).toHaveBeenCalledTimes(1);
+		await vi.advanceTimersByTimeAsync(15000);
+		expect(mockTrace).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe('discardPendingOAuthLogin（AUTH-08 会话卫生，登出/停留共用）', () => {
+	it('清 sessionStorage 四键 + 取消待重试定时器', async () => {
+		vi.useFakeTimers();
+		sessionStorage.setItem('oauth_init_ts', String(Date.now()));
+
+		// 窗口内首次调用被抑制 → 安排窗口过期后的自动重试
+		await initiateOAuthLogin('cid-1');
+		expect(mockTrace).not.toHaveBeenCalled();
+
+		// 模拟发起中途残留的预置物
+		sessionStorage.setItem('oauth_state', 's-1');
+		sessionStorage.setItem('oauth_pkce_verifier', 'v-1');
+		sessionStorage.setItem('oauth_client_id', 'cid-1');
+
+		discardPendingOAuthLogin();
+
+		expect(sessionStorage.getItem('oauth_state')).toBeNull();
+		expect(sessionStorage.getItem('oauth_pkce_verifier')).toBeNull();
+		expect(sessionStorage.getItem('oauth_client_id')).toBeNull();
+		expect(sessionStorage.getItem('oauth_init_ts')).toBeNull();
+
+		// 重试定时器已取消：窗口过期后不再自动发起
+		await vi.advanceTimersByTimeAsync(15000);
+		expect(mockTrace).not.toHaveBeenCalled();
+	});
+});