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

package/src/auth/__tests__/oauth-login-user-resolution.test.ts

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// 回归（2026-10-03 线上四门户「未登录」）：oauth 服务的 id_token 只含 sub 等标准
+// claim（无 email/username）。修复前 parseUserFromToken(id_token) 的真值结果短路了
+// /auth/me 兜底，store 落残缺 user → UserMenu 显示「未登录」。
+// 另：登录时固定调一次 OIDC userinfo（/oauth/api/v1/oauth/userinfo）合并展示名
+// （nickname→name）+ picture；失败静默降级，不阻断登录。
+
+const { mockPost, mockGet, mockLoginWithTokens, mockUpdateCurrentTenant, mockPersistCid, mockTrace } =
+	vi.hoisted(() => ({
+		mockPost: vi.fn(),
+		mockGet: vi.fn(),
+		mockLoginWithTokens: vi.fn(),
+		mockUpdateCurrentTenant: vi.fn(),
+		mockPersistCid: vi.fn(),
+		mockTrace: vi.fn(),
+	}));
+
+vi.mock('../../api/client', () => ({ apiClient: { post: mockPost, get: mockGet } }));
+vi.mock('../store', () => ({ loginWithTokens: mockLoginWithTokens }));
+vi.mock('../service', () => ({ AuthService: { updateCurrentTenant: mockUpdateCurrentTenant } }));
+vi.mock('../oauth-client-id-store', () => ({ persistOAuthClientId: mockPersistCid }));
+vi.mock('../auth-trace', () => ({ traceRedirect: mockTrace }));
+vi.mock('../../config', () => ({ getPortalUrl: () => 'https://auth.example.com' }));
+
+import { handleOAuthCallback } from '../oauth-login';
+
+function jwt(payload: Record<string, unknown>): string {
+	return `h.${btoa(JSON.stringify(payload))}.s`;
+}
+
+const ACCESS_TOKEN = jwt({ sub: 'u-1', tenant_id: 'tenant-1' });
+const ME_URL = '/identity/api/v1/auth/me';
+const USERINFO_URL = '/oauth/api/v1/oauth/userinfo';
+const ME_USER = {
+	id: 'u-1',
+	username: '',
+	email: 'demo-admin@demo.localhost',
+	status: 'active',
+};
+
+function getUserCalls(url: string) {
+	return mockGet.mock.calls.filter((c) => String(c[0]) === url);
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	sessionStorage.clear();
+	window.history.replaceState({}, '', '/?code=test-code');
+	sessionStorage.setItem('oauth_pkce_verifier', 'verifier-1');
+	sessionStorage.setItem('oauth_client_id', 'cid-1');
+	mockPost.mockResolvedValue({
+		data: { access_token: ACCESS_TOKEN, refresh_token: 'rt-1', id_token: jwt({ sub: 'u-1' }) },
+	});
+	// 默认：/auth/me 返回完整 user；userinfo 返回空（展示名缺省，走回落链）
+	mockGet.mockImplementation((url: string) =>
+		String(url) === USERINFO_URL
+			? Promise.resolve({ data: {} })
+			: Promise.resolve({ data: { ...ME_USER } }),
+	);
+});
+
+describe('handleOAuthCallback 用户信息解析（id_token 缺身份字段回归）', () => {
+	it('id_token 只含 sub → 继续调 /auth/me，落完整 user（不再显示未登录）', async () => {
+		await handleOAuthCallback();
+
+		const meCalls = getUserCalls(ME_URL);
+		expect(meCalls).toHaveLength(1);
+		expect(meCalls[0][1]).toMatchObject({
+			headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
+		});
+		expect(mockLoginWithTokens).toHaveBeenCalledTimes(1);
+		const user = mockLoginWithTokens.mock.calls[0][2];
+		expect(user.email).toBe('demo-admin@demo.localhost');
+		expect(user.id).toBe('u-1');
+	});
+
+	it('id_token 含 email → 直接采信，不调 /auth/me（既有偏好保持）', async () => {
+		mockPost.mockResolvedValue({
+			data: {
+				access_token: ACCESS_TOKEN,
+				refresh_token: 'rt-1',
+				id_token: jwt({ sub: 'u-1', email: 'a@b.c' }),
+			},
+		});
+
+		await handleOAuthCallback();
+
+		expect(getUserCalls(ME_URL)).toHaveLength(0);
+		expect(mockLoginWithTokens.mock.calls[0][2].email).toBe('a@b.c');
+	});
+
+	it('id_token 缺字段且 /auth/me 失败 → access_token JWT 兜底（id 可用）', async () => {
+		mockGet.mockImplementation((url: string) =>
+			String(url) === ME_URL
+				? Promise.reject(new Error('me down'))
+				: Promise.resolve({ data: {} }),
+		);
+
+		await handleOAuthCallback();
+
+		expect(mockLoginWithTokens).toHaveBeenCalledTimes(1);
+		expect(mockLoginWithTokens.mock.calls[0][2].id).toBe('u-1');
+	});
+
+	it('id_token 缺失 → 同样落 /auth/me', async () => {
+		mockPost.mockResolvedValue({
+			data: { access_token: ACCESS_TOKEN, refresh_token: 'rt-1' },
+		});
+
+		await handleOAuthCallback();
+
+		expect(getUserCalls(ME_URL)).toHaveLength(1);
+		expect(mockLoginWithTokens.mock.calls[0][2].email).toBe('demo-admin@demo.localhost');
+	});
+});
+
+describe('handleOAuthCallback userinfo 展示名合并', () => {
+	it('每次登录固定调一次 userinfo，带显式 Bearer（拦截器尚无 token）', async () => {
+		await handleOAuthCallback();
+
+		const calls = getUserCalls(USERINFO_URL);
+		expect(calls).toHaveLength(1);
+		expect(calls[0][1]).toMatchObject({
+			headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
+		});
+	});
+
+	it('id_token 含 email（短路 /auth/me）时 userinfo 仍调用——id_token 永不含展示名', async () => {
+		mockPost.mockResolvedValue({
+			data: {
+				access_token: ACCESS_TOKEN,
+				refresh_token: 'rt-1',
+				id_token: jwt({ sub: 'u-1', email: 'a@b.c' }),
+			},
+		});
+		mockGet.mockImplementation(() => Promise.resolve({ data: { name: 'Demo Admin' } }));
+
+		await handleOAuthCallback();
+
+		expect(mockLoginWithTokens.mock.calls[0][2].displayName).toBe('Demo Admin');
+	});
+
+	it('nickname 合入 displayName（优先于 name，含 trim）', async () => {
+		mockGet.mockImplementation((url: string) =>
+			String(url) === USERINFO_URL
+				? Promise.resolve({ data: { nickname: '  Demo Admin  ', name: 'Demo A. Admin' } })
+				: Promise.resolve({ data: { ...ME_USER } }),
+		);
+
+		await handleOAuthCallback();
+
+		expect(mockLoginWithTokens.mock.calls[0][2].displayName).toBe('Demo Admin');
+	});
+
+	it('无 nickname 时回落 name；picture 合入 avatarUrl', async () => {
+		mockGet.mockImplementation((url: string) =>
+			String(url) === USERINFO_URL
+				? Promise.resolve({ data: { name: 'Demo Admin', picture: 'https://x/p.png' } })
+				: Promise.resolve({ data: { ...ME_USER } }),
+		);
+
+		await handleOAuthCallback();
+
+		const user = mockLoginWithTokens.mock.calls[0][2];
+		expect(user.displayName).toBe('Demo Admin');
+		expect(user.avatarUrl).toBe('https://x/p.png');
+	});
+
+	it('userinfo 失败 → 登录继续，displayName 缺省（消费侧回落 username/email）', async () => {
+		mockGet.mockImplementation((url: string) =>
+			String(url) === USERINFO_URL
+				? Promise.reject(new Error('userinfo down'))
+				: Promise.resolve({ data: { ...ME_USER } }),
+		);
+
+		await handleOAuthCallback();
+
+		expect(mockLoginWithTokens).toHaveBeenCalledTimes(1);
+		const user = mockLoginWithTokens.mock.calls[0][2];
+		expect(user.displayName).toBeUndefined();
+		expect(user.email).toBe('demo-admin@demo.localhost');
+	});
+});

