@autional-cn/shared 0.1.0-rc

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

@@ -0,0 +1,124 @@
+// @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);
+	});
+
+	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__/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');
+		});
+	});
+});

package/src/auth/auth-machine.ts

@@ -0,0 +1,151 @@
+/**
+ * AuthMachine — 认证流程状态机（轻量版）
+ *
+ * 统一管理认证流程的各个阶段：
+ *   checking → authenticated → bootstrap → ready
+ *           → unauthenticated → redirecting
+ *
+ * 替代 RequireAuth 中的手动 useEffect 链式调用。
+ * 不依赖外部状态机库，使用 React hook + reducer 模式。
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+'use client';
+
+import { useReducer, useEffect, useMemo } from 'react';
+import { AuthService } from './service';
+import { useBootstrap } from '../hooks/useBootstrap';
+
+// ============ Types ============
+
+export type AuthStatus =
+	| 'checking' // 初始态：正在检查 token
+	| 'authenticated' // token 有效
+	| 'bootstrap' // token 有效，正在加载权限/租户
+	| 'ready' // 全部就绪
+	| 'unauthenticated' // 无有效 token
+	| 'redirecting'; // 正在跳转到登录页
+
+export interface AuthMachineState {
+	status: AuthStatus;
+	hasToken: boolean;
+	bootstrapState: ReturnType<typeof useBootstrap>;
+}
+
+type AuthAction =
+	| { type: 'TOKEN_FOUND' }
+	| { type: 'NO_TOKEN' }
+	| { type: 'BOOTSTRAP_LOADING' }
+	| { type: 'BOOTSTRAP_READY' }
+	| { type: 'BOOTSTRAP_ERROR' }
+	| { type: 'SESSION_EXPIRED' }
+	| { type: 'REDIRECT' };
+
+// ============ Reducer ============
+
+function authReducer(state: AuthMachineState, action: AuthAction): AuthMachineState {
+	switch (action.type) {
+		case 'TOKEN_FOUND':
+			return { ...state, status: 'authenticated', hasToken: true };
+
+		case 'NO_TOKEN':
+			return { ...state, status: 'unauthenticated', hasToken: false };
+
+		case 'BOOTSTRAP_LOADING':
+			return state.status === 'authenticated' ? { ...state, status: 'bootstrap' } : state;
+
+		case 'BOOTSTRAP_READY':
+			return state.status === 'bootstrap'
+				? { ...state, status: 'ready' }
+				: state.status === 'authenticated'
+					? { ...state, status: 'ready' }
+					: state;
+
+		case 'BOOTSTRAP_ERROR':
+			// Bootstrap 失败仍应显示 UI（降级运行）
+			return state.status === 'bootstrap' ? { ...state, status: 'ready' } : state;
+
+		case 'SESSION_EXPIRED':
+			return { ...state, status: 'unauthenticated', hasToken: false };
+
+		case 'REDIRECT':
+			return { ...state, status: 'redirecting' };
+
+		default:
+			return state;
+	}
+}
+
+// ============ Initial State ============
+
+function createInitialState(): AuthMachineState {
+	const token = AuthService.getAccessToken();
+	return {
+		status: 'checking',
+		hasToken: !!token,
+		bootstrapState: 'idle' as const,
+	};
+}
+
+// ============ Hook ============
+
+/**
+ * 认证流程状态机 Hook。
+ *
+ * 整合 token 检查 + bootstrap 加载为统一状态机，
+ * 替代 RequireAuth + useBootstrap 的手动链式调用。
+ *
+ * 用法:
+ * ```tsx
+ * function App() {
+ *   const machine = useAuthMachine();
+ *   const { status, hasToken } = machine;
+ *
+ *   if (status === 'checking') return <Loading />;
+ *   if (status === 'unauthenticated' || status === 'redirecting') return <LoginPage />;
+ *   if (status === 'ready') return <Dashboard />;
+ *   return <Loading />; // authenticated / bootstrap
+ * }
+ * ```
+ */
+export function useAuthMachine(): AuthMachineState {
+	const [state, dispatch] = useReducer(authReducer, undefined, createInitialState);
+	const bootstrapState = useBootstrap();
+
+	// Phase 1: 检查 token
+	const hasToken = useMemo(() => {
+		const token = AuthService.getAccessToken();
+		return !!token && token !== 'undefined' && token !== 'null';
+	}, []);
+
+	// Phase 2: 根据 token 和 bootstrap 状态分发事件
+	useEffect(() => {
+		if (hasToken) {
+			dispatch({ type: 'TOKEN_FOUND' });
+		} else {
+			dispatch({ type: 'NO_TOKEN' });
+		}
+	}, [hasToken]);
+
+	// Phase 3: bootstrap 状态同步
+	useEffect(() => {
+		switch (bootstrapState) {
+			case 'loading':
+				dispatch({ type: 'BOOTSTRAP_LOADING' });
+				break;
+			case 'ready':
+				dispatch({ type: 'BOOTSTRAP_READY' });
+				break;
+			case 'error':
+				dispatch({ type: 'BOOTSTRAP_ERROR' });
+				break;
+		}
+	}, [bootstrapState]);
+
+	return {
+		...state,
+		hasToken,
+		bootstrapState,
+	};
+}

