@autional-cn/shared 0.1.0-rc.2 → 0.1.0-rc.4

package/src/auth/auth-trace.ts

@@ -0,0 +1,473 @@
+/**
+ * authTrace —— auth 整页跳转的统一出口与三层可观测（#48）。
+ *
+ * 三层：
+ *  ① interstitial 提示：**被动**整页跳转（会话终结 / 未认证深链）执行前显示提示条
+ *     （原因 + 目标 host + 停留 / 立即前往），短延迟后自动前往。「停留」取消本次跳转；
+ *     页面数据面虽已失效，但用户知情（消除「静默弹走」）。
+ *  ② confirm 确认页：`?debug=auth`（或 __authTrace.on()）时所有整页跳转不自动执行，
+ *     停在遮罩确认页（跳转详情 + 最近 trace 列表 + 继续 / 留）。debug 标志随跳转
+ *     跨站透传，排障可全程跟随。
+ *  ③ 结构化日志：`[auth-trace]` console 行 + sessionStorage 环形缓冲（跨 SPA 路由、
+ *     同 tab 存活）+ `?rt=` 跨站面包屑（目标 URL 追加，下游站读取接续）+
+ *     `__authTrace.dump()` 一键导出（排障取证）。
+ *
+ * kind 语义（提示层的适用面）：
+ *  - 'interstitial'：被动跳转（会话终结 / buildLoginUrl 弹登录）→ 提示 + 延迟（可停留）。
+ *  - 'funnel'（缺省）：预期漏斗（裸根 → brand / 登出 / OAuth 发起与回跳）→ 静默直跳，
+ *    仅记 trace（用户主动或流程本身的必经步骤，加延迟只拖慢）。
+ *  - debug 模式不分 kind，一律确认页。
+ *
+ * 隐私红线：缓冲与面包屑中的 URL 一律剥除凭据类 query（token/code/state 等），
+ * 不落任何 PII。模块零依赖（不 import React / 各站设施），显式调用即用。
+ */
+
+const BUFFER_KEY = 'auth-trace-v1';
+const DEBUG_KEY = 'auth-trace-debug';
+const RT_PARAM = 'rt';
+const DEBUG_PARAM = 'debug';
+const DEBUG_VALUE = 'auth';
+const BUFFER_LIMIT = 50;
+const INTERSTITIAL_DELAY_MS = 1500;
+const Z_INDEX = '2147483000';
+
+/** URL query 中不得进入 trace 缓冲的凭据类键（前缀匹配）。 */
+const SENSITIVE_KEYS = ['token', 'access_token', 'refresh_token', 'id_token', 'code', 'state', 'secret', 'password'];
+
+export interface AuthTraceEntry {
+	/** epoch ms */
+	t: number;
+	/** 事件类型：redirect / handoff / stay / suppressed / error-exit / … */
+	ev: string;
+	reason?: string;
+	from?: string;
+	to?: string;
+}
+
+export interface AuthTraceRedirectOptions {
+	reason: string;
+	kind?: 'interstitial' | 'funnel';
+	/** true 用 location.href（新增历史），缺省 false 用 location.replace */
+	assign?: boolean;
+	/** 覆盖缺省延迟（ms），仅 interstitial 生效 */
+	delayMs?: number;
+}
+
+function isBrowser(): boolean {
+	return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+function station(): string {
+	if (!isBrowser()) return 'ssr';
+	return window.location.hostname.split('.')[0] || 'unknown';
+}
+
+function isZh(): boolean {
+	if (!isBrowser()) return false;
+	return (document.documentElement.lang || '').toLowerCase().startsWith('zh');
+}
+
+/** 剥除 URL 中的凭据类 query 参数（前缀命中 SENSITIVE_KEYS 即剥），保留其余。 */
+function sanitizeUrl(raw: string): string {
+	try {
+		const u = new URL(raw, isBrowser() ? window.location.origin : 'https://x.invalid');
+		for (const key of Array.from(u.searchParams.keys())) {
+			if (SENSITIVE_KEYS.some((s) => key.toLowerCase() === s || key.toLowerCase().startsWith(`${s}_`))) {
+				u.searchParams.delete(key);
+			}
+		}
+		return u.toString();
+	} catch {
+		return raw.split(/[?#]/)[0];
+	}
+}
+
+// ---------------------------------------------------------------- 缓冲（环形）
+
+let bufferLoaded = false;
+let buffer: AuthTraceEntry[] = [];
+
+function readBuffer(): AuthTraceEntry[] {
+	if (!isBrowser()) return [];
+	if (!bufferLoaded) {
+		bufferLoaded = true;
+		try {
+			const raw = sessionStorage.getItem(BUFFER_KEY);
+			const parsed = raw ? JSON.parse(raw) : [];
+			buffer = Array.isArray(parsed) ? parsed.slice(-BUFFER_LIMIT) : [];
+		} catch {
+			buffer = [];
+		}
+	}
+	return buffer;
+}
+
+function writeBuffer(): void {
+	if (!isBrowser()) return;
+	try {
+		sessionStorage.setItem(BUFFER_KEY, JSON.stringify(buffer.slice(-BUFFER_LIMIT)));
+	} catch {
+		// 存储受限（隐私模式 / 配额）时静默降级为仅 console
+	}
+}
+
+function push(ev: string, extra?: Partial<AuthTraceEntry>): AuthTraceEntry {
+	const entry: AuthTraceEntry = { t: Date.now(), ev, ...extra };
+	readBuffer().push(entry);
+	if (buffer.length > BUFFER_LIMIT) buffer = buffer.slice(-BUFFER_LIMIT);
+	writeBuffer();
+	if (isBrowser()) {
+		// eslint-disable-next-line no-console
+		console.info('[auth-trace]', entry.ev, entry.reason ?? '', entry.to ?? '');
+	}
+	return entry;
+}
+
+// ---------------------------------------------------------------- debug 与水印
+
+function readRTP(): string | null {
+	if (!isBrowser()) return null;
+	try {
+		return new URLSearchParams(window.location.search).get(RT_PARAM);
+	} catch {
+		return null;
+	}
+}
+
+function inDebug(): boolean {
+	if (!isBrowser()) return false;
+	try {
+		if (new URLSearchParams(window.location.search).get(DEBUG_PARAM) === DEBUG_VALUE) return true;
+		return sessionStorage.getItem(DEBUG_KEY) === '1';
+	} catch {
+		return false;
+	}
+}
+
+let initialized = false;
+
+/** 懒初始化：吸收跨站面包屑（?rt=）与 debug 标志；同 URL 重复调用无副作用。 */
+function ensureInit(): void {
+	if (!isBrowser() || initialized) return;
+	initialized = true;
+
+	let urlDebug = false;
+	try {
+		urlDebug = new URLSearchParams(window.location.search).get(DEBUG_PARAM) === DEBUG_VALUE;
+		if (urlDebug) sessionStorage.setItem(DEBUG_KEY, '1');
+	} catch {
+		/* noop */
+	}
+
+	const rt = readRTP();
+	if (rt) {
+		const [prevStation, prevReason, prevTs] = rt.split('.');
+		if (prevStation && prevReason) {
+			push('handoff', {
+				from: `${prevStation}@${prevTs ? parseInt(prevTs, 36) : ''}`,
+				reason: prevReason,
+			});
+		}
+	}
+
+	(window as any).__authTrace = {
+		version: 1,
+		dump: traceDump,
+		entries: () => readBuffer().slice(),
+		on: () => {
+			try {
+				sessionStorage.setItem(DEBUG_KEY, '1');
+			} catch {
+				/* noop */
+			}
+			return 'auth-trace debug ON（整页跳转将停在确认页；随跳转跨站透传）';
+		},
+		off: () => {
+			try {
+				sessionStorage.removeItem(DEBUG_KEY);
+			} catch {
+				/* noop */
+			}
+			return 'auth-trace debug OFF';
+		},
+	};
+
+	if (urlDebug || rt) {
+		// eslint-disable-next-line no-console
+		console.info('[auth-trace] station', station(), urlDebug ? '(debug=on)' : '', rt ? `(handoff from ${rt.split('.')[0]})` : '');
+	}
+}
+
+// ---------------------------------------------------------------- 目标 URL 装饰
+
+/** 目标 URL 追加 rt=（本站 + 原因 + 时间）与 debug 透传（debug 开启时）。 */
+function decorateTarget(target: string, reason: string): string {
+	if (!isBrowser()) return target;
+	try {
+		const u = new URL(target, window.location.origin);
+		if (!u.searchParams.has(RT_PARAM)) {
+			u.searchParams.set(RT_PARAM, `${station()}.${reason}.${Date.now().toString(36)}`);
+		}
+		if (inDebug() && !u.searchParams.has(DEBUG_PARAM)) {
+			u.searchParams.set(DEBUG_PARAM, DEBUG_VALUE);
+		}
+		return u.toString();
+	} catch {
+		return target;
+	}
+}
+
+// ---------------------------------------------------------------- 跳转执行
+
+let pending = false;
+
+function go(target: string, assign: boolean): void {
+	pending = true;
+	if (assign) window.location.href = target;
+	else window.location.replace(target);
+}
+
+function removeNode(id: string): void {
+	if (!isBrowser()) return;
+	const el = document.getElementById(id);
+	if (el && el.parentNode) el.parentNode.removeChild(el);
+}
+
+// ---------------------------------------------------------------- 层 ① 提示条
+
+const NOTICE_ID = 'auth-trace-notice';
+
+function reasonText(reason: string): { zh: string; en: string } {
+	const map: Record<string, { zh: string; en: string }> = {
+		'session-expired': { zh: '会话已过期', en: 'Session expired' },
+		unauthenticated: { zh: '需要登录', en: 'Sign-in required' },
+	};
+	return map[reason] ?? { zh: '即将离开本页', en: 'Leaving this page' };
+}
+
+function showInterstitial(target: string, opts: AuthTraceRedirectOptions, onStay: () => void): void {
+	const zh = isZh();
+	const text = reasonText(opts.reason);
+	const delay = opts.delayMs ?? INTERSTITIAL_DELAY_MS;
+
+	removeNode(NOTICE_ID);
+	const box = document.createElement('div');
+	box.id = NOTICE_ID;
+	box.setAttribute('role', 'status');
+	box.style.cssText = [
+		'position:fixed',
+		'left:50%',
+		'bottom:24px',
+		'transform:translateX(-50%)',
+		`z-index:${Z_INDEX}`,
+		'display:flex',
+		'align-items:center',
+		'gap:12px',
+		'max-width:calc(100vw - 32px)',
+		'padding:10px 14px',
+		'border-radius:8px',
+		'background:rgba(17,24,39,.94)',
+		'color:#f9fafb',
+		'font-size:13px',
+		'line-height:1.4',
+		'font-family:system-ui,-apple-system,sans-serif',
+		'box-shadow:0 8px 24px rgba(0,0,0,.28)',
+	].join(';');
+
+	const label = document.createElement('span');
+	label.textContent = zh
+		? `${text.zh}，即将前往登录（${delay / 1000} 秒后自动跳转）`
+		: `${text.en} — redirecting to sign-in in ${delay / 1000}s`;
+	box.appendChild(label);
+
+	const mkButton = (txt: string, primary: boolean, onClick: () => void) => {
+		const b = document.createElement('button');
+		b.type = 'button';
+		b.textContent = txt;
+		b.style.cssText = [
+			'border:0',
+			'border-radius:6px',
+			'padding:5px 10px',
+			'font-size:13px',
+			'cursor:pointer',
+			primary ? 'background:#2563eb;color:#fff' : 'background:rgba(255,255,255,.14);color:#f9fafb',
+		].join(';');
+		b.addEventListener('click', onClick);
+		return b;
+	};
+
+	const timer = setTimeout(() => {
+		removeNode(NOTICE_ID);
+		go(target, !!opts.assign);
+	}, delay);
+
+	box.appendChild(mkButton(zh ? '停留' : 'Stay', false, () => {
+		clearTimeout(timer);
+		removeNode(NOTICE_ID);
+		onStay();
+	}));
+	box.appendChild(mkButton(zh ? '立即前往' : 'Go now', true, () => {
+		clearTimeout(timer);
+		removeNode(NOTICE_ID);
+		go(target, !!opts.assign);
+	}));
+
+	document.body.appendChild(box);
+}
+
+// ---------------------------------------------------------------- 层 ② 确认页
+
+const CONFIRM_ID = 'auth-trace-confirm';
+
+function showConfirm(target: string, opts: AuthTraceRedirectOptions, onStay: () => void): void {
+	const zh = isZh();
+	removeNode(CONFIRM_ID);
+
+	const overlay = document.createElement('div');
+	overlay.id = CONFIRM_ID;
+	overlay.style.cssText = [
+		'position:fixed',
+		'inset:0',
+		`z-index:${Z_INDEX}`,
+		'display:flex',
+		'align-items:center',
+		'justify-content:center',
+		'background:rgba(15,23,42,.55)',
+		'font-family:system-ui,-apple-system,sans-serif',
+	].join(';');
+
+	const card = document.createElement('div');
+	card.style.cssText = [
+		'width:min(560px,calc(100vw - 40px))',
+		'max-height:80vh',
+		'overflow:auto',
+		'background:#fff',
+		'color:#111827',
+		'border-radius:10px',
+		'padding:18px 20px',
+		'box-shadow:0 20px 48px rgba(0,0,0,.32)',
+		'font-size:13px',
+	].join(';');
+
+	const title = document.createElement('h2');
+	title.textContent = zh ? '整页跳转确认（authTrace debug）' : 'Full-page redirect (authTrace debug)';
+	title.style.cssText = 'margin:0 0 10px;font-size:15px;font-weight:600';
+	card.appendChild(title);
+
+	const detail = document.createElement('pre');
+	detail.textContent = [
+		`reason: ${opts.reason}`,
+		`kind:   ${opts.kind ?? 'funnel'}`,
+		`from:   ${sanitizeUrl(window.location.href)}`,
+		`to:     ${target}`,
+		'',
+		...(readBuffer().slice(-10).map((e) => `${new Date(e.t).toISOString()}  ${e.ev}  ${e.reason ?? ''}  ${e.to ?? e.from ?? ''}`)),
+	].join('\n');
+	detail.style.cssText = [
+		'margin:0 0 14px',
+		'padding:10px',
+		'border-radius:6px',
+		'background:#f3f4f6',
+		'white-space:pre-wrap',
+		'word-break:break-all',
+		'font-size:12px',
+		'line-height:1.5',
+		'max-height:46vh',
+		'overflow:auto',
+	].join(';');
+	card.appendChild(detail);
+
+	const mkButton = (txt: string, primary: boolean, onClick: () => void) => {
+		const b = document.createElement('button');
+		b.type = 'button';
+		b.textContent = txt;
+		b.style.cssText = [
+			primary ? 'background:#2563eb;color:#fff' : 'background:#e5e7eb;color:#111827',
+			'border:0',
+			'border-radius:6px',
+			'padding:7px 14px',
+			'font-size:13px',
+			'cursor:pointer',
+			'margin-right:8px',
+		].join(';');
+		b.addEventListener('click', onClick);
+		return b;
+	};
+
+	card.appendChild(mkButton(zh ? '继续前往' : 'Continue', true, () => {
+		removeNode(CONFIRM_ID);
+		go(target, !!opts.assign);
+	}));
+	card.appendChild(mkButton(zh ? '留在本页' : 'Stay', false, () => {
+		removeNode(CONFIRM_ID);
+		onStay();
+	}));
+
+	overlay.appendChild(card);
+	document.body.appendChild(overlay);
+}
+
+// ---------------------------------------------------------------- 公开 API
+
+/**
+ * 统一整页跳转出口：记 trace →（debug 时）确认页 →（interstitial 时）提示条 →
+ * 执行 location.replace/href。
+ *
+ * 重入语义：pending 期间新的 interstitial 请求被抑制（记 suppressed，防双提示/双跳）；
+ * funnel 请求不被抑制（用户主动 / 流程必经，优先且覆盖 pending）。
+ */
+export function traceRedirect(target: string, opts: AuthTraceRedirectOptions): void {
+	if (!isBrowser()) return;
+	ensureInit();
+	const kind = opts.kind ?? 'funnel';
+	const decorated = decorateTarget(target, opts.reason);
+	const from = sanitizeUrl(window.location.href);
+
+	if (pending && kind === 'interstitial') {
+		push('suppressed', { reason: opts.reason, from, to: sanitizeUrl(decorated) });
+		return;
+	}
+
+	push('redirect', { reason: opts.reason, from, to: sanitizeUrl(decorated) });
+
+	const onStay = () => {
+		pending = false;
+		push('stay', { reason: opts.reason, from, to: sanitizeUrl(decorated) });
+	};
+
+	if (inDebug()) {
+		pending = true;
+		showConfirm(decorated, opts, onStay);
+		return;
+	}
+
+	if (kind === 'interstitial') {
+		pending = true;
+		showInterstitial(decorated, opts, onStay);
+		return;
+	}
+
+	go(decorated, !!opts.assign);
+}
+
+/** 记一条非跳转 trace 事件（如 error 页出口、OAuth 链路里程碑）。 */
+export function traceEvent(ev: string, extra?: { reason?: string; from?: string; to?: string }): void {
+	if (!isBrowser()) return;
+	ensureInit();
+	push(ev, extra);
+}
+
+/** 导出全部缓冲 + 环境摘要（`copy(__authTrace.dump())` 取证用）。 */
+export function traceDump(): string {
+	if (!isBrowser()) return '';
+	ensureInit();
+	const header = [
+		`authTrace v1 @${station()}`,
+		`url: ${sanitizeUrl(window.location.href)}`,
+		`debug: ${inDebug() ? 'on' : 'off'}`,
+		`ua: ${navigator.userAgent}`,
+		`entries: ${readBuffer().length}`,
+	];
+	const lines = readBuffer().map((e) => `${new Date(e.t).toISOString()}  ${e.ev}  ${e.reason ?? ''}  ${e.to ?? e.from ?? ''}`);
+	return [...header, '', ...lines].join('\n');
+}

package/src/auth/oauth-login.ts

@@ -14,6 +14,7 @@ import { AuthService } from './service';
 import { generatePKCE } from './pkce';
 import { getPortalUrl } from '../config';
 import { persistOAuthClientId } from './oauth-client-id-store';
+import { traceRedirect } from './auth-trace';
 import type { User } from '../types';
 
 function getAppConfig(): Record<string, string> | undefined {
@@ -157,7 +158,13 @@ export async function initiateOAuthLogin(
 			code_challenge_method: 'S256',
 			state,
 		});
-		window.location.href = `${cfg.authorizeUrl}?${params}`;
+		// interstitial：未认证深链被动弹去登录 → authTrace 提示（可停留）；
+		// 「停留」取消后 10s 防重入窗口过期即失效，用户刷新/再次交互可重新发起。
+		traceRedirect(`${cfg.authorizeUrl}?${params}`, {
+			reason: 'oauth-initiate',
+			kind: 'interstitial',
+			assign: true,
+		});
 	} catch {
 		const params = new URLSearchParams({
 			response_type: 'code',
@@ -166,7 +173,11 @@ export async function initiateOAuthLogin(
 			scope: cfg.scope,
 			state,
 		});
-		window.location.href = `${cfg.authorizeUrl}?${params}`;
+		traceRedirect(`${cfg.authorizeUrl}?${params}`, {
+			reason: 'oauth-initiate',
+			kind: 'interstitial',
+			assign: true,
+		});
 	}
 }
 
@@ -287,5 +298,6 @@ export async function handleOAuthCallback(): Promise<void> {
 	}
 
 	// Full page navigation to the target (auth gateway will route to dashboard)
-	window.location.href = target;
+	// funnel：登录成功回跳（预期行为，静默直跳，assign 保持原语义）；仅记 trace。
+	traceRedirect(target, { reason: 'oauth-callback', assign: true });
 }

package/src/auth/roles.ts

@@ -51,6 +51,22 @@ export function buildLogoutUrl(returnUrl?: string): string {
 	return `${base}/?${redirect}logout=1`;
 }
 
+/**
+ * 当前页是否已是 auth 的「登录承接面」——裸根入口（`/`、`/login`，由入口路由承接）、
+ * `/<slug>/login` 登录页、`/error` 错误页。
+ *
+ * 会话终结（onUnauthorized）时若已停在承接面，整页 replace 不但无益（目标就是本页），
+ * 还会因 buildLoginUrl 的防嵌套截断返回不带 redirect 的本页 —— 把 URL 中的回程目标
+ * 一并丢掉，且构成一次整页闪烁（F-W8b 修复②：存量过期 token 在登录页「静默弹走」）。
+ */
+export function isAuthLoginSurface(): boolean {
+	if (typeof window === 'undefined') return false;
+	const segs = window.location.pathname.split('/').filter(Boolean);
+	if (segs.length === 0) return true; // 裸根 `/`
+	if (segs[0] === 'login' || segs[0] === 'error') return true; // `/login`、`/error`
+	return segs.length === 2 && segs[1] === 'login'; // `/<slug>/login`
+}
+
 export function buildLoginUrl(returnUrl?: string, fromRequireAuth?: boolean): string {
 	const base = getPortalUrl('auth');
 	if (!base) return '/';

package/src/auth/service.ts

@@ -23,13 +23,13 @@ import {
 	isTokenExpired as checkExpired,
 } from './store';
 import { loginWithTokens } from './store';
-import { buildLoginUrl } from './roles';
+import { buildLoginUrl, isAuthLoginSurface } from './roles';
+import { traceRedirect } from './auth-trace';
 import { resolveClientIdForSession } from './oauth-client-id-store';
 import type { User } from '../types';
 
 // ============ Internal State ============
 
-let redirectingToLogin = false;
 let refreshPromise: Promise<string | null> | null = null;
 
 // ============ OAuth PKCE Bootstrap Lock ============
@@ -259,19 +259,30 @@ export const AuthService = {
 	/**
 	 * 刷新 access token。
 	 * 防重入：同一时间只会有一个刷新请求进行中。
-	 * 刷新失败时自动调用 onUnauthorized。
+	 *
+	 * 失败处置（onFailure，缺省 'redirect'）：
+	 * - 'redirect'：onUnauthorized —— 清理 + 引导登录（常规路径）；
+	 * - 'clear'   ：clearSession —— 只清理不导航（调用方自控唯一导航出口，
+	 *               如会话过期横幅 → error 页，避免与整页跳转双跳竞争）；
+	 * - 'none'    ：零副作用静默（尽力续期场景：如过期前 5 分钟的自动续期尝试，
+	 *               失败不清理不打断——会话此刻仍有效，等真正过期再统一处置）。
 	 */
-	refreshToken: async (): Promise<string | null> => {
+	refreshToken: async (opts?: {
+		onFailure?: 'redirect' | 'clear' | 'none';
+	}): Promise<string | null> => {
 		if (refreshPromise) return refreshPromise;
+		const onFailure = opts?.onFailure ?? 'redirect';
+		const handleFailure = () => {
+			if (onFailure === 'redirect') AuthService.onUnauthorized();
+			else if (onFailure === 'clear') AuthService.clearSession();
+		};
 
 		refreshPromise = (async () => {
 			const rt = AuthService.getRefreshToken();
 			if (!rt) {
 				// During OAuth PKCE bootstrap (no token yet), suppress redirect.
 				// RequireAuth will handle OAuth PKCE vs BFF fallback once tenantRoute resolves.
-				if (!_bootstrapLocked) {
-					AuthService.onUnauthorized();
-				}
+				if (!_bootstrapLocked) handleFailure();
 				return null;
 			}
 
@@ -315,7 +326,7 @@ export const AuthService = {
 				return newAT || null;
 			} catch (err) {
 				console.warn('[AuthService] Token refresh failed', (err as Error)?.message || '');
-				AuthService.onUnauthorized();
+				handleFailure();
 				return null;
 			} finally {
 				refreshPromise = null;
@@ -328,14 +339,10 @@ export const AuthService = {
 	// ==================== 401/未授权处理 ====================
 
 	/**
-	 * 处理 401 未授权响应：
-	 * 1. 登出（清除所有状态）
-	 * 2. 重定向到登录页（防重入锁）
+	 * 仅清除会话状态（store + localStorage），不做任何导航。
+	 * 供 silent 刷新失败、以及需要自控导航出口的调用方使用。
 	 */
-	onUnauthorized: (): void => {
-		// Suppress redirect during OAuth PKCE bootstrap — RequireAuth handles it
-		if (_bootstrapLocked) return;
-		// 先清除状态，不等待 logout 的异步吊销
+	clearSession: (): void => {
 		useAuthStore.getState().clearAuth();
 		if (typeof window !== 'undefined') {
 			// 清除 localStorage（同步，立即生效）
@@ -343,12 +350,32 @@ export const AuthService = {
 			localStorage.removeItem('access_token');
 			localStorage.removeItem('refresh_token');
 		}
+	},
+
+	/**
+	 * 处理 401 未授权响应：
+	 * 1. 清除所有状态（clearSession）
+	 * 2. 经 authTrace 提示（会话已过期 → 即将前往登录，可停留）后整页弹登录页
+	 *
+	 * 例外：已在 auth 登录承接面（裸根入口 / `/<slug>/login` / `/error`）时只清理不导航 ——
+	 * 目标就是当前页，整页 replace 反而会丢掉 URL 里的 redirect 回程目标并造成闪烁
+	 * （F-W8b 修复②）；承接面页面对 401 有自己的收口（登录页落表单、error 页走倒计时）。
+	 *
+	 * 重入抑制在 authTrace 内（pending 单例；并发 401 只提示一次、只跳一次）。
+	 */
+	onUnauthorized: (): void => {
+		// Suppress redirect during OAuth PKCE bootstrap — RequireAuth handles it
+		if (_bootstrapLocked) return;
+		// 先清除状态，不等待 logout 的异步吊销
+		AuthService.clearSession();
 
-		if (!redirectingToLogin && typeof window !== 'undefined') {
-			redirectingToLogin = true;
-			setTimeout(() => {
-				window.location.replace(buildLoginUrl(window.location.href, true));
-			}, 0);
+		if (isAuthLoginSurface()) return;
+
+		if (typeof window !== 'undefined') {
+			traceRedirect(buildLoginUrl(window.location.href, true), {
+				reason: 'session-expired',
+				kind: 'interstitial',
+			});
 		}
 	},
 

package/src/components/RequireAuth.tsx

@@ -1,6 +1,7 @@
 import { useEffect } 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,
@@ -103,8 +104,12 @@ export function RequireAuth({
 		// Cross-domain or no client: redirect to auth-pages login
 		// from_requireauth=1 与 service.ts 的 onUnauthorized 同口径：auth 侧据此先做会话复检
 		// （有会话直接回跳，避免「已登录还被要求再登一次」）
+		// interstitial：未认证深链被动弹登录 → authTrace 提示（可停留）；重入抑制在其内。
 		setTimeout(() => {
-			window.location.replace(buildLoginUrl(window.location.href, true));
+			traceRedirect(buildLoginUrl(window.location.href, true), {
+				reason: 'unauthenticated',
+				kind: 'interstitial',
+			});
 		}, 0);
 	}, [machine.status, tenantRoute]);