package/src/auth/__tests__/pkce-uniformity.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { generatePKCE } from '../pkce';
+
+// RFC 7636 verifier charset — must stay in sync with generateRandomString in ../pkce.ts
+const CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+const CHAR_SET = new Set(CHARSET.split(''));
+
+describe('generatePKCE (PRNG rejection sampling — no modulo bias)', () => {
+	it('produces RFC 7636-compliant verifier: 64 chars from A-Za-z0-9-._~', async () => {
+		for (let i = 0; i < 50; i++) {
+			const { verifier } = await generatePKCE();
+			expect(verifier).toHaveLength(64);
+			for (const ch of verifier) {
+				expect(CHAR_SET.has(ch), `unexpected char ${ch}`).toBe(true);
+			}
+		}
+	});
+
+	it('verifiers differ across calls (non-deterministic)', async () => {
+		const a = await generatePKCE();
+		const b = await generatePKCE();
+		expect(a.verifier).not.toBe(b.verifier);
+	});
+
+	it('each of the 66 chars is near-uniformly distributed (rejection sampling kills modulo bias)', async () => {
+		// 30k verifiers × 64 chars = 1.92M samples. With uniform distribution the
+		// per-char std dev is ~0.9% of the mean, so ±5% tolerance has ~7σ margin —
+		// never flakes, while a naive `byte % 66` would push chars 58-65 ~22%
+		// below the mean and be caught immediately.
+		const SAMPLES = 30_000;
+		const counts = new Array<number>(66).fill(0);
+		for (let i = 0; i < SAMPLES; i++) {
+			const { verifier } = await generatePKCE();
+			for (const ch of verifier) {
+				counts[CHARSET.indexOf(ch)]++;
+			}
+		}
+		const total = SAMPLES * 64;
+		const expectedFreq = 1 / 66;
+		for (let i = 0; i < 66; i++) {
+			const freq = counts[i] / total;
+			expect(
+				Math.abs(freq - expectedFreq),
+				`char ${CHARSET[i]} deviated ${(((freq - expectedFreq) / expectedFreq) * 100).toFixed(2)}% from uniform`,
+			).toBeLessThan(0.05 * expectedFreq);
+		}
+	}, 30_000);
+});