package/src/auth/auth-queries.ts

@@ -0,0 +1,118 @@
+/**
+ * auth-queries — React Query 认证数据查询
+ *
+ * 为 permissions / tenants / me 等服务端数据提供缓存语义。
+ * 替代 useBootstrap 手动管理请求/loading/error 状态的方式。
+ *
+ * 用法:
+ *   const { data: permissions, isLoading } = usePermissionsQuery();
+ *   const { data: tenants, isError } = useTenantsQuery();
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../api/client';
+import { extractItem } from '../utils/response';
+
+// ============ Constants ============
+
+/** 权限/租户缓存时间：5 分钟内不重复请求 */
+export const AUTH_DATA_STALE_TIME = 5 * 60 * 1000;
+
+// ============ Query Keys ============
+
+export const authQueryKeys = {
+	all: ['auth'] as const,
+	permissions: (tenantId?: string | null) =>
+		tenantId
+			? ([...authQueryKeys.all, 'permissions', tenantId] as const)
+			: ([...authQueryKeys.all, 'permissions'] as const),
+	tenants: (tenantId?: string | null) =>
+		tenantId
+			? ([...authQueryKeys.all, 'tenants', tenantId] as const)
+			: ([...authQueryKeys.all, 'tenants'] as const),
+	me: () => [...authQueryKeys.all, 'me'] as const,
+};
+
+// ============ Queries ============
+
+/**
+ * 当前用户权限列表查询。
+ * 结果自动写入 AuthService（通过 onSuccess 回调），
+ * 供 usePermission hook 和权限检查使用。
+ *
+ * @param tenantId — 可选，切换租户时自动重新请求
+ */
+export function usePermissionsQuery(tenantId?: string | null, enabled = true) {
+	return useQuery({
+		queryKey: authQueryKeys.permissions(tenantId),
+		queryFn: async () => {
+			const headers: Record<string, string> = {};
+			if (tenantId) headers['X-Tenant-ID'] = tenantId;
+			const res = await apiClient.get('/identity/api/v1/auth/me/permissions', { headers });
+			const d = extractItem(res.data);
+			return ((Array.isArray(d) ? d : (d as { permissions?: string[] } | null)?.permissions) ||
+				[]) as string[];
+		},
+		staleTime: AUTH_DATA_STALE_TIME,
+		retry: 1,
+		retryDelay: 1000,
+		// 无 token 时禁止发起请求：未登录时该查询必然 401 → apiClient 401 拦截
+		// → refreshToken() 无 refresh token → onUnauthorized() 抢跑 buildLoginUrl，
+		// 与 RequireAuth 的 OAuth PKCE 触发形成时序竞争（跨域 admin 场景偶发 302 回登录页）。
+		// 未登录的跳转决策统一交给 RequireAuth（OAuth PKCE 或 buildLoginUrl）。
+		enabled,
+	});
+}
+
+/**
+ * 当前用户租户列表查询。
+ * 结果自动写入 AuthService。
+ *
+ * @param tenantId — 可选，切换租户时自动重新请求
+ */
+export function useTenantsQuery(tenantId?: string | null, enabled = true) {
+	return useQuery({
+		queryKey: authQueryKeys.tenants(tenantId),
+		queryFn: async () => {
+			const headers: Record<string, string> = {};
+			if (tenantId) headers['X-Tenant-ID'] = tenantId;
+			const res = await apiClient.get('/identity/api/v1/auth/me/tenants', { headers });
+			const d = extractItem(res.data);
+			return ((Array.isArray(d)
+				? d
+				: (d as { tenants?: Array<{ id: string; name: string; role: string }> } | null)?.tenants) ||
+				[]) as Array<{
+				id: string;
+				name: string;
+				role: string;
+			}>;
+		},
+		staleTime: AUTH_DATA_STALE_TIME,
+		retry: 1,
+		retryDelay: 1000,
+		// 与 usePermissionsQuery 一致：无 token 时禁止发起请求，
+		// 避免 401 → onUnauthorized 抢跑 RequireAuth 的 OAuth PKCE 流程。
+		enabled,
+	});
+}
+
+/**
+ * 当前用户信息查询。
+ * 用于 OAuth 回调后获取完整用户信息。
+ */
+export function useMeQuery() {
+	return useQuery({
+		queryKey: authQueryKeys.me(),
+		queryFn: async () => {
+			const res = await apiClient.get('/identity/api/v1/auth/me');
+			return extractItem(res.data) ?? res.data;
+		},
+		staleTime: AUTH_DATA_STALE_TIME,
+		retry: 1,
+		retryDelay: 1000,
+	});
+}