package/src/auth/__tests__/session-client-id.test.ts

@@ -0,0 +1,147 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ============================================================
+// L6（D8）：刷新分流与登出吊销的 client_id 来源
+//  - 会话内已解析值（localStorage `oauth_client_id`，OAuth 交棒时落库）优先
+//  - env（__APP_CONFIG__.VITE_OAUTH_CLIENT_ID）兜底
+//  - 两者皆无：保持旧行为（落 identity 腿）
+// ============================================================
+
+const { mockPost } = vi.hoisted(() => ({ mockPost: vi.fn() }));
+
+vi.mock('axios', () => ({ default: { post: mockPost } }));
+vi.mock('../../api/bff-client', () => ({ bffLogout: vi.fn(() => Promise.resolve()) }));
+
+import { AuthService } from '../service';
+import { useAuthStore } from '../store';
+import { persistOAuthClientId } from '../oauth-client-id-store';
+
+const OAUTH_REFRESH = '/oauth/api/v1/oauth/refresh';
+const IDENTITY_REFRESH = '/identity/api/v1/auth/refresh';
+const REVOKE = '/oauth/api/v1/oauth/revoke';
+
+function callsTo(fragment: string) {
+	return mockPost.mock.calls.filter((c) => String(c[0]).includes(fragment));
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	localStorage.clear();
+	useAuthStore.setState({ accessToken: null, refreshToken: null, isAuthenticated: false });
+	delete (window as any).__APP_CONFIG__;
+	mockPost.mockResolvedValue({ data: { access_token: 'new-at', refresh_token: 'rt-new' } });
+});
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+describe('AuthService.refreshToken 分流', () => {
+	it('opaque refresh token + 会话内 client_id → 走 OAuth 腿并带上该 client_id', async () => {
+		persistOAuthClientId('cid-from-session');
+		useAuthStore.setState({ refreshToken: 'rt-opaque-abc' });
+
+		const at = await AuthService.refreshToken();
+
+		expect(at).toBe('new-at');
+		const oauthCalls = callsTo(OAUTH_REFRESH);
+		expect(oauthCalls).toHaveLength(1);
+		expect(oauthCalls[0][1]).toEqual({
+			refresh_token: 'rt-opaque-abc',
+			client_id: 'cid-from-session',
+		});
+		expect(callsTo(IDENTITY_REFRESH)).toHaveLength(0);
+	});
+
+	it('无会话值时 env 兜底（VITE_OAUTH_CLIENT_ID）', async () => {
+		(window as any).__APP_CONFIG__ = { VITE_OAUTH_CLIENT_ID: 'cid-from-env' };
+		useAuthStore.setState({ refreshToken: 'rt-opaque-abc' });
+
+		await AuthService.refreshToken();
+
+		expect(callsTo(OAUTH_REFRESH)[0][1]).toEqual({
+			refresh_token: 'rt-opaque-abc',
+			client_id: 'cid-from-env',
+		});
+	});
+
+	it('两者皆无 → 落 identity 腿（形态与接线前一致）', async () => {
+		useAuthStore.setState({ refreshToken: 'rt-opaque-abc' });
+
+		await AuthService.refreshToken();
+
+		expect(callsTo(IDENTITY_REFRESH)).toHaveLength(1);
+		expect(callsTo(OAUTH_REFRESH)).toHaveLength(0);
+	});
+
+	it('JWT refresh token（三段式）恒走 identity 腿，即使会话内有 client_id', async () => {
+		persistOAuthClientId('cid-from-session');
+		useAuthStore.setState({ refreshToken: 'a.b.c' });
+
+		await AuthService.refreshToken();
+
+		expect(callsTo(IDENTITY_REFRESH)).toHaveLength(1);
+		expect(callsTo(OAUTH_REFRESH)).toHaveLength(0);
+	});
+
+	// 回归锁（2026-10-03 线上缺陷：identity 腿响应是标准信封 {code,message,data:{...}}，
+	// 客户端却按扁平解析 ⇒ data.access_token 恒 undefined ⇒ updateTokens 从不执行 ⇒
+	// 预警点横幅 + 到期拿旧 RT 重放 ⇒ 服务端反重放 revoke-all 全量吊销会话）。
+	// 此前测试用扁平 mock 喂两条腿掩盖了信封形状差异，此处锁真实信封。
+	it('identity 腿（三段式 RT）信封响应必须解包：token 落库 + 返回新 AT', async () => {
+		useAuthStore.setState({ refreshToken: 'a.b.c' });
+		mockPost.mockResolvedValue({
+			data: {
+				code: 0,
+				message: 'success',
+				data: { access_token: 'env-at', refresh_token: 'env-rt' },
+				timestamp: 1728000000000,
+			},
+		});
+
+		const at = await AuthService.refreshToken();
+
+		expect(callsTo(IDENTITY_REFRESH)).toHaveLength(1);
+		expect(at).toBe('env-at');
+		expect(useAuthStore.getState().accessToken).toBe('env-at');
+		expect(useAuthStore.getState().refreshToken).toBe('env-rt');
+	});
+
+	it('刷新成功后新 token 落库（updateTokens 链路）', async () => {
+		persistOAuthClientId('cid-from-session');
+		useAuthStore.setState({ refreshToken: 'rt-opaque-abc' });
+
+		await AuthService.refreshToken();
+
+		expect(useAuthStore.getState().accessToken).toBe('new-at');
+		expect(useAuthStore.getState().refreshToken).toBe('rt-new');
+	});
+});
+
+describe('AuthService.logout 吊销', () => {
+	it('access/refresh 两条吊销都带会话内 client_id', async () => {
+		persistOAuthClientId('cid-from-session');
+		useAuthStore.setState({ accessToken: 'at-1', refreshToken: 'rt-opaque-1' });
+
+		await AuthService.logout();
+
+		const revokes = callsTo(REVOKE);
+		expect(revokes).toHaveLength(2);
+		for (const call of revokes) {
+			expect(String(call[1])).toContain('client_id=cid-from-session');
+		}
+		expect(String(revokes[0][1])).toContain('token_type_hint=access_token');
+		expect(String(revokes[1][1])).toContain('token_type_hint=refresh_token');
+	});
+
+	it('登出清 token 但**不清** client_id（部署级取值，非用户私有数据）', async () => {
+		persistOAuthClientId('cid-from-session');
+		useAuthStore.setState({ accessToken: 'at-1', refreshToken: 'rt-opaque-1' });
+
+		await AuthService.logout();
+
+		expect(localStorage.getItem('oauth_client_id')).toBe('cid-from-session');
+		expect(useAuthStore.getState().isAuthenticated).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();
+	});
+});