package/src/auth/build-tenant-urls.ts

@@ -0,0 +1,48 @@
+/**
+ * 租户直达 URL 构造工具。
+ * 替代之前由后端返回的 loginUrl/adminUrl，前端根据自身运行时 origin 自行拼接。
+ *
+ * URL 约定（所有 Portal 统一遵循）：
+ *   登录页: {portalOrigin}/{slug}/login?redirect={portalOrigin}/{slug}/admin
+ *   管理页: {portalOrigin}/{slug}/admin
+ */
+
+export interface TenantUrls {
+	/** 租户登录页直达 URL（含 redirect 参数指向管理后台） */
+	loginUrl: string;
+	/** 租户管理后台直达 URL */
+	adminUrl: string;
+}
+
+/**
+ * 根据租户 slug 构造登录和管理后台直达 URL。
+ * 使用当前页面的 origin，适用于所有 Portal（app/user/auth 等）。
+ *
+ * @param slug - 租户 slug（即 tenant.name）
+ * @param portalOrigin - 可选，指定 portal 域名。默认用 `window.location.origin`
+ * @returns 包含 loginUrl 和 adminUrl 的对象
+ *
+ * @example
+ *   const { loginUrl, adminUrl } = buildTenantUrls('acme-corp');
+ *   // loginUrl = "https://app.iam.tianv.com/acme-corp/login?redirect=https://app.iam.tianv.com/acme-corp/admin"
+ *   // adminUrl = "https://app.iam.tianv.com/acme-corp/admin"
+ *
+ * @example 使用 auth 域名的登录入口
+ *   const { loginUrl } = buildTenantUrls('acme-corp', 'https://auth.iam.tianv.com');
+ *   // loginUrl = "https://auth.iam.tianv.com/acme-corp/login?redirect=https://app.iam.tianv.com/acme-corp/admin"
+ */
+export function buildTenantUrls(
+	slug: string,
+	portalOrigin?: string,
+	adminOrigin?: string,
+): TenantUrls {
+	const portal = portalOrigin || (typeof window !== 'undefined' ? window.location.origin : '/');
+	const admin = adminOrigin || portal;
+	const adminPath = `${admin}/${slug}/admin`;
+	const loginPath = `${portal}/${slug}/login`;
+
+	return {
+		loginUrl: `${loginPath}?redirect=${encodeURIComponent(adminPath)}`,
+		adminUrl: adminPath,
+	};
+}

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