package/src/auth/__tests__/slug-from-url.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { extractSlugFromPath, registerNonTenantSegments, clearNonTenantSegments } from '../slug-from-url';
+
+describe('extractSlugFromPath', () => {
+	describe('tenant slug patterns', () => {
+		it('extracts slug from /{slug}/admin', () => {
+			expect(extractSlugFromPath('/acme/admin')).toBe('acme');
+		});
+
+		it('extracts slug from /{slug}/developer', () => {
+			expect(extractSlugFromPath('/foo/developer')).toBe('foo');
+		});
+
+		it('extracts slug from /{slug}/security', () => {
+			expect(extractSlugFromPath('/bar/security')).toBe('bar');
+		});
+
+		it('extracts slug from /{slug}/admin/dashboard (3 segments)', () => {
+			expect(extractSlugFromPath('/mycorp/admin/dashboard')).toBe('mycorp');
+		});
+
+		it('extracts slug with dashes and numbers', () => {
+			expect(extractSlugFromPath('/acme-corp-123/admin')).toBe('acme-corp-123');
+		});
+
+		it('extracts slug when followed by portal prefix in path with extra segments', () => {
+			expect(extractSlugFromPath('/tenant1/admin/users/123')).toBe('tenant1');
+		});
+	});
+
+	describe('no slug — returns undefined', () => {
+		it('returns undefined for root /', () => {
+			expect(extractSlugFromPath('/')).toBeUndefined();
+		});
+
+		it('returns admin as slug candidate for /admin (no root portal prefix after domain migration)', () => {
+			expect(extractSlugFromPath('/admin')).toBe('admin');
+		});
+
+		it('returns developer as slug candidate (no longer a root portal after domain migration)', () => {
+			// ADR-005: each portal has its own domain, /developer is no longer a root portal prefix
+			expect(extractSlugFromPath('/developer')).toBe('developer');
+		});
+
+		it('returns undefined for reserved paths', () => {
+			expect(extractSlugFromPath('/oauth/callback')).toBeUndefined();
+			expect(extractSlugFromPath('/bff/identity/api/v1/me')).toBeUndefined();
+			expect(extractSlugFromPath('/api/v1/health')).toBeUndefined();
+			expect(extractSlugFromPath('/assets/logo.png')).toBeUndefined();
+		});
+
+		it('returns admin as slug candidate for /admin/users (domain migration: no portal prefix at root)', () => {
+			// ADR-005: each portal has its own domain, so /{slug}/users pattern is expected
+			expect(extractSlugFromPath('/admin/users')).toBe('admin');
+		});
+	});
+
+	describe('edge cases', () => {
+		it('handles empty string', () => {
+			expect(extractSlugFromPath('')).toBeUndefined();
+		});
+
+		it('handles trailing slash', () => {
+			expect(extractSlugFromPath('/acme/admin/')).toBe('acme');
+		});
+
+		it('returns undefined for reserved-first segment even with portal second', () => {
+			// oauth is reserved, so /oauth/admin has no valid slug
+			expect(extractSlugFromPath('/oauth/admin')).toBeUndefined();
+		});
+
+		it('returns admin as slug candidate for /admin/settings (no portal prefix at root after domain migration)', () => {
+			// ADR-005: independent domains — no root portal prefixes
+			expect(extractSlugFromPath('/admin/settings')).toBe('admin');
+		});
+	});
+	describe('registerNonTenantSegments —— 各 portal 声明自己的业务路由', () => {
+		afterEach(() => clearNonTenantSegments());
+
+		it('未注册时行为与改动前一致（向后兼容，9 个应用无需同时改）', () => {
+			expect(extractSlugFromPath('/settings')).toBe('settings');
+			expect(extractSlugFromPath('/users/123')).toBe('users');
+		});
+
+		it('注册后业务路由不再被当成租户', () => {
+			registerNonTenantSegments(['settings', 'users', 'dashboard']);
+			expect(extractSlugFromPath('/settings')).toBeUndefined();
+			expect(extractSlugFromPath('/users/123')).toBeUndefined();
+			expect(extractSlugFromPath('/dashboard')).toBeUndefined();
+		});
+
+		it('注册后真实租户仍能识别 —— 这是本机制的关键不变量', () => {
+			registerNonTenantSegments(['settings', 'dashboard']);
+			expect(extractSlugFromPath('/acme')).toBe('acme');
+			expect(extractSlugFromPath('/acme/dashboard')).toBe('acme');
+		});
+
+		it('大小写不敏感，且容忍前后斜杠与空项', () => {
+			registerNonTenantSegments([' Settings ', '/MFA-Challenge/', '', 'sso']);
+			expect(extractSlugFromPath('/settings')).toBeUndefined();
+			expect(extractSlugFromPath('/mfa-challenge/x')).toBeUndefined();
+			expect(extractSlugFromPath('/sso')).toBeUndefined();
+		});
+
+		it('clearNonTenantSegments 可恢复（测试之间不串味）', () => {
+			registerNonTenantSegments(['settings']);
+			expect(extractSlugFromPath('/settings')).toBeUndefined();
+			clearNonTenantSegments();
+			expect(extractSlugFromPath('/settings')).toBe('settings');
+		});
+	});
+});