@@ -0,0 +1,119 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { PublicAuthConfigResponse } from '../generated/types';
+import { extractSlugFromPath } from './slug-from-url';
+
+/**
+ * Resolve OAuth client ID from URL slug.
+ * Fetches public auth-config by slug and extracts oauthClientId.
+ *
+ * Returns:
+ *   - { status: 'loading' } while fetching
+ *   - { status: 'resolved', slug, clientId, config } on success
+ *   - { status: 'not-found' } if no slug in URL, env client pinned, or no oauth client configured
+ *   - { status: 'unknown-slug', slug } if by-slug is a deterministic HTTP 404 (slug 不存在)
+ */
+export type SlugResolution =
+	| { status: 'loading' }
+	| { status: 'resolved'; slug: string; clientId: string; config: PublicAuthConfigResponse }
+	| { status: 'not-found' }
+	| { status: 'unknown-slug'; slug: string };
+
+/**
+ * 公开 auth-config 拉取三态（F-W6 门户侧闸门的判别依据）：
+ * - ok：HTTP 2xx，data 为解包后的配置体；
+ * - unknown-slug：**HTTP 404** —— identity 按「租户不存在」返回
+ *   （public_handler.go GetTenantAuthConfigBySlug：GetTenantBySlug 失败/空 → ErrCodeNotFound）。
+ *   已知租户但未配 OAuth client 时返回 200（client 字段为空）⇒ 不走本态。
+ * - error：网络错误 / 非 404 非 2xx / 解析失败 —— 必须 fail-open，不得据此判死。
+ */
+type PublicAuthConfigFetch =
+	| { kind: 'ok'; data: Record<string, any> }
+	| { kind: 'unknown-slug' }
+	| { kind: 'error' };
+
+/**
+ * 拉取公开 auth-config（原始响应，snake/camel 混合未归一）。
+ * 用 raw fetch 绕过 apiClient 401 拦截器 —— 公开配置必须在 RequireAuth 跳转前解析完成。
+ */
+async function fetchPublicAuthConfig(slug: string): Promise<PublicAuthConfigFetch> {
+	try {
+		const res = await fetch(
+			`/bff/identity/api/v1/public/auth-config/by-slug/${encodeURIComponent(slug)}`,
+		);
+		if (res.status === 404) return { kind: 'unknown-slug' };
+		if (!res.ok) return { kind: 'error' };
+		const json: any = await res.json();
+		return { kind: 'ok', data: (json?.data || json || {}) as Record<string, any> };
+	} catch {
+		return { kind: 'error' };
+	}
+}
+
+/**
+ * 按 slug 实时解析 OAuth client_id（非 hook 版本）。
+ * 供登录页 from_requireauth 分支缓存未命中时回源（TASK-09 / ADR-04）。
+ * 404（未知 slug）与网络错误统一返回 null —— 调用方只关心「能不能拿到 client」。
+ */
+export async function fetchOAuthClientIdBySlug(slug: string): Promise<string | null> {
+	const fetched = await fetchPublicAuthConfig(slug);
+	if (fetched.kind !== 'ok') return null;
+	return fetched.data.oauthClientId || fetched.data.oauth_client_id || null;
+}
+
+export function useOAuthClientIdFromUrl(): SlugResolution {
+	const [resolution, setResolution] = useState<SlugResolution>({ status: 'loading' });
+
+	useEffect(() => {
+		if (typeof window === 'undefined') {
+			setResolution({ status: 'not-found' });
+			return;
+		}
+
+		const slug = extractSlugFromPath(window.location.pathname);
+		if (!slug) {
+			setResolution({ status: 'not-found' });
+			return;
+		}
+
+		// 若当前应用已通过 VITE_OAUTH_CLIENT_ID 固定了 OAuth client（如 admin-console），
+		// 无需再按 URL slug 解析——避免把 /users、/roles 等应用路径误当租户 slug 发起 404 请求。
+		const cfg = (window as any).__APP_CONFIG__;
+		if (cfg?.VITE_OAUTH_CLIENT_ID) {
+			setResolution({ status: 'not-found' });
+			return;
+		}
+
+		let cancelled = false;
+		void fetchPublicAuthConfig(slug).then((fetched) => {
+			if (cancelled) return;
+			if (fetched.kind === 'unknown-slug') {
+				setResolution({ status: 'unknown-slug', slug });
+				return;
+			}
+			if (fetched.kind !== 'ok') {
+				setResolution({ status: 'not-found' });
+				return;
+			}
+			// Raw fetch doesn't camelCase keys — handle both snake_case and camelCase
+			const clientId = fetched.data.oauthClientId || fetched.data.oauth_client_id;
+			if (clientId) {
+				setResolution({
+					status: 'resolved',
+					slug,
+					clientId,
+					config: fetched.data as PublicAuthConfigResponse,
+				});
+			} else {
+				setResolution({ status: 'not-found' });
+			}
+		});
+
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+
+	return resolution;
+}